faberun 0.14.0 → 0.16.0

package/src/notify/index.mjs

@@ -1,15 +1,19 @@
 /**
  * Direct notification dispatcher (TECH-SPEC lean, rule 6). On `node.terminal`,
  * `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
- * make. The next read of the run's own artefacts carries the full state. With
- * no transport bound (`FABERUN_NOTIFY_BIN` unset) nothing is spawned and
- * a `no_transport` receipt is recorded instead — there is no implicit desktop
+ * `renderRunProgress` (`report/message.mjs`) from the run's own persisted
+ * state, delivers that one text to every bound transport at once, and appends
+ * one receipt (`delivered`, `failed` or `no_transport`, with the timestamp
+ * and one entry per transport) to `<run-dir>/notify.jsonl`. Two transports
+ * exist, additive and independently opted in: `FABERUN_NOTIFY_BIN`, an
+ * executable called with the event as JSON on stdin (a phone, a chat), and
+ * `FABERUN_NOTIFY_SESSION`, the harness session the controller was launched
+ * from (`session.mjs`), which is what wakes the operator's seat. Delivery is
+ * lossy: an event is attempted once per transport, a failure schedules no
+ * further attempt and is never requeued, and the controller never waits on a
+ * retry it will not make. The next read of the run's own artefacts carries
+ * the full state. With no transport bound nothing is spawned and a
+ * `no_transport` receipt is recorded instead — there is no implicit desktop
  * fallback. The macOS notifier is reachable only by setting
  * `FABERUN_NOTIFY_BIN=os-macos`, an explicit opt-in, never a default.
  *
@@ -46,24 +50,25 @@ 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 { errorMessage } from "../util.mjs";
 
 /**
- * `report/progress.mjs` reaches back to this module (through
+ * `report/message.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
+ * `report/message.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}
+ * @type {Promise<typeof import("../report/message.mjs")>|null}
  */
 let progressModule = null;
-/** @returns {Promise<typeof import("../report/progress.mjs")>} */
+/** @returns {Promise<typeof import("../report/message.mjs")>} */
 function loadProgressModule() {
-  progressModule ??= import("../report/progress.mjs");
+  progressModule ??= import("../report/message.mjs");
   return progressModule;
 }
 
@@ -129,7 +134,8 @@ export const NOTIFY_NO_TRANSPORT_WARNING = "no human notification transport is c
 /** @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 {{ok: boolean, error?: string, noTransport?: boolean}} DeliveryResult */
+/** @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 */
 
 /**
  * Render the message for an event. For `node.terminal`, `run.terminal` and
@@ -250,25 +256,31 @@ function truncate(value) {
  * @returns {string|null}
  */
 export function noTransportWarning(env = process.env) {
-  return env[NOTIFY_BIN_ENV] ? null : NOTIFY_NO_TRANSPORT_WARNING;
+  if (env[NOTIFY_BIN_ENV]) return null;
+  if (resolveSessionTargets(env).length) return null;
+  return NOTIFY_NO_TRANSPORT_WARNING;
 }
 
 /**
- * What `campaign watch --wake` must say about waking. No adapter declares
- * `canWake: true` (`os-macos` is `canWake: false`), so the wake verb records
- * to the inbox and the managed block and never implies a session was woken.
+ * What `campaign watch --wake` must say about waking. The external transport
+ * never wakes anything (`os-macos` and every `FABERUN_NOTIFY_BIN` executable
+ * are `canWake: false`: they push to a person); the session transports are
+ * the only `canWake: true`, and the notice says which of them the environment
+ * resolves to, so the verb never implies a session was woken when none will be.
  *
  * @param {string|undefined} [bin]
+ * @param {NodeJS.ProcessEnv} [env]
  * @returns {string}
  */
