@scotthuang/agent-knock-knock 0.16.0 → 0.16.2

package/docs/operator-guide.md

@@ -36,6 +36,67 @@ fields in List does not mean Send had no monitoring. See
 [List and Watch inventory](list-output.md) for the 24-hour query window,
 48-hour eligible-history retention and separate Desktop catalog cursor.
 
+## What can I do with this conversation?
+
+Read the guidance beside each conversation. It explains what works now, what
+is preventing other operations, and the next step. The controller should give
+this explanation in your language instead of asking you to interpret internal
+error codes. It changes when the conversation's state changes.
+
+| What List shows | What to do |
+| --- | --- |
+| Can send and watch | Send a new task when offered, or ask AKK to watch the task already running. |
+| Can send, but no active task to watch | Send your task. Monitoring starts with that Send; keep its returned task reference. An idle conversation is usable. |
+| Can send to a window whose native conversation is unverified | Select that exact terminal's offered Send. AKK can enter text and submit Enter, but you must inspect the result in the window because native acceptance and completion are unproven. |
+| Window is in the background-session interface | Use its physical Send if offered and inspect the result there. If Send is unavailable, continue manually or open an ordinary foreground Claude conversation and refresh List. |
+| Can only inspect or watch the terminal and cannot identify the Claude conversation | AKK has retried identification without typing into the terminal. Use the original terminal to finish or safely stop any work, then follow the recovery steps below. |
+| Needs approval or management recovery | Open Status for that exact conversation or task and follow its currently offered response or recovery action. |
+| Details omitted from this List page | Open Status for that row. Missing details do not mean the conversation lacks those features. |
+
+For a sendable background window, the instruction means:
+
+> 可以向此窗口发送任务。AKK 会输入文字并提交，但目前无法可靠确认后台任务的接受和完成状态；请在窗口中查看执行结果。
+
+Choose the exact terminal entry and its offered Send action. This is ordinary
+terminal input, not a direct background-worker connection, and it does not
+promise a task-completion callback. An existing managed task that failed is not
+automatically retried through this route. If input might already have happened,
+inspect the original result before considering another send.
+
+If the window is showing a background conversation and physical Send is not
+offered, you can keep working in the current window manually. An ordinary
+foreground Claude conversation can instead provide native task identity and
+monitoring when those operations are offered. Reopening the same background
+conversation after restarting will not add that proof. Neither option converts
+the existing background conversation or transfers its work. In the inspected
+Claude Code 2.1.295 installation,
+`tclaude attach --help` documents `Ctrl+Z` as returning to the shell while the
+background session keeps running; check the installed command's help before
+applying that shortcut to another runtime or interface.
+
+If Claude remains unidentified and List cannot confirm that more specific
+background-view explanation:
+
+1. Open the named pane in Herdr or tmux and check what is running there. You can
+   continue using Claude directly. If its current physical Send action is
+   offered, you can also select that terminal for input while inspecting the
+   result manually.
+2. After finishing or safely stopping any current work, exit Claude with `/exit`
+   and relaunch it with your usual command in the same project directory. If
+   resuming history opens a background conversation, use the guidance above
+   instead of repeatedly restarting.
+3. Refresh AKK List and select the newly identified conversation. Do not resend a
+   task whose earlier delivery is uncertain; inspect its saved task reference.
+4. If the row still cannot receive work, keep using that terminal directly and
+   report the discovery limitation. A missing or failed diagnostic check does
+   not prove a background conversation or a reader bug. Relaunching can refresh
+   registration, but cannot guarantee a repair.
+
+You do not need to restart the controller Host for this recovery attempt. A
+terminal Watch can report terminal activity while identity is unresolved; it
+cannot promise exact task completion. A count of related managed Sessions is
+history, not proof that this newly discovered conversation is currently bound.
+
 ## Command reference
 
 Direct slash commands are available in every first-party Host integration:
@@ -170,21 +231,32 @@ input-owning questionnaire, editor, menu, or read-only viewer. Broken AKK Turn,
 Session, transfer, transition, ledger, or Store state cannot veto the user's
 explicit Send within the same Store authority. A conflicting or unfinished
 cross-Store authority transfer still blocks input, including physical fallback.
-Neither can parsed working activity, an existing draft, or
-ordinary Composer visibility, stability, or exactness. Codex physical fallback
-sends `C-u` once. Claude Code physical fallback 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. Each
+For Codex, neither can parsed working activity, an existing draft, or
+ordinary Composer visibility, stability, or exactness. Claude physical Send
+requires an empty recognized main Composer, no existing stashed draft, a known native footer, and no running
+or unproven foreground turn; background shells alone do not block it. Codex physical fallback
+sends `C-u` once. Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each
 then injects the new request,
 waits through the paste window, and dispatches Enter exactly once. After text
 injection, Composer observation cannot veto Enter. Unreviewed Codex fullscreen
 frontends additionally require a recognizable styled Composer before clearing
 and a fresh empty Composer afterward, before any task text is sent.
 
