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

package/src/v2/runtime/liveness.js

@@ -0,0 +1,193 @@
+// Liveness and timing, derived only from the ledger and the live output
+// streams the shell adapter leaves in the run directory. Nothing here is
+// written to the ledger: "how long has this been running" and "when did the
+// worker last print something" are readings, not facts a Run must carry.
+//
+// Real incident (deploy campaign, 2026-08-30): the owner asked "半小时了，
+// 正常吗 / 十分钟了，是卡住了吗" more than ten times because status showed
+// steps and attempts and nothing about time. This module is that answer.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { LIVE_MARKER } from "../adapters/shell.js";
+
+export const DEFAULT_STALL_AFTER_MS = 15 * 60 * 1000;
+
+export function runDir(repoRoot, runId) {
+  return join(repoRoot, ".buildbeat", "runtime", "runs", runId);
+}
+
+// Every step attempt as a timed row; the in-flight one (if any) has no end.
+export function stepTimeline(events) {
+  const open = new Map();
+  const rows = [];
+  let running = null;
+  for (const event of events) {
+    if (event.type === "STEP_STARTED") {
+      const key = `${event.data.step}#${event.data.attempt}`;
+      open.set(key, { step: event.data.step, attempt: event.data.attempt, worker: event.data.worker, startedAt: event.ts });
+      running = open.get(key);
+    } else if (event.type === "STEP_FINISHED") {
+      const key = `${event.data.step}#${event.data.attempt}`;
+      const started = open.get(key);
+      const startedAt = started?.startedAt ?? null;
+      rows.push({
+        step: event.data.step,
+        attempt: event.data.attempt,
+        worker: started?.worker ?? null,
+        startedAt,
+        finishedAt: event.ts,
+        status: event.data.status,
+        durationMs: startedAt ? Date.parse(event.ts) - Date.parse(startedAt) : null,
+      });
+      open.delete(key);
+      if (running && running.step === event.data.step && running.attempt === event.data.attempt) {
+        running = null;
+      }
+    }
+  }
+  return { rows, running };
+}
+
+function median(values) {
+  if (values.length === 0) {
+    return null;
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+
+// Typical (median) duration per step across every readable ledger in the
+// repository, optionally excluding the run being described. Crashed and
+// timed-out attempts are excluded: they measure the host, not the step.
+export function typicalDurations(repoRoot, { excludeRun = null } = {}) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const samples = {};
+  if (!existsSync(runsDir)) {
+    return {};
+  }
+  for (const entry of readdirSync(runsDir)) {
+    if (entry === excludeRun) {
+      continue;
+    }
+    const ledgerPath = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(ledgerPath)) {
+      continue;
+    }
+    const ledger = EventLedger.open(ledgerPath);
+    for (const row of stepTimeline(ledger.events).rows) {
+      if (row.durationMs === null || row.status === "crashed" || row.status === "timeout") {
+        continue;
+      }
+      (samples[row.step] ??= []).push(row.durationMs);
+    }
+  }
+  const result = {};
+  for (const [step, values] of Object.entries(samples)) {
+    result[step] = { medianMs: median(values), samples: values.length };
+  }
+  return result;
+}
+
+// Reads the shell adapter's live marker and the mtime/size of its streams.
+export function readLive(repoRoot, runId) {
+  const dir = runDir(repoRoot, runId);
+  const markerPath = join(dir, LIVE_MARKER);
+  if (!existsSync(markerPath)) {
+    return null;
+  }
+  let marker;
+  try {
+    marker = JSON.parse(readFileSync(markerPath, "utf8"));
+  } catch {
+    return null;
+  }
+  let lastOutputAt = null;
+  let bytes = 0;
+  for (const path of [marker.stdout, marker.stderr]) {
+    if (!path || !existsSync(path)) {
+      continue;
+    }
+    const stat = statSync(path);
+    bytes += stat.size;
+    if (stat.size > 0 && (lastOutputAt === null || stat.mtimeMs > lastOutputAt)) {
+      lastOutputAt = stat.mtimeMs;
+    }
+  }
+  return { ...marker, lastOutputAt: lastOutputAt === null ? null : new Date(lastOutputAt).toISOString(), bytes };
+}
+
+export function tailLive(repoRoot, runId, lines = 5) {
+  const live = readLive(repoRoot, runId);
+  if (!live) {
+    return [];
+  }
+  const out = [];
+  for (const path of [live.stdout, live.stderr]) {
+    if (!path || !existsSync(path)) {
+      continue;
+    }
+    const text = readFileSync(path, "utf8");
+    out.push(...text.split("\n").filter((line) => line.trim().length > 0));
+  }
+  return out.slice(-lines);
+}
+
+export function describeLiveness({ repoRoot, runId, ledger, stallAfterMs = DEFAULT_STALL_AFTER_MS, now = Date.now }) {
+  const { rows, running } = stepTimeline(ledger.events);
+  const typical = typicalDurations(repoRoot, { excludeRun: runId });
+  const steps = {};
+  for (const row of rows) {
+    const entry = (steps[row.step] ??= { attempts: 0, totalMs: 0, lastMs: null, typicalMs: typical[row.step]?.medianMs ?? null, samples: typical[row.step]?.samples ?? 0 });
+    entry.attempts += 1;
+    if (row.durationMs !== null) {
+      entry.totalMs += row.durationMs;
+      entry.lastMs = row.durationMs;
+    }
+  }
+  let inFlight = null;
+  if (running && ledger.state.run?.status === "RUNNING") {
+    const nowMs = now();
+    const live = readLive(repoRoot, runId);
+    const elapsedMs = nowMs - Date.parse(running.startedAt);
+    const lastOutputMs = live?.lastOutputAt ? Date.parse(live.lastOutputAt) : null;
+    const sinceOutputMs = lastOutputMs === null ? elapsedMs : nowMs - lastOutputMs;
+    inFlight = {
+      step: running.step,
+      attempt: running.attempt,
+      worker: running.worker,
+      startedAt: running.startedAt,
+      elapsedMs,
+      command: live?.command ?? null,
+      lastOutputAt: live?.lastOutputAt ?? null,
+      sinceOutputMs,
+      bytes: live?.bytes ?? 0,
+      stalled: sinceOutputMs >= stallAfterMs,
+      stallAfterMs,
+      typicalMs: typical[running.step]?.medianMs ?? null,
+      samples: typical[running.step]?.samples ?? 0,
+    };
+    steps[running.step] ??= { attempts: 0, totalMs: 0, lastMs: null, typicalMs: inFlight.typicalMs, samples: inFlight.samples };
+  }
+  return { steps, inFlight };
+}
+
+export function formatMs(ms) {
+  if (ms === null || ms === undefined || Number.isNaN(ms)) {
+    return "?";
+  }
+  const total = Math.max(0, Math.round(ms / 1000));
+  if (total < 60) {
+    return `${total}s`;
+  }
+  const minutes = Math.floor(total / 60);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? `${hours}h` : `${hours}h${String(rest).padStart(2, "0")}m`;
+}

