@cat-factory/executor-harness 1.132.3 → 1.135.0

package/src/docker-status.ts

@@ -0,0 +1,201 @@
+import { execFile } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+import { promisify } from 'node:util'
+
+// What this container knows about its own Docker daemon, as recorded by `entrypoint.sh`.
+//
+// The Tester's local-mode infra stand-up (`docker compose up --wait`) is the only thing in the
+// harness that needs a daemon, and for months there was none: the image installed
+// `docker-ce-rootless-extras` (the wrappers that START a daemon) but never `docker-ce` (the
+// daemon), and the entrypoint backgrounded the start in a subshell where its exit status was
+// unobservable. Every local-infra Tester run degraded to a no-infra run, and the only trace was
+// a compose error in a prompt note. This module is the answer that was missing: the entrypoint
+// probes the daemon once and records the verdict, and everything that would otherwise ASSUME a
+// daemon reads it instead.
+//
+// The recorded verdict describes BOOT, and a container outlives its boot, so nothing refuses on
+// it unconfirmed: `resolveDockerVerdict` re-checks a recorded absence against a live daemon and
+// keeps the record for what only the record holds, the cause and the daemon's own log tail.
+//
+// The three-valued shape is deliberate and is the point (CLAUDE.md, "Degrade loudly"): a daemon
+// that FAILED and a daemon nobody asked about are different facts with different correct
+// reactions, and collapsing them would either refuse stand-ups that work or silently attempt
+// ones that cannot. Only a DECIDED `false` refuses.
+
+/**
+ * Where `entrypoint.sh` records its verdict. The two halves of one contract: change this and the
+ * `DOCKER_STATUS_FILE` default in `entrypoint.sh` together. `HARNESS_DOCKER_STATUS_FILE`
+ * overrides both (the acceptance suite and the unit tests point them at a temp file).
+ */
+export const DOCKER_STATUS_FILE = '/tmp/harness-docker-status.json'
+
+/** Which daemon the verdict is about. Closed vocabulary, written by `entrypoint.sh`. */
+export type DockerSource =
+  /** The rootless daemon this container starts for itself. */
+  | 'rootless'
+  /** A sidecar/external daemon a self-hosted pool wired in via `DOCKER_HOST`. */
+  | 'external'
+  /** No daemon in this image at all (no `dockerd` on PATH). */
+  | 'none'
+  /**
+   * Nothing recorded a verdict. NOT a failure: the native host-process transport
+   * (`LOCAL_NATIVE_AGENTS`) runs this harness with no entrypoint at all, on a developer's
+   * machine where Docker usually works fine.
+   */
+  | 'unreported'
+
+/**
+ * The container's Docker verdict.
+ *
+ * `available` is THREE-valued on purpose. `undefined` means "not decided" — the entrypoint's
+ * bounded wait is still running, or nothing recorded anything (native mode) — and a caller must
+ * treat it as it behaved before this existed: attempt, and report what happened. `false` is a
+ * DECIDED absence and is the only value anything refuses on.
+ */
+export interface DockerStatus {
+  available: boolean | undefined
+  source: DockerSource
+  /** Why, in the entrypoint's own closed vocabulary (`serving`/`failed`/`missing`/…). */
+  reason: string
+  /** A human detail for the failing cases: the dockerd log tail, or what was unreachable. */
+  detail?: string
+}
+
+/** The verdict when nothing recorded one (see {@link DockerSource} `unreported`). */
+const UNREPORTED: DockerStatus = {
+  available: undefined,
+  source: 'unreported',
+  reason: 'no docker status was recorded for this harness process',
+}
+
+const SOURCES: readonly DockerSource[] = ['rootless', 'external', 'none', 'unreported']
+
+/**
+ * Read the recorded verdict, or {@link UNREPORTED} when there is none.
+ *
+ * Defensive by design: the file crosses a shell→Node boundary, so an unreadable, truncated or
+ * malformed one answers "not decided" rather than throwing. That is the same disposition as an
+ * absent file, and it is the safe one — a parse bug here must not turn into a Tester that refuses
+ * to stand its dependencies up.
+ */
+export async function readDockerStatus(
+  path: string = process.env.HARNESS_DOCKER_STATUS_FILE?.trim() || DOCKER_STATUS_FILE,
+): Promise<DockerStatus> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return UNREPORTED
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return UNREPORTED
+  }
+  if (typeof parsed !== 'object' || parsed === null) return UNREPORTED
+  const record = parsed as Record<string, unknown>
+  const source = SOURCES.includes(record.source as DockerSource)
+    ? (record.source as DockerSource)
+    : 'unreported'
+  const detail = typeof record.detail === 'string' && record.detail ? record.detail : undefined
+  return {
+    available: typeof record.available === 'boolean' ? record.available : undefined,
+    source,
+    reason: typeof record.reason === 'string' && record.reason ? record.reason : UNREPORTED.reason,
+    ...(detail ? { detail } : {}),
+  }
+}
+
+/**
+ * The sentence a Tester (and the human reading its step) gets instead of a compose error, when
+ * the daemon is decidedly absent. It names the cause the agent could not have discovered and the
+ * consequence, because the agent's next move differs: with no daemon there is nothing to retry,
+ * and the useful run is the one that tests what it can and flags the dependency gap.
+ *
+ * TOTAL over {@link DockerSource}, deliberately. `unreported` is not a hypothetical arm: the
+ * reader above preserves a recorded `available: false` while degrading a source word this build
+ * does not know, so an absence whose source is `unreported` is exactly what a status file written
+ * by a NEWER entrypoint produces here. A ternary chain ending in the rootless arm answered that
+ * case by naming a daemon nobody said anything about: a guess, in the one sentence whose entire
+ * job is to tell a human which thing to go and fix. The `never` arm keeps the compile-time half:
+ * adding a source without a sentence stops building.
+ */
+export function describeDockerAbsence(status: DockerStatus): string {
+  return status.detail
+    ? `${absenceCause(status.source)} (${status.detail})`
+    : absenceCause(status.source)
+}
+
+function absenceCause(source: DockerSource): string {
+  switch (source) {
+    case 'none':
+      return 'this executor image ships no Docker daemon'
+    case 'external':
+      return 'the external Docker daemon this container was pointed at is unreachable'
+    case 'rootless':
+      return 'this container could not start its rootless Docker daemon'
+    case 'unreported':
+      return 'no Docker daemon answered in this container, and the recorded verdict did not say which one was tried'
+    default:
+      return unnamedSource(source)
+  }
+}
+
+function unnamedSource(source: never): string {
+  return `no Docker daemon answered in this container (unrecognised source ${JSON.stringify(source)})`
+}
+
+/** Whether a daemon is answering RIGHT NOW. Injected so the unit suite can state either answer. */
+export type DockerProbe = () => Promise<boolean>
+
+/** A live probe may not outlast the thing it is guarding; a hung socket is an absent daemon here. */
+const PROBE_TIMEOUT_MS = 10_000
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * The default {@link DockerProbe}: `docker version` talks to the SERVER, unlike the client-only
+ * `docker --version`, which answers happily with no daemon at all.
+ */
+export const probeDockerServing: DockerProbe = async () => {
+  try {
+    await execFileAsync('docker', ['version', '--format', '{{.Server.Version}}'], {
+      timeout: PROBE_TIMEOUT_MS,
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** What a stand-up is entitled to conclude about the daemon at the moment it is about to run. */
+export interface DockerVerdict {
+  /** Three-valued exactly as {@link DockerStatus.available}, and read the same way. */
+  available: boolean | undefined
+  /** Set only for a CONFIRMED absence: the sentence to refuse with. Absent means proceed. */
+  refusal?: string
+}
+
+/**
+ * Resolve what to do now, from what boot recorded plus what a daemon says today.
+ *
+ * `entrypoint.sh` probes once, at boot, within a bounded wait. A container outlives that: a warm
+ * pool serves many jobs from one, and a sidecar daemon that took longer than the wait allows is
+ * serving perfectly well by the second job. Refusing off the recorded verdict alone latches that
+ * container into refusing local infra that in fact works, for its whole life, with a stale
+ * sentence explaining why. So a recorded absence is a HYPOTHESIS here, and the live probe settles
+ * it; the recorded verdict is still what supplies the cause and the daemon's own log tail, which
+ * no probe can reconstruct.
+ *
+ * Only a recorded `false` is re-confirmed. "Not decided" keeps attempting exactly as before: the
+ * point of the third value is that nothing turns it into a refusal, and a probe here would.
+ */
+export async function resolveDockerVerdict(
+  status: DockerStatus,
+  probe: DockerProbe = probeDockerServing,
+): Promise<DockerVerdict> {
+  if (status.available !== false) return { available: status.available }
+  if (await probe()) return { available: true }
+  return { available: false, refusal: describeDockerAbsence(status) }
+}

package/src/frontend-infra.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path'
 import type { FrontendInfraSpec, InfraSetupRecord } from './job.js'
 import type { RunOptions } from './runner.js'
 import { killChildProcess } from './process.js'
+import { agentChildEnv } from './agent-env.js'
 import { pathExists } from './fs-utils.js'
 import { captureRedactedOutput, redactSecrets } from './redact.js'
 import { log, type Logger } from './logger.js'
@@ -134,7 +135,7 @@ export async function standUpFrontend(
       signal,
       timeout: 8 * 60_000,
       maxBuffer: 16 * 1024 * 1024,
-      env: { ...process.env, ...jobEnv },
+      env: agentChildEnv(jobEnv),
     })
     pushOutput(installed.stdout, installed.stderr)
 
@@ -147,7 +148,7 @@ export async function standUpFrontend(
       signal,
       timeout: 12 * 60_000,
       maxBuffer: 16 * 1024 * 1024,
-      env: { ...process.env, ...jobEnv, ...buildEnv },
+      env: agentChildEnv(jobEnv, buildEnv),
     })
     pushOutput(built.stdout, built.stderr)
 
@@ -305,7 +306,7 @@ function startServe(
         // Reserved names were already filtered from `infra.env` at parse; PORT wins last so
         // the health-check's port is authoritative even if a binding tried to set it.
         // (Spreading an undefined `infra.env` is a no-op, so no `?? {}` fallback is needed.)
-        env: { ...process.env, ...infra.env, PORT: String(servePort) },
+        env: agentChildEnv(infra.env, { PORT: String(servePort) }),
       }),
       'serve',
       logger,

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.