bareloop 0.5.1 → 0.7.0

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

package/src/stall.js

@@ -0,0 +1,252 @@
+// The stall watchdog (F66) — the only instrument that fires on the ABSENCE of ROUNDS.
+//
+// MEASURED reason this exists. bare-agent's `timeoutMs` is an IDLE-SOCKET timeout:
+// `applyRequestTimeout` is one `req.setTimeout(...)` in provider-http.js, and Node
+// resets that timer on every byte. Its own docstring is explicit — "the timer
+// resets on activity, so a slow-but-streaming response is not killed". On U run
+// ms3197n8 the connection stayed alive for 274 minutes with ZERO rounds emitted,
+// then died `read ECONNRESET`. bare-agent's timer never fired; the run spent
+// 287.3min against a 45min wall and $3.23 for nothing. The bound was correctly
+// derived and correctly forwarded (loop.js:732 passes options per provider call) —
+// it just watches bytes, and bytes kept flowing while the run made no progress.
+//
+// So the heartbeat here is A COMPLETED ROUND, not a byte. That swap IS the fix,
+// and it is the one signal bare-agent cannot see from inside the HTTP request.
+//
+// SELF-HEAL, not a stop (hamr's ruling): "the goal is always self heal and killing
+// and coming back is not an option — what would we tell the user, it timed out, do
+// something?!" A stall abandons the call and REISSUES it; the operator never hears
+// about it. Only after `maxStalls` does the watch give up, and even then it does
+// not end the run — it throws `step-stalled`, which the step loop reads as a
+// replan trigger. The run adapts; it does not surrender.
+//
+// What still bounds this, so self-heal cannot run away: the wallet is unchanged (a
+// reissue spends from the same signed budget), the wall clock still ends the run,
+// and the step's round bound is untouched. The one honest cost is that an
+// abandoned call MAY already have been billed, so a reissue can pay twice — that
+// is capped by the wallet, and unknown spend is reported as unknown, never zero
+// (F6/F44). It is also exactly why `Retry` was left unwired; self-heal is the
+// ruling that overrides it.
+//
+// L4 — "the wall clock still ends the run" was the half-true half of that. The
+// clock is consulted where a ROUND completes (planrun's `metered`) and after a step
+// returns; during a stall no round completes and no step returns, so nothing read it
+// between the wall passing and the next reissue. A worker stalling at its wall could
+// therefore be reissued for up to maxStalls × stallMs of calls the run had already
+// declined to authorize. So the watch takes the wall as a callback and consults it
+// BEFORE reissuing: past the deadline it does not self-heal, it gives up. That is
+// not a retreat from hamr's ruling — self-heal is what a run does with time left,
+// and there is none.
+//
+// Timers are injected so the whole mechanism is deterministically testable — a
+// watchdog validated with real sleeps is a flake generator, and one that is never
+// watched failing is not validated at all.
+
+/** hamr's number: no completed round for five minutes is a stall. */
+export const STALL_MS = 300_000;
+/** hamr's number: three stalls, then stop reissuing and replan. The count is
+ * CUMULATIVE over the watch's whole life and `watch()` never resets it — planrun
+ * builds one watch per WORKER, so the ceiling is spent across the STEP, not per
+ * call: two stalls on one call and one on the next give up just the same. That
+ * is deliberate (a step that keeps hanging is a step to replan, not a call to
+ * retry forever), and it is why nothing here says "on one call". */
+export const MAX_STALLS = 3;
+
+/**
+ * A stall gave up. Carries the category the step loop's replan trigger reads and
+ * the `lib` attribution stamped AT THE THROW SITE (never sniffed from prose).
+ */
+export class StallError extends Error {
+  /** @param {string} message @param {number} stalls */
+  constructor(message, stalls) {
+    super(message);
+    this.name = 'StallError';
+    /** @type {string} */
+    this.category = 'step-stalled';
+    /** @type {string} */
+    this.lib = 'bare-agent';
+    /** @type {number} */
+    this.stalls = stalls;
+  }
+}
+
+/**
+ * @typedef {Object} StallWatch
+ * @property {<T>(call: (gen: number) => Promise<T>) => Promise<T>} watch run `call`,
+ *   reissuing it whenever it goes `stallMs` without a beat; rejects `StallError` past
+ *   `maxStalls`. Each issue is handed its GENERATION — the token every callback that
+ *   call installs must carry back, so a corpse's callbacks cannot touch the live call.
+ * @property {(gen: number) => void} beat a round completed on generation `gen` — reset
+ *   the window. From any other generation it is inert.
+ * @property {(gen: number) => boolean} isCurrent is `gen` still the call this watch is
+ *   waiting on? The caller reads it to withhold everything else a dead call would do.
+ * @property {() => number} stalls how many stalls this watch has absorbed
+ */
+
+/**
+ * Start a stall watchdog.
+ * @param {{ stallMs?: number, maxStalls?: number, onStall?: (n: number) => void,
+ *          expired?: () => boolean,
+ *          setTimer?: (fn: () => void, ms: number) => any,
+ *          clearTimer?: (id: any) => void }} [opts]
+ *   `onStall` is announced for EVERY stall including the last — a trim or a
+ *   recovery that happens silently is indistinguishable from one that never
+ *   happened (F28's rule, applied to time).
+ *   `expired` is the run's WALL, read at the one moment this module decides to
+ *   spend again (L4). Omitted, the watch behaves exactly as it did before the wall
+ *   existed — a caller with no clock reissues on the same rules.
+ * @returns {StallWatch}
+ */
+export function createStallWatch({
+  stallMs = STALL_MS,
+  maxStalls = MAX_STALLS,
+  onStall = () => {},
+  expired = () => false,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+} = {}) {
+  let stalls = 0;
+  /** @type {any} */
+  let timerId = null;
+  /** the generation of the call currently being watched: NOTHING from an ABANDONED
+   * call may touch the one that replaced it — not its trip, not its late settlement,
+   * and not its beats. The corpse keeps streaming (ms3197n8's socket lived 274min
+   * after we would have moved on), so every callback it installed keeps firing; the
+   * generation is the token that tells those callbacks apart from the live call's.
+   * It is handed to each issued call and carried back through `beat`/`isCurrent`. */
+  let generation = 0;
+  let settled = true;
+  /** @type {((v: any) => void) | null} */
+  let resolve = null;
+  /** @type {((e: any) => void) | null} */
+  let reject = null;
+  /** @type {((gen: number) => Promise<any>) | null} */
+  let theCall = null;
+
+  const disarm = () => {
+    if (timerId !== null) { clearTimer(timerId); timerId = null; }
+  };
+
+  /** @param {number} gen */
+  function arm(gen) {
+    disarm();
+    timerId = setTimer(() => {
+      timerId = null;
+      if (settled || gen !== generation) return; // a trip from a superseded call
+      trip();
+    }, stallMs);
+  }
+
+  function trip() {
+    stalls += 1;
+    onStall(stalls);
+    generation += 1; // everything from the abandoned call is now inert
+    // L4 — the WALL, read before the decision to spend again, and read FIRST. A
+    // reissue past the deadline is money and time the run has already declined to
+    // authorize, and it is the only spend on this path nothing else can catch: no
+    // round completes during a stall, so `metered`'s clock check never fires, and no
+    // step returns, so the step loop's never does either.
+    //
+    // It outranks the `maxStalls` ceiling deliberately, and the category is the
+    // reason. `step-stalled` is a REPLAN TRIGGER (planrun's third trigger): it says
+    // "the model stopped answering, re-allocate what is left" and buys a fresh
+    // drafting round. On an expired wall there is nothing left to re-allocate, so
+    // that route would spend a draft on a run that is over and hand the operator
+    // "retry the run / check provider status" for a stop whose only remedy is
+    // `maxWallMs`. `wall-halt` is the truthful reading — the wall bound the run, not
+    // the model — and it is the SAME ruling clock.js already made for the F64
+    // ambiguity: a call that dies on a run whose wall has also passed reads as a
+    // wall-halt, because the run is out of time either way and the remedy is
+    // identical. No new category, no new routing: every consumer (ralph's
+    // DECISIONS, the step loop's terminal, `relay`, the ledger's exclusions) already
+    // handles `wall-halt`, and none of them replans on it.
+    if (expired()) {
+      settled = true;
+      disarm();
+      // Not a StallError: that class IS the `step-stalled` category, and a stall
+      // count is what happened on the way here, not what stopped it. No `lib`
+      // either — the wall is bareloop's own governance instrument, and stamping an
+      // upstream package would stand a fake bug of ours where real evidence goes.
+      const err = /** @type {any} */ (new Error(
+        `the run's wall-clock cap passed while this call was stalled (${stalls} stall${stalls === 1 ? '' : 's'}) — not reissuing`,
+      ));
+      err.category = 'wall-halt';
+      err.stalls = stalls;
+      reject?.(err);
+      return;
+    }
+    if (stalls >= maxStalls) {
+      settled = true;
+      disarm();
+      reject?.(new StallError(
+        `no round completed for ${Math.round(stallMs / 1000)}s, ${stalls} times in this step — not reissuing again`,
+        stalls,
+      ));
+      return;
+    }
+    issue(); // self-heal: abandon the hung call, start a fresh one
+  }
+
+  function issue() {
+    const gen = generation;
+    arm(gen);
+    let p;
+    try {
+      // the call is TOLD its generation: the callbacks it wires (metering, the round
+      // bound, the wall cut) outlive the call itself, and this is the only token that
+      // lets them ask "am I still the live one?".
+      p = /** @type {(g: number) => Promise<any>} */ (theCall)(gen);
+    } catch (e) { // a synchronous throw is a real failure, not a stall
+      settled = true;
+      disarm();
+      reject?.(e);
+      return;
+    }
+    p.then(
+      (v) => {
+        if (settled || gen !== generation) return; // an abandoned call finally answered
+        settled = true;
+        disarm();
+        resolve?.(v);
+      },
+      (e) => {
+        // The abandoned socket dies LATER — ms3197n8's did, at +274min. Nobody is
+        // listening any more, and an unhandled rejection here would take the whole
+        // run down. Swallowing it is the point, not an oversight.
+        if (settled || gen !== generation) return;
+        settled = true;
+        disarm();
+        reject?.(e);
+      },
+    );
+  }
+
+  /** @type {<T>(call: (gen: number) => Promise<T>) => Promise<T>} */
+  function watch(call) {
+    theCall = call;
+    settled = false;
+    generation += 1;
+    return new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+      issue();
+    });
+  }
+
+  return {
+    stalls: () => stalls,
+    // A beat is SCOPED TO ITS CALL. Rounds do arrive from a call we abandoned, and
+    // re-arming on one is not a harmless late timer: it re-arms the watch that is
+    // timing the REPLACEMENT, so the corpse feeds the watchdog and the live call can
+    // hang for the rest of the run without ever tripping. A beat after the watch has
+    // settled is inert for the same reason.
+    /** @param {number} gen the generation `watch` handed the call that produced this round */
+    beat(gen) {
+      if (settled || gen !== generation) return;
+      arm(generation);
+    },
+    /** @param {number} gen @returns {boolean} */
+    isCurrent: (gen) => !settled && gen === generation,
+    watch,
+  };
+}