bareloop 0.10.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
  */
@@ -1323,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,
 };
 
 /**
@@ -1387,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();
@@ -1412,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;
@@ -1431,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([
@@ -82,6 +83,28 @@ const EXCLUDED_ESCALATIONS = new Set([
   '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.

package/src/planrun.js

@@ -33,8 +33,11 @@ import { globToPrefix, redactSecrets, SECRET_PATTERNS } from './validate.js';
 import { validateBridge, loadGate } from './bridges.js';
 import { extractArtifact } from './text.js';
 import { createClock, isWallTimeout } from './clock.js';
-import { isDeclaredClose, runDeclaredStages, validateCloseDecl, closeGrade } from './declaredclose.js';
-import { seedAtHead, seedListing, GAP_TRIM_MARKER, GATE_AUDIT_FILE, ARBITER_BOOK_STORES } from './kinds.js';
+import { isDeclaredClose, runDeclaredStages, validateCloseDecl, closeGrade, HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED } from './declaredclose.js';
+import {
+  seedAtHead, seedListing, changedSet, GAP_TRIM_MARKER, GATE_AUDIT_FILE, ARBITER_BOOK_STORES,
+  HUMAN_KIND, HUMAN_DECISIONS, normalizeHumanRuling,
+} from './kinds.js';
 import { workBranchName, prepareWorkBranch } from './workbranch.js';
 
 const require = createRequire(import.meta.url);
@@ -65,6 +68,11 @@ const NATIVE_READ_STRATEGY = '\nINTERFACE LIMIT: on this surface a whole-file re
 const SCOUT_MIN_BYTES = 200;
 /** feed-forward artifact bound per step (prompt ingredient, spine-bound) */
 const ARTIFACT_MAX = 2000;
