bareloop 0.9.0 → 0.11.0

package/src/kinds.js

@@ -64,7 +64,7 @@ import { realpathSync } from 'node:fs';
 import { readFile, stat, mkdtemp, rm, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, sep } from 'node:path';
-import { globToPrefix } from './validate.js';
+import { globToPrefix, isNonEmptyString } from './validate.js';
 import { CLOSE_ENV_DENY } from './ralph.js';
 
 /** the close's two judgment exits — a stage's verdict, in the shape the
@@ -136,19 +136,56 @@ export const SIGNS = Object.freeze([1, -1]);
  * are catalogue entries and are deliberately absent here: declaring one is
  * counted demand (the request-red path), and reaching one at runtime is a
  * stop — never a red, and never a silent pass. */
-export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed']);
+export const LIVE_KINDS = Object.freeze(['command-exit', 'count-not-worse', 'pattern-absent-in-diff', 'files-changed', 'human-confirms']);
+/** RULING 8 — the stages the seed-verdict read (D12) must NOT run. A judged
+ * number at seed is unstable and a person at seed is an interview, not a
+ * measurement; their bar comes from calibration (soft-green) or from the person
+ * themselves (hitl), never from the seed. The skip is RECORDED by name rather
+ * than taken in silence (F59: absent is not empty), so `seedRead` still returns
+ * one row per declared stage. */
+export const SEED_EXEMPT_KINDS = Object.freeze(['judged-floor', 'human-confirms']);
+/** the one kind a PERSON renders — named once, because the runner keys three
+ * decisions on it (is there a door to answer, which stage paused, whose ruling
+ * this is) and three literals is how they come to disagree */
+export const HUMAN_KIND = 'human-confirms';
+/** the three doors the signer is offered at a hitl pause (2026-08-12 §1, doors
+ * re-cut 2026-08-17). No fourth door, and no free-text-only variant: a red that
+ * is not one of these two is not a ruling the run can act on.
+ *
+ * `cancel` was the third door and is DELETED as a concept (hamr: *"what's the
+ * point of cancel anyways? pause can resume — that would be more honest"*). The
+ * case it served — a person who looks and does not want to carry on — is a pause
+ * nobody returns to, which the 60-day checkpoint TTL retires on its own. Nothing
+ * here forces a forever-decision at the one moment the person has least reason
+ * to make one. */
+export const HUMAN_DECISIONS = Object.freeze(['accept', 'rerun', 'pause']);
 
 /**
  * @typedef {{code: string, path: string, detail: string}} Red
  * @typedef {{workdir: string, seedRef: string, gapKeep: string,
  *   timeoutMsDefault?: number, baselineMode?: 'auto'|'worktree',
- *   gapCap?: number, maxBuffer?: number, seedTrees?: SeedTrees}} Ctx
+ *   gapCap?: number, maxBuffer?: number, seedTrees?: SeedTrees,
+ *   humanRuling?: {decision: string, text?: string|null}|null,
+ *   onStage?: (row: {stage: string|null, kind: string|null, verdict: string, durationMs: number}) => void}} Ctx
  *   The arbiter's half of a stage run. Every field here is operator/runner
  *   territory: a declaration parameterises kinds, never the contracts.
- * @typedef {{verdict: 'green'|'red'|'instrument-stop'|'not-reached',
+ *   `humanRuling` is the SIGNER's answer at a hitl pause, carried in from the
+ *   runner — never authored, never defaulted, and absent on every ordinary run.
+ *   `onStage` is a REPORTING seam and nothing else: the seed read spawns a real
+ *   toolchain per stage (a suite is the slow one) and a whole read is one opaque
+ *   await, so the shell gets told as each stage lands. It decides nothing, it is
+ *   never consulted, and no verdict depends on it — the house pattern is
+ *   `runJob`'s `emit` (the library reports, the shell prints).
+ * @typedef {{verdict: 'green'|'red'|'instrument-stop'|'not-reached'|'pause'|'skipped',
  *   exitCode: number|null, value: number|null, baseline: number|null,
  *   baselineSource: string|null, gapLines: string[], judged: boolean,
  *   stage: string|null, kind: string|null, detail: Record<string, any>}} StageResult
+ *   Six outcomes, and only two of them are verdicts. `pause` is N4's fifth: the
+ *   close reached a stage a machine cannot render and is WAITING on a person —
+ *   neither green nor red, and never graded (the F17 forbidden-zone rule applied
+ *   to a non-verdict). `skipped` is the sixth and says a stage was deliberately
+ *   not run at THIS reading (ruling 8's seed exemption), which is a different
+ *   fact from `not-reached` (an earlier stage decided first).
  * @typedef {{ensure: (workdir: string, seedRef: string) => Promise<{stop: string, fault: string}|{stop: null, dir: string}>,
  *   cleanup: () => Promise<{ok: boolean, leaked: string[], detail: string|null}>}} SeedTrees
  */
