docs: align recovery and hook discovery contracts

Author: vitry

docs/adr/0010-use-thread-bound-direct-companion.md

@@ -44,11 +44,12 @@ an installed-plugin E2E demonstrates trusted per-call identity metadata.
 
 ## Consequences
 
-The plugin manifest must explicitly declare its native hooks. Integration tests
-must install the marketplace snapshot, discover the Skill through real Codex
-app-server, execute the installed hook, and call the installed companion through
-ordinary stdio. Tests cover absent and mismatched thread identity, two sessions
-in one workspace, pending-choice replay, shell metacharacters in tasks, and
-production-owned background launch. An opt-in authenticated `codex exec` E2E is
-the final model-driven proof; environments without authentication, credits, or a
+Codex auto-discovers native hooks at the default `hooks/hooks.json` path, so the
+optional plugin-manifest hook override is omitted. Integration tests must install
+the marketplace snapshot, prove discovery through real Codex app-server, execute
+the installed hook, and call the installed companion through ordinary stdio.
+Tests cover absent and mismatched thread identity, two sessions in one workspace,
+pending-choice replay, shell metacharacters in tasks, and production-owned
+background launch. An opt-in authenticated `codex exec` E2E is the final
+model-driven proof; environments without authentication, credits, or a
 configured model report unqualified rather than passing.

docs/superpowers/plans/2026-08-06-runtime-correctness-remediation.md

@@ -17,7 +17,7 @@
 - `scripts/lib/background-worker.mjs`: spawn the private worker with bounded protected stdio and verify/reap startup.
 - `scripts/zcode-companion.mjs`: constant `invoke`/`invoke-choice` entrypoints, ordinary output, reconciliation entry, and orchestration.
 - `hooks/user-prompt-hook.mjs`: record original prompt and authorization facts without emitting a secret.
-- `.codex-plugin/plugin.json` and `skills/*/SKILL.md`: explicitly load hooks and use only constant direct commands.
+- `hooks/hooks.json`, `.codex-plugin/plugin.json`, and `skills/*/SKILL.md`: use Codex's default hook discovery without a redundant manifest override and use only constant direct commands.
 - `scripts/lib/prompts.mjs`: separate trusted Rescue objective from untrusted Git evidence.
 - `scripts/lib/recovery.mjs`: reconcile owned nonterminal jobs from persisted ZCode turn boundaries.
 - `scripts/lib/state.mjs` and `scripts/lib/job-control.mjs`: persist recovery fields and command-specific default selection.
@@ -55,7 +55,7 @@ Run:
 node --test tests/identity.test.mjs tests/integration/skills.test.mjs tests/integration/two-session-hooks.test.mjs tests/plugin-contracts.test.mjs tests/skills-contracts.test.mjs
 ```
 
-Expected: failures show there is no active-turn lookup, public invocation still requires FD3/FD4, hooks are undeclared, and pending-choice storage is absent.
+Expected: failures show there is no active-turn lookup, public invocation still requires FD3/FD4, default hooks are not discovered, and pending-choice storage is absent.
 
 - [ ] **Step 3: Implement the exact active-turn and prompt parser boundary**
 
@@ -77,7 +77,7 @@ Make `invoke <command>` and `invoke-choice <command> <enum>` read `CODEX_THREAD_
 
 - [ ] **Step 5: Update installed plugin contracts**
 
-Declare `"hooks": "./hooks/hooks.json"`. Replace each public Skill's FD instructions with a constant command such as:
+Place registrations at the default `hooks/hooks.json` path and omit the optional manifest hook-path override. Replace each public Skill's FD instructions with a constant command such as:
 
 ```text
 node "<plugin-root>/scripts/zcode-companion.mjs" invoke rescue
@@ -154,7 +154,7 @@ Assert that accepted sends persist `inputId`, `startRevision`, and `beforeMessag
 
 - [ ] **Step 2: Write the failing real-worker-crash test**
 
