larkin 0.3.3 → 0.4.2

package/dist/runtime/runtime-host.mjs

@@ -2,10 +2,13 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { agentCliPromptCapabilities } from "../agent/agent-cli-capabilities.mjs";
+import { isCanonicalInboxTarget, targetKeyOfInboxEnvelope } from "../agent/inbox-projection.mjs";
 import { SpanKind } from "@opentelemetry/api";
+import { buildStrictProviderErrorInput, classifyStrictProviderError } from "./provider-error-classifier.mjs";
 import { classifyRuntimePrerequisite, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
 import { resolveOfficialLarkCli } from "../app/official-lark-cli.mjs";
 import { assertAgentWorkspaceBound, managedLarkCliEnv } from "../app/agent-lark-cli-workspace.mjs";
+import { PiCompactionBreaker, PiCompactionRecoveryMachine } from "./pi-compaction-recovery.mjs";
 export class RuntimeSessionResetError extends Error {
     code;
     pendingCount;
@@ -16,9 +19,33 @@ export class RuntimeSessionResetError extends Error {
         this.name = "RuntimeSessionResetError";
     }
 }
+export class RuntimeSessionRecoveryError extends Error {
+    code;
+    pendingCount;
+    constructor(code, message, pendingCount = 0) {
+        super(message);
+        this.code = code;
+        this.pendingCount = pendingCount;
+        this.name = "RuntimeSessionRecoveryError";
+    }
+}
 const MAX_DELIVERIES = 2048;
 const now = () => new Date().toISOString();
 const isActiveDelivery = (status) => ["pending", "submitting", "accepted"].includes(status);
+const REPLAY_FAILURE_CODES = new Set([
+    "canonical_inbox_row_missing", "canonical_inbox_malformed", "duplicate_message_id",
+    "inbox_state_conflict", "delivery_target_conflict", "structured_target_invalid",
+    "structured_target_missing", "wake_reason_conflict",
+]);
+function replayFailureReason(code) {
+    return `Runtime delivery quarantined (${code}): no safe canonical Inbox target is available; the Inbox/ledger remain durable for operator recovery`;
+}
+function replayFailureCodeOf(record) {
+    if (record.status !== "error" || typeof record.reason !== "string")
+        return null;
+    const code = /^Runtime delivery quarantined \(([^)]+)\):/.exec(record.reason)?.[1];
+    return code && REPLAY_FAILURE_CODES.has(code) ? code : null;
+}
 function deliveryFile(agent) {
     return agent.config.stateDir ? path.join(agent.config.stateDir, "runtime-deliveries.json") : null;
 }
