@pellux/goodvibes-tui 1.17.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -104,8 +104,8 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "1.8.0",
-    "@pellux/goodvibes-terminal-shell": "1.8.0",
+    "@pellux/goodvibes-sdk": "1.9.0",
+    "@pellux/goodvibes-terminal-shell": "1.9.0",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",
@@ -131,10 +131,10 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@pellux/goodvibes-tui-linux-x64": "1.17.0",
-    "@pellux/goodvibes-tui-linux-arm64": "1.17.0",
-    "@pellux/goodvibes-tui-darwin-x64": "1.17.0",
-    "@pellux/goodvibes-tui-darwin-arm64": "1.17.0"
+    "@pellux/goodvibes-tui-linux-x64": "1.18.0",
+    "@pellux/goodvibes-tui-linux-arm64": "1.18.0",
+    "@pellux/goodvibes-tui-darwin-x64": "1.18.0",
+    "@pellux/goodvibes-tui-darwin-arm64": "1.18.0"
   },
   "trustedDependencies": [],
   "overrides": {

package/src/cli/management-commands.ts

@@ -5,12 +5,16 @@ import { BUILTIN_SECRET_PROVIDER_SOURCES, describeSecretRef, isSecretRefInput, r
 import { getSubscriptionProviderConfig, listAvailableSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config';
 import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibes-sdk/platform/config';
 import { inspectProviderAuth } from '@/runtime/index.ts';
-import { getOrCreateCompanionToken, buildCompanionConnectionInfo, encodeConnectionPayload, formatConnectionBlock } from '@pellux/goodvibes-sdk/platform/pairing';
-import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
+import { generateQrMatrix, renderQrToString, PAIRING_HANDOFF_OFFER_KINDS, type PairingHandoffOfferKind } from '@pellux/goodvibes-sdk/platform/pairing';
+import { ensurePublicBaseUrl } from '../core/pairing-origin.ts';
+import { formatPairingOffers, formatPostureCapabilities, pairingPostureNotice } from '../core/pairing-offers.ts';
+import { defaultPairingTokenName } from '../core/pairing-handoff.ts';
+import { stableUrlHostForBindHost } from '../core/stable-host.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import type { CliCommandRuntime } from './types.ts';
-import { extractAuthorizationCode, formatJsonOrText, hasCommandFlag, openBrowser, probeTcp, readAuthPaths, runNonInteractiveAgent, urlHostForBindHost, withRuntimeServices, yesNo } from './management-utils.ts';
+import type { RuntimeServices } from '../runtime/services.ts';
+import { extractAuthorizationCode, formatJsonOrText, hasCommandFlag, openBrowser, probeTcp, readAuthPaths, readOptionValue, runNonInteractiveAgent, withRuntimeServices, yesNo } from './management-utils.ts';
 
 export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<string> {
   return await withRuntimeServices(runtime, async (services) => {
@@ -368,19 +372,80 @@ export async function renderControlPlaneStatus(runtime: CliCommandRuntime): Prom
   return formatControlPlaneStatus(runtime, await buildControlPlaneStatusResult(runtime));
 }
 
+interface PairingHandoffCreateResult {
+  readonly token: { readonly id: string; readonly name: string; readonly token: string };
+  readonly offers: readonly { readonly kind: PairingHandoffOfferKind }[];
+  readonly fragment: string;
+  readonly deepLink?: string | undefined;
+  /** The honest TLS/capability posture of the origin the QR points at (SDK-computed). */
+  readonly posture?: import('@pellux/goodvibes-sdk/platform/pairing').OriginPosture | undefined;
+}
+
 export async function renderPairing(runtime: CliCommandRuntime): Promise<string> {
-  const daemonHomeDir = join(runtime.homeDirectory, '.goodvibes', 'daemon');
-  const tokenRecord = getOrCreateCompanionToken('tui', { daemonHomeDir });
-  const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'controlPlane');
-  const daemonUrl = `http://${urlHostForBindHost(binding.host)}:${binding.port}`;
-  const info = buildCompanionConnectionInfo({
-    daemonUrl,
-    token: tokenRecord.token,
-    username: 'admin',
+  return await withRuntimeServices(runtime, async (services) => {
+    // Freeze a stable web origin once (never clobbering a user-set value) so the
+    // printed link and the daemon's own handoff origin agree and survive a DHCP
+    // lease change where a stable name exists. The verb re-derives the same origin
+    // and returns its honest posture, so this call is a persistence side effect.
+    ensurePublicBaseUrl(runtime.configManager);
+    const name = readOptionValue(runtime.cli.commandArgs, 'name') ?? defaultPairingTokenName();
+    // Mint through the canonical hand-off verb: it mints a fresh per-device token
+    // and returns the exact `#pair=<token>` deep link the web app consumes. The
+    // daemon filters the requested offer set down to what it can actually satisfy.
+    const result = (await services.gatewayMethods.invoke('pairing.handoff.create', {
+      body: { name, offers: [...PAIRING_HANDOFF_OFFER_KINDS] },
+      context: { principalId: 'admin', principalKind: 'user', admin: true },
+    })) as PairingHandoffCreateResult;
+    const link = result.deepLink ?? result.fragment;
+    const qr = renderQrToString(generateQrMatrix(link));
+    const lines: string[] = [
+      'Scan to pair a device — the QR opens the web app already signed in:',
+      '',
+      `  ${link}`,
+      `  Token name: ${result.token.name}  (rename or revoke later in /settings → security → devices)`,
+    ];
+    if (result.offers.length > 0) {
+      lines.push('', 'Offers carried in this pairing (each declinable in the web app):', ...formatPairingOffers(result.offers.map((o) => o.kind)));
+    }
+    // The labeled browser-capability list and the one honest LAN line both render
+    // from the SDK posture the verb returned — never a locally-authored string.
+    const capabilities = formatPostureCapabilities(result.posture);
+    if (capabilities.length > 0) lines.push('', 'This device will get:', ...capabilities);
+    const notice = pairingPostureNotice(result.posture);
+    if (notice) lines.push('', notice);
+    // Tailscale detection is read-only here (the interactive serve lives in the
+    // pairing modal); when detected with an https MagicDNS URL, name the encrypted
+    // path. Absence stays quiet.
+    lines.push(...(await renderPairingTailscaleLines(services)));
+    lines.push('', qr);
+    return lines.join('\n');
   });
-  const payload = encodeConnectionPayload(info);
-  const qr = renderQrToString(generateQrMatrix(payload));
-  return [formatConnectionBlock(info, payload), '', qr].join('\n');
+}
+
+interface TailscaleGetResult {
+  readonly available: boolean;
+  readonly httpsUrl?: string | undefined;
+  readonly detail: string;
+}
+
+/**
+ * Read-only tailscale detection for the `gv pair` block: when tailscale is
+ * available with a served https MagicDNS URL, name the encrypted path (the
+ * interactive one-action serve lives in the pairing modal). Quiet — an empty
+ * array — when tailscale is absent or the probe fails.
+ */
+async function renderPairingTailscaleLines(services: RuntimeServices): Promise<string[]> {
+  try {
+    const ts = (await services.gatewayMethods.invoke('tailscale.get', {
+      body: {},
+      context: { principalId: 'admin', principalKind: 'user', admin: true },
+    })) as TailscaleGetResult;
+    if (!ts.available) return [];
+    if (ts.httpsUrl) return ['', `Encrypted access (Tailscale): ${ts.httpsUrl}`];
+    return ['', 'Tailscale detected — run it as a serve target for encrypted https access (see the pairing modal).'];
+  } catch {
+    return [];
+  }
 }
 
 export async function renderRemote(runtime: CliCommandRuntime, label: 'remote' | 'bridge'): Promise<string> {
@@ -408,9 +473,11 @@ export function renderWeb(runtime: CliCommandRuntime): string {
   const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'web');
   const publicBaseUrl = String(runtime.configManager.get('web.publicBaseUrl') ?? '');
   const hasEndpointOverride = runtime.cli.flags.hostname !== undefined || runtime.cli.flags.port !== undefined;
+  // Prefer the stable-name resolution over the raw first-non-internal IPv4 so the
+  // printed URL survives a DHCP lease change where a stable name exists.
   const url = !hasEndpointOverride && publicBaseUrl
     ? publicBaseUrl
-    : `http://${urlHostForBindHost(binding.host)}:${binding.port}`;
+    : `http://${stableUrlHostForBindHost(binding.host).host}:${binding.port}`;
   const value = {
     enabled: runtime.configManager.get('web.enabled'),
     ...binding,

package/src/cli/management.ts

@@ -11,8 +11,6 @@ import { BUILTIN_SECRET_PROVIDER_SOURCES, describeSecretRef, isSecretRefInput, r
 import { getSubscriptionProviderConfig, listAvailableSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config';
 import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibes-sdk/platform/config';
 import { inspectProviderAuth } from '@/runtime/index.ts';
-import { getOrCreateCompanionToken, buildCompanionConnectionInfo, encodeConnectionPayload, formatConnectionBlock } from '@pellux/goodvibes-sdk/platform/pairing';
-import { generateQrMatrix, renderQrToString } from '@pellux/goodvibes-sdk/platform/pairing';
 import type { CliCommandRuntime, GoodVibesCliParseResult } from './types.ts';
 import { formatProviderAuthRoute, summarizeProviderAuthRoutes } from './provider-auth-routes.ts';
 import { classifyProviderSetup } from './provider-classification.ts';

package/src/core/consolidation-receipt.ts

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// consolidation-receipt.ts — the one-line notice for an idle-time memory
+// consolidation run.
+//
+// The SDK's MemoryConsolidationScheduler runs at idle and produces a
+// MemoryConsolidationRunReceipt (merged / archived / decayed / proposed). This
+// formats it into the same one-line shape every other attach-time receipt
+// uses, so a run that changed something surfaces on the next attach like a
+// crash/update/migration receipt. A pure no-op run yields null — no noise.
+//
+// A run that PROPOSED something (a contradiction or cross-scope-duplicate
+// awaiting human judgment — never auto-applied) names where to actually look:
+// the Memory modal's Proposals tab (`/memory`, then the Proposals tab —
+// memory-modal.ts's proposalsTab()), which lists each proposal's kind,
+// reason, and affected record ids and jumps to them in the Review Queue.
+// Without this pointer the receipt line was the only trace a proposal ever
+// existed — a count with nowhere to go.
+// ---------------------------------------------------------------------------
+
+import type { MemoryConsolidationRunReceipt } from '@pellux/goodvibes-sdk/platform/state';
+
+/**
+ * A one-line receipt for a consolidation run that changed something, or null
+ * when the run merged/archived/decayed/proposed nothing (a quiet idle pass —
+ * no notice, matching the check-in "stayed quiet" discipline).
+ */
+export function formatConsolidationReceipt(receipt: MemoryConsolidationRunReceipt): string | null {
+  const merged = receipt.merged.length;
+  const archived = receipt.archived.length;
+  const decayed = receipt.decayed.length;
+  const proposed = receipt.proposed.length;
+  if (merged + archived + decayed + proposed === 0) return null;
+  const parts: string[] = [];
+  if (merged) parts.push(`${merged} merged`);
+  if (archived) parts.push(`${archived} archived`);
+  if (decayed) parts.push(`${decayed} decayed`);
+  if (proposed) parts.push(`${proposed} proposed`);
+  const base = `Memory consolidation: ${parts.join(', ')} (scanned ${receipt.scanned}).`;
+  if (proposed === 0) return base;
+  return `${base} Review the ${proposed} proposed change${proposed === 1 ? '' : 's'} with /memory (Proposals tab).`;
+}

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-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/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;
+}