@scotthuang/agent-knock-knock 0.3.0-beta.1 → 0.3.0

package/dist/src/cli.js

@@ -14,7 +14,7 @@ import { defaultClaudeSettingsPath, loadTrustedClaudeTokenjuiceLaunchers } from
 import { CodexLocalSessionProvider } from "./codex-local-session-provider.js";
 import { CodexStoreAdapter } from "./codex-store-adapter.js";
 import { applyMessageToConversation, budgetAction, createConversation, createMessage, executorForConversation, extractStructuredMessage, parseMessageJson, resolveExecutor } from "./protocol.js";
-import { EXECUTOR_KINDS, acpxCommandForExecutor, executorDefinitionForKind, modelEnvForExecutor, normalizeModelForExecutor, proxyEnvForExecutor } from "./executors.js";
+import { EXECUTOR_KINDS, acpxCommandForExecutor, executorDefinitionForKind, isExecutorKind, modelEnvForExecutor, normalizeModelForExecutor, proxyEnvForExecutor } from "./executors.js";
 import { executorBootstrapPrompt } from "./bootstrap.js";
 import { redactString, writeRuntimeLog } from "./runtime-log.js";
 import { formatTranscript, readNdjsonLog } from "./transcript.js";
@@ -23,17 +23,30 @@ import { planFork, planTakeover } from "./session-takeover-planner.js";
 import { StaticTerminalControlProvider, TmuxTerminalControlProvider, terminalPaneContainsProcess } from "./terminal-control-provider.js";
 import { parseTerminalConversationId } from "./terminal-agent-adapter.js";
 import { createProductionTerminalAgentRegistry } from "./terminal-agent-registry.js";
-import { StaticTerminalProcessSource, SystemTerminalProcessSource } from "./terminal-process-source.js";
+import { parseProcessElapsedSeconds, StaticTerminalProcessSource, SystemTerminalProcessSource } from "./terminal-process-source.js";
 import { TerminalAgentBridge } from "./terminal-agent-bridge.js";
 import { evaluateApprovalPolicy } from "./approval-policy.js";
-import { evaluateDoctorCapabilities } from "./doctor-capabilities.js";
+import { evaluateDoctorCapabilities, runDoctorCapabilityProbes } from "./doctor-capabilities.js";
+import { runOpenClawChainDiagnostics } from "./openclaw-doctor.js";
+import { resolveSessionSelector, sessionShortRef } from "./session-selector.js";
 const DEFAULT_IDLE_TIMEOUT_MINUTES = 10080;
 const DEFAULT_AGENT_TIMEOUT_MINUTES = 60;
 const DEFAULT_AGENT_HARD_TIMEOUT_MINUTES = 720;
 const DEFAULT_MONITOR_POLL_INTERVAL_MS = 5000;
 const CLAUDE_SCREEN_APPROVAL_TTL_MS = 10 * 60 * 1000;
 const CALLBACK_DELIVERY_TIMEOUT_MS = 30_000;
+const CALLBACK_AGENT_WAIT_TIMEOUT_MS = 20_000;
+const CALLBACK_AGENT_WAIT_CLI_TIMEOUT_MS = 25_000;
+const CALLBACK_AGENT_WAIT_PROCESS_TIMEOUT_MS = 30_000;
 const CALLBACK_RETRY_DELAYS_MS = [5000, 15000, 60000, 60000];
+const TERMINAL_BRIDGE_SUPERSEDE_STATUSES = new Set([
+    "created",
+    "running",
+    "waiting_for_agent",
+    "waiting_for_openclaw",
+    "stalled",
+    "cancelling"
+]);
 const TERMINAL_BRIDGE_MONITOR_LOCK_VERSION = 1;
 const MINIMUM_NODE_VERSION = "22.14.0";
 const PRIVATE_LOCK_FILE_MODE = 0o600;
@@ -57,6 +70,18 @@ const CONVERSATION_STATUSES = new Set([
     "cancelled",
     "cancelling"
 ]);
+const SESSION_SELECTOR_COMMANDS = new Set([
+    "status",
+    "describe",
+    "summary",
+    "send",
+    "approve",
+    "cancel",
+    "renew",
+    "retry-callback",
+    "recover",
+    "close"
+]);
 class InlineCodexSessionAdapter {
     threads;
     processes;
@@ -113,6 +138,7 @@ catch (error) {
     process.exit(1);
 }
 async function runCommand(commandName, options) {
+    await resolveConversationSelectorOption(commandName, options);
     if (commandName === "help" || commandName === "--help" || commandName === "-h") {
         usage();
     }
@@ -196,7 +222,24 @@ async function runCommand(commandName, options) {
 function runInstallOpenClaw(options) {
     const root = packageRootDir();
     const skillOnly = options.skillOnly === true;
-    const needsOpenClaw = !skillOnly || options.noRestart !== true;
+    const workspace = options.workspace === undefined
+        ? undefined
+        : canonicalWorkspace(options.workspace);
+    const defaultAgent = optionalExecutorKind(options.defaultAgent);
+    const selectedMode = options.mode === undefined
+        ? undefined
+        : parseDoctorMode(options.mode);
+    if (selectedMode === "tmux" && defaultAgent === "cursor") {
+        throw new Error("--default-agent cursor requires --mode acpx or --mode all");
+    }
+    if (skillOnly &&
+        (workspace !== undefined ||
+            defaultAgent !== undefined ||
+            selectedMode !== undefined ||
+            options.verify === true)) {
+        throw new Error("--skill-only cannot be combined with --workspace, --default-agent, --mode, or --verify");
+    }
+    const needsOpenClaw = !skillOnly || options.noRestart !== true || options.verify === true;
     const openclawBin = needsOpenClaw
         ? options.openclawBin ?? resolveExecutable("openclaw")
         : options.openclawBin;
@@ -210,12 +253,35 @@ function runInstallOpenClaw(options) {
             path: root,
             mode: pluginInstall.mode
         });
-        runCheckedCommand(openclawBin, ["plugins", "enable", "agent-knock-knock"], {
-            label: "openclaw plugins enable"
-        });
+        const configOperations = [
+            {
+                path: "plugins.entries.agent-knock-knock.enabled",
+                value: true
+            },
+            ...(workspace === undefined
+                ? []
+                : [{
+                        path: "plugins.entries.agent-knock-knock.config.workspace",
+                        value: workspace
+                    }]),
+            ...(defaultAgent === undefined
+                ? []
+                : [{
+                        path: "plugins.entries.agent-knock-knock.config.defaultAgent",
+                        value: defaultAgent
+                    }]),
+            ...(selectedMode === undefined
+                ? []
+                : [{
+                        path: "plugins.entries.agent-knock-knock.config.mode",
+                        value: selectedMode
+                    }])
+        ];
+        runCheckedCommand(openclawBin, ["config", "set", "--batch-json", JSON.stringify(configOperations)], { label: "openclaw config set" });
         steps.push({
-            name: "plugin_enabled",
-            plugin: "agent-knock-knock"
+            name: "plugin_configured",
+            plugin: "agent-knock-knock",
+            updated: configOperations.map((operation) => operation.path)
         });
     }
     fs.mkdirSync(path.dirname(skillDest), { recursive: true });
@@ -232,17 +298,105 @@ function runInstallOpenClaw(options) {
             name: "gateway_restarted"
         });
     }
+    const pendingRestart = !skillOnly && options.noRestart === true;
+    const verification = options.verify === true
+        ? buildDoctorReport({
+            ...options,
+            openclawBin,
+            ...(workspace ? { workspace } : {}),
+            mode: selectedMode ?? "all"
+        })
+        : undefined;
+    const ready = verification
+        ? verification.ok === true && !pendingRestart
+        : false;
+    const nextActions = installNextActions({
+        pendingRestart,
+        verification,
+        mode: selectedMode ?? "all",
+        agent: defaultAgent ?? "codex"
+    });
     printJson({
         installed: true,
+        ready,
+        pending_restart: pendingRestart,
         mode: skillOnly ? "skill_only" : "full",
+        execution_mode: selectedMode ?? null,
+        default_agent: defaultAgent ?? null,
+        workspace: workspace ?? null,
         package_root: root,
         openclaw_bin: openclawBin ?? null,
         steps,
-        next: options.noRestart === true
-            ? "Restart the OpenClaw Gateway before using Agent Knock Knock."
-            : "Agent Knock Knock is installed. Try: AKK list"
+        ...(verification ? { verification } : {}),
+        next_actions: nextActions
     });
 }
