larkin 0.4.2 → 0.4.5

package/dist/platform/config.mjs

@@ -6,6 +6,7 @@ import { TargetRootLayout, resolveConfigDir as resolveRootConfigDir } from "./ro
 import { exactMode, fsyncDirectoryOf } from "./secure-metadata.mjs";
 import { CURRENT_RUNTIME_MODELS } from "../runtime/runtime-model-catalog.mjs";
 import processInspect from "./process-inspect.cjs";
+import { applyPiProfileMigration, assertPiProfileMigrationAfterState, preparePiProfileMigration, releasePiProfileMigrationLock, rollbackPiProfileMigration, validatePiProfileMigrationState, } from "../runtime/pi-profile-migration.mjs";
 const TOP_FIELDS_V3 = new Set(["version", "serverId", "activeAgent", "agents"]);
 const TOP_FIELDS_V4 = new Set(["version", "serverId", "mentionPolicy", "activeAgent", "agents"]);
 const AGENT_FIELDS_V3 = new Set(["runtime", "model", "effort", "noMentionChats", "createdAt"]);
@@ -19,6 +20,7 @@ const PI_MODEL = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._:@+-]+)?$/;
 const CODEX_MODEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const CLAUDE_MODEL = /^[A-Za-z0-9][A-Za-z0-9._\[\]-]{0,127}$/;
 const CONFIG_LIMIT_BYTES = 1024 * 1024;
+const PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES = 64 * 1024 * 1024;
 const LOCK_RETRIES = 200;
 const MALFORMED_LOCK_GRACE_MS = 5_000;
 let runtimeModels;
@@ -211,23 +213,36 @@ export function assertPrivateConfigMetadata(metadata, label = "配置文件") {
     if (!exactMode(metadata, 0o600))
         throw new Error(`${label} 权限必须是 0600`);
 }
