@cat-factory/executor-harness 1.78.0 → 1.82.0

package/dist/process-exit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * How a child process ended: its own exit code, or the signal that killed it.
+ *
+ * @example describeProcessExit(1, null)          // 'exited with code 1'
+ * @example describeProcessExit(null, 'SIGKILL')  // 'killed by SIGKILL'
+ */
+export declare function describeProcessExit(code: number | null, signal: NodeJS.Signals | null): string;

package/dist/process.d.ts

@@ -0,0 +1,19 @@
+import type { ChildProcess } from 'node:child_process';
+import { type Logger } from './logger.js';
+/**
+ * Terminate a child process (and its group — see {@link signalTree}): SIGTERM first, then
+ * SIGKILL after a grace period if it hasn't exited (ignored an ordinary terminate). The
+ * escalation timer is `unref()`d so it never by itself keeps the event loop alive. Safe to
+ * call more than once.
+ *
+ * An actual escalation to SIGKILL is logged at warn level: a process that ignores
+ * SIGTERM and has to be force-killed is a signal worth seeing (a wedged Pi/CLI), and
+ * was previously invisible. Pass a child logger to carry the run's `jobId`.
+ */
+export declare function killChildProcess(child: ChildProcess, graceMs?: number, logger?: Logger): void;
+/**
+ * Whether a spawned agent CLI should be its own process-group leader so {@link killChildProcess}
+ * can reap the whole tree (its grandchildren) on abort. POSIX only; Windows has no process
+ * groups (and `detached` there spawns a new console we don't want), so it stays false.
+ */
+export declare const spawnDetached: boolean;

package/dist/progress-guard.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Tool-call signal read off a streamed Pi event, or undefined if not a tool call. Exported for
+ * `runPi`'s span emitter, which reads the same event for its per-tool trace spans.
+ */
+export declare function toolCallSignal(event: Record<string, unknown>): {
+    name: string;
+    isError: boolean;
+} | undefined;
+/** Tunable bounds for the {@link ProgressGuard}. */
+export interface ProgressGuardLimits {
+    /**
+     * Abort once the agent has made this many NON-exploration tool calls without ever
+     * using a file-editing tool (see `FILE_EDIT_TOOLS`). The signature of the credential
+     * rabbit-hole that motivated this: probing the environment (`bash`/exec) endlessly
+     * without implementing anything. Read-only exploration (`read`/`grep`/… — see
+     * `EXPLORATION_TOOLS`) and planning (`todo`) do NOT count, so a large task that
+     * legitimately reads/searches many files before its first edit is not killed for it.
+     * Disabled when `expectsEdits` is false (e.g. the assess-only merger / Blueprinter,
+     * which legitimately edit nothing). Note this bound only guards the run UNTIL its
+     * first edit: once the agent has edited a file at all, it has demonstrably started
+     * the work, so only `maxConsecutiveErrors` guards a later stall.
+     */
+    maxToolCallsWithoutEdit: number;
+    /**
+     * Abort after this many consecutive failing tool calls — the agent is stuck
+     * retrying an operation that keeps failing rather than making progress.
+     */
+    maxConsecutiveErrors: number;
+    /**
+     * Abort after this many consecutive web-search/web-fetch calls with no other tool
+     * call in between. Web tools are read-only exploration (they don't count toward the
+     * no-edit bound), so without this a model could rabbit-hole on searches indefinitely
+     * without ever tripping a guard. Any non-web tool call resets the streak. Optional:
+     * defaults to {@link DEFAULT_PROGRESS_GUARD_LIMITS} when a caller builds limits
+     * without it.
+     */
+    maxConsecutiveWebCalls?: number;
+}
+export declare const DEFAULT_PROGRESS_GUARD_LIMITS: {
+    maxToolCallsWithoutEdit: number;
+    maxConsecutiveErrors: number;
+    maxConsecutiveWebCalls: number;
+};
+/** Read {@link ProgressGuardLimits} from the environment, falling back to the defaults. */
+export declare function progressGuardLimitsFromEnv(env?: NodeJS.ProcessEnv): ProgressGuardLimits;
+/**
+ * Apply per-knob overrides onto a base set of guard limits, ENFORCING loosen-only: an
+ * override can only RAISE a knob (more headroom), never lower it below the base. A
+ * larger value is more lenient for every knob (more no-edit tool calls / errors / web
+ * calls tolerated), so each result is `max(base, override)`. This is a hard guarantee,
+ * not a convention — a tuning entry (built-in or a custom kind's, which reaches this via
+ * an untrusted job body) that supplies a value TIGHTER than the base is clamped back up
+ * to the base rather than aborting a legitimately-progressing run. An absent/undefined
+ * knob keeps the base value untouched.
+ */
+export declare function mergeGuardLimits(base: ProgressGuardLimits, overrides: Partial<ProgressGuardLimits> | undefined): ProgressGuardLimits;
+/**
+ * Live anti-rabbithole guard: fed each streamed Pi event, it returns a diagnostic
+ * reason the moment a run has plainly stopped making progress, so the harness can
+ * kill Pi early instead of letting it burn the whole budget (and then surface a
+ * useful failure instead of a generic "no file changes"). Pure and incremental so
+ * it can be unit-tested over a fixed event sequence.
+ */
+export declare class ProgressGuard {
+    private readonly limits;
+    /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
+    private readonly expectsEdits;
+    private toolCalls;
+    private edits;
+    private consecutiveErrors;
+    private consecutiveWebCalls;
+    constructor(limits: ProgressGuardLimits, 
+    /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
+    expectsEdits?: boolean);
+    /** Feed one parsed Pi event; returns a diagnostic reason when the run should abort, else null. */
+    observe(event: Record<string, unknown>): string | null;
+    /**
+     * Feed one already-parsed tool-call signal (name + error flag), returning a diagnostic reason
+     * when the run should abort, else null. Split out of {@link observe} so a caller whose stream
+     * is NOT Pi's `tool_execution_end` envelope — the claude-code runner, which correlates a
+     * `tool_use` block's name with its `tool_result`'s `is_error` — can drive the SAME guard logic
+     * without synthesising a fake Pi event.
+     */
+    observeSignal(tool: {
+        name: string;
+        isError: boolean;
+    }): string | null;
+}

