bareloop 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",
@@ -23,9 +23,9 @@
     "prepublishOnly": "npm run build:types"
   },
   "dependencies": {
-    "bare-agent": "^0.33.1",
+    "bare-agent": "^0.35.0",
     "bareguard": "^0.12.0",
-    "litectx": "^0.29.1"
+    "litectx": "^0.31.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/clock.js

@@ -0,0 +1,181 @@
+// T's wall clock — the shell's time instrument (PRD v1.27/v1.29; materials
+// design record 2026-07-26, addenda 1 and 3).
+//
+// Time is arbiter territory with exactly `budgetUsd`'s status: operator input,
+// the agent may tighten and never widen, never self-raised. The agent has no time
+// field in the plan vocabulary at all (addendum 2), so nothing here is reachable
+// from an agent-authored document — this module is read by the runner only.
+//
+// Three measured facts shape it, none of them assumed:
+//
+//   1. `loop.stop()` CANNOT cut an in-flight call. Measured (F61/C1): fired at
+//      500ms against a 4,000ms hanging generate(), run() returned at 4,018ms.
+//      bare-agent reads the flag at the round boundary (loop.js:661) and between
+//      tool calls (:916). So a wall deadline is a BETWEEN-ROUND check, and
+//      enforcement is `maxWallMs + closeStages × closeTimeoutMs` — reported, never
+//      rounded down to the requested number (F6 in a time coat). The multiplier is
+//      W5: a STAGED close (PRD v1.28) runs its stages one at a time and hands EACH
+//      one the full `closeTimeoutMs` (`runStages` → `runClose`, ralph.js:257), so a
+//      4-stage close at 900s is 60 minutes of close, not 15. The runner's own
+//      outside watchdog already sized its stale window this way
+//      (scripts/run-u.mjs: `CLOSE_TIMEOUT_MS * spec.close.length`); the clock
+//      quoting the 1× number was the same arithmetic disagreeing with itself.
+//      That figure counts ONE close, and the RUNNER is what holds both of its loops
+//      to one: past the deadline it refuses to open a new fix iteration and stops on
+//      the verdict the last close already minted (W-2), and it refuses to open a
+//      STEP's attempt on the same reading — a step that would begin past the deadline
+//      is never funded. Before that second refusal a step starting with zero time left
+//      burned every attempt it was allowed (measured on the real flow: three attempts,
+//      three judged exits, all past the deadline), because the variance meter scores a
+//      step's time share against what the run had left when the step BEGAN and so is
+//      structurally blind to a step that began with nothing.
+//      It is still not a universal bound and is not claimed as one. Two overshoots
+//      remain outside this number, both deliberate. A step ALREADY UNDER WAY when the
+//      deadline trips finishes its attempt and runs its own exit checks (themselves
+//      close stages, at the full timeout each): grading real work always completes, or
+//      the run is unreadable after the money is spent. And that same mid-step deadline
+//      still routes through the ONE replan — the meter's own terminal, unchanged — so
+//      it pays a drafting call (floored at MIN_CALL_TIMEOUT_MS) before the new plan's
+//      first step is the one refused.
+//   2. BA-18's provider timeout is the only instrument that fires on the ABSENCE
+//      of events. Measured (F61/C2): 1,259ms against a socket that accepts and
+//      never answers; without it the bound is the OS TCP timeout (~2h). Deriving
+//      it from the remaining budget is what stops the LAST round outliving the run.
+//   3. ~90% accuracy is the bar, by hamr's ruling (addendum 3). This module does
+//      not chase precision; it reports honestly at the precision it has.
+//
+// Unbounded is a REAL state, not a large number: hamr ruled `maxWallMs` has no
+// default, so a run without one is time-unbounded by explicit operator choice and
+// says so (F45 — a defaulted cap is a silent second ceiling).
+
+/** BA-18's default request/idle timeout (`AnthropicProvider.timeoutMs`), the
+ * ceiling every derived per-call timeout starts from. Kept in sync deliberately:
+ * a value ABOVE the provider's own default would be inert. */
+export const PROVIDER_TIMEOUT_MS = 600_000;
+
+/**
+ * The floor for a derived per-call timeout. Below this a call cannot plausibly
+ * succeed, and a timeout that is certain to trip manufactures a `provider-red`
+ * out of a time budget — a transport CASUALTY, which is never evidence
+ * (F45/F48). The deadline check is what must stop a run out of time; the per-call
+ * timeout exists to bound a HANG, not to enforce the budget's last second.
+ */
+export const MIN_CALL_TIMEOUT_MS = 30_000;
+
+/** bare-agent's rejection code when its request/idle timeout trips (BA-18,
+ * `provider-http.js` → `TimeoutError`). The error carries a `code` and NO
+ * `category`, so every consumer that defaults an uncategorised throw would file
+ * it as transport. */
+export const TIMEOUT_CODE = 'ETIMEDOUT';
+
+/**
+ * F64 — is this throw the run's OWN deadline coming back dressed as a provider
+ * error? `callTimeoutMs()` hands the provider a bound derived from the wall, so
+ * when the wall is what shrank that bound, the resulting `TimeoutError` is a
+ * GOVERNANCE stop, not a casualty. Filing it as `provider-red` would discard it
+ * (a casualty is never evidence, F45/F48) and attach the F44
+ * `spendComplete:false` floor to a run that simply ran out of time.
+ *
+ * The discriminator is the wall itself, not the derived number: on a bounded
+ * clock a trip can only precede expiry when the bound came from the provider's
+ * own default (`remainingMs() > PROVIDER_TIMEOUT_MS`), and that case is transport
+ * by construction. So "already expired" IS the wall-derived set. An unbounded run
+ * can never produce one, and needs no separate `bounded` term to say so —
+ * `expired()` is false by construction with no cap. (A mutation run proved the
+ * extra term inert; the unbounded case is guarded by its own test instead, which
+ * is where that invariant belongs.)
+ *
+ * A genuine dead socket on a run whose wall has ALSO passed reads as a wall-halt.
+ * That is deliberate and honest: the run is out of time either way, the remedy is
+ * the same (raise `maxWallMs`), and the alternative — calling a governance stop
+ * transport on the chance that it was — is the failure this closes.
+ *
+ * @param {any} err the throw as caught
+ * @param {Clock} clock the run's clock
+ * @returns {boolean}
+ */
+export function isWallTimeout(err, clock) {
+  return !!err && err.code === TIMEOUT_CODE && clock.expired();
+}
+
+/**
+ * @typedef {object} Clock
+ * @property {boolean} bounded whether the operator set a cap at all
+ * @property {number|null} requestedMs the operator's number; `null` when unbounded
+ * @property {number} closeStages how many close stages one verdict can pay for (W5)
+ * @property {() => number} elapsedMs wall time since the clock was created
+ * @property {() => number} remainingMs what is left, floored at 0; `Infinity` when unbounded
+ * @property {() => boolean} expired whether the deadline has passed (always false when unbounded)
+ * @property {(closeTimeoutMs: number) => number|null} enforcedMs the HONEST worst case
+ * @property {(providerDefaultMs?: number) => number} callTimeoutMs the derived per-call bound
+ * @property {(closeTimeoutMs: number) => object} report one spine-safe shape carrying both numbers
+ */
+
+/**
+ * Start a wall clock for one run.
+ * @param {{ maxWallMs?: number|null, closeStages?: number, now?: () => number }} [opts]
+ *   `maxWallMs`: the signed operator cap, or absent/null for an honestly unbounded
+ *   run. `closeStages`: how many stages the job's close runs (W5) — each one gets
+ *   the FULL `closeTimeoutMs`, so this is the multiplier on the overshoot, not a
+ *   decoration. Defaults to 1, the single-predicate close. `now`: injected for
+ *   tests — the default is the real clock.
+ * @returns {Clock}
+ */
+export function createClock({ maxWallMs = null, closeStages = 1, now = () => Date.now() } = {}) {
+  const startedAt = now();
+  // A cap is only a cap if it is a usable positive number. validateJob already
+  // reds anything else, so this is the belt (a caller that hand-builds a spec
+  // must not be able to turn a garbage value into a silent unbounded run OR a
+  // silent instant expiry).
+  const bounded = typeof maxWallMs === 'number' && Number.isFinite(maxWallMs) && maxWallMs > 0;
+  const cap = bounded ? maxWallMs : null;
+  // The same belt on the stage count. A close always runs at least once, so 1 is
+  // the floor: a 0 or a NaN sneaking in here would quote an enforced number BELOW
+  // the requested cap, which is the dishonesty this multiplier exists to remove.
+  const stages = typeof closeStages === 'number' && Number.isFinite(closeStages) && closeStages >= 1
+    ? Math.floor(closeStages) : 1;
+  /** the ONE arithmetic, so the advertised record and the enforced worst case
+   * cannot be computed two ways (the two-transforms class, F9). */
+  const enforced = (/** @type {number} */ closeTimeoutMs) => (cap === null ? null : cap + stages * closeTimeoutMs);
+
+  const elapsedMs = () => now() - startedAt;
+  const remainingMs = () => (cap === null ? Infinity : Math.max(0, cap - elapsedMs()));
+  // Inclusive: AT the deadline is out of budget. A run resumes to cap, and the
+  // stop IS the checkpoint (v1.12) — so stopping one round early is correct and
+  // stopping one round late is the overshoot addendum 1 quantifies.
+  const expired = () => cap !== null && elapsedMs() >= cap;
+
+  return {
+    bounded,
+    requestedMs: cap,
+    closeStages: stages,
+    elapsedMs,
+    remainingMs,
+    expired,
+    enforcedMs: enforced,
+    callTimeoutMs: (providerDefaultMs = PROVIDER_TIMEOUT_MS) => {
+      if (cap === null) return providerDefaultMs;
+      // Clamped BOTH ways. Upper: never above the provider's own default, which
+      // would be inert. Lower: never below MIN_CALL_TIMEOUT_MS, and in
+      // particular never 0 — `0` DISABLES the provider timeout entirely
+      // (provider-anthropic.js), which is the exact opposite of the intent and
+      // would restore the ~2h OS-TCP hang on the last round of a tight budget.
+      return Math.min(providerDefaultMs, Math.max(MIN_CALL_TIMEOUT_MS, remainingMs()));
+    },
+    report: (closeTimeoutMs) => ({
+      bounded,
+      requestedMs: cap,
+      // On the record, not just in the arithmetic: without it a reader seeing
+      // enforced 90min against a requested 30min cannot tell a 60-minute close
+      // timeout from four 15-minute stages, and an unexplained gap is exactly the
+      // kind of number a later reader rounds back down to the requested one.
+      closeStages: stages,
+      enforcedMs: enforced(closeTimeoutMs),
+      elapsedMs: elapsedMs(),
+      // null, not Infinity: JSON.stringify turns Infinity into null anyway, and
+      // an append-only record must not depend on that coincidence — worse, a
+      // downstream `?? 0` on an Infinity would read as "no time left" (F6 class).
+      remainingMs: cap === null ? null : remainingMs(),
+    }),
+  };
+}

package/src/exits.js

@@ -9,8 +9,14 @@
 //     F45) and never gate intent (the F43 identical-refire trap: an allowed
 //     write that lands the same bytes is NOT a change).
 //   - a failing exit's detail is a MECHANICAL gap (a named wall, a count) —
-//     the genre that converts (F38/F46); details carry names and counts only,
-//     never file bodies (they ride the spine, which is append-only forever).
+//     the genre that converts (F38/F46). One detail is NOT names-and-counts:
+//     `json-valid` embeds `JSON.parse`'s own message and V8 quotes a window of
+//     the SOURCE inside it, so it can carry file bytes the worker chose. The
+//     CALLER scrubs, not this module: `runPlan` redacts every detail (the ONE
+//     `SECRET_PATTERNS` inventory) at the emission boundary, before anything
+//     rides the spine, which is append-only forever. `evalExits` is a public
+//     export — a direct caller wiring results into its own log applies its own
+//     redaction.
 //   - `check-passes` delegates through the `runCheck` seam the runner wires
 //     to the full runClose machinery; the evaluator itself never spawns. An
 //     unwired or throwing check fails CLOSED (the broken-close class: an

package/src/index.js

@@ -1,29 +1,35 @@
-// bareloop public surface — grows one rung at a time (PRD §10). N0: the
-// token-free spine. The five modules compose bottom-up: makeSpine feeds ralph,
-// interpret is the only config reader, extractRules distills a green run.
-// N1: the operator-owned job spec (job-v1) — validateJob is validate.js's
-// sibling (never an extension); jobSpecHash/checkApproval are the pure half
-// of human-signs-always (the N2 runner enforces).
-// N2: runJob — the runner: approval gate → primitive smoke → sealed priced
-// draft → sequential per-step loops under the ONE ledger (unpriced is never
-// free, F6) → the hitl step is the decision-ready escalation. Module 4: the
-// upstream ledger — spines fold into one append-only incident file; filing
-// stays human (suggestedAsk is a seed, never an auto-file).
+// bareloop public surface — grows one rung at a time (PRD §10). The modules
+// compose bottom-up: makeSpine feeds ralph, ralph is the wheel every layer is
+// made of, and runJob is the one entry.
+// The operator-owned job spec (job-v1) is the arbiter's rulebook — validateJob
+// and validatePlan are siblings, never extensions of each other; jobSpecHash /
+// checkApproval are the pure half of human-signs-always (the runner enforces).
+// runJob: approval gate → primitive smoke → the plan flow under the ONE ledger
+// (unpriced is never free, F6). The upstream ledger folds spines into one
+// append-only incident file; filing stays human (suggestedAsk is a seed, never
+// an auto-file).
+//
+// The config-v1 exports (`validateConfig`, `interpret`, `extractRules`,
+// `diffPaths`, `LOOP_SHAPES`, `SLOTS`, `VERBS`, `STALL_REDS`, `CLASSES`,
+// `STEP_MODES`) were REMOVED 2026-07-26 with the operator-authored steps[] path
+// (PRD v1.32) — a breaking change, and the reason for the version bump.
 
 export { makeSpine } from './spine.js';
 // CLOSE_FAULTS/scanSecrets: bareloop.context.md documents both as public API —
 // the exports make the adopter contract true (release review 2026-07-19; the
 // exports map admits only ".", so a deep import cannot reach them).
-export { ralph, runClose, CLOSE_FAULTS } from './ralph.js';
-export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from './validate.js';
-export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS, VERDICT_TYPES, LOCKED_VERDICTS } from './job.js';
+// runStages/checkMenu/STORE_VERBS: same reason, one rung later (review 2026-07-30)
+// — the CHANGELOG announces runStages async beside runClose and STORE_VERBS beside
+// the exported WRITE_VERBS, and bareloop.context.md points adopters at checkMenu by
+// name. Documented-but-unexported is a false contract; the additions are additive.
+export { ralph, runClose, runStages, CLOSE_FAULTS } from './ralph.js';
+export { globToPrefix, scanSecrets } from './validate.js';
+export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from './job.js';
 // Layer 2: the plan-v1 validator — the agent-authored plan doc's gate; the
 // two-doc split's third validator never happens (plan-v1 gates the PLAN, the
 // job spec stays the arbiter's only home).
-export { validatePlan, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from './plan.js';
+export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from './plan.js';
 export { snapshotScope, evalExits } from './exits.js';
 export { runPlan } from './planrun.js';
-export { interpret, STALL_REDS } from './interpret.js';
-export { extractRules, MAX_RULES, MAX_RULE_CHARS } from './extract.js';
 export { runJob } from './run.js';
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from './ledger.js';