# Testing

Agent Knock Knock keeps every deterministic, integration, compatibility, and
regression test, but it does not charge the full process-heavy suite to every
edit. The canonical classification is `test/test-tiers.json`. A manifest test
and every tier runner fail before execution if a test file is missing,
duplicated, or unclassified.

For periodic reviews of existing test value, use the repository's
[test-audit skill](../.agents/skills/test-audit/SKILL.md). It records the
contract each case protects before consolidating or deleting coverage, and
follows the fast-only development policy below.

`npm run architecture:dashboard` runs the same fail-closed architecture gate
as `validate:architecture` and prints the current health snapshot. It reports
total production LOC without gating it, while cycles, hard/default function
violations, large-file concentration, semantic tool counts, and bundled Skill
synchronization have explicit non-regression budgets. See
[`docs/architecture/current-architecture.md`](./architecture/current-architecture.md).

## Test tiers

| Command | Purpose | When to run |
| --- | --- | --- |
| `npm run test:fast` | Deterministic unit/component tests without test-level child processes | Every development, debugging, refactoring, review, and local-install loop |
| `npm run test:integration` | CLI subprocess, monitor, SQLite, Store locking, lifecycle, installer, and compatibility fixtures | Release-gate component; do not run during ordinary development or local verification |
| `npm run test:affected` | Complete fast tier plus mapped integration tests; unknown or shared-core changes run the full tier | Maintainer/release diagnostics only; not an ordinary development command |
| `npm run test:full` | The exact union of fast and integration tests | Immediate pre-publication gate for an actual npm or ClawHub release |
| `npm test` | Compatibility alias for `test:full` | Same release-only boundary as `test:full` |
| `npm run test:release` | Full suite, isolated current-build OpenClaw compatibility check, ClawHub runtime validation, and ClawHub publish dry-run | Immediate pre-publication gate for an actual npm or ClawHub release |
| `npm run test:release:live` | The release tier plus credentialed native Codex and Claude lifecycle smoke/attestation | Optional release-time diagnostic with dedicated prepared tmux panes |
| `npm run compat:openclaw` | Full minimum/current/API-boundary OpenClaw compatibility matrix | Periodic maintainer check and any change to declared compatibility floors; not required for every package release |

During normal development, debugging, refactoring, review, local installation,
and local verification, run only `npm run test:fast`. Type checking, builds,
architecture/evidence validators, installation, and non-test health checks may be
run when relevant, but they do not authorize a broader test tier. Run the
full/release suite only immediately before an actual npm or ClawHub
publication. A local OpenClaw install is not a package release.

The live release tier can make authenticated coding-agent turns. It is never
selected by `npm test` or `test:release`; opting in is an explicit operational
decision. The ordinary release tier builds in temporary state and does not
control a real coding-agent pane.

Routine releases exercise the OpenClaw version pinned by
`openclaw.build.openclawVersion`. The slower minimum Host, minimum Plugin API,
and adjacent unsupported boundary checks remain available through
`npm run compat:openclaw` for periodic compatibility review. Run the full
matrix whenever a declared OpenClaw compatibility floor changes.

The live gate requires both complete panes, a new private evidence path outside
the repository, the environment opt-in, and the command-line confirmation. It
forwards the exact arguments to the single-attempt lifecycle runner and then
verifies the resulting Codex+Claude matrix evidence:

```bash
AKK_RUN_LIVE_LIFECYCLE_SMOKE=1 npm run test:release:live -- \
  --confirm-live \
  --codex-target <session:window.pane> \
  --codex-expected-pane-pid <pid> \
  --codex-expected-version <version> \
  --claude-target <session:window.pane> \
  --claude-expected-pane-pid <pid> \
  --claude-expected-version <version> \
  --evidence </absolute/private/new-evidence.json>
```

The runner builds once per tier and passes an explicit cross-platform file list
to Node instead of relying on shell glob behavior. Its default file concurrency
is capped at four because each integration worker recursively starts CLI and fake
terminal processes; higher values made both wall time and bounded test-fixture
timeouts worse on the maintainer machine. Override it with
`AKK_TEST_CONCURRENCY` for a controlled benchmark. The runner also gives Node
child processes a shared bytecode cache under the operating-system temporary
directory. Override `NODE_COMPILE_CACHE` when profiling a particular cache, or
point it at a new `mktemp -d` directory for a cold-cache comparison.

## Affected tests

`test:affected` builds once, reads changed and untracked paths without shell
globs, and always runs the complete fast tier. By default it compares `HEAD`
with the current index and worktree. Supply an explicit base to include branch
commits as well as staged, unstaged, and untracked changes:

```bash
npm run test:affected
npm run test:affected -- --base origin/main
```

Known production domains map to no more than five exact integration-tier
witnesses. A changed integration test selects itself, a known test helper
selects its transitive integration consumers, and a changed fast test or
documentation file needs no additional integration worker. An additive
`test/test-tiers.json` edit narrows only when every new entry is also a changed
test and the prior tier order is preserved. `package.json` plus
`package-lock.json` narrow only when their parsed content proves one synchronized
version-only change. Deletion, tier movement, reordering, dependency or script
changes, and missing content proof select `test:full`.

