@scotthuang/agent-knock-knock 0.14.11 → 0.14.13

package/docs/list-output.md

@@ -1,71 +1,77 @@
-# List output and history
+# Conversations and Watch inventory
 
-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.
+Since 0.14.13, discovery is separate from monitoring. `agent_knock_knock_list`,
+`/akk list` and CLI `list` return currently discoverable conversations. They do
+not include Watch inventories or retained managed Turn history. Current managed
+ownership, pending approvals and blocking conditions remain on the conversation.
+Desktop sidebar entries whose live owner is unconfirmed remain visible with
+their actual connection status; visibility does not authorize Send.
 
-Starting in 0.14.11, default CLI rows combine only proven exact aliases. A
-verified backend stays selectable when a same-project terminal is unresolved,
-including an unknown/history viewport. These are separately addressable
-connections, not a count of independent tasks. Hosts may group them by project,
-but must preserve each exact target and its actions. `terminalDebug` adds routing
-evidence; it is no longer needed to reveal an unassociated backend. Neither cwd
-nor a startup `resume` argument authorizes redirecting a terminal target.
+Use `agent_knock_knock_watches`, `/akk watches` or CLI `watches` to inspect
+monitoring. This is a read-only Store query: it does not create or renew a Watch,
+reconcile callbacks, reconnect a native session or send notifications.
 
-| 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 |
+## Conversation selection
 
-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.
+Since 0.14.12 the default view prefers a verified backend as the project's CLI
+entry when discovery finds one same-agent terminal and one loaded backend with
+no known identity conflict. Its original conversation ID, title, status and
+actions are retained. Terminal candidates remain in `terminalDebug` /
+`list --terminal-debug`. Proven exact aliases combine verified capabilities;
+display grouping alone does not copy terminal permissions or redirect selectors.
+Multiple candidates, conflicts and terminals needing management recovery remain
+visible. Rows and connections are not a count of independent tasks.
 
-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.
+Host List uses `agent-knock-knock/host-list-compact` v4. Follow
+`pagination.next_args` while `has_more` is true. `listLimit` defaults to 40 and
+accepts 1–100. Pages are fresh discoveries, not a frozen snapshot; restart if
+membership changes invalidate a cursor. Legacy `listView=history/all`, `all=true`
+and CLI `list --all` return a migration error directing callers to `watches`.
 
-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.
+Each Host page is capped at 24 KiB of UTF-8 JSON and 12,000 weighted characters
+(ASCII 1, other code points 16), including metadata. This is not a token budget.
+Oversized rows retain exact IDs and a Status entry point; omitted actions do not
+mean unsupported capabilities. Read exact Status for current questions, approvals
+and bounded public progress. List contains no progress body.
 
