@cat-factory/executor-harness 1.78.0 → 1.82.0

package/dist/effort.d.ts

@@ -0,0 +1,19 @@
+/** The sentinel file the agent writes its effort self-assessment to (relative to its cwd). */
+export declare const EFFORT_REPORT_FILE = ".cat-effort.json";
+/** A container agent's self-assessment of the work it just did. */
+export interface EffortReport {
+    /** How hard the work was: 1 (trivial) .. 10 (extremely hard). */
+    difficulty: number;
+    /** One or two sentences on how hard/easy the work was and why. */
+    summary?: string;
+    /** What reduced the agent's effectiveness. */
+    reducedEffectiveness?: string;
+    /** The key obstacles the agent hit. */
+    obstacles?: string[];
+}
+/**
+ * Read + parse + REMOVE the agent's effort sentinel file from `cwd`. Lenient: returns undefined
+ * when the file is absent (the agent wrote none), unreadable, not JSON, or carries nothing
+ * meaningful. Never throws — a malformed self-report must never fail an otherwise-good run.
+ */
+export declare function readEffortReport(cwd: string): Promise<EffortReport | undefined>;

package/dist/embed.d.ts

@@ -0,0 +1,4 @@
+export { PI_MAX_OUTPUT_TOKENS, writePiModelsConfig, writeAgentsContext, runPi, summarizePiRun, parsePiOutput, parseTodoProgress, terminalRunError, type PiRunOutcome, type PiRunStats, type TodoItem, type TodoProgress, } from './pi.js';
+export { DEFAULT_PROGRESS_GUARD_LIMITS, progressGuardLimitsFromEnv, type ProgressGuardLimits, } from './progress-guard.js';
+export { cloneRepo, createBranch, changedPathsFromPorcelain, hasAgentChanges, redactSecrets, } from './git.js';
+export type { RepoSpec } from './job.js';

package/dist/failure.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The structured reason a harness job failed, surfaced on the job view's `failureCause`.
+ * Covers only HARNESS-owned failures — container eviction is detected by the runtime facade
+ * (a vanished container → `(container evicted or crashed)`), never set here.
+ *
+ *  - `inactivity-timeout` — the inactivity watchdog fired (no agent output for the window).
+ *  - `max-duration`       — the overall wall-clock cap fired.
+ *  - `agent`              — the agent ran but produced an unusable/failed result, or threw.
+ *  - `git`                — a git operation failed (clone/push/merge/PR).
+ *  - `api`                — an upstream API call failed (e.g. the GitHub/GitLab PR/MR REST call).
+ *  - `llm-upstream`       — the model provider rejected every call (auth/quota/rate-limit) and Pi
+ *                           exhausted its retries, so the run never produced a result.
+ *  - `no-usable-output`   — the agent finished but returned no usable report / structured output.
+ *  - `no-changes`         — a coding agent finished without producing any change to push.
+ */
+export type FailureCause = 'inactivity-timeout' | 'max-duration' | 'agent' | 'git' | 'api' | 'llm-upstream' | 'no-usable-output' | 'no-changes';
+/**
+ * A thrown failure that carries a structured {@link FailureCause}, so a `git` / `api`
+ * operation that fails deep in a helper surfaces its real cause instead of being flattened
+ * to the generic `agent` in the registry's catch. The watchdog kills set their cause from
+ * `killReason` and never throw this; anything else thrown without a cause stays `agent`.
+ */
+export declare class HarnessFailure extends Error {
+    readonly failureCause: FailureCause;
+    constructor(failureCause: FailureCause, message: string);
+}
+/** The structured cause a thrown error carries, or undefined for a plain/agent error. */
+export declare function failureCauseOf(err: unknown): FailureCause | undefined;
+/**
+ * The inactivity-watchdog abort message PREFIX. Human-readable only now — the backend reads the
+ * structured `inactivity-timeout` {@link FailureCause}, not this phrase (the string fallback was
+ * deleted in error-message coverage I5), so it is free to change. The caller appends a `(likely
+ * hung ...)` diagnostic clause (phase + last tool) after this, so the prefix deliberately stops
+ * before the parenthetical (see `runner.ts` drive catch).
+ */
+export declare function inactivityAbortMessage(inactivityMs: number): string;
+/**
+ * The max-duration-watchdog abort message. Human-readable only now — the backend reads the
+ * structured `max-duration` {@link FailureCause}, not this phrase (the string fallback was deleted
+ * in error-message coverage I5), so it is free to change.
+ */
+export declare function maxDurationAbortMessage(maxDurationMs: number): string;

