@cat-factory/executor-harness 1.60.0 → 1.62.0

package/README.md

@@ -73,7 +73,16 @@ The implementation job (`POST /run`) is the canonical sequence:
 6. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
    ONLY if step 4 ended green. A spent budget returns an error result with the validation report
    and opens no PR. Absent `validationChecks` / `reproduction`, steps 4 and 5 do not happen at
-   all.
+   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
+   run; an optional leading `# <title>` line, when it is the file's only `#` heading, sets the PR
+   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.
 
 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

@@ -6,7 +6,9 @@ import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
-import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, inferVcsProvider, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { inferVcsProvider, openPullRequest } from './vcs-api.js';
+import { applyPrDescription } from './pr-description.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
@@ -822,7 +824,7 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
  */
 async function runSingleRepoCoding(job, opts) {
     const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, validationReport, reproductionReport, effortReport, } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, validationReport, reproductionReport, effortReport, prDescription, } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
     // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
     // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
     const ralphVerdict = validation ? { ralphVerdict: validation } : {};
@@ -894,7 +896,11 @@ async function runSingleRepoCoding(job, opts) {
             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.

package/dist/coding-agent.js

@@ -3,9 +3,11 @@ import { join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { killChildProcess, spawnDetached } from './process.js';
 import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
-import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { openPullRequest } from './vcs-api.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { EFFORT_REPORT_FILE } from './effort.js';
+import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription, } from './pr-description.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
 import { runValidationLoop, } from './validation-checks.js';
@@ -115,6 +117,9 @@ export async function runCodingAgent(spec, opts = {}) {
         // but that cannot un-stage a mid-run commit; the per-clone exclude is what prevents it. A bare
         // filename pattern matches the file in any subdirectory, so it covers a monorepo `workDir` too.
         await excludeFromGit(dir, EFFORT_REPORT_FILE, signal);
+        // Same treatment for the agent-authored PR-description sentinel: excluded locally so the
+        // agent's own `git add` can never stage the briefing into the PR it describes.
+        await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal);
         // Follow-up companion: tail the Coder's sentinel file and stream new items out on the
         // job view. Locally exclude it from git first so the agent's own `git add` can never
         // stage it and it never surfaces as an untracked leftover or in the PR. The sentinel
@@ -376,6 +381,12 @@ async function finalizeCodingRun(args) {
     // Safety net for forgotten edits: commit changes to TRACKED files only (never
     // untracked scratch files/artifacts — the agent owns committing new files).
     await commitTrackedEdits(dir, spec.commitMessage, signal);
+    // The agent-authored PR description, read AFTER the validation loop (a repair round may have
+    // changed what the briefing should say) and removed so it never lingers in the checkout. The
+    // prompt asks for it at the top level of the checkout; a monorepo agent working in a service
+    // subdirectory may drop it in its cwd instead, so probe the checkout root first, then the cwd.
+    const prDescription = (await readPrDescription(dir)) ??
+        (workDir !== dir ? await readPrDescription(workDir) : undefined);
     // Stop periodic checkpoints and let any in-flight one settle BEFORE the final
     // push, so the two never run a concurrent `git push` to the same branch (the
     // final push below is then a fresh attempt whose failure is the real signal).
@@ -438,6 +449,7 @@ async function finalizeCodingRun(args) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...(effortReport ? { effortReport } : {}),
+            ...(prDescription ? { prDescription } : {}),
         };
     }
     // Ralph loop: run the programmatic completion command against the pushed/committed
@@ -698,7 +710,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);
+        const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts, root);
         const anyWork = primaryPushed || peerPullRequests.length > 0;
         if (!anyWork) {
             // Nothing changed in ANY repo. For the implementer this is a failure (as in the
@@ -799,6 +811,9 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
             await createBranch(dir, leg.workBranch, signal);
         }
         leg.dir = dir;
+        // Exclude the agent-authored PR-description sentinel locally (as the single-repo path does)
+        // so the agent's own `git add` can never stage the briefing into the PR it describes.
+        await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal);
         // The branch tip before the agent runs. Captured BEFORE the resume base refresh below so
         // that refresh's merge commit counts as advancement and is pushed (as in the single-repo
         // path). A fresh leg produced work iff its branch advances past this; a resumed leg already
@@ -844,7 +859,9 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
  * no PR; a read-only reference leg is never committed or pushed). Extracted so the multi-repo body
  * stays small; returns the primary's push/PR state plus the peer PRs.
  */