-Start a production background worker against the persistent fake ZCode peer, wait until the job is `running` with a persisted boundary, kill the worker process, change the peer to completed/stopped/missing variants, then invoke status/result/start in a new companion process. Assert completed becomes succeeded with only post-boundary output, stopped becomes cancelled, and missing/ambiguous becomes terminal failed; no case remains running.
+Start a production background worker against the persistent fake ZCode peer, wait until the job is `running` with a persisted boundary, kill the worker process, change the peer to completed/stopped/missing/ambiguous variants, then invoke status/result/start in a new companion process. Assert completed becomes succeeded with only post-boundary output, stopped becomes cancelled, and missing becomes failed. Ambiguous or known-active work must retain its guard unless `session/stop` is acknowledged; a failed stop remains retryable.
 
 - [ ] **Step 3: Verify RED**
 
@@ -166,11 +166,11 @@ Expected: recovery fields are rejected or absent, selection chooses the latest a
 
 - [ ] **Step 4: Implement recovery under the cancellation lock**
 
-`reconcileOwnedJobs({ store, dataRoot, workspace, ownerSessionId, createClient })` lists only owned nonterminal records. For each record, hold `withJobCancellationLock`, restore broker ownership, use `session/list` to establish existence and `session/read` for state/messages, compare the persisted input/revision/before-message boundary, and transition exactly once. Coordinate `cancelling` with the same lock. On unsafe ambiguity, persist a bounded recovery error and terminal `failed` status.
+`reconcileOwnedJobs({ store, dataRoot, workspace, ownerSessionId, createClient })` lists only owned nonterminal records. For each record, hold `withJobCancellationLock`, prove the exact worker lease is orphaned, restore broker ownership, use `session/list` to establish existence and `session/read` for state/messages, compare the persisted input/revision/before-message boundary, and transition exactly once. Coordinate `cancelling` with the same lock. On unsafe ambiguity, attempt bounded `session/stop`; without acknowledgement, persist a bounded retry error and retain the nonterminal guard.
 
 - [ ] **Step 5: Call reconciliation at every required entry**
 
-Run it before starting new work and before status/result/cancel selection. Do not reconcile sibling-owned jobs. Ensure connection/release/close happens in `finally` and a recovery failure for one job cannot skip terminalizing that job or leak the broker client.
+Run it before starting new work and before status/result/cancel selection. Do not reconcile sibling-owned jobs. Ensure connection/release/close happens in `finally`; a recovery failure for one job must not skip siblings, release an unsafe guard, or leak the broker client.
 
 - [ ] **Step 6: Verify GREEN and commit**
 
@@ -248,7 +248,7 @@ git commit -m "feat: persist workspace model configuration"
 
 - [ ] **Step 1: Write failing release-contract tests**
 
-Assert package/check scripts include the installed bridge E2E contract, no Skill mentions FD3/FD4/caller secrets, hooks are declared, background launch is production-owned, real ZCode release E2E requires non-empty `ZCODE_REAL_E2E_MODEL`, and the complete companion invocation uses that model.
+Assert package/check scripts include the installed bridge E2E contract, no Skill mentions FD3/FD4/caller secrets, default `hooks/hooks.json` is valid and auto-discovered without a manifest override, background launch is production-owned, real ZCode release E2E requires non-empty `ZCODE_REAL_E2E_MODEL`, and the complete companion invocation uses that model.
 
 - [ ] **Step 2: Add the opt-in authenticated Codex Skill E2E**
 
