@scotthuang/agent-knock-knock 0.13.18 → 0.14.0

package/docs/architecture/orchestration-refactor-history.md

@@ -0,0 +1,2987 @@
+# Historical Issue #126 orchestration refactor ledger
+
+> Immutable historical record: this document records the v0.12.11 / Issue #126
+> plan, its chronological phase reports, and later dated addenda. Tool counts,
+> action-contract versions, Watch schemas, writer protocols, module sizes, and
+> pending-work statements are true only for the snapshot named by their
+> section. See [current-architecture.md](./current-architecture.md) for the
+> authoritative current architecture, budgets, and refactor workflow.
+
+Status: architecture implementation and enforceable static gates are complete
+at the current closeout;
+[issue #126](https://github.com/scotthuang/agent-knock-knock/issues/126)
+remains open for longitudinal acceptance. The final timed
+fast/integration/full profile, dynamic subprocess runtime attestation, and one
+local OpenClaw install are separate pending final-evidence steps; this status
+does not claim they have run.
+
+The four remaining criteria require observations after the refactor:
+
+- at least 70% of normal product changes no longer modify `cli-core.ts`;
+- at least 80% of normal affected-test loops complete in 60 seconds or less;
+- five post-refactor product changes reduce median ready-to-release lead time
+  by at least 40%; and
+- repeated full-suite flaky failures remain below 1%.
+
+The frozen ten-change selector replay proves selector behavior, and a
+point-in-time suite profile proves only that measured revision. Neither can
+substitute for these four longitudinal samples.
+
+Snapshot: `main@ea592a88d7af4a709e7a7a1b989dd29e61932935` / `v0.12.11`, measured 2026-08-14
+
+Machine-readable measurements: [orchestration-baseline.json](./orchestration-baseline.json)
+
+## Purpose
+
+This document defines the boundaries, dependency direction, transaction rules,
+and compatibility contract for the incremental orchestration refactor. It is a
+design constraint for the PR sequence, not a claim that the current source tree
+already satisfies the target architecture.
+
+The objective is to make ordinary product changes local and reviewable while
+preserving AKK's safety model. `src/cli-core.ts` must become a stable command
+facade over typed services instead of remaining the owner of terminal authority,
+dispatch, lifecycle, monitor, callback, persistence, and recovery state machines.
+
+This work is a strangler refactor. Each PR extracts and characterizes existing
+behavior behind a typed boundary before callers switch to that boundary. A
+ground-up rewrite, protocol redesign, or safety simplification is out of scope.
+
+## Current baseline and concentration
+
+The production scope is the 38 checked-in `src/**/*.ts` files. Tests, generated
+`dist`, scripts, templates, and vendored dependencies are excluded.
+
+| Metric | Current baseline |
+| --- | ---: |
+| Production physical LOC | 73,792 |
+| Functions/methods with bodies | 2,449 |
+| Files over 1,000 LOC | 16 |
+| Functions over 100 LOC | 167 |
+| Functions over 200 LOC | 57 |
+| Functions over 500 LOC | 9 |
+| Approximate complexity over 20 | 150 |
+| Production import cycles | 0 |
+
+`src/cli-core.ts` is the dominant risk concentration:
+
+| Metric | `src/cli-core.ts` |
+| --- | ---: |
+| Physical LOC | 38,005 (51.5% of production source) |
+| Functions/methods with bodies | 913 |
+| Functions over 100 / 200 / 500 LOC | 116 / 43 / 8 |
+| Approximate complexity over 20 | 98 |
+| Import declarations | 37 |
+| Distinct internal modules imported | 30 |
+| `Record<string, any>` type references | 246 |
+| Functions receiving an `options` bag | 152 |
+| Distinct `options.<property>` names | 117 |
+| Durable mutation calls | 204 |
+| Lock or writer-lease acquisition calls | 91 |
+
+The largest current paths are:
+
+- `runTerminalControlSend` at `src/cli-core.ts:19838`: 1,886 lines,
+  approximate complexity 242.
+- `runTerminalBridgeMonitorWithLock` at `src/cli-core.ts:27647`: 1,444
+  lines, approximate complexity 203.
+- `terminalFirstListProjection` at `src/cli-core.ts:4931`: 1,283 lines;
+  its terminal projection callback is 1,162 lines with approximate complexity
+  302.
+- `runNativeThreadTransition` at `src/cli-core.ts:16516`: 812 lines; its
+  transaction callback is 790 lines.
+- `runSend` at `src/cli-core.ts:18077`: 721 lines.
+- `runApprove` at `src/cli-core.ts:19041`: 635 lines.
+
+The problem is concentrated orchestration, not uniform source quality. The
+import graph is currently acyclic and the public imported surface of
+`cli-core.ts` is small, so behavior can be replaced behind that facade without
+forcing consumers to migrate in one step.
+
+The test cost is similarly concentrated. At the `v0.12.11` baseline, 71
+TypeScript test files contain 71,902 physical lines. Three clean fast-tier runs
+at concurrency four completed in 8.68, 8.70, and 8.85 seconds (median 8.70
+seconds). Two clean integration-tier runs took 922.01 and 985.75 seconds; one
+was green and one exposed the pre-existing monitor-singleton supersession
+timeout. In both runs, `test/codex-no-rollout-binding-cli.test.ts` alone took
+921.81–985.56 seconds. Refactoring success therefore requires narrower affected
+selection and lighter deterministic fixtures, not fewer safety invariants.
+
+## Architectural vocabulary
+
+- **Facade**: stable CLI-facing API that parses a command, selects a handler,
+  formats output, and maps failures to the existing process contract.
+- **Observation**: immutable facts sampled from Store, terminal, process, agent,
+  and transcript sources. An observation is evidence, not durable authority by
+  itself.
+- **Authority decision**: a pure, typed allow/deny/recovery result derived from
+  an observation and a specific operation. It carries exact reasons and the
+  snapshot-bound tokens required for later revalidation.
+- **Use case**: one command-level orchestration operation such as send, approve,
+  new thread, callback delivery, or one monitor step.
+- **Transaction shell**: the only layer allowed to acquire mutation locks,
+  perform CAS writes, and execute ordered durable effects.
+- **Port**: a typed interface used by a use case for time, Store, terminal,
+  process, transcript, or callback transport access.
+- **Adapter**: an implementation of a port. Codex-, Claude-, tmux-, Herdr-,
+  filesystem-, and OpenClaw-specific behavior belongs here.
+
+## Target module ownership
+
+The path names below describe ownership. A PR may choose nearby names, but it
+must preserve the responsibility and dependency rules.
+
+| Boundary | Owns | Must not own |
+| --- | --- | --- |
+| `cli.ts` | Process argv, stdout/stderr forwarding, process exit | Business decisions, Store or terminal access |
+| CLI runtime and command registry | Per-execution context, typed parsing, command registration, output envelope | Terminal authority, lifecycle or callback state machines |
+| `cli-core.ts` | Compatibility exports `parseCliCommand` and `executeCliCommand`; temporary routing shims | New state machines, new persistence codecs, new direct lock code |
+| Terminal observation | Typed terminal/process/agent snapshots and normalization | Permission decisions or mutations |
+| Authority and action projection | Binding match/conflict, ownership, selectors, tokens, `available_actions`, handoff decisions | I/O, clocks, filesystem paths, terminal input |
+| Persistence repositories/codecs | Backward-compatible decoding, validation, atomic write primitives, revisions and CAS | Product policy or terminal input |
+| Transaction/lock kernel | Canonical lock acquisition/release and per-transaction capabilities consumed by gated mutation ports | Business decisions, durable effect ordering, command parsing, or agent-specific screen logic |
+| Dispatch service | Send/respond/approve/cancel preparation, exact input stages, acceptance receipt decisions | CLI formatting, callback transport, native-thread lifecycle policy |
+| Lifecycle service | New/resume/adopt/reconcile classifications and transition reducer | Ordinary task submission or callback delivery |
+| Callback/outbox service | Immutable callback message, attempt lease, retry and delivery settlement | Monitor polling or terminal authority projection |
+| Monitor service | Poll scheduling, pure completion/question/approval/stall decisions, reconciliation effects | Gateway transport details or duplicated dispatch policy |
+| Agent adapters | Codex/Claude process classification, composer/status/transcript profiles, native identity evidence | Store transactions or CLI response schemas |
+| Terminal-control adapters | tmux/Herdr discovery, screen capture, exact terminal mutation | Session/Turn policy or Store writes |
+| OpenClaw plugin | Tool schemas, argument mapping, command registration, Gateway integration | A second copy of CLI authority or action projection |
+
+Existing cohesive modules such as `store.ts`, `session-store.ts`,
+`terminal-control-provider.ts`, `terminal-agent-adapter.ts`, and agent-specific
+adapters are retained behind ports. Extraction may split their codecs from
+repositories, but it must not funnel their responsibilities back through the
+CLI facade.
+
+## Dependency direction
+
+The allowed direction is:
+
+```text
+CLI / OpenClaw entrypoints
+          |
+          v
+typed command facade and composition root
+          |
+          v
+dispatch | lifecycle | callback | monitor use cases
+          |
+          v
+pure authority, action, and state-transition policies
+          |
+          v
+typed domain values and port interfaces
+          ^
+          |
+filesystem, tmux, Herdr, Codex, Claude, and Gateway adapters
+```
+
+The arrows represent compile-time dependencies. Infrastructure implements ports
+defined inward; domain and use-case modules never import infrastructure or the
+CLI facade.
+
+Required rules:
+
+1. No new service may import `cli-core.ts`.
+2. Pure policy/reducer modules may not import `node:fs`, `node:child_process`,
+   environment access, wall clocks, or sleep functions.
+3. `cli-core.ts` and the OpenClaw plugin consume the same action and authority
+   result; neither reconstructs permission rules from output fields.
+4. Agent-specific composer, native-status, and transcript behavior stays behind
+   the agent-adapter boundary.
+5. Store codecs accept retained legacy formats at the boundary. Use cases
+   consume validated current domain values.
+6. The production import graph must remain acyclic. A cycle is a release
+   blocker, not an acceptable transitional state.
+7. Both `cli-core.ts` physical LOC and total `src/**/*.ts` physical LOC are
+   exact ratchets in the ownership manifest. An extraction may lower either
+   value, but cannot silently grow it back; any intentional increase requires
+   an explicit architecture review and manifest diff.
+
+## Canonical lock order
+
+All newly extracted mutation code uses this acquisition order, skipping a scope
+only when that resource is not involved:
+
+```text
+terminal dispatch lock -> Store writer lease -> conversation state lock
+```
+
+Locks are released in reverse order. An operation must never acquire a lock to
+the left while it already holds a lock to the right.
+
+- The terminal dispatch lock serializes all input and lifecycle effects for one
+  canonical terminal endpoint/incarnation.
+- The Store writer lease fences incompatible writers and serializes mutations
+  across authoritative Session, Turn, transition, and transfer records.
+- The conversation state lock protects one Turn state/event transaction and its
+  compare-before-write checks.
+
+The transaction shell creates fresh opaque terminal, Store-writer, and optional
+conversation-state scopes for every invocation. Capability-gated repositories
+validate that every required scope is authentic, active, and belongs to the
+same transaction and exact canonical terminal, Store, or state resource.
+Repositories take their raw target from the verified frozen resource handle,
+so a caller cannot pair a valid scope with a different path or terminal.
+Scopes expire before lock release begins, so a leaked scope cannot authorize a
+later write. Boolean parameters such as
+`terminalSendLockHeld`, `terminalStateLockHeld`, and `storeWriterLeaseHeld` must
+not be reproduced in new services.
+
+Read-only observation must not take mutation locks merely for convenience.
+Before a side effect, the transaction shell re-observes and revalidates exact
+endpoint, process incarnation, binding generation, owner, composer, approval,
+and snapshot/token authority under the required locks.
+
+### Current lock-order exceptions
+
+The canonical order above is a target constraint, not a statement that every
+`v0.12.11` path already conforms. Known structural exceptions at the baseline
+include:
+
+- `runTerminalControlSend` (`src/cli-core.ts:19838`) can express
+  terminal -> state -> writer through recursive `*LockHeld` flags.
+- `runTerminalControlCancel` (`src/cli-core.ts:26274`) acquires terminal, then
+  state, then enters the writer lease.
+
+Behavior-preserving extraction must inventory every reachable exception. It may
+wrap an existing order temporarily, with a named compatibility note and focused
+deadlock/crash tests, but it must not add another instance. Reordering an
+existing transaction is a separate focused change with proof at every durable
+write boundary; it must not be hidden inside a file move.
+
+## Transaction phases
+
+### Ordinary terminal dispatch
+
+The target dispatch transaction is explicit and monotonic:
+
+1. **Resolve**: select the exact Session/Turn/terminal and capture observations.
+2. **Authorize**: derive one typed authority decision and required token set.
+3. **Lock and revalidate**: acquire terminal -> writer -> state and prove the
+   same endpoint, owner, process incarnation, binding generation, request, and
+   composer boundary.
+4. **Prepare**: persist the immutable request identity and `prepared` dispatch
+   ledger before terminal input.
+5. **Inject text**: record `text_injected` only after exact text injection is
+   acknowledged.
+6. **Dispatch Enter**: send exactly one Enter and durably record
+   `enter_dispatched`. Legacy `submitted` is compatibility evidence for this
+   stage, not proof of native acceptance.
+7. **Observe acceptance**: record `agent_accepted` only with exact supported
+   native evidence. Record `not_accepted` or `uncertain` when that is what the
+   evidence proves.
+8. **Commit and monitor**: commit Session/Turn/binding effects and start or
+   reconcile the monitor from durable state.
+
+Before input, a proven rollback may end as `aborted` with `safe_to_retry=true`.
+After input may have begun, ambiguous outcomes are `uncertain` with
+`do_not_retry=true`. No extraction may collapse these two cases.
+
+### Native-thread lifecycle
+
+New, resume, and adopted external handoff use a separate transition state
+machine:
+
+```text
+prepared -> dispatching -> submitted -> verified -> committed
+                |              |           |
+                +----------> uncertain <---+
+                |
+                +----------> aborted  (only with zero-input proof)
+```
+
+`prepared` transition and lifecycle ledger records precede terminal input.
+`verified` requires exact postcondition identity. Session binding changes commit
+with revision/CAS evidence before the lifecycle ledger becomes `resolved`.
+Human-observed adoption is evidence and must never replay terminal input.
+
+### Deferred foreground transfer
+
+The Codex follow-current path retains its own durable transfer receipt:
+
+```text
+prepared -> source_reserved -> target_prepared -> dispatch_started
+          -> committed -> resolved
+```
+
+Its input substage is monotonic:
+
+```text
+none -> dispatch_started -> text_injected -> enter_dispatched -> agent_accepted
+```
+
+Only zero-input proof may reach `aborted`/`abort_resolved`. Possible input with
+an unproved outcome reaches `uncertain`; recovery may later prove and commit the
+same dispatch but may not send it again.
+
+### Callback/outbox
+
+1. Resolve one trusted, versioned, secretless callback route; a present invalid
+   route fails closed and never falls back to legacy host fields.
+2. Prepare one immutable callback envelope and deterministic delivery/idempotency
+   identity.
+3. Persist the envelope, route snapshot, pending outbox state, and attempt lease
+   before transport.
+4. Resolve the route to a concrete adapter at the composition root. The current
+   adapter preserves the OpenClaw Gateway behavior; core services do not select
+   or construct it.
+5. Persist an explicit accepted, retryable-failure, permanent-failure, or
+   uncertain attempt outcome. Only retryable failure schedules another attempt;
+   accepted checkpoints survive a later wake/observation failure.
+6. Reconciliation resumes only the same persisted route, envelope,
+   message, and attempt authority. Current CLI options or Conversation fields
+   cannot redirect an existing outbox.
+
+Callback transport state does not own or rewrite the semantic Turn phase.
+Cross-Session callback delivery remains strictly isolated.
+
+The first host-neutral slice retains the existing OpenClaw fields and Turn
+status names as a read/write compatibility projection. OpenClaw's trusted
+plugin still supplies the controller session identity; model-facing tools never
+accept a callback destination or profile. A standalone supervisor and new host
+adapters remain separate follow-on work.
+
+### Monitor step
+
+A monitor iteration becomes `observe -> decide -> execute effects -> persist`.
+The decision is pure and may yield wait, diagnostic, approval notification,
+question, completion claim, verified-dead stall/close recovery, timeout stall,
+or dispatch-ledger reconciliation. The I/O shell is responsible for locks and
+idempotent effect execution. Polling never becomes authority to replay input.
+
+## Durable write points
+
+The following records are externally observable recovery authorities. Their
+ordering and compatibility are behavior, not implementation detail.
+
+| Durable record | Current location | Authority retained during extraction |
+| --- | --- | --- |
+| Store manifest | `<store>/manifest.json` | Format/writer compatibility and writer fencing |
+| Managed Session | `<store>/sessions/<session>/state.json` | Binding, native identity, revision/CAS, lineage |
+| Turn/conversation state | `<store>/conversations/<turn>/state.json` | Semantic Turn phase, submission receipt, callback outbox |
+| Turn event log | `<store>/conversations/<turn>/events.ndjson` | Append-only audit and recovery evidence |
+| Native transition | `<store>/transitions/<transition>/state.json` | Lifecycle generation, input outcome, verification and commit |
+| Deferred foreground transfer | `<store>/deferred-foreground-transfers/<transfer>/state.json` | Follow-current reservation, input stage, commit/abort authority |
+| Terminal dispatch ledger | `<runtime-v2>/terminal-dispatch/terminal-dispatch-<key>.json` | Terminal-wide input owner and strongest transport receipt |
+| Terminal/monitor lock files | `<runtime-v2>/terminal-locks` and monitor lock paths | Live serialization only; never semantic authority by themselves |
+
+For every extracted transaction, the PR must include a durable write map that
+states:
+
+- the precondition and held lock scopes (and, once enforced by a gated port,
+  capabilities);
+- the record and expected revision/generation;
+- whether terminal input is definitely zero, possible, or accepted;
+- the crash point immediately before and after the write;
+- the single allowed reconciliation direction;
+- whether retry is safe, forbidden, or requires explicit recovery authority.
+
+The strongest durable proof is never overwritten by weaker observation. Event
+write failure after a stronger state/ledger commit is reconciled as lagging
+audit, not by downgrading the committed fact.
+
+### Transaction capability write map
+
+PR3 applies the kernel only to operations that already use the target lock
+order. Their business callbacks remain in `cli-core.ts`; the kernel owns scope
+authenticity and lifetime, not these records or effects.
+
+| Repository boundary | Required capabilities | Composition adapter retained |
+| --- | --- | --- |
+| Conversation state load / save / event append | state / writer + state / writer + state | existing Store filesystem and JSON functions |
+| Terminal dispatch-ledger load / save / resolve / reconcile | terminal / terminal + writer | existing runtime-ledger filesystem and lifecycle reconciliation functions |
+| Managed Session load / CAS save | writer | existing Session repository functions |
+
+Lifecycle recovery and reconciliation receive both the exact locked terminal
+and canonical Store path from a paired repository capability. A recorded
+`store_dir` is comparison evidence only: a mismatch fails closed before any
+transition read, quarantine, Session write, or lifecycle-ledger resolution.
+
+| Operation | Held lock scopes | Durable writes and existing order | Terminal input | Crash/retry direction |
+| --- | --- | --- | --- | --- |
+| `runReconcileBinding` | terminal -> writer | one managed Session CAS detach at the listed revision | definitely zero | before CAS, refresh and reauthorize; after CAS, detached is final and a stale token cannot retry |
+| `runTerminalConversationCancel` | terminal -> writer | none; runtime audit and JSON output remain after the adapter call | possible ordered cancel keys | before input, a fresh cancel may retry; after an unacknowledged transport attempt, adapter semantics remain authoritative |
+| `runObservedHandoffClose` | terminal -> writer -> state | Turn state `closed` -> exact dispatch-ledger resolution -> close event | definitely zero | advance only toward ledger/event reconciliation; stale handoff authority cannot start a second close |
+| `runTerminalDispatchClose` | terminal -> writer | lifecycle reconciliation keeps its existing writes; orphan recovery writes one exact dispatch-ledger generation as `resolved` | definitely zero | advance only toward resolved; refresh is required after the recorded generation changes |
+
+Each callback continues to perform the same observations, compare-before-write
+checks, output, and error text under the same lock scopes. Handoff close routes
+its fresh Turn/Session/ledger loads, state save, ledger resolution, and event
+append through the gated repositories. Dispatch close routes its
+pane-incarnation load/resolution and later reconciliation writes through them;
+binding reconciliation uses
+the managed-Session adapter for its fresh reads and CAS detach. The transaction
+module supplies no effect DSL and cannot construct Store or protocol state.
+Native-transition and raw/managed-send entry points use the same paired
+capability for lifecycle-fence recovery; unrelated dispatch and lifecycle
+writes remain in their existing shells for their later service milestones.
+
+### Initial native-thread transition policy slice
+
+PR5a introduces `native-thread-transition-policy.ts` as a 297-line pure typed
+decision module. It owns lifecycle capability eligibility, exact resume
+candidate and target-Session decisions, explicit binding-reconciliation
+eligibility, prepared transition construction, the six in-memory transition
+phase projections, and the durable failure-phase priority. `cli-core.ts`
+remains at its 37,873-line ratchet: this first slice moves one authority source
+without using formatting changes to claim a size reduction.
+
+The module has only type dependencies on managed Session/transition state and
+terminal identity. It imports no filesystem, process, terminal-control, Store,
+clock, or lock implementation. The shell still owns every public error string,
+terminal/process observation, token comparison input, clock read, and effect.
+The existing `terminal -> Store writer` lock scope is unchanged. Durable order
+also remains transition `prepared` before lifecycle ledger `prepared`, each
+transition phase CAS before its matching ledger phase, target ownership proof
+before commit, and verified Session commit before transition/ledger resolution.
+
+The focused fast table covers new/resume construction (including null versus
+existing target revision), all six phase events, failure priority, candidate
+and target eligibility, and reconciliation. Affected-test selection binds this
+module to `codex-no-rollout-binding-cli`, `human-handoff-adoption-cli`,
+`native-thread-lifecycle-cli`, and `native-thread-lifecycle-recovery-cli`.
+
+### Initial dispatch-ledger codec slice
+
+PR4b introduces `terminal-dispatch-ledger-codec.ts` as a pure document codec
+and append-only receipt reducer. It owns v1/v2 in-memory document validation,
+lifecycle-document classification, receipt history validation/candidate
+projection/strength-preserving merge, and construction of the next JSON
+document. This lowers `cli-core.ts` from 37,809 to 37,481 physical lines.
+
+The shell still chooses canonical and legacy runtime keys and paths and owns
+every filesystem observation and effect: dual-path conflict checks, symlink and
+regular-file fences, reads, promotion rename, directory fsync, exclusive temp
+creation, chmod, write/fsync, atomic rename, and cleanup. The codec receives
+already-read bytes and precomputed document identity. Native `JSON.parse`
+failures, invalid-ledger text, v1/v2 field presence and insertion order,
+historical terminal-incarnation evidence, immutable receipt fields, strongest
+receipt proof, and the one proven-safe abort retry generation remain unchanged.
+
+Focused tables characterize malformed and duplicate histories, every lifecycle
+discriminator and receipt status, immutable-field and terminal-incarnation
+conflicts, proof downgrade prevention, safe-abort chronology, and v1/v2 JSON
+ordering. The affected integration map covers dispatch authority, recovery,
+receipt fences, terminal send gates, control locks, Codex no-rollout binding,
+handoff adoption, and native lifecycle recovery.
+
+### PR4B1 dispatch receipt and application seam
+
+PR4B1 introduces `terminal-dispatch-receipt.ts` for pure terminal bridge state
+and append-only receipt construction and `terminal-dispatch-application.ts` as
+a typed application seam for already-authorized ordinary dispatch writes. It
+composes the existing ordinary-ledger codec and zero-input abort reducer behind
+five local responsibility groups: irreversible-stage synchronization, state,
+ledger, domain audit, and pre-input rollback. It imports no CLI option type,
+raw JSON or filesystem adapter, lock implementation, terminal transport,
+acceptance poller, native binding authority, or public presenter.
+
+Measured against exact head `22a379e60329d19ed884264b532106149116726d`,
+this seam lowers `cli-core.ts` from 32,146 to 31,321 physical lines. The
+492-line receipt module and 731-line application module bring total production
+from 76,076 to 76,474 lines, a reviewed 398-line typed-boundary overhead. The
+largest new function is the 164-line receipt reducer; the largest application
+method is the 118-line zero-input abort method. All new functions remain below
+the hard 500-line and approximate-complexity-50 gates.
+
+PR4B1 deliberately preserves the legacy fallback lock acquisition order:
+terminal send lock, Turn-state lock, then Store-writer lease. The composition
+root continues to own those locks and supplies raw state, ledger, event,
+rollback, clock, and crash-hook adapters. Application ports are invoked only
+inside that existing scope and do not expose lock handles or repositories. The
+stage synchronization port only copies the staged conversation and irreversible
+stage timestamp into local core catch variables before state, ledger, or
+deferred/handoff effects; it performs no I/O and cannot escape the invocation.
+
+The composition root also retains terminal input and Enter, acceptance
+observation and polling, deferred-transfer and native-binding authority,
+collateral stalling, and every CLI/OpenClaw JSON result. Only durable object
+construction and ordered application moved:
+
+- prepared remains ledger then state; either failure restores the prior ledger,
+  rolls back the provisional raw attach, and rethrows before terminal input;
+- each transport stage remains state then ledger, followed by the core-owned
+  deferred/handoff boundary, then a best-effort domain event; its irreversible
+  progress is synchronized to the core immediately before those effects;
+- native identity failure remains core quarantine/deferred marking, ledger,
+  state, event, log; generic uncertainty remains ledger, state, event before
+  core collateral stalling and presentation;
+- final acceptance remains state, best-effort final ledger, then best-effort
+  event, so a lagging ledger cannot downgrade the strongest state receipt; and
+- zero input remains deferred abort or ledger restore, raw rollback, best-effort
+  aborted state, the shared abort reducer, best-effort event, then domain log.
+
+Direct fast proofs compare `Object.keys` and newline-terminated pretty JSON
+bytes for the bridge state, prepared receipt, and final ledger. They also lock
+the write sequences above, text-stage state/ledger/boundary failures carrying a
+`TerminalInputNotStartedError` without being reclassified as zero input,
+final-ledger failure behavior, immutable receipt history, and the intentional
+authority difference where setup presentation uses the initially constructed
+aborted receipt while transport presentation uses the reducer-reported receipt.
+The owner map selects exactly recovery, receipt-fence, session-acceptance,
+terminal-send, and Codex virgin-binding integration suites. Dispatch-authority
+remains a core lock/authority boundary rather than an application owner.
+
+### PR4C canonical dispatch transaction and execution seam
+
+PR4C reuses the PR4B1 application seam as the only implementation of durable
+dispatch ordering. Measured against exact head
+`7a7987f038ac2d96f6c8dca22dcc07db4d8f1e6c`, it lowers `cli-core.ts` from
+30,640 to 29,281 physical lines (-1,359). Total production grows from 76,649
+to 77,792 lines (+1,143, 84.11 percent of the core reduction). The reviewed
+increase beyond the iteration budget is the exact-resource repair: authentic
+cross-Store state scopes, canonical terminal/writer key-value pairs, malformed
+resources, raw-attach rollback, and
+post-input Session/deferred writes now fail closed before their repository I/O.
+The largest remaining dispatch entry stage is 477 lines with approximate
+complexity 34;
+all new and split functions remain below 500 lines and complexity 50.
+
+Ordinary terminal dispatch now acquires the canonical terminal resource, then
+the exact Store writer, and derives any Turn-state scope from that same live
+transaction. The state callback is awaited and the capability expires when it
+returns. Both the dynamic send path and the static writer/state helper reject a
+wrong Store, wrong event log, mixed transaction, released scope, or forged
+resource before lock acquisition or filesystem I/O. Application repositories
+consume those exact active capabilities for every state, ledger, event, and
+rollback operation; they accept no free Store, path, terminal, or lock handle.
+
+`terminal-dispatch-execution.ts` owns preflight, transport lifecycle, native
+identity, acceptance, and authority orchestration behind five typed port
+groups: clock, native observation, acceptance, terminal proof, and Turn
+authority. Codex anchor capture/detection and Claude transcript detection are
+implemented by the core-owned adapter; the service has no filesystem, Store,
+raw-lock, public-JSON presenter, or concrete terminal-bridge dependency. Its
+direct fake-port tables lock short-circuit order, exactly one Enter stage,
+before/after-text failure classification, late acceptance and bounded pending
+results, native identity outcomes, and Turn revalidation.
+
+Raw terminal input, public CLI/OpenClaw JSON, acceptance adapter construction,
+and authority composition remain in `cli-core.ts`. At the PR4C slice, the
+82-line `terminal-dispatch-composition.ts` file was explicitly recorded as a
+temporary CLI-infrastructure type bridge owned by `terminal-dispatch-core`,
+not an application service: it still named a concrete resolved terminal type
+and the legacy `Record<string, any>` options bag, with PR7 assigned to remove
+that leakage while moving the remaining facade.
+
+The final PR7 decision keeps `TerminalDispatchTerminal` as a structural
+CLI-infrastructure carrier only and eliminates the untyped options bag through
+the six-field, unknown-valued `TerminalControlSendOptions` boundary. Business
+services still receive explicit terminal fact projections, authenticated
+routes, repositories, and typed ports; neither the structural carrier nor the
+CLI options object crosses an execution, application, capability, or deferred
+foreground service boundary.
+
+The `terminal-dispatch-application` owner retains exactly five affected
+integration witnesses: Codex no-rollout binding, dispatch recovery, receipt
+fences, session acceptance, and terminal send gates. Focused direct tables also
+prove the canonical resource identities and the preserved PR4B1 durable write
+and error-priority sequences without introducing a second state machine.
+
+## Immutable public and safety contracts
+
+The refactor must preserve all of the following unless a separate product issue
+explicitly approves a change.
+
+### Public surfaces
+
+- npm package `@scotthuang/agent-knock-knock` and executable
+  `agent-knock-knock`.
+- Imported facade functions `parseCliCommand` and `executeCliCommand`, including
+  per-execution dependency isolation.
+- Existing CLI command names, aliases, arguments, JSON field meanings, stdout,
+  and exit behavior. This includes `delegate`, `list`, `status`, `send`,
+  `new-thread`/`clear-thread`, `list-resumable-threads`/`threads`,
+  `native-inspect`/`native-status`, `resume-thread`, `reconcile-binding`,
+  `respond`, `approve`, `cancel`, `renew`, `reconcile-monitors`, `close`,
+  `transcript`, `install-openclaw`, `doctor`, `callback`, `retry-callback`, and
+  the internal `monitor` entrypoint.
+- OpenClaw plugin id `agent-knock-knock`, `/akk`, and these 14 tool names:
+  `agent_knock_knock_list`, `agent_knock_knock_list_resumable_threads`,
+  `agent_knock_knock_native_inspect`, `agent_knock_knock_new_thread`,
+  `agent_knock_knock_reconcile_binding`, `agent_knock_knock_resume_thread`,
+  `agent_knock_knock_status`, `agent_knock_knock_send`,
+  `agent_knock_knock_respond`, `agent_knock_knock_renew`,
+  `agent_knock_knock_retry_callback`, `agent_knock_knock_cancel`,
+  `agent_knock_knock_close`, and `agent_knock_knock_approve`.
+- The machine-readable `list` action contract, prefilled arguments, selectors,
+  and token semantics used by both CLI and OpenClaw.
+- tmux and exact-version Herdr support, plus current Codex and Claude adapter
+  compatibility behavior.
+
+### Persistence and recovery
+
+- Current and retained legacy Store readability/migration, including Store
+  format 1, writer protocol 5, and Session-authority protocol 3 behavior.
+- Existing Session, Turn, native-transition, deferred-transfer, dispatch-ledger,
+  callback-outbox, and event schemas and their on-disk identities.
+- Monotonic Session/transition/transfer revisions, binding-generation CAS, and
+  crash recovery.
+- Idempotent message, dispatch, completion, and callback identities.
+- Strict Store, Session, Turn, terminal-incarnation, and OpenClaw-session
+  isolation.
+
+### Terminal safety
+
+- Full native UUID and process-incarnation authority; complete Codex rollout
+  identity where required.
+- Fresh snapshot, candidate, binding, handoff, approval, and terminal tokens.
+- Endpoint, route, pane/resource, PID/process-birth, cwd/workspace, owner,
+  approval, idle, and composer fences.
+- `prepared -> text_injected -> enter_dispatched -> agent_accepted` evidence;
+  exactly one Enter after exact composer proof.
+- No blind retry after possible input, uncertain submission, uncertain approval,
+  or uncertain lifecycle transition.
+- Human input and explicit handoff remain higher priority than stale automation.
+- `list` remains read-only unless reconciliation was explicitly requested.
+- AKK never starts a coding-agent process.
+
+## Milestones and PR gates
+
+Each milestone is independently reviewable and behavior-preserving. Later work
+does not need to wait for every cleanup within an earlier module, but it may not
+bypass an unfinished safety boundary.
+
+1. **PR0 — baseline and architecture**: this document, machine-readable
+   measurements, current ownership and contract inventory.
+2. **PR1 — terminal observation and binding authority**: extract the shared pure
+   exact-binding decision first while list and mutation each retain fresh,
+   purpose-built observations and mutation revalidation.
+3. **PR2 — verified-dead agent and orphan-turn policy**: one pure decision source
+   shared by managed close, startup reconciliation, and the direct monitor; keep
+   process, transcript, Store, terminal, and callback I/O in their existing shell.
+4. **PR3 — repositories and transaction kernel**: typed codecs/ports, lock
+   capabilities, durable write maps; initially preserve legacy ordering where a
+   documented exception requires it.
+5. **PR4 — dispatch service**: send/respond/approve/cancel transaction phases and
+   acceptance evidence behind the stable facade.
+6. **PR5 — lifecycle service**: new/resume/adopt/reconcile reducer and bounded I/O
+   shell, including deferred foreground transfer recovery.
+7. **PR6 — callback/outbox and monitor/reconciliation services**: extract these
+   as separate reviewable commits behind their existing durable boundaries;
+   callback preparation/settlement and monitor polling remain distinct services.
+8. **PR7 — typed facade and secondary cleanup**: finish the command registry,
+   keep only stable facade exports in `cli-core.ts`, split remaining OpenClaw
+   adapter glue, and remove only compatibility shims proven dead by tests.
+
+Every PR records before/after metrics, responsibility movement, dependency
+edges, lock order, durable write points, and the focused tests that protect the
+moved boundary. Every production function must stay strictly below 500
+physical lines and approximate complexity 50; reaching either boundary fails
+the zero-allowlist hard gate. The normal target is under 100 lines and
+complexity under 20.
+
+The completion target remains:
+
+- `cli-core.ts` at or below 8,000 physical lines and acting only as facade/router;
+- no `Record<string, any>` or implicit `any` in new service APIs;
+- no direct lock acquisition or JSON persistence in orchestration services;
+- one authority/action decision source;
+- zero production import cycles;
+- unchanged black-box public contracts and full release gate.
+
+## Phase 1 review snapshot
+
+This branch is the first bounded delivery for issue #126, not the completion of
+the issue. It establishes enforceable architecture constraints and moves a set
+of behavior-preserving decisions behind typed seams. The dispatch-service
+experiment was explicitly retracted when review found that it owned CLI and
+OpenClaw presentation. PR4 through PR7 therefore remain open work, and this
+phase must not close issue #126.
+
+Measured against `main@ea592a8` on 2026-08-14:
+
+| Metric | Baseline | Phase 1 | Delta |
+| --- | ---: | ---: | ---: |
+| Production physical LOC | 73,792 | 75,848 | +2,056 (+2.79%) |
+| `src/cli-core.ts` physical LOC | 38,005 | 35,608 | -2,397 (-6.31%) |
+| `cli-core.ts` production share | 51.5% | 46.95% | -4.55 pp |
+| Production modules | 38 | 52 | +14 |
+| Production import edges / cycles | 95 / 0 | 130 / 0 | +35 / 0 |
+| Functions over 100 / 200 / 500 LOC | 167 / 57 / 9 | 164 / 58 / 9 | -3 / +1 / 0 |
+| Approximate complexity over 20 | 150 | 143 | -7 |
+| Test TypeScript physical LOC | 71,902 | 76,108 | +4,206 (+5.85%) |
+| Test TypeScript files | 71 | 86 | +15 |
+
+The result is a reduction in orchestration risk concentration, not a reduction
+in total code size. The exact `cli-core.ts` and production totals are ratcheted
+in `config/production-module-ownership.json`; later phases must reduce them
+rather than conceal extraction overhead. The focused test loop remains about
+ten seconds, while the real-process integration tier remains the dominant
+delivery cost.
+
+### Responsibility and dependency movement
+
+| Seam | Responsibility moved inward | I/O, locks, and durable effects deliberately retained outside | Focused proof |
+| --- | --- | --- | --- |
+| Terminal binding authority | Exact binding-match decisions and typed list/mutation observations | Fresh terminal/process sampling and mutation revalidation remain in `cli-core.ts` | authority table tests plus list, lifecycle, handoff, and send integration |
+| Verified-dead agent policy | Process-death proof validation, event replay, stall eligibility, completion tri-state | Process/transcript probes and terminal -> writer -> state orchestration remain in the shell | Codex/Claude completion-wins, fail-closed, deferred-transfer, and crash-replay tests |
+| Canonical mutation kernel | Canonical acquisition/release plus fresh resource-bound terminal, writer, and optional state capabilities for four migrated paths | Business write ordering and raw filesystem/JSON adapters remain in composition | authenticity, lifetime, wrong-resource, cross-transaction, lock-order, error-precedence, and control-lock tests |
+| Dispatch policy, zero-input abort reducer, and ledger codec | Pure preflight/abort precedence plus v1/v2 decode, construction, receipt merge, and validation | Ledger path selection, no-follow reads, atomic rename/fsync, Store locks, terminal input, and CLI formatting remain in the shell | reducer tables, codec byte/order tests, replay, receipt-fence, send-gate, and recovery tests; codec changes select the full tier |
+| Lifecycle transition policy | Candidate/target classification and transition phase reduction | Terminal observation, transition CAS, deferred transfer, input, and recovery writes remain in the shell | transition tables and lifecycle/recovery integration |
+| Callback policy, transport, and settlement | Retry decisions; Gateway process adapter; delivery progress/success/failure settlement | CLI composition owns the clock, state transaction, retry launcher, output, and callback preparation | retry matrix, exact transport call ordering, settlement write-order tests, and callback integration |
+| Monitor seams | Approval clearing/suppression/notification, activity/completion/death/timeout decisions, fingerprint facts, and launch/ownership plans | Poll I/O, supervision process management, state/event writes, callback preparation, and terminal locks remain in the shell | decision/poll/launch tables and monitor recovery/lifecycle/approval integration |
+| Terminal list renderer | Pure managed-Turn and action-contract projection from sampled facts | Store, process, ledger, Session, approval, and token observations remain in `cli-core.ts`; mutation never consumes list authority | exact v16 action order plus list/session/handoff integration |
+| Conversation trace | Bounded executor-log parsing, secret redaction, and monitor-event projection | Status routing and conversation/event loading remain in `cli-core.ts`; the module performs only the existing optional read of the selected output log | exact parser/redaction/fallback unit tests plus management CLI integration |
+| CLI runtime context | Per-execution dependency, output, clock, sleep, exit, and logging context | No business policy or persistent state moved into the runtime | nested and concurrent async-context isolation tests |
+| Install and doctor adapters | OpenClaw plugin install/configure/restart/verify ordering plus typed doctor report composition | The shared CLI command runtime retains PATH/HOME lookup, package-root resolution, output redaction, and async-local exit/output authority; terminal, lifecycle, and dispatch logic are not imported | direct argv/effect-order, exact JSON bytes/key-order, exit-code, PATH/HOME isolation, and retained CLI boundary tests |
+
+The new compile-time direction is
+`cli-core composition -> callback settlement -> callback policy`, while the
+OpenClaw child-process transport independently depends on the callback policy's
+delivery outcome type. Settlement does not import the transport adapter or CLI
+runtime.
+
+### Lock and durable-write parity
+
+No Store, Session, transition, dispatch-ledger, callback-outbox, or public
+protocol version changes in Phase 1. The extraction keeps the existing lock
+scope and durable ordering at each migrated call site. In particular:
+
+- verified-dead reconciliation continues to acquire terminal dispatch lock,
+  Store writer lease, then conversation state lock; callback execution stays
+  outside those locks;
+- callback settlement still executes progress as load -> save -> event,
+  success as load -> save -> event, and failure as load -> retry-monitor launch
+  -> save -> failure event -> monitor event;
+- terminal dispatch still records prepared state/ledger/evidence before input,
+  preserves `text_injected -> enter_dispatched -> agent_accepted`, and never
+  retries an uncertain input;
+- lifecycle transition and deferred-transfer CAS/write/crash boundaries remain
+  in their original shell; and
+- dispatch-ledger filesystem open/no-follow, temporary write, fsync, rename,
+  directory fsync, and cleanup behavior was not moved into a generic repository.
+
+The Phase 1 review gate is architecture validation, typecheck/build, focused
+policy and adapter tests, and one exact-head full test run. Packaging,
+publishing, installation, protocol upgrades, and issue closure are not part of
+this phase.
+
+### Reproducible refactor evidence guard
+
+Run the local, non-integration evidence gate with:
+
+```sh
+npm run validate:refactor-evidence
+```
+
+`config/refactor-test-evidence.json` freezes two review inputs. First, it counts
+static subprocess-startup call sites in `test/**/*.ts` for the immutable
+`v0.12.11` baseline and the current tree. The included metric is CLI-process
+plus fake-Node-process startup sites; other adapter/process calls are reported
+separately. This is a deterministic source metric, not a claim about dynamic
+process executions in one test run. The initial eight callback cases, the CLI
+UX, native-ownership, management, selector, Session-binding, deterministic
+dispatch-admission, and 20 normal callback invocations now use the imported
+command service. The multilingual composer not-accepted witness now uses the
+same imported command service while retaining the real tmux adapter and its
+exactly-one-Enter assertion. The final slice also imports redundant callback,
+installer, verifier/guard, Claude recovery, and nested approval wrappers. The
+product-test value is now 19 of 48 baseline sites, a 60.42% reduction, and its
+`final_threshold.required` flag is `true`. Measurement self-tests are reported
+separately (baseline zero; current ten included fake-Node probes) under one
+fixed diagnostic path applied to both revisions; they cannot dilute the
+product migration ratio.
+
+Second, the manifest freezes the exact changed paths and subjects of ten
+pre-`v0.12.11` product/test commits and replays them through the current
+affected-test selector. Eight changes now select owned integration witnesses;
+the two commits that changed exact `src/store.ts` authority remain full. The
+measured fallback is therefore 2 of 10 (20%), meeting the completion target.
+Every normal production domain is capped at five integration witnesses, while
+unknown paths, `src/store.ts`, `src/protocol.ts`, and shared kernels remain
+full. Known test helpers resolve through an explicit transitive consumer map.
+Tier-manifest additions and synchronized package-version bumps narrow only from
+Git parent/current blob proof; deletion, movement, reordering, dependency
+changes, or an unproved caller object fail closed. The validator fails if Git
+history, a frozen path list, the measured count, or a replay result drifts, and
+`affected_selector_replay.final_threshold.required` is now `true`.
+
+`config/public-contract-witnesses.json` is the machine-readable compatibility
+inventory. It pins the package executable and facade, CLI commands/JSON
+witnesses, list action contract v16, all 14 OpenClaw tools, Store format 1 and
+writer protocols 1 through 5, and eleven mappings from old executable tests to
+focused service invariants and retained boundary witnesses. Every authority and
+witness path must exist, each witness must remain in its declared test tier and
+contain its named assertion, and unknown or missing manifest fields fail
+closed.
+
+`npm run validate:architecture` invokes the same evidence guard after the
+ownership/import/LOC checks. Intentional contract or evidence changes therefore
+require a reviewed manifest diff; changing only a number to conceal a failed
+measurement does not pass because the validator reproduces it from source and
+Git history.
+
+### Codex no-rollout process-contract consolidation
+
+The canonical integration witness
+`test/codex-no-rollout-binding-cli.test.ts` declares 102 named
+tests with their original assertions. `config/test-file-shards.json` assigns
+every declaration to exactly one of eight worker entrypoints. Test-tier
+selection, production ownership, affected-test selection, public-contract
+evidence, and dynamic subprocess evidence continue to name the canonical path;
+the tier runner expands that one path to every compiled shard and fails closed
+for a missing, duplicate, unused, out-of-range, or uncompiled shard. A targeted
+canonical selection also rejects a shard query that does not match its actual
+worker entry, so it can never execute only a subset while claiming the whole
+witness.
+
+Repeated executable invocations now use the same imported parser/command
+boundary and fixture-scoped virtual clock as the surrounding invariant tests.
+For injected exit checkpoints, the fixture freezes the exact durable filesystem
+image at `cliExit`, rewrites active lock ownership to the simulated dead CLI
+PID, and restores files without changing surviving rollout inodes before the
+next recovery command. Ordinary exception compensation after the injected exit
+therefore cannot forge the crash state, while recovery still proves lock
+reclamation, descriptor identity, exact CAS state, and zero replay.
+
+| Former repeated executable role | Same retained invariant | Authoritative real-process witness |
+| --- | --- | --- |
+| Virgin attach, terminal send, and status variants | Exact parser/command routing, terminal text plus one Enter, acceptance binding, and no Store mutation | `doctor exits non-zero when required package files are missing` in `cli-ux.test.ts` retains argv/exit; `raw background send durably prepares its terminal submission before tmux accepts it` in the composer-replay shard retains real terminal-adapter input |
+| Deferred preparation, commit, acceptance-backfill, and recovery crash variants | Exact durable image at every named `cliExit(86)` checkpoint; subsequent recovery retains Session/Turn/ledger/transfer state and never replays input | `zero-input deferred source Session reservation before its transfer receipt recovery aborts safely before one refreshed retry` retains the real Store crash and exit-86 boundary used by dynamic evidence |
+| Startup candidate-monitor reconciliation | Exact pending Turn is accepted and completed once, its transfer and dispatch ledger resolve, and no callback state appears | `startup reconciliation relaunches one pending candidate monitor without replay` retains detached monitor PID launch, liveness, and process exit |
+
+The no-rollout suite retains two explicit `runCliSubprocess` call sites for its
+unique Store-crash and detached-monitor process boundaries. Consolidation does not
+shorten a production timeout, raise test concurrency, remove a test or
+assertion, or replace the separate OpenClaw callback process boundaries.
+
+## Callback/outbox application service
+
+The callback milestone now has one typed application boundary for generic
+callback preparation and execution, retry classification and monitoring,
+startup reconciliation, terminal-completion outbox preparation, and approval
+notification outbox preparation. The service composes the existing pure retry
+policy, OpenClaw delivery contract, and settlement service; it does not import
+`cli-core.ts`, filesystem or process adapters, CLI presentation, or raw locks.
+The OpenClaw child-process transport implements the policy-owned delivery
+contract rather than exporting an infrastructure type back into the service.
+
+Measured against its exact pre-extraction head, this vertical moves 1,133
+physical lines out of `cli-core.ts` while adding 387 physical production lines
+overall. The reviewed overhead is the explicit typed port/result surface and
+the direct service boundary; it is not hidden by unrelated cleanup or compact
+formatting. The hard maxima are 396 physical lines and approximate complexity
+32, below the 500/50 gates. The preparation span (277/32, including its nested
+persistence phase), persistence phase (145/30), reconciliation callback
+(129/20), and terminal-completion preparation (131/8) remain reviewed
+exceptions to the default 100/20 target so their durable short-circuit and write
+order stays visible. The production import graph remains acyclic.
+
+The composition root still owns terminal and Store-writer locks, state-lock
+implementation, Store/path resolution, JSON/event persistence adapters, retry
+process launch, clock/process observation, Gateway transport construction, and
+all public JSON. Terminal completion preserves state-lock scope across claim,
+detected/message/outbox writes, and the record-only crash checkpoint, releases
+that lock before settling the terminal dispatch ledger, and never replays
+terminal input. Approval persistence still records the stable message id and
+timestamp before invoking the service; the service either prepares that exact
+message id or returns the same message without an outbox when no Gateway route
+exists. Delivery settlement retains progress `load -> save -> event`, success
+`load -> save -> event`, and failure `load -> retry-monitor -> save -> events`
+ordering through the existing settlement service.
+
+Direct fast proofs cover fresh/duplicate/non-retryable outbox preparation,
+completion claim success/conflict and lock release, stable approval identity,
+and the no-Gateway branch. Existing policy, settlement, transport, callback,
+Claude, approval, monitor lifecycle, monitor recovery, and OpenClaw contract
+witnesses remain the black-box boundary set.
+
+## Terminal monitor decision policy
+
+The monitor decision milestone moves one pure policy boundary out of the CLI
+composition root. It owns completion-first poll reduction, approval prompt
+clearing, question/error classification, every consumed-prompt suppression,
+verified-dead completion classification, post-effect timeout classification,
+activity cadence, and stable approval/activity/screen identity facts. It
+directly composes the existing poll and verified-dead policies and performs no
+I/O, locking, process access, callback delivery, or CLI presentation.
+
+Measured against exact head `e62a79cc94428ddb9a5c264600f259ca4d05ee0c`,
+the extraction reduces `src/cli-core.ts` from 32,398 to 32,146 physical lines
+(-252) and changes total production TypeScript from 75,934 to 76,076 (+142).
+The 42-line excess over the preferred +100 budget is the reviewed, explicit
+typed decision surface and direct proofability; no formatting compression or
+unrelated responsibility movement is used. The 394-line module remains below
+the 500-line hard boundary, every new function remains below 100 physical
+lines, and the hard approximate-complexity maximum is 27. The approval reducer
+(67/27) and consumed-approval classifier (58/23) are transparent exceptions to
+the default complexity-20 target: their branch tables stay cohesive and direct
+tests lock every precedence path.
+
+The composition root still owns terminal singleton, Store-writer and state
+locks; terminal observation and input adapters; process launch and death
+probing; state/event/outbox writes; callback continuation; clocks and sleeping;
+and public JSON/log presentation. Approval effects retain their asymmetric
+durable order: question follows `fingerprint -> event -> record`, while an
+unapprovable or evidence error follows `event -> fingerprint -> record`.
+Polling retains `activity -> completion -> verified-dead -> fresh clock ->
+timeout`, so work performed by persistence or the death probe can cross a
+deadline without deferring the timeout by one poll. Application orchestration
+and those effect ports remain the follow-on monitor service milestone.
+
+## Terminal monitor application service
+
+The monitor application milestone moves the singleton-owned retry loop and the
+complete locked monitor state machine behind five typed port groups: state,
+authority, callbacks, runtime, and presentation. The service owns initialization,
+submission reconciliation, binding deferral, observation application, approval
+continuation, activity persistence, stable completion, verified-dead fallback,
+and timeout routing. It composes the canonical monitor decision and poll policies;
+it does not import `cli-core.ts`, filesystem or process modules, raw lock or JSON
+persistence implementations, a callback transport, or a public JSON presenter.
+
+Measured against exact head
+`b637c012cfa87315380c150405a3384d653ac847`, the extraction reduces
+`src/cli-core.ts` from 28,336 to 27,319 physical lines (-1,017). Total
+production TypeScript changes from 79,308 to 80,554 lines (+1,246, 122.52
+percent of the core reduction). The transparent overhead is the 1,583-line
+typed application boundary, the 680-line CLI adapter and presenter boundary,
+and their direct trace types; no unrelated deletion or compressed formatting is
+used to hide that cost. Every new function remains within the preferred
+100-line/complexity-20 target. The largest is the 98-line/c20 public-result
+presenter; the largest service function is the 89-line/c11 approval application,
+and the service complexity maximum is c13. The production import graph remains
+acyclic.
+
+`cli-core.ts` still resolves the exact state and event paths, acquires the
+singleton owner, and supplies the concrete terminal, Store-writer and Turn-state
+lock functions. It also supplies state/event/ledger repositories, live process
+and death probes, terminal observation, callback transport construction, clock
+and crash hooks, and the public JSON/log writer. The CLI adapter accepts only
+those invocation-local capabilities, applies them in the legacy lock order, and
+cannot manufacture a path, Store, terminal route, or lock.
+
+The application order remains `initialize -> submission reconciliation -> poll
+-> detector/approval -> activity -> stable completion -> independent verified
+death -> fresh clock -> timeout`. A completion persisted immediately before
+process exit therefore still wins over orphan cleanup, and work performed by a
+death probe can cross a deadline without postponing timeout classification by
+one poll. Approval effects keep their intentional asymmetry: question is
+`fingerprint -> event -> record`, while an unapprovable/evidence error is
+`event -> fingerprint -> record`. Stale notifications sleep and retry without
+callback execution; duplicates present without delivery; a consumed question
+callback resumes the same generation; callback and completion claims remain
+outside the Turn-state lock exactly as before.
+
+Direct fast traces prove live-dispatcher PID gating before terminal I/O, two-poll
+completion stability, exactly one status/screen snapshot per poll with the legacy
+completion-metadata read order, death-before-fresh-clock ordering, both approval
+effect orders, executor-to-callback actor mapping, prepared-recovery release
+order (`state -> writer -> terminal`), and zero terminal I/O on a fresh-state
+retry. Acceptance errors and not-accepted/fenced presentations remain inside
+the terminal send lock; pending acceptance releases that lock before backoff.
+The retained lifecycle, approval and
+recovery shards provide 21 executable boundary cases for singleton ownership,
+Store-lock deferral, callback concurrency, detector diagnostics, durable
+completion, verified death, timeout, duplicate settlement, handoff and monitor
+relaunch behavior.
+
+## Native-thread lifecycle query slice
+
+The first native-thread lifecycle application slice moves only read-side
+candidate discovery, active-owner observation, exact candidate-token
+revalidation, restorable-origin eligibility, and previous-thread projection
+behind `NativeThreadLifecycleQueryPorts`. New-thread and resume-thread mutation,
+handoff, verified-empty recovery, reconciliation, dispatch recovery, selection
+snapshot persistence, and public JSON presentation remain in `cli-core.ts`.
+The query service has no transaction, lock, capability, Store-save, snapshot-save,
+terminal-input, recovery, or presenter port.
+
+Measured against exact head `ceb1e2fbb9ffa65af139182b36ea0bd527f4fe1e`,
+the slice reduces `src/cli-core.ts` from 31,321 to 30,775 physical lines (-546)
+and changes total production TypeScript from 76,474 to 76,569 (+95). The query
+service is 495 physical lines. No function reaches 500 lines; architecture
+validation retains the hard approximate-complexity ceiling of 50. The
+production import graph remains acyclic and the module has one targeted
+ownership domain, `native-thread-lifecycle-query`, with five retained lifecycle
+integration witnesses.
+
+The default approximate-complexity target remains 20. The reviewed cohesive
+exceptions are `activeNativeThreadOwners` (93 LOC/c28),
+`verifiedPreviousResumeCandidate` (68 LOC/c24), and
+`decodeThreadCandidateToken` (38 LOC/c21); all remain below 100 LOC and c50.
+
+The composition root implements the read port with frozen method-only adapters.
+It continues to own filesystem/process observation, terminal and agent adapters,
+Store path selection, selection snapshot writes, clock sampling, and public JSON.
+Store path selection is lazy and memoized at the first Store observation; token
+revalidation that fails before a Store read cannot resolve or inspect that path.
+Candidate observation preserves `active process ownership -> managed Session
+observation -> exact running version -> provider discovery`. Invalid UUID and
+Store-authority errors precede terminal scanning; an active external owner
+precedes managed-Session conflict observation. Version failure never calls the
+candidate provider. Candidate tokens retain baseline `JSON.stringify` byte and
+key-order semantics; no canonicalization was introduced. Their codec, candidate
+sorting, committed-previous policy, and pure snapshot assertions live in the
+adapter-neutral `native-thread-resume-snapshot-policy.ts`, so importing the
+query service cannot load snapshot filesystem persistence.
+
+The direct fast table locks version short-circuit, observation order,
+deduplication and sorting, exact token mismatch precedence and bytes, Store then
+terminal ownership error priority, and one exact committed-transition read for
+the previous resume candidate. Snapshot assertion traces additionally lock lazy
+cwd and clock callbacks, terminal-evidence order, fingerprint-before-row
+short-circuiting, ordered-row equality, and rollout `JSON.stringify` field-order
+sensitivity. Since this slice writes nothing, it adds no durable-write or crash
+window; the existing core snapshot write and lifecycle mutation/recovery
+witnesses remain authoritative until the separate mutation application slice.
+
+## Terminal monitor startup eligibility policy
+
+Startup, handoff, and locked launch preparation now share one pure staged
+eligibility policy. The policy owns candidate priority and exact reason text for
+terminal-bridge identity, dispatch authority, blocking submission, runtime
+identity, deferred-transfer acceptance, and deadline metadata. Its generator
+yields only the next typed observation, so the CLI composition root does not
+touch terminal control, the dispatch ledger, Store path authority, runtime
+identity, or a deferred transfer until every earlier candidate has passed.
+The policy has no ports, filesystem or process access, locks, mutation, or CLI
+presentation.
+
+Measured against exact head `8e5c636604845d42f4f0e0af28b36621974e75b6`,
+the extraction reduces `src/cli-core.ts` from 30,775 to 30,640 physical lines
+(-135) and changes total production TypeScript from 76,569 to 76,649 (+80).
+The new policy is 195 physical lines. Its 135-line staged reducer has approximate
+complexity 48: this is a reviewed transparent exception to the preferred 100/20 target,
+while remaining below the hard 500/50 gate. Keeping the precedence in one
+reducer makes every short circuit directly table-testable without concealing
+branches in I/O adapters. The shared, I/O-free `terminal-submission-facts.ts`
+owns the submission projection and typed Codex anchor codec; its 99-line
+validator has approximate complexity 49, a reviewed transparent exception to
+the preferred complexity-20 target and still below the hard gate. All other
+new functions are below 15 lines and complexity 5.
+
+The composition root remains the sole owner of terminal-control decoding,
+dispatch-ledger and deferred-transfer reads, Store path derivation and symlink
+validation, runtime identity observation, locks, mutation, monitor launch, and
+public JSON/log presentation. Observation order remains `bridge/status ->
+message -> terminal control -> dispatch ledger -> conversation state path ->
+Store derivation -> submission -> runtime -> Store derivation -> deferred
+transfer -> deadline`. In particular, non-terminal and inactive candidates
+never derive a Store, while a malformed Store path still fails before an
+already-invalid dispatch ledger is classified, preserving the prior error
+precedence. Dispatch `state_path` is not observed until the earlier ledger,
+message, control, conversation, Session, and Turn predicates have passed.
+
+## Native-thread transition verification and settlement
+
+The second native-thread lifecycle slice moves the mutation's typed
+verification and settlement seam out of the CLI composition root. Before any
+durable transition is prepared, the verification adapter preserves lifecycle
+eligibility, plan selection, initial idle status, the exact Claude agents-row
+proof, and the single Codex `/status` probe. After core has durably recorded
+`command_submitted`, the settlement service owns stable identity verification,
+verified-transition persistence, the verified crash checkpoint, exclusive
+target ownership, Session commit, committed-transition persistence, resolved
+ledger persistence, and final presentation. Dispatch preparation, composer
+revalidation, terminal input, raw lock acquisition, recovery, handoff, and
+verified-empty reconciliation remain in `cli-core.ts`.
+
+Measured against exact head `a96bfbb2c6d011e4bdbe53f883e01250ad1e4023`,
+the slice reduces `src/cli-core.ts` from 29,281 to 28,610 physical lines
+(-671) and changes total production TypeScript from 77,792 to 78,388 (+596).
+The transparent typed-capability overhead is 88.8% of the core movement. Issue
+#126 has no production-zero-growth requirement; the added lines are the five
+explicit port groups, exact verification adapter, capability-scoped repository
+surface, post-lock terminal/Store resource adapter, and reusable direct evidence
+rather than formatting compression or an unrelated responsibility move.
+
+`runNativeThreadTransition` is 421 LOC/c1, with its transaction callback at
+412 LOC/c44. The settlement service is 331 physical lines; its largest function
+is `settleFailedNativeThreadTransition` at 124 LOC/c9. The verification adapter
+is 707 physical lines; its largest function is
+`verifyNativeThreadTransition` at 201 LOC/c45. Every function remains below the
+hard 500 LOC/c50 gates. Reviewed exceptions to the default 100 LOC/c20 target
+are the cohesive transaction wrapper/callback (421/c1 and 412/c44), core port
+wiring (173/c1), failure settlement (124/c9), verification polling state
+machine (201/c45), and shared known-root reducer (94/c24). Keeping these order
+tables intact makes their fail-closed precedence visible and directly testable.
+The 100-line resource adapter's exported operation is 77 LOC/c1 and its inner
+capability gate is 55 LOC/c14, so it requires no default-threshold exception.
+
+The service imports no filesystem or path API, raw lock, Store directory,
+public JSON, terminal bridge, `any`, or `Record<string, any>`. Core still owns
+argv and public JSON, constructs concrete terminal and Store adapters, acquires
+terminal then writer locks, and invokes the presenter before leaving the
+transaction callback. Every service repository operation receives the same
+authentic `CanonicalMutationScopes` and `CanonicalMutationResources`; the
+capability-gated repositories bind every verification, ownership, transition,
+Session, and ledger operation to both locked resources. Before observation or
+I/O, the adapter verifies active scopes, the post-lock terminal's exact resource
+key and process incarnation, and the captured Store resolving to the active
+canonical writer. Lifecycle ledger
+construction and save form one scoped port; its `store_dir` must strictly equal
+the active writer Store, and persistence uses the post-lock fresh terminal route.
+The lifecycle resource adapter reuses the common mutation pair gate and
+`terminalRuntimeResourceKey`; it imports no terminal-dispatch domain module.
+Agent kind and PID come only from that resolved terminal and are absent from the
+service verification request.
+Lifecycle and dispatch compatibility exports share one adapter-neutral native
+identity fence, matcher, and strict complete-rollout predicate in
+`terminal-binding-authority.ts`. Blank or malformed runtime rollout fields fail
+closed before path comparison and cannot escape as a `TypeError`.
+
+Verified success retains `verify -> verified transition -> crash hook ->
+ownership -> Session commit -> committed transition -> resolved ledger ->
+present`. Failure retains committed-bookkeeping error precedence, verified
+recovery without roll-forward, proven-zero-input abort plus source restoration,
+and possible-input uncertainty plus source quarantine. A five-case recording
+port table asserts those orders, exact scope/resource forwarding, and
+presentation before writer and terminal lock release. The no-rollout identity
+case separately proves that a legitimate status-card or pre-materialization
+observation returns false without reading a missing rollout or throwing. One
+targeted ownership domain retains five native lifecycle integration witnesses.
+Direct resource-adapter cases additionally prove moved-route fresh bytes and
+zero verification/ownership/ledger I/O for wrong incarnation, malformed or
+key-mismatched terminal/writer resources, captured-Store mismatch, and released
+scopes. Adapter cases pin Codex probe/companion ordering, Claude rows-before-status
+ordering, and the no-revalidation callback's original synchronous invocation.
+
+## Terminal list and action authority projection
+
+The terminal-list milestone gives list projection and fresh mutation
+preparation one canonical send-authority reducer. `terminal-action-projection.ts`
+owns Session-claim conflict precedence, dispatch/Session conflict composition,
+send authority, safe action selection, management facts, and handoff/recovery
+projection. `terminal-authority-policy.ts` owns provider-neutral terminal and
+process-incarnation facts, managed-binding conflict classification, Codex
+companion fences, exact deferred-source authority, stored Turn identity, and
+the byte-sensitive verified-empty, deferred-foreground, observed-handoff, and
+active-Turn token codecs. Both modules are typed and have no filesystem,
+process, lock, CLI-option, concrete-adapter, or public-JSON input boundary.
+The adapter-neutral complete-rollout predicate, identity fence and matcher from
+the lifecycle slice remain canonical in `terminal-binding-authority.ts`;
+authority policy directly imports and re-exports them. That module also owns
+the single status-card predicate and neutral binding-conflict/candidate helpers.
+PR4C's dispatch execution service imports those identity decisions from binding
+authority and its process-incarnation and companion decisions from authority
+policy, so production has one implementation for each decision and no cycle.
+
+Measured against exact lifecycle head
+`10b2b9c60a8f5635961156bf9951472ea5542a48`, this slice reduces
+`src/cli-core.ts` from 28,610 to 28,336 physical lines (-274) and changes total
+production TypeScript from 78,388 to 79,308 (+920).
+The overhead is reported rather than hidden by compact formatting: it is the
+explicit typed observation handoff needed to keep Store and terminal reads in
+the composition root while making each authority stage independently bounded
+and testable. The production graph has 78 modules, 307 static import edges, and
+zero cycles. Targeted ownership is split honestly across
+`terminal-action-projection` and `terminal-authority-policy` with five retained
+integration witnesses each; the pre-existing binding-authority and
+dispatch-policy owners are also reduced to five witnesses each.
+
+The old 1,162-line terminal projection callback is now a sequence of bounded
+stages. The final TypeScript AST spans are binding observation 298 lines,
+verified-empty authority 97, deferred-source authority 77, deferred action
+authority 106, handoff authority 139, terminal-scoped approval authority 96,
+authority composition 23, public rendering 256, and the outer list projection
+144.
+No touched or extracted function reaches the hard 500-line boundary. The
+TypeScript AST approximate-complexity maximum across the touched and extracted
+production functions is 48, below the hard approximate-complexity-50 gate.
+Binding observation, deferred action authority, handoff authority, and
+public rendering are reviewed exceptions to the preferred 100-line and/or
+complexity-20 targets: further splitting them would duplicate the staged facts
+or move Store reads across a safety short circuit.
+
+The composition root continues to own deferred-transfer, managed-Session,
+managed-Turn, transition, and dispatch-ledger reads; terminal/process
+collection; Codex inventory and identity observation; terminal-scoped approval
+boundary I/O; runtime logging; and the final public JSON shell. The staged calls
+preserve the old left-to-right read order. In particular, a Session-authority
+conflict never reads the dispatch owner's Session id, a genuine mismatch keeps
+the old two `sessionIdForConversation` calls, and every unresolved-transition
+read remains behind the same verified-empty, reconcile, external-handoff, or
+active-Turn preconditions. Listed tokens remain stale snapshots; mutation paths
+repeat fresh observation and invoke the same canonical send reducer before a
+side effect. Blocking Turn statuses do not inspect callback delivery, current
+approval actions are retargeted before reading the live terminal approval
+state, and stored native rollout fields remain unread until all earlier Turn
+identity exits have passed.
+
+Direct fast proofs compare the old and new `JSON.stringify` action bytes and
+key order, verified-empty and deferred v2/v5 token hashes, active-Turn handoff
+hashes, conflict precedence with lazy managed-Turn facts, selector alias and
+process-incarnation behavior, and list-snapshot versus fresh-mutation send
+decisions. Getter-backed fixtures make the three lazy-read fences executable,
+and ordinary fixtures compare canonical results with the previous decisions.
+Existing binding-authority, dispatch-policy, list-renderer, and
+terminal-send boundary witnesses remain in place; this slice changes no action
+name, action order, error string, token field order, Store format, or public
+contract version.
+## Native-thread lifecycle crash recovery and reconciliation
+
+The third native-thread lifecycle slice moves one crash-recovery state machine
+from `recoverLifecycleFenceBeforeMutation` through fail-closed lifecycle-ledger
+reconciliation into `native-thread-lifecycle-recovery-service.ts`. It includes
+human-observed ledger rebuild, prepared rollback, verified roll-forward,
+committed/aborted replay, possible-input quarantine, and operator-authorized
+Claude/Codex identity reconciliation. Ordinary deferred foreground-dispatch
+recovery remains a core-owned state machine behind one scoped call. Verified
+empty recovery, observed external-handoff send/adoption, lifecycle mutation,
+monitor/callback orchestration, and public presentation remain outside this
+service.
+
+Measured against exact head `29446b0649555c4bfca8ee23a4f2f0d9523c9fcf`,
+the slice reduces `src/cli-core.ts` from 27,319 to 26,095 physical lines
+(-1,224, -4.48%) and changes total production TypeScript from 80,554 to
+81,427 (+873, +1.08%). The transparent typed-boundary overhead is 71.3% of
+the core movement. It consists of the four port groups, direct recording
+surface, fresh-route composition, normalized probe facts, and the core-side
+raw terminal adapter; issue #126 does not impose a zero-production-growth
+target. The production graph has 82 modules, 339 static import edges, and zero
+cycles.
+
+The recovery service is 1,834 physical lines and its infrastructure adapter is
+263 lines. The largest function remains the 211-line/c32 reconciliation reducer
+and the highest conservative approximate complexity is c37 in the 186-line
+manual Codex probe reducer. Every function is below the hard 500 LOC/c50 gates.
+The reviewed exceptions to the default 100 LOC/c20 target are:
+
+- reconciliation (211/c32), whose ordered status and catch precedence is one
+  directly recorded state machine;
+- prepared human-observed handoff recovery (116/c21), which keeps its source
+  CAS, identity observation, rollback, and verified checkpoint together;
+- stored ledger/transition comparison (66/c36) and live-terminal/adapter
+  comparison (68/c25), split only at the side-effect boundary so boolean
+  short-circuit order is unchanged;
+- verified after-binding revalidation (143/c36), uncertain manual settlement
+  (140/c15), Claude stable identity probing (115/c27), and Codex stable identity
+  probing (186/c37), whose polling and exact-incarnation precedence remain
+  visible as cohesive reducers;
+- the core-side probe adapter factory (110/c1), which keeps its closed raw
+  capability, bridge preparation, normalization, and ordered observations in
+  one infrastructure boundary while each returned method remains short.
+
+The service imports no CLI core, filesystem/path API, raw lock, raw repository,
+raw JSON persistence, public presenter, `TerminalAgentAdapter`, terminal-agent
+bridge type or value, `any`, or `Record<..., any>`. It contains no raw screen
+excerpt or composer grammar. Its public request contains only fresh terminal
+facts; Store directory and path authority are absent. The four typed port
+groups are scoped authority, persistence, terminal/process evidence, and
+clock/sleep. Core retains terminal then writer lock acquisition, the ordinary
+deferred-recovery implementation, raw transition/Session/ledger repositories,
+terminal bridge and process probes, Store/path canonicalization, CLI logging,
+and JSON output. The core-side recovery adapter exposes only normalized
+status/probe facts and closed plan steps through separately scoped
+`probeThreadLifecycle`, `planThreadLifecycle`, and `observeThreadLifecycle`
+ports; the full terminal adapter is never returned to business code. Before
+either service entry, core projects the fresh resolved terminal into a new
+runtime object with exactly `conversationId`, `agent`, `pid`, and
+`terminalControl`; the broad resolved terminal remains captured only by the
+core ports closure.
+
+Every authority, repository, process, and terminal port call receives the same
+active `CanonicalMutationScopes` and `CanonicalMutationResources`. Before the
+service is entered, core authenticates both scopes, resolves the terminal again
+after lock acquisition, proves the captured and fresh terminal/process
+incarnations match, and captures the canonical writer Store. The shared native
+thread resource adapter repeats those checks for every port call, including
+reads and probes as well as transition, Session, and ledger writes. Thus a
+request cannot retain free terminal-control, Store, cwd, or path authority, and
+released, cross-transaction, wrong-route, or wrong-Store capabilities fail
+before business I/O. Lifecycle ledger construction remains in the core adapter;
+rebuild phases replace their control with the post-lock fresh route and every
+persisted ledger Store must equal the canonical writer resource.
+
+### Recovery order and durable checkpoints
+
+The extraction preserves these existing sequences inside the terminal ->
+writer lock scope:
+
+| Recovery path | Exact effect order retained |
+| --- | --- |
+| Fence entry | authenticate/fresh terminal -> ordinary deferred recovery -> ledger load -> optional rebuild -> lifecycle classification -> reconcile |
+| Missing/resolved human-handoff ledger | transition list -> typed ledger build -> complete transition/terminal/adapter validation -> compare-and-save rebuild ledger -> reload |
+| Live automatic dispatcher | dispatcher process probe -> unchanged ledger; no Store transition read, probe bridge, or write |
+| Wrong Store / unavailable transition | Store comparison or transition load -> fail-closed uncertain-ledger CAS -> reload; a failed fail-closed CAS returns the original ledger |
+| Prepared, zero possible input | ledger/terminal/adapter validation -> exact before-owner proof -> target/source reads and source restoration -> aborted transition CAS -> resolved-ledger CAS -> reload |
+| Verified | after-binding/live identity verification -> exact target-owner proof -> Session commit -> committed transition CAS -> resolved-with-binding ledger CAS -> reload |
+| Committed / aborted replay | live verification and owner/target assertion or before-owner/source restoration -> resolved-ledger CAS -> reload |
+| Dispatching/submitted automatic recovery | uncertain transition CAS -> source quarantine Session CAS -> uncertain-ledger CAS -> reload |
+| Operator-authorized uncertain recovery | exact stable manual probe -> process/rollout assertion -> before rollback, or target verification -> target-owner proof -> Session commit -> committed transition CAS -> resolved-ledger CAS -> reload |
+| Inner recovery failure | source quarantine attempt -> fail-closed uncertain-ledger CAS -> reload/original ledger |
+
+Bridge construction remains at the old probe checkpoints: after the verified
+human-handoff early return, after Claude prepare-time process validation, and
+after the Codex-agent guard but before root/runtime observation. Raw terminal
+status, clear-line, `/status` input, agents rows, resolver, and process-birth
+operations stay in core or its recovery adapter. A Claude sample performs
+agents-row load then lifecycle observation inside one scoped call, and business
+recovery performs terminal status only afterward. A Codex post-`/status` sample
+performs one raw status call and only then raw-screen lifecycle observation
+inside the same scoped adapter call; it returns normalized status plus the
+optional observation. No raw screen or composer decision crosses into the
+service. No new durable checkpoint or retry permission is introduced. Manual
+terminal-close JSON is still emitted by core before the writer and terminal
+scopes are released.
+
+The direct fast recording table fixes five precedence witnesses: live
+dispatcher short-circuit; wrong-Store fail closed before transition load;
+prepared rollback; dispatching possible-input quarantine; and verified
+roll-forward. It asserts the exact transition/Session/ledger phase order, CAS
+expectations, probe-before-plan order, probe preparation point, and
+reference-equal forwarding of the same active scopes/resources on every port
+call. Direct adapter witnesses fix Claude rows -> observe and Codex status ->
+observe order, while the static boundary witness rejects bridge imports, full
+terminal-adapter capability, raw screen excerpts, or composer helpers in the
+service. A runtime-shape witness also fixes the four projected request keys and
+proves that neither `adapter` nor `legacy` survives projection. Existing
+lifecycle recovery, human handoff, no-rollout, lifecycle, and ownership
+integration witnesses remain the retained black-box boundary set.
+
+## Deferred Codex foreground application and recovery
+
+This slice moves the complete deferred Codex foreground application vertical
+out of `cli-core.ts`: preparation and fresh-authority publication; source
+reservation and target preparation; dispatch begin/stage advancement;
+zero-input abort and rollback; accepted commit and resolution; uncertain
+settlement; and prepared, accepted, and committed crash recovery. The typed
+implementation is split across the application, preparation, and recovery
+services plus their CLI adapters, a data-only boundary module, and the
+invocation-scoped repository capability. Observed handoff, native-thread
+lifecycle recovery, ordinary dispatch, monitor/callback behavior, public
+presentation, and raw terminal I/O remain outside this vertical.
+
+Measured against exact head
+`257950022ea40e343808ef68c903c6f874497a09`, the slice reduces
+`src/cli-core.ts` from 26,095 to 23,124 physical lines (-2,971, -11.39%) and
+changes total production TypeScript from 81,427 to 84,241 (+2,814, +3.46%).
+Typed production overhead is 94.7% of core movement, leaving 157 lines of
+positive movement margin. The production graph has 90 modules, 417 static
+import edges, and zero cycles.
+
+Across the eight new production modules, the TypeScript AST inventory contains
+219 functions. No function reaches the default 100 LOC/c20 review threshold;
+the maxima are 92 LOC and c19. Consequently there is no 500 LOC/c50 hard-gate
+exception. Application and preparation each expose three typed port groups;
+recovery exposes four. No service imports CLI core, Node filesystem/process
+APIs, raw JSON/lock helpers, a presenter, `ResolvedTerminalConversation`,
+`TerminalAgentAdapter`, or the concrete capability adapter. The service-side
+repository scope is a narrow interface in `deferred-foreground-boundary.ts`;
+its implementation is module-private and can only be obtained through the
+production terminal/writer or terminal/writer/state binders.
+
+The preparation request receives a projected terminal object with exactly
+`conversationId`, `agent`, `pid`, optional `workspace`, `target`, `resourceKey`,
+optional endpoint evidence, and `canonicalEndpoint`. The returned application
+boundary contains only those terminal facts and immutable transfer/session,
+process-incarnation, dispatch-snapshot, rollout-authority, and CAS facts. The
+resolved terminal, concrete control, adapter, legacy marker, Store directory,
+Turn paths, and terminal transport methods remain captured in CLI adapter
+closures. Runtime `Object.keys` witnesses fix the request, terminal-facts, and
+boundary shapes and reject `adapter` or `terminalControl` leakage. A stable
+data-only projection carries the source-reserved and target-prepared revisions
+and binding tokens through verification, dispatch, commit, and resolution;
+the associated broad terminal remains only in the CLI adapter.
+
+The capability binder authenticates one active terminal -> Store writer ->
+optional Turn state transaction before repository use. Terminal incarnation
+and resource key, absolute canonical Store key/value, `state.json` membership
+under that Store, matching `events.ndjson`, and state resource key/value are
+checked before I/O. Null, object, relative, cross-Store, wrong-key,
+wrong-process, wrong-log, and released-scope cases fail with ordinary errors
+before repository access. The concrete scope is not exported, and every scope
+method repeats the active-scope gate; retained scopes therefore expire when the
+transaction callback returns. Recovery asserts the transfer, projected
+terminal, and Turn route immediately after candidate selection and carries the
+same scope through every transfer/Session/state/ledger adapter operation. The
+PR172 lifecycle-recovery service retains ownership of its state machine and
+invokes this deferred service through its existing `recoverDeferred` port with
+the same active terminal and writer scopes/resources.
+
+### Application, CAS, and recovery order
+
+The extraction preserves these Store, Turn, ledger, and terminal-evidence
+orders:
+
+| Path | Exact effect and CAS order retained |
+| --- | --- |
+| Fresh preparation | process incarnation -> fresh rollout/dispatch observation -> fresh binding token -> target/transfer IDs -> canonical boundary revalidation -> exclusive ownership -> unresolved-transfer list (source identity or terminal id + endpoint; PID is not collision authority) -> request hash -> dispatcher pid -> clock -> transfer create with expected revision `null` |
+| Stale list token | process incarnation -> fresh observation -> freshly derived token -> reject; no ID generation, ownership check, list, hash, clock, or write |
+| Reservation | transfer load/authority -> fresh source verification -> source Session `bound -> transitioning` CAS -> crash point -> transfer `prepared -> source_reserved` CAS -> crash point -> transfer `source_reserved -> target_prepared` CAS with canonical Turn path -> crash point -> target Session create with expected revision `null` |
+| Dispatch evidence | target/source receipt checks -> transfer `target_prepared -> dispatch_started` CAS -> transfer `dispatch_started -> text_injected` CAS -> transfer `text_injected -> enter_dispatched` CAS; each write consumes the immediately loaded transfer revision |
+| Zero-input abort | possible-input guard first -> aborted transfer CAS -> target detach Session CAS -> source restore Session CAS -> `abort_resolved` transfer CAS. Before current-terminal recovery, every Store-authoritative aborted intent is finalized under the existing writer scope without pane/PID/cwd checks or a Turn-state lock, then transfers are listed again and filtered to the current terminal. Recovery with a prepared Turn first persists the aborted Turn receipt, then the resolved safe-to-retry ledger receipt, then performs those transfer/Session CAS writes |
+| Accepted commit | transfer/source/target reads and exact authority -> ownership -> optional same-thread source scrub Session CAS -> target accepted Session CAS -> committed transfer CAS -> source detach Session CAS -> target bind Session CAS -> exclusive-owner revalidation -> resolved transfer CAS |
+| Uncertain | authority and dispatch-start fence -> clock(s) -> one transfer CAS carrying `do_not_retry: true`; no Session rollback and no terminal retry |
+| Committed recovery | transfer/Turn/target/ledger authority -> exact acceptance observation -> accepted Turn state write -> accepted ledger write -> crash point -> source/target/transfer resolution CAS -> accepted Turn identity assertion |
+| Possible-input recovery | exact Turn/ledger authority -> one acceptance observation. Durable zero-input proof may enter the abort path; otherwise no abort or rollback is callable. A v3 pending candidate returns without replay, while older pending or observation failure reloads durable transfer authority, records uncertainty at most once, and fails closed |
+
+Turn acceptance remains stronger than later Session and ledger bookkeeping. In
+accepted recovery the accepted Turn state is written before Session/transfer
+commit and the accepted ledger is written only after the resolved Session
+authority and Turn identity checks. If later bookkeeping fails, the accepted
+Turn is retained and the failure path records stalled/uncertain durable
+evidence; terminal input is never replayed. All transfer writes use explicit
+revision CAS, Session writes use the immediately observed managed-Session
+revision, target creation uses `null`, and no list token is reused as mutation
+authority: mutation always re-observes the canonical post-lock terminal and
+binding authority.
+
+Four fast direct files provide the fake-port order, route, capability, and
+transition tables. They cover stale-token revalidation, request/boundary
+runtime shape, revision/clock order, possible-input never-abort behavior,
+single-observation recovery, durable reload before uncertainty, status routing,
+multiple-candidate rejection before state scope, cross-terminal abort cleanup
+before fresh matching, stable reservation-boundary CAS facts, canonical resource failures,
+non-public scope construction, and every-method released-scope failure. The
+five retained targeted integration witnesses are Codex no-rollout binding,
+dispatch authority, dispatch recovery, Session acceptance, and terminal send
+gates.
+
+## Terminal list and selector CLI facade
+
+The terminal-list slice moves raw Store, managed-Session, managed-Turn,
+terminal/process, dispatch-ledger, and approval observations out of
+`cli-core.ts` into `terminal-list-cli-adapter.ts`. The adapter owns only CLI
+composition and infrastructure projection. Existing terminal action,
+authority, binding, dispatch, approval, and list-renderer modules remain the
+unique decision owners; the facade does not copy their reducers, tokens,
+identity classifiers, conflict precedence, or approval rules.
+
+The exported facade has five cohesive, explicitly typed dependency groups:
+reconciliation, terminal discovery, Store observation, authority observation,
+and policy configuration. `cli-core.ts` constructs one local facade and routes
+list and selector work through it. Each facade call installs its own immutable
+dependency set in an async-local execution context. There is no mutable module
+configuration or catch-all `(...args: any[]) => any` runtime port, and the only
+runtime export from the adapter is `createTerminalListCliFacade`.
+
+The direct concurrency witness runs facade A's reconciled `runList` and facade
+B's selector discovery concurrently, pauses both across independent awaits,
+then releases B before A. The observed post-await callbacks remain B's process
+source and A's idle reconciler respectively. After both Promises settle, a
+second selector call through each facade still observes its own marker. This
+locks the per-execution dependency isolation and factory-only entry boundary.
+
+Selector candidate projection is the I/O-free
+`terminal-selector-projection-service.ts`; it accepts typed entry facts and one
+typed active-status policy. Process elapsed parsing has one I/O-free canonical
+owner in `terminal-process-facts.ts`; the process-source adapter compatibility
+re-exports it, while the selector service never imports the process-source
+module or its `node:child_process` edge. Managed-Session revision is read
+directly from `managed-session.ts`. Native Turn identity matching has one
+neutral implementation in `terminal-authority-policy.ts`, shared by list and
+dispatch; the dispatch module keeps only a compatibility re-export.
+
+Measured against exact head `29219e4f98a6057924feb37ed05a9982e7310695`,
+the slice reduces `src/cli-core.ts` from 23,124 to 20,051 physical lines
+(-3,073) and changes production TypeScript from 84,241 to 84,907 (+666). The
+transparent typed-facade overhead is 21.67% of the core movement. The graph
+changes from 90 modules and 417 static import edges to 93 modules and 446
+edges, with zero cycles before and after. The terminal-list owner has two
+modules and four targeted integration witnesses. The preceding deferred
+foreground slice retains its eight-module ownership mapping unchanged.
+
+The stacked composition preserves the deferred foreground authority,
+preparation, application, and recovery services as the only owners of their
+state machines. Its existing authority-adapter ports now call the terminal-list
+facade for managed-Turn attention, transition state, and terminal-incarnation
+blocking facts; no old inline deferred reducer was restored during the rebase.
+
+The infrastructure adapter is a reviewed exception to the preferred
+100-line/complexity-20 function target because its staged observation
+functions preserve existing Store/terminal/error priority and getter
+short-circuits. Its maximum function span is the 298-line/c43 binding
+observation, and its highest conservative approximate complexity is c44 in the
+139-line handoff observation. Public rendering is 256/c42, terminal discovery
+entry composition is 227/c39, and scoped approval resolution is 221/c36. All
+remain below the hard 500-line/c50 boundary. The pure selector service peaks at
+42/c11 and the process fact parser at 24/c9.
+
+Direct fast proofs preserve exact selector JSON bytes and key insertion order,
+mutation-disabled lazy `available_actions` reads, approval fallback getter
+order and action target, canonical native-identity getter order, and concurrent
+facade isolation. Focused list, delegate, Session-selector, action projection,
+and process-source witnesses retain Store/terminal/error priority, the second
+Session lookup on mismatch, stale-list versus fresh-mutation separation, and
+public token bytes.
+## Generic CLI file-lock infrastructure
+
+The synchronous generic file-lock protocol now lives in
+`file-lock-cli-adapter.ts`. The adapter owns only exclusive private-file
+creation, stale-owner probing, reclaim-guard cleanup, token-matched release,
+and legacy owner decoding. Store leases, terminal routing, lifecycle ledgers,
+monitor ownership, callback policy, and deferred-transfer decisions remain in
+their existing owners.
+
+The factory receives typed clock, PID, sleep, nonce, process-signal, and
+filesystem ports and retains no mutable global configuration. `cli-core.ts`
+binds its existing async-local clock/PID/sleep functions once; those functions
+still resolve the active command context at each lock call. All 28 acquisition
+call sites keep the same lock path, timeout/retry options, returned release
+closure, and surrounding `try`/`finally` order. The one stale probe and one
+owner read also retain their previous query inputs and results.
+
+Against exact parent `59983e63c8e5569d27e6396dc0961433e3a6ec34`, the move
+reduces `cli-core.ts` from 20,051 to 19,901 physical lines (-150). The new
+infrastructure module is 192 lines, so production grows from 84,907 to 84,949
+(+42, below both the 50-line target and the 150-line core movement). Direct
+recording tests lock acquisition/write/close/release order, live-owner timeout
+cleanup, dead-owner reclaim-before-retry, and descriptor close-before-error
+propagation. No file-lock behavior or error precedence changes.
+
+## Ordinary terminal command CLI facade
+
+The ordinary-command slice moves send, respond, approve, exclusive replay,
+and dispatch composition out of `cli-core.ts` into
+`terminal-command-cli-adapter.ts`. Cancel, renew, close, monitor, lifecycle,
+callback, and deferred-foreground state machines remain with their existing
+owners. The adapter composes the existing terminal-dispatch execution,
+application, capability, receipt, deferred-foreground, terminal-list, and
+file-lock factories; it does not introduce a second reducer or authority
+decision.
+
+The only runtime export is `createTerminalCommandCliFacade`. Each invocation
+runs with an immutable dependency set in async-local context, so concurrently
+awaiting facades cannot observe one another's ports. The emitted command-facade
+declaration contains neither `any`, `Record<..., any>`, nor
+`ResolvedTerminalConversation`. Every callback has explicit parameters and
+results. `TerminalDispatchTerminal` is only a structural, CLI-infrastructure
+carrier for `conversationId`, `agent`, `pid`, and `terminalControl`; it does
+not claim to remove extra properties from the runtime object.
+`TerminalControlSendRequest` now uses a six-field
+`TerminalControlSendOptions extends Record<string, unknown>` boundary covering
+only the timeout, polling, scrollback, and Claude-home values read by dispatch.
+The structural terminal carrier and concrete deferred adapters remain
+CLI-infrastructure values, not business-service requests.
+
+Every actual deferred business-service request still crosses the explicit
+`projectDeferredForegroundTerminalFacts()` literal projection. The direct
+preparation-service witness fixes the request and boundary `Object.keys`, and
+proves that neither `adapter` nor `terminalControl` crosses that boundary.
+Terminal-dispatch execution receives typed facts and ports, while dispatch
+application and capability receive authenticated routes/repositories; none of
+the three receives the concrete terminal carrier.
+
+Measured against exact parent
+`921636a4a86da8d565c659bdcbb64021ac112366`, the slice reduces
+`src/cli-core.ts` from 19,901 to 16,350 physical lines (-3,551) and changes
+production TypeScript from 84,949 to 86,473 lines (+1,524). Typed production
+overhead is 42.92 percent of core movement, leaving 2,027 lines of movement
+margin. The production graph has 46 domains, 95 modules, 482 static import
+edges, and zero cycles. `cli-core.ts` retains one production importer. The
+ordinary-command owner has one module and exactly five focused integration
+witnesses.
+
+The extraction preserves three critical transaction shapes. Replay validates
+ledger receipt history before active-ledger authority, validates every stored
+match (including getters and conflicting safe-abort receipts) before filtering
+retryable zero-input receipts, validates the durable log body, and presents
+inside the canonical mutation callback. Transport failure may call the
+zero-input reducer only when no text timestamp exists and the error is
+`TerminalInputNotStartedError`; every possible-input failure instead records
+uncertainty, emits `do_not_retry`, and presents the uncertain receipt. Managed
+approval holds the terminal lock across observation, reservation, key
+dispatch, durable resolution, monitor handoff, and JSON presentation. Its
+state lock is released before monitor launch as before, while a failed
+`beforeKeyDispatch` leaves the reserved uncertain marker and sends no key.
+
+The following infrastructure functions are reviewed exceptions to the
+preferred 100-line/c20 target. Counts use the same conservative physical-span
+and nested-function-excluding complexity method as this document; every entry
+remains below the hard 500-line/c50 gate.
+
+| Function or nested stage | LOC / approximate complexity |
+| --- | ---: |
+| `runManagedApprovalDispatch` | 486 / c2 |
+| `runRawTerminalSend` | 443 / c2 |
+| raw-send canonical mutation callback | 419 / c45 |
+| `runApprovalWithStateLock` | 393 / c30 |
+| `replayExactActiveTerminalSubmission` | 276 / c41 |
+| `runManagedSessionSend` | 265 / c21 |
+| `resolveTerminalDispatchSubmissionOwner` | 261 / c43 |
+| `prepareTerminalControlSend` | 255 / c42 |
+| `runTurnResponse` | 223 / c11 |
+| `replayExactStoredTerminalSubmission` | 188 / c22 |
+| managed-send mutation callback | 186 / c21 |
+| `runApprove` | 177 / c32 |
+| respond outer mutation callback | 164 / c1 |
+| `runTerminalConversationApprove` | 162 / c10 |
+| respond state callback | 153 / c22 |
+| `validateStoredTerminalSubmissionMatch` | 150 / c28 |
+| `createTerminalDispatchRuntime` | 148 / c4 |
+| approval `beforeKeyDispatch` callback | 132 / c31 |
+| `runTerminalControlSend` | 105 / c9 |
+| `runTerminalDispatchTransport` | 106 / c7 |
+| raw-send state callback | 103 / c4 |
+
+The evidence map deliberately reuses the direct tests of the unique dispatch
+owners instead of copying their state machines into facade tests:
+
+| Contract | Direct proof | Focused real-CLI proof |
+| --- | --- | --- |
+| Factory-only typed ports and await isolation | `terminal-command-cli-adapter.test.ts` fake-port trace | all five owner files exercise the bound production factory |
+| Replay receipt/log bytes, getter validation, error priority, and locked presentation | facade compiled-wiring proof; `terminal-dispatch-receipt.test.ts` exact bytes | `agent-cli-composer-replay.test.ts` exact output/log body and no second Enter |
+| Possible input never becomes zero-input retry | facade failure-wiring proof; `terminal-dispatch-application.test.ts` text-progress table; `terminal-dispatch-execution.test.ts` one-Enter table | `agent-cli-dispatch-authority.test.ts` retryable pre-input versus uncertain post-input receipts |
+| Approval uncertain reservation and terminal-lock lifetime | facade lock-wiring proof; `terminal-agent-bridge.test.ts` reservation/callback/no-key order | `agent-cli-claude-callback.test.ts` and `agent-cli-control-locks.test.ts` |
+| Native acceptance and dispatch-owner authority | execution/application fake-port tables | `agent-cli-session-acceptance.test.ts` |
+| Runtime stripping at the service boundary | `deferred-foreground-preparation-service.test.ts` exact request/boundary keys | the Session-acceptance witness traverses the same production projection |
+
+The five selected focused files are composer replay, dispatch authority,
+control locks, Claude callback, and Session acceptance. They cover replay,
+send/possible-input, approval, lock order, and native acceptance without adding
+lifecycle, close, monitor, or callback ownership to this facade.
+
+## Terminal dispatch repository and recovery
+
+The terminal dispatch recovery slice moves the raw ordinary-ledger repository,
+prepared and lagging crash reconciliation, verified-dead reconciliation, and
+callbackless local-completion settlement out of `cli-core.ts`. Ordinary
+send/respond/approve dispatch, deferred foreground transfer state machines,
+native lifecycle policy, monitor polling and callback transport remain in their
+existing owners. The composition root keeps the narrow callback-outbox
+preparation closure and routes the old helper names through one invocation-safe
+facade.
+
+Measured against exact parent `9156a7d45c28b8d9a428fbd048c46cf2226d56aa`,
+the slice reduces `src/cli-core.ts` from 16,350 to 14,390 physical lines
+(-1,960) and changes total production TypeScript from 86,473 to 87,562 lines
+(+1,089, 55.56% of the core movement). The three-module ownership domain has five
+targeted integration witnesses. Architecture validation reports 98 production
+modules, 515 static import edges, and zero cycles.
+
+The 410-line repository adapter is the sole owner of dispatch-ledger filesystem
+paths, raw bytes, legacy/canonical filenames, the dual lock set, file modes,
+directory fsync, and atomic replace. Its 321-line/c1 factory is a reviewed
+exception to the preferred 100-line function target; its largest inner
+operation is the 73-line/c18 save. The 791-line recovery service exposes exactly
+five typed port groups (`transaction`, `authority`, `evidence`, `state`, and
+`completion`), has a 47-line maximum function and c12 maximum complexity, and
+imports no Node filesystem/path API, CLI core, Store/session persistence, raw
+lock or JSON helper, `Record<..., any>`, full resolved terminal, or terminal
+adapter capability. The 1,848-line CLI transaction adapter owns path projection,
+Session/event reads, Store-writer and state locking, callback preparation, and
+legacy record validation. Its largest function is 77/c17. The reviewed
+complexity exception is the 37-line/c30 exact ledger-receipt predicate; every
+function remains below the hard 500 LOC/c50 gates, and the facade factory is
+24/c1.
+
+Repository compatibility remains fail closed. A canonical terminal acquires
+the canonical and legacy send locks in lexical order and releases them in
+reverse order through an idempotent closure. Reads reject symlinks and non-files
+without following the final path and reject simultaneous canonical/legacy
+owners. A validated legacy ledger is renamed to its canonical owner and the
+directory is synced before the next version-2 replace. Every replace creates a
+0600 exclusive temporary file, writes the exact pretty-JSON-plus-newline bytes,
+fsyncs the file, renames, reapplies 0600, fsyncs the directory, and removes any
+temporary artifact. Receipt history remains append-preserving across migration
+and settlement; a failed conversation/message CAS leaves the original bytes
+unchanged. Restoring a prior durable generation replaces the top-level document
+while retaining its append-only receipt history, so the abandoned generation
+cannot leak a self-referential `previous_generation_id`.
+
+Recovery retains `terminal dispatch lock -> Store writer lease -> Turn state
+lock`. Prepared keep decisions do not sample the clock, and owner mismatch
+returns before Store/binding projection. Prepared recovery resolves only when
+durable evidence proves zero input was possible; text-injected,
+Enter-dispatched, submitted, accepted, and uncertain proof is reconciled
+without terminal replay. Fresh verified-dead recovery applies the basic ledger
+fence first, then short-circuits state, Store, full ledger, receipt, and
+acceptance observations in order. It reuses or observes one process-death proof
+and lets a newly observed durable completion win before writing stall evidence.
+Stall persistence remains `death event -> stalled event -> crash fence -> state
+-> runtime log`. Completion preparation releases the state lock while retaining
+terminal and writer ownership; a failed release is retried by the enclosing
+transaction cleanup before writer and terminal release. Local completion
+verifies the exact claim, detected event,
+message event, accepted submission, and ledger before `resolve ledger -> settled
+event`. Reload, projection, and callback errors still unwind state, writer, then
+terminal ownership.
+
+Direct fast evidence fixes legacy promotion, canonical bytes and 0600 mode,
+receipt preservation, canonical/legacy conflict rejection, dangling-symlink
+rejection, dual-lock cleanup, failed-CAS byte identity, verified-dead completion
+and stall write order, callbackless settlement idempotence, zero-input-only
+prepared resolution, no replay surface, five-port boundary hygiene, and all-lock
+cleanup after a locked reload failure. It also fixes replacement-document
+Object keys and bytes, lazy-observation call counts and reason strings, and a
+release-error retry. Existing dispatch recovery, receipt
+fence, control-lock, monitor recovery, and human-handoff suites remain the
+black-box boundary set.
+
+## Terminal runtime and provider CLI composition
+
+The runtime/provider slice moves command-scoped terminal-control provider
+selection, process-source selection, Codex/Claude adapter registry composition,
+bridge construction, Claude `agents --json --all` observation, running-agent
+version observation, and provider-owned takeover decoding into
+`terminal-runtime-cli-adapter.ts`. Exact-bound Codex completion policy, native
+identity resolution and assertion, Store-backed runtime identity, durable
+request construction, endpoint refinement, legacy migration, acceptance,
+dispatch, monitor, lifecycle, callback, and deferred foreground work remain in
+their existing owners and enter this adapter only through typed callbacks.
+
+The factory receives five invocation-local groups: options, async-local command
+dependencies, completion callbacks, opaque identity callbacks, and workspace
+validation. It retains no mutable global provider or dependency state. Bridge
+defaults are still evaluated lazily in provider -> agent registry -> process
+source order. Injected providers and sources still win before static fixtures;
+the original option truthiness rules are unchanged. Concrete raw JSON parsing
+and `spawnSync` calls stay in this CLI infrastructure adapter rather than
+crossing a service boundary. Claude keeps the exact
+`agents --json --all` argv, status/error handling, invalid-JSON diagnostics,
+required-observation refusal, and row normalization order. Running-version
+observation keeps injected -> per-PID fixture -> per-agent fixture -> exact
+`lsof` executable-path evidence priority.
+
+Against exact parent `779e2e5d15ff18c5b8d0c5bbb7493e601f06cfb3`, the
+required top runtime movement plus the independent agent-version adapter reduce
+`src/cli-core.ts` from 14,390 to 13,935 physical lines (-455). Production
+TypeScript changes from 87,562 to 87,718 lines (+156, 34.29 percent of the core
+reduction), meeting the preferred overhead target and remaining below the 518
+lines of gross responsibility movement. The graph has 48 domains, 99 modules,
+526 edges, and zero cycles. The generated adapter declaration has no `any`,
+`Record<..., any>`, or `ResolvedTerminalConversation`; the module imports no
+Store, identity-authority, acceptance, dispatch, monitor, lifecycle, callback,
+or deferred module. Every adapter function is below 100 physical lines and
+approximate complexity 20; the maxima are 47 lines and c15.
+
+Direct fast proofs lock factory laziness and instance isolation, exact provider
+-> registry -> process-source getter order, injection/static truthiness,
+exact-bound completion short-circuiting, Claude subprocess argv and fail-closed
+errors, agent-version precedence, and tmux/Herdr takeover decoding. Its targeted
+owner selects five retained CLI witnesses spanning Claude native inspection,
+facade import laziness, lifecycle versioning, send gating, and native Session
+acceptance. The 8,997-line Codex no-rollout fixture is deliberately excluded:
+these narrower witnesses cover this composition boundary without selecting the
+integration tier's dominant runtime for every adapter edit.
+
+## Native acceptance and managed Turn application
+
+The acceptance slice moves native acceptance composition, virgin Codex
+post-submission binding recovery, monitor acceptance reconciliation, uncertain
+settlement, managed Session identity refinement, managed Turn queries, and
+managed Turn construction out of `cli-core.ts`. The new CLI adapter composes the
+existing `TerminalDispatchExecutionService`, terminal-submission detectors,
+receipt merger, deferred-foreground recovery owner, and terminal-dispatch
+repository/recovery facades. Ordinary ledger locking, reads, and writes are
+projected directly from `terminalDispatchRepository`; prepared reconciliation
+and binding proof are projected directly from `terminalDispatchRecovery`. It
+obtains the command-local terminal runtime lazily and uses its existing Claude
+row and bridge ports instead of rebuilding provider composition. It does not
+copy acceptance scanning, receipt ranking,
+ledger repair, authority tokens, or deferred-transfer reducers.
+
+`TerminalAcceptanceApplicationService` owns the ordered
+recover -> detect -> optional second recovery -> second detect -> exact draft
+proof -> commit decision. `ManagedTurnRecoveryService` owns the monotonic virgin
+binding sequence: validate literal facts, resolve the exact identity, require
+the canonical acceptance detector when neither side was committed, prove
+exclusive ownership, commit Session identity, commit Turn identity, then
+revalidate the Turn. Both services receive at most five typed port groups and
+import no filesystem, path, Store/session repository, raw lock, raw JSON,
+`Record<..., any>`, `ResolvedTerminalConversation`, or terminal adapter
+instances.
+
+The CLI adapter retains the concrete resource discipline. Virgin recovery is
+terminal lock -> Store writer -> Turn state lock; monitor acceptance already
+holds the same terminal lock and therefore enters only writer -> state. Final
+acceptance writes Turn state before best-effort ledger and event bookkeeping,
+while uncertainty retains the legacy ledger -> Turn state -> event durable
+order. An `enter_dispatched` Turn with possible input never enters a replay or
+zero-input abort path: absent acceptance stays pending unless the exact draft
+is still present, in which case it becomes durable `not_accepted` with
+`do_not_retry` authority.
+
+Managed Turn construction retains the original insertion order and exact
+storage-path suffix, binding id/generation, native identity, endpoint evidence,
+message metadata, and optional deferred transfer id. The public adapter
+declaration contains neither `any`, `Record<..., any>`, nor
+`ResolvedTerminalConversation`; deferred operations cross only the structural
+`TerminalDispatchTerminal` carrier.
+
+Measured against exact parent
+`6318a3bbff2ec0aa10baa3ada8313d1eed038bd2`, this slice reduces
+`src/cli-core.ts` from 13,935 to 12,721 physical lines (-1,214) and changes
+production TypeScript from 87,718 to 88,732 lines (+1,014). The typed overhead
+is 83.53 percent of core movement and remains 200 lines below the hard
+movement ceiling; it does not meet the preferred 450-line overhead target, so
+that tradeoff is explicit. The production graph has 49 domains, 102 modules,
+559 static import edges, and zero cycles. `cli-core.ts` retains one production
+importer, and the acceptance owner retains exactly five integration witnesses.
+
+All extracted functions remain below the hard 500-line/c50 gates. The two
+reviewed preferred-target exceptions use the documented nested-function-
+excluding complexity method: `#recoverVirginLocked` is 104 physical lines/c2,
+and `attachManagedTurn` is 75 lines/c23. Every business-service function stays
+below 100 lines and c20.
+
+The direct evidence fixes the critical boundaries:
+
+| Contract | Direct proof | Focused real-CLI proof |
+| --- | --- | --- |
+| Virgin acceptance order and split CAS recovery | recording ports prove detector -> ownership -> Session -> Turn -> revalidation and both one-sided crash continuations | no-rollout binding and Session-acceptance shards |
+| Possible input never replays | application table proves pending without exact draft and `not_accepted` only with exact draft | Session acceptance and terminal-send gates |
+| Terminal -> writer -> state and durable write order | compiled facade wiring checks both lock stacks plus accepted and uncertain writes | monitor-recovery and no-rollout binding |
+| Managed Turn JSON shape | direct exact key/order/binding/message projection | handoff and Session-acceptance shards |
+| Data-only service boundary | declaration/source prohibition test and at-most-five-group typed ports | all five owner witnesses traverse the production facade |
+
+The five focused witnesses are Codex no-rollout binding, human handoff,
+monitor recovery, Session acceptance, and terminal send gates. Together they
+cover virgin and deferred acceptance, process drift/quarantine, crash recovery,
+uncertainty, Turn construction, and no-replay behavior without assigning
+lifecycle, callback, or generic ledger-recovery ownership to this slice.
+
+## Terminal identity authority CLI composition
+
+The identity-authority slice moves the exact 37-function inventory for terminal
+routing, process-incarnation and verified-dead observation, managed Session
+logical/native identity, Codex companion and pre-materialization fences,
+binding selection/conflict/materialization/reattach, and verified-empty deferred
+authority observation out of `cli-core.ts`. It deliberately leaves submission
+acceptance refinement/persistence/quarantine, current-native-identity polling,
+managed Turn creation, deferred detach/adoption state machines, repository,
+monitor, callback, and lifecycle mutation in their existing owners.
+
+Against exact parent `918812c5b541d5586595c4ea793df370f538d3e4`,
+`src/cli-core.ts` falls from 12,721 to 11,468 physical lines (-1,253). Total
+production TypeScript changes from 88,732 to 89,156 (+424, 33.84 percent of the
+core movement), below the preferred 450-line overhead target. Architecture
+validation reports 50 domains, 104 production modules, 589 static import edges,
+and zero cycles. The factory has four explicit invocation-scoped groups
+(`runtime`, `store`, `authority`, and `environment`) and exports no singleton or
+mutable process-global runtime. The composition root projects provider ports
+directly from `terminalRuntime(options)` and acceptance-owned identity/Session
+ports directly from `terminalAcceptanceCliFacade`; it adds no interim owner.
+
+The 78-line data-only service receives only projected native identity, process
+incarnation, companion, revision, status, and binding-token facts. It imports no
+filesystem/path/process-source, Store, managed Session, resolved terminal, raw
+JSON, lock, or `Record<..., any>` API. It owns only the moved exact-lifecycle
+fallback, deterministic companion uniqueness, and verified-empty snapshot
+comparison. The 1,599-line CLI adapter retains provider/process observation,
+Store reads, one managed-Session CAS reattach write, and explicit terminal
+projection. It reuses `terminal-binding-authority`,
+`terminal-authority-policy`, `terminal-dispatch-execution`, action projection,
+lifecycle verification, submission acceptance, verified-dead policy, and the
+runtime provider rather than copying rollout, fence, token, companion,
+status-card, or transition reducers.
+
+Observation and mutation order remain fail closed. Exact bound-process proof
+short-circuits envelope, binding, then accepted-submission evidence before
+consulting the complete process inventory. Stored status-card identity remains
+preferred only under the committed companion/predecessor fence. Codex process
+birth lookup stays lazy, and Claude still rejects a missing process UUID before
+any fallback. Raw reattach performs exclusive-ownership observation, reloads
+the exact Session, revalidates revision plus binding token, then writes one
+generation-incremented Session CAS. Verified-empty handoff checks the initial
+snapshot, process incarnation, absent native identity, terminal status and
+dispatch readiness, then reloads and revalidates the Session before transition
+and composer gates. No new lock or durable-file order is introduced.
+
+Every new function meets the preferred limits: the maximum adapter span is 95
+lines and the conservative maximum approximate complexity is c17; the service
+is smaller. Direct fast proofs cover malformed/fail-closed facts, deterministic
+companion selection, lazy process-birth lookup, parallel async-execution
+isolation, the four-group factory boundary, and service infrastructure hygiene.
+Five retained focused witnesses cover no-rollout/status-card binding, observed
+handoff/verified-empty authority, native lifecycle identity, Session acceptance,
+and terminal-send gates. The remaining exact-bound completion detector and
+requirement predicate stay with completion/recovery composition; endpoint
+refinement, Store-backed runtime identity, durable request construction, and
+legacy identity migration remain a later minimal identity-facade prerequisite
+rather than being duplicated here.
+
+## Terminal runtime prerequisites and exact completion authority
+
+The follow-up prerequisite slice closes that deliberately deferred inventory.
+The single exact-bound Codex completion detector and requirement predicate now
+live in `terminal-dispatch-completion-cli-adapter.ts`; neither the raw dispatch
+repository nor recovery adapter imports it. The detector retains
+accepted-submission -> exact-required -> Codex-source -> exact-anchor -> bound
+rollout detection order, while its synthetic-acceptance switch is read lazily
+from the invocation-local CLI environment. Exact completion still uses the one
+`detectCodexBoundRolloutCompletion` implementation and preserves request-hash
+fallback, byte identity, diagnostics, pending behavior, and completion metadata.
+
+Endpoint refinement, Store-backed runtime identity, durable request projection,
+and legacy terminal-agent identity migration are now methods of the existing
+identity facade. The earlier temporary `runtimeIdentity` and `durableRequest`
+callback ports are gone. A fifth typed completion group supplies only the exact
+requirement predicate. Runtime identity still checks binding id, generation,
+native thread, PID, terminal incarnation, and committed Codex companion fences
+before expanding its authority. Durable requests continue to prefer takeover
+request text and metadata. Endpoint refinement associates and saves only
+canonical evidence for the same terminal incarnation.
+
+Legacy migration is split into observation, locked persistence, and reporting
+functions. Only provider/process observation is downgraded to a warning. The
+state lock still encloses reload, revalidation, and save; every path releases it
+in `finally`. A successful save is followed, outside that lock, by durable event
+append and then runtime logging. Save and event failures propagate. The runtime
+facade also owns Codex Session-provider selection and active-Session terminal
+attachment, preserving injected-provider and injected-adapter precedence,
+fixture truthiness and JSON parsing, production Store fallback, and the original
+provider/process-source/bridge construction counts.
+
+Against exact parent `6c83f9efe5b3201c584db3ad2b50cd9e120310ad`,
+`src/cli-core.ts` falls from 11,468 to 11,066 physical lines (-402). Production
+TypeScript changes from 89,156 to 89,264 lines (+108, 26.87 percent of the core
+reduction), below the preferred 160-line overhead target and the 240-line hard
+cap. Architecture validation reports 51 domains, 105 production modules, 596
+static import edges, and zero cycles. The three changed facade declarations
+contain no `any`, `Record<..., any>`, or `ResolvedTerminalConversation`. New
+functions are below 55 physical lines and approximate c20; the expanded identity
+facade retains its pre-existing 95-line/c17 maxima, below both hard limits.
+
+Direct fast proofs cover dynamic synthetic environment lookup; accepted, source,
+anchor, and real byte-detector order; exact binding/generation/thread/PID/
+incarnation and companion fences; takeover-first durable requests; canonical
+endpoint save; observation-only warning behavior; lock/reload/save/unlock/event/
+log order; save and event error propagation; provider injection, fixture
+truthiness, JSON validation, and active provider/source/bridge call counts. Four
+targeted integration witnesses retain exact monitor recovery, Session acceptance,
+terminal send gates, and import-time facade wiring.
+
+## Native lifecycle context, listing, and inspection CLI composition
+
+The native-lifecycle Vertical A slice moves the exact 21-function inventory for
+binding tokens, lifecycle terminal resolution, query-port composition,
+workspace and exclusive-ownership observation, current lifecycle snapshots,
+resumable-thread listing, and the closed native status inspection out of
+`cli-core.ts`. It also moves terminal Store-authority and orphan projections
+behind the typed dispatch-recovery facade and keeps Codex latent-clear parsing,
+composer checks, and candidate-provider precedence in one command-scoped CLI
+adapter. Native new/resume/reconcile transition, recovery, verification,
+settlement, deferred handoff, acceptance, callback, and monitor state machines
+remain in their existing owners.
+
+Against exact parent `81feac294d5a62ea8309c6e96a66c042ebf239b8`,
+`src/cli-core.ts` falls from 11,066 to 9,868 physical lines (-1,198). Total
+production TypeScript changes from 89,264 to 89,498 (+234, 19.53 percent of the
+core movement), below the preferred 350-line and hard 550-line overhead limits.
+Architecture validation reports 51 domains, 106 production modules, 615 static
+import edges, and zero cycles. The factory has exactly five explicit,
+invocation-scoped groups (`runtime`, `identity`, `state`, `terminalList`, and
+`output`) and exports no mutable singleton. Codex lifecycle-candidate selection
+delegates directly to the runtime facade's dedicated provider factory, retaining
+the invocation-local override before production Store fallback.
+
+`currentSnapshot` is the only lifecycle snapshot sequencer. It resolves the
+claimed Codex companion context through `terminalIdentityAuthority`, observes
+the current native identity through `terminalAcceptanceCliFacade`, selects or
+materializes the managed Session, refines it through the acceptance owner when
+requested, derives the logical identity and companion set through the identity
+facade, performs exclusive ownership before returning a frozen data-only
+snapshot, and never returns a terminal adapter. Vertical B requests adapter
+behavior separately through the facade, so no full terminal or executable
+capability leaks into snapshot facts.
+
+Native inspection retains the exact safety boundary: the terminal lock remains
+held through output presentation; `/status` is the only accepted plan; Enter is
+dispatched exactly once; a fresh terminal, binding token, agent version,
+identity, ownership, readiness, and composer are revalidated immediately before
+Enter; two consecutive fresh observations with the same evidence fingerprint
+are required; modal dismissal revalidates the same facts immediately before its
+single key sequence; and final status plus empty-composer proof precedes output.
+Only a pre-input `NativeInspectionSubmissionError` remains safely retryable;
+possible input and every post-Enter uncertainty retain the do-not-retry result.
+
+The TypeScript compiler AST inventory contains 68 functions in the new adapter;
+every one stays below the preferred limits (maximum 64 physical lines and
+approximate complexity c14). Direct evidence
+fixes canonical and legacy binding-token bytes plus double getter order,
+snapshot sequencing and exact data-only keys, one-Enter/two-observation/final-
+revalidation ordering with lock-held presentation, parallel async provider
+isolation, the five-group factory boundary, and declaration/core forbidden
+patterns. The four focused witnesses are Claude native inspection,
+native-thread lifecycle, native ownership, and the Codex no-rollout native-
+inspection cases.
+
+## Deferred foreground and observed handoff CLI facade
+
+This slice moves the exact 23-function deferred/verified-empty/observed-handoff
+inventory (1,733 physical function-span lines) out of `cli-core.ts`. It owns
+safe-aborted deferred retry validation, verified-empty detach and transport
+boundaries, deferred preparation/application/recovery composition, observed
+handoff token/selector/target/adoption/transport boundaries, and nonterminal
+transfer guards. Ordinary replay, deferred reducers and repositories,
+submission acceptance, identity authority, lifecycle commands, callbacks,
+monitoring, and `runObservedHandoffClose` remain with their existing owners.
+
+Against exact parent `d4cb4f108ce240a006c7eebb56e2ce5cc9d70c3f`,
+`src/cli-core.ts` falls from 9,868 to 8,119 physical lines (-1,749). Total
+production TypeScript changes from 89,498 to 89,873 (+375), meeting the
+preferred 450-line overhead target and the 1,650–1,850 core-reduction target.
+Architecture validation reports 52 domains, 109 production modules, 643 static
+import edges, zero cycles, and one retained `cli-core.ts` importer. The new
+owner has three modules and exactly five focused integration witnesses.
+
+`terminal-handoff-facts.ts` and `TerminalHandoffApplicationService` own only
+neutral zero-input chronology and ordered authority-thunk evaluation. They
+import no filesystem/path API, Store or Session repository, locks, raw JSON,
+full terminal object, or `Record<..., any>`. The CLI adapter retains concrete
+terminal, Session, ledger, and path translation. Its invocation-local factory
+has exactly five groups (`runtime`, `identity`, `acceptance`, `authority`, and
+`repository`); repository includes the already-authenticated transaction-shell
+operations. `identity` is the actual `terminalIdentityAuthority` facade type,
+not a copied identity port list. Acceptance observation and Turn checks remain
+direct projections of `terminalAcceptanceCliFacade`.
+
+The recovery seam is explicit for downstream lifecycle composition.
+`recoverDeferredCodexForegroundTransferBeforeMutation` is entered while the
+caller owns the exact terminal lock; it creates the canonical transaction scope
+with a no-op terminal acquisition, then acquires the Store writer lease.
+`recoverDeferredCodexForegroundTransferWhileWriterLease` accepts the resulting
+typed canonical scopes/resources, and only `withDeferredForegroundRecoveryScope`
+may add the conversation state capability. Transfers without a state path use
+the writer capability directly. Thus the retained order is terminal -> writer
+-> state, and no service reconstructs a raw lock or held-lock flag. Fresh
+handoff identity/status observation is exposed as the invocation-scoped
+`observedExternalHandoffIdentity`; known roots and companions remain the
+invocation-scoped `terminalIdentityAuthority` operation rather than being
+reconstructed here.
+
+Safe retry remains fail closed. Only an exact `aborted` receipt with
+`safe_to_retry=true`, zero-input chronology, canonical state/log paths, exact
+terminal route and process incarnation, one byte-identical canonical receipt,
+matching request hash, resolved zero-input ledger, and exact restored Session
+CAS authority may retry. A possible-input stage never takes this route.
+Verified-empty detach revalidates the source snapshot and identity boundary
+before its Session CAS. Observed adoption retains the durable order `prepared
+transition -> prepared ledger -> source transitioning -> fresh observation ->
+verified transition -> verified ledger -> Session commit -> committed
+transition -> resolved ledger`. Once the durable transition is verified or
+committed, catch handling rethrows and never downgrades it to uncertain.
+
+The two previously over-complex boundaries are now below the hard gate:
+safe-aborted retry is 148 lines/c9 and observed-handoff transport is 166/c28.
+The reviewed preferred-target exceptions are:
+
+| Function | LOC / approximate complexity |
+| --- | ---: |
+| `maybeAdoptObservedExternalThread` | 322 / c35 |
+| `assertObservedHandoffTransportBoundary` | 166 / c28 |
+| `prepareDeferredCodexForegroundBinding` | 152 / c2 |
+| `safeAbortedDeferredRetrySourceSession` | 148 / c9 |
+| `recoverDeferredCodexForegroundTransferWhileWriterLease` | 123 / c1 |
+| `maybeDetachVerifiedEmptyCodexSource` | 104 / c9 |
+
+Direct fast evidence records parallel factory/capability isolation, selector
+WeakMap isolation, getter and original-error priority, zero-input chronology,
+canonical receipt/hash/route byte ordering, monotonic handoff writes,
+verified-state non-downgrade, terminal/writer/state capability order, neutral
+service imports, and direct identity-facade composition. The five retained
+focused witnesses are Codex no-rollout binding, human handoff adoption,
+dispatch recovery, Session acceptance, and terminal-send gates. They cover the
+real verified-empty, deferred crash/retry, observed adoption, acceptance, and
+pre-input transport paths without assigning lifecycle, callback, monitor, or
+ordinary replay ownership to this facade.
+
+## Callback CLI and outbox composition facade
+
+The callback CLI slice moves the exact nine-function command, transaction,
+outbox-composition, prepared-result presentation, process-delivery recording,
+and OpenClaw transport inventory out of `cli-core.ts`. The new
+`callback-cli-adapter.ts` remains raw CLI infrastructure: it delegates every
+callback transition to the existing callback outbox service, settlement,
+policy, and OpenClaw transport owners and introduces no callback state machine.
+The outbox service boundary changes only mechanically from six port groups to
+five by placing `resolveCompletionDispatch` beside the other authority ports.
+
+Against exact parent `0c2d4258094f47302bc8265eb98d4a05f5b44305`,
+`src/cli-core.ts` falls from 8,119 to 7,941 physical lines (-178). Total
+production TypeScript changes from 89,873 to 89,933 lines (+60, 33.71 percent
+of the core movement), meeting the preferred 60-line overhead target and the
+120-line hard cap. Architecture validation reports 52 domains, 110 production
+modules, 651 static import edges, and zero cycles. The 240-line adapter has four
+invocation-scoped groups (`state`, `authority`, `retry`, and `runtime`), exports
+only its factory at runtime, and uses async-local binding rather than mutable
+process-global configuration. Its declaration contains no `any`,
+`Record<..., any>`, or resolved-terminal capability.
+
+The transaction chronology is unchanged. A normal callback holds writer then
+state authority through required-message validation and outbox preparation,
+releases state then writer, and only then performs delivery and presentation.
+A manual retry loads its selected Turn, takes writer authority, reloads the
+fresh Turn, applies the canonical handoff facade's nonterminal-transfer fence,
+releases the writer, and only then enters accepted recovery or retry delivery.
+Settlement keeps its existing state transaction. Delivery never holds either
+outer lock. Fresh preparation retains message-before-path/Store validation and
+the existing message/event/monitor/state/runtime-log sequence; progress,
+accepted transport, success, failure, and bounded retry remain owned by the
+unchanged outbox service and settlement. Accepted transport followed by an
+observation error still settles as delivered. Process delivery still appends
+the redacted durable event before its redacted runtime log.
+
+All adapter functions stay within the preferred limits (maximum 34 physical
+lines and approximate c2, excluding nested function bodies). Direct recording
+tests prove writer/state release before presentation, fresh deferred fencing
+before retry, accepted-transport recovery, nested facade isolation, compiled
+lock and redaction order, the four-group boundary, factory-only exports, and
+declaration prohibitions. The focused real-CLI witnesses remain callback CLI,
+Claude callback, monitor approval context, and monitor recovery; they exercise
+ordinary and recovered single emission, retry, completion/approval preparation,
+transport acceptance, and monitor consumption without duplicating callback
+authority.
+
+## Native lifecycle transition application
+
+This slice moves the exact 13-function native lifecycle transition inventory
+(1,344 physical function-span lines) out of `cli-core.ts`. The new
+`native-thread-transition-application.ts` owns new-thread, exact resume,
+binding reconciliation, pre-mutation lifecycle recovery, transition
+settlement composition, and terminal-ready verification. The separate
+`native-thread-lifecycle-ledger-cli-adapter.ts` owns exact lifecycle ledger CAS
+against the existing terminal-dispatch repository. Candidate query,
+verification, settlement, recovery, ledger codec, identity, acceptance, and
+Session repositories remain with their existing owners; no reducer or
+repository is copied.
+
+Against exact parent `98e3566f0e15e4a6ff0ffff6efa85cdde532ee77`,
+`src/cli-core.ts` falls from 7,941 to 6,483 physical lines (-1,458). Total
+production TypeScript changes from 89,933 to 90,578 (+645), inside the hard
+650-line overhead gate. Architecture validation reports 52 domains, 112
+production modules, 669 static import edges, zero cycles, and one retained
+`cli-core.ts` importer.
+
+The invocation-local CLI bounded I/O shell composes exactly five port groups
+(`runtime`, `lifecycle`, `state`, `authority`, and `mutation`). It extends the
+existing lifecycle query facade at the CLI composition root. Observed handoff
+identity and writer-scope deferred recovery call the merged terminal-handoff
+facade directly; verified-empty detach and transport continue through that
+same facade. Recovery services receive only projected terminal facts plus scoped
+capabilities. Binding reconciliation likewise receives data-only terminal and
+status facts, while the CLI adapter retains the exact runtime terminal needed
+for subsequent infrastructure calls.
+
+The mutation sequence remains terminal lock -> Store writer lease. A fresh
+terminal route is re-resolved after both capabilities are authenticated.
+Resume snapshot expiry, action fingerprint, and the complete candidate set are
+revalidated before persistence and again at their mutation-adjacent fences.
+The durable order remains prepared transition -> prepared ledger -> source
+transitioning -> dispatching transition/ledger -> input -> submitted
+transition/ledger -> verification -> verified transition -> target ownership
+-> Session commit -> committed transition -> resolved ledger -> presentation.
+Presentation therefore remains inside both locks. Only a
+`TerminalInputNotStartedError` with no text-injection observation can take the
+zero-input abort path; possible input remains uncertain, quarantined, and
+do-not-retry.
+
+Compiler-AST evidence covers every function-like declaration in the new
+application. The maximum span is 445 physical lines and maximum approximate
+complexity is c44, below the hard 500/c50 gates. Direct tests record exact
+ledger load/authority/save precedence, scoped recovery resources, verified
+commit and uncertain failure order, resolved-ledger-before-presentation, and
+presentation before writer/terminal lock release. Fast and focused lifecycle,
+recovery, ownership, Codex sticky-rollout, and stale-resume witnesses retain
+the real CLI behavior.
+
+## Terminal monitor state and collateral CLI facade
+
+This slice moves the exact 14-function monitor state inventory plus its
+adjacent durable state/fact preparation out of `cli-core.ts`: uncertain-dispatch
+collateral fencing and repair evidence, approval notification persistence and
+clear, activity and detector diagnostics, stalled-state notification,
+callback/local-completion recovery, startup eligibility, and monitor service
+port composition. The state facade deliberately does not absorb process-owner
+inspection, legacy-owner decisions, watchdog supervision, monitor launch, or
+launch-event presentation. Those responsibilities now belong to the subsequent
+terminal monitor supervision facade documented below, rather than
+`cli-core.ts`.
+
+Against exact parent `240732e4d0a654abb4f88a01020bd93734f0d020`,
+`src/cli-core.ts` falls from 6,212 to 4,547 physical lines (-1,665). Total
+production TypeScript changes from 90,711 to 91,535 lines (+824, 49.49 percent
+of the core movement), so production overhead remains below the moved core.
+Architecture validation reports 54 domains, 115 production modules, 712 static
+import edges, zero cycles, and one retained `cli-core.ts` importer.
+
+`terminal-monitor-state-reconciliation-service.ts` is data-only and has four
+port groups (`state`, `completion`, `callbacks`, and `authority`). It imports no
+filesystem/path API, raw lock, Store, Session, resolved terminal, raw JSON, or
+`Record<..., any>`. Its reconciliation order remains local completion ->
+callback recovery -> terminal-bridge filter -> legacy identity migration ->
+verified-dead settlement -> deferred recovery -> virgin acceptance recovery ->
+binding assertion -> eligibility. Handled local, callback, dead-process, and
+ineligible results stop every later observation.
+
+The CLI adapter has exactly five dependency groups (`dispatch`, `acceptance`,
+`authority`, `callbacks`, and `runtime`). It calls the merged
+`callbackCliFacade`, terminal-dispatch repository/recovery,
+`terminalAcceptanceCliFacade`, `terminalHandoffCliFacade`, and identity
+authority directly; it contains no copied callback, deferred, acceptance, or
+dispatch reducer. Command-selected Store authority is retained for terminal
+send locks, while state-path-derived Store authority is retained for writer
+leases, collateral repair, and verified-dead settlement.
+
+The existing monitor application still samples one poll snapshot for status
+and screen facts. Prepared recovery preserves terminal -> writer -> state lock
+order; presentation stays inside the required lock scope. Approval state is
+saved before its event and outbox preparation, duplicate/recovery reads retain
+their original order, and approval/stalled callback delivery begins only after
+the state and writer locks release. Verified-dead completion calls the canonical
+prepared callback exactly once. Superseded binding remains a non-error skip,
+the subsequent supervision facade directly classifies raw `LOCK_TIMEOUT` for
+only its handoff and singleton process locks, and state/application deferral
+retains typed `StoreLockTimeoutError` plus the existing raw
+terminal/conversation timeout path.
+
+All new functions remain below the hard 500-line/c50 gates. The transparent
+preferred-limit exceptions are the 209-line/c1 service-port composition table,
+the 122-line/c47 fail-closed collateral evidence predicate, and its
+64-line/c22 exact owner predicate; splitting either evidence predicate would
+obscure its ordered short-circuit proof. The data-only service maximum is
+63 lines/c8. Direct fast tests record resource identity and post-scope data,
+exact port/getter/error order, optional zero/null fields, prepared completion
+byte facts, canonical facade wiring, four/five-group declarations, and
+forbidden imports. The five focused CLI witnesses are Claude callback, monitor
+approval context, monitor lifecycle, monitor recovery, and Session acceptance.
+
+## Maintenance command facade
+
+The renew, raw/managed cancel, observed-handoff close, generic managed close,
+and orphan/lifecycle dispatch-close slice now lives in
+`terminal-maintenance-cli-adapter.ts`. The adapter is a bounded CLI I/O shell;
+it composes the existing terminal identity, acceptance, handoff, list, native
+lifecycle, dispatch repository, and verified-dead recovery authorities rather
+than copying a reducer, receipt, repository, or CAS transition. The subsequent
+terminal monitor supervision facade owns monitor process supervision, monitor
+reconciliation, and startup reconciliation. Maintenance routes its monitor
+start and lock-version facts through that typed facade; ordinary delegate/send
+presentation remains with its existing owner.
+
+Against exact parent `8683b42c248b2310c59165ba712ecc943da3d775`,
+`src/cli-core.ts` falls from 4,547 to 3,419 physical lines (-1,128). Total
+production TypeScript changes from 91,535 to 91,961 lines (+426, 37.77 percent
+of the core movement), meeting the preferred 450-line and hard 650-line
+overhead gates. Architecture validation reports 54 domains, 116 production
+modules, 742 static import edges, zero cycles, and one retained `cli-core.ts`
+importer. The now 1,555-line adapter exposes only its factory at runtime and binds
+four invocation-scoped port groups (`runtime`, `identity`, `authority`, and
+`repository`) through async-local context. Its public option surface is
+`Readonly<Record<string, unknown>>`; its source and declaration contain no
+`any`, raw JSON codec, or resolved-terminal capability API.
+
+Renew preserves selector/migration, status, verified-dead and uncertain-submit
+fences before terminal availability, then reloads under its state lock,
+revalidates binding and hard lifetime, persists state before the renewal event,
+and launches/presents only after releasing state. Raw cancel takes terminal
+then writer authority. Managed cancel preserves its distinct authorities:
+the command-selected Store keys only the terminal lock, the state-file lock is
+second, and the state-path-derived Store keys the writer lease third. It
+releases writer -> state -> terminal. Its fresh Turn, terminal incarnation,
+exact dispatch owner, bridge cancellation, event, state, and presentation order
+is unchanged, and presentation stays inside the authenticated transaction.
+
+Observed-handoff close retains terminal -> writer -> state, fresh Turn and
+Session loads, native identity observation, exclusive target ownership, exact
+handoff token and dispatch-generation validation, then Turn save -> ledger
+resolve -> close event -> presentation. Generic close keeps its observed
+handoff fence and verified-dead completion-first recovery, persists the closed
+Turn before dispatch resolution and the append-only close event, and presents
+only after those effects. Orphan/lifecycle dispatch close continues to
+reconcile incarnation and deferred-transfer authority before lifecycle
+recovery or exact message-id resolution. Possible terminal input is never
+retried or downgraded.
+
+Every extracted function remains below the hard 500/c50 gates. The cohesive
+CLI-shell exceptions to the preferred 100/c20 target are:
+
+| Function or nested transaction | LOC / approximate complexity |
+| --- | ---: |
+| `runClose` | 264 / c8 |
+| generic close fresh-state transaction | 205 / c24 |
+| `runRenew` | 192 / c32 |
+| dispatch-close transaction | 184 / c22 |
+| observed-handoff close transaction | 176 / c29 |
+| `assertGenericCloseDoesNotBypassObservedHandoff` | 138 / c19 |
+
+Direct recording tests prove concurrent factory isolation, factory-only
+exports, typed declarations, raw-cancel reverse release, managed-cancel
+terminal/state/writer order with distinct command/state Store keys, every
+acquire/release error priority, and the getter/error/persistence tables for all
+three commands. The five focused files are the maintenance facade, control
+locks, monitor lifecycle, human-handoff adoption, and native lifecycle
+recovery witnesses; together they retain real CLI cancel/close races, renew,
+verified-dead completion, observed handoff, and exact lifecycle ledger
+recovery.
+
+## Terminal monitor supervision CLI facade
+
+This slice moves 16 named monitor process-supervision functions spanning 706
+physical function-span lines, plus the
+`DEFAULT_MONITOR_POLL_INTERVAL_MS` constant, out of `cli-core.ts` into
+`terminal-monitor-supervision-cli-adapter.ts`:
+`spawnDetachedTerminalMonitor`,
+`startTerminalBridgeMonitorForConversation`,
+`ensureTerminalBridgeMonitorAfterApproval`, `runReconcileMonitors`,
+`reconcileMonitors`, `latestTerminalBridgeMonitorLaunchPid`,
+`prepareTerminalBridgeMonitorReconciliation`, `runMonitor`,
+`startCallbackRetryMonitor`, `runCallbackRetryMonitor`,
+`runTerminalBridgeMonitorHandoff`, `runTerminalBridgeMonitor`,
+`runTerminalBridgeMonitorWithLock`, `activeTerminalBridgeMonitorOwner`,
+`terminalBridgeMonitorLockOwner`, and
+`tryAcquireTerminalBridgeMonitorLock`. The adapter owns only the detached
+process shell, current/legacy process-owner supervision, watchdog retries,
+singleton monitor locks, launch presentation, and CLI command routing. Monitor
+state, acceptance, callback, deferred handoff, terminal-dispatch repository,
+and terminal runtime behavior continue through their canonical facades and
+services; no reducer or persistence protocol is copied.
+
+Against exact parent `cc69f520207e276a4f3a55b0a32dfeb179ea8095`,
+`src/cli-core.ts` falls from 3,419 to 2,735 physical lines (-684). Total
+production TypeScript changes from 91,961 to 92,432 lines (+471), below the
+hard 500-line overhead gate and below the moved core. Architecture validation
+reports 54 domains, 117 production modules, 750 static import edges, zero
+cycles, and one retained `cli-core.ts` importer. The adapter exposes only its
+factory at runtime. Every function remains within the preferred limits; the
+compiler-AST maximum is 59 physical lines and approximate c8.
+
+The invocation-local boundary has exactly five port groups: `state`,
+`callbacks`, `authority`, `io`, and `runtime`. `state` directly reuses
+`terminalMonitorStateCliFacade` for service execution, deferral, collateral
+repair, startup reconciliation, eligibility, and fresh launch preparation.
+The callback-retry command branch delegates directly to `callbackCliFacade`
+without acquiring a supervision lock. A normal callback reached through an
+owned monitor retains its message-generation singleton owner, but the existing
+callback/state adapters release state and writer locks before actual delivery.
+`authority` performs legacy identity migration and constructs the terminal
+bridge lazily.
+`io` binds detached spawn, the existing file-lock adapter, Store reads/events,
+and transcript reads. `runtime` supplies only invocation-scoped clock,
+environment, workspace, process-liveness, logging, and presentation facts.
+`loadTerminalDispatchLedgerOwner` and `assertManagedTerminalDispatchOwner`
+remain with dispatch/maintenance composition and were not moved into monitor
+supervision.
+
+Startup reconciliation retains the durable observation order: collateral and
+state-facade reconciliation first (local completion -> callback recovery ->
+migration -> verified-dead -> deferred -> virgin -> binding -> eligibility),
+then current owner before legacy owner, fresh launch preparation, detached
+spawn, and only after successful spawn the exit/launch events, runtime log, and
+counters. A failed or disabled spawn records no launch event. The approval path
+also observes the exact generation owner, prepares the process plan, spawns,
+and only then records reuse, watchdog, or launch presentation.
+
+The watchdog acquires its generation-specific handoff lock and performs a
+fresh Turn load on every retry; it never caches status, generation, owner, or
+launch preparation across sleeps. The owned monitor acquires its
+message-generation singleton lock before invoking
+`runTerminalMonitorWithStoreDeferral` and releases it in `finally`. Supervision
+directly classifies raw `LOCK_TIMEOUT` only while acquiring the handoff and
+message-generation singleton process locks. State/application deferral
+continues to classify typed Store timeouts and retains the existing raw
+terminal/conversation timeout path. The monitor configuration and terminal
+bridge remain lazy, so a replaced generation exits before timeout validation
+or effect initialization. Live owners stop duplicate launch, and dead owners
+are reclaimed by the canonical file-lock adapter. The monitor application
+service is the sole emitter of the `terminal_bridge_monitor_started` event and
+runtime log; command, receipt, and maintenance owners may still persist the
+separate `terminal_bridge_monitor_started_at` state field.
+
+Maintenance remains the owner of renew/cancel/close durable transitions. Renew
+persists state and its renewal event under the state lock, releases that lock,
+then calls the supervision facade's typed `startMonitor`; its persisted
+`terminal_bridge_monitor_lock_version` now comes from the same facade. This
+keeps the cross-module durable order state -> renewal event -> state-lock
+release -> spawn -> launch event. Cancel and close lock stacks and their
+dispatch authority are unchanged.
+
+The old black-box paths now have direct invariant witnesses:
+
+| Old behavior path | New direct invariant | Direct witness |
+| --- | --- | --- |
+| monitor plan, approval launch, and process isolation | entry/environment/cwd/spawn/unref order, secret stripping, current-owner reuse, spawn failure without an event, and parallel factory isolation | `terminal-monitor-supervision-cli-adapter.test.ts` |
+| renew starts monitoring after its durable state transition | maintenance uses typed `startMonitor` and the supervision-owned lock version without changing renewal/cancel lock order | `terminal-maintenance-cli-adapter.test.ts` |
+| startup state and collateral recovery precede process ownership | the existing state facade returns a data-only handled/candidate result before owner or launch observations | `terminal-monitor-state-reconciliation-service.test.ts` |
+| monitor generation and Store contention | generation replacement precedes lazy configuration/bridge construction, while Store timeout deferral does not duplicate monitor start | `terminal-monitor-application-service.test.ts` |
+| live/dead singleton ownership and startup restart | current and legacy owners stop duplicate launch, while the canonical lock shell reclaims an exact dead owner | `terminal-monitor-supervision-cli-adapter.test.ts` and `file-lock-cli-adapter.test.ts` |
+
+The configured focused integration witnesses remain exactly five shards:
+`test/shards/agent-cli-claude-callback.test.ts`,
+`test/shards/agent-cli-monitor-approval-context.test.ts`,
+`test/shards/agent-cli-monitor-lifecycle.test.ts`,
+`test/shards/agent-cli-monitor-recovery.test.ts`, and
+`test/shards/agent-cli-session-acceptance.test.ts`. They retain callback
+delivery, approval, monitor lifecycle, singleton/restart recovery, and
+Session-acceptance behavior through the real CLI boundary.
+
+## Status CLI facade and data-only facts
+
+The standalone status read, explicit status reconciliation, terminal context,
+Codex history projection, managed Turn summary, discoverability fact, and idle
+timeout reconciliation now live in `terminal-status-cli-adapter.ts` and
+`terminal-status-facts.ts`. The CLI adapter is the bounded Store/runtime I/O
+shell. The facts module is data-only and imports no filesystem/path API, Store,
+Session repository, lock, raw JSON codec, or `Record<..., any>`. List,
+terminal-command, identity, and runtime-completion composition use the same
+exported fact or typed facade operation; no selector, terminal action, monitor,
+or callback authority is copied.
+
+Against exact parent `afa09955b0c5bd528aaaa69cf4d4f92ed1f44079`,
+`src/cli-core.ts` falls from 2,735 to 2,122 physical lines (-613). This is the
+bounded fallback slice: the remaining shared state/path selection and runtime
+completion context stay at the composition root rather than absorbing
+maintenance, transcript, or monitor supervision merely to increase movement.
+Total production TypeScript changes from 92,432 to 92,904 lines (+472, 77.00
+percent of the core movement), below the hard 500-line overhead cap though not
+the preferred 300-line target. Architecture validation reports 55 domains, 119
+production modules, 772 static import edges, zero cycles, and one retained
+`cli-core.ts` importer.
+
+The adapter exposes only its factory at runtime and has four invocation-scoped
+port groups (`selection`, `observation`, `reconciliation`, and `projection`).
+It directly reuses the invocation-local CLI clock/output/log and the existing
+Store and trace infrastructure appropriate to a bounded CLI adapter. Default
+`status` performs no writable-Store assertion, state lock, save, event append,
+idle close, or monitor reconciliation. Only exact `--reconcile` first asserts
+the Store writable, then calls the narrow monitor-reconciliation port, then
+runs idle reconciliation and aggregates the two results.
+
+Terminal-control status retains selector-token fencing before bridge status,
+then historical context, JSON presentation, and the redacted runtime log.
+Managed status retains events -> summary/about/recent evidence -> optional
+trace -> terminal status ordering and its exact insertion order. Codex history
+prefers the active process session id, otherwise sorts matching-cwd sessions by
+descending update time, and finally reports screen-only evidence. Claude keeps
+the adapter display name and explicit historical-context limitation. Public
+options remain unknown-valued and the emitted declaration contains no `any` or
+resolved capability object.
+
+Idle reconciliation still observes the listed snapshot before acquiring the
+state lock, skips nonterminal candidate-rollout source Turns, treats raw
+`LOCK_TIMEOUT` as a skip, reloads the fresh Turn under lock, and rechecks fresh
+idle age. A close remains save -> append-only event -> runtime log, with the
+state lock released in `finally`. All 51 extracted function-like declarations
+meet the preferred 100/c20 target: adapter maxima are 60 lines and c12; facts
+maxima are 48 lines and c8. Direct tests cover concurrent factory isolation,
+factory-only exports and declarations, zero-write default status, parent-exact
+managed continuation and screen getter timing, non-Codex getter/error priority,
+terminal and managed JSON order, newest-cwd Codex fallback and default bounds,
+exact monitor aggregation, fresh idle locking/log getter order, and lock-timeout
+skip. The five
+focused CLI witnesses are CLI UX, management, control locks, monitor recovery,
+and terminal-send gates.
+
+## OpenClaw plugin boundary split
+
+Against exact parent `96b5dbdf775ed55ef0efb9391ab2618167a08966`, the
+2,830-line `openclaw-plugin.ts` monolith becomes a 67-line composition entry
+(-2,763). The complete plugin family, including the unchanged 1,068-line
+helper, moves from 3,898 to 3,974 lines (+76). Total production TypeScript
+moves from 92,904 to 92,980 lines, so adapter overhead is 2.75 percent of the
+entry movement and remains below both the preferred 250-line and hard 500-line
+budgets. The graph moves from 119 to 123 production modules and from 772 to 783
+static import edges, with zero cycles and the same sole `cli-core.ts` importer.
+The affected ownership groups contain four OpenClaw plugin modules, two
+callback-transport modules, and four monitor-supervision modules.
+
+The split assigns one explicit role to every authority path:
+
+- `openclaw-plugin-schemas.ts` owns the 14 tool JSON schemas and their exact
+  property, `required`, `not`, `anyOf`, and `allOf` insertion order.
+- `openclaw-plugin-command-adapter.ts` owns `/akk` parsing/formatting,
+  registration and tool mapping, argv construction, synchronous/asynchronous
+  CLI result/error priority, message identity, and the per-API relay-path
+  `WeakMap`.
+- `openclaw-plugin-callback-adapter.ts` owns callback identity and target
+  agreement, automatic approval, injection, delivery planning, and shortcut
+  text.
+- `openclaw-plugin-supervisor.ts` owns startup reconciliation and the
+  non-overlapping immediate/timer/start/stop monitor-supervision loop.
+- `openclaw-plugin.ts` owns only `definePluginEntry` composition, stable plugin
+  metadata, ordered registration wiring, the default export, and
+  `createOpenClawPluginForTest`.
+- `openclaw-plugin-helpers.ts` remains the canonical parser/formatter/store-dir
+  helper owner; no helper was copied into a new module.
+
+The static dependency graph is deliberately one-way:
+
+```text
+openclaw-plugin entry
+  |-> callback adapter -> command adapter -> schemas -> executors
+  |                    \-> helpers -> value guards
+  |-> supervisor -------> command adapter
+  |                    \-> helpers
+  \-> command adapter ---> helpers
+```
+
+Neither callback nor supervisor is imported by command, schemas, or helpers,
+and no split module imports the entry. The entry still binds the relay path
+before registering the callback, then registers callback -> supervisor ->
+slash command/tools in the original observable order. The merged status and
+terminal-monitor-supervision facades remain unchanged and retain their newer
+configuration, process ownership, and documentation authorities.
+
+| Old monolith boundary | Preserved invariant | New authority and proof boundary |
+| --- | --- | --- |
+| 14 inline schema objects | byte-identical JSON, tool order, descriptions, required/exclusion semantics | schemas module; 12,657-byte schema SHA-256 contract and exact 14-tool registration witness |
+| `/akk` plus tool registration/CLI execution | argv/env/cwd/stdout/stderr/exit/JSON/error and getter priority | command adapter; OpenClaw contract argv/result/error and Resume snapshot witnesses |
+| callback gateway block | modern/legacy Session/Turn identity agreement, auto-approval, injection/delivery/shortcut order | callback adapter; callback injection, mismatch, approval, and per-API isolation witnesses |
+| monitor reconciliation service | immediate startup, non-overlap, timer reschedule, stop/drain, catch-and-warn routing | supervisor module; recording supervisor timer witness |
+| plugin factory and metadata | id/name/description, Gateway scope/error code, registration order, instance-local snapshots | 67-line entry; runtime and declaration expose only `default` and `createOpenClawPluginForTest` |
+
+This is a source-ownership change only. It adds or removes no lock, Store or
+durable JSON/event write, subprocess boundary, timer, Gateway method, or
+Gateway restart. The existing `spawnSync`/`spawn` calls and their exact argv,
+environment, working-directory, output, timeout, and error rules only moved to
+the command adapter. At this exact plugin-split slice, static subprocess
+startup evidence remained 38 included sites; that is a historical slice metric,
+not the final result. The later static closeout establishes 19 of 48 baseline
+sites. The single supervisor `setTimeout` loop only moved files, and no install
+or restart path is called by plugin registration. Multiple plugin definitions
+retain separate resume caches, while the existing per-API `WeakMap` keeps
+relay path and plugin config isolated.
+
+All newly extracted or moved slice functions remain below the hard
+500-line/c50 gates. The unchanged canonical `openclaw-plugin-helpers.ts` is not
+counted in this slice gate: its existing `parseAkkCommand` remains 188 lines/c58
+and is retained for the final global complexity closure. The cohesive preferred
+100-line/c20 exceptions in this slice are transparent and recorded below;
+splitting the registration table or the ordered decision/format paths further
+would obscure schema/action order or fail-closed precedence without reducing
+authority.
+
+| Function or table | LOC / approximate complexity |
+| --- | ---: |
+| `registerOpenClawCommands` | 398 / c1 |
+| `runDelegate` | 178 / c45 |
+| `handleAkkLifecycleCommand` | 165 / c30 |
+| `runCliAsync` | 100 / c1 |
+| callback `handleCallback` | 105 / c15 |
+| `handleAkkCommand` | 90 / c22 |
+| `formatSendCommandResult` | 84 / c28 |
+| `formatStatusCommandResult` | 59 / c27 |
+| `runSendRequest` | 93 / c21 |
+
+The entry maximum is 37 lines/c3 and the supervisor maximum is 97 lines/c12.
+Machine-readable public-contract evidence freezes the exact manifest plus six
+source authority paths, checks a role-specific responsibility signature and
+each required direct import, and rejects missing command/schema roles or an
+existing but incorrect substitute path.
+
+## #195 production function hard-gate closeout
+
+PR #195 compares exact parent
+`68e0e399152f5569ef0572b914da308acea36423` with exact candidate
+`256614ede43188c7cf29594b5afe14331ff9b909`. The compiler-AST measurement
+counts every production function, method, accessor, constructor, function
+expression, and arrow function with a body, excluding nested function bodies
+from the enclosing function's complexity.
+
+| Metric | Parent | Candidate | Delta |
+| --- | ---: | ---: | ---: |
+| Production physical LOC | 92,980 | 93,303 | +323 |
+| Production functions | 4,019 | 4,044 | +25 |
+| Largest function / maximum complexity | 834 / c190 | 484 / c49 | strictly below 500 / c50 |
+| Hard-limit violations under the final rule | 6 | 0 | -6 |
+| Production modules / import edges / cycles | 123 / 783 / 0 | 123 / 783 / 0 | unchanged |
+| Static subprocess sites / affected full fallback | 19 of 48 / 2 of 10 | 19 of 48 / 2 of 10 | unchanged |
+
+The six mechanical splits preserve evaluation, short-circuit, getter, and
+first-error order:
+
+| Parent hard violation | Parent LOC / complexity | Candidate private stages | Candidate stage maxima |
+| --- | ---: | --- | ---: |
+| `pendingApprovalFromRecords` | 237 / c50 | turn selection, tool-use agreement, evidence projection | 91 / c22 |
+| `assertDeferredForegroundTransfer` | 834 / c190 | header, source history/binding, target, preparation, dispatch, commit, resolution, abort, failure | 142 / c37 |
+| `deriveRelationshipAssertions` | 121 / c60 | Session relationships and stable relationships | 90 / c36 |
+| `selectTerminalSnapshot` | 279 / c64 | row, process, management, and action selection | 128 / c28 |
+| `assertNativeThreadTransition` | 327 / c71 | header, identity, receipt, and binding consistency | 146 / c29 |
+| `parseAkkCommand` | 188 / c58 | lifecycle, Turn, and close parsing | 80 / c24 |
+
+The gate is strict `<500` LOC and `<50` approximate complexity: a function
+that reaches 500 or c50 fails. There is no exception field or allowlist. The
+default `<100`/`<20` inventory remains visible for review but is not silently
+treated as a hard failure. This closeout changes no module ownership or import
+direction, lock scope or order, durable write or recovery phase, subprocess
+boundary, public command/tool/schema/JSON contract, Store protocol, or runtime
+export.
+
+Exact-candidate validation covered typecheck, build, architecture, refactor
+evidence, and diff checks; 186 relevant direct tests, 1,001 fast tests, and
+five targeted integration files passed. Two independent exact-head reviews
+returned GO. No full suite, install, package, publish, or GitHub Actions run was
+part of PR #195.
+
+## Final CLI-core facade and ownership closeout
+
+The final closeout moves the remaining reusable authority and I/O helpers out
+of `cli-core.ts` without moving another command state machine. CLI option
+coercion and canonical workspace checks now live in `cli-command-runtime.ts`;
+conversation activity/waiting policy lives in `protocol.ts`; callback process
+failure classification lives in `callback-outbox-policy.ts`; and terminal
+process liveness lives at the existing `ps` boundary in
+`terminal-process-source.ts`. Terminal send safety is owned by
+`terminal-authority-policy.ts`, OpenClaw yield presentation by
+`terminal-dispatch-presenter.ts`, and Codex completion-context reads by the
+status facade. List and monitor consumers reuse those canonical policies rather
+than retaining private copies.
+
+The Store-backed current-Turn fence is exposed through
+`terminal-turn-binding-authority-cli-adapter.ts` under the existing terminal
+identity-authority domain. It preserves Store selection, terminal-control
+validation, writable-Store upgrade, protocol check, authoritative Session read,
+and exact-or-migrated binding comparison order. Dispatch recovery now exposes
+its existing ledger-owner read and managed-owner fence directly. Managed
+approval/cancellation still checks deferred transfer, current binding, and the
+ledger generation in that order; no lock, Store, error, or asynchronous
+boundary is reordered.
+
+Against exact parent `1274306e8e2f1e294910c8719b23de0d74878a31`,
+`src/cli-core.ts` falls from 2,122 to 1,556 physical lines (-566). Total
+production TypeScript changes from 93,303 to 93,313 lines (+10), the typed
+owner/facade overhead for the final extraction. Architecture validation reports
+57 domains, 125 production modules, 809 static import edges, zero cycles, and
+one retained `cli-core.ts` importer. Its public surface remains the stable
+`parseCliCommand` / `executeCliCommand` facade, and `CliCommandOptions` is now
+`Record<string, unknown>` in both source and emitted declarations.
+
+The final typed-boundary cleanup adds nine interface-only production lines to
+remove the last `TerminalControlSendRequest` `Record<string, any>` bridge. The
+closeout production ratchet is therefore 93,322 physical lines;
+`cli-core.ts` remains 1,556 lines and the graph remains 125 modules, 809 edges,
+and zero cycles. Direct source and emitted-declaration guards freeze the six
+option properties and reject any reintroduction of raw `any` in the composition
+boundary.
+
+The ownership validator also fixes an independent Issue-level ceiling of 8,000
+physical `cli-core.ts` lines. Manifest validation rejects a configured value
+above 8,000, while architecture validation rejects an actual source above
+8,000 even when a coordinated manifest edit makes the two values equal. The
+exact ratchet remains 1,556; a direct tamper witness raises both source and
+ratchet to 8,001, synchronizes the production total, and still fails on the
+hard ceiling. The combined compiler-AST architecture gate reports zero
+production function hard-limit violations. It also fixes one owner for each of
+the six shared status predicates: conversation release, session-send blocking,
+and callback supersede belong to `protocol.ts`; deferred-transfer finality
+belongs to `deferred-foreground-transfer-policy.ts`; ordinary dispatch activity
+and recovery belong to `terminal-dispatch-policy.ts`. The same compiler-AST
+gate rejects duplicate predicate definitions, duplicate exact inline tables,
+and full active/recoverable tables that bypass their derived policy.
+
+An exact compiler-AST inventory ratchets the 27 remaining top-level functions
+and rejects top-level classes or function-valued variables. A forbidden-owner
+guard prevents terminal-send policy, Turn-binding authority, Codex context
+loading, callback failure classification, process liveness, and status policy
+definitions from returning to the composition root. Direct tests record the
+Turn-generation and migrated compatibility boundary, superseded-error
+projection, delegated/malformed short-circuits, deferred -> binding -> ledger
+ordering and early failure, Codex provider/process/history read order, callback
+classification priority, terminal-send getter/error priority, canonical
+workspace behavior, and process/status policy reuse. Therefore `cli-core.ts`
+contains no send, lifecycle, monitor, or callback state-machine definition; it
+retains only stable parsing/execution, command routing, composition wiring,
+shared lock scopes, and CLI parser/presentation compatibility.
+
+## Integration virtual-clock profile remediation
+
+The final profile remediation changes test timing only. Production timeout,
+polling, retry, lock, and composer windows are unchanged. The ordinary
+`runAgentCliInProcess` fixture also remains real-time by default. Selected
+sequential scenarios opt in to `runAgentCliInProcessVirtual`, whose wall and
+monotonic clocks are scoped by an explicit Store, state path, or
+`AKK_RUNTIME_DIR`. Async sleeps advance that clock and yield one `setImmediate`
+turn; sync sleeps only advance it. The fixture records both kinds of request,
+reuses one monotonic clock across calls in the same fixture, and fails fast if
+two commands try to share that clock concurrently.
+
+The highest-volume sequential Codex cases may opt in one step further through
+`runAgentCliInProcessDirect`. That helper still runs the production CLI parser,
+composition, terminal adapters, identity fences, dispatch ledger, and receipt
+state machines. It replaces only the executable fake `tmux`/`ps`/`lsof` ports
+with the existing `MutableRecordingTerminalProvider` and
+`StaticTerminalProcessSource`. `writeFakeTmux` and `writeFakeProcessTools`
+register fixture-scoped panes, screens, and process snapshots; screen capture
+remains live across calls, and direct text/key operations are projected into
+the existing exact input ledger with a `direct_terminal_provider` marker.
+Explicit JSON terminal fixtures retain their own static adapters. The direct
+helper fails before command execution when it sees a capture/send/list gate,
+delay, transport failure, uncertain SIGKILL outcome, or overlapping command.
+It is additionally restricted to a non-empty Codex process fixture. Monitor,
+Claude, empty-process, process-death, and executable-observation scenarios may
+use virtual time where listed below, but never the direct provider seam.
+
+The timing boundary is intentionally narrower than the test boundary:
+
+| Virtual-time scenarios | Real-time boundary retained |
+| --- | --- |
+| Session follow-current/response generations and synthetic acceptance outcomes | v0.8.1 compatibility, Claude observation failure, the real native-binding window, and late-ACK child processes |
+| Sequential dispatch recovery and receipt-fence state machines, using direct terminal/process ports where the executable shim is not the contract | the public active-managed dispatch witness, uncertain transport/SIGKILL recovery, and both concurrent-send witnesses |
+| Wrapped-composer, prepared/orphan receipt, stable replay, and delegate replay semantics | the multilingual composer adapter witness and both gated raw-send process witnesses |
+| Same-cwd/low-confidence monitor decisions, working hard-timeout policy, and sequential renew semantics | one complete Gateway callback path and the gated renew-versus-close race |
+| Fake-process Claude death/transcript reconciliation | monitor singleton, live/dead PID and SIGKILL recovery, supervised/crash recovery, and transcript-monitor restart processes |
+| Idle-gate matrix except injected capture failure, and managed background-conversation projection | capture failure, stale-PID, partial-`lsof`, raw approval, and direct cancel adapter witnesses |
+
+No test name or pre-existing assertion is removed. Receipt bytes, whitespace,
+error priority, no-second-Enter, no-terminal-input, and Store-authority
+assertions remain in their original integration tests. The existing
+`terminal-dispatch-ledger` public-contract mapping continues to pair those
+retained receipt/recovery boundaries with the direct dispatch application,
+ledger codec, receipt, and terminal-acceptance witnesses; no manifest path or
+tier changes merely to claim a timing improvement.
+
+Measure the focused worker cost from a clean exact commit with the repository
+profile reporter. Run the identical command for the parent and candidate, on
+the same host, Node version, compile-cache state, and concurrency:
+
+```sh
+test -z "$(git status --porcelain)"
+npm run build
+test -z "$(git status --porcelain)"
+AKK_PROFILE_CACHE="$(mktemp -d /tmp/akk-126-integration-cache.XXXXXX)"
+AKK_PROFILE_OUTPUT="/tmp/akk-126-integration-$(git rev-parse HEAD).json"
+AKK_TEST_CONCURRENCY=4 \
+NODE_COMPILE_CACHE="$AKK_PROFILE_CACHE" \
+AKK_TEST_REPORTER="$PWD/scripts/test-profile-reporter.js" \
+AKK_TEST_PROFILE_TIER=integration \
+AKK_TEST_PROFILE_COMMIT="$(git rev-parse HEAD)" \
+AKK_TEST_PROFILE_DIRTY=0 \
+AKK_TEST_PROFILE_OUTPUT="$AKK_PROFILE_OUTPUT" \
+node scripts/run-test-tier.js integration \
+  test/shards/agent-cli-session-acceptance.test.ts \
+  test/shards/agent-cli-dispatch-recovery.test.ts \
+  test/shards/agent-cli-dispatch-authority.test.ts \
+  test/shards/agent-cli-composer-replay.test.ts \
+  test/shards/agent-cli-monitor-recovery.test.ts \
+  test/shards/agent-cli-monitor-lifecycle.test.ts \
+  test/shards/agent-cli-terminal-send-gates.test.ts \
+  test/shards/agent-cli-receipt-fences.test.ts
+```
+
+Compare the sum of `files[].duration_ms`, not nested test durations, and reject
+dirty, failed, wrong-SHA, wrong-Node, or wrong-concurrency reports. This section
+does not claim the final performance gate: exact merged-head before/after
+worker time and the repeated fast/full reports belong in the separate final
+evidence update after all remediation branches are stacked.
+
+## Soft freeze while #126 is active
+
+Until the orchestration milestones finish:
+
+1. Do not add product features directly to a hotspot in `cli-core.ts`. Route new
+   work through the next typed seam when reasonably possible.
+2. Security, data-loss, liveness, and release-blocking regressions may patch the
+   current path, but the PR must identify the temporary ownership and update the
+   extraction inventory.
+3. Do not introduce new `Record<string, any>` service inputs, new `*LockHeld`
+   booleans, new direct persistence calls in `cli-core.ts`, or a new lock-order
+   exception.
+4. Keep refactor PRs free of unrelated user-facing behavior changes. A behavior
+   change needs its own issue, acceptance tests, and explicit review.
+5. Retain real-process contract tests for argv/exit, terminal input, Store crash
+   recovery, and OpenClaw callback boundaries. First add deterministic reducer
+   tests; consolidate duplicate black-box cases only after equivalent contract
+   coverage is demonstrated.
+6. Do not weaken identity, token, composer, approval, ownership, CAS, uncertain
+   outcome, or callback isolation fences to make extraction easier.
+
+## Measurement method
+
+Physical LOC is `wc -l` over checked-in `src/*.ts`. Function and approximate
+complexity measurements use the TypeScript compiler AST and count functions,
+methods, accessors, constructors, function expressions, and arrow functions with
+bodies. Approximate complexity is `1 + if/loop/case/catch/?:/&&/||/??`, excluding
+nested function bodies from the enclosing function. It is a prioritization
+signal, not a semantic correctness score.
+
+The JSON baseline is immutable for this snapshot. Future PRs append their own
+before/after measurements or replace the documented current baseline while
+retaining this commit as the historical comparison point.
+
+## Issue #206 addendum — durable observation of human-started work
+
+Issue #206 adds Terminal Watch as a new aggregate beside, not inside, the
+managed Session/Turn architecture. The v16 action-contract and 14-tool sections
+above remain immutable historical snapshots; at the time of the #206 delta,
+the public surface was list action-contract v23 with 16 registered OpenClaw
+tools. v23 keeps every structured
+Send semantic-ID-only while making Codex `terminal_user_explicit` independent
+of Composer visibility, stability, and exactness. Its physical fallback clears
+the current Composer once, injects the new request, waits through the paste
+window, and dispatches Enter exactly once without a post-text Composer veto.
+Claude Code user-explicit Send, native inspection, and lifecycle input remain
+exact-empty-only; the managed path may require exact empty before input, but a
+user-explicit Codex request cannot be vetoed by Composer observation after text
+injection. When managed delivery fails before input, the physical fallback
+captures a pre-Send provider boundary and best-effort attaches an exact
+request-bound Terminal Watch after Enter. The Watch supplies completion callback
+behavior without claiming a managed Turn, and its failure never revokes Send.
+No draft text or Composer digest crosses the model boundary.
+
+The later interactive-response release advances the current public surface to
+action-contract v24 and 17 OpenClaw tools. It adds a status-bound semantic
+questionnaire response action while keeping prompt fingerprints, terminal-key
+plans, and one-shot mutation authority private.
+
+Issue #298 P2 subsequently advances the current core surface to action-contract
+v25 and 19 OpenClaw tools. It adds explicit Codex `identify_foreground` and
+atomic `identify_and_send` operations plus independent screen, native-identity,
+and durable-activity status axes. The standalone 30-second `/status` proof is
+diagnostic only and is not persisted as reusable identity authority; normal
+Send, List, and Status do not run the probe.
+
+### Aggregate and persistence boundary
+
+`TerminalWatch` schema v2 represents either one task that a human started
+directly in a Codex or Claude Code TUI or one request AKK delivered through the
+user-explicit unmanaged fallback. It is not a Conversation, Session, Turn, dispatch
+receipt, monitor owner, or terminal-input authority. Creating or reconciling it
+does not send input, adopt or claim the work, reserve the terminal, block later
+human activity, or create callback authority for a managed Turn.
+
+Each strict record contains `watch_id`, revision, agent, exact terminal endpoint,
+workspace and internally resolved binding token; one privacy-safe provider anchor
+owns the process incarnation, native thread/task and exact captured agent-version
+evidence. Regression-tested versions are diagnostics rather than a Watch
+allowlist; structurally compatible future versions remain observable with a
+warning. The record also retains the originating OpenClaw session/binary,
+creation/update/deadline timestamps, status, last activity, optional terminal
+settlement, and an append-only notification outbox whose approval entries carry
+their own evidence fingerprints.
+Status is one of `active`, `completed`,
+`failed`, `timed_out`, `invalidated`, or `cancelled`. The files live at
+`<store>/terminal-watches/<watch_id>.json`, with a `0700` directory, `0600`
+owner-private atomic JSON, strict path/symlink/shape validation, and revision
+CAS. The independent namespace is admitted by the Store root allowlist while
+retaining Store format 1 and advancing the writer fence to protocol 6.
+
+Codex anchors retain the exact process identity, rollout device/inode/path, native
+task, request hash, version, task-start/user-message/observed-end byte offsets,
+capture time, and evidence fingerprint. Claude anchors retain the exact
+process/session identity, workspace, transcript relative path/device/inode/file
+identity, root prompt, request hash, version, current-turn/observed-end byte
+offsets, capture time, and fingerprint. The compact terminal record separately
+binds endpoint/incarnation, workspace, and the internal creation-time binding
+token. The Store validates the provider-owned anchor directly, without a mirrored
+Watch-specific shape or any raw prompt or command text. Legacy schema-v1 Watch
+records normalize to v2 on read; protocol 6 prevents an older writer from
+treating those v2 records as compatible.
+
+### State, locking, and callback recovery
+
+The user flow is human TUI start → fresh `/akk list` → copy only the advertised
+`terminals[].available_actions.watch` action's exact `terminal_id` → create Watch
+→ address it only by `watch_id` for status or unwatch. The creation path resolves
+the current binding token internally, acquires the terminal lock, rescans and
+revalidates the exact terminal incarnation and token, captures one unique
+active-task anchor, then creates with expected revision `null`. All mutations acquire the canonical
+Store writer lease before the per-Watch file lock. Observation occurs outside
+that write scope; settlement reloads under `writer -> watch`, checks the exact
+terminal and anchor fingerprints plus deadline, and commits one CAS transition.
+Concurrent cancellation, timeout, settlement, or another observer therefore
+cannot overwrite a newer revision.
+
+The observation reducer yields `pending`, `approval`, `completed`, `failed`, or
+`invalidated`. Any endpoint, process, native-thread/task, provider file,
+offset/boundary, version/profile, request, or fingerprint drift—and any missing,
+truncated, replaced, successor, unsupported, or ambiguous evidence—fails closed
+as invalidated rather than following current terminal work. `unwatch` settles
+only the aggregate as cancelled and never touches the TUI.
+
+Approval appends one notification per exact fingerprint while leaving the Watch
+active. It carries metadata only, never raw prompt/command text; Terminal Watch
+has no approval execution port and cannot participate in automatic approval.
+Completed/failed observations may retain only provider-redacted bounded
+completion text (maximum 4,000 characters) plus optional completion identity and
+timestamp. Every terminal outcome appends exactly one outcome notification.
+
+Notification IDs derive deterministically from Watch, kind, and evidence
+fingerprint; the transport idempotency key derives from Watch plus notification.
+Delivery first persists a leased claim, performs transport outside the lock,
+then CAS-settles success or retry metadata. A process crash leaves an expiring
+claim that startup/periodic reconciliation can reclaim. This is crash-safe
+at-least-once transport with effective at-most-once logical delivery when the
+OpenClaw transport honors the idempotency key. One Watch's observation or
+delivery failure is recorded in its reconciliation item and does not stop the
+remaining Watches.
+
+### Public wiring and supervision
+
+The 16-tool OpenClaw surface adds `agent_knock_knock_watch` and
+`agent_knock_knock_unwatch`; the existing status tool accepts exactly one of a
+managed Turn target, semantic terminal target, or `watch_id`. List projects
+active Watches in `terminal_watches[]` and advertises `watch` only for an exact,
+supported terminal currently classified as working or awaiting approval. Slash
+routing is `/akk watch <exact-terminal-id>`, `/akk status <watch-id>`, and
+`/akk unwatch <watch-id>`. The internal CLI boundary has exactly four entries:
+
+```text
+watch-terminal --terminal <exact-terminal-id> ...
+watch-status --watch <watch-id> ...
+unwatch-terminal --watch <watch-id> ...
+reconcile-watches ...
+```
+
+Action-contract v18 establishes a zero-token model boundary. Structured actions
+carry semantic identities and user intent only:
+
+- ordinary send is `{session_id, request}` for strict continuation or
+  `{terminal_id, request}` for follow-current; the target fields are mutually
+  exclusive and may both be absent only when AKK must prove one unique target;
+- Terminal Watch is `{terminal_id}` only;
+- native inspection is `{terminal_id, inspection}`, new is `{terminal_id}`, and
+  resume is `{terminal_id, native_thread_id}`;
+- managed approval is `{turn_id}`, terminal-scoped approval is `{terminal_id}`,
+  reconcile is `{terminal_id, conflicting_session_id}`, and handoff takeover is
+  `{turn_id, reason:"superseded_by_human_context_switch"}`.
+
+Approval, reconcile, and handoff still require explicit user confirmation. The
+trusted plugin/CLI retains that confirmation offer, derives fresh terminal,
+binding, candidate, approval, handoff, revision, and compare-and-swap fences,
+and revalidates them under the canonical locks immediately before mutation.
+None of those opaque values—including live native UUIDs used only as a handoff
+fence—crosses the model-facing boundary. Human slash selectors remain a CLI
+discovery layer. Orphan close keeps `expected_message_id` and
+`expected_transition_id` because they are durable entity identities rather than
+authority tokens. This projection change retains Store format 1 and the private
+persisted authority evidence while advancing the writer fence to protocol 6.
+
+The existing non-overlapping OpenClaw supervisor now coordinates two independent
+steps at startup and every five seconds: managed-Turn monitor reconciliation and
+Terminal Watch reconciliation. Each has its own error boundary, so a failure in
+one cannot starve the other. Watch reconciliation observes active aggregates,
+settles deadlines/outcomes, and drains eligible durable notifications; it does
+not mutate Session/Turn state or replay terminal input.
+
+The deterministic fast witnesses cover provider-anchor drift, Store privacy and
+CAS, service restart/dedupe/timeout/claim-crash/retry behavior, callback
+projection, list/action v18, slash/tool routing, and documentation. Per the
+repository test policy, integration/full/release tests remain reserved for the
+immediate pre-publication gate of an actual npm or ClawHub release.
+
+## Issue #212 addendum — Host-owned lifecycle adapter
+
+AKK does not run a standalone supervisor. Exactly one external Host owns the
+in-process AKK lifecycle and calls `start()` and `stop()` with its own plugin or
+adapter lifetime. The Host injects an ordered list of reconciliation phases;
+the host-neutral lifecycle service owns only startup execution, periodic
+single-flight scheduling, per-phase error isolation, and stop/drain behavior.
+It owns no Store, callback transport, process identity, Host configuration,
+daemon entrypoint, or cross-Host lease.
+
+OpenClaw is the first adapter. Its compatibility module continues to own the
+existing reconciliation argv, Store-dir lookup, log messages, unref timer
+policy, registration service id, and managed-monitor-before-Watch ordering. The
+legacy module and service names remain unchanged to avoid an unnecessary
+OpenClaw compatibility change; they do not represent an independently running
+Supervisor product. Callback route and delivery ports were already
+host-neutral, so this extraction does not change the Store or callback protocol.
+
+Future Hosts such as Hermes compose their own adapter around the same lifecycle
+and callback ports. AKK deliberately does not add multi-Host ownership,
+Host-switch recovery, PID/heartbeat fencing, or no-Host continuity because
+those are outside the supported product behavior.
+
+## Issue #320 P2 addendum — Host connector capability handshake
+
+The Host-neutral catalog now derives one immutable capability handshake for Pi
+and DeepSeek Harness. Version 1 contains only public catalog identity: the
+ordered tool names and derived count, a canonical metadata/schema SHA-256, and
+the canonical Skill name/SHA-256. It contains no controller route, environment,
+token, filesystem path, or other authority. Each connector validates the
+handshake before starting its Host lifecycle and validates the exact names it
+registered before reporting ready. Unknown versions, missing metadata, catalog
+drift, generated-Skill drift, and partial registration fail closed.
+
+This replaces connector-local `EXPECTED_TOOL_COUNT` literals and removes the
+architecture dashboard's regex extraction of those constants. The checked-in
+public-contract witness still records the current 22-tool OpenClaw/Host Bridge
+surface; adding or removing a catalog entry intentionally changes that public
+witness, while connector counts and registration expectations derive from the
+same handshake without another manual edit.