bareloop 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [0.20.0] — 2026-09-05
+
+### Added
+
+- Operator-only scout OFF switch (`docs/product/SCOUT-CONTRAST.md`): `runJob`/`runPlan`
+  accept `scout` (boolean, default `true`); `false` on a fresh run skips the read-only
+  survey and records `scout-skipped { reason: 'operator-off' }` instead — the planner
+  drafts from `(no scout notes)`. `scripts/run-u.mjs --scout on|off` is the runner
+  surface, modelled on `--read-shim`; a non-boolean/unrecognised value throws/exits
+  before a token is spent. Runner territory — the signed spec hash is unaffected.
+  Measured (F126): both arms green on `aurora-u-spawner-types`, OFF cost $0.37 more
+  (inside the $0.40 noise band) — the scout is not dead weight; the switch stays as a
+  probe knob, no default flip.
+
+### Docs
+
+- Export scoping and lock: `docs/product/EXPORT-SCOPING.md` (tree facts, proposed
+  bundle shape) and `docs/product/EXPORT-BUILD.md` (frozen build spec — worktree,
+  no-resign-on-tighten) record hamr's interview answers ahead of the export build
+  itself; no code shipped yet.
+- G4 counting-rule scoping (`docs/product/G4-SCOPING.md`) and the first `docs/logs/BENCH.md`
+  bench-ledger row.
+
 ## [0.19.1] — 2026-09-02
 
 ### Fixed

package/bareloop.context.md

