@pellux/goodvibes-tui 2.0.20 → 2.1.0

package/src/core/agent-view-render.ts

@@ -0,0 +1,157 @@
+/**
+ * agent-view-render.ts, one agent opened full screen.
+ *
+ * The agent becomes the session: its own transcript is the spine (drawn by
+ * the same lane-graph path as main, conversation-rendering.ts), the agents
+ * it spawned branch off it as lanes, and steers you sent that it has not
+ * picked up yet sit at the bottom marked as queued. Its lanes are drawn with
+ * the color base shifted (lane-graph/paint.ts withLaneColorBase) so its spine
+ * keeps the color its lane has in main.
+ *
+ *   row 0     ◆ engineer · the task · started by main 2m 14s ago
+ *   row 1     (blank)
+ *   rows      the agent's transcript
+ *
+ * A WRFC chain owner takes no turns of its own: its view is its chain, each
+ * phase agent a lane off its spine drawn from that agent's own transcript
+ * (work-tree-model.ts buildWrfcOwnerModel).
+ *
+ * The thin bar down column 0, the blank rows above and below the body, and
+ * the scroll window are the caller's (shell/session-views.ts); this returns
+ * every line.
+ */
+
+import { createEmptyLine, type Line } from '@pellux/goodvibes-sdk/platform/types';
+import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+import { appendConversationMessages, drawConversationTurn, type ConversationRenderContext } from './conversation-rendering.ts';
+import { buildWrfcOwnerModel } from './work-tree-model.ts';
+import type { AgentLaneInfo, WorkTreeSources } from './work-tree-sources.ts';
+import { laneColor, withLaneColorBase } from '../renderer/lane-graph/paint.ts';
+import type { TreeGlyphSetName } from '../renderer/lane-graph/glyphs.ts';
+import { UIFactory } from '../renderer/ui-factory.ts';
+import { activeTokens } from '../renderer/theme.ts';
+import { formatElapsed } from '../utils/format-elapsed.ts';
+import { getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
+
+export interface AgentViewInput {
+  readonly width: number;
+  readonly agent: AgentLaneInfo;
+  /** The agent's transcript (its lane info carries none for a WRFC owner). */
+  readonly messages: readonly ConversationMessageSnapshot[];
+  /** The agent's lane color index in main. */
+  readonly colorIndex: number;
+  /** Who started it: "main" or the parent agent's name. */
+  readonly parentName: string;
+  /** Main's work-tree sources (timings, spawned agents, waiting calls). */
+  readonly sources: WorkTreeSources;
+  /** Fold state for this view's beads; kept by the caller across frames. */
+  readonly collapse: Map<string, boolean>;
+  readonly glyphSet: TreeGlyphSetName;
+  readonly frame: number;
+  readonly now: number;
+  /** Steers sent from this view that the agent has not picked up yet, oldest first. */
+  readonly queuedSteers: readonly string[];
+}
+
+const TEXT_X = 3;
+
+function put(line: Line, x: number, endX: number, text: string, style: { fg: string; bold?: boolean }): number {
+  let cx = x;
+  for (const ch of text) {
+    const w = getDisplayWidth(ch);
+    if (w <= 0) continue;
+    if (cx + w > endX || cx >= line.length) break;
+    line[cx] = { char: ch, fg: style.fg, bg: '', bold: style.bold ?? false, dim: false, underline: false, italic: false, strikethrough: false };
+    if (w === 2 && cx + 1 < line.length) line[cx + 1] = { ...line[cx]!, char: '' };
+    cx += w;
+  }
+  return cx;
+}
+
+function stateText(agent: AgentLaneInfo, parentName: string, now: number): { text: string; tone: 'faint' | 'good' | 'bad' | 'warn' } {
+  const started = agent.startedAt !== undefined ? `started by ${parentName} ${formatElapsed(Math.max(0, now - agent.startedAt))} ago` : `started by ${parentName}`;
+  switch (agent.status) {
+    case 'running': return { text: started, tone: 'faint' };
+    case 'pending': return { text: `waiting to start · ${started}`, tone: 'faint' };
+    case 'completed': {
+      const took = agent.startedAt !== undefined && agent.completedAt !== undefined ? ` in ${formatElapsed(agent.completedAt - agent.startedAt)}` : '';
+      return { text: `finished${took} · ${agent.toolCallCount} tool${agent.toolCallCount === 1 ? '' : 's'}`, tone: 'good' };
+    }
+    case 'failed': return { text: `failed${agent.error ? `: ${agent.error.split('\n')[0]}` : ''}`, tone: 'bad' };
+    case 'cancelled': return { text: 'stopped', tone: 'warn' };
+  }
+}
+
+/** The ◆ head row. */
+function headRow(input: AgentViewInput): Line {
+  const t = activeTokens();
+  const line = createEmptyLine(input.width);
+  for (const cell of line) cell.bg = '';
+  const end = input.width - 3;
+  const color = laneColor(input.colorIndex);
+  let x = put(line, TEXT_X, end, '◆', { fg: color, bold: true });
+  // A chain owner is named for what it is, as its lane in main is.
+  x = put(line, x + 1, end, input.agent.wrfcPhases ? 'WRFC chain' : input.agent.hostedLabel ?? input.agent.name, { fg: color, bold: true });
+  const state = stateText(input.agent, input.parentName, input.now);
+  const stateFg = state.tone === 'good' ? t.success : state.tone === 'bad' ? t.error : state.tone === 'warn' ? t.warning : t.textFaint;
+  const task = input.agent.task.split('\n').find((l) => l.trim().length > 0)?.trim() ?? '';
+  // The state is kept whole; the task yields its room first.
+  const stateW = getDisplayWidth(state.text) + 3;
+  const taskRoom = end - x - 3 - stateW;
+  if (task && taskRoom >= 8) {
+    x = put(line, x + 1, end, '·', { fg: t.textFaint });
+    x = put(line, x + 1, end, truncateDisplay(task, taskRoom), { fg: t.textMuted });
+  }
+  x = put(line, x + 1, end, '·', { fg: t.textFaint });
+  put(line, x + 1, end, truncateDisplay(state.text, Math.max(0, end - x - 1)), { fg: stateFg });
+  return line;
+}
+
+/** Every line of the agent view, top to bottom. */
+export function renderAgentView(input: AgentViewInput): Line[] {
+  const t = activeTokens();
+  const lines: Line[] = [headRow(input), createEmptyLine(input.width)];
+  const running = input.agent.status === 'running' || input.agent.status === 'pending';
+  const context: ConversationRenderContext = {
+    history: { addLine: (l) => { lines.push(l); }, addLines: (ls) => { lines.push(...ls); }, getLineCount: () => lines.length },
+    blockRegistry: [],
+    collapseState: input.collapse,
+    errorLineRegistry: [],
+    messageKindRegistry: new Map(),
+    configManager: null,
+    splashOptions: {},
+    // The agent's own turns are live while the agent runs, not while main does.
+    workTreeSources: { ...input.sources, turnActive: () => running, turnTiming: undefined },
+    treeGlyphSet: input.glyphSet,
+    focusId: null,
+    frame: input.frame,
+  };
+  const phases = input.agent.wrfcPhases;
+  if (phases) {
+    if (phases.length > 0) {
+      const model = buildWrfcOwnerModel({ info: input.agent, sources: context.workTreeSources ?? {}, collapse: input.collapse });
+      withLaneColorBase(input.colorIndex, () => { lines.push(...drawConversationTurn(context, model, input.width).lines); });
+    }
+  } else {
+    withLaneColorBase(input.colorIndex, () => appendConversationMessages(context, [...input.messages], input.width, []));
+  }
+  const empty = phases ? phases.length === 0 : input.messages.length === 0;
+  if (empty) {
+    const note = createEmptyLine(input.width);
+    for (const cell of note) cell.bg = '';
+    const text = phases
+      ? (running ? 'The chain has not started a phase yet.' : 'This chain ran no phases.')
+      : running ? 'No transcript yet: the agent has not taken a turn.' : 'This agent left no transcript.';
+    put(note, TEXT_X + 2, input.width - 3, text, { fg: t.textFaint });
+    lines.push(note);
+  }
+  for (const steer of input.queuedSteers) {
+    lines.push(createEmptyLine(input.width));
+    lines.push(...UIFactory.createMessageBar(input.width, steer));
+    const note = createEmptyLine(input.width);
+    for (const cell of note) cell.bg = '';
+    put(note, TEXT_X + 2, input.width - 3, '⧗ queued · it arrives at the agent\'s next turn', { fg: t.textFaint });
+    lines.push(note);
+  }
+  return lines;
+}

package/src/core/approval-alert.ts

@@ -14,16 +14,30 @@
  * wrapped promise settles) so it reflects "a prompt just appeared", not
  * "a prompt was just resolved".
  *
