faberun 0.27.0 → 0.28.0

package/src/host/uninstall-roots.mjs

@@ -0,0 +1,196 @@
+/**
+ * Root confinement for `faberun uninstall`.
+ *
+ * `uninstall` is the one verb that deletes outside the target repository, and
+ * the only thing between a stray link and the operator's home is this module.
+ * Every candidate is resolved through the links on the way to it -- a POSIX
+ * symlink or a Windows directory junction, which `realpathSync` follows the
+ * same way -- and compared against the effective `HOME` and `FABERUN_HOME`
+ * named by the *injected* environment. The roots come from
+ * `home.mjs`'s `effectiveHome`, not from `faberunHome`, because the latter may
+ * fall back to `os.homedir()`: a normal command legitimately acts on the
+ * operator's own home, but a delete scoped to a throwaway home must never
+ * silently aim at the real one. When the environment names neither root there
+ * is no allowed root and every removal is refused.
+ *
+ * The comparison is not only at the top of the tree. `removeWithinRemovalRoots`
+ * re-resolves each entry immediately before unlinking it, so a directory whose
+ * own name resolves outside the roots -- `$FABERUN_HOME/current` pointing at
+ * `/etc`, say -- cannot smuggle its target into the recursive delete. A link
+ * that resolves outside is refused even though unlinking it would not follow
+ * the link, because a caller that hands over a resolved path deserves the same
+ * answer as one that hands over the path the resolution produced.
+ *
+ * Isolation is a requirement of the command, not a convenience: every test and
+ * every attempt to run `uninstall` during the work points `HOME` and
+ * `FABERUN_HOME` at a throwaway directory, and this module's refusal of the
+ * empty environment is what makes the fallback impossible to reintroduce.
+ */
+import { lstatSync, readdirSync, realpathSync, rmdirSync, unlinkSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { effectiveHome } from "./home.mjs";
+
+/** The `code` a removal outside the effective roots carries. */
+export const REMOVAL_OUTSIDE_ROOTS = "uninstall_outside_roots";
+
+/** Raised when a removal target is not under the effective HOME/FABERUN_HOME. */
+export class RemovalRefusedError extends Error {
+  /**
+   * @param {string} target the resolved path a caller asked to delete
+   * @param {string[]} roots the roots it was compared against
+   */
+  constructor(target, roots) {
+    super(
+      roots.length
+        ? `refusing to remove ${target}: it resolves outside ${roots.join(", ")}`
+        : `refusing to remove ${target}: the injected environment names no HOME or FABERUN_HOME`,
+    );
+    this.name = "RemovalRefusedError";
+    this.code = REMOVAL_OUTSIDE_ROOTS;
+    this.target = target;
+    this.roots = roots;
+  }
+}
+
+/**
+ * `path` with every link on the way to it resolved.
+ *
+ * A path that does not exist yet is canonicalised through its deepest existing
+ * ancestor and the remaining names appended. That is what keeps a not-yet-made
+ * leaf under a symlinked parent comparable: `$TMPDIR` on macOS is `/var`, a
+ * link to `/private/var`, so `removalRoots` resolving `$FABERUN_HOME` while
+ * `$FABERUN_HOME/versions` does not exist still has to agree with the
+ * `/private/var/...` realpath of a target that does.
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+export function canonicalPath(path) {
+  const absolute = resolve(path);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    const parent = dirname(absolute);
+    if (parent === absolute) return absolute;
+    return join(canonicalPath(parent), basename(absolute));
+  }
+}
+
+/**
+ * The roots `uninstall` may delete inside, resolved and de-duplicated: the
+ * effective `HOME` and `FABERUN_HOME` the injected environment names. When
+ * `FABERUN_HOME` is unset and a home is known, the install root is that home's
+ * `.faberun`; when neither is known the list is empty and nothing may be
+ * removed.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+export function removalRoots(env = process.env) {
+  const home = effectiveHome(env);
+  const canonicalHome = home === null ? null : canonicalPath(home);
+  const configured = env.FABERUN_HOME;
+  const canonicalFaberun = typeof configured === "string" && configured
+    ? canonicalPath(configured)
+    : canonicalHome === null
+      ? null
+      : canonicalPath(join(canonicalHome, ".faberun"));
+  return [...new Set([canonicalHome, canonicalFaberun].filter((root) => root !== null))];
+}
+
+/**
+ * Whether `root` contains `target` (or is it). The comparison is on resolved
+ * absolute paths, so `..` segments and case-normalised Windows spellings do
+ * not matter.
+ *
+ * @param {string} root
+ * @param {string} target
+ * @returns {boolean}
+ */
+function contains(root, target) {
+  if (target === root) return true;
+  const step = relative(root, target);
+  return step !== "" && !step.startsWith("..") && !isAbsolute(step);
+}
+
+/**
+ * Whether `target`, once resolved, sits under one of `roots`.
+ *
+ * @param {string} target
+ * @param {string[]} roots
+ * @returns {boolean}
+ */
+export function isWithinRemovalRoots(target, roots) {
+  const canonicalTarget = canonicalPath(target);
+  return roots.some((root) => contains(canonicalPath(root), canonicalTarget));
+}
+
+/**
+ * Resolve `target` and return it, or throw {@link RemovalRefusedError} when it
+ * is not under one of `roots`. The resolved path is what a caller should delete
+ * or report, so the resolution is not repeated at the deletion site.
+ *
+ * @param {string} target
+ * @param {string[]} roots
+ * @returns {string}
+ */
+export function assertWithinRemovalRoots(target, roots) {
+  const canonicalTarget = canonicalPath(target);
+  const canonicalRoots = roots.map(canonicalPath);
+  if (!canonicalRoots.some((root) => contains(root, canonicalTarget))) {
+    throw new RemovalRefusedError(canonicalTarget, canonicalRoots);
+  }
+  return canonicalTarget;
+}
+
+/**
+ * Remove `target`, recursively, every deletion preceded by a fresh resolution
+ * and containment check. Links are unlinked, never followed: the check on a
+ * link is about where it points, and a link that points outside is refused, so
+ * its target cannot be reached through it.
+ *
+ * A target that does not exist is simply absent; only a target that resolves
+ * outside the effective roots raises. When the environment names no root, every
+ * target raises.
+ *
+ * @param {string} target
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {void}
+ */
+export function removeWithinRemovalRoots(target, env = process.env) {
+  const roots = removalRoots(env);
+  if (roots.length === 0) throw new RemovalRefusedError(canonicalPath(target), roots);
+  removeChecked(target, roots);
+}
+
+/**
+ * @param {string} target
+ * @param {string[]} roots canonical and already non-empty
+ * @returns {void}
+ */
+function removeChecked(target, roots) {
+  /** @type {import("node:fs").Stats} */
+  let stats;
+  try {
+    stats = lstatSync(target);
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return;
+    throw error;
+  }
+  // Resolve immediately before this entry's own deletion. `lstat` does not
+  // follow the link, so a directory link is unlinked below rather than walked.
+  assertWithinRemovalRoots(target, roots);
+  if (stats.isSymbolicLink()) {
+    unlinkSync(target);
+    return;
+  }
+  if (stats.isDirectory()) {
+    for (const name of readdirSync(target)) removeChecked(join(target, name), roots);
+    // Re-check after the children, so a directory swapped for an escaping link
+    // in the meantime is not removed by the `rmdir` either.
+    assertWithinRemovalRoots(target, roots);
+    rmdirSync(target);
+    return;
+  }
+  unlinkSync(target);
+}

package/src/plan/proof-check.mjs

@@ -13,6 +13,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { shellWords } from "../util.mjs";
+import { inlineScriptParseError } from "../contract/definition-of-done.mjs";
 import { NAME_PATTERN_FLAG } from "./proof-run.mjs";
 
 /** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
@@ -135,6 +136,20 @@ export function checkPlanProofs(plan, repoFacts, cwd) {
     for (const item of node.definitionOfDone) {
       const commandText = proofCommandText(node, item.proof);
       if (commandText === null) continue;
+      // R34: a `node -e` body the parser rejects can never exit 0, so no
+      // revise of the work helps; the body has to change before the plan is
+      // frozen. Raises the finding the planner can act on, rather than
+      // spending a review round on a proof that is unsatisfiable by syntax.
+      const inlineScriptError = inlineScriptParseError(commandText);
+      if (inlineScriptError !== null) {
+        findings.push({
+          id: `proof-unparseable-${node.id}-${item.id}`,
+          severity: "critical",
+          nodeId: node.id,
+          text: `Node ${node.id}'s Definition of Done item "${item.id}" proves itself with an inline script that does not parse ("${inlineScriptError}"), so no delivery can make this proof exit 0. Fix the script body.`,
+        });
+        continue;
+      }
       const nameFlag = NAME_PATTERN_FLAG.exec(commandText);
       if (nameFlag) {
         const pattern = nameFlag[1] ?? nameFlag[2] ?? nameFlag[3];

package/src/plan/repo-facts.mjs

@@ -1,7 +1,10 @@
 /**
  * Repo facts: a deterministic, bounded inventory of the target repository —
- * tracked paths, declared scripts, timed verification candidates, and which
- * test file covers which source module — collected without invoking a model.
+ * tracked paths, declared scripts, verification candidates across the Node,
+ * Python, Go, Rust, Zig and Makefile ecosystems, and which test file covers
+ * which source module — collected without invoking a model. Every candidate
+ * records the manifest it was read from; only the Node candidates are timed,
+ * and no candidate for another ecosystem is ever executed to be found.
  * A planning stage's draft is authored against exactly this JSON instead of
  * the session reading the repository by hand.
  *
@@ -23,9 +26,27 @@ import { runShellCapture } from "./proof-run.mjs";
 /** @typedef {import("./spec.mjs").SpecRequirement} SpecRequirement */
 /** @typedef {import("./proof-run.mjs").MeasureProbes} MeasureProbes */
 /** @typedef {{requirementId: string|null, command: string, output: string, exitCode: number|null, truncated: boolean}} RequirementMeasurement */
-/** @typedef {{argv: string[], measuredMs: number, eligible: boolean}} VerificationCandidate */
+/**
+ * A verification command repo facts measured: a timed Node candidate, the
+ * manifest file it was read from, and its eligibility. It keeps the shape
+ * `freeze.mjs`'s `MeasuredFacts` reads (`argv` plus a numeric `measuredMs`),
+ * so a repository's facts stay assignable there while carrying the manifest
+ * the planner needs.
+ *
+ * @typedef {{argv: string[], manifest: string, measuredMs: number, eligible: boolean}} VerificationCandidate
+ */
+/**
+ * A verification command repo facts detected in a non-Node manifest it never
+ * ran: `pyproject.toml`/`pytest.ini` (Python), `go.mod`, `Cargo.toml`,
+ * `build.zig`, or a `Makefile` with a `test` target. Detection is file
+ * inspection alone, so `measuredMs` is the null "no measurement" sentinel
+ * `freeze.mjs` reads and `eligible` is true — the manifest's own presence is
+ * the evidence. `manifest` names the file the command was read from.
+ *
+ * @typedef {{argv: string[], manifest: string, measuredMs: number|null, eligible: boolean}} DetectedVerificationCandidate
+ */
 /** @typedef {{path: string, covers: string|null}} TestFileEntry */
-/** @typedef {{formatVersion: number, gitHead: string|null, paths: string[], truncated: boolean, scripts: Record<string, string>, verificationCandidates: VerificationCandidate[], testFiles: TestFileEntry[], requirementMeasurements: RequirementMeasurement[]}} RepoFacts */
+/** @typedef {{formatVersion: number, gitHead: string|null, paths: string[], truncated: boolean, scripts: Record<string, string>, verificationCandidates: VerificationCandidate[], detectedVerificationCandidates?: DetectedVerificationCandidate[], testFiles: TestFileEntry[], requirementMeasurements: RequirementMeasurement[]}} RepoFacts */
 
 const FORMAT_VERSION = 1;
 const DEFAULT_MAX_PATHS = 2000;
@@ -87,16 +108,71 @@ function testFileEntries(paths, pathSet) {
     });
 }
 
