@cleocode/core 2026.6.14 → 2026.6.17

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":"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"}
+{"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-context.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Bounded file-content loader for the fix-gen stage (T11988).
+ *
+ * The self-improvement fix-gen stage builds a prompt for the LLM
+ * ({@link "./fix-gen.js".buildFixGenPrompt}). Without file context the model
+ * can only see the regression diff entries (e.g.
+ * `op tasks.show (#0) at data/task/status: actual="pending" expected="active"`)
+ * and rationally responds `NO_PATCH` because it cannot locate the responsible code.
+ *
+ * This module resolves the relevant source files for each regressing op-coordinate
+ * via the static map ({@link "./op-source-map.js"}) and reads their content with a
+ * **hard context budget** so the prompt stays bounded regardless of file size.
+ *
+ * ## Budget model
+ *
+ * Two independent byte-level caps:
+ *
+ *   - `perFileBudget` (default {@link DEFAULT_PER_FILE_BUDGET}): the maximum bytes
+ *     read from any single file. Files larger than this are truncated at a
+ *     newline boundary and a `<… TRUNCATED …>` marker is appended.
+ *   - `totalBudget` (default {@link DEFAULT_TOTAL_BUDGET}): the maximum total bytes
+ *     across ALL included files. Files are added in order (handler files first, then
+ *     core files); once the total would be exceeded the remaining files are
+ *     summarised as a path-only `<file listed but not loaded — budget exhausted>` stub.
+ *
+ * The caller embeds the resolved {@link LoadedFileContext} into the prompt. The LLM
+ * prompt builder ({@link "./fix-gen.js".buildFixGenPrompt}) inserts the file blocks
+ * between the regression description and the "produce the diff" instruction, giving
+ * the model concrete code to work from.
+ *
+ * Import-time side-effect-free: no logger init, no native handles.
+ *
+ * @module @cleocode/core/selfimprove/fix-gen-context
+ * @epic T11889
+ * @task T11988
+ */
+/**
+ * Per-file byte cap (default): any single file is truncated to at most 24 KB
+ * before being included in the prompt. Chosen to comfortably fit a large-ish
+ * handler or core module without overwhelming the model context.
+ */
+export declare const DEFAULT_PER_FILE_BUDGET = 24576;
+/**
+ * Total byte cap (default): the combined content of all included files must not
+ * exceed 65 KB. Keeps the combined code context section to a model-digestible
+ * slice of the context window even when multiple files are included.
+ */
+export declare const DEFAULT_TOTAL_BUDGET = 65536;
+/** Options for {@link loadFileContext}. */
+export interface LoadFileContextOptions {
+    /**
+     * Absolute project root. Source files are resolved relative to this path.
+     * Must be set to the actual repo root for the paths from the op-source-map
+     * to resolve correctly.
+     */
+    readonly projectRoot: string;
+    /**
+     * The op-coordinates whose source files should be loaded (e.g. `['tasks.show']`).
+     * Resolved via {@link collectOpSourceFiles}.
+     */
+    readonly opCoords: readonly string[];
+    /**
+     * Per-file byte budget (defaults to {@link DEFAULT_PER_FILE_BUDGET}).
+     * Files exceeding this are truncated with a `<… TRUNCATED …>` marker.
+     */
+    readonly perFileBudget?: number;
+    /**
+     * Total byte budget for all files combined
+     * (defaults to {@link DEFAULT_TOTAL_BUDGET}).
+     * Files whose content would push the total over budget are listed but not
+     * loaded (their path is emitted as a stub).
+     */
+    readonly totalBudget?: number;
+}
+/** A single file included in the context (content loaded or stubbed). */
+export interface FileContextEntry {
+    /** Repo-relative path (as returned by the op-source-map). */
+    readonly repoRelativePath: string;
+    /**
+     * File content (possibly truncated if `truncated` is `true`). `null` when the
+     * file was skipped due to the total budget being exhausted or a read error.
+     */
+    readonly content: string | null;
+    /**
+     * `true` when the file was truncated at the per-file budget; the loaded
+     * `content` ends with a `<… TRUNCATED …>` marker.
+     */
+    readonly truncated: boolean;
+    /**
+     * `true` when the total budget was exhausted before this file was loaded. The
+     * file appears in the context list but its `content` is `null`.
+     */
+    readonly budgetExhausted: boolean;
+    /**
+     * `true` when the file could not be read (missing, permission error, etc.).
+     * The file appears in the context list with `content: null`.
+     */
+    readonly readError: boolean;
+}
+/** Resolved file context for a set of op-coordinates. */
+export interface LoadedFileContext {
+    /** The resolved file entries (handler files first, then core files). */
+    readonly entries: readonly FileContextEntry[];
+    /** Total bytes of loaded content (across all non-skipped entries). */
+    readonly totalBytes: number;
+    /** Number of files that were truncated due to the per-file budget. */
+    readonly truncatedCount: number;
+    /** Number of files that were skipped due to the total budget. */
+    readonly budgetSkippedCount: number;
+    /** Number of files that could not be read. */
+    readonly errorCount: number;
+}
+/**
+ * Truncate `content` to at most `maxBytes` bytes, cutting at a newline boundary
+ * wherever possible, and appending a marker.
+ *
+ * Operates on raw bytes via `Buffer` so multi-byte characters don't produce
+ * partial surrogate pairs in the truncated output.
+ *
+ * @param content - The full file content string.
+ * @param maxBytes - The per-file byte cap.
+ * @returns `{ text, truncated }` — the (possibly shortened) string and a flag.
+ * @internal
+ */
+export declare function truncateToByteLimit(content: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Load bounded file content for the op-coordinates in a fix-gen request.
+ *
+ * Resolves the handler + core files for each `opCoord` via
+ * {@link collectOpSourceFiles}, reads them against `projectRoot`, applies the
+ * per-file and total byte budgets, and returns a structured
+ * {@link LoadedFileContext} describing every entry (loaded, truncated, skipped, or
+ * errored). NEVER throws — read errors produce `{ content: null, readError: true }`.
+ *
+ * @param opts - See {@link LoadFileContextOptions}.
+ * @returns The resolved {@link LoadedFileContext}.
+ *
+ * @example
+ * ```ts
+ * const ctx = loadFileContext({
+ *   projectRoot: '/repo',
+ *   opCoords: ['tasks.show'],
+ * });
+ * // ctx.entries[0].repoRelativePath  === 'packages/cleo/src/dispatch/domains/tasks.ts'
+ * // ctx.entries[1].repoRelativePath  === 'packages/core/src/tasks/show.ts'
+ * // ctx.totalBytes                   <= DEFAULT_TOTAL_BUDGET
+ * ```
+ */
+export declare function loadFileContext(opts: LoadFileContextOptions): LoadedFileContext;
+/**
+ * Render a {@link LoadedFileContext} as the file-context section of a fix-gen
+ * prompt.
+ *
+ * Produces a human-readable block listing each file with its content (or a stub
+ * explaining why the content was omitted). Suitable for direct embedding in the
+ * LLM user-turn after the regression description.
+ *
+ * @param ctx - The loaded file context.
+ * @returns A string ready for embedding in the prompt (empty string when no files).
+ *
+ * @example
+ * ```ts
+ * const section = renderFileContextSection(ctx);
+ * // --- packages/core/src/tasks/show.ts ---
+ * // <content or stub>
+ * ```
+ */
+export declare function renderFileContextSection(ctx: LoadedFileContext): string;
+//# sourceMappingURL=fix-gen-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fix-gen-context.d.ts","sourceRoot":"","sources":["../../src/selfimprove/fix-gen-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAQH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAI3C,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAatC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CAmF/E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAgBvE"}