faberun 0.17.1 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.17.1",
+  "version": "0.18.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": {

package/skills/faberun/references/operations.md

@@ -111,7 +111,10 @@ the contract is frozen with a digest, and the phone's middle ground is a note.
 
 On `node.terminal`, `run.terminal` and `attention` the controller renders one
 message from persisted state, in the operator's own language (detected from
-the campaign goal, journal notes and node objectives; English otherwise):
+the campaign goal, journal notes and node objectives, or `FABERUN_NOTIFY_LANG`;
+English otherwise). Only `run.terminal`, `attention` and `advisory` leave by
+default -- a phase settling and a person being needed -- while a node settling
+gets a `filtered` receipt; `FABERUN_NOTIFY_EVENTS` widens or narrows the list:
 line one is the outcome (`✅ <node> · done in 8m · $0.09`, `🏁 run 15 · <name>
 · 2/2 done`, or `👀 <node> needs you · <error>`), then asked / done / proof
 for a node, what every node delivered for a run, or why / asked / do for
@@ -123,12 +126,16 @@ same text to every bound transport at once, appending one receipt
 `<run-dir>/notify.jsonl`. Delivery is lossy: **exactly one attempt**, no retry,
 no backoff. `FABERUN_NOTIFY_BIN` names an executable called with the event as
 JSON on stdin (`os-macos` selects the bundled `osascript` adapter); it pushes to
-a person, `canWake: false`. `FABERUN_NOTIFY_SESSION=auto` wakes the harness
-session the controller was launched from, `canWake: true`: the Claude Code
-inbox socket and the Codex thread the environment names. A seat window sets it;
-nothing else does, so a test suite never wakes a session. **On an inbound
-`🐦 faberun` message**: `✅` or `🏁` with nothing waiting, answer in one line
-and keep waiting; `👀`, act on the `do` command it names. A
+a person, `canWake: false`. `FABERUN_NOTIFY_SESSION` wakes harness sessions,
+`canWake: true`: `auto` is the Claude Code inbox and Codex thread the
+environment names; `claude:<socket>` adds another session's inbox, so the
+operator's own interactive session hears a run a background session launched
+(`echo $CLAUDE_CODE_MESSAGING_SOCKET` in that session gives the path). A seat
+window sets `auto`; nothing else does, so a test suite never wakes a session.
+**On an inbound `🐦 faberun` message**: repeat it to the operator verbatim,
+then one line on what you do next -- the message exists to inform the person,
+not you, and it reaches them only through your reply; `👀`, act on the `do`
+command it names. A
 resume never re-sends a notification already recorded for the same node, attempt
 and outcome. No transport is a default: `doctor`, `preflight` and the foreground
 launch warn when both variables are empty, and `--wake` names what will wake.

package/src/campaign/metrics.mjs

@@ -46,7 +46,9 @@ const DONE_STATUSES = new Set(["done", "no-op"]);
 /** Gate review that blocks the node on a failing verdict (TECH-SPEC lean, rule 2). */
 const BLOCKING_REVIEW = "blocking";
 /** A receipt this settled: delivered, no transport bound, or the retry budget spent. */
-const SETTLED_NOTIFY_STATUSES = new Set(["delivered", "no_transport"]);
+// `filtered` is a decided outcome too: the event type was kept out of every
+// transport on purpose (`FABERUN_NOTIFY_EVENTS`), not lost.
+const SETTLED_NOTIFY_STATUSES = new Set(["delivered", "no_transport", "filtered"]);
 /** Target latency for a terminal/attention event to carry a settled receipt (TECH-SPEC section 6). */
 const NOTIFY_TARGET_SEC = 60;
 const SECONDS_PER_HOUR = 3600;

package/src/host/preflight.mjs

@@ -26,7 +26,7 @@ import { DISCOVERY_RUNTIME_DEFINITIONS, discoverRuntimes } from "../engine/runti
 import { errorMessage } from "../util.mjs";
 import { boundedGitSync } from "../repo/worktree.mjs";
 import { routeRuntime } from "../contract/runtime.mjs";
-import { NOTIFY_BIN_ENV, noTransportWarning } from "../notify/index.mjs";
+import { NOTIFY_BIN_ENV, deliverableEventTypes, noTransportWarning, notifySettingProblems } from "../notify/index.mjs";
 import { NOTIFY_SESSION_ENV, sessionWakeNotice } from "../notify/session.mjs";
 import { findExecutable } from "./platform.mjs";
 import { colorLevel, statusToken } from "../cli/brand.mjs";