Selection remains fail-closed for an unreadable Git diff, a stale ownership
mapping, an unknown path, exact Store/protocol modules, shared production
kernels, or selector/architecture authority files. `src/store.ts` and
`src/protocol.ts` cannot be narrowed by accompanying tests or manifest proof.

This selector remains documented for release-maintainer diagnostics. Under the
normal-development policy above, use `npm run test:fast` instead; an actual
publication uses the complete full/release gate rather than treating affected
selection as sufficient evidence.

## Targeted integration map

The map below records which integration witnesses own each subsystem. It is for
release-gate triage and failure diagnosis, not permission to run integration
tests during ordinary development or local installation. In those workflows,
run only `npm run test:fast`. Paths are source paths under `test/`, and the tier
runner handles their compiled `dist` paths.

Pass one or more exact manifest paths after `--` to run only those integration
files. The runner rejects duplicates, unknown paths, and files from the fast
tier, so a typo cannot silently weaken the intended check:

```bash
npm run test:integration -- \
  test/codex-store-adapter.test.ts \
  test/stale-bound-resume-cli.test.ts
```

| Changed subsystem | Targeted integration files |
| --- | --- |
| CLI parser, help, version, doctor, redaction | `test/cli-ux.test.ts` |
| Raw/managed send, composer/Enter, acceptance and receipt fences | `test/shards/agent-cli-terminal-send-gates.test.ts`, `test/shards/agent-cli-composer-replay.test.ts`, `test/shards/agent-cli-session-acceptance.test.ts`, `test/shards/agent-cli-receipt-fences.test.ts`; add `test/codex-no-rollout-binding-cli.test.ts` for virgin attachment |
| Dispatch authorization, locks, retry and recovery | `test/shards/agent-cli-dispatch-authority.test.ts`, `test/shards/agent-cli-control-locks.test.ts`, `test/shards/agent-cli-dispatch-recovery.test.ts`, `test/shards/agent-cli-receipt-fences.test.ts` |
| Callback outbox, responder, retry, Gateway wake and close races | `test/callback-cli.test.ts`, `test/openclaw-plugin-contract.test.ts`, `test/shards/agent-cli-claude-callback.test.ts`, `test/shards/agent-cli-monitor-lifecycle.test.ts`, `test/shards/agent-cli-monitor-recovery.test.ts` |
| Monitor completion, approval context, cancellation and renewal | `test/shards/agent-cli-monitor-lifecycle.test.ts`, `test/shards/agent-cli-monitor-recovery.test.ts`, `test/shards/agent-cli-monitor-approval-context.test.ts`, `test/shards/agent-cli-control-locks.test.ts` |
| Delegate, workspace and terminal selection | `test/delegate-cli.test.ts`, `test/session-selector-cli.test.ts`, `test/management-cli.test.ts` |
| List, status, available actions and terminal discovery | `test/management-cli.test.ts`, `test/session-selector-cli.test.ts`; add `test/codex-no-rollout-binding-cli.test.ts` for binding conflicts |
| Codex SQLite/state DB, rollout fd, WAL, candidate discovery and version filtering | `test/codex-store-adapter.test.ts`, `test/codex-no-rollout-binding-cli.test.ts`, `test/stale-bound-resume-cli.test.ts` |
| Virgin attach, reconcile-binding, PID incarnation/reuse and orphan recovery | `test/codex-no-rollout-binding-cli.test.ts`, `test/native-thread-ownership-cli.test.ts`, `test/stale-bound-resume-cli.test.ts`, `test/turn-session-binding-cli.test.ts`, `test/shards/agent-cli-dispatch-recovery.test.ts` |
| Native New/Clear/Resume transitions and guards | `test/native-thread-lifecycle-cli.test.ts`, `test/native-thread-lifecycle-recovery-cli.test.ts`, `test/native-thread-ownership-cli.test.ts`, `test/native-lifecycle-command-guard-cli.test.ts`, `test/codex-sticky-rollout-lifecycle-cli.test.ts`, `test/stale-bound-resume-cli.test.ts`, `test/codex-no-rollout-binding-cli.test.ts` |
| Store, Session, Turn, writer protocol, migration and locks | `test/store.test.ts`, `test/store-protocol-cli.test.ts`, `test/turn-session-binding-cli.test.ts`; add `test/session-selector-cli.test.ts` for projections |
| OpenClaw tool schemas, slash routing, supervisor and manifest | `test/openclaw-plugin-contract.test.ts`, `test/management-cli.test.ts`; add `test/install-openclaw-cli.test.ts` for installation/skill sync |
| Installer trust, force, update and restart readiness | `test/install-openclaw-cli.test.ts` |
| Runtime logs, redaction and permissions | `test/runtime-log.test.ts` |
| Lifecycle evidence, verifier and release guards | `test/live-lifecycle-verifier.test.ts`, `test/live-smoke-guards.test.ts` |
| Compatibility or legacy identifiers/protocols | The exact domain file plus `test/store.test.ts`, `test/store-protocol-cli.test.ts`, `test/turn-session-binding-cli.test.ts`, or `test/session-selector-cli.test.ts` as applicable |

