bareloop 0.10.0 → 0.11.0

package/src/reuse.js

@@ -1,5 +1,5 @@
 // Layer 3 — the D7 ENVELOPE and the REUSE RUNNER (design record
-// docs/plans/2026-08-01-layer-3-reuse-design.md, D3/D5/D6/D7 + R1).
+// docs/02-features/2026-08-01-layer-3-reuse-design.md, D3/D5/D6/D7 + R1).
 //
 // hamr's sentence is the whole specification of this file, verbatim:
 //
@@ -52,6 +52,12 @@ import { closeStagesOf } from './plan.js';
 import { MIN_WALL_MS, jobSpecHash } from './job.js';
 import { isObj, isNonEmptyString } from './validate.js';
 import { readGrade } from './trend.js';
+
+/** the paused-run TERMINAL and its spine record share one name (`runPlan` returns
+ * it and `runJob` writes it onto `job-end`), spelled once in `declaredclose.js`
+ * beside the close-verdict word it translates, so the emitters, the checkpoint
+ * list, and the TTL gate below cannot drift from each other */
+import { HITL_PAUSE, HUMAN_CHECKPOINTS } from './declaredclose.js';
 import { extractArtifact, priceOf } from './text.js';
 import { runJob as shippedRunJob } from './run.js';
 
@@ -84,6 +90,34 @@ const { Loop } = require('bare-agent');
  */
 export const REUSE_GRADED_RED = Object.freeze(['escalated']);
 
+/**
+ * WHICH TERMINALS ARE A CHECKPOINT — the list a runner hands `readResume` as
+ * `resumableOutcomes`, minted HERE rather than in whichever script happens to
+ * launch a run.
+ *
+ * `readResume` deliberately takes it as a parameter and defaults to empty, and
+ * that stays true: the reuse loop's own semantics depend on the empty default.
+ * What did not exist was a canonical ANSWER, so `scripts/run-u.mjs` kept its own
+ * copy — and the exported bundle (PRD v1.44 §2: a thin runner with bareloop as a
+ * dependency) would have had to keep a third. The same reasoning that put the
+ * pause TTL in the library (OPEN-2, hamr, 2026-08-13) puts this here.
+ *
+ * Every entry is a stop that left WORK ON DISK and an allowance unspent — money,
+ * time, a self-healed stall, and now a person who has not answered yet. A verdict
+ * already rendered is never on this list: `green`/`escalated` are graded rows, and
+ * re-buying one would pay twice for an answer already in hand. (The signer's own
+ * `hitl-cancel` terminal used to be the other example; the door was deleted on
+ * 2026-08-17 — a person who does not want to carry on pauses, and the checkpoint
+ * they keep is retired by the TTL rather than by a terminal.)
+ *
+ * The human half is SPLICED IN from `declaredclose.js` rather than spelled again,
+ * because the try loop below reads the two halves differently and a second copy is
+ * how they would come to disagree about which member is which: the first three are
+ * allowances the loop's remaining tries are meant to spend against, and the human
+ * ones are the stop no further try can change (see `hardStop`).
+ */
+export const CHECKPOINT_OUTCOMES = Object.freeze(['cap-halt', 'wall-halt', 'step-stalled', ...HUMAN_CHECKPOINTS]);
+
 /**
  * v1's definition of "the same KIND of recipe" — and it is the LOAD GATE's own: the
  * close-stage names, in the same order (`bridges.loadGate` rule 2). One predicate,
@@ -418,13 +452,24 @@ function readTry(events) {
   };
 }
 
-/** the three-way verdict read of a runJob outcome, in ONE place: a green, the one
- * GRADED red that demotes (D6), or a casualty that keeps its own name. Both the live
- * try loop and the resume reader classify through this — two spellings of "what kind
- * of answer was that" is how a casualty ends up demoting a recipe.
- * @param {string} outcome @returns {'green'|'red'|'casualty'} */
+/** the verdict read of a runJob outcome, in ONE place: a green, the one GRADED red
+ * that demotes (D6), a CHECKPOINT waiting on a person, or a casualty that keeps its
+ * own name. Both the live try loop and the resume reader classify through this — two
+ * spellings of "what kind of answer was that" is how a casualty ends up demoting a
+ * recipe.
+ *
+ * `checkpoint` is its own name rather than a fourth flavour of casualty (2026-08-17).
+ * A casualty is a run that DIED — a transport fault, a governance cut, a broken close
+ * — and a reader that sees one is being told the attempt is over. A human checkpoint
+ * is the opposite fact in every respect: nothing failed, nothing is discarded, the
+ * work and the money are exactly where they were, and the allowance still unspent is
+ * a person's answer. It behaves like neither a red nor a casualty everywhere it
+ * matters already (`hardStop` ends the loop on it, the box is left untouched), so the
+ * ROW saying "casualty" was the one place the machinery still mis-described itself.
+ * @param {string} outcome @returns {'green'|'red'|'checkpoint'|'casualty'} */
 function verdictClassOf(outcome) {
   if (outcome === 'green' || outcome === 'already-green') return 'green';
+  if (HUMAN_CHECKPOINTS.includes(outcome)) return 'checkpoint';
   return REUSE_GRADED_RED.includes(outcome) ? 'red' : 'casualty';
 }
 
