@scotthuang/agent-knock-knock 0.13.11 → 0.13.13

package/docs/quickstart-herdr.md

@@ -28,11 +28,11 @@ AKK enumerates every running local Herdr session, identifies a terminal by its s
 
 The v30 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.
 
-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. Ordinary Send, List, and Status never run the probe. 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.
+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 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.
 
-To observe an exact Herdr Codex or Claude Code terminal without changing it, run a fresh `/akk list` and copy that row's complete `terminal_id`. Its advertised `watch` action is the recommended convenience, but missing advertisement does not veto an explicit user request. Both the structured action and `/akk watch <exact-terminal-id>` take only that exact ID. The result's `watch_id` is the sole target for `/akk status <watch-id>` and `/akk unwatch <watch-id>`.
+To observe an exact Herdr Codex or Claude Code terminal, run a fresh `/akk list` and copy that row's complete `terminal_id`. Its advertised `watch` action is the recommended convenience, but missing advertisement does not veto an explicit user request. Both the structured action and `/akk watch <exact-terminal-id>` take only that exact ID. The result's `watch_id` is the sole target for `/akk status <watch-id>` and `/akk unwatch <watch-id>`.
 
-Watch creation and observation are read-only and follow the user's selected terminal. Coding-agent version or artifact uncertainty, missing binding metadata, managed ownership, and missing action advertisement are warnings rather than creation vetoes. AKK fails only when that exact Herdr terminal is absent, its endpoint/process cannot be identified, neither an exact durable task anchor nor a read-only screen-status path exists, or the durable Watch Store cannot be created. An existing managed monitor remains preferable for exact Turn attribution, but an explicit Watch can coexist without adopting or mutating it. New exact-task Watches default to `respond_when_exact`: each distinct supported native interaction emits an `interaction_required` wake-up, then Status in the owning controller conversation exposes a single-use response offer. Activity/best-effort Watches and unsupported or secret question shapes emit `interaction_manual_required` and remain `notify_only`.
+Watch follows the user's selected terminal. Codex 0.158.0/0.159.0 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.0-compatibility.md). Coding-agent version or artifact uncertainty, missing binding metadata, managed ownership, and missing action advertisement are warnings rather than creation vetoes. AKK fails only when that exact Herdr terminal is absent, its endpoint/process cannot be identified, neither an exact durable task anchor nor a read-only screen-status path exists, or the durable Watch Store cannot be created. An existing managed monitor remains preferable for exact Turn attribution, but an explicit Watch can coexist without adopting or mutating it. New exact-task Watches default to `respond_when_exact`: each distinct supported native interaction emits an `interaction_required` wake-up, then Status in the owning controller conversation exposes a single-use response offer. Activity/best-effort Watches and unsupported or secret question shapes emit `interaction_manual_required` and remain `notify_only`.
 
 Status can also expose a Codex `kind="async_question"` while the observed task remains `working`. Its response requires the same exact managed `turn_id` or response-capable exact `watch_id`, semantic question/option IDs, and an optional advertised `delivery_mode` (default: `steer_current_turn`): `steer_current_turn` delivers to the running turn, while `queue_next_turn` queues it for the next turn. A blocking `kind="questionnaire"` never carries `delivery_mode`. Neither form accepts raw Herdr input, a shortcut chord, or a menu index. Codex 0.154.0 and 0.155.1 use separate version-bound TUI profiles; AKK does not attribute post-0.155.1 main-only notification or stable-question-identity wrappers to either released client.
 

package/docs/quickstart-tmux.md

@@ -118,13 +118,13 @@ verified Escape, but it never receives Enter authority.
 
 Codex declares `scope="current_and_new_sessions"`: the native selection changes the open session and persists the model for future sessions. Ordinary reasoning efforts through `max` persist too. `ultra` is the native exception—it applies to the current session, while Codex stores a non-Ultra effort fallback for new sessions. AKK therefore reports current `effective` and `new_session_defaults` separately and omits the future effort when the native TUI cannot expose its exact fallback value. Claude Code declares `scope="current_session"` and does not change its new-session default. AKK does not silently edit a configuration file to simulate either behavior. If the outcome is `uncertain` or `do_not_retry=true`, do not repeat the command; inspect the shared pane and refresh `/akk models` before a deliberate new attempt.
 
