@scotthuang/agent-knock-knock 0.12.18 → 0.12.20

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.12.20 - 2026-08-28
+
+### Added
+
+- Add a durable `terminal_activity` / `best_effort` Watch fallback for an exact user-selected terminal when no unique provider task anchor is available. It arms on observed work or approval and reports stable idle only after two consecutive supervision sweeps.
+
+### Fixed
+
+- Keep an explicit read-only Watch available across managed ownership, missing action advertisement, lifecycle-binding gaps, agent/artifact version drift, an existing Watch, and malformed unrelated Watch records; these conditions now warn, reuse, or degrade instead of vetoing the user.
+- Recognize the Codex 0.149.1 `item_completed` `UserMessage` record as exact human-root evidence, including exact text and turn-identity validation.
+
+### Changed
+
+- Allow independent controller callback authorities to observe the same terminal while keeping same-target, same-controller Watch creation idempotent. Existing active Watches no longer hide the Watch action on terminal rows.
+- Expose immutable Watch warnings plus `watch_mode` and `confidence` in status and callbacks so exact task completion remains distinct from best-effort terminal activity becoming idle.
+
+### Security
+
+- Keep manual Watch observation-only: it acquires no terminal mutation authority, sends no input, changes no managed ownership, and never auto-approves. Creation still fails when the exact terminal is absent or unobservable, neither an exact anchor nor screen-status path exists, or durable Watch state cannot be written.
+
+## 0.12.19 - 2026-08-27
+
+### Added
+
+- Attach a durable Terminal Watch after a successful `terminal_user_explicit` unmanaged physical Send, restoring completion, failure, invalidation, and timeout callbacks without fabricating a managed Turn.
+
+### Changed
+
+- Advance the model-facing action contract to 23, Terminal Watch schema to v2, and Store writer protocol to 6 with compatible migration and normalization of existing records.
+
+### Security
+
+- Keep the user's explicit Send authoritative: Watch attachment and observation are best-effort, warning-only follow-up work and can never block, revoke, or automatically replay accepted terminal input.
+- Bind fallback callbacks to the exact Codex rollout or Claude transcript task accepted after the Send, including same-request races and completion before the first Watch sweep. Automatic fallback Watches do not emit approval callbacks; approval input remains manual.
+
 ## 0.12.18 - 2026-08-27
 
 ### Fixed

package/README.md

@@ -74,11 +74,11 @@ AKK connects OpenClaw to Codex or Claude Code already running inside a supported
 
 AKK is local-first. It has no hosted control plane or telemetry and does not change the coding agent's configured permission mode.
 
-AKK can also observe work that a human started directly in the Codex or Claude Code TUI. While that task is actively working or awaiting approval, refresh `/akk list` and use only the exact `watch` action advertised by that terminal row. Both the structured action and `/akk watch <exact-terminal-id>` take only that full `terminal_id`; AKK refreshes and revalidates the current terminal binding internally. It returns a durable `watch_id`, which is the only target for `/akk status <watch-id>` or `/akk unwatch <watch-id>`.
+AKK can also observe any exact Codex or Claude Code terminal the user explicitly selects. Refreshing `/akk list` is the safest way to copy its full `terminal_id` and any advertised `watch` action, but Watch advertisement is a convenience rather than authorization: `/akk watch <exact-terminal-id>` and `watch({terminal_id})` honor that explicit read-only intent even when the current row does not advertise Watch. A coding-agent version warning, missing or incompatible task artifact, or existing AKK-managed ownership is reported but does not veto creation. AKK fails only when the exact terminal does not exist, its endpoint/process cannot be identified, neither a durable exact-task anchor nor a read-only screen-status activity path exists, or the durable Watch Store cannot be created. The returned durable `watch_id` is the only target for `/akk status <watch-id>` or `/akk unwatch <watch-id>`.
 
-Terminal Watch is only for human-started external work. If that terminal already has an active AKK-managed Turn, list and status do not offer Watch and a direct Watch attempt is rejected; use the Turn's existing monitor, status, and callback path instead.
+A Terminal Watch is a separate schema-v2 aggregate, not an AKK Session or Turn. It sends no terminal input and does not adopt, claim, reserve, block, interrupt, approve, or otherwise change the selected task or any managed ownership. When AKK can construct a privacy-safe Codex rollout or Claude transcript task anchor, `watch_mode="exact_task"` and `confidence="exact"` follow that task and use its durable completion/failure evidence; missing or mismatched version evidence is only a warning and does not weaken an otherwise exact anchor. If artifact, native-task, or boundary evidence cannot establish a unique exact anchor at creation, AKK records warnings and falls back to `watch_mode="terminal_activity"`, `confidence="best_effort"`. That fallback watches only the exact terminal/process activity epoch: it must observe working or approval activity and then stable idle across consecutive sweeps before emitting its completion-shaped callback. The callback explicitly means “observed activity became idle”; it is not proof that one exact task completed successfully and carries no exact-task completion text. Exact-anchor drift still invalidates that exact Watch instead of following a successor task.
 
-A Terminal Watch is a separate schema-v1 aggregate, not an AKK Session or Turn. It sends no terminal input, does not adopt, claim, reserve, or block the human's task, and never auto-approves anything. An approval observation only notifies OpenClaw; the human must inspect and decide in the TUI. The Watch is pinned to the exact terminal/process/native-task identity and a privacy-safe Codex rollout or Claude transcript anchor. An exact durable completion already written to that anchor wins; otherwise any process, thread, endpoint, file, boundary, or fingerprint drift invalidates the Watch instead of following a successor task. Its settlement and notification outbox survive AKK or OpenClaw restarts, with leased retry and deterministic callback idempotency.
+An active AKK-managed Turn normally already has the better correlated monitor, so use it by preference; an explicit Watch is nevertheless allowed because it is read-only and does not replace or mutate that owner. Manual-Watch approval observations remain notification-only and must be decided by the human in the TUI. Separately, a successful `terminal_user_explicit` unmanaged fallback may automatically attach an exact request-hash-bound Watch after Send. Terminal Watch outcomes and notification outboxes survive AKK or OpenClaw restarts, with leased retry and deterministic callback idempotency.
 
 ### Terminal, native session, AKK session, and Turn
 
