larkin 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.3
+
+External Pi initialization now runs with bounded concurrency and recovers from isolated startup-probe timeouts through the existing retry policy. Shutdown waits for pending initialization and closes late sessions. Generic Runtime and delivery failures show unavailable instead of incompatible, while explicit prerequisite failures and useful provider diagnostics are preserved. Recovery workflow tests wait for delivery consumption and Inbox watermarks to converge and isolate temporary state.
+
 ## 0.5.2
 
 External pi now runs with the user's own Pi home; compaction settings move to the Agent workspace's `.pi/settings.json`; 0.5.0/0.5.1 started external pi with an empty agent dir and saw no logins. Stock pi 0.84.x does not emit `get_state.compactionCapabilities` (that handshake only existed for the bundled build); Larkin accepts the absence and keeps native compaction via the workspace settings file, while a present handshake must still match exactly.

package/dist/feishu/host-shell.cjs

@@ -57,6 +57,7 @@ const host_channel_business_js_1 = require("./host-channel-business.cjs");
 const interaction_orchestrator_js_1 = require("./interaction-orchestrator.cjs");
 const message_policy_js_1 = require("./message-policy.cjs");
 const runtime_readiness_js_1 = require("../runtime/runtime-readiness.cjs");
+const provider_error_classifier_js_1 = require("../runtime/provider-error-classifier.cjs");
 const callback_capability_js_1 = require("../platform/callback-capability.cjs");
 const config_js_1 = require("../platform/config.cjs");
 const internal_command_js_1 = require("../app/internal-command.cjs");
@@ -119,6 +120,9 @@ function memberNamesFromPayloads(payloads) {
     return names;
 }
 function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function safeRuntimeStatusDiagnostic(error) {
+    return (0, provider_error_classifier_js_1.safeProviderDiagnostic)(error, "Runtime entered an error state", 500);
+}
 function agentConfigSignature(agent) {
     return JSON.stringify({
         agentId: agent.agentId, runtime: agent.runtime, model: agent.model, effort: agent.effort ?? null,
@@ -233,17 +237,40 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
         }
         hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt } });
     };
+    const projectFallbackRuntimeReadiness = (agent, observedAt, fallback, preserveCurrentUnavailableDiagnostic = false) => {
+        const failure = unresolvedCurrentAuth(agent);
+        if (failure) {
+            hostState.updateStatus(agent, {
+                runtimeReadiness: { ...(0, runtime_readiness_js_1.readinessForPersistedAuthFailure)(failure), observedAt },
+            });
+            return;
+        }
+        const currentReadiness = hostState.readStatus(agent).runtimeReadiness;
+        const observedMs = Date.parse(String(currentReadiness?.observedAt || ""));
+        const daemonStartedMs = Date.parse(daemonStartedAt);
+        const currentEpoch = currentReadiness?.runtime === agent.runtime
+            && Number.isFinite(observedMs) && Number.isFinite(daemonStartedMs) && observedMs >= daemonStartedMs;
+        if (currentEpoch && (currentReadiness?.state === "missing" || currentReadiness?.state === "unauthenticated" || currentReadiness?.state === "incompatible"))
+            return;
+        if (currentEpoch && preserveCurrentUnavailableDiagnostic && currentReadiness?.state === "unavailable"
+            && typeof currentReadiness.reason === "string" && currentReadiness.reason.trim()) {
+            hostState.updateStatus(agent, {
+                runtimeReadiness: { ...currentReadiness, runtime: agent.runtime, state: "unavailable", observedAt },
+            });
+            return;
+        }
+        hostState.updateStatus(agent, {
+            runtimeReadiness: { runtime: agent.runtime, ...fallback, observedAt },
+        });
+    };
     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.";
-        const currentReadiness = hostState.readStatus(agent).runtimeReadiness;
         hostState.updateStatus(agent, {
             inboundDeliveryHealth: { state: "error", code, at, reason, nextAction },
-            ...(currentReadiness?.state === "unauthenticated" ? {} : {
-                runtimeReadiness: { runtime: agent.runtime, state: "incompatible", reason, nextAction },
-            }),
         });
