synergyspec-selfevolving 2.1.4 → 2.1.6

package/dist/core/self-evolution/host-harness.js

@@ -34,17 +34,18 @@ const HARNESSES = ['claude', 'codex', 'opencode'];
 export const DEFAULT_AGENT_TIMEOUT_MS = 600_000;
 /**
  * Per-host absolute-timeout defaults. claude/codex keep the 10-min
- * {@link DEFAULT_AGENT_TIMEOUT_MS}; opencode is given a lower wall because — in
- * the v2.1.2 smoke run — an opencode/GPT-5.5 print-mode spawn emitted ZERO
- * output and burned the full 10 minutes before the wall fired (the host CLI is
- * empirically slow-to-emit / occasionally non-terminating in `run` print mode).
+ * {@link DEFAULT_AGENT_TIMEOUT_MS}; opencode gets a longer wall because the
+ * v2.1.5 Windows/OpenCode smoke run reached reward/scoring, then killed the
+ * evolving agent at the previous 5-min wall while it was still producing a
+ * bounded candidate. The idle watchdog remains the earlier trip wire for silent
+ * wedges, so the absolute wall should be large enough for a live edit attempt.
  * The wall is still overridable per-host via
  * `SYNERGYSPEC_SELFEVOLVING_AGENT_TIMEOUT_MS` ({@link resolveAgentTimeoutMs}).
  */
 const HARNESS_TIMEOUT_DEFAULTS_MS = {
     claude: DEFAULT_AGENT_TIMEOUT_MS,
     codex: DEFAULT_AGENT_TIMEOUT_MS,
-    opencode: 300_000,
+    opencode: 900_000,
 };
 /**
  * Default STDOUT/STDERR-idle watchdog window (2 min). If a spawned host CLI
@@ -62,11 +63,13 @@ export const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 120_000;
  * emit ZERO bytes for well over 2 min while it reasons, so claude/codex get a
  * 5-min idle leash. opencode keeps the tighter 2-min window — it is the
  * empirically-wedging host (the v2.1.2 hang emitted no output at all) and a
- * faster idle kill is what we want there.
+ * faster idle kill is what we want there. opencode's absolute wall is longer
+ * than claude/codex because its live edit attempts can be slower even when they
+ * are not silent.
  *
  * INVARIANT: every harness's idle default is strictly LESS than its absolute
  * default ({@link HARNESS_TIMEOUT_DEFAULTS_MS}) so the idle watchdog stays the
- * earlier trip wire (claude 300<600, codex 300<600, opencode 120<300).
+ * earlier trip wire (claude 300<600, codex 300<600, opencode 120<900).
  * Overridable per host via `SYNERGYSPEC_SELFEVOLVING_AGENT_IDLE_TIMEOUT_MS`
  * ({@link resolveIdleTimeoutMs}).
  */
@@ -125,8 +128,8 @@ const AGENT_TIMEOUT_ENV = 'SYNERGYSPEC_SELFEVOLVING_AGENT_TIMEOUT_MS';
  *   (1) `SYNERGYSPEC_SELFEVOLVING_AGENT_TIMEOUT_MS` when it parses to a positive
  *       finite integer — a host-wide tunable that overrides every harness.
  *   (2) the per-harness default ({@link HARNESS_TIMEOUT_DEFAULTS_MS}): the 10-min
- *       {@link DEFAULT_AGENT_TIMEOUT_MS} for claude/codex, a lower wall for the
- *       empirically slow-to-emit opencode.
+ *       {@link DEFAULT_AGENT_TIMEOUT_MS} for claude/codex, and a longer wall for
+ *       opencode live edit attempts.
  *
  * `harness` omitted ⇒ {@link resolveHostHarness} is consulted so the default is
  * host-appropriate.
