larkin 0.4.1 → 0.4.5

package/dist/app/agent-readiness.mjs

@@ -3,6 +3,19 @@ function timestamp(value) {
     const parsed = Date.parse(String(value || ""));
     return Number.isFinite(parsed) ? parsed : null;
 }
+export function isRuntimeReadinessCurrent(readiness, daemonStartedAt) {
+    if (readiness?.state !== "ready")
+        return false;
+    const observedAt = timestamp(readiness.observedAt);
+    const epoch = timestamp(daemonStartedAt);
+    return observedAt !== null && epoch !== null && observedAt >= epoch;
+}
+export function isCurrentOwnedDaemon(daemon) {
+    return daemon?.state === "owned"
+        && Number(daemon.pid) > 0
+        && typeof daemon.processStartToken === "string" && daemon.processStartToken.length > 0
+        && timestamp(daemon.startedAt) !== null;
+}
 export function isChannelReconnecting(status) {
     const reconnectingAt = timestamp(status?.reconnectingAt);
     const connectedAt = timestamp(status?.connectedAt);
@@ -12,9 +25,14 @@ export function isChannelReconnecting(status) {
 }
 export function projectAgentReadiness(input) {
     const status = input.status ?? null;
-    const daemonOwned = daemonHasAgent(input.daemon, input.agentId);
+    const daemonOwned = isCurrentOwnedDaemon(input.daemon) && daemonHasAgent(input.daemon, input.agentId);
     const daemonStartedAt = timestamp(input.daemon.startedAt);
     const connectedAt = timestamp(status?.connectedAt);
+    // A resumed session deliberately retains its original creation time.  Its
+    // current daemon-epoch proof is the fresh session observation, not that
+    // historic creation timestamp.
+    const sessionObservedAt = timestamp(status?.session?.lastSeenAt) ?? timestamp(status?.session?.startedAt);
+    const sessionCurrent = daemonStartedAt !== null && sessionObservedAt !== null && sessionObservedAt >= daemonStartedAt;
     const channelConnected = daemonOwned
         && status?.connectedVia === "channel"
         && daemonStartedAt !== null
@@ -22,7 +40,7 @@ export function projectAgentReadiness(input) {
         && connectedAt >= daemonStartedAt;
     const readiness = {
         daemon_owned: daemonOwned,
-        runtime_ready: status?.runtimeReadiness?.state === "ready",
+        runtime_ready: daemonOwned && sessionCurrent && isRuntimeReadinessCurrent(status?.runtimeReadiness, input.daemon.startedAt),
         channel_connected: channelConnected,
         channel_not_reconnecting: !isChannelReconnecting(status),
     };

package/dist/app/binary-entry.mjs

@@ -55,6 +55,12 @@ async function dispatchInternal(mode, rest) {
             process.title = "pi-rpc";
             process.env.PI_CODING_AGENT = "true";
             process.emitWarning = (() => { });
+            // The Pi package's normal Bun CLI registers OAuth loaders before starting.
+            // Larkin invokes its RPC entrypoint directly, so do the same here; otherwise
+            // an OAuth-backed compact falls back to a dynamic module import unavailable in
+            // a compiled standalone binary.
+            const { registerBunOAuthFlows } = await import("@earendil-works/pi-ai/bun-oauth");
+            registerBunOAuthFlows();
             const { main: piMain } = await import("@earendil-works/pi-coding-agent");
             const { invokeBuiltinPiRpc } = await import("../runtime/pi-inline-extensions.mjs");
             await invokeBuiltinPiRpc(piMain, rest);

package/dist/app/cli.mjs

@@ -29,6 +29,7 @@ const routes = {
     model: ["agent-config", "model"],
     runtime: ["agent-config", "runtime"],
     effort: ["agent-config", "effort"],
+    "pi-distribution": ["agent-config", "pi-distribution"],
     chats: ["agent-config", "chats"],
     config: ["agent-config", "config"],
     session: ["session-cli"],
@@ -58,6 +59,9 @@ List every configured Agent and its current local status. Use --json for daemon/
 Show or change an Agent model.`,
     runtime: `Usage: larkin runtime [<runtime>] [--agent <App ID>] [--model <model>]
 Show or change an Agent runtime.`,
+    "pi-distribution": `Usage: larkin pi-distribution [show|builtin|external] [--agent <App ID>] [--snapshot <private-file>] [--import-external-profile]
+       larkin pi-distribution rollback --snapshot <private-file>
+Show or change one Pi Agent distribution. builtin requires configured provider state, or explicitly imports the external Pi 0.84.2 profile with --import-external-profile; all changes support config-lock CAS rollback.`,
     effort: `Usage: larkin effort [<level>|clear|default] [--agent <App ID>]
 Show or change an Agent reasoning effort; clear/default restores the Runtime default.`,
     chats: `Usage: larkin chats [--agent <App ID>]
@@ -77,7 +81,8 @@ Examples:
 
 Credentials, internal paths, serverId, activeAgent, and raw config are never exposed here.`,
     session: `Usage: larkin session reset --agent <App ID> --json [--wait-ready <seconds>]
-Atomically replace one idle, zero-backlog Agent Runtime session through authenticated local control.`,
+       larkin session recover --agent <App ID> --reason context-overflow --json [--wait-ready <seconds>]
+Reset replaces one idle, zero-backlog Runtime session. Recover is an explicit operator-only context-window recovery that preserves and replays canonical Inbox deliveries.`,
     "pi-auth": `Usage: larkin pi-auth status [--agent <App ID>] [--json]
        larkin pi-auth logout <provider> [--agent <App ID>]
 Show non-sensitive official Pi credential metadata or remove one target provider credential.`,
@@ -124,6 +129,7 @@ Usage: larkin <command>
   chats            List known chats; use free/strict <oc_id> to configure mention requirements
   config           Inspect effective config/source, edit mention inheritance, or explicitly apply runtime changes
   session reset    Replace one idle, zero-backlog Agent Runtime session for a fresh scenario
+  session recover  Explicitly recover a context-overflowed session and replay retained Inbox deliveries
   pi-auth          Show non-sensitive built-in Pi auth status or logout one provider
   comment reply    Reply to the exact cloud-document comment bound by a polled Inbox message
   telemetry        Inspect, export, import, or flush the durable OpenTelemetry trace queue

package/dist/app/local-control.mjs

@@ -15,6 +15,48 @@ const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
 const OPERATION_ID = /^[A-Za-z0-9_-]{8,128}$/;
 const AUTHORIZATION = /^[A-Za-z0-9_-]{43,128}$/;
 const UNIX_SOCKET_PATH_MAX_BYTES = process.platform === "darwin" ? 103 : 107;
+function recoveryErrorText(code) {
+    switch (code) {
+        case "unknown_agent": return "unknown Agent";
+        case "agent_busy": return "Agent is not idle";
+        case "channel_unavailable": return "Runtime channel is unavailable";
+        case "channel_reconnecting": return "Runtime channel is reconnecting";
+        case "runtime_unavailable": return "Runtime readiness is unavailable";
+        case "recovery_unavailable": return "context-overflow recovery is unavailable";
+        case "recovery_staged_not_committed": return "context-overflow recovery was staged but not committed";
+        case "state_persistence_failed": return "context-overflow recovery committed but state persistence failed";
+        case "recovery_timeout": return "context-overflow recovery committed but readiness did not converge";
+        case "recovery_refused": return "context-overflow recovery was refused";
+        default: return "context-overflow recovery failed";
+    }
+}
+function sanitizeRecoveryReadiness(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    if (!["codex", "claude", "pi"].includes(String(candidate.runtime))
+        || !["missing", "unauthenticated", "unavailable", "incompatible", "ready"].includes(String(candidate.state)))
+        return undefined;
+    const runtime = candidate.runtime;
+    const state = candidate.state;
+    return { runtime, state,
+        ...(state === "ready" ? {} : { reason: `Runtime readiness is ${state}.`, nextAction: "Inspect Runtime/provider configuration, then retry." }) };
+}
+function sanitizeSessionRecoveryResponse(response, agentId) {
+    const code = typeof response.code === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(response.code) ? response.code : undefined;
+    return {
+        ok: response.ok === true, agentId, ...(code ? { code } : {}),
+        ...(code || response.error ? { error: recoveryErrorText(code) } : {}),
+        recoveryCommitted: response.recoveryCommitted === true, generationChanged: response.generationChanged === true,
+        sessionChanged: response.sessionChanged === true, turns: 0, runtimeReady: response.runtimeReady === true,
+        channelConnected: response.channelConnected === true, reconnecting: response.reconnecting === true,
+        pendingCount: Math.max(0, Number(response.pendingCount) || 0), rearmedCount: Math.max(0, Number(response.rearmedCount) || 0),
+        replayStatus: ["scheduled", "pending", "consumed", "not_started"].includes(response.replayStatus) ? response.replayStatus : "not_started",
+        remainingPendingCount: Math.max(0, Number(response.remainingPendingCount) || 0),
+        readyForFreshScenario: response.readyForFreshScenario === true, inboundObserved: false,
+        ...(sanitizeRecoveryReadiness(response.readiness) ? { readiness: sanitizeRecoveryReadiness(response.readiness) } : {}),
+    };
+}
 function socketPathsFit(root) {
     if (isWindows)
         return true; // Windows named-pipe socket paths use a much larger limit
@@ -92,7 +134,7 @@ function parseRequest(line) {
         throw new Error("invalid agent control request");
     }
     if (value.operation === "session-reset") {
-        if (value.waitReadyMs !== undefined && (!Number.isSafeInteger(value.waitReadyMs) || value.waitReadyMs < 0 || value.waitReadyMs > 300_000)) {
+        if (value.waitReadyMs !== undefined && (typeof value.waitReadyMs !== "number" || !Number.isSafeInteger(value.waitReadyMs) || value.waitReadyMs < 0 || value.waitReadyMs > 300_000)) {
             throw new Error("invalid session reset waitReadyMs");
         }
         if (Object.keys(value).some((key) => !["agentId", "authorization", "operation", "waitReadyMs"].includes(key))) {
@@ -100,6 +142,17 @@ function parseRequest(line) {
         }
         return value;
     }
+    if (value.operation === "session-recover") {
+        if (value.reason !== "context-overflow")
+            throw new Error("session recovery requires reason=context-overflow");
+        if (value.waitReadyMs !== undefined && (typeof value.waitReadyMs !== "number" || !Number.isSafeInteger(value.waitReadyMs) || value.waitReadyMs < 0 || value.waitReadyMs > 300_000)) {
+            throw new Error("invalid session recovery waitReadyMs");
+        }
+        if (Object.keys(value).some((key) => !["agentId", "authorization", "operation", "reason", "waitReadyMs"].includes(key))) {
+            throw new Error("session recovery control request 包含未知字段");
+        }
+        return value;
+    }
     if (value.operation !== undefined || !OPERATION_ID.test(String(value.operationId || ""))) {
         throw new Error("invalid agent upsert request");
     }
@@ -498,13 +551,14 @@ export function createSupervisorControlServer({ larkinHome, authorityToken, ensu
         },
     };
 }
-export function createAgentControlServer({ larkinHome, authorityToken, upsert, resetSession, maxRememberedOperations = 256, }) {
+export function createAgentControlServer({ larkinHome, authorityToken, upsert, resetSession, recoverSession, maxRememberedOperations = 256, }) {
     let socket = "";
     let socketRoot = "";
     let socketIdentity = null;
     const completed = new Map();
     const inFlight = new Map();
     const resetInFlight = new Map();
+    const recoveryInFlight = new Map();
     const agentQueues = new Map();
     const upsertConflict = (operationId, agentId) => ({
         ok: false, operationId, agentId, code: "operation_conflict", error: "operationId 已绑定其他 Agent 或操作",
@@ -564,6 +618,52 @@ export function createAgentControlServer({ larkinHome, authorityToken, upsert, r
                             return;
                         }
                         if ("operation" in request) {
+                            if (request.operation === "session-recover") {
+                                const recoveryRequest = request;
+                                let operation = recoveryInFlight.get(recoveryRequest.agentId);
+                                if (!operation) {
+                                    const executeRecovery = async () => {
+                                        try {
+                                            if (!recoverSession)
+                                                throw new Error("session recovery control unavailable");
+                                            const result = await recoverSession({ agentId: recoveryRequest.agentId, reason: recoveryRequest.reason,
+                                                waitReadyMs: recoveryRequest.waitReadyMs ?? 30_000 });
+                                            return sanitizeSessionRecoveryResponse(result, recoveryRequest.agentId);
+                                        }
+                                        catch (error) {
+                                            const code = typeof error.code === "string"
+                                                ? String(error.code)
+                                                : error instanceof RuntimePrerequisiteError && error.readiness.state === "unavailable"
+                                                    ? "runtime_unavailable" : "recovery_refused";
+                                            const projection = error;
+                                            return { ok: false, agentId: recoveryRequest.agentId, code,
+                                                error: recoveryErrorText(code), recoveryCommitted: false,
+                                                generationChanged: false, sessionChanged: false, turns: Math.max(0, Number(projection.turns) || 0),
+                                                runtimeReady: projection.runtimeReady === true, channelConnected: projection.channelConnected === true,
+                                                reconnecting: projection.reconnecting === true, pendingCount: Math.max(0, Number(projection.pendingCount) || 0),
+                                                rearmedCount: Math.max(0, Number(projection.rearmedCount) || 0), replayStatus: "not_started",
+                                                remainingPendingCount: Math.max(0, Number(projection.remainingPendingCount) || 0),
+                                                readyForFreshScenario: false, inboundObserved: false,
+                                                ...(error instanceof RuntimePrerequisiteError ? { readiness: sanitizeRecoveryReadiness(error.readiness) } : {}) };
+                                        }
+                                    };
+                                    const prior = agentQueues.get(recoveryRequest.agentId) ?? Promise.resolve();
+                                    const executing = prior.catch(() => { }).then(executeRecovery);
+                                    let queued;
+                                    queued = executing.finally(() => {
+                                        if (agentQueues.get(recoveryRequest.agentId) === queued)
+                                            agentQueues.delete(recoveryRequest.agentId);
+                                        if (recoveryInFlight.get(recoveryRequest.agentId) === queued)
+                                            recoveryInFlight.delete(recoveryRequest.agentId);
+                                    });
+                                    agentQueues.set(recoveryRequest.agentId, queued);
+                                    recoveryInFlight.set(recoveryRequest.agentId, queued);
+                                    operation = queued;
+                                }
+                                const response = await operation;
+                                connection.end(`${JSON.stringify(response)}\n`);
+                                return;
+                            }
                             const resetRequest = request;
                             let operation = resetInFlight.get(resetRequest.agentId);
                             if (!operation) {
@@ -776,6 +876,12 @@ export async function requestSessionReset({ larkinHome, agentId, waitReadyMs = 3
         request: { operation: "session-reset", agentId, waitReadyMs },
     });
 }
+export async function requestSessionRecovery({ larkinHome, agentId, reason = "context-overflow", waitReadyMs = 30_000, }) {
+    return requestAgentControl({
+        larkinHome, timeoutMs: Math.max(1_000, waitReadyMs + 1_000),
+        request: { operation: "session-recover", agentId, reason, waitReadyMs },
+    });
+}
 export function cleanupStaleAgentControlSocket(larkinHome, expectedToken) {
     const authority = secureAuthority(larkinHome);
     if (!sameSecret(authority.token, expectedToken))

package/dist/app/run.mjs

@@ -11,6 +11,7 @@ import { acquireProcessLock, readProcessState, terminateOwnedProcess, waitForPro
 import { hydrateRuntimeAgent, syncAgentProfile } from "./runtime-agent-config.mjs";
 import { cleanupStaleAgentControlSocket, createSupervisorControlServer, initializeControlAuthority, removeControlAuthority, requestDashboardRecovery, } from "./local-control.mjs";
 import { internalCommandSpec, processCommandToken } from "./internal-command.mjs";
+import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const die = (message) => { console.error(`✗ ${message}`); process.exit(1); };
 export function selectedAgentIds(argv, available) {
@@ -63,8 +64,11 @@ export async function stopDashboardWithinBound(child, configDir, signal = "SIGTE
     return await waitForChildExit(child, Math.max(250, Math.min(2_000, timeoutMs))) ? "killed" : "unowned";
 }
 export async function main() {
+    process.env.LARKIN_DAEMON_EPOCH ||= new Date().toISOString();
     const argv = process.argv.slice(2);
     const { configDir, file: configFile, config } = larkinConfig.loadConfig(process.env);
+    for (const agent of Object.values(config.agents))
+        traceProcessBoundary(process.env, "supervisor:config-loaded", { configDir, agentId: agent.agentId, targetDir: path.join(configDir, "providers", "pi", agent.agentId) });
     if (!fs.existsSync(configFile))
         die(`没找到配置 ${configFile}，先跑 larkin setup`);
     if (!config.serverId || !Object.keys(config.agents).length)
@@ -193,6 +197,8 @@ export async function main() {
     };
     if (argv.includes("--dry-run"))
         runtimeEnv.LARKIN_FEISHU_DRYRUN = "1";
+    for (const agent of agents)
+        traceProcessBoundary(runtimeEnv, "supervisor:daemon-env-prepared", { configDir, agentId: agent.agentId, targetDir: path.join(configDir, "providers", "pi", agent.agentId) });
     let stopping = false;
     let dashboard = null;
     // Set when the daemon-restart path stops the dashboard on purpose (port
@@ -218,6 +224,8 @@ export async function main() {
     // external process manager (launchd) takes over as the final respawn layer.
     const launchDaemon = () => {
         daemon = spawn(daemonSpec.command, daemonSpec.args, { env: runtimeEnv, stdio: "inherit" });
+        for (const agent of agents)
+            traceProcessBoundary(runtimeEnv, "supervisor:daemon-spawned", { configDir, agentId: agent.agentId, targetDir: path.join(configDir, "providers", "pi", agent.agentId), childPid: daemon.pid ?? null });
         daemon.once("exit", (code, signal) => {
             if (stopping) {
                 resolveDaemonFinal?.({ code, signal });

package/dist/app/runtime-process.mjs

@@ -7,6 +7,7 @@ import { createNativeRuntimeAdapter } from "../runtime/runtime-adapters.mjs";
 import { createRuntimeHost } from "../runtime/runtime-host.mjs";
 import { createAgentStateStore } from "../agent/agent-state-store.mjs";
 import { loadConfig, markConfigApplied, runtimeConfigSignature } from "../platform/config.mjs";
+import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 import { createAgentControlServer } from "./local-control.mjs";
 import { hydrateRuntimeAgent, syncAgentProfile } from "./runtime-agent-config.mjs";
 import { loadTelemetryConfig } from "../platform/telemetry-config.mjs";
@@ -53,6 +54,7 @@ export async function main(env = process.env, overrides = {}) {
         channelPackage = await import(pathToFileURL(path.resolve(env.LARKIN_TEST_CHANNEL_MODULE)).href);
     }
     const adapters = new Map();
+    env.LARKIN_DAEMON_EPOCH ||= new Date().toISOString();
     const runtimeHost = overrides.runtimeHost ?? createRuntimeHost({
         promptBuilder: new ContextPromptBuilder(),
         stateStoreFor(agentId) {
@@ -91,6 +93,9 @@ export async function main(env = process.env, overrides = {}) {
         throw new Error("LARKIN_HOME/LARKIN_CONFIG_DIR required");
     if (!env.LARKIN_CONTROL_AUTHORIZATION)
         throw new Error("LARKIN_CONTROL_AUTHORIZATION required");
+    const loaded = loadConfig(env);
+    for (const agent of Object.values(loaded.config.agents))
+        traceProcessBoundary(env, "daemon:config-loaded", { configDir: loaded.configDir, agentId: agent.agentId, targetDir: path.join(loaded.configDir, "providers", "pi", agent.agentId) });
     controlServer = createAgentControlServer({
         larkinHome: env.LARKIN_HOME,
         authorityToken: env.LARKIN_CONTROL_AUTHORIZATION,
@@ -104,9 +109,20 @@ export async function main(env = process.env, overrides = {}) {
             const result = await hostShell.resetSession(request.agentId, request.waitReadyMs);
             return { ok: result.readyForFreshScenario, agentId: request.agentId, ...result };
         },
+        async recoverSession(request) {
+            const result = await hostShell.recoverSession(request.agentId, request.reason, request.waitReadyMs);
+            return { ok: result.recoveryCommitted, agentId: request.agentId, ...result };
+        },
     });
     await controlServer.start();
-    await markConfigAppliedAfterRuntimeReady(env, hostShell.agents, hostShell.start());
+    for (const agent of hostShell.agents)
+        traceProcessBoundary(env, "daemon:before-runtime-ready", { configDir: loaded.configDir, agentId: agent.agentId, targetDir: path.join(loaded.configDir, "providers", "pi", agent.agentId) });
+    const runtimeStart = hostShell.start().catch((error) => {
+        for (const agent of hostShell.agents)
+            traceProcessBoundary(env, "daemon:runtime-ready-failure", { configDir: loaded.configDir, agentId: agent.agentId, targetDir: path.join(loaded.configDir, "providers", "pi", agent.agentId), error });
+        throw error;
+    });
+    await markConfigAppliedAfterRuntimeReady(env, hostShell.agents, runtimeStart);
 }
 if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) {
     main().catch((error) => { console.error(`✗ ${error instanceof Error ? error.message : String(error)}`); process.exit(1); });

package/dist/app/session-cli.mjs

@@ -1,8 +1,19 @@
 import { loadConfig } from "../platform/config.mjs";
-import { requestSessionReset } from "./local-control.mjs";
-function parseResetArguments(args) {
-    if (args[0] !== "reset")
+import { requestSessionRecovery, requestSessionReset } from "./local-control.mjs";
+function sanitizeRecoveryReadiness(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    if (!["codex", "claude", "pi"].includes(String(candidate.runtime))
+        || !["missing", "unauthenticated", "unavailable", "incompatible", "ready"].includes(String(candidate.state)))
+        return undefined;
+    return { runtime: candidate.runtime, state: candidate.state,
+        ...(candidate.state === "ready" ? {} : { reason: `Runtime readiness is ${String(candidate.state)}.`, nextAction: "Inspect Runtime/provider configuration, then retry." }) };
+}
+function parseSessionArguments(args) {
+    if (args[0] !== "reset" && args[0] !== "recover")
         throw new Error("unsupported session subcommand");
+    const operation = args[0];
     const values = new Map();
     let json = false;
     for (let index = 1; index < args.length; index += 1) {
@@ -13,7 +24,7 @@ function parseResetArguments(args) {
             json = true;
             continue;
         }
-        if (!["--agent", "--wait-ready"].includes(token)) {
+        if (!["--agent", "--wait-ready", "--reason"].includes(token)) {
             throw new Error(token.startsWith("-") ? `unknown flag: ${token}` : `unexpected positional: ${token}`);
         }
         if (values.has(token))
@@ -32,7 +43,12 @@ function parseResetArguments(args) {
     const waitSeconds = Number(values.get("--wait-ready") ?? "30");
     if (!Number.isFinite(waitSeconds) || waitSeconds < 0 || waitSeconds > 300)
         throw new Error("--wait-ready must be 0..300 seconds");
-    return { agentId, waitReadyMs: Math.round(waitSeconds * 1000) };
+    const reason = values.get("--reason");
+    if (operation === "recover" && reason !== "context-overflow")
+        throw new Error("--reason context-overflow is required for session recover");
+    if (operation === "reset" && reason !== undefined)
+        throw new Error("--reason is only valid for session recover");
+    return { operation, agentId, waitReadyMs: Math.round(waitSeconds * 1000), ...(reason ? { reason: reason } : {}) };
 }
 export async function runSessionCli(args, env = process.env, dependencies = {}) {
     const io = dependencies.io ?? { stdout: (value) => process.stdout.write(value), stderr: (value) => process.stderr.write(value) };
@@ -42,29 +58,46 @@ export async function runSessionCli(args, env = process.env, dependencies = {})
     };
     let parsed;
     try {
-        parsed = parseResetArguments(args);
+        parsed = parseSessionArguments(args);
     }
     catch (error) {
         return fail("invalid_arguments", error instanceof Error ? error.message : String(error));
     }
     const agentId = parsed.agentId;
     if (typeof env.LARKIN_AGENT_ID === "string" && env.LARKIN_AGENT_ID.trim()) {
-        return fail("user_authority_required", "session reset is available only from a user terminal", agentId);
+        return fail("user_authority_required", parsed.operation === "reset"
+            ? "session reset is available only from a user terminal"
+            : "session recovery is available only from a user terminal", agentId);
     }
     try {
         const loaded = loadConfig(env);
-        const result = await (dependencies.request ?? requestSessionReset)({
-            larkinHome: loaded.config.larkinHome, agentId, waitReadyMs: parsed.waitReadyMs,
-        });
-        const output = {
-            ok: result.ok, agent_id: result.agentId,
-            reset_committed: result.resetCommitted, generation_changed: result.generationChanged,
-            session_changed: result.sessionChanged, turns: result.turns, runtime_ready: result.runtimeReady,
-            channel_connected: result.channelConnected, reconnecting: result.reconnecting,
-            pending_count: result.pendingCount, ready_for_fresh_scenario: result.readyForFreshScenario,
-            inbound_observed: result.inboundObserved, ...(result.code ? { code: result.code } : {}),
-            ...(result.error ? { error: result.error } : {}), ...(result.readiness ? { readiness: result.readiness } : {}),
-        };
+        const result = parsed.operation === "recover"
+            ? await (dependencies.requestRecovery ?? requestSessionRecovery)({
+                larkinHome: loaded.config.larkinHome, agentId, reason: parsed.reason, waitReadyMs: parsed.waitReadyMs,
+            })
+            : await (dependencies.request ?? requestSessionReset)({
+                larkinHome: loaded.config.larkinHome, agentId, waitReadyMs: parsed.waitReadyMs,
+            });
+        const output = "recoveryCommitted" in result
+            ? {
+                ok: result.ok, agent_id: result.agentId, recovery_committed: result.recoveryCommitted,
+                generation_changed: result.generationChanged, session_changed: result.sessionChanged, turns: result.turns,
+                runtime_ready: result.runtimeReady, channel_connected: result.channelConnected, reconnecting: result.reconnecting,
+                pending_count: result.pendingCount, rearmed_count: result.rearmedCount, replay_status: result.replayStatus,
+                remaining_pending_count: result.remainingPendingCount, ready_for_fresh_scenario: result.readyForFreshScenario,
+                inbound_observed: result.inboundObserved, ...(result.code ? { code: result.code } : {}),
+                ...(result.error ? { error: "context-overflow recovery failed" } : {}),
+                ...(sanitizeRecoveryReadiness(result.readiness) ? { readiness: sanitizeRecoveryReadiness(result.readiness) } : {}),
+            }
+            : {
+                ok: result.ok, agent_id: result.agentId,
+                reset_committed: result.resetCommitted, generation_changed: result.generationChanged,
+                session_changed: result.sessionChanged, turns: result.turns, runtime_ready: result.runtimeReady,
+                channel_connected: result.channelConnected, reconnecting: result.reconnecting,
+                pending_count: result.pendingCount, ready_for_fresh_scenario: result.readyForFreshScenario,
+                inbound_observed: result.inboundObserved, ...(result.code ? { code: result.code } : {}),
+                ...(result.error ? { error: result.error } : {}), ...(result.readiness ? { readiness: result.readiness } : {}),
+            };
         io.stdout(`${JSON.stringify(output, null, 2)}\n`);
         return result.ok ? 0 : 1;
     }
@@ -72,7 +105,9 @@ export async function runSessionCli(args, env = process.env, dependencies = {})
         const message = error instanceof Error ? error.message : String(error);
         const output = {
             ok: false, agent_id: agentId,
-            code: /timeout/i.test(message) ? "control_timeout" : "control_unavailable", error: message,
+            code: /timeout/i.test(message) ? "control_timeout" : "control_unavailable",
+            error: parsed.operation === "recover"
+                ? (/timeout/i.test(message) ? "session recovery control timed out" : "session recovery control unavailable") : message,
         };
         io.stdout(`${JSON.stringify(output, null, 2)}\n`);
         return 1;

package/dist/dashboard/dashboard-view-model.mjs

@@ -7,6 +7,7 @@ import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath } from "node:url";
 import { readJson, readProcessState } from "../platform/process-state.mjs";
+import { isRuntimeReadinessCurrent } from "../app/agent-readiness.mjs";
 import { isAllowedDashboardAvatarUrl } from "./dashboard-avatar.mjs";
 import { collectWorkspaceEntry as collectTypedWorkspaceEntry } from "./dashboard-workspace.mjs";
 import { buildFingerprint, packageVersion } from "../platform/build-info.mjs";
@@ -429,7 +430,7 @@ export function projectStatusTimeline(status) {
     ].sort((x, y) => new Date(String(y.at)).getTime() - new Date(String(x.at)).getTime()).slice(0, 30);
     return { activityLog, deliverLog, recentErrors, lastActivity, lastDeliver, feed };
 }
-async function collectAgentStatus(a, configDir, piModelResolver) {
+async function collectAgentStatus(a, configDir, daemonStartedAt, piModelResolver) {
     const dir = a.stateDir;
     const botIdentity = readJson(path.join(dir, "bot-identity.json"), null);
     const status = readJson(path.join(dir, "status.json"), {});
@@ -476,6 +477,14 @@ async function collectAgentStatus(a, configDir, piModelResolver) {
     }
     // 本 agent 专属时间线：三路历史合并按时间倒序，不是全局一条汇总——每个 agent 只看自己的故事。
     const { recentErrors, lastActivity, lastDeliver, feed } = projectStatusTimeline(status);
+    const statusReadiness = status.runtimeReadiness;
+    const sessionStartedAt = finiteTime(status.session?.startedAt);
+    const daemonEpoch = finiteTime(daemonStartedAt);
+    const sessionCurrent = sessionStartedAt !== null && daemonEpoch !== null && sessionStartedAt >= daemonEpoch;
+    const runtimeReadiness = sessionCurrent && isRuntimeReadinessCurrent(statusReadiness, daemonStartedAt)
+        || statusReadiness?.state !== "ready"
+        ? statusReadiness || null
+        : { ...statusReadiness, state: "unavailable", reason: "Runtime readiness evidence is stale for the current daemon epoch." };
     // 提醒：不只给数量，给完整列表——待触发按最近到期优先排前面，已触发/已取消按最近的排在后面。
     const pendingReminders = reminders.filter((r) => r.status === "scheduled" || r.status === "pending")
         .sort((x, y) => new Date(String(x.fireAt)).getTime() - new Date(String(y.fireAt)).getTime());
@@ -492,7 +501,7 @@ async function collectAgentStatus(a, configDir, piModelResolver) {
         runtime: a.runtime,
         model: status.session?.runtime === a.runtime && status.session?.model ? String(status.session.model) : a.model,
         effort: status.session?.runtime === a.runtime && status.session?.reasoningEffort ? String(status.session.reasoningEffort) : a.effort || null,
-        runtimeReadiness: status.runtimeReadiness || null,
+        runtimeReadiness,
         credentialReady: fs.existsSync(path.join(configDir, "bots", `${a.feishuProfile}.json`)),
         bot: botIdentity ? {
             name: botIdentity.name,
@@ -542,7 +551,7 @@ export async function collectStatus(options = {}) {
         uptimeSec: daemonStatus?.startedAt ? ageSec(daemonStatus.startedAt) : null,
         agents: Array.isArray(daemonStatus?.agents) ? daemonStatus.agents.filter((id) => typeof id === "string") : [],
     };
-    const statuses = (await Promise.all(agents.map((a) => collectAgentStatus(a, configDir, options.piModelResolver)))).map((agent) => {
+    const statuses = (await Promise.all(agents.map((a) => collectAgentStatus(a, configDir, daemon.startedAt, options.piModelResolver)))).map((agent) => {
         return { ...agent, ...projectAgentHealth(agent, daemon) };
     });
     return {