@scotthuang/agent-knock-knock 0.14.8 → 0.14.10

package/docs/list-output.md

@@ -0,0 +1,53 @@
+# List output and history
+
+AKK 0.14.9 bounds the entire controller-facing List result before serializing
+JSON. Current conversations come first; healthy ended Watches no longer crowd
+them out. Failed or uncertain callbacks, pending interactions and active
+observations remain in the current view. This changes presentation, not Watch
+deadlines, callback delivery or persisted history.
+
+| Request | Included records |
+| --- | --- |
+| `{}` or `{"listView":"current"}` | Conversations and current/attention-needed observations |
+| `{"listView":"history"}` | Healthy ended Watches and retained managed Turns |
+| `{"listView":"all"}` or `{"all":true}` | Both, still paged |
+
+An explicit `listView` takes precedence over the view selected by `all`.
+`all` continues to control underlying terminal-history discovery; it does not
+mean an unlimited Host response. Raw CLI `list --json` and `list --all --json`
+retain their operator/debug behavior.
+
+Follow `pagination.next_args` unchanged while `pagination.has_more` is true.
+Every page is a fresh read, not a frozen snapshot. If the cursor is invalid
+after membership changes, restart List. `listLimit` defaults to 40 rows and
+accepts 1–100; the output budget may produce a smaller page. Counts describe
+all records observed by that discovery, not only the returned page.
+
+The compact contract is `agent-knock-knock/host-list-compact`, version 3,
+action contract 31. It retains exact conversation, native task and Watch IDs
+and usable action inputs. A very large row becomes a Status reference with
+`details_omitted=true`; omitted actions do not mean unsupported capabilities.
+Refresh exact Status to obtain pending questions, approvals and current actions.
+No progress body is added to List.
+
+`watch_summary` distinguishes current observations from healthy history.
+`pagination.attention_counts` reports failed/uncertain/pending delivery and
+pending interactions even when their rows appear on a later page. Categories
+can overlap. Watches are observations, not extra conversations or independent
+tasks. `callback_expected=false` alone does not mean missing or failed delivery;
+completed notifications and unresolved delivery have different states.
+
+Each page is limited to 24 KiB of UTF-8 JSON and 12,000 conservative weighted
+characters (ASCII costs 1, other Unicode code points cost 16), including its
+metadata. These are not token counts or a guarantee for every custom Host's
+smaller output allowance. The current OpenClaw Codex harness was checked at
+its lowest 16,000-character budget. The limits reduce returned context, not the
+cost of reading the underlying local records.
+
+Desktop catalog pagination is separate: finish the Host pages for one catalog
+page, then use `desktop_scan.next_cursor` as `desktopCursor` with the same
+Desktop filters and no previous Host cursor. Sidebar membership and a saved
+history row still do not prove a live Desktop owner.
+
+See [the operator guide](operator-guide.md), [Desktop discovery](codex-desktop-compatibility.md#find-and-select-a-conversation),
+and [task recovery](backend-task-recovery.md) for the related workflows.

package/docs/operator-guide.md

@@ -29,6 +29,11 @@ its equivalent `turn_id` for follow-up. A project path or title alone is never
 task identity. [Backend task recovery](backend-task-recovery.md) explains how
 to resume observation or release management for that exact task.
 
+Host List returns bounded pages with current conversations first. Follow
+`pagination.next_args` for the rest; use `listView: "history"` for ended
+observations. See [List output and history](list-output.md) for attention
+counts, compatibility and the separate Desktop catalog cursor.
+
 ## Command reference
 
 Direct slash commands are available in every first-party Host integration:
@@ -111,7 +116,7 @@ to obtain completion callbacks. Expiry ends observation, not the native task.
 Existing saved deadlines and repeated message IDs are not extended by an upgrade.
 Managed terminal inactivity remains a separate 60-minute default.
 
-The v30 `action_contracts` expose model-facing semantic IDs only. The trusted
+The v31 `action_contracts` expose model-facing semantic IDs only. The trusted
 adapter privately derives and revalidates terminal, process, binding, native
 thread, composer, approval, handoff, revision, and compare-and-swap evidence.
 Callers never supply those opaque fences.

package/docs/pi-dsh-compatibility.md

@@ -1,10 +1,55 @@
 # Pi and DeepSeek Harness connector compatibility
 
 These are independently versioned controller connectors. Installing an AKK
-core/OpenClaw release does not update an already installed connector. Both
-connectors below pin the published AKK core `0.14.7` and carry its identical
-canonical Skill and 26-tool capability handshake. No new core release is
-required for this update.
+core/OpenClaw release does not update an already installed connector. The
+published 2026-10-14 connectors pin AKK core `0.14.7`; DSH connector `0.1.0-rc.6`
+pins `0.14.8`. Each carries its runtime's canonical Skill and 26-tool
+capability handshake. Neither connector update requires a new core release.
+
+## DSH 0.2.1-rc.2 compatibility — 2026-10-17
+
+`@scotthuang/agent-knock-knock-deepseek-harness@0.1.0-rc.6` is an independent
+**prerelease on npm `next`**, built against DSH `0.2.1-rc.2`, Cordis `4.0.5` and published
+AKK core `0.14.8`. At verification time DSH npm `next` was `0.2.1-rc.2`, while
+`latest` remained `0.2.0-rc.2`; neither is a stable release. The connector's
+npm `latest` remains `0.1.0-rc.1`. Pi and core are unchanged by this release.
+
+The [official DSH release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-rc.2)
+adds DeepSeek-V4.1-Flash-1017 support. Comparing its actual packages with the
+previous RC and alpha shows that AKK's command, Skill, message-source,
+Agent Inbox and ordinary tool contracts remain compatible. PTC cancellation
+and tool-mode changes do not affect the interfaces used by this connector.
+The update aligns exact peers, SDK dependencies, the runtime version check,
+lockfile and core dependency; it does not bypass Host compatibility preflight.
+
+| Verification | Result and evidence boundary |
+| --- | --- |
+| Current RC SDK | Typecheck, 39 fast tests and package/Skill checks passed. |
+| Previous `0.2.0-rc.2` SDK / Cordis `4.0.4` | Final Store patch: isolated typecheck, 39 fast tests and actual coherent launcher/helper resolution passed. |
+| Retained `0.1.5-rc.2` / Cordis `4.0.2` and preview `0.2.1-alpha.2` / Cordis `4.0.5-alpha.1` | Each passed typecheck, 39 fast tests and actual coherent launcher/helper resolution with the final product sources. Old Web/model acceptance was not repeated; `0.1.1-rc.2` and `0.1.2-alpha.1` retain historical policy only. |
+| Actual `0.2.1-rc.2` launcher and native registries | Official peer preflight, coherent runtime resolution and registration of all 26 tools passed. |
+| Native Agent loop and callback helper | Busy injection and idle followup were consumed by a deterministic local provider. Duplicate notifications retained one message/acceptance ID; collisions, disposed/replaced Agents and closed routes were rejected. |
+| Approval and typed-question tool contracts | Real upstream ToolRuntime preserved decisions, exact identifiers and Unicode answers. The downstream coding-agent results in these checks were fixtures, not new live approval/question acceptance tests. |
+
+A real account-backed Web task also passed: the DSH model called Send, the
+dedicated Codex task completed, its callback was accepted once by the DSH
+Inbox, and the DSH model consumed it and replied. This used Codex CLI
+`0.162.1` with the already running backend `0.163.0`; neither that backend nor
+other business sessions were restarted. No external chat delivery was tested.
+
+The live check exposed a separate shared-Store hazard: another Host can claim
+a native callback without the owning DSH profile. An isolated actual-core
+reproduction confirmed this failure mode. The connector now defaults tools
+and lifecycle workers to one stable DSH-specific Store. Explicit Store paths
+are preserved, and old records are neither migrated nor replayed. Parallel
+DSH Hosts/profiles still need distinct explicit Store paths; cross-Host
+ownership filtering in core is outside this change.
+
+The independent connector publication gate runs typecheck, `test:fast`, and
+package/Skill checks on clean synchronized `main`, then publishes to `next`.
+The root OpenClaw release suite is not this connector's publication gate.
+Callback admission, model consumption and external-chat delivery remain separate facts. Old process-owned callback
+routes are not transferred to a restarted Web Host.
 
 ## Upstream versions checked on 2026-10-14
 

package/docs/quickstart-herdr.md

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

package/docs/quickstart-tmux.md

@@ -68,7 +68,7 @@ Success returns a managed turn and, when the work finishes, its result. The same
 
 `/akk list` keeps that physical pane as the primary resource: it appears once in `terminals[]`. Read `screen_state` for the bounded live TUI, `native_identity_state` for foreground native-session resolution, and `durable_activity_state` for exact rollout/transcript task evidence. The legacy `activity_state` remains conservative for compatibility, so an idle screen can coexist with ambiguous native identity, unknown durable activity, and legacy `activity_state="unknown"`. These status axes are diagnostic; use only a current `available_actions` entry for mutations. Its managed context follows terminal → native coding-agent session → AKK `session_id` → Turns. AKK places the active Turn under `managed.current_turn`, or the newest retained Turn under `managed.recent_turn`; retained Turns do not occupy or hide the pane.
 
-For another request, refresh `/akk list` and use only that terminal row's listed v30 `send` action. A `session_exact` action carries `session_id`; `terminal_follow_current` and user-priority `terminal_user_explicit` actions carry `terminal_id`. Add only the new request text. The two target fields are mutually exclusive, and a structured model call never carries a selector, draft text, composer digest, or opaque token. AKK derives and revalidates its freshness fences internally. Managed delivery may require exact empty before input and creates a new `turn_id`; native inspection and lifecycle input remain exact-empty-only. Codex and Claude Code `terminal_user_explicit` advertise the agent-neutral `terminal_user_explicit_composer_policy=replace_current_composer_and_submit`; the older Codex-named field remains a compatibility alias. Codex freezes every open rollout as a candidate instead of trusting one stale root as the foreground thread, then binds the uniquely accepting rollout after Enter. For either agent, once the managed path injects user-explicit text or physical fallback runs, Composer observation cannot veto the one Enter after injection. If managed promotion is unavailable, the physical fallback creates no managed callback Turn; after Enter, AKK best-effort attaches an exact Terminal Watch callback and returns its `watch_id`. Once exact request acceptance is established, that Watch can notify and—after a same-controller Status refresh plus an explicit user answer—respond to a supported native interaction. Before acceptance and for best-effort activity Watches, interaction handling remains notification-only. Attachment failure is a warning and never changes delivery. Check `terminal_input_dispatched` separately from `agent_acceptance`, `management_mode`, and `observation_mode`; once clear or request input may have occurred, an uncertain result must not be retried automatically. A completed Turn is history, not the destination of the next send. Human-friendly selectors such as `codex`, `only`, or `@a1b2c3d4` remain slash-command discovery conveniences; they are not structured action authority.
+For another request, refresh `/akk list` and use only that terminal row's listed v31 `send` action. A `session_exact` action carries `session_id`; `terminal_follow_current` and user-priority `terminal_user_explicit` actions carry `terminal_id`. Add only the new request text. The two target fields are mutually exclusive, and a structured model call never carries a selector, draft text, composer digest, or opaque token. AKK derives and revalidates its freshness fences internally. Managed delivery may require exact empty before input and creates a new `turn_id`; native inspection and lifecycle input remain exact-empty-only. Codex and Claude Code `terminal_user_explicit` advertise the agent-neutral `terminal_user_explicit_composer_policy=replace_current_composer_and_submit`; the older Codex-named field remains a compatibility alias. Codex freezes every open rollout as a candidate instead of trusting one stale root as the foreground thread, then binds the uniquely accepting rollout after Enter. For either agent, once the managed path injects user-explicit text or physical fallback runs, Composer observation cannot veto the one Enter after injection. If managed promotion is unavailable, the physical fallback creates no managed callback Turn; after Enter, AKK best-effort attaches an exact Terminal Watch callback and returns its `watch_id`. Once exact request acceptance is established, that Watch can notify and—after a same-controller Status refresh plus an explicit user answer—respond to a supported native interaction. Before acceptance and for best-effort activity Watches, interaction handling remains notification-only. Attachment failure is a warning and never changes delivery. Check `terminal_input_dispatched` separately from `agent_acceptance`, `management_mode`, and `observation_mode`; once clear or request input may have occurred, an uncertain result must not be retried automatically. A completed Turn is history, not the destination of the next send. Human-friendly selectors such as `codex`, `only`, or `@a1b2c3d4` remain slash-command discovery conveniences; they are not structured action authority.
 
 If the coding agent asks a question and the active Turn becomes `waiting_for_openclaw`, use the listed `respond` action with its prefilled `turn_id`, or the equivalent form:
 

package/docs/testing.md

@@ -190,7 +190,7 @@ The fast tier owns the deterministic Terminal Watch contract:
 | `test/durable-notification-kernel.test.ts` | Store-neutral callback/Watch lease, retry timing, exhaustion, and settlement authorization policy |
 | `test/terminal-submission-acceptance.test.ts`, `test/claude-local-transcript-provider.test.ts` | Preferred exact Codex rollout and Claude current-turn transcript anchors; source-less Codex candidate-set acceptance over anchored plus current roots, including closed-FD frozen-file scans and fail-closed replacement/deletion/multiple-acceptor evidence; drift invalidates an already exact-anchored Watch, while absence or structural incompatibility at manual-Watch creation can be downgraded to a warning and terminal-activity fallback |
 | `test/terminal-watch-cli-adapter.test.ts`, `test/terminal-watch-callback-cli-adapter.test.ts` | Exact-task capture when available; best-effort `terminal_activity` fallback after observed activity and consecutive stable-idle sweeps; `watch_mode`/`confidence`/warning projection; no Session/Turn ownership; exact-Watch same-controller Status and one-shot `respond_interaction({watch_id})`; managed-first responder arbitration; zero-input release versus uncertain dispatch; activity/manual notification-only behavior; hard failure only for an absent/unobservable exact terminal or unwritable Store; privacy-safe callbacks that never present stable idle as exact task completion; and restart-safe exact fallback anchors |
-| `test/terminal-agent-bridge.test.ts`, `test/terminal-list-action-policy.test.ts`, `test/terminal-action-projection.test.ts`, `test/terminal-list-renderer.test.ts`, `test/openclaw-plugin-helpers.test.ts`, `test/quickstart-docs.test.ts` | Broad read-only Watch discovery, direct user-explicit Watch by exact `terminal_id` even without advertisement, Watch status/unwatch routing and formatting, action-contract v30 semantic-ID-only projection including same-controller status-bound native-interaction response, exact Codex model-control residue repair, and explicit foreground identification, three-axis terminal status, Codex and Claude Code user-priority replace-current-Composer delivery without visibility/exactness or post-text Composer vetoes, automatic fallback Watch callback semantics, and the documented terminal selection → exact-task-or-activity Watch workflow |
+| `test/terminal-agent-bridge.test.ts`, `test/terminal-list-action-policy.test.ts`, `test/terminal-action-projection.test.ts`, `test/terminal-list-renderer.test.ts`, `test/openclaw-plugin-helpers.test.ts`, `test/quickstart-docs.test.ts` | Broad read-only Watch discovery, direct user-explicit Watch by exact `terminal_id` even without advertisement, Watch status/unwatch routing and formatting, action-contract v31 semantic-ID-only projection including same-controller status-bound native-interaction response, exact Codex model-control residue repair, and explicit foreground identification, three-axis terminal status, Codex and Claude Code user-priority replace-current-Composer delivery without visibility/exactness or post-text Composer vetoes, automatic fallback Watch callback semantics, and the documented terminal selection → exact-task-or-activity Watch workflow |
 
 The current public surface has 22 OpenClaw tools. Terminal Watch adds the
 `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`
@@ -207,7 +207,7 @@ shown activity and then stable idle across consecutive observations, carries
 controller that the signal is not exact task-completion proof. An initially
 idle or unknown terminal cannot settle until activity has first been observed.
 
-The v30 fast contract also proves that structured model actions expose semantic
+The v31 fast contract also proves that structured model actions expose semantic
 IDs only: Watch uses `terminal_id`; send uses mutually exclusive `session_id` or
 `terminal_id`; native inspection, new, resume, and reconcile use their documented
 terminal/session/thread IDs; and approve or handoff retains explicit-confirmation

package/package.json

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

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

@@ -77,7 +77,7 @@ Desktop rows in `conversations[]` have `surface="desktop"` and a full `desktop:v
 - `model_options({conversation_id})` reads the current model, reasoning effort, and Plan/default mode. Desktop does not expose a model catalog (`catalog_available=false`). Use `set_model({conversation_id,model,reasoning_effort,collaboration_mode?})` only with an explicitly requested model ID; optional `collaboration_mode` is `plan` or `default`. Omitting it preserves the existing mode. Effective settings do not prove a model is available to the account. An unconfirmed update must be inspected, not blindly replayed.
 - Cancel with `cancel({watch_id})` for the exact watched task, or `cancel({conversation_id,expected_native_turn_id})` using the native task ID advertised by fresh Status. A late cancel must never interrupt a newer task. `unwatch` only stops observation. Arbitrary cold loading/resume remains unsupported; explicit creation uses the separate tool below.
 
-Full Desktop control is reviewed for macOS Codex Desktop `26.1002.52244` build `13536` through private local IPC. The profile for `26.1007.30912` build `20156` supports creation and Send/Status/Watch; AKK 0.14.7 also supports command/file approvals with `approve_once` or `reject`. AKK 0.14.8 adds blocking and asynchronous answers with separate capability checks. Permission/model changes and cancellation remain unavailable on that build; handle those controls in Desktop. Use only the currently advertised action. The `13536` full-control profile is unchanged; unknown Desktop builds do not gain native write capability. Read the actual capability and error result after an app update; never downgrade to raw UI input or relax identity checks. The native protocol has no atomic idle-and-send operation, so concurrent human input can make acceptance uncertain. Preserve the returned Watch and reconcile it instead of repeating the task.
+Full Desktop control is reviewed for macOS Codex Desktop `26.1002.52244` build `13536` and, in AKK 0.14.9, `26.1007.71326` build `20398` through private local IPC. The `20398` profile also supports new-conversation creation with its verified bundled backend. Its command/file approvals, blocking/asynchronous answers, settings and exact cancellation have dedicated native-effect evidence; callback acceptance is separate from downstream chat delivery. The older `26.1007.30912` build `20156` supports creation, Send/Status/Watch, command/file approvals and blocking/asynchronous answers, but permission/model changes and cancellation remain unavailable there. Use only the currently advertised action. Unknown Desktop builds do not gain native write capability. Read the actual capability and error result after an app update; never downgrade to raw UI input or relax identity checks. The native protocol has no atomic idle-and-send operation, so concurrent human input can make acceptance uncertain. Preserve the returned Watch and reconcile it instead of repeating the task.
 
 ### Create a Desktop conversation
 
@@ -108,7 +108,7 @@ Core slash-command forms:
 - `/akk respond <turn-selector>: <answer>`: answer a coding-agent question inside a `waiting_for_openclaw` Turn.
 - `/akk cancel <turn-selector>`: interrupt the exact Turn without closing its terminal pane.
 
-For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v30 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. The agent-neutral `terminal_user_explicit_composer_policy` advertises `replace_current_composer_and_submit`; the old Codex-named field is a v28 compatibility alias only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is either managed `terminal_follow_current` or user-priority `terminal_user_explicit`, exactly as advertised; the two target fields are mutually exclusive, and both may be omitted only when AKK must prove one unique send-ready pane. Codex and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer—not ordinary main-Composer visibility, stability, exactness, parsed working activity, existing draft contents, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. Both advertise `replace_current_composer_and_submit`: Codex physical fallback sends `C-u` once; Claude Code physical fallback uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. Native inspection and native lifecycle input remain exact-empty-only. With runtime durability, an omitted target binds its `message_id` to the first selected physical terminal and existing or uncertain same-ID evidence rejects replay. If fresh durability is unavailable, user priority wins: AKK proceeds with a warning, and the degraded result must not be automatically retried. Once clear or request input may have occurred, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. The only non-ordinary Send form is an exact `send({turn_id})` copied unchanged from a current `available_actions.retry_submission`; it accepts no request text or other target and requires explicit user confirmation. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Other managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity and revalidate the relevant approval prompt; Composer revalidation remains action-specific; unreviewed Codex frontends require the styled-Composer checks above.
+For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v31 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. The agent-neutral `terminal_user_explicit_composer_policy` advertises `replace_current_composer_and_submit`; the old Codex-named field is a v28 compatibility alias only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is either managed `terminal_follow_current` or user-priority `terminal_user_explicit`, exactly as advertised; the two target fields are mutually exclusive, and both may be omitted only when AKK must prove one unique send-ready pane. Codex and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer—not ordinary main-Composer visibility, stability, exactness, parsed working activity, existing draft contents, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. Both advertise `replace_current_composer_and_submit`: Codex physical fallback sends `C-u` once; Claude Code physical fallback uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. Native inspection and native lifecycle input remain exact-empty-only. With runtime durability, an omitted target binds its `message_id` to the first selected physical terminal and existing or uncertain same-ID evidence rejects replay. If fresh durability is unavailable, user priority wins: AKK proceeds with a warning, and the degraded result must not be automatically retried. Once clear or request input may have occurred, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. The only non-ordinary Send form is an exact `send({turn_id})` copied unchanged from a current `available_actions.retry_submission`; it accepts no request text or other target and requires explicit user confirmation. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Other managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity and revalidate the relevant approval prompt; Composer revalidation remains action-specific; unreviewed Codex frontends require the styled-Composer checks above.
 
 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.
 
@@ -183,7 +183,7 @@ Hard creation failure includes an absent exact terminal, inability to identify i
 
 Approval attention is notification-only for every Watch: never call an approval tool for a `watch_id`, send approval keys, or apply `autoApprove`. Native-interaction attention is different. An automatic exact request-bound Watch created by `terminal_user_explicit` unmanaged fallback can, after exact request acceptance and attribution, emit `interaction_required`; call Status with its exact `watch_id`, show the projected question to the user, and use `respond_interaction({watch_id,...})` only when that fresh owner-bound projection advertises `capabilities.respond=true`. A terminal-activity Watch or `interaction_manual_required` callback remains notify-only: tell the user to inspect and answer in the live TUI, and send no interaction input. Each new exact attention fingerprint is notified once while the Watch remains active. Terminal outcomes settle once. The durable outbox uses deterministic notification IDs/idempotency and leased retry, so startup and periodic supervision can safely recover callback delivery after AKK, OpenClaw, or Gateway restart.
 
-The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v30. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v1 and point here for the static contract; the CLI keeps the complete operator/debug action contract. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
+The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v31. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v3 and point here for the static contract; the CLI keeps the complete operator/debug action contract. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
 
 For Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Codex 0.160 may report `current="workspace_granular"`; this is a current-only native default, not a selectable mode. Select only an ID actually returned in `choices`. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
 
@@ -292,11 +292,15 @@ A trusted, default-disabled plugin `autoApprove` policy may independently approv
 
 ## Terminal Sessions
 
-The model-facing `agent_knock_knock_list` presents `conversations[]` once. Exact matched Codex terminal/backend representations are coalesced; unproven matches remain separate, and unconnected Desktop candidates stay visible. Raw CLI output retains the provider arrays for diagnostics. Terminal-backed rows still include retained managed context without duplicating the pane. The terminal resource chain is terminal → verified native session → managed AKK `session_id` → Turns; independent terminal observation records appear in `terminal_watches[]` and are addressed only by `watch_id`. `process_state` reports process liveness. Read `screen_state` as bounded live-TUI evidence, `native_identity_state` as foreground native-session resolution, and `durable_activity_state` as exact artifact-backed task activity. The legacy `activity_state` is a conservative compatibility projection and may remain `unknown` while `screen_state="idle"`; none of these diagnostic fields replaces `available_actions` authority. `managed.current_turn` is the authoritative active Turn for that terminal; otherwise `managed.recent_turn` shows the newest retained context. A human-driven thread mismatch remains `management_state="conflict"`; `handoff_state="external_handoff_adoptable"` authorizes only the exact fenced `send` advertised on that row, while `external_handoff_blocked` means do not send or guess a recovery. Listing itself never adopts the new context. Request `all=true` only when older `managed.history`, settled Terminal Watches, or retained unavailable history is needed. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
+The model-facing `agent_knock_knock_list` presents `conversations[]` once. Exact matched Codex terminal/backend representations are coalesced; unproven matches remain separate, and unconnected Desktop candidates stay visible. Raw CLI output retains the provider arrays for diagnostics. Terminal-backed rows still include retained managed context without duplicating the pane. The terminal resource chain is terminal → verified native session → managed AKK `session_id` → Turns; independent terminal observation records appear in `terminal_watches[]` and are addressed only by `watch_id`. `process_state` reports process liveness. Read `screen_state` as bounded live-TUI evidence, `native_identity_state` as foreground native-session resolution, and `durable_activity_state` as exact artifact-backed task activity. The legacy `activity_state` is a conservative compatibility projection and may remain `unknown` while `screen_state="idle"`; none of these diagnostic fields replaces `available_actions` authority. `managed.current_turn` is the authoritative active Turn for that terminal; otherwise `managed.recent_turn` shows the newest retained context. A human-driven thread mismatch remains `management_state="conflict"`; `handoff_state="external_handoff_adoptable"` authorizes only the exact fenced `send` advertised on that row, while `external_handoff_blocked` means do not send or guess a recovery. Listing itself never adopts the new context. Request `all=true` only when older `managed.history`, settled Watches, or retained unavailable history is needed; Host results remain paginated, not an unlimited dump. By default, `unavailable_managed_turns[]` contains attention-needed records whose terminal is unavailable.
 
 ### Compact controller-Host List projection
 
-The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=1`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, explanatory `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
+The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=3`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, explanatory `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
+
+**Bounded List pages:** default `listView="current"` puts conversations first, followed by active observations and unresolved attention (including failed/uncertain/pending callbacks and pending interactions). Healthy ended Watches are counted in `watch_summary`, not repeated inline. Older managed terminal Turns are paged separately in `managed_turns`; unresolved delivery remains in the current view and safe callback state stays visible. `callback_expected=false` does not by itself remove an unresolved callback, and omitted healthy history does not mean that Send had no Watch. Use `listView="history"` for healthy ended Watches or `listView="all"`/`all=true` for both. An explicit `listView` overrides the default selected by `all`.
+
+Every Host page has a total row limit (`listLimit`, default 40, maximum 100) and a 24 KiB UTF-8 serialized JSON ceiling plus a conservative 12,000 weighted-character budget (ASCII 1, other Unicode code points 16), including metadata. These are output bounds, not token counts. Follow `pagination.next_args` unchanged while `has_more=true`; the count of omitted rows is explicit. This cursor is independent of `desktopCursor`: first finish Host pages for one Desktop catalog page, then follow `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Pages are fresh discovery snapshots, not frozen history: if membership changes and a cursor is invalid, restart List. Never treat a partial page as the complete inventory. No progress body is added to List; use exact conversation/Watch Status. Very large individual records retain exact IDs and attention state with `details_omitted=true` and a Status entry point; their omitted actions are **not** proof of unsupported capabilities. Full current action/interaction details must be refreshed with Status before acting. Raw CLI `list --json` remains the complete operator/debug contract; `--all` retains its existing history behavior. These bounds reduce Host output, not native discovery/read cost.
 
 For every resource, `available_actions` is an object whose keys are the exact current semantic action names and whose values are `true`. `action_inputs` contains only dynamic semantic values that cannot be derived from the parent resource, plus scope, permitted decision values, and fields listed by `missing_required`; it does not repeat the same terminal/Session/Turn/Watch ID for every action. The parent `conversation_id` is the target for Send, Status, Watch and supported conversation settings; AKK chooses the operation route. For capability-specific terminal actions, the terminal `id` remains the full `terminal_id`; managed and Watch records expose their own `session_id`, `turn_id`, or `watch_id`. `features` is only a compact capability-status summary and never authorizes an action. Never infer an absent action. The compact display is not the enforcement boundary: the plugin caches the complete private offer before projection, and the CLI re-observes and revalidates the live pane under its action lock before every mutation.