@@ -1023,6 +1068,81 @@ export function readResume(events, { deathAt = null, direct = false, resumableOu
   };
 }
 
+/**
+ * THE PAUSE TTL (2026-08-12 §2): a hitl checkpoint is kept for 60 days.
+ *
+ * OPEN-2, RULED (hamr, in-turn, 2026-08-13): **the TTL lives in the LIBRARY**, so
+ * the exported bundle (a headless runner with bareloop as a dependency, PRD v1.44
+ * §2) inherits it instead of every runner re-implementing it. A script-only TTL
+ * would vanish on export — the one place the rule is most needed and least
+ * likely to be re-typed.
+ */
+export const PAUSE_TTL_MS = 60 * 24 * 60 * 60_000;
+
+/**
+ * The AGE gate for a paused checkpoint — the sibling of `resumeTreeGate`, and it
+ * asks the other question a 60-day-old checkpoint raises. The tree gate asks
+ * *is this still the tree the run left?*; this asks *is this still a decision
+ * anyone is waiting on?*
+ *
+ * THREE things it deliberately does NOT do:
+ *
+ *  - it does not widen any other resume rule. The 2026-08-12 ruling is about a
+ *    person deciding, so `applies: false` on every other terminal: a cap-halt
+ *    checkpoint is a different stop under a different allowance, and quietly
+ *    ageing it out would be a governance change nobody ruled.
+ *  - it does not treat an unreadable stamp as young (F6). A checkpoint that
+ *    cannot say WHEN it paused has an unknown age, and unknown is refused rather
+ *    than rounded down to fresh — the direction that fails safe.
+ *  - it does not skip silently. An expired checkpoint comes back as a refusal
+ *    that NAMES the age and the TTL, because the operator's next move (start
+ *    fresh) depends on knowing which of the two it hit.
+ *
+ * The clock is injected for the same reason `runPlan`'s is: a rule measured in
+ * months cannot otherwise be tested at all.
+ *
+ * @param {any[]} events the paused run's own spine, parsed, in file order
+ * @param {{now?: () => number, ttlMs?: number}} [opts]
+ * @returns {{ok: boolean, applies: boolean, ageMs: number|null, ttlMs: number, pausedAt: string|null, detail: string|null}}
+ */
+export function checkpointAgeGate(events, { now = Date.now, ttlMs = PAUSE_TTL_MS } = {}) {
+  const list = Array.isArray(events) ? events.filter(isObj) : [];
+  const end = list.filter((e) => e.type === 'job-end').at(-1) ?? null;
+  const base = { applies: false, ageMs: null, ttlMs, pausedAt: null, detail: null };
+  if (end?.outcome !== HITL_PAUSE) return { ...base, ok: true };
+
+  // the PAUSE RECORD's own timestamp, and its terminal's as the fallback: the
+  // pause is what the human is answering, so its stamp is when the waiting began
+  const pause = list.filter((e) => e.type === HITL_PAUSE).at(-1) ?? end;
+  const pausedAt = typeof pause.ts === 'string' ? pause.ts : null;
+  const atMs = pausedAt === null ? NaN : Date.parse(pausedAt);
+  if (!Number.isFinite(atMs)) {
+    return {
+      ...base,
+      ok: false,
+      applies: true,
+      detail: 'this checkpoint does not record when it paused, so its age is unknown — and an unknown age is not a '
+        + `young one (F6). The TTL is ${Math.round(ttlMs / 86_400_000)} days; start a fresh run rather than resuming a `
+        + 'checkpoint nothing can date.',
+    };
+  }
+  const ageMs = Math.max(0, now() - atMs);
+  const days = (/** @type {number} */ ms) => Math.floor(ms / 86_400_000);
+  if (ageMs > ttlMs) {
+    return {
+      ...base,
+      ok: false,
+      applies: true,
+      ageMs,
+      pausedAt,
+      detail: `this run paused ${days(ageMs)} days ago and the pause TTL is ${days(ttlMs)} days — the tree, the `
+        + 'toolchain and the job itself have had two months to move, so the evidence the signer would be answering '
+        + 'about is no longer the evidence the run produced. Start a fresh run.',
+    };
+  }
+  return { ...base, ok: true, applies: true, ageMs, pausedAt };
+}
+
 /**
  * The PATIENT gate for a resume, which is deliberately NOT the fresh-launch one.
  *
@@ -1375,7 +1495,30 @@ export async function runReuse(opts) {
       costUsd: read.spentUsd, spendComplete: read.spendComplete, wallMs, rounds,
       ...(trySpecHash ? { specHash: trySpecHash } : {}),
     };
-    if (verdictClass === 'green' && read.plan === null) {
+    if (outcome === 'already-green') {
+      // A GREEN THAT PREDATES THE RUN mints nothing, and the guard keys on the
+      // TERMINAL rather than on the absence of a plan. `already-green` means the
+      // close was satisfied at the precheck — before this leg wrote a byte — so
+      // whatever plan is on the spine did not produce it, and minting a version
+      // from one would be learning credit for work that did not happen.
+      //
+      // It used to be covered by accident: a cold already-green never drafts, so
+      // `read.plan` was null and the branch below caught it. N4 broke that
+      // accident — a hitl try that PAUSED and came back with the signer's
+      // `accept` lands `already-green` with its predecessor's `plan-accepted`
+      // sitting in the same try window. A rule with no wired detector is prose.
+      bridgeWrites.push({
+        name,
+        action: 'none',
+        file: null,
+        reds: [{
+          code: 'green-predates-run',
+          path: 'outcome',
+          detail: 'the close was already satisfied before this run did anything (already-green) — nothing here earned '
+            + 'a version, and a plan on the spine did not produce this green',
+        }],
+      });
+    } else if (verdictClass === 'green' && read.plan === null) {
       // a green with no plan on the spine cannot mint a version — the artifact that
       // inherits is the one that RAN, and there is nothing here to inherit. Reported,
       // never faked with a placeholder.
@@ -1389,6 +1532,26 @@ export async function runReuse(opts) {
         toolsUsed: [...new Set((read.plan.steps ?? []).flatMap((/** @type {any} */ s) => s.tools ?? []))],
       };
       row.bridgeWrite = writeGreen(bridge, meta, { ...record, plan: read.plan });
