faberun 0.11.0 → 0.12.0

package/README.md

@@ -178,6 +178,12 @@ The installer resolves the newest release, checks the requirements and runs
 curl -fsSL https://raw.githubusercontent.com/feliperun/faberun/main/install.sh | sh
 ```
 
+On Windows, in PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/feliperun/faberun/main/install.ps1 | iex
+```
+
 `faberun setup` runs at the end of the installer and registers the `faberun`
 skill for the harnesses it finds (Claude Code, Codex and the shared
 `~/.agents/skills`, plus any measured convention); `faberun skills register`

package/integrations/claude-code/statusline.sh

@@ -1,13 +1,17 @@
 #!/bin/sh
 # Claude Code statusLine renderer for faberun ambient liveness. Reads
-# the session JSON on stdin, reads that repo's .runs/status.json pointer
-# (rewritten every controller tick), and prints one line:
+# the session JSON on stdin, resolves that repo's runs pointer (rewritten
+# every controller tick), and prints one line:
 #   <run-id> · <state> · <node> <elapsed> · $<usd> · needs you: <n>
 # elapsedSec, costUsd and needsYou are precomputed by the controller, so this
 # never touches a clock or a node process, only formats. No pointer, an
 # unreadable file, or one over the 1 KiB cap prints an empty line, exit 0.
 # jq is used when present; otherwise sed/grep pull the flat top-level fields.
 #
+# This file is a hand-maintained seam: the repository's source-shape guard
+# walks .mjs files only, so no test fails when this script and the resolver
+# drift -- test/integrations/statusline.test.mjs is the only pin here.
+#
 # Allowance guard. The same session JSON carries rate_limits.five_hour
 # (used_percentage plus a reset instant); the script otherwise reads stdin only
 # for cwd. At ALLOWANCE_WARN_PCT or above, the line appends the warning and the
@@ -27,7 +31,32 @@ ALLOWANCE_WARN_PCT=85
 
 session=$(cat)
 repo=$(printf '%s' "$session" | sed -n 's/.*"cwd":"\([^"]*\)".*/\1/p;s/.*"current_dir":"\([^"]*\)".*/\1/p' | head -n 1)
+# The pointer follows the state (R2): the project registry under the faberun
+# home maps the repository's resolved path to an opaque id, and the pointer
+# sits in that project's runs directory. A repository whose runs never moved
+# still answers in-tree -- R7 keeps the reading side dual-layout until
+# `faberun migrate` runs -- so the legacy path stays the fallback, and the
+# home side wins when both exist, exactly like the resolver. Two fixed paths:
+# no glob, no newest-by-mtime. That is the half of R6 already true and to
+# keep; the one machine-wide pointer is a later phase, not this lookup.
+home=${FABERUN_HOME:-$HOME/.faberun}
+index="$home/projects/index.json"
+id=
+if [ -n "$repo" ] && [ -f "$index" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    id=$(jq -r --arg p "$repo" '.[$p] // empty' "$index" 2>/dev/null) || id=
+  else
+    # The index is pretty-printed, one `"path": "id"` pair per line, so a
+    # fixed-string grep for the quoted key picks exactly that one line and
+    # the id follows its colon. Fixed-string on purpose: a repo path is
+    # data, not a regex.
+    id=$(grep -F "\"$repo\"" "$index" 2>/dev/null | sed -n 's/^.*:[[:space:]]*"\([^"]*\)".*/\1/p')
+  fi
+fi
 pointer="$repo/.runs/status.json"
+if [ -n "$id" ] && [ -d "$home/projects/$id/runs" ]; then
+  pointer="$home/projects/$id/runs/status.json"
+fi
 
 # The nested five_hour.used_percentage. jq when present; otherwise flatten the
 # session JSON and pull the field out of the five_hour object with sed. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "for f in bin/*.mjs .claude/hooks/*.mjs src/*.mjs src/*/*.mjs src/*/*/*.mjs evals/*.mjs test/*.mjs test/*/*.mjs; do node --check \"$f\" || exit 1; done",
+    "check": "node -e \"const{readdirSync}=require('node:fs');const{spawnSync}=require('node:child_process');const roots=['bin','.claude/hooks','src','evals','test'];const files=roots.flatMap(r=>readdirSync(r,{recursive:true}).map(String).filter(p=>p.endsWith('.mjs')).map(p=>r+'/'+p));for(const f of files)if(spawnSync(process.execPath,['--check',f],{stdio:'inherit'}).status!==0)process.exit(1);console.log(files.length+' files checked')\"",
     "typecheck": "tsc",
     "test": "node --test test/*.test.mjs test/*/*.test.mjs",
     "docs": "node src/cli/manual.mjs --write",

package/skills/faberun/references/spec-format.md

@@ -71,6 +71,15 @@ comparative arm, a follow-up spec). `statement` is the testable claim.
 A requirement may add its own `- **constraints:** ...` line for a rule
 scoped to it alone, distinct from the spec-wide Constraints section.
 
