@cat-factory/executor-harness 1.76.2 → 1.78.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.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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.76.2",
+  "version": "1.78.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/kernel": "0.193.0",
+    "@cat-factory/spend": "0.12.123",
+    "@cat-factory/server": "0.178.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

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/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/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')

package/src/pr-template.ts

@@ -0,0 +1,366 @@
+import { readdir, readFile, realpath } from 'node:fs/promises'
+import { join, sep } from 'node:path'
+import { fencedOutput } from './captured-command.js'
+import type { RepoSpec } from './job.js'
+import type { Logger } from './logger.js'
+import { MAX_PR_BODY_CHARS, PR_DESCRIPTION_FILE } from './pr-description.js'
+
+// ---------------------------------------------------------------------------
+// THE REPOSITORY'S OWN PULL-REQUEST TEMPLATE.
+//
+// A repo that ships `.github/PULL_REQUEST_TEMPLATE.md` (or GitLab's
+// `.gitlab/merge_request_templates/Default.md`) is stating the shape every pull request against
+// it must take — the sections its reviewers read, the checklist its process requires. A platform
+// that opens PRs there and ignores that is a bad citizen: its pull requests are the only ones on
+// the repo missing the structure everyone else follows.
+//
+// The trap this module exists for is that the template is NOT applied for us. Both hosts
+// interpolate the template only into the WEB form a human opens; a PR created through the REST
+// API gets exactly the body the caller sends. So nothing anywhere fails or warns — the platform's
+// pull requests simply, quietly, don't follow the repo's own convention.
+//
+// The template is FILLED IN BY THE AGENT, not by the platform. Mechanically stuffing the
+// briefing under the first heading would produce a document with the template's shape and none
+// of its meaning: the sections are questions ("what is the risk?", "how was this tested?") that
+// only whoever did the work can answer. So the harness discovers the template and hands it to the
+// agent that just did the work, in the same prompt that already asks it for a briefing — and the
+// agent answers the template's questions instead of writing a free-form one. Zero extra model
+// calls, and the answers come from the run's full context rather than a summary of it.
+//
+// Discovery is HARNESS-side, deliberately, and reads from the checkout on disk. The backend could
+// instead resolve the template through the `RepoFiles` port at dispatch, but that is an HTTP round
+// trip per dispatch to answer a question the container can answer for free — and every dispatch
+// that opens a pull request has a checkout by definition.
+//
+// The filled text goes back out through `readPrDescription`, so it crosses `redactSecrets` and
+// `host-markdown.ts` on the way to the PR exactly as a free-form briefing does. Nothing here
+// widens that boundary: a template is repo-committed text on the way IN, and what the agent
+// writes is model-authored text on the way OUT either way. What it DOES change on the way out is
+// the title heuristic: the headings are now the repo's, so the caller reads the sentinel with
+// `titleFromHeading: false` (see `ReadPrDescriptionOptions`).
+// ---------------------------------------------------------------------------
+
+/** The VCS providers a repo can live on. Bound to `RepoSpec` so the two cannot drift. */
+type ProviderName = NonNullable<RepoSpec['provider']>
+
+/**
+ * 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: TemplateLocation[] = [
+  { 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: TemplateLocation[] = [
+  { dir: '.gitlab/merge_request_templates', pick: true },
+]
+
+interface TemplateLocation {
+  /** Repo-root-relative directory ('' = the root). */
+  dir: string
+  /** Match a single file with this basename (case-insensitive). */
+  stem?: string
+  /** Treat the directory as a set of templates and pick one. */
+  pick?: boolean
+}
+
+/** A discovered pull-request template. */
+export interface PrTemplate {
+  /** Repo-root-relative path, forward-slashed (it is prose an agent reads). */
+  path: string
+  /**
+   * The template's size. ALWAYS the real one, including when {@link text} is absent: an over-budget
+   * template reporting `chars: 0` would read in the log exactly like an empty file, which is the
+   * one thing discovery treats as "no template at all".
+   */
+  chars: number
+  /** The template text. Absent ⇒ over budget, so the agent is told to read {@link path} itself. */
+  text?: string
+}
+
+/** One checkout to look for a template in. */
+export interface PrTemplateTarget {
+  /** The repository checkout root (NOT a monorepo service subtree — a template is a repo fact). */
+  repoDir: string
+  provider?: ProviderName
+  /** Names this repo in the note. Omit when the run has a single checkout ("this repository"). */
+  repoLabel?: string
+}
+
+/** What {@link resolvePrTemplateNote} tells the run about the templates it found. */
+export interface PrTemplateResolution {
+  /** The prompt note, or absent when no target ships a template (which is most repos). */
+  note?: string
+  /**
+   * The `repoDir`s whose briefing is a FILLED TEMPLATE. The push phase reads those sentinels with
+   * `titleFromHeading: false`, because the headings in them are the repo's — see
+   * `ReadPrDescriptionOptions.titleFromHeading`. A SET keyed by directory rather than a boolean
+   * because a multi-repo run's legs need not all ship a template.
+   */
+  templated: ReadonlySet<string>
+}
+
+/** Why a discovered template was named rather than inlined — the two are not the same fix. */
+type NotInlinedReason = 'over-file-budget' | 'over-shared-budget'
+
+/**
+ * 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: {
+  targets: PrTemplateTarget[]
+  logger: Logger
+}): Promise<PrTemplateResolution> {
+  const { targets, logger } = args
+  const notes: string[] = []
+  const templated = new Set<string>()
+  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: NotInlinedReason | undefined = 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: string,
+  provider?: ProviderName,
+): Promise<PrTemplate | undefined> {
+  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: string): Promise<{ name: string; directory: boolean }[]> {
+  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: { name: string; directory: boolean }[],
+  location: TemplateLocation,
+): string | undefined {
+  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: { name: string; directory: boolean }[]): string | undefined {
+  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: string): { stem: string; extension: string } {
+  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: string, repoDir: string): Promise<string | undefined> {
+  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: PrTemplate, repoLabel?: string): string {
+  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: string, note: string | undefined): string {
+  return note ? `${userPrompt}\n\n${note}` : userPrompt
+}