@scotthuang/agent-knock-knock 0.1.0

package/dist/src/cli.js

@@ -0,0 +1,2364 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { applyMessageToConversation, budgetAction, createConversation, createMessage, executorForConversation, extractStructuredMessage, parseMessageJson, resolveExecutor } from "./protocol.js";
+import { EXECUTOR_KINDS, acpxCommandForExecutor, executorDefinitionForKind, modelEnvForExecutor, proxyEnvForExecutor, sessionRecoveryStrategyForExecutor } 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";
+const DEFAULT_IDLE_TIMEOUT_MINUTES = 10080;
+const DEFAULT_AGENT_TIMEOUT_MINUTES = 60;
+const DEFAULT_MONITOR_POLL_INTERVAL_MS = 5000;
+const command = process.argv[2];
+const args = parseArgs(process.argv.slice(3));
+runtimeLog("info", "cli_start", {
+    command: command ?? "help",
+    cwd: process.cwd(),
+    option_keys: Object.keys(args).sort()
+});
+try {
+    runCommand(command, args);
+    runtimeLog("info", "cli_finish", {
+        command: command ?? "help",
+        exit_code: process.exitCode ?? 0
+    });
+}
+catch (error) {
+    runtimeLog("error", "cli_error", {
+        command: command ?? "help",
+        message: error.message,
+        stack: error.stack
+    });
+    console.error(error.message);
+    process.exit(1);
+}
+function runCommand(commandName, options) {
+    if (commandName === "new") {
+        runNew(options);
+    }
+    else if (commandName === "record") {
+        runRecord(options);
+    }
+    else if (commandName === "bootstrap-prompt") {
+        runBootstrapPrompt(options);
+    }
+    else if (commandName === "delegate") {
+        runDelegate(options);
+    }
+    else if (commandName === "list") {
+        runList(options);
+    }
+    else if (commandName === "status") {
+        runStatus(options);
+    }
+    else if (commandName === "send") {
+        runSend(options);
+    }
+    else if (commandName === "cancel") {
+        runCancel(options);
+    }
+    else if (commandName === "recover") {
+        runRecover(options);
+    }
+    else if (commandName === "restart") {
+        runRestart(options);
+    }
+    else if (commandName === "close") {
+        runClose(options);
+    }
+    else if (commandName === "transcript") {
+        runTranscript(options);
+    }
+    else if (commandName === "install-openclaw") {
+        runInstallOpenClaw(options);
+    }
+    else if (commandName === "doctor") {
+        runDoctor(options);
+    }
+    else if (commandName === "callback") {
+        runCallback(options);
+    }
+    else if (commandName === "monitor") {
+        runMonitor(options);
+    }
+    else {
+        usage();
+        process.exitCode = commandName ? 1 : 0;
+    }
+}
+function runInstallOpenClaw(options) {
+    const root = packageRootDir();
+    const openclawBin = options.openclawBin ?? resolveExecutable("openclaw");
+    const skillSource = path.join(root, "templates", "openclaw-skills", "agent-knock-knock", "SKILL.md");
+    const skillDest = expandHome(options.skillPath ?? "~/.openclaw/skills/agent-knock-knock/SKILL.md");
+    const steps = [];
+    runCheckedCommand(openclawBin, ["plugins", "install", "--link", root], {
+        label: "openclaw plugins install"
+    });
+    steps.push({
+        name: "plugin_installed",
+        path: root
+    });
+    runCheckedCommand(openclawBin, ["plugins", "enable", "agent-knock-knock"], {
+        label: "openclaw plugins enable"
+    });
+    steps.push({
+        name: "plugin_enabled",
+        plugin: "agent-knock-knock"
+    });
+    fs.mkdirSync(path.dirname(skillDest), { recursive: true });
+    fs.copyFileSync(skillSource, skillDest);
+    steps.push({
+        name: "skill_installed",
+        path: skillDest
+    });
+    if (options.noRestart !== true) {
+        runCheckedCommand(openclawBin, ["gateway", "restart"], {
+            label: "openclaw gateway restart"
+        });
+        steps.push({
+            name: "gateway_restarted"
+        });
+    }
+    printJson({
+        installed: true,
+        package_root: root,
+        openclaw_bin: openclawBin,
+        steps,
+        next: options.noRestart === true
+            ? "Restart the OpenClaw Gateway before using Agent Knock Knock."
+            : "Agent Knock Knock is installed. Try: AKK list"
+    });
+}
+function runDoctor(options) {
+    const commands = ["node", "openclaw", "acpx", "codex", "claude", "cursor"];
+    const checks = commands.map((commandName) => executableCheck(commandName));
+    const root = packageRootDir();
+    const packageFiles = [
+        "dist/src/cli.js",
+        "dist/src/openclaw-plugin.js",
+        "templates/openclaw-skills/agent-knock-knock/SKILL.md",
+        "openclaw.plugin.json"
+    ].map((relativePath) => {
+        const filePath = path.join(root, relativePath);
+        return {
+            path: filePath,
+            exists: fs.existsSync(filePath)
+        };
+    });
+    const requiredOk = checks
+        .filter((check) => ["node", "openclaw", "acpx"].includes(check.command))
+        .every((check) => check.available);
+    const agentOk = checks
+        .filter((check) => ["codex", "claude", "cursor"].includes(check.command))
+        .some((check) => check.available);
+    const filesOk = packageFiles.every((check) => check.exists);
+    printJson({
+        ok: requiredOk && agentOk && filesOk,
+        package_root: root,
+        checks,
+        package_files: packageFiles,
+        notes: [
+            "node, openclaw, and acpx are required.",
+            "At least one local coding agent command should be available: codex, claude, or cursor."
+        ],
+        options
+    });
+}
+function runNew(options) {
+    const request = required(options.request, "--request is required");
+    const workspace = options.workspace ?? process.cwd();
+    cleanupIdleConversations(expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace)), options);
+    const executor = resolveExecutor({
+        kind: options.agent ?? "claude",
+        session: options.session ?? options.executorSession ?? options.claudeSession
+    });
+    const conversation = createConversation({
+        userRequest: request,
+        workspace,
+        openclawSession: options.openclawSession ?? "agent:main:main",
+        claudeSession: options.claudeSession ?? "bidirectional",
+        executorKind: executor.kind,
+        executorSession: executor.session,
+        softLimit: Number(options.softLimit ?? 50),
+        hardLimit: Number(options.hardLimit ?? 100)
+    });
+    const taskMessage = createMessage({
+        conversation,
+        from: "openclaw",
+        to: executor.actor,
+        type: "task",
+        body: request,
+        metadata: {
+            executor_kind: executor.kind,
+            executor_session: executor.session
+        }
+    });
+    const nextConversation = applyMessageToConversation(conversation, taskMessage);
+    const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
+    const paths = pathsForConversation(conversation.conversation_id, storeDir);
+    const storedConversation = withStoragePaths(nextConversation, paths);
+    saveState(paths.statePath, storedConversation);
+    appendEvent(paths.logPath, {
+        ts: conversation.created_at,
+        conversation_id: conversation.conversation_id,
+        event: "conversation_created",
+        conversation: storedConversation
+    });
+    appendEvent(paths.logPath, messageEvent(taskMessage));
+    runtimeLog("info", "conversation_created", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        workspace,
+        store_dir: storeDir,
+        state_path: paths.statePath,
+        event_log_path: paths.logPath,
+        request: textSummary(request)
+    });
+    printJson({
+        conversation: storedConversation,
+        paths,
+        task_message: taskMessage,
+        budget: budgetAction(storedConversation)
+    });
+}
+function runRecord(options) {
+    const statePath = required(options.state, "--state is required");
+    const messageInput = required(options.messageJson, "--message-json is required");
+    const logPath = options.log ?? logPathForStatePath(statePath);
+    const conversation = loadState(expandHome(statePath));
+    const message = parseMessageJson(messageInput);
+    const nextConversation = applyMessageToConversation(conversation, message);
+    appendEvent(expandHome(logPath), messageEvent(message));
+    saveState(expandHome(statePath), nextConversation);
+    printJson({
+        conversation: nextConversation,
+        budget: budgetAction(nextConversation)
+    });
+}
+function runBootstrapPrompt(options) {
+    const callbackCommand = required(options.callbackCommand, "--callback-command is required");
+    const executor = resolveExecutor({
+        kind: options.agent ?? "claude",
+        session: options.session ?? options.claudeSession
+    });
+    process.stdout.write(executorBootstrapPrompt({
+        callbackCommand,
+        executorName: executor.display_name,
+        softLimit: Number(options.softLimit ?? 50),
+        hardLimit: Number(options.hardLimit ?? 100)
+    }));
+}
+function runDelegate(options) {
+    const request = required(options.request, "--request is required");
+    const workspace = options.workspace ?? process.cwd();
+    const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
+    cleanupIdleConversations(storeDir, options);
+    const explicitExecutorSession = options.session ?? options.executorSession ?? options.claudeSession;
+    const executor = resolveExecutor({
+        kind: options.agent ?? "claude",
+        session: explicitExecutorSession ?? uniqueDelegateSessionName(options.agent ?? "claude")
+    });
+    const newResult = captureJson([
+        "new",
+        "--request",
+        request,
+        "--workspace",
+        workspace,
+        "--openclaw-session",
+        options.openclawSession ?? "agent:main:main",
+        "--agent",
+        executor.kind,
+        "--session",
+        executor.session,
+        "--soft-limit",
+        String(options.softLimit ?? 50),
+        "--hard-limit",
+        String(options.hardLimit ?? 100),
+        "--store-dir",
+        storeDir
+    ]);
+    const gatewayUrl = options.gatewayUrl ?? "ws://127.0.0.1:18789";
+    if (options.send && !options.token) {
+        throw new Error("--token is required when using --send");
+    }
+    const openclawSession = options.openclawSession ?? "agent:main:main";
+    const openclawBin = options.openclawBin ?? resolveOptionalExecutable("openclaw");
+    const executorEnv = environmentForExecutor(executor, options);
+    const executorAllProxy = proxyForExecutor(executor, options);
+    const executorModel = modelForExecutor(executor, options);
+    const callbackCommand = options.callbackCommand
+        ? expandCallbackCommandTemplate(options.callbackCommand, { statePath: newResult.paths.statePath })
+        : buildCallbackCommand({
+            statePath: newResult.paths.statePath,
+            gatewayUrl,
+            token: options.token,
+            openclawSession,
+            gatewayMethod: options.gatewayMethod,
+            gatewaySession: options.gatewaySession,
+            openclawBin
+        });
+    const conversationWithCallback = {
+        ...newResult.conversation,
+        gateway_url: gatewayUrl,
+        callback_command: callbackCommand,
+        gateway_method: options.gatewayMethod,
+        gateway_session: options.gatewaySession ?? openclawSession,
+        openclaw_bin: openclawBin,
+        executor_all_proxy: executorAllProxy,
+        executor_model: executorModel
+    };
+    saveState(newResult.paths.statePath, conversationWithCallback);
+    newResult.conversation = conversationWithCallback;
+    runtimeLog("info", "delegate_created", {
+        conversation_id: newResult.conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        workspace,
+        store_dir: storeDir,
+        state_path: newResult.paths.statePath,
+        gateway_method: options.gatewayMethod,
+        background: Boolean(options.background),
+        request: textSummary(request)
+    });
+    const bootstrap = executorBootstrapPrompt({
+        callbackCommand,
+        executorName: executor.display_name,
+        softLimit: Number(options.softLimit ?? 50),
+        hardLimit: Number(options.hardLimit ?? 100)
+    });
+    const payload = `${bootstrap}\n\nInitial task message:\n${JSON.stringify(newResult.task_message)}`;
+    const acpxArgs = buildAcpxPromptArgs({ executor, payload, model: executorModel });
+    if (options.background) {
+        const acpxPath = resolveExecutable("acpx");
+        const ensureSession = ensureExecutorSession({
+            acpxPath,
+            executor,
+            cwd: workspace,
+            env: executorEnv
+        });
+        appendEvent(newResult.paths.logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: newResult.conversation.conversation_id,
+            event: "executor_session_ensure",
+            status: ensureSession.status ?? null,
+            executor,
+            stdout: cleanProcessText(ensureSession.stdout),
+            stderr: cleanProcessText(ensureSession.stderr)
+        });
+        runtimeLog("info", "executor_session_ensure", {
+            conversation_id: newResult.conversation.conversation_id,
+            agent: executor.kind,
+            executor_session: executor.session,
+            status: ensureSession.status ?? null,
+            failure_kind: classifyProcessFailure(ensureSession),
+            stdout: textSummary(cleanProcessText(ensureSession.stdout)),
+            stderr: textSummary(cleanProcessText(ensureSession.stderr))
+        });
+        if (executor.kind === "claude") {
+            appendEvent(newResult.paths.logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: newResult.conversation.conversation_id,
+                event: "claude_session_ensure",
+                status: ensureSession.status ?? null,
+                claude_session: executor.session,
+                stdout: cleanProcessText(ensureSession.stdout),
+                stderr: cleanProcessText(ensureSession.stderr)
+            });
+        }
+        if (ensureSession.error) {
+            throw new Error(`acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`);
+        }
+        if (ensureSession.status !== 0) {
+            throw new Error(cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`));
+        }
+        const outputPath = path.join(newResult.paths.conversationDir, `${executor.kind}-output.log`);
+        const outputFd = fs.openSync(outputPath, "a");
+        const child = spawn(acpxPath, acpxArgs, {
+            detached: true,
+            stdio: ["ignore", outputFd, outputFd],
+            env: executorEnv,
+            cwd: workspace
+        });
+        child.unref();
+        fs.closeSync(outputFd);
+        appendEvent(newResult.paths.logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: newResult.conversation.conversation_id,
+            event: "executor_launch",
+            mode: "background",
+            pid: child.pid ?? null,
+            executor,
+            output_path: outputPath
+        });
+        runtimeLog("info", "executor_launch", {
+            conversation_id: newResult.conversation.conversation_id,
+            agent: executor.kind,
+            executor_session: executor.session,
+            mode: "background",
+            pid: child.pid ?? null,
+            output_path: outputPath
+        });
+        if (executor.kind === "claude") {
+            appendEvent(newResult.paths.logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: newResult.conversation.conversation_id,
+                event: "claude_launch",
+                mode: "background",
+                pid: child.pid ?? null,
+                claude_session: executor.session,
+                output_path: outputPath
+            });
+        }
+        const monitor = startExecutorMonitor({
+            statePath: newResult.paths.statePath,
+            logPath: newResult.paths.logPath,
+            pid: child.pid,
+            outputPath,
+            agentTimeoutMinutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES),
+            pollIntervalMs: Number(options.monitorPollIntervalMs ?? DEFAULT_MONITOR_POLL_INTERVAL_MS)
+        });
+        appendEvent(newResult.paths.logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: newResult.conversation.conversation_id,
+            event: "executor_monitor_launch",
+            pid: monitor.pid ?? null,
+            executor_pid: child.pid ?? null,
+            agent_timeout_minutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES)
+        });
+        runtimeLog("info", "executor_monitor_launch", {
+            conversation_id: newResult.conversation.conversation_id,
+            monitor_pid: monitor.pid ?? null,
+            executor_pid: child.pid ?? null,
+            agent_timeout_minutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES)
+        });
+        printJson({
+            ...newResult,
+            launched: true,
+            background: true,
+            pid: child.pid ?? null,
+            monitor_pid: monitor.pid ?? null,
+            output_path: outputPath
+        });
+        return;
+    }
+    if (options.send) {
+        const acpxPath = resolveExecutable("acpx");
+        const ensureSession = ensureExecutorSession({
+            acpxPath,
+            executor,
+            cwd: workspace,
+            env: executorEnv
+        });
+        if (ensureSession.error) {
+            throw new Error(`acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`);
+        }
+        if (ensureSession.status !== 0) {
+            throw new Error(cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`));
+        }
+        const result = spawnSync(acpxPath, acpxArgs, {
+            stdio: "inherit",
+            cwd: workspace,
+            env: executorEnv
+        });
+        runtimeLog("info", "executor_send", {
+            conversation_id: newResult.conversation.conversation_id,
+            agent: executor.kind,
+            executor_session: executor.session,
+            status: result.status ?? null,
+            failure_kind: classifyProcessFailure(result)
+        });
+        process.exitCode = result.status ?? 1;
+        return;
+    }
+    runtimeLog("info", "delegate_dry_run", {
+        conversation_id: newResult.conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session
+    });
+    printJson({
+        ...newResult,
+        dry_run: true,
+        acpx_command: ["acpx", ...acpxArgs],
+        note: "Run again with --send to send this task through acpx."
+    });
+}
+function ensureExecutorSession({ acpxPath, executor, cwd, env }) {
+    return spawnSync(acpxPath, [acpxCommandForExecutor(executor), "sessions", "ensure", "--name", executor.session], {
+        encoding: "utf8",
+        cwd,
+        env
+    });
+}
+function startExecutorMonitor({ statePath, logPath, pid, outputPath, agentTimeoutMinutes, pollIntervalMs }) {
+    const args = [
+        new URL(import.meta.url).pathname,
+        "monitor",
+        "--state",
+        statePath,
+        "--log",
+        logPath,
+        "--agent-timeout-minutes",
+        String(agentTimeoutMinutes),
+        "--poll-interval-ms",
+        String(pollIntervalMs)
+    ];
+    if (pid) {
+        args.push("--pid", String(pid));
+    }
+    if (outputPath) {
+        args.push("--output-path", outputPath);
+    }
+    const child = spawn(process.execPath, args, {
+        detached: true,
+        stdio: "ignore",
+        cwd: process.cwd(),
+        env: process.env
+    });
+    child.unref();
+    return child;
+}
+function uniqueDelegateSessionName(kind) {
+    const { sessionPrefix } = executorDefinitionForKind(kind || "claude");
+    const timestamp = new Date().toISOString().replace(/\D/g, "").slice(0, 14);
+    return `${sessionPrefix}-${timestamp}-${randomUUID().slice(0, 8)}`;
+}
+function buildAcpxPromptArgs({ executor, payload, model }) {
+    const args = ["--approve-all"];
+    if (model) {
+        args.push("--model", model);
+    }
+    args.push(acpxCommandForExecutor(executor), "-s", executor.session, payload);
+    return args;
+}
+function proxyForExecutor(executor, options = {}) {
+    const explicit = options.allProxy ?? options.proxy;
+    if (explicit) {
+        return explicit;
+    }
+    return proxyEnvForExecutor(executor, process.env);
+}
+function modelForExecutor(executor, options = {}) {
+    const explicit = options.model ?? options.codexModel;
+    if (explicit) {
+        return explicit;
+    }
+    return modelEnvForExecutor(executor, process.env);
+}
+function environmentForExecutor(executor, options = {}) {
+    const proxy = proxyForExecutor(executor, options);
+    if (!proxy) {
+        return process.env;
+    }
+    return {
+        ...process.env,
+        ALL_PROXY: proxy,
+        all_proxy: proxy
+    };
+}
+function runList(options) {
+    const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(process.cwd()));
+    const cleanup = cleanupIdleConversations(storeDir, 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))
+        .filter((conversation) => includeAll || isActiveStatus(conversation.status))
+        .filter((conversation) => !agentFilter || conversation.agent === agentFilter)
+        .filter((conversation) => !statusFilter || conversation.status === statusFilter);
+    printJson({
+        store_dir: storeDir,
+        cleanup,
+        tasks: conversations
+    });
+    runtimeLog("info", "tasks_listed", {
+        store_dir: storeDir,
+        returned_count: conversations.length,
+        include_all: includeAll,
+        agent_filter: agentFilter,
+        status_filter: statusFilter,
+        cleanup
+    });
+}
+function runStatus(options) {
+    cleanupIdleConversations(storeDirFromOptions(options), options);
+    const { conversation, statePath, logPath } = loadConversationFromOptions(options);
+    const events = readExistingEvents(logPath);
+    const result = {
+        conversation,
+        summary: summarizeConversation(conversation),
+        state_path: statePath,
+        event_log_path: logPath,
+        budget: budgetAction(conversation),
+        recent_events: events.slice(-10).map(summarizeEvent)
+    };
+    if (options.trace) {
+        result.trace = buildConversationTrace({ conversation, events, logPath });
+    }
+    printJson(result);
+    runtimeLog("info", "task_status_read", {
+        conversation_id: conversation.conversation_id,
+        status: conversation.status,
+        state_path: statePath,
+        event_log_path: logPath,
+        recent_event_count: Math.min(events.length, 10),
+        trace: Boolean(options.trace)
+    });
+}
+function runSend(options) {
+    const messageBody = required(options.message ?? options.request, "--message is required");
+    cleanupIdleConversations(storeDirFromOptions(options), options);
+    const { conversation, statePath, logPath } = loadConversationFromOptions(options);
+    if (["done", "failed", "closed", "cancelled"].includes(conversation.status)) {
+        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`);
+    }
+    const executor = executorForConversation(conversation);
+    const type = options.type ?? (conversation.status === "waiting_for_openclaw" ? "answer" : "task");
+    const message = createMessage({
+        conversation,
+        from: "openclaw",
+        to: executor.actor,
+        type,
+        body: messageBody,
+        metadata: {
+            executor_kind: executor.kind,
+            executor_session: executor.session
+        }
+    });
+    const nextConversation = {
+        ...applyMessageToConversation(conversation, message),
+        executor,
+        claude_session: executor.kind === "claude" ? executor.session : conversation.claude_session
+    };
+    saveState(statePath, nextConversation);
+    appendEvent(logPath, messageEvent(message));
+    runtimeLog("info", "message_created", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        message_type: type,
+        state_path: statePath,
+        event_log_path: logPath,
+        message: textSummary(messageBody)
+    });
+    const acpxPath = resolveExecutable("acpx");
+    const executorEnv = environmentForExecutor(executor, {
+        allProxy: options.allProxy ?? conversation.executor_all_proxy
+    });
+    const executorModel = modelForExecutor(executor, {
+        model: options.model ?? conversation.executor_model
+    });
+    const ensureSession = ensureExecutorSession({
+        acpxPath,
+        executor,
+        cwd: conversation.workspace ?? process.cwd(),
+        env: executorEnv
+    });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "executor_session_ensure",
+        status: ensureSession.status ?? null,
+        executor,
+        stdout: cleanProcessText(ensureSession.stdout),
+        stderr: cleanProcessText(ensureSession.stderr)
+    });
+    runtimeLog("info", "executor_session_ensure", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        status: ensureSession.status ?? null,
+        failure_kind: classifyProcessFailure(ensureSession),
+        stdout: textSummary(cleanProcessText(ensureSession.stdout)),
+        stderr: textSummary(cleanProcessText(ensureSession.stderr))
+    });
+    if (ensureSession.error) {
+        if (requiresExplicitRecoveryDecision(executor, options)) {
+            printJson(markConversationNeedsRecovery({
+                conversation: nextConversation,
+                statePath,
+                logPath,
+                executor,
+                message,
+                failedStage: "session_ensure",
+                result: ensureSession,
+                reason: `acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`
+            }));
+            return;
+        }
+        throw new Error(`acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`);
+    }
+    if (ensureSession.status !== 0) {
+        if (requiresExplicitRecoveryDecision(executor, options)) {
+            printJson(markConversationNeedsRecovery({
+                conversation: nextConversation,
+                statePath,
+                logPath,
+                executor,
+                message,
+                failedStage: "session_ensure",
+                result: ensureSession,
+                reason: cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`)
+            }));
+            return;
+        }
+        throw new Error(cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`));
+    }
+    const payload = [
+        "Continue the existing Agent Knock Knock delegation using this structured OpenClaw message.",
+        "If this message answers a question or blocker, follow it as the product decision.",
+        "Continue to report back only through the callback command already provided for this conversation.",
+        "",
+        JSON.stringify(message)
+    ].join("\n");
+    const acpxArgs = buildAcpxPromptArgs({ executor, payload, model: executorModel });
+    if (options.background) {
+        const outputPath = path.join(path.dirname(logPath), `${executor.kind}-followup-output.log`);
+        const outputFd = fs.openSync(outputPath, "a");
+        const child = spawn(acpxPath, acpxArgs, {
+            detached: true,
+            stdio: ["ignore", outputFd, outputFd],
+            cwd: conversation.workspace ?? process.cwd(),
+            env: executorEnv
+        });
+        child.unref();
+        fs.closeSync(outputFd);
+        appendEvent(logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: conversation.conversation_id,
+            event: "executor_message_launch",
+            mode: "background",
+            pid: child.pid ?? null,
+            executor,
+            output_path: outputPath
+        });
+        runtimeLog("info", "executor_message_launch", {
+            conversation_id: conversation.conversation_id,
+            agent: executor.kind,
+            executor_session: executor.session,
+            mode: "background",
+            pid: child.pid ?? null,
+            output_path: outputPath
+        });
+        const monitor = startExecutorMonitor({
+            statePath,
+            logPath,
+            pid: child.pid,
+            outputPath,
+            agentTimeoutMinutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES),
+            pollIntervalMs: Number(options.monitorPollIntervalMs ?? DEFAULT_MONITOR_POLL_INTERVAL_MS)
+        });
+        appendEvent(logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: conversation.conversation_id,
+            event: "executor_monitor_launch",
+            pid: monitor.pid ?? null,
+            executor_pid: child.pid ?? null,
+            agent_timeout_minutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES)
+        });
+        printJson({
+            conversation: nextConversation,
+            message,
+            delivered: true,
+            background: true,
+            pid: child.pid ?? null,
+            monitor_pid: monitor.pid ?? null,
+            output_path: outputPath,
+            executor,
+            budget: budgetAction(nextConversation)
+        });
+        return;
+    }
+    const sendResult = spawnSync(acpxPath, acpxArgs, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10,
+        cwd: conversation.workspace ?? process.cwd(),
+        env: executorEnv
+    });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "executor_message_send",
+        status: sendResult.status ?? null,
+        executor,
+        stdout: cleanProcessText(sendResult.stdout),
+        stderr: cleanProcessText(sendResult.stderr)
+    });
+    runtimeLog("info", "executor_message_send", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        status: sendResult.status ?? null,
+        failure_kind: classifyProcessFailure(sendResult),
+        stdout: textSummary(cleanProcessText(sendResult.stdout)),
+        stderr: textSummary(cleanProcessText(sendResult.stderr))
+    });
+    if (sendResult.error) {
+        if (requiresExplicitRecoveryDecision(executor, options)) {
+            printJson(markConversationNeedsRecovery({
+                conversation: nextConversation,
+                statePath,
+                logPath,
+                executor,
+                message,
+                failedStage: "message_send",
+                result: sendResult,
+                reason: `acpx ${executor.kind} send failed to start: ${sendResult.error.message}`
+            }));
+            return;
+        }
+        throw new Error(`acpx ${executor.kind} send failed to start: ${sendResult.error.message}`);
+    }
+    if (sendResult.status !== 0) {
+        if (requiresExplicitRecoveryDecision(executor, options)) {
+            printJson(markConversationNeedsRecovery({
+                conversation: nextConversation,
+                statePath,
+                logPath,
+                executor,
+                message,
+                failedStage: "message_send",
+                result: sendResult,
+                reason: cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`)
+            }));
+            return;
+        }
+        throw new Error(cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`));
+    }
+    printJson({
+        conversation: nextConversation,
+        message,
+        delivered: true,
+        executor,
+        budget: budgetAction(nextConversation)
+    });
+}
+function requiresExplicitRecoveryDecision(executor, options = {}) {
+    if (options.recoveryPolicy === "explicit" || options.recoveryPolicy === "explicit-decision") {
+        return true;
+    }
+    return sessionRecoveryStrategyForExecutor(executor) === "explicit-decision";
+}
+function markConversationNeedsRecovery({ conversation, statePath, logPath, executor, message, failedStage, result, reason }) {
+    const now = new Date().toISOString();
+    const failureKind = classifyProcessFailure(result);
+    const recovery = {
+        reason: "executor_session_unavailable",
+        detail: reason,
+        failed_at: now,
+        failed_stage: failedStage,
+        failure_kind: failureKind,
+        failed_message_id: message.id,
+        pending_message: message,
+        previous_executor: executor,
+        options: ["recover", "restart", "close"]
+    };
+    const nextConversation = {
+        ...conversation,
+        status: "needs_recovery",
+        recovery,
+        updated_at: now
+    };
+    saveState(statePath, nextConversation);
+    appendEvent(logPath, {
+        ts: now,
+        conversation_id: conversation.conversation_id,
+        event: "conversation_needs_recovery",
+        status: "needs_recovery",
+        executor,
+        failed_stage: failedStage,
+        failure_kind: failureKind,
+        reason
+    });
+    runtimeLog("warn", "conversation_needs_recovery", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        failed_stage: failedStage,
+        failure_kind: failureKind,
+        reason: textSummary(reason)
+    });
+    return {
+        conversation: nextConversation,
+        message,
+        delivered: false,
+        requires_recovery_decision: true,
+        recovery,
+        executor,
+        budget: budgetAction(nextConversation)
+    };
+}
+function runCancel(options) {
+    cleanupIdleConversations(storeDirFromOptions(options), options);
+    const { conversation, statePath, logPath } = loadConversationFromOptions(options);
+    if (["closed", "cancelled"].includes(conversation.status)) {
+        throw new Error(`cannot cancel ${conversation.conversation_id}; conversation is ${conversation.status}`);
+    }
+    const executor = executorForConversation(conversation);
+    const acpxPath = resolveExecutable("acpx");
+    const executorEnv = environmentForExecutor(executor, {
+        allProxy: options.allProxy ?? conversation.executor_all_proxy
+    });
+    const acpxCommand = acpxCommandForExecutor(executor);
+    const cancelResult = spawnSync(acpxPath, [acpxCommand, "cancel", "-s", executor.session], {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10,
+        cwd: conversation.workspace ?? process.cwd(),
+        env: executorEnv
+    });
+    const now = new Date().toISOString();
+    appendEvent(logPath, {
+        ts: now,
+        conversation_id: conversation.conversation_id,
+        event: "executor_cancel_requested",
+        status: cancelResult.status ?? null,
+        executor,
+        stdout: cleanProcessText(cancelResult.stdout),
+        stderr: cleanProcessText(cancelResult.stderr)
+    });
+    runtimeLog("info", "executor_cancel_requested", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        status: cancelResult.status ?? null,
+        failure_kind: classifyProcessFailure(cancelResult),
+        stdout: textSummary(cleanProcessText(cancelResult.stdout)),
+        stderr: textSummary(cleanProcessText(cancelResult.stderr))
+    });
+    if (cancelResult.error) {
+        throw new Error(`acpx ${executor.kind} cancel failed to start: ${cancelResult.error.message}`);
+    }
+    if (cancelResult.status !== 0) {
+        throw new Error(cleanProcessText(cancelResult.stderr || cancelResult.stdout || `acpx ${executor.kind} cancel exited with status ${cancelResult.status}`));
+    }
+    const nextConversation = {
+        ...conversation,
+        status: "cancelling",
+        cancel_requested_at: now,
+        updated_at: now
+    };
+    saveState(statePath, nextConversation);
+    runtimeLog("info", "conversation_cancelling", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        state_path: statePath
+    });
+    printJson({
+        conversation: nextConversation,
+        cancel_requested: true,
+        executor,
+        acpx_command: ["acpx", acpxCommand, "cancel", "-s", executor.session],
+        budget: budgetAction(nextConversation)
+    });
+}
+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);
+    if (conversation.status !== "needs_recovery") {
+        throw new Error(`cannot ${options.mode} ${conversation.conversation_id}; conversation is ${conversation.status}`);
+    }
+    const pendingMessage = conversation.recovery?.pending_message;
+    if (!isRecord(pendingMessage)) {
+        throw new Error(`cannot ${options.mode} ${conversation.conversation_id}; recovery pending message is missing`);
+    }
+    const previousExecutor = executorForConversation(conversation);
+    const executor = resolveExecutor({
+        kind: previousExecutor.kind,
+        session: options.session ?? uniqueDelegateSessionName(previousExecutor.kind)
+    });
+    const now = new Date().toISOString();
+    const recoveredConversation = {
+        ...conversation,
+        executor,
+        claude_session: executor.kind === "claude" ? executor.session : conversation.claude_session,
+        status: "waiting_for_agent",
+        recovery: {
+            ...conversation.recovery,
+            resolved_at: now,
+            resolution: options.mode,
+            previous_session: previousExecutor.session,
+            new_session: executor.session
+        },
+        updated_at: now
+    };
+    saveState(statePath, recoveredConversation);
+    const payload = options.mode === "recover"
+        ? buildRecoverPayload({ conversation, pendingMessage, logPath })
+        : buildRestartPayload({ pendingMessage });
+    const acpxPath = resolveExecutable("acpx");
+    const executorEnv = environmentForExecutor(executor, {
+        allProxy: options.allProxy ?? conversation.executor_all_proxy
+    });
+    const executorModel = modelForExecutor(executor, {
+        model: options.model ?? conversation.executor_model
+    });
+    const ensureSession = ensureExecutorSession({
+        acpxPath,
+        executor,
+        cwd: conversation.workspace ?? process.cwd(),
+        env: executorEnv
+    });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "executor_recovery_session_ensure",
+        mode: options.mode,
+        status: ensureSession.status ?? null,
+        executor,
+        stdout: cleanProcessText(ensureSession.stdout),
+        stderr: cleanProcessText(ensureSession.stderr)
+    });
+    if (ensureSession.error) {
+        throw new Error(`acpx ${executor.kind} recovery session ensure failed to start: ${ensureSession.error.message}`);
+    }
+    if (ensureSession.status !== 0) {
+        throw new Error(cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} recovery sessions ensure exited with status ${ensureSession.status}`));
+    }
+    const acpxArgs = buildAcpxPromptArgs({ executor, payload, model: executorModel });
+    if (options.background) {
+        const outputPath = path.join(path.dirname(logPath), `${executor.kind}-${options.mode}-output.log`);
+        const outputFd = fs.openSync(outputPath, "a");
+        const child = spawn(acpxPath, acpxArgs, {
+            detached: true,
+            stdio: ["ignore", outputFd, outputFd],
+            cwd: conversation.workspace ?? process.cwd(),
+            env: executorEnv
+        });
+        child.unref();
+        fs.closeSync(outputFd);
+        appendEvent(logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: conversation.conversation_id,
+            event: "executor_recovery_launch",
+            mode: options.mode,
+            run_mode: "background",
+            pid: child.pid ?? null,
+            executor,
+            output_path: outputPath
+        });
+        const monitor = startExecutorMonitor({
+            statePath,
+            logPath,
+            pid: child.pid,
+            outputPath,
+            agentTimeoutMinutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES),
+            pollIntervalMs: Number(options.monitorPollIntervalMs ?? DEFAULT_MONITOR_POLL_INTERVAL_MS)
+        });
+        printJson({
+            conversation: recoveredConversation,
+            recovered: options.mode === "recover",
+            restarted: options.mode === "restart",
+            background: true,
+            pid: child.pid ?? null,
+            monitor_pid: monitor.pid ?? null,
+            output_path: outputPath,
+            executor,
+            budget: budgetAction(recoveredConversation)
+        });
+        return;
+    }
+    const sendResult = spawnSync(acpxPath, acpxArgs, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10,
+        cwd: conversation.workspace ?? process.cwd(),
+        env: executorEnv
+    });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "executor_recovery_send",
+        mode: options.mode,
+        status: sendResult.status ?? null,
+        executor,
+        stdout: cleanProcessText(sendResult.stdout),
+        stderr: cleanProcessText(sendResult.stderr)
+    });
+    if (sendResult.error) {
+        throw new Error(`acpx ${executor.kind} recovery send failed to start: ${sendResult.error.message}`);
+    }
+    if (sendResult.status !== 0) {
+        throw new Error(cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} recovery send exited with status ${sendResult.status}`));
+    }
+    printJson({
+        conversation: recoveredConversation,
+        recovered: options.mode === "recover",
+        restarted: options.mode === "restart",
+        delivered: true,
+        executor,
+        budget: budgetAction(recoveredConversation)
+    });
+}
+function buildRecoverPayload({ conversation, pendingMessage, logPath }) {
+    return [
+        "Recover this Agent Knock Knock task in a new ACPX session.",
+        "The previous coding-agent session was unavailable. This is AKK replay recovery, not native agent session resume.",
+        "Use the saved protocol history summary below as context, then continue with the pending OpenClaw message.",
+        "Continue to report back only through the callback command already provided for this conversation.",
+        "",
+        "Task:",
+        conversation.user_request,
+        "",
+        "Saved protocol history:",
+        formatProtocolHistoryForRecovery(readExistingEvents(logPath)),
+        "",
+        "Pending OpenClaw message:",
+        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")
+        .map((event) => event.message ?? event)
+        .filter((message) => message?.from && message?.to && message?.type)
+        .slice(-40)
+        .map((message) => {
+        const body = String(message.body ?? "").replace(/\s+/g, " ").trim().slice(0, 700);
+        return `- round ${message.round ?? "?"}: ${message.from} -> ${message.to} ${message.type}: ${body}`;
+    });
+    return lines.length ? lines.join("\n") : "- No prior protocol messages were recorded.";
+}
+function runClose(options) {
+    const { conversation, statePath, logPath } = loadConversationFromOptions(options);
+    const now = new Date().toISOString();
+    const closed = {
+        ...conversation,
+        status: "closed",
+        closed_at: now,
+        close_reason: options.reason ?? "closed by request",
+        updated_at: now
+    };
+    saveState(statePath, closed);
+    appendEvent(logPath, {
+        ts: now,
+        conversation_id: conversation.conversation_id,
+        event: "conversation_closed",
+        status: "closed",
+        reason: closed.close_reason
+    });
+    runtimeLog("info", "conversation_closed", {
+        conversation_id: conversation.conversation_id,
+        status: "closed",
+        reason: closed.close_reason,
+        state_path: statePath,
+        event_log_path: logPath
+    });
+    printJson({
+        conversation: closed,
+        closed: true
+    });
+}
+function runMonitor(options) {
+    const statePath = expandHome(required(options.state, "--state is required"));
+    const logPath = expandHome(options.log ?? logPathForStatePath(statePath));
+    const pid = options.pid ? Number(options.pid) : undefined;
+    const timeoutMinutes = Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES);
+    const pollIntervalMs = Math.max(50, Number(options.pollIntervalMs ?? DEFAULT_MONITOR_POLL_INTERVAL_MS));
+    let conversation = loadState(statePath);
+    const executor = executorForConversation(conversation);
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "executor_monitor_started",
+        executor,
+        executor_pid: Number.isFinite(pid) ? pid : null,
+        agent_timeout_minutes: timeoutMinutes,
+        poll_interval_ms: pollIntervalMs,
+        output_path: options.outputPath
+    });
+    runtimeLog("info", "executor_monitor_started", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        executor_pid: Number.isFinite(pid) ? pid : null,
+        agent_timeout_minutes: timeoutMinutes
+    });
+    while (true) {
+        conversation = loadState(statePath);
+        if (!isWaitingForAgent(conversation.status)) {
+            runtimeLog("info", "executor_monitor_finished", {
+                conversation_id: conversation.conversation_id,
+                status: conversation.status,
+                reason: "conversation_no_longer_waiting"
+            });
+            printJson({
+                conversation,
+                monitored: true,
+                stalled: false,
+                reason: "conversation_no_longer_waiting"
+            });
+            return;
+        }
+        if (Number.isFinite(pid) && !isProcessAlive(pid)) {
+            const stalledConversation = markConversationStalled({
+                statePath,
+                logPath,
+                reason: `executor process ${pid} exited before callback`,
+                detail: {
+                    executor_pid: pid,
+                    output_path: options.outputPath
+                }
+            });
+            printJson({
+                conversation: stalledConversation,
+                monitored: true,
+                stalled: true,
+                reason: stalledConversation?.stalled_reason
+            });
+            return;
+        }
+        if (Number.isFinite(timeoutMinutes) && timeoutMinutes > 0) {
+            const updatedAtMs = Date.parse(String(conversation.updated_at ?? conversation.created_at));
+            if (Number.isFinite(updatedAtMs) && Date.now() - updatedAtMs >= timeoutMinutes * 60 * 1000) {
+                const stalledConversation = markConversationStalled({
+                    statePath,
+                    logPath,
+                    reason: `no callback after ${timeoutMinutes} minutes`,
+                    detail: {
+                        agent_timeout_minutes: timeoutMinutes,
+                        output_path: options.outputPath
+                    }
+                });
+                printJson({
+                    conversation: stalledConversation,
+                    monitored: true,
+                    stalled: true,
+                    reason: stalledConversation?.stalled_reason
+                });
+                return;
+            }
+        }
+        sleepSync(pollIntervalMs);
+    }
+}
+function resolveExecutable(command) {
+    if (command.includes(path.sep)) {
+        return command;
+    }
+    const paths = executableSearchPaths();
+    for (const dir of paths) {
+        const candidate = path.join(dir, command);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Continue searching PATH.
+        }
+    }
+    throw new Error(`executable not found on PATH: ${command}`);
+}
+function executableSearchPaths() {
+    const home = process.env.HOME;
+    return [
+        ...(process.env.PATH ?? "").split(path.delimiter).filter(Boolean),
+        ...(home ? [
+            path.join(home, ".npm-global", "bin"),
+            path.join(home, ".local", "bin")
+        ] : []),
+        "/opt/homebrew/bin",
+        "/usr/local/bin"
+    ];
+}
+function resolveOptionalExecutable(command) {
+    try {
+        return resolveExecutable(command);
+    }
+    catch {
+        return command;
+    }
+}
+function packageRootDir() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+function runCheckedCommand(command, args, { label }) {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10
+    });
+    if (result.error) {
+        throw new Error(`${label} failed to start: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(cleanProcessText(result.stderr || result.stdout || `${label} exited with status ${result.status}`));
+    }
+    return result;
+}
+function executableCheck(commandName) {
+    try {
+        const executable = resolveExecutable(commandName);
+        return {
+            command: commandName,
+            available: true,
+            path: executable
+        };
+    }
+    catch (error) {
+        return {
+            command: commandName,
+            available: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function buildCallbackCommand({ statePath, gatewayUrl, token, openclawSession, gatewayMethod, gatewaySession, openclawBin }) {
+    const parts = [
+        shellQuote(process.execPath),
+        shellQuote(new URL(import.meta.url).pathname),
+        "callback",
+        "--state",
+        shellQuote(statePath)
+    ];
+    if (token) {
+        parts.push("--gateway-url", shellQuote(gatewayUrl), "--token", shellQuote(token), "--openclaw-session", shellQuote(openclawSession));
+    }
+    else if (!gatewayMethod) {
+        parts.push("--record-only");
+    }
+    if (gatewayMethod) {
+        parts.push("--gateway-method", shellQuote(gatewayMethod), "--gateway-session", shellQuote(gatewaySession ?? openclawSession));
+        if (openclawBin) {
+            parts.push("--openclaw-bin", shellQuote(openclawBin));
+        }
+    }
+    parts.push("--message-json", "'<structured-message-json>'");
+    return parts.join(" ");
+}
+function expandCallbackCommandTemplate(template, { statePath }) {
+    return template
+        .replaceAll("{statePath}", shellQuote(statePath))
+        .replaceAll("{state_path}", shellQuote(statePath));
+}
+function runTranscript(options) {
+    const conversationDir = options.conversation ? expandHome(options.conversation) : null;
+    const logPath = conversationDir
+        ? pathsForConversationDir(conversationDir).logPath
+        : required(options.log ?? options.path, "--log or --conversation is required");
+    const events = readNdjsonLog(expandHome(logPath));
+    process.stdout.write(formatTranscript(events, {
+        includeRaw: Boolean(options.includeRaw)
+    }));
+}
+function runCallback(options) {
+    const statePath = expandHome(required(options.state, "--state is required"));
+    const releaseLock = acquireFileLock(`${statePath}.lock`);
+    try {
+        runLockedCallback({ ...options, statePath });
+    }
+    finally {
+        releaseLock();
+    }
+}
+function runLockedCallback(options) {
+    const messageInput = required(options.messageJson, "--message-json is required");
+    const logPath = expandHome(options.log ?? logPathForStatePath(options.statePath));
+    const conversation = loadState(options.statePath);
+    const executor = executorForConversation(conversation);
+    const message = extractStructuredMessage({
+        conversation,
+        input: messageInput,
+        defaultFrom: executor.actor,
+        defaultTo: "openclaw"
+    });
+    const existingEvents = readExistingEvents(logPath);
+    if (isDuplicateMessage(existingEvents, message)) {
+        runtimeLog("info", "callback_duplicate", {
+            conversation_id: conversation.conversation_id,
+            agent: executor.kind,
+            executor_session: executor.session,
+            from: message.from,
+            type: message.type,
+            round: message.round,
+            state_path: options.statePath,
+            event_log_path: logPath
+        });
+        printJson({
+            conversation,
+            message,
+            budget: budgetAction(conversation),
+            delivered: false,
+            duplicate: true
+        });
+        return;
+    }
+    const nextConversation = applyMessageToConversation(conversation, message);
+    appendEvent(logPath, messageEvent(message));
+    saveState(options.statePath, nextConversation);
+    runtimeLog("info", "callback_received", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        from: message.from,
+        type: message.type,
+        round: message.round,
+        status: nextConversation.status,
+        requires_response: message.requires_response,
+        state_path: options.statePath,
+        event_log_path: logPath,
+        message: textSummary(message.body)
+    });
+    const result = {
+        conversation: nextConversation,
+        message,
+        budget: budgetAction(nextConversation),
+        delivered: false,
+        duplicate: false
+    };
+    if (options.gatewayMethod) {
+        const delivery = deliverToGatewayMethod({
+            method: options.gatewayMethod,
+            openclawBin: options.openclawBin,
+            gatewayUrl: options.gatewayUrl,
+            token: options.token,
+            sessionKey: options.gatewaySession ?? options.openclawSession ?? conversation.openclaw_session,
+            statePath: options.statePath,
+            logPath,
+            conversation: nextConversation,
+            message
+        });
+        appendEvent(logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: conversation.conversation_id,
+            event: "callback_gateway_method_delivery",
+            from: message.from,
+            to: "openclaw",
+            round: message.round,
+            method: options.gatewayMethod,
+            status: delivery.status,
+            stdout: delivery.stdout,
+            stderr: delivery.stderr
+        });
+        runtimeLog("info", "callback_gateway_method_delivery", {
+            conversation_id: conversation.conversation_id,
+            method: options.gatewayMethod,
+            status: delivery.status,
+            failure_kind: classifyProcessFailure(delivery),
+            stdout: textSummary(delivery.stdout),
+            stderr: textSummary(delivery.stderr)
+        });
+        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;
+        let chatSendDelivery;
+        let sessionSendDelivery;
+        if (chatSendParams) {
+            chatSendDelivery = deliverToChatSend({
+                openclawBin: options.openclawBin,
+                gatewayUrl: options.gatewayUrl,
+                token: options.token,
+                params: chatSendParams
+            });
+            appendEvent(logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: conversation.conversation_id,
+                event: "callback_chat_send_delivery",
+                from: message.from,
+                to: "openclaw",
+                round: message.round,
+                status: chatSendDelivery.status,
+                stdout: chatSendDelivery.stdout,
+                stderr: chatSendDelivery.stderr
+            });
+            runtimeLog("info", "callback_chat_send_delivery", {
+                conversation_id: conversation.conversation_id,
+                status: chatSendDelivery.status,
+                failure_kind: classifyProcessFailure(chatSendDelivery),
+                stdout: textSummary(chatSendDelivery.stdout),
+                stderr: textSummary(chatSendDelivery.stderr)
+            });
+            if (chatSendDelivery.status !== 0) {
+                throw new Error(chatSendDelivery.stderr || chatSendDelivery.stdout || `chat callback delivery failed with status ${chatSendDelivery.status}`);
+            }
+        }
+        else if (sessionSendParams) {
+            sessionSendDelivery = deliverToSessionSend({
+                openclawBin: options.openclawBin,
+                gatewayUrl: options.gatewayUrl,
+                token: options.token,
+                params: sessionSendParams
+            });
+            appendEvent(logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: conversation.conversation_id,
+                event: "callback_session_send_delivery",
+                from: message.from,
+                to: "openclaw",
+                round: message.round,
+                status: sessionSendDelivery.status,
+                stdout: sessionSendDelivery.stdout,
+                stderr: sessionSendDelivery.stderr
+            });
+            runtimeLog("info", "callback_session_send_delivery", {
+                conversation_id: conversation.conversation_id,
+                status: sessionSendDelivery.status,
+                failure_kind: classifyProcessFailure(sessionSendDelivery),
+                stdout: textSummary(sessionSendDelivery.stdout),
+                stderr: textSummary(sessionSendDelivery.stderr)
+            });
+            if (sessionSendDelivery.status !== 0) {
+                throw new Error(sessionSendDelivery.stderr || sessionSendDelivery.stdout || `session callback delivery failed with status ${sessionSendDelivery.status}`);
+            }
+        }
+        printJson({
+            ...result,
+            delivered: true,
+            delivery: chatSendDelivery
+                ? "gateway_method+chat_send"
+                : sessionSendDelivery
+                    ? "gateway_method+sessions_send"
+                    : "gateway_method"
+        });
+        return;
+    }
+    if (options.recordOnly) {
+        runtimeLog("info", "callback_recorded_only", {
+            conversation_id: conversation.conversation_id,
+            status: nextConversation.status
+        });
+        printJson(result);
+        return;
+    }
+    const gatewayUrl = options.gatewayUrl ?? conversation.gateway_url;
+    const token = options.token ?? conversation.gateway_token;
+    const openclawSession = options.openclawSession ?? conversation.openclaw_session;
+    if (!gatewayUrl) {
+        throw new Error("--gateway-url is required unless state has gateway_url");
+    }
+    if (!token || token === "<token>") {
+        throw new Error("--token is required for callback delivery");
+    }
+    if (!openclawSession) {
+        throw new Error("--openclaw-session is required unless state has openclaw_session");
+    }
+    const delivery = deliverToOpenClaw({ gatewayUrl, token, openclawSession, message });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "callback_delivery",
+        from: message.from,
+        to: "openclaw",
+        round: message.round,
+        status: delivery.status,
+        stdout: delivery.stdout,
+        stderr: delivery.stderr
+    });
+    runtimeLog("info", "callback_delivery", {
+        conversation_id: conversation.conversation_id,
+        status: delivery.status,
+        failure_kind: classifyProcessFailure(delivery),
+        stdout: textSummary(delivery.stdout),
+        stderr: textSummary(delivery.stderr)
+    });
+    if (delivery.status !== 0) {
+        throw new Error(delivery.stderr || delivery.stdout || `callback delivery failed with status ${delivery.status}`);
+    }
+    printJson({
+        ...result,
+        delivered: true
+    });
+}
+function acquireFileLock(lockPath, { timeoutMs = 5000, retryMs = 50 } = {}) {
+    const started = Date.now();
+    while (true) {
+        try {
+            const fd = fs.openSync(lockPath, "wx");
+            fs.closeSync(fd);
+            return () => {
+                fs.rmSync(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+            if (Date.now() - started >= timeoutMs) {
+                throw new Error(`timed out waiting for callback lock: ${lockPath}`);
+            }
+            sleepSync(retryMs);
+        }
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function readExistingEvents(logPath) {
+    try {
+        return readNdjsonLog(logPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}
+function loadConversationFromOptions(options) {
+    const storeDir = storeDirFromOptions(options);
+    const conversationId = options.conversation ?? options.conversationId;
+    const statePath = expandHome(options.state ?? (conversationId ? statePathForConversationId(conversationId, storeDir) : undefined));
+    if (!statePath) {
+        throw new Error("--conversation or --state is required");
+    }
+    const conversation = options.state
+        ? loadState(statePath)
+        : loadConversationById(conversationId, storeDir);
+    return {
+        conversation,
+        statePath,
+        logPath: logPathForStatePath(statePath)
+    };
+}
+function storeDirFromOptions(options) {
+    return expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(process.cwd()));
+}
+function summarizeConversation(conversation) {
+    const executor = executorForConversation(conversation);
+    return {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor,
+        session: executor.session,
+        status: conversation.status,
+        request: conversation.user_request,
+        workspace: conversation.workspace,
+        openclaw_session: conversation.openclaw_session,
+        response_rounds_used: conversation.response_rounds_used,
+        soft_limit: conversation.soft_limit,
+        hard_limit: conversation.hard_limit,
+        created_at: conversation.created_at,
+        updated_at: conversation.updated_at,
+        idle_since: conversation.idle_since,
+        closed_at: conversation.closed_at,
+        recovery: conversation.recovery,
+        state_path: conversation.state_path,
+        event_log_path: conversation.event_log_path
+    };
+}
+function summarizeEvent(event) {
+    return {
+        ts: event.ts,
+        event: event.event,
+        from: event.from,
+        to: event.to,
+        type: event.type,
+        status: event.status,
+        round: event.round,
+        body: typeof event.body === "string" ? event.body.slice(0, 500) : undefined
+    };
+}
+function buildConversationTrace({ conversation, events, logPath }) {
+    const outputPath = traceOutputPath({ conversation, events, logPath });
+    const output = outputPath && fs.existsSync(outputPath)
+        ? fs.readFileSync(outputPath, "utf8").slice(-256 * 1024)
+        : "";
+    const parsed = parseExecutorTraceOutput(output);
+    const monitorEvents = events
+        .filter((event) => [
+        "executor_launch",
+        "executor_message_launch",
+        "executor_monitor_launch",
+        "executor_monitor_started",
+        "conversation_stalled",
+        "callback_delivery",
+        "callback_gateway_method_delivery",
+        "callback_chat_send_delivery",
+        "callback_session_send_delivery"
+    ].includes(event.event))
+        .slice(-20)
+        .map((event) => ({
+        ts: event.ts,
+        event: event.event,
+        status: event.status,
+        pid: event.pid,
+        executor_pid: event.executor_pid,
+        reason: event.reason,
+        output_path: event.output_path
+    }));
+    return {
+        source: output ? "executor_output_log" : "events_only",
+        output_path: outputPath,
+        thinking_redacted_count: parsed.thinkingRedactedCount,
+        client_events: parsed.clientEvents.slice(-20),
+        permission_requests: parsed.permissionRequests.slice(-10),
+        tool_calls: parsed.toolCalls.slice(-20),
+        agent_messages: parsed.agentMessages.slice(-8),
+        done_events: parsed.doneEvents.slice(-5),
+        monitor_events: monitorEvents,
+        safety: {
+            thinking: "redacted",
+            tool_output: "summarized",
+            callback_payloads: "redacted"
+        }
+    };
+}
+function traceOutputPath({ conversation, events, logPath }) {
+    const launch = [...events].reverse().find((event) => ["executor_message_launch", "executor_launch"].includes(event.event) &&
+        typeof event.output_path === "string");
+    if (launch?.output_path) {
+        return launch.output_path;
+    }
+    const executor = executorForConversation(conversation);
+    const conversationDir = conversation.conversation_dir ?? path.dirname(logPath);
+    const candidates = [
+        path.join(conversationDir, `${executor.kind}-followup-output.log`),
+        path.join(conversationDir, `${executor.kind}-output.log`)
+    ];
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? candidates.at(-1);
+}
+function parseExecutorTraceOutput(output) {
+    const toolCalls = [];
+    const clientEvents = [];
+    const permissionRequests = [];
+    const agentMessages = [];
+    const doneEvents = [];
+    let thinkingRedactedCount = 0;
+    let currentTool = null;
+    let captureOutputFor = null;
+    let capturedOutputLines = [];
+    const flushToolOutput = () => {
+        if (captureOutputFor && capturedOutputLines.length > 0) {
+            captureOutputFor.output_preview = sanitizeTraceText(capturedOutputLines.join("\n"), 500);
+        }
+        captureOutputFor = null;
+        capturedOutputLines = [];
+    };
+    for (const rawLine of String(output ?? "").split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        const text = line.trim();
+        if (!text) {
+            continue;
+        }
+        if (text.startsWith("[") && captureOutputFor) {
+            flushToolOutput();
+        }
+        const client = text.match(/^\[client\]\s+(.+?)(?:\s+\(([^)]+)\))?$/);
+        if (client) {
+            if (isPermissionTraceLine(text)) {
+                permissionRequests.push({
+                    body: sanitizeTraceText(text, 240)
+                });
+            }
+            clientEvents.push({
+                name: sanitizeTraceText(client[1], 160),
+                status: client[2] ? sanitizeTraceText(client[2], 80) : undefined
+            });
+            continue;
+        }
+        const acpx = text.match(/^\[acpx\]\s+(.+)$/);
+        if (acpx) {
+            clientEvents.push({
+                name: "acpx",
+                status: sanitizeTraceText(acpx[1], 220)
+            });
+            continue;
+        }
+        if (text.startsWith("[thinking]")) {
+            thinkingRedactedCount += 1;
+            agentMessages.push({
+                kind: "thinking",
+                body: "[redacted]"
+            });
+            continue;
+        }
+        const done = text.match(/^\[done\]\s*(.*)$/);
+        if (done) {
+            doneEvents.push({
+                status: sanitizeTraceText(done[1] || "done", 120)
+            });
+            continue;
+        }
+        const tool = text.match(/^\[tool\]\s+(.+?)\s+\(([^)]+)\)$/);
+        if (tool) {
+            const toolCall = {
+                name: sanitizeToolName(tool[1]),
+                status: sanitizeTraceText(tool[2], 80)
+            };
+            toolCalls.push(toolCall);
+            currentTool = toolCall;
+            continue;
+        }
+        if (currentTool && text.startsWith("input:")) {
+            currentTool.input_preview = sanitizeTraceText(text.slice("input:".length).trim(), 360);
+            continue;
+        }
+        if (currentTool && text.startsWith("output:")) {
+            captureOutputFor = currentTool;
+            capturedOutputLines = [];
+            continue;
+        }
+        if (captureOutputFor && !text.startsWith("[")) {
+            if (capturedOutputLines.length < 8) {
+                capturedOutputLines.push(text);
+            }
+            continue;
+        }
+        if (isPermissionTraceLine(text)) {
+            permissionRequests.push({
+                body: sanitizeTraceText(text, 240)
+            });
+            continue;
+        }
+        if (isAgentMessageTraceLine(text)) {
+            agentMessages.push({
+                kind: "message",
+                body: sanitizeTraceText(text, 360)
+            });
+        }
+    }
+    flushToolOutput();
+    return {
+        toolCalls,
+        clientEvents,
+        permissionRequests,
+        agentMessages,
+        doneEvents,
+        thinkingRedactedCount
+    };
+}
+function sanitizeToolName(value) {
+    return sanitizeTraceText(String(value ?? "")
+        .replace(/--message-json\s+(['"]).*?\1/g, "--message-json <redacted>")
+        .replace(/--message-json\s+.*/g, "--message-json <redacted>")
+        .replace(/--token\s+\S+/g, "--token <redacted>"), 220);
+}
+function sanitizeTraceText(value, maxLength = 240) {
+    return String(value ?? "")
+        .replace(/--message-json\s+(['"]).*?\1/g, "--message-json <redacted>")
+        .replace(/--message-json\s+.*/g, "--message-json <redacted>")
+        .replace(/--token\s+\S+/g, "--token <redacted>")
+        .replace(/(gateway[_-]?token|api[_-]?key|token|password|secret)=\S+/gi, "$1=<redacted>")
+        .slice(0, maxLength);
+}
+function isPermissionTraceLine(text) {
+    const lower = text.toLowerCase();
+    return lower.includes("session/request_permission") ||
+        (lower.includes("permission") && (lower.includes("request") || lower.includes("approve") || lower.includes("allow")));
+}
+function isAgentMessageTraceLine(text) {
+    if (text.startsWith("[") || text.startsWith("{") || text.startsWith("}") || text.startsWith("```")) {
+        return false;
+    }
+    if (text.startsWith("input:") || text.startsWith("output:") || text.startsWith("kind:")) {
+        return false;
+    }
+    if (/^(call_id|process_id|turn_id|command|cwd):/i.test(text)) {
+        return false;
+    }
+    return text.length >= 12;
+}
+function isActiveStatus(status) {
+    return !["done", "failed", "closed", "cancelled"].includes(status);
+}
+function isWaitingForAgent(status) {
+    return ["created", "running", "waiting_for_agent", "cancelling"].includes(status);
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code === "EPERM";
+    }
+}
+function markConversationStalled({ statePath, logPath, reason, detail = {} }) {
+    const releaseLock = acquireFileLock(`${statePath}.lock`);
+    let stalledConversation;
+    try {
+        const conversation = loadState(statePath);
+        if (!isWaitingForAgent(conversation.status)) {
+            runtimeLog("info", "executor_monitor_finished", {
+                conversation_id: conversation.conversation_id,
+                status: conversation.status,
+                reason: "conversation_changed_before_stall"
+            });
+            return conversation;
+        }
+        const now = new Date().toISOString();
+        stalledConversation = {
+            ...conversation,
+            status: "stalled",
+            stalled_at: now,
+            stalled_reason: reason,
+            updated_at: now
+        };
+        saveState(statePath, stalledConversation);
+        appendEvent(logPath, {
+            ts: now,
+            conversation_id: conversation.conversation_id,
+            event: "conversation_stalled",
+            status: "stalled",
+            reason,
+            ...detail
+        });
+        runtimeLog("warn", "conversation_stalled", {
+            conversation_id: conversation.conversation_id,
+            agent: executorForConversation(conversation).kind,
+            executor_session: executorForConversation(conversation).session,
+            state_path: statePath,
+            event_log_path: logPath,
+            reason,
+            ...detail
+        });
+    }
+    finally {
+        releaseLock();
+    }
+    if (stalledConversation) {
+        deliverStalledNotification({
+            statePath,
+            logPath,
+            conversation: stalledConversation,
+            reason
+        });
+    }
+    return stalledConversation;
+}
+function deliverStalledNotification({ statePath, logPath, conversation, reason }) {
+    if (!conversation.gateway_method) {
+        return;
+    }
+    const executor = executorForConversation(conversation);
+    const message = createMessage({
+        conversation,
+        from: executor.actor,
+        to: "openclaw",
+        type: "error",
+        requiresResponse: false,
+        body: [
+            `AKK marked this ${executor.display_name} task as stalled: ${reason}.`,
+            "",
+            `Conversation: ${conversation.conversation_id}`,
+            `Session: ${executor.session}`,
+            "Use `AKK status` for details, `AKK send` to retry/follow up, or `AKK close` to close it."
+        ].join("\n")
+    });
+    const delivery = deliverToGatewayMethod({
+        method: conversation.gateway_method,
+        openclawBin: conversation.openclaw_bin,
+        gatewayUrl: conversation.gateway_url,
+        token: conversation.gateway_token,
+        sessionKey: conversation.gateway_session ?? conversation.openclaw_session,
+        statePath,
+        logPath,
+        conversation,
+        message
+    });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "stalled_gateway_method_delivery",
+        method: conversation.gateway_method,
+        status: delivery.status,
+        stdout: delivery.stdout,
+        stderr: delivery.stderr
+    });
+    runtimeLog("info", "stalled_gateway_method_delivery", {
+        conversation_id: conversation.conversation_id,
+        method: conversation.gateway_method,
+        status: delivery.status,
+        failure_kind: classifyProcessFailure(delivery),
+        stdout: textSummary(delivery.stdout),
+        stderr: textSummary(delivery.stderr)
+    });
+    if (delivery.status !== 0) {
+        return;
+    }
+    const gatewayPayload = parseOptionalJson(delivery.stdout);
+    const chatSendParams = isRecord(gatewayPayload?.chat_send) ? gatewayPayload.chat_send : undefined;
+    if (!chatSendParams) {
+        return;
+    }
+    const chatSendDelivery = deliverToChatSend({
+        openclawBin: conversation.openclaw_bin,
+        gatewayUrl: conversation.gateway_url,
+        token: conversation.gateway_token,
+        params: chatSendParams
+    });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "stalled_chat_send_delivery",
+        status: chatSendDelivery.status,
+        stdout: chatSendDelivery.stdout,
+        stderr: chatSendDelivery.stderr
+    });
+    runtimeLog("info", "stalled_chat_send_delivery", {
+        conversation_id: conversation.conversation_id,
+        status: chatSendDelivery.status,
+        failure_kind: classifyProcessFailure(chatSendDelivery),
+        stdout: textSummary(chatSendDelivery.stdout),
+        stderr: textSummary(chatSendDelivery.stderr)
+    });
+}
+function cleanupIdleConversations(storeDir, options = {}, now = new Date()) {
+    const timeoutMinutes = Number(options.idleTimeoutMinutes ?? DEFAULT_IDLE_TIMEOUT_MINUTES);
+    if (!Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0) {
+        return { checked: 0, closed: 0, idle_timeout_minutes: timeoutMinutes };
+    }
+    const conversations = listConversations(storeDir);
+    let closed = 0;
+    for (const conversation of conversations) {
+        if (conversation.status !== "idle" || !conversation.idle_since) {
+            continue;
+        }
+        const idleSinceMs = Date.parse(conversation.idle_since);
+        if (!Number.isFinite(idleSinceMs)) {
+            continue;
+        }
+        if (now.getTime() - idleSinceMs < timeoutMinutes * 60 * 1000) {
+            continue;
+        }
+        const statePath = conversation.state_path ?? statePathForConversationId(conversation.conversation_id, storeDir);
+        const logPath = conversation.event_log_path ?? logPathForStatePath(statePath);
+        const closedConversation = {
+            ...conversation,
+            status: "closed",
+            closed_at: now.toISOString(),
+            close_reason: `idle timeout after ${timeoutMinutes} minutes`,
+            updated_at: now.toISOString()
+        };
+        delete closedConversation.idle_since;
+        saveState(statePath, closedConversation);
+        appendEvent(logPath, {
+            ts: now.toISOString(),
+            conversation_id: conversation.conversation_id,
+            event: "conversation_closed",
+            status: "closed",
+            reason: closedConversation.close_reason,
+            idle_timeout_minutes: timeoutMinutes
+        });
+        runtimeLog("info", "idle_conversation_closed", {
+            conversation_id: conversation.conversation_id,
+            agent: executorForConversation(conversation).kind,
+            executor_session: executorForConversation(conversation).session,
+            state_path: statePath,
+            event_log_path: logPath,
+            idle_since: conversation.idle_since,
+            idle_timeout_minutes: timeoutMinutes,
+            reason: closedConversation.close_reason
+        });
+        closed += 1;
+    }
+    return {
+        checked: conversations.length,
+        closed,
+        idle_timeout_minutes: timeoutMinutes
+    };
+}
+function isDuplicateMessage(events, message) {
+    return events.some((event) => {
+        if (event.event !== "message") {
+            return false;
+        }
+        const existing = event.message ?? event;
+        if (existing.id && existing.id === message.id) {
+            return true;
+        }
+        return messageFingerprint(existing) === messageFingerprint(message);
+    });
+}
+function messageFingerprint(message) {
+    return JSON.stringify({
+        conversation_id: message.conversation_id,
+        from: message.from,
+        to: message.to,
+        type: message.type,
+        requires_response: message.requires_response,
+        body: message.body
+    });
+}
+function deliverToOpenClaw({ gatewayUrl, token, openclawSession, message }) {
+    const agent = `openclaw acp --url ${gatewayUrl} --token ${token} --session ${openclawSession}`;
+    const result = spawnSync("acpx", ["--agent", agent, JSON.stringify(message)], {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10
+    });
+    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 deliverToGatewayMethod({ method, openclawBin, gatewayUrl, token, sessionKey, statePath, logPath, conversation, message }) {
+    const args = [
+        "gateway",
+        "call",
+        method,
+        "--params",
+        JSON.stringify({
+            sessionKey,
+            statePath,
+            logPath,
+            conversation,
+            message
+        }),
+        "--json"
+    ];
+    if (gatewayUrl) {
+        args.push("--url", gatewayUrl);
+    }
+    if (token && token !== "<token>") {
+        args.push("--token", token);
+    }
+    const result = spawnSync(openclawBin ?? "openclaw", args, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10
+    });
+    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 deliverToSessionSend({ openclawBin, gatewayUrl, token, params }) {
+    const args = [
+        "gateway",
+        "call",
+        "sessions.send",
+        "--params",
+        JSON.stringify(params),
+        "--json"
+    ];
+    if (gatewayUrl) {
+        args.push("--url", gatewayUrl);
+    }
+    if (token && token !== "<token>") {
+        args.push("--token", token);
+    }
+    const result = spawnSync(openclawBin ?? "openclaw", args, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10
+    });
+    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 deliverToChatSend({ openclawBin, gatewayUrl, token, params }) {
+    const args = [
+        "gateway",
+        "call",
+        "chat.send",
+        "--params",
+        JSON.stringify(params),
+        "--json"
+    ];
+    if (gatewayUrl) {
+        args.push("--url", gatewayUrl);
+    }
+    if (token && token !== "<token>") {
+        args.push("--token", token);
+    }
+    const result = spawnSync(openclawBin ?? "openclaw", args, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10
+    });
+    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 captureJson(argv) {
+    const result = spawnSync(process.execPath, [new URL(import.meta.url).pathname, ...argv], {
+        encoding: "utf8"
+    });
+    if (result.status !== 0) {
+        throw new Error(result.stderr || result.stdout || `subcommand failed: ${argv[0]}`);
+    }
+    return JSON.parse(result.stdout);
+}
+function parseArgs(argv) {
+    const parsed = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith("--")) {
+            throw new Error(`unexpected argument: ${arg}`);
+        }
+        const key = toCamelCase(arg.slice(2));
+        const next = argv[index + 1];
+        if (next === undefined || next.startsWith("--")) {
+            parsed[key] = true;
+        }
+        else {
+            parsed[key] = next;
+            index += 1;
+        }
+    }
+    return parsed;
+}
+function toCamelCase(value) {
+    return value.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+function required(value, message) {
+    if (value === undefined || value === "") {
+        throw new Error(message);
+    }
+    return value;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseOptionalJson(text) {
+    try {
+        return JSON.parse(String(text));
+    }
+    catch {
+        return undefined;
+    }
+}
+function expandHome(filePath) {
+    if (filePath === "~") {
+        return process.env.HOME;
+    }
+    if (filePath?.startsWith("~/")) {
+        return `${process.env.HOME}${filePath.slice(1)}`;
+    }
+    return filePath;
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function cleanProcessText(text) {
+    const value = String(text ?? "").trim();
+    return value ? value.slice(0, 2000) : undefined;
+}
+function textSummary(text, maxLength = 240) {
+    const value = String(text ?? "");
+    return {
+        length: value.length,
+        preview: value ? value.slice(0, maxLength) : undefined
+    };
+}
+function classifyProcessFailure(result) {
+    const status = result?.status ?? 0;
+    const combined = [
+        result?.error?.message,
+        result?.stderr,
+        result?.stdout
+    ].filter(Boolean).join("\n").toLowerCase();
+    if (!combined && status === 0) {
+        return undefined;
+    }
+    if (combined.includes("agent needs reconnect") || combined.includes("internal error")) {
+        return "agent_reconnect_required";
+    }
+    if (combined.includes("permission denied") || combined.includes("operation not permitted")) {
+        return "permission_denied";
+    }
+    if (combined.includes("sandbox") || combined.includes("outside workspace")) {
+        return "sandbox_denied";
+    }
+    if (combined.includes("timed out") || combined.includes("timeout")) {
+        return "timeout";
+    }
+    if (status !== 0) {
+        return "nonzero_exit";
+    }
+    return undefined;
+}
+function runtimeLog(level, event, fields = {}) {
+    try {
+        writeRuntimeLog({
+            level,
+            event,
+            ...fields
+        });
+    }
+    catch {
+        // Runtime logging must never break the user-facing CLI command.
+    }
+}
+function shellQuote(value) {
+    return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+function withStoragePaths(conversation, paths) {
+    return {
+        ...conversation,
+        store_dir: paths.storeDir,
+        conversation_dir: paths.conversationDir,
+        event_log_path: paths.logPath,
+        state_path: paths.statePath
+    };
+}
+function usage() {
+    const agentList = EXECUTOR_KINDS.join("|");
+    process.stdout.write(`Usage:
+  agent-knock-knock new --request <text> [--agent ${agentList}] [--workspace <path>] [--store-dir <dir>]
+  agent-knock-knock record --state <file> --message-json <json>
+  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]
+  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 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 callback --state <file> --message-json <json> [--record-only]
+  agent-knock-knock transcript --log <file> [--include-raw]
+  agent-knock-knock transcript --conversation <dir> [--include-raw]
+`);
+}
+//# sourceMappingURL=cli.js.map