faberun 0.30.0 → 0.32.0

package/src/plan/template.mjs

@@ -1,7 +1,7 @@
 /**
  * Planning contract templates: the one-node `mode: "discovery"` contracts a
- * plan pipeline runs outside the control session — draft, review, revise (a
- * draft carrying the reviewer's findings), spec authoring, and spec review.
+ * plan pipeline runs outside the control session — draft, review, revise (the
+ * reviewer's findings and the nodes they name), spec authoring, and spec review.
  * Separate from freeze.mjs (which turns an already-built plan into a
  * validated contract on disk) because this module never touches the
  * filesystem or a model: it only assembles the JSON object `validateContract`
@@ -27,11 +27,17 @@ import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../contract/index.mjs
 import { validateDefinitionOfDone } from "../contract/definition-of-done.mjs";
 import { validateFinalVerification, validateSharedVerification } from "../contract/final-verification.mjs";
 import { validateVerificationCommands } from "../contract/verification.mjs";
+import { REVISE_FACT_SELECTION_RULE, REVISE_OPENING, REVISE_PATCH_OPENING, REVISE_PATCH_PHASES_INSTRUCTION, REVISE_PATCH_VENDOR_RULE } from "./revise-context.mjs";
 
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
 /** @typedef {"draft"|"review"|"revise"|"spec-author"|"spec-review"} PlanningKind */
 /** @typedef {"low"|"standard"|"high"} RiskTier */
 /** @typedef {{campaignId: string, phase: string, n: number, goal?: string, cwd?: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, reviewerId?: string, specPath?: string, repoFactsPath?: string, cataloguePath?: string, packageMode?: import("./sizing.mjs").PackageMode, planPath?: string, findingsPath?: string, notesPath?: string, revisePatch?: boolean}} PlanningContractInputs */
+// A revise's planPath names the plan context it starts from: before the
+// first validated plan, the rejected draft, whole; after it, the narrowed
+// context `reviseContextFor` (revise-context.mjs, R4) builds. A revise never
+// reads the repository facts — the plan's readFiles are the selection its
+// drafter drew from the fact set, and the reviser keeps them.
 /** @typedef {{id: string, objective: string, taskKind: string, riskTier: RiskTier, dependsOn: string[], readFiles: string[], writeFiles: string[], scopeAcknowledged: string[], definitionOfDone: import("../contract/definition-of-done.mjs").DefinitionOfDoneItem[], verification: import("../contract/verification.mjs").VerificationCommand[], expectedTurns?: number}} PlanOutputNode */
 /** @typedef {{nodes: PlanOutputNode[], phases?: PlanPhase[], sharedVerification?: import("../contract/verification.mjs").VerificationCommand[], finalVerification?: import("../contract/verification.mjs").VerificationCommand[], findings?: PlanFindingOutput[], justification?: string}} PlanOutput */
 /** @typedef {{id: string, requirementIds: string[], nodeIds?: string[], deliverable: string}} PlanPhase */
