bareloop 0.2.0 → 0.4.0

package/src/validate.js

@@ -15,6 +15,20 @@ export const LOOP_SHAPES = Object.freeze(['refine', 'plan']);
 export const SLOTS = Object.freeze(['before-attempt', 'after-red', 'on-green']);
 export const VERBS = Object.freeze(['recall', 'compress', 'stash', 'remember']);
 const TOP_FIELDS = ['schema', 'loop', 'memory', 'hooks', 'gate', 'escalation'];
+// Unknown-field guard, PER SECTION — not just at the top (F17). The arbiter
+// split is guarded "both directions by inexpressibility": the drafted config
+// must be UNABLE to say certain things. A guard that stops at the top level
+// does not deliver that — `gate: { judged: {...} }` (the close's own honesty
+// check) validated green, as would `gate.maxCostUsd`. Nothing consumed those
+// keys, so nothing broke; the guarantee is that nothing ever can. Hook ops are
+// guarded separately by VERB_PARAMS.
+const SECTION_FIELDS = Object.freeze({
+  loop: ['shape', 'maxIterations'],
+  memory: ['store', 'recall', 'compressLevel'],
+  'memory.recall': ['k', 'kinds'],
+  gate: ['budgetUsd', 'writeScope'],
+  escalation: ['mode'],
+});
 const MAX_OPS_PER_SLOT = 2;
 
 // per-verb parameter contracts: name → check(value) (op field itself excluded).
@@ -22,7 +36,7 @@ const MAX_OPS_PER_SLOT = 2;
 // (the set remember() itself validates against — adaptlearn F5's drift lesson:
 // the export you bind can be wider than the function you call), minus doc:
 // the doc/upload axis stays gated out deliberately.
