faberun 0.14.0 → 0.16.0

package/src/report/packet-repetition.mjs

@@ -0,0 +1,121 @@
+/**
+ * Packet repetition between a node's successive attempts — the R16
+ * measurement the deduplication decision waits for, and nothing more: this
+ * module counts bytes; it never deduplicates or reshapes a payload.
+ *
+ * It is a module of its own because render.mjs sits at the repository's
+ * 800-line ceiling (measured 2026-09-21: render.mjs 799, progress.mjs 724,
+ * final.mjs 202): the renderers gain a single line each, the computation
+ * lives here.
+ *
+ * A node's packet, per attempt, is the prompt file its worker invocation was
+ * dispatched with (`invocation.promptPath`) — the only per-attempt packet
+ * bytes a run persists. Paths resolve against the run directory; an absolute
+ * path is taken as written. "Repeated" between two successive attempts is
+ * their common byte prefix: the share a retry re-sends identically, the
+ * number a deduplication or prefix-cache decision would act on. A packet
+ * file that cannot be read leaves its attempt absent from the measurement —
+ * absent is never zero — and `packetsRead` beside `attempts` is how a reader
+ * sees the gap.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { compactTokens } from "../util.mjs";
+
+/**
+ * @typedef {{attempts: number, packetsRead: number, packetBytes: number|null, repeatedBytes: number|null}} PacketRepetition
+ * `packetBytes` sums the packets that were readable; `repeatedBytes` sums the
+ * common prefix of each *adjacent* worker-invocation pair whose both packets
+ * were readable — `null` when no pair was measurable. When `packetsRead` is
+ * smaller than `attempts`, the totals cover only the packets still on disk.
+ */
+
+/**
+ * Per node, from the invocation ledger alone, in contract order.
+ *
+ * @param {string} runDir
+ * @param {{id: string, invocations?: unknown}[]} nodes
+ * @returns {Map<string, PacketRepetition>}
+ */
+export function packetRepetitionByNode(runDir, nodes) {
+  return new Map(nodes.map((node) => [node.id, packetRepetition(runDir, node.invocations)]));
+}
+
+/**
+ * @param {string} runDir
+ * @param {unknown} invocations
+ * @returns {PacketRepetition}
+ */
+function packetRepetition(runDir, invocations) {
+  const ledger = Array.isArray(invocations) ? /** @type {Record<string, unknown>[]} */ (invocations) : [];
+  const workerPackets = ledger
+    .filter((invocation) => /** @type {{role?: unknown}} */ (invocation)?.role === "worker")
+    .map((invocation) => (typeof /** @type {{promptPath?: unknown}} */ (invocation).promptPath === "string"
+      ? readPacket(runDir, /** @type {string} */ (/** @type {{promptPath?: unknown}} */ (invocation).promptPath))
+      : null));
+  let repeatedBytes = /** @type {number|null} */ (null);
+  for (let index = 1; index < workerPackets.length; index += 1) {
+    const previous = workerPackets[index - 1];
+    const current = workerPackets[index];
+    // A gap in the ledger's packets breaks the pair rather than pairing
+    // across it: attempts i-1 and i+1 are not successive.
+    if (previous === null || current === null) continue;
+    repeatedBytes = (repeatedBytes ?? 0) + sharedPrefixBytes(previous, current);
+  }
+  const readable = workerPackets.filter((packetBytes) => packetBytes !== null);
+  return {
+    attempts: workerPackets.length,
+    packetsRead: readable.length,
+    packetBytes: readable.length ? readable.reduce((total, packet) => total + /** @type {Buffer} */ (packet).length, 0) : null,
+    repeatedBytes,
+  };
+}
+
+/**
+ * @param {string} runDir
+ * @param {string} promptPath
+ * @returns {Buffer|null}
+ */
+function readPacket(runDir, promptPath) {
+  try {
+    return readFileSync(resolve(runDir, promptPath));
+  } catch {
+    // A prompt file the run no longer carries (pruned, or a fixture's
+    // placeholder path) leaves that attempt absent from the measurement
+    // rather than counted as zero bytes; `packetsRead` shows the gap.
+    return null;
+  }
+}
+
+/** @param {Buffer} left @param {Buffer} right @returns {number} */
+function sharedPrefixBytes(left, right) {
+  const max = Math.min(left.length, right.length);
+  let index = 0;
+  while (index < max && left[index] === right[index]) index += 1;
+  return index;
+}
+
+/**
+ * The report's one-line exposure, appended to a totals line: per node with
+ * two or more attempts on record, the bytes its successive attempts re-sent
+ * identically of the packet bytes those attempts carried. A node with a
+ * single attempt has no successive pair and is rightly absent; a node whose
+ * packets cannot be read says `unmeasured` rather than a zero; a node whose
+ * measurement covers only some of its packets says `partial`.
+ *
+ * @param {Map<string, PacketRepetition>} repetition
+ * @returns {string} "" when no node has a successive pair to expose
+ */
+export function packetRepetitionNote(repetition) {
+  const parts = [];
+  for (const [id, measured] of repetition) {
+    if (measured.attempts < 2) continue;
+    if (measured.repeatedBytes === null || measured.packetBytes === null) {
+      parts.push(`${id} unmeasured`);
+      continue;
+    }
+    const partial = measured.packetsRead < measured.attempts ? " (partial)" : "";
+    parts.push(`${id} ${compactTokens(measured.repeatedBytes)} of ${compactTokens(measured.packetBytes)}${partial}`);
+  }
+  return parts.length ? ` · packet repeat across attempts: ${parts.join(" · ")}` : "";
+}