-AKK first takes the managed path where its stronger pre-input requirements
-hold. Otherwise it may deliver unmanaged work once and best-effort attaches a
-Terminal Watch that provides the completion callback. Exact preparation failure falls back to a request-correlated terminal-activity
-Watch when the physical identity and observation path remain valid. Its callback
+Claude physical-input preparation finishes before task text or Enter. A visible `› stashed` indicator refuses the attempt before any terminal input. When no stash is shown, AKK rechecks the empty main Composer and uses `C-s` once to restore any hidden stash. If content appears, it stops and leaves that content in the input box for the user; it does not re-stash or delete it. If the probe or final empty check is uncertain, it stops without task text or Enter and does not retry the key. This replaces the former sentinel transaction: no new marker is written and no editing keys delete a draft. There is no Composer observation or cleanup after task text or Enter. Ordinary managed Sends, Codex clearing and independent Watch monitoring are unchanged. This is refusal with manual recovery, not a guarantee of protecting drafts against simultaneous human input; avoid typing in the pane during an attempt. Screen capture and key delivery are not an atomic keyboard lock. A transport acknowledgement cannot prove that Claude processed `Ctrl+S`; ignored keys or cropped native indicators can leave stash occupancy unproven. AKK does not overwrite that unknown slot with a marker.
+
+If List or Send reports a stashed draft, open that exact window and wait for the foreground turn to finish. Preserve any visible draft first. With the main input box empty, press `Ctrl+S` once to restore the stash, then save, send, or clear it yourself before refreshing List. AKK cannot identify hidden content just from the stash label. If restoration reveals `[AKK replacing current draft ...]`, it may be residue from an older failed AKK cleanup: remove only that marker after checking the text, preserve any other content, and do not press Enter on the marker. `Draft restored` is a transient restore notification; an accompanying `› stashed` still reports an occupied slot and remains a refusal condition. Do not repeatedly toggle `Ctrl+S` or retry an uncertain AKK attempt automatically.
+
+Within an explicitly selected physical-input operation, AKK can use managed
+delivery where its stronger pre-input requirements hold. Otherwise that
+operation may deliver unmanaged input once and best-effort attach the strongest
+safe Terminal Watch available. A verified exact-task Watch can provide a
+completion callback; that proof is not supplied by a physical dispatch receipt.
+An ordinary Claude managed Send does not change to physical input after failure.
+Read the actual receipt: absent native identity
+means acceptance and completion remain unproven, including for a window showing
+a background conversation. Exact preparation failure may leave a
+request-correlated terminal-activity Watch when the physical identity and
+observation path remain valid. Its callback
 reports stable idle with best-effort confidence, never exact task success.
 Watch persistence failure never vetoes, revokes, or retries a successful
 Send. Uncertain native probe input or unsafe input surfaces stop before task

package/docs/quickstart-herdr.md

@@ -26,7 +26,7 @@ Wait for the empty idle composer. After the AKK OpenClaw plugin is installed and
 
 AKK enumerates every running local Herdr session, identifies a terminal by its session socket plus stable `terminal_id`, and treats the current `pane_id` only as a refreshable route. Moving a live pane does not silently rebind ownership. Every side effect revalidates the terminal resource, shell PID, agent PID, cwd, native-session evidence, and current composer first.
 
-The v31 structured model contract carries semantic IDs only. Ordinary send is `send({session_id,request})` for strict continuation or `send({terminal_id,request})` for the current verified Herdr pane; the targets are mutually exclusive. An advertised `terminal_user_explicit` action keeps the user's Send independent of broken AKK management state and ordinary Composer visibility, stability, exactness, or existing draft contents. It requires the exact live terminal/process, a scanned non-blocked approval state, and no proven questionnaire, editor, menu, history search, or read-only viewer that owns input. The agent-neutral `terminal_user_explicit_composer_policy` advertises `replace_current_composer_and_submit`; the older Codex-named field remains a compatibility alias. Codex freezes the open-rollout candidate set and sends `C-u` once to replace the current Composer; 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. Each then injects the request, waits through the paste window, and dispatches Enter exactly once without a post-text Composer veto. For Codex, a unique exact request acceptance promotes the provisional Session/Turn even when `/clear` delayed creation of the foreground rollout; zero or ambiguous matches never cause replay. If managed promotion cannot be prepared before input, AKK still sends once, best-effort attaches an exact Terminal Watch, and releases stale management. After exact request acceptance, that Watch can notify the owning controller of a questionnaire and broker one explicitly chosen response through Status plus `respond_interaction({watch_id,...})`; before acceptance, or when only best-effort activity evidence exists, it remains notification-only. Watch failure never changes delivery. Native inspection and lifecycle input remain exact-empty-only. Send results expose physical dispatch, agent acceptance, management, and observation separately. Watch and native/lifecycle actions likewise expose `terminal_id` (plus `inspection` or `native_thread_id` where applicable), never a pane route, selector, draft text, composer digest, token, fingerprint, revision, or binding generation. AKK resolves the current Herdr route and derives all opaque freshness fences privately, then revalidates them under lock before terminal input. Once clear or request input may have occurred, an uncertain result must not be retried automatically.
+The v31 structured model contract carries semantic IDs only. Ordinary send is `send({session_id,request})` for strict continuation or `send({terminal_id,request})` for the current verified Herdr pane; the targets are mutually exclusive. An advertised `terminal_user_explicit` action keeps the user's Send independent of broken AKK management state within the same Store authority; cross-Store conflicts remain fenced. Codex does not require an empty visible Composer. Claude requires a recognized empty main Composer, no existing stashed draft, a known footer, and no running or unproven foreground turn. It requires the exact live terminal/process, a scanned non-blocked approval state, and no proven questionnaire, editor, menu, history search, or read-only viewer that owns input. Action contract v35 advertises `terminal_user_explicit_composer_policy=per_agent`: Codex uses `replace_current_composer_and_submit`, while Claude uses `require_empty_composer_and_submit` with the additional no-existing-stash rule. The older Codex-named field remains a compatibility alias. Codex freezes the open-rollout candidate set and sends `C-u` once to replace the current Composer; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each then injects the request, waits through the paste window, and dispatches Enter exactly once without a post-text Composer veto. For Codex, a unique exact request acceptance promotes the provisional Session/Turn even when `/clear` delayed creation of the foreground rollout; zero or ambiguous matches never cause replay. If managed promotion cannot be prepared before input, AKK still sends once, best-effort attaches an exact Terminal Watch, and releases stale management. After exact request acceptance, that Watch can notify the owning controller of a questionnaire and broker one explicitly chosen response through Status plus `respond_interaction({watch_id,...})`; before acceptance, or when only best-effort activity evidence exists, it remains notification-only. Watch failure never changes delivery. Native inspection and lifecycle input remain exact-empty-only. Send results expose physical dispatch, agent acceptance, management, and observation separately. Watch and native/lifecycle actions likewise expose `terminal_id` (plus `inspection` or `native_thread_id` where applicable), never a pane route, selector, draft text, composer digest, token, fingerprint, revision, or binding generation. AKK resolves the current Herdr route and derives all opaque freshness fences privately, then revalidates them under lock before terminal input. Once clear or request input may have occurred, an uncertain result must not be retried automatically.
 
 For a physically exact, exact-empty idle Codex pane with ambiguous rollout identity, a fresh row may advertise `identify_foreground` and `identify_and_send`. The diagnostic action changes no AKK Store record but sends `/status` exactly once through the same visible Herdr pane; its 30-second proof grants no later authority. The atomic action retains the canonical Herdr terminal lock across the probe and one task, while exact request acceptance remains the only durable Session/Turn identity. List and Status never run the probe. Codex 0.158.0/0.159.0/0.159.2 exact Send and active-task Watch use a separate closed `/status` transaction to bind the foreground paginated thread. The three status axes remain independent: `screen_state` describes the live TUI, `native_identity_state` describes foreground identity resolution, and `durable_activity_state` describes exact artifact-backed work; legacy `activity_state` stays conservative for compatibility.
 

