@cat-factory/executor-harness 1.60.0 → 1.62.0

package/src/coding-agent.ts

@@ -24,15 +24,21 @@ import {
   fetchReferenceBranches,
   headCommit,
   listUntrackedFiles,
-  openPullRequest,
   prepareExistingCheckout,
   pushBranch,
   refreshFromBaseIfClean,
   remoteBranchExists,
 } from './git.js'
+import { openPullRequest } from './vcs-api.js'
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js'
 import type { HarnessCallMetric, PiRunStats } from './pi.js'
 import { EFFORT_REPORT_FILE, type EffortReport } from './effort.js'
+import {
+  type AgentPrDescription,
+  applyPrDescription,
+  PR_DESCRIPTION_FILE,
+  readPrDescription,
+} from './pr-description.js'
 import {
   acquireRepoCheckout,
   agentNeverActed,
@@ -157,6 +163,12 @@ export interface CodingAgentOutcome {
   callMetrics?: HarnessCallMetric[]
   /** The agent's effort self-assessment, lifted from its sentinel file (absent when it wrote none). */
   effortReport?: EffortReport
+  /**
+   * The agent-authored PR description, lifted from its sentinel file (absent when it wrote none).
+   * The PR-opening caller folds it over the dispatch-time title/body via {@link applyPrDescription};
+   * absent means the fallback text, unchanged.
+   */
+  prDescription?: AgentPrDescription
   /**
    * Ralph loop: the verdict of the post-commit validation command (whether it exited 0, the
    * exit code, and a bounded/redacted output tail). Present only when {@link CodingAgentSpec.validation}
@@ -295,6 +307,9 @@ export async function runCodingAgent(
       // 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
@@ -624,6 +639,14 @@ async function finalizeCodingRun(args: {
   // 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).
@@ -686,6 +709,7 @@ async function finalizeCodingRun(args: {
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...(effortReport ? { effortReport } : {}),
+      ...(prDescription ? { prDescription } : {}),
     }
   }
 
@@ -1017,6 +1041,7 @@ export async function runMultiRepoCoding(
       job,
       logger,
       opts,
+      root,
     )
 
     const anyWork = primaryPushed || peerPullRequests.length > 0
@@ -1129,6 +1154,9 @@ async function prepareMultiRepoCheckouts(
       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
@@ -1187,6 +1215,8 @@ async function pushMultiRepoLegs(
   job: AgentJob,
   logger: Logger,
   opts: RunOptions,
+  /** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
+  root: string,
 ): Promise<{
   primaryPushed: boolean
   primaryPrUrl: string | undefined
@@ -1201,6 +1231,15 @@ async function pushMultiRepoLegs(
     // A read-only reference leg is never committed or pushed — the third layer of the read-only
     // 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
@@ -1229,7 +1268,10 @@ async function pushMultiRepoLegs(
         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/src/git.ts

@@ -3,7 +3,7 @@ import { appendFile, chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { promisify } from 'node:util'
-import type { BootstrapTargetSpec, PrSpec, RepoSpec } from './job.js'
+import type { BootstrapTargetSpec, RepoSpec } from './job.js'
 import { pathExists } from './fs-utils.js'
 import { redactSecrets } from './redact.js'
 import { loadRunnerLimits } from './runner.js'
@@ -174,51 +174,6 @@ export function describeGitFailure(stderr: string): string | undefined {
   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: number,
-  provider: 'github' | 'gitlab',
-): string | undefined {
-  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:
@@ -1096,342 +1051,3 @@ export async function reinitAndPush(opts: {
     env: await authEnv(opts.ghToken),
   })
 }
-
-export interface OpenPullRequestOptions {
-  owner: string
-  name: string
-  ghToken: string
-  head: string
-  base: string
-  pr: PrSpec
-  apiBase?: string
-  /**
-   * The repo's clone URL. Used (when {@link provider} is absent) to detect the provider and,
-   * for GitLab, to derive the REST base + project path from its host — so the harness opens a
-   * GitLab **merge request** rather than POSTing to GitHub's pulls API. Absent ⇒ GitHub.
-   */
-  cloneUrl?: string
-  /**
-   * The VCS provider, when the dispatcher knows it (the server derives it from the configured
-   * source-control backend and sets `repo.provider`). AUTHORITATIVE — it overrides host
-   * inference — so a self-managed GitLab on an arbitrarily-named host (e.g. `git.acme.com`,
-   * which {@link inferVcsProvider} can't recognise) still opens a merge request instead of
-   * being misrouted to GitHub's API. Absent ⇒ inferred from {@link cloneUrl}'s host.
-   */
-  provider?: 'github' | 'gitlab'
-  signal?: AbortSignal
-}
-
-/**
- * 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: string): 'github' | 'gitlab' {
-  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: string): string {
-  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: string): string {
-  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: AbortSignal): Error {
-  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: unknown): boolean {
-  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: Response): number | undefined {
-  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: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(abortError(signal))
-    const onAbort = (): void => {
-      clearTimeout(timer)
-      reject(abortError(signal as AbortSignal))
-    }
-    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: () => Promise<Response>,
-  opts: { signal?: AbortSignal; attempts?: number } = {},
-): Promise<Response> {
-  const maxAttempts = opts.attempts ?? 3
-  let lastError: unknown
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    if (opts.signal?.aborted) throw abortError(opts.signal)
-    let res: Response | undefined
-    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: number): number {
-  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: OpenPullRequestOptions): Promise<string | null> {
-  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()) as { html_url?: string }
-  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: string): Record<string, string> {
-  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: OpenPullRequestOptions & { cloneUrl: string },
-): Promise<string> {
-  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()) as { web_url?: string }
-  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: string,
-  project: string,
-  opts: { head: string; base: string; ghToken: string; signal?: AbortSignal },
-): Promise<string | undefined> {
-  // 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(() => [])) as Array<{ web_url?: string }>
-  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: {
-  owner: string
-  name: string
-  ghToken: string
-  head: string
-  base: string
-  apiBase?: string
-  signal?: AbortSignal
-}): Promise<string | undefined> {
-  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(() => [])) as Array<{ html_url?: string }>
-  return Array.isArray(list) && list[0]?.html_url ? list[0].html_url : undefined
-}

package/src/host-markdown.ts

@@ -0,0 +1,155 @@
+// ---------------------------------------------------------------------------
+// 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: string): string {
+  return mapOutsideCodeSpans(line, (text) =>
+    text.replace(AUTO_LINK_TRIGGERS, (match, ...args) => {
+      const groups = args[args.length - 1] as Record<string, string | undefined>
+      // 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: string, fn: (text: string) => string): string {
+  const out: string[] = []
+  let index = 0
+  const span = /(`+)[\s\S]*?\1/g
+  let match: RegExpExecArray | null
+  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: string): { char: string; length: number; info: boolean } | null {
+  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: readonly string[],
+  visit: (line: string, insideFence: boolean) => void,
+): { char: string; length: number } | null {
+  let open: { char: string; length: number } | null = 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: string): string {
+  const normalised = text.replace(/\r\n?/g, '\n')
+  const rewritten: string[] = []
+  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: string): string {
+  return inertLine(text.replace(/\s+/g, ' '))
+}