specrails-desktop 2.57.0 → 2.58.0

package/server/dist/modules/agent-runtime/runtime/agent-runtime-package-gc.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectUnreferencedRuntimePackages = collectUnreferencedRuntimePackages;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const agent_runtime_package_lock_1 = require("./agent-runtime-package-lock");
+const DIGEST = /^[a-f0-9]{64}$/;
+const STAGED = /^\.staged-[a-f0-9-]{36}$/;
+const GARBAGE = /^\.garbage-[a-f0-9]{64}-[a-f0-9-]{36}$/;
+/** Collects only expired, unreferenced package directories. Every run pin is
+ * inspected before the first mutation; an unknown pin protects the whole cache.
+ * Callers must use the same package lock when publishing new retained pins. */
+function collectUnreferencedRuntimePackages(pipelineRoot, options) {
+    if (!Number.isSafeInteger(options.minimumAgeMs) || options.minimumAgeMs < 86_400_000 || !Number.isFinite(options.now))
+        throw new Error('Package retention requires an age of at least one day and a valid clock');
+    if (!node_fs_1.default.existsSync(pipelineRoot))
+        return [];
+    if (node_fs_1.default.lstatSync(pipelineRoot).isSymbolicLink() || !node_fs_1.default.statSync(pipelineRoot).isDirectory())
+        throw new Error('Pipeline storage must be a real directory');
+    const cache = node_path_1.default.join(pipelineRoot, 'runtime-packages');
+    if (!node_fs_1.default.existsSync(cache))
+        return [];
+    return (0, agent_runtime_package_lock_1.withRuntimePackageLock)(cache, () => {
+        const referenced = new Set();
+        for (const entry of node_fs_1.default.readdirSync(pipelineRoot, { withFileTypes: true })) {
+            if (entry.name === 'runtime-packages')
+                continue;
+            if (entry.isSymbolicLink())
+                throw new Error('Cannot collect packages across an unknown pipeline link');
+            if (!entry.isDirectory())
+                continue;
+            const directory = node_path_1.default.join(pipelineRoot, entry.name);
+            if (entry.name === '.retention') {
+                if (node_fs_1.default.readdirSync(directory).length)
+                    throw new Error('Runtime quarantine must be recovered before package collection');
+                continue;
+            }
+            const pinFile = node_path_1.default.join(directory, 'desktop-runtime-package.json');
+            if (!node_fs_1.default.existsSync(pinFile)) {
+                if (node_fs_1.default.existsSync(node_path_1.default.join(directory, 'agent-runtime-request.json')))
+                    throw new Error('A saved execution has no proven original package pin');
+                continue;
+            }
+            const stat = node_fs_1.default.lstatSync(pinFile);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16_384)
+                throw new Error('Invalid runtime package pin');
+            const pin = JSON.parse(node_fs_1.default.readFileSync(pinFile, 'utf8'));
+            if (pin.schemaVersion !== 1 || typeof pin.integrity !== 'string' || !DIGEST.test(pin.integrity) ||
+                pin.root !== node_path_1.default.join(cache, pin.integrity) || typeof pin.cli !== 'string' || !pin.cli || node_path_1.default.isAbsolute(pin.cli) || pin.cli.split(/[\\/]/).includes('..'))
+                throw new Error('Runtime package pin scope is invalid');
+            referenced.add(pin.integrity);
+        }
+        const eligible = [];
+        for (const entry of node_fs_1.default.readdirSync(cache, { withFileTypes: true })) {
+            if (!DIGEST.test(entry.name) && !GARBAGE.test(entry.name) && !STAGED.test(entry.name))
+                continue;
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                throw new Error('Runtime package storage contains an invalid entry');
+            if (referenced.has(entry.name))
+                continue;
+            const stat = node_fs_1.default.statSync(node_path_1.default.join(cache, entry.name));
+            if (stat.mtimeMs > options.now || options.now - stat.mtimeMs < options.minimumAgeMs)
+                continue;
+            eligible.push(entry.name);
+        }
+        for (const name of options.dryRun ? [] : eligible) {
+            const original = node_path_1.default.join(cache, name);
+            // A crashed deletion cannot leave a partially deleted digest available to
+            // a future publisher. The private garbage name is safe to retry later.
+            const garbage = GARBAGE.test(name) || STAGED.test(name) ? original : node_path_1.default.join(cache, `.garbage-${name}-${(0, node_crypto_1.randomUUID)()}`);
+            if (garbage !== original)
+                node_fs_1.default.renameSync(original, garbage);
+            node_fs_1.default.rmSync(garbage, { recursive: true });
+        }
+        return eligible.sort();
+    });
+}

