@evomap/evolver-core 2.0.0-beta.0

package/dist/exec/runnerRegistry.d.ts

@@ -0,0 +1,123 @@
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+export interface AgentRunContext {
+    cwd: string;
+    timeoutMs?: number;
+    /** Environment for the spawned agent. The bridge passes a scrubbed env here (see scrubAgentEnv); undefined → inherit. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface AgentRunResult {
+    ok: boolean;
+    output: string;
+    error?: string;
+}
+/** Run a coding agent against a working directory with the given instruction. */
+export type AgentRunner = (prompt: string, ctx: AgentRunContext) => Promise<AgentRunResult>;
+/** Thrown when permission bypass is requested without bounding the agent's tools (would be an unbounded autonomous agent). */
+export declare class UnboundedSkipPermissionsError extends Error {
+    constructor();
+}
+/** Thrown when Cursor skipPermissions is requested before the runner can enforce per-run permissions. */
+export declare class UnsupportedCursorSkipPermissionsError extends Error {
+    constructor();
+}
+/** Thrown when Cursor's built-in runner is requested on Windows before its launcher path is run-verified. */
+export declare class UnsupportedCursorWindowsRunnerError extends Error {
+    constructor();
+}
+export declare function assertCursorRunnerPlatformSupported(platform?: NodeJS.Platform): void;
+/**
+ * Make a bare command name spawnable shell-free on Windows. `spawn(shell:false)` cannot execute an npm CLI
+ * shim (a `.cmd`/`.bat`), and routing through a shell would expose the prompt arg to cmd.exe quoting
+ * (injection). npm shims are node wrappers, so we resolve the bare name on PATH and, when it's a node shim,
+ * run `node <entry.js>` directly (shell-free, args passed safely). A native `.exe` (claude) resolves to itself.
+ * No-op on POSIX and for any command that is already a path or has an extension. Surfaced by codex on Windows
+ * (codex is `codex.cmd`, while claude is `claude.exe`), #66.
+ */
+export declare function resolveSpawnCommand(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Promise wrapper over spawn (shell:false). Optionally writes `input` to stdin; resolves with stdout/exit.
+ * On timeout the WHOLE process group is killed, not just the direct child (finding #39.5): an agent spawns
+ * tool subprocesses (grandchildren) that would otherwise orphan and leak. On POSIX we spawn detached (the
+ * child becomes its own group leader) and SIGKILL the group via the negative pid; Windows falls back to a
+ * direct kill (different process-group semantics).
+ */
+export declare function spawnCapture(cmd: string, args: readonly string[], opts: {
+    cwd: string;
+    timeoutMs: number;
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+/** Options for a built-in headless runner (claude / codex share the shape and the skip⇒bounded invariant). */
+export interface AgentRunnerOptions {
+    /** Bypass permission prompts so the agent can edit autonomously (required for unattended use). Default off.
+     *  MUST be paired with a non-empty allowedTools (enforced) — bypassing prompts without bounding tools
+     *  would be an unbounded autonomous agent. */
+    skipPermissions?: boolean;
+    /** Constrain the agent to these tools (e.g. ['Read', 'Edit', 'Write']) — the safety counterpart to
+     *  skipPermissions: bypass prompts but bound what the agent can do. */
+    allowedTools?: readonly string[];
+    /** Pin a model (e.g. 'claude-sonnet-4-6'). */
+    model?: string;
+}
+/** @deprecated use AgentRunnerOptions — kept for back-compat (#91 item 6 rename). */
+export type ClaudeRunnerOptions = AgentRunnerOptions;
+/** @deprecated use AgentRunnerOptions — codex shares the exact option shape. */
+export type CodexRunnerOptions = AgentRunnerOptions;
+/**
+ * Build the `claude -p` argv for the given options (pure — testable without spawning).
+ * Safety invariant: skipPermissions (bypassing prompts) is only allowed together with a non-empty
+ * allowedTools — otherwise it would be an unattended agent with full tools and no gate; refuse loudly.
+ */
+export declare function claudeRunnerArgs(opts?: AgentRunnerOptions): string[];
+/**
+ * Build a headless `claude -p` agent runner. Prompt fed via stdin (no shell, no argv length limit). For
+ * unattended evolution set { skipPermissions: true, allowedTools: ['Read','Edit','Write'] } — bypass the
+ * permission prompts but bound the agent to file edits. Validated end to end against a real agent.
+ */
+export declare function makeClaudeHeadlessRunner(opts?: AgentRunnerOptions): AgentRunner;
+/** Default agent runner: conservative `claude -p --output-format text` (no permission bypass; opt in via makeClaudeHeadlessRunner). */
+export declare const claudeHeadlessRunner: AgentRunner;
+/**
+ * Build the `codex exec` argv (pure). Verified live against codex-cli 0.137.0:
+ *  - sandboxed default → `exec --sandbox workspace-write`: edits the workspace non-interactively (read-only,
+ *    the codex default, cannot write). The wrapper's worktree + allowedRoots are the outer containment.
+ *  - skipPermissions (bounded) → `exec --dangerously-bypass-approvals-and-sandbox`: full bypass, intended for
+ *    an already-externally-sandboxed run (our throwaway worktree). The `skip⇒bounded` invariant is the explicit
+ *    acknowledgement guard, same shape as claude.
+ */
+export declare function codexRunnerArgs(opts?: AgentRunnerOptions): string[];
+/** Headless `codex exec` runner. Working root pinned with `--cd`; prompt is the trailing positional arg (shell:false). */
+export declare function makeCodexHeadlessRunner(opts?: AgentRunnerOptions): AgentRunner;
+/**
+ * Build the `cursor-agent` argv (pure). Ground-truth from `cursor-agent --help` (#66): base `-p --output-format
+ * text` (headless, write+shell access). `--model` is a real flag. skipPermissions is rejected until Cursor has a
+ * verified per-run allowlist/sandbox mapping; allowedTools is not emitted because cursor has no per-tool allowlist.
+ */
+export declare function cursorRunnerArgs(opts?: AgentRunnerOptions): string[];
+/**
+ * Headless `cursor-agent` runner. Prompt passed as the trailing positional arg (shell:false, no injection risk;
+ * docs show `cursor-agent -p "<prompt>"`). cwd is set via spawn. SCAFFOLD — run-verify against a real
+ * cursor-agent before autonomous use (see the block comment above for what is doc-confirmed vs unverified).
+ */
+export declare function makeCursorHeadlessRunner(opts?: AgentRunnerOptions, platform?: NodeJS.Platform): AgentRunner;
+/** A built-in coding-agent harness (#66). cursor is a SCAFFOLD — its runner is unverified (see cursorRunnerArgs). */
+export type RunnerName = 'claude' | 'codex' | 'cursor';
+/** A harness runner: how to launch it + which env auth prefixes it (and ONLY it) may keep (#66). */
+export interface AgentRunnerSpec {
+    name: RunnerName;
+    makeRunner: (opts?: AgentRunnerOptions) => AgentRunner;
+    /** Per-runner auth env — only this runner's keys reach it (claude never gets OPENAI_, codex never gets ANTHROPIC_). */
+    envAllow: {
+        prefixes: readonly string[];
+        keys?: readonly string[];
+    };
+}
+/** Resolve a runner spec by name (default 'claude' — byte-identical to the pre-registry behavior). */
+export declare function getRunnerSpec(name?: RunnerName): AgentRunnerSpec;

package/dist/exec/runnerRegistry.js

@@ -0,0 +1,237 @@
+// The runner layer of the exec bridge (#66, split out per #91 item 6): how to spawn a coding-agent CLI
+// shell-free, the per-runner argv builders + headless factories, and the runner registry that maps a runner
+// name → { factory, env-auth allowlist }. claudeBridge.ts (the bridge orchestration) imports from here; this
+// module never imports back from claudeBridge, so the dependency is one-directional (no cycle). Pure/seam-able:
+// nothing here spawns a real agent in tests except through spawnCapture, which the bridge injects fakes around.
+import { spawn } from 'node:child_process';
+import { join as joinPath, delimiter as pathDelimiter } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+export const DEFAULT_TIMEOUT_MS = 600_000;
+/** Thrown when permission bypass is requested without bounding the agent's tools (would be an unbounded autonomous agent). */
+export class UnboundedSkipPermissionsError extends Error {
+    constructor() {
+        super("skipPermissions requires a non-empty allowedTools — refusing to bypass permission prompts without bounding the agent (e.g. allowedTools: ['Read','Edit','Write'])");
+        this.name = 'UnboundedSkipPermissionsError';
+    }
+}
+/** Thrown when Cursor skipPermissions is requested before the runner can enforce per-run permissions. */
+export class UnsupportedCursorSkipPermissionsError extends Error {
+    constructor() {
+        super('cursor runner does not support skipPermissions yet: cursor-agent has no verified per-run allowlist or sandbox mapping, so --force --trust is refused');
+        this.name = 'UnsupportedCursorSkipPermissionsError';
+    }
+}
+/** Thrown when Cursor's built-in runner is requested on Windows before its launcher path is run-verified. */
+export class UnsupportedCursorWindowsRunnerError extends Error {
+    constructor() {
+        super('cursor runner on Windows is not yet supported/run-verified due to cursor-agent shim spawn issue; use claude/codex or an injected cursor runner until the Windows launcher is run-verified');
+        this.name = 'UnsupportedCursorWindowsRunnerError';
+    }
+}
+export function assertCursorRunnerPlatformSupported(platform = process.platform) {
+    if (platform === 'win32')
+        throw new UnsupportedCursorWindowsRunnerError();
+}
+/**
+ * Make a bare command name spawnable shell-free on Windows. `spawn(shell:false)` cannot execute an npm CLI
+ * shim (a `.cmd`/`.bat`), and routing through a shell would expose the prompt arg to cmd.exe quoting
+ * (injection). npm shims are node wrappers, so we resolve the bare name on PATH and, when it's a node shim,
+ * run `node <entry.js>` directly (shell-free, args passed safely). A native `.exe` (claude) resolves to itself.
+ * No-op on POSIX and for any command that is already a path or has an extension. Surfaced by codex on Windows
+ * (codex is `codex.cmd`, while claude is `claude.exe`), #66.
+ */
+export function resolveSpawnCommand(cmd, args, env = process.env) {
+    if (process.platform !== 'win32' || /[\\/]/.test(cmd) || /\.[a-z0-9]+$/i.test(cmd))
+        return { cmd, args: [...args] };
+    for (const dir of (env['PATH'] ?? '').split(pathDelimiter).filter(Boolean)) {
+        for (const ext of ['.exe', '.cmd', '.bat']) {
+            const full = joinPath(dir, cmd + ext);
+            if (!existsSync(full))
+                continue;
+            if (ext === '.exe')
+                return { cmd: full, args: [...args] };
+            try {
+                const shim = readFileSync(full, 'utf8');
+                const rel = shim.match(/%~?dp0%?\\([^"\s]+\.js)/i)?.[1]; // npm node-shim: node "%dp0%\...\entry.js" %*
+                if (rel) {
+                    const js = joinPath(dir, rel);
+                    if (existsSync(js))
+                        return { cmd: process.execPath, args: [js, ...args] };
+                }
+            }
+            catch { /* unreadable shim — keep searching */ }
+            // A .cmd/.bat whose node entry we can't extract is NOT runnable shell-free — DON'T return it (that would
+            // ENOENT and also stop the search). Keep scanning later PATH dirs/exts for a real .exe or resolvable shim.
+        }
+    }
+    return { cmd, args: [...args] };
+}
+/**
+ * Promise wrapper over spawn (shell:false). Optionally writes `input` to stdin; resolves with stdout/exit.
+ * On timeout the WHOLE process group is killed, not just the direct child (finding #39.5): an agent spawns
+ * tool subprocesses (grandchildren) that would otherwise orphan and leak. On POSIX we spawn detached (the
+ * child becomes its own group leader) and SIGKILL the group via the negative pid; Windows falls back to a
+ * direct kill (different process-group semantics).
+ */
+export function spawnCapture(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        const detached = process.platform !== 'win32';
+        const r = resolveSpawnCommand(cmd, args, opts.env);
+        const child = spawn(r.cmd, r.args, { cwd: opts.cwd, shell: false, detached, ...(opts.env ? { env: opts.env } : {}) });
+        let stdout = '';
+        let stderr = '';
+        const killTree = () => {
+            if (detached && typeof child.pid === 'number') {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                    return;
+                }
+                catch { /* group gone; fall back */ }
+            }
+            child.kill('SIGKILL');
+        };
+        const timer = setTimeout(killTree, opts.timeoutMs);
+        child.stdout?.on('data', (d) => { stdout += d.toString(); });
+        child.stderr?.on('data', (d) => { stderr += d.toString(); });
+        child.on('error', (e) => { clearTimeout(timer); reject(e); });
+        child.on('close', (code) => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+        if (opts.input !== undefined) {
+            child.stdin?.write(opts.input);
+            child.stdin?.end();
+        }
+    });
+}
+/**
+ * Build the `claude -p` argv for the given options (pure — testable without spawning).
+ * Safety invariant: skipPermissions (bypassing prompts) is only allowed together with a non-empty
+ * allowedTools — otherwise it would be an unattended agent with full tools and no gate; refuse loudly.
+ */
+export function claudeRunnerArgs(opts = {}) {
+    const bounded = !!(opts.allowedTools && opts.allowedTools.length > 0);
+    if (opts.skipPermissions && !bounded)
+        throw new UnboundedSkipPermissionsError();
+    const args = ['-p', '--output-format', 'text'];
+    if (opts.skipPermissions)
+        args.push('--dangerously-skip-permissions');
+    if (opts.allowedTools && opts.allowedTools.length > 0)
+        args.push('--allowedTools', ...opts.allowedTools);
+    if (opts.model)
+        args.push('--model', opts.model);
+    return args;
+}
+/**
+ * Build a headless `claude -p` agent runner. Prompt fed via stdin (no shell, no argv length limit). For
+ * unattended evolution set { skipPermissions: true, allowedTools: ['Read','Edit','Write'] } — bypass the
+ * permission prompts but bound the agent to file edits. Validated end to end against a real agent.
+ */
+export function makeClaudeHeadlessRunner(opts = {}) {
+    const args = claudeRunnerArgs(opts);
+    return async (prompt, ctx) => {
+        try {
+            const r = await spawnCapture('claude', args, { cwd: ctx.cwd, timeoutMs: ctx.timeoutMs ?? DEFAULT_TIMEOUT_MS, input: prompt, ...(ctx.env ? { env: ctx.env } : {}) });
+            return r.code === 0 ? { ok: true, output: r.stdout } : { ok: false, output: r.stdout, error: r.stderr || `exit ${r.code}` };
+        }
+        catch (e) {
+            return { ok: false, output: '', error: e instanceof Error ? e.message : String(e) };
+        }
+    };
+}
+/** Default agent runner: conservative `claude -p --output-format text` (no permission bypass; opt in via makeClaudeHeadlessRunner). */
+export const claudeHeadlessRunner = makeClaudeHeadlessRunner();
+// --- Codex runner (#66 multi-harness) ---
+/**
+ * Build the `codex exec` argv (pure). Verified live against codex-cli 0.137.0:
+ *  - sandboxed default → `exec --sandbox workspace-write`: edits the workspace non-interactively (read-only,
+ *    the codex default, cannot write). The wrapper's worktree + allowedRoots are the outer containment.
+ *  - skipPermissions (bounded) → `exec --dangerously-bypass-approvals-and-sandbox`: full bypass, intended for
+ *    an already-externally-sandboxed run (our throwaway worktree). The `skip⇒bounded` invariant is the explicit
+ *    acknowledgement guard, same shape as claude.
+ */
+export function codexRunnerArgs(opts = {}) {
+    const bounded = !!(opts.allowedTools && opts.allowedTools.length > 0);
+    if (opts.skipPermissions && !bounded)
+        throw new UnboundedSkipPermissionsError(); // same invariant as claude skip⇒allowedTools
+    const args = ['exec'];
+    // codex bounds via sandbox mode (not a per-tool allowlist): workspace-write is the safe autonomous default;
+    // the explicit bypass removes the inner sandbox for a run the wrapper already isolates.
+    args.push('--sandbox', opts.skipPermissions ? 'danger-full-access' : 'workspace-write');
+    if (opts.skipPermissions)
+        args.push('--dangerously-bypass-approvals-and-sandbox');
+    if (opts.model)
+        args.push('--model', opts.model);
+    return args;
+}
+/** Headless `codex exec` runner. Working root pinned with `--cd`; prompt is the trailing positional arg (shell:false). */
+export function makeCodexHeadlessRunner(opts = {}) {
+    const args = codexRunnerArgs(opts);
+    return async (prompt, ctx) => {
+        try {
+            const r = await spawnCapture('codex', [...args, '--cd', ctx.cwd, prompt], { cwd: ctx.cwd, timeoutMs: ctx.timeoutMs ?? DEFAULT_TIMEOUT_MS, ...(ctx.env ? { env: ctx.env } : {}) });
+            return r.code === 0 ? { ok: true, output: r.stdout } : { ok: false, output: r.stdout, error: r.stderr || `exit ${r.code}` };
+        }
+        catch (e) {
+            return { ok: false, output: '', error: e instanceof Error ? e.message : String(e) };
+        }
+    };
+}
+// --- Cursor runner (#66 multi-harness) ---
+//
+// Flags below are GROUND-TRUTH from `cursor-agent --help` (CLI 2026.06.15), not guesses. Confirmed surface:
+//   - headless: `-p` / `--print` — "Has access to all tools, including write and shell". So `-p` ALONE can edit;
+//     output via `--output-format text|json|stream-json` (text default, only with --print).
+//   - autonomy flags: `-f`/`--force` (alias `--yolo`) = auto-allow commands unless explicitly denied; `--trust`
+//     = trust the workspace without prompting (headless only). Together they make `-p` truly non-interactive —
+//     WITHOUT them headless can block on a command-approval / workspace-trust prompt (the forum "-p hangs" reports).
+//   - `--model <model>` exists (e.g. gpt-5, sonnet-4, sonnet-4-thinking); `--list-models` enumerates.
+//   - auth: `CURSOR_API_KEY` or `--api-key` (the spec's envAllow prefix is CURSOR_).
+//   - cursor has its OWN `--sandbox enabled|disabled` and `-w/--worktree`; we still wrap with our git worktree.
+// STILL NOT run-verified end to end (needs an authed cursor-agent; claude/codex were each run-verified). Two known
+// gaps surfaced while testing: (1) on Windows `cursor-agent.cmd` is a powershell shim, NOT an npm node-shim, so
+// resolveSpawnCommand cannot rewrite it; the built-in runner fail-fasts there instead of surfacing ENOENT;
+// (2) the installed launcher's version-discovery regex rejects the real version dir name (Cursor's own bug).
+//
+// SAFETY: `-p --force --trust` auto-approves shell+write with no verified per-run allowlist/sandbox mapping.
+// Until Cursor can really map agentOptions into per-run permissions, skipPermissions is refused outright. The
+// wrapper worktree still contains default cursor runs, but it is not a permissions/sandbox substitute for skip.
+// Safe default keeps skip OFF (CURSOR_DEFAULT_AGENT_OPTIONS), so the wiring is exercised by tests with fakes.
+/**
+ * Build the `cursor-agent` argv (pure). Ground-truth from `cursor-agent --help` (#66): base `-p --output-format
+ * text` (headless, write+shell access). `--model` is a real flag. skipPermissions is rejected until Cursor has a
+ * verified per-run allowlist/sandbox mapping; allowedTools is not emitted because cursor has no per-tool allowlist.
+ */
+export function cursorRunnerArgs(opts = {}) {
+    if (opts.skipPermissions)
+        throw new UnsupportedCursorSkipPermissionsError();
+    const args = ['-p', '--output-format', 'text'];
+    if (opts.model)
+        args.push('--model', opts.model);
+    return args;
+}
+/**
+ * Headless `cursor-agent` runner. Prompt passed as the trailing positional arg (shell:false, no injection risk;
+ * docs show `cursor-agent -p "<prompt>"`). cwd is set via spawn. SCAFFOLD — run-verify against a real
+ * cursor-agent before autonomous use (see the block comment above for what is doc-confirmed vs unverified).
+ */
+export function makeCursorHeadlessRunner(opts = {}, platform = process.platform) {
+    const args = cursorRunnerArgs(opts);
+    return async (prompt, ctx) => {
+        assertCursorRunnerPlatformSupported(platform);
+        try {
+            const r = await spawnCapture('cursor-agent', [...args, prompt], { cwd: ctx.cwd, timeoutMs: ctx.timeoutMs ?? DEFAULT_TIMEOUT_MS, ...(ctx.env ? { env: ctx.env } : {}) });
+            return r.code === 0 ? { ok: true, output: r.stdout } : { ok: false, output: r.stdout, error: r.stderr || `exit ${r.code}` };
+        }
+        catch (e) {
+            return { ok: false, output: '', error: e instanceof Error ? e.message : String(e) };
+        }
+    };
+}
+const RUNNER_SPECS = {
+    claude: { name: 'claude', makeRunner: makeClaudeHeadlessRunner, envAllow: { prefixes: ['ANTHROPIC_', 'CLAUDE_'] } },
+    codex: { name: 'codex', makeRunner: makeCodexHeadlessRunner, envAllow: { prefixes: ['OPENAI_', 'CODEX_'] } },
+    // cursor keeps only its OWN auth env (CURSOR_); like every runner it never inherits another's vendor key.
+    cursor: { name: 'cursor', makeRunner: makeCursorHeadlessRunner, envAllow: { prefixes: ['CURSOR_'] } },
+};
+/** Resolve a runner spec by name (default 'claude' — byte-identical to the pre-registry behavior). */
+export function getRunnerSpec(name = 'claude') {
+    return RUNNER_SPECS[name];
+}

package/dist/exec/selfPr.d.ts

@@ -0,0 +1,83 @@
+import { type ReadManifest } from './selfPrObfuscation.js';
+export interface SelfPrGates {
+    /** Minimum outcome score. Default 0.9. */
+    minScore: number;
+    /** Minimum consecutive-success streak. Default 2. */
+    minStreak: number;
+    /** Maximum changed files. Default 5. */
+    maxFiles: number;
+    /** Maximum changed lines. Default 200. */
+    maxLines: number;
+    /** Cooldown between self-PRs (ms). Default 24h. */
+    cooldownMs: number;
+}
+export declare const DEFAULT_SELF_PR_GATES: SelfPrGates;
+export interface SelfPrEvalInput {
+    /** Master opt-in. Default-off: when false/undefined the PR is never created. */
+    enabled: boolean;
+    /** Deny-by-default repo allowlist. Empty = deny everything (the safe default). */
+    allowedRoots: readonly string[];
+    repoRoot: string;
+    outcome: {
+        status: string;
+        score: number;
+    };
+    successStreak?: number;
+    changedFiles: readonly string[];
+    blastLines?: number;
+    /** Dedup/cooldown state (supplied from a SelfPrState store). */
+    lastPrAt?: string | null;
+    recentDiffHashes?: readonly string[];
+    diffHash?: string;
+    now?: number;
+}
+export interface SelfPrDecision {
+    eligible: boolean;
+    reason: string;
+}
+/**
+ * Decide whether a self-PR may be created. Pure — combines every gate and returns the FIRST failing reason, so
+ * the default (disabled, empty allowlist) is always a clean refusal that runs nothing.
+ */
+export declare function evaluateSelfPr(input: SelfPrEvalInput, gates?: SelfPrGates): SelfPrDecision;
+/** Run a `gh`/`git` subcommand. Inject a fake in tests; the default would shell out (never invoked unless eligible). */
+export type GhRunner = (args: readonly string[], cwd: string) => Promise<{
+    ok: boolean;
+    stdout: string;
+    stderr?: string;
+}>;
+/** Scan text for secrets before any push. Return leaked:true to BLOCK. Inject e.g. the hub sanitize check. */
+export type LeakScan = (text: string) => {
+    leaked: boolean;
+    detail?: string;
+};
+export interface CreateSelfPrDeps {
+    gh: GhRunner;
+    leakScan?: LeakScan;
+    /**
+     * Injectable reader for `public.manifest.json` (the obfuscate guard). Tests pass a fake so they don't depend
+     * on a real manifest on disk. When omitted, defaults to reading `<repoRoot>/public.manifest.json`. A missing /
+     * unreadable / invalid manifest is FAIL-CLOSED: every changed file is treated as obfuscated → the PR is blocked.
+     */
+    readManifest?: ReadManifest;
+}
+export interface CreateSelfPrContent {
+    branch: string;
+    title: string;
+    body: string;
+    /** The unified diff (scanned for leaks before pushing). */
+    diff: string;
+    base?: string;
+}
+export interface CreateSelfPrResult {
+    created: boolean;
+    reason: string;
+    url?: string;
+}
+/**
+ * Create a DRAFT pull request for an eligible self-mutation. Re-checks eligibility (so it can't be bypassed),
+ * blocks any change touching an OBFUSCATED file (fail-closed manifest), leak-scans the diff + body, then stages
+ * ONLY the agent's changed files (never `git add -A`), commits, pushes the branch and opens the PR with
+ * `gh pr create --draft`. ALWAYS draft, NEVER merges. Any gh failure is returned, not thrown.
+ */
+export declare function createDraftSelfPr(evalInput: SelfPrEvalInput, content: CreateSelfPrContent, deps: CreateSelfPrDeps, gates?: SelfPrGates): Promise<CreateSelfPrResult>;

package/dist/exec/selfPr.js

@@ -0,0 +1,104 @@
+// Self-PR (ported + hardened from v1 gep/selfPR.js). Turns a high-confidence self-mutation into a DRAFT pull
+// request on an allowlisted repo, so a human reviews and merges. This touches a REAL repo, so it is wrapped in
+// the same deny-by-default discipline as the exec bridge and is OFF unless explicitly opted in:
+//   1. enabled === true (default off)              4. always --draft, NEVER auto-merge
+//   2. repo within allowedRoots (empty = deny all)  5. confidence gates (score/streak/blast)
+//   3. leak scan of the diff before any push        6. cooldown + diff dedup
+// evaluateSelfPr is PURE (decision only); the `gh` call is an injected GhRunner seam so a test never creates a
+// real PR. Nothing here runs unless the caller has wired enabled:true AND a non-empty allowedRoots.
+import { resolve as resolvePath, sep } from 'node:path';
+import { defaultReadManifest, isObfuscatedFile } from './selfPrObfuscation.js';
+export const DEFAULT_SELF_PR_GATES = { minScore: 0.9, minStreak: 2, maxFiles: 5, maxLines: 200, cooldownMs: 24 * 60 * 60 * 1000 };
+/** Whether `child` is the same as or nested under `root` (both resolved absolute). */
+function isWithinRoot(child, root) {
+    const c = resolvePath(child);
+    const r = resolvePath(root);
+    return c === r || c.startsWith(r.endsWith(sep) ? r : r + sep);
+}
+/**
+ * Decide whether a self-PR may be created. Pure — combines every gate and returns the FIRST failing reason, so
+ * the default (disabled, empty allowlist) is always a clean refusal that runs nothing.
+ */
+export function evaluateSelfPr(input, gates = DEFAULT_SELF_PR_GATES) {
+    if (input.enabled !== true)
+        return { eligible: false, reason: 'disabled' };
+    if (!input.allowedRoots || input.allowedRoots.length === 0)
+        return { eligible: false, reason: 'no_allowed_roots' };
+    if (!input.allowedRoots.some((root) => isWithinRoot(input.repoRoot, root)))
+        return { eligible: false, reason: 'repo_not_allowlisted' };
+    if (input.outcome?.status !== 'success')
+        return { eligible: false, reason: 'not_successful' };
+    if ((Number(input.outcome.score) || 0) < gates.minScore)
+        return { eligible: false, reason: 'score_below_min' };
+    if ((input.successStreak ?? 0) < gates.minStreak)
+        return { eligible: false, reason: 'streak_below_min' };
+    const files = (input.changedFiles ?? []).filter(Boolean);
+    if (files.length === 0)
+        return { eligible: false, reason: 'no_changes' };
+    if (files.length > gates.maxFiles)
+        return { eligible: false, reason: 'too_many_files' };
+    if ((input.blastLines ?? 0) > gates.maxLines)
+        return { eligible: false, reason: 'too_many_lines' };
+    if (input.lastPrAt) {
+        const elapsed = (input.now ?? Date.now()) - new Date(input.lastPrAt).getTime();
+        if (Number.isFinite(elapsed) && elapsed < gates.cooldownMs)
+            return { eligible: false, reason: 'cooldown' };
+    }
+    if (input.diffHash && (input.recentDiffHashes ?? []).includes(input.diffHash))
+        return { eligible: false, reason: 'duplicate_diff' };
+    return { eligible: true, reason: 'eligible' };
+}
+/**
+ * Create a DRAFT pull request for an eligible self-mutation. Re-checks eligibility (so it can't be bypassed),
+ * blocks any change touching an OBFUSCATED file (fail-closed manifest), leak-scans the diff + body, then stages
+ * ONLY the agent's changed files (never `git add -A`), commits, pushes the branch and opens the PR with
+ * `gh pr create --draft`. ALWAYS draft, NEVER merges. Any gh failure is returned, not thrown.
+ */
+export async function createDraftSelfPr(evalInput, content, deps, gates = DEFAULT_SELF_PR_GATES) {
+    const decision = evaluateSelfPr(evalInput, gates);
+    if (!decision.eligible)
+        return { created: false, reason: decision.reason };
+    // The set of files the agent actually changed this cycle (from the exec `git diff --name-only`). We stage
+    // EXACTLY these, never `git add -A` (which would sweep every stray/uncommitted change in the working tree
+    // into the self-PR). evaluateSelfPr already guarantees this is non-empty (the `no_changes` gate), but re-guard
+    // here so an empty list is an explicit no-op self-PR rather than a tree-sweeping commit.
+    const changedFiles = (evalInput.changedFiles ?? []).filter(Boolean);
+    if (changedFiles.length === 0)
+        return { created: false, reason: 'no_changes' };
+    // Obfuscation-leak guard: any changed file that ships OBFUSCATED on the public repo (per public.manifest.json)
+    // would land as raw source there. Block before we create anything. FAIL-CLOSED: a missing/unreadable/invalid
+    // manifest treats every file as obfuscated, so the guard never silently lets a leaking file through.
+    const readManifest = deps.readManifest ?? defaultReadManifest(evalInput.repoRoot);
+    for (const file of changedFiles) {
+        if (isObfuscatedFile(file, readManifest))
+            return { created: false, reason: `obfuscated_file_blocked: ${file}` };
+    }
+    if (deps.leakScan) {
+        for (const text of [content.diff, content.body]) {
+            const scan = deps.leakScan(text);
+            if (scan.leaked)
+                return { created: false, reason: `leak_blocked${scan.detail ? `: ${scan.detail}` : ''}` };
+        }
+    }
+    const cwd = evalInput.repoRoot;
+    const run = async (args) => deps.gh(args, cwd);
+    const checkout = await run(['checkout', '-b', content.branch]);
+    if (!checkout.ok)
+        return { created: false, reason: `git_checkout_failed: ${checkout.stderr ?? ''}`.trim() };
+    // Stage ONLY the agent's changed files (the `--` terminator stops any path being read as an option). NOT -A.
+    const add = await run(['add', '--', ...changedFiles]);
+    if (!add.ok)
+        return { created: false, reason: 'git_add_failed' };
+    const commit = await run(['commit', '-m', content.title]);
+    if (!commit.ok)
+        return { created: false, reason: 'git_commit_failed' };
+    const push = await run(['push', '-u', 'origin', content.branch]);
+    if (!push.ok)
+        return { created: false, reason: `git_push_failed: ${push.stderr ?? ''}`.trim() };
+    // ALWAYS --draft; never any merge/auto-merge flag.
+    const prArgs = ['pr', 'create', '--draft', '--title', content.title, '--body', content.body, ...(content.base ? ['--base', content.base] : [])];
+    const pr = await run(prArgs);
+    if (!pr.ok)
+        return { created: false, reason: `gh_pr_create_failed: ${pr.stderr ?? ''}`.trim() };
+    return { created: true, reason: 'created', url: pr.stdout.trim() };
+}

package/dist/exec/selfPrObfuscation.d.ts

@@ -0,0 +1,21 @@
+/** Reads the raw manifest text. Return null when absent/unreadable (treated as fail-closed). Inject in tests. */
+export type ReadManifest = () => string | null;
+/** Normalize a path for comparison: backslash→slash, strip leading `./`, trim. Mirrors v1 normalizeRel. */
+export declare function normalizeManifestPath(filePath: string): string;
+/** Default manifest reader: reads `<repoRoot>/public.manifest.json`, returning null on any failure. */
+export declare function defaultReadManifest(repoRoot: string): ReadManifest;
+/** Test/maintenance hook: drop any cached load for a reader (or all readers) so the load path re-runs. */
+export declare function resetObfuscatedCache(reader?: ReadManifest): void;
+/**
+ * Load the obfuscated-file set from the manifest. Returns a normalized Set, or null when the manifest is
+ * missing / unreadable / structurally invalid (NOT an `obfuscate` array of literal string paths). null is the
+ * fail-closed signal: the caller must then reject all files. Result is cached per reader.
+ */
+export declare function loadObfuscatedFiles(readManifest: ReadManifest): Set<string> | null;
+/**
+ * Is `changedFile` one of the obfuscated files? FAIL-CLOSED: when the manifest can't be loaded (null) every
+ * file is treated as obfuscated. Matching is on the normalized relative path (exact, segment-aware) — the
+ * manifest holds literal file paths, so a similarly-named non-obfuscated file (e.g. "src/secret_helper.ts"
+ * vs an obfuscated "src/secret.ts") is NOT a false positive.
+ */
+export declare function isObfuscatedFile(changedFile: string, readManifest: ReadManifest): boolean;

package/dist/exec/selfPrObfuscation.js

@@ -0,0 +1,85 @@
+// Obfuscation-leak guard for self-PRs (ported from v1 src/gep/selfPR.js loadObfuscatedFromManifest /
+// isPublicNonObfuscated, the `public.manifest.json` obfuscate slice). Some files ship OBFUSCATED on the public
+// repo: a self-PR that touches one of those would land RAW SOURCE there, leaking implementation detail. This
+// module reads `public.manifest.json`'s `obfuscate` array (literal string paths) and exposes a segment-aware
+// membership check.
+//
+// FAIL-CLOSED (matches v1): when the manifest is MISSING / unreadable / invalid, loadObfuscatedFiles returns
+// null and isObfuscatedFile treats EVERY file as obfuscated (rejects), so a missing manifest can never silently
+// let a potentially-leaking file through. The manifest read is INJECTABLE so tests are hermetic and never depend
+// on a real public.manifest.json on disk. Pure + injectable; the cache is resettable. Hub-agnostic (no economy).
+import { readFileSync } from 'node:fs';
+import { join as joinPath } from 'node:path';
+/** Normalize a path for comparison: backslash→slash, strip leading `./`, trim. Mirrors v1 normalizeRel. */
+export function normalizeManifestPath(filePath) {
+    return String(filePath ?? '')
+        .replace(/\\/g, '/')
+        .replace(/^\.\/+/, '')
+        .trim();
+}
+/** Default manifest reader: reads `<repoRoot>/public.manifest.json`, returning null on any failure. */
+export function defaultReadManifest(repoRoot) {
+    return () => {
+        try {
+            return readFileSync(joinPath(repoRoot, 'public.manifest.json'), 'utf8');
+        }
+        catch {
+            return null;
+        }
+    };
+}
+// Resettable cache keyed by the reader identity, so distinct readers (e.g. per test) don't bleed into each other.
+// `null` = a load was attempted and FAILED (fail-closed); a Set = the loaded obfuscate paths.
+const cache = new WeakMap();
+/** Test/maintenance hook: drop any cached load for a reader (or all readers) so the load path re-runs. */
+export function resetObfuscatedCache(reader) {
+    if (reader)
+        cache.delete(reader);
+    // A WeakMap can't be cleared wholesale; callers that need a clean slate pass a fresh reader instead.
+}
+/**
+ * Load the obfuscated-file set from the manifest. Returns a normalized Set, or null when the manifest is
+ * missing / unreadable / structurally invalid (NOT an `obfuscate` array of literal string paths). null is the
+ * fail-closed signal: the caller must then reject all files. Result is cached per reader.
+ */
+export function loadObfuscatedFiles(readManifest) {
+    if (cache.has(readManifest))
+        return cache.get(readManifest) ?? null;
+    let result;
+    try {
+        const raw = readManifest();
+        if (raw === null)
+            throw new Error('public.manifest.json not found / unreadable');
+        const manifest = JSON.parse(raw);
+        if (!Array.isArray(manifest.obfuscate)) {
+            throw new Error('public.manifest.json missing `obfuscate` array');
+        }
+        // Reject globs / non-strings: a glob would silently miss exact-path matches and reintroduce drift.
+        for (const f of manifest.obfuscate) {
+            if (typeof f !== 'string' || /[*?[\]]/.test(f)) {
+                throw new Error(`public.manifest.json \`obfuscate\` must contain literal paths, got: ${JSON.stringify(f)}`);
+            }
+        }
+        result = new Set(manifest.obfuscate.map((f) => normalizeManifestPath(f)).filter(Boolean));
+    }
+    catch {
+        result = null; // fail-closed: an unreadable/invalid manifest rejects everything
+    }
+    cache.set(readManifest, result);
+    return result;
+}
+/**
+ * Is `changedFile` one of the obfuscated files? FAIL-CLOSED: when the manifest can't be loaded (null) every
+ * file is treated as obfuscated. Matching is on the normalized relative path (exact, segment-aware) — the
+ * manifest holds literal file paths, so a similarly-named non-obfuscated file (e.g. "src/secret_helper.ts"
+ * vs an obfuscated "src/secret.ts") is NOT a false positive.
+ */
+export function isObfuscatedFile(changedFile, readManifest) {
+    const obfuscated = loadObfuscatedFiles(readManifest);
+    if (obfuscated === null)
+        return true; // fail-closed
+    const rel = normalizeManifestPath(changedFile);
+    if (!rel)
+        return false;
+    return obfuscated.has(rel);
+}