bareloop 0.19.1 → 0.21.0

package/types/bundle.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Recompute the bundle hash from what is ACTUALLY on disk right now (never
+ * trusts the stored manifest). Throws only if `dir` itself does not exist —
+ * every other absence (a missing spec.json, an empty close/) folds into the
+ * hash as an omitted file, which is exactly what makes a swapped/deleted
+ * script change the hash.
+ * @param {string} dir bundle directory
+ * @returns {string} sha256 hex
+ */
+export function bundleHash(dir: string): string;
+/**
+ * EXPORT — mints a bundle directory from a signed job spec (`docs/product/
+ * EXPORT-BUILD.md`, "The bundle"). Every check below runs BEFORE anything
+ * touches disk (typed reds, nothing written): a partially-written bundle
+ * would be worse than no bundle, since `readBundle`'s tamper check has
+ * nothing trustworthy to compare against yet.
+ *
+ * Refusals, each a distinct red code:
+ *  - `no-bridge-at-hash` — neither of the job's two possible bridge names —
+ *    `spec.job` itself, or its SHAPE FORK `shapeForkName(spec.job,
+ *    closeStagesOf(spec))` (the name `writeGreenRow`/`writeRunGreenRow` in
+ *    `src/reuse.js` mint whenever a run's close-stage set differs from the
+ *    base bridge's `closeStageNames` — same derivation, imported rather than
+ *    re-spelled, so the two names cannot drift) — carries a recorded specHash
+ *    (bridge-level or on some version) equal to `jobSpecHash(spec)`: nothing
+ *    has ever greened THIS exact spec, so there is nothing proven to ship.
+ *    Every candidate bridge that DOES exist (base and/or fork) still ships
+ *    into `bridges/` — the spec says "the job's WHOLE registry history
+ *    (greens and reds)", not just the one that matched.
+ *  - `close-cmd-unrelocatable` — a `close[].cmd` is not `node <abs .mjs> …`.
+ *  - `close-script-missing` — a cmd names a script `closeScripts` does not
+ *    carry the source for.
+ *  - `close-script-collision` — two different script paths share a basename;
+ *    copying both into one flat `close/` directory would silently clobber one.
+ *  - `close-import-unexported` — a close script imports a name from
+ *    bareloop's own src that `src/index.js` does not export.
+ *  - `close-import-unparsed` — a close script's import is a shape this
+ *    module cannot verify at all (default import, `* as ns`, mixed
+ *    default+named/namespace, a bare side-effect import, or a dynamic
+ *    `import()`), or is a relative import that does not point into
+ *    `src/` (a sibling file `close/` never ships, so it would be missing
+ *    from the bundle). Fails safe rather than silently accepting what it
+ *    cannot read.
+ *  - `close-absolute-path` — a close script's source bakes in a string
+ *    literal that is an absolute POSIX path which exists on the exporting
+ *    machine and is outside the system-prefix allow-list (see
+ *    `absolutePathLiteralsOf`): a close judges the cwd the runner gives it,
+ *    never a path baked into the script — F8/F129, the live defect this
+ *    guard would have refused at export time before any run.
+ *  - `outdir-not-empty` — `outDir` exists and already holds files.
+ *  - `registry-unreadable` — `registryDir` itself could not be read
+ *    (bubbled from `loadRegistry`).
+ * @param {{ spec: any, closeScripts: Record<string, string>, registryDir: string, outDir: string, bareloopVersion: string }} o
+ * @returns {{ ok: boolean, reds: Red[], dir: string|null, bundleHash: string|null, manifest: any|null }}
+ */
+export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloopVersion }: {
+    spec: any;
+    closeScripts: Record<string, string>;
+    registryDir: string;
+    outDir: string;
+    bareloopVersion: string;
+}): {
+    ok: boolean;
+    reds: Red[];
+    dir: string | null;
+    bundleHash: string | null;
+    manifest: any | null;
+};
+/**
+ * READ a bundle directory back: the manifest/spec, tamper-checked against
+ * what is actually on disk, plus the record-only bridges/blessing/history a
+ * runner needs beside them. Never throws — every failure is a typed red.
+ *
+ * `bundle-tampered` (N4) is a RED, never a warning, and runs whenever both a
+ * manifest and a spec could be read at all — a swapped close script must be
+ * caught here, before any caller reaches `runJob`.
+ * @param {string} dir bundle directory
+ * @returns {{ ok: boolean, reds: Red[], spec: any, manifest: any, bridges: any[], blessing: any, history: any[] }}
+ */
+export function readBundle(dir: string): {
+    ok: boolean;
+    reds: Red[];
+    spec: any;
+    manifest: any;
+    bridges: any[];
+    blessing: any;
+    history: any[];
+};
+/**
+ * The IN-MEMORY `$BARELOOP_BUNDLE` substitution (the frozen spec's "two
+ * facts": the runner never touches the spec on disk, it substitutes the
+ * absolute bundle directory into a copy before `runJob`, and signs THAT
+ * substituted spec's hash — not the on-disk one). `approveHash` is the value
+ * an `--approve` flag / a `history.jsonl` row must record.
+ * @param {{ spec: any }} bundle a `readBundle` result (or anything carrying `.spec`)
+ * @param {string} bundleDir absolute or relative bundle directory
+ * @returns {{ spec: any, approveHash: string }}
+ */
+export function resolveBundleSpec(bundle: {
+    spec: any;
+}, bundleDir: string): {
+    spec: any;
+    approveHash: string;
+};
+/**
+ * TIGHTEN-ONLY envelope check (hamr Q8: raising the ceiling is a re-export,
+ * never a runner flag). Each GIVEN number must be ≤ the bundle spec's own —
+ * an absent field in the envelope trivially passes (nothing was asked to
+ * tighten), and a spec with no ceiling of its own for that field (only
+ * `maxWallMs` is ever absent — `budgetUsd` is required) has nothing to
+ * widen, so a given number passes there too.
+ * @param {any} spec the (already `$BARELOOP_BUNDLE`-resolved) bundle spec
+ * @param {{ budgetUsd?: number, maxWallMs?: number }} envelope
+ * @returns {{ ok: boolean, reds: Red[] }}
+ */
+export function checkEnvelope(spec: any, envelope?: {
+    budgetUsd?: number;
+    maxWallMs?: number;
+}): {
+    ok: boolean;
+    reds: Red[];
+};
+/**
+ * Write `blessing.json`: the FIRST GREEN RUN on the importer's own machine
+ * signs the bundle as trustworthy (hamr Q2), so later runs need no
+ * `--approve` (hamr: "no-resign"). Overwrites any prior blessing — there is
+ * only ever one, for the bundle's current `bundleHash`.
+ * @param {string} dir bundle directory
+ * @param {{ bundleHash: string, runid: string, outcome: string, host?: string, blessedAt?: string }} record
+ * @returns {any} the blessing object written
+ */
+export function bless(dir: string, record: {
+    bundleHash: string;
+    runid: string;
+    outcome: string;
+    host?: string;
+    blessedAt?: string;
+}): any;
+/**
+ * Read `blessing.json` back and judge it against the bundle's CURRENT
+ * manifest hash. Three outcomes, never conflated: no blessing at all
+ * (`unblessed: true` — the bundle has simply never greened here, not a red);
+ * a blessing whose hash no longer matches the manifest (`blessing-stale` —
+ * the bundle was re-exported/edited since the run that blessed it); a match.
+ * @param {{ manifest: any, blessing: any }} bundle a `readBundle` result
+ * @returns {{ ok: boolean, unblessed: boolean, reds: Red[] }}
+ */
+export function verifyBlessing(bundle: {
+    manifest: any;
+    blessing: any;
+}): {
+    ok: boolean;
+    unblessed: boolean;
+    reds: Red[];
+};
+/**
+ * F128 preflight — can this bundle's close scripts actually resolve `import
+ * ... from 'bareloop'` at runtime? The bundle's own `package.json` declares
+ * `bareloop` as ITS dependency (`npm install` must be run INSIDE the bundle
+ * directory — validation step 2 was corrected 2026-09-06, see the dated
+ * addendum in `docs/product/EXPORT-BUILD.md`); nothing installs it for the
+ * bundle as a side effect of the bundle being installed as someone else's
+ * dependency. Left unchecked, a missing `node_modules` crashes every close
+ * stage deep inside the close-first precheck with a bare
+ * `ERR_MODULE_NOT_FOUND`, which surfaces as a generic `close-red` with no
+ * cure line (the live defect this fixes) — this check runs first and fails
+ * fast with the exact command to run.
+ *
+ * Resolves the bare specifier `'bareloop'` exactly as a close script would,
+ * from inside the bundle's own `close/` directory (the probe path itself
+ * need not exist — `createRequire`/`resolve` only use it to anchor the
+ * `node_modules` walk). Going through `require.resolve` also walks
+ * `bareloop`'s own `exports` map (the package root, `"."` -> `./src/
+ * index.js`), so a bare successful resolve already proves a real,
+ * exports-map-shaped `bareloop` package is reachable from THIS bundle's own
+ * dependency chain — not some unrelated global install. Any resolution
+ * counts (a direct `node_modules/bareloop`, a symlink into it, or a parent
+ * `node_modules/bareloop` up the directory chain) — it only has to resolve.
+ * @param {string} bundleDir
+ * @returns {{ ok: boolean, reds: Red[] }}
+ */
+export function checkBundleDeps(bundleDir: string): {
+    ok: boolean;
+    reds: Red[];
+};
+/**
+ * Append one row to `history.jsonl` — one `bareloop run` on this machine per
+ * line. Same convention as `spine.js`/`ledger.js`: `appendFileSync` opens
+ * with O_APPEND, so one line under PIPE_BUF is written atomically with
+ * respect to other appenders; there is no read-modify-write here to race.
+ * @param {string} dir bundle directory
+ * @param {any} row
+ */
+export function appendHistory(dir: string, row: any): void;
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};