package/dist/follow-ups.d.ts

@@ -0,0 +1,28 @@
+import { type Logger } from './logger.js';
+/** The sentinel file the Coder appends items to, relative to its working directory. */
+export declare const FOLLOW_UPS_FILENAME = ".cat-follow-ups.jsonl";
+/** One streamed item the Coder surfaced. Mirrors the backend's `streamedFollowUpSchema`. */
+export interface FollowUpLine {
+    kind: 'follow_up' | 'question';
+    title: string;
+    detail: string;
+    suggestedAction?: string;
+}
+/**
+ * Tails an append-only JSONL sentinel file, yielding only the NEW complete lines on each
+ * {@link poll}. Tracks how many characters have been consumed so a partially-written
+ * trailing line (no newline yet) is held back until it completes. Tolerant: a malformed
+ * line is skipped, a missing file yields nothing — surfacing follow-ups must never
+ * disturb the coding run.
+ */
+export declare class FollowUpTailer {
+    private readonly filePath;
+    private readonly onItems;
+    private readonly logger;
+    private consumed;
+    /** Running count of complete-but-unparsable lines, so silent drops become visible. */
+    private skipped;
+    constructor(filePath: string, onItems: (items: FollowUpLine[]) => void, logger?: Logger);
+    /** Read any new complete lines and emit the coerced items. Best-effort; never throws. */
+    poll(): Promise<void>;
+}

package/dist/frontend-infra.d.ts

@@ -0,0 +1,25 @@
+import { type ChildProcess } from 'node:child_process';
+import type { FrontendInfraSpec, InfraSetupRecord } from './job.js';
+import type { RunOptions } from './runner.js';
+import { type Logger } from './logger.js';
+export interface FrontendStandUp {
+    /** The processes to terminate on teardown (WireMock + the served app). */
+    processes: ChildProcess[];
+    /** The URL the built app is served at, when it came up. Folded into the agent prompt. */
+    serveUrl?: string;
+    /** A problem note folded into the agent prompt (a failed build / server that never bound). */
+    note?: string;
+    /** The captured (redacted, bounded) stand-up record surfaced on the Tester step. */
+    record: InfraSetupRecord;
+}
+/** The install command for a package manager (an explicit `install` overrides this). */
+export declare function installCommand(spec: FrontendInfraSpec): string[];
+/**
+ * Build the frontend, start WireMock, serve the built app and health-check both. Best-effort,
+ * like the docker-compose stand-up: a failed build / server that never binds is surfaced to
+ * the agent as a prompt note (and captured on the record) rather than failing the job — the
+ * agent then reports the gap as a concern. Every path returns the processes to tear down.
+ */
+export declare function standUpFrontend(dir: string, infra: FrontendInfraSpec, run: Pick<RunOptions, 'signal' | 'onActivity' | 'agentEnv'>, logger?: Logger): Promise<FrontendStandUp>;
+/** Terminate the frontend stand-up's processes (WireMock + the served app). Best-effort. */
+export declare function tearDownFrontend(processes: ChildProcess[], logger?: Logger): Promise<void>;

package/dist/fs-utils.d.ts

@@ -0,0 +1,2 @@
+/** Whether `path` exists (a file or directory), swallowing ENOENT (and any stat error). */
+export declare function pathExists(path: string): Promise<boolean>;

package/dist/git.d.ts

