@cat-factory/executor-harness 1.132.3 → 1.134.0

package/src/multi-repo-coding.ts

@@ -12,11 +12,11 @@ import {
   excludeFromGit,
   fetchReferenceBranches,
   headCommit,
-  listUntrackedFiles,
   pushBranch,
   refreshFromBaseIfClean,
   remoteBranchExists,
 } from './git.js'
+import { salvageOnlyNotice, salvageUntrackedWork } from './salvage.js'
 import { openPullRequest } from './vcs-api.js'
 import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription } from './pr-description.js'
 import { runAgentInWorkspace, withWorkspace } from './pi-workspace.js'
@@ -212,6 +212,8 @@ export async function runMultiRepoCoding(
           ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
           ...(job.designImages ? { designImages: job.designImages } : {}),
           multiRepo: true,
+          // What the no-progress guard's working-tree bound decides on: see {@link probeDirsForLegs}.
+          repoDirs: probeDirsForLegs(legs),
         },
         opts,
       )
@@ -386,6 +388,37 @@ async function prepareMultiRepoCheckouts(
   }
 }
 
+/**
+ * The checkouts the no-progress guard's working-tree bound may judge this run on.
+ *
+ * A multi-repo run's cwd is the workspace ROOT, which is no git repository, so the guard's default
+ * (probe the cwd) asks git a question with no answer: every probe throws, the driver re-arms
+ * forever, and the bound is permanently unenforceable — strictly worse than the tool-name reading
+ * it replaced. The writable legs are the repositories this run may change, so they are what it
+ * has to show progress in.
+ *
+ * A READ-ONLY reference leg is excluded, and not merely as an optimisation: the run is forbidden
+ * to write to it, so a change appearing there is not this run making progress and must never be
+ * what saves it from the bound.
+ */
+export function probeDirsForLegs(legs: readonly { dir: string; readOnly?: boolean }[]): string[] {
+  return legs.filter((leg) => !leg.readOnly).map((leg) => leg.dir)
+}
+
+/**
+ * Put {@link salvageOnlyNotice} at the top of a pull request that is nothing but a salvage.
+ *
+ * Only the BODY is marked. A title carrying it would follow the PR into every list and
+ * notification a maintainer sees, which is a lot of noise for a caveat that belongs beside the
+ * diff, and the salvage commit's own message elaborates on it there.
+ */
+function withSalvageOnlyNote(
+  pr: { title: string; body: string },
+  salvageOnly: boolean,
+): { title: string; body: string } {
+  return salvageOnly ? { ...pr, body: `${salvageOnlyNotice()}\n\n${pr.body}` } : pr
+}
+
 /**
  * Push phase for {@link runMultiRepoCoding}: commit forgotten tracked edits, then push + open a PR
  * for each repo the run actually changed (a repo the agent left untouched is skipped — no branch,
@@ -430,18 +463,36 @@ async function pushMultiRepoLegs(
       (await readPrDescription(leg.dir, readOptions)) ??
       (leg.primary ? await readPrDescription(root, readOptions) : undefined)
     await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal)
-    const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal)
+    // Whether the leg carried COMMITTED work before the salvage, read here and not after it.
+    // Afterwards the salvage's own commit makes every leg it touched look advanced, and the two
+    // are not the same claim: work the agent committed to this repo is a change it chose to make,
+    // where a salvage-only leg is a branch built entirely out of files it left lying in that
+    // checkout. Both are worth keeping; only one is worth presenting as a proposed change without
+    // saying where it came from.
+    const committedOwnWork = await branchHasCommitsSince(leg.dir, leg.baseSha, signal)
+    // Recover this leg's new files, exactly as the single-repo settle path does and for the same
+    // reason: `commitTrackedEdits` captures edits to files git ALREADY tracks, so a new file the
+    // agent created and never added used to be listed, warned about and dropped. Runs BEFORE the
+    // advanced/no-op judgement below, so a leg whose only work is those files is pushed rather
+    // than read as untouched.
+    const salvage = await salvageUntrackedWork({
+      dir: leg.dir,
+      occasion: { kind: 'settled' },
+      logger: logger.child({ repo: leg.dirName }),
+      ...(signal ? { signal } : {}),
+    })
+    const salvageOnly = !committedOwnWork && salvage.status === 'committed'
+    const advanced = committedOwnWork || salvage.status === 'committed'
     let hasWork = advanced || leg.resumed
     if (leg.resumed && !advanced) {
       const ahead = await branchAheadOfBase(leg.dir, leg.repo.baseBranch, leg.ghToken, signal)
       if (ahead === false) hasWork = false
     }
-    const leftover = await listUntrackedFiles(leg.dir, signal)
-    if (leftover.length > 0) {
-      logger.warn('multi-repo: uncommitted new files left behind (not pushed)', {
+    if (salvage.status === 'refused' || salvage.status === 'failed') {
+      logger.warn('multi-repo: new files were left behind and are NOT in the push', {
         repo: leg.dirName,
-        count: leftover.length,
-        files: leftover.slice(0, 20),
+        count: salvage.fileCount,
+        reason: salvage.reason,
       })
     }
     if (!hasWork) {
@@ -457,7 +508,7 @@ async function pushMultiRepoLegs(
         ghToken: leg.ghToken,
         head: leg.workBranch,
         base: leg.repo.baseBranch,
-        pr: applyPrDescription(leg.pr, agentPrDescription),
+        pr: withSalvageOnlyNote(applyPrDescription(leg.pr, agentPrDescription), salvageOnly),
         // See the single-repo call site: refresh a resumed leg's already-open PR, but only
         // when the text is the agent's own briefing rather than the dispatch-time fallback.
         ...(agentPrDescription ? { refreshExisting: true } : {}),

package/src/pi-workspace.ts

@@ -26,6 +26,12 @@ import {
   mergeGuardLimits,
   progressGuardLimitsFromEnv,
 } from './progress-guard.js'
+import {
+  composeWorkspaceProbes,
+  createWorkspaceProbe,
+  readHeadOrEmpty,
+  type WorkspaceProbe,
+} from './workspace-probe.js'
 import type { RunOptions } from './runner.js'
 import { type SubscriptionHarness, runSubscriptionHarness } from './agent-runner.js'
 
@@ -151,6 +157,17 @@ export async function acquireRepoCheckout<T>(
 export interface AgentRunSpec {
   /** The prepared working directory (cloned/scaffolded by the caller). */
   dir: string
