larkin 0.4.1 → 0.4.5

package/dist/agent/agent-state-store.cjs

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentStateStore = void 0;
+exports.AgentStateStore = exports.ContextOverflowRecoveryError = void 0;
 exports.createAgentStateStore = createAgentStateStore;
 const fs = __importStar(require("node:fs"));
 const crypto = __importStar(require("node:crypto"));
@@ -42,6 +42,7 @@ const root_layout_js_1 = require("../platform/root-layout.cjs");
 const process_state_js_1 = require("../platform/process-state.cjs");
 const secure_metadata_js_1 = require("../platform/secure-metadata.cjs");
 const inbox_projection_js_1 = require("./inbox-projection.cjs");
+const provider_error_classifier_js_1 = require("../runtime/provider-error-classifier.cjs");
 const JSON_KEYS = new Set([
     "agentState", "status", "map", "replyctx", "botIdentity", "senderProfiles", "readReceipts", "pendingReact", "runtimeDeliveries", "inboxState", "freshnessState", "documentComments", "reminders", "interactions",
 ]);
@@ -197,6 +198,15 @@ function validInboxLockOwner(value) {
         && typeof owner.processStartToken === "string" && !!owner.processStartToken
         && typeof owner.nonce === "string" && /^[0-9a-f-]{36}$/i.test(owner.nonce);
 }
+class ContextOverflowRecoveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ContextOverflowRecoveryError";
+    }
+}
+exports.ContextOverflowRecoveryError = ContextOverflowRecoveryError;
 class AgentStateStore {
     paths;
     boundary;
@@ -728,6 +738,188 @@ class AgentStateStore {
             return { status: "missing", code: "canonical_inbox_row_missing" };
         });
     }
