@cat-factory/executor-harness 1.58.0 → 1.62.0

package/src/agent.ts

@@ -22,16 +22,16 @@ import {
   fetchReferenceBranches,
   hasAgentChanges,
   headCommit,
-  inferVcsProvider,
   mergeBranch,
-  openPullRequest,
   prepareExistingCheckout,
   pushBranch,
   reinitAndPush,
   unmergedPaths,
 } from './git.js'
+import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi.js'
 import type { EffortReport } from './effort.js'
+import { applyPrDescription } from './pr-description.js'
 import {
   makeDirClaimer,
   noChangesReason,
@@ -972,6 +972,10 @@ function buildSingleRepoCodingSpec(
     // Forwarded straight off the job body — the loop is generic machinery keyed on the data, not
     // on the agent kind.
     ...(job.validationChecks ? { validationChecks: job.validationChecks } : {}),
+    // Bugfix reproduction proof: the declared command run against the pre-fix and final trees
+    // (see docs/initiatives/bugfix-reproduction-proof.md). Forwarded straight off the job body —
+    // like the checks above, the loop is generic machinery keyed on the data, not the agent kind.
+    ...(job.reproduction ? { reproduction: job.reproduction } : {}),
   }
 }
 
@@ -992,17 +996,23 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     callMetrics,
     validation,
     validationReport,
+    reproductionReport,
     effortReport,