@@ -93,9 +93,9 @@ terminal resource / process incarnation
       └─ Turn 3 (turn_id)
 ```
 
-The v22 model-facing action contract remains semantic-ID only. `send(session_id, request)` is **session-scoped** (`session_exact`): it creates a new `turn_id` in that exact native coding-agent context and never silently follows a different thread now visible in the pane. `send(terminal_id, request)` may be managed follow-current (`terminal_follow_current`) or the user-priority physical-terminal path (`terminal_user_explicit`), exactly as advertised by the current row. `session_id` and `terminal_id` are mutually exclusive; callers may omit both only when AKK must prove one unique send-ready pane. Human-facing slash selectors remain a discovery convenience, but structured tools never carry selectors or opaque authority values. The trusted plugin/CLI derives fresh terminal, binding, candidate, prompt, composer, and handoff fences internally. Every mutation holds the terminal lock; managed operations additionally use Store locks, while unmanaged user-priority fallback deliberately does not depend on Store health. A managed send creates a Turn and binds only the single rollout that durably accepts that exact request. The `turn_id` is not a destination for later ordinary sends; it is the exact identity used for status, approval, cancellation, renewal, callback retry, close, and callback correlation. If a Turn is `waiting_for_openclaw`, `respond(turn_id, answer)` supplies the answer inside that same Turn instead of creating another one.
+The v23 model-facing action contract remains semantic-ID only. `send(session_id, request)` is **session-scoped** (`session_exact`): it creates a new `turn_id` in that exact native coding-agent context and never silently follows a different thread now visible in the pane. `send(terminal_id, request)` may be managed follow-current (`terminal_follow_current`) or the user-priority physical-terminal path (`terminal_user_explicit`), exactly as advertised by the current row. `session_id` and `terminal_id` are mutually exclusive; callers may omit both only when AKK must prove one unique send-ready pane. Human-facing slash selectors remain a discovery convenience, but structured tools never carry selectors or opaque authority values. The trusted plugin/CLI derives fresh terminal, binding, candidate, prompt, composer, and handoff fences internally. Every mutation holds the terminal lock; managed operations additionally use Store locks, while unmanaged user-priority fallback deliberately does not depend on Store health. A managed send creates a Turn and binds only the single rollout that durably accepts that exact request. The `turn_id` is not a destination for later ordinary sends; it is the exact identity used for status, approval, cancellation, renewal, callback retry, close, and callback correlation. If a Turn is `waiting_for_openclaw`, `respond(turn_id, answer)` supplies the answer inside that same Turn instead of creating another one.
 
-v15 generalized the human-priority Codex path; v18 preserves that safety while removing opaque fences from model arguments. It covers a status-card-only Session with no rollout, a quiescent managed pane whose exact open-rollout inventory is complete but cannot identify the foreground candidate, and a supported manual `/clear` whose new logical thread is visible before its rollout materializes. The complete exact inventory domain binds the provider terminal, PID and process birth, workspace and canonical endpoint, and every open rollout's UUID, descriptor, device, inode, canonical path, and pre-submit byte offset. Native foreground resolution may be unavailable only when that independent domain is complete and exact; an incomplete, missing, stale, or changed domain fails closed. A `/clear` resume hint is advisory only. Under the terminal lock, AKK isolates the old Session, creates a separate zero-UUID provisional Session and Turn, sends only the real task, and promotes that target only after the post-submit monitor finds a unique exact request acceptance in the pinned rollout domain. The resulting native UUID may match or differ from the old Session; it is never silently merged back into the predecessor. A rollout-backed Codex row therefore advertises `terminal_follow_current` with `terminal_id`, not `session_exact`; a cached or direct `session_exact` attempt revalidates under the terminal lock, rejects before task text, and never downgrades itself to the follow-current path. Only released predecessor Turn history from a strictly earlier binding epoch is excluded from current-send authority; unresolved current-epoch state still blocks the managed path. The freshly listed semantic-ID action can work in a narrow pane without `/status`. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If terminal delivery or native acceptance is uncertain, AKK does not retry the input. Explicit Close is the user's management escape hatch: AKK closes the selected Turn first, sends no terminal input, leaves the coding agent and pane running, and then best-effort releases only linked AKK metadata. Missing, malformed, stale, or newer cleanup records are preserved and reported as warnings instead of vetoing Close. Refresh the list afterward; if the coding agent is still working, Watch can observe it again. v19 and v20 introduced and expanded `terminal_user_explicit`; v22 supersedes their Composer-dependent Codex behavior. Codex eligibility now depends on the exact live terminal/process and a scanned, non-blocked approval state, not Composer visibility, stability, or exactness. Physical fallback always sends one `C-u`, injects the new request, waits through the paste window, and dispatches Enter exactly once; after injection, Composer observation cannot veto Enter. Claude Code user-explicit Send, native inspection, and native lifecycle input remain exact-empty-only. The managed fast path may require exact empty before input, but after user-explicit Codex text injection it follows the same no-Composer-veto Enter rule. Broken AKK Turn, Session, deferred-transfer, transition, ledger, or Store state cannot veto the user decision. AKK tries the managed fast path where it is eligible; otherwise it delivers the physical operation once as unmanaged work and then best-effort releases conflicting management. For an omitted target, AKK durably binds the `message_id` to the first selected physical terminal before input whenever runtime durability is available, so a retry cannot move the same request to another pane. An existing or possibly existing same-ID record rejects automatic replay. If no record exists and durability is unavailable, user priority wins: AKK proceeds with a warning, and strict cross-process replay or reselection protection is unavailable for that degraded invocation, so callers must not automatically retry its result. The fallback creates no callback Turn and sends no callback; once its sole mutation sequence begins, an uncertain result must not be retried automatically. Refresh the list and use Watch to observe the task.
+v15 generalized the human-priority Codex path; v18 preserves that safety while removing opaque fences from model arguments. It covers a status-card-only Session with no rollout, a quiescent managed pane whose exact open-rollout inventory is complete but cannot identify the foreground candidate, and a supported manual `/clear` whose new logical thread is visible before its rollout materializes. The complete exact inventory domain binds the provider terminal, PID and process birth, workspace and canonical endpoint, and every open rollout's UUID, descriptor, device, inode, canonical path, and pre-submit byte offset. Native foreground resolution may be unavailable only when that independent domain is complete and exact; an incomplete, missing, stale, or changed domain fails closed. A `/clear` resume hint is advisory only. Under the terminal lock, AKK isolates the old Session, creates a separate zero-UUID provisional Session and Turn, sends only the real task, and promotes that target only after the post-submit monitor finds a unique exact request acceptance in the pinned rollout domain. The resulting native UUID may match or differ from the old Session; it is never silently merged back into the predecessor. A rollout-backed Codex row therefore advertises `terminal_follow_current` with `terminal_id`, not `session_exact`; a cached or direct `session_exact` attempt revalidates under the terminal lock, rejects before task text, and never downgrades itself to the follow-current path. Only released predecessor Turn history from a strictly earlier binding epoch is excluded from current-send authority; unresolved current-epoch state still blocks the managed path. The freshly listed semantic-ID action can work in a narrow pane without `/status`. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If terminal delivery or native acceptance is uncertain, AKK does not retry the input. Explicit Close is the user's management escape hatch: AKK closes the selected Turn first, sends no terminal input, leaves the coding agent and pane running, and then best-effort releases only linked AKK metadata. Missing, malformed, stale, or newer cleanup records are preserved and reported as warnings instead of vetoing Close. Refresh the list afterward; if the coding agent is still working, Watch can observe it again. v19 and v20 introduced and expanded `terminal_user_explicit`; v22 supersedes their Composer-dependent Codex behavior. Codex eligibility now depends on the exact live terminal/process and a scanned, non-blocked approval state, not Composer visibility, stability, or exactness. Physical fallback always sends one `C-u`, injects the new request, waits through the paste window, and dispatches Enter exactly once; after injection, Composer observation cannot veto Enter. Claude Code user-explicit Send, native inspection, and native lifecycle input remain exact-empty-only. The managed fast path may require exact empty before input, but after user-explicit Codex text injection it follows the same no-Composer-veto Enter rule. Broken AKK Turn, Session, deferred-transfer, transition, ledger, or Store state cannot veto the user decision. AKK tries the managed fast path where it is eligible; otherwise it delivers the physical operation once as unmanaged work. v23 captures the exact provider byte boundary before that physical mutation and, after Enter succeeds, best-effort attaches a Terminal Watch bound to the request hash and physical Send token. That Watch supplies the completion callback without claiming a managed Turn. Watch preparation or persistence failure is only a callback warning: it never vetoes, revokes, or retries the successful Send. For an omitted target, AKK durably binds the `message_id` to the first selected physical terminal before input whenever runtime durability is available, so a retry cannot move the same request to another pane. An existing or possibly existing same-ID record rejects automatic replay, and a replay reports the same persisted Watch when present. If no record exists and durability is unavailable, user priority wins: AKK proceeds with a warning, and strict cross-process replay or reselection protection is unavailable for that degraded invocation, so callers must not automatically retry its result. Once the sole mutation sequence begins, an uncertain result must not be retried automatically. `watch-status` remains the recovery path for an attached fallback Watch.
 
 Approval remains separate from managed attribution. When `list` can prove one exact visible Codex approval prompt, it may advertise managed `approve({turn_id})` or terminal-scoped `approve({terminal_id})`; the latter remains possible when foreground rollout attribution is temporarily unavailable. The user must inspect and explicitly confirm that exact prompt. The plugin/CLI then keeps the confirmation offer private, recaptures the prompt, and revalidates the Store, terminal, process, and prompt fence under lock immediately before sending the exact key once. No token or fingerprint is transported through the model call. Terminal-scoped approval does not attribute the approval to a Turn, mutate Session identity, or create a durable approval receipt, so an uncertain transport result must not be retried blindly. It is never available to auto-approve. A changed prompt, identity, owner, or confirmation offer remains blocked.
 
@@ -103,7 +103,7 @@ The private approval fence remains prompt-scoped. AKK hashes the adapter-isolate
 
 Human-friendly selectors such as `only`, `codex`, `claude`, a terminal ID, or `@short-ref` remain a slash-command discovery layer. Structured model tools use semantic IDs instead: strict continuation pre-fills `session_id`, while terminal-scoped Send pre-fills `terminal_id`. Merely observing a mismatch or an unbound rollout inventory never mutates the Store. Managed Send remains available only when AKK can prove its complete managed authority and an exact empty Composer before input. A listed `terminal_user_explicit` action has the narrower user-priority boundary instead: one exact live physical terminal/process and a scanned, non-blocked approval state. Codex applies `replace_current_composer_and_submit`; its Composer may be invisible, truncated, unstable, empty, or nonempty. Claude remains exact-empty-only. Parsed working activity and AKK internal management or persistence damage do not suppress that action. Native inspection and native lifecycle input also remain exact-empty-only. Other actions likewise expose only their semantic identities, while opaque freshness fences are derived and consumed inside the trusted plugin/CLI boundary.
 
-An exact human switch while the old Session still has one active Turn is a decision point, not an automatic redirect. The terminal row may expose `handoff_decision` instead of a follow-current send. If the user chooses to close the old Turn, explicit Close takes priority and releases only its AKK management; it does not depend on the live native thread remaining unchanged, sends no terminal input, and does not stop the coding agent. Then list again and use only the newly advertised follow-current send or Watch action. Choosing `keep_source` changes no AKK state: restore the old native thread in the Codex or Claude TUI, then refresh the list.
+An exact human switch while the old Session still has one active Turn is a decision point, not an automatic redirect. The terminal row may expose `handoff_decision` instead of a follow-current send. If the user chooses to close the old Turn, explicit Close takes priority and releases only its AKK management; it does not depend on the live native thread remaining unchanged, sends no terminal input, and does not stop the coding agent. Then list again and use only the newly advertised follow-current send. A read-only Watch may be started for the exact selected terminal whether or not the row advertises it or the old Turn remains managed. Choosing `keep_source` changes no AKK state: restore the old native thread in the Codex or Claude TUI, then refresh the list.
 
 Native clear/new/resume operations requested through AKK are explicit lifecycle actions, separate from ordinary Turn creation. A successful new/clear creates a new native thread and AKK Session; resume activates the exact historical native thread and its corresponding Session. Each successful lifecycle transition creates no Turn. A human may also run native `/clear`, `/new`, `/resume`, or the equivalent directly in the shared terminal. AKK does not forbid that takeover: the next exact, fresh terminal-scoped follow-current send can absorb the human-driven transition when it is safe, while a `session_id` send deliberately remains pinned to its old context. AKK serializes either transition, verifies the resulting native identity, and advances the terminal binding generation so work and callbacks from the previous context cannot cross the boundary. Exact AKK-driven lifecycle profiles are regression-tested for Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1 and Claude Code 2.1.218/2.1.226/2.1.237. They are verification records, not an allowlist: another complete `x.y.z` version keeps Watch, native inspection, candidate discovery, new, and resume available through the generic runtime protocol, with a compatibility warning. Runtime structure and postconditions still decide success; a possibly submitted but unproven operation is reported as uncertain and is never retried automatically.
 
@@ -250,7 +250,7 @@ The core command surface is intentionally small:
 
 `/akk list` performs a controlled reconciliation across managed turns, and managed `/akk status` limits reconciliation to the selected turn. This can close records whose idle retention has elapsed and restore eligible missing monitors, but it does not send terminal input or retry managed-Turn callback delivery. A `watch_id` status reads that independent Watch record. The running OpenClaw supervisor coordinates two separate reconciliation passes every five seconds and at startup: one restores eligible `waiting_for_agent` Turn monitors, while the other observes active Terminal Watches and retries their durable callback outboxes. Each pass has its own error boundary, so one failure does not starve the other. Standalone shell queries are read-only unless their command explicitly reconciles, and resolving a selector never changes turn state.
 
-Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and `codex` or `claude` must identify exactly one eligible pane. These names and `@short-ref` are human-facing slash-command resolution inputs. The v22 structured model contract does not expose a `selector`: JSON actions carry an authoritative `session_id`, `terminal_id`, `turn_id`, `watch_id`, or other semantic entity ID. For ordinary send, exactly one of `session_id` and `terminal_id` may be supplied, or both may be omitted to require one unique send-ready pane. Approval likewise uses only `turn_id` or `terminal_id` after explicit confirmation. Before every terminal operation, AKK derives fresh opaque authority internally and revalidates the expected agent PID and provider-owned terminal identity. `terminal_user_explicit` additionally requires a scanned, non-blocked approval state. Codex Composer visibility, stability, exactness, and parsed working activity are not eligibility requirements; Claude still requires an exact empty Composer.
+Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and `codex` or `claude` must identify exactly one eligible pane. These names and `@short-ref` are human-facing slash-command resolution inputs. The v23 structured model contract does not expose a `selector`: JSON actions carry an authoritative `session_id`, `terminal_id`, `turn_id`, `watch_id`, or other semantic entity ID. For ordinary send, exactly one of `session_id` and `terminal_id` may be supplied, or both may be omitted to require one unique send-ready pane. Approval likewise uses only `turn_id` or `terminal_id` after explicit confirmation. Before every terminal operation, AKK derives fresh opaque authority internally and revalidates the expected agent PID and provider-owned terminal identity. `terminal_user_explicit` additionally requires a scanned, non-blocked approval state. Codex Composer visibility, stability, exactness, and parsed working activity are not eligibility requirements; Claude still requires an exact empty Composer.
 
 To ask AKK itself to change native context, first copy the full `terminal_id` from `/akk list`; lifecycle commands do not accept an ordinary-send `@short-ref` or loose agent selector. `/akk threads <exact-terminal-id>` lists exact, same-workspace candidates with a deterministic number, a collision-safe display-only `@short-id`, and the complete UUID. `/akk resume-thread <exact-terminal-id>` without a selection shows that list. A complete UUID remains compatible. A number or short ID resolves only against the latest list displayed in the same OpenClaw conversation incarnation; both expire after five minutes and fail after terminal, process, workspace, binding, candidate-set, or relevant action changes. AKK resolves that human navigation to the complete UUID and derives fresh private evidence under lock. `previous` (or `刚才那个`) is advertised only when the current Session's latest committed lifecycle transition identifies exactly one currently verified resumable source; it never guesses from title, recency, or static lineage. If `previous` is present, use only its exact prefilled semantic-ID action for a natural-language “刚才那个” request. Structured lifecycle mutations are `new_thread({terminal_id})` and `resume_thread({terminal_id,native_thread_id})`. AKK does not poll bindings or adopt observed switches in the background: a human-driven switch is adopted only as part of an explicit, fresh terminal-scoped send. If a recorded owner process exits, the next lifecycle listing can classify that sole historical binding as resumable, and the resume mutation compare-and-swap detaches it before touching the terminal. Stale, expired, unsupported, busy, ambiguous, active-elsewhere, or unverifiable transitions fail closed. Do not ask AKK to send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, or `/btw`, Claude `/branch`, or any other first-line native slash command as an ordinary task or answer; use an advertised AKK action, express the request in natural language, or enter an unsupported native command manually in the terminal UI.
 
@@ -258,15 +258,15 @@ The number and short-ID resume forms refer only to that displayed snapshot; neit
 
 To request a native Codex status card or Claude Status panel, first run `agent_knock_knock_list` and use only that terminal row's advertised `native_inspect({terminal_id,inspection:"status"})` action. The structured tool schema is closed to those two semantic fields; callers cannot provide `/status`, another slash command, or an authority token. AKK serializes the inspection with terminal mutations, derives and revalidates its private binding fence and exact terminal identity, and returns only after it proves one fresh bounded status result and an idle postcondition. Codex status probes additionally require an exact viewport of at least 80 columns to preserve the full Session UUID, cross the versioned paste-settle boundary, and dispatch Enter exactly once. An initially narrow or unknown viewport fails before text input with a widen/zoom diagnostic; post-injection viewport or composer drift fails closed before Enter and leaves the draft for manual inspection. Codex `/status` and that viewport requirement apply only to operations that must prove the UUID before terminal input. An otherwise eligible terminal-scoped ordinary task can send once and bind from exact native acceptance afterward, so it does not run `/status` or fail merely because the pane is narrow. For Claude, the inspection safely dismisses the exact modal once. It never turns ordinary `send` or `respond` into a slash-command escape hatch.
 
-The current OpenClaw surface registers 16 tools, and the top-level v22 `action_contracts` documents Terminal Watch alongside closed native inspection, user-priority current-pane Send/approval, lifecycle, and Turn actions. Every model-facing action carries semantic IDs only; opaque freshness and compare-and-swap fences stay inside the trusted plugin/CLI boundary. `available_actions` remains the authority for ordinary current actions. A listed `terminal_user_explicit` Send prioritizes the user's exact live physical terminal/process over broken AKK internal state. Codex physical fallback replaces the current Composer with the new request and submits once without a post-text Composer veto; Claude remains empty-only. AKK attempts managed delivery where eligible, then may deliver unmanaged without a callback before attempting best-effort management release. Refresh and use Watch afterward. Explicit Close is always available for a selected managed Turn after user confirmation, including deferred-transfer and handoff conflicts; it releases AKK management without terminal input or stopping the coding agent. A terminal row may also expose a nested `blocking_turns[].recovery_action` for the same user-owned Close. Invoke the advertised semantic-ID action, then refresh the list before doing anything else.
+The current OpenClaw surface registers 16 tools, and the top-level v23 `action_contracts` documents Terminal Watch alongside closed native inspection, user-priority current-pane Send/approval, lifecycle, and Turn actions. Every model-facing action carries semantic IDs only; opaque freshness and compare-and-swap fences stay inside the trusted plugin/CLI boundary. `available_actions` remains the authority for ordinary current actions. Read-only Watch is the deliberate exception: once the user supplies one exact listed `terminal_id`, missing Watch advertisement, agent-version or artifact uncertainty, and managed ownership are warnings rather than authorization vetoes. A listed `terminal_user_explicit` Send prioritizes the user's exact live physical terminal/process over broken AKK internal state. Codex physical fallback replaces the current Composer with the new request and submits once without a post-text Composer veto; Claude remains empty-only. AKK attempts managed delivery where eligible, then may deliver unmanaged and attach an exact Terminal Watch callback without creating a managed Turn. Watch failure is reported without changing delivery. Explicit Close is always available for a selected managed Turn after user confirmation, including deferred-transfer and handoff conflicts; it releases AKK management without terminal input or stopping the coding agent. A terminal row may also expose a nested `blocking_turns[].recovery_action` for the same user-owned Close. Invoke the advertised semantic-ID action, then refresh the list before doing anything else.
 
 For natural-language tool use, `agent_knock_knock_list` is terminal-first. Each live pane appears exactly once in `terminals[]`; `process_state` reports whether its coding-agent process is alive and `activity_state` reports the parsed screen state. `managed.session_id` identifies the continuing AKK session, `managed.current_turn` is its optional active Turn, and `managed.recent_turn` is retained history; retained Turns do not occupy the terminal. A human-driven native-thread mismatch remains honestly classified as `management_state="conflict"`; its `handoff_state` is `external_handoff_adoptable` only when the row advertises the fenced follow-current `send`, otherwise it is `external_handoff_blocked`. `management_state="unavailable"` means only that AKK's management projection could not be read; the separately observed live terminal facts and any advertised `terminal_user_explicit` Send remain authoritative. Listing never performs the adoption. Pass `all=true` to include older entries in `managed.history`. By default, `unavailable_managed_turns[]` contains attention-needed records whose pane cannot be presented as a live terminal; `all=true` also includes retained unavailable history.
 
-Use only an `available_actions` entry returned in the current list, begin with its prefilled semantic IDs, and supply every `missing_required` field. The only additional action sources are a terminal row's nested `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`; both require explicit user confirmation. When advertised, a managed Session's strict send uses `send({session_id,request})` and creates a new Turn only in that Session's native context. Terminal-scoped Send uses `send({terminal_id,request})`. A `terminal_user_explicit` action is the user-priority path: healthy AKK state still takes the managed fast path where its exact-empty pre-input requirements hold, while Codex physical fallback always replaces the current Composer with the request and submits it once without a post-text Composer veto. Claude can fall back only from an exact empty Composer. Unmanaged delivery has no callback and is followed by best-effort management release. Refresh the list and use Watch afterward. Structured Send never exposes a selector, draft text, or composer authority. `respond` and managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` only after explicit confirmation. Native inspection uses `{terminal_id,inspection:"status"}`. Other raw controls may be used only through the exact action their row advertises. `timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK derives fresh opaque fences and revalidates availability under lock before every side effect.
+Except for read-only Watch, use only an `available_actions` entry returned in the current list, begin with its prefilled semantic IDs, and supply every `missing_required` field. A user-explicit Watch may instead pass one exact listed `terminal_id` directly; the absence of `available_actions.watch` does not veto observation. The only other action sources are a terminal row's nested `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`; both require explicit user confirmation. When advertised, a managed Session's strict send uses `send({session_id,request})` and creates a new Turn only in that Session's native context. Terminal-scoped Send uses `send({terminal_id,request})`. A `terminal_user_explicit` action is the user-priority path: healthy AKK state still takes the managed fast path where its exact-empty pre-input requirements hold, while Codex physical fallback always replaces the current Composer with the request and submits it once without a post-text Composer veto. Claude can fall back only from an exact empty Composer. Unmanaged delivery creates no managed callback Turn; after successful Enter, AKK best-effort attaches an exact Terminal Watch callback. Attachment failure is a warning and never changes the Send result. Structured Send never exposes a selector, draft text, or composer authority. `respond` and managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` only after explicit confirmation. Native inspection uses `{terminal_id,inspection:"status"}`. Other raw controls may be used only through the exact action their row advertises. `timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK derives fresh opaque fences and revalidates availability under lock before every side effect.
 
 On first attach, the target terminal must be explicitly named by the user; AKK never guesses which already-running pane should receive a task.
 
-The top-level v22 action contracts include `watch` and `unwatch` as well as `send`, manual `approve`, `native_inspect`, `list_resumable_threads`, `new_thread`, `resume_thread`, and conflict-only `reconcile_binding`. Their model-facing mutation shapes are deliberately small: `watch({terminal_id})`; `send({session_id|terminal_id,request})` with the targets mutually exclusive; managed `approve({turn_id})` or terminal-scoped `approve({terminal_id})`; `native_inspect({terminal_id,inspection})`; `new_thread({terminal_id})`; `resume_thread({terminal_id,native_thread_id})`; and `reconcile_binding({terminal_id,conflicting_session_id})`. The listed Send scope distinguishes managed delivery from `terminal_user_explicit`; the latter is gated by exact terminal/process identity and scanned, non-blocked approval state, not AKK management health or Codex Composer observation, and an unmanaged fallback has no callback. Approval, handoff takeover, and reconciliation require explicit user confirmation, but none transports a token, revision, binding ID/generation, candidate or composer fence, handoff-only live-native-UUID fence, or approval fingerprint through the model. `native_thread_id` remains the intentional semantic identity for resume. `watch` returns a `watch_id`; Watch status and `unwatch` use only that ID. Human-facing resume numbers and short IDs remain conversation-scoped navigation aids that AKK resolves to the complete native thread ID before the structured action. Orphan close retains `expected_message_id` or `expected_transition_id` because those are entity identities, not opaque authority tokens. The plugin/CLI derives and revalidates all freshness fences privately under the canonical locks. Store format remains 1 and writer protocol remains 5.
+The top-level v23 action contracts include `watch` and `unwatch` as well as `send`, manual `approve`, `native_inspect`, `list_resumable_threads`, `new_thread`, `resume_thread`, and conflict-only `reconcile_binding`. Their model-facing mutation shapes are deliberately small: `watch({terminal_id})`; `send({session_id|terminal_id,request})` with the targets mutually exclusive; managed `approve({turn_id})` or terminal-scoped `approve({terminal_id})`; `native_inspect({terminal_id,inspection})`; `new_thread({terminal_id})`; `resume_thread({terminal_id,native_thread_id})`; and `reconcile_binding({terminal_id,conflicting_session_id})`. Watch status exposes `watch_mode` and `confidence`: exact provider evidence yields `exact_task`/`exact`, while the terminal-activity fallback yields `terminal_activity`/`best_effort` plus creation warnings. The listed Send scope distinguishes managed delivery from `terminal_user_explicit`; the latter is gated by exact terminal/process identity and scanned, non-blocked approval state, not AKK management health or Codex Composer observation. An unmanaged fallback creates no managed Turn but can return `callback_mode="terminal_watch"` and a durable `watch_id`. Approval, handoff takeover, and reconciliation require explicit user confirmation, but none transports a token, revision, binding ID/generation, candidate or composer fence, handoff-only live-native-UUID fence, or approval fingerprint through the model. `native_thread_id` remains the intentional semantic identity for resume. `watch` returns a `watch_id`; Watch status and `unwatch` use only that ID. Human-facing resume numbers and short IDs remain conversation-scoped navigation aids that AKK resolves to the complete native thread ID before the structured action. Orphan close retains `expected_message_id` or `expected_transition_id` because those are entity identities, not opaque authority tokens. The plugin/CLI derives and revalidates all freshness fences privately under the canonical locks. Store format remains 1 and writer protocol remains 6.
 
 Workspace is not a routing boundary. AKK can list, inspect, and control verified panes across projects; when more than one target matches, choose one listed `terminal_id` for a structured tool or one listed selector for a slash command.
 
@@ -405,7 +405,7 @@ than a publishing prerequisite.
 
 Managed state now lives in the stable `~/.agent-knock-knock/store` root. Its manifest prevents an incompatible AKK writer from changing authoritative Session or Turn state. Directories use mode `0700`; state and log files use `0600`.
 
-The manifest checks storage format and writer behavior separately. An unknown `format_version` is not read. The current writer protocol is 5, and writer protocols 1, 2, 3, and 4 are its supported predecessors: inspection reports them as `upgradeable`. Upgrading protocol 1 or 2 validates predecessor Turn records, deterministically derives and durably materializes authoritative Session records, and quarantines ambiguous Session bindings before atomically publishing protocol 5. Protocols 3 and 4 already have Session authority, so their upgrade is an atomic manifest-only writer fence with no data migration. Existing Turn state and event logs remain unchanged, and the manifest's `created_at` is preserved. Any other writer-protocol mismatch remains readable for normal queries, while explicit reconciliation reports `skipped` and every mutation fails closed before terminal or Gateway side effects.
+The manifest checks storage format and writer behavior separately. An unknown `format_version` is not read. The current writer protocol is 6, and writer protocols 1 through 5 are its supported predecessors: inspection reports them as `upgradeable`. Upgrading protocol 1 or 2 validates predecessor Turn records, deterministically derives and durably materializes authoritative Session records, and quarantines ambiguous Session bindings before atomically publishing protocol 6. Protocols 3, 4, and 5 already have Session authority, so their upgrade is an atomic manifest-only writer fence with no data migration. Protocol 6 prevents an older writer from silently rejecting or damaging v2 Terminal Watch records. Existing Turn state and event logs remain unchanged, and the manifest's `created_at` is preserved. Any other writer-protocol mismatch remains readable for normal queries, while explicit reconciliation reports `skipped` and every mutation fails closed before terminal or Gateway side effects.
 
 The former `~/.agent-knock-knock/conversations` directory is left untouched; AKK does not read or migrate it. Existing Codex and Claude Code tmux panes remain available through live discovery, while their old managed-turn IDs, callback associations, and legacy conversation aliases are not carried into the new Store. Compatible future upgrades continue using the stable Store rather than creating a directory per package version.
 

package/dist/src/claude-local-transcript-provider.d.ts

@@ -113,6 +113,22 @@ export type ClaudeDeadProcessCompletionObservation = {
     status: "unverifiable";
     reason: string;
 };
+export type ClaudeUserExplicitFallbackTranscriptObservation = {
+    status: "pending";
+    acceptance?: ClaudeTranscriptAcceptanceEvidence;
+    observedEndOffsetBytes?: number;
+} | {
+    status: "completed";
+    acceptance: ClaudeTranscriptAcceptanceEvidence;
+    completion: TerminalCompletionEvidence;
+    observedEndOffsetBytes: number;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+export interface ObserveClaudeUserExplicitFallbackTranscriptOptions extends Omit<DetectClaudeTranscriptCompletionOptions, "agentRows"> {
+    acceptanceEvidence?: unknown;
+}
 export interface ClaudeHistoricalSessionSummary {
     id: string;
     cwd: string;
@@ -203,6 +219,21 @@ export declare function observeClaudeDeadProcessTranscriptCompletion(request: Te
  * idle because the row is normally written while Claude is working.
  */
 export declare function detectClaudeTranscriptAcceptance(request: TerminalDurableCompletionRequest, options: DetectClaudeTranscriptCompletionOptions): ClaudeTranscriptAcceptanceEvidence | undefined;
+/**
+ * Observe one user-explicit fallback request without persisting its raw text.
+ * The immutable pre-send transcript byte anchor plus the SHA-256 request hash
+ * must identify exactly one post-anchor root prompt.
+ */
+export declare function detectClaudeTranscriptAcceptanceByHash(request: TerminalDurableCompletionRequest, options: DetectClaudeTranscriptCompletionOptions): ClaudeTranscriptAcceptanceEvidence | undefined;
+export declare function detectClaudeTranscriptCompletionByHash(request: TerminalDurableCompletionRequest, options: DetectClaudeTranscriptCompletionOptions): TerminalCompletionEvidence | undefined;
+/**
+ * Observe a fallback Watch from its immutable pre-send transcript anchor.
+ * Once acceptance has been persisted, the native prompt UUID becomes the
+ * sole prompt selector so a later identical request cannot redirect the
+ * Watch. This path intentionally requires only the durable transcript: a
+ * completed callback remains recoverable after the pane or agent row exits.
+ */
+export declare function observeClaudeUserExplicitFallbackTranscript(request: TerminalDurableCompletionRequest, options: ObserveClaudeUserExplicitFallbackTranscriptOptions): ClaudeUserExplicitFallbackTranscriptObservation;
 /**
  * Detects exactly one unresolved foreground Bash tool use for the current
  * AKK-managed Claude turn. It uses the same anchored, owner-private,
@@ -210,3 +241,4 @@ export declare function detectClaudeTranscriptAcceptance(request: TerminalDurabl
  * closed on identity changes, completed turns, background work, or ambiguity.
  */
 export declare function detectClaudeTranscriptPendingApproval(request: TerminalDurableCompletionRequest, options: DetectClaudeTranscriptCompletionOptions): ClaudeTranscriptPendingApprovalEvidence | undefined;
+export declare function claudeTranscriptAnchorFingerprint(anchor: ClaudeTranscriptAnchor): string;

package/dist/src/claude-local-transcript-provider.js

@@ -1258,6 +1258,87 @@ export function detectClaudeTranscriptAcceptance(request, options) {
     }
     return acceptanceEvidenceFromSnapshot(snapshot);
 }
+/**
+ * Observe one user-explicit fallback request without persisting its raw text.
+ * The immutable pre-send transcript byte anchor plus the SHA-256 request hash
+ * must identify exactly one post-anchor root prompt.
+ */
+export function detectClaudeTranscriptAcceptanceByHash(request, options) {
+    const snapshot = readClaudeTranscriptTurnSnapshot(request, options, undefined, "live_monitor", "hash_only");
+    return snapshot ? acceptanceEvidenceFromSnapshot(snapshot) : undefined;
+}
+export function detectClaudeTranscriptCompletionByHash(request, options) {
+    const snapshot = readClaudeTranscriptTurnSnapshot(request, options, "idle", "live_monitor", "hash_only");
+    return snapshot ? completionFromRecords(snapshot) : undefined;
+}
+/**
+ * Observe a fallback Watch from its immutable pre-send transcript anchor.
+ * Once acceptance has been persisted, the native prompt UUID becomes the
+ * sole prompt selector so a later identical request cannot redirect the
+ * Watch. This path intentionally requires only the durable transcript: a
+ * completed callback remains recoverable after the pane or agent row exits.
+ */
+export function observeClaudeUserExplicitFallbackTranscript(request, options) {
+    try {
+        const sessionId = nonEmptyString(request.sessionId);
+        const requestHash = nonEmptyString(request.requestHash);
+        if (!sessionId || !requestHash) {
+            throw new Error("Claude fallback transcript request identity is unavailable");
+        }
+        const persistedAcceptance = options.acceptanceEvidence === undefined
+            ? undefined
+            : validateTerminalSubmissionAcceptanceEvidence(options.acceptanceEvidence, {
+                source: "claude_transcript",
+                nativeThreadId: sessionId,
+                requestHash
+            });
+        const acceptedPromptUuid = persistedAcceptance
+            ? uuidValue(persistedAcceptance.acceptanceId)
+            : undefined;
+        if (persistedAcceptance && !acceptedPromptUuid) {
+            throw new Error("persisted Claude fallback acceptance has no exact prompt UUID");
+        }
+        const snapshot = readClaudeTranscriptTurnSnapshot(request, { ...options, agentRows: [] }, undefined, "durable_fallback", "hash_only", acceptedPromptUuid);
+        if (!snapshot) {
+            return { status: "pending" };
+        }
+        const observedAcceptance = acceptanceEvidenceFromSnapshot(snapshot);
+        if (!observedAcceptance) {
+            if (persistedAcceptance) {
+                throw new Error("the exact accepted Claude fallback prompt is absent from its transcript");
+            }
+            return {
+                status: "pending",
+                observedEndOffsetBytes: snapshot.observedEndOffsetBytes
+            };
+        }
+        if (persistedAcceptance) {
+            assertSameClaudeTranscriptAcceptance(persistedAcceptance, observedAcceptance, snapshot);
+        }
+        const completion = completionFromRecords(snapshot, {
+            requireVerifiableCompletionSignal: true
+        });
+        if (!completion) {
+            return {
+                status: "pending",
+                acceptance: persistedAcceptance ?? observedAcceptance,
+                observedEndOffsetBytes: snapshot.observedEndOffsetBytes
+            };
+        }
+        return {
+            status: "completed",
+            acceptance: persistedAcceptance ?? observedAcceptance,
+            completion,
+            observedEndOffsetBytes: snapshot.observedEndOffsetBytes
+        };
+    }
+    catch (error) {
+        return {
+            status: "unavailable",
+            reason: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
 function acceptanceEvidenceFromSnapshot(snapshot) {
     const prompt = matchingManagedPrompt(snapshot);
     if (!prompt) {
@@ -1333,9 +1414,9 @@ export function detectClaudeTranscriptPendingApproval(request, options) {
     }
     return pendingApprovalFromRecords(snapshot);
 }
-function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus, readMode = "live_monitor") {
+function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus, readMode = "live_monitor", requestIdentity = "text_and_hash", acceptedPromptUuid) {
     const unavailable = (reason) => {
-        if (readMode === "verified_dead_process") {
+        if (readMode !== "live_monitor") {
             throw new Error(reason);
         }
         return undefined;
@@ -1354,9 +1435,10 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus,
     if (!sessionId ||
         !cwd ||
         !expectedRequestHash ||
-        !requestTextHash ||
-        !expectedPromptText ||
-        expectedRequestHash !== requestTextHash ||
+        (requestIdentity === "text_and_hash" &&
+            (!requestTextHash ||
+                !expectedPromptText ||
+                expectedRequestHash !== requestTextHash)) ||
         startedAtMs === undefined ||
         capturedAtMs === undefined) {
         return unavailable("Claude transcript request metadata cannot be verified");
@@ -1371,17 +1453,19 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus,
     if (runtimePid === undefined || runtimePid !== anchor.pid) {
         throw new Error("Claude transcript anchor PID does not match the active terminal runtime");
     }
-    const agent = exactInteractiveAgent(options.agentRows, anchor.pid);
-    if (!agent) {
-        throw new Error("the exact Claude process is absent from the local agent registry");
-    }
-    if (agent.startedAt !== anchor.agent_started_at_ms ||
-        agent.sessionId !== sessionId ||
-        normalizePath(agent.cwd) !== normalizePath(cwd)) {
-        throw new Error("the Claude process session identity changed after the managed send");
-    }
-    if (requiredAgentStatus && agent.status !== requiredAgentStatus) {
-        return unavailable(`the exact Claude process is ${agent.status}, not ${requiredAgentStatus}`);
+    if (readMode !== "durable_fallback") {
+        const agent = exactInteractiveAgent(options.agentRows, anchor.pid);
+        if (!agent) {
+            throw new Error("the exact Claude process is absent from the local agent registry");
+        }
+        if (agent.startedAt !== anchor.agent_started_at_ms ||
+            agent.sessionId !== sessionId ||
+            normalizePath(agent.cwd) !== normalizePath(cwd)) {
+            throw new Error("the Claude process session identity changed after the managed send");
+        }
+        if (requiredAgentStatus && agent.status !== requiredAgentStatus) {
+            return unavailable(`the exact Claude process is ${agent.status}, not ${requiredAgentStatus}`);
+        }
     }
     const projectsRoot = projectsRootPath(path.resolve(options.claudeHome ?? defaultClaudeHome()));
     if (!isRealDirectory(projectsRoot)) {
@@ -1408,7 +1492,7 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus,
         if (bytesToRead > maxTurnBytes) {
             throw new Error("Claude transcript turn exceeded the bounded local read limit");
         }
-        if (readMode === "verified_dead_process" &&
+        if (readMode !== "live_monitor" &&
             !fileEndsWithNewline(opened.fd, opened.stat.size)) {
             throw new Error("Claude transcript ends with an incomplete JSONL record");
         }
@@ -1428,6 +1512,7 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus,
             cwd,
             expectedRequestHash,
             expectedPromptText,
+            ...(acceptedPromptUuid ? { expectedPromptUuid: acceptedPromptUuid } : {}),
             transcriptFileId: transcriptFileId(sessionId, fileIdentity),
             observedEndOffsetBytes: opened.stat.size
         };
@@ -1441,8 +1526,9 @@ function matchingManagedPrompt(snapshot) {
         const promptText = userPromptText(record);
         const exactPromptIdentity = snapshot.expectedPromptUuid
             ? uuidValue(record.uuid) === snapshot.expectedPromptUuid
-            : snapshot.expectedPromptText !== undefined &&
-                exactPromptText(promptText) === snapshot.expectedPromptText;
+            : snapshot.expectedPromptText !== undefined
+                ? exactPromptText(promptText) === snapshot.expectedPromptText
+                : exactRequestFingerprint(promptText) === snapshot.expectedRequestHash;
         return record.type === "user" &&
             isRecord(record.message) &&
             record.message.role === "user" &&
@@ -2385,7 +2471,7 @@ function exactRequestFingerprint(value) {
     const text = String(value ?? "");
     return text ? createHash("sha256").update(text).digest("hex") : undefined;
 }
-function claudeTranscriptAnchorFingerprint(anchor) {
+export function claudeTranscriptAnchorFingerprint(anchor) {
     return sha256Hex(JSON.stringify({
         schema: "agent-knock-knock/claude-transcript-acceptance-anchor",
         version: 1,