@haiyangbg/buildbeat 3.3.1 → 4.0.0

package/src/v2/runtime/decisions.js

@@ -6,12 +6,26 @@
 // as a DECISION_RECORDED event and as a line in the Git plane
 // (delivery/work/<work>/decisions.jsonl).
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+} from "node:fs";
 import { join } from "node:path";
 
-import { evaluatePolicies, sha256Text } from "../policy/policy.js";
+import {
+  deliveryChecks,
+  evaluatePolicies,
+  sha256Text,
+} from "../policy/policy.js";
 import { EventLedger } from "../storage/event-ledger.js";
-import { acquireLock, readback, releaseLock } from "../workspace/workspace-manager.js";
+import {
+  acquireLock,
+  readback,
+  releaseLock,
+} from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
 import { resolveRepoRef } from "./repo-ref.js";
 
@@ -39,7 +53,9 @@ function openWaiting(repoRoot, runId) {
     throw new DecisionError(`no ledger for run ${runId}`);
   }
   if (ledger.state.terminal) {
-    throw new DecisionError(`run ${runId} is already terminal (${ledger.state.terminal.status})`);
+    throw new DecisionError(
+      `run ${runId} is already terminal (${ledger.state.terminal.status})`,
+    );
   }
   if (!ledger.state.pendingHuman) {
     throw new DecisionError(`run ${runId} has no pending human request`);
@@ -47,13 +63,50 @@ function openWaiting(repoRoot, runId) {
   return ledger;
 }
 
+// Work artifacts whose digests a run froze at creation: the plan or work.md
+// it was started on and, for the legacy controlled safeguards, intent.md.
+// `committed` marks the ones start verified in the base checkout, so the
+// candidate must still carry them unchanged.
+export function boundArtifacts(run, planDigest = run.planDigest) {
+  const checks = run.deliveryChecks;
+  if (!checks) return [];
+  const bound = [];
+  if (checks.requireAcceptance || planDigest !== "UNVERIFIED") {
+    bound.push({
+      artifact: checks.artifact,
+      digest: planDigest,
+      committed: checks.requireAcceptance,
+    });
+  }
+  if (checks.requireIntent && checks.artifact !== "work") {
+    bound.push({
+      artifact: "intent",
+      digest: run.intentDigest ?? "UNVERIFIED",
+      committed: true,
+    });
+  }
+  return bound;
+}
+
+function digestOf(file) {
+  return existsSync(file) ? sha256Text(readFileSync(file, "utf8")) : null;
+}
+
 function recordDecisionFile(repoRoot, work, line) {
   const dir = join(repoRoot, "delivery", "work", work);
   mkdirSync(dir, { recursive: true });
-  appendFileSync(join(dir, "decisions.jsonl"), `${JSON.stringify(line)}\n`, "utf8");
+  appendFileSync(
+    join(dir, "decisions.jsonl"),
+    `${JSON.stringify(line)}\n`,
+    "utf8",
+  );
 }
 
-export function approveRun(repoRoot, runId, { by = "human", transition, ts, policies } = {}) {
+export function approveRun(
+  repoRoot,
+  runId,
+  { by = "human", transition, ts, policies } = {},
+) {
   // Read, check and write under the run lock: a ledger read before the
   // lock may be stale by the time it is written to.
   acquireLock(repoRoot, runId);
@@ -71,14 +124,19 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
       );
     }
     const bound = ledger.state.workspaces[runId];
-    const worktreePath = bound ? resolveRepoRef(repoRoot, bound.worktreePath) : null;
+    const worktreePath = bound
+      ? resolveRepoRef(repoRoot, bound.worktreePath)
+      : null;
     if (!bound || !existsSync(worktreePath)) {
-      throw new DecisionError(`worktree missing for ${runId}; cannot verify the approval subject`);
+      throw new DecisionError(
+        `worktree missing for ${runId}; cannot verify the approval subject`,
+      );
     }
     const tree = readback(worktreePath);
     const when = ts ?? new Date().toISOString();
     if (tree.dirty || tree.head !== pending.subject.candidate) {
-      const lastEvidence = ledger.state.evidence[ledger.state.evidence.length - 1];
+      const lastEvidence =
+        ledger.state.evidence[ledger.state.evidence.length - 1];
       ledger.append({
         type: "HUMAN_REQUESTED",
         actor: KERNEL,
@@ -90,19 +148,53 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
             planDigest: ledger.state.run.planDigest,
             evidenceDigest: lastEvidence?.digest ?? "UNVERIFIED",
           },
-          reasons: ["subject changed since the request; review the new state before approving"],
+          reasons: [
+            "subject changed since the request; review the new state before approving",
+          ],
           kind: pending.kind,
         },
       });
