@scotthuang/agent-knock-knock 0.1.1 → 0.2.0

package/dist/src/cli.js

@@ -5,24 +5,59 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 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 { 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";
 const DEFAULT_IDLE_TIMEOUT_MINUTES = 10080;
 const DEFAULT_AGENT_TIMEOUT_MINUTES = 60;
 const DEFAULT_MONITOR_POLL_INTERVAL_MS = 5000;
+class InlineCodexSessionAdapter {
+    threads;
+    processes;
+    processBatches;
+    processBatchIndex = 0;
+    rollouts;
+    constructor({ threads, processes, rollouts }) {
+        this.threads = Array.isArray(threads) ? threads : [];
+        this.processBatches = Array.isArray(processes?.[0])
+            ? processes
+            : [];
+        this.processes = Array.isArray(processes) && !Array.isArray(processes[0]) ? processes : [];
+        this.rollouts = new Map(Object.entries(rollouts ?? {}));
+    }
+    async listThreadRows() {
+        return this.threads;
+    }
+    async readRollout(rolloutPath) {
+        return this.rollouts.get(rolloutPath);
+    }
+    async listProcessSnapshots() {
+        if (this.processBatches.length > 0) {
+            const batch = this.processBatches[Math.min(this.processBatchIndex, this.processBatches.length - 1)];
+            this.processBatchIndex += 1;
+            return batch;
+        }
+        return this.processes;
+    }
+}
 const command = process.argv[2];
-const args = parseArgs(process.argv.slice(3));
+const rawArgs = process.argv.slice(3);
+const args = command === "agent"
+    ? { agentCommand: rawArgs[0], ...parseArgs(rawArgs.slice(1)) }
+    : parseArgs(rawArgs);
 runtimeLog("info", "cli_start", {
     command: command ?? "help",
     cwd: process.cwd(),
     option_keys: Object.keys(args).sort()
 });
 try {
-    runCommand(command, args);
+    await runCommand(command, args);
     runtimeLog("info", "cli_finish", {
         command: command ?? "help",
         exit_code: process.exitCode ?? 0
@@ -37,7 +72,7 @@ catch (error) {
     console.error(error.message);
     process.exit(1);
 }
-function runCommand(commandName, options) {
+async function runCommand(commandName, options) {
     if (commandName === "new") {
         runNew(options);
     }
@@ -86,6 +121,9 @@ function runCommand(commandName, options) {
     else if (commandName === "monitor") {
         runMonitor(options);
     }
+    else if (commandName === "agent") {
+        await runAgent(options);
+    }
     else {
         usage();
         process.exitCode = commandName ? 1 : 0;
@@ -170,6 +208,495 @@ function runDoctor(options) {
         options
     });
 }
+async function runAgent(options) {
+    const agentCommand = required(options.agentCommand, "agent subcommand is required: discover or takeover");
+    if (agentCommand === "discover") {
+        printJson(await runAgentDiscover(options));
+        return;
+    }
+    if (agentCommand === "takeover") {
+        printJson(await runAgentTakeover(options));
+        return;
+    }
+    throw new Error(`unsupported agent subcommand: ${agentCommand}`);
+}
+async function runAgentDiscover(options) {
+    const agent = required(options.agent, "--agent is required");
+    const scope = required(options.scope, "--scope is required");
+    const provider = createAgentSessionProvider(agent, options);
+    const capabilities = await provider.getCapabilities();
+    if (scope === "capabilities") {
+        return {
+            agent,
+            scope,
+            capabilities
+        };
+    }
+    if (scope === "sessions") {
+        return {
+            agent,
+            scope,
+            capabilities,
+            sessions: await provider.listHistoricalSessions()
+        };
+    }
+    if (scope === "active") {
+        return {
+            agent,
+            scope,
+            capabilities,
+            active: await provider.listActiveSessions()
+        };
+    }
+    throw new Error(`unsupported discover scope: ${scope}`);
+}
+async function runAgentTakeover(options) {
+    const agent = required(options.agent, "--agent is required");
+    const sessionId = required(options.sessionId, "--session-id is required");
+    const strategy = options.strategy ?? "terminate_then_resume";
+    const provider = createAgentSessionProvider(agent, options);
+    const session = await provider.getSession(sessionId);
+    if (!session) {
+        return {
+            agent,
+            sessionId,
+            strategy,
+            status: "blocked",
+            sideEffectsExecuted: false,
+            error: {
+                code: "session_not_found",
+                message: `No ${agent} session found for ${sessionId}`
+            }
+        };
+    }
+    if (strategy === "safe_resume") {
+        const plan = planSafeResume(session, await provider.listActiveSessions());
+        if (plan.allowed && options.createConversation) {
+            const modelInfo = await provider.getSessionModel(session.id);
+            const attached = createNativeSessionConversation({
+                agent,
+                strategy,
+                session,
+                modelInfo,
+                options
+            });
+            return {
+                agent,
+                sessionId,
+                strategy,
+                status: "attached",
+                sideEffectsExecuted: true,
+                plan,
+                ...attached
+            };
+        }
+        return {
+            agent,
+            sessionId,
+            strategy,
+            status: plan.allowed ? "ready" : "blocked",
+            sideEffectsExecuted: false,
+            plan
+        };
+    }
+    if (strategy === "terminate_then_resume") {
+        const activeSessions = await provider.listActiveSessions();
+        const plan = planTakeover(session, activeSessions);
+        if (options.confirmTerminate === true) {
+            const expectedPid = Number(required(options.expectedPid, "--expected-pid is required with --confirm-terminate"));
+            if (!Number.isInteger(expectedPid) || expectedPid <= 0) {
+                throw new Error("--expected-pid must be a positive integer");
+            }
+            if (!options.createConversation) {
+                throw new Error("--create-conversation is required with --confirm-terminate");
+            }
+            const targetSelection = selectTerminateTarget({
+                plan,
+                session,
+                activeSessions,
+                expectedPid,
+                allowCwdOnly: options.allowCwdOnly === true
+            });
+            if (!targetSelection.allowed) {
+                return {
+                    agent,
+                    sessionId,
+                    strategy,
+                    status: "blocked",
+                    sideEffectsExecuted: false,
+                    plan,
+                    error: {
+                        code: targetSelection.code,
+                        message: targetSelection.message
+                    }
+                };
+            }
+            const { target, matchKind } = targetSelection;
+            const termination = terminateProcessTarget(target, {
+                timeoutMs: Number(options.terminateTimeoutMs ?? 3000)
+            });
+            const activeAfterTermination = await provider.listActiveSessions();
+            const afterTerminationPlan = planTakeover(session, activeAfterTermination);
+            if (afterTerminationPlan.targets.some((candidate) => candidate.sessionId === session.id || candidate.pid === expectedPid)) {
+                return {
+                    agent,
+                    sessionId,
+                    strategy,
+                    status: "blocked",
+                    sideEffectsExecuted: true,
+                    plan: afterTerminationPlan,
+                    termination,
+                    error: {
+                        code: "target_still_active",
+                        message: `Codex process ${expectedPid} still appears active after termination.`
+                    }
+                };
+            }
+            const modelInfo = await provider.getSessionModel(session.id);
+            const attached = createNativeSessionConversation({
+                agent,
+                strategy,
+                session,
+                modelInfo,
+                options,
+                takeoverMatchKind: matchKind
+            });
+            return {
+                agent,
+                sessionId,
+                strategy,
+                status: "attached",
+                sideEffectsExecuted: true,
+                plan,
+                termination,
+                matchKind,
+                ...attached
+            };
+        }
+        return {
+            agent,
+            sessionId,
+            strategy,
+            status: plan.requiresConfirmation ? "requires_confirmation" : "blocked",
+            sideEffectsExecuted: false,
+            plan
+        };
+    }
+    if (strategy === "fork") {
+        const contextPackage = await provider.getForkContext({
+            sessionId,
+            maxMessages: Number(options.maxMessages ?? 12),
+            maxCommands: Number(options.maxCommands ?? 8),
+            maxTextLength: Number(options.maxTextLength ?? 1200)
+        });
+        if (!contextPackage) {
+            return {
+                agent,
+                sessionId,
+                strategy,
+                status: "blocked",
+                sideEffectsExecuted: false,
+                error: {
+                    code: "fork_context_unavailable",
+                    message: `No fork context could be built for ${sessionId}`
+                }
+            };
+        }
+        if (options.createConversation) {
+            const forkSummary = String(required(options.forkSummary ?? options.summary, "--fork-summary is required when creating a fork conversation"));
+            const modelInfo = await provider.getSessionModel(session.id);
+            const attached = createForkConversation({
+                agent,
+                strategy,
+                session,
+                contextPackage,
+                forkSummary,
+                modelInfo,
+                options
+            });
+            return {
+                agent,
+                sessionId,
+                strategy,
+                status: "forked",
+                sideEffectsExecuted: true,
+                plan: planFork(session, contextPackage),
+                ...attached
+            };
+        }
+        return {
+            agent,
+            sessionId,
+            strategy,
+            status: "awaiting_openclaw_summary",
+            sideEffectsExecuted: false,
+            plan: planFork(session, contextPackage),
+            summaryPrompt: buildForkSummaryPrompt({ agent, session, contextPackage }),
+            nextAction: {
+                actor: "openclaw",
+                action: "summarize_and_confirm_fork",
+                instructions: [
+                    "Summarize plan.contextPackage for the user before creating a forked AKK-managed session.",
+                    "Do not inject the raw rollout or full contextPackage into the new coding agent.",
+                    "Ask the user to confirm the summary.",
+                    "After confirmation, call this tool again with strategy=fork, createConversation=true, and forkSummary set to the confirmed summary."
+                ],
+                followUpTool: "agent_knock_knock_agent_takeover",
+                followUpParams: {
+                    agent,
+                    sessionId,
+                    strategy: "fork",
+                    createConversation: true,
+                    forkSummary: "<confirmed OpenClaw summary>"
+                }
+            },
+            next: "Use summaryPrompt to summarize the bounded context package for the user, ask for confirmation, then create the forked AKK-managed session with forkSummary."
+        };
+    }
+    throw new Error(`unsupported takeover strategy: ${strategy}`);
+}
+function buildForkSummaryPrompt({ agent, session, contextPackage }) {
+    return [
+        "You are OpenClaw summarizing a bounded native coding-agent session context before Agent Knock Knock forks it into a new managed session.",
+        "",
+        "Goal:",
+        "- Produce a concise, user-reviewable summary that can be safely injected into a new AKK-managed coding-agent session after the user confirms it.",
+        "- The new session must use the summary only; do not pass raw rollout history or the full context package to the coding agent.",
+        "",
+        "Source:",
+        `- Agent: ${agent}`,
+        `- Session id: ${session.id}`,
+        `- Workspace: ${session.cwd}`,
+        `- Title: ${session.title ?? session.preview ?? session.firstUserMessage ?? "(unknown)"}`,
+        `- Context messages included: ${contextPackage.messages.length}`,
+        `- Commands included: ${contextPackage.commands.length}`,
+        `- Context truncated: ${contextPackage.truncated ? "yes" : "no"}`,
+        "",
+        "Summary format:",
+        "1. Original user goal",
+        "2. Work already completed",
+        "3. Current state and important findings",
+        "4. Constraints, risks, or files/workspace details the forked agent must preserve",
+        "5. Recommended next step for the forked agent",
+        "",
+        "After writing the summary, ask the user to confirm. If confirmed, call agent_knock_knock_agent_takeover with strategy=\"fork\", createConversation=true, and forkSummary equal to the confirmed summary."
+    ].join("\n");
+}
+function selectTerminateTarget({ plan, session, activeSessions, expectedPid, allowCwdOnly }) {
+    const exactTarget = plan.targets.find((candidate) => candidate.pid === expectedPid && candidate.sessionId === session.id);
+    if (exactTarget) {
+        return {
+            allowed: true,
+            target: exactTarget,
+            matchKind: "exact_session"
+        };
+    }
+    if (!allowCwdOnly) {
+        return {
+            allowed: false,
+            code: plan.allowed && plan.requiresConfirmation ? "expected_pid_mismatch" : "takeover_not_confirmable",
+            message: plan.allowed && plan.requiresConfirmation
+                ? `Expected pid ${expectedPid} is no longer the exact active Codex process for session ${session.id}.`
+                : "The current active Codex process no longer has an exact session match that can be safely terminated."
+        };
+    }
+    const cwdOnlyTarget = plan.targets.find((candidate) => candidate.pid === expectedPid &&
+        candidate.cwd === session.cwd &&
+        candidate.sessionId === undefined);
+    const stillActive = activeSessions.some((candidate) => candidate.pid === expectedPid &&
+        candidate.cwd === session.cwd &&
+        candidate.sessionId === undefined);
+    if (!cwdOnlyTarget || !stillActive) {
+        return {
+            allowed: false,
+            code: "expected_pid_mismatch",
+            message: `Expected pid ${expectedPid} is no longer an active Codex process in ${session.cwd}.`
+        };
+    }
+    return {
+        allowed: true,
+        target: cwdOnlyTarget,
+        matchKind: "cwd_only_confirmed"
+    };
+}
+function createForkConversation({ agent, strategy, session, contextPackage, forkSummary, modelInfo, options }) {
+    const workspace = session.cwd;
+    const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
+    cleanupIdleConversations(storeDir, options);
+    const executor = resolveExecutor({
+        kind: agent,
+        session: options.session ?? options.executorSession ?? uniqueDelegateSessionName(agent)
+    });
+    const now = new Date();
+    const conversation = createConversation({
+        userRequest: options.request ?? `Fork native ${agent} session ${session.id}`,
+        workspace,
+        openclawSession: options.openclawSession ?? "agent:main:main",
+        executorKind: executor.kind,
+        executorSession: executor.session,
+        softLimit: Number(options.softLimit ?? 50),
+        hardLimit: Number(options.hardLimit ?? 100),
+        now
+    });
+    const paths = pathsForConversation(conversation.conversation_id, storeDir);
+    const callbackCommand = options.callbackCommand
+        ? expandCallbackCommandTemplate(options.callbackCommand, { statePath: paths.statePath })
+        : buildCallbackCommand({
+            statePath: paths.statePath,
+            gatewayUrl: options.gatewayUrl ?? "ws://127.0.0.1:18789",
+            token: options.token,
+            openclawSession: options.openclawSession ?? "agent:main:main",
+            gatewayMethod: options.gatewayMethod,
+            gatewaySession: options.gatewaySession,
+            openclawBin: options.openclawBin ?? resolveOptionalExecutable("openclaw")
+        });
+    const explicitModel = options.model ?? options.codexModel;
+    const executorModel = explicitModel ?? modelInfo?.acpxModel ?? modelEnvForExecutor(executor, process.env);
+    const forkedConversation = withStoragePaths({
+        ...conversation,
+        executor,
+        status: "idle",
+        idle_since: now.toISOString(),
+        updated_at: now.toISOString(),
+        callback_command: callbackCommand,
+        gateway_url: options.gatewayUrl ?? "ws://127.0.0.1:18789",
+        gateway_method: options.gatewayMethod,
+        gateway_session: options.gatewaySession ?? options.openclawSession ?? "agent:main:main",
+        openclaw_bin: options.openclawBin ?? resolveOptionalExecutable("openclaw"),
+        executor_all_proxy: proxyForExecutor(executor, options),
+        executor_model: executorModel,
+        fork_context_takeover: {
+            agent,
+            source_session_id: session.id,
+            source_cwd: session.cwd,
+            source_title: session.title,
+            source_updated_at_ms: session.updatedAtMs,
+            strategy,
+            forked_at: now.toISOString(),
+            summary: forkSummary,
+            context_message_count: contextPackage.messages.length,
+            context_command_count: contextPackage.commands.length,
+            context_truncated: contextPackage.truncated,
+            native_model: modelInfo?.model,
+            acpx_model: modelInfo?.acpxModel,
+            model_source: modelInfo?.source,
+            needs_bootstrap: true
+        }
+    }, paths);
+    saveState(paths.statePath, forkedConversation);
+    appendEvent(paths.logPath, {
+        ts: now.toISOString(),
+        conversation_id: forkedConversation.conversation_id,
+        event: "native_session_forked",
+        agent,
+        strategy,
+        source_session_id: session.id,
+        source_cwd: session.cwd,
+        executor,
+        context_message_count: contextPackage.messages.length,
+        context_command_count: contextPackage.commands.length,
+        context_truncated: contextPackage.truncated
+    });
+    runtimeLog("info", "native_session_forked", {
+        conversation_id: forkedConversation.conversation_id,
+        agent,
+        strategy,
+        source_session_id: session.id,
+        executor_session: executor.session,
+        state_path: paths.statePath,
+        event_log_path: paths.logPath
+    });
+    return {
+        conversation: forkedConversation,
+        paths,
+        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 }) {
+    const workspace = session.cwd;
+    const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
+    cleanupIdleConversations(storeDir, options);
+    const executor = resolveExecutor({
+        kind: agent,
+        session: session.id
+    });
+    const now = new Date();
+    const conversation = createConversation({
+        userRequest: options.request ?? `Attach native ${agent} session ${session.id}`,
+        workspace,
+        openclawSession: options.openclawSession ?? "agent:main:main",
+        executorKind: executor.kind,
+        executorSession: executor.session,
+        softLimit: Number(options.softLimit ?? 50),
+        hardLimit: Number(options.hardLimit ?? 100),
+        now
+    });
+    const paths = pathsForConversation(conversation.conversation_id, storeDir);
+    const callbackCommand = options.callbackCommand
+        ? expandCallbackCommandTemplate(options.callbackCommand, { statePath: paths.statePath })
+        : buildCallbackCommand({
+            statePath: paths.statePath,
+            gatewayUrl: options.gatewayUrl ?? "ws://127.0.0.1:18789",
+            token: options.token,
+            openclawSession: options.openclawSession ?? "agent:main:main",
+            gatewayMethod: options.gatewayMethod,
+            gatewaySession: options.gatewaySession,
+            openclawBin: options.openclawBin ?? resolveOptionalExecutable("openclaw")
+        });
+    const explicitModel = options.model ?? options.codexModel;
+    const executorModel = explicitModel ?? modelInfo?.acpxModel ?? modelEnvForExecutor(executor, process.env);
+    const attachedConversation = withStoragePaths({
+        ...conversation,
+        executor,
+        status: "idle",
+        idle_since: now.toISOString(),
+        updated_at: now.toISOString(),
+        callback_command: callbackCommand,
+        gateway_url: options.gatewayUrl ?? "ws://127.0.0.1:18789",
+        gateway_method: options.gatewayMethod,
+        gateway_session: options.gatewaySession ?? options.openclawSession ?? "agent:main:main",
+        openclaw_bin: options.openclawBin ?? resolveOptionalExecutable("openclaw"),
+        executor_all_proxy: proxyForExecutor(executor, options),
+        executor_model: executorModel,
+        native_session_takeover: {
+            agent,
+            native_session_id: session.id,
+            source_cwd: session.cwd,
+            source_title: session.title,
+            strategy,
+            attached_at: now.toISOString(),
+            native_model: modelInfo?.model,
+            acpx_model: modelInfo?.acpxModel,
+            model_source: modelInfo?.source,
+            takeover_match_kind: takeoverMatchKind,
+            needs_bootstrap: true
+        }
+    }, paths);
+    saveState(paths.statePath, attachedConversation);
+    appendEvent(paths.logPath, {
+        ts: now.toISOString(),
+        conversation_id: attachedConversation.conversation_id,
+        event: "native_session_attached",
+        agent,
+        strategy,
+        native_session_id: session.id,
+        source_cwd: session.cwd,
+        executor
+    });
+    runtimeLog("info", "native_session_attached", {
+        conversation_id: attachedConversation.conversation_id,
+        agent,
+        strategy,
+        native_session_id: session.id,
+        state_path: paths.statePath,
+        event_log_path: paths.logPath
+    });
+    return {
+        conversation: attachedConversation,
+        paths,
+        next: `Use AKK send ${attachedConversation.conversation_id}: <message> to continue this native ${agent} session through AKK.`
+    };
+}
 function runNew(options) {
     const request = required(options.request, "--request is required");
     const workspace = options.workspace ?? process.cwd();
@@ -489,8 +1016,15 @@ function runDelegate(options) {
         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], {
+function ensureExecutorSession({ acpxPath, executor, cwd, env, resumeSessionId }) {
+    const args = [acpxCommandForExecutor(executor), "sessions", "ensure"];
+    if (resumeSessionId) {
+        args.push("--resume-session", resumeSessionId);
+    }
+    else {
+        args.push("--name", executor.session);
+    }
+    return spawnSync(acpxPath, args, {
         encoding: "utf8",
         cwd,
         env
@@ -622,8 +1156,19 @@ function runSend(options) {
     if (conversation.status === "needs_recovery") {
         throw new Error(`cannot send to ${conversation.conversation_id}; choose recover, restart, or close 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`);
+    }
     const executor = executorForConversation(conversation);
     const type = options.type ?? (conversation.status === "waiting_for_openclaw" ? "answer" : "task");
+    const nativeTakeoverForSend = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const forkTakeoverForSend = isRecord(conversation.fork_context_takeover)
+        ? conversation.fork_context_takeover
+        : undefined;
+    const needsNativeTakeoverBootstrap = nativeTakeoverForSend?.["needs_bootstrap"] === true;
+    const needsForkTakeoverBootstrap = forkTakeoverForSend?.["needs_bootstrap"] === true;
     const message = createMessage({
         conversation,
         from: "openclaw",
@@ -635,10 +1180,21 @@ function runSend(options) {
             executor_session: executor.session
         }
     });
+    const previousModelSelection = isRecord(conversation.model_selection)
+        ? conversation.model_selection
+        : {};
     const nextConversation = {
         ...applyMessageToConversation(conversation, message),
         executor,
-        claude_session: executor.kind === "claude" ? executor.session : conversation.claude_session
+        claude_session: executor.kind === "claude" ? executor.session : conversation.claude_session,
+        executor_model: options.model ?? conversation.executor_model,
+        model_selection: conversation.status === "needs_model_selection"
+            ? {
+                ...previousModelSelection,
+                resolved_at: new Date().toISOString(),
+                selected_model: options.model
+            }
+            : conversation.model_selection
     };
     saveState(statePath, nextConversation);
     appendEvent(logPath, messageEvent(message));
@@ -651,10 +1207,34 @@ function runSend(options) {
         event_log_path: logPath,
         message: textSummary(messageBody)
     });
-    const acpxPath = resolveExecutable("acpx");
     const executorEnv = environmentForExecutor(executor, {
         allProxy: options.allProxy ?? conversation.executor_all_proxy
     });
+    const payload = buildAgentSendPayload({
+        conversation,
+        executor,
+        message,
+        includeNativeTakeoverBootstrap: needsNativeTakeoverBootstrap,
+        includeForkTakeoverBootstrap: needsForkTakeoverBootstrap,
+        forkTakeover: forkTakeoverForSend
+    });
+    if (nativeTakeoverForSend?.["native_session_id"] && executor.kind === "codex") {
+        runNativeCodexResumeSend({
+            options,
+            conversation,
+            nextConversation,
+            statePath,
+            logPath,
+            executor,
+            executorEnv,
+            message,
+            payload,
+            nativeTakeover: nativeTakeoverForSend,
+            needsNativeTakeoverBootstrap
+        });
+        return;
+    }
+    const acpxPath = resolveExecutable("acpx");
     const executorModel = modelForExecutor(executor, {
         model: options.model ?? conversation.executor_model
     });
@@ -662,7 +1242,8 @@ function runSend(options) {
         acpxPath,
         executor,
         cwd: conversation.workspace ?? process.cwd(),
-        env: executorEnv
+        env: executorEnv,
+        resumeSessionId: nativeTakeoverForSend?.["native_session_id"]
     });
     appendEvent(logPath, {
         ts: new Date().toISOString(),
@@ -714,13 +1295,6 @@ function runSend(options) {
         }
         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`);
@@ -766,8 +1340,16 @@ function runSend(options) {
             executor_pid: child.pid ?? null,
             agent_timeout_minutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES)
         });
-        printJson({
+        const deliveredConversation = markTakeoverBootstrapped({
             conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            native: needsNativeTakeoverBootstrap,
+            fork: needsForkTakeoverBootstrap
+        });
+        printJson({
+            conversation: deliveredConversation,
             message,
             delivered: true,
             background: true,
@@ -835,13 +1417,303 @@ function runSend(options) {
         }
         throw new Error(cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`));
     }
+    const deliveredConversation = markTakeoverBootstrapped({
+        conversation: nextConversation,
+        statePath,
+        logPath,
+        executor,
+        native: needsNativeTakeoverBootstrap,
+        fork: needsForkTakeoverBootstrap
+    });
     printJson({
+        conversation: deliveredConversation,
+        message,
+        delivered: true,
+        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"]);
+    const nativeModel = nativeCodexModelForSend({ options, conversation, nativeTakeover });
+    const codexArgs = buildCodexExecResumeArgs({
+        nativeSessionId,
+        payload,
+        model: nativeModel
+    });
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "native_executor_resume_prepare",
+        executor,
+        native_session_id: nativeSessionId,
+        model: nativeModel ?? null
+    });
+    runtimeLog("info", "native_executor_resume_prepare", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        native_session_id: nativeSessionId,
+        model: nativeModel
+    });
+    if (options.background) {
+        const outputPath = path.join(path.dirname(logPath), `${executor.kind}-native-resume-output.log`);
+        const outputFd = fs.openSync(outputPath, "a");
+        const child = spawn(codexPath, codexArgs, {
+            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: "native_executor_resume_launch",
+            mode: "background",
+            pid: child.pid ?? null,
+            executor,
+            native_session_id: nativeSessionId,
+            output_path: outputPath
+        });
+        runtimeLog("info", "native_executor_resume_launch", {
+            conversation_id: conversation.conversation_id,
+            agent: executor.kind,
+            executor_session: executor.session,
+            native_session_id: nativeSessionId,
+            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)
+        });
+        const deliveredConversation = markTakeoverBootstrapped({
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            native: needsNativeTakeoverBootstrap,
+            fork: false
+        });
+        printJson({
+            conversation: deliveredConversation,
+            message,
+            delivered: true,
+            background: true,
+            native_resume: true,
+            pid: child.pid ?? null,
+            monitor_pid: monitor.pid ?? null,
+            output_path: outputPath,
+            executor,
+            budget: budgetAction(deliveredConversation)
+        });
+        return;
+    }
+    const sendResult = spawnSync(codexPath, codexArgs, {
+        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: "native_executor_resume_send",
+        status: sendResult.status ?? null,
+        executor,
+        native_session_id: nativeSessionId,
+        stdout: cleanProcessText(sendResult.stdout),
+        stderr: cleanProcessText(sendResult.stderr)
+    });
+    runtimeLog("info", "native_executor_resume_send", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        native_session_id: nativeSessionId,
+        status: sendResult.status ?? null,
+        failure_kind: classifyProcessFailure(sendResult),
+        stdout: textSummary(cleanProcessText(sendResult.stdout)),
+        stderr: textSummary(cleanProcessText(sendResult.stderr))
+    });
+    if (sendResult.error) {
+        throw new Error(`codex exec resume failed to start: ${sendResult.error.message}`);
+    }
+    if (sendResult.status !== 0) {
+        throw new Error(cleanProcessText(sendResult.stderr || sendResult.stdout || `codex exec resume exited with status ${sendResult.status}`));
+    }
+    const deliveredConversation = markTakeoverBootstrapped({
         conversation: nextConversation,
+        statePath,
+        logPath,
+        executor,
+        native: needsNativeTakeoverBootstrap,
+        fork: false
+    });
+    printJson({
+        conversation: deliveredConversation,
         message,
         delivered: true,
+        native_resume: true,
         executor,
-        budget: budgetAction(nextConversation)
+        budget: budgetAction(deliveredConversation)
+    });
+}
+function buildCodexExecResumeArgs({ nativeSessionId, payload, model }) {
+    const args = ["exec", "resume"];
+    if (model) {
+        args.push("--model", model);
+    }
+    args.push("--skip-git-repo-check", nativeSessionId, payload);
+    return args;
+}
+function nativeCodexModelForSend({ options, conversation, nativeTakeover }) {
+    const explicit = options.model ?? options.codexModel;
+    if (explicit) {
+        return normalizeNativeCodexModel(explicit);
+    }
+    const nativeModel = isRecord(nativeTakeover) ? nativeTakeover["native_model"] : undefined;
+    if (typeof nativeModel === "string" && nativeModel.trim()) {
+        return normalizeNativeCodexModel(nativeModel);
+    }
+    return normalizeNativeCodexModel(conversation.executor_model);
+}
+function normalizeNativeCodexModel(model) {
+    const value = typeof model === "string" ? model.trim() : "";
+    if (!value) {
+        return undefined;
+    }
+    return value.replace(/\[[^\]]+\]$/u, "").replace(/\/(?:low|medium|high|xhigh)$/u, "");
+}
+function buildAgentSendPayload({ conversation, executor, message, includeNativeTakeoverBootstrap, includeForkTakeoverBootstrap, forkTakeover }) {
+    const messageJson = JSON.stringify(message);
+    if (!includeNativeTakeoverBootstrap && !includeForkTakeoverBootstrap) {
+        return [
+            "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.",
+            "",
+            messageJson
+        ].join("\n");
+    }
+    if (includeForkTakeoverBootstrap) {
+        const summary = forkTakeoverSummaryText(forkTakeover);
+        return [
+            executorBootstrapPrompt({
+                callbackCommand: conversation.callback_command,
+                executorName: executor.display_name,
+                softLimit: Number(conversation.soft_limit ?? 50),
+                hardLimit: Number(conversation.hard_limit ?? 100)
+            }),
+            "",
+            "This AKK conversation is a fork of an existing native coding-agent session. Do not resume the original native session. Treat the approved summary below as the only imported context from the source session, then continue as a new AKK-managed session in this workspace.",
+            "",
+            "Approved source-session summary:",
+            summary || "(No approved summary was provided.)",
+            "",
+            "Initial AKK fork message:",
+            messageJson
+        ].join("\n");
+    }
+    return [
+        executorBootstrapPrompt({
+            callbackCommand: conversation.callback_command,
+            executorName: executor.display_name,
+            softLimit: Number(conversation.soft_limit ?? 50),
+            hardLimit: Number(conversation.hard_limit ?? 100)
+        }),
+        "",
+        "This AKK conversation is attaching to an existing native coding-agent session. Continue from the native session context if it is available, and use the callback command above for all replies to OpenClaw.",
+        "",
+        "Initial AKK takeover message:",
+        messageJson
+    ].join("\n");
+}
+function forkTakeoverSummaryText(forkTakeover) {
+    return String(isRecord(forkTakeover) ? forkTakeover.summary ?? "" : "").trim();
+}
+function markTakeoverBootstrapped({ conversation, statePath, logPath, executor, native, fork }) {
+    let nextConversation = conversation;
+    if (native) {
+        nextConversation = markNativeSessionBootstrapped({ conversation: nextConversation, statePath, logPath, executor });
+    }
+    if (fork) {
+        nextConversation = markForkSessionBootstrapped({ conversation: nextConversation, statePath, logPath, executor });
+    }
+    return nextConversation;
+}
+function markNativeSessionBootstrapped({ conversation, statePath, logPath, executor }) {
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : {};
+    const now = new Date().toISOString();
+    const nextConversation = {
+        ...conversation,
+        native_session_takeover: {
+            ...nativeTakeover,
+            needs_bootstrap: false,
+            bootstrapped_at: now
+        },
+        updated_at: now
+    };
+    saveState(statePath, nextConversation);
+    appendEvent(logPath, {
+        ts: now,
+        conversation_id: conversation.conversation_id,
+        event: "native_session_bootstrapped",
+        executor
+    });
+    runtimeLog("info", "native_session_bootstrapped", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        state_path: statePath
+    });
+    return nextConversation;
+}
+function markForkSessionBootstrapped({ conversation, statePath, logPath, executor }) {
+    const forkTakeover = isRecord(conversation.fork_context_takeover)
+        ? conversation.fork_context_takeover
+        : {};
+    const now = new Date().toISOString();
+    const nextConversation = {
+        ...conversation,
+        fork_context_takeover: {
+            ...forkTakeover,
+            needs_bootstrap: false,
+            bootstrapped_at: now
+        },
+        updated_at: now
+    };
+    saveState(statePath, nextConversation);
+    appendEvent(logPath, {
+        ts: now,
+        conversation_id: conversation.conversation_id,
+        event: "fork_session_bootstrapped",
+        executor
+    });
+    runtimeLog("info", "fork_session_bootstrapped", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        state_path: statePath
     });
+    return nextConversation;
 }
 function requiresExplicitRecoveryDecision(executor, options = {}) {
     if (options.recoveryPolicy === "explicit" || options.recoveryPolicy === "explicit-decision") {
@@ -1216,6 +2088,27 @@ function runMonitor(options) {
             return;
         }
         if (Number.isFinite(pid) && !isProcessAlive(pid)) {
+            const modelSelection = detectModelSelectionError(readOutputTail(options.outputPath));
+            if (modelSelection) {
+                const modelSelectionConversation = markConversationNeedsModelSelection({
+                    statePath,
+                    logPath,
+                    reason: modelSelection.message,
+                    detail: {
+                        executor_pid: pid,
+                        output_path: options.outputPath,
+                        model_selection: modelSelection
+                    }
+                });
+                printJson({
+                    conversation: modelSelectionConversation,
+                    monitored: true,
+                    stalled: false,
+                    needs_model_selection: true,
+                    reason: modelSelectionConversation?.model_selection?.message ?? modelSelection.message
+                });
+                return;
+            }
             const stalledConversation = markConversationStalled({
                 statePath,
                 logPath,
@@ -1884,12 +2777,65 @@ function isWaitingForAgent(status) {
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
-        return true;
+        return !isZombieProcess(pid);
     }
     catch (error) {
         return error?.code === "EPERM";
     }
 }
+function isZombieProcess(pid) {
+    const result = spawnSync("ps", ["-o", "stat=", "-p", String(pid)], {
+        encoding: "utf8"
+    });
+    if (result.status !== 0) {
+        return false;
+    }
+    return result.stdout.trim().toUpperCase().startsWith("Z");
+}
+function terminateProcessTarget(target, { timeoutMs = 3000 } = {}) {
+    const pids = [...target.childPids, target.pid]
+        .filter((pid, index, all) => Number.isInteger(pid) && pid > 0 && all.indexOf(pid) === index);
+    const signals = [];
+    for (const pid of pids) {
+        signals.push(sendSignalToPid(pid, "SIGTERM"));
+    }
+    const exited = waitForPidsToExit(pids, timeoutMs);
+    return {
+        target,
+        signal: "SIGTERM",
+        signals,
+        exited,
+        remainingPids: pids.filter((pid) => isProcessAlive(pid))
+    };
+}
+function sendSignalToPid(pid, signal) {
+    try {
+        process.kill(pid, signal);
+        return {
+            pid,
+            signal,
+            status: "sent"
+        };
+    }
+    catch (error) {
+        return {
+            pid,
+            signal,
+            status: "failed",
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function waitForPidsToExit(pids, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (pids.every((pid) => !isProcessAlive(pid))) {
+            return true;
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    }
+    return pids.every((pid) => !isProcessAlive(pid));
+}
 function markConversationStalled({ statePath, logPath, reason, detail = {} }) {
     const releaseLock = acquireFileLock(`${statePath}.lock`);
     let stalledConversation;
@@ -1938,16 +2884,70 @@ function markConversationStalled({ statePath, logPath, reason, detail = {} }) {
             statePath,
             logPath,
             conversation: stalledConversation,
-            reason
+            reason,
+            detail
         });
     }
     return stalledConversation;
 }
-function deliverStalledNotification({ statePath, logPath, conversation, reason }) {
+function markConversationNeedsModelSelection({ statePath, logPath, reason, detail = {} }) {
+    const releaseLock = acquireFileLock(`${statePath}.lock`);
+    let modelSelectionConversation;
+    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_model_selection"
+            });
+            return conversation;
+        }
+        const now = new Date().toISOString();
+        const detailRecord = detail;
+        const modelSelection = isRecord(detailRecord.model_selection)
+            ? detailRecord.model_selection
+            : {};
+        modelSelectionConversation = {
+            ...conversation,
+            status: "needs_model_selection",
+            model_selection: {
+                detected_at: now,
+                message: reason,
+                ...modelSelection
+            },
+            updated_at: now
+        };
+        saveState(statePath, modelSelectionConversation);
+        appendEvent(logPath, {
+            ts: now,
+            conversation_id: conversation.conversation_id,
+            event: "conversation_needs_model_selection",
+            status: "needs_model_selection",
+            reason,
+            ...detailRecord
+        });
+        runtimeLog("warn", "conversation_needs_model_selection", {
+            conversation_id: conversation.conversation_id,
+            agent: executorForConversation(conversation).kind,
+            executor_session: executorForConversation(conversation).session,
+            state_path: statePath,
+            event_log_path: logPath,
+            reason,
+            ...detailRecord
+        });
+    }
+    finally {
+        releaseLock();
+    }
+    return modelSelectionConversation;
+}
+function deliverStalledNotification({ statePath, logPath, conversation, reason, detail = {} }) {
     if (!conversation.gateway_method) {
         return;
     }
     const executor = executorForConversation(conversation);
+    const trace = buildStalledTraceSummary({ conversation, logPath, detail });
     const message = createMessage({
         conversation,
         from: executor.actor,
@@ -1959,14 +2959,17 @@ function deliverStalledNotification({ statePath, logPath, conversation, reason }
             "",
             `Conversation: ${conversation.conversation_id}`,
             `Session: ${executor.session}`,
+            trace ? `Trace: ${trace}` : "",
             "Use `AKK status` for details, `AKK send` to retry/follow up, or `AKK close` to close it."
-        ].join("\n")
+        ].filter(Boolean).join("\n")
     });
+    const gatewayToken = conversation.gateway_token;
+    const gatewayUrl = gatewayToken ? conversation.gateway_url : undefined;
     const delivery = deliverToGatewayMethod({
         method: conversation.gateway_method,
         openclawBin: conversation.openclaw_bin,
-        gatewayUrl: conversation.gateway_url,
-        token: conversation.gateway_token,
+        gatewayUrl,
+        token: gatewayToken,
         sessionKey: conversation.gateway_session ?? conversation.openclaw_session,
         statePath,
         logPath,
@@ -2000,8 +3003,8 @@ function deliverStalledNotification({ statePath, logPath, conversation, reason }
     }
     const chatSendDelivery = deliverToChatSend({
         openclawBin: conversation.openclaw_bin,
-        gatewayUrl: conversation.gateway_url,
-        token: conversation.gateway_token,
+        gatewayUrl,
+        token: gatewayToken,
         params: chatSendParams
     });
     appendEvent(logPath, {
@@ -2020,6 +3023,42 @@ function deliverStalledNotification({ statePath, logPath, conversation, reason }
         stderr: textSummary(chatSendDelivery.stderr)
     });
 }
+function buildStalledTraceSummary({ conversation, logPath, detail = {} }) {
+    const detailRecord = isRecord(detail) ? detail : {};
+    const outputPath = typeof detailRecord.output_path === "string"
+        ? detailRecord.output_path
+        : traceOutputPath({
+            conversation,
+            events: safeReadEvents(logPath),
+            logPath
+        });
+    if (!outputPath || !fs.existsSync(outputPath)) {
+        return undefined;
+    }
+    const output = fs.readFileSync(outputPath, "utf8").slice(-64 * 1024);
+    const parts = output
+        .split(/\r?\n/)
+        .map((line) => sanitizeTraceText(line.trim(), 220))
+        .filter((line) => line &&
+        !line.startsWith("input:") &&
+        !line.startsWith("output:") &&
+        !line.startsWith("{") &&
+        !line.startsWith("}") &&
+        !line.includes("--message-json"))
+        .slice(-6);
+    if (parts.length === 0) {
+        return undefined;
+    }
+    return cleanProcessText(parts.join(" | "))?.slice(0, 500);
+}
+function safeReadEvents(logPath) {
+    try {
+        return readNdjsonLog(logPath);
+    }
+    catch {
+        return [];
+    }
+}
 function cleanupIdleConversations(storeDir, options = {}, now = new Date()) {
     const timeoutMinutes = Number(options.idleTimeoutMinutes ?? DEFAULT_IDLE_TIMEOUT_MINUTES);
     if (!Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0) {
@@ -2266,6 +3305,32 @@ function parseOptionalJson(text) {
         return undefined;
     }
 }
+function createAgentSessionProvider(agent, options) {
+    if (agent !== "codex") {
+        throw new Error(`unsupported agent session provider: ${agent}`);
+    }
+    if (options.threadsJson || options.processesJson || options.rolloutsJson) {
+        return new CodexLocalSessionProvider(new InlineCodexSessionAdapter({
+            threads: parseJsonOption(options.threadsJson, "--threads-json"),
+            processes: parseJsonOption(options.processesJson, "--processes-json"),
+            rollouts: parseJsonOption(options.rolloutsJson, "--rollouts-json")
+        }));
+    }
+    return new CodexLocalSessionProvider(new CodexStoreAdapter({
+        codexHome: expandHome(options.codexHome)
+    }));
+}
+function parseJsonOption(value, optionName) {
+    if (!value) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(String(value));
+    }
+    catch (error) {
+        throw new Error(`${optionName} must be valid JSON: ${error.message}`);
+    }
+}
 function expandHome(filePath) {
     if (filePath === "~") {
         return process.env.HOME;
@@ -2316,6 +3381,56 @@ function classifyProcessFailure(result) {
     }
     return undefined;
 }
+function readOutputTail(outputPath, maxBytes = 65536) {
+    if (!outputPath) {
+        return "";
+    }
+    try {
+        const resolvedPath = expandHome(outputPath);
+        const stat = fs.statSync(resolvedPath);
+        const start = Math.max(0, stat.size - maxBytes);
+        const length = stat.size - start;
+        const fd = fs.openSync(resolvedPath, "r");
+        try {
+            const buffer = Buffer.alloc(length);
+            fs.readSync(fd, buffer, 0, length, start);
+            return buffer.toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return "";
+    }
+}
+function detectModelSelectionError(text) {
+    const cleaned = cleanProcessText(text);
+    if (!cleaned) {
+        return undefined;
+    }
+    const unsupportedAccount = /The '([^']+)' model is not supported when using Codex with a ChatGPT account/i.exec(cleaned);
+    if (unsupportedAccount) {
+        return {
+            kind: "unsupported_chatgpt_account_model",
+            attempted_model: unsupportedAccount[1],
+            message: unsupportedAccount[0]
+        };
+    }
+    const unadvertised = /Cannot apply --model "([^"]+)": the ACP agent did not advertise that model\. Available models:\s*([^\n\r]+)/i.exec(cleaned);
+    if (unadvertised) {
+        return {
+            kind: "unadvertised_acpx_model",
+            attempted_model: unadvertised[1],
+            available_models: unadvertised[2]
+                .split(",")
+                .map((model) => model.trim())
+                .filter(Boolean),
+            message: unadvertised[0]
+        };
+    }
+    return undefined;
+}
 function runtimeLog(level, event, fields = {}) {
     try {
         writeRuntimeLog({
@@ -2356,6 +3471,8 @@ function usage() {
   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 callback --state <file> --message-json <json> [--record-only]
   agent-knock-knock transcript --log <file> [--include-raw]
   agent-knock-knock transcript --conversation <dir> [--include-raw]