@cat-factory/executor-harness 1.135.0 → 1.139.0

package/dist/salvage.d.ts

@@ -126,6 +126,28 @@ export declare function salvageUntrackedWork(args: {
     signal?: AbortSignal;
     bounds?: SalvageBounds;
 }): Promise<SalvageReport>;
+/**
+ * Fold a later salvage pass onto an earlier one, so a run that salvaged TWICE reports what both
+ * passes did rather than only the last.
+ *
+ * A coding run salvages at each point where the next thing to happen reads COMMITS rather than the
+ * working tree: once before the pre-PR gates (which is what lets them run at all on a run whose
+ * only product is untracked files), and again at the settle, because a gate's repair round runs
+ * the agent afresh and can leave new files of its own. On almost every run the second pass is
+ * `none` (the first one already committed everything), so this is a cheap way to keep ONE honest
+ * report instead of two half-truths.
+ *
+ * Counts are summed only when BOTH passes committed, because only then are the two sets disjoint.
+ * A pass that refused or failed sees the same files again on the next pass, so summing there would
+ * double-count the one loss; instead the more significant status wins outright, `failed` over
+ * `refused` over `committed`, on the rule that a pass which could NOT keep its files is the fact a
+ * human has to act on and must not be hidden by a later pass that found nothing left to do. Ties
+ * take the later pass, whose numbers are the current ones.
+ *
+ * `withheld` is always the union: a credential-bearing file either pass declined to commit has to
+ * be named whatever else happened, since naming it is what lets someone rotate what it held.
+ */
+export declare function foldSalvageReports(previous: SalvageReport, next: SalvageReport): SalvageReport;
 /**
  * How the run that left these files behind ended. It decides what the commit message SAYS, which
  * is the whole point of marking a salvage: a commit arriving on a branch with no explanation is
@@ -159,6 +181,21 @@ export declare function salvageCommitMessage(fileCount: number, occasion: Salvag
  * into describing it differently. The caller decides WHERE it goes.
  */
 export declare function salvageOnlyNotice(): string;
+/**
+ * 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.
+ *
+ * Lives here rather than beside either caller because BOTH open pull requests off a salvage-only
+ * branch: the multi-repo push phase, per leg, and the single-repo one. It was the multi-repo path
+ * alone for a while, which meant the same branch shape opened an unmarked PR depending only on how
+ * many repositories the run happened to clone.
+ */
+export declare function withSalvageOnlyNote<T extends {
+    body: string;
+}>(pr: T, salvageOnly: boolean): T;
 /**
  * Where a salvage commit ENDED UP, which the salvage itself cannot know: it commits, and someone
  * else pushes. A commit that was not pushed dies with the container exactly as the uncommitted
@@ -174,7 +211,13 @@ export interface SalvageDelivery {
  * reports, so the person reading "the run was killed" is told in the same breath what became of
  * its work: on the branch and reviewed by nobody, still in the container, or never committed.
  *
+ * `occasion` is the SAME fact {@link salvageCommitMessage} is given, and for the same reason: how
+ * the run ended is what decides how much to trust the files. A run that was killed left them
+ * mid-thought; a run that settled simply never added them, and telling a human a clean run "was
+ * aborted" describes a failure that did not happen. The two texts had drifted precisely here,
+ * which is why the occasion is now a parameter of both rather than a constant inside one.
+ *
  * `delivery` is supplied by whoever pushed. Absent means the caller is on a path where the
  * ordinary push follows (the settle path), so there is nothing extra to say.
  */
-export declare function describeSalvage(report: SalvageReport, delivery?: SalvageDelivery): string | undefined;
+export declare function describeSalvage(report: SalvageReport, occasion: SalvageOccasion, delivery?: SalvageDelivery): string | undefined;

package/dist/salvage.js

@@ -206,6 +206,59 @@ export async function salvageUntrackedWork(args) {
         return { status: 'failed', ...report, reason };
     }
 }
