@scotthuang/agent-knock-knock 0.12.11 → 0.12.13

package/dist/src/openclaw-plugin-helpers.js

@@ -1,4 +1,161 @@
 import path from "node:path";
+import { recordValue } from "./value-guards.js";
+const MODEL_FACING_PRIVATE_AUTHORITY_PARTS = [
+    ["expected", "terminal", "token"],
+    ["expected", "binding", "token"],
+    ["expected", "handoff", "token"],
+    ["candidate", "token"],
+    ["expected", "approval", "fingerprint"],
+    ["approval", "fingerprint"],
+    ["expected", "session", "revision"],
+    ["lifecycle", "binding", "token"],
+    ["binding", "token"],
+    ["binding", "id"],
+    ["binding", "generation"],
+    ["terminal", "binding", "id"],
+    ["terminal", "binding", "generation"],
+    ["selection", "handle"],
+    ["selection", "snapshot"],
+    ["selection", "scope"],
+    ["expected", "callback", "conversation", "id"],
+    ["expected", "callback", "session", "id"],
+    ["expected", "callback", "turn", "id"],
+    ["expected", "callback", "message", "id"],
+    ["expected", "callback", "openclaw", "session"]
+];
+// The optional separator accepts the three spellings that can be emitted by
+// old CLI/JSON diagnostics: snake_case, kebab-case, and camelCase.  These are
+// exact AKK authority names rather than generic words such as "token" or
+// "revision", so ordinary user and agent text remains intact.
+const MODEL_FACING_PRIVATE_AUTHORITY_NAME = `(?:${MODEL_FACING_PRIVATE_AUTHORITY_PARTS
+    .map((parts) => parts.join("[_-]?"))
+    .join("|")})`;
+const MODEL_FACING_SCALAR = `(?:"(?:\\\\.|[^"\\\\])*"|'(?:\\\\.|[^'\\\\])*'|` +
+    "`(?:\\\\.|[^`\\\\])*`|true|false|null|" +
+    `-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?|[^\\s,;}\\]]+)`;
+const MODEL_FACING_PRIVATE_AUTHORITY_JSON = new RegExp(`"${MODEL_FACING_PRIVATE_AUTHORITY_NAME}"\\s*:\\s*${MODEL_FACING_SCALAR}`, "giu");
+const MODEL_FACING_PRIVATE_AUTHORITY_CLI = new RegExp(`--${MODEL_FACING_PRIVATE_AUTHORITY_NAME}(?:=|\\s+)${MODEL_FACING_SCALAR}`, "giu");
+const MODEL_FACING_PRIVATE_AUTHORITY_ASSIGNMENT = new RegExp(`(^|[^A-Za-z0-9])${MODEL_FACING_PRIVATE_AUTHORITY_NAME}` +
+    `\\s*(?:=|:)\\s*${MODEL_FACING_SCALAR}`, "gimu");
+const MODEL_FACING_PRIVATE_AUTHORITY_LINE = new RegExp(`^\\s*(?:[-*]\\s*)?(?:` +
+    `(?:["']?${MODEL_FACING_PRIVATE_AUTHORITY_NAME}["']?\\s*(?:=|:))|` +
+    `(?:--${MODEL_FACING_PRIVATE_AUTHORITY_NAME}(?:=|\\s+)))`, "iu");
+const LEGACY_APPROVAL_TAIL_MARKER = "If the user approves, call `agent_knock_knock_approve`";
+const LEGACY_APPROVAL_TERMINAL_INSTRUCTION = "Do not use raw tmux, shell, or manual key presses for this approval. Do not approve without explicit user confirmation.";
+const MODEL_OPAQUE_AUTHORITY_FIELDS = new Set([
+    "acceptanceevidence",
+    "candidaterollouts",
+    "claudetranscriptanchor",
+    "codexopenrootrolloutinventory",
+    "codexrolloutacceptanceanchor",
+    "challenge",
+    "etag",
+    "expectedapprovalfingerprint",
+    "expectedcallbackconversationid",
+    "expectedcallbackmessageid",
+    "expectedcallbackopenclawsession",
+    "expectedcallbacksessionid",
+    "expectedcallbackturnid",
+    "generationid",
+    "livenativethreadid",
+    "nativesessiontakeover",
+    "nonce",
+    "proof",
+    "selectionhandle",
+    "selectionsnapshot",
+    "selectionscope",
+    "snapshotid"
+]);
+export function normalizeAkkModelFacingFieldName(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/gu, "");
+}
+export function isAkkModelFacingPrivateAuthorityField(key) {
+    const compact = normalizeAkkModelFacingFieldName(key);
+    return compact.endsWith("token") ||
+        compact.endsWith("fingerprint") ||
+        compact.endsWith("hash") ||
+        compact.endsWith("sha256") ||
+        compact.endsWith("digest") ||
+        compact.endsWith("revision") ||
+        compact.endsWith("revisions") ||
+        compact.endsWith("bindingid") ||
+        compact.endsWith("bindingids") ||
+        compact.endsWith("bindinggeneration") ||
+        compact.endsWith("bindinggenerations") ||
+        compact === "generation" ||
+        MODEL_OPAQUE_AUTHORITY_FIELDS.has(compact);
+}
+export function isAkkModelFacingDiagnosticField(key) {
+    if (!key)
+        return false;
+    const separated = key
+        .replace(/([a-z0-9])([A-Z])/gu, "$1_$2")
+        .toLowerCase();
+    return /(?:^|[_-])(?:reasons?|errors?|warnings?|diagnostics?)$/u.test(separated) || /(?:^|[_-])(?:error|warning|diagnostic)_message$/u.test(separated);
+}
+function sanitizeAkkModelFacingEmbeddedAuthorityText(value) {
+    return value
+        .replace(MODEL_FACING_PRIVATE_AUTHORITY_JSON, '"internal_authority":"[retained by AKK]"')
+        .replace(MODEL_FACING_PRIVATE_AUTHORITY_CLI, "[AKK internal authority omitted]")
+        .replace(MODEL_FACING_PRIVATE_AUTHORITY_ASSIGNMENT, (_match, prefix) => `${prefix}[AKK internal authority omitted]`);
+}
+/**
+ * Remove only AKK-generated pre-v18 authority instructions from callback/event
+ * text.  Exact authority-looking text outside one of these fixed machine-owned
+ * forms is business content and must remain byte-for-byte visible.
+ */
+export function sanitizeAkkModelFacingLegacyAuthorityInstructionText(value) {
+    const reviewOnly = stripAkkLegacyApprovalInstructionTail(value);
+    let machineAuthorityBlock = false;
+    return reviewOnly.split("\n").map((line) => {
+        const text = line.endsWith("\r") ? line.slice(0, -1) : line;
+        const carriageReturn = line.endsWith("\r") ? "\r" : "";
+        if (/^\s*(?:\[?AKK\]?\s+)?(?:approval|internal) authority\s*:?\s*$/iu
+            .test(text)) {
+            machineAuthorityBlock = true;
+            return line;
+        }
+        if (text.trim().length === 0) {
+            machineAuthorityBlock = false;
+            return line;
+        }
+        const fixedCommand = /^\s*(?:equivalent (?:user )?command|AKK (?:approval )?command)\s*:/iu
+            .test(text) && containsEmbeddedPrivateAuthority(text);
+        const blockAuthority = machineAuthorityBlock &&
+            containsEmbeddedPrivateAuthority(text);
+        if (fixedCommand || blockAuthority) {
+            return `${text.match(/^\s*/u)?.[0] ?? ""}` +
+                `[AKK internal authority omitted]${carriageReturn}`;
+        }
+        if (machineAuthorityBlock)
+            machineAuthorityBlock = false;
+        return line;
+    }).join("\n");
+}
+/** Remove only the exact legacy approval instruction appended by AKK. */
+export function stripAkkLegacyApprovalInstructionTail(value) {
+    const markerIndex = value.lastIndexOf(LEGACY_APPROVAL_TAIL_MARKER);
+    const markerSuffix = markerIndex === -1 ? "" : value.slice(markerIndex);
+    const fixedTail = markerIndex !== -1 && (markerSuffix.trimEnd().endsWith(LEGACY_APPROVAL_TERMINAL_INSTRUCTION) ||
+        markerSuffix.split(/\r?\n/u).some(isLegacyMachineAuthorityLine));
+    return fixedTail ? value.slice(0, markerIndex) : value;
+}
+function isLegacyMachineAuthorityLine(line) {
+    return containsEmbeddedPrivateAuthority(line) && (MODEL_FACING_PRIVATE_AUTHORITY_LINE.test(line) ||
+        /^\s*(?:equivalent (?:user )?command|AKK (?:approval )?command)\s*:/iu
+            .test(line));
+}
+function containsEmbeddedPrivateAuthority(value) {
+    return sanitizeAkkModelFacingEmbeddedAuthorityText(value) !== value;
+}
+export function sanitizeAkkModelFacingDiagnosticText(message) {
+    const sanitized = sanitizeAkkModelFacingEmbeddedAuthorityText(message);
+    if (sanitized !== message ||
+        /(?:\bexpected\s+(?:session\s+)?revision\b|\bactual\s+(?:session\s+)?revision\b|\b(?:terminal|binding|handoff|candidate)\s+token\b|\bapproval\s+fingerprint\b|\bbinding\s+(?:id|generation)\b|\bcompare-and-swap\b|\bCAS\b)/iu.test(message)) {
+        return "AKK's private authority changed or could not be verified. Refresh AKK list/status and retry only the currently advertised semantic action.";
+    }
+    return sanitized;
+}
 export const AKK_CALLBACK_METHOD = "agent-knock-knock.callback";
 export function parseAkkCommand(args) {
     const input = String(args ?? "").trim();
@@ -15,6 +172,14 @@ export function parseAkkCommand(args) {
     }
     const { token, rest } = takeToken(input);
     const action = token.toLowerCase();
+    const lifecycleCommand = parseAkkLifecycleCommand(action, rest);
+    if (lifecycleCommand) {
+        return lifecycleCommand;
+    }
+    const turnCommand = parseAkkTurnCommand(action, rest);
+    return turnCommand ?? { action: "delegate", request: input };
+}
+function parseAkkLifecycleCommand(action, rest) {
     if (action === "list" || action === "ls" || action === "tasks") {
         return { action: "list" };
     }
@@ -24,6 +189,23 @@ export function parseAkkCommand(args) {
         }
         return { action: "doctor" };
     }
