@haiyangbg/buildbeat 2.0.0-beta.3 → 2.0.0-beta.5

package/src/v2/domain/event-registry.js

@@ -33,6 +33,7 @@ export const EVENT_REGISTRY = {
   TRANSITION: ["from", "to", "cause"],
   FAILURE_FINGERPRINT: ["step", "command", "exitCode", "errorDigest", "diffDigest"],
   BUDGET_CONSUMED: ["kind", "amount", "remaining"],
+  BUDGET_EXTENDED: ["step", "amount", "maxAttempts"],
   HUMAN_REQUESTED: ["transition", "subject", "reasons"],
   DECISION_RECORDED: ["decision", "transition", "subject", "decisionRef"],
   APPROVAL_STALE: ["approvalRef", "changed"],

package/src/v2/engine/reducer.js

@@ -23,6 +23,8 @@ export function initialState() {
     fingerprints: [],
     consecutiveSameFailure: 0,
     budgets: {},
+    budgetExtensions: {},
+    workReviewGrants: 0,
     pendingHuman: null,
     decisions: [],
     approvals: [],
@@ -107,7 +109,12 @@ export function applyEvent(state, event) {
           `step ${data.step} expected attempt ${expectedAttempt}, got ${data.attempt}`,
         );
       }
-      next.steps[data.step] = { status: "RUNNING", attempts: data.attempt, detail: null };
+      next.steps[data.step] = {
+        status: "RUNNING",
+        attempts: data.attempt,
+        detail: null,
+        infraAttempts: state.steps[data.step]?.infraAttempts ?? 0,
+      };
       next.currentStep = data.step;
       break;
     }
@@ -120,6 +127,11 @@ export function applyEvent(state, event) {
       }
       next.steps[data.step].status = data.status === "succeeded" ? "SUCCEEDED" : "FAILED";
       next.steps[data.step].detail = data.status;
+      if (data.infra === true) {
+        // A worker-infrastructure failure (backend outage, timeout, garbage
+        // output, exit 75) is not charged to the step's budget.
+        next.steps[data.step].infraAttempts = (step.infraAttempts ?? 0) + 1;
+      }
       next.currentStep = null;
       break;
     }
@@ -143,6 +155,8 @@ export function applyEvent(state, event) {
         ...(data.suppressedFingerprints
           ? { suppressedFingerprints: data.suppressedFingerprints }
           : {}),
+        ...(data.cacheKey ? { cacheKey: data.cacheKey } : {}),
+        ...(data.reused ? { reused: data.reused } : {}),
       });
       break;
     }
@@ -166,6 +180,19 @@ export function applyEvent(state, event) {
       next.budgets[data.kind] = { consumed: consumed + data.amount, remaining: data.remaining };
       break;
     }
+    case "BUDGET_EXTENDED": {
+      // A human approving resume-<step> after its budget ran out grants
+      // exactly one more attempt; the grant is a ledger fact, not a config
+      // edit, so the effective cap is replayable.
+      if (data.scope === "work") {
+        // Work-level review cap (budgets.reviewRoundsPerWork) lifted once by
+        // a human for this run.
+        next.workReviewGrants = (state.workReviewGrants ?? 0) + data.amount;
+      } else {
+        next.budgetExtensions[data.step] = (state.budgetExtensions?.[data.step] ?? 0) + data.amount;
+      }
+      break;
+    }
     case "HUMAN_REQUESTED": {
       next.pendingHuman = {
         transition: data.transition,
@@ -192,6 +219,7 @@ export function applyEvent(state, event) {
           transition: data.transition,
           subject: data.subject,
           stale: false,
+          ...(data.resumeAt ? { resumeAt: data.resumeAt } : {}),
         });
       }
       next.pendingHuman = null;

package/src/v2/engine/workflow.js

@@ -27,7 +27,8 @@ const TOP_FIELDS = new Set([
   "policies",
   "budgets",
 ]);
