larkin 0.4.1 → 0.4.2

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

@@ -0,0 +1,623 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PiCompactionRecoveryMachine = exports.PiCompactionBreaker = exports.PI_COMPACTION_RECOVERY_FILE = exports.PI_COMPACTION_RECOVERY_VERSION = exports.PI_COMPACTION_THRESHOLD = exports.COMPACTION_KEEP_RECENT_TOKENS = exports.COMPACTION_RESERVE_TOKENS = exports.PI_CONTEXT_WINDOW = void 0;
+exports.isPiNativeCompactionRequired = isPiNativeCompactionRequired;
+exports.assertEffectivePiCompactionSettings = assertEffectivePiCompactionSettings;
+exports.hasProjectPiCompactionOverride = hasProjectPiCompactionOverride;
+exports.ensureOwnedPiAgentDirectory = ensureOwnedPiAgentDirectory;
+exports.ownedPiSettings = ownedPiSettings;
+exports.prepareOwnedPiDirectory = prepareOwnedPiDirectory;
+exports.writeOwnedPiSettings = writeOwnedPiSettings;
+exports.readOwnedPiSettings = readOwnedPiSettings;
+exports.verifyPiCapabilities = verifyPiCapabilities;
+exports.prepareOwnedPiEnvironment = prepareOwnedPiEnvironment;
+exports.readProjectPiSettings = readProjectPiSettings;
+exports.assertNoProjectPiCompactionOverride = assertNoProjectPiCompactionOverride;
+exports.currentUserLabel = currentUserLabel;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.PI_CONTEXT_WINDOW = 272_000;
+exports.COMPACTION_RESERVE_TOKENS = 40_800;
+exports.COMPACTION_KEEP_RECENT_TOKENS = 20_000;
+exports.PI_COMPACTION_THRESHOLD = exports.PI_CONTEXT_WINDOW - exports.COMPACTION_RESERVE_TOKENS;
+exports.PI_COMPACTION_RECOVERY_VERSION = 1;
+exports.PI_COMPACTION_RECOVERY_FILE = "piCompactionRecovery.json";
+const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
+const REQUIRED_PI_EVENTS = ["compaction_start", "compaction_end", "agent_end", "agent_settled"];
+const TERMINAL_STATES = new Set(["closed", "fallback_committed"]);
+const ALLOWED_TRANSITIONS = {
+    eligible: ["native_compacting", "native_retry_owned", "settled_for_manual"],
+    native_compacting: ["native_retry_owned", "native_succeeded", "native_failed"],
+    native_retry_owned: ["native_compacting", "native_succeeded", "native_failed"],
+    native_succeeded: ["closed"],
+    native_failed: ["fallback_required", "fallback_committed"],
+    settled_for_manual: ["manual_sent"],
+    manual_sent: ["manual_succeeded", "manual_failed", "manual_ambiguous"],
+    manual_succeeded: ["retrying", "second_overflow"],
+    manual_failed: ["fallback_required", "fallback_committed"],
+    manual_ambiguous: ["fallback_required", "fallback_committed"],
+    retrying: ["second_overflow", "closed"],
+    second_overflow: ["fallback_required", "fallback_committed"],
+    fallback_required: ["fallback_committed"],
+    fallback_committed: ["closed"],
+    closed: [],
+};
+function requireFiniteBoolean(value, name) {
+    if (typeof value !== "boolean")
+        throw new Error(`${name} must be a boolean`);
+    return value;
+}
+function isPiNativeCompactionRequired(contextTokens) {
+    return Number.isFinite(contextTokens) && contextTokens > exports.PI_COMPACTION_THRESHOLD;
+}
+function assertEffectivePiCompactionSettings(settings) {
+    const contextWindow = settings.contextWindow ?? settings.model?.contextWindow;
+    if (contextWindow !== exports.PI_CONTEXT_WINDOW)
+        throw new Error(`Pi effective context window must be exactly ${exports.PI_CONTEXT_WINDOW}`);
+    if (settings.compaction?.enabled !== true)
+        throw new Error("Pi native compaction must be enabled");
+    if (settings.compaction.reserveTokens !== exports.COMPACTION_RESERVE_TOKENS) {
+        throw new Error(`Pi reserveTokens must be exactly ${exports.COMPACTION_RESERVE_TOKENS}`);
+    }
+    if (settings.compaction.keepRecentTokens !== exports.COMPACTION_KEEP_RECENT_TOKENS) {
+        throw new Error(`Pi keepRecentTokens must be exactly ${exports.COMPACTION_KEEP_RECENT_TOKENS}`);
+    }
+}
+function hasProjectPiCompactionOverride(settings) {
+    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+        return false;
+    const value = settings;
+    if (Object.hasOwn(value, "contextWindow") || Object.hasOwn(value, "contextTokens")
+        || Object.hasOwn(value, "reserveTokens") || Object.hasOwn(value, "keepRecentTokens"))
+        return true;
+    const compaction = value.compaction;
+    return Boolean(compaction && typeof compaction === "object" && !Array.isArray(compaction)
+        && ["enabled", "reserveTokens", "keepRecentTokens"].some((key) => Object.hasOwn(compaction, key)));
+}
+function assertOwnedDirectory(directory) {
+    const stat = node_fs_1.default.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`Pi Agent directory is unsafe: ${directory}`);
+    if (process.platform !== "win32" && ((typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o777) !== 0o700))
+        throw new Error("Pi Agent directory must be owner-only 0700");
+}
+function ensureDirectory(directory) {
+    try {
+        const existing = node_fs_1.default.lstatSync(directory);
+        if (existing.isSymbolicLink() || !existing.isDirectory())
+            throw new Error(`unsafe Pi Agent directory: ${directory}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        node_fs_1.default.mkdirSync(directory, { mode: 0o700 });
+    }
+    node_fs_1.default.chmodSync(directory, 0o700);
+    assertOwnedDirectory(directory);
+}
+function ensureDirectoryChain(directory) {
+    const resolved = node_path_1.default.resolve(directory);
+    const root = node_path_1.default.parse(resolved).root;
+    let current = root;
+    for (const part of node_path_1.default.relative(root, resolved).split(node_path_1.default.sep).filter(Boolean)) {
+        current = node_path_1.default.join(current, part);
+        try {
+            const stat = node_fs_1.default.lstatSync(current);
+            // macOS exposes /tmp and /var as stable system aliases; all deeper
+            // Larkin-controlled ancestors remain strictly no-symlink.
+            const knownSystemSymlink = current === "/tmp" || current === "/var" || current === "/private/tmp" || current === "/private/var";
+            const systemAlias = knownSystemSymlink
+                || current === "/var/folders" || /^\/var\/folders\/[^/]+$/.test(current)
+                || current === "/private/var/folders" || /^\/private\/var\/folders\/[^/]+$/.test(current);
+            if ((!knownSystemSymlink && stat.isSymbolicLink()) || (!systemAlias && !stat.isDirectory())) {
+                throw new Error(`unsafe Pi Agent ancestor: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            node_fs_1.default.mkdirSync(current, { mode: 0o700 });
+            const created = node_fs_1.default.lstatSync(current);
+            if (created.isSymbolicLink() || !created.isDirectory())
+                throw new Error(`unsafe Pi Agent ancestor: ${current}`);
+        }
+    }
+}
+function ensureOwnedPiAgentDirectory(root, agentId) {
+    if (!AGENT_ID.test(agentId))
+        throw new Error("invalid Pi Agent ID");
+    const resolvedRoot = node_path_1.default.resolve(root);
+    ensureDirectory(resolvedRoot);
+    const parent = node_path_1.default.join(resolvedRoot, "pi-agents");
+    ensureDirectory(parent);
+    const directory = node_path_1.default.join(parent, agentId);
+    ensureDirectory(directory);
+    return directory;
+}
+function ownedPiSettings(directory) {
+    return node_path_1.default.join(directory, "settings.json");
+}
+function prepareOwnedPiDirectory(directory) {
+    ensureDirectoryChain(node_path_1.default.dirname(directory));
+    ensureDirectory(node_path_1.default.dirname(directory));
+    ensureDirectory(directory);
+    writeOwnedPiSettings(directory);
+    return directory;
+}
+function writeOwnedPiSettings(directory) {
+    assertOwnedDirectory(directory);
+    const file = ownedPiSettings(directory);
+    try {
+        const existing = node_fs_1.default.lstatSync(file);
+        if (existing.isSymbolicLink() || !existing.isFile())
+            throw new Error("Pi owned settings must not be a symlink");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const temporary = node_path_1.default.join(directory, `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
+    try {
+        node_fs_1.default.writeFileSync(temporary, `${JSON.stringify({
+            compaction: {
+                enabled: true,
+                reserveTokens: exports.COMPACTION_RESERVE_TOKENS,
+                keepRecentTokens: exports.COMPACTION_KEEP_RECENT_TOKENS,
+            },
+        }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        node_fs_1.default.renameSync(temporary, file);
+        node_fs_1.default.chmodSync(file, 0o600);
+    }
+    finally {
+        try {
+            node_fs_1.default.unlinkSync(temporary);
+        }
+        catch { /* renamed or absent */ }
+    }
+}
+function readOwnedPiSettings(directory) {
+    const file = ownedPiSettings(directory);
+    const stat = node_fs_1.default.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error("Pi owned settings must be a regular file");
+    const parsed = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Pi owned settings are invalid");
+    const compaction = parsed.compaction;
+    if (!compaction || typeof compaction !== "object" || Array.isArray(compaction))
+        throw new Error("Pi owned compaction settings are missing");
+    const values = compaction;
+    const enabled = requireFiniteBoolean(values.enabled, "Pi owned compaction enabled");
+    if (typeof values.reserveTokens !== "number" || typeof values.keepRecentTokens !== "number") {
+        throw new Error("Pi owned compaction reserve/keep settings are invalid");
+    }
+    return { compaction: { enabled, reserveTokens: values.reserveTokens, keepRecentTokens: values.keepRecentTokens } };
+}
+function verifyPiCapabilities(capabilities) {
+    if (!/(?:^|\D)0\.83\.0(?:$|\D)/.test(capabilities.version || "")) {
+        throw new Error("trusted Pi version 0.83.0 is required");
+    }
+    const contextWindow = capabilities.contextWindow ?? capabilities.model?.contextWindow;
+    if (contextWindow !== exports.PI_CONTEXT_WINDOW)
+        throw new Error("Pi capability context window is not 272000");
+    if (requireFiniteBoolean(capabilities.autoCompactionEnabled, "Pi autoCompactionEnabled") !== true) {
+        throw new Error("Pi effective native compaction is disabled");
+    }
+    if (capabilities.compactRpc !== true)
+        throw new Error("Pi compact RPC capability is missing");
+    if (capabilities.trustedProtocol !== true) {
+        if (capabilities.reserveTokens !== exports.COMPACTION_RESERVE_TOKENS
+            || capabilities.keepRecentTokens !== exports.COMPACTION_KEEP_RECENT_TOKENS) {
+            throw new Error("Pi external effective compaction reserve/keep settings are unproven");
+        }
+        const events = new Set(capabilities.events || []);
+        for (const event of REQUIRED_PI_EVENTS)
+            if (!events.has(event))
+                throw new Error(`Pi capability event is unproven: ${event}`);
+    }
+}
+function stateFile(root) {
+    return node_path_1.default.join(root, exports.PI_COMPACTION_RECOVERY_FILE);
+}
+function assertStableIdentity(value, name) {
+    if (typeof value !== "string" || value.trim() === "" || value.length > 512 || /[\u0000\r\n]/.test(value)) {
+        throw new Error(`invalid stable Pi compaction identity: ${name}`);
+    }
+}
+function safeRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid Pi compaction breaker record");
+    const record = value;
+    const manualAttempt = record.manualAttempt;
+    const sessionGeneration = record.sessionGeneration;
+    try {
+        assertStableIdentity(record.key, "key");
+        assertStableIdentity(record.messageId, "messageId");
+        assertStableIdentity(record.deliveryId, "deliveryId");
+        assertStableIdentity(record.inputId, "inputId");
+    }
+    catch {
+        throw new Error("invalid Pi compaction breaker identity");
+    }
+    if (typeof sessionGeneration !== "number" || !Number.isSafeInteger(sessionGeneration)
+        || typeof record.state !== "string" || typeof manualAttempt !== "number" || !Number.isSafeInteger(manualAttempt)
+        || manualAttempt < 0 || manualAttempt > 1 || typeof record.updatedAt !== "string") {
+        throw new Error("invalid Pi compaction breaker identity");
+    }
+    if (record.compactSentAt !== null && typeof record.compactSentAt !== "string")
+        throw new Error("invalid compactSentAt");
+    if (record.compactDeadlineAt !== null && typeof record.compactDeadlineAt !== "string")
+        throw new Error("invalid compactDeadlineAt");
+    if (record.compactFinishedAt !== null && typeof record.compactFinishedAt !== "string")
+        throw new Error("invalid compactFinishedAt");
+    if (record.retrySubmittedAt !== null && typeof record.retrySubmittedAt !== "string")
+        throw new Error("invalid retrySubmittedAt");
+    if (record.fallbackReason !== null && typeof record.fallbackReason !== "string")
+        throw new Error("invalid fallbackReason");
+    if (record.compactResponseReceived !== undefined && typeof record.compactResponseReceived !== "boolean")
+        throw new Error("invalid compactResponseReceived");
+    if (record.compactionLifecycleSucceeded !== undefined && typeof record.compactionLifecycleSucceeded !== "boolean")
+        throw new Error("invalid compactionLifecycleSucceeded");
+    if (!(new Set([
+        "eligible", "native_compacting", "native_retry_owned", "native_succeeded", "native_failed", "settled_for_manual",
+        "manual_sent", "manual_succeeded", "manual_failed", "manual_ambiguous", "retrying", "second_overflow",
+        "fallback_required", "fallback_committed", "closed",
+    ])).has(record.state))
+        throw new Error("unknown Pi compaction breaker state");
+    return {
+        key: record.key, messageId: record.messageId, deliveryId: record.deliveryId, inputId: record.inputId,
+        sessionGeneration: sessionGeneration, state: record.state,
+        manualAttempt: manualAttempt, compactSentAt: record.compactSentAt ?? null,
+        compactDeadlineAt: record.compactDeadlineAt ?? null, compactFinishedAt: record.compactFinishedAt ?? null,
+        retrySubmittedAt: record.retrySubmittedAt ?? null, fallbackReason: record.fallbackReason ?? null,
+        ...(record.compactResponseReceived !== undefined ? { compactResponseReceived: record.compactResponseReceived } : {}),
+        ...(record.compactionLifecycleSucceeded !== undefined ? { compactionLifecycleSucceeded: record.compactionLifecycleSucceeded } : {}),
+        updatedAt: record.updatedAt,
+    };
+}
+class PiCompactionBreaker {
+    root;
+    file;
+    clock;
+    records;
+    withLock;
+    constructor(root, options = {}) {
+        this.root = root;
+        node_fs_1.default.mkdirSync(root, { recursive: true, mode: 0o700 });
+        node_fs_1.default.chmodSync(root, 0o700);
+        ensureDirectory(root);
+        this.file = stateFile(root);
+        this.clock = options.now ?? (() => new Date().toISOString());
+        this.records = new Map(this.read().records.map((record) => [record.key, record]));
+        this.retentionMs = options.retentionMs ?? 30 * 24 * 60 * 60 * 1000;
+        this.withLock = options.withLock ?? ((operation) => operation());
+    }
+    retentionMs;
+    read() {
+        try {
+            const stat = node_fs_1.default.lstatSync(this.file);
+            if (stat.isSymbolicLink() || !stat.isFile())
+                throw new Error("Pi compaction breaker must be a regular file");
+            if (process.platform !== "win32" && ((typeof process.getuid === "function" && stat.uid !== process.getuid())
+                || (stat.mode & 0o777) !== 0o600))
+                throw new Error("Pi compaction breaker must be owner-only 0600");
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(this.file, "utf8"));
+            if (parsed.version !== 1 || !Array.isArray(parsed.records))
+                throw new Error("unknown Pi compaction breaker version");
+            return { version: 1, records: parsed.records.map(safeRecord) };
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { version: 1, records: [] };
+            throw error;
+        }
+    }
+    persist() {
+        const temporary = node_path_1.default.join(this.root, `.${node_path_1.default.basename(this.file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
+        const content = `${JSON.stringify({ version: 1, records: [...this.records.values()] }, null, 2)}\n`;
+        let descriptor = null;
+        try {
+            descriptor = node_fs_1.default.openSync(temporary, "wx", 0o600);
+            node_fs_1.default.writeFileSync(descriptor, content);
+            node_fs_1.default.fsyncSync(descriptor);
+            node_fs_1.default.closeSync(descriptor);
+            descriptor = null;
+            node_fs_1.default.renameSync(temporary, this.file);
+            node_fs_1.default.chmodSync(this.file, 0o600);
+            const stat = node_fs_1.default.lstatSync(this.file);
+            if (stat.isSymbolicLink() || (process.platform !== "win32" && (stat.mode & 0o777) !== 0o600))
+                throw new Error("Pi compaction breaker write verification failed");
+        }
+        finally {
+            if (descriptor !== null) {
+                try {
+                    node_fs_1.default.closeSync(descriptor);
+                }
+                catch { /* preserve primary error */ }
+            }
+            try {
+                node_fs_1.default.unlinkSync(temporary);
+            }
+            catch { /* renamed or absent */ }
+        }
+    }
+    reload() {
+        this.records = new Map(this.read().records.map((record) => [record.key, record]));
+    }
+    get(key) {
+        return this.withLock(() => { this.reload(); const record = this.records.get(key); return record ? { ...record } : undefined; });
+    }
+    listNonTerminal() {
+        return this.withLock(() => { this.reload(); return [...this.records.values()].filter((record) => !TERMINAL_STATES.has(record.state)).map((record) => ({ ...record })); });
+    }
+    save(record) {
+        this.withLock(() => { this.reload(); const checked = safeRecord({ ...record, updatedAt: this.clock() }); this.records.set(checked.key, checked); this.persist(); });
+    }
+    transitionUnlocked(key, patch, state) {
+        this.reload();
+        const current = this.records.get(key);
+        if (!current) {
+            const sessionGeneration = patch.sessionGeneration;
+            if (state !== "eligible" || !patch.messageId || !patch.deliveryId || !patch.inputId
+                || typeof sessionGeneration !== "number" || !Number.isSafeInteger(sessionGeneration)) {
+                throw new Error("invalid initial Pi compaction breaker transition");
+            }
+            const record = {
+                key, messageId: patch.messageId, deliveryId: patch.deliveryId, inputId: patch.inputId,
+                sessionGeneration, state, manualAttempt: 0,
+                compactSentAt: null, compactDeadlineAt: null, compactFinishedAt: null, retrySubmittedAt: null,
+                fallbackReason: null, updatedAt: this.clock(),
+            };
+            this.records.set(key, record);
+            this.persist();
+            return { ...record };
+        }
+        if (current.state === state)
+            throw new Error(`duplicate Pi compaction transition: ${state}`);
+        if (TERMINAL_STATES.has(current.state))
+            throw new Error(`Pi compaction breaker is terminal: ${current.state}`);
+        if (!ALLOWED_TRANSITIONS[current.state].includes(state))
+            throw new Error(`invalid Pi compaction transition ${current.state} -> ${state}`);
+        const next = { ...current, ...patch, key, state, updatedAt: this.clock() };
+        if (next.key !== current.key || next.messageId !== current.messageId || next.deliveryId !== current.deliveryId
+            || next.inputId !== current.inputId || next.sessionGeneration !== current.sessionGeneration) {
+            throw new Error("Pi compaction breaker stable identity is immutable");
+        }
+        if (state === "manual_sent") {
+            if (current.state !== "settled_for_manual" || current.manualAttempt >= 1)
+                throw new Error("manual compact attempt already used");
+            next.manualAttempt = 1;
+        }
+        safeRecord(next);
+        this.records.set(key, next);
+        this.persist();
+        return { ...next };
+    }
+    transition(key, patch, state) {
+        return this.withLock(() => this.transitionUnlocked(key, patch, state));
+    }
+    transitionInTransaction(key, patch, state) {
+        return this.transitionUnlocked(key, patch, state);
+    }
+    prune(consumedKeys = []) {
+        return this.withLock(() => this.pruneUnlocked(consumedKeys));
+    }
+    pruneUnlocked(consumedKeys = []) {
+        this.reload();
+        const consumed = new Set(consumedKeys);
+        const cutoff = Date.parse(this.clock()) - this.retentionMs;
+        let count = 0;
+        for (const [key, record] of this.records) {
+            if (!TERMINAL_STATES.has(record.state) || !consumed.has(key))
+                continue;
+            if (!Number.isFinite(cutoff) || Date.parse(record.updatedAt) > cutoff)
+                continue;
+            this.records.delete(key);
+            count += 1;
+        }
+        if (count)
+            this.persist();
+        return count;
+    }
+    forceFallback(key, reason) {
+        return this.withLock(() => {
+            this.reload();
+            const current = this.records.get(key);
+            if (!current)
+                throw new Error("Pi compaction breaker record is missing");
+            if (TERMINAL_STATES.has(current.state))
+                return { ...current };
+            const next = { ...current, state: "fallback_required", fallbackReason: reason, updatedAt: this.clock() };
+            safeRecord(next);
+            this.records.set(key, next);
+            this.persist();
+            return { ...next };
+        });
+    }
+    forceFallbackInTransaction(key, reason) {
+        this.reload();
+        const current = this.records.get(key);
+        if (!current)
+            throw new Error("Pi compaction breaker record is missing");
+        if (TERMINAL_STATES.has(current.state))
+            return { ...current };
+        const next = { ...current, state: "fallback_committed", fallbackReason: reason, updatedAt: this.clock() };
+        safeRecord(next);
+        this.records.set(key, next);
+        this.persist();
+        return { ...next };
+    }
+}
+exports.PiCompactionBreaker = PiCompactionBreaker;
+class PiCompactionRecoveryMachine {
+    key;
+    record;
+    breaker;
+    onAction;
+    constructor(input) {
+        this.key = input.key;
+        this.breaker = input.breaker;
+        this.onAction = input.onAction ?? (() => { });
+        this.record = input.breaker.get?.(input.key) ?? {
+            key: input.key, messageId: input.messageId, deliveryId: input.deliveryId, inputId: input.inputId,
+            sessionGeneration: input.sessionGeneration, state: "eligible", manualAttempt: 0,
+            compactSentAt: null, compactDeadlineAt: null, compactFinishedAt: null, retrySubmittedAt: null,
+            fallbackReason: null, updatedAt: new Date().toISOString(),
+        };
+    }
+    get state() { return this.record.state; }
+    get recordSnapshot() { return { ...this.record }; }
+    change(state, patch = {}) {
+        if (TERMINAL_STATES.has(this.record.state) || this.record.state === "fallback_required")
+            return;
+        this.record = { ...this.record, ...patch, state, updatedAt: new Date().toISOString() };
+        if (this.breaker.transition) {
+            try {
+                this.record = this.breaker.transition(this.key, this.record, state);
+            }
+            catch (error) {
+                if (this.breaker.get?.(this.key))
+                    throw error;
+                this.breaker.save?.(this.record);
+            }
+        }
+        else
+            this.breaker.save?.(this.record);
+    }
+    agentEnd(input) {
+        if (!input.exactOverflow || TERMINAL_STATES.has(this.state) || this.state === "fallback_required")
+            return;
+        if (["native_compacting", "native_retry_owned", "native_succeeded"].includes(this.state))
+            return;
+        if (this.state === "retrying") {
+            this.change("second_overflow", { fallbackReason: "second exact context overflow" });
+            this.onAction("fresh_session_fallback");
+            return;
+        }
+        if (input.willRetry)
+            this.change("native_retry_owned");
+    }
+    compactionStart(input) {
+        if (input.reason === "overflow" && (this.state === "eligible" || this.state === "native_retry_owned"))
+            this.change("native_compacting");
+    }
+    compactionEnd(input) {
+        if (this.state === "fallback_required" || TERMINAL_STATES.has(this.state))
+            return;
+        if (input.reason === "overflow") {
+            if (this.state === "native_retry_owned" || this.state === "native_compacting" || this.state === "eligible") {
+                if (input.success && input.willRetry)
+                    this.change("native_succeeded");
+                else {
+                    this.change("native_failed", { fallbackReason: "native overflow compaction failed" });
+                    this.onAction("fresh_session_fallback");
+                }
+            }
+            return;
+        }
+        if (this.state !== "manual_sent")
+            return;
+        if (!input.success) {
+            this.change("manual_failed", { fallbackReason: "manual compaction failed" });
+            this.onAction("fresh_session_fallback");
+            return;
+        }
+        this.record = { ...this.record, compactionLifecycleSucceeded: true };
+        if (this.record.compactResponseReceived) {
+            this.change("manual_succeeded", { compactFinishedAt: new Date().toISOString() });
+            this.onAction("retry_input");
+        }
+    }
+    agentSettled() {
+        if (this.state !== "eligible")
+            return;
+        this.change("settled_for_manual");
+        this.onAction("arm_manual_compact");
+    }
+    manualCompactSent(deadlineAt) {
+        if (this.state !== "settled_for_manual" || this.record.manualAttempt >= 1)
+            return;
+        this.change("manual_sent", { manualAttempt: 1, compactSentAt: new Date().toISOString(), compactDeadlineAt: deadlineAt });
+        this.onAction("manual_compact");
+    }
+    compactResponse(input) {
+        if (this.state !== "manual_sent")
+            return;
+        if (!input.success) {
+            this.change(input.ambiguous ? "manual_ambiguous" : "manual_failed", {
+                fallbackReason: input.ambiguous ? "manual compact response became ambiguous after send" : "manual compact RPC failed",
+            });
+            this.onAction("fresh_session_fallback");
+            return;
+        }
+        this.record = { ...this.record, compactResponseReceived: true };
+        if (this.record.compactionLifecycleSucceeded) {
+            this.change("manual_succeeded", { compactFinishedAt: new Date().toISOString() });
+            this.onAction("retry_input");
+        }
+    }
+    compactTimeout() {
+        if (this.state !== "manual_sent")
+            return;
+        this.change("manual_ambiguous", { fallbackReason: "manual compact deadline expired" });
+        this.onAction("fresh_session_fallback");
+    }
+    retrySubmitted() {
+        if (this.state !== "manual_succeeded")
+            return;
+        this.change("retrying", { retrySubmittedAt: new Date().toISOString() });
+    }
+    fallbackRequired(reason) {
+        if (TERMINAL_STATES.has(this.state))
+            return;
+        if (this.breaker.forceFallback)
+            this.record = this.breaker.forceFallback(this.key, reason);
+        else
+            this.change("fallback_required", { fallbackReason: reason });
+        this.onAction("fresh_session_fallback");
+    }
+    fallbackCommitted() {
+        if (!["native_failed", "manual_failed", "manual_ambiguous", "second_overflow", "fallback_required"].includes(this.state))
+            return;
+        this.change("fallback_committed");
+    }
+    close() {
+        if (["native_succeeded", "retrying", "fallback_committed"].includes(this.state))
+            this.change("closed");
+    }
+}
+exports.PiCompactionRecoveryMachine = PiCompactionRecoveryMachine;
+function prepareOwnedPiEnvironment(input) {
+    const directory = ensureOwnedPiAgentDirectory(input.root, input.agentId);
+    writeOwnedPiSettings(directory);
+    return { ...input.env, PI_CODING_AGENT_DIR: directory };
+}
+function readProjectPiSettings(workspaceDir) {
+    const file = node_path_1.default.join(workspaceDir, ".pi", "settings.json");
+    try {
+        const stat = node_fs_1.default.lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error("project Pi settings must be a regular file");
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("project Pi settings are invalid");
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function assertNoProjectPiCompactionOverride(workspaceDir) {
+    const settings = readProjectPiSettings(workspaceDir);
+    if (settings && hasProjectPiCompactionOverride(settings))
+        throw new Error("project Pi compaction/context settings override Larkin policy");
+}
+function currentUserLabel() { return node_os_1.default.userInfo().username; }