@obversa/runtime 0.1.0

package/dist/core/assert-graph.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `assertGraph(job, shape)` — turn `jobMeta` introspection into test
+ * assertions. The shape is a PARTIAL expectation: only asserted fields are
+ * compared, and extra actual nodes are allowed unless `exactNodes: true`.
+ * On mismatch it throws a plain `Error` whose message carries the JSON path
+ * to the mismatch (e.g. `nodes[build].needs`) plus expected vs actual — the
+ * message IS the API (vitest surfaces it verbatim).
+ */
+import type { Job, JobMeta } from './types.js';
+export interface GraphNodeShape {
+    name: string;
+    needs?: string | string[];
+    desc?: string;
+    gate?: string;
+    optional?: boolean;
+    /** A boolean meaning "a `when` gate exists" — the meta stores condition
+     *  labels, so this is a presence check, not label equality. */
+    when?: boolean;
+    isolate?: boolean;
+    /** Asserted against the node's nested job meta (`node.job.kind`). */
+    kind?: string;
+}
+export interface GraphShape {
+    kind?: string;
+    name?: string;
+    nodes?: GraphNodeShape[];
+    /** Fail when the actual node set has names beyond `nodes`. */
+    exactNodes?: boolean;
+    body?: GraphShape;
+    [key: string]: unknown;
+}
+/** Assert a job's introspected shape matches a partial expectation. Accepts the
+ *  `Job` itself (resolved via `jobMeta`) or a `JobMeta` directly. */
+export declare function assertGraph(job: Job | JobMeta, shape: GraphShape): void;

package/dist/core/budget.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A token-denominated budget for a whole run, threaded through the JobContext so
+ * every engine call site can refuse to spend past the cap. Where `max` and depth
+ * bound the count of calls, this bounds their cost.
+ *
+ * The runner feeds `add()` from each `engine:usage` event, so `spent()` is live.
+ * `assertBudget(ctx)` runs before an engine call; once the cap is reached it
+ * throws a non-retryable BUDGET error (hard mode, terminates the run) or logs
+ * and continues (soft mode, for exploratory runs).
+ */
+import type { UsageReceipt } from '../engines/engine.js';
+interface BudgetContext {
+    readonly budget?: Budget;
+    log(message: string, level?: 'debug' | 'info' | 'warn' | 'error'): void;
+}
+export interface BudgetConfig {
+    /** Cap on total tokens (input + output) for the whole run. */
+    limit: number;
+    /**
+     * Refuse a new engine call once `spent + headroom >= limit`, i.e. stop with
+     * room to spare rather than only after the cap is already blown. Default 0.
+     */
+    headroom?: number;
+    /** Warn and continue instead of refusing when the cap is hit. Default false. */
+    soft?: boolean;
+}
+export declare class Budget {
+    readonly limit: number;
+    readonly headroom: number;
+    readonly soft: boolean;
+    private tokens;
+    private unknownCalls;
+    constructor(config: BudgetConfig);
+    /** Record consumed tokens. Non-finite or non-positive values are ignored. */
+    add(tokens: number): void;
+    addUsage(usage: UsageReceipt): void;
+    unknownUsageCalls(): number;
+    spent(): number;
+    remaining(): number;
+    /** True once the next call would breach the cap (accounting for headroom). */
+    exceeded(): boolean;
+}
+/**
+ * Guard an engine call against the run budget. No-op when no budget is set or
+ * the cap is not yet reached. In `soft` mode a breach warns and continues; in
+ * hard mode it throws a non-retryable BUDGET error that terminates the run.
+ */
+export declare function assertBudget(ctx: BudgetContext): void;
+export {};