package/docs/quickstart-tmux.md

@@ -34,7 +34,7 @@ tmux new-session -s akk-work -c "$(pwd -P)" codex
 
 Use `claude` instead of `codex` to share a Claude Code terminal. Wait until the coding agent is authenticated and showing its idle prompt. Detach from tmux with `Ctrl-b`, followed by `d`.
 
-AKK discovers supported Codex and Claude Code panes across workspaces. Before acting, it revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories still match. Managed Send requires a verified idle prompt; an advertised user-explicit physical Send may steer a working Codex or Claude Code pane when its scanned, non-blocked approval boundary remains valid and no proven questionnaire, editor, menu, or read-only viewer owns input. An existing draft or ordinary Composer uncertainty does not veto that explicit Send.
+AKK discovers supported Codex and Claude Code panes across workspaces. Before acting, it revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories still match. Managed Send requires a verified idle prompt; an advertised user-explicit physical Send may steer a working Codex pane when its scanned, non-blocked approval boundary remains valid and no proven questionnaire, editor, menu, or read-only viewer owns input. An existing draft or ordinary Composer uncertainty does not veto Codex explicit Send. Claude physical Send instead requires an empty recognized main Composer, a known native footer, and no running or unproven foreground turn. Background shells alone do not block it.
 
 ## 3. Run doctor
 
@@ -58,7 +58,9 @@ Doctor verifies the installed plugin and skill, Gateway health, tmux, and at lea
 /akk inspect this repository and summarize it
 ```
 
-The bare task works when exactly one send-ready coding-agent pane exists across all workspaces. Send-ready means an exact live terminal/process, a scanned non-blocked approval state, and no proven questionnaire, editor, menu, or read-only viewer that owns input. Parsed working activity, an existing draft, and ordinary main-Composer visibility, stability, or exactness do not veto this user-priority path. Profiled Codex 0.154.0/0.155.1 collapsed async-question summaries remain sendable, while their expanded, clipped, or ambiguous editors receive zero AKK input. Codex physical fallback sends `C-u` once to replace the current Composer; 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. Each then injects the request, waits through the paste window, and dispatches Enter exactly once without a post-text Composer veto. Broken AKK management state does not veto this user-explicit Send. If more than one pane is eligible, AKK stops instead of guessing: run `/akk list`, then use `/akk <selector>: <message>`, for example:
+Claude physical-input preparation finishes before task text or Enter. A visible `› stashed` indicator refuses the attempt before any terminal input. When no stash is shown, AKK rechecks the empty main Composer and uses `C-s` once to restore any hidden stash. If content appears, it stops and leaves that content in the input box for the user; it does not re-stash or delete it. If the probe or final empty check is uncertain, it stops without task text or Enter and does not retry the key. This replaces the former sentinel transaction: no new marker is written and no editing keys delete a draft. There is no Composer observation or cleanup after task text or Enter. Ordinary managed Sends, Codex clearing and independent Watch monitoring are unchanged. This is refusal with manual recovery, not a guarantee of protecting drafts against simultaneous human input; avoid typing in the pane during an attempt.
+
+The bare task works when exactly one send-ready coding-agent pane exists across all workspaces. Send-ready means an exact live terminal/process, a scanned non-blocked approval state, and no proven questionnaire, editor, menu, or read-only viewer that owns input. For Codex, parsed working activity, an existing draft, and ordinary main-Composer visibility, stability, or exactness do not veto this user-priority path. Claude requires an empty recognized main Composer, no existing stashed draft, a known native footer, and no running or unproven foreground turn; background shells alone do not block it. Profiled Codex 0.154.0/0.155.1 collapsed async-question summaries remain sendable, while their expanded, clipped, or ambiguous editors receive zero AKK input. Codex physical fallback sends `C-u` once to replace the current Composer; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each then injects the request, waits through the paste window, and dispatches Enter exactly once without a post-text Composer veto. Broken AKK management state does not veto this user-explicit Send. If more than one pane is eligible, AKK stops instead of guessing: run `/akk list`, then use `/akk <selector>: <message>`, for example:
 
 ```text
 /akk @a1b2c3d4: inspect this repository and summarize it
@@ -68,7 +70,7 @@ Success returns a managed turn and, when the work finishes, its result. The same
 
 `/akk list` keeps that physical pane as the primary resource: it appears once in `terminals[]`. Read `screen_state` for the bounded live TUI, `native_identity_state` for foreground native-session resolution, and `durable_activity_state` for exact rollout/transcript task evidence. The legacy `activity_state` remains conservative for compatibility, so an idle screen can coexist with ambiguous native identity, unknown durable activity, and legacy `activity_state="unknown"`. These status axes are diagnostic; use only a current `available_actions` entry for mutations. Its managed context follows terminal → native coding-agent session → AKK `session_id` → Turns. AKK places the active Turn under `managed.current_turn`, or the newest retained Turn under `managed.recent_turn`; retained Turns do not occupy or hide the pane.
 
