faberun 0.15.0 → 0.16.0

package/package.json

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

@@ -109,18 +109,29 @@ the contract is frozen with a digest, and the phone's middle ground is a note.
 
 ## Notify
 
-On `node.terminal`, `run.terminal` and `attention` the controller renders a
-one-line message from counters and identifiers only (node id, run id, state,
-attempt, error code, done/total — never model text), calls the executable named
-by `FABERUN_NOTIFY_BIN` with that event as JSON on stdin, and appends a
-timestamped receipt (`delivered`, `failed`, `no_transport`) to
+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):
+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
+attention, then a progress bar, a rule and the `🐦 faberun` signature with
+campaign percent, cost and elapsed; an `⬆️` line names a newer release when
+the cached update check has one. ≤2 KiB. It delivers that
+same text to every bound transport at once, appending one receipt
+(`delivered`, `failed`, `no_transport`, one entry per transport) to
 `<run-dir>/notify.jsonl`. Delivery is lossy: **exactly one attempt**, no retry,
-no backoff. Unset, nothing is spawned and the receipt is `no_transport`.
-`FABERUN_NOTIFY_BIN=os-macos` selects the bundled `osascript` adapter
-(`canWake: false`); any other value is an executable path. 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 the variable is empty, and `--wake` reports no adapter can wake a session.
+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
+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.
 Campaign-level lines are queued in `.runs/inbox.jsonl`, the managed block's
 append-only record — one object per line `{schemaVersion, eventId, at, type,
 campaignId, runId, nodeId, status, errorCode, dedupeKey, summary}`, deduped on

package/src/engine/cancel.mjs

@@ -17,7 +17,7 @@ import { terminateInvocation } from "./process.mjs";
 import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { readRunNodes } from "./scheduler.mjs";
-import { deleteRef, releaseAttemptWorktree, runRefName } from "../repo/worktree.mjs";
+import { createPreservedRef, deleteRef, releaseAttemptWorktree, runRefName } from "../repo/worktree.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
 import { transition, writeNode } from "./state.mjs";
 import { validateContract } from "../contract/index.mjs";
@@ -26,10 +26,11 @@ import { writeJsonAtomic } from "../run/store.mjs";
 /** @typedef {import("./process.mjs").InvocationProbe} InvocationProbe */
 /** @typedef {import("../cli.mjs").LockHandle} LockHandle */
 /** @typedef {import("../run/lock.mjs").LockRecord} LockRecord */
+/** @typedef {{preservedRefs: string[], released: string[]}} CancelResult */
 
 /**
  * @param {string} runDirPath
- * @returns {Promise<boolean>}
+ * @returns {Promise<CancelResult>}
  */
 export async function cancelRun(runDirPath) {
   const runDir = resolve(runDirPath);
@@ -108,20 +109,33 @@ export async function cancelRun(runDirPath) {
       throw error;
     }
     if (!await waitForTerminal(runDir, 1_000)) throw new Error("cancel could not confirm a terminal run state");
+    // Preserved refs come first, before anything is released: a cancel that
+    // dies part-way must leave more work reachable, never less. If a creation
+    // fails here, nothing below has run and every integrated commit is as
+    // reachable as cancel found it. A node whose integratedHead is null was
+    // never integrated and gets none.
+    const preservedRefs = states
+      .filter((state) => state.integratedHead)
+      .map((state) => createPreservedRef(contract.cwd, contract.id, state.id, state.integratedHead));
     // The run directory is evidence a campaign ledger may still want, so it
     // stays; the run ref and every node's attempt branch are just git names
     // the next launch of this same contract id needs back, and cancel is the
     // operator saying this run is over. Releasing a name is not destroying a
-    // record -- each state's `worktree.branch`/`commit` fields, and the sha
-    // this ref pointed at, remain in the persisted snapshot regardless.
+    // record: the sha remains in the persisted snapshot, and the commit it
+    // names stays reachable through the preserved ref created above.
     // Idempotent both ways: `removeWorktree` and `deleteRef` already tolerate
     // an artefact a previous cancel (or the run itself) already released.
+    const released = [];
     for (const state of states) {
-      if (state.worktree?.branch) releaseAttemptWorktree(contract.cwd, state.worktree.path, state.worktree.branch);
+      if (!state.worktree?.branch) continue;
+      releaseAttemptWorktree(contract.cwd, state.worktree.path, state.worktree.branch);
+      released.push(`refs/heads/${state.worktree.branch}`);
+      if (state.worktree.path) released.push(state.worktree.path);
     }
     deleteRef(contract.cwd, runRefName(contract.id));
+    released.push(runRefName(contract.id));
     syncAgentSignal(join(runDir, ".."));
-    return true;
+    return { preservedRefs, released };
   } finally {
     controllerLock.release();
   }

package/src/host/preflight.mjs