@@ -91,6 +118,9 @@ export function createRuntimeHost(options) {
     const listeners = new Set();
     const log = options.log ?? (() => { });
     const telemetry = options.telemetry;
+    const compactTimeoutMs = options.compactTimeoutMs ?? 120_000;
+    if (!Number.isFinite(compactTimeoutMs) || compactTimeoutMs <= 0)
+        throw new Error("compactTimeoutMs must be positive");
     const retryPolicy = {
         baseDelayMs: options.retryPolicy?.baseDelayMs ?? 250,
         maxDelayMs: options.retryPolicy?.maxDelayMs ?? 10_000,
@@ -151,6 +181,82 @@ export function createRuntimeHost(options) {
         emitConsumed(agent, persist(agent));
         return agent.records.get(record.deliveryId) ?? record;
     };
+    const scrubQuarantinedInput = (record, reason) => {
+        const staleInput = record.input && typeof record.input === "object" ? record.input : null;
+        record.input = {
+            inputId: typeof staleInput?.inputId === "string" && staleInput.inputId ? staleInput.inputId : record.deliveryId,
+            deliveryId: record.deliveryId,
+            kind: "wake",
+            text: reason,
+            attempt: Number.isSafeInteger(staleInput?.attempt) && Number(staleInput?.attempt) >= 0 ? Number(staleInput.attempt) : 0,
+        };
+    };
+    /** Rebuild every submitted notice from canonical structured state, never persisted text. */
+    const prepareRecordInput = (agent, record, busy) => {
+        if (record.target !== undefined && (typeof record.target !== "string" || !isCanonicalInboxTarget(record.target))) {
+            return { status: "error", code: "structured_target_invalid", reason: replayFailureReason("structured_target_invalid") };
+        }
+        if (record.wakeReason !== undefined && typeof record.wakeReason !== "string") {
+            return { status: "error", code: "wake_reason_conflict", reason: replayFailureReason("wake_reason_conflict") };
+        }
+        let target = typeof record.target === "string" ? record.target : null;
+        let wakeReason = typeof record.wakeReason === "string" ? record.wakeReason : undefined;
+        if (agent.stateStore?.resolveInboxDeliverySource) {
+            let source;
+            try {
+                source = agent.stateStore.resolveInboxDeliverySource(record.messageId);
+            }
+            catch {
+                source = { status: "invalid", code: "canonical_inbox_malformed" };
+            }
+            if (source.status === "consumed")
+                return { status: "consumed" };
+            if (source.status === "missing" || source.status === "invalid") {
+                return { status: "error", code: source.code, reason: replayFailureReason(source.code) };
+            }
+            if (target && target !== source.target) {
+                return { status: "error", code: "delivery_target_conflict", reason: replayFailureReason("delivery_target_conflict") };
+            }
+            const canonicalWakeReason = typeof source.envelope.wake_reason === "string" ? source.envelope.wake_reason : undefined;
+            if (record.wakeReason !== undefined && wakeReason !== canonicalWakeReason) {
+                return { status: "error", code: "wake_reason_conflict", reason: replayFailureReason("wake_reason_conflict") };
+            }
+            target = source.target;
+            wakeReason = canonicalWakeReason;
+        }
+        if (!target)
+            return { status: "error", code: "structured_target_missing", reason: replayFailureReason("structured_target_missing") };
+        const staleInput = record.input && typeof record.input === "object" ? record.input : null;
+        const attempt = Number.isSafeInteger(staleInput?.attempt) && Number(staleInput?.attempt) >= 0 ? Number(staleInput.attempt) : 0;
+        const inputId = typeof staleInput?.inputId === "string" && staleInput.inputId ? staleInput.inputId : record.deliveryId;
+        record.target = target;
+        if (wakeReason)
+            record.wakeReason = wakeReason;
+        else
+            delete record.wakeReason;
+        record.input = {
+            inputId,
+            deliveryId: record.deliveryId,
+            kind: busy ? "inbox_update" : "wake",
+            text: options.promptBuilder.buildInboxNotice({ busy, count: 1, deliveryId: record.deliveryId, target,
+                ...(wakeReason ? { wakeReason } : {}) }),
+            attempt,
+        };
+        return { status: "ready", target };
+    };
+    const quarantineRecord = (agent, record, code) => {
+        const reason = replayFailureReason(code);
+        scrubQuarantinedInput(record, reason);
+        record.reason = reason;
+        record.retryable = false;
+        delete record.errorCategory;
+        const finalRecord = setRecord(agent, record, "error");
+        if (finalRecord.status === "consumed")
+            return { status: "accepted", deliveryId: record.deliveryId };
+        emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
+            messageId: record.messageId, status: "error", reason });
+        return { status: "error", deliveryId: record.deliveryId, reason, retryable: false };
+    };
     const reconcileExternalConsumption = (agent) => {
         if (agent.stateStore) {
             agent.stateStore.withInboxTransaction(() => reconcileFile(agent, agent.stateStore.readJson("runtimeDeliveries", { version: 1, records: [] })));
@@ -284,12 +390,14 @@ export function createRuntimeHost(options) {
         if (result.status === "accepted") {
             delete record.reason;
             delete record.retryable;
+            delete record.errorCategory;
             const finalRecord = setRecord(agent, record, "accepted");
             if (finalRecord.status !== "consumed")
                 emit({ type: "delivery", agentId: agent.config.agentId,
                     deliveryId: record.deliveryId, messageId: record.messageId, status: "accepted" });
             return { status: "accepted", deliveryId: record.deliveryId };
         }
+        delete record.errorCategory;
         const retryable = result.status === "deferred" || result.retryable;
         record.reason = result.reason;
         record.retryable = retryable;
@@ -307,6 +415,20 @@ export function createRuntimeHost(options) {
         if (!busy)
             agent.busy = true; // Reserve the turn before prompt() can yield.
         try {
+            const prepared = prepareRecordInput(agent, record, busy);
+            if (prepared.status === "consumed") {
+                if (!busy)
+                    agent.busy = false;
+                const consumedRecord = setRecord(agent, record, "consumed");
+                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: consumedRecord.deliveryId,
+                    messageId: consumedRecord.messageId, status: "consumed" });
+                return { status: "accepted", deliveryId: record.deliveryId };
+            }
+            if (prepared.status === "error") {
+                if (!busy)
+                    agent.busy = false;
+                return quarantineRecord(agent, record, prepared.code);
+            }
             const session = await ensureSession(agent);
             const submittingRecord = setRecord(agent, record, "submitting");
             if (submittingRecord.status === "consumed") {
@@ -330,6 +452,7 @@ export function createRuntimeHost(options) {
             const reason = error instanceof Error ? error.message : String(error);
             record.reason = reason;
             record.retryable = true;
+            delete record.errorCategory;
             setRecord(agent, record, "pending");
             emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId, messageId: record.messageId, status: "deferred", reason });
             return { status: "deferred", deliveryId: record.deliveryId, reason };
@@ -456,6 +579,106 @@ export function createRuntimeHost(options) {
         })();
         agent.configurationRecovery = recovery;
     };
+    let recoverContextOverflowInternal;
+    const beginPiManualCompaction = (agent, session, record, nativeWillRetry = false) => {
+        if (agent.adapter.id !== "pi" || !session.compact || !agent.compactionBreaker)
+            return;
+        const existing = agent.compactionMachines.get(record.input.inputId);
+        if (existing) {
+            existing.agentEnd({ exactOverflow: true, willRetry: nativeWillRetry });
+            return;
+        }
+        const key = `${record.deliveryId}:${record.input.inputId}`;
+        const prior = agent.compactionBreaker.get(key);
+        if (prior && prior.manualAttempt >= 1 && ["manual_sent", "manual_ambiguous", "manual_failed", "native_failed"].includes(prior.state)) {
+            agent.busy = false;
+            agent.turnInProgress = false;
+            void recoverContextOverflowInternal(agent.config.agentId, key, "validated Pi compaction breaker state after restart", key)
+                .catch((error) => log("Pi restart fallback failed", String(error)));
+            return;
+        }
+        const machine = new PiCompactionRecoveryMachine({
+            breaker: agent.compactionBreaker, key, messageId: record.messageId, deliveryId: record.deliveryId,
+            inputId: record.input.inputId, sessionGeneration: agent.generation,
+            onAction: (action) => {
+                if (action === "retry_input") {
+                    machine.retrySubmitted();
+                    record.status = "pending";
+                    record.retryable = true;
+                    record.reason = "Pi manual compaction succeeded; retrying the same delivery input";
+                    record.updatedAt = now();
+                    persist(agent);
+                    queueMicrotask(() => { if (!agent.stopped)
+                        void submit(agent, record, false); });
+                }
+                else if (action === "fresh_session_fallback") {
+                    agent.busy = false;
+                    agent.turnInProgress = false;
+                    if (record.status !== "error") {
+                        record.reason = machine.recordSnapshot.fallbackReason || "Pi compaction recovery fallback";
+                        record.retryable = false;
+                        record.errorCategory = "context_window";
+                        setRecord(agent, record, "error");
+                    }
+                    void recoverContextOverflowInternal(agent.config.agentId, key, machine.recordSnapshot.fallbackReason || "Pi compaction recovery fallback", key)
+                        .catch((error) => log("Pi context fallback failed", String(error)));
+                }
+            },
+        });
+        agent.compactionMachines.set(record.input.inputId, machine);
+        machine.agentEnd({ exactOverflow: true, willRetry: nativeWillRetry });
+        if (nativeWillRetry)
+            return;
+        machine.agentSettled();
+        const deadline = new Date(Date.now() + compactTimeoutMs).toISOString();
+        machine.manualCompactSent(deadline);
+        let compactSettled = false;
+        const compactTimer = setTimeout(() => {
+            if (compactSettled)
+                return;
+            compactSettled = true;
+            machine.compactTimeout();
+        }, compactTimeoutMs);
+        compactTimer.unref?.();
+        void session.compact().then(() => {
+            if (compactSettled)
+                return;
+            compactSettled = true;
+            clearTimeout(compactTimer);
+            machine.compactResponse({ success: true });
+        }).catch((error) => {
+            if (compactSettled)
+                return;
+            compactSettled = true;
+            clearTimeout(compactTimer);
+            const message = error instanceof Error ? error.message : String(error);
+            machine.compactResponse({ success: false, ambiguous: /process exited|process failed|session replaced|protocol/i.test(message) });
+        });
+    };
+    const recoverStalePiCompaction = async (agent) => {
+        const breaker = agent.compactionBreaker;
+        if (!breaker)
+            return;
+        const stale = breaker.listNonTerminal().find((candidate) => candidate.state !== "native_succeeded");
+        if (!stale) {
+            const succeeded = breaker.listNonTerminal().find((candidate) => candidate.state === "native_succeeded");
+            if (succeeded)
+                breaker.transition(succeeded.key, {}, "closed");
+            return;
+        }
+        const record = [...agent.records.values()].find((candidate) => candidate.deliveryId === stale.deliveryId
+            || candidate.input.inputId === stale.inputId);
+        if (!record)
+            return;
+        record.reason = stale.fallbackReason || "Pi compaction recovery resumed after restart";
+        record.retryable = false;
+        record.errorCategory = "context_window";
+        setRecord(agent, record, "error");
+        breaker.forceFallback(stale.key, record.reason);
+        agent.busy = false;
+        agent.turnInProgress = false;
+        await recoverContextOverflowInternal(agent.config.agentId, stale.key, record.reason, stale.key);
+    };
     const observe = (agent, session, event) => {
         if (agent.session !== session)
             return; // Ignore late output from a replaced child.
@@ -464,6 +687,34 @@ export function createRuntimeHost(options) {
         if (event.type !== "turn-end")
             telemetry?.runtimeEvent(agent.config.agentId, event);
         emit({ type: "runtime", agentId: agent.config.agentId, event });
+        if (event.type === "runtime-observation") {
+            if (event.phase === "compaction_start" && event.reason === "overflow" && event.inputId) {
+                const overflowRecord = [...agent.records.values()].find((candidate) => candidate.input.inputId === event.inputId);
+                if (overflowRecord && !agent.compactionMachines.has(event.inputId))
+                    beginPiManualCompaction(agent, session, overflowRecord, true);
+            }
+            const candidates = [...agent.compactionMachines.values()].filter((machine) => machine.recordSnapshot.sessionGeneration === agent.generation
+                && (!event.inputId || machine.recordSnapshot.inputId === event.inputId));
+            const machines = event.inputId ? candidates : candidates.length === 1 ? candidates : [];
+            for (const machine of machines) {
+                if (event.phase === "compaction_start" && event.reason === "overflow")
+                    machine.compactionStart({ reason: "overflow" });
+                if (event.phase === "compaction_end" && event.reason === "manual") {
+                    machine.compactionEnd({ reason: "manual", success: event.success === true, willRetry: event.willRetry === true });
+                }
+                if (event.phase === "compaction_end" && event.reason === "overflow") {
+                    machine.compactionEnd({ reason: "overflow", success: event.success === true, willRetry: event.willRetry === true });
+                }
+                if (event.phase === "settled")
+                    machine.agentSettled();
+            }
+            if (event.phase === "compaction_end" && event.reason === "overflow" && event.success !== true) {
+                for (const record of agent.records.values()) {
+                    if (isActiveDelivery(record.status))
+                        agent.piOverflowCompactionFailed.add(record.input.inputId);
+                }
+            }
+        }
         if (event.type === "session-init") {
             agent.config.sessionId = event.sessionId;
             emit({ type: "session", agentId: agent.config.agentId, runtime: agent.adapter.id, sessionId: event.sessionId, launchId: agent.launchId,
@@ -479,6 +730,13 @@ export function createRuntimeHost(options) {
             emit({ type: "activity", agentId: agent.config.agentId, activity: "working", activityKind: "working", detailKind: "turn_started" });
         }
         else if (event.type === "turn-end") {
+            for (const [inputId, machine] of agent.compactionMachines) {
+                if (machine.recordSnapshot.sessionGeneration !== agent.generation)
+                    continue;
+                machine.close();
+                if (["closed", "fallback_committed"].includes(machine.state))
+                    agent.compactionMachines.delete(inputId);
+            }
             const recoveredAuthentication = agent.authFailureActive && agent.turnInProgress
                 && agent.turnHadAuthenticatedOutput && !agent.turnHadFailure;
             agent.turnInProgress = false;
@@ -511,6 +769,29 @@ export function createRuntimeHost(options) {
             if (!record || record.status === "consumed" || record.status === "error")
                 return;
             agent.turnHadFailure = true;
+            if (agent.adapter.id === "pi" && event.errorCategory === "context_window" && event.willRetry === true && session.compact) {
+                beginPiManualCompaction(agent, session, record, true);
+                return;
+            }
+            if (agent.adapter.id === "pi" && event.errorCategory === "context_window" && event.willRetry !== true && session.compact) {
+                record.reason = event.message;
+                record.retryable = false;
+                record.errorCategory = "context_window";
+                setRecord(agent, record, "error");
+                if (agent.piOverflowCompactionFailed.has(record.input.inputId)) {
+                    agent.busy = false;
+                    agent.turnInProgress = false;
+                    void recoverContextOverflowInternal(agent.config.agentId, `${record.deliveryId}:${record.input.inputId}`, "native Pi overflow compaction failed", `${record.deliveryId}:${record.input.inputId}`)
+                        .catch((error) => log("Pi native compaction fallback failed", String(error)));
+                    return;
+                }
+                // Pi emits this terminal error only after agent_settled; release the
+                // normal turn reservation before the one authorized recovery action.
+                agent.busy = false;
+                agent.turnInProgress = false;
+                beginPiManualCompaction(agent, session, record);
+                return;
+            }
             if (event.willRetry) {
                 emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
                     messageId: record.messageId, status: "deferred", reason: event.message });
@@ -521,6 +802,13 @@ export function createRuntimeHost(options) {
                 agent.busy = false;
             record.reason = event.message;
             record.retryable = event.retryable;
+            const classifiedCategory = event.errorCategory ?? classifyStrictProviderError(buildStrictProviderErrorInput({
+                message: event.message, errorCategory: event.errorCategory, upstream: event.upstream,
+            }));
+            if (classifiedCategory)
+                record.errorCategory = classifiedCategory;
+            else
+                delete record.errorCategory;
             const finalRecord = setRecord(agent, record, event.retryable ? "pending" : "error");
             if (finalRecord.status !== "consumed")
                 emit({ type: "delivery", agentId: agent.config.agentId,
@@ -607,6 +895,129 @@ export function createRuntimeHost(options) {
         });
         return agent.starting;
     };
+    recoverContextOverflowInternal = async (agentId, deliveryKey, reason, breakerKey) => {
+        const agent = managed.get(agentId);
+        if (!agent || agent.stopped)
+            throw new RuntimeSessionRecoveryError("unknown_agent", `unknown runtime Agent: ${agentId}`);
+        if (agent.adapter.id !== "pi")
+            throw new RuntimeSessionRecoveryError("recovery_unavailable", "Pi context fallback is unavailable for this runtime");
+        const oldSession = agent.session;
+        if (!oldSession || agent.busy || agent.submitting || agent.starting) {
+            throw new RuntimeSessionRecoveryError("agent_busy", `Agent ${agentId} is not idle for Pi context fallback`);
+        }
+        const record = [...agent.records.values()].find((candidate) => candidate.deliveryId === deliveryKey || candidate.input.inputId === deliveryKey || `${candidate.deliveryId}:${candidate.input.inputId}` === deliveryKey);
+        if (!record)
+            throw new RuntimeSessionRecoveryError("recovery_refused", "Pi context fallback delivery identity is unavailable");
+        const probeEnv = runtimeEnv(agent.config, `${agent.launchId}:pi-context-fallback`);
+        await assertOfficialCliReady(agent.config, probeEnv);
+        const readiness = agent.adapter.probe ? await agent.adapter.probe({ agentId: agent.config.agentId,
+            workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir, env: probeEnv }) : { runtime: "pi", state: "ready" };
+        if (readiness.state !== "ready")
+            throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", "Pi context fallback readiness failed");
+        const standingPrompt = options.promptBuilder.build({
+            agentId: agent.config.agentId, name: agent.config.displayName || agent.config.name,
+            description: agent.config.description || "", runtime: agent.adapter.id, cli: agentCliPromptCapabilities("larkin"),
+        });
+        let fresh;
+        try {
+            fresh = await agent.adapter.createSession({ agentId: agent.config.agentId, model: agent.config.model,
+                reasoningEffort: agent.config.effort || null, workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
+                resumeSessionId: null, standingPrompt, env: probeEnv });
+        }
+        catch {
+            throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", "Pi fresh fallback session could not be staged");
+        }
+        if (agent.session !== oldSession || agent.busy || agent.submitting || agent.starting || agent.stopped) {
+            await fresh.close("Pi context fallback commit precondition changed").catch(() => { });
+            throw new RuntimeSessionRecoveryError("agent_busy", `Agent ${agentId} changed during Pi context fallback`);
+        }
+        let unsubscribeFresh = null;
+        try {
+            unsubscribeFresh = fresh.subscribe((next) => observe(agent, fresh, next));
+        }
+        catch {
+            await fresh.close("Pi context fallback subscription failed").catch(() => { });
+            throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", "Pi context fallback subscription failed");
+        }
+        const oldSessionId = oldSession.sessionId;
+        const oldGeneration = agent.generation;
+        const oldLaunchId = agent.launchId;
+        const oldConfigSessionId = agent.config.sessionId;
+        const oldReadiness = agent.readiness;
+        const oldDisabledReason = agent.disabledReason;
+        const oldRecord = { ...record, input: { ...record.input } };
+        let durableRollback = null;
+        let rearmedCount = 1;
+        let remainingPendingCount = 1;
+        const commitSwap = (messageIds, rollback) => {
+            if (agent.session !== oldSession || agent.busy || agent.submitting || agent.starting || agent.stopped) {
+                throw new RuntimeSessionRecoveryError("agent_busy", `Agent ${agentId} changed during Pi context fallback`);
+            }
+            durableRollback = rollback ?? null;
+            if (breakerKey && agent.compactionBreaker)
+                agent.compactionBreaker.forceFallbackInTransaction(breakerKey, reason);
+            agent.generation += 1;
+            agent.launchId = crypto.randomUUID();
+            agent.config.sessionId = null;
+            agent.session = fresh;
+            agent.readiness = readiness;
+            agent.disabledReason = null;
+            for (const candidate of agent.records.values()) {
+                if (!messageIds.includes(candidate.messageId))
+                    continue;
+                candidate.status = "pending";
+                candidate.retryable = true;
+                candidate.reason = "context-window recovery rearmed the retained Inbox delivery";
+                candidate.updatedAt = now();
+            }
+        };
+        try {
+            if (agent.stateStore?.rearmContextOverflow) {
+                const rearmed = agent.stateStore.rearmContextOverflow((messageIds, rollback) => commitSwap(messageIds, rollback), {
+                    messageId: record.messageId, deliveryId: record.deliveryId, inputId: record.input.inputId,
+                });
+                rearmedCount = rearmed.rearmedCount;
+                remainingPendingCount = rearmed.remainingPendingCount;
+            }
+            else {
+                commitSwap([record.messageId]);
+                persist(agent);
+            }
+        }
+        catch (error) {
+            try {
+                const rollback = durableRollback;
+                if (rollback)
+                    rollback();
+            }
+            catch { /* preserve primary error */ }
+            agent.generation = oldGeneration;
+            agent.launchId = oldLaunchId;
+            agent.config.sessionId = oldConfigSessionId;
+            agent.session = oldSession;
+            agent.readiness = oldReadiness;
+            agent.disabledReason = oldDisabledReason;
+            Object.assign(record, oldRecord);
+            try {
+                unsubscribeFresh?.();
+            }
+            catch { /* preserve primary failure */ }
+            await fresh.close("Pi context fallback rolled back").catch(() => { });
+            throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", error instanceof Error ? error.message : "Pi context fallback commit failed");
+        }
+        if (fresh.sessionId) {
+            agent.config.sessionId = fresh.sessionId;
+            emit({ type: "session", agentId, runtime: agent.adapter.id, sessionId: fresh.sessionId, launchId: agent.launchId,
+                ...(fresh.effectiveModel ? { model: fresh.effectiveModel } : {}),
+                ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}) });
+        }
+        emit({ type: "agent-status", agentId, status: "active", readiness });
+        await oldSession.close("Pi context fallback committed").catch((error) => log("previous Pi session close after fallback failed", String(error)));
+        void retryPending(agent);
+        return { generationChanged: true, sessionChanged: oldSessionId !== fresh.sessionId, turns: 0,
+            runtimeReady: true, pendingCount: remainingPendingCount, rearmedCount,
+            replayStatus: remainingPendingCount > 0 ? "pending" : "consumed", sessionId: fresh.sessionId };
+    };
     return {
         async probe(config) {
             const adapter = options.adapterFor(config.runtime);
@@ -781,6 +1192,180 @@ export function createRuntimeHost(options) {
             return { generationChanged: true, sessionChanged: oldSessionId !== fresh.sessionId, turns: 0,
                 runtimeReady: true, pendingCount: 0, sessionId: fresh.sessionId };
         },
+        async recoverSession(agentId, reason) {
+            if (reason !== "context-overflow")
+                throw new RuntimeSessionRecoveryError("recovery_refused", "unsupported recovery reason");
+            const agent = managed.get(agentId);
+            if (agent && agent.adapter.id !== "pi")
+                throw new RuntimeSessionRecoveryError("recovery_unavailable", "context-overflow recovery is available only for Pi Runtime");
+            if (!agent || agent.stopped)
+                throw new RuntimeSessionRecoveryError("unknown_agent", `unknown runtime Agent: ${agentId}`);
+            if (!agent.stateStore?.rearmContextOverflow) {
+                throw new RuntimeSessionRecoveryError("recovery_unavailable", "canonical Inbox recovery is unavailable");
+            }
+            if (agent.busy || agent.turnInProgress || agent.submitting || agent.starting) {
+                throw new RuntimeSessionRecoveryError("agent_busy", `Agent ${agentId} is not idle`);
+            }
+            const oldSession = agent.session;
+            if (!oldSession)
+                throw new RuntimeSessionRecoveryError("agent_busy", `Agent ${agentId} Runtime session is unavailable`);
+            const oldSessionId = oldSession.sessionId;
+            if (agent.stateStore.readNdjson) {
+                const pendingRows = agent.stateStore.withInboxTransaction(() => agent.stateStore.readNdjson("inbox"));
+                if (pendingRows.length === 0) {
+                    throw new RuntimeSessionRecoveryError("recovery_refused", "context-window recovery has no retained Inbox backlog");
+                }
+                const messageIds = new Set(pendingRows.flatMap((row) => {
+                    const messageId = row && typeof row === "object" && !Array.isArray(row)
+                        ? row.message_id : undefined;
+                    return typeof messageId === "string" && messageId ? [messageId] : [];
+                }));
+                const persisted = agent.stateStore.readJson("runtimeDeliveries", { version: 1, records: [] });
+                if (Array.isArray(persisted.records) && persisted.records.some((record) => messageIds.has(record.messageId) && record.status !== "error")) {
+                    throw new RuntimeSessionRecoveryError("recovery_refused", "context-window recovery is already staged or completed");
+                }
+            }
+            const probeEnv = runtimeEnv(agent.config, `${agent.launchId}:context-overflow-recovery`);
+            let readiness;
+            try {
+                await assertOfficialCliReady(agent.config, probeEnv);
+                readiness = agent.adapter.probe ? await agent.adapter.probe({ agentId: agent.config.agentId,
+                    workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
+                    env: { LARKIN_PI_COMMAND: process.env.LARKIN_PI_COMMAND, LARKIN_CODEX_COMMAND: process.env.LARKIN_CODEX_COMMAND,
+                        LARKIN_CLAUDE_COMMAND: process.env.LARKIN_CLAUDE_COMMAND, ...probeEnv } })
+                    : { runtime: agent.adapter.id, state: "ready" };
+            }
+            catch (error) {
+                if (error instanceof RuntimePrerequisiteError)
+                    throw error;
+                throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", "Runtime readiness probe failed");
+            }
+            if (readiness.state !== "ready")
+                throw new RuntimePrerequisiteError(readiness);
+            const standingPrompt = options.promptBuilder.build({
+                agentId: agent.config.agentId, name: agent.config.displayName || agent.config.name,
+                description: agent.config.description || "", runtime: agent.adapter.id,
+                cli: agentCliPromptCapabilities("larkin"),
+            });
+            let fresh;
+            try {
+                fresh = await agent.adapter.createSession({
+                    agentId: agent.config.agentId, model: agent.config.model, reasoningEffort: agent.config.effort || null,
+                    workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
+                    resumeSessionId: null, standingPrompt, env: probeEnv,
+                });
+            }
+            catch {
+                throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", "fresh Runtime session could not be staged");
+            }
+            let unsubscribeFresh = null;
+            try {
+                unsubscribeFresh = fresh.subscribe((event) => observe(agent, fresh, event));
+            }
+            catch {
+                await fresh.close("context-window recovery subscription failed").catch(() => { });
+                throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", "fresh Runtime session subscription failed");
+            }
+            const oldGeneration = agent.generation;
+            const oldLaunchId = agent.launchId;
+            const oldConfigSessionId = agent.config.sessionId;
+            const oldReadiness = agent.readiness;
+            const oldDisabledReason = agent.disabledReason;
+            const oldRecords = new Map([...agent.records.entries()].map(([id, record]) => [id, { ...record, input: { ...record.input } }]));
+            const cleanupFresh = async (reason) => {
+                const unsubscribe = unsubscribeFresh;
+                unsubscribeFresh = null;
+                try {
+                    unsubscribe?.();
+                }
+                catch { /* close still owns staged-session cleanup */ }
+                await fresh.close(reason).catch(() => { });
+            };
+            const restoreRuntime = () => {
+                agent.session = oldSession;
+                agent.generation = oldGeneration;
+                agent.launchId = oldLaunchId;
+                agent.config.sessionId = oldConfigSessionId;
+                agent.readiness = oldReadiness;
+                agent.disabledReason = oldDisabledReason;
+                agent.records = new Map(oldRecords);
+                agent.byMessage = new Map([...oldRecords.values()].map((record) => [record.messageId, record.deliveryId]));
+            };
+            let recoveryProjectionEmitted = false;
+            const compensateProjection = () => {
+                if (!recoveryProjectionEmitted)
+                    return;
+                try {
+                    emit({ type: "session", agentId, runtime: agent.adapter.id, sessionId: oldSessionId, launchId: oldLaunchId });
+                }
+                catch { /* preserve the original listener failure */ }
+                try {
+                    emit({ type: "agent-status", agentId, status: "active", ...(oldReadiness ? { readiness: oldReadiness } : {}) });
+                }
+                catch { /* preserve the original listener failure */ }
+            };
+            let durableRollback = null;
+            try {
+                const rearmed = agent.stateStore.rearmContextOverflow((messageIds, rollback) => {
+                    // This callback runs under the canonical Inbox lock. All potentially
+                    // racing checks above are synchronous from this process, while the
+                    // state-store method rechecks every row and delivery on disk.
+                    if (agent.session !== oldSession || agent.busy || agent.turnInProgress || agent.submitting || agent.starting || agent.stopped) {
+                        throw new RuntimeSessionRecoveryError("agent_busy", `Agent ${agentId} changed during recovery`);
+                    }
+                    durableRollback = rollback;
+                    agent.generation += 1;
+                    agent.launchId = crypto.randomUUID();
+                    agent.config.sessionId = null;
+                    agent.session = fresh;
+                    agent.readiness = readiness;
+                    agent.disabledReason = null;
+                    for (const record of agent.records.values()) {
+                        if (!messageIds.includes(record.messageId))
+                            continue;
+                        record.status = "pending";
+                        record.retryable = true;
+                        record.reason = "context-window recovery rearmed the retained Inbox delivery";
+                        record.updatedAt = now();
+                    }
+                });
+                recoveryProjectionEmitted = true;
+                if (fresh.sessionId) {
+                    agent.config.sessionId = fresh.sessionId;
+                    emit({ type: "session", agentId, runtime: agent.adapter.id, sessionId: fresh.sessionId, launchId: agent.launchId,
+                        ...(fresh.effectiveModel ? { model: fresh.effectiveModel } : {}),
+                        ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}) });
+                }
+                emit({ type: "agent-status", agentId, status: "active", readiness });
+                durableRollback = null;
+                await oldSession.close("context-window recovery committed")
+                    .catch((error) => log("previous runtime close after context-window recovery failed", String(error)));
+                void retryPending(agent);
+                return { generationChanged: true, sessionChanged: oldSessionId !== fresh.sessionId, turns: 0,
+                    runtimeReady: true, pendingCount: rearmed.remainingPendingCount, rearmedCount: rearmed.rearmedCount,
+                    replayStatus: rearmed.remainingPendingCount > 0 ? "pending" : "consumed", sessionId: fresh.sessionId };
+            }
+            catch (error) {
+                try {
+                    const rollback = durableRollback;
+                    if (rollback)
+                        rollback();
+                }
+                catch { /* preserve the original failure */ }
+                restoreRuntime();
+                compensateProjection();
+                await cleanupFresh("context-window recovery not committed");
+                if (error instanceof RuntimeSessionRecoveryError)
+                    throw error;
+                if (typeof error.code === "string") {
+                    throw new RuntimeSessionRecoveryError("recovery_refused", error instanceof Error ? error.message : "context-window recovery was refused");
+                }
+                throw new RuntimeSessionRecoveryError("recovery_staged_not_committed", "context-window recovery was not committed");
+            }
+        },
+        async recoverContextOverflow(agentId, deliveryKey, reason) {
+            return recoverContextOverflowInternal(agentId, deliveryKey, reason);
+        },
         async start(configs) {
             let activeCount = 0;
             let recoveringCount = 0;
@@ -799,7 +1384,14 @@ export function createRuntimeHost(options) {
                         const deliveryFile = stateStore.readJson("runtimeDeliveries", { version: 1, records: [] });
                         if (!stateStore.readNdjson)
                             return deliveryFile;
-                        const inboxIds = new Set(stateStore.readNdjson("inbox").flatMap((row) => typeof row?.message_id === "string" ? [row.message_id] : []));
+                        let inboxRows;
+                        try {
+                            inboxRows = stateStore.readNdjson("inbox");
+                        }
+                        catch {
+                            return deliveryFile;
+                        }
+                        const inboxIds = new Set(inboxRows.flatMap((row) => typeof row?.message_id === "string" ? [row.message_id] : []));
                         let changed = false;
                         const records = deliveryFile.records.map((record) => {
                             const synthetic = /^(?:redeliver_|rem_|interaction_)/.test(record.messageId);
@@ -820,15 +1412,44 @@ export function createRuntimeHost(options) {
                     byMessage: new Map(persisted.records.map((record) => [record.messageId, record.deliveryId])),
                     generation: 0, poller: null, retryTimer: null, recreateAttempts: 0,
                     stabilityTimer: null, recreateReason: null, stopped: false, disabledReason: null,
-                    configurationRecovery: null, stateStore, readiness: null,
+                    configurationRecovery: null, stateStore,
+                    compactionBreaker: config.runtime === "pi"
+                        ? new PiCompactionBreaker(config.stateDir ?? path.join(config.workspaceDir, ".larkin", "agents", config.agentId), {
+                            withLock: stateStore ? (operation) => stateStore.withInboxTransaction(operation) : undefined,
+                        }) : undefined,
+                    compactionMachines: new Map(), piOverflowCompactionFailed: new Set(), readiness: null,
                     turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false };
-                for (const record of agent.records.values())
-                    if (isActiveDelivery(record.status))
-                        record.status = "pending";
-                emitConsumed(agent, persist(agent));
+                const startupConsumed = [];
+                const startupQuarantined = [];
+                for (const record of agent.records.values()) {
+                    const existingQuarantine = replayFailureCodeOf(record);
+                    if (existingQuarantine) {
+                        startupQuarantined.push({ record, code: existingQuarantine });
+                        continue;
+                    }
+                    if (!isActiveDelivery(record.status))
+                        continue;
+                    record.status = "pending";
+                    const prepared = prepareRecordInput(agent, record, false);
+                    if (prepared.status === "consumed") {
+                        record.status = "consumed";
+                        record.updatedAt = now();
+                        startupConsumed.push(record);
+                    }
+                    else if (prepared.status === "error") {
+                        record.status = "error";
+                        record.updatedAt = now();
+                        scrubQuarantinedInput(record, prepared.reason);
+                        record.reason = prepared.reason;
+                        record.retryable = false;
+                        startupQuarantined.push({ record, code: prepared.code });
+                    }
+                }
                 managed.set(config.agentId, agent);
+                emitConsumed(agent, [...startupConsumed, ...persist(agent)]);
                 try {
                     await ensureSession(agent);
+                    await recoverStalePiCompaction(agent);
                     activeCount += 1;
                     await retryPending(agent);
                 }
@@ -844,6 +1465,13 @@ export function createRuntimeHost(options) {
                     emit({ type: "agent-status", agentId: config.agentId, status: "error", error: reason,
                         ...(error instanceof RuntimePrerequisiteError ? { readiness: error.readiness } : {}) });
                 }
+                const visibleQuarantines = startupQuarantined.filter(({ record }) => agent.records.get(record.deliveryId)?.status === "error");
+                for (const { record, code } of visibleQuarantines)
+                    emit({ type: "delivery", agentId: config.agentId,
+                        deliveryId: record.deliveryId, messageId: record.messageId, status: "error", reason: replayFailureReason(code) });
+                if (visibleQuarantines.length)
+                    emit({ type: "agent-status", agentId: config.agentId, status: "error",
+                        error: `${visibleQuarantines.length} Runtime delivery record(s) quarantined; canonical Inbox recovery is required` });
                 agent.poller = setInterval(() => reconcileExternalConsumption(agent), 250);
                 agent.poller.unref?.();
             });
@@ -859,12 +1487,33 @@ export function createRuntimeHost(options) {
                 telemetry?.delivery(agentId, messageId, "error");
                 throw new Error(`unknown runtime Agent: ${agentId}`);
             }
+            let target;
+            try {
+                target = targetKeyOfInboxEnvelope(envelope);
+            }
+            catch (error) {
+                const reason = `Inbox target derivation failed: ${error instanceof Error ? error.message : String(error)}`;
+                const deliveryId = `invalid-target-${crypto.createHash("sha256").update(`${agentId}\0${messageId}`).digest("hex").slice(0, 24)}`;
+                telemetry?.delivery(agentId, messageId, "error");
+                emit({ type: "delivery", agentId, deliveryId, messageId, status: "error", reason });
+                return { status: "error", deliveryId, reason, retryable: false };
+            }
             reconcileExternalConsumption(agent);
             const existingId = agent.byMessage.get(messageId);
             if (existingId) {
                 const existing = agent.records.get(existingId);
                 if (existing?.status === "error") {
-                    existing.input.attempt += 1;
+                    if (existing.target && existing.target !== target)
+                        return quarantineRecord(agent, existing, "delivery_target_conflict");
+                    existing.target = target;
+                    if (typeof envelope.wake_reason === "string" && envelope.wake_reason)
+                        existing.wakeReason = envelope.wake_reason;
+                    else
+                        delete existing.wakeReason;
+                    const priorAttempt = existing.input && Number.isSafeInteger(existing.input.attempt) ? existing.input.attempt : 0;
+                    existing.input = existing.input && typeof existing.input === "object"
+                        ? { ...existing.input, attempt: priorAttempt + 1 }
+                        : { inputId: existing.deliveryId, deliveryId: existing.deliveryId, kind: "wake", text: "", attempt: priorAttempt + 1 };
                     delete existing.reason;
                     delete existing.retryable;
                     setRecord(agent, existing, "pending");
@@ -885,11 +1534,12 @@ export function createRuntimeHost(options) {
             }
             const deliveryId = crypto.randomUUID();
             const busy = agent.busy || agent.submitting;
+            const wakeReason = typeof envelope.wake_reason === "string" ? envelope.wake_reason : undefined;
             const input = { inputId: deliveryId, deliveryId, kind: busy ? "inbox_update" : "wake",
-                text: options.promptBuilder.buildInboxNotice({ busy, count: 1, deliveryId,
-                    ...(typeof envelope.target === "string" ? { target: envelope.target } : {}),
-                    ...(typeof envelope.wake_reason === "string" ? { wakeReason: envelope.wake_reason } : {}) }), attempt: 0 };
-            const record = { deliveryId, messageId, status: "pending", input, updatedAt: now() };
+                text: options.promptBuilder.buildInboxNotice({ busy, count: 1, deliveryId, target,
+                    ...(wakeReason ? { wakeReason } : {}) }), attempt: 0 };
+            const record = { deliveryId, messageId, status: "pending", input, target,
+                ...(wakeReason ? { wakeReason } : {}), updatedAt: now() };
             agent.records.set(deliveryId, record);
             agent.byMessage.set(messageId, deliveryId);
             persist(agent);