-export function wakeCapabilityNotice(bin = process.env[NOTIFY_BIN_ENV]) {
+export function wakeCapabilityNotice(bin = process.env[NOTIFY_BIN_ENV], env = process.env) {
+  const session = sessionWakeNotice(env);
   if (!bin) {
-    return "no notify transport is configured; --wake records to .runs/inbox.jsonl and the AGENTS.md managed block; no session is woken";
+    return `no external notify transport is configured; --wake records to .runs/inbox.jsonl and the AGENTS.md managed block; ${session}`;
   }
   if (bin === MACOS_TRANSPORT) {
-    return "os-macos cannot wake a session (canWake: false); --wake records to .runs/inbox.jsonl and the AGENTS.md managed block";
+    return `os-macos cannot wake a session (canWake: false); --wake records to .runs/inbox.jsonl and the AGENTS.md managed block; ${session}`;
   }
-  return `notify transport ${bin} declares canWake: false; --wake records to .runs/inbox.jsonl and the AGENTS.md managed block; no session is woken`;
+  return `notify transport ${bin} declares canWake: false; --wake records to .runs/inbox.jsonl and the AGENTS.md managed block; ${session}`;
 }
 
 /** @param {string} runsDir @returns {string} */
@@ -345,20 +357,39 @@ export function appendInbox(runsDir, event) {
 }
 
 /**
- * Deliver one event through the bound transport. No transport bound resolves
- * `{ok: false, noTransport: true}` without spawning anything.
+ * Deliver one event through every bound transport at once: the external
+ * executable and each resolved harness session, all given the same rendered
+ * text. The result is `ok` when any one of them took the message, carries
+ * every transport's own outcome for the receipt, and is
+ * `{ok: false, noTransport: true}` when nothing at all is bound -- without
+ * spawning or connecting anything.
  *
  * @param {{type: string, summary: string, campaignId?: string|null, [key: string]: unknown}} event
- * @param {{bin?: string, spawn?: typeof defaultSpawn, timeoutMs?: number}} [options]
+ * @param {{bin?: string, env?: NodeJS.ProcessEnv, spawn?: typeof defaultSpawn, timeoutMs?: number}} [options]
  * @returns {Promise<DeliveryResult>}
  */
-function deliverNotification(event, options = {}) {
-  const bin = options.bin ?? process.env[NOTIFY_BIN_ENV];
-  if (!bin) return Promise.resolve({ ok: false, noTransport: true });
-  if (bin === MACOS_TRANSPORT) {
-    return createMacosNotifier({ spawn: options.spawn }).deliver(/** @type {any} */ (event));
+async function deliverNotification(event, options = {}) {
+  const env = options.env ?? process.env;
+  const bin = options.bin ?? env[NOTIFY_BIN_ENV];
+  const targets = resolveSessionTargets(env);
+  /** @type {Promise<TransportOutcome>[]} */
+  const attempts = [];
+  if (bin) {
+    const external = bin === MACOS_TRANSPORT
+      ? createMacosNotifier({ spawn: options.spawn }).deliver(/** @type {any} */ (event))
+      : spawnDeliver(bin, event, options);
+    attempts.push(external.then((result) => ({ id: bin === MACOS_TRANSPORT ? MACOS_TRANSPORT : "bin", ...result })));
   }
-  return spawnDeliver(bin, event, options);
+  /** @type {Promise<TransportOutcome[]>} */
+  const sessions = targets.length ? deliverToSessions(event, targets, { timeoutMs: options.timeoutMs, env }) : Promise.resolve([]);
+  if (!attempts.length && !targets.length) return { ok: false, noTransport: true, transports: [] };
+  const transports = [...(await Promise.all(attempts)), ...(await sessions)];
+  const failures = transports.filter((outcome) => !outcome.ok).map((outcome) => `${outcome.id}: ${outcome.error ?? "failed"}`);
+  return {
+    ok: transports.some((outcome) => outcome.ok),
+    ...(failures.length ? { error: failures.join("; ") } : {}),
+    transports,
+  };
 }
 
 /**
@@ -472,6 +503,9 @@ export class NotifyQueue {
       summary,
       attempt: 1,
       status: 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;

package/src/notify/session.mjs

@@ -0,0 +1,240 @@
+/**
+ * The session transports: the channel that wakes the harness session an
+ * operator is sitting in, rather than a phone.
+ *
+ * A controller launched from inside a Claude Code or Codex session inherits
+ * that session's own address. Claude Code exports `CLAUDE_CODE_MESSAGING_SOCKET`
+ * (a Unix socket, the session's inbox) and `CLAUDE_CODE_MESSAGING_TOKEN` to
+ * every Bash command and hook it runs; Codex exports `CODEX_THREAD_ID` and
+ * accepts `codex queue --thread <id> --message <text>` for a running thread.
+ * Posting the rendered message there is what `canWake: true` means: the
+ * session gets a turn and reads the same text the phone gets, so the two
+ * never differ. It is a module apart from `index.mjs` because that module is
+ * the dispatcher and the receipt log; this one knows two wire protocols and
+ * nothing about receipts.
+ *
+ * Measured 2026-09-21 against a live Claude Code 2.1.269 session: the inbox
+ * accepts `{"type":"auth","token"}` and then
+ * `{"type":"user","message":{"role":"user","content"}}`, one JSON object per
+ * line, answers nothing, and delivered the line to the session mid-turn; the
+ * session closes a connection that has not sent a complete line within 30 s.
+ * The token is what lets the session verify a poster whose process has
+ * already exited (macOS cannot check process ancestry after exit), so it is
+ * always sent when present and never logged.
+ *
+ * Opt-in by `FABERUN_NOTIFY_SESSION`, never by detection alone: a test suite
+ * running inside a session would otherwise wake it on every fixture's
+ * terminal node, the hazard `FABERUN_NOTIFY_BIN` already has and guards
+ * against. The seat sets the variable to `auto` on the window it launches, so
+ * everything under a seat inherits the opt-in and nothing else does.
+ */
+import { spawn as defaultSpawn } from "node:child_process";
+import { createConnection as defaultConnect } from "node:net";
+import { errorMessage } from "../util.mjs";
+
+export const NOTIFY_SESSION_ENV = "FABERUN_NOTIFY_SESSION";
+export const CLAUDE_SOCKET_ENV = "CLAUDE_CODE_MESSAGING_SOCKET";
+export const CLAUDE_TOKEN_ENV = "CLAUDE_CODE_MESSAGING_TOKEN";
+export const CODEX_THREAD_ENV = "CODEX_THREAD_ID";
+
+/**
+ * Measured 2026-09-21: one post to a live inbox completed well under a
+ * second, and Claude Code's own peer sender gives up at 5 s; the same budget
+ * `index.mjs` gives an external transport.
+ */
+export const SESSION_DELIVERY_TIMEOUT_MS = 5_000;
+
+/** The values the variable accepts besides `codex:<thread>`. */
+const SETTINGS = new Set(["off", "auto", "claude", "codex"]);
+
+/** @typedef {Record<string, unknown>} JsonObject */
+/** @typedef {{kind: "claude", id: "claude-session", socketPath: string, token: string|null}} ClaudeTarget */
+/** @typedef {{kind: "codex", id: "codex-session", thread: string}} CodexTarget */
+/** @typedef {ClaudeTarget|CodexTarget} SessionTarget */
+/** @typedef {{type: string, summary?: unknown, campaignId?: unknown, runId?: unknown, nodeId?: unknown}} SessionEvent */
+/** @typedef {{ok: boolean, error?: string}} SessionDelivery */
+/** @typedef {{once(event: string, listener: (...args: any[]) => void): unknown, kill(signal?: any): unknown, stderr?: {on(event: string, listener: (chunk: string|Buffer) => void): unknown}|null}} SpawnedChild */
+/** @typedef {(command: string, args?: any, options?: any) => SpawnedChild} SpawnFunction */
+/** @typedef {{once(event: string, listener: (...args: any[]) => void): unknown, end(data: string, callback?: () => void): unknown, destroy(): unknown}} SessionSocket */
+/** @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.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {SessionTarget[]}
+ */
+export function resolveSessionTargets(env = process.env) {
+  const setting = (env[NOTIFY_SESSION_ENV] ?? "").trim();
+  if (!setting || setting === "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 });
+  }
+  return targets;
+}
+
+/**
+ * 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.
+ *
+ * @param {NodeJS.ProcessEnv} [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>`;
+  }
+  if (resolveSessionTargets(env).length) return null;
+  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`;
+}
+
+/**
+ * What `campaign watch --wake` and `doctor` say about waking a session.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function sessionWakeNotice(env = process.env) {
+  const targets = resolveSessionTargets(env);
+  if (targets.length) {
+    return `session transport ${targets.map((target) => target.id).join(" + ")} wakes the launching harness session (canWake: true)`;
+  }
+  const problem = sessionSettingProblem(env);
+  if (problem) return `${problem}; no harness session is woken`;
+  return `${NOTIFY_SESSION_ENV} unset: no harness session is woken (a seat window sets it to auto)`;
+}
+
+/**
+ * The text a session reads: the rendered summary, whose first line already
+ * names the sender; a counters-only fallback for an event that reaches a
+ * transport unrendered.
+ *
+ * @param {SessionEvent} event
+ * @returns {string}
+ */
+function messageText(event) {
+  if (typeof event.summary === "string" && event.summary.trim()) return event.summary;
+  return ["🐦 faberun", event.type, event.campaignId, event.runId, event.nodeId].filter((part) => typeof part === "string" && part).join(" · ");
+}
+
+/**
+ * @param {{connect?: ConnectFunction, timeoutMs?: number}} [options]
+ * @returns {{id: "claude-session", capabilities: {canPush: boolean, canWake: boolean, canRenderAmbient: boolean}, deliver(event: SessionEvent, target: ClaudeTarget): Promise<SessionDelivery>}}
+ */
+export function createClaudeSessionNotifier({ connect = /** @type {ConnectFunction} */ (defaultConnect), timeoutMs = SESSION_DELIVERY_TIMEOUT_MS } = {}) {
+  return {
+    id: "claude-session",
+    capabilities: { canPush: false, canWake: true, canRenderAmbient: false },
+    deliver(event, target) {
+      return new Promise((resolve) => {
+        /** @type {string[]} */
+        const lines = [];
+        if (target.token) lines.push(JSON.stringify({ type: "auth", token: target.token }));
+        lines.push(JSON.stringify({ type: "user", message: { role: "user", content: messageText(event) } }));
+        let socket;
+        try {
+          socket = connect(target.socketPath);
+        } catch (error) {
+          resolve({ ok: false, error: errorMessage(error) });
+          return;
+        }
+        let settled = false;
+        /** @param {SessionDelivery} result */
+        const finish = (result) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve(result);
+        };
+        const timer = setTimeout(() => {
+          socket.destroy();
+          finish({ ok: false, error: `session inbox ${target.socketPath} did not take the message within ${timeoutMs}ms` });
+        }, timeoutMs);
+        socket.once("error", (error) => finish({ ok: false, error: errorMessage(error) }));
+        // The inbox answers nothing, so a flushed write and a clean close is
+        // the whole evidence of delivery there is.
+        socket.once("connect", () => socket.end(`${lines.join("\n")}\n`, () => finish({ ok: true })));
+      });
+    },
+  };
+}
+
+/**
+ * @param {{spawn?: SpawnFunction, timeoutMs?: number, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {{id: "codex-session", capabilities: {canPush: boolean, canWake: boolean, canRenderAmbient: boolean}, deliver(event: SessionEvent, target: CodexTarget): Promise<SessionDelivery>}}
+ */
+export function createCodexSessionNotifier({ spawn = /** @type {SpawnFunction} */ (defaultSpawn), timeoutMs = SESSION_DELIVERY_TIMEOUT_MS, env = process.env } = {}) {
+  return {
+    id: "codex-session",
+    capabilities: { canPush: false, canWake: true, canRenderAmbient: false },
+    deliver(event, target) {
+      return new Promise((resolve) => {
+        const executable = env.FABERUN_CODEX_BIN ?? "codex";
+        let child;
+        try {
+          child = spawn(executable, ["queue", "--thread", target.thread, "--message", messageText(event)], { stdio: ["ignore", "ignore", "pipe"], env });
+        } catch (error) {
+          resolve({ ok: false, error: errorMessage(error) });
+          return;
+        }
+        let settled = false;
+        let stderr = "";
+        /** @param {SessionDelivery} result */
+        const finish = (result) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve(result);
+        };
+        const timer = setTimeout(() => {
+          try {
+            child.kill("SIGTERM");
+          } catch {
+            // ESRCH: the child already exited before the timeout kill; finish still resolves.
+          }
+          finish({ ok: false, error: `codex queue did not return within ${timeoutMs}ms` });
+        }, timeoutMs);
+        child.stderr?.on("data", (chunk) => {
+          stderr = `${stderr}${chunk}`.slice(-1024);
+        });
+        child.once("error", (error) => finish({ ok: false, error: errorMessage(error) }));
+        child.once("exit", (code) => finish(code === 0 ? { ok: true } : { ok: false, error: stderr.trim() || `codex queue exited ${code}` }));
+      });
+    },
+  };
+}
+
+/**
+ * Deliver one event to every resolved session, each through its own adapter,
+ * and report per target: the receipt names which session took the message.
+ *
+ * @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}[]>}
+ */
+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 };
+  }));
+}