package/dist/core/concurrency.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_FANOUT_CONCURRENCY = 4;
+export declare function mapWithConcurrency<T, R>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/core/condition.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Conditions answer a yes/no question against the run context and the latest
+ * body outcome. They power a loop's `start`, `until`, and `stopOn` gates.
+ *
+ * Two flavours, same type:
+ *   - deterministic (`predicate`, `bodyPassed`, `maxConfidence`)
+ *   - agent-validated (`agentCheck`): a model returns a verdict + confidence,
+ *     and the gate opens only above a threshold.
+ *
+ * `gateJob` lifts any Condition into a `Job`, so a reviewer can be expressed
+ * as a condition and still slot into `loop({ review })`.
+ */
+import type { Condition, ConditionInput, Outcome, Job, JobContext } from './types.js';
+import type { EngineRef } from '../engines/engine.js';
+import { type AgentDef } from './agent.js';
+/**
+ * Coerce any `ConditionInput` — a `Condition`, a bare predicate, or an array
+ * mixing both — into the single `Condition` primitive. This is what lets
+ * `until`/`start`/`stopOn` accept one or many items of either flavour.
+ *
+ * Arrays default to `all` (every item must hold); pass `'any'` for or-semantics.
+ */
+export declare function toCondition(input: ConditionInput, combine?: 'all' | 'any'): Condition;
+type ConditionPreparation = (ctx: JobContext) => Condition | Promise<Condition>;
+/** Internal lifecycle hook for conditions that need state from loop entry. */
+export declare function withConditionPreparation(condition: Condition, prepare: ConditionPreparation): Condition;
+/** Prepare a condition tree once for one loop invocation. */
+export declare function prepareCondition(input: ConditionInput, ctx: JobContext, combine?: 'all' | 'any'): Promise<Condition>;
+/** Deterministic predicate over context + last outcome. */
+export declare function predicate(fn: (ctx: JobContext, last: Outcome | undefined) => boolean | Promise<boolean>, reason?: string): Condition;
+/** Met when the most recent body outcome passed. */
+export declare function bodyPassed(): Condition;
+/** Met when the last outcome carries confidence at or above `threshold`. */
+export declare function minConfidence(threshold: number): Condition;
+/**
+ * Deterministic gate that runs a shell command and is met on exit code 0. This
+ * is the deterministic convergence signal for coding loop jobs: pair it with an
+ * `agentCheck` in an `until` array so the loop stops only when the tests ACTUALLY
+ * pass AND a judge agrees the work matches intent, never on a model's self-report
+ * alone.
+ * Runs in `cwd` (default: the process working dir), inherits the run's abort
+ * signal, and never throws (a spawn failure counts as "not met"). A command's
+ * `timeoutMs` is explicit: node/agent turn timeouts do not become hard shell
+ * kills for deterministic gates.
+ * `opts.env` pins vars for this one gate command; it is the most specific
+ * layer, over any `withEnv` overlay and the running environment's vars.
+ * `opts.captureOutput` appends a scrubbed, bounded combined-output tail to a
+ * failed command's reason. The separate evidence output remains unchanged.
+ */
+export declare function commandSucceeds(command: string, args?: string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    captureOutput?: boolean;
+}): Condition;
+export declare const always: Condition;
+export declare const never: Condition;
+/** Inverts a condition. The inner result's `output` is carried through unchanged. */
+export declare function not(c: ConditionInput): Condition;
+/**
+ * Met only when every input holds (short-circuits on the first failure).
+ * On failure the FAILING item's `output` is carried; a success carries none.
+ */
+export declare function all(...inputs: ConditionInput[]): Condition;
+/**
+ * Met when any input holds (short-circuits on the first success).
+ * On success THAT item's `output` is carried; on failure, the first defined
+ * `output` among the collected failures.
+ */
+export declare function any(...inputs: ConditionInput[]): Condition;
+/**
+ * Met when at least `k` of the inputs hold. A hedge against a single agent
+ * judge's self-reported confidence: ask N independent judges and require a
+ * quorum (e.g. `quorum(2, j, j, j)`). All inputs run in parallel; a judge that
+ * throws counts as a "no" vote rather than sinking the whole gate. Each input
+ * may hit a model, so size N with cost in mind. Reported confidence is the mean
+ * of the holding inputs' confidences. On failure the first defined `output`
+ * among the non-holding voters is carried; a success carries none.
+ */
+export declare function quorum(k: number, ...inputs: ConditionInput[]): Condition;
+export interface AgentCheckConfig {
+    /** The yes/no question the validator must answer. */
+    question: string;
+    /** Open the gate only at/above this confidence (0..1). Default 0.8. */
+    threshold?: number;
+    /** Cheap model recommended. A bare string, provider-agnostic. */
+    model?: string;
+    /**
+     * Give the judge a persona — an `AgentDef` whose resolved system (persona +
+     * skills) is prepended to the validator's scoring instructions, so a reviewer
+     * can be a named specialist (e.g. an adversarial reviewer) instead of an
+     * anonymous yes/no. The validator's output contract stays authoritative (it
+     * comes last); `model` falls back to the agent's `model`. Mirrors `agentJob`.
+     */
+    agent?: AgentDef;
+    /** Engine for validation: a registered name, your own `Engine`, or default. */
+    engine?: EngineRef;
+    /**
+     * Working directory for the judge's engine turn — a tool-using judge may
+     * need the workspace to read the artifact it is ruling on. Absent means the
+     * engine's default; deliberately NOT defaulted to the loop workspace.
+     */
+    cwd?: string;
+    /**
+     * Time cap on the judge turn, passed through to the engine. The
+     * anthropic-api engine ignores it.
+     */
+    timeoutMs?: number;
+    /**
+     * What the validator sees. By default: the last outcome's summary/data plus
+     * the shared state. Override to feed something bespoke; may be async, since a
+     * judge often gathers evidence (read the artifact, ground on the history, run a
+     * probe) before ruling. Give it the thing it is meant to be reviewing.
+     */
+    context?: (ctx: JobContext, last: Outcome | undefined) => string | Promise<string>;
+    maxTokens?: number;
+    /**
+     * Score these named dimensions (0..1 each) instead of a single yes/no
+     * confidence. The gate opens when the GEOMETRIC MEAN of the scores is
+     * >= `threshold`, so one weak dimension drags the whole verdict down. Stricter
+     * than a lone self-reported number, e.g.
+     * `['intent match', 'evidence quality', 'outcome coherence']`.
+     */
+    dimensions?: string[];
+    /**
+     * Parse a free-form review that closes with `<confidence>N%</confidence>`
+     * (N is 0-100) instead of forcing a JSON shape. The gate opens at/above
+     * `threshold`; the reviewer's prose before the tag becomes the gate's `reason`,
+     * so a failing review carries its findings to the next iteration (`lastReview`).
+     * More robust than scraping JSON, and the natural fit for a report-then-rate
+     * reviewer persona. Takes precedence over `dimensions`.
+     */
+    confidenceTag?: boolean;
+    /**
+     * Cap on the findings excerpt embedded in the `confidenceTag` gate `reason`.
+     * Default 280. The FULL findings always travel via `ConditionResult.output`.
+     */
+    maxReasonChars?: number;
+}
+/**
+ * A Condition decided by a (preferably cheap) model. With a single yes/no
+ * question the gate opens when the verdict is "yes" AND confidence >= threshold.
+ * With `dimensions`, the model scores each dimension 0..1 and the gate opens
+ * when their geometric mean >= threshold, stricter than a single number.
+ */
+export declare function agentCheck(config: AgentCheckConfig): Condition;
+/**
+ * Lift a Condition (or one-or-many `ConditionInput`) into a Job: `pass` when
+ * met, `fail` otherwise. This is how a reviewer becomes a drop-in `review` job
+ * (`gateJob('review', agentCheck(...))`). The condition's diagnostic `output`
+ * rides `Outcome.data`, so it survives the Job boundary.
+ */
+export declare function gateJob(label: string, condition: ConditionInput, opts?: {
+    /**
+     * The upstream node that owns the fix. When the condition is not met, the
+     * outcome carries a revision request to that node with the condition's
+     * evidence as the finding, so a red test suite goes straight back to the
+     * step that must fix it, with the output in hand and no agent in between.
+     * The enclosing `dag` routes it exactly as it routes a review panel's.
+     */
+    target?: string;
+}): Job;
+/**
+ * A command as a job: `pass` on exit 0, `fail` otherwise, with the command's
+ * output as the evidence. Give the command as one string when no argument
+ * needs quoting (`'pnpm test'`), or as an array, one argument per entry
+ * (`['node', '--test', 'test/']`). `target` names the node that owns the fix,
+ * exactly as `gateJob` does: a red run goes back there with the output as the
+ * finding and no agent in between. `capture` (default true) appends the
+ * output tail to the failure summary.
+ */
+export declare function commandJob(label: string, command: string | readonly string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    target?: string;
+    capture?: boolean;
+}): Job;
+/**
+ * Met when the named dependency passed. For a node's `when`: the node runs
+ * only on that path (`when: passed('size')`). A skipped dependency counts as
+ * passed, as it does everywhere in a dag. A name the node does not `need` is
+ * a configuration error, not a quiet false.
+ */
+export declare function passed(name: string): Condition;
+/**
+ * Met when the named dependency ran and failed: the other branch of `passed`.
+ * A dependency that never got to decide (blocked by a failure upstream, or
+ * aborted) meets neither, so a branch runs only on a decision. The deciding
+ * node must be `optional: true`: a required node's failure blocks its
+ * dependents before any `when` runs, so a branch on `failed` would never be
+ * reached. `dag` refuses the graph at build time when it is not.
+ */
+export declare function failed(name: string): Condition;
+/** One `passed(name)` or `failed(name)` found inside a condition input. */
+export interface NeedDecision {
+    readonly on: 'passed' | 'failed';
+    readonly need: string;
+}
+/**
+ * Every `passed(name)` and `failed(name)` a condition input requires: the
+ * input itself, each item of an array, and each input of `all`, which carry
+ * their inputs in their meta. `not`, `any` and `quorum` are not walked: a
+ * branch composed with them can be met another way, so a `failed(x)` inside
+ * one does not make the branch dead. The graph builder reads this to refuse
+ * a branch that could never run.
+ */
+export declare function needDecisionsOf(input: ConditionInput): NeedDecision[];
+export {};

