@cat-factory/executor-harness 1.54.0 → 1.58.0

package/src/job.ts

@@ -2,6 +2,7 @@ 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'
 
 // 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.
@@ -174,6 +175,38 @@ 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
@@ -831,8 +864,29 @@ export interface AgentJob extends HarnessAuthFields {
    * agent commits + pushes. Present only for a `ralph` iteration. See {@link ValidationSpec}.
    */
   validation?: ValidationSpec
+  /**
+   * Coding mode: the service's PRE-PR VALIDATION CHECKS — commands the harness runs against the
+   * checkout after the agent settles and BEFORE opening a PR, feeding a failure back to the agent
+   * until they pass or the budget is spent. Present only on a dispatch that opens a PR and whose
+   * service configured checks; absent ⇒ the run behaves exactly as before. Deliberately keyed off
+   * job DATA, not the agent kind. See {@link ValidationChecksSpec}.
+   */
+  validationChecks?: ValidationChecksSpec
 }
 
+/**
+ * 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
@@ -876,6 +930,14 @@ export interface AgentResult {
    * — the failure-class artifact the orchestrator-side provisioning logs can't capture.
    */
   infraSetup?: InfraSetupRecord
+  /**
+   * The PRE-PR VALIDATION report: the outcome of running the service's configured check commands
+   * against the checkout after the agent settled and before opening a PR, plus how many repair
+   * rounds the harness spent. Present on BOTH outcomes — a passing report accompanies the opened
+   * PR (the captured proof), and a failing one accompanies the run's `error` (no PR was opened).
+   * Absent when the job carried no {@link AgentJob.validationChecks}.
+   */
+  validationReport?: ValidationReport
   /**
    * 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
@@ -1282,6 +1344,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     testSecrets: parseTestSecrets(o.testSecrets),
     guardLimits: parseGuardLimits(o.guardLimits),
     validation: parseValidationSpec(o.validation),
+    validationChecks: parseValidationChecksSpec(o.validationChecks),
     reviewPrNumber: posInt(o.reviewPrNumber),
   })
   assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl')
@@ -1319,6 +1382,7 @@ interface ParsedAgentJobParts {
   testSecrets: ReturnType<typeof parseTestSecrets>
   guardLimits: ReturnType<typeof parseGuardLimits>
   validation: ReturnType<typeof parseValidationSpec>
+  validationChecks: ReturnType<typeof parseValidationChecksSpec>
   reviewPrNumber: number | undefined
 }
 
@@ -1371,6 +1435,7 @@ function assembleAgentJob(
     testSecrets,
     guardLimits,
     validation,
+    validationChecks,
     reviewPrNumber,
   } = parts
   const repo = (o.repo ?? {}) as Record<string, unknown>
@@ -1399,6 +1464,7 @@ function assembleAgentJob(
     ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
     ...(guardLimits ? { guardLimits } : {}),
     ...(validation ? { validation } : {}),
+    ...(validationChecks ? { validationChecks } : {}),
   }
 }
 

package/src/runner.ts

@@ -1,5 +1,6 @@
 import { redactSecrets } from './redact.js'
 import type { FollowUpLine } from './follow-ups.js'
+import type { ValidationReport } from './validation-checks.js'
 import type { HarnessCallMetric, TodoProgress, ToolSpan } from './pi.js'
 import { log, type Logger } from './logger.js'
 import {
@@ -30,6 +31,13 @@ export interface RunOptions {
   onSpan?: (span: ToolSpan) => void
   /** Receives the forward-looking follow-up / question items the Coder streamed since the last poll. */
   onFollowUp?: (items: FollowUpLine[]) => void
+  /**
+   * Receives each completed PRE-PR VALIDATION attempt the moment the harness finishes running
+   * the service's check commands, so the backend can surface the repair loop LIVE ("lint failed,
+   * repairing — attempt 2 of 3") instead of only in the terminal result. Latest-wins (NOT a drain
+   * buffer): a published attempt is final, and the loop republishes a whole new one per round.
+   */
+  onValidationReport?: (report: ValidationReport) => void
   /**
    * Receives each per-call telemetry row the moment the agent's CLI stream yields it, so a
    * run's model calls reach `llm_call_metrics` WHILE it runs rather than only in its terminal
@@ -162,6 +170,13 @@ export interface JobView<TResult extends JobResultBase = JobResultBase> {
    * Absent on a job that produced output promptly (the overwhelming common case). Sticky once set.
    */
   coldStart?: { atMs: number; message: string }