+        projectFallbackRuntimeReadiness(agent, at, { state: "unavailable", reason, nextAction }, true);
         hostState.recordStatusError(agent, `${reason} ${nextAction} code=${code}`);
     };
     const agentStates = new Map();
@@ -1312,15 +1339,21 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
         if (message.type === "agent-status") {
             log("agent:status", message.agentId, message.status);
             const observedAt = new Date().toISOString();
-            if (message.status === "error" || message.status === "inactive")
-                hostState.updateStatus(agent, {
-                    runtimeReadiness: message.readiness?.state && message.readiness.state !== "ready" ? { ...message.readiness, observedAt } : {
-                        runtime: agent.runtime,
-                        state: message.status === "error" ? "incompatible" : "missing",
-                        reason: message.status === "error" ? message.error || "Runtime entered an error state" : "Runtime is inactive",
-                        observedAt,
-                    },
-                });
+            if (message.status === "error" || message.status === "inactive") {
+                if (message.readiness?.state && message.readiness.state !== "ready") {
+                    hostState.updateStatus(agent, { runtimeReadiness: { ...message.readiness, observedAt } });
+                }
+                else {
+                    projectFallbackRuntimeReadiness(agent, observedAt, message.status === "error" ? {
+                        state: "unavailable",
+                        reason: safeRuntimeStatusDiagnostic(message.error),
+                        nextAction: "Inspect the Runtime status error, correct the Runtime availability issue, then retry.",
+                    } : {
+                        state: "missing",
+                        reason: "Runtime is inactive",
+                    });
+                }
+            }
             else if (message.readiness) {
                 if (message.readiness.state === "ready" && unresolvedCurrentAuth(agent)) {
                     projectReadyUnlessUnresolvedAuth(agent, observedAt);
@@ -1338,7 +1371,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                 redeliveryTimer.unref?.();
             }
             if (message.status === "error" && message.error)
-                hostState.recordStatusError(agent, message.error);
+                hostState.recordStatusError(agent, safeRuntimeStatusDiagnostic(message.error));
             if (message.status === "error" || message.status === "inactive") {
                 processingEyes.clear(agent, `agent-status:${message.status}`);
             }

package/dist/feishu/host-shell.mjs

@@ -17,6 +17,7 @@ import { HostChannelBusiness } from "./host-channel-business.mjs";
 import { HostInteractionOrchestrator } from "./interaction-orchestrator.mjs";
 import { targetFor } from "./message-policy.mjs";
 import { authFailureAppliesTo, parsePersistedAuthFailure, providerAuthenticationFailureReadiness, readinessForPersistedAuthFailure, RuntimePrerequisiteError, } from "../runtime/runtime-readiness.mjs";
+import { safeProviderDiagnostic } from "../runtime/provider-error-classifier.mjs";
 import { readDocumentCommentSubscription, verifyCallbackProbe } from "../platform/callback-capability.mjs";
 import { loadConfig, resolveMentionPolicy } from "../platform/config.mjs";
 import { processCommandToken } from "../app/internal-command.mjs";
@@ -79,6 +80,9 @@ export function memberNamesFromPayloads(payloads) {
     return names;
 }
 function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function safeRuntimeStatusDiagnostic(error) {
+    return safeProviderDiagnostic(error, "Runtime entered an error state", 500);
+}
 function agentConfigSignature(agent) {
     return JSON.stringify({
         agentId: agent.agentId, runtime: agent.runtime, model: agent.model, effort: agent.effort ?? null,
@@ -193,17 +197,40 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
         }
         hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt } });
     };
