bareloop 0.3.0 → 0.5.0

package/src/ralph.js

@@ -143,6 +143,12 @@ const GAP_HEAD = 400, GAP_TAIL = 1500;
 // matches it says so with an explicit marker — silent truncation is the disease
 // this whole fix cures (F28), never a cure that truncates silently in turn.
 const GAP_KEEP_MAX_LINES = 50, GAP_KEEP_MAX_BYTES = 8192;
+// The exact phrase the trim announcement carries when kept failures are dropped
+// by the cap above. Exported so Layer R's detector (src/root.js) keys off the
+// SAME string the shell emits — a magic string on the reading side would drift
+// silently the day this wording changes (the blind-instrument class). Reference
+// only: the shell's behavior is unchanged, the label below is byte-identical.
+export const GAP_KEEP_TRIM_MARKER = 'more elided by the';
 
 /**
  * Bound an over-long close stream to a head sample + elided middle + tail. When
@@ -173,7 +179,7 @@ function boundGap(s, keepPattern) {
     bytes += line.length + 1;
   }
   if (!matched.length) return `${base}\n${tail}`; // pattern matched nothing — behave as the plain bound
-  const label = `kept failures matching /${keepPattern}/ (${matched.length}${trimmed ? `, ${trimmed} more elided by the ${GAP_KEEP_MAX_LINES}-line/${GAP_KEEP_MAX_BYTES}-byte cap` : ''})`;
+  const label = `kept failures matching /${keepPattern}/ (${matched.length}${trimmed ? `, ${trimmed} ${GAP_KEEP_TRIM_MARKER} ${GAP_KEEP_MAX_LINES}-line/${GAP_KEEP_MAX_BYTES}-byte cap` : ''})`;
   return `${base}\n── ${label} ──\n${matched.join('\n')}\n── end kept failures ──\n${tail}`;
 }
 
@@ -229,7 +235,15 @@ export const CLOSE_FAULTS = Object.freeze({
  *
  * @param {object} opts
  * @param {(iteration: number, gap?: string) => void|Promise<void>} opts.middle the emergent middle; never sees close/cap
- * @param {string[]} opts.close argv whose exit code is truth
+ * @param {string[]} [opts.close] argv whose exit code is truth (required unless `judge` is injected)
+ * @param {() => Promise<{verdict: string, gap?: string, detail?: string}>|{verdict: string, gap?: string, detail?: string}} [opts.judge]
+ *   Layer 2 (PRD v1.12 §4): the judge generalized to a SHELL-owned seam. When
+ *   present it replaces runClose for this loop — a plan STEP's micro-loop is
+ *   judged by the exit evaluator (declarative form checks), not a command. It
+ *   returns the same verdict vocabulary runClose renders, so the forbidden
+ *   zone, worker-crash routing (F32), and the cap taxonomy apply unchanged.
+ *   Injected by run.js only; inexpressible in any config or plan — the agent
+ *   never authors its judge any more than its close.
  * @param {number} opts.capRuns budget: max middle runs
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
  * @param {(s: string) => string} [opts.redact] source scrubber for close output
@@ -249,13 +263,15 @@ export const CLOSE_FAULTS = Object.freeze({
  *   with zero writes, a crash stays what it always was: an instrument stop.
  * @returns {Promise<'green'|'escalated'>}
  */
