larkin 0.4.17 → 0.4.18

package/dist/runtime/builtin-pi-assets.cjs

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareBuiltinPiPackageAssets = prepareBuiltinPiPackageAssets;
+exports.piChildDistribution = piChildDistribution;
+exports.piChildDistributionFromOverrides = piChildDistributionFromOverrides;
+exports.resolveExternalPiPackageDir = resolveExternalPiPackageDir;
+exports.isLarkinBuiltinPiPackageDir = isLarkinBuiltinPiPackageDir;
+exports.catalogPiChildDistribution = catalogPiChildDistribution;
+exports.applyPiPackageDirForChild = applyPiPackageDirForChild;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function privateDirectory(directory) {
+    node_fs_1.default.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = node_fs_1.default.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`unsafe bundled Pi asset directory: ${directory}`);
+    node_fs_1.default.chmodSync(directory, 0o700);
+}
+function writeEmbeddedFile(file, contents) {
+    const temporary = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    node_fs_1.default.writeFileSync(temporary, contents, { mode: 0o600, flag: "wx" });
+    node_fs_1.default.renameSync(temporary, file);
+    node_fs_1.default.chmodSync(file, 0o600);
+}
+/** Materialize upstream runtime assets that Bun cannot serve through ordinary fs paths. */
+function prepareBuiltinPiPackageAssets() {
+    const assets = globalThis.__LARKIN_EMBEDDED_BUILTIN_PI_ASSETS__;
+    if (!assets)
+        return;
+    const agentDir = process.env.PI_CODING_AGENT_DIR;
+    if (!agentDir)
+        throw new Error("bundled Pi requires PI_CODING_AGENT_DIR");
+    privateDirectory(agentDir);
+    const packageDir = node_path_1.default.join(agentDir, ".larkin-official-pi-package");
+    const themeDir = node_path_1.default.join(packageDir, "theme");
+    privateDirectory(packageDir);
+    privateDirectory(themeDir);
+    writeEmbeddedFile(node_path_1.default.join(packageDir, "package.json"), assets.packageJson);
+    writeEmbeddedFile(node_path_1.default.join(themeDir, "dark.json"), assets.darkTheme);
+    writeEmbeddedFile(node_path_1.default.join(themeDir, "light.json"), assets.lightTheme);
+    process.env.PI_PACKAGE_DIR = packageDir;
+}
+function piChildDistribution(env) {
+    return env?.LARKIN_PI_DISTRIBUTION === "builtin" ? "builtin" : "external";
+}
+/** Host process env may be builtin Pi; only explicit child overrides select bundled assets. */
+function piChildDistributionFromOverrides(...overrides) {
+    for (let index = overrides.length - 1; index >= 0; index -= 1) {
+        const value = overrides[index]?.LARKIN_PI_DISTRIBUTION;
+        if (value === "builtin" || value === "external")
+            return value;
+    }
+    return "external";
+}
+function existingPiThemeFile(directory) {
+    const theme = node_path_1.default.join(directory, "dist", "modes", "interactive", "theme", "dark.json");
+    let fd;
+    try {
+        fd = node_fs_1.default.openSync(theme, node_fs_1.default.constants.O_RDONLY);
+        return node_fs_1.default.fstatSync(fd).isFile() ? theme : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                node_fs_1.default.closeSync(fd);
+            }
+            catch { /* already closed or unreadable */ }
+        }
+    }
+}
+function resolveExternalPiPackageDir(directory) {
+    if (!directory?.trim())
+        return undefined;
+    try {
+        const resolved = node_fs_1.default.realpathSync(directory);
+        return existingPiThemeFile(resolved) ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLarkinBuiltinPiPackageDir(directory) {
+    if (!directory)
+        return false;
+    try {
+        const resolved = node_fs_1.default.realpathSync(directory);
+        if (node_path_1.default.basename(resolved).toLowerCase() !== ".larkin-official-pi-package")
+            return false;
+        return !existingPiThemeFile(resolved);
+    }
+    catch {
+        return node_path_1.default.basename(directory).toLowerCase() === ".larkin-official-pi-package";
+    }
+}
+function catalogPiChildDistribution(commandArgs) {
+    return commandArgs?.includes("pi-rpc") ? "builtin" : "external";
+}
+/** External/npm Pi resolves PI_PACKAGE_DIR as a Node package root and looks for dist/themes. */
+function applyPiPackageDirForChild(env, distribution = piChildDistribution(env)) {
+    const options = typeof distribution === "string" ? { distribution } : distribution;
+    const resolved = options.distribution ?? piChildDistribution(env);
+    const next = { ...env };
+    if (resolved === "builtin")
+        return next;
+    const kept = resolveExternalPiPackageDir(options.explicitPackageDir) ?? resolveExternalPiPackageDir(next.PI_PACKAGE_DIR);
+    if (kept)
+        next.PI_PACKAGE_DIR = kept;
+    else
+        delete next.PI_PACKAGE_DIR;
+    return next;
+}

package/dist/runtime/builtin-pi-assets.mjs

@@ -31,3 +31,75 @@ export function prepareBuiltinPiPackageAssets() {
     writeEmbeddedFile(path.join(themeDir, "light.json"), assets.lightTheme);
     process.env.PI_PACKAGE_DIR = packageDir;
 }
+export function piChildDistribution(env) {
+    return env?.LARKIN_PI_DISTRIBUTION === "builtin" ? "builtin" : "external";
+}
+/** Host process env may be builtin Pi; only explicit child overrides select bundled assets. */
+export function piChildDistributionFromOverrides(...overrides) {
+    for (let index = overrides.length - 1; index >= 0; index -= 1) {
+        const value = overrides[index]?.LARKIN_PI_DISTRIBUTION;
+        if (value === "builtin" || value === "external")
+            return value;
+    }
+    return "external";
+}
+function existingPiThemeFile(directory) {
+    const theme = path.join(directory, "dist", "modes", "interactive", "theme", "dark.json");
+    let fd;
+    try {
+        fd = fs.openSync(theme, fs.constants.O_RDONLY);
+        return fs.fstatSync(fd).isFile() ? theme : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* already closed or unreadable */ }
+        }
+    }
+}
+export function resolveExternalPiPackageDir(directory) {
+    if (!directory?.trim())
+        return undefined;
+    try {
+        const resolved = fs.realpathSync(directory);
+        return existingPiThemeFile(resolved) ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isLarkinBuiltinPiPackageDir(directory) {
+    if (!directory)
+        return false;
+    try {
+        const resolved = fs.realpathSync(directory);
+        if (path.basename(resolved).toLowerCase() !== ".larkin-official-pi-package")
+            return false;
+        return !existingPiThemeFile(resolved);
+    }
+    catch {
+        return path.basename(directory).toLowerCase() === ".larkin-official-pi-package";
+    }
+}
+export function catalogPiChildDistribution(commandArgs) {
+    return commandArgs?.includes("pi-rpc") ? "builtin" : "external";
+}
+/** External/npm Pi resolves PI_PACKAGE_DIR as a Node package root and looks for dist/themes. */
+export function applyPiPackageDirForChild(env, distribution = piChildDistribution(env)) {
+    const options = typeof distribution === "string" ? { distribution } : distribution;
+    const resolved = options.distribution ?? piChildDistribution(env);
+    const next = { ...env };
+    if (resolved === "builtin")
+        return next;
+    const kept = resolveExternalPiPackageDir(options.explicitPackageDir) ?? resolveExternalPiPackageDir(next.PI_PACKAGE_DIR);
+    if (kept)
+        next.PI_PACKAGE_DIR = kept;
+    else
+        delete next.PI_PACKAGE_DIR;
+    return next;
+}

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

@@ -41,6 +41,7 @@ exports.findExactPiModel = findExactPiModel;
 exports.discoverPiModelCatalog = discoverPiModelCatalog;
 const node_child_process_1 = require("node:child_process");
 const path = __importStar(require("node:path"));
+const builtin_pi_assets_js_1 = require("./builtin-pi-assets.cjs");
 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"];
@@ -71,10 +72,23 @@ function findExactPiModel(reference, models) {
  */
 const discoveryCache = new Map();
 /** Discover only through Pi's structured RPC protocol; no table parsing or static fallback. */
+function piCatalogChildEnv(options) {
+    const mergedEnv = {
+        ...process.env,
+        ...options.env,
+        ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}),
+        NO_COLOR: "1",
+    };
+    return (0, builtin_pi_assets_js_1.applyPiPackageDirForChild)(mergedEnv, {
+        distribution: (0, builtin_pi_assets_js_1.catalogPiChildDistribution)(options.commandArgs),
+        explicitPackageDir: options.packageDir,
+    });
+}
 async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
         const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${options.env?.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}`;
+        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 cached = discoveryCache.get(key);
         if (cached)
             return cached;
@@ -93,7 +107,7 @@ async function discoverPiModelCatalogUncached(options) {
     const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
     const child = spawn(command, [...(options.commandArgs ?? []), "--mode", "rpc", "--no-session"], {
         cwd: options.cwd,
-        env: { ...process.env, ...options.env, ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}), NO_COLOR: "1" },
+        env: piCatalogChildEnv(options),
         stdio: ["pipe", "pipe", "pipe"],
     });
     const client = new pi_rpc_client_js_1.PiRpcClient(child, { requestTimeoutMs: options.timeoutMs ?? 10_000 });

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

@@ -1,5 +1,6 @@
 import { spawn as nodeSpawn } from "node:child_process";
 import * as path from "node:path";
+import { applyPiPackageDirForChild, catalogPiChildDistribution } from "./builtin-pi-assets.mjs";
 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"];
@@ -30,10 +31,23 @@ export function findExactPiModel(reference, models) {
  */
 const discoveryCache = new Map();
 /** Discover only through Pi's structured RPC protocol; no table parsing or static fallback. */
+function piCatalogChildEnv(options) {
+    const mergedEnv = {
+        ...process.env,
+        ...options.env,
+        ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}),
+        NO_COLOR: "1",
+    };
+    return applyPiPackageDirForChild(mergedEnv, {
+        distribution: catalogPiChildDistribution(options.commandArgs),
+        explicitPackageDir: options.packageDir,
+    });
+}
 export async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
         const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${options.env?.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}`;
+        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 cached = discoveryCache.get(key);
         if (cached)
             return cached;
@@ -52,7 +66,7 @@ async function discoverPiModelCatalogUncached(options) {
     const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
     const child = spawn(command, [...(options.commandArgs ?? []), "--mode", "rpc", "--no-session"], {
         cwd: options.cwd,
-        env: { ...process.env, ...options.env, ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}), NO_COLOR: "1" },
+        env: piCatalogChildEnv(options),
         stdio: ["pipe", "pipe", "pipe"],
     });
     const client = new PiRpcClient(child, { requestTimeoutMs: options.timeoutMs ?? 10_000 });

