@naxodev/apnea 0.1.0 → 0.2.1

package/docs/adr/0005-harness-profiles.md

@@ -1,5 +1,5 @@
 # Harness abstraction: profiles with mode variants
 
-Roles do not carry freeform model strings. Global **profiles** define `cmd_interactive` (required for dispatch) and optional `cmd_oneshot` (unused by regular Apnea dispatch). Every worker role opens the interactive harness TUI in a labeled Herdr pane so humans can watch the session. Binding a role to a profile missing `cmd_interactive` hard-errors at start. Project config may only rebind role→profile names.
+Roles do not carry freeform model strings. Global **profiles** define `cmd_interactive` (required for dispatch) and optional `cmd_oneshot` (unused by Apnea dispatch). Every worker role opens the interactive harness TUI in a labeled Herdr pane so humans can watch the session. Binding a role to a profile missing `cmd_interactive` hard-errors at start. Project config may only rebind role→profile names.
 
 Each remembered role pane stores a deterministic fingerprint of the effective profile name and interactive command. Dispatch reuses the pane only when that fingerprint still matches resolved config. Legacy pane records have no fingerprint and are recreated once rather than risking an old harness.

package/docs/adr/0010-package-split.md

@@ -16,7 +16,7 @@ Both adapters bind the operation registry exported by `@naxodev/apnea`. The Pi a
 
 The core exposes only the operation registry, result formatting, command parsing, resource-root lookup, and the `ApneaHostAdapter` launch hooks. Pi supplies those hooks when it creates its registry.
 
-`@naxodev/pi-apnea` depends on `@naxodev/apnea` with `^0.1.0`. Compatible core patch releases flow through that range. An incompatible host interface change requires coordinated minor releases of both packages.
+The current incompatible `@naxodev/pi-apnea` line depends on `@naxodev/apnea` with `^0.2.0`. Compatible core patch releases flow through that range. For an incompatible line, the core manifest is pre-staged at the new minor so the workspace remains installable while Nx coordinates the adapter's minor release.
 
 ## Consequences
 

package/docs/protocol/artifacts.md

@@ -5,7 +5,7 @@
 ```text
 .apnea/                          # runtime; ignore in VCS
   config.json                    # optional project role→profile bindings only
-  state.json                     # step, phase index, rounds per (phase, gate), slug
+  state.json                     # step, phase index, rounds, required rework target, slug
   tasks/
     <dispatch-id>.md             # human/agent-readable task payload
   artifacts/
@@ -25,6 +25,10 @@
 
 Package-owned briefs live in the installed package (`briefs/`), not under `.apnea/`.
 
+Persisted artifact references in `state.json` must be repository-relative paths below `.apnea/`.
+Absolute paths and paths containing NULs, empty, `.`, `..`, or backslash components are corrupt
+state. State and artifacts must be regular UTF-8 files no larger than 1 MiB.
+
 ## Front-matter schema
 
 Required on every role-produced artifact:
@@ -61,7 +65,19 @@ For a given target path, `dispatch_role` deletes or renames away any existing fi
 
 On rework after CHANGES_REQUIRED, the **round number increases** and the path changes (`round-2/...`), so history is preserved.
 
-On crash re-dispatch (same round), the same path is cleared and reused.
+On crash redelivery, `dispatch_role` requires `redeliver=true`, matching pending ownership, and proof that any recorded pane is dead. It clears and reuses the same path without advancing the round. Manual/no-Herdr ownership requires an explicit operator request because no pane can provide liveness evidence.
+
+`state.json.pending_delivery` records whether pending ownership crossed a `manual` or `interactive` delivery boundary. Dispatch persists `interactive` before calling `runInteractivePrompt`, even though `pending_pane_id` is still null. This closes the crash window where the prompt may be accepted but the pane id cannot be saved: redelivery refuses that ambiguous state. Completion clears the mode with every other pending field, and rollback restores the prior mode.
+
+Version-1 state lacks this mode. A recorded pending pane safely migrates to `interactive`; a null pane cannot distinguish manual work from an accepted interactive prompt whose final save failed. It migrates to null and redelivery fails closed instead of guessing.
+
+Before checking pane liveness or renaming the artifact, redelivery reads the pending path and applies the complete `workflow_wait` acceptance boundary: completeness, rework legality, frontmatter schema decoding, and state transition. An accepted artifact refuses redelivery with an explicit `workflow_wait` next step and remains unchanged. Review `status: done` without a valid verdict is incomplete. Illegal or unknown rework metadata is malformed. Both proceed to normal redelivery validation.
+
+## Persisted rework ownership
+
+After a review rejects work, `state.json.required_rework` names the exact next target: `plan`, `code`, or `phase_package`. Dispatch consumes this marker only when it saves pending ownership. Refusals and launch rollback preserve it. A recovered same-round dispatch sees a cleared marker and does not advance the round again.
+
+Version-1 state without this field migrates package rework only from `phase_package_rework: true`. Planning state and coding state with `current_code_review` are ambiguous: either may be initial work after a completed prior stage. Only an explicit, matching deprecated assertion (`kind=plan` or `kind=code` with `rework=true`) converts that legacy ambiguity into one authoritative rework dispatch. Omitted assertions remain ordinary work. A matching coder dispatch already pending is not ambiguous and never re-arms code rework.
 
 ## Human markers (optional)
 

package/docs/protocol/config.md

@@ -9,6 +9,10 @@
 
 Unknown keys and unimplemented values (`isolation: "worktree"`) **hard-error** at start.
 
+`review_round_cap` is a safe integer from 1 through 20. Every `timeouts_ms` value is a safe
+integer from 1000 through 9007199254740991. For 0.2 compatibility, a numeric value outside these
+ranges falls back per field instead of rejecting the whole config. Wrong types still hard-error.
+
 ## Global profiles
 
 ```jsonc
