@pellux/goodvibes-tui 1.1.0 → 1.9.0

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

@@ -0,0 +1,218 @@
+import type {
+  ConfigModalActionContext,
+  ConfigModalRow,
+  ConfigModalSurface,
+  ConfigModalView,
+} from '../../input/config-modal-types.ts';
+import { MODAL_TONES } from './modal-theme.ts';
+import { infoRow } from './modal-surface-helpers.ts';
+import {
+  loadEcosystemCatalog,
+  listInstalledEcosystemEntries,
+  reviewEcosystemCatalogEntry,
+  type EcosystemCatalogEntry,
+  type EcosystemCatalogPathOptions,
+  type EcosystemEntryKind,
+} from '@/runtime/index.ts';
+import type { UiMarketplaceSnapshot, UiReadModel } from '../../runtime/ui-read-models.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Live deps the marketplace modal captures (mirrors the panel factory). */
+export interface MarketplaceModalDeps {
+  readonly readModel?: UiReadModel<UiMarketplaceSnapshot>;
+  readonly ecosystemPaths?: EcosystemCatalogPathOptions;
+}
+
+type MarketplaceReview = ReturnType<typeof reviewEcosystemCatalogEntry>;
+
+interface MarketplaceRow {
+  readonly kind: EcosystemEntryKind;
+  readonly entry: EcosystemCatalogEntry;
+  readonly installed: boolean;
+  readonly review: MarketplaceReview;
+}
+
+const KINDS: readonly EcosystemEntryKind[] = ['plugin', 'skill', 'hook-pack', 'policy-pack'];
+
+/**
+ * Marketplace → config-modal surface (W6.1 group-B port). Local-first
+ * publish/import catalog (NOT a remote store) with provenance, compatibility,
+ * and install posture. Disk catalog loads happen in refresh() (never in
+ * buildView), mirroring the panel's explicit render()/refresh() split.
+ * Install/uninstall route to the `/marketplace` command path (charter: no
+ * destructive confirm folded into a modal).
+ *
+ * B30 (honest empty-state): the panel's original "No curated marketplace
+ * entries found yet." copy implied a curated remote catalog. It isn't one —
+ * loadEcosystemCatalog only ever reads .goodvibes/ecosystem/<kind>s.json under
+ * the project/home, populated solely by `/marketplace publish` and
+ * `/marketplace bundle import`. The empty-state copy below (locked byte-for-byte
+ * in the golden) names that reality. Selection-blind port: the panel's
+ * selected-entry compatibility/risk/state detail is folded into each row label.
+ */
+class MarketplaceModalSurface implements ConfigModalSurface {
+  readonly name = 'marketplace-modal';
+  readonly title = 'Marketplace';
+  private rows: MarketplaceRow[] = [];
+  private loadError: string | null = null;
+  private requestRender: () => void = () => {};
+  private unsub: (() => void) | null = null;
+
+  constructor(private readonly deps: MarketplaceModalDeps) {}
+
+  readonly actions = [
+    { key: 'i', id: 'install', label: 'install', enabledFor: (row: ConfigModalRow | null) => this.canInstall(row) },
+    { key: 'u', id: 'uninstall', label: 'uninstall', enabledFor: (row: ConfigModalRow | null) => this.canUninstall(row) },
+    { key: 'r', id: 'refresh', label: 'refresh' },
+  ];
+
+  onOpen(requestRender: () => void): void {
+    this.requestRender = requestRender;
+    this.refresh();
+    if (this.deps.readModel && !this.unsub) this.unsub = this.deps.readModel.subscribe(() => this.requestRender());
+  }
+
+  onClose(): void {
+    this.unsub?.();
+    this.unsub = null;
+  }
+
+  private refresh(): void {
+    const paths = this.deps.ecosystemPaths;
+    if (!paths) { this.rows = []; this.loadError = null; return; }
+    try {
+      const built: MarketplaceRow[] = [];
+      for (const kind of KINDS) {
+        const installed = new Set(listInstalledEcosystemEntries(kind, paths).map((receipt) => receipt.entry.id));
+        for (const entry of loadEcosystemCatalog(kind, paths)) {
+          built.push({ kind, entry, installed: installed.has(entry.id), review: reviewEcosystemCatalogEntry(entry, paths) });
+        }
+      }
+      this.rows = built.sort((a, b) => a.entry.name.localeCompare(b.entry.name));
+      this.loadError = null;
+    } catch (e) {
+      this.rows = [];
+      this.loadError = `Catalog load failed: ${summarizeError(e)}`;
+    }
+  }
+
+  private entryFor(row: ConfigModalRow | null): MarketplaceRow | undefined {
+    if (!row) return undefined;
+    return this.rows.find((r) => `${r.kind}:${r.entry.id}` === row.id);
+  }
+
+  private canInstall(row: ConfigModalRow | null): boolean {
+    const entry = this.entryFor(row);
+    return Boolean(entry && !entry.installed);
+  }
+
+  private canUninstall(row: ConfigModalRow | null): boolean {
+    const entry = this.entryFor(row);
+    return Boolean(entry && entry.installed);
+  }
+
+  buildView(): ConfigModalView {
+    const snapshot = this.deps.readModel?.getSnapshot();
+    const rows: ConfigModalRow[] = [];
+
+    // Honest empty / degraded state (B30). loadError → degraded banner.
+    if (this.loadError) {
+      return { title: 'Marketplace', degraded: this.loadError, tabs: [{ id: 'catalog', label: 'Catalog', rows: [] }] };
+    }
+    if (this.rows.length === 0) {
+      if (!this.deps.ecosystemPaths) {
+        rows.push(infoRow('empty:unwired', 'Marketplace catalog roots aren’t wired into this session, so there’s nothing to read yet.'));
+      } else {
+        rows.push(infoRow('empty:0', 'This is your local plugin, skill, hook-pack, and policy-pack catalog — not a remote store.'));
+        rows.push(infoRow('empty:1', 'It’s empty because nothing has been published or imported into this workspace yet. Entries appear here once you publish a local component or import a bundle.'));
+      }
+      rows.push(infoRow('empty:title', 'Populate it', { bold: true }));
+      rows.push(infoRow('empty:publish', '/marketplace publish <kind> <path>  — publish local plugins/skills into the catalog', { dim: true }));
+      rows.push(infoRow('empty:import', '/marketplace bundle import <path>   — import a catalog bundle from disk', { dim: true }));
+      rows.push(infoRow('empty:review', '/marketplace catalog review         — inspect the current local catalog posture', { dim: true }));
+      return {
+        title: 'Marketplace',
+        tabs: [{ id: 'catalog', label: 'Catalog', rows, emptyText: '' }],
+        hints: ['local publish/import catalog'],
+      };
+    }
+
+    // Posture summary header.
+    const installedCount = this.rows.filter((r) => r.installed).length;
+    const count = (k: EcosystemEntryKind): number => this.rows.filter((r) => r.kind === k).length;
+    const header = [
+      `catalog ${this.rows.length}  installed ${installedCount}  plugins ${count('plugin')}  skills ${count('skill')}  hooks ${count('hook-pack')}  policies ${count('policy-pack')}`,
+    ];
+
+    const startupIssues = snapshot?.startupIssues ?? [];
+    for (const [i, issue] of startupIssues.slice(0, 3).entries()) {
+      rows.push(infoRow(`issue:${i}`, `⚠ ${issue}`, { fg: MODAL_TONES.warn }));
+    }
+
+    // Catalog list — selection-blind: fold provenance/compat/risk/state into the label.
+    for (const row of this.rows) {
+      const review = row.review;
+      const provenance = row.entry.provenance ?? 'local';
+      rows.push({
+        id: `${row.kind}:${row.entry.id}`,
+        label: `${row.kind.padEnd(11)} ${row.entry.name.padEnd(22)} ${provenance.padEnd(14)} ${row.installed ? 'INSTALLED' : 'local    '} ${row.entry.version ?? 'n/a'} · compat ${review.compatibility.status} risk ${review.riskLevel}`,
+      });
+    }
+
+    // Recommendations (displayed with their command; digit-jump dropped).
+    const recommendations = snapshot?.recommendations ?? [];
+    if (recommendations.length > 0) {
+      rows.push(infoRow('rec:title', 'Recommended', { bold: true }));
+      for (const [i, rec] of recommendations.slice(0, 3).entries()) {
+        rows.push(infoRow(`rec:${i}`, `${rec.title} — ${rec.command}`, { dim: true }));
+      }
+    }
+
+    return {
+      title: 'Marketplace',
+      tabs: [{
+        id: 'catalog',
+        label: 'Catalog',
+        header,
+        rows,
+        hints: ['local publish/import catalog'],
+      }],
+    };
+  }
+
+  onAction(id: string, ctx: ConfigModalActionContext): void {
+    if (id === 'refresh') { this.refresh(); ctx.setStatus('Refreshing catalog…'); return; }
+    const entry = this.entryFor(ctx.row);
+    if (!entry) return;
+    if (id === 'install' && !entry.installed) {
+      void ctx.executeCommand?.('marketplace', ['install', entry.kind, entry.entry.id]);
+      ctx.setStatus(`Dispatched /marketplace install ${entry.kind} ${entry.entry.id} (see transcript).`);
+    } else if (id === 'uninstall' && entry.installed) {
+      void ctx.executeCommand?.('marketplace', ['uninstall', entry.kind, entry.entry.id]);
+      ctx.setStatus(`Dispatched /marketplace uninstall ${entry.kind} ${entry.entry.id} (see transcript).`);
+    }
+  }
+}
+
+export function createMarketplaceModalSurface(deps: MarketplaceModalDeps): ConfigModalSurface {
+  return new MarketplaceModalSurface(deps);
+}
+
+/**
+ * Deterministic golden fixture: catalog roots wired at a fresh tmp path that is
+ * removed immediately (loadEcosystemCatalog/listInstalledEcosystemEntries guard
+ * missing paths with existsSync → [], so refresh() finds nothing and renders the
+ * B30 honest empty-state copy). The random tmp path never appears in the
+ * rendered lines (the empty-state copy is static), so the golden is byte-stable.
+ */
+export function marketplaceModalGoldenSurface(): ConfigModalSurface {
+  const root = mkdtempSync(join(tmpdir(), 'gv-marketplace-golden-'));
+  const surface = createMarketplaceModalSurface({
+    ecosystemPaths: { cwd: root, homeDir: root, projectCatalogRoot: join(root, 'ecosystem') },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return surface;
+}

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

@@ -0,0 +1,180 @@
+import { infoRow } from './modal-surface-helpers.ts';
+import type {
+  ConfigModalActionContext,
+  ConfigModalRow,
+  ConfigModalSurface,
+  ConfigModalTab,
+  ConfigModalView,
+} from '../../input/config-modal-types.ts';
+
+// ---------------------------------------------------------------------------
+// Memory → config-modal surface (W6.1 group-B port). Two tabs: 'All Records'
+// (the full record list) and 'Review Queue' (the operator review queue) — the
+// same split the panel toggled with Tab, now real host tabs. Review-state
+// mutations (reviewed/stale/contradicted/fresh) and record delete route to the
+// existing `/recall review` / `/recall remove` command path (charter: no
+// destructive mutation direct-called from a modal). Selection-blind port: the
+// panel's selected-record scope/class/tags/provenance detail is folded into
+// each row label. `memoryRegistry` absent → the retired MemoryPanel's
+// "not configured" copy renders as an honest degraded state.
+// ---------------------------------------------------------------------------
+
+/** Minimal read shape of a `MemoryRecord` this modal renders. */
+interface MemoryRecordLike {
+  readonly id: string;
+  readonly scope: string;
+  readonly cls: string;
+  readonly summary: string;
+  readonly detail?: string | undefined;
+  readonly tags: readonly string[];
+  readonly reviewState: string;
+  readonly confidence: number;
+  readonly staleReason?: string | undefined;
+  readonly reviewedAt?: number | undefined;
+  readonly reviewedBy?: string | undefined;
+  readonly createdAt: number;
+  readonly provenance: readonly { readonly kind: string; readonly ref: string }[];
+}
+
+export interface MemoryModalDeps {
+  readonly memoryRegistry?: {
+    search(filter?: { limit?: number }): readonly MemoryRecordLike[];
+    reviewQueue(limit?: number): readonly MemoryRecordLike[];
+  };
+}
+
+// Mirrors registerKnowledgePanels's withUnconfiguredFallback copy for the
+// retired MemoryPanel (src/panels/builtin/knowledge.ts) verbatim.
+const NOT_CONFIGURED_TITLE = 'Memory registry not configured for this session.';
+const NOT_CONFIGURED_BODY = 'This runtime was not wired with a project memory registry at bootstrap, so no memory data is available.';
+
+function fmtTime(ts: number): string {
+  return new Date(ts).toISOString().slice(0, 16).replace('T', ' ');
+}
+
+class MemoryModalSurface implements ConfigModalSurface {
+  readonly name = 'memory-modal';
+  readonly title = 'Memory';
+  private allRecords: MemoryRecordLike[] = [];
+  private reviewRecords: MemoryRecordLike[] = [];
+
+  constructor(private readonly deps: MemoryModalDeps) {}
+
+  private readonly reviewGate = (row: ConfigModalRow | null, tabId: string): boolean => tabId === 'review' && row !== null;
+
+  readonly actions = [
+    { key: 'enter', id: 'markReviewed', label: 'reviewed', enabledFor: this.reviewGate },
+    { key: 's', id: 'markStale', label: 'stale', enabledFor: this.reviewGate },
+    { key: 'c', id: 'markContradicted', label: 'contradicted', enabledFor: this.reviewGate },
+    { key: 'f', id: 'markFresh', label: 'fresh', enabledFor: this.reviewGate },
+    { key: 'd', id: 'remove', label: 'delete', enabledFor: (row: ConfigModalRow | null) => row !== null },
+    { key: 'r', id: 'refresh', label: 'refresh' },
+  ];
+
+  onOpen(): void { this.refresh(); }
+
+  private refresh(): void {
+    if (!this.deps.memoryRegistry) { this.allRecords = []; this.reviewRecords = []; return; }
+    this.allRecords = [...this.deps.memoryRegistry.search({ limit: 100 })];
+    this.reviewRecords = [...this.deps.memoryRegistry.reviewQueue(24)];
+  }
+
+  private recordFrom(id: string): MemoryRecordLike | undefined {
+    return this.allRecords.find((r) => r.id === id) ?? this.reviewRecords.find((r) => r.id === id);
+  }
+
+  private allTab(): ConfigModalTab {
+    const rows: ConfigModalRow[] = this.allRecords.map((record) => ({
+      id: record.id,
+      label: `[${record.scope.slice(0, 1).toUpperCase()}/${record.cls.slice(0, 3).toUpperCase()}] ${record.id.slice(-8)}  ${fmtTime(record.createdAt)}  ${record.summary}${record.tags.length > 0 ? `  #${record.tags.join(' #')}` : ''}`,
+    }));
+    return {
+      id: 'all',
+      label: 'All Records',
+      header: [`records ${this.allRecords.length}  review queue ${this.reviewRecords.length}`],
+      rows,
+      emptyText: 'No memory records.',
+      hints: ['d delete'],
+    };
+  }
+
+  private reviewTab(): ConfigModalTab {
+    const rows: ConfigModalRow[] = this.reviewRecords.map((record) => ({
+      id: record.id,
+      label: `${record.reviewState.padEnd(13)} ${String(record.confidence).padStart(3)}%  ${record.summary}${record.staleReason ? `  (stale: ${record.staleReason})` : ''}`,
+    }));
+    return {
+      id: 'review',
+      label: 'Review Queue',
+      header: [`records ${this.allRecords.length}  review queue ${this.reviewRecords.length}`],
+      rows,
+      emptyText: 'No records in the review queue.',
+      hints: ['enter reviewed', 's stale', 'c contradicted', 'f fresh', 'd delete'],
+    };
+  }
+
+  buildView(): ConfigModalView {
+    if (!this.deps.memoryRegistry) {
+      return {
+        title: 'Memory',
+        degraded: `${NOT_CONFIGURED_TITLE} ${NOT_CONFIGURED_BODY}`,
+        tabs: [{ id: 'all', label: 'All Records', rows: [] }],
+      };
+    }
+    return { title: 'Memory', tabs: [this.allTab(), this.reviewTab()] };
+  }
+
+  onAction(id: string, ctx: ConfigModalActionContext): void {
+    if (id === 'refresh') { this.refresh(); ctx.setStatus('Reloaded memory records.'); return; }
+    const record = ctx.row ? this.recordFrom(ctx.row.id) : undefined;
+    if (!record) return;
+    const review = (state: string, confidence: number, reason?: string): void => {
+      const args = ['review', record.id, state, '--confidence', String(confidence), '--by', 'operator'];
+      if (reason) args.push('--reason', reason);
+      void ctx.executeCommand?.('recall', args);
+      ctx.setStatus(`Dispatched /recall review ${record.id} ${state}.`);
+    };
+    switch (id) {
+      case 'markReviewed': review('reviewed', Math.max(record.confidence, 85)); break;
+      case 'markStale': review('stale', Math.min(record.confidence, 40), 'marked stale from the memory panel'); break;
+      case 'markContradicted': review('contradicted', 0, 'marked contradicted from the memory panel'); break;
+      case 'markFresh': review('fresh', Math.max(record.confidence, 60)); break;
+      case 'remove': void ctx.executeCommand?.('recall', ['remove', record.id]); ctx.setStatus(`Dispatched /recall remove ${record.id}.`); break;
+    }
+  }
+}
+
+export function createMemoryModalSurface(deps: MemoryModalDeps): ConfigModalSurface {
+  return new MemoryModalSurface(deps);
+}
+
+/**
+ * Deterministic golden fixture: fixed memory records with frozen createdAt
+ * timestamps — no live registry, no wall-clock, no random ids.
+ */
+export function memoryModalGoldenSurface(): ConfigModalSurface {
+  const FIXED_CREATED_AT = 1735689600000; // 2025-01-01T00:00:00.000Z
+  const records: readonly MemoryRecordLike[] = [
+    {
+      id: 'mem-0000001a', scope: 'project', cls: 'decision',
+      summary: 'Wave-6 batches panel retirements behind modal builders.',
+      detail: 'Applies to KNOWLEDGE, MEMORY, WORK-PLAN in WO-B.',
+      tags: ['wave-6', 'modals'], reviewState: 'reviewed', confidence: 90,
+      reviewedAt: FIXED_CREATED_AT + 3600000, reviewedBy: 'operator', createdAt: FIXED_CREATED_AT,
+      provenance: [{ kind: 'session', ref: 'session-fixed-1' }],
+    },
+    {
+      id: 'mem-0000002b', scope: 'session', cls: 'risk',
+      summary: 'Modal review actions must not call mutation APIs directly.',
+      tags: ['charter'], reviewState: 'stale', confidence: 35,
+      staleReason: 'needs re-verification against the charter doc',
+      createdAt: FIXED_CREATED_AT + 86400000, provenance: [],
+    },
+  ];
+  return createMemoryModalSurface({
+    memoryRegistry: {
+      search: () => records,
+      reviewQueue: () => records.filter((record) => record.reviewState !== 'reviewed'),
+    },
+  });
+}

package/src/panels/modals/modal-surface-helpers.ts

@@ -0,0 +1,54 @@
+import { DEFAULT_PANEL_PALETTE } from '../polish.ts';
+import type { ModalSectionStyle } from '../../renderer/modal-factory.ts';
+import type { ConfigModalRow } from '../../input/config-modal-types.ts';
+
+/**
+ * Shared formatting helpers for W6.1 config-modal surfaces. Row styling reuses
+ * DEFAULT_PANEL_PALETTE (the retired panels' palette) so a migrated modal reads
+ * as the same surface it replaced — the goldens stay panel-consistent.
+ */
+export const PALETTE = DEFAULT_PANEL_PALETTE;
+
+export type Tone = 'good' | 'bad' | 'warn' | 'info' | 'dim' | 'value';
+
+/** Map a semantic tone to a ModalSectionStyle (foreground only). */
+export function toneStyle(tone: Tone): ModalSectionStyle {
+  return { fg: PALETTE[tone] };
+}
+
+/** A single-glyph status dot matching the provider-console convention
+ *  (● online · ◐ warming · ✕ error · ○ idle). */
+export function statusGlyph(tone: Tone): string {
+  switch (tone) {
+    case 'good': return '●';
+    case 'warn': return '◐';
+    case 'bad': return '✕';
+    default: return '○';
+  }
+}
+
+/** Fixed-width left-justify by display columns (plain padEnd is fine for the
+ *  ASCII/latin labels these surfaces use; wide glyphs are the status dot only,
+ *  which we place at a fixed column). */
+export function pad(text: string, width: number): string {
+  return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+
+/** Build a `label value` posture cell for the header line. */
+export function kv(label: string, value: string | number): string {
+  return `${label} ${value}`;
+}
+
+/** Join posture cells into one header line with a consistent separator. */
+export function postureLine(cells: string[]): string {
+  return cells.join('   ');
+}
+
+/**
+ * A stable non-selectable informational row (section title, empty-state copy,
+ * or a content line the surface renders but the cursor never lands on). `id`
+ * must be unique within its tab so the host's live-value overlay keys off it.
+ */
+export function infoRow(id: string, label: string, style?: ModalSectionStyle): ConfigModalRow {
+  return { id, label, selectable: false, ...(style ? { style } : {}) };
+}

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

@@ -0,0 +1,42 @@
+import { activeUiTones, registerThemeRefresh } from '../../renderer/theme.ts';
+
+// ---------------------------------------------------------------------------
+// Semantic tone tokens for the W6.1 group-B config modals.
+//
+// Derived entirely from the chrome token set so the builders carry NO raw hex
+// color literals (architecture: no-raw-hex-literal-growth). Rebuilt IN PLACE
+// on theme flips via registerThemeRefresh — the group-B surfaces read
+// MODAL_TONES by reference at render time, so a dark-pinned module const here
+// left them rendering dark accents on light chrome (batch refutation
+// finding 2). Mirrors the polish-core/overlay-box/modal-factory pattern.
+// ---------------------------------------------------------------------------
+
+function buildModalTones() {
+  const T = activeUiTones();
+  return {
+    /** Informational / accent (blue). */
+    info: T.state.info,
+    /** Positive / healthy (green). */
+    good: T.state.good,
+    /** Caution (amber). */
+    warn: T.state.warn,
+    /** Error / danger (red). */
+    bad: T.state.bad,
+    /** Reasoning / secondary accent (purple). */
+    reasoning: T.state.reasoning,
+    /** Muted secondary text. */
+    muted: T.fg.muted,
+    /** Dim tertiary text. */
+    dim: T.fg.dim,
+    /** Primary text. */
+    primary: T.fg.primary,
+    /** QR module foreground — high-contrast, mode-appropriate. */
+    qrDark: T.fg.inverse,
+    /** QR field background — high-contrast, mode-appropriate. */
+    qrLight: T.fg.primary,
+  };
+}
+
+export const MODAL_TONES: Readonly<ReturnType<typeof buildModalTones>> = buildModalTones();
+
+registerThemeRefresh(() => Object.assign(MODAL_TONES as Record<string, string>, buildModalTones()));

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

@@ -0,0 +1,163 @@
+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 { encodeConnectionPayload, generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
+
+// ---------------------------------------------------------------------------
+// QR Code → 'pairing' config-modal surface (W6.1 group-B port). Connection
+// URL/token/username(/password) plus a scannable QR block — read/navigate only.
+// Token regeneration is a destructive mutation (it invalidates any live
+// companion session) that the panel gated behind an in-panel confirm; per
+// charter that confirm is never folded into a modal, so regenerate routes to a
+// command instead. `getConnectionInfo` is a lazy thunk (loaded once on first
+// buildView, cached) so a missing daemon home degrades honestly rather than
+// throwing at modal-registration time.
+//
+// DEBT-3: the regenerate action now dispatches the real `/qrcode regenerate`
+// verb (which rotates the shared operator-token store) and, once it resolves,
+// RE-PULLS the lazy connection-info thunk so the modal shows the rotated token +
+// QR in place without being re-opened. `confirm: true` keeps the two-press
+// guard so a stray keystroke never rotates a live companion's token.
+// ---------------------------------------------------------------------------
+
+export interface PairingModalConnectionInfo {
+  readonly url: string;
+  readonly token: string;
+  readonly username: string;
+  readonly password?: string;
+  readonly version?: string;
+  readonly surface?: string;
+}
+export interface PairingModalControlPlaneSnapshot { readonly activeClientIds: readonly string[]; }
+export interface PairingModalReadModel<T> { getSnapshot(): T; }
+
+export interface PairingModalDeps {
+  /** Lazy connection-info provider — returns null when the daemon/companion
+   *  token cannot be resolved (honest degraded state instead of a throw). */
+  readonly getConnectionInfo: () => PairingModalConnectionInfo | null;
+  readonly controlPlaneReadModel?: PairingModalReadModel<PairingModalControlPlaneSnapshot>;
+  readonly copyToClipboard?: (text: string) => void;
+}
+
+// Fixed-width placeholder — deliberately NOT derived from the real secret's
+// length (mirrors QrPanel.SECRET_MASK), so masking doesn't leak length.
+const SECRET_MASK = '••••••••••••';
+
+class PairingModalSurface implements ConfigModalSurface {
+  readonly name = 'pairing-modal';
+  readonly title = 'Companion Pairing';
+  private info: PairingModalConnectionInfo | null | undefined = undefined;
+  private revealed = false;
+  private requestRender: () => void = () => {};
+
+  constructor(private readonly deps: PairingModalDeps) {}
+
+  readonly actions = [
+    { key: 'v', id: 'toggleReveal', label: 'reveal token' },
+    { key: 'c', id: 'copyToken', label: 'copy token', enabledFor: () => Boolean(this.deps.copyToClipboard) },
+    { key: 'r', id: 'regenerate', label: 'regenerate token', confirm: true },
+  ];
+
+  onOpen(requestRender: () => void): void { this.requestRender = requestRender; }
+
+  private ensureInfo(): PairingModalConnectionInfo | null {
+    if (this.info === undefined) {
+      try { this.info = this.deps.getConnectionInfo(); } catch { this.info = null; }
+    }
+    return this.info;
+  }
+
+  buildView(): ConfigModalView {
+    const info = this.ensureInfo();
+    if (!info) {
+      return { title: 'Companion Pairing', degraded: 'Companion pairing is unavailable — the daemon connection info could not be resolved for this session.', tabs: [{ id: 'pairing', label: 'Pairing', rows: [] }] };
+    }
+    const { url, token, username, password } = info;
+    const displayToken = this.revealed ? token : SECRET_MASK;
+    const displayPassword = password !== undefined ? (this.revealed ? password : SECRET_MASK) : undefined;
+
+    const rows: ConfigModalRow[] = [];
+    rows.push(infoRow('intro', 'Scan with the GoodVibes companion app to pair this session.', { dim: true }));
+    rows.push(infoRow('url', `URL       ${url}`));
+    rows.push(infoRow('token', `Token     ${displayToken}`, { fg: MODAL_TONES.reasoning }));
+    rows.push(infoRow('username', `Username  ${username}`));
+    if (displayPassword !== undefined) rows.push(infoRow('password', `Password  ${displayPassword}`));
+    if (this.deps.controlPlaneReadModel) {
+      const connected = this.deps.controlPlaneReadModel.getSnapshot().activeClientIds.length;
+      rows.push(infoRow('companions', `Companions connected: ${connected}`, connected > 0 ? { fg: MODAL_TONES.good } : { dim: true }));
+    }
+
+    // ASCII QR block — same payload shape as QrPanel.render(); the multi-line
+    // preformatted string is split into one non-selectable row per block row.
+    const payload = encodeConnectionPayload({
+      url, token, username,
+      ...(password !== undefined ? { password } : {}),
+      version: info.version ?? '0.0.0',
+      surface: info.surface ?? 'tui',
+    });
+    const qr = renderQrToString(generateQrMatrix(payload));
+    qr.split('\n').forEach((line, i) => rows.push(infoRow(`qr:${i}`, line, { fg: MODAL_TONES.qrDark, bg: MODAL_TONES.qrLight })));
+
+    return {
+      title: 'Companion Pairing',
+      tabs: [{ id: 'pairing', label: 'Pairing', rows, hints: [this.revealed ? 'v hide token' : 'v reveal token'] }],
+    };
+  }
+
+  onAction(id: string, ctx: ConfigModalActionContext): void {
+    const info = this.ensureInfo();
+    if (id === 'toggleReveal') { this.revealed = !this.revealed; this.requestRender(); return; }
+    if (id === 'copyToken') {
+      if (!this.deps.copyToClipboard || !info) { ctx.print('Clipboard not available.'); return; }
+      this.deps.copyToClipboard(info.token);
+      ctx.print('Token copied to clipboard.');
+      return;
+    }
+    if (id === 'regenerate') {
+      const dispatched = ctx.executeCommand?.('qrcode', ['regenerate']);
+      if (!dispatched) {
+        ctx.setStatus('Token rotation is unavailable in this runtime.');
+        return;
+      }
+      ctx.setStatus('Rotating pairing token…');
+      void dispatched
+        .then((ok) => {
+          if (ok === false) { ctx.setStatus('Token rotation did not complete.'); return; }
+          // Re-pull the lazy connection-info thunk: /qrcode regenerate rewrote
+          // the shared token store, so a fresh getConnectionInfo() reflects the
+          // rotated token + QR. ensureInfo caches on first build — clear it.
+          this.info = undefined;
+          this.revealed = false;
+          this.ensureInfo();
+          this.requestRender();
+          ctx.setStatus('Pairing token rotated — new token and QR loaded.');
+        })
+        .catch(() => { ctx.setStatus('Token rotation failed.'); });
+    }
+  }
+}
+
+export function createPairingModalSurface(deps: PairingModalDeps): ConfigModalSurface {
+  return new PairingModalSurface(deps);
+}
+
+/**
+ * Deterministic golden fixture: a frozen connectionInfo literal (no real
+ * token/QR generation call — encodeConnectionPayload/generateQrMatrix are pure
+ * functions of this literal) and a frozen control-plane snapshot.
+ */
+export function pairingModalGoldenSurface(): ConfigModalSurface {
+  const connectionInfo: PairingModalConnectionInfo = {
+    url: 'http://192.168.1.50:3141', token: 'golden-token-0123456789abcdef', username: 'golden-user', password: 'golden-pass', version: '0.0.0', surface: 'tui',
+  };
+  return createPairingModalSurface({
+    getConnectionInfo: () => connectionInfo,
+    controlPlaneReadModel: { getSnapshot: () => ({ activeClientIds: ['golden-client-1'] }) },
+    copyToClipboard: () => {},
+  });
+}