@scotthuang/agent-knock-knock 0.13.13 → 0.13.14

package/docs/codex-0.159.2-compatibility.md

@@ -0,0 +1,226 @@
+# Codex CLI 0.159.2 compatibility
+
+AKK 0.13.14 adds `codex-cli 0.159.2` and repairs the terminal-routing
+failures described in the [0.159.0 follow-up](codex-0.159.0-compatibility.md#local-terminal-routing-follow-up-2026-09-30-not-a-release).
+The native observations below were collected before publication. The user
+subsequently tested the locally installed candidate successfully; publication
+checks are recorded separately from those observations.
+
+The official source target is `rust-v0.159.2`, commit
+[`ff6aec96948b70d94983af2641a6b67c94faeff5`](https://github.com/openai/codex/tree/ff6aec96948b70d94983af2641a6b67c94faeff5).
+Compared with 0.159.0, the app-server protocol, paginated thread processor, and
+production TUI sources have no changes. TUI differences are confined to tests
+and snapshots; app-server implementation differences concern feedback reports.
+The terminal status, fullscreen Composer, async question, questionnaire, and
+model/plan profiles therefore use the existing 0.159 UI contract with an exact
+0.159.2 version identity.
+
+## Foreground and shared backend versions
+
+The foreground executable and shared daemon are independently installed. An
+already-open 0.159.0 process can remain connected to the existing 0.159.2 daemon
+after the standalone CLI is updated. `initialize.userAgent` and the thread's
+`cliVersion` describe that daemon; neither replaces physical process/version
+verification.
+
+AKK binds both versions. The only supported pairs are 0.158.0/0.158.0,
+0.159.0/0.159.0, 0.159.0/0.159.2, and 0.159.2/0.159.2. Initial negotiation
+permits only these reviewed pairs. Every subsequent read and answer pins the
+actual bound daemon version. A backend change invalidates that expectation; an
+old Watch is never silently migrated.
+
+The paginated task anchor keeps `codex_version` as the physical TUI version and
+uses an optional `backend_version` for a different daemon version. The field is
+covered by strict validation and the anchor fingerprint. Missing fields in old
+anchors retain same-version semantics. Older readers reject mixed-version
+anchors instead of interpreting them as same-version tasks. UI/terminal safety
+checks continue to use the physical version, exact process birth, and canonical
+terminal identity.
+
+## Terminal and answer corrections
+
+The original tmux failure was not caused by window size. With all locale
+variables absent, tmux 3.6b rendered the tab in the old dimension format as an
+underscore (`213_63`). The provider now requests a strictly parsed ASCII
+`213x63` format. Its diagnostics summarize command and socket identities with
+hashes rather than exposing their raw paths.
+
+Herdr 0.8 returns no text for `pane.read` with `lines: 0`. AKK now requests the
+visible viewport with that argument omitted when its caller requests zero
+scrollback lines. The native `/status` selection also uses truecolor foreground
+and background attributes instead of the reverse-video attribute expected by
+the old parser. The finite-state style check recognizes the observed native
+palette, verifies all visible selected-row cells, and rejects partial, dimmed,
+reset, or unknown selections.
+
+Normal output updates the macOS TTY device's change timestamp. Herdr viewport
+inspection no longer treats that timestamp as a device replacement. Device,
+inode, device number, owner, character-device type, non-symlink status, terminal
+identity, and process birth checks remain in force. Socket identity checks are
+unchanged.
+
+At 29 rows, a working indicator and tip can push the native status header above
+the visible viewport. Herdr's visible/detection reads cannot expose that hidden
+content by requesting more lines. The private paginated binding transaction now
+supports one native PageUp followed by Ctrl+End. It joins only a unique,
+nonblank overlap between captured frames, requires the real version header and
+complete strict status card, and verifies restoration of the original card tail
+before returning an identity. Every capture and key rechecks terminal identity.
+Drafts, selection mode, unknown history chrome, ambiguous overlap, or failed
+restoration stop the operation. The header is never synthesized from cached
+metadata. Native observations at 91 by 24 exercised clipping without creating a
+model task; the required existing Herdr session retains its 91 by 29 geometry.
+
+Herdr 0.8.0's key-name parser omits PageUp and End. Its official terminal
+encoder defines PageUp as `ESC [ 5 ~` and Ctrl+End as `ESC [ 1 ; 5 F`.
+For just these two singleton semantic keys, the provider uses the official
+`pane.send_text` direct-input endpoint with those fixed constants. Ordinary
+text retains `pane.send_input` and its bracketed-paste behavior. Mixed navigation
+batches are rejected before input; stable-resource resolution, socket identity,
+response correlation, and uncertain-delivery fencing are unchanged. No caller
+can provide arbitrary raw bytes through this key path.
+
+Working and queued-question chrome can remain visible while browsing history;
+the existing strict native suffix grammar separates it from the card. If the
+first PageUp exposes a compatible but non-overlapping partial status prefix,
+one optional closed WheelDown event advances three transcript rows. Eligibility
+uses the same strict card grammar, including a command-only prefix immediately
+before its header; that temporary adjacency never supplies binding evidence. It requires a freshly matching paused frame and
+exact viewport, targets the fixed transcript position (2,2), and exposes no
+caller-selected coordinates or bytes. Both providers send the official SGR
+wheel encoding without paste framing. Multiple candidate overlaps never
+authorize this fallback. A unique nonblank overlap and successful restoration
+are still required afterward. This is a bounded transaction, not an unbounded
+history scan or a relaxation of the identity parser.
+
+The native queued-question suffix can add or remove a 1–20 second countdown.
+That countdown is display state, not an automatic answer or popup timer; it is
+normalized only while comparing otherwise identical native chrome. The exact
+`New activity` paused-view prefix is also recognized. Restoration alone permits
+a known task-finished or question-count transition, while still requiring a
+fresh native paused footer, matching model/path, and an empty styled Composer.
+Unknown chrome or a draft forbids restoration input. A changed status card
+after restoration cannot return the earlier binding.
+
+This navigation is confined to the private closed binding used by Send/Watch
+and response preflight. Public `native_inspect(status)` remains idle-only; it
+still fails safely if its own full status card cannot fit. The ordinary 91 by
+29 public inspection was observed separately on both physical CLI versions.
+
+One native async answer was recorded about 7.4 seconds after submission, beyond
+the previous five-second confirmation window. Answer delivery now keeps the
+transport RPC deadline separate from a 15-second read-only receipt observation
+window. An RPC error or an early completed-turn status cannot establish that
+the answer was lost. Only the unique receipt matching the submitted client ID,
+payload, native turn, and question tuple confirms it. There is still exactly
+one answer submission; unresolved outcomes remain fenced against automatic
+retry.
+
+## Local upgrade and validation boundary
+
+The installed CLI uses the official standalone layout under
+`~/.codex/packages/standalone`; its visible entry is `~/.local/bin/codex`.
+The existing `mycodes` wrapper supplies the configured SOCKS proxy and remains
+unchanged. The existing latest update channel is retained. Updating the visible
+executable does not restart existing TUI processes or the shared daemon.
+
+The required old Herdr session is identified by its actual directory
+`~/workspace/herdr-codex`, stable terminal ID, PID, and process birth. It is not
+replaced by a different directory or silently restarted to make the version pair
+match. Separate owned tmux sessions exercise locale-free viewport access and the
+new executable without interrupting user sessions.
+
+Fast regressions and targeted native observations are distinct evidence. The original local task did not authorize the full/integration/release tier;
+the subsequently authorized publication uses the standard release gate. Native
+callbacks are collected locally, so this work does not establish external chat
+delivery. Managed native new/resume, unrecognized terminal styles, and a first
+Watch while an unbound blocking modal owns the terminal retain the documented
+0.159.0 limitations. The protected OpenClaw pane's previous task result is not
+part of this verification.
+
+
+## Combined candidate results (2026-09-30)
+
+The combined local candidate includes the Claude 2.1.285 adapter described in
+[its separate report](claude-2.1.285-compatibility.md). `npm run test:fast` passes
+**2,336 tests**, with zero failures, cancellations, or skips. The fast build also
+checks TypeScript and canonical Skill replicas. Architecture and refactor-evidence
+validators pass without increasing production size budgets.
+
+The tested runtime contains 238 JavaScript files under `dist/src`. SHA-256 is
+`e71abb37ee38717830b9acff4642f5c07c45670b6f76050897e46b08b59cb97f`, over sorted
+repository-relative paths followed by NUL, content, and NUL. The canonical Skill
+SHA-256 is `57c70aadbf8e48f05e11d2841c4889b7815d92bdee6fd20cedfa1e73e9da1eff`.
+These hashes identify a local candidate, not a release attestation.
+
+Native observations call compiled production terminal, Send, Watch, response,
+and durable callback components with real I/O, a private Store, and local callback
+collector. They are not unit mocks. All terminal mutations retain the global AKK
+ownership lock and verify the physical endpoint, process birth, and exact workspace.
+
+| Native scenario | Actual evidence |
+| --- | --- |
+| Existing Herdr `~/workspace/herdr-codex` | Physical 0.159.0, existing backend 0.159.2; original process and conversation retained |
+| Herdr Send and Watch | Auto Watch accepted the real prompt; an additional running-task Watch bound the same native turn |
+| Herdr question and answer | Exact single-select question notification; one native Yes response, durable receipt `confirmed` |
+| Herdr completion | Expected marker returned; each exact Watch delivered one completion callback; two extra reconciliations produced no duplicates |
+| New 0.159.2 tmux, locale variables absent | Real process launched through unchanged `mycodes --yolo`; exact Send binding, question, one confirmed Yes, and one exact completion callback passed |
+| 0.159.2 manual Watch after output settled | A fresh guarded probe bound the same running turn; auto and manual exact Watches each delivered the expected completion marker once |
+| Existing `akk:0.0` | Read-only fixed viewport query returned 213 by 63 under both locale-free and UTF-8 environments |
+| Public native status | Ordinary idle inspection at 91 by 29 observed the exact session on both physical CLI versions |
+
+The final Herdr turn is `01a0f17a-f838-7562-9c4a-dfc619c1d386`, with final marker
+`AKK159_HERDR_ROUTING_a22752f7`. The final 0.159.2 async-answer turn is
+`01a0f17a-cb8d-7b01-ad28-b3f3caa480fe`, with marker
+`AKK1592_TMUX_ROUTING_efe316c1`. The separate running-task manual-Watch turn is
+`01a0f17d-5f58-7dc2-8d5b-c3805d5e8aad`, with marker
+`AKK1592_TMUX_ROUTING_427687aa`; both exact completion callbacks passed after additional
+reconciliation without duplicates.
+
+One concurrent-output boundary remains: if fresh assistant text appears after
+the status card during a binding probe, the closed-card parser rejects that
+frame. A manual Watch then reports `terminal_activity` / `best_effort` explicitly;
+it must not be counted as an exact completion. Once output settles, a new,
+separately guarded status probe can bind the active task. The final tmux async
+scenario encountered this boundary for its extra manual Watch; its Send-created
+exact Watch still confirmed the answer and exact marker completion. The activity
+Watch's independent idle event is excluded from that result. No automatic answer
+retry or permissive parsing of intervening assistant prose was introduced.
+
+Earlier native attempts deliberately remain failed evidence: missing overlap,
+unsupported history keys, changing history chrome, and delayed receipt exposed
+the corrections above. A previous answer recorded after the old five-second
+window was never replayed. Attempts ending without an answer are not successful
+question tests, even when the daemon reports the turn completed.
+
+At the close of the compatibility work, the original working directory's 34
+dirty/untracked files, shell startup files, and Claude settings retained their
+pre-task hashes. The CLI upgrades were installed. AKK code was initially kept
+in the isolated compatibility worktree. Only the two owned Codex test tmux
+servers were stopped after completion, with their socket, sole pane, workspace,
+PID, and birth revalidated. The designated Herdr process retained its original
+91 by 29 viewport. A later user-authorized local installation updated the
+standalone CLI, plugin, and Skill to this exact runtime, restarted only the
+Gateway, and passed `agent-knock-knock doctor --timeout-ms 60000`. The user
+reported successful manual testing before authorizing publication.
+
+
+## Publication gate for 0.13.14
+
+After the user's successful local test and explicit publication authorization,
+`npm run test:release` passed on 2026-10-01:
+
+- Full suite: **2,851 passed**, zero failures, cancellations, or skips.
+- Isolated OpenClaw 2026.9.1: install, runtime loading, callback, Doctor, bundled
+  Skill, tmux fixture/diagnostics, update/reinstall, and uninstall passed.
+- ClawHub Plugin Inspector runtime validation: **PASS**, with the real SDK.
+- ClawHub publish dry-run: passed with the `herdr` topic retained.
+
+The first full run exposed seven old TAB-separated tmux viewport fixture
+responses across four test helpers, causing eleven failures. Those fixtures now
+return the requested ASCII `x` format and assert the exact format argument;
+negative malformed-viewport and native input safety assertions remain intact.
+The final run above includes those corrections. Production runtime and Skill
+hashes remained identical to the native-tested and user-tested candidate above.
+No additional credentialed native lifecycle smoke was run; the existing actual
+native observations and their limitations remain the evidence for that scope.

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. 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.
+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.
 
 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 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`.
+Watch follows the user's selected terminal. Codex 0.158.0/0.159.0/0.159.2 exact Watch creation types a closed `/status` command into an available main Composer to bind its foreground task; later observation is read-only. See the [compatibility boundaries](codex-0.159.2-compatibility.md). 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,9 +118,9 @@ 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/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.
+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/0.159.2 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/2.1.285. 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. 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.
+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/0.159.2 exact Send and active-task Watch use a separate closed `/status` transaction to bind the foreground paginated thread.
 
 ## 5. Watch an existing terminal task
 
@@ -136,7 +136,7 @@ Copy the row's complete `terminal_id`. An advertised `available_actions.watch` i
 /akk watch <exact-terminal-id>
 ```
 
-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`.
+Watch follows the exact terminal selected by the user. Codex 0.158.0/0.159.0/0.159.2 exact Watch creation types a closed `/status` command into an available main Composer to bind its foreground task; later observation is read-only. See the [compatibility boundaries](codex-0.159.2-compatibility.md). Agent-version or artifact uncertainty, missing binding metadata, existing AKK-managed ownership, and missing action advertisement produce warnings rather than blocking creation. AKK fails only when the exact terminal is absent, its endpoint/process cannot be identified, neither an exact durable task anchor nor a read-only screen-status path exists, or its durable Store record cannot be created. Prefer an existing managed monitor when its exact Turn attribution is what you need, but Watch can coexist without adopting or mutating it. New exact-task Watches and accepted exact-request fallback Watches default to `respond_when_exact`; a supported native interaction emits `interaction_required`, and the owning controller must call Status before it receives a single-use response offer. Terminal-activity/best-effort Watches and manual-only shapes emit `interaction_manual_required` with `capabilities.interaction_respond=false`.
 
 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.13",
+  "version": "0.13.14",
   "description": "Control local Codex and Claude Code from OpenClaw or compatible controller Hosts through shared terminals.",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,9 @@
     "LICENSE",
     "CHANGELOG.md",
     "docs/codex-0.158.0-compatibility.md",
-    "docs/codex-0.159.0-compatibility.md"
+    "docs/codex-0.159.0-compatibility.md",
+    "docs/codex-0.159.2-compatibility.md",
+    "docs/claude-2.1.285-compatibility.md"
   ],
   "publishConfig": {
     "access": "public"

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

@@ -42,13 +42,13 @@ 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. 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.
+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/0.159.2 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.
+Codex 0.158.0/0.159.0/0.159.2 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.
 
@@ -78,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 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.
+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/0.159.2 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 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.
+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/0.159.2 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.
 
@@ -99,11 +99,11 @@ Do not treat ordinary Send's whole-draft Composer replacement as a native conver
 
 ## Terminal Watch
 
-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.
+Terminal Watch follows the exact terminal selected by the user. Codex 0.158.0/0.159.0/0.159.2 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 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.
+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/0.159.2 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 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.
+At creation, AKK first tries to build a privacy-safe exact provider task anchor. Codex 0.158.0/0.159.0/0.159.2 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/0.159.2 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.
 
@@ -130,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/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.
+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/0.159.2 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/2.1.285 `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. 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.
+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/0.159.2 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.
 
@@ -232,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`: 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.
+- `watch` / `unwatch`: create or stop durable terminal observation; Codex 0.158.0/0.159.0/0.159.2 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.