- * PRIVACY: message content is tool name + permission category only, no
- * args, no file contents, no command strings (mirrors long-task-notifier's
- * privacy guarantee).
+ * Text (owner ruling 2026-09-29, SDK runtime/turn-notification.ts): the
+ * notice names what is waiting, the command for exec, the file for write and
+ * edit, the URL for fetch, and the turn that asked for it. When
+ * behavior.notificationsMetadataOnly is on (default off) every channel here
+ * (OSC 9, desktop, webhook) sends the tool name and permission category only,
+ * never a command, a path or the turn's name.
  */
 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 { PermissionRequestHandler, PermissionPromptRequest } from '@pellux/goodvibes-sdk/platform/permissions';
 import type { FocusTracker } from '@pellux/goodvibes-sdk/platform/runtime/operations';
-import { shouldFireAlert, FORCE_NOTIFY_DURATION_MS, type ConfigGet } from '@pellux/goodvibes-sdk/platform/runtime/operations';
+import {
+  shouldFireAlert,
+  FORCE_NOTIFY_DURATION_MS,
+  NOTIFICATION_TEXT_LIMITS,
+  buildApprovalNotification,
+  describeToolTarget,
+  formatWebhookText,
+  joinNotificationLine,
+  readNotificationsMetadataOnly,
+  resolveTurnName,
+  type ConfigGet,
+} from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { TerminalNotifier } from './terminal-notifier.ts';
 
 export interface ApprovalAlertDeps {
@@ -37,6 +51,21 @@ export interface ApprovalAlertDeps {
    * desktop-alert gate below). Absent in tests/headless.
    */
   readonly terminalNotifier?: TerminalNotifier | null;
+  /**
+   * The live conversation, read for the name of the turn that is asking: a
+   * title the user set, else the message that started this turn (the last
+   * user message while a turn runs). Absent means the notice names no turn.
+   */
+  readonly conversation?: ApprovalTurnSource | null;
+  /** Desktop delivery; defaults to the SDK notifyCompletion. Tests pass a spy to read the text. */
+  readonly notifyDesktop?: typeof notifyCompletion;
+}
+
+/** The conversation surface the approval notice names the turn from. */
+export interface ApprovalTurnSource {
+  readonly title: string;
+  getTitleSource(): string;
+  getLastUserMessage(): string | null;
 }
 
 /**
@@ -56,19 +85,28 @@ export function wrapRequestPermissionWithAlert(
 }
 
 function fireApprovalAlert(request: PermissionPromptRequest, deps: ApprovalAlertDeps): void {
-  // PRIVACY: tool name + category only. Never request.args.
-  const message = `${request.tool} (${request.category}) is waiting for approval`;
+  const metadataOnly = readNotificationsMetadataOnly(deps.configGet);
+  const conversation = deps.conversation;
+  const titleSource = conversation?.getTitleSource();
+  const notice = buildApprovalNotification({
+    tool: request.tool,
+    category: request.category,
+    target: metadataOnly ? null : describeToolTarget(request.args, request.analysis?.target),
+    turnName: metadataOnly || !conversation ? null : resolveTurnName({
+      title: conversation.title,
+      titleSource: titleSource === 'user' || titleSource === 'system' ? titleSource : null,
+      turnText: conversation.getLastUserMessage(),
+    }),
+  }, { metadataOnly });
 
   // In-terminal (OSC 9) notification fires on its OWN gating (independent of the
   // desktop-alert gate below), so it is emitted before the early return.
-  deps.terminalNotifier?.notify('approval-wait', message);
+  deps.terminalNotifier?.notify('approval-wait', joinNotificationLine(notice, NOTIFICATION_TEXT_LIMITS.terminal));
 
   if (!shouldFireAlert(deps.focusTracker, deps.configGet, 'behavior.notifyOnApprovalPending')) return;
 
-  const title = 'GoodVibes: approval needed';
-
   try {
-    notifyCompletion(title, message, FORCE_NOTIFY_DURATION_MS);
+    (deps.notifyDesktop ?? notifyCompletion)(notice.title, notice.body, FORCE_NOTIFY_DURATION_MS);
   } catch (err) {
     logger.debug('approval-alert: desktop notify error', { error: String(err) });
   }
@@ -77,7 +115,7 @@ function fireApprovalAlert(request: PermissionPromptRequest, deps: ApprovalAlert
   if (webhookNotifier) {
     const urls = webhookNotifier.getUrls();
     if (urls.length > 0) {
-      webhookNotifier.send(message).catch((err: unknown) => {
+      webhookNotifier.send(formatWebhookText(notice)).catch((err: unknown) => {
         logger.debug('approval-alert: webhook send error', { error: String(err) });
       });
     }

package/src/core/bookmark-navigation.ts

@@ -25,7 +25,13 @@
 
 import type { ConversationManager } from './conversation.ts';
 
-const MESSAGE_BOOKMARK_KEY = /^msg_(\d+)$/;
+/**
+ * `msg_<idx>` (a message block), or `bead_c:<idx>:<call>` (a work-tree bead of
+ * the main transcript: its call's message index). A bead inside a folded turn
+ * or lane has no block of its own; its message line is the row that stands
+ * for it (the folded turn's header, or the ◉ of its folded lane's spawn).
+ */
+const MESSAGE_BOOKMARK_KEY = /^(?:msg_|bead_c:)(\d+)(?::\d+)?$/;
 
 /**
  * Resolve a bookmark key that missed a direct BlockMeta lookup. Returns the

package/src/core/budget-breach-notifier.ts

@@ -13,18 +13,28 @@
  * (notifyCompletion) + outbound webhook (WebhookNotifier), both gated by
  * the shared focus/config gating in alert-gating.ts. Skips evaluation
  * entirely when the session model is unpriced, a $0 placeholder cost must
- * never be reported as a real breach (mirrors CostTrackerPanel's "unpriced"
+ * never be reported as a real breach (mirrors the usage modal's "unpriced"
  * display convention).
  *
- * PRIVACY: message text is built from cost/threshold numbers and the
- * session id prefix only, no conversation content.
+ * Text (owner ruling 2026-09-29, SDK runtime/turn-notification.ts): the
+ * notice names the budget that tripped (cost against the configured
+ * threshold) and the turn during which it tripped. When
+ * behavior.notificationsMetadataOnly is on (default off) the desktop and
+ * webhook text carries the numbers and the session id prefix only.
  */
 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 { calcSessionCost, computeBudgetBreach, isModelPriced } from '@pellux/goodvibes-sdk/platform/providers';
 import type { FocusTracker } from '@pellux/goodvibes-sdk/platform/runtime/operations';
