@cat-factory/executor-harness 1.56.0 → 1.60.0

package/src/git.ts

@@ -648,6 +648,46 @@ export async function branchAheadOfBase(
   }
 }
 
+/**
+ * The files `commitish` changes relative to its merge base with the PR base branch — i.e.
+ * everything the work branch has added on top of base, `git diff --name-only <base>...<commitish>`.
+ *
+ * The BUGFIX REPRODUCTION PROOF uses this to answer the one question that decides whether a GREEN
+ * pre-fix tree means anything: does that tree ALREADY carry non-test work committed on this
+ * branch? A resumed run's `baseSha` is whatever the branch tip was when this pass started, which
+ * in the designed flow is the reproduction step's test commit — but after an eviction it is this
+ * same coder step's own interrupted work, fix included. Reporting "the check passed before your
+ * change, so it does not demonstrate the defect" in that case is simply false.
+ *
+ * `undefined` means "could not determine" (a shallow clone with no reachable merge base, a fetch
+ * failure, an unknown ref), never an empty list: the caller must degrade to its prior behaviour
+ * rather than read a failed probe as "the tree is clean".
+ *
+ * NUL-delimited so a path containing a newline (legal in git) cannot split into two entries.
+ */
+export async function changedFilesSinceBase(
+  dir: string,
+  baseBranch: string,
+  ghToken: string,
+  commitish: string,
+  signal?: AbortSignal,
+): Promise<string[] | undefined> {
+  try {
+    await git(['fetch', 'origin', `+refs/heads/${baseBranch}:refs/cat-factory/base`], {
+      cwd: dir,
+      signal,
+      env: await authEnv(ghToken),
+    })
+    const out = await git(['diff', '--name-only', '-z', `refs/cat-factory/base...${commitish}`], {
+      cwd: dir,
+      signal,
+    })
+    return out.split('\0').filter((p) => p !== '')
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Whether the checked-out branch has a real, examinable diff against
  * `origin/<baseBranch>` — i.e. the base branch's remote-tracking ref exists (so the
@@ -708,6 +748,99 @@ export async function headCommit(dir: string, signal?: AbortSignal): Promise<str
   return (await git(['rev-parse', 'HEAD'], { cwd: dir, signal })).trim()
 }
 
+/**
+ * Add a DETACHED worktree of `commitish` at `worktreePath`, sharing `dir`'s object database.
+ *
+ * The bugfix reproduction proof runs the declared check against two trees of the SAME clone (the
+ * pre-fix tree and the final tree), so a worktree is the only mechanism that gets both without a
+ * second clone, a second fetch, or disturbing the agent's own checkout — which must stay exactly
+ * as the agent left it, since the push and the PR come off it.
+ *
+ * `--detach` (rather than a branch) is deliberate: a worktree that claimed a branch would collide
+ * with the work branch checked out in `dir`, and nothing here ever commits.
+ *
+ * `worktreePath` is expected to live OUTSIDE the checkout (a per-job temp root), so the worktree's
+ * `.git` pointer file can never be swept into the agent's commit by a broad `git add -A`.
+ */
+export async function addWorktree(
+  dir: string,
+  worktreePath: string,
+  commitish: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  await git(['worktree', 'add', '--detach', worktreePath, commitish], { cwd: dir, signal })
+}
+
+/**
+ * Remove a worktree previously added by {@link addWorktree} and prune the stale administrative
+ * entry, never throwing: teardown is bookkeeping, and a run whose PROOF succeeded must not fail
+ * because a temp directory could not be cleaned up. The caller still deletes the temp root, so a
+ * failure here leaks only a `.git/worktrees/<name>` record inside a container that is about to be
+ * destroyed anyway.
+ */
+export async function removeWorktree(
+  dir: string,
+  worktreePath: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  try {
+    await git(['worktree', 'remove', '--force', worktreePath], { cwd: dir, signal })
+  } catch {
+    // Fall through to the prune, which cleans up the record even when the directory is gone.
+  }
+  try {
+    await git(['worktree', 'prune'], { cwd: dir, signal })
+  } catch {
+    // Best-effort by design (see the doc comment).
+  }
+}
+
+/**
+ * Which of `paths` actually exist in `commitish`'s tree. Used by the reproduction proof to tell a
+ * DECLARED test file that was committed from one that only ever existed as an untracked working-
+ * tree file: the proof runs against committed trees, so an unadded test is invisible to it — and
+ * equally invisible to the push, which is the point worth telling the agent about rather than
+ * reporting a verdict computed without the reproduction in it.
+ *
+ * Returns the input order/spelling of the paths that matched, so the caller can diff against its
+ * declared list to name the missing ones verbatim.
+ */
+export async function pathsPresentAtCommit(
+  dir: string,
+  commitish: string,
+  paths: readonly string[],
+  signal?: AbortSignal,
+): Promise<string[]> {
+  if (paths.length === 0) return []
+  const out = await git(['ls-tree', '-r', '--name-only', '-z', commitish, '--', ...paths], {
+    cwd: dir,
+    signal,
+  })
+  // NUL-delimited so a path containing a newline (legal in git) can't split into two entries.
+  const present = new Set(out.split('\0').filter((p) => p !== ''))
+  return paths.filter((p) => present.has(p))
+}
+
+/**
+ * Check `paths` out of `commitish` into `dir`'s working tree (and index), leaving every other file
+ * untouched.
+ *
+ * This is how the reproduction's declared TEST files are placed onto the pre-fix worktree, and the
+ * narrowness is the whole safety property: a whole-tree checkout would drag the FIX across too and
+ * green the base, manufacturing a "the test does not capture the defect" verdict out of a
+ * perfectly good reproduction. Only the paths the caller has already sanitized are passed, and
+ * `--` stops any of them being read as a revision.
+ */
+export async function checkoutPathsFrom(
+  dir: string,
+  commitish: string,
+  paths: readonly string[],
+  signal?: AbortSignal,
+): Promise<void> {
+  if (paths.length === 0) return
+  await git(['checkout', commitish, '--', ...paths], { cwd: dir, signal })
+}
+
 /** Stage everything and commit; returns false when there was nothing to commit. */
 export async function commitAll(
   dir: string,

package/src/job.ts

@@ -2,7 +2,16 @@ import type { HarnessCallMetric, PiRunStats } from './pi.js'
 import type { HarnessKind } from './pi-workspace.js'
 import type { FailureCause } from './failure.js'
 import type { EffortReport } from './effort.js'
-import type { ValidationChecksSpec, ValidationReport } from './validation-checks.js'
+import {
+  parseValidationChecksSpec,
+  type ValidationChecksSpec,
+  type ValidationReport,
+} from './validation-checks.js'
+import {
+  parseReproductionSpec,
+  type ReproductionReport,
+  type ReproductionSpec,
+} from './reproduction-proof.js'
 
 // The job the Worker's ContainerAgentExecutor POSTs to /run. Kept as plain
 // types with a hand-rolled validator so the image needs no schema dependency.
@@ -175,38 +184,6 @@ function parseValidationSpec(value: unknown): ValidationSpec | undefined {
   }
 }
 
-/**
- * Parse the optional PRE-PR VALIDATION CHECKS spec (see
- * docs/initiatives/pre-pr-validation.md): the service's ordered `{ label, command }` pairs and
- * the repair-round budget. Every entry needs a non-empty command; entries without one are
- * dropped, and a spec that ends up with no usable check returns `undefined` — so a malformed
- * body degrades to the exact pre-feature behaviour (no loop, PR opens as before) rather than
- * failing an otherwise-good coding run. `maxAttempts` is clamped to a sane range so a bad body
- * can't make a container loop forever.
- */
-function parseValidationChecksSpec(value: unknown): ValidationChecksSpec | undefined {
-  if (typeof value !== 'object' || value === null) return undefined
-  const o = value as Record<string, unknown>
-  if (!Array.isArray(o.checks)) return undefined
-  const checks: { label: string; command: string }[] = []
-  for (const raw of o.checks) {
-    if (typeof raw !== 'object' || raw === null) continue
-    const c = raw as Record<string, unknown>
-    if (typeof c.command !== 'string' || c.command.trim() === '') continue
-    const label = typeof c.label === 'string' && c.label.trim() ? c.label.trim() : c.command
-    checks.push({ label, command: c.command })
-  }
-  if (checks.length === 0) return undefined
-  const parsed = posInt(o.maxAttempts)
-  return {
-    checks,
-    maxAttempts: Math.min(
-      parsed ?? VALIDATION_DEFAULT_MAX_ATTEMPTS,
-      VALIDATION_MAX_ATTEMPTS_CEILING,
-    ),
-  }
-}
-
 /**
  * Parse the shared per-job auth fields, validating per harness: a subscription
  * harness (`claude-code` / `codex`) requires `subscriptionToken`; the default Pi
@@ -872,21 +849,18 @@ export interface AgentJob extends HarnessAuthFields {
    * job DATA, not the agent kind. See {@link ValidationChecksSpec}.
    */
   validationChecks?: ValidationChecksSpec
+  /**
+   * Coding mode: the run's BUGFIX REPRODUCTION PROOF — the declared reproduction command, the
+   * test file(s) that constitute it, and an optional setup command. When set, the harness runs
+   * that command against the pre-fix tree AND the tree the PR will open from, and reports both
+   * exit codes: only red-then-green is proof. Present only on a dispatch that opens a PR and
+   * whose run carries a reproduction declaration; absent ⇒ the run behaves exactly as before.
+   * Deliberately keyed off job DATA, not the agent kind. See
+   * `docs/initiatives/bugfix-reproduction-proof.md`.
+   */
+  reproduction?: ReproductionSpec
 }
 
