bareloop 0.8.0 → 0.10.0

package/src/planrun.js

@@ -20,7 +20,7 @@ import { join, resolve, relative } from 'node:path';
 import { Gate } from 'bareguard';
 import { LiteCtx } from 'litectx';
 import { runClose, runStages, ralph, CLOSE_FAULTS, boundGap } from './ralph.js';
-import { validatePlan, legalScopes, stageClose } from './plan.js';
+import { validatePlan, legalScopes, closeStagesOf } from './plan.js';
 import { WRITE_VERBS, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, MAX_SCOPE_MENU } from './plan.js';
 import { snapshotScope, evalExits, CHECK_GAP_MAX } from './exits.js';
 import { createRoot } from './root.js';
@@ -33,6 +33,9 @@ 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 { workBranchName, prepareWorkBranch } from './workbranch.js';
 
 const require = createRequire(import.meta.url);
 const { Loop, wireGate, HaltError } = require('bare-agent');
@@ -257,6 +260,60 @@ export function closeGapBlock(gap) {
     + (scrubbed.length > CHECK_GAP_MAX ? boundGap(scrubbed, REPLAN_GAP_KEEP) : scrubbed);
 }
 
+/**
+ * The recorded bound-reason's ceiling in the WORKER-facing note. The reason is a
+ * provider string (`denied:<tool>` today, ~20 bytes), not a gap, so this is a
+ * backstop against a future terminal that arrives long — never an envelope the
+ * shipped path routinely rides through.
+ */
+export const BOUND_REASON_MAX = 200;
+
+/**
+ * What the NEXT attempt is told about the bound that cut the previous one.
+ *
+ * Two different bounds used to set the same bare `attemptBounded = roundIteration`
+ * and therefore render the same sentence. For a round-bound cutoff that sentence is
+ * true. For BA-11's deny streak it is false twice over — the rounds did NOT run out
+ * (the fence short-circuited the attempt with budget left), and the count it quotes
+ * is the cap, not what was spent — and it aims the worker at the READ BUDGET when the
+ * thing that stopped it was the FENCE. The reason was already recorded on the spine;
+ * nothing carried it to the one reader who could act on it.
+ *
+ * The denial note is MECHANICAL in the strict sense: it quotes the terminal the
+ * provider actually returned and names which bound fired. It invents nothing —
+ * no streak count and no denied path, because bare-agent's return (`error:
+ * 'denied:<tool>'`, loop.js) carries neither, and a number nobody measured is a
+ * bug with a confident voice. Every other cause keeps the frozen wording byte for
+ * byte: a wall-bounded attempt reads as a round bound exactly as it did before
+ * (and is unreachable anyway — the step head refuses to fund an attempt past the
+ * deadline, W-2), so this change can only ever speak where it has something true
+ * to add.
+ *
+ * The reason arrives ALREADY SCRUBBED (the capture seam in `mkWorker` runs it
+ * through the one `SECRET_PATTERNS` inventory), so this renderer only bounds it —
+ * and announces the trim with the repo's ONE marker rather than a second spelling
+ * of "this text was cut" (F90.2).
+ *
+ * @param {{iteration?: number|string|undefined, cause: string, reason: string|null}|null|undefined} bounded
+ *   the previous attempt's bound state, or nullish when it was not bounded
+ * @param {number} rounds the step's round bound, as quoted by the frozen sentence
+ * @returns {string|null} the note, or null when there is nothing to say
+ */
+export function boundedNote(bounded, rounds) {
+  if (!bounded) return null;
+  if (bounded.cause !== 'denied') {
+    return `Your previous attempt was CUT OFF after ${rounds} tool rounds. `
+      + 'Reading is bounded; writing is not. Form a hypothesis EARLY and make the change.';
+  }
+  const raw = String(bounded.reason ?? '');
+  const shown = raw.length > BOUND_REASON_MAX
+    ? `${raw.slice(0, BOUND_REASON_MAX)} [${GAP_TRIM_MARKER} ${raw.length - BOUND_REASON_MAX} of ${raw.length} characters withheld — the cap is ${BOUND_REASON_MAX}]`
+    : raw;
+  return 'Your previous attempt was CUT OFF by the gate: it denied consecutive tool calls '
+    + `until the streak guard ended the attempt. The gate recorded: ${shown}. `
+    + 'The round budget was not what stopped you — repeating a denied call ends this attempt the same way.';
+}
+
 /**
  * The plan-drafting prompt: a schema DESCRIPTION built from the live validator
  * menus — never a copyable example (the drafter must author, not echo; the
@@ -306,7 +363,7 @@ export function planPrompt(job, scoutBlob, reds, maxStepRounds, failure, scopes,
   // executes and `validatePlan` accepts against. Reading `job.close` raw here left
   // the legacy object form offering nothing while the runner preflighted a stage.
   // (`?? []`: a close naming no command stages nothing, so it offers nothing)
-  const closeStages = stageClose(job.close) ?? [];
+  const closeStages = closeStagesOf(job) ?? [];
   const checkNames = checkMenu(closeStages).map((m) => m.name);
   const doc = `DRAFT-PLAN
 You are planning how to accomplish a goal in a repository, as an ordered list of bounded
@@ -318,7 +375,7 @@ Shape: { "schema": "plan-v1", "steps": [ ... 1..${MAX_PLAN_STEPS} steps ... ] }
 strictly in array order. Each step (no other fields exist):
 - "id": kebab-case slug, unique
 - "action": the step's task, precise enough for a worker that sees ONLY this step
-- "tools": non-empty unique subset of ${JSON.stringify(ceiling)} (write/edit change the tree; recall/get/impact/related/recent search and navigate the repository index; compress/peek read cheaply; stash/remember/forget park and record notes across steps)
+- "tools": non-empty unique subset of ${JSON.stringify(ceiling)} (read/grep are the worker's ONLY way to see the tree — there is no shell; write/edit change the tree; recall/get/impact/related/recent search and navigate the repository index; compress/peek read cheaply; stash/remember/forget park and record notes across steps)
 - "rounds": integer 1..${maxStepRounds} — the step's per-attempt tool-round bound
 - "target": the step's deliverable path (REQUIRED when tools include write/edit), inside ${JSON.stringify(job.writeScope)}
 - "scope" (optional): narrow this step's WRITE fence — copy one value from the offered scopes below.
@@ -348,6 +405,15 @@ strictly in array order. Each step (no other fields exist):
   exit reds on that file can never finish, on any attempt.${seedRedLaw}${priorChecksLaw}
   Reference checks by NAME only; you cannot author or modify one.
 
+The worker has NO SHELL. It cannot run a command, a compiler, a linter, or a test suite,
+and it cannot execute a script it writes: its only verbs are the tools you grant that step
+in "tools". The check named in a "check-passes" exit is the ONLY execution in this run —
+the shell runs it after each attempt and hands the worker its raw output. So write every
+"action" for a worker that locates its work by READING and GREPPING files and by reading
+the check output it is given. Never tell it to run, execute, re-run, or verify by running
+anything (an action that opens with "Run \`<command>\`…" costs the whole step: the worker
+has no way to obey it and spends its rounds hunting by hand).
+
 Offered "scope" values for tree-changed — copy ONE of these exactly, character for
 character. No other value is accepted, and patterns of your own (like "src/*.js")
 are not accepted:
@@ -509,12 +575,18 @@ ${scoutBlob || '(no scout notes)'}`;
  *   default; a caller supplies this to drive time deterministically (the same seam `createClock`
  *   already exposes — a run's terminal cannot otherwise be exercised without waiting out a cap
  *   whose floor is one close timeout).
+ * @param {string|null} [opts.resumeBranch] RESUME — the WORK BRANCH the killed leg
+ *   recorded on its own spine (`readResume`'s `restart.branch`, off the `work-branch`
+ *   event). With it the resume returns to the branch its own work is sitting on; without
+ *   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.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
- *   'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' | 'step-stalled' |
- *   `step-red:<id>`
+ *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
+ *   'step-stalled' | `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 }) {
+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 }) {
   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
@@ -550,14 +622,17 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
   // A STAGED close (PRD v1.28) is an ordered list of command stages and is the
   // go-forward shape; the object form survives only for the declared-but-locked
   // verdict classes (gold/rubric/hitl), which name no command to run.
-  // W4: the staging itself lives in ONE place (`stageClose`), shared with
+  // W4: the staging itself lives in ONE place (`closeStagesOf`), shared with
   // `planPrompt` and `validatePlan` — a second copy here is exactly how the
-  // runner came to execute a stage neither of the other two could see.
-  const stagedClose = stageClose(job.close);
+  // runner came to execute a stage neither of the other two could see. M4 widened
+  // that one derivation to the AUTHORED close (`closeDecl`) rather than adding a
+  // second: a consumer reading only `close` sees a declared job as closeless.
+  const stagedClose = closeStagesOf(job);
+  const declared = isDeclaredClose(job);
   if (!stagedClose) {
     emit('escalation', {
       category: 'close-unsupported', decisionReady: true,
-      decision: `The job's close is a ${job.close.type} close — the plan flow executes commands whose exit codes are truth (a staged close, or a single predicate).`,
+      decision: `The job's close is a ${job.close?.type ?? 'non-command'} close — the plan flow executes commands whose exit codes are truth (a staged close, a single predicate, or an authored declaration).`,
       options: ['restate the close as a predicate', 'wait for the verdict-classes rung'],
     });
     return 'close-unsupported';
@@ -738,6 +813,22 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
   ];
 
   const closeOpts = { timeoutMs: closeTimeoutMs, cwd: workdir };
+  /** D8 — the DECLARED close's seed, filled in below before anything runs.
+   * `null` for a command close, which has no baseline to measure against. */
+  /** @type {{seedRef: string}|null} */
+  let declaredCtx = null;
+  /**
+   * ONE close-execution seam, chosen once by which field the SIGNED spec carries.
+   * Both executors return `runClose`'s verdict shape, so everything downstream —
+   * the precheck, the preflight, the check seam, ralph's judge, `CLOSE_FAULTS`,
+   * the trend reader and Layer R — is the same code for both.
+   *
+   * The command path is byte-identical to what it was: same call, same options.
+   * @param {any[]} stages
+   */
+  const runCloseStages = (stages) => (declared
+    ? runDeclaredStages(stages, scrub, { ...closeOpts, seedRef: /** @type {any} */ (declaredCtx).seedRef })
+    : runStages(stages, scrub, closeOpts));
   /** @type {string|undefined} the stage that rendered the LAST close verdict (Layer R's red-set source) */
   let closeStage;
   /** @type {any} the LAST close verdict itself (W-2). A wall stop KEEPS the grade
@@ -795,16 +886,172 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
   };
   /** the close, as ONE verdict: every stage in order, first red wins */
   const judgeClose = async () => {
-    const v = await runStages(stagedClose, scrub, closeOpts);
+    const v = await runCloseStages(stagedClose);
     closeStage = v.stage;
     lastCloseVerdict = v;
     // Only a RED grade is a reading. A `satisfied` ends the run and a close FAULT
     // rendered no judgment at all (CLOSE_FAULTS) — folding either into the series
     // would put a non-number where the instrument expects a graded one.
-    if (v.verdict === 'needs_revision') runTrend.record({ gap: v.gap });
+    // `closeGrade` is the reader's input for EITHER executor: a command close
+    // hands over its gap and `readGrade` scrapes the stage and the count out of
+    // it; a declared close already KNOWS both and says them, rather than
+    // round-tripping a number through prose it would then have to parse back.
+    if (v.verdict === 'needs_revision') runTrend.record(closeGrade(v));
     return v;
   };
 