+  /**
+   * The LATEST completed pre-PR validation attempt (see `docs/initiatives/pre-pr-validation.md`).
+   * Unlike {@link spans}/{@link followUps} this is NOT drain-on-read: it is a whole-value latest
+   * publish, so re-reading it on a later poll is harmless and a dropped poll loses nothing (the
+   * next round republishes). Absent for a job whose service configured no checks.
+   */
+  validationReport?: ValidationReport
 }
 
 interface JobEntry<TResult extends JobResultBase> extends JobView<TResult> {
@@ -425,6 +440,9 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
         onFollowUp: (items) => {
           entry.followUpBuffer.push(...items)
         },
+        onValidationReport: (report) => {
+          entry.validationReport = report
+        },
         onCallMetric: (call) => {
           // Stamp the job-scoped sequence on the metric OBJECT: the handler keeps the same
           // instance for its terminal result, so both channels carry the same `seq` and the

package/src/validation-checks.ts

@@ -0,0 +1,395 @@
+import { spawn } from 'node:child_process'
+import { killChildProcess, spawnDetached } from './process.js'
+import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js'
+import type { RunOptions } from './runner.js'
+import type { Logger } from './logger.js'
+
+// PRE-PR VALIDATION — the generic check runner (see docs/initiatives/pre-pr-validation.md).
+//
+// A service can declare shell commands (install / lint / test / build) that run against the
+// CHECKOUT after the coding agent settles and BEFORE a PR is opened. This module owns running
+// them and shaping the report; the loop that feeds a failure back to the agent lives in
+// `coding-agent.ts`, and the decision to run at all is made purely by the JOB BODY carrying
+// `validationChecks` — there is deliberately no agent-kind switch anywhere in the harness.
+//
+// Everything here is PER-JOB by construction: the commands, the cwd, and the environment all
+// arrive as arguments. Nothing is read from or written to `process.env` or `HOME`, because the
+// local NATIVE transport serves every concurrent job from ONE host process — a global would leak
+// one job's config into a sibling's checks, and the container path would never catch it.
+
+/** One configured check, as it arrives on the job body. */
+export interface ValidationCheckSpec {
+  label: string
+  command: string
+}
+
+/** The whole validation config a job carries. */
+export interface ValidationChecksSpec {
+  checks: ValidationCheckSpec[]
+  /** How many agent+check rounds the loop may run (1 = check once, no repair round). */
+  maxAttempts: number
+}
+
+/** One command's outcome within an attempt. */
+export interface ValidationCheckOutcome {
+  label: string
+  command: string
+  exitCode: number
+  passed: boolean
+  outputTail?: string
+  durationMs?: number
+  timedOut?: boolean
+}
+
+/**
+ * One attempt's result: the REPORT that crosses the wire, plus the FULL (scrubbed, 16k) output
+ * tails kept in memory for the repair prompt. The two are deliberately separate — see
+ * {@link VALIDATION_REPORT_TAIL_CHARS}.
+ */
+export interface ValidationAttempt {
+  report: ValidationReport
+  /** Full scrubbed output per check label — never leaves the container. */
+  fullTails: Map<string, string>
+}
+
+/** One attempt's report — what the backend records on the step. */
+export interface ValidationReport {
+  passed: boolean
+  attempts: number
+  maxAttempts: number
+  outcomes: ValidationCheckOutcome[]
+  at: number
+}
+
+/**
+ * Per-command output kept on the REPORT (what crosses the wire and lands in the run's persisted
+ * `detail` blob). Deliberately smaller than {@link MAX_CAPTURED_OUTPUT_CHARS}, which is what the
+ * AGENT sees in its repair prompt: the agent needs the full failure to fix it, the operator needs
+ * enough to recognise it, and a chatty build must not inflate every run's stored state.
+ */
+export const VALIDATION_REPORT_TAIL_CHARS = 4_000
+
+/**
+ * The per-command watchdog: the longest a single check may run before it is killed and treated
+ * as a failure, so one hung `pnpm test` cannot wedge a run. Overridable via env for tests;
+ * defaults to 15 minutes (matching the ralph completion command's watchdog).
+ */
+export function validationCommandTimeoutMs(): number {
+  const n = Number(process.env.VALIDATION_COMMAND_TIMEOUT_MS)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 15 * 60_000
+}
+
+/**
+ * How often the check loop feeds the run's inactivity watchdog. Well under the harness's own
+ * `JOB_INACTIVITY_MS` (default 10 min) so a single slow command can never look wedged; matches
+ * the frontend stand-up's heartbeat, which exists for exactly the same reason. Overridable via
+ * env for tests, like {@link validationCommandTimeoutMs}.
+ */
+export function validationHeartbeatMs(): number {
+  const n = Number(process.env.VALIDATION_HEARTBEAT_MS)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 30_000
+}
+
+/**
+ * Run every configured check IN ORDER against `cwd` and build the attempt's report.
+ *
+ * Runs all of them even after one fails, rather than short-circuiting: the agent repairing the
+ * checkout should see every problem at once instead of rediscovering the next one on the next
+ * round, which is the difference between one repair round and four. (A check whose failure makes
+ * the rest meaningless — e.g. a failed install — still costs only the cheap downstream failures.)
+ *
+ * Keeps the run's inactivity watchdog fed for the whole attempt. These commands are exactly the
+ * activity-SILENT kind — a cold `install`, a full `test` run, a `build` — and the harness spawns
+ * them itself rather than through the agent, so they emit no activity events of their own. The
+ * job-level watchdog (`JOB_INACTIVITY_MS`, default 10 min) is TIGHTER than one command's own
+ * watchdog ({@link validationCommandTimeoutMs}, default 15 min), so without this a legitimately
+ * slow check would abort the entire run as "inactivity" — mislabelling a healthy build as a
+ * wedge, and making the per-command timeout unreachable at stock settings.
+ */
+export async function runValidationChecks(
+  cwd: string,
+  spec: ValidationChecksSpec,
+  attempt: number,
+  logger: Logger,
+  opts: RunOptions,
+): Promise<ValidationAttempt> {
+  const outcomes: ValidationCheckOutcome[] = []
+  const fullTails = new Map<string, string>()
+  const heartbeat = setInterval(() => opts.onActivity?.(), validationHeartbeatMs())
+  heartbeat.unref?.()
+  try {
+    for (const check of spec.checks) {
+      const { outcome, fullTail } = await runOneCheck(cwd, check, logger, opts)
+      outcomes.push(outcome)
+      if (fullTail) fullTails.set(check.label, fullTail)
+    }
+  } finally {
+    clearInterval(heartbeat)
+  }
+  const report: ValidationReport = {
+    passed: outcomes.every((o) => o.passed),
+    attempts: attempt,
+    maxAttempts: spec.maxAttempts,
+    outcomes,
+    at: Date.now(),
+  }
+  logger.info('validation: attempt finished', {
+    attempt,
+    maxAttempts: spec.maxAttempts,
+    passed: report.passed,
+    failed: outcomes.filter((o) => !o.passed).map((o) => o.label),
+  })
+  return { report, fullTails }
+}
+
+/**
+ * Run ONE check as `sh -c <command>` in `cwd`, capturing a bounded, secret-scrubbed tail of its
+ * combined stdout+stderr. The exit code is the verdict — computed here by the harness, never
+ * self-reported by the model, which is the whole point of a programmatic gate. A watchdog kills
+ * the process tree on timeout and an aborted run resolves non-zero, so the loop is never blocked.
+ *
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * not a mutated global: the harness spawns this itself rather than through the agent, so without
+ * the explicit merge a native-mode job would run its checks without the private-registry npmrc
+ * pointer (and against a sibling job's state, had this been staged in `process.env`).
+ */
+async function runOneCheck(
+  cwd: string,
+  check: ValidationCheckSpec,
+  logger: Logger,
+  opts: RunOptions,
+): Promise<{ outcome: ValidationCheckOutcome; fullTail?: string }> {
+  const timeoutMs = validationCommandTimeoutMs()
+  const startedAt = Date.now()
+  logger.info('validation: running check', { label: check.label })
+  return new Promise((resolve) => {
+    let out = ''
+    let settled = false
+    let timedOut = false
+    const child = spawn('sh', ['-c', check.command], {
+      cwd,
+      detached: spawnDetached,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, ...opts.agentEnv },
+    })
+    // Keep only the tail; guard against unbounded buffering on a chatty command.
+    const capture = (chunk: Buffer): void => {
+      out = (out + chunk.toString('utf8')).slice(-MAX_CAPTURED_OUTPUT_CHARS)
+    }
+    child.stdout?.on('data', capture)
+    child.stderr?.on('data', capture)
+    const finish = (exitCode: number): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      opts.signal?.removeEventListener('abort', onAbort)
+      const trimmed = out.trim()
+      // Scrub BEFORE truncating: a token straddling the cut would otherwise survive as a
+      // partial, and the pattern rules need the whole assignment to match.
+      const scrubbed = trimmed ? redactSecrets(trimmed) : ''
+      logger.info('validation: check finished', { label: check.label, exitCode })
+      resolve({
+        outcome: {
+          label: check.label,
+          command: check.command,
+          exitCode,
+          passed: exitCode === 0,
+          ...(scrubbed ? { outputTail: tailFor(scrubbed) } : {}),
+          durationMs: Date.now() - startedAt,
+          ...(timedOut ? { timedOut: true } : {}),
+        },
+        ...(scrubbed ? { fullTail: scrubbed } : {}),
+      })
+    }
+    const timer = setTimeout(() => {
+      logger.warn('validation: check timed out', { label: check.label, timeoutMs })
+      timedOut = true
+      killChildProcess(child, undefined, logger)
+      finish(124) // conventional timeout exit code (a non-zero fail)
+    }, timeoutMs)
+    timer.unref?.()
+    const onAbort = (): void => {
+      killChildProcess(child, undefined, logger)
+      finish(130) // aborted (a non-zero fail)
+    }
+    opts.signal?.addEventListener('abort', onAbort, { once: true })
+    child.on('error', (err) => {
+      logger.warn('validation: check failed to spawn', {
+        label: check.label,
+        error: err instanceof Error ? err.message : String(err),
+      })
+      finish(127) // spawn error / command not found (a non-zero fail)
+    })
+    child.on('close', (code) => finish(code ?? 1))
+  })
+}
+
+/** Bound an already-scrubbed output tail to what the REPORT carries. */
+function tailFor(scrubbed: string): string {
+  if (scrubbed.length <= VALIDATION_REPORT_TAIL_CHARS) return scrubbed
+  const trimmed = scrubbed.length - VALIDATION_REPORT_TAIL_CHARS
+  return `…(${trimmed} earlier chars trimmed)\n${scrubbed.slice(-VALIDATION_REPORT_TAIL_CHARS)}`
+}
+
+/**
+ * The repair instruction handed to the agent after a failed attempt: the failing commands and
+ * their captured output, plus an explicit statement of the exit condition and the remaining
+ * budget. The FULL captured tail is used here (not the report's smaller bound) — the agent needs
+ * the whole failure to fix it, and this text never leaves the container.
+ *
+ * Deliberately prescriptive about scope: a validation loop that lets the agent "fix" the failure
+ * by weakening the check is worse than no loop at all, so the prompt forbids editing the
+ * commands' configuration to make them pass.
+ */
+export function buildRepairPrompt(
+  report: ValidationReport,
+  fullTails: Map<string, string>,
+  /**
+   * New files the agent created but never `git add`ed, if the caller can tell. The harness only
+   * auto-stages TRACKED edits (`git add -u`), so an uncommitted new file is invisible to the push
+   * — yet fully visible to the checks, which run against the working tree. Naming them here is
+   * what stops the loop going green on work the pull request would not contain.
+   */
+  untrackedFiles: string[] = [],
+): string {
+  const failed = report.outcomes.filter((o) => !o.passed)
+  const blocks = failed
+    .map((o) => {
+      const body = fullTails.get(o.label) ?? o.outputTail ?? '(no output captured)'
+      const reason = o.timedOut
+        ? `timed out after ${Math.round((o.durationMs ?? 0) / 1000)}s`
+        : `exited ${o.exitCode}`
+      return `### ${o.label} — ${reason}\n\n\`\`\`\n$ ${o.command}\n${body}\n\`\`\``
+    })
+    .join('\n\n')
+  const remaining = report.maxAttempts - report.attempts
+  const untracked = untrackedFiles.length
+    ? [
+        '',
+        '## Uncommitted new files',
+        '',
+        'These files exist in your checkout but were never added to git, so they are NOT part of',
+        'the branch even though the checks above ran against them. `git add` each one you meant to',
+        'keep (or delete it), or the checks will pass on work the pull request will not contain:',
+        '',
+        ...untrackedFiles.map((f) => `- ${f}`),
+      ]
+    : []
+  return [
+    'The work you just finished does NOT pass this service’s required validation checks, so',
+    'no pull request has been opened. Fix the failures below, then stop.',
+    '',
+    blocks,
+    ...untracked,
+    '',
+    '## How this is judged',
+    '',
+    `The checks above are re-run automatically against your checkout when you stop. They are the`,
+    `exit condition: a pull request opens only once every one of them exits 0. You have`,
+    `${remaining} attempt(s) left before this task fails.`,
+    '',
+    '## Rules',
+    '',
+    '- Fix the underlying problem in the code. Do NOT edit, disable, skip, or relax the checks',
+    '  themselves (their scripts, configs, thresholds, ignore files, or test assertions) to make',
+    '  them pass — a green check obtained that way is a failed task.',
+    '- Do not revert your earlier work; build on it.',
+    '- Commit your fixes, as you did before. `git add` any NEW file you create — only changes to',
+    '  files already tracked by git are staged for you, so an unadded file is silently dropped',
+    '  from the branch even though the checks can see it.',
+  ].join('\n')
+}
+
+/**
+ * The pre-PR validation LOOP: run the checks, and while they fail and budget remains, hand the
+ * captured output back to the agent as its next instruction and check again. Returns the LAST
+ * attempt's report — `passed: true` means the caller may open the PR; `passed: false` means the
+ * budget is spent and the caller must FAIL the job with this report as the evidence, opening
+ * nothing.
+ *
+ * Generic by construction: it knows nothing about agent kinds, repos or PRs — only how to run
+ * commands in a directory and how to ask for another pass. Every input (`workDir`, `spec`,
+ * `opts.agentEnv`) is per-job, so two concurrent jobs on the ONE local-native host process cannot
+ * see each other's configuration (`validation-checks.concurrency.test.ts` pins this).
+ *
+ * `onAttempt` publishes each completed attempt on the job view 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, so a 3-round loop reports what all 3 rounds actually spent.
+ */
+export async function runValidationLoop<TRun>(args: {
+  workDir: string
+  spec: ValidationChecksSpec
+  logger: Logger
+  opts: RunOptions
+  runAgentPass: (userPrompt: string) => Promise<TRun>
+  onAgentPass?: (run: TRun) => void
+  /**
+   * Optional: the new files left uncommitted in the checkout, folded into each repair prompt.
+   * Injected rather than read here so this module stays git-agnostic (it knows only how to run
+   * commands in a directory and how to ask for another pass); the coding agent, which owns the
+   * checkout, supplies it. A throw is swallowed — a missing warning must never fail the loop.
+   */
+  listUncommittedNewFiles?: () => Promise<string[]>
+}): Promise<ValidationReport> {
+  const { workDir, spec, logger, opts, runAgentPass, onAgentPass, listUncommittedNewFiles } = args
+  let attempt = 1
+  for (;;) {
+    const { report, fullTails } = await runValidationChecks(workDir, spec, attempt, logger, opts)
+    opts.onValidationReport?.(report)
+    if (report.passed) {
+      logger.info('validation: checkout is green', { attempt })
+      return report
+    }
+    if (attempt >= spec.maxAttempts) {
+      logger.warn('validation: attempt budget spent — no PR will be opened', {
+        attempt,
+        maxAttempts: spec.maxAttempts,
+      })
+      return report
+    }
+    attempt += 1
+    logger.info('validation: repairing', { nextAttempt: attempt })
+    opts.onPhase?.('validation-repair')
+    const untracked = await safeListUncommitted(listUncommittedNewFiles, logger)
+    const run = await runAgentPass(buildRepairPrompt(report, fullTails, untracked))
+    onAgentPass?.(run)
+    opts.onPhase?.('agent')
+  }
+}
+
+/**
+ * The uncommitted-new-file list for a repair prompt, never throwing: this is an ADVISORY
+ * addition to the instruction, so a `git` hiccup must degrade to "no warning" rather than
+ * failing a loop that is otherwise working.
+ */
+async function safeListUncommitted(
+  list: (() => Promise<string[]>) | undefined,
+  logger: Logger,
+): Promise<string[]> {
+  if (!list) return []
+  try {
+    return await list()
+  } catch (error) {
+    logger.warn('validation: could not list uncommitted new files', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return []
+  }
+}
+
+/**
+ * The failure message for a run whose pre-PR validation never went green: which checks failed
+ * (with exit codes) and the last one's captured output. Read by the operator on the step's
+ * failure card, so it must say what broke without needing the full report opened.
+ */
+export function validationFailureMessage(report: ValidationReport): string {
+  const failed = report.outcomes.filter((o) => !o.passed)
+  const names = failed.map((o) => `${o.label} (exit ${o.exitCode})`).join(', ')
+  const last = failed[failed.length - 1]
+  const tail = last?.outputTail?.trim()
+  const head =
+    `pre-PR validation failed after ${report.attempts} of ${report.maxAttempts} attempt(s)` +
+    (names ? `: ${names}` : '') +
+    '. No pull request was opened.'
+  return tail ? `${head}\n\n$ ${last?.command}\n${tail}` : head
+}