-async function pushMultiRepoLegs(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) {
     const { signal } = opts;
     opts.onPhase?.('push');
     let primaryPushed = false;
@@ -855,6 +872,14 @@ async function pushMultiRepoLegs(legs, job, logger, opts) {
         // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
         if (leg.readOnly)
             continue;
+        // Lift (and remove) the agent-authored PR description for THIS repo's PR before anything
+        // else touches the checkout — each sibling checkout carries its own briefing for its own PR.
+        // The agent's cwd here is the WORKSPACE ROOT rather than any one checkout, so an agent that
+        // read the prompt loosely may well have written a single briefing there instead. Fall back
+        // to it for the PRIMARY leg only: at the root there is nothing to say which repo it
+        // describes, and the primary is the one the run is actually about.
+        const agentPrDescription = (await readPrDescription(leg.dir)) ??
+            (leg.primary ? await readPrDescription(root) : undefined);
         await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal);
         const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal);
         let hasWork = advanced || leg.resumed;
@@ -884,7 +909,10 @@ async function pushMultiRepoLegs(legs, job, logger, opts) {
                 ghToken: leg.ghToken,
                 head: leg.workBranch,
                 base: leg.repo.baseBranch,
-                pr: leg.pr,
+                pr: applyPrDescription(leg.pr, agentPrDescription),
+                // See the single-repo call site: refresh a resumed leg's already-open PR, but only
+                // when the text is the agent's own briefing rather than the dispatch-time fallback.
+                ...(agentPrDescription ? { refreshExisting: true } : {}),
                 apiBase: job.githubApiBase,
                 cloneUrl: leg.repo.cloneUrl,
                 ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),

package/dist/git.js

@@ -132,40 +132,6 @@ export function describeGitFailure(stderr) {
     }
     return undefined;
 }
-/**
- * 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;
-}
 /**
  * Wrap a git failure into a credential-scrubbed {@link HarnessFailure}('git') with an ACCURATE
  * message. Three cases the old bare "Command failed: git …" collapsed together:
@@ -878,288 +844,3 @@ export async function reinitAndPush(opts) {
         env: await authEnv(opts.ghToken),
     });
 }
-/**
- * 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 findOpenPullRequestUrl(opts);
-            if (existing)
-                return existing;
-        }
-        // 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 findOpenMergeRequestUrl(apiBase, project, opts);
-            if (existing)
-                return existing;
-        }
-        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;
-}
-/** Find the open GitLab MR for `opts.head`→`opts.base`, returning its web_url or undefined. */
-async function findOpenMergeRequestUrl(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(() => []));
-    return Array.isArray(list) && list[0]?.web_url ? list[0].web_url : undefined;
-}
-/** Find the open PR for `opts.head` on `opts.base`, returning its html_url or undefined. */
-async function findOpenPullRequestUrl(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(() => []));
-    return Array.isArray(list) && list[0]?.html_url ? list[0].html_url : undefined;
-}

package/dist/host-markdown.js

