@cat-factory/executor-harness 1.127.1 → 1.131.0

package/dist/agent.d.ts

@@ -53,6 +53,22 @@ export declare function testSecretEnv(secrets: TestSecretSpec[] | undefined): Re
  * `process.env` — and a second copy is a second place to forget the redaction.
  */
 export declare function secretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string>;
+/**
+ * Which refs a REUSED (warm-pool) explore checkout must end up holding: the branch to explore, and
+ * the repo's own base branch beside it.
+ *
+ * Its own function, and named, because the bug it removes is a swap between two branch names both
+ * in scope at the call site, and nothing downstream can tell them apart. A read-only reviewer's
+ * whole instruction is `git diff origin/<base>...HEAD`, so the base ref has to be as fresh as the
+ * branch: passing the explored branch as the base collapses the two refspecs into one, leaves
+ * `origin/<base>` at whatever tip the pool dir was first cloned at, and moves the merge base back
+ * to that tip. The diff then reports every commit merged into base since as part of the change
+ * under review, which is wrong in the direction nothing notices.
+ */
+export declare function exploreCheckoutRefs(job: Pick<AgentJob, 'branch' | 'repo'>): {
+    branch: string;
+    baseBranch: string;
+};
 /**
  * Whether a Ralph iteration ({@link AgentJob.validation} set) landed on a MULTI-REPO job (writable
  * peer repos or read-only reference repos). The post-commit validation command is only wired into

package/dist/agent.js

@@ -383,6 +383,21 @@ export function secretEnv(secrets) {
     registerKnownSecrets(secrets.map((s) => s.value));
     return Object.fromEntries(secrets.map(({ key, value }) => [key, value]));
 }
+/**
+ * Which refs a REUSED (warm-pool) explore checkout must end up holding: the branch to explore, and
+ * the repo's own base branch beside it.
+ *
+ * Its own function, and named, because the bug it removes is a swap between two branch names both
+ * in scope at the call site, and nothing downstream can tell them apart. A read-only reviewer's
+ * whole instruction is `git diff origin/<base>...HEAD`, so the base ref has to be as fresh as the
+ * branch: passing the explored branch as the base collapses the two refspecs into one, leaves
+ * `origin/<base>` at whatever tip the pool dir was first cloned at, and moves the merge base back
+ * to that tip. The diff then reports every commit merged into base since as part of the change
+ * under review, which is wrong in the direction nothing notices.
+ */
+export function exploreCheckoutRefs(job) {
+    return { branch: job.branch, baseBranch: job.repo.baseBranch };
+}
 /**
  * Read-only exploration: clone `branch`, run the agent making no edits, and return its
  * prose report — or, when `output.kind==='structured'`, the parsed JSON object as
@@ -408,12 +423,17 @@ async function runExploreMode(job, opts) {
         let workDir;
         if (job.persistentCheckout) {
             logger.info('agent(explore): preparing reused checkout');
+            // Both refs, resolved by {@link exploreCheckoutRefs}: which one is the base is the whole
+            // decision, so it is made there rather than inline here.
+            //
+            // `job.full` is deliberately not consulted: the fresh-clone leg inside
+            // `prepareExistingCheckout` always clones with full history, so a reused checkout already
+            // has the merge base a shallow explore clone would not.
             await prepareExistingCheckout({
                 dir,
                 repo: job.repo,
                 ghToken: job.ghToken,
-                branch: job.branch,
-                baseBranch: job.branch,
+                ...exploreCheckoutRefs(job),
                 existing: true,
                 signal: opts.signal,
             });
@@ -841,6 +861,10 @@ export function buildSingleRepoCodingSpec(job, pushBranch) {
         guardLimits: job.guardLimits,
         ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
         ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
+        // The task's linked documents, materialised into `.cat-context/` for the agent to read on
+        // demand. Every other caller of `runAgentInWorkspace` forwards these; this spread was the one
+        // that did not, so the implementer's prompt named files its checkout had never been given.
+        ...(job.contextFiles?.length ? { contextFiles: job.contextFiles } : {}),
         // Whether a pull request will open at all is exactly `job.pr` (see the `if (job.pr)` guard in
         // `runSingleRepoCoding`), and it is what decides whether the repo's PR template is worth
         // resolving. Read off the same field rather than a new job-body flag, so the two can't drift.

package/dist/coding-agent.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessAuthFields, ImageManifestSpec, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
+import type { ContextFileSpec, HarnessAuthFields, ImageManifestSpec, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
 import type { HarnessCallMetric } from './pi.js';
 import type { PiRunStats } from './pi-reduction.js';
 import { type EffortReport } from './effort.js';
@@ -99,6 +99,21 @@ export interface CodingAgentSpec extends HarnessAuthFields {
      * `docs/initiatives/bugfix-reproduction-proof.md`.
      */
     reproduction?: ReproductionSpec;
