@pellux/goodvibes-tui 1.23.0 → 1.24.0

package/src/input/settings-modal-data.ts

@@ -132,6 +132,12 @@ export function buildSettingGroups(
     // dropped from the workspace entirely — reachable only by editing the
     // config file by hand.
     if (rawCat === 'push' && groups.has('notifications')) groups.get('notifications')!.push(entry);
+    // cluster.* decides which node on this network reads the inbox, and it is
+    // configured in the same terms the network category already speaks: a
+    // group address, a port, a shared phrase, a peer list. Given no category of
+    // its own it would match nothing and drop out of the workspace entirely —
+    // reachable only by hand-editing a settings file.
+    if (rawCat === 'cluster' && groups.has('network')) groups.get('network')!.push(entry);
   }
 
   // Synthetic display.themeMode enum (auto|dark|light) — TUI-local, see theme-mode-config.ts.

package/src/main.ts

@@ -221,6 +221,9 @@ async function main() {
   const powerChipSource = createPowerChipSource({ powerManager: ctx.services.powerManager, render: () => render(), isExternalDaemon,
     onPowerEvent: (cb) => uiServices.events.ops.on('OPS_POWER_STATE_CHANGED', cb as never), fetchDaemonPowerState: () => fetchDaemonPowerState({ configManager, homeDirectory, isExternalDaemon }) });
   unsubs.push(powerChipSource.stop, installKeepAwakeRemoteForward({ configManager, homeDirectory, isExternalDaemon }));
+  // The interactive process composes a full runtime graph too, and that graph
+  // starts pollers. Drained with the rest of the teardown registry on exit.
+  unsubs.push(() => { ctx.services.dispose(); });
 
   const lifecycle = installProcessLifecycle({
     stdin,

package/src/renderer/conversation-surface.ts

@@ -2,6 +2,7 @@ import { type Line, createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth, wrapText } from '../utils/terminal-width.ts';
 import { LAYOUT } from './layout.ts';
 import { GLYPHS } from './ui-primitives.ts';
+import { treeBranchCol, treeContentCol } from './conversation-tree.ts';
 
 export interface ConversationSurfacePalette {
   readonly accent: string;
@@ -104,7 +105,12 @@ export function renderConversationFragment(
   palette: ConversationFragmentPalette,
   indentCols = 0,
 ): Line[] {
-  const margin = LAYOUT.USER_BOX_MARGIN + Math.max(0, indentCols);
+  // A tree fragment is a continuation of the row above it, so it starts at that
+  // row's content column — which puts its ` ▸ ` prefix glyph in exactly the same
+  // column as the parent row's own ` ▸ N lines ` badge. A flush fragment (a user
+  // message ghost box) keeps the box margin it has always used.
+  const indent = Math.max(0, indentCols);
+  const margin = indent > 0 ? treeContentCol(indent) : LAYOUT.USER_BOX_MARGIN;
   const prefixWidth = getDisplayWidth(palette.prefix);
   // The indent is charged to the content budget rather than allowed to push the
   // fragment past the right edge — a narrow terminal shrinks the preview text
@@ -211,15 +217,26 @@ export function renderConversationStatusLine(
 ): Line {
   const line = createEmptyLine(width);
   const indent = Math.max(0, options.indentCols ?? 0);
-  const markerCol = LAYOUT.LEFT_MARGIN - 1 + indent;
-  const startCol = LAYOUT.LEFT_MARGIN + 1 + indent;
+  // Both columns come from conversation-tree.ts so a flush row and a branch row
+  // sit on one grid: the marker where its depth's glyph belongs, the segment run
+  // two columns further right.
+  const markerCol = treeBranchCol(indent);
+  const startCol = treeContentCol(indent);
   const endCol = Math.max(startCol, width - LAYOUT.RIGHT_MARGIN);
-  if (markerCol >= 0 && markerCol < width) {
-    line[markerCol] = createStyledCell(options.marker ?? '▌', {
+  const marker = options.marker ?? '▌';
+  const markerWidth = getDisplayWidth(marker);
+  if (markerCol >= 0 && markerCol < width && markerWidth > 0) {
+    const markerStyle = {
       fg: options.markerFg ?? '#64748b',
       bg: options.markerBg ?? options.bodyBg ?? '',
       bold: true,
-    });
+    };
+    line[markerCol] = createStyledCell(marker, markerStyle);
+    // A double-width marker claims its trailing cell, so the segment run that
+    // follows still starts where the grid says it does.
+    if (markerWidth > 1 && markerCol + 1 < width) {
+      line[markerCol + 1] = createStyledCell('', markerStyle);
+    }
   }
   let col = startCol;
   for (const segment of segments) {

package/src/renderer/conversation-tree.ts

@@ -4,60 +4,81 @@
  * The transcript renders an assistant turn as a small tree: the turn header at
  * depth 0, each tool call it issues as a depth-1 branch, and each call's result
  * as a depth-2 branch under that call. This module owns the *only* arithmetic
- * that decides where those branch glyphs and their content land, so every row
- * type (event lines, tool-call rows, collapsed fragments) agrees on a single
- * column grid instead of each re-deriving it.
- *
- * Geometry, relative to the existing flush layout (LAYOUT.LEFT_MARGIN = 4):
- *
- *   depth 0   `  ● assistant …`         marker col 3, content col 5
- *   depth 1   `✓   ├ config.get …`       connector col 5, content col 7
- *   depth 2   `✓   │ └ ▸ 627 lines …`    connector col 7, content col 9
- *
- * The connector sits where the parent's content began, and content starts two
- * columns after it — the same marker→content relationship a depth-0 row has.
- * Status lives in a fixed gutter at column 0, OUTSIDE the indent, so every ✓
- * and ✗ in the transcript lines up in one column regardless of nesting depth.
- *
- * Every level steps by exactly TREE_STEP_COLS, and indent, gutter and content
- * columns are functions of depth and width ALONE — never of sibling status.
- * That is what makes a `└`→`├` connector flip cost exactly one cell: the
- * column it occupies exists either way, so no text moves.
- *
- * Narrow terminals: indenting unconditionally would eat the content budget and
- * silently truncate the informative end of a row — the failure class the
- * markdown-table column bug came from. treeIndentCols() therefore clamps the
- * indent to whatever still leaves TREE_MIN_CONTENT_COLS of content, and drops
- * to 0 (flush, no branch glyph) when even one level does not fit. Losing the
- * visual nesting on a 30-column terminal is acceptable; losing characters is
- * not.
+ * that decides where those branch glyphs, status markers and row text land, so
+ * every row type (event lines, tool-call rows, collapsed fragments) agrees on a
+ * single column grid instead of each re-deriving it.
+ *
+ * ## The grid
+ *
+ * One function generates every column, from LAYOUT.LEFT_MARGIN and the row's
+ * depth. With LEFT_MARGIN = 4 and TREE_STEP_COLS = 2 that is:
+ *
+ *   depth 0   `   ●  assistant …`            marker col 3, text col 6
+ *   depth 1   `   ✓  ├ read  foo.ts`         marker col 3, connector col 5, text col 8
+ *   depth 2   `      │ └  ▸ 31 lines`        connector col 7, text col 10
+ *   depth 3   `      │   │ └  …`             connector col 9, text col 12
+ *
+ * A level's connector sits where its parent's content began, and the row's
+ * first printable character sits two columns further right — the same
+ * marker→text relationship a depth-0 row has. So the step between levels is
+ * exactly TREE_STEP_COLS at every depth, for every row type.
+ *
+ * ## The status column IS the bullet column
+ *
+ * `treeStatusCol()` is defined as `treeBranchCol(0)` — literally the column the
+ * `●` of `● assistant` occupies. A tool row's ✓ / ✗ / ⊘ / ◌ therefore lands in
+ * the same column as the bullet of the turn that issued it, and reads as that
+ * bullet's column continuing down the turn rather than as a separate rail off
+ * to the left. Deriving it from treeBranchCol rather than restating a number is
+ * what keeps the two from drifting: move the bullet and the markers follow.
+ *
+ * The column is free at every depth ≥ 1 by construction — a branch row's own
+ * marker moves right with its indent, and depth 0 never contributes a `│`
+ * gutter (a top-level row has no ancestor to continue), so nothing else can
+ * claim it.
+ *
+ * ## Rails are continuous
+ *
+ * `drawTreeRails` paints EVERY line a row emits, not just its first: the
+ * connector on line 0, then `│` down the row's own column for as long as the
+ * row has a sibling below it, plus `│` in each open ancestor's gutter on every
+ * line. That is what closes the gaps a first-line-only connector leaves under
+ * multi-line rows (collapsed fragment boxes, wrapped text, expanded bodies).
+ *
+ * Rails never overwrite text: apart from the connector itself — which
+ * deliberately replaces the marker cell of the row it labels — a rail is drawn
+ * only into a cell that is blank and unstyled. A row whose own content reaches
+ * into a rail column keeps its content and loses the rail there.
+ *
+ * ## Narrow terminals
+ *
+ * Indenting unconditionally would eat the content budget and silently truncate
+ * the informative end of a row — the failure class the markdown-table column
+ * bug came from. treeIndentCols() therefore clamps the indent to whatever still
+ * leaves TREE_MIN_CONTENT_COLS of content, and drops to 0 (flush, no branch
+ * glyph) when even one level does not fit. Losing the visual nesting on a
+ * 30-column terminal is acceptable; losing characters is not.
  */
 
 import { LAYOUT } from './layout.ts';
 import type { Line } from '../types/grid.ts';
 import { createStyledCell } from '../types/grid.ts';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
 
 /** Columns added per nesting level. Fixed — never content-dependent. */
 const TREE_STEP_COLS = 2;
 
-/**
- * Width of the reserved status column that every row carries, at every depth.
- *
- * The column exists whether or not the row currently has a marker: a completed
- * row shows ✓, a failed row its failure glyph, an in-flight or plain row a
- * blank of the same width. Because the space is always reserved, a marker
- * appearing or resolving changes only that cell's contents and can never shift
- * the label beside it. Combined with fixed per-depth indentation this gives the
- * whole tree one rule: columns are fixed, only their contents change.
- */
-const TREE_STATUS_COLS = 2;
-
 /**
  * Content columns a branch row is guaranteed to keep. Below this the indent is
  * reduced (and finally dropped) rather than squeezing the row's text.
  */
 const TREE_MIN_CONTENT_COLS = 16;
 
+/** Vertical rail drawn in an ancestor's gutter and down an open row's column. */
+const TREE_RAIL = '│';
+
+/** The connector a row draws when a sibling follows it below. */
+const TREE_CONNECTOR_CONTINUES = '├';
 
 /**
  * Effective indent, in columns, for a branch at `depth` rendered at `width`.
@@ -69,57 +90,66 @@ const TREE_MIN_CONTENT_COLS = 16;
  */
 export function treeIndentCols(depth: number, width: number): number {
   if (depth <= 0) return 0;
-  // The status gutter is charged first and never given back — see TREE_GUTTER_COL.
-  const budget = width - LAYOUT.LEFT_MARGIN - LAYOUT.RIGHT_MARGIN - TREE_STATUS_COLS - TREE_MIN_CONTENT_COLS;
+  const budget = width - LAYOUT.LEFT_MARGIN - LAYOUT.RIGHT_MARGIN - TREE_MIN_CONTENT_COLS;
   if (budget < TREE_STEP_COLS) return 0;
   const affordableLevels = Math.floor(budget / TREE_STEP_COLS);
   return Math.min(depth, affordableLevels) * TREE_STEP_COLS;
 }
 
 /**
- * Write the status gutter for a row: `glyph` when it has one, an untouched
- * blank of the same width when it does not. Success and failure differ by
- * GLYPH, not only by colour, so the distinction survives a monochrome terminal
- * and colour-blind viewers.
+ * Column the row's leading glyph occupies for a given effective indent: the
+ * `●` of a depth-0 row, the `├`/`└` of a branch row, and the `│` an ancestor
+ * carries down through its descendants' rows.
  */
-export function writeTreeStatusGutter(
-  line: Line,
-  glyph: string | null,
-  fg: string,
-  width: number,
-): void {
-  if (!glyph || TREE_GUTTER_COL >= width) return;
-  line[TREE_GUTTER_COL] = createStyledCell(glyph, { fg, bold: true });
+export function treeBranchCol(indentCols: number): number {
+  return LAYOUT.LEFT_MARGIN - 1 + indentCols;
 }
 
 /**
- * Column the connector (`├`/`└`) occupies for a given effective indent, and
- * the column an ancestor's `│` gutter occupies at that same indent.
+ * Column at which a row's segment run begins. Segment runs carry one leading
+ * blank by convention (` assistant `, ` ▸ 31 lines `, the fragment's ` ▸ `
+ * prefix), so this is the gap column and treeTextCol is where glyphs land.
  */
-export function treeBranchCol(indentCols: number): number {
-  return LAYOUT.LEFT_MARGIN - 1 + indentCols;
+export function treeContentCol(indentCols: number): number {
+  return treeBranchCol(indentCols) + 2;
 }
 
 /**
- * The status gutter: a fixed column at the far LEFT of every row, before any
- * indentation, carrying ✓ / ✕ / blank.
- *
- * Deliberately outside the indent so it does not scale with depth. With the
- * marker placed after the connector instead, status would sit at a different
- * horizontal position on every row depending on nesting, so scanning for what
- * completed means tracking a ragged edge — and that degrades precisely as
- * trees get deeper. Here every marker in the transcript lines up in one
- * column no matter how deep its row sits, for the cost of one fixed column.
- *
- * It is never clamped: narrow terminals clamp the INDENT (see treeIndentCols)
- * and leave the gutter intact, because losing nesting depth is recoverable by
- * widening the terminal while losing which rows succeeded is not.
+ * Column of a row's first PRINTABLE character. Every row type must land its
+ * text here — that is the invariant which makes each level step by exactly
+ * TREE_STEP_COLS regardless of whether the row came from an event line, a
+ * tool-call row or a collapsed fragment.
  */
-const TREE_GUTTER_COL = 0;
+export function treeTextCol(indentCols: number): number {
+  return treeContentCol(indentCols) + 1;
+}
 
-/** Column where a branch row's text starts, immediately after its connector. */
-export function treeContentCol(indentCols: number): number {
-  return treeBranchCol(indentCols) + 2;
+/**
+ * Write a branch row's status marker into the shared bullet column.
+ *
+ * Success and failure differ by GLYPH, not only by colour, so the distinction
+ * survives a monochrome terminal and colour-blind viewers. A double-width glyph
+ * claims its trailing cell too, so the column math stays honest for emoji-class
+ * markers instead of leaving a stale half-character behind.
+ */
+export function writeTreeStatusMarker(
+  line: Line,
+  glyph: string | null,
+  fg: string,
+  width: number,
+): void {
+  if (!glyph) return;
+  // THE column: treeBranchCol(0) is where a depth-0 row draws its `●`, so a
+  // branch row's marker lands in the bullet column of the turn it belongs to.
+  // Derived, never restated, so the two cannot drift apart.
+  const col = treeBranchCol(0);
+  if (col < 0 || col >= width) return;
+  const glyphWidth = getDisplayWidth(glyph);
+  if (glyphWidth <= 0) return;
+  line[col] = createStyledCell(glyph, { fg, bold: true });
+  if (glyphWidth > 1 && col + 1 < width) {
+    line[col + 1] = createStyledCell('', { fg, bold: true });
+  }
 }
 
 /**
@@ -145,35 +175,54 @@ function treeGutterCols(
   return cols;
 }
 
+/** True when a rail may claim this cell without destroying rendered content. */
+function railCellIsFree(line: Line, col: number): boolean {
+  const cell = line[col];
+  if (!cell) return false;
+  return cell.char === ' ' && !cell.bg;
+}
+
+function writeRail(line: Line, col: number, glyph: string, fg: string, width: number, force: boolean): void {
+  if (col < 0 || col >= width) return;
+  if (!force && !railCellIsFree(line, col)) return;
+  line[col] = createStyledCell(glyph, { fg, dim: true });
+}
+
 /**
- * Draw a branch row's connector and the `│` gutters of its still-open
- * ancestors onto an already-rendered line, in place.
- *
- * Connectors are recomputed from live structure on every rebuild (see
- * conversation-turn-structure.ts), never cached, so a row that stops being
- * last flips `└`→`├` here with nothing stale to invalidate. Only this cell
- * changes: indent, status gutter and content column are functions of depth and
- * width alone, so a sibling arriving repaints one connector cell and moves no
- * text.
+ * Draw a row's connector and every rail that must pass through it, across ALL
+ * the lines the row emitted.
+ *
+ * Line 0 gets the connector in the row's own column (deliberately replacing
+ * whatever marker the row drew there — the connector IS that row's marker).
+ * Subsequent lines get `│` in that column while the row still has a sibling
+ * below it, so the rail runs unbroken from one `├` to the next. Every line
+ * additionally gets `│` in each open ancestor's gutter.
+ *
+ * Connectors and gutters are recomputed from live structure on every rebuild
+ * (see conversation-turn-structure.ts), never cached, so a row that stops being
+ * last flips `└`→`├` here with nothing stale to invalidate.
  */
-export function drawBranchConnector(
-  line: Line,
+export function drawTreeRails(
+  lines: readonly Line[],
   depth: number,
   connector: string | undefined,
   openAncestorDepths: readonly number[],
   width: number,
   fg: string,
 ): void {
-  if (depth <= 0 || !connector) return;
+  if (depth <= 0 || !connector || lines.length === 0) return;
   const indent = treeIndentCols(depth, width);
   if (indent <= 0) return;
-  for (const gutterCol of treeGutterCols(openAncestorDepths, depth, width)) {
-    if (gutterCol >= 0 && gutterCol < width) {
-      line[gutterCol] = createStyledCell('\u2502', { fg, dim: true });
+  const ownCol = treeBranchCol(indent);
+  const gutterCols = treeGutterCols(openAncestorDepths, depth, width);
+  const continuesBelow = connector === TREE_CONNECTOR_CONTINUES;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    for (const gutterCol of gutterCols) {
+      writeRail(line, gutterCol, TREE_RAIL, fg, width, false);
     }
-  }
-  const col = treeBranchCol(indent);
-  if (col >= 0 && col < width) {
-    line[col] = createStyledCell(connector, { fg, dim: true });
+    if (i === 0) writeRail(line, ownCol, connector, fg, width, true);
+    else if (continuesBelow) writeRail(line, ownCol, TREE_RAIL, fg, width, false);
   }
 }

package/src/renderer/tool-call.ts

@@ -6,7 +6,7 @@ import { stripDangerousAnsi } from './ansi-sanitize.ts';
 import { formatElapsed } from '../utils/format-elapsed.ts';
 import { GLYPHS } from './ui-primitives.ts';
 import { activeUiTones } from './theme.ts';
-import { treeBranchCol, treeContentCol, writeTreeStatusGutter } from './conversation-tree.ts';
+import { treeContentCol, treeTextCol, writeTreeStatusMarker } from './conversation-tree.ts';
 
 const TOOL_NAME_MIN_WIDTH = 8;
 const TOOL_NAME_MAX_WIDTH = 20;
@@ -188,10 +188,11 @@ export function renderToolCallBlock(
   const line = createEmptyLine(width);
   const t = activeUiTones();
   const indent = Math.max(0, tree?.indentCols ?? 0);
-  // In tree mode the status icon moves to the branch's content column, so the
-  // ✓ lines up with the content of every other row at the same depth and the
-  // branch glyph sits where the parent's content began.
-  const margin = indent > 0 ? treeContentCol(indent) : LAYOUT.LEFT_MARGIN;
+  const inTree = indent > 0;
+  // In tree mode the row's columns come from the shared grid: the branch glyph
+  // where the parent's content began, the status marker in the bullet column,
+  // and the row's text at this depth's text column.
+  const margin = inTree ? treeContentCol(indent) : LAYOUT.LEFT_MARGIN;
   const rightMargin = LAYOUT.RIGHT_MARGIN;
   const contentEnd = width - rightMargin;
 
@@ -226,18 +227,18 @@ export function renderToolCallBlock(
   const rightStart = rightText
     ? Math.max(margin + 2, contentEnd - rightWidth)
     : contentEnd;
-  const leftStart = margin;
+  const leftStart = inTree ? treeTextCol(indent) : margin;
   const leftEndExclusive = rightText
     ? Math.max(leftStart, rightStart - 1)
     : contentEnd;
   let col: number = leftStart;
 
-  // In tree mode the status glyph goes in the fixed left gutter (column 0),
-  // before the indent, so every marker in the transcript aligns in one column
-  // no matter how deep its row sits. The row's own content then starts at the
-  // branch's content column with no inline icon slot.
-  if (indent > 0) {
-    writeTreeStatusGutter(line, icon, iconColor, width);
+  // In tree mode the status glyph goes in the bullet column — the same column
+  // as the `●` of the `● assistant` header this row hangs under — so a turn's
+  // markers read as that bullet's column continuing down the turn. The row's
+  // own text then starts at its depth's text column with no inline icon slot.
+  if (inTree) {
+    writeTreeStatusMarker(line, icon, iconColor, width);
   } else {
     if (col < leftEndExclusive) {
       line[col] = createStyledCell(icon, { fg: iconColor, bold: status === 'done' || status === 'error' || status === 'cancelled' });

package/src/runtime/bootstrap.ts

@@ -483,7 +483,8 @@ export async function bootstrapRuntime(
 
   // Embedded DaemonServer/HttpListener factories (incl. the facade auto-update
   // suppression) — see embedded-service-factories.ts.
-  const createExternalServiceFactories = createEmbeddedServiceFactories;
+  const createExternalServiceFactories = (token: string): ExternalServiceFactories =>
+    createEmbeddedServiceFactories(token, services.clusterCoordinator, services.clusterGroup.verbs);
 
   let externalServices: ExternalServicesHandle = {
     daemonServer: null, httpListener: null,
@@ -595,6 +596,10 @@ export async function bootstrapRuntime(
         createExternalServiceFactories(companionTokenRecord.token),
       );
       externalServices = await externalServicesPromise;
+      // Join the coordination group even with no embedded daemon: the inbox
+      // poller is gated on leadership and nothing else would start it when
+      // daemon.enabled is false. Idempotent with the DaemonServer's own call.
+      await services.startCluster();
       controlPlaneRecentEventsRef.value = (limit) => externalServices.listRecentControlPlaneEvents(limit);
       syncSessionSpineToHostStatus(externalServices.daemonStatus, companionTokenRecord.token);
       await renderDaemonAttachNotices(companionTokenRecord.token);

package/src/runtime/cluster-composition.ts

@@ -0,0 +1,124 @@
+/**
+ * cluster-composition.ts — this daemon's seat in the LAN leader election.
+ *
+ * When the same goodvibes install runs more than once on one network — a
+ * laptop and a desktop, or two processes on one machine — every copy
+ * independently reads the shared inbox, so one message is picked up twice and
+ * answered twice. The SDK's cluster coordinator elects exactly one node to be
+ * responsible for inbound consumption; everything else stays warm and silent.
+ *
+ * This file exists because the goodvibes-tui daemon does NOT get that for free
+ * from the SDK facade. The facade gates the consumers IT owns (Telegram
+ * ingress, the ntfy/Slack/Discord provider runtime), but this repository
+ * composes an inbound consumer of its own — the Slack/Discord/email inbox
+ * poller in daemon/handlers/inbox — and the facade knows nothing about it.
+ * A fix that only landed in the facade would leave the poller double-reading
+ * on exactly the machine this product runs on.
+ *
+ * So this composition builds the ONE coordinator for the process, registers
+ * the inbox poller with it, and hands the same instance to the DaemonServer
+ * (via `DaemonConfig.clusterCoordinator`) so the SDK's consumers ride the same
+ * leadership rather than holding a second, competing election.
+ *
+ * What leadership does NOT gate, here or anywhere: outbound delivery,
+ * sessions, the control plane, the HTTP listener, the UI. A standby node is a
+ * complete goodvibes daemon that simply is not the one reading the inbox.
+ */
+import {
+  ClusterCoordinator,
+  inboxSurface,
+  readClusterSettings,
+  type ClusterConsumerGate,
+  type ClusterTransport,
+} from '@pellux/goodvibes-sdk/platform/cluster';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { GOODVIBES_TUI_SURFACE_ROOT } from '../config/surface.ts';
+import { VERSION } from '../version.ts';
+
+/** What an inbound poller must expose to be placed under leadership. */
+export interface GatedPollerControl {
+  /** Begin polling. Must not resolve until polling has actually begun. */
+  start(): Promise<void>;
+  /** Stop polling. Must not resolve until no further poll can run. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Build the process's single coordinator.
+ *
+ * Constructing it is inert: no socket is opened and no state is written until
+ * `start()` runs, so composing a runtime in a test never joins a network.
+ *
+ * The version is THIS BINARY's version, not the SDK package's — the same
+ * distinction daemon/cli.ts already makes for the self-update artifact. It is
+ * the first ranking tier, so getting it wrong would let a stale build hold the
+ * role through an update.
+ */
+export function createClusterComposition(options: {
+  /**
+   * Narrowed to what is actually read, which is exactly what
+   * `readClusterSettings` asks for. The daemon passes a whole ConfigManager;
+   * the handler context carries only this slice, and a test standing in a
+   * minimal config object should not have to fabricate the full fifty-odd
+   * members to compose a coordinator — a cast there would hide a real shape
+   * mismatch rather than document one.
+   */
+  readonly configManager: Pick<ConfigManager, 'getCategory'>;
+  readonly shellPaths: ShellPathService;
+  /**
+   * The datagram transport to coordinate over.
+   *
+   * Supplied by the group layer (cluster-group-composition.ts), which owns the
+   * socket and wraps every election datagram in the group envelope, signed with
+   * the current group key. That is what stops a daemon belonging to somebody
+   * else on the same network from taking part in this election at all.
+   *
+   * Absent — the plain default — means the coordinator opens its own socket and
+   * coordinates with anything that answers on the configured port.
+   */
+  readonly transport?: ClusterTransport | undefined;
+}): ClusterCoordinator {
+  return new ClusterCoordinator({
+    settings: readClusterSettings(options.configManager),
+    version: VERSION,
+    // Surface-scoped, alongside this surface's other durable state: the node
+    // identity is per-surface and must not leak across surface roots.
+    stateDirectory: options.shellPaths.resolveProjectPath(GOODVIBES_TUI_SURFACE_ROOT, 'cluster'),
+    logger,
+    ...(options.transport ? { transport: options.transport } : {}),
+  });
+}
+
+/**
+ * ONE inbox provider as a leadership gate.
+ *
+ * One gate per account, not one for the poller. Each inbox account is its own
+ * surface in the election, so this laptop can hold the work Slack account
+ * while the desktop holds the mailbox — and losing one machine moves only the
+ * accounts it was reading. A single gate covering the whole poller could not
+ * express that: it would hand every account over together, and a node with a
+ * credential for only one of them could never take part at all.
+ *
+ * The provider id is the surface's local discriminator and is hashed before it
+ * reaches the network, so what travels is a digest and not an account name.
+ *
+ * No replay cursor is threaded in, and that is deliberate rather than an
+ * omission: the inbox keeps a persisted per-provider cursor of its own
+ * (InboxCursorStore), so a node taking an account over resumes from where the
+ * previous one committed. ntfy needs an explicit `since=` because it has no
+ * server-side per-subscriber cursor; this poller does not.
+ */
+export function inboxPollerGate(providerId: string, control: GatedPollerControl): ClusterConsumerGate {
+  return {
+    id: `inbox-poller:${providerId}`,
+    surface: inboxSurface(providerId),
+    start: async () => {
+      await control.start();
+    },
+    stop: async () => {
+      await control.stop();
+    },
+  };
+}