bareloop 0.11.0 → 0.12.0

package/src/reviewdoor.js

@@ -0,0 +1,246 @@
+// THE REVIEW DOOR — the signer's three doors at the END of a run (softgreen
+// module 8; PRD v1.71 §3, design record 2026-08-17 §3 + the 2026-08-18 addenda).
+//
+// THE LAW, hamr verbatim: *"it's important not to change the loop self verdict."*
+// The close mints the verdict and the ledger records it before anything here runs.
+// What a door records is a DISPOSITION — what the person wants done about a
+// verdict, never what the verdict is. Nothing in this file returns, writes or
+// implies an outcome, and the run it answers has already ended.
+//
+// WHY THIS IS NOT `runPlan`'s job. A door opens after the run is over: a person
+// may answer minutes or days later, from a different process, and the answer
+// cannot ride the run's own return path (module 6 named this when it left
+// `applyDoorDecision` exported and unwired). So the door is OPENED by the run
+// (one record on its spine, `src/planrun.js`) and ANSWERED here, off that record.
+//
+// THE THREE DOORS, and what each one costs:
+//   accept — the close's MECHANICAL stages re-run against the tree as it stands
+//            (hamr's N4 ruling: an accept is not a rubber stamp), and only then is
+//            the disposition recorded and — for a held judged green — the learning
+//            credit released. A red at re-run means the tree changed under the
+//            signer: the accept is REFUSED with the stage named. Never the judged
+//            or human stages: a machine may re-prove a machine's reading, and a
+//            judgment is not re-run behind the person who rendered it.
+//   rerun  — a fresh engagement (§3.4). The person's words ARE the gap; empty
+//            words are refused at the same seam every other door is refused at.
+//            It re-proves nothing here — the NEW run's close is what judges.
+//   pause  — not now. Nothing runs, nothing is spent, and the same three doors are
+//            open the next time somebody looks. An unanswered door expires under
+//            the existing 60-day checkpoint TTL, and that expiry IS what `cancel`
+//            used to do (doors addendum, 2026-08-18).
+//
+// The registry half is module 6's (`applyDoorDecision`), called from exactly one
+// place here so a disposition cannot be recorded twice or by two spellings.
+
+import { REVIEW_DOOR, HUMAN_DECISIONS, mechanicalStages, normalizeHumanRuling } from './kinds.js';
+import { closeStagesOf } from './plan.js';
+import { isDeclaredClose, runDeclaredStages, HITL_DECISION_RED } from './declaredclose.js';
+import { runStages } from './ralph.js';
+import { redactSecrets } from './validate.js';
+import { applyDoorDecision, PAUSE_TTL_MS } from './reuse.js';
+
+/** the door's own record, off the run's spine — the LAST one, because a run that
+ * ends at a door writes exactly one and a reader that guesses which is which is a
+ * reader that will one day answer the wrong question.
+ * @param {any[]} events the run's spine, parsed
+ * @returns {any|null} */
+export function doorRecordOf(events) {
+  if (!Array.isArray(events)) return null;
+  return events.findLast?.((e) => e?.type === REVIEW_DOOR) ?? null;
+}
+
+/**
+ * IS THE DOOR STILL OPEN? The same 60-day TTL a hitl checkpoint keeps
+ * (`PAUSE_TTL_MS`) and deliberately the same NUMBER — the door replaced `cancel`
+ * precisely because an unanswered door and an unresumed pause are one state, and
+ * two TTLs for one state is how they come to disagree.
+ *
+ * An UNREADABLE stamp refuses too: unknown is not young (F6). Reading the age is
+ * not the same as deciding on it, so this states both the answer and the arithmetic.
+ * @param {any} door the door record
+ * @param {{now?: () => number, ttlMs?: number}} [opts]
+ * @returns {{ok: boolean, ageMs: number|null, ttlMs: number, detail: string}}
+ */
+export function doorAgeGate(door, { now = Date.now, ttlMs = PAUSE_TTL_MS } = {}) {
+  const days = (/** @type {number} */ ms) => (ms / 86_400_000).toFixed(1);
+  const at = typeof door?.ts === 'string' ? Date.parse(door.ts) : NaN;
+  if (!Number.isFinite(at)) {
+    return { ok: false, ageMs: null, ttlMs, detail: 'the door carries no readable timestamp, and an unknown age is not a young one — the decision cannot be honoured on a record nobody can date' };
+  }
+  const ageMs = now() - at;
+  if (ageMs > ttlMs) {
+    return { ok: false, ageMs, ttlMs, detail: `the door was opened ${days(ageMs)} days ago and a door keeps for ${days(ttlMs)} days — it has expired on its own, which is exactly what nobody having to decide looks like` };
+  }
+  return { ok: true, ageMs, ttlMs, detail: `${days(ageMs)} days old, of ${days(ttlMs)}` };
+}
+
+/** one red, one spelling @param {string} code @param {string} detail @param {string} [path] */
+const red = (code, detail, path = 'decision') => [{ code, path, detail }];
+
+/**
+ * Answer a run's review door.
+ *
+ * Never throws and never conjures: a malformed decision, a run that opened no
+ * door, an expired one, a tree that moved and a registry that is not there all
+ * come back as named reds. The loop's verdict is untouched on every path — this
+ * function has no way to write one.
+ *
+ * @param {object} opts
+ * @param {any} opts.job the SIGNED spec the run was judged by (its close is what an accept re-proves)
+ * @param {string} opts.workdir the patient, as it stands NOW
+ * @param {any[]} opts.events the run's own spine, parsed
+ * @param {string} opts.decision one of the three doors
+ * @param {string|null} [opts.text] the rerun's words — the gap, and refused when empty
+ * @param {number} [opts.closeTimeoutMs] the per-stage bound for the accept's re-run
+ * @param {string|null} [opts.registryDir] the workflow registry, when the runner keeps one
+ * @param {string|null} [opts.name] the workflow this run wrote its row against
+ * @param {string|null} [opts.runid] the RUN's id, exactly as the bridge row records it
+ * @param {string|null} [opts.at] when the person answered
+ * @param {() => number} [opts.now] the clock, injected for the TTL
+ * @param {number} [opts.ttlMs]
+ * @param {((type: string, data: any) => any)|null} [opts.emit] the run's spine, to record the disposition on
+ * @returns {Promise<{ok: boolean, decision: string|null, next: string|null, released: boolean,
+ *   doorRecorded: boolean, reds: any[], mechanical: any, door: any, text: string|null,
+ *   options: string[], ttlMs: number, note: string|null}>}
+ */
+export async function answerReviewDoor({
+  job, workdir, events, decision, text = null, closeTimeoutMs,
+  registryDir = null, name = null, runid = null, at = null,
+  now = Date.now, ttlMs = PAUSE_TTL_MS, emit = null,
+}) {
+  /** @type {any} */
+  const out = {
+    ok: false, decision: null, next: null, released: false, doorRecorded: false,
+    reds: [], mechanical: null, door: null, text: null, options: [...HUMAN_DECISIONS], ttlMs, note: null,
+  };
+
+  // ── 1. THE OPERATOR'S OWN INPUT, at the LIBRARY's one seam. A fourth door and
+  // an empty rerun are refused by `normalizeHumanRuling` — the same rulebook the
+  // close's human stage is answered through, so a surface cannot admit what a run
+  // refuses.
+  const norm = normalizeHumanRuling({ decision, ...(text === null ? {} : { text }) });
+  if (!norm.ok) {
+    out.reds = red(HITL_DECISION_RED, /** @type {string} */ (norm.why));
+    return out;
+  }
+  const ruling = /** @type {{decision: string, text: string|null}} */ (norm.ruling);
+  out.decision = ruling.decision;
+  out.text = ruling.text;
+
+  // ── 2. IS THERE A DOOR? A run that opened none has nothing to answer, and
+  // conjuring one would let a decision be recorded against a verdict nobody was
+  // ever shown the evidence for.
+  const door = doorRecordOf(events);
+  if (door === null) {
+    out.reds = red('no-door', 'this run opened no review door — its verdict stands on its own, and there is nothing here to dispose of (a green-class run opens one only when the runner asks: --review-door)', 'events');
+    return out;
+  }
+  out.door = door;
+
+  // ── 3. IS IT STILL OPEN? The TTL is the cancel case: nobody has to decide, and
+  // a door nobody answered simply expires.
+  const age = doorAgeGate(door, { now, ttlMs });
+  if (!age.ok) {
+    out.reds = red('door-expired', age.detail, 'door.ts');
+    return out;
+  }
+
+  // ── 4. ACCEPT RE-PROVES THE TREE. Everything above is $0 and deterministic;
+  // this is the only branch that runs anything, and it runs the close's own
+  // mechanical stages — never a second, weaker spelling of "is it still green".
+  if (out.decision === 'accept') {
+    const proof = await proveMechanically({ job, workdir, events, closeTimeoutMs });
+    out.mechanical = proof.reading;
+    if (!proof.ok) {
+      out.reds = red('door-accept-red', proof.detail, proof.reading.stage ? `stage.${proof.reading.stage}` : 'close');
+      // NOTHING IS RECORDED on a refusal. A disposition the machine would not
+      // honour is not a disposition the record should carry: the person's answer
+      // was about a tree that no longer exists.
+      if (emit) emit('door-decision', { decision: 'accept', honoured: false, stage: proof.reading.stage ?? null, reason: 'the tree moved under the signer' });
+      return out;
+    }
+  }
+
+  // ── 5. THE DISPOSITION IS RECORDED, and only accept releases (module 6's
+  // `recordDoor`, reached through its one on-disk seam). Every door is a datum:
+  // *"the signer's accepts double as the judge's ongoing report card"* (v1.71 §3),
+  // and a rerun over a judged green is exactly as informative as an accept.
+  if (registryDir && name && runid) {
+    // ALREADY-GREEN MINTS NOTHING, from the other side: a run that changed
+    // nothing wrote no row of its own, so there is nothing to record a door on and
+    // nothing to release. Stated rather than surfaced as a `no-row-for-run` red —
+    // the rule is the design, not a failure.
+    if (door.outcome === 'already-green') {
+      out.note = 'already-green: the run minted no row of its own, so the door records nothing and releases nothing — accept confirms a verdict, it never mints one';
+    } else {
+      const r = applyDoorDecision({ registryDir, name, runid, decision: out.decision, at });
+      if (!r.ok) {
+        out.reds = r.reds;
+        return out;
+      }
+      out.released = r.released;
+      out.doorRecorded = true;
+    }
+  }
+
+  out.ok = true;
+  out.next = out.decision === 'accept' ? 'accepted' : (out.decision === 'rerun' ? 'rerun' : 'paused');
+  if (emit) {
+    emit('door-decision', {
+      decision: out.decision,
+      honoured: true,
+      ...(out.text === null ? {} : { text: redactSecrets(out.text) }),
+      released: out.released,
+      recorded: out.doorRecorded,
+      meaning: 'a disposition — the verdict this run minted is untouched, and nothing here can change it',
+    });
+  }
+  return out;
+}
+
+/**
+ * The accept's re-proof: the close's MECHANICAL stages, run against the tree as it
+ * stands now, through the SAME executors the run itself was judged by.
+ *
+ * The declared path measures against the run's OWN seed (`close-decl.seedRef` off
+ * the spine), never a fresh one: re-basing the baseline onto today's HEAD would
+ * compare the tree to itself and turn "nothing has changed since the run" into a
+ * green for a `files-changed` stage that means the opposite. A run whose seed is
+ * not on its spine is refused rather than guessed at.
+ * @param {{job: any, workdir: string, events: any[], closeTimeoutMs?: number}} o
+ */
+async function proveMechanically({ job, workdir, events, closeTimeoutMs }) {
+  const stages = mechanicalStages(closeStagesOf(job) ?? []);
+  if (!stages.length) {
+    // Honest, and named: a close with no mechanical stage has nothing a machine
+    // can re-prove, so the accept rests on the person alone. Never a silent pass
+    // dressed as a re-run.
+    return { ok: true, detail: '', reading: { ran: 0, verdict: null, stage: null, stages: [], note: 'this close has no mechanical stage — there is nothing a machine can re-prove, so the accept rests on the person' } };
+  }
+  /** @type {any} */
+  let v;
+  if (isDeclaredClose(job)) {
+    const seedRef = events.findLast?.((e) => e?.type === 'close-decl' && typeof e.seedRef === 'string')?.seedRef ?? null;
+    if (!seedRef) {
+      return { ok: false, detail: 'this run left no seed on its spine (`close-decl.seedRef`), and a declared close measures against a seed — re-proving against a guessed baseline would grade a tree nobody chose', reading: { ran: 0, verdict: null, stage: null, stages: [] } };
+    }
+    v = await runDeclaredStages(stages, redactSecrets, { timeoutMs: closeTimeoutMs, cwd: workdir, seedRef });
+  } else {
+    v = await runStages(stages, redactSecrets, { timeoutMs: closeTimeoutMs, cwd: workdir });
+  }
+  const reading = {
+    ran: stages.length,
+    verdict: v.verdict ?? null,
+    stage: v.stage ?? null,
+    stages: v.stages ?? [],
+    ...(v.gap ? { gap: v.gap } : {}),
+  };
+  if (v.verdict === 'satisfied') return { ok: true, detail: '', reading };
+  return {
+    ok: false,
+    reading,
+    detail: `the close's mechanical stage "${v.stage ?? 'unknown'}" no longer passes on this tree (${v.verdict}) — `
+      + 'the tree moved under you, so the accept is refused rather than applied to work you did not read. '
+      + `${redactSecrets(String(v.gap ?? v.detail ?? '')).split('\n').slice(0, 3).join(' ')}`.trim(),
+  };
+}