+/** The manifest the Node candidates — the test directories and the scripts — are read from. */
+const PACKAGE_MANIFEST = "package.json";
+
 /**
+ * The Node candidates: one per first-level test directory, plus the `check`
+ * and `typecheck` scripts `package.json` declares. Every one is measured, so
+ * each is handed to the timed probe below; each names package.json as the
+ * manifest it came from.
+ *
  * @param {Record<string, string>} scripts
  * @param {string[]} paths
- * @returns {{argv: string[]}[]}
+ * @returns {{argv: string[], manifest: string}[]}
  */
-function candidateCommands(scripts, paths) {
-  const commands = testDirectories(paths).map((directory) => ({ argv: ["node", "--test", directory] }));
+function nodeCandidateCommands(scripts, paths) {
+  const commands = testDirectories(paths).map((directory) => ({ argv: ["node", "--test", directory], manifest: PACKAGE_MANIFEST }));
   for (const name of ["check", "typecheck"]) {
-    if (typeof scripts[name] === "string") commands.push({ argv: ["npm", "run", name] });
+    if (typeof scripts[name] === "string") commands.push({ argv: ["npm", "run", name], manifest: PACKAGE_MANIFEST });
+  }
+  return commands;
+}
+
+/**
+ * The makefile that declares a `test` target, or null when none does. A rule
+ * line starts at column zero with the target name `test` followed by a colon;
+ * `test:=` is a variable assignment, `.PHONY: test` declares no rule, an
+ * indented recipe line never matches, and `test-all:` names another target.
+ * Pure text inspection of the first conventional makefile present, so a
+ * command is never run to discover the target.
+ *
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function makefileWithTestTarget(cwd) {
+  for (const name of ["Makefile", "makefile", "GNUmakefile"]) {
+    const path = join(cwd, name);
+    if (!existsSync(path)) continue;
+    if (/^test[ \t]*:(?!=)/mu.test(readFileSync(path, "utf8"))) return name;
   }
+  return null;
+}
+
+/**
+ * The verification commands the non-Node ecosystems declare, in a fixed order,
+ * each naming the manifest file it was read from. Detection is file inspection
+ * alone — existence for the manifest files, one read for a Makefile target —
+ * so no discovered command is executed, the order never depends on a directory
+ * listing, and two calls at the same HEAD return identical candidates.
+ * `pyproject.toml` wins over `pytest.ini` when both exist because it is the
+ * file pytest itself reads first.
+ *
+ * @param {string} cwd
+ * @returns {{argv: string[], manifest: string}[]}
+ */
+function manifestCandidateCommands(cwd) {
+  /** @type {{argv: string[], manifest: string}[]} */
+  const commands = [];
+  /** @param {string} name @returns {boolean} */
+  const present = (name) => existsSync(join(cwd, name));
+  if (present("pyproject.toml")) commands.push({ argv: ["pytest"], manifest: "pyproject.toml" });
+  else if (present("pytest.ini")) commands.push({ argv: ["pytest"], manifest: "pytest.ini" });
+  if (present("go.mod")) commands.push({ argv: ["go", "test", "./..."], manifest: "go.mod" });
+  if (present("Cargo.toml")) commands.push({ argv: ["cargo", "test"], manifest: "Cargo.toml" });
+  if (present("build.zig")) commands.push({ argv: ["zig", "build", "test"], manifest: "build.zig" });
+  const makefile = makefileWithTestTarget(cwd);
+  if (makefile !== null) commands.push({ argv: ["make", "test"], manifest: makefile });
   return commands;
 }
 
@@ -111,7 +187,7 @@ function candidateCommands(scripts, paths) {
  * @param {string} cwd
  * @param {{argv: string[]}[]} commands
  * @param {MeasureProbes} probes
- * @returns {VerificationCandidate[]}
+ * @returns {{argv: string[], measuredMs: number, eligible: boolean}[]}
  */
 function measureCandidates(cwd, commands, probes) {
   if (commands.length === 0) return [];
@@ -179,7 +255,8 @@ export function collectRepoFacts(cwd, options = {}) {
   const allPaths = listTrackedPaths(cwd);
   const pathSet = new Set(allPaths);
   const scripts = readScripts(cwd);
-  const commands = candidateCommands(scripts, allPaths);
+  const measured = measureCandidates(cwd, nodeCandidateCommands(scripts, allPaths), options.measure ?? {});
+  const detected = manifestCandidateCommands(cwd);
   const truncated = allPaths.length > maxPaths;
   return {
     formatVersion: FORMAT_VERSION,
@@ -187,7 +264,14 @@ export function collectRepoFacts(cwd, options = {}) {
     paths: truncated ? allPaths.slice(0, maxPaths) : allPaths,
     truncated,
     scripts,
-    verificationCandidates: measureCandidates(cwd, commands, options.measure ?? {}),
+    // The measured Node candidates first, in their timed order, each naming
+    // package.json as the manifest it came from; then the manifest-only
+    // candidates in a fixed ecosystem order, each naming the manifest it was
+    // read from. Only the measured candidates carry a numeric `measuredMs`:
+    // a detected command is never run, so it lands in its own array with the
+    // null "no measurement" sentinel freeze.mjs reads and eligibility true.
+    verificationCandidates: measured.map((candidate) => ({ ...candidate, manifest: PACKAGE_MANIFEST })),
+    detectedVerificationCandidates: detected.map((candidate) => ({ ...candidate, measuredMs: null, eligible: true })),
     testFiles: testFileEntries(allPaths, pathSet),
     requirementMeasurements: measureRequirements(cwd, options.requirements ?? [], options.measure ?? {}),
   };

package/src/plan/rounds.mjs

@@ -444,3 +444,30 @@ export async function runReviewRounds(options) {
   }
   return { resolved: true, plan, findings, roundsRun };
 }
+
+/**
+ * A hard round budget around any discovery pass: at most `rounds` calls to
+ * `step`, stopping at the first result whose `accepted` flag is true. The
+ * reauthor flow spends this budget widening a refused packet; the planning
+ * pipeline's own review/revise loop keeps its bespoke bookkeeping and does not
+ * use it. `step` receives the round number and the results so far, so a round
+ * can feed the previous rounds' findings into its own prompt.
+ *
+ * @template T
+ * @param {number} rounds a positive integer; the budget is never exceeded
+ * @param {(round: number, history: T[]) => T|Promise<T>} step
+ * @returns {Promise<{accepted: boolean, roundsUsed: number, last: T|null, history: T[]}>}
+ */
+export async function runBoundedRounds(rounds, step) {
+  if (!Number.isInteger(rounds) || rounds < 1) throw new TypeError(`rounds must be a positive integer: ${String(rounds)}`);
+  /** @type {T[]} */
+  const history = [];
+  for (let round = 1; round <= rounds; round += 1) {
+    const result = await step(round, history);
+    history.push(result);
+    if (/** @type {{accepted?: boolean}} */ (result).accepted === true) {
+      return { accepted: true, roundsUsed: round, last: result, history };
+    }
+  }
+  return { accepted: false, roundsUsed: rounds, last: history.at(-1) ?? null, history };
+}

package/src/repo/declared-paths.mjs

@@ -14,7 +14,7 @@ import { errorCode, exitStatus } from "../util.mjs";
 import { execFileSync } from "node:child_process";
 import { gitArguments } from "../host/platform.mjs";
 import { join, resolve } from "node:path";
-import { lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { RUNS_DIR_NAME } from "../run/paths.mjs";
 import { isIgnoreSource } from "./workspace.mjs";
@@ -54,16 +54,84 @@ export function unsnapshottedWriteWarnings(node, index, cwd) {
  * `writes_ignore_source`: a declared write the workspace snapshot fingerprints
  * as an ignore source. The node fails with `snapshot_ignore_changed` the
  * moment the worker changes it, and two campaigns each lost a node learning
- * that (RM-051), so the author hears it before dispatch.
+ * that (RM-051), so the author hears it before dispatch. A declared write root
+ * is covered too: a worker is free to edit a `.gitignore` anywhere under it,
+ * and the node would fail the same way.
  *
  * @param {ValidatedNode} node
  * @param {number} index
+ * @param {string} [cwd]
  * @returns {string[]}
  */
-export function ignoreSourceWriteWarnings(node, index) {
-  const sources = (node.taskPacket.writeFiles ?? []).filter(isIgnoreSource);
-  if (!sources.length) return [];
-  return [`nodes[${index}] (${node.id}): writes_ignore_source: writeFiles ${sources.join(", ")} ${sources.length === 1 ? "is an ignore source" : "are ignore sources"} the workspace snapshot fingerprints; a worker that changes one fails the node with snapshot_ignore_changed, so make that edit outside the run`];
+export function ignoreSourceWriteWarnings(node, index, cwd) {
+  const nodeCwd = /** @type {{cwd?: unknown}} */ (node).cwd;
+  const directory = typeof cwd === "string" ? cwd : (typeof nodeCwd === "string" ? nodeCwd : undefined);
+  const fileSources = (node.taskPacket.writeFiles ?? []).filter(isIgnoreSource);
+  const rootSources = [];
+  for (const root of node.taskPacket.writeRoots ?? []) {
+    const sources = ignoreSourcesUnderWriteRoot(root, directory);
+    if (sources.length) rootSources.push({ root, sources });
+  }
+  if (!fileSources.length && !rootSources.length) return [];
+  const clauses = [];
+  if (fileSources.length) {
+    clauses.push(`writeFiles ${fileSources.join(", ")} ${fileSources.length === 1 ? "is an ignore source" : "are ignore sources"}`);
+  }
+  for (const { root, sources } of rootSources) {
+    const literal = normalizeDeclaredPath(root);
+    clauses.push(isIgnoreSource(literal)
+      ? `writeRoots ${literal} is an ignore source`
+      : `writeRoots ${literal} contains ${sources.join(", ")}`);
+  }
+  return [`nodes[${index}] (${node.id}): writes_ignore_source: ${clauses.join("; ")} the workspace snapshot fingerprints; a worker that changes one fails the node with snapshot_ignore_changed, so make that edit outside the run`];
+}
+/** Directories a write-root scan never descends into, mirroring `isIgnoreSource`. */
+const UNSCANNED_WRITE_ROOT_DIRS = new Set([".git", RUNS_DIR_NAME, "node_modules", ".venv", "venv"]);
+/**
+ * The ignore sources inside a declared write root. The root itself counts; a
+ * directory is walked with the same exclusions `isIgnoreSource` applies, and
+ * the walk is bounded so a broad root cannot stall validation.
+ *
+ * @param {string} root
+ * @param {string|undefined} cwd
+ * @returns {string[]}
+ */
+function ignoreSourcesUnderWriteRoot(root, cwd) {
+  const literal = normalizeDeclaredPath(root);
+  if (!literal) return [];
+  if (isIgnoreSource(literal)) return [literal];
+  if (!cwd) return [];
+  /** @type {string[]} */
+  const found = [];
+  /** @param {string} directory @param {number} budget @returns {number} */
+  const walk = (directory, budget) => {
+    if (budget <= 0) return budget;
+    let entries;
+    try {
+      entries = readdirSync(join(cwd, directory), { withFileTypes: true });
+    } catch {
+      return budget;
+    }
+    for (const entry of entries) {
+      if (budget <= 0) break;
+      const relative = `${directory}/${entry.name}`;
+      if (isIgnoreSource(relative)) {
+        found.push(relative);
+        budget -= 1;
+        continue;
+      }
+      if (entry.isDirectory() && !UNSCANNED_WRITE_ROOT_DIRS.has(entry.name) && !(directory === literal && (entry.name === ".claude" || entry.name === ".codex"))) {
+        budget = walk(relative, budget - 1);
+      }
+    }
+    return budget;
+  };
+  walk(literal, 200);
+  return found;
+}
+/** @param {string} path @returns {string} */
+function normalizeDeclaredPath(path) {
+  return (process.platform === "win32" ? String(path).replaceAll("\\", "/") : String(path)).replace(/\/+$/u, "");
 }
 /**
  * @param {string|undefined} cwd

package/src/repo/integrate.mjs

@@ -425,7 +425,7 @@ function gitSetRef(repo, ref, sha) {
 
 /** @param {string} repo @param {string} tree @param {string} firstParent @param {string} secondParent @param {string} runId @param {string} nodeId @param {number} attempt @returns {string} */
 function gitCommitTree(repo, tree, firstParent, secondParent, runId, nodeId, attempt) {
-  const result = boundedGitSync(["-C", repo, "commit-tree", tree, "-p", firstParent, "-p", secondParent, "-m", `faberun candidate ${runId} ${nodeId} attempt ${attempt}`], {
+  const result = boundedGitSync(["-C", repo, "commit-tree", tree, "-p", firstParent, "-p", secondParent, "-m", `chore(faberun): integrate ${nodeId} attempt ${attempt}`, "-m", `faberun run ${runId}`], {
     encoding: "utf8",
     env: {
       ...process.env,

package/src/repo/scope-closure.mjs

@@ -231,6 +231,65 @@ export function crossNodeScopeFindings(nodes, cwd) {
   return findings;
 }
 
+/**
+ * Every scope-closure obligation of a whole contract at once: the per-node
+ * detectors and the cross-node pair. `validateContract` runs exactly this pair
+ * as a refusal; a widening pass needs the same findings without throwing, so
+ * it can show them to the operator and hand them to the next discovery round.
+ *
+ * @param {ValidatedNode[]} nodes every node of one contract
+ * @param {string} cwd
+ * @returns {(ScopeClosureFinding|CrossNodeScopeFinding)[]}
+ */
+export function contractScopeFindings(nodes, cwd) {
+  return [
+    ...nodes.flatMap((node, index) => scopeClosureFindings(node, index, cwd)),
+    ...crossNodeScopeFindings(nodes, cwd),
+  ];
+}
+
+/**
+ * Widen a task packet with a discovery pass's proposed additions. Only unions:
+ * a reauthor may add a read, a write, an acknowledgement, or a symbol, never
+ * remove one -- a shrink clears a closure finding while leaving the worker
+ * unable to do the work.
+ *
+ * @param {TaskPacket} packet
+ * @param {import("../contract/scope-findings.mjs").ReauthorAdditions} additions
+ * @returns {TaskPacket}
+ */
+export function widenTaskPacket(packet, additions) {
+  /** @param {string[]|undefined} base @param {string[]|undefined} extra @returns {string[]} */
+  const union = (base, extra) => [...new Set([...(base ?? []), ...(extra ?? [])])];
+  const acknowledged = union(packet.scopeAcknowledged, additions.scopeAcknowledged);
+  return {
+    ...packet,
+    readFiles: union(packet.readFiles, additions.readFiles),
+    writeFiles: union(packet.writeFiles, additions.writeFiles),
+    symbols: union(packet.symbols, additions.symbols),
+    ...(acknowledged.length ? { scopeAcknowledged: acknowledged } : {}),
+  };
+}
+
+/**
+ * Replace one node's inline packet in a raw contract and drop its `packetHash`,
+ * which `validateContract` recomputes for the widened packet. The caller
+ * re-stamps the new hash before persisting the accepted widening.
+ *
+ * @param {Record<string, unknown>} raw
+ * @param {string} nodeId
+ * @param {TaskPacket} packet
+ * @returns {Record<string, unknown>}
+ */
+export function replacePacketInContract(raw, nodeId, packet) {
+  const candidate = /** @type {any} */ (structuredClone(raw));
+  const record = candidate.nodes.find((/** @type {any} */ node) => node.id === nodeId);
+  if (!record) throw new Error(`unknown node id: ${nodeId}`);
+  record.taskPacket = packet;
+  delete record.packetHash;
+  return candidate;
+}
+
 /**
  * DETECTOR 1. An importer of a written module must change with it, so it is in
  * scope unless declared. A packet that names `symbols` narrows the rule to

package/src/repo/signal-block.mjs

@@ -21,3 +21,29 @@ export function normalizeManagedSignalBlock(text) {
   const after = text.slice(end + SIGNAL_END.length).replace(/^\s+/u, "");
   return after ? `${before}\n\n${after}` : `${before}\n`;
 }
+
+/**
+ * Apply a freshly rendered managed block to `text`, but only when the start
+ * marker is already present. A document without the marker is the operator's
+ * file, not the runner's: it is returned byte-identical so no campaign
+ * operation can quietly append a managed block to an `AGENTS.md` that never
+ * opted in. The operator opts in by pasting the start marker once, and this
+ * repository already carries it.
+ *
+ * `block` is the renderer's output, or `""` to remove a block that is present
+ * once the run settled. The surrounding text is joined with the same blank
+ * line the writer always used, so a rewrite of an existing block and its
+ * removal both normalise to the file's committed shape.
+ *
+ * @param {string} text
+ * @param {string} block
+ * @returns {string}
+ */
+export function applyManagedSignalBlock(text, block) {
+  const start = text.indexOf(SIGNAL_START);
+  if (start < 0) return text;
+  const end = text.indexOf(SIGNAL_END, start + SIGNAL_START.length);
+  const before = text.slice(0, start).trimEnd();
+  const after = end < 0 ? "" : text.slice(end + SIGNAL_END.length);
+  return [before, block, after.trimStart()].filter((part) => part.length).join("\n\n") + "\n";
+}

package/src/repo/signal.mjs

@@ -40,7 +40,7 @@ import { discoverCampaigns } from "../campaign/index.mjs";
 import { runProgress } from "../engine/supervise.mjs";
 import { readInbox } from "../notify/index.mjs";
 import { repositoryForRunsDir } from "../run/paths.mjs";
-import { SIGNAL_END, SIGNAL_START } from "./signal-block.mjs";
+import { applyManagedSignalBlock, SIGNAL_END, SIGNAL_START } from "./signal-block.mjs";
 import { HANDOFF_FILE } from "../campaign/layout.mjs";
 import { classifyRunProgress } from "../campaign/chain.mjs";
 
@@ -298,9 +298,12 @@ function boundLines(lines) {
 
 /**
  * Rewrites the managed signal block at the bottom of the repository's
- * AGENTS.md from the current runs state. Leaves the file untouched when there
- * is no AGENTS.md, no active work, or nothing changed. Returns true when the
- * file was written.
+ * AGENTS.md from the current runs state. The file must already contain the
+ * start marker: the operator opts in by pasting it once, and this repository
+ * already carries it, so no campaign operation can append a managed block to a
+ * document that never asked for one. Leaves the file untouched when there is
+ * no AGENTS.md, no start marker, no active work, or nothing changed. Returns
+ * true when the file was written.
  *
  * The repository is named by the project registry, not derived as a sibling
  * of `runsDir`: since the runs directory moved under the home, a directory
@@ -315,26 +318,8 @@ export function syncAgentSignal(runsDir) {
   const agentsPath = join(repositoryForRunsDir(runsDir) ?? dirname(runsDir), "AGENTS.md");
   if (!existsSync(agentsPath)) return false;
   const current = readFileSync(agentsPath, "utf8");
-  const block = renderAgentSignalBlock(runsDir);
-  const start = current.indexOf(SIGNAL_START);
-  const end = current.indexOf(SIGNAL_END);
-  if (!block && start < 0 && end < 0) return false;
-  let before;
-  let after;
-  if (start >= 0 && end > start) {
-    before = current.slice(0, start).trimEnd();
-    after = current.slice(end + SIGNAL_END.length);
-  } else if (start >= 0) {
-    before = current.slice(0, start).trimEnd();
-    after = "";
-  } else if (end >= 0) {
-    before = current.slice(0, end).trimEnd();
-    after = current.slice(end + SIGNAL_END.length);
-  } else {
-    before = current.trimEnd();
-    after = "";
-  }
-  const next = [before, block, after.trimStart()].filter((part) => part.length).join("\n\n") + "\n";
+  if (!current.includes(SIGNAL_START)) return false;
+  const next = applyManagedSignalBlock(current, renderAgentSignalBlock(runsDir));
   if (next === current) return false;
   writeFileSync(agentsPath, next);
   return true;