@@ -0,0 +1,142 @@
+// ---------------------------------------------------------------------------
+// The TEXT BOUNDARY for agent-authored text the harness writes onto a VCS host.
+//
+// A pull-request description is NOT an inert string sink. The host parses it: `#123` becomes
+// an issue link, `@name` notifies a real person, a closing keyword in front of an issue
+// reference CLOSES that issue when the PR merges, and an unbalanced code fence swallows
+// everything rendered after it — including the fenced JSON block the engine later appends as
+// the verification report's machine-readable contract.
+//
+// The agent's reviewer briefing (`pr-description.ts`) is model-authored prose that lands
+// verbatim on that surface, so it crosses this boundary first. "This closes #42" is idiomatic
+// for a briefing to emit and must not close issue 42; "@alice owns the rounding rule" is
+// idiomatic and must not page whoever holds that handle.
+//
+// This is a deliberate COPY of `hostMarkdown` in `@cat-factory/kernel`
+// (`src/shared/host-markdown.logic.ts`), for the same reason `isSafeTestPath` is copied: the
+// container image is built from `src/` plus typescript alone (the Dockerfile cannot resolve a
+// `workspace:*` dependency), so the harness carries no runtime dependency on any package here.
+// `test/host-markdown.conformity.test.ts` pins the two implementations to byte-identical
+// output over a shared corpus, so the copy cannot drift — change one, change the other.
+// ---------------------------------------------------------------------------
+/**
+ * The host's closing keywords. A PR body carrying one of these in front of an issue reference
+ * closes that issue on merge — a side effect the harness must never trigger on the agent's
+ * behalf. Same list on GitHub and GitLab.
+ */
+const CLOSING_KEYWORDS = 'close[sd]?|closing|fix|fixe[sd]|fixing|resolve[sd]?|resolving|implement(?:s|ed)?|implementing';
+/** An issue/MR URL on either host, in the form a closing keyword can reference. */
+const ISSUE_URL = String.raw `https?://\S+?/(?:issues|-/issues|merge_requests|pull)/\d+`;
+/**
+ * Every auto-linking trigger, in ONE alternation.
+ *
+ * Deliberately a single pass rather than chained `.replace()` calls: each escape EMITS a `#`,
+ * so a later rule would re-escape the output of an earlier one (`@` → `@` → `@`).
+ * One regex means the replacement text is never rescanned.
+ */
+const AUTO_LINK_TRIGGERS = new RegExp([
+    // A closing keyword in front of an issue/MR URL. The URL form survives the character
+    // escapes below (nothing in it is a trigger), so the KEYWORD is what gets defused.
+    String.raw `(?<keyword>\b(?:${CLOSING_KEYWORDS}))(?=\s*:?\s+${ISSUE_URL})`,
+    // `@name` / `@org/team` — a mention notifies a real account.
+    String.raw `(?<at>@(?=[A-Za-z0-9]))`,
+    // `#123` and `owner/repo#123` — an issue/PR cross-reference.
+    String.raw `(?<hash>#(?=\d))`,
+    // `!123` — GitLab's merge-request reference.
+    String.raw `(?<bang>!(?=\d))`,
+].join('|'), 'gi');
+/**
+ * Neutralise the host's auto-linking triggers in ONE line of untrusted text, leaving inline
+ * code spans alone (the host does not auto-link inside them, so escaping there would only
+ * show the reader a literal `&#35;`).
+ *
+ * The escapes are numeric HTML entities, which render as the original character but are
+ * invisible to the reference parser — so the reader sees exactly what the agent wrote while
+ * the mention/close side effects are defused.
+ */
+function inertLine(line) {
+    return mapOutsideCodeSpans(line, (text) => text.replace(AUTO_LINK_TRIGGERS, (match, ...args) => {
+        const groups = args[args.length - 1];
+        // Entity-escaping the FIRST character is enough to break the parser's match while
+        // rendering identically — which matters most for the keyword, whose remaining letters
+        // are ordinary prose the reader should still see.
+        return `&#${match.charCodeAt(0)};${groups.keyword ? match.slice(1) : ''}`;
+    }));
+}
+/**
+ * Apply `fn` to the parts of `line` that are NOT inline code spans. Code spans are matched by
+ * a backtick run and its matching closer, which is CommonMark's rule and — more to the point
+ * — the rule the host renderer applies when deciding where to auto-link.
+ */
+function mapOutsideCodeSpans(line, fn) {
+    const out = [];
+    let index = 0;
+    const span = /(`+)[\s\S]*?\1/g;
+    let match;
+    while ((match = span.exec(line)) !== null) {
+        out.push(fn(line.slice(index, match.index)), match[0]);
+        index = match.index + match[0].length;
+    }
+    return out.join('') + fn(line.slice(index));
+}
+/** A line that opens or closes a fenced code block, with the fence it uses. */
+function fenceAt(line) {
+    const match = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (!match)
+        return null;
+    const fence = match[1];
+    // A ``` fence's info string may not contain a backtick (CommonMark), which is what stops an
+    // inline span from being read as a fence.
+    if (fence.startsWith('`') && match[2].includes('`'))
+        return null;
+    return { char: fence[0], length: fence.length, info: match[2].trim().length > 0 };
+}
+/**
+ * Walk `lines`, tracking fenced-code state, and hand each line to `visit` together with
+ * whether it sits INSIDE a fenced block. Returns the fence still open at the end, if any.
+ *
+ * One shared walker so the three things that care about fences — leaving code untouched,
+ * closing what the text left open, and finding the briefing's title heading — can never
+ * disagree about where a block starts and ends.
+ */
+export function walkFences(lines, visit) {
+    let open = null;
+    for (const line of lines) {
+        const fence = fenceAt(line);
+        // The fence line itself belongs to the code block, so it is never rewritten.
+        visit(line, open !== null || fence !== null);
+        if (!fence)
+            continue;
+        if (!open)
+            open = { char: fence.char, length: fence.length };
+        else if (fence.char === open.char && fence.length >= open.length && !fence.info)
+            open = null;
+    }
+    return open;
+}
+/**
+ * Render untrusted multi-line markdown safe to send to a host: auto-link triggers defused
+ * outside fenced code, and any fence the text leaves open closed again.
+ *
+ * Unlike kernel's `hostMarkdown.prose` this does NOT cap the length — the caller
+ * ({@link import('./pr-description.js')}) applies its own budget with its own visible note
+ * BEFORE calling here, so an escape entity can never be sliced in half. With that one
+ * difference the output is identical, which the conformity test pins.
+ */
+export function inertMarkdown(text) {
+    const normalised = text.replace(/\r\n?/g, '\n');
+    const rewritten = [];
+    const open = walkFences(normalised.split('\n'), (line, insideFence) => {
+        rewritten.push(insideFence ? line : inertLine(line));
+    });
+    const joined = rewritten.join('\n');
+    return open ? `${joined}\n${open.char.repeat(open.length)}` : joined;
+}
+/**
+ * Render untrusted text INLINE (a pull-request title): newlines folded to spaces because the
+ * surrounding line has its own meaning, and auto-link triggers defused. The caller caps the
+ * length first, for the same reason as {@link inertMarkdown}.
+ */
+export function inertInline(text) {
+    return inertLine(text.replace(/\s+/g, ' '));
+}