faberun 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.16.0",
+  "version": "0.17.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": {
@@ -26,7 +26,7 @@
   "scripts": {
     "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",
+    "test": "node --test --import ./test/scoped-home.mjs --import ./test/setup.mjs test/*.test.mjs test/*/*.test.mjs",
     "docs": "node src/cli/manual.mjs --write",
     "docs:check": "node src/cli/manual.mjs --check",
     "prepare": "husky"

package/src/campaign/journal.mjs

@@ -8,7 +8,7 @@
  * the journal's own `eventId` so two sessions cannot consume each other's place.
  */
 import { JOURNAL_FILE, JOURNAL_TEXT_BYTES, JOURNAL_WATCH_CURSOR_DIR, JOURNAL_WATCH_CURSOR_SCHEMA_VERSION } from "./layout.mjs";
-import { boundedText, collapseLines } from "../util.mjs";
+import { collapseLines } from "../util.mjs";
 import { campaignIdOf } from "./record.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -382,6 +382,11 @@ function normalizeEntry(entry) {
   return /** @type {JournalEntry} */ (normalized);
 }
 /**
+ * Collapse to one line and enforce the byte cap by refusing, not truncating:
+ * the journal is the record of what was written, so a note that does not fit
+ * is the author's to cut -- a silently shortened entry lies about its own
+ * write. Readers of already-stored text never pass through here.
+ *
  * @param {unknown} value
  * @param {string} label
  * @param {number} maxBytes
@@ -391,5 +396,9 @@ export function normalizeText(value, label, maxBytes = JOURNAL_TEXT_BYTES) {
   requireText(value, label);
   const collapsed = collapseLines(value);
   if (!collapsed) throw new TypeError(`${label} must not be blank`);
-  return boundedText(collapsed, maxBytes);
+  const bytes = Buffer.byteLength(collapsed, "utf8");
+  if (bytes > maxBytes) {
+    throw new TypeError(`${label} is ${bytes} bytes, over the ${maxBytes}-byte cap; cut ${bytes - maxBytes} bytes and retry`);
+  }
+  return collapsed;
 }

package/src/engine/gate.mjs

@@ -30,6 +30,7 @@
 import { existsSync, readFileSync, statSync, openSync, closeSync, readSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
 import { spawn } from "node:child_process";
+import { NOTIFY_ENV_NAMES } from "../notify/index.mjs";
 
 /** @typedef {{executable: string, args: string[], cwd: string, promptTransport: "stdin"|"argv", harness: string, env: Record<string, string|null>|null, stdoutPath: string, stderrPath: string}} GateConfig */
 
@@ -155,9 +156,13 @@ function childEnv() {
     if (value === null) delete merged[key];
     else merged[key] = value;
   }
-  // Worker providers are not a notification surface: strip the controller-only
-  // transport after the harness overlay so no harness can reintroduce it.
-  delete merged.FABERUN_NOTIFY_BIN;
+  // Worker providers are not a notification surface: strip every controller-only
+  // transport after the harness overlay so no harness can reintroduce one. The
+  // list lives in `notify/index.mjs`, not here: this line once named
+  // FABERUN_NOTIFY_BIN alone, and on 2026-09-21 a worker that inherited
+  // FABERUN_NOTIFY_SESSION ran this repository's suite, whose fixture
+  // controllers woke the operator's live session seven times in minutes.
+  for (const name of NOTIFY_ENV_NAMES) delete merged[name];
   return merged;
 }
 

package/src/engine/judge-gate.mjs

@@ -135,6 +135,74 @@ function proveVerification(id, proof, recorded) {
   return { id, kind: "verification", ref: proof.ref, pass: entry.passed === true, detail };
 }
 