-export async function ralph({ middle, close, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }) {
-  emit('run-start', { capRuns, close: close.join(' ') });
+export async function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }) {
+  emit('run-start', { capRuns, close: judge ? 'judge:injected' : /** @type {string[]} */ (close).join(' ') });
   // The blind spot is NAMED, never hidden: with no judgment-rendered signal this
   // close cannot tell a crash from an honest red (they are byte-identical at the
   // exit-code seam), so the record says so out loud rather than passing the exit
-  // code off as trustworthy (PRD v1.11).
-  if (!judged) emit('close-unaudited', { close: close.join(' '), meaning: 'no judgment-rendered signal declared — a crash-at-load is indistinguishable from an honest red for this close' });
+  // code off as trustworthy (PRD v1.11). The judged-floor story belongs to
+  // CLOSES: an injected judge (Layer 2 exit evaluation) owns its own honesty
+  // reads, so the note would be noise there.
+  if (!judged && !judge) emit('close-unaudited', { close: /** @type {string[]} */ (close).join(' '), meaning: 'no judgment-rendered signal declared — a crash-at-load is indistinguishable from an honest red for this close' });
   const verdicts = [];
   let gap;
   for (let iteration = 1; iteration <= capRuns; iteration++) {
@@ -293,7 +309,9 @@ export async function ralph({ middle, close, capRuns, emit, redact, closeTimeout
       return 'escalated';
     }
     emit('middle-done', { iteration });
-    const v = runClose(close, redact, { timeoutMs: closeTimeoutMs ?? 120_000, cwd, expect, judged, gapKeep });
+    const v = judge
+      ? await judge()
+      : runClose(/** @type {string[]} */ (close), redact, { timeoutMs: closeTimeoutMs ?? 120_000, cwd, expect, judged, gapKeep });
     // Worker-crash attribution (F32, measured in F31: 4 of 7 battery rows). A crash is
     // still not a verdict (F17) — but a crash that FOLLOWS worker writes, on a run whose
     // precheck proved the close judged at baseline (run.js escalates a crash-at-precheck

package/src/root.js

@@ -0,0 +1,305 @@
+// Layer R — the root: the within-run ratchet (LAYERS.md item 2; design record
+// docs/plans/2026-07-19-layer-r-design.md). One state that survives attempts
+// inside ONE run so a never-green run stops repeating itself (F21). Role is
+// CONTINUITY ONLY — F39 measured that hand-delivered state buys no conversion;
+// the semantic converter is Layer 2's job, not this module's.
+//
+// Ownership: the SHELL authors the root, mechanically, from the arbiter's own
+// books — per-attempt write-sets (the gate audit, via the F32 workerWrites
+// seam) and the close's kept-failure lines. The worker authors nothing and
+// gains no verb; delivery is injection into the next attempt's prompt, so the
+// adaptlearn-F6 write-only-decoy class is structurally excluded.
+//
+// Engagement is FIXATION-GATED (RSI-LEARNINGS §3.3: the rejected-edit buffer's
+// lift is a fixation phenomenon and an honest null on a strong model when not
+// stuck — pay only when stuck). Content ESCALATES: first detection injects a
+// capped mechanical summary; a second consecutive detection injects the
+// worker's own prior failed edit content verbatim ("write something
+// STRUCTURALLY DIFFERENT" — the BA-14 mechanism, 50%→100% under fixation).
+// Both stages fire on DIFFERENT attempts, so every stuck episode yields a
+// per-stage read for the acceptance battery.
+//
+// Scope: within-run scratch, discarded at run end — NEVER across-run memory
+// (only a green mints that, and this module touches no inheritance channel).
+// Spine events carry counts and paths only, never content: verbatim edit text
+// is worker-authored and the spine is append-only (what a log captures, it
+// captures forever).
+
+// The shell's kept-failures trim announcement (ralph): its presence in a gap means
+// failures were dropped past the gap cap, so the visible kept lines are an
+// UNRELIABLE red-set for comparison. Imported (never re-spelled) so the detector
+// keys off the exact string the shell emits — a magic string here would drift.
+import { GAP_KEEP_TRIM_MARKER } from './ralph.js';
+
+/**
+ * Strip a trailing duration stamp from a kept-failure line. Real `node --test`
+ * spec-reporter lines are NEVER byte-stable across runs (`✖ multiplies
+ * (1.738ms)` vs `(1.637ms)` — POC 2026-07-19), so naive equality reads every
+ * attempt as "reds moved" and the detector never fires. COMPARISON-ONLY: the
+ * gap the worker sees is never rewritten.
+ * @param {string} line
+ */
+export const normalizeRedLine = (line) => line.replace(/ \(\d+(?:\.\d+)?m?s\)\s*$/, '');
+
+// Bounds — every trim is ANNOUNCED in the note (F28: silent truncation is the
+// disease; a cure that truncates silently is the same disease).
+/**
+ * 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`.
+ * @typedef {{content: string, trimmed: boolean, landed: boolean}} TeeEntry
+ */
+
+const TEE_CAP_BYTES = 2000;   // per-file content retained for the verbatim stage
+const VERBATIM_MAX_FILES = 3; // files surfaced per verbatim injection
+const SUMMARY_MAX_PATHS = 10; // paths named in the summary line
+
+/**
+ * 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 = (s) => s, writesInformative = true } = {}) {
+  const keepRe = gapKeep ? new RegExp(gapKeep, 'm') : null;
+  /**
+   * The comparable red-set, or null when it CANNOT be trusted — one clean UNKNOWN
+   * covering three cases, so the detector honestly degrades to write-overlap alone
+   * rather than making the strong "reds unchanged" claim off a blind instrument:
+   *   - no gapKeep pattern at all (no red-set instrument);
+   *   - a TRIMMED window (ralph dropped failures past the cap): failures beyond the
+   *     window can move while the visible lines stay identical (Finding 5);
+   *   - zero matches on a judged gap: an empty kept-set is UNKNOWN, not "zero
+   *     failures" — [] === [] would false-read as "reds unchanged" (Finding 2).
+   * @param {string} gap @returns {string[]|null} normalized kept lines, or null when untrustworthy
+   */
+  const keptSet = (gap) => {
+    if (!keepRe || gap.includes(GAP_KEEP_TRIM_MARKER)) return null;
+    const lines = [...new Set(gap.split('\n').filter((l) => keepRe.test(l)).map(normalizeRedLine))].sort();
+    return lines.length ? lines : null;
+  };
+
+  /** @type {{writes: string[], reds: string[]|null, tee: Map<string, TeeEntry>}[]} finalized attempts */
+  const attempts = [];
+  /** @type {Set<string>} cumulative audit write-set at the last observe */
+  let prevCumulative = new Set();
+  /** @type {Map<string, TeeEntry>} tee for the attempt currently running */
+  let tee = new Map();
+  /** @type {{path: string, entry: TeeEntry}|null} the write awaiting its outcome */
+  let pending = null;
+  let streak = 0;
+
+  /**
+   * Capture a write/edit's content as PENDING — staged against the gate verdict
+   * that has not been rendered yet (Finding 6). Scrub at CAPTURE, BEFORE
+   * truncating (repo doctrine: secrets scrub at the source, and staging IS the
+   * source — a staged secret must be scrubbed even if the write is later
+   * discarded). Every SECRET_PATTERN is a prefix+min-length shape (sk-…{16,}),
+   * so a secret straddling the cap would lose the bytes that make it match and a
+   * partial token would ride the note unredacted — redact the FULL content
+   * first, then cap the already-scrubbed string.
+   * @param {string} path @param {string} content
+   */
+  const stageWrite = (path, content) => {
+    const scrubbed = redact(content);
+    const trimmed = scrubbed.length > TEE_CAP_BYTES;
+    pending = { path, entry: { content: scrubbed.slice(0, TEE_CAP_BYTES), trimmed, landed: false } };
+  };
+
+  return {
+    stageWrite,
+
+    /**
+     * 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) {
+      if (pending) tee.set(pending.path, { ...pending.entry, landed });
+      pending = null;
+    },
+
+    /**
+     * 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() { pending = null; },
+
+    /**
+     * 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, content) {
+      stageWrite(path, content);
+      if (pending) tee.set(pending.path, { ...pending.entry, landed: true });
+      pending = null;
+    },
+
+    /**
+     * 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 }) {
+      const cumulative = new Set(writes);
+      if (!gap) { // first attempt: nothing judged yet, nothing to compare
+        prevCumulative = cumulative;
+        tee = new Map();
+        pending = null;
+        return null;
+      }
+      // finalize the attempt that just failed: its writes are the audit delta
+      const delta = [...cumulative].filter((p) => !prevCumulative.has(p));
+      // an edit to a file already written in an earlier attempt is not in the
+      // delta — the tee saw it, and a teed landed path IS this attempt's work
+      for (const p of tee.keys()) if (cumulative.has(p) && !delta.includes(p)) delta.push(p);
+      // `gap` is guaranteed truthy here (the `if (!gap) return` guard above handled
+      // the empty case); reds === null comes only from keptSet's own UNKNOWN logic.
+      attempts.push({ writes: delta, reds: keptSet(gap), tee });
+      // The detector only ever compares the last two finalized attempts, so older
+      // ones (and their teed content) are dead state — keep just the two (Finding 7).
+      if (attempts.length > 2) attempts.shift();
+      prevCumulative = cumulative;
+      tee = new Map();
+      // a stage whose verdict never arrived (the attempt ended mid-flight) is not
+      // a landed write and must not survive into the next attempt's tee
+      pending = null;
+
+      if (attempts.length < 2) return null;
+      const [prev, last] = attempts.slice(-2);
+      const overlap = last.writes.filter((p) => prev.writes.includes(p));
+      // Both UNKNOWN → no trustworthy red-set either side: write-overlap alone
+      // decides (writes-only mode, named below). One known and one UNKNOWN → the
+      // red-set is not provably the same, so it counts as MOVEMENT, never a fire
+      // (a real red-set followed by a crash/empty gap is new information, not
+      // repetition). Both known → the honest set comparison.
+      const redsSame = last.reds === null && prev.reds === null ? null
+        : last.reds === null || prev.reds === null ? false
+        : JSON.stringify(last.reds) === JSON.stringify(prev.reds);
+      // Finding 3: when writes carry no information (text mode — the one target is
+      // rewritten every attempt regardless of progress), write-overlap alone can
+      // never establish fixation; only a KNOWN-unmoved red-set can. So the
+      // degraded writes-only path (redsSame === null) is available to fire only
+      // when writes ARE informative (tool mode). With informative writes the prior
+      // behavior stands: overlap + reds-not-known-to-have-moved.
+      const redsGate = writesInformative ? redsSame !== false : redsSame === true;
+      const fixated = overlap.length > 0 && redsGate;
+      if (!fixated) { streak = 0; return null; }
+      streak += 1;
+
+      const stage = streak === 1 ? 'summary' : 'verbatim';
+      const mode = redsSame === null ? 'writes-only' : 'reds+writes';
+      const shownPaths = overlap.slice(0, SUMMARY_MAX_PATHS);
+      const morePaths = overlap.length - shownPaths.length;
+      const event = {
+        iteration, stage, mode, streak,
+        paths: shownPaths, ...(morePaths > 0 ? { pathsElided: morePaths } : {}),
+        redSetSize: last.reds ? last.reds.length : null,
+      };
+
+      // Finding 7: what the worker REACHED FOR fired the detector; what it
+      // ACHIEVED decides the wording. Only paths this attempt actually teed can
+      // answer the outcome question — a path known solely from the audit is
+      // unattributable, so it falls back to the neutral (landed) phrasing rather
+      // than guessing.
+      const attempted = overlap.filter((p) => last.tee.has(p));
+      const noneApplied = attempted.length > 0
+        && attempted.every((p) => !(/** @type {TeeEntry} */ (last.tee.get(p)).landed));
+
+      if (stage === 'summary') {
+        const redsClause = mode === 'reds+writes'
+          ? 'and the set of failing tests did not change at all'
+          : 'with no visible progress';
+        // The unapplied case is the MECHANICAL genre (F38: gaps that name a wall
+        // convert; semantic ones stall) — naming the missed anchor is strictly
+        // more actionable than "form a different hypothesis", because the
+        // hypothesis may have been right and only the anchor wrong.
+        const body = noneApplied
+          ? `Your last two attempts both tried to change ${shownPaths.join(', ')}`
+            + `${morePaths > 0 ? ` (and ${morePaths} more)` : ''} and NEITHER EDIT APPLIED — `
+            + 'the text you anchored on was not found in the file, so nothing changed. '
+            + 'Re-read the file and quote the exact text (whitespace and indentation included) before editing again.'
+          : `Your last two attempts both rewrote ${shownPaths.join(', ')}`
+            + `${morePaths > 0 ? ` (and ${morePaths} more)` : ''} ${redsClause}. `
+            + 'Do NOT retry the same change — form a DIFFERENT hypothesis before your next edit.';
+        return { stage, event, note: `RATCHET: you are repeating yourself. ${body}` };
+      }
+      // verbatim: surface the worker's own last content for the repeated paths —
+      // scrubbed, capped, every trim announced. Grouped by OUTCOME, because the
+      // two groups need opposite advice: content that landed and failed must not
+      // be written again, while content that never applied may have been the
+      // right change aimed at the wrong anchor — telling that worker to "write
+      // something structurally different" would steer it away from a correct fix.
+      const files = attempted.slice(0, VERBATIM_MAX_FILES);
+      const moreFiles = attempted.length - files.length;
+      /** @param {string} p */
+      const block = (p) => {
+        const t = /** @type {TeeEntry} */ (last.tee.get(p));
+        // t.content was already scrubbed by redact() in stageWrite before storage
+        // (Finding 6): re-redacting here is redundant work over already-masked text.
+        return `--- ${p}${t.trimmed ? ` (truncated to first ${TEE_CAP_BYTES} chars)` : ''} ---\n${t.content}`;
+      };
+      const landedFiles = files.filter((p) => /** @type {TeeEntry} */ (last.tee.get(p)).landed);
+      const unappliedFiles = files.filter((p) => !(/** @type {TeeEntry} */ (last.tee.get(p)).landed));
+      const sections = [];
+      if (landedFiles.length) {
+        sections.push('These are your OWN previous changes — they landed, and they did NOT fix the failing set:\n'
+          + landedFiles.map(block).join('\n')
+          + '\nDo not write these again. Write something STRUCTURALLY DIFFERENT, or change a different file.');
+      }
+      if (unappliedFiles.length) {
+        sections.push('This is text you tried to write, and it did NOT apply — the anchor was not found, '
+          + 'so the file is UNCHANGED and none of this is in it:\n'
+          + unappliedFiles.map(block).join('\n')
+          + '\nRe-read the file and copy the exact text you mean to replace, character for character, before editing again.');
+      }
+      return {
+        stage, event,
+        note: `RATCHET: you are STILL repeating yourself. ${sections.join('\n\n')}`
+          + (moreFiles > 0 ? `\n(and ${moreFiles} more repeated file${moreFiles > 1 ? 's' : ''}, elided)` : ''),
+      };
+    },
+  };
+}