package/dist/core/context.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Build a child `JobContext` from a parent, overriding only the per-scope
+ * fields. One helper shared by `loop()` and `dag()` so the next field added to
+ * `JobContext` is threaded in exactly one place.
+ */
+import type { ConditionResult, GraphPosition, JobContext, Outcome, Workspace } from './types.js';
+import type { EnvHandle } from '../env/environment.js';
+export interface ContextOverride {
+    depth: number;
+    path: readonly string[];
+    iteration?: number;
+    lastOutcome?: Outcome;
+    lastReview?: Outcome;
+    lastGate?: ConditionResult;
+    /** The outcomes of a dag node's `needs`, set by the dag for that node only. */
+    needs?: Readonly<Record<string, Outcome>>;
+    /** Override the workspace (a worktree fork at a concurrency boundary). */
+    workspace?: Workspace;
+    /** Override the environment (a per-team env at a concurrency boundary). */
+    environment?: EnvHandle;
+    /** Override the pinned env vars (a `withEnv` wrapper layering its overlay). */
+    envOverlay?: Record<string, string>;
+    /** Override the DAG graph position for a node. */
+    graph?: GraphPosition;
+    /** Set or clear the acceptance criterion visible to a stage reviewer. */
+    reviewerGate?: string | null;
+    /** Carry the nearest DAG node's acceptance criterion through nested jobs. */
+    stageGate?: string | null;
+    /** Override the inherited timeout for jobs in this scope. */
+    timeoutMs?: number;
+    /** Override the inherited timeout grace for jobs in this scope. */
+    timeoutGraceMs?: number;
+}
+/** Resolve the criterion for the reviewer context currently being evaluated. */
+export declare function criterionFor(ctx: Pick<JobContext, 'reviewerGate' | 'stageGate' | 'graph'>): string | undefined;
+export declare function childContext(parent: JobContext, over: ContextOverride): JobContext;

