Add 'babysitter run:halt' command for sealing divergent runs

[rogelsm]

R6 · SDK feature request — babysitter run:halt command

Title

Add babysitter run:halt for sealing divergent runs without hand-crafting journal events

Problem

When a run's SDK state diverges from operational reality (e.g. after the Promise.all collision bug), the only way to seal it cleanly is to:

1. Manually delete colliding journal entries
2. Hand-craft a RUN_COMPLETED (or RUN_FAILED) JSON event
3. Compute the right next-seq number
4. Pick a matching completionProof hash from run.json
5. Write the synthetic event to journal/000NNN.<ulid>.json
6. Run babysitter run:rebuild-state to refresh the cache

This worked but is fragile (hash/seq must be exact) and there's no audit trail of WHY we sealed.

Suggested command

babysitter run:halt <runDir> [--reason "<text>"] [--final-status completed|failed] [--json]

Behavior:

• Writes a synthetic terminal event with the right seq + ulid
• Computes/copies the completionProof from run.json
• Records the --reason in a manual_seal_reason field for audit
• Rebuilds the state cache
• Returns the run to a terminal state cleanly

Use case

Operator-driven recovery from SDK state divergence — e.g. after a Promise.all collision (see R2), after a process file refactor that obsoletes pending effects, or after a user-rejected breakpoint that should mark the run failed but auto-iterate keeps trying.

Precedent

This is analogous to git rebase --abort or kubectl delete --force — a deliberate "halt and accept current state" tool. Today the operator has to write the event file by hand.

Reference

Cookbook run 01KT797KHQ6RFVMJ55TPBQ1K26 required this on 2026-06-03 (V2 lane epic seal).

[a5c-ai]

Triage Summary

• One-line: Add an SDK CLI recovery command that safely seals divergent runs without manual journal surgery.

Critical Evaluation

• The reporter's analysis is accurate: there is no babysitter run:halt command today, and the existing recovery commands do not cover deliberate operator sealing of a divergent run.
• This is a feature request for an operator recovery tool, not the same thing as process-level ctx.halt(...) / RUN_HALTED.

Root Cause Analysis

• Affected files/functions:
  • packages/sdk/src/cli/main/program.ts: command allowlist currently has run:create, run:assign-process, run:status, run:iterate, run:events, run:rebuild-state, run:repair-journal, and run:recover-process-error, but no run:halt.
  • packages/sdk/src/cli/main/dispatchRunSession.ts: run command dispatch has no halt handler.
  • packages/sdk/src/cli/main/argPositionals.ts: run command positional parsing has no halt mapping.
  • packages/sdk/src/cli/main/runCreate.ts: existing rebuild/repair/recover handlers are the closest implementation home/pattern.
  • packages/sdk/src/storage/journal.ts: appendEvent already handles seq allocation, ULID filename, checksum, harness/session metadata, and serialized appends.
  • packages/sdk/src/runtime/replay/stateCache.ts: should be reused after sealing to refresh derived state.
  • packages/sdk/src/cli/__tests__/cliRuns.test.ts: existing run recovery/status tests are the right place for coverage.
• Actual root cause: the SDK has the low-level primitives to append terminal events and rebuild state, but no CLI facade that wraps those primitives into a safe, auditable operator command.
• Code evidence: searches found RUN_HALTED/ctx.halt support and existing run:repair-journal / run:recover-process-error, but no registered or dispatched run:halt command and no manual_seal_reason field.

Affected Components

• Packages: sdk
• Effort: effort:medium

Recommended Approach

Implement babysitter run:halt <runDir> [--reason "<text>"] [--final-status completed|failed] [--json] as a narrow operator recovery command.

Suggested shape:

• Add run:halt to the command allowlist, usage, positional parsing, and run-command dispatch.
• Implement a dedicated handler, likely near the existing run recovery handlers.
• Validate the run exists and inspect current lifecycle state before mutating it.
• Reject already terminal runs by default unless a separate explicit override is later designed.
• Use appendEvent, not manual file writes, to append exactly one terminal event:
  • RUN_FAILED when --final-status failed
  • RUN_COMPLETED when --final-status completed
• Include audit data in event payload, at minimum manual_seal_reason, sealedBy: "run:halt", and the requested final status.
• Rebuild state with rebuildStateCache after the append.
• Return JSON/human output with final status, event seq/filename, state rebuild metadata, and completion proof only for completed seals.
• Add tests for dry-run, JSON output, completed seal, failed seal, reason recording, already-terminal rejection, state rebuild, and status/events visibility.

