@cleocode/core 2026.6.14 → 2026.6.15

package/dist/resources/spawn-wrapper.js

@@ -0,0 +1,304 @@
+/**
+ * Slice-aware launch-wrapper SSoT (T11993 · Epic T11992).
+ *
+ * This module is the ONLY constructor of `systemd-run` argv for cleo children.
+ * Every consumer that needs to launch a cleo child in a memory-capped cgroup
+ * MUST call {@link buildSpawnArgs} or {@link spawnWrapped} here instead of
+ * constructing `systemd-run` arguments ad-hoc.
+ *
+ * ## Design
+ *
+ * Children are placed inside `cleo.slice` when systemd is available:
+ *
+ * ```
+ * cleo.slice
+ *   ├── cleo-daemon.service         (managed by the daemon service unit)
+ *   └── cleo-<scopeClass>-<n>.scope (transient scopes for child spawns)
+ * ```
+ *
+ * The slice applies MemoryHigh (primary soft throttle) and MemoryMax (hard
+ * safety net) at the slice level, shared across all members.  Child scopes
+ * inherit these limits and may override them downward.
+ *
+ * ## Staged P1 budget (IMPORTANT — read before tuning)
+ *
+ * P1 ships MemoryHigh within 5 % of MemoryMax (80 % / 85 % of a reference
+ * host total) so that reclaim stalls under the soft limit NEVER block the
+ * SQLite WAL write-transaction held by a slice member.  A stalled scope
+ * holding a WAL write-txn for > 30 s (busy_timeout) cascades SQLITE_BUSY to
+ * every other slice member.
+ *
+ * **P1 installed values (safe defaults):**
+ *   - `MemoryHigh = undefined` (disabled — no throttle in P1)
+ *   - `MemoryMax  = 32G`       (hard cap, benign cgroup kill)
+ *
+ * The 60 % / 85 % target shape is documented here and in `DEFAULT_SLICE_CONFIG`
+ * as the P2 goal once the stall-escalator (T11994) is in place.
+ *
+ * **With `MemorySwapMax=0`:** reclaim has only page-cache to chew against
+ * `MemoryHigh` on anonymous heaps — admission (P2) becomes the primary
+ * control, throttling is not load-bearing in P1.
+ *
+ * ## oomd-avoid (selective)
+ *
+ * `ManagedOOMPreference=avoid` is applied ONLY to daemon/db-heavy scope
+ * classes (`'daemon'`, `'db'`).  Bulk agent/test scopes do NOT get `avoid`
+ * because Fedora oomd monitors `user@1000.service` at 80 %/20 s and ranks
+ * avoid-marked candidates last — blanket avoid redirects oomd kills onto
+ * innocent user apps.
+ *
+ * ## Fallback
+ *
+ * On hosts without systemd-run (macOS, CI containers, minimal installs)
+ * the wrapper degrades log-once to plain `spawn` in a new process-group
+ * with NODE_OPTIONS heap cap inherited from the caller.  This is mirrored
+ * from the writer-lease `pgid-demotion` pattern.
+ *
+ * ## Return value — ownership handle (T11998 / T11995)
+ *
+ * {@link SpawnWrappedResult} carries `{ unitName?, pid, mode }` so the
+ * suite-containment epic (T11998) and the janitor (T11995) can look up or
+ * clean up the transient scope by unit name.
+ *
+ * @module @cleocode/core/resources/spawn-wrapper
+ * @epic T11992
+ * @task T11993
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * The systemd user slice that all cleo child scopes are placed under.
+ *
+ * The slice unit (`~/.config/systemd/user/cleo.slice`) must be installed
+ * by the doctor/install flow before this is effective.  Placing an orphan
+ * scope under a non-existent slice degrades silently to the default slice —
+ * so the slice install is best-effort and the wrapper is always safe to call.
+ */
+export const CLEO_SLICE = 'cleo.slice';
+/**
+ * Default per-scope memory resource config (P1 staged values).
+ *
+ * P1: MemoryHigh disabled, MemoryMax=32G.
+ * P2 target (after T11994 stall-escalator lands): memoryHigh=0.60, memoryMax=0.85.
+ */
+export const DEFAULT_SCOPE_RESOURCES = {
+    memoryHigh: 'infinity', // P1: disabled — no throttle (safe until P2 stall-escalator)
+    memoryMax: '32G', // P1: hard cap (benign cgroup kill; coredumps suppressed via ulimit -c 0)
+};
+/**
+ * Scope classes that receive `ManagedOOMPreference=avoid`.
+ *
+ * Only write-transaction holders (daemon, db) are marked `avoid` to prevent
+ * mid-txn oomd kills.  See module-level TSDoc for the Fedora oomd rationale.
+ */
+const OOM_AVOID_CLASSES = new Set(['daemon', 'db']);
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Is `systemd-run` available on this host? Probed once and cached.
+ * Mirrors the probe in `packages/core/src/check/pr-gate.ts`.
+ */
+let _systemdRunAvailable;
+/**
+ * Check whether `systemd-run --user` is usable on this host.
+ *
+ * Returns `false` on non-Linux, when systemd-run is not on PATH, or when
+ * DBUS_SESSION_BUS_ADDRESS / XDG_RUNTIME_DIR are absent (CI containers,
+ * ssh sessions without a user bus).
+ */
+export function hasSystemdRun() {
+    if (_systemdRunAvailable !== undefined)
+        return _systemdRunAvailable;
+    if (process.platform !== 'linux') {
+        _systemdRunAvailable = false;
+        return false;
+    }
+    // Quick binary availability check — does NOT test user-bus connectivity.
+    const probe = spawnSync('systemd-run', ['--version'], { stdio: 'ignore' });
+    _systemdRunAvailable = probe.status === 0;
+    return _systemdRunAvailable;
+}
+/**
+ * Force-override the cached systemd-run availability.
+ *
+ * Exposed for unit tests that need to exercise the pgid-fallback or
+ * systemd paths without the real binary.
+ *
+ * @param available - `true` = force systemd path, `false` = force pgid path.
+ */
+export function _forceSystemdRunAvailable(available) {
+    _systemdRunAvailable = available;
+}
+/** Whether we have already emitted the pgid-demotion log line for this process. */
+let _pgidDemotionLogged = false;
+/**
+ * Resolve a memory value to a systemd property string.
+ *
+ * Numbers in (0, 1] are treated as fractions of a `totalBytes` reference.
+ * Strings are passed through verbatim.  `undefined` / `'infinity'` resolves
+ * to `'infinity'` (disabled).
+ */
+function resolveMemoryValue(val, totalBytes) {
+    if (val === undefined || val === 'infinity')
+        return 'infinity';
+    if (typeof val === 'string')
+        return val;
+    // Fraction: multiply by total and round to nearest mebibyte boundary.
+    const bytes = Math.round(val * totalBytes);
+    const mib = Math.round(bytes / (1024 * 1024));
+    return `${mib}M`;
+}
+/**
+ * Read /proc/meminfo MemTotal in bytes.  Returns 32 GiB as a safe fallback
+ * when unavailable (non-Linux, CI, permission denied).
+ */
+function readMemTotalBytes() {
+    if (process.platform !== 'linux')
+        return 32 * 1024 * 1024 * 1024;
+    try {
+        const raw = readFileSync('/proc/meminfo', 'utf8');
+        const m = raw.match(/^MemTotal:\s+(\d+)\s+kB/m);
+        if (m?.[1])
+            return parseInt(m[1], 10) * 1024;
+    }
+    catch {
+        // ignore
+    }
+    return 32 * 1024 * 1024 * 1024;
+}
+/** Counter for generating unique scope discriminators within a process. */
+let _scopeCounter = 0;
+// ---------------------------------------------------------------------------
+// Core API
+// ---------------------------------------------------------------------------
+/**
+ * Build the argv for a cleo child spawn.
+ *
+ * When `systemd-run` is available, the result is:
+ *
+ * ```
+ * ['systemd-run', '--user', '--scope', '--slice=cleo.slice',
+ *   '--unit=cleo-<class>-<id>.scope',
+ *   '-p', 'MemoryHigh=<high>', '-p', 'MemoryMax=<max>',
+ *   '-p', 'MemorySwapMax=0',
+ *   ['-p', 'ManagedOOMPreference=avoid'],  // daemon/db only
+ *   '--',
+ *   // when noCoreFile=true (default):
+ *   'sh', '-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args
+ *   // when noCoreFile=false:
+ *   command, ...args]
+ * ```
+ *
+ * `LimitCORE` is intentionally NOT used — it is a service-unit EXEC property
+ * and is rejected by `systemd-run --scope` with "Unknown assignment: LimitCORE".
+ * Core-dump suppression is applied at the process level instead via
+ * `ulimit -c 0` (POSIX sh, works in both systemd and pgid-fallback paths).
+ *
+ * When `systemd-run` is NOT available, the result is `[command, ...args]`
+ * (or the sh/ulimit-wrapped form when noCoreFile=true) and `mode` is `'pgid'`.
+ *
+ * @param command - The executable to run (e.g. `'node'`).
+ * @param args - Arguments to pass to the executable.
+ * @param opts - Wrapper options (scope class, resources, etc.).
+ * @returns Build result with final command, args, mode, and unit name.
+ */
+export function buildSpawnArgs(command, args, opts = {}) {
+    const { scopeClass = 'agent', scopeId, resources = {}, noCoreFile = true } = opts;
+    if (!hasSystemdRun()) {
+        if (!_pgidDemotionLogged) {
+            _pgidDemotionLogged = true;
+            process.stderr.write('[cleo:spawn-wrapper] systemd-run unavailable — falling back to plain pgid spawn ' +
+                '(no cgroup containment; set NODE_OPTIONS=--max-old-space-size=<mb> externally)\n');
+        }
+        if (noCoreFile) {
+            // Apply ulimit -c 0 in the pgid path as well so core suppression is
+            // consistent regardless of whether systemd is available.
+            return {
+                command: 'sh',
+                args: ['-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args],
+                mode: 'pgid',
+            };
+        }
+        return { command, args: [...args], mode: 'pgid' };
+    }
+    const totalBytes = readMemTotalBytes();
+    const merged = {
+        memoryHigh: resources.memoryHigh ?? DEFAULT_SCOPE_RESOURCES.memoryHigh,
+        memoryMax: resources.memoryMax ?? DEFAULT_SCOPE_RESOURCES.memoryMax,
+    };
+    const highStr = resolveMemoryValue(merged.memoryHigh, totalBytes);
+    const maxStr = resolveMemoryValue(merged.memoryMax, totalBytes);
+    // Build a deterministic, unique unit name.
+    const counter = ++_scopeCounter;
+    const discriminator = scopeId ? scopeId.replace(/[^a-zA-Z0-9-]/g, '-') : String(counter);
+    const unitName = `cleo-${scopeClass}-${discriminator}.scope`;
+    const wrapArgs = [
+        '--user',
+        '--scope',
+        `--slice=${CLEO_SLICE}`,
+        `--unit=${unitName}`,
+        '-p',
+        `MemoryMax=${maxStr}`,
+        '-p',
+        'MemorySwapMax=0',
+    ];
+    // MemoryHigh: only emit the directive when it is a real limit (not infinity).
+    if (highStr !== 'infinity') {
+        wrapArgs.push('-p', `MemoryHigh=${highStr}`);
+    }
+    // Selective oomd-avoid: only for write-txn holder classes.
+    if (OOM_AVOID_CLASSES.has(scopeClass)) {
+        wrapArgs.push('-p', 'ManagedOOMPreference=avoid');
+    }
+    if (noCoreFile) {
+        // LimitCORE is a service-unit EXEC property — it is NOT valid on scope
+        // units and causes systemd-run to reject the argv with:
+        //   "Unknown assignment: LimitCORE=0"
+        // Suppress coredumps at the process level instead: wrap the inner command
+        // in a tiny sh fragment that sets `ulimit -c 0` then execs the real binary.
+        // This is equivalent to LimitCORE for our purposes and works on both
+        // Fedora and Ubuntu CI runners.
+        wrapArgs.push('--', 'sh', '-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args);
+    }
+    else {
+        wrapArgs.push('--', command, ...args);
+    }
+    return {
+        command: 'systemd-run',
+        args: wrapArgs,
+        mode: 'systemd',
+        unitName,
+    };
+}
+/**
+ * Spawn a command wrapped in a cleo.slice transient cgroup scope.
+ *
+ * This is a thin convenience wrapper over {@link buildSpawnArgs} +
+ * Node.js `child_process.spawn`.  All cleo child spawns SHOULD route through
+ * this function instead of constructing `systemd-run` arguments inline.
+ *
+ * The returned {@link SpawnWrappedResult} carries `unitName` — the systemd
+ * transient scope unit name — as the ownership/cleanup handle for
+ * T11998 (suite containment) and T11995 (janitor).
+ *
+ * @param command - The executable to run.
+ * @param args - Arguments to pass to the executable.
+ * @param spawnOpts - Options forwarded to `child_process.spawn`.
+ * @param wrapOpts - Wrapper options (scope class, resources, etc.).
+ * @returns Wrapped spawn result.
+ */
+export function spawnWrapped(command, args, spawnOpts = {}, wrapOpts = {}) {
+    const built = buildSpawnArgs(command, args, wrapOpts);
+    const child = spawn(built.command, built.args, spawnOpts);
+    return {
+        child,
+        pid: child.pid,
+        mode: built.mode,
+        unitName: built.unitName,
+    };
+}
+//# sourceMappingURL=spawn-wrapper.js.map

package/dist/resources/spawn-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-wrapper.js","sourceRoot":"","sources":["../../src/resources/spawn-wrapper.ts"],"names":[],"mappings":"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"}

package/dist/selfimprove/budget.d.ts

@@ -75,13 +75,22 @@ export interface SelfImproveBudget {
  */
 export declare const DEFAULT_BUDGET: SelfImproveBudget;
 /**
+ * @deprecated Use {@link "../resources/spawn-wrapper.js".buildSpawnArgs} instead.
+ *
  * The launch-boundary memory cap — an OPERATIONAL wrapper, NOT an in-code cap.
  *
  * A CORE function cannot portably self-confine to a cgroup (`systemd-run` is
  * Linux-only; re-exec'ing under it from inside the engine is fragile), so the
  * runbook / spawn wrapper that invokes `cleo selfimprove run` wraps it on Linux.
- * On macOS the gondolin VM's own `memory` option bounds the guest. Exported as a
- * documented constant so the spawn wrapper and the runbook share one SSoT string.
+ * On macOS the gondolin VM's own `memory` option bounds the guest.
+ *
+ * **Retired (T11993)**: callers should use
+ * `buildSpawnArgs('cleo', ['selfimprove', 'run', ...], {}, { scopeClass: 'agent' })`
+ * from `@cleocode/core/resources/spawn-wrapper` instead.  This constant remains
+ * exported only for backward compatibility until all doc references are updated.
+ *
+ * The new SSoT places children under `cleo.slice` with coredumps suppressed
+ * via `ulimit -c 0` and staged memory budgets (see spawn-wrapper module TSDoc).
  */
 export declare const MEMORY_MAX_LAUNCH_WRAPPER: "systemd-run --user --scope -p MemoryMax=32G -p MemorySwapMax=0";
 /**

package/dist/selfimprove/budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/selfimprove/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB;AAC9B,mEAAmE;AACjE,SAAS;AACX,+EAA+E;GAC7E,kBAAkB;AACpB,+DAA+D;GAC7D,eAAe;AACjB,6CAA6C;GAC3C,SAAS,CAAC;AAEd;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,iBAK5B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EACpC,gEAAyE,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2CAA2C;AAC3C,wBAAgB,UAAU,IAAI,WAAW,CAExC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,oCAAoC;IACpC,SAAgB,IAAI,EAAG,+BAA+B,CAAU;IAChE,8BAA8B;IAC9B,SAAgB,SAAS,EAAE,MAAM,iBAAiB,CAAC;IAEnD;;;;OAIG;gBACS,SAAS,EAAE,MAAM,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAK/E;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7C,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;;IAOzB;;;OAGG;gBACS,MAAM,GAAE,iBAAkC,EAAE,KAAK,GAAE,WAA0B;IAKzF,4CAA4C;IAC5C,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,6DAA6D;IAC7D,IAAI,KAAK,IAAI,mBAAmB,CAE/B;IAED,2EAA2E;IAC3E,IAAI,KAAK,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEjC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAOxD;;;;;OAKG;IACH,YAAY,IAAI,IAAI;IAQpB;;;;;;;;OAQG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;CA2BzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,GAAE,OAAO,CAAC,iBAAiB,CAAM,EAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,iBAAiB,CAenB"}
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/selfimprove/budget.ts"],"names":[],"mappings":"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"}

package/dist/selfimprove/budget.js

@@ -44,13 +44,22 @@ export const DEFAULT_BUDGET = {
     maxWorktrees: 1,
 };
 /**
+ * @deprecated Use {@link "../resources/spawn-wrapper.js".buildSpawnArgs} instead.
+ *
  * The launch-boundary memory cap — an OPERATIONAL wrapper, NOT an in-code cap.
  *
  * A CORE function cannot portably self-confine to a cgroup (`systemd-run` is
  * Linux-only; re-exec'ing under it from inside the engine is fragile), so the
  * runbook / spawn wrapper that invokes `cleo selfimprove run` wraps it on Linux.
- * On macOS the gondolin VM's own `memory` option bounds the guest. Exported as a
- * documented constant so the spawn wrapper and the runbook share one SSoT string.
+ * On macOS the gondolin VM's own `memory` option bounds the guest.
+ *
+ * **Retired (T11993)**: callers should use
+ * `buildSpawnArgs('cleo', ['selfimprove', 'run', ...], {}, { scopeClass: 'agent' })`
+ * from `@cleocode/core/resources/spawn-wrapper` instead.  This constant remains
+ * exported only for backward compatibility until all doc references are updated.
+ *
+ * The new SSoT places children under `cleo.slice` with coredumps suppressed
+ * via `ulimit -c 0` and staged memory budgets (see spawn-wrapper module TSDoc).
  */
 export const MEMORY_MAX_LAUNCH_WRAPPER = 'systemd-run --user --scope -p MemoryMax=32G -p MemorySwapMax=0';
 /** A fresh, zeroed {@link BudgetSpend}. */

package/dist/selfimprove/budget.js.map

@@ -1 +1 @@
-{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/selfimprove/budget.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/selfimprove/budget.ts"],"names":[],"mappings":"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"}

package/dist/selfimprove/fix-gen.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Fix-generation stage for the self-improvement loop (T11889 · T11975).
+ *
+ * This is the missing autonomous link the v1 loop explicitly stubbed out
+ * ("NO autonomous fix-gen in v1", see {@link "./run-loop.js"}): given a detected
+ * regression (an open `selfimprove_dhq` + its envelope-diff) plus minimal repo
+ * context, it asks the LLM to PROPOSE a unified-diff patch and writes that patch
+ * to the path the draft-PR egress ({@link "./draft-pr.js".openDraftPr}) already
+ * `existsSync`-checks: `<cwd>/selfimprove-<scenario>.patch`. Once the patch is on
+ * disk the existing egress guard opens ONE DRAFT PR — closing the
+ * DHQ → fix → draft-PR pipeline end-to-end.
+ *
+ * ## Hard safety posture (unchanged from v1 — P5 spec §B.7)
+ *
+ *   - **LLM ONLY via the E9 chokepoint.** The real generator
+ *     ({@link createLlmFixGenerator}) resolves its model strictly through
+ *     {@link "../llm/system-resolver.js".resolveLLMForSystem} → {@link ModelRunner}
+ *     (Gate-13). It constructs NO raw provider client, reads NO `*_API_KEY` env,
+ *     and hardcodes no model id — the resolver/registry is the SSoT. The
+ *     plaintext token is materialized only at the wire boundary (E10).
+ *   - **Draft-PR-ONLY, never auto-merge.** This module produces a PATCH FILE only;
+ *     the egress that consumes it always opens a `--draft` PR against a feature
+ *     branch (never `main`). This module performs NO git/gh action.
+ *   - **Graceful degrade, never a rogue mutation.** Every failure (no credential,
+ *     LLM error, empty / non-unified-diff output) returns a typed
+ *     {@link FixGenResult} of kind `'skipped'` and writes NO patch file — so the
+ *     existing egress guard (`existsSync` on the patch path) simply skips the PR.
+ *     This function NEVER throws.
+ *   - **Injectable seam.** The LLM dependency is the {@link FixGenerator} port;
+ *     unit tests inject a deterministic fake that returns a canned patch, so NO
+ *     real LLM is reached in tests.
+ *
+ * CORE-first: this engine lives in `core` and owns the `FixGenerator` port TYPE.
+ * Import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/fix-gen
+ * @epic T11889
+ * @task T11975
+ */
+import type { Logger } from 'pino';
+import type { DiffEntry } from './envelope-diff.js';
+/**
+ * The structured request handed to a {@link FixGenerator}. Carries only what the
+ * generator needs to draft a patch: the DHQ identity, the scenario, the
+ * regression diff, and a minimal slice of repo context.
+ */
+export interface FixGenRequest {
+    /** The stable `'DHQ-###'` handle of the open regression. */
+    readonly dhqId: string;
+    /** The scenario whose replay diverged from the golden. */
+    readonly scenario: string;
+    /** The idempotency hash tying this request to ONE open DHQ row. */
+    readonly questionHash: string;
+    /** The structured regression entries (the evidence) from the envelope diff. */
+    readonly regressions: readonly DiffEntry[];
+    /**
+     * Minimal repo context the generator may use to ground the patch (e.g. the
+     * project root, a short description). Kept small on purpose — the loop does NOT
+     * stuff the whole repo into the prompt.
+     */
+    readonly repoContext: FixGenRepoContext;
+}
+/** Minimal repo context grounding a fix-generation request. */
+export interface FixGenRepoContext {
+    /** Absolute project root the patch is generated against. */
+    readonly projectRoot: string;
+    /** Optional one-line summary of what the scenario exercises. */
+    readonly summary?: string;
+}
+/** A generated patch, or an explicit "no usable patch" signal. */
+export type FixGenOutput = {
+    /** The generator produced a candidate unified-diff patch. */
+    readonly kind: 'patch';
+    /** The raw unified-diff text (validated by {@link generateFixPatch}). */
+    readonly diff: string;
+    /** The model id that produced it (for audit). */
+    readonly model: string;
+} | {
+    /** The generator produced no usable patch (degrade — never an error throw). */
+    readonly kind: 'none';
+    /** Machine-stable reason for the absence. */
+    readonly reason: string;
+};
+/**
+ * The injectable fix-generation port (the LLM seam).
+ *
+ * The real implementation ({@link createLlmFixGenerator}) drives the E9 chokepoint;
+ * tests inject a deterministic fake returning a canned patch. A `FixGenerator`
+ * MUST NOT throw — it encodes "no patch" as `{ kind: 'none', reason }`.
+ */
+export interface FixGenerator {
+    /**
+     * Propose a unified-diff patch for one regression.
+     *
+     * @param request - The structured {@link FixGenRequest}.
+     * @returns A {@link FixGenOutput} — a candidate patch or an explicit "none".
+     */
+    propose(request: FixGenRequest): Promise<FixGenOutput>;
+}
+/** The terminal outcome of {@link generateFixPatch}. */
+export type FixGenResult = {
+    /** A validated patch was written to {@link FixGenResultWritten.patchPath}. */
+    readonly kind: 'written';
+    /** Absolute path the patch was written to. */
+    readonly patchPath: string;
+    /** Byte length of the written patch. */
+    readonly bytes: number;
+    /** The model id that produced the patch. */
+    readonly model: string;
+} | {
+    /** No patch was written; the egress guard will skip the PR. */
+    readonly kind: 'skipped';
+    /** Machine-stable reason recorded on the DHQ evidence. */
+    readonly reason: string;
+};
+/**
+ * Options for {@link generateFixPatch}.
+ */
+export interface GenerateFixPatchOptions {
+    /** The structured fix-generation request. */
+    readonly request: FixGenRequest;
+    /** The injected generator (real LLM impl or a test fake). */
+    readonly generator: FixGenerator;
+    /**
+     * Working directory the patch path is resolved against — MUST match the `cwd`
+     * the downstream {@link "./draft-pr.js".openDraftPr} uses, so the file it writes
+     * is the file the egress finds.
+     */
+    readonly cwd?: string;
+    /** Injectable logger (defaults to the module logger). */
+    readonly logger?: Logger;
+}
+/**
+ * Compute the patch path the draft-PR egress expects for a scenario:
+ * `<cwd>/selfimprove-<scenario>.patch`. The scenario is sanitized to a safe file
+ * stem so a hostile scenario name cannot escape the cwd.
+ *
+ * @param scenario - The scenario name.
+ * @param cwd - The working directory to resolve against (defaults to `process.cwd`).
+ * @returns The absolute patch path.
+ */
+export declare function fixPatchPath(scenario: string, cwd?: string): string;
+/**
+ * Is `text` a plausible unified diff?
+ *
+ * A real `git apply`-able patch always carries at least one of the canonical
+ * unified-diff markers ({@link UNIFIED_DIFF_MARKERS}). An LLM that returns prose,
+ * an apology, or an empty string fails this guard, so the loop degrades to "no
+ * patch" rather than writing junk the egress would then fail to `git apply`.
+ *
+ * This is a cheap structural sniff, NOT a full parse — the authoritative
+ * applicability check is `git apply` inside the egress (which fails the PR cut on
+ * a bad patch, never `main`).
+ *
+ * @param text - Candidate patch text.
+ * @returns `true` when the text looks like a unified diff.
+ */
+export declare function looksLikeUnifiedDiff(text: string): boolean;
+/**
+ * Build the system + user prompt the real generator sends to the LLM. Pure
+ * (no IO) so it is unit-testable in isolation. The prompt is deliberately strict:
+ * "respond with ONLY a unified diff" — anything else fails
+ * {@link looksLikeUnifiedDiff} downstream and degrades to "no patch".
+ *
+ * @param request - The fix-generation request.
+ * @returns The `{ system, user }` prompt pair.
+ */
+export declare function buildFixGenPrompt(request: FixGenRequest): {
+    system: string;
+    user: string;
+};
+/**
+ * Run the fix-generation stage: ask the injected {@link FixGenerator} for a patch,
+ * validate it as a unified diff, and write it to the egress-expected patch path.
+ *
+ * This function NEVER throws and NEVER mutates anything but the single patch file.
+ * On ANY degrade path — generator returns `'none'`, the generator throws, or the
+ * returned text is not a unified diff — it writes NO file and returns
+ * `{ kind: 'skipped', reason }`, so the downstream `existsSync` egress guard
+ * simply skips the PR. The caller records the `reason` on the DHQ evidence.
+ *
+ * @param opts - See {@link GenerateFixPatchOptions}.
+ * @returns A {@link FixGenResult}.
+ *
+ * @example
+ * ```ts
+ * const res = await generateFixPatch({
+ *   request: { dhqId: 'DHQ-abcd1234', scenario, questionHash, regressions, repoContext },
+ *   generator: createLlmFixGenerator(),
+ *   cwd: projectRoot,
+ * });
+ * if (res.kind === 'written') { // openDraftPr will now find selfimprove-<scenario>.patch }
+ * ```
+ */
+export declare function generateFixPatch(opts: GenerateFixPatchOptions): Promise<FixGenResult>;
+/**
+ * Construct the REAL fix generator — the one that drives the E9 LLM chokepoint.
+ *
+ * Resolution funnels through {@link resolveLLMForSystem}(`'task-executor'`) →
+ * {@link ModelRunner.build} → `session.send` (ONE non-streaming completion).
+ * It constructs NO raw provider client, reads NO API-key env, and hardcodes no
+ * model id (Gate-13). The plaintext credential is materialized ONLY at the
+ * `ModelRunner` wire boundary (E10) via the sealed handle. When no credential is
+ * reachable it returns `{ kind: 'none' }` — the loop degrades to "no patch", no
+ * PR. This function constructs nothing at call time (lazy dynamic imports keep the
+ * module import-time side-effect-free + the E9 deps off the hot import path).
+ *
+ * @param opts - Optional project root threaded into the resolver.
+ * @returns A {@link FixGenerator} backed by the E9 chokepoint.
+ *
+ * @example
+ * ```ts
+ * const gen = createLlmFixGenerator({ projectRoot });
+ * const out = await gen.propose(request); // resolves model via E9, never raw client
+ * ```
+ */
+export declare function createLlmFixGenerator(opts?: {
+    projectRoot?: string;
+}): FixGenerator;
+/**
+ * Strip a single surrounding markdown code fence (```diff … ```), if present, so a
+ * model that wraps its diff still yields an applyable patch. A bare diff passes
+ * through untouched.
+ *
+ * @param text - Candidate patch text (already trimmed).
+ * @returns The fence-stripped text.
+ */
+export declare function stripCodeFences(text: string): string;
+//# sourceMappingURL=fix-gen.d.ts.map

package/dist/selfimprove/fix-gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-gen.d.ts","sourceRoot":"","sources":["../../src/selfimprove/fix-gen.ts"],"names":[],"mappings":"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"}