@scotthuang/agent-knock-knock 0.2.0 → 0.2.2

package/dist/src/cli.js

@@ -8,12 +8,13 @@ import { fileURLToPath } from "node:url";
 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, sessionRecoveryStrategyForExecutor } from "./executors.js";
+import { EXECUTOR_KINDS, acpxCommandForExecutor, executorDefinitionForKind, modelEnvForExecutor, normalizeModelForExecutor, proxyEnvForExecutor } from "./executors.js";
 import { executorBootstrapPrompt } from "./bootstrap.js";
 import { writeRuntimeLog } from "./runtime-log.js";
 import { formatTranscript, readNdjsonLog } from "./transcript.js";
 import { appendEvent, defaultStoreDir, listConversations, logPathForStatePath, loadConversationById, loadState, messageEvent, pathsForConversation, pathsForConversationDir, saveState, statePathForConversationId } from "./store.js";
 import { planFork, planSafeResume, planTakeover } from "./session-takeover-planner.js";
+import { StaticTerminalControlProvider, TmuxTerminalControlProvider, enrichActiveProcessesWithTerminalControl } from "./terminal-control-provider.js";
 const DEFAULT_IDLE_TIMEOUT_MINUTES = 10080;
 const DEFAULT_AGENT_TIMEOUT_MINUTES = 60;
 const DEFAULT_MONITOR_POLL_INTERVAL_MS = 5000;
