@cat-factory/executor-harness 1.80.0 → 1.84.0

package/dist/coding-agent.js

@@ -42,6 +42,64 @@ function followUpPollIntervalMs() {
  * retry resumes on them. Returns the run's summary/stats, whether it pushed, and
  * whether it resumed; callers decide what to do after a push (open a PR, or nothing).
  */
+/**
+ * The work-branch push machinery for one coding run: a single coalesced push plus the periodic
+ * checkpoint that keeps mid-run commits durable. Split out of {@link runCodingAgent} for the
+ * per-function line budget; the caller owns the interval's lifetime (it clears `checkpoint`).
+ *
+ * Serialize all pushes to the work branch through a single in-flight promise. A checkpoint tick
+ * and the final push (or two slow checkpoint ticks) must never run `git push` to the same branch
+ * concurrently: overlapping pushes race on the remote ref and can make a push fail with a
+ * ref-lock / non-fast-forward error — which, on the FINAL push, would fail the whole run even
+ * though the work is committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
+ * pushes once the branch has advanced past `baseSha`.
+ *
+ * Only push once the branch has advanced past its pre-run tip: pushing while it still sits at
+ * `baseSha` would create the work branch at the base commit (a zero-diff branch), which a later
+ * retry would see via `remoteBranchExists` and treat as resumable work — then fail to open a PR
+ * ("no commits between base and head"). So a run that never commits leaves NO branch behind,
+ * preserving the clean no-op outcome.
+ */
+function createWorkBranchPusher(args) {
+    const { dir, spec, baseSha, logger, signal } = args;
+    let pushInFlight = null;
+    const pushWorkOnce = () => {
+        if (pushInFlight)
+            return pushInFlight;
+        pushInFlight = (async () => {
+            if (!(await branchHasCommitsSince(dir, baseSha, signal)))
+                return;
+            await pushBranch(dir, spec.pushBranch, spec.ghToken, signal);
+        })().finally(() => {
+            pushInFlight = null;
+        });
+        return pushInFlight;
+    };
+    // Read the in-flight push, if any. A function (with an explicit return type) so the
+    // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
+    // only ever assigned inside closures, which flow analysis can't observe.
+    const inFlightPush = () => pushInFlight;
+    // Checkpoint the agent's committed work to the branch periodically so an eviction
+    // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
+    // agent commits its own work; this only PUSHES already-committed commits, so it
+    // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
+    // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
+    // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
+    // being durably checkpointed, so an eviction would lose it — previously invisible at
+    // info level. Still best-effort: a failed checkpoint never fails the run.
+    let checkpointFailures = 0;
+    const checkpoint = setInterval(() => {
+        pushWorkOnce().catch((err) => {
+            checkpointFailures++;
+            logger.warn('coding-agent: checkpoint push failed', {
+                reason: err instanceof Error ? err.message : String(err),
+                checkpointFailures,
+            });
+        });
+    }, checkpointIntervalMs());
+    checkpoint.unref?.();
+    return { pushWorkOnce, inFlightPush, checkpoint };
+}
 export async function runCodingAgent(spec, opts = {}) {
     const { signal } = opts;
     // The registry already binds jobId/repo/branch; add the coding kind + the push branch
@@ -51,56 +109,17 @@ export async function runCodingAgent(spec, opts = {}) {
         // Clone (or resume) the checkout, fetch any read-only reference branches, and capture the
         // pre-run branch tip. See {@link prepareCodingCheckout} for the resume-safety invariants.
         const { resumed, baseSha } = await prepareCodingCheckout(dir, spec, logger, opts);
-        // Serialize all pushes to the work branch through a single in-flight promise.
-        // A checkpoint tick and the final push (or two slow checkpoint ticks) must never
-        // run `git push` to the same branch concurrently: overlapping pushes race on the
-        // remote ref and can make a push fail with a ref-lock / non-fast-forward error —
-        // which, on the FINAL push, would fail the whole run even though the work is
-        // committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
-        // pushes once the branch has advanced past `baseSha` (see below).
-        //
-        // Only push once the branch has advanced past its pre-run tip: pushing while it
-        // still sits at `baseSha` would create the work branch at the base commit (a
-        // zero-diff branch), which a later retry would see via `remoteBranchExists` and
-        // treat as resumable work — then fail to open a PR ("no commits between base and
-        // head"). So a run that never commits leaves NO branch behind, preserving the
-        // clean no-op outcome.
-        let pushInFlight = null;
-        const pushWorkOnce = () => {
-            if (pushInFlight)
-                return pushInFlight;
-            pushInFlight = (async () => {
-                if (!(await branchHasCommitsSince(dir, baseSha, signal)))
-                    return;
-                await pushBranch(dir, spec.pushBranch, spec.ghToken, signal);
-            })().finally(() => {
-                pushInFlight = null;
-            });
-            return pushInFlight;
-        };
-        // Read the in-flight push, if any. A function (with an explicit return type) so the
-        // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
-        // only ever assigned inside closures, which flow analysis can't observe.
-        const inFlightPush = () => pushInFlight;
-        // Checkpoint the agent's committed work to the branch periodically so an eviction
-        // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
-        // agent commits its own work; this only PUSHES already-committed commits, so it
-        // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
-        // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
-        // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
-        // being durably checkpointed, so an eviction would lose it — previously invisible at
-        // info level. Still best-effort: a failed checkpoint never fails the run.
-        let checkpointFailures = 0;
-        const checkpoint = setInterval(() => {
-            pushWorkOnce().catch((err) => {
-                checkpointFailures++;
-                logger.warn('coding-agent: checkpoint push failed', {
-                    reason: err instanceof Error ? err.message : String(err),
-                    checkpointFailures,
-                });
-            });
-        }, checkpointIntervalMs());
-        checkpoint.unref?.();
+        // The work-branch push machinery: one coalesced in-flight push plus the periodic
+        // checkpoint that keeps mid-run commits durable across an eviction. Lifted into
+        // {@link createWorkBranchPusher} so this callback stays within the per-function line budget;
+        // the invariants it upholds are documented there.
+        const { pushWorkOnce, inFlightPush, checkpoint } = createWorkBranchPusher({
+            dir,
+            spec,
+            baseSha,
+            logger,
+            signal,
+        });
         // In a monorepo the service lives in a subdirectory: run Pi with its cwd set to
         // that subtree (git stays rooted at `dir` so commits/pushes still cover the whole
         // checkout). Created if missing so a coder scaffolding a brand-new service into an

package/dist/dependency-install.d.ts

@@ -0,0 +1,111 @@
+import { type RunOptions } from './runner.js';
+import type { Logger } from './logger.js';
+/** The dependency-install phase as it arrives on the job body. */
+export interface DependencyInstallSpec {
+    /** The shell command, run as `sh -c` in the checkout (the service directory for a monorepo). */
+    command: string;
+}
+/** What the install did — folded into the agent's prompt, never a verdict about the run. */
+export interface DependencyInstallOutcome {
+    command: string;
+    exitCode: number;
+    passed: boolean;
+    /** Scrubbed, bounded tail of the combined output. Only kept for a FAILED install. */
+    outputTail?: string;
+    durationMs: number;
+    timedOut?: boolean;
+}
+/**
+ * How much of a failed install's output the agent is shown. Smaller than the validation loop's
+ * repair budget (16k) on purpose: a repair prompt has to carry the whole failure because fixing
+ * it IS the task, whereas this note only has to let the agent decide whether to install
+ * something itself. The tail is where a package manager puts its actual error.
+ */
+export declare const DEPENDENCY_INSTALL_TAIL_CHARS = 4000;
+/**
+ * The per-install watchdog: the longest the install may run before it is killed and reported as
+ * failed. Generous (20 min at the defaults) because a cold monorepo install on a slow registry
+ * legitimately takes many minutes.
+ *
+ * DERIVED from the configured job ceiling rather than hardcoded against the default one, the same
+ * way `git.ts` derives its per-command timeout from the configured inactivity window: a constant
+ * sized against a default silently breaks its own invariant the moment an operator changes that
+ * default. An explicit `DEPENDENCY_INSTALL_TIMEOUT_MS` is honoured but still CLAMPED — the point
+ * of the share is that no configuration lets setup eat the run, and an override that could exceed
+ * the job's own ceiling would only ever be killed later by a watchdog that fails the whole job
+ * instead of degrading to a note.
+ */
+export declare function dependencyInstallTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * How often the install feeds the run's inactivity watchdog. Well under `JOB_INACTIVITY_MS`
+ * (default 10 min); matches the validation loop's and the frontend stand-up's heartbeat, which
+ * exist for exactly the same reason.
+ */
+export declare function dependencyInstallHeartbeatMs(): number;
+/**
+ * Parse the optional DEPENDENCY INSTALL envelope off the job body. A missing/blank command
+ * returns `undefined`, so a malformed body degrades to the exact pre-feature behaviour (no
+ * install phase, the agent starts against the bare clone) rather than failing a good run.
+ *
+ * Lives with the feature rather than in `job.ts`, following the same rule the two pre-PR
+ * verification phases do: each phase owns its own job-body parser next to the code that consumes
+ * it, and `job.ts` stays the job SHAPE plus the generic assembly.
+ */
+export declare function parseDependencyInstallSpec(value: unknown): DependencyInstallSpec | undefined;
+/**
+ * Run the declared install against `cwd` and return what happened. Never throws and never fails
+ * the job: every failure shape ({@link runCapturedCommand} maps a timeout to 124, a spawn error
+ * to 127, an abort to 130) comes back as a non-zero outcome the caller turns into a prompt note.
+ *
+ * The output tail is kept ONLY for a failure. A successful install prints tens of thousands of
+ * uninteresting lines, and the agent needs to know that it succeeded, not what it resolved.
+ */
+export declare function runDependencyInstall(args: {
+    cwd: string;
+    spec: DependencyInstallSpec;
+    logger: Logger;
+    opts: RunOptions;
+}): Promise<DependencyInstallOutcome>;
+/**
+ * THE entry point: run the phase for a mode that has a checkout, and hand back the note to fold
+ * into the agent's prompt (or `undefined` when the service declared no install, which is every
+ * dispatch today that never configured one).
+ *
+ * Everything a caller could get wrong lives here rather than at six call sites: the phase marker,
+ * the best-effort run, keeping the installed tree out of the agent's commits, and naming WHERE
+ * the install ran when that is not where the agent will be standing. A mode supplies only its
+ * three directories.
+ */
+export declare function prepopulateDependencies(args: {
+    spec: DependencyInstallSpec | undefined;
+    /** Where the install runs: the service subtree for a monorepo, else the checkout root. */
+    installDir: string;
+    /** The git checkout whose local excludes protect the agent's commits from the installed tree. */
+    repoDir: string;
+    /** The agent's own working directory, which names the install location when the two differ. */
+    agentDir: string;
+    logger: Logger;
+    opts: RunOptions;
+}): Promise<string | undefined>;
+/**
+ * Fold the note into a prompt. Trivial, and deliberately not inlined: it is applied on EVERY
+ * agent pass — including the validation and reproduction REPAIR passes, which start a fresh
+ * agent that would otherwise never learn the tree is already installed and would spend a repair
+ * round reinstalling it.
+ */
+export declare function withDependencyNote(userPrompt: string, note: string | undefined): string;
+/**
+ * The note folded into the agent's prompt describing the checkout it is about to work in.
+ *
+ * Stated in BOTH directions on purpose. On success the agent is told the tree is ready, which is
+ * what stops it spending turns re-running an install that already ran (and, on a repo whose
+ * install is slow, spending most of its budget there). On failure it is told plainly what failed
+ * and that it may install what it needs itself — an agent that merely finds no `node_modules` and
+ * no explanation concludes the environment is offline and works around a gap that isn't there.
+ *
+ * `scope` names the checkout the install ran in and is set ONLY when that is not the agent's own
+ * working directory — the multi-repo layout runs the agent at the workspace root while the install
+ * belongs to the primary service's sibling directory. Saying "this checkout" there would point the
+ * agent at a root that has no dependency tree of its own.
+ */
+export declare function buildDependencyInstallNote(outcome: DependencyInstallOutcome, scope?: string): string;

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>;