faberun 0.3.0

package/src/repo/signal.mjs

@@ -0,0 +1,222 @@
+/**
+ * The faberun signal block in the target repository's AGENTS.md.
+ *
+ * Every agent that opens the repository — whatever the harness — reads
+ * AGENTS.md before its first prompt. The runner mirrors its active state
+ * there so a takeover session learns that active work exists without
+ * probing .runs/. The block is machine-managed: agents read it, never edit
+ * it.
+ *
+ * The defect this module fixes is what the block says, not whether it is
+ * rewritten. A run that parked — every node terminal but none successful —
+ * used to disappear, because the old renderer only listed runs holding a
+ * node that was not terminal. A session reading the block learned nothing
+ * about the work that most needs it. The block now renders the phase-2
+ * `runOutcome` per linked run: `parked` with its nodes, their error codes and
+ * the exact `resume` command; `succeeded` as one line; plus the most recent
+ * campaign-level `attention` entry from `.runs/inbox.jsonl`. It is bounded,
+ * because every session pays for it in its first tokens.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { discoverCampaigns } from "../campaign/index.mjs";
+import { runProgress } from "../engine/supervise.mjs";
+import { readInbox } from "../notify/index.mjs";
+import { SIGNAL_END, SIGNAL_START } from "./signal-block.mjs";
+import { HANDOFF_FILE } from "../campaign/layout.mjs";
+
+export { SIGNAL_END, SIGNAL_START } from "./signal-block.mjs";
+
+/** Keep the block cheap for every session; a campaign with many runs is summarised, not dumped. */
+const SIGNAL_LINES_BYTE_BUDGET = 2_600;
+/** How many parked nodes are named before the rest are counted. */
+const MAX_PARKED_NODES = 6;
+/** One attention entry, bounded like a notification summary. */
+const ATTENTION_CHARS = 200;
+
+const HEADER = "Before starting new work here, check `.runs/`: if a campaign is active or a run is not terminal, continue it instead of starting over — read its `HANDOFF.md`/`STATUS.md`, attach to the campaign, and `resume` or `supervise` the run. Active runs are supervised by a deterministic detached process: do not poll `status` in a loop — on resume, check status once and act only on terminal states.";
+
+/**
+ * @param {string} runsDir
+ * @returns {string}
+ */
+export function renderAgentSignalBlock(runsDir) {
+  /** @type {string[]} */
+  const lines = [];
+  /** @type {Set<string>} */
+  const linked = new Set();
+  const { campaigns } = discoverCampaigns(runsDir);
+  for (const { campaign } of campaigns.filter(({ campaign }) => campaign.status !== "closed")) {
+    lines.push(`- faberun campaign \`${campaign.id}\`: active — read \`.runs/campaigns/${campaign.id}/${HANDOFF_FILE}\``);
+    for (const runId of campaign.linkedRunIds) {
+      linked.add(runId);
+      lines.push(...runSignalLines(runsDir, runId));
+    }
+    const attention = campaignAttentionLine(runsDir, campaign);
+    if (attention) lines.push(attention);
+  }
+  for (const line of activeRunLines(runsDir, linked)) lines.push(line);
+  if (!lines.length) return "";
+  return `${SIGNAL_START}\n${HEADER}\n\n${boundLines(lines).join("\n")}\n${SIGNAL_END}`;
+}
+
+/**
+ * One linked run's outcome as block lines. `runProgress` folds the phase-2
+ * `runOutcome`, so a parked run is rendered by its own declared nodes rather
+ * than being dropped for having no non-terminal one.
+ *
+ * @param {string} runsDir
+ * @param {string} runId
+ * @returns {string[]}
+ */
+function runSignalLines(runsDir, runId) {
+  const runDir = join(runsDir, runId);
+  const resume = `node src/cli.mjs resume ${runDir}`;
+  if (!existsSync(runDir)) {
+    return [`  - run \`${runId}\`: missing — resume \`${resume}\``];
+  }
+  const progress = runProgress(runDir);
+  switch (progress.runOutcome) {
+    case "succeeded":
+      return [`  - run \`${runId}\`: succeeded (${progress.terminal}/${progress.total} nodes)`];
+    case "canceled":
+      return [`  - run \`${runId}\`: canceled`];
+    case "waiting":
+      return [`  - run \`${runId}\`: waiting${progress.waitingUntil ? ` until ${progress.waitingUntil}` : ""} — supervise \`node src/cli.mjs supervise ${runDir}\``];
+    case "parked":
+      break;
+    default:
+      // No snapshot yet: the run exists but has not proved an outcome. It is
+      // active work, not parked work, so it must not claim parked nodes.
+      return [`  - run \`${runId}\`: active — read \`.runs/${runId}/STATUS.md\`; \`resume\` or \`supervise\` it`];
+  }
+  const nodes = progress.outcomeNodes ?? [];
+  const shown = nodes.slice(0, MAX_PARKED_NODES).map(nodeText).join(", ");
+  const more = nodes.length > MAX_PARKED_NODES ? `, +${nodes.length - MAX_PARKED_NODES} more` : "";
+  return [`  - run \`${runId}\`: parked — ${shown || "no nodes named"}${more} — resume \`${resume}\``];
+}
+
+/**
+ * Standalone runs that no active campaign links. A parked run is included, so
+ * a run with no campaign at all still blocks a naive "start fresh".
+ *
+ * @param {string} runsDir
+ * @param {Set<string>} linked
+ * @returns {string[]}
+ */
+function activeRunLines(runsDir, linked) {
+  if (!existsSync(runsDir)) return [];
+  /** @type {string[]} */
+  const lines = [];
+  for (const name of readdirSync(runsDir)) {
+    if (linked.has(name)) continue;
+    const nodeDir = join(runsDir, name, "nodes");
+    if (!existsSync(nodeDir)) continue;
+    const runDir = join(runsDir, name);
+    const progress = runProgress(runDir);
+    // A nodes directory with no committed snapshot is a creation in progress,
+    // not evidence of work; the old renderer left it off and so does this one.
+    if (progress.runOutcome === undefined && progress.total === 0) continue;
+    if (progress.runOutcome === "succeeded" || progress.runOutcome === "canceled") continue;
+    const resume = `node src/cli.mjs resume ${runDir}`;
+    if (progress.runOutcome === "parked" && progress.state === "done") {
+      const nodes = (progress.outcomeNodes ?? []).slice(0, MAX_PARKED_NODES).map(nodeText).join(", ");
+      lines.push(`- faberun run \`${name}\`: parked — ${nodes || "no nodes named"} — resume \`${resume}\``);
+    } else {
+      lines.push(`- faberun run \`${name}\`: active (${progress.terminal}/${progress.total} nodes done) — read \`.runs/${name}/STATUS.md\`; \`resume\` or \`supervise\` it`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * The most recent campaign-level attention: an inbox entry when one exists,
+ * otherwise the durable record on the campaign itself.
+ *
+ * @param {string} runsDir
+ * @param {import("../campaign/index.mjs").Campaign} campaign
+ * @returns {string|null}
+ */
+function campaignAttentionLine(runsDir, campaign) {
+  const latest = readInbox(runsDir)
+    .filter((entry) => entry.type === "attention" && (entry.campaignId === campaign.id || entry.campaignId === null))
+    .at(-1);
+  if (latest) return `  - attention: ${boundedAttention(latest.summary)}`;
+  if (campaign.attention && typeof campaign.attention.message === "string") {
+    const code = campaign.attention.code ? ` (${campaign.attention.code})` : "";
+    return `  - attention: ${boundedAttention(`${campaign.attention.message}${code}`)}`;
+  }
+  return null;
+}
+
+/**
+ * @param {import("../engine/supervise.mjs").OutcomeNode} node
+ * @returns {string}
+ */
+function nodeText(node) {
+  return `\`${node.id}:${node.status ?? "unknown"}${node.errorCode ? ` ${node.errorCode}` : ""}\``;
+}
+
+/** @param {string} value @returns {string} */
+function boundedAttention(value) {
+  return value.length <= ATTENTION_CHARS ? value : `${value.slice(0, ATTENTION_CHARS - 1)}…`;
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {string[]}
+ */
+function boundLines(lines) {
+  /** @type {string[]} */
+  const out = [];
+  let bytes = 0;
+  for (const line of lines) {
+    const size = Buffer.byteLength(line, "utf8") + 1;
+    if (bytes + size > SIGNAL_LINES_BYTE_BUDGET) {
+      out.push("- … signal truncated; read the campaign HANDOFF.md for the rest");
+      break;
+    }
+    out.push(line);
+    bytes += size;
+  }
+  return out;
+}
+
+/**
+ * Rewrites the managed signal block at the bottom of <repo>/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.
+ *
+ * @param {string} runsDir
+ * @returns {boolean}
+ */
+export function syncAgentSignal(runsDir) {
+  const agentsPath = join(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 (next === current) return false;
+  writeFileSync(agentsPath, next);
+  return true;
+}

package/src/repo/source-identity.mjs

@@ -0,0 +1,295 @@
+/**
+ * The identity a run is pinned to: the git head it started from, a fingerprint
+ * of the dirty tree, the hash of every task packet, the agent-guidance files in
+ * force, and the harness versions observed.
+ *
+ * This is what makes a resume honest. A run that resumes against a different
+ * head, a changed packet or an edited `AGENTS.md` is not the run that was
+ * approved, and `validateCompleteSourceIdentity` is where that is refused.
+ */
+import { Buffer } from "node:buffer";
+import { assertObject, rejectUnknown, requireId, requirePacketHash, requireString } from "../contract/assert.mjs";
+import { createHash } from "node:crypto";
+import { errorCode } from "../util.mjs";
+import { boundedGitSync } from "./worktree.mjs";
+import { lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { normalizeManagedSignalBlock } from "./signal-block.mjs";
+
+/** @typedef {import("../notify/index.mjs").JsonObject} JsonObject */
+/** @typedef {import("../contract/index.mjs").SourceIdentity} SourceIdentity */
+/** @typedef {{encoding?: "utf8"|"buffer", stdio?: import("node:child_process").StdioOptions}} GitReadOptions */
+
+/**
+ * Run one bounded synchronous git read and surface a failure as a throw, so
+ * the callers below keep their `try/catch` shape. Every `execFileSync("git")`
+ * here went through this helper so a held index lock cannot hang the controller.
+ *
+ * @param {string[]} args
+ * @param {GitReadOptions} [options]
+ * @returns {string|Buffer}
+ */
+function gitSyncOrThrow(args, options = {}) {
+  const result = boundedGitSync(args, options);
+  if (result.error || result.status !== 0) {
+    throw result.error ?? new Error(`git ${args.join(" ")} exited ${result.status}`);
+  }
+  return result.stdout;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {JsonObject|null} expected
+ */
+export function validateSourceIdentity(value, label, expected = null) {
+  assertObject(value, label);
+  const allowed = new Set([
+    "kind", "id", "campaignId", "contractId", "nodeId", "cwd", "gitHead",
+    "dirtyTreeFingerprint", "packetHashes", "harnessVersions",
+  ]);
+  rejectUnknown(value, allowed, label);
+  requireString(value.kind, `${label}.kind`);
+  for (const key of ["id", "campaignId", "contractId", "nodeId"]) {
+    if (value[key] !== undefined) requireId(value[key], `${label}.${key}`);
+  }
+  if (value.cwd !== undefined) requireString(value.cwd, `${label}.cwd`);
+  for (const key of ["gitHead", "dirtyTreeFingerprint"]) {
+    if (value[key] !== undefined && value[key] !== null) requireString(value[key], `${label}.${key}`);
+  }
+  if (value.packetHashes !== undefined) validateHashMap(value.packetHashes, `${label}.packetHashes`);
+  if (value.harnessVersions !== undefined) {
+    assertObject(value.harnessVersions, `${label}.harnessVersions`);
+    for (const [key, version] of Object.entries(value.harnessVersions)) {
+      requireId(key, `${label}.harnessVersions key`);
+      if (version !== null) requireString(version, `${label}.harnessVersions.${key}`);
+    }
+  }
+  if (expected) {
+    for (const [key, expectedValue] of Object.entries(expected)) {
+      if (value[key] !== expectedValue) throw new TypeError(`${label}.${key} does not match its source`);
+    }
+  }
+  return /** @type {SourceIdentity} */ ({ ...value });
+}
+/**
+ * @param {{id: string, campaignId: string, cwd: string, nodes: {id: string, packetHash: string}[]}} contract
+ * @param {Record<string, string|null>} harnessVersions
+ * @param {{ignorePaths?: string[], ignoreRoots?: string[]}} options
+ */
+export function captureSourceIdentity(contract, harnessVersions = {}, options = {}) {
+  const git = gitIdentity(contract.cwd, options);
+  return validateSourceIdentity({
+    kind: "run",
+    contractId: contract.id,
+    campaignId: contract.campaignId,
+    cwd: contract.cwd,
+    gitHead: git.gitHead,
+    dirtyTreeFingerprint: git.dirtyTreeFingerprint,
+    packetHashes: Object.fromEntries(contract.nodes.map((node) => [node.id, node.packetHash])),
+    harnessVersions,
+  }, "run source identity", { kind: "run", contractId: contract.id, campaignId: contract.campaignId });
+}
+/**
+ * @param {JsonObject} value
+ */
+export function validateCompleteSourceIdentity(value) {
+  for (const key of ["cwd", "gitHead", "dirtyTreeFingerprint", "packetHashes", "harnessVersions"]) {
+    if (!Object.hasOwn(value, key)) throw new TypeError(`run metadata.sourceIdentity.${key} is required for resume`);
+  }
+}
+/**
+ * @param {unknown} value
+ * @param {string} label
+ */
+function validateHashMap(value, label) {
+  assertObject(value, label);
+  for (const [key, hash] of Object.entries(value)) {
+    requireId(key, `${label} key`);
+    requirePacketHash(hash, `${label}.${key}`);
+  }
+}
+/**
+ * The pathspec that scopes a source-identity read: everything, minus the
+ * factory's own run tree, minus the machine-managed AGENTS.md signal, minus
+ * whatever the caller declared out of scope.
+ *
+ * @param {{ignorePaths?: string[], ignoreRoots?: string[]}} options
+ * @returns {string[]}
+ */
+function sourcePathspec(options = {}) {
+  return [
+    ".",
+    ":(exclude).runs",
+    ":(exclude)AGENTS.md",
+    ...(options.ignorePaths ?? []).map((path) => `:(exclude)${path}`),
+    ...(options.ignoreRoots ?? []).map((path) => `:(exclude)${path}`),
+  ];
+}
+
+/**
+ * The commit a source identity is pinned to. Without `baseRef` this is the
+ * checkout's own HEAD, with the unborn-HEAD probe that makes a fresh
+ * repository report `null` rather than fail. With `baseRef` it is that ref's
+ * sha, so a run can be cut from a landing branch while the operator's tree
+ * stays on whatever they were doing.
+ *
+ * @param {string} cwd
+ * @param {string|undefined} baseRef
+ * @returns {string|null}
+ */
+function resolveGitHead(cwd, baseRef) {
+  if (baseRef) {
+    try {
+      return String(gitSyncOrThrow(["-C", cwd, "rev-parse", baseRef], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      })).trim() || null;
+    } catch {
+      // An unknown ref resolves to null; the caller decides whether that is fatal.
+      return null;
+    }
+  }
+  const headPath = resolve(cwd, ".git", "HEAD");
+  let headText = null;
+  try { headText = readFileSync(headPath, "utf8").trim(); } catch {
+    // A missing or unreadable .git/HEAD leaves headText null; rev-parse below still decides gitHead.
+  }
+  if (headText?.startsWith("ref: ") === true) {
+    try { lstatSync(resolve(cwd, ".git", headText.slice(5))); }
+    catch (error) { if (errorCode(error) !== "ENOENT") throw error; return null; }
+  }
+  try {
+    return String(gitSyncOrThrow(["-C", cwd, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    })).trim() || null;
+  } catch {
+    // Any rev-parse failure (no repo, unborn HEAD, git absent) leaves gitHead null.
+    return null;
+  }
+}
+
+/**
+ * The paths the working tree has modified, added or left untracked, ignoring
+ * the factory's own `.runs` tree and the machine-managed AGENTS.md signal. A
+ * clean tree is `[]`; an unreadable tree is treated as clean because the
+ * caller has no dirt to name.
+ *
+ * @param {string} cwd
+ * @param {{ignorePaths?: string[], ignoreRoots?: string[]}} [options]
+ * @returns {string[]}
+ */
+export function dirtyTreePaths(cwd, options = {}) {
+  try {
+    const status = String(gitSyncOrThrow(["-C", cwd, "status", "--porcelain=v1", "--untracked-files=all", "-z", "--", ...sourcePathspec(options)], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }));
+    return status.split("\0").filter(Boolean);
+  } catch {
+    // Not a repository, or git absent: there is no dirt the launch can name.
+    return [];
+  }
+}
+
+/**
+ * Refuse a launch whose base is the checked-out HEAD and whose tree is dirty.
+ * The base is what every worktree is cut from, so a dirty tree only matters
+ * when it *is* the base: then the validator sees files the worker will never
+ * have. A base ref that resolves elsewhere leaves the operator's checkout
+ * alone and is always clean enough to launch from.
+ *
+ * The launch's own contract file is passed in `ignorePaths`: it is the input
+ * being launched, written or re-authored immediately before the command, and
+ * is not source the worktrees are cut from.
+ *
+ * @param {string} cwd
+ * @param {string|undefined} baseRef
+ * @param {{ignorePaths?: string[], ignoreRoots?: string[]}} [options]
+ * @returns {void}
+ */
+export function assertLaunchBaseClean(cwd, baseRef, options = {}) {
+  const headSha = resolveGitHead(cwd, undefined);
+  const baseSha = baseRef ? resolveGitHead(cwd, baseRef) : headSha;
+  if (baseRef && !baseSha) {
+    throw Object.assign(new Error(`base ref does not resolve: ${baseRef}`), { code: "base_ref_unresolved" });
+  }
+  if (!baseSha || !headSha || baseSha !== headSha) return;
+  const dirty = dirtyTreePaths(cwd, options);
+  if (dirty.length) {
+    const label = baseRef ?? "HEAD";
+    throw Object.assign(
+      new Error(`refusing to launch against ${label}: the working tree has ${dirty.length} uncommitted path${dirty.length === 1 ? "" : "s"}; commit or stash before running when the cwd HEAD is the base, or pass --base-ref for a different base`),
+      { code: "dirty_work_tree" },
+    );
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ignorePaths?: string[], ignoreRoots?: string[], baseRef?: string}} options
+ * @returns {{gitHead: string|null, dirtyTreeFingerprint: string|null}}
+ */
+export function gitIdentity(cwd, options = {}) {
+  try {
+    const pathspec = sourcePathspec(options);
+    const gitHead = resolveGitHead(cwd, options.baseRef);
+    const status = /** @type {Buffer} */ (gitSyncOrThrow(["-C", cwd, "status", "--porcelain=v1", "--untracked-files=all", "-z", "--", ...pathspec], {
+      encoding: "buffer",
+      stdio: ["ignore", "pipe", "ignore"],
+    }));
+    const statusText = status.toString("utf8");
+    const diff = !gitHead || status.length === 0
+      ? Buffer.alloc(0)
+      : /** @type {Buffer} */ (gitSyncOrThrow(["-C", cwd, "diff", "--binary", "HEAD", "--", ...pathspec], {
+        encoding: "buffer",
+        stdio: ["ignore", "pipe", "ignore"],
+      }));
+    const untrackedFiles = statusText.split("\0")
+      .filter((entry) => entry.startsWith("?? "))
+      .map((entry) => entry.slice(3));
+    const contents = createHash("sha256");
+    for (const relativePath of untrackedFiles) {
+      const absolutePath = resolve(cwd, relativePath);
+      const metadata = lstatSync(absolutePath);
+      contents.update(`${relativePath}\0${metadata.mode}\0`);
+      if (metadata.isSymbolicLink()) contents.update(readlinkSync(absolutePath));
+      else if (metadata.isFile()) contents.update(readFileSync(absolutePath));
+      contents.update("\0");
+    }
+    return {
+      gitHead,
+      dirtyTreeFingerprint: createHash("sha256")
+        .update(status)
+        .update(diff)
+        .update(contents.digest())
+        .update(agentGuidanceIdentity(cwd))
+        .digest("hex"),
+    };
+  } catch {
+    return { gitHead: null, dirtyTreeFingerprint: null };
+  }
+}
+/**
+ * Hash AGENTS.md separately so its machine-managed signal may change without
+ * hiding edits to human-authored repository guidance.
+ *
+ * @param {string} cwd
+ * @returns {Buffer}
+ */
+function agentGuidanceIdentity(cwd) {
+  const path = resolve(cwd, "AGENTS.md");
+  const identity = createHash("sha256").update("AGENTS.md\0");
+  try {
+    const metadata = lstatSync(path);
+    identity.update(`${metadata.mode}\0`);
+    if (metadata.isSymbolicLink()) identity.update(`symlink\0${readlinkSync(path)}`);
+    else if (metadata.isFile()) identity.update(`file\0${normalizeManagedSignalBlock(readFileSync(path, "utf8"))}`);
+    else identity.update("unsupported");
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+    identity.update("missing");
+  }
+  return identity.digest();
+}