-AKK Turn status and the coding agent's native status are separate. `/akk status` and `agent_knock_knock_status` inspect AKK-managed state and a bounded current screen; they never type `/status`. For native status, start from `/akk list` and use only an advertised `agent_knock_knock_native_inspect({terminal_id,inspection:"status"})` action. AKK derives and revalidates the binding fence internally. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267. Other complete `x.y.z` versions remain callable through the generic runtime protocol and display a compatibility warning; a real UI/schema incompatibility fails at runtime and is never retried automatically. Claude's modal Status panel is parsed and dismissed before the action proves the original idle composer. The action creates no Session, Turn, receipt, monitor, or callback. Direct `/model`, `/usage`, `/cost`, `/stats`, `/usage-credits`, `/compact`, and arbitrary slash-command injection remain unavailable; use only the typed `/akk models` and `/akk set-model` model-control flow above. Bare Codex `/usage` is not read-only automation: it opens a menu whose later Enter can select an account-side usage-limit reset.
+AKK Turn status and the coding agent's native status are separate. `/akk status` and `agent_knock_knock_status` inspect AKK-managed state and a bounded current screen; they never type `/status`. For native status, start from `/akk list` and use only an advertised `agent_knock_knock_native_inspect({terminal_id,inspection:"status"})` action. AKK derives and revalidates the binding fence internally. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1/0.158.0/0.159.0 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267. Other complete `x.y.z` versions remain callable through the generic runtime protocol and display a compatibility warning; a real UI/schema incompatibility fails at runtime and is never retried automatically. Claude's modal Status panel is parsed and dismissed before the action proves the original idle composer. The action creates no Session, Turn, receipt, monitor, or callback. Direct `/model`, `/usage`, `/cost`, `/stats`, `/usage-credits`, `/compact`, and arbitrary slash-command injection remain unavailable; use only the typed `/akk models` and `/akk set-model` model-control flow above. Bare Codex `/usage` is not read-only automation: it opens a menu whose later Enter can select an account-side usage-limit reset.
 
-An idle Codex row with ambiguous foreground rollout identity may instead advertise `agent_knock_knock_identify_foreground({terminal_id})` and `agent_knock_knock_identify_and_send({terminal_id,request})`. The first action mutates no AKK Store state, but it does type `/status` and Enter exactly once into that visible exact-empty pane. Its 30-second proof is diagnostic only and cannot authorize a later call. The second is the safe actionable form: it retains one terminal lock across that probe and one task, while durable Session/Turn identity still requires unique exact request acceptance. If the probe becomes changed or uncertain, no task is sent and neither input is retried automatically. Ordinary Send, List, and Status never invoke this probe.
+An idle Codex row with ambiguous foreground rollout identity may instead advertise `agent_knock_knock_identify_foreground({terminal_id})` and `agent_knock_knock_identify_and_send({terminal_id,request})`. The first action mutates no AKK Store state, but it does type `/status` and Enter exactly once into that visible exact-empty pane. Its 30-second proof is diagnostic only and cannot authorize a later call. The second is the safe actionable form: it retains one terminal lock across that probe and one task, while durable Session/Turn identity still requires unique exact request acceptance. If the probe becomes changed or uncertain, no task is sent and neither input is retried automatically. List and Status never invoke this probe. Codex 0.158.0/0.159.0 exact Send and active-task Watch use a separate closed `/status` transaction to bind the foreground paginated thread.
 
-## 5. Watch an exact terminal without changing it
+## 5. Watch an existing terminal task
 