+  // ── 0c. THE WORK BRANCH — the HARD RULE (PRD Addendum v1.57 §3, hamr):
+  // *"The agent creates a NEW BRANCH before it touches any code — a HARD RULE, no
+  // exceptions. Not a default, not a preference: no job edits the branch it was
+  // handed, and none edits `main`."*
+  //
+  // ONE SEAM, TWO PLACEMENTS. The split is COLD vs RESUME, and every half of it is
+  // ruled rather than convenient:
+  //
+  //  * BEFORE the scout on BOTH paths, the scout being the run's first PAID call. A
+  //    patient that is not a git checkout, a namespace with no free name, a resume
+  //    whose branch a human deleted — each is an instrument stop that must cost zero
+  //    tokens, and a branch prepared after the scout would already have bought one.
+  //  * COLD: AFTER the precheck and the preflight, which are $0 and deterministic.
+  //    An ALREADY-GREEN tree returns below without ever reaching the seam and leaves
+  //    no branch behind: a run with no work to do has no blast radius to bound, and
+  //    minting a branch for it would litter every patient with the record of a run
+  //    that did nothing.
+  //  * RESUME: BEFORE them — here, above 0*. There is nothing to mint on a resume
+  //    (the recorded branch exists, `created:false`, and the arm below refuses
+  //    rather than creating), so the leave-no-branch-behind clause has nothing to
+  //    say; what IS at stake is WHICH TREE the $0 instruments measure. The recorded
+  //    branch holds the work the operator already paid for and IS the run being
+  //    continued, while the ref the operator handed back can be anything at all. Run
+  //    from where the run happens to stand, the precheck could read `already-green`
+  //    off a tree that is not this run's and every `baseline: "seed"` stage would
+  //    baseline against it — an instrument measuring the wrong subject, reading
+  //    honestly and saying nothing true. Moving the seam up is also strictly cheaper
+  //    for the failure case: a resume whose branch is gone or foreign now stops
+  //    before the arbiter grades anything at all.
+  //
+  // The scout itself needs no branch and is not what this gates: its menu simply
+  // has no write-class verb in it (the menu IS the grant), so it cannot touch code
+  // wherever it stands. What the branch gates is the WRITE-CAPABLE phase, and that
+  // gate is enforced structurally rather than by this ordering — `mkWorker` refuses
+  // to build a `writable` worker while `workBranch` is null (below). Ordering says
+  // where the honest stop happens; the guard says the rule cannot be bypassed.
+  //
+  // Creating a branch at HEAD moves no commit and changes nothing the close can
+  // measure: the declared seed is HEAD either way, and the tree — dirty or clean —
+  // is carried across untouched.
+  /** @type {string|null} the branch this run's work lands on, once it exists */
+  let workBranch = null;
+  /** is this leg continuing work that already exists? Spelled EXACTLY as
+   * `prepareWorkBranch`'s own resume test, so the two cannot disagree about which
+   * arm a given input takes. */
+  const resuming = resumeBranch !== null && resumeBranch !== undefined;
+  /**
+   * 0c itself — ONE definition for both placements. The refusal below is written
+   * once on purpose: two call sites emitting their own branch-red would be two
+   * messages free to drift apart, and this one is what a human reads when a run
+   * stops having spent nothing.
+   * @returns {Promise<'branch-red'|null>} the terminal to return, or `null` once the
+   *   run is standing on a branch nobody handed it
+   */
+  const prepareBranch = async () => {
+    const wb = await prepareWorkBranch(workdir, { name: workBranchName(job), resume: resumeBranch ?? null });
+    if (wb.stop !== null) {
+      // Never a fallback to the handed branch. That fallback IS the thing the rule
+      // forbids, and a run that silently took it would report a green whose blast
+      // radius nobody bounded — so this is a named terminal of its own rather than
+      // a wiring fault (`interpreter-red` aims an upstream ask at a library; a
+      // patient that is not a git checkout is the operator's own state speaking).
+      emit('escalation', {
+        category: 'branch-red', decisionReady: true,
+        decision: 'The run could not create its own work branch, and no job runs on the branch it was handed (PRD v1.57 §3). Nothing was spent.',
+        options: [
+          'make the patient a git checkout with at least one commit',
+          'free the work-branch name (delete or rename the stale branches this run collided with)',
+          'abandon the run',
+        ],
+        detail: scrub(wb.stop),
+      });
+      return 'branch-red';
+    }
+    workBranch = wb.branch;
+    // The run's own books say where its work went. A human reading a spine — or a
+    // resume reading it back (`readResume`'s `restart.branch`) — must not have to
+    // re-derive the name from the spec and guess how many collisions there were.
+    emit('work-branch', {
+      branch: wb.branch,
+      created: wb.created,
+      resumed: wb.resumed,
+      from: wb.from,
+      base: wb.base,
+      repo: wb.repo,
+      ...(wb.collided > 0 ? { collided: wb.collided } : {}),
+      meaning: wb.resumed
+        ? 'returned to the branch this run was killed on — its work is on this branch, and a fresh one would strand it'
+        : 'the HARD RULE (PRD v1.57 §3): the run works here, never on the branch it was handed and never on main',
+    });
+    return null;
+  };
+  if (resuming) {
+    const stop = await prepareBranch();
+    if (stop !== null) return stop;
+  }
+
+  // ── 0*. the DECLARED close's two run-start facts. Both are $0 and both sit
+  // INSIDE the clock (they are the arbiter's own instruments, and time the
+  // operator's instruments too or the budget measures a different run).
+  //
+  //  (1) THE SEED (D8/D12). HEAD at run start, READ and recorded, never typed.
+  //      The close stores the counting RULE and never the number, so every
+  //      `baseline: "seed"` stage is measured against THIS run's own starting
+  //      point — a constant frozen at signing would judge run 5 against run 1's
+  //      tree, which is the one-experiment shape D12 retires.
+  //
+  //  (2) THE GROUNDED RE-VALIDATION (D9 gate 1). The job validator judged the
+  //      declaration with no repository in hand, so hamr's listing rule and the
+  //      scoped-job derivation that arms the F84 one-population law were
+  //      DEFERRED, not skipped. They run here, against the real seed tree,
+  //      before any stage and before any token. A declaration that names a path
+  //      the tree does not have is a broken close, not a red about the worker —
+  //      round 2's arm A invented `src/alertEmail.js` and silently reclassified
+  //      15 real errors into the wrong population.
+  if (declared) {
+    const s = await seedAtHead(workdir);
+    if (s.stop !== null) {
+      emit('escalation', {
+        category: CLOSE_FAULTS.failed.category, decisionReady: true,
+        decision: `The authored close measures against this run's own seed, and the seed could not be read. ${CLOSE_FAULTS.failed.decision}`,
+        options: ['check the repository is a git checkout with at least one commit', ...CLOSE_FAULTS.failed.options],
+        detail: scrub(s.stop),
+      });
+      return 'close-red';
+    }
+    const listed = await seedListing(workdir, s.seedRef);
+    const v = listed.stop === null
+      ? validateCloseDecl(job.closeDecl, { at: 'closeDecl', listing: listed.files, verdictType: job.verdictType })
+      : { ok: false, grounded: false, reds: [{ code: 'listing-unreadable', path: 'closeDecl', detail: listed.stop }] };
+    emit('close-decl', {
+      genre: job.closeDecl.genre,
+      lang: job.closeDecl.lang,
+      seedRef: s.seedRef,
+      stages: stagedClose.map((/** @type {any} */ st) => st.name),
+      grounded: v.grounded,
+      ok: v.ok,
+      ...(v.ok ? {} : { reds: v.reds.map((/** @type {any} */ r) => ({ ...r, detail: scrub(String(r.detail ?? '')) })) }),
+    });
+    if (!v.ok) {
+      emit('escalation', {
+        category: CLOSE_FAULTS.failed.category, decisionReady: true,
+        decision: 'The authored close does not validate against the repository it is about to judge — a path it names, '
+          + 'or a population it counts, does not match the seed tree. Nothing it rendered would be trustworthy.',
+        options: ['re-author the close against this repository (a new declaration is a new spec hash, and needs re-signing)', ...CLOSE_FAULTS.failed.options],
+        detail: v.reds.map((/** @type {any} */ r) => `${r.code}:${r.path}${r.detail ? ` — ${scrub(String(r.detail))}` : ''}`).join('\n'),
+      });
+      return 'close-red';
+    }
+    declaredCtx = { seedRef: s.seedRef };
+  }
+
   // ── 0a. close precheck (close-first, F17): already-green is a DISTINCT
   // record, zero tokens; a forbidden-zone verdict escalates before any spend
   const pre = await judgeClose();