@@ -209,10 +209,13 @@ export function environmentPreflight(options) {
  * @returns {EnvCheck}
  */
 export function notifyTransportCheck(env = process.env) {
+  const problems = notifySettingProblems(env);
+  if (problems.length) return fail("notify transport", problems.join("; "), true);
   const warning = noTransportWarning(env);
   if (warning) return fail("notify transport", warning, true);
   const external = env[NOTIFY_BIN_ENV] ? `${NOTIFY_BIN_ENV}=${env[NOTIFY_BIN_ENV]}` : `${NOTIFY_BIN_ENV} unset`;
-  return pass("notify transport", `${external} · ${sessionWakeNotice(env)}`);
+  const events = [...deliverableEventTypes(env)].join(",");
+  return pass("notify transport", `${external} · ${sessionWakeNotice(env)} · events: ${events}`);
 }
 
 /** @param {EnvReport} report @returns {EnvCheck[]} the checks that block a dispatch */

package/src/notify/index.mjs

@@ -86,7 +86,59 @@ const MACOS_TRANSPORT = "os-macos";
  * 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]);
+export const NOTIFY_EVENTS_ENV = "FABERUN_NOTIFY_EVENTS";
+export const NOTIFY_LANG_ENV = "FABERUN_NOTIFY_LANG";
+export const NOTIFY_ENV_NAMES = Object.freeze([NOTIFY_BIN_ENV, NOTIFY_SESSION_ENV, NOTIFY_EVENTS_ENV, NOTIFY_LANG_ENV]);
+
+/** Every event type the dispatcher can be asked to deliver. */
+export const NOTIFY_EVENT_TYPES = Object.freeze(["node.terminal", "run.terminal", "attention", "advisory"]);
+
+/**
+ * What leaves the controller when `FABERUN_NOTIFY_EVENTS` is unset: a phase
+ * settling, a node that waits on a person, and an advisory threshold the
+ * operator declared. A node settling stays in `notify.jsonl` as a `filtered`
+ * receipt. The operator's own words, 2026-09-22, after a run of two nodes
+ * produced four wake-ups: "só fechamento de fase e atenção acordam, nó
+ * individual fica no log" -- and before that, after the phone flood, "só
+ * milestones e fechamentos de fase". Measured on the campaign that prompted
+ * it: five phases of two or three nodes would be about 20 messages with every
+ * event, about 7 with these.
+ */
+export const DEFAULT_NOTIFY_EVENTS = Object.freeze(["run.terminal", "attention", "advisory"]);
+
+/** The two languages the message renders its wording in; `FABERUN_NOTIFY_LANG` may name either. */
+export const NOTIFY_LANGUAGES = Object.freeze(["en", "pt"]);
+
+/**
+ * The event types the environment lets out, as a set. Unknown items are left
+ * out here and reported by `notifySettingProblems`; an empty value is the
+ * default, never "nothing".
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Set<string>}
+ */
+export function deliverableEventTypes(env = process.env) {
+  const items = (env[NOTIFY_EVENTS_ENV] ?? "").split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+  return new Set(items.length ? items.filter((item) => NOTIFY_EVENT_TYPES.includes(item)) : DEFAULT_NOTIFY_EVENTS);
+}
+
+/**
+ * Every notify setting the environment gets wrong, one sentence each, for
+ * `doctor` and `preflight`. Empty when everything parses.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+export function notifySettingProblems(env = process.env) {
+  const problems = [];
+  const events = (env[NOTIFY_EVENTS_ENV] ?? "").split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+  for (const item of events) {
+    if (!NOTIFY_EVENT_TYPES.includes(item)) problems.push(`${NOTIFY_EVENTS_ENV} item "${item}" is not one of ${NOTIFY_EVENT_TYPES.join(", ")}`);
+  }
+  const lang = (env[NOTIFY_LANG_ENV] ?? "").trim();
+  if (lang && !NOTIFY_LANGUAGES.includes(lang)) problems.push(`${NOTIFY_LANG_ENV}=${lang} is not one of ${NOTIFY_LANGUAGES.join(", ")}`);
+  return problems;
+}
 
 /**
  * @param {NodeJS.ProcessEnv} env
@@ -156,7 +208,7 @@ export const NOTIFY_NO_TRANSPORT_WARNING = "no human notification transport is c
 /** @typedef {Record<string, unknown>} JsonObject */
 /** @typedef {{schemaVersion: number, eventId: string, at: string, type: string, campaignId: string|null, runId: string|null, nodeId: string|null, status: string|null, errorCode: string|null, dedupeKey: string, summary: string}} InboxEntry */
 /** @typedef {{type: string, dedupeKey: string, summary: string, at?: string, campaignId?: string|null, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}} InboxEvent */
