Skip to content

Run one abort sequence on every exit and clean up every run artifact on Windows, Linux and macOS #1354

Open

Description

@gewenyu99

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*.json and orphaned .tmp files 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 wizardAbort and three paths in run-wizard call runCleanups(). The other 61 raw process.exit calls 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

  1. Anything that needs cleanup registers for cleanup. Whatever creates a transient artifact calls registerCleanup when it creates it. The removal is synchronous file work.
  2. Any kill runs the abort sequence. Ctrl-C, SIGINT, SIGTERM, SIGHUP and SIGBREAK all run the same sequence, below.
  3. It all gets cleaned up. Every exit runs the registered cleanups: success, an error, a crash, a screen's Exit, and an abort.
  4. 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
Loading

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:

  1. Show Aborting run, cleaning up. TUI and headless.
  2. 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.
  3. Run the cleanups. Synchronous file work only, so a second Ctrl-C can't interrupt it.
  4. Run the cancel hooks, capped at 2 s. Network work, such as settling the task stream as an error.
  5. Flush analytics as cancelled, capped at 2 s.
  6. Exit 128 plus the signal number. 130 for Ctrl-C and SIGINT, 143 for SIGTERM, 129 for SIGHUP, 149 for SIGBREAK. os.constants.signals.SIGBREAK only 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