+/** how many changed paths ride the hitl pause's evidence package. Bounded like
+ * every other list this repo puts on a spine, and the trim ANNOUNCED (F28): the
+ * person needs to see WHAT moved, and a run that touched a thousand files is
+ * telling them something a thousand lines would not. */
+const PAUSE_CHANGED_CAP = 50;
 /** the wallet floor below which a replan is a stop, not an adaptation (review
  * #5): a money-gate halt drains the wallet to ~0, so replanning against dust
  * just burns another draft and mislabels the money-cut as "exits still red"
@@ -581,12 +589,24 @@ ${scoutBlob || '(no scout notes)'}`;
  *   it the deterministic name would collide with that very branch and the collision walk
  *   would mint a `-2` beside the progress the resume exists to keep. Absent is the cold
  *   path. A recorded branch that no longer exists is a STOP, never a fresh start.
+ * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ *   answer at a hitl pause (2026-08-12 §1, re-cut 2026-08-17: accept | rerun <text> | pause), carried in
+ *   by the runner on the leg that RESUMES a paused run. Absent on every ordinary run and
+ *   on the leg that pauses; it is never authored, never defaulted, and never inferred.
+ *
+ *   It is spent ONCE, on this leg's close readings up to the moment the fix loop opens:
+ *   `accept` greens the human stage on fresh evidence (OPEN-3 — the mechanical stages
+ *   re-run first, because the tree can change while a run is paused), `rerun` reds it
+ *   with the human's own words as the gap, and `pause` keeps the checkpoint exactly as it
+ *   is, before anything is read at all. After the fix loop opens the ruling is gone, so once the mechanical
+ *   stages pass again the run PAUSES for a second review rather than converting the same
+ *   sentence forever.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
- *   'step-stalled' | `step-red:<id>`
+ *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null }) {
+export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null }) {
   workdir = resolve(workdir);
   // ONE spelling of the redaction, housed next to the inventory it reads
   // (src/validate.js) — the same helper the isolate verbs scrub the litectx store
@@ -638,6 +658,79 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     return 'close-unsupported';
   }
 
+  // ── THE SIGNER'S ANSWER (N4 §1.4), read before anything costs anything.
+  //
+  // Three gates, and each refuses rather than guesses. A decision that is not one
+  // of the three doors — or a `rerun` whose text is empty — is refused at the
+  // seam that ACCEPTS it, because the whole of what a rerun gives the fix worker
+  // is the human's words, and an empty gap re-runs the worker as though nothing
+  // had been said (the POC's negative control measured exactly that). A decision
+  // handed to a close with no human stage is refused too: there is nothing for it
+  // to rule on, and silently ignoring it would leave a person believing they had
+  // answered. It is a terminal of its own rather than an `interpreter-red` — no
+  // library failed, the operator's own input is what could not be read.
+  const hasHumanStage = stagedClose.some((/** @type {any} */ s) => s?.kind === HUMAN_KIND);
+  const ruling = normalizeHumanRuling(humanRuling);
+  const decisionRed = (/** @type {string} */ detail) => {
+    emit('escalation', {
+      category: HITL_DECISION_RED, decisionReady: true,
+      decision: 'The decision handed to this run could not be applied, so nothing was run and nothing was spent.',
+      options: [
+        `re-run the resume with one of: ${HUMAN_DECISIONS.join(' | ')} (a rerun carries the text the worker converts)`,
+        'abandon the task',
+      ],
+      detail: scrub(detail),
+    });
+    return HITL_DECISION_RED;
+  };
+  if (!ruling.ok) return decisionRed(/** @type {string} */ (ruling.why));
+  if (ruling.ruling !== null && !hasHumanStage) {
+    return decisionRed(`this job's close has no ${HUMAN_KIND} stage, so a signer's "${ruling.ruling.decision}" has `
+      + 'nothing to rule on — the verdict class is a promise about the CLOSE, and only a close that asks a person '
+      + 'can be answered by one');
+  }
+  /** the ruling still to be spent. Cleared the moment the fix loop opens: the
+   * human's words are what OPENS that loop, and once the worker holds them the
+   * next machine-clean tree is a new question for the person, not the old one. */
+  let liveRuling = ruling.ruling;
+
+  // ── PAUSE: the third door, and it costs nothing at all (2026-08-12 §1, doors
+  // re-cut 2026-08-17). Before the branch, the seed, the precheck and the clock,
+  // because a person who answered "not now" has asked for nothing to be done: no
+  // gap, no continuation, no worker round. It is deliberately NOT routed through
+  // the close — running four stages to arrive back at the question the person has
+  // just declined to answer is wall time spent on an answer already in hand.
+  //
+  // hamr's ruling, verbatim: *"what's the point of cancel anyways? pause can
+  // resume — that would be more honest"*. So this mints the SAME checkpoint
+  // terminal the machine-side pause mints, which is what keeps it resumable under
+  // the existing TTL: the run re-enters at the start of its last step whenever
+  // somebody comes back, and if nobody does, the checkpoint expires on its own.
+  // That expiry IS the case cancel used to serve, without forcing a person into a
+  // forever-decision at the moment they least want to make one.
+  //
+  // The record is EXPLICIT (`humanDecision`) rather than a silent re-pause: "a
+  // person looked and kept it" and "nobody has looked yet" are two different
+  // facts, and one record spelling both is how a reader comes to confuse them.
+  // The evidence package is not re-assembled here — it is already on the spine of
+  // the leg that asked, and this leg measured nothing, so it states nothing (F6:
+  // absent, never an empty list dressed as a reading).
+  if (liveRuling?.decision === 'pause') {
+    emit(HITL_PAUSE, {
+      stage: stagedClose.find((/** @type {any} */ s) => s?.kind === HUMAN_KIND)?.name ?? null,
+      humanDecision: 'pause',
+      decisionReady: true,
+      // EXPLICITLY null, never absent: every gap consumer guards with `if (gap)`,
+      // and the field states the ruling rather than leaving it to be inferred.
+      gap: null,
+      decision: 'The signer looked and paused: nothing was asked for, so nothing was run and nothing was spent. The '
+        + 'checkpoint stands exactly as it was — the work, the plan and the money are where the paused leg left them.',
+      options: [...HUMAN_DECISIONS],
+      meaning: 'not a verdict — the run is still paused, the clock is still stopped, and the same three doors are open',
+    });
+    return HITL_PAUSE;
+  }
+
   // ── native wiring: a clipipe-subscription job needs the native provider
   // FACTORY (native governance is constructor-time + per-worker, so the runner
   // cannot reuse one injected instance). A missing factory is an adopter wiring
@@ -827,7 +920,14 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * @param {any[]} stages
    */
   const runCloseStages = (stages) => (declared
-    ? runDeclaredStages(stages, scrub, { ...closeOpts, seedRef: /** @type {any} */ (declaredCtx).seedRef })
+    ? runDeclaredStages(stages, scrub, {
+      ...closeOpts,
+      seedRef: /** @type {any} */ (declaredCtx).seedRef,
+      // the signer's answer reaches the human stage the same way every other
+      // arbiter-owned fact reaches a stage: through the ctx, never through the
+      // declaration. A command close has no human stage to hand it to.
+      humanRuling: liveRuling,
+    })
     : runStages(stages, scrub, closeOpts));
   /** @type {string|undefined} the stage that rendered the LAST close verdict (Layer R's red-set source) */
   let closeStage;
