@pellux/goodvibes-tui 1.17.0 → 1.19.0

package/src/panels/fleet-spawn.ts

@@ -0,0 +1,266 @@
+// ---------------------------------------------------------------------------
+// fleet-spawn.ts
+//
+// The Fleet panel's ACP spawn affordance: 'n' on the fleet surface lists the
+// third-party coding agents the daemon discovered (acp.agents.list — read-only,
+// quiet when none), you pick one, then pick a working directory from the known
+// candidates (the registered workspaces + the current dir — no free-text path
+// retyping where a known dir exists), and acp.sessions.create hosts it as a
+// long-lived daemon session. The new row shows up on the next fleet snapshot as
+// kind 'acp-agent' and steers/stops/flags-for-attention like any other row.
+//
+// A structured spawn failure ({binary, stage, message}) is surfaced verbatim —
+// never a hung row: the daemon bounds the handshake and returns a 'failed'
+// record, and this controller reports its three honest fields.
+//
+// The controller owns the fleet view + input while a pick is in flight (mirrors
+// FleetActs' pick mode), so fleet-panel.ts stays a thin delegator under the
+// architecture line cap. The gateway is injectable so the flow round-trips
+// against a mocked daemon in tests; the live builder is createAcpSpawnGateway.
+// ---------------------------------------------------------------------------
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { Line } from '../types/grid.ts';
+import { resolveOperatorRpc } from '../input/commands/operator-rpc.ts';
+import {
+  buildKeyboardHints,
+  buildPanelWorkspace,
+  buildPanelLine,
+  DEFAULT_PANEL_PALETTE,
+  type PanelPalette,
+} from './polish.ts';
+
+/** One discovered third-party ACP agent (acp.agents.list). */
+export type AcpDiscoveredAgent = OperatorMethodOutput<'acp.agents.list'>['agents'][number];
+/** acp.sessions.create output — the hosted record + whether it started. */
+export type AcpSpawnResult = OperatorMethodOutput<'acp.sessions.create'>;
+/** One registered workspace root (workspaces.registrations.list). */
+export type AcpWorkspaceRegistration = OperatorMethodOutput<'workspaces.registrations.list'>['workspaces'][number];
+
+/** A working-directory candidate offered in the picker: a known dir, never retyped. */
+export interface AcpDirCandidate {
+  readonly path: string;
+  /** A short human label (a workspace label, or "current directory"). */
+  readonly label: string;
+}
+
+/**
+ * The async verb surface the spawn flow drives — real daemon round-trips in
+ * production (createAcpSpawnGateway), a mocked shape in tests.
+ */
+export interface AcpSpawnGateway {
+  /** Discovered third-party agents (read-only; empty is a quiet, honest absence). */
+  listAgents(): Promise<readonly AcpDiscoveredAgent[]>;
+  /** The registered workspace roots — the known-dir candidates for the picker. */
+  listWorkspaces(): Promise<readonly AcpWorkspaceRegistration[]>;
+  /** Host a discovered agent in a directory as a long-lived daemon session. */
+  createSession(input: { readonly agentId: string; readonly cwd: string }): Promise<AcpSpawnResult>;
+}
+
+export type AcpSpawnGatewayResolution =
+  | { readonly available: true; readonly gateway: AcpSpawnGateway }
+  | { readonly available: false; readonly reason: string };
+
+export interface AcpSpawnGatewayDeps {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string | (() => string);
+}
+
+/**
+ * Build the live ACP spawn gateway over the generic operator invoke path — the
+ * same daemon resolution the fleet acts use. Honest unavailable reason when no
+ * daemon is reachable, so the spawn key refuses cleanly instead of throwing.
+ */
+export function createAcpSpawnGateway(deps: AcpSpawnGatewayDeps): AcpSpawnGatewayResolution {
+  const rpc = resolveOperatorRpc(deps);
+  if (!rpc.available) return { available: false, reason: rpc.reason };
+  const { sdk } = rpc;
+  const gateway: AcpSpawnGateway = {
+    listAgents: async () => (await sdk.operator.invoke('acp.agents.list', {})).agents,
+    listWorkspaces: async () => (await sdk.operator.invoke('workspaces.registrations.list', {})).workspaces,
+    createSession: (input) => sdk.operator.invoke('acp.sessions.create', input),
+  };
+  return { available: true, gateway };
+}
+
+export interface FleetSpawnDeps {
+  /** Resolve a live gateway per action (a daemon that comes up mid-session is seen). */
+  readonly resolveGateway: () => AcpSpawnGatewayResolution;
+  /** The current working directory — always a candidate dir (labeled "current directory"). */
+  readonly currentDirectory: () => string;
+  /** Surface a result/receipt/error line to the operator (system message). */
+  readonly notify: (message: string) => void;
+  /** Repaint request when the controller's own mode state changes. */
+  readonly markDirty: () => void;
+}
+
+/** Pick a third-party agent to host. */
+interface AgentStep {
+  readonly step: 'agent';
+  readonly agents: readonly AcpDiscoveredAgent[];
+  index: number;
+}
+/** Pick the working directory the hosted agent runs in. */
+interface DirStep {
+  readonly step: 'dir';
+  readonly agent: AcpDiscoveredAgent;
+  readonly candidates: readonly AcpDirCandidate[];
+  index: number;
+}
+type SpawnMode = AgentStep | DirStep | null;
+
+const C = DEFAULT_PANEL_PALETTE;
+
+export class FleetSpawn {
+  private mode: SpawnMode = null;
+  /** True while a create round-trip is in flight (absorb keys, show a spinner line). */
+  private creating = false;
+
+  public constructor(private readonly deps: FleetSpawnDeps) {}
+
+  /** True while the spawn picker owns the fleet view + input. */
+  public spawnModeActive(): boolean {
+    return this.mode !== null;
+  }
+
+  /**
+   * Begin the spawn flow: list discovered agents. Quiet, honest absence when the
+   * daemon reports none (no mode entered) rather than an empty picker.
+   */
+  public async begin(): Promise<void> {
+    if (this.mode !== null || this.creating) return;
+    const gateway = this.requireGateway();
+    if (!gateway) return;
+    let agents: readonly AcpDiscoveredAgent[];
+    try {
+      agents = await gateway.listAgents();
+    } catch (err) {
+      this.deps.notify(`Could not list ACP agents: ${summarizeError(err)}`);
+      return;
+    }
+    if (agents.length === 0) {
+      this.deps.notify('No third-party ACP agents discovered (Claude Code, Codex, opencode). Install one on PATH to host it here.');
+      return;
+    }
+    this.mode = { step: 'agent', agents, index: 0 };
+    this.deps.markDirty();
+  }
+
+  /** Input while the spawn picker is active. Absorbs every key it owns. */
+  public handleSpawnInput(key: string): boolean {
+    if (!this.mode || this.creating) return true;
+    if (key === 'escape' || key === 'esc') { this.mode = null; this.deps.markDirty(); return true; }
+    const list = this.mode.step === 'agent' ? this.mode.agents : this.mode.candidates;
+    if (key === 'up' || key === 'k') { this.mode.index = (this.mode.index - 1 + list.length) % list.length; this.deps.markDirty(); return true; }
+    if (key === 'down' || key === 'j') { this.mode.index = (this.mode.index + 1) % list.length; this.deps.markDirty(); return true; }
+    if (key === 'enter' || key === 'return') { void this.advance(); return true; }
+    return true;
+  }
+
+  /** Enter on the current step: agent → dir picker; dir → create the session. */
+  private async advance(): Promise<void> {
+    if (!this.mode) return;
+    if (this.mode.step === 'agent') {
+      const agent = this.mode.agents[this.mode.index];
+      if (!agent) return;
+      const candidates = await this.resolveDirCandidates();
+      this.mode = { step: 'dir', agent, candidates, index: 0 };
+      this.deps.markDirty();
+      return;
+    }
+    const cwd = this.mode.candidates[this.mode.index]?.path;
+    const agentId = this.mode.agent.id;
+    if (!cwd) return;
+    await this.createSession(agentId, cwd);
+  }
+
+  /** The known-dir candidates: the current directory first, then registered workspaces (deduped). */
+  private async resolveDirCandidates(): Promise<AcpDirCandidate[]> {
+    const current = this.deps.currentDirectory();
+    const candidates: AcpDirCandidate[] = [{ path: current, label: 'current directory' }];
+    const gateway = this.requireGateway();
+    if (gateway) {
+      try {
+        for (const ws of await gateway.listWorkspaces()) {
+          if (ws.root === current) continue; // already offered as "current directory"
+          candidates.push({ path: ws.root, label: ws.label ?? 'workspace' });
+        }
+      } catch {
+        // A workspaces read failure is non-fatal: the current dir is still offered.
+      }
+    }
+    return candidates;
+  }
+
+  /** Drive acp.sessions.create and surface the honest outcome (success or structured failure). */
+  private async createSession(agentId: string, cwd: string): Promise<void> {
+    const gateway = this.requireGateway();
+    if (!gateway) { this.mode = null; this.deps.markDirty(); return; }
+    this.creating = true;
+    this.deps.markDirty();
+    try {
+      const result = await gateway.createSession({ agentId, cwd });
+      const hosted = result.hosted;
+      if (hosted.error) {
+        // Structured failure rendered verbatim — never a hung row.
+        this.deps.notify(`[Fleet] Could not host ${hosted.title || agentId}: ${hosted.error.stage} stage failed for ${hosted.error.binary} — ${hosted.error.message}`);
+      } else {
+        this.deps.notify(`[Fleet] Hosting ${hosted.title || agentId} in ${cwd} — it appears as an acp-agent row; steer and stop it like any agent.`);
+      }
+    } catch (err) {
+      this.deps.notify(`ACP session create failed: ${summarizeError(err)}`);
+    } finally {
+      this.creating = false;
+      this.mode = null;
+      this.deps.markDirty();
+    }
+  }
+
+  /** The spawn picker view (replaces the tree while a pick is in flight). */
+  public renderSpawnMode(width: number, height: number, palette: PanelPalette = C): Line[] {
+    const P = palette;
+    if (!this.mode) return [];
+    const lines: Line[] = [];
+    if (this.creating) {
+      lines.push(buildPanelLine(width, [[' Hosting the agent…', P.dim]]));
+      return buildPanelWorkspace(width, height, { title: 'Fleet — Host an agent', sections: [{ lines }], footerLines: [], palette: P });
+    }
+    if (this.mode.step === 'agent') {
+      lines.push(buildPanelLine(width, [[' Host a third-party coding agent — pick one, then a directory.', P.dim]]));
+      lines.push(buildPanelLine(width, [['', P.dim]]));
+      this.mode.agents.forEach((agent, i) => {
+        const selected = i === (this.mode as AgentStep).index;
+        lines.push(buildPanelLine(width, [
+          [selected ? ' ▸ ' : '   ', selected ? P.info : P.dim],
+          [agent.title, selected ? P.value : P.dim],
+          [`  — ${agent.binaryPath}`, P.dim],
+        ]));
+      });
+    } else {
+      lines.push(buildPanelLine(width, [[` Directory for ${this.mode.agent.title} — a known dir, no path to type.`, P.dim]]));
+      lines.push(buildPanelLine(width, [['', P.dim]]));
+      this.mode.candidates.forEach((cand, i) => {
+        const selected = i === (this.mode as DirStep).index;
+        lines.push(buildPanelLine(width, [
+          [selected ? ' ▸ ' : '   ', selected ? P.info : P.dim],
+          [cand.label, selected ? P.value : P.dim],
+          [`  — ${cand.path}`, P.dim],
+        ]));
+      });
+    }
+    const footerLines = [buildKeyboardHints(width, [
+      { keys: '↑↓', label: 'choose' },
+      { keys: 'Enter', label: this.mode.step === 'agent' ? 'pick agent' : 'host here' },
+      { keys: 'Esc', label: 'cancel' },
+    ], P)];
+    return buildPanelWorkspace(width, height, { title: 'Fleet — Host an agent', sections: [{ lines }], footerLines, palette: P });
+  }
+
+  private requireGateway(): AcpSpawnGateway | null {
+    const resolution = this.deps.resolveGateway();
+    if (!resolution.available) { this.deps.notify(`[Fleet] ${resolution.reason}`); return null; }
+    return resolution.gateway;
+  }
+}