package/types/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The one entry point. Never calls `process.exit` — always returns an exit
+ * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
+ * queued stdout on its own (F-something: `process.exit()` can discard it).
+ * @param {string[]} argv
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, now?: () => number, stdin?: any }} deps
+ * @returns {Promise<number>}
+ */
+export function main(argv: string[], deps?: {
+    env?: Record<string, string | undefined>;
+    stdout?: any;
+    stderr?: any;
+    cwd?: string;
+    provider?: any;
+    providerFor?: any;
+    judgeProvider?: any;
+    now?: () => number;
+    stdin?: any;
+}): Promise<number>;

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export { makeSpine } from "./spine.js";
 export { runPlan } from "./planrun.js";
+export { main as cliMain } from "./cli.js";
 export { ralph, runClose, runStages, CLOSE_FAULTS } from "./ralph.js";
 export { globToPrefix, scanSecrets } from "./validate.js";
 export { validateJob, jobSpecHash, checkApproval, checkMenu, resolveWorkerModel, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
@@ -8,7 +9,7 @@ export { snapshotScope, evalExits } from "./exits.js";
 export { runJob, ACCOUNTED_ROUND_TYPES } from "./run.js";
 export { BRIDGE_SCHEMA, validateBridge, deriveStatus, listingRow, loadGate, mintBridge, appendGreen, appendRed, loadBridge, loadRegistry, saveBridge, makeRegistry, registryExists, QUARANTINED_VERDICTS, QUARANTINED_CODE, quarantinesCredit, newestEligibleVersion, reuseEligibility, recordDoor } from "./bridges.js";
 export { renderListing, selectionPrompt } from "./selection.js";
-export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow } from "./reuse.js";
+export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow, shapeForkName } from "./reuse.js";
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES, VOUCHED_RATE_SOURCES, rateProvenance, spendProvenance } from "./ledger.js";
 export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE } from "./workbranch.js";
 export { createReadShim, wrapReadTool, readShimArm, readShimStrategy, READ_SHIM_CAP, READ_SHIM_STRATEGY, READ_SHIM_DIFF_STRATEGY, READ_SHIM_ARMS } from "./readshim.js";
