@scotthuang/agent-knock-knock 0.15.0 → 0.16.1

package/docs/storage-and-logging.md

@@ -16,22 +16,23 @@ remain private.
 - The Store manifest fences incompatible managed writers before managed
   terminal or callback mutations. An eligible explicit physical Send retains
   its separate runtime receipt and input-safety checks; it cannot mutate an
-  incompatible managed Store.
+  incompatible managed Store. Conflicting or unfinished cross-Store authority
+  also blocks physical fallback; a physical Send token cannot bypass that fence.
 
 ## Compatibility manifest
 
 The manifest checks storage format and writer behavior separately. An unknown
-`format_version` is not read. The current writer protocol is 10; writer
-protocols 1 through 9 are supported predecessors and inspection reports them
+`format_version` is not read. The current writer protocol is 11; writer
+protocols 1 through 10 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 10. Existing Turn state, event logs, and the original
+publishing protocol 11. Existing Turn state, event logs, and the original
 manifest `created_at` remain unchanged.
 
-Protocols 3 through 9 already have Session authority, so their upgrade is an
+Protocols 3 through 10 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
@@ -44,6 +45,10 @@ normalized to `notify_only`; they never silently acquire terminal response
 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.
+Protocol 11 additionally fences retired Session authority after a Store transfer.
+The source Session keeps a durable retirement record, and predecessor writers
+are refused before they can revive it. Store authority transfer uses a shared
+terminal lock and a resumable journal; it does not replay terminal input.
 Core
 Session/Turn data remains readable across a writer-protocol mismatch, while
 explicit reconciliation reports `skipped` and managed mutations fail before

package/docs/testing.md

@@ -216,10 +216,7 @@ IDs/generations, composer digests, draft text, or handoff-only live-native-UUID
 fences. Questionnaire response uses a fresh same-controller Status projection,
 one opaque interaction ID, semantic answer IDs or bounded text, and a durable
 one-shot reservation; changed, manual-required, secret, or uncertain state stays