+A requirement may also declare a measurement with
+`- **measure:** command: <shell command>` — a read-only check the planner
+runs against the repository *before* drafting anything, folded into the repo
+facts the draft stage reads. The distinction from `proof` is timing: `proof`
+is what the finished node satisfies, while `measure` is checkable before any
+node exists — a grep, a `wc -l`, a small pipeline, run through the shell
+exactly as written here, pipes included. Only the `command` kind is wired;
+`path` and `judgment` measures parse but run nothing.
+
 ## What `faberun spec validate` checks
 
 Deterministic, no model call. Rejects:

package/src/campaign/chain.mjs

@@ -41,6 +41,7 @@ import { HEARTBEAT_INTERVAL_MS, createHeartbeat, groupAlive, heartbeatBreach, re
 import { pidAlive, processStartToken } from "../run/lock.mjs";
 import { delay, errorCode, errorMessage } from "../util.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
+import { runDirectory } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").ControllerIdentity} ControllerIdentity */
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -333,7 +334,7 @@ function runIdentityFor(contractPath) {
   const raw = /** @type {Record<string, unknown>} */ (JSON.parse(readFileSync(contractPath, "utf8")));
   const cwd = resolve(dirname(contractPath), typeof raw.cwd === "string" ? raw.cwd : ".");
   const id = String(raw.id);
-  return { id, cwd, runDir: join(cwd, ".runs", id) };
+  return { id, cwd, runDir: runDirectory(cwd, id) };
 }
 
 /**

package/src/campaign/index.mjs

@@ -8,6 +8,7 @@ import {
 import { createHash, randomUUID } from "node:crypto";
 import { join, resolve } from "node:path";
 import { writeJsonAtomic } from "../run/store.mjs";
+import { projectIdForRunsDir, repositoryForRunsDir } from "../run/paths.mjs";
 import { requireId, requirePacketHash, requireString, requireTimestamp } from "../contract/assert.mjs";
 import { promoteRun } from "../repo/integrate.mjs";
 import { CAMPAIGN_FILE, GOAL_TEXT_BYTES, JOURNAL_FILE, PROJECTION_FILE, campaignDir, campaignsDir } from "./layout.mjs";
@@ -132,7 +133,7 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   if (!readJournalForDedupe(campaignPath).some((entry) => entry.type === "retrospective")) {
     throw new Error(`campaign ${campaign.id} has no recorded retrospective; record one with note --kind retrospective before close`);
   }
-  const repoRoot = resolve(campaignPath, "..", "..", "..");
+  const repoRoot = campaignRepoRoot(campaignPath);
   const ledgerFiles = preserveCampaignLedger(campaignPath, repoRoot);
   const closed = /** @type {Campaign} */ ({ ...campaign, status: "closed", closedAt: at, updatedAt: at });
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), closed);
@@ -140,6 +141,28 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   return { path: campaignPath, campaign: closed, ledgerFiles };
 }
 