@@ -52,8 +56,6 @@ Unknown keys and unimplemented values (`isolation: "worktree"`) **hard-error** a
     "coder": { "profile": "pi-grok" },
   },
   "review_round_cap": 3,
-  // "regular" (default) or "floating"; omit the key to keep the default
-  "pane_style": "regular",
   "timeouts_ms": {
     "planning": 1500000,
     "plan_review": 900000,
@@ -115,9 +117,12 @@ that gets killed. Passing `--budget` explicitly still works at any poll: it is a
 statement that your shell allows a longer call. An explicit budget under the floor is still
 refused.
 
-`poll_ms` must be at least 250ms. Every poll spawns two herdr subprocesses, so a smaller
-interval is a busy-spin rather than a faster wait. `budget_ms` must be finite. The sleep between
-polls is clamped to the remaining budget, so a large `poll_ms` cannot make a call outlive it.
+`poll_ms` must be a safe integer of at least 250ms. Every poll spawns two herdr subprocesses, so a
+smaller interval is a busy-spin rather than a faster wait. `budget_ms` must be a positive safe
+integer. Human flags use JavaScript numeric syntax: hexadecimal and scientific forms are accepted
+when they evaluate to an exact safe integer, while fractional values are refused. The sleep
+between polls is clamped to the remaining budget, so a large `poll_ms` cannot make a call outlive
+it.
 
 The idle nudge and the final grace are independent rungs. A role nudged early for going idle
 still receives its 180000ms grace at the deadline; it just is not prompted twice.
@@ -129,29 +134,16 @@ a slow test run can read `idle` for a minute. The nudge is one-shot, so a false
 105000ms, leaving roughly 15000ms of margin under a 120000ms shell. Raise one and you must raise
 the other.
 
-## Pane style
-
-`pane_style` controls how role dispatches appear in Herdr:
-
-- Values: `"regular"` | `"floating"`. Default is `"regular"` — **omitting the key changes nothing**.
-- Allowed in global config and overridable per project.
-- `"floating"` applies to **planner/reviewer oneshot dispatches only**. It requires herdr ≥ 0.7.4 **and** the linked `apnea` plugin (provisioned by `/apnea setup`). The popup is **session-modal**: it takes keyboard input until the worker exits, and dismissing it early kills the dispatch.
-- Floating oneshot scripts resolve `cmd_oneshot[0]` to an **absolute path** in the orchestrator environment and pass an augmented `PATH` into the popup. Bare names must be findable via the orchestrator's `PATH` (e.g. `~/.local/bin`); otherwise dispatch fails immediately instead of the popup exiting 127. Prefer absolute `cmd_oneshot` if your orchestrator process has a stripped PATH.
-- **Lifecycle (single popup):** herdr allows only one popup. Dispatch refuses while a prior floating oneshot is still live. The worker writes an exit-status file; `workflow_wait` fails closed when the popup dies without a complete artifact (instead of hanging until timeout). A second open while a popup is up surfaces `popup already open` immediately.
-- Interactive roles (orchestrator, coder) always use regular panes; the dispatch result reports `pane_style_effective: "regular (interactive role)"`.
-- Misconfiguration (old herdr, missing plugin, missing `cmd_oneshot`, unresolved oneshot binary) fails fast at dispatch with an actionable error.
-- Non-goal: per-role `pane_style` is future work. Setup never writes or flips this key — it only preserves a valid existing value on re-run.
-
 ## Role modes (fixed)
 
-By default every worker role launches the **interactive** harness TUI so you can watch it in Herdr. With `pane_style: "floating"`, planner and reviewer instead run their profile's **`cmd_oneshot`** inside the popup (those profiles therefore need `cmd_oneshot` for floating — dispatch preflight errors otherwise). Interactive roles always stay on `cmd_interactive`.
+Every worker role launches the **interactive** harness TUI in a reusable Herdr pane. Apnea dispatch always resolves `cmd_interactive`; a profile that only has `cmd_oneshot` cannot satisfy any role. `cmd_oneshot` remains part of the profile contract for manual and external workflows.
 
-| Role         | Required profile capability                                         |
-| ------------ | ------------------------------------------------------------------- |
-| orchestrator | `cmd_interactive`                                                   |
-| planner      | `cmd_interactive` (and `cmd_oneshot` when `pane_style: "floating"`) |
-| reviewer     | `cmd_interactive` (and `cmd_oneshot` when `pane_style: "floating"`) |
-| coder        | `cmd_interactive`                                                   |
+| Role         | Required profile capability |
+| ------------ | --------------------------- |
+| orchestrator | `cmd_interactive`           |
+| planner      | `cmd_interactive`           |
+| reviewer     | `cmd_interactive`           |
+| coder        | `cmd_interactive`           |
 
 Binding a role to a profile missing the required capability → **hard-error**.
 
@@ -184,3 +176,8 @@ Project entries that include `cmd`, `cmd_oneshot`, `cmd_interactive`, or `bin`
 - Optionally write project role bindings
 - Never write `cmd` into project config
 - Point at the manual gate before claiming readiness
+
+Existing global config is merged only after bounded JSON parsing. Malformed global JSON is left
+unchanged unless the human passes `--force`; forced replacement is atomic and reported. Existing
+project config is validated before setup overwrites role bindings and malformed content fails
+closed.

package/docs/protocol/manual-gate.md

@@ -17,14 +17,14 @@ Two phases, e.g. “CLI that greets by name + `--json` flag,” small enough to
 
 ## Required paths (must all pass)
 
-| #   | Path                  | Pass criteria                                                                                                                     |
-| --- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | Happy path            | Two phases committed/described; `pr-description.md` exists                                                                        |
-| 2   | Plan CHANGES_REQUIRED | At least one plan rework; new plan-review round artifact; **no** manual verdict transcription                                     |
-| 3   | Code CHANGES_REQUIRED | Live follow-up into existing coder pane; new `round-N` code-review; then APPROVED                                                 |
-| 4   | APPROVED + nits       | One review with `nits` field; commit still proceeds                                                                               |
-| 5   | Kill-and-resume       | Kill coder pane mid-phase; human reconciles per protocol (artifact present? ingest : re-dispatch same round); continue to success |
-| 6   | Mixed harness         | Planner/reviewer Claude oneshot; coder Pi interactive                                                                             |
+| #   | Path                  | Pass criteria                                                                                                                                       |
+| --- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Happy path            | Two phases committed/described; `pr-description.md` exists                                                                                          |
+| 2   | Plan CHANGES_REQUIRED | At least one plan rework; new plan-review round artifact; **no** manual verdict transcription                                                       |
+| 3   | Code CHANGES_REQUIRED | Live follow-up into existing coder pane; new `round-N` code-review; then APPROVED                                                                   |
+| 4   | APPROVED + nits       | One review with `nits` field; commit still proceeds                                                                                                 |
+| 5   | Kill-and-resume       | Kill coder pane mid-phase; human reconciles per protocol (artifact present? ingest : dispatch same kind with `redeliver=true`); continue to success |
+| 6   | Mixed harness         | Planner/reviewer Claude interactive; coder Pi interactive                                                                                           |
 
 ## Hard rules during the gate
 

package/docs/protocol/overview.md

@@ -33,7 +33,7 @@ Illegal tool calls refuse with the legal next call named in the error.
 | Tool                    | Purpose                                                                                                                   |
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `workflow_start`        | Resolve config; clean-tree check (unless allow-dirty / resume); create git branch or prepare jj; label panes; write state |
-| `dispatch_role`         | Write task file; open live harness TUI in pane; wait idle; submit short pointer; rework-only round increment              |
+| `dispatch_role`         | Write task file; claim pending ownership; consume persisted rework; open live harness TUI and submit a short pointer      |
 | `workflow_wait`         | Wait for artifact front-matter; treat agent-status as liveness only                                                       |
 | `workflow_commit_phase` | Require APPROVED + verify commands (log to `verify.log`) + VCS backend; advance phase                                     |
 | `workflow_status`       | **Read-only** snapshot                                                                                                    |
@@ -67,26 +67,39 @@ nits: | # optional; never blocks alone
 ---
 ```
 
-Pane markers are human decoration. Herdr `agent_status` is liveness (dead pane / hung oneshot without artifact → escalate).
+Pane markers are human decoration. Herdr `agent_status` is liveness (dead pane without artifact → escalate).
 
 ## Rework
 
 - **All roles:** live follow-up on the same pane when the harness is still idle; if pane missing or busy → new pane + cold TUI launch, then pointer.
 - Pointer always includes prior artifact paths for context.
-- Round increments **only** after CHANGES_REQUIRED on the same (phase, gate).
-- Crash / timeout / resume: **same round number**, clear-before-dispatch on that path.
+- `workflow_wait` records the exact required target (`plan`, `code`, or `phase_package`) after `CHANGES_REQUIRED`.
+- `dispatch_role` derives round advancement only from that persisted target and consumes it when pending ownership is saved.
+- The deprecated `rework` dispatch parameter remains an assertion through 0.2.x. It grants authority only when migrating ambiguous version-1 planning or coding state.
+- Round increments **only** when the required target is dispatched on the same (phase, gate).
+- Crash / timeout / resume: after proving the prior pane is dead, explicitly dispatch the same kind with `redeliver=true`. It validates pending kind, role, phase, and round, then clears the same artifact without advancing the round. A live or ambiguous pane refuses. Manual/no-Herdr work has no pane proof, so the operator must explicitly request redelivery.
+- Pending ownership records `pending_delivery: manual | interactive`. The prepared save writes this before crossing `runInteractivePrompt`, while the pane id may still be null. Interactive null-pane ownership refuses redelivery because prompt acceptance may have happened before the final save. Version-1 ownership without this field migrates to interactive only when a pane id is already recorded; legacy null-pane ownership remains ambiguous and refuses.
+- Before liveness checks or clear-before-dispatch, redelivery parses the pending artifact with the same acceptance rule as `workflow_wait`. `status: done` completes non-review artifacts; review artifacts also require `verdict: APPROVED | CHANGES_REQUIRED`, legal rework placement, schema-valid rework values, and a valid state transition. Accepted artifacts remain byte-identical and refuse with guidance to call `workflow_wait`. Malformed or incomplete artifacts continue to liveness validation.
 
 ## Resume
 
 1. Re-resolve panes by role label (respawn if needed).
 2. If expected artifact has valid front-matter → ingest and advance.
-3. Else report state; **offer** re-dispatch — never auto-dispatch.
+3. Else report state; **offer** explicit `redeliver=true` after liveness checks — never auto-dispatch.
 4. Skip clean-tree check on resume.
 
 ## Commit
 
 - Orchestrator only.
 - `workflow_commit_phase` runs phase package verify commands; non-zero → refuse.
+- Commits are crash-recoverable transactions. After verification, the run
+  prepares the commit and persists a durable `pending_commit` anchor in
+  `state.json` (version 2) before completing it; every commit message body
+  carries an `Apnea-Transaction: <uuid>` trailer line. A later
+  `workflow_commit_phase` call that finds a pending transaction skips gates
+  and verification, completes or recognizes the exact commit once (drift is
+  refused), then advances. Cancellation after the anchor is saved does not
+  undo the transaction.
 - jj: `jj describe` + `jj new` after APPROVED; **bookmark `apnea/<slug>` at terminus**, not start.
 - git: branch `apnea/<slug>` at start; one commit per phase.
 - No push / remote PR in v1. Terminus artifact: `pr-description.md` (planner).

package/extension/adapters/commit.ts

@@ -3,13 +3,17 @@ import { runToolResult } from "../run-tool.ts"
 import { makeAppLive } from "../services/app-live.ts"
 import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
 import { commitWorkflow, type CommitParams } from "../workflows/commit.ts"
+import { withRepositoryLock } from "../services/operation-lock.ts"
+import type { OperationHooks } from "../operation-hooks.ts"
 
 export async function workflowCommitPhase(
   params: CommitParams,
   hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+  hooks: OperationHooks = {},
 ): Promise<ToolResult> {
   return runToolResult(
-    commitWorkflow(params, process.cwd()),
+    withRepositoryLock(process.cwd(), commitWorkflow(params, process.cwd())),
     makeAppLive(hostAdapter),
+    { signal: hooks.signal, operation: "workflow_commit_phase" },
   )
 }

package/extension/adapters/dispatch.ts

@@ -3,13 +3,21 @@ import { runToolResult } from "../run-tool.ts"
 import { makeAppLive } from "../services/app-live.ts"
 import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
 import { dispatchWorkflow, type DispatchParams } from "../workflows/dispatch.ts"
+import { withRepositoryLock } from "../services/operation-lock.ts"
+import type { OperationHooks } from "../operation-hooks.ts"
 
 export async function workflowDispatch(
   params: DispatchParams,
   hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+  hooks: OperationHooks = {},
 ): Promise<ToolResult> {
   return runToolResult(
-    dispatchWorkflow(params, process.cwd()),
+    withRepositoryLock(process.cwd(), dispatchWorkflow(params, process.cwd())),
     makeAppLive(hostAdapter),
+    {
+      signal: hooks.signal,
+      operation: "dispatch_role",
+      abortDetails: { delivery: "unknown" },
+    },
   )
 }

package/extension/adapters/setup.ts

@@ -1,4 +1,5 @@
 import type { ToolResult } from "../result.ts"
+import * as os from "node:os"
 import { runToolResult } from "../run-tool.ts"
 import { makeAppLive } from "../services/app-live.ts"
 import { resolveExecutable } from "../services/herdr.ts"
@@ -8,6 +9,8 @@ import {
   type SetupDeps,
   type SetupParams,
 } from "../workflows/setup.ts"
+import { withSetupLocks } from "../services/operation-lock.ts"
+import type { OperationHooks } from "../operation-hooks.ts"
 
 /**
  * Walk PATH directly rather than spawning `which` once per binary — `which`
@@ -21,14 +24,25 @@ function onPath(bin: string): boolean {
 export async function apneaSetup(
   params: SetupParams,
   hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+  hooks: OperationHooks = {},
 ): Promise<ToolResult> {
+  const trustedHome = os.homedir()
   const prodDeps: SetupDeps = {
     onPath,
+    trustedHome: () => trustedHome,
     materializeRoleAgentDir: () =>
       hostAdapter.materializeRoleAgentDir?.() ?? null,
   }
+  const root = process.cwd()
+  const workflow = setupWorkflow(params, root, prodDeps)
   return runToolResult(
-    setupWorkflow(params, process.cwd(), prodDeps),
+    withSetupLocks(
+      trustedHome,
+      root,
+      params.project === true || params.agents_md === true,
+      workflow,
+    ),
     makeAppLive(hostAdapter),
+    { signal: hooks.signal, operation: "setup" },
   )
 }

package/extension/adapters/start.ts

@@ -4,13 +4,17 @@ import { neutralHostAdapter } from "../host-adapter.ts"
 import type { ToolResult } from "../result.ts"
 import { runToolResult } from "../run-tool.ts"
 import { startWorkflow, type StartParams } from "../workflows/start.ts"
+import { withRepositoryLock } from "../services/operation-lock.ts"
+import type { OperationHooks } from "../operation-hooks.ts"
 
 export async function workflowStart(
   params: StartParams,
   hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+  hooks: OperationHooks = {},
 ): Promise<ToolResult> {
   return runToolResult(
-    startWorkflow(params, process.cwd()),
+    withRepositoryLock(process.cwd(), startWorkflow(params, process.cwd())),
     makeAppLive(hostAdapter),
+    { signal: hooks.signal, operation: "workflow_start" },
   )
 }

package/extension/adapters/status.ts

@@ -4,11 +4,21 @@ import type { ToolResult } from "../result.ts"
 import { runToolResult } from "../run-tool.ts"
 import { resetRoundsWorkflow } from "../workflows/reset.ts"
 import { statusWorkflow } from "../workflows/status.ts"
+import { withRepositoryLock } from "../services/operation-lock.ts"
+import type { OperationHooks } from "../operation-hooks.ts"
 
 export async function workflowStatus(
   hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+  hooks: OperationHooks = {},
 ): Promise<ToolResult> {
-  return runToolResult(statusWorkflow(process.cwd()), makeAppLive(hostAdapter))
+  return runToolResult(
+    statusWorkflow(process.cwd()),
+    makeAppLive(hostAdapter),
+    {
+      signal: hooks.signal,
+      operation: "workflow_status",
+    },
+  )
 }
 
 export async function workflowResetRounds(
@@ -16,9 +26,14 @@ export async function workflowResetRounds(
     gate: string
   },
   hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+  hooks: OperationHooks = {},
 ): Promise<ToolResult> {
   return runToolResult(
-    resetRoundsWorkflow(params, process.cwd()),
+    withRepositoryLock(
+      process.cwd(),
+      resetRoundsWorkflow(params, process.cwd()),
+    ),
     makeAppLive(hostAdapter),
+    { signal: hooks.signal, operation: "workflow_reset_rounds" },
   )
 }

package/extension/adapters/wait.ts

@@ -7,6 +7,7 @@ import {
   type WaitHooks,
   type WaitParams,
 } from "../workflows/wait.ts"
+import { withRepositoryLock } from "../services/operation-lock.ts"
 
 export async function workflowWait(
   params: WaitParams,
@@ -14,7 +15,11 @@ export async function workflowWait(
   hooks: WaitHooks = {},
 ): Promise<ToolResult> {
   return runToolResult(
-    waitWorkflow(params, process.cwd(), hooks),
+    withRepositoryLock(
+      process.cwd(),
+      waitWorkflow(params, process.cwd(), hooks),
+    ),
     makeAppLive(hostAdapter),
+    // waitWorkflow owns signal cancellation so it can preserve WaitAborted.
   )
 }

package/extension/api.ts

@@ -9,7 +9,13 @@ export {
   type Operation,
   type ExecuteOperation,
 } from "./registry.ts"
-export { parseFlags, parseNumFlag } from "./cli/parse.ts"
+export type { OperationHooks } from "./operation-hooks.ts"
+export {
+  parseFlags,
+  parseNumFlag,
+  parseOperationArgs,
+  type ParsedOperationArgs,
+} from "./cli/parse.ts"
 export { DISPATCH_KINDS, type DispatchKind } from "./domain/state-machine.ts"
 export { packageRoot } from "./domain/paths.ts"
 export { formatResult, toolContent, type ToolResult } from "./result.ts"

package/extension/cli/main.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { parseFlags, parseNumFlag } from "./parse.ts"
+import { parseFlags, parseNumFlag, parseOperationArgs } from "./parse.ts"
 import {
   EXIT_ERROR,
   EXIT_USAGE,
@@ -8,7 +8,12 @@ import {
   renderJson,
 } from "./format.ts"
 import { confirmHuman, prodHumanGateDeps } from "./human-gate.ts"
-import { OPERATIONS, executeOperation, findByVerb } from "../registry.ts"
+import {
+  OPERATIONS,
+  executeOperation,
+  findByVerb,
+  type ExecuteOperation,
+} from "../registry.ts"
 import { DISPATCH_KINDS } from "../domain/state-machine.ts"
 import type { ToolResult } from "../result.ts"
 
@@ -48,14 +53,18 @@ function printUsageError(message: string, json: boolean): void {
 
 export async function main(argv: string[]): Promise<number> {
   const [verbRaw, ...rest] = argv
-  const { flags, values, rest: positional } = parseFlags(rest)
-  const json = flags.has("json")
+  const json = parseFlags(rest).flags.has("json")
 
   if (!verbRaw) {
     printUsageError("usage: apnea <command> [args] [--json]", json)
     return EXIT_USAGE
   }
   if (verbRaw === "help" || verbRaw === "--help") {
+    const parsed = parseOperationArgs("help", rest, { surface: "cli" })
+    if (!parsed.ok) {
+      printUsageError(parsed.message, json)
+      return EXIT_USAGE
+    }
     console.log(usage())
     return 0
   }
@@ -68,6 +77,13 @@ export async function main(argv: string[]): Promise<number> {
     return EXIT_USAGE
   }
 
+  const parsed = parseOperationArgs(verbRaw, rest, { surface: "cli" })
+  if (!parsed.ok) {
+    printUsageError(parsed.message, json)
+    return EXIT_USAGE
+  }
+  const { flags, values, positional } = parsed
+
   const built = buildParams(
     op.verb,
     isAction ? verbRaw : null,
@@ -97,13 +113,53 @@ export async function main(argv: string[]): Promise<number> {
     }
   }
 
-  const result = await executeOperation(op.verb, built.params)
+  const result = await executeWithSignals(
+    executeOperation,
+    op.verb,
+    built.params,
+  )
   const text = json ? renderJson(result) : renderHuman(result)
   if (result.ok) console.log(text)
   else console.error(text)
   return exitCodeFor(result)
 }
 
+export type SignalTarget = {
+  on: (signal: "SIGINT" | "SIGTERM", listener: () => void) => unknown
+  off: (signal: "SIGINT" | "SIGTERM", listener: () => void) => unknown
+}
+
+export async function executeWithSignals(
+  execute: ExecuteOperation,
+  verb: string,
+  params: Record<string, unknown>,
+  target: SignalTarget = process,
+  exit: (code: number) => void = (code) => process.exit(code),
+): Promise<ToolResult> {
+  const controller = new AbortController()
+  let interrupts = 0
+  const abort = () => controller.abort()
+  const onInterrupt = () => {
+    interrupts += 1
+    if (interrupts >= 2) {
+      // A second Ctrl+C must always terminate, even if an operation stopped
+      // observing the abort signal.
+      controller.abort()
+      exit(130)
+      return
+    }
+    abort()
+  }
+  target.on("SIGINT", onInterrupt)
+  target.on("SIGTERM", abort)
+  try {
+    return await execute(verb, params, { signal: controller.signal })
+  } finally {
+    target.off("SIGINT", onInterrupt)
+    target.off("SIGTERM", abort)
+  }
+}
+
 export type BuildParamsResult =
   | { ok: true; params: Record<string, unknown> }
   | { ok: false; message?: string }
@@ -140,12 +196,16 @@ export function buildParams(
       if (!kind || !DISPATCH_KINDS.includes(kind as never)) {
         return {
           ok: false,
-          message: `usage: apnea dispatch <${DISPATCH_KINDS.join("|")}> [--rework]`,
+          message: `usage: apnea dispatch <${DISPATCH_KINDS.join("|")}> [--rework] [--redeliver]`,
         }
       }
       return {
         ok: true,
-        params: { kind, rework: flags.has("rework") || undefined },
+        params: {
+          kind,
+          rework: flags.has("rework") || undefined,
+          redeliver: flags.has("redeliver") || undefined,
+        },
       }
     }
     case "wait": {