-For another request, refresh `/akk list` and use only that terminal row's listed v31 `send` action. A `session_exact` action carries `session_id`; `terminal_follow_current` and user-priority `terminal_user_explicit` actions carry `terminal_id`. Add only the new request text. The two target fields are mutually exclusive, and a structured model call never carries a selector, draft text, composer digest, or opaque token. AKK derives and revalidates its freshness fences internally. Managed delivery may require exact empty before input and creates a new `turn_id`; native inspection and lifecycle input remain exact-empty-only. Codex and Claude Code `terminal_user_explicit` advertise the agent-neutral `terminal_user_explicit_composer_policy=replace_current_composer_and_submit`; the older Codex-named field remains a compatibility alias. Codex freezes every open rollout as a candidate instead of trusting one stale root as the foreground thread, then binds the uniquely accepting rollout after Enter. For either agent, once the managed path injects user-explicit text or physical fallback runs, Composer observation cannot veto the one Enter after injection. If managed promotion is unavailable, the physical fallback creates no managed callback Turn; after Enter, AKK best-effort attaches an exact Terminal Watch callback and returns its `watch_id`. Once exact request acceptance is established, that Watch can notify and—after a same-controller Status refresh plus an explicit user answer—respond to a supported native interaction. Before acceptance and for best-effort activity Watches, interaction handling remains notification-only. Attachment failure is a warning and never changes delivery. Check `terminal_input_dispatched` separately from `agent_acceptance`, `management_mode`, and `observation_mode`; once clear or request input may have occurred, an uncertain result must not be retried automatically. A completed Turn is history, not the destination of the next send. Human-friendly selectors such as `codex`, `only`, or `@a1b2c3d4` remain slash-command discovery conveniences; they are not structured action authority.
+For another request, refresh `/akk list` and use only that terminal row's listed v31 `send` action. A `session_exact` action carries `session_id`; `terminal_follow_current` and user-priority `terminal_user_explicit` actions carry `terminal_id`. Add only the new request text. The two target fields are mutually exclusive, and a structured model call never carries a selector, draft text, composer digest, or opaque token. AKK derives and revalidates its freshness fences internally. Managed delivery may require exact empty before input and creates a new `turn_id`; native inspection and lifecycle input remain exact-empty-only. Codex and Claude Code `terminal_user_explicit` advertise different Composer policies in action contract v35: Codex keeps `replace_current_composer_and_submit`, while Claude uses `require_empty_composer_and_submit`. The static `terminal_user_explicit_composer_policy=per_agent` points to `terminal_user_explicit_composer_policies`; the older Codex-named field remains a compatibility alias. Codex freezes every open rollout as a candidate instead of trusting one stale root as the foreground thread, then binds the uniquely accepting rollout after Enter. For either agent, once the managed path injects user-explicit text or physical fallback runs, Composer observation cannot veto the one Enter after injection. If managed promotion is unavailable, the physical fallback creates no managed callback Turn; after Enter, AKK best-effort attaches an exact Terminal Watch callback and returns its `watch_id`. Once exact request acceptance is established, that Watch can notify and—after a same-controller Status refresh plus an explicit user answer—respond to a supported native interaction. Before acceptance and for best-effort activity Watches, interaction handling remains notification-only. Attachment failure is a warning and never changes delivery. Check `terminal_input_dispatched` separately from `agent_acceptance`, `management_mode`, and `observation_mode`; once clear or request input may have occurred, an uncertain result must not be retried automatically. A completed Turn is history, not the destination of the next send. Human-friendly selectors such as `codex`, `only`, or `@a1b2c3d4` remain slash-command discovery conveniences; they are not structured action authority.
 
 If the coding agent asks a question and the active Turn becomes `waiting_for_openclaw`, use the listed `respond` action with its prefilled `turn_id`, or the equivalent form:
 
@@ -138,6 +140,21 @@ Copy the row's complete `terminal_id`. An advertised `available_actions.watch` i
 
 Watch follows the exact terminal selected by the user. Codex 0.158.0/0.159.0/0.159.2 exact Watch creation types a closed `/status` command into an available main Composer to bind its foreground task; later observation is read-only. See the [compatibility boundaries](codex-0.159.2-compatibility.md). Agent-version or artifact uncertainty, missing binding metadata, existing AKK-managed ownership, and missing action advertisement produce warnings rather than blocking creation. AKK fails only when the exact terminal is absent, its endpoint/process cannot be identified, neither an exact durable task anchor nor a read-only screen-status path exists, or its durable Store record cannot be created. Prefer an existing managed monitor when its exact Turn attribution is what you need, but Watch can coexist without adopting or mutating it. New exact-task Watches and accepted exact-request fallback Watches default to `respond_when_exact`; a supported native interaction emits `interaction_required`, and the owning controller must call Status before it receives a single-use response offer. Terminal-activity/best-effort Watches and manual-only shapes emit `interaction_manual_required` with `capabilities.interaction_respond=false`.
 