+    } else if (HUMAN_CHECKPOINTS.includes(outcome)) {
+      // A PAUSE IS NOT A RESULT, so the box gets nothing — not a casualty row, not a red,
+      // and the workflow is left exactly as it was. The recipe has not been judged: the
+      // close is not FINISHED rendering its verdict, and the answer that would finish it
+      // is a person's. Filing it as history would put a row on the entry that reads as a
+      // run this workflow failed to carry, and the signer's `accept` moments later would
+      // leave that row standing as evidence against a workflow that in fact greened.
+      // Recorded as an explicit no-write for the already-green branch's reason: a reader
+      // never has to branch on absence.
+      bridgeWrites.push({
+        name,
+        action: 'none',
+        file: null,
+        reds: [{
+          code: 'run-paused-for-decision',
+          path: 'outcome',
+          detail: `the run is waiting on a person (${outcome}) — nothing has been judged yet, so there is no result to `
+            + 'file against this workflow. The row is written by whatever the resumed run finally earns.',
+        }],
+      });
     } else if (bridge) {
       // R1: the recipe is NOT edited by a red. `outcome` rides in verbatim — a casualty
       // keeps its own name, and only the literal 'red' demotes (D6).
@@ -1495,6 +1658,31 @@ export async function runReuse(opts) {
    * @param {any} row @returns {any|null} the terminal, or null to carry on
    */
   const hardStop = (row) => {
+    // THE HUMAN HALF, read before the table and off the LIBRARY's own list: a run
+    // waiting on a person is not one of the stops below, which are properties of the
+    // run that would reproduce for $0. This one is the opposite — a try that did real
+    // work and reached the one stage a machine cannot render. Buying the next try (and
+    // then the cold leg) would spend the envelope re-asking a question already put to
+    // someone who has not replied yet, and the second attempt could not be graded any
+    // sooner than the first. The allowance still unspent is a person, so the loop stops
+    // and hands the run back; the checkpoint on disk is untouched and resumable, which
+    // is the runner script's half (N4 §1.6, PAUSE_TTL_MS).
+    if (HUMAN_CHECKPOINTS.includes(row.runOutcome)) {
+      return done(row.runOutcome, {
+        category: row.runOutcome,
+        decision: 'The run reached a stage only a person can render, and it is waiting on that answer. Every further '
+          + 'try and the cold leg would run the same job to the same question, so the loop stops here rather than '
+          + 'buying attempts nobody can grade yet. Nothing is lost: the run kept everything it did, and it resumes '
+          + 'from this checkpoint once the decision is in.',
+        options: [
+          'read the evidence package the pause recorded, then answer it and resume this run',
+          'leave it: an unanswered checkpoint expires on its own once the pause TTL is up',
+        ],
+      // NOT re-filed, for `interpreter-red`'s reason: the pause already escalated from
+      // its own site inside the run, under this same name and with the evidence package
+      // attached. A second copy here would count one person's pending decision twice.
+      }, false);
+    }
     const decisions = {
       'unapproved-spec': {
         decision: `No approval record matches the per-try spec (hash ${trySpecHash}). Tightening the caps with an envelope makes a NEW spec version, and a new version is signed, not inherited — nothing was run.`,

package/src/root.js

@@ -1,5 +1,5 @@
 // Layer R — the root: the within-run ratchet (LAYERS.md item 2; design record
-// docs/plans/2026-07-19-layer-r-design.md). One state that survives attempts
+// docs/02-features/2026-07-19-layer-r-design.md). One state that survives attempts
 // inside ONE run so a never-green run stops repeating itself (F21). Role is
 // CONTINUITY ONLY — F39 measured that hand-delivered state buys no conversion;
 // the semantic converter is Layer 2's job, not this module's.

package/src/run.js

@@ -3,7 +3,7 @@
 // smoke, the ONE budget ledger (cap-not-estimate; unpriced is never free, F6),
 // and the decision-ready stops. It composes the plan flow below it and
 // interprets nothing itself.
-// Design record: docs/plans/2026-07-12-n2-headless-loop-design.md.
+// Design record: docs/02-features/2026-07-12-n2-headless-loop-design.md.
 //
 // The legacy operator-authored `steps[]` path was DELETED 2026-07-26 (PRD
 // v1.32): the drafting call, config-v1, the per-step interpret loops and the
@@ -140,12 +140,18 @@ async function primitiveSmoke(workdir) {
  *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
  *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
  *        binding.)
+ * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ *   answer at a hitl pause (accept | rerun <text> | pause), carried by the leg that
+ *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
+ *   ordinary run; never authored and never defaulted (a defaulted answer to "is this
+ *   done?" is the rubber-stamp the class exists to prevent, 2026-08-12 §4).
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
- *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
+ *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
+ *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null }) {
   // 0. the ledger's counters, declared FIRST so that every job-end — including
   // the pre-token reds below — can state a real figure. An omitted `spentUsd` is
   // not a zero: a consumer reads `undefined` and either crashes or launders it
@@ -283,7 +289,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch,
+      workdir, provider, nativeProvider, providerFor, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling,
       remainingUsd: () => Math.min(shellCapUsd, job.budgetUsd - spentUsd),
       isUnpriced: () => unpriced, // F6: let the plan flow bail in-flight, not just after it returns
       spendComplete, // …and let its money-halt readout say whether the remaining it quotes is exact

package/src/selection.js

@@ -1,5 +1,5 @@
 // Layer 3 — D3's DISPLAY half: the workflow LISTING, and the prompt that asks for a
-// pick (design record docs/plans/2026-08-01-layer-3-reuse-design.md, D3).
+// pick (design record docs/02-features/2026-08-01-layer-3-reuse-design.md, D3).
 //
 // hamr's ruling, verbatim: *"i think there should be a listing for workflows names that
 // user can choose or auto-choose, or do we want llm to always decide (we still need to

package/types/authorflow.d.ts

@@ -346,9 +346,25 @@ export function resolveSourcePrefixes({ workdir, sourcePaths, seedFiles }: {
  * run could not be read afterwards. A cost entry with no raw beside it is that
  * run again.
  */
-/** @param {{ceilingUsd?: number|null}} [o] the OPERATOR's ceiling; `null`/absent is UNBOUNDED */
-export function makeCostBook({ ceilingUsd }?: {
+/**
+ * @param {{ceilingUsd?: number|null,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void}} [o]
+ *   `ceilingUsd` is the OPERATOR's ceiling; `null`/absent is UNBOUNDED.
+ *   `onCall` is a REPORTING seam fired as each metered call lands — the shell's
+ *   only chance to know what has been spent while the run is still alive. It is
+ *   never consulted and never governs: `capStop` below is still the one
+ *   predicate, still asked between calls, and still reads the same `entries`.
+ *   `absorb` deliberately does NOT fire it: those calls were metered (and
+ *   reported) by whoever made them, and reporting them twice would double the
+ *   scout's spend in every reader downstream.
+ */
+export function makeCostBook({ ceilingUsd, onCall }?: {
     ceilingUsd?: number | null;
+    onCall?: (call: {
+        label: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }) => void;
 }): {
     /** @param {string} label @param {any} r a bare-agent run result @param {number} [attempt] */
     add(label: string, r: any, attempt?: number): {
@@ -450,10 +466,12 @@ export function makeLoopGenerate(provider: any, { system, maxTokens }?: {
  *   listing?: {stop: string|null, files: string[]|null, block: string|null, meta: any}|null,
  *   generate: Function, seedReadFn?: Function, closeCtx?: any,
  *   ceilingUsd?: number|null,
+ *   onPhase?: (phase: string, data?: any) => void,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   maxRevisions?: number, structureRetries?: number,
  *   structuredMode?: 'tool'|'text', catalogue?: Record<string, any>}} o
  */
-export function authorClose({ workdir, seedRef, lang, verdictType, answers, questions, scout, listing, generate, seedReadFn, closeCtx, ceilingUsd, maxRevisions, structureRetries, structuredMode, catalogue, }: {
+export function authorClose({ workdir, seedRef, lang, verdictType, answers, questions, scout, listing, generate, seedReadFn, closeCtx, ceilingUsd, onPhase, onCall, maxRevisions, structureRetries, structuredMode, catalogue, }: {
     workdir: string;
     seedRef: string;
     lang: string;
@@ -479,6 +497,12 @@ export function authorClose({ workdir, seedRef, lang, verdictType, answers, ques
     seedReadFn?: Function;
     closeCtx?: any;
     ceilingUsd?: number | null;
+    onPhase?: (phase: string, data?: any) => void;
+    onCall?: (call: {
+        label: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }) => void;
     maxRevisions?: number;
     structureRetries?: number;
     structuredMode?: "tool" | "text";
@@ -529,21 +553,66 @@ export const STRUCTURE_INSTRUCTION_TEXT: string;
  * cannot emit anything else (D2/D3), so a genre it has never seen is a
  * composition problem, not a catalogue problem.
  *
- * The GREEN set is questions 1–6 of the frozen TYPES set (prereg §5) BYTE FOR
- * BYTE. What is gone is the seventh slot — D13's genre CONFIRM ("this looks like
- * a type-fixing job, correct?") — superseded in full: the interview never asks
- * about a genre again. The refusal it carried did not disappear; it MOVED to the
- * composer, on the same counted `request-red` path (see `authorCloseForJob`).
- * The remaining six are already genre-neutral, which is why generalising them
- * required deleting a slot rather than rewording one.
+ * The GREEN set descends from questions 1–6 of the frozen TYPES set (prereg §5).
+ * TWO slots have been deleted since, both because the interview was ASKING FOR
+ * SOMETHING IT ALREADY HAD or already knew:
+ *
+ *   - D13's genre CONFIRM ("this looks like a type-fixing job, correct?") —
+ *     superseded in full: the interview never asks about a genre again, and the
+ *     refusal it carried MOVED to the composer, on the same counted
+ *     `request-red` path (see `authorCloseForJob`);
+ *   - "Is there a code repo I can look at? Where?" — DROPPED on hamr's ruling
+ *     after he drove the terminal interview himself (2026-08-15, verbatim: *"drop
+ *     Q6"*). The repository is a MANDATORY, STRUCTURED input already —
+ *     `runInterview`'s own `repoPath`, which the runner takes from `--patient` and
+ *     refuses to start without. Asking a person to re-type in prose a path the
+ *     machine is holding in a variable is the SWE tax this product refuses, and
+ *     it invites a second, drifting answer for the same fact (hamr's own answer
+ *     on the live run was *"Yes — the patient itself."*). Nothing downstream lost
+ *     anything: the scout reads `repoPath`, never the answer.
+ *
+ * Question 2 was WIDENED in the same ruling: it now asks for the read-or-draw-from
+ * files as well as the ones that change. The two halves belong in one answer
+ * because they are one decision for the person answering — what the work touches,
+ * and what it touches only to look at.
+ *
+ * The five that remain are genre-neutral, which is why every generalisation so far
+ * has deleted a slot rather than reworded one. They are NUMBERED CONTIGUOUSLY from
+ * 1: the number a person sees is the key their answer is filed under, and a gap
+ * would be a hole in a form nobody can explain.
  */
 export const GREEN_QUESTIONS: Readonly<{
     1: "What do you want done?";
-    2: "Which files or folders should change?";
+    2: "Which files or folders should change? And which files should the work read or draw from (they stay untouched)?";
+    3: "Is there anything that must not change?";
+    4: "How do you check today whether it's working?";
+    5: "What would make you say this came back worse than before?";
+}>;
+/**
+ * THE HITL SET (N4 slice 1) — the green questions BYTE FOR BYTE, plus one.
+ *
+ * The five are unchanged deliberately rather than economically: the
+ * mechanical-first composition law (2026-08-07) says every hitl close is
+ * *deterministic stages first, judge minimal, human last*, so a hitl job needs
+ * exactly the same mechanical facts a green one does — what changes, what must
+ * not, how it is checked today, what "worse" looks like. Rewording them would
+ * fork one interview into two that drift.
+ *
+ * The last one is the only thing the green set cannot supply, and it is not a
+ * flourish: `human-confirms` requires an `ask` — the question the signer answers
+ * at the end of the run — and nothing else in the interview names it. Without it
+ * the composer would have to invent what a person is deciding, which is the one
+ * thing a human stage must never have done for it. It is the SPREAD's next number
+ * rather than a fixed one, so a green-side deletion renumbers it instead of
+ * leaving a gap (it was 7 while the green set held six, and is 6 now it holds five).
+ */
+export const HITL_QUESTIONS: Readonly<{
+    6: "When you look at the finished result yourself, what are you deciding?";
+    1: "What do you want done?";
+    2: "Which files or folders should change? And which files should the work read or draw from (they stay untouched)?";
     3: "Is there anything that must not change?";
     4: "How do you check today whether it's working?";
     5: "What would make you say this came back worse than before?";
-    6: "Is there a code repo I can look at? Where?";
 }>;
 /**
  * The three sets. `questions: null` on a locked class is ABSENT, never `{}`:
@@ -754,6 +823,11 @@ export const PARAM_SCHEMAS: Readonly<{
     requireNonEmpty: {
         const: boolean;
     };
+    ask: {
+        type: string;
+        minLength: number;
+        description: string;
+    };
 }>;
 export type Red = {
     code: string;

package/types/authoring.d.ts

@@ -290,9 +290,11 @@ export function normalizeDeclaration(declaration: any): any;
 /** @typedef {{required: readonly string[], optional: readonly string[], pathParams: readonly string[], locked?: true, verdictClass: string, shape: string, asserts: string}} KindSpec */
 /** the whole menu, in ascending order of what it takes to render the verdict */
 export const VERDICT_CLASSES: readonly string[];
-/** declared-but-locked: selecting one is COUNTED demand, never an admission */
+/** 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: readonly string[];
-/** the classes v1 actually builds — exactly one */
+/** the classes v1 actually builds */
 export const LIVE_CLASSES: readonly string[];
 /**
  * The whole vocabulary, as DATA. `shape` and `asserts` are the strings the
@@ -508,40 +510,52 @@ export const TYPES_GENRE: Readonly<{
         }>;
     }>;
 }>;
-/**
- * THE GUARD BATTERY, KEYED BY VERDICT CLASS (hamr's ruling, PRD v1.57 §2).
- *
- * D5's battery was genre-keyed data. Under class-keyed interviews it has no
- * genre to hang from, and the ruling gives it the same home the interview took:
- * **the battery attaches to the verdict class the user picked** — not to a
- * problem-genre label, and not per catalogue KIND.
- *
- * WHY THE CLASS. What a battery is FOR is the class of dishonesty the class of
- * VERDICT admits. A green job is a job whose *done* is claimed to be
- * machine-checkable, so it carries the green battery whatever problem it came
- * from — that is the anti-suppression obligation the F87 genre earned, and it
- * must not travel with a label the interview no longer asks for.
- *
- * ATTACHMENT POINT vs CONTENTS, and the split is the whole implementation:
- *   - the battery's STRUCTURE and its un-removability key off the CLASS. That
- *     is this table: which guards exist, what they assert, which slot is the
- *     model's (`fill`), and which params are ours.
- *   - the battery's CONTENTS fill in at COMPOSITION (`compose`), because a
- *     suppression pattern, a file extension and a checker's escape hatch belong
- *     to the TOOL the declaration names, and nothing before composition knows
- *     that tool. `classGuards` resolves them from the language data below.
- *
- * A LOCKED class carries `guards: null`, not `[]`. Absent is never empty (F59):
- * `[]` would read as "this class needs no guards", which is exactly the sentence
- * D5 exists to make unsayable. Nothing ever reaches it — admission refuses a
- * locked class before its battery is asked for — and `classGuards` throws rather
- * than hand back nothing if anything ever does.
- * @type {Record<string, {locked: boolean, guards: readonly any[]|null}>}
- */
-export const CLASS_BATTERIES: Record<string, {
-    locked: boolean;
-    guards: readonly any[] | null;
+export const CLASS_BATTERIES: Readonly<{
+    green: Readonly<{
+        locked: false;
+        guards: readonly (Readonly<{
+            name: "changed-from-seed";
+            kind: "files-changed";
+            params: Readonly<{
+                requireNonEmpty: true;
+            }>;
+            compose: readonly never[];
+            fill: readonly string[];
+        }> | Readonly<{
+            name: "no-suppressions";
+            kind: "pattern-absent-in-diff";
+            params: Readonly<{}>;
+            compose: readonly string[];
+            fill: readonly never[];
+        }>)[];
+    }>;
+    'soft-green': Readonly<{
+        locked: true;
+        guards: null;
+    }>;
+    hitl: Readonly<{
+        locked: false;
+        guards: readonly (Readonly<{
+            name: "changed-from-seed";
+            kind: "files-changed";
+            params: Readonly<{
+                requireNonEmpty: true;
+            }>;
+            compose: readonly never[];
+            fill: readonly string[];
+        }> | Readonly<{
+            name: "no-suppressions";
+            kind: "pattern-absent-in-diff";
+            params: Readonly<{}>;
+            compose: readonly string[];
+            fill: readonly never[];
+        }>)[];
+    }>;
 }>;
+/** 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: readonly string[];
 export type Red = {
     code: string;
     path: string;

package/types/authorjob.d.ts

@@ -82,13 +82,15 @@ export function refuseLockedKind(kind: string): Refusal;
  *   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,
  *   closeDecl: any, seedRef: string|null, authoring: any, reds: Red[], stop: string|null,
  *   cost: any, interview: any}>}
  */
-export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, generate, provider, seedRef, scout, listing, ceilingUsd, seedFn, scoutFn, listingFn, authorFn, authorOpts, }: {
+export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, generate, provider, seedRef, scout, listing, ceilingUsd, onPhase, onCall, seedFn, scoutFn, listingFn, authorFn, authorOpts, }: {
     answers: Record<string | number, any>;
     repoPath?: string | null;
     lang: string;
@@ -100,6 +102,12 @@ export function authorCloseForJob({ answers, repoPath, lang, verdictType, questi
     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;

package/types/authorscout.d.ts

@@ -92,13 +92,14 @@ export function defaultSurveyor({ workdir, granted, auditPath, ctx }: {
  * @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>[],
  *   calls: {label: string, costUsd: number|null, unpricedRounds: number}[],
  *   budgetStop: 'cap-halt'|'pricing-red'|null}>}
  */
-export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, maxTokens, ctx, attempts, ceilingUsd, createLoop, createSurveyor, }: {
+export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, maxTokens, ctx, attempts, ceilingUsd, onCall, createLoop, createSurveyor, }: {
     workdir: string;
     provider?: any;
     rounds?: number;
@@ -108,6 +109,11 @@ export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, m
     ctx?: boolean;
     attempts?: number;
     ceilingUsd?: number | null;
+    onCall?: (call: {
+        label: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }) => void;
     createLoop?: (o: {
         system: string;
         policy: any;

package/types/clock.d.ts

@@ -53,8 +53,11 @@ export function isWallTimeout(err: any, clock: Clock): boolean;
  *   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, closeStages, now, priorElapsedMs }?: {