@@ -27,6 +27,7 @@ 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_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";
@@ -209,9 +210,9 @@ export function environmentPreflight(options) {
  */
 export function notifyTransportCheck(env = process.env) {
   const warning = noTransportWarning(env);
-  return warning
-    ? fail("notify transport", warning, true)
-    : pass("notify transport", `${NOTIFY_BIN_ENV}=${env[NOTIFY_BIN_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)}`);
 }
 
 /** @param {EnvReport} report @returns {EnvCheck[]} the checks that block a dispatch */
@@ -265,6 +266,7 @@ export function declaredVerificationCommands(contract) {
  */
 const SIDE_EFFECT_ENV_KEYS = [
   NOTIFY_BIN_ENV, // a measurement must not notify a human
+  NOTIFY_SESSION_ENV, // nor wake the harness session it was measured from
   "FABERUN_CODEX_BIN", // could redirect the timed command at a live, paid codex binary instead of this repository's own fixtures
   "FABERUN_CLAUDE_BIN", // same, for the claude harness
   "FABERUN_AGY_BIN", // same, for the agy harness

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 };
+  }));
+}

package/src/plan/pipeline.mjs

@@ -607,6 +607,17 @@ export function unresolvedFindings(findings, previousPlan, revisedPlan) {
  * not make — a removed node's writes were reviewed as a removal, not as a
  * silent shrink.
  *
+ * Membership is judged against the whole revised plan, not against the node
+ * that used to hold the path. A revise that splits one node in two and hands
+ * a file to the new sibling has not dropped that file: it is still declared,
+ * still reviewable, and the graph change is visible in the plan. Measured
+ * 2026-09-21 on durable-state-integrity phase 1, where a per-node test made
+ * exactly that move a critical and contested a sound plan — the draft's only
+ * node wrote src/repo/worktree.mjs and src/engine/cancel.mjs, and the revise
+ * layered them into worktree-preserve-ref-verb and
+ * cancel-preserves-integrated-heads, which is the decomposition this
+ * repository's own layering asks for.
+ *
  * @param {PlanOutput|null} previousPlan the plan the revise revised, null when the draft never validated
  * @param {PlanOutput|null} revisedPlan the plan the revise produced, null when its output was refused
  * @returns {PlanFindingOutput[]}
@@ -614,6 +625,7 @@ export function unresolvedFindings(findings, previousPlan, revisedPlan) {
 export function droppedWriteFindings(previousPlan, revisedPlan) {
   if (!previousPlan || !revisedPlan) return [];
   const before = new Map(previousPlan.nodes.map((node) => [node.id, new Set(node.writeFiles)]));
+  const stillDeclared = new Set(revisedPlan.nodes.flatMap((node) => node.writeFiles));
   /** @type {PlanFindingOutput[]} */
   const findings = [];
   for (const node of revisedPlan.nodes) {
@@ -621,13 +633,13 @@ export function droppedWriteFindings(previousPlan, revisedPlan) {
     if (!previousWrites) continue;
     let dropped = 0;
     for (const path of previousWrites) {
-      if (node.writeFiles.includes(path)) continue;
+      if (stillDeclared.has(path)) continue;
       dropped += 1;
       findings.push({
         id: `dropped-write-${node.id}-${dropped}`,
         severity: "critical",
         nodeId: node.id,
-        text: `Node ${node.id} no longer declares ${path} in writeFiles, which the plan this revise revised did declare. Declare it again: the resolution to a scope-closure finding is to declare or acknowledge the dragged-along file, never to drop a write the node needs — a smaller write set clears the same finding while leaving the worker unable to do the work.`,
+        text: `Node ${node.id} no longer declares ${path} in writeFiles, which the plan this revise revised did declare, and no other node in the revised plan declares it either. Declare it again on whichever node owns the work: the resolution to a scope-closure finding is to declare or acknowledge the dragged-along file, never to drop a write the node needs — a smaller write set clears the same finding while leaving the worker unable to do the work. Moving the file to another node is a resolution; removing it from the plan is not.`,
       });
     }
   }

package/src/plan/repo-facts.mjs

@@ -19,6 +19,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { timeVerificationCommands } from "../host/preflight.mjs";
 import { NOTIFY_BIN_ENV } from "../notify/index.mjs";
+import { NOTIFY_SESSION_ENV } from "../notify/session.mjs";
 import { boundedGitSync, gitHead } from "../repo/worktree.mjs";
 
 /** @typedef {import("./spec.mjs").SpecRequirement} SpecRequirement */
@@ -45,6 +46,7 @@ const MEASURE_OUTPUT_CAP_BYTES = 4096;
  */
 const MEASURE_SIDE_EFFECT_ENV_KEYS = [
   NOTIFY_BIN_ENV,
+  NOTIFY_SESSION_ENV,
   "FABERUN_CODEX_BIN",
   "FABERUN_CLAUDE_BIN",
   "FABERUN_AGY_BIN",