package/src/panels/fleet-stop.ts

@@ -8,7 +8,13 @@
 // ---------------------------------------------------------------------------
 
 import type { ProcessNode, ProcessState } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
-import { fleetStateGlyph, fleetStateTone, isTerminalProcessState, type FleetStateTone, type FleetTreeRow } from './fleet-read-model.ts';
+import type { WorkItem } from '@pellux/goodvibes-sdk/platform/orchestration';
+import { fleetNodeAttention, fleetStateGlyph, fleetStateTone, isTerminalProcessState, type FleetStateTone, type FleetTreeRow } from './fleet-read-model.ts';
+
+/** True when a work-item node owns a worktree that worktrees.discard can act on (D from the tree). */
+function ownsWorktree(node: ProcessNode): boolean {
+  return Boolean((node.raw as { item?: WorkItem } | undefined)?.item?.worktreePath);
+}
 
 /** How long 'stopping…' lingers after a stop keypress before the true state is shown regardless (never masks a stuck kill). */
 export const STOP_SETTLE_MS = 1500;
@@ -123,9 +129,15 @@ export function buildFleetTreeHints(
 ): FleetHint[] {
   const live = selected !== undefined && !isTerminalProcessState(selected.state);
   const isPaused = selected !== undefined && selected.state === 'paused';
+  // Enter is context-sensitive: on a flagged pick/conflict row it acts, else it
+  // attaches. Name the act so the key is discoverable from the tree.
+  const attention = selected ? fleetNodeAttention(selected) : null;
+  const enterLabel = attention?.reason === 'pick' ? 'pick'
+    : attention?.reason === 'conflict' ? 'resolve conflict'
+      : 'attach';
   const hints: FleetHint[] = [
     { keys: 'j/k', label: 'navigate' },
-    { keys: 'Enter', label: 'attach' },
+    { keys: 'Enter', label: enterLabel },
   ];
   // Jump-to-blocked is offered whenever something is waiting on the operator,
   // in either view (the blocked nodes live in the active fleet, and the jump
@@ -144,9 +156,11 @@ export function buildFleetTreeHints(
   if (live && selected.capabilities.killable) hints.push({ keys: 'K', label: 'kill' });
   if (live && !isPaused && selected.capabilities.pausable) hints.push({ keys: 'p', label: 'pause' });
   if (isPaused && selected.capabilities.resumable) hints.push({ keys: 'p', label: 'resume' });
+  if (selected && ownsWorktree(selected)) hints.push({ keys: 'D', label: 'discard worktree' });
   if (selected && !live) hints.push({ keys: 'a', label: 'archive' });
   hints.push({ keys: 'A', label: 'archive finished' });
   hints.push({ keys: 'v', label: 'archived' });
+  hints.push({ keys: 'n', label: 'host agent' });
   hints.push({ keys: 'f', label: follow ? 'follow:on' : 'follow' });
   if (hasTabs) hints.push({ keys: '[ ]', label: 'tabs' });
   return hints;
@@ -178,3 +192,25 @@ export function countDescendantStats(rows: readonly FleetTreeRow[], nodeId: stri
   }
   return { total, active };
 }
+
+/**
+ * Build the confirm-overlay arm options for a cascade Kill of one node — the
+ * label carries the descendant count so the operator sees what a confirm takes
+ * down. Extracted from FleetPanel to keep that file under the 800-line cap.
+ */
+export function fleetKillConfirmArgs(
+  node: ProcessNode,
+  items: readonly FleetTreeRow[],
+  deps: { readonly kill: (id: string) => void; readonly markStopping: (id: string) => void },
+): { id: string; label: string; verb: string; onConfirm: () => void } {
+  const shortId = node.id.length > 8 ? node.id.slice(-8) : node.id;
+  const stats = countDescendantStats(items, node.id);
+  const suffix = stats.total > 0 ? ` (+${stats.total} descendant${stats.total === 1 ? '' : 's'}, ${stats.active} active)` : '';
+  return {
+    id: node.id,
+    label: `${node.kind} ${shortId}${suffix}`,
+    verb: 'Kill',
+    // Mark 'stopping…' only once the kill is confirmed, not while merely armed.
+    onConfirm: () => { deps.kill(node.id); deps.markStopping(node.id); },
+  };
+}

package/src/panels/fleet-tabs.ts

@@ -25,10 +25,10 @@ import { MessageLineCache } from '../core/conversation-line-cache.ts';
 import { fleetKindTag } from './fleet-read-model.ts';
 
 /** Node kinds that can be attached as a session tab. */
-export type FleetAttachableKind = 'agent' | 'wrfc-chain';
+export type FleetAttachableKind = 'agent' | 'wrfc-chain' | 'acp-agent';
 
 export function isAttachableFleetKind(kind: ProcessKind): kind is FleetAttachableKind {
-  return kind === 'agent' || kind === 'wrfc-chain';
+  return kind === 'agent' || kind === 'wrfc-chain' || kind === 'acp-agent';
 }
 
 /**

package/src/panels/memory-consolidation-gateway.ts

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// memory-consolidation-gateway.ts
+//
+// The async, daemon-backed verb the Memory modal's Proposals tab reads:
+// memory.consolidation.receipts (GET /api/memory/consolidation/receipts) — the
+// retained memory-consolidation run receipts plus the flattened
+// pendingProposals (contradiction / cross-scope-duplicate / stale-delete)
+// awaiting human review. The records a proposal references are already
+// marked into the review queue by the daemon (reviewState 'contradicted' with
+// a staleReason, or 'fresh' for cross-scope duplicates); this gateway is only
+// how the Memory modal learns WHAT was proposed and WHY, so it can show that
+// reason next to the affected records and offer a jump to them.
+//
+// No named facade exists on the in-process OperatorClient for this verb, so —
+// exactly like the Fleet gateway (fleet-gateway.ts) — it goes over the
+// generic operator invoke path (operator-rpc.ts's resolveOperatorRpc ->
+// sdk.operator.invoke), reaching the SAME daemon the command layer does. A
+// runtime without the consolidation scheduler answers an honest 501; an older
+// daemon that has not wired this route yet answers 404 — both are "verb
+// unavailable", not "no proposals" (see classifyConsolidationFetchError).
+//
+// The interface is injectable so the modal's proposals fetch round-trips
+// against a mocked daemon in tests; the live builder
+// (createMemoryConsolidationGateway) is wired in builtin-modals.ts, resolved
+// lazily (a fresh factory call per fetch) exactly like the Fleet gateway.
+// ---------------------------------------------------------------------------
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+import { GoodVibesSdkError } from '@pellux/goodvibes-sdk';
+import { resolveOperatorRpc, describeOperatorRpcError } from '../input/commands/operator-rpc.ts';
+
+/** memory.consolidation.receipts output — retained receipts + the flattened pending proposals. */
+export type MemoryConsolidationReceiptsResult = OperatorMethodOutput<'memory.consolidation.receipts'>;
+/** One pending judgment proposal (contradiction / cross-scope-duplicate / stale-delete) awaiting human review. */
+export type MemoryConsolidationProposal = MemoryConsolidationReceiptsResult['pendingProposals'][number];
+
+/** The narrow async verb surface the Memory modal's Proposals tab drives. */
+export interface MemoryConsolidationGateway {
+  /** Fetch the retained consolidation receipts + flattened pending proposals. */
+  fetchReceipts(): Promise<MemoryConsolidationReceiptsResult>;
+}
+
+/**
+ * Why the gateway could not be built (daemon disabled / no control-plane URL),
+ * surfaced verbatim so the modal can print an honest "unavailable" line
+ * rather than guessing — mirrors FleetGatewayResolution.
+ */
+export type MemoryConsolidationGatewayResolution =
+  | { readonly available: true; readonly gateway: MemoryConsolidationGateway }
+  | { readonly available: false; readonly reason: string };
+
+export interface MemoryConsolidationGatewayDeps {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string;
+}
+
+/**
+ * Build the live consolidation-receipts gateway over the generic operator
+ * invoke path — the same daemon resolution the command layer and the Fleet
+ * gateway use. Returns an honest unavailable reason when no daemon is
+ * reachable, so the modal can refuse cleanly instead of throwing mid-render.
+ */
+export function createMemoryConsolidationGateway(deps: MemoryConsolidationGatewayDeps): MemoryConsolidationGatewayResolution {
+  const rpc = resolveOperatorRpc({ configManager: deps.configManager, homeDirectory: deps.homeDirectory });
+  if (!rpc.available) return { available: false, reason: rpc.reason };
+  const { sdk } = rpc;
+  return {
+    available: true,
+    gateway: { fetchReceipts: () => sdk.operator.invoke('memory.consolidation.receipts', {}) },
+  };
+}
+
+/** How a `fetchReceipts()` rejection should render in the Proposals tab. */
+export type MemoryConsolidationFetchFailure =
+  | { readonly kind: 'unavailable'; readonly reason: string }
+  | { readonly kind: 'error'; readonly message: string };
+
+/**
+ * Classify a `fetchReceipts()` rejection: a 501 (the documented "no
+ * consolidation scheduler on this runtime" response) or a 404 (an older
+ * daemon that has not wired this route yet) are both "verb unavailable" —
+ * distinct from a generic request failure (network error, 401/403, 500),
+ * which renders as an honest fetch error instead. Reuses
+ * describeOperatorRpcError's wording so the two call sites (command layer,
+ * Fleet gateway, this gateway) never diverge on how they describe the same
+ * daemon response.
+ */
+export function classifyConsolidationFetchError(error: unknown): MemoryConsolidationFetchFailure {
+  if (error instanceof GoodVibesSdkError && (error.status === 501 || error.status === 404)) {
+    return { kind: 'unavailable', reason: describeOperatorRpcError(error) };
+  }
+  return { kind: 'error', message: describeOperatorRpcError(error) };
+}

package/src/panels/modals/devices-modal.ts

@@ -0,0 +1,161 @@
+import { MODAL_TONES } from './modal-theme.ts';
+import { infoRow } from './modal-surface-helpers.ts';
+import type {
+  ConfigModalActionContext,
+  ConfigModalRow,
+  ConfigModalSurface,
+  ConfigModalView,
+} from '../../input/config-modal-types.ts';
+import type { MintedPairingToken, PublicPairingToken } from '@pellux/goodvibes-sdk/platform/pairing';
+import { formatDeviceLine, shortTokenId } from '../../core/pairing-devices.ts';
+
+// ---------------------------------------------------------------------------
+// Paired Devices — the settings security-domain device/token management surface.
+// Lists every per-device pairing token (name · created · last-seen · id) and
+// mirrors the pairing.tokens.* gateway verbs: revoke a device, migrate off the
+// legacy shared token, revoke the shared token. Rename needs a name, which the
+// stable-layout modal cannot capture inline, so it routes to the /devices rename
+// command with the row's id pre-filled in the guidance. buildView reads list()
+// fresh every render, so a revoke/migrate reflects immediately.
+// ---------------------------------------------------------------------------
+
+/** The token-store capability this surface needs — satisfied by PairingTokenManager. */
+export interface DevicesModalPairingTokens {
+  list(): PublicPairingToken[];
+  rename(id: string, name: string): boolean;
+  revoke(id: string): boolean;
+  mintForMigration(input: { readonly name: string }): MintedPairingToken;
+  isLegacyRevoked(): boolean;
+  revokeLegacyShared(): void;
+}
+
+export interface DevicesModalDeps {
+  readonly pairingTokens: DevicesModalPairingTokens;
+  /** Injectable clock so last-seen formatting is deterministic in tests. */
+  readonly now?: () => number;
+  readonly copyToClipboard?: (text: string) => void;
+}
+
+const DEVICE_ROW_PREFIX = 'device:';
+
+function deviceIdOf(row: ConfigModalRow | null): string | null {
+  return row && row.id.startsWith(DEVICE_ROW_PREFIX) ? row.id.slice(DEVICE_ROW_PREFIX.length) : null;
+}
+
+class DevicesModalSurface implements ConfigModalSurface {
+  readonly name = 'devices-modal';
+  readonly title = 'Paired Devices';
+  private requestRender: () => void = () => {};
+
+  constructor(private readonly deps: DevicesModalDeps) {}
+
+  readonly actions = [
+    { key: 'r', id: 'rename', label: 'rename', enabledFor: (row: ConfigModalRow | null) => deviceIdOf(row) !== null },
+    { key: 'x', id: 'revoke', label: 'revoke', confirm: true, enabledFor: (row: ConfigModalRow | null) => deviceIdOf(row) !== null },
+    { key: 'm', id: 'migrateShared', label: 'migrate off shared token' },
+    { key: 's', id: 'revokeShared', label: 'revoke shared token', confirm: true, enabledFor: () => !this.deps.pairingTokens.isLegacyRevoked() },
+  ];
+
+  onOpen(requestRender: () => void): void { this.requestRender = requestRender; }
+
+  buildView(): ConfigModalView {
+    const now = this.deps.now?.() ?? Date.now();
+    const tokens = this.deps.pairingTokens.list();
+    const rows: ConfigModalRow[] = [];
+    rows.push(infoRow('intro', 'Devices paired to this daemon. Each has its own token — revoke one without affecting the others.', { dim: true }));
+
+    if (tokens.length === 0) {
+      rows.push(infoRow('empty', 'No devices paired yet — run /pair (or open the pairing QR) to add one.'));
+    } else {
+      for (const token of tokens) {
+        rows.push({ id: `${DEVICE_ROW_PREFIX}${token.id}`, label: formatDeviceLine(token, now) });
+      }
+    }
+
+    const legacyRevoked = this.deps.pairingTokens.isLegacyRevoked();
+    rows.push(infoRow(
+      'legacy',
+      legacyRevoked
+        ? 'Legacy shared token: revoked.'
+        : 'Legacy shared token: active — migrate a device off it (m), then revoke it (s).',
+      legacyRevoked ? { dim: true } : { fg: MODAL_TONES.reasoning },
+    ));
+
+    return {
+      title: 'Paired Devices',
+      tabs: [{ id: 'devices', label: 'Devices', rows, hints: ['r rename', 'x revoke', 'm migrate off shared', 's revoke shared'] }],
+    };
+  }
+
+  onAction(id: string, ctx: ConfigModalActionContext): void {
+    const tokens = this.deps.pairingTokens;
+
+    if (id === 'rename') {
+      const deviceId = deviceIdOf(ctx.row);
+      if (!deviceId) { ctx.setStatus('Select a device row first.'); return; }
+      // The stable-layout modal cannot capture a name inline — route to the
+      // command with the id pre-filled so the user only types the new name.
+      ctx.print(`To rename this device, run:  /devices rename ${shortTokenId(deviceId)} <new name>`);
+      return;
+    }
+
+    if (id === 'revoke') {
+      const deviceId = deviceIdOf(ctx.row);
+      if (!deviceId) { ctx.setStatus('Select a device row first.'); return; }
+      const record = tokens.list().find((t) => t.id === deviceId);
+      const revoked = tokens.revoke(deviceId);
+      ctx.setStatus(revoked ? `Revoked "${record?.name ?? shortTokenId(deviceId)}" — its token stops working now.` : 'That device was already absent.');
+      this.requestRender();
+      return;
+    }
+
+    if (id === 'migrateShared') {
+      const minted = tokens.mintForMigration({ name: 'migrated device' });
+      if (this.deps.copyToClipboard) {
+        this.deps.copyToClipboard(minted.token);
+        ctx.print(`Minted "${minted.name}" and copied its one-time token to the clipboard. Pair the device, then revoke the shared token (s).`);
+      } else {
+        ctx.print(`Minted "${minted.name}" (one-time token): ${minted.token}\nPair the device with it, then revoke the shared token (s).`);
+      }
+      this.requestRender();
+      return;
+    }
+
+    if (id === 'revokeShared') {
+      if (tokens.isLegacyRevoked()) { ctx.setStatus('The legacy shared token is already revoked.'); return; }
+      tokens.revokeLegacyShared();
+      ctx.setStatus('Revoked the legacy shared token — devices on it must re-pair with their own token.');
+      this.requestRender();
+      return;
+    }
+  }
+}
+
+export function createDevicesModalSurface(deps: DevicesModalDeps): ConfigModalSurface {
+  return new DevicesModalSurface(deps);
+}
+
+/**
+ * Deterministic golden/render fixture: frozen token list + clock so last-seen
+ * formatting is stable.
+ */
+export function devicesModalGoldenSurface(): ConfigModalSurface {
+  const now = Date.UTC(2026, 6, 13, 12, 0, 0);
+  const tokens: PublicPairingToken[] = [
+    { id: 'aaaa1111bbbb2222', name: 'my laptop', createdAt: Date.UTC(2026, 6, 10, 9, 0, 0), lastSeenAt: now - 3 * 60_000 },
+    { id: 'cccc3333dddd4444', name: 'kitchen tablet', createdAt: Date.UTC(2026, 6, 1, 9, 0, 0), lastSeenAt: now - 5 * 60 * 60_000 },
+    { id: 'eeee5555ffff6666', name: 'phone (never scanned)', createdAt: Date.UTC(2026, 6, 13, 8, 0, 0) },
+  ];
+  let legacyRevoked = false;
+  return createDevicesModalSurface({
+    now: () => now,
+    pairingTokens: {
+      list: () => tokens,
+      rename: () => true,
+      revoke: () => true,
+      mintForMigration: () => ({ id: 'new', name: 'migrated device', token: 'tok', createdAt: now }),
+      isLegacyRevoked: () => legacyRevoked,
+      revokeLegacyShared: () => { legacyRevoked = true; },
+    },
+  });
+}