package/server/dist/modules/agent-runtime/runtime/agent-runtime-package-lock.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRuntimePackageLock = withRuntimePackageLock;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** SQLite's OS-backed write reservation serializes package publication and
+ * collection across Desktop processes and releases automatically after a crash.
+ * No timestamps, guessed stale owners or advisory PID files authorize deletion. */
+function withRuntimePackageLock(cache, operation) {
+    node_fs_1.default.mkdirSync(cache, { recursive: true, mode: 0o700 });
+    if (node_fs_1.default.lstatSync(cache).isSymbolicLink() || !node_fs_1.default.statSync(cache).isDirectory())
+        throw new Error('Runtime package cache must be a real directory');
+    const lock = node_path_1.default.join(cache, '.maintenance.sqlite');
+    try {
+        node_fs_1.default.writeFileSync(lock, '', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const stat = node_fs_1.default.lstatSync(lock);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+        throw new Error('Runtime package maintenance lock is invalid');
+    const database = new better_sqlite3_1.default(lock, { timeout: 0 });
+    try {
+        // No asynchronous work may escape this transaction. Retention's host/Core
+        // inspection happens before package collection; copying is synchronous.
+        return database.transaction(operation).immediate();
+    }
+    finally {
+        database.close();
+    }
+}

package/server/dist/modules/agent-runtime/runtime/agent-runtime-package.js

@@ -3,9 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectUnreferencedRuntimePackages = void 0;
 exports.runtimeEntryFingerprint = runtimeEntryFingerprint;
 exports.retainAgentRuntime = retainAgentRuntime;
 exports.resolveRetainedAgentRuntime = resolveRetainedAgentRuntime;
+const agent_runtime_package_lock_1 = require("./agent-runtime-package-lock");
+var agent_runtime_package_gc_1 = require("./agent-runtime-package-gc");
+Object.defineProperty(exports, "collectUnreferencedRuntimePackages", { enumerable: true, get: function () { return agent_runtime_package_gc_1.collectUnreferencedRuntimePackages; } });
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_module_1 = require("node:module");
@@ -155,37 +159,39 @@ function retainAgentRuntime(cli, contextPath) {
         throw new Error('Core CLI escapes its package');
     const cache = node_path_1.default.join(node_path_1.default.dirname(node_path_1.default.dirname(contextPath)), 'runtime-packages');
     node_fs_1.default.mkdirSync(cache, { recursive: true, mode: 0o700 });
-    const staged = node_path_1.default.join(cache, '.staged-' + (0, node_crypto_1.randomUUID)());
-    try {
-        copyInstalledPackage(root, staged);
-        const integrity = treeDigest(staged);
-        const retained = node_path_1.default.join(cache, integrity);
-        if (node_fs_1.default.existsSync(retained)) {
-            if (treeDigest(retained) !== integrity)
-                throw new Error('Retained Core runtime integrity changed');
-        }
-        else {
+    return (0, agent_runtime_package_lock_1.withRuntimePackageLock)(cache, () => {
+        const staged = node_path_1.default.join(cache, '.staged-' + (0, node_crypto_1.randomUUID)());
+        try {
+            copyInstalledPackage(root, staged);
+            const integrity = treeDigest(staged);
+            const retained = node_path_1.default.join(cache, integrity);
+            if (node_fs_1.default.existsSync(retained)) {
+                if (treeDigest(retained) !== integrity)
+                    throw new Error('Retained Core runtime integrity changed');
+            }
+            else {
+                try {
+                    node_fs_1.default.renameSync(staged, retained);
+                }
+                catch (error) {
+                    if (!node_fs_1.default.existsSync(retained) || treeDigest(retained) !== integrity)
+                        throw error;
+                }
+            }
+            const pin = { schemaVersion: 1, packageVersion: JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(root, 'package.json'), 'utf8')).version, integrity, root: retained, cli: relativeCli };
             try {
-                node_fs_1.default.renameSync(staged, retained);
+                node_fs_1.default.writeFileSync(pinFile, JSON.stringify(pin) + '\n', { flag: 'wx', mode: 0o600 });
             }
             catch (error) {
-                if (!node_fs_1.default.existsSync(retained) || treeDigest(retained) !== integrity)
+                if (error.code !== 'EEXIST' || resolveRetainedAgentRuntime(contextPath) !== node_path_1.default.join(retained, relativeCli))
                     throw error;
             }
+            return node_path_1.default.join(retained, relativeCli);
         }
-        const pin = { schemaVersion: 1, packageVersion: JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(root, 'package.json'), 'utf8')).version, integrity, root: retained, cli: relativeCli };
-        try {
-            node_fs_1.default.writeFileSync(pinFile, JSON.stringify(pin) + '\n', { flag: 'wx', mode: 0o600 });
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST' || resolveRetainedAgentRuntime(contextPath) !== node_path_1.default.join(retained, relativeCli))
-                throw error;
+        finally {
+            node_fs_1.default.rmSync(staged, { recursive: true, force: true });
         }
-        return node_path_1.default.join(retained, relativeCli);
-    }
-    finally {
-        node_fs_1.default.rmSync(staged, { recursive: true, force: true });
-    }
+    });
 }
 function resolveRetainedAgentRuntime(contextPath) {
     const pinFile = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-package.json');

package/server/dist/modules/agent-runtime/runtime/agent-runtime-retention-host.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeRetentionHostPorts = runtimeRetentionHostPorts;
+exports.recoverHostRuntimeRetention = recoverHostRuntimeRetention;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
+const agent_runtime_package_1 = require("./agent-runtime-package");
+const agent_runtime_retention_quarantine_1 = require("./agent-runtime-retention-quarantine");
+const agent_runtime_retention_records_1 = require("./agent-runtime-retention-records");
+function terminalTime(value) {
+    if (!value)
+        return null;
+    return /^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d$/.test(value) ? value.replace(' ', 'T') + 'Z' : value;
+}
+function deliveryState(db, runId) {
+    const rows = db.prepare('SELECT run_ids,decision,operation_token FROM rail_pr_deliveries').all();
+    const relevant = rows.filter(row => {
+        const ids = JSON.parse(row.run_ids);
+        if (!Array.isArray(ids) || ids.some(id => typeof id !== 'string'))
+            throw new Error('Unknown delivery run ownership');
+        return ids.includes(runId);
+    });
+    return { pending: relevant.some(row => row.operation_token !== null || !['completed', 'merged', 'discarded', 'superseded'].includes(row.decision)),
+        discarded: relevant.length > 0 && relevant.every(row => ['discarded', 'superseded'].includes(row.decision)) };
+}
+function runtimeRetentionHostPorts(host, policy, now) {
+    const owner = 'retention:' + (0, node_crypto_1.randomUUID)();
+    return {
+        async runIds() {
+            // Children settle later than parents. Expire a child before reconsidering
+            // its parent's lineage; unexpired descendants continue protecting it.
+            return host.db.prepare("SELECT id FROM loop_runs WHERE project_id=? AND status='completed' ORDER BY finished_at DESC,id").all(host.projectId)
+                .map(row => row.id).filter(id => !(0, agent_runtime_retention_records_1.readRuntimeExpiration)(host.db, id) && node_fs_1.default.existsSync(node_path_1.default.join(host.pipelineRoot, id, 'agent-runtime-request.json')));
+        },
+        async reserve(runId) {
+            if (host.active(runId))
+                return null;
+            const scope = host.scope(runId);
+            const claim = (0, loop_runs_store_1.claimDefinitionExecution)(host.db, runId, { owner, repositoryMounts: scope.repositoryMounts });
+            if (!claim.ok)
+                return null;
+            try {
+                const state = await scope.inspect(), row = (0, loop_runs_store_1.getLoopRun)(host.db, runId);
+                if (!state || state.runId !== runId || !row || row.project_id !== host.projectId || (0, loop_runs_store_1.readDefinitionExecutionClaim)(host.db, runId)?.owner !== owner)
+                    throw new Error('Runtime retention authority changed');
+                const job = host.db.prepare('SELECT status FROM jobs WHERE id=?').get(runId);
+                const delivery = deliveryState(host.db, runId);
+                const terminal = ['succeeded', 'cancelled', 'failed'].includes(state.status);
+                const settled = row.status === 'completed' && job?.status === 'completed' && row.final_outcome === 'success' && state.status === 'succeeded';
+                const discarded = row.status === 'completed' && delivery.discarded && terminal;
+                const fork = (0, loop_runs_store_1.readDefinitionForkTarget)(host.db, runId);
+                const evidence = {
+                    runId, disposition: settled ? 'settled' : discarded ? 'discarded' : 'recoverable',
+                    terminalAt: terminalTime(row.finished_at), active: host.active(runId) || row.status !== 'completed' || !terminal || state.lease?.active === true || state.engineVersion === 2 && state.lease === undefined,
+                    humanPending: state.engineVersion === 2 && !Array.isArray(state.pendingInterrupts) || !!state.pendingQuestion || !!state.pendingApproval || !!state.pendingInterrupts?.length,
+                    interruptedWrites: state.engineVersion === 2 && !Array.isArray(state.recoverableSteps) || !!state.recoverableSteps?.length || Object.values(state.steps).some(step => ['running', 'interrupted', 'paused'].includes(step.status)),
+                    deliveryPending: delivery.pending || !job || !['completed', 'failed', 'canceled', 'cancelled'].includes(job.status),
+                    forkPending: !!fork && !(0, agent_runtime_retention_records_1.readRuntimeExpiration)(host.db, fork),
+                };
+                return { evidence, ...(0, agent_runtime_retention_quarantine_1.runtimeJournalQuarantine)(host.db, host.pipelineRoot, {
+                        runId, expiredAt: new Date(now).toISOString(), disposition: discarded ? 'discarded' : 'settled', previousStatus: state.status,
+                        summary: { status: state.status, engineVersion: state.engineVersion ?? 1, nextStep: null, historical: true },
+                    }), release: claim.release };
+            }
+            catch (error) {
+                claim.release();
+                throw error;
+            }
+        },
+        async collectUnreferencedPackages(dryRun) {
+            return policy.days === null ? [] : (0, agent_runtime_package_1.collectUnreferencedRuntimePackages)(host.pipelineRoot, { dryRun, minimumAgeMs: policy.days * 86_400_000, now });
+        },
+    };
+}
+function recoverHostRuntimeRetention(host) {
+    return (0, agent_runtime_retention_quarantine_1.recoverRuntimeQuarantine)(host.db, host.pipelineRoot, runId => {
+        if (host.active(runId))
+            return null;
+        const claim = (0, loop_runs_store_1.claimDefinitionExecution)(host.db, runId, { owner: 'retention-recovery:' + (0, node_crypto_1.randomUUID)(), repositoryMounts: [] });
+        return claim.ok ? claim.release : null;
+    });
+}

package/server/dist/modules/agent-runtime/runtime/agent-runtime-retention-quarantine.js

@@ -0,0 +1,231 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeJournalQuarantine = runtimeJournalQuarantine;
+exports.recoverRuntimeQuarantine = recoverRuntimeQuarantine;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const agent_runtime_retention_records_1 = require("./agent-runtime-retention-records");
+/*
+ * Durable quarantine protocol. Every crash boundary leaves one recognizable state:
+ *
+ *   1. `.retention/.staging-<token>/` holds at most a partial intent. The original
+ *      journal was not moved yet, so recovery deletes only the staging directory.
+ *   2. `.retention/<token>/intent.json` is published by an atomic directory rename.
+ *      Before the journal move the original is intact and still has the recorded
+ *      identity; recovery removes only the intent.
+ *   3. `<token>/run` is the moved journal (same inode). Without an expiration
+ *      record recovery restores it; with an owning record it finishes deletion.
+ *   4. Deletion removes the journal first and the intent last, so an interrupted
+ *      deletion always keeps the intent that authorizes it. A directory without
+ *      an intent is removed only when it is empty.
+ *   5. Restoration moves the journal back first; before the intent is removed the
+ *      original must still have the recorded identity. Replacement data is never
+ *      deleted or overwritten.
+ */
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const TOKEN = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const STAGING = /^\.staging-([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/;
+function realDirectory(directory) {
+    const stat = node_fs_1.default.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('Runtime retention cannot cross a storage link');
+}
+function syncDirectory(directory) {
+    // Directory handles cannot be flushed on Windows; NTFS journals the rename itself.
+    if (process.platform === 'win32')
+        return;
+    const handle = node_fs_1.default.openSync(directory, 'r');
+    try {
+        node_fs_1.default.fsyncSync(handle);
+    }
+    finally {
+        node_fs_1.default.closeSync(handle);
+    }
+}
+function locations(pipeline, runId, token) {
+    if (!RUN_ID.test(runId) || !TOKEN.test(token))
+        throw new Error('Invalid runtime retention identity');
+    realDirectory(pipeline);
+    const root = node_path_1.default.join(pipeline, '.retention');
+    if (node_fs_1.default.existsSync(root))
+        realDirectory(root);
+    const directory = node_path_1.default.join(root, token);
+    if (node_fs_1.default.existsSync(directory))
+        realDirectory(directory);
+    return { original: node_path_1.default.join(pipeline, runId), root, directory, staging: node_path_1.default.join(root, `.staging-${token}`), journal: node_path_1.default.join(directory, 'run'), intent: node_path_1.default.join(directory, 'intent.json') };
+}
+function identity(directory) {
+    realDirectory(directory);
+    const stat = node_fs_1.default.statSync(directory, { bigint: true });
+    if (stat.ino === 0n)
+        throw new Error('Runtime journal filesystem identity is unavailable');
+    return { dev: String(stat.dev), ino: String(stat.ino) };
+}
+const sameIdentity = (a, b) => a.dev === b.dev && a.ino === b.ino;
+function readIntent(file) {
+    const stat = node_fs_1.default.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16_384)
+        throw new Error('Invalid runtime quarantine intent');
+    const intent = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+    if (intent?.schemaVersion !== 1 || typeof intent.runId !== 'string' || typeof intent.token !== 'string' || !intent.journalIdentity ||
+        typeof intent.journalIdentity.dev !== 'string' || typeof intent.journalIdentity.ino !== 'string')
+        throw new Error('Runtime quarantine intent identity changed');
+    return intent;
+}
+function inspectIntent(files, runId, token) {
+    const intent = readIntent(files.intent);
+    if (intent.runId !== runId || intent.token !== token)
+        throw new Error('Runtime quarantine intent identity changed');
+    if (node_fs_1.default.readdirSync(files.directory).some(name => !['intent.json', 'run'].includes(name)))
+        throw new Error('Unknown files in runtime quarantine');
+    if (node_fs_1.default.existsSync(files.journal) && !sameIdentity(identity(files.journal), intent.journalIdentity))
+        throw new Error('Runtime quarantine journal was replaced');
+    return intent;
+}
+/** Journal first, intent last: every interruption keeps the deletion authority. */
+function deleteQuarantine(files, runId, token) {
+    if (!node_fs_1.default.existsSync(files.directory))
+        return;
+    if (node_fs_1.default.existsSync(files.intent)) {
+        inspectIntent(files, runId, token);
+        node_fs_1.default.rmSync(files.journal, { recursive: true, force: true });
+        node_fs_1.default.rmSync(files.intent, { force: true });
+    }
+    // Fails with ENOTEMPTY rather than deleting data this protocol did not create.
+    node_fs_1.default.rmdirSync(files.directory);
+}
+/** Journal back first; the intent stays until the restored original is proven. */
+function restoreQuarantine(files, intent) {
+    if (node_fs_1.default.existsSync(files.journal)) {
+        if (node_fs_1.default.existsSync(files.original))
+            throw new Error('Original runtime location was replaced; recovery must not overwrite it');
+        realDirectory(files.journal);
+        node_fs_1.default.renameSync(files.journal, files.original);
+        syncDirectory(node_path_1.default.dirname(files.original));
+    }
+    if (!node_fs_1.default.existsSync(files.original) || !sameIdentity(identity(files.original), intent.journalIdentity))
+        throw new Error('Restored runtime journal identity changed; quarantine retained for review');
+    if (node_fs_1.default.readdirSync(files.directory).some(name => name !== 'intent.json'))
+        throw new Error('Unknown files in runtime quarantine');
+    node_fs_1.default.rmSync(files.intent);
+    node_fs_1.default.rmdirSync(files.directory);
+}
+/** Host execution/delivery reservations must be held for the complete lifecycle.
+ * Only journal storage is moved; no path from frozen repository metadata is used. */
+function runtimeJournalQuarantine(db, pipeline, record) {
+    const token = (0, node_crypto_1.randomUUID)(), files = locations(pipeline, record.runId, token);
+    const own = (value) => { if (value !== token)
+        throw new Error('Runtime quarantine ownership changed'); return locations(pipeline, record.runId, token); };
+    return {
+        async quarantine() {
+            realDirectory(files.original);
+            node_fs_1.default.mkdirSync(files.root, { recursive: true, mode: 0o700 });
+            realDirectory(files.root);
+            node_fs_1.default.mkdirSync(files.staging, { mode: 0o700 });
+            const intent = { schemaVersion: 1, runId: record.runId, token, journalIdentity: identity(files.original) };
+            const handle = node_fs_1.default.openSync(node_path_1.default.join(files.staging, 'intent.json'), 'wx', 0o600);
+            try {
+                node_fs_1.default.writeFileSync(handle, JSON.stringify(intent));
+                node_fs_1.default.fsyncSync(handle);
+            }
+            finally {
+                node_fs_1.default.closeSync(handle);
+            }
+            // Publication is atomic: recovery sees either staging or a complete intent.
+            node_fs_1.default.renameSync(files.staging, files.directory);
+            syncDirectory(files.root);
+            node_fs_1.default.renameSync(files.original, files.journal);
+            syncDirectory(pipeline);
+            return { token };
+        },
+        async expire(value) {
+            const target = own(value), intent = inspectIntent(target, record.runId, token);
+            if (!node_fs_1.default.existsSync(target.journal) || !sameIdentity(identity(target.journal), intent.journalIdentity))
+                throw new Error('Runtime quarantine journal is not owned');
+            (0, agent_runtime_retention_records_1.recordRuntimeExpiration)(db, { ...record, quarantineToken: token });
+        },
+        async restore(value) {
+            const target = own(value);
+            if ((0, agent_runtime_retention_records_1.readRuntimeExpiration)(db, record.runId))
+                throw new Error('Expired runtime cannot be restored as executable history');
+            restoreQuarantine(target, inspectIntent(target, record.runId, token));
+        },
+        async remove(value) {
+            const target = own(value), expired = (0, agent_runtime_retention_records_1.readRuntimeExpiration)(db, record.runId);
+            if (!expired || expired.quarantineToken !== token)
+                throw new Error('Runtime expiration is not durable');
+            deleteQuarantine(target, record.runId, token);
+        },
+    };
+}
+/** Recovery runs under a host reservation supplied for each intent. A live
+ * collection must return null; no age/PID heuristic takes over its ownership.
+ * One damaged entry is reported and left in place without blocking the others;
+ * package collection refuses to run while any quarantine entry remains. */
+function recoverRuntimeQuarantine(db, pipeline, reserve) {
+    const result = { restored: [], removed: [], protected: [], errors: [] };
+    const root = node_path_1.default.join(pipeline, '.retention');
+    if (!node_fs_1.default.existsSync(root))
+        return result;
+    realDirectory(pipeline);
+    realDirectory(root);
+    for (const entry of node_fs_1.default.readdirSync(root, { withFileTypes: true })) {
+        try {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                throw new Error(`Unknown runtime quarantine entry ${entry.name}`);
+            const directory = node_path_1.default.join(root, entry.name), staging = STAGING.exec(entry.name);
+            if (staging) {
+                // Unpublished: the original journal was never moved.
+                if (node_fs_1.default.readdirSync(directory).some(name => name !== 'intent.json'))
+                    throw new Error('Unknown files in unpublished runtime quarantine');
+                node_fs_1.default.rmSync(node_path_1.default.join(directory, 'intent.json'), { force: true });
+                node_fs_1.default.rmdirSync(directory);
+                continue;
+            }
+            if (!TOKEN.test(entry.name))
+                throw new Error(`Unknown runtime quarantine entry ${entry.name}`);
+            if (!node_fs_1.default.existsSync(node_path_1.default.join(directory, 'intent.json'))) {
+                // Deletion removed the intent last, or a pre-protocol crash left an empty
+                // directory. Anything else has no authority and is kept.
+                if (node_fs_1.default.readdirSync(directory).length)
+                    throw new Error('Runtime quarantine has data without an intent');
+                node_fs_1.default.rmdirSync(directory);
+                continue;
+            }
+            const intent = readIntent(node_path_1.default.join(directory, 'intent.json'));
+            if (intent.token !== entry.name)
+                throw new Error('Runtime quarantine intent identity changed');
+            const files = locations(pipeline, intent.runId, intent.token);
+            inspectIntent(files, intent.runId, intent.token);
+            const release = reserve(intent.runId);
+            if (!release) {
+                result.protected.push(intent.runId);
+                continue;
+            }
+            try {
+                const expired = (0, agent_runtime_retention_records_1.readRuntimeExpiration)(db, intent.runId);
+                if (expired) {
+                    if (expired.quarantineToken !== intent.token)
+                        throw new Error('Runtime expiration does not own this quarantine');
+                    deleteQuarantine(files, intent.runId, intent.token);
+                    result.removed.push(intent.runId);
+                }
+                else {
+                    restoreQuarantine(files, intent);
+                    result.restored.push(intent.runId);
+                }
+            }
+            finally {
+                release();
+            }
+        }
+        catch (error) {
+            result.errors.push(`${entry.name}: ${error instanceof Error ? error.message : 'Runtime quarantine recovery failed'}`);
+        }
+    }
+    return result;
+}

package/server/dist/modules/agent-runtime/runtime/agent-runtime-retention-records.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRuntimeExpiration = readRuntimeExpiration;
+exports.recordRuntimeExpiration = recordRuntimeExpiration;
+exports.readRuntimeRetentionPolicy = readRuntimeRetentionPolicy;
+exports.saveRuntimeRetentionPolicy = saveRuntimeRetentionPolicy;
+const agent_runtime_retention_1 = require("./agent-runtime-retention");
+function readRuntimeExpiration(db, runId) {
+    const row = db.prepare('SELECT * FROM runtime_retention_records WHERE run_id=?').get(runId);
+    return row ? { runId: row.run_id, expiredAt: row.expired_at, disposition: row.disposition, previousStatus: row.previous_status, quarantineToken: row.quarantine_token, summary: JSON.parse(row.summary_json) } : null;
+}
+function recordRuntimeExpiration(db, value) {
+    db.transaction(() => {
+        const previous = readRuntimeExpiration(db, value.runId);
+        if (previous) {
+            if (previous.quarantineToken !== value.quarantineToken)
+                throw new Error('Runtime expiration identity changed');
+            return;
+        }
+        db.prepare('INSERT INTO runtime_retention_records(run_id,expired_at,disposition,previous_status,quarantine_token,summary_json) VALUES (?,?,?,?,?,?)')
+            .run(value.runId, value.expiredAt, value.disposition, value.previousStatus, value.quarantineToken, JSON.stringify(value.summary));
+    }).immediate();
+}
+function readRuntimeRetentionPolicy(db) {
+    const row = db.prepare('SELECT days FROM runtime_retention_policy WHERE id=1').get();
+    return row ? (0, agent_runtime_retention_1.validateRuntimeRetentionPolicy)(row) : { days: null };
+}
+function saveRuntimeRetentionPolicy(db, value) {
+    const policy = (0, agent_runtime_retention_1.validateRuntimeRetentionPolicy)(value);
+    db.prepare('INSERT INTO runtime_retention_policy(id,days) VALUES (1,?) ON CONFLICT(id) DO UPDATE SET days=excluded.days').run(policy.days);
+    return policy;
+}

package/server/dist/modules/agent-runtime/runtime/agent-runtime-retention.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRuntimeRetentionPolicy = validateRuntimeRetentionPolicy;
+exports.runtimeRetentionDecision = runtimeRetentionDecision;
+exports.collectRuntimeRetention = collectRuntimeRetention;
+const DAY_MS = 86_400_000;
+function validateRuntimeRetentionPolicy(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => key !== 'days'))
+        throw new Error('Retention policy requires only days');
+    const days = value.days;
+    if (days !== null && (!Number.isSafeInteger(days) || days < 1 || days > 3650))
+        throw new Error('Retention days must be null or an integer from 1 to 3650');
+    return { days };
+}
+function runtimeRetentionDecision(evidence, policy, now) {
+    validateRuntimeRetentionPolicy(policy);
+    if (!Number.isFinite(now))
+        throw new Error('Retention requires a valid clock');
+    const reasons = [];
+    if (policy.days === null)
+        reasons.push('disabled');
+    if (evidence.disposition !== 'settled' && evidence.disposition !== 'discarded')
+        reasons.push('recoverable');
+    if (evidence.active !== false)
+        reasons.push('active');
+    if (evidence.humanPending !== false)
+        reasons.push('human_pending');
+    if (evidence.interruptedWrites !== false)
+        reasons.push('interrupted_writes');
+    if (evidence.deliveryPending !== false)
+        reasons.push('delivery_pending');
+    if (evidence.forkPending !== false)
+        reasons.push('fork_pending');
+    const at = evidence.terminalAt === null ? NaN : Date.parse(evidence.terminalAt);
+    if (!Number.isFinite(at) || at > now)
+        reasons.push('unknown_terminal_time');
+    else if (policy.days !== null && now - at < policy.days * DAY_MS)
+        reasons.push('within_retention');
+    return { runId: evidence.runId, collect: reasons.length === 0, reasons };
+}
+/** Failure boundaries are intentional: never delete before durable expiration,
+ * never resurrect an expired run when cleanup fails, and never collect packages
+ * after a run boundary whose integrity could not be established. */
+async function collectRuntimeRetention(ports, policy, options) {
+    validateRuntimeRetentionPolicy(policy);
+    const report = { dryRun: options.dryRun, runs: [], packages: [], errors: [] };
+    let packageCollectionSafe = true;
+    for (const runId of [...new Set(await ports.runIds())]) {
+        if (policy.days === null) {
+            report.runs.push({ runId, collect: false, reasons: ['disabled'], state: 'protected' });
+            continue;
+        }
+        let reservation = null;
+        try {
+            reservation = await ports.reserve(runId);
+            if (!reservation) {
+                report.runs.push({ runId, collect: false, reasons: [], state: 'busy' });
+                continue;
+            }
+            if (reservation.evidence.runId !== runId)
+                throw new Error('Retention reservation identity changed');
+            const decision = runtimeRetentionDecision(reservation.evidence, policy, options.now);
+            if (!decision.collect || options.dryRun) {
+                report.runs.push({ ...decision, state: decision.collect ? 'eligible' : 'protected' });
+                continue;
+            }
+            const { token } = await reservation.quarantine();
+            try {
+                await reservation.expire(token);
+            }
+            catch (error) {
+                await reservation.restore(token);
+                throw error;
+            }
+            try {
+                await reservation.remove(token);
+                report.runs.push({ ...decision, state: 'expired' });
+            }
+            catch (error) {
+                // Restart recovery retries only deletion, never original-run execution.
+                report.runs.push({ ...decision, state: 'cleanup_pending', error: error instanceof Error ? error.message : 'Runtime cleanup failed' });
+                packageCollectionSafe = false;
+            }
+        }
+        catch (error) {
+            packageCollectionSafe = false;
+            report.runs.push({ runId, collect: false, reasons: [], state: 'error', error: error instanceof Error ? error.message : 'Runtime retention failed' });
+        }
+        finally {
+            reservation?.release();
+        }
+    }
+    if (packageCollectionSafe && policy.days !== null) {
+        try {
+            report.packages = await ports.collectUnreferencedPackages(options.dryRun);
+        }
+        catch (error) {
+            report.errors.push(error instanceof Error ? error.message : 'Package collection failed');
+        }
+    }
+    return report;
+}