@@ -958,7 +958,7 @@ Reserved spine vocabulary (V7, machinery-free until job #1 surfaces one):
 `coordination-red` — a failure between units (scope contention, step order, store
 races), never to be folded into worker/interpreter reds.
 
-### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, readShim?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch?, humanRuling?, heldRuling?, reviewDoor?, doorRerun? })` → outcome — `src/run.js`
+### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, readShim?, scout?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch?, humanRuling?, heldRuling?, reviewDoor?, doorRerun? })` → outcome — `src/run.js`
 
 The last seven are the RESUME fold and are documented under *Resuming a killed run* below; they
 default to `0` / `true` / `0` / `null` / `[]` / `null` / `null`, so a fresh run passes none of them.
@@ -1027,6 +1027,20 @@ arm replaces the CLI-display cap rather than stacking on it; a non-capping arm l
 installed *inside* the shim, so native never loses its bound. Default-flip pending a paid contrast;
 see CHANGELOG for the replay numbers behind it.
 
+**`scout` (default `true`) — the operator-only off switch** (`docs/product/SCOUT-CONTRAST.md`),
+threaded verbatim from `runJob` to `runPlan`. `false` on a FRESH run (no `resumeSeed`) skips the
+read-only survey entirely — `scout-start`/`scout-result`/`scout-empty` never fire, and a single
+`scout-skipped { reason: 'operator-off', meaning }` records it (a RECORD, never silence — the
+resume skip's own rule). The planner then drafts from `(no scout notes)` exactly as it does today
+when a scout returns an empty blob; nothing else observable changes. Precedence when both a
+resumed leg and `scout:false` are in play: the resume skip fires first and wins its own reason
+(`resumed`) — `operator-off` is only ever emitted on a fresh run. A non-boolean value **throws**
+a `TypeError` at the same door as the `readShim` arm guard, before a token is spent. It is a probe
+knob, not a product default — the spec names no scout, so the signed hash is unaffected — and
+`scripts/run-u.mjs --scout on|off` (default `on`) is its runner-territory surface, modelled on
+`--read-shim`: an unrecognised value exits 2 at argv, and every re-invocation the runner prints
+carries `--scout off` when set, so a resume never silently drops the arm.
+
 **The two hitl terminals (N4 slice 1, doors re-cut 2026-08-18)** are the class's whole surface
 at this layer, and each is a CLEAN exit (`spendComplete` stays true — only the two casualties floor). `hitl-pause` is a
 decision-ready CHECKPOINT: the close reached a stage no machine can render, so the run stops

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Workflows that earn their own design, with receipts \u2014 agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",

package/src/planrun.js

@@ -642,6 +642,17 @@ ${scoutBlob || '(no scout notes)'}`;
  *   it.
  * @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.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md):
+ *        `false` on a FRESH run (no `resumeSeed`) skips the survey entirely — `scoutBlob`
+ *        stays `''`, no `scout-start`/`scout-result`/`scout-empty` is emitted, and a single
+ *        `scout-skipped {reason:'operator-off'}` records it (a RECORD, never silence — the
+ *        resume skip's own rule). The planner then drafts from `(no scout notes)`
+ *        (line ~587) exactly as it does today when a scout returns an empty blob — OFF is
+ *        byte-identical to today's run everywhere but the survey. Precedence: when
+ *        `resumeSeed` is set the existing resume skip fires first and wins its own reason
+ *        (`resumed`); `operator-off` is only ever emitted on a fresh run. A non-boolean
+ *        THROWS a TypeError at entry (the `readShimArm` guard class) — a knob that
+ *        silently coerced would mislabel a bench row.
  * @param {number} [opts.scoutRounds] the read-only survey's round bound (F59: the LAST round is
  *   reserved — a scout that spends every round on tools gets one toolless round to write its
  *   survey, because the bound halts it mid-tool-use and text is its only deliverable)
@@ -805,7 +816,7 @@ ${scoutBlob || '(no scout notes)'}`;
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, readShim = false, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null }) {
+export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null }) {
   // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
   // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
   // worker) — one accumulator closed over by all of them, because the shim's ledger
@@ -822,6 +833,11 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
   // would be wrong and would look fine). Only the guard runs here; the flag itself
   // is still threaded onward as written.
   readShimArm(readShim);
+  // The scout switch's guard, same class and same door: a mis-typed value
+  // coerced by truthiness would run the scout under an "off" label (or skip it
+  // under an "on" one) and no reading of the results afterwards could recover
+  // which arm actually ran (docs/product/SCOUT-CONTRAST.md).
+  if (typeof scout !== 'boolean') throw new TypeError(`scout: expected boolean, got ${JSON.stringify(scout)}`);
   // G1's OTHER half, refused at the same $0 door. `validatePlan` reds `read-blind`
   // when a step grants `read` without the retrieval pair — but a step cannot grant
   // what the SIGNED CEILING does not offer, so against a spec whose `tools` lack
@@ -2456,6 +2472,15 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       reason: 'resumed', phase: resumeSeed.phase ?? null,
       meaning: 'the killed run already paid for this survey; its plan is reloaded, not re-drafted. A replan after this point drafts from an empty survey plus the failure brief.',
     });