+/**
+ * Fold a later salvage pass onto an earlier one, so a run that salvaged TWICE reports what both
+ * passes did rather than only the last.
+ *
+ * A coding run salvages at each point where the next thing to happen reads COMMITS rather than the
+ * working tree: once before the pre-PR gates (which is what lets them run at all on a run whose
+ * only product is untracked files), and again at the settle, because a gate's repair round runs
+ * the agent afresh and can leave new files of its own. On almost every run the second pass is
+ * `none` (the first one already committed everything), so this is a cheap way to keep ONE honest
+ * report instead of two half-truths.
+ *
+ * Counts are summed only when BOTH passes committed, because only then are the two sets disjoint.
+ * A pass that refused or failed sees the same files again on the next pass, so summing there would
+ * double-count the one loss; instead the more significant status wins outright, `failed` over
+ * `refused` over `committed`, on the rule that a pass which could NOT keep its files is the fact a
+ * human has to act on and must not be hidden by a later pass that found nothing left to do. Ties
+ * take the later pass, whose numbers are the current ones.
+ *
+ * `withheld` is always the union: a credential-bearing file either pass declined to commit has to
+ * be named whatever else happened, since naming it is what lets someone rotate what it held.
+ */
+export function foldSalvageReports(previous, next) {
+    if (next.status === 'none')
+        return withWithheld(previous, next);
+    if (previous.status === 'none')
+        return withWithheld(next, previous);
+    if (previous.status === 'committed' && next.status === 'committed') {
+        return withWithheld({
+            status: 'committed',
+            files: [...previous.files, ...next.files].slice(0, REPORTED_PATHS),
+            fileCount: previous.fileCount + next.fileCount,
+            totalBytes: previous.totalBytes + next.totalBytes,
+            ...((next.commitSha ?? previous.commitSha)
+                ? { commitSha: next.commitSha ?? previous.commitSha }
+                : {}),
+        }, previous);
+    }
+    return SALVAGE_STATUS_RANK[previous.status] > SALVAGE_STATUS_RANK[next.status]
+        ? withWithheld(previous, next)
+        : withWithheld(next, previous);
+}
+/** Which status a fold keeps when the two passes disagree; see {@link foldSalvageReports}. */
+const SALVAGE_STATUS_RANK = {
+    none: 0,
+    committed: 1,
+    refused: 2,
+    failed: 3,
+};
+/** `kept` with `other`'s withheld paths merged in, de-duplicated and order-preserving. */
+function withWithheld(kept, other) {
+    const union = [...new Set([...(kept.withheld ?? []), ...(other.withheld ?? [])])];
+    return union.length > 0 ? { ...kept, withheld: union } : kept;
+}
 /** The salvage commit's message: what it is, why it exists, and how much to trust it. */
 export function salvageCommitMessage(fileCount, occasion) {
     const noun = fileCount === 1 ? 'file' : 'files';
@@ -240,6 +293,21 @@ export function salvageOnlyNotice() {
         `not be discarded with the container. Nothing has reviewed them for completeness or ` +
         `relevance, and some may be scratch work from the agent's task in a sibling repository.`);
 }