Reproduction

babysitter run:halt <runDir> is currently unavailable because run:halt is absent from the CLI command allowlist and dispatch switch. The current workaround is hand-editing journal files and then running run:rebuild-state.

Related Issues/PRs

• sdk: typed ctx.halt() for honest early-exits (vs fake RUN_COMPLETED on halt:true return) #574 is related but distinct: process-level typed ctx.halt() / RUN_HALTED semantics.
• [runtime] Duplicate RUN_COMPLETED event emitted on post-completion state rebuild #181 is related but distinct: duplicate RUN_COMPLETED after post-completion rebuild.
• State cache silently drifts behind the journal — task:post may not update state/state.json atomically #147 is related but distinct: state cache drift after task:post.
• Journal sequence collision when --non-interactive auto-approves multiple breakpoints; spurious RUN_FAILED follows #191 is related but distinct: sequence collision / spurious RUN_FAILED after non-interactive breakpoints.

Priority: medium

• This is a meaningful operator-experience and recovery safety improvement, but not a core runtime crash or data-loss bug. Existing manual recovery and narrower repair commands partially cover adjacent cases.

Risk Analysis

• Risk Level: risk:medium
• Sealed completed runs may be mistaken for normal successful completions
  • Mitigation: prominently record manual_seal_reason, final status, and command source in the terminal event and CLI output.
• The command could hide unresolved effects or journal corruption
  • Mitigation: report pending effect counts before sealing, reject already terminal runs by default, and document when to use repair/recover versus halt.
• Semantics may conflict with process-driven ctx.halt / RUN_HALTED
  • Mitigation: keep run:halt clearly operator-driven and separate from process-level intentional halt semantics.
• Journal invariants must remain intact
  • Mitigation: reuse appendEvent and rebuildStateCache; do not write journal files by hand in the command implementation.

[a5c-ai]

Triage Summary

• One-line: Add an operator-facing babysitter run:halt command for deliberately sealing divergent runs without hand-writing journal events.

Critical Evaluation

• The reporter's analysis is accurate: current recovery paths still leave a gap for intentionally sealing a run whose SDK state no longer matches operational reality.
• This is not a duplicate of the existing recovery work. run:recover-process-error targets typed PROCESS_RUNTIME_ERROR markers, and ctx.halt(...) is process-authored. This issue asks for an operator-authored CLI seal with an audit reason.
• The suggested shape is directionally correct, but --final-status completed should be handled carefully because completed status can imply successful process execution. Prefer a halted/default manual-seal semantic unless the operator explicitly chooses completed or failed.

Root Cause Analysis

Affected CLI/runtime surfaces:

• packages/sdk/src/cli/main/program.ts - valid command list does not include run:halt.
• packages/sdk/src/cli/main/dispatchRunSession.ts and packages/sdk/src/cli/main/runCommands.ts - no command handler is wired for manual run sealing.
• packages/sdk/src/cli/main/argPositionals.ts, argFlagParsers.ts, and types.ts - no positional/flag support for run:halt <runDir>, --reason, or --final-status for this command.
• packages/sdk/src/cli/main/usage.ts and CLI reference docs - help output does not expose a manual halt/seal command.
• packages/sdk/src/cli/main/runCreate.ts - contains the closest reusable implementation patterns in run:rebuild-state, run:repair-journal, and run:recover-process-error.
• packages/sdk/src/storage/journal.ts - appendEvent already safely computes seq, ULID, checksum, timestamp, harness, and session metadata; run:halt should reuse this instead of writing journal files manually.
• packages/sdk/src/runtime/orchestrateIteration.ts - terminal replay already understands RUN_HALTED, RUN_FAILED, RUN_COMPLETED, and PROCESS_RUNTIME_ERROR.

Current evidence:

• babysitter --help | rg 'run:halt|recover-process-error|rebuild-state|halt' shows run:rebuild-state and run:recover-process-error, but no run:halt.
• rg 'run:halt|manual_seal_reason|manual seal|synthetic terminal' packages/sdk packages/babysitter docs finds no implementation or docs.

Affected Components

• Packages: sdk
• Type: enhancement
• Effort: effort:medium