package/dist/progress.d.ts

@@ -0,0 +1,87 @@
+import type { TodoProgress } from './pi.js';
+/** Statuses a plan entry can carry; anything unrecognised is treated as not-yet-started. */
+export declare function normalizeStatus(status: unknown): 'pending' | 'in_progress' | 'completed';
+/** Roll a label+status list up into the counts the board renders. Shared by every plan shape. */
+export declare function toProgress(items: {
+    label: string;
+    status: ReturnType<typeof normalizeStatus>;
+}[]): {
+    completed: number;
+    inProgress: number;
+    total: number;
+    items: {
+        label: string;
+        status: ReturnType<typeof normalizeStatus>;
+    }[];
+};
+/** Map a `TodoWrite` call's `todos` array onto subtask counts. Each call is a full snapshot. */
+export declare function todosToProgress(todos: unknown): TodoProgress | undefined;
+/**
+ * The id the CLI assigned to a just-created task, read from `TaskCreate`'s tool RESULT.
+ *
+ * `TaskCreate`'s INPUT carries only `{subject, description}` — the id is minted by the CLI and
+ * comes back on the result, so pairing a later `TaskUpdate({taskId})` to the task it created
+ * requires reading the result text. The CLI's shipped `TaskCreateOutput` is
+ * `{task: {id, subject}}`, but the parent stream's `tool_result` block carries the rendered
+ * STRING (`"Task #1 created successfully: <subject>"`), so both shapes are accepted.
+ */
+export declare function parseCreatedTaskId(content: unknown): string | undefined;
+/**
+ * Tracks the parent's incremental `TaskCreate` / `TaskUpdate` plan.
+ *
+ * A `TaskCreate` is registered as pending against its tool_use id, then bound to the CLI-assigned
+ * task id when its result arrives; `TaskUpdate` moves the bound task. A create whose result is
+ * never seen (or whose id can't be parsed) still counts toward `total` under a synthetic key, so
+ * the plan size stays honest even when the pairing fails — it simply can never advance.
+ *
+ * `deleted` tombstones are dropped from the list entirely (matching `TodoWrite`'s live-tasks-only
+ * shape), so a task the agent abandons doesn't hold the bar back forever.
+ */
+export interface TaskPlanTracker {
+    /** Feed an `assistant` message's content blocks: registers creates + applies updates. */
+    onAssistant(content: unknown[]): void;
+    /** Feed a `user` message's content blocks: binds each create to its CLI-assigned task id. */
+    onUser(content: unknown[]): void;
+    /** The plan as progress counts, or undefined when nothing has been planned yet. */
+    progress(): TodoProgress | undefined;
+}
+export declare function createTaskPlanTracker(): TaskPlanTracker;
+/**
+ * Reconcile the parent's TWO plan vocabularies (`TodoWrite` snapshots vs the incremental
+ * `TaskCreate`/`TaskUpdate` pair) into one plan. A run uses one or the other, so this is a
+ * genuine either/or: prefer whichever is further along — more `completed`, then more
+ * `inProgress`, then more `total` — else the `TodoWrite` view. Pure + total; returns whichever
+ * single input is present when only one is.
+ *
+ * This is NOT how the plan reconciles with the parallel-subagent view — those describe the same
+ * slices from two angles and are MERGED, see {@link mergeProgress}.
+ */
+export declare function pickProgress(todo: TodoProgress | undefined, slice: TodoProgress | undefined): TodoProgress | undefined;
+/**
+ * A slice label reduced to its identifying words, for pairing a plan entry with the subagent
+ * dispatched to review it. Case, punctuation and the boilerplate around the slice name all
+ * differ between the two vocabularies; the slice NAME does not.
+ */
+export declare function sliceLabelKey(label: string): string;
+/**
+ * MERGE the parent's plan with the `SliceTracker`'s subagent-dispatch view into the single list
+ * the board renders (ADR 0027 Defect B, corrected).
+ *
+ * The two are not competing answers, they are two halves of one: the plan is the INVENTORY (it
+ * names every slice, including the ones not dispatched yet, which is the only place a `pending`
+ * slice exists at all), and the dispatch view is the live STATUS (the plan advances only when
+ * the agent remembers to update it, which it does unreliably). Picking whichever looked "further
+ * along" — the previous behaviour — made the rendered list SHRINK the moment the first subagent
+ * returned: the dispatch view won on `completed`, and it only knows the slices dispatched so far,
+ * so every queued slice vanished from the window and reappeared one at a time as it was dispatched.
+ *
+ * Pairing is by normalised label ({@link sliceLabelKey}) — exact first, then containment — and
+ * finally positionally into the leftover pending entries, in dispatch order (the agent dispatches
+ * in plan order). A dispatch that pairs with nothing is APPENDED rather than dropped, so the list
+ * is at worst a union and can never lose a slice. Statuses only ever advance, so a plan entry the
+ * agent already marked done is not walked back by a re-dispatch.
+ *
+ * Pure + total. Falls back to {@link pickProgress} when either side carries counts but no items
+ * (nothing to merge onto).
+ */
+export declare function mergeProgress(plan: TodoProgress | undefined, slice: TodoProgress | undefined): TodoProgress | undefined;