+/**
+ * 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.
+ *
+ * Lives here rather than beside either caller because BOTH open pull requests off a salvage-only
+ * branch: the multi-repo push phase, per leg, and the single-repo one. It was the multi-repo path
+ * alone for a while, which meant the same branch shape opened an unmarked PR depending only on how
+ * many repositories the run happened to clone.
+ */
+export function withSalvageOnlyNote(pr, salvageOnly) {
+    return salvageOnly ? { ...pr, body: `${salvageOnlyNotice()}\n\n${pr.body}` } : pr;
+}
 /** Total size of `paths` under `dir`; a file that cannot be stat'd counts as zero rather than failing. */
 async function measure(dir, paths) {
     const sizes = await Promise.all(paths.map((path) => stat(join(dir, path)).then((info) => info.size, () => 0)));
@@ -250,15 +318,21 @@ async function measure(dir, paths) {
  * reports, so the person reading "the run was killed" is told in the same breath what became of
  * its work: on the branch and reviewed by nobody, still in the container, or never committed.
  *
+ * `occasion` is the SAME fact {@link salvageCommitMessage} is given, and for the same reason: how
+ * the run ended is what decides how much to trust the files. A run that was killed left them
+ * mid-thought; a run that settled simply never added them, and telling a human a clean run "was
+ * aborted" describes a failure that did not happen. The two texts had drifted precisely here,
+ * which is why the occasion is now a parameter of both rather than a constant inside one.
+ *
  * `delivery` is supplied by whoever pushed. Absent means the caller is on a path where the
  * ordinary push follows (the settle path), so there is nothing extra to say.
  */
-export function describeSalvage(report, delivery) {
-    const parts = [describeOutcome(report, delivery), describeWithheld(report)].filter((part) => part !== undefined);
+export function describeSalvage(report, occasion, delivery) {
+    const parts = [describeOutcome(report, occasion, delivery), describeWithheld(report)].filter((part) => part !== undefined);
     return parts.length > 0 ? parts.join(' ') : undefined;
 }
 /** The fate of the files the salvage DID try to keep. */
-function describeOutcome(report, delivery) {
+function describeOutcome(report, occasion, delivery) {
     switch (report.status) {
         case 'none':
             return undefined;
@@ -267,8 +341,11 @@ function describeOutcome(report, delivery) {
                 ? `commit ${report.commitSha ?? 'unknown'}, which could NOT be pushed ` +
                     `(${delivery.reason ?? 'the push failed'}) and so is lost with the container`
                 : `commit ${report.commitSha ?? 'unknown'}`;
+            const why = occasion.kind === 'aborted'
+                ? 'this run was aborted'
+                : 'the agent finished without committing them';
             return (`${report.fileCount} uncommitted new file(s) the agent left behind were salvaged into ` +
-                `${landed}; this run was aborted, so review them before trusting them.`);
+                `${landed}; ${why}, so review them before trusting them.`);
         }
         case 'refused':
             return `Uncommitted new files were NOT salvaged: ${report.reason ?? 'over the salvage bounds'}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.135.0",
+  "version": "1.139.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "devDependencies": {
     "@cat-factory/kernel": "0.321.0",
-    "@cat-factory/server": "0.306.5",
+    "@cat-factory/server": "0.306.7",
     "@cat-factory/spend": "0.16.17",
     "@hono/node-server": "^2.1.1",
     "@types/node": "^26.2.0",

package/src/agent-runner.ts

@@ -683,6 +683,17 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // The built-in tools this run declares, named ONCE: the same list rides `--tools` and the
   // `--allowedTools` re-grant, which is additive rather than inert (see `claudeAllowedToolPatterns`).
   const tools = CLAUDE_TOOL_SET
+  // ...but `--tools` itself is withheld from an ambient run, whose `claude` is the developer's own
+  // rather than this image's pinned one: an unrecognised FLAG fails the whole run, where an
+  // unrecognised tool NAME is merely dropped. See `claudeCliArgs`. The re-grant is unaffected
+  // (`--allowedTools` long predates this), so a tool-server run still unlocks what it wires.
+  const declareTools = opts.ambientAuth !== true
+  const declaredTools = declareTools ? tools : []
+  if (!declareTools) {
+    opts.log?.info(
+      'claude-code: taking the CLI’s default tool surface (ambient CLI, version unknown)',
+    )
+  }
 
   const secrets = opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : []
   const capture = openClaudeCallCapture(opts, { prompt, folded, secrets })
@@ -730,7 +741,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     reportToolServerStartup(event, opts.onToolServers)
     // The same startup event answers what the CLI granted of what we asked for; a capability it
     // named no tool for is a silent capability loss otherwise (see `assertClaudeToolsCurrent`).
-    assertClaudeToolsCurrent(event, tools, opts.log)
+    assertClaudeToolsCurrent(event, declaredTools, opts.log)
     // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
     // `telemetry` routes them off the parent's chain (and decides who bills them). Progress, slice
     // tracking, the guard and `stats` below deliberately see EVERY event: a subagent grinding on
@@ -820,7 +831,13 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     const { stderrTail } = await streamCli(
       {
         command: 'claude',
-        args: claudeCliArgs({ model: opts.model, tools, mcpArgs: home.mcpArgs, appendArgs }),
+        args: claudeCliArgs({
+          model: opts.model,
+          tools,
+          declareTools,
+          mcpArgs: home.mcpArgs,
+          appendArgs,
+        }),
       },
       prompt,
       { ...opts, signal: runSignal },

package/src/agent.ts

@@ -31,12 +31,14 @@ import {
 import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.js'
 import { applyPrDescription } from './pr-description.js'
+import { withSalvageOnlyNote } from './salvage.js'
 import { makeDirClaimer } from './checkout-dir.js'
 import { noChangesReason, runCodingAgent } from './coding-agent.js'
 import { runMultiRepoCoding } from './multi-repo-coding.js'
 import { validationFailureMessage } from './validation-checks.js'
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js'
 import { agentCapabilities, mergeEffort } from './agent-shared.js'
+import { appendEnvironmentInventory } from './environment-inventory.js'
 import { runBootstrap } from './bootstrap-mode.js'
 import {
   acquireRepoCheckout,
@@ -176,9 +178,28 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
       ...artifactUploadEnv(job.artifactUpload),
     })
     if (job.mode === 'preview') return await runPreviewMode(job, scoped)
-    return job.mode === 'coding'
-      ? await runCodingMode(job, scoped)
-      : await runExploreMode(job, scoped)
+    // THE composition point for the environment inventory (see `environment-inventory.ts`): the
+    // machine is probed ONCE here, before any mode branches, and the result is folded onto the
+    // job's own system prompt. Every mode, every repair round and all three agent CLIs read that
+    // one field, so none of them can end up without the block and none can carry it twice.
+    // `preview` returns above because it runs no agent at all, so there is no prompt to fold onto.
+    //
+    // This sits on the critical path AHEAD of the clone, which is the cost of having one
+    // composition point instead of one per mode (each mode owns its own clone, so there is no
+    // single post-clone place to put this). The pass is sized for that: everything in it runs
+    // concurrently, every probe is a call that answers in milliseconds or is wedged, and the one
+    // deliberate wait is a single short retry for a daemon that is still starting.
+
+    const staged: AgentJob = {
+      ...job,
+      systemPrompt: await appendEnvironmentInventory(job.systemPrompt, {
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(opts.log ? { log: opts.log } : {}),
+      }),
+    }
+    return staged.mode === 'coding'
+      ? await runCodingMode(staged, scoped)
+      : await runExploreMode(staged, scoped)
   } finally {
     if (scopeDir) await rm(scopeDir, { recursive: true, force: true }).catch(() => {})
   }
@@ -925,6 +946,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     reproductionReport,
     effortReport,
     prDescription,
+    salvageOnly,
   } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts)
   // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
   // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
@@ -1000,8 +1022,10 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ghToken: job.ghToken,
       head: pushBranch,
       base: job.repo.baseBranch,
-      // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text.
-      pr: applyPrDescription(job.pr, prDescription),
+      // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text,
+      // and a branch that is nothing but salvage says so above whichever body won: the agent
+      // committed nothing here, so no briefing on it describes a change anyone proposed.
+      pr: withSalvageOnlyNote(applyPrDescription(job.pr, prDescription), salvageOnly === true),
       // A resumed run's PR is already open, so refresh it rather than lose the briefing to the
       // duplicate-PR 422 — only from a REAL briefing (see `refreshExisting` for why).
       ...(prDescription ? { refreshExisting: true } : {}),

package/src/claude-cli.ts

@@ -141,6 +141,18 @@ export function claudeCliArgs(opts: {
   model: string
   /** The built-in tools this run asks for; see {@link CLAUDE_TOOL_SET}. */
   tools: readonly string[]
+  /**
+   * Whether to DECLARE that set with `--tools`, or take whatever the CLI defaults to.
+   *
+   * False for an `ambientAuth` run, which is the one case where the CLI is not this image's. A
+   * name the build does not carry is dropped silently, which is what makes {@link CLAUDE_TOOL_SET}
+   * safe to be over-inclusive, but that rule is about tool NAMES. An unrecognised FLAG is a
+   * different failure: the CLI exits before the run starts. Everywhere else the image pins the
+   * version and the flag is measured against it; on a developer's own machine the harness knows
+   * neither which `claude` is on the PATH nor how old it is, and the cost of guessing wrong is
+   * every local native run, not a thinner tool surface on one.
+   */
+  declareTools: boolean
   /** `--mcp-config` + `--strict-mcp-config` + any `--allowedTools`; empty when no server is wired. */
   mcpArgs: readonly string[]
   /** `--append-system-prompt <prompt>`, or empty when the prompt was folded into stdin. */
@@ -160,8 +172,7 @@ export function claudeCliArgs(opts: {
     '--model',
     opts.model,
     // Declared rather than defaulted: see this module's header for what the default set costs.
-    '--tools',
-    opts.tools.join(','),
+    ...(opts.declareTools ? ['--tools', opts.tools.join(',')] : []),
     ...opts.mcpArgs,
     ...opts.appendArgs,
   ]
@@ -180,6 +191,11 @@ export function claudeCliArgs(opts: {
  * Best-effort and never throws: a run whose tool surface is short is still a run, and the honest
  * disposition for a floor this image cannot verify is to SAY it could not be read, not to fail the
  * job and not to stay silent (which reads exactly like a satisfied request).
+ *
+ * `requested` is what the argv actually DECLARED, so an ambient run (which declares nothing, see
+ * {@link claudeCliArgs}) passes none and the line says the surface is the CLI's own default. The
+ * floor is still read back there: "the default set carries no search tool" and "we asked for one
+ * and did not get it" are both worth a line, and they are not the same fact or the same fix.
  */
 export function assertClaudeToolsCurrent(
   event: Record<string, unknown>,
@@ -192,7 +208,7 @@ export function assertClaudeToolsCurrent(
   const cliVersion = version ? { cliVersion: version } : {}
   if (!Array.isArray(event.tools)) {
     log.warn('claude-code announced no tool list, so this run has an unverified tool surface', {
-      requestedTools: [...requested],
+      ...(requested.length > 0 ? { requestedTools: [...requested] } : { toolsDeclared: false }),
       ...cliVersion,
     })
     return
@@ -202,7 +218,7 @@ export function assertClaudeToolsCurrent(
     (c) => c.capability,
   )
   const fields = {
-    requestedTools: [...requested],
+    ...(requested.length > 0 ? { requestedTools: [...requested] } : { toolsDeclared: false }),
     grantedTools: [...granted].sort(),
     ...cliVersion,
   }