-import { shouldFireAlert, FORCE_NOTIFY_DURATION_MS, type ConfigGet } from '@pellux/goodvibes-sdk/platform/runtime/operations';
+import {
+  shouldFireAlert,
+  FORCE_NOTIFY_DURATION_MS,
+  buildBudgetNotification,
+  formatWebhookText,
+  readNotificationsMetadataOnly,
+  type ConfigGet,
+} from '@pellux/goodvibes-sdk/platform/runtime/operations';
 
 export interface BudgetBreachUsageSnapshot {
   readonly input: number;
@@ -38,6 +48,10 @@ export interface BudgetBreachNotifierDeps {
   readonly configGet: ConfigGet;
   readonly webhookNotifier?: WebhookNotifier | null;
   readonly sessionId: string;
+  /** The name of the turn that just ended (the one during which the budget tripped). */
+  readonly getTurnName?: (() => string | null) | undefined;
+  /** Desktop delivery; defaults to the SDK notifyCompletion. Tests pass a spy to read the text. */
+  readonly notifyDesktop?: typeof notifyCompletion | undefined;
 }
 
 /** Stateful edge-trigger checker, construct once per session, call on every TURN_COMPLETED. */
@@ -85,11 +99,16 @@ export function createBudgetBreachNotifier(deps: BudgetBreachNotifierDeps): Budg
 function fireBudgetBreachAlert(deps: BudgetBreachNotifierDeps, sessionCost: number, budgetThresholdUsd: number): void {
   if (!shouldFireAlert(deps.focusTracker, deps.configGet, 'behavior.notifyOnBudgetBreach')) return;
 
-  const title = 'GoodVibes: budget breach';
-  const message = `session cost $${sessionCost.toFixed(2)} exceeded budget $${budgetThresholdUsd.toFixed(2)}  ·  session ${deps.sessionId.slice(0, 8)}`;
+  const metadataOnly = readNotificationsMetadataOnly(deps.configGet);
+  const notice = buildBudgetNotification({
+    sessionCostUsd: sessionCost,
+    budgetUsd: budgetThresholdUsd,
+    sessionId: deps.sessionId,
+    turnName: metadataOnly ? null : deps.getTurnName?.() ?? null,
+  }, { metadataOnly });
 
   try {
-    notifyCompletion(title, message, FORCE_NOTIFY_DURATION_MS);
+    (deps.notifyDesktop ?? notifyCompletion)(notice.title, notice.body, FORCE_NOTIFY_DURATION_MS);
   } catch (err) {
     logger.debug('budget-breach-notifier: desktop notify error', { error: String(err) });
   }
@@ -98,7 +117,7 @@ function fireBudgetBreachAlert(deps: BudgetBreachNotifierDeps, sessionCost: numb
   if (webhookNotifier) {
     const urls = webhookNotifier.getUrls();
     if (urls.length > 0) {
-      webhookNotifier.send(message).catch((err: unknown) => {
+      webhookNotifier.send(formatWebhookText(notice)).catch((err: unknown) => {
         logger.debug('budget-breach-notifier: webhook send error', { error: String(err) });
       });
     }

package/src/core/compaction-receipt.ts

@@ -15,7 +15,7 @@
  *
  * The `[Compaction]` prefix is one of the FORCE_CONVERSATION_PREFIXES the
  * system-message router always surfaces inline (see system-message-router.ts),
- * so the receipt cannot be routed away into a panel and vanish.
+ * so the receipt cannot be routed away from the transcript and vanish.
  */
 
 /** The shape of the SDK's COMPACTION_RECEIPT event payload we render from. */

package/src/core/context-usage.ts

@@ -1,7 +1,7 @@
 /**
  * Shared context-window usage computation.
  *
- * Centralises the tokens/contextWindow ratio so all panels, auto-compact,
+ * Centralises the tokens/contextWindow ratio so all views, auto-compact,
  * and session-maintenance read from one formula rather than six diverging
  * hand-rolled copies.
  *

package/src/core/conversation-compaction-render.ts

@@ -7,7 +7,7 @@
  * architecture line-count gate; behaviour is unchanged.
  */
 
-import { activeTheme } from '../renderer/theme.ts';
+import { activeTheme, activeTokens } from '../renderer/theme.ts';
 import { renderMarkdownTracked } from '../renderer/markdown.ts';
 import { renderConversationEventLine, renderConversationFoldedRow } from '../renderer/conversation-surface.ts';
 import { GLYPHS } from '../renderer/ui-primitives.ts';
@@ -54,10 +54,10 @@ export function renderCompactionContinuationMessage(
     markerFg: T.toolAccent,
     label: 'compaction handoff',
     labelFg: T.toolAccent,
-    detailFg: '244',
+    detailFg: activeTokens().textMuted,
   };
   const details = [
-    { text: ` ${isCollapsed ? GLYPHS.navigation.collapsed : GLYPHS.navigation.expanded} ${lineCount} line${lineCount === 1 ? '' : 's'} `, fg: '244', dim: true },
+    { text: ` ${isCollapsed ? GLYPHS.navigation.collapsed : GLYPHS.navigation.expanded} ${lineCount} line${lineCount === 1 ? '' : 's'} `, fg: activeTokens().textFaint },
   ];
 
   if (isCollapsed) {

package/src/core/conversation-display-only.ts

@@ -0,0 +1,86 @@
+/**
+ * conversation-display-only.ts, the display-only output a conversation keeps.
+ *
+ * A command's printed text or a tool result row is drawn into the transcript
+ * but is not a message, so a rebuild (a resize, a theme change, the splash
+ * leaving) would drop it. ConversationManager keeps each such draw here, with
+ * the number of messages that existed when it was drawn, and draws it again
+ * in the same place on every rebuild. While a reply streams, draws made during
+ * the turn sit below the streamed text and are drawn again after each delta.
+ */
+
+/** Display-only draws kept for redraw; the oldest leave first. */
+const MAX_DISPLAY_ONLY_ENTRIES = 500;
+
+interface DisplayOnlyEntry {
+  readonly seq: number;
+  /** Messages that existed when it was drawn: it goes right after the unit holding message `anchor - 1`. */
+  readonly anchor: number;
+  readonly draw: (width: number) => void;
+}
+
+/** One rebuild's walk over the kept draws, in order. */
+export interface DisplayOnlyCursor {
+  /** Draw every kept entry printed while messages up to `lastIndex` existed. */
+  through(lastIndex: number): void;
+  /** During a streaming rebuild: the entries not yet drawn go below the streamed text. */
+  trailStreamed(lineCount: () => number): void;
+}
+
+export class DisplayOnlyOutput {
+  private entries: DisplayOnlyEntry[] = [];
+  private seq = 0;
+  /** While a reply streams, draws from this seq on sit below the streamed text. */
+  private trailingFromSeq = Number.POSITIVE_INFINITY;
+  /** Lines those trailing draws take, below the streamed text. */
+  trailingLineCount = 0;
+
+  get count(): number { return this.entries.length; }
+
+  drop(): void {
+    this.entries = [];
+    this.resetTrailing();
+  }
+
+  resetTrailing(): void {
+    this.trailingFromSeq = Number.POSITIVE_INFINITY;
+    this.trailingLineCount = 0;
+  }
+
+  /** Keep a draw; `anchor` is the message count when it was printed. */
+  keep(anchor: number, draw: (width: number) => void): number {
+    const seq = ++this.seq;
+    this.entries.push({ seq, anchor, draw });
+    if (this.entries.length > MAX_DISPLAY_ONLY_ENTRIES) this.entries.splice(0, this.entries.length - MAX_DISPLAY_ONLY_ENTRIES);
+    return seq;
+  }
+
+  /** A kept draw was just drawn at the end of the buffer; while streaming it trails the streamed text. */
+  noteDrawn(seq: number, lines: number, streaming: boolean): void {
+    if (!streaming) return;
+    if (this.trailingFromSeq === Number.POSITIVE_INFINITY) this.trailingFromSeq = seq;
+    this.trailingLineCount += lines;
+  }
+
+  /** Draw the entries kept below the streamed text again, and count their lines. */
+  drawTrailing(width: number, lineCount: () => number): void {
+    const before = lineCount();
+    for (const entry of this.entries) if (entry.seq >= this.trailingFromSeq) entry.draw(width);
+    this.trailingLineCount = lineCount() - before;
+  }
+
+  cursor(width: number): DisplayOnlyCursor {
+    const kept = this.entries;
+    let next = 0;
+    return {
+      through: (lastIndex) => {
+        while (next < kept.length && kept[next]!.anchor <= lastIndex + 1) kept[next++]!.draw(width);
+      },
+      trailStreamed: (lineCount) => {
+        if (next >= kept.length) return;
+        this.trailingFromSeq = kept[next]!.seq;
+        this.drawTrailing(width, lineCount);
+      },
+    };
+  }
+}

package/src/core/conversation-event-navigation.ts

@@ -40,3 +40,30 @@ export function resolveTranscriptEventLine(
   }
   return [...lines].reverse().find((line) => line < currentLine) ?? lines[lines.length - 1]!;
 }
+
+/** The next (or previous) line in a sorted list after (or before) `currentLine`, wrapping around; -1 when the list is empty. */
+export function wrapToLine(lines: readonly number[], currentLine: number, direction: 'next' | 'prev'): number {
+  if (lines.length === 0) return -1;
+  if (direction === 'next') return lines.find((line) => line > currentLine) ?? lines[0]!;
+  return [...lines].reverse().find((line) => line < currentLine) ?? lines[lines.length - 1]!;
+}
+
+/** The block containing `lineIndex`, else the one starting nearest it (optionally only blocks of `typeFilter`). */
+export function nearestBlock<B extends { readonly type: string; readonly startLine: number; readonly lineCount: number }>(
+  blocks: readonly B[],
+  lineIndex: number,
+  typeFilter?: string,
+): B | null {
+  let nearest: B | null = null;
+  let nearestDist = Infinity;
+  for (const block of blocks) {
+    if (typeFilter !== undefined && block.type !== typeFilter) continue;
+    if (lineIndex >= block.startLine && lineIndex < block.startLine + block.lineCount) return block;
+    const dist = Math.abs(block.startLine - lineIndex);
+    if (dist < nearestDist) {
+      nearestDist = dist;
+      nearest = block;
+    }
+  }
+  return nearest;
+}