bareloop 0.10.0 → 0.11.0

package/src/authoring.js

@@ -94,9 +94,11 @@ import { isObj, isNonEmptyString, hasNestedQuantifier, globToPrefix } from './va
 
 /** the whole menu, in ascending order of what it takes to render the verdict */
 export const VERDICT_CLASSES = Object.freeze(['green', 'soft-green', 'hitl']);
-/** declared-but-locked: selecting one is COUNTED demand, never an admission */
-export const LOCKED_CLASSES = Object.freeze(['soft-green', 'hitl']);
-/** the classes v1 actually builds — exactly one */
+/** declared-but-locked: selecting one is COUNTED demand, never an admission.
+ * `hitl` LEFT this list at N4 slice 1 (see `src/job.js`'s twin) — the class is
+ * built, and its battery is below. `soft-green` waits for the judged floor. */
+export const LOCKED_CLASSES = Object.freeze(['soft-green']);
+/** the classes v1 actually builds */
 export const LIVE_CLASSES = Object.freeze(VERDICT_CLASSES.filter((c) => !LOCKED_CLASSES.includes(c)));
 
 /** the hierarchy as a comparable number. `green` is the FLOOR: a mechanical
@@ -237,11 +239,22 @@ export const KIND_CATALOGUE = Object.freeze({
     shape: 'LOCKED — not available in v1',
     asserts: 'a judged score must clear a floor. Declaring it is recorded as demand; it will not run.',
   }),
+  // LIVE at N4 slice 1, and the ONLY kind that does not measure anything: it
+  // does not RUN, it PAUSES the run and hands the tree to a person (ruling 1).
+  // `ask` is the whole parameter surface — no cmd, no timeoutMs, no env — so a
+  // human stage cannot spawn, cannot be env-capable, and cannot be given a
+  // second job. `offer` is never one of its fields either: ruling 5's law is a
+  // LAW, checked by the validator, not a knob the composer sets.
   'human-confirms': Object.freeze({
     verdictClass: 'hitl',
-    required: Object.freeze([]), optional: Object.freeze([]), pathParams: Object.freeze([]), locked: true,
-    shape: 'LOCKED — not available in v1',
-    asserts: 'a person renders the verdict. Declaring it is recorded as demand; it will not run.',
+    required: Object.freeze(['ask']),
+    optional: Object.freeze([]),
+    pathParams: Object.freeze([]),
+    shape: 'ask: string',
+    asserts: 'a PERSON renders this verdict, at the end of the run, and nothing about it is measured. Write `ask` as '
+      + 'the plain question they answer while looking at the finished result. It is always the LAST stage, it is '
+      + 'never offered to the agent as an in-run check, and every part of the job a command can decide belongs in a '
+      + 'mechanical stage before it.',
   }),
 });
 
@@ -613,30 +626,40 @@ function language(lang) {
  * than hand back nothing if anything ever does.
  * @type {Record<string, {locked: boolean, guards: readonly any[]|null}>}
  */