-You can start a task yourself by typing it directly in the Codex or Claude Code TUI, then let OpenClaw observe that terminal without handing the task to AKK. You can also explicitly add a read-only Watch alongside an existing managed Turn; it does not replace or change that Turn. Send a fresh:
+You can start a task yourself by typing it directly in the Codex or Claude Code TUI, then let OpenClaw observe that terminal without handing the task to AKK. You can also explicitly add a Watch alongside an existing managed Turn; it does not replace or change that Turn. Send a fresh:
 
 ```text
 /akk list
@@ -136,7 +136,7 @@ Copy the row's complete `terminal_id`. An advertised `available_actions.watch` i
 /akk watch <exact-terminal-id>
 ```
 
-Watch creation and observation are read-only and user-intent-first. 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`.
+Watch follows the exact terminal selected by the user. Codex 0.158.0/0.159.0 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.0-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`.
 
 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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.13.11",
+  "version": "0.13.13",
   "description": "Control local Codex and Claude Code from OpenClaw or compatible controller Hosts through shared terminals.",
   "license": "MIT",
   "type": "module",
@@ -86,7 +86,9 @@
     "openclaw.plugin.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/codex-0.158.0-compatibility.md",
+    "docs/codex-0.159.0-compatibility.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -141,11 +143,13 @@
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
+    "@types/ws": "8.18.1",
     "clawhub": "0.23.3",
     "openclaw": "2026.9.1",
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "ws": "8.22.0"
   }
 }

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