package/src/run.js

@@ -15,10 +15,26 @@ import { join } from 'node:path';
 import { LiteCtx } from 'litectx';
 import { validateJob, jobSpecHash, checkApproval } from './job.js';
 import { runPlan } from './planrun.js';
-import { SMOKE_STORE } from './kinds.js';
+import { SMOKE_STORE, resolveHumanRuling } from './kinds.js';
 
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 
+/**
+ * THE ROUND RECORDS THE ONE LEDGER SUMS — as data, because two of them now exist
+ * and a hand-spelled condition per record is how a paid call comes to be free.
+ *
+ * `worker-round` is the attempt's own spend, metered per ROUND rather than per
+ * attempt-return (F12: a halted attempt's spend was invisible by 300×).
+ * `judge-round` is the CLOSE's, and it is the first spend a close has ever had:
+ * the judged floor (softgreen) buys a pinned locate call per artifact, and the
+ * budget-identity rule is that a budget funds the attempt PLUS its close. Both
+ * carry the honest `costUsd` — a null lands as `unpriced` and halts, never as $0.
+ *
+ * What is deliberately NOT here: `worker-result` / `worker-plan`, which are
+ * attempt TOTALS of the same rounds and would double-count.
+ */
+export const ACCOUNTED_ROUND_TYPES = Object.freeze(['worker-round', 'judge-round']);
+
 
 /**
  * Known-answer smoke on the primitive the run is about to trust (PRD v1.5 §4,
@@ -77,6 +93,13 @@ async function primitiveSmoke(workdir) {
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
+ * @param {any} [opts.judgeProvider] SOFTGREEN — the provider a JUDGED close stage runs its
+ *   locate call through, wired by the operator and PINNED to `JUDGE_MODEL` (src/judged.js:
+ *   the only tier with established injection resistance upstream). Forwarded to the plan
+ *   flow. It is its own seam and not `provider`/`providerFor`, because the judge tier is
+ *   never a step knob and never agent-selectable; absent, a judged stage instrument-stops as
+ *   a wiring gap rather than grading on whatever binding happened to be at hand. Its spend
+ *   lands on this ledger as `judge-round` (see `ACCOUNTED_ROUND_TYPES`).
  * @param {number} [opts.capRuns] shell-owned iteration cap for the plan flow's
  *   CLOSE-FIX loop (a plan STEP runs under the strike ladder instead)
  * @param {number} [opts.strikeLimit] shell-owned strike ceiling for a plan step's ladder
@@ -145,13 +168,26 @@ async function primitiveSmoke(workdir) {
  *   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).
+ * @param {{decision: string, text?: string|null, receivedAt?: string|null}|null} [opts.heldRuling]
+ *   F102 — the answer the CHECKPOINT holds (`readResume`'s `restart.pendingDecision`):
+ *   a decision a person already gave on a leg that stopped before a single round was
+ *   bought for it. Forwarded verbatim; the plan flow applies it exactly as a fresh one
+ *   and refuses a leg handed both. It is also what decides whether the TIME fold this
+ *   run declares is the chain's or this engagement's (F103).
+ * @param {boolean|null} [opts.reviewDoor] MODULE 8 — does this run END at the review
+ *   door (PRD v1.71 §3)? Forwarded verbatim to the plan flow, which owns the class
+ *   default. It changes what the run RECORDS and never what it returns: the door is a
+ *   disposition and the loop's verdict is not the door's to touch.
+ * @param {{text: string, fromRunid?: string|null, receivedAt?: string|null}|null} [opts.doorRerun]
+ *   MODULE 8 — this leg IS the fresh engagement a signer commissioned at a previous
+ *   run's review door, carrying their words. Forwarded verbatim.
  * @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' |
  *   '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, humanRuling = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, 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, heldRuling = null, reviewDoor = null, doorRerun = 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
@@ -162,6 +198,11 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // number that enters the arbiter's arithmetic: a garbage fold is 0, never a NaN
   // that would poison every later comparison into "no cap".
   let spentUsd = typeof priorSpentUsd === 'number' && Number.isFinite(priorSpentUsd) && priorSpentUsd > 0 ? priorSpentUsd : 0;
+  /** F103's money half — the CHAIN's fold, kept as its own figure so `spentUsd`
+   * (the chain total, what a person reads and what the ceiling governs) and THIS
+   * ENGAGEMENT's spend can be stated side by side on every terminal. Two things
+   * counted by one number will eventually be asked to disagree. */
+  const chainFoldUsd = spentUsd;
   let unpriced = false;
   // RESUME (v1.46 §3): was the FOLD itself exact? `readResume` marks it false when any
   // round inside the dead attempt came back unpriced, and that unknown does not heal by
