faberun 0.17.2 → 0.19.0

package/src/host/platform.mjs

@@ -21,7 +21,9 @@
  * `node.exe` and there is no extensionless file beside it, so a lookup that
  * only joins the bare name reports the running interpreter as missing.
  */
-import { existsSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { Buffer } from "node:buffer";
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readSync, renameSync, rmSync, symlinkSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 
 /**
@@ -109,3 +111,204 @@ function executableCandidates(name) {
   const extensions = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((extension) => extension.trim().toLowerCase()).filter(Boolean);
   return [...extensions.map((extension) => `${name}${extension}`), name];
 }
+
+/** A command script Windows runs through the command interpreter, not directly. */
+const COMMAND_SCRIPT = /\.(?:cmd|bat)$/iu;
+
+/**
+ * How this platform has to be asked to run `executable` with `args`.
+ *
+ * POSIX hands both back untouched. Windows has two problems with the binaries
+ * a harness actually installs as, and both are this function's business so no
+ * caller has to know about either.
+ *
+ * A command name resolves through `PATHEXT`, and `spawn` does not do it: with
+ * only `claude.cmd` on PATH, `spawn("claude")` is ENOENT. So a bare name is
+ * resolved here first.
+ *
+ * And a `.cmd` or `.bat` cannot be spawned directly at all — node refuses it
+ * with EINVAL since the argument-injection fix — so it runs through
+ * `%ComSpec% /d /s /c`. Every argument is quoted for `CommandLineToArgvW` and
+ * then caret-escaped *twice*: the interpreter consumes one layer parsing the
+ * command line, and the `%*` that every npm-written shim forwards its
+ * arguments with consumes the second. Measured 2026-09-20 on Windows 11 —
+ * with one layer, an argument containing `&` is truncated at it; with two,
+ * spaces, quotes, `&`, `|`, `%`, `^`, `()` and `!` all arrive intact.
+ *
+ * A relative executable — `./my-worker.mjs`, the shape a contract names a
+ * wrapped harness by — is relative to the directory the child will run in, and
+ * the caller is the only one who knows it. Without `cwd` the shebang is looked
+ * for beside *this* process instead, found nowhere, and the spawn fails as
+ * EFTYPE with nothing said about why.
+ *
+ * @param {string} executable
+ * @param {string[]} args
+ * @param {{cwd?: string}} [options] the directory the child will run in
+ * @returns {{command: string, args: string[], options: {windowsVerbatimArguments?: boolean}}}
+ */
+export function spawnInvocation(executable, args, options = {}) {
+  if (process.platform !== "win32") return { command: executable, args, options: {} };
+  const named = executable.includes("/") || executable.includes("\\");
+  const resolved = named
+    ? (options.cwd === undefined ? executable : resolve(options.cwd, executable))
+    : (findExecutable(executable) ?? executable);
+  if (COMMAND_SCRIPT.test(resolved)) {
+    const line = [quoteArgument(resolved), ...args.map((argument) => escapeThroughShim(quoteArgument(argument)))].join(" ");
+    return {
+      command: process.env.ComSpec ?? "cmd.exe",
+      args: ["/d", "/s", "/c", `"${line}"`],
+      options: { windowsVerbatimArguments: true },
+    };
+  }
+  const shebang = interpreterOf(resolved);
+  if (shebang) return { command: shebang[0], args: [...shebang.slice(1), resolved, ...args], options: {} };
+  return { command: resolved, args, options: {} };
+}
+
+/**
+ * The interpreter a `#!` line names, or null when the file has none.
+ *
+ * A shebang is a POSIX kernel feature, so Windows hands the same file back as
+ * EFTYPE. Reading the line and running the interpreter is what cross-spawn —
+ * and therefore npm — does on Windows, and it is the only way an executable
+ * handed over as a POSIX script (`FABERUN_CODEX_BIN` pointed at the
+ * extensionless file npm installs beside its `.cmd`, a harness wrapper written
+ * by hand) runs there at all.
+ *
+ * @param {string} path
+ * @returns {string[]|null} the interpreter and its own arguments
+ */
+function interpreterOf(path) {
+  /** @type {number|undefined} */
+  let handle;
+  try {
+    handle = openSync(path, "r");
+    const head = Buffer.alloc(256);
+    const read = readSync(handle, head, 0, 256, 0);
+    const first = head.subarray(0, read).toString("utf8").split(/\r?\n/u, 1)[0];
+    if (!first.startsWith("#!")) return null;
+    const line = first.slice(2).trim();
+    if (!line) return null;
+    // A whole line that names a real file is the interpreter, spaces and all:
+    // every fixture here is written with `#!${process.execPath}`, and on
+    // Windows that is `C:\Program Files\nodejs\node.exe`. Splitting it on
+    // whitespace the POSIX way would ask for `C:\Program`.
+    if (existsSync(line)) return [line];
+    // An interpreter named by a POSIX path that this host does not have:
+    // `#!/bin/sh` is not a file on Windows, but `sh` is a command there
+    // wherever Git for Windows is installed, which is wherever this tool runs.
+    const named = line.includes(" ") ? null : findExecutable(line.slice(line.lastIndexOf("/") + 1));
+    if (named) return [named];
+    // `#!/usr/bin/env node` names the interpreter in its own argument.
+    const parts = line.split(/\s+/u).filter(Boolean);
+    if (!parts.length) return null;
+    if (/(?:^|[\\/])env(?:\.exe)?$/iu.test(parts[0])) return parts.slice(1).length ? parts.slice(1) : null;
+    return parts;
+  } catch {
+    // Unreadable, a directory, or gone: there is no shebang to honour, and the
+    // spawn below reports the real reason.
+    return null;
+  } finally {
+    if (handle !== undefined) closeSync(handle);
+  }
+}
+
+/**
+ * One argument, quoted the way `CommandLineToArgvW` reads it back: a backslash
+ * run before a quote doubles, and a trailing run doubles so the closing quote
+ * survives.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function quoteArgument(value) {
+  return `"${String(value).replace(/(\*)"/gu, '$1$1\\"').replace(/(\+)$/u, "$1$1")}"`;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeThroughShim(value) {
+  return value.replace(/[()%!^"<>&|]/gu, "^$&").replace(/[()%!^"<>&|]/gu, "^$&");
+}
+
+/**
+ * End a process and everything it started, the way this platform can.
+ *
+ * On POSIX the caller passes a negative pid and the kernel signals the whole
+ * process group, which is what every signalling path here already does.
+ * Windows has no process group to signal: `process.kill(pid)` ends that one
+ * process, and the provider a gate spawned — or the `node` a `.cmd` shim
+ * started — keeps running. Measured 2026-09-20: a full suite run on Windows 11
+ * stranded 105 `node -e "setInterval(…)"` fixtures this way, and then hung
+ * waiting for one of them to die.
+ *
+ * `taskkill /T` walks the tree from the pid. `/F` is the only ending Windows
+ * offers a console process, so there is no graceful step to escalate from —
+ * which is why every caller already skips its `SIGKILL` escalation there.
+ * A non-zero exit means no such process, read the way a POSIX `ESRCH` is: the
+ * target is gone, which is not a failure to report.
+ *
+ * @param {number} target a pid, or on POSIX a negative process-group id
+ * @param {string|number} signal
+ * @returns {unknown}
+ */
+export function killTarget(target, signal) {
+  if (process.platform !== "win32") return process.kill(target, signal);
+  const result = spawnSync(join(process.env.SystemRoot ?? "C:\Windows", "System32", "taskkill.exe"), ["/PID", String(Math.abs(target)), "/T", "/F"], { stdio: "ignore" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw Object.assign(new Error(`taskkill found no process ${Math.abs(target)}`), { code: "ESRCH" });
+  return true;
+}
+
+/**
+ * The `git` argument list every invocation here carries.
+ *
+ * **`core.fsmonitor=false`, on every platform.** A repository with the file
+ * system monitor enabled starts `git fsmonitor--daemon --detach` on first use,
+ * and the daemon outlives the directory it watched. This tool creates a
+ * worktree per attempt and its suite creates a throwaway repository per
+ * fixture, so the daemons accumulate: measured 2026-09-20 on Windows 11, one
+ * afternoon of suite runs left **4810** of them holding 39 GB, until the
+ * machine could not start another test process. Nothing here benefits from a
+ * daemon watching a tree that is about to be deleted.
+ *
+ * **`core.longpaths=true`, on Windows.** It caps a path at 260 characters
+ * unless the program opts out, and git's
+ * own `core.longpaths` is off by default even where the OS itself allows long
+ * paths. The run layout is deep on purpose — `projects/<id>/runs/worktrees/
+ * <run>/<node>.<attempt>` before the repository's own tree begins — so a file
+ * a worker writes a few directories down reaches the cap easily.
+ *
+ * What makes this worth a flag on every call is *how* git fails there.
+ * Measured 2026-09-20 on Windows 11, a repository holding one file at a
+ * 268-character path: `git add --all` exits 0 and tracks nothing. With
+ * `core.longpaths=true` it exits 0 and tracks the file. A tool whose gate is
+ * the diff of what a worker changed cannot afford a git that silently cannot
+ * see part of the tree.
+ *
+ * It does not lift every limit: `git worktree add` dies with `'$GIT_DIR' too
+ * big` once the repository's own `.git/worktrees/<name>` path passes about 160
+ * characters, and that guard is a fixed buffer no configuration reaches.
+ *
+ * **`core.autocrlf=false`, on Windows.** The default there is `true`, and it
+ * rewrites line endings on the way into the index and out of a checkout. This
+ * tool's gate is a byte comparison of what a worker changed, and a rewrite it
+ * did not make is indistinguishable from one it did: measured 2026-09-22 on a
+ * GitHub windows-latest runner, a declared read carried into an attempt
+ * worktree came back changed after passing through git, the scope gate called
+ * it an `unexpected_write`, and the adopted node failed for a file nobody had
+ * touched. The attempt worktree is this tool's own directory and its content
+ * is what the run commits; the operator's checkout keeps whatever they
+ * configured.
+ *
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+export function gitArguments(args) {
+  const platformArgs = process.platform === "win32"
+    ? ["-c", "core.longpaths=true", "-c", "core.autocrlf=false"]
+    : [];
+  return ["-c", "core.fsmonitor=false", ...platformArgs, ...args];
+}

package/src/host/preflight.mjs

@@ -8,6 +8,17 @@
  * report as run evidence and stops, so the operator fixes the host and
  * resumes instead of starting over and paying for the finished nodes twice.
  *
+ * A version is not a verdict: a binary that answered `--version` can still
+ * hold a dead credential or a spent quota. With a contract, `doctor` asks
+ * each routed runtime the same live question the dispatch gate asks and
+ * reports that verdict beside the version checks — the `models` surfaces
+ * name this report the authoritative word on availability — and without a
+ * contract it says plainly that it asked nothing. The verdict is the
+ * report, not the gate: a runtime with no answer is a finding on its own
+ * line, while the exit code keeps answering the host-fact question it
+ * always answered, because blocking on silence is the dispatch gate's job
+ * and it blocks on exactly those causes.
+ *
  * A check may be advisory, meaning it reports a fact without blocking: a
  * merely dirty worktree is normal in this repository (the run captures a
  * dirtyTreeFingerprint for it), while unmerged paths or an interrupted git
@@ -18,6 +29,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statfsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, getHarness, probeRuntime } from "../harnesses/index.mjs";
+import { liveSilenceCause } from "../engine/live-silence.mjs";
 import { addRuntimeRequirement, failoverTargets, runtimeSnapshot } from "../engine/failover.mjs";
 import { pricingSeedAge } from "../engine/pricing-seed.mjs";
 import { validateContract } from "../contract/index.mjs";
@@ -26,15 +38,18 @@ 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";
 import { RUNS_DIR_NAME } from "../run/paths.mjs";
+import { availabilityKey, readAvailability, recordAvailability } from "../run/availability.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 /** @typedef {import("../contract/index.mjs").RuntimeSnapshot} RuntimeSnapshot */
 /** @typedef {import("../harnesses/index.mjs").CapabilityRequirements} CapabilityRequirements */
+/** @typedef {import("../harnesses/index.mjs").ProbeResult} ProbeResult */
+/** @typedef {import("../engine/runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
 /** @typedef {Map<string, {runtime: RuntimeSnapshot, requiredCapabilitySets: CapabilityRequirements[]}>} ReachableRuntimes */
 /** @typedef {{name: string, ok: boolean, advisory: boolean, detail: string}} EnvCheck */
 /** @typedef {{schemaVersion: number, ok: boolean, checks: EnvCheck[]}} EnvReport */
@@ -209,10 +224,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 */
@@ -381,6 +399,106 @@ export function reachableRuntimes(contract) {
   return runtimes;
 }
 
+
+/**
+ * Read the live verdict off one `preflightContract` probe, in the detail it
+ * embeds: `… · live <status> · <code>: …` for an ask that failed, and the
+ * repository wording when no runtime could be asked at all. Any verdict a
+ * provider produced — a quota refusal, an auth failure, unparsable output —
+ * is an answer; a silence is a verdict of nothing and is never recorded, so
+ * the operator who fixes the host is never told the fix "already answered".
+ *
+ * @param {ProbeResult} probe
+ * @returns {{answered: boolean, cause: string|null, recorded: boolean}}
+ */
+function liveVerdict(probe) {
+  if (probe.liveStatus === "done") return { answered: true, cause: null, recorded: true };
+  // `liveSilenceCause` is the dispatch gate's own classification, imported
+  // rather than restated. A second copy here had `command_invalid` in it,
+  // which the gate deliberately does not: a command that could not be
+  // constructed never reached a provider, so there is no availability verdict
+  // to report either way. Two copies of this rule is how doctor and the gate
+  // would come to disagree about whether an answer was an answer.
+  const silence = liveSilenceCause(probe);
+  if (silence !== null) return { answered: false, cause: silence, recorded: false };
+  const match = / · live \S+ · ([a-z_]+):/u.exec(probe.detail ?? "");
+  const cause = match?.[1] ?? null;
+  if (cause === null) return { answered: false, cause, recorded: false };
+  return { answered: true, cause, recorded: true };
+}
+
+/**
+ * The live half of `doctor`: the verdict, not the version. The two catalogue
+ * surfaces (`models`, `models --probe`) name this report the authoritative
+ * word on availability, so with a contract doctor asks what the dispatch
+ * gate asks — one trivial prompt per routed runtime through
+ * `preflightContract` — and reports beside the version checks what
+ * answered, naming the cause when nothing did.
+ *
+ * A verdict this machine recorded inside the preflight window is reused
+ * rather than re-bought, and every ask that reached a provider is recorded
+ * in turn: the store (`run/availability.mjs`) is the only cache; none is
+ * built here.
+ *
+ * Every check returned here is advisory. `ok` carries the honest verdict —
+ * false when nothing answered — but the lines never gate `doctor`'s exit
+ * code: the report is where the operator reads what answered, and blocking
+ * on silence is the dispatch gate's decision, made on the same causes. A
+ * doctor that failed on a runtime it could not ask inside its own sandbox
+ * (a relative-executable wrapper) would report the runtime broken when the
+ * actual launch may resolve it fine.
+ *
+ * @param {string} contractPath the authored contract, re-read and re-validated by the ask
+ * @param {ReachableRuntimes} runtimes
+ * @returns {Promise<EnvCheck[]>}
+ */
+async function liveAvailabilityChecks(contractPath, runtimes) {
+  /** @type {Map<string, RuntimeAvailability>} */
+  const fresh = new Map();
+  for (const [id, { runtime }] of runtimes) {
+    const verdict = readAvailability(availabilityKey({
+      harness: runtime.harness,
+      model: runtime.model,
+      executable: getHarness(runtime.harness).executable(runtime),
+    }));
+    if (verdict) fresh.set(id, verdict);
+  }
+  if (runtimes.size > 0 && fresh.size === runtimes.size) {
+    return [...runtimes.keys()].map((id) => {
+      const verdict = /** @type {RuntimeAvailability} */ (fresh.get(id));
+      return {
+        name: `availability ${id}`,
+        ok: true,
+        advisory: true,
+        detail: `answered · verdict reused · observed ${verdict.observedAt ?? "unknown instant"}`,
+      };
+    });
+  }
+  // The ask is imported where it runs: live-preflight imports this module's
+  // reachableRuntimes, so a static edge here would be the runtime import
+  // cycle the source gate bans. At call time both modules are fully
+  // evaluated; this is a plain cache hit, not a cycle.
+  const { preflightContract } = await import("../engine/live-preflight.mjs");
+  // measured 2026-09-22 (dispatch gate): four routed runtimes asked in
+  // parallel took about 18s, so 60s is the budget; FABERUN_PREFLIGHT_TIMEOUT_SEC
+  // is the same operator override the gate honours.
+  const override = Number(process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC);
+  const timeoutSec = process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC !== undefined && Number.isFinite(override) && override > 0 ? override : 60;
+  const probes = await preflightContract(contractPath, { liveTimeoutSec: timeoutSec });
+  recordAvailability(probes.filter((probe) => liveVerdict(probe).recorded).map((probe) => availabilityKey(probe)));
+  return probes.map((probe) => {
+    const verdict = liveVerdict(probe);
+    return {
+      name: `availability ${probe.id ?? probe.harness}`,
+      ok: verdict.answered,
+      advisory: true,
+      detail: verdict.answered
+        ? `answered · ${probe.detail ?? `the provider answered (${verdict.cause})`}`
+        : `no answer · ${probe.detail ?? `cause ${verdict.cause ?? "unknown"}`}`,
+    };
+  });
+}
+
 const HARNESS_BIN_OVERRIDES = Object.freeze({
   codex: "FABERUN_CODEX_BIN",
   claude: "FABERUN_CLAUDE_BIN",
@@ -390,9 +508,17 @@ const HARNESS_BIN_OVERRIDES = Object.freeze({
 });
 
 /**
- * Mutation-free environment doctor: repository prerequisites, ignored .runs,
- * required binaries, the dispatch environment gate, and (when a contract is
- * given) schema and harness versions.
+ * Environment doctor: repository prerequisites, ignored .runs, required
+ * binaries, the dispatch environment gate, and (when a contract is given)
+ * the harness versions beside the live availability verdict per routed
+ * runtime — the report `models` defers to. Without a contract it says
+ * plainly that it asked nothing.
+ *
+ * The exit code answers the host-fact question it always answered: the
+ * live availability lines carry their verdict (false when nothing
+ * answered) but are advisory, because blocking on silence is the dispatch
+ * gate's job and a runtime doctor could not ask inside its own sandbox is
+ * not thereby a runtime the launch cannot run.
  *
  * @param {string|undefined} contractPath
  * @param {{cwd?: string, json?: boolean, discover?: boolean}} values
@@ -400,7 +526,7 @@ const HARNESS_BIN_OVERRIDES = Object.freeze({
  */
 export async function doctorCommand(contractPath, values) {
   const repoDir = resolve(values.cwd ?? ".");
-  /** @type {{name: string, ok: boolean, detail: string}[]} */
+  /** @type {{name: string, ok: boolean, advisory?: boolean, detail: string}[]} */
   const checks = [];
   const gitRepo = isGitWorkTree(repoDir);
   checks.push({ name: "git repository", ok: gitRepo, detail: gitRepo ? repoDir : "not inside a git work tree" });
@@ -454,6 +580,10 @@ export async function doctorCommand(contractPath, values) {
         harnessVersions[id] = probe.version;
         checks.push({ name: `harness ${probe.id ?? runtime.harness}`, ok: probe.ok, detail: probe.detail ?? (probe.ok ? "ok" : "probe failed") });
       }
+      // The verdict beside the version: a binary that answered --version is
+      // not thereby a provider that answered, and the report names which of
+      // the two failed because the remedies differ.
+      checks.push(...await liveAvailabilityChecks(absolute, runtimes));
     } catch (error) {
       checks.push({ name: "contract", ok: false, detail: errorMessage(error) });
     }
@@ -494,7 +624,12 @@ export async function doctorCommand(contractPath, values) {
   for (const check of environmentPreflight({ cwd: dispatchCwd, runtimes: routedRuntimes, harnessVersions }).checks) {
     checks.push({ name: check.name, ok: check.ok || check.advisory, detail: check.ok ? check.detail : `${check.detail} (advisory)` });
   }
-  const ok = checks.every((check) => check.ok);
+  // The live availability lines never gate the verdict: a no-answer is the
+  // finding it is on its own line (ok false, cause named), and what still
+  // fails doctor is every host fact and static probe — which is why the
+  // nonexistent-binary case below exits non-zero while a merely silent
+  // provider does not.
+  const ok = checks.every((check) => check.ok || check.advisory === true);
   const transportWarning = noTransportWarning(process.env);
   if (transportWarning) process.stderr.write(`${statusToken("warn", colorLevel(process.env, process.stderr.isTTY))} ${transportWarning}\n`);
   if (values.json === true) {

package/src/notify/index.mjs

@@ -51,6 +51,7 @@ import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, writeSync
 import { join } from "node:path";
 import { createMacosNotifier } from "./os-macos.mjs";
 import { NOTIFY_SESSION_ENV, deliverToSessions, resolveSessionTargets, sessionWakeNotice } from "./session.mjs";
+import { spawnInvocation } from "../host/platform.mjs";
 import { errorMessage } from "../util.mjs";
 
 /**
@@ -86,7 +87,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 +209,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 */
 
@@ -432,7 +485,12 @@ function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = notificati
   return new Promise((resolveDelivery) => {
     let child;
     try {
-      child = spawn(bin, [], { stdio: ["pipe", "ignore", "pipe"], env: process.env });
+      // The transport is whatever the operator bound, and on Windows that is
+      // rarely an .exe: a `.cmd` shim npm wrote, or a script whose shebang
+      // names its interpreter. Either spawns as EFTYPE unhandled, which is a
+      // notification that silently never arrives.
+      const invocation = spawnInvocation(bin, []);
+      child = spawn(invocation.command, invocation.args, { stdio: ["pipe", "ignore", "pipe"], env: process.env, ...invocation.options });
     } catch (error) {
       resolveDelivery({ ok: false, error: errorMessage(error) });
       return;
@@ -503,14 +561,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 +591,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`);
   }
 }