@evomap/evolver-core 2.0.0-beta.0

package/dist/exec/autoExec.d.ts

@@ -0,0 +1,137 @@
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+import { type ProvenanceStore } from '../assetstore/provenance.js';
+import type { ReviewLedger } from '../assetstore/reviewLedger.js';
+import type { GeneCandidateInput } from '../algo/geneSelection.js';
+import type { CycleEngine, SolidifyPermitGate } from '../algo/cycleEngine.js';
+import { type AutonomousSafety } from './autonomousCycle.js';
+import type { GitRunner, ValidateHook } from './claudeBridge.js';
+import type { AgentRunner } from './runnerRegistry.js';
+import { type OpenPrLister } from './openPrRegistry.js';
+import type { ReuseOutcomeSummary, ReuseOutcomeEvent } from '../ops/reuseOutcomes.js';
+import type { PersonalityStore } from '../personality/store.js';
+export interface AutoExecTask {
+    id: string;
+    repo: string;
+    target: string;
+    expectedEffect: string;
+    /** Explicit opt-in public context safe to send to the public Hub question generator. */
+    publicQuestionContext?: string;
+    signals: readonly string[];
+    /** Optional learned strategy to seed as a local (trusted) gene for this task. */
+    strategy?: readonly string[];
+    /** Optional explicit gene id/asset id selected by GEP or the task source. */
+    forcedGeneId?: string;
+    /** Legacy/GEP aliases accepted at the autoexec boundary and normalized into forcedGeneId. */
+    preferredGeneId?: string;
+    selected_gene_id?: string;
+    selectedGeneId?: string;
+    /** Optional explicit strategy preset name for this task; wins over daemon default and meta-signal auto-detection. */
+    strategyName?: string;
+    validationCmds?: readonly string[];
+}
+export interface AutoExecVerdict {
+    taskId: string;
+    status: 'refused' | 'skipped' | 'solidified' | 'failed' | 'innovated';
+    reason?: string;
+    finalStage?: string;
+    outcome?: {
+        status: string;
+        score: number;
+    };
+    proofOfWork?: unknown;
+    usedAssetIds?: readonly string[];
+}
+/**
+ * Reuse-before-solve seam (#110): given the task's signals, resolve hub candidates worth competing in the
+ * selection pool. This is a pure FUNCTION SIGNATURE — core deliberately does NOT import the adapter's
+ * `reuseBeforeSolve` (that would breach the core-can't-import-adapter boundary). The real implementation
+ * (free hub search → pure score → paid fetch → cache) is injected at the composition layer that already owns
+ * the hub capability (the CLI/daemon), mirroring how the exec bridge's `agent` seam is injected. The seam is
+ * optional: when absent, no hub candidates flow and the cycle behaves exactly as today (and makes ZERO hub
+ * calls). It must never throw — reuse is an optimization, so a hub failure degrades to solving fresh.
+ */
+export interface HubReuseContext {
+    /** The cycle this reuse resolution feeds — carried so the composition layer can emit a reuse event whose
+     *  refs point at the SAME cycleId the cycle records (value-ledger audit anchor, #112). */
+    cycleId: string;
+}
+export type HubReuseSeam = (signals: readonly string[], ctx?: HubReuseContext) => Promise<readonly GeneCandidateInput[]>;
+export interface AutoExecDeps {
+    engine: CycleEngine;
+    store: AssetStoreProvider;
+    provenance?: ProvenanceStore;
+    /** Optional review-state gate: withhold an unreviewed (auto-distilled) gene's strategy from the agent prompt. */
+    review?: ReviewLedger;
+    /**
+     * Probation (#306, gated): when set, a quarantined auto-distilled gene is BOTH selectable and embeddable, so it
+     * is tried with its own strategy and its outcome becomes real evidence for auto-promote. Forwarded to selection
+     * (includeProbation) AND to makeSafeExecute (the resolver embeds the probation strategy). Omit (default) → today's
+     * behavior: quarantined drafts wait for human approval. Bad probation strategies are contained by the exec gates.
+     */
+    includeProbation?: boolean;
+    /**
+     * Optional reuse-before-solve seam (#110): when set, it is called before the cycle to pull hub candidates
+     * that compete in the SAME pool as local genes (trust-first — a trusted local gene wins on a geneId
+     * collision). Omit to disable (zero hub calls, exactly today's behavior). Injected by the composition layer
+     * that owns the hub capability so core stays hub-agnostic (the signature, not the adapter, lives here).
+     */
+    hubReuse?: HubReuseSeam;
+    /** Build a validation hook for a task (e.g. run its validationCmds in the worktree). Deployment-specific. */
+    validate?: (task: AutoExecTask) => ValidateHook;
+    /** Optional adapter/runtime permit gate. Core owns only the seam; adapters own the verification policy. */
+    solidifyPermit?: SolidifyPermitGate;
+    /**
+     * Optional open-PR dedup: when set, before spawning an agent the task's signals are compared against open PR
+     * titles/branches; a strong overlap yields a 'skipped' verdict so the daemon never re-implements work that is
+     * already in flight. Opt-in — omit to disable. Wrap with makeCachedPrLister for a polling daemon.
+     */
+    prLister?: OpenPrLister;
+    /** Min token-overlap for a PR to count as a duplicate (default 0.5). */
+    dedupThreshold?: number;
+    /**
+     * Cross-runtime reuse-outcome summary (#268 phase 1 on-switch): when set, it SOFTLY re-orders gene selection by
+     * how MCP-native agents fared reusing each gene (forwarded to runEvolutionCycle). Omit (the default) → no reuse
+     * re-order → exactly today's behavior. The composition layer computes it from reuse-outcome events behind a flag.
+     */
+    reuseOutcomes?: ReuseOutcomeSummary;
+    /** Observed `value.recall` events (#274 slice 3): folded into the same soft re-order as reuseOutcomes (lower
+     *  weight) so transcript-observed recall influences selection. Forwarded to runEvolutionCycle. Omit → none. */
+    recallEvents?: readonly ReuseOutcomeEvent[];
+    /** Optional daemon-level explicit strategy preset name, e.g. EVOLVE_STRATEGY. */
+    strategyName?: string;
+    /** Optional evolvable personality store shared with CycleEngine and the exec prompt. */
+    personality?: PersonalityStore;
+    /** Test/custom seam: inject a runner instead of spawning a real agent. */
+    agent?: AgentRunner;
+    /** Test/custom seam: inject git instead of spawning git. */
+    git?: GitRunner;
+}
+export interface ForcedGeneFields {
+    forcedGeneId?: unknown;
+    preferredGeneId?: unknown;
+    selected_gene_id?: unknown;
+    selectedGeneId?: unknown;
+}
+export declare function canonicalForcedGeneId(task: ForcedGeneFields): string | undefined;
+export declare function normalizeAutoExecTask(task: AutoExecTask): AutoExecTask;
+/**
+ * Run one autonomous task end to end with every safety control composed (makeSafeExecute). Deny-by-default:
+ * if task.repo is not within safety.allowedRoots, returns a 'refused' verdict and runs nothing. Otherwise seeds
+ * the task's strategy as a local (trusted) gene, then drives a real evolution cycle and maps the result.
+ */
+export declare function runAutoExecTask(deps: AutoExecDeps, rawTask: AutoExecTask, safety: AutonomousSafety): Promise<AutoExecVerdict>;
+/**
+ * Single-flight re-entrancy guard for a poll-driven resident loop. A resident autoexec daemon polls on an
+ * interval; if a pass outlives the poll period (a hung/slow agent), the next tick must NOT start a second
+ * overlapping pass — that piled up runaway nested agents in an early scratch run. Wrap the pass: while one is
+ * in flight, subsequent calls return { skipped: true } immediately instead of starting another.
+ */
+export declare function singleFlight<T>(fn: () => Promise<T>): () => Promise<T | {
+    skipped: true;
+}>;
+/**
+ * Process tasks strictly SEQUENTIALLY (one at a time, never overlapping) through `runOne`, collecting verdicts.
+ * Sequential by construction — an autonomous agent edits a worktree and runs tools; concurrent passes would
+ * contend. Combine with {@link singleFlight} so a poll tick that fires mid-drain is skipped, not stacked.
+ */
+export declare function drainTasks<T, V>(tasks: readonly T[], runOne: (task: T) => Promise<V>): Promise<V[]>;

