@cat-factory/executor-harness 1.60.0 → 1.62.0

package/dist/pr-description.js

@@ -0,0 +1,157 @@
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inertInline, inertMarkdown, walkFences } from './host-markdown.js';
+import { redactSecrets } from './redact.js';
+// ---------------------------------------------------------------------------
+// The agent-authored pull-request description side channel. A coding agent whose
+// dispatch opens a PR is asked (via the backend-composed system prompt) to end its
+// run by writing a reviewer briefing — the problem, the decisions made, what to
+// look out for — to a sentinel file at the root of the checkout the PR belongs to.
+// The harness reads it after the agent settles, removes it (so it never lands in a
+// commit), and uses it as the PR body in place of the generic dispatch-time text
+// the job body carries. Absent or unusable ⇒ the dispatch-time fallback, unchanged.
+//
+// The briefing is MODEL-AUTHORED text landing verbatim on a host-parsed surface, so
+// it crosses `host-markdown.ts` (auto-link triggers defused, open code fences closed)
+// on the way out — see that module for why a PR body is not an inert string sink.
+//
+// The filename is kept in sync with `PR_DESCRIPTION_FILE` in `@cat-factory/agents`
+// (the executor-harness has no dependency on that package), exactly like the
+// effort-report and follow-ups sentinels.
+// ---------------------------------------------------------------------------
+/** The sentinel file the agent writes its PR description to (relative to the checkout root). */
+export const PR_DESCRIPTION_FILE = '.cat-pr-description.md';
+/**
+ * Ceiling on the agent-authored body.
+ *
+ * The engine appends its verification report to the SAME body later, and that section carries
+ * its own 50,000-character ceiling (`MAX_SECTION_CHARS` in kernel's `hostMarkdown`). GitHub
+ * 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.
+ */
+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`). */
+export const PR_REPORT_MARKER_START = '<!-- cat-factory:verification-report:start -->';
+/** Closes the engine-managed region of a PR body. */
+export const PR_REPORT_MARKER_END = '<!-- cat-factory:verification-report:end -->';
+/**
+ * A marker inside the agent-authored briefing would make the engine's splice treat part of the
+ * briefing as its own managed region and rewrite it, so any occurrence is stripped up front.
+ * Deliberately laxer than the exact constants above (whitespace-tolerant), so a near-miss the
+ * splice itself would not match cannot survive here either.
+ */
+const MANAGED_SECTION_MARKER = /<!--\s*cat-factory:verification-report:(?:start|end)\s*-->/g;
+/**
+ * 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
+ * throws — a bad description must never fail an otherwise-good run; the caller falls back to
+ * 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.
+ *
+ * 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) {
+    const path = join(dir, PR_DESCRIPTION_FILE);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined; // no description written — the fallback body applies
+    }
+    // Remove it so it never lands in a commit (defence in depth; the checkout also excludes it).
+    await rm(path, { force: true }).catch(() => { });
+    const text = redactSecrets(raw).replace(MANAGED_SECTION_MARKER, '').trim();
+    if (!text)
+        return undefined;
+    const split = 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;
+    if (!title && !body)
+        return undefined;
+    return { ...(title ? { title } : {}), ...(body ? { body } : {}) };
+}
+/**
+ * Split a leading `# <title>` heading off the briefing.
+ *
+ * The heading becomes the title ONLY when it is the single level-1 heading in the whole file,
+ * which is exactly what the prompt asks for ("a single `# <title>` heading line"). An agent
+ * that instead uses `#` for its section headings — `# Problem`, `# Decisions`, entirely
+ * idiomatic for the briefing the prompt describes — would otherwise have its first section
+ * 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.
+ */
+function splitTitle(text) {
+    const lines = text.split('\n');
+    const headings = [];
+    let index = 0;
+    walkFences(lines, (line, insideFence) => {
+        if (!insideFence && /^#\s+\S/.test(line))
+            headings.push(index);
+        index += 1;
+    });
+    if (headings.length !== 1 || headings[0] !== 0)
+        return { body: text };
+    const title = lines[0].replace(/^#\s+/, '').trim();
+    if (!title)
+        return { body: text };
+    return { title, body: lines.slice(1).join('\n').trim() };
+}
+/** Cut an over-long title at a word boundary when one is near, marking the cut. */
+function capTitle(value) {
+    const collapsed = value.trim();
+    if (collapsed.length <= MAX_PR_TITLE_CHARS)
+        return collapsed;
+    const head = collapsed.slice(0, MAX_PR_TITLE_CHARS - 1);
+    const space = head.lastIndexOf(' ');
+    const kept = space > MAX_PR_TITLE_CHARS * 0.6 ? head.slice(0, space) : head;
+    return `${kept.trimEnd()}…`;
+}
+/** Cut an over-budget body, marking the cut so it is never read as the whole briefing. */
+function capBody(value) {
+    if (value.length <= MAX_PR_BODY_CHARS)
+        return value;
+    return (value.slice(0, MAX_PR_BODY_CHARS).trimEnd() +
+        '\n\n_Truncated by the platform: the description exceeded the size budget._');
+}
+/**
+ * Fold an agent-authored description over the dispatch-time fallback the job body carries.
+ * Field-wise: the agent's title/body each win when present, so a body-only briefing keeps the
+ * backend-composed title and vice versa.
+ */
+export function applyPrDescription(fallback, agent) {
+    if (!agent)
+        return fallback;
+    return { title: agent.title ?? fallback.title, body: agent.body ?? fallback.body };
+}
+/**
+ * The body to PATCH onto an ALREADY-OPEN pull request when a resumed run produced a fresh
+ * briefing: the new description followed by whatever the engine's managed verification-report
+ * region currently holds.
+ *
+ * Carrying the region across is what makes the refresh safe. The engine re-publishes the report
+ * on every step settlement, so dropping it here would usually self-heal — but "usually" is not
+ * a property to rest the one artefact a reviewer reads on, and a run that settles no further
+ * step (the work is already merged, the run failed after its push) would never restore it.
+ */
+export function preserveManagedSection(currentBody, nextBody) {
+    const existing = currentBody ?? '';
+    const start = existing.indexOf(PR_REPORT_MARKER_START);
+    const end = existing.indexOf(PR_REPORT_MARKER_END);
+    if (start === -1 || end <= start)
+        return nextBody;
+    const region = existing.slice(start, end + PR_REPORT_MARKER_END.length);
+    return `${nextBody.trim()}\n\n${region}\n`;
+}

package/dist/vcs-api.js

@@ -0,0 +1,402 @@
+// ---------------------------------------------------------------------------
+// The VCS HOST REST surface: opening a pull request / merge request, finding the one that is
+// already open, and refreshing its title + description.
+//
+// Split out of `git.ts`, which is otherwise entirely the git CLI. The seam is real rather than
+// arithmetic: nothing here shells out to git, nothing in `git.ts` speaks HTTP, and the two
+// halves fail in completely different ways (a rejected credential and a 403 from an App
+// permission want different remedies). `test/git-pr.test.ts` already covered exactly this
+// surface before it had a file of its own.
+//
+// Provider-agnostic by construction: GitHub and GitLab each get their own request shapes behind
+// one `openPullRequest` entry point, and every capability added to one is added to the other.
+// ---------------------------------------------------------------------------
+import { HarnessFailure } from './failure.js';
+import { preserveManagedSection } from './pr-description.js';
+import { redactSecrets } from './redact.js';
+/**
+ * Classify a PR/MR-open REST failure by its HTTP status into an actionable remedy, else
+ * undefined (an unmapped status keeps just the raw `Failed to open … (HTTP n)` line). Like
+ * {@link describeGitFailure} this only APPENDS a cause + fix — the raw status line is
+ * load-bearing detail and stays. `provider` tailors the scope/permission wording (GitHub App
+ * Pull-requests permission / `repo` PAT scope vs GitLab `api` scope) and the noun (pull
+ * request vs merge request). Pure, so it is unit-tested per status.
+ */
+export function describePrOpenFailure(status, provider) {
+    const noun = provider === 'gitlab' ? 'merge request' : 'pull request';
+    if (status === 401) {
+        return (`The credential was rejected while opening the ${noun}. The GitHub App installation token ` +
+            '(or, in local mode, the GITHUB_PAT) is most likely expired, rotated, or revoked — reconnect ' +
+            'the GitHub App for the workspace (or regenerate the PAT), then retry.');
+    }
+    if (status === 403) {
+        const scope = provider === 'gitlab'
+            ? 'the GitLab token needs the `api` scope and Developer+ access to the project'
+            : 'the GitHub App needs the "Pull requests: write" permission (or the PAT the `repo` scope) and write access to the repository';
+        return `The credential lacks permission to open a ${noun}: ${scope}. Grant it, then retry.`;
+    }
+    if (status === 404) {
+        return (`The repository could not be found while opening the ${noun} — it may have been deleted, ` +
+            'renamed, or made private, or the credential can no longer see it. Confirm the repo and the ' +
+            "credential's access to it, then retry.");
+    }
+    if (status === 422 || status === 400) {
+        return (`GitHub/GitLab rejected the ${noun} as invalid. Usually the head or base branch does not ` +
+            'exist, the two branches are identical (nothing to compare), or the base branch is protected ' +
+            'against direct PRs. Check the branch names and that the head has commits ahead of the base, ' +
+            'then retry.');
+    }
+    return undefined;
+}
+/**
+ * The VCS host a clone URL points at. The harness is otherwise provider-agnostic (its git
+ * auth is a host-neutral GIT_ASKPASS credential), but the "open the PR/MR" REST call is not:
+ * GitHub and GitLab have different endpoints, so infer which to call from the host. GitHub is
+ * the default; a host of `gitlab.com` or one in the `gitlab.*` / `*.gitlab.*` family (covering
+ * self-managed instances named that way) is treated as GitLab.
+ */
+export function inferVcsProvider(cloneUrl) {
+    let host = '';
+    try {
+        host = new URL(cloneUrl).host.toLowerCase();
+    }
+    catch {
+        return 'github';
+    }
+    if (host === 'gitlab.com' || host.startsWith('gitlab.') || host.includes('.gitlab.')) {
+        return 'gitlab';
+    }
+    return 'github';
+}
+/** The GitLab REST v4 base for a clone URL's host, e.g. `https://gitlab.com/api/v4`. */
+export function gitlabApiBaseFromCloneUrl(cloneUrl) {
+    const u = new URL(cloneUrl);
+    return `${u.protocol}//${u.host}/api/v4`;
+}
+/**
+ * The URL-encoded GitLab project path from a clone URL — the full namespace path (so subgroups
+ * survive), with the trailing `.git` stripped, e.g.
+ * `https://gitlab.com/group/sub/proj.git` → `group%2Fsub%2Fproj`.
+ */
+export function gitlabProjectPath(cloneUrl) {
+    const path = new URL(cloneUrl).pathname.replace(/^\/+/, '').replace(/\.git$/, '');
+    return encodeURIComponent(path);
+}
+/** The abort reason as an Error (the watchdog aborts with one), or a generic fallback. */
+function abortError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error('aborted');
+}
+/** Whether a thrown fetch error is an AbortError (caller-initiated, never retried). */
+function isAbortError(err) {
+    return err instanceof Error && err.name === 'AbortError';
+}
+/**
+ * Parse a `Retry-After` header into ms, bounded so it can't stall the job. Accepts BOTH
+ * forms the spec allows: integer delay-seconds (`120`) and an HTTP-date (`Wed, 21 Oct 2026
+ * 07:28:00 GMT`); the latter is turned into a delay from now. A past/zero/unparseable value
+ * yields undefined so the caller falls back to exponential backoff.
+ */
+function retryAfterMs(res) {
+    const raw = res.headers.get('retry-after');
+    if (!raw)
+        return undefined;
+    const secs = Number(raw);
+    if (Number.isFinite(secs)) {
+        return secs > 0 ? Math.min(secs * 1000, MAX_RETRY_AFTER_MS) : undefined;
+    }
+    const at = Date.parse(raw);
+    if (Number.isNaN(at))
+        return undefined;
+    const ms = at - Date.now();
+    return ms > 0 ? Math.min(ms, MAX_RETRY_AFTER_MS) : undefined;
+}
+/** Sleep `ms`, rejecting immediately (with the abort reason) if `signal` aborts meanwhile. */
+function abortableDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(abortError(signal));
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+const MAX_RETRY_AFTER_MS = 8_000;
+const RETRY_BASE_MS = 500;
+const RETRY_MAX_DELAY_MS = 4_000;
+/**
+ * Run a single HTTP request with bounded retry for TRANSIENT failures, so a momentary
+ * upstream blip (a 5xx, a 429 rate-limit, or a dropped connection) no longer fails an
+ * otherwise-complete run on its very last step (opening the PR/MR). Up to 3 attempts
+ * (2 retries) with exponential backoff + jitter (honoring a `Retry-After` on a 429),
+ * every wait abort-aware so the inactivity/max-duration watchdog still cancels promptly.
+ *
+ * ONLY transient failures retry: a `>=500`/`429` response, or a network-level fetch
+ * rejection. A 4xx (incl. the 422/409 "already exists" the callers treat as success) is
+ * returned to the caller unretried, and a caller abort is rethrown at once. The response
+ * body is never read here, so the caller's existing status handling is unchanged.
+ */
+async function withApiRetry(fn, opts = {}) {
+    const maxAttempts = opts.attempts ?? 3;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (opts.signal?.aborted)
+            throw abortError(opts.signal);
+        let res;
+        try {
+            res = await fn();
+        }
+        catch (err) {
+            // A caller/watchdog abort is terminal; a network error is transient → retry.
+            if (isAbortError(err) || opts.signal?.aborted)
+                throw err;
+            lastError = err;
+        }
+        if (res) {
+            const transient = res.status >= 500 || res.status === 429;
+            if (!transient || attempt >= maxAttempts)
+                return res;
+            const after = retryAfterMs(res);
+            // Discard the unread body before retrying so the connection can be reused.
+            await res.body?.cancel().catch(() => { });
+            await abortableDelay(after ?? backoffMs(attempt), opts.signal);
+            continue;
+        }
+        if (attempt >= maxAttempts)
+            break;
+        await abortableDelay(backoffMs(attempt), opts.signal);
+    }
+    // Exhausted on a network-level rejection (no HTTP response): an upstream API failure.
+    const message = lastError instanceof Error ? lastError.message : 'API request failed after retries';
+    throw new HarnessFailure('api', redactSecrets(message));
+}
+/** Exponential backoff (base 500ms, capped 4s) with up to 25% positive jitter. */
+function backoffMs(attempt) {
+    const base = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_MS * 2 ** (attempt - 1));
+    return base + Math.floor(base * 0.25 * Math.random());
+}
+/**
+ * Open a PR (GitHub) or merge request (GitLab) for the pushed branch; returns its web URL.
+ * The provider is chosen from the EXPLICIT `opts.provider` when the dispatcher set it,
+ * falling back to host inference from the clone URL only when it didn't — so a self-managed
+ * GitLab whose host isn't named `gitlab.*` still opens an MR instead of being misrouted to
+ * GitHub's API. The GitHub path is unchanged.
+ */
+export async function openPullRequest(opts) {
+    const provider = opts.provider ?? (opts.cloneUrl ? inferVcsProvider(opts.cloneUrl) : 'github');
+    if (provider === 'gitlab') {
+        if (!opts.cloneUrl) {
+            throw new Error('Cannot open a GitLab merge request without the repo clone URL');
+        }
+        return openGitLabMergeRequest({ ...opts, cloneUrl: opts.cloneUrl });
+    }
+    const apiBase = opts.apiBase ?? 'https://api.github.com';
+    const path = `${encodeURIComponent(opts.owner)}/${encodeURIComponent(opts.name)}`;
+    const res = await withApiRetry(() => fetch(`${apiBase}/repos/${path}/pulls`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${opts.ghToken}`,
+            accept: 'application/vnd.github+json',
+            'user-agent': 'cat-factory-executor',
+            'x-github-api-version': '2022-11-28',
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            title: opts.pr.title,
+            head: opts.head,
+            base: opts.base,
+            body: opts.pr.body,
+        }),
+        // Bound on the watchdog so a hung GitHub call can't stall the job.
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    }), { signal: opts.signal });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => '');
+        // A resumed run pushes to a branch that already has an open PR; GitHub answers
+        // 422 "A pull request already exists". That's success for us — return the
+        // existing PR's url rather than failing the resumed run.
+        if (res.status === 422 && /pull request already exists/i.test(detail)) {
+            const existing = await findOpenPullRequest(opts);
+            if (existing) {
+                if (opts.refreshExisting)
+                    await refreshPullRequest(opts, existing);
+                return existing.url;
+            }
+        }
+        // The head branch has nothing ahead of base ("No commits between <base> and <head>").
+        // That is not an API failure — there is simply nothing to open a PR for (e.g. a resumed
+        // branch whose earlier PR was merged with a merge commit, leaving the branch reachable
+        // from base). Signal it with null so the caller records a clean no-op instead of failing
+        // the run with GitHub's opaque 422.
+        if (res.status === 422 && /no commits between/i.test(detail))
+            return null;
+        const remedy = describePrOpenFailure(res.status, 'github');
+        const base = redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+        throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base);
+    }
+    const body = (await res.json());
+    if (!body.html_url)
+        throw new HarnessFailure('api', 'GitHub did not return a PR url');
+    return body.html_url;
+}
+/** GitLab API headers for the PAT (the `PRIVATE-TOKEN` auth GitLab uses). */
+function gitlabHeaders(token) {
+    return {
+        'private-token': token,
+        accept: 'application/json',
+        'user-agent': 'cat-factory-executor',
+        'content-type': 'application/json',
+    };
+}
+/**
+ * Open a GitLab merge request (the analogue of {@link openPullRequest} for GitLab). The REST
+ * base + project path are derived from the clone URL's host, so it works for gitlab.com and a
+ * self-managed instance alike. `head`→`source_branch`, `base`→`target_branch`. On a duplicate
+ * (a resumed run whose branch already has an open MR — GitLab answers 409) the existing MR's
+ * web URL is returned instead of failing the run, mirroring the GitHub 422 handling.
+ */
+async function openGitLabMergeRequest(opts) {
+    const apiBase = gitlabApiBaseFromCloneUrl(opts.cloneUrl);
+    const project = gitlabProjectPath(opts.cloneUrl);
+    const res = await withApiRetry(() => fetch(`${apiBase}/projects/${project}/merge_requests`, {
+        method: 'POST',
+        headers: gitlabHeaders(opts.ghToken),
+        body: JSON.stringify({
+            source_branch: opts.head,
+            target_branch: opts.base,
+            title: opts.pr.title,
+            description: opts.pr.body,
+        }),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    }), { signal: opts.signal });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => '');
+        // GitLab returns 409 (sometimes 400) when an open MR already exists for this source
+        // branch; that is success for a resumed run — return the existing MR's url.
+        if ((res.status === 409 || res.status === 400) &&
+            /already exists|open merge request/i.test(detail)) {
+            const existing = await findOpenMergeRequest(apiBase, project, opts);
+            if (existing) {
+                if (opts.refreshExisting)
+                    await refreshMergeRequest(apiBase, project, opts, existing);
+                return existing.url;
+            }
+        }
+        const remedy = describePrOpenFailure(res.status, 'gitlab');
+        const base = redactSecrets(`Failed to open merge request (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+        throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base);
+    }
+    const body = (await res.json());
+    if (!body.web_url)
+        throw new HarnessFailure('api', 'GitLab did not return a merge request url');
+    return body.web_url;
+}
+/**
+ * Rewrite an already-open MR's title and description — the GitLab half of
+ * {@link refreshPullRequest}, so a resumed run's agent briefing reaches both hosts alike.
+ * Best-effort for the same reason.
+ */
+async function refreshMergeRequest(apiBase, project, opts, existing) {
+    if (existing.number === undefined)
+        return;
+    await fetch(`${apiBase}/projects/${project}/merge_requests/${existing.number}`, {
+        method: 'PUT',
+        headers: gitlabHeaders(opts.ghToken),
+        body: JSON.stringify({
+            title: opts.pr.title,
+            description: preserveManagedSection(existing.body, opts.pr.body),
+        }),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    }).catch(() => undefined);
+}
+/** Find the open GitLab MR for `opts.head`→`opts.base`, or undefined when there is none. */
+async function findOpenMergeRequest(apiBase, project, opts) {
+    // Filter by BOTH branches: a source branch can have open MRs to several targets, so the
+    // source alone could match an MR against a different base than the one we just tried to open.
+    const query = new URLSearchParams({
+        source_branch: opts.head,
+        target_branch: opts.base,
+        state: 'opened',
+    });
+    const res = await fetch(`${apiBase}/projects/${project}/merge_requests?${query}`, {
+        headers: gitlabHeaders(opts.ghToken),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    if (!res.ok)
+        return undefined;
+    const list = (await res.json().catch(() => []));
+    const found = Array.isArray(list) ? list[0] : undefined;
+    if (!found?.web_url)
+        return undefined;
+    return {
+        url: found.web_url,
+        // `iid` (project-scoped) is what the update endpoint addresses, not the global `id`.
+        ...(typeof found.iid === 'number' ? { number: found.iid } : {}),
+        body: found.description ?? undefined,
+    };
+}
+/**
+ * Rewrite an already-open PR's title and description from `opts.pr` (a resumed run whose agent
+ * wrote a fresh reviewer briefing — see {@link OpenPullRequestOptions.refreshExisting}).
+ *
+ * Best-effort by construction: the work is already pushed and the PR already exists, so a failed
+ * refresh must degrade to the stale description rather than fail the run.
+ */
+async function refreshPullRequest(opts, existing) {
+    if (existing.number === undefined)
+        return;
+    const apiBase = opts.apiBase ?? 'https://api.github.com';
+    const path = `${encodeURIComponent(opts.owner)}/${encodeURIComponent(opts.name)}`;
+    await fetch(`${apiBase}/repos/${path}/pulls/${existing.number}`, {
+        method: 'PATCH',
+        headers: {
+            authorization: `Bearer ${opts.ghToken}`,
+            accept: 'application/vnd.github+json',
+            'user-agent': 'cat-factory-executor',
+            'x-github-api-version': '2022-11-28',
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            title: opts.pr.title,
+            body: preserveManagedSection(existing.body, opts.pr.body),
+        }),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    }).catch(() => undefined);
+}
+/** Find the open PR for `opts.head` on `opts.base`, or undefined when there is none. */
+async function findOpenPullRequest(opts) {
+    const apiBase = opts.apiBase ?? 'https://api.github.com';
+    // Encode the ref-derived query params: a branch/owner containing `&` or `#` would
+    // otherwise split the query string or inject an unintended parameter.
+    const query = new URLSearchParams({
+        head: `${opts.owner}:${opts.head}`,
+        base: opts.base,
+        state: 'open',
+    });
+    const path = `${encodeURIComponent(opts.owner)}/${encodeURIComponent(opts.name)}`;
+    const res = await fetch(`${apiBase}/repos/${path}/pulls?${query}`, {
+        headers: {
+            authorization: `Bearer ${opts.ghToken}`,
+            accept: 'application/vnd.github+json',
+            'user-agent': 'cat-factory-executor',
+            'x-github-api-version': '2022-11-28',
+        },
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    if (!res.ok)
+        return undefined;
+    const list = (await res.json().catch(() => []));
+    const found = Array.isArray(list) ? list[0] : undefined;
+    if (!found?.html_url)
+        return undefined;
+    return {
+        url: found.html_url,
+        ...(typeof found.number === 'number' ? { number: found.number } : {}),
+        body: found.body ?? undefined,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.60.0",
+  "version": "1.62.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,8 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.154.0",
-    "@cat-factory/spend": "0.12.90"
+    "@cat-factory/kernel": "0.168.0",
+    "@cat-factory/spend": "0.12.97",
+    "@cat-factory/server": "0.158.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -22,16 +22,16 @@ import {
   fetchReferenceBranches,
   hasAgentChanges,
   headCommit,
-  inferVcsProvider,
   mergeBranch,
-  openPullRequest,
   prepareExistingCheckout,
   pushBranch,
   reinitAndPush,
   unmergedPaths,
 } from './git.js'
+import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi.js'
 import type { EffortReport } from './effort.js'
+import { applyPrDescription } from './pr-description.js'
 import {
   makeDirClaimer,
   noChangesReason,
@@ -998,6 +998,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     validationReport,
     reproductionReport,
     effortReport,
+    prDescription,
   } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts)
   // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
   // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
@@ -1073,7 +1074,11 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ghToken: job.ghToken,
       head: pushBranch,
       base: job.repo.baseBranch,
-      pr: job.pr,
+      // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text.
+      pr: applyPrDescription(job.pr, prDescription),
+      // A resumed run's PR is already open, so refresh it rather than lose the briefing to the
+      // duplicate-PR 422 — only from a REAL briefing (see `refreshExisting` for why).
+      ...(prDescription ? { refreshExisting: true } : {}),
       apiBase: job.githubApiBase,
       // The provider (set by the server from the configured backend) selects GitHub-PR vs
       // GitLab-MR authoritatively; the clone URL supplies the GitLab REST base + project path.