+    const projectFallbackRuntimeReadiness = (agent, observedAt, fallback, preserveCurrentUnavailableDiagnostic = false) => {
+        const failure = unresolvedCurrentAuth(agent);
+        if (failure) {
+            hostState.updateStatus(agent, {
+                runtimeReadiness: { ...readinessForPersistedAuthFailure(failure), observedAt },
+            });
+            return;
+        }
+        const currentReadiness = hostState.readStatus(agent).runtimeReadiness;
+        const observedMs = Date.parse(String(currentReadiness?.observedAt || ""));
+        const daemonStartedMs = Date.parse(daemonStartedAt);
+        const currentEpoch = currentReadiness?.runtime === agent.runtime
+            && Number.isFinite(observedMs) && Number.isFinite(daemonStartedMs) && observedMs >= daemonStartedMs;
+        if (currentEpoch && (currentReadiness?.state === "missing" || currentReadiness?.state === "unauthenticated" || currentReadiness?.state === "incompatible"))
+            return;
+        if (currentEpoch && preserveCurrentUnavailableDiagnostic && currentReadiness?.state === "unavailable"
+            && typeof currentReadiness.reason === "string" && currentReadiness.reason.trim()) {
+            hostState.updateStatus(agent, {
+                runtimeReadiness: { ...currentReadiness, runtime: agent.runtime, state: "unavailable", observedAt },
+            });
+            return;
+        }
+        hostState.updateStatus(agent, {
+            runtimeReadiness: { runtime: agent.runtime, ...fallback, observedAt },
+        });
+    };
     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.";
-        const currentReadiness = hostState.readStatus(agent).runtimeReadiness;
         hostState.updateStatus(agent, {
             inboundDeliveryHealth: { state: "error", code, at, reason, nextAction },
-            ...(currentReadiness?.state === "unauthenticated" ? {} : {
-                runtimeReadiness: { runtime: agent.runtime, state: "incompatible", reason, nextAction },
-            }),
         });
+        projectFallbackRuntimeReadiness(agent, at, { state: "unavailable", reason, nextAction }, true);
         hostState.recordStatusError(agent, `${reason} ${nextAction} code=${code}`);
     };
     const agentStates = new Map();
