@scotthuang/agent-knock-knock 0.16.0 → 0.16.1

package/docs/claude-cli-direct.md

@@ -4,6 +4,8 @@ AKK controls an already-open Claude Code CLI through its native connection or an
 
 Starting with AKK **0.15.0**, new Claude Code sends automatically prefer a **managed terminal Turn** when AKK verifies a unique controllable tmux/Herdr counterpart for the exact native session and process. The result supplies a `turn_id` for monitoring and supported approvals or question responses; the caller does not select a transport or enable background management. Without that exact terminal, AKK uses the native inbox and returns a `claude-cli-watch:...` receipt. Codex CLI continues to prefer its shared backend. Existing Turns, Watches and send receipts retain their original provider and are never migrated or resent to adopt this policy.
 
+An explicitly selected physical terminal is a separate existing operation. When List offers that terminal's `terminal_user_explicit` Send, call Send with its exact displayed `terminal_id` and request. AKK may enter text and submit Enter even when native conversation identity is unresolved, subject to the current terminal input-safety checks: an empty recognized main Composer, a known native footer, and no running or unproven foreground turn. Background shells alone do not block this physical Send. This does not prove native acceptance or completion and does not add background-worker protocol support. Ordinary managed sends never silently downgrade to physical input after failure, and callers do not pass a new scope or private token.
+
 Live observations include **Claude Code `2.1.295` and `2.1.296` on macOS**, using native peer protocol `1`. These are tested versions, not minimum versions or a promise that every UI variant works. An unlisted, complete `x.y.z` version can use the compatible runtime contracts; absence from the regression matrix alone does not disable an otherwise eligible operation. Discovery checks the running CLI's registry, native session UUID, PID/start time, and socket identity. Unknown identity, protocol or UI structure is not guessed.
 
 AKK uses a small **Python 3 helper on the controller side** to verify macOS Unix-socket peer credentials. Python 3 must be available to AKK. This is not installed into Claude Code and does not change its login, proxy, permissions, or settings. Other operating systems do not yet have this direct adapter; existing supported terminal routes remain available.
