bareloop 0.8.0 → 0.9.0

package/types/declaredclose.d.ts

@@ -0,0 +1,174 @@
+/** @param {any} job @returns {boolean} */
+export function isDeclaredClose(job: any): boolean;
+/**
+ * The declaration's stages as the RUNNER's stage descriptors: the declared
+ * `{name, kind, params}` plus the arbiter's own `gapKeep`.
+ *
+ * `offer` and `needs` pass through untouched when a declaration carries them
+ * (v1's schema does not let one), so `checkMenu`'s derivation is unchanged.
+ * @param {any} closeDecl
+ * @returns {any[]|null} null when this is not a declaration
+ */
+export function declaredStages(closeDecl: any): any[] | null;
+/**
+ * Validate a `closeDecl` as a JOB SPEC field: the envelope (genre, language,
+ * notes) plus M2's full declaration validator underneath it.
+ *
+ * `listing` is what splits the two callers, and the split is deliberate:
+ *   - the JOB VALIDATOR has no repository, so it passes nothing and gets
+ *     `grounded: false` — every tree-independent rule runs, the path rule and
+ *     the scoped-job derivation do not;
+ *   - the RUNNER has the real seed, so it passes the real listing and gets
+ *     `grounded: true`. It runs this BEFORE any stage and before any token, so
+ *     the deferred half is proved rather than skipped.
+ * A caller that passes neither a listing nor `deferListing` gets M2's
+ * `listing-absent` red, unchanged: a validator handed nothing to check against
+ * must refuse, never report a declaration it never examined.
+ *
+ * THREE checks now ride on the listing, not two: the path rule, the scoped-job
+ * derivation, and the GROUNDING of a recorded `genreEnv` (a by-value comparison
+ * between two copies inside one hand-editable spec proves they agree, never that
+ * the arbiter wrote them — see `ungroundedGenreEnv`). All three are deferred at
+ * the job-spec gate and all three are re-run GROUNDED by the runner before any
+ * stage executes, so the deferral moves the check rather than dropping it. The
+ * grounded gates are `prepareSigning`'s gate 1b — where the signature is minted,
+ * so a forged env can never be signed in the first place — and `runPlan`'s
+ * pre-flight, which catches a spec edited after signing.
+ *
+ * `verdictType` is the class the USER picked, and it is REQUIRED here because
+ * the guard battery keys off it (PRD v1.57 §2): with no class in hand there is
+ * no battery, and M2 would be handed nothing to check D5 against. It arrives
+ * from the spec's sibling `verdictType` field on every caller — the job
+ * validator, the signing gate and the runner all hold the whole spec.
+ *
+ * @param {any} closeDecl
+ * @param {{at?: string, listing?: string[]|null, deferListing?: boolean,
+ *   catalogue?: Record<string, any>, verdictType?: string|null}} [opts]
+ * @returns {{ok: boolean, reds: Red[], closeDecl: any, grounded: boolean,
+ *   scoped: {scoped: boolean, via: string|null},
+ *   ceiling: {class: string, kind: string, stage: string|null, locked: boolean}|null}}
+ */
+export function validateCloseDecl(closeDecl: any, opts?: {
+    at?: string;
+    listing?: string[] | null;
+    deferListing?: boolean;
+    catalogue?: Record<string, any>;
+    verdictType?: string | null;
+}): {
+    ok: boolean;
+    reds: Red[];
+    closeDecl: any;
+    grounded: boolean;
+    scoped: {
+        scoped: boolean;
+        via: string | null;
+    };
+    ceiling: {
+        class: string;
+        kind: string;
+        stage: string | null;
+        locked: boolean;
+    } | null;
+};
+/**
+ * The genre's mandatory guard NAMES for a declaration — which stages are D5's
+ * guards and which are the job's own work. The seed-verdict read (D9.3) needs
+ * exactly this split: `changed-from-seed` is RED at its own seed by
+ * construction, so counting it as work would let a close with nothing to do
+ * pass the "something must be red at seed" gate.
+ * The battery keys off the CLASS the user picked (PRD v1.57 §2), so the class
+ * comes in beside the declaration. A class or a language with no battery hands
+ * back `[]` — this reads a split, it does not enforce one, and every caller
+ * reaches it only after `validateCloseDecl` has already refused both cases.
+ * @param {any} closeDecl @param {string} verdictType @returns {string[]}
+ */
+export function guardNames(closeDecl: any, verdictType: string): string[];
+/**
+ * Run a DECLARED close (or a check's chain out of one) and return `runClose`'s
+ * verdict shape, so every consumer downstream — the precheck, ralph's judge, the
+ * `CLOSE_FAULTS` routing, the trend reader, Layer R — is unchanged.
+ *
+ * The extras a declared close can honestly add ride alongside rather than
+ * replacing anything: `declared: true` marks the shape, `value`/`baseline` carry
+ * the deciding stage's own measurement, and `trendValue` is the ONE number the
+ * trend reader may compare (see the header for why a higher-is-better stage
+ * donates none).
+ *
+ * @param {any[]} stages declared stage descriptors, already validated
+ * @param {(s: string) => string} [redact] the scrub, applied at THIS boundary
+ * @param {{timeoutMs?: number, cwd?: string, seedRef?: string,
+ *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree'}} [opts]
+ * @returns {Promise<any>}
+ */
+export function runDeclaredStages(stages: any[], redact?: (s: string) => string, opts?: {
+    timeoutMs?: number;
+    cwd?: string;
+    seedRef?: string;
+    seedTrees?: any;
+    gapCap?: number;
+    maxBuffer?: number;
+    baselineMode?: "auto" | "worktree";
+}): Promise<any>;
+/**
+ * The trend reader's input for ONE close verdict, whichever executor produced
+ * it. A command close hands over its gap and `readGrade` scrapes stage and count
+ * out of the text; a declared close already KNOWS both, so it says them instead
+ * of round-tripping them through prose it would then have to parse back.
+ *
+ * Byte-identical to the previous call for a command close: `{ gap }`, with
+ * `stage`/`value` left UNDEFINED so `trend.record` falls through to `readGrade`
+ * exactly as before. Passing `stage: null` instead would silently disable that
+ * fallback — undefined and null are different answers here.
+ * @param {any} v a `runClose`-shaped verdict
+ * @returns {{gap?: string, stage?: string|null, value?: number|null}}
+ */
+export function closeGrade(v: any): {
+    gap?: string;
+    stage?: string | null;
+    value?: number | null;
+};
+/** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
+/** The genres a `closeDecl` may name. v1 admits exactly one (D13) — a genre
+ * classifier is designed the day there is a second genre to classify. */
+export const DECLARED_GENRES: readonly "TYPES"[];
+/**
+ * The exact field set of a `closeDecl` — anything else is a smuggle channel, the
+ * same rule `STAGE_FIELDS` enforces on a command stage.
+ *
+ * `genreEnv` is the ARBITER's own record of what it injected (M3's
+ * `applyGenreEnv`), and it is here because the injection has to survive being
+ * re-read. The flow applies the genre's variable to every env-capable stage
+ * AFTER the model's form passed; from then on every re-validation — signing
+ * (`prepareSigning`), the job validator (`src/job.js`), the runner
+ * (`src/planrun.js`) — sees that key sitting in `params.env` and cannot, from
+ * the stage alone, tell our injection from a model-authored guess. Recording it
+ * once, in the SIGNED envelope, is what makes the comparison an EQUALITY rather
+ * than a presence flag (the same move `checkGuards` makes for guard params), and
+ * it is why the model never gets to author it: `authorCloseForJob` composes this
+ * field from the flow's own applied map, never from model output. Its keys are
+ * constrained to the names the genre OWNS, so it can never become an environment
+ * channel of its own.
+ */
+export const CLOSE_DECL_FIELDS: readonly string[];
+/**
+ * The prefix M1 puts on EVERY gap line of a declared stage (its `ctx.gapKeep`).
+ * A literal, so the anchored pattern below is exact.
+ */
+export const DECLARED_GAP_PREFIX: "close: ";
+/** The `gapKeep` PATTERN for a declared stage, DERIVED from the prefix so the
+ * two can never drift. Layer R's red-set and `boundGap`'s keep-block both read
+ * it; because every declared line carries the prefix, it designates the stage's
+ * whole judged output rather than a hand-picked slice of it. */
+export const DECLARED_GAP_KEEP: string;
+/** The verdict class a DECLARED close may claim. Hard, and by CONSTRUCTION
+ * rather than by assertion: every live kind is a mechanical command whose
+ * measurement is the truth, and the two judgment kinds are locked out at the
+ * catalogue (M2) and absent from the executor (M1). Named as data so the job
+ * validator reads one hierarchy table rather than hard-coding a class. */
+export const DECLARED_CLOSE_CLASSES: readonly string[];
+export type Red = {
+    code: string;
+    path: string;
+    detail: string;
+    [k: string]: any;
+};

