@cat-factory/executor-harness 1.132.1 → 1.134.0

package/dist/infra-standup.js

@@ -0,0 +1,182 @@
+// 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 { probeDockerServing, readDockerStatus, resolveDockerVerdict, } from './docker-status.js';
+import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
+import { captureRedactedOutput, redactSecrets } from './redact.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, infra, signal, logger, probe = probeDockerServing) {
+    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;
+        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, workDir, infra, opts, logger) {
+    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) {
+    const notes = [];
+    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, infra) {
+    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/dist/job.d.ts

@@ -546,6 +546,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. */

package/dist/multi-repo-coding.d.ts

@@ -14,3 +14,20 @@ import type { RunOptions } from './runner.js';
  * git helpers, so the per-repo clone/commit/push/PR mechanics match the single-repo path exactly.
  */
 export declare function runMultiRepoCoding(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;
+/**
+ * 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 declare function probeDirsForLegs(legs: readonly {
+    dir: string;
+    readOnly?: boolean;
+}[]): string[];

package/dist/multi-repo-coding.js

@@ -1,7 +1,8 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { makeDirClaimer } from './checkout-dir.js';
-import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, 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';
@@ -143,6 +144,8 @@ export async function runMultiRepoCoding(job, opts = {}) {
             ...(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);
         // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.
         const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts, root, prTemplate);
@@ -288,6 +291,32 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
         }
     }
 }
+/**
+ * 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) {
+    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, salvageOnly) {
+    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,
@@ -323,19 +352,37 @@ prTemplate) {
         const agentPrDescription = (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) {
@@ -351,7 +398,7 @@ prTemplate) {
                 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/dist/pi-workspace.d.ts

@@ -43,6 +43,17 @@ export declare function acquireRepoCheckout<T>(opts: {
 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. */

package/dist/pi-workspace.js

@@ -6,6 +6,7 @@ import { readEffortReport } from './effort.js';
 import { log } from './logger.js';
 import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, phasedProxyBaseUrl, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
 import { mergeGuardLimits, progressGuardLimitsFromEnv, } from './progress-guard.js';
+import { composeWorkspaceProbes, createWorkspaceProbe, readHeadOrEmpty, } from './workspace-probe.js';
 import { runSubscriptionHarness } from './agent-runner.js';
 // The thin base every container agent shares: an ephemeral working directory, and
 // one Pi run inside it driven by the harness-written context. The agents differ in
@@ -167,6 +168,19 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     if (spec.skills?.length && !installsSkillNatively(spec)) {
         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,
@@ -201,6 +215,8 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             // 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
@@ -283,10 +299,41 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         // 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, signal) {
+    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/dist/pi.d.ts

@@ -1,5 +1,6 @@
 import type { EffortReport } from './effort.js';
 import { type ProgressGuardLimits } from './progress-guard.js';
+import type { WorkspaceProbe } from './workspace-probe.js';
 import { type PiRunStats, type RunDiagnostics } from './pi-reduction.js';
 import { type ToolProgressWindow } from './tool-silence.js';
 /**
@@ -314,6 +315,21 @@ export interface HarnessCallMetric {
      * turn. `CliInlineLanguageModel`'s step-level row is the same idea on the inline path.
      */
     standsForJob?: boolean;
+    /**
+     * This row carries only TOKENS and stands for no model call of its own, so the backend counts it
+     * in every token sum and in no `calls` figure.
+     *
+     * Separate from {@link standsForJob}, which is only about the missing TURN ordinal. The
+     * shortfall row occupies no turn either way, but when the CLI narrated NO turns at all it is the
+     * job's only record and IS the call — nothing else recorded it, and a count excluding it would
+     * report a step that burned tokens across zero calls. The producer is the only layer that can
+     * tell the two apart: the backend sees one BATCH of a job's calls at a time (the live drain
+     * splits them across polls), so it cannot ask whether any turn was narrated.
+     *
+     * Absent on every real turn. `CliInlineLanguageModel.fileUnaccounted` makes the same split on
+     * the inline path, off its own `reported > 0`.
+     */
+    spendOnly?: boolean;
 }
 /**
  * Publish one captured model call: append it to the run's list (which becomes the terminal
@@ -423,6 +439,13 @@ export declare 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

package/dist/pi.js

@@ -3,11 +3,13 @@ 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';
 import { log } from './logger.js';
 import { ProgressGuard, progressGuardLimitsFromEnv, toolCallSignal, } from './progress-guard.js';
+import { createGuardDriver } from './guard-driver.js';
 import { ToolCallTracker, readToolCallId, toolCallResult, toolCallStart, } from './tool-trajectory.js';
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js';
 import { PI_MAX_OUTPUT_TOKENS, PiRunReducer, isObject, } from './pi-reduction.js';
@@ -562,7 +564,7 @@ export function runPi(opts) {
         }
         const child = spawn('pi', ['-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'],
@@ -597,7 +599,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`.
@@ -612,6 +613,17 @@ export function runPi(opts) {
         // SIGTERM first, then SIGKILL if Pi ignores it. Shared by the watchdog abort
         // and the no-progress guard; the `close` handler turns it into a rejection.
         const killChild = () => 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.
@@ -668,13 +680,8 @@ 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
         // chunks (bounded — see `JsonlLineReader`) so we only ever parse complete ones.

package/dist/progress-guard.d.ts

@@ -82,11 +82,35 @@ export declare function progressGuardLimitsFromEnv(env?: NodeJS.ProcessEnv): Pro
  */
 export declare function mergeGuardLimits(base: ProgressGuardLimits, overrides: Partial<ProgressGuardLimits> | undefined): ProgressGuardLimits;
 /**
- * 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 declare class ProgressGuard {
     private readonly limits;
@@ -98,14 +122,36 @@ export declare class ProgressGuard {
     private consecutiveWebCalls;
     private consecutiveMcpCalls;
     private consecutiveNonActionCalls;
+    private awaitingWorkspaceEvidence;
     constructor(limits: ProgressGuardLimits, 
     /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
     expectsEdits?: boolean);
-    /** 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
-     * 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
+     * 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.
@@ -113,5 +159,5 @@ export declare class ProgressGuard {
     observeSignal(tool: {
         name: string;
         isError: boolean;
-    }): string | null;
+    }): ProgressVerdict | null;
 }