+    if (action === "watch") {
+        const usage = "Usage: /akk watch <exact-terminal-id>";
+        const { token: terminalId, rest: extra } = takeRequiredToken(rest, usage);
+        assertExactTerminalId(terminalId, usage);
+        if (extra.trim()) {
+            throw new Error(usage);
+        }
+        return { action: "watch", terminalId };
+    }
+    if (action === "unwatch") {
+        const usage = "Usage: /akk unwatch <watch-id>";
+        const { token: watchId, rest: extra } = takeRequiredToken(rest, usage);
+        if (extra.trim() || !isTerminalWatchId(watchId)) {
+            throw new Error(usage);
+        }
+        return { action: "unwatch", watchId };
+    }
     if (action === "threads" || action === "list-resumable-threads") {
         const usage = "Usage: /akk threads <exact-terminal-id>";
         const { token: terminalId, rest: extra } = takeRequiredToken(rest, usage);
@@ -44,7 +226,7 @@ export function parseAkkCommand(args) {
     }
     if (action === "resume-thread") {
         const usage = "Usage: /akk resume-thread <exact-terminal-id> " +
-            "[native-thread-uuid|previous|刚才那个|number|@short-id|snapshot-handle]";
+            "[native-thread-uuid|previous|刚才那个|number|@short-id]";
         const { token: terminalId, rest: nativeInput } = takeRequiredToken(rest, usage);
         assertExactTerminalId(terminalId, usage);
         const { token: selectionInput, rest: extra } = takeToken(nativeInput);
@@ -62,12 +244,17 @@ export function parseAkkCommand(args) {
                 : {})
         };
     }