+  /**
+   * The git checkouts this pass may change, for the no-progress guard's working-tree bound.
+   * Absent ⇒ `[dir]`, which is right whenever the agent's cwd is (or is inside) the one repo.
+   *
+   * A MULTI-REPO run is the exception the default cannot serve: its cwd is a workspace ROOT
+   * holding sibling checkouts and is no repository itself, so probing it asks git a question with
+   * no answer, every probe throws, and the bound goes permanently unenforced. Such a caller names
+   * its writable legs here instead. A read-only reference checkout is deliberately NOT named: the
+   * run is forbidden to write to it, so a change there is not this run making progress.
+   */
+  repoDirs?: readonly string[]
   /** Composed role + best-practice fragments; written to Pi's global AGENTS.md context. */
   systemPrompt: string
   /** The concrete task prompt handed to Pi. */
@@ -331,6 +348,20 @@ export async function runAgentInWorkspace(
     await materializeSkillResources(spec.dir, spec.skills)
   }
 
+  // The no-progress guard's no-edit bound asks "has this run changed the repository", and the
+  // tool names it can see are only a proxy for that: an agent writing every file through `bash`
+  // reads as making no edits at all, and the guard killed exactly such a run after it had built,
+  // tested and verified a whole service. The working tree is the honest answer, so wire the probe
+  // that reads it. Built HERE because this is the shared middle of both harness paths and the one
+  // place that knows the checkout: the guard itself stays pure and takes it injected.
+  //
+  // The baseline is HEAD as this PASS begins, not the clone's — a repair round is a fresh agent
+  // that must show its OWN progress, and judging it against the clone would let the previous
+  // round's commits satisfy its bound. A checkout with no commit yet (a scaffold-from-scratch
+  // bootstrap) has no HEAD to read; the probe then rides on the dirty-tree half alone, which is
+  // the half that matters there anyway.
+  const workspaceProbe = await buildWorkspaceProbe(spec, opts.signal)
+
   // Subscription harnesses (Claude Code / Codex) authenticate with the leased
   // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
   // system prompt is passed straight to the CLI; everything around this (clone,
