larkin 0.5.1 → 0.5.3

package/dist/runtime/pi-subagent-injection.mjs

@@ -7,8 +7,9 @@ import { fileURLToPath } from "node:url";
  *
  * 分发：构建期把 @tintinweb/pi-subagents bundle 成单文件
  * `dist/runtime/pi-subagents.bundle.js`（pi-* 包 external），运行时仅向 external
- * （用户 pi CLI）通过 `pi --extension/-e` 显式注入，不碰用户 ~/.pi 配置。
- * Builtin Pi 直接接收静态 factory，不经过本文件或 Pi 的路径加载器。
+ * （用户 pi CLI）通过 `pi --extension/-e` 显式注入。可只读用户 ~/.pi/agent
+ * 的非密钥设置/扩展元数据以避免重复注册 FATAL；不得读、复制或写 auth.json，
+ * 也不得写入 ~/.pi。
  *
  * 版本门槛：pi-subagents peerDependency 要求 @earendil-works/pi-* >= 0.80.0；
  * external 的 pi 版本低于 0.80 时不注入（降级为无 subagent 能力）。
@@ -184,16 +185,49 @@ export function probeExternalPiVersion(piCommand, env) {
  * 用户 pi 是否已自行安装 pi-subagents（settings.json packages 或包目录）。
  * 已装时 Larkin 不再 -e 注入，避免同名工具（Agent/get_subagent_result/steer_subagent）
  * 重复注册导致 pi 扩展加载 FATAL（pi 对 duplicate tool registration 是硬失败）。
+ *
+ * Owner 边界：只读非密钥兼容信息（settings.json / package 清单 / 扩展源码标记）。
+ * 不得打开或写入用户 Pi home 里的 auth.json，也不得往 ~/.pi 写任何文件。
  */
 const BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
 const SUPERVISED_COMMAND_CAPABILITY = "larkin-pi-supervised-command-v1";
+function assertRegularFile(file) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
+        throw new Error("user Pi path is not a regular file");
+    }
+}
+function readRegularFile(file) {
+    assertRegularFile(file);
+    return fs.readFileSync(file, "utf8");
+}
+function isRealpathInside(root, candidate) {
+    const rootReal = fs.realpathSync(root);
+    const candidateReal = fs.realpathSync(candidate);
+    const prefix = rootReal.endsWith(path.sep) ? rootReal : `${rootReal}${path.sep}`;
+    return candidateReal.startsWith(prefix);
+}
+/** 只读包根内的单链接常规文件；绝对路径、逃逸、符号链接、硬链接一律视为不可验证。 */
+function readContainedPackageEntry(packageRoot, entry) {
+    if (path.isAbsolute(entry))
+        throw new Error("absolute Pi extension entry");
+    const root = path.resolve(packageRoot);
+    const resolved = path.resolve(root, entry);
+    const lexicalPrefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+    if (resolved !== root && !resolved.startsWith(lexicalPrefix))
+        throw new Error("Pi extension entry escaped package root");
+    assertRegularFile(resolved);
+    if (!isRealpathInside(root, resolved))
+        throw new Error("Pi extension entry escaped package root");
+    return fs.readFileSync(resolved, "utf8");
+}
 function userPiSubagentsWaitCapability(env) {
     const agentDir = env.PI_CODING_AGENT_DIR || path.join(env.HOME || process.env.HOME || "", ".pi", "agent");
     try {
         let configured = false;
         const settingsFile = path.join(agentDir, "settings.json");
         if (fs.existsSync(settingsFile)) {
-            const settings = JSON.parse(fs.readFileSync(settingsFile, "utf8"));
+            const settings = JSON.parse(readRegularFile(settingsFile));
             const packages = settings?.packages;
             if (Array.isArray(packages)) {
                 configured = packages.some((entry) => typeof entry === "string" && /pi-subagents/i.test(entry));
@@ -210,7 +244,7 @@ function userPiSubagentsWaitCapability(env) {
             return "absent";
         if (!installedRoot)
             return "unbounded";
-        const packageManifest = JSON.parse(fs.readFileSync(path.join(installedRoot, "package.json"), "utf8"));
+        const packageManifest = JSON.parse(readRegularFile(path.join(installedRoot, "package.json")));
         const extensions = packageManifest.pi?.extensions;
         if (!Array.isArray(extensions) || extensions.length === 0
             || !extensions.every((entry) => typeof entry === "string" && entry.length > 0)) {
@@ -218,20 +252,14 @@ function userPiSubagentsWaitCapability(env) {
         }
         // Pi executes the entries declared by the package manifest. Do not trust a
         // marker in a build artifact when the manifest points Pi at another file.
-        const capabilityFiles = extensions.map((entry) => path.resolve(installedRoot, entry));
-        const hasCapability = capabilityFiles.every((file) => {
-            try {
-                const source = fs.readFileSync(file, "utf8");
-                return source.includes(BOUNDED_WAIT_CAPABILITY) && source.includes(SUPERVISED_COMMAND_CAPABILITY);
-            }
-            catch {
-                return false;
-            }
+        const hasCapability = extensions.every((entry) => {
+            const source = readContainedPackageEntry(installedRoot, entry);
+            return source.includes(BOUNDED_WAIT_CAPABILITY) && source.includes(SUPERVISED_COMMAND_CAPABILITY);
         });
         return hasCapability ? "bounded" : "unbounded";
     }
     catch {
-        // Unreadable user extension state is not safe to treat as bounded.
+        // Unreadable or escaped user extension state is not safe to treat as bounded.
         return "unbounded";
     }
 }

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

@@ -5,7 +5,6 @@ import * as path from "node:path";
 import { createInterface } from "node:readline";
 import { isPiThinkingLevel } from "./pi-model-catalog.mjs";
 import { PiRpcClient } from "./pi-rpc-client.mjs";
-import { recordPiRuntimeArtifactProvenance } from "./pi-artifact-provenance.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 import { resolvePiSubagentExtensionArg } from "./pi-subagent-injection.mjs";
 import { extractCanonicalPiSubagentNotification, ledgerStatusFromPiNotificationStatus, } from "./pi-subagents-notification.mjs";
@@ -13,10 +12,38 @@ 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 { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, MINIMUM_PI_VERSION, calculatePiCompactionSettings, parsePiExecutableVersion, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, writeOwnedPiSettings, } from "./pi-compaction-recovery.mjs";
-function piAgentDirectory(configDir, agentId) {
-    return path.join(path.resolve(configDir), "providers", "pi", agentId);
+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) {
+    const next = { ...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();
@@ -778,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 : [])]
@@ -977,19 +997,12 @@ class PiRpcBackend {
             this.sessionFile = state.sessionFile;
         if (typeof state.sessionId === "string" && state.sessionId)
             this.sessionId = state.sessionId;
-        // Use the live process handshake, not a disk re-read of owned settings.json.
-        // Disk reserveTokens can drift after startup; that must not reject prompt.
-        const handshake = state.compactionCapabilities;
-        if (typeof handshake?.reserveTokens === "number" && typeof handshake?.keepRecentTokens === "number") {
-            assertEffectivePiCompactionSettings({ contextWindow: state.model?.contextWindow, compaction: {
-                    enabled: state.autoCompactionEnabled,
-                    reserveTokens: handshake.reserveTokens,
-                    keepRecentTokens: handshake.keepRecentTokens,
-                } });
-            return;
-        }
-        if (state.autoCompactionEnabled !== true)
-            throw new Error("Pi native compaction must be enabled");
+        // Prompt 只信 live get_state：有 handshake 就必须精确匹配，没有则只要求 compaction 仍开启。
+        verifyPiCapabilities({
+            distribution: "external", version: this.policy.version,
+            contextWindow: state.model?.contextWindow, autoCompactionEnabled: state.autoCompactionEnabled,
+            compactRpc: true, compactionCapabilities: state.compactionCapabilities,
+        });
     }
     getState() { return this.client.request("get_state"); }
     dispose() { return this.client.close(); }
@@ -1017,13 +1030,11 @@ export function resolvePiProcessExtensionArgs(input, resolvers = {}) {
 }
 async function createPiRpcBackend(input, dependencies, spawn, productionSpawn = true) {
     const stateRoot = effectivePiStateDir(input);
-    const mergedEnv = { ...globalThis.process.env, ...dependencies.env, ...input.env, NO_COLOR: "1" };
-    assertNoProjectPiCompactionOverride(input.workspaceDir);
-    const ownedPiDirectory = mergedEnv.LARKIN_CONFIG_DIR
-        ? 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 mergedEnv = stripPiCodingAgentDir({ ...globalThis.process.env, ...dependencies.env, ...input.env, NO_COLOR: "1" });
+    if (mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin")
+        delete mergedEnv.LARKIN_PI_DISTRIBUTION;
+    const projectSettings = projectPiSettingsFile(input.workspaceDir);
+    traceProcessBoundary(mergedEnv, "pi-rpc:child-env", { configDir: mergedEnv.LARKIN_CONFIG_DIR, agentId: input.agentId, targetDir: projectSettings, 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");
@@ -1033,17 +1044,15 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
     const requestedEffort = input.reasoningEffort?.trim() || undefined;
     if (requestedEffort && !isPiThinkingLevel(requestedEffort))
         throw new Error(`Unknown Pi thinking level: ${requestedEffort}`);
-    const args = ["--mode", "rpc", "--session-dir", session.sessionDir, "--append-system-prompt", promptFile,
+    // `--approve` 让 RPC 在无 UI 时仍加载工作区 `.pi/settings.json`（否则 settings.json 会触发 trust gate 并被忽略）。
+    const args = ["--mode", "rpc", "--approve", "--session-dir", session.sessionDir, "--append-system-prompt", promptFile,
         ...(session.sessionFile ? ["--session", session.sessionFile] : []),
         ...(requestedModel ? ["--model", requestedModel] : []),
         ...(requestedEffort ? ["--thinking", requestedEffort] : [])];
-    if (mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin")
-        delete mergedEnv.LARKIN_PI_DISTRIBUTION;
     const command = dependencies.piCommand ?? dependencies.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
     const commandPrefix = dependencies.piCommandArgs ?? [];
     const commandArgs = [...commandPrefix, ...args];
-    mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
-    const childEnv = { ...mergedEnv };
+    const childEnv = stripPiCodingAgentDir(mergedEnv);
     const reportedVersion = productionSpawn
         ? parsePiExecutableVersion(String(spawnSync(command, [...commandPrefix, "--version"], {
             cwd: input.workspaceDir, env: childEnv, encoding: "utf8", timeout: 5_000,
@@ -1057,21 +1066,24 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
     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, childEnv, spawn, dependencies.piRpcClientOptions);
-        writeOwnedPiSettings(ownedPiDirectory, calculatePiCompactionSettings(probedModel.contextWindow));
+        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 artifactEntriesBeforeSpawn = new Set(fs.readdirSync(ownedPiDirectory));
-    const artifactSpawnBoundary = Date.now();
     const child = spawn(command, commandArgs, {
         cwd: input.workspaceDir,
         env: childEnv,
         stdio: ["pipe", "pipe", "pipe"],
     });
-    traceProcessBoundary(mergedEnv, "pi-rpc:child-spawned", { configDir: mergedEnv.LARKIN_CONFIG_DIR, agentId: input.agentId, targetDir: ownedPiDirectory, childPid: child.pid ?? null });
+    traceProcessBoundary(mergedEnv, "pi-rpc:child-spawned", { configDir: mergedEnv.LARKIN_CONFIG_DIR, agentId: input.agentId, targetDir: projectSettings, childPid: child.pid ?? null });
     const client = new PiRpcClient(child, dependencies.piRpcClientOptions);
     try {
         const [state, available] = await Promise.all([
@@ -1086,17 +1098,18 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
                 || 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);
+            const ownedSettings = readOwnedPiSettings(input.workspaceDir);
             assertEffectivePiCompactionSettings({ contextWindow: state.model?.contextWindow, compaction: {
                     enabled: state.autoCompactionEnabled,
                     reserveTokens: ownedSettings.compaction?.reserveTokens,
                     keepRecentTokens: ownedSettings.compaction?.keepRecentTokens,
                 } });
-            const handshake = state.compactionCapabilities;
-            verifyPiCapabilities({ distribution: "external", version: reportedVersion,
+            const policySource = verifyPiCapabilities({
+                distribution: "external", version: reportedVersion,
                 contextWindow: state.model?.contextWindow, autoCompactionEnabled: state.autoCompactionEnabled,
-                reserveTokens: handshake?.reserveTokens, keepRecentTokens: handshake?.keepRecentTokens,
-                compactRpc: true, events: handshake?.events });
+                compactRpc: true, compactionCapabilities: state.compactionCapabilities,
+            });
+            process.stderr.write(`[runtime] Pi compaction policy source=${policySource} agent=${input.agentId} model=${effectiveModel} contextWindow=${state.model?.contextWindow}\n`);
         }
         // 严格对账（Owner 决策）：模型必须来自 pi 的权威可用列表，不做后缀猜测——
         // 配置的模型与 pi 可用列表不符即报错，并在错误里列出可用模型。
@@ -1110,9 +1123,8 @@ 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"}`);
-        recordPiRuntimeArtifactProvenance(ownedPiDirectory, artifactEntriesBeforeSpawn, artifactSpawnBoundary);
         return new PiRpcBackend(client, state, productionSpawn ? {
-            model: effectiveModel, contextWindow: state.model?.contextWindow, ownedPiDirectory,
+            model: effectiveModel, contextWindow: state.model?.contextWindow, version: reportedVersion,
         } : undefined);
     }
     catch (error) {
@@ -1133,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) => {
@@ -1231,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" });
         },