@@ -838,7 +1085,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       : {}),
   });
   for (const m of menu) {
-    const v = await runStages(m.run, scrub, closeOpts);
+    const v = await runCloseStages(m.run);
     if (v.verdict === 'needs_revision') {
       seedRed.push(m.name);
       // …and the preflight grade is a READING, for the same reason the precheck one
@@ -856,7 +1103,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // handed to a human and to the replanner, which is the exact class of false
       // story this change exists to remove. Asked of the reader's own books, so
       // there is no second record of what has been graded.
-      if (!runTrend.report().stages.some((s) => s.stage === v.stage)) runTrend.record({ gap: v.gap });
+      if (!runTrend.report().stages.some((s) => s.stage === v.stage)) runTrend.record(closeGrade(v));
     }
     emit('check-preflight', { name: m.name, verdict: v.verdict, ...(m.run.length > 1 ? { chain: m.run.map((s2) => s2.name) } : {}) });
     const f = Object.hasOwn(CLOSE_FAULTS, v.verdict) ? CLOSE_FAULTS[v.verdict] : undefined;
@@ -866,10 +1113,19 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     }
   }
 
+  // ── 0c, COLD. The seam and both halves of its placement ruling are stated
+  // above, where a RESUME reaches it; this is where a run that is NOT resuming
+  // does — after the $0 precheck and preflight, so an already-green tree has
+  // already returned and left no branch behind.
+  if (!resuming) {
+    const stop = await prepareBranch();
+    if (stop !== null) return stop;
+  }
+
   const lc = new LiteCtx({ root: workdir });
   const ceiling = Array.isArray(job.tools) ? job.tools : [...TOOL_MENU];
   const fencePrefixes = job.writeScope.map((/** @type {string} */ g) => resolve(workdir, globToPrefix(g)));