@@ -201,7 +242,16 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // ONE spelling of the four causes, so the terminal and the in-flight money readout can
   // never disagree about whether the same run's figure is exact.
   const spendComplete = () => !unpriced && !stalled && !cutMidCall && !priorFloor;
-  const spend = () => ({ spentUsd, spendComplete: spendComplete() });
+  const spend = () => ({
+    spentUsd,
+    spendComplete: spendComplete(),
+    // F103's second counter, on every terminal beside the chain total it is NOT.
+    // `spentUsd` is cumulative-so-far (this job, across engagements) and governs the
+    // ceiling; this is what THIS engagement spent. Always emitted, never conditional
+    // on there being a fold: a consumer that has to branch on field presence is a
+    // consumer that will read absence as zero.
+    engagementSpentUsd: Math.max(0, spentUsd - chainFoldUsd),
+  });
   // 1. human-signs-always — before ANY provider call (N1 decision #1)
   if (!checkApproval(rawSpec, approvals)) {
     emit('job-end', { outcome: 'unapproved-spec', detail: 'no approval record matches this exact spec version', ...spend() });
@@ -214,6 +264,11 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
     return 'job-red';
   }
   const job = /** @type {any} */ (jv.job);
+  /** F103 — the two TIME figures, resolved once here and read the same way by
+   * `runPlan`'s clock. An unreadable ruling resolves to `fresh: false` and folds as
+   * it always did; `runPlan` is where it is refused, so this never has to. */
+  const chainWallMs = typeof priorWallMs === 'number' && Number.isFinite(priorWallMs) && priorWallMs > 0 ? priorWallMs : 0;
+  const wallFold = resolveHumanRuling(humanRuling, heldRuling, doorRerun).fresh ? 0 : chainWallMs;
   emit('job-start', {
     job: job.job, specHash: jobSpecHash(job), budgetUsd: job.budgetUsd,
     shape: 'plan', goal: job.goal,
@@ -226,7 +281,17 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
     // A fold of $0 that is NOT exact is still a fold — the unknown is the whole of what
     // it inherited, and it is the only field that can carry it forward.
     ...(spentUsd > 0 || priorFloor ? { priorSpentUsd: spentUsd, priorSpendComplete: !priorFloor } : {}),
-    ...(typeof priorWallMs === 'number' && Number.isFinite(priorWallMs) && priorWallMs > 0 ? { priorWallMs } : {}),
+    // …and the TIME fold, which F103 splits in two. `priorWallMs` is what the next
+    // reader ADDS to (the bound), and it is engagement-scoped: a rerun opens a fresh
+    // engagement, so the minutes the person did not commission are not a bound on
+    // anybody. `chainWallMs` is the cumulative view and is declared whenever there is
+    // one, so nothing is lost — the readout keeps spanning the chain (the halt readout
+    // and the leg's own governor answer different questions and are never mixed).
+    // The `fresh` reading comes from the ONE resolver `runPlan`'s clock reads, never a
+    // second spelling of "is this a rerun" (that is how a record and a clock come to
+    // disagree about the same leg).
+    ...(wallFold > 0 ? { priorWallMs: wallFold } : {}),
+    ...(chainWallMs > 0 && chainWallMs !== wallFold ? { chainWallMs } : {}),
     // the REPLAN ledger, on the same declaration and for the same reason — a chain of
     // resumes must fold once. This is the DIRECT-spine half of it: `readResume`'s
     // `direct` mode opens its one implicit window on `job-start` and reads the fold off
@@ -265,7 +330,9 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
     // `account` reds the run on ANY unpriced round (a null cost is the honest
     // unknown, never $0 — F6): per-round metering means a partially-unpriced run
     // is caught natively, round by round, with no separate unpricedRounds tally.
-    if (type === 'worker-round') account(/** @type {any} */ (data)?.costUsd);
+    // …and the CLOSE's own rounds sum into the same wallet the moment a close can
+    // spend at all (the judged floor): one ledger, never a second arithmetic.
+    if (ACCOUNTED_ROUND_TYPES.includes(type)) account(/** @type {any} */ (data)?.costUsd);
     // W1: a `stall` is the plan flow announcing it ABANDONED a call and reissued
     // it. The abandoned call's spend is unknowable from here (billed or not,
     // indistinguishable), so from this point the priced sum is a floor no matter
@@ -289,7 +356,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, humanRuling,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
       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

@@ -26,7 +26,7 @@
 // in either direction, a percentage over 2–3 runs is fake precision, and if a score ever
 // earns its way in its threshold is hamr's, from a measured base rate.
 
-import { listingRow } from './bridges.js';
+import { listingRow, QUARANTINED_CODE } from './bridges.js';
 
 /** minutes, one decimal — the granularity a human picks a workflow at (the unit is
  * written once, by the band) */
@@ -74,10 +74,22 @@ export function renderListing(registry) {
   const reds = Array.isArray(r?.reds) ? r.reds : [];
   const rows = bridges.map(listingRow).sort((a, b) => String(a.name).localeCompare(String(b.name)));
 
-  const skipped = reds.length
-    ? [`\n\nNOTE: ${reds.length} registry entr${reds.length === 1 ? 'y' : 'ies'} could not be read and ${reds.length === 1 ? 'is' : 'are'} NOT listed — this listing is smaller than the directory:`,
-      ...reds.map((/** @type {any} */ x) => `  ${x.path ?? '(unknown file)'}${x.detail ? ` — ${x.detail}` : ''}`)].join('\n')
-    : '';
+  // TWO KINDS OF SKIP, and they are never written as one. An unreadable entry is a
+  // broken file; a HELD one (softgreen module 6) is a perfectly good workflow whose
+  // judged green no signer has accepted yet. Saying "could not be read" about the
+  // second would send the operator to fix a file that is not broken.
+  const broken = reds.filter((/** @type {any} */ x) => x?.code !== QUARANTINED_CODE);
+  const held = reds.filter((/** @type {any} */ x) => x?.code === QUARANTINED_CODE);
+  const skipped = [
+    broken.length
+      ? [`\n\nNOTE: ${broken.length} registry entr${broken.length === 1 ? 'y' : 'ies'} could not be read and ${broken.length === 1 ? 'is' : 'are'} NOT listed — this listing is smaller than the directory:`,
+        ...broken.map((/** @type {any} */ x) => `  ${x.path ?? '(unknown file)'}${x.detail ? ` — ${x.detail}` : ''}`)].join('\n')
+      : '',
+    held.length
+      ? [`\n\nNOTE: ${held.length} workflow${held.length === 1 ? ' is' : 's are'} HELD and NOT offered — a judged green earns no reuse until the person who owns the job accepts it:`,
+        ...held.map((/** @type {any} */ x) => `  ${x.path ?? '(unnamed)'}${x.detail ? ` — ${x.detail}` : ''}`)].join('\n')
+      : '',
+  ].join('');
 
   if (!rows.length) {
     return `WORKFLOWS ON RECORD — none.\nThere are no workflows to reuse; a plan has to be drafted from scratch.${skipped}`;
@@ -86,7 +98,11 @@ export function renderListing(registry) {
   const blocks = rows.map((row) => {
     const g = row.greenCost;
     return [
-      `[${row.name ?? '(unnamed)'}]  ${(row.status ?? 'no-green').toUpperCase()}`,
+      // an entry whose only greens are HELD has no status — but "NO-GREEN" would be
+      // false about it: it greened, and a person has simply not accepted the judged
+      // verdict yet. The distinct word is the whole difference between "this never
+      // worked" and "this is waiting on you".
+      `[${row.name ?? '(unnamed)'}]  ${(row.status ?? (row.quarantinedGreens > 0 ? 'held' : 'no-green')).toUpperCase()}`,
       `  goal   ${row.goal ?? '(no goal recorded)'}`,
       `  runs   ${row.greens} green · ${row.reds} red${row.lastOutcome ? `  (last: ${row.lastOutcome})` : ''}`,
       `  green  cost ${band(g.minUsd, g.maxUsd, usd, g.unpricedCount, row.greens, 'unpriced')}`

package/types/authorflow.d.ts

@@ -32,12 +32,21 @@ export function schemaCoverage(catalogue?: Record<string, any>): {
  * and they arrive as validation reds through the revise loop — a schema that
  * tried to restate them would be a second validator.
  *
+ * `verdictType` narrows the branches to the kinds the picked class may express
+ * (softgreen module 3, `classMenu`): a green job cannot SPELL `judged-floor`,
+ * rather than spelling it and being told afterwards. COVERAGE is still computed
+ * over the WHOLE catalogue — the class filter must never make a parameter look
+ * orphaned and turn a menu narrowing into a catalogue-drift alarm.
+ *
  * THROWS on a catalogue it cannot cover: a malformed catalogue is a bareloop bug,
  * and failing loudly beats emitting a schema that quietly cannot say something
  * the validator will then demand.
  * @param {Record<string, any>} [catalogue]
+ * @param {{verdictType?: string|null}} [o]
  */
-export function declarationSchema(catalogue?: Record<string, any>): {
+export function declarationSchema(catalogue?: Record<string, any>, { verdictType }?: {
+    verdictType?: string | null;
+}): {
     type: string;
     properties: {
         stages: {
@@ -86,12 +95,13 @@ export function declarationSchema(catalogue?: Record<string, any>): {
  * The output channel. It records and acknowledges; it takes no action, which is
  * why handing it to a toolless authoring call does not reopen D3.
  * @param {{calls: any[]}} box
- * @param {{catalogue?: Record<string, any>}} [o]
+ * @param {{catalogue?: Record<string, any>, verdictType?: string|null}} [o]
  */
 export function declarationTool(box: {
     calls: any[];
-}, { catalogue }?: {
+}, { catalogue, verdictType }?: {
     catalogue?: Record<string, any>;
+    verdictType?: string | null;
 }): {
     name: string;
     description: string;
@@ -146,9 +156,19 @@ export function declarationTool(box: {
  * The catalogue, as the authoring call sees it — rendered FROM the catalogue, so
  * the prompt and the validator judge one set of facts. `shape` and `asserts` are
  * M2's own strings.
+ *
+ * `verdictType` narrows it to the picked class's menu, exactly as it narrows the
+ * schema — the prompt and the tool must offer ONE set of kinds, or the composer
+ * reads about a kind it cannot call. A kind above the ceiling is omitted rather
+ * than rendered as unavailable: a LOCKED row says "this does not run in v1",
+ * which is a fact about the build; "not for your class" is a fact about a choice
+ * the person already made, and printing it invites the composer to argue with it.
  * @param {Record<string, any>} [catalogue]
+ * @param {{verdictType?: string|null}} [o]
  */
-export function catalogueBlock(catalogue?: Record<string, any>): string;
+export function catalogueBlock(catalogue?: Record<string, any>, { verdictType }?: {
+    verdictType?: string | null;
+}): string;
 /**
  * HOW THE GENRE'S OWN TOOLS PRINT — rendered FROM `genreInstruments`, so the
  * pattern the author is handed and the pattern the tree already grades with are
@@ -433,6 +453,48 @@ export function makeLoopGenerate(provider: any, { system, maxTokens }?: {
     system?: string;
     maxTokens?: number;
 }): (messages: any[], tools: any[], opts?: any) => Promise<any>;
+/**
+ * ONE structured ask, with the malformed-emission retry bounded on its OWN axis.
+ * A reply that carries no artifact is an ARTIFACT-RED — name the axis, retry
+ * under a cap, write nothing — and it never consumes a revision, because a
+ * transport fault is not a defect in a close.
+ *
+ * THE CHANNEL IS A PARAMETER, and that is softgreen module 4's only change here:
+ * the rubric card and the calibration set are a SECOND schema-forced emission
+ * with the same failure modes, and a second ladder is a second place for the cap,
+ * the reject block and the re-ask to drift. The declaration channel below is the
+ * one this loop has always used, spelled out rather than inlined — nothing about
+ * the authoring path's behaviour moves.
+ * @param {{messages: any[], generate: Function, mode: 'tool'|'text', retries: number,
+ *   label: string, book: ReturnType<typeof makeCostBook>,
+ *   channel: {name: string, instruction: string, textPath?: string, tool: (box: {calls: any[]}) => any}}} o
+ * @returns {Promise<{artifact: any, attempts: number, convo: any[], raw: string,
+ *   providerError: string|null, red: Red|null, budget: 'cap-halt'|'pricing-red'|null}>}
+ */
+export function askStructured({ messages, generate, mode, retries, label, book, channel }: {
+    messages: any[];
+    generate: Function;
+    mode: "tool" | "text";
+    retries: number;
+    label: string;
+    book: ReturnType<typeof makeCostBook>;
+    channel: {
+        name: string;
+        instruction: string;
+        textPath?: string;
+        tool: (box: {
+            calls: any[];
+        }) => any;
+    };
+}): Promise<{
+    artifact: any;
+    attempts: number;
+    convo: any[];
+    raw: string;
+    providerError: string | null;
+    red: Red | null;
+    budget: "cap-halt" | "pricing-red" | null;
+}>;
 /**
  * THE AUTHORING FLOW.
  *
@@ -615,11 +677,50 @@ export const HITL_QUESTIONS: Readonly<{
     5: "What would make you say this came back worse than before?";
 }>;
 /**
- * The three sets. `questions: null` on a locked class is ABSENT, never `{}`:
- * an empty set would read as "this class needs no questions", which is a
- * different and false statement (F59's distinction, at the interview layer).
- * Nothing ever reads them — a locked class refuses at ADMISSION, before its
- * questions run — and the two readers below throw rather than hand back nothing.
+ * THE SOFTGREEN SET (module 3, design record §4.6) — the green questions BYTE
+ * FOR BYTE, plus TWO.
+ *
+ * Same discipline as the hitl set, and for the same reason: a softgreen close is
+ * *mechanical stages first, the judged stage after* (§4.5), so a softgreen job
+ * needs every mechanical fact a green one does. No renumbering of the green set,
+ * no genre question, nothing reworded.
+ *
+ * The two additions are the only things the green set cannot supply, and neither
+ * is a flourish — they are the judged floor's two REQUIRED inputs:
+ *   - Q6 becomes the RUBRIC CARD (§4.3): the person's own pass/fail lines,
+ *     compiled into enumerated items, signed, and enumerated in the spec hash.
+ *     The documented ceiling rides with it — the judge catches violations of
+ *     STATED card items only, and the fix for a miss is a new card line and a
+ *     re-sign, never a smarter judge.
+ *   - Q7 becomes the frozen CALIBRATION SET (§4.4): the whole pipe must grade it
+ *     correctly before the close is signable.
+ * Both are asked in the person's own terms — an example they would pass and one
+ * they would fail, not a rubric they are asked to write — because compiling a lay
+ * answer into extractable items is the LLM's job (D5, proposed-and-signed) and
+ * asking the person to do it is the SWE tax this product refuses.
+ *
+ * What the two answers COMPILE INTO is module 4. This module carries them
+ * exactly as the hitl set carries its own last answer: they ride in `answers`,
+ * they reach the composer verbatim through the prompt's interview block, and
+ * nothing here derives anything from them.
+ */
+export const SOFTGREEN_QUESTIONS: Readonly<{
+    6: "When you judge the result yourself, what separates a pass from a fail? Name the few things you actually look for.";
+    7: "Give one example you'd pass and one you'd fail, and say why.";
+    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?";
+}>;
+/**
+ * The three sets, all LIVE as of softgreen module 3. The locked shape stays
+ * spelled out in the readers below rather than deleted with the last locked
+ * class: `questions: null` is ABSENT, never `{}` — an empty set would read as
+ * "this class needs no questions", a different and false statement (F59's
+ * distinction, at the interview layer) — and a locked class refuses at ADMISSION,
+ * before its questions run, so the two readers throw rather than hand back
+ * nothing. A fourth class arrives locked, and the machinery is here for it.
  * @type {Record<string, {locked: boolean, questions: Record<string|number, string>|null, required: readonly number[]|null}>}
  */
 export const QUESTION_SETS: Record<string, {
@@ -823,6 +924,43 @@ export const PARAM_SCHEMAS: Readonly<{
     requireNonEmpty: {
         const: boolean;
     };
+    card: {
+        type: string;
+        description: string;
+        properties: {
+            items: {
+                type: string;
+                minItems: number;
+                items: {
+                    type: string;
+                    properties: {
+                        rule: {
+                            enum: string[];
+                            description: string;
+                        };
+                        text: {
+                            type: string;
+                            minLength: number;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                };
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    paths: {
+        type: string;
+        minItems: number;
+        maxItems: number;
+        items: {
+            type: string;
+        };
+        description: string;
+    };
     ask: {
         type: string;
         minLength: number;