@@ -42,12 +42,14 @@ For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`,
 
 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.
 
-For an exact-empty idle Codex pane whose native identity is ambiguous, List may advertise `identify_foreground` and `identify_and_send`. `agent_knock_knock_identify_foreground({terminal_id})` is explicit and Codex-only: it mutates no Store record but does send `/status` and Enter exactly once to the visible pane. Its 30-second proof is diagnostic, never reusable authority; do not feed its UUID or expiry into another tool. `agent_knock_knock_identify_and_send({terminal_id,request})` keeps one terminal lock across the probe and task and is the only actionable consumer of that observation. It still binds a durable Session/Turn only from unique exact request acceptance. A changed or uncertain probe sends no task and must not be retried automatically. Never invoke either action unless the current terminal row advertises it. Ordinary `agent_knock_knock_send`, List, and Status do not run `/status` and must not be redirected through these tools implicitly.
+For an exact-empty idle Codex pane whose native identity is ambiguous, List may advertise `identify_foreground` and `identify_and_send`. `agent_knock_knock_identify_foreground({terminal_id})` is explicit and Codex-only: it mutates no Store record but does send `/status` and Enter exactly once to the visible pane. Its 30-second proof is diagnostic, never reusable authority; do not feed its UUID or expiry into another tool. `agent_knock_knock_identify_and_send({terminal_id,request})` keeps one terminal lock across the probe and task and is the only actionable consumer of that observation. It still binds a durable Session/Turn only from unique exact request acceptance. A changed or uncertain probe sends no task and must not be retried automatically. Never invoke either action unless the current terminal row advertises it. List and Status do not run `/status`. Ordinary Send must not be redirected through these explicit identification tools implicitly; Codex 0.158.0/0.159.0 uses its separate closed `/status` transaction for exact paginated Watch binding.
 
 The private approval fence remains prompt-scoped. It binds the adapter-isolated exact unredacted approval region plus terminal/process identity, decision keys and label, prompt kind, working directory, reason/detail, and request or policy evidence. The whole-screen digest and redacted excerpt are diagnostic only: output outside the approval region may continue scrolling without invalidating the same reviewed prompt. After explicit user confirmation, the plugin/CLI retains a private confirmation offer and recaptures the region under lock. Any change inside the exact region—including a command or otherwise identically redacted secret—rejects and sends zero approval keys. Never expose, persist as public action data, log, infer, or reconstruct the raw prompt evidence or its opaque fingerprint.
 
 Coding-agent versions distinguish missing verification from known protocol incompatibility. A merely unverified complete Codex or Claude Code `x.y.z` version keeps otherwise eligible actions advertised; preserve and surface its compatibility warning, then let runtime structure and postcondition checks decide success. Never suppress an action solely because its exact version lacks a regression-tested AKK profile. Known incompatible protocols disable their affected actions before input. Codex 0.157.0/0.157.1 create new durable TUI sessions with paginated history and may use a shared background server; AKK cannot yet bind that history to an exact managed task. Managed completion callbacks, native thread lifecycle actions, and automated native status dispatch remain unavailable; visible status cards can still be parsed. Explicit terminal Send and warning-bearing `terminal_activity` Watch remain available subject to native UI safety checks; that Watch reports best-effort activity notifications without proving exact task completion or granting question-response authority. `--no-daemon` does not restore legacy JSONL history for new sessions. Use only currently advertised mutation actions, and if input may already have occurred and the result is unproven, report the uncertainty and never retry automatically.
 
+Codex 0.158.0/0.159.0 physical Send uses an exact paginated task Watch instead of a legacy managed Session/Turn. Before Send, AKK attempts a closed `/status` transaction in the available main Composer to bind the foreground thread. When an exact Watch attaches, retain its `watch_id` for Status, question responses, and completion callbacks; do not invent a `turn_id`. If binding or Watch attachment fails, report the receipt's callback limitation. This adapter does not establish managed session-only dispatch or native new/resume for paginated threads. Async responses offer only `steer_current_turn`, never `queue_next_turn`. A first Watch requested while a blocking modal already owns input cannot establish this binding and falls back to activity observation with manual question handling.
+
 AKK discovers eligible panes across workspaces. When more than one target matches, choose one exact listed `terminal_id` for a structured tool or a listed selector for a human slash command; never guess based on a workspace name or path.
 
 Natural-language forms:
@@ -56,7 +58,7 @@ Natural-language forms:
 - `AKK Codex: <task>`: list first, require one exact eligible Codex row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
 - `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`.
-- Requests to observe an exact Codex or Claude Code terminal: normally call `agent_knock_knock_list` and copy that row's advertised `watch` action, then pass its complete `terminal_id`. If the user explicitly selected a complete exact terminal ID, missing `available_actions.watch` is not a veto: Watch is read-only and may still be called with that ID. Never guess, shorten, or substitute a selector. AKK prefers an exact task anchor and otherwise records warnings and observes the terminal/process activity epoch.
+- Requests to observe an exact Codex or Claude Code terminal: normally call `agent_knock_knock_list` and copy that row's advertised `watch` action, then pass its complete `terminal_id`. If the user explicitly selected a complete exact terminal ID, missing `available_actions.watch` is not a veto: Watch may still be called with that ID. Never guess, shorten, or substitute a selector. AKK prefers an exact task anchor and otherwise records warnings and observes the terminal/process activity epoch.
 - Requests to inspect an existing Terminal Watch: call `agent_knock_knock_status` with its authoritative `watch_id`. Requests to stop observing it: call `agent_knock_knock_unwatch` with that same `watch_id`. Never substitute a Session, Turn, terminal selector, or short reference.
 - Requests to continue in the current terminal context after the human may have run `/clear`, `/new`, `/resume`, or an equivalent native operation: first call `agent_knock_knock_list`, then use only that exact terminal row's advertised `send({terminal_id,request})`; do not substitute the stale `session_id`.
 - Requests to recover an AKK submission reported as uncertain: refresh `agent_knock_knock_list`. Only if the current exact Turn advertises `retry_submission`, explain that AKK will revalidate the immutable original request and may either press one Enter for the exact existing draft or retransmit that original text once after structured no-Enter proof and a positively empty composer. Require explicit user confirmation, then call the prefilled `agent_knock_knock_send({turn_id})` unchanged. Never add `request`, terminal/Session IDs, timeout fields, or callback route data, and never retry it automatically.
@@ -76,9 +78,9 @@ Natural-language forms:
 
 ## Sessions and Turns
 
-AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. `session_id` is the strict ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted ordinary send creates a distinct `turn_id` without clearing the native agent context. A `turn_id` is used for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, close, and the explicitly advertised submission-retry form of Send.
+AKK's identity hierarchy is terminal → native Codex or Claude Code session → AKK session → Turns. `session_id` is the strict ordinary-send target for one exact native context. `terminal_id` is the deliberately different follow-current target that lets the user hand the pane's currently verified context back to AKK after a safe human-driven switch. Each accepted managed Send creates a distinct `turn_id` without clearing the native agent context; Codex 0.158.0/0.159.0 physical Send instead returns an independent task Watch when observation can be attached. A `turn_id` is used for history, callbacks, respond, status, approval, cancellation, renewal, callback retry, close, and the explicitly advertised submission-retry form of Send.
 
-Use `agent_knock_knock_send` with `request` and neither `session_id` nor `terminal_id` only when the target is unspecified. AKK must resolve exactly one eligible Codex or Claude Code pane across all workspaces, attach or discover its AKK session, and verify that it is idle immediately before writing the request. If no eligible pane exists, report AKK's setup guidance; do not substitute another execution path.
+Use `agent_knock_knock_send` with `request` and neither `session_id` nor `terminal_id` only when the target is unspecified. AKK must resolve exactly one eligible Codex or Claude Code pane across all workspaces and use its currently advertised Send path. Managed delivery attaches or discovers its AKK session and verifies idle before input; Codex 0.158.0/0.159.0 physical Send does not require a managed Session and follows its terminal input-safety checks. If no eligible pane exists, report AKK's setup guidance; do not substitute another execution path.
 
 On first attach, the target terminal must be explicitly named by the user; never guess which already-running pane should receive the task.
 
@@ -87,7 +89,7 @@ For ordinary send or an in-flight answer:
 1. Reuse an AKK session only when the user's reference uniquely identifies its verified native session and terminal incarnation.
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
 3. Treat `terminals[]` as the primary resource list. Its managed context exposes `session_id`; `managed.current_turn` is the only current AKK owner, while `managed.recent_turn` and `managed.history` are retained Turn history. Records in `unavailable_managed_turns[]` have no live pane in this snapshot.
-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. Read-only 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.
+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. If the selected row advertises terminal-scoped send, call `agent_knock_knock_send({terminal_id,request})`. `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. After Enter, AKK best-effort attaches a Terminal Watch callback; Watch 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.
 