@@ -107,7 +113,7 @@ const KIND_ROLE = Object.freeze({
 /** @type {Record<PlanningKind, string[]>} */
 const REQUIRED_INPUTS = Object.freeze({
   draft: ["specPath", "repoFactsPath", "cataloguePath"],
-  revise: ["specPath", "repoFactsPath", "cataloguePath", "findingsPath", "planPath"],
+  revise: ["specPath", "cataloguePath", "findingsPath", "planPath"],
   review: ["specPath", "repoFactsPath", "planPath"],
   "spec-author": ["notesPath"],
   "spec-review": ["specPath"],
@@ -127,10 +133,10 @@ const PLAN_SUITE_SHAPE = '[{argv: [string], cwd?, timeoutSec?, repeat?, env?, mu
 const ID_CHARSET_RULE = 'every id in it (node, phase, node assignment, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
 const PLAN_OUTPUT_SHAPE = `{nodes: [${PLAN_NODE_SHAPE}], phases?: ${PLAN_PHASE_SHAPE}, sharedVerification?: ${PLAN_SUITE_SHAPE}, finalVerification?: ${PLAN_SUITE_SHAPE}, justification?}; ${ID_CHARSET_RULE}`;
 /**
- * What a revise writes instead of the plan again (RM-110). Every node this
- * names is a complete node, because the plan it patches is in the reviser's
- * readFiles and the patch says only what changes: the node shape is
- * `PLAN_NODE_SHAPE`, one home for both strings so they cannot drift.
+ * What a revise writes instead of the plan again (RM-110): complete nodes,
+ * spelled exactly as the plan spells them — `PLAN_NODE_SHAPE`, one home for
+ * both strings so they cannot drift. The patch applies to the whole plan the
+ * pipeline holds; only the reviser's reading narrowed (R4).
  */
 const REVISE_PATCH_SHAPE = `{nodes?: [${PLAN_NODE_SHAPE}], removedNodeIds?: [string], phases?: ${PLAN_PHASE_SHAPE}, sharedVerification?: ${PLAN_SUITE_SHAPE}, finalVerification?: ${PLAN_SUITE_SHAPE}, justification?}; ${ID_CHARSET_RULE}`;
 /**
@@ -161,20 +167,33 @@ const FINDINGS_SHAPE = "[{id, severity, nodeId, text}]";
  * rejected output).
  */
 const REVISE_PLAN_INSTRUCTION = `Return exactly one worker-result JSON object. Put the revised plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`;
-const REVISE_PATCH_INSTRUCTION = `Return exactly one worker-result JSON object. Put the revision in output.patch as ${REVISE_PATCH_SHAPE} and nothing else in output. The patch applies to the plan JSON in readFiles: a node whose id that plan already has replaces it, a new id adds a node, removedNodeIds names each node the plan must no longer have, and a field you omit keeps the value the plan already has. Carry only the nodes and fields a finding requires — a revise that omits what a finding names has not answered it.`;
+const REVISE_PATCH_INSTRUCTION = `Return exactly one worker-result JSON object. Put the revision in output.patch as ${REVISE_PATCH_SHAPE} and nothing else in output. The patch applies to the plan the pipeline holds, not to the context in readFiles: a node whose id that plan already has replaces it, a new id adds a node, removedNodeIds names each node the plan must no longer have, and a field you omit keeps the value the plan already has. The context names the nodes your findings concern (changedNodes) and the dependencies those nodes need (dependencyNodes); dependencyNodes are there to be read, never re-emitted. Carry only the nodes and fields a finding requires — a revise that omits what a finding names has not answered it.`;
+
+/** The phase declaration rule a draft and a whole-plan revise share. */
+const PLAN_PHASES_INSTRUCTION = "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies, the planned node ids it assigns, and the deliverable it produces in one sentence. Every planned node must appear in exactly one phase's nodeIds; a missing, duplicate, or unknown node assignment is refused.";
+
+/** The classification rule a draft and a whole-plan revise share. */
+const PLAN_VENDOR_RULE = "Never name a runtime, harness, model, or vendor anywhere in output.plan.";
 
 /**
- * The instruction list is a frozen table because it is the same for every
- * campaign; only the sizing sentence depends on what kind of package this is.
+ * The frozen instruction table; `instructionsFor` swaps the sizing sentence
+ * by package mode and, for a patch revise (RM-110), the four lines whose
+ * whole plan became the narrowed context (R4, `revise-context.mjs`).
  *
  * @param {PlanningKind} kind
  * @param {PlanningContractInputs} inputs
  * @returns {string[]}
  */
 function instructionsFor(kind, inputs) {
-  const lines = kind !== "revise" || inputs.revisePatch !== true
-    ? INSTRUCTIONS[kind]
-    : INSTRUCTIONS[kind].map((line) => (line === REVISE_PLAN_INSTRUCTION ? REVISE_PATCH_INSTRUCTION : line));
+  let lines = INSTRUCTIONS[kind];
+  if (kind === "revise" && inputs.revisePatch === true) {
+    lines = lines.map((line) => (
+      line === REVISE_OPENING ? REVISE_PATCH_OPENING
+        : line === PLAN_PHASES_INSTRUCTION ? REVISE_PATCH_PHASES_INSTRUCTION
+        : line === REVISE_PLAN_INSTRUCTION ? REVISE_PATCH_INSTRUCTION
+        : line === PLAN_VENDOR_RULE ? REVISE_PATCH_VENDOR_RULE
+        : line));
+  }
   if (inputs.packageMode !== "exploratory") return lines;
   return lines.map((line) => (line === SIZING_INSTRUCTION ? EXPLORATORY_SIZING_INSTRUCTION : line));
 }
@@ -203,6 +222,72 @@ const NAMED_TEST_FILE_RULE = 'A command that filters node:test by name (--test-n
 // references, so the planner names the files that can actually break.
 const COVERING_TEST_RULE = 'repo-facts.json\'s testFiles lists, per test file, the repo-relative modules it is named after and the ones it imports or runs. A node\'s verification names every test file whose covers intersects its writeFiles, not only the one named after the module: node --test <file>, one per covering file, and the enclosing test directory when that set is larger than one verification array holds. A test file that references nothing the node writes is not named there; those are the phase\'s finalVerification, which runs the whole suite once when the phase closes.';
 
+// R4 of the phase-2 reissue: repo-facts.json's `paths` is a byte-limited cut
+// (DEFAULT_MAX_PATH_BYTES in src/plan/repo-facts.mjs), and the finding it
+// answers (judge Sol's `r4-omission-text-legible`) was that a single
+// `truncated` flag described nothing: a dropped manifest and a dropped
+// historical log read the same. The artefact now reports paths and bytes per
+// source kind, so both stages that read it are told to read that report rather
+// than to read an absent path as an absent file.
+/**
+ * What a draft or revise is told about the cut it authors from. The plan is
+ * written against the cut, so a node that needs a file the cut discarded has
+ * to know the path may exist and be absent from `paths` — otherwise the honest
+ * plan it produces is "this repository holds no such file".
+ */
+export const PATH_CUT_RULE = "repo-facts.json's paths is the byte-limited cut of the tracked tree, never the whole index: it keeps every path a requirement's proof or measure names, every test file, and every module the tree references, and reports what the ceiling discarded in pathOmission — paths and bytes in total, and the same two numbers per source kind (document, archived-log, manifest, code, other). Read pathOmission before concluding the tree holds no file of a kind, and never read a path's absence from paths as proof of absence: it may be one the ceiling discarded. The complete index is staged beside the artefact as repo-paths.txt, for a discovery node the plan explicitly authorises to enumerate the tree; a node's readFiles never names it otherwise.";
+/**
+ * The reviewer's half of the same rule. A reviewer only ever sees the
+ * artefact, so the cut is exactly what could make it raise a finding against
+ * the tree rather than against the plan.
+ */
+export const REVIEW_PATH_CUT_RULE = "repo-facts.json's paths is a byte-limited cut of the tracked tree, so a path absent from it is not evidence that the file is absent. pathOmission reports, per source kind (document, archived-log, manifest, code, other), how many paths and how many bytes the cut discarded, and those per-kind numbers sum to its own paths and bytes totals. A finding that a node misses a file the spec implies is only valid when the path is in paths or named by the requirement itself; the complete index is staged beside the artefact as repo-paths.txt for the plan to read if it needs it.";
+
+// measured 2026-09-30: the FX runner truncates a tool result at 8,192 output
+// tokens, and a draft that asked for repo-facts.json's whole paths, testFiles
+// or coverage mapping in one call read the partial it got back as though it
+// were the whole tree. The ceiling is per response, so the rule is scoped to
+// one requirement's decision instead of the artefact at large.
+const REPO_FACTS_QUERY_BOUND_RULE = "Bound every repository-facts query by the current requirement and below the measured 8,192-output-token FX response ceiling: query repo-facts.json one requirement at a time, and read only the exact source and test entries that requirement's decision names, so each individual tool result stays strictly below the ceiling. Never dump all of paths, testFiles, or the testFiles[].covers coverage mapping in one result; split a broad selection into requirement-scoped queries, or answer it with a focused summary or count. A tool result that truncated is not evidence: narrow the query and read again before continuing, because a partial result cannot show what it dropped.";
+
+// R4 of campaign-efficiency phase 4: a worker packet's context is exactly its
+// declared readFiles, so what the drafter names there is the selection of
+// phase facts that worker will see. Nothing said so, which let a node name a
+// path the planner never measured and freeze a packet whose context nothing
+// vouches for; sizing refuses that selection (`sizing_read_outside_fact_set`)
+// and this is the same rule told to the author.
+export const FACT_SELECTION_RULE = "Each node's readFiles is the closed context its worker receives: the node's declared selection from the phase fact set. Select it from repo-facts.json's paths and testFiles, name exactly the files that node must read for its own work, and never name a path the fact set does not hold — sizing refuses a read outside the fact set (sizing_read_outside_fact_set), because a packet's context must be facts the planner measured. Absence from paths is still not proof a file is absent (see the path-cut rule above); it only means the file is not this phase's measured context.";
+
+// R5 of the phase-2 reissue, reissued: this module used to export
+// PLAN_RULE_READ_FILES, the Faberun source and test paths a review packet
+// declared in `readFiles` so its reviewer could read the rules it judged by.
+// A planning packet's readFiles resolve against the repository being planned,
+// so a review contract naming them validated in this repository and nowhere
+// else: an ordinary target checkout could not receive the rules at all, and a
+// path name that matched was read as proof that the target's file held them.
+// The rules travel in the review packet's own `instructions`
+// (INSTRUCTIONS.review) instead, and its readFiles are the target's inputs.
+
+/**
+ * What a review packet says about where its own paths point. The rules it is
+ * held to are stated in it, never pointed at: no path name is a rule, and a
+ * name that matches a file in another repository is not evidence about this
+ * one.
+ */
+const REVIEW_TARGET_PATHS_RULE = "The readFiles and writeFiles of every task packet in this plan resolve against the target repository being planned — the checkout the spec, the repository facts and the plan describe. A file outside that repository is not available to this review, and a path name that happens to match one there proves nothing: never read a matching path name as evidence that the target's file, or any file, holds a rule. Judge the plan against the rules this packet states.";
+
+/**
+ * The freeze-time refusals the rule strings above do not state (`freeze.mjs`,
+ * `proof-scope.mjs`, `sizing.mjs`, `definition-of-done.mjs`). The review is the
+ * only stage that sees the whole plan before it is frozen, so a refusal it
+ * cannot see is a refusal raised a round later, at freeze, with no reviewer
+ * left to repair it.
+ */
+const FREEZE_AND_CONTRACT_RULE = Object.freeze([
+  "A plan freezes only if its Definition of Done is provable: every item declares a proof or judgment: true; a judgment item says in `reason` what no command verifies; a `verification` proof's ref is the zero-based index, or the exact text, of one of that node's own verification commands, never a command the node does not carry; a command proof runs through a shell, not an argv array, so an unquoted value after --test-name-pattern is split into extra words, a proof command that leaves a quote open is refused before it runs, and an inline node -e script that does not parse can never exit 0.",
+  "A verification command fits its evidence and its limits: its timeoutSec is at least 1.5 times what repo-facts.json measured for the same argv, and at most 1800 s; a node's verification holds at most 32 commands. A phase declaration that assigns nodeIds must cover every planned node exactly once, and a single-node plan or a dependency chain deeper than 8 nodes needs plan.justification.",
+]);
+
 // RM-107, measured 2026-09-27 on `safe-to-hand-to-a-friend` phase 1: the phase
 // integrated a red tree -- src/host/preflight.mjs at 840 lines against the 800
 // ceiling, declaredEnvironment exported by seven modules, three test files
@@ -231,7 +316,7 @@ const SCOPE_CLOSURE_RULE = Object.freeze([
 /** @type {Record<PlanningKind, string>} */
 const OBJECTIVES = Object.freeze({
   draft: "Draft an execution plan for this phase: classify every node's taskKind and riskTier from the spec and the repository facts, and propose the dependency graph.",
-  revise: "Revise the plan in readFiles to resolve every one of the reviewer's findings, changing only what a finding requires.",
+  revise: "Resolve every one of the reviewer's findings, changing only what a finding requires.",
   review: "Review this plan against the spec and the repository facts, and report only findings.",
   "spec-author": "Turn free notes into a structured spec document following the spec format.",
   "spec-review": "Review this spec for traceability and completeness, and report only findings.",
@@ -241,29 +326,49 @@ const OBJECTIVES = Object.freeze({
 const INSTRUCTIONS = Object.freeze({
   draft: [
     `Consult the ${TASK_KIND_CATALOGUE_FILE} in readFiles before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
-    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies, the planned node ids it assigns, and the deliverable it produces in one sentence. Every planned node must appear in exactly one phase's nodeIds; a missing, duplicate, or unknown node assignment is refused.",
+    PLAN_PHASES_INSTRUCTION,
     ...SCOPE_CLOSURE_RULE,
     NAMED_TEST_FILE_RULE,
     COVERING_TEST_RULE,
+    PATH_CUT_RULE,
+    FACT_SELECTION_RULE,
+    REPO_FACTS_QUERY_BOUND_RULE,
     ...CONTRACT_VERIFICATION_RULE,
     `Return exactly one worker-result JSON object. Put the plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
-    "Never name a runtime, harness, model, or vendor anywhere in output.plan. taskKind and riskTier are the only classification a draft makes; a routing table assigns a runtime afterward, from those two fields alone.",
+    PLAN_VENDOR_RULE,
     SIZING_INSTRUCTION,
   ],
+  // The revise reads no repository facts (R4): it keeps the plan's own
+  // selections (REVISE_FACT_SELECTION_RULE, revise-context.mjs), and the two
+  // repo-facts rules the draft authors to stay with the stages that read the
+  // facts. The freeze pre-flight holds the revise to both mechanically.
   revise: [
-    "Start from the plan JSON in readFiles, the plan the findings were raised against, and return it with only the changes the findings require. Keep every node id, write file, definitionOfDone item and contract-level suite that no finding asks you to change: a revise that redrafts from the findings alone loses what the plan already got right.",
+    REVISE_OPENING,
     "Read the findings and resolve every one; do not leave a critical or major finding unaddressed.",
-    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies, the planned node ids it assigns, and the deliverable it produces in one sentence. Every planned node must appear in exactly one phase's nodeIds; a missing, duplicate, or unknown node assignment is refused.",
+    PLAN_PHASES_INSTRUCTION,
     ...SCOPE_CLOSURE_RULE,
     NAMED_TEST_FILE_RULE,
-    COVERING_TEST_RULE,
+    REVISE_FACT_SELECTION_RULE,
     ...CONTRACT_VERIFICATION_RULE,
     REVISE_PLAN_INSTRUCTION,
-    "Never name a runtime, harness, model, or vendor anywhere in output.plan.",
+    PLAN_VENDOR_RULE,
     SIZING_INSTRUCTION,
   ],
+  // The rules the plan is judged against, carried as rules. They are the same
+  // strings a draft authors to, because a reviewer that grades against other
+  // wording grades against a different rule; the reviewer adds the two rules
+  // only it can apply (the proof-vs-requirement reading and the path cut) and
+  // the freeze-time refusals no other stage can see before the freeze.
   review: [
-    "You are given only the spec, the repository facts, and the plan under review; you have not seen how the plan was produced or any reasoning behind it. Review the artefact alone.",
+    "You are given only the spec, the repository facts, the plan under review, and the rules stated below; you have not seen how the plan was produced or any reasoning behind it. Review the artefact alone.",
+    REVIEW_TARGET_PATHS_RULE,
+    ...SCOPE_CLOSURE_RULE,
+    NAMED_TEST_FILE_RULE,
+    COVERING_TEST_RULE,
+    REVIEW_PATH_CUT_RULE,
+    ...CONTRACT_VERIFICATION_RULE,
+    ...FREEZE_AND_CONTRACT_RULE,
+    SIZING_INSTRUCTION,
     PROOF_NOT_STRICTER_THAN_REQUIREMENT_RULE,
     `Return exactly one worker-result JSON object. Put your findings in output.findings as ${FINDINGS_SHAPE} and nothing else in output.`,
     "severity must be one of critical, major, minor. Every finding's nodeId must name a node id that actually appears in the plan under review.",
@@ -295,9 +400,16 @@ const NON_GOALS = Object.freeze({
  */
 function readFilesForKind(kind, inputs) {
   if (kind === "draft") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.cataloguePath)];
+  // No repository facts: the reviser keeps the plan's own selections (R4).
+  // planPath is the whole rejected plan before the first validated plan, the
+  // narrowed context `reviseContextFor` builds after.
   if (kind === "revise") {
-    return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.cataloguePath), /** @type {string} */ (inputs.findingsPath), /** @type {string} */ (inputs.planPath)];
+    return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.cataloguePath), /** @type {string} */ (inputs.findingsPath), /** @type {string} */ (inputs.planPath)];
   }
+  // The review's readFiles are the target's own three inputs: the rules it
+  // judges by are in INSTRUCTIONS.review, because a path in this repository
+  // would resolve against the target repository being planned and refuse the
+  // contract in every ordinary checkout (R5, reissued).
   if (kind === "review") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.planPath)];
   if (kind === "spec-author") return [/** @type {string} */ (inputs.notesPath)];
   return [/** @type {string} */ (inputs.specPath)];

package/src/repo/integrate.mjs

@@ -20,6 +20,41 @@ import { candidateWorktreePath } from "../run/paths.mjs";
 const JOURNAL = "integration.jsonl";
 const TERMINAL = new Set(["accepted", "failed", "conflict"]);
 
+/**
+ * The candidate resource — the per-run candidate ref, its single worktree and
+ * the verify→accept transition around them — admits one integration at a
+ * time. The settlement chain serializes callers today; this lock is what
+ * keeps that guarantee true at the resource itself rather than by caller
+ * discipline, so a caller that overlaps two `integrateAttempt` calls for one
+ * run interleaves nothing here: the second transaction verifies only after
+ * the first has accepted (and cleaned up), then reads the moved run ref and
+ * settles as a concurrent move — the verdict it would have earned arriving
+ * second in any order.
+ *
+ * Recovery's bookkeeping cleanups (`cleanupCandidate` on dead records) stay
+ * outside the lock: they run in the recovery loop's own sequence, which no
+ * concurrent integration has ever shared.
+ */
+/** @type {Map<string, Promise<unknown>>} */
+const candidateLocks = new Map();
+
+/**
+ * @template T
+ * @param {string} runDir
+ * @param {() => T | Promise<T>} work
+ * @returns {Promise<T>}
+ */
+function withCandidateLock(runDir, work) {
+  const previous = candidateLocks.get(runDir) ?? Promise.resolve();
+  const settled = previous.then(work, work);
+  const tail = settled.catch(() => {});
+  candidateLocks.set(runDir, tail);
+  void tail.then(() => {
+    if (candidateLocks.get(runDir) === tail) candidateLocks.delete(runDir);
+  });
+  return settled;
+}
+
 /** @typedef {"prepared"|"verified"|"accepted"|"failed"|"conflict"} IntegrationStatus */
 /** @typedef {{schemaVersion: number, transactionId: string, runId: string, node: string, attempt: number, attemptSha: string, branch: string|null, empty: boolean, previousRunRefTip: string, candidateSha: string|null, conflictingPaths: string[], at: string, status?: IntegrationStatus, verificationEvidence?: unknown, acceptedAt?: string}} IntegrationRecord */
 /** @typedef {{passed?: boolean, error?: string, [key: string]: unknown}} CandidateEvidence */
@@ -126,7 +161,7 @@ export async function integrateAttempt({
   if (transaction.conflictingPaths.length) {
     appendRecord(runDir, { ...transaction, status: "conflict", conflictingPaths: transaction.conflictingPaths, verificationEvidence: verificationEvidence ?? null });
     await onConflict?.(transaction);
-    cleanupCandidate(repo, runDir, runId);
+    await withCandidateLock(runDir, () => cleanupCandidate(repo, runDir, runId));
     return { status: "conflict", conflictingPaths: transaction.conflictingPaths };
   }
   return verifyAndAdvance({
@@ -287,7 +322,7 @@ function prepareTransaction({ repo, runId, nodeId, attempt, attemptSha, branch,
   return transaction;
 }
 
-/** @param {{repo: string, runDir: string, runId: string, transaction: IntegrationRecord, verificationEvidence?: unknown, verifyCandidate: CandidateVerifier, onAccepted?: AcceptedCallback, onVerificationFailure?: VerificationFailureCallback, onConcurrentMove?: ConcurrentMoveCallback, interrupt?: (stage: string) => void}} args @returns {Promise<IntegrationResult>} */
+/** @param {{repo: string, runDir: string, runId: string, transaction: IntegrationRecord, verificationEvidence?: unknown, verifyCandidate: CandidateVerifier, onAccepted?: AcceptedCallback, onVerificationFailure?: VerificationFailureCallback, onConcurrentMove?: ConcurrentMoveCallback, interrupt?: (stage: string) => void, exclusive?: boolean}} args @returns {Promise<IntegrationResult>} */
 async function verifyAndAdvance({
   repo,
   runDir,
@@ -299,7 +334,11 @@ async function verifyAndAdvance({
   onVerificationFailure,
   onConcurrentMove,
   interrupt,
+  exclusive = false,
 }) {
+  if (!exclusive) {
+    return withCandidateLock(runDir, () => verifyAndAdvance({ repo, runDir, runId, transaction, verificationEvidence, verifyCandidate, onAccepted, onVerificationFailure, onConcurrentMove, interrupt, exclusive: true }));
+  }
   deleteRef(repo, candidateRefName(runId));
   deleteCandidateWorktree(repo, runDir, runId);
   gitSetRef(repo, candidateRefName(runId), transaction.candidateSha);
@@ -321,11 +360,14 @@ async function verifyAndAdvance({
   const verified = { ...transaction, status: "verified", verificationEvidence: { attempt: verificationEvidence ?? null, candidate: candidateEvidence } };
   appendRecord(runDir, verified);
   interruptStage(interrupt, "before-ref");
-  return advanceVerified({ repo, runDir, runId, transaction: verified, onAccepted, onConcurrentMove, interrupt });
+  return advanceVerified({ repo, runDir, runId, transaction: verified, onAccepted, onConcurrentMove, interrupt, exclusive: true });
 }
 
-/** @param {{repo: string, runDir: string, runId: string, transaction: IntegrationRecord, onAccepted?: AcceptedCallback, onConcurrentMove?: ConcurrentMoveCallback, interrupt?: (stage: string) => void}} args @returns {Promise<IntegrationResult>} */
-async function advanceVerified({ repo, runDir, runId, transaction, onAccepted, onConcurrentMove, interrupt }) {
+/** @param {{repo: string, runDir: string, runId: string, transaction: IntegrationRecord, onAccepted?: AcceptedCallback, onConcurrentMove?: ConcurrentMoveCallback, interrupt?: (stage: string) => void, exclusive?: boolean}} args @returns {Promise<IntegrationResult>} */
+async function advanceVerified({ repo, runDir, runId, transaction, onAccepted, onConcurrentMove, interrupt, exclusive = false }) {
+  if (!exclusive) {
+    return withCandidateLock(runDir, () => advanceVerified({ repo, runDir, runId, transaction, onAccepted, onConcurrentMove, interrupt, exclusive: true }));
+  }
   const current = gitHead(repo, runRefName(runId));
   if (!current) throw new Error(`integration ref is unavailable for ${runId}`);
   if (current === transaction.candidateSha && current !== transaction.previousRunRefTip) {

package/src/report/campaign-brief-estimate.mjs

@@ -21,12 +21,15 @@
 import { collectCompletedExecutionNodes } from "../run/usage.mjs";
 import { asArray, unique } from "../campaign/brief-text.mjs";
 import { scheduleUnderCapacity } from "../campaign/campaign-brief-graph.mjs";
+import { sumCounters } from "../run/usage-windows.mjs";
 
 /** @typedef {import("../run/usage.mjs").CompletedExecutionNode} CompletedExecutionNode */
 /** @typedef {import("../run/usage.mjs").CompletedExecutionPool} CompletedExecutionPool */
 /** @typedef {import("../campaign/campaign-brief.mjs").BriefEstimateInput} BriefEstimateInput */
 /** @typedef {import("../campaign/campaign-brief.mjs").BriefMeasureInput} BriefMeasureInput */
-/** @typedef {BriefEstimateInput & {cost: BriefMeasureInput, duration: BriefMeasureInput, method: string[], assumptions: string[]}} BriefExpenseInput */
+/** @typedef {import("../run/usage.mjs").UsageCounters} UsageCounters */
+/** @typedef {{worker: UsageCounters|null, judge: UsageCounters|null}} BriefUsageRollup */
+/** @typedef {BriefEstimateInput & {cost: BriefMeasureInput, duration: BriefMeasureInput, method: string[], assumptions: string[], usage: BriefUsageRollup}} BriefExpenseInput */
 /** @typedef {Record<string, any>} AnyRecord */
 /** @typedef {"worker"|"judge"} ExecutionRole */
 /** @typedef {{nodeId: string, role: ExecutionRole, taskKind: string, runtimeId: string|null, model: string|null}} AssignedRole */
@@ -90,6 +93,7 @@ export function estimateBriefExpense(options) {
   const bothInsufficient = (reason) => ({
     cost: measure("insufficient data", reason, { provenance: "priced usage.jsonl invocations" }),
     duration: measure("insufficient data", reason, { provenance: "recorded actual node and verification elapsed times" }),
+    usage: { worker: null, judge: null },
     runtimes,
     models,
     effectiveConcurrency,
@@ -118,6 +122,7 @@ export function estimateBriefExpense(options) {
   return {
     cost: costMeasure(assignments, samples),
     duration: durationMeasure(assignments, samples, scheduledNodes, maxParallel, maxConcurrent),
+    usage: usageRollup(assignments, samples),
     runtimes,
     models,
     effectiveConcurrency,
@@ -275,6 +280,47 @@ function comparable(key, samples, measureName) {
   return result;
 }
 
+/**
+ * The usage counters carried through with the cost measure: for each role, the
+ * strict rollup over the same comparable, priced population the cost range
+ * sums, so the usage evidence stands with the cost range or is absent with it.
+ *
+ * @param {AssignedRole[]} assignments
+ * @param {CompletedExecutionNode[]} samples
+ * @returns {BriefUsageRollup}
+ */
+function usageRollup(assignments, samples) {
+  return {
+    worker: roleUsageRollup("worker", assignments, samples),
+    judge: roleUsageRollup("judge", assignments, samples),
+  };
+}
+
+/**
+ * @param {ExecutionRole} role
+ * @param {AssignedRole[]} assignments
+ * @param {CompletedExecutionNode[]} samples
+ * @returns {UsageCounters|null} null when any assigned key of the role lacks the comparable floor
+ */
+function roleUsageRollup(role, assignments, samples) {
+  const keys = assignments.filter((assignment) => assignment.role === role);
+  if (keys.length === 0) return null;
+  const seen = new Set();
+  /** @type {CompletedExecutionNode[]} */
+  const eligible = [];
+  for (const key of keys) {
+    const comparableNodes = comparable(key, samples, "cost");
+    if (comparableNodes.length < SAMPLE_FLOOR) return null;
+    for (const sample of comparableNodes) {
+      const identity = `${sample.runId}\u0000${sample.nodeId}`;
+      if (seen.has(identity)) continue;
+      seen.add(identity);
+      eligible.push(sample);
+    }
+  }
+  return sumCounters(eligible.map((sample) => (role === "worker" ? sample.worker.usage ?? null : sample.judge?.usage ?? null)));
+}
+
 /**
  * @param {AssignedRole[]} assignments
  * @param {CompletedExecutionNode[]} samples

package/src/report/campaign-brief.mjs

@@ -315,12 +315,34 @@ function renderGaps(model) {
   return ["## Gaps", ...lines].join("\n");
 }
 
+/**
+ * The estimate section renders whatever the model carries. `buildEstimate`
+ * always records `costPerAccepted`; a model built before the measure existed
+ * omits it, and the brief says so instead of crashing.
+ *
+ * @param {BriefModel["estimate"]} estimate
+ * @returns {BriefMeasure}
+ */
+function costPerAcceptedMeasure(estimate) {
+  return estimate.costPerAccepted ?? {
+    status: "insufficient data",
+    min: null,
+    max: null,
+    samples: null,
+    reason: "cost per accepted result was not recorded",
+    sourceRuns: [],
+    method: null,
+    provenance: null,
+  };
+}
+
 /**
  * @param {BriefModel} model
  * @returns {string}
  */
 function renderEstimate(model) {
   const { estimate } = model;
+  const costPerAccepted = costPerAcceptedMeasure(estimate);
   const method = estimate.method.length > 0 ? estimate.method.join("; ") : "not recorded";
   const assumptions = estimate.assumptions.length > 0 ? estimate.assumptions.join("; ") : "not recorded";
   return [
@@ -328,7 +350,12 @@ function renderEstimate(model) {
     `- Nodes: ${estimate.nodeCount}`,
     `- Workers: ${estimate.workerCount}`,
     `- Cost: ${renderMeasure(estimate.cost, "usd")}`,
+    // Phase-4 R5: the comparison that matters is cost per accepted result,
+    // reported next to the isolated price so a cheaper model with fewer
+    // accepted results cannot win on price alone.
+    `- Cost per accepted result: ${renderMeasure(costPerAccepted, "usd")}`,
     `- Cost provenance: ${estimate.cost.provenance ?? "not recorded"}`,
+    `- Cost per accepted result provenance: ${costPerAccepted.provenance ?? "not recorded"}`,
     `- Duration: ${renderMeasure(estimate.duration, "minutes")}`,
     `- Duration provenance: ${estimate.duration.provenance ?? "not recorded"}`,
     `- Runtimes: ${estimate.runtimes.length > 0 ? estimate.runtimes.map((id) => `\`${id}\``).join(", ") : "none"}`,
@@ -398,12 +425,14 @@ function link(path) {
 }
 
 /**
- * Escape a table cell and collapse it to one line.
+ * Escape a table cell and collapse it to one line. Exported so the report's
+ * HTML surface (`report-html.mjs`) shares this one home instead of carrying a
+ * byte-identical copy.
  *
  * @param {string} value
  * @returns {string}
  */
-function cell(value) {
+export function cell(value) {
   return value.replace(/\|/gu, "\\|").replace(/\s+/gu, " ").trim();
 }
 

package/src/report/locale.mjs

@@ -182,3 +182,23 @@ export function labelsFor(language) {
   const table = LABELS[language];
   return (key) => table[key] ?? LABELS.en[key] ?? key;
 }
+
+/**
+ * The alert catalogue: the four campaign events that deserve a notification
+ * of their own, registered in the same wording home every notification
+ * phrase is written in. Each alert carries its text per language and the
+ * dedup keys that make one occurrence send once: `campaign` (the campaign
+ * id) plus `episode` (the one id that names the occurrence -- the phase for
+ * a completed phase, the node for exhausted recovery or a needed decision,
+ * the campaign itself for closure). The same occurrence is re-derived on
+ * every render; without the keys it would re-send with it.
+ *
+ * @typedef {{id: string, dedupKeys: ["campaign", "episode"], text: Record<Language, string>}} AlertSpec
+ * @type {AlertSpec[]}
+ */
+export const ALERTS = [
+  { id: "phase-completed", dedupKeys: ["campaign", "episode"], text: { en: "phase completed", pt: "fase concluída" } },
+  { id: "recovery-exhausted", dedupKeys: ["campaign", "episode"], text: { en: "recovery exhausted", pt: "recuperação esgotada" } },
+  { id: "decision-needed", dedupKeys: ["campaign", "episode"], text: { en: "decision needed", pt: "decisão necessária" } },
+  { id: "closure", dedupKeys: ["campaign", "episode"], text: { en: "campaign closed", pt: "campanha encerrada" } },
+];

package/src/report/message.mjs

@@ -124,7 +124,7 @@ export function renderRunProgress(runDir, event) {
   const view = { runDir, runId: event.runId ?? basename(runDir), payload, objectives, snapshots, campaign, label, subject };
 
   const body = event.type === "run.terminal" ? runTerminal(view) : event.type === "attention" ? attention(view) : nodeTerminal(view);
-  const lines = [...body, RULE, footer(view, event.type), ...updateLine(label)];
+  const lines = [...body, ...artifactLines(event.artifacts), RULE, footer(view, event.type), ...updateLine(label)];
   return boundToCeiling(lines);
 }
 
@@ -614,6 +614,18 @@ function formatUsdCompact(value) {
   return formatUsd(value);
 }
 
+/**
+ * The run's readable artifacts, one line each with the glyph the report
+ * command prints beside it. The path is data, not wording, so the line needs
+ * no label and stays out of the operator's language.
+ *
+ * @param {{kind: "html"|"video", path: string}[]|undefined} artifacts
+ * @returns {string[]}
+ */
+function artifactLines(artifacts) {
+  return (artifacts ?? []).map((artifact) => `${artifact.kind === "video" ? "📹" : "📄"} ${artifact.path}`);
+}
+
 /**
  * The delivered bullets are the only block that grows with the run, so they
  * are dropped from the end first when the whole message would exceed the

package/src/report/metrics-report.mjs

@@ -10,9 +10,14 @@
  * many lanes or runtimes prints in the same space as one with few. The
  * dependency runs one way: the projector imports the renderers, and nothing
  * here reads a filesystem path or a projection's inputs.
+ *
+ * The reserve the projection carries (ADR 0011) is policy state, not an
+ * indicator, so it prints on its own line after the indicator set, in the JSON
+ * form beside `indicators` instead of inside it.
  */
 
 /** @typedef {import("../campaign/metrics.mjs").CampaignMetrics} CampaignMetrics */
+/** @typedef {import("../campaign/spend.mjs").ReserveProjection} ReserveProjection */
 /** @typedef {import("../campaign/metrics-command.mjs").MetricsSources} MetricsSources */
 
 /** Schema of the `--json` form; bumped when a consumer would have to change. */
@@ -52,9 +57,41 @@ export function renderMetricsReport(sources, metrics) {
     const missing = Array.isArray(indicator.missingSources) ? ` · missing ${indicator.missingSources.join(", ")}` : "";
     lines.push(`${name.padEnd(NAME_WIDTH)} ${indicator.direction.padEnd(11)} ${formatValue(name, indicator.value).padEnd(24)} · ${records}${unknown}${missing}`);
   }
+  const reserve = projectedReserve(metrics);
+  if (reserve !== undefined) lines.push(renderReserveLine(reserve));
   return `${lines.join("\n")}\n`;
 }
 
+/** @param {CampaignMetrics} metrics @returns {ReserveProjection|undefined} */
+function projectedReserve(metrics) {
+  return /** @type {{reserve?: ReserveProjection}} */ (/** @type {unknown} */ (metrics)).reserve;
+}
+
+/**
+ * The reserve line: the optional balance the campaign configured, what is
+ * still held against future charges, what was released once the real charge
+ * arrived, and the part of a late charge that went past its reservation. It
+ * says outright that the reserve is not an absolute cap, so a blocked dispatch
+ * is never read as provider-side enforcement of a ceiling (ADR 0011).
+ *
+ * @param {ReserveProjection} reserve
+ * @returns {string}
+ */
+function renderReserveLine(reserve) {
+  const incomplete = reserve.missingSources !== undefined;
+  const rounded = (/** @type {number} */ value) => String(Math.round(value * 100) / 100);
+  // A campaign that configured no balance never had one, which is a different
+  // fact from a balance the preserved sources cannot show.
+  const configured = reserve.configuredUsd === null ? "none" : rounded(reserve.configuredUsd);
+  const money = (/** @type {number|null} */ value) => value === null
+    ? (incomplete ? "unknown" : "none")
+    : rounded(value);
+  const reservations = reserve.heldCount + reserve.reconciledCount;
+  const counts = `${reservations} reservation${reservations === 1 ? "" : "s"}${incomplete ? ` · missing ${reserve.missingSources?.join(", ")}` : ""}`;
+  const value = `configured=${configured} held=${money(reserve.heldUsd)} released=${money(reserve.releasedUsd)} charged=${money(reserve.chargedUsd)} late=${money(reserve.lateChargeUsd)}`;
+  return `${"reserve".padEnd(NAME_WIDTH)} ${"informative".padEnd(11)} ${value.padEnd(24)} · ${counts} · not an absolute cap`;
+}
+
 /** @param {{unknownCount: number, unknownFractionByReason?: Record<string, number>}} indicator @returns {string} */
 function unknownCostSuffix(indicator) {
   const reasons = Object.entries(indicator.unknownFractionByReason ?? {})
@@ -80,6 +117,7 @@ export function renderMetricsJson(sources, metrics) {
     missingSources,
     sameProviderReviewNodeCount: sameProviderReviewNodeIds(sources).length,
     sameProviderReviewNodeIds: sameProviderReviewNodeIds(sources),
+    reserve: projectedReserve(metrics) ?? null,
     indicators: metrics,
   })}\n`;
 }