@scotthuang/agent-knock-knock 0.13.17 → 0.14.0

package/docs/architecture/interactive-terminal-response.md

@@ -0,0 +1,276 @@
+# Interactive terminal response design
+
+Status: implemented public package contract
+
+## Problem
+
+AKK's terminal approval boundary historically exposes one operation: approve
+the adapter-proven first, one-time `Yes` choice. `cancel` interrupts the Turn;
+it is not a semantic `No` selection. Modern Claude Code and Codex TUI surfaces
+also ask ordinary questions with choices, optional free-form input, multiple
+steps, and a final confirmation. Treating every such surface as approval would
+conflate permission authority with task input and would make safe replay and
+auditing impossible.
+
+This design therefore keeps two boundaries:
+
+- **Permission decision**: a closed adapter-owned decision such as
+  `approve_once` or `reject`. Persistent authorization choices are never
+  offered. The caller never supplies terminal keys, menu indexes, or labels.
+- **Questionnaire response**: a versioned public projection containing opaque
+  question and option ids, plus typed answers. The terminal key plan and all
+  mutation authority remain owner-private.
+
+## Public model-facing contract
+
+AKK projects one currently visible interaction:
+
+```json
+{
+  "schema": "agent-knock-knock/terminal-interaction",
+  "version": 1,
+  "interaction_id": "opaque-id",
+  "turn_id": "turn-...",
+  "agent": "claude",
+  "kind": "questionnaire",
+  "state": "pending",
+  "step": { "index": 1, "total": 2 },
+  "questions": [
+    {
+      "question_id": "opaque-question-id",
+      "header": "Color",
+      "prompt": "Which color do you prefer?",
+      "required": true,
+      "response_kind": "single_select",
+      "options": [
+        { "option_id": "opaque-red-id", "label": "Red" },
+        { "option_id": "opaque-blue-id", "label": "Blue" }
+      ]
+    }
+  ],
+  "capabilities": {
+    "batch_response": false,
+    "free_text": false,
+    "multi_select": false
+  }
+}
+```
+
+The corresponding mutation accepts only the advertised semantic ids and typed
+answer shape:
+
+```json
+{
+  "interaction_id": "opaque-id",
+  "turn_id": "turn-...",
+  "answers": [
+    {
+      "question_id": "opaque-question-id",
+      "response_kind": "single_select",
+      "selected_option_ids": ["opaque-blue-id"]
+    }
+  ]
+}
+```
+
+The OpenClaw tool should be named
+`agent_knock_knock_respond_interaction`. It is deliberately separate from
+ordinary `respond({turn_id, request})`, which injects a new composer message,
+and from `approve({turn_id, decision})`, which resolves a permission prompt.
+
+The public implementation is step-oriented: one response call resolves only
+the currently projected step. The managed monitor recaptures the next native
+question, publishes a new `interaction_id`, and emits a new
+`interaction_required` callback for each supported actionable step. This makes
+multi-question and final-confirm flows explicit and avoids a blind batch of
+terminal input.
+
+The callback is a durable wake-up signal, not response authority. It contains
+only the public interaction projection and never the private prompt
+fingerprint or key plan. The owning OpenClaw conversation must call Status for
+the exact `turn_id`; displaying that fresh result creates the short-lived,
+conversation-bound private offer required by `respond_interaction`. A delayed
+or replayed callback therefore cannot authorize input by itself.
+
+## Private authority
+
+The Store may retain a private authority record binding all of the following:
+
+- exact Turn and owning OpenClaw session;
+- terminal endpoint, process incarnation, native thread, and binding
+  generation;
+- transcript/rollout source identity and bounded observation point when
+  available;
+- an exact unredacted prompt-region fingerprint;
+- the current native step and the adapter-owned semantic-id-to-input plan;
+- expiry, reservation, last proven stage, and uncertain-outcome state.
+
+None of those mutation fields are copied into the public projection. Labels
+and redacted excerpts are presentation only and never mutation authority.
+
+## Recognition and dispatch
+
+Every supported surface has a closed adapter/version profile. Detection must
+isolate one bottom-most complete prompt, prove its footer and frame, reject
+duplicate/out-of-order choices, and produce a digest before redaction.
+
+For each response AKK:
+
+1. acquires terminal, Store-writer, and Turn-state locks in canonical order;
+2. revalidates owner, Turn status, binding generation, process/native identity,
+   and the current private interaction offer; an elapsed displayed expiry
+   forces this live revalidation but does not claim the native prompt died;
+3. recaptures the screen and requires the same exact prompt fingerprint;
+4. resolves opaque semantic ids to an adapter-owned input plan;
+5. reserves the response durably before possible terminal input;
+6. dispatches one bounded native step;
+7. records an audit receipt without raw answer content and resumes the monitor;
+   and
+8. resumes the managed monitor, which recaptures the next native state, rotates
+   the interaction id when the exact prompt changes, and emits the next
+   supported-step callback. Status can always refresh the same projection
+   explicitly.
+
+If a failure occurs before terminal input, the response is safely rejected.
+If input may have occurred, the Turn becomes `response_uncertain`; AKK sends no
+automatic retry. Unknown versions, secret-input questions, ambiguous screens,
+unsupported option counts, changed prompts, or unprovable postconditions are
+`manual_required` and send zero input.
+
+## Native behavior profiles
+
+### Claude Code 2.1.263, 2.1.266, and 2.1.267
+
+Claude Code 2.1.263 was observed locally in an isolated tmux session; the
+versioned profiles retain this exact behavior contract:
+
+- single-select: digit selects and advances/submits;
+- multi-select: digits toggle checkboxes, then `Tab` advances to review;
+- Other/free text: select `Type something`, enter a single-line response below
+  Claude's 800-character paste-collapse threshold, then Enter;
+- multi-question: a tab header shows checked/unanswered sections;
+- final review: `Submit answers` / `Cancel` is a distinct confirmation step;
+- Bash permission prompt: the exact four-row form has one-time Yes as the
+  current row and `4. No`; `Escape` cancels the dialog and is not modeled as
+  semantic reject.
+
+The installed 2.1.266 binary and Anthropic's official 2.1.267 Darwin arm64
+artifact retain the same bounded questionnaire, collapsed-paste, and Status
+anchors. Each version has a distinct interaction profile so a durable offer
+cannot cross a client-version change. Claude Code 2.1.261 also introduced an
+optional `Organization policy` Status row when managed policy loading fails;
+the 2.1.263/2.1.266/2.1.267 profiles allow that exact field and redact its
+value.
+
+The initial public implementation executes exact single-select rows (including the transition into
+`Type something`), the recaptured single-line custom-text editor, and the
+separate final Submit/Cancel review. Custom text is capped at 799 characters;
+larger answers fail before dispatch reservation until the editor gains the
+same collapsed-paste proof as managed Send. It detects multi-select screens
+but keeps them `manual_required`: safely toggling several checkboxes requires
+a recapture after every toggle and is intentionally deferred. `Tab to amend`,
+persistent Yes, auto mode, resized/wrapped variants, and any changed menu shape
+also remain manual.
+
+### Codex 0.153.4, 0.154.0, and 0.155.1
+
+The installed client matches the current official TUI protocol:
+
+- `RequestUserInput` contains 1-3 questions with 2-3 options and automatic
+  Other;
+- numeric selection advances an ordinary choice question, but would bypass
+  Notes and submit the literal label for the native Other row;
+- the client-generated `None of the above` row is Codex's canonical Notes
+  carrier; when the model did not supply a `Type something.` alias, AKK derives
+  that separate semantic free-text choice beside the proven native row;
+- choosing the guarded or derived free-text choice moves to native Other with
+  bounded cursor movement and invokes Codex's native Accept action, which
+  opens Notes without submitting a literal label; choosing native Other itself
+  retains its distinct numeric direct-submit behavior;
+- the recaptured empty `Add notes` composer becomes a separate free-text
+  interaction step;
+- Codex submits that text as `user_note: ...` alongside `None of the above`;
+  it does not expose a Claude-style bare custom-answer value;
+- semantic free-text dispatch crosses the verified 121ms paste-suppression
+  window before its sole Enter;
+- the exact multi-question free-form footer is handled one current step at a
+  time;
+- unanswered-question confirmation is its own `Proceed` / `Go back` step.
+
+Codex does not currently expose a native multi-select question in this
+protocol. Any future or unrecognized shape remains manual until a new profile
+and tests are added.
+
+Codex 0.154.0 and 0.155.1 preserve those blocking `request_user_input` frames
+under separate version-bound profiles. Codex 0.154.0 also adds
+`request_user_input_async`; unlike a blocking `questionnaire`, its question is
+projected as `kind="async_question"` while the agent Turn remains `working`.
+The projection advertises semantic `delivery_modes`. A typed response defaults
+to advertised `steer_current_turn` or explicitly selects advertised `queue_next_turn`: `steer_current_turn` delivers the answer to
+the running turn, while `queue_next_turn` queues it for the next turn. Blocking
+questionnaires do not advertise and must reject that field.
+
+For async questions, the advertised native Other option opens a separate
+`free_text` step; it is not the blocking questionnaire's Notes workflow.
+An answer queued for the next turn uses the same exact question editor and
+must verify the injected answer before the final submit/queue key. If that
+editor closes or changes, input stops with an uncertain result and no retry.
+
+Collapsed async countdown redraws are not question changes: dispatch compares
+the independently parsed question, pending count, opening binding, subject and
+terminal identity, while retaining the rendered digest for evidence. A different
+question, count, input mode or binding still rejects before input.
+
+For managed user Send on profiled Codex 0.154.0/0.155.1 using Astra, animated
+empty Composer proof requires the full dim placeholder, styled marker and shared painted
+background, only the known decorated cells, and a complete supported footer.
+Activity, approval and input-owner checks run first. This proof does not grant
+native lifecycle or model-control authority. After the managed pre-text proof,
+user-explicit Send retains its one-paste/one-Enter contract without a post-text
+Composer veto.
+
+AKK still treats input ownership independently: an exact collapsed question
+summary leaves the main Composer sendable, while an expanded, clipped, or
+ambiguous async editor is a zero-input boundary so an explicit task cannot
+become a question answer. Response execution uses only semantic question and
+option identities; raw shortcut keys and menu indexes never cross the public
+contract. Codex 0.154.0 and 0.155.1 rely on exact version-bound TUI and durable
+task evidence. Notification and stable-question-identity response wrappers
+added on Codex main after 0.155.1 must not be assumed to exist in either
+release. The 0.154/0.155 active-writer `/resume` viewer is likewise read-only
+and receives no AKK terminal input.
+
+Codex 0.155.1 can also display native user-verification prompts for MCP
+requests. AKK classifies the exact prompt and waiting surfaces as blocked but
+never exposes them as approvable: completing platform user verification
+requires direct user presence and is outside terminal approval automation.
+
+## Delivery stages
+
+1. **Permission parity (implemented)**: expose `reject` only when an
+   adapter proves an exact safe native reject action; retain `approve_once`
+   compatibility.
+2. **Read-only projection (implemented)**: detect and report supported
+   questionnaire steps while changed or unsupported shapes remain manual.
+3. **Initial public response contract (implemented)**: enable one current
+   single-select, free-text, or confirmation step with pre-input fencing,
+   durable one-shot reservation, and uncertain-result audit.
+4. **Managed interaction callback (implemented)**: durably notify the owning
+   controller about each actionable current step, require a fresh Status call
+   before response, permanently fence a consumed prompt fingerprint from
+   replay, and notify the next distinct questionnaire step independently.
+5. **Expanded native coverage (not implemented)**: multi-select (tracked in
+   [#292](https://github.com/scotthuang/agent-knock-knock/issues/292)),
+   arbitrary per-option Notes, broader navigation, and more version profiles
+   only with captured fixtures and live regression evidence.
+6. **Host-native UX**: OpenClaw may render the projection using a future public
+   session-bound `requestUserInput` API. Until then, the structured AKK tool is
+   the authority boundary; a plugin must not use private Gateway methods.
+
+## Non-goals
+
+- no raw tmux keys, numeric menu indexes, or arbitrary labels in public tools;
+- no automatic permission decisions or persistent authorization grants;
+- no secret/password response relay;
+- no blind retry after possible input;
+- no attempt to emulate an arbitrary terminal UI.

package/docs/architecture/issue-126-final-report.md

@@ -0,0 +1,248 @@
+# Issue #126 architecture closeout report
+
+Status: the product architecture and production-source freeze are complete.
+Issue [#126](https://github.com/scotthuang/agent-knock-knock/issues/126)
+was closed as completed on 2026-08-20. Exact-head operational evidence is the
+remaining closeout step; four longitudinal measurements remain uncollected
+follow-up observations and are not claimed as completed by this report.
+
+This report is written against `main@61da2a6e482f96fb2b8d552fe4909d6e3ab09e64`.
+The production freeze is
+`49d351e8501efdb8814ba4d6646b8f7a81856cbc`: PRs #198 through #200 changed
+tests, test infrastructure, configuration, and documentation only, so the
+`src/**` tree at the report revision is byte-identical to that freeze.
+
+This document does **not** claim that the final full-suite median is at or below
+180 seconds, that the final dynamic subprocess comparison has passed, or that
+the final local OpenClaw build has been installed. Those are separate
+exact-SHA evidence steps described below.
+
+## Product problem and outcome
+
+At the v0.12.11 baseline, `src/cli-core.ts` owned 51.5 percent of production
+TypeScript. It mixed parsing and presentation with terminal authority,
+dispatch, lifecycle, callback, monitor, recovery, locks, and persistence. A
+normal change therefore touched a shared 38,005-line integration point and
+made ownership and durable-effect ordering difficult to review.
+
+Issue #126 applied a strangler refactor, moving characterized behavior behind
+typed policies, services, repositories, and adapters while preserving
+`parseCliCommand` and `executeCliCommand`. Each vertical now has a named owner
+and focused witnesses. Public CLI, OpenClaw, Session/Turn, Store, terminal, and
+callback contracts remain compatible; the 1,556-line core is composition and
+compatibility routing, not a second state-machine implementation.
+
+## Before and after
+
+The baseline is `ea592a88d7af4a709e7a7a1b989dd29e61932935`
+(`v0.12.11`, measured 2026-08-14). The after column is the production freeze
+carried unchanged by the report revision.
+
+| Metric | Baseline | Production freeze | Result |
+| --- | ---: | ---: | ---: |
+| Production TypeScript LOC | 73,792 | 93,322 | +19,530 (+26.5%) typed ownership and adapters |
+| Production modules | 38 | 125 | responsibilities split into reviewable owners |
+| `cli-core.ts` LOC | 38,005 | 1,556 | -36,449 (-95.9%) |
+| `cli-core.ts` share of production | 51.5% | 1.7% | -49.8 percentage points |
+| Production functions at or above 500 LOC | 9 | 0 | strict `<500` hard gate |
+| Maximum production function LOC / approximate complexity | 1,886 / c302 | separate maxima of 484 LOC and c49 at hard-gate closeout | strict `<500` / `<50`, no allowlist |
+| Production import cycles | 0 | 0 | acyclic throughout |
+| `openclaw-plugin.ts` entry LOC | 2,830 before its split | 67 | -2,763 (-97.6%) |
+| Included product-test subprocess sites | 48 | 19 | -60.42% static closeout |
+| Frozen affected-selector replay | — | 8 targeted / 2 full | 80% avoid full fallback; point evidence only |
+
+The production LOC increase is visible typed ownership, not generated code or
+generic bags. Exact manifest ratchets prevent the core or total from silently
+growing.
+
+## Canonical vertical ownership
+
+A CLI adapter may translate options, acquire its shell capabilities, call one
+use case, and present the result; it may not recreate the use case's decisions.
+
+| Vertical | Unique canonical authority | I/O and durable boundary | CLI/OpenClaw role |
+| --- | --- | --- | --- |
+| Terminal identity, binding, and actions | terminal binding/identity authority, terminal authority policy, and terminal action projection | terminal/process observations plus authoritative Session reads | list, status, send, approve, cancel, and lifecycle adapters consume the same decision facts |
+| Dispatch and acceptance | terminal dispatch policy/application, submission acceptance, receipt, ledger codec, repository, and recovery | exact terminal input, prepared/accepted receipt writes, ledger CAS and recovery | terminal command facade maps command options and presents the canonical result |
+| Native lifecycle | native-thread transition policy, application, settlement, verification, lifecycle query, and lifecycle CLI adapter | transition records, terminal observation/input, Session CAS, and recovery | New/Clear/Resume/inspect commands route to one lifecycle composition |
+| Deferred foreground handoff | deferred-foreground policy, preparation/application services, capability repositories, and authority adapter | append-only transfer/receipt history and terminal -> writer -> state transactions | ordinary send and recovery call the same handoff authority instead of copying it |
+| Callback and outbox | callback outbox policy, service, settlement, OpenClaw callback transport, and callback facade | immutable message/attempt state, Gateway process transport, retry ownership, and settlement events | callback/retry commands and monitors share one outbox implementation |
+| Monitor and reconciliation | monitor decision policy/application, state reconciliation, and supervision facade | polling observations, singleton process ownership, state/event writes, and callback preparation | monitor commands and OpenClaw supervision schedule the same services |
+| List, status, delegate, and maintenance | dedicated list, status-facts/status, delegate, and maintenance facades | bounded Store/terminal reads and explicit reconciliation-only mutations | default reads remain read-only; formatting does not grant mutation authority |
+| Persistence and locking | Store and Session repositories/codecs, durable JSON and dispatch-ledger I/O, mutation capabilities, and file-lock adapter | no-follow/atomic write, fsync/rename, revision/CAS, writer and state locks | services receive typed capabilities rather than raw paths or `*LockHeld` booleans |
+| Runtime and external adapters | async-local CLI runtime, tmux/Herdr providers, Codex/Claude adapters, OpenClaw Gateway adapter | process argv/env/cwd/timeout/exit, terminal screen/input, clocks and sleeps | entrypoints bind ports; policies do not import process or filesystem APIs |
+
+Six formerly duplicated status decisions are also frozen to a single source.
+Conversation release, Session-send blocking, and callback supersession belong
+to `protocol.ts`; deferred-transfer finality belongs to
+`deferred-foreground-transfer-policy.ts`; ordinary dispatch activity and
+recoverability belong to `terminal-dispatch-policy.ts`. Compiler-AST guards
+reject duplicate function definitions, copied exact tables, and bypass tables
+in other owners.
+
+## Service, CLI, and dependency boundaries
+
+Dependencies flow from CLI/OpenClaw entrypoints through typed composition,
+use cases, pure policies, and domain ports. Filesystem, Store, tmux, Herdr,
+Codex, Claude, and Gateway adapters implement those inward-facing ports.
+
+`src/cli.ts` is the sole production importer of `cli-core.ts`. The core keeps
+stable parser/executor exports, routing, composition, shared scopes, and
+compatibility presentation; it contains no send, lifecycle, monitor, or
+callback state machine. Its options are `Record<string, unknown>`, guarded in
+source and declarations against a returning raw-`any` bridge.
+
+Pure decisions import no filesystem, process, environment, clock, or sleep
+APIs. Services use typed ports; CLI adapters own option/path translation and
+transaction shells; infrastructure owns external semantics. Validation reports
+57 domains, 125 modules, 809 edges, zero cycles, and one core importer. Known
+domains select at most five focused integration witnesses; shared authorities
+still fail closed to the full tier.
+
+## OpenClaw boundary
+
+The OpenClaw entry is no longer a second orchestration monolith. Schemas owns
+the exact 14 tools; command adapter owns `/akk`, tool mapping and CLI process
+projection; callback adapter owns identity, approval, injection and delivery;
+supervisor owns non-overlapping monitor scheduling; helpers remains the shared
+parser/formatter owner; the 67-line entry owns metadata and ordered composition.
+
+The plugin family grew by 76 lines while its entry lost 2,763. The split added
+or removed no lock, durable write, process, timer, Gateway method, restart, or
+public tool contract. Exact schemas, tool order, callback identity, registration
+order, instance isolation, and supervision remain contract witnesses.
+
+## Compatibility, locking, and persistence invariants
+
+The refactor retains Store format 1, writer protocol 5, Session-authority
+protocol 3, managed Session schema/version 1, native-transition schema/version
+1, and readable deferred-foreground v1/v2. It also retains package/executable/
+plugin identities, `/akk`, 14 tools, CLI/public JSON/redaction/legacy decoding,
+and Codex/Claude plus tmux/Herdr identity, cwd, incarnation, and composer fences.
+
+The canonical mutation order remains:
+
+```text
+terminal dispatch lock -> Store writer lease -> conversation state lock
+```
+
+Capabilities are invocation-local, resource-bound, and invalidated before
+reverse-order lock release. A valid capability cannot be paired with another
+terminal, Store, state path, or transaction. Durable effects retain their
+original order: prepare before terminal input, text before exactly one Enter,
+Enter before native acceptance, and state before append-only event where the
+existing protocol requires it. Possible input, uncertain dispatch, uncertain
+approval, and uncertain lifecycle outcomes are never blindly retried.
+
+Callback preparation and state claiming remain inside their required writer
+and state boundaries; Gateway delivery occurs after the outer locks release.
+Callback progress, success, failure, retry scheduling, and accepted-transport
+recovery remain the responsibility of the canonical outbox settlement path.
+Lifecycle and deferred-transfer recovery retain their CAS and crash boundaries.
+Ledger and durable-file adapters retain no-follow opens, temporary writes,
+fsync, rename, directory fsync, and cleanup behavior.
+
+## Enforceable evidence at the production freeze
+
+The architecture closeout is guarded by checked-in machine-readable evidence,
+not only by this narrative:
+
+- exact ownership ratchets: 1,556 `cli-core.ts` lines and 93,322 production
+  lines;
+- a separate hard ceiling of 8,000 core lines that cannot be bypassed by
+  editing the ratchet to 8,001;
+- zero production functions reaching 500 LOC or c50, with no exception or
+  allowlist;
+- 57 domains, 125 modules, 809 edges, zero cycles, and the sole permitted core
+  importer;
+- 19 of the immutable 48 included product-test subprocess sites, a 60.42%
+  static reduction, while crash, lock, PID/SIGKILL, Gateway, terminal adapter,
+  and argv/exit witnesses remain process-backed;
+- a frozen ten-change affected-selector replay with eight targeted and two
+  full results; unknown/shared authority still selects full;
+- four public contracts, 65 witnesses, 11 migration mappings, the exact 14
+  OpenClaw tools, and five Store protocol witnesses;
+- compiler-AST guards for canonical status ownership, top-level core inventory,
+  forbidden owner returns, declarations, and dependency direction.
+
+The post-freeze test work preserves rather than weakens those contracts. PR
+#198 batches repeated Git metadata reads and replaces selected wall waits with
+real completion gates. PR #199 expands the canonical 97-test no-rollout file
+into eight worker-isolated shards while preserving the canonical manifest
+entry, test names, assertions, affected selection, and dynamic-evidence source
+identity. PR #200 adds explicitly scoped virtual clocks and direct recording
+terminal/process ports only for sequential deterministic fixtures; real timing,
+process death, concurrency, Gateway, SIGKILL, and terminal-input canaries remain.
+These facts describe test architecture, not final exact-head performance.
+
+## Merged delivery stages
+
+Issue #126 was merged incrementally so each authority and durable boundary
+could be reviewed independently:
+
+| PR stage | Merged PRs | Main result |
+| --- | --- | --- |
+| Baseline, safety characterization, and transaction foundations | #134-#148 | architecture/evidence baseline, action and binding authority, verified-dead policy, capability repositories, durable JSON/ledger codecs, approval and zero-input safety |
+| Test-loop seams and bounded infrastructure extraction | #149-#162 | in-process command seam with retained real boundaries, installer/doctor adapters, atomic ledger I/O, lifecycle reconciliation, acceptance and runtime evidence |
+| Vertical application services | #163-#174 | callback preparation, monitor decisions/application/reconciliation, dispatch application, lifecycle query/mutation/recovery, authority projection, deferred foreground recovery, dynamic subprocess evidence |
+| Typed CLI and repository facades | #175-#186 | list/file-lock/terminal-command facades, dispatch repository/recovery, runtime providers, acceptance, identity, prerequisites, lifecycle, deferred handoff, callback, and native transition composition |
+| Secondary facade and OpenClaw closeout | #187-#192 | delegate, monitor state, maintenance, monitor supervision, status facts/facade, and OpenClaw plugin split |
+| Enforceable architecture closure | #193-#197 | affected-selector gate, 60% static subprocess gate, zero-allowlist function gate, 1,556-line final core, typed-boundary/docs freeze |
+| Merged test-only performance remediation | #198-#200 | fast fixture cleanup, canonical no-rollout sharding, and scoped integration virtual-clock/direct-provider fixtures |
+
+The production source freeze is the result of #197. The last row is deliberately
+outside production ownership: the diff from #197 through #200 contains no
+`src/**` path.
+
+Two additional performance experiments are **not merged** and are not part of
+the production freeze or acceptance evidence:
+
+- `refactor/126-control-stale-direct@3ffa179312888ad7db97fdb74bb1001bd53beaef`;
+- the `refactor/126-callback-transport-profile` callback experiment.
+
+Results or local edits from either branch must not be quoted as main-branch
+behavior, included in final metrics, or installed into OpenClaw.
+
+## Pending exact-SHA validation and installation evidence
+
+The final point-in-time evidence will be recorded in an Issue #126 comment tied
+to one exact clean SHA. That comment, rather than this architecture report,
+will carry:
+
+- fast, integration, and full profiles each run three times from the same final
+  clean SHA on the same host with Node 24.18.0, concurrency four, and one shared
+  warm cache, together with their raw reports;
+- the final full-suite median comparison, without changing production timing
+  windows or default concurrency;
+- the dynamic subprocess attestation from one clean baseline full run and one
+  clean current full run, together with its retained real-process boundaries;
+- the exactly-once local OpenClaw install command and installer verification;
+- installed source, runtime, manifest, and skill hashes matched to the exact
+  repository SHA;
+- exactly one Gateway restart, readiness and smoke results, plus confirmation
+  that the protected user development process was not touched.
+
+Until that comment exists and its reports pass, this report makes no statement
+that the full tier is at or below 180 seconds and no statement that installation
+has completed.
+
+## Longitudinal measurements remain uncollected
+
+Issue #126 is already closed for the implementation refactor and will not be
+reopened by this closeout. Real post-refactor history has not yet established
+the four longitudinal measurements originally listed in the issue:
+
+1. at least 70% of normal product changes avoid `cli-core.ts`;
+2. at least 80% of normal affected-test loops finish within 60 seconds;
+3. five post-refactor product changes reduce median ready-to-release lead time
+   by at least 40%; and
+4. repeated full-suite flaky failures remain below 1%.
+
+The ten-change selector replay and any one exact-head profile are useful point
+evidence, but neither substitutes for these samples. The final closeout freezes
+the implementation and records these measurements as follow-up observations;
+it does not claim that they have been achieved.
+
+For the detailed extraction chronology and measurement definitions, see
+[orchestration-refactor.md](./orchestration-refactor.md) and
+[orchestration-baseline.json](./orchestration-baseline.json).