faberun 0.10.0 → 0.12.0

package/src/repo/workspace.mjs

@@ -22,6 +22,7 @@ import { errorCode } from "../util.mjs";
 import { execFileSync } from "node:child_process";
 import { fail, isContained } from "../util.mjs";
 import { normalizeManagedSignalBlock } from "./signal-block.mjs";
+import { RUNS_DIR_NAME } from "../run/paths.mjs";
 
 /** A `node_modules` directory at any depth, matched as a whole path segment. */
 const NODE_MODULES_SEGMENT = /(?:^|\/)node_modules(?:\/|$)/u;
@@ -311,7 +312,12 @@ function captureIgnoreSources(root) {
       throw fail("snapshot_read_error", `cannot inspect workspace directory ${relativeWorkspacePath(root, directory)}: ${error instanceof Error ? error.message : String(error)}`);
     }
     for (const entry of entries) {
-      if (entry.name === ".git" || entry.name === ".runs") continue;
+      // The runner's own state and git's own metadata carry no ignore rule a
+      // fingerprint here needs to see: `.runs/` is the runner's scratch tree,
+      // walked elsewhere for evidence and never for gitignore files, and
+      // `.git` is git's own directory, not the workspace git ignores things
+      // in.
+      if (entry.name === ".git" || entry.name === RUNS_DIR_NAME) continue;
       // Same exclusions as the entries snapshot (see the task-packet
       // reference): `node_modules` at any depth, and the agent runtimes'
       // scratch state at the root (`.claude`, `.codex`). Ignore files inside
@@ -466,7 +472,11 @@ function relevantWorkspacePaths(cwd) {
   const paths = new Set();
   for (const value of output.toString("utf8").split("\0")) {
     if (!value) continue;
-    if (value === ".runs" || value.startsWith(".runs/")) continue;
+    // The runner's own scratch tree, excluded for the same reason as in the
+    // ignore-source walk above: it is machine-owned state, not evidence of
+    // what the worker changed, and letting it into the snapshot would fail a
+    // node on the runner's own bookkeeping rather than on the worker's work.
+    if (value === RUNS_DIR_NAME || value.startsWith(`${RUNS_DIR_NAME}/`)) continue;
     // Same exclusion as the ignore-source walk above: a repository's
     // gitignore conventionally excludes `node_modules/` as a directory
     // pattern, which does not match the symlink an attempt worktree links it

package/src/repo/worktree.mjs

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { RUNS_DIR_NAME, attemptWorktreePath, candidateWorktreePath } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
 
@@ -103,26 +104,11 @@ export function candidateRefName(runId) {
   return `refs/faberun/${runId}/candidate`;
 }
 
-/** @param {string} runDir @param {string} runId @returns {string} */
-function worktreeRoot(runDir, runId) {
-  return join(dirname(runDir), "worktrees", runId);
-}
-
-/** @param {string} runDir @param {string} runId @param {string} nodeId @param {number} attempt @returns {string} */
-export function attemptWorktreePath(runDir, runId, nodeId, attempt) {
-  return join(worktreeRoot(runDir, runId), `${nodeId}.${attempt}`);
-}
-
 /** @param {string} runId @param {string} nodeId @param {number} attempt @returns {string} */
 function attemptBranchName(runId, nodeId, attempt) {
   return `faberun/${runId}/${nodeId}/${attempt}`;
 }
 
-/** @param {string} runDir @param {string} runId @returns {string} */
-export function candidateWorktreePath(runDir, runId) {
-  return join(worktreeRoot(runDir, runId), ".candidate");
-}
-
 /** @param {unknown} error @returns {string} */
 function gitFailureReason(error) {
   const streams = /** @type {{stderr?: unknown, stdout?: unknown}} */ (error ?? {});
@@ -183,14 +169,16 @@ export function createRunRef(repo, runId, head) {
 }
 
 /**
- * @param {{repo: string, runDir: string, runId: string, nodeId: string, attempt: number, base?: string}} args
+ * @param {{repo: string, runDir: string, runId: string, nodeId: string, attempt: number, base?: string, declaredReads?: string[]}} args
  *   `base` cuts the new branch from a sealed sha instead of the run ref tip —
  *   the previous attempt's sealed work, when it left one (TECH-SPEC lean
  *   v0.3 section 3 rule 4). Omitted, it falls back to the run ref tip as
- *   before.
+ *   before. `declaredReads` names the packet's readFiles: entries git does
+ *   not track are carried into the fresh worktree, since a checkout carries
+ *   only tracked content and the worker reads the packet's reads from here.
  * @returns {AttemptWorktree}
  */
-export function createAttemptWorktree({ repo, runDir, runId, nodeId, attempt, base }) {
+export function createAttemptWorktree({ repo, runDir, runId, nodeId, attempt, base, declaredReads }) {
   const runRefSha = gitHead(repo, runRefName(runId));
   if (!runRefSha) throw Object.assign(new Error(`integration ref is unavailable for ${runId}`), { code: "run_ref_missing" });
   const path = attemptWorktreePath(runDir, runId, nodeId, attempt);
@@ -206,6 +194,7 @@ export function createAttemptWorktree({ repo, runDir, runId, nodeId, attempt, ba
     runGit(["-C", repo, "worktree", "add", path, "-b", branch, base ?? runRefName(runId)]);
   }
   prepareWorktreeEnvironment(repo, path);
+  carryDeclaredReads(repo, path, declaredReads ?? []);
   return { status: "ready", path, branch, commit: gitHead(path), baseSha: base ?? runRefSha };
 }
 
@@ -242,6 +231,67 @@ function isSymlink(path) {
   }
 }
 
+/**
+ * Carry a packet's declared reads that git does not track from the repository
+ * checkout into a freshly created attempt worktree. Validation checks
+ * readFiles against the repository, but the worker reads them from the
+ * worktree, and a worktree carries only tracked content: an ignored or
+ * untracked declared read — the plan pipeline's gitignored repo-facts relay is
+ * the live case — would be absent from the very packet that names it.
+ *
+ * A tracked file is never copied, so a dirty working copy cannot leak into a
+ * clean attempt: the worktree's own checkout is the only source for those. A
+ * path already present in the worktree is left alone, so recreating one never
+ * clobbers what an attempt left there.
+ *
+ * @param {string} repo @param {string} worktree @param {string[]} readFiles @returns {void}
+ */
+function carryDeclaredReads(repo, worktree, readFiles) {
+  const repoRoot = resolve(repo);
+  const realRepoRoot = realpathSync(repoRoot);
+  for (const read of readFiles) {
+    if (typeof read !== "string" || !read || isAbsolute(read)) continue;
+    const source = resolve(repoRoot, read);
+    let real;
+    try {
+      if (!statSync(source).isFile()) continue;
+      real = realpathSync(source);
+    } catch {
+      // Absent or unreadable — including a broken symlink inside the path:
+      // nothing exists to carry, and a declared read may legitimately be
+      // produced later or removed since authoring.
+      continue;
+    }
+    // Containment inline: task-packet.mjs owns pathInside privately, and a
+    // second top-level body would fail the duplicate-body gate.
+    const rel = relative(realRepoRoot, real);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
+    if (gitTracks(repo, read)) continue;
+    const target = join(worktree, read);
+    if (existsSync(target) || isSymlink(target)) continue;
+    mkdirSync(dirname(target), { recursive: true });
+    // A copy, never a symlink back at the checkout: the attempt's grounding
+    // input is frozen at creation, exactly like the tracked content around it.
+    writeFileSync(target, readFileSync(source));
+  }
+}
+
+/**
+ * Whether git lists the path in the index, i.e. a fresh worktree's checkout
+ * already brings it on its own.
+ *
+ * @param {string} repo @param {string} read @returns {boolean}
+ */
+function gitTracks(repo, read) {
+  try {
+    return git(repo, ["ls-files", "--", read]).length > 0;
+  } catch {
+    // git could not answer (locked index, unusable repository): fail toward
+    // "tracked", because never copying a tracked file outranks carrying one.
+    return true;
+  }
+}
+
 /**
  * @param {{repo: string, path: string, baseSha: string|null, runId: string, nodeId: string, attempt: number}} args
  * @returns {SealedAttempt}
@@ -260,12 +310,12 @@ export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt }) {
   // entry is that link would look dirty, stage it, unstage it, and commit an
   // empty change set — which exits 1 and turns every retry of an
   // already-sealed attempt into a hard failure.
-  const dirty = git(path, ["status", "--porcelain=v1", "--", ".", ":(exclude).runs", ":(exclude)node_modules"]);
+  const dirty = git(path, ["status", "--porcelain=v1", "--", ".", `:(exclude)${RUNS_DIR_NAME}`, ":(exclude)node_modules"]);
   if (dirty) {
     runGit(["-C", path, "add", "-A", "--", "."]);
     // node_modules is linked into the worktree as a symlink, which `node_modules/`
     // in .gitignore does not match; never let the link into the attempt commit.
-    runGit(["-C", path, "rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", ".runs", "node_modules"]);
+    runGit(["-C", path, "rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", RUNS_DIR_NAME, "node_modules"]);
     runGit([
       "-C", path,
       "-c", "user.email=runner@example.test",
@@ -339,6 +389,23 @@ export function removeWorktree(repo, path) {
   }
 }
 
+/**
+ * Release one node's attempt worktree and the branch name it was checked out
+ * on. Git refuses to delete a branch that is still checked out anywhere, so
+ * the worktree goes first; both halves already tolerate an artefact that is
+ * already gone, which is what makes calling this on an accepted (worktree
+ * already `removed`) or an already-released attempt harmless.
+ *
+ * @param {string} repo
+ * @param {string|null|undefined} path
+ * @param {string} branch
+ * @returns {void}
+ */
+export function releaseAttemptWorktree(repo, path, branch) {
+  removeWorktree(repo, path);
+  deleteRef(repo, `refs/heads/${branch}`);
+}
+
 /** @param {string} repo @param {string} runDir @param {string} runId @returns {void} */
 export function cleanupCandidate(repo, runDir, runId) {
   removeWorktree(repo, candidateWorktreePath(runDir, runId));

package/src/report/next.mjs

@@ -14,6 +14,7 @@
  * never through `loadRun`/`validateNodeSnapshot`: a torn snapshot is exactly
  * the case this command must survive and report, not crash on.
  */
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { discoverCampaigns } from "../campaign/index.mjs";
 import { readJournalForDedupe } from "../campaign/journal.mjs";
@@ -23,7 +24,17 @@ import { errorMessage } from "../util.mjs";
 
 /** @typedef {Record<string, unknown>} JsonObject */
 /** @typedef {import("../campaign/index.mjs").Campaign} Campaign */
-/** @typedef {{campaign: string, rank: number, reason: string, command: string, runnable: boolean}} NextItem */
+/**
+ * `message`, when present, is the newest already-rendered progress line for
+ * the campaign (read back from a linked run's own `notify.jsonl`, never
+ * re-rendered here). Every per-node/per-run candidate constructor below
+ * leaves it unset; `campaignItem` attaches it once, to whichever candidate
+ * wins, so there is exactly one place that decides it rather than every
+ * constructor repeating the read. It is for the human text only --
+ * `renderNextJson` keeps carrying structure, not prose, so it omits this
+ * field.
+ * @typedef {{campaign: string, rank: number, reason: string, command: string, runnable: boolean, message?: string|null}} NextItem
+ */
 
 /** Node states that are still in flight, versus every settled terminal state. */
 const IN_PROGRESS = new Set(["pending", "running"]);
@@ -49,6 +60,7 @@ export function computeNextItems(runsDir, cwd) {
       reason: `campaign ${entry.id} unreadable: ${errorMessage(entry.error)} (${entry.path})`,
       command: "",
       runnable: false,
+      message: null,
     });
   }
   for (const entry of campaigns) {
@@ -139,21 +151,60 @@ function campaignItem(entry, runsDir, cwd) {
     }
   }
 
+  const message = newestCampaignMessage(runsDir, campaign);
   const best = candidates.reduce(
     (found, candidate) => (!found || candidate.rank < found.rank ? candidate : found),
     /** @type {NextItem|null} */ (null),
   );
-  if (best) return best;
-  if (!inProgress) return closureItem(campaign, entry.path, cwd);
+  if (best) return { ...best, message };
+  if (!inProgress) return { ...closureItem(campaign, entry.path, cwd), message };
   return {
     campaign: campaign.id,
     rank: 6,
     reason: `run ${liveRunId ?? campaign.linkedRunIds[0] ?? ""} live; nothing to do`,
     command: "",
     runnable: false,
+    message,
   };
 }
 
+/**
+ * The newest already-rendered notification text across every run this
+ * campaign links, read straight from each run's own `notify.jsonl` receipts
+ * -- the durable, already-rendered text `NotifyQueue.enqueue` wrote, not a
+ * fresh render. `next` is a second audience for that same string, the way a
+ * bound transport is: reading it back here can never disagree with what the
+ * transport already received, because nothing here re-renders it.
+ *
+ * @param {string} runsDir
+ * @param {Campaign} campaign
+ * @returns {string|null}
+ */
+function newestCampaignMessage(runsDir, campaign) {
+  /** @type {{at: string, summary: string}[]} */
+  const receipts = [];
+  for (const runId of campaign.linkedRunIds) {
+    let text;
+    try {
+      text = readFileSync(join(runsDir, runId, "notify.jsonl"), "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (entry && typeof entry.summary === "string" && typeof entry.at === "string") receipts.push({ at: entry.at, summary: entry.summary });
+    }
+  }
+  const newest = receipts.sort((left, right) => left.at.localeCompare(right.at)).at(-1);
+  return newest ? newest.summary : null;
+}
+
 /**
  * A live controller is the exact inverse of the stale test: a lock that is
  * absent, `{invalid: true}` (unparsable), stale, or unreadable is not live.
@@ -363,11 +414,20 @@ function closureItem(campaign, campaignPath, cwd) {
   };
 }
 
-/** @param {NextItem} item @returns {string} */
+/**
+ * The item's own line, plus its newest progress message indented on the line
+ * after it when one exists -- the same string `next --json` deliberately
+ * omits, since prose has no place in that structured payload.
+ *
+ * @param {NextItem} item
+ * @returns {string}
+ */
 function renderLine(item) {
   const prefix = `${item.campaign}: ${item.reason}`;
-  if (!item.command) return prefix;
-  return `${prefix} · ${item.command}${item.runnable ? "" : " [template]"}`;
+  const line = item.command ? `${prefix} · ${item.command}${item.runnable ? "" : " [template]"}` : prefix;
+  if (!item.message) return line;
+  const indented = item.message.split("\n").map((part) => `  ${part}`).join("\n");
+  return `${line}\n${indented}`;
 }
 
 /**