-      return { approved: false, refreshed: true, subject: ledger.state.pendingHuman.subject };
+      return {
+        approved: false,
+        refreshed: true,
+        subject: ledger.state.pendingHuman.subject,
+      };
+    }
+
+    // Both the accepted copy (main checkout) and the candidate's copy must
+    // still be the bytes bound at creation: a builder or fixer that edits
+    // the work artifact in its worktree must not carry a different scope
+    // into a final approval.
+    const frozenChecks = ledger.state.run.deliveryChecks;
+    for (const { artifact, digest, committed } of boundArtifacts(
+      ledger.state.run,
+      pending.subject.planDigest,
+    )) {
+      const rel = join(
+        "delivery",
+        "work",
+        ledger.state.run.work,
+        `${artifact}.md`,
+      );
+      if (digestOf(join(repoRoot, rel)) !== digest) {
+        throw new DecisionError(
+          `work artifact changed since the run was created (${artifact}.md); accept the new scope and start a new attempt`,
+        );
+      }
+      if (committed && digestOf(join(worktreePath, rel)) !== digest) {
+        throw new DecisionError(
+          `the candidate changed the bound ${artifact}.md; restore the accepted version in the candidate, or accept the new scope and start a new attempt`,
+        );
+      }
     }
 
     // Transition policies are enforced at the moment of stamping: an
     // approval that a LOCAL_ENFORCED policy forbids is refused, not logged.
     const policyRows = evaluatePolicies(
-      policies ?? [],
+      frozenChecks ? deliveryChecks(frozenChecks) : (policies ?? []),
       { type: "transition", appliesTo: pending.transition },
       {
+        repoRoot,
         state: ledger.state,
         candidate: pending.subject.candidate,
         workDir: join(repoRoot, "delivery", "work", ledger.state.run.work),
@@ -167,7 +259,8 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
         ts: when,
         data: {
           status: "SUCCEEDED",
-          reason: "final decision approved; the external action (merge) stays manual",
+          reason:
+            "final decision approved; the external action (merge) stays manual",
         },
       });
       writeRunRecord({ repoRoot, ledger, ts: when });
@@ -195,40 +288,64 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
 // 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 } = {}) {
+export function adoptCandidate(
+  repoRoot,
+  runId,
+  { sha, by = "human", resumeAt, ts } = {},
+) {
   acquireLock(repoRoot, runId);
   try {
     if (!sha || typeof sha !== "string" || sha.length < 7) {
-      throw new DecisionError("adopt requires a commit sha (at least 7 characters)");
+      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)");
+      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");
+      throw new DecisionError(
+        "adopt is for a run waiting before fix/verify, not at the merge decision",
+      );
     }
     const bound = ledger.state.workspaces[runId];
-    const worktreePath = bound ? resolveRepoRef(repoRoot, bound.worktreePath) : null;
+    const worktreePath = bound
+      ? resolveRepoRef(repoRoot, bound.worktreePath)
+      : null;
     if (!bound || !existsSync(worktreePath)) {
-      throw new DecisionError(`worktree missing for ${runId}; cannot adopt a candidate`);
+      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");
+      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`);
+      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];
+    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 },
+        data: {
+          workspaceId: runId,
+          base: bound.base,
+          candidate: tree.head,
+          adopted: true,
+        },
       });
     }
     const subject = {
@@ -261,7 +378,13 @@ export function adoptCandidate(repoRoot, runId, { sha, by = "human", resumeAt, t
       adopted: tree.head,
       resumeAt,
     });
-    return { adopted: tree.head, decisionRef, transition: pending.transition, resumeAt, state: ledger.state };
+    return {
+      adopted: tree.head,
+      decisionRef,
+      transition: pending.transition,
+      resumeAt,
+      state: ledger.state,
+    };
   } finally {
     releaseLock(repoRoot, runId);
   }
@@ -271,13 +394,26 @@ export function adoptCandidate(repoRoot, runId, { sha, by = "human", resumeAt, t
 // file's current digest in the Git plane. If the file changes afterwards,
 // artifact.accepted evaluates false again — acceptance cannot go stale
 // silently (closes MVP DoD #1 with staleness included).
-export function acceptArtifact(repoRoot, workId, artifact, { by = "human", ts } = {}) {
+export function acceptArtifact(
+  repoRoot,
+  workId,
+  artifact,
+  { by = "human", ts } = {},
+) {
+  if (!["work", "intent", "plan", "spec"].includes(artifact))
+    throw new DecisionError("artifact must be work, intent, plan or spec");
   const filePath = join(repoRoot, "delivery", "work", workId, `${artifact}.md`);
   if (!existsSync(filePath)) {
     throw new DecisionError(`artifact file missing: ${filePath}`);
   }
   const digest = sha256Text(readFileSync(filePath, "utf8"));
-  const decisionsPath = join(repoRoot, "delivery", "work", workId, "decisions.jsonl");
+  const decisionsPath = join(
+    repoRoot,
+    "delivery",
+    "work",
+    workId,
+    "decisions.jsonl",
+  );
   const count = existsSync(decisionsPath)
     ? readFileSync(decisionsPath, "utf8").split("\n").filter(Boolean).length
     : 0;
@@ -298,19 +434,30 @@ export function acceptArtifact(repoRoot, workId, artifact, { by = "human", ts }
 // acceptance is written, and each artifact keeps its own digest-bound line.
 export function acceptArtifacts(repoRoot, workId, artifacts, options = {}) {
   const unique = [...new Set(artifacts)];
+  if (unique.some((name) => !["work", "intent", "plan", "spec"].includes(name)))
+    throw new DecisionError("artifact must be work, intent, plan or spec");
   if (unique.length === 0) {
     throw new DecisionError("no artifact to accept");
   }
   const missing = unique
-    .map((artifact) => join(repoRoot, "delivery", "work", workId, `${artifact}.md`))
+    .map((artifact) =>
+      join(repoRoot, "delivery", "work", workId, `${artifact}.md`),
+    )
     .filter((filePath) => !existsSync(filePath));
   if (missing.length > 0) {
     throw new DecisionError(`artifact file missing: ${missing.join(", ")}`);
   }
-  return unique.map((artifact) => ({ artifact, ...acceptArtifact(repoRoot, workId, artifact, options) }));
+  return unique.map((artifact) => ({
+    artifact,
+    ...acceptArtifact(repoRoot, workId, artifact, options),
+  }));
 }
 
-export function rejectRun(repoRoot, runId, { by = "human", transition, reason, ts } = {}) {
+export function rejectRun(
+  repoRoot,
+  runId,
+  { by = "human", transition, reason, ts } = {},
+) {
   acquireLock(repoRoot, runId);
   try {
     const ledger = openWaiting(repoRoot, runId);
@@ -347,7 +494,10 @@ export function rejectRun(repoRoot, runId, { by = "human", transition, reason, t
       type: "RUN_TERMINAL",
       actor: KERNEL,
       ts: when,
-      data: { status: "CANCELLED", reason: `rejected by ${by}${reason ? `: ${reason}` : ""}` },
+      data: {
+        status: "CANCELLED",
+        reason: `rejected by ${by}${reason ? `: ${reason}` : ""}`,
+      },
     });
     writeRunRecord({ repoRoot, ledger, ts: when });
     return { rejected: true, decisionRef, state: ledger.state };
@@ -373,7 +523,11 @@ export function listInbox(repoRoot) {
       continue;
     }
     const state = ledger.state;
-    if (state.run && state.run.status === "WAITING_HUMAN" && state.pendingHuman) {
+    if (
+      state.run &&
+      state.run.status === "WAITING_HUMAN" &&
+      state.pendingHuman
+    ) {
       rows.push({
         run: state.run.id,
         work: state.run.work,

package/src/v2/runtime/findings.js

@@ -109,7 +109,10 @@ export function sameIssue(a, b) {
 }
 
 export function readFindingsAccount(repoRoot, workId) {
-  const filePath = accountPath(repoRoot, workId);
+  return readFindingsFile(accountPath(repoRoot, workId));
+}
+
+export function readFindingsFile(filePath) {
   if (!existsSync(filePath)) {
     return [];
   }

package/src/v2/runtime/notify.js

@@ -8,6 +8,8 @@
 // config), payloads carry identifiers and the next reply — never candidate
 // content, never logs.
 
+import { payloadFor } from "../adapters/notification-payload.js";
+import { currentScreenshots } from "../policy/policy.js";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -73,6 +75,18 @@ export function subscribes(config, event) {
   return Boolean(config?.channels.some((channel) => channel.events.includes(event)));
 }
 
+// Screenshot evidence recorded for a candidate: what a person deciding on a
+// UI change should look at. References and digests only, never the images.
+export function candidateScreenshots(state, candidate) {
+  if (!candidate) {
+    return [];
+  }
+  return currentScreenshots(state.evidence ?? [], candidate).map((item) => ({
+    ref: item.ref,
+    digest: item.digest,
+  }));
+}
+
 // 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 }) {
@@ -82,17 +96,34 @@ export function nextReply({ repoLabel, state }) {
   }
   const runId = state.run.id;
   const lines = [];
-  if (pending.kind === "finding-triage" || pending.kind === "review-not-converging") {
-    lines.push(`buildbeat findings list --repo ${repoLabel} --work ${state.run.work}`);
+  const triage = pending.kind === "finding-triage" || pending.kind === "review-not-converging";
+  // A ledger without frozen safeguards was written by 3.x: this runtime
+  // refuses to approve or resume it, so offer the spellings its original
+  // runtime understands (reject works on both).
+  if (!state.run.deliveryChecks) {
+    const legacy = "   # legacy 3.x run: use its original 3.3.1 runtime (docs/MIGRATION.md)";
+    if (triage) {
+      lines.push(
+        `buildbeat findings adjudicate --repo ${repoLabel} --work ${state.run.work} --fingerprint <fp> --action accept|dismiss --by <you>${legacy}`,
+      );
+    }
     lines.push(
-      `buildbeat findings adjudicate --repo ${repoLabel} --work ${state.run.work} --fingerprint <fp> --action accept|dismiss --by <you>`,
+      `buildbeat approve --repo ${repoLabel} --run ${runId} --transition ${pending.transition} --by <you>${legacy}`,
+    );
+    lines.push(`buildbeat reject --repo ${repoLabel} --run ${runId} --reason <why> --by <you>`);
+    return lines;
+  }
+  if (triage) {
+    lines.push(`buildbeat status --repo ${repoLabel} --work ${state.run.work}`);
+    lines.push(
+      `buildbeat decide --repo ${repoLabel} --work ${state.run.work} --fingerprint <fp> --action accept|dismiss --by <you>`,
     );
   }
   lines.push(
-    `buildbeat 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>"),
+    `buildbeat decide --action approve --repo ${repoLabel} --run ${runId} --transition ${pending.transition} --by <you>` +
+      (pending.kind === "final-decision" ? "   # merge-ready; merge/push stay yours" : "   # then: run --config <run-config.yaml>"),
   );
-  lines.push(`buildbeat reject --repo ${repoLabel} --run ${runId} --reason <why> --by <you>`);
+  lines.push(`buildbeat decide --action reject --repo ${repoLabel} --run ${runId} --reason <why> --by <you>`);
   return lines;
 }
 
@@ -108,11 +139,16 @@ export function buildNotification(kind, { repoLabel, state, detail = {} }) {
   };
   if (kind === "HUMAN_REQUESTED") {
     const pending = state.pendingHuman;
+    const screenshots = candidateScreenshots(
+      state,
+      pending?.subject?.candidate ?? null,
+    );
     return {
       ...base,
       title: `[BuildBeat] ${run.id} 等你拍板：${pending?.transition ?? "?"}`,
       reasons: pending?.reasons ?? [],
       candidate: pending?.subject?.candidate ?? null,
+      ...(screenshots.length > 0 ? { screenshots } : {}),
       nextReply: nextReply({ repoLabel, state }),
     };
   }
@@ -141,36 +177,6 @@ export function buildNotification(kind, { repoLabel, state, detail = {} }) {
   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;