-`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.
+Desktop catalog pagination remains separate: finish Host pages for one catalog
+page, then pass `desktop_scan.next_cursor` as `desktopCursor` with the same filters
+and no previous Host cursor. Explicit Desktop catalog history is a separate
+native discovery view, not AKK Watch history.
 
-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.
+## Monitoring and retention
 
-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.
+`watches` defaults to a 24-hour lookback, 40 rows per page (maximum 100) and the
+same whole-response output limits. The lookback may be set from 1 to 48 hours.
+Continuation freezes the query's `as_of` and filters, not the underlying Store;
+refresh before acting. Active or unresolved observations remain visible even
+outside the lookback, marked `outside_window`. Retained terminal managed Turns
+are listed separately from Watches so offline recovery is still discoverable.
+Use each row's exact Status input to inspect it; managed rows retain the existing
+pane-independent Close / callback-retry actions where permitted; these records are
+observations, not additional conversations or a count of independent tasks.
 
-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.
+Healthy completed Watch bodies become eligible for cleanup 48 hours after
+settlement and callback completion. Cleanup is bounded and performed by Host
+maintenance, at most once per hour and up to 100 records per pass. Active,
+failed, uncertain, pending-interaction or otherwise unresolved records are
+retained. Managed Turns, Sessions and native coding-agent history are not deleted.
 
-Terminal Send routing uses the same authoritative action projection as List,
-then revalidates the current process, endpoint, approval and input ownership at
-dispatch. A displayed action is not permission to bypass a changed terminal.
-New route journals record a preparation rejection with `request_dispatched:false`
-only when no executor has started. The v1 `reserved` route remains pinned;
-this is neither task acceptance nor uncertain delivery. An explicit retry with
-the same message ID can prepare that same route again, never switch transports.
-Executor failures retain uncertain semantics. Legacy records without phase
-proof are left conservative; upgrades do not replay or rewrite old outcomes.
+Cleanup writes a minimal durable tombstone before removing the body. It retains
+the provider, exact Watch ID, settlement/prune time and record fingerprint, not
+prompts, results or callback payloads. Old deterministic Send IDs cannot recreate
+a task after cleanup. An exact request for pruned history returns
+`watch_history_expired` with replay forbidden, not a misleading missing-record
+success. Tombstones are retained for deduplication; this is not a promise that
+all AKK metadata disappears after 48 hours. Writer protocol 10 prevents older processes from recreating pruned requests;
+rolling back requires a coherent pre-upgrade Store backup, not lowering the manifest.
+Nothing is cleaned merely by reading
+`list` or `watches`.
+
+`callback_expected=false` alone is not a delivery failure or proof of delivery.
+Native completion, controller callback acceptance and delivery to an external
+chat remain separate states. Missing Watch fields in List are intentional, not
+proof that Send lacked monitoring. Query `watches` or the exact returned Watch ID.
+
+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).

package/docs/operator-guide.md

@@ -29,10 +29,12 @@ 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.
+Host List returns bounded pages of currently discoverable conversations. Follow
+`pagination.next_args` for remaining conversations. Use `agent_knock_knock_watches`
+or `/akk watches` for recent monitoring and unresolved callbacks; absence of Watch
+fields in List does not mean Send had no monitoring. See
+[List and Watch inventory](list-output.md) for the 24-hour query window,
+48-hour eligible-history retention and separate Desktop catalog cursor.
 
 ## Command reference
 
@@ -42,7 +44,8 @@ Direct slash commands are available in every first-party Host integration:
 | --- | --- |
 | `/akk <task>` | Send a task when AKK can prove one unique send-ready terminal. |
 | `/akk <selector>: <message>` | Send to the exact selector returned by the current list. |
-| `/akk list` | Discover conversations, managed work, Watches, and supported actions. |
+| `/akk list` | Discover conversations and their supported actions. |
+| `/akk watches` | Read recent monitoring and unresolved records; follow pagination for more. |
 | `/akk watch <terminal-id>` | Observe one exact terminal task. |
 | `/akk unwatch <watch-id>` | Stop observation of one terminal or backend Watch without stopping its native task. |
 | `/akk threads <terminal-id>` | List resumable native threads for one terminal. |
@@ -60,13 +63,15 @@ Direct slash commands are available in every first-party Host integration:
 
 AKK List presents **CLI** and **Desktop** in one `conversations[]` collection,
 with Codex/Claude Code as the agent type. Choose the displayed conversation and
-action; AKK selects the connection. The default view groups a one-to-one
-same-agent/project terminal and direct candidate without changing the terminal's
-identity, status, actions or dispatch checks. Multiple candidates and known
-identity conflicts stay separate; direct-only CLI conversations remain visible.
-Use `terminalDebug: true` or `list --terminal-debug` for all unassociated
-connections and routing details. A display group is not proof that its candidates
-are the same native session, and neither rows nor Watches are a task count.
+action; AKK selects the connection. The default view prefers the verified backend
+entry for a one-to-one same-agent/project discovery pair, preserving the
+backend's exact ID, status and actions. A terminal candidate does not donate
+unverified capabilities or management to that entry. Multiple candidates,
+known identity conflicts and terminal attention/recovery records stay visible;
+direct-only and terminal-only CLI conversations remain available.
+Use `terminalDebug: true` or `list --terminal-debug` for all connections and
+routing details. A display group is not proof that its candidates are the same
+native session, and neither rows nor Watches are a task count.
 Bound task and interaction IDs retain their original provider; uncertain input
 is never retried through another transport. The
 [CLI backend guide](codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10)
@@ -76,9 +81,9 @@ The terminal-specific commands in the table require a physical terminal;
 Desktop interaction, model, permission, and cancellation controls use their
 advertised semantic tools. Backend and terminal capabilities are distinct.
 Raw CLI output retains provider arrays, including `terminals[]`, for diagnostics.
-Within a terminal row, the optional `managed.current_turn` is active work; `managed.recent_turn` is
-retained history and does not occupy the terminal. Attention-needed records
-whose pane is unavailable appear in `unavailable_managed_turns[]`.
+Within a terminal row, `managed.current_turn` is current managed work. Retained
+managed Turn history, including records whose pane is unavailable, is queried
+separately through `watches` and exact Status.
 
 Terminal status has three independent evidence axes. `screen_state` describes
 the bounded live TUI (`idle`, `working`, `awaiting_approval`, or `unknown`);

package/docs/storage-and-logging.md

@@ -21,17 +21,17 @@ remain private.
 ## Compatibility manifest
 
 The manifest checks storage format and writer behavior separately. An unknown
-`format_version` is not read. The current writer protocol is 9; writer
-protocols 1 through 8 are supported predecessors and inspection reports them
+`format_version` is not read. The current writer protocol is 10; writer
+protocols 1 through 9 are supported predecessors and inspection reports them
 as `upgradeable`.
 
 Upgrading protocol 1 or 2 validates predecessor Turn records,
 deterministically derives and durably materializes authoritative Session
 records, quarantines ambiguous Session bindings, and finishes by atomically
-publishing protocol 9. Existing Turn state, event logs, and the original
+publishing protocol 10. Existing Turn state, event logs, and the original
 manifest `created_at` remain unchanged.
 
-Protocols 3 through 8 already have Session authority, so their upgrade is an
+Protocols 3 through 9 already have Session authority, so their upgrade is an
 atomic manifest-only writer fence with no data migration. Protocol 6 prevents
 older writers from rejecting or damaging schema-v2 Terminal Watch records.
 Protocol 7 fences the `interaction_manual_required` notification kind from
@@ -41,7 +41,10 @@ policy, subject-aware projection, one-shot reservation, and callback-outbox
 state; its version fence makes older strict Watch decoders reject the record
 instead of rewriting unknown authority. Legacy schema-v1/v2 Watches are
 normalized to `notify_only`; they never silently acquire terminal response
-authority. Downgrading after v3 records exist is not supported. Core
+authority. Downgrading after v3 records exist is not supported. Protocol 10 additionally requires deletion receipts before pruning completed Watch
+bodies, preventing older writers from recreating an expired Send. Do not manually
+lower the manifest for rollback: restore a coherent pre-upgrade backup instead.
+Core
 Session/Turn data remains readable across a writer-protocol mismatch, while
 explicit reconciliation reports `skipped` and managed mutations fail before
 terminal or Host side effects. This does not prohibit an independently

package/docs/testing.md

@@ -233,8 +233,8 @@ replays terminal input while resolving that identity.
 The semantic
 `native_thread_id` remains public for resume. The plugin/CLI still derives and
 revalidates those private fences under lock. Store format remains 1 and the
-Terminal Watch schema is 3; writer protocol 9 fences capability-checked paginated task
-bindings and private native-question checkpoints from older writers. It retains
+Terminal Watch schema is 3; writer protocol 10 fences capability-checked paginated task
+bindings, private native-question checkpoints and Watch deletion receipts from older writers. It retains
 the manual-interaction notification state and bounded callback metadata introduced
 in writer protocol 7. The Watch schema version fences the response aggregate.
 

package/openclaw.plugin.json

@@ -16,6 +16,7 @@
   "contracts": {
     "tools": [
       "agent_knock_knock_list",
+      "agent_knock_knock_watches",
       "agent_knock_knock_watch",
       "agent_knock_knock_unwatch",
       "agent_knock_knock_list_resumable_threads",
@@ -47,6 +48,9 @@
     "agent_knock_knock_list": {
       "optional": true
     },
+    "agent_knock_knock_watches": {
+      "optional": true
+    },
     "agent_knock_knock_watch": {
       "optional": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.14.11",
+  "version": "0.14.13",
   "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

@@ -21,7 +21,7 @@ Keep the user's requested scope and approval boundaries. Do not expand a task, a
 
 Present `conversations[]` as **CLI** or **Desktop** using `surface`, and keep Codex/Claude Code as the agent type. Select the displayed `conversation_id` and its advertised operation; AKK chooses the connection internally. Do not make separate user-facing backend and terminal lists, repeat raw discovery arrays, or count Watches as additional conversations or tasks. Preserve unavailable actions, current questions/approvals, and management/recovery records. Scoped controls, when present, are operations on exact targets within a row, not extra conversations.
 
-Default CLI presentation combines only proven exact aliases. An independently verified backend remains selectable even when a same-project terminal has unknown identity or activity. Unassociated connections retain their own exact conversation IDs; group them visually by project if helpful, but do not assume they are separate tasks or the same native session. A matching cwd or startup resume UUID never authorizes redirecting a terminal selector. Use `terminalDebug: true` (CLI `list --terminal-debug`) for additional routing evidence; it is not required to discover an unassociated backend.
+Default CLI presentation prefers the verified backend entry for a one-to-one same-agent/project discovery pair without known identity conflicts. Use that returned conversation ID and its actions directly; do not search for or choose an alternative transport. Its title, state and actions belong to the selected backend. Presentation preference does not prove a terminal alias, copy terminal permissions, or redirect a previously selected terminal ID. Multiple candidates, conflicts and terminal attention/recovery records remain visible. Proven exact aliases still combine verified controls. Use `terminalDebug: true` (CLI `list --terminal-debug`) only when connection diagnostics are needed, not as a routine selection step.
 
 AKK prefers a reachable direct connection only after proving the exact selected native session and process or thread. An unavailable backend may retain an eligible terminal path; busy/blocked state or identity conflict cannot authorize bypass. Targeted operations on an idle terminal can use the existing advertised `/status` inspection to learn its identity; working or blocked terminals are not interrupted. List itself sends no terminal input. Keep an uncertain dispatch receipt and inspect it instead of retrying through another connection.
 
@@ -158,7 +158,7 @@ For ordinary send or an in-flight answer:
 
 1. Reuse an AKK session only when the user's reference uniquely identifies its verified native session and terminal incarnation.
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
-3. Treat `conversations[]` as the primary resource list; older raw CLI output may expose `terminals[]` instead. For a terminal-backed row, its managed context exposes `session_id`; `managed.current_turn` is the only current AKK owner, while `managed.recent_turn` and `managed.history` are retained Turn history. Records in `unavailable_managed_turns[]` have no live pane in this snapshot.
+3. Treat `conversations[]` as the primary resource list; older raw CLI output may expose `terminals[]` instead. For a terminal-backed row, its managed context exposes `session_id`; `managed.current_turn` is the current AKK owner. Query `watches` for retained monitoring and managed Turn history, including unavailable-pane recovery.
 4. Read the selected resource's `available_actions`. In the compact Host projection its keys are the exact current action names and each value is `true`; `action_inputs`, when present, carries only dynamic semantic arguments, `missing_required`, and scope. For every mutation, use only an advertised action, start with those semantic inputs, supply every `missing_required` field, and follow this skill's action rules. User-selected Watch is the exception: explicit user intent plus one complete exact `terminal_id` is sufficient even when `available_actions.watch` is absent. The only additional mutation sources are a terminal row's `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`: use either only after explicit user confirmation and refresh the list immediately afterward.
 5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context and may require exact empty before input. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules apply only if AKK selects terminal delivery. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the new request and submits exactly once without a post-text Composer veto. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. Managed delivery is attempted where eligible, but a proven zero-input failure falls back to one unmanaged delivery with no managed callback Turn. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence or composer authority. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
 6. If multiple terminals match, show their `short_ref`, agent, provider, and terminal target, then ask the user to choose. If a human switch has an unresolved Turn, ambiguous ownership, or unverifiable identity and no follow-current send is advertised, report that blocker and ask the user which context to resolve; never guess, supersede active work, or bypass the fence.
@@ -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 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`.
+The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v32. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v4 and point here for the static contract; the CLI keeps the complete operator/debug action contract. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
 
 For Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Codex 0.160 may report `current="workspace_granular"`; this is a current-only native default, not a selectable mode. Select only an ID actually returned in `choices`. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
 