The 11 former `agent-cli.test.ts` domains map one-to-one to exact integration
manifest entries; use these names directly rather than a shell wildcard:

| Agent CLI domain | Exact manifest path |
| --- | --- |
| Claude callback and response delivery | `test/shards/agent-cli-claude-callback.test.ts` |
| Composer replay and paste-window submission | `test/shards/agent-cli-composer-replay.test.ts` |
| Terminal mutation and dispatch locks | `test/shards/agent-cli-control-locks.test.ts` |
| Dispatch ownership and authorization | `test/shards/agent-cli-dispatch-authority.test.ts` |
| Interrupted dispatch recovery | `test/shards/agent-cli-dispatch-recovery.test.ts` |
| Monitor approval context | `test/shards/agent-cli-monitor-approval-context.test.ts` |
| Monitor completion lifecycle | `test/shards/agent-cli-monitor-lifecycle.test.ts` |
| Monitor/callback recovery | `test/shards/agent-cli-monitor-recovery.test.ts` |
| Acceptance and delivery receipt fences | `test/shards/agent-cli-receipt-fences.test.ts` |
| Session/Turn acceptance and bookkeeping | `test/shards/agent-cli-session-acceptance.test.ts` |
| Raw and managed terminal send gates | `test/shards/agent-cli-terminal-send-gates.test.ts` |

The mapping diagnoses a release gate; it never replaces the complete
pre-publication full/release suite.
Safety fences from #87, native lifecycle smoke tooling from #88, Store upgrade
paths, Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1, OpenClaw boundaries, and verified
Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267/2.1.285 schemas
remain covered.

The [Codex 0.157.1 compatibility review](./codex-0.157.1-compatibility.md)
records partial fullscreen/status support and the known paginated-history
boundary. Managed completion and native thread transitions remain unavailable
on 0.157.0/0.157.1; passing the test suite does not promote those versions to
verified native-action profiles.

The [Claude Code 2.1.285 compatibility review](./claude-2.1.285-compatibility.md)
records native observations, the attachment ordering repair, and explicit
coverage limits for this local-only update.

## #206 Terminal Watch fast contract

The fast tier owns the deterministic Terminal Watch contract:

| Fast witness | Contract proved |
| --- | --- |
| `test/terminal-watch-store.test.ts` | Owner-private atomic schema-v3 records under `terminal-watches/`, legacy-v1/v2 notify-only normalization, strict interaction aggregate validation, revision CAS, exact provider anchors plus terminal-activity anchors/checkpoints and immutable warnings, and `writer -> per-watch` lock order |
| `test/terminal-watch-service.test.ts` | Restart/list recovery, timeout and terminal settlement, actionable/manual questionnaire projection and redraw dedupe, exact observation fences, terminal-activity checkpoint persistence, callback claim-crash recovery, retry, and deterministic idempotency |
| `test/durable-notification-kernel.test.ts` | Store-neutral callback/Watch lease, retry timing, exhaustion, and settlement authorization policy |
| `test/terminal-submission-acceptance.test.ts`, `test/claude-local-transcript-provider.test.ts` | Preferred exact Codex rollout and Claude current-turn transcript anchors; source-less Codex candidate-set acceptance over anchored plus current roots, including closed-FD frozen-file scans and fail-closed replacement/deletion/multiple-acceptor evidence; drift invalidates an already exact-anchored Watch, while absence or structural incompatibility at manual-Watch creation can be downgraded to a warning and terminal-activity fallback |
| `test/terminal-watch-cli-adapter.test.ts`, `test/terminal-watch-callback-cli-adapter.test.ts` | Exact-task capture when available; best-effort `terminal_activity` fallback after observed activity and consecutive stable-idle sweeps; `watch_mode`/`confidence`/warning projection; no Session/Turn ownership; exact-Watch same-controller Status and one-shot `respond_interaction({watch_id})`; managed-first responder arbitration; zero-input release versus uncertain dispatch; activity/manual notification-only behavior; hard failure only for an absent/unobservable exact terminal or unwritable Store; privacy-safe callbacks that never present stable idle as exact task completion; and restart-safe exact fallback anchors |
| `test/terminal-agent-bridge.test.ts`, `test/terminal-list-action-policy.test.ts`, `test/terminal-action-projection.test.ts`, `test/terminal-list-renderer.test.ts`, `test/openclaw-plugin-helpers.test.ts`, `test/quickstart-docs.test.ts` | Broad read-only Watch discovery, direct user-explicit Watch by exact `terminal_id` even without advertisement, Watch status/unwatch routing and formatting, action-contract v30 semantic-ID-only projection including same-controller status-bound native-interaction response, exact Codex model-control residue repair, and explicit foreground identification, three-axis terminal status, Codex and Claude Code user-priority replace-current-Composer delivery without visibility/exactness or post-text Composer vetoes, automatic fallback Watch callback semantics, and the documented terminal selection → exact-task-or-activity Watch workflow |

