bareloop 0.3.0 → 0.5.0

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.
  *
@@ -42,11 +109,18 @@
  * @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, closeTimeoutMs, mode, tools, closeState, closeExpect, closeJudged, closeGapKeep }: {
+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 | undefined;
     close: string[];
@@ -75,10 +149,42 @@ export function interpret(configRaw: object | string, { task, target, close, wor
     }>) | undefined;
     closeState?: string | undefined;
     mode?: "text" | "tools" | undefined;
+    layerRoot?: boolean | undefined;
     tools?: string[] | undefined;
 }): 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,41 @@
+/** @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,49 @@
+/**
+ * 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)
+ * @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 }: {
+    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;
+}): 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;
@@ -134,6 +151,7 @@ export function ralph({ middle, close, capRuns, emit, redact, closeTimeoutMs, cw
     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

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

@@ -17,32 +17,55 @@
  * 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 function runJob(rawSpec: object | string, { approvals, workdir, target, provider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd }: {
+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;
     closeTimeoutMs?: number | undefined;
     execCmd?: ExecCmd | undefined;
+    layerRoot?: boolean | undefined;
 }): Promise<string>;
 export type Red = {
     code: string;