@scotthuang/agent-knock-knock 0.13.18 → 0.14.1

package/docs/operator-guide.md

@@ -0,0 +1,572 @@
+# AKK Operator Guide
+
+This guide covers daily use of existing Codex CLI backend conversations,
+Codex Desktop conversations, and Codex or Claude Code terminals. OpenClaw,
+Pi, DeepSeek Harness, or another compatible Host can act as the controller.
+AKK 0.14.0 introduces the backend and Desktop features described here; see the
+[README](../README.md) for installation. Each connector's pinned runtime
+determines its supported capabilities.
+
+Choose the guide for the coding agent you already use:
+
+| Existing coding-agent environment | Setup and capability guide |
+| --- | --- |
+| Codex CLI connected to its shared backend | [CLI backend guide](codex-cli-native-compatibility.md); no tmux or Herdr required |
+| Codex Desktop | [Desktop guide](codex-desktop-compatibility.md); keep the intended conversation open in the supported app |
+| Codex or Claude Code in a shared terminal | [tmux quick start](quickstart-tmux.md) or [Herdr quick start](quickstart-herdr.md) |
+
+For controller-specific setup, see [OpenClaw operations](openclaw-operations.md),
+the [Pi guide](../connectors/pi/README.md), or the
+[DeepSeek Harness guide](../connectors/deepseek-harness/README.md).
+AKK never launches a hidden replacement coding agent. Human and controller
+continue in the original conversation or shared terminal.
+
+Start with AKK List, choose the intended conversation by title and project,
+then use its advertised Send, Status, Watch, or interaction action. Backend
+tools use the returned `conversation_id`; the controller supplies its own
+session identity. Save the task's returned `watch_id` and, for a managed Send,
+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.
+
+## Command reference
+
+Direct slash commands are available in every first-party Host integration:
+
+| Command | Purpose |
+| --- | --- |
+| `/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 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. |
+| `/akk models <terminal-id>` | Inspect the current native model and reasoning choices for one exact idle terminal. |
+| `/akk permissions <terminal-id>` | Inspect the exact Codex terminal's native permission choices. |
+| `/akk set-permissions <terminal-id> <advertised-mode-id>` | Apply the selected native permission mode before a task. |
+| `/akk repair-model-control <terminal-id>` | Clear only an exact advertised stale profiled Codex 0.154.0/0.155.1 `/model` Composer surface or open native picker and prove an empty Composer. |
+| `/akk set-model <terminal-id> <model> <reasoning-effort>` | Select one exact tuple from the immediately preceding model catalog. |
+| `/akk new-thread <terminal-id>` | Start a clean native coding-agent thread. |
+| `/akk clear-thread <terminal-id>` | Alias for the same clean-thread lifecycle action. |
+| `/akk resume-thread <terminal-id> [thread]` | Resume one exact native thread. |
+| `/akk status <turn-or-watch>` | Inspect the original managed terminal Turn or backend/terminal Watch. |
+| `/akk respond <turn-id> <answer>` | Answer a question inside the same managed Turn. |
+| `/akk cancel <turn-id>` | Interrupt one exact active managed Turn. |
+
+AKK List presents one `conversations[]` collection. It merges terminal/backend
+rows only when their exact current native identities match. A matching project
+or title does not establish that link. Select a conversation and action; AKK
+chooses the supported transport. Bound task and interaction IDs retain their
+original provider, and an uncertain mutation is never retried through another
+transport. The [CLI backend guide](codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10)
+describes backend preference and terminal fallback in detail.
+
+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[]`.
+
+Terminal status has three independent evidence axes. `screen_state` describes
+the bounded live TUI (`idle`, `working`, `awaiting_approval`, or `unknown`);
+`native_identity_state` describes foreground native-session resolution
+(`resolved`, `ambiguous`, `verified_absent`, or `unavailable`); and
+`durable_activity_state` describes exact rollout/transcript task evidence
+(`idle`, `working`, or `unknown`). The legacy `activity_state` remains a
+conservative compatibility projection and can therefore be `unknown` while
+`screen_state` is `idle`. These fields are diagnostic; `available_actions`
+remains the authority for tool calls.
+
+Human-facing terminal selectors are a slash-command convenience. Terminal
+structured tools use semantic identities: `session_id` for strict continuation, `terminal_id` for
+the currently verified physical terminal, `turn_id` for one managed dispatch,
+`watch_id` for read-only observation, and `native_thread_id` for resume. A
+`session_exact` action targets the continuing native context; a
+`terminal_follow_current` action targets the current verified context in the
+pane. Except for user-intent-first Watch, always use the exact action and
+prefilled semantic IDs from a fresh list.
+
+## Reliable Send
+
+Backend Send persists one submission and monitors its original accepted native
+task. Reusing its message ID returns the same record; uncertain submission
+evidence never triggers an automatic resend. See the [CLI backend guide](codex-cli-native-compatibility.md)
+and [Desktop guide](codex-desktop-compatibility.md) for native acceptance and
+interaction capabilities. The remainder of this section covers terminal Send,
+including its physical-input fallback and terminal response adapters.
+
+Starting in AKK 0.14.1, new Send monitoring and explicit or
+automatic Watch share a default **720-minute hard deadline**. Explicit request
+parameters override the Host hard-timeout configuration, which overrides that
+default. Save and use the Watch returned by Send; do not add another Watch merely
+to obtain completion callbacks. Expiry ends observation, not the native task.
+Existing saved deadlines and repeated message IDs are not extended by an upgrade.
+Managed terminal inactivity remains a separate 60-minute default.
+
+The v30 `action_contracts` expose model-facing semantic IDs only. The trusted
+adapter privately derives and revalidates terminal, process, binding, native
+thread, composer, approval, handoff, revision, and compare-and-swap evidence.
+Callers never supply those opaque fences.
+
+A managed Send verifies one terminal and native context, creates one Turn,
+proves exact request acceptance, monitors that Turn, and returns completion or
+attention callbacks to the initiating Host. A completed `turn_id` is history,
+not a destination for another task. A question inside a live Turn uses the
+advertised `respond` action with that Turn's `turn_id`.
+
+Native interaction prompts use `respond_interaction`, not ordinary `respond`.
+For a supported pending step, the managed monitor sends an
+`interaction_required` callback to wake the owning controller conversation.
+That callback is notification only and carries no private response authority:
+first obtain the current managed Turn's `interaction_state` from Status in the
+same controller conversation, show that exact step to the user, and submit only
+its advertised semantic question/option IDs or bounded typed text. A blocking
+`questionnaire` does not carry `delivery_mode`. A Codex `async_question`
+coexists with a task that remains `working`; responses default to advertised
+`steer_current_turn` or explicitly select advertised `queue_next_turn`: `steer_current_turn` delivers the answer to that running turn,
+while `queue_next_turn` queues it for the next turn. One call resolves one
+current step; the monitor notifies the next supported step when it appears.
+Status remains the manual refresh fallback. Never submit raw keys, shortcut
+chords, or menu indexes, and never respond to `manual_required`, expired,
+changed, secret-bearing, or uncertain state. Codex 0.154.0 and 0.155.1 use
+version-bound TUI execution; main-only notification and stable-question-ID
+wrappers added after 0.155.1 are not assumed to exist in either release.
+
+The initial async adapter accepts at most four fully visible suggestions plus
+native Other, and custom answers must be a short, fully visible single line
+without leading/trailing whitespace. Wrapped or clipped input cannot prove the
+postcondition and stops without a submit key. Codex's own collapsed-question
+timer still applies: AKK does not keep a question alive or reopen an expired
+one. Refresh Status before responding; an absent question is not retryable.
+
+The user-priority `terminal_user_explicit` path requires one exact live
+physical terminal/process, a scanned non-blocked approval state, and no proven
+input-owning questionnaire, editor, menu, or read-only viewer. Broken AKK Turn,
+Session, transfer, transition, ledger, or Store state cannot veto the user's
+explicit Send. Neither can parsed working activity, an existing draft, or
+ordinary Composer visibility, stability, or exactness. 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
+then injects the new request,
+waits through the paste window, and dispatches Enter exactly once. After text
+injection, Composer observation cannot veto Enter. Unreviewed Codex fullscreen
+frontends additionally require a recognizable styled Composer before clearing
+and a fresh empty Composer afterward, before any task text is sent.
+
+AKK first takes the managed path where its stronger pre-input requirements
+hold. Otherwise it may deliver unmanaged work once and best-effort attaches a
+Terminal Watch that provides the completion callback. Exact preparation failure falls back to a request-correlated terminal-activity
+Watch when the physical identity and observation path remain valid. Its callback
+reports stable idle with best-effort confidence, never exact task success.
+Watch persistence failure never vetoes, revokes, or retries a successful
+Send. Uncertain native probe input or unsafe input surfaces stop before task
+text; they do not authorize this fallback. If clear or request input may have occurred and terminal
+delivery or native acceptance is uncertain, AKK does not retry automatically;
+inspect Status, the exact pane, or the returned Watch instead.
+
+On first attach, the target terminal must be explicitly named by the user. AKK
+never guesses which already-running pane should receive the task. An omitted
+target is allowed only when AKK can prove one unique eligible terminal.
+
+### Codex candidate attribution
+
+The human-priority Codex path also covers a status-card-only Session, a
+quiescent managed pane whose foreground rollout cannot be selected, and 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 request once, and binds
+only the single rollout that proves exact request acceptance. A rollout-backed
+Codex row therefore advertises `terminal_follow_current`, not `session_exact`;
+a cached or direct `session_exact` attempt rejects before task text and never
+downgrades itself. Only released predecessor Turn history from an earlier
+binding epoch is excluded from current authority. 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. This provisional path can still work in a narrow pane
+because it binds from acceptance rather than automating native `/status`.
+
+### Explicit Codex foreground identification
+
+When a recent `/clear` has not yet materialized a rollout, or several open
+rollouts make `native_identity_state="ambiguous"`, a fresh List may advertise
+two Codex-only actions. `identify_foreground({terminal_id})` holds the exact
+terminal lock and sends the closed `/status` probe exactly once, but performs
+no Store mutation and creates no Session, Turn, receipt, monitor, or callback.
+The returned proof expires after 30 seconds and is diagnostic only: it cannot
+authorize Send, approval, native-interaction response, lifecycle input, or a later
+binding after the lock is released.
+
+`identify_and_send({terminal_id,request})` is the actionable atomic form. It
+keeps one terminal lock from foreground identification through the one task
+dispatch. The status UUID is provisional; only one rollout that later accepts
+the exact request can become durable Session/Turn identity. A changed or
+uncertain probe boundary stops before the task and is not retried
+automatically. This optional enhancement is not a prerequisite for ordinary
+human Send: ordinary Send retains its user-priority behavior. Codex 0.158.0/0.159.0/0.159.2
+exact Send and active-task Watch use a separate closed `/status` transaction
+to bind the foreground paginated thread. List never types an identity probe.
+Status for an exact backend task does not use terminal input. A targeted
+conversation Status for an unbound, idle Codex terminal may use the separate
+closed routing inspection described under [Status](#akk-status-and-native-inspection).
+
+## Terminal Watch
+
+The [terminal handoff demo](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/assets/akk-tmux-handoff-demo.mp4)
+shows OpenClaw giving Claude Code a task and handing its result to Codex
+through tmux; both terminals remain available for direct human use.
+
+Watch follows the exact terminal selected by the user. Codex 0.158.0/0.159.0/0.159.2 exact
+Watch creation types a closed `/status` command into an available main Composer;
+subsequent observation is read-only. Newer Codex versions may use the same
+strict observed UI and paginated read contracts. See the
+[upgrade compatibility policy](callback-compatibility.md).
+
+```text
+/akk list
+/akk watch <exact-terminal-id>
+/akk status <watch-id>
+/akk unwatch <watch-id>
+```
+
+The fresh list is the safest way to copy a complete `terminal_id`, but missing
+Watch advertisement, coding-agent version uncertainty, unusable task artifacts,
+or existing managed ownership are warnings rather than authorization vetoes.
+Watch fails only when the exact terminal/process cannot be identified, neither
+an exact task anchor nor a read-only terminal-activity path exists, or the
+durable Watch record cannot be created.
+
+An exact provider anchor produces `watch_mode="exact_task"` and
+`confidence="exact"`. Without one, AKK can use
+`watch_mode="terminal_activity"` and `confidence="best_effort"`: it must first
+observe working or approval activity and then stable idle. That callback proves
+only that the observed activity became idle, not that one uniquely identified
+task succeeded, and it contains no exact-task completion text.
+
+After initial Codex foreground binding, Watch observation sends no terminal
+input and does not adopt, reserve, block, interrupt,
+approve, or own the selected task. Manual-Watch approval events are
+notification-only and never participate in auto-approval. Durable Watch state,
+notification identities, and callback outboxes make restart recovery
+idempotent. A managed Turn monitor remains preferable when exact Turn
+attribution already exists.
+
+## Sessions, Turns, and native threads
+
+For terminal-managed work, AKK keeps these identities separate:
+
+```text
+tmux or Herdr terminal / verified process incarnation
+├─ native Codex or Claude Code session
+│  └─ AKK Session (session_id)
+│     ├─ Turn (turn_id)
+│     └─ Turn (turn_id)
+└─ Terminal Watch (watch_id)
+```
+
+Backend Send instead returns one persisted task ID as both `watch_id` and
+`turn_id`; a standalone backend Watch has no Send management. These task IDs
+stay bound to the original thread and native task. They do not authorize the
+terminal lifecycle commands below.
+
+New and resume are native lifecycle transitions. They create or activate an
+AKK Session but create no Turn. Run `/akk threads <exact-terminal-id>` to get
+the current candidates. The output includes deterministic numbers,
+collision-safe display-only short IDs, and each complete native thread UUID.
+The number and short-ID resume forms belong only to that displayed snapshot;
+neither is a durable identity or model authority. They expire after five
+minutes and after terminal, process, workspace, binding, candidate-set, or
+relevant action changes.
+
+`previous` is advertised only when the current Session's latest committed
+transition and fresh discovery prove exactly one resumable source. If
+`previous` is present, use only its exact prefilled semantic-ID action for a
+natural-language “刚才那个” request. Never substitute the newest terminal row.
+
+Do not ask AKK to send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`,
+`/side`, `/btw`, Claude `/branch`, or another first-line native slash command
+as an ordinary task. Use the advertised lifecycle, native-inspection, or
+Codex foreground-identification action, express the outcome in natural
+language, or type an unsupported command directly in the TUI. AKK revalidates
+the entire candidate snapshot before terminal input; candidate-set changes
+fail closed. A replaced or changed transcript/rollout cannot be resumed under
+stale metadata.
+
+## Permission settings
+
+Send preserves the selected conversation's existing permission mode. Use an
+explicit advertised permission action to change it before sending a task.
+The [CLI backend](codex-cli-native-compatibility.md) and
+[Desktop](codex-desktop-compatibility.md#settings-and-cancellation) adapters
+apply and verify the selected conversation's native settings. For a Codex
+terminal, [Codex permissions](codex-permissions.md) covers the current native
+choices and exact idle-terminal checks. Full Access is an explicit supported
+choice; AKK handles its native confirmation without an additional prompt.
+
+## Safe model control
+
+This section describes terminal model control. Desktop settings use the
+[Desktop settings API](codex-desktop-compatibility.md#settings-and-cancellation)
+and do not expose a model catalog; they accept an explicitly requested model
+and effort. The direct CLI backend has no equivalent native model operation.
+Use only the provider capability advertised by the selected conversation.
+
+Model control is a two-step, current-snapshot operation. Start from a fresh
+`/akk list`, copy one complete `terminal_id` whose row advertises
+`available_actions.model_options`, then run:
+
+```text
+/akk models <exact-terminal-id>
+/akk set-model <exact-terminal-id> <advertised-model-id> <advertised-reasoning-effort>
+```
+
+The first command opens and closes the agent's native model UI as one bounded
+inspection. It returns the effective model, the semantic model IDs currently
+available to that account and runtime, and each model's available reasoning
+efforts. This is dynamic authority, not a static AKK allowlist: copy one exact
+model ID and one exact reasoning value from that result. Both values are
+required; an omitted, invented, or unadvertised effort fails before native
+model-selection input. The structured postcondition remains authoritative
+about the effective tuple.
+
+The matching OpenClaw tools are
+`agent_knock_knock_model_options({terminal_id})` and
+`agent_knock_knock_set_model({terminal_id,model,reasoning_effort})`. The
+options result and its private physical-terminal/catalog authority belong to the
+same controller
+conversation and are consumed by one set-model attempt. Relist after any pane,
+process, catalog, or UI change, or after any failed attempt.
+Neither tool accepts a slash command, raw key, menu index, display label,
+scope override, token, or fingerprint.
+
+If a failed profiled Codex 0.154.0/0.155.1 attempt leaves an exact `/model` popup or an
+exact bare `/model` Composer, List may advertise both
+`model_options({terminal_id})` and `repair_model_control({terminal_id})`.
+The former uses separate residual-bound authority to continue that exact slash
+command into read-only catalog discovery without retyping it. The latter is the
+cleanup-only alternative; its equivalent human command is
+`/akk repair-model-control <exact-terminal-id>`. It accepts only the terminal
+ID and privately revalidates the pane, process, residue, approval state, and
+absence of an active Turn before every reversible cleanup input. It never
+presses Enter, selects a model, submits a task, or handles an approval or
+questionnaire. Success requires an exactly empty Composer. An uncertain
+continuation or repair is not retryable.
+
+If the exact native model picker is already open, List projects the terminal
+as non-idle and advertises only `repair_model_control`. That repair may dismiss
+the exact picker but never receives authority to press Enter.
+
+Both steps use explicit current-snapshot authority for the same exact physical
+terminal and coding-agent process. Profiled Codex 0.154.0/0.155.1 may use either one exact current
+native Session or a verified-zero-rollout pane, and the Codex-only
+`identify_foreground` diagnostic is not a prerequisite. Claude Code still
+requires one exact current native Session. The pane
+must remain safely idle with an exactly empty Composer, except for the exact
+Codex residual continuation described above. An active Turn, working
+agent, approval, questionnaire or editor, read-only viewer, non-empty Composer,
+ambiguous or multi-rollout Codex identity, stale physical snapshot, unsupported
+version, or changed catalog fails closed
+with no model-selection input. The private multi-step native sequence
+revalidates each frame and must return to the main Composer without submitting
+a task or answering a prompt.
+
+Provider scope is explicit in both results:
+
+- Codex reports `scope="current_and_new_sessions"`. Its native model flow
+  changes this session and persists the selected model as the default for
+  future Codex sessions. Ordinary reasoning efforts through `max` are also
+  persisted. Codex treats `ultra` specially: it is effective only in the
+  current session, while the future-session effort falls back to a non-Ultra
+  value. The scope label therefore does not claim that Ultra itself persists.
+  These are intentional, visible side effects of the approved native
+  operation; AKK does not edit `~/.codex/config.toml` directly or restore it
+  afterward.
+- Claude Code reports `scope="current_session"`. Its native session-only path
+  changes the open session and leaves new-session defaults unchanged.
+
+A successful result is `changed` or `already_effective` and reports the
+current session under `effective`, the future Codex defaults under
+`new_session_defaults`, and whether they changed under `defaults_changed`.
+For an Ultra request, expect `effective.reasoning_effort="ultra"` and only the
+persisted model in `new_session_defaults`. The native TUI does not expose the
+exact non-Ultra effort it chooses for new sessions, so AKK omits that field
+rather than guessing; never infer that Ultra became a future default from
+`scope="current_and_new_sessions"` alone.
+`outcome="uncertain"` means native input may have taken effect but AKK could
+not prove the final state. It carries `do_not_retry=true`: inspect the shared
+pane, then obtain a new model catalog before any deliberate new attempt. Model
+control creates no AKK Turn and never approves, answers, or submits coding
+work.
+
+## AKK Status and native inspection
+
+Status follows its target. An exact backend task's `watch_id` or Send-produced
+`turn_id` reads that original backend's native state without terminal input.
+A backend conversation Status reads the selected native conversation. Bound
+terminal Turns and Watches retain their original observation route. List
+never types into a terminal.
+
+AKK 0.14.1 adds a single `progress` object to CLI
+backend and Desktop Status. Conversation Status selects its current native turn;
+Watch Status always selects the Watch's original turn, even after a newer task
+starts. The latest public commentary and up to two short action type/status
+summaries share an 800-Unicode-code-point body budget, with unused space shared
+between them. Redaction precedes truncation, which preserves complete graphemes.
+Reasoning, analysis, raw command output, tool arguments and diffs are excluded.
+This is a progress-body limit, not a limit on the whole Status JSON. List does not
+include this body, and the terminal screen contract is unchanged.
+
+`progress.native_turn_id` identifies the selected task; `read_at` records the
+read time. `latest_item_at` is a native timestamp of the displayed progress, or
+`null` if none is available; it is never replaced with the read time. `truncated`
+reports shortening of the selected progress body or omission of code blocks. `state: "no_public_progress"` means the read
+succeeded without eligible public progress, while `state: "read_error"` means
+the exact task/items could not be read completely. Neither means the task has
+stopped. Missing old-turn data is never replaced with a successor's progress.
+`trace` retains its existing terminal behavior; it is not an unbounded backend
+progress mode. Final answers and current questions/approvals retain their own
+existing fields.
+
+When the selected conversation is an unbound physical Codex terminal, targeted
+Status may use the existing closed `/status` identity inspection if that pane
+is safely idle. It can display a native status card to establish the exact
+backend thread. It does not create a task or disturb a working or blocked
+terminal. This routing inspection is separate from the diagnostic-only
+`identify_foreground` action; see [automatic conversation routing](codex-cli-native-compatibility.md#automatic-conversation-routing-2026-10-10).
+
+Explicit native inspection remains a closed action:
+`native_inspect({terminal_id,inspection:"status"})`. It accepts no arbitrary
+command and creates no AKK Turn, Session, receipt, monitor, or callback.
+
+Native inspection and foreground identification are different contracts.
+`native_inspect` inspects an already attributable native context. The explicit
+Codex-only `identify_foreground` action is available for an otherwise safe but
+ambiguous foreground and returns only the 30-second non-authorizing diagnostic
+described above. `identify_and_send` consumes its observation without
+releasing the terminal lock; callers must never cache a standalone proof and
+use it as authority for a later action.
+
+Codex native `/status` inspection requires an exact viewport of at least 80
+columns so the complete UUID can be proven. Legacy terminal-scoped tasks
+can bind from exact native acceptance afterward without running `/status` or
+failing merely because the pane is narrow. Codex paginated read-contract candidates attempt a separate
+closed `/status` binding before physical Send. If an exact callback Watch cannot
+be prepared safely, AKK may prepare terminal-activity observation; the receipt states the actual mode and limitation. Claude inspection must prove,
+parse, and dismiss one fresh Status panel and return to the same idle composer.
+Other complete `x.y.z` agent versions remain callable with a compatibility
+warning; incompatible runtime behavior fails or becomes uncertain rather than
+being blocked by a version allowlist.
+
+## Approval boundaries
+
+Approval always requires the current exact prompt and explicit human intent.
+Backend approvals use the exact pending interaction from fresh Status in the
+same controller conversation. See the [CLI backend](codex-cli-native-compatibility.md)
+and [Desktop interaction](codex-desktop-compatibility.md) guides. The prompt,
+screen, and key boundaries below describe terminal approval.
+
+Managed approval uses `approve({turn_id})`; terminal-scoped manual Codex
+approval uses `approve({terminal_id})` when the current list advertises it.
+On an unmanaged raw-terminal row, that action is prefilled with its exact
+`terminal_id`; never construct or guess the target.
+
+The private approval fence is prompt-scoped. It binds the adapter-isolated
+exact unredacted approval region, terminal/process identity, decision keys,
+prompt kind, working directory, reason, and request evidence. The whole-screen
+digest and redacted excerpt are diagnostic only: output outside the approval
+region may keep scrolling without invalidating the same prompt. Any change
+inside the exact region—including a command or an otherwise identically
+redacted secret—rejects and sends zero approval keys.
+
+Terminal-scoped approval leaves Session and Turn identity unchanged, is never
+available to auto-approve, and must not be retried blindly after an uncertain
+transport result. Unsupported, stale, changed, ambiguous, or ownership-drifted
+prompts remain for the human to resolve in the coding-agent TUI. OpenClaw's
+optional exact-command auto-approval policy is documented separately in
+[OpenClaw operations](openclaw-operations.md#automatic-approval).
+
+## Recovery and advanced controls
+
+Recovery is specific to the provider and original task. Use its exact saved ID
+and the applicable actions below; do not substitute the latest conversation.
+
+### Backend task recovery
+
+For Codex CLI backend and Desktop tasks, use the original task's `watch_id`
+from the originating controller; Recover, Renew, Close, and Retry Callback
+also accept its Send-produced `turn_id`. `recover` reconciles
+the original task and supervises eligible monitor work; `renew` verifies that
+task before extending observation. `unwatch` stops observation while retaining
+Send management, and `close` releases managed Send ownership without stopping
+Codex. A standalone Watch uses Unwatch. `retry_callback` retries only a known
+retryable notification with its original identity; select `notification_id`
+when more than one is eligible.
+
+These operations never select the latest task or fall back to a terminal.
+Closed management cannot be reopened, and Recover does not extend deadlines
+or resume an explicitly stopped Watch. For exact inputs, callback uncertainty,
+and observation semantics, use the [backend task recovery reference](backend-task-recovery.md).
+
+### Terminal recovery and diagnostics
+
+The following terminal controls remain available when the corresponding
+state makes them meaningful. `reconcile_binding`, `identify_foreground`, and
+`repair_model_control` retain their physical-terminal requirements; backend
+Recover does not replace them.
+
+| Command | Use |
+| --- | --- |
+| `/akk doctor` | Diagnose installation, Host, terminal, and coding-agent readiness. |
+| `/akk models <terminal>` | Inspect one idle pane's exact native model and reasoning catalog. |
+| `/akk repair-model-control <terminal>` | Clear one exact List-advertised stale Codex `/model` surface; never submit it. |
+| `/akk set-model <terminal> <model> <effort>` | Consume that catalog once; Codex reports current and future defaults separately (Ultra stays current-only), while Claude Code is session-only. |
+| `/akk approve <turn-or-terminal>` | Approve one current prompt after explicit review. |
+| `/akk renew <turn> <minutes>` | Restart monitoring for one still-live stalled Turn without terminal input. |
+| `/akk retry-callback <turn>` | Retry one persisted failed callback with its original identity. |
+| `/akk close <turn>` | Ordinary managed-Turn Close releases AKK management without terminal input or stopping the coding agent; native lifecycle recovery has the exception below. |
+
+Explicit terminal Close is the user's management escape hatch. It has priority over
+broken deferred-transfer or handoff state, closes the selected Turn first, and
+then best-effort releases only linked AKK metadata. Refresh List afterward; if
+the agent is still working, a new Watch can observe it.
+
+Closing an uncertain native new/resume transition is a separate recovery path:
+it may clear an unsubmitted Composer and perform a guarded `/status` inspection
+to establish the actual native identity. Follow that exact advertised recovery
+action. Do not treat every terminal Close variant as a record-only operation.
+
+An uncertain terminal mutation is not a retry instruction. Do not resend,
+approve, cancel, or repeat Enter blindly. Inspect the exact pane and durable
+Status, then use only the action currently advertised by AKK.
+
+## Structured tool surface
+
+The OpenClaw plugin and Host Adapter register the ordered semantic tool catalog.
+Pi and DeepSeek Harness verify the Host Adapter capability handshake against
+their actual registrations, so the tool count and names are derived from that
+catalog rather than maintained as connector constants. The current catalog
+includes list, watch, unwatch, list resumable threads, native inspect, model
+options, repair model control, set model, permission options, set permissions,
+identify foreground, identify and send, new thread, reconcile binding, resume
+thread, status, send, respond, typed native interaction response, approve,
+renew, recover, retry callback, cancel, and close. Model-facing mutations
+contain semantic IDs and user content only.
+Connector prereleases that pin an earlier AKK runtime retain the tool surface
+documented by that connector release.
+Selectors, pane routes, draft text, fingerprints, tokens, revisions, candidate
+fences, and binding generations stay inside the trusted Host adapter.
+
+For the full lifecycle, callback, identity, handoff, and persistence contract,
+see the [Terminal Handoff Protocol](bidirectional-agent-protocol.md). For
+configuration and recovery specific to OpenClaw, see
+[OpenClaw Operations](openclaw-operations.md).

package/docs/storage-and-logging.md

@@ -0,0 +1,91 @@
+# Storage and Logging
+
+AKK keeps managed state in `~/.agent-knock-knock/store` by default. The Store
+contains its compatibility manifest, authoritative Sessions and Turns,
+independent Terminal Watch records, dispatch receipts, callback outboxes, and
+event logs. It may therefore contain terminal and task metadata and should
+remain private.
+
+## Filesystem safety
+
+- Store directories use mode `0700`.
+- State and event-log files use mode `0600`.
+- Durable JSON writes are atomic and do not follow symbolic-link targets.
+- A custom Store must be a dedicated directory. AKK refuses a non-empty
+  manifestless directory rather than adopting unknown files.
+- 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.
+
+## 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
+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
+manifest `created_at` remain unchanged.
+
+Protocols 3 through 8 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
+protocol-6 writers. Protocol 8 protects paginated task anchors and private
+multi-question checkpoints from older writers. Terminal Watch schema v3 separately adds interaction
+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
+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
+authorized physical Send that leaves managed state untouched.
+
+## Conversation routing journal
+
+Backend-first Send records its chosen provider before task delivery. These
+records live under the private runtime directory (`~/.agent-knock-knock/runtime-v2`
+by default, or `AKK_RUNTIME_DIR`), in `conversation-routing/<store-path-hash>/state`.
+They have their own locks and compatibility manifest; they do not acquire the
+managed Store's writer lock. A reused message ID stays on its original provider,
+even if another route becomes available later.
+
+Development builds that wrote these records under the managed Store are read
+without modifying the old records. Their original route and any recorded outcome
+remain authoritative; conflicting journals stop the request. A replayed receipt
+is the original submission observation. Query Status for current task state.
+
+## Legacy directory
+
+The former `~/.agent-knock-knock/conversations` directory is left untouched.
+AKK does not read or migrate it. Existing Codex and Claude Code terminals remain
+discoverable, but legacy managed-turn IDs, callback associations, and old
+conversation aliases are not imported into the stable Store.
+
+## Logs and retention
+
+Runtime logs redact common secret forms and default to 14-day retention. The
+main controls are:
+
+| Control | Purpose |
+| --- | --- |
+| `--store-dir` | Use a dedicated Store for standalone CLI operations. |
+| `AKK_LOG_DIR` | Select a dedicated runtime log directory. |
+| `AKK_LOG_LEVEL` | Set the emitted log level. |
+| `AKK_LOG_RETENTION_DAYS` | Change the retention window. |
+
+Do not point a custom Store or log directory at a broad home, workspace, or
+shared directory. Review retained callback and terminal data before any manual
+cleanup. AKK does not delete coding-agent transcripts, Codex rollouts, tmux or
+Herdr sessions, or model credentials.
+
+OpenClaw-specific `storeDir` configuration and operational diagnostics are in
+[OpenClaw Operations](openclaw-operations.md). The full Session, Turn, Watch,
+and callback identity contract is in the
+[Terminal Handoff Protocol](bidirectional-agent-protocol.md).