@pellux/goodvibes-tui 1.17.0 → 1.19.0

package/src/core/conversation-rendering.ts

@@ -1,7 +1,7 @@
 import { UIFactory } from '../renderer/ui-factory.ts';
 import { renderMarkdownTracked } from '../renderer/markdown.ts';
 import { renderDiffView } from '../renderer/diff-view.ts';
-import { activeTheme } from '../renderer/theme.ts';
+import { activeTheme, activeUiTones } from '../renderer/theme.ts';
 import { renderToolCallBlock } from '../renderer/tool-call.ts';
 import { summarizeToolResult } from '../renderer/tool-result-summary.ts';
 import type { ToolCall } from '@pellux/goodvibes-sdk/platform/types';
@@ -291,11 +291,20 @@ export function renderConversationToolMessage(
     context.collapseState.set(collapseKey, isShort ? false : true);
   }
 
+  // A per-call user cancellation settles as a tool result whose content leads
+  // with "Error: cancelled by user" (the SDK's structured cancelled shape; any
+  // partial output the tool produced before it stopped follows on later lines).
+  // Render it structurally as a distinct "cancelled" block in the warn tone —
+  // not a generic tool result, and not a hard error — so the transcript reads
+  // the user's decision honestly while the partial output stays visible below.
+  const isCancelled = blockType === 'tool' && /^Error: cancelled by user\b/.test(contentLines[0] ?? '');
+  const warnTone = activeUiTones().chrome.warn;
+
   context.history.addLine(renderConversationEventLine(width, {
-    marker: blockType === 'diff' ? GLYPHS.status.dualPane : GLYPHS.status.active,
-    markerFg: blockType === 'diff' ? T.diffAccent : T.toolAccent,
-    label: blockType === 'diff' ? 'diff' : 'tool result',
-    labelFg: blockType === 'diff' ? T.diffAccent : T.toolAccent,
+    marker: isCancelled ? GLYPHS.status.blocked : (blockType === 'diff' ? GLYPHS.status.dualPane : GLYPHS.status.active),
+    markerFg: isCancelled ? warnTone : (blockType === 'diff' ? T.diffAccent : T.toolAccent),
+    label: isCancelled ? 'cancelled' : (blockType === 'diff' ? 'diff' : 'tool result'),
+    labelFg: isCancelled ? warnTone : (blockType === 'diff' ? T.diffAccent : T.toolAccent),
     detailFg: '244',
   }, [
     ...(message.toolName

package/src/core/memory-diagnostics-gateway.ts

@@ -0,0 +1,99 @@
+// ---------------------------------------------------------------------------
+// memory-diagnostics-gateway.ts
+//
+// The daemon-backed verb the /health memory (doctor) surface reads:
+// ops.memory.get (GET /api/ops/memory) — the read-only MemoryGovernor snapshot.
+// No named facade exists on the in-process OperatorClient, so — exactly like
+// the memory-consolidation and voice-provisioning gateways — 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 daemon that predates the memory governor answers an honest 501 (the verb is
+// cataloged but has no handler when no live governor is composed) or a 404 (an
+// older daemon without the route) — both mean "this daemon does not serve
+// memory diagnostics", NOT a fabricated all-zero snapshot (see
+// classifyMemoryDiagnosticsError). The interface is injectable so the command
+// and its tests round-trip against a mocked daemon.
+// ---------------------------------------------------------------------------
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { GoodVibesSdkError } from '@pellux/goodvibes-sdk';
+import { resolveOperatorRpc, describeOperatorRpcError } from '../input/commands/operator-rpc.ts';
+import { memoryStatusLines, type MemoryGovernorSnapshotResult } from './memory-status.ts';
+
+/** The narrow async verb surface the /health memory (doctor) surface drives. */
+export interface MemoryDiagnosticsGateway {
+  /** Read the MemoryGovernor snapshot (ops.memory.get). */
+  fetchSnapshot(): Promise<MemoryGovernorSnapshotResult>;
+}
+
+/**
+ * Why the gateway could not be built (daemon disabled / no control-plane URL),
+ * surfaced verbatim so the surface prints an honest "unavailable" line rather
+ * than guessing — mirrors the memory-consolidation / voice gateways.
+ */
+export type MemoryDiagnosticsGatewayResolution =
+  | { readonly available: true; readonly gateway: MemoryDiagnosticsGateway }
+  | { readonly available: false; readonly reason: string };
+
+export interface MemoryDiagnosticsGatewayDeps {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string | (() => string);
+}
+
+/**
+ * Build the live memory-diagnostics gateway over the generic operator invoke
+ * path — the same daemon resolution the command layer uses. Returns an honest
+ * unavailable reason when no daemon is reachable.
+ */
+export function createMemoryDiagnosticsGateway(deps: MemoryDiagnosticsGatewayDeps): MemoryDiagnosticsGatewayResolution {
+  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: { fetchSnapshot: () => sdk.operator.invoke('ops.memory.get', {}) },
+  };
+}
+
+/** How an ops.memory.get rejection should render. */
+export type MemoryDiagnosticsFailure =
+  | { readonly kind: 'unavailable'; readonly reason: string }
+  | { readonly kind: 'error'; readonly message: string };
+
+/** The honest "no memory diagnostics" reason for a daemon that predates the governor verb. */
+export const MEMORY_DIAGNOSTICS_UNAVAILABLE = 'this daemon does not serve memory diagnostics.';
+
+/**
+ * Classify an ops.memory.get rejection: a 501 (a daemon composed without a live
+ * governor — the verb is cataloged but unhandled) or a 404 (an older daemon
+ * without the route) are both "verb unavailable"; anything else (network,
+ * 401/403, 500) is a generic error.
+ */
+export function classifyMemoryDiagnosticsError(error: unknown): MemoryDiagnosticsFailure {
+  if (error instanceof GoodVibesSdkError && (error.status === 501 || error.status === 404)) {
+    return { kind: 'unavailable', reason: MEMORY_DIAGNOSTICS_UNAVAILABLE };
+  }
+  return { kind: 'error', message: describeOperatorRpcError(error) };
+}
+
+/**
+ * Render the /health memory (doctor) block from an already-resolved gateway
+ * resolution — the testable core the command wraps. Kept separate from the live
+ * gateway construction so a wire test injects a fake resolution (available /
+ * unavailable / failing) with no HTTP.
+ */
+export async function renderMemoryDiagnostics(resolution: MemoryDiagnosticsGatewayResolution): Promise<string> {
+  if (!resolution.available) {
+    return `Health Review: Memory\n  memory diagnostics unavailable: ${resolution.reason}`;
+  }
+  try {
+    const snapshot = await resolution.gateway.fetchSnapshot();
+    return ['Health Review: Memory', ...memoryStatusLines(snapshot)].join('\n');
+  } catch (error) {
+    const failure = classifyMemoryDiagnosticsError(error);
+    return failure.kind === 'unavailable'
+      ? `Health Review: Memory\n  ${failure.reason}`
+      : `Health Review: Memory\n  could not read memory diagnostics: ${failure.message}`;
+  }
+}

package/src/core/memory-provenance.ts

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// memory-provenance.ts — the optional "used N memories" turn chip (owner-ruled
+// 2026-07-13, default OFF).
+//
+// The SDK tags each turn payload with the memory-sourced injection ids it drew
+// on: `metadata.memory.recordIds: string[]` (absent when none) — the SAME
+// convention the webui's chip reads, so both surfaces name the same records.
+// When the memory-provenance setting is ON, a turn that used memories shows a
+// small chip naming how many, with a drill-in listing them. When OFF (default),
+// NOTHING is rendered and the metadata is never even read.
+// ---------------------------------------------------------------------------
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/** TUI-local setting key: show the per-turn memory-provenance chip. Default OFF. */
+export const MEMORY_SHOW_PROVENANCE_CONFIG_KEY = 'memory.showProvenance';
+export const MEMORY_SHOW_PROVENANCE_DEFAULT = false;
+export const MEMORY_SHOW_PROVENANCE_DESCRIPTION =
+  'Show a "used N memories" chip on turns that drew on your standing memories, with a drill-in ' +
+  'listing them (Alt+M to expand). Off by default; when off, nothing is rendered and no metadata is read.';
+
+/**
+ * Read the memory-provenance toggle defensively. `memory.*` is a TUI-local
+ * section with no SDK DEFAULT_CONFIG entry, so ConfigManager.get() throws for
+ * it until something has been written — an unset key means the default (OFF),
+ * not an error (same pattern as memory.projection.dir).
+ */
+export function readMemoryShowProvenance(configManager: Pick<ConfigManager, 'get'>): boolean {
+  try {
+    return configManager.get(MEMORY_SHOW_PROVENANCE_CONFIG_KEY as Parameters<ConfigManager['get']>[0]) === true;
+  } catch {
+    return MEMORY_SHOW_PROVENANCE_DEFAULT;
+  }
+}
+
+/**
+ * Extract the memory-sourced record ids a turn drew on, from the SDK's
+ * `metadata.memory.recordIds` convention. Structural (not a named import) so it
+ * reads the field whether or not the pinned SDK's TurnEvent type surfaces it
+ * yet, and yields an empty list for any turn without the field — never a guess,
+ * never a throw.
+ */
+export function memoryRecordIdsFromTurn(turn: unknown): readonly string[] {
+  const metadata = (turn as { metadata?: unknown } | null | undefined)?.metadata;
+  const memory = (metadata as { memory?: unknown } | null | undefined)?.memory;
+  const recordIds = (memory as { recordIds?: unknown } | null | undefined)?.recordIds;
+  if (!Array.isArray(recordIds)) return [];
+  return recordIds.filter((id): id is string => typeof id === 'string');
+}
+
+/**
+ * Build the settings-modal synthetic entry for memory.showProvenance (TUI-local,
+ * default OFF). Read defensively — memory.* has no SDK DEFAULT_CONFIG entry, so
+ * an unset key means the OFF default, not an error.
+ */
+export function buildMemoryProvenanceSyntheticEntry(configManager: Pick<ConfigManager, 'get'>): {
+  setting: { key: string; type: 'boolean'; default: boolean; description: string };
+  currentValue: boolean;
+  isDefault: boolean;
+} {
+  const currentValue = readMemoryShowProvenance(configManager);
+  return {
+    setting: { key: MEMORY_SHOW_PROVENANCE_CONFIG_KEY, type: 'boolean', default: MEMORY_SHOW_PROVENANCE_DEFAULT, description: MEMORY_SHOW_PROVENANCE_DESCRIPTION },
+    currentValue,
+    isDefault: currentValue === MEMORY_SHOW_PROVENANCE_DEFAULT,
+  };
+}

package/src/core/memory-status.ts

@@ -0,0 +1,118 @@
+// ---------------------------------------------------------------------------
+// memory-status.ts — the surface-facing projection of the daemon's memory
+// governance (ops.memory.get + OPS_MEMORY_PRESSURE).
+//
+// The SDK's MemoryGovernor owns the policy: it samples RSS/heap against a
+// budget, sheds memory by tier (trimming registered caches, pausing deferrable
+// background jobs), refuses new expensive work at the critical tier, and trips
+// on a genuine leak before the OS OOM-kills it. This module is the read-only
+// projection the /health memory (doctor) surface renders from — the snapshot
+// rows — and the attention line OPS_MEMORY_PRESSURE produces when the tier
+// changes or the tripwire fires.
+//
+// Pure formatting only (no I/O): the command fetches the typed verb response
+// over the operator invoke seam (memory-diagnostics-gateway.ts) and hands it
+// here, so these builders are unit-testable against fixture shapes.
+// ---------------------------------------------------------------------------
+
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+import type { OpsEvent } from '@/runtime/index.ts';
+
+/** ops.memory.get output — the full governor snapshot. */
+export type MemoryGovernorSnapshotResult = OperatorMethodOutput<'ops.memory.get'>;
+/** The OPS_MEMORY_PRESSURE event payload (a tier change or a tripwire firing). */
+export type MemoryPressurePayload = Extract<OpsEvent, { type: 'OPS_MEMORY_PRESSURE' }>;
+
+/** Human MB (the governor already reports MB as numbers; round to 1 decimal). */
+export function formatMb(mb: number | null | undefined): string {
+  if (mb === null || mb === undefined || !Number.isFinite(mb)) return 'unknown';
+  return `${mb >= 100 ? Math.round(mb) : Math.round(mb * 10) / 10} MB`;
+}
+
+/** Human byte size for a cache footprint estimate. */
+export function formatMemoryBytes(bytes: number | null | undefined): string {
+  if (bytes === null || bytes === undefined || !Number.isFinite(bytes) || bytes < 0) return 'size n/a';
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value >= 10 ? value.toFixed(0) : value.toFixed(1)} ${units[unit]}`;
+}
+
+/** A plain-language note for the current tier (the governor's posture at this tier). */
+export function memoryTierNote(tier: MemoryGovernorSnapshotResult['tier']): string {
+  switch (tier) {
+    case 'normal': return 'footprint is comfortably within budget';
+    case 'elevated': return 'trimming caches to a floor and running gc';
+    case 'high': return 'flushing caches and pausing deferrable background jobs';
+    case 'critical': return 'refusing new expensive work until the footprint recovers';
+    default: return '';
+  }
+}
+
+/**
+ * The /health memory (doctor) rows — the honest account of the daemon defending
+ * its footprint. Order: tier + posture, budget vs RSS, heap, tier thresholds,
+ * per-cache footprints the governor can shrink, which deferrable jobs are
+ * paused, and the leak-tripwire state.
+ */
+export function memoryStatusLines(snapshot: MemoryGovernorSnapshotResult): string[] {
+  const lines: string[] = [];
+  lines.push(`  tier: ${snapshot.tier} — ${memoryTierNote(snapshot.tier)}`);
+  if (snapshot.refusingExpensiveWork) {
+    lines.push('  expensive work: REFUSED (critical tier) — new ingestion / reindex / voice install is declined until RSS recovers');
+  }
+  lines.push(`  budget: ${formatMb(snapshot.rssMb)} rss / ${formatMb(snapshot.budgetMb)} budget (${Math.round(snapshot.usedPct)}%)`);
+  const heap = snapshot.heapTotalMb !== undefined
+    ? `${formatMb(snapshot.heapUsedMb)} used / ${formatMb(snapshot.heapTotalMb)} total`
+    : formatMb(snapshot.heapUsedMb);
+  lines.push(`  heap: ${heap}`);
+  lines.push(`  tiers: elevated ${snapshot.thresholds.elevatedPct}% · high ${snapshot.thresholds.highPct}% · critical ${snapshot.thresholds.criticalPct}%`);
+
+  if (snapshot.caches.length === 0) {
+    lines.push('  caches: none registered');
+  } else {
+    lines.push(`  caches: ${snapshot.caches.length}`);
+    for (const cache of snapshot.caches) {
+      const size = cache.estimatedBytes !== undefined ? `, ~${formatMemoryBytes(cache.estimatedBytes)}` : '';
+      lines.push(`    ${cache.id} (${cache.name}): ${cache.entries} entries${size}`);
+    }
+  }
+
+  lines.push(snapshot.pausedJobs.length === 0
+    ? '  paused jobs: none'
+    : `  paused jobs: ${snapshot.pausedJobs.join(', ')}`);
+
+  if (snapshot.tripwire.armed) {
+    lines.push(`  tripwire: ARMED — watching for a sustained >${snapshot.tripwire.rateMbPerSec} MB/s post-flush leak (held ${Math.round(snapshot.tripwire.sustainedSec)}s)`);
+  } else {
+    lines.push('  tripwire: disarmed (no post-flush leak growth under watch)');
+  }
+  return lines;
+}
+
+/**
+ * The attention line OPS_MEMORY_PRESSURE produces: a one-liner naming the new
+ * tier and the RSS/budget, plus a distinct escalation when the leak tripwire
+ * fires (the daemon is about to exit for a clean supervisor restart). Returned
+ * as a single string so the notice/attention surface can push it directly.
+ */
+export function memoryPressureLine(event: MemoryPressurePayload): string {
+  const base = `memory pressure: ${event.previousTier} → ${event.tier} (${formatMb(event.rssMb)} rss / ${formatMb(event.budgetMb)} budget, ${Math.round(event.usedPct)}%)`;
+  if (event.tripwire) {
+    return `${base} — leak tripwire fired (${event.tripwire.rateMbPerSec} MB/s sustained ${Math.round(event.tripwire.sustainedSec)}s); the daemon will exit for a clean restart`;
+  }
+  if (event.note) return `${base} — ${event.note}`;
+  return base;
+}
+
+/** Severity for the notice feed: critical tier (or a tripwire) is critical; high is a warning. */
+export function memoryPressureLevel(event: MemoryPressurePayload): 'info' | 'warning' | 'critical' {
+  if (event.tripwire || event.tier === 'critical') return 'critical';
+  if (event.tier === 'high') return 'warning';
+  return 'info';
+}

package/src/core/pairing-devices.ts

@@ -0,0 +1,49 @@
+/**
+ * pairing-devices.ts — shared rendering for the paired-device list.
+ *
+ * Both the /devices command family and the settings device-management modal
+ * render each per-device token the same way (name · created · last-seen · id),
+ * so the two surfaces never drift. Pure over its inputs and a `now` clock, so
+ * the formatting is testable without real time.
+ */
+import type { PublicPairingToken } from '@pellux/goodvibes-sdk/platform/pairing';
+
+/** A short, human-quotable id prefix used to target rename/revoke. */
+export function shortTokenId(id: string): string {
+  return id.slice(0, 8);
+}
+
+/** Relative last-seen, or "never" when the device has not authenticated yet. */
+export function formatLastSeen(ms: number | undefined, now: number = Date.now()): string {
+  if (ms === undefined) return 'never';
+  const delta = Math.max(0, now - ms);
+  if (delta < 60_000) return 'just now';
+  const mins = Math.floor(delta / 60_000);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+/** Creation date as YYYY-MM-DD. */
+export function formatCreated(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/** One device line: name · created · last-seen · short id. */
+export function formatDeviceLine(token: PublicPairingToken, now: number = Date.now()): string {
+  return `${token.name}  ·  created ${formatCreated(token.createdAt)}  ·  last seen ${formatLastSeen(token.lastSeenAt, now)}  ·  ${shortTokenId(token.id)}`;
+}
+
+/** Resolve a token by exact id or unambiguous id-prefix; returns a resolution result. */
+export function resolveTokenByIdPrefix(
+  tokens: readonly PublicPairingToken[],
+  idOrPrefix: string,
+): { readonly ok: true; readonly token: PublicPairingToken } | { readonly ok: false; readonly reason: 'not-found' | 'ambiguous' } {
+  const exact = tokens.find((t) => t.id === idOrPrefix);
+  if (exact) return { ok: true, token: exact };
+  const matches = tokens.filter((t) => t.id.startsWith(idOrPrefix));
+  if (matches.length === 1) return { ok: true, token: matches[0]! };
+  if (matches.length === 0) return { ok: false, reason: 'not-found' };
+  return { ok: false, reason: 'ambiguous' };
+}

package/src/core/pairing-handoff.ts

@@ -0,0 +1,101 @@
+/**
+ * pairing-handoff.ts — the one place a TUI pairing producer mints a link.
+ *
+ * Every producer (the `gv pair` CLI block, the pairing modal QR, the /qrcode
+ * flow) routes through mintPairingHandoff, which mints a fresh per-device token
+ * and encodes the SDK's canonical `#pair=<token>` deep link — the exact shape
+ * the web app consumes, byte-for-byte the same as the `pairing.handoff.create`
+ * gateway verb's handler (mint + buildPairingHandoffLink). No producer encodes a
+ * raw JSON connection blob any more: a camera scan of the QR opens the web app
+ * already carrying the one-time token, so the device lands signed in.
+ *
+ * The token rides in the URL fragment, never the query, so it is never sent to a
+ * server (no access-log / Referer exposure). The offer set rides alongside so a
+ * bundle-aware surface can present the notifications/relay/passkey steps.
+ */
+import {
+  buildPairingHandoffFragment,
+  buildPairingHandoffLink,
+  describeOriginPosture,
+  type MintedPairingToken,
+  type OriginPosture,
+  type PairingHandoffOfferKind,
+} from '@pellux/goodvibes-sdk/platform/pairing';
+
+/** The token-minting surface a handoff needs — satisfied by the SDK's PairingTokenManager. */
+export interface PairingTokenMinter {
+  mint(input: { readonly name: string }): MintedPairingToken;
+}
+
+export interface PairingHandoff {
+  readonly token: MintedPairingToken;
+  readonly offers: readonly PairingHandoffOfferKind[];
+  /** `#pair=<token>` (with an `offers=` key when offers are present). */
+  readonly fragment: string;
+  /** `<webOrigin>/#pair=<token>` — present only when a web origin is known. */
+  readonly deepLink?: string | undefined;
+  /**
+   * The honest TLS/capability posture of the web origin the deep link opens —
+   * the same field the `pairing.handoff.create` gateway verb carries (both
+   * computed by the SDK's describeOriginPosture). Present only when a web origin
+   * is known; a surface renders its one honest LAN line and its labeled
+   * capability list from here, never from a locally-authored string.
+   */
+  readonly posture?: OriginPosture | undefined;
+}
+
+export interface MintPairingHandoffInput {
+  readonly pairingTokens: PairingTokenMinter;
+  /** The device/token name shown to the user and stored on the token; editable later. */
+  readonly name: string;
+  readonly offers: readonly PairingHandoffOfferKind[];
+  /** The web-app origin the deep link points at; absent ⇒ fragment-only. */
+  readonly webOrigin?: string | undefined;
+}
+
+/**
+ * A default name for a freshly-minted pairing token when the user did not supply
+ * one. Names are shown and editable later in the device management surface, so a
+ * date-stamped default is enough to tell two devices apart at a glance.
+ */
+export function defaultPairingTokenName(now: Date = new Date()): string {
+  const stamp = now.toISOString().slice(0, 16).replace('T', ' ');
+  return `paired device (${stamp})`;
+}
+
+export function mintPairingHandoff(input: MintPairingHandoffInput): PairingHandoff {
+  const token = input.pairingTokens.mint({ name: input.name });
+  const fragment = buildPairingHandoffFragment({ token: token.token, offers: input.offers });
+  const deepLink = input.webOrigin
+    ? buildPairingHandoffLink({ webOrigin: input.webOrigin, token: token.token, offers: input.offers })
+    : undefined;
+  // The posture is described from the SAME web origin the deep link opens — the
+  // identical computation the gateway verb performs — so a locally-minted handoff
+  // carries the same honest posture as one minted over the wire.
+  const posture = input.webOrigin ? describeOriginPosture(input.webOrigin) : undefined;
+  return { token, offers: input.offers, fragment, ...(deepLink ? { deepLink } : {}), ...(posture ? { posture } : {}) };
+}
+
+/** The link content a QR should encode: the full deep link when known, else the fragment. */
+export function pairingQrContent(handoff: PairingHandoff): string {
+  return handoff.deepLink ?? handoff.fragment;
+}
+
+export interface PairingOfferAvailability {
+  /** Whether the rendezvous relay is configured ⇒ the relay offer is presentable. */
+  readonly relayEnabled: boolean;
+  /** Whether a step-up (passkey) ceremony is wired ⇒ the passkey offer is presentable. */
+  readonly stepUpAvailable: boolean;
+}
+
+/**
+ * The offers this daemon can satisfy right now, in canonical order. Notifications
+ * are always available (browser push needs no server-side prerequisite beyond
+ * the VAPID key the daemon mints on demand); relay and passkey are gated.
+ */
+export function availablePairingOffers(availability: PairingOfferAvailability): PairingHandoffOfferKind[] {
+  const offers: PairingHandoffOfferKind[] = ['notifications'];
+  if (availability.relayEnabled) offers.push('relay');
+  if (availability.stepUpAvailable) offers.push('passkey');
+  return offers;
+}

package/src/core/pairing-offers.ts

@@ -0,0 +1,83 @@
+/**
+ * pairing-offers.ts — plain-language copy for the pairing offer set, the one
+ * honest LAN-posture line, and the labeled browser-capability list.
+ *
+ * Each offer names, in plain terms, what accepting it does and what declining it
+ * costs — no security jargon, just the concrete consequence. Every offer is
+ * independently declinable; a pairing without any accepted offer still pairs the
+ * device (it just signs in with none of the extras).
+ *
+ * The one honest LAN line and the per-capability availability both come from the
+ * SDK posture (describeOriginPosture / the `posture` field on a handoff), so
+ * every surface renders the SAME truth: the exact LAN_PLAIN_HTTP_NOTICE wording
+ * only when the posture carries it, and each browser-gated capability labeled
+ * with whether the paired device gets it (and why not, when it does not).
+ */
+import type {
+  BrowserGatedCapability,
+  OriginPosture,
+  PairingHandoffOfferKind,
+} from '@pellux/goodvibes-sdk/platform/pairing';
+
+export interface PairingOfferCopy {
+  readonly title: string;
+  /** One plain-language line: what accepting does, and what declining leaves you with. */
+  readonly consequence: string;
+}
+
+export const PAIRING_OFFER_COPY: Record<PairingHandoffOfferKind, PairingOfferCopy> = {
+  notifications: {
+    title: 'Notifications',
+    consequence: 'This device gets a push when an agent needs your input or a run finishes. Decline and it pairs without push.',
+  },
+  relay: {
+    title: 'Relay',
+    consequence: 'Reach this daemon from off the LAN through the rendezvous relay, which sees only ciphertext and connection metadata. Decline to stay LAN-only.',
+  },
+  passkey: {
+    title: 'Passkey',
+    consequence: 'Register a passkey on this device to confirm sensitive actions with a tap. Decline and sensitive actions ask another way.',
+  },
+};
+
+/** The offer set as `label — consequence` lines, in the given order. */
+export function formatPairingOffers(offers: readonly PairingHandoffOfferKind[]): string[] {
+  return offers.map((kind) => {
+    const copy = PAIRING_OFFER_COPY[kind];
+    return `  ${copy.title} — ${copy.consequence}`;
+  });
+}
+
+/**
+ * Plain-language label for each browser-gated capability the posture reports —
+ * what the paired device would actually get, named without jargon.
+ */
+export const POSTURE_CAPABILITY_LABEL: Record<BrowserGatedCapability, string> = {
+  'service-worker': 'Offline app (installable / background sync)',
+  push: 'Push notifications',
+  microphone: 'Voice input (microphone)',
+};
+
+/**
+ * The one honest LAN line to render, or null. This is the SDK posture's own
+ * `notice` field verbatim (LAN_PLAIN_HTTP_NOTICE) — present ONLY for the
+ * plain-http-on-LAN posture, absent (and so never a nag) everywhere else.
+ */
+export function pairingPostureNotice(posture: OriginPosture | undefined): string | null {
+  return posture?.notice ?? null;
+}
+
+/**
+ * The labeled capability list from the posture: each browser-gated capability as
+ * a `Label — available` / `Label — <reason>` line, so the pairing surface lists
+ * what the paired device will get instead of hiding a dead button. Empty when no
+ * posture is known.
+ */
+export function formatPostureCapabilities(posture: OriginPosture | undefined): string[] {
+  if (!posture) return [];
+  return posture.capabilities.map((cap) => {
+    const label = POSTURE_CAPABILITY_LABEL[cap.capability as BrowserGatedCapability] ?? cap.capability;
+    const status = cap.available ? 'available' : (cap.reason ?? 'unavailable');
+    return `  ${label} — ${status}`;
+  });
+}

package/src/core/pairing-origin.ts

@@ -0,0 +1,78 @@
+/**
+ * pairing-origin.ts — the web-app origin a pairing deep link points at, and the
+ * one-time write of web.publicBaseUrl from the stable-name resolution.
+ *
+ * The origin is the WEB endpoint's public URL (the surface the `#pair=<token>`
+ * link opens), not the control-plane daemon URL. A user-set web.publicBaseUrl is
+ * authoritative and is never re-derived or clobbered; only when it is empty do
+ * we fall back to `http://<stable-host>:<web-port>` using the same ladder the
+ * printed/QR link uses, so the link and the persisted origin always agree.
+ */
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { resolveRuntimeEndpointBinding } from '../cli/endpoints.ts';
+import { stableUrlHostForBindHost, type ResolvedStableHost, type StableHostInputs } from './stable-host.ts';
+
+export interface PairingWebOrigin {
+  readonly origin: string;
+  readonly resolvedHost: ResolvedStableHost;
+  /** True when the origin is http:// on a non-loopback host — the honest LAN-posture case. */
+  readonly httpOnLan: boolean;
+  /** True when the origin came verbatim from a user-set web.publicBaseUrl. */
+  readonly fromPublicBaseUrl: boolean;
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, '');
+}
+
+/** http:// on anything other than loopback is served in the clear on the LAN. */
+export function isHttpOnLan(origin: string): boolean {
+  if (!origin.startsWith('http://')) return false;
+  let host: string;
+  try {
+    host = new URL(origin).hostname;
+  } catch {
+    return false;
+  }
+  return host !== '127.0.0.1' && host !== 'localhost' && host !== '::1';
+}
+
+export function resolvePairingWebOrigin(
+  configManager: Pick<ConfigManager, 'get'>,
+  probe?: () => StableHostInputs,
+): PairingWebOrigin {
+  const publicBaseUrl = trimTrailingSlash(String(configManager.get('web.publicBaseUrl') ?? '').trim());
+  if (publicBaseUrl) {
+    return { origin: publicBaseUrl, resolvedHost: { host: hostnameOf(publicBaseUrl), kind: 'gateway-interface', stable: true }, httpOnLan: isHttpOnLan(publicBaseUrl), fromPublicBaseUrl: true };
+  }
+  const binding = resolveRuntimeEndpointBinding(configManager, 'web');
+  const resolvedHost = stableUrlHostForBindHost(binding.host, probe);
+  const origin = `http://${resolvedHost.host}:${binding.port}`;
+  return { origin, resolvedHost, httpOnLan: isHttpOnLan(origin), fromPublicBaseUrl: false };
+}
+
+function hostnameOf(origin: string): string {
+  try {
+    return new URL(origin).hostname;
+  } catch {
+    return origin;
+  }
+}
+
+/**
+ * Persist web.publicBaseUrl once, from the stable-name resolution, and only when
+ * it is empty AND the resolution produced a stable name (a DHCP-bound address is
+ * not worth freezing into config). Returns the resolved origin either way. Never
+ * overwrites a user-set value.
+ */
+export function ensurePublicBaseUrl(
+  configManager: Pick<ConfigManager, 'get' | 'setDynamic'>,
+  probe?: () => StableHostInputs,
+): PairingWebOrigin {
+  const resolved = resolvePairingWebOrigin(configManager, probe);
+  if (!resolved.fromPublicBaseUrl && resolved.resolvedHost.stable) {
+    configManager.setDynamic('web.publicBaseUrl', resolved.origin);
+    return { ...resolved, fromPublicBaseUrl: true };
+  }
+  return resolved;
+}