package/dist/exec/autoExec.js

@@ -0,0 +1,221 @@
+// Autonomous-exec task runner — the productized per-task kernel a resident daemon polls (the deployment form
+// of the scratch autoexec daemon). One task → one fully-hardened evolution cycle, with a deny-by-default
+// allowlist pre-check that yields a clean "refused" verdict WITHOUT running anything when the repo is not
+// allowlisted. Secure by construction: the execute is built by makeSafeExecute (all six controls); callers
+// cannot bypass the safety composition.
+import { resolve as resolvePath, sep } from 'node:path';
+import { normalizeForPut } from '../assetstore/provider.js';
+import { ingestUntrusted } from '../assetstore/provenance.js';
+import { mergePendingSignalsForStore } from '../assetstore/pendingSignals.js';
+import { intakeGene } from '../algo/geneIntake.js';
+import { runEvolutionCycle } from '../algo/orchestrator.js';
+import { makeSafeExecute, makeTrustedGeneResolver } from './autonomousCycle.js';
+import { findSignalHints } from './openPrRegistry.js';
+/** Same path-containment as the bridge guard — used here to refuse before running anything (clean verdict). */
+function withinAllowlist(repo, roots) {
+    const c = resolvePath(repo);
+    return roots.some((root) => { const r = resolvePath(root); return c === r || c.startsWith(r.endsWith(sep) ? r : r + sep); });
+}
+function cleanForcedGeneId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export function canonicalForcedGeneId(task) {
+    return cleanForcedGeneId(task.forcedGeneId)
+        ?? cleanForcedGeneId(task.preferredGeneId)
+        ?? cleanForcedGeneId(task.selected_gene_id)
+        ?? cleanForcedGeneId(task.selectedGeneId);
+}
+export function normalizeAutoExecTask(task) {
+    const forcedGeneId = canonicalForcedGeneId(task);
+    const normalized = { ...task };
+    if (forcedGeneId === undefined)
+        delete normalized.forcedGeneId;
+    else
+        normalized.forcedGeneId = forcedGeneId;
+    return normalized;
+}
+async function landHubAssetIfPresent(deps, candidate) {
+    if (!candidate.hubAsset)
+        return candidate;
+    if (!deps.provenance)
+        return null;
+    let normalized;
+    try {
+        normalized = normalizeForPut(candidate.hubAsset).record;
+    }
+    catch {
+        return null;
+    }
+    const existing = await deps.store.get(normalized.asset_id);
+    if (!existing) {
+        try {
+            await ingestUntrusted(deps.store, deps.provenance, normalized, 'hub');
+        }
+        catch {
+            return null;
+        }
+    }
+    return candidate.assetId === normalized.asset_id ? candidate : { ...candidate, assetId: normalized.asset_id };
+}
+async function hasTrustedResolvedStrategy(deps, candidate) {
+    if (!deps.provenance)
+        return false;
+    const resolveGene = makeTrustedGeneResolver(deps.store, deps.provenance, deps.review);
+    const ids = candidate.hubAsset
+        ? [candidate.assetId].filter((id) => typeof id === 'string' && id.length > 0)
+        : [candidate.geneId, candidate.assetId].filter((id) => typeof id === 'string' && id.length > 0);
+    const uniqueIds = [...new Set(ids)];
+    for (const id of uniqueIds) {
+        const info = await resolveGene(id);
+        if (info?.trusted === true && (info.strategy?.length ?? 0) > 0)
+            return true;
+    }
+    return false;
+}
+async function executableHubCandidates(deps, candidates) {
+    const out = [];
+    for (const candidate of candidates) {
+        const landed = await landHubAssetIfPresent(deps, candidate);
+        if (!landed)
+            continue;
+        if (await hasTrustedResolvedStrategy(deps, landed))
+            out.push(landed);
+    }
+    return out;
+}
+/**
+ * Run one autonomous task end to end with every safety control composed (makeSafeExecute). Deny-by-default:
+ * if task.repo is not within safety.allowedRoots, returns a 'refused' verdict and runs nothing. Otherwise seeds
+ * the task's strategy as a local (trusted) gene, then drives a real evolution cycle and maps the result.
+ */
+export async function runAutoExecTask(deps, rawTask, safety) {
+    const task = normalizeAutoExecTask(rawTask);
+    if (!withinAllowlist(task.repo, safety.allowedRoots)) {
+        return { taskId: task.id, status: 'refused', reason: `repo not in allowlist: ${task.repo}` };
+    }
+    // Open-PR dedup (opt-in): if an open PR already covers this task's signals, skip before spawning an agent
+    // so the daemon doesn't re-implement in-flight work. Graceful — a lister that returns [] is a no-op.
+    if (deps.prLister) {
+        const hints = findSignalHints(task.signals, await deps.prLister(task.repo), { threshold: deps.dedupThreshold ?? 0.5 });
+        const top = hints[0];
+        if (top) {
+            return { taskId: task.id, status: 'skipped', reason: `open-pr-dedup: signals overlap PR #${top.number} (${top.headRefName}) @ ${top.tokenOverlap.toFixed(2)}` };
+        }
+    }
+    let cycleSignals = [...task.signals];
+    try {
+        const explicit = mergePendingSignalsForStore(deps.store, task.signals, { repoRoot: task.repo });
+        cycleSignals = explicit.signals;
+        if (explicit.injected > 0) {
+            console.log(`[ExplicitSignals] Injected ${explicit.injected} user-declared signal(s) from pending_signals.json.`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[ExplicitSignals] Failed to consume pending signals (non-fatal): ${message}`);
+    }
+    let seededStrategyGeneId;
+    if (task.strategy && task.strategy.length > 0) {
+        const gi = intakeGene({
+            category: 'repair', signals_match: cycleSignals, strategy: [...task.strategy],
+            summary: task.expectedEffect.slice(0, 80), ...(task.validationCmds ? { validation: [...task.validationCmds] } : {}),
+        });
+        if (gi.ok && gi.gene) {
+            await deps.store.put(gi.gene);
+            seededStrategyGeneId = cleanForcedGeneId(gi.gene.id);
+        }
+    }
+    // Reuse-before-solve (#110): if the seam is wired, resolve hub candidates BEFORE the cycle so they compete
+    // in the same selection pool as local genes. Reuse is an optimization, never a hard dependency — a seam
+    // that throws degrades to solving fresh (no hub candidates) rather than failing the task.
+    let hubCandidates = [];
+    const cycleId = `autoexec-${task.id}`;
+    if (deps.hubReuse) {
+        try {
+            hubCandidates = await executableHubCandidates(deps, await deps.hubReuse(cycleSignals, { cycleId }));
+        }
+        catch {
+            hubCandidates = [];
+        }
+    }
+    const execute = makeSafeExecute(task.repo, deps.store, safety, {
+        ...(deps.provenance ? { provenance: deps.provenance } : {}),
+        ...(deps.review ? { review: deps.review } : {}),
+        ...(deps.includeProbation ? { includeProbation: true } : {}),
+        ...(task.validationCmds ? { validationCmds: task.validationCmds } : {}),
+        ...(deps.validate ? { validate: deps.validate(task) } : {}),
+        ...(deps.personality ? { personality: deps.personality } : {}),
+        ...(deps.agent ? { agent: deps.agent } : {}),
+        ...(deps.git ? { git: deps.git } : {}),
+    });
+    const strategyName = task.strategyName ?? deps.strategyName;
+    // Intentional semantics (see #308 review M1): a task carrying `strategy` — even without an
+    // explicit forcedGeneId — force-selects the gene seeded from that strategy above, rather than
+    // letting it compete in normal ranking. Supplying a strategy is treated as "use this strategy".
+    // The forced pick still passes every hard gate downstream (candidate pool, ban, epigenetic
+    // suppression), so this never bypasses trust/review/inert filtering.
+    const cycleForcedGeneId = task.forcedGeneId ?? seededStrategyGeneId;
+    const res = await runEvolutionCycle(deps.engine, deps.store, {
+        ...(deps.provenance ? { provenance: deps.provenance } : {}),
+        ...(deps.review ? { review: deps.review } : {}),
+        ...(deps.includeProbation ? { includeProbation: true } : {}),
+        ...(hubCandidates.length > 0 ? { hubCandidates } : {}),
+        ...(deps.solidifyPermit ? { solidifyPermit: deps.solidifyPermit } : {}),
+        ...(deps.reuseOutcomes ? { reuseOutcomes: deps.reuseOutcomes } : {}),
+        ...(deps.recallEvents ? { recallEvents: deps.recallEvents } : {}),
+        ...(strategyName !== undefined ? { strategyName } : {}),
+        ...(cycleForcedGeneId !== undefined ? { forcedGeneId: cycleForcedGeneId } : {}),
+        cycleId,
+        problem: {
+            id: task.id, signature: `sig:${task.id}`, signatureV: 1,
+            firstSeenAt: new Date(0).toISOString(), lastSeenAt: new Date(0).toISOString(),
+            occurrences: 1, linkedSignals: cycleSignals, resolvedBy: null, status: 'open',
+            value: { severity: 0.7, reach: 1, strategicFit: 0.9, novelty: 0, costEst: 0.2 },
+            consecutiveFailures: 0, cooldownUntil: null, extensions: {},
+        },
+        signals: cycleSignals, category: 'repair', target: task.target, expectedEffect: task.expectedEffect,
+        summary: `autonomous: ${task.id}`, confidence: 0.85, execute, consumePendingSignals: false,
+    });
+    const status = res.finalStage === 'solidified' ? 'solidified' : res.finalStage === 'failed' ? 'failed' : 'innovated';
+    const cap = res.capsule;
+    const hubAssetIds = new Set(hubCandidates.map((c) => c.assetId).filter((id) => typeof id === 'string' && id.length > 0));
+    const selectedAssetId = res.decision?.selectedAssetId;
+    const usedAssetIds = selectedAssetId && hubAssetIds.has(selectedAssetId) ? [selectedAssetId] : [];
+    return {
+        taskId: task.id, status, finalStage: res.finalStage,
+        ...(res.reasons.length > 0 && status !== 'solidified' ? { reason: res.reasons.join('; ') } : {}),
+        ...(cap?.outcome ? { outcome: cap.outcome } : {}),
+        ...(cap?.proof_of_work ? { proofOfWork: cap.proof_of_work } : {}),
+        ...(usedAssetIds.length > 0 ? { usedAssetIds } : {}),
+    };
+}
+/**
+ * Single-flight re-entrancy guard for a poll-driven resident loop. A resident autoexec daemon polls on an
+ * interval; if a pass outlives the poll period (a hung/slow agent), the next tick must NOT start a second
+ * overlapping pass — that piled up runaway nested agents in an early scratch run. Wrap the pass: while one is
+ * in flight, subsequent calls return { skipped: true } immediately instead of starting another.
+ */
+export function singleFlight(fn) {
+    let inFlight = null;
+    return () => {
+        if (inFlight)
+            return Promise.resolve({ skipped: true });
+        const p = fn().finally(() => { inFlight = null; });
+        inFlight = p;
+        return p;
+    };
+}
+/**
+ * Process tasks strictly SEQUENTIALLY (one at a time, never overlapping) through `runOne`, collecting verdicts.
+ * Sequential by construction — an autonomous agent edits a worktree and runs tools; concurrent passes would
+ * contend. Combine with {@link singleFlight} so a poll tick that fires mid-drain is skipped, not stacked.
+ */
+export async function drainTasks(tasks, runOne) {
+    const out = [];
+    for (const t of tasks)
+        out.push(await runOne(t));
+    return out;
+}

package/dist/exec/autonomousCycle.d.ts

@@ -0,0 +1,48 @@
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+import type { ProvenanceStore } from '../assetstore/provenance.js';
+import type { ReviewLedger } from '../assetstore/reviewLedger.js';
+import type { Mutation } from '../wire/index.js';
+import type { GeneDecision } from '../algo/geneSelection.js';
+import type { ExecutionResult } from '../algo/cycleEngine.js';
+import { type GeneResolver, type ValidateHook, type AgentRunnerOptions, type RunnerName, type AgentRunner, type GitRunner } from './claudeBridge.js';
+import type { PersonalityStore } from '../personality/store.js';
+/**
+ * Resolve a gene's strategy from the store and whether it is safe to EMBED into an autonomous agent's prompt —
+ * the exec-side link from #30 (provenance ledger) and the review-state gate to #45 (requireTrustedGene gate). A
+ * gene is embeddable only when BOTH axes pass: trusted ORIGIN (no provenance record → local/trusted; a hub one
+ * is untrusted until promoted) AND review-APPROVED content (no review record → eligible; an auto-distilled draft
+ * is quarantined until a human approves). Both default-open, so cycle-self-produced/local genes are unaffected;
+ * only hub-ingested (untrusted) and auto-distilled (unreviewed) drafts are withheld. Looks up by id or asset_id.
+ */
+export declare function makeTrustedGeneResolver(store: AssetStoreProvider, provenance?: ProvenanceStore, review?: ReviewLedger, includeProbation?: boolean): GeneResolver;
+export interface AutonomousSafety {
+    /** Deny-by-default repo allowlist (#41). Required — an empty array refuses everything. */
+    allowedRoots: readonly string[];
+    /** Which built-in runner (#66). Default 'claude'. The same safety controls wrap whichever runner. cursor is a scaffold (unverified). */
+    runner?: RunnerName;
+    /** Agent runner options (#38/#40). Default: bounded skip-permissions (Read/Edit/Write). */
+    agentOptions?: AgentRunnerOptions;
+    /** Strip evolver/hub secrets from the agent env (#42). Default true. */
+    scrubEnv?: boolean;
+    /** Run in a throwaway git worktree (#43). Default 'worktree'. */
+    isolation?: 'worktree' | 'none';
+    /** Only embed trusted gene strategies (#45). Default true. */
+    requireTrustedGene?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Build the fully-hardened `execute` for an autonomous run against `repo`. Composes every exec-bridge control
+ * with secure defaults so they can't be forgotten piecemeal: deny-by-default allowedRoots (#41) + worktree
+ * isolation (#43) + env scrub (#42) + bounded skip-permissions agent (#38/#40) + trusted-gene gate fed by
+ * provenance (#45/#30). Pass the result as runEvolutionCycle's `execute`.
+ */
+export declare function makeSafeExecute(repo: string, store: AssetStoreProvider, safety: AutonomousSafety, opts?: {
+    provenance?: ProvenanceStore;
+    review?: ReviewLedger;
+    validate?: ValidateHook;
+    validationCmds?: readonly string[];
+    includeProbation?: boolean;
+    personality?: PersonalityStore;
+    agent?: AgentRunner;
+    git?: GitRunner;
+}): (mutation: Mutation, decision: GeneDecision) => Promise<ExecutionResult>;

package/dist/exec/autonomousCycle.js

@@ -0,0 +1,78 @@
+import { makeClaudeExecBridge } from './claudeBridge.js';
+const asStrings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+/**
+ * Resolve a gene's strategy from the store and whether it is safe to EMBED into an autonomous agent's prompt —
+ * the exec-side link from #30 (provenance ledger) and the review-state gate to #45 (requireTrustedGene gate). A
+ * gene is embeddable only when BOTH axes pass: trusted ORIGIN (no provenance record → local/trusted; a hub one
+ * is untrusted until promoted) AND review-APPROVED content (no review record → eligible; an auto-distilled draft
+ * is quarantined until a human approves). Both default-open, so cycle-self-produced/local genes are unaffected;
+ * only hub-ingested (untrusted) and auto-distilled (unreviewed) drafts are withheld. Looks up by id or asset_id.
+ */
+export function makeTrustedGeneResolver(store, provenance, review, includeProbation = false) {
+    return async (geneId) => {
+        const genes = await store.list('Gene', 1000);
+        const g = genes.find((x) => String(x['id']) === geneId || String(x.asset_id) === geneId);
+        if (!g)
+            return null;
+        const summary = g['summary'];
+        const trustedOrigin = provenance ? provenance.isTrusted(String(g.asset_id)) : true;
+        const reviewApproved = review ? review.isApproved(String(g.asset_id)) : true;
+        // Probation (#306): when enabled, a QUARANTINED (auto-distilled, not yet approved — but not rejected) draft IS
+        // embeddable, so its strategy actually drives the trial. That is what makes the trial's outcome real evidence
+        // for auto-promote (without embedding, the gene would be selected but run as innovate — hollow evidence). The
+        // strategy is unreviewed, so its containment rests on the proven exec gates: sanitizeInjection neutralizes
+        // injected directives in the prompt, and the always-on hard gates + worktree isolation contain the agent's
+        // ACTIONS regardless of the prompt (#309). A REJECTED draft and an untrusted-origin (hub) gene stay withheld.
+        const probationOk = includeProbation && review?.get(String(g.asset_id))?.state === 'quarantined';
+        const info = {
+            strategy: asStrings(g['strategy']),
+            preconditions: asStrings(g['preconditions']),
+            ...(typeof summary === 'string' ? { summary } : {}),
+            trusted: trustedOrigin && (reviewApproved || probationOk), // trusted ORIGIN + (approved OR on probation)
+        };
+        return info;
+    };
+}
+// Claude's safe default: bypass the permission prompts but BOUND the agent to file edits (#38/#40).
+const CLAUDE_DEFAULT_AGENT_OPTIONS = { skipPermissions: true, allowedTools: ['Read', 'Edit', 'Write'] };
+// Codex's safe default is SANDBOXED (no skip): the autonomous-bypass flag is gated until verified (#66), so
+// skipPermissions would throw at construction. `codex exec` still runs non-interactively under its own sandbox.
+const CODEX_DEFAULT_AGENT_OPTIONS = {};
+// Cursor's safe default keeps skip OFF (#66 SCAFFOLD). The runner is flag-confirmed via `cursor-agent --help`
+// but not yet run-verified end to end (needs an authed cursor-agent). The `-p --force --trust` bypass would
+// auto-approve shell+write, but Cursor has no verified per-run allowlist/sandbox mapping yet, so skipPermissions
+// is refused outright. Use default cursor with worktree isolation until the CLI is run-verified.
+const CURSOR_DEFAULT_AGENT_OPTIONS = {};
+/** Per-runner safe default agent options — claude bypasses-with-bounds; codex + cursor stay non-bypassing (codex sandboxed; cursor skip refused, #66). */
+function defaultAgentOptions(runner) {
+    if (runner === 'codex')
+        return CODEX_DEFAULT_AGENT_OPTIONS;
+    if (runner === 'cursor')
+        return CURSOR_DEFAULT_AGENT_OPTIONS;
+    return CLAUDE_DEFAULT_AGENT_OPTIONS;
+}
+/**
+ * Build the fully-hardened `execute` for an autonomous run against `repo`. Composes every exec-bridge control
+ * with secure defaults so they can't be forgotten piecemeal: deny-by-default allowedRoots (#41) + worktree
+ * isolation (#43) + env scrub (#42) + bounded skip-permissions agent (#38/#40) + trusted-gene gate fed by
+ * provenance (#45/#30). Pass the result as runEvolutionCycle's `execute`.
+ */
+export function makeSafeExecute(repo, store, safety, opts = {}) {
+    return makeClaudeExecBridge({
+        cwd: repo,
+        enabled: true,
+        ...(opts.agent ? { agent: opts.agent } : {}),
+        ...(opts.git ? { git: opts.git } : {}),
+        allowedRoots: safety.allowedRoots,
+        ...(safety.runner ? { runner: safety.runner } : {}),
+        ...(safety.isolation === 'none' ? {} : { isolation: 'worktree' }),
+        scrubEnv: safety.scrubEnv ?? true,
+        requireTrustedGene: safety.requireTrustedGene ?? true,
+        agentOptions: safety.agentOptions ?? defaultAgentOptions(safety.runner),
+        ...(safety.timeoutMs !== undefined ? { timeoutMs: safety.timeoutMs } : {}),
+        resolveGene: makeTrustedGeneResolver(store, opts.provenance, opts.review, opts.includeProbation ?? false),
+        ...(opts.validate ? { validate: opts.validate } : {}),
+        ...(opts.validationCmds ? { validationCmds: opts.validationCmds } : {}),
+        ...(opts.personality ? { personality: opts.personality } : {}),
+    });
+}

package/dist/exec/claudeBridge.d.ts

@@ -0,0 +1,112 @@
+import type { Mutation } from '../wire/index.js';
+import type { GeneDecision } from '../algo/geneSelection.js';
+import type { ExecutionResult } from '../algo/cycleEngine.js';
+import { type GeneStrategyInfo } from './prompt.js';
+import type { PersonalityStore } from '../personality/store.js';
+import { type AgentRunner, type AgentRunnerOptions, type RunnerName } from './runnerRegistry.js';
+export { resolveSpawnCommand, spawnCapture, UnboundedSkipPermissionsError, UnsupportedCursorSkipPermissionsError, claudeRunnerArgs, makeClaudeHeadlessRunner, claudeHeadlessRunner, codexRunnerArgs, makeCodexHeadlessRunner, cursorRunnerArgs, makeCursorHeadlessRunner, getRunnerSpec, } from './runnerRegistry.js';
+export type { AgentRunContext, AgentRunResult, AgentRunner, RunnerName, AgentRunnerOptions, ClaudeRunnerOptions, CodexRunnerOptions, AgentRunnerSpec, } from './runnerRegistry.js';
+/** Run a git subcommand in cwd and return its stdout. */
+export type GitRunner = (args: readonly string[], cwd: string) => Promise<string>;
+/** Resolve the selected gene's learned strategy (for prompt enrichment). */
+export type GeneResolver = (geneId: string) => Promise<GeneStrategyInfo | null> | GeneStrategyInfo | null;
+/** Decide success from the post-run working tree (e.g. run the gene's validation plan). */
+export type ValidateHook = (mutation: Mutation, decision: GeneDecision, cwd: string) => Promise<{
+    passed: boolean;
+    score?: number;
+}> | {
+    passed: boolean;
+    score?: number;
+};
+export interface ExecBridgeOptions {
+    /** Working directory the agent edits and git is measured in. */
+    cwd: string;
+    /** Default: headless `claude` runner. Inject a fake in tests. */
+    agent?: AgentRunner;
+    /** Which built-in runner to use when `agent` is not injected (#66). Default 'claude' (byte-identical). cursor is a scaffold (unverified runner). */
+    runner?: RunnerName;
+    /** When `agent` is not injected, options for the built-in headless runner (permission bypass / allowed tools / model). */
+    agentOptions?: AgentRunnerOptions;
+    /** Default: spawns `git`. Inject a fake in tests. */
+    git?: GitRunner;
+    /** Default: EVOLVE_EXEC_BRIDGE === '1'. Set true to force-enable (e.g. integration tests). */
+    enabled?: boolean;
+    /**
+     * Deny-by-default repo guardrail for autonomous use: when set, the agent may only run in a `cwd` that is
+     * within one of these roots. An empty array denies everything (the safe default for a resident loop until
+     * repos are explicitly allowlisted). When undefined, no path restriction (caller's responsibility — e.g.
+     * tests with fake agents). Autonomous deployments MUST set this.
+     */
+    allowedRoots?: readonly string[];
+    /** Strip evolver/hub/cloud secrets from the agent's environment before spawning (finding #39.2). Default true
+     *  (secure by default); the agent keeps ONLY its own runner's auth (claude: ANTHROPIC_/CLAUDE_, codex: OPENAI_/
+     *  CODEX_ — #66). Set false only to inherit the full env. */
+    scrubEnv?: boolean;
+    /**
+     * Run the agent in a throwaway git worktree of `cwd` instead of the repo's real working tree (finding #39.4):
+     * the agent's edits land in an isolated checkout, never touching the user's working tree. The diff is measured
+     * there, captured as a patch (proof.gitDiff.patchRef), and the worktree is removed. `cwd` must be a git repo.
+     */
+    isolation?: 'worktree';
+    /**
+     * Only embed a selected gene's strategy into the agent prompt when it is trusted (gene.trusted === true)
+     * (finding #39.3): a poisoned/hub-ingested gene's strategy is the injection blast end for an autonomous agent.
+     * When true, an untrusted gene is dropped (the run proceeds as innovate, without its strategy). Recommended
+     * for unattended runs. Default false (back-compat; local genes are trusted by their author).
+     */
+    requireTrustedGene?: boolean;
+    /** Per-run agent timeout. Default 600_000ms (10 min). */
+    timeoutMs?: number;
+    /** Optional: enrich the prompt with the selected gene's strategy. */
+    resolveGene?: GeneResolver;
+    /** Optional: validation commands surfaced in the prompt's done-criteria. */
+    validationCmds?: readonly string[];
+    /** Optional: authoritative success decision after the agent runs. Falls back to "agent ok + produced a diff". */
+    validate?: ValidateHook;
+    /**
+     * Optional evolvable personality (use-case ①): when set, the agent prompt gets a behavioral-style block
+     * rendered from the store's CURRENT persisted state. CycleEngine's applySelectForRun has already run and
+     * saved the per-run state to this same store before execute() is invoked, so reading currentState() here
+     * injects exactly the personality this cycle selected. Pass the SAME PersonalityStore given to CycleEngine.
+     * Absent ⇒ no style block (byte-identical to today). Reading is best-effort — a load failure falls back to
+     * the store's default state (store.load never throws), it never fails the run.
+     */
+    personality?: PersonalityStore;
+}
+export declare class ExecBridgeDisabledError extends Error {
+    constructor();
+}
+/** Thrown when the agent's working directory is outside the configured allowedRoots (deny-by-default guardrail). */
+export declare class ExecBridgeForbiddenError extends Error {
+    constructor(cwd: string);
+}
+/**
+ * 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 declare class UnsandboxedFullAccessRequiresIsolationError extends Error {
+    constructor();
+}
+/**
+ * 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 declare function scrubAgentEnv(env: NodeJS.ProcessEnv, opts?: {
+    allowKeys?: readonly string[];
+    allowPrefixes?: readonly string[];
+}): NodeJS.ProcessEnv;
+/** Default git runner: spawn `git <args>` in cwd, return stdout (empty string on error). Env scrubbed — git never needs evolver/hub secrets. */
+export declare const defaultGitRunner: GitRunner;
+/**
+ * Build the `execute` function CycleEngine/runEvolutionCycle consume. Default-off: throws
+ * ExecBridgeDisabledError on first call unless enabled.
+ */
+export declare function makeClaudeExecBridge(opts: ExecBridgeOptions): (mutation: Mutation, decision: GeneDecision) => Promise<ExecutionResult>;