The current public surface has 22 OpenClaw tools. Terminal Watch adds the
`watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`
CLI entries. OpenClaw's supervisor coordinates managed-monitor and Watch
reconciliation in the same non-overlapping lifecycle but with independent error
boundaries, so either side can make progress when the other fails. The
process-level plugin contract remains in the integration tier and is exercised
only as part of an authorized pre-publication full/release gate.

The fallback completion-shaped event is deliberately a weaker contract. Tests
must assert that it is emitted only after the selected terminal/process has
shown activity and then stable idle across consecutive observations, carries
`watch_mode="terminal_activity"` and `confidence="best_effort"`, and tells the
controller that the signal is not exact task-completion proof. An initially
idle or unknown terminal cannot settle until activity has first been observed.

The v30 fast contract also proves that structured model actions expose semantic
IDs only: Watch uses `terminal_id`; send uses mutually exclusive `session_id` or
`terminal_id`; native inspection, new, resume, and reconcile use their documented
terminal/session/thread IDs; and approve or handoff retains explicit-confirmation
behavior without projecting opaque tokens, fingerprints, revisions, binding
IDs/generations, composer digests, draft text, or handoff-only live-native-UUID
fences. Questionnaire response uses a fresh same-controller Status projection,
one opaque interaction ID, semantic answer IDs or bounded text, and a durable
one-shot reservation; changed, manual-required, secret, or uncertain state stays
fail-closed. Codex and Claude Code `terminal_user_explicit` each prove one
clear/inject/paste-wait/Enter sequence even when the Composer is invisible,
truncated, unstable, or nonempty, with no post-text Composer veto. Codex uses
`C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Native inspection and
lifecycle input remain exact-empty-only; managed delivery may require exact
empty before input, but either agent's user-explicit Enter is not post-text
gated. Once clear or request input may have occurred, uncertainty forbids an
automatic retry.
The Send result contract independently proves physical dispatch, native
acceptance, management mode, observation mode, and callback/interaction
capabilities. Durable close audit facts come from dispatch receipts rather than
human-readable close prose. Candidate-set recovery may leave a provisional Turn
pending until exactly one rollout accepts its immutable request hash; it never
replays terminal input while resolving that identity.
The semantic
`native_thread_id` remains public for resume. The plugin/CLI still derives and
revalidates those private fences under lock. Store format remains 1 and the
Terminal Watch schema is 3; writer protocol 9 fences capability-checked paginated task
bindings and private native-question checkpoints from older writers. It retains
the manual-interaction notification state and bounded callback metadata introduced
in writer protocol 7. The Watch schema version fences the response aggregate.

## Profiling

Run the same tier, Node version, concurrency, machine, and compile-cache mode
before and after a performance change:

```bash
npm run test:profile -- --output /tmp/akk-test-profile.json
npm run test:profile -- integration --output /tmp/akk-integration-profile.json
```

The reporter records the commit and dirty state, Node/platform/CPU metadata,
concurrency and cache path, total wall duration, counts, per-file worker
duration, and every test duration. It prints the 20 slowest files and tests and
writes the complete JSON report when `--output` is supplied. Set an explicit
concurrency for a controlled comparison:

```bash
AKK_TEST_CONCURRENCY=8 npm run test:profile -- --output /tmp/akk-profile-c8.json
```

Do not reduce production polling/settle windows, disable process isolation, or
force-exit the runner to improve a benchmark. Split independent file workers,
inject clocks/providers where semantics permit it, and retain thin real-process
coverage for process, WAL/checkpoint, fs-lock, and lifecycle boundaries.

## #126 callback in-process migration

Eight once-per-file executable starts in `test/callback-cli.test.ts` now use the
same `parseCliCommand` to `executeCliCommand` path imported by the executable.
Their original assertions remain in place. The migration maps each former
black-box case to the service invariant it exercises and the process boundary
that remains black-box:

| Former executable case | Imported service invariant | Retained real boundary |
| --- | --- | --- |
| Late callback after Turn release | Reject before state or event mutation | Emitted callback argv/stdout/exit goldens |
| Corrupted event log | Fail closed on Store validation | Emitted callback error projection |
| Failed question notification | Preserve `waiting_for_openclaw` and failed outbox state | Fake OpenClaw Gateway child failure |
| Close after failed delivery | Keep the failed outbox retryable and immutable | Gateway child plus separate executable concurrency witnesses |
| Reused message ID with changed payload | Reject payload mutation under an existing claim | Retained callback executable helper |
| Explicit Gateway URL/token retry | Persist authentication while redacting public state | Fake OpenClaw environment and argv |
| Automatic transient retry | Preserve retry state and monitor scheduling | Real retry-monitor and Gateway children |
| Manual retry during automatic attempt | Report the exact live lease without mutation | Concurrent winner/loser CLI processes |

The dynamic callback test path therefore starts eight fewer CLI processes. The
reproducible static evidence moves from 48 to 40 included startup sites
(`cli_process` 38 to 30), while all 10 fake-Node startup sites remain. The
machine-readable `callback-outbox` migration in
`config/public-contract-witnesses.json` ties the old executable witnesses to
the callback policy, settlement, and transport service invariants and to the
retained CLI, Claude, and OpenClaw boundaries.

## #126 CLI UX and native-ownership in-process migration

The second migration slice routes 21 normal invocations through
`parseCliCommand` and `executeCliCommand`: eight help, version, doctor, and
redaction invocations plus thirteen native-ownership sends. The test and
assertion inventories are unchanged.

| Former executable cases | Imported service invariant | Retained real boundary |
| --- | --- | --- |
| Help and version aliases | Exact parser aliases, stdout bytes, and success status | CLI import isolation and copied-distribution doctor executable |
| Runnable-doctor failure and public redaction | Probe result projection and secret-free JSON | Copied-distribution doctor argv/stdout/OS-exit plus real-CLI runtime-log redaction |
| Codex and Claude native ownership sends | Exact PID/UUID, Store, binding-generation, and stale-ledger authority | Codex attach, handoff, lifecycle recovery, and terminal-send executable suites |

The static metric removes the two direct native-ownership startup sites and the
shared normal CLI UX startup site, moving the current evidence from 40 to 37
included sites (`cli_process` 30 to 27). All fake-Node sites remain. Claude
native inspection was also audited, but remains executable-backed because its
PATH-scoped `ps` and `tmux` discovery is not equivalent through the current
in-process dependency seam. Crash injection, OS exit, process competition,
file-lock, monitor-PID, nested Gateway approval, updater, and terminal-process
witnesses in `agent-cli-fixtures.ts` remain process-backed.

The machine-readable `cli-runtime` and `terminal-binding-authority` mappings in
`config/public-contract-witnesses.json` connect the migrated cases to focused
service invariants and retained executable witnesses.

### Doctor capability boundary tier

Doctor capability evaluation and invalid-timeout policy remain in the fast
tier. The four tests that intentionally execute fake Node and shell programs
live in `test/doctor-capabilities-process.test.ts` in the integration tier.
They still prove exact argv, version parsing, executable permissions, timeout,
non-zero exit, missing executable, and malformed-output behavior; only their
tier classification changed.

## #126 management, selector, and Session-binding in-process migration

The third migration slice removes the outer CLI process from 50 normal command
invocation expressions across 24 tests while preserving all 298 assertion call
sites. `management-cli` and `session-selector-cli` now exercise the executable's
same `parseCliCommand` to `executeCliCommand` path for list, status, selector,
static-terminal, and synthetic-acceptance behavior. The six record-only
`turn-session-binding-cli` callbacks use that path for Session authority checks.

| Former executable cases | Imported service invariant | Retained real boundary |
| --- | --- | --- |
| Ten management list/status invocations | Exact JSON projection, trace redaction, static terminal observation, and action-contract v24 | Standalone executable list/status in `store-protocol-cli`, copied-distribution CLI output/exit |
| Thirty-four selector, status, send, respond, and approve invocations | Deterministic ambiguity failures, canonical ownership, cross-Store fencing, semantic-ID routing, and private fence derivation | Codex binding and terminal-send executable suites with real terminal observation/input |
| Six record-only callback binding invocations | Protocol-3 Session presence, generation, process evidence, route-rename, and protocol-2 compatibility | Callback executable argv/exit, Gateway, retry, and concurrency suites |

The static metric removes one CLI startup site from each migrated file, moving
the evidence from 37 to 34 included sites (`cli_process` 27 to 24). All 10
fake-Node sites remain. Writer-protocol mismatch and fake-tmux observation in
`store-protocol-cli`, callback Gateway/concurrency, Store crash and migration,
terminal input, lock competition, monitor PID, and OS-exit witnesses remain
process-backed.

The machine-readable `callback-outbox`, `terminal-binding-authority`, and
`terminal-list-renderer` mappings tie each former executable family to its fast
service invariant and to a separate retained real-process witness.

## #126 deterministic dispatch-admission in-process migration

The fourth migration slice removes 27 outer CLI process starts across 23 tests
while preserving all 63 assertion call sites in those cases. The commands still
enter through `parseCliCommand` and `executeCliCommand`; only the redundant Node
executable boundary is removed.

| Former executable cases | Imported service invariant | Retained real boundary |
| --- | --- | --- |
| Ten delegate routing tests (14 invocations) | Deterministic agent, workspace, pane-incarnation, and exact-selector routing over the production static terminal/process adapters | Dispatch-authority, recovery, and terminal-send executable suites |
| Twelve native slash-command guard cases | Every ordinary send/respond alias rejects before Store creation or terminal input | Native lifecycle and lifecycle-recovery crash/terminal executables |
| One static-fixture acceptance case | Synthetic transport cannot become native acceptance without the explicit opt-in | Session-acceptance, receipt-fence, and terminal-send executable suites |

The delegate fixture continues to use the production
`StaticTerminalProcessSource` selected by `--processes-json`. Its former fake
`ps` executable supplied only a deterministic Codex process-birth string and
was not a PATH-discovery assertion, so the imported command now injects that
same typed observation directly. PATH-scoped process discovery remains covered
by its dedicated executable tests. Environment, cwd, clock, output, and exit
state are scoped through the CLI async-local runtime; no test mutates process
globals.

The static metric removes one CLI startup site from each migrated file, moving
the evidence from 34 to 31 included sites (`cli_process` 24 to 21). All 10
fake-Node sites remain. Test tiers are unchanged: these filesystem and terminal
component cases remain in the integration tier even though their redundant
outer executable was removed.

The machine-readable `terminal-dispatch-policy` and
`terminal-dispatch-ledger` mappings connect the imported cases to focused
policy/acceptance invariants and to retained real-process witnesses for argv,
OS exit, terminal input, crash recovery, locks, concurrency, monitor PID,
Gateway transport, and Store writer fencing.

## #126 callback normal-command in-process migration

The fifth migration slice routes all 20 successful invocations that formerly
shared the generic synchronous callback CLI helper through `runInProcessCli`,
and therefore through the production `parseCliCommand` to `executeCliCommand`
path. The 13 affected tests and all 160 assertion call sites remain. Nine tests
become async; four were already async.

| Former normal callback cases | Invocations | Imported service invariant | Retained real boundary |
| --- | ---: | --- | --- |
| Record-only creation and duplicate suppression | 3 | Message identity, Turn identity, event persistence, and idempotency | Concurrent duplicate CLI processes |
| Direct Gateway delivery and legacy identity derivation | 2 | Gateway payload projection, token redaction, and legacy Session/Turn fallback | Production fake-OpenClaw child processes |
| Close, retry, rebinding, and persisted authentication | 7 | Immutable outbox, close-state preservation, binding generation, and URL/token routing | Gateway success/failure helpers and the close-during-delivery child |
| Startup reconciliation and accepted-wake settlement | 4 | Retry-monitor launch/reconciliation and no-redelivery settlement | Real detached retry-monitor and Gateway children |
| `chat.send`, `agent.wait`, legacy plan, and `sessions.send` delivery | 4 | Accepted delivery plans, run observation, exact argv, and event recording | Production Gateway child-process transport |

Environment overlays remain scoped by the CLI async-local runtime. `PATH` and
Gateway-token overrides reach the production OpenClaw transport through
`cliEnv()`, while the transport continues to start the fake Gateway executable
itself. The tests do not mutate `process.env`, change cwd, observe the outer CLI
PID, or assert OS exit. The close-during-delivery and callback-retry competition
tests still use separate real CLI processes where process identity and file
competition are the behavior under test.

The in-process `callback` and `retry-callback` commands in this slice complete
their delivered or accepted settlement before returning. Reconciliation only
persists the PID of the real retry-monitor child it launches; it does not claim
an attempt for the in-process caller. No migrated case waits for an outer CLI
`attempt_pid` to die, while the manual in-flight and winner/loser lease cases
remain on their existing imported-failure and real-process paths.

Four explicit callback CLI startup sites remain: Gateway failure and success
helpers, the asynchronous concurrency helper, and the direct retry loser. They
perform 9, 6, 4, and 1 dynamic CLI starts respectively in this file. The
generic helper removes exactly 20 outer CLI starts without removing any
Gateway or retry-monitor start. `test/runtime-log.test.ts` also remains
process-backed because it proves the executable wrapper's `cli_start` and
`cli_finish` records, default `AKK_LOG_DIR` environment routing, and redaction.

The static metric moves from 31 to 30 included startup sites (`cli_process` 21
to 20); all 10 fake-Node sites remain. The machine-readable
`callback-cli-in-process` witness records the moved normal-command cases, while
`callback-cli-boundary` now names the retained winner/loser executable race.

## #126 composer not-accepted in-process migration

The sixth migration slice routes the multilingual Codex composer
not-accepted command through `runInProcessCli`, and therefore through the same
production `parseCliCommand` to `executeCliCommand` path. The test still uses
the real tmux adapter executable, preserves the exact multiline composer after
paste and after Enter, disables synthetic acceptance, and asserts that AKK
dispatches exactly one `C-m`. Its durable not-accepted receipt, close recovery,
and public JSON assertions are unchanged; only the outer Node CLI wrapper is
removed. The explicitly injected process runner remains a visible
`other_process_or_adapter` site and still starts the fake tmux, `ps`, and
`lsof` executables with the command-scoped environment.

This removes one real CLI startup site without moving or hiding a spawn. The
static evidence becomes 29 included sites (`cli_process` 19 plus the unchanged
10 fake-Node sites), a 39.58% reduction from the frozen 48-site baseline. The
machine-readable `terminal-composer-in-process` witness records the imported
command invariant, while raw/managed send, receipt-fence, crash, lock,
acceptance, and terminal-input executable witnesses remain process-backed.

## #126 shared agent CLI in-process migration

The seventh migration slice removes the synchronous outer-Node
`runAgentCli` wrapper from `test/agent-cli-fixtures.ts`. All 197 former call
sites are classified by behavior. Normal deterministic commands now await the
shared `runAgentCliInProcess` path, which still executes the production
`parseCliCommand` to `executeCliCommand` boundary. Across parameterized tests
and shared fixture calls, 214 of the former 233 dynamic outer CLI starts move
in process. The remaining 19 dynamic starts use `runAgentCliAsync` because the
asserted behavior requires an independently dying PID, exit 86, a live monitor
or handoff singleton, cross-process lock competition, or a detached
monitor/retry child whose PID is observed.

The shared runner scopes environment, cwd, caller PID, wall and monotonic
clocks, and sleeps to one imported command. CLI JSON fixtures continue to
select the production static terminal, process, Codex-session, Claude-agent,
and version adapters. A command that instead supplies a fake `PATH` receives
the production `TmuxTerminalControlProvider`, `SystemTerminalProcessSource`,
and `CodexStoreAdapter` with one command-scoped runner. Fake `tmux`, `ps`,
`lsof`, and `claude` executables therefore remain real adapter subprocesses;
their single visible `spawnSync` call site is classified as
`other_process_or_adapter`, not hidden or counted as an imported CLI.

The 70 affected shard test declarations, the one parameterized native-
inspection declaration, and all 1,223 assertion call sites remain.
The static metric becomes 28 included sites (`cli_process` 18 plus the
unchanged 10 fake-Node sites), a 41.67% reduction from the frozen 48-site
baseline. The adapter runner raises the diagnostic-only
`other_process_or_adapter` count from 11 to 12 while deleting the synchronous
CLI startup site. No production source changes are part of this slice.

## #126 final static subprocess gate

The final static slice removes nine more real product-test startup call sites.
It does not merge start helpers, move a start to an uncounted file, change the
lookahead, drop a test, or alter concurrency. Each migrated case still enters
the same production parser/command or domain authority:

| Former executable case | Imported invariant | Retained real boundary |
| --- | --- | --- |
| Callback success/failure helpers and the retry loser | Callback policy, immutable attempt claim, transport acceptance, and settlement | Async retry winner, callback CLI/Gateway concurrency, and fake OpenClaw children |
| `install-openclaw` outer CLI | Parser, installer filesystem effects, trust fallback, verification, readiness, and JSON projection | Real fake-OpenClaw, tmux, and Claude executables plus the doctor argv/OS-exit witness |
| Lifecycle evidence verifier wrapper | Exact argument policy, bounded reads, private output, redaction, validation codes, and tag round-trip through an injected IO port | Release-script wiring and the retained executable argv/OS-exit witness |
| Live tmux opt-in refusal | The same exported two-factor guard called by the executable entry | Live script keeps the guard before discovery/input; doctor retains executable exit projection |
| CLI-core import probe | An isolated Worker proves no argv inspection, output, exit, or import side effect | Doctor and runtime-log tests retain real CLI argv, stdout/stderr, OS exit, and environment routing |
| Duplicate Claude recovery wrapper | Exact lifecycle identity, CAS, and no-replay settlement through injected terminal/process seams | Codex black-box recovery remains executable and crash/lifecycle suites retain status 86 |
| Single auto-approval nested CLI | The real fake-Gateway child imports `parseCliCommand`/`executeCliCommand` for the nested approval | Sequential nested approval remains process-backed; Gateway, monitor, and callback children remain real |

`config/public-contract-witnesses.json` records this table as the
`static-subprocess-final` old-case → service-invariant → retained-boundary
mapping. The product-test count is now 19 of the immutable 48-site baseline
(`cli_process` 12, `fake_node_process` 7), or 39.58%, so the static
`final_threshold.required` gate is enabled. Store/file-lock competition,
crash-86, live monitor PID recovery, callback Gateway, tmux/ps/lsof/Claude
adapter, and real Herdr capability probes remain process-backed.

The measurement implementation's own CJS/ESM and process-tree probes are
reported separately: the baseline has zero diagnostic starts and the current
tree has 10 included fake-Node diagnostic starts plus one
`other_process_or_adapter` fork. The one canonical diagnostic path is applied
to both revisions and is fixed by validation; it cannot be widened to hide a
product-test start.

## #126 dynamic subprocess reduction attestation

The static call-site count above remains a cheap architecture diagnostic. It
is not the final proof for the requirement to remove at least 60% of redundant
outer CLI starts: one helper can execute a call site many times, and moving a
`spawn` into another helper must not improve the result.

Run the final same-machine process-tree attestation from a clean worktree:

```sh
node scripts/measure-subprocess-dynamic-evidence.js \
  --output /tmp/akk-subprocess-evidence.json