package/types/index.d.ts

@@ -4,9 +4,17 @@ export { runJob } from "./run.js";
 export { ralph, runClose, runStages, CLOSE_FAULTS } from "./ralph.js";
 export { globToPrefix, scanSecrets } from "./validate.js";
 export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
-export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from "./plan.js";
+export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS, closeStagesOf } from "./plan.js";
 export { snapshotScope, evalExits } from "./exits.js";
 export { BRIDGE_SCHEMA, validateBridge, deriveStatus, listingRow, loadGate, mintBridge, appendGreen, appendRed, loadBridge, loadRegistry, saveBridge, makeRegistry, registryExists } from "./bridges.js";
 export { renderListing, selectionPrompt } from "./selection.js";
 export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate } from "./reuse.js";
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from "./ledger.js";
+export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE } from "./workbranch.js";
+export { runDeclaredClose, runStage, seedRead, seedAtHead, seedListing, changedSet, makeSeedTrees, LIVE_KINDS, STOP_FAULTS, JUDGED_MARKER, EXIT_GREEN, EXIT_RED, EXIT_STOP } from "./kinds.js";
+export { validateDeclaration, normalizeDeclaration, KIND_CATALOGUE, CATALOGUE_KINDS, CATALOGUE_LIVE_KINDS, LOCKED_KINDS, TYPES_GENRE, TYPES_GENRE_TEMPLATE, GENRE_LANGUAGES, genreEnv, genreOwnedEnvNames, DIRECTIONS, BASELINES, MAX_STAGES, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, CLASS_BATTERIES, classGuards, closeCeiling } from "./authoring.js";
+export { runAuthorScout, buildSeedListing, seedFileList, classifySurvey, AUTHOR_SCOUT_VERBS, SCOUT_ATTEMPTS, SURVEY_CAUSES, SCOUT_RETRY_CAUSES } from "./authorscout.js";
+export { scrubRaw, RAW_PERSIST_MAX, RAW_TRIM_MARKER } from "./text.js";
+export { authorClose, authorPrompt, declarationSchema, makeLoopGenerate, MAX_REVISIONS, QUESTION_SETS, GREEN_QUESTIONS, CLASS_STATEMENTS, questionsFor, requiredAnswersFor } from "./authorflow.js";
+export { validateCloseDecl, runDeclaredStages, declaredStages, isDeclaredClose, guardNames, closeGrade, DECLARED_GENRES, DECLARED_GAP_PREFIX, DECLARED_GAP_KEEP, DECLARED_CLOSE_CLASSES, CLOSE_DECL_FIELDS } from "./declaredclose.js";
+export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS } from "./authorjob.js";