-  const auditPath = join(workdir, 'gate-audit.jsonl');
+  const auditPath = join(workdir, GATE_AUDIT_FILE);
   const chainByName = new Map(menu.map((m) => [m.name, m.run]));
   // Choose-don't-describe (§4): the offered `tree-changed` scopes, enumerated from
   // the signed fence plus the directories that actually exist beneath it. ONE menu
@@ -909,7 +1165,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     // derivation, not a live path; the reachable guard is the validator's, and
     // that one is mutation-covered.
     if (!chain) return { pass: false, fault: 'failed', gap: `no offered close stage named "${name}"` };
-    const v = await runStages(chain, scrub, closeOpts);
+    const v = await runCloseStages(chain);
     emit('check-run', { name, verdict: v.verdict, ...(v.stage && v.stage !== name ? { stage: v.stage } : {}), ...(v.exitCode !== undefined ? { exitCode: v.exitCode } : {}) });
     if (v.verdict === 'satisfied') return { pass: true };
     if (v.verdict === 'needs_revision') {
@@ -927,7 +1183,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // step grade donates a null. Measured on u-msh70zla's own archived gaps: raw
       // reads `typecheck 24 → 15 → 14`, wrapped reads nothing at all. Same seam the
       // Layer R note below already calls out for a check's `^`-anchored gapKeep.
-      runTrend.record({ gap: v.gap });
+      runTrend.record(closeGrade(v));
       return { pass: false, gap: v.gap };
     }
     return { pass: false, fault: v.verdict, gap: v.detail };
