@scotthuang/agent-knock-knock 0.12.6 → 0.12.8

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.12.8 - 2026-08-13
+
+### Fixed
+
+- Route every eligible quiescent rollout-backed Codex pane through terminal-follow-current candidate attribution, including single-root and multi-root inventories with resolved or unavailable foreground identity, then bind only the unique post-submit acceptor.
+- Keep the Codex `/clear` resume hint advisory, so a valid fresh candidate action remains usable after the hint scrolls out of view while exact terminal, process, Store, inventory, and composer authority remains unchanged.
+- Restore idempotent retry after a conclusively zero-input candidate-send abort without reusing the abandoned provisional Session or allowing binding drift.
+
+### Changed
+
+- Publish action contract 15. Rollout-backed Codex rows advertise `terminal_follow_current` instead of `session_exact`, and cached direct `session_id` sends reject before task input.
+- Store writer protocol remains 5.
+
+### Security
+
+- Require a complete nonempty open-root inventory, exclusive candidate ownership, exact process and terminal incarnation, frozen source history and dispatch ledger, an idle empty composer, and no blocking Turn before candidate input; stale, incomplete, claimed, or ambiguous state remains fail-closed.
+
+## 0.12.7 - 2026-08-12
+
+### Fixed
+
+- Follow a supported manual Codex `/clear` through a fresh terminal-scoped candidate send, binding only the rollout with one unique post-anchor acceptance without an internal `/status` probe.
+- Restore future-send liveness after explicitly closing an uncertain predecessor when its resolved close ledger, append-only uncertain receipt, frozen Turn history, absent old rollout, and unclaimed current inventory remain exact.
+- Recognize the supported Codex resume hint when its UUID wraps across lines in a narrow pane, while keeping the hint as routing evidence rather than native-identity authority.
+- Ignore closed detached Codex companions when one exact current rollout is open, and release completed Claude Turns for a fresh message ID while retaining immutable acceptance receipts.
+
+### Changed
+
+- Publish action contract 14. Store writer protocol remains 5.
+
+### Security
+
+- Revalidate candidate inventory, terminal and process identity, abandonment proof, and source/target lineage before input, commit, and crash recovery; ambiguous, drifted, or uncertain native acceptance remains non-retryable.
+
 ## 0.12.6 - 2026-08-12
 
 ### Added

package/README.md

