larkin 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 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.
+
 ## 0.5.0
 
 BREAKING — builtin Pi is removed. Larkin supports only externally installed `pi`, `codex`, and `claude`. If the selected runtime is not installed, setup, runtime switch, and readiness fail with an explicit missing-install message.

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

@@ -3,20 +3,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PiCompactionRecoveryMachine = exports.PiCompactionBreaker = exports.PI_COMPACTION_RECOVERY_FILE = exports.PI_COMPACTION_RECOVERY_VERSION = exports.PI_COMPACTION_THRESHOLD = exports.COMPACTION_KEEP_RECENT_TOKENS = exports.COMPACTION_RESERVE_TOKENS = exports.PI_CONTEXT_WINDOW = exports.PINNED_PI_VERSION = void 0;
+exports.PiCompactionRecoveryMachine = exports.PiCompactionBreaker = exports.PI_COMPACTION_RECOVERY_FILE = exports.PI_COMPACTION_RECOVERY_VERSION = exports.PI_COMPACTION_THRESHOLD = exports.COMPACTION_KEEP_RECENT_TOKENS = exports.COMPACTION_RESERVE_TOKENS = exports.PI_CONTEXT_WINDOW = exports.MINIMUM_PI_VERSION = void 0;
 exports.calculatePiCompactionSettings = calculatePiCompactionSettings;
 exports.isPiNativeCompactionRequired = isPiNativeCompactionRequired;
 exports.assertEffectivePiCompactionSettings = assertEffectivePiCompactionSettings;
 exports.hasProjectPiCompactionOverride = hasProjectPiCompactionOverride;
 exports.ensureOwnedPiAgentDirectory = ensureOwnedPiAgentDirectory;
+exports.projectPiSettingsFile = projectPiSettingsFile;
 exports.ownedPiSettings = ownedPiSettings;
 exports.prepareOwnedPiDirectory = prepareOwnedPiDirectory;
 exports.mergeOwnedPiSettings = mergeOwnedPiSettings;
 exports.writeOwnedPiSettings = writeOwnedPiSettings;
 exports.readOwnedPiSettings = readOwnedPiSettings;
+exports.olderThanMinimumPiVersionMessage = olderThanMinimumPiVersionMessage;
 exports.parsePiExecutableVersion = parsePiExecutableVersion;
 exports.verifyPiCapabilities = verifyPiCapabilities;
-exports.prepareOwnedPiEnvironment = prepareOwnedPiEnvironment;
 exports.readProjectPiSettings = readProjectPiSettings;
 exports.assertNoProjectPiCompactionOverride = assertNoProjectPiCompactionOverride;
 exports.currentUserLabel = currentUserLabel;