# Site Call
A1 src/lib/programs/error-tracking/index.ts:49 wizardAbort(…)
A2 src/lib/programs/error-tracking/index.ts:187 wizardAbort(…)
A3 src/lib/programs/posthog-integration/index.ts:267 wizardAbort(…)
A4 src/lib/programs/replay-vision/index.ts:65 wizardAbort(…)
A5 src/lib/programs/replay-vision/index.ts:176 wizardAbort(…)
A6 src/lib/programs/run-agent-legacy.ts:295 wizardAbort(…)
A7 src/lib/programs/run-agent-legacy.ts:351 wizardAbort(…)
A8 src/lib/programs/run-agent-legacy.ts:426 wizardAbort(…)
A9 src/lib/runners/run-non-interactive.ts:171 wizardAbort(…)
A10 src/lib/runners/run-non-interactive.ts:296 wizardAbort(…)
A11 src/lib/runners/run-non-interactive.ts:322 wizardAbort(…)
A12 src/lib/runners/run-non-interactive.ts:367 wizardAbort(…)
A13 src/lib/runners/run-wizard.ts:109 wizardAbort(…)
A14 src/shared/utils/oauth.ts:729 abort(…)
A15 src/shared/utils/setup-utils.ts:290 abort(…)
A16 src/shared/utils/setup-utils.ts:326 abort(…)
A17 src/shared/utils/setup-utils.ts:337 abort(…)
A18 src/shared/utils/setup-utils.ts:375 abort(…)
A19 src/shared/utils/setup-utils.ts:635 wizardAbort(…)
A20 src/shared/utils/setup-utils.ts:671 abort(…)
A21 src/shared/utils/setup-utils.ts:685 abort(…)
A22 src/shared/utils/setup-utils.ts:740 abort(…)
A23 src/shared/utils/setup-utils.ts:802 abort(…)
A24 src/ui/tui/screens/health/HealthCheckScreen.tsx:171 wizardAbort(…)
A25 src/ui/tui/screens/health/HealthCheckScreen.tsx:197 wizardAbort(…)
A26 src/ui/tui/screens/health/HealthCheckScreen.tsx:203 wizardAbort(…)

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
# Site Area Call
E1 bin.ts:49 CLI entry or command process.exit(1)
E2 src/commands/basic-integration/ci-install.ts:91 CLI entry or command process.exit(1)
E3 src/commands/basic-integration/ci-install.ts:100 CLI entry or command process.exit(1)
E4 src/commands/basic-integration/non-interactive.ts:19 CLI entry or command process.exit(1)
E5 src/commands/cli/add.ts:68 CLI entry or command process.exit(1)
E6 src/commands/cli/add.ts:86 CLI entry or command process.exit(1)
E7 src/commands/cli/add.ts:109 CLI entry or command process.exit(1)
E8 src/commands/cli/add.ts:115 CLI entry or command process.exit(0)
E9 src/commands/doctor.ts:49 CLI entry or command process.exit(1)
E10 src/commands/doctor.ts:74 CLI entry or command process.exit(0)
E11 src/commands/doctor.ts:88 CLI entry or command process.exit(1)
E12 src/commands/doctor.ts:105 CLI entry or command process.exit(1)
E13 src/commands/factories/shared.ts:33 CLI entry or command process.exit(1)
E14 src/commands/mcp/tutorial.ts:50 CLI entry or command process.exit(1)
E15 src/commands/provision.ts:75 CLI entry or command process.exit(0)
E16 src/commands/provision.ts:78 CLI entry or command process.exit(1)
E17 src/commands/skill.ts:106 CLI entry or command process.exit(1)
E18 src/commands/slack.ts:49 CLI entry or command process.exit(1)
E19 src/lib/programs/dispatch-family.ts:37 Program process.exit(code)
E20 src/lib/runners/run-non-interactive.ts:66 Runner process.exit(1)
E21 src/lib/runners/run-non-interactive.ts:77 Runner process.exit(1)
E22 src/lib/runners/run-non-interactive.ts:380 Runner process.exit(1)
E23 src/lib/runners/run-wizard.ts:169 Runner process.exit(130)
E24 src/lib/runners/run-wizard.ts:297 Runner process.exit(runFailed ? 1 : 0)
E25 src/lib/runners/run-wizard.ts:339 Runner process.exit(1)
E26 src/shared/utils/wizard-abort.ts:139 wizardAbort process.exit(exitCode)
E27 src/ui/tui/screens/AgentSkillIntroScreen.tsx:77 TUI screen process.exit(0)
E28 src/ui/tui/screens/AiObservabilityIntroScreen.tsx:74 TUI screen process.exit(0)
E29 src/ui/tui/screens/AiOptInRequiredScreen.tsx:113 TUI screen process.exit(0)
E30 src/ui/tui/screens/AuthErrorScreen.tsx:30 TUI screen process.exit(1)
E31 src/ui/tui/screens/ErrorTrackingDetectScreen.tsx:125 TUI screen process.exit(1)
E32 src/ui/tui/screens/ErrorTrackingDetectScreen.tsx:149 TUI screen process.exit(0)
E33 src/ui/tui/screens/ErrorTrackingDetectScreen.tsx:178 TUI screen process.exit(0)
E34 src/ui/tui/screens/ErrorTrackingIntroScreen.tsx:74 TUI screen process.exit(0)
E35 src/ui/tui/screens/ExitScreen.tsx:14 TUI screen process.exit(0)
E36 src/ui/tui/screens/KeepSkillsScreen.tsx:82 TUI screen process.exit(0)
E37 src/ui/tui/screens/ManagedSettingsScreen.tsx:78 TUI screen process.exit(1)
E38 src/ui/tui/screens/ManagedSettingsScreen.tsx:79 TUI screen process.exit(1)
E39 src/ui/tui/screens/MetricsIntroScreen.tsx:74 TUI screen process.exit(0)
E40 src/ui/tui/screens/MigrationIntroScreen.tsx:36 TUI screen process.exit(0)
E41 src/ui/tui/screens/PortConflictScreen.tsx:38 TUI screen process.exit(1)
E42 src/ui/tui/screens/PostHogIntegrationIntroScreen.tsx:322 TUI screen process.exit(0)
E43 src/ui/tui/screens/PostHogIntegrationIntroScreen.tsx:341 TUI screen process.exit(0)
E44 src/ui/tui/screens/RevenueIntroScreen.tsx:126 TUI screen process.exit(1)
E45 src/ui/tui/screens/RevenueIntroScreen.tsx:154 TUI screen process.exit(0)
E46 src/ui/tui/screens/SelfDrivingIntegrationDetectScreen.tsx:186 TUI screen process.exit(0)
E47 src/ui/tui/screens/SelfDrivingIntegrationDetectScreen.tsx:215 TUI screen process.exit(0)
E48 src/ui/tui/screens/SelfDrivingIntroScreen.tsx:119 TUI screen process.exit(1)
E49 src/ui/tui/screens/SelfDrivingIntroScreen.tsx:145 TUI screen process.exit(0)
E50 src/ui/tui/screens/SessionTimeoutScreen.tsx:29 TUI screen process.exit(1)
E51 src/ui/tui/screens/SettingsOverrideScreen.tsx:54 TUI screen process.exit(1)
E52 src/ui/tui/screens/SourceMapsDetectScreen.tsx:129 TUI screen process.exit(1)
E53 src/ui/tui/screens/SourceMapsDetectScreen.tsx:155 TUI screen process.exit(0)
E54 src/ui/tui/screens/SourceMapsDetectScreen.tsx:185 TUI screen process.exit(0)
E55 src/ui/tui/screens/SourceMapsIntroScreen.tsx:99 TUI screen process.exit(0)
E56 src/ui/tui/screens/WarehouseIntroScreen.tsx:97 TUI screen process.exit(0)
E57 src/ui/tui/screens/WarehouseIntroScreen.tsx:125 TUI screen process.exit(0)
E58 src/ui/tui/screens/audit/AuditIntroScreen.tsx:68 TUI screen process.exit(0)
E59 src/ui/tui/screens/doctor/DoctorIntroScreen.tsx:48 TUI screen process.exit(0)
E60 src/ui/tui/screens/health/HealthCheckScreen.tsx:40 TUI screen process.exit(0)
E61 src/ui/tui/start-tui.ts:95 TUI shell process.exit(process.exitCode ?? 0)
E62 src/wizard.ts:203 CLI entry or command process.exit(1)
E63 src/wizard.ts:247 CLI entry or command process.exit(1)
E64 src/wizard.ts:283 CLI entry or command process.exit(1)
E65 src/wizard.ts:306 CLI entry or command process.exit(1)

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.kill with 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. renameSync over 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 on macos or windows.

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_INPUT off, 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, lsof and open || xdg-open are 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/fixtures if 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

  1. self-assigned this
    on Sep 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions