@cat-factory/executor-harness 1.76.2 → 1.80.0

package/dist/subagents.js

@@ -1,9 +1,62 @@
 import { readdir, stat } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import { basename, join } from 'node:path';
-import { claudeAssistantContent, claudeCallUsage, isObject, redactBody, SUBAGENT_TOOL_NAMES, } from './claude-stream.js';
+import { claudeAssistantContent, claudeCallUsage, claudeToolResultText, isObject, redactBody, SUBAGENT_TOOL_NAMES, } from './claude-stream.js';
 import { publishCallMetric } from './pi.js';
-export function createSliceTracker() {
+// ADR 0026 D2.1 + D3, corrected by ADR 0027. When the Claude Code CLI reviews a large PR
+// it fans the work out across parallel `Task` subagents. Two things then go dark to the
+// harness, which only reads the PARENT process's stream-json stdout:
+//
+//  - the parent stream falls quiet for the whole (potentially 15+ minute) parallel
+//    review, so the inactivity heartbeat freezes and a healthy run looks wedged (P3);
+//  - every subagent's token spend is written to a SEPARATE `subagents/*.jsonl`
+//    transcript under the CLI's config home and never reaches the parent stream, so
+//    the run's telemetry reports ~0 tokens while hundreds of thousands are spent (P3).
+//
+// This module closes both without disabling the (context-bounding, ADR-0023-wanted)
+// subagent parallelism:
+//
+//  - {@link createSliceTracker} derives the slice plan + per-slice progress from the
+//    PARENT stream alone — the subagent-dispatch tool_use and its terminal tool_result
+//    DO appear there (only the subagent's intermediate turns don't), so slices/progress
+//    need no file watching (D2.1). `pickProgress` (./progress.ts) reconciles it with the
+//    parent's own plan (ADR 0027 Defect B);
+//  - {@link startSubagentWatcher} tails the `subagents/*.jsonl` transcripts for the
+//    heartbeat (any new bytes ⇒ `onActivity`) and sums each subagent turn's usage into
+//    the run's telemetry (D3).
+//
+// The CLI does NOT write those transcripts to `<configHome>/subagents` (the location ADR
+// 0026 assumed, which never exists — ADR 0027 Defect A). It writes them PER SESSION under
+// `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/agent-*.jsonl`, and the
+// session-uuid dir isn't known before the CLI mints it — so the watcher is pointed at the
+// `projects` root and DISCOVERS the `subagents/` dir by walking (see
+// {@link findSubagentTranscripts}).
+//
+// Both degrade gracefully in the sense that a missing directory, an unreadable file, or an
+// unparseable line is swallowed rather than failing the run — the CLI's subagent transcript layout
+// is not a stable contract. But note what that costs SINCE the per-call fold landed: the parent
+// loop's telemetry now filters the subagent turns the CLI tags onto its stdout (they were being
+// counted twice and spliced into the parent's message chain), so when this watcher is wired and
+// yields nothing, the run's subagent calls are recorded by NEITHER channel. `runClaudeCode` warns
+// on exactly that shape, and an `ambientAuth` run — which has no config home to watch, so no
+// watcher — keeps recording them off the parent stream instead
+// (`createSubagentStreamTelemetry`). Do not "simplify" that fallback away.
+// ---------------------------------------------------------------------------
+// Slice / progress tracking off the PARENT stream (D2.1)
+// ---------------------------------------------------------------------------
+/**
+ * How much of one slice's terminal report is kept. A slice review is prose (findings for a handful
+ * of files), not a transcript, so this is far above a real report while still bounding what a
+ * runaway subagent can push onto the step — the reports ride the job view on every poll and are
+ * persisted on the run.
+ */
+export const SLICE_REPORT_MAX_CHARS = 24_000;
+/**
+ * @param secrets Leased-credential strings scrubbed from every captured report. A subagent can
+ *   echo a token it saw in the checkout, and these reports are persisted on the run, so they are
+ *   redacted on the way in rather than trusting each consumer to do it.
+ */
+export function createSliceTracker(secrets = []) {
     // Insertion-ordered so the progress `items` render in dispatch order.
     const slices = new Map();
     return {
@@ -33,10 +86,27 @@ export function createSliceTracker() {
                     continue;
                 const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
                 const slice = id ? slices.get(id) : undefined;
-                if (slice)
-                    slice.done = true;
+                if (!slice)
+                    continue;
+                slice.done = true;
+                // The report is captured here or nowhere: this `tool_result` is the only place the
+                // subagent's findings appear on the parent stream, and the next poll may be the last one
+                // this job ever answers.
+                const report = redactBody(claudeToolResultText(block), secrets).trim();
+                if (report)
+                    slice.report = report.slice(0, SLICE_REPORT_MAX_CHARS);
             }
         },
+        sliceReviews() {
+            return [...slices.values()].map((s) => ({
+                label: s.description,
+                status: (s.done ? 'completed' : 'in_progress'),
+                // A slice that finished but whose result carried no readable text is reported as
+                // completed with a null report rather than being dropped: a resume must still know it
+                // does not need re-reviewing, and silently omitting it would send it round again.
+                report: s.report ?? null,
+            }));
+        },
         hasSlices() {
             return slices.size > 0;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.76.2",
+  "version": "1.80.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,9 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.188.0",
-    "@cat-factory/server": "0.175.0",
-    "@cat-factory/spend": "0.12.118"
+    "@cat-factory/server": "0.183.0",
+    "@cat-factory/kernel": "0.197.0",
+    "@cat-factory/spend": "0.12.127"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -26,7 +26,7 @@ import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { describeProcessExit } from './process-exit.js'
 import { redact, registerKnownSecrets, secretsToRedact } from './redact.js'
-import { createSliceTracker, startSubagentWatcher } from './subagents.js'
+import { createSliceTracker, startSubagentWatcher, type SliceReview } from './subagents.js'
 import {
   createTaskPlanTracker,
   mergeProgress,
@@ -123,6 +123,13 @@ export interface SubscriptionRunOptions {
   onActivity?: () => void
   /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
   onProgress?: (progress: TodoProgress) => void
+  /**
+   * Called with the FULL set of per-slice reviews each time one lands, so the backend can persist
+   * a parallel review's completed work as it happens instead of only from the terminal result.
+   * A whole value rather than a delta: the set only grows and losing a finished slice's report to
+   * a dropped poll would defeat the point (see `SliceTracker.sliceReviews`).
+   */
+  onSliceReviews?: (reviews: SliceReview[]) => void
   /**
    * Called with each per-call telemetry row as the CLI stream yields it, so the backend can
    * record the run's model calls WHILE it runs instead of only from its terminal result. The
@@ -542,7 +549,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // either/or; the plan then MERGES with the dispatch view (`mergeProgress`) rather than
   // competing with it — picking the further-along view collapsed the list to the dispatched
   // slices alone the moment the first subagent returned. See ./progress.ts.
-  const sliceTracker = createSliceTracker()
+  const sliceTracker = createSliceTracker(secrets)
   const planTracker = createTaskPlanTracker()
   let lastTodo: TodoProgress | undefined
   const emitProgress = (): void => {
@@ -553,6 +560,15 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     )
     if (progress) opts.onProgress(progress)
   }
+  // Publish the per-slice reviews the tracker has captured. Separate from `emitProgress` because
+  // the two answer different questions and have different lifetimes: progress is a disposable
+  // count the UI renders, while these carry the slices' actual review WORK and are persisted so a
+  // run that dies before its aggregation can be resumed from them.
+  const emitSliceReviews = (): void => {
+    if (!opts.onSliceReviews) return
+    const reviews = sliceTracker.sliceReviews()
+    if (reviews.length > 0) opts.onSliceReviews(reviews)
+  }
 
   // No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
   // absent on this path until now. Claude Code reports a tool CALL (its name) on the `assistant`
@@ -626,6 +642,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         sliceTracker.onUser(content)
         planTracker.onUser(content)
         emitProgress()
+        // A slice's report lands on exactly this turn, so publish here: waiting for the next
+        // progress tick would risk the job dying with the report captured but never surfaced.
+        emitSliceReviews()
         // Not on the at-close flush: the CLI has already exited, so tripping the guard there
         // would kill nothing and only convert a clean exit into a spurious failure.
         if (!meta?.final) feedGuard(content)

package/src/agent.ts

@@ -962,8 +962,12 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
  * Assemble the {@link runCodingAgent} spec for the ordinary single-repo coding flow. Extracted
  * from {@link runSingleRepoCoding} so the many optional-field spreads don't inflate that
  * function's cyclomatic complexity; the mapping is a straight field copy off `job`.
+ *
+ * Exported for the `opensPr` assertion: whether a dispatch fills the repo's PR template turns on
+ * this one spread, and the in-place fixers reach it through the SAME function as the implementer,
+ * so no structural guard can tell their cases apart.
  */
-function buildSingleRepoCodingSpec(
+export function buildSingleRepoCodingSpec(
   job: AgentJob,
   pushBranch: string,
 ): Parameters<typeof runCodingAgent>[0] {
@@ -991,6 +995,10 @@ function buildSingleRepoCodingSpec(
     guardLimits: job.guardLimits,
     ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
     ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
+    // 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.
+    ...(job.pr ? { opensPr: true } : {}),
     ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
     // Skills + tool servers: installed/wired harness-aware by runAgentInWorkspace.
     ...agentCapabilities(job),

package/src/claude-stream.ts

@@ -57,6 +57,27 @@ export function claudeAssistantContent(content: unknown[]): {
   return { text, reasoning, toolUses }
 }
 
+/**
+ * The text a `tool_result` block carries. The CLI writes it either as a bare string or as an
+ * array of content blocks (the shape a subagent's terminal report arrives in), so both are read
+ * here rather than at each call site. Non-text blocks (an image a tool returned) contribute
+ * nothing. Returns '' when the block carries no readable text.
+ *
+ * This is what makes a parallel subagent's work observable to the harness at all: the parent
+ * stream shows a subagent's dispatch and its terminal `tool_result` and nothing in between, so
+ * this text is the ONLY place its findings surface outside its own untailed transcript.
+ */
+export function claudeToolResultText(block: Record<string, unknown>): string {
+  const content = block.content
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  let text = ''
+  for (const part of content) {
+    if (isObject(part) && part.type === 'text' && typeof part.text === 'string') text += part.text
+  }
+  return text
+}
+
 /**
  * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
  * the cumulative `result` total).

package/src/coding-agent.ts

@@ -63,6 +63,11 @@ import {
   withDependencyNote,
   type DependencyInstallSpec,
 } from './dependency-install.js'
+import {
+  resolvePrTemplateNote,
+  withPrTemplateNote,
+  type PrTemplateResolution,
+} from './pr-template.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
@@ -114,6 +119,14 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * only for the implementer (`coder`) dispatch; absent ⇒ no tailing (e.g. the CI-fixer).
    */
   streamFollowUps?: boolean
+  /**
+   * Whether this dispatch OPENS a pull request (the caller passes `pr` to `openPullRequest`).
+   * Set, the harness looks for the repo's own pull-request template and asks the agent to fill it
+   * (see `pr-template.ts`). Absent for a dispatch that amends someone else's PR (the in-place
+   * fixers) — a template filled for a pull request nothing opens is wasted prompt and, worse,
+   * would have a CI-fixer rewrite the implementer's already-published description.
+   */
+  opensPr?: boolean
   /**
    * READ-ONLY reference branches of THIS repo (the apriori-branches reference mode): fetched
    * into `origin/<b>` after the checkout so the agent can inspect them but never commits to
@@ -365,13 +378,28 @@ export async function runCodingAgent(
         opts,
       })
 
+      // THE REPO'S OWN PR TEMPLATE: when this dispatch opens a pull request and the repo ships a
+      // template, the agent is asked to write its briefing AS that template rather than free-form
+      // (see `pr-template.ts` for why neither host applies it to an API-created PR for us).
+      // Discovered at the CHECKOUT ROOT, never `workDir`: a template is a fact about the
+      // repository, so a monorepo service dispatch reads the same one as any other.
+      const prTemplate = await resolvePrTemplateNote({
+        targets: spec.opensPr
+          ? [{ repoDir: dir, ...(spec.repo.provider ? { provider: spec.repo.provider } : {}) }]
+          : [],
+        logger,
+      })
+
       // One agent pass over this checkout, parameterised only by the prompt — so the pre-PR
       // validation loop below can re-run the agent with a repair instruction without
       // re-deriving (or drifting from) the dispatch's own settings.
       //
       // The dependency note rides EVERY pass, not just the first: a repair round starts a fresh
       // agent, and one that is not told the tree is already installed spends the round it was
-      // given to fix something reinstalling it instead.
+      // given to fix something reinstalling it instead. The PR-template note rides every pass for
+      // the mirror-image reason: a repair-round agent still carries the description guidance, so
+      // one that is not told about the template would replace the filled template with a
+      // free-form briefing.
       const runAgentPass = (
         userPrompt: string,
       ): Promise<Awaited<ReturnType<typeof runAgentInWorkspace>>> =>
@@ -379,7 +407,10 @@ export async function runCodingAgent(
           {
             dir: workDir,
             systemPrompt: spec.systemPrompt,
-            userPrompt: withDependencyNote(userPrompt, dependencyNote),
+            userPrompt: withDependencyNote(
+              withPrTemplateNote(userPrompt, prTemplate.note),
+              dependencyNote,
+            ),
             model: spec.model,
             harness: spec.harness,
             subscriptionToken: spec.subscriptionToken,
@@ -499,6 +530,7 @@ export async function runCodingAgent(
           pushWorkOnce,
           inFlightPush,
           agentRun,
+          prTemplate,
         })
       } finally {
         // Safety net for the throw path (the happy path already cleared these above).
@@ -651,6 +683,8 @@ async function finalizeCodingRun(args: {
   pushWorkOnce: () => Promise<void>
   inFlightPush: () => Promise<void> | null
   agentRun: Awaited<ReturnType<typeof runAgentInWorkspace>>
+  /** The repo's PR template, if it ships one — see the `titleFromHeading` read below. */
+  prTemplate: PrTemplateResolution
 }): Promise<CodingAgentOutcome> {
   const {
     validationReport,
@@ -668,6 +702,7 @@ async function finalizeCodingRun(args: {
     pushWorkOnce,
     inFlightPush,
     agentRun,
+    prTemplate,
   } = args
   const { signal } = opts
   const { summary, stats, stderrTail, usage, callMetrics, effortReport } = agentRun
@@ -686,9 +721,15 @@ async function finalizeCodingRun(args: {
   // 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.
+  //
+  // When the repo ships a template the briefing IS that template filled in, so its headings are
+  // the REPO's: a leading `# …` there is the template's own top heading, not the title line the
+  // description guidance asks a free-form briefing for, and lifting it would retitle the PR after
+  // the template and delete the heading from the body.
+  const readDescription = (from: string): Promise<AgentPrDescription | undefined> =>
+    readPrDescription(from, { titleFromHeading: !prTemplate.templated.has(dir) })
   const prDescription =
-    (await readPrDescription(dir)) ??
-    (workDir !== dir ? await readPrDescription(workDir) : undefined)
+    (await readDescription(dir)) ?? (workDir !== dir ? await readDescription(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
@@ -1093,6 +1134,21 @@ export async function runMultiRepoCoding(
         })
       : undefined
 
+    // THE REPOS' OWN PR TEMPLATES: one per leg that will actually open a pull request, each named
+    // by its sibling directory so the agent knows which checkout's briefing takes which shape —
+    // the repos in a workspace need not share a template, or ship one at all. A read-only
+    // reference leg is excluded by construction: it carries no `pr`, so nothing publishes for it.
+    const prTemplate = await resolvePrTemplateNote({
+      targets: legs
+        .filter((leg) => leg.pr)
+        .map((leg) => ({
+          repoDir: leg.dir,
+          repoLabel: leg.dirName,
+          ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),
+        })),
+      logger,
+    })
+
     // Run the agent ONCE with its cwd at the workspace root, so it sees every sibling checkout
     // and can change them coherently. No monorepo/service-directory scoping — the multi-repo
     // note + the backend system-prompt section explain the layout.
@@ -1103,7 +1159,10 @@ export async function runMultiRepoCoding(
         {
           dir: root,
           systemPrompt: job.systemPrompt,
-          userPrompt: withDependencyNote(job.userPrompt, dependencyNote),
+          userPrompt: withDependencyNote(
+            withPrTemplateNote(job.userPrompt, prTemplate.note),
+            dependencyNote,
+          ),
           model: job.model,
           harness: job.harness,
           subscriptionToken: job.subscriptionToken,
@@ -1132,6 +1191,7 @@ export async function runMultiRepoCoding(
       logger,
       opts,
       root,
+      prTemplate,
     )
 
     const anyWork = primaryPushed || peerPullRequests.length > 0
@@ -1307,6 +1367,8 @@ async function pushMultiRepoLegs(
   opts: RunOptions,
   /** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
   root: string,
+  /** Which legs' briefings are filled templates — see the `titleFromHeading` read below. */
+  prTemplate: PrTemplateResolution,
 ): Promise<{
   primaryPushed: boolean
   primaryPrUrl: string | undefined
@@ -1327,9 +1389,14 @@ async function pushMultiRepoLegs(
     // 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.
+    //
+    // Per-leg `titleFromHeading`: only a leg whose OWN repo ships a template has repo-authored
+    // headings in its sentinel, and the legs of a workspace need not agree about that — so this
+    // is keyed on the leg, never on whether the run found any template at all.
+    const readOptions = { titleFromHeading: !prTemplate.templated.has(leg.dir) }
     const agentPrDescription =
-      (await readPrDescription(leg.dir)) ??
-      (leg.primary ? await readPrDescription(root) : undefined)
+      (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)
     let hasWork = advanced || leg.resumed

package/src/pi-workspace.ts

@@ -325,6 +325,10 @@ export async function runAgentInWorkspace(
       expectsEdits: spec.expectsEdits ?? true,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,
+      // 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,
       // 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.

package/src/pr-description.ts

@@ -32,8 +32,14 @@ export const PR_DESCRIPTION_FILE = '.cat-pr-description.md'
  * rejects a body over 65,536 with a 422, and the report publisher swallows its own failures —
  * so a briefing budget that does not leave the report room would surface as a report that
  * silently never publishes. 15,000 + 50,000 stays under the limit with room to join them.
+ *
+ * Exported because the PR-TEMPLATE note states it to the agent (`pr-template.ts`): a filled
+ * template is the one briefing shape whose length is dictated by a file the agent did not write,
+ * so an agent that does not know the ceiling can answer a long template past it and have
+ * {@link capBody} cut the repo's last sections — the very failure the inline budget avoids on the
+ * way IN.
  */
-const MAX_PR_BODY_CHARS = 15_000
+export const MAX_PR_BODY_CHARS = 15_000
 
 /** Ceiling on an agent-supplied title (GitHub truncates around 256; a title should be short). */
 const MAX_PR_TITLE_CHARS = 160
@@ -57,6 +63,24 @@ export interface AgentPrDescription {
   body?: string
 }
 
+/** How to read a sentinel. */
+export interface ReadPrDescriptionOptions {
+  /**
+   * Whether a lone leading `# <title>` heading may be lifted off as the PR title (see
+   * {@link splitTitle}). Default `true` — that is what the description guidance asks a free-form
+   * briefing for.
+   *
+   * FALSE when the briefing is a FILLED TEMPLATE (`pr-template.ts`): then the headings are the
+   * repo's, not the agent's, and a template whose first heading is its only level-1 one — `#
+   * Pull Request` above a set of `##` sections, an entirely ordinary shape — would have that
+   * heading silently become the pull request's title, so the PR reads "Pull Request" instead of
+   * `<block> (<pipeline>)` and the body loses the heading the repo asked for. The heuristic below
+   * is sound for the shape the guidance describes and cannot be made to cover both, so the caller
+   * that KNOWS which shape it asked for says so.
+   */
+  titleFromHeading?: boolean
+}
+
 /**
  * Read + parse + REMOVE the agent's PR-description sentinel from `dir`. Lenient: returns
  * undefined when the file is absent (the agent wrote none) or carries nothing usable. Never
@@ -64,16 +88,20 @@ export interface AgentPrDescription {
  * the dispatch-time text.
  *
  * A SINGLE `# <title>` heading on the first line sets the PR title; everything after it is the
- * body (see {@link splitTitle} for why a LONE heading is required). The whole text is
- * secret-scrubbed, an over-budget body is truncated WITH a visible note (a silent cut would
- * read as the complete briefing), and both halves are made inert for the host.
+ * body (see {@link splitTitle} for why a LONE heading is required, and
+ * {@link ReadPrDescriptionOptions.titleFromHeading} for the caller that must switch it off). The
+ * whole text is secret-scrubbed, an over-budget body is truncated WITH a visible note (a silent
+ * cut would read as the complete briefing), and both halves are made inert for the host.
  *
  * On scrubbing: `redactSecrets`'s credential-assignment rule is deliberately eager, so a
  * briefing sentence like "the token: handling changed" loses its next word. That is the right
  * trade for a surface this public — the rule is shared with every other redaction path, and
  * narrowing it so prose reads better would weaken all of them.
  */
-export async function readPrDescription(dir: string): Promise<AgentPrDescription | undefined> {
+export async function readPrDescription(
+  dir: string,
+  opts: ReadPrDescriptionOptions = {},
+): Promise<AgentPrDescription | undefined> {
   const path = join(dir, PR_DESCRIPTION_FILE)
   let raw: string
   try {
@@ -86,7 +114,8 @@ export async function readPrDescription(dir: string): Promise<AgentPrDescription
   const text = redactSecrets(raw).replace(MANAGED_SECTION_MARKER, '').trim()
   if (!text) return undefined
 
-  const split = splitTitle(text)
+  const split: { title?: string; body: string } =
+    opts.titleFromHeading === false ? { body: text } : splitTitle(text)
   // Cap BEFORE the escapes on both halves, so a numeric entity can never be sliced in half.
   const title = split.title ? inertInline(capTitle(split.title)) : undefined
   const body = split.body ? inertMarkdown(capBody(split.body)) : undefined
@@ -104,6 +133,11 @@ export async function readPrDescription(dir: string): Promise<AgentPrDescription
  * silently become the pull request's title, replacing `<block> (<pipeline>)` with the word
  * "Problem". Headings inside fenced code are not headings and are skipped, or a briefing
  * quoting a shell snippet (`# rebuild the image`) would lose its title to the snippet.
+ *
+ * The "single H1" test is what makes this safe for the free-form shape and is exactly what makes
+ * it WRONG for a filled template, whose H1 count is the repo's choice — hence
+ * {@link ReadPrDescriptionOptions.titleFromHeading}, which skips this entirely rather than piling
+ * another heuristic on top of one that cannot serve both shapes.
  */
 function splitTitle(text: string): { title?: string; body: string } {
   const lines = text.split('\n')