@cat-factory/executor-harness 1.76.2 → 1.80.0

package/README.md

@@ -68,25 +68,34 @@ The implementation job (`POST /run`) is the canonical sequence:
    it reads real installed packages instead of inferring a library's capabilities from a
    manifest entry. Best-effort and never a gate: the outcome (success or the captured
    failure) is folded into the agent's prompt — on EVERY pass, including the repair passes of
-   steps 5 and 6, which start a fresh agent — and the run continues either way. Whatever the
+   steps 6 and 7, which start a fresh agent — and the run continues either way. Whatever the
    install materialises is excluded from git first, so no later `git add -A` can sweep a
    dependency tree into the pull request (see
    [dependency prepopulation](../../../docs/initiatives/agent-dependency-prepopulation.md)),
-4. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
-5. **validate** the checkout, when the job body carries `validationChecks` — the service's
+4. **resolve the repo's pull-request template**, when this dispatch opens a PR (`src/pr-template.ts`)
+   — `.github/PULL_REQUEST_TEMPLATE.md` and its root/`docs/`/multi-template-directory variants, or
+   GitLab's `.gitlab/merge_request_templates/`, read straight off the checkout (a symlinked template
+   is followed only while it resolves INSIDE the checkout — this is the one repo-chosen path the
+   harness reads unprompted). Found, it is folded into the agent's prompt (on EVERY pass, as with
+   the install above) asking it to write its briefing AS that template, filled in. This exists
+   because neither host applies a template to an API-created pull request, so nothing else would:
+   the template only reaches the web form a human opens. A directory of several templates with no
+   `default` is left alone deliberately — it exists so a human can choose per pull request,
+5. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
+6. **validate** the checkout, when the job body carries `validationChecks` — the service's
    configured check commands (install/lint/test/build) run with `sh -c` in the checkout, and
    while they fail and the attempt budget remains the agent is re-run with the captured output
    as its instruction (see [pre-PR validation](../../../docs/initiatives/pre-pr-validation.md)),
-6. **prove the reproduction**, when the job body carries `reproduction` — the declared check is
+7. **prove the reproduction**, when the job body carries `reproduction` — the declared check is
    run against the pre-fix tree and the tree the PR will open from, in two freshly-created
    symmetric `git worktree` checkouts, and only red-then-green is reported as proof (see
    [bugfix reproduction proof](../../../docs/initiatives/bugfix-reproduction-proof.md)). Unlike
-   step 5 this NEVER gates the PR: a failed verification is fed back to the agent while budget
-   remains, then recorded as `inconclusive`. It runs BEFORE step 5 so validation stays the last
+   step 6 this NEVER gates the PR: a failed verification is fed back to the agent while budget
+   remains, then recorded as `inconclusive`. It runs BEFORE step 6 so validation stays the last
    thing to touch the tree,
-7. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
-   ONLY if step 5 ended green. A spent budget returns an error result with the validation report
-   and opens no PR. Absent `validationChecks` / `reproduction`, steps 5 and 6 do not happen at
+8. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
+   ONLY if step 6 ended green. A spent budget returns an error result with the validation report
+   and opens no PR. Absent `validationChecks` / `reproduction`, steps 6 and 7 do not happen at
    all. The PR's description prefers the agent-authored reviewer briefing over the generic
    dispatch-time text the job body carries: a PR-opening agent is prompted to write one to the
    `.cat-pr-description.md` sentinel at the checkout root (one per sibling repo in a multi-repo
@@ -94,9 +103,13 @@ The implementation job (`POST /run`) is the canonical sequence:
    title), and `src/pr-description.ts` lifts it — secret-scrubbed, size-capped with a visible
    note, made inert for the host by `src/host-markdown.ts`, kept out of the commit like the
    effort/follow-ups sentinels — onto `openPullRequest`. Absent or unusable ⇒ the fallback text,