@@ -0,0 +1,394 @@
+import type { BootstrapTargetSpec, RepoSpec } from './job.js';
+export { redactSecrets } from './redact.js';
+export declare const NON_INTERACTIVE_CREDENTIAL_ARGS: string[];
+/**
+ * Whether `err` is a per-command TIMEOUT kill (the child exceeded `execFile`'s `timeout`, so
+ * Node killed it with `killSignal` and set `killed=true`) — as opposed to a normal non-zero
+ * exit or a watchdog/caller abort. `aborted` is the caller signal's state: an abort ALSO
+ * kills the child, but it's the outer watchdog's story (recorded via `killReason` upstream),
+ * so it must NOT be reported here as a git timeout. Pure, so the classification is unit-tested.
+ */
+export declare function isGitTimeoutKill(err: unknown, aborted: boolean): boolean;
+/**
+ * Classify the common shapes of git's own stderr into an actionable remedy, else undefined
+ * (an unrecognized failure keeps just its raw stderr). This is the FIRST-WRAP-POINT for
+ * unavoidable third-party text (per the error-message initiative's I6): git's stderr is the
+ * only signal we get for a clone/push auth or access fault, so we match it ONCE here and
+ * APPEND a cause + fix, never rewrite the raw line. Host-neutral — the same remedy serves a
+ * GitHub-App installation token and a GitLab/GitHub PAT (local mode). Pure, so it is
+ * unit-tested over a fixed set of stderr strings.
+ */
+export declare function describeGitFailure(stderr: string): string | undefined;
+/**
+ * Build the remote URL git uses. Only the username (`x-access-token`) is embedded
+ * — never the token — so the token never appears in argv. The token is supplied
+ * separately via {@link authEnv} and read by the GIT_ASKPASS helper.
+ *
+ * The `x-access-token` username is host-neutral: GitHub keys auth off the token (password)
+ * and ignores the username, and GitLab likewise accepts ANY non-blank username with a PAT as
+ * the password — so the same embedded username authenticates github.com and gitlab.com alike.
+ */
+export declare function authenticatedCloneUrl(cloneUrl: string): string;
+/** Clone `repo`'s base branch (shallow by default) into `dir` and set commit identity. */
+export declare function cloneRepo(opts: {
+    repo: RepoSpec;
+    ghToken: string;
+    dir: string;
+    signal?: AbortSignal;
+    /**
+     * Full history + all remote-tracking branches. A shallow single-branch clone is
+     * enough to implement on one branch, but merging ANOTHER branch in (the
+     * conflict-resolver) needs the merge base in history and `origin/<other>` present
+     * — so `full` drops both `--depth 1` (which implies `--single-branch`).
+     */
+    full?: boolean;
+}): Promise<void>;
+/** Create and switch to the work branch. */
+export declare function createBranch(dir: string, branch: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Whether `branch` already exists on the remote — i.e. an earlier (possibly
+ * evicted) run of this task already pushed work to it, so a re-dispatch should
+ * RESUME on it (clone it, continue on its commits) rather than branch off base and
+ * start over. Uses `git ls-remote` (no checkout); the token is supplied out of band.
+ */
+export declare function remoteBranchExists(cloneUrl: string, branch: string, ghToken: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Clone an EXISTING work branch (full history) into `dir` and check it out — used
+ * to resume a task whose earlier run already pushed commits to this branch, so the
+ * agent continues on top of that work instead of redoing it.
+ */
+export declare function cloneExistingBranch(opts: {
+    cloneUrl: string;
+    branch: string;
+    ghToken: string;
+    dir: string;
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * The directory-name globs the clean sweep PRESERVES — dependency caches that are
+ * expensive to rebuild (node_modules, language toolchain caches). Keeping them is the
+ * whole point of reusing a checkout: a `git clean -ffdx` would otherwise wipe them and
+ * force a reinstall every run. Configurable via `HARNESS_CLEAN_KEEP` (comma-separated).
+ */
+export declare function cleanKeepPatterns(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Reset a REUSED checkout to a pristine state before the next job runs in it: hard-reset
+ * tracked files and remove every untracked/ignored file EXCEPT the preserved dependency
+ * caches (see {@link cleanKeepPatterns}). This is what guarantees a prior run's garbage —
+ * stray scratch files, half-written edits, stale build output — never contaminates the
+ * next run that reuses the same persistent checkout. A fresh clone never needs it.
+ *
+ * Submodules: when `.gitmodules` is present we use a single `-f` (which makes `git clean`
+ * skip nested git repositories, i.e. the submodule worktrees) and reset/refresh the
+ * submodules explicitly; otherwise `-ff` also nukes any stray nested repo the agent left.
+ */
+export declare function cleanSweep(dir: string, ghToken: string, signal?: AbortSignal, env?: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * The `origin` remote URL (without credentials) of the checkout at `dir`, or undefined
+ * when it isn't a git repo / has no origin. Used to detect a persistent checkout dir that
+ * somehow holds a DIFFERENT repo than the one we're about to prepare (it never should —
+ * the dir is keyed per repo — but a stale dir from a prior layout would be a silent
+ * cross-repo bleed, so we re-clone rather than reuse).
+ */
+export declare function checkoutRemoteUrl(dir: string, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * Prepare a REUSED (persistent) checkout at `dir` so the agent runs against a clean tree
+ * on the right branch — the persistent-checkout analogue of {@link cloneRepo} +
+ * {@link cloneExistingBranch}. On the FIRST use of a per-repo dir there's no `.git` yet, so
+ * it clones once (full history, so a later merger/conflict step reusing the dir can diff
+ * against the base); afterwards it reuses the dir in place: clean sweep → re-point origin →
+ * fetch → check out `branch`. When `existing` is true `branch` is fetched and checked out
+ * directly (resume / base branch); otherwise `branch` is (re)created off `baseBranch`'s tip
+ * (a fresh work branch). Only the local transport sets `persistentCheckout`, so every other
+ * runtime keeps the fresh-clone path untouched.
+ */
+export declare function prepareExistingCheckout(opts: {
+    dir: string;
+    repo: RepoSpec;
+    ghToken: string;
+    /** The branch to end up checked out on. */
+    branch: string;
+    /** Base branch to (re)create `branch` off when `existing` is false; also fetched for history. */
+    baseBranch: string;
+    /** Whether `branch` already exists on the remote (resume / base) — checkout it directly. */
+    existing: boolean;
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * Commit edits the agent left UNCOMMITTED — but only to files git already tracks
+ * (`git add -u`), never new untracked files. The agent owns commit selection (it
+ * alone knows which new files are part of the solution vs scratch scripts/artifacts
+ * it created while exploring), so this is just a safety net that captures forgotten
+ * edits to existing files without ever sweeping in junk a blanket `git add -A`
+ * would. Returns false when there was nothing tracked to commit.
+ */
+export declare function commitTrackedEdits(dir: string, message: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * The untracked, non-ignored files left in the working tree (`git ls-files --others
+ * --exclude-standard`). The harness deliberately never blanket-stages new files (the
+ * agent owns commit selection), so this is exactly what {@link commitTrackedEdits}
+ * does NOT capture — a NEW file the agent created but forgot to commit. The caller
+ * surfaces it as a warning so that silent loss is at least observable in the logs.
+ */
+export declare function listUntrackedFiles(dir: string, signal?: AbortSignal): Promise<string[]>;
+/**
+ * The untracked, non-ignored paths in the working tree with whole untracked DIRECTORIES
+ * collapsed to a single `dir/` entry (`--directory`), rather than every file beneath them.
+ *
+ * The sibling {@link listUntrackedFiles} answers "what did the agent forget to commit", where
+ * every individual file is the point. This one answers "what appeared in the tree", where it is
+ * emphatically not: a dependency install leaves tens of thousands of files under one directory,
+ * and enumerating them would cost a multi-megabyte listing to learn a single name.
+ */
+export declare function listUntrackedPaths(dir: string, signal?: AbortSignal): Promise<string[]>;
+/**
+ * Locally exclude `pattern` from this checkout via `.git/info/exclude` — a per-clone
+ * ignore that never lands in the repo (unlike a `.gitignore`). Used for the harness's
+ * follow-up sentinel file so the agent's own `git add` can never stage it and it never
+ * surfaces as an untracked-leftover warning or in the PR. Best-effort: a failure here
+ * just means the sentinel might show as untracked (logged, not pushed), never fatal.
+ */
+export declare function excludeFromGit(dir: string, pattern: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Locally exclude LITERAL paths — never patterns — from this checkout, in ONE write.
+ *
+ * The sibling {@link excludeFromGit} takes an author-written pattern for a known sentinel. These
+ * paths instead come from the FILESYSTEM (what a dependency install left behind), so two things
+ * differ. Each is escaped, because a directory named `pkg[1]` read as a gitignore character class
+ * excludes something else entirely and, being a no-op on the real path, fails silently. And they
+ * are appended together, because a per-path append would cost one file write per entry to build
+ * a list that is already known in full.
+ *
+ * Anchored: `ls-files` reports repo-root-relative paths and a gitignore pattern containing a
+ * slash is root-anchored, which is what makes `packages/api/node_modules/` exclude that service's
+ * tree and not a same-named directory elsewhere. Best-effort, exactly like its sibling.
+ */
+export declare function excludePathsFromGit(dir: string, paths: readonly string[], signal?: AbortSignal): Promise<void>;
+/** Whether the branch advanced past `baseSha` via commits (the agent's own + any safety-net commit). */
+export declare function branchHasCommitsSince(dir: string, baseSha: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Whether the checked-out branch carries at least one commit the PR base does NOT — i.e.
+ * `git rev-list --count <base>..HEAD > 0`. A resume clone is single-branch, so it has no
+ * `origin/<base>` tracking ref; this fetches the base into a dedicated local ref first and
+ * diffs HEAD against it.
+ *
+ * Tri-state on purpose:
+ *  - `true`  — confirmed ≥1 commit ahead (there is something to open a PR for).
+ *  - `false` — confirmed 0 commits ahead (the branch is reachable from base, e.g. its earlier
+ *              PR was merged with a merge commit and the best-effort branch delete was skipped).
+ *  - `undefined` — could not determine (fetch / rev-list error); the caller keeps its prior
+ *              behaviour rather than wrongly dropping a resumed branch that has real work.
+ *
+ * Used by the resume path to avoid declaring a merged/empty branch as work and then failing
+ * the run with GitHub's opaque 422 "No commits between <base> and <branch>".
+ */
+export declare function branchAheadOfBase(dir: string, baseBranch: string, ghToken: string, signal?: AbortSignal): Promise<boolean | undefined>;
+/**
+ * The files `commitish` changes relative to its merge base with the PR base branch — i.e.
+ * everything the work branch has added on top of base, `git diff --name-only <base>...<commitish>`.
+ *
+ * The BUGFIX REPRODUCTION PROOF uses this to answer the one question that decides whether a GREEN
+ * pre-fix tree means anything: does that tree ALREADY carry non-test work committed on this
+ * branch? A resumed run's `baseSha` is whatever the branch tip was when this pass started, which
+ * in the designed flow is the reproduction step's test commit — but after an eviction it is this
+ * same coder step's own interrupted work, fix included. Reporting "the check passed before your
+ * change, so it does not demonstrate the defect" in that case is simply false.
+ *
+ * `undefined` means "could not determine" (a shallow clone with no reachable merge base, a fetch
+ * failure, an unknown ref), never an empty list: the caller must degrade to its prior behaviour
+ * rather than read a failed probe as "the tree is clean".
+ *
+ * NUL-delimited so a path containing a newline (legal in git) cannot split into two entries.
+ */
+export declare function changedFilesSinceBase(dir: string, baseBranch: string, ghToken: string, commitish: string, signal?: AbortSignal): Promise<string[] | undefined>;
+/**
+ * Whether the checked-out branch has a real, examinable diff against
+ * `origin/<baseBranch>` — i.e. the base branch's remote-tracking ref exists (so the
+ * merge base resolves) AND there are changes between that merge base and HEAD. The
+ * merger uses this to refuse to score a PR it could not actually inspect (a missing
+ * base ref or an empty diff) instead of emitting bogus low scores that would
+ * auto-merge. Returns false on ANY git error (e.g. an unknown ref). Requires a
+ * {@link cloneRepo} with `full: true` so `origin/<baseBranch>` and the merge base exist.
+ */
+export declare function hasDiffAgainstBase(dir: string, baseBranch: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Parse the paths out of `git status --porcelain` (v1) output. Each line is
+ * `XY <path>`, or `XY <old> -> <new>` for a rename/copy (we keep the new path);
+ * git quotes paths with special characters, which we unquote. Blank lines are
+ * skipped. Pure so the no-op detection can be tested without spawning git.
+ */
+export declare function changedPathsFromPorcelain(status: string): string[];
+/**
+ * Whether the agent changed anything in a cloned checkout. Stages the working
+ * tree and inspects the porcelain status: an empty result means the bootstrapper
+ * made no adaptation — a no-op we must not pass off as a successful push. (The
+ * harness writes its prompt context to Pi's global `~/.pi/agent/AGENTS.md`, never
+ * into the checkout, so every change reported here is a genuine agent edit.)
+ */
+export declare function hasAgentChanges(dir: string, signal?: AbortSignal): Promise<boolean>;
+/** The commit SHA at `dir`'s HEAD — captured right after clone as the base tip. */
+export declare function headCommit(dir: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Add a DETACHED worktree of `commitish` at `worktreePath`, sharing `dir`'s object database.
+ *
+ * The bugfix reproduction proof runs the declared check against two trees of the SAME clone (the
+ * pre-fix tree and the final tree), so a worktree is the only mechanism that gets both without a
+ * second clone, a second fetch, or disturbing the agent's own checkout — which must stay exactly
+ * as the agent left it, since the push and the PR come off it.
+ *
+ * `--detach` (rather than a branch) is deliberate: a worktree that claimed a branch would collide
+ * with the work branch checked out in `dir`, and nothing here ever commits.
+ *
+ * `worktreePath` is expected to live OUTSIDE the checkout (a per-job temp root), so the worktree's
+ * `.git` pointer file can never be swept into the agent's commit by a broad `git add -A`.
+ */
+export declare function addWorktree(dir: string, worktreePath: string, commitish: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Remove a worktree previously added by {@link addWorktree} and prune the stale administrative
+ * entry, never throwing: teardown is bookkeeping, and a run whose PROOF succeeded must not fail
+ * because a temp directory could not be cleaned up. The caller still deletes the temp root, so a
+ * failure here leaks only a `.git/worktrees/<name>` record inside a container that is about to be
+ * destroyed anyway.
+ */
+export declare function removeWorktree(dir: string, worktreePath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Which of `paths` actually exist in `commitish`'s tree. Used by the reproduction proof to tell a
+ * DECLARED test file that was committed from one that only ever existed as an untracked working-
+ * tree file: the proof runs against committed trees, so an unadded test is invisible to it — and
+ * equally invisible to the push, which is the point worth telling the agent about rather than
+ * reporting a verdict computed without the reproduction in it.
+ *
+ * Returns the input order/spelling of the paths that matched, so the caller can diff against its
+ * declared list to name the missing ones verbatim.
+ */
+export declare function pathsPresentAtCommit(dir: string, commitish: string, paths: readonly string[], signal?: AbortSignal): Promise<string[]>;
+/**
+ * Check `paths` out of `commitish` into `dir`'s working tree (and index), leaving every other file
+ * untouched.
+ *
+ * This is how the reproduction's declared TEST files are placed onto the pre-fix worktree, and the
+ * narrowness is the whole safety property: a whole-tree checkout would drag the FIX across too and
+ * green the base, manufacturing a "the test does not capture the defect" verdict out of a
+ * perfectly good reproduction. Only the paths the caller has already sanitized are passed, and
+ * `--` stops any of them being read as a revision.
+ */
+export declare function checkoutPathsFrom(dir: string, commitish: string, paths: readonly string[], signal?: AbortSignal): Promise<void>;
+/** Stage everything and commit; returns false when there was nothing to commit. */
+export declare function commitAll(dir: string, message: string, signal?: AbortSignal): Promise<boolean>;
+/** Paths git still reports as unmerged (conflict stage entries) in the working tree. */
+export declare function unmergedPaths(dir: string, signal?: AbortSignal): Promise<string[]>;
+/**
+ * The conflict hunks for the given unmerged `paths`: `git diff` over exactly those
+ * files, which for an unmerged entry renders the combined diff carrying the
+ * `<<<<<<<` / `=======` / `>>>>>>>` markers each side contributed. Handed to the
+ * conflict-resolver agent so it sees the actual conflicts instead of having to
+ * rediscover them. Capped to `maxChars` total (a note is appended on truncation) so a
+ * huge conflict can't blow up the prompt. Returns '' when there are no paths.
+ */
+export declare function conflictDiff(dir: string, paths: string[], signal?: AbortSignal, maxChars?: number): Promise<string>;
+/**
+ * Merge `origin/<baseBranch>` into the current branch (no fast-forward squash, no
+ * editor). Returns `true` for a clean merge (or an already-up-to-date no-op) and
+ * `false` when the merge left conflicts in the working tree — the expected case the
+ * conflict-resolver agent then fixes, NOT an error. Any other git failure (e.g. an
+ * unknown ref) is re-thrown. Requires a {@link cloneRepo} with `full: true` so the
+ * merge base and `origin/<baseBranch>` are present.
+ */
+export declare function mergeBranch(dir: string, baseBranch: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Bring a RESUMED work branch up to the latest `baseBranch` when (and only when) the
+ * two merge cleanly. A resumed branch was cut from an older base, so without this the
+ * agent continues against a stale base and the eventual PR can carry avoidable
+ * conflicts. Fetches the base (the single-branch resume clone doesn't have it),
+ * attempts `git merge --no-edit`, and on a conflict ABORTS — leaving the branch
+ * exactly as it was so the run proceeds on the stale base (the CI/merge gate handles
+ * a genuinely conflicting PR downstream, as before). Returns whether base was merged
+ * in. Best-effort: callers treat a thrown/false result as "continue without refresh".
+ */
+export declare function refreshFromBaseIfClean(dir: string, baseBranch: string, ghToken: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * The directory the reference-branches prompt section suggests for a `git worktree add` checkout of
+ * a reference branch alongside the agent's own work. Excluded from the checkout (below) so the
+ * embedded worktree can never be staged into the agent's PR — mirrors the `.cat-context/` treatment
+ * in {@link file://./pi.ts}. Kept in step with the same literal in the backend's
+ * `renderReferenceBranchesSection` (a separate package, so a shared constant isn't feasible).
+ */
+export declare const REFERENCE_WORKTREE_DIR = ".cat-reference";
+/**
+ * Fetch pre-existing REFERENCE branches into their `origin/<b>` tracking refs, so the agent can
+ * inspect them read-only (`git log origin/<b>`, two-dot `git diff origin/<b>`,
+ * `git show origin/<b>:<path>`) without any git network credentials of its own. The primary
+ * checkout is a shallow single-branch clone, so these refs aren't present until fetched — and the
+ * harness (which holds the per-job token) is the only place that can reach the remote. Uses an
+ * explicit destination refspec (`+refs/heads/<b>:refs/remotes/origin/<b>`) and `--no-tags` so a
+ * reference branch's tags don't pollute the checkout. Best-effort PER branch: a fetch failure (a
+ * branch deleted since dispatch, a transient network error) is reported via `onSkip` and skipped,
+ * never fatal — a reference branch is context, not the run's starting point (contrast the WORKING
+ * branch, whose absence fails the dispatch loudly). Returns the branch names that fetched cleanly.
+ *
+ * On any successful fetch it locally excludes {@link REFERENCE_WORKTREE_DIR} from this checkout, so
+ * if the agent follows the prompt's suggested `git worktree add .cat-reference/<b>` a broad
+ * `git add -A` can never embed that worktree as a stray gitlink in the run's PR.
+ */
+export declare function fetchReferenceBranches(opts: {
+    dir: string;
+    branches: string[];
+    ghToken: string;
+    signal?: AbortSignal;
+    /** Called once per branch that failed to fetch, so the caller (which owns a logger) can warn. */
+    onSkip?: (branch: string, reason: string) => void;
+}): Promise<string[]>;
+/** The local tracking ref a fetched PR/MR head lands on, so the reviewer reads `origin/pr-head`. */
+export declare const PR_HEAD_REF = "refs/remotes/origin/pr-head";
+/**
+ * The `git fetch` refspec that maps a PR/MR's server-side HEAD ref onto {@link PR_HEAD_REF}. A
+ * PR head is a synthetic ref the host maintains, NOT part of a normal clone: GitHub exposes it at
+ * `refs/pull/<n>/head`, GitLab at `refs/merge-requests/<n>/head`. Pure so the provider branch is
+ * unit-tested without a network. The leading `+` forces the update (the ref is read-only here).
+ */
+export declare function pullHeadRefspec(number: number, provider: 'github' | 'gitlab'): string;
+/**
+ * Fetch the reviewed PR/MR's HEAD into {@link PR_HEAD_REF} so a read-only reviewer can inspect the
+ * PROPOSED code — files the PR adds (absent from the base checkout) and the head version of every
+ * modified file — with `git diff origin/<base>...origin/pr-head`, `git show origin/pr-head:<path>`.
+ * The base clone never includes the pull ref, and the container agent holds no git credential of
+ * its own (the token lives with the harness), so the agent's own `git fetch pull/<n>/head` fails
+ * on a private repo — this harness-side fetch (which carries the token out of band via GIT_ASKPASS,
+ * exactly like {@link fetchReferenceBranches}) is what actually makes the head reachable.
+ *
+ * Best-effort: a fetch failure (a closed/deleted PR, a host without the pull ref, a transient
+ * network error) is reported via `onSkip` and swallowed — the review then proceeds on the base
+ * checkout + the injected diff, never fails. Returns whether the head was fetched.
+ */
+export declare function fetchPullRequestHead(opts: {
+    dir: string;
+    number: number;
+    provider: 'github' | 'gitlab';
+    ghToken: string;
+    signal?: AbortSignal;
+    /** Called when the fetch failed, so the caller (which owns a logger) can warn. */
+    onSkip?: (reason: string) => void;
+}): Promise<boolean>;
+/**
+ * Push the work branch to origin. The remote URL carries only the username, so
+ * the token is supplied here via the askpass env (never in argv).
+ */
+export declare function pushBranch(dir: string, branch: string, ghToken: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Reset the working tree's git history to a single bootstrap commit and push it
+ * to the target repository's default branch. Wiping `.git` before re-initialising
+ * means the new repo starts clean — it inherits the bootstrapped *contents* of the
+ * reference architecture, not its commit history.
+ *
+ * The push is forced: the fresh single-commit history shares no ancestor with
+ * whatever GitHub prepopulated when the user created the repo (a README,
+ * .gitignore and/or license picked on the new-repo page), so a fast-forward is
+ * impossible. The Worker pre-flights that the target is empty or holds only that
+ * boilerplate, so overwriting it is safe and intended.
+ */
+export declare function reinitAndPush(opts: {
+    dir: string;
+    target: BootstrapTargetSpec;
+    ghToken: string;
+    message: string;
+}): Promise<void>;

package/dist/host-markdown.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function walkFences(lines: readonly string[], visit: (line: string, insideFence: boolean) => void): {
+    char: string;
+    length: number;
+} | null;
+/**
+ * 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 declare function inertMarkdown(text: string): string;
+/**
+ * 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 declare function inertInline(text: string): string;

package/dist/inline.d.ts

@@ -0,0 +1,10 @@
+import type { InlineJob, InlineResult } from './job.js';
+import type { RunOptions } from './runner.js';
+/**
+ * Run one inline completion in a throwaway temp cwd and return the reply text + lifted
+ * usage/telemetry. The CLI clones/pushes nothing — the empty cwd only gives it a working
+ * directory. The job's watchdog (inactivity + max-duration, see {@link JobRegistry}) bounds
+ * it through `opts.signal`; `opts.onActivity` keeps the inactivity timer alive while the CLI
+ * streams. The temp cwd is always removed.
+ */
+export declare function handleInline(job: InlineJob, opts: RunOptions): Promise<InlineResult>;