@cat-factory/executor-harness 1.58.0 → 1.62.0

package/dist/validation-checks.js

@@ -1,9 +1,58 @@
-import { spawn } from 'node:child_process';
-import { killChildProcess, spawnDetached } from './process.js';
-import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
+import { runCapturedCommand } from './captured-command.js';
+/**
+ * The ceiling the harness clamps a body-supplied `validationChecks.maxAttempts` to, and the
+ * default it applies when the body omits one.
+ *
+ * DELIBERATE DUPLICATES of `VALIDATION_MAX_ATTEMPTS_CEILING` / `VALIDATION_DEFAULT_MAX_ATTEMPTS`
+ * in `@cat-factory/contracts` — the published image takes no schema dependency, so the harness
+ * cannot import them. Keep the two in step: the API validates writes against the contracts
+ * values, so a harness clamping to a DIFFERENT ceiling would silently cap a budget an operator
+ * was allowed to save, with nothing to flag the mismatch.
+ */
+export const VALIDATION_MAX_ATTEMPTS_CEILING = 10;
+export const VALIDATION_DEFAULT_MAX_ATTEMPTS = 3;
+/**
+ * Parse the optional PRE-PR VALIDATION CHECKS envelope off the job body: the service's ordered
+ * `{ label, command }` pairs and the repair-round budget. Every entry needs a non-empty command;
+ * entries without one are dropped, and a spec that ends up with no usable check returns
+ * `undefined` — so a malformed body degrades to the exact pre-feature behaviour (no loop, PR
+ * opens as before) rather than failing an otherwise-good coding run. `maxAttempts` is clamped to
+ * a sane range so a bad body can't make a container loop forever.
+ *
+ * Lives with the feature rather than in `job.ts` so each pre-PR verification phase owns its own
+ * job-body parser next to the loop that consumes it (the reproduction proof's
+ * `parseReproductionSpec` is the sibling); `job.ts` stays the job SHAPE plus the generic
+ * assembly.
+ */
+export function parseValidationChecksSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    if (!Array.isArray(o.checks))
+        return undefined;
+    const checks = [];
+    for (const raw of o.checks) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const c = raw;
+        if (typeof c.command !== 'string' || c.command.trim() === '')
+            continue;
+        const label = typeof c.label === 'string' && c.label.trim() ? c.label.trim() : c.command;
+        checks.push({ label, command: c.command });
+    }
+    if (checks.length === 0)
+        return undefined;
+    const parsed = typeof o.maxAttempts === 'number' && Number.isFinite(o.maxAttempts) && o.maxAttempts > 0
+        ? Math.floor(o.maxAttempts)
+        : undefined;
+    return {
+        checks,
+        maxAttempts: Math.min(parsed ?? VALIDATION_DEFAULT_MAX_ATTEMPTS, VALIDATION_MAX_ATTEMPTS_CEILING),
+    };
+}
 /**
  * Per-command output kept on the REPORT (what crosses the wire and lands in the run's persisted
- * `detail` blob). Deliberately smaller than {@link MAX_CAPTURED_OUTPUT_CHARS}, which is what the
+ * `detail` blob). Deliberately smaller than `MAX_CAPTURED_OUTPUT_CHARS` (`redact.ts`), which is what the
  * AGENT sees in its repair prompt: the agent needs the full failure to fix it, the operator needs
  * enough to recognise it, and a chatty build must not inflate every run's stored state.
  */