package/dist/core/cost.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Cost accounting over the run's measured token usage — the honest-receipt
+ * fold. Two rules keep cost reports honest:
+ *
+ * 1. **Never silently $0.** A model without complete price coverage lands in
+ *    `unpricedModels`, and the totals stay `undefined` rather than pretending
+ *    the run was free or pricing cached input at the base input rate.
+ * 2. **The baseline is labeled a reconstruction.** `baselineUsd` prices the
+ *    SAME measured token stream at the baseline model's rates — "what these
+ *    exact tokens would have cost on the ceiling model". It is a like-for-like
+ *    counterfactual, not a measured alternative run, and consumers should say
+ *    so when they print it.
+ *
+ * Prices are supplied by the caller (a JSON file via `--prices`, or a table
+ * in code). The library ships none: hardcoded prices go stale, and a wrong
+ * price is worse than no price.
+ */
+import type { StatsSnapshot } from './stats.js';
+export interface ModelPrice {
+    /** Dollars per million input tokens. */
+    inputPerMTokUsd: number;
+    /** Dollars per million output tokens. */
+    outputPerMTokUsd: number;
+}
+/** Model id → price. Keys match exactly first, then by longest prefix, so
+ *  `"claude-sonnet-5"` covers dated ids like `claude-sonnet-5-20250929`. */
+export type PriceTable = Record<string, ModelPrice>;
+export interface ModelCost {
+    model: string;
+    calls: number;
+    reportedCalls: number;
+    unknownUsageCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** Undefined when the table cannot price this model's complete usage. */
+    usd?: number;
+}
+export interface CostReport {
+    /** Measured usage priced at each model's own rate; undefined if ANY used
+     *  model is unpriced (a partial total masquerading as a total is a lie). */
+    spentUsd?: number;
+    /** The same token stream repriced at the baseline model — a reconstruction. */
+    baselineModel?: string;
+    baselineUsd?: number;
+    /** `baselineUsd - spentUsd` when both exist. Negative means the run cost
+     *  MORE than the baseline would have. */
+    savedUsd?: number;
+    /** Models whose complete usage cannot be priced by the supplied table. */
+    unpricedModels: string[];
+    /** Models with calls whose provider reported no usage receipt. */
+    unknownUsageModels: string[];
+    models: ModelCost[];
+}
+/** Exact key first, then the longest prefix whose next char is a boundary. */
+export declare function priceFor(table: PriceTable, model: string): ModelPrice | undefined;
+export declare function costReport(snapshot: Pick<StatsSnapshot, 'models'>, prices: PriceTable, baselineModel?: string): CostReport;
+/** A compact receipt for the exit summary. States what is measured and what
+ *  is reconstructed; names unpriced models instead of zeroing them. */
+export declare function formatCostReport(report: CostReport): string[];