-   unchanged. On a RESUMED run the PR already exists, so an agent briefing additionally refreshes
-   its title/description in place (carrying the engine's managed report region across); the
-   generic fallback never does, so a human's edit is safe.
+   unchanged. When the repo ships a template (step 4) that briefing IS the filled template: it
+   crosses the same scrub/cap/inert boundary on the way out, but the leading-`#` title rule is
+   switched OFF for it (`titleFromHeading: false`), because those headings are the repo's and
+   lifting the template's top heading would retitle the PR after it and drop it from the body. On a
+   RESUMED run the PR already exists, so an agent briefing additionally refreshes its
+   title/description in place (carrying the engine's managed report region across); the generic
+   fallback never does, so a human's edit is safe.
 
 Bootstrap differs at the ends — it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a

package/dist/agent-runner.js

@@ -384,7 +384,7 @@ export async function runClaudeCode(opts) {
     // 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;
     const emitProgress = () => {
@@ -394,6 +394,17 @@ export async function runClaudeCode(opts) {
         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 = () => {
+        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`
     // turn and that call's RESULT (`is_error`) on the following `user` turn, so correlate them by
@@ -471,6 +482,9 @@ export async function runClaudeCode(opts) {
                 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)

package/dist/agent.js

@@ -802,8 +802,12 @@ async function runCodingMode(job, opts) {
  * 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(job, pushBranch) {
+export function buildSingleRepoCodingSpec(job, pushBranch) {
     return {
         kind: 'agent',
         jobId: job.jobId,
@@ -828,6 +832,10 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
         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/dist/claude-stream.js

@@ -49,6 +49,29 @@ export function claudeAssistantContent(content) {
     }
     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) {
+    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/dist/coding-agent.js

@@ -11,6 +11,7 @@ import { log } from './logger.js';
 import { runValidationLoop, } from './validation-checks.js';
 import { runReproductionLoop, } from './reproduction-proof.js';
 import { prepopulateDependencies, withDependencyNote, } from './dependency-install.js';
+import { resolvePrTemplateNote, withPrTemplateNote, } from './pr-template.js';
 /**
  * How often the harness checkpoints the agent's work mid-run by pushing the branch.
  * A per-run container can be evicted at any moment; pushing the agent's commits
@@ -149,17 +150,31 @@ export async function runCodingAgent(spec, opts = {}) {
             logger,
             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) => runAgentInWorkspace({
             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,
@@ -267,6 +282,7 @@ export async function runCodingAgent(spec, opts = {}) {
                 pushWorkOnce,
                 inFlightPush,
                 agentRun,
+                prTemplate,
             });
         }
         finally {
@@ -388,7 +404,7 @@ async function prepareCodingCheckout(dir, spec, logger, opts) {
  * {@link runCodingAgent} so its body stays small; returns the built {@link CodingAgentOutcome}.
  */
 async function finalizeCodingRun(args) {
-    const { validationReport, reproductionReport, dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, } = args;
+    const { validationReport, reproductionReport, dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, prTemplate, } = args;
     const { signal } = opts;
     const { summary, stats, stderrTail, usage, callMetrics, effortReport } = agentRun;
     let outcome;
@@ -405,8 +421,13 @@ 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.
-    const prDescription = (await readPrDescription(dir)) ??
-        (workDir !== dir ? await readPrDescription(workDir) : undefined);
+    //
+    // 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) => readPrDescription(from, { titleFromHeading: !prTemplate.templated.has(dir) });
+    const prDescription = (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
     // final push below is then a fresh attempt whose failure is the real signal).
@@ -744,6 +765,20 @@ export async function runMultiRepoCoding(job, opts = {}) {
                 opts,
             })
             : 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.
@@ -752,7 +787,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
         const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
             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,
@@ -772,7 +807,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
             multiRepo: true,
         }, 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);
+        const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts, root, prTemplate);
         const anyWork = primaryPushed || peerPullRequests.length > 0;
         if (!anyWork) {
             // Nothing changed in ANY repo. For the implementer this is a failure (as in the
@@ -923,7 +958,9 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
  */
 async function pushMultiRepoLegs(legs, job, logger, opts, 
 /** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
-root) {
+root, 
+/** Which legs' briefings are filled templates — see the `titleFromHeading` read below. */
+prTemplate) {
     const { signal } = opts;
     opts.onPhase?.('push');
     let primaryPushed = false;
@@ -940,8 +977,13 @@ root) {
         // 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);
+        //
+        // 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, 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/dist/pi-workspace.js

@@ -182,6 +182,10 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             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/dist/pr-description.js

@@ -29,8 +29,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;
 /** Opens the engine-managed region of a PR body (kept in sync with `kernel/domain/pr-report.ts`). */
@@ -51,16 +57,17 @@ const MANAGED_SECTION_MARKER = /<!--\s*cat-factory:verification-report:(?:start|
  * 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) {
+export async function readPrDescription(dir, opts = {}) {
     const path = join(dir, PR_DESCRIPTION_FILE);
     let raw;
     try {
@@ -74,7 +81,7 @@ export async function readPrDescription(dir) {
     const text = redactSecrets(raw).replace(MANAGED_SECTION_MARKER, '').trim();
     if (!text)
         return undefined;
-    const split = splitTitle(text);
+    const split = 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;
@@ -92,6 +99,11 @@ export async function readPrDescription(dir) {
  * 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) {
     const lines = text.split('\n');

package/dist/pr-template.js

@@ -0,0 +1,250 @@
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { fencedOutput } from './captured-command.js';
+import { MAX_PR_BODY_CHARS, PR_DESCRIPTION_FILE } from './pr-description.js';
+/**
+ * How much template text is inlined into the agent's prompt.
+ *
+ * Over this, the template is NAMED rather than inlined and the agent is told to read it from the
+ * checkout — which it can, because the file is on disk. That is strictly better than the
+ * alternatives: truncating a template would have the agent fill a structure whose tail it never
+ * saw (silently dropping the repo's last sections), and skipping it entirely would abandon the
+ * feature on exactly the repos with the most demanding process.
+ */
+export const MAX_INLINE_PR_TEMPLATE_CHARS = 8_000;
+/**
+ * The shared inline budget across a multi-repo run's legs. Each repo's template competes for it in
+ * leg order, and a leg that does not fit is NAMED rather than inlined (as above) — so a workspace
+ * of four template-carrying repos cannot quietly consume 32k of the agent's prompt.
+ */
+export const MAX_TOTAL_INLINE_PR_TEMPLATE_CHARS = 12_000;
+/** Extensions a template file may carry. Both hosts also accept an extensionless file. */
+const TEMPLATE_EXTENSIONS = new Set(['.md', '.markdown', '.txt']);
+/** GitHub's single-file template basename, matched case-insensitively as GitHub itself does. */
+const GITHUB_TEMPLATE_STEM = 'pull_request_template';
+/**
+ * Where a template can live, in each host's OWN precedence order. A `stem` entry is a single file
+ * in that directory; a `pick` entry is a directory of templates (see {@link chooseFromDirectory}).
+ */
+const GITHUB_LOCATIONS = [
+    { dir: '.github', stem: GITHUB_TEMPLATE_STEM },
+    { dir: '', stem: GITHUB_TEMPLATE_STEM },
+    { dir: 'docs', stem: GITHUB_TEMPLATE_STEM },
+    { dir: '.github/PULL_REQUEST_TEMPLATE', pick: true },
+];
+/**
+ * GitLab keeps merge-request templates only in a directory — there is no root single-file
+ * convention to probe, so none is invented here.
+ */
+const GITLAB_LOCATIONS = [
+    { dir: '.gitlab/merge_request_templates', pick: true },
+];
+/**
+ * THE entry point: find each target's pull-request template and build the prompt note that asks
+ * the agent to fill it, plus the set of checkouts whose sentinel will therefore hold a filled
+ * template rather than a free-form briefing (see {@link PrTemplateResolution}).
+ *
+ * Pass NO targets for a dispatch that opens no pull request — an in-place fixer amending someone
+ * else's PR, a read-only explore run. Asking such a run to fill a template would be asking for a
+ * document nothing publishes.
+ *
+ * Never rejects: a template is an improvement to a PR body, so no failure reading one may cost a
+ * run that otherwise succeeded. An unreadable or empty template is simply no template.
+ */
+export async function resolvePrTemplateNote(args) {
+    const { targets, logger } = args;
+    const notes = [];
+    const templated = new Set();
+    let inlineBudget = MAX_TOTAL_INLINE_PR_TEMPLATE_CHARS;
+    for (const target of targets) {
+        const found = await discoverPrTemplate(target.repoDir, target.provider);
+        if (!found)
+            continue;
+        // Spend the shared budget in leg order; a template that no longer fits is named, not cut. The
+        // per-file budget was already spent inside discovery, so an absent `text` means THAT ceiling —
+        // distinguished in the log because the two want different fixes (a smaller template vs a
+        // workspace carrying more template text than one prompt should hold).
+        const text = found.text;
+        const inline = text !== undefined && text.length <= inlineBudget;
+        if (inline)
+            inlineBudget -= text.length;
+        const reason = inline
+            ? undefined
+            : text === undefined
+                ? 'over-file-budget'
+                : 'over-shared-budget';
+        logger.info('pr template: found', {
+            path: found.path,
+            chars: found.chars,
+            inlined: inline,
+            ...(reason ? { reason } : {}),
+            ...(target.repoLabel ? { repo: target.repoLabel } : {}),
+        });
+        templated.add(target.repoDir);
+        notes.push(buildPrTemplateNote(inline ? found : { path: found.path, chars: found.chars }, target.repoLabel));
+    }
+    return { ...(notes.length > 0 ? { note: notes.join('\n\n') } : {}), templated };
+}
+/**
+ * Locate the template in `repoDir`, probing the repo's OWN host convention first and the other
+ * host's second — a repo mirrored across both, or one whose provider the dispatcher did not set,
+ * still gets its template respected rather than falling to whichever list happened to be first.
+ */
+export async function discoverPrTemplate(repoDir, provider) {
+    const locations = provider === 'gitlab'
+        ? [...GITLAB_LOCATIONS, ...GITHUB_LOCATIONS]
+        : [...GITHUB_LOCATIONS, ...GITLAB_LOCATIONS];
+    for (const location of locations) {
+        const entries = await listDirectory(join(repoDir, location.dir));
+        if (entries.length === 0)
+            continue;
+        const name = location.pick ? chooseFromDirectory(entries) : chooseSingleFile(entries, location);
+        if (!name)
+            continue;
+        const path = location.dir ? `${location.dir}/${name}` : name;
+        const text = await readTemplate(join(repoDir, location.dir, name), repoDir);
+        // An empty (or unreadable) file imposes no structure, so keep probing: a repo can carry a
+        // placeholder at one location and its real template at another.
+        if (!text)
+            continue;
+        const chars = text.length;
+        return chars <= MAX_INLINE_PR_TEMPLATE_CHARS ? { path, chars, text } : { path, chars };
+    }
+    return undefined;
+}
+/** Directory entries with their kind, or `[]` for a directory that is absent or unreadable. */
+async function listDirectory(path) {
+    try {
+        const entries = await readdir(path, { withFileTypes: true });
+        // Sorted so a repo carrying several matches always yields the SAME one: readdir order is
+        // filesystem-defined, and a PR body that changed shape between two runs of the same repo
+        // would be a genuinely baffling thing to debug.
+        return entries
+            .map((entry) => ({ name: entry.name, directory: entry.isDirectory() }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The single-file match. Case-insensitive on both the stem and the extension, and extensionless
+ * is allowed because both hosts accept it — which is why the DIRECTORY check matters here:
+ * `.github/PULL_REQUEST_TEMPLATE/` is itself an extensionless match for the stem, and reading a
+ * directory as a template would produce nothing but a swallowed EISDIR.
+ */
+function chooseSingleFile(entries, location) {
+    return entries.find((entry) => {
+        if (entry.directory)
+            return false;
+        const { stem, extension } = splitName(entry.name);
+        return stem === location.stem && (extension === '' || TEMPLATE_EXTENSIONS.has(extension));
+    })?.name;
+}
+/**
+ * Pick from a directory of templates — GitHub's `.github/PULL_REQUEST_TEMPLATE/`, GitLab's
+ * `.gitlab/merge_request_templates/`.
+ *
+ * A `default` template wins (GitLab applies `Default.md` by itself, so it is unambiguously the
+ * one meant for a PR that names none). Failing that, a lone template is taken: a repo with
+ * exactly one has expressed exactly one convention.
+ *
+ * SEVERAL templates with no default yields NOTHING, deliberately. That directory exists so a
+ * HUMAN can choose per pull request — "bug report" vs "release" vs "RFC" — and the choice is
+ * usually not inferable from a diff. Picking one arbitrarily would file every run's work under
+ * whichever name sorts first, which is worse than the free-form briefing: it looks like a
+ * deliberate categorisation and is not.
+ */
+function chooseFromDirectory(entries) {
+    const usable = entries.filter((entry) => !entry.directory && TEMPLATE_EXTENSIONS.has(splitName(entry.name).extension));
+    const fallback = usable.find((entry) => splitName(entry.name).stem === 'default');
+    if (fallback)
+        return fallback.name;
+    return usable.length === 1 ? usable[0].name : undefined;
+}
+/** Lower-cased stem + extension ('' when the name carries none). */
+function splitName(name) {
+    const lower = name.toLowerCase();
+    const dot = lower.lastIndexOf('.');
+    if (dot <= 0)
+        return { stem: lower, extension: '' };
+    return { stem: lower.slice(0, dot), extension: lower.slice(dot) };
+}
+/**
+ * The template's text, or undefined when it is unreadable or carries nothing.
+ *
+ * A checkout is REPO-AUTHORED, symlinks included, and this is the one read the harness performs on
+ * a repo-chosen path without the agent asking for it — so the resolved target must stay inside
+ * `repoDir`. A link out of the tree would inline an arbitrary container file (the run's own env,
+ * a sibling checkout) into the prompt, and from there into a body only `redactSecrets` stands in
+ * front of. Containment rather than a blanket symlink refusal, because a monorepo pointing
+ * `.github/PULL_REQUEST_TEMPLATE.md` at a doc it keeps elsewhere in the repo is a real and
+ * legitimate layout.
+ */
+async function readTemplate(path, repoDir) {
+    try {
+        // Both sides resolved, so the comparison is between two canonical paths — `repoDir` itself is
+        // routinely reached through a symlinked temp dir (macOS `/tmp`), which a raw prefix test on the
+        // unresolved root would read as an escape.
+        const [target, root] = await Promise.all([realpath(path), realpath(repoDir)]);
+        if (target !== root && !target.startsWith(root.endsWith(sep) ? root : root + sep)) {
+            return undefined;
+        }
+        return (await readFile(target, 'utf8')).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The prompt note. It has to do more than show the template, because the agent has already been
+ * told (by the backend-composed `PR_DESCRIPTION_GUIDANCE`) to write a free-form briefing, and the
+ * two genuinely conflict: a template that asks for a test plan or a checklist is asking for
+ * exactly the "restated diff" that guidance rules out. So the note states which wins, and states
+ * why the template is not already applied — an agent that believes the host will merge the
+ * template with its text has no reason to reproduce the structure itself.
+ *
+ * The template is delimited with `fencedOutput`, the same helper every other captured-text-into-a-
+ * prompt path uses. Templates routinely carry fenced blocks of their own, and a fixed three-tick
+ * wrapper closes on the first of them — spilling the rest of the template, and the instructions
+ * after it, into the prompt as prose. `fencedOutput` sizes the fence one tick longer than the
+ * longest run in the body, which is what CommonMark specifies for exactly this, so no template can
+ * break out of its own block. A plain `--- BEGIN/END ---` rule would read more nicely and is
+ * trivially forgeable by the template's own content, which is the whole thing being defended.
+ */
+export function buildPrTemplateNote(template, repoLabel) {
+    const subject = repoLabel ? `The \`${repoLabel}\` repository` : 'This repository';
+    const lead = `PULL REQUEST TEMPLATE — ${subject} ships a pull request template at \`${template.path}\` ` +
+        '(relative to the repository root). The platform opens the pull request through the host API, ' +
+        'and neither GitHub nor GitLab applies a template to an API-created pull request — that only ' +
+        'happens for a human opening one in the web form. So following it is on you.';
+    const instructions = `Write \`${PR_DESCRIPTION_FILE}\` as that template, FILLED IN${repoLabel ? ` (in the \`${repoLabel}\` checkout)` : ''}: keep its headings, their order, and any structure it defines; answer every section from ` +
+        'the work you actually did; delete its instructional HTML comments and any placeholder text; ' +
+        'and complete checklists honestly, ticking only what is true. Leave a section that genuinely ' +
+        'does not apply in place with a brief "n/a" and why, rather than deleting the heading — a ' +
+        'reviewer looking for it needs to see it was considered. Where the template asks for ' +
+        'something the general description guidance does not, the TEMPLATE wins; where it leaves room ' +
+        'for prose, brief it as that guidance describes. The platform rules still hold either way: no ' +
+        'secrets, and no issue/PR numbers, @-mentions, or issue-closing wording. Do NOT put a title ' +
+        "line above the template — the platform titles this pull request itself, so the template's " +
+        'own first heading stays the first line of the file. Keep the finished file under ' +
+        `${MAX_PR_BODY_CHARS.toLocaleString('en-US')} characters: the platform truncates a longer ` +
+        "body, which would cut the template's last sections.";
+    if (template.text === undefined) {
+        // Reached both when the file alone exceeds the inline budget and when a multi-repo run's
+        // earlier legs spent the shared one, so the wording states the size and stays true of both.
+        return (`${lead} ${instructions} The template (${template.chars} characters) is not reproduced ` +
+            'here — read it from the checkout.');
+    }
+    return `${lead} ${instructions}\n\nThe template follows, in a fenced block that is NOT part of it:\n${fencedOutput(template.text)}`;
+}
+/**
+ * Fold the note into a prompt. The sibling of `withDependencyNote`, and deliberately not inlined
+ * for the same reason: it rides EVERY agent pass, including the validation and reproduction
+ * REPAIR passes. Those start a fresh agent that still carries the description guidance in its
+ * system prompt, so one that is not also told about the template would rewrite the briefing
+ * free-form and undo the filled template the first pass produced.
+ */
+export function withPrTemplateNote(userPrompt, note) {
+    return note ? `${userPrompt}\n\n${note}` : userPrompt;
+}

package/dist/runner.js

@@ -220,6 +220,9 @@ export class JobRegistry {
                 onValidationReport: (report) => {
                     entry.validationReport = report;
                 },
+                onSliceReviews: (reviews) => {
+                    entry.sliceReviews = reviews;
+                },
                 onReproductionProof: (report) => {
                     entry.reproductionReport = report;
                 },