@@ -365,6 +396,8 @@ export async function runAgentInWorkspace(
       // ignores it for now (its stream isn't wired to the guard).
       guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
       expectsEdits: spec.expectsEdits ?? true,
+      // What the guard's no-edit bound actually decides on (see `buildWorkspaceProbe`).
+      workspaceProbe,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,
       // The run's tool-call trajectory, the same hook the Pi path feeds — so a subscription run
@@ -446,11 +479,50 @@ export async function runAgentInWorkspace(
     // Start from the env/built-in defaults and apply only the per-knob overrides the
     // backend set for this kind (loosen-only), so an unspecified knob keeps its default.
     guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
+    // What the guard's no-edit bound actually decides on (see `buildWorkspaceProbe`).
+    workspaceProbe,
     extraEnv,
   })
   return withEffortReport(spec.dir, piOutcome)
 }
 
+/**
+ * The workspace probe for one agent pass: each of the pass's working trees, baselined against its
+ * own HEAD as this pass begins.
+ *
+ * Reading HEAD is the one part that can fail benignly: a scaffold-from-scratch checkout has no
+ * commit yet, so `rev-parse HEAD` errors. That is no reason to leave the bound blind, since the
+ * dirty-tree half is exactly what answers a from-scratch build — so the pass baselines against
+ * the empty sha (`readHeadOrEmpty`, which the probe itself reads HEAD through for the same
+ * reason), and any commit the agent makes reads as HEAD having moved off it.
+ *
+ * A directory that is no git repository at all makes every probe THROW, which the driver treats
+ * as inconclusive: the bound re-arms and the run is neither killed nor left to the streak bounds
+ * alone. Deliberate, and the same disposition a transient git failure gets.
+ *
+ * WHICH trees is `spec.repoDirs`, defaulted HERE rather than at the call site so the rule that a
+ * pass with no declared checkouts is judged on its own directory lives with the builder that acts
+ * on it. Several of them compose into one probe over the whole workspace (see
+ * {@link composeWorkspaceProbes}); an empty list would silently disarm the bound, so it falls back
+ * to `dir` too.
+ */
+async function buildWorkspaceProbe(
+  spec: Pick<AgentRunSpec, 'dir' | 'repoDirs'>,
+  signal: AbortSignal | undefined,
+): Promise<WorkspaceProbe> {
+  const dirs = spec.repoDirs?.length ? spec.repoDirs : [spec.dir]
+  const probes = await Promise.all(
+    dirs.map(async (dir) =>
+      createWorkspaceProbe({
+        dir,
+        baseSha: await readHeadOrEmpty(dir, signal),
+        ...(signal ? { signal } : {}),
+      }),
+    ),
+  )
+  return composeWorkspaceProbes(probes)
+}
+
 /**
  * Whether the claude-code runner will install this run's skills natively (into the CLI's config
  * dir) rather than the caller materialising them into the checkout. True ONLY for a

package/src/pi.ts

@@ -3,6 +3,7 @@ import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { killChildProcess, spawnDetached } from './process.js'
+import { agentChildEnv } from './agent-env.js'
 import { pathExists } from './fs-utils.js'
 import { redactSecrets, secretsToRedact } from './redact.js'
 import { HarnessFailure } from './failure.js'
@@ -14,6 +15,8 @@ import {
   toolCallSignal,
   type ProgressGuardLimits,
 } from './progress-guard.js'
+import { createGuardDriver } from './guard-driver.js'
+import type { WorkspaceProbe } from './workspace-probe.js'
 import {
   ToolCallTracker,
   readToolCallId,
@@ -881,6 +884,13 @@ export function runPi(opts: {
   guardLimits?: ProgressGuardLimits
   /** Whether this run is expected to edit files (false for assess-only runs like the merger). */
   expectsEdits?: boolean