+function canonicalWorkspace(value) {
+    const requested = path.resolve(String(required(value, "--workspace is required")));
+    let canonical;
+    let stat;
+    try {
+        canonical = fs.realpathSync(requested);
+        stat = fs.statSync(canonical);
+    }
+    catch {
+        throw new Error(`--workspace does not exist: ${requested}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`--workspace must be a directory: ${requested}`);
+    }
+    return canonical;
+}
+function optionalExecutorKind(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = String(value).trim().toLowerCase();
+    if (!isExecutorKind(normalized)) {
+        throw new Error(`--default-agent must be one of: ${EXECUTOR_KINDS.join(", ")}`);
+    }
+    return normalized;
+}
+function installNextActions({ pendingRestart, verification, mode, agent }) {
+    if (pendingRestart) {
+        return [
+            {
+                action: "apply_plugin_changes",
+                command: "openclaw gateway restart"
+            },
+            {
+                action: "verify",
+                command: `agent-knock-knock doctor --mode ${mode}`
+            }
+        ];
+    }
+    if (verification && verification.ok !== true) {
+        const chain = isRecord(verification.openclaw) ? verification.openclaw : {};
+        const checks = Array.isArray(chain.checks) ? chain.checks : [];
+        const remediation = checks.flatMap((check) => isRecord(check) && Array.isArray(check.remediation)
+            ? check.remediation.filter((command) => typeof command === "string")
+            : []);
+        return [...new Set(remediation)].map((command) => ({
+            action: "repair",
+            command
+        }));
+    }
+    if (!verification) {
+        return [{
+                action: "verify",
+                command: `agent-knock-knock doctor --mode ${mode}`
+            }];
+    }
+    return mode === "tmux"
+        ? [{
+                action: "start_agent",
+                command: `tmux new -s akk-${agent} ${agent}`
+            }]
+        : [{
+                action: "delegate",
+                command: `/akk ${agent} <task>`
+            }];
+}
 async function runClaudeHook(options) {
     const rawInput = fs.readFileSync(0, "utf8");
     let input;
@@ -321,18 +475,41 @@ function installOpenClawPlugin(openclawBin, root) {
     return { mode: "replaced" };
 }
 function runDoctor(options) {
-    const commands = ["node", "openclaw", "tmux", "acpx", "codex", "claude", "cursor"];
-    const checks = commands.map((commandName) => {
-        const check = executableCheck(commandName);
-        return commandName === "node"
-            ? {
-                ...check,
-                version: process.versions.node,
-                version_supported: versionAtLeast(process.versions.node, MINIMUM_NODE_VERSION),
-                minimum_version: MINIMUM_NODE_VERSION
-            }
-            : check;
-    });
+    const report = buildDoctorReport(options);
+    printJson(report);
+    if (!report.ok) {
+        process.exitCode = 1;
+    }
+}
+function buildDoctorReport(options) {
+    const mode = parseDoctorMode(options.mode ?? "all");
+    const timeoutMs = options.timeoutMs === undefined
+        ? undefined
+        : positiveMilliseconds(options.timeoutMs, "--timeout-ms");
+    const openclawBin = String(options.openclawBin ?? resolveOptionalExecutable("openclaw"));
+    const executables = {
+        openclaw: openclawBin,
+        ...(options.tmuxBin ? { tmux: String(options.tmuxBin) } : {}),
+        ...(options.acpxBin ? { acpx: String(options.acpxBin) } : {}),
+        ...(options.codexBin ? { codex: String(options.codexBin) } : {}),
+        ...(options.claudeBin ? { claude: String(options.claudeBin) } : {}),
+        ...(options.cursorBin ? { cursor: String(options.cursorBin) } : {})
+    };
+    const checks = [
+        {
+            command: "node",
+            status: "ok",
+            available: true,
+            executable: process.execPath,
+            version: process.versions.node,
+            version_supported: versionAtLeast(process.versions.node, MINIMUM_NODE_VERSION),
+            minimum_version: MINIMUM_NODE_VERSION
+        },
+        ...runDoctorCapabilityProbes({
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            executables
+        }, mode)
+    ];
     const root = packageRootDir();
     const packageFiles = [
         "dist/src/cli.js",
@@ -346,29 +523,78 @@ function runDoctor(options) {
             exists: fs.existsSync(filePath)
         };
     });
-    const capabilities = evaluateDoctorCapabilities(checks);
+    const capabilities = evaluateDoctorCapabilities(checks, mode);
     const filesOk = packageFiles.every((check) => check.exists);
-    const ok = capabilities.coreOk && filesOk && capabilities.transportOk;
-    printJson({
+    const openclaw = runOpenClawChainDiagnostics({
+        openclawBin,
+        ...(options.workspace ? { workspace: String(options.workspace) } : {}),
+        ...(timeoutMs === undefined ? {} : { timeoutMs })
+    });
+    const selectedAgent = optionalExecutorKind(options.defaultAgent) ??
+        openclaw.default_agent ??
+        "codex";
+    const selectedAgentReady = mode === "tmux"
+        ? capabilities.tmux.status === "ready" &&
+            capabilities.tmux.agents.includes(selectedAgent)
+        : mode === "acpx"
+            ? capabilities.acpx.status === "ready" &&
+                capabilities.acpx.agents.includes(selectedAgent)
+            : (capabilities.tmux.status === "ready" &&
+                capabilities.tmux.agents.includes(selectedAgent)) || (capabilities.acpx.status === "ready" &&
+                capabilities.acpx.agents.includes(selectedAgent));
+    const ok = capabilities.readiness === "ready" &&
+        selectedAgentReady &&
+        filesOk &&
+        openclaw.ready;
+    return {
         ok,
+        readiness: ok
+            ? "ready"
+            : capabilities.readiness === "not_ready"
+                ? "not_ready"
+                : "partially_ready",
+        selected_mode: mode,
+        selected_agent: selectedAgent
+            ? {
+                agent: selectedAgent,
+                ready: selectedAgentReady
+            }
+            : null,
         package_root: root,
         checks,
         package_files: packageFiles,
         capabilities: {
-            tmux: capabilities.tmux,
-            acp: capabilities.acp
+            tmux: {
+                ...capabilities.tmux,
+                checked: mode !== "acpx"
+            },
+            acpx: {
+                ...capabilities.acpx,
+                checked: mode !== "tmux"
+            }
         },
+        openclaw,
         notes: [
             `Node.js ${MINIMUM_NODE_VERSION}+ and OpenClaw are required.`,
             "Choose tmux (recommended), ACPX/ACP, or install both.",
             "tmux supports Codex and Claude Code; ACPX supports Codex, Claude Code, and Cursor.",
             "Claude tmux completion is hook-free and fails closed unless the local transcript schema is verified."
-        ],
-        options
-    });
-    if (!ok) {
-        process.exitCode = 1;
+        ]
+    };
+}
+function parseDoctorMode(value) {
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === "tmux" || normalized === "acpx" || normalized === "all") {
+        return normalized;
+    }
+    throw new Error("--mode must be one of: tmux, acpx, all");
+}
+function positiveMilliseconds(value, optionName) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${optionName} must be a positive number`);
     }
+    return Math.ceil(parsed);
 }
 function versionAtLeast(version, minimum) {
     const parsed = version.split(".").slice(0, 3).map((part) => Number.parseInt(part, 10));
@@ -829,29 +1055,42 @@ function createRuntimeTerminalAgentRegistry(options) {
                     if (!isRecord(conversation)) {
                         return undefined;
                     }
-                    const contextMatch = await loadCodexTerminalContext({
+                    const contextMatches = await loadCodexTerminalContexts({
                         conversation,
                         nativeTakeover,
                         options
                     });
-                    if (!contextMatch?.context) {
-                        return undefined;
-                    }
-                    const evidence = detectCodexDurableCompletion({
-                        ...request,
-                        context: contextMatch.context
-                    });
-                    return evidence
-                        ? {
-                            ...evidence,
-                            confidence: contextMatch.confidence,
-                            metadata: {
-                                ...evidence.metadata,
-                                context_match: contextMatch.match,
-                                session: contextMatch.context.source
+                    const matches = [];
+                    const detectionErrors = [];
+                    for (const contextMatch of contextMatches) {
+                        try {
+                            const evidence = detectCodexDurableCompletion({
+                                ...request,
+                                context: contextMatch.context
+                            });
+                            if (evidence) {
+                                matches.push({
+                                    ...evidence,
+                                    confidence: contextMatch.confidence,
+                                    metadata: {
+                                        ...evidence.metadata,
+                                        context_match: contextMatch.match,
+                                        session: contextMatch.context.source
+                                    }
+                                });
                             }
                         }
-                        : undefined;
+                        catch (error) {
+                            detectionErrors.push(error instanceof Error ? error.message : String(error));
+                        }
+                    }
+                    if (detectionErrors.length > 0) {
+                        throw new Error(`could not inspect every plausible Codex completion: ${detectionErrors.join("; ")}`);
+                    }
+                    if (matches.length > 1) {
+                        throw new Error("multiple same-cwd Codex sessions match the managed terminal request");
+                    }
+                    return matches[0];
                 }
             }),
             createClaudeTerminalAgentAdapter({
@@ -2160,12 +2399,12 @@ async function runList(options) {
     const includeAll = Boolean(options.all);
     const agentFilter = options.agent ? resolveExecutor({ kind: options.agent }).kind : undefined;
     const statusFilter = options.status;
-    const conversations = listConversations(storeDir)
-        .map((conversation) => summarizeConversation(conversation))
+    const storedConversations = listConversations(storeDir)
         .filter((conversation) => includeAll || isActiveStatus(conversation.status))
-        .filter((conversation) => !agentFilter || conversation.agent === agentFilter)
+        .filter((conversation) => !agentFilter || executorForConversation(conversation).kind === agentFilter)
         .filter((conversation) => !statusFilter || conversation.status === statusFilter);
-    const delegated = conversations.map(delegatedListEntry);
+    const conversations = storedConversations.map((conversation) => summarizeConversation(conversation));
+    const delegated = storedConversations.map((conversation) => delegatedListEntry(summarizeConversation(conversation), { terminalBridge: terminalBridgeEnabled(conversation) }));
     const nativeScan = await buildNativeListGroups({ options, agentFilter, statusFilter });
     printJson({
         store_dir: storeDir,
@@ -2274,23 +2513,26 @@ async function terminalControlDiagnostics(provider) {
         paneCount: (await provider.listPanes()).length
     };
 }
-function delegatedListEntry(task) {
+function delegatedListEntry(task, { terminalBridge = false } = {}) {
     return {
         ...task,
         id: task.conversation_id,
+        short_ref: sessionShortRef(task.conversation_id),
         source: "akk_delegate",
         commands: {
             send: canSendDelegated(task.status),
             cancel: isWaitingForAgent(task.status),
             close: task.status !== "closed",
             status: true,
-            approve: false
+            approve: terminalBridge && isActiveStatus(task.status)
         }
     };
 }
 function nativeListEntry(session, activeSessions) {
+    const id = `native:${session.agent}:${session.pid}`;
     return {
-        id: `native:${session.agent}:${session.pid}`,
+        id,
+        short_ref: sessionShortRef(id),
         source: "native_active",
         agent: session.agent,
         status: "active",
@@ -2328,6 +2570,7 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
     });
     return {
         id: bridge.terminalConversationId(session),
+        short_ref: sessionShortRef(bridge.terminalConversationId(session)),
         source: "terminal_control",
         agent: session.agent,
         status: "active",
@@ -2421,6 +2664,120 @@ function childPidsForRoot(root, processes) {
 function canSendDelegated(status) {
     return !["failed", "closed", "cancelled"].includes(status);
 }
+async function resolveConversationSelectorOption(commandName, options) {
+    if (!SESSION_SELECTOR_COMMANDS.has(String(commandName ?? "")) ||
+        options.state) {
+        return;
+    }
+    const supplied = stringValue(options.conversation ?? options.conversationId)?.trim();
+    if (supplied && !isSessionSelectorSyntax(supplied)) {
+        // Full authoritative IDs keep their existing command-specific validation
+        // path. This avoids a discovery scan before option validation and preserves
+        // precise downstream errors for closed or currently non-actionable state.
+        return;
+    }
+    const candidates = await sessionSelectorCandidates(commandName, options);
+    const resolution = resolveSessionSelector(supplied, candidates, {
+        operation: commandName
+    });
+    options.conversation = resolution.id;
+    delete options.conversationId;
+}
+function isSessionSelectorSyntax(value) {
+    return (/^(?:only|latest|codex|claude|cursor|(?:codex|claude|cursor):latest)$/iu.test(value) ||
+        /^@[0-9a-f]+$/iu.test(value));
+}
+async function sessionSelectorCandidates(commandName, options) {
+    const storeDir = storeDirFromOptions(options);
+    cleanupIdleConversations(storeDir, options);
+    const storedConversations = listConversations(storeDir);
+    const managed = storedConversations.map((conversation) => delegatedListEntry(summarizeConversation(conversation), { terminalBridge: terminalBridgeEnabled(conversation) }));
+    const managedTerminalKeys = new Set(storedConversations
+        .filter((conversation) => isActiveStatus(conversation.status))
+        .map((conversation) => terminalControlSelectorKey(terminalControlFromTakeover(isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined)))
+        .filter((key) => key !== undefined));
+    const nativeScan = await buildNativeListGroups({
+        options: {
+            ...options,
+            noApprovalScan: commandName === "approve"
+                ? options.noApprovalScan
+                : true
+        },
+        agentFilter: undefined,
+        statusFilter: undefined
+    });
+    const observedAtMs = Date.now();
+    return [
+        ...managed,
+        ...nativeScan.terminalControlled.filter((entry) => {
+            const key = terminalControlSelectorKey(entry.terminal_control);
+            return key === undefined || !managedTerminalKeys.has(key);
+        }),
+        ...nativeScan.native
+    ].map((entry) => ({
+        id: String(entry.id),
+        agent: resolveExecutor({ kind: entry.agent }).kind,
+        actionable: sessionEntrySupportsCommand(entry, commandName),
+        ...sessionEntryRecency(entry, observedAtMs),
+        source: stringValue(entry.source),
+        status: stringValue(entry.status),
+        workspace: stringValue(entry.workspace ?? entry.cwd),
+        label: stringValue(entry.request ?? entry.command)
+    }));
+}
+function terminalControlSelectorKey(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const target = stringValue(value.target);
+    const panePid = Number(value.panePid);
+    if (!target || !Number.isSafeInteger(panePid) || panePid <= 1) {
+        return undefined;
+    }
+    return JSON.stringify({
+        target,
+        pane_pid: panePid,
+        socket_path: stringValue(value.socketPath) ?? null
+    });
+}
+function sessionEntrySupportsCommand(entry, commandName) {
+    if (commandName === "summary") {
+        commandName = "describe";
+    }
+    const commands = isRecord(entry.commands) ? entry.commands : {};
+    if (typeof commands[commandName] === "boolean") {
+        return commands[commandName] === true;
+    }
+    if (commandName === "describe") {
+        return commands.status === true || entry.source === "native_active";
+    }
+    if (entry.source !== "akk_delegate") {
+        return false;
+    }
+    if (commandName === "renew") {
+        return entry.status === "stalled";
+    }
+    if (commandName === "retry-callback") {
+        return ["callback_pending", "callback_failed"].includes(entry.status);
+    }
+    if (commandName === "recover") {
+        return entry.status === "needs_recovery";
+    }
+    return false;
+}
+function sessionEntryRecency(entry, observedAtMs) {
+    const timestamp = Date.parse(String(entry.updated_at ?? entry.created_at ?? ""));
+    if (Number.isFinite(timestamp)) {
+        return { updatedAtMs: timestamp };
+    }
+    const elapsedSeconds = parseProcessElapsedSeconds(entry.elapsed);
+    if (elapsedSeconds !== undefined) {
+        return { updatedAtMs: observedAtMs - elapsedSeconds * 1000 };
+    }
+    return {};
+}
 async function resolveTerminalConversationFromOptions(options) {
     return createTerminalAgentBridge(options).resolveConversationId(stringValue(options.conversation ?? options.conversationId));
 }
@@ -4227,6 +4584,39 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
         }
         throw error;
     }
+    let terminalCompletionReconciliation = {
+        prepared: [],
+        reconciledConversationIds: [],
+        protectedConversationIds: [],
+        skipSupersede: false
+    };
+    if (bridge) {
+        try {
+            terminalCompletionReconciliation =
+                await reconcileTerminalBridgeCompletionsBeforeSupersede({
+                    options,
+                    storeDir: storeDirFromOptions(options),
+                    terminalControl,
+                    replacementConversationId: conversation.conversation_id
+                });
+        }
+        catch (error) {
+            terminalCompletionReconciliation.skipSupersede = true;
+            terminalCompletionReconciliation.protectedConversationIds =
+                fenceTerminalBridgeConversationsForReconciliation({
+                    storeDir: storeDirFromOptions(options),
+                    terminalControl,
+                    replacementConversationId: conversation.conversation_id
+                });
+            appendEvent(logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: conversation.conversation_id,
+                event: "terminal_bridge_pre_supersede_reconciliation_failed",
+                terminal_control: terminalControl,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
     const bridgeConversation = bridge
         ? withTerminalBridgeState({
             conversation: conversationWithHookLease,
@@ -4250,11 +4640,16 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
         stateLockHeld: terminalStateLockHeld
     });
     saveState(statePath, deliveredConversation);
-    const supersededConversationIds = bridge
+    const supersededConversationIds = bridge &&
+        !terminalCompletionReconciliation.skipSupersede
         ? supersedeTerminalBridgeConversations({
             storeDir: storeDirFromOptions(options),
             terminalControl,
-            replacementConversationId: conversation.conversation_id
+            replacementConversationId: conversation.conversation_id,
+            excludedConversationIds: [
+                ...terminalCompletionReconciliation.reconciledConversationIds,
+                ...terminalCompletionReconciliation.protectedConversationIds
+            ]
         })
         : [];
     if (recordRawAttachmentAfterSend) {
@@ -4298,6 +4693,8 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
         terminal_control: terminalControl,
         message: textSummary(message.body),
         payload: textSummary(terminalPayload),
+        reconciled_conversation_ids: terminalCompletionReconciliation.reconciledConversationIds,
+        reconciliation_protected_conversation_ids: terminalCompletionReconciliation.protectedConversationIds,
         superseded_conversation_ids: supersededConversationIds
     });
     runtimeLog("info", "terminal_message_send", {
@@ -4306,6 +4703,8 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
         terminal_target: terminalControl.target,
         message: textSummary(message.body),
         payload: textSummary(terminalPayload),
+        reconciled_conversation_ids: terminalCompletionReconciliation.reconciledConversationIds,
+        reconciliation_protected_conversation_ids: terminalCompletionReconciliation.protectedConversationIds,
         superseded_conversation_ids: supersededConversationIds
     });
     const bridgeMonitor = bridge
@@ -4349,6 +4748,11 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
             callbackExpected: Boolean(deliveredConversation.callback_command || deliveredConversation.gateway_method)
         })
     });
+    if (terminalCompletionReconciliation.prepared.length > 0) {
+        setImmediate(() => {
+            deliverReconciledTerminalBridgeCallbacks(terminalCompletionReconciliation.prepared);
+        });
+    }
 }
 function terminalSubmissionPayload(payload) {
     return payload.trimEnd();
@@ -4437,18 +4841,272 @@ function createManagedTerminalConversationFromRawId({ options, conversationId, a
         message
     };
 }
-function supersedeTerminalBridgeConversations({ storeDir, terminalControl, replacementConversationId }) {
-    const activeStatuses = new Set([
-        "created",
-        "running",
-        "waiting_for_agent",
-        "waiting_for_openclaw",
-        "stalled",
-        "cancelling"
-    ]);
+async function reconcileTerminalBridgeCompletionsBeforeSupersede({ options, storeDir, terminalControl, replacementConversationId }) {
+    const prepared = [];
+    const reconciledConversationIds = [];
+    const protectedConversationIds = [];
+    const registry = createRuntimeTerminalAgentRegistry(options);
+    for (const listedConversation of listConversations(storeDir)) {
+        if (listedConversation.conversation_id === replacementConversationId ||
+            !TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(listedConversation.status)) {
+            continue;
+        }
+        const listedTakeover = isRecord(listedConversation.native_session_takeover)
+            ? listedConversation.native_session_takeover
+            : undefined;
+        const listedControl = terminalControlFromTakeover(listedTakeover);
+        if (listedTakeover?.terminal_bridge !== true ||
+            !listedControl ||
+            listedControl.target !== terminalControl.target ||
+            listedControl.socketPath !== terminalControl.socketPath ||
+            !listedControl.capabilities.includes("durable_completion")) {
+            continue;
+        }
+        const candidateStatePath = stringValue(listedConversation.state_path);
+        if (!candidateStatePath) {
+            continue;
+        }
+        const candidateLogPath = logPathForStatePath(candidateStatePath);
+        let candidate = loadState(candidateStatePath);
+        const candidateTakeover = isRecord(candidate.native_session_takeover)
+            ? candidate.native_session_takeover
+            : undefined;
+        const candidateControl = terminalControlFromTakeover(candidateTakeover);
+        const terminalMessageId = stringValue(candidateTakeover?.terminal_bridge_message_id);
+        if (!TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(candidate.status) ||
+            candidateTakeover?.terminal_bridge !== true ||
+            !candidateControl ||
+            candidateControl.target !== terminalControl.target ||
+            candidateControl.socketPath !== terminalControl.socketPath ||
+            !candidateControl.capabilities.includes("durable_completion") ||
+            !terminalMessageId) {
+            continue;
+        }
+        const fenced = fenceTerminalBridgeConversationForReconciliation({
+            statePath: candidateStatePath,
+            logPath: candidateLogPath,
+            terminalControl: candidateControl,
+            terminalMessageId,
+            replacementConversationId
+        });
+        if (!fenced.fenced) {
+            continue;
+        }
+        candidate = fenced.conversation;
+        const executor = executorForConversation(candidate);
+        const adapter = registry.require(executor.kind);
+        if (adapter.capabilities.durableCompletion !== true ||
+            typeof adapter.detectDurableCompletion !== "function") {
+            continue;
+        }
+        let completion;
+        try {
+            completion = await adapter.detectDurableCompletion(terminalDurableRequestForConversation(candidate, candidateControl));
+        }
+        catch (error) {
+            protectedConversationIds.push(candidate.conversation_id);
+            appendEvent(candidateLogPath, {
+                ts: new Date().toISOString(),
+                conversation_id: candidate.conversation_id,
+                event: "terminal_bridge_pre_supersede_reconciliation_failed",
+                terminal_control: candidateControl,
+                terminal_bridge_message_id: terminalMessageId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            continue;
+        }
+        if (!completion || completion.source !== "durable") {
+            continue;
+        }
+        let preparedCompletion;
+        try {
+            preparedCompletion = prepareTerminalBridgeCompletionCallback({
+                options,
+                statePath: candidateStatePath,
+                logPath: candidateLogPath,
+                conversation: candidate,
+                executor,
+                terminalControl: candidateControl,
+                terminalMessageId,
+                completion,
+                allowSupersedeRecovery: true
+            });
+        }
+        catch (error) {
+            protectedConversationIds.push(candidate.conversation_id);
+            appendEvent(candidateLogPath, {
+                ts: new Date().toISOString(),
+                conversation_id: candidate.conversation_id,
+                event: "terminal_bridge_pre_supersede_reconciliation_failed",
+                terminal_control: candidateControl,
+                terminal_bridge_message_id: terminalMessageId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            continue;
+        }
+        if (!preparedCompletion.claimed) {
+            const latest = preparedCompletion.conversation;
+            if (TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(latest.status)) {
+                protectedConversationIds.push(candidate.conversation_id);
+            }
+            else {
+                reconciledConversationIds.push(candidate.conversation_id);
+            }
+            continue;
+        }
+        const reconciledAt = new Date().toISOString();
+        appendEvent(candidateLogPath, {
+            ts: reconciledAt,
+            conversation_id: candidate.conversation_id,
+            event: "terminal_bridge_completion_reconciled_before_supersede",
+            terminal_control: candidateControl,
+            terminal_bridge_message_id: terminalMessageId,
+            callback_message_id: preparedCompletion.callbackMessageId,
+            replacement_conversation_id: replacementConversationId
+        });
+        reconciledConversationIds.push(candidate.conversation_id);
+        prepared.push({
+            conversationId: candidate.conversation_id,
+            statePath: candidateStatePath,
+            logPath: candidateLogPath,
+            terminalControl: candidateControl,
+            prepared: preparedCompletion.prepared
+        });
+    }
+    return {
+        prepared,
+        reconciledConversationIds,
+        protectedConversationIds,
+        skipSupersede: false
+    };
+}
+function fenceTerminalBridgeConversationsForReconciliation({ storeDir, terminalControl, replacementConversationId }) {
+    const fencedConversationIds = [];
+    for (const listedConversation of listConversations(storeDir)) {
+        if (listedConversation.conversation_id === replacementConversationId ||
+            !TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(listedConversation.status)) {
+            continue;
+        }
+        const statePath = stringValue(listedConversation.state_path);
+        const listedTakeover = isRecord(listedConversation.native_session_takeover)
+            ? listedConversation.native_session_takeover
+            : undefined;
+        const listedControl = terminalControlFromTakeover(listedTakeover);
+        const terminalMessageId = stringValue(listedTakeover?.terminal_bridge_message_id);
+        if (!statePath ||
+            listedTakeover?.terminal_bridge !== true ||
+            !listedControl ||
+            listedControl.target !== terminalControl.target ||
+            listedControl.socketPath !== terminalControl.socketPath ||
+            !terminalMessageId) {
+            continue;
+        }
+        const result = fenceTerminalBridgeConversationForReconciliation({
+            statePath,
+            logPath: logPathForStatePath(statePath),
+            terminalControl: listedControl,
+            terminalMessageId,
+            replacementConversationId
+        });
+        if (result.fenced) {
+            fencedConversationIds.push(listedConversation.conversation_id);
+        }
+    }
+    return fencedConversationIds;
+}
+function fenceTerminalBridgeConversationForReconciliation({ statePath, logPath, terminalControl, terminalMessageId, replacementConversationId }) {
+    const releaseLock = acquireFileLock(`${statePath}.lock`);
+    try {
+        const conversation = loadState(statePath);
+        const nativeTakeover = isRecord(conversation.native_session_takeover)
+            ? conversation.native_session_takeover
+            : undefined;
+        const currentControl = terminalControlFromTakeover(nativeTakeover);
+        if (!TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(conversation.status) ||
+            nativeTakeover?.terminal_bridge !== true ||
+            currentControl?.target !== terminalControl.target ||
+            currentControl?.socketPath !== terminalControl.socketPath ||
+            stringValue(nativeTakeover?.terminal_bridge_message_id) !==
+                terminalMessageId) {
+            return {
+                fenced: false,
+                conversation
+            };
+        }
+        const existingFence = isRecord(nativeTakeover.terminal_bridge_reconciliation_fence)
+            ? nativeTakeover.terminal_bridge_reconciliation_fence
+            : undefined;
+        if (conversation.status === "stalled" &&
+            existingFence?.replacement_conversation_id === replacementConversationId) {
+            return {
+                fenced: true,
+                conversation
+            };
+        }
+        const fencedAt = new Date().toISOString();
+        const fencedConversation = {
+            ...conversation,
+            status: "stalled",
+            stalled_reason: "terminal bridge paused because a newer task reused the same terminal before durable completion was resolved",
+            native_session_takeover: {
+                ...nativeTakeover,
+                terminal_bridge_reconciliation_fence: {
+                    replacement_conversation_id: replacementConversationId,
+                    terminal_bridge_message_id: terminalMessageId,
+                    previous_status: conversation.status,
+                    fenced_at: fencedAt
+                }
+            },
+            updated_at: fencedAt
+        };
+        saveState(statePath, fencedConversation);
+        appendEvent(logPath, {
+            ts: fencedAt,
+            conversation_id: conversation.conversation_id,
+            event: "terminal_bridge_reconciliation_fenced",
+            terminal_control: terminalControl,
+            terminal_bridge_message_id: terminalMessageId,
+            previous_status: conversation.status,
+            replacement_conversation_id: replacementConversationId
+        });
+        return {
+            fenced: true,
+            conversation: fencedConversation
+        };
+    }
+    finally {
+        releaseLock();
+    }
+}
+function deliverReconciledTerminalBridgeCallbacks(reconciledCallbacks) {
+    for (const callback of reconciledCallbacks) {
+        try {
+            runPreparedCallback(callback.prepared, { emit: false });
+        }
+        catch (error) {
+            appendEvent(callback.logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: callback.conversationId,
+                event: "terminal_bridge_reconciled_callback_delivery_failed",
+                terminal_control: callback.terminalControl,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            runtimeLog("warn", "terminal_bridge_reconciled_callback_delivery_failed", {
+                conversation_id: callback.conversationId,
+                terminal_target: callback.terminalControl.target,
+                state_path: callback.statePath,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+}
+function supersedeTerminalBridgeConversations({ storeDir, terminalControl, replacementConversationId, excludedConversationIds = [] }) {
+    const excluded = new Set(excludedConversationIds);
     const superseded = [];
     for (const candidate of listConversations(storeDir)) {
-        if (candidate.conversation_id === replacementConversationId || !activeStatuses.has(candidate.status)) {
+        if (candidate.conversation_id === replacementConversationId ||
+            excluded.has(candidate.conversation_id) ||
+            !TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(candidate.status)) {
             continue;
         }
         const candidateTakeover = isRecord(candidate.native_session_takeover)
@@ -4467,7 +5125,7 @@ function supersedeTerminalBridgeConversations({ storeDir, terminalControl, repla
         const releaseLock = acquireFileLock(`${candidateStatePath}.lock`);
         try {
             const current = loadState(candidateStatePath);
-            if (!activeStatuses.has(current.status)) {
+            if (!TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(current.status)) {
                 continue;
             }
             const currentTakeover = isRecord(current.native_session_takeover)
@@ -6942,99 +7600,29 @@ async function runTerminalBridgeMonitorWithLock(options) {
         const completionStable = completionFingerprint !== undefined && completionFingerprint === idleCompletionFingerprint;
         idleCompletionFingerprint = completionFingerprint;
         if (completion && completionStable && completionFingerprint) {
-            const completionOutcome = completion.outcome === "failure" ? "failure" : "success";
-            const callbackMessageId = deterministicTerminalCallbackMessageId({
-                conversationId: conversation.conversation_id,
-                terminalMessageId: currentMessageId,
-                completionFingerprint,
-                outcome: completionOutcome
-            });
-            const claim = claimTerminalBridgeCompletion({
+            const preparedCompletion = prepareTerminalBridgeCompletionCallback({
+                options,
                 statePath,
                 logPath,
+                conversation,
+                executor,
+                terminalControl,
                 terminalMessageId: currentMessageId,
-                completionFingerprint,
-                completionId: completion.id,
-                callbackMessageId,
-                outcome: completionOutcome
+                completion,
+                completionFingerprint
             });
-            if (!claim.claimed) {
+            if (!preparedCompletion.claimed) {
                 printJson({
-                    conversation: claim.conversation,
+                    conversation: preparedCompletion.conversation,
                     monitored: true,
                     terminal_bridge: true,
                     completed: false,
                     duplicate: true,
-                    reason: claim.reason
+                    reason: preparedCompletion.reason
                 });
                 return;
             }
-            let preparedCallback;
-            try {
-                conversation = claim.conversation;
-                appendEvent(logPath, {
-                    ts: new Date().toISOString(),
-                    conversation_id: conversation.conversation_id,
-                    event: "terminal_bridge_completion_detected",
-                    terminal_control: terminalControl,
-                    match: completionMatch,
-                    completion_source: completion.source,
-                    completion_outcome: completionOutcome,
-                    completion_id: completion.id,
-                    terminal_session: completionMetadata.session,
-                    context_match: completionMetadata.context_match,
-                    assistant_timestamp: completion?.timestamp,
-                    rollout_turn_id: completion.source === "durable" ? completion.id : undefined,
-                    terminal_bridge_message_id: currentMessageId,
-                    callback_message_id: callbackMessageId
-                });
-                const callbackMessage = {
-                    ...createMessage({
-                        conversation,
-                        from: executor.actor,
-                        to: "openclaw",
-                        type: completionOutcome === "failure" ? "error" : "done",
-                        requiresResponse: false,
-                        body: completion.text,
-                        metadata: {
-                            source: "terminal_bridge",
-                            terminal_control: terminalControl,
-                            ...completionMetadata,
-                            completion_source: completion.source,
-                            completion_outcome: completionOutcome,
-                            completion_id: completion.id,
-                            terminal_session: completionMetadata.session,
-                            confidence: completion.confidence,
-                            match: completionMatch,
-                            assistant_timestamp: completion?.timestamp,
-                            rollout_turn_id: completion.source === "durable" ? completion.id : undefined,
-                            terminal_bridge_message_id: currentMessageId
-                        }
-                    }),
-                    id: callbackMessageId
-                };
-                preparedCallback = prepareLockedCallback({
-                    ...options,
-                    statePath,
-                    log: logPath,
-                    closeTerminalBridgeOnDone: completionOutcome === "success",
-                    trackCallbackDelivery: true,
-                    recoverTerminalCompletion: claim.resumed === true,
-                    preserveMessageId: true,
-                    messageJson: JSON.stringify(callbackMessage),
-                    gatewayMethod: conversation.gateway_method,
-                    gatewaySession: conversation.gateway_session,
-                    openclawSession: conversation.openclaw_session,
-                    openclawBin: conversation.openclaw_bin,
-                    gatewayUrl: stringValue(conversation.gateway_token) ? conversation.gateway_url : undefined,
-                    token: stringValue(conversation.gateway_token)
-                });
-            }
-            finally {
-                releaseClaudeHookLease(conversation);
-                claim.release();
-            }
-            runPreparedCallback(preparedCallback);
+            runPreparedCallback(preparedCompletion.prepared);
             return;
         }
         // A concrete approval or completion observed on this poll wins over a timeout boundary.
@@ -7198,14 +7786,132 @@ function deterministicTerminalCallbackMessageId({ conversationId, terminalMessag
         .slice(0, 32);
     return `msg-terminal-${digest}`;
 }
-function claimTerminalBridgeCompletion({ statePath, logPath, terminalMessageId, completionFingerprint, completionId, callbackMessageId, outcome }) {
+function terminalBridgeCompletionFingerprint({ completion, terminalMessageId }) {
+    const metadata = isRecord(completion.metadata) ? completion.metadata : {};
+    const match = stringValue(metadata.match) ??
+        (completion.source === "screen" ? "terminal_screen" : "durable_completion");
+    return createHash("sha256")
+        .update(JSON.stringify({
+        text: completion.text,
+        timestamp: completion.timestamp,
+        match,
+        source: completion.source,
+        id: completion.id,
+        message_id: terminalMessageId
+    }))
+        .digest("hex");
+}
+function prepareTerminalBridgeCompletionCallback({ options, statePath, logPath, conversation, executor, terminalControl, terminalMessageId, completion, allowSupersedeRecovery = false, completionFingerprint = terminalBridgeCompletionFingerprint({
+    completion,
+    terminalMessageId
+}) }) {
+    const completionMetadata = isRecord(completion.metadata) ? completion.metadata : {};
+    const completionMatch = stringValue(completionMetadata.match) ??
+        (completion.source === "screen" ? "terminal_screen" : "durable_completion");
+    const completionOutcome = completion.outcome === "failure" ? "failure" : "success";
+    const callbackMessageId = deterministicTerminalCallbackMessageId({
+        conversationId: conversation.conversation_id,
+        terminalMessageId,
+        completionFingerprint,
+        outcome: completionOutcome
+    });
+    const claim = claimTerminalBridgeCompletion({
+        statePath,
+        logPath,
+        terminalMessageId,
+        completionFingerprint,
+        completionId: completion.id,
+        callbackMessageId,
+        outcome: completionOutcome,
+        allowSupersedeRecovery
+    });
+    if (!claim.claimed) {
+        return claim;
+    }
+    let claimedConversation = claim.conversation;
+    try {
+        appendEvent(logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: claimedConversation.conversation_id,
+            event: "terminal_bridge_completion_detected",
+            terminal_control: terminalControl,
+            match: completionMatch,
+            completion_source: completion.source,
+            completion_outcome: completionOutcome,
+            completion_id: completion.id,
+            terminal_session: completionMetadata.session,
+            context_match: completionMetadata.context_match,
+            assistant_timestamp: completion.timestamp,
+            rollout_turn_id: completion.source === "durable" ? completion.id : undefined,
+            terminal_bridge_message_id: terminalMessageId,
+            callback_message_id: callbackMessageId
+        });
+        const callbackMessage = {
+            ...createMessage({
+                conversation: claimedConversation,
+                from: executor.actor,
+                to: "openclaw",
+                type: completionOutcome === "failure" ? "error" : "done",
+                requiresResponse: false,
+                body: completion.text,
+                metadata: {
+                    source: "terminal_bridge",
+                    terminal_control: terminalControl,
+                    ...completionMetadata,
+                    completion_source: completion.source,
+                    completion_outcome: completionOutcome,
+                    completion_id: completion.id,
+                    terminal_session: completionMetadata.session,
+                    confidence: completion.confidence,
+                    match: completionMatch,
+                    assistant_timestamp: completion.timestamp,
+                    rollout_turn_id: completion.source === "durable" ? completion.id : undefined,
+                    terminal_bridge_message_id: terminalMessageId
+                }
+            }),
+            id: callbackMessageId
+        };
+        const prepared = prepareLockedCallback({
+            ...options,
+            statePath,
+            log: logPath,
+            closeTerminalBridgeOnDone: completionOutcome === "success",
+            trackCallbackDelivery: true,
+            recoverTerminalCompletion: claim.resumed === true,
+            allowTerminalCompletionRecoveryStatus: allowSupersedeRecovery,
+            preserveMessageId: true,
+            messageJson: JSON.stringify(callbackMessage),
+            gatewayMethod: claimedConversation.gateway_method,
+            gatewaySession: claimedConversation.gateway_session,
+            openclawSession: claimedConversation.openclaw_session,
+            openclawBin: claimedConversation.openclaw_bin,
+            gatewayUrl: stringValue(claimedConversation.gateway_token)
+                ? claimedConversation.gateway_url
+                : undefined,
+            token: stringValue(claimedConversation.gateway_token)
+        });
+        return {
+            claimed: true,
+            conversation: claimedConversation,
+            prepared,
+            callbackMessageId
+        };
+    }
+    finally {
+        releaseClaudeHookLease(claimedConversation);
+        claim.release();
+    }
+}
+function claimTerminalBridgeCompletion({ statePath, logPath, terminalMessageId, completionFingerprint, completionId, callbackMessageId, outcome, allowSupersedeRecovery = false }) {
     const release = acquireFileLock(`${statePath}.lock`);
     try {
         const conversation = loadState(statePath);
         const nativeTakeover = isRecord(conversation.native_session_takeover)
             ? conversation.native_session_takeover
             : {};
-        if (!isWaitingForAgent(conversation.status)) {
+        if (!isWaitingForAgent(conversation.status) &&
+            !(allowSupersedeRecovery &&
+                TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(conversation.status))) {
             release();
             return {
                 claimed: false,
@@ -7405,7 +8111,7 @@ function terminalBridgeApprovalCandidate({ executor, terminalControl, terminalSt
             : {})
     };
 }
-async function loadCodexTerminalContext({ conversation, nativeTakeover, options }) {
+async function loadCodexTerminalContexts({ conversation, nativeTakeover, options }) {
     const provider = createAgentSessionProvider("codex", options);
     const nativeSessionId = stringValue(nativeTakeover?.["native_session_id"]);
     const startedAtMs = Date.parse(String(nativeTakeover?.["terminal_bridge_started_at"] ?? ""));
@@ -7420,17 +8126,17 @@ async function loadCodexTerminalContext({ conversation, nativeTakeover, options
             maxTextLength: Number(options.maxTextLength ?? 4000)
         });
         if (context) {
-            return {
-                context,
-                process: activeProcess,
-                match: activeProcess?.sessionId ? "process_session_id" : "native_session_id",
-                confidence: "high"
-            };
+            return [{
+                    context,
+                    process: activeProcess,
+                    match: activeProcess?.sessionId ? "process_session_id" : "native_session_id",
+                    confidence: "high"
+                }];
         }
     }
     const cwd = activeProcess?.cwd ?? stringValue(nativeTakeover?.["source_cwd"]);
     if (!cwd) {
-        return undefined;
+        return [];
     }
     const sessions = (await provider.listHistoricalSessions())
         .filter((session) => session.cwd === cwd)
@@ -7438,28 +8144,40 @@ async function loadCodexTerminalContext({ conversation, nativeTakeover, options
         if (!Number.isFinite(startedAtMs)) {
             return true;
         }
-        return Number(session.updatedAtMs ?? 0) >= startedAtMs;
+        if (session.updatedAtMs === undefined || session.updatedAtMs === null) {
+            return true;
+        }
+        const updatedAtMs = Number(session.updatedAtMs);
+        return !Number.isFinite(updatedAtMs) || updatedAtMs >= startedAtMs;
     })
         .sort((left, right) => Number(right.updatedAtMs ?? 0) - Number(left.updatedAtMs ?? 0));
-    const selected = sessions[0];
-    if (!selected) {
-        return undefined;
+    const matches = [];
+    const candidateErrors = [];
+    for (const session of sessions) {
+        try {
+            const context = await provider.getForkContext({
+                sessionId: session.id,
+                maxMessages: Number(options.maxMessages ?? 16),
+                maxCommands: Number(options.maxCommands ?? 10),
+                maxTextLength: Number(options.maxTextLength ?? 4000)
+            });
+            if (context) {
+                matches.push({
+                    context,
+                    process: activeProcess,
+                    match: sessions.length === 1 ? "cwd" : "cwd_request_hash",
+                    confidence: sessions.length === 1 ? "medium" : "low"
+                });
+            }
+        }
+        catch (error) {
+            candidateErrors.push(`${session.id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
-    const context = await provider.getForkContext({
-        sessionId: selected.id,
-        maxMessages: Number(options.maxMessages ?? 16),
-        maxCommands: Number(options.maxCommands ?? 10),
-        maxTextLength: Number(options.maxTextLength ?? 4000)
-    });
-    if (!context) {
-        return undefined;
+    if (candidateErrors.length > 0) {
+        throw new Error(`could not inspect every plausible same-cwd Codex session: ${candidateErrors.join("; ")}`);
     }
-    return {
-        context,
-        process: activeProcess,
-        match: sessions.length === 1 ? "cwd" : "cwd_latest",
-        confidence: sessions.length === 1 ? "medium" : "low"
-    };
+    return matches;
 }
 function resolveExecutable(command) {
     if (command.includes(path.sep)) {
@@ -7653,7 +8371,9 @@ function prepareLockedCallback(options) {
             callbackDelivery.message.id !== message.id);
     const recoveringTerminalCompletion = options.recoverTerminalCompletion === true &&
         duplicateMessage &&
-        isWaitingForAgent(conversation.status);
+        (isWaitingForAgent(conversation.status) ||
+            (options.allowTerminalCompletionRecoveryStatus === true &&
+                TERMINAL_BRIDGE_SUPERSEDE_STATUSES.has(conversation.status)));
     if (duplicateMessage &&
         !retryingPending &&
         !recoveringTerminalCompletion &&
@@ -8040,9 +8760,8 @@ function deliverCallbackToOpenClaw({ options, statePath, logPath, conversation,
         if (delivery.status !== 0) {
             throw new Error(delivery.stderr || delivery.stdout || `gateway method delivery failed with status ${delivery.status}`);
         }
-        const gatewayPayload = parseOptionalJson(delivery.stdout);
-        const chatSendParams = isRecord(gatewayPayload?.chat_send) ? gatewayPayload.chat_send : undefined;
-        const sessionSendParams = isRecord(gatewayPayload?.session_send) ? gatewayPayload.session_send : undefined;
+        const gatewayPayload = parseRequiredGatewayDeliveryPayload(delivery.stdout);
+        const { chatSendParams, sessionSendParams } = parseGatewayCallbackDeliveryPlan(gatewayPayload);
         if (chatSendParams) {
             const chatSendDelivery = deliverToChatSend({
                 openclawBin: options.openclawBin,
@@ -8050,16 +8769,71 @@ function deliverCallbackToOpenClaw({ options, statePath, logPath, conversation,
                 token: options.token,
                 params: chatSendParams
             });
+            if (chatSendDelivery.status !== 0) {
+                recordCallbackProcessDelivery({
+                    logPath,
+                    conversation,
+                    message,
+                    event: "callback_chat_send_delivery",
+                    runtimeEvent: "callback_chat_send_delivery",
+                    delivery: chatSendDelivery
+                });
+                throw new Error(chatSendDelivery.stderr || chatSendDelivery.stdout || `chat callback delivery failed with status ${chatSendDelivery.status}`);
+            }
+            const chatSendAck = parseChatSendAcknowledgement(chatSendDelivery.stdout, String(chatSendParams.idempotencyKey));
             recordCallbackProcessDelivery({
                 logPath,
                 conversation,
                 message,
                 event: "callback_chat_send_delivery",
                 runtimeEvent: "callback_chat_send_delivery",
-                delivery: chatSendDelivery
+                delivery: chatSendDelivery,
+                detail: {
+                    run_id: chatSendAck.runId,
+                    run_status: chatSendAck.status
+                }
             });
-            if (chatSendDelivery.status !== 0) {
-                throw new Error(chatSendDelivery.stderr || chatSendDelivery.stdout || `chat callback delivery failed with status ${chatSendDelivery.status}`);
+            if (chatSendAck.status === "ok") {
+                return "gateway_method+chat_send";
+            }
+            const agentWaitDelivery = deliverToAgentWait({
+                openclawBin: options.openclawBin,
+                gatewayUrl: options.gatewayUrl,
+                token: options.token,
+                runId: chatSendAck.runId
+            });
+            if (agentWaitDelivery.status !== 0) {
+                recordCallbackProcessDelivery({
+                    logPath,
+                    conversation,
+                    message,
+                    event: "callback_agent_wait_delivery",
+                    runtimeEvent: "callback_agent_wait_delivery",
+                    delivery: agentWaitDelivery,
+                    detail: { run_id: chatSendAck.runId }
+                });
+                throw new Error(agentWaitDelivery.stderr ||
+                    agentWaitDelivery.stdout ||
+                    `callback agent wait failed with status ${agentWaitDelivery.status}`);
+            }
+            const waitResult = parseAgentWaitResult(agentWaitDelivery.stdout, chatSendAck.runId);
+            recordCallbackProcessDelivery({
+                logPath,
+                conversation,
+                message,
+                event: "callback_agent_wait_delivery",
+                runtimeEvent: "callback_agent_wait_delivery",
+                delivery: agentWaitDelivery,
+                detail: {
+                    run_id: chatSendAck.runId,
+                    run_status: waitResult.status
+                }
+            });
+            if (waitResult.status !== "ok") {
+                const detail = stringValue(waitResult.error) ??
+                    stringValue(waitResult.stopReason) ??
+                    `agent.wait returned ${String(waitResult.status)}`;
+                throw new Error(`callback Gateway run did not complete successfully: ${detail}`);
             }
             return "gateway_method+chat_send";
         }
@@ -8070,16 +8844,70 @@ function deliverCallbackToOpenClaw({ options, statePath, logPath, conversation,
                 token: options.token,
                 params: sessionSendParams
             });
+            if (sessionSendDelivery.status !== 0) {
+                recordCallbackProcessDelivery({
+                    logPath,
+                    conversation,
+                    message,
+                    event: "callback_session_send_delivery",
+                    runtimeEvent: "callback_session_send_delivery",
+                    delivery: sessionSendDelivery
+                });
+                throw new Error(sessionSendDelivery.stderr || sessionSendDelivery.stdout || `session callback delivery failed with status ${sessionSendDelivery.status}`);
+            }
+            const sessionSendAck = parseChatSendAcknowledgement(sessionSendDelivery.stdout, String(sessionSendParams.idempotencyKey));
             recordCallbackProcessDelivery({
                 logPath,
                 conversation,
                 message,
                 event: "callback_session_send_delivery",
                 runtimeEvent: "callback_session_send_delivery",
-                delivery: sessionSendDelivery
+                delivery: sessionSendDelivery,
+                detail: {
+                    run_id: sessionSendAck.runId,
+                    run_status: sessionSendAck.status
+                }
             });
-            if (sessionSendDelivery.status !== 0) {
-                throw new Error(sessionSendDelivery.stderr || sessionSendDelivery.stdout || `session callback delivery failed with status ${sessionSendDelivery.status}`);
+            if (sessionSendAck.status !== "ok") {
+                const agentWaitDelivery = deliverToAgentWait({
+                    openclawBin: options.openclawBin,
+                    gatewayUrl: options.gatewayUrl,
+                    token: options.token,
+                    runId: sessionSendAck.runId
+                });
+                if (agentWaitDelivery.status !== 0) {
+                    recordCallbackProcessDelivery({
+                        logPath,
+                        conversation,
+                        message,
+                        event: "callback_agent_wait_delivery",
+                        runtimeEvent: "callback_agent_wait_delivery",
+                        delivery: agentWaitDelivery,
+                        detail: { run_id: sessionSendAck.runId }
+                    });
+                    throw new Error(agentWaitDelivery.stderr ||
+                        agentWaitDelivery.stdout ||
+                        `callback agent wait failed with status ${agentWaitDelivery.status}`);
+                }
+                const waitResult = parseAgentWaitResult(agentWaitDelivery.stdout, sessionSendAck.runId);
+                recordCallbackProcessDelivery({
+                    logPath,
+                    conversation,
+                    message,
+                    event: "callback_agent_wait_delivery",
+                    runtimeEvent: "callback_agent_wait_delivery",
+                    delivery: agentWaitDelivery,
+                    detail: {
+                        run_id: sessionSendAck.runId,
+                        run_status: waitResult.status
+                    }
+                });
+                if (waitResult.status !== "ok") {
+                    const detail = stringValue(waitResult.error) ??
+                        stringValue(waitResult.stopReason) ??
+                        `agent.wait returned ${String(waitResult.status)}`;
+                    throw new Error(`callback Gateway run did not complete successfully: ${detail}`);
+                }
             }
             return "gateway_method+sessions_send";
         }
@@ -9371,6 +10199,43 @@ function deliverToChatSend({ openclawBin, gatewayUrl, token, params }) {
         stderr: result.stderr ?? ""
     };
 }
+function deliverToAgentWait({ openclawBin, gatewayUrl, token, runId }) {
+    const args = [
+        "gateway",
+        "call",
+        "agent.wait",
+        "--params",
+        JSON.stringify({
+            runId,
+            timeoutMs: CALLBACK_AGENT_WAIT_TIMEOUT_MS
+        }),
+        "--json",
+        "--timeout",
+        String(CALLBACK_AGENT_WAIT_CLI_TIMEOUT_MS)
+    ];
+    if (gatewayUrl) {
+        args.push("--url", gatewayUrl);
+    }
+    const result = spawnSync(openclawBin ?? "openclaw", args, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10,
+        timeout: CALLBACK_AGENT_WAIT_PROCESS_TIMEOUT_MS,
+        killSignal: "SIGKILL",
+        env: openClawGatewayEnvironment(token)
+    });
+    if (result.error) {
+        return {
+            status: 1,
+            stdout: result.stdout ?? "",
+            stderr: result.error.message
+        };
+    }
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? ""
+    };
+}
 function openClawGatewayEnvironment(token) {
     if (!token || token === "<token>") {
         return process.env;
@@ -9431,6 +10296,96 @@ function parseOptionalJson(text) {
         return undefined;
     }
 }
+function parseRequiredGatewayDeliveryPayload(text) {
+    const payload = parseOptionalJson(text);
+    if (!isRecord(payload)) {
+        throw new Error("gateway callback returned malformed JSON");
+    }
+    if (payload.ok !== true) {
+        throw new Error(`gateway callback was not accepted: ${stringValue(payload.error) ?? stringValue(payload.message) ?? "ok was not true"}`);
+    }
+    if (payload.delivery_required !== undefined &&
+        typeof payload.delivery_required !== "boolean") {
+        throw new Error("gateway callback returned an invalid delivery_required value");
+    }
+    return payload;
+}
+function parseGatewayCallbackDeliveryPlan(payload) {
+    const chatSendParams = isRecord(payload.chat_send) ? payload.chat_send : undefined;
+    const sessionSendParams = isRecord(payload.session_send) ? payload.session_send : undefined;
+    if (chatSendParams && sessionSendParams) {
+        throw new Error("gateway callback returned multiple delivery plans");
+    }
+    const deliveryRequired = payload.delivery_required === true;
+    const deliveryExplicitlyNotRequired = payload.delivery_required === false;
+    const deliveryMode = stringValue(payload.delivery_mode);
+    if (deliveryRequired && !chatSendParams && !sessionSendParams) {
+        throw new Error("gateway callback requires delivery but returned no supported chat_send or session_send plan");
+    }
+    if (deliveryExplicitlyNotRequired && (chatSendParams || sessionSendParams)) {
+        throw new Error("gateway callback returned a delivery plan without delivery_required");
+    }
+    if (deliveryMode && deliveryMode !== "none") {
+        const expectedMode = chatSendParams ? "chat.send" : sessionSendParams ? "sessions.send" : undefined;
+        if (deliveryMode !== expectedMode) {
+            throw new Error("gateway callback delivery_mode does not match its delivery plan");
+        }
+    }
+    if (deliveryMode === "none" && deliveryRequired) {
+        throw new Error("gateway callback delivery_mode none cannot require delivery");
+    }
+    if (chatSendParams) {
+        if (!stringValue(chatSendParams.sessionKey) ||
+            !stringValue(chatSendParams.message) ||
+            !stringValue(chatSendParams.idempotencyKey) ||
+            chatSendParams.deliver !== true) {
+            throw new Error("gateway callback returned an invalid chat_send delivery plan");
+        }
+    }
+    if (sessionSendParams) {
+        if (!stringValue(sessionSendParams.key) ||
+            !stringValue(sessionSendParams.message) ||
+            !stringValue(sessionSendParams.idempotencyKey)) {
+            throw new Error("gateway callback returned an invalid session_send delivery plan");
+        }
+    }
+    return { chatSendParams, sessionSendParams };
+}
+function parseChatSendAcknowledgement(text, expectedRunId) {
+    const payload = parseOptionalJson(text);
+    if (!isRecord(payload)) {
+        throw new Error("chat.send returned malformed JSON");
+    }
+    const runId = stringValue(payload.runId);
+    const status = stringValue(payload.status);
+    if (!runId) {
+        throw new Error("chat.send acknowledgement is missing runId");
+    }
+    if (runId !== expectedRunId) {
+        throw new Error("chat.send acknowledgement runId does not match its idempotencyKey");
+    }
+    if (!status || !["started", "in_flight", "ok"].includes(status)) {
+        throw new Error(`chat.send returned unexpected status ${JSON.stringify(status ?? null)}`);
+    }
+    return {
+        runId,
+        status: status
+    };
+}
+function parseAgentWaitResult(text, expectedRunId) {
+    const payload = parseOptionalJson(text);
+    if (!isRecord(payload)) {
+        throw new Error("agent.wait returned malformed JSON");
+    }
+    if (stringValue(payload.runId) !== expectedRunId) {
+        throw new Error("agent.wait returned a result for a different runId");
+    }
+    const status = stringValue(payload.status);
+    if (!status || !["ok", "error", "timeout", "pending"].includes(status)) {
+        throw new Error(`agent.wait returned unexpected status ${JSON.stringify(status ?? null)}`);
+    }
+    return payload;
+}
 function createAgentSessionProvider(agent, options) {
     if (agent !== "codex") {
         throw new Error(`unsupported agent session provider: ${agent}`);
@@ -9654,18 +10609,18 @@ function usage() {
   agent-knock-knock bootstrap-prompt --callback-command <command> [--agent ${agentList}]
   agent-knock-knock delegate --request <text> [--agent ${agentList}] [--store-dir <dir>] [--all-proxy <url>] [--agent-timeout-minutes <minutes>] [--token <gateway-token>] [--send|--background]
   agent-knock-knock list [--store-dir <dir>] [--agent ${agentList}] [--status <status>] [--all] [--managed-only] [--no-approval-scan] [--terminal-debug]
-  agent-knock-knock status --conversation <id> [--store-dir <dir>] [--trace]
-  agent-knock-knock describe --conversation <id> [--store-dir <dir>]
-  agent-knock-knock send --conversation <id> --message <text> [--type answer|task|control] [--all-proxy <url>] [--agent-timeout-minutes <minutes>] [--agent-hard-timeout-minutes <minutes>]
-  agent-knock-knock approve --conversation <id>
-  agent-knock-knock cancel --conversation <id> [--all-proxy <url>]
-  agent-knock-knock renew --conversation <id> [--minutes <inactivity-minutes>]
+  agent-knock-knock status [--conversation <id|selector>] [--store-dir <dir>] [--trace]
+  agent-knock-knock describe [--conversation <id|selector>] [--store-dir <dir>]
+  agent-knock-knock send [--conversation <id|selector>] --message <text> [--type answer|task|control] [--all-proxy <url>] [--agent-timeout-minutes <minutes>] [--agent-hard-timeout-minutes <minutes>]
+  agent-knock-knock approve [--conversation <id|selector>]
+  agent-knock-knock cancel [--conversation <id|selector>] [--all-proxy <url>]
+  agent-knock-knock renew [--conversation <id|selector>] [--minutes <inactivity-minutes>]
   agent-knock-knock reconcile-monitors [--store-dir <dir>]
   agent-knock-knock retry-callback --conversation <id> [--store-dir <dir>]
   agent-knock-knock recover --conversation <id> [--session <name>] [--all-proxy <url>]
   agent-knock-knock close --conversation <id> [--reason <text>]
-  agent-knock-knock install-openclaw [--openclaw-bin <path>] [--skill-path <path>] [--skill-only] [--no-restart]
-  agent-knock-knock doctor
+  agent-knock-knock install-openclaw [--workspace <path>] [--default-agent ${agentList}] [--mode tmux|acpx|all] [--verify] [--openclaw-bin <path>] [--skill-path <path>] [--skill-only] [--no-restart]
+  agent-knock-knock doctor [--mode tmux|acpx|all] [--workspace <path>] [--openclaw-bin <path>]
   agent-knock-knock agent takeover --agent codex --session-id <id> --strategy terminate_then_resume|terminal_control|fork [--create-conversation]
   agent-knock-knock callback --state <file> --message-json <json> [--record-only]
   agent-knock-knock transcript --log <file> [--include-raw]