@pellux/goodvibes-tui 1.16.1 → 1.18.0

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

@@ -6,42 +6,83 @@ import type {
   ConfigModalSurface,
   ConfigModalView,
 } from '../../input/config-modal-types.ts';
-import { encodeConnectionPayload, generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
+import { describeOriginPosture, generateQrMatrix, renderQrToString, type OriginPosture, type PairingHandoffOfferKind } from '@pellux/goodvibes-sdk/platform/pairing';
+import { formatPairingOffers, formatPostureCapabilities, pairingPostureNotice } from '../../core/pairing-offers.ts';
 
 // ---------------------------------------------------------------------------
-// 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.
+// Device Pairing config-modal surface. Shows the web-app origin, the per-device
+// token's name, a masked token/deep-link pair, the offer set with plain-language
+// consequences, and a scannable QR of the `#pair=<token>` deep link — a camera
+// scan opens the web app already signed in. No raw JSON connection blob is ever
+// encoded.
 //
-// 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.
+// `getConnectionInfo` is a lazy thunk (loaded once on first buildView, cached):
+// each modal open mints its OWN named per-device token, so a missing pairing
+// service degrades honestly to an "unavailable" state instead of throwing at
+// registration time. "new device token" clears the cache and re-pulls to mint a
+// fresh token + QR in place — non-destructive now, because a freshly minted
+// token no longer rotates a shared secret out from under a live device; old
+// tokens stay valid until explicitly revoked in the settings device surface.
 // ---------------------------------------------------------------------------
 
 export interface PairingModalConnectionInfo {
+  /** The web-app origin the deep link opens (e.g. http://workshop.local:3141). */
   readonly url: string;
+  /** The one-time pairing secret (masked unless revealed). */
   readonly token: string;
-  readonly username: string;
-  readonly password?: string;
-  readonly version?: string;
-  readonly surface?: string;
+  /** The per-device token's editable name. */
+  readonly tokenName: string;
+  /** The `#pair=<token>` deep link the QR encodes — opens the web app signed in. */
+  readonly deepLink: string;
+  /** The offer set this pairing carries (each declinable in the web app). */
+  readonly offers: readonly PairingHandoffOfferKind[];
+  /**
+   * The honest TLS/capability posture of the web origin the deep link opens
+   * (the SDK's describeOriginPosture / the handoff's `posture` field). The one
+   * honest LAN line and the labeled capability list both render from here — never
+   * from a locally-authored string. Absent when no web origin is known.
+   */
+  readonly posture?: OriginPosture | undefined;
 }
 export interface PairingModalControlPlaneSnapshot { readonly activeClientIds: readonly string[]; }
 export interface PairingModalReadModel<T> { getSnapshot(): T; }
 
+/** tailscale.get shape — the daemon's honest tailscale detection (quiet when absent). */
+export interface PairingTailscaleStatus {
+  readonly available: boolean;
+  readonly loggedIn: boolean;
+  readonly magicDnsName?: string | undefined;
+  readonly httpsUrl?: string | undefined;
+  readonly detail: string;
+  readonly lastServe?: PairingTailscaleServeReceipt | undefined;
+}
+/** tailscale.serve.run receipt — the one-action serve result rendered verbatim. */
+export interface PairingTailscaleServeReceipt {
+  readonly at: number;
+  readonly command: string;
+  readonly ok: boolean;
+  readonly url?: string | undefined;
+  readonly detail: string;
+}
+
 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;
+  /**
+   * Probe tailscale (tailscale.get) once on open. Absent dep, a null result, or
+   * `available:false` all keep the tailscale affordance QUIET — never a nag.
+   * Present + available ⇒ the surface offers the one-action serve.
+   */
+  readonly probeTailscale?: () => Promise<PairingTailscaleStatus | null>;
+  /**
+   * Run tailscale.serve.run (behind the standard confirm) and return its receipt.
+   * Wired only when probeTailscale is; the resulting https MagicDNS URL and the
+   * receipt render in place.
+   */
+  readonly runTailscaleServe?: () => Promise<PairingTailscaleServeReceipt | null>;
 }
 
 // Fixed-width placeholder — deliberately NOT derived from the real secret's
