bareloop 0.26.0 → 0.28.0

package/src/validate.js

@@ -41,11 +41,34 @@ export function globToPrefix(scope) {
   return p;
 }
 
+/**
+ * Path segments a fence/scope may never contain, checked WHOLE-SEGMENT
+ * (`prefix.split('/')`), never substring — a look-alike (`.github`,
+ * `.gitignore`, `my.git`, `node_modules_util`) is a DIFFERENT name and stays
+ * admitted. hamr's ruling (option B, 2026-09-14, block both): F178 — a
+ * signed fence naming `.git` could let a worker write git's own files (refs,
+ * the seed, `info/exclude`) and hide those writes from `changedSet`. F177's
+ * follow-up — a signed fence naming `node_modules` directly is the same class
+ * of gap (an installed/worker-written file inside it is invisible to
+ * `changedSet` the same way, and installs are the person's job now, F177).
+ * This catches only a fence that NAMES one of these directly; a fence like
+ * `packages/api/**` that later reaches a NESTED `node_modules` beneath it is a
+ * distinct, only partially closeable gap — see the runtime belt in
+ * planrun.js for `node_modules` (`.git` has no such gap: there is exactly one
+ * `.git` per repo, always at the workdir root, so its own runtime belt is a
+ * single `fs.deny` entry). Both are inexpressible at declaration time, the
+ * same law #1 already applies to `..`.
+ * @type {readonly string[]}
+ */
+export const FORBIDDEN_SCOPE_SEGMENTS = Object.freeze(['.git', 'node_modules']);
+
 /**
  * A scope may never reach the arbiter's inputs (design law #1): it must
  * resolve to a PROPER subdirectory of the run directory. Absolute paths and
  * ".." segments escape it; "." / "./**" cover the whole run directory — where
  * the close suite lives. Windows spellings ("..\", "C:\") count as escapes.
+ * A `.git` or `node_modules` segment anywhere in the prefix is refused too
+ * (F178/F177, see {@link FORBIDDEN_SCOPE_SEGMENTS}).
  * Exported for the job validator: the operator's outer fence obeys the SAME
  * law through the same code — two containment transforms would be the F9
  * red-class one level up.
@@ -59,7 +82,8 @@ export function scopeContained(s) {
   // that normalizes to something absolute can never pass (defense in depth
   // against a future globToPrefix regression; the un-gameable gate, law #1).
   if (prefix === '' || prefix === '.' || prefix.startsWith('/') || /^[a-zA-Z]:/.test(prefix)) return false;
-  return prefix.split('/').every((seg) => seg !== '..');
+  const segments = prefix.split('/');
+  return segments.every((seg) => seg !== '..' && !FORBIDDEN_SCOPE_SEGMENTS.includes(seg));
 }
 
 /** Shared with the job validator — one definition of "a JSON object" for both

package/types/authorflow.d.ts

@@ -254,13 +254,21 @@ export function writeScopeBlock(writeScope: string[]): string;
  * no listed check can verify — shown so the composer names the gap in its
  * own notes rather than the plan quietly reading as if everything asked for
  * is covered.
- * @param {{checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[]}} confirmed
+ * `answeredQuestions` (F175's open half, run mu0voeo4, hamr's 2026-09-16
+ * ruling) is every `Q:/A:` pair the person answered inline when a "Confirm"
+ * or "Type the goal yourself" pick forced a raised question before
+ * acceptance — BINDING, never re-decided by the composer, and a DIFFERENT
+ * meaning from `openQuestions` (which means "could not resolve"): the two
+ * never merge.
+ * @param {{checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[],
+ *   answeredQuestions?: string[]}} confirmed
  */
 export function confirmedBlock(confirmed: {
     checks: string[];
     protections: string[];
     openQuestions?: string[];
     notChecked?: string[];
+    answeredQuestions?: string[];
 }): string;
 /**
  * The whole authoring prompt, as one string.
@@ -284,7 +292,7 @@ export function confirmedBlock(confirmed: {
  *   guards: {name: string, kind: string, params: Record<string, any>, fill: string[]}[],
  *   ownedEnvNames?: string[], mode?: 'tool'|'text', catalogue?: Record<string, any>,
  *   writeScope?: string[]|null,
- *   confirmed?: {checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[]}|null}} o
+ *   confirmed?: {checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[], answeredQuestions?: string[]}|null}} o
  */
 export function authorPrompt({ answers, questions, facts, listingBlock, lang, verdictType, guards, ownedEnvNames, mode, catalogue, writeScope, confirmed, }: {
     answers: Record<string | number, string>;
@@ -308,6 +316,7 @@ export function authorPrompt({ answers, questions, facts, listingBlock, lang, ve
         protections: string[];
         openQuestions?: string[];
         notChecked?: string[];
+        answeredQuestions?: string[];
     } | null;
 }): string;
 /**
@@ -592,12 +601,20 @@ export function confirmTool(box: {
  * listing already paid for, the write fence, the detected language, "worse
  * than before" when the person gave one (repo only), and — on a fix round —
  * what the person asked to change.
+ * F183 (2026-09-16, ruling A, run mu2qmept): also carries the REAL,
+ * code-derived `protections` list ({@link confirmProtections} — the same
+ * guards the close will actually compose plus the real write fence, never a
+ * second hand-typed list) as an ALREADY COVERED block, with the instruction
+ * that anything on it never belongs in `notChecked`. Twice live (mu2bjmed,
+ * mu2qmept) the model claimed a guard or the write fence was missing while
+ * blind to what was actually enforced — this is the fix: show it the facts
+ * before it drafts, never hand-write a matcher over its answer.
  * @param {{answers: Record<string|number, string>, questions: Record<string|number, string>,
  *   labels?: Record<string|number, string>, facts?: any, listing?: string|null,
  *   writeScope?: string[]|null, isRepo: boolean, lang: string, worseThanBefore?: string,
- *   fixText?: string|null}} o
+ *   fixText?: string|null, protections?: string[]}} o
  */
-export function confirmPrompt({ answers, questions, labels, facts, listing, writeScope, isRepo, lang, worseThanBefore, fixText }: {
+export function confirmPrompt({ answers, questions, labels, facts, listing, writeScope, isRepo, lang, worseThanBefore, fixText, protections }: {
     answers: Record<string | number, string>;
     questions: Record<string | number, string>;
     labels?: Record<string | number, string>;
@@ -608,6 +625,7 @@ export function confirmPrompt({ answers, questions, labels, facts, listing, writ
     lang: string;
     worseThanBefore?: string;
     fixText?: string | null;
+    protections?: string[];
 }): string;
 /**
  * THE CONFIRM TURN: the $0 half (worse-than-before for a repo, a language
@@ -636,7 +654,7 @@ export function confirmPrompt({ answers, questions, labels, facts, listing, writ
  *   stop: null|'cap-halt'|'pricing-red'|'provider-red'|'artifact-red'|'confirm-abandoned'|'confirm-restart',
  *   rounds: number,
  *   accepted: {goal: string, checks: string[], protections: string[], lang: string,
- *     worseThanBefore: string, openQuestions: string[], notChecked: string[]}|null,
+ *     worseThanBefore: string, openQuestions: string[], notChecked: string[], answeredQuestions?: string[]}|null,
  *   reds: Red[], cost: any}>}
  */
 export function runConfirmTurn({ verdictType, answers, questions, labels, facts, listing, writeScope, isRepo, lang, generate, book, ask, onPhase, mode, worseThanBefore: presetWorseThanBefore, }: {
@@ -674,6 +692,7 @@ export function runConfirmTurn({ verdictType, answers, questions, labels, facts,
         worseThanBefore: string;
         openQuestions: string[];
         notChecked: string[];
+        answeredQuestions?: string[];
     } | null;
     reds: Red[];
     cost: any;
@@ -689,7 +708,13 @@ export function runConfirmTurn({ verdictType, answers, questions, labels, facts,
  * The return is deliberately complete rather than tidy:
  *   - `ok` is true iff a declaration passed validation and was measured;
  *   - `declaration` is the LAST ACCEPTED one, genre-env injected — the exact form
- *     that will run and that the signature will cover;
+ *     that will run and that the signature will cover; unless F176's fallback
+ *     fired (see `fellBack`), in which case it is the newest SOUND accepted one
+ *     instead — a "last accepted" close whose seed read instrument-stopped is
+ *     never handed to a signer as though it were the best close this run found;
+ *   - `fellBack` is `null` unless the fallback above fired, in which case it names
+ *     `{from, to, brokenStages}` — which iteration was dropped, which one now
+ *     stands, and which of the dropped one's stages instrument-stopped;
  *   - `reds` is what the LAST validated iteration said. `ok:true` with a non-empty
  *     `reds` means the final revision was rejected and the previous close stands:
  *     the rejection is reported, never hidden, and never silently shipped either;
@@ -717,7 +742,7 @@ export function runConfirmTurn({ verdictType, answers, questions, labels, facts,
  *   structuredMode?: 'tool'|'text', catalogue?: Record<string, any>, writeScope?: string[]|null,
  *   priorCalls?: {label: string, costUsd: number|null, unpricedRounds: number}[]|null,
  *   priorRaws?: any[]|null,
- *   confirmed?: {checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[]}|null}} o
+ *   confirmed?: {checks: string[], protections: string[], openQuestions?: string[], notChecked?: string[], answeredQuestions?: string[]}|null}} o
  */
 export function authorClose({ workdir, seedRef, lang, verdictType, answers, questions, writeScope, scout, listing, priorCalls, priorRaws, confirmed, generate, seedReadFn, closeCtx, ceilingUsd, onPhase, onCall, maxRevisions, structureRetries, structuredMode, catalogue, }: {
     workdir: string;
@@ -767,6 +792,7 @@ export function authorClose({ workdir, seedRef, lang, verdictType, answers, ques
         protections: string[];
         openQuestions?: string[];
         notChecked?: string[];
+        answeredQuestions?: string[];
     } | null;
 }): Promise<any>;
 /** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
@@ -1023,6 +1049,22 @@ export const LANGUAGE_PICK_FIELD: Readonly<{
     label: "Language";
     prompt: "This repo has more than one supported language's manifest at the same level. Which one is this job about?";
 }>;
+/**
+ * F175's open half (docs/logs/FINDINGS.md, run mu0voeo4), hamr's ruling
+ * (2026-09-16): "Confirm" and "Type the goal yourself" may not bypass a
+ * `questions` entry the model itself raised on the plan being accepted — the
+ * person answers it inline, one question at a time, with NO extra model
+ * call (the round cap and D3 are untouched). This is the `field` handed to
+ * `ask({kind: 'answer', ...})` for each forced question — `question`,
+ * `index` (1-based) and `total` ride alongside on the step itself, not on
+ * this frozen constant, because they differ per question within one turn.
+ */
+export const ANSWER_QUESTION_FIELD: Readonly<{
+    id: "answerQuestion";
+    kind: "mechanical";
+    label: "Answer";
+    prompt: string;
+}>;
 /**
  * THE CONFIRM TURN'S MENU — a structured CHOICE the person picks from after
  * each round, never free text matched against a pattern (ruling 6's "no

package/types/authorreadout.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @param {{goal?: string|null, closeDecl?: any}} spec the RESOLVED spec — the bytes
+ *   that get hashed and signed, never the operator's draft and never the authored
+ *   half on its own.
+ * @returns {string[]} one console line each, in print order.
+ */
+export function declarationLines({ goal, closeDecl }: {
+    goal?: string | null;
+    closeDecl?: any;
+}): string[];
+/**
+ * F176'S FALLBACK, SAID OUT LOUD — the revise ladder kept the NEWEST SOUND
+ * declaration rather than the last one it happened to try, because "kept the
+ * last accepted revision" is not the same claim as "kept the best revision"
+ * (docs/logs/FINDINGS.md F176). Absent on every run where the fallback never
+ * fired (the overwhelming majority), which is why this returns an EMPTY list
+ * rather than a "no fallback" line — a green close has nothing to say here and
+ * printing it every run would be noise, not information.
+ * @param {{fellBack?: {from: string, to: string, brokenStages: string[]}|null}|null} authoring `authored.authoring`
+ * @returns {string[]}
+ */
+export function fellBackLines(authoring: {
+    fellBack?: {
+        from: string;
+        to: string;
+        brokenStages: string[];
+    } | null;
+} | null): string[];
+/**
+ * THE TWO SIGNED JUDGED ARTIFACTS, as a person reads them before signing
+ * (softgreen modules 4+5). Absent on a close that judges nothing, which is why
+ * this returns an EMPTY list rather than a "no card" line: a green close has no
+ * rubric and saying so every run is noise, not information.
+ *
+ * The CARD is printed in full — it is short, it is the whole standard the judge
+ * will hold the work to, and it is the signer's own words. The CASES are printed
+ * as a ROSTER (id, verdict, itemized reds) rather than in full: ten real source
+ * artifacts is a page of code the terminal cannot usefully show, and what a
+ * signer checks at this surface is that both polarities are there and that each
+ * red names something they recognise. The artifacts themselves are in the spec
+ * file, which is named right above this block.
+ * @param {{closeDecl?: any}} spec the RESOLVED spec
+ * @returns {string[]}
+ */
+export function rubricLines({ closeDecl }: {
+    closeDecl?: any;
+}): string[];
+/**
+ * THE CONFIRM TURN'S OPEN QUESTIONS (PRD item 33 M3 piece 4, ruling 5's D3
+ * addendum) — shown at the SIGNING readout, from `authored.json`'s own
+ * `confirmed.openQuestions`, never added to the signed spec format itself
+ * (D4: the closeDecl's `notes` are the model's own record; this is the
+ * person's "fix" text from a round that hit the 2-round cap, ruling 5,
+ * passed to the composer verbatim rather than spending a 3rd call, D3). A
+ * close with none is shown as `(none)` rather than an empty line — the
+ * absence is itself part of what the signer reads before signing.
+ * @param {{openQuestions?: string[]}|null} confirmed `authored.confirmed`
+ * @returns {string[]}
+ */
+export function openQuestionLines(confirmed: {
+    openQuestions?: string[];
+} | null): string[];
+/**
+ * F175's open half, said at the SIGNING readout too (run mu0voeo4, hamr's
+ * 2026-09-16 ruling) — every question the plan raised that "Confirm" or
+ * "Type the goal yourself" forced the person to answer inline, from
+ * `authored.json`'s own `confirmed.answeredQuestions`. Shown only when
+ * non-empty (the overwhelming majority of plans raise no question at all,
+ * and printing an empty block every run would be noise, not information) —
+ * unlike {@link openQuestionLines}, an empty list here says nothing, because
+ * absence is the ordinary case, not a fact the signer needs flagged.
+ * @param {{answeredQuestions?: string[]}|null} confirmed `authored.confirmed`
+ * @returns {string[]}
+ */
+export function answeredQuestionLines(confirmed: {
+    answeredQuestions?: string[];
+} | null): string[];
+/**
+ * THE CALIBRATION GATE'S OWN READOUT — the one gate that spends money, and the
+ * one whose rows a signer has to read case by case.
+ *
+ * ITEMIZED, never an aggregate percentage: "9/10" tells a person nothing about
+ * which line of their own rubric is wrong, and the fix for a miss is a card line
+ * or a corrected case (§4.3's ceiling). A CASUALTY prints under its own name and
+ * says so, because a dead judge is not a failed set.
+ * @param {any} calibration `signing.gates.calibration`
+ * @returns {string[]}
+ */
+export function calibrationLines(calibration: any): string[];
+/**
+ * THE AUTHORING CEILING, parsed from `--budget`. Housed here for the same reason
+ * the readout above is: the runner is a script, and a rule no test can reach is a
+ * rule nothing checks.
+ *
+ * ABSENT IS UNBOUNDED, and that is the only way to get there. A malformed value
+ * is an ERROR rather than a fallback: `--budget banana` silently collapsing to
+ * "no ceiling" is precisely the failure this flag exists to prevent, wearing the
+ * operator's own typo. Zero and negatives are rejected on the same rule — a
+ * ceiling that can fund nothing is a typo for "unbounded" far more often than it
+ * is a request, and the honest way to ask for nothing is not to ask.
+ *
+ * There is NO DEFAULT anywhere in this function, deliberately: a defaulted cap is
+ * a silent second ceiling (the `maxWallMs` precedent), and the number is the
+ * operator's to set or to decline.
+ * @param {string|null} raw the argv value, or null when the flag was not given
+ * @returns {{ceilingUsd: number|null, error: string|null}}
+ */
+export function parseCeiling(raw: string | null): {
+    ceilingUsd: number | null;
+    error: string | null;
+};
+/**
+ * The ceiling's header line. An UNBOUNDED run is ANNOUNCED — printed before the
+ * provider is built, so it reaches stdout ahead of the first paid byte rather
+ * than being inferred from the total afterwards. An unbounded run is legal; it is
+ * never allowed to be an accident.
+ * @param {number|null} ceilingUsd
+ */
+export function ceilingLine(ceilingUsd: number | null): string;
+/**
+ * ONE PROGRESS PHASE, as a console line.
+ *
+ * The pipeline used to run up to ~15 minutes saying nothing between
+ * `author-start` and its result — a real survey ladder, a real declaration
+ * ladder, and a real toolchain per close stage, all inside one await. Silence
+ * and a hang are the same bytes on a terminal, and the operator's only lever is
+ * to kill a run that may be working.
+ *
+ * It says WHAT is happening, never how far along it is: there is no honest
+ * fraction to print (a survey attempt has no progress, and a suite stage
+ * finishes when it finishes), and an invented percentage is a number nobody
+ * measured. What it does carry is the two facts a person waiting actually uses —
+ * which phase, and how long the last thing took.
+ *
+ * `durationMs` prints as UNKNOWN when it is absent rather than as 0 (F6's rule,
+ * in its time form): a stage whose duration was never measured did not take no
+ * time.
+ * @param {string} phase @param {any} [data]
+ * @returns {string}
+ */
+export function phaseLine(phase: string, data?: any): string;
+/**
+ * ONE crashed authoring run, ready for the spine.
+ *
+ * It exists because a crash used to leave NO body. `run-author.mjs` awaited the
+ * paid pipeline at the top level, so a throw anywhere inside it went to the
+ * operator's terminal as an unhandled rejection and the spine kept exactly one
+ * line — `author-start` — which is byte-for-byte what a run still in flight looks
+ * like. The terminal scrolls; the spine is the record.
+ *
+ * The STACK is the evidence (the incident that minted this had no idea WHERE the
+ * throw came from), and a stack is the one field here that can be arbitrarily
+ * long and can quote anything the process had open. So it goes through `scrubRaw`
+ * — the ONE persist boundary for a raw blob — which redacts it over the same
+ * `SECRET_PATTERNS` inventory the validator reds on and bounds it with the bound
+ * announcing its own size (F28). Nothing here is hand-rolled: a second spelling
+ * of either rule is how the two drift.
+ *
+ * A non-Error throw (a string, a plain object) is honest rather than coerced into
+ * an Error shape: it has no `name`, so `name` is `null`, and `String(err)` is what
+ * lands in the raw.
+ * @param {unknown} err whatever was thrown
+ * @returns {{name: string|null, message: string|null, code: string|null,
+ *   raw: ReturnType<typeof scrubRaw>}}
+ */
+export function crashRecord(err: unknown): {
+    name: string | null;
+    message: string | null;
+    code: string | null;
+    raw: ReturnType<typeof scrubRaw>;
+};
+import { scrubRaw } from './text.js';

package/types/authorrun.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @typedef {object} Deps
+ * @property {Record<string,string|undefined>} [env]
+ * @property {NodeJS.ReadStream} [stdin]
+ * @property {NodeJS.WritableStream} [stdout]
+ * @property {NodeJS.WritableStream} [stderr]
+ * @property {string} [invokedAs] the command name this run was actually
+ *   reached through, for the usage message ONLY — `scripts/run-author.mjs`
+ *   supplies none (defaults to its own real invocation), `src/cli.js` passes
+ *   `'bareloop author'` so a person who typed that is told to re-run THAT,
+ *   never a script path they never invoked and may not have on disk.
+ */
+/**
+ * Parses this script's own argv shape and runs the authoring pipeline
+ * (scout, declaration loop, D9's gates) against the given (or real)
+ * stdin/stdout. `scripts/run-author.mjs` is the thin adapter over this, the
+ * same shape `bin/bareloop.mjs` already is over `src/cli.js`'s own
+ * `main(argv, deps)`.
+ * @param {string[]} argv
+ * @param {Deps} [deps]
+ * @returns {Promise<number>} an exit code — never calls process.exit
+ */
+export function main(argv: string[], deps?: Deps): Promise<number>;
+export type Deps = {
+    env?: Record<string, string | undefined> | undefined;
+    stdin?: NodeJS.ReadStream | undefined;
+    stdout?: NodeJS.WritableStream | undefined;
+    stderr?: NodeJS.WritableStream | undefined;
+    /**
+     * the command name this run was actually
+     * reached through, for the usage message ONLY — `scripts/run-author.mjs`
+     * supplies none (defaults to its own real invocation), `src/cli.js` passes
+     * `'bareloop author'` so a person who typed that is told to re-run THAT,
+     * never a script path they never invoked and may not have on disk.
+     */
+    invokedAs?: string | undefined;
+};

package/types/index.d.ts

@@ -24,9 +24,10 @@ export { scrubRaw, RAW_PERSIST_MAX } from "./text.js";
 export { authorClose, MAX_REVISIONS, questionsFor, requiredAnswersFor } from "./authorflow.js";
 export { validateCloseDecl, runDeclaredStages, declaredStages, HUMAN_PAUSE } from "./declaredclose.js";
 export { runBehaviour, formatBehaviour } from "./behaviour.js";
-export { replayRun, formatReplay } from "./replay.js";
+export { replayRun, formatReplay, summarizeForAllLine, formatAllLines } from "./replay.js";
+export { replayOne, listSpines, readHistoryLog } from "./replayio.js";
 export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, 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";
 export { readCloseScripts, checkCloseAbsolutePaths, absolutePathLiteralsOf, hashCloseScriptBytes, checkCloseByteSignature, checkStageByteSignature, signCloseScripts } from "./close-integrity.js";
-export { prepareSource, proveDestination, copyOut, readSourceManifest, frontDoorFromManifest, datedDestination, pickDelivery } from "./source.js";
+export { prepareSource, proveDestination, copyOut, readSourceManifest, frontDoorFromManifest, datedDestination, pickDelivery, missingDependencies } from "./source.js";

package/types/interviewrun.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @typedef {object} Deps
+ * @property {Record<string,string|undefined>} [env]
+ * @property {NodeJS.ReadStream} [stdin]
+ * @property {NodeJS.WritableStream} [stdout]
+ * @property {NodeJS.WritableStream} [stderr]
+ * @property {typeof realSpawnSync} [spawnSync] the TEST SEAM for the final
+ *   paid-step offer — a caller that supplies this never actually spawns
+ *   `scripts/run-author.mjs`.
+ * @property {string} [invokedAs] the command name this run was actually
+ *   reached through, for the usage message ONLY — `scripts/run-interview.mjs`
+ *   supplies none (defaults to its own real invocation), `src/cli.js` passes
+ *   `'bareloop interview'` so a person who typed that is told to re-run THAT,
+ *   never a script path they never invoked and may not have on disk.
+ */
+/**
+ * Parses this script's own argv shape and runs the interview against the
+ * given (or real) stdin/stdout. `scripts/run-interview.mjs` is the thin
+ * adapter over this, the same shape `bin/bareloop.mjs` already is over
+ * `src/cli.js`'s own `main(argv, deps)`.
+ * @param {string[]} argv
+ * @param {Deps} [deps]
+ * @returns {Promise<number>} an exit code — never calls process.exit
+ */
+export function main(argv: string[], deps?: Deps): Promise<number>;
+export type Deps = {
+    env?: Record<string, string | undefined> | undefined;
+    stdin?: NodeJS.ReadStream | undefined;
+    stdout?: NodeJS.WritableStream | undefined;
+    stderr?: NodeJS.WritableStream | undefined;
+    /**
+     * the TEST SEAM for the final
+     * paid-step offer — a caller that supplies this never actually spawns
+     * `scripts/run-author.mjs`.
+     */
+    spawnSync?: typeof realSpawnSync | undefined;
+    /**
+     * the command name this run was actually
+     * reached through, for the usage message ONLY — `scripts/run-interview.mjs`
+     * supplies none (defaults to its own real invocation), `src/cli.js` passes
+     * `'bareloop interview'` so a person who typed that is told to re-run THAT,
+     * never a script path they never invoked and may not have on disk.
+     */
+    invokedAs?: string | undefined;
+};
+import { spawnSync as realSpawnSync } from 'node:child_process';

package/types/job.d.ts

@@ -4,6 +4,27 @@
  * against the worker-surface package, a locked VERDICT type is demand against
  * bareloop's OWN menu. Inferring it downstream is how a bareloop refusal gets
  * filed as an upstream bug (the BA-2 misattribution class). */
+/**
+ * The `baseUrl` SHAPE rule, standalone (PRD item 28 ruling (d); PRD item 33
+ * close-out, "authoring provider selectable" — a bad `--base-url` used to
+ * refuse only at the end of the interview, through `validateJob`, after every
+ * question had already been asked). ONE spelling of the rule: `validateJob`
+ * below calls this, and so does `scripts/run-interview.mjs`, at flag-parse
+ * time, before it asks anything.
+ *
+ * No network access, so this checks SHAPE only: `https://` for a real
+ * endpoint, or `http://` restricted to a loopback host (a local
+ * OpenAI-compatible server, the only legitimate reason to skip TLS) — and
+ * never a credential embedded IN the URL itself. A URL travels into logs and
+ * spine records far more casually than a header ever would, and secrets never
+ * enter the tree/spine (hard line #3) — a baseUrl carrying `user:pass@host`
+ * is exactly that leak, just spelled differently. The returned message never
+ * echoes the value it judged — it is printed as-is by both callers, and a
+ * value that failed for carrying credentials must not repeat them back.
+ * @param {unknown} value
+ * @returns {string|null} a red `detail`, or `null` when the value is admitted
+ */
+export function validateBaseUrl(value: unknown): string | null;
 /**
  * Validate an operator-owned job spec (`schema: "job-v1"`). Never throws on
  * JSON text or plain parsed data — the ingest contract; a live object with a

package/types/planrun.d.ts

@@ -73,7 +73,6 @@
  * No gap → the empty string, so the brief renders byte-identically to the pre-F86
  * one. A labelled empty section would be an invitation to explain an absence the
  * run never observed (a stall never judged its exits at all).
- *
  * @param {string | null | undefined} gap the step's last exit gap text
  * @returns {string} the labelled block, or '' when there is nothing to show
  */
@@ -366,7 +365,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   it the deterministic name would collide with that very branch and the collision walk
  *   would mint a `-2` beside the progress the resume exists to keep. Absent is the cold
  *   path. A recorded branch that no longer exists is a STOP, never a fresh start.
- * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ * @param {{decision: string, text?: string|null}|null} [opts.humanRuling] N4 — the SIGNER's
  *   answer at a hitl pause (2026-08-12 §1, re-cut 2026-08-17: accept | rerun <text> | pause), carried in
  *   by the runner on the leg that RESUMES a paused run. Absent on every ordinary run and
  *   on the leg that pauses; it is never authored, never defaulted, and never inferred.
@@ -457,7 +456,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     resumeBranch?: string | null | undefined;
     humanRuling?: {
         decision: string;
-        text?: string;
+        text?: string | null;
     } | null | undefined;
     heldRuling?: {
         decision: string;
@@ -473,6 +472,47 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     } | null | undefined;
     resumable?: boolean | undefined;
 }): Promise<string>;
+/**
+ * The runtime belt for F178 (`.git`) and F177's follow-up (`node_modules`) —
+ * hamr's option B ruling (2026-09-14): block WRITING to either, never reading.
+ * bareguard's `fs.deny` cannot be used for this: it blocks ALL fs actions,
+ * reads included (node_modules/bareguard/src/primitives/fs.js:43 "paths/
+ * prefixes denied for all fs actions", checked at :62-66 before the read/write
+ * split) — putting `.git` there (the first version of this fix) silently also
+ * blocked READING it, which was never ruled, and the worker's persona never
+ * names `.git`/`node_modules` as a denied book the way it does the gate audit
+ * / `.smoke` / `.litectx` (`tests/tools.test.js`'s persona/fence-drift guard
+ * caught exactly this in the full gate). `fs.deny` is exact prefix-containment
+ * only anyway — no glob, no path-segment match — confirmed by reading
+ * `within()` (node_modules/bareguard/src/primitives/fs.js:26-31): `p === b ||
+ * p.startsWith(b + '/')` against each configured entry, nothing else; it
+ * could not express `node_modules`-at-any-depth even if reads were not a
+ * problem (`node_modules/bareguard/src/glob.js`'s `matchAny`/`globToRegex`
+ * exist in the same package but `fs.js` never imports them).
+ *
+ * `tools.denyArgPatterns` (`node_modules/bareguard/src/primitives/tools.js`,
+ * step 3 of `Gate#_stepEval` — the SAME step `fsCheck` runs at, checked right
+ * after it in the `??` chain, `node_modules/bareguard/src/gate.js`) is the
+ * supported hook used instead: a RegExp tested against
+ * `JSON.stringify(action)`, keyed by `action.type` so it is scoped to
+ * `write`/`edit` ONLY — a `read` action never reaches this pattern at all.
+ * Because `fsCheck` runs first in the same `??` chain, this pattern is
+ * reached only when the path already passed `writeScope`/`deny` — exactly the
+ * residual case (an in-fence write/edit whose path still carries a `.git` or
+ * `node_modules` segment; `.git` itself is never IN a signed fence in the
+ * first place, `scopeContained` in src/validate.js refuses that at
+ * declaration time — this is the belt for a validator regression). Matched
+ * whole-segment (a look-alike like `.github`/`.gitignore`/`my.git`/
+ * `node_modules_util` stays admitted). Safe to match the WHOLE serialized
+ * action (not just the `path` field in isolation) because bareloop's own
+ * action shape (`toolAction`, src/tools.js) never carries a write's byte
+ * CONTENT in the action object — `args.bytes` is a length, not the text — so
+ * there is no written-file-content collision risk the way there would be for
+ * bareguard's own `content.denyPatterns` primitive (which explicitly strips
+ * payload fields for exactly that reason).
+ * @type {RegExp}
+ */
+export const FORBIDDEN_WRITE_SEGMENT_PATTERN: RegExp;
 /**
  * The recorded bound-reason's ceiling in the WORKER-facing note. The reason is a
  * provider string (`denied:<tool>` today, ~20 bytes), not a gap, so this is a

package/types/providers.d.ts

@@ -8,6 +8,34 @@
  * @returns {ProviderTableEntry}
  */
 export function resolveProvider(providerName: string): ProviderTableEntry;
+/**
+ * Report whether a resolved API key VALUE (not its presence — every call
+ * site already presence-checks separately) carries a shape an HTTP header
+ * value cannot: F181 (`docs/logs/FINDINGS.md`) — a two-line secret-store
+ * entry put the key plus a trailing metadata line into `OPENAI_API_KEY`
+ * (`"<key>\nmeta"`), the presence-only check at every door passed, and Node
+ * crashed `TypeError [ERR_INVALID_CHAR]` inside its own header-encode at the
+ * FIRST paid call — after the run had already announced itself as spending,
+ * inside the paid span. curl tolerated the same value (HTTP 200 twice), so a
+ * curl probe is a blind instrument for this defect class.
+ *
+ * NEVER TRIMS OR REPAIRS — this reports a reason, it does not fix the value
+ * (hamr's retry-never-repair rule, in spirit: refuse loud, don't guess at
+ * what the operator's secret store meant). Every call site that gets a
+ * non-null reason back refuses at $0, in the SAME place and the SAME way it
+ * already refuses a missing key — this function only adds a second shape of
+ * refusal to a door that already had one.
+ *
+ * The checked shape is deliberately wider than what Node's own header
+ * encoder rejects (Node tolerates a bare tab in a header value): CR, LF, TAB,
+ * every other C0/DEL control character, and leading/trailing whitespace all
+ * refuse, because every one of them is evidence the resolved value is not a
+ * clean single-line secret — the same class of "reads as one plausible thing,
+ * is actually stale/wrong/multi-line" this finding named.
+ * @param {string} value the resolved key value — never logged, never echoed by any caller
+ * @returns {string|null} a plain-English reason class, or `null` when the value is clean
+ */
+export function apiKeyProblem(value: string): string | null;
 /**
  * Construct ONE provider instance for `providerName`/`model`, applying
  * `exposeErrorBody: true` (F153 — every constructed provider, unconditionally)