-/** @typedef {{type: "node.terminal"|"run.terminal"|"attention", runId: string|null, campaignId?: string|null, nodeId?: string|null, status?: string|null, attempt?: number|null, errorCode?: string|null, done?: number|null, total?: number|null, dedupeKey?: string|null, runDir?: string|null, costUsd?: number|null, summary?: string|null, eventId?: string}} NotifyEvent */
+/** @typedef {{type: "node.terminal"|"run.terminal"|"attention"|"advisory", runId: string|null, campaignId?: string|null, nodeId?: string|null, status?: string|null, attempt?: number|null, errorCode?: string|null, done?: number|null, total?: number|null, dedupeKey?: string|null, runDir?: string|null, costUsd?: number|null, summary?: string|null, eventId?: string}} NotifyEvent */
 /** @typedef {{id: string, ok: boolean, error?: string}} TransportOutcome one transport's own outcome, named so the receipt says which took the message */
 /** @typedef {{ok: boolean, error?: string, noTransport?: boolean, transports?: TransportOutcome[]}} DeliveryResult */
 
@@ -503,14 +555,22 @@ export class NotifyQueue {
     // one), so every delivery carries a stable id derived from the dedupe key.
     const eventId = enriched.eventId
       ?? createHash("sha256").update(enriched.dedupeKey ?? JSON.stringify(enriched)).digest("hex");
+    // An event type the environment keeps out of every transport is still a
+    // receipt -- `filtered`, with the rendered summary -- so the log says what
+    // happened to it, and the resume's dedupe sees it as already handled.
+    const filtered = !deliverableEventTypes().has(enriched.type);
     /** @type {DeliveryResult} */
     let result;
-    try {
-      result = await this.deliver({ ...enriched, summary, eventId });
-    } catch (error) {
-      // A transport that rejects is a failed delivery, not a controller fault:
-      // the receipt is still appended and the failure is dropped like any other.
-      result = { ok: false, error: errorMessage(error) };
+    if (filtered) {
+      result = { ok: false, transports: [] };
+    } else {
+      try {
+        result = await this.deliver({ ...enriched, summary, eventId });
+      } catch (error) {
+        // A transport that rejects is a failed delivery, not a controller fault:
+        // the receipt is still appended and the failure is dropped like any other.
+        result = { ok: false, error: errorMessage(error) };
+      }
     }
     /** @type {JsonObject} */
     const receipt = {
@@ -525,13 +585,13 @@ export class NotifyQueue {
       dedupeKey: enriched.dedupeKey ?? null,
       summary,
       attempt: 1,
-      status: result.ok ? "delivered" : result.noTransport ? "no_transport" : "failed",
+      status: filtered ? "filtered" : result.ok ? "delivered" : result.noTransport ? "no_transport" : "failed",
       // One entry per bound transport, so a receipt that says `delivered`
       // also says whether the phone, the session, or both took the message.
       transports: result.transports ?? [],
       at: new Date(this.now()).toISOString(),
     };
-    if (!result.ok && !result.noTransport) receipt.error = result.error ?? null;
+    if (!filtered && !result.ok && !result.noTransport) receipt.error = result.error ?? null;
     appendFileSync(join(this.runDir, NOTIFY_LOG_FILE), `${JSON.stringify(receipt)}\n`);
   }
 }

package/src/notify/session.mjs

@@ -44,7 +44,7 @@ export const CODEX_THREAD_ENV = "CODEX_THREAD_ID";
  */
 export const SESSION_DELIVERY_TIMEOUT_MS = 5_000;
 
-/** The values the variable accepts besides `codex:<thread>`. */
+/** The bare words an item of the setting may be; `codex:<thread>` and `claude:<socket>` carry an address. */
 const SETTINGS = new Set(["off", "auto", "claude", "codex"]);
 
 /** @typedef {Record<string, unknown>} JsonObject */
@@ -59,32 +59,66 @@ const SETTINGS = new Set(["off", "auto", "claude", "codex"]);
 /** @typedef {(path: string) => SessionSocket} ConnectFunction */
 
 /**
- * The sessions the variable and the environment together name. `auto` takes
- * every session whose address is present -- a Codex thread opened from a
- * Claude Code shell inherits both, and both are supervising. An explicit
- * `claude` or `codex` whose address is absent resolves to nothing; the
- * doctor reports why through `sessionSettingProblem`, this function never
- * throws, because it backs a lossy dispatcher.
+ * The sessions the variable and the environment together name. The value is
+ * a comma-separated list; each item is one of:
+ *
+ *   auto             every session whose address this process inherited --
+ *                    a Codex thread opened from a Claude Code shell inherits
+ *                    both, and both are supervising
+ *   claude           the inherited Claude Code inbox alone
+ *   codex            the inherited Codex thread alone
+ *   codex:<thread>   a Codex thread by id or name
+ *   claude:<socket>  a Claude Code inbox by socket path -- the operator's
+ *                    own interactive session, which did not launch the run
+ *                    and would otherwise never hear of it (the session that
+ *                    launches a campaign is often a background one nobody
+ *                    reads); the token travels only to the inherited inbox,
+ *                    since it belongs to that session and no other
+ *   off              nothing, whatever else the list says
+ *
+ * An item whose address is absent resolves to nothing; the doctor reports
+ * why through `sessionSettingProblem`. This function never throws, because it
+ * backs a lossy dispatcher. Duplicates collapse: `auto,claude:<own socket>`
+ * is one target.
  *
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {SessionTarget[]}
  */
 export function resolveSessionTargets(env = process.env) {
-  const setting = (env[NOTIFY_SESSION_ENV] ?? "").trim();
-  if (!setting || setting === "off") return [];
+  const items = settingItems(env);
+  if (!items.length || items.includes("off")) return [];
   /** @type {SessionTarget[]} */
   const targets = [];
-  const socketPath = env[CLAUDE_SOCKET_ENV];
-  if ((setting === "auto" || setting === "claude") && socketPath) {
-    targets.push({ kind: "claude", id: "claude-session", socketPath, token: env[CLAUDE_TOKEN_ENV] || null });
-  }
-  const thread = setting.startsWith("codex:") ? setting.slice("codex:".length).trim() : env[CODEX_THREAD_ENV];
-  if ((setting === "auto" || setting === "codex" || setting.startsWith("codex:")) && thread) {
-    targets.push({ kind: "codex", id: "codex-session", thread });
+  /** @param {SessionTarget} target */
+  const add = (target) => {
+    const address = target.kind === "claude" ? target.socketPath : target.thread;
+    if (!targets.some((known) => known.kind === target.kind && (known.kind === "claude" ? known.socketPath : known.thread) === address)) targets.push(target);
+  };
+  const inheritedSocket = env[CLAUDE_SOCKET_ENV];
+  const inheritedThread = env[CODEX_THREAD_ENV];
+  for (const item of items) {
+    if ((item === "auto" || item === "claude") && inheritedSocket) {
+      add({ kind: "claude", id: "claude-session", socketPath: inheritedSocket, token: env[CLAUDE_TOKEN_ENV] || null });
+    }
+    if ((item === "auto" || item === "codex") && inheritedThread) {
+      add({ kind: "codex", id: "codex-session", thread: inheritedThread });
+    }
+    if (item.startsWith("codex:") && item.slice("codex:".length).trim()) {
+      add({ kind: "codex", id: "codex-session", thread: item.slice("codex:".length).trim() });
+    }
+    if (item.startsWith("claude:") && item.slice("claude:".length).trim()) {
+      const socketPath = item.slice("claude:".length).trim();
+      add({ kind: "claude", id: "claude-session", socketPath, token: socketPath === inheritedSocket ? env[CLAUDE_TOKEN_ENV] || null : null });
+    }
   }
   return targets;
 }
 
+/** @param {NodeJS.ProcessEnv} env @returns {string[]} the non-empty items of the setting */
+function settingItems(env) {
+  return (env[NOTIFY_SESSION_ENV] ?? "").split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+
 /**
  * Why the setting names no session, in one sentence for `doctor` and
  * `--wake`; `null` when it is unset, `off`, or resolves to at least one.
@@ -93,15 +127,16 @@ export function resolveSessionTargets(env = process.env) {
  * @returns {string|null}
  */
 export function sessionSettingProblem(env = process.env) {
-  const setting = (env[NOTIFY_SESSION_ENV] ?? "").trim();
-  if (!setting || setting === "off") return null;
-  if (!SETTINGS.has(setting) && !setting.startsWith("codex:")) {
-    return `${NOTIFY_SESSION_ENV}=${setting} is not one of off, auto, claude, codex, codex:<thread>`;
+  const items = settingItems(env);
+  if (!items.length || items.includes("off")) return null;
+  const unknown = items.find((item) => !SETTINGS.has(item) && !(item.startsWith("codex:") && item.length > "codex:".length) && !(item.startsWith("claude:") && item.length > "claude:".length));
+  if (unknown !== undefined) {
+    return `${NOTIFY_SESSION_ENV} item "${unknown}" is not one of off, auto, claude, codex, codex:<thread>, claude:<socket>`;
   }
   if (resolveSessionTargets(env).length) return null;
+  const [setting] = items;
   if (setting === "claude") return `${NOTIFY_SESSION_ENV}=claude but ${CLAUDE_SOCKET_ENV} is not set: this process was not started from inside a Claude Code session`;
   if (setting === "codex") return `${NOTIFY_SESSION_ENV}=codex but ${CODEX_THREAD_ENV} is not set: this process was not started from inside a Codex session`;
-  if (setting.startsWith("codex:")) return `${NOTIFY_SESSION_ENV}=codex: names an empty thread id`;
   return `${NOTIFY_SESSION_ENV}=auto found neither ${CLAUDE_SOCKET_ENV} nor ${CODEX_THREAD_ENV}: no harness session to wake`;
 }
 
@@ -228,13 +263,13 @@ export function createCodexSessionNotifier({ spawn = /** @type {SpawnFunction} *
  * @param {SessionEvent} event
  * @param {SessionTarget[]} targets
  * @param {{connect?: ConnectFunction, spawn?: SpawnFunction, timeoutMs?: number, env?: NodeJS.ProcessEnv}} [options]
- * @returns {Promise<{id: string, ok: boolean, error?: string}[]>}
+ * @returns {Promise<{id: string, address: string, ok: boolean, error?: string}[]>}
  */
 export function deliverToSessions(event, targets, options = {}) {
   return Promise.all(targets.map(async (target) => {
     const result = target.kind === "claude"
       ? await createClaudeSessionNotifier(options).deliver(event, target)
       : await createCodexSessionNotifier(options).deliver(event, target);
-    return { id: target.id, ...result };
+    return { id: target.id, address: target.kind === "claude" ? target.socketPath : target.thread, ...result };
   }));
 }

package/src/report/locale.mjs

@@ -16,6 +16,8 @@
  * function there.
  */
 
+import { NOTIFY_LANG_ENV } from "../notify/index.mjs";
+
 /** @typedef {"en"|"pt"} Language */
 
 // `a`, `do` and `no` are left out on purpose: each is also an English word,
@@ -51,6 +53,24 @@ export function detectLanguage(...groups) {
   return "en";
 }
 
+/**
+ * The language the message is written in: `FABERUN_NOTIFY_LANG` when the
+ * operator set it to a language this module has (a campaign whose goal an
+ * orchestrator wrote in English still belongs to a person who reads
+ * Portuguese), else detection over the groups. The override moves the
+ * wording only; quoted text keeps the language it was written in, so a
+ * Portuguese label may sit beside an English objective -- honest, if uneven.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {...readonly (string|null|undefined)[]} groups
+ * @returns {Language}
+ */
+export function chooseLanguage(env, ...groups) {
+  const forced = (env[NOTIFY_LANG_ENV] ?? "").trim();
+  if (forced === "pt" || forced === "en") return forced;
+  return detectLanguage(...groups);
+}
+
 /**
  * Every phrase the message renders, per language. Node ids, run ids, model
  * names and quoted text are never here: they are data, not wording.

package/src/report/message.mjs

@@ -24,7 +24,7 @@
  */
 import { renderStatusJson } from "./render.mjs";
 import { buildCampaignProgress, remainingEstimateMs } from "./progress.mjs";
-import { detectLanguage, labelsFor } from "./locale.mjs";
+import { chooseLanguage, labelsFor } from "./locale.mjs";
 import { readNodeSnapshot } from "../run/node-store.mjs";
 import { campaignDir } from "../campaign/layout.mjs";
 import { readJournal } from "../campaign/journal.mjs";
@@ -106,7 +106,7 @@ export function renderRunProgress(runDir, event) {
   const objectives = readObjectives(runDir);
   const snapshots = new Map(payload.nodes.map((node) => [node.id, readSnapshotSafe(runDir, node.id)]));
   const campaign = campaignSummary(runsDir, payload.campaignId);
-  const label = labelsFor(detectLanguage([campaign?.goal], journalTexts(runsDir, payload.campaignId), [...objectives.values()]));
+  const label = labelsFor(chooseLanguage(process.env, [campaign?.goal], journalTexts(runsDir, payload.campaignId), [...objectives.values()]));
   const subject = subjectNode(payload.nodes, event.nodeId ?? null);
   /** @type {View} */
   const view = { runDir, runId: event.runId ?? basename(runDir), payload, objectives, snapshots, campaign, label, subject };