package/dist/redact.d.ts

@@ -0,0 +1,31 @@
+/** Register known secret values to scrub on every subsequent redaction. */
+export declare function registerKnownSecrets(values: readonly string[]): void;
+/**
+ * Strip credentials out of any string before it is logged or stored. Applies the
+ * pattern rules (URL userinfo `https://user:pass@host`, `x-access-token:<token>`, bare
+ * `ghs_`/`ghp_`/`gho_`/`github_pat_` shapes, and credential-named `KEY=value` / `KEY:
+ * value` assignments) and then scrubs every supplied known-secret value plus the
+ * module-registered ones ({@link registerKnownSecrets}). Idempotent — safe to call on
+ * already-redacted text.
+ */
+export declare function redact(input: string, knownSecrets?: readonly string[]): string;
+/** Pattern + registered-value redaction. Kept for callers without a per-call secret list. */
+export declare function redactSecrets(input: string): string;
+/** Cap on captured command output kept on an infra record (tail-biased — failures show last). */
+export declare const MAX_CAPTURED_OUTPUT_CHARS = 16000;
+/**
+ * Combine, redact and tail-bound captured stdout+stderr into a single stored string. Keeps
+ * the LAST {@link MAX_CAPTURED_OUTPUT_CHARS} (where a failure's error lives), prefixed with a
+ * truncation marker when trimmed. Returns undefined for empty output so a record stays sparse.
+ * Shared by the docker-compose and the frontend UI-test stand-ups.
+ */
+export declare function captureRedactedOutput(stdout: unknown, stderr: unknown): string | undefined;
+/**
+ * The set of secret strings to scrub from a run's stderr/output. For Claude (and the
+ * Anthropic-compatible vendors GLM/Kimi/DeepSeek) the credential IS the token string,
+ * so the whole-string entry covers it. For Codex the credential is a whole `auth.json`
+ * blob, so we ALSO scrub every string value parsed out of it (access/refresh tokens,
+ * ids): a token echoed on its OWN — not as part of the whole blob — would otherwise
+ * slip past a whole-blob-only match and leak into an error message.
+ */
+export declare function secretsToRedact(subscriptionToken: string): string[];