@@ -24,7 +25,8 @@ 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"));
-exports.PINNED_PI_VERSION = "0.84.2";
+/** 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;
 exports.COMPACTION_RESERVE_TOKENS = 40_800;
@@ -172,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,
@@ -200,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())
@@ -221,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);
@@ -234,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");
@@ -254,25 +258,73 @@ function readOwnedPiSettings(directory) {
     }
     return { compaction: { enabled, reserveTokens: values.reserveTokens, keepRecentTokens: values.keepRecentTokens } };
 }
+const PI_VERSION_LINE = /^(?:pi(?:-coding-agent)?(?:\s+version)?\s+v?)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/i;
+const PI_VERSION_CORE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+function comparePiNumericVersions(left, right) {
+    const leftParts = left.split(".").map(Number);
+    const rightParts = right.split(".").map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] !== rightParts[index])
+            return Math.sign(leftParts[index] - rightParts[index]);
+    }
+    return 0;
+}
+function olderThanMinimumPiVersionMessage(version) {
+    return `Pi executable version ${version} is older than the minimum ${exports.MINIMUM_PI_VERSION}`;
+}
+function assertSupportedPiVersion(version) {
+    if (typeof version !== "string")
+        throw new Error(`Pi executable version ${exports.MINIMUM_PI_VERSION} or newer is required`);
+    const raw = version.trim();
+    const match = PI_VERSION_CORE.exec(raw);
+    if (!match)
+        throw new Error(`Pi executable version ${raw || "missing"} is not a supported version`);
+    const numeric = `${match[1]}.${match[2]}.${match[3]}`;
+    if (match[4]) {
+        throw new Error(`Pi executable version ${raw} is unsupported: SemVer ${raw} < ${numeric}; Larkin supports stable external pi only`);
+    }
+    if (comparePiNumericVersions(numeric, exports.MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(numeric));
+    }
+    return numeric;
+}
 function parsePiExecutableVersion(output) {
     const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
     if (lines.length !== 1)
         throw new Error("Pi executable version output must contain exactly one version line");
-    const line = lines[0];
-    // Pi's bare version is canonical; permit only the fixed official display prefix.
-    const escapedVersion = exports.PINNED_PI_VERSION.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    if (!new RegExp(`^(?:${escapedVersion}|pi(?:-coding-agent)?(?:\\s+version)?\\s+v?${escapedVersion})$`, "i").test(line)) {
-        throw new Error(`Pi executable version must be exactly ${exports.PINNED_PI_VERSION}`);
+    const match = PI_VERSION_LINE.exec(lines[0]);
+    if (!match)
+        throw new Error("Pi executable version output is not a supported version line");
+    const version = `${match[1]}.${match[2]}.${match[3]}`;
+    if (comparePiNumericVersions(version, exports.MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(version));
+    }
+    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 exports.PINNED_PI_VERSION;
+    return undefined;
 }
 function verifyPiCapabilities(capabilities) {
-    if (capabilities.version !== exports.PINNED_PI_VERSION)
-        throw new Error(`trusted Pi version ${exports.PINNED_PI_VERSION} is required`);
+    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);
@@ -286,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);
@@ -671,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,8 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-export const PINNED_PI_VERSION = "0.84.2";
+/** 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;
 export const COMPACTION_RESERVE_TOKENS = 40_800;
@@ -150,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,
@@ -178,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())
@@ -199,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);
@@ -212,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");
@@ -232,25 +235,73 @@ export function readOwnedPiSettings(directory) {
     }
     return { compaction: { enabled, reserveTokens: values.reserveTokens, keepRecentTokens: values.keepRecentTokens } };
 }
+const PI_VERSION_LINE = /^(?:pi(?:-coding-agent)?(?:\s+version)?\s+v?)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/i;
+const PI_VERSION_CORE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+function comparePiNumericVersions(left, right) {
+    const leftParts = left.split(".").map(Number);
+    const rightParts = right.split(".").map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] !== rightParts[index])
+            return Math.sign(leftParts[index] - rightParts[index]);
+    }
+    return 0;
+}
+export function olderThanMinimumPiVersionMessage(version) {
+    return `Pi executable version ${version} is older than the minimum ${MINIMUM_PI_VERSION}`;
+}
+function assertSupportedPiVersion(version) {
+    if (typeof version !== "string")
+        throw new Error(`Pi executable version ${MINIMUM_PI_VERSION} or newer is required`);
+    const raw = version.trim();
+    const match = PI_VERSION_CORE.exec(raw);
+    if (!match)
+        throw new Error(`Pi executable version ${raw || "missing"} is not a supported version`);
+    const numeric = `${match[1]}.${match[2]}.${match[3]}`;
+    if (match[4]) {
+        throw new Error(`Pi executable version ${raw} is unsupported: SemVer ${raw} < ${numeric}; Larkin supports stable external pi only`);
+    }
+    if (comparePiNumericVersions(numeric, MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(numeric));
+    }
+    return numeric;
+}
 export function parsePiExecutableVersion(output) {
     const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
     if (lines.length !== 1)
         throw new Error("Pi executable version output must contain exactly one version line");
-    const line = lines[0];
-    // Pi's bare version is canonical; permit only the fixed official display prefix.
-    const escapedVersion = PINNED_PI_VERSION.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    if (!new RegExp(`^(?:${escapedVersion}|pi(?:-coding-agent)?(?:\\s+version)?\\s+v?${escapedVersion})$`, "i").test(line)) {
-        throw new Error(`Pi executable version must be exactly ${PINNED_PI_VERSION}`);
+    const match = PI_VERSION_LINE.exec(lines[0]);
+    if (!match)
+        throw new Error("Pi executable version output is not a supported version line");
+    const version = `${match[1]}.${match[2]}.${match[3]}`;
+    if (comparePiNumericVersions(version, MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(version));
+    }
+    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 PINNED_PI_VERSION;
+    return undefined;
 }
 export function verifyPiCapabilities(capabilities) {
-    if (capabilities.version !== PINNED_PI_VERSION)
-        throw new Error(`trusted Pi version ${PINNED_PI_VERSION} is required`);
+    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);
@@ -264,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);
@@ -647,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;

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/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";
@@ -14,9 +13,12 @@ import { effectivePiStateDir, extractBackgroundPiSubagentDispatch } from "./pi-s
 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, PINNED_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 { 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;
 }
 class EventSession {
     listeners = new Set();
@@ -977,19 +979,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 +1012,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,22 +1026,20 @@ 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,
         }).stdout || ""))
-        : PINNED_PI_VERSION;
+        : MINIMUM_PI_VERSION;
     const extensionInput = { piCommand: command, env: childEnv, platform: process.platform };
     // 假 spawn 不需要真实 extension 路径；默认 resolver 会 spawnSync(`pi --version`)。
     const extensionArgs = dependencies.resolvePiProcessExtensionArgs
@@ -1057,21 +1048,16 @@ 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.
+        // 隔离探测用户自己的 Pi home（无 PI_CODING_AGENT_DIR），再把 15% reserve 写到工作区项目设置。
         probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, childEnv, spawn, dependencies.piRpcClientOptions);
-        writeOwnedPiSettings(ownedPiDirectory, calculatePiCompactionSettings(probedModel.contextWindow));
+        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 +1072,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 +1097,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) {

package/dist/runtime/runtime-readiness.cjs

@@ -53,6 +53,7 @@ exports.probeNativeRuntimeReadiness = probeNativeRuntimeReadiness;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+const pi_compaction_recovery_js_1 = require("./pi-compaction-recovery.cjs");
 function safeProviderId(value) {
     const provider = typeof value === "string" ? value.trim() : "";
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(provider) ? provider : null;
@@ -191,6 +192,14 @@ function classifyRuntimePrerequisite(runtime, error, executable) {
             runtime, state: "unauthenticated", ...(executable ? { executable } : {}), reason,
             nextAction: runtimeLoginNextAction(runtime),
         };
+    if (/older than the minimum|not a supported version(?: line)?|version output must contain exactly one/i.test(reason)) {
+        return {
+            runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
+            nextAction: runtime === "pi"
+                ? `Upgrade pi to ${pi_compaction_recovery_js_1.MINIMUM_PI_VERSION} or newer`
+                : `Upgrade ${runtime}, then retry.`,
+        };
+    }
     if (/protocol (?:version )?(?:mismatch|unsupported|incompatible)|unsupported (?:rpc|protocol|schema)|schema (?:mismatch|incompatible)|requires (?:a )?newer version/i.test(reason)) {
         return {
             runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
@@ -228,6 +237,8 @@ function executableVersion(executable, env, commandArgs = []) {
 /** Resolve and handshake through each runtime's structured native control protocol. */
 async function probeNativeRuntimeReadiness(options) {
     const env = { ...process.env, ...options.env };
+    if (options.runtime === "pi")
+        delete env.PI_CODING_AGENT_DIR;
     const command = selectedCommand(options);
     const executable = resolveRuntimeExecutable(command, env);
     if (!executable) {
@@ -238,7 +249,19 @@ async function probeNativeRuntimeReadiness(options) {
             nextAction: runtimeInstallNextAction(options.runtime),
         };
     }
-    const version = executableVersion(executable, env, options.commandArgs);
+    let version = executableVersion(executable, env, options.commandArgs);
+    if (options.runtime === "pi") {
+        try {
+            const probe = (0, node_child_process_1.spawnSync)(executable, [...options.commandArgs ?? [], "--version"], {
+                env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024,
+            });
+            version = (0, pi_compaction_recovery_js_1.parsePiExecutableVersion)(String(probe.stdout || ""));
+        }
+        catch (error) {
+            const classified = classifyRuntimePrerequisite("pi", error, executable);
+            return { ...classified, executable, ...(version ? { version } : {}) };
+        }
+    }
     try {
         if (options.runtime === "pi") {
             const { discoverPiModelCatalog } = await Promise.resolve().then(() => __importStar(require("./pi-model-catalog.cjs")));

package/dist/runtime/runtime-readiness.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { MINIMUM_PI_VERSION, parsePiExecutableVersion } from "./pi-compaction-recovery.mjs";
 export function safeProviderId(value) {
     const provider = typeof value === "string" ? value.trim() : "";
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(provider) ? provider : null;
@@ -138,6 +139,14 @@ export function classifyRuntimePrerequisite(runtime, error, executable) {
             runtime, state: "unauthenticated", ...(executable ? { executable } : {}), reason,
             nextAction: runtimeLoginNextAction(runtime),
         };
+    if (/older than the minimum|not a supported version(?: line)?|version output must contain exactly one/i.test(reason)) {
+        return {
+            runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
+            nextAction: runtime === "pi"
+                ? `Upgrade pi to ${MINIMUM_PI_VERSION} or newer`
+                : `Upgrade ${runtime}, then retry.`,
+        };
+    }
     if (/protocol (?:version )?(?:mismatch|unsupported|incompatible)|unsupported (?:rpc|protocol|schema)|schema (?:mismatch|incompatible)|requires (?:a )?newer version/i.test(reason)) {
         return {
             runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
@@ -175,6 +184,8 @@ function executableVersion(executable, env, commandArgs = []) {
 /** Resolve and handshake through each runtime's structured native control protocol. */
 export async function probeNativeRuntimeReadiness(options) {
     const env = { ...process.env, ...options.env };
+    if (options.runtime === "pi")
+        delete env.PI_CODING_AGENT_DIR;
     const command = selectedCommand(options);
     const executable = resolveRuntimeExecutable(command, env);
     if (!executable) {
@@ -185,7 +196,19 @@ export async function probeNativeRuntimeReadiness(options) {
             nextAction: runtimeInstallNextAction(options.runtime),
         };
     }
-    const version = executableVersion(executable, env, options.commandArgs);
+    let version = executableVersion(executable, env, options.commandArgs);
+    if (options.runtime === "pi") {
+        try {
+            const probe = spawnSync(executable, [...options.commandArgs ?? [], "--version"], {
+                env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024,
+            });
+            version = parsePiExecutableVersion(String(probe.stdout || ""));
+        }
+        catch (error) {
+            const classified = classifyRuntimePrerequisite("pi", error, executable);
+            return { ...classified, executable, ...(version ? { version } : {}) };
+        }
+    }
     try {
         if (options.runtime === "pi") {
             const { discoverPiModelCatalog } = await import("./pi-model-catalog.mjs");

package/package.json

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

package/dist/runtime/pi-artifact-provenance.mjs

@@ -1,139 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { exactMode } from "../platform/secure-metadata.mjs";
-export const PI_RUNTIME_ARTIFACT_MANIFEST = ".larkin-pi-owned-artifacts.json";
-export const PI_RUNTIME_ARTIFACT_NAMES = ["models-store.json", "npm"];
-const MAX_FILE_BYTES = 256 * 1024 * 1024;
-const MAX_ENTRIES = 4096;
-function digest(value) {
-    return crypto.createHash("sha256").update(value).digest("hex");
-}
-function assertSafeEntry(file, label) {
-    const stat = fs.lstatSync(file);
-    if (stat.isSymbolicLink())
-        throw new Error(`${label} must not be a symlink`);
-    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
-        throw new Error(`${label} owner is unsafe`);
-    return stat;
-}
-function identity(file, label) {
-    const stat = assertSafeEntry(file, label);
-    const mode = stat.mode & 0o777;
-    if (stat.isFile()) {
-        if (stat.size > MAX_FILE_BYTES)
-            throw new Error(`${label} is too large`);
-        const bytes = fs.readFileSync(file);
-        return { kind: "file", mode, device: String(stat.dev), inode: String(stat.ino), bytes: bytes.length, digest: digest(bytes) };
-    }
-    if (!stat.isDirectory())
-        throw new Error(`${label} has an unsupported type`);
-    const entries = fs.readdirSync(file).sort();
-    if (entries.length > MAX_ENTRIES)
-        throw new Error(`${label} has too many entries`);
-    const children = entries.map((name) => {
-        if (name === "." || name === ".." || name.includes("/"))
-            throw new Error(`${label} contains an unsafe entry`);
-        const child = identity(path.join(file, name), `${label} child`);
-        return [name, child.kind, child.mode, child.device, child.inode, child.bytes, child.digest];
-    });
-    return {
-        kind: "directory", mode, device: String(stat.dev), inode: String(stat.ino),
-        bytes: children.reduce((sum, child) => sum + Number(child[5]), 0), digest: digest(JSON.stringify(children)),
-    };
-}
-function sameIdentity(actual, expected) {
-    return actual.kind === expected.kind && actual.mode === expected.mode
-        && actual.device === expected.device && actual.inode === expected.inode
-        && actual.bytes === expected.bytes && actual.digest === expected.digest;
-}
-function readManifest(file) {
-    try {
-        const stat = assertSafeEntry(file, "Pi artifact provenance manifest");
-        if (!stat.isFile() || !exactMode(stat, 0o600) || stat.size > 1024 * 1024)
-            throw new Error("Pi artifact provenance manifest is unsafe");
-        const value = JSON.parse(fs.readFileSync(file, "utf8"));
-        if (value?.version !== 1 || (value.owner !== "larkin-pi" && value.owner !== "larkin-builtin-pi") || !value.directory || !value.artifacts)
-            throw new Error("Pi artifact provenance manifest is invalid");
-        return value;
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-}
-function writeManifest(file, value) {
-    const temp = `${file}.tmp-${process.pid}`;
-    const fd = fs.openSync(temp, "wx", 0o600);
-    try {
-        fs.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
-        fs.fsyncSync(fd);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-    fs.renameSync(temp, file);
-}
-/** Record only allowed entries that were absent at the runtime spawn boundary. */
-export function recordPiRuntimeArtifactProvenance(targetDir, beforeEntries, boundaryAt = Date.now()) {
-    const target = assertSafeEntry(targetDir, "Pi provider target");
-    if (!target.isDirectory() || !exactMode(target, 0o700))
-        throw new Error("Pi provider target is unsafe");
-    const manifestFile = path.join(targetDir, PI_RUNTIME_ARTIFACT_MANIFEST);
-    const existing = readManifest(manifestFile);
-    const manifest = existing ?? {
-        version: 1, owner: "larkin-pi", directory: { device: String(target.dev), inode: String(target.ino) },
-        recordedAt: new Date(boundaryAt).toISOString(), artifacts: {},
-    };
-    if (manifest.directory.device !== String(target.dev) || manifest.directory.inode !== String(target.ino))
-        throw new Error("Pi artifact provenance target identity changed");
-    let changed = false;
-    for (const [name, expected] of Object.entries(manifest.artifacts)) {
-        if (!PI_RUNTIME_ARTIFACT_NAMES.includes(name) || name.includes("/") || !expected)
-            throw new Error("Pi artifact provenance entry is invalid");
-        const actual = identity(path.join(targetDir, name), `Pi artifact ${name}`);
-        const sameOwner = actual.kind === expected.kind && actual.mode === expected.mode
-            && actual.device === expected.device && actual.inode === expected.inode;
-        if (!sameOwner)
-            throw new Error(`Pi artifact ${name} provenance identity changed`);
-        if (!sameIdentity(actual, expected)) {
-            manifest.artifacts[name] = actual;
-            changed = true;
-        }
-    }
-    for (const name of PI_RUNTIME_ARTIFACT_NAMES) {
-        if (beforeEntries.has(name) || manifest.artifacts[name])
-            continue;
-        const file = path.join(targetDir, name);
-        if (!fs.existsSync(file))
-            continue;
-        const actual = identity(file, `Pi artifact ${name}`);
-        const stat = fs.lstatSync(file);
-        if (stat.birthtimeMs + 1 < boundaryAt && stat.mtimeMs + 1 < boundaryAt)
-            throw new Error(`Pi artifact ${name} predates runtime provenance boundary`);
-        manifest.artifacts[name] = actual;
-        changed = true;
-    }
-    if (changed)
-        writeManifest(manifestFile, manifest);
-}
-/** Return the names that are both explicitly attested and unchanged. */
-export function attestedPiRuntimeArtifactNames(targetDir) {
-    const target = assertSafeEntry(targetDir, "Pi provider target");
-    if (!target.isDirectory())
-        throw new Error("Pi provider target is unsafe");
-    const manifest = readManifest(path.join(targetDir, PI_RUNTIME_ARTIFACT_MANIFEST));
-    if (!manifest || manifest.directory.device !== String(target.dev) || manifest.directory.inode !== String(target.ino))
-        return new Set();
-    const names = new Set();
-    for (const [name, expected] of Object.entries(manifest.artifacts)) {
-        if (!PI_RUNTIME_ARTIFACT_NAMES.includes(name) || !expected)
-            continue;
-        const actual = identity(path.join(targetDir, name), `Pi artifact ${name}`);
-        if (!sameIdentity(actual, expected))
-            throw new Error(`Pi artifact ${name} provenance changed`);
-        names.add(name);
-    }
-    return names;
-}