+Starting with AKK 0.16.2, a degraded activity Watch can omit optional native
+UUID/birth metadata while retaining every process fence that was observed. A
+missing process directory may fall back to the same selected terminal's absolute
+path; if neither source supplies one, no new Watch is saved. Refresh discovery
+and retry observation after the directory is available; do not resend an already
+dispatched task to repair monitoring.
+
+During fallback observation, temporarily unreadable identity or workspace
+metadata leaves the Watch pending so a later sweep can retry. A proven terminal,
+PID, endpoint, incarnation or directory difference still terminates observation.
+An unavailable fact cannot hide a separately proven mismatch and does not
+authorize approval or question input. This change does not repair the separate
+Host-restart recovery paths for already-existing exact Watches or notification
+outboxes, and does not turn stable terminal idle into exact task success.
+
 The result contains a durable `watch_id`. Use that ID—not a `session_id`, `turn_id`, terminal selector, or short reference—to inspect or stop observation:
 
 ```text

package/docs/testing.md

@@ -216,10 +216,7 @@ 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
+fail-closed. Codex `terminal_user_explicit` proves 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 requires a recognized empty main Composer, no existing stash, a known footer and a quiescent foreground turn. Its single `C-s` probe on that empty Composer may restore a hidden draft; restored content refuses submission and remains for the user. Visible stash refusal precedes all input, and neither sentinel insertion nor draft deletion is performed. An uncertain probe is not automatically retried. 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Delegate to existing Codex CLI, Codex Desktop, and Claude Code sessions from OpenClaw or compatible controller Hosts, with native direct control and supported terminal fallbacks.",
   "license": "MIT",
   "type": "module",

package/templates/openclaw-skills/agent-knock-knock/SKILL.md

@@ -23,6 +23,14 @@ Keep the user's requested scope and approval boundaries. Do not expand a task, a
 
 Present `conversations[]` as **CLI** or **Desktop** using `surface`, and keep Codex/Claude Code as the agent type. Select the displayed `conversation_id` and its advertised operation; AKK chooses the connection internally. Do not make separate user-facing backend and terminal lists, repeat raw discovery arrays, or count Watches as additional conversations or tasks. Preserve unavailable actions, current questions/approvals, and management/recovery records. Scoped controls, when present, are operations on exact targets within a row, not extra conversations.
 
+Explain each row's `usage` in the user's language: `summary` says whether it can be used now, `available` says what for, `limitations` explains what is unavailable, and `next_steps` gives concrete actions. Do not merely show missing capability switches or internal error codes. Guidance is recomputed from current actions, activity and blockers; it neither grants authority nor overrides `available_actions`. An idle native Claude conversation without Watch is still usable when Send is offered: send the requested task and retain its automatically created Turn or Watch. A terminal-only Watch observes terminal activity, not exact native task completion.
+
+An unresolved Claude terminal receives one additional fresh reader check during List, shared across unresolved panes in that scan, without terminal input. A separate read-only check can explain that the foreground window is in the background-session interface only when its owned registry and live process incarnation verify that role. This role does not mean the window cannot receive input. When its real `terminal_user_explicit` Send is offered, explain: 可以向此窗口发送任务。AKK 会输入文字并提交，但目前无法可靠确认后台任务的接受和完成状态；请在窗口中查看执行结果。 Without that physical action, the user can continue manually or start an ordinary foreground conversation and refresh List. Reopening the same background conversation does not add native acceptance or completion proof. This diagnostic never binds a background worker, grants actions, or authorizes daemon/claim-socket access.
+
+To use that offered physical action, explicitly select its displayed `terminal_id` and call the existing `agent_knock_knock_send({terminal_id,request})`. AKK consumes the displayed private action internally; do not invent a public scope parameter or provide a private token. An ordinary managed Send must not silently switch to physical input after failure. Physical dispatch can prove text injection and Enter only as reported in its receipt; do not turn it into native acceptance, successful task completion or a promised completion callback. Check the actual window result, and never replay uncertain input through another route.
+
+If identity remains unresolved and the more specific diagnostic is missing, invalid, stale or unavailable, keep the uncertainty and actual options: use the offered physical Send for that exact terminal with its stated proof limits, or inspect the original pane, continue manually, and retry ordinary startup/List refresh as appropriate. Missing native identity alone is not an input veto. Do not infer a background conversation or reader bug from missing evidence, promise that restart repairs discovery, substitute a background or same-directory agent, or replay an uncertain Send. A positive `managed.session_count` is a count of related current/historical Sessions, not current binding authority; null Session IDs and absent `binding_status` mean no authoritative current Session was selected.
+
 Default CLI presentation prefers the verified backend entry for a one-to-one same-agent/project discovery pair without known identity conflicts. Use that returned conversation ID and its actions directly; do not search for or choose an alternative transport. Its title, state and actions belong to the selected backend. Presentation preference does not prove a terminal alias, copy terminal permissions, or redirect a previously selected terminal ID. Multiple candidates, conflicts and terminal attention/recovery records remain visible. Proven exact aliases still combine verified controls. Use `terminalDebug: true` (CLI `list --terminal-debug`) only when connection diagnostics are needed, not as a routine selection step. Unnamed, unstarted Codex candidates beside an established same-project conversation may be folded for display; `conversation_presentation.unstarted_candidates_omitted` reports their count and `diagnostic_query` expands them. This does not prove abandonment or an exact alias. If the requested new empty session is missing, use that query and its original exact ID; never substitute the established conversation. Sole or exactly associated new sessions remain visible, and a first task restores ordinary display.
 
 For new Codex sends, AKK prefers the verified shared backend and retains an eligible terminal path when that backend is unavailable. For new Claude Code sends, AKK automatically prefers a managed terminal Turn when a unique controllable tmux/Herdr counterpart proves the same native session and process; without that terminal it uses the native inbox and returns a native Watch. The controller selects the conversation, not the transport or management mode. Busy/blocked state, identity conflict, ownership conflict or a Store error cannot authorize bypass to native delivery. Targeted reads can still use the exact backend; an idle terminal may use the advertised `/status` inspection to learn its identity, while working or blocked terminals are not interrupted. List itself sends no terminal input. Keep an uncertain dispatch receipt and inspect it instead of retrying through another connection.
@@ -122,7 +130,11 @@ Core slash-command forms:
 
 The `terminal_user_explicit` physical-delivery rules below describe retained legacy routes/receipts and other explicitly advertised fallback paths. New ordinary Claude sends use managed terminal delivery; Store or ownership failure does not degrade them to unmanaged work.
 
-For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v31 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. The agent-neutral `terminal_user_explicit_composer_policy` advertises `replace_current_composer_and_submit`; the old Codex-named field is a v28 compatibility alias only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is either managed `terminal_follow_current` or user-priority `terminal_user_explicit`, exactly as advertised; the two target fields are mutually exclusive, and both may be omitted only when AKK must prove one unique send-ready pane. The following `terminal_user_explicit` rules apply to retained legacy receipts and other advertised physical fallback paths; new ordinary Claude Sends require a managed Turn and do not use Store or ownership failure to authorize unmanaged input. For those physical paths, Codex and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer—not ordinary main-Composer visibility, stability, exactness, parsed working activity, existing draft contents, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. Both advertise `replace_current_composer_and_submit`: Codex physical fallback sends `C-u` once; Claude Code physical fallback 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. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. Native inspection and native lifecycle input remain exact-empty-only. With runtime durability, an omitted target binds its `message_id` to the first selected physical terminal and existing or uncertain same-ID evidence rejects replay. If fresh durability is unavailable, user priority wins: AKK proceeds with a warning, and the degraded result must not be automatically retried. Once clear or request input may have occurred, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. The only non-ordinary Send form is an exact `send({turn_id})` copied unchanged from a current `available_actions.retry_submission`; it accepts no request text or other target and requires explicit user confirmation. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Other managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity and revalidate the relevant approval prompt; Composer revalidation remains action-specific; unreviewed Codex frontends require the styled-Composer checks above.
+For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v31 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. Action contract v35 uses `terminal_user_explicit_composer_policy=per_agent` with `terminal_user_explicit_composer_policies`: Codex keeps `replace_current_composer_and_submit`, while Claude uses `require_empty_composer_and_submit`; the old Codex-named field is a v28 compatibility alias only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is either managed `terminal_follow_current` or user-priority `terminal_user_explicit`, exactly as advertised; the two target fields are mutually exclusive, and both may be omitted only when AKK must prove one unique send-ready pane. The following `terminal_user_explicit` rules apply to explicitly selected physical terminal actions and retained legacy receipts; ordinary Claude managed Sends never use failure as permission to switch to physical input. For those physical paths, Codex and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer. AKK Store, Turn, Session, transfer, transition, ledger, or ownership records do not establish that physical input is unsafe; cross-Store authority remains fenced. For Codex, ordinary main-Composer visibility, stability, exactness, parsed working activity and existing draft contents remain advisory. Claude instead requires an empty recognized main Composer, no existing stashed draft, a known native footer, and no running or unproven foreground turn; background shells alone do not block it. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. The per-agent policies preserve the following clearing mechanics: Codex physical fallback sends `C-u` once; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. Native inspection and native lifecycle input remain exact-empty-only. With runtime durability, an omitted target binds its `message_id` to the first selected physical terminal and existing or uncertain same-ID evidence rejects replay. If fresh durability is unavailable, user priority wins: AKK proceeds with a warning, and the degraded result must not be automatically retried. Once clear or request input may have occurred, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. The only non-ordinary Send form is an exact `send({turn_id})` copied unchanged from a current `available_actions.retry_submission`; it accepts no request text or other target and requires explicit user confirmation. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Other managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity and revalidate the relevant approval prompt; Composer revalidation remains action-specific; unreviewed Codex frontends require the styled-Composer checks above.
+
+Claude physical-input preparation finishes before task text or Enter. A visible `› stashed` indicator refuses the attempt before any terminal input. When no stash is shown, AKK rechecks the empty main Composer and uses `C-s` once to restore any hidden stash. If content appears, it stops and leaves that content in the input box for the user; it does not re-stash or delete it. If the probe or final empty check is uncertain, it stops without task text or Enter and does not retry the key. This replaces the former sentinel transaction: no new marker is written and no editing keys delete a draft. There is no Composer observation or cleanup after task text or Enter. Ordinary managed Sends, Codex clearing and independent Watch monitoring are unchanged. This is refusal with manual recovery, not a guarantee of protecting drafts against simultaneous human input; avoid typing in the pane during an attempt. Screen capture and key delivery are not an atomic keyboard lock. A transport acknowledgement cannot prove that Claude processed `Ctrl+S`; ignored keys or cropped native indicators can leave stash occupancy unproven. AKK does not overwrite that unknown slot with a marker.
+
+If List or Send reports a stashed draft, open that exact window and wait for the foreground turn to finish. Preserve any visible draft first. With the main input box empty, press `Ctrl+S` once to restore the stash, then save, send, or clear it yourself before refreshing List. AKK cannot identify hidden content just from the stash label. If restoration reveals `[AKK replacing current draft ...]`, it may be residue from an older failed AKK cleanup: remove only that marker after checking the text, preserve any other content, and do not press Enter on the marker. `Draft restored` is a transient restore notification; an accompanying `› stashed` still reports an occupied slot and remains a refusal condition. Do not repeatedly toggle `Ctrl+S` or retry an uncertain AKK attempt automatically.
 
 The human-priority Codex path may proceed when the pane/process and complete open-rollout candidate inventory are exact even though no single foreground UUID can be selected, including a supported manual `/clear` whose new logical thread appears 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. A `/clear` resume hint is advisory only, never routing or acceptance authority. Under the terminal lock, AKK isolates the predecessor, creates a separate zero-UUID provisional Session and Turn, sends the real task once, and binds only the single candidate rollout that durably accepts that exact request. A rollout-backed Codex row therefore advertises `terminal_follow_current` with `terminal_id`, not `session_exact`; a cached strict Session attempt rejects before task text and never downgrades itself. Only released predecessor Turn history from a strictly earlier binding epoch is excluded from current-send authority; unresolved current-epoch state still blocks. Use only the freshly listed semantic-ID action. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If delivery or acceptance is uncertain, do not retry automatically. Terminal-scoped manual Codex approval likewise exposes only `terminal_id`, requires explicit confirmation, leaves managed identity unchanged, never participates in auto-approval, and must not be retried blindly after an uncertain result.
 
@@ -138,7 +150,7 @@ AKK discovers eligible panes across workspaces. When more than one target matche
 
 Natural-language forms:
 
-- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists. A selected Claude terminal uses the managed path and refuses busy, ownership or Store blockers. On eligible physical fallback paths, a scanned blocked approval or proven input-owning questionnaire, editor, menu, or read-only viewer vetoes physical Send; parsed working activity and an existing draft do not. Unreviewed Codex frontends require the styled-Composer checks above; reviewed physical Send paths do not require ordinary main-Composer visibility. Codex replaces the current Composer with `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. Each injects the request and submits exactly once. Broken or stale AKK management activity records do not veto that independently verified live terminal/process.
+- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists. A selected Claude terminal uses the managed path and refuses busy, ownership or Store blockers. On eligible physical fallback paths, a scanned blocked approval or proven input-owning questionnaire, editor, menu, or read-only viewer vetoes physical Send; parsed working activity and an existing draft do not veto Codex Send. Claude requires an empty recognized main Composer, no existing stashed draft, a known native footer, and no running or unproven foreground turn; background shells alone do not block it. Unreviewed Codex frontends require the styled-Composer checks above; reviewed Codex physical Send paths do not require ordinary main-Composer visibility. Codex replaces the current Composer with `C-u`; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each injects the request and submits exactly once. Broken or stale AKK management activity records do not veto that independently verified live terminal/process.
 - `AKK Codex: <task>`: list first and identify one exact eligible Codex conversation. For a direct CLI or Desktop row, copy its advertised Send with `conversation_id`; for a terminal row use its `terminal_id`. Send `request=<task>` once through that route. Do not count duplicate representations of the same proven thread as separate tasks.
 - `AKK Claude: <task>`: list first, require one exact eligible Claude row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
 - Requests to list AKK or local coding-agent work: call `agent_knock_knock_list`.