@@ -89,10 +90,13 @@ async function runCommand(commandName, options) {
         runList(options);
     }
     else if (commandName === "status") {
-        runStatus(options);
+        await runStatus(options);
     }
     else if (commandName === "send") {
-        runSend(options);
+        await runSend(options);
+    }
+    else if (commandName === "approve") {
+        await runApprove(options);
     }
     else if (commandName === "cancel") {
         runCancel(options);
@@ -100,9 +104,6 @@ async function runCommand(commandName, options) {
     else if (commandName === "recover") {
         runRecover(options);
     }
-    else if (commandName === "restart") {
-        runRestart(options);
-    }
     else if (commandName === "close") {
         runClose(options);
     }
@@ -245,7 +246,7 @@ async function runAgentDiscover(options) {
             agent,
             scope,
             capabilities,
-            active: await provider.listActiveSessions()
+            active: await listActiveSessionsWithTerminalControl(provider, options)
         };
     }
     throw new Error(`unsupported discover scope: ${scope}`);
@@ -270,7 +271,7 @@ async function runAgentTakeover(options) {
         };
     }
     if (strategy === "safe_resume") {
-        const plan = planSafeResume(session, await provider.listActiveSessions());
+        const plan = planSafeResume(session, await listActiveSessionsWithTerminalControl(provider, options));
         if (plan.allowed && options.createConversation) {
             const modelInfo = await provider.getSessionModel(session.id);
             const attached = createNativeSessionConversation({
@@ -300,7 +301,7 @@ async function runAgentTakeover(options) {
         };
     }
     if (strategy === "terminate_then_resume") {
-        const activeSessions = await provider.listActiveSessions();
+        const activeSessions = await listActiveSessionsWithTerminalControl(provider, options);
         const plan = planTakeover(session, activeSessions);
         if (options.confirmTerminate === true) {
             const expectedPid = Number(required(options.expectedPid, "--expected-pid is required with --confirm-terminate"));
@@ -335,7 +336,7 @@ async function runAgentTakeover(options) {
             const termination = terminateProcessTarget(target, {
                 timeoutMs: Number(options.terminateTimeoutMs ?? 3000)
             });
-            const activeAfterTermination = await provider.listActiveSessions();
+            const activeAfterTermination = await listActiveSessionsWithTerminalControl(provider, options);
             const afterTerminationPlan = planTakeover(session, activeAfterTermination);
             if (afterTerminationPlan.targets.some((candidate) => candidate.sessionId === session.id || candidate.pid === expectedPid)) {
                 return {
@@ -382,6 +383,60 @@ async function runAgentTakeover(options) {
             plan
         };
     }
+    if (strategy === "terminal_control") {
+        const activeSessions = await listActiveSessionsWithTerminalControl(provider, options);
+        const plan = planTerminalControlTakeover(session, activeSessions);
+        if (options.confirmTerminal === true) {
+            const terminalTarget = String(required(options.terminalTarget, "--terminal-target is required with --confirm-terminal"));
+            if (!options.createConversation) {
+                throw new Error("--create-conversation is required with --confirm-terminal");
+            }
+            const target = plan.targets.find((candidate) => candidate.terminalControl?.target === terminalTarget);
+            if (!plan.allowed || !target?.terminalControl) {
+                return {
+                    agent,
+                    sessionId,
+                    strategy,
+                    status: "blocked",
+                    sideEffectsExecuted: false,
+                    plan,
+                    error: {
+                        code: "terminal_target_unavailable",
+                        message: `No matching tmux-controlled Codex process was found for ${terminalTarget}`
+                    }
+                };
+            }
+            const modelInfo = await provider.getSessionModel(session.id);
+            const attached = createNativeSessionConversation({
+                agent,
+                strategy,
+                session,
+                modelInfo,
+                options,
+                takeoverMatchKind: "terminal_control",
+                terminalControl: target.terminalControl,
+                needsBootstrap: false
+            });
+            return {
+                agent,
+                sessionId,
+                strategy,
+                status: "attached",
+                sideEffectsExecuted: true,
+                plan,
+                terminalControl: target.terminalControl,
+                ...attached
+            };
+        }
+        return {
+            agent,
+            sessionId,
+            strategy,
+            status: plan.allowed ? "requires_confirmation" : "blocked",
+            sideEffectsExecuted: false,
+            plan
+        };
+    }
     if (strategy === "fork") {
         const contextPackage = await provider.getForkContext({
             sessionId,
@@ -519,6 +574,120 @@ function selectTerminateTarget({ plan, session, activeSessions, expectedPid, all
         matchKind: "cwd_only_confirmed"
     };
 }
+async function listActiveSessionsWithTerminalControl(provider, options) {
+    const activeSessions = await provider.listActiveSessions();
+    return enrichActiveProcessesWithTerminalControl(activeSessions, createTerminalControlProvider(options));
+}
+function createTerminalControlProvider(options) {
+    if (options.terminalsJson || options.terminalScreensJson) {
+        return new StaticTerminalControlProvider({
+            panes: parseJsonOption(options.terminalsJson, "--terminals-json"),
+            screens: parseJsonOption(options.terminalScreensJson, "--terminal-screens-json")
+        });
+    }
+    return new TmuxTerminalControlProvider();
+}
+function planTerminalControlTakeover(session, activeSessions) {
+    const matched = activeSessions
+        .filter((process) => process.kind === "codex_cli" &&
+        process.terminalControl &&
+        (process.sessionId === session.id ||
+            (!process.sessionId && process.cwd === session.cwd)));
+    const matchedPidSet = new Set(matched.map((process) => process.pid));
+    const targets = matched
+        .filter((process) => !process.ppid || !matchedPidSet.has(process.ppid))
+        .map((process) => ({
+        pid: process.pid,
+        childPids: matched
+            .filter((child) => child.ppid === process.pid)
+            .map((child) => child.pid),
+        cwd: process.cwd,
+        command: process.command,
+        sessionId: process.sessionId,
+        terminalControl: process.terminalControl
+    }));
+    const exactTargets = targets.filter((target) => target.sessionId === session.id);
+    const selectableTargets = exactTargets.length > 0 ? exactTargets : targets;
+    return {
+        mode: "terminal_control",
+        allowed: selectableTargets.length === 1,
+        requiresConfirmation: selectableTargets.length === 1,
+        reason: selectableTargets.length === 0
+            ? "no_terminal_control_target"
+            : selectableTargets.length === 1
+                ? "terminal_control_available"
+                : "ambiguous_terminal_control_target",
+        targets: selectableTargets
+    };
+}
+function terminalControlFromTakeover(nativeTakeover) {
+    if (!isRecord(nativeTakeover)) {
+        return undefined;
+    }
+    const terminalControl = nativeTakeover["terminal_control"];
+    if (!isRecord(terminalControl) || terminalControl.kind !== "tmux") {
+        return undefined;
+    }
+    const target = stringValue(terminalControl.target);
+    const session = stringValue(terminalControl.session);
+    const window = Number(terminalControl.window);
+    const pane = Number(terminalControl.pane);
+    const panePid = Number(terminalControl.panePid);
+    if (!target || !session || !Number.isInteger(window) || !Number.isInteger(pane) || !Number.isInteger(panePid)) {
+        return undefined;
+    }
+    return {
+        kind: "tmux",
+        target,
+        session,
+        window,
+        pane,
+        panePid,
+        currentCommand: stringValue(terminalControl.currentCommand),
+        currentPath: stringValue(terminalControl.currentPath),
+        capabilities: ["capture_screen", "send_keys", "terminal_approval"]
+    };
+}
+function detectCodexApprovalPrompt(screen) {
+    const approvalMarkers = [
+        "Would you like to run the following command?",
+        "Would you like to make the following edits?",
+        "Would you like to grant these permissions?",
+        "needs your approval."
+    ];
+    if (!approvalMarkers.some((marker) => screen.includes(marker))) {
+        return {
+            approvable: false,
+            reason: "no Codex approval prompt was detected in the terminal screen"
+        };
+    }
+    for (const line of screen.split(/\r?\n/)) {
+        const match = /^[\s›]*1\.\s+(Yes,[^(]+)\(([^)]+)\)/u.exec(line.trim());
+        if (!match) {
+            continue;
+        }
+        const key = match[2].trim();
+        if (key !== "y") {
+            return {
+                approvable: false,
+                reason: `primary approval shortcut is ${key}, not y`
+            };
+        }
+        return {
+            approvable: true,
+            key,
+            label: match[1].trim()
+        };
+    }
+    return {
+        approvable: false,
+        reason: "no primary approve option with a shortcut was detected"
+    };
+}
+function screenExcerpt(screen, maxLength = 4000) {
+    const lines = screen.trimEnd().split(/\r?\n/);
+    return lines.slice(Math.max(0, lines.length - 80)).join("\n").slice(-maxLength);
+}
 function createForkConversation({ agent, strategy, session, contextPackage, forkSummary, modelInfo, options }) {
     const workspace = session.cwd;
     const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
@@ -612,7 +781,7 @@ function createForkConversation({ agent, strategy, session, contextPackage, fork
         next: `Use AKK send ${forkedConversation.conversation_id}: <message> to start the forked ${agent} session with the approved summary.`
     };
 }
-function createNativeSessionConversation({ agent, strategy, session, modelInfo, options, takeoverMatchKind = strategy }) {
+function createNativeSessionConversation({ agent, strategy, session, modelInfo, options, takeoverMatchKind = strategy, terminalControl = undefined, needsBootstrap = true }) {
     const workspace = session.cwd;
     const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
     cleanupIdleConversations(storeDir, options);
@@ -669,7 +838,8 @@ function createNativeSessionConversation({ agent, strategy, session, modelInfo,
             acpx_model: modelInfo?.acpxModel,
             model_source: modelInfo?.source,
             takeover_match_kind: takeoverMatchKind,
-            needs_bootstrap: true
+            terminal_control: terminalControl,
+            needs_bootstrap: needsBootstrap
         }
     }, paths);
     saveState(paths.statePath, attachedConversation);
@@ -1121,7 +1291,7 @@ function runList(options) {
         cleanup
     });
 }
-function runStatus(options) {
+async function runStatus(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
     const events = readExistingEvents(logPath);
@@ -1136,6 +1306,24 @@ function runStatus(options) {
     if (options.trace) {
         result.trace = buildConversationTrace({ conversation, events, logPath });
     }
+    const terminalControl = terminalControlFromTakeover(isRecord(conversation.native_session_takeover) ? conversation.native_session_takeover : undefined);
+    if (terminalControl) {
+        result.terminal_control = terminalControl;
+        try {
+            const screen = await createTerminalControlProvider(options).capture(terminalControl.target, {
+                scrollbackLines: Number(options.scrollbackLines ?? 120)
+            });
+            result.terminal_screen = {
+                excerpt: screenExcerpt(screen),
+                approval: detectCodexApprovalPrompt(screen)
+            };
+        }
+        catch (error) {
+            result.terminal_screen = {
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
     printJson(result);
     runtimeLog("info", "task_status_read", {
         conversation_id: conversation.conversation_id,
@@ -1146,7 +1334,7 @@ function runStatus(options) {
         trace: Boolean(options.trace)
     });
 }
-function runSend(options) {
+async function runSend(options) {
     const messageBody = required(options.message ?? options.request, "--message is required");
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
@@ -1154,7 +1342,7 @@ function runSend(options) {
         throw new Error(`cannot send to ${conversation.conversation_id}; conversation is ${conversation.status}`);
     }
     if (conversation.status === "needs_recovery") {
-        throw new Error(`cannot send to ${conversation.conversation_id}; choose recover, restart, or close first`);
+        throw new Error(`cannot send to ${conversation.conversation_id}; choose recover, close, or delegate a new task first`);
     }
     if (conversation.status === "needs_model_selection" && !options.model) {
         throw new Error(`cannot send to ${conversation.conversation_id}; choose a supported model with --model first`);
@@ -1218,6 +1406,21 @@ function runSend(options) {
         includeForkTakeoverBootstrap: needsForkTakeoverBootstrap,
         forkTakeover: forkTakeoverForSend
     });
+    const terminalControlForSend = terminalControlFromTakeover(nativeTakeoverForSend);
+    if (terminalControlForSend) {
+        await runTerminalControlSend({
+            options,
+            conversation,
+            nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            terminalControl: terminalControlForSend,
+            needsNativeTakeoverBootstrap
+        });
+        return;
+    }
     if (nativeTakeoverForSend?.["native_session_id"] && executor.kind === "codex") {
         runNativeCodexResumeSend({
             options,
@@ -1264,7 +1467,7 @@ function runSend(options) {
         stderr: textSummary(cleanProcessText(ensureSession.stderr))
     });
     if (ensureSession.error) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1277,10 +1480,22 @@ function runSend(options) {
             }));
             return;
         }
-        throw new Error(`acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`);
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "session_ensure",
+            result: ensureSession,
+            reason: `acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`
+        });
+        return;
     }
     if (ensureSession.status !== 0) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        const reason = cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`);
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1289,11 +1504,22 @@ function runSend(options) {
                 message,
                 failedStage: "session_ensure",
                 result: ensureSession,
-                reason: cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`)
+                reason
             }));
             return;
         }
-        throw new Error(cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`));
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "session_ensure",
+            result: ensureSession,
+            reason
+        });
+        return;
     }
     const acpxArgs = buildAcpxPromptArgs({ executor, payload, model: executorModel });
     if (options.background) {
@@ -1386,7 +1612,7 @@ function runSend(options) {
         stderr: textSummary(cleanProcessText(sendResult.stderr))
     });
     if (sendResult.error) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1399,10 +1625,22 @@ function runSend(options) {
             }));
             return;
         }
-        throw new Error(`acpx ${executor.kind} send failed to start: ${sendResult.error.message}`);
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "message_send",
+            result: sendResult,
+            reason: `acpx ${executor.kind} send failed to start: ${sendResult.error.message}`
+        });
+        return;
     }
     if (sendResult.status !== 0) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        const reason = cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`);
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1411,11 +1649,22 @@ function runSend(options) {
                 message,
                 failedStage: "message_send",
                 result: sendResult,
-                reason: cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`)
+                reason
             }));
             return;
         }
-        throw new Error(cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`));
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "message_send",
+            result: sendResult,
+            reason
+        });
+        return;
     }
     const deliveredConversation = markTakeoverBootstrapped({
         conversation: nextConversation,
@@ -1433,6 +1682,94 @@ function runSend(options) {
         budget: budgetAction(deliveredConversation)
     });
 }
+async function runApprove(options) {
+    cleanupIdleConversations(storeDirFromOptions(options), options);
+    const { conversation, statePath, logPath } = loadConversationFromOptions(options);
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const terminalControl = terminalControlFromTakeover(nativeTakeover);
+    if (!terminalControl) {
+        throw new Error(`conversation ${conversation.conversation_id} is not controlled through a terminal`);
+    }
+    const provider = createTerminalControlProvider(options);
+    const screen = await provider.capture(terminalControl.target, {
+        scrollbackLines: Number(options.scrollbackLines ?? 120)
+    });
+    const approval = detectCodexApprovalPrompt(screen);
+    if (!approval.approvable) {
+        printJson({
+            conversation,
+            approved: false,
+            blocked: true,
+            reason: approval.reason,
+            terminal_control: terminalControl,
+            screen_excerpt: screenExcerpt(screen)
+        });
+        return;
+    }
+    await provider.sendKeys(terminalControl.target, [approval.key]);
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "terminal_approval_send",
+        terminal_control: terminalControl,
+        key: approval.key,
+        label: approval.label
+    });
+    runtimeLog("info", "terminal_approval_send", {
+        conversation_id: conversation.conversation_id,
+        terminal_target: terminalControl.target,
+        key: approval.key,
+        label: approval.label
+    });
+    saveState(statePath, {
+        ...conversation,
+        updated_at: new Date().toISOString()
+    });
+    printJson({
+        conversation,
+        approved: true,
+        terminal_control: terminalControl,
+        key: approval.key,
+        label: approval.label
+    });
+}
+async function runTerminalControlSend({ options, conversation, nextConversation, statePath, logPath, executor, message, terminalControl, needsNativeTakeoverBootstrap }) {
+    const provider = createTerminalControlProvider(options);
+    await provider.sendText(terminalControl.target, String(message.body ?? ""));
+    await provider.sendKeys(terminalControl.target, ["Enter"]);
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "terminal_message_send",
+        executor,
+        terminal_control: terminalControl,
+        message: textSummary(message.body)
+    });
+    runtimeLog("info", "terminal_message_send", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        terminal_target: terminalControl.target,
+        message: textSummary(message.body)
+    });
+    const deliveredConversation = markTakeoverBootstrapped({
+        conversation: nextConversation,
+        statePath,
+        logPath,
+        executor,
+        native: needsNativeTakeoverBootstrap,
+        fork: false
+    });
+    printJson({
+        conversation: deliveredConversation,
+        message,
+        delivered: true,
+        terminal_control: terminalControl,
+        executor,
+        budget: budgetAction(deliveredConversation)
+    });
+}
 function runNativeCodexResumeSend({ options, conversation, nextConversation, statePath, logPath, executor, executorEnv, message, payload, nativeTakeover, needsNativeTakeoverBootstrap }) {
     const codexPath = resolveExecutable("codex");
     const nativeSessionId = String(nativeTakeover["native_session_id"]);
@@ -1715,11 +2052,35 @@ function markForkSessionBootstrapped({ conversation, statePath, logPath, executo
     });
     return nextConversation;
 }