@@ -150,25 +153,25 @@ function isAgentHarness(value) {
  * Precedence:
  *   (a) `SYNERGYSPEC_SELFEVOLVING_HOST_HARNESS` when it equals claude|codex|opencode.
  *   (b) Heuristic on the ambient environment:
- *       - `CODEX_HOME` or any `CODEX_*` var set → 'codex'.
  *       - `OPENCODE_DATA_DIR` or any `OPENCODE_*` var set → 'opencode'.
+ *       - `CODEX_HOME` or any `CODEX_*` var set → 'codex'.
  *   (c) Default 'claude'.
  *
- * Codex is checked before opencode so that, in the unlikely event both families
- * of env vars are present, the explicit override remains the only way to force a
- * choice; the heuristic is best-effort.
+ * OpenCode is checked before Codex because Codex can be the meta-runner that is
+ * invoking an OpenCode smoke test; in that mixed environment OPENCODE_* is the
+ * stronger signal for the observed run whose trajectory we must grade.
  */
 export function resolveHostHarness() {
     const override = process.env.SYNERGYSPEC_SELFEVOLVING_HOST_HARNESS;
     if (isAgentHarness(override))
         return override;
     const envKeys = Object.keys(process.env);
-    const hasCodex = process.env.CODEX_HOME !== undefined || envKeys.some((k) => k.startsWith('CODEX_'));
-    if (hasCodex)
-        return 'codex';
     const hasOpencode = process.env.OPENCODE_DATA_DIR !== undefined || envKeys.some((k) => k.startsWith('OPENCODE_'));
     if (hasOpencode)
         return 'opencode';
+    const hasCodex = process.env.CODEX_HOME !== undefined || envKeys.some((k) => k.startsWith('CODEX_'));
+    if (hasCodex)
+        return 'codex';
     return 'claude';
 }
 // ---------------------------------------------------------------------------
@@ -194,14 +197,23 @@ function hostHarnessPath(repoRoot) {
  * spawns, never a precondition for the current run.
  */
 export async function persistHostHarness(repoRoot, harness) {
+    let tmpFile = null;
     try {
         const file = hostHarnessPath(repoRoot);
         await fs.mkdir(path.dirname(file), { recursive: true });
-        await fs.writeFile(file, `${JSON.stringify({ harness }, null, 2)}\n`, 'utf8');
+        tmpFile = path.join(path.dirname(file), `${HOST_HARNESS_FILE}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+        await fs.writeFile(tmpFile, `${JSON.stringify({ harness }, null, 2)}\n`, 'utf8');
+        await fs.rename(tmpFile, file);
+        tmpFile = null;
     }
     catch {
         // Swallow: a read-only or transient FS must not break the loop.
     }
+    finally {
+        if (tmpFile) {
+            await fs.unlink(tmpFile).catch(() => undefined);
+        }
+    }
 }
 /**
  * Read + parse + validate the persisted-harness sidecar. Returns the
@@ -253,18 +265,16 @@ function binaryResolvable(binary) {
         if (binary.trim().length === 0)
             return false;
         const isWindows = process.platform === 'win32';
-        // Windows PATHEXT (e.g. `.COM;.EXE;.BAT;.CMD`); also try the bare name (a
-        // binary may already carry its extension).
-        const exts = isWindows
-            ? ['', ...(process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)]
-            : [''];
+        // Windows PATHEXT (e.g. `.COM;.EXE;.BAT;.CMD`). A bare extensionless npm
+        // shim is not a CreateProcess target; prefer the PATHEXT-resolved .cmd/.exe.
+        const exts = executableExtensions(binary, isWindows, process.env.PATHEXT);
         const isExecutableFile = (candidate) => {
             try {
                 const st = statSync(candidate);
                 if (!st.isFile())
                     return false;
                 if (isWindows)
-                    return true; // Windows has no executable bit; existence + ext suffices.
+                    return isWindowsSpawnCompatibleExecutable(candidate);
                 // POSIX: any execute bit (owner/group/other) marks it runnable.
                 return (st.mode & 0o111) !== 0;
             }
@@ -314,34 +324,34 @@ function persistedBinary(harness) {
  *       wrong binary,
  *   (4) 'claude'.
  *
- * When (1) or (2) resolve CONFIDENTLY from a real env signal, the result is
- * persisted best-effort (fire-and-forget) so a later env-less call recovers it.
+ * This resolver is read-only. Command entry points that need to seed an
+ * env-less subagent call `seedHostHarnessForRepo`; keeping this function pure
+ * matters because learn preview/report generation uses it during trajectory
+ * lookup and must not write sidecar files.
+ *
  * The env checks are replicated inline (rather than only calling the sync
  * {@link resolveHostHarness}) precisely so we can tell "env gave a real signal"
  * apart from "defaulted to claude with no signal" — the sync resolver collapses
  * both onto 'claude'.
  */
-export async function resolveHostHarnessForRepo(repoRoot) {
+export async function resolveHostHarnessDetailsForRepo(repoRoot) {
     // (1) explicit override.
     const override = process.env.SYNERGYSPEC_SELFEVOLVING_HOST_HARNESS;
     if (isAgentHarness(override)) {
-        void persistHostHarness(repoRoot, override);
-        return override;
+        return { harness: override, source: 'override' };
     }
     // (2) env heuristic — only a POSITIVE hit counts (mirrors resolveHostHarness'
-    //     CODEX_-before-OPENCODE_ ordering, but distinguishes a real signal from
+    //     OPENCODE_-before-CODEX_ ordering, but distinguishes a real signal from
     //     the 'claude' fall-through).
     const envKeys = Object.keys(process.env);
-    const hasCodex = process.env.CODEX_HOME !== undefined || envKeys.some((k) => k.startsWith('CODEX_'));
-    if (hasCodex) {
-        void persistHostHarness(repoRoot, 'codex');
-        return 'codex';
-    }
     const hasOpencode = process.env.OPENCODE_DATA_DIR !== undefined ||
         envKeys.some((k) => k.startsWith('OPENCODE_'));
     if (hasOpencode) {
-        void persistHostHarness(repoRoot, 'opencode');
-        return 'opencode';
+        return { harness: 'opencode', source: 'env' };
+    }
+    const hasCodex = process.env.CODEX_HOME !== undefined || envKeys.some((k) => k.startsWith('CODEX_'));
+    if (hasCodex) {
+        return { harness: 'codex', source: 'env' };
     }
     // (3) persisted sidecar (the env-less-subagent recovery path) — honored ONLY
     //     when its binary is resolvable here. The persisted value for codex /
@@ -349,19 +359,36 @@ export async function resolveHostHarnessForRepo(repoRoot) {
     //     sidecar whose binary is absent (best-effort: a probe error trusts the
     //     sidecar — see {@link binaryResolvable}).
     const persisted = await readPersistedHostHarness(repoRoot);
-    if (persisted && binaryResolvable(persistedBinary(persisted)))
-        return persisted;
+    if (persisted && binaryResolvable(persistedBinary(persisted))) {
+        return { harness: persisted, source: 'persisted' };
+    }
     // (4) default.
-    return 'claude';
+    return { harness: 'claude', source: 'default' };
+}
+export async function resolveHostHarnessForRepo(repoRoot) {
+    return (await resolveHostHarnessDetailsForRepo(repoRoot)).harness;
+}
+/**
+ * Resolve the host harness and persist only a confident host signal (explicit
+ * override or CODEX_/OPENCODE_ env). This is the side-effecting entry point for
+ * command handlers that are about to spawn env-less subagents; core report and
+ * trajectory readers should use the read-only resolver above.
+ */
+export async function seedHostHarnessForRepo(repoRoot) {
+    const resolution = await resolveHostHarnessDetailsForRepo(repoRoot);
+    if (resolution.source === 'override' || resolution.source === 'env') {
+        await persistHostHarness(repoRoot, resolution.harness);
+    }
+    return resolution;
 }
 /**
  * Build the concrete `{binary, args, useStdin}` invocation for a headless run.
  *
  * Full escape hatch: if `SYNERGYSPEC_CODE_AGENT_COMMAND` is set, it is parsed as a
- * JSON `string[]` template. The literal tokens `{prompt}` and `{cwd}` are
- * substituted in each element; `binary = template[0]`, `args = template.slice(1)`.
- * `useStdin` is inferred — true iff the template does NOT contain a `{prompt}`
- * token anywhere (so the caller streams the prompt to stdin instead).
+ * JSON `string[]` template. The literal token `{cwd}` is substituted in each
+ * element; `binary = template[0]`, `args = template.slice(1)`. `{prompt}` is
+ * deliberately rejected: loop-v2 prompts are too large for argv and must flow
+ * through stdin for every harness and override.
  *
  * Otherwise the command is derived from the harness (default
  * {@link resolveHostHarness}). Every harness streams the prompt over stdin
@@ -381,12 +408,14 @@ export function buildHeadlessCommand(prompt, opts) {
             throw new Error('SYNERGYSPEC_CODE_AGENT_COMMAND must be a non-empty JSON array of strings');
         }
         const rawTemplate = parsed;
-        const useStdin = !rawTemplate.some((e) => e.includes('{prompt}'));
-        const substituted = rawTemplate.map((e) => e.split('{prompt}').join(prompt).split('{cwd}').join(opts.cwd));
+        if (rawTemplate.some((e) => e.includes('{prompt}'))) {
+            throw new Error('SYNERGYSPEC_CODE_AGENT_COMMAND must not contain {prompt}; prompts are always streamed over stdin');
+        }
+        const substituted = rawTemplate.map((e) => e.split('{cwd}').join(opts.cwd));
         return {
             binary: substituted[0],
             args: substituted.slice(1),
-            useStdin,
+            useStdin: true,
         };
     }
     const harness = opts.harness ?? resolveHostHarness();
@@ -418,6 +447,110 @@ export function buildHeadlessCommand(prompt, opts) {
         }
     }
 }
+export function resolveHeadlessCommandForSpawn(command, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== 'win32') {
+        return { ...command, shell: false };
+    }
+    const resolved = resolveWindowsExecutable(command.binary, {
+        env: opts.env ?? process.env,
+        isExecutableFile: opts.isExecutableFile ??
+            ((candidate) => {
+                try {
+                    return statSync(candidate).isFile();
+                }
+                catch {
+                    return false;
+                }
+            }),
+    });
+    const binary = resolved ?? command.binary;
+    if (isUnsupportedWindowsExecutable(binary)) {
+        throw new Error(`Windows headless agent binary '${binary}' has unsupported extension '${path.win32
+            .extname(binary)
+            .toLowerCase()}'; use a .cmd, .bat, .exe, or .com shim, or invoke the interpreter explicitly via SYNERGYSPEC_CODE_AGENT_COMMAND.`);
+    }
+    if (isWindowsShellScript(binary)) {
+        const wrapper = wrapWindowsShellScript(binary, command.args, opts.env ?? process.env);
+        return {
+            ...command,
+            binary: wrapper.binary,
+            args: wrapper.args,
+            shell: false,
+        };
+    }
+    return {
+        ...command,
+        binary,
+        shell: false,
+    };
+}
+function executableExtensions(binary, isWindows, pathext) {
+    if (!isWindows)
+        return [''];
+    if (path.win32.extname(binary))
+        return [''];
+    return (pathext ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map((ext) => ext.trim())
+        .filter(Boolean);
+}
+function resolveWindowsExecutable(binary, opts) {
+    if (!binary || binary.trim().length === 0)
+        return null;
+    const exts = executableExtensions(binary, true, opts.env.PATHEXT);
+    const candidates = [];
+    const hasPathSeparator = binary.includes('/') || binary.includes('\\');
+    if (hasPathSeparator) {
+        candidates.push(...exts.map((ext) => binary + ext));
+    }
+    else {
+        const entries = (opts.env.PATH ?? '').split(';').filter(Boolean);
+        for (const dir of entries) {
+            for (const ext of exts)
+                candidates.push(path.win32.join(dir, binary + ext));
+        }
+    }
+    let firstUnsupported = null;
+    for (const candidate of candidates) {
+        if (!opts.isExecutableFile(candidate, true))
+            continue;
+        if (isWindowsSpawnCompatibleExecutable(candidate))
+            return candidate;
+        firstUnsupported ??= candidate;
+    }
+    if (firstUnsupported) {
+        throw new Error(`Windows headless agent binary resolved to '${firstUnsupported}', but that extension cannot be spawned with shell:false; use a .cmd, .bat, .exe, or .com shim, or invoke the interpreter explicitly via SYNERGYSPEC_CODE_AGENT_COMMAND.`);
+    }
+    return null;
+}
+function isWindowsShellScript(binary) {
+    const ext = path.win32.extname(binary).toLowerCase();
+    return ext === '.cmd' || ext === '.bat';
+}
+function isWindowsSpawnCompatibleExecutable(binary) {
+    const ext = path.win32.extname(binary).toLowerCase();
+    return ext === '' || ext === '.com' || ext === '.exe' || ext === '.bat' || ext === '.cmd';
+}
+function isUnsupportedWindowsExecutable(binary) {
+    const ext = path.win32.extname(binary).toLowerCase();
+    return ext.length > 0 && !isWindowsSpawnCompatibleExecutable(binary);
+}
+function wrapWindowsShellScript(binary, args, env) {
+    const comspec = firstNonBlankEnv(env, 'ComSpec', 'COMSPEC') ?? 'cmd.exe';
+    return {
+        binary: comspec,
+        args: ['/d', '/s', '/c', 'call', binary, ...args],
+    };
+}
+function firstNonBlankEnv(env, ...keys) {
+    for (const key of keys) {
+        const value = env[key];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value;
+    }
+    return undefined;
+}
 /**
  * The claude-default binary fallback: `SYNERGYSPEC_SELFEVOLVING_CLAUDE_BIN` when
  * non-empty, else `'claude'`. Kept here so {@link buildHeadlessCommand} is the
@@ -453,16 +586,27 @@ function claudeDefaultBinary() {
  */
 export async function runHeadlessAgent(prompt, opts) {
     const spawnImpl = opts.spawn ?? nodeSpawn;
-    const command = buildHeadlessCommand(prompt, {
-        cwd: opts.cwd,
-        harness: opts.harness,
-        binaryOverride: opts.binaryOverride,
-    });
+    let spawnCommand;
+    try {
+        const command = buildHeadlessCommand(prompt, {
+            cwd: opts.cwd,
+            harness: opts.harness,
+            binaryOverride: opts.binaryOverride,
+        });
+        spawnCommand = resolveHeadlessCommandForSpawn(command);
+    }
+    catch (e) {
+        return {
+            exitCode: -1,
+            stdout: '',
+            stderr: e instanceof Error ? e.message : String(e),
+        };
+    }
     return await new Promise((resolve) => {
         let child;
         try {
-            child = spawnImpl(command.binary, command.args, {
-                shell: false,
+            child = spawnImpl(spawnCommand.binary, spawnCommand.args, {
+                shell: spawnCommand.shell,
                 cwd: opts.cwd,
             });
         }
@@ -520,7 +664,7 @@ export async function runHeadlessAgent(prompt, opts) {
                 // ignore
             }
         };
-        if (command.useStdin) {
+        if (spawnCommand.useStdin) {
             // Swallow stdin stream errors (e.g. EPIPE when the child exits before it
             // has read the whole — possibly 100KB+ — prompt). The real failure is
             // reported via the child's own 'error'/'close' handlers below; an
@@ -581,7 +725,6 @@ export async function runHeadlessAgent(prompt, opts) {
                 if (settled)
                     return;
                 const elapsedS = Math.round((Date.now() - startedAt) / 1000);
-                // eslint-disable-next-line no-console
                 console.error(`[self-evolution] headless agent running: ${elapsedS}s elapsed, ${bytesReceived} bytes received`);
             }, HEARTBEAT_INTERVAL_MS);
             heartbeatTimer.unref?.();

package/dist/core/self-evolution/index.d.ts

@@ -22,6 +22,7 @@ export * from './eval-report.js';
 export * from './edits-contract.js';
 export * from './proposer-slice.js';
 export * from './promotion.js';
+export * from './dream.js';
 export * from './policy/index.js';
 export * from './episode-store.js';
 export * from './line-diff.js';

package/dist/core/self-evolution/index.js

@@ -22,6 +22,7 @@ export * from './eval-report.js';
 export * from './edits-contract.js';
 export * from './proposer-slice.js';
 export * from './promotion.js';
+export * from './dream.js';
 // ── Loop v2 (self-evolution as in-context RL) ────────────────────────────────
 // Policy (ledger + reject-buffer + fs-safe), the disk episode store, the three
 // agents (critic / reward / evolving), the line-diff + scope gate, and the

package/dist/core/self-evolution/policy/policy-store.d.ts

@@ -7,7 +7,7 @@ export declare const POLICY_SNAPSHOT_DELTA_FILE = "delta.patch";
 /** An in-flight episode older than this is stale and its slot reclaimable. */
 export declare const IN_FLIGHT_STALE_MS: number;
 /** What a ledger entry records happened to the lineage. */
-export type PolicyLedgerAction = 'init' | 'evolve' | 'rollback' | 'refused';
+export type PolicyLedgerAction = 'init' | 'evolve' | 'promote' | 'rollback' | 'refused';
 /** One file the policy version covers, content-addressed for verification. */
 export interface PolicyLedgerFileEntry {
     /** Repo-relative POSIX path of the live policy file. */
@@ -25,7 +25,7 @@ export interface PolicyPrediction {
     direction: 'down' | 'up';
     checkBy: string;
 }
-/** Size of an 'evolve'/'rollback' step, derived from its `delta.patch`. */
+/** Size of an 'evolve'/'promote'/'rollback' step, derived from its `delta.patch`. */
 export interface PolicyDeltaStats {
     filesChanged: number;
     linesAdded: number;
@@ -156,6 +156,23 @@ export interface AdvancePolicyVersionOptions {
  * and `deltaStats`) is appended only after every live write succeeded.
  */
 export declare function advancePolicyVersion(opts: AdvancePolicyVersionOptions): Promise<PolicyLedgerEntry>;
+export interface AdoptPromotedPolicyVersionOptions {
+    repoRoot: string;
+    targetId: string;
+    candidateId: string;
+    reason?: string;
+}
+/**
+ * Adopt an already-applied candidate/human promotion into an existing policy
+ * lineage. This is deliberately separate from {@link advancePolicyVersion}: a
+ * human promotion is not an optimizer step and carries no falsifiable prediction,
+ * but it still must bump the snapshot/ledger head when it changes a versioned
+ * policy target.
+ *
+ * Returns `null` when the target has no initialized lineage or when the live
+ * files are already byte-identical to the head snapshot.
+ */
+export declare function adoptPromotedPolicyVersion(opts: AdoptPromotedPolicyVersionOptions): Promise<PolicyLedgerEntry | null>;
 export interface RollbackPolicyVersionOptions {
     repoRoot: string;
     targetId: string;

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

@@ -31,6 +31,8 @@
  *                  CRITIC AGENT（基线智能体 baseline agent）'s skip condition
  *                  reads: the policy did not change, so there is no new arm
  *                  to compare against the baseline.
+ *   - 'promote'  → vN+1: an approved human/candidate promotion that already
+ *                  wrote the live file is adopted into the same lineage.
  *   - '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
@@ -110,6 +112,7 @@ function isValidLedgerEntry(value) {
         return false;
     if (e.action !== 'init' &&
         e.action !== 'evolve' &&
+        e.action !== 'promote' &&
         e.action !== 'rollback' &&
         e.action !== 'refused') {
         return false;
@@ -534,6 +537,88 @@ export async function advancePolicyVersion(opts) {
         throw err;
     }
 }
+/**
+ * Adopt an already-applied candidate/human promotion into an existing policy
+ * lineage. This is deliberately separate from {@link advancePolicyVersion}: a
+ * human promotion is not an optimizer step and carries no falsifiable prediction,
+ * but it still must bump the snapshot/ledger head when it changes a versioned
+ * policy target.
+ *
+ * Returns `null` when the target has no initialized lineage or when the live
+ * files are already byte-identical to the head snapshot.
+ */
+export async function adoptPromotedPolicyVersion(opts) {
+    assertNonEmptyString(opts.targetId, 'targetId');
+    assertNonEmptyString(opts.candidateId, 'candidateId');
+    const repoRoot = path.resolve(opts.repoRoot);
+    const layout = resolvePolicyLayout(repoRoot);
+    const entries = await readPolicyLedger(repoRoot, opts.targetId);
+    if (entries.length === 0)
+        return null;
+    const headVersion = entries[entries.length - 1].version;
+    const headFiles = await readPolicySnapshotFiles(repoRoot, opts.targetId, headVersion);
+    const headByPath = new Map(headFiles.map((f) => [f.relPath, f.content]));
+    const liveFiles = [];
+    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 adopt promotion for ${opts.targetId}: live file ${f.relPath} is missing.`);
+            }
+            throw err;
+        }
+        liveFiles.push({ relPath: f.relPath, content: live });
+    }
+    const changed = liveFiles.filter((f) => f.content !== headByPath.get(f.relPath));
+    if (changed.length === 0)
+        return null;
+    const deltaPatch = changed
+        .map((f) => renderFileDelta(f.relPath, headByPath.get(f.relPath), f.content))
+        .join('\n');
+    const deltaStats = countDeltaStats(deltaPatch, changed.length);
+    const newVersion = headVersion + 1;
+    const at = new Date().toISOString();
+    const manifestFiles = await writeSnapshot(layout, {
+        targetId: opts.targetId,
+        version: newVersion,
+        at,
+        files: liveFiles,
+        deltaPatch,
+    });
+    const entry = {
+        schemaVersion: 1,
+        version: newVersion,
+        targetId: opts.targetId,
+        at,
+        action: 'promote',
+        episodeId: null,
+        files: manifestFiles,
+        reason: opts.reason ??
+            `candidate promotion ${opts.candidateId} adopted into policy lineage`,
+        deltaStats,
+    };
+    try {
+        await appendLedgerEntry(layout, entry);
+    }
+    catch (err) {
+        try {
+            await fs.rm(policySnapshotDir(layout, opts.targetId, newVersion), {
+                recursive: true,
+                force: true,
+            });
+        }
+        catch {
+            // ignore cleanup failure; surface the durable append error
+        }
+        throw err;
+    }
+    return entry;
+}
 /**
  * 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

package/dist/core/self-evolution/promote.d.ts

@@ -1,3 +1,4 @@
+import { type PolicyLedgerEntry } from './policy/policy-store.js';
 import { type TargetEvolutionPolicy } from './target-evolution.js';
 import { updateCandidateStatus, type CandidateRepoLayout, type CanonicalCandidateStatus } from './candidates.js';
 export interface AppliedFile {
@@ -15,6 +16,8 @@ export interface PromotionApplyResult {
     /** Absolute path of the pre-image snapshot dir (for rollback). */
     rollbackDir: string;
     targetIds: string[];
+    /** Policy ledger rows appended for file-backed policy targets, if any. */
+    policyLedgerEntries: PolicyLedgerEntry[];
 }
 export interface RollbackResult {
     candidateId: string;
@@ -45,9 +48,9 @@ export interface ApplyCandidateOptions {
  * + status promoted), or files byte-unchanged". A status-write failure leaves
  * the candidate at its prior status (re-runnable), never half-applied.
  *
- * Preconditions: the candidate must carry structured `edits.json` (i.e. it was
- * proposed with `--agent`) and be in status `ready-for-eval` or `eval-passed`
- * (i.e. the static gate passed).
+ * Preconditions: the candidate must carry structured `edits.json` from a
+ * host-authored or externally packaged proposal and be in status
+ * `ready-for-eval` or `eval-passed` (i.e. the static gate passed).
  */
 export declare function applyCandidatePromotion(layout: CandidateRepoLayout, candidateId: string, opts: ApplyCandidateOptions): Promise<PromotionApplyResult>;
 /**
@@ -174,8 +177,7 @@ export interface EvidenceCheck {
  *   1. `fitnessSample.loss !== null` (a functional loss was actually computed), and
  *   2. `fitnessSample.trajectoryFacts.verified === true` (a real test-runner was
  *      observed in the agent trajectory, not just a hand-authored test-report), and
- *   3. the observed run was GREEN: `observedStatus === 'success'` OR
- *      `observedPassRate >= 1`, and
+ *   3. the observed run was GREEN: `observedStatus === 'success'`, and
  *   4. NO learn observation with code `trajectory-report-conflict` (report claims
  *      green but the observed run failed) or `trajectory-unverified-pass` (report
  *      claims green but no run was observed).