@@ -176,7 +188,7 @@ For ordinary send or an in-flight answer:
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
 3. Treat `conversations[]` as the primary resource list; older raw CLI output may expose `terminals[]` instead. For a terminal-backed row, its managed context exposes `session_id`; `managed.current_turn` is the current AKK owner. Query `watches` for retained monitoring and managed Turn history, including unavailable-pane recovery.
 4. Read the selected resource's `available_actions`. In the compact Host projection its keys are the exact current action names and each value is `true`; `action_inputs`, when present, carries only dynamic semantic arguments, `missing_required`, and scope. For every mutation, use only an advertised action, start with those semantic inputs, supply every `missing_required` field, and follow this skill's action rules. User-selected Watch is the exception: explicit user intent plus one complete exact `terminal_id` is sufficient even when `available_actions.watch` is absent. The only additional mutation sources are a terminal row's `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`: use either only after explicit user confirmation and refresh the list immediately afterward.
-5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context and may require exact empty before input. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules describe retained legacy routes/receipts and other explicitly advertised physical fallback paths; new ordinary Claude sends retain the managed path and do not fall back to unmanaged delivery after a Store or ownership failure. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: Codex replaces the current Composer with `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. Each injects the new request and submits exactly once without a post-text Composer veto. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. Managed delivery is attempted where eligible, but a proven zero-input failure falls back to one unmanaged delivery with no managed callback Turn. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence or composer authority. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
+5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context and may require exact empty before input. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules apply to an explicitly selected physical terminal action and retained legacy routes/receipts; ordinary Claude managed sends never silently switch to physical input after failure. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: Codex replaces the current Composer with `C-u`; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each injects the new request and submits exactly once without a post-text Composer veto. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. Within an already selected physical-input operation, eligible managed delivery may be attempted; a proven zero-input failure can then use that operation's established unmanaged fallback with no managed callback Turn. This does not authorize changing an ordinary Claude managed Send into a physical operation. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence or composer authority. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
 6. If multiple terminals match, show their `short_ref`, agent, provider, and terminal target, then ask the user to choose. If a human switch has an unresolved Turn, ambiguous ownership, or unverifiable identity and no follow-current send is advertised, report that blocker and ask the user which context to resolve; never guess, supersede active work, or bypass the fence.
 
 An idle pane is at a verified ready prompt, with no current work or unresolved permission request. A previously completed managed turn alone is not proof that the pane is still idle.
@@ -199,7 +211,7 @@ Hard creation failure includes an absent exact terminal, inability to identify i
 
 Approval attention is notification-only for every Watch: never call an approval tool for a `watch_id`, send approval keys, or apply `autoApprove`. Native-interaction attention is different. An automatic exact request-bound Watch created by `terminal_user_explicit` unmanaged fallback can, after exact request acceptance and attribution, emit `interaction_required`; call Status with its exact `watch_id`, show the projected question to the user, and use `respond_interaction({watch_id,...})` only when that fresh owner-bound projection advertises `capabilities.respond=true`. A terminal-activity Watch or `interaction_manual_required` callback remains notify-only: tell the user to inspect and answer in the live TUI, and send no interaction input. Each new exact attention fingerprint is notified once while the Watch remains active. Terminal outcomes settle once. The durable outbox uses deterministic notification IDs/idempotency and leased retry, so startup and periodic supervision can safely recover callback delivery after AKK, OpenClaw, or Gateway restart.
 
-The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v33. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v4 and point here for the static contract; the CLI keeps the complete operator/debug action contract. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
+The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v35. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v4 and point here for the static contract; the CLI keeps the complete operator/debug action contract. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
 
 For Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Codex 0.160 may report `current="workspace_granular"`; this is a current-only native default, not a selectable mode. Select only an ID actually returned in `choices`. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
 
@@ -312,11 +324,11 @@ The model-facing `agent_knock_knock_list` presents `conversations[]` once. Exact
 
 ### Compact controller-Host List projection
 
-The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=4`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, explanatory `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
+The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=4`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, static action `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Bounded per-conversation `usage` is additive display guidance for Codex CLI, Codex Desktop, Claude and terminal-only rows, derived from current evidence; it keeps projection v4. Action contract v35 adds a no-existing-stash prerequisite to Claude physical Send, narrowing eligibility from v34; `physical_send_readiness` explains draft, stash, legacy-marker, foreground-turn and footer blockers without changing public call parameters or projection v4. The extra reader recheck and foreground background-view diagnosis are Claude-only. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
 
 **Conversation-only List:** List returns currently discoverable conversations, including Desktop sidebar entries with unconfirmed live owners. It never includes Watch inventories or retained managed history. Keep current ownership, blockers and advertised approvals; do not interpret missing Watch fields as missing Send monitoring. Use `agent_knock_knock_watches` or `/akk watches` to inspect observations. Legacy `listView="history"/"all"`, `all=true` and CLI `list --all` return a migration error.
 
-Every Host List page has a total row limit (`listLimit`, default 40, maximum 100), a 24 KiB UTF-8 JSON ceiling and a conservative 12,000 weighted-character budget (ASCII 1, other code points 16), including metadata. Follow `pagination.next_args` unchanged while `has_more=true`. Desktop catalog pagination is separate: finish the Host pages, then use `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Discovery pages are live snapshots; restart if membership changes invalidate the cursor. No progress body is added to List. Oversized rows retain exact IDs and a Status entry point; omitted actions do not mean unsupported capabilities. Refresh exact Status before acting.
+Every Host List page has a total row limit (`listLimit`, default 40, maximum 100), a 24 KiB UTF-8 JSON ceiling and a conservative 12,000 weighted-character budget (ASCII 1, other code points 16), including metadata. Follow `pagination.next_args` unchanged while `has_more=true`. Desktop catalog pagination is separate: finish the Host pages, then use `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Discovery pages are live snapshots; restart if membership changes invalidate the cursor. No progress body is added to List. Oversized rows retain exact IDs and a Status entry point; their guidance says details were omitted and directs the user to Status, rather than describing those operations as unsupported. Refresh exact Status before acting.
 
 **Watch inventory:** `agent_knock_knock_watches` / `/akk watches` / CLI `watches` is a read-only Store query, defaulting to the most recent 24 hours, 40 rows per page (maximum 100), with a whole-response budget. `hours` accepts 1–48. Active or unresolved observations older than the window remain visible as `outside_window`; terminal managed Turns are a distinct section. Follow the returned pagination arguments. The query does not create/renew monitoring, reconcile or resend notifications. Use exact Status for actionable questions, approvals, callback recovery or full results. Native completion, controller acceptance and chat delivery are separate; `callback_expected=false` alone is neither failure nor delivery proof.
 
@@ -349,7 +361,7 @@ The tool name is normally `agent_knock_knock_<action-name>`. List aliases are `r
 
 `available_actions` is the authoritative current-action source for mutations after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`; user-selected `watch({terminal_id})` deliberately honors an exact user-selected terminal even without advertisement. A native interaction response instead requires the current `interaction_state` returned by Status in the same controller conversation. Approval, native interaction response, handoff takeover, and `reconcile_binding` require explicit user intent and fresh source state. Model-facing shapes include `permission_options({terminal_id})` and `set_permissions({terminal_id,mode})`; `model_options({terminal_id})`, the separately advertised Codex-only `repair_model_control({terminal_id})`, and `set_model({terminal_id,model,reasoning_effort})`; `watch({terminal_id})`; `send({session_id|terminal_id,request})`, with the targets mutually exclusive; `identify_foreground({terminal_id})`; `identify_and_send({terminal_id,request})`; `respond_interaction({turn_id|watch_id,interaction_id,answers,delivery_mode?})`, with exactly one subject id, only projected question/option ids, and `delivery_mode` present only for `async_question`; managed `approve({turn_id,decision})` or approve-once-only 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})` or its separately advertised `{operation:"transfer_store_authority",terminal_id,maintenance_acknowledgement?:true}` form. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request; human-facing numbers and short IDs remain slash-navigation aids and are never structured tool arguments. The model never carries terminal, binding, catalog, candidate, composer, handoff, approval, interaction-fingerprint, revision, binding ID/generation, or handoff-only live-native-UUID fences; it never receives draft text or composer digests. `native_thread_id` remains the semantic resume identity. AKK derives those private fences and revalidates them before side effects. Orphan-close `expected_message_id` and `expected_transition_id` remain because they are entity IDs. Store format remains 1 and writer protocol is 11; Terminal Watch schema remains 3. Protocol 11 fences retired Session authority so predecessor writers cannot revive a source Session after Store authority transfer.
 
-Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Native inspection and lifecycle input require an exactly empty Composer; managed Send may require exact empty before input. Codex and Claude Code `terminal_user_explicit` instead require a scanned non-blocked approval state and no proven input-owning questionnaire, editor, menu, or read-only viewer. Reviewed physical Send paths do not require ordinary main-Composer visibility, stability, or exactness. Unreviewed Codex frontends require a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Existing drafts and parsed working activity do not themselves veto the user-priority path, and after text injection no Composer observation may veto Enter. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Humans can attach to the same tmux or Herdr session and continue directly at any time.
+Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Native inspection and lifecycle input require an exactly empty Composer; managed Send may require exact empty before input. Codex and Claude Code `terminal_user_explicit` instead require a scanned non-blocked approval state and no proven input-owning questionnaire, editor, menu, or read-only viewer. Reviewed Codex physical Send paths do not require ordinary main-Composer visibility, stability, or exactness. Claude physical Send requires an empty recognized main Composer, a known native footer, and no running or unproven foreground turn; background shells alone do not block it. Unreviewed Codex frontends require a recognized styled Composer before clearing and a fresh empty styled Composer before task text. For Codex, existing drafts and parsed working activity do not themselves veto the user-priority path, and after text injection no Composer observation may veto Enter. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Humans can attach to the same tmux or Herdr session and continue directly at any time.
 
 Exact-task Claude Code completion depends on a strictly correlated local transcript turn and fails closed for unknown schemas, background work, or ambiguous identity. A `terminal_activity` Watch may separately notify that the selected terminal became stably idle only after observed activity; always label that callback best-effort and never report it as exact task completion or success.