@cat-factory/executor-harness 1.60.0 → 1.64.0

package/dist/git.js

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

package/dist/host-markdown.js

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

package/dist/pi-workspace.js

@@ -1,9 +1,10 @@
-import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { readEffortReport } from './effort.js';
 import { log } from './logger.js';
-import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, mergeGuardLimits, progressGuardLimitsFromEnv, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
+import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
+import { mergeGuardLimits, progressGuardLimitsFromEnv, } from './progress-guard.js';
 import { runSubscriptionHarness } from './agent-runner.js';
 // The thin base every container agent shares: an ephemeral working directory, and
 // one Pi run inside it driven by the harness-written context. The agents differ in
@@ -106,6 +107,29 @@ export async function acquireRepoCheckout(opts, fn) {
         return withPersistentWorkspace(opts.repo, fn);
     return withWorkspace(opts.prefix, fn);
 }
+/**
+ * Whether the run's checkout actually ships a `blueprints/` folder — what gates the blueprint
+ * orientation note in AGENTS.md (an external repo has none, so the note would be ~10 lines of
+ * dead guidance pointing at files that don't exist, re-sent on every turn).
+ *
+ * A MULTI-REPO run's `dir` is the workspace ROOT with each repo checked out as a sibling under
+ * it, so the root itself never holds `blueprints/`: the legs are checked too, and the note is
+ * included when ANY leg ships one (it orients the agent to the concept, and the agent finds the
+ * per-repo folder from there). Best-effort throughout — any stat/readdir failure simply omits
+ * the note rather than failing the dispatch.
+ */
+export async function checkoutHasBlueprints(dir, multiRepo) {
+    const isBlueprintDir = (path) => stat(join(path, 'blueprints'))
+        .then((s) => s.isDirectory())
+        .catch(() => false);
+    if (await isBlueprintDir(dir))
+        return true;
+    if (!multiRepo)
+        return false;
+    const legs = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const checks = await Promise.all(legs.filter((e) => e.isDirectory()).map((e) => isBlueprintDir(join(dir, e.name))));
+    return checks.some(Boolean);
+}
 /**
  * Write Pi's global agent context (`~/.pi/agent/AGENTS.md`) + provider config,
  * then run Pi once in `spec.dir` and return its summary/stats/stderr. The context
@@ -148,6 +172,13 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             ...(spec.skill ? { skill: spec.skill } : {}),
             ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
             signal: opts.signal,
+            // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
+            // defaults merged loosen-only with the kind's tuning + the backend's complexity-scaled
+            // no-edit allowance, so a claude-code run that stops making progress is killed early
+            // instead of burning the full wall-clock budget. The claude runner consumes it; codex
+            // ignores it for now (its stream isn't wired to the guard).
+            guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
+            expectsEdits: spec.expectsEdits ?? true,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
             // Stream this run's per-call telemetry to the job's live drain. The subscription
@@ -180,11 +211,13 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     const webSearch = webSearchConfigFromEnv({ ...process.env, ...extraEnv });
     if (webSearch)
         await writeWebToolsConfig(webSearch);
+    const hasBlueprints = await checkoutHasBlueprints(spec.dir, spec.multiRepo === true);
     await writeAgentsContext(spec.systemPrompt, {
         webSearch: Boolean(webSearch),
         guidance: spec.webToolsGuidance,
         serviceDirectory: spec.serviceDirectory,
         contextFiles,
+        hasBlueprints,
         ...(spec.multiRepo ? { multiRepo: true } : {}),
     });
     await writePiModelsConfig({ model: spec.model, proxyBaseUrl });