package/src/v2/runtime/metrics.js

@@ -6,6 +6,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 
 import { EventLedger } from "../storage/event-ledger.js";
+import { formatMs, typicalDurations } from "./liveness.js";
 
 export function computeMetrics(repoRoot) {
   const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
@@ -105,6 +106,9 @@ export function computeMetrics(repoRoot) {
   summary.autoReachedHumanRate = measurable === 0 ? null : autoReached / measurable;
   summary.evidenceCompleteness =
     summary.finishedSteps === 0 ? null : evidencedSteps / summary.finishedSteps;
+  // Typical step duration (median over finished attempts, crashes and
+  // timeouts excluded): the number behind "is this taking too long".
+  summary.stepDurations = typicalDurations(repoRoot);
   return summary;
 }
 
@@ -136,5 +140,9 @@ export function renderMetrics(summary) {
     lines.push("approval waits: (none recorded)");
   }
   lines.push(`stale approvals: ${summary.staleApprovals}; budget stops: ${summary.budgetStops}`);
+  const durations = Object.entries(summary.stepDurations ?? {})
+    .map(([step, row]) => `${step}=${formatMs(row.medianMs)} (n=${row.samples})`)
+    .join(" ");
+  lines.push(`typical step duration (median): ${durations || "(no finished attempts)"}`);
   return lines.join("\n");
 }

package/src/v2/runtime/notify.js