@@ -955,6 +1211,27 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    *   the turn-allowance note below.
    */
   async function mkWorker({ granted, phase, attemptRounds, attempts, writable, root = null, fence = null, workerProvider = null }) {
+    // THE HARD RULE, ENFORCED STRUCTURALLY (PRD v1.57 §3). This is the ONE seam
+    // that grants write-class verbs — `writeScope` is empty for every other
+    // worker, so a read-only phase cannot reach a file whatever it intends — and
+    // a branch is therefore a PRECONDITION of it, not a courtesy the ordering
+    // above happens to provide. "No exceptions" has to mean the rule survives a
+    // future caller who adds a third writable worker and forgets the ordering.
+    //
+    // Unreachable through `runPlan` as it stands (0c runs before the scout and
+    // returns `branch-red` on any fault), which is exactly what a backstop should
+    // be. Categorised so it lands as the wiring fault it is: the step site and
+    // `relay` both return `interpreter-red` verbatim, so the escalation a human
+    // reads and the outcome the spine records name the same thing.
+    if (writable && workBranch === null) {
+      const err = /** @type {any} */ (new Error(
+        `HARD RULE (PRD v1.57 §3): a write-capable worker was requested for phase "${phase}" with no work branch prepared — `
+        + 'no job edits the branch it was handed. The run is refused rather than allowed to write where it stands.',
+      ));
+      err.category = 'interpreter-red';
+      err.lib = 'bareloop';
+      throw err;
+    }
     /**
      * The gate's LLM-turn allowance THROUGH iteration `i` — the old expression
      * `attemptRounds * (attempts + 1)` with the iteration count made explicit
@@ -984,7 +1261,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         // uses), so this can only tighten, never widen
         writeScope: writable ? (fence ?? fencePrefixes) : [],
         readScope: [workdir],
-        deny: [auditPath, join(workdir, '.smoke'), join(workdir, '.litectx')],
+        deny: [auditPath, ...ARBITER_BOOK_STORES.map((s) => join(workdir, s))],
       },
       budget: { maxCostUsd: Math.max(remainingUsd(), 0.0001) },
       limits: { maxTurns },
@@ -1098,7 +1375,23 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     /** @type {number|string|undefined} */
     let roundIteration;
     let roundsThisAttempt = 0;
-    /** @type {number|string|undefined} */
+    /**
+     * WHICH bound cut the last attempt, and — when the provider recorded one — its
+     * reason. A bare iteration number was the whole state here, so three different
+     * bounds (round cap, wall, BA-11 deny streak) were indistinguishable to the one
+     * consumer that speaks to the worker, which then told every one of them the
+     * round cap had run out. The cause travels WITH the iteration because they are
+     * read together and can never be allowed to drift apart.
+     *
+     * `reason` is scrubbed at THIS seam — the boundary, once, before any reader —
+     * so no consumer has to remember to do it (the same placement the exit results
+     * get in `judge`). It rides the spine event in the same scrubbed spelling: one
+     * value, one inventory, and an append-only log is forever.
+     * `iteration` mirrors `roundIteration` exactly, undefined included: the bound
+     * cannot know a label the run never set, and inventing one here would be the
+     * only place in this file that claims to.
+     * @type {{iteration: number|string|undefined, cause: 'rounds'|'wall'|'denied', reason: string|null}|undefined}
+     */
     let attemptBounded;
     /**
      * Open an iteration: label the rounds, reset the per-iteration round counter,
@@ -1199,19 +1492,24 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         }
         // a maxTurns session is a BOUNDED attempt, not an escalation — the same
         // role loop.stop() plays on the Loop path: judge the partial work and
-        // feed the gap forward (the CLI preserves lastText, BA-5).
-        if (r.error === 'max_turns') {
-          attemptBounded = roundIteration;
-          emit('attempt-bounded', { phase, iteration: roundIteration, cap: attemptRounds, native: true });
-          return r;
-        }
+        // feed the gap forward (the CLI preserves lastText, BA-5). A DENIAL
+        // STREAK is the same shape and takes the same lane (see the Loop path's
+        // note below — one doctrine, both surfaces).
         if (r.error) {
+          if (r.error === 'max_turns' || r.error.startsWith('denied:')) {
+            // the CAUSE is kept, not just the fact: `max_turns` really is the round
+            // cap, a `denied:` terminal is the fence, and the next attempt is told
+            // which one it was (`boundedNote`)
+            const denied = r.error.startsWith('denied:');
+            const reason = scrub(r.error);
+            attemptBounded = { iteration: roundIteration, cause: denied ? 'denied' : 'rounds', reason };
+            emit('attempt-bounded', { phase, iteration: roundIteration, cap: attemptRounds, native: true, reason });
+            return r;
+          }
           const err = /** @type {CategorizedError} */ (new Error(`native session: ${r.error}`));
-          // halt → cap-halt, denial streak → gate-red; a bridge/session terminal
-          // (bridge-failed, session_timeout, session:*) is provider-owned transport
-          err.category = r.error.startsWith('halt:') ? 'cap-halt'
-            : r.error.startsWith('denied:') ? 'gate-red'
-            : 'provider-red';
+          // halt → cap-halt; a bridge/session terminal (bridge-failed,
+          // session_timeout, session:*) is provider-owned transport
+          err.category = r.error.startsWith('halt:') ? 'cap-halt' : 'provider-red';
           err.lib = 'bare-agent';
           throw err;
         }
