bareloop 0.4.0 → 0.5.1

package/src/ralph.js

@@ -235,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
@@ -255,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++) {
@@ -299,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/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';
 
@@ -194,7 +195,11 @@ async function openDraftPr({ workdir, branch, title, body, addPaths, exec }) {
  * @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
@@ -211,7 +216,7 @@ async function openDraftPr({ workdir, branch, title, body, addPaths, exec }) {
  *   '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, layerRoot = false }) {
+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
@@ -238,16 +243,23 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
     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', ...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);
@@ -284,6 +296,31 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
     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, layerRoot,
+      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.' });

package/types/exits.d.ts

@@ -0,0 +1,51 @@
+/** @typedef {{ type: string, pass: boolean, detail?: string, fault?: string }} ExitResult
+ * `fault` present means the INSTRUMENT could not judge (unwired snapshot/seam,
+ * a check in runClose's forbidden zone) — it carries the runClose verdict name
+ * ('failed'|'timed-out'|'killed'|'crashed') so the micro-loop escalates through
+ * the same CLOSE_FAULTS taxonomy instead of feeding a fake gap to the worker.
+ * A plain pass:false with no fault is honest worker feedback. */
+/**
+ * Snapshot the file state under a scope prefix — the "before" side of
+ * `tree-changed`. Content hashes, not mtimes: only real bytes count as
+ * outcome. A scope directory that does not exist yet snapshots empty (the
+ * step creating it IS the change). Never throws on a missing dir.
+ * @param {string} dir absolute workdir (the run directory)
+ * @param {string} scope a validated scope glob (e.g. `tests/**`)
+ * @returns {Promise<Map<string, string>>} relative path → sha256
+ */
+export function snapshotScope(dir: string, scope: string): Promise<Map<string, string>>;
+/**
+ * Evaluate a step's exits — AND-only (decision 8): the step passes iff EVERY
+ * listed exit passes. All exits are evaluated (never short-circuit): the gap
+ * must name every wall, not the first one hit.
+ * @param {Array<Record<string, any>>} exits validated exit items
+ * @param {{ dir: string, snapshot?: Map<string, string>, runCheck?: (name: string) => Promise<{pass: boolean, gap?: string}> }} ctx
+ *   `dir`: the run directory; `snapshot`: the pre-step `snapshotScope` result
+ *   (required by tree-changed — absent fails closed); `runCheck`: the runner's
+ *   runClose-backed seam (required by check-passes — absent fails closed).
+ * @returns {Promise<{ pass: boolean, results: ExitResult[] }>}
+ */
+export function evalExits(exits: Array<Record<string, any>>, { dir, snapshot, runCheck }: {
+    dir: string;
+    snapshot?: Map<string, string>;
+    runCheck?: (name: string) => Promise<{
+        pass: boolean;
+        gap?: string;
+    }>;
+}): Promise<{
+    pass: boolean;
+    results: ExitResult[];
+}>;
+/**
+ * `fault` present means the INSTRUMENT could not judge (unwired snapshot/seam,
+ * a check in runClose's forbidden zone) — it carries the runClose verdict name
+ * ('failed'|'timed-out'|'killed'|'crashed') so the micro-loop escalates through
+ * the same CLOSE_FAULTS taxonomy instead of feeding a fake gap to the worker.
+ * A plain pass:false with no fault is honest worker feedback.
+ */
+export type ExitResult = {
+    type: string;
+    pass: boolean;
+    detail?: string;
+    fault?: string;
+};

package/types/index.d.ts

@@ -1,8 +1,11 @@
 export { makeSpine } from "./spine.js";
+export { runPlan } from "./planrun.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 { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
+export { validatePlan, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from "./plan.js";
+export { snapshotScope, evalExits } from "./exits.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

@@ -1,3 +1,70 @@
+/**
+ * The retrieval pair (F19). `shell_read` cannot seek — it starts at byte zero — so a
+ * pointer at a symbol was inert and the worker paged whole files to reach one function.
+ * `ctx_recall` hands back a POINTER (no body: a search index returns pointers, and bodies
+ * on every hit rebuild the bloat — measured, a 5-hit recall dumps ~15k tokens unbidden);
+ * `ctx_get` trades that pointer for ONE chunk. A chunk starts at its doc-comment, so the
+ * body arrives WITH the docstring that says what it was supposed to do.
+ * @param {any} lc the run's LiteCtx (rooted at workdir)
+ * @param {string} workdir
+ * @param {(type: string, data: object) => void} emit the spine — a retrieval verb whose
+ *   RESULT is invisible cannot be judged: a `ctx_get` that silently reds (stale pointer,
+ *   bad range) looks exactly like one that worked, and the worker's fallback to a
+ *   whole-file read looks like a free choice instead of a forced one.
+ */
+export function createCtxTools(lc: any, workdir: string, emit: (type: string, data: object) => void): ({
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            n: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+        };
+        required: string[];
+    };
+    execute: ({ query, n }: {
+        query: string;
+        n?: number;
+    }) => Promise<any>;
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            startLine: {
+                type: string;
+                description: string;
+            };
+            endLine: {
+                type: string;
+                description: string;
+            };
+            query?: undefined;
+            n?: undefined;
+        };
+        required: string[];
+    };
+    execute: ({ path: p, startLine, endLine }: {
+        path: string;
+        startLine: number;
+        endLine: number;
+    }) => Promise<any>;
+})[];
 /**
  * Execute a workflow config against one task under the dumb shell.
  *
@@ -87,6 +154,37 @@ export function interpret(configRaw: object | string, { task, target, close, wor
 }): Promise<"green" | "escalated" | "config-red">;
 /** @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;
+export const PERSONA_TOOLS: string;
+export const RETRIEVAL_STRATEGY: string;
+export const EDIT_STRATEGY: string;
+export const TOOL_BY_VERB: Readonly<{
+    read: "shell_read";
+    grep: "shell_grep";
+    write: "shell_write";
+    edit: "shell_edit";
+    recall: "ctx_recall";
+    get: "ctx_get";
+}>;
+export const CTX_TOOLS: readonly string[];
+export function toolAction(name: string, args: any, workdir?: string): {
+    type: string;
+    path: string;
+    args: {
+        bytes: number;
+        tool?: undefined;
+    };
+} | {
+    type: string;
+    path: string;
+    args: {
+        tool: string;
+        bytes?: undefined;
+    };
+} | {
+    type: string;
+    args: any;
+    path?: undefined;
+};
 /**
  * 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)
  */