+/**
+ * The repository a campaign's ledger is preserved into. Under the home layout
+ * the campaign path carries the project id at the resolver's fixed position,
+ * so the repository is looked up live in the registry rather than derived by
+ * climbing: a project reassociated after the campaign was created preserves
+ * at its current repository, which a path cached anywhere would not. A
+ * campaign under a legacy `<repo>/.runs` keeps the old three-directory climb,
+ * which is exact there because the campaign path ends `<repo>/.runs/campaigns/<id>`.
+ *
+ * @param {string} campaignPath
+ * @returns {string}
+ */
+function campaignRepoRoot(campaignPath) {
+  const runsDir = resolve(campaignPath, "..", "..");
+  const repository = repositoryForRunsDir(runsDir);
+  if (repository) return repository;
+  if (projectIdForRunsDir(runsDir)) {
+    throw new Error(`no project record for ${campaignPath}; the registry cannot name the repository its ledger belongs to`);
+  }
+  return resolve(campaignPath, "..", "..", "..");
+}
+
 /**
  * Copy a campaign's journal, record and each linked run's usage into
  * `<repoRoot>/docs/campaigns/<id>/ledger/` so the comparative arm of the
@@ -237,6 +260,84 @@ export function assertContractManifestIntact(entry) {
   }
 }
 
+/**
+ * Append a contract to an active campaign's manifest, digesting its authored
+ * bytes exactly as `campaign init --contract` does. This is what an operator
+ * used to do by hand-editing `campaign.json` and recomputing
+ * `authoredContractDigest` themselves -- a step that parks the campaign for
+ * good on a typo, since `assertContractManifestIntact` refuses a digest that
+ * does not match at launch.
+ *
+ * Idempotent by path and bytes: adding the same contract path a second time,
+ * with the file unchanged since, finds its digest already recorded and
+ * returns the campaign untouched. A second call after the file changed
+ * updates the recorded digest in place rather than duplicating the entry.
+ *
+ * @param {string} campaignPath
+ * @param {string} contractPath
+ * @param {{at?: string}} [options]
+ * @returns {{campaign: Campaign, added: boolean}}
+ */
+export function addContractToCampaign(campaignPath, contractPath, { at = new Date().toISOString() } = {}) {
+  requireTimestamp(at, "at");
+  requireString(contractPath, "contractPath");
+  if (!existsSync(contractPath)) throw new Error(`contract not found: ${contractPath}`);
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status === "closed") throw new Error(`campaign is closed: ${campaign.id}`);
+  const digest = authoredContractDigest(contractPath);
+  const existingIndex = campaign.contracts.findIndex((entry) => entry.path === contractPath);
+  if (existingIndex !== -1 && campaign.contracts[existingIndex].digest === digest) {
+    return { campaign, added: false };
+  }
+  const entry = { path: contractPath, digest };
+  const contracts = existingIndex === -1
+    ? [...campaign.contracts, entry]
+    : campaign.contracts.map((existing, index) => (index === existingIndex ? entry : existing));
+  const updated = /** @type {Campaign} */ ({ ...campaign, contracts, updatedAt: at });
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), updated);
+  return { campaign: updated, added: true };
+}
+
+/**
+ * Replace a manifest entry -- matched by its current, recorded path -- with a
+ * freshly authored contract. Re-authoring a phase after a blocked or failed
+ * node is the normal case in this repository, not the exception, so this is
+ * the command form of the hand edit an operator otherwise repeats every time.
+ *
+ * When the campaign's `attention` names the contract being replaced (its
+ * `contractPath` matches `oldPath`), the attention is cleared in the same
+ * write, so a stale park cannot go on refusing `campaign supervise` once the
+ * contract it named is gone. This does not go through `unparkCampaign`
+ * (`./unpark.mjs`, which owns the `campaign.unparked` journal event): that
+ * module already imports `chain.mjs`, which imports this one, and importing
+ * it back here would close that cycle.
+ *
+ * @param {string} campaignPath
+ * @param {string} oldPath
+ * @param {string} newPath
+ * @param {{at?: string}} [options]
+ * @returns {{campaign: Campaign, replaced: CampaignContract, clearedAttention: CampaignAttention|null}}
+ */
+export function replaceContractInCampaign(campaignPath, oldPath, newPath, { at = new Date().toISOString() } = {}) {
+  requireTimestamp(at, "at");
+  requireString(oldPath, "oldPath");
+  requireString(newPath, "newPath");
+  if (!existsSync(newPath)) throw new Error(`contract not found: ${newPath}`);
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status === "closed") throw new Error(`campaign is closed: ${campaign.id}`);
+  const index = campaign.contracts.findIndex((entry) => entry.path === oldPath);
+  if (index === -1) throw new Error(`no contract at ${oldPath} in campaign ${campaign.id}`);
+  const replaced = { path: newPath, digest: authoredContractDigest(newPath) };
+  const contracts = campaign.contracts.map((entry, position) => (position === index ? replaced : entry));
+  const attention = campaign.attention;
+  const clearAttention = attention !== undefined && attention.contractPath === oldPath;
+  /** @type {Campaign} */
+  const updated = { ...campaign, contracts, updatedAt: at };
+  if (clearAttention) delete updated.attention;
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), updated);
+  return { campaign: updated, replaced, clearedAttention: clearAttention ? /** @type {CampaignAttention} */ (attention) : null };
+}
+
 /**
  * Persist one promotion in the campaign record. Idempotent by run id and the
  * sha it landed: a re-invocation after a crash between the branch move and

package/src/campaign/metrics.mjs

@@ -37,6 +37,7 @@ import { renderMetricsJson, renderMetricsReport } from "../report/metrics-report
 import { campaignDir } from "./layout.mjs";
 import { readCampaign } from "./record.mjs";
 import { listNodeSnapshots, nodeSnapshotPath } from "../run/node-store.mjs";
+import { runsRoot } from "../run/paths.mjs";
 
 /** Node statuses that are not terminal: everything else settles a logical node. */
 const OPEN_STATUSES = new Set(["pending", "running"]);