-/**
- * The ceiling the harness clamps a body-supplied `validationChecks.maxAttempts` to, and the
- * default it applies when the body omits one.
- *
- * DELIBERATE DUPLICATES of `VALIDATION_MAX_ATTEMPTS_CEILING` / `VALIDATION_DEFAULT_MAX_ATTEMPTS`
- * in `@cat-factory/contracts` — the published image takes no schema dependency, so the harness
- * cannot import them. Keep the two in step: the API validates writes against the contracts
- * values, so a harness clamping to a DIFFERENT ceiling would silently cap a budget an operator
- * was allowed to save, with nothing to flag the mismatch.
- */
-export const VALIDATION_MAX_ATTEMPTS_CEILING = 10
-export const VALIDATION_DEFAULT_MAX_ATTEMPTS = 3
-
 /** Per-job, per-knob progress-guard overrides (see {@link AgentJob.guardLimits}). */
 export interface GuardLimitsSpec {
   maxToolCallsWithoutEdit?: number
@@ -938,6 +912,14 @@ export interface AgentResult {
    * Absent when the job carried no {@link AgentJob.validationChecks}.
    */
   validationReport?: ValidationReport
+  /**
+   * The BUGFIX REPRODUCTION PROOF: the declared reproduction command's verdict across the pre-fix
+   * tree and the final tree, computed by the harness from exit codes. Present on every outcome of
+   * a job that carried {@link AgentJob.reproduction} — a verdict is evidence, not a gate, so an
+   * `inconclusive` one accompanies the opened PR exactly like a `reproduced` one does. Absent
+   * when the job carried no reproduction declaration.
+   */
+  reproductionReport?: ReproductionReport
   /**
    * Preview mode: the in-container URL the built app is served at (e.g. `http://localhost:4173`).
    * This is NOT host-reachable on its own — the container runtime publishes the serve port to an
@@ -1345,6 +1327,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     guardLimits: parseGuardLimits(o.guardLimits),
     validation: parseValidationSpec(o.validation),
     validationChecks: parseValidationChecksSpec(o.validationChecks),
+    reproduction: parseReproductionSpec(o.reproduction),
     reviewPrNumber: posInt(o.reviewPrNumber),
   })
   assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl')
@@ -1383,6 +1366,7 @@ interface ParsedAgentJobParts {
   guardLimits: ReturnType<typeof parseGuardLimits>
   validation: ReturnType<typeof parseValidationSpec>
   validationChecks: ReturnType<typeof parseValidationChecksSpec>
+  reproduction: ReturnType<typeof parseReproductionSpec>
   reviewPrNumber: number | undefined
 }
 
@@ -1436,6 +1420,7 @@ function assembleAgentJob(
     guardLimits,
     validation,
     validationChecks,
+    reproduction,
     reviewPrNumber,
   } = parts
   const repo = (o.repo ?? {}) as Record<string, unknown>
@@ -1465,6 +1450,7 @@ function assembleAgentJob(
     ...(guardLimits ? { guardLimits } : {}),
     ...(validation ? { validation } : {}),
     ...(validationChecks ? { validationChecks } : {}),
+    ...(reproduction ? { reproduction } : {}),
   }
 }