-fail-closed. Codex and Claude Code `terminal_user_explicit` each prove one
-clear/inject/paste-wait/Enter sequence even when the Composer is invisible,
-truncated, unstable, or nonempty, with no post-text Composer veto. Codex uses
-`C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Native inspection and
+fail-closed. Codex `terminal_user_explicit` proves one clear/inject/paste-wait/Enter sequence even when the Composer is invisible, truncated, unstable, or nonempty, with no post-text Composer veto. Codex uses `C-u`. Claude requires a recognized empty main Composer, no existing stash, a known footer and a quiescent foreground turn. Its single `C-s` probe on that empty Composer may restore a hidden draft; restored content refuses submission and remains for the user. Visible stash refusal precedes all input, and neither sentinel insertion nor draft deletion is performed. An uncertain probe is not automatically retried. Native inspection and
 lifecycle input remain exact-empty-only; managed delivery may require exact
 empty before input, but either agent's user-explicit Enter is not post-text
 gated. Once clear or request input may have occurred, uncertainty forbids an
@@ -233,8 +230,10 @@ 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 10 fences capability-checked paginated task
-bindings, private native-question checkpoints and Watch deletion receipts from older writers. It retains
+Terminal Watch schema is 3; writer protocol 11 additionally fences retired Session
+authority after Store transfer so predecessor writers cannot revive the source
+Session. Earlier protocols fence 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/package.json

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

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

@@ -23,6 +23,14 @@ Keep the user's requested scope and approval boundaries. Do not expand a task, a
 
 Present `conversations[]` as **CLI** or **Desktop** using `surface`, and keep Codex/Claude Code as the agent type. Select the displayed `conversation_id` and its advertised operation; AKK chooses the connection internally. Do not make separate user-facing backend and terminal lists, repeat raw discovery arrays, or count Watches as additional conversations or tasks. Preserve unavailable actions, current questions/approvals, and management/recovery records. Scoped controls, when present, are operations on exact targets within a row, not extra conversations.
 
+Explain each row's `usage` in the user's language: `summary` says whether it can be used now, `available` says what for, `limitations` explains what is unavailable, and `next_steps` gives concrete actions. Do not merely show missing capability switches or internal error codes. Guidance is recomputed from current actions, activity and blockers; it neither grants authority nor overrides `available_actions`. An idle native Claude conversation without Watch is still usable when Send is offered: send the requested task and retain its automatically created Turn or Watch. A terminal-only Watch observes terminal activity, not exact native task completion.
+
+An unresolved Claude terminal receives one additional fresh reader check during List, shared across unresolved panes in that scan, without terminal input. A separate read-only check can explain that the foreground window is in the background-session interface only when its owned registry and live process incarnation verify that role. This role does not mean the window cannot receive input. When its real `terminal_user_explicit` Send is offered, explain: 可以向此窗口发送任务。AKK 会输入文字并提交，但目前无法可靠确认后台任务的接受和完成状态；请在窗口中查看执行结果。 Without that physical action, the user can continue manually or start an ordinary foreground conversation and refresh List. Reopening the same background conversation does not add native acceptance or completion proof. This diagnostic never binds a background worker, grants actions, or authorizes daemon/claim-socket access.
+
+To use that offered physical action, explicitly select its displayed `terminal_id` and call the existing `agent_knock_knock_send({terminal_id,request})`. AKK consumes the displayed private action internally; do not invent a public scope parameter or provide a private token. An ordinary managed Send must not silently switch to physical input after failure. Physical dispatch can prove text injection and Enter only as reported in its receipt; do not turn it into native acceptance, successful task completion or a promised completion callback. Check the actual window result, and never replay uncertain input through another route.
+
+If identity remains unresolved and the more specific diagnostic is missing, invalid, stale or unavailable, keep the uncertainty and actual options: use the offered physical Send for that exact terminal with its stated proof limits, or inspect the original pane, continue manually, and retry ordinary startup/List refresh as appropriate. Missing native identity alone is not an input veto. Do not infer a background conversation or reader bug from missing evidence, promise that restart repairs discovery, substitute a background or same-directory agent, or replay an uncertain Send. A positive `managed.session_count` is a count of related current/historical Sessions, not current binding authority; null Session IDs and absent `binding_status` mean no authoritative current Session was selected.
+
 Default CLI presentation prefers the verified backend entry for a one-to-one same-agent/project discovery pair without known identity conflicts. Use that returned conversation ID and its actions directly; do not search for or choose an alternative transport. Its title, state and actions belong to the selected backend. Presentation preference does not prove a terminal alias, copy terminal permissions, or redirect a previously selected terminal ID. Multiple candidates, conflicts and terminal attention/recovery records remain visible. Proven exact aliases still combine verified controls. Use `terminalDebug: true` (CLI `list --terminal-debug`) only when connection diagnostics are needed, not as a routine selection step. Unnamed, unstarted Codex candidates beside an established same-project conversation may be folded for display; `conversation_presentation.unstarted_candidates_omitted` reports their count and `diagnostic_query` expands them. This does not prove abandonment or an exact alias. If the requested new empty session is missing, use that query and its original exact ID; never substitute the established conversation. Sole or exactly associated new sessions remain visible, and a first task restores ordinary display.
 
 For new Codex sends, AKK prefers the verified shared backend and retains an eligible terminal path when that backend is unavailable. For new Claude Code sends, AKK automatically prefers a managed terminal Turn when a unique controllable tmux/Herdr counterpart proves the same native session and process; without that terminal it uses the native inbox and returns a native Watch. The controller selects the conversation, not the transport or management mode. Busy/blocked state, identity conflict, ownership conflict or a Store error cannot authorize bypass to native delivery. Targeted reads can still use the exact backend; an idle terminal may use the advertised `/status` inspection to learn its identity, while working or blocked terminals are not interrupted. List itself sends no terminal input. Keep an uncertain dispatch receipt and inspect it instead of retrying through another connection.
@@ -122,7 +130,11 @@ Core slash-command forms:
 
 The `terminal_user_explicit` physical-delivery rules below describe retained legacy routes/receipts and other explicitly advertised fallback paths. New ordinary Claude sends use managed terminal delivery; Store or ownership failure does not degrade them to unmanaged work.
 
-For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v31 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. The agent-neutral `terminal_user_explicit_composer_policy` advertises `replace_current_composer_and_submit`; the old Codex-named field is a v28 compatibility alias only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is either managed `terminal_follow_current` or user-priority `terminal_user_explicit`, exactly as advertised; the two target fields are mutually exclusive, and both may be omitted only when AKK must prove one unique send-ready pane. The following `terminal_user_explicit` rules apply to retained legacy receipts and other advertised physical fallback paths; new ordinary Claude Sends require a managed Turn and do not use Store or ownership failure to authorize unmanaged input. For those physical paths, Codex and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer—not ordinary main-Composer visibility, stability, exactness, parsed working activity, existing draft contents, or AKK Store, Turn, Session, transfer, transition, ledger, or ownership. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. Both advertise `replace_current_composer_and_submit`: Codex physical fallback sends `C-u` once; Claude Code physical fallback uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. Native inspection and native lifecycle input remain exact-empty-only. With runtime durability, an omitted target binds its `message_id` to the first selected physical terminal and existing or uncertain same-ID evidence rejects replay. If fresh durability is unavailable, user priority wins: AKK proceeds with a warning, and the degraded result must not be automatically retried. Once clear or request input may have occurred, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. The only non-ordinary Send form is an exact `send({turn_id})` copied unchanged from a current `available_actions.retry_submission`; it accepts no request text or other target and requires explicit user confirmation. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Other managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity and revalidate the relevant approval prompt; Composer revalidation remains action-specific; unreviewed Codex frontends require the styled-Composer checks above.
+For human-facing ordinary-send slash forms, a selector may be `codex`, `claude`, `only`, `latest`, or an `@short-ref` returned by `AKK list`. These selectors are only a resolution layer and fail closed when the target is missing or ambiguous. The v31 structured-tool contract never exposes a selector or opaque authority value: the model supplies semantic IDs only. Action contract v35 uses `terminal_user_explicit_composer_policy=per_agent` with `terminal_user_explicit_composer_policies`: Codex keeps `replace_current_composer_and_submit`, while Claude uses `require_empty_composer_and_submit`; the old Codex-named field is a v28 compatibility alias only. `send({session_id,request})` is strict `session_exact`; `send({terminal_id,request})` is either managed `terminal_follow_current` or user-priority `terminal_user_explicit`, exactly as advertised; the two target fields are mutually exclusive, and both may be omitted only when AKK must prove one unique send-ready pane. The following `terminal_user_explicit` rules apply to explicitly selected physical terminal actions and retained legacy receipts; ordinary Claude managed Sends never use failure as permission to switch to physical input. For those physical paths, Codex and Claude Code `terminal_user_explicit` depend on the exact live terminal/process, a scanned non-blocked approval state, and no proven input-owning questionnaire, editor, menu, history search, or read-only viewer. AKK Store, Turn, Session, transfer, transition, ledger, or ownership records do not establish that physical input is unsafe; cross-Store authority remains fenced. For Codex, ordinary main-Composer visibility, stability, exactness, parsed working activity and existing draft contents remain advisory. Claude instead requires an empty recognized main Composer, no existing stashed draft, a known native footer, and no running or unproven foreground turn; background shells alone do not block it. An unreviewed Codex frontend is the narrower exception: physical Send requires a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Profiled Codex 0.154.0/0.155.1 exact collapsed async-question summaries leaves the main Composer sendable; an expanded, clipped, or ambiguous async editor and an active-writer resume viewer remain zero-input boundaries. The per-agent policies preserve the following clearing mechanics: Codex physical fallback sends `C-u` once; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each injects the request, waits through the paste window, and dispatches Enter exactly once. After text injection, Composer observation must never veto Enter. AKK tries managed delivery where its strict empty-Composer pre-input authority exists; after either agent's user-explicit text injection, that path follows the same no-Composer-veto Enter rule. A source-less Codex terminal with zero, one, or many pre-existing rollout roots freezes that full candidate set before input and binds only the unique rollout that later persists the exact request hash; a unique stale root is never assumed to be foreground. If managed preparation still fails before input, AKK sends once without a managed callback Turn, then best-effort attaches the prepared exact request-bound or clearly labeled terminal-activity Watch and releases stale management. Watch persistence failure is a warning and never revokes or retries a successful Send; an unsafe or uncertain native probe still stops before task text. Native inspection and native lifecycle input remain exact-empty-only. With runtime durability, an omitted target binds its `message_id` to the first selected physical terminal and existing or uncertain same-ID evidence rejects replay. If fresh durability is unavailable, user priority wins: AKK proceeds with a warning, and the degraded result must not be automatically retried. Once clear or request input may have occurred, an uncertain result must not be automatically retried. Read Send results as orthogonal facts: `terminal_input_dispatched`, `agent_acceptance`, `management_mode`, `observation_mode`, and `capabilities` distinguish physical dispatch from durable native acceptance and callback/interaction authority; do not infer one from another. If the result returns `observation_mode="terminal_watch"`, wait for that callback and retain `watch-status` as the recovery path. The only non-ordinary Send form is an exact `send({turn_id})` copied unchanged from a current `available_actions.retry_submission`; it accepts no request text or other target and requires explicit user confirmation. Native-thread actions use the full `terminal_id`, never an `@short-ref`. Other managed controls use `turn_id`; terminal-scoped approval uses `terminal_id` after explicit user confirmation. The trusted plugin/CLI derives terminal, binding, candidate, prompt, composer, handoff, and compare-and-swap fences privately. Never ask the user or model to copy draft text, a composer digest, a token, fingerprint, revision, binding ID/generation, or handoff-only live native UUID from an action; `native_thread_id` is the intentional semantic UUID for resume. For every side effect, AKK must revalidate the selected agent PID and provider-owned terminal identity and revalidate the relevant approval prompt; Composer revalidation remains action-specific; unreviewed Codex frontends require the styled-Composer checks above.
+
+Claude physical-input preparation finishes before task text or Enter. A visible `› stashed` indicator refuses the attempt before any terminal input. When no stash is shown, AKK rechecks the empty main Composer and uses `C-s` once to restore any hidden stash. If content appears, it stops and leaves that content in the input box for the user; it does not re-stash or delete it. If the probe or final empty check is uncertain, it stops without task text or Enter and does not retry the key. This replaces the former sentinel transaction: no new marker is written and no editing keys delete a draft. There is no Composer observation or cleanup after task text or Enter. Ordinary managed Sends, Codex clearing and independent Watch monitoring are unchanged. This is refusal with manual recovery, not a guarantee of protecting drafts against simultaneous human input; avoid typing in the pane during an attempt. Screen capture and key delivery are not an atomic keyboard lock. A transport acknowledgement cannot prove that Claude processed `Ctrl+S`; ignored keys or cropped native indicators can leave stash occupancy unproven. AKK does not overwrite that unknown slot with a marker.
+
+If List or Send reports a stashed draft, open that exact window and wait for the foreground turn to finish. Preserve any visible draft first. With the main input box empty, press `Ctrl+S` once to restore the stash, then save, send, or clear it yourself before refreshing List. AKK cannot identify hidden content just from the stash label. If restoration reveals `[AKK replacing current draft ...]`, it may be residue from an older failed AKK cleanup: remove only that marker after checking the text, preserve any other content, and do not press Enter on the marker. `Draft restored` is a transient restore notification; an accompanying `› stashed` still reports an occupied slot and remains a refusal condition. Do not repeatedly toggle `Ctrl+S` or retry an uncertain AKK attempt automatically.
 
 The human-priority Codex path may proceed when the pane/process and complete open-rollout candidate inventory are exact even though no single foreground UUID can be selected, including a supported manual `/clear` whose new logical thread appears before its rollout materializes. The complete exact inventory domain binds the provider terminal, PID and process birth, workspace and canonical endpoint, and every open rollout's UUID, descriptor, device, inode, canonical path, and pre-submit byte offset. A `/clear` resume hint is advisory only, never routing or acceptance authority. Under the terminal lock, AKK isolates the predecessor, creates a separate zero-UUID provisional Session and Turn, sends the real task once, and binds only the single candidate rollout that durably accepts that exact request. A rollout-backed Codex row therefore advertises `terminal_follow_current` with `terminal_id`, not `session_exact`; a cached strict Session attempt rejects before task text and never downgrades itself. Only released predecessor Turn history from a strictly earlier binding epoch is excluded from current-send authority; unresolved current-epoch state still blocks. Use only the freshly listed semantic-ID action. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If delivery or acceptance is uncertain, do not retry automatically. Terminal-scoped manual Codex approval likewise exposes only `terminal_id`, requires explicit confirmation, leaves managed identity unchanged, never participates in auto-approval, and must not be retried blindly after an uncertain result.
 
@@ -138,7 +150,7 @@ AKK discovers eligible panes across workspaces. When more than one target matche
 
 Natural-language forms:
 
-- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists. A selected Claude terminal uses the managed path and refuses busy, ownership or Store blockers. On eligible physical fallback paths, a scanned blocked approval or proven input-owning questionnaire, editor, menu, or read-only viewer vetoes physical Send; parsed working activity and an existing draft do not. Unreviewed Codex frontends require the styled-Composer checks above; reviewed physical Send paths do not require ordinary main-Composer visibility. Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the request and submits exactly once. Broken or stale AKK management activity records do not veto that independently verified live terminal/process.
+- `AKK: <task>`: call `agent_knock_knock_send` with `request=<task>` and neither target ID. This succeeds only when exactly one send-ready pane exists. A selected Claude terminal uses the managed path and refuses busy, ownership or Store blockers. On eligible physical fallback paths, a scanned blocked approval or proven input-owning questionnaire, editor, menu, or read-only viewer vetoes physical Send; parsed working activity and an existing draft do not veto Codex Send. Claude requires an empty recognized main Composer, no existing stashed draft, a known native footer, and no running or unproven foreground turn; background shells alone do not block it. Unreviewed Codex frontends require the styled-Composer checks above; reviewed Codex physical Send paths do not require ordinary main-Composer visibility. Codex replaces the current Composer with `C-u`; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each injects the request and submits exactly once. Broken or stale AKK management activity records do not veto that independently verified live terminal/process.
 - `AKK Codex: <task>`: list first and identify one exact eligible Codex conversation. For a direct CLI or Desktop row, copy its advertised Send with `conversation_id`; for a terminal row use its `terminal_id`. Send `request=<task>` once through that route. Do not count duplicate representations of the same proven thread as separate tasks.
 - `AKK Claude: <task>`: list first, require one exact eligible Claude row, then call `agent_knock_knock_send` with that row's `terminal_id` and `request=<task>`.
 - Requests to list AKK or local coding-agent work: call `agent_knock_knock_list`.
@@ -152,6 +164,8 @@ Natural-language forms:
 - Requests to list resumable native threads for an exact terminal: call `agent_knock_knock_list_resumable_threads` with the terminal row's prefilled `terminal_id`.
 - Explicit requests to start a new thread or clear context: call `agent_knock_knock_new_thread({terminal_id})` only from an advertised `new_thread` action.
 - Explicit requests for low-level recovery of a listed binding conflict: after explicit user confirmation, call only the advertised `agent_knock_knock_reconcile_binding({terminal_id,conflicting_session_id})`. AKK derives its revision and binding fences privately, detaches the stale/conflicting binding without adopting the live thread, and requires a fresh list afterward. Do not use it in place of an advertised follow-current send.
+- Automatic Store authority recovery keeps the existing shared runtime location and never deletes temporary Store directories. It requires the source Store's explicit `AKK_EPHEMERAL_STORE=1` registration, a private owned non-symlink `akk-*` path inside the system temporary directory, every registered owner proven dead by exact process incarnation, settled work, and fresh matching native-session/terminal identity with idle non-blocked status. A temporary pathname, timeout or absent PID alone never grants takeover. Persistent Stores use the explicit transfer action below. When a newer writer records older legacy authority, incomplete legacy owner coverage remains recorded; later writes cannot turn it into an automatic takeover candidate. Conflicting or unfinished cross-Store authority also blocks physical fallback Send; do not use a native backend or physical token to bypass it.
+- Explicit requests to move a settled native thread's authority from another AKK Store to this Host: refresh List and use only `available_actions.transfer_store_authority`, including when it appears on a native Claude conversation row. Its tool is `agent_knock_knock_reconcile_binding({operation:"transfer_store_authority",terminal_id})`; keep the advertised physical `terminal_id` and obtain explicit user confirmation for the transfer. If `missing_required` includes `maintenance_acknowledgement`, the legacy record cannot prove the previous Host/writer has stopped: first require the user to stop every Host and old writer using the source Store and explicitly confirm that maintenance condition, then pass `maintenance_acknowledgement:true`. Never prefill or infer this from an idle terminal, a completed task, a resolved ledger, or an elapsed timeout. Visible live or unverifiable owners and unresolved work remain blocked. The transfer sends no coding-agent input and creates no Turn; refresh List afterward and use the same native conversation's newly advertised Send. Never delete ledger or Store files, invent a conflicting Session, pass private tokens/Store paths, or use binding-detach as an authority-transfer substitute.
 - Explicit requests to resume prior native context: first call `agent_knock_knock_list_resumable_threads`; then call `agent_knock_knock_resume_thread({terminal_id,native_thread_id})` for one `resumable=true` candidate using its complete UUID. For “previous” / “刚才那个”, proceed only when the fresh result advertises `previous.available_actions.resume_thread`; use that exact semantic-ID action and never substitute the newest row. Human-facing numbers and short IDs are resolved privately and are never structured tool arguments.
 - Requests to inspect current output or ask what a task is doing: call `agent_knock_knock_status`.
 - A later ordinary request: refresh `agent_knock_knock_list` and use only the selected terminal row's advertised send. Use `send({session_id,request})` for `session_exact` or `send({terminal_id,request})` for `terminal_follow_current`; never substitute a retained Session or Turn identity.
@@ -174,7 +188,7 @@ For ordinary send or an in-flight answer:
 2. If no ID is supplied and more than one eligible pane may exist, call `agent_knock_knock_list`.
 3. Treat `conversations[]` as the primary resource list; older raw CLI output may expose `terminals[]` instead. For a terminal-backed row, its managed context exposes `session_id`; `managed.current_turn` is the current AKK owner. Query `watches` for retained monitoring and managed Turn history, including unavailable-pane recovery.
 4. Read the selected resource's `available_actions`. In the compact Host projection its keys are the exact current action names and each value is `true`; `action_inputs`, when present, carries only dynamic semantic arguments, `missing_required`, and scope. For every mutation, use only an advertised action, start with those semantic inputs, supply every `missing_required` field, and follow this skill's action rules. User-selected Watch is the exception: explicit user intent plus one complete exact `terminal_id` is sufficient even when `available_actions.watch` is absent. The only additional mutation sources are a terminal row's `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`: use either only after explicit user confirmation and refresh the list immediately afterward.
-5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context and may require exact empty before input. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules describe retained legacy routes/receipts and other explicitly advertised physical fallback paths; new ordinary Claude sends retain the managed path and do not fall back to unmanaged delivery after a Store or ownership failure. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: Codex replaces the current Composer with `C-u`; Claude Code uses a sentinel-backed native `C-s` stash-clear transaction that is independent of the cursor position and does not interrupt an active turn, then proves the main Composer empty. Each injects the new request and submits exactly once without a post-text Composer veto. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. Managed delivery is attempted where eligible, but a proven zero-input failure falls back to one unmanaged delivery with no managed callback Turn. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence or composer authority. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
+5. If an existing managed Session advertises send with `session_id`, call `agent_knock_knock_send({session_id,request})`; it creates a new Turn strictly in that Session's native context and may require exact empty before input. For an ordinary selected conversation, call `agent_knock_knock_send({conversation_id,request})`; terminal-scoped rows also accept legacy `terminal_id`. The following physical-input rules apply to an explicitly selected physical terminal action and retained legacy routes/receipts; ordinary Claude managed sends never silently switch to physical input after failure. `terminal_follow_current` may adopt a safe human-driven handoff or send once within an exact, complete Codex rollout-candidate inventory before binding the uniquely accepting native thread. `terminal_user_explicit` instead preserves the user's Send when internal AKK state is broken: Codex replaces the current Composer with `C-u`; Claude Code refuses an existing stashed draft before input. On a freshly empty main Composer it uses one `C-s` to check for a hidden stash; restored content stops task submission and remains for the user. It writes no sentinel and deletes no draft. Each injects the new request and submits exactly once without a post-text Composer veto. For source-less Codex sends, zero exact acceptors remains pending for monitor recovery, one promotes the provisional Session/Turn, and multiple acceptors or identity drift becomes uncertain without replay. Within an already selected physical-input operation, eligible managed delivery may be attempted; a proven zero-input failure can then use that operation's established unmanaged fallback with no managed callback Turn. This does not authorize changing an ordinary Claude managed Send into a physical operation. AKK prepares the strongest safe Watch before dispatch and best-effort attaches it after Enter; Watch persistence failure never changes the successful Send. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Wait for an attached Watch callback or use its status as recovery. The status-card-only first-task path remains the zero-rollout special case. `send({turn_id})` is never an ordinary target: use it only for a fresh `retry_submission` action after explicit confirmation, with no other field. Never construct or pass an opaque fence or composer authority. Use `respond` with its `turn_id` only when that Turn is explicitly `waiting_for_openclaw`; the answer stays in the same Turn. Do not add timeout fields for ordinary use; `timeoutSeconds` is unsupported.
 6. If multiple terminals match, show their `short_ref`, agent, provider, and terminal target, then ask the user to choose. If a human switch has an unresolved Turn, ambiguous ownership, or unverifiable identity and no follow-current send is advertised, report that blocker and ask the user which context to resolve; never guess, supersede active work, or bypass the fence.
 
 An idle pane is at a verified ready prompt, with no current work or unresolved permission request. A previously completed managed turn alone is not proof that the pane is still idle.
@@ -197,7 +211,7 @@ Hard creation failure includes an absent exact terminal, inability to identify i
 
 Approval attention is notification-only for every Watch: never call an approval tool for a `watch_id`, send approval keys, or apply `autoApprove`. Native-interaction attention is different. An automatic exact request-bound Watch created by `terminal_user_explicit` unmanaged fallback can, after exact request acceptance and attribution, emit `interaction_required`; call Status with its exact `watch_id`, show the projected question to the user, and use `respond_interaction({watch_id,...})` only when that fresh owner-bound projection advertises `capabilities.respond=true`. A terminal-activity Watch or `interaction_manual_required` callback remains notify-only: tell the user to inspect and answer in the live TUI, and send no interaction input. Each new exact attention fingerprint is notified once while the Watch remains active. Terminal outcomes settle once. The durable outbox uses deterministic notification IDs/idempotency and leased retry, so startup and periodic supervision can safely recover callback delivery after AKK, OpenClaw, or Gateway restart.
 
-The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract 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`.
+The current integrations register the complete capability-handshake-verified semantic AKK tool catalog and list action-contract v35. Structured OpenClaw, Pi, and DeepSeek Harness Lists use compact projection v4 and point here for the static contract; the CLI keeps the complete operator/debug action contract. Every structured model action carries semantic IDs only; opaque fences, Composer digests, and draft text are derived or retained privately. Watch uses `agent_knock_knock_watch({terminal_id})`, `agent_knock_knock_status({watch_id})`, and `agent_knock_knock_unwatch({watch_id})`; its internal CLI boundary is `watch-terminal`, `watch-status`, `unwatch-terminal`, and `reconcile-watches`.
 
 For Codex permission changes, first call `agent_knock_knock_permission_options({terminal_id})` from the current row’s advertised action. This sends closed `/status` and `/permissions` inspection input but leaves permissions unchanged; the terminal must be idle, its Composer empty, and its physical and native thread identities verifiable. Use `current`, `scope`, and the returned choice descriptions to select the requested or authorized mode. Then call `agent_knock_knock_set_permissions({terminal_id,mode})` using its exact returned semantic ID in the same controller conversation. Full Access is an ordinary option and needs no additional user confirmation. AKK automatically handles its exact native confirmation inside this permission transaction; do not pause to ask the user to confirm Full Access or call generic `approve` for that dialog. Ordinary Send does not change permissions. Codex 0.160 may report `current="workspace_granular"`; this is a current-only native default, not a selectable mode. Select only an ID actually returned in `choices`. Only currently displayed built-in modes are supported: do not invent `read_only` when the picker omits it, supply a named/custom profile, or pass commands, labels, menu indexes, keys, tokens, or scope overrides. Changes affect the current session/thread, may be retained on Resume, and leave global defaults unchanged. Send the intended task only after `outcome="changed"` or `"already_effective"` with matching `effective.mode`; `"uncertain"` means stop and do not retry automatically. Refresh the catalog after any change or consumed attempt.
 
