faberun 0.3.0

package/src/engine/scope.mjs

@@ -0,0 +1,378 @@
+/**
+ * The write boundary: what a node was allowed to touch, what it actually
+ * touched, and what to do when those differ.
+ *
+ * Scope is advisory by design -- an unexpected write is recorded as a finding
+ * and shown to the judge, not treated as a crime -- with one exception:
+ * `resolveUnknownEffect` decides whether an invocation whose effect is unproven
+ * may be replayed at all, and a dirty scope there is a refusal.
+ */
+import { SETTLED } from "./prompts.mjs";
+import { appendTransitionEvent, recordExecutionOverride, transition, writeNode } from "./state.mjs";
+import { attemptWorkspace } from "../repo/worktree.mjs";
+
+import { errorCode, errorMessage, excerpt } from "../util.mjs";
+import { executeControllerVerification } from "./verify.mjs";
+import { providerReceiptsFromInvocationTail, settleInvocation } from "../run/operations.mjs";
+import { readJson } from "../run/store.mjs";
+import { scopeFindingFromScope } from "../contract/scope-findings.mjs";
+import { captureWorkspaceScope, compareWorkspaceSnapshot, validateWorkspaceScopeBoundary } from "../repo/workspace.mjs";
+
+/** @typedef {import("../contract/index.mjs").BoundedScope} BoundedScope */
+/** @typedef {import("./lifecycle.mjs").Invocation} Invocation */
+/** @typedef {import("./lifecycle.mjs").Job} Job */
+/** @typedef {import("../cli.mjs").LockHandle} LockHandle */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("../run/usage.mjs").RecoveryOutcome} RecoveryOutcome */
+/** @typedef {import("../repo/workspace.mjs").ScopeComparison} ScopeComparison */
+/** @typedef {import("../contract/index.mjs").TaskPacket} TaskPacket */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
+/** @typedef {import("../repo/workspace.mjs").WorkspaceScopeBoundary} WorkspaceScopeBoundary */
+/** @typedef {import("../repo/workspace.mjs").WorkspaceSnapshot} WorkspaceSnapshot */
+
+/**
+ * @param {NodeSnapshot} state
+ * @returns {string|null}
+ */
+export function sourceWorkerRuntime(state) {
+  return [...(state.invocations ?? [])].reverse().find((invocation) => invocation.phase === "worker")?.runtimeId
+    ?? state.runtime?.id
+    ?? null;
+}
+/**
+ * @param {ScopeComparison} scope
+ * @param {import("../repo/workspace.mjs").WorkspaceScopeBoundary} boundary
+ * @returns {BoundedScope}
+ */
+function boundedScope(scope, boundary) {
+  return {
+    boundary,
+    changedPaths: scope.changedPaths.slice(0, 64),
+    unexpectedPaths: scope.unexpectedPaths.slice(0, 64),
+    changedPathCount: scope.changedPaths.length,
+    unexpectedPathCount: scope.unexpectedPaths.length,
+    truncated: scope.changedPaths.length > 64 || scope.unexpectedPaths.length > 64,
+  };
+}
+/**
+ * @param {import("../repo/workspace.mjs").WorkspaceScopeBoundary} boundary
+ * @returns {BoundedScope}
+ */
+export function emptyScope(boundary) {
+  if (!boundary) throw Object.assign(new Error("worker scope boundary is missing"), { code: "scope_boundary_missing" });
+  return {
+    boundary,
+    changedPaths: [],
+    unexpectedPaths: [],
+    changedPathCount: 0,
+    unexpectedPathCount: 0,
+    truncated: false,
+  };
+}
+/**
+ * @param {ValidatedContract} contract
+ * @returns {Map<string, import("../repo/workspace.mjs").WorkspaceScopeBoundary>}
+ */
+export function captureNodeScopeBoundaries(contract) {
+  return new Map(contract.nodes.map((node) => [node.id, captureWorkspaceScope(contract.cwd, workerScope(node.taskPacket))]));
+}
+/**
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot|undefined} state
+ * @returns {import("../repo/workspace.mjs").WorkspaceScopeBoundary}
+ */
+export function persistedScopeBoundary(contract, node, state, workspace = contract.cwd) {
+  const boundary = state?.scope?.boundary;
+  if (!boundary) throw Object.assign(new Error(`node ${node.id} has no persisted worker scope boundary`), { code: "scope_boundary_missing" });
+  return validateWorkspaceScopeBoundary(workspace, boundary, workerScope(node.taskPacket));
+}
+/**
+ * @param {import("../contract/index.mjs").TaskPacket} taskPacket
+ * @returns {{files: string[], roots: string[]}}
+ */
+export function workerScope(taskPacket) {
+  return {
+    files: taskPacket.writeFiles ?? [],
+    roots: taskPacket.writeRoots ?? [],
+  };
+}
+/**
+ * @param {ValidatedContract} contract
+ * @param {string} runDir
+ * @param {Job} job
+ * @param {LockHandle} lock
+ * @param {{deferViolation?: boolean}} [options]
+ * @returns {boolean}
+ */
+export function checkWorkerScope(contract, runDir, job, lock, options = {}) {
+  if (job.scopeChecked) return !job.scopeViolation;
+  job.scopeChecked = true;
+  const state = job.state;
+  try {
+    const baseline = /** @type {WorkspaceSnapshot|undefined} */ (job.scopeBaseline ?? (job.invocation.snapshotPath ? readJson(job.invocation.snapshotPath) : null));
+    if (!baseline) throw Object.assign(new Error("worker scope snapshot is missing"), { code: "scope_snapshot_missing" });
+    const boundary = persistedScopeBoundary(contract, job.node, state, job.cwd);
+    const scope = compareWorkspaceSnapshot(baseline, job.cwd, { ...workerScope(job.node.taskPacket), boundary });
+    const bounded = boundedScope(scope, boundary);
+    state.scope = bounded;
+    if (!scope.unexpectedPaths.length) return true;
+    job.scopeViolation = true;
+    // A completed attempt whose controller verification passes never fails
+    // on scope alone (TECH-SPEC lean, rule 1): the caller defers the verdict
+    // until verification has run and records an advisory finding instead.
+    if (options.deferViolation) return true;
+    const shown = bounded.unexpectedPaths.slice(0, 8).join(", ");
+    const message = `unexpected paths changed (${scope.unexpectedPaths.length}): ${shown}`;
+    if (!SETTLED.has(state.status)) {
+      transition(runDir, state, "failed", { phase: "worker", error: { code: "unexpected_write", message: excerpt(message) } }, lock);
+      appendTransitionEvent(runDir, state, "failed", "failed", {
+        unexpectedPaths: bounded.unexpectedPaths,
+        unexpectedPathCount: bounded.unexpectedPathCount,
+      }, lock);
+    }
+    return false;
+  } catch (error) {
+    job.scopeViolation = true;
+    if (!SETTLED.has(state.status)) {
+      transition(runDir, state, "failed", { phase: "worker", error: { code: /** @type {string} */ (errorCode(error) ?? "scope_snapshot_invalid"), message: excerpt(errorMessage(error)) } }, lock);
+    }
+    return false;
+  }
+}
+/**
+ * A result-only continuation is not implementation work. Its baseline is
+ * captured immediately before that single turn, so every workspace change is
+ * outside its authority (the run-owned result file is ignored by snapshots).
+ *
+ * @param {ValidatedContract} contract
+ * @param {string} runDir
+ * @param {Job} job
+ * @param {LockHandle} lock
+ * @param {string} [label]
+ * @returns {boolean}
+ */
+export function checkResultMaterializationScope(contract, runDir, job, lock, label = "result materialization") {
+  if (job.scopeChecked) return !job.scopeViolation;
+  job.scopeChecked = true;
+  const state = job.state;
+  try {
+    const baseline = /** @type {WorkspaceSnapshot|undefined} */ (job.recoveryBaseline ?? (job.invocation.snapshotPath ? readJson(job.invocation.snapshotPath) : null));
+    if (!baseline) throw Object.assign(new Error(`${label} scope snapshot is missing`), { code: "scope_snapshot_missing" });
+    const scope = compareWorkspaceSnapshot(baseline, job.cwd);
+    if (!scope.changedPaths.length) return true;
+    job.scopeViolation = true;
+    const shown = scope.changedPaths.slice(0, 8).join(", ");
+    transition(runDir, state, "failed", {
+      phase: "worker",
+      error: { code: "unexpected_write", message: excerpt(`${label} changed workspace paths (${scope.changedPaths.length}): ${shown}`) },
+    }, lock);
+    return false;
+  } catch (error) {
+    job.scopeViolation = true;
+    transition(runDir, state, "failed", {
+      phase: "worker",
+      error: { code: /** @type {string} */ (errorCode(error) ?? "scope_snapshot_invalid"), message: excerpt(errorMessage(error)) },
+    }, lock);
+    return false;
+  }
+}
+/**
+ * Materialization can reuse prior controller evidence only when that evidence
+ * survived the same worker attempt. A fresh worker clears verification; the
+ * retained, completed record is therefore the bounded same-attempt proof.
+ * Judge evidence cannot currently carry that identity, so gated nodes fail
+ * closed and run their normal judge phase.
+ *
+ * @param {NodeSnapshot} state
+ * @param {ValidatedNode} node
+ * @returns {boolean}
+ */
+export function canReuseResultEvidence(state, node) {
+  if (state.verification?.completed !== true || state.verification.passed !== true) return false;
+  return !node.gate.enabled;
+}
+/**
+ * Compare the current workspace against the persisted worker baseline without
+ * transitioning the node. Shared by the unexpected-write failure path and the
+ * unknown_effect replay gate.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {Invocation|undefined} invocation
+ * @param {{strict?: boolean}} [options]
+ * @returns {{ok: true}|{ok: false, code: string, detail: string, unexpectedPaths?: string[], unexpectedPathCount?: number, changedPaths?: string[], changedPathCount?: number}}
+ */
+function evaluatePersistedWorkerScope(contract, node, state, invocation, options = {}) {
+  const strict = options.strict === true;
+  try {
+    const baseline = invocation?.snapshotPath
+      ? /** @type {WorkspaceSnapshot} */ (readJson(invocation.snapshotPath))
+      : null;
+    if (!baseline) return { ok: false, code: "scope_snapshot_missing", detail: "worker scope snapshot is missing" };
+    const workspace = attemptWorkspace(state) ?? invocation?.workspace ?? contract.cwd;
+    const boundary = persistedScopeBoundary(contract, node, state, workspace);
+    const scope = compareWorkspaceSnapshot(baseline, workspace, { ...workerScope(node.taskPacket), boundary });
+    const bounded = boundedScope(scope, boundary);
+    state.scope = bounded;
+    if (!scope.unexpectedPaths.length && (!strict || scope.changedPaths.length === 0)) return { ok: true };
+    if (scope.unexpectedPaths.length) {
+      const shown = bounded.unexpectedPaths.slice(0, 8).join(", ");
+      return {
+        ok: false,
+        code: "unexpected_write",
+        detail: `unexpected paths changed (${scope.unexpectedPaths.length}): ${shown}`,
+        unexpectedPaths: bounded.unexpectedPaths,
+        unexpectedPathCount: bounded.unexpectedPathCount,
+      };
+    }
+    return {
+      ok: false,
+      code: "declared_paths_changed",
+      detail: `declared workspace paths changed across the ambiguous window (${scope.changedPaths.length}): ${bounded.changedPaths.slice(0, 8).join(", ")}`,
+      changedPaths: bounded.changedPaths,
+      changedPathCount: bounded.changedPathCount,
+    };
+  } catch (error) {
+    return { ok: false, code: /** @type {string} */ (errorCode(error) ?? "scope_snapshot_invalid"), detail: errorMessage(error) };
+  }
+}
+/**
+ * Gate a worker restart behind proof that the replay cannot duplicate effects.
+ * Declared workspace changes are not proof of absence: any change across the
+ * ambiguous window (declared or unexpected) or a missing scope baseline is
+ * reconciled as terminal attention instead of silently replaying the attempt.
+ * Returns true when the restart must not proceed (the node was blocked).
+ *
+ * @param {ValidatedContract} contract
+ * @param {string} runDir
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {Invocation|undefined} invocation
+ * @param {RecoveryOutcome} recovery
+ * @param {Record<string, unknown>|undefined} persistedRecovery
+ * @param {LockHandle} lock
+ * @returns {boolean}
+ */
+export function reconcileAmbiguousWorkerRestart(contract, runDir, node, state, invocation, recovery, persistedRecovery, lock) {
+  const evaluation = evaluatePersistedWorkerScope(contract, node, state, invocation, { strict: true });
+  if (evaluation.ok) return false;
+  const invocationId = recovery.invocationId ?? invocation?.id;
+  const reason = evaluation.code === "declared_paths_changed"
+    ? `declared workspace changes across the ambiguous window are not proof that replay cannot duplicate effects for node ${state.id}: ${evaluation.detail}`
+    : evaluation.code === "unexpected_write"
+      ? `workspace moved outside the declared write scope across the ambiguous window: ${evaluation.detail}`
+      : `the ambiguous worker window for node ${state.id} cannot prove replay safety: ${evaluation.detail}`;
+  if (invocationId) {
+    settleInvocation(runDir, invocationId, {
+      status: "reconciled",
+      usage: invocation?.usage ?? recovery.usage ?? null,
+      costUsd: typeof invocation?.costUsd === "number" ? invocation.costUsd : recovery.costUsd ?? null,
+      receipts: providerReceiptsFromInvocationTail(contract, invocation),
+      unknownEffect: true,
+      classification: "unknown_effect",
+      reason,
+    });
+  }
+  if (!persistedRecovery) recordExecutionOverride(runDir, state, {
+    kind: "recovery",
+    decision: "reconciled",
+    invocationId,
+    phase: recovery.phase,
+    reason,
+  }, lock);
+  transition(runDir, state, "blocked", {
+    phase: recovery.phase,
+    error: { code: "unknown_effect_reconciled", message: excerpt(reason) },
+  }, lock);
+  return true;
+}
+/**
+ * @param {ValidatedContract} contract
+ * @param {string} runDir
+ * @param {NodeSnapshot} state
+ * @param {ValidatedNode} node
+ * @param {Invocation|undefined} invocation
+ * @param {LockHandle} lock
+ * @param {{materialization?: boolean}} [options]
+ * @returns {boolean}
+ */
+export function checkPersistedWorkerScope(contract, runDir, state, node, invocation, lock, options = {}) {
+  const materialization = options.materialization === true;
+  const evaluation = evaluatePersistedWorkerScope(contract, node, state, invocation, { strict: materialization });
+  if (evaluation.ok) return true;
+  // A recovered materialization turn mirrors the live check: it may only write
+  // the canonical result file, so declared-path changes are as terminal as
+  // unexpected ones.
+  const failure = materialization && (evaluation.code === "unexpected_write" || evaluation.code === "declared_paths_changed")
+    ? {
+      code: "unexpected_write",
+      message: excerpt(`result materialization changed workspace paths (${evaluation.changedPathCount ?? evaluation.unexpectedPathCount}): ${(evaluation.changedPaths ?? evaluation.unexpectedPaths ?? []).slice(0, 8).join(", ")}`),
+    }
+    : { code: evaluation.code, message: excerpt(evaluation.detail) };
+  transition(runDir, state, "failed", {
+    phase: "worker",
+    error: failure,
+  }, lock);
+  if (evaluation.unexpectedPaths) {
+    appendTransitionEvent(runDir, state, "failed", "failed", {
+      unexpectedPaths: evaluation.unexpectedPaths,
+      unexpectedPathCount: evaluation.unexpectedPathCount,
+    }, lock);
+  }
+  return false;
+}
+/**
+ * Record a deferred scope violation as an advisory finding on a node whose
+ * controller verification passed: the node proceeds into the gate exactly as
+ * a clean node would (TECH-SPEC lean, rule 1).
+ *
+ * @param {string} runDir
+ * @param {NodeSnapshot} state
+ * @param {LockHandle} lock
+ */
+export function recordScopeFinding(runDir, state, lock) {
+  if (!state.scope?.unexpectedPaths?.length) return;
+  state.scopeFindings = scopeFindingFromScope(state.scope);
+  writeNode(runDir, state, lock);
+  appendTransitionEvent(runDir, state, state.status, state.status, {
+    type: "scope.finding",
+    unexpectedPaths: state.scopeFindings.unexpectedPaths,
+    unexpectedPathCount: state.scope.unexpectedPathCount,
+  }, lock);
+}
+/**
+ * Resolve an unknown_effect window (intent without settlement) per the node's
+ * replayPolicy. Adoption proof was already applied by recoverOrphan when it
+ * applied; what remains is the scoped safe-replay or a durable reconcile.
+ *
+ * @param {ValidatedContract} contract
+ * @param {string} runDir
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {Invocation|undefined} workerInvocation
+ * @param {LockHandle} lock
+ * @returns {Promise<{action: "replay"}|{action: "reconcile", reason: string}>}
+ */
+export async function resolveUnknownEffect(contract, runDir, node, state, workerInvocation, lock) {
+  const policy = node.replayPolicy ?? "safe";
+  if (policy !== "safe") {
+    return { action: "reconcile", reason: `node ${state.id} declares replayPolicy ${policy}; the interrupted attempt with unknown effects requires manual reconciliation` };
+  }
+  const evaluation = evaluatePersistedWorkerScope(contract, node, state, workerInvocation, { strict: true });
+  if (!evaluation.ok) {
+    return {
+      action: "reconcile",
+      reason: evaluation.code === "declared_paths_changed"
+        ? `declared workspace changes across the ambiguous window are not proof that replay cannot duplicate effects for node ${state.id}: ${evaluation.detail}`
+        : `workspace moved outside the declared write scope across the ambiguous window: ${evaluation.detail}`,
+    };
+  }
+  await executeControllerVerification(contract, runDir, node, state, lock);
+  if (!state.verification?.passed) {
+    return { action: "reconcile", reason: `deterministic verification failed while resolving the ambiguous window for node ${state.id}; partial effects cannot be proven absent` };
+  }
+  return { action: "replay" };
+}