@@ -97,11 +99,11 @@ Do not treat ordinary Send's whole-draft Composer replacement as a native conver
 
 ## Terminal Watch
 
-Creating and observing a Terminal Watch is read-only and user-intent-first; answering a supported native interaction later is a separate explicit, owner-bound mutation. The normal sequence is user selects a Codex or Claude Code terminal → fresh `agent_knock_knock_list` or `/akk list` → copy its complete `terminal_id` and, when present, its advertised `watch` action → retain the returned `watch_id` for status or unwatch. Advertisement is discovery help, not Watch authorization. If the user explicitly supplies one complete exact terminal ID, call `agent_knock_knock_watch({terminal_id})` even when that row does not advertise Watch. Never infer a terminal or use a selector/short ID.
+Terminal Watch follows the exact terminal selected by the user. Codex 0.158.0/0.159.0 exact Watch creation uses a closed `/status` transaction in an available main Composer to bind its foreground paginated task; subsequent observation is read-only. Answering a supported native interaction later is a separate explicit, owner-bound mutation. The normal sequence is user selects a Codex or Claude Code terminal → fresh `agent_knock_knock_list` or `/akk list` → copy its complete `terminal_id` and, when present, its advertised `watch` action → retain the returned `watch_id` for status or unwatch. Advertisement is discovery help, not Watch authorization. If the user explicitly supplies one complete exact terminal ID, call `agent_knock_knock_watch({terminal_id})` even when that row does not advertise Watch. Never infer a terminal or use a selector/short ID.
 