@@ -50,20 +91,45 @@ const SECRET_MASK = '••••••••••••';
 
 class PairingModalSurface implements ConfigModalSurface {
   readonly name = 'pairing-modal';
-  readonly title = 'Companion Pairing';
+  readonly title = 'Device Pairing';
   private info: PairingModalConnectionInfo | null | undefined = undefined;
   private revealed = false;
   private requestRender: () => void = () => {};
+  /** tailscale.get result: undefined = not probed yet, null = probed/absent (stays quiet). */
+  private tailscale: PairingTailscaleStatus | null | undefined = undefined;
+  /** The receipt from a completed serve run, rendered verbatim under the affordance. */
+  private serveReceipt: PairingTailscaleServeReceipt | null = null;
+  /** True while a serve run is in flight (the action is single-shot). */
+  private serving = false;
 
   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 },
+    { key: 'c', id: 'copyLink', label: 'copy link', enabledFor: () => Boolean(this.deps.copyToClipboard) },
+    { key: 'r', id: 'newToken', label: 'new device token' },
+    // The one-action serve affordance — offered ONLY when tailscale is detected
+    // and not already serving https; a second 't' press (the standard confirm)
+    // runs tailscale.serve.run. Absence keeps this key unadvertised and inert.
+    {
+      key: 't',
+      id: 'tailscaleServe',
+      label: 'serve over tailscale (https)',
+      confirm: true,
+      enabledFor: () => this.tailscale?.available === true && !this.serving,
+    },
   ];
 
-  onOpen(requestRender: () => void): void { this.requestRender = requestRender; }
+  onOpen(requestRender: () => void): void {
+    this.requestRender = requestRender;
+    // Probe tailscale once on open; the affordance stays quiet until (and unless)
+    // this resolves to an available status. Failures degrade to quiet absence.
+    if (this.deps.probeTailscale && this.tailscale === undefined) {
+      this.deps.probeTailscale()
+        .then((status) => { this.tailscale = status ?? null; this.requestRender(); })
+        .catch(() => { this.tailscale = null; this.requestRender(); });
+    }
+  }
 
   private ensureInfo(): PairingModalConnectionInfo | null {
     if (this.info === undefined) {
@@ -75,71 +141,130 @@ class PairingModalSurface implements ConfigModalSurface {
   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: [] }] };
+      return { title: 'Device Pairing', degraded: 'Device pairing is unavailable — the pairing token service could not be resolved for this session.', tabs: [{ id: 'pairing', label: 'Pairing', rows: [] }] };
     }
-    const { url, token, username, password } = info;
+    const { url, token, tokenName, deepLink, offers, posture } = info;
     const displayToken = this.revealed ? token : SECRET_MASK;
-    const displayPassword = password !== undefined ? (this.revealed ? password : SECRET_MASK) : undefined;
+    // The deep link carries the one-time token, so it is masked with the token.
+    const displayLink = this.revealed ? deepLink : SECRET_MASK;
 
     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('intro', 'Scan with the GoodVibes web app to pair this device — it opens already signed in.', { dim: true }));