package/dist/runtime/pi-profile-migration.cjs

@@ -49,6 +49,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const process_inspect_cjs_1 = __importDefault(require("../platform/process-inspect.cjs"));
+const builtin_pi_assets_js_1 = require("./builtin-pi-assets.cjs");
 const runtime_readiness_js_1 = require("./runtime-readiness.cjs");
 const pi_compaction_recovery_js_1 = require("./pi-compaction-recovery.cjs");
 const pi_provider_config_js_1 = require("./pi-provider-config.cjs");
@@ -61,6 +62,60 @@ const EXECUTABLE_LIMIT = 256 * 1024 * 1024;
 const SOURCE_MODES = new Set([0o600, 0o644, 0o640]);
 const TARGET_LOCK_SUFFIX = ".larkin-pi-import.lock";
 function hash(bytes) { return crypto.createHash("sha256").update(bytes).digest("hex"); }
+function isPiOrLarkinEnvKey(key) {
+    return key === "PATH" || key.startsWith("PI_") || key.startsWith("LARKIN_");
+}
+function isolatePlannedReplayEnv(source) {
+    const next = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (isPiOrLarkinEnvKey(key))
+            continue;
+        next[key] = value;
+    }
+    if (source.PATH)
+        next.PATH = source.PATH;
+    if (source.LARKIN_PI_COMMAND)
+        next.LARKIN_PI_COMMAND = source.LARKIN_PI_COMMAND;
+    if (source.PI_PACKAGE_DIR)
+        next.PI_PACKAGE_DIR = source.PI_PACKAGE_DIR;
+    return next;
+}
+function capturePackageRootProof(directory) {
+    const resolved = fs.realpathSync(directory);
+    const rootStat = fs.statSync(resolved);
+    const theme = path.join(resolved, "dist", "modes", "interactive", "theme", "dark.json");
+    let fd;
+    try {
+        fd = fs.openSync(theme, fs.constants.O_RDONLY);
+        const themeStat = fs.fstatSync(fd);
+        if (!themeStat.isFile())
+            throw new Error("external Pi package root changed; refusing migration");
+        const bytes = fs.readFileSync(fd);
+        return { dir: resolved, dev: rootStat.dev, ino: rootStat.ino, themeSha256: hash(bytes) };
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+    }
+}
+function assertPackageRootProof(state) {
+    if (!state.sourcePackageDir)
+        return;
+    let current;
+    try {
+        current = capturePackageRootProof(state.sourcePackageDir);
+    }
+    catch {
+        throw new Error("external Pi package root changed; refusing migration");
+    }
+    if (current.dir !== state.sourcePackageDir || current.dev !== state.sourcePackageDev
+        || current.ino !== state.sourcePackageIno || current.themeSha256 !== state.sourcePackageThemeSha256) {
+        throw new Error("external Pi package root changed; refusing migration");
+    }
+}
 function targetLockFile(state) { return path.join(path.dirname(state.targetDir), `${state.agentId}${TARGET_LOCK_SUFFIX}`); }
 function acquireTargetLock(state) {
     const file = targetLockFile(state);
@@ -314,13 +369,20 @@ function targetDirectory(configDir, agentId) {
         throw new Error("Pi Agent ID 格式无效");
     return path.join(path.resolve(configDir), "providers", "pi", agentId);
 }
-function sourceVersion(env, cwd) {
+function sourceVersion(env, cwd, alreadySanitized = false) {
     const command = String(env.LARKIN_PI_COMMAND || "pi");
     const executable = (0, runtime_readiness_js_1.resolveRuntimeExecutable)(command, env);
     if (!executable)
         throw new Error("外部 Pi 0.84.2 profile import requires an installed Pi executable");
     const executableState = readExecutable(executable, "external Pi executable");
-    const result = (0, node_child_process_1.spawnSync)(executableState.path, ["--version"], { cwd, env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 });
+    const probeEnv = alreadySanitized ? env : (0, builtin_pi_assets_js_1.applyPiPackageDirForChild)(env, { distribution: "external" });
+    const result = (0, node_child_process_1.spawnSync)(executableState.path, ["--version"], {
+        cwd,
+        env: probeEnv,
+        encoding: "utf8",
+        timeout: 5_000,
+        maxBuffer: 64 * 1024,
+    });
     if (result.status !== 0)
         throw new Error("external Pi version probe failed");
     try {
@@ -366,10 +428,11 @@ function targetPrior(directory) {
     return { stat, entries, files };
 }
 function preparePiProfileMigration(env, configDir, agentId, distribution = "builtin") {
-    const sourceDir = sourceDirectory(env);
+    const sanitized = (0, builtin_pi_assets_js_1.applyPiPackageDirForChild)({ ...env }, { distribution: "external" });
+    const sourceDir = sourceDirectory(sanitized);
     verifySourceProfile(sourceDir);
     const sourceDirectoryState = assertDirectory(sourceDir, "external Pi profile");
-    const sourceExecutable = sourceVersion(env, sourceDir);
+    const sourceExecutable = sourceVersion(sanitized, sourceDir, true);
     const sourceFiles = Object.fromEntries(FILES.map((name) => {
         const file = readRegular(path.join(sourceDir, name), `external Pi ${name}`, false);
         if (!file)
@@ -391,14 +454,28 @@ function preparePiProfileMigration(env, configDir, agentId, distribution = "buil
     const afterFiles = Object.fromEntries(FILES.map((name) => [name, safeState({ bytes: imported[name], mode: 0o600 }, false)]));
     return {
         state: { version: 1, agentId, sourceDir, sourceDirMode: sourceDirectoryState.mode & 0o777,
-            sourceCommand: String(env.LARKIN_PI_COMMAND || "pi"), sourceExecutable,
+            sourceCommand: String(sanitized.LARKIN_PI_COMMAND || "pi"), sourceExecutable,
             sourceFiles: Object.fromEntries(FILES.map((name) => [name, safeState(sourceFiles[name], false)])),
             targetDir, targetDirExisted: Boolean(target.stat), targetDirMode: target.stat ? target.stat.mode & 0o777 : 0o700,
             ...(target.stat ? { targetDirDevice: target.stat.dev, targetDirInode: target.stat.ino } : {}), targetEntries: target.entries,
-            priorFiles: target.files, afterFiles },
+            priorFiles: target.files, afterFiles,
+            ...(sanitized.PATH ? { sourcePath: sanitized.PATH } : {}),
+            ...(sanitized.PI_PACKAGE_DIR ? (() => {
+                const proof = capturePackageRootProof(sanitized.PI_PACKAGE_DIR);
+                return {
+                    sourcePackageDir: proof.dir,
+                    sourcePackageDev: proof.dev,
+                    sourcePackageIno: proof.ino,
+                    sourcePackageThemeSha256: proof.themeSha256,
+                };
+            })() : {}) },
         sourceBytes: { "auth.json": sourceFiles["auth.json"].bytes, "models.json": sourceFiles["models.json"].bytes,
             "settings.json": imported["settings.json"] },
-        sourceEnvironment: { PATH: env.PATH, LARKIN_PI_COMMAND: env.LARKIN_PI_COMMAND },
+        sourceEnvironment: {
+            PATH: sanitized.PATH,
+            LARKIN_PI_COMMAND: String(sanitized.LARKIN_PI_COMMAND || "pi"),
+            ...(sanitized.PI_PACKAGE_DIR ? { PI_PACKAGE_DIR: capturePackageRootProof(sanitized.PI_PACKAGE_DIR).dir } : {}),
+        },
     };
 }
 function validatePiProfileMigrationState(value) {
@@ -439,12 +516,26 @@ function validatePiProfileMigrationState(value) {
         }
     }
 }
+function replayExternalPiPackageEnv(env) {
+    const next = { ...env };
+    const planned = env.PI_PACKAGE_DIR;
+    if (!planned) {
+        delete next.PI_PACKAGE_DIR;
+        return next;
+    }
+    const resolved = (0, builtin_pi_assets_js_1.applyPiPackageDirForChild)({ PI_PACKAGE_DIR: planned }, { distribution: "external", explicitPackageDir: planned }).PI_PACKAGE_DIR;
+    if (!resolved)
+        throw new Error("external Pi package root changed; refusing migration");
+    next.PI_PACKAGE_DIR = resolved;
+    return next;
+}
 function assertSourceUnchanged(state, resolutionEnvironment = process.env, verifyResolution = true) {
     const directory = assertDirectory(state.sourceDir, "external Pi profile");
     if ((directory.mode & 0o777) !== state.sourceDirMode)
         throw new Error("external Pi profile changed; refusing migration");
     verifySourceProfile(state.sourceDir);
-    const probeEnvironment = { ...process.env, ...resolutionEnvironment };
+    assertPackageRootProof(state);
+    const probeEnvironment = replayExternalPiPackageEnv(resolutionEnvironment);
     const resolved = verifyResolution ? (0, runtime_readiness_js_1.resolveRuntimeExecutable)(state.sourceCommand, probeEnvironment) : state.sourceExecutable.path;
     if (!resolved)
         throw new Error("external Pi executable changed; refusing migration");
@@ -453,7 +544,13 @@ function assertSourceUnchanged(state, resolutionEnvironment = process.env, verif
         || executable.bytes !== state.sourceExecutable.bytes || executable.mode !== state.sourceExecutable.mode) {
         throw new Error("external Pi executable changed; refusing migration");
     }
-    const result = (0, node_child_process_1.spawnSync)(executable.path, ["--version"], { cwd: state.sourceDir, env: probeEnvironment, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 });
+    const result = (0, node_child_process_1.spawnSync)(executable.path, ["--version"], {
+        cwd: state.sourceDir,
+        env: probeEnvironment,
+        encoding: "utf8",
+        timeout: 5_000,
+        maxBuffer: 64 * 1024,
+    });
     if (result.status !== 0)
         throw new Error("external Pi version probe failed");
     try {
@@ -565,9 +662,8 @@ function restoreFile(file, prior) {
         fs.chmodSync(file, prior.mode);
 }
 function applyPiProfileMigration(plan) {
-    const sameEnvironment = process.env.PATH === plan.sourceEnvironment.PATH
-        && process.env.LARKIN_PI_COMMAND === plan.sourceEnvironment.LARKIN_PI_COMMAND;
-    assertSourceUnchanged(plan.state, sameEnvironment ? process.env : plan.sourceEnvironment);
+    const replayEnv = isolatePlannedReplayEnv(plan.sourceEnvironment);
+    assertSourceUnchanged(plan.state, replayEnv);
     const parent = path.dirname(plan.state.targetDir);
     assertNoSymlinkAncestors(parent);
     fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
@@ -613,7 +709,11 @@ function fsyncDirectory(directory) {
 }
 function rollbackPiProfileMigration(state) {
     validatePiProfileMigrationState(state);
-    assertSourceUnchanged(state, process.env, false);
+    assertSourceUnchanged(state, isolatePlannedReplayEnv({
+        PATH: state.sourcePath,
+        LARKIN_PI_COMMAND: state.sourceCommand,
+        ...(state.sourcePackageDir ? { PI_PACKAGE_DIR: state.sourcePackageDir } : {}),
+    }), false);
     const target = assertDirectory(state.targetDir, "Pi provider target", false);
     if (!target) {
         if (state.targetDirExisted)

package/dist/runtime/pi-profile-migration.mjs

@@ -4,6 +4,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import processInspect from "../platform/process-inspect.cjs";
+import { applyPiPackageDirForChild } from "./builtin-pi-assets.mjs";
 import { resolveRuntimeExecutable } from "./runtime-readiness.mjs";
 import { mergeOwnedPiSettings, parsePiExecutableVersion } from "./pi-compaction-recovery.mjs";
 import { BUNDLED_PI_VERSION } from "./pi-provider-config.mjs";
@@ -16,6 +17,60 @@ const EXECUTABLE_LIMIT = 256 * 1024 * 1024;
 const SOURCE_MODES = new Set([0o600, 0o644, 0o640]);
 const TARGET_LOCK_SUFFIX = ".larkin-pi-import.lock";
 function hash(bytes) { return crypto.createHash("sha256").update(bytes).digest("hex"); }
+function isPiOrLarkinEnvKey(key) {
+    return key === "PATH" || key.startsWith("PI_") || key.startsWith("LARKIN_");
+}
+function isolatePlannedReplayEnv(source) {
+    const next = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (isPiOrLarkinEnvKey(key))
+            continue;
+        next[key] = value;
+    }
+    if (source.PATH)
+        next.PATH = source.PATH;
+    if (source.LARKIN_PI_COMMAND)
+        next.LARKIN_PI_COMMAND = source.LARKIN_PI_COMMAND;
+    if (source.PI_PACKAGE_DIR)
+        next.PI_PACKAGE_DIR = source.PI_PACKAGE_DIR;
+    return next;
+}
+function capturePackageRootProof(directory) {
+    const resolved = fs.realpathSync(directory);
+    const rootStat = fs.statSync(resolved);
+    const theme = path.join(resolved, "dist", "modes", "interactive", "theme", "dark.json");
+    let fd;
+    try {
+        fd = fs.openSync(theme, fs.constants.O_RDONLY);
+        const themeStat = fs.fstatSync(fd);
+        if (!themeStat.isFile())
+            throw new Error("external Pi package root changed; refusing migration");
+        const bytes = fs.readFileSync(fd);
+        return { dir: resolved, dev: rootStat.dev, ino: rootStat.ino, themeSha256: hash(bytes) };
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+    }
+}
+function assertPackageRootProof(state) {
+    if (!state.sourcePackageDir)
+        return;
+    let current;
+    try {
+        current = capturePackageRootProof(state.sourcePackageDir);
+    }
+    catch {
+        throw new Error("external Pi package root changed; refusing migration");
+    }
+    if (current.dir !== state.sourcePackageDir || current.dev !== state.sourcePackageDev
+        || current.ino !== state.sourcePackageIno || current.themeSha256 !== state.sourcePackageThemeSha256) {
+        throw new Error("external Pi package root changed; refusing migration");
+    }
+}
 function targetLockFile(state) { return path.join(path.dirname(state.targetDir), `${state.agentId}${TARGET_LOCK_SUFFIX}`); }
 function acquireTargetLock(state) {
     const file = targetLockFile(state);
@@ -269,13 +324,20 @@ function targetDirectory(configDir, agentId) {
         throw new Error("Pi Agent ID 格式无效");
     return path.join(path.resolve(configDir), "providers", "pi", agentId);
 }
-function sourceVersion(env, cwd) {
+function sourceVersion(env, cwd, alreadySanitized = false) {
     const command = String(env.LARKIN_PI_COMMAND || "pi");
     const executable = resolveRuntimeExecutable(command, env);
     if (!executable)
         throw new Error("外部 Pi 0.84.2 profile import requires an installed Pi executable");
     const executableState = readExecutable(executable, "external Pi executable");
-    const result = spawnSync(executableState.path, ["--version"], { cwd, env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 });
+    const probeEnv = alreadySanitized ? env : applyPiPackageDirForChild(env, { distribution: "external" });
+    const result = spawnSync(executableState.path, ["--version"], {
+        cwd,
+        env: probeEnv,
+        encoding: "utf8",
+        timeout: 5_000,
+        maxBuffer: 64 * 1024,
+    });
     if (result.status !== 0)
         throw new Error("external Pi version probe failed");
     try {
@@ -321,10 +383,11 @@ function targetPrior(directory) {
     return { stat, entries, files };
 }
 export function preparePiProfileMigration(env, configDir, agentId, distribution = "builtin") {
-    const sourceDir = sourceDirectory(env);
+    const sanitized = applyPiPackageDirForChild({ ...env }, { distribution: "external" });
+    const sourceDir = sourceDirectory(sanitized);
     verifySourceProfile(sourceDir);
     const sourceDirectoryState = assertDirectory(sourceDir, "external Pi profile");
-    const sourceExecutable = sourceVersion(env, sourceDir);
+    const sourceExecutable = sourceVersion(sanitized, sourceDir, true);
     const sourceFiles = Object.fromEntries(FILES.map((name) => {
         const file = readRegular(path.join(sourceDir, name), `external Pi ${name}`, false);
         if (!file)
@@ -346,14 +409,28 @@ export function preparePiProfileMigration(env, configDir, agentId, distribution
     const afterFiles = Object.fromEntries(FILES.map((name) => [name, safeState({ bytes: imported[name], mode: 0o600 }, false)]));
     return {
         state: { version: 1, agentId, sourceDir, sourceDirMode: sourceDirectoryState.mode & 0o777,
-            sourceCommand: String(env.LARKIN_PI_COMMAND || "pi"), sourceExecutable,
+            sourceCommand: String(sanitized.LARKIN_PI_COMMAND || "pi"), sourceExecutable,
             sourceFiles: Object.fromEntries(FILES.map((name) => [name, safeState(sourceFiles[name], false)])),
             targetDir, targetDirExisted: Boolean(target.stat), targetDirMode: target.stat ? target.stat.mode & 0o777 : 0o700,
             ...(target.stat ? { targetDirDevice: target.stat.dev, targetDirInode: target.stat.ino } : {}), targetEntries: target.entries,
-            priorFiles: target.files, afterFiles },
+            priorFiles: target.files, afterFiles,
+            ...(sanitized.PATH ? { sourcePath: sanitized.PATH } : {}),
+            ...(sanitized.PI_PACKAGE_DIR ? (() => {
+                const proof = capturePackageRootProof(sanitized.PI_PACKAGE_DIR);
+                return {
+                    sourcePackageDir: proof.dir,
+                    sourcePackageDev: proof.dev,
+                    sourcePackageIno: proof.ino,
+                    sourcePackageThemeSha256: proof.themeSha256,
+                };
+            })() : {}) },
         sourceBytes: { "auth.json": sourceFiles["auth.json"].bytes, "models.json": sourceFiles["models.json"].bytes,
             "settings.json": imported["settings.json"] },
-        sourceEnvironment: { PATH: env.PATH, LARKIN_PI_COMMAND: env.LARKIN_PI_COMMAND },
+        sourceEnvironment: {
+            PATH: sanitized.PATH,
+            LARKIN_PI_COMMAND: String(sanitized.LARKIN_PI_COMMAND || "pi"),
+            ...(sanitized.PI_PACKAGE_DIR ? { PI_PACKAGE_DIR: capturePackageRootProof(sanitized.PI_PACKAGE_DIR).dir } : {}),
+        },
     };
 }
 export function validatePiProfileMigrationState(value) {
@@ -394,12 +471,26 @@ export function validatePiProfileMigrationState(value) {
         }
     }
 }
+function replayExternalPiPackageEnv(env) {
+    const next = { ...env };
+    const planned = env.PI_PACKAGE_DIR;
+    if (!planned) {
+        delete next.PI_PACKAGE_DIR;
+        return next;
+    }
+    const resolved = applyPiPackageDirForChild({ PI_PACKAGE_DIR: planned }, { distribution: "external", explicitPackageDir: planned }).PI_PACKAGE_DIR;
+    if (!resolved)
+        throw new Error("external Pi package root changed; refusing migration");
+    next.PI_PACKAGE_DIR = resolved;
+    return next;
+}
 function assertSourceUnchanged(state, resolutionEnvironment = process.env, verifyResolution = true) {
     const directory = assertDirectory(state.sourceDir, "external Pi profile");
     if ((directory.mode & 0o777) !== state.sourceDirMode)
         throw new Error("external Pi profile changed; refusing migration");
     verifySourceProfile(state.sourceDir);
-    const probeEnvironment = { ...process.env, ...resolutionEnvironment };
+    assertPackageRootProof(state);
+    const probeEnvironment = replayExternalPiPackageEnv(resolutionEnvironment);
     const resolved = verifyResolution ? resolveRuntimeExecutable(state.sourceCommand, probeEnvironment) : state.sourceExecutable.path;
     if (!resolved)
         throw new Error("external Pi executable changed; refusing migration");
@@ -408,7 +499,13 @@ function assertSourceUnchanged(state, resolutionEnvironment = process.env, verif
         || executable.bytes !== state.sourceExecutable.bytes || executable.mode !== state.sourceExecutable.mode) {
         throw new Error("external Pi executable changed; refusing migration");
     }
-    const result = spawnSync(executable.path, ["--version"], { cwd: state.sourceDir, env: probeEnvironment, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 });
+    const result = spawnSync(executable.path, ["--version"], {
+        cwd: state.sourceDir,
+        env: probeEnvironment,
+        encoding: "utf8",
+        timeout: 5_000,
+        maxBuffer: 64 * 1024,
+    });
     if (result.status !== 0)
         throw new Error("external Pi version probe failed");
     try {
@@ -520,9 +617,8 @@ function restoreFile(file, prior) {
         fs.chmodSync(file, prior.mode);
 }
 export function applyPiProfileMigration(plan) {
-    const sameEnvironment = process.env.PATH === plan.sourceEnvironment.PATH
-        && process.env.LARKIN_PI_COMMAND === plan.sourceEnvironment.LARKIN_PI_COMMAND;
-    assertSourceUnchanged(plan.state, sameEnvironment ? process.env : plan.sourceEnvironment);
+    const replayEnv = isolatePlannedReplayEnv(plan.sourceEnvironment);
+    assertSourceUnchanged(plan.state, replayEnv);
     const parent = path.dirname(plan.state.targetDir);
     assertNoSymlinkAncestors(parent);
     fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
@@ -568,7 +664,11 @@ function fsyncDirectory(directory) {
 }
 export function rollbackPiProfileMigration(state) {
     validatePiProfileMigrationState(state);
-    assertSourceUnchanged(state, process.env, false);
+    assertSourceUnchanged(state, isolatePlannedReplayEnv({
+        PATH: state.sourcePath,
+        LARKIN_PI_COMMAND: state.sourceCommand,
+        ...(state.sourcePackageDir ? { PI_PACKAGE_DIR: state.sourcePackageDir } : {}),
+    }), false);
     const target = assertDirectory(state.targetDir, "Pi provider target", false);
     if (!target) {
         if (state.targetDirExisted)

package/dist/runtime/runtime-adapters.mjs

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { createInterface } from "node:readline";
+import { applyPiPackageDirForChild, piChildDistributionFromOverrides } from "./builtin-pi-assets.mjs";
 import { isPiThinkingLevel } from "./pi-model-catalog.mjs";
 import { PiRpcClient } from "./pi-rpc-client.mjs";
 import { internalCommandSpec } from "../app/internal-command.mjs";
@@ -967,23 +968,29 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         ...(session.sessionFile ? ["--session", session.sessionFile] : []),
         ...(requestedModel ? ["--model", requestedModel] : []),
         ...(requestedEffort ? ["--thinking", requestedEffort] : [])];
-    const builtin = mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin";
+    const builtin = piChildDistributionFromOverrides(dependencies.env, input.env) === "builtin";
+    if (!builtin && mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin")
+        delete mergedEnv.LARKIN_PI_DISTRIBUTION;
     const builtinSpec = builtin ? internalCommandSpec("pi-rpc", [], mergedEnv) : null;
     const command = builtinSpec?.command ?? dependencies.piCommand ?? dependencies.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
     const commandPrefix = builtinSpec?.args ?? dependencies.piCommandArgs ?? [];
     const commandArgs = [...commandPrefix, ...args];
+    mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
+    if (builtin)
+        mergedEnv.PI_TELEMETRY = "0";
+    const childEnv = applyPiPackageDirForChild(mergedEnv, {
+        distribution: builtin ? "builtin" : "external",
+        explicitPackageDir: input.env?.PI_PACKAGE_DIR ?? dependencies.env?.PI_PACKAGE_DIR,
+    });
     const reportedVersion = productionSpawn && !builtin
         ? parsePiExecutableVersion(String(spawnSync(command, [...commandPrefix, "--version"], {
-            cwd: input.workspaceDir, env: mergedEnv, encoding: "utf8", timeout: 5_000,
+            cwd: input.workspaceDir, env: childEnv, encoding: "utf8", timeout: 5_000,
         }).stdout || ""))
         : BUNDLED_PI_VERSION;
-    mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
-    if (builtin)
-        mergedEnv.PI_TELEMETRY = "0";
     const extensionArgs = (dependencies.resolvePiProcessExtensionArgs ?? resolvePiProcessExtensionArgs)({
         distribution: builtin ? "builtin" : "external",
         piCommand: command,
-        env: mergedEnv,
+        env: childEnv,
         platform: process.platform,
     });
     commandArgs.push(...extensionArgs);
@@ -993,14 +1000,14 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         // requested model first, then write the matching 15% reserve before the
         // real session starts; no prompt, provider request, package, or extension
         // is loaded by the probe.
-        probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, mergedEnv, spawn, dependencies.piRpcClientOptions);
+        probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, childEnv, spawn, dependencies.piRpcClientOptions);
         writeOwnedPiSettings(ownedPiDirectory, calculatePiCompactionSettings(probedModel.contextWindow));
     }
     const artifactEntriesBeforeSpawn = new Set(fs.readdirSync(ownedPiDirectory));
     const artifactSpawnBoundary = Date.now();
     const child = spawn(command, commandArgs, {
         cwd: input.workspaceDir,
-        env: mergedEnv,
+        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 });
@@ -1164,8 +1171,7 @@ export function createNativeRuntimeAdapter(id, dependencies = {}) {
                     throw new RuntimePrerequisiteError(readiness);
             }
             if (id === "pi") {
-                const distribution = ({ ...globalThis.process.env, ...dependencies.env, ...input.env }).LARKIN_PI_DISTRIBUTION === "builtin"
-                    ? "builtin" : "external";
+                const distribution = piChildDistributionFromOverrides(dependencies.env, input.env);
                 return new PiSession(await (dependencies.createPiSession
                     ? dependencies.createPiSession(input)
                     : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn, productionSpawn)), distribution);

package/dist/runtime/runtime-readiness.cjs

@@ -44,6 +44,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 builtin_pi_assets_js_1 = require("./builtin-pi-assets.cjs");
 const pi_provider_config_js_1 = require("./pi-provider-config.cjs");
 const process_boundary_trace_js_1 = require("../platform/process-boundary-trace.cjs");
 function safeProviderLabel(value) {
@@ -131,8 +132,14 @@ 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" && env.LARKIN_PI_DISTRIBUTION === "builtin") {
+    let env = { ...process.env, ...options.env };
+    const piDistribution = options.runtime === "pi" ? (0, builtin_pi_assets_js_1.piChildDistributionFromOverrides)(options.env) : "external";
+    if (options.runtime === "pi" && piDistribution !== "builtin") {
+        if (env.LARKIN_PI_DISTRIBUTION === "builtin")
+            delete env.LARKIN_PI_DISTRIBUTION;
+        env = (0, builtin_pi_assets_js_1.applyPiPackageDirForChild)(env, { distribution: "external" });
+    }
+    if (options.runtime === "pi" && piDistribution === "builtin") {
         try {
             if (!options.agentId || !env.LARKIN_CONFIG_DIR)
                 throw new Error("内置 Pi readiness 缺少 Agent/config identity");

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 { applyPiPackageDirForChild, piChildDistributionFromOverrides } from "./builtin-pi-assets.mjs";
 import { assertBuiltinPiAgentDirectory, BUNDLED_PI_VERSION, piAgentDirectory } from "./pi-provider-config.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 function safeProviderLabel(value) {
@@ -87,8 +88,14 @@ 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" && env.LARKIN_PI_DISTRIBUTION === "builtin") {
+    let env = { ...process.env, ...options.env };
+    const piDistribution = options.runtime === "pi" ? piChildDistributionFromOverrides(options.env) : "external";
+    if (options.runtime === "pi" && piDistribution !== "builtin") {
+        if (env.LARKIN_PI_DISTRIBUTION === "builtin")
+            delete env.LARKIN_PI_DISTRIBUTION;
+        env = applyPiPackageDirForChild(env, { distribution: "external" });
+    }
+    if (options.runtime === "pi" && piDistribution === "builtin") {
         try {
             if (!options.agentId || !env.LARKIN_CONFIG_DIR)
                 throw new Error("内置 Pi readiness 缺少 Agent/config identity");

package/dist/setup/setup-bind.mjs

@@ -330,7 +330,7 @@ export async function main() {
                 const catalog = await discoverPiModelCatalog({
                     cwd: CFG_DIR,
                     agentDir: piAgentDirectory(CFG_DIR, profile.appId),
-                    env: process.env,
+                    env: { ...process.env, LARKIN_PI_DISTRIBUTION: "external" },
                 });
                 const effective = catalog.effectiveModel;
                 const entry = effective ? catalog.models.find((model) => model.id === effective) : undefined;

package/package.json

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