@@ -1309,11 +1607,11 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
           // (a step that would BEGIN past the deadline is never funded), and the head of
           // a close-fix iteration (W-2 — the run stops on the verdict already minted).
           if (clock.expired()) {
-            attemptBounded = roundIteration;
+            attemptBounded = { iteration: roundIteration, cause: 'wall', reason: null };
             emit('wall-bounded', { phase, iteration: roundIteration, ...clock.report(closeTimeoutForReport) });
             self.stop();
           } else if (roundsThisAttempt >= attemptRounds) {
-            attemptBounded = roundIteration;
+            attemptBounded = { iteration: roundIteration, cause: 'rounds', reason: null };
             emit('attempt-bounded', { phase, iteration: roundIteration, rounds: roundsThisAttempt, cap: attemptRounds });
             self.stop();
           }
@@ -1347,12 +1645,25 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       } catch (e) {
         throw categorize(e).err;
       }
-      // same error-return taxonomy as interpret's ask (one map, same doctrine):
-      // halt → cap-halt, denial streak → gate-red, API truncation → provider-red
+      // BA-11's deny streak is a BOUNDED ATTEMPT, not a terminal. It is the same
+      // shape `loop.stop()` has at the round bound thirty lines up: the attempt
+      // ran, produced real work, and was cut short by a governance bound doing
+      // exactly its job — the fence HELD, which is the opposite of a fault. So it
+      // takes the same lane: judge the partial work, feed the gap forward, the
+      // loop continues under unchanged caps. Routing it as a terminal killed a
+      // converging run with money and wall left (u-msn227nq). The native surface
+      // takes the identical lane above — one doctrine, both surfaces.
+      if (r.error && r.error.startsWith('denied:')) {
+        const reason = scrub(r.error);
+        attemptBounded = { iteration: roundIteration, cause: 'denied', reason };
+        emit('attempt-bounded', { phase, iteration: roundIteration, rounds: roundsThisAttempt, cap: attemptRounds, reason });
+        return r;
+      }
+      // the remaining error-return taxonomy (one map, same doctrine as native's):
+      // halt → cap-halt, API truncation → provider-red, anything else is wiring
       if (r.error) {
         const err = /** @type {CategorizedError} */ (new Error(`worker loop: ${r.error}`));
         err.category = r.error.startsWith('halt:') ? 'cap-halt'
-          : r.error.startsWith('denied:') ? 'gate-red'
           : r.error.startsWith('truncated:') ? 'provider-red'
           : 'interpreter-red';
         err.lib = 'bare-agent';
@@ -1388,6 +1699,14 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // and those are different diagnoses with different remedies (F45/F48: a
       // casualty is never evidence, and a governance stop is never a casualty).
       'step-stalled': [`The model stopped producing rounds during ${phase} and reissuing the call did not recover it.`, ['retry the run', 'check provider status', 'abandon the run']],
+      // A WIRING/INVARIANT fault is not a transport casualty, and the default
+      // below would file it as one. The step loop already restores this category
+      // verbatim at its own setup site ("the RECORDED outcome must match the
+      // escalation the human reads", review #6/F11); the fix loop reached `relay`
+      // instead and every such fault came back `provider-red` — a broken runner
+      // reported as the provider's fault, and an upstream ask aimed at a library
+      // for our own missing wiring (the step-stalled lesson).
+      'interpreter-red': [`The ${phase} phase could not be set up — the runner or a primitive it was handed is not correctly bound.`, ['fix the wiring the detail names', 'retry the run', 'abandon the run']],
     };
     const [decision, options] = (Object.hasOwn(DECIDE, category) ? DECIDE[category] : undefined)
       ?? [`The ${phase} call failed (${category}) — no result exists.`, ['retry the run', 'fix the provider binding', 'abandon the run']];