+    rows.push(infoRow('url', `Web app   ${url}`));
+    rows.push(infoRow('name', `Device    ${tokenName}`));
     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}`));
+    rows.push(infoRow('link', `Link      ${displayLink}`, { dim: true }));
     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 }));
+      rows.push(infoRow('companions', `Devices connected: ${connected}`, connected > 0 ? { fg: MODAL_TONES.good } : { dim: true }));
+    }
+
+    // The offer set carried by this pairing — each named with its plain-language
+    // consequence, each declinable in the web app.
+    if (offers.length > 0) {
+      rows.push(infoRow('offers-h', 'Offers (each declinable when you pair):', { dim: true }));
+      formatPairingOffers(offers).forEach((line, i) => rows.push(infoRow(`offer:${i}`, line)));
+    }
+    // The labeled browser-capability list — what the paired device actually gets
+    // over this origin (and, for a gated one, why not). Rendered from the posture,
+    // never hidden behind a dead button.
+    const capabilities = formatPostureCapabilities(posture);
+    if (capabilities.length > 0) {
+      rows.push(infoRow('caps-h', 'This device will get:', { dim: true }));
+      capabilities.forEach((line, i) => rows.push(infoRow(`cap:${i}`, line)));
     }
+    // The ONE honest LAN line — the SDK posture's own notice (LAN_PLAIN_HTTP_NOTICE),
+    // present only for the plain-http-on-LAN posture, never a nag elsewhere.
+    const notice = pairingPostureNotice(posture);
+    if (notice) rows.push(infoRow('posture', notice, { fg: MODAL_TONES.reasoning }));
+    // The tailscale serve affordance — quiet unless tailscale is detected.
+    this.appendTailscaleRows(rows);
 
-    // 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));
+    // ASCII QR of the deep link — a camera scan opens the web app already
+    // carrying the one-time token. No raw JSON blob is ever encoded. The
+    // multi-line preformatted string is split into one non-selectable row per row.
+    const qr = renderQrToString(generateQrMatrix(deepLink));
     qr.split('\n').forEach((line, i) => rows.push(infoRow(`qr:${i}`, line, { fg: MODAL_TONES.qrDark, bg: MODAL_TONES.qrLight })));
 
+    const hints = [this.revealed ? 'v hide token' : 'v reveal token'];
+    if (this.tailscale?.available && !this.serving) hints.push('t serve over tailscale');
     return {
-      title: 'Companion Pairing',
-      tabs: [{ id: 'pairing', label: 'Pairing', rows, hints: [this.revealed ? 'v hide token' : 'v reveal token'] }],
+      title: 'Device Pairing',
+      tabs: [{ id: 'pairing', label: 'Pairing', rows, hints }],
     };
   }
 
+  /**
+   * Append the tailscale section — quiet when tailscale is undetected or
+   * unavailable. When detected, the surface names the one-action serve; once a
+   * serve has produced (or tailscale already reports) an https MagicDNS URL, that
+   * URL and the serve receipt render verbatim so the encrypted path is visible.
+   */
+  private appendTailscaleRows(rows: ConfigModalRow[]): void {
+    const ts = this.tailscale;
+    if (!ts || !ts.available) return; // absence stays quiet
+    const httpsUrl = this.serveReceipt?.url ?? ts.httpsUrl;
+    if (httpsUrl) {
+      rows.push(infoRow('ts-h', 'Encrypted access (Tailscale):', { dim: true }));
+      rows.push(infoRow('ts-url', `  ${httpsUrl}`, { fg: MODAL_TONES.good }));
+    } else {
+      rows.push(infoRow('ts-h', 'Tailscale detected — press t to serve this app over https (MagicDNS).', { fg: MODAL_TONES.reasoning }));
+    }
+    const receipt = this.serveReceipt ?? ts.lastServe;
+    if (receipt) {
+      rows.push(infoRow('ts-receipt', `  ${receipt.ok ? '✓' : '✗'} ${receipt.detail}`, receipt.ok ? { dim: true } : { fg: MODAL_TONES.warn }));
+    } else if (this.serving) {
+      rows.push(infoRow('ts-serving', '  Serving over tailscale…', { dim: true }));
+    }
+  }
+
   onAction(id: string, ctx: ConfigModalActionContext): void {
     const info = this.ensureInfo();
     if (id === 'toggleReveal') { this.revealed = !this.revealed; this.requestRender(); return; }
-    if (id === 'copyToken') {
+    if (id === 'tailscaleServe') { this.runTailscaleServe(ctx); return; }
+    if (id === 'copyLink') {
       if (!this.deps.copyToClipboard || !info) { ctx.print('Clipboard not available.'); return; }
-      this.deps.copyToClipboard(info.token);
-      ctx.print('Token copied to clipboard.');
+      this.deps.copyToClipboard(info.deepLink);
+      ctx.print('Pairing link 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.'); });
+    if (id === 'newToken') {
+      // Each open mints its own named token; "new device token" just re-pulls the
+      // thunk to mint a fresh one + QR in place. Non-destructive: the prior token
+      // stays valid until it is revoked in /settings → security → devices.
+      this.info = undefined;
+      this.revealed = false;
+      this.ensureInfo();
+      this.requestRender();
+      ctx.setStatus('Minted a fresh device token and QR. Revoke old ones in /settings → security → devices.');
+      return;
     }
   }
+
+  /**
+   * Run the one-action tailscale serve (tailscale.serve.run) after the standard
+   * confirm has fired. The resulting https MagicDNS URL and receipt render in
+   * place; a failed run keeps its honest receipt detail rather than a dead row.
+   */
+  private runTailscaleServe(ctx: ConfigModalActionContext): void {
+    if (!this.deps.runTailscaleServe || this.serving) return;
+    this.serving = true;
+    this.requestRender();
+    this.deps.runTailscaleServe()
+      .then((receipt) => {
+        this.serving = false;
+        this.serveReceipt = receipt;
+        if (receipt?.ok && receipt.url) ctx.setStatus(`Serving over tailscale: ${receipt.url}`);
+        else if (receipt) ctx.setStatus(`Tailscale serve did not complete: ${receipt.detail}`);
+        this.requestRender();
+      })
+      .catch((err: unknown) => {
+        this.serving = false;
+        this.serveReceipt = { at: Date.now(), command: 'tailscale serve', ok: false, detail: err instanceof Error ? err.message : String(err) };
+        ctx.setStatus('Tailscale serve failed.');
+        this.requestRender();
+      });
+  }
 }
 
 export function createPairingModalSurface(deps: PairingModalDeps): ConfigModalSurface {
@@ -147,13 +272,18 @@ export function createPairingModalSurface(deps: PairingModalDeps): ConfigModalSu
 }
 
 /**
- * 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.
+ * Deterministic golden fixture: a frozen connectionInfo literal (the QR renders
+ * purely from its deepLink via generateQrMatrix) 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',
+    url: 'http://workshop.local:3141',
+    token: 'golden-token-0123456789abcdef',
+    tokenName: 'golden device',
+    deepLink: 'http://workshop.local:3141/#pair=golden-token-0123456789abcdef&offers=notifications~relay~passkey',
+    offers: ['notifications', 'relay', 'passkey'],
+    posture: describeOriginPosture('http://workshop.local:3141'),
   };
   return createPairingModalSurface({
     getConnectionInfo: () => connectionInfo,

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

@@ -18,12 +18,12 @@ import type {
 import { buildAnswerActions, isGenericRecommendation, type PlanningAnswerAction } from '../project-planning-answer-actions.ts';
 
 // ---------------------------------------------------------------------------
-// Project Planning → 'planning' config-modal surface (W6.1 group-B port). Shows
+// Project Planning → 'planning' config-modal surface (group-B port). Shows
 // readiness/questions/decisions/task-graph/handoff — read-only except choosing
 // an answer to the current open question, approving execution, dismissing the
 // plan, or refreshing.
 //
-// DEBT-3 — the seams are now real:
+// — the seams are now real:
 //   - A CANNED answer to a real open question dispatches `/plan answer <id> <text>`
 //     (records it; the open-question gap clears on the next refine).
 //   - The CUSTOM free-form typed answer (and any answer to a synthetic readiness

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

@@ -13,7 +13,7 @@ import type {
 } from '@pellux/goodvibes-sdk/platform/plugins';
 
 // ---------------------------------------------------------------------------
-// Plugins → config-modal surface (W6.1 group-B port). Mirrors the retired
+// Plugins → config-modal surface (group-B port). Mirrors the retired
 // PluginsPanel's read surface (list/capabilities/getTrustRecord/
 // getQuarantineRecord) plus `verify` (a pure read-only signature check).
 // enable/disable/liftQuarantine are DROPPED from the dep shape on purpose:

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

@@ -18,7 +18,7 @@ import type {
 } from '../../input/config-modal-types.ts';
 
 // ---------------------------------------------------------------------------
-// Policy → config-modal surface (W6.1 group-B port). Governance CONTENT view,
+// Policy → config-modal surface (group-B port). Governance CONTENT view,
 // not a selectable list — current/candidate bundle state, diff, divergence
 // gate, history, permission audit, lint findings, preflight review, and
 // simulation samples render as non-selectable rows (the host windows/scrolls

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

@@ -12,7 +12,7 @@ import type {
 } from '../../input/config-modal-types.ts';
 
 // ---------------------------------------------------------------------------
-// Security → config-modal surface (W6.1 group-B port). Two tabs: 'Tokens' (the
+// Security → config-modal surface (group-B port). Two tabs: 'Tokens' (the
 // token scope/rotation audit list under the governance summary) and
 // 'Governance' (policy preflight, MCP/plugin quarantine, latest incident, and
 // the MCP attack-path review). Read-model-backed, so refresh() is a no-op —
@@ -74,6 +74,7 @@ class SecurityModalSurface implements ConfigModalSurface {
   readonly actions = [
     { key: 'f', id: 'preflight', label: 'preflight' },
     { key: 'i', id: 'jumpToIncident', label: 'jump to incident', enabledFor: () => Boolean(this.deps.readModel.getSnapshot().latestIncident) },
+    { key: 'd', id: 'manageDevices', label: 'manage devices' },
     { key: 'r', id: 'refresh', label: 'refresh audit' },
   ];
 
@@ -170,6 +171,11 @@ class SecurityModalSurface implements ConfigModalSurface {
     if (id === 'jumpToIncident' && this.deps.readModel.getSnapshot().latestIncident) {
       void ctx.executeCommand?.('panel', ['open', 'incident']);
       ctx.setStatus('Opened the incident surface (fleet).');
+      return;
+    }
+    if (id === 'manageDevices') {
+      ctx.openModal?.('devices-modal');
+      ctx.setStatus('Opened paired-device management.');
     }
   }
 }

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

@@ -8,7 +8,7 @@ import type { SkillOrigin, SkillRecord } from '../skills-panel.ts';
 import { listInstalledEcosystemEntries, type EcosystemCatalogPathOptions, type ShellPathService } from '@/runtime/index.ts';
 
 // ---------------------------------------------------------------------------
-// Skills → config-modal surface (W6.1 group-B port). Project-local and global
+// Skills → config-modal surface (group-B port). Project-local and global
 // skill-pack discovery. Disk scans happen only in refresh() (never in
 // buildView), mirroring the panel's onActivate()-triggered load. Browse-only:
 // the panel never had a command-routable mutation verb (no /skills delete/remove

package/src/panels/modals/work-plan-modal.ts

@@ -7,7 +7,7 @@ import type {
 import type { WorkPlanItemStatus } from '../../work-plans/work-plan-store.ts';
 
 // ---------------------------------------------------------------------------
-// Work Plan → config-modal surface (W6.1 group-B port). Lists the active
+// Work Plan → config-modal surface (group-B port). Lists the active
 // persistent plan's checklist items with a progress summary + status counts.
 // All mutations (add/edit item, cycle/set status, remove, clear-completed)
 // route to the existing `/work-plan` command path (charter: no
@@ -65,8 +65,8 @@ class WorkPlanModalSurface implements ConfigModalSurface {
   private readonly hasRow = (row: ConfigModalRow | null): boolean => row !== null;
 
   /** 'i'/'w' jump to the selected item's linked agent/WRFC chain in Fleet
-   *  (DEBT-5 item 4 — restores the retired WorkPlanPanel's per-item deep-link,
-   *  lost when W6.1 migrated this surface to a modal without it). Gated on
+   *  (item 4 — restores the retired WorkPlanPanel's per-item deep-link,
+   *  lost when migrated this surface to a modal without it). Gated on
    *  the link actually being present, same as the retired panel gated the key
    *  on `item?.linked?.agentId`/`wrfcId` before ever reaching the jump. */
   private readonly hasAgentLink = (row: ConfigModalRow | null): boolean =>

package/src/panels/notifications-feed.ts

@@ -0,0 +1,127 @@
+/**
+ * PanelNotificationFeed — the read-model behind the `panel_only` notification
+ * target.
+ *
+ * The SDK's NotificationRouter (`@/runtime/index.ts` -> platform runtime `ui`
+ * barrel) can route a notification's `RoutingDecision.target` to
+ * `'panel_only'`, meaning: don't surface this in the conversation or the
+ * status bar, but it must still reach a real, visible place. Before this
+ * file, nothing in this repo consumed that target outside of tests — a
+ * panel-routed notification (including every burst- or batch-collapsed one)
+ * had nowhere to go. This feed is that place: a caller holding a routed
+ * `Notification` + `RoutingDecision` pair calls `record()`, and
+ * `notifications-panel.ts` renders whatever has accumulated.
+ *
+ * Collapsed groups (reasonCode `burst_collapsed` / `batch_window_collapsed`)
+ * are tracked by their `batchKey` and accumulate an honest running count
+ * instead of rendering one row per suppressed duplicate.
+ *
+ * Production wiring — something in the running app actually calling
+ * `record()` with live notifications — rides the SDK round that turns on
+ * adaptive notification suppression by default; this feed and its panel are
+ * the render target that work lands on, built ahead of it so the target is
+ * never missing when that switch flips.
+ */
+import type { Notification, RoutingDecision } from '@/runtime/index.ts';
+
+export interface PanelFeedEntry {
+  readonly key: string;
+  readonly domain: string;
+  readonly level: Notification['level'];
+  readonly title: string;
+  readonly body: string | undefined;
+  /** Unix ms of the most recent notification folded into this entry. */
+  readonly timestamp: number;
+  readonly reasonCode: RoutingDecision['reasonCode'];
+  /** How many notifications this entry represents. 1 for a standalone item; >1 for a collapsed group. Always the true count — never estimated. */
+  readonly collapsedCount: number;
+}
+
+const MAX_ENTRIES = 200;
+
+/** Reason codes whose notifications fold into one running-count entry per batch key, rather than one entry per occurrence. */
+const COLLAPSING_REASON_CODES: ReadonlySet<RoutingDecision['reasonCode']> = new Set([
+  'burst_collapsed',
+  'batch_window_collapsed',
+]);
+
+export class PanelNotificationFeed {
+  private readonly entries = new Map<string, PanelFeedEntry>();
+  /** Insertion order of `entries` keys (oldest first), for bounded eviction. */
+  private order: string[] = [];
+  private readonly listeners = new Set<() => void>();
+
+  /**
+   * Record a routed notification. Only notifications actually targeted at
+   * `panel_only` are kept — a caller passing anything else is a mistake (the
+   * router sent it elsewhere), so it's dropped rather than shown in the
+   * wrong place.
+   */
+  record(notification: Notification, decision: RoutingDecision): void {
+    if (decision.target !== 'panel_only') return;
+
+    const collapsing = COLLAPSING_REASON_CODES.has(decision.reasonCode) && Boolean(decision.batchKey);
+    const key = collapsing ? `group:${decision.batchKey}` : `single:${notification.id}`;
+    const previousCount = collapsing ? (this.entries.get(key)?.collapsedCount ?? 0) : 0;
+
+    const entry: PanelFeedEntry = {
+      key,
+      domain: notification.domain,
+      level: notification.level,
+      title: notification.title,
+      body: notification.body,
+      timestamp: notification.timestamp,
+      reasonCode: decision.reasonCode,
+      collapsedCount: previousCount + 1,
+    };
+
+    if (!this.entries.has(key)) {
+      this.order.push(key);
+      if (this.order.length > MAX_ENTRIES) {
+        const evicted = this.order.shift();
+        if (evicted !== undefined) this.entries.delete(evicted);
+      }
+    }
+    this.entries.set(key, entry);
+    this.emitChange();
+  }
+
+  /** Every entry, most recently updated first. */
+  list(): readonly PanelFeedEntry[] {
+    const items: PanelFeedEntry[] = [];
+    for (const key of this.order) {
+      const entry = this.entries.get(key);
+      if (entry) items.push(entry);
+    }
+    return items.reverse();
+  }
+
+  clear(): void {
+    this.entries.clear();
+    this.order = [];
+    this.emitChange();
+  }
+
+  /** Subscribe to feed changes (e.g. to mark a panel dirty). Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emitChange(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
+let sharedFeed: PanelNotificationFeed | null = null;
+
+/**
+ * The process-wide `panel_only` feed. Lazily created so the running app has
+ * exactly one feed that every future caller and the NotificationsPanel agree
+ * on, while tests construct their own isolated `PanelNotificationFeed`
+ * instance instead of reaching for this one.
+ */
+export function getSharedNotificationFeed(): PanelNotificationFeed {
+  if (!sharedFeed) sharedFeed = new PanelNotificationFeed();
+  return sharedFeed;
+}