package/src/engine/settle.mjs

@@ -0,0 +1,207 @@
+/**
+ * How a node ends: accepted and integrated, rejected, or parked for attention.
+ *
+ * These are the settlement primitives, and they are their own module because
+ * both the control loop and the review policy call them -- `settleDone`'s
+ * `onVerificationFailure` callback rejects the candidate, and `review.mjs`
+ * settles a node whose judge passed. Leaving them in `engine/lifecycle.mjs`
+ * made those two import each other, which was the last runtime import cycle in
+ * `src/` and the one the allowlist used to name.
+ *
+ * `settleDone` is the only place a node becomes `done`, and it does it through
+ * the integration transaction: the journal and the conditional ref update
+ * belong to `repo/integrate.mjs`, and the callbacks here own node state alone.
+ */
+import { candidateOnlyFailures, resetPhaseRouting, verificationFailureVerdict } from "./judge-gate.mjs";
+import { retryPrompt } from "./prompts.mjs";
+import { renderPreviousAttemptSection } from "./retry.mjs";
+import { startWorker } from "./dispatch.mjs";
+import { ensureTerminalEvent, transition, writeNode } from "./state.mjs";
+import { verificationFailureWithScope } from "../contract/scope-findings.mjs";
+import { alreadyNotified, notifyQueueFor } from "./notify-queue.mjs";
+
+import {
+  attemptWorkspace,
+  attemptWorktreePath,
+  removeWorktree,
+  sealAttempt,
+} from "../repo/worktree.mjs";
+import { basename } from "node:path";
+import { boundedUtf8, errorCode, errorMessage } from "../util.mjs";
+import { campaignIdOf } from "../campaign/record.mjs";
+import { integrateAttempt } from "../repo/integrate.mjs";
+import { verifyCandidateWorkspace } from "./verify.mjs";
+
+/** @typedef {import("../repo/integrate.mjs").IntegrationResult} IntegrationResult */
+/** @typedef {import("./lifecycle.mjs").Job} Job */
+/** @typedef {import("./prompts.mjs").JudgeVerdict} JudgeVerdict */
+/** @typedef {import("../cli.mjs").LockHandle} LockHandle */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
+
+/** Settle one worker-generation rejection: bounded revision when one remains, otherwise terminal exhausted/failed. @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {Map<string, Job>|null} running @param {LockHandle} lock @param {Map<string, NodeSnapshot>} states @param {string} campaignPath @param {JudgeVerdict} verdict @param {{code: string, label: string, phase?: "worker"|"judge", message?: string, forceFresh?: boolean}} options */
+export function applyRejection(contract, node, state, runDir, running, lock, states, campaignPath, verdict, options) {
+  const { code, label, phase = "worker", message = verdict.summary, forceFresh = true } = options;
+  state.gate = verdict;
+  if (node.gate.enabled && state.revisions < (node.gate.maxRevisions ?? 1)) {
+    resetPhaseRouting(state);
+    state.revisions += 1;
+    // The fresh-session decision travels with the node, not just this call:
+    // the `running === null` branch below hands the retry to the scheduler,
+    // whose own `startWorker` call carries no policy and would otherwise
+    // rediscover the prior compatible continuation from the persisted ledger.
+    // `startWorker` consumes and clears it, so it governs one dispatch only.
+    state.sessionPolicy = forceFresh ? { forceFresh: true } : null;
+    process.stdout.write(`[${label}] ${node.id} retry · ${verdict.summary}\n`);
+    // The retry is a fresh session when the decision says so, so the evidence
+    // it needs has to travel in the prompt, not the transcript. Rendering the
+    // bounded `## Previous attempt` section here means both the immediate
+    // dispatch below and a later scheduler dispatch (the `running` is null
+    // path) carry it.
+    state.previousAttempt = renderPreviousAttemptSection(state) ?? state.previousAttempt;
+    if (running) {
+      // Dispatching here owns the increment, because `startWorker` expects the
+      // attempt number it is about to run under.
+      state.attempt += 1;
+      startWorker(contract, node, state, runDir, running, retryPrompt(node, verdict), lock, states, campaignPath, { forceFresh });
+      return;
+    }
+    // Handing the node back to the scheduler instead: its dispatch increments
+    // on the way out, so incrementing here too spent two attempt numbers on one
+    // retry. Observed 2026-09-13 on a resume after a killed controller — a node
+    // that ran twice reported attempt 3, with no `…2.*` logs and a
+    // `worktree.previousAttempt` naming an attempt that never existed.
+    transition(runDir, state, "pending", { phase: "worker", error: null }, lock);
+    return;
+  }
+  transition(runDir, state, node.gate.enabled ? "exhausted" : "failed", {
+    phase,
+    gate: verdict,
+    error: { code, message },
+  }, lock);
+}
+/** Deterministic verification failure settles through the shared rejection path. The verdict carries this attempt's unexpected paths, so a red attempt reports them whether it stops here or starts its revision (TECH-SPEC lean, rule 1). @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {Map<string, Job>|null} running @param {LockHandle} lock @param {Map<string, NodeSnapshot>} states @param {string} campaignPath @param {JudgeVerdict} [verdict] */
+export function applyVerificationFailure(contract, node, state, runDir, running, lock, states, campaignPath, verdict = verificationFailureWithScope(verificationFailureVerdict(state), state.scope)) {
+  applyRejection(contract, node, state, runDir, running, lock, states, campaignPath, verdict, { code: "verification_failed", label: "verification" });
+}
+
+/**
+ * Seal the current attempt, verify its candidate in a detached worktree, and
+ * only then perform the single done-state transition. The integration module
+ * owns the journal and conditional ref update; this callback owns node state.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {string} runDir
+ * @param {LockHandle} lock
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {string} campaignPath
+ * @param {Partial<NodeSnapshot>} [patch]
+ * @returns {Promise<import("../repo/integrate.mjs").IntegrationResult|null|undefined>}
+ */
+export async function settleDone(contract, node, state, runDir, lock, states, campaignPath, patch = {}) {
+  const workspace = attemptWorkspace(state);
+  if (!workspace || !state.worktree?.branch || !state.worktree.baseSha) {
+    transition(runDir, state, "failed", {
+      phase: "complete",
+      error: { code: "attempt_worktree_missing", message: "completed attempt has no isolated worktree" },
+    }, lock);
+    return;
+  }
+  let sealed;
+  try {
+    sealed = sealAttempt({
+      repo: contract.cwd,
+      path: workspace,
+      baseSha: state.worktree.baseSha,
+      runId: contract.id,
+      nodeId: node.id,
+      attempt: state.attempt,
+    });
+    state.worktree = { ...state.worktree, commit: sealed.sha, status: "ready" };
+    writeNode(runDir, state, lock);
+  } catch (error) {
+    transition(runDir, state, "failed", {
+      phase: "complete",
+      error: { code: errorCode(error) ?? "attempt_seal_failed", message: errorMessage(error) },
+    }, lock);
+    return;
+  }
+  const result = await integrateAttempt({
+    repo: contract.cwd,
+    runDir,
+    runId: contract.id,
+    nodeId: node.id,
+    attempt: state.attempt,
+    attemptSha: sealed.sha,
+    branch: state.worktree.branch,
+    verificationEvidence: state.verification,
+    verifyCandidate: (candidateWorkspace) => verifyCandidateWorkspace(contract, node, state, runDir, candidateWorkspace),
+    onAccepted: async (transaction) => {
+      const acceptedPath = state.worktree?.path ?? attemptWorktreePath(runDir, contract.id, node.id, transaction.attempt);
+      if (state.attempt === transaction.attempt && state.status !== "done") {
+        transition(runDir, state, "done", {
+          ...patch,
+          integratedHead: transaction.candidateSha,
+          worktree: { ...(state.worktree ?? {}), status: "removed", commit: transaction.attemptSha, baseSha: transaction.previousRunRefTip },
+        }, lock);
+      }
+      if (state.attempt === transaction.attempt) ensureTerminalEvent(runDir, state, lock);
+      removeWorktree(contract.cwd, acceptedPath);
+    },
+    onVerificationFailure: async (transaction) => {
+      const verdict = verificationFailureWithScope(verificationFailureVerdict(state), state.scope);
+      verdict.summary = "integrated candidate verification failed";
+      const divergent = candidateOnlyFailures(state.verification, transaction.candidateEvidence);
+      verdict.findings = [...(verdict.findings ?? []), {
+        severity: "critical",
+        description: divergent.length
+          ? `the integration worktree failed a verification the attempt passed (${boundedUtf8(divergent.join("; "), 512)}): the two worktrees disagree about the environment, not about the work`
+          : "the sealed candidate did not pass the node verification in its integration worktree",
+        evidence: boundedUtf8(JSON.stringify(transaction.candidateEvidence ?? {}), 4 * 1024),
+      }];
+      applyRejection(contract, node, state, runDir, null, lock, states, campaignPath, verdict, {
+        code: "verification_failed",
+        label: "candidate-verification",
+      });
+    },
+    onConflict: async (transaction) => {
+      const paths = transaction.conflictingPaths?.length ? transaction.conflictingPaths.join(", ") : "unknown paths";
+      transition(runDir, state, "blocked", {
+        phase: "complete",
+        error: { code: "integration_conflict", message: `integration conflict in: ${paths}` },
+      }, lock);
+      if (campaignPath) await raiseNodeAttention(campaignPath, runDir, state, "integration_conflict");
+    },
+    onConcurrentMove: async (transaction) => {
+      transition(runDir, state, "blocked", {
+        phase: "complete",
+        error: { code: "integration_concurrent_move", message: `run ref moved from ${transaction.previousRunRefTip} to ${transaction.currentRunRefTip ?? "unknown"}` },
+      }, lock);
+      if (campaignPath) await raiseNodeAttention(campaignPath, runDir, state, "integration_concurrent_move");
+    },
+  });
+  return result;
+}
+/**
+ * Surface a node attention state through the run's notify queue.
+ * @param {string} campaignPath
+ * @param {string} runDir
+ * @param {NodeSnapshot} state
+ * @param {string} code
+ */
+export async function raiseNodeAttention(campaignPath, runDir, state, code) {
+  const runId = basename(runDir);
+  const dedupeKey = `attention:${runId}:${state.id}:${code}`;
+  if (alreadyNotified(runDir, dedupeKey)) return;
+  await notifyQueueFor(runDir).enqueue({
+    type: "attention",
+    campaignId: campaignIdOf(campaignPath),
+    runId,
+    nodeId: state.id,
+    errorCode: code,
+    dedupeKey,
+  });
+}