-const REMEMBER_KINDS = WRITE_KINDS.filter((k) => k !== 'doc');
+export const REMEMBER_KINDS = WRITE_KINDS.filter((k) => k !== 'doc'); // exported: the drafting prompt advertises THIS menu (one source, no drift)
 const VERB_PARAMS = {
   recall: { k: (v) => Number.isInteger(v) && v >= 1 && v <= 20, kinds: isKinds },
   compress: { level: (v) => COMPRESS_LEVELS.includes(v) },
@@ -134,6 +148,24 @@ export const SECRET_PATTERNS = [
 ];
 const SECRET_RE = new RegExp(SECRET_PATTERNS.map((r) => r.source).join('|'));
 
+/**
+ * Scan a RAW text stream (a spine file, a close's output, a transcript) for
+ * known secret shapes and return the literal matches. The ONE spelling of the
+ * text-side scan, for the same reason SECRET_PATTERNS is the ONE inventory: a
+ * hand-rolled copy that misses a shape is a leak on the very output it guards
+ * (seven copies of this expression lived in scripts/ before it landed here).
+ * `sweepSecretLiterals` is the config-tree twin — same shapes, tree walk.
+ * Never throws; returns [] for a missing stream.
+ * @param {unknown} raw
+ * @returns {string[]} every match, in stream order per pattern
+ */
+export function scanSecrets(raw) {
+  const text = String(raw ?? '');
+  // a fresh global clone per call: a shared /g regex carries lastIndex between
+  // calls and would skip matches on the next stream
+  return SECRET_PATTERNS.flatMap((re) => text.match(new RegExp(re.source, `${re.flags.replace('g', '')}g`)) ?? []);
+}
+
 /**
  * Red every string in a config tree that carries a known secret-token shape.
  * @param {any} root
@@ -287,6 +319,15 @@ export function validateConfig(input, { shellCapUsd = 2, jobWriteScope } = {}) {
     }
   }
 
+  // 4b. inexpressibility, at every depth the arbiter can be reached from
+  for (const [section, allowed] of Object.entries(SECTION_FIELDS)) {
+    const obj = section === 'memory.recall' ? memory.recall : c[section];
+    if (!isObj(obj)) continue;
+    for (const key of Object.keys(obj)) {
+      if (!allowed.includes(key)) red('unknown-field', `${section}.${key}`);
+    }
+  }
+
   // 5. secrets sweep — same guard as the job spec (the agent-authored document
   // is the riskier one; a green config is a ledger fact and inherits forever)
   sweepSecretLiterals(c, red);

package/types/extract.d.ts

@@ -5,7 +5,9 @@
  * @param {object} opts.provider a bareagent provider — SHELL-owned, sealed
  * @param {string[]|null} opts.priorRules the lineage's current rules, if any
  * @param {string[]} [opts.revisionDiff] changed config paths, when the run recovered mid-run
- * @returns {Promise<{rules: string[]|null, valid: boolean, reds: Array<object>, costUsd: number, raw: string}>}
+ * @returns {Promise<{rules: string[]|null, valid: boolean, reds: Array<object>, costUsd: number|null, raw: string}>}
+ *   costUsd is null when the spend could not be priced — the explicit-unknown
+ *   signal (F6: unpriced is never free); callers must not coerce it to 0
  */
 export function extractRules({ config, provider, priorRules, revisionDiff }: {
     config: object;
@@ -16,7 +18,7 @@ export function extractRules({ config, provider, priorRules, revisionDiff }: {
     rules: string[] | null;
     valid: boolean;
     reds: Array<object>;
-    costUsd: number;
+    costUsd: number | null;
     raw: string;
 }>;
 export const MAX_RULES: 5;

package/types/index.d.ts

@@ -1,6 +1,8 @@
 export { makeSpine } from "./spine.js";
-export { ralph, runClose } from "./ralph.js";
-export { validateConfig, diffPaths, globToPrefix, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
-export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS } from "./job.js";
+export { runJob } from "./run.js";
+export { ralph, runClose, CLOSE_FAULTS } from "./ralph.js";
+export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS } from "./job.js";
 export { interpret, STALL_REDS } from "./interpret.js";
 export { extractRules, MAX_RULES, MAX_RULE_CHARS } from "./extract.js";
+export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from "./ledger.js";

package/types/interpret.d.ts

@@ -4,13 +4,26 @@
  * @param {object|string} configRaw schema v1 config (object or raw JSON text)
  * @param {object} opts
  * @param {string} opts.task implement instruction shown to the worker
- * @param {string} opts.target absolute path the artifact is written to
+ * @param {string} [opts.target] absolute path the artifact is written to —
+ *        required in text mode; unused in tool mode (the worker writes through
+ *        the gated tools, wherever the fence allows)
  * @param {string[]} opts.close argv whose exit code is truth (shell-owned)
+ * @param {number} [opts.closeExpect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.closeJudged] the signed spec's
+ *   judgment-rendered signal — proof the close actually judged something before
+ *   its exit code is believed in EITHER direction (PRD v1.11; the drafted config
+ *   cannot express it, and must not: it is the arbiter's own honesty check)
+ * @param {string} [opts.closeGapKeep] the signed spec's kept-failures pattern (F28):
+ *   close-output lines matching it survive the gap bound, so a large suite's
+ *   `not ok` names reach the worker instead of being elided into "N fail" — also
+ *   arbiter territory, inexpressible in the drafted config
  * @param {string} opts.workdir run directory (litectx root, gate audit, scope base)
  * @param {number} opts.capRuns shell iteration budget; the config may tighten via loop.maxIterations, never exceed
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {object} opts.provider a bareagent provider — SHELL-owned binding (adaptlearn F8: an unsealed binding is a gate bypass)
- * @param {number} [opts.shellCapUsd=2] the shell's USD cap; config budgetUsd is clamped by validation
+ * @param {number} [opts.shellCapUsd=2] the shell's USD cap; a config budgetUsd above it REDS at validation (bounds — no silent clamping)
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap, threaded to the shell
+ *        (shell/operator territory — the workflow config cannot express it)
  * @param {string[]} [opts.jobWriteScope] the job spec's outer write fence (operator law,
  *        job-v1) — enforced HERE, the one choke point where a config becomes a Gate:
  *        every workflow scope must fit inside it (scope-escape config-red otherwise),
@@ -22,17 +35,40 @@
  *        (arbiter-touch / cap-touch revision-reds otherwise; the run continues on the old
  *        config). Revisor spend rides the run's own gate handlers — same budget axis as
  *        the worker.
+ * @param {string} [opts.closeState] the close's CURRENT output on the tree as it stands
+ *        (the shell's pre-token close check, F13) — shown to the first attempt only, and
+ *        never framed as an attempt: the worker cannot run the close itself (`run` is a
+ *        locked verb), so without this it is asked to fix a failure it cannot see
+ * @param {'text'|'tools'} [opts.mode] middle mode (2b): 'text' (default) writes the ONE
+ *        target from the response artifact; 'tools' gives the worker Gate-governed file
+ *        tools — SPEC-side territory (the step declares it; the config cannot express it)
+ * @param {boolean} [opts.layerRoot=false] Layer R (the within-run ratchet, src/root.js):
+ *        shell-assembled fixation detection over the run's own books, injecting an
+ *        escalating summary→verbatim note when consecutive attempts rewrite the same
+ *        files without moving the reds. Inert when the worker is not stuck (RSI §3.3).
+ *        Defaults OFF (decided 2026-07-21): fixation is extinct on every current job
+ *        (F41), so ON is unproven — the field read defers to Layer 2. `true` is the
+ *        ON/experimental arm; never a worker-visible knob
+ * @param {string[]} [opts.tools] the spec's tool grant (subset of read|grep|write,
+ *        job-v1 validated); defaults to the full menu in tool mode
  * @returns {Promise<'green'|'escalated'|'config-red'>}
  */
-export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor }: {
+export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor, closeTimeoutMs, mode, tools, closeState, closeExpect, closeJudged, closeGapKeep, layerRoot }: {
     task: string;
-    target: string;
+    target?: string | undefined;
     close: string[];
+    closeExpect?: number | undefined;
+    closeJudged?: {
+        pattern: string;
+        min: number;
+    } | undefined;
+    closeGapKeep?: string | undefined;
     workdir: string;
     capRuns: number;
     emit: (type: string, data?: object) => object;
     provider: object;
     shellCapUsd?: number | undefined;
+    closeTimeoutMs?: number | undefined;
     jobWriteScope?: string[] | undefined;
     revisor?: ((o: {
         config: object;
@@ -44,14 +80,19 @@ export function interpret(configRaw: object | string, { task, target, close, wor
         parseError?: string | null;
         costUsd?: number;
     }>) | undefined;
+    closeState?: string | undefined;
+    mode?: "text" | "tools" | undefined;
+    layerRoot?: boolean | undefined;
+    tools?: string[] | undefined;
 }): Promise<"green" | "escalated" | "config-red">;
-/** @typedef {Error & {category?: string}} CategorizedError the failure map's carrier: ralph relays by `category` */
+/** @typedef {Error & {category?: string, lib?: string}} CategorizedError the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose) */
 export const STALL_REDS: 2;
 /**
- * the failure map's carrier: ralph relays by `category`
+ * the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose)
  */
 export type CategorizedError = Error & {
     category?: string;
+    lib?: string;
 };
 /**
  * litectx recall hit — body present only with `{body: true}`

package/types/job.d.ts

@@ -1,4 +1,4 @@
-/** @typedef {{code: string, path: string, detail?: string}} Red */
+/** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red — `verb` rides request-reds as structured data (the ledger keys on it, never on prose) */
 /**
  * Validate an operator-owned job spec (`schema: "job-v1"`). Never throws on
  * JSON text or plain parsed data — the ingest contract; a live object with a
@@ -44,14 +44,45 @@ export const CLASS_BY_CLOSE: Readonly<{
     hitl: readonly string[];
 }>;
 export const GOLD_COMPARE: readonly string[];
+/** step middle modes (2b): text = single-target artifact; tools = Gate-governed file tools */
+export const STEP_MODES: readonly string[];
+/** the tool grant menu (2b interview #1): read/grep/write, plus the two litectx
+ * RETRIEVAL verbs (F19) — `run` stays locked-but-listed; a spec requesting it
+ * reds, and that red IS the request-red evidence admission waits on (curation
+ * doctrine, PRD F2).
+ *
+ * `recall`/`get` are READ-ONLY BY CONSTRUCTION, not by promise: `recall` returns
+ * pointers (path/symbol/line-range, no bodies) and `get` trades ONE pointer for
+ * ONE chunk — it refuses any range that is not a chunk boundary, so it cannot be
+ * widened into a whole-file read, and it is content-hash gated (a drifted file
+ * throws rather than serving a stale body). Admitting them does NOT weaken the
+ * `run` lock: the worker still cannot execute anything, so it still cannot run
+ * its own close (the arbiter). F19: `shell_read` starts at byte ZERO and cannot
+ * seek, so a pointer was INERT — the worker paged 1.37 MB of source through
+ * context to reach 8 lines. The ranged read is the pager.
+ *
+ * `edit` (BA-13, bare-agent 0.29.0) is the anchored exact-once replace — a
+ * WRITE-class verb judged by the SAME writeScope fence as `write` (bareguard
+ * action type 'edit'). Admitted because whole-file rewrite is measurably
+ * unreliable at size (F31: 4 of 5 big-file whole-writes broke the tree) and
+ * taxes output tokens ∝ file size. It admits no execution either. */
+export const TOOL_MENU: readonly string[];
+/** locked-but-listed tools: real capabilities deliberately outside the grant
+ * menu. Requesting one is a DISTINCT `request-red` (module 4) — the ledger
+ * counts admission demand, and a generic invalid-value would bury it as a typo. */
+export const LOCKED_TOOLS: readonly string[];
 export const CADENCE_UNITS: readonly string[];
 export const PROVIDERS: readonly string[];
 /** V3 environment label: declared keys only — every field is a lineage-key
  * candidate at N3. `provider` is part of the key by definition (top-level,
  * not duplicated here). */
 export const CONDITION_KEYS: readonly string[];
+/**
+ * — `verb` rides request-reds as structured data (the ledger keys on it, never on prose)
+ */
 export type Red = {
     code: string;
     path: string;
     detail?: string;
+    verb?: string;
 };

package/types/ledger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Classify one spine's events into incident occurrences (the design table in
+ * bareloop vocabulary). Deliberate exclusions — bare cap-halt (a budget story),
+ * close-verdict reds and artifact-red (worker stories, the §5b line), gate-red
+ * (governance working as intended), pr-red (operator environment, not a suite
+ * lib), smoke-red escalations (already counted via primitive-smoke), hitl-close
+ * and close-unsupported (by design) — classify to nothing.
+ * @param {any[]} events one spine's parsed events, in seq order
+ * @param {{spine?: string}} [opts] spine id stamped into samples
+ * @returns {Occurrence[]}
+ */
+export function classifyIncidents(events: any[], { spine }?: {
+    spine?: string;
+}): Occurrence[];
+/**
+ * Fold ledger rows to current state — latest cumulative count per key, latest
+ * human-appended status riding on top (default 'open'). A status row for a key
+ * with no incident row still folds (occurrences 0): a human note must never
+ * silently vanish.
+ * @param {any[]} rows parsed ledger rows, in seq order
+ * @returns {Record<string, FoldEntry>}
+ */
+export function foldLedger(rows: any[]): Record<string, FoldEntry>;
+/**
+ * Compute the append-only delta rows: group occurrences by key; a row is due
+ * only when the key is new or its corpus total grew past the folded count.
+ * detail is first-seen (the fold's wins); samples are the corpus's first few.
+ * @param {Record<string, FoldEntry>} fold current ledger state
+ * @param {Occurrence[]} occurrences the FULL corpus's occurrences
+ * @returns {object[]} lib-incident rows, unstamped (no seq/ts)
+ */
+export function ledgerDeltas(fold: Record<string, FoldEntry>, occurrences: Occurrence[]): object[];
+/**
+ * The collector: read the ledger, classify the FULL spine corpus, append the
+ * deltas (spine conventions: type first, ts stamped last, seq continuing
+ * monotonically across appends). Idempotent over the same corpus; the CLI
+ * wrapping this lands at N5, the panel reads the same file at N6.
+ * @param {{ledgerFile: string, spineFiles: string[]}} o spineFiles: the corpus
+ *   (pass ALL of it each time — counts are totals, not increments)
+ * @returns {{appended: object[], fold: Record<string, FoldEntry>}}
+ */
+export function updateLedger({ ledgerFile, spineFiles }: {
+    ledgerFile: string;
+    spineFiles: string[];
+}): {
+    appended: object[];
+    fold: Record<string, FoldEntry>;
+};
+/** severity order, worst-first (the fold's display order; frequency ranks within) */
+export const LEDGER_CLASSES: readonly string[];
+export type Sample = {
+    spine: string;
+    seq: number;
+};
+export type Occurrence = {
+    key: string;
+    class: string;
+    lib: string;
+    verb: string;
+    sig: string;
+    detail: string;
+    sample: Sample;
+};
+export type FoldEntry = {
+    key: string;
+    lib: string;
+    verb: string;
+    class: string;
+    sig: string;
+    detail: string;
+    occurrences: number;
+    samples: Sample[];
+    suggestedAsk: string;
+    status: string;
+    ref?: string;
+};

package/types/ralph.d.ts

@@ -1,6 +1,34 @@
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
- * 0 → satisfied; nonzero → needs_revision (gap fed back); spawn error → failed (terminal).
+ * `expect` → satisfied; any other exit → needs_revision (gap fed back).
+ *
+ * THE FORBIDDEN ZONE (PRD v1.11, F17; adaptlearn F25/V10). The two clean bands
+ * are green (exit == expect, judgment rendered) and red (exit != expect,
+ * judgment rendered). Every other outcome rendered NO JUDGMENT and is therefore
+ * NOT A VERDICT — it gets its own name and escalates; coercing one into a
+ * verdict IS the instrument fault (law #8 generalized):
+ *   - `failed`    — the close cannot RUN (spawn error).             → broken-close
+ *   - `timed-out` — it ran and never finished judging.              → close-timeout
+ *   - `killed`    — it died by signal (status null, no spawn error). → close-killed
+ *   - `crashed`   — it ran, exited, and judged nothing.             → close-crashed
+ * `timed-out` is split OUT of `failed` deliberately: "raise the timeout" and
+ * "fix the argv" are different human decisions, so pooling them erases the
+ * decision information the escalation exists to carry.
+ *
+ * `judged` is the judgment-rendered signal, and it is the hard one. Exit code
+ * ALONE cannot separate a crash-at-load from an honest red — they are
+ * byte-identical at this seam, and against `node --test` so are the test counts
+ * (node synthesizes ONE failing test for the file that crashed, so a crash
+ * reports `tests 1 / fail 1`, exactly like a one-assertion failure). So the
+ * signal cannot be "zero judged"; it must be a FLOOR against a declared
+ * baseline: litectx runs ~390 tests, and a run claiming it judged 1 did not
+ * judge. `judged.pattern` extracts one integer from the close's own (redacted)
+ * output; below `judged.min` the close crashed, WHATEVER its exit code says —
+ * and that check runs on the GREEN side too: a close that exits 0 having judged
+ * nothing is a confident fake green, the only real failure there is (law #8).
+ * `judged` is OPTIONAL — a linter or a hitl close may have no count to give —
+ * and its absence stamps `unaudited: true` so the blind spot is NAMED on the
+ * record rather than passed off as a trustworthy exit code.
  *
  * `redact` scrubs the close's own output at the SOURCE — before the gap becomes
  * a spine event or a worker prompt — so a secret a checked command echoes
@@ -10,24 +38,49 @@
  * primitive (bareguard's, wired by the interpreter), never an emergent
  * component — so V4 holds. The shell's canonical emission IS the redacted text;
  * a benign gap is returned byte-identical (default: identity).
+ * `cwd` is where the close RUNS, and it is load-bearing (F8): a close is a
+ * command in a repository — `npm test`, `make check` — and every one of them is
+ * cwd-relative. Run it anywhere but the workdir and the arbiter judges the wrong
+ * tree: exit-code-is-truth silently becomes exit-code-of-some-other-repo-is-truth.
+ * The default (the runner's own cwd) exists only for callers with an absolute
+ * close; the runner and the interpreter always pass the workdir.
+ *
+ * `gapKeep` (F28) is a regex SOURCE whose matching lines are PRESERVED through
+ * the gap bound in addition to the head/tail sample: a large TAP suite prints
+ * its `not ok` lines in the middle of the stream, exactly where `boundGap`
+ * elides — so the failing-test NAMES (the causal input the worker navigates on)
+ * were deleted in transit and the worker was told "5 fail" and never WHICH. It
+ * is arbiter territory like the rest here: the drafted config cannot express it.
+ *
  * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
  * @param {(s: string) => string} [redact] source scrubber; identity by default
+ * @param {{ timeoutMs?: number, cwd?: string, expect?: number, judged?: {pattern: string, min: number}, gapKeep?: string }} [opts]
+ *   close wall-clock cap (operator-set via the runner, never the config's — the
+ *   agent must not author its arbiter's clock), the directory the close runs in
+ *   (the workdir — the tree it is judging), the exit code the SIGNED spec calls
+ *   success, the judgment-rendered signal, and the kept-failures pattern. All
+ *   five are arbiter territory: the drafted workflow config cannot express any.
+ * @returns {{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
+ *   gap?: string, exitCode?: number, signal?: string, detail?: string,
+ *   judgedCount?: number|null, unaudited?: boolean}}
  */
-export function runClose(close: string[], redact?: (s: string) => string): {
-    verdict: string;
-    detail: string;
-    gap?: undefined;
-    exitCode?: undefined;
-} | {
-    verdict: string;
-    detail?: undefined;
-    gap?: undefined;
-    exitCode?: undefined;
-} | {
-    verdict: string;
-    gap: string;
-    exitCode: number | null;
-    detail?: undefined;
+export function runClose(close: string[], redact?: (s: string) => string, { timeoutMs, cwd, expect, judged, gapKeep }?: {
+    timeoutMs?: number;
+    cwd?: string;
+    expect?: number;
+    judged?: {
+        pattern: string;
+        min: number;
+    };
+    gapKeep?: string;
+}): {
+    verdict: "satisfied" | "needs_revision" | "failed" | "timed-out" | "killed" | "crashed";
+    gap?: string;
+    exitCode?: number;
+    signal?: string;
+    detail?: string;
+    judgedCount?: number | null;
+    unaudited?: boolean;
 };
 /**
  * The loop: `while close-red and under-cap: run the middle`. Stops at first
@@ -50,12 +103,53 @@ export function runClose(close: string[], redact?: (s: string) => string): {
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
  * @param {(s: string) => string} [opts.redact] source scrubber for close output
  *   (secrets never enter the spine); injected so the shell stays stdlib-only
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell/operator
+ *   territory — the workflow config cannot express it)
+ * @param {string} [opts.cwd] the directory every close runs in — the tree it is
+ *   judging (F8: a cwd-relative close run elsewhere judges the wrong repository)
+ * @param {number} [opts.expect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.judged] the judgment-rendered signal
+ * @param {string} [opts.gapKeep] kept-failures pattern (F28): matching close-output
+ *   lines survive the gap bound so a large suite's `not ok` names reach the worker
+ * @param {() => string[]} [opts.workerWrites] the crash-attribution instrument (F32):
+ *   answers "which files has the WORKER written so far this run?" — the runner wires
+ *   it to the gate audit's allow-decision writes. Injected like `redact` so the shell
+ *   stays stdlib-only and dumb; consulted ONLY at a crashed verdict. With no seam, or
+ *   with zero writes, a crash stays what it always was: an instrument stop.
  * @returns {Promise<'green'|'escalated'>}
  */
-export function ralph({ middle, close, capRuns, emit, redact }: {
+export function ralph({ middle, close, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
     middle: (iteration: number, gap?: string) => void | Promise<void>;
     close: string[];
     capRuns: number;
     emit: (type: string, data?: object) => object;
     redact?: ((s: string) => string) | undefined;
+    closeTimeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    expect?: number | undefined;
+    judged?: {
+        pattern: string;
+        min: number;
+    } | undefined;
+    gapKeep?: string | undefined;
+    workerWrites?: (() => string[]) | undefined;
 }): Promise<"green" | "escalated">;
+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
+ * close rendered NO JUDGMENT — so it is not a verdict, it never feeds a gap
+ * back, and it is never retried. They are kept SEPARATE on purpose: pooling
+ * them would erase the decision information the escalation exists to carry —
+ * "raise the timeout", "fix the argv", and "re-run, it was OOM-killed" are
+ * three different human answers.
+ * Exported because the RUNNER's close-first precheck runs the same arbiter
+ * before any tokens: two maps would be two instruments, and two instruments
+ * disagreeing about the same outcome is the fault this whole addendum exists
+ * to close.
+ * @type {Record<string, {category: string, decision: string, options: string[]}>}
+ */
+export const CLOSE_FAULTS: Record<string, {
+    category: string;
+    decision: string;
+    options: string[];
+}>;

package/types/root.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The root collector. One per run; state dies with the run.
+ *
+ * Call order (wired by the interpreter's middle):
+ *   observe({iteration: 1, writes})            → null (nothing to compare)
+ *   stageWrite(path, content)                  → stage, before the tool runs
+ *   settleWrite(landed) | discardWrite()       → the outcome, after it ran
+ *   noteWrite(path, content)                   → stage+settle, text mode (which
+ *                                                writes before it reports)
+ *   observe({iteration: N, gap, writes})       → null | {stage, note, event}
+ * `writes` is the CUMULATIVE allow-decision write/edit path list from the gate
+ * audit (the F32 instrument); the per-attempt set is the delta between calls —
+ * so a gate-DENIED write is never counted (the tool never ran at all).
+ *
+ * Finding 7 — the two axes, deliberately NOT merged. An allow-decision records
+ * what the worker REACHED FOR, which is the right instrument for "is it
+ * repeating itself"; whether those bytes reached the file is a different
+ * question, and only the note (a claim about file contents) needs it. Collapsing
+ * them either way is a bug: settling the note on the allow makes it lie, and
+ * running the detector off the file makes it blind to a worker re-firing an
+ * identical edit whose anchor never matches — measured null on every attempt.
+ *
+ * @param {{gapKeep?: string, redact?: (s: string) => string, writesInformative?: boolean}} [opts]
+ *   the signed spec's kept-failures pattern (the red-set source; without it the
+ *   detector degrades to write-overlap alone and the event says so), the shell's
+ *   secret scrubber (verbatim content is scrubbed before it rides a prompt), and
+ *   `writesInformative` (Finding 3, default true): whether the per-attempt
+ *   write-set carries information. In TOOL mode the worker CHOOSES which files to
+ *   write, so re-writing the same file is a real repetition signal; in TEXT mode
+ *   the one target is rewritten every attempt by construction, so write-overlap
+ *   is constant-true and carries none — with no red-set to compare, the detector
+ *   cannot tell repetition from progress and must stay inert (it would otherwise
+ *   steer a progressing worker off course, violating "inert when not stuck").
+ */
+export function createRoot({ gapKeep, redact, writesInformative }?: {
+    gapKeep?: string;
+    redact?: (s: string) => string;
+    writesInformative?: boolean;
+}): {
+    stageWrite: (path: string, content: string) => void;
+    /**
+     * The staged write RAN — record what it actually did (Finding 7). Retained
+     * either way: an attempted-but-unapplied edit is still the worker reaching
+     * for the same file, which is what the detector measures, and dropping it
+     * here would blind the ratchet to the purest fixation there is (a worker
+     * re-firing an identical edit whose anchor never matches — measured null on
+     * every attempt under a tree-diff detector, 2026-07-20). Only the NOTE's
+     * wording turns on `landed`. Last write per path wins (the tree's final
+     * state for that attempt is what failed the close).
+     * @param {boolean} landed whether the content is now in the file
+     */
+    settleWrite(landed: boolean): void;
+    /**
+     * The staged write was DENIED or HALTED: it is not in the file, so it must
+     * never be surfaced as "your own change that landed". Drops the stage and
+     * leaves whatever DID land for that path untouched.
+     */
+    discardWrite(): void;
+    /**
+     * Stage and commit in one call — the post-allow write site (text mode
+     * gate-checks and writes before it calls this, so the verdict is already in).
+     * @param {string} path @param {string} content
+     */
+    noteWrite(path: string, content: string): void;
+    /**
+     * Called at the START of attempt `iteration`, with the PREVIOUS attempt's
+     * gap. Finalizes that attempt from the books, runs the detector, and
+     * returns the injection for the attempt about to run — or null (inert).
+     * @param {{iteration: number, gap?: string, writes: string[]}} o
+     * @returns {null | {stage: 'summary'|'verbatim', note: string, event: object}}
+     */
+    observe({ iteration, gap, writes }: {
+        iteration: number;
+        gap?: string;
+        writes: string[];
+    }): null | {
+        stage: "summary" | "verbatim";
+        note: string;
+        event: object;
+    };
+};
+export function normalizeRedLine(line: string): string;
+/**
+ * A teed write: the content the worker emitted, plus whether it actually reached
+ * the file. `landed` is the OUTCOME axis (Finding 7) — the gate's allow is an
+ * intent record written before the tool runs, and a shell_edit whose anchor
+ * misses returns a refusal RESULT with the file untouched (bare-agent
+ * tools/shell.js:190). A note that says "these are your changes" is a claim
+ * about the file's contents and must be true, so it reads this flag, never the
+ * audit. The DETECTOR deliberately does not: see `observe`.
+ */
+export type TeeEntry = {
+    content: string;
+    trimmed: boolean;
+    landed: boolean;
+};

package/types/run.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Run an approved job end to end: approval gate → primitive smoke → sequential
+ * per-step interpret loops under the one ledger → the hitl step opens the draft
+ * PR (deterministic git, never model tools) and becomes the decision-ready
+ * escalation. Every predicate step runs its close FIRST (close-first skip,
+ * resume model): already-green skips the step for zero tokens as a distinct
+ * spine record, so a stopped run reruns from where it died — the workdir plus
+ * the closes are the checkpoint. The sealed config draft (one shot + one
+ * redraft) is deferred to the first step that actually needs a worker; a clean
+ * rerun pays zero provider calls.
+ *
+ * N2 bounds (honest, documented): text-mode steps write a single `target`
+ * artifact; tool-mode steps (2b) work multi-file through the gated shell tools,
+ * granted per step by the SPEC (mode/tools — the drafted config cannot express
+ * either); `gold`/`rubric` closes refuse `close-unsupported` (execution lands
+ * with the verdict classes, N4); the pricing-red halt lands at the step
+ * boundary — the Gate still caps within a step, but an unpriced result cannot
+ * be summed, so the run stops rather than counting it $0 (F6).
+ *
+ * EVERY terminal `job-end` states the money: `spentUsd` (the sum of PRICED
+ * rounds only — never an estimate; a real 0 on the pre-token reds) plus
+ * `spendComplete`, false when any round came back unpriced and the figure is
+ * therefore a FLOOR, not the total. Both are always present, so a consumer
+ * never branches on field presence nor launders a blank into $0.
+ *
+ * @param {object|string} rawSpec the job spec (job-v1), text or parsed
+ * @param {object} opts
+ * @param {unknown} opts.approvals `{ specHash, signer, ts }` records (from OUTSIDE the spec)
+ * @param {string} opts.workdir the run directory (the fence's root)
+ * @param {string} [opts.target] the step artifact path (text-mode steps; unused by tool-mode steps)
+ * @param {any} opts.provider shell-owned LLM binding (never the config's)
+ * @param {(type: string, data?: object) => object} opts.emit spine emitter
+ * @param {number} [opts.capRuns] shell-owned per-step iteration cap
+ * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
+ * @param {ExecCmd} [opts.execCmd] process runner for the hitl PR mechanics
+ * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
+ *        territory, threaded to every predicate step's interpreter. Defaults OFF
+ *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
+ *        ON has never won its own A/B — the acceptance read defers to Layer 2 (or
+ *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
+ *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
+ *        binding.)
+ * @returns {Promise<string>} outcome: 'green' | 'escalated' | 'unapproved-spec' |
+ *   'job-red' | 'smoke-red' | 'config-red' | 'pricing-red' | 'provider-red' |
+ *   'cap-halt' | 'close-unsupported' | `step-red:<id>`
+ */
+export function runJob(rawSpec: object | string, { approvals, workdir, target, provider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd, layerRoot }: {
+    approvals: unknown;
+    workdir: string;
+    target?: string | undefined;
+    provider: any;
+    emit: (type: string, data?: object) => object;
+    capRuns?: number | undefined;
+    shellCapUsd?: number | undefined;
+    closeTimeoutMs?: number | undefined;
+    execCmd?: ExecCmd | undefined;
+    layerRoot?: boolean | undefined;
+}): Promise<string>;
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};
+export type ExecCmd = (argv: string[], opts?: {
+    cwd?: string;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};