-export const CLASS_BATTERIES = Object.freeze({
-  green: Object.freeze({
-    locked: false,
-    guards: Object.freeze([
-      Object.freeze({
-        name: 'changed-from-seed',
-        kind: 'files-changed',
-        params: Object.freeze({ requireNonEmpty: true }),
-        compose: Object.freeze([]),
-        fill: Object.freeze(['allowPrefixes']),
-      }),
-      Object.freeze({
-        name: 'no-suppressions',
-        kind: 'pattern-absent-in-diff',
-        // NO scope: the scan covers every changed file of these extensions. A
-        // narrowing here is the round-3 arm A defect and is a red, not a taste.
-        params: Object.freeze({}),
-        compose: Object.freeze(['patterns', 'extensions']),
-        fill: Object.freeze([]),
-      }),
-    ]),
+/** THE MECHANICAL BATTERY — the two guards a machine can always render, named
+ * once because TWO classes carry exactly them (OPEN-1's ruling below). It is
+ * shared by reference and never mutated: `classGuards` deep-copies before it
+ * hands anything back, so one battery cannot be weakened through another class. */
+const MECHANICAL_GUARDS = Object.freeze([
+  Object.freeze({
+    name: 'changed-from-seed',
+    kind: 'files-changed',
+    params: Object.freeze({ requireNonEmpty: true }),
+    compose: Object.freeze([]),
+    fill: Object.freeze(['allowPrefixes']),
+  }),
+  Object.freeze({
+    name: 'no-suppressions',
+    kind: 'pattern-absent-in-diff',
+    // NO scope: the scan covers every changed file of these extensions. A
+    // narrowing here is the round-3 arm A defect and is a red, not a taste.
+    params: Object.freeze({}),
+    compose: Object.freeze(['patterns', 'extensions']),
+    fill: Object.freeze([]),
   }),
+]);
+
+export const CLASS_BATTERIES = Object.freeze({
+  green: Object.freeze({ locked: false, guards: MECHANICAL_GUARDS }),
   'soft-green': Object.freeze({ locked: true, guards: null }),
-  hitl: Object.freeze({ locked: true, guards: null }),
+  // OPEN-1, RULED (hamr, in-turn, 2026-08-13): **hitl inherits the green
+  // mechanical guards and adds nothing a human stage cannot see.** D5 makes the
+  // battery mandatory, shown-and-fixed and un-removable, and PRD v1.57 §2 keys it
+  // to the CLASS; the mechanical-first composition law makes every hitl close
+  // mostly mechanical anyway, so the green battery is the right FLOOR. A guard a
+  // person cannot verify by looking would be a guard nobody checks — the one
+  // thing D5 exists to make unsayable.
+  hitl: Object.freeze({ locked: false, guards: MECHANICAL_GUARDS }),
 });
 
 /**
@@ -925,7 +948,12 @@ function scopeOfJob(declaration, idx, guards) {
  * stage — applied to the one population that decides whether the law fires at
  * all.
  */
-const AT_MOST_ONCE_KINDS = Object.freeze(['files-changed']);
+const AT_MOST_ONCE_KINDS = Object.freeze(['files-changed', 'human-confirms']);
+
+/** the kinds NO ONE runs as an in-run ruler — ruling 5's law, as data. A
+ * declaration that offers one is a red rather than a normalization: the signer
+ * must not read one thing and have the runner store another. */
+export const NEVER_OFFERED_KINDS = Object.freeze(['human-confirms', 'judged-floor']);
 
 /** @param {any} v */
 const strArray = (v) => Array.isArray(v) && v.length > 0 && v.every(isNonEmptyString);
@@ -1128,13 +1156,43 @@ export function validateDeclaration(declaration, opts = {}) {
     if (AT_MOST_ONCE_KINDS.includes(s.kind)) {
       const owner = kindOwners.get(s.kind);
       if (owner !== undefined) {
-        red('duplicate-kind', `${at}.kind`, `stage "${label}" is a second ${s.kind} stage — "${owner}" already declares `
-          + 'which files this job may change. Stages are ANDed, so two of them mean the intersection of two prefix sets, '
-          + 'which is itself a prefix set and already says the same thing in one stage; what a second one does add is a '
-          + 'second answer to what this job\'s scope IS', { kind: s.kind, stage: label, twin: owner });
+        red('duplicate-kind', `${at}.kind`, s.kind === 'human-confirms'
+          ? `stage "${label}" is a second ${s.kind} stage — "${owner}" already asks the person. One signer, one judge `
+            + '(ruling 4), asked ONCE at the end: a second door is a second verdict, and the run has no way to say '
+            + 'which of them was the one it stopped for'
+          : `stage "${label}" is a second ${s.kind} stage — "${owner}" already declares `
+            + 'which files this job may change. Stages are ANDed, so two of them mean the intersection of two prefix sets, '
+            + 'which is itself a prefix set and already says the same thing in one stage; what a second one does add is a '
+            + 'second answer to what this job\'s scope IS', { kind: s.kind, stage: label, twin: owner });
       } else kindOwners.set(s.kind, label);
     }
 
+    // ── RULING 5, AS LAW: judged and human stages are `offer: false`, and the
+    // law is checked rather than applied. `checkMenu` filters `offer !== false`,
+    // so a declaration that says nothing is silent about a rule the runner
+    // enforces anyway (`declaredStages` stamps it) — that part is the arbiter's
+    // own bookkeeping. What must never happen is a declaration that says
+    // something ELSE: `offer: true` on a human stage is the composer asking to
+    // use a person as an in-run ruler, and a silent normalization would leave
+    // the signer reading one thing while the runner stored another.
+    if (NEVER_OFFERED_KINDS.includes(s.kind) && Object.hasOwn(s, 'offer') && s.offer !== false) {
+      red('human-stage-offered', `${at}.offer`, `stage "${label}" is a ${s.kind} stage and offers itself as an in-run `
+        + 'check. A person (or a paid judge) is never an in-run ruler (ruling 5): the agent may never use one to '
+        + 'decide a step, and this is refused rather than quietly rewritten to offer: false',
+      { kind: s.kind, stage: label });
+    }
+    // ── THE COMPOSITION LAW's ordering half (2026-08-07: *mechanical first,
+    // judge minimal, human LAST*), enforced where it is cheap. First-red-wins
+    // means anything after the human stage never runs — so a human stage in the
+    // middle silently deletes the mechanical stages behind it AND empties the
+    // evidence package ruling 2 requires the person to be shown.
+    if (s.kind === 'human-confirms' && i !== stages.length - 1) {
+      red('human-stage-not-last', `${at}.kind`, `stage "${label}" asks a person and is not the LAST stage. The close `
+        + 'is first-red-wins, so every stage after this one would never run: the person would be shown an incomplete '
+        + 'evidence package and the mechanical stages behind them would be silently deleted (the composition law: '
+        + 'mechanical first, human last)', { kind: s.kind, stage: label, at: i, last: stages.length - 1 });
+    }
+
     const p = s.params;
     if (!isObj(p)) { red('missing-field', `${at}.params`, `an object carrying: ${spec.required.join(', ')}`); return; }
     for (const k of spec.required) {
@@ -1338,6 +1396,15 @@ function checkKind({ kind, params: p, at, red, scoped, label, populations, envOw
       if (!strArray(p.allowPrefixes)) red('invalid-value', `${at}.params.allowPrefixes`, 'a non-empty array of path prefixes');
       if (p.requireNonEmpty !== true) red('invalid-value', `${at}.params.requireNonEmpty`, 'literally true');
       break;
+    case 'human-confirms':
+      // the whole surface: the question the signer answers. It is shown to a
+      // person verbatim, so an empty one is a bare "approve?" — ruling 2's
+      // named failure mode, refused here rather than rendered.
+      if (!isNonEmptyString(p.ask)) {
+        red('invalid-value', `${at}.params.ask`, 'the plain question the signer answers while looking at the finished '
+          + 'result — a human stage with nothing to ask is the bare "approve?" ruling 2 forbids');
+      }
+      break;
     default:
       red('unknown-kind', `${at}.kind`, `"${kind}" is in the catalogue but has no checker`, { kind });
   }

package/src/authorjob.js

@@ -96,7 +96,7 @@ import {
   GENRE_LANGUAGES, LOCKED_KINDS, TYPES_GENRE, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES,
 } from './authoring.js';
 import { QUESTION_SETS, questionsFor, requiredAnswersFor, authorClose } from './authorflow.js';
-import { runAuthorScout, buildSeedListing } from './authorscout.js';
+import { runAuthorScout, buildSeedListing, SCOUT_ATTEMPTS } from './authorscout.js';
 import {
   DECLARED_GAP_PREFIX, DECLARED_GENRES, guardNames, isDeclaredClose, validateCloseDecl,
 } from './declaredclose.js';
@@ -366,6 +366,8 @@ function composerRefusal(reds) {
  *   verdictType?: string|null,
  *   questions?: Record<string|number, string>|null, generate?: Function, provider?: any,
  *   seedRef?: string|null, scout?: any, listing?: any, ceilingUsd?: number|null,
+ *   onPhase?: (phase: string, data?: any) => void,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   seedFn?: Function, scoutFn?: Function, listingFn?: Function,
  *   authorFn?: Function, authorOpts?: object}} o
  * @returns {Promise<{ok: boolean, refusal: Refusal|null, verdictType: string|null,
@@ -376,6 +378,13 @@ export async function authorCloseForJob({
   answers, repoPath = null, lang, verdictType = null, questions = null,
   generate, provider = null, seedRef = null, scout = null, listing = null,
   ceilingUsd = null,
+  // THE PROGRESS SEAMS. This composition is the pipeline's long silence — a real
+  // survey, a real declaration ladder, and a real toolchain per close stage — and
+  // it emitted nothing until it returned, so an operator watching a live run
+  // could not tell work from a hang. The library REPORTS and the shell PRINTS
+  // (`runJob`'s `emit` → `runPlan`, the same shape): nothing here reads either
+  // callback back, and no decision in this file or below it depends on one.
+  onPhase = () => {}, onCall = () => {},
   seedFn = seedAtHead, scoutFn = runAuthorScout, listingFn = buildSeedListing,
   authorFn = authorClose, authorOpts = {},
 }) {
@@ -425,6 +434,10 @@ export async function authorCloseForJob({
   // D8 — the seed, READ rather than typed.
   let seed = seedRef;
   if (!isNonEmptyString(seed)) {
+    // Announced only on the path that actually READS one: a caller who handed a
+    // seedRef in never paid for a git call, and a phase line for work nobody did
+    // is the blind-instrument class, one line wide.
+    onPhase('seed', {});
     const s = await seedFn(workdir);
     if (s.stop !== null) {
       // same git-stderr channel as `prepareSigning`'s, scrubbed at the same
@@ -445,15 +458,46 @@ export async function authorCloseForJob({
   // form). `null` travels EXPLICITLY rather than being left off — unbounded is a
   // stated operator choice, and an absent field read as falsy is the same state
   // arrived at by accident.
-  const survey = scout ?? await scoutFn({ workdir, provider, ceilingUsd });
-  const seeds = listing ?? await listingFn({
-    workdir, seedRef: seed, sourcePaths: survey?.facts?.sourcePaths, testPaths: survey?.facts?.testPaths,
-  });
+  /** @type {any} */
+  let survey = scout;
+  // `== null` and not `!survey`: this is the `??` these two lines replaced, kept
+  // exactly — a caller-supplied survey is used whatever it is, and only an
+  // ABSENT one is paid for.
+  if (survey == null) {
+    // The scout is the pipeline's FIRST paid stage and its longest single
+    // silence: up to three ladder attempts, each a real toolable survey over a
+    // real tree. `attempts` is the ceiling the scout enforces on itself, so the
+    // reader knows how many the line could repeat for.
+    onPhase('scout', { attempts: SCOUT_ATTEMPTS });
+    survey = await scoutFn({ workdir, provider, ceilingUsd, onCall });
+    // …and the survey's own VERDICT, said the moment it lands. `state` is what
+    // every downstream refusal keys on (F59: absent is never "no facts needed"),
+    // and the fact count is the one number that says whether the ladder came
+    // back with anything to author from.
+    onPhase('scout-done', { state: survey?.state ?? null, facts: Object.keys(survey?.facts ?? {}).length });
+  }
+  /** @type {any} */
+  let seeds = listing;
+  if (seeds == null) {
+    onPhase('listing', {});
+    seeds = await listingFn({
+      workdir, seedRef: seed, sourcePaths: survey?.facts?.sourcePaths, testPaths: survey?.facts?.testPaths,
+    });
+    // the count is only knowable AFTER, so it rides the done line rather than
+    // being guessed onto the start one
+    onPhase('listing-done', { files: seeds?.files?.length ?? null, stop: seeds?.stop ?? null });
+  }
 
+  // The declaration ladder. The REVISION CAP is deliberately not quoted here:
+  // the tighten-only clamp lives in `authorClose` (and `authorOpts` may lower
+  // it), so a number spelled at this call site could disagree with the one the
+  // loop obeys — `author-call` carries the enforced cap instead, from where it
+  // is computed.
+  onPhase('author', {});
   const authored = await authorFn({
     workdir, seedRef: seed, lang, verdictType: picked,
     answers: interview.answers, questions: questions ?? questionsFor(picked),
-    scout: survey, listing: seeds, generate, ceilingUsd, ...authorOpts,
+    scout: survey, listing: seeds, generate, ceilingUsd, onPhase, onCall, ...authorOpts,
   });
 
   if (!authored.ok) {

package/src/authorscout.js

@@ -349,6 +349,7 @@ const defaultLoop = (/** @type {any} */ { system, policy, onLlmResult, provider
  * @param {{workdir: string, provider?: any,
  *   rounds?: number, minBytes?: number, blobMax?: number, maxTokens?: number, ctx?: boolean,
  *   attempts?: number, ceilingUsd?: number|null,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any}) => any,
  *   createSurveyor?: (o: {workdir: string, granted: readonly string[], ctx: boolean}) => Promise<any>}} o
  * @returns {Promise<Survey & {raw: string, raws: ReturnType<typeof scrubRaw>[],
@@ -364,6 +365,7 @@ export async function runAuthorScout({
   ctx = true,
   attempts = SCOUT_ATTEMPTS,
   ceilingUsd = null,
+  onCall = () => {},
   createLoop = defaultLoop,
   createSurveyor = defaultSurveyor,
 }) {
@@ -384,7 +386,17 @@ export async function runAuthorScout({
    * @param {string} label @param {number} attempt @param {any} r @returns {number}
    */
   const record = (label, attempt, r) => {
-    calls.push({ label, ...priceOf(r) });
+    const call = { label, ...priceOf(r) };
+    calls.push(call);
+    // …and the SHELL is told, at the same instant and off the same entry. A run
+    // killed from outside used to lose 100% of its spend record (F6/F12: a
+    // halted attempt's spend was invisible by 300×) — the totals only ever
+    // existed in this array, which dies with the process. Fired from inside the
+    // one recorder rather than at the call sites, so a paid call cannot be
+    // metered without the report going out: exactly the pairing invariant the
+    // raw already rides. It REPORTS and decides nothing; the ceiling still binds
+    // through `capStop` between calls, untouched.
+    onCall({ ...call });
     return raws.push(scrubRaw({ label, attempt, text: r?.text })) - 1;
   };
   // TIGHTEN-ONLY: an operator may lower the ceiling, never raise it. A garbage

package/src/bridges.js

@@ -1,5 +1,5 @@
 // Layer 3 — the REUSE registry (design record:
-// docs/plans/2026-08-01-layer-3-reuse-design.md, D1/D2/D6, frozen 2026-08-01).
+// docs/02-features/2026-08-01-layer-3-reuse-design.md, D1/D2/D6, frozen 2026-08-01).
 //
 // A BRIDGE is the plan a green actually executed, kept so the next run of the same
 // SHAPE starts from it instead of cold. This module is the box and the label on it:

package/src/clock.js

@@ -43,6 +43,21 @@
 //      it from the remaining budget is what stops the LAST round outliving the run.
 //   3. ~90% accuracy is the bar, by hamr's ruling (addendum 3). This module does
 //      not chase precision; it reports honestly at the precision it has.
+//   4. SUSPENDED MINUTES NEVER CHARGE A SIGNED WALL (hamr's ruling, 2026-08-15:
+//      "if computer suspended, time shouldn't count"). The default source is
+//      therefore MONOTONIC — `performance.now()`, which reads libuv's `uv_hrtime`
+//      and so CLOCK_MONOTONIC, which per clock_gettime(2) "does not count time
+//      that the system is suspended" on Linux (CLOCK_BOOTTIME is the one that
+//      would). `Date.now()` is CLOCK_REALTIME and counts every suspended minute:
+//      that was not a hypothetical, it charged 45 phantom minutes against a
+//      45-minute wall when an s2idle suspend landed mid-run, and it is the same
+//      exposure for an NTP step or a hand-set date. Nothing here corrects for a
+//      suspend after the fact; the reading simply never includes one.
+//      The epoch change is safe by construction: every use of `now()` below is
+//      RELATIVE (`now() - startedAt`), and no value derived from this clock is
+//      ever published as a calendar timestamp — `report()` carries durations only,
+//      and the `at:`/`ts:` stamps a run writes come from their own `Date.now`
+//      seams (src/reuse.js), which stay calendar-correct on purpose.
 //
 // Unbounded is a REAL state, not a large number: hamr ruled `maxWallMs` has no
 // default, so a run without one is time-unbounded by explicit operator choice and
@@ -135,11 +150,14 @@ export function isWallTimeout(err, clock) {
  *   run. `closeStages`: how many stages the job's close runs (W5) — each one gets
  *   the FULL `closeTimeoutMs`, so this is the multiplier on the overshoot, not a
  *   decoration. Defaults to 1, the single-predicate close. `now`: injected for
- *   tests — the default is the real clock. `priorElapsedMs`: time this attempt's
- *   PREDECESSOR already consumed (see below).
+ *   tests — the default is the real clock, and it stays injectable precisely so
+ *   every test here can drive time deterministically without a sleep. That default
+ *   is MONOTONIC (fact 4 above), not `Date.now`: a wall-clock jump — a suspend, an
+ *   NTP step, a hand-set date — must not be able to reach a signed deadline.
+ *   `priorElapsedMs`: time this attempt's PREDECESSOR already consumed (see below).
  * @returns {Clock}
  */
-export function createClock({ maxWallMs = null, closeStages = 1, now = () => Date.now(), priorElapsedMs = 0 } = {}) {
+export function createClock({ maxWallMs = null, closeStages = 1, now = () => performance.now(), priorElapsedMs = 0 } = {}) {
   // RESUME (module C) — hamr's checkpoint ruling in a time coat: a run killed
   // mid-try restarts THAT try under the REMAINDER of its signed per-try numbers,
   // because "a budget ceiling folds in prior spend so re-invoking cannot silently

package/src/declaredclose.js

@@ -71,7 +71,7 @@
 import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED } from './kinds.js';
 import {
   validateDeclaration, classGuards, genreOwnedEnvNames, ungroundedGenreEnv, GENRE_LANGUAGES, TYPES_GENRE,
-  VERDICT_CLASSES, LIVE_CLASSES,
+  VERDICT_CLASSES, LIVE_CLASSES, NEVER_OFFERED_KINDS,
 } from './authoring.js';
 import { stageGap } from './ralph.js';
 import { isObj, isNonEmptyString } from './validate.js';
@@ -112,12 +112,68 @@ export const DECLARED_GAP_PREFIX = 'close: ';
  * whole judged output rather than a hand-picked slice of it. */
 export const DECLARED_GAP_KEEP = `^${DECLARED_GAP_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`;
 
-/** The verdict class a DECLARED close may claim. Hard, and by CONSTRUCTION
- * rather than by assertion: every live kind is a mechanical command whose
- * measurement is the truth, and the two judgment kinds are locked out at the
- * catalogue (M2) and absent from the executor (M1). Named as data so the job
- * validator reads one hierarchy table rather than hard-coding a class. */
-export const DECLARED_CLOSE_CLASSES = Object.freeze(['hard']);
+/**
+ * The close verdict word for a run WAITING on a person (N4 §1.3/§1.4). A
+ * literal, exported, because three readers key on it — the runner's pause
+ * branch, the ledger's excluded set, and the trend reader's blind rule — and
+ * three hand-spelled copies of one terminal is how they come to disagree.
+ *
+ * It is not in `CLOSE_FAULTS` and must never be added: a fault says the close
+ * could not render a verdict, and this says the close is not FINISHED rendering
+ * one. The first escalates; the second is a checkpoint the operator returns to.
+ */
+export const HUMAN_PAUSE = 'human-pause';
+
+/**
+ * The RUN-level terminal names the hitl class mints one layer up from
+ * `HUMAN_PAUSE` (N4 §1.3–§1.5): the checkpoint, and the honest refusal of the
+ * operator's rerun input. Spelled once here, beside the close-verdict word they
+ * translate, for the same reason `HUMAN_PAUSE` is — the emitters (`planrun.js`),
+ * the ledger's excluded set, the resume reader (`reuse.js`), and the runner
+ * script all key on them, and hand-spelled copies of one terminal is how they
+ * come to disagree.
+ *
+ * There were three (2026-08-17): `hitl-cancel` was the signer's own terminal and
+ * is DELETED with the door it belonged to. A person who does not want to carry on
+ * now PAUSES — the same checkpoint, resumable, retired by the TTL if nobody comes
+ * back — so nothing in this tree mints that name any more. The ledger keeps the
+ * bare string in its excluded set so a spine written before this change still
+ * reads as governance rather than as a capability gap; that is a READER's
+ * backward compatibility, and deliberately not a constant a writer could reach.
+ */
+export const HITL_PAUSE = 'hitl-pause';
+export const HITL_DECISION_RED = 'hitl-decision-red';
+
+/**
+ * The terminals above that leave the run WAITING ON A PERSON — as a list, minted
+ * beside the names it holds so a reader keys on membership rather than on a
+ * spelling, and a rename here travels to every reader for free.
+ *
+ * It is deliberately NOT `reuse.js`'s `CHECKPOINT_OUTCOMES`, which is the wider
+ * RESUME list: every stop that left work on disk and an allowance unspent, money
+ * and time included. Those are governance stops the reuse loop is meant to try
+ * again under its remaining tries; this is the half no further attempt can
+ * change, because the allowance still unspent is a human answer. `CHECKPOINT_OUTCOMES`
+ * is composed FROM this list so the two can never disagree about which is which.
+ *
+ * `HITL_DECISION_RED` is not here: it is a verdict already rendered on the operator's
+ * own input, not a question still open.
+ */
+export const HUMAN_CHECKPOINTS = Object.freeze([HITL_PAUSE]);
+
+/** The verdict classes a DECLARED close may claim. Named as data so the job
+ * validator reads one hierarchy table rather than hard-coding a class.
+ *
+ * `hard` is by CONSTRUCTION: every mechanical kind is a command whose measurement
+ * is the truth. `hitl` joined it at N4 slice 1, and only because `human-confirms`
+ * is genuinely LIVE — the widening and the kind go in one commit, or this table
+ * admits a class the executor cannot render. The `soft` class is still absent:
+ * `judged-floor` is locked, so no declaration can reach above hitl.
+ *
+ * The direction that matters is unchanged. This says which class a declaration
+ * MAY claim; `closeCeiling` says which class its stages actually NEED. A pick
+ * below the ceiling is still the silent upgrade `class-ceiling` refuses. */
+export const DECLARED_CLOSE_CLASSES = Object.freeze(['hard', 'hitl']);
 
 /** @param {any} job @returns {boolean} */
 export function isDeclaredClose(job) {
@@ -135,7 +191,15 @@ export function isDeclaredClose(job) {
  */
 export function declaredStages(closeDecl) {
   if (!isObj(closeDecl) || !Array.isArray(closeDecl.stages)) return null;
-  return closeDecl.stages.map((s) => (isObj(s) ? { ...s, gapKeep: DECLARED_GAP_KEEP } : s));
+  return closeDecl.stages.map((s) => (isObj(s)
+    // RULING 5, stamped by the ARBITER rather than trusted from the artefact:
+    // a judged or human stage is `offer: false` BY LAW, so `checkMenu` can never
+    // hand the agent `check-passes(<a person>)`. The validator refuses a
+    // declaration that says anything else (`human-stage-offered`), so this is
+    // never overwriting a signer-visible value — it is filling in a law the
+    // declaration schema deliberately gives the composer no way to state.
+    ? { ...s, gapKeep: DECLARED_GAP_KEEP, ...(NEVER_OFFERED_KINDS.includes(s.kind) ? { offer: false } : {}) }
+    : s));
 }
 
 // ── the spec-level gate ──────────────────────────────────────────────────────
@@ -361,7 +425,7 @@ export function guardNames(closeDecl, verdictType) {
  * @param {any} r an M1 `StageResult`
  * @param {(s: string) => string} redact
  * @returns {{verdict: string, notes?: string, gap?: string, detail?: string,
- *   exitCode?: number, judgedCount?: number}} `notes` is absent, never empty —
+ *   exitCode?: number, judgedCount?: number, ask?: string|null}} `notes` is absent, never empty —
  *   a field that is always there says nothing; a RED carries its diagnostics
  *   inside `gap` and so has none of its own.
  */
@@ -370,6 +434,13 @@ function translate(r, redact) {
   /** absent rather than empty: a field that is always there says nothing */
   const notes = gapText ? { notes: gapText } : {};
   if (r.verdict === 'green') return { verdict: 'satisfied', judgedCount: 1, ...notes };
+  // THE PAUSE (N4 §1.3) — its own verdict word, and deliberately NOT one of the
+  // three below. `satisfied` would mint a green nobody gave; `needs_revision`
+  // would hand the fix worker a gap the person has not written yet; a
+  // `CLOSE_FAULTS` word would file a working arbiter as a broken instrument.
+  // No `gap` and no `judgedCount`: nothing was judged, and every consumer guards
+  // with `if (gap)`.
+  if (r.verdict === 'pause') return { verdict: HUMAN_PAUSE, ask: r.detail?.ask ?? null, ...notes };
   if (r.verdict === 'red') {
     return {
       verdict: 'needs_revision',
@@ -408,11 +479,12 @@ function translate(r, redact) {
  * @param {any[]} stages declared stage descriptors, already validated
  * @param {(s: string) => string} [redact] the scrub, applied at THIS boundary
  * @param {{timeoutMs?: number, cwd?: string, seedRef?: string,
- *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree'}} [opts]
+ *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree',
+ *   humanRuling?: {decision: string, text?: string|null}|null}} [opts]
  * @returns {Promise<any>}
  */
 export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
-  const { timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode } = opts;
+  const { timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode, humanRuling = null } = opts;
   if (!isNonEmptyString(cwd) || !isNonEmptyString(seedRef)) {
     // Refuse rather than guess. A declared close measures against a SEED; a
     // missing one is the close unable to run, not a red about the worker.
@@ -436,6 +508,11 @@ export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
     ...(gapCap !== undefined ? { gapCap } : {}),
     ...(maxBuffer !== undefined ? { maxBuffer } : {}),
     ...(baselineMode !== undefined ? { baselineMode } : {}),
+    // the SIGNER's answer, when this close has a human stage and a leg is
+    // carrying one. Absent (null) is the ordinary path AND the pause path — the
+    // human stage reads the absence as "nobody has answered yet", which is the
+    // whole of what a pause means.
+    humanRuling,
     seedTrees,
   };
   try {

package/src/index.js

@@ -60,7 +60,7 @@ export { renderListing, selectionPrompt } from './selection.js';
 // `resumeTreeGate` is the ruling that a resumed patient is continued dirty and never
 // reset. Both are read by a runner BEFORE the approval gate, so neither can live behind
 // `runReuse`'s own entry.
-export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate } from './reuse.js';
+export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate } from './reuse.js';
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from './ledger.js';
 // THE WORK BRANCH (PRD v1.57 §3). `workBranchName` is exported so an operator runner can
 // SHOW, before the approval gate, which branch the run will work on — the same reason the
@@ -89,6 +89,10 @@ export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE }
 export {
   runDeclaredClose, runStage, seedRead, seedAtHead, seedListing, changedSet, makeSeedTrees,
   LIVE_KINDS, STOP_FAULTS, JUDGED_MARKER, EXIT_GREEN, EXIT_RED, EXIT_STOP,
+  // N4 slice 1 — the hitl surface an adopting runner needs: the three doors, the
+  // gate that reads a signer's answer (and refuses an empty one), and the seed
+  // exemption ruling 8 states.
+  HUMAN_DECISIONS, SEED_EXEMPT_KINDS, normalizeHumanRuling,
 } from './kinds.js';
 // M2 — what a declaration may SAY, and whether one said it legally. The
 // catalogue and the genre are DATA an integrating UI renders (the kind menu, the
@@ -103,6 +107,8 @@ export {
   // the verdict-class surface (PRD v1.57 §1–§2): the radio's own menu, the guard
   // battery keyed off it, and the ceiling that makes the pick a promise
   VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, CLASS_BATTERIES, classGuards, closeCeiling,
+  // ruling 5 as data: the kinds no agent may ever be offered as an in-run ruler
+  NEVER_OFFERED_KINDS,
 } from './authoring.js';
 // M3 — the looking half and the writing half. `authorClose` is the grounded
 // loop; `runAuthorScout`/`buildSeedListing` are exported because a caller that
@@ -128,6 +134,7 @@ export {
 export {
   validateCloseDecl, runDeclaredStages, declaredStages, isDeclaredClose, guardNames, closeGrade,
   DECLARED_GENRES, DECLARED_GAP_PREFIX, DECLARED_GAP_KEEP, DECLARED_CLOSE_CLASSES, CLOSE_DECL_FIELDS,
+  HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS,
 } from './declaredclose.js';
 export { closeStagesOf } from './plan.js';
 // M4b — the interview, the refusal, the composition, and D9's three gates.

package/src/job.js

@@ -1,5 +1,5 @@
 // Job-spec validator — the OPERATOR-owned half of the config story (N1,
-// design record: docs/plans/2026-07-12-n1-job-close-schema-design.md).
+// design record: docs/02-features/2026-07-12-n1-job-close-schema-design.md).
 // A job spec is the arbiter's rulebook: the close chain, the budget, the
 // outer write fence, the escalation route. It is pure declarative data —
 // no freeform code is expressible anywhere in it — and it validates
@@ -103,7 +103,12 @@ export const LOCKED_TOOLS = Object.freeze(['run']);
  * pattern: disclosure ≠ admission), so the ledger counts the demand and the
  * non-code rung later fills a declared slot instead of reshaping the schema. */
 export const VERDICT_TYPES = Object.freeze(['green', 'soft-green', 'hitl']);
-export const LOCKED_VERDICTS = Object.freeze(['soft-green', 'hitl']);
+/** N4 slice 1: `hitl` is ADMITTED — the class whose *done* needs a person runs
+ * through the same signed spec, the same agent-authored plan and the same
+ * arbiter as a green job (the nine rulings, 2026-08-07; the three-button surface,
+ * 2026-08-12). `soft-green` stays declared-but-locked until its judged floor is
+ * built and proven (slice 2): a wobbly ruler must not mint anything. */
+export const LOCKED_VERDICTS = Object.freeze(['soft-green']);
 /** which close CLASS a declared verdictType demands — the close hierarchy one
  * level up: the same laundering guard as CLASS_BY_CLOSE, applied to the plan
  * shape's single close (green on a rubric would be a fake-hard verdict). */