```

This command performs no install and uses no network service. It verifies that
`package-lock.json` is byte-identical at current HEAD and the immutable
`ea592a88d7af4a709e7a7a1b989dd29e61932935` baseline, creates a detached
temporary baseline worktree, links the already-present `node_modules`, builds
both revisions, and runs the full tier at concurrency four once per revision.
Both full runs must pass; a partial or failed run is not accepted as evidence.

`scripts/subprocess-dynamic-hook.cjs` is preloaded before the test workers. It
patches every standard `node:child_process` start entry point, synchronizes the
patched CommonJS exports into ESM named imports, and propagates the preload and
run identity even when a caller supplies an explicit stripped `env`. Every
launch also propagates one random, non-secret call ID into the child boot, so
synchronous launches are associated directly without scanning PIDs created by
other concurrent workers. Nested
implementations such as `exec` calling `execFile` emit one record for the real
child rather than two wrapper records, and `util.promisify.custom` remains
usable.

The attestation runs each full tier in one new POSIX process group. The hook
records every explicitly detached child as another process-group root. After
the direct runner exits, measurement waits on the kernel until the runner group
and every recorded detached group are empty; a shell that exits after forking a
background descendant therefore cannot create an unobserved quiet gap. Trace
files are read twice only after all groups are empty, and any live group fails
closed at the configured 30-second timeout. This local attestation consequently
supports macOS and Linux and fails closed on Windows. The baseline completion
finishes before current measurement starts, and the current completion finishes
before either trace is summarized. The final
count comes from observed CLI process boots and their process ancestry, not
from source locations. Moving a start behind a shared Node helper, shell, or
another call expression therefore does not make that start disappear. A
targeted CLI start without its corresponding boot, or a CLI boot without an
originating test, makes the attestation fail closed.

The denominator is the observed full-tree count at the immutable baseline;
the 233-call shared `runAgentCli` migration inventory is only one family and is
not misreported as the global baseline. Current HEAD must be at most 40% of the
same observed baseline (at least a 60% reduction). The report
contains only command basenames, CLI actions, option names, counts, status or
signal outcomes, and test paths; message bodies, tokens, environment values,
and raw argv are never recorded.

The reduction gate is paired with retained real-process checks so deleting or
reclassifying necessary coverage cannot satisfy it. The current full trace
must still demonstrate:

- real doctor argv and non-zero OS exit;
- a crash-injected CLI exit with status 86;
- overlapping CLI processes for Store/terminal lock competition;
- a live child PID and a `SIGKILL` monitor-recovery boundary;
- real fake-Gateway (`openclaw`) execution; and
- real `tmux`, `ps`, `lsof`, and `claude` adapter subprocesses.

Each retained observation is tied at runtime to its explicitly scoped,
allowlisted `TestContext.name`. The canonical path and exact test name in
`config/subprocess-dynamic-evidence.json` are immutable validation inputs, not
replaceable substring hints. Multiple argv,
exit, signal, or live-PID requirements on one boundary must be satisfied by the
same observed CLI process; unrelated children in the same file cannot be
combined into a passing witness. Multi-command adapter boundaries likewise
require every command beneath one outer CLI process, so separate tests in the
same source file cannot be combined into a passing case. Boundaries sharing one
canonical test name also share one command group. The retained Claude and
terminal-adapter witness is the raw background send case, where one outer CLI
process owns every observed `claude`, `tmux`, `ps`, and `lsof` child. The normal
fast evidence test validates that immutable configuration and executes a real
process-group probe in which an exited shell leaves a delayed 1.5-second
background CLI with an explicit stripped environment. A second CJS/ESM matrix
covers every sync and async launch API plus promisified `execFile`, exact
call-ID deduplication, and stripped-environment propagation; an overlapping
sync/concurrent-writer probe prevents shared-trace PID inference from returning.
Those probes transparently add ten fake-Node source sites to the separately
reported diagnostic scope; one fork probe is classified as
`other_process_or_adapter`. They do not increase either revision's product
migration numerator, and the same canonical partition is applied to baseline
and current. The dynamic full-tree ratio remains the final runtime 60% gate.
It validates the already-active preload without recursively starting its probe
while the outer dynamic attestation runs, avoiding a measurement of the
measurement itself. The expensive two-revision full attestation remains an
explicit final/local gate rather than running inside ordinary fast tests.

## #108 performance record

The pre-refactor maintainer baseline was 48 files / 683 tests / about 573
seconds. By v0.11.3 it had grown to 48 files / 696 tests; with the two manifest
guards added by this work, the comparable before profile was 49 files / 698
tests / 513.96 seconds. The final stable profile is 59 files / 698 tests /
301.05 seconds, a 41.4% reduction with no removed tests. A higher-concurrency
passing run reached 240.13 seconds but was not adopted because repeated stress
caused resource-starvation false failures.

See [the complete #108 performance report](test-performance-issue-108.md) for
the before/after critical paths and why the remaining real-process gates make a
stable 180-second full suite unattainable without the next handler/provider
injection refactor.

Issue #120 completed that next handler/provider-injection phase for the three
largest lifecycle families. See
[the #120 performance report](test-performance-issue-120.md) for the in-process
semantic inventory, retained black-box contracts, and final three-run profile.