larkin 0.4.28 → 0.5.0

package/dist/app/agent-cli.mjs

@@ -12,6 +12,8 @@ import { createReminderRoutes } from "../agent/reminder-routes.mjs";
 import { InteractionStateMachine } from "../agent/interaction-state-machine.mjs";
 import { issueCallbackProbe, readCallbackCapability } from "../platform/callback-capability.mjs";
 import { requestAgentUpsert } from "./local-control.mjs";
+import { isUserRuntime } from "../runtime/user-runtime.mjs";
+import { resolveRuntimeExecutable, runtimeInstallNextAction } from "../runtime/runtime-readiness.mjs";
 export { AGENT_CLI_CAPABILITIES } from "../agent/agent-cli-capabilities.mjs";
 import { AGENT_CLI_CAPABILITIES } from "../agent/agent-cli-capabilities.mjs";
 import { CONFIG_CLI_USAGE, CONFIG_CLI_VALUES } from "../agent/config-cli-contract.mjs";
@@ -157,7 +159,7 @@ function agentConfigRequest(argv, env, config, agent, dependencies) {
     const target = config.agents[targetId];
     if (!target)
         throw new Error(`Agent 不存在：${targetId}；运行 larkin config show --json 查看可用 Agent`);
-    const currentDirectory = (runtime = larkinConfig.toUserRuntime(target.runtime, target.piDistribution)) => (dependencies.modelDirectory ?? ((input) => discoverRuntimeModelDirectorySync(input, env)))({
+    const currentDirectory = (runtime = larkinConfig.toUserRuntime(target.runtime)) => (dependencies.modelDirectory ?? ((input) => discoverRuntimeModelDirectorySync(input, env)))({
         agentId: target.agentId, cwd: target.workspaceDir, runtime,
     });
     if (operation === "show") {
@@ -173,6 +175,16 @@ function agentConfigRequest(argv, env, config, agent, dependencies) {
         const runtime = options.positionals[0];
         if (!runtime || options.positionals.length > 1)
             throw new Error("用法: larkin config runtime <runtime> [--model <model>] [--agent <App ID>]");
+        if (!isUserRuntime(runtime))
+            throw new Error(`未知 runtime：${runtime}`);
+        const command = runtime === "pi"
+            ? env.LARKIN_PI_COMMAND || "pi"
+            : runtime === "codex"
+                ? env.LARKIN_CODEX_COMMAND || "codex"
+                : env.LARKIN_CLAUDE_COMMAND || "claude";
+        if (!resolveRuntimeExecutable(command, env)) {
+            throw new Error(`${runtime} is not installed；${runtimeInstallNextAction(runtime)}`);
+        }
         const model = options.values.get("--model");
         if (model && !currentDirectory(runtime).some((item) => item.id === model))
             throw new Error(`model 不在 ${runtime} 当前目录中：${model}`);
@@ -594,7 +606,7 @@ export function runAgentCli(argv, env = process.env, dependencies = {}) {
                 openId: identity?.open_id ?? identity?.openId ?? null,
                 avatarUrl: identity?.avatar_url ?? identity?.avatarUrl ?? null,
                 runtime: agent.runtime,
-                runtimeOption: larkinConfig.toUserRuntime(agent.runtime, agent.piDistribution),
+                runtimeOption: larkinConfig.toUserRuntime(agent.runtime),
                 model: agent.model, reasoningEffort: agent.effort ?? null,
                 createdAt: agent.createdAt ?? "1970-01-01T00:00:00.000Z",
             });

package/dist/app/agent-config.mjs

@@ -11,9 +11,8 @@ import { isChannelReconnecting, projectAgentReadiness } from "./agent-readiness.
 import { requestAgentUpsert } from "./local-control.mjs";
 import * as larkinConfig from "../platform/config.mjs";
 import { managedOfficialLarkCli } from "./agent-lark-cli-workspace.mjs";
-import { assertBuiltinPiAgentDirectory, ownedPiCatalogAgentDir, piAgentDirectory, piCatalogCommandSpec } from "../runtime/pi-provider-config.mjs";
-import { RUNTIME_OPTIONS, fromUserRuntime, isUserRuntime, piCatalogDistributionForUserRuntime, toUserRuntime } from "../runtime/user-runtime.mjs";
-import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
+import { RUNTIME_OPTIONS, fromUserRuntime, isUserRuntime, toUserRuntime } from "../runtime/user-runtime.mjs";
+import { resolveRuntimeExecutable, runtimeInstallNextAction } from "../runtime/runtime-readiness.mjs";
 function safeDocumentCommentCapabilities(configDir, profile) {
     try {
         return {
@@ -52,15 +51,15 @@ const die = (message) => {
         console.error("  下一步: larkin config --help");
     process.exit(1);
 };
-if (!kind || !["agents", "model", "runtime", "effort", "pi-distribution", "chats", "config"].includes(kind)) {
-    die("用法: larkin agents | larkin config <show|mention|apply> | larkin model [<id>] | larkin runtime [<id>] [--model <id>] | larkin pi-distribution [show|builtin|external] | larkin effort [<level>|clear] | larkin chats [free|strict <oc_id>]");
+if (!kind || !["agents", "model", "runtime", "effort", "chats", "config"].includes(kind)) {
+    die("用法: larkin agents | larkin config <show|mention|apply> | larkin model [<id>] | larkin runtime [<id>] [--model <id>] | larkin effort [<level>|clear] | larkin chats [free|strict <oc_id>]");
 }
 const allowedValueFlags = {
     agents: new Set(), model: new Set(["--agent"]), runtime: new Set(["--agent", "--model"]),
-    effort: new Set(["--agent"]), "pi-distribution": new Set(["--agent", "--snapshot"]), chats: new Set(["--agent"]), config: new Set(["--agent", "--chat"]),
+    effort: new Set(["--agent"]), chats: new Set(["--agent"]), config: new Set(["--agent", "--chat"]),
 };
 const allowedBooleanFlags = {
-    agents: new Set(["--json"]), model: new Set(), runtime: new Set(), effort: new Set(), "pi-distribution": new Set(["--import-external-profile"]), chats: new Set(), config: new Set(["--json"]),
+    agents: new Set(["--json"]), model: new Set(), runtime: new Set(), effort: new Set(), chats: new Set(), config: new Set(["--json"]),
 };
 const parsedValues = new Map();
 const parsedBooleans = new Set();
@@ -94,7 +93,6 @@ const flagAgent = parsedValues.get("--agent");
 const flagModel = parsedValues.get("--model");
 const flagChat = parsedValues.get("--chat");
 const flagJson = parsedBooleans.has("--json");
-const importExternalProfile = parsedBooleans.has("--import-external-profile");
 const value = positionals[0];
 function assertOnlyFlags(valueFlags, booleanFlags = []) {
     const allowedValues = new Set(valueFlags);
@@ -126,11 +124,6 @@ else if (kind === "effort") {
     if (positionals.length > 1)
         die("用法: larkin effort [<level>|clear|default] [--agent <App ID>]");
 }
-else if (kind === "pi-distribution") {
-    assertOnlyFlags(["--agent", "--snapshot"], ["--import-external-profile"]);
-    if (positionals.length > 1)
-        die("用法: larkin pi-distribution [show|builtin|external] [--agent <App ID>] [--snapshot <private-file>]");
-}
 else if (kind === "chats") {
     assertOnlyFlags(["--agent"]);
     if (![0, 2].includes(positionals.length))
@@ -178,21 +171,6 @@ const loaded = (() => {
 const { configDir, file, config } = loaded;
 if (!fs.existsSync(file))
     die("未找到 Larkin 配置，请运行 larkin setup");
-const snapshotFile = parsedValues.get("--snapshot");
-if (kind === "pi-distribution" && value === "rollback") {
-    if (importExternalProfile)
-        die("--import-external-profile 只允许与 builtin 一起使用");
-    if (!snapshotFile || flagAgent || positionals.length !== 1)
-        die("用法: larkin pi-distribution rollback --snapshot <private-file>");
-    try {
-        const result = larkinConfig.rollbackConfig(process.env, snapshotFile);
-        say(JSON.stringify({ ok: true, rolledBackAgent: result.agentId, revision: result.revision }));
-    }
-    catch (error) {
-        die(`回滚失败：${error instanceof Error ? error.message : String(error)}`);
-    }
-    process.exit(0);
-}
 if (kind === "agents") {
     const list = Object.values(config.agents || {});
     const daemon = readProcessState(config.larkinHome).daemon;
@@ -224,7 +202,7 @@ if (kind === "agents") {
                 agent_id: agent.agentId,
                 name: agent.name,
                 runtime: agent.runtime,
-                runtimeOption: toUserRuntime(agent.runtime, agent.piDistribution),
+                runtimeOption: toUserRuntime(agent.runtime),
                 model: effectiveModel,
                 document_comment: {
                     event: "drive.notice.comment_add_v1",
@@ -295,7 +273,7 @@ if (kind === "agents") {
         say(`  ${agent.name}${agent.name === config.activeAgent ? " [active]" : ""}`);
         const effectiveModel = status?.session?.runtime === agent.runtime && status.session.model ? status.session.model : agent.model;
         const effectiveEffort = status?.session?.runtime === agent.runtime && status.session.reasoningEffort ? status.session.reasoningEffort : agent.effort;
-        say(`    runtime=${toUserRuntime(agent.runtime, agent.piDistribution)}  model=${effectiveModel}${effectiveModel !== agent.model ? `  stored=${agent.model}` : ""}${effectiveEffort ? `  effort=${effectiveEffort}` : ""}`);
+        say(`    runtime=${toUserRuntime(agent.runtime)}  model=${effectiveModel}${effectiveModel !== agent.model ? `  stored=${agent.model}` : ""}${effectiveEffort ? `  effort=${effectiveEffort}` : ""}`);
         if (status?.runtimeReadiness) {
             const current = projectedReadiness.readiness.runtime_ready;
             const state = status.runtimeReadiness.state === "ready" && !current ? "unavailable" : status.runtimeReadiness.state || "incompatible";
@@ -429,7 +407,7 @@ if (!key) {
         say(`共 ${keys.length} 个 agent（用 --agent <appId> 查看/修改指定一个）:`);
         for (const candidate of keys) {
             const item = config.agents[candidate];
-            say(`  ${candidate}${candidate === config.activeAgent ? " [active]" : ""}  runtime=${toUserRuntime(item.runtime, item.piDistribution)}  model=${item.model}`);
+            say(`  ${candidate}${candidate === config.activeAgent ? " [active]" : ""}  runtime=${toUserRuntime(item.runtime)}  model=${item.model}`);
         }
         process.exit(0);
     }
@@ -437,47 +415,21 @@ if (!key) {
 }
 const selectedKey = key;
 const agent = config.agents[selectedKey];
-if (kind === "pi-distribution") {
-    traceProcessBoundary(process.env, "agent-config:pi-distribution-loaded", { configDir, agentId: selectedKey, targetDir: piAgentDirectory(configDir, selectedKey), requested: value || "show", importExternalProfile });
-    const requested = value || "show";
-    if (importExternalProfile && requested !== "builtin")
-        die("--import-external-profile 只允许与 builtin 一起使用");
-    if (requested === "show") {
-        say(JSON.stringify({
-            agentId: selectedKey,
-            runtime: agent.runtime,
-            runtimeOption: toUserRuntime(agent.runtime, agent.piDistribution),
-            piDistribution: agent.piDistribution ?? "external",
-        }));
-        process.exit(0);
-    }
-    if (requested !== "builtin" && requested !== "external")
-        die("Pi distribution 只允许 show/builtin/external");
-    if (agent.runtime !== "pi")
-        die(`Agent ${selectedKey} 不是 Pi runtime`);
-    if (!snapshotFile)
-        die("修改 Pi distribution 必须提供 --snapshot <private-file>");
-    if (requested === "builtin" && !importExternalProfile) {
-        try {
-            assertBuiltinPiAgentDirectory(piAgentDirectory(configDir, selectedKey));
-        }
-        catch {
-            die("内置 Pi provider 尚未为该 Agent 配置；请先运行 larkin setup 完成内置 Pi provider 配置，或使用 --import-external-profile");
-        }
-    }
-    try {
-        const result = larkinConfig.mutateConfig(process.env, { kind: "set-agent-pi-distribution", agentId: selectedKey, distribution: requested }, { kind: "user" }, {
-            snapshotFile: snapshotFile, ...(importExternalProfile ? { importExternalProfile: true } : {}),
-        });
-        traceProcessBoundary(process.env, "agent-config:pi-distribution-persisted", { configDir, agentId: selectedKey, targetDir: piAgentDirectory(configDir, selectedKey), requested, applyState: result.applyState });
-        say(JSON.stringify({ ok: true, agentId: selectedKey, piDistribution: requested, revision: result.revision, applyState: result.applyState }));
+function runtimeExecutableName(runtime) {
+    if (runtime === "pi")
+        return process.env.LARKIN_PI_COMMAND || "pi";
+    if (runtime === "codex")
+        return process.env.LARKIN_CODEX_COMMAND || "codex";
+    return process.env.LARKIN_CLAUDE_COMMAND || "claude";
+}
+if (kind === "runtime" && value) {
+    if (!isUserRuntime(value)) {
+        console.error(`✗ 未知 runtime：${value}。合法值: ${RUNTIME_OPTIONS.join(", ")}`);
+        process.exit(1);
     }
-    catch (error) {
-        if (importExternalProfile)
-            die("Pi external profile import failed; no secret or private path was disclosed");
-        die(`Pi distribution 修改失败：${error instanceof Error ? error.message : String(error)}`);
+    if (!resolveRuntimeExecutable(runtimeExecutableName(value), process.env)) {
+        die(`${value} is not installed；${runtimeInstallNextAction(value)}`);
     }
-    process.exit(0);
 }
 const catalog = larkinConfig.loadRuntimeModels();
 if ((["model", "effort"].includes(kind || "") && agent.runtime === "codex") || (kind === "runtime" && value === "codex")) {
@@ -499,28 +451,22 @@ if ((["model", "effort"].includes(kind || "") && agent.runtime === "claude") ||
     }
 }
 let piCatalog = null;
-const userRuntime = toUserRuntime(agent.runtime, agent.piDistribution);
-const catalogUserRuntime = kind === "runtime" && (value === "pi" || value === "builtin-pi")
-    ? value
-    : userRuntime;
+const userRuntime = toUserRuntime(agent.runtime);
 if ((kind === "model" || kind === "effort" || kind === "runtime") && !value) {
     say(`agent=${selectedKey}  runtime=${userRuntime}  model=${agent.model}`);
 }
 const needsLivePiCatalog = (["model", "effort"].includes(kind) && agent.runtime === "pi")
-    || (kind === "runtime" && (value === "pi" || value === "builtin-pi") && Boolean(flagModel));
+    || (kind === "runtime" && value === "pi" && Boolean(flagModel));
 if (needsLivePiCatalog) {
     try {
-        const catalogCommand = piCatalogCommandSpec(piCatalogDistributionForUserRuntime(catalogUserRuntime), process.env);
         piCatalog = await discoverPiModelCatalog({
             cwd: String(agent.workspaceDir),
-            agentDir: ownedPiCatalogAgentDir(configDir, selectedKey),
-            command: catalogCommand.command,
-            commandArgs: catalogCommand.commandArgs,
+            command: process.env.LARKIN_PI_COMMAND || "pi",
             env: process.env,
         });
     }
     catch (error) {
-        die(`Pi 模型目录加载失败：${error instanceof Error ? error.message : String(error)}。请先用官方 pi 登录或检查该 Agent 的隔离 provider 目录。`);
+        die(`Pi 模型目录加载失败：${error instanceof Error ? error.message : String(error)}。请先运行官方 pi 登录流程。`);
     }
     if (!piCatalog)
         die("Pi 模型目录加载失败");
@@ -693,10 +639,6 @@ else {
         say("\n切换: larkin runtime <id> [--model <id>]");
         process.exit(0);
     }
-    if (!isUserRuntime(value)) {
-        console.error(`✗ "${value}" 不是合法 runtime。合法值: ${RUNTIME_OPTIONS.join(", ")}`);
-        process.exit(1);
-    }
     let model = flagModel;
     if (model) {
         const items = catalog[catalogRuntimeKey(value)];

package/dist/app/binary-entry.mjs

@@ -49,26 +49,6 @@ async function dispatchInternal(mode, rest) {
         case "lark-channel-secret":
             await (await import("./lark-channel-secret.mjs")).main(process.env);
             return;
-        case "pi-rpc": {
-            const { prepareBuiltinPiPackageAssets } = await import("../runtime/builtin-pi-assets.mjs");
-            prepareBuiltinPiPackageAssets();
-            process.title = "pi-rpc";
-            process.env.PI_CODING_AGENT = "true";
-            process.emitWarning = (() => { });
-            // The Pi package's normal Bun CLI registers OAuth loaders before starting.
-            // Larkin invokes its RPC entrypoint directly, so do the same here; otherwise
-            // an OAuth-backed compact falls back to a dynamic module import unavailable in
-            // a compiled standalone binary.
-            const { registerBunOAuthFlows } = await import("@earendil-works/pi-ai/bun-oauth");
-            registerBunOAuthFlows();
-            const { main: piMain } = await import("@earendil-works/pi-coding-agent");
-            const { invokeBuiltinPiRpc } = await import("../runtime/pi-inline-extensions.mjs");
-            await invokeBuiltinPiRpc(piMain, rest);
-            return;
-        }
-        case "pi-auth":
-            await (await import("./pi-auth-cli.mjs")).main(rest, process.env);
-            return;
         case "telemetry":
             await (await import("./telemetry.mjs")).main(rest, process.env);
             return;

package/dist/app/cli.mjs

@@ -29,11 +29,9 @@ const routes = {
     model: ["agent-config", "model"],
     runtime: ["agent-config", "runtime"],
     effort: ["agent-config", "effort"],
-    "pi-distribution": ["agent-config", "pi-distribution"],
     chats: ["agent-config", "chats"],
     config: ["agent-config", "config"],
     session: ["session-cli"],
-    "pi-auth": ["pi-auth"],
     telemetry: ["telemetry"],
 };
 const runtimeAgentAuthority = typeof process.env.LARKIN_AGENT_ID === "string"
@@ -49,8 +47,8 @@ if (runtimeAgentAuthority && command === "comment")
 const commandHelp = {
     start: `Usage: larkin start [--agent <App ID> | --agents <App ID,...>]
 Start one foreground supervisor for the daemon and local dashboard, or reuse it.`,
-    setup: `Usage: larkin setup [--tenant feishu|lark] [--runtime <builtin-pi|pi|codex|claude>] [--provider <id> --api-key <key>]
-Run setup to create or connect a bot, configure its Agent, and attach it. Choose Feishu or Lark before the authorization QR (--tenant; default feishu). Interactive terminals keep the guided flow; Agent-driven (non-TTY) runs default to builtin-pi and need --provider/--api-key (or --runtime pi).`,
+    setup: `Usage: larkin setup [--tenant feishu|lark] [--runtime <pi|codex|claude>]
+Run setup to create or connect a bot, configure its Agent, and attach it. Choose Feishu or Lark before the authorization QR (--tenant; default feishu). Interactive terminals list pi, Codex, and Claude Code with installed / not installed status. Non-TTY runs require --runtime and fail if that executable is missing.`,
     status: `Usage: larkin status [--json]
 Show Agent configuration, bot identity, credentials, and connection status. Use --json for readiness automation.`,
     agents: `Usage: larkin agents [--json]
@@ -58,10 +56,7 @@ List every configured Agent and its current local status. Use --json for daemon/
     model: `Usage: larkin model [<model>] [--agent <App ID>]
 Show or change an Agent model.`,
     runtime: `Usage: larkin runtime [<runtime>] [--agent <App ID>] [--model <model>]
-Show or change an Agent runtime. User-facing ids: pi | builtin-pi | codex | claude.`,
-    "pi-distribution": `Usage: larkin pi-distribution [show|builtin|external] [--agent <App ID>] [--snapshot <private-file>] [--import-external-profile]
-       larkin pi-distribution rollback --snapshot <private-file>
-Show or change one Pi Agent distribution. builtin requires configured provider state, or explicitly imports the external Pi 0.84.2 profile with --import-external-profile; all changes support config-lock CAS rollback.`,
+Show or change an Agent runtime. User-facing ids: pi | codex | claude. A missing executable is rejected and does not write config.`,
     effort: `Usage: larkin effort [<level>|clear|default] [--agent <App ID>]
 Show or change an Agent reasoning effort; clear/default restores the Runtime default.`,
     chats: `Usage: larkin chats [--agent <App ID>]
@@ -83,9 +78,6 @@ Credentials, internal paths, serverId, activeAgent, and raw config are never exp
     session: `Usage: larkin session reset --agent <App ID> --json [--wait-ready <seconds>]
        larkin session recover --agent <App ID> --reason context-overflow --json [--wait-ready <seconds>]
 Reset replaces one idle, zero-backlog Runtime session. Recover is an explicit operator-only context-window recovery that preserves and replays canonical Inbox deliveries.`,
-    "pi-auth": `Usage: larkin pi-auth status [--agent <App ID>] [--json]
-       larkin pi-auth logout <provider> [--agent <App ID>]
-Show non-sensitive official Pi credential metadata or remove one target provider credential.`,
     comment: `Usage: larkin comment reply --message-id <doc_comment_message_id> --text '<reply>' --json
 Reply as the Runtime-bound Bot to the exact cloud-document comment locator supplied by canonical Inbox. Retrying the same body is idempotent; a different body appends a follow-up reply to the same comment.`,
     telemetry: `Usage: larkin telemetry <status|export|import|flush>
@@ -110,9 +102,10 @@ if (!runtimeAgentCommand && command === "config" && ["runtime", "model", "effort
 // At a user terminal, unregistered non-flag commands keep the legacy lark-cli passthrough.
 // Inside an Agent Runtime, unknown Feishu command groups enter the same Larkin-owned
 // identity and freshness AOP before delegation to the verified global official CLI.
+const retiredPublicCommands = new Set(["pi-auth", "pi-distribution"]);
 const wantsHelp = command === "help" || command === "--help" || command === "-h"
     || (!runtimeAgentAuthority && command.startsWith("-"));
-if (!routes[command] && !wantsHelp) {
+if (!routes[command] && !wantsHelp && !retiredPublicCommands.has(command)) {
     routes[command] = runtimeAgentAuthority ? ["lark-cli", command] : ["lark", command];
 }
 if (!routes[command]) {
@@ -130,7 +123,6 @@ Usage: larkin <command>
   config           Inspect effective config/source, edit mention inheritance, or explicitly apply runtime changes
   session reset    Replace one idle, zero-backlog Agent Runtime session for a fresh scenario
   session recover  Explicitly recover a context-overflowed session and replay retained Inbox deliveries
-  pi-auth          Show non-sensitive built-in Pi auth status or logout one provider
   comment reply    Reply to the exact cloud-document comment bound by a polled Inbox message
   telemetry        Inspect, export, import, or flush the durable OpenTelemetry trace queue
   <lark-cli 命令组>  im/docs/wiki/drive 等 lark-cli 命令原样转发，机器人身份已锁定（如 larkin im +chat-list）
@@ -144,7 +136,9 @@ Process persistence is managed externally. larkin start stays in the foreground
 }
 const [mode, ...presetArguments] = routes[command];
 const childSpec = internalCommandSpec(mode, [...presetArguments, ...rest]);
-const child = spawn(childSpec.command, childSpec.args, { stdio: "inherit" });
+const child = spawn(childSpec.command, childSpec.args, {
+    stdio: ["inherit", "inherit", "inherit"],
+});
 // Package-manager bin shims add a wrapper process. Forward terminal signals so the actual command
 // does not become an orphan that keeps the machine lock or Feishu connection.
 const signalForwarders = new Map();

package/dist/app/internal-command.cjs

@@ -24,8 +24,6 @@ exports.INTERNAL_MODES = [
     "setup-bind",
     "grant-scopes",
     "lark-channel-secret",
-    "pi-rpc",
-    "pi-auth",
     "telemetry",
 ];
 exports.PROCESS_COMMAND_TOKENS = Object.freeze({

package/dist/app/internal-command.mjs

@@ -15,8 +15,6 @@ export const INTERNAL_MODES = [
     "setup-bind",
     "grant-scopes",
     "lark-channel-secret",
-    "pi-rpc",
-    "pi-auth",
     "telemetry",
 ];
 export const PROCESS_COMMAND_TOKENS = Object.freeze({

package/dist/app/local-control.mjs

@@ -14,6 +14,7 @@ const WINDOWS_SOCKET_BINDING = { device: "0", inode: "0", owner: "0", changeTime
 const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
 const OPERATION_ID = /^[A-Za-z0-9_-]{8,128}$/;
 const AUTHORIZATION = /^[A-Za-z0-9_-]{43,128}$/;
+const CONFIG_SIGNATURE = /^sha256:[a-f0-9]{64}$/;
 const UNIX_SOCKET_PATH_MAX_BYTES = process.platform === "darwin" ? 103 : 107;
 function recoveryErrorText(code) {
     switch (code) {
@@ -159,9 +160,13 @@ function parseRequest(line) {
     if (value.waitReadyMs !== undefined) {
         throw new Error("invalid session reset waitReadyMs");
     }
-    if (Object.keys(value).some((key) => !["operationId", "agentId", "authorization"].includes(key))) {
+    if (Object.keys(value).some((key) => !["operationId", "agentId", "authorization", "expectedSignature"].includes(key))) {
         throw new Error("agent control request 包含未知字段");
     }
+    if (value.expectedSignature !== undefined
+        && (typeof value.expectedSignature !== "string" || !CONFIG_SIGNATURE.test(value.expectedSignature))) {
+        throw new Error("invalid agent upsert expectedSignature");
+    }
     return value;
 }
 function atomicWritePrivateJson(file, value) {
@@ -741,7 +746,11 @@ export function createAgentControlServer({ larkinHome, authorityToken, upsert, r
                         }
                         const execute = async () => {
                             try {
-                                await upsert({ operationId: upsertRequest.operationId, agentId: upsertRequest.agentId });
+                                await upsert({
+                                    operationId: upsertRequest.operationId,
+                                    agentId: upsertRequest.agentId,
+                                    ...(upsertRequest.expectedSignature ? { expectedSignature: upsertRequest.expectedSignature } : {}),
+                                });
                                 return { ok: true, operationId: upsertRequest.operationId, agentId: upsertRequest.agentId };
                             }
                             catch (error) {
@@ -926,7 +935,11 @@ async function requestAgentControl({ larkinHome, timeoutMs = 30_000, request, })
 }
 export async function requestAgentUpsert(input) {
     return requestAgentControl({ larkinHome: input.larkinHome, timeoutMs: input.timeoutMs,
-        request: { operationId: input.operationId ?? crypto.randomUUID(), agentId: input.agentId } });
+        request: {
+            operationId: input.operationId ?? crypto.randomUUID(),
+            agentId: input.agentId,
+            ...(input.expectedSignature ? { expectedSignature: input.expectedSignature } : {}),
+        } });
 }
 export async function requestSessionReset({ larkinHome, agentId, waitReadyMs = 30_000, }) {
     return requestAgentControl({

package/dist/app/runtime-model-directory.mjs

@@ -2,12 +2,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { loadConfig, resolveConfigDir } from "../platform/config.mjs";
 import { discoverClaudeModelCatalog } from "../runtime/claude-model-catalog.mjs";
 import { discoverPiModelCatalog } from "../runtime/pi-model-catalog.mjs";
 import { discoverCodexModelCatalog } from "../runtime/codex-model-catalog.mjs";
-import { ownedPiCatalogAgentDir, piCatalogCommandSpec } from "../runtime/pi-provider-config.mjs";
-import { piCatalogDistributionForUserRuntime } from "../runtime/user-runtime.mjs";
 function readTestModelDirectory(env) {
     const fixture = env?.LARKIN_TEST_RUNTIME_MODEL_DIRECTORY_FILE;
     if (!fixture)
@@ -37,22 +34,11 @@ export async function discoverRuntimeModelDirectory(input) {
             ...catalog.models.map(({ id, label, supportedReasoningEfforts }) => ({ id, label, supportedReasoningEfforts })),
         ];
     }
-    if (input.runtime === "pi" || input.runtime === "builtin-pi") {
+    if (input.runtime === "pi") {
         const env = input.env ?? process.env;
-        const agentId = input.agentId || "";
-        if (!agentId)
-            throw new Error("runtime model directory requires agentId for Pi");
-        const configDir = resolveConfigDir(env);
-        const { config } = loadConfig(env);
-        const agent = config.agents[agentId];
-        if (!agent)
-            throw new Error(`unknown agent: ${agentId}`);
-        const catalogCommand = piCatalogCommandSpec(piCatalogDistributionForUserRuntime(input.runtime), env);
         const catalog = await discoverPiModelCatalog({
             cwd: input.cwd,
-            agentDir: ownedPiCatalogAgentDir(configDir, agentId),
-            command: catalogCommand.command,
-            commandArgs: catalogCommand.commandArgs,
+            command: env.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi",
             env,
         });
         if (!catalog.effectiveModel)

package/dist/app/runtime-process.mjs

@@ -6,22 +6,58 @@ import { ContextPromptBuilder } from "../agent/context-prompt.mjs";
 import { createNativeRuntimeAdapter } from "../runtime/runtime-adapters.mjs";
 import { createRuntimeHost } from "../runtime/runtime-host.mjs";
 import { createAgentStateStore } from "../agent/agent-state-store.mjs";
-import { loadConfig, markConfigApplied, runtimeConfigSignature } from "../platform/config.mjs";
+import { loadConfig, markConfigApplied, runtimeConfigSignature, withConfigMutationLock, withConfigMutationLockAsync, } from "../platform/config.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 import { createAgentControlServer, requestSupervisorAgentUpsert } from "./local-control.mjs";
-import { hydrateRuntimeAgent, syncAgentProfile } from "./runtime-agent-config.mjs";
+import { hydrateRuntimeAgent, syncAgentProfile, } from "./runtime-agent-config.mjs";
 import { loadTelemetryConfig } from "../platform/telemetry-config.mjs";
 import { telemetrySingleton } from "../platform/telemetry-tracing.mjs";
 import { packageVersion } from "../platform/build-info.mjs";
-export function loadAndSyncRuntimeAgent(env, agentId, dependencies = {}) {
+function readRuntimeAgent(env, agentId, expectedSignature) {
     const loaded = loadConfig(env);
     const stored = loaded.config.agents[agentId];
     if (!stored)
         throw new Error(`Agent ${agentId} 不存在于 canonical config`);
+    if (expectedSignature) {
+        const current = runtimeConfigSignature(loaded.config, agentId);
+        if (current !== expectedSignature) {
+            throw new Error("配置在 apply 期间发生变化；未热加载已切换的 Agent");
+        }
+    }
+    return { loaded, stored };
+}
+function hydrateAndSyncRuntimeAgent(env, loaded, stored, dependencies) {
     const agent = hydrateRuntimeAgent(loaded.configDir, stored);
     syncAgentProfile(agent, { ...env, LARKIN_CONFIG_DIR: loaded.configDir }, dependencies);
     return agent;
 }
+export function loadAndSyncRuntimeAgent(env, agentId, dependencies = {}, options = {}) {
+    const snapshot = readRuntimeAgent(env, agentId, options.expectedSignature);
+    options.afterCanonicalValidate?.();
+    if (!options.expectedSignature) {
+        return hydrateAndSyncRuntimeAgent(env, snapshot.loaded, snapshot.stored, dependencies);
+    }
+    return withConfigMutationLock(env, () => {
+        const locked = readRuntimeAgent(env, agentId, options.expectedSignature);
+        return hydrateAndSyncRuntimeAgent(env, locked.loaded, locked.stored, dependencies);
+    });
+}
+/** 签名校验贯穿实际 Host upsert；并发 config mutation 不能热挂载已失效的 snapshot。 */
+export async function applyRuntimeAgentUpsert(env, agentId, dependencies = {}, options = {}, upsert = () => undefined) {
+    const snapshot = readRuntimeAgent(env, agentId, options.expectedSignature);
+    options.afterCanonicalValidate?.();
+    if (!options.expectedSignature) {
+        const agent = hydrateAndSyncRuntimeAgent(env, snapshot.loaded, snapshot.stored, dependencies);
+        await upsert(agent);
+        return agent;
+    }
+    return withConfigMutationLockAsync(env, async () => {
+        const locked = readRuntimeAgent(env, agentId, options.expectedSignature);
+        const agent = hydrateAndSyncRuntimeAgent(env, locked.loaded, locked.stored, dependencies);
+        await upsert(agent);
+        return agent;
+    });
+}
 export async function markConfigAppliedAfterRuntimeReady(env, runningAgents, runtimeReady) {
     await runtimeReady;
     try {
@@ -29,7 +65,6 @@ export async function markConfigAppliedAfterRuntimeReady(env, runningAgents, run
         for (const running of runningAgents) {
             const current = loaded.config.agents[running.agentId];
             if (!current || current.runtime !== running.runtime || current.model !== running.model
-                || (current.piDistribution || "external") !== (running.piDistribution || "external")
                 || (current.effort || null) !== (running.effort || null))
                 continue;
             markConfigApplied(env, running.agentId, runtimeConfigSignature(loaded.config, running.agentId));
@@ -100,10 +135,11 @@ export async function main(env = process.env, overrides = {}) {
         larkinHome: env.LARKIN_HOME,
         authorityToken: env.LARKIN_CONTROL_AUTHORIZATION,
         async upsert(request) {
-            const agent = loadAndSyncRuntimeAgent(env, request.agentId);
+            const agent = await applyRuntimeAgentUpsert(env, request.agentId, {}, {
+                ...(request.expectedSignature ? { expectedSignature: request.expectedSignature } : {}),
+            }, (candidate) => hostShell.upsertAgent(candidate));
             // Only the selected profile is synchronized; active profiles and their directory
             // are never quarantined or rebuilt during hot attach.
-            await hostShell.upsertAgent(agent);
             const tracked = await requestSupervisorAgentUpsert({
                 larkinHome: env.LARKIN_HOME, agentId: agent.agentId, operationId: request.operationId,
             });