@haiyangbg/buildbeat 2.0.0-beta.4 → 2.0.0

package/src/v2/cli/run.js

@@ -17,11 +17,11 @@ import { fileURLToPath } from "node:url";
 
 import { createShellAdapter } from "../adapters/shell.js";
 import { loadRiskPreset } from "../engine/risk-preset.js";
-import { loadWorkflow } from "../engine/workflow.js";
+import { loadWorkflow, nextStep } from "../engine/workflow.js";
 import { parseYamlSubset } from "../engine/yaml-subset.js";
 import { parsePolicyDoc } from "../policy/policy.js";
 import { observeStatus, runObserveCycle, triageIntent } from "../observe/observe.js";
-import { acceptArtifact, approveRun, listInbox, rejectRun } from "../runtime/decisions.js";
+import { acceptArtifact, adoptCandidate, approveRun, listInbox, rejectRun } from "../runtime/decisions.js";
 import { checkRequires } from "../runtime/env-contract.js";
 import {
   adjudicateFinding,
@@ -31,7 +31,7 @@ import {
 } from "../runtime/findings.js";
 import { loadEnvelope, nextAttemptId } from "../runtime/envelope.js";
 import { applyGc, planGc } from "../runtime/gc.js";
-import { computeOverview, renderOverview } from "../runtime/overview.js";
+import { artifactStatus, computeOverview, readJsonl, renderOverview } from "../runtime/overview.js";
 import {
   DEFAULT_STALL_AFTER_MS,
   describeLiveness,
@@ -51,7 +51,7 @@ import { writeRunRecord } from "../runtime/run-record.js";
 import { resumeRun, startRun } from "../runtime/orchestrator.js";
 import { toRepoRef } from "../runtime/repo-ref.js";
 import { EventLedger } from "../storage/event-ledger.js";
-import { acquireLock, releaseLock } from "../workspace/workspace-manager.js";
+import { acquireLock, listHeldRunLocks, releaseLock } from "../workspace/workspace-manager.js";
 
 const KERNEL = { kind: "kernel", id: "cli" };
 
@@ -59,7 +59,7 @@ const USAGE = `BuildBeat v2 runtime
 
 Usage:
   run.js start --config <run-config.yaml> [--attempt new]
-  run.js resume --config <run-config.yaml>
+  run.js resume --config <run-config.yaml> [--adopt <sha> --by <name>]   # --adopt: hand fix committed in the worktree; skip fix, resume at verify
   run.js status --repo <path> --run <RUN-ID> [--stall-after <minutes>]
   run.js inbox --repo <path>
   run.js overview --repo <path> [--work <WORK-ID>] [--json true]
@@ -281,6 +281,43 @@ function loadRunConfig(flags, command) {
   if (config.stallAfterMs !== undefined && !(Number(config.stallAfterMs) > 0)) {
     throw new Error(`stallAfterMs must be a positive number, got: ${config.stallAfterMs}`);
   }
+  // budgets: run config beats the preset (the preset's two review rounds
+  // could not be raised per run before; a pilot's shipped candidates ended
+  // as CANCELLED runs because of it).
+  const budgets = {};
+  if (config.budgets !== undefined) {
+    if (!config.budgets || typeof config.budgets !== "object" || Array.isArray(config.budgets)) {
+      throw new Error("budgets must be a map");
+    }
+    for (const key of Object.keys(config.budgets)) {
+      if (!["maxAttempts", "reviewRoundsPerWork"].includes(key)) {
+        throw new Error(`unknown budgets key: ${key} (known: maxAttempts, reviewRoundsPerWork)`);
+      }
+    }
+    if (config.budgets.maxAttempts !== undefined) {
+      const map = config.budgets.maxAttempts;
+      if (!map || typeof map !== "object" || Array.isArray(map)) {
+        throw new Error("budgets.maxAttempts must be a map of step -> positive integer");
+      }
+      budgets.maxAttempts = {};
+      for (const [step, value] of Object.entries(map)) {
+        if (!workflow.stepIds.has(step)) {
+          throw new Error(`budgets.maxAttempts.${step}: step not in workflow`);
+        }
+        if (!Number.isInteger(Number(value)) || Number(value) < 1) {
+          throw new Error(`budgets.maxAttempts.${step} must be a positive integer, got: ${value}`);
+        }
+        budgets.maxAttempts[step] = Number(value);
+      }
+    }
+    if (config.budgets.reviewRoundsPerWork !== undefined) {
+      const value = Number(config.budgets.reviewRoundsPerWork);
+      if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`budgets.reviewRoundsPerWork must be a positive integer, got: ${config.budgets.reviewRoundsPerWork}`);
+      }
+      budgets.reviewRoundsPerWork = value;
+    }
+  }
   const cache = {};
   for (const [step, mode] of Object.entries(config.cache ?? {})) {
     if (mode !== "tree") {
@@ -317,6 +354,7 @@ function loadRunConfig(flags, command) {
     policies,
     riskPreset,
     maxAttemptsPerStep: config.maxAttemptsPerStep ?? 4,
+    budgets,
     stepTimeoutMs: config.stepTimeoutMs,
     allowedPaths: config.allowedPaths,
     requires: config.requires ?? [],
@@ -419,7 +457,36 @@ async function commandStart(flags) {
   if (watching) {
     console.log(`stall watcher armed (no output for ${formatMs(options.stallAfterMs)} notifies STALLED)`);
   }
-  const result = startRun(options);
+  let result;
+  try {
+    result = startRun(options);
+  } catch (error) {
+    if (/another run is active/.test(error.message ?? "")) {
+      // Say who holds the repository and how to watch it: a pilot session
+      // waited 3h23m behind another work's run with nothing but the lock
+      // message to go on ("二十分钟了哎").
+      const label = repoLabelFor(options.repoRoot);
+      const holders = listHeldRunLocks(options.repoRoot);
+      if (holders.length === 0) {
+        console.error("blocked by: a stale active-run lock with no run holding it (a killed process?); `gc` clears locks of terminal runs, or remove .buildbeat/runtime/locks/active-run.lock after checking no driver process is alive");
+      }
+      for (const holder of holders) {
+        const ledgerPath = join(options.repoRoot, ".buildbeat", "runtime", "runs", holder, "events.jsonl");
+        let summary = "(no ledger found)";
+        if (existsSync(ledgerPath)) {
+          const ledger = EventLedger.open(ledgerPath);
+          const state = ledger.state;
+          const step = state.currentStep ? `step ${state.currentStep} attempt ${state.steps[state.currentStep]?.attempts ?? "?"}` : "between steps";
+          const since = ledger.events[ledger.events.length - 1]?.ts;
+          summary = `${state.run?.work ?? "?"} ${state.run?.status ?? "?"} ${step}${since ? `, last event ${formatMs(Date.now() - Date.parse(since))} ago` : ""}`;
+        }
+        console.error(`blocked by ${holder}: ${summary}`);
+        console.error(`  watch it: buildbeat-v2 status --repo ${label} --run ${holder}`);
+      }
+      console.error("queue position: next after the holder(s) above stop or wait on a human (the repository allows one driving run at a time; worktrees are already isolated)");
+    }
+    throw error;
+  }
   const repoLabel = repoLabelFor(options.repoRoot);
   for (const run of result.superseded ?? []) {
     console.log(`superseded ${run} (was waiting on a human for the same work; now SUPERSEDED)`);
@@ -439,6 +506,15 @@ async function commandStart(flags) {
 
 async function commandResume(flags) {
   const options = loadRunConfig(flags, "resume");
+  if (flags.adopt !== undefined) {
+    const resumeAt = nextStep(options.workflow, "fix", "succeeded") ?? "verify";
+    const adopted = adoptCandidate(options.repoRoot, options.runId, {
+      sha: flags.adopt,
+      by: flags.by ?? "human",
+      resumeAt,
+    });
+    console.log(`adopted ${adopted.adopted} as candidate (${adopted.decisionRef}, answers ${adopted.transition}); resuming at ${adopted.resumeAt}`);
+  }
   const watching = spawnStallWatcher(options.repoRoot, options.runId, options.stallAfterMs);
   if (watching) {
     console.log(`stall watcher armed (no output for ${formatMs(options.stallAfterMs)} notifies STALLED)`);
@@ -549,6 +625,26 @@ function commandAccept(flags) {
   console.log("  note: editing the artifact after acceptance makes this acceptance stale");
 }
 
+// Artifacts a policy rule requires to be accepted (artifact.accepted leaves
+// anywhere under all/any/not).
+function artifactsRequiredBy(rule, found = []) {
+  if (!rule || typeof rule !== "object") {
+    return found;
+  }
+  for (const [key, value] of Object.entries(rule)) {
+    if (key === "artifact.accepted" && value && typeof value.artifact === "string") {
+      found.push(value.artifact);
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        artifactsRequiredBy(item, found);
+      }
+    } else if (value && typeof value === "object") {
+      artifactsRequiredBy(value, found);
+    }
+  }
+  return found;
+}
+
 function commandDoctor(flags) {
   const options = loadRunConfig(flags, "doctor");
   console.log(`risk preset: ${options.riskPreset}`);
@@ -593,6 +689,51 @@ function commandDoctor(flags) {
     console.log("push protection: repository has no remotes (nothing to protect)");
   }
   console.log("kernel capabilities: merge/deploy/publish have no call path in the runner (invariant 20)");
+  const budgetLines = [];
+  for (const step of options.workflow.steps) {
+    if (!step.worker) {
+      continue;
+    }
+    const fromRun = options.budgets.maxAttempts?.[step.id];
+    const fromPreset = options.workflow.budgets?.maxAttempts?.[step.id];
+    const effective = fromRun ?? fromPreset ?? options.maxAttemptsPerStep;
+    const source = fromRun !== undefined ? "run config" : fromPreset !== undefined ? "workflow preset" : "default";
+    budgetLines.push(`${step.id}=${effective} (${source})`);
+  }
+  console.log(`budgets (maxAttempts per step; approving resume-<step> after exhaustion grants +1): ${budgetLines.join(", ")}`);
+  if (options.budgets.reviewRoundsPerWork !== undefined) {
+    console.log(`budgets.reviewRoundsPerWork: ${options.budgets.reviewRoundsPerWork} (counted across every run of the work, superseded ones included)`);
+  }
+  // Same preconditions start's first gate will read (real incident, twice:
+  // doctor passed, start stopped at build because plan.md was not mirrored
+  // into the repository the run was started in).
+  const workDir = join(options.repoRoot, "delivery", "work", options.workId);
+  const decisions = readJsonl(join(workDir, "decisions.jsonl"));
+  console.log(`work artifacts in this repository (delivery/work/${options.workId}):`);
+  const artifactState = {};
+  for (const artifact of ["intent", "plan"]) {
+    const status = artifactStatus(workDir, decisions, artifact);
+    artifactState[artifact] = status;
+    const label = !status.exists
+      ? "MISSING"
+      : status.stale
+        ? "accepted but edited since (stale)"
+        : status.accepted
+          ? `accepted${status.by ? ` by ${status.by}` : ""}`
+          : "draft (not accepted)";
+    console.log(`  ${artifact}.md: ${label}`);
+  }
+  for (const policy of options.policies) {
+    for (const artifact of artifactsRequiredBy(policy.rule)) {
+      const status = artifactState[artifact] ?? artifactStatus(workDir, decisions, artifact);
+      if (!status.accepted) {
+        console.log(
+          `  WARNING policy ${policy.name} (${policy.type} ${policy.appliesTo}) needs an accepted ${artifact}.md; start will stop at ${policy.appliesTo}` +
+            (!status.exists ? " (file missing here: mirror it into this repository, then accept)" : " (accept it first)"),
+        );
+      }
+    }
+  }
   if (options.requires.length > 0) {
     console.log("environment contract (requires):");
     const check = checkRequires(options.requires);

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;
     }
@@ -168,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,
@@ -194,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/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/orchestrator.js

@@ -26,6 +26,7 @@ import {
   releaseLock,
 } from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
+import { computeWorkCost } from "./work-cost.js";
 import { assertRequires } from "./env-contract.js";
 import { materialisePrompt } from "./envelope.js";
 import { cacheKey, findReusableEvidence, lastReviewedCandidate, treeHash } from "./cache.js";
@@ -142,8 +143,18 @@ function makeContext(options, ledger, workspace) {
     ledger,
     workspace,
   };
+  // Effective cap per step: run config `budgets:` beats the preset, the
+  // preset beats the global default, and every BUDGET_EXTENDED a human
+  // granted on this ledger adds to it. Real incident: the preset's two
+  // review rounds could not be raised from the run config, and approving
+  // resume-review re-asked the same question forever.
+  context.runBudgets = options.budgets ?? {};
   context.maxAttemptsFor = (step) =>
-    workflow.budgets?.maxAttempts?.[step] ?? maxAttemptsPerStep;
+    (context.runBudgets.maxAttempts?.[step] ??
+      workflow.budgets?.maxAttempts?.[step] ??
+      maxAttemptsPerStep) +
+    (ledger.state.budgetExtensions?.[step] ?? 0) +
+    (ledger.state.steps[step]?.infraAttempts ?? 0);
   context.policies = options.policies ?? [];
   context.allowedPaths = options.allowedPaths ?? null;
   context.reviewTriage = options.reviewTriage ?? null;
@@ -240,6 +251,7 @@ function settleOutcome(context, step, outcome, tree, exec) {
     if ((ledger.state.steps[step]?.attempts ?? 0) >= context.maxAttemptsFor(step)) {
       context.waitHuman(`resume-${step}`, [
         `budget exhausted: ${step} failed its final attempt (maxAttempts=${context.maxAttemptsFor(step)}); not routing to fix`,
+        `approving resume-${step} grants one more attempt; rejecting ends the run`,
       ]);
       return null;
     }
@@ -266,13 +278,13 @@ function settleOutcome(context, step, outcome, tree, exec) {
     },
   });
   if (!to) {
-    ledger.append({
-      type: "RUN_TERMINAL",
-      actor: KERNEL,
-      ts: now(),
-      data: { status: "FAILED", reason: `no transition for (${step}, ${outcome})` },
-    });
-    writeRunRecord({ repoRoot: context.repoRoot, ledger, ts: now() });
+    // A workflow without an edge for this outcome is not a verdict on the
+    // candidate; the person decides whether to rerun the step or end the
+    // run. Terminal FAILED here used to kill runs whose reviewer had merely
+    // errored out.
+    context.waitHuman(`resume-${step}`, [
+      `no transition for (${step}, ${outcome}); approve resume-${step} to rerun the step, reject to end the run`,
+    ]);
     return null;
   }
   ledger.append({
@@ -320,6 +332,30 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
       return;
     }
 
+    // Work-level review cap (iteration 09): review rounds are counted across
+    // every run of the work, superseded ones included, so "one run per
+    // round" cannot slip past the per-run budget. Reaching the cap is a
+    // human decision (review once more, or merge/close as-is), not a stop.
+    const workCap = context.runBudgets.reviewRoundsPerWork;
+    if (workCap !== undefined && (stepDef.worker === "reviewer" || step === "review")) {
+      const prior = computeWorkCost(context.repoRoot, ledger.state.run.work, {
+        excludeRun: ledger.state.run.id,
+      });
+      const rounds = prior.reviewRounds + (ledger.state.steps[step]?.attempts ?? 0);
+      const allowed = workCap + (ledger.state.workReviewGrants ?? 0);
+      if (rounds >= allowed) {
+        context.waitHuman(
+          `enter-${step}`,
+          [
+            `work review cap reached: ${rounds} review round(s) across ${prior.runs + 1} run(s) of ${ledger.state.run.work} (budgets.reviewRoundsPerWork=${workCap})`,
+            `approve enter-${step} to review once more, or reject and merge/close the work on the evidence you have`,
+          ],
+          "work-review-cap",
+        );
+        return;
+      }
+    }
+
     const preGate = runPolicyGate(context, "pre", step);
     if (preGate.action === "block") {
       ledger.append({
@@ -341,6 +377,7 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
     if (attempt > maxAttempts) {
       context.waitHuman(`resume-${step}`, [
         `budget exhausted: ${step} would exceed maxAttempts=${maxAttempts}`,
+        `approving resume-${step} grants one more attempt; rejecting ends the run`,
       ]);
       return;
     }
@@ -531,18 +568,53 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
     } else {
       stepStatus = "succeeded";
     }
+    // Infrastructure failure vs candidate failure. A timeout, a crash,
+    // garbage output or the worker's own "environment unavailable" signal
+    // (exit 75, EX_TEMPFAIL) says nothing about the candidate: no failure
+    // fingerprint, no fixer, the attempt is refunded, and a human decides
+    // when the backend is back. Real incidents: a worker backend outage
+    // (review exit 97) and non-JSON reviewer output killed five runs in two
+    // days as "no transition for (review, failed)"; PATH, port and host-load
+    // verify failures dispatched fixers five times.
+    const infra =
+      stepStatus === "timeout" ||
+      stepStatus === "crashed" ||
+      stepStatus === "invalid-output" ||
+      (stepStatus === "failed" && exec.exitCode === 75);
     ledger.append({
       type: "STEP_FINISHED",
       actor: KERNEL,
       ts: now(),
-      data: { step, attempt, status: stepStatus, exitCode: exec.exitCode },
+      data: { step, attempt, status: stepStatus, exitCode: exec.exitCode, ...(infra ? { infra: true } : {}) },
     });
     ledger.append({
       type: "BUDGET_CONSUMED",
       actor: KERNEL,
       ts: now(),
-      data: { kind: "attempts", amount: 1, remaining: maxAttempts - attempt },
+      data: {
+        kind: "attempts",
+        amount: infra ? 0 : 1,
+        remaining: context.maxAttemptsFor(step) - attempt,
+      },
     });
+    if (infra) {
+      const cause =
+        stepStatus === "failed"
+          ? "exit 75 (worker reports its environment unavailable)"
+          : stepStatus === "invalid-output"
+            ? "output is not a worker envelope"
+            : stepStatus;
+      context.waitHuman(
+        `resume-${step}`,
+        [
+          `worker infrastructure failure at ${step}: ${cause}; not a candidate defect, attempt not charged`,
+          ...(tree.dirty ? [`the failed worker left the worktree dirty; inspect before rerunning`] : []),
+          `approve resume-${step} to rerun once the backend/environment is back; reject to end the run`,
+        ],
+        "infra",
+      );
+      return;
+    }
 
     let blockingFindings = [];
     if (envelope?.findings) {
@@ -920,12 +992,51 @@ export function resumeRun(options) {
         });
         return { runId, ledgerPath, state: ledger.state, resumed: true, stale: true, reason: null };
       }
-      const step = resumeStepFromTransition(approval.transition);
+      // An adopted candidate names where to resume (verify, by convention):
+      // the fixer step the request was waiting on has nothing left to do.
+      const step = approval.resumeAt ?? resumeStepFromTransition(approval.transition);
       if (!step || !context.workflow.stepIds.has(step)) {
         throw new OrchestratorError(
           `cannot derive a resume step from approved transition ${approval.transition}`,
         );
       }
+      // An approved resume-<step> on an exhausted budget is the human saying
+      // "one more"; record the grant before driving or the same request
+      // comes straight back (the pilot's app-login runs ended CANCELLED
+      // with their candidates in production because of exactly that).
+      const requestKind = [...ledger.events]
+        .reverse()
+        .find((event) => event.type === "HUMAN_REQUESTED" && event.data.transition === approval.transition)
+        ?.data.kind;
+      if (requestKind === "work-review-cap") {
+        ledger.append({
+          type: "BUDGET_EXTENDED",
+          actor: KERNEL,
+          ts: now(),
+          data: {
+            step,
+            amount: 1,
+            scope: "work",
+            maxAttempts: (context.runBudgets.reviewRoundsPerWork ?? 0) + (state.workReviewGrants ?? 0) + 1,
+            approvalRef: approval.decisionRef,
+          },
+        });
+      } else if (
+        approval.transition.startsWith("resume-") &&
+        (state.steps[step]?.attempts ?? 0) >= context.maxAttemptsFor(step)
+      ) {
+        ledger.append({
+          type: "BUDGET_EXTENDED",
+          actor: KERNEL,
+          ts: now(),
+          data: {
+            step,
+            amount: 1,
+            maxAttempts: context.maxAttemptsFor(step) + 1,
+            approvalRef: approval.decisionRef,
+          },
+        });
+      }
       ledger.append({ type: "RUN_STARTED", actor: KERNEL, ts: now(), data: {} });
       drive(context, step, { skipBoundaryOnce: true });
       return { runId, ledgerPath, state: ledger.state, resumed: true, reason: null };