-const STEP_FIELDS = new Set(["id", "worker", "optional", "requiredWhen", "readonly"]);
+const STEP_FIELDS = new Set(["id", "worker", "optional", "requiredWhen", "readonly", "grade"]);
+const EVIDENCE_GRADES = new Set(["L0", "L1", "L2", "L3", "L4"]);
 const TRANSITION_FIELDS = new Set(["from", "on", "to"]);
 
 function rejectUnknownFields(object, allowed, where) {
@@ -82,6 +83,11 @@ export function parseWorkflow(text) {
     if (raw.readonly !== undefined && typeof raw.readonly !== "boolean") {
       throw new WorkflowError(`step ${id} readonly must be a boolean`);
     }
+    // Evidence grade a step's command evidence is recorded at (iteration 08:
+    // release readbacks run against the real environment and are L4).
+    if (raw.grade !== undefined && !EVIDENCE_GRADES.has(raw.grade)) {
+      throw new WorkflowError(`step ${id} grade must be one of L0-L4`);
+    }
     stepIds.add(id);
     steps.push({
       id,
@@ -89,6 +95,7 @@ export function parseWorkflow(text) {
       optional: raw.optional ?? false,
       requiredWhen: raw.requiredWhen ?? null,
       readonly: raw.readonly ?? false,
+      grade: raw.grade ?? "L2",
     });
   }
 

package/src/v2/evidence/collector.js

@@ -17,21 +17,32 @@ export function collectCommandEvidence({
   kind = "command",
   grade = "L2",
   coverage = null,
+  redact = [],
 }) {
   const logsDir = join(runtimeDir, "runs", runId, "logs");
   mkdirSync(logsDir, { recursive: true });
   const logName = `${step}-${attempt}.log`;
   const logPath = join(logsDir, logName);
+  // Redaction (iteration 08, C6): patterns from the run config are applied
+  // to worker output before it becomes evidence. The digest binds the
+  // redacted text — what is on disk is what was hashed.
+  const scrub = (text) => {
+    let out = String(text ?? "");
+    for (const pattern of redact) {
+      out = out.replace(pattern, "<REDACTED>");
+    }
+    return out;
+  };
   const logBody = [
-    `command: ${execResult.command}`,
+    `command: ${scrub(execResult.command)}`,
     `exitCode: ${execResult.exitCode}`,
     `signal: ${execResult.signal}`,
     `timedOut: ${execResult.timedOut}`,
     `spawnError: ${execResult.spawnError}`,
     "--- stdout ---",
-    execResult.stdout,
+    scrub(execResult.stdout),
     "--- stderr ---",
-    execResult.stderr,
+    scrub(execResult.stderr),
   ].join("\n");
   writeFileSync(logPath, logBody, "utf8");
   const digest = `sha256:${createHash("sha256").update(logBody, "utf8").digest("hex")}`;

package/src/v2/presets/release-readback.yaml

@@ -0,0 +1,36 @@
+# Release readback lane (iteration 08, C8). The kernel still has no deploy
+# capability (invariant 20): every production action stays a human's. What
+# this lane fixes is the bookkeeping around it — a pilot go-live was
+# ledgered by hand as forty "step N readback" commits. Here each step is a
+# read-only command that proves the world is in the expected state; every
+# failure stops for a human (maxAttempts 1, no fix edge), and evidence is
+# graded L4 because it was read from the real environment.
+#
+# Shape: preflight (before the action) → [human performs the action; the
+# risk preset "release" stops here] → apply-readback (proves it happened) →
+# observe (proves it is healthy) → wait-close (human closes the window).
+kind: workflow
+version: 1
+name: release-readback
+entry: preflight
+steps:
+  - id: preflight
+    worker: readback
+    readonly: true
+    grade: L4
+  - id: apply-readback
+    worker: readback
+    readonly: true
+    grade: L4
+  - id: observe
+    worker: observe
+    readonly: true
+    grade: L4
+  - id: wait-close
+terminal:
+  - wait-close
+budgets:
+  maxAttempts:
+    preflight: 1
+    apply-readback: 1
+    observe: 1

package/src/v2/presets/risk/release.yaml

@@ -0,0 +1,21 @@
+# Release lane (iteration 08, C8): pairs with the release-readback workflow.
+# Automation stops before apply-readback — that pause is where the human
+# performs the production action — and the window may only close behind L4
+# evidence read from the real environment. (No finding floor: the lane has
+# no reviewer step, and a rule that cannot be satisfied is not a gate.)
+kind: risk-preset
+version: 1
+name: release
+stopAt:
+  - apply-readback
+policies:
+  - kind: policy
+    version: 1
+    name: close-evidence-floor
+    type: transition
+    appliesTo: enter-wait-close
+    enforcement: LOCAL_ENFORCED
+    rule:
+      evidence.exists:
+        kind: command
+        minGrade: L4

package/src/v2/runtime/cache.js

@@ -0,0 +1,124 @@
+// Verification reuse and incremental review (iteration 08, C7).
+//
+// Reuse: a verify step whose input is byte-identical to one that already
+// passed — same tree, same worker command, same envelope — is not re-run; the
+// earlier evidence is referenced and the reuse is visible in the ledger
+// (`reused`) and in status. Only *passed* results are ever reused; a failure
+// always runs again. Real number: the deploy campaign's envelope-side cache
+// cut verify from 25 to 13 minutes per round.
+//
+// Incremental review: a reviewer is told which candidate the last review
+// looked at (when it is an ancestor of the current one) so it can focus on
+// the delta instead of re-reading the whole change every round.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { canonicalJson } from "../storage/event-ledger.js";
+
+function git(cwd, args) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+export function treeHash(worktreePath) {
+  return git(worktreePath, ["rev-parse", "HEAD^{tree}"]);
+}
+
+export function cacheKey({ tree, worker, adapterSpec, adapterName, envelopeDigest }) {
+  const body = canonicalJson({
+    tree,
+    worker,
+    adapter: adapterSpec ?? adapterName ?? null,
+    envelope: envelopeDigest ?? null,
+  });
+  return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+
+function eachLedger(repoRoot, { excludeRun = null } = {}) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const out = [];
+  if (!existsSync(runsDir)) {
+    return out;
+  }
+  for (const entry of readdirSync(runsDir).sort()) {
+    if (entry === excludeRun) {
+      continue;
+    }
+    const path = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(path)) {
+      continue;
+    }
+    const ledger = EventLedger.open(path);
+    if (ledger.state.run) {
+      out.push(ledger);
+    }
+  }
+  return out;
+}
+
+// Latest passed command evidence carrying this cache key, across the
+// repository's runs (the current run included: a re-verify after an
+// unrelated fix step on the same tree is the common case).
+export function findReusableEvidence(repoRoot, key) {
+  let best = null;
+  for (const ledger of eachLedger(repoRoot)) {
+    for (const event of ledger.events) {
+      if (
+        event.type === "EVIDENCE_RECORDED" &&
+        event.data.cacheKey === key &&
+        event.data.status === "passed" &&
+        event.data.kind === "command" &&
+        !event.data.reused
+      ) {
+        if (!best || event.ts > best.ts) {
+          best = { run: ledger.state.run.id, evidenceRef: event.data.evidenceRef, digest: event.data.digest, grade: event.data.grade, ts: event.ts };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+// The most recent review evidence for this work whose subject is an ancestor
+// of (and not equal to) the current head — the anchor for an incremental
+// review. Null when there is no such review.
+export function lastReviewedCandidate(repoRoot, workId, worktreePath, head) {
+  let best = null;
+  for (const ledger of eachLedger(repoRoot)) {
+    if (ledger.state.run.work !== workId) {
+      continue;
+    }
+    for (const event of ledger.events) {
+      if (event.type !== "EVIDENCE_RECORDED" || event.data.kind !== "review") {
+        continue;
+      }
+      const subject = event.data.subject;
+      if (!subject || subject === head) {
+        continue;
+      }
+      if (best && event.ts <= best.ts) {
+        continue;
+      }
+      let ancestor = false;
+      try {
+        execFileSync("git", ["-C", worktreePath, "merge-base", "--is-ancestor", subject, head], { stdio: "ignore" });
+        ancestor = true;
+      } catch {
+        ancestor = false;
+      }
+      if (ancestor) {
+        best = { candidate: subject, run: ledger.state.run.id, evidenceRef: event.data.evidenceRef, ts: event.ts };
+      }
+    }
+  }
+  if (!best) {
+    return null;
+  }
+  return { candidate: best.candidate, run: best.run, evidenceRef: best.evidenceRef, range: `${best.candidate}..${head}` };
+}

package/src/v2/runtime/decisions.js

@@ -185,6 +185,86 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
   }
 }
 
+// A human (or the driving session) supplies the candidate: the fix was made
+// by hand in the run's worktree and committed, so the fixer step has nothing
+// to do. The pending request is answered with the adopted commit as its
+// subject and the run resumes at `resumeAt` (verify, by convention). Real
+// incident: hand fixes inside a run cost a no-op fixer and an extra verify
+// each time (a frontend run reached verify #5 and fix #3 for three hand
+// fixes). The commit must already be the worktree HEAD: git is read back,
+// the claim is not trusted.
+export function adoptCandidate(repoRoot, runId, { sha, by = "human", resumeAt, ts } = {}) {
+  if (!sha || typeof sha !== "string" || sha.length < 7) {
+    throw new DecisionError("adopt requires a commit sha (at least 7 characters)");
+  }
+  if (!resumeAt) {
+    throw new DecisionError("adopt requires the step to resume at (resumeAt)");
+  }
+  const ledger = openWaiting(repoRoot, runId);
+  const pending = ledger.state.pendingHuman;
+  if (pending.kind === "final-decision") {
+    throw new DecisionError("adopt is for a run waiting before fix/verify, not at the merge decision");
+  }
+  acquireLock(repoRoot, runId);
+  try {
+    const bound = ledger.state.workspaces[runId];
+    const worktreePath = bound ? resolveRepoRef(repoRoot, bound.worktreePath) : null;
+    if (!bound || !existsSync(worktreePath)) {
+      throw new DecisionError(`worktree missing for ${runId}; cannot adopt a candidate`);
+    }
+    const tree = readback(worktreePath);
+    if (tree.dirty) {
+      throw new DecisionError("worktree is dirty; commit the hand fix before adopting it");
+    }
+    if (!tree.head.startsWith(sha)) {
+      throw new DecisionError(`worktree HEAD is ${tree.head}, not ${sha}; adopt what git reads back`);
+    }
+    const when = ts ?? new Date().toISOString();
+    const lastEvidence = ledger.state.evidence[ledger.state.evidence.length - 1];
+    if (bound.candidate !== tree.head) {
+      ledger.append({
+        type: "CANDIDATE_PINNED",
+        actor: { kind: "human", id: by },
+        ts: when,
+        data: { workspaceId: runId, base: bound.base, candidate: tree.head, adopted: true },
+      });
+    }
+    const subject = {
+      candidate: tree.head,
+      planDigest: ledger.state.run.planDigest,
+      evidenceDigest: lastEvidence?.digest ?? "UNVERIFIED",
+    };
+    const decisionRef = `D-${runId}-${ledger.state.decisions.length + 1}`;
+    ledger.append({
+      type: "DECISION_RECORDED",
+      actor: { kind: "human", id: by },
+      ts: when,
+      data: {
+        decision: "approved",
+        transition: pending.transition,
+        subject,
+        decisionRef,
+        adopted: tree.head,
+        resumeAt,
+      },
+    });
+    recordDecisionFile(repoRoot, ledger.state.run.work, {
+      ts: when,
+      run: runId,
+      decisionRef,
+      decision: "approved",
+      transition: pending.transition,
+      subject,
+      by,
+      adopted: tree.head,
+      resumeAt,
+    });
+    return { adopted: tree.head, decisionRef, transition: pending.transition, resumeAt, state: ledger.state };
+  } finally {
+    releaseLock(repoRoot, runId);
+  }
+}
+
 // Accepts a work artifact (plan, intent, spec) by binding a decision to the
 // file's current digest in the Git plane. If the file changes afterwards,
 // artifact.accepted evaluates false again — acceptance cannot go stale

package/src/v2/runtime/env-contract.js

@@ -49,8 +49,42 @@ export function checkRequires(requires) {
   const problems = [];
   const checked = [];
   for (const entry of requires ?? []) {
+    // Probe entries (iteration 08, C10): an environment fact that is not a
+    // binary version — "Redis answers PING on the target", "python on the
+    // host is >= 3.9" — expressed as a shell command whose exit code (and
+    // optionally output) must match. Absorbed from the first-proof rerun:
+    // Redis < 7 and Python 3.6 on the target burned a window each because
+    // nothing checked them before the run.
+    if (entry && typeof entry === "object" && typeof entry.probe === "string" && entry.probe.length > 0) {
+      const label = entry.name ?? entry.probe;
+      const run = spawnSync("bash", ["-lc", entry.probe], { encoding: "utf8", timeout: entry.timeoutMs ?? 30_000 });
+      if (run.error) {
+        problems.push(`${label}: probe could not run (${run.error.code ?? run.error.message})`);
+        continue;
+      }
+      const output = `${run.stdout ?? ""}\n${run.stderr ?? ""}`;
+      if (run.status !== 0) {
+        problems.push(`${label}: probe exited ${run.status}${output.trim() ? ` — ${output.trim().split("\n").slice(-1)[0].slice(0, 160)}` : ""}`);
+        continue;
+      }
+      if (entry.expect !== undefined) {
+        let matcher;
+        try {
+          matcher = new RegExp(String(entry.expect));
+        } catch {
+          problems.push(`${label}: expect ${JSON.stringify(entry.expect)} is not a valid regular expression`);
+          continue;
+        }
+        if (!matcher.test(output)) {
+          problems.push(`${label}: probe output does not match expect ${JSON.stringify(entry.expect)}`);
+          continue;
+        }
+      }
+      checked.push({ command: label, version: null, probe: true });
+      continue;
+    }
     if (!entry || typeof entry !== "object" || typeof entry.command !== "string" || entry.command.length === 0) {
-      problems.push(`requires entries need a command name, got: ${JSON.stringify(entry)}`);
+      problems.push(`requires entries need a command name or a probe, got: ${JSON.stringify(entry)}`);
       continue;
     }
     // A generous timeout: a missing binary fails instantly (ENOENT), while a

package/src/v2/runtime/envelope.js

@@ -0,0 +1,183 @@
+// Envelope as a first-class run-config section (iteration 08, C6). The deploy
+// campaign paid for every Run with a 34-line yaml, a 10 KB worker.sh and four
+// prompt files, and each worker line was a `git show <meta sha>:path | bash`
+// incantation. The kernel now does that part: it reads the prompt for the
+// step's worker (optionally pinned to a commit), substitutes declared vars,
+// materialises it into the run directory and hands the path to the worker as
+// BUILDBEAT_PROMPT. The envelope digest is recorded on RUN_CREATED so "which
+// prompts did this run see" is answerable from the ledger.
+//
+//   envelope:
+//     prompts: run-envelope/prompts     # dir, relative to the run config
+//     pin: <commit sha>                 # optional: read prompts from that commit
+//     vars:
+//       component: auth                 # {vars.component} in prompts and args
+//
+// Prompt lookup per worker: <component>-<worker>.md (when vars.component is
+// set) then <worker>.md. Missing prompt for a configured worker is not an
+// error — that worker simply gets no BUILDBEAT_PROMPT.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+import { canonicalJson } from "../storage/event-ledger.js";
+
+export class EnvelopeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnvelopeError";
+  }
+}
+
+function gitToplevel(dir) {
+  try {
+    return execFileSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function readPinned(toplevel, pin, relPath) {
+  try {
+    return execFileSync("git", ["-C", toplevel, "show", `${pin}:${relPath}`], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function substituteVars(text, vars) {
+  let out = String(text);
+  for (const [key, value] of Object.entries(vars ?? {})) {
+    out = out.replaceAll(`{vars.${key}}`, String(value));
+  }
+  return out;
+}
+
+// Loads every prompt the configured workers could use. Returns null when the
+// run config declares no envelope.
+export function loadEnvelope(config, configDir, workerNames) {
+  const spec = config.envelope;
+  if (spec === undefined) {
+    return null;
+  }
+  if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+    throw new EnvelopeError("envelope must be a map");
+  }
+  if (typeof spec.prompts !== "string" || spec.prompts.length === 0) {
+    throw new EnvelopeError("envelope.prompts (a directory) is required");
+  }
+  const vars = spec.vars ?? {};
+  if (!vars || typeof vars !== "object" || Array.isArray(vars)) {
+    throw new EnvelopeError("envelope.vars must be a map");
+  }
+  for (const [key, value] of Object.entries(vars)) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(key) || (typeof value !== "string" && typeof value !== "number")) {
+      throw new EnvelopeError(`envelope.vars.${key} must be a scalar`);
+    }
+  }
+  const pin = spec.pin ?? null;
+  if (pin !== null && !/^[0-9a-f]{7,40}$/.test(String(pin))) {
+    throw new EnvelopeError(`envelope.pin must be a commit sha, got: ${pin}`);
+  }
+  // realpath: git reports the toplevel through resolved symlinks (macOS
+  // /var → /private/var), so the config dir must be resolved the same way
+  // before a repository-relative prompt path can be computed.
+  const configReal = existsSync(configDir) ? realpathSync(configDir) : resolve(configDir);
+  const promptsDir = resolve(configReal, spec.prompts);
+  let toplevel = null;
+  let promptsRel = null;
+  if (pin) {
+    toplevel = gitToplevel(configReal);
+    if (!toplevel) {
+      throw new EnvelopeError("envelope.pin needs the run config to live inside a git repository");
+    }
+    promptsRel = relative(toplevel, promptsDir).split("\\").join("/");
+    if (promptsRel.startsWith("..")) {
+      throw new EnvelopeError("envelope.prompts must be inside the repository that holds the run config when pinned");
+    }
+  }
+  const component = vars.component !== undefined ? String(vars.component) : null;
+  const prompts = {};
+  for (const worker of workerNames) {
+    const candidates = [];
+    if (component) {
+      candidates.push(`${component}-${worker}.md`);
+    }
+    candidates.push(`${worker}.md`);
+    for (const name of candidates) {
+      let text = null;
+      if (pin) {
+        text = readPinned(toplevel, String(pin), `${promptsRel}/${name}`);
+      } else if (existsSync(join(promptsDir, name))) {
+        text = readFileSync(join(promptsDir, name), "utf8");
+      }
+      if (text !== null) {
+        prompts[worker] = { file: name, text: substituteVars(text, vars) };
+        break;
+      }
+    }
+  }
+  if (Object.keys(prompts).length === 0) {
+    throw new EnvelopeError(
+      `envelope.prompts ${spec.prompts} holds no prompt for any configured worker (${workerNames.join(", ") || "none"})${pin ? ` at ${pin}` : ""}`,
+    );
+  }
+  const digest = `sha256:${createHash("sha256")
+    .update(canonicalJson({ prompts, vars, pin }), "utf8")
+    .digest("hex")}`;
+  return { prompts, vars, pin: pin ? String(pin) : null, digest, source: pin ? `${promptsRel}@${pin}` : spec.prompts };
+}
+
+// Writes the step's prompt into the run directory and returns its absolute
+// path plus the repository-relative reference for the worker input.
+export function materialisePrompt({ envelope, worker, runtimeDir, runId, step, attempt, repoRoot }) {
+  const prompt = envelope?.prompts?.[worker];
+  if (!prompt) {
+    return null;
+  }
+  const dir = join(runtimeDir, "runs", runId, "prompts");
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${step}-${attempt}.md`);
+  writeFileSync(path, prompt.text, "utf8");
+  return { path, ref: relative(repoRoot, path).split("\\").join("/"), file: prompt.file };
+}
+
+// Next attempt id for a run family: RUN-X → RUN-X-01, RUN-X-02, ... scanning
+// both the runtime plane and the Git plane (run-records survive a runtime
+// wipe, so numbering never collides with a compacted run).
+export function nextAttemptId(repoRoot, workId, family) {
+  const pattern = new RegExp(`^${family.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-(\\d{2,})$`);
+  let max = 0;
+  const dirs = [
+    join(repoRoot, ".buildbeat", "runtime", "runs"),
+    join(repoRoot, "delivery", "work", workId, "runs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      continue;
+    }
+    for (const entry of readdirSafe(dir)) {
+      const match = entry.match(pattern);
+      if (match) {
+        max = Math.max(max, Number(match[1]));
+      }
+    }
+  }
+  return `${family}-${String(max + 1).padStart(2, "0")}`;
+}
+
+function readdirSafe(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}