bareloop 0.2.0 → 0.4.0

package/src/ralph.js

@@ -8,7 +8,35 @@ import { spawnSync } from 'node:child_process';
 
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
- * 0 → satisfied; nonzero → needs_revision (gap fed back); spawn error → failed (terminal).
+ * `expect` → satisfied; any other exit → needs_revision (gap fed back).
+ *
+ * THE FORBIDDEN ZONE (PRD v1.11, F17; adaptlearn F25/V10). The two clean bands
+ * are green (exit == expect, judgment rendered) and red (exit != expect,
+ * judgment rendered). Every other outcome rendered NO JUDGMENT and is therefore
+ * NOT A VERDICT — it gets its own name and escalates; coercing one into a
+ * verdict IS the instrument fault (law #8 generalized):
+ *   - `failed`    — the close cannot RUN (spawn error).             → broken-close
+ *   - `timed-out` — it ran and never finished judging.              → close-timeout
+ *   - `killed`    — it died by signal (status null, no spawn error). → close-killed
+ *   - `crashed`   — it ran, exited, and judged nothing.             → close-crashed
+ * `timed-out` is split OUT of `failed` deliberately: "raise the timeout" and
+ * "fix the argv" are different human decisions, so pooling them erases the
+ * decision information the escalation exists to carry.
+ *
+ * `judged` is the judgment-rendered signal, and it is the hard one. Exit code
+ * ALONE cannot separate a crash-at-load from an honest red — they are
+ * byte-identical at this seam, and against `node --test` so are the test counts
+ * (node synthesizes ONE failing test for the file that crashed, so a crash
+ * reports `tests 1 / fail 1`, exactly like a one-assertion failure). So the
+ * signal cannot be "zero judged"; it must be a FLOOR against a declared
+ * baseline: litectx runs ~390 tests, and a run claiming it judged 1 did not
+ * judge. `judged.pattern` extracts one integer from the close's own (redacted)
+ * output; below `judged.min` the close crashed, WHATEVER its exit code says —
+ * and that check runs on the GREEN side too: a close that exits 0 having judged
+ * nothing is a confident fake green, the only real failure there is (law #8).
+ * `judged` is OPTIONAL — a linter or a hitl close may have no count to give —
+ * and its absence stamps `unaudited: true` so the blind spot is NAMED on the
+ * record rather than passed off as a trustworthy exit code.
  *
  * `redact` scrubs the close's own output at the SOURCE — before the gap becomes
  * a spine event or a worker prompt — so a secret a checked command echoes
@@ -18,22 +46,179 @@ import { spawnSync } from 'node:child_process';
  * primitive (bareguard's, wired by the interpreter), never an emergent
  * component — so V4 holds. The shell's canonical emission IS the redacted text;
  * a benign gap is returned byte-identical (default: identity).
+ * `cwd` is where the close RUNS, and it is load-bearing (F8): a close is a
+ * command in a repository — `npm test`, `make check` — and every one of them is
+ * cwd-relative. Run it anywhere but the workdir and the arbiter judges the wrong
+ * tree: exit-code-is-truth silently becomes exit-code-of-some-other-repo-is-truth.
+ * The default (the runner's own cwd) exists only for callers with an absolute
+ * close; the runner and the interpreter always pass the workdir.
+ *
+ * `gapKeep` (F28) is a regex SOURCE whose matching lines are PRESERVED through
+ * the gap bound in addition to the head/tail sample: a large TAP suite prints
+ * its `not ok` lines in the middle of the stream, exactly where `boundGap`
+ * elides — so the failing-test NAMES (the causal input the worker navigates on)
+ * were deleted in transit and the worker was told "5 fail" and never WHICH. It
+ * is arbiter territory like the rest here: the drafted config cannot express it.
+ *
  * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
  * @param {(s: string) => string} [redact] source scrubber; identity by default
+ * @param {{ timeoutMs?: number, cwd?: string, expect?: number, judged?: {pattern: string, min: number}, gapKeep?: string }} [opts]
+ *   close wall-clock cap (operator-set via the runner, never the config's — the
+ *   agent must not author its arbiter's clock), the directory the close runs in
+ *   (the workdir — the tree it is judging), the exit code the SIGNED spec calls
+ *   success, the judgment-rendered signal, and the kept-failures pattern. All
+ *   five are arbiter territory: the drafted workflow config cannot express any.
+ * @returns {{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
+ *   gap?: string, exitCode?: number, signal?: string, detail?: string,
+ *   judgedCount?: number|null, unaudited?: boolean}}
  */
-export function runClose(close, redact = (s) => s) {
+export function runClose(close, redact = (s) => s, { timeoutMs = 120_000, cwd, expect = 0, judged, gapKeep } = {}) {
   const env = { ...process.env };
   delete env.NODE_TEST_CONTEXT; // a `node --test` close inherits this from a test runner and silently no-ops — a fake green
-  const r = spawnSync(close[0], close.slice(1), { env, encoding: 'utf8', timeout: 120_000 });
-  if (r.error) return { verdict: 'failed', detail: String(r.error) };
-  if (r.status === 0) return { verdict: 'satisfied' };
+  const r = spawnSync(close[0], close.slice(1), { env, cwd, encoding: 'utf8', timeout: timeoutMs });
+
+  // ── forbidden zone, before any exit code is believed ──────────────────────
+  if (r.error) {
+    // spawnSync reports BOTH "cannot run" and "ran too long" through `error`;
+    // they are different human decisions, so they get different names.
+    const code = /** @type {NodeJS.ErrnoException} */ (r.error).code;
+    if (code === 'ETIMEDOUT') return { verdict: 'timed-out', detail: `close exceeded ${timeoutMs}ms and was killed — it never finished judging` };
+    return { verdict: 'failed', detail: String(r.error) };
+  }
+  // No spawn error and no exit status: the close died by signal (OOM, an
+  // external kill). It did not fail — it never rendered an opinion.
+  if (r.status === null) {
+    return { verdict: 'killed', signal: r.signal ?? undefined, detail: `close died by signal ${r.signal ?? 'unknown'} — no judgment was rendered` };
+  }
+
+  // Redact at the SOURCE, before anything is read back: the count is extracted
+  // from scrubbed text, so a secret in the close's output can never ride out on
+  // the judged path any more than it can on the gap path (the hard line).
+  const out = redact(r.stdout || '');
+  const err = redact(r.stderr || '');
+
+  // ── the judgment-rendered signal: did this close actually judge anything? ──
+  // Checked on BOTH bands — an exit-0 close that judged nothing is a fake green.
+  let judgedCount;
+  if (judged) {
+    const m = new RegExp(judged.pattern, 'm').exec(`${out}\n${err}`);
+    const n = m ? Number(m[1]) : NaN;
+    judgedCount = Number.isFinite(n) ? n : null; // honest null: no number rendered (F6)
+    if (judgedCount === null || judgedCount < judged.min) {
+      return {
+        verdict: 'crashed', judgedCount, exitCode: r.status,
+        detail: `close judged ${judgedCount ?? 'nothing'} of a declared floor of ${judged.min} — it exited ${r.status} without rendering judgment (a crash, not a verdict)`,
+      };
+    }
+  }
+
+  if (r.status === expect) return { verdict: 'satisfied', ...(judged ? { judgedCount } : { unaudited: true }) };
   // The gap must never be falsy: every consumer guards with `if (gap)` — an
   // empty-output red would silently kill gap feedback, after-red hooks, AND
   // stall detection, leaving the worker re-prompted byte-identically to the cap.
-  // Redact BEFORE slicing so a token straddling the 2000-char bound can't survive.
-  return { verdict: 'needs_revision', gap: redact(r.stderr || r.stdout || '').slice(0, 2000) || '(close exited nonzero with no output)', exitCode: r.status };
+  // Bound AFTER redaction so a token straddling the bound can't survive.
+  // BOTH streams, not one (F28 hazard): the old `err || out` returned stderr
+  // ALONE whenever it was non-empty, so a close writing its `not ok` lines to
+  // stdout while emitting any stderr noise lost the failures entirely, before
+  // the bound ever ran. Combine them (out then err, matching the judged path's
+  // `${out}\n${err}`); both empty still falls to the no-output message.
+  const combined = [out, err].filter(Boolean).join('\n');
+  return {
+    verdict: 'needs_revision',
+    gap: boundGap(combined, gapKeep) || `(close exited ${r.status}, expected ${expect}, with no output)`,
+    exitCode: r.status,
+    ...(judged ? { judgedCount } : { unaudited: true }),
+  };
+}
+
+// Tail-biased bound: a test runner's useful output (the assertion diff, the
+// failing case name) is at the END; head-only truncation fed the worker the
+// preamble and dropped the cause (N2 queue, F2). Head sample kept so "what ran"
+// stays visible; the truncation marker is hygiene, not load-bearing (F3).
+const GAP_HEAD = 400, GAP_TAIL = 1500;
+// The keep-block cap (F28): a large suite's `not ok` lines live in the elided
+// middle, so gapKeep re-surfaces them — but a pathological close (thousands of
+// matching lines) could rebuild the very 67KB bloat the bound exists to prevent.
+// Hard-capped by BOTH lines and bytes, whichever binds first; when the cap trims
+// matches it says so with an explicit marker — silent truncation is the disease
+// this whole fix cures (F28), never a cure that truncates silently in turn.
+const GAP_KEEP_MAX_LINES = 50, GAP_KEEP_MAX_BYTES = 8192;
+// The exact phrase the trim announcement carries when kept failures are dropped
+// by the cap above. Exported so Layer R's detector (src/root.js) keys off the
+// SAME string the shell emits — a magic string on the reading side would drift
+// silently the day this wording changes (the blind-instrument class). Reference
+// only: the shell's behavior is unchanged, the label below is byte-identical.
+export const GAP_KEEP_TRIM_MARKER = 'more elided by the';
+
+/**
+ * Bound an over-long close stream to a head sample + elided middle + tail. When
+ * `keepPattern` is set (F28), lines of the WHOLE stream matching it are also
+ * carried in a clearly-delimited block between head and tail — capped — so the
+ * failing-test names buried in the middle still reach the worker.
+ * @param {string} s the (redacted) close output
+ * @param {string} [keepPattern] regex source; matching lines survive the elision
+ */
+function boundGap(s, keepPattern) {
+  if (s.length <= GAP_HEAD + GAP_TAIL + 100) return s;
+  const head = s.slice(0, GAP_HEAD);
+  const tail = s.slice(-GAP_TAIL);
+  const elided = s.length - GAP_HEAD - GAP_TAIL;
+  const base = `${head}\n…[${elided} chars truncated]…`;
+  if (!keepPattern) return `${base}\n${tail}`;
+
+  // Scan the WHOLE stream, keep matching lines in original order, cap by lines
+  // AND bytes. `re.test` with no `g` flag is stateless, so reuse is safe.
+  const re = new RegExp(keepPattern, 'm');
+  /** @type {string[]} */
+  const matched = [];
+  let bytes = 0, trimmed = 0;
+  for (const line of s.split('\n')) {
+    if (!re.test(line)) continue;
+    if (matched.length >= GAP_KEEP_MAX_LINES || bytes + line.length + 1 > GAP_KEEP_MAX_BYTES) { trimmed += 1; continue; }
+    matched.push(line);
+    bytes += line.length + 1;
+  }
+  if (!matched.length) return `${base}\n${tail}`; // pattern matched nothing — behave as the plain bound
+  const label = `kept failures matching /${keepPattern}/ (${matched.length}${trimmed ? `, ${trimmed} ${GAP_KEEP_TRIM_MARKER} ${GAP_KEEP_MAX_LINES}-line/${GAP_KEEP_MAX_BYTES}-byte cap` : ''})`;
+  return `${base}\n── ${label} ──\n${matched.join('\n')}\n── end kept failures ──\n${tail}`;
 }
 
+/**
+ * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the
+ * close rendered NO JUDGMENT — so it is not a verdict, it never feeds a gap
+ * back, and it is never retried. They are kept SEPARATE on purpose: pooling
+ * them would erase the decision information the escalation exists to carry —
+ * "raise the timeout", "fix the argv", and "re-run, it was OOM-killed" are
+ * three different human answers.
+ * Exported because the RUNNER's close-first precheck runs the same arbiter
+ * before any tokens: two maps would be two instruments, and two instruments
+ * disagreeing about the same outcome is the fault this whole addendum exists
+ * to close.
+ * @type {Record<string, {category: string, decision: string, options: string[]}>}
+ */
+export const CLOSE_FAULTS = Object.freeze({
+  failed: {
+    category: 'broken-close',
+    decision: 'The close itself cannot run — no verdict is trustworthy until it is fixed.',
+    options: ['fix the close command', 'abandon the task'],
+  },
+  'timed-out': {
+    category: 'close-timeout',
+    decision: 'The close ran but never finished judging — it hit the timeout and was killed. It did not fail; it did not answer.',
+    options: ['raise the close timeout', 'make the close faster', 'abandon the task'],
+  },
+  killed: {
+    category: 'close-killed',
+    decision: 'The close died by signal (OOM, or an external kill) — it rendered no judgment, so its exit tells you nothing about the tree.',
+    options: ['re-run (a transient kill)', 'fix the close environment (memory, sandbox limits)', 'abandon the task'],
+  },
+  crashed: {
+    category: 'close-crashed',
+    decision: 'The close exited without judging anything — it crashed rather than failed. Its exit code is NOT a verdict, in either direction.',
+    options: ['fix what makes the close crash at startup', 'fix the close argv', 'lower the declared judgment floor if the suite legitimately shrank', 'abandon the task'],
+  },
+});
+
 /**
  * The loop: `while close-red and under-cap: run the middle`. Stops at first
  * green (within-run tuning past a visible close is the fit-to-pass surface,
@@ -55,10 +240,28 @@ export function runClose(close, redact = (s) => s) {
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
  * @param {(s: string) => string} [opts.redact] source scrubber for close output
  *   (secrets never enter the spine); injected so the shell stays stdlib-only
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell/operator
+ *   territory — the workflow config cannot express it)
+ * @param {string} [opts.cwd] the directory every close runs in — the tree it is
+ *   judging (F8: a cwd-relative close run elsewhere judges the wrong repository)
+ * @param {number} [opts.expect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.judged] the judgment-rendered signal
+ * @param {string} [opts.gapKeep] kept-failures pattern (F28): matching close-output
+ *   lines survive the gap bound so a large suite's `not ok` names reach the worker
+ * @param {() => string[]} [opts.workerWrites] the crash-attribution instrument (F32):
+ *   answers "which files has the WORKER written so far this run?" — the runner wires
+ *   it to the gate audit's allow-decision writes. Injected like `redact` so the shell
+ *   stays stdlib-only and dumb; consulted ONLY at a crashed verdict. With no seam, or
+ *   with zero writes, a crash stays what it always was: an instrument stop.
  * @returns {Promise<'green'|'escalated'>}
  */
-export async function ralph({ middle, close, capRuns, emit, redact }) {
+export async function ralph({ middle, close, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }) {
   emit('run-start', { capRuns, close: close.join(' ') });
+  // The blind spot is NAMED, never hidden: with no judgment-rendered signal this
+  // close cannot tell a crash from an honest red (they are byte-identical at the
+  // exit-code seam), so the record says so out loud rather than passing the exit
+  // code off as trustworthy (PRD v1.11).
+  if (!judged) emit('close-unaudited', { close: close.join(' '), meaning: 'no judgment-rendered signal declared — a crash-at-load is indistinguishable from an honest red for this close' });
   const verdicts = [];
   let gap;
   for (let iteration = 1; iteration <= capRuns; iteration++) {
@@ -74,6 +277,8 @@ export async function ralph({ middle, close, capRuns, emit, redact }) {
           ['raise the cap and rerun', 'change the middle/harness', 'abandon the task']],
         'gate-red': ['The gate denied an action mid-run — the harness asked for something outside its scope.',
           ['widen the write scope deliberately', 'change the middle/harness', 'abandon the task']],
+        'provider-red': ['The provider path failed mid-run (transport, not logic) — no verdict exists and the spend for the failed call is unknown (F6).',
+          ['retry the run', 'fix the provider binding', 'abandon the task']],
       };
       // Object.hasOwn, not bare lookup: a category named after an
       // Object.prototype member ("toString") would return the inherited
@@ -84,26 +289,51 @@ export async function ralph({ middle, close, capRuns, emit, redact }) {
       emit('escalation', {
         category, decisionReady: true, verdicts,
         spend: { runs: iteration, capRuns },
+        // the thrower names its OWNER too when it knows one (interpret's worker
+        // loop → bare-agent): the ledger prefers the typed field over sniffing
+        // this detail string for library names
+        ...(e && typeof e.lib === 'string' ? { lib: e.lib } : {}),
         decision, options, detail: String(e.message || e),
       });
       emit('run-end', { outcome: 'escalated', iterations: iteration });
       return 'escalated';
     }
     emit('middle-done', { iteration });
-    const v = runClose(close, redact);
-    verdicts.push(v.verdict);
+    const v = runClose(close, redact, { timeoutMs: closeTimeoutMs ?? 120_000, cwd, expect, judged, gapKeep });
+    // Worker-crash attribution (F32, measured in F31: 4 of 7 battery rows). A crash is
+    // still not a verdict (F17) — but a crash that FOLLOWS worker writes, on a run whose
+    // precheck proved the close judged at baseline (run.js escalates a crash-at-precheck
+    // before any tokens), is the worker's own broken edit: the most recoverable red there
+    // is, and the one red this loop could never feed back. The close's raw reading stays
+    // 'crashed' on the record; the ROUTING is what attribution changes. Decided before
+    // the satisfied check so an exit-0 crash (fake green, law #8) is caught the same way.
+    const crashFiles = v.verdict === 'crashed' && workerWrites ? workerWrites() : [];
+    const workerCrashed = crashFiles.length > 0;
+    verdicts.push(workerCrashed ? 'worker-crash' : v.verdict);
     emit('close-verdict', { iteration, ...v });
     if (v.verdict === 'satisfied') {
       emit('run-end', { outcome: 'green', iterations: iteration });
       return 'green';
     }
-    if (v.verdict === 'failed') {
+    if (workerCrashed) {
+      emit('worker-crash', { iteration, category: 'worker-crash', files: crashFiles, detail: v.detail });
+      // the file list is bounded and the trim ANNOUNCED — silent truncation is the F28 disease
+      const shown = crashFiles.slice(0, 30);
+      const more = crashFiles.length - shown.length;
+      gap = `Your edit CRASHED the test suite — it can no longer even load and judge (${v.detail}). `
+        + `Files you have written this run: ${shown.join(', ')}${more > 0 ? ` (and ${more} more)` : ''}. `
+        + 'Fix or revert your change so the suite can run again — nothing can pass while the suite cannot load.';
+      continue;
+    }
+    // Forbidden zone: no judgment was rendered, so there is no verdict. Escalate
+    // by the outcome's OWN name and never retry — retrying a broken arbiter is
+    // the §5b violation adaptlearn found live in its shipped shell (F25/Z-3).
+    const fault = Object.hasOwn(CLOSE_FAULTS, v.verdict) ? CLOSE_FAULTS[v.verdict] : undefined;
+    if (fault) {
       emit('escalation', {
-        category: 'broken-close', decisionReady: true, verdicts,
+        category: fault.category, decisionReady: true, verdicts,
         spend: { runs: iteration, capRuns },
-        decision: 'The close itself cannot run — no verdict is trustworthy until it is fixed.',
-        options: ['fix the close command', 'abandon the task'],
-        detail: v.detail,
+        decision: fault.decision, options: fault.options, detail: v.detail,
       });
       emit('run-end', { outcome: 'escalated', iterations: iteration });
       return 'escalated';

package/src/root.js

@@ -0,0 +1,305 @@
+// Layer R — the root: the within-run ratchet (LAYERS.md item 2; design record
+// docs/plans/2026-07-19-layer-r-design.md). One state that survives attempts
+// inside ONE run so a never-green run stops repeating itself (F21). Role is
+// CONTINUITY ONLY — F39 measured that hand-delivered state buys no conversion;
+// the semantic converter is Layer 2's job, not this module's.
+//
+// Ownership: the SHELL authors the root, mechanically, from the arbiter's own
+// books — per-attempt write-sets (the gate audit, via the F32 workerWrites
+// seam) and the close's kept-failure lines. The worker authors nothing and
+// gains no verb; delivery is injection into the next attempt's prompt, so the
+// adaptlearn-F6 write-only-decoy class is structurally excluded.
+//
+// Engagement is FIXATION-GATED (RSI-LEARNINGS §3.3: the rejected-edit buffer's
+// lift is a fixation phenomenon and an honest null on a strong model when not
+// stuck — pay only when stuck). Content ESCALATES: first detection injects a
+// capped mechanical summary; a second consecutive detection injects the
+// worker's own prior failed edit content verbatim ("write something
+// STRUCTURALLY DIFFERENT" — the BA-14 mechanism, 50%→100% under fixation).
+// Both stages fire on DIFFERENT attempts, so every stuck episode yields a
+// per-stage read for the acceptance battery.
+//
+// Scope: within-run scratch, discarded at run end — NEVER across-run memory
+// (only a green mints that, and this module touches no inheritance channel).
+// Spine events carry counts and paths only, never content: verbatim edit text
+// is worker-authored and the spine is append-only (what a log captures, it
+// captures forever).
+
+// The shell's kept-failures trim announcement (ralph): its presence in a gap means
+// failures were dropped past the gap cap, so the visible kept lines are an
+// UNRELIABLE red-set for comparison. Imported (never re-spelled) so the detector
+// keys off the exact string the shell emits — a magic string here would drift.
+import { GAP_KEEP_TRIM_MARKER } from './ralph.js';
+
+/**
+ * Strip a trailing duration stamp from a kept-failure line. Real `node --test`
+ * spec-reporter lines are NEVER byte-stable across runs (`✖ multiplies
+ * (1.738ms)` vs `(1.637ms)` — POC 2026-07-19), so naive equality reads every
+ * attempt as "reds moved" and the detector never fires. COMPARISON-ONLY: the
+ * gap the worker sees is never rewritten.
+ * @param {string} line
+ */
+export const normalizeRedLine = (line) => line.replace(/ \(\d+(?:\.\d+)?m?s\)\s*$/, '');
+
+// Bounds — every trim is ANNOUNCED in the note (F28: silent truncation is the
+// disease; a cure that truncates silently is the same disease).
+/**
+ * A teed write: the content the worker emitted, plus whether it actually reached
+ * the file. `landed` is the OUTCOME axis (Finding 7) — the gate's allow is an
+ * intent record written before the tool runs, and a shell_edit whose anchor
+ * misses returns a refusal RESULT with the file untouched (bare-agent
+ * tools/shell.js:190). A note that says "these are your changes" is a claim
+ * about the file's contents and must be true, so it reads this flag, never the
+ * audit. The DETECTOR deliberately does not: see `observe`.
+ * @typedef {{content: string, trimmed: boolean, landed: boolean}} TeeEntry
+ */
+
+const TEE_CAP_BYTES = 2000;   // per-file content retained for the verbatim stage
+const VERBATIM_MAX_FILES = 3; // files surfaced per verbatim injection
+const SUMMARY_MAX_PATHS = 10; // paths named in the summary line
+
+/**
+ * The root collector. One per run; state dies with the run.
+ *
+ * Call order (wired by the interpreter's middle):
+ *   observe({iteration: 1, writes})            → null (nothing to compare)
+ *   stageWrite(path, content)                  → stage, before the tool runs
+ *   settleWrite(landed) | discardWrite()       → the outcome, after it ran
+ *   noteWrite(path, content)                   → stage+settle, text mode (which
+ *                                                writes before it reports)
+ *   observe({iteration: N, gap, writes})       → null | {stage, note, event}
+ * `writes` is the CUMULATIVE allow-decision write/edit path list from the gate
+ * audit (the F32 instrument); the per-attempt set is the delta between calls —
+ * so a gate-DENIED write is never counted (the tool never ran at all).
+ *
+ * Finding 7 — the two axes, deliberately NOT merged. An allow-decision records
+ * what the worker REACHED FOR, which is the right instrument for "is it
+ * repeating itself"; whether those bytes reached the file is a different
+ * question, and only the note (a claim about file contents) needs it. Collapsing
+ * them either way is a bug: settling the note on the allow makes it lie, and
+ * running the detector off the file makes it blind to a worker re-firing an
+ * identical edit whose anchor never matches — measured null on every attempt.
+ *
+ * @param {{gapKeep?: string, redact?: (s: string) => string, writesInformative?: boolean}} [opts]
+ *   the signed spec's kept-failures pattern (the red-set source; without it the
+ *   detector degrades to write-overlap alone and the event says so), the shell's
+ *   secret scrubber (verbatim content is scrubbed before it rides a prompt), and
+ *   `writesInformative` (Finding 3, default true): whether the per-attempt
+ *   write-set carries information. In TOOL mode the worker CHOOSES which files to
+ *   write, so re-writing the same file is a real repetition signal; in TEXT mode
+ *   the one target is rewritten every attempt by construction, so write-overlap
+ *   is constant-true and carries none — with no red-set to compare, the detector
+ *   cannot tell repetition from progress and must stay inert (it would otherwise
+ *   steer a progressing worker off course, violating "inert when not stuck").
+ */
+export function createRoot({ gapKeep, redact = (s) => s, writesInformative = true } = {}) {
+  const keepRe = gapKeep ? new RegExp(gapKeep, 'm') : null;
+  /**
+   * The comparable red-set, or null when it CANNOT be trusted — one clean UNKNOWN
+   * covering three cases, so the detector honestly degrades to write-overlap alone
+   * rather than making the strong "reds unchanged" claim off a blind instrument:
+   *   - no gapKeep pattern at all (no red-set instrument);
+   *   - a TRIMMED window (ralph dropped failures past the cap): failures beyond the
+   *     window can move while the visible lines stay identical (Finding 5);
+   *   - zero matches on a judged gap: an empty kept-set is UNKNOWN, not "zero
+   *     failures" — [] === [] would false-read as "reds unchanged" (Finding 2).
+   * @param {string} gap @returns {string[]|null} normalized kept lines, or null when untrustworthy
+   */
+  const keptSet = (gap) => {
+    if (!keepRe || gap.includes(GAP_KEEP_TRIM_MARKER)) return null;
+    const lines = [...new Set(gap.split('\n').filter((l) => keepRe.test(l)).map(normalizeRedLine))].sort();
+    return lines.length ? lines : null;
+  };
+
+  /** @type {{writes: string[], reds: string[]|null, tee: Map<string, TeeEntry>}[]} finalized attempts */
+  const attempts = [];
+  /** @type {Set<string>} cumulative audit write-set at the last observe */
+  let prevCumulative = new Set();
+  /** @type {Map<string, TeeEntry>} tee for the attempt currently running */
+  let tee = new Map();
+  /** @type {{path: string, entry: TeeEntry}|null} the write awaiting its outcome */
+  let pending = null;
+  let streak = 0;
+
+  /**
+   * Capture a write/edit's content as PENDING — staged against the gate verdict
+   * that has not been rendered yet (Finding 6). Scrub at CAPTURE, BEFORE
+   * truncating (repo doctrine: secrets scrub at the source, and staging IS the
+   * source — a staged secret must be scrubbed even if the write is later
+   * discarded). Every SECRET_PATTERN is a prefix+min-length shape (sk-…{16,}),
+   * so a secret straddling the cap would lose the bytes that make it match and a
+   * partial token would ride the note unredacted — redact the FULL content
+   * first, then cap the already-scrubbed string.
+   * @param {string} path @param {string} content
+   */
+  const stageWrite = (path, content) => {
+    const scrubbed = redact(content);
+    const trimmed = scrubbed.length > TEE_CAP_BYTES;
+    pending = { path, entry: { content: scrubbed.slice(0, TEE_CAP_BYTES), trimmed, landed: false } };
+  };
+
+  return {
+    stageWrite,
+
+    /**
+     * The staged write RAN — record what it actually did (Finding 7). Retained
+     * either way: an attempted-but-unapplied edit is still the worker reaching
+     * for the same file, which is what the detector measures, and dropping it
+     * here would blind the ratchet to the purest fixation there is (a worker
+     * re-firing an identical edit whose anchor never matches — measured null on
+     * every attempt under a tree-diff detector, 2026-07-20). Only the NOTE's
+     * wording turns on `landed`. Last write per path wins (the tree's final
+     * state for that attempt is what failed the close).
+     * @param {boolean} landed whether the content is now in the file
+     */
+    settleWrite(landed) {
+      if (pending) tee.set(pending.path, { ...pending.entry, landed });
+      pending = null;
+    },
+
+    /**
+     * The staged write was DENIED or HALTED: it is not in the file, so it must
+     * never be surfaced as "your own change that landed". Drops the stage and
+     * leaves whatever DID land for that path untouched.
+     */
+    discardWrite() { pending = null; },
+
+    /**
+     * Stage and commit in one call — the post-allow write site (text mode
+     * gate-checks and writes before it calls this, so the verdict is already in).
+     * @param {string} path @param {string} content
+     */
+    noteWrite(path, content) {
+      stageWrite(path, content);
+      if (pending) tee.set(pending.path, { ...pending.entry, landed: true });
+      pending = null;
+    },
+
+    /**
+     * Called at the START of attempt `iteration`, with the PREVIOUS attempt's
+     * gap. Finalizes that attempt from the books, runs the detector, and
+     * returns the injection for the attempt about to run — or null (inert).
+     * @param {{iteration: number, gap?: string, writes: string[]}} o
+     * @returns {null | {stage: 'summary'|'verbatim', note: string, event: object}}
+     */
+    observe({ iteration, gap, writes }) {
+      const cumulative = new Set(writes);
+      if (!gap) { // first attempt: nothing judged yet, nothing to compare
+        prevCumulative = cumulative;
+        tee = new Map();
+        pending = null;
+        return null;
+      }
+      // finalize the attempt that just failed: its writes are the audit delta
+      const delta = [...cumulative].filter((p) => !prevCumulative.has(p));
+      // an edit to a file already written in an earlier attempt is not in the
+      // delta — the tee saw it, and a teed landed path IS this attempt's work
+      for (const p of tee.keys()) if (cumulative.has(p) && !delta.includes(p)) delta.push(p);
+      // `gap` is guaranteed truthy here (the `if (!gap) return` guard above handled
+      // the empty case); reds === null comes only from keptSet's own UNKNOWN logic.
+      attempts.push({ writes: delta, reds: keptSet(gap), tee });
+      // The detector only ever compares the last two finalized attempts, so older
+      // ones (and their teed content) are dead state — keep just the two (Finding 7).
+      if (attempts.length > 2) attempts.shift();
+      prevCumulative = cumulative;
+      tee = new Map();
+      // a stage whose verdict never arrived (the attempt ended mid-flight) is not
+      // a landed write and must not survive into the next attempt's tee
+      pending = null;
+
+      if (attempts.length < 2) return null;
+      const [prev, last] = attempts.slice(-2);
+      const overlap = last.writes.filter((p) => prev.writes.includes(p));
+      // Both UNKNOWN → no trustworthy red-set either side: write-overlap alone
+      // decides (writes-only mode, named below). One known and one UNKNOWN → the
+      // red-set is not provably the same, so it counts as MOVEMENT, never a fire
+      // (a real red-set followed by a crash/empty gap is new information, not
+      // repetition). Both known → the honest set comparison.
+      const redsSame = last.reds === null && prev.reds === null ? null
+        : last.reds === null || prev.reds === null ? false
+        : JSON.stringify(last.reds) === JSON.stringify(prev.reds);
+      // Finding 3: when writes carry no information (text mode — the one target is
+      // rewritten every attempt regardless of progress), write-overlap alone can
+      // never establish fixation; only a KNOWN-unmoved red-set can. So the
+      // degraded writes-only path (redsSame === null) is available to fire only
+      // when writes ARE informative (tool mode). With informative writes the prior
+      // behavior stands: overlap + reds-not-known-to-have-moved.
+      const redsGate = writesInformative ? redsSame !== false : redsSame === true;
+      const fixated = overlap.length > 0 && redsGate;
+      if (!fixated) { streak = 0; return null; }
+      streak += 1;
+
+      const stage = streak === 1 ? 'summary' : 'verbatim';
+      const mode = redsSame === null ? 'writes-only' : 'reds+writes';
+      const shownPaths = overlap.slice(0, SUMMARY_MAX_PATHS);
+      const morePaths = overlap.length - shownPaths.length;
+      const event = {
+        iteration, stage, mode, streak,
+        paths: shownPaths, ...(morePaths > 0 ? { pathsElided: morePaths } : {}),
+        redSetSize: last.reds ? last.reds.length : null,
+      };
+
+      // Finding 7: what the worker REACHED FOR fired the detector; what it
+      // ACHIEVED decides the wording. Only paths this attempt actually teed can
+      // answer the outcome question — a path known solely from the audit is
+      // unattributable, so it falls back to the neutral (landed) phrasing rather
+      // than guessing.
+      const attempted = overlap.filter((p) => last.tee.has(p));
+      const noneApplied = attempted.length > 0
+        && attempted.every((p) => !(/** @type {TeeEntry} */ (last.tee.get(p)).landed));
+
+      if (stage === 'summary') {
+        const redsClause = mode === 'reds+writes'
+          ? 'and the set of failing tests did not change at all'
+          : 'with no visible progress';
+        // The unapplied case is the MECHANICAL genre (F38: gaps that name a wall
+        // convert; semantic ones stall) — naming the missed anchor is strictly
+        // more actionable than "form a different hypothesis", because the
+        // hypothesis may have been right and only the anchor wrong.
+        const body = noneApplied
+          ? `Your last two attempts both tried to change ${shownPaths.join(', ')}`
+            + `${morePaths > 0 ? ` (and ${morePaths} more)` : ''} and NEITHER EDIT APPLIED — `
+            + 'the text you anchored on was not found in the file, so nothing changed. '
+            + 'Re-read the file and quote the exact text (whitespace and indentation included) before editing again.'
+          : `Your last two attempts both rewrote ${shownPaths.join(', ')}`
+            + `${morePaths > 0 ? ` (and ${morePaths} more)` : ''} ${redsClause}. `
+            + 'Do NOT retry the same change — form a DIFFERENT hypothesis before your next edit.';
+        return { stage, event, note: `RATCHET: you are repeating yourself. ${body}` };
+      }
+      // verbatim: surface the worker's own last content for the repeated paths —
+      // scrubbed, capped, every trim announced. Grouped by OUTCOME, because the
+      // two groups need opposite advice: content that landed and failed must not
+      // be written again, while content that never applied may have been the
+      // right change aimed at the wrong anchor — telling that worker to "write
+      // something structurally different" would steer it away from a correct fix.
+      const files = attempted.slice(0, VERBATIM_MAX_FILES);
+      const moreFiles = attempted.length - files.length;
+      /** @param {string} p */
+      const block = (p) => {
+        const t = /** @type {TeeEntry} */ (last.tee.get(p));
+        // t.content was already scrubbed by redact() in stageWrite before storage
+        // (Finding 6): re-redacting here is redundant work over already-masked text.
+        return `--- ${p}${t.trimmed ? ` (truncated to first ${TEE_CAP_BYTES} chars)` : ''} ---\n${t.content}`;
+      };
+      const landedFiles = files.filter((p) => /** @type {TeeEntry} */ (last.tee.get(p)).landed);
+      const unappliedFiles = files.filter((p) => !(/** @type {TeeEntry} */ (last.tee.get(p)).landed));
+      const sections = [];
+      if (landedFiles.length) {
+        sections.push('These are your OWN previous changes — they landed, and they did NOT fix the failing set:\n'
+          + landedFiles.map(block).join('\n')
+          + '\nDo not write these again. Write something STRUCTURALLY DIFFERENT, or change a different file.');
+      }
+      if (unappliedFiles.length) {
+        sections.push('This is text you tried to write, and it did NOT apply — the anchor was not found, '
+          + 'so the file is UNCHANGED and none of this is in it:\n'
+          + unappliedFiles.map(block).join('\n')
+          + '\nRe-read the file and copy the exact text you mean to replace, character for character, before editing again.');
+      }
+      return {
+        stage, event,
+        note: `RATCHET: you are STILL repeating yourself. ${sections.join('\n\n')}`
+          + (moreFiles > 0 ? `\n(and ${moreFiles} more repeated file${moreFiles > 1 ? 's' : ''}, elided)` : ''),
+      };
+    },
+  };
+}