faberun 0.11.0 → 0.12.0

package/src/cli/project.mjs

@@ -0,0 +1,150 @@
+/**
+ * `faberun project`: re-associate a project whose repository moved, keeping
+ * its id -- and everything that will hang off that id -- untouched.
+ *
+ * `src/host/projects.mjs` is out of this node's write scope, and its public
+ * surface (`registerProject`, `findProjectByPath`, `readProject`) has no
+ * operation that keeps an existing id while giving it a new path:
+ * `registerProject` either finds the id already at a path or mints a fresh
+ * one, and a fresh id is exactly what a move must not produce. This module
+ * therefore reads and rewrites `projects/index.json` and
+ * `projects/<id>/project.json` directly, with the same temp-then-rename
+ * discipline the registry itself uses, rather than inventing a second
+ * on-disk format for the same directory.
+ */
+import { join } from "node:path";
+import { readJson, writeJsonAtomic } from "../run/store.mjs";
+import { errorCode } from "../util.mjs";
+import { findProjectByPath, projectsDir, readProject, resolveIdentity } from "../host/projects.mjs";
+import { boundedGitSync } from "../repo/worktree.mjs";
+
+/** @typedef {import("../host/projects.mjs").ProjectRecord} ProjectRecord */
+
+/**
+ * The path-to-id index, read straight off `index.json`. Inlined at each of
+ * its two call sites rather than pulled out as a shared top-level helper: the
+ * identical helper already lives, unexported, in `host/projects.mjs`, which
+ * this module cannot import from without that file entering its write scope.
+ *
+ * @param {string} indexPath
+ * @returns {Record<string, string>}
+ */
+function readIndexAt(indexPath) {
+  try {
+    return /** @type {Record<string, string>} */ (readJson(indexPath));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return {};
+    throw error;
+  }
+}
+
+/**
+ * Every registered project, read straight off disk. Used only to search by
+ * remote when the operator names no `--from`.
+ *
+ * @param {string} home
+ * @returns {ProjectRecord[]}
+ */
+function listProjects(home) {
+  const index = readIndexAt(join(projectsDir(home), "index.json"));
+  const ids = new Set(Object.values(index));
+  /** @type {ProjectRecord[]} */
+  const projects = [];
+  for (const id of ids) {
+    const project = readProject(home, id);
+    if (project) projects.push(project);
+  }
+  return projects;
+}
+
+/**
+ * The remote URLs a git repository at `path` currently reports, or `[]` when
+ * `path` is not a git repository, has no remote, or git is unavailable. An
+ * operator who names `--from` never needs this at all.
+ *
+ * @param {string} path
+ * @returns {string[]}
+ */
+export function readRemotes(path) {
+  const result = boundedGitSync(["-C", path, "remote", "-v"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  if (result.error || result.status !== 0) return [];
+  /** @type {Set<string>} */
+  const urls = new Set();
+  for (const line of /** @type {string} */ (result.stdout).split("\n")) {
+    const match = /^\S+\s+(\S+)\s+\(/u.exec(line);
+    if (match) urls.add(match[1]);
+  }
+  return [...urls];
+}
+
+/**
+ * The registered project whose remotes overlap what `remotesOf(path)` reports
+ * right now, or null when none does, or when `path` reports no remote at all.
+ * More than one match is refused by the caller, not decided here.
+ *
+ * @param {string} home
+ * @param {string} path
+ * @param {(path: string) => string[]} remotesOf
+ * @returns {ProjectRecord[]}
+ */
+function projectsMatchingRemotes(home, path, remotesOf) {
+  const remotes = new Set(remotesOf(path));
+  if (remotes.size === 0) return [];
+  return listProjects(home).filter((project) => project.remotes.some((remote) => remotes.has(remote)));
+}
+
+/**
+ * @param {string} home
+ * @param {ProjectRecord} project
+ * @param {string} newPath
+ * @returns {ProjectRecord}
+ */
+function moveProject(home, project, newPath) {
+  const indexPath = join(projectsDir(home), "index.json");
+  const index = readIndexAt(indexPath);
+  delete index[project.path];
+  index[newPath] = project.id;
+  writeJsonAtomic(indexPath, index);
+  /** @type {ProjectRecord} */
+  const record = { ...project, path: newPath, updatedAt: new Date().toISOString() };
+  writeJsonAtomic(join(projectsDir(home), project.id, "project.json"), record);
+  return record;
+}
+
+/**
+ * Re-associate a project with the path its repository moved to.
+ *
+ * Idempotent by construction: when `newPath` is already the project's
+ * registered path -- whether this is the first call or a repeat of one that
+ * already landed -- the current record comes back untouched and nothing is
+ * written. That is deliberate: an operator unsure whether a previous attempt
+ * succeeded runs the same command again rather than inspecting the registry
+ * first.
+ *
+ * With `options.from`, the project once registered at that path is moved.
+ * Without it, the project is found by matching the git remotes `newPath`
+ * reports now against the remotes every registered project last recorded;
+ * no match, or more than one, is refused with a message naming what was
+ * looked for, rather than guessed.
+ *
+ * @param {string} home
+ * @param {string} newPath
+ * @param {{from?: string, remotesOf?: (path: string) => string[]}} [options]
+ * @returns {ProjectRecord}
+ */
+export function reassociateProject(home, newPath, options = {}) {
+  const resolvedNew = resolveIdentity(newPath);
+  const already = findProjectByPath(home, resolvedNew);
+  if (already) return already;
+  if (options.from) {
+    const resolvedFrom = resolveIdentity(options.from);
+    const found = findProjectByPath(home, resolvedFrom);
+    if (!found) throw new Error(`no project is registered at ${resolvedFrom}`);
+    return moveProject(home, found, resolvedNew);
+  }
+  const remotesOf = options.remotesOf ?? readRemotes;
+  const matches = projectsMatchingRemotes(home, resolvedNew, remotesOf);
+  if (matches.length === 0) throw new Error(`no registered project has the remotes reported at ${resolvedNew}`);
+  if (matches.length > 1) throw new Error(`${matches.length} registered projects share a remote reported at ${resolvedNew}; pass --from to disambiguate`);
+  return moveProject(home, matches[0], resolvedNew);
+}

package/src/cli/skills.mjs

@@ -20,7 +20,6 @@ import {
   readdirSync,
   realpathSync,
   rmSync,
-  symlinkSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
@@ -28,7 +27,7 @@ import { fileURLToPath } from "node:url";
 import { parseArgs as parseFlags } from "node:util";
 
 import { faberunHome, installedVersionDir } from "../host/home.mjs";
-import { findExecutable } from "../host/preflight.mjs";
+import { findExecutable, linkDirectory } from "../host/platform.mjs";
 import { colorLevel, statusToken } from "./brand.mjs";
 
 const SKILLS_DIR = fileURLToPath(new URL("../../skills", import.meta.url));
@@ -304,7 +303,7 @@ function linkSkill(source, destination, force) {
     if (!existing.isSymbolicLink() && !force) return "skipped";
     rmSync(destination, { recursive: true, force: true });
   }
-  symlinkSync(source, destination);
+  linkDirectory(destination, source);
   return "linked";
 }
 

package/src/cli/update.mjs

@@ -13,9 +13,10 @@
  * rather than something to compare as if it were a release.
  */
 import { spawnSync } from "node:child_process";
-import { mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { compareVersions, currentLink, faberunHome, installedVersionDir, tmpDir, versionsDir, writeUpdateCheck } from "../host/home.mjs";
+import { linkDirectory, tarExecutable } from "../host/platform.mjs";
 import { packageVersion } from "../host/package.mjs";
 import { errorMessage } from "../util.mjs";
 
@@ -170,7 +171,7 @@ async function downloadTarball(fetchImpl, url, destination) {
  * @returns {void}
  */
 function extractTarball(tarball, destination) {
-  const result = spawnSync("tar", ["-xzf", tarball, "--strip-components=1", "-C", destination], { encoding: "utf8" });
+  const result = spawnSync(tarExecutable(), ["-xzf", tarball, "--strip-components=1", "-C", destination], { encoding: "utf8" });
   if (result.error) throw result.error;
   if (result.status !== 0) throw new Error(`tar failed: ${String(result.stderr ?? "").trim() || `exit ${result.status}`}`);
 }
@@ -193,21 +194,17 @@ function verifyVersion(partial, version) {
 }
 
 /**
- * Point `current` at the new version atomically: a `current.tmp` symlink then a
- * rename over `current`, so a concurrent reader sees either the old target or
- * the new one, never a missing link.
+ * Point `current` at the new version. `linkDirectory` owns how: a rename over
+ * a sibling temporary link where the platform makes that atomic, a remove and
+ * remake on Windows where it does not.
  *
  * @param {string} home
  * @param {string} version
  * @returns {void}
  */
 function repointCurrent(home, version) {
-  const link = currentLink(home);
-  const temporary = `${link}.tmp`;
-  rmSync(temporary, { force: true });
   // SPEC.md's layout: `current -> versions/<v>`, relative to the home.
-  symlinkSync(join("versions", version), temporary);
-  renameSync(temporary, link);
+  linkDirectory(currentLink(home), join("versions", version));
 }
 
 /** @returns {Record<string, string>} */

package/src/cli.mjs

@@ -9,8 +9,11 @@ import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { modelsCommand } from "./harnesses/catalogue.mjs";
 import { bulkReadCommand } from "./engine/bulk-read.mjs";
-import { doctorCommand, environmentPreflight, findExecutable, notifyTransportCheck, reachableRuntimes, timeVerificationCommands } from "./host/preflight.mjs";
+import { doctorCommand, environmentPreflight, notifyTransportCheck, reachableRuntimes, timeVerificationCommands } from "./host/preflight.mjs";
+import { findExecutable } from "./host/platform.mjs";
 import { packageName, packageVersion } from "./host/package.mjs";
+import { faberunHome } from "./host/home.mjs";
+import { reassociateProject } from "./cli/project.mjs";
 import { colorLevel, renderBanner, renderUsage, statusToken } from "./cli/brand.mjs";
 import { noTransportWarning } from "./notify/index.mjs";
 import { renderFindings, renderReport, renderReportJson, renderStatus, renderStatusJson } from "./report/render.mjs";
@@ -19,6 +22,8 @@ import { renderNext, renderNextJson } from "./report/next.mjs";
 import {
   writeTextAtomic,
 } from "./run/store.mjs";
+import { runDirectory, runsRoot } from "./run/paths.mjs";
+import { migrateRunState } from "./run/migrate.mjs";
 import {
   acquire as acquireLock,
   validBootstrapNonce,
@@ -105,6 +110,8 @@ export const COMMAND_OPTIONS = {
   "bulk-read": { question: { type: "string" }, paths: { type: "string", multiple: true }, json: { type: "boolean" } },
   next: { cwd: { type: "string" }, json: { type: "boolean" } },
   update: { check: { type: "boolean" }, json: { type: "boolean" } },
+  project: { from: { type: "string" } },
+  migrate: { cwd: { type: "string" } },
   setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, "no-skill": { type: "boolean" }, json: { type: "boolean" } },
   init: { cwd: { type: "string" }, yes: { type: "boolean" }, "no-skill": { type: "boolean" }, agentkit: { type: "boolean" }, greenfield: { type: "boolean" }, stable: { type: "boolean" }, json: { type: "boolean" } },
   metrics: METRICS_OPTIONS,
@@ -145,7 +152,8 @@ function parseCli(argv, quiet = false) {
   if (command === "update" && parsed.positionals.length !== 0) return null;
   if (command === "setup" && parsed.positionals.length !== 0) return null;
   if (command === "init" && parsed.positionals.length !== 0) return null;
-  if (command !== "doctor" && command !== "models" && command !== "bulk-read" && command !== "next" && command !== "update" && command !== "setup" && command !== "init" && parsed.positionals.length !== 1) return null;
+  if (command === "migrate" && parsed.positionals.length !== 0) return null;
+  if (command !== "doctor" && command !== "models" && command !== "bulk-read" && command !== "next" && command !== "update" && command !== "setup" && command !== "init" && command !== "migrate" && parsed.positionals.length !== 1) return null;
   return {
     command,
     target: parsed.positionals[0],
@@ -246,7 +254,7 @@ async function main(argv) {
   }
   if (command === "next") {
     const cwd = resolve(typeof values.cwd === "string" ? values.cwd : ".");
-    const runsDir = join(cwd, ".runs");
+    const runsDir = runsRoot(cwd);
     process.stdout.write(values.json === true ? renderNextJson(runsDir, cwd) : renderNext(runsDir, cwd));
     return;
   }
@@ -288,13 +296,31 @@ async function main(argv) {
     });
     return;
   }
+  if (command === "migrate") {
+    const result = migrateRunState(resolve(typeof values.cwd === "string" ? values.cwd : "."), { home: faberunHome(process.env) });
+    if (!result.moved) {
+      process.stdout.write(`[migrate] nothing to move · ${result.legacy} does not exist\n`);
+      return;
+    }
+    const runs = `${result.runs} run${result.runs === 1 ? "" : "s"}`;
+    const campaigns = `${result.campaigns} campaign${result.campaigns === 1 ? "" : "s"}`;
+    process.stdout.write(`[migrate] ${result.legacy} -> ${result.target} · ${runs}, ${campaigns}\n`);
+    return;
+  }
   if (!target) { usage(); return; }
+  if (command === "project") {
+    const record = reassociateProject(faberunHome(process.env), target, {
+      from: typeof values.from === "string" && values.from ? values.from : undefined,
+    });
+    process.stdout.write(`[project] ${record.id} · ${record.path}\n`);
+    return;
+  }
   if (command === "run") {
     warnIfNoTransport();
     const absolute = resolve(target);
     const baseRef = typeof values["base-ref"] === "string" && values["base-ref"] ? values["base-ref"] : undefined;
     const contract = validateContractForLaunch(JSON.parse(readFileSync(absolute, "utf8")), absolute, { baseRef });
-    const runDir = join(contract.cwd, ".runs", contract.id);
+    const runDir = runDirectory(contract.cwd, contract.id);
     setLaunchBaseRef(baseRef);
     // The base is what every worktree is cut from; a dirty tree only blocks
     // when the cwd HEAD *is* that base. A `--base-ref` elsewhere leaves the

package/src/contract/index.mjs

@@ -20,6 +20,16 @@ import { crossNodeScopeFindings, scopeClosureFindings } from "../repo/scope-clos
 
 export { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../harnesses/index.mjs";
 
+// Mirrors test/repo/source-shape.test.mjs's LINE_CEILING; that test refuses a
+// file over it, at commit time. The margin is 100 lines: measured against
+// this tree (`find src -name '*.mjs' | xargs wc -l`, 2026-09-18), it is the
+// smallest round number that would have flagged both write targets a real
+// node overran -- 783 and 749 lines, both later landing at 801 -- while
+// catching only about 8 of this tree's ~230 modules today, so the warning
+// stays rare enough to read instead of becoming routine noise.
+const WRITE_FILE_LINE_CEILING = 800;
+const WRITE_FILE_LINE_WARN_MARGIN = 100;
+
 const CONTRACT_FIELDS = new Set([
   "schemaVersion", "contractVersion", "id", "campaignId", "goal", "cwd", "sourceIdentity",
   "maxParallel", "pollIntervalMs", "stallTimeoutSec", "timeoutSec",
@@ -337,6 +347,7 @@ export function validateContract(raw, contractPath, options = {}) {
   const warnings = nodes.flatMap((node, index) => [
     ...commandCoverageWarnings(node, index),
     ...(persisted ? [] : unsnapshottedWriteWarnings(node, index, cwd)),
+    ...(persisted ? [] : writeFileLineBudgetWarnings(node, index, cwd)),
   ]);
   const contract = /** @type {ValidatedContract} */ ({
     ...raw,
@@ -620,6 +631,39 @@ function dependencyCoversPath(closure, path, cwd) {
   return false;
 }
 
+/**
+ * A `writeFiles` entry naming a file already close to the line ceiling is
+ * legal -- the ceiling refuses the file itself, at commit time, not the
+ * contract that names it -- but a worker cannot discover the file has no
+ * room for its diff until an attempt has already spent an invocation
+ * finding out. This warns, never refuses, so the author decides whether the
+ * write set needs a split before dispatch. A missing file has no current
+ * count to warn about, so it is skipped, not treated as zero.
+ *
+ * @param {ValidatedNode} node
+ * @param {number} index
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function writeFileLineBudgetWarnings(node, index, cwd) {
+  const warnings = [];
+  for (const path of node.taskPacket.writeFiles ?? []) {
+    let text;
+    try {
+      text = readFileSync(resolve(cwd, path), "utf8");
+    } catch {
+      continue;
+    }
+    const lines = text.split("\n").length;
+    const remaining = WRITE_FILE_LINE_CEILING - lines;
+    if (remaining > WRITE_FILE_LINE_WARN_MARGIN) continue;
+    warnings.push(
+      `nodes[${index}] (${node.id}): writeFiles ${path} is already ${lines} lines, ${remaining} from the ${WRITE_FILE_LINE_CEILING}-line ceiling; confirm this node's write has room before it starts`,
+    );
+  }
+  return warnings;
+}
+
 /**
  * @param {string} root
  * @param {string} cwd

package/src/engine/cancel.mjs

@@ -17,6 +17,7 @@ import { terminateInvocation } from "./process.mjs";
 import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { readRunNodes } from "./scheduler.mjs";
+import { deleteRef, releaseAttemptWorktree, runRefName } from "../repo/worktree.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
 import { transition, writeNode } from "./state.mjs";
 import { validateContract } from "../contract/index.mjs";
@@ -107,6 +108,18 @@ export async function cancelRun(runDirPath) {
       throw error;
     }
     if (!await waitForTerminal(runDir, 1_000)) throw new Error("cancel could not confirm a terminal run state");
+    // The run directory is evidence a campaign ledger may still want, so it
+    // stays; the run ref and every node's attempt branch are just git names
+    // the next launch of this same contract id needs back, and cancel is the
+    // operator saying this run is over. Releasing a name is not destroying a
+    // record -- each state's `worktree.branch`/`commit` fields, and the sha
+    // this ref pointed at, remain in the persisted snapshot regardless.
+    // Idempotent both ways: `removeWorktree` and `deleteRef` already tolerate
+    // an artefact a previous cancel (or the run itself) already released.
+    for (const state of states) {
+      if (state.worktree?.branch) releaseAttemptWorktree(contract.cwd, state.worktree.path, state.worktree.branch);
+    }
+    deleteRef(contract.cwd, runRefName(contract.id));
     syncAgentSignal(join(runDir, ".."));
     return true;
   } finally {

package/src/engine/dispatch.mjs

@@ -21,8 +21,8 @@ import {
   readWorkerResultFile,
   workerProtocolPrompt,
 } from "./result-file.mjs";
-import { attemptWorkspace } from "../repo/worktree.mjs";
-import { attemptWorktreePath, createAttemptWorktree, sealAttempt } from "../repo/worktree.mjs";
+import { attemptWorkspace, createAttemptWorktree, sealAttempt } from "../repo/worktree.mjs";
+import { attemptWorktreePath } from "../run/paths.mjs";
 import { basename, dirname, join } from "node:path";
 import { boundedUtf8, errorCode, errorMessage, stableJson } from "../util.mjs";
 import { captureWorkspaceScope, captureWorkspaceSnapshot } from "../repo/workspace.mjs";
@@ -387,6 +387,7 @@ function ensureAttemptWorkspace(contract, node, state, runDir, lock) {
     runId: contract.id,
     nodeId: node.id,
     attempt: state.attempt,
+    declaredReads: node.taskPacket.readFiles,
     base: previous?.sha,
   });
   const boundary = captureWorkspaceScope(worktree.path, workerScope(node.taskPacket));

package/src/engine/lifecycle.mjs

@@ -521,7 +521,13 @@ export async function finalizeClosedJobs(contract, runDir, states, running, lock
         await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(error), states, campaignPath);
         continue;
       }
-      if (job.node.taskPacket.mode === "discovery" && workerResult.status === "done") {
+      // The artifact demand follows the documented discovery contract, not the
+      // mode alone: only a packet with no read files -- the one exception to
+      // closed scope, allowed to read the repository to produce an execution
+      // packet -- owes that artifact. A discovery packet closed to its listed
+      // read files delivers through `output` (a planning node's plan or
+      // findings) and carries none.
+      if (job.node.taskPacket.mode === "discovery" && job.node.taskPacket.readFiles.length === 0 && workerResult.status === "done") {
         try {
           parseDiscoveryResult(workerResult, attemptWorkspace(state) ?? contract.cwd);
         } catch (error) {

package/src/engine/live-preflight.mjs

@@ -24,6 +24,7 @@ import { tmpdir } from "node:os";
 import { validateContract } from "../contract/index.mjs";
 import { validateNodeSnapshot } from "../contract/snapshot.mjs";
 import { compactCost as formatCost } from "../util.mjs";
+import { runsRoot } from "../run/paths.mjs";
 
 /** @typedef {import("../harnesses/index.mjs").ProbeResult} ProbeResult */
 /** @typedef {import("../harnesses/index.mjs").ProviderEnvelope} ProviderEnvelope */
@@ -263,7 +264,7 @@ function redactProviderText(value) {
 export function reusedDoneWarnings(contract) {
   /** @type {string[]} */
   const warnings = [];
-  const runsDir = join(contract.cwd, ".runs");
+  const runsDir = runsRoot(contract.cwd);
   if (!existsSync(runsDir)) return warnings;
   const ownRunDir = join(runsDir, contract.id);
   for (const name of readdirSync(runsDir)) {

package/src/engine/notify-queue.mjs

@@ -222,6 +222,12 @@ export function attentionDedupeKey(runId, anchor, slot) {
  * already announced. A receipt is the durable record, so a restarted
  * supervisor reads the same slot as already sent.
  *
+ * The message is rendered exactly once, with `runDir` set, and that one
+ * string is handed to both the inbox entry and the notify queue: `enqueue`
+ * never re-renders a `summary` it is given. Rendering it twice -- once for
+ * the inbox with no `runDir` and once inside `enqueue` with `runDir` filled
+ * in -- is what let the inbox and the transport disagree before.
+ *
  * @param {string} runDir
  * @param {{anchor: string, code?: string|null, campaignId?: string|null, now?: number}} options
  * @returns {Promise<number|null>} the emitted slot, or null when none was due
@@ -234,10 +240,11 @@ export async function emitScheduledAttention(runDir, options) {
   const runId = basename(runDir);
   const dedupeKey = attentionDedupeKey(runId, options.anchor, slot);
   if (alreadyNotified(runDir, dedupeKey)) return null;
-  const summary = renderNotification({
+  const summary = await renderNotification({
     type: "attention",
     runId,
     errorCode: options.code ?? null,
+    runDir,
   });
   // The run-level attention also lands in the campaign-level inbox, which is
   // the append-only record the managed signal block summarises.
@@ -255,6 +262,7 @@ export async function emitScheduledAttention(runDir, options) {
     runId,
     errorCode: options.code ?? null,
     dedupeKey,
+    summary,
   });
   return slot;
 }