faberun 0.15.0 → 0.17.0

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",

package/src/repo/signal.mjs

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

package/src/repo/worktree.mjs

@@ -104,6 +104,11 @@ export function candidateRefName(runId) {
   return `refs/faberun/${runId}/candidate`;
 }
 
+/** @param {string} runId @param {string} nodeId @returns {string} */
+export function preservedRefName(runId, nodeId) {
+  return `refs/faberun/${runId}/preserved/${nodeId}`;
+}
+
 /** @param {string} runId @param {string} nodeId @param {number} attempt @returns {string} */
 function attemptBranchName(runId, nodeId, attempt) {
   return `faberun/${runId}/${nodeId}/${attempt}`;
@@ -168,6 +173,29 @@ export function createRunRef(repo, runId, head) {
   return ref;
 }
 
+/**
+ * Keep one node's integrated commit reachable after cancel releases the run
+ * ref and the attempt branches: without a ref of its own the commit is
+ * garbage the next `git gc` collects, and the persisted snapshot alone cannot
+ * bring a pruned object back.
+ *
+ * Idempotent by the same contract `deleteRef` and `removeWorktree` honour:
+ * cancel can legitimately run twice (a retry after a partial first pass, or
+ * the operator repeating it), so a preserved ref that already names this
+ * exact commit is done, not a conflict — the second creation neither fails
+ * nor moves the target. A ref left at a different sha moves to the commit
+ * handed in now.
+ *
+ * @param {string} repo @param {string} runId @param {string} nodeId @param {string|null|undefined} sha @returns {string}
+ */
+export function createPreservedRef(repo, runId, nodeId, sha) {
+  if (!sha) throw Object.assign(new Error("a preserved ref needs an integrated commit"), { code: "git_head_required" });
+  const ref = preservedRefName(runId, nodeId);
+  if (gitHead(repo, ref) === sha) return ref;
+  runGit(["-C", repo, "update-ref", ref, sha]);
+  return ref;
+}
+
 /**
  * @param {{repo: string, runDir: string, runId: string, nodeId: string, attempt: number, base?: string, declaredReads?: string[]}} args
  *   `base` cuts the new branch from a sealed sha instead of the run ref tip —

package/src/report/locale.mjs

@@ -0,0 +1,164 @@
+/**
+ * The language of a notification, and the labels it is written in.
+ *
+ * The controller never sees the operator's conversation with a harness; it
+ * sees what the operator wrote for faberun: the campaign goal, the journal
+ * notes and the objectives the plan gave each node. Those are the operator's
+ * prompts to this product, and a message that answers them in the same
+ * language reads as a reply rather than a log line. Detection is a count of
+ * function words in the two languages this product's operators write in;
+ * anything else, or nothing to read, is English. Quoted content -- the
+ * worker's own words, a judge finding -- keeps the language it was written
+ * in, because translating a quotation would make it stop being one.
+ *
+ * It is a module apart from `message.mjs` so the layout and the wording can
+ * change independently: a new label is one line here, a new line is one
+ * function there.
+ */
+
+/** @typedef {"en"|"pt"} Language */
+
+// `a`, `do` and `no` are left out on purpose: each is also an English word,
+// and one article in an English sentence must not read as Portuguese.
+const PORTUGUESE = new Set(["o", "e", "de", "da", "na", "que", "não", "nao", "para", "com", "uma", "um", "em", "os", "as", "dos", "das", "é", "se", "por", "mais", "como", "mas", "ao", "ou", "quando", "já", "também", "ser", "sem", "até", "cada", "nunca", "está", "são", "foi", "pelo", "pela", "nos", "nas", "seu", "sua", "isso", "esse", "essa", "ele", "ela"]);
+const ENGLISH = new Set(["the", "and", "of", "to", "in", "is", "for", "with", "that", "on", "as", "are", "this", "it", "be", "by", "from", "or", "an", "not", "at", "when", "every", "never", "before", "after", "its", "into", "than", "which", "while", "each", "was", "has", "have"]);
+
+/**
+ * The language of the first group of samples that carries any function word
+ * at all, English when none does. Groups are passed in order of authorship:
+ * the campaign goal is the operator's own sentence, the journal notes are the
+ * orchestrating session's, the node objectives are the planner's -- and a
+ * plan written by a model in English must not outvote the person who typed
+ * the goal in Portuguese (measured 2026-09-21: two node objectives held 40
+ * English function words against a Portuguese goal's 19).
+ *
+ * @param {...readonly (string|null|undefined)[]} groups
+ * @returns {Language}
+ */
+export function detectLanguage(...groups) {
+  for (const samples of groups) {
+    let portuguese = 0;
+    let english = 0;
+    for (const sample of samples) {
+      if (typeof sample !== "string") continue;
+      for (const word of sample.toLowerCase().split(/[^\p{L}]+/u)) {
+        if (PORTUGUESE.has(word)) portuguese += 1;
+        else if (ENGLISH.has(word)) english += 1;
+      }
+    }
+    if (portuguese + english > 0) return portuguese > english ? "pt" : "en";
+  }
+  return "en";
+}
+
+/**
+ * Every phrase the message renders, per language. Node ids, run ids, model
+ * names and quoted text are never here: they are data, not wording.
+ *
+ * @type {Record<Language, Record<string, string>>}
+ */
+const LABELS = {
+  en: {
+    doneIn: "done in",
+    running: "running",
+    pending: "pending",
+    state: "state",
+    nothingDelivered: "nothing delivered",
+    "no-op": "no-op after",
+    failedAfter: "failed after",
+    blockedAfter: "blocked after",
+    exhaustedAfter: "exhausted after",
+    stalledAfter: "stalled after",
+    canceledAfter: "canceled after",
+    needsYou: "needs you",
+    attempt: "attempt",
+    run: "run",
+    done: "done",
+    asked: "asked",
+    did: "done",
+    proof: "proof",
+    delivered: "delivered",
+    why: "why",
+    do: "do",
+    judge: "judge",
+    missing: "missing",
+    error: "error",
+    checksGreen: "checks green",
+    checksOf: "checks passed",
+    judgePass: "judge pass",
+    judgePasses: "judge passes",
+    judgeRejected: "judge rejected",
+    noJudge: "no judge",
+    revisions: "revisions",
+    nodes: "nodes",
+    next: "next",
+    waitingOnYou: "waiting on you",
+    phases: "phases",
+    cache: "cache",
+    in: "in",
+    out: "out",
+    nextCommand: "next",
+    available: "available",
+    runUpdate: "run",
+    noSummary: "(no summary recorded)",
+    noObjective: "(no objective recorded)",
+    more: "more",
+    complete: "complete",
+  },
+  pt: {
+    doneIn: "concluído em",
+    running: "rodando",
+    pending: "pendente",
+    state: "estado",
+    nothingDelivered: "nada entregue",
+    "no-op": "sem mudança após",
+    failedAfter: "falhou após",
+    blockedAfter: "bloqueado após",
+    exhaustedAfter: "esgotado após",
+    stalledAfter: "travou após",
+    canceledAfter: "cancelado após",
+    needsYou: "precisa de você",
+    attempt: "tentativa",
+    run: "run",
+    done: "concluídos",
+    asked: "pedido",
+    did: "feito",
+    proof: "prova",
+    delivered: "entregue",
+    why: "motivo",
+    do: "ação",
+    judge: "juiz",
+    missing: "faltou",
+    error: "erro",
+    checksGreen: "checagens verdes",
+    checksOf: "checagens passaram",
+    judgePass: "juiz aprovou",
+    judgePasses: "aprovações do juiz",
+    judgeRejected: "juiz rejeitou",
+    noJudge: "sem juiz",
+    revisions: "revisões",
+    nodes: "nós",
+    next: "próximo",
+    waitingOnYou: "esperando você",
+    phases: "fases",
+    cache: "cache",
+    in: "entrada",
+    out: "saída",
+    nextCommand: "próximo passo",
+    available: "disponível",
+    runUpdate: "rode",
+    noSummary: "(sem resumo registrado)",
+    noObjective: "(sem objetivo registrado)",
+    more: "mais",
+    complete: "completa",
+  },
+};
+
+/**
+ * @param {Language} language
+ * @returns {(key: string) => string}
+ */
+export function labelsFor(language) {
+  const table = LABELS[language];
+  return (key) => table[key] ?? LABELS.en[key] ?? key;
+}