+    /**
+     * Re-arm only the durable deliveries proven to be the context-window incident.
+     * The Inbox bytes are intentionally untouched. An optional synchronous commit
+     * hook lets RuntimeHost swap its in-memory generation while this same lock is
+     * still held. If the hook fails, the ledger is restored before the lock is
+     * released. The callback also receives a guarded rollback for post-callback
+     * commit failures before retry scheduling begins.
+     */
+    rearmContextOverflow(onCommit, expected) {
+        let lockActive = true;
+        try {
+            return this.withInboxTransaction(() => {
+                let rows;
+                try {
+                    rows = this.readNdjson("inbox");
+                }
+                catch {
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox is malformed");
+                }
+                if (rows.length === 0)
+                    throw new ContextOverflowRecoveryError("inbox_empty", "canonical Inbox backlog is empty");
+                const messageIds = new Set();
+                for (const row of rows) {
+                    try {
+                        (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
+                    }
+                    catch {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox contains a malformed row");
+                    }
+                    if (typeof row.message_id !== "string" || !row.message_id) {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox row has no message identity");
+                    }
+                    if (messageIds.has(row.message_id))
+                        throw new ContextOverflowRecoveryError("duplicate_message_id", "canonical Inbox contains duplicate message identities");
+                    messageIds.add(row.message_id);
+                }
+                const ledger = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                if (!Array.isArray(ledger.records))
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "Runtime delivery ledger is malformed");
+                const ledgerRecords = ledger.records;
+                const matches = new Map();
+                const deliveryIds = new Set();
+                const inputIds = new Set();
+                for (const candidate of ledger.records) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        continue;
+                    if (typeof record.deliveryId !== "string" || !record.deliveryId)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a matching Runtime delivery record has no delivery identity");
+                    if (!record.input || typeof record.input !== "object" || Array.isArray(record.input)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has no Runtime input identity");
+                    }
+                    const input = record.input;
+                    if (typeof input.inputId !== "string" || !input.inputId.trim()
+                        || typeof input.deliveryId !== "string" || input.deliveryId !== record.deliveryId) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has malformed input identity");
+                    }
+                    if (matches.has(record.messageId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a canonical Inbox row maps to multiple delivery records");
+                    if (deliveryIds.has(record.deliveryId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "matching Runtime delivery records share a delivery identity");
+                    if (inputIds.has(input.inputId))
+                        throw new ContextOverflowRecoveryError("duplicate_input_id", "matching Runtime delivery records share an input identity");
+                    deliveryIds.add(record.deliveryId);
+                    inputIds.add(input.inputId);
+                    matches.set(record.messageId, record);
+                }
+                if (expected?.messageId && !messageIds.has(expected.messageId)) {
+                    throw new ContextOverflowRecoveryError("delivery_missing", "the expected context-overflow message is not in canonical Inbox");
+                }
+                if (expected?.messageId) {
+                    const expectedRecord = matches.get(expected.messageId);
+                    if (!expectedRecord || (expected.deliveryId && expectedRecord.deliveryId !== expected.deliveryId)
+                        || (expected.inputId && expectedRecord.input.inputId !== expected.inputId)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "the expected context-overflow delivery identity changed");
+                    }
+                }
+                for (const messageId of messageIds) {
+                    const record = matches.get(messageId);
+                    if (!record)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a canonical Inbox row has no Runtime delivery record");
+                    if (record.status !== "error" || record.retryable === true) {
+                        throw new ContextOverflowRecoveryError("delivery_not_terminal", "a canonical Inbox row is not backed by a non-retryable terminal Runtime error");
+                    }
+                    const reasonCategory = (0, provider_error_classifier_js_1.classifyStrictProviderError)((0, provider_error_classifier_js_1.buildStrictProviderErrorInput)({
+                        reason: record.reason, errorCategory: record.errorCategory,
+                    }));
+                    if (record.retryable !== false || reasonCategory !== "context_window"
+                        || (record.errorCategory !== undefined && record.errorCategory !== "context_window")) {
+                        throw new ContextOverflowRecoveryError("delivery_not_context_window", "a Runtime delivery error is not classified as context_window");
+                    }
+                }
+                for (const candidate of ledgerRecords) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.deliveryId === "string" && deliveryIds.has(record.deliveryId)
+                        && (typeof record.messageId !== "string" || !messageIds.has(record.messageId))) {
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a matching delivery identity is also used by an unrelated Runtime delivery record");
+                    }
+                }
+                const updatedAt = new Date().toISOString();
+                const records = ledgerRecords.map((candidate) => {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        return candidate;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        return candidate;
+                    return { ...record, status: "pending", retryable: true, updatedAt };
+                });
+                const committedLedger = { ...ledger, records };
+                let restored = false;
+                const restoreUnlocked = () => {
+                    if (restored)
+                        return;
+                    const current = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                    if (!Array.isArray(current.records))
+                        throw new Error("Runtime delivery rollback found a malformed ledger");
+                    const originalMatching = ledgerRecords.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return typeof record.messageId === "string" && messageIds.has(record.messageId);
+                    });
+                    const originalDeliveryIds = new Set(originalMatching.flatMap((candidate) => {
+                        const deliveryId = candidate.deliveryId;
+                        return typeof deliveryId === "string" ? [deliveryId] : [];
+                    }));
+                    const currentMatching = current.records.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return (typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                            || (typeof record.messageId === "string" && messageIds.has(record.messageId));
+                    });
+                    const matchingRestored = currentMatching.length === originalMatching.length
+                        && currentMatching.every((candidate, index) => JSON.stringify(candidate) === JSON.stringify(originalMatching[index]));
+                    if (!matchingRestored) {
+                        const unrelated = current.records.filter((candidate) => {
+                            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                                return true;
+                            const record = candidate;
+                            return !((typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                                || (typeof record.messageId === "string" && messageIds.has(record.messageId)));
+                        });
+                        const restoredRecords = [...unrelated];
+                        for (const candidate of originalMatching) {
+                            const originalIndex = ledgerRecords.indexOf(candidate);
+                            restoredRecords.splice(Math.min(originalIndex, restoredRecords.length), 0, candidate);
+                        }
+                        this.writeJson("runtimeDeliveries", { ...current, records: restoredRecords });
+                    }
+                    restored = true;
+                };
+                const rollback = () => {
+                    if (lockActive)
+                        restoreUnlocked();
+                    else
+                        this.withInboxTransaction(restoreUnlocked);
+                };
+                try {
+                    this.writeJson("runtimeDeliveries", committedLedger);
+                    onCommit?.([...messageIds], rollback);
+                }
+                catch (error) {
+                    try {
+                        rollback();
+                    }
+                    catch {
+                        throw new Error("context-window recovery ledger rollback failed");
+                    }
+                    throw error;
+                }
+                return { rearmedCount: messageIds.size, remainingPendingCount: rows.length };
+            });
+        }
+        finally {
+            lockActive = false;
+        }
+    }
     /**
      * Recoverably bridge an outbox wake into the canonical Inbox. A durable
      * Runtime ledger is authoritative after the Inbox has been drained, so a

package/dist/agent/agent-state-store.mjs

@@ -5,6 +5,7 @@ import { TargetRootLayout } from "../platform/root-layout.mjs";
 import { acquireProcessLock, inspectProcess } from "../platform/process-state.mjs";
 import { isWindows } from "../platform/secure-metadata.mjs";
 import { isCanonicalInboxTarget, targetKeyOfInboxEnvelope } from "./inbox-projection.mjs";
+import { buildStrictProviderErrorInput, classifyStrictProviderError } from "../runtime/provider-error-classifier.mjs";
 const JSON_KEYS = new Set([
     "agentState", "status", "map", "replyctx", "botIdentity", "senderProfiles", "readReceipts", "pendingReact", "runtimeDeliveries", "inboxState", "freshnessState", "documentComments", "reminders", "interactions",
 ]);
@@ -160,6 +161,14 @@ function validInboxLockOwner(value) {
         && typeof owner.processStartToken === "string" && !!owner.processStartToken
         && typeof owner.nonce === "string" && /^[0-9a-f-]{36}$/i.test(owner.nonce);
 }
+export class ContextOverflowRecoveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ContextOverflowRecoveryError";
+    }
+}
 export class AgentStateStore {
     paths;
     boundary;
@@ -691,6 +700,188 @@ export class AgentStateStore {
             return { status: "missing", code: "canonical_inbox_row_missing" };
         });
     }
+    /**
+     * Re-arm only the durable deliveries proven to be the context-window incident.
+     * The Inbox bytes are intentionally untouched. An optional synchronous commit
+     * hook lets RuntimeHost swap its in-memory generation while this same lock is
+     * still held. If the hook fails, the ledger is restored before the lock is
+     * released. The callback also receives a guarded rollback for post-callback
+     * commit failures before retry scheduling begins.
+     */
+    rearmContextOverflow(onCommit, expected) {
+        let lockActive = true;
+        try {
+            return this.withInboxTransaction(() => {
+                let rows;
+                try {
+                    rows = this.readNdjson("inbox");
+                }
+                catch {
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox is malformed");
+                }
+                if (rows.length === 0)
+                    throw new ContextOverflowRecoveryError("inbox_empty", "canonical Inbox backlog is empty");
+                const messageIds = new Set();
+                for (const row of rows) {
+                    try {
+                        targetKeyOfInboxEnvelope(row);
+                    }
+                    catch {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox contains a malformed row");
+                    }
+                    if (typeof row.message_id !== "string" || !row.message_id) {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox row has no message identity");
+                    }
+                    if (messageIds.has(row.message_id))
+                        throw new ContextOverflowRecoveryError("duplicate_message_id", "canonical Inbox contains duplicate message identities");
+                    messageIds.add(row.message_id);
+                }
+                const ledger = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                if (!Array.isArray(ledger.records))
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "Runtime delivery ledger is malformed");
+                const ledgerRecords = ledger.records;
+                const matches = new Map();
+                const deliveryIds = new Set();
+                const inputIds = new Set();
+                for (const candidate of ledger.records) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        continue;
+                    if (typeof record.deliveryId !== "string" || !record.deliveryId)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a matching Runtime delivery record has no delivery identity");
+                    if (!record.input || typeof record.input !== "object" || Array.isArray(record.input)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has no Runtime input identity");
+                    }
+                    const input = record.input;
+                    if (typeof input.inputId !== "string" || !input.inputId.trim()
+                        || typeof input.deliveryId !== "string" || input.deliveryId !== record.deliveryId) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has malformed input identity");
+                    }
+                    if (matches.has(record.messageId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a canonical Inbox row maps to multiple delivery records");
+                    if (deliveryIds.has(record.deliveryId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "matching Runtime delivery records share a delivery identity");
+                    if (inputIds.has(input.inputId))
+                        throw new ContextOverflowRecoveryError("duplicate_input_id", "matching Runtime delivery records share an input identity");
+                    deliveryIds.add(record.deliveryId);
+                    inputIds.add(input.inputId);
+                    matches.set(record.messageId, record);
+                }
+                if (expected?.messageId && !messageIds.has(expected.messageId)) {
+                    throw new ContextOverflowRecoveryError("delivery_missing", "the expected context-overflow message is not in canonical Inbox");
+                }
+                if (expected?.messageId) {
+                    const expectedRecord = matches.get(expected.messageId);
+                    if (!expectedRecord || (expected.deliveryId && expectedRecord.deliveryId !== expected.deliveryId)
+                        || (expected.inputId && expectedRecord.input.inputId !== expected.inputId)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "the expected context-overflow delivery identity changed");
+                    }
+                }
+                for (const messageId of messageIds) {
+                    const record = matches.get(messageId);
+                    if (!record)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a canonical Inbox row has no Runtime delivery record");
+                    if (record.status !== "error" || record.retryable === true) {
+                        throw new ContextOverflowRecoveryError("delivery_not_terminal", "a canonical Inbox row is not backed by a non-retryable terminal Runtime error");
+                    }
+                    const reasonCategory = classifyStrictProviderError(buildStrictProviderErrorInput({
+                        reason: record.reason, errorCategory: record.errorCategory,
+                    }));
+                    if (record.retryable !== false || reasonCategory !== "context_window"
+                        || (record.errorCategory !== undefined && record.errorCategory !== "context_window")) {
+                        throw new ContextOverflowRecoveryError("delivery_not_context_window", "a Runtime delivery error is not classified as context_window");
+                    }
+                }
+                for (const candidate of ledgerRecords) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.deliveryId === "string" && deliveryIds.has(record.deliveryId)
+                        && (typeof record.messageId !== "string" || !messageIds.has(record.messageId))) {
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a matching delivery identity is also used by an unrelated Runtime delivery record");
+                    }
+                }
+                const updatedAt = new Date().toISOString();
+                const records = ledgerRecords.map((candidate) => {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        return candidate;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        return candidate;
+                    return { ...record, status: "pending", retryable: true, updatedAt };
+                });
+                const committedLedger = { ...ledger, records };
+                let restored = false;
+                const restoreUnlocked = () => {
+                    if (restored)
+                        return;
+                    const current = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                    if (!Array.isArray(current.records))
+                        throw new Error("Runtime delivery rollback found a malformed ledger");
+                    const originalMatching = ledgerRecords.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return typeof record.messageId === "string" && messageIds.has(record.messageId);
+                    });
+                    const originalDeliveryIds = new Set(originalMatching.flatMap((candidate) => {
+                        const deliveryId = candidate.deliveryId;
+                        return typeof deliveryId === "string" ? [deliveryId] : [];
+                    }));
+                    const currentMatching = current.records.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return (typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                            || (typeof record.messageId === "string" && messageIds.has(record.messageId));
+                    });
+                    const matchingRestored = currentMatching.length === originalMatching.length
+                        && currentMatching.every((candidate, index) => JSON.stringify(candidate) === JSON.stringify(originalMatching[index]));
+                    if (!matchingRestored) {
+                        const unrelated = current.records.filter((candidate) => {
+                            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                                return true;
+                            const record = candidate;
+                            return !((typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                                || (typeof record.messageId === "string" && messageIds.has(record.messageId)));
+                        });
+                        const restoredRecords = [...unrelated];
+                        for (const candidate of originalMatching) {
+                            const originalIndex = ledgerRecords.indexOf(candidate);
+                            restoredRecords.splice(Math.min(originalIndex, restoredRecords.length), 0, candidate);
+                        }
+                        this.writeJson("runtimeDeliveries", { ...current, records: restoredRecords });
+                    }
+                    restored = true;
+                };
+                const rollback = () => {
+                    if (lockActive)
+                        restoreUnlocked();
+                    else
+                        this.withInboxTransaction(restoreUnlocked);
+                };
+                try {
+                    this.writeJson("runtimeDeliveries", committedLedger);
+                    onCommit?.([...messageIds], rollback);
+                }
+                catch (error) {
+                    try {
+                        rollback();
+                    }
+                    catch {
+                        throw new Error("context-window recovery ledger rollback failed");
+                    }
+                    throw error;
+                }
+                return { rearmedCount: messageIds.size, remainingPendingCount: rows.length };
+            });
+        }
+        finally {
+            lockActive = false;
+        }
+    }
     /**
      * Recoverably bridge an outbox wake into the canonical Inbox. A durable
      * Runtime ledger is authoritative after the Inbox has been drained, so a

package/dist/app/agent-config.mjs

@@ -11,6 +11,8 @@ import { isChannelReconnecting, projectAgentReadiness } from "./agent-readiness.
 import { requestAgentUpsert } from "./local-control.mjs";
 import * as larkinConfig from "../platform/config.mjs";
 import { managedOfficialLarkCli } from "./agent-lark-cli-workspace.mjs";
+import { assertBuiltinPiAgentDirectory, piAgentDirectory } from "../runtime/pi-provider-config.mjs";
+import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 function safeDocumentCommentCapabilities(configDir, profile) {
     try {
         return {
@@ -49,15 +51,15 @@ const die = (message) => {
         console.error("  下一步: larkin config --help");
     process.exit(1);
 };
-if (!kind || !["agents", "model", "runtime", "effort", "chats", "config"].includes(kind)) {
-    die("用法: larkin agents | larkin config <show|mention|apply> | larkin model [<id>] | larkin runtime [<id>] [--model <id>] | larkin effort [<level>|clear] | larkin chats [free|strict <oc_id>]");
+if (!kind || !["agents", "model", "runtime", "effort", "pi-distribution", "chats", "config"].includes(kind)) {
+    die("用法: larkin agents | larkin config <show|mention|apply> | larkin model [<id>] | larkin runtime [<id>] [--model <id>] | larkin pi-distribution [show|builtin|external] | larkin effort [<level>|clear] | larkin chats [free|strict <oc_id>]");
 }
 const allowedValueFlags = {
     agents: new Set(), model: new Set(["--agent"]), runtime: new Set(["--agent", "--model"]),
-    effort: new Set(["--agent"]), chats: new Set(["--agent"]), config: new Set(["--agent", "--chat"]),
+    effort: new Set(["--agent"]), "pi-distribution": new Set(["--agent", "--snapshot"]), chats: new Set(["--agent"]), config: new Set(["--agent", "--chat"]),
 };
 const allowedBooleanFlags = {
-    agents: new Set(["--json"]), model: new Set(), runtime: new Set(), effort: new Set(), chats: new Set(), config: new Set(["--json"]),
+    agents: new Set(["--json"]), model: new Set(), runtime: new Set(), effort: new Set(), "pi-distribution": new Set(["--import-external-profile"]), chats: new Set(), config: new Set(["--json"]),
 };
 const parsedValues = new Map();
 const parsedBooleans = new Set();
@@ -91,6 +93,7 @@ const flagAgent = parsedValues.get("--agent");
 const flagModel = parsedValues.get("--model");
 const flagChat = parsedValues.get("--chat");
 const flagJson = parsedBooleans.has("--json");
+const importExternalProfile = parsedBooleans.has("--import-external-profile");
 const value = positionals[0];
 function assertOnlyFlags(valueFlags, booleanFlags = []) {
     const allowedValues = new Set(valueFlags);
@@ -122,6 +125,11 @@ else if (kind === "effort") {
     if (positionals.length > 1)
         die("用法: larkin effort [<level>|clear|default] [--agent <App ID>]");
 }
+else if (kind === "pi-distribution") {
+    assertOnlyFlags(["--agent", "--snapshot"], ["--import-external-profile"]);
+    if (positionals.length > 1)
+        die("用法: larkin pi-distribution [show|builtin|external] [--agent <App ID>] [--snapshot <private-file>]");
+}
 else if (kind === "chats") {
     assertOnlyFlags(["--agent"]);
     if (![0, 2].includes(positionals.length))
@@ -169,6 +177,21 @@ const loaded = (() => {
 const { configDir, file, config } = loaded;
 if (!fs.existsSync(file))
     die("未找到 Larkin 配置，请运行 larkin setup");
+const snapshotFile = parsedValues.get("--snapshot");
+if (kind === "pi-distribution" && value === "rollback") {
+    if (importExternalProfile)
+        die("--import-external-profile 只允许与 builtin 一起使用");
+    if (!snapshotFile || flagAgent || positionals.length !== 1)
+        die("用法: larkin pi-distribution rollback --snapshot <private-file>");
+    try {
+        const result = larkinConfig.rollbackConfig(process.env, snapshotFile);
+        say(JSON.stringify({ ok: true, rolledBackAgent: result.agentId, revision: result.revision }));
+    }
+    catch (error) {
+        die(`回滚失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exit(0);
+}
 if (kind === "agents") {
     const list = Object.values(config.agents || {});
     const daemon = readProcessState(config.larkinHome).daemon;
@@ -266,12 +289,19 @@ if (kind === "agents") {
             && !!status?.inboundVerifiedAt
             && Date.parse(status.inboundVerifiedAt) >= Date.parse(String(daemon.startedAt || 0));
         const commentDiagnostic = projectDocumentCommentDiagnostic(commentCapability, status);
+        const projectedReadiness = projectAgentReadiness({ agentId: agent.agentId, daemon, status });
         say(`  ${agent.name}${agent.name === config.activeAgent ? " [active]" : ""}`);
         const effectiveModel = status?.session?.runtime === agent.runtime && status.session.model ? status.session.model : agent.model;
         const effectiveEffort = status?.session?.runtime === agent.runtime && status.session.reasoningEffort ? status.session.reasoningEffort : agent.effort;
         say(`    runtime=${agent.runtime}  model=${effectiveModel}${effectiveModel !== agent.model ? `  stored=${agent.model}` : ""}${effectiveEffort ? `  effort=${effectiveEffort}` : ""}`);
-        if (status?.runtimeReadiness)
-            say(`    runtime readiness=${status.runtimeReadiness.state || "incompatible"}${status.runtimeReadiness.reason ? `：${status.runtimeReadiness.reason}` : ""}${status.runtimeReadiness.nextAction ? `；下一步：${status.runtimeReadiness.nextAction}` : ""}`);
+        if (status?.runtimeReadiness) {
+            const current = projectedReadiness.readiness.runtime_ready;
+            const state = status.runtimeReadiness.state === "ready" && !current ? "unavailable" : status.runtimeReadiness.state || "incompatible";
+            const staleReason = status.runtimeReadiness.state === "ready" && !current
+                ? "：ready 证据不属于当前 owned daemon epoch 或当前 session，已拒绝展示为 ready"
+                : status.runtimeReadiness.reason ? `：${status.runtimeReadiness.reason}` : "";
+            say(`    runtime readiness=${state}${staleReason}${status.runtimeReadiness.nextAction ? `；下一步：${status.runtimeReadiness.nextAction}` : ""}`);
+        }
         if (status?.runtimeReadiness?.executable)
             say(`    runtime executable=${status.runtimeReadiness.executable}${status.runtimeReadiness.version ? `  version=${status.runtimeReadiness.version}` : ""}`);
         say(`    bot=${bot ? `${bot.name}(${bot.open_id})` : "（未连接过，无身份缓存）"}`);
@@ -405,6 +435,43 @@ if (!key) {
 }
 const selectedKey = key;
 const agent = config.agents[selectedKey];
+if (kind === "pi-distribution") {
+    traceProcessBoundary(process.env, "agent-config:pi-distribution-loaded", { configDir, agentId: selectedKey, targetDir: piAgentDirectory(configDir, selectedKey), requested: value || "show", importExternalProfile });
+    const requested = value || "show";
+    if (importExternalProfile && requested !== "builtin")
+        die("--import-external-profile 只允许与 builtin 一起使用");
+    if (requested === "show") {
+        say(JSON.stringify({ agentId: selectedKey, runtime: agent.runtime, piDistribution: agent.piDistribution ?? "external" }));
+        process.exit(0);
+    }
+    if (requested !== "builtin" && requested !== "external")
+        die("Pi distribution 只允许 show/builtin/external");
+    if (agent.runtime !== "pi")
+        die(`Agent ${selectedKey} 不是 Pi runtime`);
+    if (!snapshotFile)
+        die("修改 Pi distribution 必须提供 --snapshot <private-file>");
+    if (requested === "builtin" && !importExternalProfile) {
+        try {
+            assertBuiltinPiAgentDirectory(piAgentDirectory(configDir, selectedKey));
+        }
+        catch {
+            die("内置 Pi provider 尚未为该 Agent 配置；请先运行 larkin setup 完成内置 Pi provider 配置，或使用 --import-external-profile");
+        }
+    }
+    try {
+        const result = larkinConfig.mutateConfig(process.env, { kind: "set-agent-pi-distribution", agentId: selectedKey, distribution: requested }, { kind: "user" }, {
+            snapshotFile: snapshotFile, ...(importExternalProfile ? { importExternalProfile: true } : {}),
+        });
+        traceProcessBoundary(process.env, "agent-config:pi-distribution-persisted", { configDir, agentId: selectedKey, targetDir: piAgentDirectory(configDir, selectedKey), requested, applyState: result.applyState });
+        say(JSON.stringify({ ok: true, agentId: selectedKey, piDistribution: requested, revision: result.revision, applyState: result.applyState }));
+    }
+    catch (error) {
+        if (importExternalProfile)
+            die("Pi external profile import failed; no secret or private path was disclosed");
+        die(`Pi distribution 修改失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exit(0);
+}
 const catalog = larkinConfig.loadRuntimeModels();
 if ((["model", "effort"].includes(kind || "") && agent.runtime === "codex") || (kind === "runtime" && value === "codex")) {
     try {

package/dist/app/agent-readiness.cjs

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRuntimeReadinessCurrent = isRuntimeReadinessCurrent;
+exports.isCurrentOwnedDaemon = isCurrentOwnedDaemon;
 exports.isChannelReconnecting = isChannelReconnecting;
 exports.projectAgentReadiness = projectAgentReadiness;
 const process_state_js_1 = require("../platform/process-state.cjs");
@@ -7,6 +9,19 @@ function timestamp(value) {
     const parsed = Date.parse(String(value || ""));
     return Number.isFinite(parsed) ? parsed : null;
 }
+function isRuntimeReadinessCurrent(readiness, daemonStartedAt) {
+    if (readiness?.state !== "ready")
+        return false;
+    const observedAt = timestamp(readiness.observedAt);
+    const epoch = timestamp(daemonStartedAt);
+    return observedAt !== null && epoch !== null && observedAt >= epoch;
+}
+function isCurrentOwnedDaemon(daemon) {
+    return daemon?.state === "owned"
+        && Number(daemon.pid) > 0
+        && typeof daemon.processStartToken === "string" && daemon.processStartToken.length > 0
+        && timestamp(daemon.startedAt) !== null;
+}
 function isChannelReconnecting(status) {
     const reconnectingAt = timestamp(status?.reconnectingAt);
     const connectedAt = timestamp(status?.connectedAt);
@@ -16,9 +31,14 @@ function isChannelReconnecting(status) {
 }
 function projectAgentReadiness(input) {
     const status = input.status ?? null;
-    const daemonOwned = (0, process_state_js_1.daemonHasAgent)(input.daemon, input.agentId);
+    const daemonOwned = isCurrentOwnedDaemon(input.daemon) && (0, process_state_js_1.daemonHasAgent)(input.daemon, input.agentId);
     const daemonStartedAt = timestamp(input.daemon.startedAt);
     const connectedAt = timestamp(status?.connectedAt);
+    // A resumed session deliberately retains its original creation time.  Its
+    // current daemon-epoch proof is the fresh session observation, not that
+    // historic creation timestamp.
+    const sessionObservedAt = timestamp(status?.session?.lastSeenAt) ?? timestamp(status?.session?.startedAt);
+    const sessionCurrent = daemonStartedAt !== null && sessionObservedAt !== null && sessionObservedAt >= daemonStartedAt;
     const channelConnected = daemonOwned
         && status?.connectedVia === "channel"
         && daemonStartedAt !== null
@@ -26,7 +46,7 @@ function projectAgentReadiness(input) {
         && connectedAt >= daemonStartedAt;
     const readiness = {
         daemon_owned: daemonOwned,
-        runtime_ready: status?.runtimeReadiness?.state === "ready",
+        runtime_ready: daemonOwned && sessionCurrent && isRuntimeReadinessCurrent(status?.runtimeReadiness, input.daemon.startedAt),
         channel_connected: channelConnected,
         channel_not_reconnecting: !isChannelReconnecting(status),
     };