larkin 0.4.2 → 0.4.6

package/dist/runtime/runtime-adapters.mjs

@@ -6,12 +6,14 @@ import { createInterface } from "node:readline";
 import { isPiThinkingLevel } from "./pi-model-catalog.mjs";
 import { PiRpcClient } from "./pi-rpc-client.mjs";
 import { internalCommandSpec } from "../app/internal-command.mjs";
-import { piAgentDirectory } from "./pi-provider-config.mjs";
+import { BUNDLED_PI_VERSION, piAgentDirectory } from "./pi-provider-config.mjs";
+import { recordPiRuntimeArtifactProvenance } from "./pi-artifact-provenance.mjs";
+import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 import { resolvePiSubagentExtensionArg } from "./pi-subagent-injection.mjs";
 import { resolvePiBashTimeoutExtensionArg } from "./pi-bash-timeout-injection.mjs";
 import { classifyRuntimePrerequisite, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
 import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, } from "./provider-error-classifier.mjs";
-import { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, } from "./pi-compaction-recovery.mjs";
+import { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, calculatePiCompactionSettings, parsePiExecutableVersion, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, writeOwnedPiSettings, } from "./pi-compaction-recovery.mjs";
 class EventSession {
     listeners = new Set();
     subscribe(listener) {
@@ -452,10 +454,12 @@ class PiSession extends EventSession {
     observedAgentEndEpochs = new Set();
     firstOutputObserved = false;
     toolCallOpen = false;
+    piPolicyManaged;
     constructor(sdk, distribution) {
         super();
         this.sdk = sdk;
         this.distribution = distribution;
+        this.piPolicyManaged = sdk.policyManaged ?? typeof sdk.validatePolicy === "function";
         const result = sdk.subscribe?.((event) => this.onEvent(event));
         if (typeof result === "function")
             this.unsubscribe = result;
@@ -476,8 +480,22 @@ class PiSession extends EventSession {
     async compact(customInstructions) {
         if (!this.sdk.compact)
             throw new Error("Pi compact RPC is unavailable");
+        await this.sdk.validatePolicy?.();
         return this.sdk.compact(customInstructions);
     }
+    async getContextUsage() {
+        if (!this.sdk.getSessionStats)
+            return null;
+        await this.sdk.validatePolicy?.();
+        const stats = await this.sdk.getSessionStats();
+        const usage = stats?.contextUsage;
+        const tokens = Number(usage?.tokens);
+        const contextWindow = Number(usage?.contextWindow);
+        if (!Number.isFinite(tokens) || tokens < 0 || !Number.isSafeInteger(contextWindow) || contextWindow <= 0) {
+            throw new Error("Pi get_session_stats returned invalid contextUsage");
+        }
+        return { tokens, contextWindow };
+    }
     async close(_reason) { this.unsubscribe?.(); await this.sdk.dispose?.(); }
     async enqueue(input, operation) {
         if (this.ownedInputIds.size === 0)
@@ -492,7 +510,8 @@ class PiSession extends EventSession {
             this.emitObservation("rpc_submit");
         }
         try {
-            await operation();
+            const accepted = this.sdk.validatePolicy ? this.sdk.validatePolicy().then(operation) : operation();
+            await accepted;
             this.awaitingAcknowledgement.delete(input.inputId);
             if (ownsRpcObservation && !this.observedAcceptedEpochs.has(epoch)) {
                 this.observedAcceptedEpochs.add(epoch);
@@ -788,6 +807,28 @@ export function createPiSessionManager(input) {
         throw error;
     }
 }
+async function discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, env, spawn, rpcOptions) {
+    const probeArgs = [...commandPrefix, "--mode", "rpc", "--no-session", "--no-extensions",
+        ...(requestedModel ? ["--model", requestedModel] : [])];
+    const probe = spawn(command, probeArgs, {
+        cwd: input.workspaceDir,
+        env,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const client = new PiRpcClient(probe, rpcOptions);
+    try {
+        const state = await client.request("get_state");
+        const contextWindow = state.model?.contextWindow;
+        calculatePiCompactionSettings(contextWindow);
+        const model = state.model?.provider && state.model.id ? `${state.model.provider}/${state.model.id}` : null;
+        if (!model)
+            throw new Error("Pi isolated probe did not report an effective model");
+        return { model, contextWindow: contextWindow };
+    }
+    finally {
+        await client.close();
+    }
+}
 function writePrivateAtomic(file, content) {
     try {
         if (fs.lstatSync(file).isSymbolicLink())
@@ -812,11 +853,15 @@ function writePrivateAtomic(file, content) {
 }
 class PiRpcBackend {
     client;
+    policy;
+    policyManaged;
     sessionId;
     model;
     thinkingLevel;
-    constructor(client, state) {
+    constructor(client, state, policy) {
         this.client = client;
+        this.policy = policy;
+        this.policyManaged = Boolean(policy);
         this.sessionId = state.sessionId ?? null;
         if (state.model?.provider && state.model.id)
             this.model = {
@@ -830,6 +875,22 @@ class PiRpcBackend {
     steer(text) { return this.client.request("steer", { message: text }); }
     abort() { return this.client.request("abort"); }
     compact(customInstructions) { return this.client.requestCompact(customInstructions); }
+    getSessionStats() { return this.client.request("get_session_stats"); }
+    async validatePolicy() {
+        if (!this.policy)
+            return;
+        const state = await this.client.request("get_state");
+        const effectiveModel = state.model?.provider && state.model.id ? `${state.model.provider}/${state.model.id}` : null;
+        if (effectiveModel !== this.policy.model || state.model?.contextWindow !== this.policy.contextWindow) {
+            throw new Error("Pi model or context window changed after startup; compaction policy is no longer safe");
+        }
+        const ownedSettings = readOwnedPiSettings(this.policy.ownedPiDirectory);
+        assertEffectivePiCompactionSettings({ contextWindow: state.model?.contextWindow, compaction: {
+                enabled: state.autoCompactionEnabled,
+                reserveTokens: ownedSettings.compaction?.reserveTokens,
+                keepRecentTokens: ownedSettings.compaction?.keepRecentTokens,
+            } });
+    }
     getState() { return this.client.request("get_state"); }
     dispose() { return this.client.close(); }
     subscribe(listener) {
@@ -861,6 +922,7 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         ? piAgentDirectory(mergedEnv.LARKIN_CONFIG_DIR, input.agentId)
         : path.join(stateRoot, "pi-agent");
     prepareOwnedPiDirectory(ownedPiDirectory);
+    traceProcessBoundary(mergedEnv, "pi-rpc:child-env", { configDir: mergedEnv.LARKIN_CONFIG_DIR, agentId: input.agentId, targetDir: ownedPiDirectory, childEnvConfigDir: mergedEnv.LARKIN_CONFIG_DIR || null, childEnvHome: mergedEnv.HOME || null });
     const runtimeDir = path.join(stateRoot, "runtime");
     fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
     const promptFile = path.join(runtimeDir, "pi-standing-prompt.md");
@@ -877,24 +939,40 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
     const builtin = mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin";
     const builtinSpec = builtin ? internalCommandSpec("pi-rpc", [], mergedEnv) : null;
     const command = builtinSpec?.command ?? dependencies.piCommand ?? dependencies.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-    const commandArgs = [...(builtinSpec?.args ?? []), ...args];
+    const commandPrefix = builtinSpec?.args ?? dependencies.piCommandArgs ?? [];
+    const commandArgs = [...commandPrefix, ...args];
     const reportedVersion = productionSpawn && !builtin
-        ? String(spawnSync(command, ["--version"], { cwd: input.workspaceDir, env: mergedEnv, encoding: "utf8", timeout: 5_000 }).stdout || "").trim()
-        : "0.83.0";
+        ? parsePiExecutableVersion(String(spawnSync(command, [...commandPrefix, "--version"], {
+            cwd: input.workspaceDir, env: mergedEnv, encoding: "utf8", timeout: 5_000,
+        }).stdout || ""))
+        : BUNDLED_PI_VERSION;
     mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
     if (builtin)
         mergedEnv.PI_TELEMETRY = "0";
-    commandArgs.push(...(dependencies.resolvePiProcessExtensionArgs ?? resolvePiProcessExtensionArgs)({
+    const extensionArgs = (dependencies.resolvePiProcessExtensionArgs ?? resolvePiProcessExtensionArgs)({
         distribution: builtin ? "builtin" : "external",
         piCommand: command,
         env: mergedEnv,
         platform: process.platform,
-    }));
+    });
+    commandArgs.push(...extensionArgs);
+    let probedModel = null;
+    if (productionSpawn) {
+        // Pi reads compaction settings when the process starts. Probe the exact
+        // requested model first, then write the matching 15% reserve before the
+        // real session starts; no prompt, provider request, package, or extension
+        // is loaded by the probe.
+        probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, mergedEnv, spawn, dependencies.piRpcClientOptions);
+        writeOwnedPiSettings(ownedPiDirectory, calculatePiCompactionSettings(probedModel.contextWindow));
+    }
+    const artifactEntriesBeforeSpawn = new Set(fs.readdirSync(ownedPiDirectory));
+    const artifactSpawnBoundary = Date.now();
     const child = spawn(command, commandArgs, {
         cwd: input.workspaceDir,
         env: mergedEnv,
         stdio: ["pipe", "pipe", "pipe"],
     });
+    traceProcessBoundary(mergedEnv, "pi-rpc:child-spawned", { configDir: mergedEnv.LARKIN_CONFIG_DIR, agentId: input.agentId, targetDir: ownedPiDirectory, childPid: child.pid ?? null });
     const client = new PiRpcClient(child, dependencies.piRpcClientOptions);
     try {
         const [state, available] = await Promise.all([
@@ -905,6 +983,10 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
             throw new Error("Pi has no authenticated available models. Run the official `pi` login flow or configure provider credentials; Larkin will not create a fallback session.");
         const effectiveModel = state.model?.provider && state.model.id ? `${state.model.provider}/${state.model.id}` : null;
         if (productionSpawn) {
+            if (!effectiveModel || !probedModel || effectiveModel !== probedModel.model
+                || state.model?.contextWindow !== probedModel.contextWindow) {
+                throw new Error("Pi model or context window changed between the isolated probe and runtime startup");
+            }
             const ownedSettings = readOwnedPiSettings(ownedPiDirectory);
             assertEffectivePiCompactionSettings({ contextWindow: state.model?.contextWindow, compaction: {
                     enabled: state.autoCompactionEnabled,
@@ -930,7 +1012,10 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         }
         if (requestedEffort && state.thinkingLevel !== requestedEffort)
             throw new Error(`Pi thinking level ${requestedEffort} was not accepted by effective model ${effectiveModel || "unknown"}`);
-        return new PiRpcBackend(client, state);
+        recordPiRuntimeArtifactProvenance(ownedPiDirectory, artifactEntriesBeforeSpawn, artifactSpawnBoundary);
+        return new PiRpcBackend(client, state, productionSpawn ? {
+            model: effectiveModel, contextWindow: state.model?.contextWindow, ownedPiDirectory,
+        } : undefined);
     }
     catch (error) {
         await client.close();
@@ -1035,7 +1120,8 @@ export function createNativeRuntimeAdapter(id, dependencies = {}) {
         capabilities: CAPABILITIES[id],
         async probe(input) {
             const readiness = await probeNativeRuntimeReadiness({ runtime: id, agentId: input.agentId, cwd: input.workspaceDir,
-                env: { ...dependencies.env, ...input.env }, command: configuredCommand });
+                env: { ...dependencies.env, ...input.env }, command: configuredCommand,
+                ...(id === "pi" && dependencies.piCommandArgs ? { commandArgs: dependencies.piCommandArgs } : {}) });
             resolvedExecutable = readiness.state === "ready" ? readiness.executable ?? null : null;
             return readiness;
         },

package/dist/runtime/runtime-host.cjs

@@ -397,18 +397,22 @@ function createRuntimeHost(options) {
     };
     const resultFor = (agent, record, result) => {
         if (result.status === "accepted") {
-            delete record.reason;
+            if (record.errorCategory !== "context_window") {
+                delete record.reason;
+                delete record.errorCategory;
+            }
             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;
+        if (record.errorCategory !== "context_window")
+            delete record.errorCategory;
         const retryable = result.status === "deferred" || result.retryable;
-        record.reason = result.reason;
+        if (record.errorCategory !== "context_window")
+            record.reason = result.reason;
         record.retryable = retryable;
         const finalRecord = setRecord(agent, record, retryable ? "pending" : "error");
         if (finalRecord.status === "consumed")
@@ -420,6 +424,22 @@ function createRuntimeHost(options) {
             : { status: "error", deliveryId: record.deliveryId, reason: result.reason, retryable: false };
     };
     const submit = async (agent, record, busy) => {
+        const proactive = agent.piProactiveCompaction
+            && agent.piProactiveCompactionGeneration === agent.generation
+            && agent.piProactiveCompactionSession === agent.session
+            ? agent.piProactiveCompaction : null;
+        if (proactive && await proactive === "failed") {
+            return { status: "deferred", deliveryId: record.deliveryId, reason: "Pi proactive compaction failed for the current session generation" };
+        }
+        if (agent.adapter.id === "pi" && agent.piProactiveCompactionFailedGeneration === agent.generation) {
+            return { status: "deferred", deliveryId: record.deliveryId, reason: "Pi proactive compaction failed for the current session generation" };
+        }
+        if (agent.adapter.id === "pi" && !busy && !agent.busy && !agent.turnInProgress && agent.session) {
+            const idleGate = proactivelyCompactPiAtIdle(agent, agent.session);
+            if (idleGate && await idleGate === "failed") {
+                return { status: "deferred", deliveryId: record.deliveryId, reason: "Pi proactive compaction failed for the current session generation" };
+            }
+        }
         agent.submitting = true;
         if (!busy)
             agent.busy = true; // Reserve the turn before prompt() can yield.
@@ -459,9 +479,11 @@ function createRuntimeHost(options) {
             if (!busy)
                 agent.busy = false;
             const reason = error instanceof Error ? error.message : String(error);
-            record.reason = reason;
+            if (record.errorCategory !== "context_window") {
+                record.reason = reason;
+                delete record.errorCategory;
+            }
             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 };
@@ -475,16 +497,41 @@ function createRuntimeHost(options) {
         }
     };
     const retryPending = async (agent) => {
-        reconcileExternalConsumption(agent);
-        if (agent.submitting) {
-            agent.retryAfterSubmit = true;
-            return;
+        if (agent.retryPendingInFlight)
+            return agent.retryPendingInFlight;
+        const run = (async () => {
+            reconcileExternalConsumption(agent);
+            const proactive = agent.piProactiveCompaction
+                && agent.piProactiveCompactionGeneration === agent.generation
+                && agent.piProactiveCompactionSession === agent.session
+                ? agent.piProactiveCompaction : null;
+            if (proactive && await proactive === "failed")
+                return;
+            if (agent.submitting || agent.starting) {
+                agent.retryAfterSubmit = true;
+                return;
+            }
+            if (agent.adapter.id === "pi" && agent.piProactiveCompactionFailedGeneration === agent.generation)
+                return;
+            if (agent.busy || agent.turnInProgress || !agent.session)
+                return;
+            if (agent.adapter.id === "pi") {
+                const idleGate = proactivelyCompactPiAtIdle(agent, agent.session);
+                if (idleGate && await idleGate === "failed")
+                    return;
+            }
+            const record = [...agent.records.values()].find((candidate) => candidate.status === "pending" || candidate.status === "submitting");
+            if (record)
+                await submit(agent, record, false);
+        })();
+        agent.retryPendingInFlight = run;
+        try {
+            await run;
+        }
+        finally {
+            if (agent.retryPendingInFlight === run)
+                agent.retryPendingInFlight = null;
         }
-        if (agent.busy || agent.turnInProgress || !agent.session)
-            return;
-        const record = [...agent.records.values()].find((candidate) => candidate.status === "pending" || candidate.status === "submitting");
-        if (record)
-            await submit(agent, record, false);
     };
     const scheduleRecreate = (agent, reason) => {
         if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
@@ -502,8 +549,12 @@ function createRuntimeHost(options) {
             agent.retryTimer = null;
             if (agent.stopped)
                 return;
-            void ensureSession(agent).then(() => {
-                return retryPending(agent);
+            void ensureSession(agent).then(async () => {
+                const session = agent.session;
+                const proactive = session ? proactivelyCompactPiAtIdle(agent, session) : null;
+                if (proactive && await proactive === "failed")
+                    return;
+                await retryPending(agent);
             }).catch((error) => {
                 const readiness = error instanceof runtime_readiness_js_1.RuntimePrerequisiteError ? error.readiness
                     : (0, runtime_readiness_js_1.classifyRuntimePrerequisite)(agent.adapter.id, error);
@@ -614,7 +665,6 @@ function createRuntimeHost(options) {
                     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)
@@ -623,14 +673,19 @@ function createRuntimeHost(options) {
                 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";
+                    const recoveryReason = machine.recordSnapshot.fallbackReason || "Pi compaction recovery fallback";
+                    // Delivery proof must remain the exact provider-classified context error.
+                    // Generic Pi recovery text belongs only in the breaker and logs.
+                    if (record.errorCategory === "context_window" && typeof record.reason === "string") {
                         record.retryable = false;
-                        record.errorCategory = "context_window";
                         setRecord(agent, record, "error");
+                        if (!agent.compactionRecoveryInFlight.has(key)) {
+                            agent.compactionRecoveryInFlight.add(key);
+                            void recoverContextOverflowInternal(agent.config.agentId, key, recoveryReason, key)
+                                .catch((error) => log("Pi context fallback failed", String(error)))
+                                .finally(() => agent.compactionRecoveryInFlight.delete(key));
+                        }
                     }
-                    void recoverContextOverflowInternal(agent.config.agentId, key, machine.recordSnapshot.fallbackReason || "Pi compaction recovery fallback", key)
-                        .catch((error) => log("Pi context fallback failed", String(error)));
                 }
             },
         });
@@ -665,6 +720,8 @@ function createRuntimeHost(options) {
         });
     };
     const recoverStalePiCompaction = async (agent) => {
+        if (!agent.stateStore)
+            return;
         const breaker = agent.compactionBreaker;
         if (!breaker)
             return;
@@ -679,14 +736,59 @@ function createRuntimeHost(options) {
             || candidate.input.inputId === stale.inputId);
         if (!record)
             return;
-        record.reason = stale.fallbackReason || "Pi compaction recovery resumed after restart";
+        const recoveryReason = stale.fallbackReason || "Pi compaction recovery resumed after restart";
+        if (record.errorCategory !== "context_window" || typeof record.reason !== "string")
+            return;
         record.retryable = false;
-        record.errorCategory = "context_window";
         setRecord(agent, record, "error");
-        breaker.forceFallback(stale.key, record.reason);
+        breaker.forceFallback(stale.key, recoveryReason);
         agent.busy = false;
         agent.turnInProgress = false;
-        await recoverContextOverflowInternal(agent.config.agentId, stale.key, record.reason, stale.key);
+        await recoverContextOverflowInternal(agent.config.agentId, stale.key, recoveryReason, stale.key);
+    };
+    const proactivelyCompactPiAtIdle = (agent, session) => {
+        if (agent.adapter.id !== "pi" || session.piPolicyManaged === false
+            || !session.getContextUsage || !session.compact)
+            return null;
+        if (agent.session !== session || agent.stopped || agent.busy || agent.turnInProgress || agent.submitting || agent.starting
+            || agent.compactionRecoveryInFlight.size > 0
+            || agent.compactionMachines.size > 0 || agent.piOverflowCompactionFailed.size > 0)
+            return null;
+        if (agent.piProactiveCompactionFailedGeneration === agent.generation)
+            return null;
+        const generation = agent.generation;
+        if (agent.piProactiveCompaction && agent.piProactiveCompactionGeneration === generation
+            && agent.piProactiveCompactionSession === session)
+            return agent.piProactiveCompaction;
+        const task = (async () => {
+            const before = await session.getContextUsage();
+            if (!before || agent.session !== session || agent.stopped || agent.busy || agent.turnInProgress || agent.submitting
+                || agent.compactionRecoveryInFlight.size > 0 || agent.compactionMachines.size > 0
+                || agent.piOverflowCompactionFailed.size > 0)
+                return "noop";
+            if (!(0, pi_compaction_recovery_js_1.isPiNativeCompactionRequired)(before.tokens, before.contextWindow))
+                return "noop";
+            await session.compact();
+            const after = await session.getContextUsage();
+            if (!after || after.contextWindow !== before.contextWindow || after.tokens >= before.tokens) {
+                throw new Error("Pi proactive compaction did not reduce the verified context usage");
+            }
+            return "succeeded";
+        })();
+        const tracked = task.catch((error) => {
+            agent.piProactiveCompactionFailedGeneration = generation;
+            emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
+                error: "Pi proactive compaction failed; the current session generation is degraded" });
+            log("Pi proactive compaction failed", String(error));
+            return "failed";
+        }).finally(() => {
+            if (agent.piProactiveCompaction === tracked)
+                agent.piProactiveCompaction = null;
+        });
+        agent.piProactiveCompactionGeneration = generation;
+        agent.piProactiveCompactionSession = session;
+        agent.piProactiveCompaction = tracked;
+        return tracked;
     };
     const observe = (agent, session, event) => {
         if (agent.session !== session)
@@ -728,7 +830,6 @@ function createRuntimeHost(options) {
             agent.config.sessionId = event.sessionId;
             emit({ type: "session", agentId: agent.config.agentId, runtime: agent.adapter.id, sessionId: event.sessionId, launchId: agent.launchId,
                 ...(event.model ? { model: event.model } : {}), ...(event.reasoningEffort ? { reasoningEffort: event.reasoningEffort } : {}) });
-            void retryPending(agent);
         }
         else if (event.type === "turn-start") {
             agent.busy = true;
@@ -764,7 +865,11 @@ function createRuntimeHost(options) {
                 };
                 emit({ type: "agent-status", agentId: agent.config.agentId, status: "active", readiness: agent.readiness });
             }
-            void retryPending(agent);
+            const proactive = proactivelyCompactPiAtIdle(agent, session);
+            void (proactive ?? Promise.resolve("noop")).then((outcome) => {
+                if (outcome !== "failed")
+                    return retryPending(agent);
+            });
         }
         else if (event.type === "activity") {
             if (agent.turnInProgress && event.activity !== "internal")
@@ -790,8 +895,13 @@ function createRuntimeHost(options) {
                 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)));
+                    const recoveryKey = `${record.deliveryId}:${record.input.inputId}`;
+                    if (!agent.compactionRecoveryInFlight.has(recoveryKey)) {
+                        agent.compactionRecoveryInFlight.add(recoveryKey);
+                        void recoverContextOverflowInternal(agent.config.agentId, recoveryKey, "native Pi overflow compaction failed", recoveryKey)
+                            .catch((error) => log("Pi native compaction fallback failed", String(error)))
+                            .finally(() => agent.compactionRecoveryInFlight.delete(recoveryKey));
+                    }
                     return;
                 }
                 // Pi emits this terminal error only after agent_settled; release the
@@ -976,7 +1086,6 @@ function createRuntimeHost(options) {
                     continue;
                 candidate.status = "pending";
                 candidate.retryable = true;
-                candidate.reason = "context-window recovery rearmed the retained Inbox delivery";
                 candidate.updatedAt = now();
             }
         };
@@ -1022,7 +1131,11 @@ function createRuntimeHost(options) {
         }
         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);
+        const proactive = proactivelyCompactPiAtIdle(agent, fresh);
+        void (proactive ?? Promise.resolve("noop")).then((outcome) => {
+            if (outcome !== "failed")
+                return retryPending(agent);
+        });
         return { generationChanged: true, sessionChanged: oldSessionId !== fresh.sessionId, turns: 0,
             runtimeReady: true, pendingCount: remainingPendingCount, rearmedCount,
             replayStatus: remainingPendingCount > 0 ? "pending" : "consumed", sessionId: fresh.sessionId };
@@ -1334,7 +1447,6 @@ function createRuntimeHost(options) {
                             continue;
                         record.status = "pending";
                         record.retryable = true;
-                        record.reason = "context-window recovery rearmed the retained Inbox delivery";
                         record.updatedAt = now();
                     }
                 });
@@ -1349,7 +1461,11 @@ function createRuntimeHost(options) {
                 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);
+                const proactive = proactivelyCompactPiAtIdle(agent, fresh);
+                void (proactive ?? Promise.resolve("noop")).then((outcome) => {
+                    if (outcome !== "failed")
+                        return 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 };
@@ -1417,16 +1533,19 @@ function createRuntimeHost(options) {
                     : readDeliveryFile(config.stateDir ? node_path_1.default.join(config.stateDir, "runtime-deliveries.json") : null);
                 const agent = { config, adapter: options.adapterFor(config.runtime), session: null,
                     launchId: node_crypto_1.default.randomUUID(), busy: false, submitting: false, starting: null, retryAfterSubmit: false,
+                    retryPendingInFlight: null,
                     records: new Map(persisted.records.map((record) => [record.deliveryId, record])),
                     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,
-                    compactionBreaker: config.runtime === "pi"
+                    compactionBreaker: config.runtime === "pi" && stateStore
                         ? new pi_compaction_recovery_js_1.PiCompactionBreaker(config.stateDir ?? node_path_1.default.join(config.workspaceDir, ".larkin", "agents", config.agentId), {
-                            withLock: stateStore ? (operation) => stateStore.withInboxTransaction(operation) : undefined,
+                            withLock: (operation) => stateStore.withInboxTransaction(operation),
                         }) : undefined,
-                    compactionMachines: new Map(), piOverflowCompactionFailed: new Set(), readiness: null,
+                    compactionMachines: new Map(), compactionRecoveryInFlight: new Set(), piOverflowCompactionFailed: new Set(),
+                    piProactiveCompaction: null, piProactiveCompactionGeneration: null, piProactiveCompactionSession: null,
+                    piProactiveCompactionFailedGeneration: null, readiness: null,
                     turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false };
                 const startupConsumed = [];
                 const startupQuarantined = [];
@@ -1459,8 +1578,12 @@ function createRuntimeHost(options) {
                 try {
                     await ensureSession(agent);
                     await recoverStalePiCompaction(agent);
+                    const startupSession = agent.session;
+                    const proactive = startupSession ? proactivelyCompactPiAtIdle(agent, startupSession) : null;
+                    const proactiveOutcome = proactive ? await proactive : "noop";
                     activeCount += 1;
-                    await retryPending(agent);
+                    if (proactiveOutcome !== "failed")
+                        await retryPending(agent);
                 }
                 catch (error) {
                     const reason = error instanceof Error ? error.message : String(error);