@@ -83,13 +83,13 @@ terminal resource / process incarnation
       └─ Turn 3 (turn_id)
 ```
 
-Once an AKK session exists, an ordinary `send(session_id, request)` is **session-scoped**: it creates a new `turn_id` in that exact native coding-agent context and never silently follows a different thread now visible in the pane. A listed terminal may instead advertise a **terminal-scoped follow-current** send with its exact full `selector` and a fresh `expected_terminal_token`. Using that prefilled action says “send this ordinary task to the current verified pane, even when AKK cannot yet name its foreground native thread.” The token fences the terminal, process, workspace, composer, dispatch owner, and—when present—the complete set of exact Codex rollout candidates. AKK sends the task once, then binds only the single rollout that durably accepts that exact request. Legacy selector-based first attach remains supported. Never infer a selector or token, copy one from another row, reuse one after another terminal action, or pass a selector as `session_id`. The `turn_id` is not a destination for later ordinary sends; it is the exact identity used for status, approval, cancellation, renewal, callback retry, close, and callback correlation. If a Turn is `waiting_for_openclaw`, `respond(turn_id, answer)` supplies the answer inside that same Turn instead of creating another one.
+When a listed action supplies `send(session_id, request)`, that ordinary send is **session-scoped**: the v15 contract calls this `session_exact`. It creates a new `turn_id` in that exact native coding-agent context and never silently follows a different thread now visible in the pane. A listed terminal may instead advertise `terminal_follow_current`, a **terminal-scoped follow-current** send with its exact full `selector` and a fresh `expected_terminal_token`. Using that prefilled action says “send this ordinary task to the current verified pane, even when AKK cannot yet name its foreground native thread.” The token fences the terminal, process, workspace, composer, dispatch owner, and—when present—the complete set of exact Codex rollout candidates. AKK sends the task once, then binds only the single rollout that durably accepts that exact request. Legacy selector-based first attach remains supported. Never infer a selector or token, copy one from another row, reuse one after another terminal action, or pass a selector as `session_id`. The `turn_id` is not a destination for later ordinary sends; it is the exact identity used for status, approval, cancellation, renewal, callback retry, close, and callback correlation. If a Turn is `waiting_for_openclaw`, `respond(turn_id, answer)` supplies the answer inside that same Turn instead of creating another one.
 
-v12 generalizes the human-priority Codex path. It covers both a status-card-only Session with no rollout and a quiescent managed pane whose exact open-rollout inventory is complete but cannot identify the foreground candidate. Under the terminal lock, AKK isolates the old Session, creates a separate zero-UUID provisional Session and Turn, sends only the real task, and promotes that target only after the post-submit monitor finds a unique exact request acceptance in the pinned rollout domain. The resulting native UUID may match or differ from the old Session; it is never silently merged back into the predecessor. A narrow pane does not force `/status` for this ordinary terminal-scoped send. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If terminal delivery or native acceptance is uncertain, AKK does not retry the input.
+v15 generalizes the human-priority Codex path. It covers a status-card-only Session with no rollout, a quiescent managed pane whose exact open-rollout inventory is complete but cannot identify the foreground candidate, and a supported manual `/clear` whose new logical thread is visible 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. Native foreground resolution may be unavailable only when that independent domain is complete and exact; an incomplete, missing, stale, or changed domain fails closed. A `/clear` resume hint is only an advisory routing and diagnostic signal. It is not token, UUID, foreground, rollout, or acceptance authority, and its disappearance does not invalidate an otherwise fresh candidate action. Under the terminal lock, AKK isolates the old Session, creates a separate zero-UUID provisional Session and Turn, sends only the real task, and promotes that target only after the post-submit monitor finds a unique exact request acceptance in the pinned rollout domain. The resulting native UUID may match or differ from the old Session; it is never silently merged back into the predecessor. A rollout-backed Codex row therefore advertises `terminal_follow_current`, not `session_exact`; a cached or direct `session_exact` attempt revalidates under the terminal lock, rejects before task text, and never downgrades itself to the follow-current path. The freshly listed selector/token action can work in a narrow pane without `/status`. Until promotion commits, strict `session_id` send, `respond`, managed `approve`, `cancel`, native lifecycle, callback delivery, and `native_inspect` remain unavailable. If terminal delivery or native acceptance is uncertain, AKK does not retry the input. Explicitly closing such an uncertain Turn abandons its missing result and callback; when the exact resolved close ledger, append-only uncertain receipt, frozen predecessor history, absent old rollout, and unclaimed current candidate inventory remain authoritative, the conflict row may restore only a future snapshot-bound candidate send.
 
-v12 also separates human-confirmed Codex approval from managed attribution. When `list` can prove one exact visible Codex approval prompt, it may advertise a terminal-scoped `approve` even when the foreground rollout UUID is temporarily unavailable. The authority may be either one exact current AKK dispatch owner or one exact bound managed Session whose dispatch owner is already released; the latter covers a task that the human entered directly in the pane. After the user reviews the current `status` fingerprint and explicitly confirms, AKK revalidates the Store/terminal/process snapshot, token, and approval fingerprint immediately before sending the exact key once. This action does not attribute the approval to a Turn, mutate Session identity, or create a durable approval receipt, so an uncertain transport result must not be retried blindly. It is never available to auto-approve. Known native-thread changes, unresolved dispatches, transitions, stale tokens, or changed prompts remain blocked.
+v15 also preserves the separation between human-confirmed Codex approval and managed attribution. When `list` can prove one exact visible Codex approval prompt, it may advertise a terminal-scoped `approve` even when the foreground rollout UUID is temporarily unavailable. The authority may be either one exact current AKK dispatch owner or one exact bound managed Session whose dispatch owner is already released; the latter covers a task that the human entered directly in the pane. After the user reviews the current `status` fingerprint and explicitly confirms, AKK revalidates the Store/terminal/process snapshot, token, and approval fingerprint immediately before sending the exact key once. This action does not attribute the approval to a Turn, mutate Session identity, or create a durable approval receipt, so an uncertain transport result must not be retried blindly. It is never available to auto-approve. Known native-thread changes, unresolved dispatches, transitions, stale tokens, or changed prompts remain blocked.
 
-Human-friendly selectors such as `only`, `codex`, `claude`, a terminal ID, or `@short-ref` remain a discovery layer. A natural-language tool call may preserve one only when the user explicitly named it; otherwise use the exact selector returned by `AKK list`, or omit it and require a unique eligible pane. Normally a managed row pre-fills its authoritative `session_id` for strict continuation. A human-priority row instead pre-fills the exact terminal selector and `expected_terminal_token` for follow-current continuation. Merely observing a mismatch or an unbound rollout inventory never mutates the Store. AKK advertises the fenced send only when it can prove a single source claim, an exact live terminal/process incarnation, an idle empty composer, a stable complete rollout inventory, and no unresolved Turn, transition, dispatch, or approval. A foreground ambiguity inside that complete inventory may be resolved after the real request is accepted; incomplete, stale, or unverifiable evidence remains blocked. The same terminal row may advertise status, manual approval, cancellation, or orphan-close with its own prefilled `conversation_id` compatibility selector and, where required, a fresh token. Never infer, guess, or reuse compatibility selectors or tokens.
+Human-friendly selectors such as `only`, `codex`, `claude`, a terminal ID, or `@short-ref` remain a discovery layer. A natural-language tool call may preserve one only when the user explicitly named it; otherwise use the exact selector returned by `AKK list`, or omit it and require a unique eligible pane. When strict continuation is safe, a managed row pre-fills its authoritative `session_id`; a rollout-backed Codex row instead uses the exact terminal selector and `expected_terminal_token` for follow-current continuation. Merely observing a mismatch or an unbound rollout inventory never mutates the Store. AKK advertises the fenced send only when it can prove a single source claim, an exact live terminal/process incarnation, an idle empty composer, a stable complete rollout inventory, and no unresolved Turn, transition, dispatch, or approval. A foreground ambiguity inside that complete inventory may be resolved after the real request is accepted; incomplete, stale, or unverifiable evidence remains blocked. The same terminal row may advertise status, manual approval, cancellation, or orphan-close with its own prefilled `conversation_id` compatibility selector and, where required, a fresh token. Never infer, guess, or reuse compatibility selectors or tokens.
 
 An exact human switch while the old Session still has one active Turn is a decision point, not an automatic redirect. In that case the terminal row may expose `handoff_decision` instead of a follow-current send. Its nested `choices.take_over_current.action` is the only authoritative supersede action: after explicit user confirmation, invoke its complete `agent_knock_knock_close` arguments unchanged (`turn_id`, `reason="superseded_by_human_context_switch"`, and `expected_handoff_token`). The snapshot-bound close records the old Turn's disposition and sends no terminal input. Then list again and use only the newly advertised follow-current send; never chain the old token into a send. Choosing `keep_source` changes no AKK state: restore the old native thread in the Codex or Claude TUI, then refresh the list. A completed/changed Turn or another human thread switch makes the decision token stale and requires a fresh decision.
 
@@ -242,13 +242,13 @@ To ask AKK itself to change native context, first copy the full `terminal_id` fr
 
 To request a native Codex status card or Claude Status panel, first run `agent_knock_knock_list` and use only that terminal row's advertised `native_inspect` action. The structured tool schema is closed to `inspection="status"`; callers cannot provide `/status` or another slash command as text. AKK serializes the inspection with terminal mutations, revalidates the fresh token and exact terminal identity, and returns only after it proves one fresh bounded status result and an idle postcondition. Codex status probes additionally require an exact viewport of at least 80 columns to preserve the full Session UUID, cross the versioned paste-settle boundary, and dispatch Enter exactly once. An initially narrow or unknown viewport fails before text input with a widen/zoom diagnostic; post-injection viewport or composer drift fails closed before Enter and leaves the draft for manual inspection. Codex `/status` and that viewport requirement apply only to operations that must prove the UUID before terminal input. An otherwise eligible terminal-scoped ordinary task can send once and bind from exact native acceptance afterward, so it does not run `/status` or fail merely because the pane is narrow. For Claude, the inspection safely dismisses the exact modal once. It never turns ordinary `send` or `respond` into a slash-command escape hatch.
 
-The top-level v12 `action_contracts` documents this closed inspection alongside human-priority current-pane send/approval, lifecycle, and Turn actions. `available_actions` remains the authority for ordinary current actions. Two deliberate nested exceptions require explicit user confirmation: an active human-handoff conflict may expose the snapshot-bound `handoff_decision.choices.take_over_current.action`, while a collateral terminal-wide unresolved Turn may appear in `blocking_turns[]` with its exact Store-only `recovery_action`. An active handoff source Turn is never generically closable through `blocking_turns`; it remains governed only by the snapshot-bound handoff decision. Copy only the complete listed action, then refresh the list before doing anything else.
+The top-level v15 `action_contracts` documents this closed inspection alongside human-priority current-pane send/approval, lifecycle, and Turn actions. `available_actions` remains the authority for ordinary current actions. Two deliberate nested exceptions require explicit user confirmation: an active human-handoff conflict may expose the snapshot-bound `handoff_decision.choices.take_over_current.action`, while a collateral terminal-wide unresolved Turn may appear in `blocking_turns[]` with its exact Store-only `recovery_action`. An active handoff source Turn is never generically closable through `blocking_turns`; it remains governed only by the snapshot-bound handoff decision. Copy only the complete listed action, then refresh the list before doing anything else.
 
 For natural-language tool use, `agent_knock_knock_list` is terminal-first. Each live pane appears exactly once in `terminals[]`; `process_state` reports whether its coding-agent process is alive and `activity_state` reports the parsed screen state. `managed.session_id` identifies the continuing AKK session, `managed.current_turn` is its optional active Turn, and `managed.recent_turn` is retained history; retained Turns do not occupy the terminal. A human-driven native-thread mismatch remains honestly classified as `management_state="conflict"`; its `handoff_state` is `external_handoff_adoptable` only when the row advertises the fenced follow-current `send`, otherwise it is `external_handoff_blocked`. Listing never performs the adoption. Pass `all=true` to include older entries in `managed.history`. By default, `unavailable_managed_turns[]` contains attention-needed records whose pane cannot be presented as a live terminal; `all=true` also includes retained unavailable history.
 
-Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. The only additional action sources are a terminal row's nested `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`; both require explicit user confirmation and must be copied whole. A managed Session's strict `send` uses its prefilled `session_id` and creates a new Turn only in that Session's native context. A terminal-scoped follow-current `send` instead carries the selected row's exact full `selector` and `expected_terminal_token`; preserve both and add only `request`. This is the human-priority path when the pane is exact but its foreground Codex UUID is not yet attributable. Legacy first attach may still use a discovery selector explicitly named by the user or the unmanaged raw-terminal row's prefilled `selector`; do not infer or reuse one. `respond` is available only while a Turn is `waiting_for_openclaw`; it uses `turn_id` and keeps the answer inside that Turn. Managed status, approval, cancellation, renewal, callback retry, and close also use the exact `turn_id`. Native inspection instead uses the exact terminal row's `terminal_id`, closed `inspection`, and snapshot-bound `expected_binding_token`; do not substitute AKK status or ordinary send. A terminal-scoped manual Codex approval may use the exact listed `conversation_id` plus `expected_terminal_token` and the latest status fingerprint; it never authorizes auto-approve or changes managed identity. Other raw controls may be used only through the exact action their row advertises. `timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
+Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. The only additional action sources are a terminal row's nested `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`; both require explicit user confirmation and must be copied whole. When advertised, a managed Session's strict `send` uses its prefilled `session_id` and creates a new Turn only in that Session's native context. A terminal-scoped follow-current `send` instead carries the selected row's exact full `selector` and `expected_terminal_token`; preserve both and add only `request`. This is the human-priority path when the pane is exact but its foreground Codex UUID is not yet attributable. Legacy first attach may still use a discovery selector explicitly named by the user or the unmanaged raw-terminal row's prefilled `selector`; do not infer or reuse one. `respond` is available only while a Turn is `waiting_for_openclaw`; it uses `turn_id` and keeps the answer inside that Turn. Managed status, approval, cancellation, renewal, callback retry, and close also use the exact `turn_id`. Native inspection instead uses the exact terminal row's `terminal_id`, closed `inspection`, and snapshot-bound `expected_binding_token`; do not substitute AKK status or ordinary send. A terminal-scoped manual Codex approval may use the exact listed `conversation_id` plus `expected_terminal_token` and the latest status fingerprint; it never authorizes auto-approve or changes managed identity. Other raw controls may be used only through the exact action their row advertises. `timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
 
-The top-level v12 action contracts include `send`, manual `approve`, `native_inspect`, `list_resumable_threads`, `new_thread`, `resume_thread`, and the conflict-only `reconcile_binding` recovery action. `send` has two deliberately different managed scopes: `session_id` is strict context, while the exact terminal `selector` plus `expected_terminal_token` is follow-current current-pane context. Manual Codex approval likewise has a strict managed-Turn form and a separately advertised terminal-scoped form; only the latter carries the terminal token, and neither permits the model to enable automatic approval. A supported idle Codex or Claude Code terminal may advertise `native_inspect` with its exact terminal ID, the closed `status` inspection kind, and a fresh binding token. The terminal row also advertises `list_resumable_threads` and, when currently safe, `new_thread`. Thread listing is read-only with respect to Session/Turn state, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` row retains its complete UUID and exact prefilled `resume_thread` action. If `previous` is present, use only its exact prefilled action for a natural-language “刚才那个” request. Numbers, short IDs, and handles are human display/navigation aids, never tool arguments or authoritative native identity. The `new_thread` and `resume_thread` mutations require the fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. `reconcile_binding` remains a low-level compatibility/recovery action for a safely detachable conflict when no ordinary follow-current send is appropriate; it never adopts the replacement thread, sends terminal input, or creates a Turn. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. Native inspection and lifecycle results contain no `turn_id` because no work was sent.
+The top-level v15 action contracts include `send`, manual `approve`, `native_inspect`, `list_resumable_threads`, `new_thread`, `resume_thread`, and the conflict-only `reconcile_binding` recovery action. `send` has two deliberately different managed scopes: `session_exact` uses `session_id` for strict context, while `terminal_follow_current` uses the exact terminal `selector` plus `expected_terminal_token` for follow-current current-pane context. Manual Codex approval likewise has a strict managed-Turn form and a separately advertised terminal-scoped form; only the latter carries the terminal token, and neither permits the model to enable automatic approval. A supported idle Codex or Claude Code terminal may advertise `native_inspect` with its exact terminal ID, the closed `status` inspection kind, and a fresh binding token. The terminal row also advertises `list_resumable_threads` and, when currently safe, `new_thread`. Thread listing is read-only with respect to Session/Turn state, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` row retains its complete UUID and exact prefilled `resume_thread` action. If `previous` is present, use only its exact prefilled action for a natural-language “刚才那个” request. Numbers, short IDs, and handles are human display/navigation aids, never tool arguments or authoritative native identity. The `new_thread` and `resume_thread` mutations require the fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. `reconcile_binding` remains a low-level compatibility/recovery action for a safely detachable conflict when no ordinary follow-current send is appropriate; it never adopts the replacement thread, sends terminal input, or creates a Turn. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. Native inspection and lifecycle results contain no `turn_id` because no work was sent.
 
 Workspace is not a routing boundary. AKK can list, inspect, and control verified panes across projects; when more than one target matches, use a selector to choose one explicitly.