package/src/run.js

@@ -13,6 +13,7 @@ import { redact } from 'bareguard';
 import { validateJob, jobSpecHash, checkApproval } from './job.js';
 import { validateConfig, LOOP_SHAPES, SLOTS, VERBS, globToPrefix, SECRET_PATTERNS, REMEMBER_KINDS } from './validate.js';
 import { interpret } from './interpret.js';
+import { runPlan } from './planrun.js';
 import { runClose, CLOSE_FAULTS } from './ralph.js';
 import { extractArtifact, priceOf } from './text.js';
 
@@ -183,59 +184,94 @@ async function openDraftPr({ workdir, branch, title, body, addPaths, exec }) {
  * 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 {any} opts.provider shell-owned LLM binding (never the config's; the Loop path)
+ * @param {(o: {policy: Function, onTurn?: Function, maxTurns: number, hasTools: boolean}) => any} [opts.nativeProvider]
+ *   native clipipe provider factory (BA-16), required for a `clipipe-subscription` plan-shape job —
+ *   threaded to runPlan, which builds one per worker (native tool mode when `hasTools`, else a
+ *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @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
- *        (shell-owned seam, same doctrine as the provider binding)
+ * @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 async function runJob(rawSpec, { approvals, workdir, target, provider, emit, capRuns = 3, shellCapUsd = 2, closeTimeoutMs, execCmd = defaultExec }) {
+export async function runJob(rawSpec, { approvals, workdir, target, provider, nativeProvider, emit, capRuns = 3, shellCapUsd = 2, closeTimeoutMs, execCmd = defaultExec, layerRoot = false }) {
+  // 0. the ledger's counters, declared FIRST so that every job-end — including
+  // the pre-token reds below — can state a real figure. An omitted `spentUsd` is
+  // not a zero: a consumer reads `undefined` and either crashes or launders it
+  // into $0 (F12's class, at the terminal record instead of mid-attempt).
+  let spentUsd = 0;
+  let unpriced = false;
+  // The money on the terminal record, and whether the money is EXACT. `spentUsd`
+  // is the accumulated sum of PRICED rounds ONLY — never an estimate derived
+  // from tokens or averages (cap-not-estimate). When any round came back
+  // unpriced (F6) that sum is a FLOOR, not the total, and `spendComplete: false`
+  // says so machine-readably instead of dressing a floor up as exact. Emitted on
+  // EVERY job-end (true when everything was priced) so no consumer ever has to
+  // branch on field presence.
+  const spend = () => ({ spentUsd, spendComplete: !unpriced });
   // 1. human-signs-always — before ANY provider call (N1 decision #1)
   if (!checkApproval(rawSpec, approvals)) {
-    emit('job-end', { outcome: 'unapproved-spec', detail: 'no approval record matches this exact spec version' });
+    emit('job-end', { outcome: 'unapproved-spec', detail: 'no approval record matches this exact spec version', ...spend() });
     return 'unapproved-spec';
   }
   const jv = validateJob(rawSpec, { shellCapUsd });
   if (!jv.ok) {
     for (const r of jv.reds) emit('job-red', r);
-    emit('job-end', { outcome: 'job-red' });
+    emit('job-end', { outcome: 'job-red', ...spend() });
     return 'job-red';
   }
   const job = /** @type {any} */ (jv.job);
+  // Layer 2: the two exclusive shapes (decision 6). A plan-shape spec (goal/
+  // verdictType/close/checks[]) has no steps[] and its steps are tool-mode by
+  // construction — the text-mode target rule below is a legacy-steps rule only.
+  const planShape = job.goal !== undefined;
   // Reds-before-tokens: a text-mode predicate step writes ONE artifact — with
   // no target it would burn a draft + a worker call and then crash inside the
   // middle as a misfiled interpreter-red. The spec is fine; the CALL is not.
-  if ((typeof target !== 'string' || !target)
+  if (!planShape && (typeof target !== 'string' || !target)
       && job.steps.some((/** @type {any} */ s) => s.close.type === 'predicate' && (s.mode ?? 'text') === 'text')) {
     emit('job-red', { code: 'missing-required', path: 'opts.target', detail: 'text-mode steps write ONE artifact — pass opts.target (reds-before-tokens)' });
-    emit('job-end', { outcome: 'job-red' });
+    emit('job-end', { outcome: 'job-red', ...spend() });
     return 'job-red';
   }
-  emit('job-start', { job: job.job, specHash: jobSpecHash(job), budgetUsd: job.budgetUsd, steps: job.steps.map((/** @type {any} */ s) => s.id) });
+  emit('job-start', {
+    job: job.job, specHash: jobSpecHash(job), budgetUsd: job.budgetUsd,
+    ...(planShape ? { shape: 'plan', goal: job.goal } : { steps: job.steps.map((/** @type {any} */ s) => s.id) }),
+  });
 
   // 2. known-answer smoke before tokens (A3: silent degradation throws nothing)
   const smoke = await primitiveSmoke(workdir);
   emit('primitive-smoke', smoke);
   if (!smoke.ok) {
     emit('escalation', { category: 'smoke-red', decisionReady: true, decision: `The ${smoke.primitive} primitive failed its known-answer check — no run verdict is trustworthy on a degraded primitive.`, options: ['fix the primitive/store', 'abandon the run'], detail: smoke.detail });
-    emit('job-end', { outcome: 'smoke-red' });
+    emit('job-end', { outcome: 'smoke-red', ...spend() });
     return 'smoke-red';
   }
 
   // 3. the ONE ledger. Unpriced is never free (F6): a null cost can't be
   // summed, so it flags a stop instead of accumulating $0.
-  let spentUsd = 0;
-  let unpriced = false;
   /** @param {number|null|undefined} c */
   const account = (c) => { if (typeof c === 'number' && Number.isFinite(c)) spentUsd += c; else unpriced = true; };
   /** @type {(type: string, data?: object) => object} */
@@ -256,10 +292,35 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
   };
   const pricingRed = () => {
     emit('escalation', { category: 'pricing-red', decisionReady: true, decision: 'A provider result carried no priced cost — the hard cap cannot govern spend it cannot see (unpriced is never free, F6).', options: ['bind a priced provider/model', 'abandon the run'], spentUsd });
-    emit('job-end', { outcome: 'pricing-red' });
+    emit('job-end', { outcome: 'pricing-red', ...spend() });
     return 'pricing-red';
   };
 
+  // ── Layer 2 dispatch: the plan flow (SCOUT → PLAN → EXECUTE → close) under
+  // the SAME approval gate, smoke, and ledger — runJob stays the one entry
+  // (N2 lock). runPlan emits every provider round as worker-round, so the
+  // metered emit above accounts the plan flow natively (F12); the job-end
+  // money contract is identical to the legacy path.
+  if (planShape) {
+    const outcome = await runPlan(job, {
+      workdir, provider, nativeProvider, emit: meter, capRuns, closeTimeoutMs,
+      remainingUsd: () => Math.min(shellCapUsd, job.budgetUsd - spentUsd),
+      isUnpriced: () => unpriced, // F6: let the plan flow bail in-flight, not just after it returns
+    });
+    if (unpriced) return pricingRed();
+    if (outcome.startsWith('step-red:')) {
+      emit('job-end', { outcome: 'step-red', step: outcome.slice('step-red:'.length), ...spend() });
+    } else if (outcome === 'provider-red') {
+      // F44: a transport-throw provider-red never returned a usage figure for the
+      // failed call, so the priced sum is a FLOOR, not the total — mirror the
+      // legacy providerRed(): spendComplete false, never overclaim an exact total.
+      emit('job-end', { outcome, ...spend(), spendComplete: false });
+    } else {
+      emit('job-end', { outcome, ...spend() });
+    }
+    return outcome;
+  }
+
   // 4. sealed drafting: one shot + one redraft, reds fed back, PRICED path
   // (through Loop, the same accounting the worker uses — never around it, F6)
   const drafter = new Loop({ provider, system: 'You draft workflow configs as pure JSON. Output only the JSON object.' });
@@ -294,7 +355,11 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
   };
   const providerRed = () => {
     emit('escalation', { category: 'provider-red', decisionReady: true, decision: 'The provider path threw before a result existed — spend for the failed call is unknown (F6), and no drafting verdict exists.', options: ['fix the provider binding', 'retry the run', 'abandon the run'], detail: transportRed, spentUsd });
-    emit('job-end', { outcome: 'provider-red' });
+    // A transport THROW never returned a usage figure, so the floor is NOT the total
+    // (F6): spendComplete must be false — spend()'s `!unpriced` only knows about priced
+    // rounds that came back unpriced, not a call that never returned at all. Leaving it
+    // true would have the job-end contradict the escalation's own "spend … is unknown".
+    emit('job-end', { outcome: 'provider-red', ...spend(), spendComplete: false });
     return 'provider-red';
   };
   const capNow = () => Math.min(shellCapUsd, job.budgetUsd - spentUsd);
@@ -345,7 +410,7 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
       // not on trial. Mirrors the worker path (interpret.js) and the human's options: the round
       // was metered, so this is a fault with a known cost, not a spend-unknown transport throw.
       emit('escalation', { category: 'provider-red', decisionReady: true, decision: 'The drafting round was truncated at the output cap (BA-6) — the API cut the config off mid-generation, so no valid config exists. Not the drafter\'s competence (never a config-red), and not silently retried.', options: ['raise the drafting cap and rerun', 'retry the run', 'abandon the run'], detail: draftTruncated, spentUsd });
-      emit('job-end', { outcome: 'provider-red' });
+      emit('job-end', { outcome: 'provider-red', ...spend() });
       return 'provider-red';
     }
     if (unpriced) return pricingRed();
@@ -355,11 +420,11 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
         // the honest stop is a cap story, never a config-red blaming the drafter
         emit('cap-halt', { category: 'cap-halt', meaning: 'not under cap — not "can\'t"', spentUsd, budgetUsd: job.budgetUsd });
         emit('escalation', { category: 'cap-halt', decisionReady: true, decision: `Drafting spend ($${spentUsd.toFixed(4)}) consumed the job budget ($${job.budgetUsd}) before a valid config existed.`, options: ['raise the job budget and rerun', 'abandon the run'], spentUsd });
-        emit('job-end', { outcome: 'cap-halt' });
+        emit('job-end', { outcome: 'cap-halt', ...spend() });
         return 'cap-halt';
       }
       for (const r of cv.reds) emit('config-red', r);
-      emit('job-end', { outcome: 'config-red' });
+      emit('job-end', { outcome: 'config-red', ...spend() });
       return 'config-red';
     }
     config = cv.config;
@@ -402,14 +467,14 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
       // baseline — loud, and never allowed to un-open a real PR
       if (pr.strandedOn) emit('workdir-red', { step: step.id, branch: pr.strandedOn, detail: 'the run could not return the checkout to its starting branch — the next run would build on this one' });
       emit('escalation', { category: 'hitl-close', decisionReady: true, step: step.id, prompt: step.close.prompt, spentUsd, decision: step.close.prompt, options: ['approve', 'reject'], pr: { url: pr.url, branch, error: pr.red?.detail ?? null } });
-      emit('job-end', { outcome: 'escalated', step: step.id, spentUsd });
+      emit('job-end', { outcome: 'escalated', step: step.id, ...spend() });
       return 'escalated'; // by design: the human acts outside the run, forever
     }
     if (step.close.type !== 'predicate') {
       // honest refusal: gold/rubric EXECUTION lands with the verdict classes
       // (N4); a fake verdict here would poison every contrast downstream
       emit('escalation', { category: 'close-unsupported', decisionReady: true, step: step.id, decision: `Step "${step.id}" has a ${step.close.type} close — N2 executes predicate and hitl closes only.`, options: ['restate the close as a predicate', 'wait for the verdict-classes rung'] });
-      emit('job-end', { outcome: 'close-unsupported', step: step.id });
+      emit('job-end', { outcome: 'close-unsupported', step: step.id, ...spend() });
       return 'close-unsupported';
     }
     emit('step-start', { step: step.id, remainingUsd: job.budgetUsd - spentUsd, spentUsd, mode: step.mode ?? 'text' });
