@cat-factory/executor-harness 1.80.0 → 1.82.0

package/dist/claude-call-aggregator.js

@@ -77,6 +77,112 @@ export function createClaudeCallAggregator(handlers) {
         flush: complete,
     };
 }
+/**
+ * How much reconstructed transcript ONE conversation may retain.
+ *
+ * The stream feeds this without limit — a tool loop that reads large files grows the history by
+ * every one of them — and the reconstruction is held in the driver's own process. In the container
+ * that is a box sized for one job; in the BACKEND it is the orchestrator, where `streamCli` already
+ * refuses to retain the raw stream for exactly this reason (`harnessInline.ts` →
+ * `OUTPUT_TAIL_RETAIN_CHARS`: "a stalled tool-using run would otherwise park hundreds of MB in the
+ * orchestrator process — precisely on the runs worth diagnosing").
+ *
+ * 512 KiB because that is `LlmObservabilityService.MAX_BODY_CHARS`, the point past which the store
+ * truncates a body anyway: retaining more can only ever be thrown away. Deliberately NOT a
+ * per-deployment knob — it bounds a memory fault, and a number an operator can raise is one an
+ * operator can raise until the process dies.
+ */
+export const MAX_TRANSCRIPT_CHARS = 512 * 1024;
+/**
+ * The role a turn carries when it is not a turn at all, but the note saying what stopped being
+ * retained. A distinct namespaced role rather than `system`, so nothing downstream can read it as a
+ * message that was actually sent — the same reason `seed` exists.
+ */
+const ELIDED_ROLE = 'cat-factory:elided';
+/**
+ * Retain the transcript up to {@link MAX_TRANSCRIPT_CHARS} and then STOP, stating what it stopped
+ * retaining rather than silently ending mid-conversation.
+ *
+ * Freezing the tail (rather than evicting the head) keeps the seed and the early history — the
+ * task, and the turns that explain what the loop is doing — and keeps each call's `promptText` a
+ * stable PREFIX plus a changing note, so the backend's chain delta-compresses right up to the bound
+ * and only then degrades to storing the (now capped) array. Evicting the head would drop the task
+ * itself and break the prefix property from the first eviction on.
+ *
+ * The seed is never dropped: it is what the CALLER sent, so it is bounded by the caller's own
+ * prompt rather than by the stream, and it is the half a reader cannot reconstruct from anything
+ * else.
+ */
+function createBoundedTranscript(seed, secrets, maxChars) {
+    const turns = [...seed];
+    const sizeOf = (turn) => {
+        try {
+            return JSON.stringify(turn)?.length ?? 0;
+        }
+        catch {
+            // An un-serialisable turn cannot be retained at all, so charge it nothing and let the
+            // append below drop it on its own terms.
+            return Number.POSITIVE_INFINITY;
+        }
+    };
+    let retained = turns.reduce((n, turn) => n + sizeOf(turn), 0);
+    const dropped = { turns: 0, chars: 0 };
+    return {
+        append(turn) {
+            const size = sizeOf(turn);
+            if (retained + size > maxChars) {
+                dropped.turns += 1;
+                dropped.chars += Number.isFinite(size) ? size : 0;
+                return;
+            }
+            turns.push(turn);
+            retained += size;
+        },
+        snapshot() {
+            const encoded = dropped.turns
+                ? [
+                    ...turns,
+                    {
+                        role: ELIDED_ROLE,
+                        content: `${dropped.turns} later turn(s), ${dropped.chars} chars, were not retained: ` +
+                            `this conversation reached the ${maxChars}-char reconstruction bound`,
+                    },
+                ]
+                : turns;
+            return {
+                text: redactBody(safeSerialise(encoded), secrets),
+                messageCount: encoded.length,
+            };
+        },
+    };
+}
+/**
+ * Count the turns and assemble NO bodies — for a driver that has nowhere to put them (the backend
+ * with `LLM_RECORD_PROMPTS` off, where the store drops every body it is handed).
+ *
+ * `messageCount` stays real, because it is a COUNT rather than a body and every consumer of the
+ * metric wants it. The point is not to omit data the gate would keep; it is that serialising a
+ * transcript the gate is about to drop is pure cost, and the whole reason bodies travel to the
+ * recorder as thunks (`CLAUDE.md` → "Telemetry & agent-context observability").
+ */
+function createCountingTranscript(seed) {
+    let messageCount = seed.length;
+    return {
+        append() {
+            messageCount += 1;
+        },
+        snapshot: () => ({ text: '', messageCount }),
+    };
+}
+/** Serialise a transcript for the store, never throwing into the stream that produced it. */
+function safeSerialise(turns) {
+    try {
+        return JSON.stringify(turns) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * Assemble ONE conversation's per-call telemetry from the CLI stream: the growing request
  * transcript and the per-call token/body metrics.
@@ -88,16 +194,20 @@ export function createClaudeCallAggregator(handlers) {
  * was not sent. A subagent's conversation seeds EMPTY — its prompt was minted by the CLI and never
  * crosses this stream — which is also why its first call carries `messageCount: 0` (the backend's
  * `latestChainTip` skips those on purpose: there is no re-sendable chain to delta against).
- * Bodies are credential-scrubbed; they can echo the leased token.
+ * Bodies are credential-scrubbed; they can echo the leased token — and assembled at all only when
+ * {@link ClaudeStreamTelemetryOptions.bodies} says a driver has somewhere to put them. The
+ * transcript is bounded either way ({@link MAX_TRANSCRIPT_CHARS}).
  *
  * Deliberately does NOT touch {@link PiRunStats}: the run's tool/output counters describe whether
  * the agent ACTED at all (`agentNeverActed`), which is true of a subagent's turns whichever channel
  * ends up owning their telemetry rows. The caller accumulates them off the raw stream instead.
  */
 export function createClaudeStreamTelemetry(opts) {
-    const messages = [...opts.seed];
-    let callPrompt = '';
-    let callMessageCount = 0;
+    const bodies = opts.bodies ?? true;
+    const transcript = bodies
+        ? createBoundedTranscript(opts.seed, opts.secrets, opts.maxTranscriptChars ?? MAX_TRANSCRIPT_CHARS)
+        : createCountingTranscript(opts.seed);
+    let sent = { text: '', messageCount: 0 };
     // The aggregator IS the surface: the transcript and metric work happens in its callbacks, so
     // there is nothing to wrap it in.
     return createClaudeCallAggregator({
@@ -105,16 +215,15 @@ export function createClaudeStreamTelemetry(opts) {
         // produced the response, and later envelopes of the same call must not see the turns it
         // went on to add.
         onCallStart: () => {
-            callPrompt = redactBody(JSON.stringify(messages), opts.secrets);
-            callMessageCount = messages.length;
+            sent = transcript.snapshot();
         },
         onCall: (call) => {
             opts.publish({
                 ...(call.model ? { model: call.model } : {}),
-                promptText: callPrompt,
-                messageCount: callMessageCount,
-                responseText: redactBody(call.text, opts.secrets),
-                reasoningText: redactBody(call.reasoning, opts.secrets),
+                promptText: sent.text,
+                messageCount: sent.messageCount,
+                responseText: bodies ? redactBody(call.text, opts.secrets) : '',
+                reasoningText: bodies ? redactBody(call.reasoning, opts.secrets) : '',
                 inputTokens: call.inputTokens,
                 cacheReadTokens: call.cacheReadTokens,
                 cacheWriteTokens: call.cacheWriteTokens,
@@ -123,9 +232,9 @@ export function createClaudeStreamTelemetry(opts) {
             });
             // Appended only now, so each call's prompt stays a strict prefix of the next and the
             // backend's telemetry chain delta-compresses cleanly.
-            messages.push({ role: 'assistant', content: call.content });
+            transcript.append({ role: 'assistant', content: call.content });
             for (const result of call.toolResults)
-                messages.push({ role: 'tool', content: result });
+                transcript.append({ role: 'tool', content: result });
         },
     });
 }
@@ -171,11 +280,8 @@ function createSubagentStreamTelemetry(opts) {
         let telemetry = perDispatch.get(dispatchId);
         if (!telemetry) {
             // Seeded EMPTY: the CLI minted this subagent's prompt and it never crossed the stream.
-            telemetry = createClaudeStreamTelemetry({
-                seed: [],
-                secrets: opts.secrets,
-                publish: opts.publish,
-            });
+            // Each dispatch gets its OWN retention bound, since each is its own conversation.
+            telemetry = createClaudeStreamTelemetry({ ...opts, seed: [] });
             perDispatch.set(dispatchId, telemetry);
         }
         return telemetry;

package/dist/claude-stream.d.ts

@@ -0,0 +1,56 @@
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 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 declare const SUBAGENT_TOOL_NAMES: Set<string>;
+export declare function numberOf(value: unknown): number;
+/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
+export declare function redactBody(text: string, secrets: string[]): string;
+/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
+export declare function claudeAssistantContent(content: unknown[]): {
+    text: string;
+    reasoning: string;
+    toolUses: number;
+};
+/**
+ * The text a `tool_result` block carries. The CLI writes it either as a bare string or as an
+ * array of content blocks (the shape a subagent's terminal report arrives in), so both are read
+ * here rather than at each call site. Non-text blocks (an image a tool returned) contribute
+ * nothing. Returns '' when the block carries no readable text.
+ *
+ * This is what makes a parallel subagent's work observable to the harness at all: the parent
+ * stream shows a subagent's dispatch and its terminal `tool_result` and nothing in between, so
+ * this text is the ONLY place its findings surface outside its own untailed transcript.
+ */
+export declare function claudeToolResultText(block: Record<string, unknown>): string;
+/**
+ * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
+ * the cumulative `result` total).
+ *
+ * Anthropic reports all three input classes SEPARATELY and `input_tokens` is already
+ * exclusive of both caches, so the three fields here are orthogonal and additive:
+ * total input = `inputTokens + cacheReadTokens + cacheWriteTokens`. Do NOT re-lump the
+ * reads and the writes — a cache write costs 1.25–2× base input while a read costs ~0.1×,
+ * so a turn that keeps invalidating the prefix and one that rides a warm cache are
+ * indistinguishable once they are summed.
+ */
+export declare function claudeCallUsage(raw: unknown): {
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+};

package/dist/coding-agent.d.ts

@@ -0,0 +1,263 @@
+import type { AgentJob, AgentResult, HarnessAuthFields, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
+import type { HarnessCallMetric, PiRunStats } from './pi.js';
+import { type EffortReport } from './effort.js';
+import { type AgentPrDescription } from './pr-description.js';
+import type { ProgressGuardLimits } from './progress-guard.js';
+import type { RunOptions } from './runner.js';
+import { type Logger } from './logger.js';
+import { type ValidationChecksSpec, type ValidationReport } from './validation-checks.js';
+import { type ReproductionReport, type ReproductionSpec } from './reproduction-proof.js';
+import { type DependencyInstallSpec } from './dependency-install.js';
+/** What a coding agent run needs: where to clone, what to run, where to push. */
+export interface CodingAgentSpec extends HarnessAuthFields {
+    /** Short label for the temp dir + log lines (e.g. 'impl', 'ci-fix'). */
+    kind: string;
+    /** The job id, threaded into every log line for end-to-end tracing. */
+    jobId: string;
+    repo: RepoSpec;
+    /** Branch to clone and check out as the starting point. */
+    cloneBranch: string;
+    /** A fresh branch to create off the clone before running; omit to work directly on `cloneBranch`. */
+    newBranch?: string;
+    /** Branch the produced change is pushed to. */
+    pushBranch: string;
+    ghToken: string;
+    /** Composed role + best-practice fragments; written to Pi's global AGENTS.md context. */
+    systemPrompt: string;
+    /** The concrete task prompt handed to Pi. */
+    userPrompt: string;
+    model: string;
+    /** Commit message for any work the agent left uncommitted. */
+    commitMessage: string;
+    /** Per-kind web-search guidance (backend-composed); surfaced only when web search is on. */
+    webToolsGuidance?: string;
+    /** Enable proxy-backed web search for this run (see {@link AgentRunSpec.webSearchProxy}). */
+    webSearchProxy?: boolean;
+    /** Backend serves the phase-tagged completions route (see {@link AgentRunSpec.proxyPhasePath}). */
+    proxyPhasePath?: boolean;
+    /** Per-knob progress-guard overrides (loosen-only), set per agent kind by the backend. */
+    guardLimits?: Partial<ProgressGuardLimits>;
+    /**
+     * Reuse a stable per-repo checkout (clean-sweep + fetch + switch branch) instead of a
+     * fresh clone into a throwaway temp dir. Set only by the local warm-pool transport
+     * (its containers are reused across runs); absent everywhere else.
+     */
+    persistentCheckout?: boolean;
+    /**
+     * Tail the Coder's follow-up sentinel file ({@link FOLLOW_UPS_FILENAME}) and stream the
+     * forward-looking items it surfaces out on the job view (the Follow-up companion). Set
+     * only for the implementer (`coder`) dispatch; absent ⇒ no tailing (e.g. the CI-fixer).
+     */
+    streamFollowUps?: boolean;
+    /**
+     * Whether this dispatch OPENS a pull request (the caller passes `pr` to `openPullRequest`).
+     * Set, the harness looks for the repo's own pull-request template and asks the agent to fill it
+     * (see `pr-template.ts`). Absent for a dispatch that amends someone else's PR (the in-place
+     * fixers) — a template filled for a pull request nothing opens is wasted prompt and, worse,
+     * would have a CI-fixer rewrite the implementer's already-published description.
+     */
+    opensPr?: boolean;
+    /**
+     * READ-ONLY reference branches of THIS repo (the apriori-branches reference mode): fetched
+     * into `origin/<b>` after the checkout so the agent can inspect them but never commits to
+     * them. Best-effort per branch. Absent/empty ⇒ none fetched.
+     */
+    referenceBranches?: string[];
+    /**
+     * Ralph loop: run this programmatic completion command in the checkout AFTER the agent
+     * commits + pushes, capturing its exit code + a bounded output tail (the loop's exit
+     * condition — computed by the harness, never the model). Absent for every non-`ralph` run.
+     */
+    validation?: {
+        command: string;
+        iteration?: number;
+    };
+    /**
+     * PRE-PR VALIDATION: the service's configured check commands + repair-round budget. When set,
+     * the harness runs them against the checkout after the agent settles and, while they fail and
+     * budget remains, re-runs the agent with the captured output as its instruction. A red checkout
+     * at the end means the caller opens NO pull request and fails the job. Set only for a dispatch
+     * that opens a PR and whose service configured checks; absent everywhere else. See
+     * `docs/initiatives/pre-pr-validation.md`.
+     */
+    validationChecks?: ValidationChecksSpec;
+    /**
+     * DEPENDENCY PREPOPULATION: the service's install command, run against the checkout BEFORE the
+     * agent's first turn so it works against a tree whose dependencies are present. Best-effort —
+     * a failure becomes a note in the agent's prompt, never a failed run. Absent ⇒ no install
+     * phase. See `docs/initiatives/agent-dependency-prepopulation.md`.
+     */
+    dependencyInstall?: DependencyInstallSpec;
+    /**
+     * BUGFIX REPRODUCTION PROOF: the run's declared reproduction command + test files. When set, the
+     * harness runs that command against the pre-fix tree AND the tree the PR will open from, feeding
+     * a failed verification back to the agent while budget remains, and attaches the verdict to the
+     * outcome. Unlike {@link validationChecks} it NEVER gates the pull request — an unproven
+     * reproduction is weak evidence, which is a reviewer's call, not a machine's. Set only for a
+     * dispatch that opens a PR and whose run carries a declaration. See
+     * `docs/initiatives/bugfix-reproduction-proof.md`.
+     */
+    reproduction?: ReproductionSpec;
+    /**
+     * The skills to make available for this run — a `skill` step's pick and/or the running kind's
+     * declared playbooks. Threaded into {@link runAgentInWorkspace}, which installs them
+     * harness-aware: natively under the ISOLATED `CLAUDE_CONFIG_DIR` for a leased-credential
+     * claude-code run, `.cat-context/skill/<name>/` for everything else (Pi, codex, and ambient
+     * claude-code, which has no isolated config dir). Absent ⇒ no skills.
+     */
+    skills?: SkillSpec[];
+    /**
+     * Tool servers (MCP) to wire into the agent CLI for this run. Forwarded verbatim — the backend
+     * has already dropped anything this harness cannot serve. Absent ⇒ built-in tools only.
+     */
+    mcpServers?: McpServerSpec[];
+}
+/** The outcome of a coding agent run, before each caller maps it to its own result shape. */
+export interface CodingAgentOutcome {
+    /** Whether the branch carries work and was therefore pushed (new commits, or resumed prior work). */
+    pushed: boolean;
+    /** Whether the run resumed an existing remote branch (prior work already pushed). */
+    resumed: boolean;
+    summary: string;
+    stats: PiRunStats;
+    stderrTail?: string;
+    /** Token usage from a subscription harness's CLI stream (absent for Pi). */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Per-model-call telemetry from a subscription harness's CLI stream (absent for Pi). */
+    callMetrics?: HarnessCallMetric[];
+    /** The agent's effort self-assessment, lifted from its sentinel file (absent when it wrote none). */
+    effortReport?: EffortReport;
+    /**
+     * The agent-authored PR description, lifted from its sentinel file (absent when it wrote none).
+     * The PR-opening caller folds it over the dispatch-time title/body via {@link applyPrDescription};
+     * absent means the fallback text, unchanged.
+     */
+    prDescription?: AgentPrDescription;
+    /**
+     * Ralph loop: the verdict of the post-commit validation command (whether it exited 0, the
+     * exit code, and a bounded/redacted output tail). Present only when {@link CodingAgentSpec.validation}
+     * was set. The exit code is the loop's authoritative completion signal.
+     */
+    validation?: {
+        validationPassed: boolean;
+        exitCode: number;
+        validationOutputTail?: string;
+        iteration?: number;
+        /** The work-branch HEAD the command was judged against (absent when it could not be read). */
+        headSha?: string;
+    };
+    /**
+     * The pre-PR validation loop's LAST attempt (present only when {@link CodingAgentSpec.validationChecks}
+     * was set). `passed: false` means the attempt budget was spent with the checkout still red —
+     * the caller must open no PR and fail the job with this as the evidence.
+     */
+    validationReport?: ValidationReport;
+    /**
+     * The bugfix reproduction proof's LAST attempt (present only when
+     * {@link CodingAgentSpec.reproduction} was set). Evidence, never a gate: `inconclusive` is
+     * attached to a perfectly successful run and the PR still opens.
+     */
+    reproductionReport?: ReproductionReport;
+}
+/**
+ * Clone (or RESUME an existing branch) → write context → run Pi → push the branch
+ * iff it carries work. The agent commits its OWN work (it alone knows which files
+ * belong vs scratch/artifacts it created), so the harness never blanket-stages:
+ * {@link commitTrackedEdits} is only a safety net for forgotten edits to ALREADY
+ * tracked files, and the run is judged a no-op only when the branch never advanced
+ * past its pre-run tip ({@link branchHasCommitsSince}). The harness owns push + PR;
+ * it checkpoints (pushes) periodically so an evicted run's commits survive and a
+ * 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).
+ */
+export declare function runCodingAgent(spec: CodingAgentSpec, opts?: RunOptions): Promise<CodingAgentOutcome>;
+/**
+ * The Ralph-loop validation watchdog: the longest a completion command may run before it is
+ * killed and treated as a failure (a hung `pnpm test` must never block the loop forever).
+ * Overridable via env for tests; defaults to 15 minutes.
+ */
+export declare function ralphValidationTimeoutMs(): number;
+/**
+ * How often the Ralph validation feeds the run's inactivity watchdog while its command runs.
+ * The command is exactly the activity-SILENT kind — a full `pnpm test`, a cold install-then-build
+ * — and the harness spawns it ITSELF rather than through the agent, so it emits no activity
+ * events of its own. `JOB_INACTIVITY_MS` (default 10 min) is TIGHTER than the command's own
+ * watchdog ({@link ralphValidationTimeoutMs}, default 15 min), so without this heartbeat any
+ * validation running past 10 minutes aborted the whole iteration as "inactivity" — mislabelling
+ * a healthy test suite as a wedge, and making the 15-minute watchdog unreachable at stock
+ * settings. The two sibling harness-run phases (pre-PR validation, reproduction proof) have
+ * always fed it; this one did not. Overridable via env for tests.
+ */
+export declare function ralphHeartbeatMs(): number;
+/**
+ * Bound on the validation output tail that crosses the wire. Deliberately smaller than
+ * `MAX_CAPTURED_OUTPUT_CHARS` (`redact.ts`) and equal to the two sibling phases' budgets, for
+ * the same reason: this tail is persisted on the step (and on EVERY iteration of the attempt
+ * log) inside the run's `detail` JSON blob, which is re-serialized on every step-progress write.
+ */
+export declare const RALPH_VALIDATION_TAIL_CHARS = 4000;
+/**
+ * Ralph loop: run the programmatic completion command in the checkout and return its exit
+ * code, a bounded + redacted tail of its output, and the work branch's HEAD it ran against.
+ * The EXIT CODE is the loop's authoritative done signal (0 = the criterion is met) — computed
+ * here by the harness, never self-reported by the model, which is the whole point of a
+ * programmatic exit condition. The command runs INSIDE the sandboxed run container (the same
+ * trust boundary as the coding agent) — there is no host/backend execution.
+ *
+ * The spawn itself goes through {@link runCapturedCommand}, the ONE seam for a harness-run
+ * command, rather than the near-verbatim copy this used to be. That copy had drifted in two
+ * ways the seam exists to prevent: it scrubbed secrets AFTER the rolling truncation with no
+ * margin (so a credential straddling the cut lost its `KEY=` prefix and survived redaction as
+ * an unrecognised partial, on a tail that reaches the step, the notification and the SPA), and
+ * it published the full 16k capture where both siblings deliberately bound the wire tail.
+ *
+ * `headSha` is what lets the engine tell a loop that is iterating from one that is merely
+ * repeating: two consecutive failing iterations against an unchanged head means the agent
+ * committed nothing, and the loop is ended early instead of spending the rest of its budget.
+ * Best-effort — a head that cannot be read is simply omitted, and the engine's check fails open.
+ */
+export declare function runRalphValidation(repoDir: string, cwd: string, validation: {
+    command: string;
+    iteration?: number;
+}, logger: Logger, opts: RunOptions): Promise<{
+    validationPassed: boolean;
+    exitCode: number;
+    validationOutputTail?: string;
+    iteration?: number;
+    headSha?: string;
+}>;
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export declare function safeDirSegment(value: string): string;
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
+ * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
+ * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
+ * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
+ * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
+ * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
+ * independently, so a divergent rule would point the agent at a directory that does not exist.
+ */
+export declare function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string;
+/**
+ * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
+ * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at
+ * that root (so it makes the cross-service change coherently across all of them), then commit +
+ * push each repo that actually changed and open one PR per dirty repo. The task's own-service PR
+ * is reported as `prUrl`/`branch`; the peer PRs as `peerPullRequests`.
+ *
+ * Deliberately simpler than the single-repo {@link runCodingAgent} for the first cut: NO mid-run
+ * checkpoint pushes (an evicted multi-repo run re-clones on retry — the deterministic work branch
+ * still lets it resume any commits it managed to push at the end), NO warm-pool persistent
+ * checkout (always ephemeral), and NO follow-up sentinel streaming. It reuses the SAME dir-scoped
+ * git helpers, so the per-repo clone/commit/push/PR mechanics match the single-repo path exactly.
+ */
+export declare function runMultiRepoCoding(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;
+/**
+ * The "no changes" reason both coding agents report: a caller-supplied lead phrase
+ * plus the shared "never acted" cause and a credential-scrubbed tail of Pi's stderr.
+ */
+export declare function noChangesReason(lead: string, stats: PiRunStats, stderrTail: string | undefined): string;

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