@@ -292,15 +292,19 @@ 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 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.
+The model-facing `agent_knock_knock_list` presents `conversations[]` once. Exact matched Codex terminal/backend representations are coalesced. A unique nonconflicting project pair prefers its backend entry without claiming an exact alias; ambiguous or attention-needed terminal records and unconnected Desktop candidates stay visible. Raw CLI output retains provider arrays for diagnostics. The terminal resource chain is terminal → verified native session → managed AKK `session_id` → Turns. Independent observations are queried through `watches` and addressed by `watch_id`. `process_state` reports process liveness; `screen_state` is bounded TUI evidence, `native_identity_state` is foreground identity resolution, and `durable_activity_state` is exact artifact-backed activity. `activity_state` can remain unknown even if the screen looks idle; none replaces advertised action authority. `managed.current_turn` is the current Turn. Historical contexts are absent from List. A human-driven thread mismatch remains `management_state="conflict"`; `external_handoff_adoptable` authorizes only the exact fenced Send advertised on the row, while `external_handoff_blocked` means do not send or guess recovery. Listing never adopts a new context.
 
 ### Compact controller-Host List projection
 
-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.
+The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=4`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, explanatory `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
 
-**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`.
+**Conversation-only List:** List returns currently discoverable conversations, including Desktop sidebar entries with unconfirmed live owners. It never includes Watch inventories or retained managed history. Keep current ownership, blockers and advertised approvals; do not interpret missing Watch fields as missing Send monitoring. Use `agent_knock_knock_watches` or `/akk watches` to inspect observations. Legacy `listView="history"/"all"`, `all=true` and CLI `list --all` return a migration error.
 
-Every Host 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.
+Every Host List page has a total row limit (`listLimit`, default 40, maximum 100), a 24 KiB UTF-8 JSON ceiling and a conservative 12,000 weighted-character budget (ASCII 1, other code points 16), including metadata. Follow `pagination.next_args` unchanged while `has_more=true`. Desktop catalog pagination is separate: finish the Host pages, then use `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Discovery pages are live snapshots; restart if membership changes invalidate the cursor. No progress body is added to List. Oversized rows retain exact IDs and a Status entry point; omitted actions do not mean unsupported capabilities. Refresh exact Status before acting.
+
+**Watch inventory:** `agent_knock_knock_watches` / `/akk watches` / CLI `watches` is a read-only Store query, defaulting to the most recent 24 hours, 40 rows per page (maximum 100), with a whole-response budget. `hours` accepts 1–48. Active or unresolved observations older than the window remain visible as `outside_window`; terminal managed Turns are a distinct section. Follow the returned pagination arguments. The query does not create/renew monitoring, reconcile or resend notifications. Use exact Status for actionable questions, approvals, callback recovery or full results. Native completion, controller acceptance and chat delivery are separate; `callback_expected=false` alone is neither failure nor delivery proof.
+
+Healthy completed Watch bodies are eligible for bounded background cleanup after 48 hours. Active, pending-interaction and unresolved callback records are retained. Cleanup preserves minimal deduplication tombstones; an exact expired record reports `watch_history_expired` and forbids replay. Never resend an old task because its body was pruned. Managed Turns, Sessions and native history are not deleted. See `docs/list-output.md` for retention and migration details.
 
 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.
 
