@cat-factory/executor-harness 1.132.3 → 1.134.0

package/src/git.ts

@@ -604,14 +604,86 @@ export async function commitTrackedEdits(
  * --exclude-standard`). The harness deliberately never blanket-stages new files (the
  * agent owns commit selection), so this is exactly what {@link commitTrackedEdits}
  * does NOT capture — a NEW file the agent created but forgot to commit. The caller
- * surfaces it as a warning so that silent loss is at least observable in the logs.
+ * surfaces it as a warning, and the salvage commits it, so that loss is at least observable.
+ *
+ * `-z` for the reason given on {@link splitNulPaths}: the default output C-QUOTES any path git
+ * considers unusual, and a quoted path is not the name of a file. The salvage stages exactly
+ * what this returns, so a single accented filename would make its one `git add` exit 128 and
+ * discard the whole all-or-nothing salvage.
  */
 export async function listUntrackedFiles(dir: string, signal?: AbortSignal): Promise<string[]> {
-  const out = await git(['ls-files', '--others', '--exclude-standard'], { cwd: dir, signal })
-  return out
-    .split('\n')
-    .map((line) => line.replace(/\r$/, '').trim())
-    .filter((path) => path !== '')
+  return splitNulPaths(
+    await git(['ls-files', '--others', '--exclude-standard', '-z'], { cwd: dir, signal }),
+  )
+}
+
+/**
+ * Split git's NUL-delimited path output into real, unescaped paths.
+ *
+ * Every path-listing git command here passes `-z`, and this is why: without it git renders a
+ * path containing a non-ASCII byte, a quote, a backslash or a newline as a C-QUOTED STRING
+ * (`"caf\303\251.ts"`), quotes and octal escapes included. That string is not a filename — feed
+ * it back to `git add` and the command exits 128 with `pathspec ... did not match any files`, and
+ * `stat` on it reports nothing. `-z` turns the quoting off entirely (a NUL cannot occur in a path,
+ * so no escaping is needed) and is the ONLY setting that is correct for every path: `core.quotePath
+ * =false` covers the non-ASCII case alone and still quotes the other three.
+ *
+ * A trailing NUL leaves an empty final field, which is dropped along with any other blank.
+ */
+function splitNulPaths(out: string): string[] {
+  return out.split('\0').filter((path) => path !== '')
+}
+
+/**
+ * The raw `git status --porcelain -z --untracked-files=all` output for `dir` — every path git
+ * considers changed, with untracked files enumerated INDIVIDUALLY rather than collapsed to their
+ * directory.
+ *
+ * The raw string, not a parsed list, because its two consumers want different things from it and
+ * the parse ({@link changedPathsFromPorcelain}) is pure and shared: the workspace probe wants "is
+ * anything here at all", the salvage wants the paths themselves. Gitignored paths are absent by
+ * construction, which is what keeps a dependency install from reading as agent progress.
+ *
+ * NOTHING IS STAGED, unlike {@link hasAgentChanges}: this runs mid-flight, while the agent is
+ * still working, so a `git add -A` here would silently stage files the agent had not chosen and
+ * change what a later `commitTrackedEdits` captures.
+ */
+export async function workingTreeStatus(dir: string, signal?: AbortSignal): Promise<string> {
+  return git(['status', '--porcelain', '-z', '--untracked-files=all'], { cwd: dir, signal })
+}
+
+/**
+ * Stage exactly `paths` and commit them with `message`, returning the new commit's sha (or null
+ * when git found nothing to commit — a path that vanished between listing and staging).
+ *
+ * Three separate things stop a path being read as something other than a path. `--` terminates
+ * the options, so one beginning with `-` cannot be read as a flag. Each path is a separate argv
+ * entry, so no shell ever sees them. And each is prefixed `:(literal)`, which is what `--` does
+ * NOT cover: everything after `--` is a PATHSPEC, not a filename, so its leading `:` is read as
+ * pathspec magic and its wildcards are matched as a glob. An agent-authored `:notes.txt` makes a
+ * bare `git add -- :notes.txt` exit 128 on `did not match any files` — and since this stages every
+ * path in ONE command, that one name discards the whole all-or-nothing salvage, exactly as an
+ * unquoted accented name did. `:(literal)` matches the entry as itself and nothing else.
+ *
+ * The caller has already decided WHICH paths belong; this only commits them.
+ */
+export async function commitPaths(
+  dir: string,
+  paths: string[],
+  message: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  if (paths.length === 0) return null
+  await git(['add', '--', ...paths.map(literalPathspec)], { cwd: dir, signal })
+  const staged = await git(['diff', '--cached', '--name-only'], { cwd: dir, signal })
+  if (staged.trim() === '') return null
+  await git(['commit', '-m', message], { cwd: dir, signal })
+  return headCommit(dir, signal)
+}
+
+/** One path as a pathspec that matches only itself — see {@link commitPaths} for why. */
+function literalPathspec(path: string): string {
+  return `:(literal)${path}`
 }
 
 /**
@@ -624,14 +696,12 @@ export async function listUntrackedFiles(dir: string, signal?: AbortSignal): Pro
  * and enumerating them would cost a multi-megabyte listing to learn a single name.
  */
 export async function listUntrackedPaths(dir: string, signal?: AbortSignal): Promise<string[]> {
-  const out = await git(
-    ['ls-files', '--others', '--exclude-standard', '--directory', '--no-empty-directory'],
-    { cwd: dir, signal },
+  return splitNulPaths(
+    await git(
+      ['ls-files', '--others', '--exclude-standard', '--directory', '--no-empty-directory', '-z'],
+      { cwd: dir, signal },
+    ),
   )
-  return out
-    .split('\n')
-    .map((line) => line.replace(/\r$/, '').trim())
-    .filter((path) => path !== '')
 }
 
 /**
@@ -796,21 +866,29 @@ export async function hasDiffAgainstBase(
 }
 
 /**
- * Parse the paths out of `git status --porcelain` (v1) output. Each line is
- * `XY <path>`, or `XY <old> -> <new>` for a rename/copy (we keep the new path);
- * git quotes paths with special characters, which we unquote. Blank lines are
- * skipped. Pure so the no-op detection can be tested without spawning git.
+ * Parse the paths out of `git status --porcelain -z` (v1) output.
+ *
+ * `-z` rather than the default, for the reason given on {@link splitNulPaths}: the default
+ * C-QUOTES any path git considers unusual, so `caf\u00e9.ts` arrives as the seven-character
+ * literal `"caf\303\251.ts"` and every consumer that then touches the file misses it. In `-z`
+ * every field is a real path and nothing is escaped.
+ *
+ * Each NUL-terminated field is `XY <path>`. A rename or copy (`R`/`C` in either status column)
+ * spends a SECOND field on its original path, which is consumed and dropped: we keep the new
+ * path, the one that now exists in the tree. Pure so the no-op detection and the workspace
+ * probe's sentinel rule can be tested without spawning git.
  */
 export function changedPathsFromPorcelain(status: string): string[] {
+  const fields = status.split('\0')
   const paths: string[] = []
-  for (const raw of status.split('\n')) {
-    const line = raw.replace(/\r$/, '')
-    if (line.trim() === '') continue
-    let path = line.slice(3)
-    const arrow = path.indexOf(' -> ')
-    if (arrow !== -1) path = path.slice(arrow + 4)
-    path = path.trim().replace(/^"(.*)"$/, '$1')
-    if (path) paths.push(path)
+  for (let index = 0; index < fields.length; index++) {
+    const entry = fields[index] ?? ''
+    if (entry === '') continue
+    // `XY ` then the path. A field too short to hold both is not a status entry (a stray
+    // trailing fragment), so there is no path in it to keep.
+    if (entry.length <= 3) continue
+    if (entry[0] === 'R' || entry[0] === 'C' || entry[1] === 'R' || entry[1] === 'C') index++
+    paths.push(entry.slice(3))
   }
   return paths
 }
@@ -824,7 +902,7 @@ export function changedPathsFromPorcelain(status: string): string[] {
  */
 export async function hasAgentChanges(dir: string, signal?: AbortSignal): Promise<boolean> {
   await git(['add', '-A'], { cwd: dir, signal })
-  const status = await git(['status', '--porcelain'], { cwd: dir, signal })
+  const status = await git(['status', '--porcelain', '-z'], { cwd: dir, signal })
   return changedPathsFromPorcelain(status).length > 0
 }
 

package/src/guard-driver.ts

@@ -0,0 +1,203 @@
+import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
+import type { WorkspaceProbe } from './workspace-probe.js'
+import { log as defaultLog, type Logger } from './logger.js'
+
+// The bridge between the SYNCHRONOUS {@link ProgressGuard} and the ASYNCHRONOUS evidence one of
+// its bounds needs. Both runners feed the guard from a sync stream handler (`pi.ts`'s JSONL line
+// reader, `agent-runner.ts`'s tool_result pairing) and neither can await inside one, so the driver
+// owns the probe's lifetime instead. Shared rather than copied per runner: a decision this one
+// ("has the run stopped making progress") must come out the same way on both, which is why
+// `ProgressGuard` itself was extracted in the first place.
+
+/** The whole cause chain of a thrown value, one line, so a probe failure names what actually broke. */
+function describeCause(error: unknown): string {
+  const parts: string[] = []
+  let current: unknown = error
+  for (let depth = 0; depth < 8 && current !== undefined && current !== null; depth++) {
+    parts.push(current instanceof Error ? current.message : String(current))
+    current = current instanceof Error ? (current.cause as unknown) : undefined
+  }
+  return parts.filter((part) => part !== '').join(': ')
+}
+
+/** One run's guard plus the async settlement of the bound the stream alone cannot decide. */
+export interface GuardDriver {
+  /** Feed one tool-call signal (name + error flag) — the claude-code runner's shape. */
+  observeSignal: (tool: { name: string; isError: boolean }) => void
+  /** Feed one parsed Pi `--mode json` event; a non-tool-call event is a no-op. */
+  observeEvent: (event: Record<string, unknown>) => void
+  /** Whether the guard has decided to kill this run. */
+  aborted: () => boolean
+}
+
+/**
+ * Drive one run's {@link ProgressGuard}, resolving the one verdict the stream cannot settle.
+ *
+ * An `abort` verdict fires {@link onAbort} immediately: every streak bound (consecutive errors /
+ * web calls / MCP calls / non-action calls) reads only the stream, so the stream is all the
+ * evidence there is.
+ *
+ * A `needs-workspace-evidence` verdict — the no-edit bound — starts a probe of the working tree
+ * and acts on its answer:
+ *
+ *  - MUTATED: the run has changed the repository, whichever tool it used. The bound is satisfied
+ *    permanently, exactly as a recognised edit-tool call satisfies it, so no second probe is ever
+ *    made and the run continues.
+ *  - CLEAN: abort, with the evidence in the message.
+ *  - THREW: inconclusive, which is neither a pass nor a fail. The bound is re-armed (it can trip
+ *    again after another `maxToolCallsWithoutEdit` action calls) and the cause is warned. Failing
+ *    open is deliberate: killing a productive run is the expensive error, and the streak bounds,
+ *    the inactivity watchdog and the wall-clock cap all still hold the run.
+ *
+ * With no probe wired the bound falls back to its old tool-name-only judgement, so a caller with
+ * no checkout to probe is no worse off than before.
+ */
+export function createGuardDriver(deps: {
+  guard: ProgressGuard
+  probe?: WorkspaceProbe | undefined
+  /** Kill the run with this diagnostic. Called at most once. */
+  onAbort: (reason: string) => void
+  log?: Logger | undefined
+}): GuardDriver {
+  const logger = deps.log ?? defaultLog
+  let aborted = false
+  let probing = false
+
+  const abort = (reason: string): void => {
+    if (aborted) return
+    aborted = true
+    deps.onAbort(reason)
+  }
+
+  const settleFromWorkspace = (provisional: string): void => {
+    const probe = deps.probe
+    if (!probe) {
+      // No checkout to probe: the tool-name reading is the only evidence there is, so act on it
+      // rather than leaving the bound permanently unenforceable.
+      abort(`${provisional} Aborting before it burns the whole run.`)
+      return
+    }
+    probing = true
+    void probe()
+      .then((evidence) => {
+        if (aborted) return
+        if (evidence.mutated) {
+          deps.guard.noteWorkspaceMutation()
+          logger.info('progress-guard: working tree shows the run IS changing the repository', {
+            headSha: evidence.headSha,
+            headMoved: evidence.headMoved,
+            dirtyPathCount: evidence.dirtyPathCount,
+          })
+          return
+        }
+        abort(
+          `${provisional} The working tree agrees: at ${evidence.headSha} there is nothing ` +
+            `uncommitted and HEAD has not moved since this pass began, so the repository is ` +
+            `unchanged. Aborting before it burns the whole run.`,
+        )
+      })
+      .catch((error: unknown) => {
+        if (aborted) return
+        deps.guard.rearmNoEditBound()
+        logger.warn('progress-guard: workspace probe failed; treating it as inconclusive', {
+          error: describeCause(error),
+        })
+      })
+      .finally(() => {
+        probing = false
+      })
+  }
+
+  const act = (verdict: ReturnType<ProgressGuard['observeSignal']>): void => {
+    if (aborted || !verdict) return
+    if (verdict.kind === 'needs-workspace-evidence') {
+      // A probe already in flight owns the current question. The guard itself suppresses a second
+      // `needs-workspace-evidence` until one is answered; this is the belt to that braces.
+      if (!probing) settleFromWorkspace(verdict.reason)
+      return
+    }
+    abort(verdict.reason)
+  }
+
+  return {
+    observeSignal: (tool) => {
+      if (aborted) return
+      act(deps.guard.observeSignal(tool))
+    },
+    observeEvent: (event) => {
+      if (aborted) return
+      act(deps.guard.observe(event))
+    },
+    aborted: () => aborted,
+  }
+}
+
+/** What {@link createClaudeProgressGuard} needs off the run options, and nothing more. */
+export interface ClaudeGuardOptions {
+  guardLimits?: ProgressGuardLimits | undefined
+  expectsEdits?: boolean | undefined
+  workspaceProbe?: WorkspaceProbe | undefined
+  log?: Logger | undefined
+}
+
+/**
+ * No-progress guard on the claude-code CLI's own tool stream — the claude-code analogue of runPi's
+ * guard, which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name
+ * off the assistant turn (`rememberTool`) and hands the following user turn's content to
+ * `feedGuard`, which pairs each `tool_result`'s `is_error` with that name.
+ *
+ * The first abort trips it: the diagnostic is recorded (readable via `reason()`, which the catch
+ * surfaces over the generic abort message) and `guardAbort` fires, folded into streamCli's signal
+ * so a tripped guard kills the CLI the same way the external watchdog does. Disabled when the
+ * caller supplies no limits (only the external watchdog then bounds the run).
+ *
+ * Lives here rather than in `agent-runner.ts` because the async half of it — the workspace probe
+ * behind the no-edit bound — is the same collaborator the Pi runner drives.
+ */
+export function createClaudeProgressGuard(opts: ClaudeGuardOptions): {
+  rememberTool: (id: string, name: string) => void
+  feedGuard: (content: unknown[]) => void
+  guardAbort: AbortController
+  reason: () => string | undefined
+} {
+  const toolNames = new Map<string, string>()
+  const guardAbort = new AbortController()
+  let guardReason: string | undefined
+
+  const limits = opts.guardLimits
+  const driver = limits
+    ? createGuardDriver({
+        guard: new ProgressGuard(limits, opts.expectsEdits ?? true),
+        probe: opts.workspaceProbe,
+        log: opts.log,
+        onAbort: (reason) => {
+          guardReason = reason
+          guardAbort.abort()
+        },
+      })
+    : undefined
+
+  const feedGuard = (content: unknown[]): void => {
+    if (!driver || driver.aborted()) return
+    for (const block of content) {
+      if (!isRecord(block) || block.type !== 'tool_result') continue
+      const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined
+      const name = id ? toolNames.get(id) : undefined
+      if (id) toolNames.delete(id)
+      if (!name) continue
+      driver.observeSignal({ name, isError: block.is_error === true })
+      if (driver.aborted()) return
+    }
+  }
+
+  return {
+    rememberTool: (id, name) => toolNames.set(id, name),
+    feedGuard,
+    guardAbort,
+    reason: () => guardReason,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}

package/src/harness-server.ts

@@ -5,6 +5,7 @@ import { parseAgentJob, parseInlineJob } from './job.js'
 import { handleAgent } from './agent.js'
 import { handleInline } from './inline.js'
 import { redactSecrets } from './git.js'
+import { readDockerStatus } from './docker-status.js'
 import { JobRegistry, loadRunnerLimits, type JobResultBase, type RunOptions } from './runner.js'
 import { log } from './logger.js'
 import { HARNESS_VERSION } from './version.js'
@@ -128,10 +129,22 @@ const server = createServer((req, res) => {
       // fail loudly early (see version.ts). Unauthenticated like the rest of /health — the
       // version is not a secret. An old image predating this field simply omits it, which the
       // backend treats as a stale signal.
+      //
+      // `docker` is this container's own verdict on its daemon (see docker-status.ts). It rides
+      // /health because that is where an operator and a boot-time probe already look, and because
+      // the alternative was every agent discovering an absent daemon for itself, one failed
+      // compose command at a time. Reported, never enforced here: what REFUSES on it is the
+      // stand-up in agent.ts, which is the only place that knows a job wanted a daemon.
+      //
+      // Deliberately the BOOT record, not a live probe. /health is polled, and a probe per poll
+      // would spawn a process per poll to answer a question this endpoint is not the one to act
+      // on; the stand-up re-confirms a recorded absence at the moment it matters
+      // (`resolveDockerVerdict`), so a stale negative here never becomes a stale refusal there.
       return send(res, 200, {
         status: 'ok',
         ...(HARNESS_VERSION ? { version: HARNESS_VERSION } : {}),
         capabilities: HARNESS_BODY_CAPABILITIES,
+        docker: await readDockerStatus(),
       })
     }
     // All non-health endpoints are gated by the optional shared secret.

package/src/infra-standup.ts

@@ -0,0 +1,218 @@
+// The run's infra stand-up: the docker-compose dependencies a local-mode service declares, and
+// the frontend build/serve + WireMock flow the UI-test runs use instead. Split out of agent.ts,
+// which owns the agent MODES; this owns what surrounds a mode with the dependencies it needs and
+// guarantees the matching teardown. `manageInfra` is the one entry point a mode calls.
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { AgentInfraSpec, InfraSetupRecord, ServiceInfraSpec } from './job.js'
+import {
+  type DockerProbe,
+  probeDockerServing,
+  readDockerStatus,
+  resolveDockerVerdict,
+} from './docker-status.js'
+import { standUpFrontend, tearDownFrontend } from './frontend-infra.js'
+import { captureRedactedOutput, redactSecrets } from './redact.js'
+import type { RunOptions } from './runner.js'
+import type { Logger } from './logger.js'
+
+const exec = promisify(execFile)
+
+/**
+ * Bring the service's docker-compose dependencies up (local infra only). Best-effort:
+ * runs `docker compose -f <path> up -d --wait` in the checkout. A compose failure is logged
+ * and surfaced to the agent (as a prompt note) rather than failing the job — the agent can
+ * still run unit-level tests and report what it could. A no-op for ephemeral / no-infra /
+ * no-compose-path runs.
+ *
+ * A CONFIRMED absence of a Docker daemon short-circuits it: the container's own probe
+ * ({@link readDockerStatus}, recorded by `entrypoint.sh`) already knows there is nothing to
+ * talk to, so running compose against it would only turn a fact this container holds into a
+ * connection error the agent has to interpret. The record then carries `dockerAvailable: false`
+ * and the stated cause, which is what makes the Tester step say why it ran no infra instead of
+ * looking like a Tester that simply chose not to. Anything OTHER than a confirmed absence
+ * attempts as before (`DockerStatus.available` in docker-status.ts states why "undecided" is its
+ * own value).
+ *
+ * "Confirmed", not merely recorded: {@link resolveDockerVerdict} re-checks a recorded absence
+ * against a live daemon first, so a warm-pool container whose sidecar came up late is not
+ * latched into refusing infra that works. `probe` is that check, injected so the unit suite can
+ * state both answers on a machine that has its own daemon either way.
+ *
+ * Whether it succeeds or fails, the (redacted, bounded) command output is captured into a
+ * {@link InfraSetupRecord} returned alongside the prompt `note`, so the backend can surface
+ * the in-container dependency stand-up logs on the Tester step — the failure-class artifact
+ * the orchestrator-side provisioning logs can't see.
+ *
+ * Exported for the unit suite (like {@link buildInfraNotes}): the refusal branch is a decision
+ * this container makes about itself, and the acceptance suite can only exercise it on a machine
+ * where the daemon genuinely fails.
+ */
+export async function standUpInfra(
+  dir: string,
+  infra: ServiceInfraSpec,
+  signal: AbortSignal | undefined,
+  logger: Logger,
+  probe: DockerProbe = probeDockerServing,
+): Promise<{ started: boolean; note?: string; record?: InfraSetupRecord }> {
+  if (infra.environment !== 'local' || infra.noInfraDependencies || !infra.composePath) {
+    return { started: false }
+  }
+  const startedAt = Date.now()
+  const recorded = await readDockerStatus()
+  const docker = await resolveDockerVerdict(recorded, probe)
+  if (docker.refusal) {
+    const note = `the dependencies could not be started: ${docker.refusal}`
+    logger.warn('agent(explore): infra stand-up refused, no docker daemon', {
+      composePath: infra.composePath,
+      dockerSource: recorded.source,
+      dockerReason: recorded.reason,
+    })
+    return {
+      started: false,
+      note,
+      record: {
+        started: false,
+        dockerAvailable: false,
+        composePath: infra.composePath,
+        at: Date.now(),
+        durationMs: Date.now() - startedAt,
+        error: redactSecrets(note),
+      },
+    }
+  }
+  try {
+    logger.info('agent(explore): standing up infra', { composePath: infra.composePath })
+    // Raise maxBuffer well above the 1MB default so a chatty compose stand-up can't fail the
+    // (best-effort) infra step with ENOBUFS; the captured output is tail-bounded on storage.
+    const { stdout, stderr } = await exec(
+      'docker',
+      ['compose', '-f', infra.composePath, 'up', '-d', '--wait'],
+      { cwd: dir, signal, timeout: 5 * 60_000, maxBuffer: 16 * 1024 * 1024 },
+    )
+    const logs = captureRedactedOutput(stdout, stderr)
+    return {
+      started: true,
+      record: {
+        started: true,
+        dockerAvailable: true,
+        composePath: infra.composePath,
+        at: Date.now(),
+        durationMs: Date.now() - startedAt,
+        ...(logs ? { logs } : {}),
+      },
+    }
+  } catch (err) {
+    const note = err instanceof Error ? err.message : String(err)
+    logger.warn('agent(explore): infra stand-up failed', { error: note })
+    // `execFile` rejections carry the partial stdout/stderr on the error object — capture them
+    // so the stored logs explain the failure (a port clash, a pull-auth error, an exited
+    // dependency), not just the one-line exit message.
+    const e = err as { stdout?: unknown; stderr?: unknown }
+    const logs = captureRedactedOutput(e.stdout, e.stderr)
+    return {
+      started: false,
+      note,
+      record: {
+        started: false,
+        // A compose failure with a REACHABLE daemon: the two `false`s above and here are
+        // different diagnoses (nothing to talk to vs the stack itself did not come up), and
+        // only stating both keeps the second from being read as the first. Read off the
+        // RESOLVED verdict, so a container whose daemon came up after boot claims the daemon it
+        // actually reached rather than the one its boot record still denies.
+        ...(docker.available === true ? { dockerAvailable: true } : {}),
+        composePath: infra.composePath,
+        at: Date.now(),
+        durationMs: Date.now() - startedAt,
+        error: redactSecrets(note),
+        ...(logs ? { logs } : {}),
+      },
+    }
+  }
+}
+
+/**
+ * Stand the run's infra up and return a single cleanup handle, dispatching on the spec's
+ * `kind`: the frontend UI-test flow (`kind: 'frontend'`) builds/serves the app + WireMock as
+ * processes (torn down by killing them); the default backend-service flow stands the
+ * docker-compose stack up (torn down with `docker compose down`). Unifying the two here keeps
+ * `runExploreMode` free of the branch and guarantees the matching teardown runs in its finally.
+ *
+ * `dir` is the clone ROOT; `workDir` is the service subtree (equal to `dir` when the run is not
+ * monorepo-scoped). The docker-compose stand-up runs at the root (its `composePath` is
+ * repo-relative), but the FRONTEND stand-up runs in `workDir`: a monorepo frontend's
+ * `package.json` / `outputDir` / `mocks/` all live under the service subtree, so installing,
+ * building, serving and seeding WireMock from the root would target the wrong directory.
+ */
+export async function manageInfra(
+  dir: string,
+  workDir: string,
+  infra: AgentInfraSpec,
+  opts: RunOptions,
+  logger: Logger,
+): Promise<{
+  note?: string
+  serveUrl?: string
+  record?: InfraSetupRecord
+  cleanup: () => Promise<void>
+}> {
+  if (infra.kind === 'frontend') {
+    // `onActivity` feeds the inactivity watchdog through the frontend build/serve stand-up,
+    // which (unlike docker-compose's 5-min-capped `up`) can run past the inactivity window.
+    // Runs in `workDir` so a monorepo frontend builds/serves from its own package subtree.
+    const fe = await standUpFrontend(workDir, infra, opts, logger)
+    return {
+      ...(fe.note ? { note: fe.note } : {}),
+      ...(fe.serveUrl ? { serveUrl: fe.serveUrl } : {}),
+      record: fe.record,
+      cleanup: () => tearDownFrontend(fe.processes, logger),
+    }
+  }
+  const standUp = await standUpInfra(dir, infra, opts.signal, logger)
+  return {
+    ...(standUp.note ? { note: standUp.note } : {}),
+    ...(standUp.record ? { record: standUp.record } : {}),
+    cleanup: () => tearDownInfra(dir, infra),
+  }
+}
+
+/**
+ * Build the dynamic infra notes appended to the agent's user prompt from a stand-up outcome.
+ * A stand-up problem (a failed build / compose) is flagged as a concern to test around; a
+ * frontend serve URL points the UI tester at the app that was just built + served and pre-empts
+ * a live-backend CORS failure being mis-reported as an app defect. Pure (no IO) so the exact
+ * wording + ordering is unit-tested; returns the notes in order (problem first, serve URL next).
+ */
+export function buildInfraNotes(managed: { note?: string; serveUrl?: string }): string[] {
+  const notes: string[] = []
+  if (managed.note) {
+    notes.push(
+      `standing the infra up reported a problem (${managed.note}). Test what you can and ` +
+        `flag any dependency-related gaps as concerns.`,
+    )
+  }
+  if (managed.serveUrl) {
+    notes.push(
+      `The frontend under test is built and served at ${managed.serveUrl}, with its other ` +
+        `backend upstreams handled by WireMock. Drive your UI tests against ${managed.serveUrl}. ` +
+        `If a call to a live backend fails with a CORS / cross-origin error, that is an infra ` +
+        `gap (the backend must allow the ${managed.serveUrl} origin), not an app defect — flag ` +
+        `it as a concern rather than a failing test.`,
+    )
+  }
+  return notes
+}
+
+/** Tear the docker-compose dependencies down (best-effort; a no-op when none were started). */
+async function tearDownInfra(dir: string, infra: ServiceInfraSpec): Promise<void> {
+  if (infra.environment !== 'local' || infra.noInfraDependencies || !infra.composePath) return
+  try {
+    await exec('docker', ['compose', '-f', infra.composePath, 'down', '-v'], {
+      cwd: dir,
+      timeout: 2 * 60_000,
+    })
+  } catch {
+    // The container is ephemeral and torn down with the run anyway — ignore.
+  }
+}

package/src/job.ts

@@ -945,6 +945,16 @@ export interface GuardLimitsSpec {
 export interface InfraSetupRecord {
   /** Whether `docker compose up --wait` succeeded (the dependencies are up). */
   started: boolean
+  /**
+   * Whether this container had a Docker daemon to talk to at all, when it knows.
+   *
+   * The distinction `started` alone cannot make: a stack that failed to come up and a container
+   * with no daemon are the same `started: false` and opposite problems (one is the service's
+   * compose file, the other is the executor image or the sandbox it runs in). ABSENT means this
+   * container's probe reached no verdict — never assume `false` from absence, which is the exact
+   * mistake that let a daemon-less image read as an ordinary infra failure for months.
+   */
+  dockerAvailable?: boolean
   /** The repo-relative compose file that was stood up. */
   composePath?: string
   /** Epoch ms the stand-up attempt finished. */