@@ -401,7 +402,6 @@ function orderOf(entry) {
 /** @type {import("node:util").ParseArgsOptionsConfig} */
 export const METRICS_OPTIONS = { cwd: { type: "string" }, json: { type: "boolean" } };
 
-const RUNS_DIR_NAME = ".runs";
 const RUN_EVENTS_FILE = "events.jsonl";
 const USAGE_LOG_FILE = "usage.jsonl";
 const NOTIFY_LOG_FILE = "notify.jsonl";
@@ -488,7 +488,7 @@ function readRunNodes(runDir) {
  * @returns {string}
  */
 export function renderCampaignMetrics(campaignId, values = {}) {
-  const runsDir = join(resolve(typeof values.cwd === "string" && values.cwd !== "" ? values.cwd : process.cwd()), RUNS_DIR_NAME);
+  const runsDir = runsRoot(resolve(typeof values.cwd === "string" && values.cwd !== "" ? values.cwd : process.cwd()));
   const sources = readMetricsSources(campaignDir(runsDir, campaignId), { runsDir });
   const metrics = projectMetrics(sources);
   return values.json === true ? renderMetricsJson(sources, metrics) : renderMetricsReport(sources, metrics);

package/src/cli/brand.mjs

@@ -191,6 +191,8 @@ export function renderUsage() {
     "setup [--yes] [--no-skill] [--harnesses <a,b>] [--worker <id>] [--judge <id>] [--json]",
     "init [--cwd <dir>] [--yes] [--no-skill] [--agentkit] [--greenfield|--stable] [--json]",
     "update [--check] [--json]",
+    "project <new-path> [--from <old-path>]",
+    "migrate [--cwd <dir>]",
     "models [--probe] [--json]",
     "next [--cwd <dir>] [--json]",
     "bulk-read --question <text> --paths <a,b,c> [--json]",

package/src/cli/campaign-contract.mjs

@@ -0,0 +1,55 @@
+/**
+ * `campaign add-contract` and `campaign replace-contract`: give an active
+ * campaign's contract manifest a command, instead of the hand edit of
+ * `campaign.json` an operator otherwise repeats every time a phase is
+ * re-authored. `campaign.mjs` dispatches into this module; its
+ * `OPERATION_OPTIONS` entries live there so the command surface stays one
+ * table (`cli/campaign.mjs`'s own header explains why).
+ */
+import { resolve } from "node:path";
+import { addContractToCampaign, renderHandoff, replaceContractInCampaign, resolveCampaign } from "../campaign/index.mjs";
+import { runsRoot } from "../run/paths.mjs";
+
+/** @typedef {{cwd?: string, path?: string, replace?: string, eventId?: string}} CampaignContractValues */
+
+/**
+ * @param {string} campaignId
+ * @param {CampaignContractValues} values
+ */
+export function addContract(campaignId, values) {
+  const cwd = resolve(values.cwd ?? ".");
+  const runsDir = runsRoot(cwd);
+  const { path } = resolveCampaign(runsDir, campaignId);
+  const contractPath = requiredPath(values.path, "--path");
+  const { campaign, added } = addContractToCampaign(path, contractPath);
+  renderHandoff(path, runsDir);
+  process.stdout.write(added
+    ? `[campaign] contract added · ${contractPath} · ${campaign.contracts.length} contract(s)\n`
+    : `[campaign] contract already recorded · ${contractPath}\n`);
+}
+
+/**
+ * @param {string} campaignId
+ * @param {CampaignContractValues} values
+ */
+export function replaceContract(campaignId, values) {
+  const cwd = resolve(values.cwd ?? ".");
+  const runsDir = runsRoot(cwd);
+  const { path } = resolveCampaign(runsDir, campaignId);
+  const contractPath = requiredPath(values.path, "--path");
+  const oldPath = requiredPath(values.replace, "--replace");
+  const { clearedAttention } = replaceContractInCampaign(path, oldPath, contractPath);
+  renderHandoff(path, runsDir);
+  process.stdout.write(`[campaign] contract replaced · ${oldPath} -> ${contractPath}\n`);
+  if (clearedAttention) process.stdout.write(`[campaign] attention cleared · ${clearedAttention.code}\n`);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {string}
+ */
+function requiredPath(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${label} requires a value`);
+  return resolve(value);
+}

package/src/cli/campaign.mjs

@@ -10,7 +10,9 @@ import {
   renderHandoff,
   resolveCampaign,
 } from "../campaign/index.mjs";
+import { addContract, replaceContract } from "./campaign-contract.mjs";
 import { lockStale, pidAlive, processStartToken, readLock } from "../run/lock.mjs";
+import { runsRoot } from "../run/paths.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
 import { acknowledgeJournalEvent, appendJournal, appendSeatAllowanceEvent, readJournal, watchJournal } from "../campaign/journal.mjs";
 import { driveCampaignChain } from "../campaign/chain.mjs";
@@ -85,12 +87,14 @@ const OPERATION_OPTIONS = {
   close: { cwd: { type: "string" }, "event-id": { type: "string" } },
   supervise: { cwd: { type: "string" }, "allow-main": { type: "boolean" } },
   unpark: { cwd: { type: "string" }, force: { type: "boolean" }, "event-id": { type: "string" } },
+  "add-contract": { cwd: { type: "string" }, path: { type: "string" } },
+  "replace-contract": { cwd: { type: "string" }, path: { type: "string" }, replace: { type: "string" } },
   show: { cwd: { type: "string" } },
   sync: { cwd: { type: "string" }, "session-id": { type: "string" } },
   ack: { cwd: { type: "string" }, "session-id": { type: "string" }, "event-id": { type: "string" } },
 };
 
-/** @typedef {{cwd?: string, goal?: string, contract?: string[], landBranch?: string, tool?: string, sessionId?: string, transcript?: string, format?: string, cursor?: string, since?: string, kind?: string, text?: string, runId?: string, supersedes?: string, decisionId?: string, questionId?: string, eventId?: string, noTranscript?: boolean, wake?: boolean, detach?: boolean, interval?: string, once?: boolean, allowMain?: boolean, force?: boolean}} CliValues */
+/** @typedef {{cwd?: string, goal?: string, contract?: string[], landBranch?: string, tool?: string, sessionId?: string, transcript?: string, format?: string, cursor?: string, since?: string, kind?: string, text?: string, runId?: string, supersedes?: string, decisionId?: string, questionId?: string, eventId?: string, noTranscript?: boolean, wake?: boolean, detach?: boolean, interval?: string, once?: boolean, allowMain?: boolean, force?: boolean, path?: string, replace?: string}} CliValues */
 /** @typedef {import("../campaign/index.mjs").Campaign} Campaign */
 
 /**
@@ -118,6 +122,8 @@ export async function campaignCli(args) {
   if (operation === "show") return show(campaignId, values);
   if (operation === "sync") return sync(campaignId, values);
   if (operation === "ack") return ack(campaignId, values);
+  if (operation === "add-contract") return addContract(campaignId, values);
+  if (operation === "replace-contract") return replaceContract(campaignId, values);
   return usage();
 }
 
@@ -330,7 +336,7 @@ function watchLockStale(occupant) {
  */
 async function init(campaignId, values) {
   const cwd = resolve(values.cwd ?? ".");
-  const runsDir = join(cwd, ".runs");
+  const runsDir = runsRoot(cwd);
   const goal = textValue(values.goal, "--goal");
   const contracts = contractManifest(values.contract);
   const created = initializeCampaign(runsDir, { campaignId, goal, contracts, landBranch: values.landBranch });
@@ -476,7 +482,7 @@ function close(campaignId, values) {
  */
 async function supervise(campaignId, values) {
   const cwd = resolve(values.cwd ?? ".");
-  const runsDir = join(cwd, ".runs");
+  const runsDir = runsRoot(cwd);
   const { path } = resolveCampaign(runsDir, campaignId);
   const outcome = await driveCampaignChain(path, {
     repo: cwd,
@@ -502,13 +508,42 @@ async function supervise(campaignId, values) {
  * @param {CliValues} values
  */
 function unpark(campaignId, values) {
-  const { path, runsDir } = selectCampaign(campaignId, values);
-  const result = unparkCampaign(path, {
-    runsDir,
-    force: values.force === true,
-    eventId: values.eventId ?? randomUUID(),
-  });
-  process.stdout.write(`[campaign] ${result.campaign.id} unparked · ${result.cleared.code} cleared\n`);
+  const { path, runsDir, campaign } = selectCampaign(campaignId, values);
+  try {
+    const result = unparkCampaign(path, {
+      runsDir,
+      force: values.force === true,
+      eventId: values.eventId ?? randomUUID(),
+    });
+    process.stdout.write(`[campaign] ${result.campaign.id} unparked · ${result.cleared.code} cleared\n`);
+  } catch (error) {
+    throw explainStillParked(error, campaign.attention);
+  }
+}
+
+/**
+ * `unparkCampaign`'s still-parked refusal names the run and its state but not
+ * the node holding the park, and tells the operator to pass `--force` without
+ * saying what that flag will and will not do -- an operator told only the
+ * flag types the flag. The campaign's own `attention` record already carries
+ * the node, its status, and the resume command the chain wrote when it
+ * parked (see `chain.mjs`'s `park`), so recompose the message from that
+ * instead of changing what the still-parked check itself reports. Any other
+ * refusal (closed campaign, not parked) is passed through unchanged.
+ *
+ * @param {unknown} error
+ * @param {Campaign["attention"]} attention
+ * @returns {unknown}
+ */
+function explainStillParked(error, attention) {
+  if (!(error instanceof Error) || !attention) return error;
+  const match = /^run (\S+) is still (parked|canceled); resume it first or pass --force$/u.exec(error.message);
+  if (!match) return error;
+  const [, runId, state] = match;
+  const node = attention.node ? ` node ${attention.node}${attention.status ? ` (${attention.status})` : ""}` : "";
+  return new Error(
+    `run ${runId}${node} is still ${state}. --force clears only the campaign's parked attention so \`supervise campaign\` can drive the chain again; it does not resume, cancel, or otherwise change run ${runId}, which stays ${state} until you act on it directly. Resume the run, or pass --force to move on without resuming it.`,
+  );
 }
 
 /**
@@ -634,7 +669,7 @@ function sessionCursorId(sessionId) {
  */
 function listCampaigns(values) {
   const cwd = resolve(values.cwd ?? ".");
-  const runsDir = join(cwd, ".runs");
+  const runsDir = runsRoot(cwd);
   const { campaigns, corrupt } = discoverCampaigns(runsDir);
   if (!campaigns.length && !corrupt.length) {
     process.stdout.write("[campaign] none\n");
@@ -658,7 +693,7 @@ function listCampaigns(values) {
  */
 function selectCampaign(campaignId, values) {
   const cwd = resolve(values.cwd ?? ".");
-  const runsDir = join(cwd, ".runs");
+  const runsDir = runsRoot(cwd);
   return { ...resolveCampaign(runsDir, campaignId), runsDir };
 }
 
@@ -738,7 +773,7 @@ function positiveIntervalMs(value) {
 
 function usage() {
   process.stderr.write(
-    "usage: faberun campaign <init|watch|attach|note|resolve|close|supervise|unpark|show|list|sync|ack> <campaign-id> [--cwd <dir>] ...\n",
+    "usage: faberun campaign <init|watch|attach|note|resolve|close|supervise|unpark|show|list|sync|ack|add-contract|replace-contract> <campaign-id> [--cwd <dir>] ...\n",
   );
   process.exitCode = 2;
 }

package/src/cli/init.mjs

@@ -19,6 +19,7 @@ import { fileURLToPath } from "node:url";
 import { colorLevel, statusToken } from "./brand.mjs";
 import { installSkills } from "./skills.mjs";
 import { boundedGitSync } from "../repo/worktree.mjs";
+import { RUNS_DIR_NAME } from "../run/paths.mjs";
 
 /** @typedef {(text: string) => void} Writer */
 /** @typedef {(question: string) => Promise<string>} Asker */
@@ -152,6 +153,11 @@ function isGitWorkTree(cwd) {
  * exists, creating the file when missing. A file that does not end in a newline
  * gets one before the appended line, so the result is always a whole line.
  *
+ * Run state itself lives under the faberun home now, but this line is not
+ * obsolete: every attempt worktree is still a git working tree, and R3 keeps
+ * the worker's result sidecar inside it, under `.runs/`, where the scope diff
+ * must not see it. Do not remove this as cleanup.
+ *
  * @param {string} cwd
  * @returns {string} the `.gitignore` path written or confirmed
  */
@@ -160,11 +166,11 @@ function ensureRunsIgnored(cwd) {
   const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
   const ignored = existing.split(/\r?\n/u).some((line) => {
     const trimmed = line.trim();
-    return trimmed === ".runs/" || trimmed === ".runs";
+    return trimmed === `${RUNS_DIR_NAME}/` || trimmed === RUNS_DIR_NAME;
   });
   if (!ignored) {
     const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-    writeFileSync(path, `${existing}${separator}.runs/\n`);
+    writeFileSync(path, `${existing}${separator}${RUNS_DIR_NAME}/\n`);
   }
   return path;
 }

package/src/cli/launch.mjs

@@ -23,6 +23,7 @@ import { randomUUID } from "node:crypto";
 import { readRunNodes } from "../engine/scheduler.mjs";
 import { spawn } from "node:child_process";
 import { validateContract } from "../contract/index.mjs";
+import { runDirectory } from "../run/paths.mjs";
 
 /**
  * The file a detached child is spawned as. It must be the CLI and not this
@@ -182,7 +183,7 @@ export function bootstrapRunDir(command, target) {
       if (!target) return null;
       const path = resolve(target);
       const contract = validateContract(JSON.parse(readFileSync(path, "utf8")), path);
-      return join(contract.cwd, ".runs", contract.id);
+      return runDirectory(contract.cwd, contract.id);
     }
     if (["resume", "cancel"].includes(command)) {
       if (!target) return null;

package/src/cli/plan.mjs

@@ -5,7 +5,7 @@
  * sequencing and every decision the pipeline makes.
  */
 import { readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
 import { classifyRunProgress } from "../campaign/chain.mjs";
 import { runProgress } from "../engine/supervise.mjs";
@@ -13,6 +13,7 @@ import { DISCOVERY_RUNTIME_DEFINITIONS } from "../engine/runtime-discovery.mjs";
 import { validateRuntime } from "../contract/runtime.mjs";
 import { delay } from "../util.mjs";
 import { runPlanningPipeline } from "../plan/pipeline.mjs";
+import { runDirectory } from "../run/paths.mjs";
 
 /** How often a foreground `plan` polls a launched stage's run directory. */
 const DEFAULT_POLL_MS = 1_000;
@@ -117,7 +118,7 @@ export async function planCli(target, values) {
     launch: async (contractPath, contract) => {
       const child = detachSelf("run", contractPath);
       if (child.pid === undefined) throw new Error("detached planning run has no pid");
-      await waitForBootstrap(join(contract.cwd, ".runs", contract.id), child.pid, child);
+      await waitForBootstrap(runDirectory(contract.cwd, contract.id), child.pid, child);
     },
     wait: async (runDir) => {
       for (;;) {