@@ -326,7 +330,7 @@ Action-name glossary:
 
 The tool name is normally `agent_knock_knock_<action-name>`. The sole List alias is `retry_submission`, which invokes `agent_knock_knock_send` with its listed `turn_id` only after explicit confirmation. Nested `handoff_decision.choices.take_over_current.action` and `blocking_turns[].recovery_action` carry their explicit tool/action name and semantic arguments; the explanatory choice and recovery text is defined here rather than repeated in every List row.
 
-`available_actions` is the authoritative current-action source for mutations after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`; user-selected `watch({terminal_id})` deliberately honors an exact user-selected terminal even without advertisement. A native interaction response instead requires the current `interaction_state` returned by Status in the same controller conversation. Approval, native interaction response, handoff takeover, and `reconcile_binding` require explicit user intent and fresh source state. Model-facing shapes include `permission_options({terminal_id})` and `set_permissions({terminal_id,mode})`; `model_options({terminal_id})`, the separately advertised Codex-only `repair_model_control({terminal_id})`, and `set_model({terminal_id,model,reasoning_effort})`; `watch({terminal_id})`; `send({session_id|terminal_id,request})`, with the targets mutually exclusive; `identify_foreground({terminal_id})`; `identify_and_send({terminal_id,request})`; `respond_interaction({turn_id|watch_id,interaction_id,answers,delivery_mode?})`, with exactly one subject id, only projected question/option ids, and `delivery_mode` present only for `async_question`; managed `approve({turn_id,decision})` or approve-once-only terminal-scoped `approve({terminal_id})`; `native_inspect({terminal_id,inspection})`; `new_thread({terminal_id})`; `resume_thread({terminal_id,native_thread_id})`; and `reconcile_binding({terminal_id,conflicting_session_id})`. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request; human-facing numbers and short IDs remain slash-navigation aids and are never structured tool arguments. The model never carries terminal, binding, catalog, candidate, composer, handoff, approval, interaction-fingerprint, revision, binding ID/generation, or handoff-only live-native-UUID fences; it never receives draft text or composer digests. `native_thread_id` remains the semantic resume identity. AKK derives those private fences and revalidates them before side effects. Orphan-close `expected_message_id` and `expected_transition_id` remain because they are entity IDs. Store format remains 1 and writer protocol is 9; Terminal Watch schema remains 3.
+`available_actions` is the authoritative current-action source for mutations after listing except for the explicitly modeled nested handoff decision and `blocking_turns[].recovery_action`; user-selected `watch({terminal_id})` deliberately honors an exact user-selected terminal even without advertisement. A native interaction response instead requires the current `interaction_state` returned by Status in the same controller conversation. Approval, native interaction response, handoff takeover, and `reconcile_binding` require explicit user intent and fresh source state. Model-facing shapes include `permission_options({terminal_id})` and `set_permissions({terminal_id,mode})`; `model_options({terminal_id})`, the separately advertised Codex-only `repair_model_control({terminal_id})`, and `set_model({terminal_id,model,reasoning_effort})`; `watch({terminal_id})`; `send({session_id|terminal_id,request})`, with the targets mutually exclusive; `identify_foreground({terminal_id})`; `identify_and_send({terminal_id,request})`; `respond_interaction({turn_id|watch_id,interaction_id,answers,delivery_mode?})`, with exactly one subject id, only projected question/option ids, and `delivery_mode` present only for `async_question`; managed `approve({turn_id,decision})` or approve-once-only terminal-scoped `approve({terminal_id})`; `native_inspect({terminal_id,inspection})`; `new_thread({terminal_id})`; `resume_thread({terminal_id,native_thread_id})`; and `reconcile_binding({terminal_id,conflicting_session_id})`. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request; human-facing numbers and short IDs remain slash-navigation aids and are never structured tool arguments. The model never carries terminal, binding, catalog, candidate, composer, handoff, approval, interaction-fingerprint, revision, binding ID/generation, or handoff-only live-native-UUID fences; it never receives draft text or composer digests. `native_thread_id` remains the semantic resume identity. AKK derives those private fences and revalidates them before side effects. Orphan-close `expected_message_id` and `expected_transition_id` remain because they are entity IDs. Store format remains 1 and writer protocol is 10; Terminal Watch schema remains 3.
 
 Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Native inspection and lifecycle input require an exactly empty Composer; managed Send may require exact empty before input. Codex and Claude Code `terminal_user_explicit` instead require a scanned non-blocked approval state and no proven input-owning questionnaire, editor, menu, or read-only viewer. Reviewed physical Send paths do not require ordinary main-Composer visibility, stability, or exactness. Unreviewed Codex frontends require a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Existing drafts and parsed working activity do not themselves veto the user-priority path, and after text injection no Composer observation may veto Enter. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Humans can attach to the same tmux or Herdr session and continue directly at any time.