+    /**
+     * The run's LINKED CONTEXT documents (the task's attached brief, an RFC, a tracker issue body),
+     * materialised into `.cat-context/<path>` in the checkout and enumerated for the agent in its
+     * `AGENTS.md` context block. Absent ⇒ none.
+     *
+     * Carried here because the CODING agent is the one that needs them most and was the ONE path
+     * that dropped them: every sibling caller of {@link runAgentInWorkspace} (the explore paths, the
+     * conflict path, `multi-repo-coding.ts`) forwarded `job.contextFiles` and this one did not, so a
+     * task whose brief was too long for `description` and therefore rode an attached document
+     * reached the implementer as a prompt naming `.cat-context/<file>.md` and a checkout with no
+     * such directory. The agent then rebuilt the brief from whatever summary the prompt carried and
+     * reported the gap as a follow-up question, which is the most expensive way to discover a
+     * missing field spread.
+     */
+    contextFiles?: ContextFileSpec[];
     /**
      * The skills to make available for this run — a `skill` step's pick and/or the running kind's
      * declared playbooks. Threaded into {@link runAgentInWorkspace}, which installs them

package/dist/coding-agent.js

@@ -246,6 +246,8 @@ export async function runCodingAgent(spec, opts = {}) {
             webToolsGuidance: spec.webToolsGuidance,
             webSearchProxy: spec.webSearchProxy,
             guardLimits: spec.guardLimits,
+            // Materialised into `.cat-context/` and enumerated in the agent's AGENTS.md block.
+            ...(spec.contextFiles?.length ? { contextFiles: spec.contextFiles } : {}),
             ...(spec.skills?.length ? { skills: spec.skills } : {}),
             ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
             ...(spec.referenceScreenshots

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.127.1",
+  "version": "1.131.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",
@@ -25,14 +25,14 @@
     "access": "public"
   },
   "devDependencies": {
+    "@cat-factory/kernel": "0.318.0",
+    "@cat-factory/server": "0.305.0",
+    "@cat-factory/spend": "0.16.12",
     "@hono/node-server": "^2.1.1",
     "@types/node": "^26.2.0",
     "hono": "^4.13.3",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11",
-    "@cat-factory/kernel": "0.314.1",
-    "@cat-factory/server": "0.299.1",
-    "@cat-factory/spend": "0.16.7"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -464,6 +464,25 @@ export function secretEnv(secrets: TestSecretSpec[] | undefined): Record<string,
   return Object.fromEntries(secrets.map(({ key, value }) => [key, value]))
 }
 
+/**
+ * Which refs a REUSED (warm-pool) explore checkout must end up holding: the branch to explore, and
+ * the repo's own base branch beside it.
+ *
+ * Its own function, and named, because the bug it removes is a swap between two branch names both
+ * in scope at the call site, and nothing downstream can tell them apart. A read-only reviewer's
+ * whole instruction is `git diff origin/<base>...HEAD`, so the base ref has to be as fresh as the
+ * branch: passing the explored branch as the base collapses the two refspecs into one, leaves
+ * `origin/<base>` at whatever tip the pool dir was first cloned at, and moves the merge base back
+ * to that tip. The diff then reports every commit merged into base since as part of the change
+ * under review, which is wrong in the direction nothing notices.
+ */
+export function exploreCheckoutRefs(job: Pick<AgentJob, 'branch' | 'repo'>): {
+  branch: string
+  baseBranch: string
+} {
+  return { branch: job.branch, baseBranch: job.repo.baseBranch }
+}
+
 /**
  * Read-only exploration: clone `branch`, run the agent making no edits, and return its
  * prose report — or, when `output.kind==='structured'`, the parsed JSON object as
@@ -490,12 +509,17 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
       let workDir: string
       if (job.persistentCheckout) {
         logger.info('agent(explore): preparing reused checkout')
+        // Both refs, resolved by {@link exploreCheckoutRefs}: which one is the base is the whole
+        // decision, so it is made there rather than inline here.
+        //
+        // `job.full` is deliberately not consulted: the fresh-clone leg inside
+        // `prepareExistingCheckout` always clones with full history, so a reused checkout already
+        // has the merge base a shallow explore clone would not.
         await prepareExistingCheckout({
           dir,
           repo: job.repo,
           ghToken: job.ghToken,
-          branch: job.branch,
-          baseBranch: job.branch,
+          ...exploreCheckoutRefs(job),
           existing: true,
           signal: opts.signal,
         })
@@ -1000,6 +1024,10 @@ export function buildSingleRepoCodingSpec(
     guardLimits: job.guardLimits,
     ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
     ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
+    // The task's linked documents, materialised into `.cat-context/` for the agent to read on
+    // demand. Every other caller of `runAgentInWorkspace` forwards these; this spread was the one
+    // that did not, so the implementer's prompt named files its checkout had never been given.
+    ...(job.contextFiles?.length ? { contextFiles: job.contextFiles } : {}),
     // Whether a pull request will open at all is exactly `job.pr` (see the `if (job.pr)` guard in
     // `runSingleRepoCoding`), and it is what decides whether the repo's PR template is worth
     // resolving. Read off the same field rather than a new job-body flag, so the two can't drift.

package/src/coding-agent.ts

@@ -2,6 +2,7 @@ import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { runCapturedCommand } from './captured-command.js'
 import type {
+  ContextFileSpec,
   HarnessAuthFields,
   ImageManifestSpec,
   RepoSpec,
@@ -162,6 +163,21 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * `docs/initiatives/bugfix-reproduction-proof.md`.
    */
   reproduction?: ReproductionSpec
