@cat-factory/executor-harness 1.60.0 → 1.64.0

package/dist/vcs-api.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.60.0",
+  "version": "1.64.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.154.0",
-    "@cat-factory/spend": "0.12.90"
+    "@cat-factory/kernel": "0.170.0",
+    "@cat-factory/server": "0.160.0",
+    "@cat-factory/spend": "0.12.99"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -19,6 +19,7 @@ import {
   type PiRunStats,
   type TodoProgress,
 } from './pi.js'
+import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
 import { createSliceTracker, startSubagentWatcher } from './subagents.js'
@@ -101,6 +102,17 @@ export interface SubscriptionRunOptions {
   extraEnv?: Record<string, string>
   /** Aborting this kills the CLI (the job's inactivity/max-duration watchdog). */
   signal?: AbortSignal
+  /**
+   * Fully-resolved no-progress guard limits (env defaults merged loosen-only with the kind's
+   * tuning + any complexity-scaled allowance). When set, the claude-code runner runs the SAME
+   * {@link ProgressGuard} as Pi over the CLI's tool stream and kills a run that has plainly
+   * stopped making progress (no-edit probing, error-retry loop, web rabbit-hole) rather than
+   * letting it burn the whole wall-clock budget. Omitted ⇒ the guard is disabled for this run
+   * (only the external watchdog bounds it), preserving the pre-guard behaviour.
+   */
+  guardLimits?: ProgressGuardLimits
+  /** Whether this run is expected to edit files (false for assess-only runs); gates the no-edit bound. */
+  expectsEdits?: boolean
   /** Called on every chunk of CLI output, so the watchdog sees the agent is alive. */
   onActivity?: () => void
   /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
@@ -154,7 +166,7 @@ function streamCli(
   opts: SubscriptionRunOptions,
   env: Record<string, string>,
   secrets: string[],
-  onEvent: (event: Record<string, unknown>) => void,
+  onEvent: (event: Record<string, unknown>, meta?: { final?: boolean }) => void,
 ): Promise<{ stderrTail: string }> {
   const { command, args } = cli
   return new Promise((resolve, reject) => {
@@ -178,7 +190,12 @@ function streamCli(
 
     const killChild = (): void => killChildProcess(child)
 
-    const processLine = (line: string): void => {
+    // `final` marks the at-close flush of a trailing unterminated line: the CLI has already
+    // exited, so an observer must not act on that record in a way that KILLS the run (mirrors
+    // `runPi`'s `runGuard = false` flush — without it, a guard tripping on the last buffered
+    // record could turn a clean exit into a spurious "no progress" failure). The record's
+    // progress/telemetry signal is still delivered; only kill decisions are suppressed.
+    const processLine = (line: string, final = false): void => {
       if (!line.startsWith('{')) return
       let event: Record<string, unknown>
       try {
@@ -187,7 +204,7 @@ function streamCli(
         return
       }
       try {
-        onEvent(event)
+        onEvent(event, { final })
       } catch {
         // A faulty observer must never break the run.
       }
@@ -226,10 +243,13 @@ function streamCli(
     })
     child.on('close', (code) => {
       opts.signal?.removeEventListener('abort', onAbort)
-      if (lineBuffer.trim()) processLine(lineBuffer.trim())
       const stderrTail = redact(stderr, secrets).slice(-700)
+      if (lineBuffer.trim()) processLine(lineBuffer.trim(), true)
       if (aborted) {
-        reject(new Error('agent run aborted by watchdog'))
+        // Carry the tail on the rejection so a caller that REPLACES this generic message with a
+        // more specific cause (the no-progress guard's diagnostic) can still append it — the
+        // stderr is often the only evidence of what the CLI was doing when it was killed.
+        reject(Object.assign(new Error('agent run aborted by watchdog'), { stderrTail }))
         return
       }
       if (code !== 0) {
@@ -382,7 +402,42 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     if (progress) opts.onProgress(progress)
   }
 
-  const onEvent = (event: Record<string, unknown>): void => {
+  // No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
+  // absent on this path until now. Claude Code reports a tool CALL (its name) on the `assistant`
+  // turn and that call's RESULT (`is_error`) on the following `user` turn, so correlate them by
+  // `tool_use` id to feed the guard a {name,isError} signal. A tripped guard aborts the CLI via
+  // `guardAbort` (folded into streamCli's signal below) and the run then fails with its
+  // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
+  const guard = opts.guardLimits
+    ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
+    : undefined
+  const toolNames = new Map<string, string>()
+  const guardAbort = new AbortController()
+  let guardReason: string | undefined
+
+  // Feed a user turn's settled tool calls to the guard, pairing each `tool_result`'s `is_error`
+  // with the name captured for its `tool_use` id on the assistant turn. The FIRST reason trips
+  // it: record the diagnostic and abort the CLI (streamCli's close handler rejects; the catch
+  // below surfaces `guardReason` over the generic abort message). A standalone closure so the
+  // per-block loop doesn't nest onEvent past the readable-depth limit.
+  const feedGuard = (content: unknown[]): void => {
+    if (!guard || guardReason) return
+    for (const block of content) {
+      if (!isObject(block) || block.type !== 'tool_result') continue
+      const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined
+      const name = id ? toolNames.get(id) : undefined
+      if (id) toolNames.delete(id)
+      if (!name) continue
+      const reason = guard.observeSignal({ name, isError: block.is_error === true })
+      if (reason) {
+        guardReason = reason
+        guardAbort.abort()
+        return
+      }
+    }
+  }
+
+  const onEvent = (event: Record<string, unknown>, meta?: { final?: boolean }): void => {
     const type = event.type
     if (type === 'assistant' && isObject(event.message)) {
       const message = event.message as Record<string, unknown>
@@ -391,7 +446,13 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       stats.assistantChars += text.length
       stats.toolCalls += toolUses
       for (const block of content) {
-        if (isObject(block) && block.type === 'tool_use' && block.name === 'TodoWrite') {
+        if (!isObject(block) || block.type !== 'tool_use') continue
+        // Remember each call's name against its id so the guard can pair it with the
+        // `is_error` its `tool_result` carries on the next `user` turn.
+        if (typeof block.id === 'string' && typeof block.name === 'string') {
+          toolNames.set(block.id, block.name)
+        }
+        if (block.name === 'TodoWrite') {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
           if (progress) lastTodo = progress
         }
@@ -422,6 +483,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         sliceTracker.onUser(content)
         planTracker.onUser(content)
         emitProgress()
+        // Not on the at-close flush: the CLI has already exited, so tripping the guard there
+        // would kill nothing and only convert a clean exit into a spurious failure.
+        if (!meta?.final) feedGuard(content)
         messages.push({ role: 'tool', content })
       }
     } else if (type === 'result') {
@@ -488,6 +552,12 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       })
     : undefined
 
+  // Fold the guard's abort into the run signal so a tripped guard kills the CLI the same way the
+  // external watchdog does; `guardReason` (set above) distinguishes the two at the catch below.
+  const runSignal = opts.signal
+    ? AbortSignal.any([opts.signal, guardAbort.signal])
+    : guardAbort.signal
+
   try {
     const { stderrTail } = await streamCli(
       {
@@ -509,7 +579,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         ],
       },
       prompt,
-      opts,
+      { ...opts, signal: runSignal },
       env,
       opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [],
       onEvent,
@@ -524,6 +594,16 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       usage,
       subagents,
     })
+  } catch (err) {
+    // A tripped no-progress guard aborted the CLI; streamCli rejects with its generic abort
+    // message, so replace it with the guard's actionable diagnostic — carrying the stderr tail
+    // it attached, since that is usually the only evidence of what the CLI was doing when it was
+    // killed. Byte-for-byte the shape `runPi` fails with.
+    if (guardReason) {
+      const tail = (err as { stderrTail?: string } | undefined)?.stderrTail
+      throw new Error(tail ? `${guardReason} Agent stderr: ${tail}` : guardReason)
+    }
+    throw err
   } finally {
     await subagents?.stop()
     if (configHome) {

package/src/agent.ts

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

package/src/claude-stream.ts

@@ -10,6 +10,25 @@ export function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }
 
+/**
+ * The tool names the Claude Code CLI dispatches a parallel subagent under. `Agent` is what the
+ * shipped schema declares (`AgentInput` in `sdk-tools.d.ts`, carrying `description` / `prompt` /
+ * `subagent_type`); `Task` is the older name for the same dispatch. Both are matched because the
+ * harness runs against whatever CLI the image happens to bundle, and matching only the old name
+ * is what left a CLI 2.1.x pr-review reporting no slices at all.
+ *
+ * Note the asymmetry: keeping the legacy `Task` here is the one place a CLI rename could produce a
+ * FALSE signal rather than merely no signal — if a future build were to name a plain task-list
+ * tool `Task`, its writes would be counted as in-flight slices. We accept that because no shipped
+ * build does (the incremental plan tool is `TaskCreate`/`TaskUpdate`, tracked separately in
+ * `progress.ts`), and dropping legacy coverage is the more likely regression.
+ *
+ * Lives here rather than in `subagents.ts` because BOTH the slice tracker and the no-progress
+ * guard (`pi.ts`, which `subagents.ts` imports — so it cannot import back) must agree on what a
+ * subagent dispatch looks like.
+ */
+export const SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task'])
+
 export function numberOf(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0
 }