@@ -310,11 +324,11 @@ The model-facing `agent_knock_knock_list` presents `conversations[]` once. Exact
 
 ### Compact controller-Host List projection
 
-The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=4`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, explanatory `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
+The structured OpenClaw, Pi, and DeepSeek Harness tools return `projection.schema="agent-knock-knock/host-list-compact"`, `projection.version=4`, `projection.skill="agent-knock-knock"`, and the CLI action-contract version. They deliberately omit the repeated 30KB static `action_contracts`, static action `reason`/`use` text, Store paths, terminal diagnostics, native evidence, callback envelopes, full historical requests, completion text, screens, and event/file paths. Bounded per-conversation `usage` is additive display guidance for Codex CLI, Codex Desktop, Claude and terminal-only rows, derived from current evidence; it keeps projection v4. Action contract v35 adds a no-existing-stash prerequisite to Claude physical Send, narrowing eligibility from v34; `physical_send_readiness` explains draft, stash, legacy-marker, foreground-turn and footer blockers without changing public call parameters or projection v4. The extra reader recheck and foreground background-view diagnosis are Claude-only. Use Status for one selected Turn or Watch and `/akk doctor` or the CLI for operator diagnostics. A bounded dynamic failure `message` or scan `error` may still appear because it cannot be documented statically.
 
 **Conversation-only List:** List returns currently discoverable conversations, including Desktop sidebar entries with unconfirmed live owners. It never includes Watch inventories or retained managed history. Keep current ownership, blockers and advertised approvals; do not interpret missing Watch fields as missing Send monitoring. Use `agent_knock_knock_watches` or `/akk watches` to inspect observations. Legacy `listView="history"/"all"`, `all=true` and CLI `list --all` return a migration error.
 