Recommended Approach

1. Add run:halt to CLI command registration, positionals, usage text, parser/types, and dispatch.
2. Implement a handler that validates the run, requires a non-empty --reason, supports --dry-run/--json, appends a terminal event via appendEvent, and calls rebuildStateCache after mutation.
3. Record the audit reason in a stable field such as manual_seal_reason or an equivalent documented field, along with enough context to understand pending effects and selected final status.
4. Decide terminal semantics explicitly:
   • Recommended default: manual RUN_HALTED / halted status, because this is an operator seal rather than successful process completion.
   • If --final-status completed|failed remains part of the contract, require explicit selection and document the automation implications.
5. Add tests in packages/sdk/src/cli/__tests__/cliRuns.test.ts for dry-run JSON, missing reason, successful seal, state cache rebuild, help output, status/events visibility, and no direct journal hand-crafting.
6. Update recovery docs with a decision table:
   • ctx.halt(...): process-authored honest early exit.
   • run:recover-process-error: recover from typed process exceptions.
   • run:halt: operator-authored manual seal for divergent runs.

Reproduction

On current staging:

babysitter --help | rg 'run:halt|recover-process-error|rebuild-state|halt'
rg 'run:halt|manual_seal_reason|manual seal|synthetic terminal' packages/sdk packages/babysitter docs

The CLI exposes adjacent recovery commands but no supported babysitter run:halt <runDir> --reason ... --final-status ... path.

Related Issues/PRs

• Promise.all + ctx.task emits duplicate effects with collided journal sequence numbers #879 - Promise.all + ctx.task journal collision referenced by this issue's use case.
• sdk: distinguish process_runtime_error from effect_failed + first-class recovery CLI #573 / PR feat: process runtime error recovery #711 / PR fix(sdk): patch recovered task values by default #769 - typed PROCESS_RUNTIME_ERROR and run:recover-process-error; related but not a manual seal command.
• sdk: typed ctx.halt() for honest early-exits (vs fake RUN_COMPLETED on halt:true return) #574 / PR feat: typed ctx.halt lifecycle #701 - typed ctx.halt(...) lifecycle; related but process-authored rather than operator-authored.
• [runtime] Duplicate RUN_COMPLETED event emitted on post-completion state rebuild #181 - duplicate RUN_COMPLETED lifecycle precedent.
• Journal sequence collision when --non-interactive auto-approves multiple breakpoints; spurious RUN_FAILED follows #191 - journal sequence collision recovery precedent.

Priority: medium

The workflow impact is meaningful because this removes fragile manual journal surgery from operator recovery, but it is not a normal execution blocker and there are manual workarounds today.

Risk Analysis

• Risk Level: risk:medium
• Manual sealing can hide unresolved pending effects.
  • Mitigation: require explicit --reason, show pending-effect counts in dry-run/JSON output, and document this as an operator recovery command.
• Completed final status can mislead automation.
  • Mitigation: default to halted/manual-seal semantics or require explicit --final-status completed; document completion proof/status behavior clearly.
• Journal writes can corrupt seq/checksum/state if hand-crafted.
  • Mitigation: reuse appendEvent and rebuildStateCache; test seq/checksum/state cache behavior.
• Overlap with existing recovery commands can confuse users.
  • Mitigation: update CLI reference, SDK recovery docs, and agent recovery prompts with clear command selection guidance.

Ready for development.

[a5c-ai]

Planning PR created: #932

Plan summary:

• Add an executable Babysitter process definition and inputs for implementing babysitter run:halt.
• Start with issue/context reread, Phase 0 reuse audit, and runtime call-path tracing across CLI parsing, dispatch, journal append, state rebuild, status/events, tests, and docs.
• Include a contract phase to resolve operator seal semantics, especially RUN_HALTED default behavior versus explicit completed/failed final status.
• Use TDD: author failing CLI regression tests before implementation.
• Implement command registration, flag parsing, handler wiring, appendEvent terminal writes, rebuildStateCache, JSON/human output, and docs in a bounded verification loop.
• Gate on SDK build/tests, metadata verification, journal invariants, audit fields, completionProof semantics, dry-run/no-mutation behavior, already-terminal rejection, and scoped diff review.

Artifacts in the PR:

• .a5c/processes/issue-880-run-halt-command.mjs
• .a5c/processes/issue-880-run-halt-command.inputs.json