@pellux/goodvibes-tui 2.0.21 → 2.1.1

package/src/core/long-task-notifier.ts

@@ -1,12 +1,20 @@
 /**
  * long-task-notifier, fires push notifications when a turn or agent task
- * completes after running longer than the configured threshold.
+ * ends after running longer than the configured threshold.
  *
- * PRIVACY GUARANTEE: Notification text must never include conversation content
- * (user messages, assistant replies, tool outputs). Only metadata is included:
- * task kind, elapsed time, ok/fail status, and session id. This module enforces
- * that constraint by construction, it receives no conversation object and
- * builds all message text from structural metadata only.
+ * NAMING RULE (owner ruling 2026-09-29): a notification names the work it is
+ * about. The title is the turn's name (the user-set conversation title, else
+ * the first line of the message that started the turn, trimmed at a word
+ * boundary), the body is the outcome: done, failed or cancelled, elapsed time,
+ * files changed, tool calls, agents started, review score, and for a failure
+ * the reason. Text comes from the SDK's runtime/turn-notification.ts so every
+ * channel and host words it the same way.
+ *
+ * PRIVACY RULE: behavior.notificationsMetadataOnly (default off). When on,
+ * every channel this module sends on (desktop and webhook) carries metadata
+ * only: the outcome, elapsed time, counts and the session id prefix, never the
+ * turn's name or a failure reason. When off, both channels, the webhook
+ * included, carry the name and the outcome.
  *
  * Delivery targets (in preference order):
  *   1. Desktop notification (linux notify-send / mac osascript) via SDK
@@ -32,7 +40,15 @@ import { notifyCompletion } from '@pellux/goodvibes-sdk/platform/utils';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
 import type { FocusTracker } from '@pellux/goodvibes-sdk/platform/runtime/operations';
-import { readNotifyOnlyWhenUnfocused, type ConfigGet } from '@pellux/goodvibes-sdk/platform/runtime/operations';
+import {
+  FORCE_NOTIFY_DURATION_MS,
+  buildTurnNotification,
+  formatWebhookText,
+  readNotificationsMetadataOnly,
+  readNotifyOnlyWhenUnfocused,
+  type ConfigGet,
+  type TurnOutcome,
+} from '@pellux/goodvibes-sdk/platform/runtime/operations';
 
 /** Default threshold in seconds. Turns shorter than this do not notify. */
 export const NOTIFY_AFTER_SECONDS_DEFAULT = 60;
