synergyspec-selfevolving 1.4.0 → 2.1.0

package/dist/core/self-evolution/critic-agent.js

@@ -0,0 +1,568 @@
+/**
+ * CRITIC AGENT（基线智能体 baseline agent）runner — loop v2 (self-evolution as
+ * in-context RL).
+ *
+ * The CRITIC AGENT is an AGENT with the SAME input/output as the 主智能体 MAIN
+ * AGENT (frozen actor; the user's host agent running the current 策略 policy
+ * vN+1). It produces the baseline arm for LAST episode's 策略 policy vN on the
+ * SAME change in an ISOLATED worktree (by default RE-DOING the change under vN —
+ * see {@link CriticBaselineMode}), so the 奖励智能体 REWARD AGENT can later 算分
+ * calculate reward(主臂)＆reward(基线臂) and advantage ＝ reward(主臂) −
+ * reward(基线臂). Only its baseline trajectory survives — 产物即弃 (worktree
+ * artifacts discarded): the worktree is torn down in `finally`, and the single
+ * durable output is the `baseline-arm/` capture in the episode store.
+ *
+ * This module orchestrates ONE baseline arm:
+ *   1. create an isolated worktree OUTSIDE the repo (git worktree at detached
+ *      HEAD — which excludes the change's still-uncommitted implementation — else
+ *      a recursive file copy fallback),
+ *   2. make it runnable (node_modules junction/symlink + the untracked surfaces
+ *      the rerun reads),
+ *   2b. ('re-do' mode, the default) reset the copied change dir to its INPUTS —
+ *      remove the GENERATED artifacts (design.md, tasks.md) + reports — so the
+ *      rerun re-authors them under the installed prior policy ({@link
+ *      resetChangeArtifactsForRedo}),
+ *   3. INSTALL 策略 policy vN into the worktree from the byte-for-byte version
+ *      snapshot, so the baseline arm reruns the PRIOR policy and not the live
+ *      templates,
+ *   4. rerun headlessly via the host-aware {@link runHeadlessAgent} with
+ *      cwd = worktree ('re-do' regenerates design→tasks→impl→tests; 're-test'
+ *      re-runs the existing change's tests), never editing canonical files,
+ *   5. persist the baseline arm (stdout always; the claude session transcript +
+ *      action skeleton when discoverable; an `objective.json` shaped IDENTICALLY
+ *      to the main arm's), and
+ *   6. ALWAYS tear the worktree down.
+ *
+ * Honesty contract: a pass rate is parse-or-throw — when the rerun's stdout
+ * carries no parseable test summary the objective records `passRate: null`
+ * rather than fabricating one. The agent is RUN, never asked to edit; the prompt
+ * strips every arm/candidate word.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parseTestMetrics, computePerChangeLoss, measureHealthPenalty, resolveMetricSource, } from '../fitness/index.js';
+import { readProjectConfig } from '../project-config.js';
+import { claudeProjectsDir } from '../learn/trajectory-discovery.js';
+import { claudeSourceFactory } from '../trajectory/adapters/claude.js';
+import { toActionSkeleton } from '../trajectory/skeleton.js';
+import { runHeadlessAgent } from './host-harness.js';
+import { currentPolicyVersion, readPolicyLedger, readPolicySnapshotFiles, } from './policy/index.js';
+import { advanceEpisodeStage, writeArmCapture } from './episode-store.js';
+/** Error thrown when the worktree could not be created (git AND copy fallback failed). */
+export class CriticWorktreeError extends Error {
+    constructor(message) {
+        super(`critic worktree failed: ${message}`);
+        this.name = 'CriticWorktreeError';
+    }
+}
+/**
+ * Decide whether the CRITIC AGENT（基线智能体 baseline agent）should run for the
+ * NEXT episode.
+ *
+ * Skip (`run: false`) when:
+ *   - the 单一血统 single lineage has < 2 versions — there is no PRIOR policy to
+ *     rerun (v0 is the only point; the 主智能体 MAIN AGENT IS v0), OR
+ *   - the head 版本账本 ledger entry's action is 'refused' — the 演进智能体
+ *     EVOLVING AGENT refused last episode, so vN+1 ≡ vN and rerunning the
+ *     baseline would compare a policy against ITSELF (no advantage to measure).
+ *
+ * Otherwise run, rerunning the head version (vN, the policy the LAST episode
+ * settled on, which the current 主智能体 MAIN AGENT also runs as vN+1 unless an
+ * evolve happened — the comparison the 奖励智能体 REWARD AGENT scores).
+ *
+ * Pure read of the ledger via {@link readPolicyLedger}/{@link currentPolicyVersion};
+ * this function NEVER writes episode state. The skip path's
+ * {@link advanceEpisodeStage} to 'baseline-skipped' is the CALLER's job.
+ */
+export async function shouldRunCriticAgent(opts) {
+    const repoRoot = path.resolve(opts.repoRoot);
+    const ledger = await readPolicyLedger(repoRoot, opts.targetId);
+    if (ledger.length === 0) {
+        return {
+            run: false,
+            reason: `policy lineage for ${opts.targetId} is not initialized (no versions to rerun)`,
+            baselineVersion: null,
+        };
+    }
+    // A lineage with a single distinct version (only v0) has no PRIOR policy to
+    // compare against. The lineage head is monotonic, so "< 2 versions" is "head
+    // version is 0" — 'init' alone, or 'init' followed only by 'refused' entries
+    // (refused does not bump the version).
+    const head = ledger[ledger.length - 1];
+    const baselineVersion = await currentPolicyVersion(repoRoot, opts.targetId);
+    if (baselineVersion === null || baselineVersion < 1) {
+        return {
+            run: false,
+            reason: `policy lineage for ${opts.targetId} has < 2 versions (head v${baselineVersion ?? 0}); no prior policy to rerun`,
+            baselineVersion: null,
+        };
+    }
+    if (head.action === 'refused') {
+        return {
+            run: false,
+            reason: `last episode refused to evolve ${opts.targetId} (vN+1 ≡ vN); rerunning the baseline would compare a policy against itself`,
+            baselineVersion: null,
+        };
+    }
+    return {
+        run: true,
+        reason: `policy lineage for ${opts.targetId} head v${baselineVersion} (last action '${head.action}'); rerunning the baseline arm`,
+        baselineVersion,
+    };
+}
+export function assembleCriticPrompt(changeName, mode = 're-do') {
+    if (mode === 're-test') {
+        return [
+            `You are RE-RUNNING an existing SynergySpec change end-to-end to measure its`,
+            `test outcome under the artifact templates already installed in your working`,
+            `directory. This is a measurement run only — do NOT modify any canonical`,
+            `workflow prompt, artifact template, or schema, and do NOT edit the frozen`,
+            `gen-test/run-test oracle.`,
+            ``,
+            `Change name: ${changeName}`,
+            ``,
+            `Run the change's tests (apply → gen-test → run-test) and output the test`,
+            `runner's SUMMARY LINE verbatim as the final line of your response, e.g.`,
+            `"Tests  12 passed | 1 failed (13)" or "5 passed, 0 failed in 0.4s".`,
+        ].join('\n');
+    }
+    // 're-do' — regenerate the change end-to-end so the installed prior-policy
+    // design template is actually exercised.
+    return [
+        `You are RE-DOING an existing SynergySpec change from scratch under the`,
+        `artifact templates currently installed in your working directory, to measure`,
+        `the test outcome those templates produce. This is a measurement run.`,
+        ``,
+        `Change name: ${changeName}`,
+        ``,
+        `The change's INPUT artifacts (proposal.md, usecases.md, specs/) are present.`,
+        `Its design.md and tasks.md have been intentionally REMOVED so you regenerate`,
+        `them under the installed templates. Re-create the change end-to-end:`,
+        ``,
+        `1. Regenerate the design — run`,
+        `     synergyspec-selfevolving instructions design --change "${changeName}" --json`,
+        `   read the returned template + dependency files (proposal.md, usecases.md),`,
+        `   and author design.md using that template as the structure.`,
+        `2. Regenerate the tasks the same way`,
+        `   (synergyspec-selfevolving instructions tasks --change "${changeName}" --json),`,
+        `   then apply them — implement the code each task requires.`,
+        `3. Generate the change's tests (gen-test), then run the test runner (run-test).`,
+        ``,
+        `Do NOT modify any canonical workflow prompt, artifact TEMPLATE, or schema, and`,
+        `do NOT edit the frozen gen-test/run-test oracle. Write ONLY the change's own`,
+        `artifacts (design.md, tasks.md in the change dir) and the implementation`,
+        `source the tasks require.`,
+        ``,
+        `Output the test runner's SUMMARY LINE verbatim as the final line of your`,
+        `response, e.g. "Tests  12 passed | 1 failed (13)" or "5 passed, 0 failed in 0.4s".`,
+    ].join('\n');
+}
+/**
+ * Generated artifacts a 're-do' baseline removes from the copied change dir
+ * before the rerun, so the agent re-authors them under the installed prior
+ * policy. design.md + tasks.md are the policy-shaped chain; the report files are
+ * post-implementation residue that would otherwise read the change as already
+ * applied (status keys doneness off file existence). The INPUT artifacts
+ * (proposal.md, usecases.md, specs/) — which define "the same task" — are KEPT.
+ */
+const REDO_REGENERATED_ARTIFACTS = [
+    'design.md',
+    'tasks.md',
+    'test-report.md',
+    'test-plan.md',
+    'spec-tests.md',
+    'spec-blast-radius.md',
+    'verification-report.md',
+];
+/**
+ * Reset a copied change dir to its inputs for a 're-do' baseline (see
+ * {@link REDO_REGENERATED_ARTIFACTS}). Best-effort: a missing artifact is fine.
+ */
+async function resetChangeArtifactsForRedo(changeDir) {
+    for (const rel of REDO_REGENERATED_ARTIFACTS) {
+        await fs.rm(path.join(changeDir, rel), { force: true }).catch(() => { });
+    }
+}
+const NODE_MODULES = 'node_modules';
+const CONFIG_DIR = '.synergyspec-selfevolving';
+const SCHEMAS_REL = path.join('synergyspec-selfevolving', 'schemas');
+/**
+ * Run the CRITIC AGENT（基线智能体 baseline agent）'s full baseline arm and
+ * persist its capture. ALWAYS tears the worktree down (产物即弃). On success it
+ * advances the episode to 'baseline-arm-captured' (patch
+ * `{policyVersionBaseline}`). The SKIP path is the caller's job (see
+ * {@link shouldRunCriticAgent}).
+ */
+export async function runCriticAgent(opts) {
+    const repoRoot = path.resolve(opts.repoRoot);
+    const spawnImpl = opts.spawn ?? nodeSpawn;
+    const timeoutMs = opts.timeoutMs ?? 600000;
+    const homeDir = opts.homeDir ?? os.homedir();
+    const baselineMode = opts.baselineMode ?? 're-do';
+    if (!Number.isInteger(opts.baselineVersion) || opts.baselineVersion < 0) {
+        throw new Error(`runCriticAgent requires a non-negative integer baselineVersion, got ${JSON.stringify(opts.baselineVersion)}`);
+    }
+    const worktreeName = `synergyspec-critic-${opts.episodeId}`;
+    const worktreePath = path.join(os.tmpdir(), worktreeName);
+    // The run window opens just before the spawn; the claude transcript discovery
+    // selects the newest session file written after this instant.
+    const runStart = (opts.now ?? new Date()).getTime();
+    let worktreeMode = 'git-worktree';
+    try {
+        // 1) Isolated worktree OUTSIDE the repo (git worktree --detach, else copy).
+        worktreeMode = await createIsolatedWorktree(repoRoot, worktreePath, spawnImpl);
+        // 're-do' fidelity needs the detached-HEAD tree (pre-change code). The copy
+        // fallback (non-git repo) brings the LIVE tree — including the change's
+        // uncommitted implementation — so it cannot reach the pre-change state and
+        // degrades to a re-measure. Surface that so a degraded baseline is not silent.
+        if (baselineMode === 're-do' && worktreeMode === 'copy-fallback') {
+            console.warn(`[critic] re-do baseline degraded for "${opts.changeName}": no git worktree ` +
+                `(copy fallback) — the change's implementation could not be isolated, so the ` +
+                `baseline re-measures rather than re-does. Use a git repo, or set ` +
+                `selfEvolution.critic.baselineMode: re-test to silence this.`);
+        }
+        // 2) Make it runnable: node_modules junction/symlink + untracked surfaces.
+        await makeWorktreeRunnable(repoRoot, worktreePath, opts.changeName);
+        // 2b) 're-do': reset the copied change dir to its inputs so the rerun
+        //     RE-AUTHORS design+tasks under the prior policy (and re-implements on
+        //     the pre-change code the detached-HEAD worktree already holds). The
+        //     fidelity over 're-test' is that the design TEMPLATE is actually
+        //     exercised, so advantage reflects the policy change, not re-run noise.
+        if (baselineMode === 're-do') {
+            await resetChangeArtifactsForRedo(path.join(worktreePath, 'synergyspec-selfevolving', 'changes', opts.changeName));
+        }
+        // 3) INSTALL 策略 policy vN (byte-for-byte snapshot files) — the fidelity
+        //    fix the old GA replay never performed.
+        await installPolicyVersion(repoRoot, worktreePath, opts.targetId, opts.baselineVersion);
+        // 4) Rerun headlessly with cwd = worktree (re-do: regenerate; re-test: measure).
+        const prompt = assembleCriticPrompt(opts.changeName, baselineMode);
+        const run = await runHeadlessAgent(prompt, {
+            cwd: worktreePath,
+            spawn: spawnImpl,
+            timeoutMs,
+        });
+        // 5) Build + persist the baseline arm.
+        const measuredAt = new Date().toISOString();
+        const metrics = parseTestMetrics(run.stdout);
+        // Discover + normalize the claude session transcript for the WORKTREE path
+        // (newest session file written after `runStart`). Yields the observed
+        // verdict + the action skeleton; absent on non-claude harnesses or a miss.
+        const trajectory = await discoverWorktreeTrajectory({
+            worktreePath,
+            changeName: opts.changeName,
+            homeDir,
+            runStartMs: runStart,
+        });
+        const facts = trajectory
+            ? // Local import keeps the facts derivation in one place (learn uses the
+                // same function); imported lazily to avoid a top-level cycle hazard.
+                (await import('../trajectory/facts.js')).toTrajectoryFacts(trajectory, opts.changeName)
+            : null;
+        // Honesty: prefer the OBSERVED pass rate (a real runner ran), else the
+        // stdout-parsed summary; null when neither parsed (never fabricated).
+        const observedPassRate = facts?.testRunObserved && facts.observedPassRate !== null
+            ? facts.observedPassRate
+            : null;
+        const passRate = observedPassRate ?? metrics?.passRate ?? null;
+        const verified = facts ? facts.verified : false;
+        const observedStatus = facts ? facts.observedStatus : null;
+        // Health measured against the WORKTREE produced code, via the project's
+        // configured source (resolved from the worktree's copied config). No signal
+        // ⇒ null, exactly like the main arm.
+        const metricSource = resolveMetricSource(readProjectConfig(worktreePath));
+        const healthPenalty = (await measureHealthPenalty(metricSource, worktreePath)) ?? null;
+        const loss = passRate !== null
+            ? computePerChangeLoss({
+                passRate,
+                healthPenalty: healthPenalty ?? undefined,
+                verified: facts ? facts.verified : undefined,
+            }).loss
+            : null;
+        const objective = {
+            passRate,
+            ...(metrics ? { testsTotal: metrics.total, testsFailed: metrics.failed } : {}),
+            healthPenalty,
+            loss,
+            verified,
+            observedStatus,
+            measuredAt,
+            ...(facts ? { testRunObserved: facts.testRunObserved } : {}),
+            ...(facts?.observedFailures && facts.observedFailures.length > 0
+                ? { observedFailures: facts.observedFailures }
+                : {}),
+        };
+        // Transcript: the claude session `.jsonl` when discovered, else stdout.
+        let transcriptDiscovered = false;
+        let transcript;
+        let skeleton;
+        const sessionPath = trajectory?.sourcePaths[0];
+        if (trajectory && sessionPath) {
+            try {
+                const content = await fs.readFile(sessionPath, 'utf8');
+                transcript = { fileName: 'transcript.jsonl', content };
+                transcriptDiscovered = true;
+                const actionSkeleton = toActionSkeleton(trajectory);
+                if (actionSkeleton)
+                    skeleton = actionSkeleton;
+            }
+            catch {
+                // Unreadable session file — fall back to stdout below.
+                transcript = { fileName: 'stdout.txt', content: run.stdout };
+            }
+        }
+        else {
+            transcript = { fileName: 'stdout.txt', content: run.stdout };
+        }
+        const { armDir } = await writeArmCapture({
+            repoRoot,
+            episodeId: opts.episodeId,
+            arm: 'baseline-arm',
+            transcript,
+            ...(skeleton ? { skeleton } : {}),
+            objective,
+        });
+        // Record the arm landed (monotonic stage advance + which version reran).
+        await advanceEpisodeStage({
+            repoRoot,
+            episodeId: opts.episodeId,
+            stage: 'baseline-arm-captured',
+            patch: { policyVersionBaseline: opts.baselineVersion },
+        });
+        return {
+            armDir,
+            objective,
+            transcriptDiscovered,
+            worktreePath,
+            worktreeMode,
+            baselineMode,
+        };
+    }
+    finally {
+        // 6) 产物即弃: ALWAYS tear the worktree down — even when a step above threw.
+        await teardownWorktree(repoRoot, worktreePath, worktreeMode, spawnImpl);
+    }
+}
+// ---------------------------------------------------------------------------
+// Worktree lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Create an isolated worktree at `worktreePath` OUTSIDE the repo. Tries
+ * `git worktree add --detach <worktreePath> HEAD` first; on ANY git failure
+ * (not a repo, git missing, etc.) falls back to a recursive file copy of the
+ * repo excluding `node_modules` and `.git`. Returns which mode succeeded.
+ */
+async function createIsolatedWorktree(repoRoot, worktreePath, spawnImpl) {
+    // Best-effort: a stale worktree dir from an interrupted run would make both
+    // git-add and copy fail; clear it first (产物即弃 — nothing here is durable).
+    await fs.rm(worktreePath, { recursive: true, force: true }).catch(() => { });
+    try {
+        await runGit(repoRoot, ['worktree', 'add', '--detach', worktreePath, 'HEAD'], spawnImpl);
+        return 'git-worktree';
+    }
+    catch {
+        // Fall through to the copy fallback (not a git repo, git unavailable, …).
+    }
+    try {
+        await copyRepoTree(repoRoot, worktreePath);
+        return 'copy-fallback';
+    }
+    catch (err) {
+        throw new CriticWorktreeError(`git worktree add failed and the copy fallback failed too: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Tear down the worktree. For a git worktree: `git worktree remove --force` then
+ * `git worktree prune` (both best-effort), and an explicit rmdir to be sure.
+ * For the copy fallback: recursive rmdir. Never throws — teardown failures must
+ * not mask a real error from the run.
+ */
+async function teardownWorktree(repoRoot, worktreePath, mode, spawnImpl) {
+    if (mode === 'git-worktree') {
+        await runGit(repoRoot, ['worktree', 'remove', '--force', worktreePath], spawnImpl).catch(() => { });
+        await runGit(repoRoot, ['worktree', 'prune'], spawnImpl).catch(() => { });
+    }
+    // The node_modules entry is a junction/symlink; `rm -rf` removes the link, not
+    // the real tree behind it. Belt-and-suspenders rmdir for both modes.
+    await fs.rm(worktreePath, { recursive: true, force: true }).catch(() => { });
+}
+/** Run a git subcommand in `repoRoot`; rejects on a non-zero exit or spawn error. */
+async function runGit(repoRoot, args, spawnImpl) {
+    await new Promise((resolve, reject) => {
+        const child = spawnImpl('git', args, { cwd: repoRoot, shell: false });
+        const err = [];
+        child.stderr?.on('data', (c) => err.push(Buffer.from(c)));
+        child.on('error', (e) => reject(e));
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`git ${args[0]} exited ${code}: ${Buffer.concat(err).toString('utf8')}`));
+        });
+    });
+}
+/**
+ * Recursive copy of the repo tree into `dest`, excluding `node_modules` and
+ * `.git` (the two directories that are huge and/or meaningless in an isolated
+ * checkout — node_modules is re-linked separately, .git is the worktree's
+ * parent's concern).
+ */
+async function copyRepoTree(src, dest) {
+    await fs.cp(src, dest, {
+        recursive: true,
+        filter: (source) => {
+            const base = path.basename(source);
+            return base !== NODE_MODULES && base !== '.git';
+        },
+    });
+}
+/**
+ * Make the worktree runnable:
+ *   - junction/symlink `node_modules` into the worktree (junction on Windows so
+ *     no admin/dev-mode is needed; a plain dir symlink elsewhere), and
+ *   - copy the untracked surfaces the rerun reads that git worktree / the copy
+ *     filter do not bring: the change dir, the project-local schemas dir (if
+ *     present), and the `.synergyspec-selfevolving/` config EXCLUDING its
+ *     `self-evolution/` subdir (the loop's own state must NOT leak into the
+ *     isolated rerun).
+ */
+async function makeWorktreeRunnable(repoRoot, worktreePath, changeName) {
+    // node_modules link.
+    const srcNodeModules = path.join(repoRoot, NODE_MODULES);
+    if (await pathExists(srcNodeModules)) {
+        const destNodeModules = path.join(worktreePath, NODE_MODULES);
+        // A git worktree starts empty of node_modules; the copy fallback excluded
+        // it. Either way the dest should not exist — clear a stray one to be safe.
+        await fs.rm(destNodeModules, { recursive: true, force: true }).catch(() => { });
+        const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+        try {
+            await fs.symlink(srcNodeModules, destNodeModules, linkType);
+        }
+        catch {
+            // Symlink/junction unavailable (rare) — leave it absent; the rerun may
+            // still resolve the linked CLI from the parent install. Non-fatal.
+        }
+    }
+    // Untracked change dir (git tracks it once committed, but a fresh change is
+    // untracked; the copy fallback already brought it — copying is idempotent).
+    await copyDirInto(path.join(repoRoot, 'synergyspec-selfevolving', 'changes', changeName), path.join(worktreePath, 'synergyspec-selfevolving', 'changes', changeName));
+    // Project-local schemas dir, when present.
+    await copyDirInto(path.join(repoRoot, SCHEMAS_REL), path.join(worktreePath, SCHEMAS_REL));
+    // `.synergyspec-selfevolving/` config, EXCLUDING the self-evolution/ subdir.
+    const srcConfig = path.join(repoRoot, CONFIG_DIR);
+    if (await pathExists(srcConfig)) {
+        await fs.cp(srcConfig, path.join(worktreePath, CONFIG_DIR), {
+            recursive: true,
+            force: true,
+            filter: (source) => {
+                const rel = path.relative(srcConfig, source);
+                // Drop the loop's own state dir and everything under it.
+                return rel !== 'self-evolution' && !rel.startsWith(`self-evolution${path.sep}`);
+            },
+        });
+    }
+}
+/**
+ * INSTALL the byte-for-byte 策略 policy vN snapshot files into the worktree at
+ * their repo-relative paths. This is the fidelity fix: the baseline arm runs the
+ * SAME policy the LAST episode settled on, not whatever happens to be live.
+ * Snapshot reads are sha256-verified by {@link readPolicySnapshotFiles}, so a
+ * corrupt snapshot throws here rather than silently installing wrong bytes.
+ */
+async function installPolicyVersion(repoRoot, worktreePath, targetId, version) {
+    const files = await readPolicySnapshotFiles(repoRoot, targetId, version);
+    for (const f of files) {
+        const abs = path.join(worktreePath, ...f.relPath.split('/'));
+        // Defense-in-depth: snapshot relPaths are repo-relative POSIX paths; refuse
+        // anything that escapes the worktree.
+        const rel = path.relative(worktreePath, abs);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Refusing to install policy file outside the worktree: ${f.relPath}`);
+        }
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, f.content, 'utf8');
+    }
+}
+/**
+ * Discover + normalize the claude session transcript produced by the rerun, by
+ * computing the claude project-dir path-hash FOR THE WORKTREE PATH (the rerun's
+ * cwd) and picking the newest `.jsonl` written after the run started, then
+ * reusing the claude adapter to normalize it. Returns `null` on a non-claude
+ * harness, no projects dir, or no session file in the window — exactly the
+ * "no trajectory ⇒ stdout only" fallback the caller relies on.
+ *
+ * Reuses {@link claudeProjectsDir} (the path-hash encoding) and the public
+ * {@link claudeSourceFactory} (the per-line transcript parser + subagent
+ * stitching) so this never reimplements either; full reuse, no new exports.
+ */
+async function discoverWorktreeTrajectory(opts) {
+    const projectsDir = claudeProjectsDir(opts.worktreePath, opts.homeDir);
+    // No projects dir for the worktree ⇒ the host harness is not claude (or never
+    // wrote a session). Skip cleanly.
+    let entries;
+    try {
+        entries = await fs.readdir(projectsDir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    // Newest `.jsonl` whose mtime is within the run window (>= runStart). Picking
+    // the newest matches trajectory-discovery's window intent: the rerun's own
+    // session is the most-recently-written one under the worktree's project dir.
+    let newest = null;
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+            continue;
+        const full = path.join(projectsDir, entry.name);
+        let mtimeMs;
+        try {
+            mtimeMs = (await fs.stat(full)).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (mtimeMs < opts.runStartMs)
+            continue;
+        if (!newest || mtimeMs > newest.mtimeMs)
+            newest = { path: full, mtimeMs };
+    }
+    if (!newest)
+        return null;
+    // Normalize via the claude adapter. The source's getTrajectory re-discovers
+    // through findTranscriptsForChange against the WORKTREE root: with no
+    // events.ndjson it uses the mtime-overlap fallback over this same projects
+    // dir, so the session we just selected is the one normalized (main session +
+    // its subagents stitched). Detect against the worktree so the source is
+    // pinned to the worktree's project hash.
+    try {
+        const source = await claudeSourceFactory.detect(opts.worktreePath, {
+            homeDir: opts.homeDir,
+        });
+        if (!source)
+            return null;
+        return await source.getTrajectory(opts.changeName);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Small fs helpers (match the neighbor idiom: no throw on probe)
+// ---------------------------------------------------------------------------
+async function pathExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Recursive copy of `src` into `dest` when `src` exists; idempotent, no throw on a missing src. */
+async function copyDirInto(src, dest) {
+    if (!(await pathExists(src)))
+        return;
+    await fs.cp(src, dest, { recursive: true, force: true });
+}
+//# sourceMappingURL=critic-agent.js.map

package/dist/core/self-evolution/edits-contract.d.ts

@@ -0,0 +1,53 @@
+export declare class CanonicalProposerOutputInvalid extends Error {
+    constructor(message: string);
+}
+/** The model declined to edit anything (empty edits). Not an error — a no-op. */
+export declare class CanonicalProposerNoOp extends Error {
+    constructor();
+}
+/** The headless agent invocation itself failed (crash / empty output). */
+export declare class CanonicalProposerInvocationError extends Error {
+    constructor(stderr: string);
+}
+/**
+ * The packaged result of one validated candidate edit set: the human-readable
+ * unified diff, the POSIX paths actually edited (a subset of the target's
+ * declared files), a non-empty rationale, and the parsed full-file-replacement
+ * edits. Produced by the manual host-authored channel (`packageHostEdits`).
+ */
+export interface CanonicalProposeOutput {
+    targetId: string;
+    /** A unified-diff rendering of the edits (opaque to the gate; readable by a human). */
+    diffPatch: string;
+    /** POSIX paths actually edited — always a subset of the target's declared files. */
+    changedFiles: string[];
+    /** Non-empty rationale (the static gate requires one). */
+    rationale: string;
+    /** The parsed full-file-replacement edits. */
+    edits: {
+        relPath: string;
+        content: string;
+    }[];
+}
+/**
+ * Validate already-structured candidate edits against the allowed (target-
+ * scoped) file set and the frozen gate-defining files. Author-agnostic: this is
+ * the SINGLE place that enforces, at propose time, that every edit (a) is a
+ * well-formed `{relPath, content}` object, (b) does not touch a
+ * `GATE_DEFINING_FILES` entry (the frozen oracle/gate files), and (c) stays
+ * inside `allowedFiles`. Both the manual host-authored (`--from-edits`) path and
+ * the loop-v2 演进智能体 EVOLVING AGENT call this so their safety contract is
+ * byte-identical. relPaths are normalized to POSIX separators.
+ *
+ * Throws {@link CanonicalProposerNoOp} when `rawEdits` is empty and
+ * {@link CanonicalProposerOutputInvalid} for any shape / frozen / scope
+ * violation. Path traversal and absolute paths are rejected transitively: they
+ * can never be a member of `allowedFiles`, so they fail the scope check.
+ */
+export declare function validateCandidateEdits(rawEdits: readonly unknown[], allowedFiles: readonly string[]): {
+    relPath: string;
+    content: string;
+}[];
+/** Render a whole-file-replacement unified diff (human-readable; git-apply friendly). */
+export declare function renderUnifiedDiff(relPath: string, oldContent: string, newContent: string): string;
+//# sourceMappingURL=edits-contract.d.ts.map