@evomap/evolver-core 2.0.0-beta.0

package/dist/exec/claudeBridge.js

@@ -0,0 +1,219 @@
+// The Claude Code execution bridge — the REAL implementation of CycleEngine's `execute` seam (ported from
+// v1's exec bridge, EVOLVE_EXEC_BRIDGE-gated). It renders the mutation into an instruction, runs a coding
+// agent against a working directory, measures proof-of-work from the git diff, and (optionally) runs a
+// validation hook to decide success. Everything external (the agent, git, validation) is an injected seam,
+// so the whole bridge is unit-testable with fakes and NEVER spawns a real agent in tests.
+//
+// The runner layer (how to spawn a CLI shell-free, the per-runner argv/factories, the runner registry) lives
+// in ./runnerRegistry.ts (#91 item 6); this file is the bridge orchestration around it. Env scrubbing stays
+// here — it is a bridge-side security control, not a runner concern.
+//
+// SAFETY: default-OFF. The factory throws ExecBridgeDisabledError unless explicitly enabled (opts.enabled)
+// or EVOLVE_EXEC_BRIDGE === '1'. Wiring it in by accident must fail loudly rather than silently spawn an
+// autonomous agent.
+import { resolve as resolvePath, sep, join as joinPath } from 'node:path';
+import { tmpdir } from 'node:os';
+import { writeFileSync } from 'node:fs';
+import { renderExecPrompt } from './prompt.js';
+import { parseGitShortstat, gitDiffProof } from './proofOfWork.js';
+// Policy enforcement core (#107): checkPolicy runs the always-on global guards (blast hard cap +
+// protected paths + destructive deletes) on EVERY exec — gene or not — plus the per-gene constraints when a
+// gene supplies them. It supersedes the old gene-gated `checkChangeConstraints` call (the no-gene-no-guard hole).
+import { checkPolicy, summarizeViolations } from './policy/index.js';
+import { spawnCapture, getRunnerSpec, DEFAULT_TIMEOUT_MS } from './runnerRegistry.js';
+// Re-export the runner layer so existing importers of ./claudeBridge.js (and the `exec` namespace) keep their
+// surface after the #91-6 split — the registry simply has a clearer home now.
+export { resolveSpawnCommand, spawnCapture, UnboundedSkipPermissionsError, UnsupportedCursorSkipPermissionsError, claudeRunnerArgs, makeClaudeHeadlessRunner, claudeHeadlessRunner, codexRunnerArgs, makeCodexHeadlessRunner, cursorRunnerArgs, makeCursorHeadlessRunner, getRunnerSpec, } from './runnerRegistry.js';
+export class ExecBridgeDisabledError extends Error {
+    constructor() {
+        super('exec bridge is disabled — set EVOLVE_EXEC_BRIDGE=1 or pass { enabled: true } to enable agent execution');
+        this.name = 'ExecBridgeDisabledError';
+    }
+}
+/** Thrown when the agent's working directory is outside the configured allowedRoots (deny-by-default guardrail). */
+export class ExecBridgeForbiddenError extends Error {
+    constructor(cwd) {
+        super(`exec bridge refused: cwd ${cwd} is not within any allowedRoots — an autonomous agent may only edit allowlisted repos`);
+        this.name = 'ExecBridgeForbiddenError';
+    }
+}
+/**
+ * Thrown when a FULL-ACCESS (or unverified) agent run is requested without worktree isolation. The throwaway
+ * worktree is the containment WE control — allowedRoots gates the cwd but cannot stop an auto-approved or
+ * unsandboxed process writing/running outside it. Gated runners:
+ *  - codex with skipPermissions → `--sandbox danger-full-access` (no inner OS sandbox). Without skip it stays
+ *    workspace-write, so only the skip path is gated.
+ *  - cursor default → gated UNCONDITIONALLY. cursor-agent base `-p` already documents write+shell access, cursor
+ *    skipPermissions is rejected by the runner layer, and the scaffold remains unverified (#66/#181) — so default
+ *    cursor still needs the wrapper worktree rather than risk mutating the real tree.
+ * claude is exempt: its skip is bounded by --allowedTools (finding #80).
+ */
+export class UnsandboxedFullAccessRequiresIsolationError extends Error {
+    constructor() {
+        super('a full-access or unverified agent run (codex --sandbox danger-full-access, or any cursor scaffold run) can auto-approve shell+write and requires isolation: "worktree" — refusing to run it against the real working tree');
+        this.name = 'UnsandboxedFullAccessRequiresIsolationError';
+    }
+}
+/** Whether `child` is the same as, or nested under, `root` (both resolved to absolute paths). */
+function isWithinRoot(child, root) {
+    const c = resolvePath(child);
+    const r = resolvePath(root);
+    return c === r || c.startsWith(r.endsWith(sep) ? r : r + sep);
+}
+/**
+ * Sensitive env keys to strip before spawning an agent/tool (finding #39.2): evolver/hub/cloud secrets must
+ * not be inherited by an autonomous agent (it could exfiltrate them via its tools). The base keeps only NEUTRAL
+ * system env — vendor auth is NOT in the base; each runner contributes its OWN via envAllow (#66), so one
+ * runner's key (e.g. ANTHROPIC_) is never handed to another agent (e.g. codex).
+ */
+// WHITELIST, fail-safe (#39.2 / #46): default-DENY — only explicitly-allowed env vars reach the agent. A
+// denylist of secret-shaped names can miss a future sensitive var; a whitelist can't. The base allow-set is
+// ONLY NEUTRAL system env (no vendor auth) — per-runner auth (ANTHROPIC_/CLAUDE_ for claude, OPENAI_/CODEX_ for
+// codex) is contributed by each runner's envAllow (#66), so one runner's key is never handed to another agent.
+// Callers extend via opts.allowKeys / allowPrefixes when an agent legitimately needs more.
+const ALLOW_ENV_PREFIXES = ['XDG_', 'LC_', 'NPM_CONFIG_'];
+const ALLOW_ENV_KEYS = new Set([
+    'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LANGUAGE', 'TERM', 'TZ', 'PWD', 'HOSTNAME',
+    'TMPDIR', 'TMP', 'TEMP', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
+    // Windows OS essentials (absent on POSIX → no-op there): a process can't run, resolve PATHEXT shims, or find
+    // its own per-user config/auth dir without these. They are OS runtime vars, NOT app secrets — the secret
+    // env (NODE_SECRET/AWS_*/GH_TOKEN/vendor keys) is still denied by the whitelist. Their absence is why an
+    // npm-installed agent (codex) failed on Windows while the native claude.exe happened to run (#66).
+    'SystemRoot', 'SystemDrive', 'windir', 'ComSpec', 'PATHEXT', 'NUMBER_OF_PROCESSORS',
+    'PROCESSOR_ARCHITECTURE', 'PROCESSOR_IDENTIFIER', 'PROCESSOR_LEVEL', 'PROCESSOR_REVISION',
+    'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA',
+]);
+/**
+ * Whitelist-filter `env` for a spawned agent/tool: keep ONLY the minimal runtime env + the caller-declared
+ * extras (the runner's own auth via allowPrefixes/allowKeys); drop everything else. Fail-safe by construction —
+ * an unlisted var never leaks.
+ */
+export function scrubAgentEnv(env, opts = {}) {
+    const allowKeys = new Set([...ALLOW_ENV_KEYS, ...(opts.allowKeys ?? [])]);
+    const allowPrefixes = [...ALLOW_ENV_PREFIXES, ...(opts.allowPrefixes ?? [])];
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (v === undefined)
+            continue;
+        if (allowKeys.has(k) || allowPrefixes.some((p) => k.startsWith(p)))
+            out[k] = v;
+    }
+    return out;
+}
+/** Default git runner: spawn `git <args>` in cwd, return stdout (empty string on error). Env scrubbed — git never needs evolver/hub secrets. */
+export const defaultGitRunner = async (args, cwd) => {
+    try {
+        const r = await spawnCapture('git', args, { cwd, timeoutMs: 30_000, env: scrubAgentEnv(process.env) });
+        return r.stdout;
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * Build the `execute` function CycleEngine/runEvolutionCycle consume. Default-off: throws
+ * ExecBridgeDisabledError on first call unless enabled.
+ */
+export function makeClaudeExecBridge(opts) {
+    const enabled = opts.enabled ?? (process.env['EVOLVE_EXEC_BRIDGE'] === '1');
+    const spec = getRunnerSpec(opts.runner); // #66: claude (default, byte-identical) | codex
+    const agent = opts.agent ?? spec.makeRunner(opts.agentOptions);
+    const git = opts.git ?? defaultGitRunner;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // secure by default; only THIS runner's auth env reaches it (claude never gets OPENAI_, codex never ANTHROPIC_, #66)
+    const agentEnv = opts.scrubEnv === false ? undefined : scrubAgentEnv(process.env, { allowPrefixes: spec.envAllow.prefixes, ...(spec.envAllow.keys ? { allowKeys: spec.envAllow.keys } : {}) });
+    // Fail-fast when a run that can write/execute against the tree with no inner sandbox we control is requested
+    // without the throwaway worktree as containment (allowedRoots gates the cwd but can't stop a write outside it).
+    // Only when WE build the runner — an injected `agent` bypasses the built-in runner:
+    //  - codex: only its skip path emits --sandbox danger-full-access; without skip it stays workspace-write.
+    //  - cursor: gated UNCONDITIONALLY. cursor-agent base `-p` already has write+shell access, its skipPermissions
+    //    path is refused by runnerRegistry, and the runner is an unverified scaffold (#66/#181), so we do not let
+    //    default cursor touch the real tree until run-verified. (Bugbot High #181)
+    // claude is exempt — its skip is bounded by --allowedTools (finding #80).
+    const needsIsolation = opts.runner === 'cursor'
+        || (opts.runner === 'codex' && opts.agentOptions?.skipPermissions === true);
+    if (!opts.agent && needsIsolation && opts.isolation !== 'worktree') {
+        throw new UnsandboxedFullAccessRequiresIsolationError();
+    }
+    return async (mutation, decision) => {
+        if (!enabled)
+            throw new ExecBridgeDisabledError();
+        // Deny-by-default guardrail: an autonomous agent may only edit allowlisted repos. Checked before the
+        // agent is ever spawned, so a forbidden cwd never runs anything.
+        if (opts.allowedRoots !== undefined && !opts.allowedRoots.some((root) => isWithinRoot(opts.cwd, root))) {
+            throw new ExecBridgeForbiddenError(opts.cwd);
+        }
+        const resolveId = decision.selectedAssetId ?? decision.selectedGeneId;
+        const resolved = resolveId && opts.resolveGene ? await opts.resolveGene(resolveId) : null;
+        // Trust gate (finding #39.3): for unattended runs, only embed a gene we trust — an untrusted gene's strategy
+        // is dropped so a poisoned strategy can't drive the autonomous agent (the run falls back to innovate).
+        const gene = resolved && (!opts.requireTrustedGene || resolved.trusted === true) ? resolved : null;
+        const prompt = renderExecPrompt({
+            mutation,
+            decision,
+            ...(gene ? { gene } : {}),
+            ...(opts.validationCmds ? { validationCmds: opts.validationCmds } : {}),
+            // use-case ①: inject the personality style block from the state applySelectForRun just persisted.
+            ...(opts.personality ? { personality: opts.personality.currentState() } : {}),
+        });
+        // Isolation: run in a throwaway git worktree so the agent's edits never touch the real working tree.
+        const isolate = opts.isolation === 'worktree';
+        const workDir = isolate ? joinPath(tmpdir(), `evolver-wt-${mutation.id}`) : opts.cwd;
+        if (isolate)
+            await git(['worktree', 'add', '--detach', workDir, 'HEAD'], opts.cwd);
+        try {
+            const run = await agent(prompt, { cwd: workDir, timeoutMs, ...(agentEnv ? { env: agentEnv } : {}) });
+            const stat = parseGitShortstat(await git(['diff', '--shortstat'], workDir));
+            // ENFORCE policy against the ACTUAL diff (finding: prompt.ts only ADVISES the agent "touch at most N
+            // file(s) / never modify X"; this is the hard gate). checkPolicy ALWAYS runs the global guards — the
+            // system blast hard cap (EVOLVER_HARD_CAP_FILES/LINES), the critical-protected paths (.env, MEMORY.md,
+            // package.json, the evolver skill, …), and destructive deletes of those paths — so a no-gene / no-
+            // constraints run is no longer un-guarded. The gene's max_files/max_lines/forbidden_paths layer on top.
+            // Any violation fails the cycle no matter what the agent did — even when validation would pass.
+            const changedFiles = (await git(['diff', '--name-only'], workDir)).split('\n').map((s) => s.trim()).filter(Boolean);
+            const numstat = await git(['diff', '--numstat'], workDir);
+            const violations = checkPolicy({ stat, changedFiles, numstat, ...(gene?.constraints ? { constraints: gene.constraints } : {}) });
+            let patchRef;
+            if (isolate && stat.files > 0) {
+                // preserve the isolated edits as a patch (the worktree itself is removed); the real repo is untouched
+                patchRef = joinPath(tmpdir(), `evolver-patch-${mutation.id}.diff`);
+                writeFileSync(patchRef, await git(['diff'], workDir));
+            }
+            const proof = gitDiffProof(stat, patchRef);
+            // Success: prefer the authoritative validation hook; otherwise "agent succeeded AND produced a diff".
+            let passed = run.ok && stat.files > 0;
+            let score = passed ? 0.7 : run.ok ? 0.4 : 0.1; // ran-but-no-change is weak, not a clean failure
+            // Only validate a change that already respects the constraints — a constraint-violating diff is never
+            // a success regardless of what its tests say.
+            if (run.ok && opts.validate && violations.length === 0) {
+                const v = await opts.validate(mutation, decision, workDir);
+                passed = v.passed;
+                score = v.score ?? (v.passed ? 0.9 : 0.2);
+            }
+            let reason;
+            if (violations.length > 0) {
+                passed = false;
+                score = Math.min(score, 0.1);
+                reason = summarizeViolations(violations);
+            }
+            return {
+                outcome: { status: passed ? 'success' : 'failed', score, ...(reason ? { reason } : {}) },
+                proofOfWork: proof,
+                strongEvidence: passed && stat.files > 0,
+                // On a FAILED outcome, hand the agent transcript (stdout + stderr) to the cycle engine as host-side
+                // triage context (#279): an empty transcript -> host_no_transcript, a provider-error string ->
+                // host_provider_error. Omitted on success (failure-only context; never persisted).
+                ...(passed ? {} : { sessionLog: run.error ? `${run.output}\n${run.error}` : run.output }),
+            };
+        }
+        finally {
+            if (isolate) {
+                try {
+                    await git(['worktree', 'remove', '--force', workDir], opts.cwd);
+                }
+                catch { /* best-effort cleanup */ }
+            }
+        }
+    };
+}

package/dist/exec/index.d.ts

@@ -0,0 +1,9 @@
+export * from './prompt.js';
+export * from './proofOfWork.js';
+export * from './policy/index.js';
+export * from './openPrRegistry.js';
+export * from './claudeBridge.js';
+export * from './autonomousCycle.js';
+export * from './autoExec.js';
+export * from './selfPr.js';
+export * from './selfPrObfuscation.js';

package/dist/exec/index.js

@@ -0,0 +1,11 @@
+export * from './prompt.js';
+export * from './proofOfWork.js';
+// The policy enforcement core (checkPolicy + the split guards). policyCheck.js is a back-compat shim that
+// re-exports the per-gene checker from here, so it is intentionally NOT re-exported again (would duplicate names).
+export * from './policy/index.js';
+export * from './openPrRegistry.js';
+export * from './claudeBridge.js';
+export * from './autonomousCycle.js';
+export * from './autoExec.js';
+export * from './selfPr.js';
+export * from './selfPrObfuscation.js';

package/dist/exec/openPrRegistry.d.ts

@@ -0,0 +1,60 @@
+export interface OpenPr {
+    number: number;
+    title: string;
+    headRefName: string;
+    files: readonly string[];
+}
+export interface FileOverlap {
+    overlap: true;
+    prNumber: number;
+    prTitle: string;
+    headRefName: string;
+    /** |shared| / |changedFiles| — what fraction of MY change is the PR already doing. */
+    overlapRatio: number;
+    sharedFiles: string[];
+}
+export type FileOverlapResult = FileOverlap | {
+    overlap: false;
+    reason: string;
+};
+export interface SignalHint {
+    number: number;
+    title: string;
+    headRefName: string;
+    files: readonly string[];
+    /** |shared signal tokens| / |signal tokens| — how much of the task's vocabulary the PR already covers. */
+    tokenOverlap: number;
+}
+/** List the repo's open PRs. Default = `gh pr list`; inject a fake in tests. cwd selects the repo. */
+export type OpenPrLister = (cwd?: string) => Promise<OpenPr[]>;
+/**
+ * Strongest file overlap by ratio = |shared| / |changedFiles|. We use the CYCLE's changed-file count as the
+ * denominator (not the PR's): the question is "is this cycle re-doing work the PR already does?" — so a daemon
+ * that changes 4 files, 3 of which are in a PR's 11-file diff, scores 0.75 (re-doing most of its own work)
+ * even though that's only 0.27 of the PR. Returns { overlap:false, reason } when there's nothing to compare.
+ */
+export declare function findFileOverlap(changedFiles: readonly string[], prs: readonly OpenPr[]): FileOverlapResult;
+/**
+ * Token overlap between a task's signals and each PR's title + branch name — the pre-exec dedup signal, used
+ * before any files exist. Returns the top-N PRs whose token overlap meets `threshold` (default 0.5), strongest
+ * first. Denominator is the signal-token set, so this asks "how much of what I'm about to work on does this PR
+ * already mention?".
+ */
+export declare function findSignalHints(signals: readonly string[], prs: readonly OpenPr[], opts?: {
+    threshold?: number;
+    topN?: number;
+}): SignalHint[];
+/**
+ * Default lister: `gh pr list --state=open --json number,title,headRefName,files --limit 50`. Graceful —
+ * returns [] on any failure (gh missing, unauthenticated, timeout, bad JSON) so dedup just turns off. gh is a
+ * trusted infra tool, so its own auth (GH_TOKEN/GITHUB_TOKEN, or the gh config under $HOME) is passed through.
+ */
+export declare function makeGhPrLister(): OpenPrLister;
+/**
+ * Wrap a lister with a TTL cache + single-flight: a resident daemon polls often, but the open-PR set changes
+ * slowly — don't shell `gh` every tick. Concurrent callers within the window share one in-flight fetch.
+ */
+export declare function makeCachedPrLister(lister: OpenPrLister, opts?: {
+    ttlMs?: number;
+    now?: () => number;
+}): OpenPrLister;

package/dist/exec/openPrRegistry.js

@@ -0,0 +1,130 @@
+// Open-PR dedup (ported from v1 src/gep/openPRRegistry.js). An autonomous loop has been observed to
+// independently re-implement work already in flight on an open PR — wasting a full agent run and dirtying
+// the tree with a near-duplicate diff. This module lets the daemon ask, cheaply and BEFORE spawning an
+// agent, "is an open PR already doing this?" (token overlap of the task's signals against PR titles/branches),
+// and AFTER a diff, "does my change substantially overlap an open PR's files?" (file-set overlap).
+//
+// Seam-based like the rest of exec: the PR list is an injected OpenPrLister (default shells `gh pr list`).
+// Graceful + opt-in: the default lister returns [] if gh is missing/unauthenticated/errors, so dedup simply
+// turns itself off rather than failing a run; the daemon only consults it when a lister is wired in.
+import { spawnCapture, scrubAgentEnv } from './claudeBridge.js';
+// ── pure logic (fully testable, no subprocess) ─────────────────────────────
+/**
+ * Strongest file overlap by ratio = |shared| / |changedFiles|. We use the CYCLE's changed-file count as the
+ * denominator (not the PR's): the question is "is this cycle re-doing work the PR already does?" — so a daemon
+ * that changes 4 files, 3 of which are in a PR's 11-file diff, scores 0.75 (re-doing most of its own work)
+ * even though that's only 0.27 of the PR. Returns { overlap:false, reason } when there's nothing to compare.
+ */
+export function findFileOverlap(changedFiles, prs) {
+    const files = changedFiles.map(String).filter(Boolean);
+    if (files.length === 0)
+        return { overlap: false, reason: 'no_changed_files' };
+    if (prs.length === 0)
+        return { overlap: false, reason: 'no_open_prs' };
+    const changedSet = new Set(files);
+    let best = null;
+    for (const pr of prs) {
+        if (!pr.files?.length)
+            continue;
+        const prSet = new Set(pr.files.map(String));
+        const shared = [...changedSet].filter((f) => prSet.has(f));
+        if (shared.length === 0)
+            continue;
+        const ratio = shared.length / files.length;
+        if (!best || ratio > best.overlapRatio) {
+            best = { overlap: true, prNumber: pr.number, prTitle: pr.title, headRefName: pr.headRefName, overlapRatio: ratio, sharedFiles: shared };
+        }
+    }
+    return best ?? { overlap: false, reason: 'no_intersection' };
+}
+function tokenize(s) {
+    return String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').split(/\s+/).filter((t) => t.length >= 3);
+}
+/**
+ * Token overlap between a task's signals and each PR's title + branch name — the pre-exec dedup signal, used
+ * before any files exist. Returns the top-N PRs whose token overlap meets `threshold` (default 0.5), strongest
+ * first. Denominator is the signal-token set, so this asks "how much of what I'm about to work on does this PR
+ * already mention?".
+ */
+export function findSignalHints(signals, prs, opts = {}) {
+    const threshold = opts.threshold ?? 0.5;
+    const topN = opts.topN ?? 3;
+    const sigTokens = new Set();
+    for (const s of signals)
+        for (const t of tokenize(s))
+            sigTokens.add(t);
+    if (sigTokens.size === 0 || prs.length === 0)
+        return [];
+    const hits = [];
+    for (const pr of prs) {
+        const prTokens = new Set();
+        for (const t of tokenize(pr.title))
+            prTokens.add(t);
+        for (const t of tokenize(pr.headRefName))
+            prTokens.add(t);
+        if (prTokens.size === 0)
+            continue;
+        let common = 0;
+        sigTokens.forEach((t) => { if (prTokens.has(t))
+            common++; });
+        const ratio = common / sigTokens.size;
+        if (ratio >= threshold) {
+            hits.push({ number: pr.number, title: pr.title, headRefName: pr.headRefName, files: (pr.files ?? []).slice(0, 5), tokenOverlap: ratio });
+        }
+    }
+    hits.sort((a, b) => b.tokenOverlap - a.tokenOverlap);
+    return hits.slice(0, topN);
+}
+// ── gh lister seam + TTL cache ─────────────────────────────────────────────
+const GH_TIMEOUT_MS = 5000;
+/**
+ * Default lister: `gh pr list --state=open --json number,title,headRefName,files --limit 50`. Graceful —
+ * returns [] on any failure (gh missing, unauthenticated, timeout, bad JSON) so dedup just turns off. gh is a
+ * trusted infra tool, so its own auth (GH_TOKEN/GITHUB_TOKEN, or the gh config under $HOME) is passed through.
+ */
+export function makeGhPrLister() {
+    return async (cwd) => {
+        try {
+            const r = await spawnCapture('gh', ['pr', 'list', '--state=open', '--json', 'number,title,headRefName,files', '--limit', '50'], {
+                cwd: cwd ?? process.cwd(),
+                timeoutMs: GH_TIMEOUT_MS,
+                env: scrubAgentEnv(process.env, { allowKeys: ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_HOST', 'GH_CONFIG_DIR'] }),
+            });
+            if (r.code !== 0)
+                return [];
+            const arr = JSON.parse(r.stdout || '[]');
+            if (!Array.isArray(arr))
+                return [];
+            return arr.map((pr) => ({
+                number: Number(pr.number),
+                title: String(pr.title ?? ''),
+                headRefName: String(pr.headRefName ?? ''),
+                files: Array.isArray(pr.files) ? pr.files.map((f) => String(f.path ?? '')).filter(Boolean) : [],
+            }));
+        }
+        catch {
+            return [];
+        }
+    };
+}
+/**
+ * Wrap a lister with a TTL cache + single-flight: a resident daemon polls often, but the open-PR set changes
+ * slowly — don't shell `gh` every tick. Concurrent callers within the window share one in-flight fetch.
+ */
+export function makeCachedPrLister(lister, opts = {}) {
+    const ttlMs = opts.ttlMs ?? 60_000;
+    const now = opts.now ?? (() => Date.now());
+    let cache = null;
+    let cacheAt = 0;
+    let inflight = null;
+    return (cwd) => {
+        if (cache && now() - cacheAt < ttlMs)
+            return Promise.resolve(cache);
+        if (inflight)
+            return inflight; // share the in-flight fetch rather than spawning a second gh
+        inflight = lister(cwd)
+            .then((fresh) => { cache = fresh; cacheAt = now(); return fresh; })
+            .finally(() => { inflight = null; });
+        return inflight;
+    };
+}

package/dist/exec/policy/blastRadius.d.ts

@@ -0,0 +1,31 @@
+import type { DiffStat } from '../proofOfWork.js';
+import type { ChangeConstraints, PolicyViolation } from './constraints.js';
+/** System-wide blast caps. Env-overridable (EVOLVER_HARD_CAP_FILES / EVOLVER_HARD_CAP_LINES), same names/defaults as v1. */
+export declare function globalHardCaps(): {
+    files: number;
+    lines: number;
+};
+export type BlastSeverity = 'hard_cap_breach' | 'critical_overrun' | 'exceeded' | 'approaching_limit' | 'within_limit';
+/**
+ * Classify a diff's blast radius (ported from v1 classifyBlastSeverity). The global hard cap is checked first
+ * and is independent of any per-gene maxFiles (so it fires even when maxFiles is undefined). When a per-gene
+ * maxFiles is given, the over-limit / 2x-critical / approaching bands apply on top.
+ */
+export declare function classifyBlastSeverity(stat: DiffStat, maxFiles?: number, caps?: {
+    files: number;
+    lines: number;
+}): {
+    severity: BlastSeverity;
+    message: string;
+};
+/**
+ * GLOBAL blast-radius guard — ALWAYS enforced. Returns a violation when the diff breaches the system hard cap
+ * (files or lines), regardless of whether a gene/constraints are present. The per-gene `critical_overrun` band
+ * (2x the gene's own max_files) is also surfaced as a violation when a gene cap is supplied; the softer
+ * `approaching_limit` band is a warning, not a violation. Per-gene `exceeded` (files > max_files) is handled by
+ * constraints.ts so the two layers don't double-report; here we only escalate the global cap + the 2x overrun.
+ */
+export declare function checkBlastRadius(stat: DiffStat, constraints?: ChangeConstraints, caps?: {
+    files: number;
+    lines: number;
+}): PolicyViolation[];

package/dist/exec/policy/blastRadius.js

@@ -0,0 +1,67 @@
+/** Read a positive integer env override, falling back to a default (mirrors v1 config.js envInt). */
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '')
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** System-wide blast caps. Env-overridable (EVOLVER_HARD_CAP_FILES / EVOLVER_HARD_CAP_LINES), same names/defaults as v1. */
+export function globalHardCaps() {
+    return {
+        files: envInt('EVOLVER_HARD_CAP_FILES', 60),
+        lines: envInt('EVOLVER_HARD_CAP_LINES', 20000),
+    };
+}
+// Severity ratio bands ported verbatim from v1 policyCheck.js.
+const BLAST_WARN_RATIO = 0.8;
+const BLAST_CRITICAL_RATIO = 2.0;
+/**
+ * Classify a diff's blast radius (ported from v1 classifyBlastSeverity). The global hard cap is checked first
+ * and is independent of any per-gene maxFiles (so it fires even when maxFiles is undefined). When a per-gene
+ * maxFiles is given, the over-limit / 2x-critical / approaching bands apply on top.
+ */
+export function classifyBlastSeverity(stat, maxFiles, caps = globalHardCaps()) {
+    const files = Number(stat.files) || 0;
+    const lines = Number(stat.lines) || 0;
+    if (files > caps.files || lines > caps.lines) {
+        return {
+            severity: 'hard_cap_breach',
+            message: `HARD CAP BREACH: ${files} files / ${lines} lines exceeds system limit (${caps.files} files / ${caps.lines} lines)`,
+        };
+    }
+    if (maxFiles === undefined || !Number.isFinite(maxFiles) || maxFiles <= 0) {
+        return { severity: 'within_limit', message: 'no max_files constraint defined' };
+    }
+    if (files > maxFiles * BLAST_CRITICAL_RATIO) {
+        return {
+            severity: 'critical_overrun',
+            message: `CRITICAL OVERRUN: ${files} files > ${maxFiles * BLAST_CRITICAL_RATIO} (${BLAST_CRITICAL_RATIO}x limit of ${maxFiles}). Agent likely performed bulk/unintended operation.`,
+        };
+    }
+    if (files > maxFiles) {
+        return { severity: 'exceeded', message: `max_files exceeded: ${files} > ${maxFiles}` };
+    }
+    if (files > maxFiles * BLAST_WARN_RATIO) {
+        return {
+            severity: 'approaching_limit',
+            message: `approaching limit: ${files} / ${maxFiles} files (${Math.round((files / maxFiles) * 100)}%)`,
+        };
+    }
+    return { severity: 'within_limit', message: `${files} / ${maxFiles} files` };
+}
+/**
+ * GLOBAL blast-radius guard — ALWAYS enforced. Returns a violation when the diff breaches the system hard cap
+ * (files or lines), regardless of whether a gene/constraints are present. The per-gene `critical_overrun` band
+ * (2x the gene's own max_files) is also surfaced as a violation when a gene cap is supplied; the softer
+ * `approaching_limit` band is a warning, not a violation. Per-gene `exceeded` (files > max_files) is handled by
+ * constraints.ts so the two layers don't double-report; here we only escalate the global cap + the 2x overrun.
+ */
+export function checkBlastRadius(stat, constraints, caps = globalHardCaps()) {
+    const violations = [];
+    const sev = classifyBlastSeverity(stat, constraints?.max_files, caps);
+    if (sev.severity === 'hard_cap_breach' || sev.severity === 'critical_overrun') {
+        violations.push({ kind: 'blast_radius', detail: sev.message });
+    }
+    return violations;
+}

package/dist/exec/policy/constraints.d.ts

@@ -0,0 +1,26 @@
+export interface ChangeConstraints {
+    max_files?: number;
+    /** Per-gene line-churn cap (insertions+deletions). Layers UNDER the global hard cap. */
+    max_lines?: number;
+    forbidden_paths?: readonly string[];
+}
+export interface PolicyViolation {
+    kind: 'blast_radius' | 'forbidden_path' | 'protected_path' | 'destructive';
+    detail: string;
+}
+/**
+ * Does a changed path fall under a forbidden path? Matches on path SEGMENTS, never raw substrings, so
+ * "migrations" hits "migrations/001.sql" and "db/migrations/x.sql" but NOT "migrations_helper.ts":
+ *  - exact match: forbidden "src/x.ts" === changed "src/x.ts"
+ *  - directory prefix: forbidden "migrations/" / "db/migrations" contains "db/migrations/001.sql"
+ *  - bare segment (no slash, e.g. "node_modules", ".env"): matches any path containing that exact segment
+ */
+export declare function pathIsForbidden(changed: string, forbidden: string): boolean;
+/**
+ * Check the agent's actual changed files (and optional line churn) against the gene's constraints.
+ * Undefined/empty constraints = no policy (returns []). Returns every violation (one per offending file for
+ * forbidden paths) so the caller can surface a complete reason.
+ */
+export declare function checkChangeConstraints(changedFiles: readonly string[], constraints?: ChangeConstraints, lines?: number): PolicyViolation[];
+/** One-line human summary of a violation set (for an outcome reason / audit log). */
+export declare function summarizeViolations(violations: readonly PolicyViolation[]): string;

package/dist/exec/policy/constraints.js

@@ -0,0 +1,62 @@
+// Per-gene change-constraint enforcement (ported from v1 src/gep/policyCheck.js checkConstraints — the
+// forbidden_paths + max_files slice). renderExecPrompt only TELLS the agent "touch at most N file(s) / never
+// modify X" — that is advisory. A misbehaving, confused, or prompt-injected agent can ignore it. This module
+// ENFORCES the same limits against the ACTUAL git diff after the agent runs. These checks ONLY apply when a
+// gene with constraints is present; the always-on global guards (blast hard cap + protected paths +
+// destructive) live in their own modules and run regardless. Pure + deterministic.
+const norm = (p) => p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+/**
+ * Does a changed path fall under a forbidden path? Matches on path SEGMENTS, never raw substrings, so
+ * "migrations" hits "migrations/001.sql" and "db/migrations/x.sql" but NOT "migrations_helper.ts":
+ *  - exact match: forbidden "src/x.ts" === changed "src/x.ts"
+ *  - directory prefix: forbidden "migrations/" / "db/migrations" contains "db/migrations/001.sql"
+ *  - bare segment (no slash, e.g. "node_modules", ".env"): matches any path containing that exact segment
+ */
+export function pathIsForbidden(changed, forbidden) {
+    const c = norm(changed);
+    const f = norm(forbidden);
+    if (!f)
+        return false;
+    if (c === f)
+        return true;
+    if (c.startsWith(`${f}/`))
+        return true; // forbidden dir is a path prefix at a segment boundary
+    if (!f.includes('/'))
+        return c.split('/').includes(f); // bare segment anywhere in the path
+    return false;
+}
+/**
+ * Check the agent's actual changed files (and optional line churn) against the gene's constraints.
+ * Undefined/empty constraints = no policy (returns []). Returns every violation (one per offending file for
+ * forbidden paths) so the caller can surface a complete reason.
+ */
+export function checkChangeConstraints(changedFiles, constraints, lines) {
+    const violations = [];
+    if (!constraints)
+        return violations;
+    const files = changedFiles.map(norm).filter(Boolean);
+    if (constraints.max_files !== undefined && files.length > constraints.max_files) {
+        violations.push({
+            kind: 'blast_radius',
+            detail: `changed ${files.length} file(s) > max_files ${constraints.max_files}`,
+        });
+    }
+    if (constraints.max_lines !== undefined && lines !== undefined && lines > constraints.max_lines) {
+        violations.push({
+            kind: 'blast_radius',
+            detail: `changed ${lines} line(s) > max_lines ${constraints.max_lines}`,
+        });
+    }
+    if (constraints.forbidden_paths?.length) {
+        for (const file of files) {
+            const hit = constraints.forbidden_paths.find((fp) => pathIsForbidden(file, fp));
+            if (hit)
+                violations.push({ kind: 'forbidden_path', detail: `${file} matches forbidden path "${hit}"` });
+        }
+    }
+    return violations;
+}
+/** One-line human summary of a violation set (for an outcome reason / audit log). */
+export function summarizeViolations(violations) {
+    return `constraint violation: ${violations.map((v) => v.detail).join('; ')}`;
+}