bareloop 0.26.0 → 0.28.0

package/src/job.js

@@ -192,6 +192,42 @@ const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
  * 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) {
+  if (!isNonEmptyString(value)) {
+    return 'non-empty string — an https:// URL (http:// admitted only to 127.0.0.1/localhost/::1)';
+  }
+  /** @type {URL|null} */
+  let u = null;
+  try { u = new URL(value); } catch { /* u stays null — caught below */ }
+  if (!u) return 'must be a parseable URL';
+  if (u.username !== '' || u.password !== '') return 'no embedded credentials (user:pass@host) — secrets never enter a signed spec';
+  if (u.protocol === 'https:') return null; // admitted
+  if (u.protocol === 'http:' && (u.hostname === '127.0.0.1' || u.hostname === 'localhost' || u.hostname === '::1')) {
+    return null; // admitted — a local OpenAI-compatible endpoint, the one case that legitimately skips TLS
+  }
+  return 'https:// required (http:// admitted only to 127.0.0.1/localhost/::1)';
+}
+
 /**
  * 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
@@ -329,33 +365,13 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
 
   // BASE URL — PRD item 28, ruling (d), 2026-09-09: admitted in v1 of
   // openai-api (an OpenAI-compatible gateway/endpoint), OPTIONAL and part of
-  // the signed hash like `model` above. This validator has no network
-  // access, so it 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 bareUrl carrying
-  // `user:pass@host` is exactly that leak, just spelled differently.
+  // the signed hash like `model` above. `validateBaseUrl` (below) is the ONE
+  // spelling of the shape rule — `scripts/run-interview.mjs` calls it too, at
+  // flag-parse time, before the interview asks a single question, rather than
+  // this file's copy being the only one that ever ran it.
   if (spec.baseUrl !== undefined) {
-    if (!isNonEmptyString(spec.baseUrl)) {
-      red('invalid-value', 'baseUrl', 'non-empty string — an https:// URL (http:// admitted only to 127.0.0.1/localhost/::1)');
-    } else {
-      /** @type {URL|null} */
-      let u = null;
-      try { u = new URL(spec.baseUrl); } catch { /* u stays null — caught below */ }
-      if (!u) {
-        red('invalid-value', 'baseUrl', 'must be a parseable URL');
-      } else if (u.username !== '' || u.password !== '') {
-        red('invalid-value', 'baseUrl', 'no embedded credentials (user:pass@host) — secrets never enter a signed spec');
-      } else if (u.protocol === 'https:') {
-        // admitted
-      } else if (u.protocol === 'http:' && (u.hostname === '127.0.0.1' || u.hostname === 'localhost' || u.hostname === '::1')) {
-        // admitted — a local OpenAI-compatible endpoint, the one case that legitimately skips TLS
-      } else {
-        red('invalid-value', 'baseUrl', 'https:// required (http:// admitted only to 127.0.0.1/localhost/::1)');
-      }
-    }
+    const err = validateBaseUrl(spec.baseUrl);
+    if (err) red('invalid-value', 'baseUrl', err);
   }
 
   // 3. the outer write fence — operator law (interview decision #4), same

package/src/planrun.js

@@ -11,7 +11,14 @@
 // absolute repo root, its target, prior steps' artifacts labeled by id, its
 // gap, and a cut-off notice. It NEVER sees the budget, the close command, a
 // check's command, the validator, other steps' grants, or the arbiter's books
-// (fs.deny on the gate audit / .smoke / .litectx, unchanged).
+// (fs.deny on the gate audit / .smoke / .litectx, unchanged). `.git` and
+// `node_modules` are a DIFFERENT law (F178/F177): WRITES there are blocked
+// (tools.denyArgPatterns on write/edit, FORBIDDEN_WRITE_SEGMENT_PATTERN,
+// below), but READS are not — fs.deny blocks ALL fs actions including reads
+// (bareguard node_modules/bareguard/src/primitives/fs.js:43,62-66), and
+// hamr's ruling was to block WRITING, never reading; the worker's persona
+// also never names `.git`/`node_modules` as denied books (tests/tools.test.js),
+// which putting either in fs.deny would silently contradict.
 
 import { createRequire } from 'node:module';
 import { readFileSync, readdirSync } from 'node:fs';