@@ -346,24 +383,55 @@ export async function seedListing(workdir, seedRef) {
 // ── contract (c): the changed-set primitive ──────────────────────────────────
 
 /**
- * The two arbiter books, and the shape of each exclusion is the whole point.
+ * The arbiter books, and the shape of each exclusion is the whole point.
  *
- * `.litectx/` is a PREFIX — everything beneath the store belongs to the
- * arbiter. `gate-audit.jsonl` is an EXACT repo-relative path and never a
- * basename or a pattern: the gate audit is written to
+ * `.litectx/` and `.smoke/` are PREFIXES — everything beneath either store
+ * belongs to the arbiter. `gate-audit.jsonl` is an EXACT repo-relative path and
+ * never a basename or a pattern: the gate audit is written to
  * `join(workdir, 'gate-audit.jsonl')` and nowhere else, so a worker-authored
  * `src/gate-audit.jsonl` is NOT an arbiter book and must still count as work.
  * Matching by basename would swallow it — and swallowing a worker's real
- * write is the failure direction that reads as a clean tree.
+ * write is the failure direction that reads as a clean tree. `src/smoke.js` and
+ * `tests/smoke.test.js` are that same decoy for the store below.
+ *
+ * `.smoke/` — F98's parked residual, closed here. The fence has always denied
+ * `join(workdir, '.smoke')` on every worker (src/planrun.js, src/authorscout.js)
+ * and the persona now states the rule; this reader, which decides what COUNTS AS
+ * WORK, was the one place that never knew the name. On patients whose .gitignore
+ * default-denies dot-directories the store never reaches `ls-files --others` and
+ * the gap is masked — by the PATIENT's config, not by anything here. Incidental
+ * masking is not an exclusion: on a patient without that line the arbiter's own
+ * store would enter the changed set as the worker's writing.
  * @param {string} rel a repo-relative POSIX path
  * @returns {string|null} the book it belongs to, or null
  */
 export function isArbiterBook(rel) {
-  if (rel === '.litectx' || rel.startsWith('.litectx/')) return '.litectx/';
-  if (rel === 'gate-audit.jsonl') return 'gate-audit.jsonl';
+  for (const store of ARBITER_BOOK_STORES) {
+    if (rel === store || rel.startsWith(`${store}/`)) return `${store}/`;
+  }
+  if (rel === GATE_AUDIT_FILE) return GATE_AUDIT_FILE;
   return null;
 }
 
+/**
+ * The arbiter's book NAMES, one home. F98's mechanism was exactly this list
+ * living as independent literals: the fence deny arrays (src/planrun.js,
+ * src/authorscout.js) knew `.smoke` while `isArbiterBook` — the reader that
+ * decides what COUNTS AS WORK — did not, and the drift was masked by the
+ * patient's own .gitignore. Every consumer (the fence deny lists, this file's
+ * reader, the persona's stated law, run.js's smoke-store root) now spells the
+ * names from here, so adding or renaming a book is one edit that cannot leave
+ * a site behind.
+ *
+ * `ARBITER_BOOK_STORES` are directory PREFIXES; `GATE_AUDIT_FILE` is an EXACT
+ * repo-relative path (see `isArbiterBook`'s docstring for why never a
+ * basename). Order is the fence deny-list order and the persona's prose order.
+ */
+export const SMOKE_STORE = '.smoke';
+export const LITECTX_STORE = '.litectx';
+export const GATE_AUDIT_FILE = 'gate-audit.jsonl';
+export const ARBITER_BOOK_STORES = Object.freeze([SMOKE_STORE, LITECTX_STORE]);
+
 /**
  * Everything this run changed against the seed: the tracked diff PLUS
  * untracked files (an untracked file has no diff — the case a naive
@@ -699,13 +767,36 @@ export function normalizeParser(parser, at = 'parser') {
  * that matched BEFORE the filter judged them — kept, unattributable and dropped
  * alike — and it is the only evidence of liveness a caller has once the scope
  * has removed the whole population. It is never the number being read.
+ *
+ * `matched` is the KEPT lines themselves, PER TERM and index-aligned with
+ * `breakdown`: entry i holds, in output order, exactly the lines term i's
+ * subtotal was computed FROM. Run u-msn227nq paid for the echo — the executor
+ * counted 8 real `error TS…` lines and told the worker "8 match(es)", discarding
+ * every address, and a worker with a number and no file to open went looking for
+ * the arbiter's own books instead.
+ *
+ * TWO EXCLUSIONS, both of them "this line is not what the count is made of":
+ *  - a scope-DROPPED line is never in here. It was never counted, so aiming the
+ *    worker at it would aim it outside its own population.
+ *  - under `first`, only the line the aggregate actually READ. The later matches
+ *    are real matches (`breakdown[i].matches` still counts them) but the value
+ *    never contained them, and echoing them points the worker at a number that
+ *    is not in the reading.
+ *
+ * And the GROUPING is the third: a term's sign lives in `breakdown[i]`, so lines
+ * pooled flat across terms lose the one fact that says what they DID to the
+ * number. A subtracted term's line rendered beside an added one reads as a wall
+ * to go fix, and fixing it moves the count the wrong way. Deduplication is
+ * therefore within a term only — one line matched by two terms plays two
+ * arithmetic roles and is named under each. The count is computed from `values`,
+ * never from this list.
  * @param {string} output @param {any[]} terms normalised terms
  * Every stop here is `crashed` in the arbiter's vocabulary — the command RAN,
  * came back, and the number could not be read out of it. Nothing in this
  * function can observe a spawn failure, a timeout or a signal, so it never
  * claims one.
  * @param {{scope?: any, workdir?: string}} [o]
- * @returns {{stop: string, fault: string, notes?: string[]}|{stop: null, value: number, breakdown: any[], notes: string[], preScopeMatches: number}}
+ * @returns {{stop: string, fault: string, notes?: string[]}|{stop: null, value: number, breakdown: any[], notes: string[], preScopeMatches: number, matched: string[][]}}
  */
 export function parseValue(output, terms, { scope = null, workdir = '' } = {}) {
   let value = 0;
@@ -715,6 +806,10 @@ export function parseValue(output, terms, { scope = null, workdir = '' } = {}) {
   const breakdown = [];
   /** @type {string[]} */
   const notes = [];
+  // the KEPT lines PER TERM, in output order and deduplicated within the term —
+  // see the note above
+  /** @type {string[][]} */
+  const matched = [];
   const filtering = scopeFilters(scope);
   // one resolver (and one realpath cache) per call, built only when a filter
   // will actually read it
@@ -739,6 +834,9 @@ export function parseValue(output, terms, { scope = null, workdir = '' } = {}) {
     try { re = new RegExp(t.lineMatch, 'g'); } catch (e) { return { stop: `INSTRUMENT: term ${i} lineMatch /${t.lineMatch}/ is not a valid regex: ${String(/** @type {any} */ (e)?.message ?? e)}`, fault: STOP_FAULTS.CRASHED }; }
     /** @type {number[]} */
     const values = [];
+    /** @type {string[]} */
+    const kept = [];
+    const seen = new Set();
     let dropped = 0;
     let unattributable = 0;
     for (const line of region.split('\n')) {
@@ -750,6 +848,10 @@ export function parseValue(output, terms, { scope = null, workdir = '' } = {}) {
         if (p === null) unattributable += 1;
         else if (!inScope(p, scope, phys)) { dropped += 1; continue; }
       }
+      // past the filter, so this line is a CANDIDATE for the harvest — kept here
+      // rather than at aggregation because this is the only place the raw line
+      // still exists, and narrowed to what the aggregate actually read below
+      if (!seen.has(line)) { seen.add(line); kept.push(line); }
       for (const h of hits) {
         if (t.capture === null) { values.push(1); continue; }
         const rawCapture = h[t.capture];
@@ -789,10 +891,14 @@ export function parseValue(output, terms, { scope = null, workdir = '' } = {}) {
       }
       subtotal = values[0];
     }
+    // `first` read ONE line — `kept[0]`, since `values[0]` is the first hit on
+    // the first kept line. The rest matched (and `matches` below still says so)
+    // but are not what this subtotal is made of.
+    matched.push(t.aggregate === 'first' ? kept.slice(0, 1) : kept);
     breakdown.push({ term: i, lineMatch: t.lineMatch, aggregate: t.aggregate, sign: t.sign, matches: values.length, subtotal, contribution: t.sign * subtotal });
     value += t.sign * subtotal;
   }
-  return { stop: null, value, breakdown, notes, preScopeMatches };
+  return { stop: null, value, breakdown, notes, preScopeMatches, matched };
 }
 
 // ── D12: the baseline is MEASURED at this run's own seed, every run ──────────
@@ -1084,7 +1190,7 @@ async function runCountNotWorse(stage, ctx) {
         notes: [],
       };
     }
-    return { stop: null, value: v.value, breakdown: v.breakdown, notes: v.notes, exit: r.code, dropped: r.dropped, fault: STOP_FAULTS.FAILED };
+    return { stop: null, value: v.value, breakdown: v.breakdown, notes: v.notes, matched: v.matched, exit: r.code, dropped: r.dropped, fault: STOP_FAULTS.FAILED };
   };
 
   const now = await measure(ctx.workdir, 'the current tree');
@@ -1126,8 +1232,30 @@ async function runCountNotWorse(stage, ctx) {
   if (worse) {
     gap.push(`${stage.name}: ${value} against a baseline of ${baseline} (${p.direction}) — worse`);
     gap.push(`  baseline ${baselineSource}`);
-    for (const b of /** @type {any[]} */ (now.breakdown)) {
+    // …each term stating itself, and THEN the lines that term's subtotal is made
+    // of, nested under it. A count with no addresses is the semantic genre F38
+    // measured as inert: run u-msn227nq's worker was handed "8 match(es)", had
+    // nowhere to open, and probed the arbiter's books until the deny guard ended
+    // the run. The instrument NAMED these lines — echoing what it named is the
+    // same licence `pattern-absent-in-diff` already runs under, not the barred
+    // move of naming a culprit the instrument never reported.
+    //
+    // NESTED, not pooled, because a line's arithmetic role is the term's and only
+    // the term's row carries it. `value` is a SIGNED sum: a term declared
+    // `sign: -1` subtracts, so its lines are ones the count went DOWN for, and a
+    // worker handed them flat beside the added ones reads every line as a wall
+    // and "fixes" one that moves the number the wrong way. The row directly above
+    // each block already says `contributes +n` / `-n`; sitting the lines under it
+    // is what makes that statement reach them. Nothing is withheld — under
+    // `higher-is-better` the subtracted term is exactly where the news usually is
+    // — and nothing is relabelled: the lines are still verbatim, one indent in.
+    //
+    // They ride the Gap like every other line: the stage prefix (Layer R's
+    // redKeep derives from it), the cap, and the trim marker on overflow.
+    const perTerm = /** @type {string[][]} */ (now.matched ?? []);
+    for (const [i, b] of /** @type {any[]} */ (now.breakdown).entries()) {
       gap.push(`  term ${b.term} /${b.lineMatch}/ ${b.aggregate}: ${b.matches} match(es), subtotal ${b.subtotal}, contributes ${b.contribution >= 0 ? '+' : ''}${b.contribution}`);
+      for (const l of perTerm[i] ?? []) gap.push(`    ${l}`);
     }
   }
   return result(stage, {
@@ -1232,12 +1360,117 @@ async function runFilesChanged(stage, ctx) {
   });
 }
 
+/**
+ * THE SIGNER'S ANSWER, normalised at the seam that accepts it — the library half
+ * of the three-button gate (2026-08-12 §1).
+ *
+ * `null` is not a refusal: no ruling at all IS the pause path, which is how every
+ * ordinary run and every first leg of a hitl run arrives here. What is refused is
+ * an answer that is not one of the three doors, and — the case the POC's negative
+ * control measured — a `rerun` with no text. Ruling 3 makes the human's words the
+ * gap the worker converts from; an empty one launches a fix worker that re-runs
+ * as though nothing had been said, which is the failure this refusal exists for.
+ *
+ * It never throws and never repairs: a decision that cannot be read is handed
+ * back as a refusal with its reason, and the caller decides what to do about it.
+ * @param {any} ruling
+ * @returns {{ok: boolean, ruling: {decision: string, text: string|null}|null, why: string|null}}
+ */
+export function normalizeHumanRuling(ruling) {
+  if (ruling === null || ruling === undefined) return { ok: true, ruling: null, why: null };
+  if (typeof ruling !== 'object' || Array.isArray(ruling)) {
+    return { ok: false, ruling: null, why: `a decision is an object {decision, text?} — one of ${HUMAN_DECISIONS.join(' | ')}` };
+  }
+  const decision = String(/** @type {any} */ (ruling).decision);
+  if (!HUMAN_DECISIONS.includes(decision)) {
+    return {
+      ok: false,
+      ruling: null,
+      why: `"${decision}" is not one of the three doors (${HUMAN_DECISIONS.join(' | ')}). There is no fourth, and no `
+        + 'free-text-only variant: a red that is not one of these two is not a ruling the run can act on',
+    };
+  }
+  const text = /** @type {any} */ (ruling).text;
+  if (decision === 'rerun') {
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      return {
+        ok: false,
+        ruling: null,
+        why: 'a "rerun" decision needs TEXT: the human is the gap author (ruling 3), and their words are the whole of '
+          + 'what the fix worker is given. An empty gap re-runs the worker as though nothing had been said',
+      };
+    }
+    return { ok: true, ruling: { decision, text }, why: null };
+  }
+  return { ok: true, ruling: { decision, text: null }, why: null };
+}
+
+/**
+ * THE HUMAN STAGE (N4 slice 1) — the one kind that measures nothing.
+ *
+ * With no ruling in hand it does not RUN, it PAUSES: the fifth outcome, neither
+ * green nor red, so nothing downstream grades it. With the signer's ruling in
+ * hand it renders exactly what the person said — `accept` is a green a PERSON
+ * judged, and `rerun` is a red whose gap is the human's own words, verbatim,
+ * through the same bounded/announced channel every other stage's gap uses.
+ *
+ * It spawns nothing, reads nothing and touches no tree, which is why it can
+ * render both without a workdir that exists.
+ *
+ * `pause` is deliberately NOT a case here. It is not a judgment about the tree
+ * — it is the signer saying "not now" — and it is consumed above this stage, by
+ * the runner and by `runPlan` before the close is ever asked (a `pause` that
+ * reached this far has bypassed that seam, so it renders NO verdict rather than
+ * being guessed into one). With no ruling in hand this kind pauses anyway, which
+ * is the same place the person is left; what the door adds is the RECORD that
+ * they looked and chose to keep the checkpoint.
+ * @param {any} stage @param {Ctx} ctx @returns {Promise<StageResult>}
+ */
+async function runHumanConfirms(stage, ctx) {
+  const ask = stage?.params?.ask;
+  const norm = normalizeHumanRuling(ctx.humanRuling ?? null);
+  if (!norm.ok) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" was handed a decision it cannot read — ${norm.why}`,
+      {}, STOP_FAULTS.CRASHED);
+  }
+  if (norm.ruling === null) {
+    // THE PAUSE. `judged: false` and `exitCode: null` together are the whole
+    // contract: nothing was measured and no process ran, so a zero here would be
+    // F6 in an exit code's coat.
+    return result(stage, {
+      verdict: 'pause',
+      exitCode: null,
+      judged: false,
+      detail: { ask: isNonEmptyString(ask) ? ask : null },
+    });
+  }
+  if (norm.ruling.decision === 'accept') {
+    return result(stage, { verdict: 'green', exitCode: EXIT_GREEN, judged: true, detail: { ask: ask ?? null, decision: 'accept' } });
+  }
+  if (norm.ruling.decision === 'rerun') {
+    const gap = new Gap(ctx.gapKeep, ctx.gapCap);
+    gap.push(`${stage.name}: the signer reviewed the result and asked for another pass. Their words:`);
+    gap.push(/** @type {string} */ (norm.ruling.text));
+    return result(stage, {
+      verdict: 'red',
+      exitCode: EXIT_RED,
+      judged: true,
+      gapLines: gap.render(),
+      detail: { ask: ask ?? null, decision: 'rerun' },
+    });
+  }
+  return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" was handed a "${norm.ruling.decision}" decision, which `
+    + 'is the signer ending the run and is never a verdict about the tree — the runner consumes it before the close',
+  {}, STOP_FAULTS.CRASHED);
+}
+
 /** @type {Record<string, (stage: any, ctx: Ctx) => Promise<StageResult>>} */
 const RUNNERS = {
   'command-exit': runCommandExit,
   'count-not-worse': runCountNotWorse,
   'pattern-absent-in-diff': runPatternAbsentInDiff,
   'files-changed': runFilesChanged,
+  'human-confirms': runHumanConfirms,
 };
 
 /**
@@ -1296,10 +1529,41 @@ export async function seedRead(declaration, ctx) {
   const owned = !ctx.seedTrees;
   const seedTrees = ctx.seedTrees ?? makeSeedTrees();
   const inner = { ...ctx, seedTrees };
+  /** AFTER the stage completes, never before: a line saying a stage STARTED and
+   * a line saying what it RETURNED are two different facts, and only the second
+   * one can carry a verdict. The duration is measured around the call rather
+   * than reported by it, so a stage that stops still gets a real number.
+   * @param {StageResult} row @param {number} startedAt */
+  const told = (row, startedAt) => {
+    if (typeof ctx.onStage === 'function') {
+      ctx.onStage({ stage: row.stage, kind: row.kind, verdict: row.verdict, durationMs: Date.now() - startedAt });
+    }
+    return row;
+  };
   try {
     /** @type {StageResult[]} */
     const rows = [];
-    for (const stage of declaration?.stages ?? []) rows.push(await runStageIn(stage, inner));
+    for (const stage of declaration?.stages ?? []) {
+      // RULING 8 — judged and human stages are EXEMPT from the seed read, and
+      // the exemption is a ROW, not an absence (F59). A person asked at the seed
+      // is being interviewed, not measured, and there is nothing to baseline.
+      const startedAt = Date.now();
+      if (SEED_EXEMPT_KINDS.includes(stage?.kind)) {
+        rows.push(told(result(stage, {
+          verdict: 'skipped',
+          exitCode: null,
+          judged: false,
+          detail: {
+            skipped: true,
+            why: 'ruling 8 (2026-08-07): judged and human stages skip the seed-verdict read — a judged number at seed '
+              + 'is unstable and a person at seed is an interview, not a measurement. This stage has no seed baseline '
+              + 'and contributes none.',
+          },
+        }), startedAt));
+        continue;
+      }
+      rows.push(told(await runStageIn(stage, inner), startedAt));
+    }
     return rows;
   } finally {
     if (owned) await seedTrees.cleanup();
@@ -1321,7 +1585,7 @@ export async function seedRead(declaration, ctx) {
  * room would break a documented adopter contract for nothing; the new name says
  * exactly what differs. `src/declaredclose.js` is what bridges the two shapes.
  * @param {any} declaration @param {Ctx} ctx
- * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop', exitCode: number, judged: boolean, firstRed: string|null, stages: StageResult[]}>}
+ * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop'|'pause', exitCode: number|null, judged: boolean, firstRed: string|null, pausedAt: string|null, stages: StageResult[]}>}
  */
 export async function runDeclaredClose(declaration, ctx) {
   const owned = !ctx.seedTrees;
@@ -1340,12 +1604,20 @@ export async function runDeclaredClose(declaration, ctx) {
       stages.push(r);
       if (r.verdict !== 'green') ended = true;
     }
+    // A PAUSE stops the close exactly like a red does, and is DELIBERATELY not
+    // in this list: `deciding` names the stage that rendered a VERDICT, and a
+    // pause rendered none. Reading it as one would fall through to green — the
+    // close would mint a verdict nobody gave (the defect this line exists to
+    // make impossible).
     const deciding = stages.find((s) => s.verdict === 'red' || s.verdict === 'instrument-stop');
+    const paused = deciding ? null : stages.find((s) => s.verdict === 'pause') ?? null;
     return {
-      verdict: /** @type {'green'|'red'|'instrument-stop'} */ (deciding ? deciding.verdict : 'green'),
-      exitCode: deciding ? /** @type {number} */ (deciding.exitCode) : EXIT_GREEN,
-      judged: deciding ? deciding.judged : true,
+      verdict: /** @type {'green'|'red'|'instrument-stop'|'pause'} */ (deciding ? deciding.verdict : (paused ? 'pause' : 'green')),
+      exitCode: deciding ? /** @type {number} */ (deciding.exitCode) : (paused ? null : EXIT_GREEN),
+      judged: deciding ? deciding.judged : (paused ? false : true),
       firstRed: deciding ? deciding.stage : null,
+      /** the stage the close is WAITING on, when it is waiting on a person */
+      pausedAt: paused ? paused.stage : null,
       stages,
     };
   } finally {

package/src/ledger.js

@@ -1,5 +1,5 @@
 // The upstream ledger (module 4) — reactive lib/primitive incident monitoring.
-// Design record: docs/plans/2026-07-11-upstream-ledger-design.md (adaptlearn
+// Design record: docs/02-features/2026-07-11-upstream-ledger-design.md (adaptlearn
 // POC'd spec) + its 2026-07-13 addendum: the bareloop event mapping. One
 // append-only JSONL both the consumer (the panel, N6) and the maintainer read;
 // the A1/A2/A3 upstream-ask flow, mechanized — evidence in, human judgment out.
@@ -22,6 +22,7 @@
 import { readFileSync, appendFileSync, existsSync } from 'node:fs';
 import { basename } from 'node:path';
 import { createHash } from 'node:crypto';
+import { HITL_PAUSE, HITL_DECISION_RED } from './declaredclose.js';
 
 /** severity order, worst-first (the fold's display order; frequency ranks within) */
 export const LEDGER_CLASSES = Object.freeze([
@@ -75,9 +76,35 @@ const EXCLUDED_ESCALATIONS = new Set([
   // real upstream ask would be sourced from anyway.
   'step-stalled',
   'step-variance',      // A's replan trigger: a planning story, never a lib bug
-  'gate-red',           // governance working as intended
+  // Governance working as intended — and no longer minted anywhere in this tree
+  // (a denial streak is a bounded attempt, not a terminal). Kept listed because
+  // this set is the EXECUTABLE excluded-set: dropping a name does not delete the
+  // category, it re-files any future emission of it as a counted capability gap.
+  'gate-red',
   'smoke-red',          // already counted via primitive-smoke
   'hitl-close',         // by design: a human is the close
+  // N4 slice 1 — the hitl class's own terminals, and each is here for its own
+  // reason rather than by family resemblance. `hitl-pause` is a CHECKPOINT (the
+  // cap-halt story with a person instead of a budget: the run stopped because it
+  // reached the one stage a machine cannot render). `hitl-decision-red` is an
+  // honest refusal of the OPERATOR's own input, exactly like `close-unsupported`
+  // below, and the one direction that would be wrong is filing either of them as
+  // a capability gap against a library that did nothing.
+  //
+  // MINTED, never borrowed: the legacy `hitl-close` above is the deleted path's
+  // close TYPE and keeps its own meaning. Reusing that name would have made two
+  // different facts one number (the `step-stalled` lesson).
+  HITL_PAUSE,
+  HITL_DECISION_RED,
+  // LEGACY, read-only, and a bare STRING on purpose (the `gate-red` precedent
+  // above): `hitl-cancel` was the third door's terminal until 2026-08-17, when
+  // cancel was deleted in favour of a pause that can resume. Nothing in this tree
+  // mints it any more — there is no constant left to import — but this set is the
+  // EXECUTABLE excluded-set, and dropping a name does not delete the category: it
+  // re-files any spine that still CARRIES one as a counted capability gap against
+  // a library that did nothing. A reader must keep recognising what a writer can
+  // no longer write.
+  'hitl-cancel',
   'close-unsupported',  // honest refusal, by design
   // Close authoring (M4, D13) — the interview refusing a job we cannot close: a
   // genre we do not run, a job with no seed to measure against, a locked kind.