bareloop 0.0.1 → 0.2.0

package/bareloop.context.md

@@ -0,0 +1,182 @@
+# bareloop — Integration Guide
+
+> **Current through N1** (job/close schema); API sections fill in as build-ladder rungs
+> land (PRD §10). What is settled — the boundary, the architecture, the refusals, the
+> constraints — is settled for good. Per LIBRARY_CONVENTIONS §3 this file ships with the
+> package and is the complete adopter contract; the README is only the pitch.
+
+## What this is
+
+**"Automate this job — I don't know the best workflow."** bareloop runs tasks that are
+repeated, long, and verifiable: you describe the job and its checkpoints; an agent authors
+the workflow scaffolding (a constrained, validated config — never freeform code); runs
+execute under an un-gameable outer gate; the scaffolding improves across runs through
+verdict-gated, run-as-executed inheritance with ledger-counted attribution. Every
+inherited rule carries the green that minted it and the contrast that attributed it.
+
+## What bareloop is and is not
+
+- **Is:** a place where repeated, verifiable jobs get better at themselves — job model,
+  authored-workflow lineages, verdict classes, inheritance with receipts, a panel to
+  operate it.
+- **Is not:** a general agent, a swarm, or an orchestrator framework. One-off or small
+  jobs are out of scope — that's a CLI session, not a bareloop job.
+
+## Minimal usage
+
+*TBD at N2 (first headless single-job loop). Will show: define a job (description,
+checkpoints + verdict classes, budget, cadence, provider) → run → watch the spine.*
+
+## All options
+
+Two documents, two validators — the schema is the option surface; config-red before
+tokens burn. The arbiter split is guarded from both sides by INEXPRESSIBILITY: the
+workflow config cannot say `close`/`provider`; the job spec cannot say
+`hooks`/`loop`/`memory`, any minting claim, or the shell-owned retry cap — all
+unknown-field reds.
+
+**Job spec (`schema: "job-v1"`, operator-owned — the arbiter's rulebook):**
+
+| field | shape | notes |
+|---|---|---|
+| `job` | kebab-case slug | |
+| `description` | non-empty string | |
+| `provider` | `anthropic-api` | menu; part of the lineage key by definition |
+| `conditions` | `{ providerPath?, closeVerbosity?, taskFraming?, scaffold? }` | declared keys only, string values — the environment label (consumed by the N3 lineage key; recorded on spines from run one) |
+| `cadence` | `{ unit: hour\|day\|week, every: 1..30 }` | validated now, consumed at N5 (Scheduler) |
+| `budgetUsd` | `0 < n <= shell cap` | ceiling chain: workflow ≤ job ≤ shell — each layer may tighten, never exceed |
+| `writeScope` | array of contained globs | the operator's outer fence; same containment law as the workflow layer, same code |
+| `steps` | array of `{ id, close, class }` | unique slug ids; every step names its close |
+| `escalation` | `{ mode: "decision-ready" }` | the pain channel is not optional |
+
+**Close types and the hierarchy** (a close is data, never code; verdict-class laundering
+is a named red `close-hierarchy`):
+
+| type | fields (exact — extras red) | legal class |
+|---|---|---|
+| `predicate` | `cmd`, `expect` (int exit code) | `hard` |
+| `gold` | `expected`, `compare: exact\|json-equal` | `hard` |
+| `rubric` | `criteria` | `soft` only — can never mint automatically |
+| `hitl` | `prompt` | `hitl` — a human IS the close |
+
+Red vocabulary (both validators): `parse-error`, `unknown-field`, `missing-required`,
+`invalid-value`, `bounds`, `duplicate-id`, `close-type`, `close-hierarchy`,
+`secret-literal`, `scope-escape`, `fence-invalid` (a malformed `jobWriteScope` fence — attributed to `jobWriteScope`, never the workflow config), plus the workflow-side verb reds (`verb-illegal`,
+`verb-placement`, `verb-params`, `slot-overflow`). The `secret-literal` sweep is
+defense-in-depth against known token shapes — env-only loading remains the law, not the
+sweep.
+
+## Public API
+
+*Landed through N0 (spine + shell + validator + interpreter + extractor). Still TBD:
+N1 (job/close schema), N2 (headless job loop), N3 (contrast-bit extractor), N4 (verdict
+classes), N5 (scheduler + budget ops), N6 (panel).*
+
+### `makeSpine(file)` → `emit(type, data?)` — `src/spine.js`
+
+Append-only JSONL event emitter bound to one file. `seq` monotonic per spine, `ts` stamped
+last. Consumers are pure listeners; nothing reads the file back. Returns each event as
+written.
+
+### `ralph({ middle, close, capRuns, emit })` → `'green' | 'escalated'` — `src/ralph.js`
+
+The dumb outer shell: `while close-red and under-cap: run the middle`. `close` is an argv
+whose exit code is truth (`runClose` is also exported); the red gap text feeds the next
+iteration. Escalations are decision-ready (category, options, spend); cap-halt is its own
+category, never merged with "wrong". A thrown middle is relayed by its `category`
+property (`cap-halt`, `gate-red`, …); an unnamed throw is `interpreter-red`. Close output
+is scrubbed at capture (an injected `redact`, wired to bareguard by `interpret` with the
+validators' full secret-shape inventory — Bearer/sk-/ghp_/github_pat_/AKIA/xox) so a
+secret a checked command echoes never enters the append-only spine or a worker prompt —
+a benign gap is byte-identical (secrets hard line; design law #7 intact).
+
+### `validateConfig(input, { shellCapUsd?, jobWriteScope? })` → `{ ok, reds, config }` — `src/validate.js`
+
+Deterministic schema-v1 predicate; never throws. Every failure is a named red
+`{ code, path, detail? }` — reds before tokens burn. Returns the parsed config on ok
+(single parse; `null` on any red). Pass the job spec's `writeScope` as `jobWriteScope`
+and every workflow scope must fit inside the fence (path-boundary aware: `src2` is not
+inside `src`) or it reds `scope-escape`; pass `min(shell cap, job budgetUsd)` as
+`shellCapUsd` to complete the ceiling chain. Verb vocabulary bound from litectx
+(`LOOP_SHAPES`, `SLOTS`, `VERBS` exported). `diffPaths(a, b)` returns changed JSON paths —
+the one-knob mutation checker.
+
+### `validateJob(input, { shellCapUsd? })` → `{ ok, reds, job }` — `src/job.js`
+
+The operator-owned sibling (never an extension) of `validateConfig`: validates a
+`job-v1` spec — see **All options** for the full schema, close types, and hierarchy.
+Never throws on JSON text or plain parsed data (the ingest contract); returns the
+parsed spec on ok, `null` on any red. Menus exported:
+`CLOSE_TYPES`, `CLASSES`, `CLASS_BY_CLOSE`, `GOLD_COMPARE`, `CADENCE_UNITS`,
+`PROVIDERS`, `CONDITION_KEYS`.
+
+### `jobSpecHash(job)` / `checkApproval(job, approvals)` — `src/job.js`
+
+The pure half of **human-signs-always**: an agent may draft a job spec, but no job runs
+until a human approves that exact version. `jobSpecHash` is sha256 over canonical JSON
+(key-order independent) — any edit changes the hash, so an edited spec is unapproved by
+construction. `checkApproval(job, approvals)` is a pure predicate over
+`{ specHash, signer, ts }` records; the approval record lives OUTSIDE the document it
+signs and is shell/human territory, never agent-writable. The N2 runner enforces it.
+Reserved spine vocabulary (V7, machinery-free until job #1 surfaces one):
+`coordination-red` — a failure between units (scope contention, step order, store
+races), never to be folded into worker/interpreter reds.
+
+### `interpret(configRaw, opts)` → `'green' | 'escalated' | 'config-red'` — `src/interpret.js`
+
+The only code that reads a config. Composes bareguard `Gate` (write scopes, USD budget),
+litectx (recall/compress/stash/remember hook ops), and the bareagent `Loop` under `ralph`.
+The provider and the close arrive from the shell, never the config. Optional `revisor`
+seam fires once after `STALL_REDS` consecutive close reds; the interpreter owns acceptance
+(arbiter-touch / cap-touch / validation reds), judged and installed on the candidate's
+PARSED form. Emits `config-final` — the run-as-executed config (design law #2) — on every
+run. Pass the job spec's fence as `jobWriteScope` (or `null`/omit for no fence): it is
+enforced HERE — the one choke point where a config becomes a Gate — on entry AND on every
+revision candidate, so a workflow scope outside the operator's fence reds before tokens.
+An enforcement belt resolves every scope and refuses to build a Gate that escapes the
+workdir, independent of validator correctness (law #1).
+
+### `extractRules({ config, provider, priorRules, revisionDiff? })` — `src/extract.js`
+
+One sealed LLM call distilling a lineage's rules from ledger facts after a green run.
+`MAX_RULES`/`MAX_RULE_CHARS` bounds enforced mechanically post-call, rejected whole.
+Malformed output is a red as data (`rules: null`) — the caller keeps prior rules.
+
+## Architecture
+
+Three layers. An **outer shell** (dumb, permanent): per-run budget cap via bareguard,
+retry cap, verdict collection, escalation routing — stateless across runs; nothing inside
+negotiates with it. An **emergent middle**: the authored workflow config — steps, per-step
+verdict class, memory binding, write scopes — schema-validated. A **floor**: append-only
+JSONL spine (single source for every UI), litectx store per job, per-run ledger. Built on
+the bare suite: bareagent, bareguard, litectx, barebrowse, baremobile — the full surface
+is disclosed to the authoring agent; only admitted verbs are callable per job.
+
+## What's NOT in bareloop, and why
+
+- **No agent-authored arbiters.** Closes, budgets, caps, merge/publish decisions live
+  outside the emergent part, permanently — the product's trust story depends on the gate
+  being un-gameable (adaptlearn's no-breach record is the evidence).
+- **No freeform code as scaffolding.** Configs are schema-validated; config-red before
+  tokens burn.
+- **No self-adjusted budgets — ever.** Hard cap per run, cap-not-estimate.
+- **No swarm / orchestrator frameworks; one process per run.** Fewer moving parts is the
+  point of the name.
+- **No local shims over baresuite gaps.** A missing/broken primitive is fixed upstream in
+  its own package and consumed by version bump.
+- **Merge stays human, forever.** For repo jobs the PR is the escalation artifact; a
+  human is the close.
+
+## Gotchas
+
+*TBD from real adopter friction; recorded here as they're found (repo-side friction goes
+to `docs/FINDINGS.md`).*
+
+## Constraints
+
+- **Node >= 20** (bareguard's floor governs the suite).
+- **Pure ESM + JSDoc**; generated `.d.ts` ship, never hand-written (LIBRARY_CONVENTIONS §2).
+- **Secrets load from the environment** and never enter the spine, configs, or ledger —
+  an append-only record that captures a key captures it forever.
+- **The spine is append-only** and the single source of truth; every UI (panel included)
+  is a pure observer of it.

package/package.json

@@ -1,10 +1,48 @@
 {
   "name": "bareloop",
-  "version": "0.0.1",
+  "version": "0.2.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.",
-  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "license": "Apache-2.0",
   "author": "hamr0",
-  "files": [],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "build:types": "tsc",
+    "prepublishOnly": "npm run build:types"
+  },
+  "dependencies": {
+    "bare-agent": "^0.26.2",
+    "bareguard": "^0.12.0",
+    "litectx": "^0.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hamr0/bareloop.git"
+  },
+  "homepage": "https://github.com/hamr0/bareloop#readme",
+  "files": [
+    "src/",
+    "types/",
+    "NOTICE",
+    "bareloop.context.md",
+    "CHANGELOG.md"
+  ],
   "keywords": [
     "agent",
     "workflow",

package/src/extract.js

@@ -0,0 +1,95 @@
+// The rules extractor — the lineage's inheritance representation. One sealed
+// LLM call after a green run distills/updates the lineage's rules list from
+// LEDGER FACTS only: the green config, the prior rules, and the revision diff
+// if the run recovered mid-run (the diff is the lesson — failure-transition
+// evidence, free in the event log). It never sees the close, the tests, or the
+// worker's code: rules describe the WORKFLOW, and showing the judge would open
+// the config-level fit-to-pass surface (PRD §2).
+//
+// N3 extends this with the contrast-bit rule (design law #3: verdict admits,
+// contrast attributes — the extractor may claim a knob only with ≥1
+// ledger-counted contrast bit; adaptlearn F16/F18 showed bare greens lose
+// working features). At N0 the extractor is the adaptlearn-proven distiller.
+//
+// Honesty invariants:
+// - One shot, no retry: malformed output is a red as DATA — the caller keeps
+//   the lineage's prior rules; there is never a silent empty inheritance.
+// - The ≤MAX_RULES/≤MAX_RULE_CHARS bound is stated to the model but ENFORCED
+//   mechanically post-call, and enforcement rejects whole — never trims
+//   (rejecting a half-applicable output beats silently part-applying it).
+// - Extractor spend is carried in costUsd and lands on the run's cost line —
+//   a representation whose upkeep rides free corrupts the ranking (design
+//   law #4: green gates, cost ranks).
+
+import { createRequire } from 'node:module';
+
+import { stripFences } from './text.js';
+
+const require = createRequire(import.meta.url);
+const { Loop } = require('bare-agent');
+
+export const MAX_RULES = 5;
+export const MAX_RULE_CHARS = 200;
+
+/**
+ * Distill/update a lineage's rules from one green run's ledger facts.
+ * @param {object} opts
+ * @param {object} opts.config the config that went green
+ * @param {object} opts.provider a bareagent provider — SHELL-owned, sealed
+ * @param {string[]|null} opts.priorRules the lineage's current rules, if any
+ * @param {string[]} [opts.revisionDiff] changed config paths, when the run recovered mid-run
+ * @returns {Promise<{rules: string[]|null, valid: boolean, reds: Array<object>, costUsd: number, raw: string}>}
+ */
+export async function extractRules({ config, provider, priorRules, revisionDiff }) {
+  const loop = new Loop({ provider, system: 'You emit exactly one JSON document and nothing else.' });
+  const prompt = `An automated coding workflow just completed a run that PASSED its hidden judgement.
+You maintain this workflow lineage's inherited rules: short, general lessons about how to
+configure the workflow for this task family. You never see the tasks' tests or code — only
+workflow facts.
+
+The config that went green:
+${JSON.stringify(config, null, 2)}
+${revisionDiff && revisionDiff.length > 0 ? `
+This run stalled and recovered after revising these config paths mid-run (the revision that
+turned red into green — strong evidence about what mattered):
+${revisionDiff.join(', ')}
+` : ''}${priorRules && priorRules.length > 0 ? `
+The lineage's current rules — revise them: keep what still holds, drop what this run
+contradicts, add at most what this run actually evidences:
+${JSON.stringify(priorRules, null, 2)}
+` : `
+The lineage has no rules yet. Write only what this single run actually evidences.
+`}
+Output ONLY a JSON array of strings: at most ${MAX_RULES} rules, each at most ${MAX_RULE_CHARS}
+characters. No markdown fences, no commentary.`;
+
+  // Never throw (the module contract): a provider blip during post-green
+  // extraction must not lose the green run's bookkeeping — it degrades to a
+  // red as data and the caller keeps the lineage's prior rules. Loop defaults
+  // throwOnError: true, so a transient 500 WOULD reject without this.
+  let r;
+  try {
+    r = await loop.run([{ role: 'user', content: prompt }]);
+  } catch (e) {
+    return { rules: null, valid: false, reds: [{ code: 'provider-error', detail: String(/** @type {Error} */ (e).message ?? e) }], costUsd: 0, raw: '' };
+  }
+  const costUsd = r.metrics?.costUsd ?? r.cost ?? 0;
+  const raw = stripFences(r.text ?? '');
+  if (r.error) {
+    return { rules: null, valid: false, reds: [{ code: 'provider-error', detail: String(r.error) }], costUsd, raw };
+  }
+  /** @type {(code: string, detail: string) => {rules: null, valid: false, reds: Array<object>, costUsd: number, raw: string}} */
+  const red = (code, detail) => ({ rules: null, valid: false, reds: [{ code, detail }], costUsd, raw });
+
+  let rules;
+  try { rules = JSON.parse(raw); } catch (e) {
+    return red('parse-error', String(/** @type {Error} */ (e).message));
+  }
+  if (!Array.isArray(rules) || rules.length === 0 || !rules.every((x) => typeof x === 'string')) {
+    return red('rules-shape', 'expected a non-empty JSON array of strings');
+  }
+  if (rules.length > MAX_RULES || rules.some((x) => x.length > MAX_RULE_CHARS)) {
+    return red('rules-bound', `max ${MAX_RULES} rules of ${MAX_RULE_CHARS} chars — rejected whole, never trimmed`);
+  }
+  return { rules, valid: true, reds: [], costUsd, raw };
+}

package/src/index.js

@@ -0,0 +1,13 @@
+// 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).
+
+export { makeSpine } from './spine.js';
+export { ralph, runClose } from './ralph.js';
+export { validateConfig, diffPaths, globToPrefix, LOOP_SHAPES, SLOTS, VERBS } from './validate.js';
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS } from './job.js';
+export { interpret, STALL_REDS } from './interpret.js';
+export { extractRules, MAX_RULES, MAX_RULE_CHARS } from './extract.js';

package/src/interpret.js

@@ -0,0 +1,261 @@
+// The interpreter — the ONLY code that reads a workflow config (PRD §4's
+// emergent middle, executed). It composes the suite, never invents: litectx is
+// the store, bareguard is the leash, bareagent is the worker loop (design law
+// #10). The provider arrives from the SHELL (never the config — it is
+// arbiter-adjacent), and the close never runs here: the shell runs it and
+// feeds the verdict back as `gap`.
+//
+// Two traps this encodes, both paid for in adaptlearn: `onLlmResult` is a Loop
+// CONSTRUCTOR option — passed to run() it is silently ignored and the budget
+// axis goes blind (F3); and a budget-exhausted gate deny must surface as
+// cap-halt, its own category, never a generic error (design law #8).
+
+import { createRequire } from 'node:module';
+import { writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { Gate, redact } from 'bareguard';
+import { LiteCtx, compress } from 'litectx';
+import { validateConfig, diffPaths, globToPrefix, SECRET_PATTERNS } from './validate.js';
+import { ralph } from './ralph.js';
+
+/** @typedef {Error & {category?: string}} CategorizedError the failure map's carrier: ralph relays by `category` */
+
+// consecutive close reds that count as a stall; one revision per run
+export const STALL_REDS = 2;
+
+const require = createRequire(import.meta.url);
+const { Loop, wireGate, HaltError } = require('bare-agent');
+
+import { stripFences } from './text.js';
+
+/** @typedef {{body?: string|null, text?: string|null}} RecallHit litectx recall hit — body present only with `{body: true}` */
+
+const PERSONA = 'You are a senior engineer. Reply with ONLY the complete contents of the requested JavaScript file — no markdown fences, no commentary. ESM.';
+
+/**
+ * Execute a workflow config against one task under the dumb shell.
+ *
+ * @param {object|string} configRaw schema v1 config (object or raw JSON text)
+ * @param {object} opts
+ * @param {string} opts.task implement instruction shown to the worker
+ * @param {string} opts.target absolute path the artifact is written to
+ * @param {string[]} opts.close argv whose exit code is truth (shell-owned)
+ * @param {string} opts.workdir run directory (litectx root, gate audit, scope base)
+ * @param {number} opts.capRuns shell iteration budget; the config may tighten via loop.maxIterations, never exceed
+ * @param {(type: string, data?: object) => object} opts.emit spine emitter
+ * @param {object} opts.provider a bareagent provider — SHELL-owned binding (adaptlearn F8: an unsealed binding is a gate bypass)
+ * @param {number} [opts.shellCapUsd=2] the shell's USD cap; config budgetUsd is clamped by validation
+ * @param {string[]} [opts.jobWriteScope] the job spec's outer write fence (operator law,
+ *        job-v1) — enforced HERE, the one choke point where a config becomes a Gate:
+ *        every workflow scope must fit inside it (scope-escape config-red otherwise),
+ *        on entry validation and on every revision candidate alike
+ * @param {(o: {config: object, gaps: string[], policy: any, onLlmResult: any}) => Promise<{candidate: object|null, parseError?: string|null, costUsd?: number}>} [opts.revisor]
+ *        optional mid-run revision seam. Fires ONCE per run after STALL_REDS consecutive
+ *        close reds. The interpreter — never the revisor — owns acceptance: the candidate
+ *        must validate, and gate/escalation/loop.maxIterations must be unchanged
+ *        (arbiter-touch / cap-touch revision-reds otherwise; the run continues on the old
+ *        config). Revisor spend rides the run's own gate handlers — same budget axis as
+ *        the worker.
+ * @returns {Promise<'green'|'escalated'|'config-red'>}
+ */
+export async function interpret(configRaw, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd = 2, jobWriteScope, revisor }) {
+  // Normalize ONCE: a trailing slash or a relative spelling must mean the same
+  // directory everywhere below — the enforcement belt compares string prefixes,
+  // and "/run/" vs "/run" would false-red every legal scope (release review).
+  workdir = resolve(workdir);
+  const v = validateConfig(configRaw, { shellCapUsd, jobWriteScope });
+  emit('config-validate', { ok: v.ok, reds: v.reds });
+  if (!v.ok) {
+    for (const r of v.reds) emit('config-red', r);
+    emit('run-end', { outcome: 'config-red', iterations: 0 });
+    return 'config-red';
+  }
+  let config = /** @type {any} */ (v.config); // single parse — validateConfig returns the parsed config on ok
+
+  const lc = new LiteCtx({ root: workdir });
+  // Enforcement belt (law #1, un-gameable gate): resolve every scope and prove
+  // it stays under workdir BEFORE building the Gate. validateConfig already
+  // rejects escaping scopes, so this is defense in depth — a future globToPrefix
+  // regression (a spelling that normalizes to an absolute path) can never reach
+  // a live Gate fence. The interpreter and the validator must never disagree (F9).
+  const resolvedScopes = config.gate.writeScope.map((/** @type {string} */ g) => resolve(workdir, globToPrefix(g)));
+  // equality counts as escaped: no legal scope resolves to workdir itself (the
+  // close lives there), so a scope normalizing to ''/'.' is a regression, not a grant
+  const escaped = resolvedScopes.filter((/** @type {string} */ abs) => !abs.startsWith(workdir + sep));
+  if (escaped.length) {
+    for (const abs of escaped) emit('config-red', { code: 'scope-escape', path: 'gate.writeScope', detail: `resolved scope ${abs} escapes the run directory` });
+    emit('run-end', { outcome: 'config-red', iterations: 0 });
+    return 'config-red';
+  }
+  const gate = new Gate({
+    // bareguard fs.writeScope is prefix-containment, not glob (adaptlearn F4); globToPrefix
+    // is the ONE transform shared with the validator's legality rule — mid-path wildcards
+    // and workdir-escaping scopes were already rejected up front (adaptlearn F9, law #1).
+    fs: { writeScope: resolvedScopes },
+    budget: { maxCostUsd: config.gate.budgetUsd },
+    limits: { maxTurns: 8 * (capRuns + 1) },
+    audit: { path: join(workdir, 'gate-audit.jsonl') },
+    humanChannel: async () => ({ decision: 'terminate' }), // no human mid-run: a tripped cap terminates → decision-ready escalation
+  });
+  await gate.init();
+  const { policy, onLlmResult } = wireGate(gate);
+  const loop = new Loop({ provider, system: PERSONA, policy, onLlmResult });
+
+  /** @param {string} slot */
+  const slotOps = (slot) => config.hooks?.[slot] ?? [];
+  /** @param {{kinds?: string[]}} op */
+  const recallKinds = (op) => op.kinds ?? config.memory.recall?.kinds ?? ['fact'];
+
+  /** @param {string} prompt */
+  async function ask(prompt) {
+    let r;
+    try {
+      r = await loop.run([{ role: 'user', content: prompt }]);
+    } catch (e) {
+      if (e instanceof HaltError) /** @type {CategorizedError} */ (e).category = 'cap-halt'; // belt: bare-agent's contract could change
+      throw e;
+    }
+    // bare-agent NEVER throws HaltError out of run() — a governance halt comes
+    // back as an error RETURN ({text: '', error: 'halt:<rule>'}; loop.js: "no
+    // throw even when throwOnError: true"). Read it, or the failure map goes
+    // blind and a cap story masquerades as a worker result (design law #8).
+    if (r.error) {
+      const err = /** @type {CategorizedError} */ (new Error(`worker loop: ${r.error}`));
+      err.category = r.error.startsWith('halt:') ? 'cap-halt' : 'interpreter-red';
+      throw err;
+    }
+    return r;
+  }
+
+  /**
+   * @param {string} slot
+   * @param {{iteration?: number, gap?: string, context?: any}} o
+   */
+  async function runOps(slot, { iteration, gap, context }) {
+    for (const op of slotOps(slot)) {
+      if (op.op === 'recall') {
+        /** @type {RecallHit[]} */
+        const hits = [];
+        for (const kind of recallKinds(op)) {
+          hits.push(...await lc.recall(task, { kind, n: op.k ?? config.memory.recall?.k ?? 5, body: true }));
+        }
+        context.text = hits.map((h) => h.body ?? h.text ?? '').filter(Boolean).join('\n');
+        context.level = null;
+        emit('hook-op', { slot, op: 'recall', hits: hits.length, iteration });
+      } else if (op.op === 'compress') {
+        const level = op.level ?? config.memory.compressLevel ?? 'verbatim';
+        if (context.text) context.text = await compress({ text: context.text, format: 'js' }, { level });
+        emit('hook-op', { slot, op: 'compress', level, iteration });
+      } else if (op.op === 'stash') {
+        if (gap) lc.stash(`gap-${iteration}`, gap);
+        emit('hook-op', { slot, op: 'stash', iteration });
+      } else if (op.op === 'remember') {
+        await lc.remember(`green-${iteration ?? 'final'}-${target.split('/').at(-1)}`, readFileSync(target, 'utf8'), { kind: op.kind ?? 'fact' });
+        emit('hook-op', { slot, op: 'remember' });
+      }
+    }
+  }
+
+  // Mid-run revision: interpreter-owned acceptance — a revisor cannot vouch for
+  // its own output. The gate is already constructed and the iteration budget
+  // already snapshotted, so gate/escalation (arbiter) and loop.maxIterations
+  // (cap) must be byte-identical; anything else that validates is a legal
+  // free-axis revision.
+  /** @param {any} candidate
+   *  @returns {{ red: {code: string, reds?: object[]} } | { red?: undefined, config: any }} */
+  const acceptRevision = (candidate) => {
+    if (!candidate) return { red: { code: 'parse-error' } };
+    const cv = validateConfig(candidate, { shellCapUsd, jobWriteScope });
+    if (!cv.ok) return { red: { code: 'validation', reds: cv.reds } };
+    // judged and installed on the PARSED form (single-parse contract) — a
+    // string candidate compared raw would false-red arbiter-touch (its .gate
+    // is undefined), and installing it raw would crash every later read
+    const cand = /** @type {any} */ (cv.config);
+    if (JSON.stringify(cand.gate) !== JSON.stringify(config.gate)
+        || JSON.stringify(cand.escalation) !== JSON.stringify(config.escalation)) {
+      return { red: { code: 'arbiter-touch' } };
+    }
+    if (cand.loop?.maxIterations !== config.loop.maxIterations) return { red: { code: 'cap-touch' } };
+    return { config: cand };
+  };
+
+  /** @type {string[]} */
+  const gaps = [];
+  let revised = false;
+  /**
+   * @param {number} iteration
+   * @param {string} [gap]
+   */
+  const middle = async (iteration, gap) => {
+    if (gap) gaps.push(gap);
+    if (revisor && !revised && gaps.length >= STALL_REDS) {
+      emit('stall-detected', { iteration, consecutiveReds: gaps.length });
+      revised = true; // one revision per run, spent even if rejected
+      let rv;
+      try {
+        // the run's own gate handlers ride along: revisor spend hits the same
+        // budget axis as the worker; a budget halt mid-revision is a cap story,
+        // not a revision bug
+        rv = await revisor({ config, gaps: [...gaps], policy, onLlmResult });
+      } catch (e) {
+        if (e instanceof HaltError) /** @type {CategorizedError} */ (e).category = 'cap-halt';
+        throw e;
+      }
+      const rr = acceptRevision(rv.candidate);
+      if (rr.red) {
+        emit('revision-red', { iteration, ...rr.red, detail: rv.parseError ?? undefined, costUsd: rv.costUsd ?? 0 });
+      } else {
+        emit('revision-accepted', { iteration, changedPaths: diffPaths(config, rr.config), costUsd: rv.costUsd ?? 0 });
+        config = rr.config;
+      }
+    }
+    if (gap) await runOps('after-red', { iteration, gap, context: {} });
+    const context = {};
+    await runOps('before-attempt', { iteration, context });
+    const parts = [task, context.text && `Possibly relevant notes:\n${context.text}`, gap && `Previous attempt failed the test suite:\n${gap}`];
+
+    if (config.loop.shape === 'plan') {
+      // plan-then-execute: one call to decompose, one to implement following the plan
+      const p = await ask([`Produce a SHORT numbered implementation plan (2-4 steps) for this task. Plan only, no code.`, ...parts.slice(1), parts[0]].filter(Boolean).join('\n\n'));
+      emit('worker-plan', { iteration, costUsd: p.metrics?.costUsd ?? p.cost ?? null }); // metrics.costUsd carries the honest null when unpriced; cost sums priced rounds only
+      parts.push(`Follow this plan:\n${p.text}`);
+    }
+    const r = await ask(parts.filter(Boolean).join('\n\n'));
+    emit('worker-result', { iteration, costUsd: r.metrics?.costUsd ?? r.cost ?? null, tokens: r.usage?.outputTokens ?? null });
+
+    const decision = await gate.check({ type: 'write', path: target, args: { bytes: r.text.length } });
+    if (decision.outcome !== 'allow') {
+      const err = /** @type {CategorizedError} */ (new Error(`gate ${decision.outcome} write to ${target} (${decision.rule ?? 'no rule'})`));
+      err.category = decision.severity === 'halt' ? 'cap-halt' : 'gate-red';
+      throw err;
+    }
+    writeFileSync(target, stripFences(r.text));
+    emit('artifact-written', { iteration, path: target });
+  };
+
+  // the config may tighten the shell's iteration budget, never exceed it (mirrors budgetUsd)
+  const effectiveCap = Math.min(capRuns, config.loop.maxIterations ?? capRuns);
+  // Secrets never enter the spine (hard line): the shell scrubs close output at
+  // the source with bareguard's redactor — BG-1 defaults (Bearer/sk-…) PLUS the
+  // validator's whole shape inventory (SECRET_PATTERNS), so redaction can never
+  // pass a shape detection reds (a git close echoing a ghp_ token was the gap).
+  // Injected here (the layer that owns bareguard) so ralph stays stdlib-only and
+  // the scrub is a fixed shell primitive, not an emergent component (V4 holds).
+  const outcome = await ralph({ middle, close, capRuns: effectiveCap, emit, redact: (/** @type {string} */ s) => redact(s, { patterns: SECRET_PATTERNS }) });
+  if (outcome === 'green') {
+    // The close already passed — a retention hiccup must not un-green a real
+    // green (it would corrupt the learning curve). It degrades loudly:
+    // retention-red on the spine means this green mints NO inheritance, but
+    // the delivery stands (adaptlearn F5).
+    try {
+      await runOps('on-green', {});
+    } catch (e) {
+      emit('retention-red', { category: 'retention-red', detail: String(/** @type {Error} */ (e).message || e) });
+    }
+  }
+  // Design law #2 (adaptlearn F18): the run-as-executed record. A mid-run
+  // revision changes `config`; without this event the revised config dies with
+  // the run and every inheritance channel reads only the config-as-authored.
+  emit('config-final', { config, revised });
+  return outcome;
+}