package/dist/core/dag.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The DAG / stages layer. `dag(config)` returns a `Job`, so it nests with
+ * `loop()` both ways. Nodes declare `needs` (dependencies); each node waits on
+ * its dependencies' promises, then runs under a shared `p-limit` concurrency
+ * gate. Cycle/missing-dep detection is delegated to `toposort` and happens
+ * before any work runs.
+ *
+ * Failure policy (ours, not the libs'):
+ *   - a required node failing blocks its dependents (they don't run);
+ *   - with `stopOnError` (default) the first required failure stops scheduling
+ *     anything not already in flight;
+ *   - `optional` nodes never fail the DAG nor block dependents;
+ *   - an unmet `when` gate *skips* the node, which counts as green.
+ */
+import type { DagConfig, Job } from './types.js';
+export declare function dag(config: DagConfig): Job;
+/** Run jobs strictly in order; stop at the first non-pass. Sugar over `dag`. */
+export declare function sequence(name: string, ...jobs: Job[]): Job;
+/** Run jobs concurrently; default fan-out is capped at 4. */
+export declare function parallel(name: string, jobs: Record<string, Job> | Job[], concurrency?: number): Job;

package/dist/core/decision.d.ts

@@ -0,0 +1,29 @@
+import type { Condition, Job, JobContext } from './types.js';
+export interface LastGateBriefOptions {
+    maxOutputChars?: number;
+}
+export interface ConfidenceConditionOptions {
+    /**
+     * Units used by `threshold`. `fraction` uses 0..1 (default 0.8), while
+     * `percent` uses 0..100 (default 80). Reported confidence stays normalized
+     * to 0..1 in both modes.
+     */
+    scale?: 'fraction' | 'percent';
+    threshold?: number;
+    token?: string;
+    /** Accept an exact, case-insensitive `n/a` token when the wrapped job passes. */
+    allowNa?: boolean;
+    /** Use the full work output as the condition reason when it is nonempty. */
+    reason?: 'concise' | 'output';
+}
+export interface LastDecisionLineOptions {
+    /**
+     * `closing` requires the token to be the final nonblank line. `last-match`
+     * permits trailing prose and selects the last line-anchored token.
+     */
+    mode?: 'closing' | 'last-match';
+}
+export declare function lastDecisionLine(text: string, token: string, values?: readonly string[], opts?: LastDecisionLineOptions): string | undefined;
+export declare function confidenceFromText(text: string, token?: string): number | undefined;
+export declare function confidenceCondition(job: Job, opts?: ConfidenceConditionOptions): Condition;
+export declare function lastGateBrief(ctx: Pick<JobContext, 'lastGate'>, opts?: LastGateBriefOptions): string;

package/dist/core/describe.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Job introspection. The builders register a `JobMeta` for the `Job` they return
+ * (and a short label for the conditions they build) in a side table, so a loop's
+ * shape can be read back without running it. A host can validate or describe a
+ * graph without executing it.
+ *
+ * Kept in `WeakMap`s rather than on the function objects, so the `Job`/`Condition`
+ * types stay plain functions and nothing downstream has to know meta exists.
+ */
+import type { Job, JobMeta, ConditionInput } from './types.js';
+/** Register a Job's shape and return the same Job (used inline at a builder's return). */
+export declare function setMeta<T extends object>(target: T, meta: JobMeta): T;
+/** Read a Job's registered shape, if it has one (a hand-written Job has none). */
+export declare function jobMeta(job: Job): JobMeta | undefined;
+/** Carry a Job's shape onto a wrapper that preserves its public behavior. */
+export declare function copyJobMeta<T extends object>(target: T, source: Job): T;
+/** Register a one-line label for a condition (used by the gate-describing path). */
+export declare function setLabel<T extends object>(cond: T, label: string): T;
+/** Flatten a gate input (`until`/`start`/`stopOn`) into one label per condition. */
+export declare function describeConditions(input?: ConditionInput): string[];
+/** Per-node shape `dag()` writes into its meta's `nodes` array. */
+export interface NodeMeta {
+    name: string;
+    needs?: string[];
+    desc?: string;
+    gate?: string;
+    isolate?: boolean;
+    optional?: boolean;
+    /** Condition labels for the node's `when` gate, when one is configured. */
+    when?: string[];
+    job?: JobMeta;
+}
+export type InspectionCommand = 'validate' | 'describe';
+export interface InspectionEnvelopeV1 {
+    schemaVersion: 1;
+    command: InspectionCommand;
+    file: string;
+    ok: true;
+    executed: false;
+    shape: JobShapeV1;
+}
+export type JobShapeV1 = {
+    kind: 'opaque';
+} | {
+    kind: string;
+    name?: string;
+    [producerField: string]: unknown;
+};
+export declare function jobShapeV1(meta: JobMeta | undefined): JobShapeV1;
+export declare function inspectionEnvelopeV1(command: InspectionCommand, file: string, meta: JobMeta | undefined): InspectionEnvelopeV1;
+/**
+ * Render a `JobMeta` tree to indented lines: the loop's name and cap, its gate
+ * and convergence actions, and its body / dag nodes recursively. A Job with no
+ * meta (hand-written) renders as a single opaque line.
+ */
+export declare function renderPlan(meta: JobMeta | undefined, indent?: string): string[];

package/dist/core/engine-meta.d.ts

@@ -0,0 +1,5 @@
+import type { AgentRequest, AgentResult } from '../engines/engine.js';
+import type { JobContext } from './types.js';
+export declare function attemptRequestMeta(ctx: JobContext, label: string): AgentRequest['attempt'];
+/** Surface a completed result's later transport failure through run logs. */
+export declare function logEngineTransportFailure(ctx: JobContext, result: Pick<AgentResult, 'transportFailure'>, env?: Record<string, string>): void;

package/dist/core/env-overlay.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Env-var pinning for a job subtree. `withEnv` wraps any `Job` so everything beneath
+ * it (gate commands, judge calls, and the subprocesses agent leaves spawn) sees the
+ * given variables, without mutating the global `process.env`.
+ *
+ * Precedence (most specific wins):
+ *   process.env
+ *     < ctx.environment.env    (the Environment interface's live-stack vars)
+ *     < ctx.envOverlay         (withEnv; nested wrappers merge inner-over-outer)
+ *     < explicit per-call env  (commandSucceeds `opts.env` / agentJob `config.env`)
+ *
+ * Non-goals: this is pinning, not a lifecycle. Unlike the Environment interface, an
+ * overlay has no `down()` and never touches the Environment handle. It cannot unset
+ * an inherited var: the process helper merges env over `process.env`, so an overlay only adds or
+ * shadows values.
+ */
+import type { Job, JobContext } from './types.js';
+/**
+ * Layer env sources least- to most-specific into one record for a subprocess.
+ * Returns `undefined` when every layer is absent or empty, so call sites keep
+ * their exact no-env behavior (`env: undefined`, never `{}`). Internal: the public
+ * surface is `withEnv`; per-call layers ride `opts.env` / `config.env`.
+ */
+export declare function mergeEnv(...layers: (Record<string, string> | undefined)[]): Record<string, string> | undefined;
+/**
+ * The layered env for one engine/subprocess call, least → most specific: the
+ * running environment's vars, then the `withEnv` overlay, then the per-call
+ * layer (`commandSucceeds` `opts.env` / `agentJob` `config.env`). The process helper (and
+ * the SDK adapter) merge the result over `process.env`, completing the
+ * precedence chain in the header. One helper so a new call site cannot forget
+ * a layer and silently break `withEnv`'s "everything beneath it" contract.
+ */
+export declare function resolveEnv(ctx: JobContext, perCall?: Record<string, string>): Record<string, string> | undefined;
+/** Pin env vars for `job` and everything beneath it (see the header above). */
+export declare function withEnv(overlay: Record<string, string>, job: Job): Job;

package/dist/core/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Structured, classified errors so the exit report can say what failed, where in
+ * the loop tree, and why, instead of dumping a stack.
+ */
+export type LoopErrorCode = 'ENGINE' | 'TIMEOUT' | 'ABORTED' | 'VALIDATION' | 'WRITE_BOUNDARY' | 'CONFIG' | 'BUDGET' | 'RATE_LIMIT' | 'QUOTA' | 'BODY' | 'UNKNOWN';
+export type LoopPhase = 'start' | 'body' | 'until' | 'stopOn' | 'review' | 'engine';
+export interface LoopErrorInit {
+    code: LoopErrorCode;
+    message: string;
+    phase?: LoopPhase;
+    path?: readonly string[];
+    iteration?: number;
+    cause?: unknown;
+    retryable?: boolean;
+    /** Suggested wait before retry, in ms (e.g. a `retry-after` header). */
+    retryAfterMs?: number;
+    /** When the limit resets, as epoch ms. The wait policy prefers this. */
+    resetAt?: number;
+}
+export declare class LoopError extends Error {
+    readonly code: LoopErrorCode;
+    readonly phase?: LoopPhase;
+    readonly path?: readonly string[];
+    readonly iteration?: number;
+    readonly retryable: boolean;
+    /** Suggested wait before retry, in ms (e.g. a `retry-after` header). */
+    readonly retryAfterMs?: number;
+    /** When the limit resets, as epoch ms. The wait policy prefers this. */
+    readonly resetAt?: number;
+    constructor(init: LoopErrorInit);
+    /** Wrap an arbitrary thrown value, preserving a `LoopError` as-is. */
+    static from(value: unknown, fallback: Omit<LoopErrorInit, 'message' | 'cause'>): LoopError;
+    toJSON(): {
+        name: string;
+        code: LoopErrorCode;
+        message: string;
+        phase: LoopPhase | undefined;
+        path: readonly string[] | undefined;
+        iteration: number | undefined;
+        retryable: boolean;
+        retryAfterMs: number | undefined;
+        resetAt: number | undefined;
+    };
+}
+export declare function isInfrastructureError(error: unknown): error is LoopError;
+export declare function isEngineExecutionError(error: unknown): error is LoopError;

package/dist/core/feedback.d.ts

@@ -0,0 +1,68 @@
+import type { ConditionInput, FeedbackActionSeverity, FeedbackDecision, FeedbackFinding, FeedbackSeverity, GraphPosition, Job, JobContext, Outcome, RevisionRequest, RevisionRerun } from './types.js';
+export type { FeedbackActionSeverity, FeedbackDecision, FeedbackFinding, FeedbackSeverity, RevisionRequest, RevisionRerun, } from './types.js';
+export interface RevisionRequestInput {
+    target?: string;
+    reason?: string;
+    findings?: FeedbackFinding[];
+    rerun?: RevisionRerun;
+    source?: string;
+    decision?: FeedbackDecision;
+}
+export declare function normalizeFeedbackSeverity(severity: FeedbackSeverity | undefined): FeedbackActionSeverity;
+export declare function isRequiredFeedbackSeverity(severity: FeedbackSeverity | undefined): boolean;
+export declare function revisionRequest(input: RevisionRequestInput, over?: Partial<Outcome>): Outcome;
+export declare function kickback(to: string, reason: string, over?: Partial<Outcome>): Outcome;
+/**
+ * The single accessor for an outcome's revision request. `Outcome.revision` is
+ * the one channel a producer sets (`revisionRequest`, `kickback`, `reviewPanel`,
+ * dag routing), so there is exactly one place to read it — no parallel `kickback`
+ * field or `data` copy to keep in sync.
+ */
+export declare function revisionFromOutcome(outcome: Outcome): RevisionRequest | undefined;
+export declare function feedbackBlock(outcome: Outcome): string;
+export declare function graphPositionBlock(graph: GraphPosition, reviewerGate?: string | null): string;
+type ReviewTarget = {
+    name?: string;
+    scope?: string;
+    /** Stable reviewer criteria version. Required when passes are persisted. */
+    cacheVersion?: string;
+    /** Workspace paths whose content can invalidate this reviewer's persisted pass. */
+    invalidateOn?: string[];
+} & ({
+    review: ConditionInput;
+} | {
+    job: Job;
+});
+export interface ReviewPanelConfig {
+    label?: string;
+    reviewers: ReviewTarget[];
+    /** Max reviewers running at once. Default 4. */
+    concurrency?: number;
+    /** Default `all`: every reviewer must pass. A number means k-of-n over all reviewers. */
+    pass?: 'all' | number;
+    /** Reuse only passing verdicts at or above this confidence while their evidence is unchanged. */
+    persistPasses?: {
+        minConfidence: number;
+    };
+    /**
+     * When set, findings scoped outside these surfaces are escalated and do not
+     * count against this panel's pass/fail decision. Unscoped findings stay
+     * actionable so a missing scope cannot bypass review.
+     */
+    actionableScopes?: string[];
+    /** When set, a failing panel emits a targeted revision request for dag routing. */
+    target?: string;
+    rerun?: RevisionRerun;
+}
+export declare function reviewPanel(config: ReviewPanelConfig): Job;
+export interface ReviewContextConfig {
+    diff?: boolean;
+    files?: string[];
+    tests?: boolean | {
+        command: string;
+        args?: string[];
+        cwd?: string;
+    };
+    maxChars?: number;
+}
+export declare function reviewContext(config: ReviewContextConfig): (ctx: JobContext, last: Outcome | undefined) => Promise<string>;