@@ -884,6 +984,41 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       ...extra,
     });
   };
+  /**
+   * THE PAUSE (N4 §1.3/§1.4, rulings 1 and 2) — a decision-ready checkpoint, and
+   * never a bare "approve?". What the person is shown is assembled here rather
+   * than by whatever surface renders it: every mechanical stage's own result, the
+   * question the close itself declared, and the set of files this run changed.
+   *
+   * The changed set is the "before/after" half, at the granularity a library can
+   * state honestly — WHICH files moved. Rendering the lines belongs to the
+   * surface that has a screen; carrying the list is what makes the surface's job
+   * possible without it re-deriving the run's own facts.
+   * @param {any} v the close verdict that paused @returns {Promise<void>}
+   */
+  const emitHitlPause = async (v) => {
+    const cs = declaredCtx ? await changedSet(workdir, declaredCtx.seedRef) : { stop: 'no seed', paths: [] };
+    const paths = cs.stop === null ? cs.paths : [];
+    const shown = paths.slice(0, PAUSE_CHANGED_CAP);
+    emit(HITL_PAUSE, {
+      stage: v.stage ?? null,
+      ask: v.ask ?? null,
+      decisionReady: true,
+      // ruling 2: the whole evidence package, never a bare "approve?"
+      stages: v.stages ?? [],
+      changed: {
+        paths: shown,
+        // the trim is ANNOUNCED (F28), and an unreadable set is UNKNOWN, never
+        // an empty list dressed as "nothing changed" (F6)
+        ...(paths.length > shown.length ? { more: paths.length - shown.length } : {}),
+        ...(cs.stop === null ? {} : { unreadable: scrub(String(cs.stop)) }),
+      },
+      decision: `The close reached its human stage and is waiting on you: ${v.ask ?? 'review the result'}`,
+      options: [...HUMAN_DECISIONS],
+      meaning: 'not a verdict — the run is paused, the clock is stopped, and the last thing it did stands until you answer',
+    });
+  };
+
   /** the close, as ONE verdict: every stage in order, first red wins */
   const judgeClose = async () => {
     const v = await runCloseStages(stagedClose);
@@ -1057,6 +1192,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
   const pre = await judgeClose();
   emit('close-precheck', { ...pre });
   if (pre.verdict === 'satisfied') return 'already-green';
+  // …and the pause's own arm of the same gate. Reaching a human stage HERE means
+  // every mechanical stage already passes on the untouched tree: the machine half
+  // of this job is done and the only thing left is a person. Pausing costs $0 and
+  // is the honest answer; running a plan first would spend a budget to arrive at
+  // exactly this question. No `planExecuted` — there is no plan yet, and an empty
+  // one on the spine would be a record of work nobody did.
+  if (pre.verdict === HUMAN_PAUSE) { await emitHitlPause(pre); return HITL_PAUSE; }
   const preFault = Object.hasOwn(CLOSE_FAULTS, pre.verdict) ? CLOSE_FAULTS[pre.verdict] : undefined;
   if (preFault) {
     emit('escalation', { category: preFault.category, decisionReady: true, decision: preFault.decision, options: preFault.options, detail: pre.detail });
@@ -2579,6 +2721,16 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     planExecuted();
     return 'green';
   }
+  // ── THE THIRD BRANCH (N4 §1.3): between `satisfied` and the fix loop, because
+  // a pause is neither. It is not green (nobody said so), not a red (nobody has
+  // written a gap), and not a CLOSE_FAULT (nothing broke) — so it must be caught
+  // before the fix loop, which would otherwise buy a worker round to convert a
+  // wall that does not exist yet.
+  if (post.verdict === HUMAN_PAUSE) {
+    await emitHitlPause(post);
+    planExecuted();
+    return HITL_PAUSE;
+  }
   const postFault = Object.hasOwn(CLOSE_FAULTS, post.verdict) ? CLOSE_FAULTS[post.verdict] : undefined;
   if (postFault) {
     emit('escalation', { category: postFault.category, decisionReady: true, decision: postFault.decision, options: postFault.options, detail: post.detail });
@@ -2586,6 +2738,15 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     return 'close-red';
   }
   emit('fix-loop', { gapBytes: Buffer.byteLength(post.gap ?? '') });
+  // ── THE RULING IS SPENT HERE (N4 §1.5). The human's words are what OPENS this
+  // loop; the worker now holds them. Leaving the ruling live would make the human
+  // stage red on every judgment for the rest of the leg, so the loop would keep
+  // converting one sentence until the governor or the money stopped it. Cleared,
+  // the next machine-clean tree pauses for a SECOND review — which is the honest
+  // cycle: a person asked for a change, the change happened, the person looks
+  // again. A mechanical red in between is still converted normally, because
+  // first-red-wins reaches it before the person's stage.
+  liveRuling = null;
   let fixOutcome;
   /** @type {object|null} W-2 — set when the WALL stopped the fix loop BETWEEN
    * iterations. It carries that stop's own record fields, and its presence is what
@@ -2667,6 +2828,15 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     const fixGovernor = {
       record: (/** @type {{iteration: number, gap?: string}} */ o) => {
         fixIterationsUsed = o.iteration;
+        // A PAUSE IS NEVER GRADED. ralph records every non-satisfied iteration,
+        // and a pause is one — but it carries no gap and no number, so feeding it
+        // to the trend would mint a strike out of a non-verdict and could strike
+        // the loop out into a `cap-halt` that never happened. The reading says
+        // what it is and the meter is left untouched; `middle` stops the loop on
+        // the next iteration, before anything is bought.
+        if (lastCloseVerdict?.verdict === HUMAN_PAUSE) {
+          return { governor: 'close-trend', trend: 'unknown', reading: 'the close is waiting on a person — not a grade', iteration: o.iteration, paused: true };
+        }
         return { governor: 'close-trend', ...fixTrend.record({ gap: o.gap }), iteration: o.iteration };
       },
       struckOut: fixTrend.struckOut,