package/src/report/progress.mjs

@@ -1,14 +1,8 @@
 /**
- * Two renderers sharing one module, so a notification and a campaign page can
- * never disagree about progress:
- *
- * `renderRunProgress` -- one message for a human, from a run's persisted
- * state plus one terminal event: campaign, phase and node with a glyph for
- * the node's outcome; percent and count done and left; this node's own span;
- * the phase's estimated remaining time, from settled spans alone; the next
- * node in the phase, or that the phase is complete; what the node delivered,
- * in the worker's own words; and cost by role plus the campaign's cumulative
- * cost.
+ * The campaign roll-up, and the numbers it shares with the notification
+ * message (`message.mjs`): the roll-up object itself, the remaining-time
+ * estimate and a node's span are exported from here and imported there, so
+ * the page and the message can never disagree about progress, cost or time.
  *
  * `renderCampaignProgress` -- the campaign-wide roll-up, answering the
  * owner's four questions from persisted state alone: what the campaign
@@ -36,9 +30,9 @@
  * per-role arithmetic the status payload uses for this run alone. Nothing
  * here recomputes what one of those already answers.
  */
-import { MARK, formatDuration, formatRole, readRunUsage, renderStatusJson, roleUsage } from "./render.mjs";
+import { formatDuration, readRunUsage, renderStatusJson, roleUsage } from "./render.mjs";
 import { nodeSnapshotPath, readNodeSnapshot } from "../run/node-store.mjs";
-import { boundedUtf8, compactCost, finite } from "../util.mjs";
+import { finite } from "../util.mjs";
 import { SETTLED, SUCCESS } from "../engine/prompts.mjs";
 import { campaignDir } from "../campaign/layout.mjs";
 import { readCampaign } from "../campaign/record.mjs";
@@ -47,66 +41,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { runDirectory } from "../run/paths.mjs";
 
-/** @typedef {import("./render.mjs").StatusPayloadNode} StatusPayloadNode */
-/** @typedef {import("../notify/index.mjs").NotifyEvent} NotifyEvent */
-
-/**
- * The message's byte ceiling. A three-node run, both roles priced and a
- * two-sentence worker summary, measures ~430 bytes; this leaves headroom for
- * a long campaign/phase/node id triple while still bounding an adversarial
- * worker summary (the protocol's own 4 KiB ceiling), which is the only
- * unbounded block and the one truncated first.
- */
-export const PROGRESS_MESSAGE_MAX_BYTES = 2048;
 
 const NO_SUMMARY = "(no summary recorded)";
 