@@ -26,3 +27,4 @@ export { runBehaviour, formatBehaviour } from "./behaviour.js";
 export { replayRun, formatReplay } from "./replay.js";
 export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS } from "./authorjob.js";
 export { PROMPT_REGISTERS, isPromptFile } from "./promptregisters.js";
+export { exportBundle, bundleHash, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps } from "./bundle.js";

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/reuse.d.ts

@@ -1,3 +1,17 @@
+/**
+ * The name a cold green FORKS to when the entry of the job's own name greened a
+ * different close. Derived from the shape itself, so it is deterministic: the same
+ * close always lands in the same file, and the next green of that shape appends there
+ * instead of minting a third entry.
+ *
+ * The separator is a HYPHEN, not the `~` first proposed: the registry name IS the
+ * filename and `validateBridge` holds it to the same kebab alphabet the job validator
+ * uses (`^[a-z0-9][a-z0-9-]*$`), so a `~` name would be refused by the entry's own
+ * validator and the green would be lost — which is the exact failure this fork exists
+ * to prevent.
+ * @param {string} name @param {string[]} stageNames @returns {string}
+ */
+export function shapeForkName(name: string, stageNames: string[]): string;
 /**
  * Validate the reuse envelope — the three numbers the operator signs before the run.
  *

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;