+/**
+ * A command proof that declares a node:test filter (`--test-name-pattern`,
+ * `--test-skip-pattern`) is judged on more than its exit code, because the
+ * runner exits 0 whether its filter selected anything or not. The proof runs
+ * with the TAP reporter selected through `NODE_OPTIONS` and is refused when the
+ * output carries TAP's zero-plan line. Measured 2026-09-21 on node v26.8.1: a
+ * filter that matches emits `1..0` zero times, a filter that matches nothing
+ * emits it exactly once, a run with no filter emits it zero times, and an empty
+ * suite under a matching filter emits no nested zero plan. The default reporter
+ * cannot make the distinction -- both cases print identical counters, because
+ * the tick is the file rather than a test. The reporter goes through the
+ * environment because appending `--test-reporter=tap` to the command string is
+ * a no-op whenever a test file precedes it: node reads its own options
+ * left to right, so the flag lands among the script's arguments and the runner
+ * never sees it.
+ */
+const TEST_FILTER_FLAGS = ["--test-name-pattern", "--test-skip-pattern"];
+const TAP_ZERO_PLAN = /^1\.\.0$/mu;
+
+/**
+ * The environment a filtered proof runs under: the ambient environment with
+ * the TAP reporter selected through `NODE_OPTIONS`, minus `NODE_TEST_CONTEXT`.
+ * That marker belongs to whichever test runner spawned this process; a nested
+ * `node --test` that inherits it stays a runner child and emits no TAP at all
+ * (measured 2026-09-21: with the marker the zero-plan line never appears,
+ * without it exactly once) -- and a proof is judged as its own top-level run,
+ * not as the suite's child.
+ *
+ * @returns {NodeJS.ProcessEnv}
+ */
+function envForFilteredProof() {
+  const { NODE_TEST_CONTEXT: _outer, NODE_OPTIONS: existing, ...ambient } = process.env;
+  return { ...ambient, NODE_OPTIONS: existing ? `${existing} --test-reporter=tap` : "--test-reporter=tap" };
+}
+
+/**
+ * The node:test filters a command string declares, in argv order, as flag and
+ * value. Presence alone changes behaviour (the appended reporter and the
+ * zero-plan look-up); the value is read for the refusal detail alone, which is
+ * why a whitespace split is close enough even though the command runs through
+ * a shell.
+ *
+ * @param {string} ref
+ * @returns {Array<{flag: string, value: string}>}
+ */
+function declaredTestFilters(ref) {
+  const tokens = ref.split(/\s+/u).filter(Boolean);
+  /** @type {Array<{flag: string, value: string}>} */
+  const filters = [];
+  for (const [index, token] of tokens.entries()) {
+    for (const flag of TEST_FILTER_FLAGS) {
+      if (token.startsWith(`${flag}=`)) filters.push({ flag, value: unquote(token.slice(flag.length + 1)) });
+      else if (token === flag) filters.push({ flag, value: unquote(tokens[index + 1] ?? "") });
+    }
+  }
+  return filters;
+}
+
+/** @param {string} value @returns {string} */
+function unquote(value) {
+  return value.replace(/^['"]|['"]$/gu, "");
+}
+
+/** @param {Array<{flag: string, value: string}>} filters @returns {string} */
+function filterNames(filters) {
+  return filters.map(({ flag, value }) => `${flag} "${value}"`).join(", ");
+}
+
 /**
  * @param {string} id
  * @param {DefinitionOfDoneProof} proof
@@ -144,11 +212,18 @@ function proveVerification(id, proof, recorded) {
  */
 async function proveCommand(id, proof, cwd, timeoutMs) {
   const ref = proof.ref;
+  const filters = declaredTestFilters(ref);
   return new Promise((settle) => {
     // Detached on POSIX so the shell leads its own process group: `shell: true`
     // means the timeout must kill the group, not the shell, or the command the
     // shell started keeps running and keeps the result pending forever.
-    const child = spawn(ref, { cwd, shell: true, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn(ref, {
+      cwd,
+      shell: true,
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(filters.length ? { env: envForFilteredProof() } : {}),
+    });
     let stdout = "";
     let stderr = "";
     let settled = false;
@@ -178,6 +253,18 @@ async function proveCommand(id, proof, cwd, timeoutMs) {
       finish({ id, kind: "command", ref, pass: false, detail: boundedText(error.message) });
     });
     child.on("close", (code, signal) => {
+      // Its own detail, not an ordinary command failure: the command succeeded,
+      // so what failed is that the declared filter selected nothing to prove.
+      if (code === 0 && signal === null && filters.length > 0 && TAP_ZERO_PLAN.test(stdout)) {
+        finish({
+          id,
+          kind: "command",
+          ref,
+          pass: false,
+          detail: boundedText(`${filterNames(filters)} selected no test: exit 0 over a TAP plan of 1..0, so the proof measured nothing`),
+        });
+        return;
+      }
       const detail = signal !== null ? `killed by ${signal}` : `exit ${code ?? "?"}`;
       const pass = code === 0 && signal === null;
       finish({ id, kind: "command", ref, pass, detail: pass ? detail : boundedText(`${detail}: ${(stderr || stdout).trim()}`) });

package/src/harnesses/index.mjs

@@ -6,6 +6,7 @@ import { dshHarness } from "./dsh/index.mjs";
 import { zcodeHarness } from "./zcode/index.mjs";
 import { execJsonlHarness } from "./exec-jsonl/index.mjs";
 import { replayHarness } from "./replay/index.mjs";
+import { withoutNotifyEnv } from "../notify/index.mjs";
 
 /** Current wire-contract version for runner protocol artifacts. */
 export const PROTOCOL_SCHEMA_VERSION = 3;
@@ -451,7 +452,10 @@ export function probeRuntime(runtime, options = {}) {
     try {
       child = spawn(executable, args, {
         cwd: options.cwd,
-        env: process.env,
+        // A worker or judge never delivers a notification; the controller does.
+        // In this repository a worker runs the test suite, whose fixture
+        // controllers would otherwise inherit a live transport and deliver.
+        env: withoutNotifyEnv(process.env),
         stdio: ["ignore", "pipe", "pipe"],
       });
     } catch (error) {

package/src/notify/index.mjs

@@ -50,7 +50,7 @@ import { createHash } from "node:crypto";
 import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { createMacosNotifier } from "./os-macos.mjs";
-import { deliverToSessions, resolveSessionTargets, sessionWakeNotice } from "./session.mjs";
+import { NOTIFY_SESSION_ENV, deliverToSessions, resolveSessionTargets, sessionWakeNotice } from "./session.mjs";
 import { errorMessage } from "../util.mjs";
 
 /**
@@ -74,6 +74,29 @@ function loadProgressModule() {
 
 export const NOTIFY_BIN_ENV = "FABERUN_NOTIFY_BIN";
 const MACOS_TRANSPORT = "os-macos";
+
+/**
+ * Every variable that binds a notification transport. The controller is the
+ * only process that delivers: a worker, a judge or a verification command
+ * that inherits these would notify on the controller's behalf -- and in this
+ * repository, whose workers run its own test suite, every fixture controller
+ * the suite spawns would deliver its terminal events for real. Measured
+ * 2026-09-21: a run launched with `FABERUN_NOTIFY_SESSION=auto` woke the
+ * operator's session seven times in minutes from `test/repo/base-ref.test.mjs`
+ * fixtures its worker ran. `withoutNotifyEnv` is the boundary every child
+ * crosses; `test/setup.mjs` neutralises the same names inside the suite.
+ */
+export const NOTIFY_ENV_NAMES = Object.freeze([NOTIFY_BIN_ENV, NOTIFY_SESSION_ENV]);
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {NodeJS.ProcessEnv} a copy with every notify transport unbound
+ */
+export function withoutNotifyEnv(env) {
+  const copy = { ...env };
+  for (const name of NOTIFY_ENV_NAMES) delete copy[name];
+  return copy;
+}
 export const NOTIFY_LOG_FILE = "notify.jsonl";
 /**
  * The bounded retry budget the dispatcher used to spend before giving up.

package/src/repo/signal.mjs

@@ -14,8 +14,12 @@
  * 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.
+ * `attention` entry from `.runs/inbox.jsonl`. An attention belongs to one
+ * campaign or none: an explicit `campaignId` decides, a null one is resolved
+ * from the entry's `runId` (a run belongs to at most one campaign), and an
+ * entry whose run no active campaign owns is shown once at run level instead
+ * of under every campaign at once. It is bounded, because every session pays
+ * for it in its first tokens.
  */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -47,21 +51,45 @@ export function renderAgentSignalBlock(runsDir) {
   const lines = [];
   /** @type {Set<string>} */
   const linked = new Set();
-  const { campaigns } = discoverCampaigns(runsDir);
-  for (const { campaign } of campaigns.filter(({ campaign }) => campaign.status !== "closed")) {
+  const active = discoverCampaigns(runsDir).campaigns.filter(({ campaign }) => campaign.status !== "closed");
+  const ownerByRun = runOwnerIndex(active);
+  for (const { campaign } of active) {
     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);
+    const attention = campaignAttentionLine(runsDir, campaign, ownerByRun);
     if (attention) lines.push(attention);
   }
   for (const line of activeRunLines(runsDir, linked)) lines.push(line);
+  const orphan = orphanAttentionLine(runsDir, ownerByRun);
+  if (orphan) lines.push(orphan);
   if (!lines.length) return "";
   return `${SIGNAL_START}\n${HEADER}\n\n${boundLines(lines).join("\n")}\n${SIGNAL_END}`;
 }
 
+/**
+ * Which active campaign owns each run, read from the campaigns' own
+ * `linkedRunIds`. A run belongs to at most one campaign, so the first
+ * campaign naming a run wins; a run no active campaign names is absent from
+ * the map, and that absence — never a guess — is what makes an inbox entry
+ * unattributable.
+ *
+ * @param {{campaign: import("../campaign/index.mjs").Campaign}[]} active
+ * @returns {Map<string, string>}
+ */
+function runOwnerIndex(active) {
+  /** @type {Map<string, string>} */
+  const ownerByRun = new Map();
+  for (const { campaign } of active) {
+    for (const runId of campaign.linkedRunIds) {
+      if (!ownerByRun.has(runId)) ownerByRun.set(runId, campaign.id);
+    }
+  }
+  return ownerByRun;
+}
+
 /**
  * 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
@@ -132,16 +160,17 @@ function activeRunLines(runsDir, linked) {
 }
 
 /**
- * The most recent campaign-level attention: an inbox entry when one exists,
- * otherwise the durable record on the campaign itself.
+ * The most recent attention this campaign owns: an inbox entry when one
+ * exists, otherwise the durable record on the campaign itself.
  *
  * @param {string} runsDir
  * @param {import("../campaign/index.mjs").Campaign} campaign
+ * @param {Map<string, string>} ownerByRun
  * @returns {string|null}
  */
-function campaignAttentionLine(runsDir, campaign) {
+function campaignAttentionLine(runsDir, campaign, ownerByRun) {
   const latest = readInbox(runsDir)
-    .filter((entry) => entry.type === "attention" && (entry.campaignId === campaign.id || entry.campaignId === null))
+    .filter((entry) => entry.type === "attention" && attentionBelongsTo(entry, campaign.id, ownerByRun))
     .at(-1);
   if (latest) return `  - attention: ${boundedAttention(latest.summary)}`;
   if (campaign.attention && typeof campaign.attention.message === "string") {
@@ -151,6 +180,44 @@ function campaignAttentionLine(runsDir, campaign) {
   return null;
 }
 
+/**
+ * An attention belongs to one campaign or none. An explicit `campaignId` is
+ * authoritative; a null one is resolved from the entry's `runId` through the
+ * run-owner index. Measured 2026-09-21: all 12 attention entries in the live
+ * inbox carry null, so the old `campaignId === null` fallback attributed an
+ * orphan to every campaign at once, permanently. An entry whose run resolves
+ * to no active campaign belongs to none and is surfaced once at run level by
+ * `orphanAttentionLine`, not dropped.
+ *
+ * @param {import("../notify/index.mjs").InboxEntry} entry
+ * @param {string} campaignId
+ * @param {Map<string, string>} ownerByRun
+ * @returns {boolean}
+ */
+function attentionBelongsTo(entry, campaignId, ownerByRun) {
+  if (entry.campaignId !== null) return entry.campaignId === campaignId;
+  return entry.runId !== null && ownerByRun.get(entry.runId) === campaignId;
+}
+
+/**
+ * The most recent attention no campaign owns, as one run-level line. Dropping
+ * it would trade the old wrong report (every campaign) for a missing one, and
+ * the run-level section of the block is where campaign-less work already
+ * lives.
+ *
+ * @param {string} runsDir
+ * @param {Map<string, string>} ownerByRun
+ * @returns {string|null}
+ */
+function orphanAttentionLine(runsDir, ownerByRun) {
+  const latest = readInbox(runsDir)
+    .filter((entry) => entry.type === "attention" && entry.campaignId === null && (entry.runId === null || !ownerByRun.has(entry.runId)))
+    .at(-1);
+  if (!latest) return null;
+  const subject = latest.runId ? `run \`${latest.runId}\`` : "an entry with no run";
+  return `- attention: ${subject} resolves to no campaign — ${boundedAttention(latest.summary)}`;
+}
+
 /**
  * @param {import("../engine/supervise.mjs").OutcomeNode} node
  * @returns {string}