faberun 0.10.0 → 0.12.0

package/src/host/projects.mjs

@@ -0,0 +1,155 @@
+/**
+ * The project registry under `$FABERUN_HOME/projects/`.
+ *
+ * A project is keyed by the repository path, not by anything derived from it:
+ * `projects/index.json` maps a path to an opaque id, and `projects/<id>/project.json`
+ * is the record. The split matters because a project must be able to move —
+ * a later command re-associates a project whose path changed — and everything
+ * that will hang off a project id (campaigns, in a later phase) must survive
+ * that move untouched. Keying storage by path instead would mean a rename or
+ * a clone-to-a-new-directory orphans every one of them; keying storage by id
+ * and the *lookup* by path means a move rewrites one index entry while the
+ * project directory, and everything under it, stays put.
+ *
+ * The id is `randomUUID()`: opaque, and unrelated to the path it was minted
+ * for, which is the one property this registry actually needs from it.
+ *
+ * Both files are written with the same temp-then-rename discipline as
+ * `run/store.mjs`'s `writeJsonAtomic`, so a second faberun process reading
+ * either file — the operator routinely runs more than one at a time — never
+ * observes a half-written record. This does not arbitrate two processes
+ * writing at once: a race between two *new* registrations landing in the same
+ * tick can drop one index entry, and that is accepted here because the loser
+ * simply registers again the next time its path is looked up.
+ */
+import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readJson, writeJsonAtomic } from "../run/store.mjs";
+import { errorCode } from "../util.mjs";
+import { projectsDir } from "./home.mjs";
+
+export { projectsDir };
+
+/** @typedef {{schemaVersion: 1, id: string, path: string, remotes: string[], createdAt: string, updatedAt: string}} ProjectRecord */
+
+/**
+ * `path`, realpath-resolved so two different spellings of the same real
+ * directory key the same project — `$TMPDIR` itself is a symlink on macOS
+ * (`/var` -> `/private/var`), which is what actually surfaced this,
+ * measured 2026-09-19. Falls back to a plain `resolve` for a path that does
+ * not exist: `cwd` from a live process always exists, but a path this
+ * registry is asked about — a stale config entry, an operator's typo — need
+ * not, and nothing could already be registered under either spelling of a
+ * path that was never real to begin with, so there is nothing to reconcile.
+ *
+ * Exported because `cli/project.mjs` writes this same index directly (it has
+ * no registry operation that keeps an id while changing its path) and must
+ * key its write identically, or a write it makes becomes one this module's
+ * own lookups can never find again.
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+export function resolveIdentity(path) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return resolve(path);
+    throw error;
+  }
+}
+
+/** @param {string} home @returns {string} */
+function projectIndexPath(home) {
+  return join(projectsDir(home), "index.json");
+}
+
+/** @param {string} home @param {string} id @returns {string} */
+function projectRecordPath(home, id) {
+  return join(projectsDir(home), id, "project.json");
+}
+
+/** @param {string} home @returns {Record<string, string>} the path-to-id map, or `{}` when the registry has never been written */
+function readIndex(home) {
+  try {
+    return /** @type {Record<string, string>} */ (readJson(projectIndexPath(home)));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return {};
+    throw error;
+  }
+}
+
+/**
+ * The project registered at `id`, or null when no such project exists.
+ *
+ * @param {string} home
+ * @param {string} id
+ * @returns {ProjectRecord|null}
+ */
+export function readProject(home, id) {
+  try {
+    return /** @type {ProjectRecord} */ (readJson(projectRecordPath(home, id)));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * The project registered at `path`, or null when that path has never been
+ * registered. `path` is realpath-resolved first, the same normalization
+ * `registerProject` applies, so a caller need not agree in advance on
+ * relative-vs-absolute spelling, and two different spellings of the same
+ * real directory — a symlinked `$TMPDIR` on macOS is the case that actually
+ * surfaced this, measured 2026-09-19 — still answer the same project rather
+ * than silently minting two.
+ *
+ * @param {string} home
+ * @param {string} path
+ * @returns {ProjectRecord|null}
+ */
+export function findProjectByPath(home, path) {
+  const id = readIndex(home)[resolveIdentity(path)];
+  return id ? readProject(home, id) : null;
+}
+
+/**
+ * Register `path` as a project, or update the existing one at that path.
+ *
+ * A path seen for the first time mints a new id and an index entry that
+ * outlives any single call. A path already in the index keeps its id — this
+ * is the "registers once, not twice" half of R4 — and only its record is
+ * refreshed: the remotes are replaced with what the caller passed just now.
+ * A changed remote list is not a new identity, since the project is keyed by
+ * path; it is simply the current fact about a path that can gain, lose or
+ * rename a remote over its lifetime, so each registration overwrites the
+ * list rather than accumulating history the caller no longer observes.
+ *
+ * @param {string} home
+ * @param {string} path
+ * @param {string[]} [remotes]
+ * @returns {ProjectRecord}
+ */
+export function registerProject(home, path, remotes = []) {
+  const resolved = resolveIdentity(path);
+  const index = readIndex(home);
+  let id = index[resolved];
+  if (!id) {
+    id = randomUUID();
+    writeJsonAtomic(projectIndexPath(home), { ...index, [resolved]: id });
+  }
+  const existing = readProject(home, id);
+  const now = new Date().toISOString();
+  /** @type {ProjectRecord} */
+  const record = {
+    schemaVersion: 1,
+    id,
+    path: resolved,
+    remotes: [...remotes],
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+  };
+  writeJsonAtomic(projectRecordPath(home, id), record);
+  return record;
+}

package/src/notify/index.mjs

@@ -1,8 +1,9 @@
 /**
  * Direct notification dispatcher (TECH-SPEC lean, rule 6). On `node.terminal`,
- * `run.terminal` and `attention` the controller renders a one-line message
- * from a fixed per-type template, calls `FABERUN_NOTIFY_BIN` with the
- * event as JSON on stdin, and appends a receipt (`delivered`, `failed` or
+ * `run.terminal` and `attention` the controller renders the message through
+ * `renderRunProgress` (`report/progress.mjs`) from the run's own persisted
+ * state, calls `FABERUN_NOTIFY_BIN` with the event as JSON on stdin, and
+ * appends a receipt (`delivered`, `failed` or
  * `no_transport`, with the timestamp) to `<run-dir>/notify.jsonl`. Delivery is
  * lossy: an event is attempted once, a failure schedules no further attempt and
  * is never requeued, and the controller never waits on a retry it will not
@@ -47,6 +48,25 @@ import { join } from "node:path";
 import { createMacosNotifier } from "./os-macos.mjs";
 import { errorMessage } from "../util.mjs";
 
+/**
+ * `report/progress.mjs` reaches back to this module (through
+ * `run/node-store.mjs` -> `run/disk-gc.mjs` -> `host/preflight.mjs`, which
+ * reads `NOTIFY_BIN_ENV`), so a static top-level import of it here would be a
+ * real cycle: `host/preflight.mjs` would read `NOTIFY_BIN_ENV` while this
+ * module's own top level was still mid-evaluation, before the `const` is
+ * assigned. A dynamic import resolves this module first and defers loading
+ * `report/progress.mjs` until the first call, by which point this module has
+ * already finished initializing -- so the cycle is real but harmless. Cached
+ * after the first call so every subsequent render reuses the same module.
+ * @type {Promise<typeof import("../report/progress.mjs")>|null}
+ */
+let progressModule = null;
+/** @returns {Promise<typeof import("../report/progress.mjs")>} */
+function loadProgressModule() {
+  progressModule ??= import("../report/progress.mjs");
+  return progressModule;
+}
+
 export const NOTIFY_BIN_ENV = "FABERUN_NOTIFY_BIN";
 const MACOS_TRANSPORT = "os-macos";
 export const NOTIFY_LOG_FILE = "notify.jsonl";
@@ -68,6 +88,15 @@ export const MAX_ATTEMPTS = 3;
  */
 export const notificationDeliveryTimeoutMs = 5_000;
 
+/**
+ * The one-line, character-based bound this module used to enforce on every
+ * rendered summary. The primary path (below) now defers to
+ * `PROGRESS_MESSAGE_MAX_BYTES` in `report/progress.mjs`, which bounds the
+ * whole rendered message in bytes rather than characters, because that
+ * message is no longer one line. `SUMMARY_CHARS` survives only to bound the
+ * degraded template `renderNotification` falls back to when a caller has no
+ * `runDir` to render from.
+ */
 const SUMMARY_CHARS = 200;
 
 /**
@@ -103,19 +132,68 @@ export const NOTIFY_NO_TRANSPORT_WARNING = "no human notification transport is c
 /** @typedef {{ok: boolean, error?: string, noTransport?: boolean}} DeliveryResult */
 
 /**
- * Render the fixed one-line message for an event, from counters and
- * identifiers only (node id, run id or directory, state, attempt, error
- * code, done/total, cost), never from model text:
+ * Render the message for an event. For `node.terminal`, `run.terminal` and
+ * `attention` this delegates to `renderRunProgress`, which reads the run's
+ * own persisted state (its contract, its node snapshots, its usage) from
+ * `event.runDir` -- so whatever calls this function once gets exactly the
+ * string every audience of that event sees: the inbox entry's `summary` and
+ * the transport's stdin are never rendered separately and never drift.
+ *
+ * `runDir` is absent, or names a directory with no readable run scaffold
+ * (no `contract.json`, no `run.json`, a node snapshot that fails validation),
+ * on two kinds of paths: a caller with no run directory at all, and a render
+ * that fails against a run that is present but broken. Both fall back to
+ * `degradedNotification` below, a fixed one-line, counters-only template --
+ * still one render, still the same text for every audience, just a coarser
+ * one. A render failure must never propagate: this function backs the lossy
+ * notify queue, and a broken render must not turn into a lost receipt.
+ *
+ * The unknown-type case is checked synchronously (it throws, it never
+ * returns a rejected promise a caller might forget to handle); the known
+ * types resolve asynchronously because loading `report/progress.mjs` is
+ * itself async (see `loadProgressModule`).
+ *
+ * @param {NotifyEvent} event
+ * @returns {Promise<string>}
+ */
+export function renderNotification(event) {
+  switch (event.type) {
+    case "node.terminal":
+    case "run.terminal":
+    case "attention":
+      return renderDelegated(event);
+    default:
+      throw new TypeError(`renderNotification: unknown event type ${String(event.type)}`);
+  }
+}
+
+/**
+ * @param {NotifyEvent} event
+ * @returns {Promise<string>}
+ */
+async function renderDelegated(event) {
+  if (typeof event.runDir !== "string" || !event.runDir) return degradedNotification(event);
+  try {
+    const { renderRunProgress } = await loadProgressModule();
+    return renderRunProgress(event.runDir, event);
+  } catch {
+    return degradedNotification(event);
+  }
+}
+
+/**
+ * The fixed one-line message this module rendered for every event before
+ * `renderRunProgress` existed, from counters and identifiers only (node id,
+ * run id or directory, state, attempt, error code, done/total, cost), never
+ * from model text:
  *   `node <id> failed · run <id> · attempt 2 · verification_failed · resume <run-dir>`
  *   `run <id> done · 3/3 nodes · $4.21`
  *   `node <id> needs you · run <id> · <error code>`
- * `runDir` and `costUsd`, when present on the event, come from the run's own
- * `status.json` (`NotifyQueue.enqueue` reads it) — never from the model.
  *
  * @param {NotifyEvent} event
  * @returns {string}
  */
-export function renderNotification(event) {
+function degradedNotification(event) {
   const runId = event.runId ?? "-";
   switch (event.type) {
     case "node.terminal": {
@@ -366,7 +444,7 @@ export class NotifyQueue {
     // one that reaches the transport and the receipt.
     const summary = typeof enriched.summary === "string" && enriched.summary
       ? enriched.summary
-      : renderNotification(enriched);
+      : await renderNotification(enriched);
     // Consumers deduplicate by eventId (the Ford adapter rejects an event without
     // one), so every delivery carries a stable id derived from the dedupe key.
     const eventId = enriched.eventId

package/src/plan/pipeline.mjs

@@ -16,18 +16,18 @@ import { validateContract } from "../contract/index.mjs";
 import { discoveryOutput } from "../contract/worker-result.mjs";
 import { readWorkerResultFile } from "../engine/result-file.mjs";
 import { classifyRunProgress } from "../campaign/chain.mjs";
-import { campaignDir } from "../campaign/layout.mjs";
 import { appendSeatAllowanceEvent, readJournal } from "../campaign/journal.mjs";
 import { readCampaign } from "../campaign/record.mjs";
 import { campaignCli } from "../cli/campaign.mjs";
 import { appendJsonl, writeJsonAtomic } from "../run/store.mjs";
 import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
-import { validateSpec } from "./spec.mjs";
+import { parseSpec, validateSpec } from "./spec.mjs";
 import { collectRepoFacts } from "./repo-facts.mjs";
 import { RISK_TIERS, buildPlanningContract, validateFindings, validatePlanOutput } from "./template.mjs";
 import { applySizingRules } from "./sizing.mjs";
 import { resolveRuntimes } from "./routing.mjs";
 import { freezePlan } from "./freeze.mjs";
+import { campaignTree, runDirectory } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -48,6 +48,16 @@ import { freezePlan } from "./freeze.mjs";
  */
 export const PLANNER_SESSION_ID = "planner";
 
+/**
+ * Where this pipeline stages the scratch files it must hand a discovery node
+ * through `readFiles`: `<cwd>/<this>/<campaignId>/<phase>/`, gitignored. Kept
+ * out of `RUNS_DIR_NAME` on purpose — a repository with nothing under the
+ * home yet treats a present `.runs` as an unmigrated legacy layout
+ * (`runsRoot` in `src/run/paths.mjs`), and this directory must never trip
+ * that check.
+ */
+const PLAN_SCRATCH_DIR_NAME = ".faberun-plan";
+
 /**
  * No taskKind/riskTier row is opinionated by default: absent an operator
  * `--runtime-defaults` instruction, every sized node routes through plain
@@ -78,7 +88,7 @@ export async function runPlanningPipeline(options) {
   if (typeof wait !== "function") throw new TypeError("runPlanningPipeline requires a wait seam");
   const cwd = resolve(options.cwd ?? ".");
 
-  const campaignPath = campaignDir(join(cwd, ".runs"), campaignId);
+  const campaignPath = campaignTree(cwd, campaignId);
   const campaign = readCampaign(campaignPath);
   if (campaign.status !== "active") throw new Error(`campaign is closed: ${campaignId}`);
 
@@ -90,7 +100,7 @@ export async function runPlanningPipeline(options) {
     throw new Error(`spec ${specPath} fails strict traceability: ${detail}`);
   }
 
-  const plansDir = join(cwd, ".runs", "campaigns", campaignId, "plans", phase);
+  const plansDir = join(campaignTree(cwd, campaignId), "plans", phase);
   mkdirSync(plansDir, { recursive: true });
   const pipelineLog = join(plansDir, "pipeline.jsonl");
   /** @param {string} stage @param {Record<string, unknown>} [extra] */
@@ -98,8 +108,21 @@ export async function runPlanningPipeline(options) {
     type: "plan.stage", at: new Date().toISOString(), campaignId, phase, stage, ...extra,
   });
 
-  const repoFacts = collectRepoFacts(cwd);
-  const repoFactsPath = join(plansDir, "repo-facts.json");
+  // A discovery node's `readFiles` must resolve inside `cwd` (the task packet's
+  // own containment rule), but `plansDir` lives under the home since R2 and no
+  // longer nests inside the repository. Repo facts, the working plan and each
+  // round's findings are relayed to a worker through `readFiles`, so they are
+  // staged here instead, gitignored and disposable — the durable record stays
+  // in `plansDir`.
+  const scratchDir = join(cwd, PLAN_SCRATCH_DIR_NAME, campaignId, phase);
+  mkdirSync(scratchDir, { recursive: true });
+
+  // A requirement's `measure` command runs here, before any node exists, so
+  // the draft stage reads what the planner measured instead of inferring it
+  // from the spec's prose.
+  const parsedSpec = parseSpec(specText);
+  const repoFacts = collectRepoFacts(cwd, { requirements: parsedSpec.requirements });
+  const repoFactsPath = join(scratchDir, "repo-facts.json");
   writeFileSync(repoFactsPath, `${JSON.stringify(repoFacts, null, 2)}\n`);
   const relativeRepoFactsPath = relative(cwd, repoFactsPath);
   logStage("repo-facts", { gitHead: repoFacts.gitHead });
@@ -128,7 +151,7 @@ export async function runPlanningPipeline(options) {
     const validated = validateContract(raw, contractPath);
     writeFileSync(contractPath, `${JSON.stringify(raw, null, 2)}\n`);
     await launch(contractPath, validated);
-    const runDir = join(validated.cwd, ".runs", validated.id);
+    const runDir = runDirectory(validated.cwd, validated.id);
     const progress = await wait(runDir);
     const classification = classifyRunProgress(progress);
     if (classification !== "succeeded") {
@@ -144,7 +167,7 @@ export async function runPlanningPipeline(options) {
   let plan = validatePlanOutput(draft.output.plan);
   logStage("draft", { runId: draft.contract.id, nodeCount: plan.nodes.length });
 
-  const workingPlanPath = join(plansDir, "plan.working.json");
+  const workingPlanPath = join(scratchDir, "plan.working.json");
   writeJsonAtomic(workingPlanPath, plan);
   const relativeWorkingPlanPath = relative(cwd, workingPlanPath);
 
@@ -167,7 +190,7 @@ export async function runPlanningPipeline(options) {
       ]);
       return { status: "contested", plansDir, planPath, findings, round };
     }
-    const findingsPath = join(plansDir, `findings-round-${round}.json`);
+    const findingsPath = join(scratchDir, `findings-round-${round}.json`);
     writeJsonAtomic(findingsPath, findings);
     const revise = await runStage("revise", {
       specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, findingsPath: relative(cwd, findingsPath),

package/src/plan/repo-facts.mjs

@@ -5,24 +5,53 @@
  * A planning stage's draft is authored against exactly this JSON instead of
  * the session reading the repository by hand.
  *
+ * When the caller passes the spec's parsed requirements, every `measure`
+ * command a requirement declares also runs here — read-only, before any node
+ * exists — and its output rides along as `requirementMeasurements`: the draft
+ * reasons from a fact the planner measured, not one it inferred from prose.
+ *
  * Sorting and the absence of any clock in the output itself (only inside an
  * injected measurer's own numbers) is what makes two calls at the same HEAD
  * byte-identical.
  */
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { timeVerificationCommands } from "../host/preflight.mjs";
+import { NOTIFY_BIN_ENV } from "../notify/index.mjs";
 import { boundedGitSync, gitHead } from "../repo/worktree.mjs";
 
+/** @typedef {import("./spec.mjs").SpecRequirement} SpecRequirement */
+/** @typedef {{requirementId: string|null, command: string, output: string, exitCode: number|null, truncated: boolean}} RequirementMeasurement */
 /** @typedef {{argv: string[], measuredMs: number, eligible: boolean}} VerificationCandidate */
 /** @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[]}} RepoFacts */
+/** @typedef {{formatVersion: number, gitHead: string|null, paths: string[], truncated: boolean, scripts: Record<string, string>, verificationCandidates: VerificationCandidate[], testFiles: TestFileEntry[], requirementMeasurements: RequirementMeasurement[]}} RepoFacts */
 /** @typedef {{now?: () => number, run?: typeof import("node:child_process").spawnSync}} MeasureProbes */
 
 const FORMAT_VERSION = 1;
 const DEFAULT_MAX_PATHS = 2000;
 const ELIGIBLE_MS_CEILING = 600_000;
 const CANDIDATE_TIMEOUT_SEC = ELIGIBLE_MS_CEILING / 1_000;
+const MEASURE_TIMEOUT_MS = 30_000;
+const MEASURE_OUTPUT_CAP_BYTES = 4096;
+
+/**
+ * The same named few `timeVerificationCommands` subtracts before spawning a
+ * measurement (SIDE_EFFECT_ENV_KEYS in src/host/preflight.mjs, which is
+ * module-private and could not be edited by the node that added this): a
+ * measure must not notify a human and must not be redirectable at a live,
+ * paid harness binary. A subtraction of a named few, not an allowlist — PATH,
+ * HOME and every ordinary variable still pass through unchanged.
+ */
+const MEASURE_SIDE_EFFECT_ENV_KEYS = [
+  NOTIFY_BIN_ENV,
+  "FABERUN_CODEX_BIN",
+  "FABERUN_CLAUDE_BIN",
+  "FABERUN_AGY_BIN",
+  "FABERUN_DSH_BIN",
+  "FABERUN_ZCODE_BIN",
+  "FABERUN_EXEC_JSONL_BIN",
+];
 
 /**
  * Every path git tracks at HEAD, sorted. The bounded spawn is the same
@@ -124,9 +153,57 @@ function measureCandidates(cwd, commands, probes) {
   });
 }
 
+/**
+ * Run every requirement's declared `measure` command against the repository
+ * as it stands right now and record what it reports. This is the planner's
+ * fact, not the node's proof: it has to be evaluable before any node exists,
+ * which is why it reuses the same SpecProof shape `proof` parses into.
+ *
+ * The command goes through the shell (`spawnSync` with `shell: true`), so a
+ * requirement's own pipe — `| wc -l`, `| grep -v …` — works exactly as a spec
+ * author would type it at a terminal. The bounding shape matches
+ * `timeVerificationCommands` (stripped env, injectable probes, a hard
+ * ceiling) but that function discards stdout by design, so it cannot be
+ * reused where the output is the point. A non-zero exit is recorded, never
+ * thrown: finding the pattern still present is exactly the fact a draft
+ * needs.
+ *
+ * @param {string} cwd
+ * @param {SpecRequirement[]} requirements
+ * @param {MeasureProbes} [probes]
+ * @returns {RequirementMeasurement[]}
+ */
+export function measureRequirements(cwd, requirements, probes = {}) {
+  if (requirements.length === 0) return [];
+  const run = probes.run ?? spawnSync;
+  const env = { ...process.env };
+  for (const key of MEASURE_SIDE_EFFECT_ENV_KEYS) delete env[key];
+  /** @type {RequirementMeasurement[]} */
+  const measurements = [];
+  for (const requirement of requirements) {
+    // Only the `command` kind is wired: a `path` or `judgment` measure parses
+    // (parseProof already accepts both) but nothing runs it — left unmeasured
+    // rather than guessed at.
+    if (requirement.measure?.kind !== "command" || !requirement.measure.ref) continue;
+    const command = requirement.measure.ref;
+    const result = run(command, { shell: true, cwd, timeout: MEASURE_TIMEOUT_MS, encoding: "utf8", env });
+    const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    const bytes = Buffer.from(combined, "utf8");
+    const truncated = bytes.length > MEASURE_OUTPUT_CAP_BYTES;
+    measurements.push({
+      requirementId: requirement.id,
+      command,
+      output: truncated ? bytes.subarray(0, MEASURE_OUTPUT_CAP_BYTES).toString("utf8") : combined,
+      exitCode: result.status,
+      truncated,
+    });
+  }
+  return measurements;
+}
+
 /**
  * @param {string} cwd
- * @param {{measure?: MeasureProbes, maxPaths?: number}} [options]
+ * @param {{measure?: MeasureProbes, maxPaths?: number, requirements?: SpecRequirement[]}} [options]
  * @returns {RepoFacts}
  */
 export function collectRepoFacts(cwd, options = {}) {
@@ -144,5 +221,6 @@ export function collectRepoFacts(cwd, options = {}) {
     scripts,
     verificationCandidates: measureCandidates(cwd, commands, options.measure ?? {}),
     testFiles: testFileEntries(allPaths, pathSet),
+    requirementMeasurements: measureRequirements(cwd, options.requirements ?? [], options.measure ?? {}),
   };
 }

package/src/plan/spec.mjs

@@ -9,7 +9,7 @@ import { git } from "../repo/worktree.mjs";
 
 /** @typedef {"command"|"path"|"judgment"} ProofKind */
 /** @typedef {{kind: ProofKind, ref?: string}} SpecProof */
-/** @typedef {{id: string|null, title: string, statement: string|null, proof: SpecProof|null, constraints: string|null, line: number}} SpecRequirement */
+/** @typedef {{id: string|null, title: string, statement: string|null, proof: SpecProof|null, measure: SpecProof|null, constraints: string|null, line: number}} SpecRequirement */
 /** @typedef {Record<string, string>} SpecFrontMatter */
 /** @typedef {{heading: string, body: string, line: number}} SpecSection */
 /** @typedef {{frontMatter: SpecFrontMatter|null, sections: Map<string, SpecSection>, requirements: SpecRequirement[]}} ParsedSpec */
@@ -160,6 +160,7 @@ function extractRequirements(section) {
       title: idMatch ? idMatch[2].trim() : heading,
       statement: bullets.get("statement") ?? null,
       proof: parseProof(bullets.get("proof")),
+      measure: parseProof(bullets.get("measure")),
       constraints: bullets.get("constraints") ?? null,
       line: blockLine,
     });

package/src/repo/declared-paths.mjs

@@ -15,10 +15,16 @@ import { execFileSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { RUNS_DIR_NAME } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
 
-const ALWAYS_UNOBSERVABLE_ROOTS = new Set([".runs", ".git"]);
+// `RUNS_DIR_NAME` (the runner's own scratch tree) is never part of the
+// closed-scope snapshot, so a packet that declares a write under it warns
+// instead of refusing: the author may mean it, but no diff will ever exist to
+// prove the write happened. `.git` is unobservable for the same reason as any
+// path git ignores: there is nothing for `git status` to show.
+const ALWAYS_UNOBSERVABLE_ROOTS = new Set([RUNS_DIR_NAME, ".git"]);
 /**
  * @param {ValidatedNode} node
  * @param {number} index

package/src/repo/integrate.mjs

@@ -12,10 +12,10 @@ import {
   gitHead,
   removeWorktree,
   updateRefConditional,
-  candidateWorktreePath,
   runRefName,
   worktreeCheckedOutAt,
 } from "./worktree.mjs";
+import { candidateWorktreePath } from "../run/paths.mjs";
 
 const JOURNAL = "integration.jsonl";
 const TERMINAL = new Set(["accepted", "failed", "conflict"]);

package/src/repo/scope-closure.mjs

@@ -49,6 +49,7 @@
 import { errorCode } from "../util.mjs";
 import { readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { RUNS_DIR_NAME } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").TaskPacket} TaskPacket */
 /** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
@@ -62,7 +63,7 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
  */
 const SKIPPED_DIRECTORIES = new Set([
   ".git",
-  ".runs",
+  RUNS_DIR_NAME,
   "node_modules",
   ".claude",
   ".codex",

package/src/repo/signal.mjs

@@ -23,6 +23,7 @@ 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 { repositoryForRunsDir } from "../run/paths.mjs";
 import { SIGNAL_END, SIGNAL_START } from "./signal-block.mjs";
 import { HANDOFF_FILE } from "../campaign/layout.mjs";
 
@@ -158,9 +159,19 @@ function nodeText(node) {
   return `\`${node.id}:${node.status ?? "unknown"}${node.errorCode ? ` ${node.errorCode}` : ""}\``;
 }
 
-/** @param {string} value @returns {string} */
+/**
+ * The managed block is a list of single lines, so a multi-line summary (the
+ * inbox now carries `renderRunProgress`'s full, multi-line message for a
+ * `node.terminal`/`run.terminal`/`attention` event) is collapsed to its first
+ * line before the character bound applies. The block stays a pointer; the
+ * whole message lives in the inbox, one read away.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
 function boundedAttention(value) {
-  return value.length <= ATTENTION_CHARS ? value : `${value.slice(0, ATTENTION_CHARS - 1)}…`;
+  const line = value.split("\n")[0];
+  return line.length <= ATTENTION_CHARS ? line : `${line.slice(0, ATTENTION_CHARS - 1)}…`;
 }
 
 /**
@@ -184,16 +195,22 @@ function boundLines(lines) {
 }
 
 /**
- * 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.
+ * 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.
+ *
+ * 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
+ * climb would land inside `<home>/projects/<id>` and the block would silently
+ * stop being maintained. A legacy `<repo>/.runs` has no registry entry, so it
+ * keeps the parent-of answer, which is exact there.
  *
  * @param {string} runsDir
  * @returns {boolean}
  */
 export function syncAgentSignal(runsDir) {
-  const agentsPath = join(dirname(runsDir), "AGENTS.md");
+  const agentsPath = join(repositoryForRunsDir(runsDir) ?? dirname(runsDir), "AGENTS.md");
   if (!existsSync(agentsPath)) return false;
   const current = readFileSync(agentsPath, "utf8");
   const block = renderAgentSignalBlock(runsDir);

package/src/repo/source-identity.mjs

@@ -122,6 +122,13 @@ function sourcePathspec(options = {}) {
   return [
     ".",
     ":(exclude).runs",
+    // The planning pipeline's own scratch relay (src/plan/pipeline.mjs's
+    // PLAN_SCRATCH_DIR_NAME) lands inside the target repo the same way
+    // .runs used to: untracked, and not every target repository's own
+    // .gitignore names it. Excluded here for the same reason .runs is —
+    // a dirty-tree refusal must not fire on state the pipeline itself
+    // wrote, only on an operator's own uncommitted work.
+    ":(exclude).faberun-plan",
     ":(exclude)AGENTS.md",
     ...(options.ignorePaths ?? []).map((path) => `:(exclude)${path}`),
     ...(options.ignoreRoots ?? []).map((path) => `:(exclude)${path}`),