synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/core/self-evolution/policy/policy-store.js

@@ -0,0 +1,774 @@
+/**
+ * 策略 POLICY ＝ design template（主智能体的「权重」）· CLI 持有版本.
+ *
+ * In-context-RL framing (loop v2): the 主智能体 MAIN AGENT runs the current
+ * policy vN+1 as a frozen actor; the CRITIC AGENT（基线智能体 baseline agent）
+ * reruns LAST episode's policy vN on the SAME change; the 奖励智能体 REWARD
+ * AGENT calculates 算分 reward(主臂)＆reward(基线臂), advantage ＝
+ * reward(主臂) − reward(基线臂), and the 文本梯度 textual gradient — it never
+ * edits, and it 弃权 abstains when there is no nameable gap; the 演进智能体
+ * EVOLVING AGENT is optimizer.step — ONE bounded edit ≤L, never scoring.
+ *
+ * The policy itself lives in the USER's repo (the design template file(s));
+ * this module is the CLI side that 持有版本 (holds the VERSION): the
+ * 版本账本 ledger, byte-for-byte snapshots, and the one-in-flight lock.
+ *
+ * On-disk layout, rooted at
+ * `<repoRoot>/.synergyspec-selfevolving/self-evolution/policy/`:
+ *   - `ledger.ndjson`                    — 版本账本, append-only, 单一血统
+ *                                          single lineage per target.
+ *   - `snapshots/<target-id-slug>/v<N>/` — `manifest.json` + `files/<relPath>`
+ *                                          (byte-for-byte) + `delta.patch`
+ *                                          (unified diff vs v<N-1>; v0 has no
+ *                                          delta).
+ *   - `in-flight.json`                   — one in-flight episode per target
+ *                                          (stale after 60 minutes).
+ *
+ * Versioning rules (what each ledger `action` means for the version axis):
+ *   - 'init'     → v0: snapshot of the target's CURRENT resolved local files.
+ *   - 'evolve'   → vN+1: the 演进智能体 EVOLVING AGENT's ONE bounded edit.
+ *   - 'refused'  → version does NOT bump (vN+1 ≡ vN). This is what the
+ *                  CRITIC AGENT（基线智能体 baseline agent）'s skip condition
+ *                  reads: the policy did not change, so there is no new arm
+ *                  to compare against the baseline.
+ *   - 'rollback' → vN+1 whose files are byte-identical to snapshot
+ *                  v<toVersion>. Rolling FORWARD to old content (git-revert
+ *                  style) keeps the 单一血统 single lineage monotonic: the
+ *                  version axis never rewinds, so no snapshot dir is ever
+ *                  overwritten.
+ *
+ * Snapshots are the durable record; any per-episode worktree is 产物即弃
+ * (worktree artifacts discarded). All writes are fail-closed: snapshot dirs
+ * are committed via tmp dir + rename, live files via sibling tmp + rename,
+ * the order is snapshot-then-write (the NEW version dir exists before any
+ * live file changes), and a mid-write failure restores every live file from
+ * the head snapshot before rethrowing.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { resolveTargetLocalFiles } from '../local-targets.js';
+import { assertWithinRepo, writeFileAtomic, appendFileDurable } from './fs-safe.js';
+export const POLICY_LEDGER_FILE = 'ledger.ndjson';
+export const POLICY_IN_FLIGHT_FILE = 'in-flight.json';
+export const POLICY_REJECT_BUFFER_FILE = 'reject-buffer.ndjson';
+export const POLICY_SNAPSHOT_MANIFEST_FILE = 'manifest.json';
+export const POLICY_SNAPSHOT_FILES_DIR = 'files';
+export const POLICY_SNAPSHOT_DELTA_FILE = 'delta.patch';
+/** An in-flight episode older than this is stale and its slot reclaimable. */
+export const IN_FLIGHT_STALE_MS = 60 * 60 * 1000;
+const POLICY_SUBDIR = path.join('.synergyspec-selfevolving', 'self-evolution', 'policy');
+/** Compute the policy dir layout for a repo. */
+export function resolvePolicyLayout(repoRoot) {
+    const baseDir = path.join(repoRoot, POLICY_SUBDIR);
+    return {
+        repoRoot,
+        baseDir,
+        ledgerPath: path.join(baseDir, POLICY_LEDGER_FILE),
+        snapshotsDir: path.join(baseDir, 'snapshots'),
+        inFlightPath: path.join(baseDir, POLICY_IN_FLIGHT_FILE),
+        rejectBufferPath: path.join(baseDir, POLICY_REJECT_BUFFER_FILE),
+    };
+}
+/** Kebab-case a target id for use as a snapshot directory name. */
+export function targetIdSlug(targetId) {
+    return targetId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/** Absolute path of one version's snapshot dir. No I/O is performed. */
+export function policySnapshotDir(layout, targetId, version) {
+    return path.join(layout.snapshotsDir, targetIdSlug(targetId), `v${version}`);
+}
+function sha256Of(content) {
+    return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+function assertNonEmptyString(value, name) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+}
+// ---------------------------------------------------------------------------
+// 版本账本 ledger
+// ---------------------------------------------------------------------------
+function isValidLedgerEntry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const e = value;
+    if (e.schemaVersion !== 1)
+        return false;
+    if (typeof e.version !== 'number' || !Number.isInteger(e.version) || e.version < 0) {
+        return false;
+    }
+    if (typeof e.targetId !== 'string' || e.targetId.length === 0)
+        return false;
+    if (typeof e.at !== 'string')
+        return false;
+    if (e.action !== 'init' &&
+        e.action !== 'evolve' &&
+        e.action !== 'rollback' &&
+        e.action !== 'refused') {
+        return false;
+    }
+    if (e.episodeId !== null && typeof e.episodeId !== 'string')
+        return false;
+    if (!Array.isArray(e.files))
+        return false;
+    for (const f of e.files) {
+        const ff = f;
+        if (!ff || typeof ff !== 'object')
+            return false;
+        if (typeof ff.relPath !== 'string' || typeof ff.sha256 !== 'string')
+            return false;
+    }
+    return true;
+}
+async function appendLedgerEntry(layout, entry) {
+    await fs.mkdir(layout.baseDir, { recursive: true });
+    // Durable append: fsync the fd so a host crash cannot lose a rollback ledger
+    // entry a later separate process (resumeEpisode) reads to decide head version.
+    await appendFileDurable(layout.ledgerPath, `${JSON.stringify(entry)}\n`);
+}
+/**
+ * Read one target's slice of the 版本账本 ledger, in append order. Returns
+ * `[]` when the ledger does not exist. Malformed/blank lines are skipped
+ * best-effort (forward-compatible, matching the repo's other ndjson readers).
+ */
+export async function readPolicyLedger(repoRoot, targetId) {
+    const layout = resolvePolicyLayout(path.resolve(repoRoot));
+    let raw;
+    try {
+        raw = await fs.readFile(layout.ledgerPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const entries = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (isValidLedgerEntry(parsed) && parsed.targetId === targetId)
+            entries.push(parsed);
+    }
+    return entries;
+}
+/**
+ * Read the ENTIRE 版本账本 ledger across all targets, in append order. Returns
+ * `[]` when the ledger does not exist. Malformed/blank lines are skipped
+ * best-effort (forward-compatible, matching the repo's other ndjson readers).
+ */
+export async function readPolicyLedgerAll(repoRoot) {
+    const layout = resolvePolicyLayout(path.resolve(repoRoot));
+    let raw;
+    try {
+        raw = await fs.readFile(layout.ledgerPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const entries = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (isValidLedgerEntry(parsed))
+            entries.push(parsed);
+    }
+    return entries;
+}
+/**
+ * The lineage head version for a target, or `null` when the lineage has not
+ * been initialized. The 单一血统 single lineage is append-only, so the head is
+ * simply the LAST ledger entry's version ('refused' entries carry the
+ * unchanged head; 'evolve'/'rollback' carry the new one).
+ */
+export async function currentPolicyVersion(repoRoot, targetId) {
+    const entries = await readPolicyLedger(repoRoot, targetId);
+    if (entries.length === 0)
+        return null;
+    return entries[entries.length - 1].version;
+}
+/**
+ * Write one version's snapshot dir atomically (tmp dir + rename, mirroring
+ * `writeCandidatePackage`). Refuses to overwrite an existing version dir —
+ * snapshots, like the ledger, are append-only history. Returns the
+ * content-addressed manifest file list.
+ */
+async function writeSnapshot(layout, opts) {
+    const slugDir = path.join(layout.snapshotsDir, targetIdSlug(opts.targetId));
+    const finalDir = path.join(slugDir, `v${opts.version}`);
+    // Refuse to overwrite. Detect via stat; ENOENT means safe to proceed.
+    try {
+        await fs.stat(finalDir);
+        throw new Error(`Refusing to overwrite existing policy snapshot: ${finalDir}`);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    await fs.mkdir(slugDir, { recursive: true });
+    const tmpDir = await fs.mkdtemp(path.join(slugDir, `v${opts.version}.tmp-`));
+    try {
+        const manifestFiles = opts.files.map((f) => ({
+            relPath: toPosix(f.relPath),
+            sha256: sha256Of(f.content),
+        }));
+        const manifest = {
+            version: opts.version,
+            targetId: opts.targetId,
+            at: opts.at,
+            files: manifestFiles,
+        };
+        await fs.writeFile(path.join(tmpDir, POLICY_SNAPSHOT_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+        const filesRoot = path.join(tmpDir, POLICY_SNAPSHOT_FILES_DIR);
+        for (const f of opts.files) {
+            const abs = path.join(filesRoot, ...toPosix(f.relPath).split('/'));
+            assertWithinRepo(filesRoot, abs);
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            await fs.writeFile(abs, f.content, 'utf8');
+        }
+        if (opts.deltaPatch !== null) {
+            await fs.writeFile(path.join(tmpDir, POLICY_SNAPSHOT_DELTA_FILE), opts.deltaPatch, 'utf8');
+        }
+        await fs.rename(tmpDir, finalDir);
+        return manifestFiles;
+    }
+    catch (err) {
+        // Best-effort cleanup; surface the original error.
+        try {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+}
+/**
+ * Read one version's snapshotted files (byte-for-byte). Verifies every file
+ * against the manifest's sha256 and throws on a mismatch — a snapshot is the
+ * restore source of truth, so corruption is a hard error, never silent.
+ */
+export async function readPolicySnapshotFiles(repoRoot, targetId, version) {
+    const layout = resolvePolicyLayout(path.resolve(repoRoot));
+    const dir = policySnapshotDir(layout, targetId, version);
+    let manifestRaw;
+    try {
+        manifestRaw = await fs.readFile(path.join(dir, POLICY_SNAPSHOT_MANIFEST_FILE), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new Error(`No policy snapshot v${version} for ${targetId} (looked under ${dir}).`);
+        }
+        throw err;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestRaw);
+    }
+    catch (err) {
+        throw new Error(`Policy snapshot v${version} for ${targetId} has an unreadable manifest: ${err.message}`);
+    }
+    if (!Array.isArray(manifest.files)) {
+        throw new Error(`Policy snapshot v${version} for ${targetId} has a malformed manifest (no files[]).`);
+    }
+    const filesRoot = path.join(dir, POLICY_SNAPSHOT_FILES_DIR);
+    const out = [];
+    for (const f of manifest.files) {
+        if (typeof f?.relPath !== 'string' || typeof f?.sha256 !== 'string') {
+            throw new Error(`Policy snapshot v${version} for ${targetId} has a malformed manifest file entry.`);
+        }
+        const abs = path.join(filesRoot, ...toPosix(f.relPath).split('/'));
+        assertWithinRepo(filesRoot, abs);
+        const content = await fs.readFile(abs, 'utf8');
+        if (sha256Of(content) !== f.sha256) {
+            throw new Error(`Policy snapshot corrupted: sha256 mismatch for ${f.relPath} in v${version} of ${targetId}.`);
+        }
+        out.push({ relPath: toPosix(f.relPath), content });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Delta rendering
+// ---------------------------------------------------------------------------
+/**
+ * Whole-file-replacement unified diff for one policy file. Same format as
+ * `edits-contract.ts`'s `renderUnifiedDiff`, duplicated locally on purpose so
+ * the policy module stays free of the shared edits-contract module graph.
+ */
+function renderFileDelta(relPath, oldContent, newContent) {
+    const oldLines = oldContent.length === 0 ? [] : oldContent.replace(/\n$/, '').split('\n');
+    const newLines = newContent.replace(/\n$/, '').split('\n');
+    const oldStart = oldLines.length === 0 ? 0 : 1;
+    const header = `--- a/${relPath}\n+++ b/${relPath}\n` +
+        `@@ -${oldStart},${oldLines.length} +1,${newLines.length} @@`;
+    const body = [...oldLines.map((l) => `-${l}`), ...newLines.map((l) => `+${l}`)].join('\n');
+    return `${header}\n${body}`;
+}
+/** Derive ledger `deltaStats` from a rendered `delta.patch` body. */
+function countDeltaStats(deltaPatch, filesChanged) {
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    for (const line of deltaPatch.split('\n')) {
+        if (line.startsWith('+++') || line.startsWith('---') || line.startsWith('@@'))
+            continue;
+        if (line.startsWith('+'))
+            linesAdded += 1;
+        else if (line.startsWith('-'))
+            linesRemoved += 1;
+    }
+    return { filesChanged, linesAdded, linesRemoved };
+}
+/**
+ * Start a target's 单一血统 single lineage: snapshot v0 of the target's
+ * CURRENT resolved local files and append the 'init' ledger entry. Refuses to
+ * re-init an existing lineage (the version axis never restarts).
+ */
+export async function initPolicyLineage(opts) {
+    assertNonEmptyString(opts.targetId, 'targetId');
+    const repoRoot = path.resolve(opts.repoRoot);
+    const existing = await currentPolicyVersion(repoRoot, opts.targetId);
+    if (existing !== null) {
+        throw new Error(`Policy lineage for ${opts.targetId} is already initialized (head v${existing}); ` +
+            `单一血统 single lineage — refusing to re-init.`);
+    }
+    const resolveFiles = opts.resolveFiles ?? resolveTargetLocalFiles;
+    const resolved = await resolveFiles(opts.targetId, repoRoot);
+    const files = resolved.files.map((f) => ({ relPath: toPosix(f.relPath), content: f.content }));
+    if (files.length === 0) {
+        throw new Error(`Cannot init policy lineage for ${opts.targetId}: the target resolves to no local files in this repo.`);
+    }
+    const layout = resolvePolicyLayout(repoRoot);
+    const at = new Date().toISOString();
+    const manifestFiles = await writeSnapshot(layout, {
+        targetId: opts.targetId,
+        version: 0,
+        at,
+        files,
+        deltaPatch: null, // v0 has no predecessor
+    });
+    const entry = {
+        schemaVersion: 1,
+        version: 0,
+        targetId: opts.targetId,
+        at,
+        action: 'init',
+        episodeId: null,
+        files: manifestFiles,
+    };
+    await appendLedgerEntry(layout, entry);
+    return entry;
+}
+const PREDICTION_METRICS = new Set([
+    'loss',
+    'passRate',
+    'healthPenalty',
+]);
+function assertValidPrediction(prediction) {
+    if (!prediction || typeof prediction !== 'object') {
+        throw new Error('advancePolicyVersion requires a prediction ({metric, direction, checkBy}) — every evolve step must be falsifiable.');
+    }
+    if (!PREDICTION_METRICS.has(prediction.metric)) {
+        throw new Error(`prediction.metric must be 'loss' | 'passRate' | 'healthPenalty', got ${JSON.stringify(prediction.metric)}`);
+    }
+    if (prediction.direction !== 'down' && prediction.direction !== 'up') {
+        throw new Error(`prediction.direction must be 'down' | 'up', got ${JSON.stringify(prediction.direction)}`);
+    }
+    assertNonEmptyString(prediction.checkBy, 'prediction.checkBy');
+}
+/**
+ * Apply the 演进智能体 EVOLVING AGENT's ONE bounded edit as the next policy
+ * version. 单一血统 single-lineage enforcement: the live files must still be
+ * byte-identical to the lineage head snapshot — if anything advanced or edited
+ * them out-of-band, the head is not the expected base and this throws (roll
+ * back, or re-init, before evolving again).
+ *
+ * Order is snapshot-then-write: the NEW version's snapshot dir is committed
+ * first, then the live files are written atomically; a mid-write failure
+ * restores every live file from the head content and discards the new
+ * snapshot before rethrowing. The 'evolve' ledger entry (with `prediction`
+ * and `deltaStats`) is appended only after every live write succeeded.
+ */
+export async function advancePolicyVersion(opts) {
+    assertNonEmptyString(opts.targetId, 'targetId');
+    assertNonEmptyString(opts.episodeId, 'episodeId');
+    assertValidPrediction(opts.prediction);
+    if (!Array.isArray(opts.edits) || opts.edits.length === 0) {
+        throw new Error('advancePolicyVersion requires at least one edit (the 演进智能体 EVOLVING AGENT makes ONE bounded edit ≤L, never zero).');
+    }
+    const repoRoot = path.resolve(opts.repoRoot);
+    const layout = resolvePolicyLayout(repoRoot);
+    const entries = await readPolicyLedger(repoRoot, opts.targetId);
+    if (entries.length === 0) {
+        throw new Error(`Policy lineage for ${opts.targetId} is not initialized; run initPolicyLineage first.`);
+    }
+    const headVersion = entries[entries.length - 1].version;
+    // The head snapshot is the expected base.
+    const headFiles = await readPolicySnapshotFiles(repoRoot, opts.targetId, headVersion);
+    const headByPath = new Map(headFiles.map((f) => [f.relPath, f.content]));
+    // 单一血统 single-lineage enforcement: every live file must match the head
+    // snapshot byte-for-byte before we stack a new version on top of it.
+    for (const f of headFiles) {
+        const abs = path.resolve(repoRoot, ...f.relPath.split('/'));
+        assertWithinRepo(repoRoot, abs);
+        let live;
+        try {
+            live = await fs.readFile(abs, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                throw new Error(`Refusing to advance ${opts.targetId}: live file ${f.relPath} is missing — ` +
+                    `lineage head v${headVersion} is not the expected base.`);
+            }
+            throw err;
+        }
+        if (live !== f.content) {
+            throw new Error(`Refusing to advance ${opts.targetId}: live file ${f.relPath} diverged from lineage head ` +
+                `v${headVersion} — the head is not the expected base (单一血统 single lineage; roll back ` +
+                `or re-init before evolving again).`);
+        }
+    }
+    // Validate the edits BEFORE writing anything: lineage files only, and at
+    // least one byte must actually change (a no-op evolve is a bug upstream).
+    const editByPath = new Map();
+    for (const edit of opts.edits) {
+        const rel = toPosix(edit.relPath);
+        if (!headByPath.has(rel)) {
+            throw new Error(`Refusing to advance ${opts.targetId}: edit targets ${rel}, which is not part of the ` +
+                `policy lineage (evolve existing policy files only).`);
+        }
+        if (typeof edit.content !== 'string') {
+            throw new Error(`Refusing to advance ${opts.targetId}: edit for ${rel} has no string content.`);
+        }
+        editByPath.set(rel, edit.content);
+    }
+    const changed = [...editByPath].filter(([rel, content]) => content !== headByPath.get(rel));
+    if (changed.length === 0) {
+        throw new Error(`Refusing to advance ${opts.targetId}: every edit is byte-identical to head v${headVersion} (no-op evolve).`);
+    }
+    const deltaPatch = changed
+        .map(([rel, content]) => renderFileDelta(rel, headByPath.get(rel), content))
+        .join('\n');
+    const deltaStats = countDeltaStats(deltaPatch, changed.length);
+    const newVersion = headVersion + 1;
+    const at = new Date().toISOString();
+    const newFiles = headFiles.map((f) => ({
+        relPath: f.relPath,
+        content: editByPath.get(f.relPath) ?? f.content,
+    }));
+    // 1) Snapshot the NEW version dir first (durable before any live change).
+    const manifestFiles = await writeSnapshot(layout, {
+        targetId: opts.targetId,
+        version: newVersion,
+        at,
+        files: newFiles,
+        deltaPatch,
+    });
+    // 2) Write the live files, then append the ledger entry, under ONE
+    // fail-closed guard: any failure restores the written live files from the
+    // head content and discards the new snapshot, so the lineage either fully
+    // advances or stays byte-unchanged at the head.
+    const written = [];
+    try {
+        for (const [rel, content] of changed) {
+            const abs = path.resolve(repoRoot, ...rel.split('/'));
+            const before = headByPath.get(rel);
+            await writeFileAtomic(abs, content);
+            written.push({ abs, before });
+        }
+        const entry = {
+            schemaVersion: 1,
+            version: newVersion,
+            targetId: opts.targetId,
+            at,
+            action: 'evolve',
+            episodeId: opts.episodeId,
+            files: manifestFiles,
+            prediction: opts.prediction,
+            deltaStats,
+        };
+        await appendLedgerEntry(layout, entry);
+        return entry;
+    }
+    catch (err) {
+        for (const w of written) {
+            try {
+                await writeFileAtomic(w.abs, w.before);
+            }
+            catch {
+                // best-effort restore; surface the original error
+            }
+        }
+        try {
+            await fs.rm(policySnapshotDir(layout, opts.targetId, newVersion), {
+                recursive: true,
+                force: true,
+            });
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+}
+/**
+ * Restore the live policy files byte-for-byte from snapshot v<toVersion> and
+ * append a 'rollback' ledger entry. The restore is recorded as a NEW head
+ * version whose files equal the old snapshot (git-revert style) so the
+ * 单一血统 single lineage stays monotonic — the version axis never rewinds.
+ * Unlike advance, rollback does NOT require the live files to match the head:
+ * it is the recovery path, including for out-of-band live-file divergence.
+ */
+export async function rollbackPolicyVersion(opts) {
+    assertNonEmptyString(opts.targetId, 'targetId');
+    assertNonEmptyString(opts.episodeId, 'episodeId');
+    const repoRoot = path.resolve(opts.repoRoot);
+    const layout = resolvePolicyLayout(repoRoot);
+    const entries = await readPolicyLedger(repoRoot, opts.targetId);
+    if (entries.length === 0) {
+        throw new Error(`Policy lineage for ${opts.targetId} is not initialized; run initPolicyLineage first.`);
+    }
+    const headVersion = entries[entries.length - 1].version;
+    if (!Number.isInteger(opts.toVersion) || opts.toVersion < 0 || opts.toVersion >= headVersion) {
+        throw new Error(`Cannot roll back ${opts.targetId} to v${opts.toVersion}: head is v${headVersion} ` +
+            `(toVersion must be an existing earlier version).`);
+    }
+    const restoreFiles = await readPolicySnapshotFiles(repoRoot, opts.targetId, opts.toVersion);
+    const headFiles = await readPolicySnapshotFiles(repoRoot, opts.targetId, headVersion);
+    const headByPath = new Map(headFiles.map((f) => [f.relPath, f.content]));
+    const changedVsHead = restoreFiles.filter((f) => headByPath.get(f.relPath) !== f.content);
+    const deltaPatch = changedVsHead
+        .map((f) => renderFileDelta(f.relPath, headByPath.get(f.relPath) ?? '', f.content))
+        .join('\n');
+    const deltaStats = countDeltaStats(deltaPatch, changedVsHead.length);
+    const newVersion = headVersion + 1;
+    const at = new Date().toISOString();
+    // Snapshot-then-write, same order and fail-closed guard as advance. The
+    // pre-images captured here are whatever is live right now (possibly
+    // diverged), so a mid-restore failure puts back exactly what it found.
+    const manifestFiles = await writeSnapshot(layout, {
+        targetId: opts.targetId,
+        version: newVersion,
+        at,
+        files: restoreFiles,
+        deltaPatch,
+    });
+    const written = [];
+    try {
+        for (const f of restoreFiles) {
+            const abs = path.resolve(repoRoot, ...f.relPath.split('/'));
+            assertWithinRepo(repoRoot, abs);
+            let before;
+            try {
+                before = await fs.readFile(abs, 'utf8');
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT')
+                    throw err;
+                before = null;
+            }
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            await writeFileAtomic(abs, f.content);
+            written.push({ abs, before });
+        }
+        const entry = {
+            schemaVersion: 1,
+            version: newVersion,
+            targetId: opts.targetId,
+            at,
+            action: 'rollback',
+            episodeId: opts.episodeId,
+            files: manifestFiles,
+            ...(opts.advantage !== undefined ? { advantage: opts.advantage } : {}),
+            deltaStats,
+        };
+        await appendLedgerEntry(layout, entry);
+        return entry;
+    }
+    catch (err) {
+        for (const w of written) {
+            try {
+                if (w.before !== null)
+                    await writeFileAtomic(w.abs, w.before);
+            }
+            catch {
+                // best-effort restore; surface the original error
+            }
+        }
+        try {
+            await fs.rm(policySnapshotDir(layout, opts.targetId, newVersion), {
+                recursive: true,
+                force: true,
+            });
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+}
+/**
+ * Record an episode where the 演进智能体 EVOLVING AGENT refused to edit. The
+ * version does NOT bump (vN+1 ≡ vN) — this entry is exactly what the
+ * CRITIC AGENT（基线智能体 baseline agent）'s skip condition reads: the policy
+ * is unchanged, so rerunning the baseline arm would compare a policy against
+ * itself. No files are touched.
+ */
+export async function recordEvolutionRefused(opts) {
+    assertNonEmptyString(opts.targetId, 'targetId');
+    assertNonEmptyString(opts.episodeId, 'episodeId');
+    assertNonEmptyString(opts.reason, 'reason');
+    const repoRoot = path.resolve(opts.repoRoot);
+    const layout = resolvePolicyLayout(repoRoot);
+    const entries = await readPolicyLedger(repoRoot, opts.targetId);
+    if (entries.length === 0) {
+        throw new Error(`Policy lineage for ${opts.targetId} is not initialized; run initPolicyLineage first.`);
+    }
+    const head = entries[entries.length - 1];
+    const entry = {
+        schemaVersion: 1,
+        version: head.version, // unchanged: vN+1 ≡ vN
+        targetId: opts.targetId,
+        at: new Date().toISOString(),
+        action: 'refused',
+        episodeId: opts.episodeId,
+        files: head.files,
+        reason: opts.reason,
+    };
+    await appendLedgerEntry(layout, entry);
+    return entry;
+}
+// ---------------------------------------------------------------------------
+// One in-flight episode per target
+// ---------------------------------------------------------------------------
+function isValidInFlightEntry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const e = value;
+    return (typeof e.targetId === 'string' &&
+        e.targetId.length > 0 &&
+        typeof e.episodeId === 'string' &&
+        e.episodeId.length > 0 &&
+        typeof e.sinceVersion === 'number' &&
+        Number.isInteger(e.sinceVersion) &&
+        e.sinceVersion >= 0 &&
+        typeof e.startedAt === 'string');
+}
+/**
+ * Read the in-flight map (targetId → entry). A missing or unparseable file
+ * reads as empty: the staleness window — not the file's integrity — is the
+ * real liveness guarantee, so a corrupt lock file must not wedge the loop.
+ */
+async function readInFlightMap(layout) {
+    let raw;
+    try {
+        raw = await fs.readFile(layout.inFlightPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (isValidInFlightEntry(value))
+            out[key] = value;
+    }
+    return out;
+}
+async function writeInFlightMap(layout, map) {
+    await fs.mkdir(layout.baseDir, { recursive: true });
+    await writeFileAtomic(layout.inFlightPath, `${JSON.stringify(map, null, 2)}\n`);
+}
+/**
+ * Claim the one in-flight slot for a target. Throws while a NON-stale entry
+ * exists for the target (one in-flight per target); an entry whose
+ * `startedAt` is ≥ {@link IN_FLIGHT_STALE_MS} old is stale and its slot is
+ * reclaimed (the abandoned episode's worktree is 产物即弃 — worktree
+ * artifacts discarded). Records `sinceVersion` = the lineage head at acquire
+ * time, so the episode knows which policy version it started from.
+ */
+export async function acquireInFlight(opts) {
+    assertNonEmptyString(opts.targetId, 'targetId');
+    assertNonEmptyString(opts.episodeId, 'episodeId');
+    const repoRoot = path.resolve(opts.repoRoot);
+    const layout = resolvePolicyLayout(repoRoot);
+    const now = opts.now ?? new Date();
+    const map = await readInFlightMap(layout);
+    const existing = map[opts.targetId];
+    if (existing) {
+        const startedMs = Date.parse(existing.startedAt);
+        const stale = !Number.isFinite(startedMs) || now.getTime() - startedMs >= IN_FLIGHT_STALE_MS;
+        if (!stale) {
+            throw new Error(`An episode is already in flight for ${opts.targetId} ` +
+                `(episode ${existing.episodeId}, started ${existing.startedAt}); one in-flight per target.`);
+        }
+        // Stale: reclaim the slot below.
+    }
+    const sinceVersion = await currentPolicyVersion(repoRoot, opts.targetId);
+    if (sinceVersion === null) {
+        throw new Error(`Cannot acquire in-flight for ${opts.targetId}: policy lineage not initialized (run initPolicyLineage first).`);
+    }
+    const entry = {
+        targetId: opts.targetId,
+        episodeId: opts.episodeId,
+        sinceVersion,
+        startedAt: now.toISOString(),
+    };
+    map[opts.targetId] = entry;
+    await writeInFlightMap(layout, map);
+    return entry;
+}
+/**
+ * Release a target's in-flight slot. Idempotent when no entry exists; throws
+ * when the slot is held by a DIFFERENT episode (an episode may only release
+ * its own claim).
+ */
+export async function releaseInFlight(opts) {
+    assertNonEmptyString(opts.targetId, 'targetId');
+    assertNonEmptyString(opts.episodeId, 'episodeId');
+    const repoRoot = path.resolve(opts.repoRoot);
+    const layout = resolvePolicyLayout(repoRoot);
+    const map = await readInFlightMap(layout);
+    const existing = map[opts.targetId];
+    if (!existing)
+        return; // idempotent: nothing to release
+    if (existing.episodeId !== opts.episodeId) {
+        throw new Error(`Refusing to release in-flight for ${opts.targetId}: held by episode ${existing.episodeId}, not ${opts.episodeId}.`);
+    }
+    delete map[opts.targetId];
+    await writeInFlightMap(layout, map);
+}
+//# sourceMappingURL=policy-store.js.map