-/**
- * @param {string} runDir
- * @param {NotifyEvent} event
- * @returns {string}
- */
-export function renderRunProgress(runDir, event) {
-  const payload = /** @type {{campaignId: string, usage: {costUsd: number|null}, roles: {worker: import("./render.mjs").RoleUsage, judge: import("./render.mjs").RoleUsage}, nodes: StatusPayloadNode[]}} */
-    (JSON.parse(renderStatusJson(runDir)));
-  const subject = subjectNode(payload.nodes, event.nodeId ?? null);
-  const raw = readNodeSnapshot(runDir, subject.id);
-  const phaseNodes = payload.nodes.filter((node) => node.phase === subject.phase);
-  const total = payload.nodes.length;
-  const done = payload.nodes.filter((node) => SETTLED.has(node.status)).length;
-  const donePct = total ? Math.round((done / total) * 100) : 0;
-
-  const lines = [
-    `${MARK[subject.status] ?? "[?]"} campaign ${payload.campaignId} · phase ${subject.phase ?? "-"} · node ${subject.id}`,
-    `${done}/${total} nodes done · ${donePct}% done · ${100 - donePct}% left`,
-    `this node: ${spanOf(subject) ?? "-"}`,
-    phaseEstimateLine(phaseNodes),
-    nextNodeLine(phaseNodes),
-  ];
-  if (event.type === "attention") lines.push(attentionLine(runDir, subject, raw));
-  const valueLineIndex = lines.push(valueLine(raw)) - 1;
-  lines.push(costLine(runDir, payload));
-
-  return boundToCeiling(lines, valueLineIndex);
-}
-
-/**
- * The event's own node when it names one and the run still has it, else the
- * most recently settled node (a `run.terminal` event names the run, not a
- * node), else the run's first node.
- *
- * @param {StatusPayloadNode[]} nodes
- * @param {string|null} nodeId
- * @returns {StatusPayloadNode}
- */
-function subjectNode(nodes, nodeId) {
-  const named = nodeId ? nodes.find((node) => node.id === nodeId) : undefined;
-  if (named) return named;
-  const settled = nodes.filter((node) => SETTLED.has(node.status) && node.updatedAt);
-  const latest = settled.sort((left, right) => String(left.updatedAt).localeCompare(String(right.updatedAt))).at(-1);
-  return latest ?? nodes[0];
-}
-
 /** @param {{startedAt: string|null, updatedAt: string|null}} node @returns {number|null} */
 function spanMs(node) {
   if (!node.startedAt || !node.updatedAt) return null;
@@ -122,73 +59,43 @@ function spanOf(node) {
 }
 
 /**
- * The remaining-time estimate, shared by the single-run message and the
- * campaign roll-up so neither invents a second one: the mean span of the
- * settled nodes alone -- a running node's partial elapsed is never in
- * `SETTLED`, so it never drags the mean down and the estimate forward --
- * times how many nodes have not settled. `"complete"` when nothing is left;
- * `null` when nothing has settled to base the estimate on -- absent, never
- * zero, the same refusal this page applies to requirement coverage.
+ * The remaining-time estimate as a number, for a renderer that formats it its
+ * own way: `0` when nothing is left, `null` when nothing has settled to base
+ * it on, else the mean settled span times the unsettled count.
  *
- * @param {{status: string}[]} nodes every node the estimate covers
- * @param {{status: string, startedAt: string|null, updatedAt: string|null}[]} spans the nodes that carry the timestamps to average
- * @returns {string|null}
+ * @param {{status: string}[]} nodes
+ * @param {{status: string, startedAt: string|null, updatedAt: string|null}[]} spans
+ * @returns {number|null}
  */
-function remainingEstimate(nodes, spans) {
+export function remainingEstimateMs(nodes, spans) {
   const unsettled = nodes.filter((node) => !SETTLED.has(node.status)).length;
-  if (!unsettled) return "complete";
+  if (!unsettled) return 0;
   const settledSpans = spans.filter((node) => SETTLED.has(node.status)).map(spanMs).filter((ms) => ms !== null);
   if (!settledSpans.length) return null;
   const meanMs = settledSpans.reduce((total, ms) => total + /** @type {number} */ (ms), 0) / settledSpans.length;
-  return `~${formatDuration(meanMs * unsettled)} remaining (from ${settledSpans.length} settled node${settledSpans.length === 1 ? "" : "s"})`;
-}
-
-/** @param {StatusPayloadNode[]} phaseNodes @returns {string} */
-function phaseEstimateLine(phaseNodes) {
-  return `phase estimate: ${remainingEstimate(phaseNodes, phaseNodes) ?? "unknown (no settled node yet)"}`;
-}
-
-/** @param {StatusPayloadNode[]} phaseNodes @returns {string} */
-function nextNodeLine(phaseNodes) {
-  const next = phaseNodes.find((node) => !SETTLED.has(node.status));
-  return next ? `next: ${next.id}` : "next: phase complete";
+  return meanMs * unsettled;
 }
 
 /**
- * The worker's own words, never the renderer's: the raw snapshot's own
- * `result.summary`, labelled as such so a reader never mistakes it for the
- * renderer's judgment.
+ * The remaining-time estimate, shared by the notification message
+ * (`message.mjs`) and the campaign roll-up so neither invents a second one:
+ * the mean span of the settled nodes alone -- a running node's partial
+ * elapsed is never in `SETTLED`, so it never drags the mean down and the
+ * estimate forward -- times how many nodes have not settled. `"complete"`
+ * when nothing is left; `null` when nothing has settled to base the estimate
+ * on -- absent, never zero, the same refusal this page applies to requirement
+ * coverage.
  *
- * @param {Record<string, unknown>} raw
- * @returns {string}
- */
-function valueLine(raw) {
-  const result = /** @type {{summary?: unknown}|null} */ (raw.result && typeof raw.result === "object" ? raw.result : null);
-  const summary = typeof result?.summary === "string" && result.summary.trim() ? result.summary.trim() : null;
-  return `worker says: ${summary ?? NO_SUMMARY}`;
-}
-
-/**
- * The attention variant names what must be decided and the exact command
- * that unblocks it, the way `src/report/next.mjs` does for its own items.
- *
- * @param {string} runDir
- * @param {StatusPayloadNode} subject
- * @param {Record<string, unknown>} raw
- * @returns {string}
+ * @param {{status: string}[]} nodes every node the estimate covers
+ * @param {{status: string, startedAt: string|null, updatedAt: string|null}[]} spans the nodes that carry the timestamps to average
+ * @returns {string|null}
  */
-function attentionLine(runDir, subject, raw) {
-  const result = /** @type {{status?: unknown, summary?: unknown, missingContext?: unknown}|null} */ (raw.result && typeof raw.result === "object" ? raw.result : null);
-  if (result?.status === "blocked_context") {
-    const missing = Array.isArray(result.missingContext) ? result.missingContext.filter((entry) => typeof entry === "string") : [];
-    const asked = missing.length ? ` (needs ${missing.join(", ")})` : "";
-    return `decide: answer node ${subject.id}'s missing context${asked} → resume ${runDir} --answer ${subject.id}=<answer-file>`;
-  }
-  const gate = /** @type {{findings?: unknown}|null} */ (raw.gate && typeof raw.gate === "object" ? raw.gate : null);
-  if (subject.status === "exhausted" && Array.isArray(gate?.findings) && gate.findings.length) {
-    return `decide: review node ${subject.id}'s gate findings → findings ${runDir}`;
-  }
-  return `decide: resolve node ${subject.id} (${subject.status}) → status ${runDir}`;
+export function remainingEstimate(nodes, spans) {
+  const ms = remainingEstimateMs(nodes, spans);
+  if (ms === 0) return "complete";
+  if (ms === null) return null;
+  const settled = spans.filter((node) => SETTLED.has(node.status) && spanMs(node) !== null).length;
+  return `~${formatDuration(ms)} remaining (from ${settled} settled node${settled === 1 ? "" : "s"})`;
 }
 
 /**
@@ -220,33 +127,6 @@ function campaignCumulativeCostUsd(runsDir, campaignId) {
   return total;
 }
 
-/**
- * @param {string} runDir
- * @param {{campaignId: string, roles: {worker: import("./render.mjs").RoleUsage, judge: import("./render.mjs").RoleUsage}}} payload
- * @returns {string}
- */
-function costLine(runDir, payload) {
-  const cumulative = campaignCumulativeCostUsd(dirname(runDir), payload.campaignId);
-  return `cost — worker ${formatRole(payload.roles.worker)} · judge ${formatRole(payload.roles.judge)} · campaign total ${compactCost(cumulative)}`;
-}
-
-/**
- * The value block is the only unbounded part of the message, so it is the
- * only one truncated when the whole message would exceed the ceiling.
- *
- * @param {string[]} lines
- * @param {number} valueLineIndex
- * @returns {string}
- */
-function boundToCeiling(lines, valueLineIndex) {
-  const overflow = Buffer.byteLength(lines.join("\n"), "utf8") - PROGRESS_MESSAGE_MAX_BYTES;
-  if (overflow <= 0) return lines.join("\n");
-  const valueLineBytes = Buffer.byteLength(lines[valueLineIndex], "utf8");
-  const trimmed = [...lines];
-  trimmed[valueLineIndex] = boundedUtf8(lines[valueLineIndex], Math.max(0, valueLineBytes - overflow));
-  return trimmed.join("\n");
-}
-
 /**
  * @typedef {{id: string, dependsOn: string[], status: string, attempt: number, workerRuntime: string|null, judgeRuntime: string|null, elapsedSpan: string|null, costUsd: number|null, runDir: string|null, workerLogPath: string|null, judgeLogPaths: string[], verificationRecordPath: string|null, attemptBranch: string|null, sealCommit: string|null}} RollupNode
  * `status` carries every `NodeStatus` plus two the manifest alone can
@@ -292,7 +172,7 @@ export function renderCampaignProgress(runsDir, campaignId, now = Date.now()) {
  * @param {number} now
  * @returns {Record<string, unknown>}
  */
-function buildCampaignProgress(runsDir, campaignId, now) {
+export function buildCampaignProgress(runsDir, campaignId, now) {
   const campaignPath = campaignDir(runsDir, campaignId);
   const campaign = readCampaign(campaignPath);
   // The manifest is a queue of what is declared to run next, and the

package/src/report/render.mjs

@@ -10,6 +10,7 @@ import { compactCost, compactTokens, finite, truncateChars } from "../util.mjs";
 import { listNodeSnapshots, nodeSnapshotPath } from "../run/node-store.mjs";
 import { readHeartbeat } from "../engine/supervise.mjs";
 import { SETTLED, SUCCESS } from "../engine/prompts.mjs";
+import { packetRepetitionByNode, packetRepetitionNote } from "./packet-repetition.mjs";
 
 /** Advisory ceiling for status.json (TECH-SPEC lean, rule 5); never enforced destructively. */
 const STATUS_JSON_MAX_BYTES = 200 * 1024;
@@ -396,17 +397,16 @@ export function renderReport(runDir) {
   for (const [index, node] of nodes.entries()) {
     const usage = node.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
     for (const key of /** @type {("inputTokens"|"outputTokens"|"cacheReadInputTokens")[]} */ (Object.keys(totals).filter((key) => key !== "costUsd"))) totals[key] = (totals[key] ?? 0) + (usage[key] ?? 0);
-    const cost = costs[index];
     const runtime = workerRuntimeLabel(node) ?? "-";
     const planNode = contract.nodes.find((candidate) => candidate.id === node.id);
     const note = scopeFindingsNote(node.scopeFindings)
       ? nodeNote(node)
       : `phase ${planNode?.phase ?? "-"} · ${continuationMode(node)} · ${nodeNote(node)}`;
-    lines.push(row([MARK[node.status] ?? "[?]", node.id, node.status, node.attempt ?? 0, node.revisions ?? 0, runtime, compactTokens(usage.inputTokens), compactTokens(usage.outputTokens), compactTokens(usage.cacheReadInputTokens), formatCost(cost), note]));
+    lines.push(row([MARK[node.status] ?? "[?]", node.id, node.status, node.attempt ?? 0, node.revisions ?? 0, runtime, compactTokens(usage.inputTokens), compactTokens(usage.outputTokens), compactTokens(usage.cacheReadInputTokens), formatCost(costs[index]), note]));
   }
   totals.costUsd = aggregateCost.costUsd;
   const roles = roleUsage(nodes);
-  lines.push("```", "", `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${formatRole(roles.worker)} · judge ${formatRole(roles.judge)} · cost ${formatCost(aggregateCost)}`);
+  lines.push("```", "", `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${formatRole(roles.worker)} · judge ${formatRole(roles.judge)} · cost ${formatCost(aggregateCost)}${packetRepetitionNote(packetRepetitionByNode(runDir, nodes))}`);
   return `${lines.join("\n")}\n`;
 }
 

package/src/seat/tmux.mjs

@@ -8,6 +8,7 @@
  * command working on a host without tmux, where only reattaching is lost.
  */
 import { execFileSync } from "node:child_process";
+import { NOTIFY_SESSION_ENV } from "../notify/session.mjs";
 import { errorCode, exitStatus } from "../util.mjs";
 
 /** The single seat session every campaign window lives in. */
@@ -16,6 +17,14 @@ export const SEAT_SESSION = "faberun-seat";
 /** Window option recording which harness launched the window. */
 const HARNESS_OPTION = "@faberun-harness";
 
+/**
+ * The one variable a seat window sets for the harness it launches: every
+ * controller started from that harness inherits it and wakes the session on
+ * a terminal node (`notify/session.mjs`). The seat is the opt-in, so a test
+ * suite or a plain shell never wakes anything by accident.
+ */
+const SESSION_WAKE_ENV = `${NOTIFY_SESSION_ENV}=auto`;
+
 /** `list-windows` format: name, index, harness option, pane command, tab-separated. */
 const WINDOW_FORMAT = "#{window_name}\t#{window_index}\t#{@faberun-harness}\t#{pane_current_command}";
 
@@ -95,8 +104,8 @@ export function createSeatWindow(options) {
   }
   const command = shellCommand(options.argv);
   const args = existing.exists
-    ? ["new-window", "-t", options.session, "-n", options.window, "-c", options.cwd, command]
-    : ["new-session", "-d", "-s", options.session, "-n", options.window, "-c", options.cwd, command];
+    ? ["new-window", "-t", options.session, "-n", options.window, "-c", options.cwd, "-e", SESSION_WAKE_ENV, command]
+    : ["new-session", "-d", "-s", options.session, "-n", options.window, "-c", options.cwd, "-e", SESSION_WAKE_ENV, command];
   const result = runTmux(args);
   if (!result.ok) {
     return { available: result.available, ok: false, created: false, session: options.session, window: options.window, command, reason: result.reason, stderr: result.stderr };
@@ -123,7 +132,7 @@ function shellCommand(argv) {
  */
 export function respawnSeatWindow(options) {
   const command = shellCommand(options.argv);
-  const result = runTmux(["respawn-window", "-k", "-t", `${options.session}:${options.window}`, "-c", options.cwd, command]);
+  const result = runTmux(["respawn-window", "-k", "-t", `${options.session}:${options.window}`, "-c", options.cwd, "-e", SESSION_WAKE_ENV, command]);
   if (!result.ok) {
     return { available: result.available, ok: false, respawned: false, session: options.session, window: options.window, command, reason: result.reason, stderr: result.stderr };
   }