-Managed ownership is not a veto. Prefer an existing managed Turn monitor when exact Turn attribution is wanted, but an explicit Watch may coexist because observation sends no input and does not adopt, replace, close, reserve, block, interrupt, approve, or otherwise mutate that Turn, Session, terminal, or task. A successful `terminal_user_explicit` unmanaged fallback may separately return an automatic exact request-bound Watch after AKK sends; retain that `watch_id` and use Status for recovery. Once exact request acceptance, terminal identity, owner, and one current supported native interaction are established, that Watch may emit an idempotent `interaction_required` callback. The callback itself is notification only; call `agent_knock_knock_status({watch_id})` in the owning controller conversation to obtain the single-use private response offer, and respond only when its projection says `capabilities.respond=true`. When exact response authority cannot be proven, AKK emits `interaction_manual_required` instead; that state and every terminal-activity Watch remain notify-only with `capabilities.interaction_respond=false`, so the human must answer in the live TUI.
+Managed ownership is not a veto. Prefer an existing managed Turn monitor when exact Turn attribution is wanted, but an explicit Watch may coexist because subsequent observation sends no input and does not adopt, replace, close, reserve, block, interrupt, approve, or otherwise mutate that Turn, Session, terminal, or task. Codex 0.158.0/0.159.0 exact Watch creation separately types the closed `/status` transaction described above. A successful `terminal_user_explicit` unmanaged fallback may separately return an automatic exact request-bound Watch after AKK sends; retain that `watch_id` and use Status for recovery. Once exact request acceptance, terminal identity, owner, and one current supported native interaction are established, that Watch may emit an idempotent `interaction_required` callback. The callback itself is notification only; call `agent_knock_knock_status({watch_id})` in the owning controller conversation to obtain the single-use private response offer, and respond only when its projection says `capabilities.respond=true`. When exact response authority cannot be proven, AKK emits `interaction_manual_required` instead; that state and every terminal-activity Watch remain notify-only with `capabilities.interaction_respond=false`, so the human must answer in the live TUI.
 
-At creation, AKK first tries to build a privacy-safe exact provider task anchor. Codex binds rollout identity and request/turn byte boundaries; Claude binds transcript identity, root prompt, and current-turn byte boundaries. Success returns `watch_mode="exact_task"`, `confidence="exact"`. Later process, endpoint, native-thread, file identity, truncation/replacement, boundary, successor-task, or fingerprint drift invalidates that exact Watch rather than silently following another task.
+At creation, AKK first tries to build a privacy-safe exact provider task anchor. Codex 0.158.0/0.159.0 binds the exact foreground paginated thread and native task; older supported Codex versions bind rollout identity and request/turn byte boundaries. Claude binds transcript identity, root prompt, and current-turn byte boundaries. Success returns `watch_mode="exact_task"`, `confidence="exact"`. Legacy anchors invalidate on process, endpoint, native-thread, file identity, truncation/replacement, boundary, successor-task, or fingerprint drift. Codex 0.158.0/0.159.0 retains the original accepted native turn even when an unrelated later task starts; it never follows that later task or loses the original completion merely because a successor exists.
 
 Missing or mismatched agent-version evidence is always a warning and does not weaken an otherwise usable exact task anchor. If no unique usable anchor can be established because artifact, native-task, or boundary evidence is unavailable or incompatible, do not reject. AKK records those diagnostics in `warnings` and creates `watch_mode="terminal_activity"`, `confidence="best_effort"`. Binding metadata, managed ownership, and missing action advertisement likewise remain non-veto warnings. This fallback follows only the selected terminal/process activity epoch. It must first observe `working` or `awaiting_approval`, then stable `idle` across consecutive supervision sweeps. Starting at `idle` or `unknown` never settles immediately; later activity must be observed first.
 
@@ -128,9 +130,9 @@ success; never retry an uncertain repair automatically.
 For native status inspection:
 
 1. Use only a current `available_actions.native_inspect({terminal_id,inspection:"status"})` entry. Those semantic arguments are complete; never add a command or authority field.