@@ -2708,6 +2878,19 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // until the next iteration is about to start. The close is never bounded — a
       // wall that kills grading leaves the run unreadable after the money is spent
       // (the F45 class), so the one thing this must never do is stop a close.
+      // ── THE CLOSE IS WAITING ON A PERSON. Read here, in the same place and for
+      // the same reason the wall is: past this point the iteration is guaranteed
+      // to be worthless, because the machine half of the close already passes and
+      // nothing a worker writes can answer a question only a person can. So the
+      // loop stops ON that reading — the run pauses again, with everything it has
+      // done kept, exactly as the first pause did.
+      if (lastCloseVerdict?.verdict === HUMAN_PAUSE) {
+        const err = /** @type {CategorizedError} */ (new Error(
+          `the close is waiting on the signer at stage "${lastCloseVerdict.stage ?? 'unknown'}" — every mechanical `
+          + `stage passes, so fix attempt ${iteration} could not change the answer`));
+        err.category = HITL_PAUSE;
+        throw err;
+      }
       if (clock.expired()) {
         // ONE progress instrument, shared with the money halt (PRD v1.46 §2/§4).
         // This site used to run its own `gapTrend`: byte equality of the last two
@@ -2789,6 +2972,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     return relay(e, 'fix');
   }
   planExecuted();
+  // The fix loop ran into the person again (the `middle` stop above). Same
+  // terminal as the first pause, and never `escalated`: nothing failed, and the
+  // work this loop did is exactly what the signer is now being asked about.
+  if (fixOutcome !== 'green' && lastEscalation?.category === HITL_PAUSE) {
+    await emitHitlPause(lastCloseVerdict);
+    return HITL_PAUSE;
+  }
   if (fixOutcome !== 'green' && lastEscalation?.category === 'wall-halt') {
     // F64 in the close-fix loop: the same governance stop, and it must not ride out
     // as a bare `escalated` either — that reads as "the fix failed" when the fix was

package/src/ralph.js

@@ -629,6 +629,15 @@ export async function ralph({ middle, close, judge, capRuns, ladder, emit, redac
         // interpreter" would aim a human at the one component that did nothing wrong.
         'step-stalled': ['The model stopped producing rounds and reissuing the call did not recover it — a stall, not a fault.',
           ['let the planner re-allocate what is left (replan)', 'retry the run', 'check provider status', 'abandon the task']],
+        // N4 — the close is WAITING ON A PERSON. Nothing failed and nothing is
+        // discarded: every mechanical stage passes and the one stage left is a
+        // question no worker can answer, so the loop stopped rather than buying
+        // an attempt that could not change the answer. The caller renders the
+        // real decision-ready package (`hitl-pause`, with the evidence); this
+        // entry exists so the passthrough never narrates a paused run as a
+        // broken middle.
+        'hitl-pause': ['The close reached its human stage — the run is paused, decision-ready, and the clock is stopped.',
+          ['accept', 'rerun (your words become the gap the worker converts)', 'pause (the checkpoint keeps, and it resumes)']],
       };
       // Object.hasOwn, not bare lookup: a category named after an
       // Object.prototype member ("toString") would return the inherited