@@ -75,88 +124,27 @@ export async function runValidationChecks(cwd, spec, attempt, logger, opts) {
     return { report, fullTails };
 }
 /**
- * Run ONE check as `sh -c <command>` in `cwd`, capturing a bounded, secret-scrubbed tail of its
- * combined stdout+stderr. The exit code is the verdict — computed here by the harness, never
- * self-reported by the model, which is the whole point of a programmatic gate. A watchdog kills
- * the process tree on timeout and an aborted run resolves non-zero, so the loop is never blocked.
- *
- * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
- * not a mutated global: the harness spawns this itself rather than through the agent, so without
- * the explicit merge a native-mode job would run its checks without the private-registry npmrc
- * pointer (and against a sibling job's state, had this been staged in `process.env`).
+ * Run ONE check through the shared {@link runCapturedCommand} seam and shape it as a check
+ * outcome. The exit code is the verdict — computed by the harness, never self-reported by the
+ * model, which is the whole point of a programmatic gate.
  */
 async function runOneCheck(cwd, check, logger, opts) {
-    const timeoutMs = validationCommandTimeoutMs();
-    const startedAt = Date.now();
     logger.info('validation: running check', { label: check.label });
-    return new Promise((resolve) => {
-        let out = '';
-        let settled = false;
-        let timedOut = false;
-        const child = spawn('sh', ['-c', check.command], {
-            cwd,
-            detached: spawnDetached,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, ...opts.agentEnv },
-        });
-        // Keep only the tail; guard against unbounded buffering on a chatty command.
-        const capture = (chunk) => {
-            out = (out + chunk.toString('utf8')).slice(-MAX_CAPTURED_OUTPUT_CHARS);
-        };
-        child.stdout?.on('data', capture);
-        child.stderr?.on('data', capture);
-        const finish = (exitCode) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            opts.signal?.removeEventListener('abort', onAbort);
-            const trimmed = out.trim();
-            // Scrub BEFORE truncating: a token straddling the cut would otherwise survive as a
-            // partial, and the pattern rules need the whole assignment to match.
-            const scrubbed = trimmed ? redactSecrets(trimmed) : '';
-            logger.info('validation: check finished', { label: check.label, exitCode });
-            resolve({
-                outcome: {
-                    label: check.label,
-                    command: check.command,
-                    exitCode,
-                    passed: exitCode === 0,
-                    ...(scrubbed ? { outputTail: tailFor(scrubbed) } : {}),
-                    durationMs: Date.now() - startedAt,
-                    ...(timedOut ? { timedOut: true } : {}),
-                },
-                ...(scrubbed ? { fullTail: scrubbed } : {}),
-            });
-        };
-        const timer = setTimeout(() => {
-            logger.warn('validation: check timed out', { label: check.label, timeoutMs });
-            timedOut = true;
-            killChildProcess(child, undefined, logger);
-            finish(124); // conventional timeout exit code (a non-zero fail)
-        }, timeoutMs);
-        timer.unref?.();
-        const onAbort = () => {
-            killChildProcess(child, undefined, logger);
-            finish(130); // aborted (a non-zero fail)
-        };
-        opts.signal?.addEventListener('abort', onAbort, { once: true });
-        child.on('error', (err) => {
-            logger.warn('validation: check failed to spawn', {
-                label: check.label,
-                error: err instanceof Error ? err.message : String(err),
-            });
-            finish(127); // spawn error / command not found (a non-zero fail)
-        });
-        child.on('close', (code) => finish(code ?? 1));
+    const { fullTail, ...run } = await runCapturedCommand({
+        cwd,
+        command: check.command,
+        timeoutMs: validationCommandTimeoutMs(),
+        reportTailChars: VALIDATION_REPORT_TAIL_CHARS,
+        logLabel: 'validation',
+        logFields: { label: check.label },
+        logger,
+        opts,
     });
-}
-/** Bound an already-scrubbed output tail to what the REPORT carries. */
-function tailFor(scrubbed) {
-    if (scrubbed.length <= VALIDATION_REPORT_TAIL_CHARS)
-        return scrubbed;
-    const trimmed = scrubbed.length - VALIDATION_REPORT_TAIL_CHARS;
-    return `…(${trimmed} earlier chars trimmed)\n${scrubbed.slice(-VALIDATION_REPORT_TAIL_CHARS)}`;
+    logger.info('validation: check finished', { label: check.label, exitCode: run.exitCode });
+    return {
+        outcome: { label: check.label, command: check.command, ...run },
+        ...(fullTail ? { fullTail } : {}),
+    };
 }
 /**
  * The repair instruction handed to the agent after a failed attempt: the failing commands and

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.58.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.153.1",
-    "@cat-factory/spend": "0.12.89"
+    "@cat-factory/kernel": "0.168.0",
+    "@cat-factory/spend": "0.12.97",
+    "@cat-factory/server": "0.158.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",