package/types/job.d.ts

@@ -71,7 +71,19 @@ export const TOOL_MENU: readonly string[];
  * 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[];
+/** Layer 2 (design record 2026-07-21, decision 5): the verdict-type radio of
+ * the four-field plan shape. v1 ADMITS only `green`; soft-green/hitl are
+ * declared-but-locked — declaring one is a `request-red` (the tool-menu
+ * pattern: disclosure ≠ admission), so the ledger counts the demand and the
+ * non-code rung later fills a declared slot instead of reshaping the schema. */
+export const VERDICT_TYPES: readonly string[];
+export const LOCKED_VERDICTS: readonly string[];
 export const CADENCE_UNITS: readonly string[];
+/** SP-2: API-first; local deferred (PRD §5/§8). `clipipe-subscription` (F42,
+ * bare-agent 0.32.0 tool mode): the CLI as a bare turn-provider on a Claude
+ * subscription — its costUsd axis is NOTIONAL (API-equivalent value, not
+ * billed), so it is a DISTINCT condition: rows never pool with anthropic-api
+ * rows on the cost axis, and budgets sized for one do not transfer. */
 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,

package/types/plan.d.ts

@@ -0,0 +1,77 @@
+/**
+ * F49 — a heuristic reject for the catastrophic-backtracking footgun: an
+ * unbounded quantifier applied to a group whose body itself repeats unboundedly
+ * (`(a+)+`, `(\d*)*`, `([a-z]+){1,}`) — including through a redundant wrapping
+ * group (`((a+))+`, `(?:(a+))*`), which is the SAME exponential class as `(a+)+`
+ * and is caught by propagating the inner repeat up through the wrapper. Such a
+ * pattern can hang `RegExp.test` for
+ * seconds on a short crafted body, and `evalExits` runs the agent-authored
+ * `artifact-written` pattern with NO timeout. This is self-DoS only — the agent
+ * authors both the pattern and (via the worker) the artifact, so a hang burns
+ * only its own run's wall-clock; there is NO arbiter compromise (it cannot
+ * escape the fence, forge a green, or leak a secret). So the reject targets the
+ * dominant exponential class and fails it as a mechanical gap at the validation
+ * gate, before any tokens burn. A full ReDoS analyzer needs a real regex engine
+ * (an external native dep we do not take for a LOW issue); exotic
+ * overlapping-alternation blowup is out of scope by decision.
+ *
+ * SCOPE IS ASYMMETRIC, both directions named on purpose:
+ *   - false NEGATIVE: overlapping-alternation blowup (`(a|ab)+`-class) is not
+ *     detected — out of scope (self-DoS only, no arbiter compromise).
+ *   - false POSITIVE: a group whose repetitions are disambiguated by a literal
+ *     anchor/delimiter (`(?:^- .+$\n?)+`, `(?:CHANGELOG:.+\n)+`) is FLAGGED even
+ *     though a real engine runs it linearly — the scan sees the nested-quantifier
+ *     SHAPE, not the disambiguation. Rejecting it is the FAIL-SAFE direction (it
+ *     never admits an unsafe pattern), and the cost is bounded: the plan drafter
+ *     gets a mechanical gap and rewrites (drop the outer `+`, or match once).
+ *     Detecting "safe because anchored" needs the same real engine we declined,
+ *     and guessing it wrong would ADMIT an exponential pattern — so the shape
+ *     reject stands, and the over-rejection is a named, accepted limitation.
+ *
+ * The input is guaranteed to compile as a RegExp (checked first by the caller),
+ * so this scan assumes valid, balanced JS regex syntax.
+ * @param {string} src a compiled regex source string
+ * @returns {boolean} true iff a nested unbounded quantifier is present
+ */
+export function hasNestedQuantifier(src: string): boolean;
+/** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red */
+/**
+ * Validate an agent-authored plan (`schema: "plan-v1"`) against the SIGNED
+ * job spec. Never throws on JSON text or plain parsed data; every failure is
+ * a named red. Returns the parsed plan on ok (single parse), null on any red.
+ * @param {object|string} input parsed plan, or raw JSON text (parse failures are a red)
+ * @param {{ job?: any, maxStepRounds?: number }} [opts] `job`: the
+ *   validateJob-GREEN four-field spec (the ceiling, the fence, and the checks
+ *   menu all come from it — a missing or non-plan-shape job fails CLOSED);
+ *   `maxStepRounds`: the shell's per-step rounds ceiling (interpret's
+ *   tool-mode TURNS_PER_ATTEMPT) — a step may tighten it, never exceed it.
+ * @returns {{ ok: boolean, reds: Red[], plan: object|null }}
+ */
+export function validatePlan(input: object | string, { job, maxStepRounds }?: {
+    job?: any;
+    maxStepRounds?: number;
+}): {
+    ok: boolean;
+    reds: Red[];
+    plan: object | null;
+};
+/** the closed exit menu (PRD v1.12 §3 + decision 1's `check-passes`): the
+ * shell evaluates every form with its own fixed code, never a command — the
+ * same both-directions inexpressibility guard as the two-validator split */
+export const EXIT_TYPES: readonly string[];
+/** decision 8: AND-only conjunction, bounded — no OR (a weak arm would
+ * launder the exit), no NOT */
+export const MAX_EXITS_PER_STEP: 2;
+/** plan size bound — per-step rounds bound the spend, but an unbounded step
+ * COUNT is still an unbounded claim on the wallet; same 8 as loop.maxIterations */
+export const MAX_PLAN_STEPS: 8;
+/** the write-class verbs (BA-13: `edit` is judged by the same fence as
+ * `write`) — a step granting one is a WRITE step for the F17 pairing rule
+ * and the v1.18 target requirement */
+export const WRITE_VERBS: readonly string[];
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+    verb?: string;
+};