@@ -1272,15 +1299,21 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
         if (message.type === "agent-status") {
             log("agent:status", message.agentId, message.status);
             const observedAt = new Date().toISOString();
-            if (message.status === "error" || message.status === "inactive")
-                hostState.updateStatus(agent, {
-                    runtimeReadiness: message.readiness?.state && message.readiness.state !== "ready" ? { ...message.readiness, observedAt } : {
-                        runtime: agent.runtime,
-                        state: message.status === "error" ? "incompatible" : "missing",
-                        reason: message.status === "error" ? message.error || "Runtime entered an error state" : "Runtime is inactive",
-                        observedAt,
-                    },
-                });
+            if (message.status === "error" || message.status === "inactive") {
+                if (message.readiness?.state && message.readiness.state !== "ready") {
+                    hostState.updateStatus(agent, { runtimeReadiness: { ...message.readiness, observedAt } });
+                }
+                else {
+                    projectFallbackRuntimeReadiness(agent, observedAt, message.status === "error" ? {
+                        state: "unavailable",
+                        reason: safeRuntimeStatusDiagnostic(message.error),
+                        nextAction: "Inspect the Runtime status error, correct the Runtime availability issue, then retry.",
+                    } : {
+                        state: "missing",
+                        reason: "Runtime is inactive",
+                    });
+                }
+            }
             else if (message.readiness) {
                 if (message.readiness.state === "ready" && unresolvedCurrentAuth(agent)) {
                     projectReadyUnlessUnresolvedAuth(agent, observedAt);
@@ -1298,7 +1331,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                 redeliveryTimer.unref?.();
             }
             if (message.status === "error" && message.error)
-                hostState.recordStatusError(agent, message.error);
+                hostState.recordStatusError(agent, safeRuntimeStatusDiagnostic(message.error));
             if (message.status === "error" || message.status === "inactive") {
                 processingEyes.clear(agent, `agent-status:${message.status}`);
             }

package/dist/runtime/provider-error-classifier.cjs

@@ -1,11 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON = exports.CANONICAL_CONTEXT_WINDOW_MESSAGE = exports.CODEX_ERROR_PREFIX = void 0;
+exports.safeProviderDiagnostic = safeProviderDiagnostic;
 exports.buildStrictProviderErrorInput = buildStrictProviderErrorInput;
 exports.classifyStrictProviderError = classifyStrictProviderError;
 exports.CODEX_ERROR_PREFIX = "Codex error: ";
 exports.CANONICAL_CONTEXT_WINDOW_MESSAGE = "Your input exceeds the context window of this model. Please adjust your input and try again.";
 exports.INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON = "provider rejected the input because the context window was exceeded";
+/** Redact credentials and local filesystem locations from provider diagnostics kept in status. */
+function safeProviderDiagnostic(value, fallback, max = 2_000) {
+    const source = typeof value === "string" ? value : fallback;
+    return source
+        .replace(/\b(?:authorization|proxy-authorization)\s*[:=]\s*(?:Bearer\s+)?[^\s,;]+/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
+        .replace(/\b(?:cookie|set-cookie)\s*[:=]\s*(?:[^;\s,]+(?:\s*;\s*[^;\s,]+)*)/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
+        .replace(/\b(?:api[_ -]?key|access[_ -]?token|refresh[_ -]?token|token|secret|password)\s*[:=]\s*[^\s,;]+/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
+        .replace(/(["'](?:authorization|cookie|api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password)["']\s*:\s*)["'][^"']*["']/gi, "$1\"[redacted]\"")
+        .replace(/Bearer\s+[A-Za-z0-9._~+\/-]+/gi, "Bearer [redacted]")
+        .replace(/\b(?:sk|ghp|github_pat)-?[A-Za-z0-9_-]{8,}\b/g, "[redacted]")
+        .replace(/(^|[\s"'=])(?:\/(?:Users|home|private|var|tmp|etc)\/[^\s"']+|[A-Za-z]:[\\/][^\s"']+)/g, "$1[redacted-path]")
+        .replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, max) || fallback;
+}
 /** Build the one structured provider-error shape shared by ingestion and recovery. */
 function buildStrictProviderErrorInput(source) {
     const upstream = source.upstream && typeof source.upstream === "object" && !Array.isArray(source.upstream)

package/dist/runtime/provider-error-classifier.mjs

@@ -1,6 +1,19 @@
 export const CODEX_ERROR_PREFIX = "Codex error: ";
 export const CANONICAL_CONTEXT_WINDOW_MESSAGE = "Your input exceeds the context window of this model. Please adjust your input and try again.";
 export const INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON = "provider rejected the input because the context window was exceeded";
+/** Redact credentials and local filesystem locations from provider diagnostics kept in status. */
+export function safeProviderDiagnostic(value, fallback, max = 2_000) {
+    const source = typeof value === "string" ? value : fallback;
+    return source
+        .replace(/\b(?:authorization|proxy-authorization)\s*[:=]\s*(?:Bearer\s+)?[^\s,;]+/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
+        .replace(/\b(?:cookie|set-cookie)\s*[:=]\s*(?:[^;\s,]+(?:\s*;\s*[^;\s,]+)*)/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
+        .replace(/\b(?:api[_ -]?key|access[_ -]?token|refresh[_ -]?token|token|secret|password)\s*[:=]\s*[^\s,;]+/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
+        .replace(/(["'](?:authorization|cookie|api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password)["']\s*:\s*)["'][^"']*["']/gi, "$1\"[redacted]\"")
+        .replace(/Bearer\s+[A-Za-z0-9._~+\/-]+/gi, "Bearer [redacted]")
+        .replace(/\b(?:sk|ghp|github_pat)-?[A-Za-z0-9_-]{8,}\b/g, "[redacted]")
+        .replace(/(^|[\s"'=])(?:\/(?:Users|home|private|var|tmp|etc)\/[^\s"']+|[A-Za-z]:[\\/][^\s"']+)/g, "$1[redacted-path]")
+        .replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, max) || fallback;
+}
 /** Build the one structured provider-error shape shared by ingestion and recovery. */
 export function buildStrictProviderErrorInput(source) {
     const upstream = source.upstream && typeof source.upstream === "object" && !Array.isArray(source.upstream)

package/dist/runtime/runtime-adapters.mjs

@@ -12,7 +12,7 @@ import { resolvePiSubagentRecordWatchdogExtensionArg } from "./pi-subagent-recor
 import { effectivePiStateDir, extractBackgroundPiSubagentDispatch } from "./pi-subagent-ledger.mjs";
 import { resolvePiBashTimeoutExtensionArg } from "./pi-bash-timeout-injection.mjs";
 import { classifyPiMissingCredentialRejection, classifyRuntimePrerequisite, missingProviderCredentialReadiness, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
-import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, } from "./provider-error-classifier.mjs";
+import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, safeProviderDiagnostic, } from "./provider-error-classifier.mjs";
 import { assertEffectivePiCompactionSettings, MINIMUM_PI_VERSION, calculatePiCompactionSettings, parsePiExecutableVersion, projectPiSettingsFile, readOwnedPiSettings, verifyPiCapabilities, writeOwnedPiSettings, } from "./pi-compaction-recovery.mjs";
 /** External pi must see the user's own agent dir; Larkin never injects or honors PI_CODING_AGENT_DIR. */
 function stripPiCodingAgentDir(env) {
@@ -20,6 +20,31 @@ function stripPiCodingAgentDir(env) {
     delete next.PI_CODING_AGENT_DIR;
     return next;
 }
+const PI_INITIALIZATION_CONCURRENCY = 2;
+/** Limits short-lived Pi startup handshakes without serializing live sessions. */
+function createInitializationLimiter(limit) {
+    let active = 0;
+    const waiters = [];
+    const release = () => {
+        const next = waiters.shift();
+        if (next)
+            next();
+        else
+            active -= 1;
+    };
+    return async (operation) => {
+        if (active >= limit)
+            await new Promise((resolve) => waiters.push(resolve));
+        else
+            active += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    };
+}
 class EventSession {
     listeners = new Set();
     subscribe(listener) {
@@ -780,14 +805,7 @@ class PiSession extends EventSession {
     }
 }
 function safeProviderText(value, fallback) {
-    const source = typeof value === "string" ? value : fallback;
-    return source
-        .replace(/\b(?:authorization|proxy-authorization)\s*[:=]\s*(?:Bearer\s+)?[^\s,;]+/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
-        .replace(/\b(?:cookie|set-cookie|api[_ -]?key|access[_ -]?token|refresh[_ -]?token|secret)\s*[:=]\s*[^\s,;]+/gi, (match) => `${match.split(/[:=]/, 1)[0]}=[redacted]`)
-        .replace(/(["'](?:authorization|cookie|api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret)["']\s*:\s*)["'][^"']*["']/gi, "$1\"[redacted]\"")
-        .replace(/Bearer\s+[A-Za-z0-9._~+\/-]+/gi, "Bearer [redacted]")
-        .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[redacted]")
-        .replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 2_000) || fallback;
+    return safeProviderDiagnostic(value, fallback);
 }
 function piAssistantProviderError(message) {
     const diagnostic = [...(Array.isArray(message.diagnostics) ? message.diagnostics : [])]
@@ -1048,8 +1066,16 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
     commandArgs.push(...extensionArgs);
     let probedModel = null;
     if (productionSpawn) {
-        // 隔离探测用户自己的 Pi home（无 PI_CODING_AGENT_DIR），再把 15% reserve 写到工作区项目设置。
-        probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, childEnv, spawn, dependencies.piRpcClientOptions);
+        try {
+            // Isolated probes must share the same prerequisite contract as the
+            // session handshake, so a cold-start timeout can use bounded recovery.
+            probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, childEnv, spawn, dependencies.piRpcClientOptions);
+        }
+        catch (error) {
+            if (error instanceof RuntimePrerequisiteError)
+                throw error;
+            throw new RuntimePrerequisiteError(classifyRuntimePrerequisite("pi", error, command));
+        }
         writeOwnedPiSettings(input.workspaceDir, calculatePiCompactionSettings(probedModel.contextWindow));
     }
     const child = spawn(command, commandArgs, {
@@ -1119,6 +1145,7 @@ export function createNativeRuntimeAdapter(id, dependencies = {}) {
             ? dependencies.codexCommand ?? dependencies.env?.LARKIN_CODEX_COMMAND ?? "codex"
             : dependencies.claudeCommand ?? dependencies.env?.LARKIN_CLAUDE_COMMAND ?? "claude";
     const codexCommand = dependencies.codexCommand ?? dependencies.env?.LARKIN_CODEX_COMMAND ?? "codex";
+    const runPiInitialization = createInitializationLimiter(PI_INITIALIZATION_CONCURRENCY);
     let codexUpdateAttempt = null;
     let codexUpdateAttempted = false;
     const runCodexUpdate = () => new Promise((resolve) => {
@@ -1217,9 +1244,9 @@ export function createNativeRuntimeAdapter(id, dependencies = {}) {
                     throw new RuntimePrerequisiteError(readiness);
             }
             if (id === "pi") {
-                return new PiSession(await (dependencies.createPiSession
+                return runPiInitialization(async () => new PiSession(await (dependencies.createPiSession
                     ? dependencies.createPiSession(input)
-                    : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn, productionSpawn)));
+                    : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn, productionSpawn))));
             }
             if (id === "codex") {
                 const codexInput = dependencies.codexModelOverride?.trim()

package/dist/runtime/runtime-host.cjs

@@ -1640,38 +1640,45 @@ function createRuntimeHost(options) {
     const ensureSession = async (agent) => {
         if (agent.disabledReason)
             throw new Error(agent.disabledReason);
+        if (agent.stopped)
+            throw new Error("runtime Agent is stopped");
         if (agent.session)
             return agent.session;
         if (agent.starting)
             return agent.starting;
-        const probeEnv = runtimeEnv(agent.config);
-        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: { 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" };
-        if (!agent.authFailureActive)
-            agent.readiness = readiness;
-        if (readiness.state !== "ready")
-            throw new runtime_readiness_js_1.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: (0, agent_cli_capabilities_js_1.agentCliPromptCapabilities)("larkin"), previousSession: agent.previousSession,
-        });
-        const generation = ++agent.generation;
         let completedSession = null;
-        const sessionEnv = runtimeEnv(agent.config, `${agent.launchId}:${generation}`);
-        agent.starting = 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: agent.config.sessionId || null, standingPrompt,
-            env: sessionEnv,
-        }).then((session) => {
+        agent.starting = (async () => {
+            const probeEnv = runtimeEnv(agent.config);
+            await assertOfficialCliReady(agent.config, probeEnv);
+            if (agent.stopped)
+                throw new Error("runtime Agent is stopped");
+            const 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" };
+            if (!agent.authFailureActive)
+                agent.readiness = readiness;
+            if (readiness.state !== "ready")
+                throw new runtime_readiness_js_1.RuntimePrerequisiteError(readiness);
+            if (agent.stopped)
+                throw new Error("runtime Agent is stopped");
+            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: (0, agent_cli_capabilities_js_1.agentCliPromptCapabilities)("larkin"), previousSession: agent.previousSession,
+            });
+            const generation = ++agent.generation;
+            const sessionEnv = runtimeEnv(agent.config, `${agent.launchId}:${generation}`);
+            const session = 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: agent.config.sessionId || null, standingPrompt,
+                env: sessionEnv,
+            });
             completedSession = session;
             if (agent.stopped || generation !== agent.generation) {
-                void session.close("stale creation");
+                await session.close("stale creation");
                 throw new Error("stale runtime session creation");
             }
             agent.session = session;
@@ -1691,7 +1698,7 @@ function createRuntimeHost(options) {
             agent.stabilityTimer = setTimeout(() => markSessionStable(agent, session), retryPolicy.stableWindowMs);
             agent.stabilityTimer.unref?.();
             return session;
-        }).finally(() => {
+        })().finally(() => {
             agent.starting = null;
             if (completedSession && !agent.session && !agent.stopped) {
                 scheduleRecreate(agent, agent.recreateReason || "runtime closed during session initialization");
@@ -2329,6 +2336,8 @@ function createRuntimeHost(options) {
                 emitConsumed(agent, [...startupConsumed, ...persist(agent)]);
                 try {
                     await ensureSession(agent);
+                    if (agent.stopped)
+                        return;
                     reconcileSubagentLedger(agent, { forceMissing: true, missingReason: "runtime restarted" });
                     enqueueUndeliveredTerminalWakes(agent);
                     await recoverStalePiCompaction(agent);
@@ -2336,10 +2345,14 @@ function createRuntimeHost(options) {
                     const proactive = startupSession ? proactivelyCompactPiAtIdle(agent, startupSession) : null;
                     if (proactive)
                         await proactive;
+                    if (agent.stopped)
+                        return;
                     activeCount += 1;
                     await retryPending(agent);
                 }
                 catch (error) {
+                    if (agent.stopped)
+                        return;
                     const reason = error instanceof Error ? error.message : String(error);
                     const transient = error instanceof runtime_readiness_js_1.RuntimePrerequisiteError && error.readiness.state === "unavailable";
                     agent.disabledReason = transient ? null : reason;
@@ -2353,6 +2366,8 @@ function createRuntimeHost(options) {
                     emit({ type: "agent-status", agentId: config.agentId, status: "error", error: reason,
                         ...(error instanceof runtime_readiness_js_1.RuntimePrerequisiteError ? { readiness: error.readiness } : {}) });
                 }
+                if (agent.stopped)
+                    return;
                 const visibleQuarantines = startupQuarantined.filter(({ record }) => agent.records.get(record.deliveryId)?.status === "error");
                 for (const { record, code } of visibleQuarantines)
                     emit({ type: "delivery", agentId: config.agentId,
@@ -2447,6 +2462,7 @@ function createRuntimeHost(options) {
             if (!agent)
                 return;
             agent.stopped = true;
+            const starting = agent.starting;
             if (agent.poller)
                 clearInterval(agent.poller);
             if (agent.retryTimer)
@@ -2460,6 +2476,10 @@ function createRuntimeHost(options) {
             if (agent.busy)
                 await agent.session?.cancel(reason);
             await agent.session?.close(reason);
+            // A queued Pi initializer cannot be cancelled through the public adapter
+            // contract. Drain it before removing the Agent; ensureSession sees stopped
+            // and closes any session created after this point.
+            await starting?.catch(() => { });
             managed.delete(agentId);
             emit({ type: "agent-status", agentId, status: "inactive" });
         },

package/dist/runtime/runtime-host.mjs

@@ -1631,38 +1631,45 @@ export function createRuntimeHost(options) {
     const ensureSession = async (agent) => {
         if (agent.disabledReason)
             throw new Error(agent.disabledReason);
+        if (agent.stopped)
+            throw new Error("runtime Agent is stopped");
         if (agent.session)
             return agent.session;
         if (agent.starting)
             return agent.starting;
-        const probeEnv = runtimeEnv(agent.config);
-        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: { 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" };
-        if (!agent.authFailureActive)
-            agent.readiness = readiness;
-        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"), previousSession: agent.previousSession,
-        });
-        const generation = ++agent.generation;
         let completedSession = null;
-        const sessionEnv = runtimeEnv(agent.config, `${agent.launchId}:${generation}`);
-        agent.starting = 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: agent.config.sessionId || null, standingPrompt,
-            env: sessionEnv,
-        }).then((session) => {
+        agent.starting = (async () => {
+            const probeEnv = runtimeEnv(agent.config);
+            await assertOfficialCliReady(agent.config, probeEnv);
+            if (agent.stopped)
+                throw new Error("runtime Agent is stopped");
+            const 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" };
+            if (!agent.authFailureActive)
+                agent.readiness = readiness;
+            if (readiness.state !== "ready")
+                throw new RuntimePrerequisiteError(readiness);
+            if (agent.stopped)
+                throw new Error("runtime Agent is stopped");
+            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"), previousSession: agent.previousSession,
+            });
+            const generation = ++agent.generation;
+            const sessionEnv = runtimeEnv(agent.config, `${agent.launchId}:${generation}`);
+            const session = 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: agent.config.sessionId || null, standingPrompt,
+                env: sessionEnv,
+            });
             completedSession = session;
             if (agent.stopped || generation !== agent.generation) {
-                void session.close("stale creation");
+                await session.close("stale creation");
                 throw new Error("stale runtime session creation");
             }
             agent.session = session;
@@ -1682,7 +1689,7 @@ export function createRuntimeHost(options) {
             agent.stabilityTimer = setTimeout(() => markSessionStable(agent, session), retryPolicy.stableWindowMs);
             agent.stabilityTimer.unref?.();
             return session;
-        }).finally(() => {
+        })().finally(() => {
             agent.starting = null;
             if (completedSession && !agent.session && !agent.stopped) {
                 scheduleRecreate(agent, agent.recreateReason || "runtime closed during session initialization");
@@ -2320,6 +2327,8 @@ export function createRuntimeHost(options) {
                 emitConsumed(agent, [...startupConsumed, ...persist(agent)]);
                 try {
                     await ensureSession(agent);
+                    if (agent.stopped)
+                        return;
                     reconcileSubagentLedger(agent, { forceMissing: true, missingReason: "runtime restarted" });
                     enqueueUndeliveredTerminalWakes(agent);
                     await recoverStalePiCompaction(agent);
@@ -2327,10 +2336,14 @@ export function createRuntimeHost(options) {
                     const proactive = startupSession ? proactivelyCompactPiAtIdle(agent, startupSession) : null;
                     if (proactive)
                         await proactive;
+                    if (agent.stopped)
+                        return;
                     activeCount += 1;
                     await retryPending(agent);
                 }
                 catch (error) {
+                    if (agent.stopped)
+                        return;
                     const reason = error instanceof Error ? error.message : String(error);
                     const transient = error instanceof RuntimePrerequisiteError && error.readiness.state === "unavailable";
                     agent.disabledReason = transient ? null : reason;
@@ -2344,6 +2357,8 @@ export function createRuntimeHost(options) {
                     emit({ type: "agent-status", agentId: config.agentId, status: "error", error: reason,
                         ...(error instanceof RuntimePrerequisiteError ? { readiness: error.readiness } : {}) });
                 }
+                if (agent.stopped)
+                    return;
                 const visibleQuarantines = startupQuarantined.filter(({ record }) => agent.records.get(record.deliveryId)?.status === "error");
                 for (const { record, code } of visibleQuarantines)
                     emit({ type: "delivery", agentId: config.agentId,
@@ -2438,6 +2453,7 @@ export function createRuntimeHost(options) {
             if (!agent)
                 return;
             agent.stopped = true;
+            const starting = agent.starting;
             if (agent.poller)
                 clearInterval(agent.poller);
             if (agent.retryTimer)
@@ -2451,6 +2467,10 @@ export function createRuntimeHost(options) {
             if (agent.busy)
                 await agent.session?.cancel(reason);
             await agent.session?.close(reason);
+            // A queued Pi initializer cannot be cancelled through the public adapter
+            // contract. Drain it before removing the Agent; ensureSession sees stopped
+            // and closes any session created after this point.
+            await starting?.catch(() => { });
             managed.delete(agentId);
             emit({ type: "agent-status", agentId, status: "inactive" });
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkin",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [