Repository navigation
Description
cc @PostHog/team-wizard-docs
Problem
A wizard run leaves files behind, and the agent can keep working after the user quits. Ctrl-C in the TUI skipped every cleanup until #1351. Even with #1336 and #1351 merged:
- Project leftovers.
.posthog-wizard-cache/, skills installed mid-run,.posthog-events*.jsonand orphaned.tmpfiles survive a cancel. A successful orchestrator or headless run never restores.claude/settings.json. - Temp leftovers. Every agent run creates a
posthog-wizard-claude-*directory and never removes it. - The agent outlives the cleanup. Cleanups run while the agent is still working, so it can rewrite a file right after it's removed.
- Most exits skip cleanups. Only
wizardAbortand three paths inrun-wizardcallrunCleanups(). The other 61 rawprocess.exitcalls run none. - Windows. SIGTERM never reaches Node there, and Ctrl+Break (SIGBREAK) has no handler. CI runs on Linux only, so none of this is tested on Windows or macOS.
The rules
- Anything that needs cleanup registers for cleanup. Whatever creates a transient artifact calls
registerCleanupwhen it creates it. The removal is synchronous file work. - Any kill runs the abort sequence. Ctrl-C, SIGINT, SIGTERM, SIGHUP and SIGBREAK all run the same sequence, below.
- It all gets cleaned up. Every exit runs the registered cleanups: success, an error, a crash, a screen's Exit, and an abort.
- Ctrl-C says so. The abort sequence starts by showing
Aborting run, cleaning up, in the TUI and in headless output.
One limit. SIGKILL, Windows TerminateProcess and power loss run no code, so no handler can clean up after them. The next run finishes the job instead: a startup sweep removes known leftovers before anything else reads the project. recoverOrphanedSettingsBackups already does this for settings backups.
How it works
flowchart LR
subgraph Ends["How a run ends"]
KEY["Ctrl-C key"]
SIG["SIGINT, SIGTERM, SIGHUP, SIGBREAK"]
EXIT["success, error, crash, screen Exit"]
KILL["SIGKILL, TerminateProcess, power loss"]
end
subgraph Abort["wizard-abort.ts"]
SEQ["abort sequence, wizardCancel"]
BACK["exit backstop (proposed)"]
CLEAN["runCleanups"]
end
REG["registerCleanup at creation"]
SWEEP["startup sweep (proposed)"]
KEY --> SEQ
SIG --> SEQ
SEQ -->|"message, stop agent"| CLEAN
EXIT --> BACK --> CLEAN
REG -.->|"registered removals"| CLEAN
KILL -.->|"next start"| SWEEP
Every transient artifact registers its removal. The abort sequence and the exit backstop both drain the same list. The sweep covers the kills that run no code.
The abort sequence
wizardCancel from #1351 runs it, in this order:
- Show
Aborting run, cleaning up. TUI and headless. - Stop the agent. Abort the Claude SDK query and the pi session, so nothing writes after step 3. Today the SDK only SIGTERMs its child from its own
process.on('exit'), after the cleanups have run. On Windows it only closes the child's stdin. - Run the cleanups. Synchronous file work only, so a second Ctrl-C can't interrupt it.
- Run the cancel hooks, capped at 2 s. Network work, such as settling the task stream as an error.
- Flush analytics as
cancelled, capped at 2 s. - Exit 128 plus the signal number. 130 for Ctrl-C and SIGINT, 143 for SIGTERM, 129 for SIGHUP, 149 for SIGBREAK.
os.constants.signals.SIGBREAKonly exists on Windows, so the SIGBREAK code needs a fallback elsewhere.
A second Ctrl-C skips steps 4 and 5 and exits at once. The disk is already clean by then.
Every other exit gets step 3 from one process.on('exit', runCleanups) backstop. On Node 22, exit fires on process.exit, a drained event loop, an uncaught exception and an unhandled rejection. It doesn't fire on a signal with no handler, which is why rule 2 installs one for every signal.
Cleanup ledger
Every artifact a run creates that shouldn't outlive it. Links pin main at 4acadcc2.
| # | Artifact | Created by | Cleaned today | Target |
|---|---|---|---|---|
| C1 | <installDir>/.posthog-audit-checks.json |
seedAuditLedger, agent tools via writeLedgerAtomic |
Only by the skill's rm step. #1336 removes it on settle, throw and wizardAbort |
#1336, then the backstop and the sweep |
| C2 | <file>.tmp next to any atomic ledger |
writeJsonAtomic |
Never. Orphaned only by a kill between write and rename | Sweep |
| C3 | <installDir>/.posthog-events.json |
The agent, planning events | pi harness only, src/agent/runner/harness/pi/index.ts:745. The Anthropic arm relies on the agent |
Register at run start when the program sets eventPlanFile |
| C4 | <installDir>/.posthog-events-inventory.json and .part-N.json |
events-audit subagents, names at src/shared/constants.ts:113 |
Never, on the host side | Register for events-audit runs |
| C5 | <installDir>/.posthog-wizard-cache/ |
Orchestrator queue, QUEUE_DIR_NAME |
cleanupQueue in a finally, src/agent/runner/sequence/orchestrator/orchestrator-runner.ts:601 and src/agent/runner/sequence/orchestrator/orchestrator-runner.ts:1338. Not on an abort |
Register at queue creation |
| C6 | Skills task agents install mid-run in .claude/skills/ |
Task agents | sweepRunInstalledSkills, src/agent/runner/sequence/orchestrator/orchestrator-runner.ts:1271 and src/agent/runner/sequence/orchestrator/orchestrator-runner.ts:1340. Not on an abort |
Register at run start |
| C7 | The run's skill in .claude/skills/<id>/ |
installSkillById, downloadSkill |
TUI Keep Skills screen, on the user's choice, handleRemove. Stays in CI and headless |
Register at install. Choosing Keep unregisters it |
| C8 | .claude/settings.json moved to settings.json.wizard-backup |
backupAndFixClaudeSettings |
Registered at src/shared/claude-settings.ts:292. Restored on a throw, wizardAbort, a signal, the linear outro (src/lib/programs/run-agent-legacy.ts:215) and the next start (bin.ts:92). Not on orchestrator or headless success |
Backstop runs the existing registration |
| C9 | *.wizard-backup line appended to .claude/.gitignore |
ensureBackupGitignored |
Never | Remove the line on restore when this run appended it |
| C10 | <tmp>/posthog-wizard-claude-XXXX/ |
createIsolatedAgentConfigDir, called at src/agent/agent-interface.ts:943 and src/agent/mcp-prompt-streaming.ts:389 |
Never | Register at creation |
| C11 | Claude SDK child process | The SDK's query |
SIGTERM from the SDK's own exit handler, after the cleanups. Only stdin closed on Windows |
Abort sequence step 2 |
| C12 | pi in-process agent session | pi harness, cancellation at src/agent/runner/harness/pi/cancellation.ts:4 |
Not stopped by wizardCancel |
Abort sequence step 2 |
The rest are kept on purpose and stay out of the cleanup list:
| # | Artifact | Why it stays |
|---|---|---|
| K1 | Reports (posthog-*-report.md), SDK code and edits, .env keys and their .gitignore entry |
The run's deliverable |
| K2 | Kept skills, and framework docs promoted by promoteReferenceSkill |
The user chose them, or they're the run's durable artifact |
| K3 | MCP client configs, Claude plugins, the global @posthog/cli |
Installed on purpose, removed by wizard mcp remove |
| K4 | Handoff doc and .posthog/wizard-spellbook-* |
Handoff to the user's own coding agent |
| K5 | <tmp>/wizard-handoff-*/open-agent.* |
Runs after the wizard exits and deletes itself, src/ui/tui/services/coding-agent-launcher.ts:87 |
| K6 | posthog-wizard.log, and the yara, benchmark and task-stream dumps in temp |
Diagnostics. The last three are opt-in flags |
| K7 | posthog-wizard-installation-error-*.log in the working directory |
The error message asks the user to attach it to a bug report, src/shared/utils/setup-utils.ts:280 |
Abort path ledger
Every way a run ends. The target column is what closes it.
| # | Path | Runs cleanups today | Target |
|---|---|---|---|
| S1 | Ctrl-C key in the TUI | No on main. Yes with #1351 |
Abort sequence |
| S2 | SIGINT | Only under runWizard, through its handler. #1351 covers every TUI command and headless |
Abort sequence |
| S3 | SIGTERM, never delivered on Windows | Only under runWizard. #1351 covers every TUI command and headless |
Abort sequence |
| S4 | SIGHUP, a closed terminal. Windows kills the process about 10 s later | No. #1351 adds it | Abort sequence, inside the 10 s |
| S5 | SIGBREAK, Ctrl+Break on Windows | No | Abort sequence |
| S6 | Second Ctrl-C while aborting | #1351 exits at once after the sync cleanups | Unchanged |
| S7 | Uncaught exception or unhandled rejection | No. Node prints the error and exits 1 | Backstop |
| S8 | Normal return, the event loop drains, process.exitCode set, for example src/commands/mcp/add.ts:85 |
No | Backstop |
| S9 | SIGKILL, Windows TerminateProcess, power loss |
Impossible | Startup sweep |
A1 to A26 are the wizardAbort and legacy abort callers. They all run the cleanups first, then show an outro.
A1 to A26: every wizardAbort and abort call
The raw process.exit calls are the gap rule 3 closes. run-wizard's three exits run runCleanups() on its signal, thrown-run and fatal paths. None of the others do.
E1 to E65: every process.exit call
The backstop closes every E row without editing it. A test per area (TUI screen, CLI command, runner) proves it.
Platform notes
- Windows signals. SIGTERM can be listened for but never arrives.
process.killwith SIGINT, SIGTERM or SIGKILL terminates the target outright. Closing the console sends SIGHUP, then Windows kills the process about 10 s later. Ctrl+Break sends SIGBREAK. - Windows raw mode. With processed input off, Ctrl-C arrives as a key, the same as on macOS and Linux. So fix(cli): send ctrl+c and signals through one cancel path #1351's key path should hold, but it's untested on Windows.
- Windows renames.
renameSyncover a file a watcher is reading may throw EPERM. That's an inference, not tested, and it matters for C1 and C2. - CI. Every workflow runs
ubuntu-latest. Nothing runs onmacosorwindows.
Evidence
- Node process signal events. Raw mode means Ctrl-C "is not generated" as SIGINT. SIGTERM is "not supported on Windows". SIGKILL "cannot have a listener installed". This is why the key path and the startup sweep are both required.
- Microsoft SetConsoleMode. With
ENABLE_PROCESSED_INPUToff, Ctrl-C is read as input rather than handled by the system. - signal-exit. One handler for every exit, the same design as the backstop. It only fires for signals "if the signal would cause the process to exit", and it doesn't re-enter.
- Checked locally on Node 22.
process.on('exit')fires on an uncaught exception and an unhandled rejection with code 1. It doesn't fire on SIGTERM with no handler. - Checked locally, Agent SDK. The SDK kills its child from
process.on('exit'). That runs after the wizard's cleanups, which is the ordering problem step 2 fixes. - Against. I found no source arguing against one exit routine plus a sweep. The real risks are local: a sweep deleting a file another wizard run in the same directory is using, and Windows CI flakiness with a pty.
Plan
Each slice starts with a test that fails for the named reason, then the change, then the test passes.
| PR | Scope | Depends on | Failing test first |
|---|---|---|---|
| #1336 | C1, ledger removal | None | In review |
| #1351 | S1 to S4 and S6, one cancel path | None | In review |
| 1. Exit backstop | process.on('exit', runCleanups) installed once at startup. Closes S7, S8, C8 on success, and every E row |
None | A registered cleanup runs after a screen's process.exit(0), a thrown error and a normal return. It fails today because nothing drains the list on those exits |
| 2. Abort sequence | The message, stopping the agent first (C11, C12), SIGBREAK (S5) and its exit code. registerCleanup returns a remover |
#1351 | The message shows and the agent is aborted before the first cleanup runs. It fails today because wizardCancel does neither |
| 3. Register every artifact | C3 to C7, C9 and C10 register at creation. Keep Skills unregisters C7 | 1 | Per row: after a success, a throw and an abort, the artifact is gone. It fails today for each row the "Cleaned today" column marks as not covered |
| 4. Startup sweep | Extend recoverOrphanedSettingsBackups into one sweep for C1 to C5 and stale C10 dirs. Skip it while another run holds the directory |
3 | Seeded leftovers are gone after startup, and a live run's files survive. It fails today because only settings backups are swept |
| 5. Cross-platform proof | A pty test on ubuntu-latest, macos-latest and windows-latest. Start a run, press Ctrl-C mid-run, check the message, the exit code, and that no C row remains |
2, 3 | Red on main for the message and the leftovers |
The system stays coherent after each slice. Slice 1 alone fixes the most exits. Slice 5 can land its job early as a failing, non-required check if that helps track progress.
No feature flag is proposed. The sweep only deletes wizard-named files, and a CLI release can be reverted.
Not in scope
- Uninstalling deliverables. K1 to K7 stay.
- POSIX-only shell commands on Windows.
command -v,lsofandopen || xdg-openare a separate issue. - A manifest of created paths. Deferred. Revisit if random-named leftovers show up that the sweep can't find by name.
- A supervisor process to catch SIGKILL. Rejected. CI kills the whole process tree, and passing the TTY through to Ink costs a lot.
Open questions
- Mid-run fixture. Slice 5 needs a network-free run that reaches the agent. Options are a stub agent behind a dev flag, or the recorded fixtures in
e2e-tests/fixturesif they can replay a run. That's unverified. - Sweep lock. A pid file in the project, checked with
process.kill(pid, 0), would let the sweep skip a live run. It's an artifact too, so it registers and gets swept. - Screen Cancel choices. A Cancel before any run starts exits 0 today. I'd keep it a quiet exit 0 with the backstop, and not show the abort message.
- Windows CI cancel. Whether a cancelled GitHub Actions job on Windows sends Ctrl-C or terminates outright isn't verified.
Activity