package/dist/reproduction-proof.d.ts

@@ -0,0 +1,224 @@
+import type { RunOptions } from './runner.js';
+import type { Logger } from './logger.js';
+/** The reproduction spec as it arrives on the job body. */
+export interface ReproductionSpec {
+    /** The command that runs EXACTLY the declared reproduction test(s), as `sh -c` in the checkout. */
+    command: string;
+    /** The test file(s) that constitute the reproduction (repo-relative, already sanitized). */
+    testPaths: string[];
+    /**
+     * How many declared paths the ENGINE dropped while resolving this spec (over the cap, absolute,
+     * traversing, over-long). Echoed onto the report unchanged: a dropped path can leave the base
+     * tree without the reproduction, which greens it and reads as "the test does not capture the
+     * defect", so the omission has to travel with the verdict rather than being implied by it.
+     */
+    omittedTestPaths?: number;
+    /** Optional command that makes a FRESH worktree runnable (a dependency install). */
+    setupCommand?: string;
+    /** How many agent+verify rounds the loop may run before it settles for `inconclusive`. */
+    maxAttempts: number;
+}
+/** One tree's run of the reproduction command. */
+export interface ReproductionPhaseOutcome {
+    /** Exit code (0 = pass); 124 on watchdog timeout, 127 on spawn failure, 130 on abort. */
+    exitCode: number;
+    passed: boolean;
+    /** Bounded, secret-scrubbed tail of the command's combined stdout+stderr. */
+    outputTail?: string;
+    durationMs?: number;
+    timedOut?: boolean;
+    /** Set when THIS phase's setup command failed, so the tree never ran the check meaningfully. */
+    setupFailed?: boolean;
+}
+/** The harness-computed reproduction report — what crosses the wire onto the step. */
+export interface ReproductionReport {
+    /**
+     * `reproduced` — RED on the pre-fix tree, GREEN on the final tree (the only shape that is
+     * proof); `inconclusive` — every other shape, recorded honestly rather than dressed up. The
+     * harness never emits `declared_infeasible`: a conceded run dispatches no proof at all, so the
+     * ENGINE mints that one from the declaration itself.
+     */
+    status: 'reproduced' | 'inconclusive';
+    command: string;
+    testPaths: string[];
+    omittedTestPaths?: number;
+    base?: ReproductionPhaseOutcome;
+    /** Absent when the base run settled the verdict (a green or un-runnable base). */
+    final?: ReproductionPhaseOutcome;
+    attempts: number;
+    maxAttempts: number;
+    /** For `inconclusive`: which shape was observed, in one line, for the report and the step card. */
+    note?: string;
+    at: number;
+}
+/**
+ * Per-phase output kept on the REPORT (what crosses the wire and lands in the run's persisted
+ * `detail` blob). Deliberately smaller than `MAX_CAPTURED_OUTPUT_CHARS` (`redact.ts`), which is
+ * what the AGENT sees in its repair prompt — the same split, for the same reasons, as the pre-PR
+ * validation report's tail (`validation-checks.ts`).
+ */
+export declare const REPRODUCTION_REPORT_TAIL_CHARS = 4000;
+/**
+ * The ceiling the harness clamps a body-supplied `reproduction.maxAttempts` to, and the default it
+ * applies when the body omits one.
+ *
+ * DELIBERATE DUPLICATES of `REPRODUCTION_DEFAULT_MAX_ATTEMPTS` in `@cat-factory/contracts` (and of
+ * the validation loop's own ceiling) — the published image takes no schema dependency, so the
+ * harness cannot import them. Keep them in step: a harness clamping to a DIFFERENT ceiling would
+ * silently cap a budget the engine was allowed to send, with nothing to flag the mismatch.
+ */
+export declare const REPRODUCTION_DEFAULT_MAX_ATTEMPTS = 3;
+export declare const REPRODUCTION_MAX_ATTEMPTS_CEILING = 10;
+/**
+ * The per-command watchdog: the longest a single setup or check command may run before it is
+ * killed and treated as a failure, so one hung test command cannot wedge a run. Overridable via
+ * env for tests; defaults to 15 minutes, matching the validation loop's.
+ */
+export declare function reproductionCommandTimeoutMs(): number;
+/**
+ * How often the proof feeds the run's inactivity watchdog. Well under the harness's own
+ * `JOB_INACTIVITY_MS` (default 10 min) so a slow install-plus-test in each of two worktrees can
+ * never look wedged. This is NOT optional: the job-level watchdog is TIGHTER than one command's
+ * own ({@link reproductionCommandTimeoutMs}, 15 min), and the harness spawns these itself rather
+ * than through the agent, so they emit no activity of their own — without the heartbeat a
+ * legitimately slow proof aborts the entire run as "inactivity" and the per-command timeout is
+ * unreachable at stock settings.
+ */
+export declare function reproductionHeartbeatMs(): number;
+/**
+ * The ceiling on the WHOLE proof phase — every attempt, both trees, setup included. Overridable
+ * via env; defaults to 45 minutes.
+ *
+ * The per-command watchdog bounds one command, not the phase, and the phase multiplies: a spent
+ * budget is `maxAttempts` × two trees × (setup + check), each of which may legitimately run for
+ * {@link reproductionCommandTimeoutMs}. At stock settings that is hours of container time spent
+ * BEFORE the pre-PR validation loop has run its own rounds, and nothing else stops it — the
+ * heartbeat deliberately keeps the job-level inactivity watchdog from firing, which is exactly
+ * what removes the accidental backstop the phase would otherwise have had.
+ *
+ * Enforced at PHASE boundaries (before each tree's run, and before each repair round) rather than
+ * mid-command: a command already carries its own watchdog, so the real bound is this budget plus
+ * at most one command's timeout. Exceeding it settles `inconclusive` with a note saying so —
+ * never a run failure, exactly like every other unproven shape.
+ */
+export declare function reproductionTotalBudgetMs(): number;
+/**
+ * Parse the job body's `reproduction` envelope, or `undefined` for "no proof on this job".
+ *
+ * Lenient in exactly one direction: anything malformed yields `undefined`, so the run behaves
+ * byte-for-byte as it did before this feature existed. A body that names no command has nothing
+ * to run, and inventing one would manufacture a verdict. Test paths are re-checked here even
+ * though the engine already sanitized them — this is the harness's own trust boundary, and these
+ * paths are handed to `git checkout` against a worktree.
+ */
+export declare function parseReproductionSpec(value: unknown): ReproductionSpec | undefined;
+/** Everything one proof attempt needs. Every field is per-job; nothing is read from a global. */
+export interface ReproductionProofArgs {
+    /** The agent's own checkout — the worktrees' parent clone. Never modified by the proof. */
+    dir: string;
+    /** The pre-fix tree: the branch tip captured BEFORE this pass ran (never `HEAD~1`/a base ref). */
+    baseSha: string;
+    /** The tree the pull request will open from (the checkout's HEAD, after committing). */
+    finalSha: string;
+    /** In a monorepo, the service subdirectory the commands run in (relative to each worktree). */
+    serviceDirectory?: string;
+    spec: ReproductionSpec;
+    attempt: number;
+    logger: Logger;
+    opts: RunOptions;
+    /** Epoch ms after which no further phase may START (see {@link reproductionTotalBudgetMs}). */
+    deadlineAt?: number;
+    /**
+     * The files the PRE-FIX tree already changes relative to the PR base branch, or `undefined`
+     * when that could not be determined. Consulted ONLY when the base tree comes back green — see
+     * {@link priorWorkAtBase} for why a green base is otherwise misdiagnosed.
+     */
+    listBaseTreeChanges?: () => Promise<string[] | undefined>;
+}
+/** One proof attempt: the report, the full tails for a repair prompt, and whether to repair. */
+export interface ReproductionAttempt {
+    report: ReproductionReport;
+    fullTails: Map<string, string>;
+    /**
+     * Whether spending an agent repair round on this outcome can plausibly change it. An explicit
+     * OUTPUT of the attempt rather than something re-derived from the report, because the two
+     * unrepairable shapes are known only here: a broken environment (the agent cannot change a
+     * setup command it did not declare) and a pre-fix tree that already carries this run's own
+     * earlier work (nothing is wrong with the test, so "make it exercise the defect" is bad advice).
+     */
+    repairable: boolean;
+}
+/**
+ * Run ONE proof attempt: create both worktrees, run the declared check in each, and compute the
+ * verdict from the two exit codes.
+ *
+ * The base worktree is built at `baseSha` and then has the DECLARED test files checked out of
+ * `finalSha` on top — the paths only, never a whole-tree checkout, which would drag the fix across
+ * and green the base. In the RESUMED case (a prior `repro-test` step already pushed the failing
+ * test onto the shared work branch, so `baseSha` already carries it) that overlay is a no-op by
+ * construction. Doing it unconditionally is what guarantees BOTH trees run the byte-identical
+ * check, which is the claim the report makes.
+ *
+ * Keeps the run's inactivity watchdog fed for the whole attempt (see
+ * {@link reproductionHeartbeatMs}) and always tears both worktrees down, including on a throw.
+ */
+export declare function runReproductionProof(args: ReproductionProofArgs): Promise<ReproductionAttempt>;
+/**
+ * The repair instruction handed to the agent after a failed verification: which tree behaved how,
+ * the captured output, and an explicit statement of the exit condition. The FULL captured tail is
+ * used here (not the report's smaller bound) — the agent needs the whole failure to act on it, and
+ * this text never leaves the container.
+ *
+ * Deliberately prescriptive about scope, for the same reason the validation loop's prompt is: a
+ * loop that lets the agent "succeed" by weakening the reproduction is worse than no loop at all,
+ * because it launders an unverified claim into a captured "fact" — the exact failure mode this
+ * whole feature exists to remove.
+ */
+export declare function buildReproductionRepairPrompt(report: ReproductionReport, fullTails: Map<string, string>, 
+/**
+ * New files the agent created but never `git add`ed, if the caller can tell. The proof runs
+ * against COMMITTED trees, so an unadded reproduction test is invisible to it — and to the push.
+ */
+untrackedFiles?: string[]): string;
+/**
+ * The reproduction-proof LOOP: verify, and while the verification fails, is repairable and budget
+ * remains, hand the captured output back to the agent as its next instruction and verify again.
+ * Returns the LAST attempt's report.
+ *
+ * A failed verification is a REPAIR, never a run failure (the initiative's D6). Exhausting the
+ * budget degrades to `inconclusive` and the caller opens the pull request anyway — deliberately a
+ * different disposition from the pre-PR validation loop, which opens nothing. A red validation
+ * check means the WORK is broken, so refusing the PR is right; a reproduction that could not be
+ * demonstrated means the EVIDENCE is weak, which is a reviewer's call, not a machine's, and
+ * failing the run would throw away a fix that may well be correct. The report says plainly what
+ * was and was not proven.
+ *
+ * Every settled attempt — including the ones that never ran a tree — is published on the job view
+ * (a fresh `at` per publish, which the engine's change detection relies on), so the loop is
+ * observable while it runs; `onAgentPass` lets the caller fold each repair pass's
+ * stats/usage/telemetry into the run's totals.
+ *
+ * The loop is bounded twice over: by `maxAttempts` rounds, and by the wall-clock
+ * {@link reproductionTotalBudgetMs} — attempts multiply two full tree runs each, and the phase's
+ * own heartbeat deliberately stops the job-level inactivity watchdog from ever cutting it short.
+ */
+export declare function runReproductionLoop<TRun>(args: {
+    dir: string;
+    baseSha: string;
+    /** Re-read before every attempt: a repair pass commits, so the final tree moves. */
+    resolveFinalSha: () => Promise<string>;
+    serviceDirectory?: string;
+    spec: ReproductionSpec;
+    logger: Logger;
+    opts: RunOptions;
+    runAgentPass: (userPrompt: string) => Promise<TRun>;
+    onAgentPass?: (run: TRun) => void;
+    /** The new files left uncommitted in the checkout, folded into each repair prompt. */
+    listUncommittedNewFiles?: () => Promise<string[]>;
+    /**
+     * The files the PRE-FIX tree already changes relative to the PR base branch (see
+     * `priorWorkAtBase`). Invariant across attempts — `baseSha` never moves — so it is resolved at
+     * most once and memoised here rather than re-probed per round.
+     */
+    listBaseTreeChanges?: () => Promise<string[] | undefined>;
+}): Promise<ReproductionReport>;