@naxodev/apnea 0.2.0 → 0.2.2

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`. The Herdr adapter then requires a successful ownership save with the acquired pane identity before starting the harness or sending the task prompt. Interruption retains that ownership for recovery. Submission and acceptance-query failures preserve the task and pending Artifact because delivery may have occurred. Proven pre-delivery failures restore the prior state. Legacy or interrupted acquisition can still leave a null pane identity; 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
@@ -113,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.
@@ -169,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 interactive; 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                                                                                                    |
@@ -73,20 +73,33 @@ Pane markers are human decoration. Herdr `agent_status` is liveness (dead pane w
 
 - **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`. The Herdr adapter saves the acquired pane identity before starting the harness or sending the task prompt. Interruption and uncertain delivery preserve ownership for recovery. Interactive null-pane ownership still refuses redelivery as ambiguous. 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": {

package/extension/cli/parse.ts

@@ -11,7 +11,16 @@ export function parseFlags(tokens: string[]): {
   const flags = new Set<string>()
   const values = new Map<string, string>()
   const rest: string[] = []
+  let positionalOnly = false
   for (const t of tokens) {
+    if (positionalOnly) {
+      rest.push(t)
+      continue
+    }
+    if (t === "--") {
+      positionalOnly = true
+      continue
+    }
     if (!t.startsWith("--")) {
       rest.push(t)
       continue
@@ -24,6 +33,162 @@ export function parseFlags(tokens: string[]): {
   return { flags, values, rest }
 }
 
+type OperationArgSpec = {
+  switches: readonly string[]
+  values: readonly string[]
+  minPositionals: number
+  maxPositionals: number
+}
+
+const OPERATION_ARGS: Readonly<Record<string, OperationArgSpec>> = {
+  setup: {
+    switches: ["project", "force", "agents-md"],
+    values: [],
+    minPositionals: 0,
+    maxPositionals: 0,
+  },
+  start: {
+    switches: ["allow-dirty"],
+    values: ["slug"],
+    minPositionals: 1,
+    maxPositionals: Number.POSITIVE_INFINITY,
+  },
+  resume: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  abandon: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  help: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  status: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  wait: {
+    switches: [],
+    values: ["poll", "budget", "timeout"],
+    minPositionals: 0,
+    maxPositionals: 0,
+  },
+  dispatch: {
+    switches: ["rework", "redeliver"],
+    values: [],
+    minPositionals: 1,
+    maxPositionals: 1,
+  },
+  commit: {
+    switches: ["done"],
+    values: [],
+    minPositionals: 0,
+    maxPositionals: Number.POSITIVE_INFINITY,
+  },
+  "reset-rounds": {
+    switches: [],
+    values: [],
+    minPositionals: 1,
+    maxPositionals: 1,
+  },
+}
+
+export type ParsedOperationArgs =
+  | {
+      ok: true
+      flags: Set<string>
+      values: Map<string, string>
+      positional: string[]
+    }
+  | { ok: false; message: string }
+
+/**
+ * Parse and validate one human-facing Apnea invocation. This is the shared
+ * strict boundary for the standalone CLI and Pi's `/apnea` command.
+ */
+export function parseOperationArgs(
+  verb: string,
+  tokens: string[],
+  options: { surface?: "cli" | "slash" } = {},
+): ParsedOperationArgs {
+  const spec = OPERATION_ARGS[verb]
+  if (!spec) return { ok: false, message: `unknown command: ${verb}` }
+
+  const allowedSwitches = new Set(spec.switches)
+  if (options.surface === "cli") {
+    allowedSwitches.add("json")
+    if (verb === "reset-rounds") allowedSwitches.add("i-am-human")
+  }
+  const allowedValues = new Set(spec.values)
+  const numericValues = new Set(["poll", "budget", "timeout"])
+  const flags = new Set<string>()
+  const values = new Map<string, string>()
+  const positional: string[] = []
+  let positionalOnly = false
+
+  for (const token of tokens) {
+    if (positionalOnly) {
+      positional.push(token)
+      continue
+    }
+    if (token === "--") {
+      positionalOnly = true
+      continue
+    }
+    if (!token.startsWith("--")) {
+      positional.push(token)
+      continue
+    }
+
+    const body = token.slice(2)
+    const equals = body.indexOf("=")
+    const key = equals >= 0 ? body.slice(0, equals) : body
+    const value = equals >= 0 ? body.slice(equals + 1) : undefined
+
+    if (allowedSwitches.has(key)) {
+      if (value !== undefined)
+        return { ok: false, message: `option --${key} does not take a value` }
+      if (flags.has(key))
+        return {
+          ok: false,
+          message: `option --${key} was provided more than once`,
+        }
+      flags.add(key)
+      continue
+    }
+    if (allowedValues.has(key)) {
+      if (value === undefined)
+        return { ok: false, message: `option --${key} requires =<value>` }
+      if (numericValues.has(key)) {
+        const numeric = Number(value)
+        if (
+          value === "" ||
+          value.trim() !== value ||
+          !Number.isSafeInteger(numeric) ||
+          numeric <= 0
+        ) {
+          return {
+            ok: false,
+            message: `invalid numeric option --${key}=${value}`,
+          }
+        }
+      }
+      if (values.has(key))
+        return {
+          ok: false,
+          message: `option --${key} was provided more than once`,
+        }
+      values.set(key, value)
+      continue
+    }
+    return { ok: false, message: `unknown option --${key} for ${verb}` }
+  }
+
+  if (
+    positional.length < spec.minPositionals ||
+    positional.length > spec.maxPositionals
+  ) {
+    return { ok: false, message: `invalid positional arguments for ${verb}` }
+  }
+  if (values.has("budget") && values.has("timeout")) {
+    return {
+      ok: false,
+      message: "--budget and --timeout are aliases; provide only one",
+    }
+  }
+  return { ok: true, flags, values, positional }
+}
+
 /** Reading a `--key=value` numeric flag either yields the parsed number (or
  * `undefined` when the caller didn't pass it) or the raw token that failed
  * to parse, so the caller can name exactly what it received. */
@@ -33,16 +198,18 @@ export type NumFlag =
 /**
  * Shared by `/apnea` and the CLI so a mistyped `--budget=abc` is refused the
  * same way on both surfaces instead of silently falling back to a default —
- * a scripting agent needs a signal, not a quietly-wrong value. `--key=`
- * (empty string) counts as "not provided": a caller who writes it almost
- * certainly forgot the value, not asked for zero.
+ * a scripting agent needs a signal, not a quietly-wrong value. This exported
+ * boundary rejects empty and padded values even when called directly.
  */
 export function parseNumFlag(
   values: Map<string, string>,
   key: string,
 ): NumFlag {
   const raw = values.get(key)
-  if (raw === undefined || raw === "") return { ok: true, value: undefined }
+  if (raw === undefined) return { ok: true, value: undefined }
+  if (raw === "" || raw.trim() !== raw) return { ok: false, raw }
   const n = Number(raw)
-  return Number.isFinite(n) ? { ok: true, value: n } : { ok: false, raw }
+  return Number.isSafeInteger(n) && n > 0
+    ? { ok: true, value: n }
+    : { ok: false, raw }
 }