@@ -1398,7 +1717,8 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     // `step-stalled` rides out as ITSELF, not as provider-red. Naming the
     // escalation while returning a casualty label would launder a governance stop
     // into transport noise at exactly the layer the readout reads.
-    return category === 'cap-halt' || category === 'wall-halt' || category === 'step-stalled' ? category : 'provider-red';
+    return category === 'cap-halt' || category === 'wall-halt' || category === 'step-stalled' || category === 'interpreter-red'
+      ? category : 'provider-red';
   };
 
   // ── 1. SCOUT — read-only by construction: the write-class verbs are simply
@@ -1821,14 +2141,19 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // carries counts and paths only — never content (the spine is forever).
       const rootInj = root ? root.observe({ iteration, gap, writes: w.workerWrites() }) : null;
       if (rootInj) emit('root-injected', { step: step.id, ...rootInj.event });
+      // read ONCE: the note and the "was it the attempt just before this one" test
+      // are two questions about the same record, and two reads is how they drift
+      const bound = w.wasBounded();
       const r = await w.ask([
         step.action,
         `Repository root (absolute): ${workdir}\nEvery path you pass to a tool MUST be absolute and inside this root — a relative path resolves against a different directory and will be denied by the gate.`,
         step.target && `Write your deliverable to: ${resolve(workdir, step.target)}`,
         artifacts.length > 0 && `Working context (read-only) — prior steps' results:\n${artifacts.map((a) => `[${a.id}] ${a.text}`).join('\n\n')}`,
         gap && `Previous attempt failed this step's checks:\n${gap}`,
-        w.wasBounded() === iteration - 1
-          && `Your previous attempt was CUT OFF after ${step.rounds} tool rounds. Reading is bounded; writing is not. Form a hypothesis EARLY and make the change.`,
+        // the note names the bound that ACTUALLY fired — a deny streak and a spent
+        // round cap are different diagnoses with different remedies, and telling a
+        // fenced worker to "form a hypothesis early" aims it at the wrong wall
+        bound?.iteration === iteration - 1 && boundedNote(bound, step.rounds),
         rootInj && rootInj.note,
       ].filter(Boolean).join('\n\n'));
       lastText = scrub(r.text ?? '').slice(0, ARTIFACT_MAX);
@@ -2011,7 +2336,32 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       && cat === 'step-variance'
       && !varianceGrantUsed
       && stopTrend.trend === 'converging';