-Every Host List page has a total row limit (`listLimit`, default 40, maximum 100), a 24 KiB UTF-8 JSON ceiling and a conservative 12,000 weighted-character budget (ASCII 1, other code points 16), including metadata. Follow `pagination.next_args` unchanged while `has_more=true`. Desktop catalog pagination is separate: finish the Host pages, then use `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Discovery pages are live snapshots; restart if membership changes invalidate the cursor. No progress body is added to List. Oversized rows retain exact IDs and a Status entry point; omitted actions do not mean unsupported capabilities. Refresh exact Status before acting.
+Every Host List page has a total row limit (`listLimit`, default 40, maximum 100), a 24 KiB UTF-8 JSON ceiling and a conservative 12,000 weighted-character budget (ASCII 1, other code points 16), including metadata. Follow `pagination.next_args` unchanged while `has_more=true`. Desktop catalog pagination is separate: finish the Host pages, then use `desktop_scan.next_cursor` with the same Desktop filters and a fresh Host cursor. Discovery pages are live snapshots; restart if membership changes invalidate the cursor. No progress body is added to List. Oversized rows retain exact IDs and a Status entry point; their guidance says details were omitted and directs the user to Status, rather than describing those operations as unsupported. Refresh exact Status before acting.
 
 **Watch inventory:** `agent_knock_knock_watches` / `/akk watches` / CLI `watches` is a read-only Store query, defaulting to the most recent 24 hours, 40 rows per page (maximum 100), with a whole-response budget. `hours` accepts 1–48. Active or unresolved observations older than the window remain visible as `outside_window`; terminal managed Turns are a distinct section. Follow the returned pagination arguments. The query does not create/renew monitoring, reconcile or resend notifications. Use exact Status for actionable questions, approvals, callback recovery or full results. Native completion, controller acceptance and chat delivery are separate; `callback_expected=false` alone is neither failure nor delivery proof.
 
@@ -333,6 +347,7 @@ Action-name glossary:
 - `permission_options` and `set_permissions`: inspect one idle Codex pane’s built-in permission modes, then consume one catalog for the requested or authorized change, including Full Access without an extra confirmation. Ordinary Send never increases permissions.
 - `identify_foreground` / `identify_and_send`: diagnose Codex foreground identity, or keep that diagnosis and one Send atomic.
 - `reconcile_binding`: detach only the exact listed stale/conflicting AKK binding after explicit user confirmation.
+- `transfer_store_authority`: explicitly transfer settled native-thread authority to this Host's Store through the `reconcile_binding` tool's `operation:"transfer_store_authority"` form; legacy maintenance acknowledgement must come from the user after source-Store Hosts and old writers have stopped.
 - `respond`: answer ordinary text inside the current managed Turn.
 - `respond_interaction`: answer one current native interaction step obtained from fresh Status; an `async_question` defaults to advertised `steer_current_turn` or accepts explicit advertised `queue_next_turn` as `delivery_mode`, while a blocking `questionnaire` omits it.
 - `approve`: apply only an explicitly confirmed advertised semantic approval decision.
@@ -342,11 +357,11 @@ Action-name glossary:
 - `close`: release AKK management for the selected Send Turn without stopping the coding agent or closing its conversation.
 - `recover`: reconcile an exact backend task and its receipt without resending work or changing its anchor.
 
-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.
+The tool name is normally `agent_knock_knock_<action-name>`. List aliases are `retry_submission`, which invokes `agent_knock_knock_send` with its listed `turn_id` only after explicit confirmation, and `transfer_store_authority`, which invokes `agent_knock_knock_reconcile_binding` with the explicit transfer operation. 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 10; 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})` or its separately advertised `{operation:"transfer_store_authority",terminal_id,maintenance_acknowledgement?:true}` form. A top-level `previous` block, when present, is the only authority for a “previous/刚才那个” request; human-facing numbers and short IDs remain slash-navigation aids and are never structured tool arguments. The model never carries terminal, binding, catalog, candidate, composer, handoff, approval, interaction-fingerprint, revision, binding ID/generation, or handoff-only live-native-UUID fences; it never receives draft text or composer digests. `native_thread_id` remains the semantic resume identity. AKK derives those private fences and revalidates them before side effects. Orphan-close `expected_message_id` and `expected_transition_id` remain because they are entity IDs. Store format remains 1 and writer protocol is 11; Terminal Watch schema remains 3. Protocol 11 fences retired Session authority so predecessor writers cannot revive a source Session after Store authority transfer.
 
-Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Native inspection and lifecycle input require an exactly empty Composer; managed Send may require exact empty before input. Codex and Claude Code `terminal_user_explicit` instead require a scanned non-blocked approval state and no proven input-owning questionnaire, editor, menu, or read-only viewer. Reviewed physical Send paths do not require ordinary main-Composer visibility, stability, or exactness. Unreviewed Codex frontends require a recognized styled Composer before clearing and a fresh empty styled Composer before task text. Existing drafts and parsed working activity do not themselves veto the user-priority path, and after text injection no Composer observation may veto Enter. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Humans can attach to the same tmux or Herdr session and continue directly at any time.
+Before every terminal operation, AKK revalidates the expected agent PID and provider-owned terminal identity. Native inspection and lifecycle input require an exactly empty Composer; managed Send may require exact empty before input. Codex and Claude Code `terminal_user_explicit` instead require a scanned non-blocked approval state and no proven input-owning questionnaire, editor, menu, or read-only viewer. Reviewed Codex physical Send paths do not require ordinary main-Composer visibility, stability, or exactness. Claude physical Send requires an empty recognized main Composer, a known native footer, and no running or unproven foreground turn; background shells alone do not block it. Unreviewed Codex frontends require a recognized styled Composer before clearing and a fresh empty styled Composer before task text. For Codex, existing drafts and parsed working activity do not themselves veto the user-priority path, and after text injection no Composer observation may veto Enter. Once clear or request input may have occurred, an uncertain result must not be retried automatically. Humans can attach to the same tmux or Herdr session and continue directly at any time.
 
 Exact-task Claude Code completion depends on a strictly correlated local transcript turn and fails closed for unknown schemas, background work, or ambiguous identity. A `terminal_activity` Watch may separately notify that the selected terminal became stably idle only after observed activity; always label that callback best-effort and never report it as exact task completion or success.