-function requiresExplicitRecoveryDecision(executor, options = {}) {
+function requiresExplicitRecoveryDecision(options = {}) {
     if (options.recoveryPolicy === "explicit" || options.recoveryPolicy === "explicit-decision") {
         return true;
     }
-    return sessionRecoveryStrategyForExecutor(executor) === "explicit-decision";
+    return false;
+}
+function autoRecoverSendFailure({ options, conversation, statePath, logPath, executor, message, failedStage, result, reason }) {
+    markConversationNeedsRecovery({
+        conversation,
+        statePath,
+        logPath,
+        executor,
+        message,
+        failedStage,
+        result,
+        reason
+    });
+    runtimeLog("info", "conversation_auto_recovery_start", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        failed_stage: failedStage,
+        reason: textSummary(reason)
+    });
+    runRecoveryDecision({
+        ...options,
+        mode: "recover",
+        autoRecovered: true
+    });
 }
 function markConversationNeedsRecovery({ conversation, statePath, logPath, executor, message, failedStage, result, reason }) {
     const now = new Date().toISOString();
@@ -1733,7 +2094,7 @@ function markConversationNeedsRecovery({ conversation, statePath, logPath, execu
         failed_message_id: message.id,
         pending_message: message,
         previous_executor: executor,
-        options: ["recover", "restart", "close"]
+        options: ["recover", "close", "delegate"]
     };
     const nextConversation = {
         ...conversation,
@@ -1837,9 +2198,6 @@ function runCancel(options) {
 function runRecover(options) {
     runRecoveryDecision({ ...options, mode: "recover" });
 }
-function runRestart(options) {
-    runRecoveryDecision({ ...options, mode: "restart" });
-}
 function runRecoveryDecision(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
@@ -1871,9 +2229,7 @@ function runRecoveryDecision(options) {
         updated_at: now
     };
     saveState(statePath, recoveredConversation);
-    const payload = options.mode === "recover"
-        ? buildRecoverPayload({ conversation, pendingMessage, logPath })
-        : buildRestartPayload({ pendingMessage });
+    const payload = buildRecoverPayload({ conversation, pendingMessage, logPath });
     const acpxPath = resolveExecutable("acpx");
     const executorEnv = environmentForExecutor(executor, {
         allProxy: options.allProxy ?? conversation.executor_all_proxy
@@ -1935,8 +2291,8 @@ function runRecoveryDecision(options) {
         });
         printJson({
             conversation: recoveredConversation,
-            recovered: options.mode === "recover",
-            restarted: options.mode === "restart",
+            recovered: true,
+            auto_recovered: Boolean(options.autoRecovered),
             background: true,
             pid: child.pid ?? null,
             monitor_pid: monitor.pid ?? null,
@@ -1970,8 +2326,8 @@ function runRecoveryDecision(options) {
     }
     printJson({
         conversation: recoveredConversation,
-        recovered: options.mode === "recover",
-        restarted: options.mode === "restart",
+        recovered: true,
+        auto_recovered: Boolean(options.autoRecovered),
         delivered: true,
         executor,
         budget: budgetAction(recoveredConversation)
@@ -1994,16 +2350,6 @@ function buildRecoverPayload({ conversation, pendingMessage, logPath }) {
         JSON.stringify(pendingMessage)
     ].join("\n");
 }
-function buildRestartPayload({ pendingMessage }) {
-    return [
-        "Restart this Agent Knock Knock task in a new ACPX session.",
-        "Do not assume the previous coding-agent session context is available.",
-        "Follow only the pending OpenClaw message below.",
-        "Continue to report back only through the callback command already provided for this conversation.",
-        "",
-        JSON.stringify(pendingMessage)
-    ].join("\n");
-}
 function formatProtocolHistoryForRecovery(events) {
     const lines = events
         .filter((event) => event.event === "message")
@@ -3297,6 +3643,9 @@ function required(value, message) {
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
 function parseOptionalJson(text) {
     try {
         return JSON.parse(String(text));
@@ -3465,14 +3814,14 @@ function usage() {
   agent-knock-knock list [--store-dir <dir>] [--agent ${agentList}] [--status <status>] [--all]
   agent-knock-knock status --conversation <id> [--store-dir <dir>] [--trace]
   agent-knock-knock send --conversation <id> --message <text> [--type answer|task|control] [--all-proxy <url>] [--agent-timeout-minutes <minutes>]
+  agent-knock-knock approve --conversation <id>
   agent-knock-knock cancel --conversation <id> [--all-proxy <url>]
   agent-knock-knock recover --conversation <id> [--session <name>] [--all-proxy <url>]
-  agent-knock-knock restart --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>] [--no-restart]
   agent-knock-knock doctor
   agent-knock-knock agent discover --agent codex --scope capabilities|sessions|active
-  agent-knock-knock agent takeover --agent codex --session-id <id> --strategy safe_resume|terminate_then_resume|fork [--create-conversation]
+  agent-knock-knock agent takeover --agent codex --session-id <id> --strategy safe_resume|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]
   agent-knock-knock transcript --conversation <dir> [--include-raw]