+    return undefined;
+}
+function parseAkkTurnCommand(action, rest) {
     if (action === "status" || action === "show") {
         const { token: turnId, rest: extra } = takeToken(rest);
         if (extra.trim()) {
-            throw new Error("Usage: /akk status [turn-selector]");
+            throw new Error("Usage: /akk status [turn-selector|terminal-watch-id]");
         }
-        return { action: "status", turnId: turnId || undefined };
+        return turnId && isTerminalWatchId(turnId)
+            ? { action: "status", watchId: turnId }
+            : { action: "status", turnId: turnId || undefined };
     }
     if (action === "describe" || action === "summary" || action === "about") {
         throw new Error("AKK describe was removed; use /akk status [turn-selector]");
@@ -87,15 +274,13 @@ export function parseAkkCommand(args) {
         throw new Error("AKK reply syntax changed; use /akk respond <turn-selector>: <answer>");
     }
     if (action === "approve") {
-        const { token: turnId, rest: approvalInput } = takeRequiredToken(rest, "Usage: /akk approve <turn-selector> --expected-approval-fingerprint <fingerprint>");
-        const approval = /^--expected-approval-fingerprint\s+(\S+)$/u.exec(approvalInput.trim());
-        if (!approval) {
-            throw new Error("Usage: /akk approve <turn-selector> --expected-approval-fingerprint <fingerprint>");
+        const { token: turnId, rest: approvalInput } = takeRequiredToken(rest, "Usage: /akk approve <turn-selector>");
+        if (approvalInput.trim()) {
+            throw new Error("Usage: /akk approve <turn-selector>");
         }
         return {
             action: "approve",
-            turnId,
-            expectedApprovalFingerprint: approval[1]
+            turnId
         };
     }
     if (action === "cancel" || action === "stop") {
@@ -115,40 +300,43 @@ export function parseAkkCommand(args) {
         return { action: "retry-callback", turnId };
     }
     if (action === "close" || action === "done") {
-        const usage = "Usage: /akk close <turn-selector> " +
-            "[(--expected-message-id <id> | --expected-transition-id <id>)] [reason]";
-        const { token: turnId, rest: reasonInput } = takeRequiredToken(rest, usage);
-        const recoveryInput = reasonInput.trim();
-        const recoveryFlags = recoveryInput.match(/(?:^|\s)--expected-(?:message|transition)-id(?=\s|$)/gu) ?? [];
-        if (recoveryFlags.length > 1) {
-            throw new Error(`${usage}; expected-message-id and expected-transition-id are mutually exclusive`);
-        }
-        const recovery = /^--expected-(message|transition)-id\s+(\S+)(?:\s+([\s\S]*))?$/u.exec(recoveryInput);
-        if (recoveryFlags.length === 1 && !recovery) {
-            throw new Error(usage);
-        }
-        const recoveryKind = recovery?.[1];
-        const recoveryId = recovery?.[2];
-        const recoveryReason = recovery?.[3]?.trim();
-        const defaultRecoveryReason = recoveryKind === "transition"
-            ? "Native-thread lifecycle transition recovered from /akk command"
-            : "Orphaned terminal dispatch resolved from /akk command";
-        return {
-            action: "close",
-            turnId,
-            reason: recoveryReason ||
-                (recovery
-                    ? defaultRecoveryReason
-                    : recoveryInput || "Closed from /akk command"),
-            ...(recoveryKind === "message" && recoveryId
-                ? { expectedMessageId: recoveryId }
-                : {}),
-            ...(recoveryKind === "transition" && recoveryId
-                ? { expectedTransitionId: recoveryId }
-                : {})
-        };
+        return parseAkkCloseCommand(rest);
+    }
+    return undefined;
+}
+function parseAkkCloseCommand(rest) {
+    const usage = "Usage: /akk close <turn-selector> " +
+        "[(--expected-message-id <id> | --expected-transition-id <id>)] [reason]";
+    const { token: turnId, rest: reasonInput } = takeRequiredToken(rest, usage);
+    const recoveryInput = reasonInput.trim();
+    const recoveryFlags = recoveryInput.match(/(?:^|\s)--expected-(?:message|transition)-id(?=\s|$)/gu) ?? [];
+    if (recoveryFlags.length > 1) {
+        throw new Error(`${usage}; expected-message-id and expected-transition-id are mutually exclusive`);
+    }
+    const recovery = /^--expected-(message|transition)-id\s+(\S+)(?:\s+([\s\S]*))?$/u.exec(recoveryInput);
+    if (recoveryFlags.length === 1 && !recovery) {
+        throw new Error(usage);
     }
-    return { action: "delegate", request: input };
+    const recoveryKind = recovery?.[1];
+    const recoveryId = recovery?.[2];
+    const recoveryReason = recovery?.[3]?.trim();
+    const defaultRecoveryReason = recoveryKind === "transition"
+        ? "Native-thread lifecycle transition recovered from /akk command"
+        : "Orphaned terminal dispatch resolved from /akk command";
+    return {
+        action: "close",
+        turnId,
+        reason: recoveryReason ||
+            (recovery
+                ? defaultRecoveryReason
+                : recoveryInput || "Closed from /akk command"),
+        ...(recoveryKind === "message" && recoveryId
+            ? { expectedMessageId: recoveryId }
+            : {}),
+        ...(recoveryKind === "transition" && recoveryId
+            ? { expectedTransitionId: recoveryId }
+            : {})
+    };
 }
 export function akkUsageText() {
     return [
@@ -158,21 +346,26 @@ export function akkUsageText() {
         "/akk claude: <request>",
         "/akk <session-selector>: <message>",
         "/akk list",
+        "/akk watch <exact-terminal-id>",
+        "/akk unwatch <watch-id>",
         "/akk threads <exact-terminal-id>",
         "/akk new-thread <exact-terminal-id>",
         "/akk clear-thread <exact-terminal-id>",
-        "/akk resume-thread <exact-terminal-id> [uuid|previous|number|@short-id|snapshot-handle]",
+        "/akk resume-thread <exact-terminal-id> [uuid|previous|number|@short-id]",
         "/akk doctor",
-        "/akk status [turn-selector]",
+        "/akk status [turn-selector|terminal-watch-id]",
         "/akk respond <turn-selector>: <answer>",
-        "/akk approve <turn-selector> --expected-approval-fingerprint <fingerprint>",
+        "/akk approve <turn-selector>",
         "/akk cancel <turn-selector>"
     ].join("\n");
 }
 export function formatAkkListCommandResult(result) {
     const terminals = arrayValue(result.terminals);
+    const terminalWatches = arrayValue(result.terminal_watches);
     const unavailableManagedTurns = arrayValue(result.unavailable_managed_turns);
-    if (terminals.length === 0 && unavailableManagedTurns.length === 0) {
+    if (terminals.length === 0 &&
+        terminalWatches.length === 0 &&
+        unavailableManagedTurns.length === 0) {
         return "AKK found no live terminals or unavailable managed turns.";
     }
     const terminalLines = terminals.slice(0, 20).flatMap((terminal) => {
@@ -192,11 +385,15 @@ export function formatAkkListCommandResult(result) {
             "new_thread",
             "resume_thread"
         ].some((name) => Object.hasOwn(availableActions, name));
+        const hasWatchAction = Object.hasOwn(availableActions, "watch");
         return [
             `- ${formatTerminalLine(terminal)}`,
             ...(hasLifecycleAction && terminalId
                 ? [`  lifecycle terminal_id: ${terminalId}`]
                 : []),
+            ...(hasWatchAction && terminalId
+                ? [`  AKK Watch available: /akk watch ${terminalId} — monitor this human-started task and receive attention/completion callbacks without polling.`]
+                : []),
             ...(sessionId || sessionShortRef
                 ? [`  AKK session: ${sessionShortRef ?? sessionId}`]
                 : []),
@@ -231,11 +428,21 @@ export function formatAkkListCommandResult(result) {
             ...(recovery ? [`  recovery: ${recovery}`] : [])
         ];
     });
+    const watchLines = terminalWatches.slice(0, 20).flatMap((watch) => [
+        `- ${formatTerminalWatchLine(watch)}`,
+        ...formatAvailableActions("  actions", watch)
+    ]);
+    const heading = terminalWatches.length > 0
+        ? `AKK terminals (${terminals.length} live, ${terminalWatches.length} terminal watches, ${unavailableManagedTurns.length} unavailable managed turns):`
+        : `AKK terminals (${terminals.length} live, ${unavailableManagedTurns.length} unavailable managed turns):`;
     return [
-        `AKK terminals (${terminals.length} live, ${unavailableManagedTurns.length} unavailable managed turns):`,
+        heading,
         ...(terminalLines.length > 0
             ? ["live terminals:", ...terminalLines]
             : []),
+        ...(watchLines.length > 0
+            ? ["terminal watches:", ...watchLines]
+            : []),
         ...(unavailableManagedTurns.length > 0
             ? [
                 "unavailable managed turns:",
@@ -247,6 +454,63 @@ export function formatAkkListCommandResult(result) {
             : [])
     ].join("\n");
 }
+export function formatAkkWatchCommandResult(result) {
+    const watch = terminalWatchRecord(result);
+    return [
+        "AKK Terminal Watch started:",
+        `watch: ${nonEmptyString(watch.watch_id) ?? "unknown"}`,
+        `terminal: ${nonEmptyString(watch.terminal_id) ?? "unknown"}`,
+        `agent: ${nonEmptyString(watch.agent) ?? "unknown"}`,
+        `status: ${nonEmptyString(watch.status) ?? "watching"}`,
+        "AKK did not send or adopt this task; it is observing work the human started in the terminal."
+    ].join("\n");
+}
+export function formatAkkUnwatchCommandResult(result) {
+    const watch = terminalWatchRecord(result);
+    return [
+        "AKK Terminal Watch stopped:",
+        `watch: ${nonEmptyString(watch.watch_id) ?? "unknown"}`,
+        `status: ${nonEmptyString(watch.status) ?? "cancelled"}`,
+        "The terminal and its task were not interrupted."
+    ].join("\n");
+}
+export function formatAkkWatchStatusCommandResult(result) {
+    const watch = terminalWatchRecord(result);
+    const settlement = recordValue(watch.settlement) ?? {};
+    const reason = nonEmptyString(settlement.reason_code) ??
+        nonEmptyString(watch.reason);
+    const completionText = nonEmptyString(settlement.completion_text);
+    return [
+        "AKK Terminal Watch status:",
+        `watch: ${nonEmptyString(watch.watch_id) ?? "unknown"}`,
+        `terminal: ${nonEmptyString(watch.terminal_id) ?? "unknown"}`,
+        `agent: ${nonEmptyString(watch.agent) ?? "unknown"}`,
+        `status: ${nonEmptyString(watch.status) ?? "unknown"}`,
+        ...(reason
+            ? [`reason: ${reason}`]
+            : []),
+        ...(completionText
+            ? [`completion: ${truncateText(completionText, 500)}`]
+            : []),
+        "This is observed external work; AKK did not send or adopt the task."
+    ].join("\n");
+}
+export function formatAkkTerminalWatchHint(result) {
+    const hint = recordValue(result.terminal_watch_hint);
+    if (hint?.kind !== "terminal_watch_discovery" ||
+        hint.available_action_required !== true) {
+        return [];
+    }
+    const command = nonEmptyString(hint.command);
+    const instruction = nonEmptyString(hint.instruction);
+    if (!command || !instruction) {
+        return [];
+    }
+    return [
+        `AKK Watch available: ${command}`,
+        `next: ${instruction}`
+    ];
+}
 export function formatAkkRespondCommandResult(result) {
     const conversation = recordValue(result.conversation) ?? {};
     const compatibilityId = nonEmptyString(conversation.conversation_id) ??
@@ -342,7 +606,6 @@ export function formatAkkThreadsCommandResult(result) {
         const nativeThreadId = nonEmptyString(thread.native_thread_id) ?? "unknown";
         const selectionNumber = finiteNumber(thread.selection_number);
         const shortId = nonEmptyString(thread.short_id);
-        const selectionHandle = nonEmptyString(thread.selection_handle);
         const status = thread.resumable === true
             ? "resumable"
             : nonEmptyString(thread.unavailable_reason) ?? "unavailable";
@@ -350,11 +613,10 @@ export function formatAkkThreadsCommandResult(result) {
             nonEmptyString(thread.title),
             nonEmptyString(thread.preview)
         ].filter((value) => Boolean(value)).join(" · ");
-        const selector = selectionNumber !== undefined || shortId || selectionHandle
+        const selector = selectionNumber !== undefined || shortId
             ? [
                 selectionNumber !== undefined ? `${selectionNumber}.` : undefined,
-                shortId,
-                selectionHandle ? `[${selectionHandle}]` : undefined
+                shortId
             ].filter(Boolean).join(" ")
             : `- ${nativeThreadId}`;
         const previousMarker = nativeThreadId === previousNativeThreadId
@@ -383,7 +645,7 @@ export function formatAkkThreadsCommandResult(result) {
         ...(resumableCount > 0
             ? [
                 `next: /akk resume-thread ${terminalId} <native-thread-uuid>`,
-                `shortcuts: /akk resume-thread ${terminalId} <number|@short-id|snapshot-handle>`,
+                `shortcuts: /akk resume-thread ${terminalId} <number|@short-id>`,
                 ...(previousNativeThreadId
                     ? [`previous: /akk resume-thread ${terminalId} previous`]
                     : []),
@@ -407,7 +669,9 @@ export function formatAkkThreadTransitionCommandResult(result) {
                 ? [`transition: ${nonEmptyString(result.transition_id)}`]
                 : []),
             ...(nonEmptyString(result.reason)
-                ? [`reason: ${nonEmptyString(result.reason)}`]
+                ? [
+                    `reason: ${sanitizeAkkModelFacingDiagnosticText(nonEmptyString(result.reason) ?? "")}`
+                ]
                 : []),
             "No AKK Turn was created.",
             "Next: do not retry automatically; refresh /akk list and use only its exact lifecycle recovery action."
@@ -433,9 +697,6 @@ export function formatAkkThreadTransitionCommandResult(result) {
             ]
             : []),
         `native thread: ${nonEmptyString(result.native_thread_id) ?? "unknown"}`,
-        ...(finiteNumber(result.binding_generation) !== undefined
-            ? [`binding generation: ${finiteNumber(result.binding_generation)}`]
-            : []),
         "No AKK Turn was created. The next ordinary send creates the first Turn in this native context."
     ].join("\n");
 }
@@ -457,6 +718,20 @@ export function buildAkkCommandCliArgs(command, config, context = {}) {
     switch (command.action) {
         case "list":
             return withOptionalArgs(["list", "--reconcile"], ["--store-dir", storeDir], ["--idle-timeout-minutes", idleTimeoutMinutes]);
+        case "watch": {
+            const openclawSession = nonEmptyString(context.sessionKey) ??
+                "agent:main:main";
+            return withOptionalArgs([
+                "watch-terminal",
+                "--terminal",
+                command.terminalId
+            ], ["--store-dir", storeDir], [
+                "--hard-timeout-minutes",
+                finiteNumberString(config.agentHardTimeoutMinutes)
+            ], ["--openclaw-session", openclawSession], ["--openclaw-bin", nonEmptyString(config.openclawBin)]);
+        }
+        case "unwatch":
+            return withOptionalArgs(["unwatch-terminal", "--watch", command.watchId], ["--store-dir", storeDir]);
         case "list-resumable-threads":
             return withOptionalArgs([
                 "list-resumable-threads",
@@ -505,17 +780,6 @@ export function buildAkkCommandCliArgs(command, config, context = {}) {
                     requiredSelectionScope(context.selectionScope)
                 ], ["--store-dir", storeDir], ["--codex-home", codexHome]);
             }
-            if (command.selection.kind === "snapshot-handle") {
-                return withOptionalArgs([
-                    "resume-thread",
-                    "--terminal",
-                    command.terminalId,
-                    "--selection-handle",
-                    command.selection.selectionHandle,
-                    "--selection-scope",
-                    requiredSelectionScope(context.selectionScope)
-                ], ["--store-dir", storeDir], ["--codex-home", codexHome]);
-            }
             return withOptionalArgs([
                 "resume-thread",
                 "--terminal",
@@ -528,6 +792,9 @@ export function buildAkkCommandCliArgs(command, config, context = {}) {
                 requiredCandidateToken(context.candidateToken)
             ], ["--store-dir", storeDir], ["--codex-home", codexHome]);
         case "status":
+            if (command.watchId) {
+                return withOptionalArgs(["watch-status", "--watch", command.watchId], ["--store-dir", storeDir]);
+            }
             return withOptionalArgs([
                 "status",
                 "--reconcile",
@@ -556,13 +823,9 @@ export function buildAkkCommandCliArgs(command, config, context = {}) {
                 command.message
             ], ["--store-dir", storeDir]);
         case "approve":
-            return withOptionalArgs([
-                "approve",
-                "--turn",
-                command.turnId,
-                "--expected-approval-fingerprint",
-                command.expectedApprovalFingerprint
-            ], ["--store-dir", storeDir]);
+            // The OpenClaw command adapter resolves the current private approval
+            // authority immediately before invoking the CLI.
+            return undefined;
         case "renew":
             return withOptionalArgs(["renew", "--turn", command.turnId], [
                 "--minutes",
@@ -583,6 +846,9 @@ export function buildAkkCommandCliArgs(command, config, context = {}) {
             ], ["--expected-message-id", command.expectedMessageId], ["--expected-transition-id", command.expectedTransitionId], ["--store-dir", storeDir]);
     }
 }
+function isTerminalWatchId(value) {
+    return /^terminal-watch-[A-Za-z0-9._:-]+$/u.test(value);
+}
 function parseSelectorMessage(input) {
     const match = /^((?:(?:codex|claude):latest|only|latest|codex|claude|@[0-9a-f]+))\s*:\s*([\s\S]*)$/iu.exec(input);
     const message = match?.[2]?.trim();
@@ -631,9 +897,6 @@ function parseAkkResumeSelection(value, usage) {
     if (/^@[a-f0-9]{8,32}$/u.test(normalized)) {
         return { kind: "short-id", shortId: normalized };
     }
-    if (/^rs_[A-Za-z0-9_-]{22}:[1-9][0-9]*$/u.test(value)) {
-        return { kind: "snapshot-handle", selectionHandle: value };
-    }
     throw new Error(`${usage}; use a complete UUID or a selection exactly returned by /akk threads`);
 }
 function requiredExpectedBindingToken(value) {
@@ -715,10 +978,10 @@ function arrayValue(value) {
         ? value.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item))
         : [];
 }
-function recordValue(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : undefined;
+function terminalWatchRecord(result) {
+    return recordValue(result.watch) ??
+        recordValue(result.terminal_watch) ??
+        result;
 }
 function finiteNumber(value) {
     return typeof value === "number" && Number.isFinite(value)
@@ -762,6 +1025,16 @@ function formatManagedTurnLine(turn) {
         truncateText(context, 90)
     ].filter(Boolean).join(" | ");
 }
+function formatTerminalWatchLine(watch) {
+    return [
+        nonEmptyString(watch.short_ref) ??
+            nonEmptyString(watch.watch_id) ??
+            "unknown",
+        nonEmptyString(watch.agent) ?? "agent",
+        nonEmptyString(watch.status) ?? "unknown",
+        nonEmptyString(watch.terminal_id)
+    ].filter(Boolean).join(" | ");
+}
 function formatAvailableActions(label, resource) {
     const actions = recordValue(resource.available_actions);
     if (!actions) {
@@ -769,6 +1042,8 @@ function formatAvailableActions(label, resource) {
     }
     const displayedActions = new Set([
         "send",
+        "watch",
+        "unwatch",
         "respond",
         "status",
         "approve",