package/types/job.d.ts

@@ -93,6 +93,7 @@ export const CLASS_BY_CLOSE: Readonly<{
     gold: readonly string[];
     rubric: readonly string[];
     hitl: readonly string[];
+    declared: readonly string[];
 }>;
 export const GOLD_COMPARE: readonly string[];
 /** the tool grant menu (2b interview #1): read/grep/write, plus the two litectx

package/types/kinds.d.ts

@@ -0,0 +1,343 @@
+/**
+ * D8's seed, READ rather than typed: HEAD at run start. A close stores the
+ * counting rule and never the number (D12), so which commit the run is measured
+ * from is a fact about THIS run — recorded and shown, never carried in a signed
+ * spec where it would judge run 5 against run 1's tree.
+ *
+ * A fault is a named `stop`, never a fallback ref: measuring against the wrong
+ * baseline is the failure direction that reads as a clean tree.
+ * @param {string} workdir
+ * @returns {Promise<{stop: string, seedRef: null}|{stop: null, seedRef: string}>}
+ */
+export function seedAtHead(workdir: string): Promise<{
+    stop: string;
+    seedRef: null;
+} | {
+    stop: null;
+    seedRef: string;
+}>;
+/**
+ * The files that exist AT THE SEED COMMIT. Deliberately not `ls-files`, which
+ * reads the index and the working tree: this listing is what a declared path is
+ * judged against, and it must describe the tree the close measures from rather
+ * than whatever is lying around today.
+ *
+ * ONE spelling, here beside the other git reads (`src/authorscout.js`'s
+ * `seedFileList` delegates to it) — a second listing command is a second
+ * instrument, and the one that grades would be the one nobody validated.
+ * @param {string} workdir @param {string} seedRef
+ * @returns {Promise<{stop: string, files: null}|{stop: null, files: string[]}>}
+ */
+export function seedListing(workdir: string, seedRef: string): Promise<{
+    stop: string;
+    files: null;
+} | {
+    stop: null;
+    files: string[];
+}>;
+/**
+ * The two arbiter books, and the shape of each exclusion is the whole point.
+ *
+ * `.litectx/` is a PREFIX — everything beneath the store belongs to the
+ * arbiter. `gate-audit.jsonl` is an EXACT repo-relative path and never a
+ * basename or a pattern: the gate audit is written to
+ * `join(workdir, 'gate-audit.jsonl')` and nowhere else, so a worker-authored
+ * `src/gate-audit.jsonl` is NOT an arbiter book and must still count as work.
+ * Matching by basename would swallow it — and swallowing a worker's real
+ * write is the failure direction that reads as a clean tree.
+ * @param {string} rel a repo-relative POSIX path
+ * @returns {string|null} the book it belongs to, or null
+ */
+export function isArbiterBook(rel: string): string | null;
+/**
+ * Everything this run changed against the seed: the tracked diff PLUS
+ * untracked files (an untracked file has no diff — the case a naive
+ * `git diff` scan silently misses), minus the arbiter's own books.
+ * @param {string} workdir @param {string} seedRef
+ * @returns {Promise<{stop: string, fault: string}|{stop: null, paths: string[], tracked: string[], untracked: string[], excluded: {path: string, book: string}[]}>}
+ */
+export function changedSet(workdir: string, seedRef: string): Promise<{
+    stop: string;
+    fault: string;
+} | {
+    stop: null;
+    paths: string[];
+    tracked: string[];
+    untracked: string[];
+    excluded: {
+        path: string;
+        book: string;
+    }[];
+}>;
+/**
+ * The lines this run ADDED to one file. A tracked file's additions come from
+ * its own unified diff; an UNTRACKED file has no diff at all, so its ENTIRE
+ * body is added — the half of this primitive a diff-only scan misses.
+ * @param {string} workdir @param {string} seedRef @param {string} rel
+ * @param {{untracked?: boolean}} [o]
+ * @returns {Promise<{stop: string, fault: string}|{stop: null, lines: {n: number, text: string}[], note: string|null}>}
+ */
+export function addedLines(workdir: string, seedRef: string, rel: string, { untracked }?: {
+    untracked?: boolean;
+}): Promise<{
+    stop: string;
+    fault: string;
+} | {
+    stop: null;
+    lines: {
+        n: number;
+        text: string;
+    }[];
+    note: string | null;
+}>;
+/**
+ * Count a pattern's capture groups without running it against real input:
+ * `src + '|'` always matches the empty string, so the result array's length
+ * names the group count. Also the ONE place a declared regex is compiled at
+ * validation time, so a broken pattern reds before any process is spawned.
+ * @param {any} src
+ * @returns {{count: number, red: string|null}}
+ */
+export function regexGroups(src: any): {
+    count: number;
+    red: string | null;
+};
+/**
+ * THE normalisation of a `count-not-worse` parser (gate-1 amendment #5).
+ * The declaration validator and this executor both call it, so there is
+ * exactly one spelling of what a parser MEANS — two normalisers that
+ * disagree are two instruments, and the one that grades is the one nobody
+ * validated.
+ *
+ *     value = Σ over terms of  sign × (first | sum of that term's captures,
+ *                                      inside that term's region)
+ *
+ * Backwards compatible by construction: the short form
+ * `{lineMatch, capture?}` resolves to exactly one term with
+ * `sign +1, aggregate "first", region "whole-output"`, which is the
+ * pre-amendment semantics unchanged.
+ *
+ * Never throws — reds come back in the shipped `{ok, reds, ...}` shape.
+ * @param {any} parser @param {string} [at] path prefix for reds
+ * @returns {{ok: boolean, reds: Red[], terms: any[]|null}}
+ */
+export function normalizeParser(parser: any, at?: string): {
+    ok: boolean;
+    reds: Red[];
+    terms: any[] | null;
+};
+/**
+ * Read ONE number out of a command's output, as signed arithmetic over
+ * normalised terms.
+ *
+ * The zero-match split is contract (a), not a convenience:
+ *   - `sum` over zero matches is a COUNTED zero. The region was searched and
+ *     nothing was there; that is legitimately 0.
+ *   - `first` over zero matches is UNKNOWN — the number was never reported —
+ *     and unknown is an instrument stop, never a defaulted 0 (F6).
+ *   - a region whose anchor matches nothing was never LOCATED: stop.
+ * The scope filter runs per OUTPUT LINE, before aggregation, and both its
+ * drop count and its unattributable count are ANNOUNCED: a line naming no
+ * path is KEPT (no filter can exclude what it cannot locate) and the notes
+ * say so, rather than the number quietly meaning something else.
+ *
+ * `preScopeMatches` is reported alongside the reading because a POST-scope
+ * count cannot answer "did the tool run at all". It tallies (term, line) pairs
+ * that matched BEFORE the filter judged them — kept, unattributable and dropped
+ * alike — and it is the only evidence of liveness a caller has once the scope
+ * has removed the whole population. It is never the number being read.
+ * @param {string} output @param {any[]} terms normalised terms
+ * Every stop here is `crashed` in the arbiter's vocabulary — the command RAN,
+ * came back, and the number could not be read out of it. Nothing in this
+ * function can observe a spawn failure, a timeout or a signal, so it never
+ * claims one.
+ * @param {{scope?: any, workdir?: string}} [o]
+ * @returns {{stop: string, fault: string, notes?: string[]}|{stop: null, value: number, breakdown: any[], notes: string[], preScopeMatches: number}}
+ */
+export function parseValue(output: string, terms: any[], { scope, workdir }?: {
+    scope?: any;
+    workdir?: string;
+}): {
+    stop: string;
+    fault: string;
+    notes?: string[];
+} | {
+    stop: null;
+    value: number;
+    breakdown: any[];
+    notes: string[];
+    preScopeMatches: number;
+};
+/**
+ * A caller-scoped holder for detached seed worktrees. Scoped rather than
+ * module-global on purpose: a global cache in a published library leaks
+ * worktrees into whatever process imported it, and nothing would ever remove
+ * them. `seedRead`/`runClose` create one, share it across stages (so a
+ * multi-stage close pays for one checkout), and remove it in a `finally`.
+ * @returns {SeedTrees}
+ */
+export function makeSeedTrees(): SeedTrees;
+/**
+ * Run ONE declared stage against a workdir at a seed.
+ *
+ * It never throws. An unexpected throw inside a kind — a malformed parameter
+ * the validator did not catch, an unreachable path — is an INSTRUMENT STOP,
+ * not a red: that is the casualty-vs-evidence split at its narrowest, and
+ * the direction that matters, because a crash rendered as a red is fake
+ * evidence about the worker.
+ * @param {any} stage `{name, kind, params}`
+ * @param {Ctx} ctx
+ * @returns {Promise<StageResult>}
+ */
+export function runStage(stage: any, ctx: Ctx): Promise<StageResult>;
+/**
+ * D12's seed-verdict read: run EVERY declared stage at the seed, regardless
+ * of reds, and hand back one row per stage.
+ *
+ * Not first-red-wins, and the reason is structural rather than a preference:
+ * every shipped close opens with `changed-from-seed`, which is RED at its own
+ * seed by construction (nothing has changed yet), so a first-red-wins seed
+ * read measures exactly one stage and mints no baseline for any other. The
+ * baseline every `baseline: "seed"` stage is later graded against comes from
+ * here, so a stage that never ran is a stage with no bar.
+ * @param {any} declaration `{stages: [...]}`
+ * @param {Ctx} ctx
+ * @returns {Promise<StageResult[]>}
+ */
+export function seedRead(declaration: any, ctx: Ctx): Promise<StageResult[]>;
+/**
+ * The GRADING path: stages in declared order, FIRST RED WINS. The deciding
+ * stage names the verdict; everything after it is `not-reached` and is
+ * reported as such rather than as a green nobody ran.
+ *
+ * An instrument stop ends the close UNJUDGED — the run has no verdict to
+ * carry, which is the whole point of keeping a casualty out of the evidence.
+ *
+ * NAMED `runDeclaredClose`, not `runClose` (M4's export-surface decision): the
+ * arbiter's shell already ships a public `runClose(argv, redact, opts)` that
+ * adopters import, and the two take different things and mean different things
+ * — one runs a DECLARATION, the other an argv. Renaming the shipped one to make
+ * room would break a documented adopter contract for nothing; the new name says
+ * exactly what differs. `src/declaredclose.js` is what bridges the two shapes.
+ * @param {any} declaration @param {Ctx} ctx
+ * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop', exitCode: number, judged: boolean, firstRed: string|null, stages: StageResult[]}>}
+ */
+export function runDeclaredClose(declaration: any, ctx: Ctx): Promise<{
+    verdict: "green" | "red" | "instrument-stop";
+    exitCode: number;
+    judged: boolean;
+    firstRed: string | null;
+    stages: StageResult[];
+}>;
+/** the close's two judgment exits — a stage's verdict, in the shape the
+ * hand-written closes already spoke (exit code is truth) */
+export const EXIT_GREEN: 0;
+export const EXIT_RED: 1;
+/** contract (a): the instrument-stop exit. `judged` is withheld with it. */
+export const EXIT_STOP: 97;
+/** The judgment-rendered marker a rendered close prints, for ralph's
+ * `runClose` judged floor (src/ralph.js). It rides EVERY real judgment, green or red,
+ * and NEVER a stop — this module reports the same fact as the boolean
+ * `judged`; the marker exists so a renderer and the floor agree on one
+ * spelling. */
+export const JUDGED_MARKER: "judged=1";
+/** contract (b): the per-stage gap ceiling. Trims are announced, never silent. */
+export const GAP_LINE_CAP: 40;
+/**
+ * The exact phrase this executor's trim announcement carries. Exported for the
+ * same reason ralph exports `GAP_KEEP_TRIM_MARKER`: Layer R's detector must be
+ * able to see that a gap window was TRIMMED, because failures beyond the window
+ * can move while the visible lines stay identical — and an undetected trim makes
+ * the detector claim "reds unchanged" off an instrument that was blind (F43,
+ * finding 5). A magic string on the reading side would drift the day this
+ * wording changes; the renderer below is its only other use.
+ */
+export const GAP_TRIM_MARKER: "gap trimmed:";
+/** used when neither the stage nor the ctx names a bound. A stage that could
+ * run forever is not a red — it is a stop, and something must decide when. */
+export const DEFAULT_TIMEOUT_MS: 300000;
+/** PER STREAM, like the arbiter's own close runner. An overrun truncates the
+ * output mid-summary, so any number read out of it is unknown, not zero. */
+export const MAX_BUFFER: number;
+/** an untracked file larger than this is not scanned line-by-line; the skip
+ * is ANNOUNCED in the gap rather than passing as a clean scan */
+export const MAX_SCAN_BYTES: number;
+/** ceiling on a parser's term list — a runaway parser is a red, not a bill */
+export const MAX_TERMS: 8;
+/**
+ * WHICH KIND of instrument stop, in the ARBITER's own four-row vocabulary
+ * (`CLOSE_FAULTS`, src/ralph.js). Stamped at the site that OBSERVES the fault —
+ * never sniffed out of the stop's prose downstream (the typed-attribution rule:
+ * a `lib`/fault field is stamped at the throw site, and prose is a fallback for
+ * pre-typed spines only).
+ *
+ * The rows are kept apart for the reason `CLOSE_FAULTS` keeps them apart: they
+ * are DIFFERENT HUMAN DECISIONS. "raise the close timeout", "fix the argv" and
+ * "re-run, it was OOM-killed" are three answers, and a declared close that
+ * pooled all three into `failed` would hand every one of them the same option
+ * list. `failed` is the default because "the close cannot run" is the safe
+ * reading of a fault nothing else claimed.
+ */
+export const STOP_FAULTS: Readonly<{
+    /** the stage cannot RUN at all: spawn failure, a missing seed commit, git refusing */
+    FAILED: "failed";
+    /** it ran and never finished judging */
+    TIMED_OUT: "timed-out";
+    /** it died by signal — no opinion was ever rendered */
+    KILLED: "killed";
+    /** it ran, came back, and judged nothing: unreadable output, a blown buffer,
+     * a number that was never reported, a parser that does not normalise */
+    CRASHED: "crashed";
+}>;
+export const AGGREGATES: readonly string[];
+export const SIGNS: readonly number[];
+/** every kind this executor implements. `judged-floor` / `human-confirms`
+ * are catalogue entries and are deliberately absent here: declaring one is
+ * counted demand (the request-red path), and reaching one at runtime is a
+ * stop — never a red, and never a silent pass. */
+export const LIVE_KINDS: readonly string[];
+export type Red = {
+    code: string;
+    path: string;
+    detail: string;
+};
+/**
+ * The arbiter's half of a stage run. Every field here is operator/runner
+ * territory: a declaration parameterises kinds, never the contracts.
+ */
+export type Ctx = {
+    workdir: string;
+    seedRef: string;
+    gapKeep: string;
+    timeoutMsDefault?: number;
+    baselineMode?: "auto" | "worktree";
+    gapCap?: number;
+    maxBuffer?: number;
+    seedTrees?: SeedTrees;
+};
+export type StageResult = {
+    verdict: "green" | "red" | "instrument-stop" | "not-reached";
+    exitCode: number | null;
+    value: number | null;
+    baseline: number | null;
+    baselineSource: string | null;
+    gapLines: string[];
+    judged: boolean;
+    stage: string | null;
+    kind: string | null;
+    detail: Record<string, any>;
+};
+export type SeedTrees = {
+    ensure: (workdir: string, seedRef: string) => Promise<{
+        stop: string;
+        fault: string;
+    } | {
+        stop: null;
+        dir: string;
+    }>;
+    cleanup: () => Promise<{
+        ok: boolean;
+        leaked: string[];
+        detail: string | null;
+    }>;
+};

