@scotthuang/agent-knock-knock 0.13.18 → 0.14.0

package/connectors/pi/README.md

@@ -0,0 +1,446 @@
+# Agent Knock Knock for Pi — POC
+
+This Pi Extension makes Pi an Agent Knock Knock (AKK) orchestration Host. Pi
+can use `/akk` and AKK's capability-handshake-verified semantic tools to control Codex and Claude Code
+terminals that are already running in tmux or Herdr.
+
+The connector does not modify Pi, launch or authenticate a coding agent, or
+depend on an OpenClaw Gateway. It uses AKK's public HostAdapter and returns
+callbacks to the exact initiating Pi session through a private local Unix
+socket.
+
+## Status and compatibility
+
+This connector's pinned AKK 0.13.3 runtime provides terminal control. The
+[root README](../../README.md) describes the newer AKK 0.14.0 CLI direct,
+Desktop, and Recovery features; installing this connector does not select that
+runtime automatically. The AKK core release does not upgrade this connector's
+pinned dependency.
+
+This is a POC prerelease distributed on npm as
+`@scotthuang/agent-knock-knock-pi`. Prereleases use the `next` dist-tag:
+
+```sh
+pi install npm:@scotthuang/agent-knock-knock-pi@next
+```
+
+The current compatibility contract is intentionally exact:
+
+- Pi `0.84.4`, installed from the official
+  `@earendil-works/pi-coding-agent` package.
+- Node.js `22.19.0` or newer.
+- AKK `0.13.3`, pinned by this connector's package and lockfile. Running
+  `npm ci` in `connectors/pi` installs that exact AKK runtime; a different
+  version at the repository root is not substituted automatically.
+- macOS or Linux. The POC requires a POSIX Unix socket and does not support
+  Windows named pipes.
+- At least one authenticated Codex or Claude Code process already running in a
+  supported tmux or Herdr terminal under the same OS user.
+- A configured Pi model/provider. Pi model authentication is separate from
+  AKK and is not performed by this connector.
+
+The connector rejects a Pi runtime other than `0.84.4` before it creates a
+socket or starts AKK lifecycle work. Pi's own packages remain `*` peer
+dependencies as required by Pi's package contract; the runtime check is the
+compatibility authority.
+
+## Five-minute quick start
+
+### 1. Install the accepted Pi version
+
+```sh
+npm install -g @earendil-works/pi-coding-agent@0.84.4
+node --version
+pi --version
+```
+
+Configure a model using Pi's normal `/login`, provider environment variable,
+or settings flow before continuing.
+
+### 2. Start a coding agent in a shared terminal
+
+AKK discovers an existing process; it never starts one for you. For example:
+
+```sh
+tmux new-session -s akk-pi-work -c "$(pwd -P)" codex
+```
+
+Wait for Codex to reach its interactive prompt, then detach with `Ctrl-b`
+followed by `d`. Use `claude` instead of `codex` to test Claude Code. An
+existing supported Herdr terminal works too.
+
+### 3. Install the connector
+
+```sh
+pi install npm:@scotthuang/agent-knock-knock-pi@next
+pi list
+```
+
+Using `next` follows compatible Pi connector prereleases. To pin this exact
+build instead, install
+`npm:@scotthuang/agent-knock-knock-pi@0.1.0-poc.2`; exact versions are pinned
+and are not advanced by Pi's bulk update command.
+
+### 4. Start Pi
+
+```sh
+pi
+```
+
+Pi should show `AKK ready`. The package manifest registers both the Extension
+and its bundled `agent-knock-knock` skill, so no separate skill copy, `-e`
+path, or repository checkout is required. The structured List result stays
+small by returning current action names and dynamic inputs; Pi loads the skill
+when it needs the static action meanings and safety rules.
+
+### 5. Complete the first round trip
+
+In Pi, list the live targets:
+
+```text
+/akk list
+```
+
+If exactly one terminal is send-ready, submit a small task:
+
+```text
+/akk reply with exactly AKK_PI_OK after inspecting the current workspace
+```
+
+If multiple targets are present, use the fresh selector printed by
+`/akk list`:
+
+```text
+/akk @a1b2c3d4: reply with exactly AKK_PI_OK after inspecting the current workspace
+```
+
+A managed Send returns a `turn_id`; when the coding agent settles, its callback
+is injected into the same Pi session. Inspect it at any time with the exact
+turn selector printed by AKK:
+
+```text
+/akk status <turn-selector>
+```
+
+To observe work that you started manually in the terminal, copy the complete
+`terminal_id` from a fresh list and start a read-only Watch:
+
+```text
+/akk watch <exact-terminal-id>
+/akk status <watch-id>
+/akk unwatch <watch-id>
+```
+
+Watch does not send, adopt, approve, interrupt, or reserve the task. Do not add
+a second Watch merely to make a normal managed Send callback: managed Send
+already has a callback. When a user-priority Send must fall back to unmanaged
+physical delivery, AKK instead tries to attach the request-bound Watch itself
+and returns its `watch_id`.
+
+## Tool workflow
+
+The usual product loop is:
+
+1. **List** to discover live terminals and their current `available_actions`.
+2. **Send** using the fresh action's prefilled `session_id` or `terminal_id`.
+   Do not invent semantic IDs or retry an uncertain terminal mutation.
+3. Wait for the managed **Callback**. An unmanaged user-priority fallback may
+   return a Terminal Watch callback instead of a managed Turn callback.
+4. Use **Status** with the exact `turn_id` or `watch_id` when the callback is
+   delayed or the Pi route changed.
+5. Use **Respond** for a question in that same Turn. Use **Approve** only after
+   reviewing the live approval prompt and making an explicit decision.
+6. Use **Cancel**, **Close**, **Renew**, or **Retry Callback** only when the
+   current list/status output advertises that exact action.
+
+The `/akk` command is the direct human surface. The complete semantic catalog is
+also registered for model-driven orchestration:
+
+| Tool | Purpose |
+| --- | --- |
+| `agent_knock_knock_list` | List verified Codex/Claude terminals, managed work, Watches, and currently available semantic actions. |
+| `agent_knock_knock_watch` | Start a durable, read-only Watch for one exact `terminal_id`. |
+| `agent_knock_knock_unwatch` | Stop observation by exact `watch_id`; it does not interrupt the coding agent. |
+| `agent_knock_knock_list_resumable_threads` | List structurally verified native threads that can be resumed in one terminal. |
+| `agent_knock_knock_native_inspect` | Run the closed native `status` inspection for one exact terminal. Arbitrary slash commands are not accepted. |
+| `agent_knock_knock_model_options` | Read one exact idle terminal's native model and reasoning catalog and create a single-use typed offer. |
+| `agent_knock_knock_repair_model_control` | Dismiss only an exactly recognized stale model-control surface; it never selects a model or submits a task. |
+| `agent_knock_knock_set_model` | Consume the current catalog offer to select one advertised semantic model and reasoning effort. |
+| `agent_knock_knock_identify_foreground` | Run a bounded diagnostic native identity probe without creating durable model-control authority. |
+| `agent_knock_knock_identify_and_send` | Keep one terminal lock across identity observation and one explicit Send when the normal foreground identity is ambiguous. |
+| `agent_knock_knock_new_thread` | Start and verify a clean native coding-agent thread after explicit user intent. |
+| `agent_knock_knock_reconcile_binding` | Detach one exact conflicting AKK Session binding after explicit confirmation, without adopting another thread. |
+| `agent_knock_knock_resume_thread` | Resume one exact complete `native_thread_id` returned by the current discovery result. |
+| `agent_knock_knock_status` | Inspect one exact managed Turn or Terminal Watch. |
+| `agent_knock_knock_send` | Send a new task through the exact currently advertised Session or terminal action. |
+| `agent_knock_knock_respond` | Answer a question or blocked callback in one existing Turn; it does not start a new Turn. |
+| `agent_knock_knock_respond_interaction` | Answer the current typed native questionnaire step for one exact response-capable Turn or Watch. |
+| `agent_knock_knock_approve` | Approve one current permission request after Pi presents a native user-decision gate. |
+| `agent_knock_knock_renew` | Renew monitoring for one stalled but still-live Turn without terminal input. |
+| `agent_knock_knock_retry_callback` | Retry one persisted managed callback with its original message identity. |
+| `agent_knock_knock_cancel` | Interrupt one exact task after Pi obtains native confirmation; the shared pane stays open. |
+| `agent_knock_knock_close` | Release AKK management for one Turn without sending terminal input or stopping the coding agent. |
+
+Except for the deliberately user-intent-first, read-only Watch path, treat the
+fresh `available_actions` output as authority. The connector preserves AKK's
+semantic-ID, idempotency, terminal identity, Store, Session, Turn, and
+completion rules rather than recreating them in Pi.
+
+## Active approval, response, and cancellation
+
+When a managed task needs permission, its callback is queued into the
+originating Pi session. A model-facing `agent_knock_knock_approve` call does not
+immediately type into the terminal. The connector first refreshes AKK Status,
+shows the current prompt in Pi's native UI, and requires a selection:
+
+- **Approve once** sends the current prompt-scoped AKK approval.
+- **Keep pending** sends no terminal input.
+- For a managed `turn_id`, **Reject and cancel task** asks for a second
+  confirmation, then invokes AKK Cancel.
+
+A terminal-scoped approval has no terminal-scoped Cancel authority, so its
+dialog offers only Approve or Keep pending. A separately advertised Cancel
+action gets its own Pi confirmation dialog.
+
+`agent_knock_knock_respond` answers an ordinary question in the exact
+in-flight Turn; it is not an approval denial. AKK currently has no generic
+"select the target's No option and continue this Turn" tool. Reject-and-cancel
+interrupts the task instead.
+
+The native confirmation flow requires an interactive Pi UI. In a context where
+`ctx.hasUI` is false, the connector refuses model-facing Approve and Cancel
+instead of mutating the terminal without a person. Headless/non-interactive Pi
+is not a product-acceptance target for this POC.
+
+AKK keeps the coding agent's existing permission mode. This connector does not
+enable `--yolo`, change a target's permission settings, or expose AKK's
+OpenClaw-specific `autoApprove` configuration.
+
+## Callback delivery and recovery
+
+The callback path is:
+
+```text
+AKK callback outbox
+  -> command_json_v1 callback helper
+  -> authenticated private Unix socket
+  -> fsync-backed Pi callback inbox
+  -> originating Pi session
+```
+
+When Pi is idle, the callback is injected with `triggerTurn: true` and starts a
+new Pi turn. When Pi is already producing a response, the connector uses Pi's
+follow-up queue so the callback is not mixed into the current model turn.
+
+An `accepted` callback acknowledgement means that the connector durably
+admitted the exact delivery to its local inbox and returned an acceptance ID.
+It does **not** mean the Pi model consumed the message: Pi `0.84.4` exposes a
+synchronous `sendMessage()` call without a model-consumption receipt. The last
+hop is therefore at-least-once or uncertain if Pi crashes between
+`sendMessage()` and recording the inbox entry as delivered. Delivery and
+idempotency IDs let the connector reject collisions and suppress known exact
+duplicates.
+
+For a missing callback:
+
+1. If Pi is busy, wait for the current response to end; the callback may be a
+   queued follow-up.
+2. Refresh `/akk list`, then run `/akk status <turn-selector-or-watch-id>`.
+   Status is the authoritative manual recovery path and does not need the
+   callback to have reached the model.
+3. If a still-live task has no managed callback route, start a new read-only
+   Watch on its exact current `terminal_id` and retain the returned `watch_id`.
+4. Use `agent_knock_knock_retry_callback` only when the current managed Turn
+   advertises it and the original Pi callback route is still live. Never retry
+   an uncertain terminal Send to recover a callback.
+
+The POC owns one live Pi runtime and one branch epoch. Explicit session-tree
+navigation rotates the controller route; Pi shutdown removes the socket and
+invalidates that runtime's route. The durable inbox does not migrate callbacks
+from an old random controller identity into a new Pi runtime or branch. After a
+restart or branch change, use fresh List/Status and, for still-running terminal
+work, a fresh Watch. Do not expect the old route's callback to jump to the new
+conversation automatically.
+
+## Configuration, security, and storage
+
+The connector needs no project-specific configuration. These optional
+environment variables must be set **before** Pi starts and must contain
+absolute paths:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `AKK_PI_STORE_DIR` | `~/.agent-knock-knock/store` | Override AKK's shared Session, Turn, Watch, receipt, and callback-outbox Store. |
+| `AKK_PI_STATE_DIR` | `~/.pi/agent/akk` | Override the Pi connector's durable callback-inbox directory. |
+
+Example with isolated development state:
+
+```sh
+AKK_PI_STORE_DIR=/absolute/private/path/akk-store \
+AKK_PI_STATE_DIR=/absolute/private/path/pi-akk-state \
+pi
+```
+
+Security and retention boundaries:
+
+- Pi Extensions execute with the same OS privileges as Pi. Review local
+  connector source before loading it.
+- Each Pi runtime creates a random directory under the OS temporary directory
+  with mode `0700`. Its Host Profile and authenticated Unix socket use mode
+  `0600`, and the directory is removed on clean Pi shutdown.
+- The socket token is random and runtime-private. It is not written to the
+  durable inbox or accepted as a model/tool argument. The callback helper is
+  allowed only the socket and token environment variables it needs.
+- The persistent state directory is forced to `0700`; its
+  `callback-inbox.json` is written atomically with mode `0600`. It can retain
+  callback bodies, which may contain task results. The inbox is bounded to 256
+  entries and 64 MiB, pruning older delivered entries as new callbacks arrive.
+- The AKK Store is separate from the Pi inbox and may contain terminal/session
+  metadata and callback results. Use a dedicated private directory for either
+  override; do not point it at a shared or broad filesystem root.
+- The connector strips the supported GLM credential environment variables
+  from AKK relay/callback subprocess environments. Model credentials remain
+  Pi-owned and are never connector configuration.
+
+## Troubleshooting
+
+| Symptom | Check and recovery |
+| --- | --- |
+| `requires Pi 0.84.4` | Run `pi --version`, then reinstall the exact accepted release with `npm install -g @earendil-works/pi-coding-agent@0.84.4`. Newer Pi releases are not silently accepted by this POC. |
+| Pi never shows `AKK ready` | Confirm Node is at least 22.19, run `pi list`, update or reinstall `npm:@scotthuang/agent-knock-knock-pi@next`, and fully restart Pi. For a source checkout, follow the local-development build commands below. |
+| Module or `lib/index.js` not found | Remove and reinstall the npm package. For a source checkout, confirm Pi was given `connectors/pi`, not the repository root, and rebuild with the documented cwd-specific command. |
+| `/akk list` finds no terminal | Start authenticated `codex` or `claude` inside supported tmux/Herdr under the same OS user and leave the process running. The connector never launches it. |
+| Send says the target is ambiguous | Run a fresh `/akk list` and use the exact displayed selector for `/akk`, or the prefilled semantic ID from that row's current tool action. |
+| Callback does not appear immediately | Pi may be busy, so the callback is queued as a follow-up. Wait for the current turn, then use fresh List and Status. After a Pi restart or branch change, the old callback route is intentionally not migrated. |
+| Approval or cancellation says an interactive UI is required | Use Pi's interactive TUI. The POC deliberately blocks model-facing Approve/Cancel when `ctx.hasUI` is false. |
+| Approval changed before confirmation | Refresh Status and review the newly observed prompt. Do not reuse an old approval offer or blindly retry an interrupted approval. |
+| Callback socket/profile is unavailable | The owning Pi runtime may have stopped or its temporary private directory may have disappeared. Restart Pi to create a fresh route; recover existing work with List/Status rather than copying socket paths or tokens. |
+| State-directory or Store permission error | Both override variables must be absolute and point to dedicated real directories. Stop Pi, inspect ownership and contents, then choose a new private directory if the existing path is unsafe or incompatible. |
+| Updated connector still behaves like the old POC | Run `pi update npm:@scotthuang/agent-knock-knock-pi` and fully restart Pi. For a source checkout, re-run `npm ci` and the connector-specific build first. A running Extension is not hot-replaced. |
+| Send result is uncertain | Do not automatically send the task again. Inspect Status, the exact pane, or the attached Watch; retrying terminal input could duplicate work. |
+
+## Upgrade and uninstall
+
+Inspect and update the npm installation with Pi's package manager:
+
+```sh
+pi list
+pi update npm:@scotthuang/agent-knock-knock-pi
+```
+
+Keep Pi at exactly `0.84.4` until this README declares another accepted
+version. Do not use an unverified Pi upgrade as a connector update.
+
+Remove the npm package by its package identity:
+
+```sh
+pi remove npm:@scotthuang/agent-knock-knock-pi
+```
+
+`pi uninstall` is an alias for `pi remove`. Removing the package does not stop
+or delete Codex/Claude terminals, model credentials, `~/.pi/agent/akk`, or the
+AKK Store. Those durable directories are retained for inspection/recovery and
+should be reviewed separately before any manual deletion.
+
+## Development and verification
+
+To load a source checkout for one Pi run, build the connector explicitly:
+
+```sh
+AKK_REPO=/absolute/path/to/agent-knock-knock
+cd "$AKK_REPO"
+npm --prefix connectors/pi ci
+npm run pi:build
+pi -e "$AKK_REPO/connectors/pi"
+```
+
+The equivalent child-package build is:
+
+```sh
+cd "$AKK_REPO/connectors/pi"
+npm ci
+npm run build
+```
+
+Do not run a bare root `npm run build` and assume it built this connector. The
+unambiguous root command is `npm run pi:build`; inside `connectors/pi`, use
+`npm run build`. `pi -e` is temporary and changes no package settings. To
+persist a local source path, use `pi install "$AKK_REPO/connectors/pi"`; remove
+that same absolute source with `pi remove` when finished.
+
+From the repository root:
+
+```sh
+npm run pi:typecheck
+npm run pi:test:fast
+npm run pi:pack:check
+```
+
+Or from `connectors/pi`:
+
+```sh
+npm run typecheck
+npm run test:fast
+npm run pack:check
+```
+
+## Release safety
+
+`npm run release:check` is check-only. The shared connector gate proves the
+generated Skill hash, package manifest/constants/lock/dependency parity, then
+runs typecheck, fast tests, and inspection of the real package tarball. In
+release mode it also requires a clean synchronized `main`, verifies that the
+exact npm version and `pi-v<version>` repository tag are unused, and rejects
+non-publishable runtime dependency specifiers.
+
+Activation also performs a runtime compatibility gate. The pinned AKK
+HostAdapter must expose capability handshake v1, whose catalog digest, ordered
+tool names and derived count, and canonical Skill digest must match both this
+package's generated Skill and the tools Pi just registered. Missing or forged
+metadata, an unknown handshake version, or partial registration prevents the
+connector from reporting `AKK ready`; no connector-local tool-count literal is
+used.
+
+The deterministic local form performs the same package checks without reading
+registry or git-remote release state:
+
+```sh
+npm run release:check -- --offline
+```
+
+From the repository root, `npm run connectors:verify` checks Pi and DeepSeek
+Harness independently; it does not require their package versions to match.
+Publishing Pi additionally requires explicit version confirmation:
+
+```sh
+npm run release:check -- --publish --confirm-version 0.1.0-poc.2
+```
+
+Prereleases use npm tag `next`; stable versions use `latest`. Tags and GitHub
+Releases use `pi-v<version>` and are created separately after npm verification.
+
+The [PR #266](https://github.com/scotthuang/agent-knock-knock/pull/266)
+acceptance record on 2026-08-30 included:
+
+- root fast tests: 1,462/1,462 passed;
+- connector fast tests: 23/23 passed;
+- root and connector TypeScript typechecks, architecture/evidence validators,
+  and connector package dry-run passed;
+- a real Claude Code 2.1.251 flow covering Send, approval callback, Pi native
+  approval, exact marker execution, completion callback, and delivered Status;
+- a real Codex flow in a clean isolated environment covering native
+  `agent_accepted`, exact marker execution, Unix Socket callback into Pi, and
+  durable high-confidence delivered Status.
+
+These are POC acceptance results, not a promise of compatibility with every
+future Pi, Codex, Claude Code, tmux, or Herdr release. Version
+`0.1.0-poc.2` is an npm prerelease and is distributed through the
+`next` dist-tag; it does not change the AKK main package or ClawHub artifact.
+
+## Deliberate POC limits
+
+The POC intentionally does not provide a standalone Supervisor, multi-Host
+leader election, cross-session or cross-branch callback migration, remote
+terminal access, Windows named pipes, configuration-driven auto-approval, or
+coding-agent `--yolo` adaptation. It controls only the Codex and Claude Code
+terminal surfaces already supported by AKK.

package/dist/src/backend-recovery-semantic.d.ts

@@ -0,0 +1,16 @@
+export type BackendRecoveryCommand = "renew" | "close" | "recover" | "retry-callback";
+export declare function isBackendTaskWatchId(value: unknown): value is string;
+export declare function normalizeBackendStatusTarget(params: Record<string, unknown>): Record<string, unknown>;
+/** Backend maintenance is anchored to one persisted task, never the thread's current task. */
+export declare function backendRecoveryTarget(params: Record<string, unknown>, command: BackendRecoveryCommand): string | undefined;
+export declare function backendRecoveryToolArgs(command: BackendRecoveryCommand, params: Record<string, unknown>, context: {
+    sessionKey?: unknown;
+}, options?: {
+    storeDir?: string;
+    codexHome?: string;
+    defaultMinutes?: number;
+}): string[] | undefined;
+/** Run before conversation routing, which must never reinterpret a backend recovery target. */
+export declare function assertBackendRecoveryCliTarget(command: string | undefined, options: Record<string, unknown>): void;
+/** Report observed delivery state without turning a retry attempt into a delivery receipt. */
+export declare function formatBackendRecoveryCommandResult(result: unknown, command: BackendRecoveryCommand): string | undefined;

package/dist/src/backend-recovery-semantic.js

@@ -0,0 +1,113 @@
+import { pushOptional, requiredControllerSessionKey, requiredString } from "./semantic-tool-arguments.js";
+import { isRecord, nonBlankString } from "./value-guards.js";
+const commands = new Set(["renew", "close", "recover", "retry-callback"]);
+const backendIdentity = /^(?:desktop|codex-cli):/u;
+const backendWatchPrefix = /^(?:desktop-watch|codex-cli-watch):/u;
+const backendWatch = /^(?:desktop-watch|codex-cli-watch):[A-Za-z0-9_-]{8,128}$/u;
+export function isBackendTaskWatchId(value) {
+    return typeof value === "string" && backendWatch.test(value);
+}
+export function normalizeBackendStatusTarget(params) {
+    if (typeof params.turn_id !== "string" || !backendWatchPrefix.test(params.turn_id.trim()))
+        return params;
+    if (Object.hasOwn(params, "watch_id") || Object.hasOwn(params, "conversation_id"))
+        throw new Error("status accepts exactly one of turn_id, conversation_id, or watch_id");
+    if (!backendWatch.test(params.turn_id))
+        throw new Error("status requires an exact backend Watch ID");
+    const { turn_id, ...rest } = params;
+    return { ...rest, watch_id: turn_id };
+}
+/** Backend maintenance is anchored to one persisted task, never the thread's current task. */
+export function backendRecoveryTarget(params, command) {
+    const targets = ["watch_id", "turn_id", "conversation_id"].filter(key => Object.hasOwn(params, key));
+    if (targets.length !== 1)
+        throw new Error(`${command} accepts exactly one of watch_id, turn_id or conversation_id`);
+    const field = targets[0];
+    const id = requiredString(params[field], field);
+    if (backendIdentity.test(id.trim()) || field === "conversation_id" && backendWatchPrefix.test(id.trim())) {
+        throw new Error(`${command} requires the exact backend watch_id or send-produced turn_id; conversation_id cannot select a backend task`);
+    }
+    if (backendWatchPrefix.test(id.trim()) || field === "watch_id" || command === "recover") {
+        if (!backendWatch.test(id))
+            throw new Error(`${command} requires an exact backend Watch ID`);
+        return id;
+    }
+    return undefined;
+}
+export function backendRecoveryToolArgs(command, params, context, options = {}) {
+    const id = backendRecoveryTarget(params, command);
+    if (!id) {
+        if (Object.hasOwn(params, "notification_id"))
+            throw new Error("notification_id is supported only for backend callback recovery");
+        return undefined;
+    }
+    const fields = command === "renew" ? ["minutes"] : command === "close" ? ["reason"] : command === "retry-callback" ? ["notification_id"] : [];
+    const allowed = new Set(["watch_id", "turn_id", ...fields]);
+    const extra = Object.keys(params).filter(key => !allowed.has(key));
+    if (extra.length)
+        throw new Error(`Unsupported backend ${command} parameters: ${extra.join(", ")}`);
+    const args = [command, "--watch", id, "--openclaw-session", requiredControllerSessionKey(context.sessionKey)];
+    pushOptional(args, "--store-dir", options.storeDir);
+    pushOptional(args, "--codex-home", options.codexHome);
+    if (command === "renew") {
+        const minutes = params.minutes ?? options.defaultMinutes;
+        if (minutes !== undefined) {
+            if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes <= 0)
+                throw new Error("minutes must be a positive number");
+            args.push("--minutes", String(minutes));
+        }
+    }
+    if (Object.hasOwn(params, "reason"))
+        args.push("--reason", requiredString(params.reason, "reason"));
+    if (Object.hasOwn(params, "notification_id"))
+        args.push("--notification-id", requiredString(params.notification_id, "notification_id"));
+    return args;
+}
+/** Run before conversation routing, which must never reinterpret a backend recovery target. */
+export function assertBackendRecoveryCliTarget(command, options) {
+    if (!command || !commands.has(command))
+        return;
+    const fields = ["watch", "turn", "conversation", "conversationId", "terminal", "session"];
+    const targets = fields.filter(key => Object.hasOwn(options, key));
+    const hasBackend = targets.some(key => typeof options[key] === "string" &&
+        (backendIdentity.test(options[key].trim()) || backendWatchPrefix.test(options[key].trim())));
+    if (command !== "recover" && !hasBackend && !Object.hasOwn(options, "watch")) {
+        if (Object.hasOwn(options, "notificationId"))
+            throw new Error("--notification-id is supported only for backend callback recovery");
+        return;
+    }
+    if (targets.length !== 1 || !["watch", "turn"].includes(targets[0]) || !backendWatch.test(String(options[targets[0]]))) {
+        throw new Error(`${command} requires exactly one --watch or --turn containing an exact backend Watch ID`);
+    }
+    requiredControllerSessionKey(options.openclawSession);
+    const fences = Object.keys(options).filter(key => /^expected/u.test(key));
+    if (fences.length)
+        throw new Error(`Backend ${command} does not accept terminal recovery fences: ${fences.join(", ")}`);
+    if (command !== "retry-callback" && Object.hasOwn(options, "notificationId")) {
+        throw new Error("--notification-id is supported only by retry-callback");
+    }
+    if (Object.hasOwn(options, "notificationId"))
+        requiredString(options.notificationId, "notification-id");
+}
+/** Report observed delivery state without turning a retry attempt into a delivery receipt. */
+export function formatBackendRecoveryCommandResult(result, command) {
+    if (!isRecord(result) || !backendWatch.test(String(result.watch_id)))
+        return undefined;
+    const fields = ["watch_id", "turn_id", "task_kind", "native_turn_id", "status", "management_state", "observation_state", "closed_at", "unwatched_at", "hard_timeout_at", "deadline_at"];
+    const lines = fields.flatMap(field => {
+        const value = nonBlankString(result[field]);
+        return value ? [`${field}: ${value}`] : [];
+    });
+    if (Array.isArray(result.callback_notifications)) {
+        for (const notification of result.callback_notifications) {
+            if (!isRecord(notification))
+                continue;
+            const id = nonBlankString(notification.notification_id) ?? nonBlankString(notification.id);
+            const status = nonBlankString(notification.status);
+            if (id && status)
+                lines.push(`callback ${id}: ${status}`);
+        }
+    }
+    return [`AKK backend ${command}.`, ...lines].join("\n");
+}
+//# sourceMappingURL=backend-recovery-semantic.js.map

package/dist/src/backend-recovery-semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-recovery-semantic.js","sourceRoot":"","sources":["../../src/backend-recovery-semantic.ts"],"names":[],"mappings":"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"}