-2. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267 `inspection="status"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. Claude success includes parsing and safely dismissing the newly opened Status panel. The inspection tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, raw `/model`, `/compact`, and arbitrary slash commands remain unavailable; model changes use only the typed model-control tools above. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
+2. Regression-tested profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0/0.149.1/0.150.1/0.151.0/0.153.0/0.153.4/0.154.0/0.155.1/0.158.0/0.159.0 and Claude Code 2.1.218/2.1.226/2.1.237/2.1.251/2.1.259/2.1.263/2.1.266/2.1.267 `inspection="status"`. Other complete `x.y.z` versions remain callable through the generic runtime profile and add a compatibility warning; actual incompatible UI or schema evidence fails at runtime and is not automatically retried. Claude success includes parsing and safely dismissing the newly opened Status panel. The inspection tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, raw `/model`, `/compact`, and arbitrary slash commands remain unavailable; model changes use only the typed model-control tools above. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
 3. Treat this as terminal input even though the native command is read-only. AKK privately derives a fresh binding fence and requires an idle empty composer, exact PID/process/pane/cwd/version identity, and no conflicting Turn, transition, dispatch, approval, or owner.
-4. Codex `/status` requires an exact viewport of at least 80 columns so the full Session UUID can be proven. That pre-UUID gate applies to native inspection, lifecycle, and strict Session operations that must know the UUID before terminal input. An otherwise eligible terminal-scoped ordinary task may send once and bind from exact native acceptance afterward, so it does not run `/status` or fail merely because the pane is narrow.
+4. Codex `/status` requires an exact viewport of at least 80 columns so the full Session UUID can be proven. That pre-UUID gate applies to native inspection, lifecycle, and strict Session operations that must know the UUID before terminal input. Legacy terminal-scoped ordinary tasks may send once and bind from exact native acceptance afterward without running `/status` or failing merely because the pane is narrow. Codex 0.158.0/0.159.0 attempts its separate closed `/status` binding before physical Send; if an exact callback Watch cannot be prepared, the Send receipt must state that limitation.
 5. The result is valid only when AKK proves one fresh bounded native status result and the pane returns to idle. On an uncertain or unproven submission, do not retry, send Enter, clear the composer, or bypass AKK with raw terminal input.
 6. Native inspection creates no AKK Session, Turn, receipt, monitor, callback, or response round.
 
@@ -230,7 +232,7 @@ Action-name glossary:
 
 - `status`: inspect one terminal, Turn, or Watch; it sends no native slash command.
 - `send`: deliver a new request, or perform the separately advertised immutable `retry_submission` form.
-- `watch` / `unwatch`: start or stop durable read-only terminal observation.
+- `watch` / `unwatch`: create or stop durable terminal observation; Codex 0.158.0/0.159.0 exact creation performs the closed `/status` transaction, while subsequent observation is read-only.
 - `list_resumable_threads`, `new_thread`, and `resume_thread`: inspect or change native thread context through their closed lifecycle protocols.
 - `native_inspect`: run only an advertised closed native inspection such as `status`.
 - `model_options`, `repair_model_control`, and `set_model`: discover the current native catalog, clear only a proven model-control residue, or consume one catalog offer.
@@ -246,7 +248,7 @@ Action-name glossary:
 
 The tool name is normally `agent_knock_knock_<action-name>`. The sole List alias is `retry_submission`, which invokes `agent_knock_knock_send` with its listed `turn_id` only after explicit confirmation. Nested `handoff_decision.choices.take_over_current.action` and `blocking_turns[].recovery_action` carry their explicit tool/action name and semantic arguments; the explanatory choice and recovery text is defined here rather than repeated in every List row.
 
-`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`; read-only `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 `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})`. 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 7; Terminal Watch schema remains 3.
+`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 `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})`. 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 8; Terminal Watch schema remains 3.
 
 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. Ordinary main-Composer visibility, stability, exactness, existing draft contents, and parsed working activity do not veto this 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.