package/types/plan.d.ts

@@ -48,6 +48,24 @@ export function legalScopes(writeScope: string[], dirs?: string[], cap?: number)
  * @returns {any[]|null} the stage list, or null when the close names no command
  */
 export function stageClose(close: any): any[] | null;
+/**
+ * THE ONE STAGING, one level up: a job's close stages, from EITHER of the two
+ * fields a spec may carry.
+ *
+ * `stageClose` reads a command close; `declaredStages` reads an authored
+ * declaration (M4). A spec declares exactly one of them — the job validator reds
+ * `close-duplicated` on both — so this is a selection, never a merge.
+ *
+ * Every consumer calls THIS rather than `stageClose` directly, for the reason
+ * W4 wrote `stageClose` in the first place: the drafting prompt, the plan
+ * validator, the runner, the bridge registry and the reuse envelope must all see
+ * the same stage list, and a consumer that reads only `close` sees a declared
+ * job as having no close at all — an empty check menu offered to a drafter whose
+ * plan the validator would then red for referencing a stage nobody offered.
+ * @param {any} job the job spec, any shape
+ * @returns {any[]|null} the stage list, or null when the job names no close
+ */
+export function closeStagesOf(job: any): any[] | null;
 /** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red */
 /**
  * Validate an agent-authored plan (`schema: "plan-v1"`) against the SIGNED

package/types/planrun.d.ts

@@ -252,12 +252,18 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   default; a caller supplies this to drive time deterministically (the same seam `createClock`
  *   already exposes — a run's terminal cannot otherwise be exercised without waiting out a cap
  *   whose floor is one close timeout).
+ * @param {string|null} [opts.resumeBranch] RESUME — the WORK BRANCH the killed leg
+ *   recorded on its own spine (`readResume`'s `restart.branch`, off the `work-branch`
+ *   event). With it the resume returns to the branch its own work is sitting on; without
+ *   it the deterministic name would collide with that very branch and the collision walk
+ *   would mint a `-2` beside the progress the resume exists to keep. Absent is the cold
+ *   path. A recorded branch that no longer exists is a STOP, never a fresh start.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
- *   'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' | 'step-stalled' |
- *   `step-red:<id>`
+ *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
+ *   'step-stalled' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -289,6 +295,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     } | null | undefined;
     spendComplete?: (() => boolean) | undefined;
     now?: (() => number) | undefined;
+    resumeBranch?: string | null | undefined;
 }): Promise<string>;
 export type CategorizedError = Error & {
     category?: string;

package/types/ralph.d.ts

@@ -272,6 +272,7 @@ export const CLOSE_ENV_DENY: Readonly<{
     prefixes: readonly string[];
     shape: RegExp;
 }>;
+export function stageGap(name: string, gap: string): string;
 export const GAP_KEEP_TRIM_MARKER: "more elided by the";
 /**
  * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the

package/types/run.d.ts

@@ -83,6 +83,13 @@
  *   RUN's ("unlimited replanning launders thrash as adaptation"). It also rides onto this
  *   run's `job-start` as `priorReplans`, the declared-fold precedent `priorSpentUsd`
  *   already sets, so a resume OF a resume folds once. Absent is the cold path.
+ * @param {string|null} [opts.resumeBranch] RESUME — the WORK BRANCH the killed attempt
+ *   created and recorded on its own spine (`readResume`'s `restart.branch`). The branch
+ *   name is DERIVED from the signed spec and is therefore identical on every leg, so
+ *   without this the restart would collide with its own predecessor's branch and the
+ *   collision walk would mint a `-2` beside the work the resume exists to continue. The
+ *   fold's precedent exactly: the chain's state is DECLARED, never re-derived. Forwarded
+ *   verbatim to the plan flow; absent is the cold path.
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -92,10 +99,10 @@
  *        binding.)
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
- *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' | 'provider-red' |
+ *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -124,6 +131,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         count?: number;
         grantUsed?: boolean;
     } | null | undefined;
+    resumeBranch?: string | null | undefined;
     layerRoot?: boolean | undefined;
 }): Promise<string>;
 export type Red = {