@@ -436,7 +501,7 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
     const fault = Object.hasOwn(CLOSE_FAULTS, pre.verdict) ? CLOSE_FAULTS[pre.verdict] : undefined;
     if (fault) {
       emit('escalation', { category: fault.category, decisionReady: true, step: step.id, decision: fault.decision, options: fault.options, detail: pre.detail, spentUsd });
-      emit('job-end', { outcome: 'step-red', step: step.id, cause: fault.category, spentUsd });
+      emit('job-end', { outcome: 'step-red', step: step.id, cause: fault.category, ...spend() });
       return `step-red:${step.id}`;
     }
     // The precheck's gap goes to the worker as what it IS: the close's output on
@@ -458,21 +523,22 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
         // arbiter territory (PRD v1.11; F28 for gapKeep).
         mode: step.mode ?? 'text', tools: step.tools,
         closeExpect: step.close.expect, closeJudged: step.close.judged, closeGapKeep: step.close.gapKeep,
+        layerRoot,
       });
     } catch (e) {
       // ralph belts throws INSIDE the loop; this belts the interpreter's own
       // setup (gate.init, store ctor) — the spine must terminate, never dangle
       emit('escalation', { category: 'interpreter-red', decisionReady: true, step: step.id, decision: 'The interpreter broke outside the loop — no harness verdict is trustworthy until it is fixed.', options: ['fix the interpreter/run directory', 'abandon the run'], detail: String(/** @type {Error} */ (e)?.message ?? e), spentUsd });
-      emit('job-end', { outcome: 'step-red', step: step.id, cause: 'interpreter-red', spentUsd });
+      emit('job-end', { outcome: 'step-red', step: step.id, cause: 'interpreter-red', ...spend() });
       return `step-red:${step.id}`;
     }
     emit('step-end', { step: step.id, outcome, spentUsd });
     if (unpriced) return pricingRed();
     if (outcome !== 'green') {
-      emit('job-end', { outcome: 'step-red', step: step.id, cause: outcome, spentUsd });
+      emit('job-end', { outcome: 'step-red', step: step.id, cause: outcome, ...spend() });
       return `step-red:${step.id}`;
     }
   }
-  emit('job-end', { outcome: 'green', spentUsd });
+  emit('job-end', { outcome: 'green', ...spend() });
   return 'green';
 }