+    prDescription,
   } = 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`.
   const ralphVerdict = validation ? { ralphVerdict: validation } : {}
   // The agent's effort self-assessment, spread onto every result path below (mirrors ralphVerdict).
   const effort = effortReport ? { effortReport } : {}
-  // The pre-PR validation report, spread onto every result path below: on the passing path it is
-  // the captured proof the checkout was green when the PR opened; on the exhausted path it is the
-  // evidence behind the failure below. Absent when the service configured no checks.
-  const validationFields = validationReport ? { validationReport } : {}
+  // The two PRE-PR VERIFICATION reports, spread onto every result path below. The validation one:
+  // on the passing path it is the captured proof the checkout was green when the PR opened; on the
+  // exhausted path it is the evidence behind the failure below. The reproduction one is evidence
+  // on every path — it never gates the PR. Each is absent when its phase was not configured.
+  const verificationFields = {
+    ...(validationReport ? { validationReport } : {}),
+    ...(reproductionReport ? { reproductionReport } : {}),
+  }
 
   // Pre-PR validation spent its attempt budget with the checkout still red. FAIL the job — do
   // NOT open a pull request, and do not pretend the push succeeded as a deliverable. The work is
@@ -1022,7 +1032,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'agent',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
-      ...validationFields,
+      ...verificationFields,
       ...effort,
     }
   }
@@ -1038,7 +1048,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
-        ...validationFields,
+        ...verificationFields,
         ...effort,
       }
     }
@@ -1051,7 +1061,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'no-changes',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
-      ...validationFields,
+      ...verificationFields,
       ...effort,
     }
   }
@@ -1064,7 +1074,11 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ghToken: job.ghToken,
       head: pushBranch,
       base: job.repo.baseBranch,
-      pr: job.pr,
+      // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text.
+      pr: applyPrDescription(job.pr, prDescription),
+      // 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 } : {}),
       apiBase: job.githubApiBase,
       // The provider (set by the server from the configured backend) selects GitHub-PR vs
       // GitLab-MR authoritatively; the clone URL supplies the GitLab REST base + project path.
@@ -1086,7 +1100,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
           stats,
           ...(usage ? { usage } : {}),
           ...(callMetrics ? { callMetrics } : {}),
-          ...validationFields,
+          ...verificationFields,
           ...effort,
         }
       }
@@ -1103,7 +1117,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         failureCause: 'no-changes',
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
-        ...validationFields,
+        ...verificationFields,
         ...effort,
       }
     }
@@ -1116,7 +1130,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...ralphVerdict,
-      ...validationFields,
+      ...verificationFields,
       ...effort,
     }
   }
@@ -1128,7 +1142,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     ...(usage ? { usage } : {}),
     ...(callMetrics ? { callMetrics } : {}),
     ...ralphVerdict,
-    ...validationFields,
+    ...verificationFields,
     ...effort,
   }
 }

package/src/captured-command.ts

@@ -0,0 +1,144 @@
+import { spawn } from 'node:child_process'
+import { killChildProcess, spawnDetached } from './process.js'
+import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js'
+import type { RunOptions } from './runner.js'
+import type { Logger } from './logger.js'
+
+// The ONE way the harness runs a declared shell command on its own behalf (rather than through
+// the agent) and keeps a bounded, secret-scrubbed record of what it printed.
+//
+// Both pre-PR verification phases need exactly this — the PRE-PR VALIDATION checks
+// (`validation-checks.ts`) and the BUGFIX REPRODUCTION PROOF (`reproduction-proof.ts`) — and they
+// need it to behave IDENTICALLY: same watchdog semantics, same abort handling, same conventional
+// exit codes, same scrub-then-bound pipeline. They were two near-verbatim copies; a fix applied to
+// one of them (a redaction ordering, an exit-code convention) silently missed the other, which is
+// the whole reason this seam exists.
+//
+// Everything is PER-JOB by construction: the command, the cwd and the environment all arrive as
+// arguments and nothing is read from or written to `process.env`/`HOME`. The local NATIVE
+// transport serves every concurrent job from ONE host process, so a global would leak one job's
+// state into a sibling's — and the container path would never catch it.
+
+/**
+ * A little slack kept in the rolling capture buffer ON TOP of {@link MAX_CAPTURED_OUTPUT_CHARS},
+ * so scrubbing sees whole secrets.
+ *
+ * The buffer discards from the FRONT as output arrives, and `redactSecrets` only runs once the
+ * command settles. Without the margin a token straddling that rolling cut would already have lost
+ * its `KEY=` prefix by scrub time and would survive as an unrecognised partial. Capturing a bit
+ * more than we keep, scrubbing, and only THEN bounding to the real limit closes that window; 512
+ * chars comfortably exceeds any single credential assignment the rules match.
+ */
+const CAPTURE_MARGIN_CHARS = 512
+
+/** What one harness-spawned command did, as both phases record it. */
+export interface CapturedCommandResult {
+  /** Exit code (0 = pass); 124 on watchdog timeout, 127 on spawn failure, 130 on abort. */
+  exitCode: number
+  passed: boolean
+  /** Scrubbed output bounded to the caller's REPORT budget (what crosses the wire). */
+  outputTail?: string
+  durationMs: number
+  timedOut?: boolean
+  /**
+   * The FULL scrubbed tail (up to {@link MAX_CAPTURED_OUTPUT_CHARS}) for a repair prompt. Never
+   * leaves the container — the agent needs the whole failure to act on it, the wire does not.
+   */
+  fullTail?: string
+}
+
+/**
+ * Run ONE command as `sh -c` in `cwd`, capturing a bounded, secret-scrubbed tail of its combined
+ * stdout+stderr. The exit code is the verdict — computed here by the harness, never self-reported
+ * by the model, which is the whole point of a programmatic phase. A watchdog kills the process
+ * tree on timeout and an aborted run resolves non-zero, so a phase is never what blocks a job
+ * from settling.
+ *
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * not a mutated global: the harness spawns this itself rather than through the agent, so without
+ * the explicit merge a native-mode job would run without the private-registry npmrc pointer (and,
+ * had this been staged in `process.env`, against a sibling job's state).
+ *
+ * `logLabel`/`logFields` shape only the two warnings this runner emits itself (the watchdog kill
+ * and a spawn failure); the caller keeps its own start/finish logging, which knows what the
+ * command MEANS.
+ */
+export async function runCapturedCommand(args: {
+  cwd: string
+  command: string
+  timeoutMs: number
+  /** Bound for {@link CapturedCommandResult.outputTail} — the caller's per-report budget. */
+  reportTailChars: number
+  logLabel: string
+  logFields?: Record<string, unknown>
+  logger: Logger
+  opts: RunOptions
+}): Promise<CapturedCommandResult> {
+  const { cwd, command, timeoutMs, reportTailChars, logLabel, logFields, logger, opts } = args
+  const startedAt = Date.now()
+  return new Promise((resolve) => {
+    let out = ''
+    let settled = false
+    let timedOut = false
+    const child = spawn('sh', ['-c', command], {
+      cwd,
+      detached: spawnDetached,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, ...opts.agentEnv },
+    })
+    // Keep only the tail (plus the scrub margin); guard against unbounded buffering on a chatty
+    // command.
+    const capture = (chunk: Buffer): void => {
+      out = (out + chunk.toString('utf8')).slice(
+        -(MAX_CAPTURED_OUTPUT_CHARS + CAPTURE_MARGIN_CHARS),
+      )
+    }
+    child.stdout?.on('data', capture)
+    child.stderr?.on('data', capture)
+    const finish = (exitCode: number): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      opts.signal?.removeEventListener('abort', onAbort)
+      const trimmed = out.trim()
+      // Scrub BEFORE either bound: the pattern rules need a whole assignment to match, so the
+      // margin above is trimmed away only once the secrets are already gone.
+      const scrubbed = trimmed ? redactSecrets(trimmed).slice(-MAX_CAPTURED_OUTPUT_CHARS) : ''
+      resolve({
+        exitCode,
+        passed: exitCode === 0,
+        ...(scrubbed ? { outputTail: boundTail(scrubbed, reportTailChars) } : {}),
+        durationMs: Date.now() - startedAt,
+        ...(timedOut ? { timedOut: true } : {}),
+        ...(scrubbed ? { fullTail: scrubbed } : {}),
+      })
+    }
+    const timer = setTimeout(() => {
+      logger.warn(`${logLabel}: command timed out`, { ...logFields, timeoutMs })
+      timedOut = true
+      killChildProcess(child, undefined, logger)
+      finish(124) // conventional timeout exit code (a non-zero fail)
+    }, timeoutMs)
+    timer.unref?.()
+    const onAbort = (): void => {
+      killChildProcess(child, undefined, logger)
+      finish(130) // aborted (a non-zero fail)
+    }
+    opts.signal?.addEventListener('abort', onAbort, { once: true })
+    child.on('error', (err) => {
+      logger.warn(`${logLabel}: command failed to spawn`, {
+        ...logFields,
+        error: err instanceof Error ? err.message : String(err),
+      })
+      finish(127) // spawn error / command not found (a non-zero fail)
+    })
+    child.on('close', (code) => finish(code ?? 1))
+  })
+}
+
+/** Bound an already-scrubbed output tail to what a REPORT carries, saying what it dropped. */
+export function boundTail(scrubbed: string, maxChars: number): string {
+  if (scrubbed.length <= maxChars) return scrubbed
+  const trimmed = scrubbed.length - maxChars
+  return `…(${trimmed} earlier chars trimmed)\n${scrubbed.slice(-maxChars)}`
+}

package/src/coding-agent.ts

@@ -14,6 +14,7 @@ import type {
 } from './job.js'
 import {
   branchAheadOfBase,
+  changedFilesSinceBase,
   branchHasCommitsSince,
   cloneExistingBranch,
   cloneRepo,
@@ -23,15 +24,21 @@ import {
   fetchReferenceBranches,
   headCommit,
   listUntrackedFiles,
-  openPullRequest,
   prepareExistingCheckout,
   pushBranch,
   refreshFromBaseIfClean,
   remoteBranchExists,
 } from './git.js'
+import { openPullRequest } from './vcs-api.js'
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js'
 import type { HarnessCallMetric, PiRunStats } from './pi.js'
 import { EFFORT_REPORT_FILE, type EffortReport } from './effort.js'
+import {
+  type AgentPrDescription,
+  applyPrDescription,
+  PR_DESCRIPTION_FILE,
+  readPrDescription,
+} from './pr-description.js'
 import {
   acquireRepoCheckout,
   agentNeverActed,
@@ -47,6 +54,11 @@ import {
   type ValidationChecksSpec,
   type ValidationReport,
 } from './validation-checks.js'
+import {
+  runReproductionLoop,
+  type ReproductionReport,
+  type ReproductionSpec,
+} from './reproduction-proof.js'
 
 // The shared skeleton for the container coding agents that clone a repo, run Pi
 // against it and push the result on a branch. The implementation (`/run`) and
@@ -117,6 +129,16 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * `docs/initiatives/pre-pr-validation.md`.
    */
   validationChecks?: ValidationChecksSpec
+  /**
+   * BUGFIX REPRODUCTION PROOF: the run's declared reproduction command + test files. When set, the
+   * harness runs that command against the pre-fix tree AND the tree the PR will open from, feeding
+   * a failed verification back to the agent while budget remains, and attaches the verdict to the
+   * outcome. Unlike {@link validationChecks} it NEVER gates the pull request — an unproven
+   * reproduction is weak evidence, which is a reviewer's call, not a machine's. Set only for a
+   * dispatch that opens a PR and whose run carries a declaration. See
+   * `docs/initiatives/bugfix-reproduction-proof.md`.
+   */
+  reproduction?: ReproductionSpec
   /**
    * A repo-sourced Claude Skill to make available for this run (a `skill` step, slice 2). Threaded
    * into {@link runAgentInWorkspace}, which installs it harness-aware: natively under the ISOLATED
@@ -141,6 +163,12 @@ export interface CodingAgentOutcome {
   callMetrics?: HarnessCallMetric[]
   /** The agent's effort self-assessment, lifted from its sentinel file (absent when it wrote none). */
   effortReport?: EffortReport
+  /**
+   * The agent-authored PR description, lifted from its sentinel file (absent when it wrote none).
+   * The PR-opening caller folds it over the dispatch-time title/body via {@link applyPrDescription};
+   * absent means the fallback text, unchanged.
+   */
+  prDescription?: AgentPrDescription
   /**
    * Ralph loop: the verdict of the post-commit validation command (whether it exited 0, the
    * exit code, and a bounded/redacted output tail). Present only when {@link CodingAgentSpec.validation}
@@ -158,6 +186,12 @@ export interface CodingAgentOutcome {
    * the caller must open no PR and fail the job with this as the evidence.
    */
   validationReport?: ValidationReport
+  /**
+   * The bugfix reproduction proof's LAST attempt (present only when
+   * {@link CodingAgentSpec.reproduction} was set). Evidence, never a gate: `inconclusive` is
+   * attached to a perfectly successful run and the PR still opens.
+   */
+  reproductionReport?: ReproductionReport
 }
 
 /**
@@ -273,6 +307,9 @@ export async function runCodingAgent(
       // but that cannot un-stage a mid-run commit; the per-clone exclude is what prevents it. A bare
       // filename pattern matches the file in any subdirectory, so it covers a monorepo `workDir` too.
       await excludeFromGit(dir, EFFORT_REPORT_FILE, signal)
+      // Same treatment for the agent-authored PR-description sentinel: excluded locally so the
+      // agent's own `git add` can never stage the briefing into the PR it describes.
+      await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal)
 
       // Follow-up companion: tail the Coder's sentinel file and stream new items out on the
       // job view. Locally exclude it from git first so the agent's own `git add` can never
@@ -323,6 +360,64 @@ export async function runCodingAgent(
         opts.onPhase?.('agent')
         logger.info('coding-agent: running agent', { serviceDirectory })
         let agentRun = await runAgentPass(spec.userPrompt)
+        const foldPass = (run: typeof agentRun): void => {
+          agentRun = mergeAgentPasses(agentRun, run)
+        }
+        // The new files the agent left unadded, folded into either loop's repair prompt. Both
+        // loops judge state the push will NOT carry unless it is committed — the checks run
+        // against the working tree, the proof against committed trees — so an unadded file is
+        // exactly the thing to name. A throw degrades to "no warning" inside each loop.
+        const listUncommittedNewFiles = (): Promise<string[]> =>
+          listUntrackedFiles(workDir, opts.signal)
+
+        // BUGFIX REPRODUCTION PROOF: run the run's declared reproduction command against the
+        // pre-fix tree and the tree the PR will open from, and record whether it was red then
+        // green. Runs BEFORE the validation loop below, deliberately: validation is the GATE
+        // ("only a green checkout opens a PR"), so it has to stay the last thing that touches the
+        // tree — otherwise a reproduction repair round could leave the checkout red behind it and
+        // the PR would open anyway. Keyed purely off the job body carrying a spec (no agent-kind
+        // switch); absent ⇒ a no-op and the flow below is byte-for-byte what it was.
+        const reproduction = spec.reproduction
+        let reproductionReport: ReproductionReport | undefined
+        if (reproduction && (await producedWork(dir, spec, baseSha, resumed, opts))) {
+          opts.onPhase?.('reproduction')
+          reproductionReport = await runReproductionLoop({
+            dir,
+            baseSha,
+            // Re-read per attempt: a repair pass commits, so the final tree moves under the loop.
+            // `producedWork` has already committed forgotten tracked edits, and each repair round
+            // re-commits before the next read.
+            resolveFinalSha: async () => {
+              await commitTrackedEdits(dir, spec.commitMessage, signal)
+              return headCommit(dir, signal)
+            },
+            ...(serviceDirectory ? { serviceDirectory } : {}),
+            spec: reproduction,
+            logger,
+            opts,
+            runAgentPass,
+            onAgentPass: foldPass,
+            listUncommittedNewFiles,
+            // Only a RESUMED run can have a pre-fix tree that already carries work: a fresh run
+            // branched off base, so `baseSha` IS base. Wiring the probe unconditionally would buy
+            // an always-empty answer for the price of a fetch — and a fresh clone is shallow, so
+            // it could not resolve a merge base to answer with anyway. Lazy inside the loop: it
+            // only runs if a tree comes back green.
+            ...(resumed
+              ? {
+                  listBaseTreeChanges: () =>
+                    changedFilesSinceBase(
+                      dir,
+                      spec.repo.baseBranch,
+                      spec.ghToken,
+                      baseSha,
+                      opts.signal,
+                    ),
+                }
+              : {}),
+          })
+          opts.onPhase?.('agent')
+        }
         // PRE-PR VALIDATION: run the service's configured checks against the checkout and, while
         // they fail and budget remains, hand the captured output back to the agent and run it
         // again. Sits BETWEEN the agent and the finalize/push/PR step so a red checkout never
@@ -338,17 +433,16 @@ export async function runCodingAgent(
             logger,
             opts,
             runAgentPass,
-            onAgentPass: (run) => {
-              agentRun = mergeAgentPasses(agentRun, run)
-            },
+            onAgentPass: foldPass,
             // The checks run against the WORKING TREE, but only tracked edits are staged for the
             // push — so a repair round can go green on a new file the PR would never contain.
             // Name those files in the next repair prompt so the agent adds them.
-            listUncommittedNewFiles: () => listUntrackedFiles(workDir, opts.signal),
+            listUncommittedNewFiles,
           })
         }
         outcome = await finalizeCodingRun({
           validationReport,
+          reproductionReport,
           dir,
           spec,
           logger,
@@ -499,6 +593,8 @@ async function prepareCodingCheckout(
 async function finalizeCodingRun(args: {
   /** The pre-PR validation loop's last attempt, attached to the outcome (absent when unconfigured). */
   validationReport?: ValidationReport
+  /** The reproduction proof's last attempt, attached to the outcome (absent when unconfigured). */
+  reproductionReport?: ReproductionReport
   dir: string
   spec: CodingAgentSpec
   logger: Logger
@@ -515,6 +611,7 @@ async function finalizeCodingRun(args: {
 }): Promise<CodingAgentOutcome> {
   const {
     validationReport,
+    reproductionReport,
     dir,
     spec,
     logger,
@@ -542,6 +639,14 @@ async function finalizeCodingRun(args: {
   // untracked scratch files/artifacts — the agent owns committing new files).
   await commitTrackedEdits(dir, spec.commitMessage, signal)
 
+  // The agent-authored PR description, read AFTER the validation loop (a repair round may have
+  // changed what the briefing should say) and removed so it never lingers in the checkout. The
+  // prompt asks for it at the top level of the checkout; a monorepo agent working in a service
+  // subdirectory may drop it in its cwd instead, so probe the checkout root first, then the cwd.
+  const prDescription =
+    (await readPrDescription(dir)) ??
+    (workDir !== dir ? await readPrDescription(workDir) : undefined)
+
   // Stop periodic checkpoints and let any in-flight one settle BEFORE the final
   // push, so the two never run a concurrent `git push` to the same branch (the
   // final push below is then a fresh attempt whose failure is the real signal).
@@ -604,6 +709,7 @@ async function finalizeCodingRun(args: {
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...(effortReport ? { effortReport } : {}),
+      ...(prDescription ? { prDescription } : {}),
     }
   }
 
@@ -618,6 +724,9 @@ async function finalizeCodingRun(args: {
   // reaches the PR-opening caller); attach its verdict for the caller to gate on and for the
   // backend to record on the step.
   if (validationReport) outcome.validationReport = validationReport
+  // The reproduction proof: attached to EVERY outcome, including a no-op or an `inconclusive`
+  // verdict. It is evidence about the change, not a gate on it — see the loop's D6 note.
+  if (reproductionReport) outcome.reproductionReport = reproductionReport
   return outcome
 }
 
@@ -932,6 +1041,7 @@ export async function runMultiRepoCoding(
       job,
       logger,
       opts,
+      root,
     )
 
     const anyWork = primaryPushed || peerPullRequests.length > 0
@@ -1044,6 +1154,9 @@ async function prepareMultiRepoCheckouts(
       await createBranch(dir, leg.workBranch, signal)
     }
     leg.dir = dir
+    // Exclude the agent-authored PR-description sentinel locally (as the single-repo path does)
+    // so the agent's own `git add` can never stage the briefing into the PR it describes.
+    await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal)
     // The branch tip before the agent runs. Captured BEFORE the resume base refresh below so
     // that refresh's merge commit counts as advancement and is pushed (as in the single-repo
     // path). A fresh leg produced work iff its branch advances past this; a resumed leg already
@@ -1102,6 +1215,8 @@ async function pushMultiRepoLegs(
   job: AgentJob,
   logger: Logger,
   opts: RunOptions,
+  /** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
+  root: string,
 ): Promise<{
   primaryPushed: boolean
   primaryPrUrl: string | undefined
@@ -1116,6 +1231,15 @@ async function pushMultiRepoLegs(
     // A read-only reference leg is never committed or pushed — the third layer of the read-only
     // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
     if (leg.readOnly) continue
+    // Lift (and remove) the agent-authored PR description for THIS repo's PR before anything
+    // else touches the checkout — each sibling checkout carries its own briefing for its own PR.
+    // The agent's cwd here is the WORKSPACE ROOT rather than any one checkout, so an agent that
+    // read the prompt loosely may well have written a single briefing there instead. Fall back
+    // to it for the PRIMARY leg only: at the root there is nothing to say which repo it
+    // describes, and the primary is the one the run is actually about.
+    const agentPrDescription =
+      (await readPrDescription(leg.dir)) ??
+      (leg.primary ? await readPrDescription(root) : undefined)
     await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal)
     const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal)
     let hasWork = advanced || leg.resumed
@@ -1144,7 +1268,10 @@ async function pushMultiRepoLegs(
         ghToken: leg.ghToken,
         head: leg.workBranch,
         base: leg.repo.baseBranch,
-        pr: leg.pr,
+        pr: applyPrDescription(leg.pr, agentPrDescription),
+        // 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 } : {}),
         apiBase: job.githubApiBase,
         cloneUrl: leg.repo.cloneUrl,
         ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),