@pellux/goodvibes-tui 1.23.0 → 1.24.0

package/src/core/conversation-rendering.ts

@@ -15,8 +15,13 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { renderConversationCollapsedFragment, renderConversationEventLine } from '../renderer/conversation-surface.ts';
 import { GLYPHS } from '../renderer/ui-primitives.ts';
 import type { BlockMeta } from './conversation-types.ts';
+import {
+  collectToolCallOutcomes,
+  isTurnCollapsed,
+  type ConversationRenderContext,
+} from './conversation-render-context.ts';
 import { renderCompactionContinuationMessage } from './conversation-compaction-render.ts';
-import { drawBranchConnector, treeIndentCols, writeTreeStatusGutter } from '../renderer/conversation-tree.ts';
+import { drawTreeRails, treeIndentCols, treeTextCol } from '../renderer/conversation-tree.ts';
 import {
   MAX_NEST_DEPTH,
   buildRenderPlan,
@@ -52,76 +57,22 @@ const NAVIGABLE_KINDS: ReadonlySet<SystemMessageKind> = new Set(['system', 'wrfc
 
 type Message = ConversationMessageSnapshot;
 
-/**
- * Collect the ids of tool calls that have a matching tool-result message in the
- * given slice — i.e. the tools that actually ran. Used to decide whether an
- * assistant tool call still shows as pending (awaiting approval) or done.
- * (item 2c.)
- */
-export function collectCompletedToolCallIds(messages: readonly Message[]): Set<string> {
-  const ids = new Set<string>();
-  for (const message of messages) {
-    if (message.role === 'tool' && message.callId) ids.add(message.callId);
-  }
-  return ids;
-}
+// The render context and its pure derivations live in a type-only leaf module
+// (conversation-render-context.ts) so per-row render modules can depend on the
+// SHAPE of a render without depending on this drawing module. Re-exported here
+// because this file remains the transcript renderer's entry point.
+export {
+  collectCompletedToolCallIds,
+  collectToolCallOutcomes,
+  isTurnCollapsed,
+  type ConversationRenderContext,
+  type ToolCallOutcome,
+} from './conversation-render-context.ts';
 
 function summarizeCallId(callId: string, maxLength = 24): string {
   return callId.length <= maxLength ? callId : `${callId.slice(0, maxLength - 1)}…`;
 }
 
-export interface ConversationRenderContext {
-  readonly history: {
-    addLine: (line: Line) => void;
-    addLines: (lines: Line[]) => void;
-    getLineCount: () => number;
-  };
-  readonly blockRegistry: BlockMeta[];
-  readonly collapseState: Map<string, boolean>;
-  readonly errorLineRegistry: number[];
-  /** Maps message index → SystemMessageKind for typed system messages. */
-  readonly messageKindRegistry: ReadonlyMap<number, SystemMessageKind>;
-  readonly configManager: ConfigManager | null;
-  readonly splashOptions: SplashOptions;
-  /**
-   * Tool-call ids that have a corresponding tool-result message (i.e. the tool
-   * actually ran). An assistant tool call whose id is NOT in this set is still
-   * awaiting a decision (e.g. an approval prompt) and renders with a pending
-   * glyph instead of the completed ✓. When undefined (single-message callers
-   * without sibling context), every tool call renders as done — the prior
-   * behaviour. (item 2c.)
-   */
-  readonly completedToolCallIds?: ReadonlySet<string>;
-  /**
-   * Which assistant messages share one `● assistant` header, and what that
-   * header must say (see conversation-turn-structure.ts). Keyed by absolute
-   * index for every assistant message in a run AND every tool-result message
-   * the run's calls produced, so a collapsed turn can hide its results too.
-   * A message absent from this map (or an undefined map) renders standalone,
-   * exactly as it did before turn merging.
-   */
-  readonly assistantTurns?: ReadonlyMap<number, AssistantTurnMembership>;
-  /**
-   * Live snapshot reader for a spawned agent's own conversation, used to
-   * splice that agent's rows in beneath the call that spawned it (see
-   * conversation-turn-structure.ts). Undefined disables nesting entirely and
-   * the transcript renders exactly as it would without subagents.
-   */
-  readonly resolveAgentSnapshot?: (agentId: string) => readonly Message[] | null;
-}
-
-/**
- * Whether a turn's branches are hidden. Turns default to EXPANDED (unlike
- * every other collapsible block here, which defaults to collapsed): a turn
- * collapsed by default would hide the activity the transcript exists to show.
- */
-export function isTurnCollapsed(
-  turn: AssistantTurnMembership | undefined,
-  collapseState: ReadonlyMap<string, boolean>,
-): boolean {
-  return turn !== undefined && (collapseState.get(turn.turnKey) ?? false);
-}
-
 export function renderConversationUserMessage(
   context: ConversationRenderContext,
   message: Extract<Message, { role: 'user' }>,
@@ -424,12 +375,23 @@ export function renderConversationToolCallNode(
   const turn = context.assistantTurns?.get(node.absIdx);
   if (isTurnCollapsed(turn, context.collapseState)) return;
 
+  // The call row carries the call's OUTCOME, not merely whether it finished:
+  // the result row below it no longer repeats a marker, so this glyph is the
+  // only place a failed or cancelled tool says so in the status column.
+  const outcome = call.id !== undefined ? context.toolCallOutcomes?.get(call.id) : undefined;
   const ran = context.completedToolCallIds === undefined
     || (call.id !== undefined && context.completedToolCallIds.has(call.id));
+  const status: 'done' | 'error' | 'cancelled' | 'pending' = outcome === 'error'
+    ? 'error'
+    : outcome === 'cancelled'
+      ? 'cancelled'
+      : outcome === 'ok'
+        ? 'done'
+        : ran ? 'done' : 'pending';
   const indent = treeIndentCols(node.depth, width);
   const lines = renderToolCallBlock(
     call,
-    ran ? 'done' : 'pending',
+    status,
     undefined,
     width,
     undefined,
@@ -438,15 +400,12 @@ export function renderConversationToolCallNode(
     undefined,
     { indentCols: indent, omitToolName: turn?.sharedToolLabel !== undefined },
   );
-  const line = lines[0];
-  if (line) drawBranchConnector(line, node.depth, node.connector, node.openAncestorDepths, width, T.toolAccent);
-  context.history.addLines(lines);
 
   // Recursion stopped here — say so rather than silently showing a subtree as
   // if it were a leaf.
   if (node.truncated) {
     const noteIndent = treeIndentCols(node.depth + 1, width);
-    context.history.addLine(renderConversationEventLine(width, {
+    lines.push(renderConversationEventLine(width, {
       marker: GLYPHS.navigation.collapsed,
       markerFg: '244',
       label: '',
@@ -460,6 +419,28 @@ export function renderConversationToolCallNode(
       dim: true,
     }], noteIndent));
   }
+
+  // Rails last, over every line the row emitted, so the vertical run down to
+  // the next sibling has no gap in it.
+  drawTreeRails(lines, node.depth, node.connector, node.openAncestorDepths, width, T.toolAccent);
+  context.history.addLines(lines);
+}
+
+/**
+ * Move an already-rendered line `cols` columns to the right on a fresh
+ * full-width line. Used to place a tree row's expanded body under its own
+ * indent without re-rendering it at a different width (which would change the
+ * line count the row's badge already committed to).
+ */
+function shiftLineRight(line: Line, cols: number, width: number): Line {
+  if (cols <= 0) return line;
+  const shifted = createEmptyLine(width);
+  for (let i = 0; i < line.length; i++) {
+    const target = i + cols;
+    if (target >= width) break;
+    shifted[target] = line[i]!;
+  }
+  return shifted;
 }
 
 export function renderConversationToolMessage(
@@ -485,12 +466,25 @@ export function renderConversationToolMessage(
   // Parsed once, ahead of the collapse check, so it's available for the
   // block-registry meta merge below regardless of collapsed/expanded state.
   const diffParse = isDiff ? parseDiffForApply(message.content) : undefined;
+  const inTree = depth > 0 && indent > 0;
   // The EXPANDED render, computed unconditionally (even while collapsed) so
   // the header's "N lines" badge always names what Tab would actually reveal
   // — a raw JSON blob that pretty-prints to 50 lines must say 50, not 1, even
   // while it's still folded. Reused below as the actual body when expanded,
   // so this is never rendered twice.
-  const expandedLines = renderExpandedToolResultLines(message.content, width);
+  //
+  // In the tree it is rendered at the width it will actually OCCUPY (the row's
+  // width less its indent) and then shifted into place, so the badge still
+  // counts exactly the lines expansion produces. Rendering it full-width and
+  // displaying it indented would desynchronise the two — the
+  // markdown-table-drops-columns bug class — and rendering it full-width and
+  // displaying it flush punches the row's rails out for the whole body.
+  // The body is a continuation of its row, so it starts at the row's own text
+  // column; the shift is that column expressed relative to the flush left
+  // margin the body renders with internally.
+  const bodyShift = inTree ? Math.max(0, treeTextCol(indent) - LAYOUT.LEFT_MARGIN) : 0;
+  const bodyWidth = Math.max(LAYOUT.LEFT_MARGIN + LAYOUT.RIGHT_MARGIN + 8, width - bodyShift);
+  const expandedLines = renderExpandedToolResultLines(message.content, bodyWidth);
   const lineCount = expandedLines.length;
 
   // Human one-line summary for tool results (write/read/exec/edit): shown as the
@@ -528,7 +522,6 @@ export function renderConversationToolMessage(
   // parent call row already shows — is exactly the boilerplate this layout
   // removes. The row leads with its size badge instead. `diff` and `cancelled`
   // keep their labels: those carry information the parent row does not.
-  const inTree = depth > 0 && indent > 0;
   const label = isCancelled ? 'cancelled' : (blockType === 'diff' ? 'diff' : (inTree ? '' : 'tool result'));
   const nameSegments = inTree
     ? []
@@ -546,19 +539,12 @@ export function renderConversationToolMessage(
     ...nameSegments,
     { text: ` ${isCollapsed ? GLYPHS.navigation.collapsed : GLYPHS.navigation.expanded} ${lineCount} line${lineCount === 1 ? '' : 's'} `, fg: '244', dim: true },
   ], indent);
-  if (node && inTree) {
-    drawBranchConnector(headerLine, node.depth, node.connector, node.openAncestorDepths, width, T.toolAccent);
-    // A settled result means its call finished: ✓ in the shared gutter, or the
-    // blocked glyph when the user cancelled it. Distinguished by GLYPH, not by
-    // colour alone.
-    writeTreeStatusGutter(
-      headerLine,
-      isCancelled ? GLYPHS.status.blocked : TOOL_STATUS.SUCCESS_ICON,
-      isCancelled ? warnTone : activeUiTones().chrome.good,
-      width,
-    );
-  }
-  context.history.addLine(headerLine);
+  // Every line this row emits, gathered before anything is committed, so the
+  // rails can be drawn across all of them in one pass (see drawTreeRails). The
+  // result row deliberately carries NO status marker of its own: the call row
+  // directly above it already states the outcome in the shared bullet column,
+  // and a second marker one row down only doubles it.
+  const rows: Line[] = [headerLine];
 
   if (isCollapsed) {
     const collapseSuffixReserve = 30;
@@ -584,7 +570,7 @@ export function renderConversationToolMessage(
       dim: true,
       indentCols: indent,
     });
-    context.history.addLines(rendered);
+    for (const line of rendered) rows.push(line);
   } else {
     // Diff or plain result — either way this is exactly `expandedLines`,
     // already computed above (and already what the header's line count is
@@ -595,8 +581,16 @@ export function renderConversationToolMessage(
     // reduced width would desynchronise that count from what expansion
     // actually reveals — the markdown-table-drops-columns bug class. The body
     // is already visually bound to its row by the header directly above it.
-    context.history.addLines(expandedLines);
+    // In the tree it was rendered at `bodyWidth` above and is shifted into the
+    // row's indent here, which is what leaves the rail columns to its left free
+    // for the rails to run through.
+    for (const line of expandedLines) rows.push(shiftLineRight(line, bodyShift, width));
+  }
+
+  if (node && inTree) {
+    drawTreeRails(rows, node.depth, node.connector, node.openAncestorDepths, width, T.toolAccent);
   }
+  context.history.addLines(rows);
 
   const renderedLineCount = context.history.getLineCount() - startLine;
   let meta: BlockMeta = {
@@ -635,7 +629,10 @@ export function appendConversationMessages(
   // unless the caller already supplied the set. (item 2c.)
   const renderContext: ConversationRenderContext = context.completedToolCallIds !== undefined
     ? context
-    : { ...context, completedToolCallIds: collectCompletedToolCallIds(messages) };
+    : (() => {
+      const toolCallOutcomes = collectToolCallOutcomes(messages);
+      return { ...context, toolCallOutcomes, completedToolCallIds: new Set(toolCallOutcomes.keys()) };
+    })();
   const assistantTurns = renderContext.assistantTurns
     ?? computeAssistantTurns(messages, msgIndexOffset);
   const turnContext: ConversationRenderContext = renderContext.assistantTurns !== undefined

package/src/daemon/cli.ts

@@ -14,7 +14,7 @@ import { createRuntimeStore } from '../runtime/store/index.ts';
 import { createRuntimeServices } from '../runtime/services.ts';
 import { DaemonServer, HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
 import { createHostPowerSeam } from '@pellux/goodvibes-sdk/platform/power';
-import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { flushActivityLogSync, logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import {
   getOrCreateCompanionToken,
@@ -35,6 +35,7 @@ import {
 } from '@pellux/goodvibes-sdk/platform/discovery';
 import { createSafeHostServeFactory } from './safe-serve.ts';
 import { isDaemonServiceSubcommand, resolveInstalledDaemonBinary, runDaemonServiceCli } from './service-commands.ts';
+import { runClusterCommand } from '../cluster/commands.ts';
 import { resolveConfiguredServiceName } from '../runtime/legacy-daemon-migration.ts';
 import { runDaemonConfigMigration } from '../config/run-daemon-config-migration.ts';
 import { reconcileRedundantLegacyUnit } from '../runtime/legacy-daemon-reconcile.ts';
@@ -103,6 +104,39 @@ function readDaemonCliTokens(env: NodeJS.ProcessEnv): DaemonCliTokens {
 }
 
 async function main(): Promise<void> {
+  // `cluster …` is intercepted before the daemon's own flag parser runs, and
+  // before any runtime is composed.
+  //
+  // Before the parser, because the subcommand has its own flag vocabulary
+  // (--group, --key, --host, --port, --token) that the daemon parser would
+  // reject as unknown. Before the runtime, because this command talks to a
+  // daemon that is ALREADY RUNNING — composing a second runtime here would
+  // build a competing set of state on a machine that already has one.
+  //
+  // See remote-daemon-target.ts for the --host/--port/--token convention that
+  // every later remote-capable subcommand should follow.
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === 'cluster') {
+    const ownership = resolveDaemonCliOwnership();
+    const clusterConfig = new ConfigManager({
+      workingDir: ownership.workingDirectory,
+      homeDir: ownership.homeDirectory,
+      surfaceRoot: 'tui',
+    });
+    const result = await runClusterCommand({
+      argv: rawArgs.slice(1),
+      configManager: clusterConfig,
+      daemonHomeDir: ownership.daemonHomeDirectory,
+    });
+    if (result.rawOutput) process.stdout.write(`\u001b${result.rawOutput}`);
+    for (const line of result.lines) {
+      // eslint-disable-next-line no-console
+      if (result.exitCode === 0) console.log(line);
+      else console.error(line);
+    }
+    process.exit(result.exitCode);
+  }
+
   // Parse CLI flags first so --daemon-home and --working-dir env vars are set
   // before resolveDaemonCliOwnership() reads them.
   const cli = parseGoodVibesCli(process.argv.slice(2), 'goodvibes-daemon');
@@ -327,6 +361,15 @@ async function main(): Promise<void> {
     // undefined for a non-binary install, so a dev run stays host-managed and
     // never swaps the interpreter. See lifecycle.ts.
     updateArtifact: resolveDaemonUpdateArtifact({ version: VERSION }),
+    // The SAME coordinator this repository's inbox poller registered with (see
+    // runtime/cluster-composition.ts). The facade must reuse it rather than
+    // compose its own: two coordinators in one process are two nodes in the
+    // election, and whichever lost would silence consumers the other owns.
+    clusterCoordinator: runtimeServices.clusterCoordinator,
+    // The `cluster` verbs, served on /api/cluster/*. The CLI subcommands, the
+    // TUI's /cluster command and any web UI all call these, so a command run
+    // against a REMOTE daemon behaves exactly like one run on that machine.
+    clusterGroupVerbs: runtimeServices.clusterGroup.verbs,
   });
   const listener = new HttpListener({
     hookDispatcher: runtimeServices.hookDispatcher,
@@ -357,6 +400,11 @@ async function main(): Promise<void> {
   daemon.enable({ daemon: true }, effectiveDaemonToken);
   listener.enable({ httpListener: true }, effectiveHttpToken);
 
+  // Before the daemon: the group layer owns the socket the leader election
+  // coordinates over, and it announces this machine's return to the group so a
+  // box that has been off for months re-keys itself with no operator action.
+  await runtimeServices.startCluster();
+
   await Promise.all([
     daemon.start(),
     config.get('danger.httpListener') ? listener.start() : Promise.resolve(),
@@ -375,12 +423,29 @@ async function main(): Promise<void> {
     const timeout = new Promise<'timeout'>((resolve) =>
       setTimeout(() => resolve('timeout'), SHUTDOWN_DEADLINE_MS)
     );
-    const stop = Promise.allSettled([listener.stop(), daemon.stop()]).then(() => 'done' as const);
+    // daemon.stop() drives the ordered inbound teardown: it stops every gated
+    // consumer and only then broadcasts the resignation, so another node on
+    // this network takes over in about a second instead of waiting out the
+    // crash timeout. Handler surfaces (inbox store, catalog handlers) are
+    // released afterwards — before this, a SIGTERM left the inbox cursor store
+    // open and relied on process exit to clear the poll timers.
+    const stop = Promise.allSettled([listener.stop(), daemon.stop()])
+      .then(() => runtimeServices.daemonHandlers.unregister())
+      // This process built the runtime graph and handed it to DaemonServer, so
+      // by the SDK's ownership rule the facade leaves it alone — nothing else
+      // stops these pollers. Without this the config watch, fleet tick, memory
+      // governor, watcher registry and six more kept ticking until process exit.
+      .then(() => { runtimeServices.dispose(); })
+      .then(() => 'done' as const);
     const result = await Promise.race([stop, timeout]);
     if (result === 'timeout') {
       logger.warn('shutdown deadline exceeded — forcing exit');
+      // A forced exit is exactly the case where the log matters most and is
+      // least likely to have drained on its own.
+      flushActivityLogSync();
       process.exit(1);
     }
+    flushActivityLogSync();
     process.exit(0);
   };
 
@@ -474,5 +539,9 @@ void main().catch(async (error) => {
   logger.error('goodvibes daemon host failed', {
     error: summarizeError(error),
   });
+  // The daemon never came up. Without this the reason is buffered in a process
+  // that is about to stop existing, and the failure reads as a daemon that
+  // never logged anything at all.
+  flushActivityLogSync();
   process.exit(1);
 });

package/src/daemon/handlers/inbox/index.ts

@@ -75,6 +75,14 @@ export interface InboxListOutput {
   cursor?: string;
 }
 
+/** Start/stop control over the poll loops, handed to a leadership gate. */
+export interface InboxPollingControl {
+  /** Seed one poll and arm the loops. Resolves once polling has begun. */
+  start(): Promise<void>;
+  /** Disarm the loops. Resolves once no further poll can run. */
+  stop(): Promise<void>;
+}
+
 export interface RegisterInboxOptions {
   /** Override the cursor-store filename (tests). */
   storeFileName?: string;
@@ -82,6 +90,26 @@ export interface RegisterInboxOptions {
   skipInitialPoll?: boolean;
   /** Register the built-in slack/discord/email adapters (default true). */
   registerBuiltins?: boolean;
+  /**
+   * Hand polling to a leadership gate instead of starting it here.
+   *
+   * When supplied, register() prepares the store and the handler but does NOT
+   * poll: the callback receives start/stop control and something else decides
+   * when this node is the one that should be fetching. When absent the loops
+   * start immediately, which is the behaviour every existing caller and test
+   * relies on.
+   *
+   * The READ path is never gated. `channels.inbox.list` serves the persisted
+   * feed on every node — a node that is not fetching still answers questions
+   * about what has already arrived.
+   *
+   * Called once PER PROVIDER, with that provider's id and a control that
+   * starts and stops only its loop. Each inbox account is its own surface in
+   * the LAN election, so the machine reading the work Slack account need not
+   * be the machine reading the mailbox — and handing one account over must not
+   * take the others down with it.
+   */
+  gatePolling?: (providerId: string, control: InboxPollingControl) => void;
 }
 
 function registerBuiltinAdapters(): void {
@@ -176,11 +204,14 @@ export function registerInboxMethods(
   });
   const poller = new InboundPoller({ adapters, store, logger: ctx.logger });
 
-  // Async bootstrap: init store, seed one poll, start loops. Failures are
-  // logged but never thrown out of register() — the handler still serves the
-  // (possibly empty) persisted feed.
+  const gated = options.gatePolling !== undefined;
+
+  // Async bootstrap: init store, and (ungated) seed one poll and start loops.
+  // Failures are logged but never thrown out of register() — the handler still
+  // serves the (possibly empty) persisted feed.
   const ready: Promise<void> = (async () => {
     await store.init();
+    if (gated) return;
     if (!options.skipInitialPoll) {
       await poller.pollOnce();
     }
@@ -191,6 +222,35 @@ export function registerInboxMethods(
     });
   });
 
+  const gate = options.gatePolling;
+  if (gate) {
+    // One gate per provider, not one for the poller. Leadership is decided per
+    // inbox account, so each account's loop has to be startable and stoppable
+    // on its own — otherwise handing one account to another machine would stop
+    // fetching for every account this node reads.
+    for (const providerId of poller.providerIds()) {
+      gate(providerId, {
+        start: async () => {
+          // The store must be ready before the first fetch, or the seed poll
+          // would write cursors into an uninitialised store.
+          await ready;
+          if (!options.skipInitialPoll) {
+            await poller.pollProviderOnce(providerId);
+          }
+          poller.startProvider(providerId);
+        },
+        // Synchronous underneath: it clears that provider's interval, so once
+        // it returns no further poll of that account can be scheduled.
+        // Declared async because the gate contract promises "resolves when
+        // consumption has ceased", and a future adapter with an in-flight
+        // request would need to await it.
+        stop: async () => {
+          poller.stopProvider(providerId);
+        },
+      });
+    }
+  }
+
   const unregisterMethod = registerCatalogHandler<InboxListInput, InboxListOutput>(
     ctx.catalog,
     INBOX_LIST_METHOD_ID,

package/src/daemon/handlers/inbox/poller.ts

@@ -68,14 +68,53 @@ export class InboundPoller {
   start(): void {
     if (this.started) return;
     this.started = true;
-    for (const [id, adapter] of this.adapters) {
-      const handle = this.setIntervalImpl(() => {
-        void this.pollProvider(id, adapter);
-      }, adapter.pollIntervalMs);
-      // Do not keep the event loop alive solely for polling (Bun/Node unref).
-      (handle as unknown as { unref?: () => void }).unref?.();
-      this.timers.set(id, handle);
-    }
+    for (const id of this.adapters.keys()) this.startProvider(id);
+  }
+
+  /**
+   * Begin ONE provider's interval loop. Idempotent.
+   *
+   * Each inbox account is its own surface in the LAN election, so the machine
+   * that reads the work Slack account may not be the machine that reads the
+   * mailbox. A blanket start/stop cannot express that: it would take every
+   * account down to hand one of them over. Everything below is therefore
+   * addressable per provider, and the blanket calls are fan-outs over it.
+   */
+  startProvider(id: string): void {
+    if (this.timers.has(id)) return;
+    const adapter = this.adapters.get(id);
+    if (!adapter) return;
+    const handle = this.setIntervalImpl(() => {
+      void this.pollProvider(id, adapter);
+    }, adapter.pollIntervalMs);
+    // Do not keep the event loop alive solely for polling (Bun/Node unref).
+    (handle as unknown as { unref?: () => void }).unref?.();
+    this.timers.set(id, handle);
+  }
+
+  /**
+   * Stop ONE provider's interval loop. Idempotent.
+   *
+   * Synchronous underneath — clearing the interval means no further tick can
+   * be scheduled — which is what lets the RESIGN that follows a handoff be an
+   * honest claim that this node has stopped reading that account.
+   */
+  stopProvider(id: string): void {
+    const handle = this.timers.get(id);
+    if (handle === undefined) return;
+    this.clearIntervalImpl(handle);
+    this.timers.delete(id);
+    if (this.timers.size === 0) this.started = false;
+  }
+
+  /** True when this node is polling the given provider right now. */
+  isProviderRunning(id: string): boolean {
+    return this.timers.has(id);
+  }
+
+  /** Every provider this node has an adapter for. */
+  providerIds(): string[] {
+    return [...this.adapters.keys()];
   }
 
   /** Run a single poll across all providers now (used on register + tests). */
@@ -85,6 +124,13 @@ export class InboundPoller {
     );
   }
 
+  /** Run a single poll for ONE provider now. Never throws. */
+  async pollProviderOnce(id: string): Promise<void> {
+    const adapter = this.adapters.get(id);
+    if (!adapter) return;
+    await this.pollProvider(id, adapter);
+  }
+
   /** Poll a single provider, dedup + persist, update status. Never throws. */
   async pollProvider(id: string, adapter: InboundProviderAdapter): Promise<void> {
     if (this.inFlight.has(id)) return; // skip overlapping ticks

package/src/input/command-args-hint.ts

@@ -1,5 +1,6 @@
 import type { CommandRegistry } from './command-registry.ts';
 import { SESSION_SUBCOMMAND_ARG_HINTS } from './commands/session.ts';
+import { CLUSTER_SUBCOMMAND_ARG_HINTS } from './commands/cluster-runtime.ts';
 
 /**
  * Per-command subcommand → argument-hint maps. `session`'s entries come
@@ -12,6 +13,7 @@ import { SESSION_SUBCOMMAND_ARG_HINTS } from './commands/session.ts';
  */
 const SUBCOMMAND_HINTS: Record<string, Record<string, string>> = {
   session: SESSION_SUBCOMMAND_ARG_HINTS,
+  cluster: CLUSTER_SUBCOMMAND_ARG_HINTS,
   template: { save: '<name>', use: '<name> [args]', edit: '<name>', delete: '<name>' },
   secrets: { set: '<KEY> <value>', get: '<KEY>', delete: '<KEY>' },
   permissions: { tool: '<name> allow|prompt|deny' },

package/src/input/commands/cluster-runtime.ts

@@ -0,0 +1,53 @@
+/**
+ * cluster-runtime.ts — `/cluster` in the TUI.
+ *
+ * The same operations as the `goodvibes-daemon cluster` subcommands, reaching
+ * the same daemon verbs through the same caller. There is no cluster logic in
+ * this file and there must never be any: if `/cluster status` and
+ * `cluster status` could disagree, one of them would be lying to somebody.
+ *
+ * The one honest difference is `join` without arguments. The CLI can stop and
+ * ask which group and for the join key; a slash command has nowhere to ask, so
+ * it requires `--group` and `--key` and says so — which is exactly what the
+ * shared caller already reports for any non-interactive invocation.
+ */
+import { resolveDaemonHomeDir } from '@pellux/goodvibes-sdk/platform/workspace';
+import { runClusterCommand, CLUSTER_SUBCOMMANDS } from '../../cluster/commands.ts';
+import type { CommandRegistry } from '../command-registry.ts';
+
+/** Subcommand → argument hint, surfaced as the operator types. */
+export const CLUSTER_SUBCOMMAND_ARG_HINTS: Record<string, string> = {
+  status: '',
+  create: '[--name "<group name>"] [--passphrase "<phrase>"]',
+  join: '--group <id> --key <join key>',
+  key: '',
+  nodes: '',
+  forget: '<machine>',
+  rotate: '[--now]',
+  leave: '',
+  rename: '"<new name>"',
+  groups: '',
+};
+
+export function registerClusterRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'cluster',
+    description: 'Share inbound channel work with your other goodvibes machines on this network',
+    usage: `[${CLUSTER_SUBCOMMANDS.join('|')}] — status is the default; `
+      + 'add --host/--port/--token to reach a daemon on another machine',
+    argsHint: `[${CLUSTER_SUBCOMMANDS.join('|')}]`,
+    async handler(args, ctx) {
+      const argv = args.length === 0 ? ['status'] : args;
+      const result = await runClusterCommand({
+        argv,
+        configManager: ctx.platform.configManager,
+        daemonHomeDir: resolveDaemonHomeDir(),
+        // A transcript is not a terminal for clipboard purposes: writing an
+        // OSC 52 escape into the rendered conversation would put a control
+        // sequence in the scrollback rather than on anyone's clipboard.
+        isTerminal: false,
+      });
+      ctx.print(result.lines.join('\n'));
+    },
+  });
+}

package/src/input/commands.ts

@@ -56,6 +56,7 @@ import { registerServicesRuntimeCommands } from './commands/services-runtime.ts'
 import { registerTasksRuntimeCommands } from './commands/tasks-runtime.ts';
 import { registerLocalProviderRuntimeCommands } from './commands/local-provider-runtime.ts';
 import { registerHealthRuntimeCommands } from './commands/health-runtime.ts';
+import { registerClusterRuntimeCommands } from './commands/cluster-runtime.ts';
 import { registerSettingsSyncRuntimeCommands } from './commands/settings-sync-runtime.ts';
 import { registerWorktreeRuntimeCommands } from './commands/worktree-runtime.ts';
 import { registerAcpRuntimeCommands } from './commands/acp-runtime.ts';
@@ -139,6 +140,7 @@ export const BUILTIN_COMMAND_GROUPS: readonly BuiltinCommandGroup[] = [
   { category: 'Tasks', register: registerTasksRuntimeCommands },
   { category: 'Local Providers', register: registerLocalProviderRuntimeCommands },
   { category: 'Health', register: registerHealthRuntimeCommands },
+  { category: 'Cluster', register: registerClusterRuntimeCommands },
   { category: 'Settings Sync', register: registerSettingsSyncRuntimeCommands },
   { category: 'Worktrees', register: registerWorktreeRuntimeCommands },
   { category: 'Fleet', register: registerAcpRuntimeCommands },