@@ -465,7 +472,6 @@ const REPLAN_GAP_KEEP = '\\S';
  * 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
  */
@@ -480,6 +486,48 @@ export function closeGapBlock(gap) {
     + (scrubbed.length > CHECK_GAP_MAX ? boundGap(scrubbed, REPLAN_GAP_KEEP) : scrubbed);
 }
 
+/**
+ * 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 = /"path":"(?:(?:[^"\\]|\\.)*\/)?(?:\.git|node_modules)(?:\/|")/;
+
 /**
  * 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
@@ -884,7 +932,7 @@ ${scoutBlob || '(no scout notes)'}`;
  *   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.
@@ -2250,6 +2298,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         readScope: [workdir],
         deny: [auditPath, ...ARBITER_BOOK_STORES.map((s) => join(workdir, s))],
       },
+      // F178/F177's runtime belt: `.git` and `node_modules` WRITES only — never
+      // fs.deny, which blocks reads too (see FORBIDDEN_WRITE_SEGMENT_PATTERN's
+      // own doc). Reached only when a write/edit path already cleared
+      // fs.writeScope/deny above (step 3's fsCheck runs first in the SAME `??`
+      // chain, node_modules/bareguard/src/gate.js) — i.e. only the residual
+      // case of an in-fence path that still carries one of these segments.
+      tools: { denyArgPatterns: { write: [FORBIDDEN_WRITE_SEGMENT_PATTERN], edit: [FORBIDDEN_WRITE_SEGMENT_PATTERN] } },
       budget: { maxCostUsd: Math.max(remainingUsd(), 0.0001) },
       limits: { maxTurns },
       audit: { path: auditPath },
@@ -2756,6 +2811,30 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         err.lib = 'bare-agent';
         throw err;
       }
+      // F184 — bare-agent 0.43.0 (BA-27) returns a malformed final-turn tool
+      // call PRICED rather than throwing: `toolCalls: []`, `text: ''`,
+      // `error: null`, and its own `malformedToolCall: {name, error}`
+      // marker. Nothing below this point can tell that apart from the model
+      // genuinely producing no useful work — `middle()` reads `r.text` into
+      // `lastText`, which comes back empty either way, and the ordinary
+      // `needs_revision`/`exit-eval` gap is what reaches the spine. That is
+      // NOT changed here — no retry, no new cause on `attemptBounded`, no
+      // effect on strike/ladder/attempt counting or verdict routing (all
+      // arbiter-adjacent, none of this finding's scope). What was missing is
+      // VISIBILITY: this is the one place bareloop code ever sees the
+      // marker before `ask()` returns it unexamined, so a distinct spine
+      // record names the transport class here — the same honesty bar
+      // F179/F180 set for the authoring path, applied to the worker path.
+      if (r.malformedToolCall) {
+        const rawErr = String(r.malformedToolCall.error ?? '');
+        const scrubbedErr = scrub(rawErr);
+        const shownErr = scrubbedErr.length > BOUND_REASON_MAX
+          ? `${scrubbedErr.slice(0, BOUND_REASON_MAX)} [${GAP_TRIM_MARKER} ${scrubbedErr.length - BOUND_REASON_MAX} of ${scrubbedErr.length} characters withheld — the cap is ${BOUND_REASON_MAX}]`
+          : scrubbedErr;
+        emit('worker-malformed-tool-call', {
+          phase, iteration: roundIteration, name: scrub(String(r.malformedToolCall.name ?? '')), error: shownErr,
+        });
+      }
       return r;
     };
     return { ask, askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };

package/src/promptregisters.js

@@ -76,6 +76,14 @@ export const PROMPT_REGISTERS = Object.freeze([
 
   // src/planrun.js — the native-surface read-truncation strategy line
   Object.freeze({ file: 'src/planrun.js', name: 'NATIVE_READ_STRATEGY' }),
+
+  // src/authoring.js — the types-genre close template, interpolated verbatim
+  // into the authoring prompt (src/authorflow.js's assembled system message,
+  // "THE GENRE TEMPLATE" block) — model-facing law for a types-genre
+  // declaration, not merely internal genre-table data. Found missing from
+  // this inventory 2026-09-15 (item 6 close-out); no other exported const or
+  // inline template literal in this file carries prompt/instruction text.
+  Object.freeze({ file: 'src/authoring.js', name: 'TYPES_GENRE_TEMPLATE' }),
 ]);
 
 /** The distinct file paths carrying prompt registers, repo-root-relative with

package/src/providers.js

@@ -201,6 +201,42 @@ export function resolveProvider(providerName) {
   return entry;
 }
 
+/**
+ * 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) {
+  if (/[\r\n]/.test(value)) return 'contains a line break';
+  if (/\t/.test(value)) return 'contains a tab character';
+  // eslint-disable-next-line no-control-regex -- deliberately scanning C0/DEL controls
+  if (/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(value)) return 'contains a control character';
+  if (value !== value.trim()) return 'has leading or trailing whitespace';
+  return null;
+}
+
 /**
  * Construct ONE provider instance for `providerName`/`model`, applying
  * `exposeErrorBody: true` (F153 — every constructed provider, unconditionally)

package/src/replayio.js

@@ -0,0 +1,153 @@
+// PANEL-BUILD.md P0 — the spine/gate-audit READ side. Lifted out of
+// `scripts/run-replay.mjs` (verbatim logic, moved so it is callable
+// in-process rather than only as a script) plus one more reader
+// (`readHistoryLog`) for `bareloop history`'s bundle-registry file. This
+// module is the IO layer ONLY: it resolves paths, parses JSONL tolerantly
+// (a malformed line is counted and skipped, never thrown on), and hands
+// parsed records to `src/replay.js`'s pure `replayRun`/`formatReplay`/
+// `summarizeForAllLine`/`formatAllLines` — it never recomputes anything
+// those already derive (PANEL-BUILD.md P0: "feed replay.js, never
+// duplicate it").
+//
+// NAME-AGNOSTIC spine detection (coordinator fix, 2026-08-25, carried over
+// verbatim from the script this replaces): the patient corpus does not agree
+// on a filename convention — `u-<id>.jsonl` (run-u), `battery-A1-<id>.jsonl`
+// / `l2accept-L1-<id>.jsonl` (batteries), `layer-r-probe-P1-<id>.jsonl`,
+// `types-screen-C-<id>.jsonl`, `reuse-<id>.jsonl` (first record
+// `reuse-start`), `job2-<id>.jsonl` all measured across the real archive. A
+// spine is therefore identified by CONTENT, never by a naming pattern: any
+// `*.jsonl` that is not a gate-audit/lag sidecar BY NAME
+// (`*-gate-audit.jsonl`, `*.lag.jsonl` — the one convention that IS
+// universal, because every spine resolves its own audit sibling this same
+// way) and whose records include at least one `job-start` or `run-start` is
+// a spine. A `.jsonl` that matches neither test is reported as
+// `<name> not-a-spine` — never silently dropped, never silently misread as
+// an empty/unknown run.
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { replayRun, summarizeForAllLine } from './replay.js';
+
+/**
+ * Parse one JSONL file into records, tolerant of a malformed line (counted
+ * in `skipped`, never thrown on). Mirrors `scripts/behaviour-readout.mjs`'s
+ * own parse.
+ * @param {string} file
+ * @returns {{records: any[], skipped: number}}
+ */
+export function parseJsonl(file) {
+  const raw = readFileSync(file, 'utf8');
+  const lines = raw.split('\n').filter((l) => l.trim() !== '');
+  /** @type {any[]} */
+  const records = [];
+  let skipped = 0;
+  for (const line of lines) {
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { records, skipped };
+}
+
+/**
+ * `true` when `name` (a bare filename, not a path) is a gate-audit or lag
+ * sidecar by NAME convention — the one filename rule that holds across the
+ * whole archive.
+ * @param {string} name
+ */
+export function isSidecarByName(name) {
+  return name.endsWith('-gate-audit.jsonl') || name.endsWith('.lag.jsonl');
+}
+
+/**
+ * `true` when `records` carries at least one `job-start` (present on every
+ * real spine checked, first record or not — a reuse/battery run nests one or
+ * more ordinary `runJob` calls inside it) or `run-start` (ralph's own inner
+ * loop marker, present on most but not all real spines).
+ * @param {any[]} records
+ */
+export function looksLikeSpine(records) {
+  return records.some((r) => r && (r.type === 'job-start' || r.type === 'run-start'));
+}
+
+/**
+ * `<name>.jsonl` → `<name>-gate-audit.jsonl` in the same directory, and the
+ * bare run id for display — the run id lives only in the filename (no spine
+ * record carries it; see `src/replay.js`'s header). A leading `u-` (the
+ * run-u convention) is stripped; every other prefix (`battery-A1-`,
+ * `reuse-`, …) is kept verbatim, since it is the only thing distinguishing
+ * that run from its siblings in the same directory.
+ * @param {string} spinePath
+ * @returns {{runId: string, auditPath: string|null}}
+ */
+export function resolveSiblings(spinePath) {
+  const dir = dirname(spinePath);
+  const base = basename(spinePath);
+  const stem = base.replace(/\.jsonl$/, '');
+  const runId = stem.startsWith('u-') ? stem.slice(2) : stem;
+  const auditPath = join(dir, `${stem}-gate-audit.jsonl`);
+  return { runId, auditPath: existsSync(auditPath) ? auditPath : null };
+}
+
+/**
+ * Read one run's spine (+ its gate-audit sidecar, when present) off disk and
+ * hand both to {@link replayRun}. Read-only, $0, mints no verdict.
+ * @param {string} spinePath absolute or cwd-relative path to a `.jsonl` spine
+ * @param {{preParsedSpine?: {records: any[], skipped: number}, skipAudit?: boolean}} [opts]
+ *   `preParsedSpine`: avoids a second parse of the same file when the caller
+ *   ({@link listSpines}) already read it once to run {@link looksLikeSpine}.
+ *   `skipAudit` (PR #23 review item 5, 2026-08-26, carried over): a
+ *   directory listing never opens the gate-audit sidecar at all —
+ *   `summarizeForAllLine` reads none of the fields that sidecar feeds inside
+ *   `replayRun`, so reading every run's sidecar in a directory listing was
+ *   pure unused I/O, multiplied by every spine found.
+ * @returns {ReturnType<typeof replayRun>}
+ */
+export function replayOne(spinePath, opts = {}) {
+  const { preParsedSpine, skipAudit = false } = opts;
+  const { runId, auditPath } = resolveSiblings(spinePath);
+  const spine = preParsedSpine ?? parseJsonl(spinePath);
+  const audit = (!skipAudit && auditPath) ? parseJsonl(auditPath) : { records: [], skipped: 0 };
+  const summary = replayRun(spine.records, audit.records, { runId });
+  summary.skipped += spine.skipped + audit.skipped;
+  return summary;
+}
+
+/**
+ * List every spine found directly in `dir` (not recursive — same as the
+ * script this replaces): one entry per `.jsonl` file that is not a sidecar
+ * by name, each either `{kind:'spine', row}` ({@link summarizeForAllLine}'s
+ * row) or `{kind:'not-a-spine', name}` when the file's content doesn't look
+ * like a spine. Feeds `formatAllLines` (`src/replay.js`) for the printed
+ * table — this function does no formatting of its own, only IO + detection.
+ * @param {string} dir
+ * @returns {Array<{kind: 'spine', row: ReturnType<typeof summarizeForAllLine>}|{kind: 'not-a-spine', name: string}>}
+ */
+export function listSpines(dir) {
+  const candidates = readdirSync(dir)
+    .filter((f) => f.endsWith('.jsonl') && !isSidecarByName(f))
+    .sort();
+  return candidates.map((f) => {
+    const path = join(dir, f);
+    const spine = parseJsonl(path);
+    if (!looksLikeSpine(spine.records)) return { kind: /** @type {const} */ ('not-a-spine'), name: f };
+    const summary = replayOne(path, { preParsedSpine: spine, skipAudit: true });
+    return { kind: /** @type {const} */ ('spine'), row: summarizeForAllLine(summary) };
+  });
+}
+
+/**
+ * Read a bundle's `history.jsonl` (one `bareloop run` row per line, written
+ * by `appendHistory` in `src/bundle.js`) — the single reader for this file,
+ * replacing `src/cli.js`'s own hand-rolled `readFileSync`/split. Tolerant of
+ * a malformed line the same way {@link parseJsonl} is (counted in
+ * `skipped`, never thrown on).
+ * @param {string} file absolute path to `history.jsonl`
+ * @returns {{rows: any[], skipped: number}}
+ */
+export function readHistoryLog(file) {
+  const { records, skipped } = parseJsonl(file);
+  return { rows: records, skipped };
+}

package/src/reuse.js

@@ -805,7 +805,7 @@ function readGradeSeed(seen) {
  * abandoned attempt twice in a chain of resumes.
  *
  * @param {any[]} events the dead spine's events, parsed, in file order
- * @param {{deathAt?: number|null, direct?: boolean, resumableOutcomes?: string[]}} [opts]
+ * @param {{deathAt?: number|null, direct?: boolean, resumableOutcomes?: readonly string[]}} [opts]
  *   `deathAt`: when the process is judged to have died (the watchdog's kill record,
  *   which is later and better evidence than the last event). Defaults to the last
  *   event's own timestamp — the last sign of life there is.

package/src/run.js

@@ -204,7 +204,7 @@ async function primitiveSmoke(workdir) {
  *        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.)
- * @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 (accept | rerun <text> | pause), carried by the leg that
  *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
  *   ordinary run; never authored and never defaulted (a defaulted answer to "is this

package/src/source.js

@@ -23,7 +23,7 @@
 // on rather than catch.
 
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { mkdir, readdir, readFile, writeFile, lstat, stat, chmod, access, copyFile, cp, open, rm, realpath, readlink, symlink, constants as fsConstants } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep, basename } from 'node:path';
 import { git } from './kinds.js';
@@ -76,6 +76,43 @@ const MAX_SAME_DAY = 99;
 /** @param {string} code @param {string} stop @returns {SourceRefusal} */
 const refuse = (code, stop) => ({ stop, code });
 
+/**
+ * F177 / hamr's ruling (2026-09-14, option A): a `kind: 'repo'` copy's own
+ * `node_modules/` stays hidden from `changedSet` (src/kinds.js) even when the
+ * SOURCE repo's tracked `.gitignore` does not mention it — the person
+ * installs packages into the copy themselves (`missingDependencies`,
+ * `source-deps-missing`), and an unignored `node_modules` then reads as 247
+ * files of "the worker's own writes" (live-verified against a real copy of
+ * pulselog). The fix writes into the copy's PRIVATE exclude file
+ * (`.git/info/exclude`, resolved via `--git-path` rather than assumed —
+ * worktree layouts keep it in the common dir, not the per-worktree one) —
+ * never the tracked `.gitignore` — so the source repo's own files, including
+ * its `.gitignore` bytes, are never touched. Idempotent: an existing
+ * `node_modules/` line is left alone rather than duplicated.
+ *
+ * Plain folder/file/URL sources never call this — they have no `.git` of
+ * their own to carry a private exclude, and (M2b fix 6, above) their
+ * `.gitignore` is deliberately powerless over what the seed holds at all.
+ * @param {string} treeDir
+ * @returns {Promise<SourceRefusal|null>}
+ */
+async function hideNodeModulesInCopy(treeDir) {
+  const gp = await git(treeDir, ['rev-parse', '--git-path', 'info/exclude']);
+  if (!gp.ok) return refuse('source-git-failed', `git rev-parse --git-path info/exclude failed in ${treeDir}: ${gp.err}`);
+  const excludeRel = gp.out.trim().split('\n')[0].trim();
+  if (!excludeRel) return refuse('source-git-failed', `git rev-parse --git-path info/exclude returned nothing in ${treeDir}`);
+  const excludePath = join(treeDir, excludeRel);
+  await mkdir(dirname(excludePath), { recursive: true });
+  let existing = '';
+  try { existing = await readFile(excludePath, 'utf8'); } catch { /* no exclude file yet — created fresh below */ }
+  const hasLine = existing.split('\n').some((l) => l.trim() === 'node_modules/');
+  if (!hasLine) {
+    const sep = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    await writeFile(excludePath, `${existing}${sep}node_modules/\n`);
+  }
+  return null;
+}
+
 /**
  * Walk from `startDir` upward — inclusive — to the NEAREST ancestor whose own
  * directory carries a `.git` entry, whether that entry is a real repo
@@ -611,6 +648,10 @@ export async function prepareSource({ source, into, destination, fetchTimeoutMs
     // strip the copied hooks (see NO_HOOKS above) — `force: true` because a
     // repo with no hooks configured has no `hooks/` to remove at all
     await rm(join(treeDir, '.git', 'hooks'), { recursive: true, force: true });
+    // F177: hide the copy's own future `node_modules/` before the seed is
+    // committed below — see `hideNodeModulesInCopy`'s docstring
+    const hideStop = await hideNodeModulesInCopy(treeDir);
+    if (hideStop !== null) return hideStop;
   }
   await mkdir(outputDir, { recursive: true });
   // git tracks no empty directories — a `.gitkeep` is what makes `output/`
@@ -712,6 +753,102 @@ export async function prepareSource({ source, into, destination, fetchTimeoutMs
   return { stop: null, into: intoAbs, tree: treeDir, manifestPath, manifest };
 }
 
+/**
+ * The install command a lockfile in `dir` implies — checked in a fixed order
+ * so a tree carrying more than one lockfile still picks exactly one command,
+ * deterministically. `npm install` (no lockfile match) is the fallback, never
+ * a refusal — a repo can legally have dependencies with no committed
+ * lockfile.
+ * @type {ReadonlyArray<{file: string, command: string}>}
+ */
+const LOCKFILE_COMMANDS = Object.freeze([
+  Object.freeze({ file: 'package-lock.json', command: 'npm ci' }),
+  Object.freeze({ file: 'npm-shrinkwrap.json', command: 'npm ci' }),
+  Object.freeze({ file: 'pnpm-lock.yaml', command: 'pnpm install --frozen-lockfile' }),
+  Object.freeze({ file: 'yarn.lock', command: 'yarn install --frozen-lockfile' }),
+  Object.freeze({ file: 'bun.lockb', command: 'bun install --frozen-lockfile' }),
+  Object.freeze({ file: 'bun.lock', command: 'bun install --frozen-lockfile' }),
+]);
+
+/**
+ * THE INSTALL-GAP DETECTOR (PRD item 33 close-out, `docs/product/PRD.md:450-452`,
+ * hamr's ruling 2026-09-14, option A): `prepareSource` copies ONLY git-tracked
+ * files (hamr's ruling, `docs/product/ITEM33-BUILD.md:225-239` — unchanged by
+ * this function), so a JS/TS repo's prepared copy never carries `node_modules`,
+ * and every close stage needing a tool (`tsc`, a test runner) instrument-stops
+ * with nothing telling the person why. bareloop NEVER runs an install itself —
+ * it only ever touches gated primitives, and a shell-out to `npm`/etc from
+ * inside this module would be exactly the verb hamr's law reserves for the
+ * worker's own granted tools, never the arbiter-side machinery that decides
+ * whether a run even starts. This is a pure, $0 DETECTOR: it names the gap and
+ * the exact command a person runs THEMSELVES in the copy, then returns.
+ *
+ * JS/TS ONLY for now — a repo in another detected language returns `null`
+ * here unconditionally (no `package.json` to find), which is the correct
+ * "nothing to report" reading, not a gap in this function; per-language
+ * dependency-gap data for other languages is M3b's job
+ * (`docs/product/ITEM33-BUILD.md`, "M3b"), not this one's.
+ *
+ * SUBFOLDER-AS-REPO (ruling 2 addendum, commit 2a020d8): a subfolder job
+ * freezes the WHOLE repo, so `package.json` may sit at the repo root, at the
+ * subfolder itself, or anywhere between — the SAME nearest-manifest-walking-up
+ * rule `detectLanguage` (`src/detectlang.js`) applies, done independently here
+ * (not by importing `detectLanguage`) to avoid a `source.js` ⇄ `detectlang.js`
+ * import cycle, since `detectlang.js` already imports `nearestGitAncestor`
+ * from this module.
+ *
+ * @param {string} treeDir the prepared tree's root (`prepareSource`'s
+ *   returned `tree`, e.g. `<into>/tree` — a REPO source sits directly at this
+ *   root; every other kind sits under `input/` inside it and has no repo
+ *   dependency story yet, so callers only need this for a `kind: 'repo'`
+ *   manifest)
+ * @param {string} [sourceSubdir] the manifest's own `sourceSubdir` ('' or
+ *   undefined when Source IS the repo root)
+ * @returns {{manager: string, command: string, reason: string}|null} `null`
+ *   when there is nothing to report: no JS/TS manifest found walking up from
+ *   `sourceSubdir` to `treeDir`, the nearest one found has no dependencies,
+ *   `node_modules` is already there, or the manifest cannot even be read as
+ *   JSON (an invalid `package.json` is "cannot tell", never a false alarm).
+ */
+export function missingDependencies(treeDir, sourceSubdir = '') {
+  const root = resolve(treeDir);
+  let dir = sourceSubdir ? resolve(root, sourceSubdir) : root;
+  /** @type {string[]} */
+  const chain = [];
+  for (;;) {
+    chain.push(dir);
+    if (dir === root) break;
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root — safety only, never reachable under `root`
+    dir = parent;
+  }
+
+  for (const d of chain) {
+    const pkgPath = join(d, 'package.json');
+    if (!existsSync(pkgPath)) continue;
+    let pkg;
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    } catch {
+      return null; // cannot tell — an invalid package.json is not a fabricated gap
+    }
+    if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) return null;
+    const depCount = Object.keys(pkg.dependencies ?? {}).length + Object.keys(pkg.devDependencies ?? {}).length;
+    if (depCount === 0) return null; // a manifest with nothing to install is not a gap
+    if (existsSync(join(d, 'node_modules'))) return null;
+
+    const lock = LOCKFILE_COMMANDS.find((l) => existsSync(join(d, l.file)));
+    const installCmd = lock ? lock.command : 'npm install';
+    const rel = relative(root, d).split(sep).join('/');
+    return {
+      manager: installCmd.split(' ')[0],
+      command: rel === '' ? installCmd : `cd ${rel} && ${installCmd}`,
+      reason: `${rel === '' ? 'package.json' : `${rel}/package.json`} lists dependencies but the copy has no node_modules`,
+    };
+  }
+  return null;
+}
+
 /**
  * The delivered name (M2b fix 4, kept under D3): a destination FILE of
  * `/home/me/profile.md` lands as `/home/me/profile-2026-09-12.md`, and a