+  /**
+   * The run's LINKED CONTEXT documents (the task's attached brief, an RFC, a tracker issue body),
+   * materialised into `.cat-context/<path>` in the checkout and enumerated for the agent in its
+   * `AGENTS.md` context block. Absent ⇒ none.
+   *
+   * Carried here because the CODING agent is the one that needs them most and was the ONE path
+   * that dropped them: every sibling caller of {@link runAgentInWorkspace} (the explore paths, the
+   * conflict path, `multi-repo-coding.ts`) forwarded `job.contextFiles` and this one did not, so a
+   * task whose brief was too long for `description` and therefore rode an attached document
+   * reached the implementer as a prompt naming `.cat-context/<file>.md` and a checkout with no
+   * such directory. The agent then rebuilt the brief from whatever summary the prompt carried and
+   * reported the gap as a follow-up question, which is the most expensive way to discover a
+   * missing field spread.
+   */
+  contextFiles?: ContextFileSpec[]
   /**
    * The skills to make available for this run — a `skill` step's pick and/or the running kind's
    * declared playbooks. Threaded into {@link runAgentInWorkspace}, which installs them
@@ -508,6 +524,8 @@ export async function runCodingAgent(
             webToolsGuidance: spec.webToolsGuidance,
             webSearchProxy: spec.webSearchProxy,
             guardLimits: spec.guardLimits,
+            // Materialised into `.cat-context/` and enumerated in the agent's AGENTS.md block.
+            ...(spec.contextFiles?.length ? { contextFiles: spec.contextFiles } : {}),
             ...(spec.skills?.length ? { skills: spec.skills } : {}),
             ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
             ...(spec.referenceScreenshots