-function readPrivateFile(file, root, limit, label) {
+function readBoundedPrivateFile(file, limit, label) {
     let fd = null;
     try {
-        const rootReal = fs.realpathSync(root);
-        const parentReal = fs.realpathSync(path.dirname(file));
-        if (parentReal !== rootReal)
-            throw new Error(`${label} 必须位于 canonical config root 内`);
+        const initial = fs.lstatSync(file);
+        if (initial.isSymbolicLink())
+            throw new Error(`${label} 不允许 symlink`);
+        if (!initial.isFile())
+            throw new Error(`${label} 必须是普通文件`);
         fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
-        const stat = fs.fstatSync(fd);
-        assertPrivateConfigMetadata({ regularFile: stat.isFile(), uid: stat.uid, mode: stat.mode }, label);
-        if (stat.size > limit)
+        const before = fs.fstatSync(fd);
+        assertPrivateConfigMetadata({ regularFile: before.isFile(), uid: before.uid, mode: before.mode }, label);
+        if (before.nlink !== 1)
+            throw new Error(`${label} 必须是未共享的普通文件`);
+        if (before.size > limit)
             throw new Error(`${label} 超过 ${limit} bytes`);
-        return fs.readFileSync(fd);
+        const bytes = Buffer.allocUnsafe(before.size);
+        let offset = 0;
+        while (offset < before.size) {
+            const read = fs.readSync(fd, bytes, offset, before.size - offset, null);
+            if (read === 0)
+                throw new Error(`${label} 读取期间发生变化`);
+            offset += read;
+        }
+        const after = fs.fstatSync(fd);
+        if (after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size || after.nlink !== before.nlink
+            || after.uid !== before.uid || after.gid !== before.gid || after.mode !== before.mode)
+            throw new Error(`${label} 读取期间发生变化`);
+        return bytes;
     }
     catch (error) {
-        if (error.code === "ENOENT")
-            return null;
         if (error.code === "ELOOP")
             throw new Error(`${label} 不允许 symlink`);
         throw error;
@@ -237,6 +252,20 @@ function readPrivateFile(file, root, limit, label) {
             fs.closeSync(fd);
     }
 }
+function readPrivateFile(file, root, limit, label) {
+    try {
+        const rootReal = fs.realpathSync(root);
+        const parentReal = fs.realpathSync(path.dirname(file));
+        if (parentReal !== rootReal)
+            throw new Error(`${label} 必须位于 canonical config root 内`);
+        return readBoundedPrivateFile(file, limit, label);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
 function readConfigFile(file, root = path.dirname(file)) {
     try {
         const bytes = readPrivateFile(file, root, CONFIG_LIMIT_BYTES, "配置文件");
@@ -324,23 +353,26 @@ export function runtimeConfigSignature(config, agentId) {
     return agentSignature(config, agentId);
 }
 function applyStateFile(configDir) { return path.join(configDir, "config-apply-state.json"); }
+function validateApplyState(value) {
+    if (!isPlainObject(value) || value.version !== 1 || typeof value.persistedRevision !== "string" || !isPlainObject(value.agents)) {
+        throw new Error("config apply state 无效");
+    }
+    const agents = {};
+    for (const [agentId, record] of Object.entries(value.agents)) {
+        if (!APP_ID.test(agentId) || !isPlainObject(record) || typeof record.persistedSignature !== "string"
+            || (record.appliedSignature !== null && typeof record.appliedSignature !== "string"))
+            throw new Error("config apply state Agent 记录无效");
+        agents[agentId] = { persistedSignature: record.persistedSignature, appliedSignature: record.appliedSignature };
+    }
+    return { version: 1, persistedRevision: value.persistedRevision, agents };
+}
 function readApplyFile(configDir) {
     const file = applyStateFile(configDir);
+    const bytes = readPrivateFile(file, configDir, 256 * 1024, "config apply state");
+    if (bytes === null)
+        return { version: 1, persistedRevision: "unknown", agents: {} };
     try {
-        const bytes = readPrivateFile(file, configDir, 256 * 1024, "config apply state");
-        if (bytes === null)
-            return { version: 1, persistedRevision: "unknown", agents: {} };
-        const value = JSON.parse(bytes.toString("utf8"));
-        if (value.version !== 1 || typeof value.persistedRevision !== "string" || !isPlainObject(value.agents))
-            throw new Error("config apply state 无效");
-        const agents = {};
-        for (const [agentId, record] of Object.entries(value.agents)) {
-            if (!APP_ID.test(agentId) || !isPlainObject(record) || typeof record.persistedSignature !== "string"
-                || (record.appliedSignature !== null && typeof record.appliedSignature !== "string"))
-                throw new Error("config apply state Agent 记录无效");
-            agents[agentId] = { persistedSignature: record.persistedSignature, appliedSignature: record.appliedSignature };
-        }
-        return { version: 1, persistedRevision: value.persistedRevision, agents };
+        return validateApplyState(JSON.parse(bytes.toString("utf8")));
     }
     catch (error) {
         throw error;
@@ -349,6 +381,115 @@ function readApplyFile(configDir) {
 function writeApplyFile(configDir, value) {
     atomicWriteConfig(applyStateFile(configDir), value);
 }
+function rollbackJournalFile(root) { return path.join(root, CONFIG_ROLLBACK_JOURNAL_FILE); }
+function migrationJournalFile(root) { return path.join(root, ".pi-profile-migration-journal.json"); }
+function assertMigrationTarget(root, agentId, migration) {
+    if (migration.agentId !== agentId || path.resolve(migration.targetDir) !== path.join(path.resolve(root), "providers", "pi", agentId)) {
+        throw new Error("Pi profile migration target is invalid");
+    }
+}
+function restoreTargetApplyState(root, targetAgentId, beforeRevision, before) {
+    const current = readApplyFile(root);
+    const agents = { ...current.agents };
+    if (before.agents[targetAgentId])
+        agents[targetAgentId] = { ...before.agents[targetAgentId] };
+    else
+        delete agents[targetAgentId];
+    writeApplyFile(root, { version: 1, persistedRevision: beforeRevision, agents });
+}
+function recoverRollbackJournal(root) {
+    const file = rollbackJournalFile(root);
+    let bytes;
+    try {
+        bytes = readPrivateFile(file, root, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES, "config rollback journal");
+    }
+    catch (error) {
+        throw error;
+    }
+    if (bytes === null)
+        return;
+    let journal;
+    try {
+        journal = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("config rollback journal is invalid");
+    }
+    if (journal.version !== 1 || typeof journal.targetAgentId !== "string" || !APP_ID.test(journal.targetAgentId)
+        || typeof journal.expectedAfterRevision !== "string" || typeof journal.beforeRevision !== "string"
+        || typeof journal.beforeConfigBytes !== "string" || !isPlainObject(journal.beforeApplyState)) {
+        throw new Error("config rollback journal is invalid");
+    }
+    const beforeBytes = Buffer.from(journal.beforeConfigBytes, "base64");
+    if (beforeBytes.length === 0 || revision(beforeBytes) !== journal.beforeRevision)
+        throw new Error("config rollback journal is invalid");
+    const beforeRaw = JSON.parse(beforeBytes.toString("utf8"));
+    normalizeConfig(beforeRaw, root);
+    validateApplyState(journal.beforeApplyState);
+    if (journal.migration !== undefined) {
+        validatePiProfileMigrationState(journal.migration);
+        assertMigrationTarget(root, journal.targetAgentId, journal.migration);
+    }
+    const current = readConfigFile(path.join(root, "config.json"), root);
+    const currentRevision = revision(current.bytes);
+    if (currentRevision === journal.expectedAfterRevision) {
+        if (journal.migration)
+            rollbackPiProfileMigration(journal.migration);
+        atomicWriteBytes(path.join(root, "config.json"), beforeBytes);
+        restoreTargetApplyState(root, journal.targetAgentId, journal.beforeRevision, journal.beforeApplyState);
+    }
+    else if (currentRevision === journal.beforeRevision) {
+        // The config replacement may have reached disk before apply-state restoration.
+        // Finish that phase before deleting the journal so recovery is complete.
+        restoreTargetApplyState(root, journal.targetAgentId, journal.beforeRevision, journal.beforeApplyState);
+    }
+    else {
+        throw new Error("config rollback journal conflicts with the current configuration");
+    }
+    fs.unlinkSync(file);
+    fsyncDirectoryOf(file);
+}
+function recoverMigrationJournal(root) {
+    const file = migrationJournalFile(root);
+    const bytes = readPrivateFile(file, root, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES, "Pi profile migration journal");
+    if (bytes === null)
+        return;
+    let journal;
+    try {
+        journal = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("Pi profile migration journal is invalid");
+    }
+    if (journal.version !== 1 || journal.phase !== "forward" || typeof journal.targetAgentId !== "string"
+        || typeof journal.beforeRevision !== "string" || typeof journal.expectedAfterRevision !== "string" || !journal.migration) {
+        throw new Error("Pi profile migration journal is invalid");
+    }
+    validatePiProfileMigrationState(journal.migration);
+    assertMigrationTarget(root, journal.targetAgentId, journal.migration);
+    const current = readConfigFile(path.join(root, "config.json"), root);
+    const currentRevision = revision(current.bytes);
+    if (currentRevision === journal.beforeRevision) {
+        // Forward import did not publish config. The migration helper restores only
+        // files still matching its expected post-import hashes.
+        try {
+            rollbackPiProfileMigration(journal.migration);
+        }
+        catch (error) {
+            throw new Error(`Pi profile migration recovery refused: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    else if (currentRevision === journal.expectedAfterRevision) {
+        // Config won the race; verify the provider target before finalizing.
+        const migration = journal.migration;
+        assertPiProfileMigrationAfterState(migration);
+    }
+    else
+        throw new Error("Pi profile migration journal conflicts with the current configuration");
+    releasePiProfileMigrationLock(journal.migration);
+    fs.unlinkSync(file);
+    fsyncDirectoryOf(file);
+}
 export function configApplyState(env, config) {
     let state;
     try {
@@ -425,12 +566,21 @@ function applyMutation(config, mutation) {
         agent.noMentionChats = Object.entries(policies).filter(([, value]) => value === "free").map(([chatId]) => chatId);
         return { scope: "chat", agentId: mutation.agentId, runtimeChange: false, affectedAgentIds: [mutation.agentId] };
     }
-    if (mutation.kind === "set-agent-runtime") {
+    if (mutation.kind === "set-agent-pi-distribution") {
+        if (agent.runtime !== "pi")
+            throw new Error(`Agent ${mutation.agentId} 不是 Pi runtime`);
+        if (mutation.distribution !== "builtin" && mutation.distribution !== "external")
+            throw new Error("Pi distribution 只允许 builtin/external");
+        agent.piDistribution = mutation.distribution;
+    }
+    else if (mutation.kind === "set-agent-runtime") {
         if (!loadRuntimeModels()[mutation.runtime])
             throw new Error(`未知 runtime：${mutation.runtime}`);
         assertModel(mutation.runtime, mutation.model || "default");
         agent.runtime = mutation.runtime;
         agent.model = mutation.model || "default";
+        if (mutation.runtime !== "pi")
+            delete agent.piDistribution;
         delete agent.effort;
     }
     else if (mutation.kind === "set-agent-model") {
@@ -549,8 +699,52 @@ function reclaimStaleLock(file, snapshot, owner) {
         }
     }
 }
+function isKnownSystemSymlink(current) {
+    return current === "/tmp" || current === "/var" || current === "/private/tmp" || current === "/private/var"
+        || current === "/var/folders" || /^\/var\/folders\/[^/]+$/.test(current)
+        || current === "/private/var/folders" || /^\/private\/var\/folders\/[^/]+$/.test(current);
+}
+function assertNoSymlinkAncestors(target) {
+    const resolved = path.resolve(target);
+    const root = path.parse(resolved).root;
+    let current = root;
+    for (const part of path.relative(root, resolved).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        if (stat.isSymbolicLink() && !isKnownSystemSymlink(current))
+            throw new Error("config path contains a symlink ancestor");
+        if (!stat.isDirectory() && !stat.isSymbolicLink())
+            throw new Error("config path ancestor is not a directory");
+    }
+}
+function assertConfigRoot(root) {
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("config root is unsafe");
+    if (process.platform !== "win32" && (stat.mode & 0o777) !== 0o700)
+        throw new Error("config root must be 0700");
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error("config root owner is unsafe");
+}
 function withConfigLock(layout, action) {
+    assertNoSymlinkAncestors(layout.root);
     fs.mkdirSync(layout.root, { recursive: true, mode: 0o700 });
+    const rootStat = fs.lstatSync(layout.root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error("config root is unsafe");
+    if (typeof process.getuid === "function" && rootStat.uid !== process.getuid())
+        throw new Error("config root owner is unsafe");
+    if (process.platform !== "win32" && (rootStat.mode & 0o777) !== 0o700)
+        fs.chmodSync(layout.root, 0o700);
+    assertConfigRoot(layout.root);
     const lock = `${layout.configFile}.lock`;
     const owner = currentLockRecord();
     let acquired = false;
@@ -564,6 +758,7 @@ function withConfigLock(layout, action) {
             finally {
                 fs.closeSync(fd);
             }
+            fsyncDirectoryOf(lock);
             acquired = true;
             break;
         }
@@ -579,6 +774,8 @@ function withConfigLock(layout, action) {
     if (!acquired)
         throw new Error("配置正被其他进程修改，请稍后重试");
     try {
+        recoverMigrationJournal(layout.root);
+        recoverRollbackJournal(layout.root);
         return action();
     }
     finally {
@@ -586,15 +783,113 @@ function withConfigLock(layout, action) {
         if (current?.record?.nonce === owner.nonce && current.record.pid === owner.pid) {
             try {
                 fs.unlinkSync(lock);
+                fsyncDirectoryOf(lock);
             }
             catch { /* best effort */ }
         }
     }
 }
-function atomicWriteConfig(file, value) {
-    const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
-    if (bytes.length > CONFIG_LIMIT_BYTES)
-        throw new Error(`配置文件超过 ${CONFIG_LIMIT_BYTES} bytes`);
+const CONFIG_ROLLBACK_JOURNAL_FILE = ".config-rollback-journal.json";
+function assertSnapshotPath(file, root, forbidden = []) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedFile = path.resolve(file);
+    if (forbidden.some((candidate) => resolvedFile === path.resolve(candidate)))
+        throw new Error("config snapshot path is reserved");
+    assertNoSymlinkAncestors(resolvedRoot);
+    assertNoSymlinkAncestors(path.dirname(resolvedFile));
+    const rootStat = fs.lstatSync(resolvedRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error("config root is unsafe");
+    if (process.platform !== "win32" && (rootStat.mode & 0o777) !== 0o700)
+        throw new Error("config root must be 0700");
+    if (typeof process.getuid === "function" && rootStat.uid !== process.getuid())
+        throw new Error("config root owner is unsafe");
+    const parent = path.dirname(resolvedFile);
+    const rootReal = fs.realpathSync(resolvedRoot);
+    const parentReal = fs.realpathSync(parent);
+    const relative = path.relative(rootReal, parentReal);
+    if (relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) {
+        throw new Error("config snapshot parent must be inside the canonical config root");
+    }
+    const parentStat = fs.lstatSync(parent);
+    if (!parentStat.isDirectory() || parentStat.isSymbolicLink())
+        throw new Error("config snapshot parent is unsafe");
+    if (process.platform !== "win32" && (parentStat.mode & 0o777) !== 0o700)
+        throw new Error("config snapshot parent must be 0700");
+    if (typeof process.getuid === "function" && parentStat.uid !== process.getuid())
+        throw new Error("config snapshot parent owner is unsafe");
+    try {
+        const stat = fs.lstatSync(resolvedFile);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1)
+            throw new Error("config snapshot path is unsafe");
+        if (process.platform !== "win32" && (stat.mode & 0o777) !== 0o600)
+            throw new Error("config snapshot must be 0600");
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            throw new Error("config snapshot owner is unsafe");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function writeConfigSnapshot(file, root, snapshot) {
+    assertSnapshotPath(file, root, [path.join(root, CONFIG_ROLLBACK_JOURNAL_FILE), path.join(root, "config.json"), path.join(root, "config-apply-state.json")]);
+    const bytes = Buffer.from(`${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+    if (bytes.length > PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES)
+        throw new Error("config snapshot is too large");
+    const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, bytes);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+        fsyncDirectoryOf(file);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function readConfigSnapshot(file, root) {
+    assertSnapshotPath(file, root, [path.join(root, CONFIG_ROLLBACK_JOURNAL_FILE), path.join(root, "config.json"), path.join(root, "config-apply-state.json")]);
+    const parsed = JSON.parse(readBoundedPrivateFile(file, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES, "config snapshot").toString("utf8"));
+    if (parsed.version !== 2 || typeof parsed.targetAgentId !== "string" || !APP_ID.test(parsed.targetAgentId)
+        || typeof parsed.beforeRevision !== "string" || typeof parsed.afterRevision !== "string"
+        || typeof parsed.afterSignature !== "string" || !parsed.beforeConfig || typeof parsed.beforeConfigBytes !== "string"
+        || !isPlainObject(parsed.beforeApplyState)) {
+        throw new Error("config snapshot is invalid");
+    }
+    const beforeBytes = Buffer.from(parsed.beforeConfigBytes, "base64");
+    if (beforeBytes.length === 0 || revision(beforeBytes) !== parsed.beforeRevision)
+        throw new Error("config snapshot before revision is invalid");
+    let beforeRaw;
+    try {
+        beforeRaw = JSON.parse(beforeBytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("config snapshot before config is invalid");
+    }
+    if (JSON.stringify(beforeRaw) !== JSON.stringify(parsed.beforeConfig))
+        throw new Error("config snapshot before config does not match bytes");
+    validateApplyState(parsed.beforeApplyState);
+    if (parsed.migration !== undefined) {
+        validatePiProfileMigrationState(parsed.migration);
+        assertMigrationTarget(root, parsed.targetAgentId, parsed.migration);
+    }
+    return parsed;
+}
+function atomicWriteBytes(file, bytes, limit = CONFIG_LIMIT_BYTES) {
+    if (bytes.length > limit)
+        throw new Error(`${limit === CONFIG_LIMIT_BYTES ? "配置文件" : "配置事务文件"}超过 ${limit} bytes`);
     const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
     const fd = fs.openSync(temporary, "wx", 0o600);
     try {
@@ -618,7 +913,13 @@ function atomicWriteConfig(file, value) {
     }
     return bytes;
 }
-export function mutateConfig(env, mutation, authority) {
+function atomicWriteConfig(file, value, limit = CONFIG_LIMIT_BYTES) {
+    const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+    if (bytes.length > limit)
+        throw new Error(`${limit === CONFIG_LIMIT_BYTES ? "配置文件" : "配置事务文件"}超过 ${limit} bytes`);
+    return atomicWriteBytes(file, bytes, limit);
+}
+export function mutateConfig(env, mutation, authority, options = {}) {
     assertAuthority(authority, mutation);
     const layout = TargetRootLayout.fromConfigDir(resolveConfigDir(env));
     return withConfigLock(layout, () => {
@@ -627,11 +928,43 @@ export function mutateConfig(env, mutation, authority) {
             throw new Error(`没找到配置 ${layout.configFile}，先跑 larkin setup`);
         const config = normalizeConfig(current.raw, layout.root);
         const priorSignatures = Object.fromEntries(Object.keys(config.agents).map((agentId) => [agentId, agentSignature(config, agentId)]));
+        if (options.importExternalProfile && (mutation.kind !== "set-agent-pi-distribution" || mutation.distribution !== "builtin")) {
+            throw new Error("external Pi profile import is only valid for builtin Pi distribution");
+        }
+        const migrationPlan = options.importExternalProfile && mutation.kind === "set-agent-pi-distribution"
+            ? preparePiProfileMigration(env, layout.root, mutation.agentId, "builtin")
+            : undefined;
         const changed = applyMutation(config, mutation);
         const stored = toStored(config);
         normalizeConfig(stored, layout.root);
-        const bytes = atomicWriteConfig(layout.configFile, stored);
+        const bytes = Buffer.from(`${JSON.stringify(stored, null, 2)}\n`, "utf8");
         const nextRevision = revision(bytes);
+        const beforeApplyState = options.snapshotFile
+            ? readApplyFile(layout.root)
+            : (() => { try {
+                return readApplyFile(layout.root);
+            }
+            catch {
+                return { version: 1, persistedRevision: "unknown", agents: {} };
+            } })();
+        if (options.snapshotFile) {
+            if (changed.affectedAgentIds.length !== 1 || !changed.agentId)
+                throw new Error("config snapshot requires exactly one Agent mutation");
+            writeConfigSnapshot(options.snapshotFile, layout.root, {
+                version: 2, targetAgentId: changed.agentId, beforeRevision: revision(current.bytes), afterRevision: nextRevision,
+                afterSignature: agentSignature(config, changed.agentId), beforeConfig: current.raw,
+                beforeConfigBytes: current.bytes.toString("base64"), beforeApplyState,
+                ...(migrationPlan ? { migration: migrationPlan.state } : {}),
+            });
+        }
+        if (migrationPlan) {
+            atomicWriteConfig(migrationJournalFile(layout.root), {
+                version: 1, phase: "forward", targetAgentId: changed.agentId, beforeRevision: revision(current.bytes),
+                expectedAfterRevision: nextRevision, migration: migrationPlan.state,
+            }, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES);
+            applyPiProfileMigration(migrationPlan);
+        }
+        atomicWriteConfig(layout.configFile, stored);
         let fullyApplied = changed.affectedAgentIds.length === 0;
         try {
             const applyState = readApplyFile(layout.root);
@@ -654,6 +987,17 @@ export function mutateConfig(env, mutation, authority) {
         catch {
             fullyApplied = false; /* Config persistence remains authoritative. */
         }
+        if (migrationPlan) {
+            releasePiProfileMigrationLock(migrationPlan.state);
+            try {
+                fs.unlinkSync(migrationJournalFile(layout.root));
+                fsyncDirectoryOf(migrationJournalFile(layout.root));
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
         return {
             revision: nextRevision, previousRevision: revision(current.bytes), changedScope: changed.scope,
             ...(changed.agentId ? { agentId: changed.agentId } : {}), persisted: true,
@@ -661,6 +1005,34 @@ export function mutateConfig(env, mutation, authority) {
         };
     });
 }
+export function rollbackConfig(env, snapshotFile) {
+    const layout = TargetRootLayout.fromConfigDir(resolveConfigDir(env));
+    return withConfigLock(layout, () => {
+        const snapshot = readConfigSnapshot(snapshotFile, layout.root);
+        const beforeBytes = Buffer.from(snapshot.beforeConfigBytes, "base64");
+        const beforeRaw = JSON.parse(beforeBytes.toString("utf8"));
+        normalizeConfig(beforeRaw, layout.root);
+        const current = readConfigFile(layout.configFile, layout.root);
+        const currentConfig = current.raw === null ? null : normalizeConfig(current.raw, layout.root);
+        if (!currentConfig || revision(current.bytes) !== snapshot.afterRevision
+            || agentSignature(currentConfig, snapshot.targetAgentId) !== snapshot.afterSignature) {
+            throw new Error("config changed after the snapshot; refusing rollback");
+        }
+        const journal = {
+            version: 1, targetAgentId: snapshot.targetAgentId, expectedAfterRevision: snapshot.afterRevision,
+            beforeRevision: snapshot.beforeRevision, beforeConfigBytes: snapshot.beforeConfigBytes, beforeApplyState: snapshot.beforeApplyState,
+            ...(snapshot.migration ? { migration: snapshot.migration } : {}),
+        };
+        atomicWriteConfig(rollbackJournalFile(layout.root), journal, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES);
+        if (snapshot.migration)
+            rollbackPiProfileMigration(snapshot.migration);
+        const bytes = atomicWriteBytes(layout.configFile, beforeBytes);
+        restoreTargetApplyState(layout.root, snapshot.targetAgentId, snapshot.beforeRevision, snapshot.beforeApplyState);
+        fs.unlinkSync(rollbackJournalFile(layout.root));
+        fsyncDirectoryOf(rollbackJournalFile(layout.root));
+        return { revision: revision(bytes), agentId: snapshot.targetAgentId };
+    });
+}
 export function commitSetupConfig(env, expectedRevision, nextStored) {
     const layout = TargetRootLayout.fromConfigDir(resolveConfigDir(env));
     return withConfigLock(layout, () => {
@@ -675,7 +1047,7 @@ export function commitSetupConfig(env, expectedRevision, nextStored) {
 export function safeConfigView(config, onlyAgentId, chatId, applyState) {
     const entries = onlyAgentId ? [[onlyAgentId, config.agents[onlyAgentId]]] : Object.entries(config.agents);
     const agents = entries.filter((entry) => Boolean(entry[1])).map(([agentId, agent]) => ({
-        agentId, runtime: agent.runtime, model: agent.model, effort: agent.effort ?? null,
+        agentId, runtime: agent.runtime, model: agent.model, piDistribution: agent.piDistribution ?? (agent.runtime === "pi" ? "external" : null), effort: agent.effort ?? null,
         mention: {
             override: agent.mentionPolicy ?? "inherit",
             effective: agent.mentionPolicy ?? config.mentionPolicy,