@cat-factory/executor-harness 1.132.3 → 1.135.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,12 +1,14 @@
 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';
 import { log } from './logger.js';
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
+import { agentCapabilities } from './agent-shared.js';
 import { resolvePrTemplateNote, withPrTemplateNote, } from './pr-template.js';
 import { noChangesReason } from './coding-agent.js';
 /**
@@ -132,17 +134,16 @@ export async function runMultiRepoCoding(job, opts = {}) {
             proxyBaseUrl: job.proxyBaseUrl,
             proxyPhasePath: job.proxyPhasePath,
             sessionToken: job.sessionToken,
-            webToolsGuidance: job.webToolsGuidance,
-            webSearchProxy: job.webSearch,
             guardLimits: job.guardLimits,
             ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
-            // Skills + tool servers apply to a multi-repo run exactly as to a single-repo one: they
-            // are properties of the AGENT KIND, not of the checkout layout.
-            ...(job.skills?.length ? { skills: job.skills } : {}),
-            ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
-            ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
-            ...(job.designImages ? { designImages: job.designImages } : {}),
+            // Skills, tool servers and web research apply to a multi-repo run exactly as to a
+            // single-repo one: they are properties of the AGENT KIND, not of the checkout layout.
+            // Through the shared helper rather than re-spread here, which is what let this flow
+            // drift from the single-repo one in the first place.
+            ...agentCapabilities(job),
             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 +289,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 +350,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 +396,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
@@ -131,6 +132,80 @@ export async function checkoutHasBlueprints(dir, multiRepo) {
     const checks = await Promise.all(legs.filter((e) => e.isDirectory()).map((e) => isBlueprintDir(join(dir, e.name))));
     return checks.some(Boolean);
 }
+/**
+ * Run one pass on a SUBSCRIPTION harness (Claude Code / Codex): the leased-credential path, which
+ * shares only the checkout preparation with the Pi one.
+ *
+ * Split out of {@link runAgentInWorkspace} for its cyclomatic budget. It is also the honest seam:
+ * everything here is a decision about what the vendor's own CLI is handed, while everything left
+ * behind is about the proxy-backed Pi run.
+ */
+async function runSubscriptionInWorkspace(harness, spec, opts, prepared) {
+    const { contextFiles, imageGuidance, workspaceProbe } = prepared;
+    // Ambient (native) mode authenticates with the developer's own CLI login, so no
+    // leased token is required; otherwise the leased subscription token is mandatory.
+    if (!spec.ambientAuth && !spec.subscriptionToken) {
+        throw new Error(`The ${harness} harness requires a subscription token`);
+    }
+    const subOutcome = await runSubscriptionHarness(harness, {
+        cwd: spec.dir,
+        model: spec.model,
+        systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${imageGuidance}`,
+        userPrompt: spec.userPrompt,
+        ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
+        subscriptionBaseUrl: spec.subscriptionBaseUrl,
+        ...(spec.ambientAuth ? { ambientAuth: true } : {}),
+        ...(spec.skills?.length ? { skills: spec.skills } : {}),
+        ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
+        // Codex's own image tool. Passed for both subscription harnesses because the option lives on
+        // the shared run options; `runClaudeCode` ignores it, since claude-code has no such tool and
+        // (unlike an MCP server) there is nothing to report as unservable — the backend never
+        // resolves a codex-served generator onto a claude-code step, because admission refuses it.
+        ...(spec.generateImages ? { generateImages: true } : {}),
+        // `spec.webSearchProxy` is deliberately NOT forwarded. It states whether OUR PROXY serves web
+        // research for this run's account, which is what Pi's tools ride and what they would fail
+        // without; neither subscription CLI touches that proxy. Claude Code's `WebSearch`/`WebFetch`
+        // are served by the vendor the leased subscription already pays and are declared
+        // unconditionally (see `CLAUDE_TOOL_SET`), and Codex's surface is per-tool config rather than
+        // a list. Passing the proxy's availability here would withhold working tools on the strength
+        // of an unrelated deployment's wiring.
+        ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
+        signal: opts.signal,
+        // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
+        // defaults merged loosen-only with the kind's tuning + the backend's complexity-scaled
+        // no-edit allowance, so a claude-code run that stops making progress is killed early
+        // instead of burning the full wall-clock budget. The claude runner consumes it; codex
+        // 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
+        // and a proxied one produce the same evidence rather than one of them producing none.
+        onSpan: opts.onSpan,
+        // The tool-silence window (stuck-run audit F13), opened by whichever CLI actually runs.
+        // Wired for BOTH subscription harnesses: each reports tool activity on its own stream, so
+        // each can beat the window it opens.
+        beginToolWindow: opts.beginToolWindow,
+        // Per-slice review capture, so a parallel review's finished slices are persisted as they
+        // land rather than only in the terminal output. Only the subscription runners fan work out
+        // across subagents, so this is the only path that can produce it.
+        onSliceReviews: opts.onSliceReviews,
+        // What the CLI reported about the tool servers it loaded. Wired for BOTH subscription
+        // harnesses even though only claude-code's stream carries the report today: the hook is a
+        // pass-through, and a codex run that never calls it leaves the backend's record honestly
+        // absent rather than claiming every server it wired failed to start.
+        onToolServers: opts.onToolServers,
+        // Stream this run's per-call telemetry to the job's live drain. The subscription
+        // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
+        // proxy as they happen), so this is the only path that needs the hook.
+        onCallMetric: opts.onCallMetric,
+        ...(opts.log ? { log: opts.log } : {}),
+    });
+    return withEffortReport(spec.dir, subOutcome);
+}
 /**
  * Write Pi's global agent context (`~/.pi/agent/AGENTS.md`) + provider config,
  * then run Pi once in `spec.dir` and return its summary/stats/stderr. The context
@@ -167,65 +242,28 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     if (spec.skills?.length && !installsSkillNatively(spec)) {
         await materializeSkillResources(spec.dir, spec.skills);
     }
-    // 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,
-    // push, watchdogs) is unchanged.
+    // 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, push, watchdogs) is unchanged.
     if (spec.harness === 'claude-code' || spec.harness === 'codex') {
-        // Ambient (native) mode authenticates with the developer's own CLI login, so no
-        // leased token is required; otherwise the leased subscription token is mandatory.
-        if (!spec.ambientAuth && !spec.subscriptionToken) {
-            throw new Error(`The ${spec.harness} harness requires a subscription token`);
-        }
-        const subOutcome = await runSubscriptionHarness(spec.harness, {
-            cwd: spec.dir,
-            model: spec.model,
-            systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${imageGuidance}`,
-            userPrompt: spec.userPrompt,
-            ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
-            subscriptionBaseUrl: spec.subscriptionBaseUrl,
-            ...(spec.ambientAuth ? { ambientAuth: true } : {}),
-            ...(spec.skills?.length ? { skills: spec.skills } : {}),
-            ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
-            // Codex's own image tool. Passed for both subscription harnesses because the option lives on
-            // the shared run options; `runClaudeCode` ignores it, since claude-code has no such tool and
-            // (unlike an MCP server) there is nothing to report as unservable — the backend never
-            // resolves a codex-served generator onto a claude-code step, because admission refuses it.
-            ...(spec.generateImages ? { generateImages: true } : {}),
-            ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
-            signal: opts.signal,
-            // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
-            // defaults merged loosen-only with the kind's tuning + the backend's complexity-scaled
-            // no-edit allowance, so a claude-code run that stops making progress is killed early
-            // instead of burning the full wall-clock budget. The claude runner consumes it; codex
-            // ignores it for now (its stream isn't wired to the guard).
-            guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
-            expectsEdits: spec.expectsEdits ?? true,
-            onActivity: opts.onActivity,
-            onProgress: opts.onProgress,
-            // The run's tool-call trajectory, the same hook the Pi path feeds — so a subscription run
-            // and a proxied one produce the same evidence rather than one of them producing none.
-            onSpan: opts.onSpan,
-            // The tool-silence window (stuck-run audit F13), opened by whichever CLI actually runs.
-            // Wired for BOTH subscription harnesses: each reports tool activity on its own stream, so
-            // each can beat the window it opens.
-            beginToolWindow: opts.beginToolWindow,
-            // Per-slice review capture, so a parallel review's finished slices are persisted as they
-            // land rather than only in the terminal output. Only the subscription runners fan work out
-            // across subagents, so this is the only path that can produce it.
-            onSliceReviews: opts.onSliceReviews,
-            // What the CLI reported about the tool servers it loaded. Wired for BOTH subscription
-            // harnesses even though only claude-code's stream carries the report today: the hook is a
-            // pass-through, and a codex run that never calls it leaves the backend's record honestly
-            // absent rather than claiming every server it wired failed to start.
-            onToolServers: opts.onToolServers,
-            // Stream this run's per-call telemetry to the job's live drain. The subscription
-            // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
-            // proxy as they happen), so this is the only path that needs the hook.
-            onCallMetric: opts.onCallMetric,
-            ...(opts.log ? { log: opts.log } : {}),
+        return await runSubscriptionInWorkspace(spec.harness, spec, opts, {
+            contextFiles,
+            imageGuidance,
+            workspaceProbe,
         });
-        return withEffortReport(spec.dir, subOutcome);
     }
     if (!spec.proxyBaseUrl || !spec.sessionToken) {
         throw new Error('The Pi harness requires proxyBaseUrl and sessionToken');
@@ -283,10 +321,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';
 /**
@@ -438,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