@@ -0,0 +1,223 @@
+// Outbound notifications (iteration 08, C4): a Run that stops for a human
+// should reach that human where they are, not wait for them to open a
+// session and ask. Approval waits in the deploy campaign averaged 7–12 hours
+// because nothing said "there is something for you".
+//
+// Discipline: fail-open (a notification failure never touches a run), secrets
+// stay out of Git (the webhook URL comes from an env var named in the
+// config), payloads carry identifiers and the next reply — never candidate
+// content, never logs.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseYamlSubset } from "../engine/yaml-subset.js";
+
+export const NOTIFY_CONFIG = join(".buildbeat", "notify.yaml");
+export const NOTIFY_EVENTS = ["HUMAN_REQUESTED", "RUN_TERMINAL", "STALLED"];
+const CHANNEL_TYPES = ["webhook", "dingtalk"];
+
+export class NotifyConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotifyConfigError";
+  }
+}
+
+// Returns null when no config exists. Throws NotifyConfigError on a config
+// that exists but is malformed — callers decide whether that is fatal (it is
+// not for a run; it is for `doctor`).
+export function loadNotifyConfig(repoRoot) {
+  const path = join(repoRoot, NOTIFY_CONFIG);
+  if (!existsSync(path)) {
+    return null;
+  }
+  const doc = parseYamlSubset(readFileSync(path, "utf8"));
+  if (doc.kind !== "notify" || doc.version !== 1) {
+    throw new NotifyConfigError(`${NOTIFY_CONFIG}: expected kind: notify / version: 1`);
+  }
+  if (!Array.isArray(doc.channels) || doc.channels.length === 0) {
+    throw new NotifyConfigError(`${NOTIFY_CONFIG}: channels must be a non-empty list`);
+  }
+  const channels = doc.channels.map((channel, index) => {
+    const where = `${NOTIFY_CONFIG} channels[${index}]`;
+    if (typeof channel.id !== "string" || channel.id.length === 0) {
+      throw new NotifyConfigError(`${where}: id is required`);
+    }
+    if (!CHANNEL_TYPES.includes(channel.type)) {
+      throw new NotifyConfigError(`${where}: type must be one of ${CHANNEL_TYPES.join("|")}`);
+    }
+    if (typeof channel.urlEnv !== "string" || channel.urlEnv.length === 0) {
+      throw new NotifyConfigError(
+        `${where}: urlEnv is required (the webhook URL lives in that env var, never in Git)`,
+      );
+    }
+    if (channel.url !== undefined) {
+      throw new NotifyConfigError(`${where}: url is not allowed in Git; use urlEnv`);
+    }
+    const events = channel.events ?? NOTIFY_EVENTS;
+    if (!Array.isArray(events) || events.length === 0) {
+      throw new NotifyConfigError(`${where}: events must be a non-empty list`);
+    }
+    for (const event of events) {
+      if (!NOTIFY_EVENTS.includes(event)) {
+        throw new NotifyConfigError(`${where}: unknown event ${event} (allowed: ${NOTIFY_EVENTS.join("|")})`);
+      }
+    }
+    return { id: channel.id, type: channel.type, urlEnv: channel.urlEnv, events, keyword: channel.keyword ?? "BuildBeat" };
+  });
+  return { channels };
+}
+
+export function subscribes(config, event) {
+  return Boolean(config?.channels.some((channel) => channel.events.includes(event)));
+}
+
+// The exact commands a human can copy to answer a pending request. Shared by
+// status, inbox and notifications so "what do I say now" has one answer.
+export function nextReply({ repoLabel, state }) {
+  const pending = state.pendingHuman;
+  if (!pending || !state.run) {
+    return [];
+  }
+  const runId = state.run.id;
+  const lines = [];
+  if (pending.kind === "finding-triage") {
+    lines.push(`buildbeat-v2 findings list --repo ${repoLabel} --work ${state.run.work}`);
+    lines.push(
+      `buildbeat-v2 findings adjudicate --repo ${repoLabel} --work ${state.run.work} --fingerprint <fp> --action accept|dismiss --by <you>`,
+    );
+  }
+  lines.push(
+    `buildbeat-v2 approve --repo ${repoLabel} --run ${runId} --transition ${pending.transition} --by <you>` +
+      (pending.kind === "final-decision" ? "   # merge-ready; merge/push stay yours" : "   # then: resume --config <run-config.yaml>"),
+  );
+  lines.push(`buildbeat-v2 reject --repo ${repoLabel} --run ${runId} --reason <why> --by <you>`);
+  return lines;
+}
+
+export function buildNotification(kind, { repoLabel, state, detail = {} }) {
+  const run = state.run;
+  const base = {
+    kind,
+    run: run?.id ?? null,
+    work: run?.work ?? null,
+    status: run?.status ?? null,
+    repo: repoLabel,
+    at: new Date().toISOString(),
+  };
+  if (kind === "HUMAN_REQUESTED") {
+    const pending = state.pendingHuman;
+    return {
+      ...base,
+      title: `[BuildBeat] ${run.id} 等你拍板：${pending?.transition ?? "?"}`,
+      reasons: pending?.reasons ?? [],
+      candidate: pending?.subject?.candidate ?? null,
+      nextReply: nextReply({ repoLabel, state }),
+    };
+  }
+  if (kind === "RUN_TERMINAL") {
+    return {
+      ...base,
+      title: `[BuildBeat] ${run.id} 结束：${state.terminal?.status ?? run.status}`,
+      reasons: state.terminal?.reason ? [state.terminal.reason] : [],
+      candidate: state.workspaces?.[run.id]?.candidate ?? null,
+      nextReply: [],
+    };
+  }
+  if (kind === "STALLED") {
+    return {
+      ...base,
+      title: `[BuildBeat] ${run.id} 疑似卡住：${detail.step ?? "?"} 已 ${detail.sinceOutput ?? "?"} 无输出`,
+      reasons: [
+        `step ${detail.step ?? "?"} attempt ${detail.attempt ?? "?"} started ${detail.startedAt ?? "?"}, elapsed ${detail.elapsed ?? "?"}`,
+        detail.command ? `worker: ${detail.command}` : "worker: (unknown)",
+        `threshold ${detail.threshold ?? "?"}; the process is NOT killed — check status, then decide`,
+      ],
+      candidate: null,
+      nextReply: [`buildbeat-v2 status --repo ${repoLabel} --run ${run.id}`],
+    };
+  }
+  throw new NotifyConfigError(`unknown notification kind: ${kind}`);
+}
+
+function renderText(notification) {
+  const lines = [notification.title, `work: ${notification.work}  status: ${notification.status}`];
+  for (const reason of notification.reasons ?? []) {
+    lines.push(`- ${reason}`);
+  }
+  if (notification.candidate) {
+    lines.push(`candidate: ${notification.candidate}`);
+  }
+  if (notification.nextReply?.length) {
+    lines.push("next:");
+    for (const line of notification.nextReply) {
+      lines.push(`  ${line}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function payloadFor(channel, notification) {
+  if (channel.type === "dingtalk") {
+    // DingTalk custom robots require a configured keyword in the text; the
+    // title carries it (default "BuildBeat").
+    const text = renderText(notification);
+    return {
+      msgtype: "text",
+      text: { content: text.includes(channel.keyword) ? text : `${channel.keyword}\n${text}` },
+    };
+  }
+  return { ...notification, text: renderText(notification) };
+}
+
+function logLine(repoRoot, runId, line) {
+  if (!runId) {
+    return;
+  }
+  try {
+    const dir = join(repoRoot, ".buildbeat", "runtime", "runs", runId);
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "notify.log"), `${new Date().toISOString()} ${line}\n`, "utf8");
+  } catch {
+    // logging a notification must never fail the caller
+  }
+}
+
+// Sends to every channel subscribed to the notification kind. Never throws;
+// each channel reports ok/skipped/failed. A missing URL env var is a skip
+// with a visible reason, not silence.
+export async function dispatchNotification(config, notification, { repoRoot, fetchImpl = globalThis.fetch, timeoutMs = 8000, env = process.env } = {}) {
+  const results = [];
+  for (const channel of config?.channels ?? []) {
+    if (!channel.events.includes(notification.kind)) {
+      continue;
+    }
+    const url = env[channel.urlEnv];
+    if (!url) {
+      results.push({ channel: channel.id, ok: false, skipped: true, error: `env ${channel.urlEnv} not set` });
+      logLine(repoRoot, notification.run, `${notification.kind} ${channel.id} SKIPPED env ${channel.urlEnv} not set`);
+      continue;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payloadFor(channel, notification)),
+        signal: controller.signal,
+      });
+      const ok = response.ok;
+      results.push({ channel: channel.id, ok, status: response.status, error: ok ? null : `HTTP ${response.status}` });
+      logLine(repoRoot, notification.run, `${notification.kind} ${channel.id} ${ok ? "SENT" : "FAILED"} HTTP ${response.status}`);
+    } catch (error) {
+      const message = error?.name === "AbortError" ? `timeout after ${timeoutMs}ms` : error?.message ?? String(error);
+      results.push({ channel: channel.id, ok: false, error: message });
+      logLine(repoRoot, notification.run, `${notification.kind} ${channel.id} FAILED ${message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return results;
+}

package/src/v2/runtime/orchestrator.js

@@ -11,7 +11,7 @@
 // anything changed goes APPROVAL_STALE and back to WAITING_HUMAN.
 
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { nextStep } from "../engine/workflow.js";
@@ -27,6 +27,8 @@ import {
 } from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
 import { assertRequires } from "./env-contract.js";
+import { materialisePrompt } from "./envelope.js";
+import { cacheKey, findReusableEvidence, lastReviewedCandidate, treeHash } from "./cache.js";
 import {
   buildAnchor,
   fingerprintFinding,
@@ -145,6 +147,10 @@ function makeContext(options, ledger, workspace) {
   context.policies = options.policies ?? [];
   context.allowedPaths = options.allowedPaths ?? null;
   context.reviewTriage = options.reviewTriage ?? null;
+  context.envelope = options.envelope ?? null;
+  context.cache = options.cache ?? {};
+  context.redact = options.redact ?? [];
+  context.adapterConfigs = options.adapterConfigs ?? {};
   context.policyCtx = () => ({
     state: ledger.state,
     candidate: ledger.state.workspaces[workspace.workspaceId]?.candidate ?? null,
@@ -379,14 +385,76 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
         }));
       }
     }
-    const exec = adapter.execute({
-      step,
+    // Envelope (C6): the worker's prompt, materialised into the run
+    // directory and handed over as BUILDBEAT_PROMPT / input.envelope.
+    const prompt = materialisePrompt({
+      envelope: context.envelope,
       worker: stepDef.worker,
-      workspacePath: workspace.worktreePath,
-      input,
-      timeoutMs: context.stepTimeoutMs,
-      outputPath,
+      runtimeDir: context.runtimeDir,
+      runId: ledger.state.run.id,
+      step,
+      attempt,
+      repoRoot: context.repoRoot,
     });
+    if (prompt) {
+      input.envelope = { promptRef: prompt.ref, file: prompt.file, digest: context.envelope.digest, vars: context.envelope.vars };
+    }
+    // Incremental review (C7): tell a reviewer which candidate the last
+    // review saw when it is an ancestor of this one.
+    if (stepDef.readonly) {
+      const head = before.head;
+      const lastReviewed = lastReviewedCandidate(context.repoRoot, ledger.state.run.work, workspace.worktreePath, head);
+      if (lastReviewed) {
+        input.lastReviewed = lastReviewed;
+      }
+    }
+    // Verification reuse (C7): same tree + same worker + same envelope that
+    // already passed is referenced, not re-run. Failures always re-run.
+    let stepCacheKey = null;
+    let reused = null;
+    if (context.cache[step] === "tree") {
+      const current = readback(workspace.worktreePath);
+      if (!current.dirty) {
+        stepCacheKey = cacheKey({
+          tree: treeHash(workspace.worktreePath),
+          worker: stepDef.worker,
+          adapterSpec: context.adapterConfigs[stepDef.worker] ?? null,
+          adapterName: adapter.name,
+          envelopeDigest: context.envelope?.digest ?? null,
+        });
+        reused = findReusableEvidence(context.repoRoot, stepCacheKey);
+      }
+    }
+    let exec;
+    if (reused) {
+      const at = now();
+      exec = {
+        adapter: "cache",
+        command: `reuse ${reused.run} ${reused.evidenceRef}`,
+        exitCode: 0,
+        signal: null,
+        stdout: `REUSED: identical tree/worker/envelope already passed in ${reused.run} (${reused.evidenceRef}, ${reused.digest}); not re-run`,
+        stderr: "",
+        timedOut: false,
+        spawnError: null,
+        startedAt: at,
+        finishedAt: at,
+      };
+    } else {
+      exec = adapter.execute({
+        step,
+        worker: stepDef.worker,
+        workspacePath: workspace.worktreePath,
+        input,
+        timeoutMs: context.stepTimeoutMs,
+        outputPath,
+        // Live output streams + marker land in the run directory so `status`
+        // can answer "is it still doing something" while the step runs.
+        liveDir: join(context.runtimeDir, "runs", ledger.state.run.id),
+        promptPath: prompt?.path ?? null,
+        vars: context.envelope?.vars ?? null,
+      });
+    }
     const tree = readback(workspace.worktreePath);
     const evidence = collectCommandEvidence({
       runtimeDir: context.runtimeDir,
@@ -395,6 +463,8 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
       attempt,
       execResult: exec,
       subject: tree.head,
+      grade: reused ? reused.grade : stepDef.grade ?? "L2",
+      redact: context.redact,
     });
     ledger.append({
       type: "EVIDENCE_RECORDED",
@@ -407,6 +477,8 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
         digest: evidence.digest,
         status: evidence.status,
         grade: evidence.grade,
+        ...(stepCacheKey ? { cacheKey: stepCacheKey } : {}),
+        ...(reused ? { reused: { run: reused.run, evidenceRef: reused.evidenceRef, digest: reused.digest } } : {}),
       },
     });
 
@@ -617,6 +689,57 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
   }
 }
 
+// Supersede (iteration 08, C2): a new Run for the same Work makes any older
+// Run still waiting on a human moot — the human would be approving a
+// candidate nobody intends to merge. Real incident: two WAITING_HUMAN runs
+// sat in a pilot repo's inbox for a day after their successor had already
+// shipped. Only WAITING_HUMAN runs are touched; RUNNING ones are protected
+// by the active lock, terminal ones are already settled.
+function supersedeWaitingRuns(repoRoot, workId, newRunId, now) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const superseded = [];
+  const skipped = [];
+  if (!existsSync(runsDir)) {
+    return { superseded, skipped };
+  }
+  for (const entry of readdirSync(runsDir).sort()) {
+    if (entry === newRunId) {
+      continue;
+    }
+    const ledgerPath = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(ledgerPath)) {
+      continue;
+    }
+    const ledger = EventLedger.open(ledgerPath);
+    const state = ledger.state;
+    if (ledger.corruption || !state.run || state.run.work !== workId) {
+      continue;
+    }
+    if (state.terminal || state.run.status !== "WAITING_HUMAN") {
+      continue;
+    }
+    try {
+      acquireLock(repoRoot, entry);
+    } catch {
+      skipped.push({ run: entry, reason: "locked by another process" });
+      continue;
+    }
+    try {
+      ledger.append({
+        type: "RUN_TERMINAL",
+        actor: KERNEL,
+        ts: now(),
+        data: { status: "SUPERSEDED", reason: `superseded by ${newRunId} (same work ${workId})` },
+      });
+      writeRunRecord({ repoRoot, ledger, ts: now() });
+      superseded.push(entry);
+    } finally {
+      releaseLock(repoRoot, entry);
+    }
+  }
+  return { superseded, skipped };
+}
+
 function openLedgerFor(repoRoot, runId) {
   const ledgerPath = join(repoRoot, ".buildbeat", "runtime", "runs", runId, "events.jsonl");
   const ledger = EventLedger.open(ledgerPath);
@@ -664,6 +787,10 @@ export function startRun(options) {
     const workspace = createWorkspace({ repoRoot, runId, base });
     const context = makeContext(options, ledger, workspace);
     const now = context.now;
+    const supersession =
+      options.supersede === "off"
+        ? { superseded: [], skipped: [] }
+        : supersedeWaitingRuns(repoRoot, workId, runId, now);
     ledger.append({
       type: "RUN_CREATED",
       actor: KERNEL,
@@ -678,6 +805,8 @@ export function startRun(options) {
         entry,
         planDigest: planDigest ?? "UNVERIFIED",
         intentDigest: intentDigest ?? "UNVERIFIED",
+        ...(supersession.superseded.length > 0 ? { supersedes: supersession.superseded } : {}),
+        ...(options.envelope ? { envelopeDigest: options.envelope.digest, envelopeSource: options.envelope.source } : {}),
       },
     });
     ledger.append({ type: "RUN_STARTED", actor: KERNEL, ts: now(), data: {} });
@@ -694,7 +823,15 @@ export function startRun(options) {
       },
     });
     drive(context, entry);
-    return { runId, workId, ledgerPath, state: ledger.state, workspace };
+    return {
+      runId,
+      workId,
+      ledgerPath,
+      state: ledger.state,
+      workspace,
+      superseded: supersession.superseded,
+      supersedeSkipped: supersession.skipped,
+    };
   });
 }