@@ -37,10 +39,64 @@ Keep the authenticated Claude Code CLI open and ask your controller to refresh `
 
 > Use AKK to ask Claude Code in my-project to inspect the failing tests. Tell me when it finishes.
 
-Save the task identity returned by Send: `turn_id` for managed terminal delivery, or `watch_id` for native inbox delivery. Monitoring starts automatically; do not add another Watch for that task. Use Status with that exact task identity for follow-up, including managed approvals. Conversation Status reads the latest input and must not replace the original task identity. For a task started manually in the CLI, explicitly ask the controller to Watch it.
+For managed or native inbox delivery, save the task identity returned by Send: `turn_id` for managed terminal delivery, or `watch_id` for native inbox delivery. Monitoring starts automatically; do not add another Watch for that task. Use Status with that exact task identity for follow-up, including managed approvals. An explicitly selected physical Send reports its actual dispatch and observation evidence; without native identity, it cannot promise acceptance or completion monitoring. Conversation Status reads the latest input and must not replace the original task identity. For a task started manually in the CLI, explicitly ask the controller to Watch it.
 
 The usual `CLAUDE_CONFIG_DIR` is respected. For native inbox delivery, AKK does not modify Claude's inbound-message policy: if the session holds or refuses peer messages, the result remains held/refused rather than being bypassed with terminal input. Native busy Send is rejected because Claude can absorb an inbound message into the task already running.
 
+### When List offers different operations
+
+List's per-conversation guidance explains the current usable operations and
+recovery steps. An idle native conversation can accept Send without offering
+Watch because there is no active task to observe. Send creates monitoring for
+its own task. A working or waiting native conversation can offer Watch, whose
+creation still requires an exact active input. Terminal activity observation is
+a different, best-effort operation and may remain available on an unidentified
+terminal.
+
+If a Claude pane lacks verified identity, List requests one additional fresh
+snapshot from the configured reader, shared across unresolved Claude panes in
+that scan. It applies the same interactive-session and exact process, registry
+and configuration-home checks. It never types into the terminal, promotes a
+background agent, or substitutes a same-directory conversation. If the retry
+cannot establish native identity, the row explains the missing proof and the
+operations still offered, even when a more specific diagnostic is unavailable.
+An independently offered physical Send may still accept terminal input. Follow the
+actual action and its stated proof limits rather than interpreting missing
+native identity as a blanket input prohibition.
+
+The live investigation initially looked like a reader omission. The installed
+Claude Code 2.1.295 runtime instead deliberately excludes a foreground registry
+record carrying `parkedJobId` from `agents --json`; `--all` only adds completed
+background jobs and does not remove that exclusion. A foreground window in the
+Agents/background-session interface can display a conversation executed by a
+separate `bg-spare` process. Its own registered session is therefore not proof
+of the identity of the displayed conversation. This finding describes the
+inspected installation, not a universal contract for every Claude release.
+
+For an unresolved Claude terminal, AKK can explain this state using a bounded,
+read-only check of the foreground process's owned registry, exact PID and live
+process start identity. Positive evidence produces background-view guidance.
+When that physical terminal offers Send, explicitly selecting it can enter text
+and submit Enter; the result must still be checked in the window because native
+acceptance and exact task completion are unproven. When Send is not offered,
+continue manually in the current window, or start an ordinary foreground
+conversation without attaching a background conversation, then refresh List.
+Restarting and reopening the same background conversation does not change its
+execution model. This is a display diagnosis only: AKK does not resolve the
+background job or worker, access daemon or claim sockets, add a background
+protocol delivery route, or promise exact background-task completion. The
+background-view marker neither grants physical Send authority nor blocks an
+otherwise valid physical input action.
+
+Missing, unsafe, malformed, stale or unreadable evidence does not become a
+background diagnosis. List retains the generic explanation that the current
+conversation identity could not be confirmed, with the physical input option
+when actually offered, or steps to inspect the pane, continue directly, and
+retry ordinary startup/List refresh where appropriate.
+Restarting remains an attempt, not a guaranteed repair. Background jobs remain
+excluded from AKK's interactive conversation list, so scan counts are not a
+count of every Claude process on the machine.
+
 ### Sender permission class
 
 For native inbox delivery, set `AKK_NATIVE_CLAUDE_SENDER_PERMISSION_CLASS` in the **AKK/controller Host's launch environment**, with `bypass` or `prompting`. AKK declares that value in the native `<cross-session-message from-mode="…">` envelope and escapes the supplied task text. Callers pass the plain task request; they do not construct the envelope. Managed terminal sends do not use this envelope. The declaration does not change the target's permissions or bypass its hold/refuse policy.

package/docs/list-output.md

@@ -11,6 +11,100 @@ Use `agent_knock_knock_watches`, `/akk watches` or CLI `watches` to inspect
 monitoring. This is a read-only Store query: it does not create or renew a Watch,
 reconcile callbacks, reconnect a native session or send notifications.
 
+## Understanding a conversation row
+
+Each conversation includes `usage`, a bounded explanation derived from its
+current offered actions, activity, capabilities and blockers:
+
+| Field | Meaning |
+| --- | --- |
+| `summary` | Whether the conversation can receive work or currently needs attention |
+| `available` | What the user can do now |
+| `limitations` | Why a relevant operation is unavailable, including uncertainty |
+| `next_steps` | Concrete actions the user or controller can take next |
+
+Controllers should present this guidance in the user's language, beside the
+conversation title and project. A list of missing switches or internal reason
+codes is not a substitute for explaining what to do. Guidance is regenerated
+from each observation; it does not grant authority, add an action, or change
+existing action eligibility. The current `available_actions` and their input
+contracts remain authoritative. `usage` is an additive field within Host List
+projection v4. Action contract v35 adds a no-existing-stash prerequisite to Claude physical Send. This narrows eligibility for an empty input box with a stashed draft, so the action contract increases from v34; it is not only a wording change. The per-agent Composer policy names and public Send parameters remain unchanged. Readiness diagnostics are additive, and compact projection remains v4.
+The shared List projection adds this guidance to Codex CLI, Codex Desktop,
+Claude and terminal-only rows. Existing identities, capabilities and action
+offers retain their meanings; consumers may ignore the new display field.
+The additional identity recheck and background-view diagnosis described below
+apply only to Claude terminals, not to Codex discovery or dispatch.
+
+Different rows can legitimately offer different next steps. An idle native
+Claude conversation may accept Send without offering Watch: there is no active
+task to attach that Watch to. Send starts monitoring for its new task, so keep
+the returned Turn or Watch identity. A working native conversation can offer
+Watch, with the exact active input revalidated when observation starts. A
+terminal-only Watch can observe terminal activity; it does not establish an
+exact native task or prove that task succeeded.
+
+For an unresolved Claude terminal identity, List makes one additional fresh
+reader check, shared across the unresolved Claude terminals in that scan. It
+does not send terminal input or trust a registry file alone. If native identity
+remains unproven, List retains that uncertainty and explains the currently
+offered operations. A separately verified physical terminal Send can remain
+available; a failed native identity check does not establish native acceptance
+or completion, and does not by itself prove that terminal input is unsafe.
+
+A Claude window can display a background conversation while its own foreground
+conversation is parked. When a read-only check of that foreground process's
+owned registry and current process incarnation verifies this state, guidance
+explains that this window is in the background-session interface. This does not
+make the window read-only. When its real `terminal_user_explicit` Send action
+is offered, explicitly selecting that physical terminal lets AKK enter the
+requested text and submit Enter. The guidance distinguishes input dispatch
+from unproven native acceptance and completion, and asks the user to inspect
+the execution result in the window. 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 make it an ordinary
+foreground conversation.
+The raw observation adds
+`native_agent_identity_observation.window_role: "background_view"` only for
+that positive diagnosis; compact Host output carries its explanation in `usage`.
+This diagnosis does not identify or bind the background worker, inspect daemon
+or claim sockets, or grant physical Send authority or exact-task monitoring.
+Physical authority comes only from the current terminal action and its input
+safety checks, not from the background-view marker.
+
+If the registry check is missing, malformed, unsafe, stale or unavailable, List
+does not infer a background session. It retains the generic explanation that
+the native conversation identity could not be confirmed, together with the
+actual physical Send option when offered, or instructions to inspect the pane,
+use it manually, and retry ordinary startup and List refresh if appropriate.
+Failure to diagnose never removes the guidance.
+Relaunching is a recovery attempt, not a guaranteed repair.
+
+Claude physical rows additionally expose `physical_send_readiness` from the
+same current screen evidence used before input. An unsent user draft blocks
+Send and tells the user to send, save or clear it manually. A running foreground
+turn blocks Send until completion; an unproven running state asks the user to
+wait and refresh. Background shells alone do not block Send when the main
+Composer is empty and foreground completion can be verified. Unknown footer
+controls or an unrecognized input box stop automatic input and explain what
+AKK could not verify. These explanations take precedence over native-identity
+uncertainty. Codex readiness and managed Send rules are unchanged.
+
+To use an offered physical Send, select its displayed `terminal_id` and the
+existing Send tool's semantic inputs. No new public scope or token parameter
+is required. An ordinary managed Send does not silently switch to this route
+after an identity, ownership, Store or submission failure; uncertain input must
+never be replayed through a second route. A physical dispatch receipt proves
+only the stages it reports. Terminal activity observation is not native task
+acceptance or completion proof.
+
+`managed.session_count` counts distinct related Sessions found through current
+or historical managed records. It does not count valid current bindings. A
+positive count with null `session_id` and `session_short_ref`, and no
+`binding_status`, means no current authoritative Session was selected; it is not
+evidence that List lost a binding. These historical associations do not authorize
+Send or ownership recovery.
+
 ## Conversation selection
 
 Since 0.14.12 the default view prefers a verified backend as the project's CLI
@@ -63,7 +157,9 @@ Each Host page is capped at 24 KiB of UTF-8 JSON and 12,000 weighted characters
 (ASCII 1, other code points 16), including metadata. This is not a token budget.
 Oversized rows retain exact IDs and a Status entry point; omitted actions do not
 mean unsupported capabilities. Read exact Status for current questions, approvals
-and bounded public progress. List contains no progress body.
+and bounded public progress. Their guidance explains that details were omitted
+and directs the user to Status instead of claiming those operations are
+unsupported. List contains no progress body.
 
 Desktop catalog pagination remains separate: finish Host pages for one catalog
 page, then pass `desktop_scan.next_cursor` as `desktopCursor` with the same filters

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:
 

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.1",
   "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.