package/types/planrun.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close/checks[]).
+ * Called by runJob after the approval gate, validation, and the smoke — this
+ * function owns the plan flow only; the caller owns the job-end record and the
+ * one ledger (every provider round is emitted here as `worker-round`, which
+ * the caller's metered emit accounts — F12).
+ *
+ * @param {any} job the validated plan-shape spec
+ * @param {object} opts
+ * @param {string} opts.workdir the run directory (the fence's root)
+ * @param {any} opts.provider shell-owned LLM binding (the Loop path — `anthropic-api`)
+ * @param {(o: {policy: Function, onTurn?: Function, maxTurns: number, hasTools: boolean}) => any} [opts.nativeProvider]
+ *   NATIVE clipipe factory (BA-16): required when `job.provider === 'clipipe-subscription'`.
+ *   The runner builds a FRESH provider per worker and picks the mode by `hasTools`:
+ *   `true` → native tool mode (`toolProtocol:'claude-mcp'`, wire `policy`+`onTurn`+`maxTurns`);
+ *   `false` → the drafter has no tools, so a native session would report NO cost — return a
+ *   metered claude-json TEXT provider (`--output-format json`, `parse:'claude-json'`) instead,
+ *   so its spend is never invisible. The Loop path (`anthropic-api`) never touches this.
+ * @param {(type: string, data?: object) => object} opts.emit spine emitter (the caller's METERED emit)
+ * @param {() => number} opts.remainingUsd the one wallet: what is left of the signed budget right now
+ * @param {() => boolean} [opts.isUnpriced] has any round come back with a null cost? (F6) — the
+ *   plan flow bails IN-FLIGHT on the first unpriced round instead of burning the whole plan
+ * @param {number} [opts.capRuns] shell-owned per-step attempt cap
+ * @param {number} [opts.closeTimeoutMs] close/check wall-clock cap (shell territory)
+ * @param {number} [opts.maxStepRounds] the shell's per-step rounds ceiling (validatePlan's bound)
+ * @param {boolean} [opts.layerRoot=false] Layer R — the within-run ratchet (src/root.js),
+ *   scoped PER STEP's ralph loop (each micro-wheel is the Layer-1 atom). Shell-assembled from
+ *   the step's own books: per-attempt write-sets from the F32 workerWrites audit (teed for
+ *   same-path rewrites, which the cumulative audit alone cannot see) and the red-set from the
+ *   exit evaluator's own gap. Defaults OFF (decided 2026-07-21, F41): fixation is extinct on
+ *   every current job, so ON has never won its A/B; `true` is the ON/experimental arm, and the
+ *   first plan-flow job to emit `root-injected` runs the pre-registered ON-vs-OFF acceptance
+ *   read (the Layer R default-flip, LAYERS.md ⚠). Excluded on native (clipipe): the native
+ *   worker has no onToolResult seam, so the tee cannot settle and same-path rewrites are blind.
+ * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
+ *   'check-red' | 'close-red' | 'close-unsupported' | 'pricing-red' | 'cap-halt' |
+ *   'provider-red' | 'interpreter-red' | `step-red:<id>`
+ */
+export function runPlan(job: any, { workdir, provider, nativeProvider, emit, remainingUsd, isUnpriced, capRuns, closeTimeoutMs, maxStepRounds, layerRoot }: {
+    workdir: string;
+    provider: any;
+    nativeProvider?: ((o: {
+        policy: Function;
+        onTurn?: Function;
+        maxTurns: number;
+        hasTools: boolean;
+    }) => any) | undefined;
+    emit: (type: string, data?: object) => object;
+    remainingUsd: () => number;
+    isUnpriced?: (() => boolean) | undefined;
+    capRuns?: number | undefined;
+    closeTimeoutMs?: number | undefined;
+    maxStepRounds?: number | undefined;
+    layerRoot?: boolean | undefined;
+}): Promise<string>;
+export type CategorizedError = Error & {
+    category?: string;
+    lib?: string;
+};

package/types/ralph.d.ts

@@ -98,7 +98,15 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
  *
  * @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
@@ -118,9 +126,18 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
  *   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, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
+export function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
     middle: (iteration: number, gap?: string) => void | Promise<void>;
-    close: string[];
+    close?: string[] | undefined;
+    judge?: (() => Promise<{
+        verdict: string;
+        gap?: string;
+        detail?: string;
+    }> | {
+        verdict: string;
+        gap?: string;
+        detail?: string;
+    }) | undefined;
     capRuns: number;
     emit: (type: string, data?: object) => object;
     redact?: ((s: string) => string) | undefined;

package/types/run.d.ts

@@ -28,7 +28,11 @@
  * @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
@@ -45,11 +49,17 @@
  *   '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 }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, target, provider, nativeProvider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd, layerRoot }: {
     approvals: unknown;
     workdir: string;
     target?: string | undefined;
     provider: any;
+    nativeProvider?: ((o: {
+        policy: Function;
+        onTurn?: Function;
+        maxTurns: number;
+        hasTools: boolean;
+    }) => any) | undefined;
     emit: (type: string, data?: object) => object;
     capRuns?: number | undefined;
     shellCapUsd?: number | undefined;