+  /**
+   * Probes the working tree for evidence the agent changed the repository — what the guard's
+   * no-edit bound is actually asking, as opposed to the tool names it can see. Injected (the
+   * guard stays pure) and consulted at most once per run, only when that bound is about to abort.
+   * Omitted ⇒ the bound falls back to its tool-name-only judgement.
+   */
+  workspaceProbe?: WorkspaceProbe
   /**
    * Extra environment for Pi's child process, merged over `process.env` (but under the
    * proxy token). Used to hand the rpiv-web-tools extension its proxy-backed SearXNG
@@ -898,7 +908,7 @@ export function runPi(opts: {
       ['-p', '--mode', 'json', '--model', `proxy/${opts.model}`, '--approve'],
       {
         cwd: opts.cwd,
-        env: { ...process.env, ...opts.extraEnv, PI_PROXY_TOKEN: opts.sessionToken },
+        env: agentChildEnv(opts.extraEnv, { PI_PROXY_TOKEN: opts.sessionToken }),
         // stdin is piped (not 'ignore') so the prompt is delivered out-of-band
         // rather than on argv — see the function doc for the injection rationale.
         stdio: ['pipe', 'pipe', 'pipe'],
@@ -934,10 +944,6 @@ export function runPi(opts: {
     // spam): `{`-leading lines that failed to JSON.parse, and observer-callback throws.
     let malformedLines = 0
     let observerErrors = 0
-    const guard = new ProgressGuard(
-      opts.guardLimits ?? progressGuardLimitsFromEnv(),
-      opts.expectsEdits ?? true,
-    )
     // Pairs each tool call's start with its result, numbers the pairs and captures the two
     // bodies (scrubbed + capped). A call whose start Pi never emitted still gets an entry,
     // timed from the previous call's end — see `ToolCallTracker`.
@@ -954,6 +960,21 @@ export function runPi(opts: {
     // and the no-progress guard; the `close` handler turns it into a rejection.
     const killChild = (): void => killChildProcess(child)
 
+    // The guard, plus the driver that settles its one bound needing evidence from outside this
+    // stream (see `guard-driver.ts`). `processLine` is a synchronous reader, so the driver owns
+    // the probe's lifetime rather than this handler awaiting inside it.
+    const guardDriver = createGuardDriver({
+      guard: new ProgressGuard(
+        opts.guardLimits ?? progressGuardLimitsFromEnv(),
+        opts.expectsEdits ?? true,
+      ),
+      probe: opts.workspaceProbe,
+      onAbort: (reason) => {
+        guardReason = reason
+        killChild()
+      },
+    })
+
     // Parse each complete JSONL record once, retaining it for the close-of-run reductions and
     // feeding the todo-progress emitter and the no-progress guard. A tripped guard kills Pi
     // with a diagnostic the run then fails on.
@@ -1008,13 +1029,7 @@ export function runPi(opts: {
           }
         }
       }
-      if (!final && !guardReason && !aborted) {
-        const reason = guard.observe(event)
-        if (reason) {
-          guardReason = reason
-          killChild()
-        }
-      }
+      if (!final && !guardReason && !aborted) guardDriver.observeEvent(event)
     }
 
     // Pi's json mode is strict LF-framed JSONL; the reader buffers partial records across

package/src/progress-guard.ts

@@ -104,8 +104,14 @@ export const DEFAULT_PROGRESS_GUARD_LIMITS = {
 // broad on purpose: different models/extensions name the same capability differently
 // (`edit`/`write`, but also `apply_patch`/`patch`/`str_replace`/`multiedit`/`create`),
 // and a false "no edits" reading would kill a run that IS making changes. Matched
-// case-insensitively. NOTE: a file written purely via `bash` (e.g. a heredoc) is not
-// recognised here — broaden or move to a working-tree signal if that becomes common.
+// case-insensitively.
+//
+// A file written purely through `bash` (a heredoc, `sed -i`, `node -e`) is NOT recognised here,
+// and deliberately so: this set answers "did the model call a tool we already know edits files",
+// which is a cheap SUFFICIENT condition and never a necessary one. The necessary one is the
+// working tree itself, which is what the no-edit bound now actually decides on: see the
+// `needs-workspace-evidence` verdict and {@link ProgressGuard.noteWorkspaceMutation}. A hit here
+// still satisfies the bound outright, so the common case never pays for a probe.
 const FILE_EDIT_TOOLS = new Set([
   'edit',
   'write',
@@ -274,11 +280,32 @@ export function mergeGuardLimits(
 }
 
 /**
- * Live anti-rabbithole guard: fed each streamed Pi event, it returns a diagnostic
- * reason the moment a run has plainly stopped making progress, so the harness can
- * kill Pi early instead of letting it burn the whole budget (and then surface a
- * useful failure instead of a generic "no file changes"). Pure and incremental so
- * it can be unit-tested over a fixed event sequence.
+ * What the guard concluded from one tool-call signal.
+ *
+ * `abort` is a settled judgement the caller acts on 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.
+ *
+ * `needs-workspace-evidence` is the no-edit bound, and it is deliberately NOT settled. That bound
+ * asks "has this run changed the repository yet", and the tool names are only a proxy for it: an
+ * agent writing files through `bash` reads as forty calls and no edits however much work it did.
+ * So the guard hands the question back with the diagnostic it would abort on, and the caller
+ * answers it from the working tree (see `workspace-probe.ts`) before anything is killed.
+ */
+export type ProgressVerdict =
+  | { kind: 'abort'; reason: string }
+  | { kind: 'needs-workspace-evidence'; reason: string }
+
+/**
+ * Live anti-rabbithole guard: fed each streamed tool-call signal, it returns a {@link
+ * ProgressVerdict} the moment a run has plainly stopped making progress, so the harness can kill
+ * the CLI early instead of letting it burn the whole budget (and then surface a useful failure
+ * instead of a generic "no file changes").
+ *
+ * PURE, SYNCHRONOUS and INCREMENTAL, so it can be unit-tested over a fixed event sequence: it
+ * spawns nothing and reads nothing off disk. The one bound that needs evidence from outside the
+ * stream says so in its verdict and lets the caller fetch it, then reports the answer back
+ * through {@link noteWorkspaceMutation} / {@link rearmNoEditBound}.
  */
 export class ProgressGuard {
   private toolCalls = 0
@@ -287,6 +314,11 @@ export class ProgressGuard {
   private consecutiveWebCalls = 0
   private consecutiveMcpCalls = 0
   private consecutiveNonActionCalls = 0
+  // Set when the no-edit bound has been reported as `needs-workspace-evidence` and the caller's
+  // probe has not answered yet. It suppresses a second report: the bound is a threshold, so every
+  // action call past it would otherwise re-raise the same unanswered question and the caller would
+  // probe git once per tool call. Cleared by whichever answer comes back.
+  private awaitingWorkspaceEvidence = false
 
   constructor(
     private readonly limits: ProgressGuardLimits,
@@ -294,30 +326,61 @@ export class ProgressGuard {
     private readonly expectsEdits: boolean = true,
   ) {}
 
-  /** Feed one parsed Pi event; returns a diagnostic reason when the run should abort, else null. */
-  observe(event: Record<string, unknown>): string | null {
+  /** Feed one parsed Pi event; returns a {@link ProgressVerdict} when the run is in trouble, else null. */
+  observe(event: Record<string, unknown>): ProgressVerdict | null {
     const tool = toolCallSignal(event)
     if (!tool) return null
     return this.observeSignal(tool)
   }
 
   /**
-   * Feed one already-parsed tool-call signal (name + error flag), returning a diagnostic reason
-   * when the run should abort, else null. Split out of {@link observe} so a caller whose stream
+   * Record that the run HAS changed the repository, however it did it. Satisfies the no-edit
+   * bound permanently, exactly as a recognised edit-tool call does, matching that bound's
+   * existing semantics: it guards a run only UNTIL its first edit, because an agent that has
+   * changed the tree has demonstrably started the work.
+   *
+   * Called by the driver when a workspace probe answers a `needs-workspace-evidence` verdict
+   * positively. Idempotent, and cheap enough that a caller who probes for other reasons may also
+   * report through it.
+   */
+  noteWorkspaceMutation(): void {
+    this.edits++
+    this.awaitingWorkspaceEvidence = false
+  }
+
+  /**
+   * Re-arm the no-edit bound after a probe that could answer NEITHER way (it threw). The bound
+   * becomes trippable again once another `maxToolCallsWithoutEdit` action calls have gone by,
+   * rather than the run being killed on a git failure or left permanently unguarded by one.
+   *
+   * Failing open here is the deliberate half: killing a productive run is the expensive error,
+   * and the streak bounds, the inactivity watchdog and the job's wall-clock cap all still hold
+   * the run in the meantime.
+   */
+  rearmNoEditBound(): void {
+    this.toolCalls = 0
+    this.awaitingWorkspaceEvidence = false
+  }
+
+  /**
+   * Feed one already-parsed tool-call signal (name + error flag), returning a {@link
+   * ProgressVerdict} when a bound is reached, else null. Split out of {@link observe} so a caller whose stream
    * is NOT Pi's `tool_execution_end` envelope — the claude-code runner, which correlates a
    * `tool_use` block's name with its `tool_result`'s `is_error` — can drive the SAME guard logic
    * without synthesising a fake Pi event.
    */
-  observeSignal(tool: { name: string; isError: boolean }): string | null {
+  observeSignal(tool: { name: string; isError: boolean }): ProgressVerdict | null {
     const name = tool.name.toLowerCase()
     // The error streak tracks ANY tool call (a planning call still proves the agent
     // isn't wedged in a failing-op loop), so it's updated before the planning skip.
     this.consecutiveErrors = tool.isError ? this.consecutiveErrors + 1 : 0
     if (this.consecutiveErrors >= this.limits.maxConsecutiveErrors) {
-      return (
-        `no progress: ${this.consecutiveErrors} consecutive failing tool calls — the agent is stuck ` +
-        `retrying a failing operation rather than making progress. Aborting.`
-      )
+      return {
+        kind: 'abort',
+        reason:
+          `no progress: ${this.consecutiveErrors} consecutive failing tool calls — the agent is stuck ` +
+          `retrying a failing operation rather than making progress. Aborting.`,
+      }
     }
 
     // Web search/fetch loop: web tools are read-only (they don't count toward the
@@ -328,10 +391,12 @@ export class ProgressGuard {
       const webCap =
         this.limits.maxConsecutiveWebCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls
       if (this.consecutiveWebCalls >= webCap) {
-        return (
-          `no progress: ${this.consecutiveWebCalls} consecutive web search/fetch calls without ` +
-          `any other action — the agent is stuck researching instead of doing the work. Aborting.`
-        )
+        return {
+          kind: 'abort',
+          reason:
+            `no progress: ${this.consecutiveWebCalls} consecutive web search/fetch calls without ` +
+            `any other action — the agent is stuck researching instead of doing the work. Aborting.`,
+        }
       }
     } else {
       this.consecutiveWebCalls = 0
@@ -345,11 +410,13 @@ export class ProgressGuard {
       const mcpCap =
         this.limits.maxConsecutiveMcpCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls
       if (this.consecutiveMcpCalls >= mcpCap) {
-        return (
-          `no progress: ${this.consecutiveMcpCalls} consecutive tool-server (MCP) calls without ` +
-          `any other action. The agent is stuck querying its tools instead of doing the work. ` +
-          `Aborting.`
-        )
+        return {
+          kind: 'abort',
+          reason:
+            `no progress: ${this.consecutiveMcpCalls} consecutive tool-server (MCP) calls without ` +
+            `any other action. The agent is stuck querying its tools instead of doing the work. ` +
+            `Aborting.`,
+        }
       }
     } else {
       this.consecutiveMcpCalls = 0
@@ -377,11 +444,13 @@ export class ProgressGuard {
         this.limits.maxConsecutiveNonActionCalls ??
         DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls
       if (this.consecutiveNonActionCalls >= nonActionCap) {
-        return (
-          `no progress: ${this.consecutiveNonActionCalls} consecutive read-only calls (searching, ` +
-          `reading, tool-server lookups, subagent dispatches) with no action call between them. ` +
-          `The agent is cycling through research instead of doing the work. Aborting.`
-        )
+        return {
+          kind: 'abort',
+          reason:
+            `no progress: ${this.consecutiveNonActionCalls} consecutive read-only calls (searching, ` +
+            `reading, tool-server lookups, subagent dispatches) with no action call between them. ` +
+            `The agent is cycling through research instead of doing the work. Aborting.`,
+        }
       }
       return null
     }
@@ -389,15 +458,22 @@ export class ProgressGuard {
     this.toolCalls++
     if (FILE_EDIT_TOOLS.has(name)) this.edits++
 
+    // PROVISIONAL, not settled: the tool names say no recognised edit tool was called, which is
+    // not the same fact as "the repository is unchanged". The caller answers that from the
+    // working tree and reports back; until it does, the question is not re-raised.
     if (
       this.expectsEdits &&
       this.edits === 0 &&
+      !this.awaitingWorkspaceEvidence &&
       this.toolCalls >= this.limits.maxToolCallsWithoutEdit
     ) {
-      return (
-        `no progress: ${this.toolCalls} tool calls and not one file edit — the agent is exploring or ` +
-        `probing the environment without implementing anything. Aborting before it burns the whole run.`
-      )
+      this.awaitingWorkspaceEvidence = true
+      return {
+        kind: 'needs-workspace-evidence',
+        reason:
+          `no progress: ${this.toolCalls} tool calls and no recognised file edit — the agent may be ` +
+          `exploring or probing the environment without implementing anything.`,
+      }
     }
     return null
   }

package/src/runner.ts

@@ -116,7 +116,7 @@ export interface RunOptions {
   log?: Logger
   /**
    * Extra environment for the agent's child process, scoped to THIS job. The CLI is spawned with
-   * `{...process.env, ...agentEnv}`, so these reach the agent and every shell tool it spawns.
+   * `agentChildEnv(agentEnv)`, so these reach the agent and every shell tool it spawns.
    *
    * This is the seam for anything per-job that would otherwise be written to a process- or
    * HOME-global (the tester's secrets, a private-registry npmrc pointer). Those globals are only