larkin 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.
+
 ## 0.5.1
 
 External pi is accepted at 0.84.2 or newer instead of exactly 0.84.2; 0.5.0 refused newer pi and left every migrated Agent not ready.

package/dist/dashboard/dashboard-config-controller.mjs

@@ -200,7 +200,7 @@ export function createPiModelDirectoryResolver(options = {}) {
             }
         },
         async resolve(input) {
-            const key = [input.agentId, input.cwd, input.agentDir ?? "", input.command ?? "", ...(input.commandArgs ?? [])].join("\u0000");
+            const key = [input.agentId, input.cwd, input.command ?? "", ...(input.commandArgs ?? [])].join("\u0000");
             const started = generationOf(input.agentId);
             pruneCache(cache, (entry) => now() >= entry.expiresAt, 64);
             pruneCache(failures, (entry) => now() >= entry.expiresAt, 64);
@@ -215,7 +215,6 @@ export function createPiModelDirectoryResolver(options = {}) {
                     try {
                         const catalog = await discover({
                             cwd: input.cwd,
-                            ...(input.agentDir ? { agentDir: input.agentDir } : {}),
                             ...(input.command ? { command: input.command } : {}),
                             ...(input.commandArgs ? { commandArgs: input.commandArgs } : {}),
                         });
@@ -424,7 +423,7 @@ export function createDashboardConfigController({ csrfCapability, env = process.
         const agent = config.agents[agentId];
         if (!agent)
             throw new Error("unknown agent");
-        // 外部 `pi --mode rpc` 使用用户自己的 Pi home，不再注入 Larkin 持有的 agentDir。
+        // 外部 `pi --mode rpc` 使用用户自己的 Pi home；catalog 探测不改写子进程 agent 目录。
         return await piModelDirectoryResolver.resolve({
             agentId,
             cwd: agent.workspaceDir,

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/pi-compaction-recovery.cjs

@@ -9,6 +9,7 @@ exports.isPiNativeCompactionRequired = isPiNativeCompactionRequired;
 exports.assertEffectivePiCompactionSettings = assertEffectivePiCompactionSettings;
 exports.hasProjectPiCompactionOverride = hasProjectPiCompactionOverride;
 exports.ensureOwnedPiAgentDirectory = ensureOwnedPiAgentDirectory;
+exports.projectPiSettingsFile = projectPiSettingsFile;
 exports.ownedPiSettings = ownedPiSettings;
 exports.prepareOwnedPiDirectory = prepareOwnedPiDirectory;
 exports.mergeOwnedPiSettings = mergeOwnedPiSettings;
@@ -17,7 +18,6 @@ exports.readOwnedPiSettings = readOwnedPiSettings;
 exports.olderThanMinimumPiVersionMessage = olderThanMinimumPiVersionMessage;
 exports.parsePiExecutableVersion = parsePiExecutableVersion;
 exports.verifyPiCapabilities = verifyPiCapabilities;
-exports.prepareOwnedPiEnvironment = prepareOwnedPiEnvironment;
 exports.readProjectPiSettings = readProjectPiSettings;
 exports.assertNoProjectPiCompactionOverride = assertNoProjectPiCompactionOverride;
 exports.currentUserLabel = currentUserLabel;
@@ -25,7 +25,7 @@ const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
-/** External `pi` must be this version or newer; handshake still guards protocol compatibility. */
+/** External `pi` must be this version or newer. Stock 0.84.x does not emit compactionCapabilities. */
 exports.MINIMUM_PI_VERSION = "0.84.2";
 /** Fallback values used while importing a Pi profile, before Pi reports its model. */
 exports.PI_CONTEXT_WINDOW = 272_000;
@@ -174,15 +174,16 @@ function ensureOwnedPiAgentDirectory(root, agentId) {
     ensureDirectory(directory);
     return directory;
 }
-function ownedPiSettings(directory) {
-    return node_path_1.default.join(directory, "settings.json");
+/** Larkin-owned project settings that Pi deep-merges over the user's global agent dir. */
+function projectPiSettingsFile(workspaceDir) {
+    return node_path_1.default.join(workspaceDir, ".pi", "settings.json");
 }
-function prepareOwnedPiDirectory(directory, compaction) {
-    ensureDirectoryChain(node_path_1.default.dirname(directory));
-    ensureDirectory(node_path_1.default.dirname(directory));
-    ensureDirectory(directory);
-    writeOwnedPiSettings(directory, compaction);
-    return directory;
+function ownedPiSettings(workspaceDir) {
+    return projectPiSettingsFile(workspaceDir);
+}
+function prepareOwnedPiDirectory(workspaceDir, compaction) {
+    writeOwnedPiSettings(workspaceDir, compaction);
+    return workspaceDir;
 }
 function mergeOwnedPiSettings(value, compaction = {
     reserveTokens: exports.COMPACTION_RESERVE_TOKENS,
@@ -202,10 +203,11 @@ function mergeOwnedPiSettings(value, compaction = {
             reserveTokens: compaction.reserveTokens, keepRecentTokens: compaction.keepRecentTokens,
         } };
 }
-function writeOwnedPiSettings(directory, compaction) {
-    ensureDirectoryChain(node_path_1.default.dirname(directory));
-    ensureDirectory(directory);
-    const file = ownedPiSettings(directory);
+function writeOwnedPiSettings(workspaceDir, compaction) {
+    const projectDir = node_path_1.default.join(workspaceDir, ".pi");
+    ensureDirectoryChain(node_path_1.default.resolve(workspaceDir));
+    ensureDirectory(projectDir);
+    const file = projectPiSettingsFile(workspaceDir);
     try {
         const existing = node_fs_1.default.lstatSync(file);
         if (existing.isSymbolicLink() || !existing.isFile())
@@ -223,7 +225,7 @@ function writeOwnedPiSettings(directory, compaction) {
         if (error.code !== "ENOENT")
             throw new Error("Pi owned settings are invalid");
     }
-    const temporary = node_path_1.default.join(directory, `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
+    const temporary = node_path_1.default.join(projectDir, `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
     try {
         node_fs_1.default.writeFileSync(temporary, `${JSON.stringify(mergeOwnedPiSettings(value, compaction), null, 2)}\n`, { flag: "wx", mode: 0o600 });
         node_fs_1.default.renameSync(temporary, file);
@@ -236,10 +238,10 @@ function writeOwnedPiSettings(directory, compaction) {
         catch { /* renamed or absent */ }
     }
 }
-function readOwnedPiSettings(directory) {
-    ensureDirectoryChain(node_path_1.default.dirname(directory));
-    assertOwnedDirectory(directory);
-    const file = ownedPiSettings(directory);
+function readOwnedPiSettings(workspaceDir) {
+    const projectDir = node_path_1.default.join(workspaceDir, ".pi");
+    assertOwnedDirectory(projectDir);
+    const file = projectPiSettingsFile(workspaceDir);
     const stat = node_fs_1.default.lstatSync(file);
     if (stat.isSymbolicLink() || !stat.isFile())
         throw new Error("Pi owned settings must be a regular file");
@@ -299,12 +301,30 @@ function parsePiExecutableVersion(output) {
     }
     return version;
 }
+function resolveOptionalHandshake(capabilities) {
+    if (capabilities.compactionCapabilities !== undefined && capabilities.compactionCapabilities !== null) {
+        return capabilities.compactionCapabilities;
+    }
+    if (capabilities.reserveTokens !== undefined
+        || capabilities.keepRecentTokens !== undefined
+        || capabilities.events !== undefined) {
+        return {
+            reserveTokens: capabilities.reserveTokens,
+            keepRecentTokens: capabilities.keepRecentTokens,
+            events: capabilities.events,
+        };
+    }
+    return undefined;
+}
 function verifyPiCapabilities(capabilities) {
     assertSupportedPiVersion(capabilities.version);
     if (capabilities.trustedProtocol === true) {
         throw new Error("external Pi cannot use a trusted protocol bypass");
     }
     const contextWindow = capabilities.contextWindow ?? capabilities.model?.contextWindow;
+    if (typeof contextWindow !== "number" || !Number.isFinite(contextWindow) || contextWindow <= 0) {
+        throw new Error("Pi capability context window is invalid");
+    }
     const expected = (() => {
         try {
             return calculatePiCompactionSettings(contextWindow);
@@ -318,14 +338,18 @@ function verifyPiCapabilities(capabilities) {
     }
     if (capabilities.compactRpc !== true)
         throw new Error("Pi compact RPC capability is missing");
-    if (capabilities.reserveTokens !== expected.reserveTokens
-        || capabilities.keepRecentTokens !== expected.keepRecentTokens) {
+    const handshake = resolveOptionalHandshake(capabilities);
+    if (handshake === undefined)
+        return "larkin-settings-only";
+    if (handshake.reserveTokens !== expected.reserveTokens
+        || handshake.keepRecentTokens !== expected.keepRecentTokens) {
         throw new Error(`Pi external effective compaction reserve/keep settings are unproven for context window ${contextWindow}`);
     }
-    const events = new Set(capabilities.events || []);
+    const events = new Set(handshake.events || []);
     for (const event of REQUIRED_PI_EVENTS)
         if (!events.has(event))
             throw new Error(`Pi capability event is unproven: ${event}`);
+    return "handshake-reported";
 }
 function stateFile(root) {
     return node_path_1.default.join(root, exports.PI_COMPACTION_RECOVERY_FILE);
@@ -703,11 +727,6 @@ class PiCompactionRecoveryMachine {
     }
 }
 exports.PiCompactionRecoveryMachine = PiCompactionRecoveryMachine;
-function prepareOwnedPiEnvironment(input) {
-    const directory = ensureOwnedPiAgentDirectory(input.root, input.agentId);
-    writeOwnedPiSettings(directory);
-    return { ...input.env, PI_CODING_AGENT_DIR: directory };
-}
 function readProjectPiSettings(workspaceDir) {
     const file = node_path_1.default.join(workspaceDir, ".pi", "settings.json");
     try {

package/dist/runtime/pi-compaction-recovery.mjs

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-/** External `pi` must be this version or newer; handshake still guards protocol compatibility. */
+/** External `pi` must be this version or newer. Stock 0.84.x does not emit compactionCapabilities. */
 export const MINIMUM_PI_VERSION = "0.84.2";
 /** Fallback values used while importing a Pi profile, before Pi reports its model. */
 export const PI_CONTEXT_WINDOW = 272_000;
@@ -151,15 +151,16 @@ export function ensureOwnedPiAgentDirectory(root, agentId) {
     ensureDirectory(directory);
     return directory;
 }
-export function ownedPiSettings(directory) {
-    return path.join(directory, "settings.json");
+/** Larkin-owned project settings that Pi deep-merges over the user's global agent dir. */
+export function projectPiSettingsFile(workspaceDir) {
+    return path.join(workspaceDir, ".pi", "settings.json");
 }
-export function prepareOwnedPiDirectory(directory, compaction) {
-    ensureDirectoryChain(path.dirname(directory));
-    ensureDirectory(path.dirname(directory));
-    ensureDirectory(directory);
-    writeOwnedPiSettings(directory, compaction);
-    return directory;
+export function ownedPiSettings(workspaceDir) {
+    return projectPiSettingsFile(workspaceDir);
+}
+export function prepareOwnedPiDirectory(workspaceDir, compaction) {
+    writeOwnedPiSettings(workspaceDir, compaction);
+    return workspaceDir;
 }
 export function mergeOwnedPiSettings(value, compaction = {
     reserveTokens: COMPACTION_RESERVE_TOKENS,
@@ -179,10 +180,11 @@ export function mergeOwnedPiSettings(value, compaction = {
             reserveTokens: compaction.reserveTokens, keepRecentTokens: compaction.keepRecentTokens,
         } };
 }
-export function writeOwnedPiSettings(directory, compaction) {
-    ensureDirectoryChain(path.dirname(directory));
-    ensureDirectory(directory);
-    const file = ownedPiSettings(directory);
+export function writeOwnedPiSettings(workspaceDir, compaction) {
+    const projectDir = path.join(workspaceDir, ".pi");
+    ensureDirectoryChain(path.resolve(workspaceDir));
+    ensureDirectory(projectDir);
+    const file = projectPiSettingsFile(workspaceDir);
     try {
         const existing = fs.lstatSync(file);
         if (existing.isSymbolicLink() || !existing.isFile())
@@ -200,7 +202,7 @@ export function writeOwnedPiSettings(directory, compaction) {
         if (error.code !== "ENOENT")
             throw new Error("Pi owned settings are invalid");
     }
-    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    const temporary = path.join(projectDir, `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
     try {
         fs.writeFileSync(temporary, `${JSON.stringify(mergeOwnedPiSettings(value, compaction), null, 2)}\n`, { flag: "wx", mode: 0o600 });
         fs.renameSync(temporary, file);
@@ -213,10 +215,10 @@ export function writeOwnedPiSettings(directory, compaction) {
         catch { /* renamed or absent */ }
     }
 }
-export function readOwnedPiSettings(directory) {
-    ensureDirectoryChain(path.dirname(directory));
-    assertOwnedDirectory(directory);
-    const file = ownedPiSettings(directory);
+export function readOwnedPiSettings(workspaceDir) {
+    const projectDir = path.join(workspaceDir, ".pi");
+    assertOwnedDirectory(projectDir);
+    const file = projectPiSettingsFile(workspaceDir);
     const stat = fs.lstatSync(file);
     if (stat.isSymbolicLink() || !stat.isFile())
         throw new Error("Pi owned settings must be a regular file");
@@ -276,12 +278,30 @@ export function parsePiExecutableVersion(output) {
     }
     return version;
 }
+function resolveOptionalHandshake(capabilities) {
+    if (capabilities.compactionCapabilities !== undefined && capabilities.compactionCapabilities !== null) {
+        return capabilities.compactionCapabilities;
+    }
+    if (capabilities.reserveTokens !== undefined
+        || capabilities.keepRecentTokens !== undefined
+        || capabilities.events !== undefined) {
+        return {
+            reserveTokens: capabilities.reserveTokens,
+            keepRecentTokens: capabilities.keepRecentTokens,
+            events: capabilities.events,
+        };
+    }
+    return undefined;
+}
 export function verifyPiCapabilities(capabilities) {
     assertSupportedPiVersion(capabilities.version);
     if (capabilities.trustedProtocol === true) {
         throw new Error("external Pi cannot use a trusted protocol bypass");
     }
     const contextWindow = capabilities.contextWindow ?? capabilities.model?.contextWindow;
+    if (typeof contextWindow !== "number" || !Number.isFinite(contextWindow) || contextWindow <= 0) {
+        throw new Error("Pi capability context window is invalid");
+    }
     const expected = (() => {
         try {
             return calculatePiCompactionSettings(contextWindow);
@@ -295,14 +315,18 @@ export function verifyPiCapabilities(capabilities) {
     }
     if (capabilities.compactRpc !== true)
         throw new Error("Pi compact RPC capability is missing");
-    if (capabilities.reserveTokens !== expected.reserveTokens
-        || capabilities.keepRecentTokens !== expected.keepRecentTokens) {
+    const handshake = resolveOptionalHandshake(capabilities);
+    if (handshake === undefined)
+        return "larkin-settings-only";
+    if (handshake.reserveTokens !== expected.reserveTokens
+        || handshake.keepRecentTokens !== expected.keepRecentTokens) {
         throw new Error(`Pi external effective compaction reserve/keep settings are unproven for context window ${contextWindow}`);
     }
-    const events = new Set(capabilities.events || []);
+    const events = new Set(handshake.events || []);
     for (const event of REQUIRED_PI_EVENTS)
         if (!events.has(event))
             throw new Error(`Pi capability event is unproven: ${event}`);
+    return "handshake-reported";
 }
 function stateFile(root) {
     return path.join(root, PI_COMPACTION_RECOVERY_FILE);
@@ -678,11 +702,6 @@ export class PiCompactionRecoveryMachine {
             this.change("closed");
     }
 }
-export function prepareOwnedPiEnvironment(input) {
-    const directory = ensureOwnedPiAgentDirectory(input.root, input.agentId);
-    writeOwnedPiSettings(directory);
-    return { ...input.env, PI_CODING_AGENT_DIR: directory };
-}
 export function readProjectPiSettings(workspaceDir) {
     const file = path.join(workspaceDir, ".pi", "settings.json");
     try {

package/dist/runtime/pi-model-catalog.cjs

@@ -1,37 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PI_THINKING_LEVELS = void 0;
 exports.piModelId = piModelId;
@@ -40,7 +7,6 @@ exports.isPiThinkingLevel = isPiThinkingLevel;
 exports.findExactPiModel = findExactPiModel;
 exports.discoverPiModelCatalog = discoverPiModelCatalog;
 const node_child_process_1 = require("node:child_process");
-const path = __importStar(require("node:path"));
 const pi_rpc_client_js_1 = require("./pi-rpc-client.cjs");
 const runtime_readiness_js_1 = require("./runtime-readiness.cjs");
 exports.PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
@@ -77,17 +43,15 @@ function piCatalogChildEnv(options) {
         ...options.env,
         NO_COLOR: "1",
     };
-    if (options.agentDir)
-        env.PI_CODING_AGENT_DIR = path.resolve(options.agentDir);
-    else
-        delete env.PI_CODING_AGENT_DIR;
+    // External pi 必须看见用户自己的 home；Larkin 从不注入或转发 PI_CODING_AGENT_DIR。
+    delete env.PI_CODING_AGENT_DIR;
     return env;
 }
 async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
         const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
         const childEnv = piCatalogChildEnv(options);
-        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${childEnv.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}|${childEnv.PI_PACKAGE_DIR ?? ""}|${options.packageDir ?? ""}`;
+        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${childEnv.PI_PACKAGE_DIR ?? ""}|${options.packageDir ?? ""}`;
         const cached = discoveryCache.get(key);
         if (cached)
             return cached;

package/dist/runtime/pi-model-catalog.mjs

@@ -1,5 +1,4 @@
 import { spawn as nodeSpawn } from "node:child_process";
-import * as path from "node:path";
 import { PiRpcClient } from "./pi-rpc-client.mjs";
 import { classifyRuntimePrerequisite, RuntimePrerequisiteError } from "./runtime-readiness.mjs";
 export const PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
@@ -36,17 +35,15 @@ function piCatalogChildEnv(options) {
         ...options.env,
         NO_COLOR: "1",
     };
-    if (options.agentDir)
-        env.PI_CODING_AGENT_DIR = path.resolve(options.agentDir);
-    else
-        delete env.PI_CODING_AGENT_DIR;
+    // External pi 必须看见用户自己的 home；Larkin 从不注入或转发 PI_CODING_AGENT_DIR。
+    delete env.PI_CODING_AGENT_DIR;
     return env;
 }
 export async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
         const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
         const childEnv = piCatalogChildEnv(options);
-        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${childEnv.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}|${childEnv.PI_PACKAGE_DIR ?? ""}|${options.packageDir ?? ""}`;
+        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${childEnv.PI_PACKAGE_DIR ?? ""}|${options.packageDir ?? ""}`;
         const cached = discoveryCache.get(key);
         if (cached)
             return cached;