@@ -280,4 +280,3 @@ Expected: all deterministic tests pass, only explicitly unqualified authenticate
 git add package.json README.md README.zh-CN.md tests
 git commit -m "test: qualify the installed Codex ZCode bridge"
 ```
-

docs/superpowers/specs/2026-08-03-zcode-plugin-codex-design.md

@@ -54,7 +54,7 @@ Companion command interface
 
 ### Plugin package
 
-The distributable contains `.codex-plugin/plugin.json`, eight skill directories, Codex hooks, prompts, schemas, a Node.js companion runtime, and local marketplace metadata. Skills are intentionally thin: they resolve the plugin root, validate user intent where interaction is necessary, invoke the companion, and faithfully present its output.
+The distributable contains `.codex-plugin/plugin.json`, eight skill directories, Codex hooks, prompts, schemas, a Node.js companion runtime, and local marketplace metadata. Codex auto-discovers the default `hooks/hooks.json`; the optional manifest hook-path override is omitted. Skills are intentionally thin: they resolve the plugin root, validate user intent where interaction is necessary, invoke the companion, and faithfully present its output.
 
 ### Companion runtime
 
@@ -299,24 +299,31 @@ TrackedJob
 
 State changes are atomic and validated. Terminal jobs never return to a running
 state. `cancelling` is nonterminal; a failed stop may transition it back to
-`running` while recording `lastCancelError`. Foreground work also receives a job
-record so interruption does not erase its outcome. Multiple read-only reviews may
-coexist in one workspace; only one writable rescue may run there by default to
-prevent concurrent edits.
+`running` while recording `lastCancelError`. Every foreground or background
+Review, Adversarial Review, Rescue, and Transfer worker acquires and durably
+claims an exact worker lease before discovery, history reads, Git inspection, or
+ZCode session work. Foreground work therefore also receives a job record so
+interruption does not erase its outcome. Multiple read-only reviews may coexist
+in one workspace; only one writable rescue may run there by default to prevent
+concurrent edits.
 
 For every accepted ZCode turn, the job persists the minimum recovery boundary:
 the `inputId`, accepted state revision, and the set of assistant message IDs
 visible before send. On the next start, status, result, or cancel invocation,
 the companion locks each owned nonterminal job, reconnects the broker, restores
 ownership, and reconciles through `session/read` and, when needed,
-`session/list`. A remotely completed turn extracts only assistant output beyond
-the persisted boundary, writes the result artifact, and transitions to
-`succeeded`. A stopped/cancelled turn becomes `cancelled`; a missing session,
-ambiguous boundary, incompatible state, or other condition that cannot be
-safely resumed becomes an explicit terminal `failed` recovery outcome. A
-persisted `cancelling` job coordinates with the cancellation lock and either
-finishes cancellation or records a terminal recovery failure. No crash may
-leave an owned job permanently `running`.
+`session/list`. A remotely completed turn with a complete boundary extracts only
+assistant output beyond that boundary, writes the result artifact, and becomes
+`succeeded` even if local status was `cancelling`. A remotely paused/stopped turn
+becomes `cancelled`; a proven missing or terminal-error session becomes
+`failed`. Known active or protocol-ambiguous sessions receive a best-effort
+`session/stop`; only an acknowledged stop permits terminalization. If stop is
+not acknowledged, recovery retains the nonterminal job and writable guard with
+a bounded error so a later cancellation can retry. A live exact lease is never
+reconciled away; an orphan claimed queued job fails safely, while a legacy
+lease-less queued record receives a conservative bounded stale grace period.
+Orphan Transfer jobs stop a known imported session before failing; without a
+known session they may fail safely because no mutating turn was sent.
 
 ## Model and Thought-Level Selection
 
@@ -411,7 +418,7 @@ The CLI discovery order is:
 
 The runtime requires ZCode CLI 0.16.1 or newer. Discovery results may be cached with their version and observation time, but every launch verifies that the resolved target still exists. A JavaScript entrypoint is launched through the current Node executable; a native executable is launched directly.
 
-The broker starts lazily for the first active session and is reused while healthy. Codex lifecycle hooks release session ownership and stop an idle broker. Cleanup must not stop sessions or jobs owned by sibling Codex sessions. After an abnormal exit, the next start, status, result, or cancel invocation reconciles owned nonterminal jobs, including jobs left in `cancelling`, from persisted turn boundaries and ZCode session state while holding the job's recovery/cancellation lock.
+The broker starts lazily for the first active session and is reused while healthy. Codex lifecycle hooks release session ownership and stop an idle broker. Cleanup must not stop sessions or jobs owned by sibling Codex sessions. After an abnormal exit, the next start, status, result, or cancel invocation reconciles owned nonterminal jobs, including jobs left in `cancelling`, from persisted worker leases, turn boundaries, and ZCode session state while holding the job's recovery/cancellation lock. Unsafe ambiguity retains the job guard until remote terminal/missing proof or acknowledged stop.
 
 ## Local Storage