@@ -66,9 +82,52 @@ export interface MaybeNotifyLongTaskOptions {
   /** Session id for correlation. Must not be a PII value. */
   readonly sessionId: string;
 
+  /**
+   * How the task ended. Overrides `status` when given, so a cancelled turn is
+   * told as cancelled rather than failed.
+   */
+  readonly outcome?: TurnOutcome | undefined;
+
+  /** The turn's name (SDK resolveTurnName). Left out of the text when metadata-only is on. */
+  readonly name?: string | null | undefined;
+
+  /** Why a failed or cancelled task stopped. Left out of the text when metadata-only is on. */
+  readonly reason?: string | null | undefined;
+
+  /** What the task did (SDK TurnActivityTally.snapshot()). */
+  readonly activity?: {
+    readonly toolCalls?: number | undefined;
+    readonly filesChanged?: number | undefined;
+    readonly agentsStarted?: number | undefined;
+    readonly reviewScore?: number | null | undefined;
+  } | undefined;
+
+  /**
+   * behavior.notificationsMetadataOnly. When omitted it is read through
+   * `configGet`; with neither, it is the default (off).
+   */
+  readonly metadataOnly?: boolean | undefined;
+
+  /** Desktop delivery; defaults to the SDK notifyCompletion. Tests pass a spy to read the text. */
+  readonly notifyDesktop?: typeof notifyCompletion | undefined;
+
+  /**
+   * False skips the desktop popup (behavior.notifyOnComplete off for a turn);
+   * the webhook still goes out. Default true.
+   */
+  readonly desktop?: boolean | undefined;
+
+  /**
+   * The desktop popup is also due past this many milliseconds, even under
+   * `thresholdSeconds` (and when the threshold is 0): a turn's end passes the
+   * SDK Orchestrator's own popup rule here (over 30s), since this notice
+   * replaced that popup. The webhook still waits for `thresholdSeconds`.
+   */
+  readonly desktopAfterMs?: number | undefined;
+
   /**
    * Threshold in seconds from config (behavior.notifyAfterSeconds).
-   * 0 means off; notifications are suppressed entirely.
+   * 0 means off: no webhook, and no popup unless `desktopAfterMs` makes one due.
    * Should be the raw config value; this function normalises it.
    */
   readonly thresholdSeconds: number;
@@ -95,28 +154,25 @@ export interface MaybeNotifyLongTaskOptions {
 }
 
 /**
- * Fires push notifications for a completed long task if the elapsed time
+ * Fires push notifications for a finished long task if the elapsed time
  * exceeds the configured threshold.
  *
  * Returns true when at least one delivery was attempted, false when the
  * call was a no-op (threshold not reached, off-state, or focus-gated off,
  * see `focusTracker`/`configGet` above).
  *
- * PRIVACY: builds message text from structural metadata only (kind, elapsed,
- * status, sessionId). Never includes conversation content.
+ * Text: see the NAMING and PRIVACY rules at the top of this file.
  */
 export function maybeNotifyLongTask(opts: MaybeNotifyLongTaskOptions): boolean {
   const { elapsedMs, status, kind, sessionId, thresholdSeconds, webhookNotifier, focusTracker, configGet } = opts;
+  const notifyDesktop = opts.notifyDesktop ?? notifyCompletion;
 
-  // Off-state: 0 disables notifications entirely.
-  if (thresholdSeconds === NOTIFY_AFTER_SECONDS_OFF) {
-    logger.debug('long-task-notifier: disabled (threshold=0)');
-    return false;
-  }
-
-  // Gate: only notify when the task exceeded the threshold.
+  // The threshold gates both deliveries (0 is off); a desktop floor
+  // (desktopAfterMs) can make the popup alone due before it.
   const elapsedSeconds = Math.floor(elapsedMs / 1000);
-  if (elapsedSeconds < thresholdSeconds) {
+  const thresholdMet = thresholdSeconds !== NOTIFY_AFTER_SECONDS_OFF && elapsedSeconds >= thresholdSeconds;
+  const desktopDue = opts.desktop !== false && (thresholdMet || (opts.desktopAfterMs !== undefined && elapsedMs > opts.desktopAfterMs));
+  if (!thresholdMet && !desktopDue) {
     logger.debug('long-task-notifier: below threshold', { elapsedSeconds, thresholdSeconds });
     return false;
   }
@@ -129,25 +185,38 @@ export function maybeNotifyLongTask(opts: MaybeNotifyLongTaskOptions): boolean {
     return false;
   }
 
-  // Build concise, metadata-only message. No conversation text.
-  const statusLabel = status === 'ok' ? 'completed' : 'failed';
-  const title = `GoodVibes: ${kind} ${statusLabel}`;
-  // PRIVACY: message contains only structural metadata, never conversation content.
-  const message = `${kind} ${statusLabel} in ${elapsedSeconds}s  ·  session ${sessionId.slice(0, 8)}`;
+  const metadataOnly = opts.metadataOnly ?? (configGet ? readNotificationsMetadataOnly(configGet) : false);
+  const notice = buildTurnNotification({
+    outcome: opts.outcome ?? (status === 'ok' ? 'completed' : 'failed'),
+    elapsedMs,
+    name: opts.name,
+    reason: opts.reason,
+    sessionId,
+    subject: kind,
+    ...opts.activity,
+  }, { metadataOnly });
 
   // Delivery 1: desktop notification (notify-send on linux, osascript on mac).
   // notifyCompletion is non-throwing; SDK handles platform absence silently.
-  try {
-    notifyCompletion(title, message, elapsedMs);
-  } catch (err) {
-    logger.debug('long-task-notifier: desktop notify error', { error: String(err) });
+  // Its own duration heuristic only pops a desktop notification above 30s;
+  // the threshold above is the user's (behavior.notifyAfterSeconds), so a
+  // threshold under 30s must still reach the desktop.
+  let delivered = false;
+  if (desktopDue) {
+    delivered = true;
+    try {
+      notifyDesktop(notice.title, notice.body, Math.max(elapsedMs, FORCE_NOTIFY_DURATION_MS));
+    } catch (err) {
+      logger.debug('long-task-notifier: desktop notify error', { error: String(err) });
+    }
   }
 
   // Delivery 2: outbound webhook (ntfy / generic endpoint) if configured.
-  if (webhookNotifier) {
+  if (webhookNotifier && thresholdMet) {
     const urls = webhookNotifier.getUrls();
     if (urls.length > 0) {
-      webhookNotifier.send(message).catch((err: unknown) => {
+      delivered = true;
+      webhookNotifier.send(formatWebhookText(notice)).catch((err: unknown) => {
         logger.debug('long-task-notifier: webhook send error', { error: String(err) });
       });
     } else {
@@ -155,7 +224,7 @@ export function maybeNotifyLongTask(opts: MaybeNotifyLongTaskOptions): boolean {
     }
   }
 
-  return true;
+  return delivered;
 }
 
 /**

package/src/core/notices.ts

@@ -0,0 +1,75 @@
+/**
+ * notices.ts, where a conversation system notice goes.
+ *
+ * A system notice ([WRFC] …, [Agents] …, a compaction receipt, a failover
+ * line) is not part of any turn, so the transcript does not draw it (the
+ * concept's turns hold only the turn's own text, beads, lanes and answer;
+ * agent and chain state are the lanes' own spawn and merge rows). Each notice
+ * becomes a toast in the top right and an entry in the notification history
+ * (/notifications), with its full text: the first line is the title, any
+ * further lines are the body. The conversation still stores the message, so a
+ * saved session keeps it, and restoring that session puts it back in the
+ * history without toasting it again.
+ *
+ * One entry per event: a "[WRFC] …" or "[Agents] …" line that restates an
+ * agent or chain event (the SDK's runtimeEventOfNotice names it) is kept under
+ * that event's plain title, with the line's detail as the body, and carries
+ * the event's key; the terminal's own "[WRFC] …" lines get their plain titles
+ * from core/wrfc-notice-titles.ts. The runtime-bus bridge (runtime/notification-dispatch.ts)
+ * records the same event with the same key, and the feed keeps one entry for
+ * both (NotificationFeed, eventKey).
+ */
+
+import type { Notification } from '@/runtime/index.ts';
+import { runtimeEventOfNotice } from '@pellux/goodvibes-sdk/platform/runtime/bootstrap';
+import { shellChainNoticeOf } from './wrfc-notice-titles.ts';
+import type { NotificationFeed } from '../views/notifications-feed.ts';
+import { classifySystemMessage } from '../renderer/system-message.ts';
+
+/** Receives every system notice added to (or restored into) the conversation. */
+export type NoticeSink = (content: string, options: { readonly restored: boolean }) => void;
+
+/** The pieces of a notice as the history and the toast show them. */
+export interface NoticeParts {
+  /** Lower-case bracket tag ('wrfc', 'agents', 'compaction', …) or 'system' when untagged. */
+  readonly domain: string;
+  readonly level: Notification['level'];
+  /** The first non-empty line, in full. */
+  readonly title: string;
+  /** Every further line, in full, or undefined. */
+  readonly body: string | undefined;
+}
+
+const TAG_RE = /^\s*\[([^\]\n]+)\]/;
+
+export function noticeParts(text: string): NoticeParts {
+  const trimmed = text.replace(/^\s*\n+/, '').replace(/\s+$/, '');
+  const tag = TAG_RE.exec(trimmed)?.[1];
+  const domain = tag ? tag.trim().toLowerCase().replace(/\s+/g, '-') : 'system';
+  const kind = classifySystemMessage(trimmed);
+  const level: Notification['level'] = kind === 'error' ? 'critical' : kind === 'warning' ? 'warning' : 'info';
+  const newline = trimmed.indexOf('\n');
+  const title = newline < 0 ? trimmed : trimmed.slice(0, newline);
+  const rest = newline < 0 ? '' : trimmed.slice(newline + 1).replace(/^\n+/, '');
+  return { domain, level, title, body: rest.length > 0 ? rest : undefined };
+}
+
+export interface NoticeOptions {
+  /** Restored from a saved session: kept in history, not toasted. */
+  readonly restored?: boolean;
+  readonly now?: () => number;
+}
+
+/** Keep one system notice in the history; the feed's toast bridge toasts it unless restored. */
+export function publishNotice(feed: NotificationFeed, text: string, options: NoticeOptions = {}): void {
+  if (text.trim().length === 0) return;
+  const restored = options.restored === true;
+  const parts = noticeParts(text);
+  const sdkEvent = runtimeEventOfNotice(text);
+  const event = sdkEvent ?? shellChainNoticeOf(text);
+  if (event) {
+    feed.recordNotice({ domain: parts.domain, level: event.level, title: event.title, body: event.detail, timestamp: (options.now ?? Date.now)(), restored, eventKey: sdkEvent?.key });
+    return;
+  }
+  feed.recordNotice({ ...parts, timestamp: (options.now ?? Date.now)(), restored });
+}

package/src/core/pairing-tailscale-gateway.ts

@@ -16,7 +16,7 @@ import { resolveOperatorRpc } from '../input/commands/operator-rpc.ts';
 import type {
   PairingTailscaleServeReceipt,
   PairingTailscaleStatus,
-} from '../panels/modals/pairing-modal.ts';
+} from '../views/modals/pairing-modal.ts';
 
 export interface PairingTailscaleGatewayDeps {
   readonly configManager: ConfigManager;

package/src/core/process-output-log.ts

@@ -0,0 +1,143 @@
+/**
+ * process-output-log.ts, a background process's output as timestamped lines.
+ *
+ * The process manager keeps each process's stdout and stderr as chunk arrays
+ * that grow while it runs, but it does not record when a chunk arrived. This
+ * log reads the arrays on every poll, splits new chunks into lines and stamps
+ * each line with the time it was first seen. The poll runs twice a second
+ * from startup (see shell/session-views.ts), so a stamp is at most about half
+ * a second late. A partial line (no newline yet) is held until it completes
+ * or the process ends.
+ *
+ * Bounded: each process keeps its newest MAX_LINES lines; a process the
+ * manager no longer lists is dropped on the next poll.
+ */
+
+export interface ProcessLine {
+  /** Epoch ms the line was first seen. */
+  readonly at: number;
+  readonly text: string;
+  readonly stream: 'stdout' | 'stderr';
+  /** The line reads as an error (drawn in the error color). */
+  readonly error: boolean;
+}
+
+/** The slice of a process record this log reads (BackgroundProcess from the SDK). */
+export interface ProcessRecordView {
+  readonly stdout: readonly string[];
+  readonly stderr: readonly string[];
+  readonly done: boolean;
+}
+
+/** Newest lines kept per process. */
+export const MAX_LINES = 5000;
+
+const ERROR_LINE = /\b(error|errors|failed|failure|fatal|exception|panic|traceback)\b|ERR!|✘|✖/i;
+const PORT_PATTERNS: readonly RegExp[] = [
+  /\b(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1?\]):(\d{2,5})\b/,
+  /\blistening on (?:port )?:?(\d{2,5})\b/i,
+  /\bport[ =:]+(\d{2,5})\b/i,
+];
+
+/** Terminal control sequences never reach the view: colors and cursor moves are stripped. */
+function clean(text: string): string {
+  return text
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+}
+
+export function isErrorLine(text: string): boolean {
+  return ERROR_LINE.test(text);
+}
+
+/** The first port a line announces ("http://localhost:5173/", "listening on 3000"), when it names one. */
+export function portOf(text: string): number | undefined {
+  for (const pattern of PORT_PATTERNS) {
+    const m = pattern.exec(text);
+    if (m) {
+      const port = Number(m[1]);
+      if (port > 0 && port < 65536) return port;
+    }
+  }
+  return undefined;
+}
+
+interface StreamCursor { chunks: number; partial: string }
+
+interface Entry {
+  readonly lines: ProcessLine[];
+  readonly out: StreamCursor;
+  readonly err: StreamCursor;
+  port: number | undefined;
+  /** Lines dropped off the front by the bound. */
+  dropped: number;
+}
+
+export class ProcessOutputLog {
+  private readonly entries = new Map<string, Entry>();
+
+  /**
+   * Read every listed process's new output. `records` are the processes the
+   * manager lists right now; anything else is forgotten.
+   */
+  poll(records: ReadonlyMap<string, ProcessRecordView>, now = Date.now()): boolean {
+    let changed = false;
+    for (const id of [...this.entries.keys()]) if (!records.has(id)) this.entries.delete(id);
+    for (const [id, record] of records) {
+      let entry = this.entries.get(id);
+      if (!entry) {
+        entry = { lines: [], out: { chunks: 0, partial: '' }, err: { chunks: 0, partial: '' }, port: undefined, dropped: 0 };
+        this.entries.set(id, entry);
+      }
+      if (this.read(entry, entry.out, record.stdout, 'stdout', record.done, now)) changed = true;
+      if (this.read(entry, entry.err, record.stderr, 'stderr', record.done, now)) changed = true;
+    }
+    return changed;
+  }
+
+  lines(id: string): readonly ProcessLine[] {
+    return this.entries.get(id)?.lines ?? [];
+  }
+
+  /** Lines dropped off the front of this process's log by the bound. */
+  dropped(id: string): number {
+    return this.entries.get(id)?.dropped ?? 0;
+  }
+
+  /** The port the process announced, once one of its lines named it. */
+  port(id: string): number | undefined {
+    return this.entries.get(id)?.port;
+  }
+
+  private read(entry: Entry, cursor: StreamCursor, chunks: readonly string[], stream: ProcessLine['stream'], done: boolean, now: number): boolean {
+    if (chunks.length < cursor.chunks) cursor.chunks = 0; // the manager trimmed its buffer: start over from what it has
+    let changed = false;
+    if (chunks.length > cursor.chunks) {
+      const text = cursor.partial + chunks.slice(cursor.chunks).join('');
+      cursor.chunks = chunks.length;
+      const parts = text.split(/\r?\n/);
+      cursor.partial = parts.pop() ?? '';
+      for (const part of parts) this.push(entry, part, stream, now);
+      changed = parts.length > 0;
+    }
+    if (done && cursor.partial) {
+      this.push(entry, cursor.partial, stream, now);
+      cursor.partial = '';
+      changed = true;
+    }
+    return changed;
+  }
+
+  private push(entry: Entry, raw: string, stream: ProcessLine['stream'], now: number): void {
+    // A carriage return without a newline redraws the same line (progress bars): keep what is left visible.
+    const text = clean(raw.includes('\r') ? raw.slice(raw.lastIndexOf('\r') + 1) : raw).trimEnd();
+    entry.lines.push({ at: now, text, stream, error: isErrorLine(text) });
+    if (entry.port === undefined) entry.port = portOf(text);
+    if (entry.lines.length > MAX_LINES) {
+      const extra = entry.lines.length - MAX_LINES;
+      entry.lines.splice(0, extra);
+      entry.dropped += extra;
+    }
+  }
+}

package/src/core/rewind-receipt.ts

@@ -10,7 +10,7 @@
  *
  * The `[Rewind]` prefix is one of the FORCE_CONVERSATION_PREFIXES the
  * system-message router always surfaces inline (see core/system-message-router.ts),
- * so the receipt cannot be routed into a panel and vanish.
+ * so the receipt cannot be routed away from the transcript and vanish.
  */
 
 /** The subset of the SDK's RewindReceipt this formatter renders. */

package/src/core/session-focus.ts

@@ -0,0 +1,190 @@
+/**
+ * session-focus.ts, which session the terminal is showing: main, one agent,
+ * or one background process.
+ *
+ * Enter on an agent lane (or its row in the Agents modal) opens that agent
+ * full screen; Enter on a ▶ bead (or a process row) opens the process. The
+ * session chips under the header list every session there is to switch to,
+ * and Tab / Shift+Tab cycle them while the composer is empty.
+ *
+ * Esc inside an agent or process view goes up exactly one level: a process
+ * or a top-level agent returns to main; an agent spawned by another agent
+ * returns to that agent. Going up never stops or cancels anything. Stopping
+ * is ctrl+x pressed twice: the first press arms, the second (within
+ * STOP_CONFIRM_MS) stops.
+ *
+ * Pure state plus the live facts it is handed (SessionFocusDeps); nothing
+ * here renders or talks to the runtime directly.
+ */
+
+export type SessionTarget =
+  | { readonly kind: 'main' }
+  | { readonly kind: 'agent'; readonly id: string }
+  | { readonly kind: 'process'; readonly id: string };
+
+/** The status a chip's mark shows. */
+export type SessionMark = 'run' | 'idle' | 'ok' | 'err' | 'cancel' | 'wait';
+
+/** One session the chips row lists. */
+export interface SessionEntry {
+  readonly target: SessionTarget;
+  /** "main", the agent's template name, or the process command. */
+  readonly name: string;
+  readonly mark: SessionMark;
+}
+
+export interface SessionFocusDeps {
+  /** Agents worth a chip: running or pending (finished ones leave the row). */
+  readonly liveAgents: () => ReadonlyArray<{ readonly id: string; readonly name: string; readonly mark: SessionMark }>;
+  /** Background processes still running. */
+  readonly liveProcesses: () => ReadonlyArray<{ readonly id: string; readonly name: string; readonly mark: SessionMark }>;
+  /** Name and mark of any agent (the focused one may have finished), or null when unknown. */
+  readonly agent: (id: string) => { readonly name: string; readonly mark: SessionMark } | null;
+  /** Name and mark of any process, or null when unknown. */
+  readonly process: (id: string) => { readonly name: string; readonly mark: SessionMark } | null;
+  /** The agent that spawned this agent, or null when main did (or it is unknown). */
+  readonly parentAgent: (id: string) => string | null;
+  /** Whether main is working on a turn. */
+  readonly mainBusy: () => boolean;
+  readonly now?: () => number;
+}
+
+export const MAIN: SessionTarget = { kind: 'main' };
+
+/** How long the first ctrl+x stays armed. */
+export const STOP_CONFIRM_MS = 3000;
+
+export function sameTarget(a: SessionTarget, b: SessionTarget): boolean {
+  if (a.kind !== b.kind) return false;
+  return a.kind === 'main' || a.id === (b as { id: string }).id;
+}
+
+export class SessionFocus {
+  private currentTarget: SessionTarget = MAIN;
+  private armed: { readonly target: SessionTarget; readonly at: number } | null = null;
+  private listener: (() => void) | null = null;
+
+  constructor(private readonly deps: SessionFocusDeps) {}
+
+  get current(): SessionTarget { return this.currentTarget; }
+  /** An agent or process view is showing. */
+  get active(): boolean { return this.currentTarget.kind !== 'main'; }
+
+  /** Be told whenever the view changes (the transcript scroll resets, the frame repaints). */
+  onChange(listener: (() => void) | null): void { this.listener = listener; }
+
+  /** Show `target`. Opening an unknown agent or process is refused (false). */
+  open(target: SessionTarget): boolean {
+    if (target.kind === 'agent' && this.deps.agent(target.id) === null) return false;
+    if (target.kind === 'process' && this.deps.process(target.id) === null) return false;
+    if (sameTarget(target, this.currentTarget)) return true;
+    this.currentTarget = target;
+    this.armed = null;
+    this.listener?.();
+    return true;
+  }
+
+  /** The level Esc goes back to from `target`. */
+  parentOf(target: SessionTarget): SessionTarget {
+    if (target.kind !== 'agent') return MAIN;
+    const parent = this.deps.parentAgent(target.id);
+    return parent !== null && parent !== target.id && this.deps.agent(parent) !== null ? { kind: 'agent', id: parent } : MAIN;
+  }
+
+  /** Esc in a view: go up one level. Returns false in main (nothing to go back from). Never stops anything. */
+  back(): boolean {
+    if (!this.active) return false;
+    this.currentTarget = this.parentOf(this.currentTarget);
+    this.armed = null;
+    this.listener?.();
+    return true;
+  }
+
+  /** The display name of a target. */
+  nameOf(target: SessionTarget): string {
+    if (target.kind === 'main') return 'main';
+    const known = target.kind === 'agent' ? this.deps.agent(target.id) : this.deps.process(target.id);
+    return known?.name ?? target.id;
+  }
+
+  /** "main › engineer › tester": the path from main down to the current view. */
+  breadcrumb(): SessionTarget[] {
+    const path: SessionTarget[] = [];
+    let at: SessionTarget = this.currentTarget;
+    for (let guard = 0; at.kind !== 'main' && guard < 16; guard++) {
+      path.unshift(at);
+      at = this.parentOf(at);
+    }
+    return [MAIN, ...path];
+  }
+
+  /**
+   * Every session there is to switch to: main, then running agents, then
+   * running processes. The session being shown is always listed, even after
+   * it finished.
+   */
+  sessions(): SessionEntry[] {
+    const entries: SessionEntry[] = [{ target: MAIN, name: 'main', mark: this.deps.mainBusy() ? 'run' : 'idle' }];
+    const agents = this.deps.liveAgents();
+    const processes = this.deps.liveProcesses();
+    const cur = this.currentTarget;
+    const names = new Map<string, number>();
+    const label = (name: string): string => {
+      const n = (names.get(name) ?? 0) + 1;
+      names.set(name, n);
+      return n > 1 ? `${name} ${n}` : name;
+    };
+    const pushAgent = (id: string, name: string, mark: SessionMark): void => { entries.push({ target: { kind: 'agent', id }, name: label(name), mark }); };
+    const pushProcess = (id: string, name: string, mark: SessionMark): void => { entries.push({ target: { kind: 'process', id }, name: label(name), mark }); };
+    for (const a of agents) pushAgent(a.id, a.name, a.mark);
+    if (cur.kind === 'agent' && !agents.some((a) => a.id === cur.id)) {
+      const known = this.deps.agent(cur.id);
+      if (known) pushAgent(cur.id, known.name, known.mark);
+    }
+    for (const p of processes) pushProcess(p.id, p.name, p.mark);
+    if (cur.kind === 'process' && !processes.some((p) => p.id === cur.id)) {
+      const known = this.deps.process(cur.id);
+      if (known) pushProcess(cur.id, known.name, known.mark);
+    }
+    return entries;
+  }
+
+  /** The chips row shows only when there is more than one session to switch to. */
+  chipsVisible(): boolean {
+    return this.sessions().length > 1;
+  }
+
+  /** Tab (+1) / Shift+Tab (-1): show the next or previous session. False when there is nothing to cycle to. */
+  cycle(delta: 1 | -1): boolean {
+    const list = this.sessions();
+    if (list.length < 2) return false;
+    const at = Math.max(0, list.findIndex((e) => sameTarget(e.target, this.currentTarget)));
+    const next = list[(at + delta + list.length) % list.length]!;
+    return this.open(next.target);
+  }
+
+  /**
+   * ctrl+x in a view. The first press arms and returns 'armed'; a second
+   * press within STOP_CONFIRM_MS returns 'confirmed' (the caller stops the
+   * work). In main it returns 'none'.
+   */
+  pressStop(): 'armed' | 'confirmed' | 'none' {
+    if (!this.active) return 'none';
+    const now = this.deps.now?.() ?? Date.now();
+    if (this.armed && sameTarget(this.armed.target, this.currentTarget) && now - this.armed.at <= STOP_CONFIRM_MS) {
+      this.armed = null;
+      return 'confirmed';
+    }
+    this.armed = { target: this.currentTarget, at: now };
+    return 'armed';
+  }
+
+  /** Whether a first ctrl+x is waiting for its confirming press. */
+  stopArmed(): boolean {
+    if (!this.armed || !sameTarget(this.armed.target, this.currentTarget)) return false;
+    const now = this.deps.now?.() ?? Date.now();
+    return now - this.armed.at <= STOP_CONFIRM_MS;
+  }
+
+  disarm(): void { this.armed = null; }
+}