larkin 0.3.3 → 0.4.2

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/feishu/document-comment.cjs

@@ -11,6 +11,7 @@ exports.resolveDocumentCommentContext = resolveDocumentCommentContext;
 exports.projectDocumentCommentEnvelope = projectDocumentCommentEnvelope;
 const node_crypto_1 = require("node:crypto");
 exports.DOCUMENT_COMMENT_EVENT = "drive.notice.comment_add_v1";
+const DOCUMENT_COMMENT_TARGET_PATTERN = /^document-comment:(doc|docx|sheet|file):([A-Za-z0-9_-]+):([A-Za-z0-9_-]+):(in-thread|top-level)$/;
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -39,7 +40,7 @@ function documentCommentTarget(target, commentId, topLevel = false) {
     return `document-comment:${target.fileType}:${target.fileToken}:${commentId}:${topLevel ? "top-level" : "in-thread"}`;
 }
 function parseDocumentCommentTarget(value) {
-    const match = /^document-comment:(doc|docx|sheet|file):([A-Za-z0-9_-]+):([A-Za-z0-9_-]+):(in-thread|top-level)$/.exec(value);
+    const match = DOCUMENT_COMMENT_TARGET_PATTERN.exec(value);
     return match ? {
         fileType: match[1], fileToken: match[2], commentId: match[3], topLevel: match[4] === "top-level",
     } : null;

package/dist/feishu/document-comment.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 export const DOCUMENT_COMMENT_EVENT = "drive.notice.comment_add_v1";
+const DOCUMENT_COMMENT_TARGET_PATTERN = /^document-comment:(doc|docx|sheet|file):([A-Za-z0-9_-]+):([A-Za-z0-9_-]+):(in-thread|top-level)$/;
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -28,7 +29,7 @@ export function documentCommentTarget(target, commentId, topLevel = false) {
     return `document-comment:${target.fileType}:${target.fileToken}:${commentId}:${topLevel ? "top-level" : "in-thread"}`;
 }
 export function parseDocumentCommentTarget(value) {
-    const match = /^document-comment:(doc|docx|sheet|file):([A-Za-z0-9_-]+):([A-Za-z0-9_-]+):(in-thread|top-level)$/.exec(value);
+    const match = DOCUMENT_COMMENT_TARGET_PATTERN.exec(value);
     return match ? {
         fileType: match[1], fileToken: match[2], commentId: match[3], topLevel: match[4] === "top-level",
     } : null;

package/dist/feishu/host-business-state.cjs

@@ -10,6 +10,7 @@ exports.shouldPreventiveReconnect = shouldPreventiveReconnect;
 exports.countWakeEnvelopes = countWakeEnvelopes;
 exports.projectActivityStatus = projectActivityStatus;
 exports.projectSessionStatus = projectSessionStatus;
+const inbox_projection_js_1 = require("../agent/inbox-projection.cjs");
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const message_policy_js_1 = require("./message-policy.cjs");
 function asRecord(value) {
@@ -337,7 +338,8 @@ class HostEnvelopeProjector {
                         : `本条存量提醒缺少可用的飞书 message_id/chat_id，无法安全推断原会话；请先用 ${this.larkCommand("im +chat-search")} 确认目标，禁止猜测发送`,
             `这是你之前用 ${this.agentCommand("reminder schedule")} 设置的提醒，请按标题执行相应动作。管理: ${this.agentCommand("reminder list")} / ${this.agentCommand("reminder snooze")} / ${this.agentCommand("reminder cancel")}`,
         ].filter((line) => Boolean(line));
-        return {
+        const envelope = {
+            kind: "reminder",
             message_id: `rem_${reminder.reminderId.slice(0, 16)}_${seq}`,
             seq,
             sender_name: "定时提醒",
@@ -349,10 +351,12 @@ class HostEnvelopeProjector {
             thread_id: null,
             wake: true,
         };
+        return { ...envelope, target: inbox_projection_js_1.RUNTIME_REMINDER_TARGET };
     }
     createRedeliveryEnvelope(agentId, wakeCount) {
         const seq = this.nextSequence(agentId);
-        return {
+        const envelope = {
+            kind: "redelivery",
             message_id: `redeliver_${this.randomHex(6)}`,
             seq,
             sender_name: "系统",
@@ -363,6 +367,7 @@ class HostEnvelopeProjector {
             timestamp: this.now().toISOString(),
             thread_id: null,
         };
+        return { ...envelope, target: inbox_projection_js_1.RUNTIME_REDELIVERY_TARGET };
     }
 }
 exports.HostEnvelopeProjector = HostEnvelopeProjector;

package/dist/feishu/host-business-state.mjs

@@ -1,3 +1,4 @@
+import { RUNTIME_REDELIVERY_TARGET, RUNTIME_REMINDER_TARGET } from "../agent/inbox-projection.mjs";
 import crypto from "node:crypto";
 import { createMessageEnvelope, targetAliases, targetFor, } from "./message-policy.mjs";
 function asRecord(value) {
@@ -323,7 +324,8 @@ export class HostEnvelopeProjector {
                         : `本条存量提醒缺少可用的飞书 message_id/chat_id，无法安全推断原会话；请先用 ${this.larkCommand("im +chat-search")} 确认目标，禁止猜测发送`,
             `这是你之前用 ${this.agentCommand("reminder schedule")} 设置的提醒，请按标题执行相应动作。管理: ${this.agentCommand("reminder list")} / ${this.agentCommand("reminder snooze")} / ${this.agentCommand("reminder cancel")}`,
         ].filter((line) => Boolean(line));
-        return {
+        const envelope = {
+            kind: "reminder",
             message_id: `rem_${reminder.reminderId.slice(0, 16)}_${seq}`,
             seq,
             sender_name: "定时提醒",
@@ -335,10 +337,12 @@ export class HostEnvelopeProjector {
             thread_id: null,
             wake: true,
         };
+        return { ...envelope, target: RUNTIME_REMINDER_TARGET };
     }
     createRedeliveryEnvelope(agentId, wakeCount) {
         const seq = this.nextSequence(agentId);
-        return {
+        const envelope = {
+            kind: "redelivery",
             message_id: `redeliver_${this.randomHex(6)}`,
             seq,
             sender_name: "系统",
@@ -349,6 +353,7 @@ export class HostEnvelopeProjector {
             timestamp: this.now().toISOString(),
             thread_id: null,
         };
+        return { ...envelope, target: RUNTIME_REDELIVERY_TARGET };
     }
 }
 export function countWakeEnvelopes(lines) {

package/dist/feishu/host-shell.cjs

@@ -200,6 +200,16 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
         return store;
     };
     const hostState = new host_business_state_js_1.HostStateProjection(stateStore, log);
+    const recordInboundDeliveryFailure = (agent, code) => {
+        const at = new Date().toISOString();
+        const reason = "Inbound Runtime delivery failed non-retryably; durable Inbox/ledger state is retained for recovery.";
+        const nextAction = "Inspect the delivery/status error, correct the Runtime or canonical Inbox state, then restart to replay safely.";
+        hostState.updateStatus(agent, {
+            inboundDeliveryHealth: { state: "error", code, at, reason, nextAction },
+            runtimeReadiness: { runtime: agent.runtime, state: "incompatible", reason, nextAction },
+        });
+        hostState.recordStatusError(agent, `${reason} ${nextAction} code=${code}`);
+    };
     const agentStates = new Map();
     const saveAgentState = (record) => {
         try {
@@ -335,6 +345,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
             return;
         }
         const telemetryMessageId = String(event.message_id || event.event_id || eventKey);
+        let canonicalInboxDurable = false;
         if (wake)
             telemetry?.beginMessage(agent.agentId, telemetryMessageId);
         if (event.event_id)
@@ -345,58 +356,76 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                     senderIdentity.ensureChatNames(agent, event.chat_id, 3_000),
                     event._sender_is_bot ? Promise.resolve(null) : senderIdentity.ensureSenderSignature(agent, event.sender_id, 3_000),
                 ]);
-                const envelope = envelopeProjector.projectInbound(agent, event, { anchorReply: wake, names, signature });
-                envelope.target = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)({ ...envelope, chat_id: event.chat_id, thread_id: event.thread_id });
+                const projected = envelopeProjector.projectInbound(agent, event, { anchorReply: wake, names, signature });
+                projected.target = (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)({ ...projected, chat_id: event.chat_id, thread_id: event.thread_id });
                 if (wake)
-                    envelope.wake = true;
-                const inboxEnvelope = (0, inbox_projection_js_1.projectInboxEnvelope)(envelope, {
+                    projected.wake = true;
+                const candidate = (0, inbox_projection_js_1.projectInboxEnvelope)(projected, {
                     chat_id: event.chat_id,
                     thread_id: event.thread_id,
                     ...(event.create_time !== undefined ? { create_time: String(event.create_time) } : {}),
                     sender_id: event.sender_id,
-                    content: String(envelope.content ?? event.content ?? ""),
+                    content: String(projected.content ?? event.content ?? ""),
                 });
+                let append;
                 try {
-                    stateStore(agent).appendNdjson("inbox", inboxEnvelope);
+                    append = stateStore(agent).appendCanonicalInboxOnce(candidate);
                 }
                 catch (error) {
                     throw new Error(`inbox 写失败: ${errorMessage(error)}`);
                 }
-                // An event becomes permanently seen only after its canonical Inbox append
-                // is durable. Failures remain eligible for same-process redelivery.
+                canonicalInboxDurable = true;
+                // An event becomes permanently transport-seen only after the canonical
+                // append/dedupe decision is durable. Agent model-seen state is untouched.
                 if (event.event_id)
                     seenEventIds.add(eventKey);
-                hostState.appendConversation(agent, {
-                    direction: "in", from: envelope.sender_name, senderType: envelope.sender_type,
-                    target: (0, message_policy_js_1.targetFor)(event).target, wake, text: event.content, messageId: envelope.message_id,
-                    at: envelope.timestamp || new Date().toISOString(),
-                });
-                return envelope;
+                if (append.status === "duplicate_consumed")
+                    return null;
+                const inboxEnvelope = append.envelope;
+                if (append.status === "appended")
+                    hostState.appendConversation(agent, {
+                        direction: "in", from: inboxEnvelope.sender_name, senderType: inboxEnvelope.sender_type,
+                        target: String(inboxEnvelope.target || (0, message_policy_js_1.targetFor)(event).target), wake, text: event.content, messageId: inboxEnvelope.message_id,
+                        at: inboxEnvelope.timestamp || new Date().toISOString(),
+                    });
+                return inboxEnvelope;
             };
-            const envelope = wake && telemetry
+            const inboxEnvelope = wake && telemetry
                 ? await telemetry.phase(telemetryMessageId, "feishu.receive", api_1.SpanKind.CONSUMER, receive)
                 : await receive();
-            if (!wake)
+            if (!wake || !inboxEnvelope)
                 return;
-            const receipt = await runtimeHost.deliver(agent.agentId, envelope);
-            if (receipt.status === "accepted" || receipt.status === "duplicate" || receipt.status === "deferred") {
+            const receipt = await runtimeHost.deliver(agent.agentId, inboxEnvelope);
+            if (receipt.status === "error") {
+                recordInboundDeliveryFailure(agent, "non_retryable_receipt");
                 hostState.appendStatusLog(agent, "deliverLog", {
-                    from: envelope.sender_name,
-                    target: (0, message_policy_js_1.targetFor)(event).target,
-                    excerpt: (0, host_business_state_js_1.safeConversationExcerpt)(event.content, 180),
-                    at: new Date().toISOString(),
-                }, 30);
-                if (envelope.sender_type === "human" || envelope.sender_type === "agent")
-                    processingEyes.add(agent, String(envelope.message_id || ""));
-                if (receipt.status === "deferred")
-                    log(`Runtime 暂缓投递，消息保留在 inbox seq=${envelope.seq}: ${receipt.reason}`);
+                    at: new Date().toISOString(), status: "error",
+                    reason: "non-retryable Runtime delivery error; durable recovery state retained",
+                }, 80);
+                return;
             }
+            hostState.appendStatusLog(agent, "deliverLog", {
+                from: inboxEnvelope.sender_name,
+                target: String(inboxEnvelope.target || (0, message_policy_js_1.targetFor)(event).target),
+                excerpt: (0, host_business_state_js_1.safeConversationExcerpt)(event.content, 180),
+                at: new Date().toISOString(),
+            }, 30);
+            if (inboxEnvelope.sender_type === "human" || inboxEnvelope.sender_type === "agent")
+                processingEyes.add(agent, String(inboxEnvelope.message_id || ""));
+            if (receipt.status === "deferred")
+                log(`Runtime 暂缓投递，消息保留在 inbox seq=${inboxEnvelope.seq}: ${receipt.reason}`);
         }
         catch (error) {
             if (wake)
                 telemetry?.delivery(agent.agentId, telemetryMessageId, "error");
-            log(`onFeishuMessage 异常 agent=${agent.name}: ${error instanceof Error ? error.stack || error.message : String(error)}`);
-            hostState.recordStatusError(agent, `onFeishuMessage: ${errorMessage(error)}`);
+            if (canonicalInboxDurable) {
+                log(`onFeishuMessage Runtime delivery failed agent=${agent.name}; canonical Inbox retained`);
+                recordInboundDeliveryFailure(agent, "runtime_delivery_exception");
+            }
+            else {
+                log(`onFeishuMessage 异常 agent=${agent.name}: ${error instanceof Error ? error.stack || error.message : String(error)}`);
+                hostState.recordStatusError(agent, `onFeishuMessage: ${errorMessage(error)}`);
+            }
         }
         finally {
             if (event.event_id)
@@ -1241,16 +1270,24 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
             return;
         }
         if (message.type === "delivery") {
+            if (message.status === "error")
+                recordInboundDeliveryFailure(agent, "runtime_delivery_event");
             hostState.appendStatusLog(agent, "deliverLog", {
                 at: new Date().toISOString(), deliveryId: message.deliveryId, messageId: message.messageId,
-                status: message.status, ...(message.reason ? { reason: (0, host_business_state_js_1.safeConversationExcerpt)(message.reason, 120) } : {}),
+                status: message.status,
+                ...(message.status === "error"
+                    ? { reason: "non-retryable Runtime delivery error; durable recovery state retained" }
+                    : (message.reason ? { reason: (0, host_business_state_js_1.safeConversationExcerpt)(message.reason, 120) } : {})),
             }, 80);
             return;
         }
         if (message.type === "session") {
             const record = agentStates.get(agent.agentId);
             if (record && record.state.sessions[message.runtime] !== message.sessionId) {
-                record.state.sessions[message.runtime] = message.sessionId;
+                if (message.sessionId)
+                    record.state.sessions[message.runtime] = message.sessionId;
+                else
+                    delete record.state.sessions[message.runtime];
                 saveAgentState(record);
                 log(`持久化 agent=${agent.name} runtime=${message.runtime} sessionId=${message.sessionId}`);
             }
@@ -1266,7 +1303,8 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                 hostState.recordStatusError(agent, `auth: ${readiness.reason}; ${readiness.nextAction}`);
             }
             else {
-                hostState.recordStatusError(agent, `${message.event.errorCategory || "provider"}: ${message.event.message}${message.event.nextAction ? `; ${message.event.nextAction}` : ""}`);
+                const category = message.event.errorCategory || "provider";
+                hostState.recordStatusError(agent, `${category}: Runtime input failed ${message.event.retryable ? "retryably" : "non-retryably"}; inspect delivery health and Runtime/provider configuration`);
             }
         }
     };
@@ -1397,6 +1435,74 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                     : unavailable ? "reset committed but Runtime/channel readiness is unavailable"
                         : "reset committed but readiness did not converge before timeout" };
         },
+        async recoverSession(agentId, reason, waitReadyMs = 30_000) {
+            const agent = agents.find((candidate) => candidate.agentId === agentId);
+            if (!agent)
+                throw Object.assign(new Error(`未知 Agent: ${agentId}`), { code: "unknown_agent" });
+            if (reason !== "context-overflow")
+                throw Object.assign(new Error("unsupported recovery reason"), { code: "recovery_refused" });
+            if (!runtimeHost.recoverSession)
+                throw Object.assign(new Error("Runtime session recovery 尚未就绪"), { code: "recovery_unavailable" });
+            const connectionState = (status = hostState.readStatus(agent)) => {
+                const connectedAt = Date.parse(String(status.connectedAt || ""));
+                const channelConnected = Number.isFinite(connectedAt) && connectedAt >= Date.parse(daemonStartedAt) - 1000;
+                return { channelConnected, reconnecting: (0, agent_readiness_js_1.isChannelReconnecting)(status) };
+            };
+            const readinessProjection = () => {
+                const status = hostState.readStatus(agent);
+                const turns = status.session && typeof status.session === "object"
+                    ? Math.max(0, Number(status.session.turns) || 0) : 0;
+                const runtimeReady = Boolean(status.runtimeReadiness && typeof status.runtimeReadiness === "object"
+                    && status.runtimeReadiness.state === "ready");
+                const pendingCount = stateStore(agent).withInboxTransaction(() => stateStore(agent).readNdjson("inbox").length);
+                return { turns, runtimeReady, ...connectionState(status), pendingCount };
+            };
+            const initialProjection = readinessProjection();
+            if (!initialProjection.channelConnected)
+                throw Object.assign(new Error(`Agent ${agentId} channel is not connected`), { code: "channel_unavailable", ...initialProjection });
+            if (initialProjection.reconnecting)
+                throw Object.assign(new Error(`Agent ${agentId} channel is reconnecting`), { code: "channel_reconnecting", ...initialProjection });
+            let recovery;
+            try {
+                recovery = await runtimeHost.recoverSession(agentId, reason);
+            }
+            catch (error) {
+                throw Object.assign(error instanceof Error ? error : new Error(String(error)), readinessProjection());
+            }
+            const record = agentStates.get(agentId);
+            try {
+                if (record) {
+                    if (recovery.sessionId)
+                        record.state.sessions[agent.runtime] = recovery.sessionId;
+                    else
+                        delete record.state.sessions[agent.runtime];
+                    record.store.writeJson("agentState", record.state);
+                }
+            }
+            catch (error) {
+                const projection = readinessProjection();
+                return { recoveryCommitted: true, generationChanged: recovery.generationChanged, sessionChanged: recovery.sessionChanged,
+                    ...projection, rearmedCount: recovery.rearmedCount, replayStatus: "pending", remainingPendingCount: projection.pendingCount,
+                    readyForFreshScenario: false, inboundObserved: false, code: "state_persistence_failed",
+                    error: "recovery committed but Agent session state persistence failed" };
+            }
+            const deadline = Date.now() + Math.max(0, waitReadyMs);
+            let projection = readinessProjection();
+            do {
+                projection = readinessProjection();
+                if (projection.turns === 0 && projection.runtimeReady && projection.channelConnected && !projection.reconnecting)
+                    break;
+                if (Date.now() >= deadline)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(1, deadline - Date.now()))));
+            } while (true);
+            const replayStatus = projection.pendingCount === 0 ? "consumed" : "pending";
+            const ready = projection.turns === 0 && projection.runtimeReady && projection.channelConnected && !projection.reconnecting;
+            return { recoveryCommitted: true, generationChanged: recovery.generationChanged, sessionChanged: recovery.sessionChanged,
+                ...projection, rearmedCount: recovery.rearmedCount, replayStatus, remainingPendingCount: projection.pendingCount,
+                readyForFreshScenario: ready, inboundObserved: false,
+                ...(!ready ? { code: "recovery_timeout", error: "recovery committed but Runtime/channel readiness did not converge before timeout" } : {}) };
+        },
         async start() {
             try {
                 node_fs_1.default.mkdirSync(larkinHome, { recursive: true });