@cat-factory/executor-harness 1.78.0 → 1.82.0

package/dist/job.d.ts

@@ -0,0 +1,666 @@
+import type { HarnessCallMetric, PiRunStats } from './pi.js';
+import type { HarnessKind } from './pi-workspace.js';
+import type { FailureCause } from './failure.js';
+import type { EffortReport } from './effort.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';
+import { type McpServerSpec, type SkillResourceSpec, type SkillSpec } from './agent-capabilities.js';
+export type { McpServerSpec, SkillResourceSpec, SkillSpec };
+/**
+ * Per-job auth fields, shared across every job shape. The Pi harness carries the
+ * proxy base URL + a model-locked session token; the subscription harnesses
+ * (Claude Code / Codex) carry a leased subscription token instead and talk direct
+ * to the vendor. `harness` selects which; absent ⇒ Pi.
+ */
+export interface HarnessAuthFields {
+    harness?: HarnessKind;
+    /** Worker LLM proxy base URL, including /v1 (Pi harness only). */
+    proxyBaseUrl?: string;
+    /**
+     * The backend declaring that it serves the phase-tagged completions route
+     * (`${proxyBaseUrl}/phase/<phase>/chat/completions`), so this run may attribute each model
+     * call to the phase that spent it (`docs/initiatives/token-burn-instrumentation.md`). The
+     * same shape as {@link AgentJob.webSearch}: the backend states what IT serves, and the
+     * harness points Pi accordingly.
+     *
+     * Not a capability handshake — the harness never asks and never adapts to an answer. It
+     * exists because the harness image and the backend are only a matched set on the Cloudflare
+     * deployment: a runner pool pins its own image and `LOCAL_HARNESS_IMAGE` overrides the
+     * recommended pin, so an image ahead of its backend would otherwise 404 every model call.
+     * Absent ⇒ the plain path, and the run's calls are recorded as unattributed.
+     */
+    proxyPhasePath?: boolean;
+    /** Signed, model-locked proxy session token (Pi harness only). */
+    sessionToken?: string;
+    /** Leased subscription credential (Claude Code OAuth token / Codex auth.json). */
+    subscriptionToken?: string;
+    /**
+     * Anthropic-compatible base URL for a non-Anthropic Claude-Code vendor (GLM via
+     * Z.ai, Kimi via Moonshot). Present ⇒ the claude-code runner points
+     * ANTHROPIC_BASE_URL there with ANTHROPIC_AUTH_TOKEN; absent ⇒ Anthropic itself
+     * (CLAUDE_CODE_OAUTH_TOKEN against api.anthropic.com).
+     */
+    subscriptionBaseUrl?: string;
+    /**
+     * Native local execution: the `claude-code` / `codex` CLI runs with the developer's
+     * OWN ambient login (`~/.claude` / `~/.codex`) instead of a leased subscription token.
+     * Set only by the local native transport; when true `subscriptionToken` is not required.
+     */
+    ambientAuth?: boolean;
+}
+export interface RepoSpec {
+    owner: string;
+    name: string;
+    baseBranch: string;
+    cloneUrl: string;
+    /**
+     * The VCS provider the repo lives on, when the dispatcher set it. Selects GitHub-PR vs
+     * GitLab-MR for the "open the PR" call AUTHORITATIVELY (rather than guessing from the
+     * clone URL host, which can't recognise an arbitrarily-named self-managed GitLab). Absent
+     * ⇒ inferred from the clone URL.
+     */
+    provider?: 'github' | 'gitlab';
+    /**
+     * For a monorepo service, the subdirectory (relative to the repo root, e.g.
+     * `packages/api`) the agent should run within. Sanitised on parse to a safe
+     * relative path so it can never escape the checkout. Absent ⇒ run at the repo root.
+     */
+    serviceDirectory?: string;
+}
+export interface PrSpec {
+    title: string;
+    body: string;
+}
+/**
+ * A connected service's repo to check out as a SIBLING alongside the primary during a
+ * multi-repo coding run (service-connections phase 3). The agent clones every peer repo
+ * into a sibling directory under the workspace root, makes the coherent cross-service
+ * change, and the harness opens ONE PR per peer repo it actually changed. The clone URL is
+ * host-allowlisted exactly like the primary `repo.cloneUrl`.
+ */
+export interface PeerRepoSpec {
+    repo: RepoSpec;
+    /** The involved service frame this repo resolved from, echoed back on the peer PR. */
+    frameId?: string;
+    /**
+     * The work branch to create off the peer's base and push (the shared `cat-factory/<block>`).
+     * Present for a COING fan-out (coder / ci-fixer). Absent for a READ-ONLY explore fan-out
+     * (the bug-investigator), which only clones the peer to read it and never pushes.
+     */
+    newBranch?: string;
+    /**
+     * The EXISTING branch to check the peer out at for a READ-ONLY explore fan-out (the `merger`
+     * scoring the combined diff clones each peer at its PR branch so the diff sees the PR change).
+     * Absent ⇒ the peer is cloned at its repo default branch (the bug-investigator). Ignored on the
+     * coding fan-out, which creates `newBranch` instead.
+     */
+    cloneBranch?: string;
+    /** Open a PR/MR in this peer when set AND the run changed the peer (skipped for a clean repo). */
+    pr?: PrSpec;
+    /** Per-repo GitHub token; defaults to the job's `ghToken` (one installation per workspace today). */
+    ghToken?: string;
+}
+/**
+ * A repository checked out READ-ONLY as a sibling alongside the primary during a
+ * document-authoring coding run — the doc-writer reads it (to reuse existing solutions as a
+ * reference) but the harness never creates a branch, commits, or opens a PR for it. Deliberately
+ * carries NO branch/PR fields (unlike {@link PeerRepoSpec}), so it is structurally impossible to
+ * push: the read-only guarantee is enforced by the shape itself, by cloning at the repo's own
+ * base branch with no work branch, and by skipping the leg in the push phase. The clone URL is
+ * host-allowlisted exactly like the primary `repo.cloneUrl`.
+ */
+export interface ReferenceRepoSpec {
+    repo: RepoSpec;
+    /** Per-repo GitHub token; defaults to the job's `ghToken` (one installation per workspace today). */
+    ghToken?: string;
+}
+/** Hosts the harness is willing to send the installation token to. */
+export declare function allowedGithubHosts(env?: NodeJS.ProcessEnv): Set<string>;
+/** One private-registry entry: rendered into `~/.npmrc` before the agent runs. */
+export interface PackageRegistrySpec {
+    ecosystem: 'npm';
+    /** Registry host, e.g. `registry.npmjs.org` — allowlisted, never a full URL. */
+    host: string;
+    /** npm scopes (`@org`) routed to this registry; EMPTY ⇒ authenticate the host only. */
+    scopes: string[];
+    token: string;
+}
+/** npm registry hosts the harness is willing to send a registry token to. */
+export declare function allowedNpmRegistryHosts(env?: NodeJS.ProcessEnv): Set<string>;
+/** Validate the optional `packageRegistries` list (see {@link PackageRegistrySpec}). */
+export declare function parsePackageRegistries(value: unknown, env?: NodeJS.ProcessEnv): PackageRegistrySpec[];
+/**
+ * One sensitive test credential the tester receives: an env-var name + its (secret) value.
+ * The backend seals these at rest and decrypts them at dispatch; the harness injects each as an
+ * environment variable the tester's shell can read (out of band — the value is NEVER in the
+ * prompt/telemetry). See {@link parseTestSecrets}.
+ */
+export interface TestSecretSpec {
+    key: string;
+    value: string;
+}
+/**
+ * Validate the optional tester `testSecrets` list — `{ key, value }` env pairs the harness
+ * injects into the run environment. Keys must be valid env-var names; toolchain-critical /
+ * reserved names ({@link isReservedEnvName}) and duplicates are dropped so a drifted body can't
+ * clobber PATH/NODE_OPTIONS/etc. Absent ⇒ no secrets injected.
+ */
+export declare function parseTestSecrets(value: unknown): TestSecretSpec[];
+/** The new repository a repo-bootstrap run force-pushes its fresh history to. */
+export interface BootstrapTargetSpec {
+    owner: string;
+    name: string;
+    cloneUrl: string;
+    defaultBranch: string;
+}
+/** How the generic agent runs: read-only exploration, or edit-and-push coding. */
+export type AgentMode = 'explore' | 'coding' | 'preview';
+/**
+ * Explore mode: how a container agent stands its dependencies up before the run (the
+ * tester). Two shapes, discriminated by `kind` (absent ⇒ `service`, the backend tester):
+ *   - `service` — a backend service under test: `local` brings the service's
+ *     docker-compose infra up on localhost for the run; `ephemeral` is a no-op stand-up
+ *     (the env is already deployed and its URL reaches the agent through its prompt).
+ *   - `frontend` — a frontend app under test (the self-contained UI-test flow): build the
+ *     frontend, stand WireMock up for its mocked upstreams, serve the built app, and point
+ *     the (`tester-ui`) agent at it. Everything runs as localhost PROCESSES in the one
+ *     container (no Docker-in-Docker), so it works on Cloudflare + Apple `container` too.
+ * Absent ⇒ the harness manages no infra.
+ */
+export type AgentInfraSpec = ServiceInfraSpec | FrontendInfraSpec;
+/** Backend-service tester infra (docker-compose local, or a deployed ephemeral env). */
+export interface ServiceInfraSpec {
+    /** Discriminant. Absent ⇒ `service` (the backend tester). */
+    kind?: 'service';
+    /** `local` stands infra up via docker-compose; `ephemeral` tests a deployed env. */
+    environment: 'local' | 'ephemeral';
+    /** Local mode: the service declared no infra dependencies (spin nothing up). */
+    noInfraDependencies?: boolean;
+    /** Local mode: repo-relative docker-compose path to stand the dependencies up. */
+    composePath?: string;
+    /** Ephemeral mode: the provisioned environment URL (echoed for context only). */
+    environmentUrl?: string;
+    /**
+     * The connected services "directly involved" in this task that have a LIVE ephemeral env this
+     * run (service title → URL), so a cross-service integration test can reach a peer's real
+     * environment. Echoed for context only (surfaced in the agent's prompt); the harness stands
+     * nothing up for it. Absent when no involved peer is live.
+     */
+    peerEnvironments?: Record<string, string>;
+}
+/**
+ * Frontend UI-test infra (the self-contained `tester-ui` flow). The backend has already
+ * resolved every backend upstream to a concrete URL — the bound service's live ephemeral
+ * env URL for the service under test, `http://localhost:<wiremockPort>` for every mocked
+ * upstream — and handed them here as {@link env}. The harness installs, builds (injecting
+ * `env` at build time, or writing a `window.env` shim for runtime injection), stands
+ * WireMock up on {@link wiremockPort} seeded from {@link wiremockMappingsPath}, serves the
+ * built app on {@link servePort}, health-checks it, and tells the agent the serve URL.
+ */
+export interface FrontendInfraSpec {
+    kind: 'frontend';
+    /**
+     * The frontend app's subdirectory within the checkout (a monorepo frontend). Absent ⇒ the
+     * checkout root. When set, install/build/serve run there and `outputDir`/`wiremockMappingsPath`
+     * are resolved relative to it.
+     */
+    directory?: string;
+    /** Package manager for install/build. Default `pnpm`. */
+    packageManager?: 'pnpm' | 'npm' | 'yarn';
+    /** Explicit install command, overriding the one derived from `packageManager`. */
+    install?: string;
+    /** package.json script that produces the built app. Default `build`. */
+    buildScript?: string;
+    /** The build's output directory, served in `static` mode. Default `dist`. */
+    outputDir?: string;
+    /** How the built app is served: static server of `outputDir`, or run `serveScript`. */
+    serveMode?: 'static' | 'command';
+    /** package.json script to run when `serveMode: 'command'` (e.g. `preview`). */
+    serveScript?: string;
+    /** The port the served app listens on inside the container. Default 4173. */
+    servePort?: number;
+    /** Build-time env vars vs a runtime `window.env` shim. Default `build`. */
+    envInjection?: 'build' | 'runtime';
+    /** Resolved backend upstream env vars (name → URL) to inject. Empty names filtered out. */
+    env?: Record<string, string>;
+    /** The WireMock mappings directory in the FE repo. Default `mocks/`. */
+    wiremockMappingsPath?: string;
+    /** The port WireMock listens on inside the container. Default 8089. */
+    wiremockPort?: number;
+}
+/**
+ * Coding mode (repo bootstrap): the divergent push of a bootstrap run. Instead of pushing
+ * a work branch on the cloned repo, the agent's result is force-pushed as a fresh
+ * single-commit history to a SEPARATE, pre-created target repository's default branch.
+ * Clone-and-adapt: `job.repo` is the reference architecture to clone + adapt, `target` is
+ * the new repo. From-scratch (`fromScratch`): start from an empty directory (the agent
+ * scaffolds), `job.repo` is unused as a clone source. Absent ⇒ the ordinary coding flow.
+ */
+export interface AgentBootstrapSpec {
+    /** The new repository the bootstrapped contents are pushed to (the push target). */
+    target: BootstrapTargetSpec;
+    /** Scaffold from an empty directory instead of cloning `job.repo` (no reference). */
+    fromScratch?: boolean;
+}
+/**
+ * A linked-context file the backend prepared (requirements / RFC / PRD / tracker issue)
+ * for the harness to materialise under CONTEXT_DIR in the checkout, so the agent can read
+ * it on demand. The harness can't reach Jira/GitHub itself, so all such context is fetched
+ * and shipped here up front. `path` is sanitised to a safe basename on parse.
+ */
+export interface ContextFileSpec {
+    path: string;
+    title: string;
+    url: string;
+    content: string;
+}
+/** How an explore agent's reply is consumed. */
+export interface AgentOutputSpec {
+    /** `prose` keeps the reply text; `structured` parses (and optionally repairs) it to JSON. */
+    kind: 'prose' | 'structured';
+    /** Compact shape description fed to the one-shot structured-output repair call. */
+    shapeHint?: string;
+    /** Whether to attempt the one-shot repair on a malformed reply (structured only). */
+    repair?: boolean;
+    /**
+     * Fail the run LOUDLY when the FINAL answer is unusable (cut off at the output ceiling,
+     * or empty) instead of repairing it — opt-in for kinds whose JSON deliverable is handed
+     * onward to be parsed/committed (e.g. the spec-writer). Absent ⇒ off.
+     */
+    failOnUnusableFinal?: boolean;
+}
+/**
+ * The generic agent job. `mode` selects the flow; the remaining fields are the union
+ * the flows need. Explore: clone `branch`, run read-only, return prose (or a parsed
+ * `custom` JSON object when `output.kind==='structured'`). Coding: clone `branch` (or
+ * resume `newBranch`), run, commit + push to `pushBranch`, and open `pr` when one is set
+ * and the run produced changes. Preview (local/node only): clone `branch`, build + serve
+ * the frontend (`infra.kind==='frontend'`) with its other upstreams mocked and KEEP IT
+ * RUNNING — no agent runs and the serve is deliberately not torn down when the job returns
+ * (see {@link AgentResult.preview}).
+ */
+/**
+ * Coding mode (Ralph loop): the programmatic completion criterion. After the coding agent
+ * commits + pushes, the harness runs {@link command} in the checkout and reports its exit
+ * code back on {@link AgentResult.ralphVerdict} — exit 0 means the loop is done. This is the
+ * whole point of a Ralph loop's exit condition being a REAL check: the harness runs it, not
+ * the model. The command runs only inside the sandboxed run container (same trust boundary
+ * as the coding agent). Absent for every non-`ralph` coding run.
+ */
+export interface ValidationSpec {
+    /** The shell command the harness runs against the checkout (exit 0 = the criterion is met). */
+    command: string;
+    /** Repo-relative progress-log path the agent maintains (informational; the harness doesn't write it). */
+    progressPath?: string;
+    /** 1-based iteration number, echoed back on the verdict for the engine's attempt log. */
+    iteration?: number;
+}
+export interface AgentJob extends HarnessAuthFields {
+    jobId: string;
+    /**
+     * The backend run this job belongs to, bound onto the per-job logger beside `jobId` and used
+     * for NOTHING else. The container is the far side of the platform's longest seam: the backend
+     * knows a run as `executionId` and the harness knew it only as `jobId`, so a container log line
+     * could not be joined to the run that dispatched it except through the
+     * `${executionId}-${agentKind}` job-id naming convention. Optional because a body predating the
+     * field (or a hand-rolled acceptance fixture) must still run — an absent id costs correlation,
+     * never the job.
+     */
+    workspaceId?: string;
+    executionId?: string;
+    mode: AgentMode;
+    systemPrompt: string;
+    userPrompt: string;
+    model: string;
+    ghToken: string;
+    repo: RepoSpec;
+    /** The branch to clone (the backend resolves base/pr/work to a concrete name). */
+    branch: string;
+    githubApiBase?: string;
+    webToolsGuidance?: string;
+    webSearch?: boolean;
+    /** Full-history clone (needed to diff against / merge the base). Default shallow. */
+    full?: boolean;
+    /**
+     * Coding mode (conflict-resolver): merge `origin/<mergeBase>` into the cloned PR branch
+     * to surface the Git conflicts, run the agent to resolve them, then complete the merge
+     * commit and push back onto the SAME branch (no new branch / PR). Requires `full` so the
+     * merge base + `origin/<mergeBase>` are present. Absent ⇒ the ordinary coding flow.
+     */
+    mergeBase?: string;
+    /**
+     * Coding mode (repo bootstrap): force-push the agent's output as a fresh single-commit
+     * history to a separate, pre-created target repo (clone + adapt `repo`, or scaffold from
+     * scratch). Absent ⇒ the ordinary clone-edit-push-on-the-same-repo coding flow.
+     */
+    bootstrap?: AgentBootstrapSpec;
+    /** Explore mode: how to consume the reply. Absent ⇒ prose. */
+    output?: AgentOutputSpec;
+    /**
+     * Linked-context files to materialise under CONTEXT_DIR before the run (both modes).
+     * The agent reads them on demand; they are kept out of any commit. Absent ⇒ none.
+     */
+    contextFiles?: ContextFileSpec[];
+    /**
+     * Private package-registry auth (npm private orgs, GitHub Packages), rendered into
+     * `~/.npmrc` before the run so the checkout's installs — the agent's own and the
+     * frontend-infra stand-up's — resolve private dependencies. Hosts are hard-allowlisted
+     * (see {@link allowedNpmRegistryHosts}). Absent ⇒ any stale `~/.npmrc` from a prior
+     * job on a reused container is removed.
+     */
+    packageRegistries?: PackageRegistrySpec[];
+    /**
+     * The skills to make available for this run (see {@link SkillSpec}) — a `skill` step's picked
+     * skill and/or the playbooks the running agent kind declares. Materialised harness-aware before
+     * the run: natively into `CLAUDE_CONFIG_DIR/skills/<name>/` for claude-code, or
+     * `.cat-context/skill/<name>/<relPath>` for Pi/codex. Absent ⇒ no skills installed.
+     */
+    skills?: SkillSpec[];
+    /**
+     * Tool servers (MCP) to wire into the agent CLI for this run (see {@link McpServerSpec}). The
+     * backend has already dropped anything this harness cannot serve, so every entry here is
+     * expected to work. SECRET-BEARING (`env`/`headers` carry resolved credentials), so the config
+     * files written from it live outside the checkout and are never logged. Absent ⇒ the CLI's
+     * built-in tools only.
+     */
+    mcpServers?: McpServerSpec[];
+    /**
+     * Tester kinds only: sensitive test credentials injected into the run's ENVIRONMENT (out of
+     * band) as `{ key, value }` env pairs, so the tester's shell can read `$KEY` without the value
+     * ever appearing in the prompt or telemetry. Reserved/toolchain env names are dropped at parse.
+     * Absent ⇒ no secrets injected.
+     */
+    testSecrets?: TestSecretSpec[];
+    /**
+     * Explore mode: stand the service's dependencies up before the agent runs (the
+     * tester). Brings the docker-compose infra up on localhost for the duration of the
+     * run and tears it down afterward; a stand-up failure is non-fatal (surfaced to the
+     * agent as a note). The agent makes no commits regardless. Absent ⇒ no infra managed.
+     *
+     * Preview mode: REQUIRED and must be the `frontend` variant — it is the whole job (build
+     * + serve + WireMock, kept alive). No agent runs and, unlike the tester, the stand-up is
+     * NOT torn down when the job returns.
+     */
+    infra?: AgentInfraSpec;
+    /** Coding mode: a fresh branch to create off the clone before running (else work on `branch`). */
+    newBranch?: string;
+    /** Coding mode: branch the produced change is pushed to (defaults to `newBranch ?? branch`). */
+    pushBranch?: string;
+    /** Coding mode: commit message for any work the agent left uncommitted. */
+    commitMessage?: string;
+    /** Coding mode: open this PR when the run pushed changes. Absent ⇒ push only, no PR. */
+    pr?: PrSpec;
+    /**
+     * Coding mode (implementer): connected services' repos to clone as SIBLINGS for a MULTI-REPO
+     * change (service-connections phase 3). When present, the agent works with its cwd at the
+     * workspace ROOT (all repos are sibling checkouts under it), and the harness opens one PR per
+     * peer repo it actually changed — in addition to the primary. Absent ⇒ single-repo run.
+     */
+    peerRepos?: PeerRepoSpec[];
+    /**
+     * Coding mode (doc-writer): repositories to clone READ-ONLY as SIBLINGS for the agent to
+     * reference while it drafts the document. When present the agent works at the workspace ROOT
+     * (all checkouts are siblings under it); the harness clones each reference at its own base
+     * branch and NEVER creates a branch, commits, or opens a PR for it. Only the primary is
+     * pushed. Absent ⇒ single-repo run. Independent of {@link peerRepos} (those are writable).
+     */
+    referenceRepos?: ReferenceRepoSpec[];
+    /**
+     * Pre-existing branch names of the PRIMARY repo attached to the task as READ-ONLY reference
+     * points (the apriori-branches reference mode). After the primary checkout the harness fetches
+     * each into its `origin/<b>` tracking ref (best-effort per branch) so the agent can inspect it —
+     * `git log origin/<b>`, two-dot `git diff origin/<b>`, `git show origin/<b>:<path>` — but never
+     * commits to or pushes it (that guarantee lives in the prompt guidance, not a git constraint).
+     * Distinct from {@link referenceRepos}: those are separate sibling repos; these are branches of
+     * the same primary repo. Absent ⇒ none. Consumed by the coding + explore flows.
+     */
+    referenceBranches?: string[];
+    /**
+     * Explore mode (the `pr-reviewer`): the reviewed PR/MR number. Present ⇒ after the base
+     * checkout the harness fetches that PR's HEAD into `origin/pr-head` (best-effort) so the
+     * read-only reviewer can diff/read the PROPOSED code — files the PR adds are otherwise absent
+     * from the base checkout, and the agent has no git credential to fetch the head itself. The
+     * GitHub-vs-GitLab pull ref is chosen from `repo.provider` (host-inferred when absent). Absent
+     * ⇒ no head fetch (every non-review run). See {@link file://./git.ts} `fetchPullRequestHead`.
+     */
+    reviewPrNumber?: number;
+    /**
+     * Coding mode: whether a no-op run (nothing changed) is a failure. The implementer
+     * fails on a no-op; the in-place fixers (ci-fix / fix-tests) treat it as a non-fatal
+     * no-op. Default true.
+     */
+    noChangesIsError?: boolean;
+    /**
+     * 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,
+     * whose containers are reused across runs; absent everywhere else, so every other
+     * runtime keeps the ephemeral fresh-clone behaviour. The explore + ordinary coding
+     * flows honour it; bootstrap (resets `.git`) and conflict-resolution (needs full
+     * multi-branch state) always run ephemeral regardless.
+     */
+    persistentCheckout?: boolean;
+    /**
+     * Coding mode (implementer): tail the Coder's follow-up sentinel file and stream the
+     * forward-looking items it surfaces (loose ends / side-tasks / questions) out on the job
+     * view, so the backend lifts them onto the run's step (the Follow-up companion). Set only
+     * for the `coder` dispatch when the companion is enabled. Absent ⇒ no follow-up streaming.
+     */
+    streamFollowUps?: boolean;
+    /**
+     * Per-job overrides for the anti-rabbithole progress guard, set by the backend per
+     * AGENT KIND (a read-heavy kind tolerates more web/exploration before it counts as a
+     * stall). Each knob is optional and falls back to the env / built-in default
+     * ({@link progressGuardLimitsFromEnv}); only the knobs present here override. These are
+     * loosen-only: `mergeGuardLimits` clamps each override up to the base, so a value
+     * tighter than the default is ignored and a legitimately-progressing run is never
+     * killed for a kind's normal working pattern. Absent ⇒ env/default for all knobs.
+     */
+    guardLimits?: GuardLimitsSpec;
+    /**
+     * Coding mode (Ralph loop): the programmatic completion command the harness runs after the
+     * agent commits + pushes. Present only for a `ralph` iteration. See {@link ValidationSpec}.
+     */
+    validation?: ValidationSpec;
+    /**
+     * Coding mode: the service's PRE-PR VALIDATION CHECKS — commands the harness runs against the
+     * checkout after the agent settles and BEFORE opening a PR, feeding a failure back to the agent
+     * until they pass or the budget is spent. Present only on a dispatch that opens a PR and whose
+     * service configured checks; absent ⇒ the run behaves exactly as before. Deliberately keyed off
+     * job DATA, not the agent kind. See {@link ValidationChecksSpec}.
+     */
+    validationChecks?: ValidationChecksSpec;
+    /**
+     * Coding mode: the run's BUGFIX REPRODUCTION PROOF — the declared reproduction command, the
+     * test file(s) that constitute it, and an optional setup command. When set, the harness runs
+     * that command against the pre-fix tree AND the tree the PR will open from, and reports both
+     * exit codes: only red-then-green is proof. Present only on a dispatch that opens a PR and
+     * whose run carries a reproduction declaration; absent ⇒ the run behaves exactly as before.
+     * Deliberately keyed off job DATA, not the agent kind. See
+     * `docs/initiatives/bugfix-reproduction-proof.md`.
+     */
+    reproduction?: ReproductionSpec;
+    /**
+     * DEPENDENCY PREPOPULATION: the service's install command, run against the checkout BEFORE the
+     * agent's first turn so it reads a tree whose dependencies are present rather than inferring
+     * them from a manifest. Applies to EVERY mode that gets a checkout (explore as well as coding)
+     * — unlike {@link validationChecks}, which is a pre-PR gate — because an agent reading or
+     * reviewing a tree needs its dependencies as much as one changing it.
+     *
+     * Best-effort: a failure becomes a note in the agent's prompt, never a failed job. Absent ⇒ the
+     * run behaves exactly as before. Deliberately keyed off job DATA, not the agent kind. See
+     * `docs/initiatives/agent-dependency-prepopulation.md`.
+     */
+    dependencyInstall?: DependencyInstallSpec;
+}
+/** Per-job, per-knob progress-guard overrides (see {@link AgentJob.guardLimits}). */
+export interface GuardLimitsSpec {
+    maxToolCallsWithoutEdit?: number;
+    maxConsecutiveErrors?: number;
+    maxConsecutiveWebCalls?: number;
+}
+/**
+ * The record of standing the service's docker-compose dependencies up before a tester
+ * run (explore mode, `infra.environment === 'local'`). The compose stand-up happens
+ * INSIDE the container, so its output never reaches the orchestrator's provisioning-log
+ * store (which records only the backend-side container/env spin-up); this carries the
+ * captured (redacted + bounded) command output back structurally so the test window can
+ * show WHY the dependencies failed to come up — previously this was trapped in the
+ * harness's own logs. Absent for ephemeral / no-infra / no-compose-path runs.
+ */
+export interface InfraSetupRecord {
+    /** Whether `docker compose up --wait` succeeded (the dependencies are up). */
+    started: boolean;
+    /** The repo-relative compose file that was stood up. */
+    composePath?: string;
+    /** Epoch ms the stand-up attempt finished. */
+    at: number;
+    /** Wall-clock of the stand-up attempt, ms. */
+    durationMs?: number;
+    /** Captured (redacted, tail-bounded) stdout+stderr of the stand-up command. */
+    logs?: string;
+    /** The verbatim (redacted) failure message when stand-up failed, else absent. */
+    error?: string;
+}
+/** The generic agent response. `custom` carries a structured explore result. */
+export interface AgentResult {
+    summary?: string;
+    stats?: PiRunStats;
+    /** Structured explore output (the parsed JSON object) when `output.kind==='structured'`. */
+    custom?: unknown;
+    /**
+     * The tester's docker-compose stand-up record (explore mode, local infra). Carried back
+     * so the backend can surface the in-container dependency stand-up logs on the Tester step
+     * — the failure-class artifact the orchestrator-side provisioning logs can't capture.
+     */
+    infraSetup?: InfraSetupRecord;
+    /**
+     * The PRE-PR VALIDATION report: the outcome of running the service's configured check commands
+     * against the checkout after the agent settled and before opening a PR, plus how many repair
+     * rounds the harness spent. Present on BOTH outcomes — a passing report accompanies the opened
+     * PR (the captured proof), and a failing one accompanies the run's `error` (no PR was opened).
+     * Absent when the job carried no {@link AgentJob.validationChecks}.
+     */
+    validationReport?: ValidationReport;
+    /**
+     * The BUGFIX REPRODUCTION PROOF: the declared reproduction command's verdict across the pre-fix
+     * tree and the final tree, computed by the harness from exit codes. Present on every outcome of
+     * a job that carried {@link AgentJob.reproduction} — a verdict is evidence, not a gate, so an
+     * `inconclusive` one accompanies the opened PR exactly like a `reproduced` one does. Absent
+     * when the job carried no reproduction declaration.
+     */
+    reproductionReport?: ReproductionReport;
+    /**
+     * Preview mode: the in-container URL the built app is served at (e.g. `http://localhost:4173`).
+     * This is NOT host-reachable on its own — the container runtime publishes the serve port to an
+     * ephemeral host port and the backend forms the browsable URL from that; this is echoed for
+     * logging/context. Present only on a successful preview stand-up.
+     */
+    preview?: {
+        url: string;
+    };
+    /** Coding mode: whether a change was pushed. */
+    pushed?: boolean;
+    prUrl?: string;
+    branch?: string;
+    /**
+     * Coding mode (Ralph loop): the harness-computed verdict of the post-commit validation
+     * command — whether it exited 0, its exit code, and a bounded, redacted output tail. The
+     * engine reads this (never a model self-report) to decide whether the loop is done or must
+     * iterate again. Present only for a `ralph` iteration ({@link AgentJob.validation} set).
+     */
+    ralphVerdict?: {
+        validationPassed: boolean;
+        exitCode: number;
+        validationOutputTail?: string;
+        iteration?: number;
+        /**
+         * The work-branch HEAD the command was judged against. The engine compares it across
+         * consecutive failing iterations to end a loop that has stopped committing anything,
+         * instead of spending the rest of its budget re-learning that. Absent when unreadable.
+         */
+        headSha?: string;
+    };
+    /**
+     * Coding mode (multi-repo): the PRs opened in the connected services' PEER repos, one per
+     * repo the run actually changed (service-connections phase 3). Beside the own-service
+     * `prUrl`/`branch`; the backend lifts these onto the block's `peerPullRequests`. Absent for
+     * a single-repo run.
+     */
+    peerPullRequests?: {
+        repo: string;
+        frameId?: string;
+        prUrl: string;
+        branch: string;
+    }[];
+    /** Coding mode (bootstrap): the default branch the bootstrapped contents were pushed to. */
+    defaultBranch?: string;
+    error?: string;
+    /**
+     * The structured failure cause set alongside `error` on a clean-exit failure (no usable
+     * output, no changes to push, unresolved conflicts, …). The job registry copies it onto
+     * the job view so the backend classifies the failure without regex. See {@link FailureCause}.
+     */
+    failureCause?: FailureCause;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /**
+     * Per-model-call telemetry from a subscription harness's CLI stream (absent for the
+     * proxy-metered Pi harness). The backend records these into `llm_call_metrics`. See
+     * {@link HarnessCallMetric}.
+     */
+    callMetrics?: HarnessCallMetric[];
+    /**
+     * The agent's effort self-assessment (how hard the work was, what reduced its effectiveness,
+     * the key obstacles), lifted from its sentinel file after the run. The backend forwards it onto
+     * the job result and records it on the step for run details. Absent when the agent wrote none.
+     */
+    effortReport?: EffortReport;
+}
+/** The one-shot inline completion job. `harness` must be a subscription harness. */
+export interface InlineJob extends HarnessAuthFields {
+    jobId: string;
+    /** Real vendor model id, e.g. `claude-opus-4-8` / `gpt-5.5-codex`. */
+    model: string;
+    /** Composed role + best-practice fragments (Claude: `--append-system-prompt`; Codex: prepended). */
+    systemPrompt: string;
+    /** The concrete task/user prompt fed to the CLI over stdin. */
+    userPrompt: string;
+    /** Advisory output cap, forwarded for parity; the one-shot CLIs don't all honour it. */
+    maxOutputTokens?: number;
+}
+/** The inline completion result: the reply text plus lifted token usage / per-call telemetry. */
+export interface InlineResult {
+    text: string;
+    /** `length` when the model hit its output cap (the reviewer rejects a truncated doc). */
+    finishReason?: 'stop' | 'length';
+    /**
+     * The job's token usage with the input side split into its three ORTHOGONAL classes:
+     * `inputTokens` is FRESH input only, so the total input is
+     * `inputTokens + cacheReadTokens + cacheWriteTokens`. Folded from the per-call metrics below,
+     * which is the only channel that knows the split; a CLI that streamed none falls back to the
+     * coarse total with both cache classes 0 — honest, since on that shape nothing is known to
+     * have been cached.
+     */
+    usage?: {
+        inputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        outputTokens: number;
+    };
+    /** Per-model-call telemetry lifted from the CLI stream (recorded into `llm_call_metrics`). */
+    callMetrics?: HarnessCallMetric[];
+    /** A structured failure marks a job-level failure even on a clean HTTP exit (see JobResultBase). */
+    error?: string;
+}
+/**
+ * Validate + narrow an untrusted body into an {@link InlineJob}. The harness MUST be a
+ * subscription harness (`claude-code` / `codex`) — the inline path never runs Pi (that goes
+ * through the LLM proxy inline, not a container CLI). Reuses {@link parseHarnessAuth}, so a
+ * non-ambient job requires `subscriptionToken`.
+ */
+export declare function parseInlineJob(input: unknown): InlineJob;
+/** Validate + narrow an untrusted body into an {@link AgentJob}, throwing on bad input. */
+export declare function parseAgentJob(input: unknown): AgentJob;