@pellux/goodvibes-tui 1.16.1 → 1.18.0

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

package/src/core/pairing-tailscale-gateway.ts

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// pairing-tailscale-gateway.ts
+//
+// The two tailscale verbs the pairing surfaces drive — a read-only detection
+// (tailscale.get) and the one-action serve (tailscale.serve.run) — over the
+// same generic operator invoke path the fleet acts use (resolveOperatorRpc ->
+// sdk.operator.invoke), reaching the SAME daemon the command layer does.
+//
+// Both thunks degrade QUIETLY: when no daemon is reachable, the probe resolves
+// to null (the pairing surface renders no tailscale affordance at all) rather
+// than throwing into a render path. Absence is never a nag.
+// ---------------------------------------------------------------------------
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { resolveOperatorRpc } from '../input/commands/operator-rpc.ts';
+import type {
+  PairingTailscaleServeReceipt,
+  PairingTailscaleStatus,
+} from '../panels/modals/pairing-modal.ts';
+
+export interface PairingTailscaleGatewayDeps {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string | (() => string);
+}
+
+/**
+ * Probe tailscale (tailscale.get). Returns the honest status, or null when the
+ * daemon is unreachable / the call fails — the pairing surface then stays quiet.
+ */
+export async function probePairingTailscale(
+  deps: PairingTailscaleGatewayDeps,
+): Promise<PairingTailscaleStatus | null> {
+  const rpc = resolveOperatorRpc(deps);
+  if (!rpc.available) return null;
+  try {
+    return (await rpc.sdk.operator.invoke('tailscale.get', {})) as PairingTailscaleStatus;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run tailscale.serve.run and return its receipt. Null when the daemon is
+ * unreachable; a failed serve returns a receipt with `ok:false` and an honest
+ * detail (never a throw the surface has to guess about).
+ */
+export async function runPairingTailscaleServe(
+  deps: PairingTailscaleGatewayDeps,
+): Promise<PairingTailscaleServeReceipt | null> {
+  const rpc = resolveOperatorRpc(deps);
+  if (!rpc.available) return null;
+  const result = (await rpc.sdk.operator.invoke('tailscale.serve.run', {})) as {
+    readonly receipt: PairingTailscaleServeReceipt;
+  };
+  return result.receipt;
+}

package/src/core/power-chip-source.ts

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// power-chip-source.ts — the topology-aware source of truth behind the
+// always-visible "sleep disabled" chip.
+//
+// Embedded topology: the in-process PowerManager IS the daemon's, so reading
+// getState() per render is already the whole truth; the local runtime bus's
+// OPS_POWER_STATE_CHANGED just triggers an immediate repaint so a
+// webui-originated toggle (which lands on the same in-process manager) lights
+// the chip without waiting for the next natural render.
+//
+// External/adopted topology: the local manager is NOT the daemon's, and the
+// adopted-daemon wire is plain HTTP (no realtime event bridge), so the chip
+// POLLS power.status.get on an unref'd interval and renders the DAEMON's
+// state — a webui-originated toggle on the daemon lights the TUI chip within
+// one poll, and a TUI toggle (forwarded over power.keepAwake.set by
+// power-keepawake-remote.ts) lights the webui's the same way. While the
+// daemon's state is unknown (fetch pending/unreachable) the local projection
+// is served rather than a fabricated one.
+// ---------------------------------------------------------------------------
+
+import type { PowerState } from '@pellux/goodvibes-sdk/platform/power';
+import { IDLE_POWER_STATE, powerSurfaceFromEvent, powerSurfaceFromState, type PowerStateChangedPayload, type PowerSurfaceState } from './power-status.ts';
+
+export interface PowerChipSourceDeps {
+  /** The in-process manager (the whole truth in embedded topology). */
+  readonly powerManager: { getState(): PowerState };
+  /** Subscribe to the LOCAL bus's OPS_POWER_STATE_CHANGED envelopes; returns unsubscribe. */
+  readonly onPowerEvent: (cb: (payload: PowerStateChangedPayload) => void) => () => void;
+  /** True only in the external/adopted-daemon topology. */
+  readonly isExternalDaemon: () => boolean;
+  /** Fetch the DAEMON's power.status.get (null when unreachable). */
+  readonly fetchDaemonPowerState: () => Promise<PowerState | null>;
+  /** Repaint request when the chip's source state changes. */
+  readonly render: () => void;
+  /** External-topology poll cadence (default 5000ms; unref'd). */
+  readonly pollIntervalMs?: number | undefined;
+  readonly timers?: { setInterval: typeof setInterval; clearInterval: typeof clearInterval } | undefined;
+}
+
+export interface PowerChipSource {
+  /** The current chip projection — daemon-synced in external topology, local otherwise. */
+  get(): PowerSurfaceState;
+  /** Stop the poll + event subscription. */
+  stop(): void;
+}
+
+export function createPowerChipSource(deps: PowerChipSourceDeps): PowerChipSource {
+  const timers = deps.timers ?? { setInterval, clearInterval };
+  let daemonState: PowerSurfaceState | null = null;
+  let lastLocal: PowerSurfaceState = IDLE_POWER_STATE;
+  let polling = false;
+
+  // Local bus events: immediate repaint (embedded truth changes live).
+  const unsubscribe = deps.onPowerEvent((payload) => {
+    lastLocal = powerSurfaceFromEvent(payload);
+    deps.render();
+  });
+
+  const poll = async (): Promise<void> => {
+    if (!deps.isExternalDaemon()) {
+      if (daemonState !== null) { daemonState = null; deps.render(); }
+      return;
+    }
+    if (polling) return;
+    polling = true;
+    try {
+      const state = await deps.fetchDaemonPowerState();
+      const next = state ? powerSurfaceFromState(state) : null;
+      const changed = JSON.stringify(next) !== JSON.stringify(daemonState);
+      daemonState = next;
+      if (changed) deps.render();
+    } finally {
+      polling = false;
+    }
+  };
+  const interval = timers.setInterval(() => { void poll(); }, deps.pollIntervalMs ?? 5000);
+  (interval as { unref?: () => void }).unref?.();
+  void poll(); // initial sync so an adopted daemon's held keep-awake shows immediately
+
+  return {
+    get(): PowerSurfaceState {
+      if (deps.isExternalDaemon() && daemonState !== null) return daemonState;
+      // Local truth: prefer a live event projection when one arrived, else read the manager.
+      try { return powerSurfaceFromState(deps.powerManager.getState()); } catch { return lastLocal; }
+    },
+    stop(): void {
+      unsubscribe();
+      timers.clearInterval(interval);
+    },
+  };
+}

package/src/core/power-status.ts

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// power-status.ts — the surface-facing view of host sleep ownership (power.*).
+//
+// The SDK's PowerManager owns the policy: a keep-awake toggle (daemon-held,
+// persisted), automatic work-signal inhibition ("held because X"), and the
+// honest lid-split note when idle-sleep can be blocked but lid-close suspend
+// can't. This module is the read-only projection every surface renders from —
+// the always-visible "sleep disabled" chip, and the ops/status detail lines —
+// seeded from powerManager.getState() and kept live by OPS_POWER_STATE_CHANGED.
+//
+// Owner ruling: the chip IS the safety mechanism. No timers, no AC-only
+// options — the keep-awake toggle is exactly one boolean.
+// ---------------------------------------------------------------------------
+
+import { LID_SWITCH_HONEST_SPLIT, type PowerState } from '@pellux/goodvibes-sdk/platform/power';
+
+/** The always-visible chip text shown while keep-awake holds (danger-mode idiom). */
+export const SLEEP_DISABLED_CHIP = 'sleep disabled';
+
+/** The flattened power state a surface renders from. */
+export interface PowerSurfaceState {
+  /** The owner keep-awake toggle — the "sleep disabled" chip source. */
+  readonly keepAwake: boolean;
+  /** True while any sleep inhibitor (work or keep-awake) is held. */
+  readonly inhibited: boolean;
+  /** Live reasons the WORK inhibitor is held ("held because X"). */
+  readonly workReasons: readonly string[];
+  /** The honest-split note when part of the requested coverage was refused (verbatim). */
+  readonly note: string | null;
+}
+
+/** The neutral state (no inhibition, nothing held) — the pre-event seed default. */
+export const IDLE_POWER_STATE: PowerSurfaceState = {
+  keepAwake: false,
+  inhibited: false,
+  workReasons: [],
+  note: null,
+};
+
+/** Flatten the full PowerState (power.status.get) into the surface projection. */
+export function powerSurfaceFromState(state: PowerState): PowerSurfaceState {
+  return {
+    keepAwake: state.keepAwake.enabled,
+    inhibited: state.keepAwake.held || state.work.held,
+    workReasons: state.work.reasons,
+    note: state.keepAwake.note,
+  };
+}
+
+/** The OPS_POWER_STATE_CHANGED payload shape the surface consumes. */
+export interface PowerStateChangedPayload {
+  readonly inhibited: boolean;
+  readonly keepAwake: boolean;
+  readonly workReasons: readonly string[];
+  readonly note?: string | undefined;
+}
+
+/** Flatten an OPS_POWER_STATE_CHANGED event payload into the surface projection. */
+export function powerSurfaceFromEvent(ev: PowerStateChangedPayload): PowerSurfaceState {
+  return {
+    keepAwake: ev.keepAwake,
+    inhibited: ev.inhibited,
+    workReasons: ev.workReasons,
+    note: ev.note ?? null,
+  };
+}
+
+/**
+ * The ops/status detail lines — the honest, plain-language account of sleep
+ * ownership. Order: the chip's meaning, then each "held because X" work reason,
+ * then the lid-split note VERBATIM when the SDK served it. Empty when nothing
+ * is held and no note applies.
+ */
+export function powerStatusLines(state: PowerSurfaceState): string[] {
+  const lines: string[] = [];
+  if (state.keepAwake) {
+    lines.push(`${SLEEP_DISABLED_CHIP} — keep-awake is on (this host will not idle-sleep)`);
+  }
+  for (const reason of state.workReasons) {
+    lines.push(`held because ${reason}`);
+  }
+  if (state.note) {
+    // The SDK's honest lid-split line, rendered exactly as served.
+    lines.push(state.note);
+  }
+  if (lines.length === 0) {
+    lines.push('sleep is not being held; the host sleeps on its own schedule');
+  }
+  return lines;
+}
+
+/** True when the SDK served the honest lid-split note (idle blocked, lid-close is the OS's). */
+export function hasLidSplitNote(state: PowerSurfaceState): boolean {
+  return state.note === LID_SWITCH_HONEST_SPLIT;
+}