+  } else if (scout === false) {
+    // The operator-off arm (docs/product/SCOUT-CONTRAST.md): a fresh run whose
+    // operator asked for no survey. Precedence already settled above — the
+    // resume branch fires first and wins its own reason, so this arm is only
+    // ever reached when there is nothing to resume from.
+    emit('scout-skipped', {
+      reason: 'operator-off',
+      meaning: 'the operator ran with --scout off; the planner drafts from "(no scout notes)"; no survey was paid for.',
+    });
   } else {
     emit('scout-start', { rounds: scoutRounds });
     try {

package/src/run.js

@@ -171,6 +171,12 @@ async function primitiveSmoke(workdir) {
  *        frozen A0 baseline arm has to be exactly today, so a guard firing under a disabled
  *        shim would make the baseline a treatment arm. The default-flip belongs to a
  *        paid contrast nobody has approved yet (the `layerRoot` precedent, F41).
+ * @param {boolean} [opts.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md),
+ *   forwarded verbatim to the plan flow: `false` on a fresh run (no `resumeSeed`) skips the
+ *   read-only survey and records `scout-skipped {reason:'operator-off'}` instead — the
+ *   planner drafts from `(no scout notes)`. Runner territory exactly like `readShim`: the
+ *   spec names no scout, so the signed hash is unaffected. A non-boolean THROWS at this
+ *   entry, before the ledger, before the approval gate (the `readShim` guard class).
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -202,7 +208,7 @@ async function primitiveSmoke(workdir) {
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, readShim = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, readShim = false, scout = true, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
   // THE READ SHIM's ARM, resolved at the door — the FIRST thing this entry does,
   // before the ledger, before the approval gate, before a byte of the spec is read.
   // An unrecognised spelling throws here at zero cost instead of being coerced by
@@ -211,6 +217,10 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // blind-instrument failure this programme keeps logging. Only the guard runs
   // here; the flag itself is threaded onward to the plan flow as written.
   readShimArm(readShim);
+  // The scout switch's guard, same class and same door (docs/product/SCOUT-CONTRAST.md):
+  // a mis-coerced value would run under the wrong label with no way to recover which arm
+  // actually fired from the results afterwards.
+  if (typeof scout !== 'boolean') throw new TypeError(`scout: expected boolean, got ${JSON.stringify(scout)}`);
   // 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
@@ -405,7 +415,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, readShim, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
       remainingUsd: () => Math.min(shellCapUsd, job.budgetUsd - spentUsd),
       isUnpriced: () => unpriced, // F6: let the plan flow bail in-flight, not just after it returns
       spendComplete, // …and let its money-halt readout say whether the remaining it quotes is exact

package/types/planrun.d.ts

@@ -223,6 +223,17 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   it.
  * @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.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md):
+ *        `false` on a FRESH run (no `resumeSeed`) skips the survey entirely — `scoutBlob`
+ *        stays `''`, no `scout-start`/`scout-result`/`scout-empty` is emitted, and a single
+ *        `scout-skipped {reason:'operator-off'}` records it (a RECORD, never silence — the
+ *        resume skip's own rule). The planner then drafts from `(no scout notes)`
+ *        (line ~587) exactly as it does today when a scout returns an empty blob — OFF is
+ *        byte-identical to today's run everywhere but the survey. Precedence: when
+ *        `resumeSeed` is set the existing resume skip fires first and wins its own reason
+ *        (`resumed`); `operator-off` is only ever emitted on a fresh run. A non-boolean
+ *        THROWS a TypeError at entry (the `readShimArm` guard class) — a knob that
+ *        silently coerced would mislabel a bench row.
  * @param {number} [opts.scoutRounds] the read-only survey's round bound (F59: the LAST round is
  *   reserved — a scout that spends every round on tools gets one toolless round to write its
  *   survey, because the bound halts it mid-tool-use and text is its only deliverable)
@@ -386,7 +397,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, readShim, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -404,6 +415,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     strikeLimit?: number | undefined;
     closeTimeoutMs?: number | undefined;
     maxStepRounds?: number | undefined;
+    scout?: boolean | undefined;
     scoutRounds?: number | undefined;
     readShim?: boolean | "cap" | "diff" | undefined;
     layerRoot?: boolean | undefined;

package/types/run.d.ts

@@ -110,6 +110,12 @@
  *        frozen A0 baseline arm has to be exactly today, so a guard firing under a disabled
  *        shim would make the baseline a treatment arm. The default-flip belongs to a
  *        paid contrast nobody has approved yet (the `layerRoot` precedent, F41).
+ * @param {boolean} [opts.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md),
+ *   forwarded verbatim to the plan flow: `false` on a fresh run (no `resumeSeed`) skips the
+ *   read-only survey and records `scout-skipped {reason:'operator-off'}` instead — the
+ *   planner drafts from `(no scout notes)`. Runner territory exactly like `readShim`: the
+ *   spec names no scout, so the signed hash is unaffected. A non-boolean THROWS at this
+ *   entry, before the ledger, before the approval gate (the `readShim` guard class).
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -141,7 +147,7 @@
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, readShim, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, readShim, scout, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -173,6 +179,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     } | null | undefined;
     resumeBranch?: string | null | undefined;
     readShim?: boolean | "cap" | "diff" | undefined;
+    scout?: boolean | undefined;
     layerRoot?: boolean | undefined;
     humanRuling?: {
         decision: string;