-    if ((!replanned || grantExtraReplan) && replanTrigger && remainingUsd() > MONEY_MIN) {
+    // W-2 at the replan GATE, hamr's ruling: *"past the wall no new fix cycle or step
+    // starts"* — and a replan is the first move of starting a new step. Past the
+    // deadline the whole cycle is doomed by construction and it is not free: the
+    // drafting call is bought (money the operator's time allowance no longer covers),
+    // the redrafted plan's first step is then refused at its own head by the W-2 check
+    // one level down, and the run wall-halts anyway. u-msmt91t3 paid for exactly that
+    // and called the result `step-red`. So the gate declines to FUND it.
+    //
+    // Nothing is routed here and no readout is duplicated: declining simply lets the
+    // stop fall through to the `step-variance` terminal below, which is the one site
+    // that mints the wall-halt package (record + F11-consistent escalation + levers).
+    // One site, one spelling — a second copy here is how two instruments come to
+    // disagree about one event.
+    //
+    // TRIGGER-AGNOSTIC (hamr: "extend"). It first covered the variance trigger only,
+    // the one measured on u-msmt91t3; the ladder's exhaustion and the stall fuse reach
+    // this gate past the deadline too, and a doomed cycle costs the same money whichever
+    // instrument named the stop. Each trigger then lands on its own honest terminal
+    // below — the wall for the two that would otherwise mint `step-red`, its own name
+    // for the stall (which already rides out as `step-stalled` and must, because run.js
+    // keys the F44 spend FLOOR on that outcome).
+    //
+    // The latch is NOT consumed — no grant was spent, because no replan was bought.
+    // With time on the clock this is byte-identical to today, for every trigger.
+    const wallStopsReplan = clock.expired();
+    if (!wallStopsReplan && (!replanned || grantExtraReplan) && replanTrigger && remainingUsd() > MONEY_MIN) {
       if (grantExtraReplan) varianceGrantUsed = true;
       replanned = true;
       replans += 1;
@@ -2110,6 +2460,38 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       skipCount = 0;
       continue;
     }
+    /**
+     * W-2's STEP-LOOP terminal, and the ONE place it is spelled. Reached whenever a
+     * trigger that would otherwise mint `step-red:<id>` lands with the deadline already
+     * passed: the meter's stop (F85's variance) and the ladder's (attempt exhaustion
+     * with money still on the table). Both are the same event wearing two instruments'
+     * names — the clock is what ended the run — and `step-red` is a CAPABILITY label,
+     * so minting it there files a governance stop as "the work failed". u-msmt91t3 is
+     * the measured instance: `step-red` 9.9 seconds after the run's own `wall-bounded`.
+     *
+     * One site, one spelling, because the record, the F11-consistent escalation and the
+     * lever list must be identical wherever the clock stops a step — a second copy per
+     * trigger is how two instruments come to disagree about one event. The instrument
+     * that named the stop FIRST is not discarded: it rides in the detail, so the human
+     * reads why the step was stopped as well as which lever fits.
+     *
+     * `stepWallStop` is never consulted here by construction: that record is written
+     * only by the head-of-attempt check, and both triggers above are read BEFORE it, so
+     * a step either of them stopped never reached it.
+     * @param {string} stoppedBy the instrument that named the stop first
+     */
+    const wallHaltTerminal = (stoppedBy) => {
+      emitWallHalt({ cutMidCall: false, phase: `step:${step.id}`, stepsDone: idx, stepsPlanned: plan.steps.length });
+      emit('escalation', {
+        category: 'wall-halt', decisionReady: true, phase: `step:${step.id}`,
+        decision: `The run reached its wall-clock cap while step "${step.id}" was running. Time ran out, not capability — the verdict the run already has stands.`,
+        options: WALL_OPTIONS,
+        detail: `requested ${clock.requestedMs}ms, elapsed ${clock.elapsedMs()}ms. `
+          + `${stoppedBy}: ${lastEscalation?.detail ?? '(none)'} `
+          + `Progress trend: ${stopTrend.trend} — ${stopTrend.reading}; ${stopTrend.lever}.`,
+      });
+      return 'wall-halt';
+    };
     // F64 — the wall stopped this attempt from INSIDE a provider call (the derived
     // call timeout is the deadline in the provider's own coin). ralph already
     // emitted the escalation under this category, so the outcome and the record
@@ -2132,7 +2514,19 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     // stays a step-red (the stop is a result).
     if (cat === 'cap-halt') {
       planExecuted();
-      if (remainingUsd() > MONEY_MIN) return `step-red:${step.id}`;
+      if (remainingUsd() > MONEY_MIN) {
+        // W-2 EXTENDED to the ladder's stop (hamr: "extend"). This arm is the sibling of
+        // the variance terminal below and carries the identical defect: with money still
+        // on the table it minted `step-red` whatever the clock said, so a step the
+        // deadline ended was filed as a capability failure. The wallet is re-read (it
+        // always was); the clock is re-read too, and it is read FIRST inside this arm
+        // only — a DRAINED wallet keeps its own `cap-halt` terminal below, because money
+        // is the allowance actually blocking that run and its levers are the ones the
+        // human needs (a wall-halt readout there would offer "raise maxWallMs and rerun"
+        // into an immediate money cut).
+        if (clock.expired()) return wallHaltTerminal('The ladder ended the step first');
+        return `step-red:${step.id}`;
+      }
       // v1.46 §2: the money cut is decision-ready HERE too, and for the same reason
       // W-2 gave the wall a record at every site it stops a run — a category that
       // hands the human a readout at one seam and silence at another is the readout
@@ -2148,8 +2542,22 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     // upward would mint an outcome run.js and the ledger's class table do not know,
     // and an unmapped category is counted as a library bug (ledger.js) when this is a
     // planning story. The escalation ralph already emitted carries the real detail.
+    //
+    // W-2 at the meter's own terminal. A `step-variance` stop that lands PAST the
+    // deadline is a TIME stop wearing the meter's name — the clock is what ended the
+    // run, and hamr's ruling names that stop: *"when time is up, keep the grade we
+    // already have and stop"*. Its cap-halt sibling directly above already re-reads its
+    // own governor (the wallet) before minting a terminal; this branch did not, and on
+    // u-msmt91t3 it minted `step-red` 9.9 seconds AFTER the run's own `wall-bounded`
+    // record — a governance stop filed as a capability read, and (the resume gate's
+    // half of the same defect) a checkpoint filed as an answer.
+    //
+    // The clock is read HERE, with nothing in flight, exactly as the three other
+    // terminal sites read it. With time still on the clock this is byte-identical to
+    // what it was: the step-red is the designed stop, and the stop is the result.
     if (cat === 'step-variance') {
       planExecuted();
+      if (clock.expired()) return wallHaltTerminal('The meter stopped the step first');
       return `step-red:${step.id}`;
     }
     // Any OTHER terminal escalation category is NOT a capability failure: a