bareloop 0.6.0 → 0.7.0

package/src/run.js

@@ -76,9 +76,46 @@ 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 {number} [opts.capRuns] shell-owned per-step attempt cap
+ * @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
  * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
  * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
+ * @param {unknown} [opts.bridge] Layer 3 — a bridge-v1 entry to reuse as the drafter's
+ *   STARTING DRAFT (design record 2026-08-01, D4), forwarded to the plan flow. Omitted is
+ *   the cold path and is byte-identical to a pre-Layer-3 run. WHICH entry (the listing, an
+ *   operator pin, the LLM's pick) is the caller's decision, and so is what to do when the
+ *   load gate refuses one: a refusal returns the distinct `recipe-stale` outcome with zero
+ *   spend rather than silently drafting cold, because starting a paid run on a decision
+ *   nobody made is the same class of error as widening a cap to manufacture a green.
+ * @param {number} [opts.priorSpentUsd=0] RESUME (module C) — money a PREVIOUS, killed
+ *   attempt of this same try already spent. It seeds the ledger, so the restarted
+ *   attempt runs under the REMAINDER of the signed `budgetUsd` and the terminal
+ *   `job-end` states the try's WHOLE spend across both attempts. hamr's ruling: "a
+ *   budget ceiling folds in prior spend so re-invoking cannot silently widen it" —
+ *   the fold is the seam precisely because the CAP is in the spec hash, so
+ *   tightening the cap instead would make a new spec version needing a signature
+ *   nobody typed. The caller reconstructs the figure from the dead run's own spine.
+ * @param {boolean} [opts.priorSpendComplete=true] RESUME — was that fold EXACT?
+ *   `readResume` reports false when any round inside the dead attempt came back
+ *   unpriced, which makes the fold a FLOOR. The unknown does not heal by being carried
+ *   forward, so it rides one-way onto every `job-end` this run emits: a total built on
+ *   a floor is a floor, and reporting it as exact is F6 in a resume's coat.
+ * @param {number} [opts.priorWallMs=0] RESUME — the same ruling in a time coat: wall
+ *   time the killed attempt already consumed, folded into the run clock so the
+ *   restart gets the remainder of the SIGNED wall, never a fresh allotment.
+ * @param {any} [opts.resumeSeed] RESUME (module C v2) — WHERE inside the killed attempt
+ *   the kill landed, read off its own spine by `readResume`: the plan it accepted and the
+ *   steps that reached their exits. Forwarded verbatim to the plan flow, which reloads
+ *   the plan instead of re-scouting and re-drafting, and skips the finished steps.
+ *   hamr's ruling: *"start last step instead from the beginning, why would i want to
+ *   waste more money on something i already started"*. Absent is the ordinary path.
+ * @param {{stage?: string|null, value?: number|null}[]} [opts.resumeGrades] RESUME — the
+ *   close grades the killed leg recorded (`readResume`'s `restart.grades`), forwarded to
+ *   the plan flow as the trend's BASELINES. A resumed run's halt readout judges the whole
+ *   chain, not just the leg: without them a leg that re-grades an unchanged tree reports
+ *   `flat` — "revise the goal" — on a run that was converging when the money ran out.
+ *   Counts and stage names only; no close bytes cross this seam. Absent is the cold path.
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -88,16 +125,32 @@ async function primitiveSmoke(workdir) {
  *        binding.)
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
- *   'close-red' | 'close-unsupported' | 'pricing-red' | 'provider-red' |
+ *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' | 'provider-red' |
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns = 3, shellCapUsd = 2, closeTimeoutMs, layerRoot = false }) {
+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 = [] }) {
   // 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
   // into $0 (F12's class, at the terminal record instead of mid-attempt).
-  let spentUsd = 0;
+  //
+  // It starts at the RESUME fold rather than at 0 when a killed attempt of this
+  // same try already spent money (see `priorSpentUsd`). Belted like every other
+  // 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;
   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
+  // being carried forward — every round of THIS attempt being priced repairs nothing
+  // about the one before it. One-way, like `stalled` and `cutMidCall`, and read by
+  // `spend()`, so the terminal states a floor instead of an exact-looking total (F6).
+  // Read off the FLAG alone, never conjoined with the money: a leg killed with every
+  // round unpriced folds $0 and still says `false`, and that is a floor OF zero, not an
+  // exact zero. Gating on `spentUsd > 0` dropped exactly that predecessor's unknown and
+  // handed the resumed terminal an exact-looking total. The param defaults `true`, so a
+  // run nobody resumed is unchanged.
+  const priorFloor = priorSpendComplete === false;
   // W1: did this run ABSORB a stall? The terminal `step-stalled` is the rare case;
   // the common one self-heals (src/stall.js abandons the hung call and reissues),
   // and an abandoned call may already have been billed — a reissue can pay twice
@@ -122,7 +175,10 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // says so machine-readably instead of dressing a floor up as exact. Emitted on
   // EVERY job-end (true when everything was priced) so no consumer ever has to
   // branch on field presence.
-  const spend = () => ({ spentUsd, spendComplete: !unpriced && !stalled && !cutMidCall });
+  // 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() });
   // 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() });
@@ -138,6 +194,16 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   emit('job-start', {
     job: job.job, specHash: jobSpecHash(job), budgetUsd: job.budgetUsd,
     shape: 'plan', goal: job.goal,
+    // RESUME (v1.46 §3) — the DECLARED fold, the `try-start` precedent one level
+    // down. A reader reconstructing a chain of resumes must add only each attempt's
+    // OWN new rounds; without this record the second resume of a halted run would
+    // re-derive from its own file alone and silently widen the ceiling by everything
+    // spent before it. Emitted only when there IS a fold: an absent fold is absent,
+    // and a decorative `0` would be indistinguishable from a run nobody folded.
+    // 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 } : {}),
   });
 
   // 2. known-answer smoke before tokens (A3: silent degradation throws nothing)
@@ -190,9 +256,10 @@ 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, closeTimeoutMs, layerRoot,
+      workdir, provider, nativeProvider, providerFor, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs, resumeSeed, resumeGrades,
       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
     });
     if (unpriced) return pricingRed();
     if (outcome.startsWith('step-red:')) {

package/src/selection.js

@@ -0,0 +1,160 @@
+// 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).
+//
+// 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
+// keep a way for user to inspect and view existing workflows … but llm can override and
+// say none matches the ask and that agent has to create a new one)"*.
+//
+// **Both functions are pure text.** Nothing here reads a file, calls a model, or decides
+// a run: the selection CALL, the operator's pin/shortlist/force-cold flow, and the parse
+// of the answer are the runner's (modules 4/5). Choosing is not authoring — the user
+// picks among workflows the agent authored and greens minted, and never writes a step, a
+// check or a plan (PRD v1.28, unbroken).
+//
+// Two display rules are load-bearing rather than cosmetic:
+//
+//  - **F6 — unpriced is never free.** An unknown cost or duration renders as UNKNOWN, and
+//    a band that skipped unknowns says how many it skipped. A `$0.00` where nothing was
+//    priced is a floor that reads as exact, which is the dishonesty F6 exists to stop; the
+//    same discipline extends to time.
+//  - **A listing shorter than its directory must say so.** `loadRegistry` skips-and-reports
+//    a malformed entry; a listing that quietly shows the survivors would leave the picker
+//    choosing from a set nobody told it was incomplete — the blind-instrument class.
+//
+// There is deliberately NO score and no ranking beyond name order (D6): n=1 is an anecdote
+// 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';
+
+/** minutes, one decimal — the granularity a human picks a workflow at (the unit is
+ * written once, by the band) */
+const minutes = (/** @type {number} */ ms) => (ms / 60_000).toFixed(1);
+const usd = (/** @type {number} */ n) => `$${n.toFixed(2)}`;
+
+/**
+ * One aggregate, rendered honestly (F6). `min`/`max` are null when NOTHING in the set was
+ * known — the answer is UNKNOWN, never a zero — and a partial set carries the count it
+ * could not read.
+ * @param {number|null} min @param {number|null} max
+ * @param {(n: number) => string} fmt
+ * @param {number} unknown how many of the greens carried no figure
+ * @param {number} total how many greens there are
+ * @param {string} word the honest name for a missing figure ('unpriced' | 'untimed')
+ * @param {string} [suffix] the unit, written ONCE after the range ("8.9–31.6 min", never
+ *   "8.9 min–31.6 min")
+ */
+function band(min, max, fmt, unknown, total, word, suffix = '') {
+  if (min === null || max === null) return `UNKNOWN (${total || 'no'} green${total === 1 ? '' : 's'}, none ${word === 'unpriced' ? 'priced' : 'timed'})`;
+  const core = `${min === max ? fmt(min) : `${fmt(min)}–${fmt(max)}`}${suffix}`;
+  return unknown > 0 ? `${core} (${unknown} of ${total} ${word})` : core;
+}
+
+/**
+ * D3's listing: what the operator inspects and what the selecting model reads — the SAME
+ * text, so the two can never be choosing from different sets.
+ *
+ * Per bridge, one compact block: name, the job sentence it greened, status, greens/reds
+ * with the last outcome, and the cost/time band of its greens.
+ *
+ * Total and never throws: a listing is a display surface, and one malformed entry must
+ * not take the whole listing down (`listingRow` holds the same contract). Deterministic
+ * by name, whatever order the entries arrived in — a set that reshuffles between calls
+ * would make one picker's answer unreadable against another's.
+ *
+ * @param {unknown} registry `loadRegistry`'s result (`{ok, reds, bridges}`) or a bare
+ *   array of entries. The RESULT form is preferred: it carries the skip reds, and the
+ *   skips are the half a bare array cannot tell you about.
+ * @returns {string}
+ */
+export function renderListing(registry) {
+  const r = /** @type {any} */ (registry);
+  const bridges = (Array.isArray(r) ? r : (Array.isArray(r?.bridges) ? r.bridges : [])).filter((b) => b && typeof b === 'object');
+  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')
+    : '';
+
+  if (!rows.length) {
+    return `WORKFLOWS ON RECORD — none.\nThere are no workflows to reuse; a plan has to be drafted from scratch.${skipped}`;
+  }
+
+  const blocks = rows.map((row) => {
+    const g = row.greenCost;
+    return [
+      `[${row.name ?? '(unnamed)'}]  ${(row.status ?? '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')}`
+        + ` · time ${band(g.minWallMs, g.maxWallMs, minutes, g.untimedCount, row.greens, 'untimed', ' min')}`,
+    ].join('\n');
+  });
+
+  return `WORKFLOWS ON RECORD — ${rows.length}\nCANDIDATE = greened once · PROVEN = greened on two distinct repositories. There is deliberately no success score.\n\n${blocks.join('\n\n')}${skipped}`;
+}
+
+/**
+ * The SELECT-WORKFLOW prompt: the text a later module sends to ask which workflow (if
+ * any) the run should start from. Pure — it sends nothing and parses nothing.
+ *
+ * D3's two standing rules are IN the prompt rather than enforced after the fact:
+ *  - *"none matches"* is a first-class answer, and it means the agent drafts new. A picker
+ *    with no way to decline would return the closest thing on the shelf every time, which
+ *    is how a registry becomes a lookup table.
+ *  - a PINNED workflow may be refused **only explicitly, with a reason** — never silently
+ *    ignored or quietly substituted. The operator's pick is the operator's; overriding it
+ *    invisibly is the one thing a picker must not be able to do.
+ *
+ * The output contract is stated so the answer is machine-readable, but the PARSE belongs
+ * to the runner that sends this (modules 4/5) — and the runner's parser and this shape are
+ * one contract in two places, which is why the shape is spelled out here rather than left
+ * to the model.
+ *
+ * @param {string} listing `renderListing`'s text — verbatim, so the picker sees exactly
+ *   what the human inspecting the registry sees
+ * @param {string} ask the job's goal sentence, in the operator's own words
+ * @param {string|null} [pinned] the operator's PIN, stated IN the call. D3 rules that a
+ *   pin is never bypassed and never silently overridden — so the pin does not skip the
+ *   call, it enters it, and the model's only legal ways out are confirming it or
+ *   refusing it by name with a reason. Stated here rather than assembled by the runner:
+ *   a second spelling of the pin sentence is a second prompt, and the two would drift.
+ * @returns {string}
+ */
+export function selectionPrompt(listing, ask, pinned = null) {
+  const pin = pinned
+    ? `\nThe operator has PINNED the workflow "${pinned}". Start from it unless it is genuinely the
+wrong kind of recipe for this ask. If you cannot use it, you must say so by picking a
+DIFFERENT name (or null) and giving the reason — the operator's pick is then handed back
+to the operator, never quietly replaced by yours.\n`
+    : '';
+  return `SELECT-WORKFLOW
+A previous run's workflow can be handed to the planner as a STARTING DRAFT for a new job —
+it saves the planner starting from a blank page. Your job is to decide whether any workflow
+on record is close enough to be worth starting from, or whether this ask needs a new plan.
+
+The ask:
+${ask}
+
+${listing}
+${pin}
+Rules:
+- Pick AT MOST ONE workflow, by its exact name, copied character for character from the listing.
+- A workflow is worth reusing when it did the same KIND of work — the same sort of change,
+  judged the same sort of way. It does NOT have to name the same files: it ran on a different
+  repository, so its paths, scopes and targets are expected to be wrong here and the planner
+  will replace them.
+- If none of them matches this ask, say so plainly and pick nothing.
+  The agent then drafts a new plan from scratch. "None matches" is a real answer, and a bad
+  starting draft costs more than a blank page.
+- If the operator PINNED a workflow, you may refuse it — but only EXPLICITLY, and with a
+  reason. Never silently ignore the pin or quietly substitute another one.
+- You are choosing, not authoring. You cannot edit, merge or invent a workflow here; the
+  planner does the tweaking afterwards, and the job's own verification is the only truth.
+
+Output ONLY this JSON object, no fences and no commentary:
+{"choice": "<exact name from the listing>" or null, "reason": "<one sentence>"}`;
+}

package/src/spine.js

@@ -11,10 +11,15 @@ import { appendFileSync } from 'node:fs';
 /**
  * Create an emitter bound to one JSONL file.
  * @param {string} file absolute path; created on first emit
+ * @param {{startSeq?: number}} [opts] `startSeq`: the last `seq` already IN the file, for a
+ *   process that CONTINUES an existing spine (a resumed run appends to the dead run's own
+ *   log — module C). `seq` is monotonic per SPINE, so a second series restarting at 1
+ *   would give one append-only log two rows with the same number and silently break every
+ *   reader that orders by it. Default 0: a fresh file, which is every other caller.
  * @returns {(type: string, data?: object) => object} emit — returns the event as written
  */
-export function makeSpine(file) {
-  let seq = 0;
+export function makeSpine(file, { startSeq = 0 } = {}) {
+  let seq = typeof startSeq === 'number' && Number.isFinite(startSeq) && startSeq > 0 ? Math.floor(startSeq) : 0;
   return function emit(type, data = {}) {
     // type/seq/ts are the envelope's, by mechanism not comment: callers spread
     // foreign objects into events, and a payload that grows one of these keys