@pellux/goodvibes-tui 1.16.1 → 1.18.0

package/src/daemon/cli.ts

@@ -1,25 +1,26 @@
-import { homedir, networkInterfaces } from 'node:os';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { readFileSync } from 'node:fs';
 import { ConfigManager, resolveDaemonEnabled } from '@pellux/goodvibes-sdk/platform/config';
 import { formatProviderModel, getModelIdFromProviderModel, getProviderIdFromModel } from '../config/provider-model.ts';
 import { RuntimeEventBus, GlobalNetworkTransportInstaller } from '@/runtime/index.ts';
-import { createFeatureFlagManager } from '@/runtime/index.ts';
-import type { FlagState } from '@/runtime/index.ts';
+import { bindFeatureSettingsBridge, createFeatureFlagManager, deriveFeatureStates } from '@/runtime/index.ts';
 import { createRuntimeStore } from '../runtime/store/index.ts';
 import { createRuntimeServices } from '../runtime/services.ts';
 import { DaemonServer, HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
+import { createHostPowerSeam } from '@pellux/goodvibes-sdk/platform/power';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import {
   getOrCreateCompanionToken,
   pruneStaleOperatorTokens,
-  buildCompanionConnectionInfo,
-  encodeConnectionPayload,
-  formatConnectionBlock,
+  buildPairingHandoffLink,
+  describeOriginPosture,
   generateQrMatrix,
   renderQrToString,
 } from '@pellux/goodvibes-sdk/platform/pairing';
+import { ensurePublicBaseUrl } from '../core/pairing-origin.ts';
+import { availablePairingOffers } from '../core/pairing-handoff.ts';
+import { formatPairingOffers, formatPostureCapabilities, pairingPostureNotice } from '../core/pairing-offers.ts';
 import { workspaceOperatorTokenCandidates } from '../runtime/operator-token-cleanup.ts';
 import {
   scan,
@@ -28,6 +29,8 @@ import {
 } from '@pellux/goodvibes-sdk/platform/discovery';
 import { createSafeHostServeFactory } from './safe-serve.ts';
 import { isDaemonServiceSubcommand, resolveInstalledDaemonBinary, runDaemonServiceCli } from './service-commands.ts';
+import { resolveDaemonUpdateArtifact } from './lifecycle.ts';
+import { VERSION } from '../version.ts';
 
 import {
   parseGoodVibesCli,
@@ -50,36 +53,6 @@ type DaemonCliTokens = {
   readonly httpToken: string | undefined;
 };
 
-function getLocalNetworkIp(): string {
-  try {
-    const nets = networkInterfaces();
-    for (const name of Object.keys(nets)) {
-      for (const net of nets[name] ?? []) {
-        if (net.family === 'IPv4' && !net.internal) {
-          return net.address;
-        }
-      }
-    }
-  } catch {
-    return 'localhost';
-  }
-  return 'localhost';
-}
-
-function readBootstrapPassword(credentialPath: string): string | undefined {
-  try {
-    const content = readFileSync(credentialPath, 'utf-8');
-    for (const line of content.split('\n')) {
-      if (line.startsWith('password=')) {
-        return line.slice('password='.length).trim();
-      }
-    }
-  } catch {
-    // credential file may not exist yet
-  }
-  return undefined;
-}
-
 function resolveDaemonCliOwnership(): DaemonCliOwnership {
   return {
     workingDirectory: process.env['GOODVIBES_WORKING_DIR'] ?? process.cwd(),
@@ -190,10 +163,11 @@ async function main(): Promise<void> {
 
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
+  // Gate states derive from the domain settings keys; the bridge keeps live
+  // config changes flowing into the manager for the daemon's lifetime.
   const featureFlags = createFeatureFlagManager();
-  featureFlags.loadFromConfig({
-    flags: (config.getCategory('featureFlags') as Record<string, FlagState>) ?? {},
-  });
+  featureFlags.loadFromConfig({ flags: deriveFeatureStates(config) });
+  bindFeatureSettingsBridge(config, featureFlags);
   const runtimeServices = createRuntimeServices({
     configManager: config,
     featureFlags,
@@ -202,6 +176,17 @@ async function main(): Promise<void> {
     getConversationTitle: () => 'goodvibes daemon',
     workingDir,
     homeDirectory,
+    // The standalone daemon observes externally-launched coding-agent sessions
+    // on the host read-only (fleet visibility + steer; never counted, never
+    // stopped). Daemon-side only — the interactive process reads this snapshot
+    // rather than double-detecting. Mirrors the SDK daemon cli.
+    observeExternalAgents: true,
+    // Opt into the REAL host power seam (Linux logind: systemd-inhibit children
+    // + the dbus-monitor sleep-edge watcher) so the standalone daemon holds live
+    // keep-awake/idle-inhibit. SDK 1.9.0's runtime-services factory defaults to
+    // the non-spawning unavailable seam; only daemon compositions opt in. Mirrors
+    // the SDK daemon cli's createHostPowerSeam() (sdk commit 3a5ea26d).
+    powerSeam: createHostPowerSeam(),
   });
 
   // Load persisted providers from disk so the provider registry is pre-populated
@@ -233,6 +218,11 @@ async function main(): Promise<void> {
     userAuth,
     runtimeServices,
     serveFactory: createSafeHostServeFactory('Standalone daemon'),
+    // Hand the facade this binary's real version + exec path so its self-update
+    // lifecycle compares the HOST's version (not the sdk package's). Resolves to
+    // undefined for a non-binary install, so a dev run stays host-managed and
+    // never swaps the interpreter. See lifecycle.ts.
+    updateArtifact: resolveDaemonUpdateArtifact({ version: VERSION }),
   });
   const listener = new HttpListener({
     hookDispatcher: runtimeServices.hookDispatcher,
@@ -268,6 +258,11 @@ async function main(): Promise<void> {
     config.get('danger.httpListener') ? listener.start() : Promise.resolve(),
   ]);
 
+  // The DaemonServer facade owns the hourly self-update loop now (fed this
+  // binary's version + exec path via updateArtifact above); it checks hourly,
+  // swaps only at an idle moment, keeps the outgoing binary at `<path>.previous`,
+  // and stops with the daemon. No separate host loop.
+
   const abortController = new AbortController();
 
   const shutdown = async (): Promise<void> => {
@@ -300,26 +295,37 @@ async function main(): Promise<void> {
     httpListener: config.get('danger.httpListener'),
   });
 
-  // Print companion connection info + QR code to stdout.
-  // Use the config-driven control plane port, not a hardcoded default.
-  const daemonPort = config.get('controlPlane.port');
-  const configuredDaemonHost = String(process.env.GOODVIBES_DAEMON_HOST ?? getLocalNetworkIp());
-  const daemonHost = configuredDaemonHost === '0.0.0.0' || configuredDaemonHost === '::'
-    ? getLocalNetworkIp()
-    : configuredDaemonHost;
-  const daemonUrl = `http://${daemonHost}:${daemonPort}`;
-  const bootstrapPassword = readBootstrapPassword(userAuth.getBootstrapCredentialPath());
-  const connectionInfo = buildCompanionConnectionInfo({
-    daemonUrl,
-    token: companionTokenRecord.token,
-    password: bootstrapPassword,
-    surface: 'tui',
+  // Print a device-pairing QR to stdout. The QR encodes the canonical
+  // `#pair=<token>` deep link the web app consumes — a camera scan opens it
+  // already signed in. No raw JSON connection blob is printed. This is also the
+  // one place web.publicBaseUrl is frozen from the stable-name resolution (never
+  // clobbering a user-set value), so the printed origin survives a DHCP change.
+  // The daemon's shared companion token rides as the pairing token; a device can
+  // later migrate to its own per-device token from /settings → security → devices.
+  const webOrigin = ensurePublicBaseUrl(config);
+  const offers = availablePairingOffers({
+    relayEnabled: config.get('relay.enabled') === true,
+    stepUpAvailable: true,
   });
-  const payload = encodeConnectionPayload(connectionInfo);
-  const qrMatrix = generateQrMatrix(payload);
-  const qrString = renderQrToString(qrMatrix);
+  const deepLink = buildPairingHandoffLink({ webOrigin: webOrigin.origin, token: companionTokenRecord.token, offers });
+  const qrString = renderQrToString(generateQrMatrix(deepLink));
+  // The banner renders the SAME SDK posture the pairing verb carries: the labeled
+  // capability list, and the one honest LAN line only when the posture holds it.
+  const posture = describeOriginPosture(webOrigin.origin);
+  const capabilities = formatPostureCapabilities(posture);
+  const notice = pairingPostureNotice(posture);
+  const bannerLines = [
+    `GoodVibes daemon ${VERSION} — scan to pair a device (opens the web app signed in):`,
+    '',
+    `  ${webOrigin.origin}`,
+    '',
+    ...(offers.length > 0 ? ['Offers (each declinable in the web app):', ...formatPairingOffers(offers), ''] : []),
+    ...(capabilities.length > 0 ? ['This device will get:', ...capabilities, ''] : []),
+    ...(notice ? [notice, ''] : []),
+    qrString,
+  ];
   // eslint-disable-next-line no-console
-  console.log(formatConnectionBlock(connectionInfo, qrString));
+  console.log(bannerLines.join('\n'));
 }
 
 void main().catch(async (error) => {

package/src/daemon/lifecycle.ts

@@ -0,0 +1,41 @@
+/**
+ * lifecycle.ts — resolve THIS binary's update-artifact identity for the SDK
+ * DaemonServer facade's auto-update lifecycle.
+ *
+ * The SDK facade now runs the entire self-update loop itself when handed a
+ * DaemonUpdateArtifact ({version, execPath}): it compares the HOST binary's
+ * version against the release tags (no longer the version-blind sdk-package
+ * comparison that used to restart-loop), swaps only at an idle moment, keeps
+ * the outgoing file at `<path>.previous`, and leaves a receipt in the store it
+ * serves on /status. When the artifact is ABSENT, updates are host-managed —
+ * the facade runs no loop (the safe embedded default).
+ *
+ * The one guard the facade does NOT apply is install-kind: it must never swap a
+ * dev `bun run daemon` interpreter or a bun-global package install. This helper
+ * is that guard — it hands the facade an artifact ONLY for a compiled binary
+ * install, so a dev run resolves to `undefined` (host-managed, no loop) and
+ * only a real self-contained binary self-updates.
+ */
+import type { DaemonUpdateArtifact } from '@pellux/goodvibes-sdk/platform/daemon';
+import { VERSION } from '../version.ts';
+import { detectInstallKind } from '../runtime/update-check.ts';
+
+export interface ResolveDaemonUpdateArtifactOptions {
+  /** The executable to identify; defaults to process.execPath. */
+  readonly execPath?: string;
+  /** Injectable so tests pin a fixture version — never the live build VERSION. */
+  readonly version?: string;
+}
+
+/**
+ * The update-artifact identity to hand the DaemonServer facade, or `undefined`
+ * for a non-binary install (dev/source or bun-global package) — in which case
+ * the facade keeps updates host-managed and runs no swap loop.
+ */
+export function resolveDaemonUpdateArtifact(
+  options: ResolveDaemonUpdateArtifactOptions = {},
+): DaemonUpdateArtifact | undefined {
+  const execPath = options.execPath ?? process.execPath;
+  if (detectInstallKind(execPath) !== 'binary') return undefined;
+  return { version: options.version ?? VERSION, execPath };
+}

package/src/daemon/service-commands.ts

@@ -290,7 +290,7 @@ export async function runDaemonServiceCli(input: DaemonServiceCliInput): Promise
           ok: false,
           exitCode: 1,
           lines: [
-            `service install refused: a service is already installed under the legacy name ${LEGACY_SERVICE_UNIT_NAME}.service.`,
+            `service install refused: a service is already installed as ${LEGACY_SERVICE_UNIT_NAME}.service (the unit name the goodvibes install script manages).`,
             legacyUnitNote(legacy, resolvedName),
             `Installing this tool's ${resolvedName}.service alongside it risks two daemons competing for the same port.`,
           ],
@@ -313,10 +313,10 @@ export async function runDaemonServiceCli(input: DaemonServiceCliInput): Promise
       if (uninstalled.actionError) return failed('uninstall', uninstalled);
       const extra: string[] = [];
       if (stopped.actionError) extra.push(`(it may not have been running: ${stopped.actionError})`);
-      // W3 Finding 4: this command only ever touches the TRACKED unit
-      // (whatever name/path actually resolved — not necessarily the
-      // SERVICE_NAME constant) above — say so explicitly when a legacy unit
-      // also exists, so its continued presence is never a silent surprise.
+      // This command only ever touches the TRACKED unit (whatever name/path
+      // actually resolved — not necessarily the SERVICE_NAME constant) above —
+      // say so explicitly when an install-script unit also exists, so its
+      // continued presence is never a silent surprise.
       if (legacy.present) extra.push(legacyUnitNote(legacy, resolveManagedUnitName(uninstalled)));
       return ok('uninstall', uninstalled, extra);
     }

package/src/export/cost-utils.ts

@@ -15,18 +15,30 @@
 //      honest "unpriced" state instead of a silent $0.
 // ---------------------------------------------------------------------------
 
-import type { CatalogModel } from '@pellux/goodvibes-sdk/platform/providers';
+import { computeUsageCostUsd, type CatalogModel, type ResolvedModelPricing } from '@pellux/goodvibes-sdk/platform/providers';
 
 export interface ModelPricing {
   input: number;
   output: number;
 }
 
+/**
+ * Where a resolved price came from, for the render-side source distinction:
+ * 'user' = the manual pricing.modelPrices entry ("your price"), 'provider' =
+ * served by the provider API, 'catalog' = the live model catalog (dated),
+ * 'fallback' = this module's small built-in safety net.
+ */
+export type PricingSourceKind = 'user' | 'provider' | 'catalog' | 'fallback';
+
 /** Result of a pricing lookup: the resolved (possibly zero) price, and whether it's real. */
 export interface PricingResult {
   pricing: ModelPricing;
-  /** False when no source (catalog or static fallback) recognized the model — the zero pricing is a placeholder, not a real price. */
+  /** False when no source recognized the model — the zero pricing is a placeholder, not a real price. */
   priced: boolean;
+  /** Which source priced the model (present only when priced). */
+  source?: PricingSourceKind;
+  /** ISO date (YYYY-MM-DD) of the catalog/provider snapshot the price came from, when known. */
+  asOf?: string;
 }
 
 // Hand-maintained safety net, used only when the live catalog has no source
@@ -61,7 +73,7 @@ const STATIC_FALLBACK_PRICING: Record<string, ModelPricing> = {
 
 // Module-level injection point. Kept as a bare singleton (not threaded through
 // call sites) because the 9 existing consumers are pure functions with no
-// ProviderRegistry in scope; see WO-315 brief for the tradeoff. Tests that
+// ProviderRegistry in scope; see brief for the tradeoff. Tests that
 // never call setPricingSource() fall through to the static-fallback path,
 // which keeps them isolated from catalog state by default.
 let pricingSource: (() => readonly CatalogModel[]) | null = null;
@@ -71,6 +83,34 @@ export function setPricingSource(source: (() => readonly CatalogModel[]) | null)
   pricingSource = source;
 }
 
+// The ONE model pricing resolver (manual pricing.modelPrices -> registration
+// -> provider-served -> catalog -> honest unknown), wired from
+// bootstrap-core.ts as ProviderRegistry.resolveModelPricing once the runtime
+// exists. When set, it is consulted FIRST so a manual price the user sets is
+// visible to every cost surface immediately; the legacy catalog/static chain
+// below remains the fallback for resolver-unknown models and for surfaces
+// (tests, headless) that never wire a registry.
+let modelPricingResolver: ((modelId: string) => ResolvedModelPricing) | null = null;
+
+/** Wire (or clear, with null) the registry's resolveModelPricing as the primary pricing source. */
+export function setModelPricingResolver(resolver: ((modelId: string) => ResolvedModelPricing) | null): void {
+  modelPricingResolver = resolver;
+}
+
+/**
+ * One-call bootstrap wiring: the live catalog as the legacy source AND the
+ * registry's ONE pricing resolver (manual pricing.modelPrices -> registration
+ * -> provider-served -> catalog -> honest unknown) as the primary, so every
+ * cost surface sees a manually-set price immediately and can name its source.
+ */
+export function wireCostPricing(registry: {
+  getRawCatalogModels(): readonly CatalogModel[];
+  resolveModelPricing(modelRef: string): ResolvedModelPricing;
+}): void {
+  setPricingSource(() => registry.getRawCatalogModels());
+  setModelPricingResolver((modelId) => registry.resolveModelPricing(modelId));
+}
+
 function findInCatalog(modelId: string, models: readonly CatalogModel[]): ModelPricing | null {
   const exact = models.find((m) => m.id === modelId);
   if (exact) return exact.tier === 'free' ? { input: 0, output: 0 } : exact.pricing;
@@ -97,20 +137,60 @@ function findInStaticFallback(modelId: string): ModelPricing | null {
  * header for the full resolution order.
  */
 export function resolvePricing(modelId: string): PricingResult {
-  if (modelId.endsWith(':free')) return { pricing: { input: 0, output: 0 }, priced: true };
+  if (modelId.endsWith(':free')) return { pricing: { input: 0, output: 0 }, priced: true, source: 'catalog' };
+
+  // The ONE resolver first: manual price -> registration -> provider-served
+  // -> catalog. A 'priced' answer carries its source (and snapshot date when
+  // known) so render surfaces can say "your price" vs "catalog price, as of
+  // <date>". Unknown/subscription answers fall through to the legacy chain
+  // so nothing regresses while the catalog is still loading.
+  if (modelPricingResolver) {
+    const resolved = modelPricingResolver(modelId);
+    if (resolved.status === 'priced') {
+      return {
+        pricing: { input: resolved.rates.inputPerMTok, output: resolved.rates.outputPerMTok },
+        priced: true,
+        source: resolved.source,
+        ...(resolved.asOf ? { asOf: resolved.asOf } : {}),
+      };
+    }
+  }
 
   const models = pricingSource?.() ?? [];
   const catalogHit = findInCatalog(modelId, models);
-  if (catalogHit) return { pricing: catalogHit, priced: true };
+  if (catalogHit) return { pricing: catalogHit, priced: true, source: 'catalog' };
 
   const fallbackHit = findInStaticFallback(modelId);
-  if (fallbackHit) return { pricing: fallbackHit, priced: true };
+  if (fallbackHit) return { pricing: fallbackHit, priced: true, source: 'fallback' };
 
   // Genuinely unknown — no source recognizes this model. Report honestly
   // rather than collapsing into the same zero a free model would return.
   return { pricing: { input: 0, output: 0 }, priced: false };
 }
 
+/**
+ * The render-side source distinction for a priced model: "your price" for a
+ * manual pricing.modelPrices entry, "catalog price, as of <date>" (or
+ * provider-served/built-in equivalents) otherwise. Null when the model is
+ * unpriced — callers render the explicit "price unknown" marker instead.
+ */
+export function describePricingSource(modelId: string): string | null {
+  const result = resolvePricing(modelId);
+  if (!result.priced) return null;
+  switch (result.source) {
+    case 'user':
+      return 'your price';
+    case 'provider':
+      return result.asOf ? `provider price, as of ${result.asOf}` : 'provider price';
+    case 'catalog':
+      return result.asOf ? `catalog price, as of ${result.asOf}` : 'catalog price';
+    case 'fallback':
+      return 'built-in price';
+    default:
+      return 'catalog price';
+  }
+}
+
 /**
  * getPricing — resolve USD-per-1M-token pricing for a model ID.
  * Back-compat wrapper over resolvePricing(); returns zero for both genuinely
@@ -146,6 +226,20 @@ export function calcSessionCost(
   cacheWrite: number,
   modelId: string,
 ): number {
+  // Through the ONE resolver when wired: computeUsageCostUsd applies the
+  // source's explicit cache rates (or the published per-provider ratio)
+  // instead of billing cache traffic at the full input rate.
+  if (modelPricingResolver) {
+    const resolved = modelPricingResolver(modelId);
+    if (resolved.status === 'priced') {
+      return computeUsageCostUsd(resolved, {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+      }) ?? 0;
+    }
+  }
   const pricing = getPricing(modelId);
   // Cache reads/writes count toward billable input side (same convention as panel)
   const billableInput = inputTokens + cacheRead + cacheWrite;
@@ -195,3 +289,31 @@ export function readBudgetAlertUsd(configGet: (key: string) => unknown): number
   const parsed = typeof raw === 'number' ? raw : Number(raw);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : BUDGET_ALERT_USD_DEFAULT;
 }
+
+/**
+ * The SDK settings key holding the user's manual per-model prices — the
+ * highest-precedence source in the ONE pricing resolver. Object map of
+ * `provider:model` -> { input, output, cacheRead?, cacheWrite? } in USD per
+ * 1M tokens.
+ */
+export const MODEL_PRICES_CONFIG_KEY = 'pricing.modelPrices';
+
+/**
+ * Persist a manual price for one `provider:model` key into
+ * pricing.modelPrices, preserving every other entry. The registry's resolver
+ * reads the key live per call, so the new price is visible to every cost
+ * surface on the next render — no restart.
+ */
+export function writeManualModelPrice(
+  config: BudgetAlertConfigAccess,
+  modelKey: string,
+  price: { input: number; output: number },
+): void {
+  const current = config.get(MODEL_PRICES_CONFIG_KEY);
+  const map: Record<string, unknown> =
+    current && typeof current === 'object' && !Array.isArray(current)
+      ? { ...(current as Record<string, unknown>) }
+      : {};
+  map[modelKey] = { input: price.input, output: price.output };
+  config.set(MODEL_PRICES_CONFIG_KEY, map);
+}

package/src/input/autocomplete.ts

@@ -19,7 +19,7 @@ export interface AutocompleteState {
   results: AutocompleteResult[];
   selectedIndex: number;
   /**
-   * UX-C (item 4): how many leading entries of `results` belong to the
+   * (item 4): how many leading entries of `results` belong to the
    * curated "common" tier — only meaningful when `query === ''` (0
    * otherwise, since a typed filter searches everything and the common/rest
    * split no longer applies). The renderer uses this to draw a separator
@@ -56,7 +56,7 @@ export class AutocompleteEngine {
     this.state.query = query;
     this.state.results = this.registry.fuzzyMatch(query);
     this.state.active = true;
-    // UX-C: fuzzyMatch('') sorts the curated common tier first (score 2),
+    // fuzzyMatch('') sorts the curated common tier first (score 2),
     // then the alphabetical rest (score 1) — both tiers alphabetical within
     // themselves. Count the leading common run to tell the renderer where to
     // draw the separator. A non-empty query means every command was scored on

package/src/input/command-registry.ts

@@ -56,7 +56,7 @@ export interface CommandRuntimeState {
    * Cumulative count of direct terminal writes the output guard intercepted
    * this session — surfaced by /debug. Optional so the SDK's MutableRuntimeState
    * (which has no such field) stays assignable; the guard sets it lazily on the
-   * shared runtime object. (UX-B item 1a.)
+   * shared runtime object. (item 1a.)
    */
   terminalWritesIntercepted?: number;
 }
@@ -81,7 +81,28 @@ export interface CommandUiActions {
     marker?: string;
   };
   executeCommand?: (name: string, args: string[]) => Promise<boolean>;
+  /** Arm the one-key jump to a spawned CI fix-session (the surface attaches on the jump key; the user never retypes an id). */
+  armFixSessionAttach?: (fixSessionId: string) => void;
   cancelGeneration?: () => void;
+  /**
+   * Cancel JUST the currently-running tool call (the live transcript row),
+   * leaving the turn to continue — the local-session equivalent of the
+   * sessions.toolCalls.cancel wire verb over the in-process orchestrator.
+   * Returns true when a running call was found and cancelled.
+   */
+  cancelToolCall?: () => boolean;
+  /** The still-undelivered mid-turn messages, in delivery order (the /queue editable list). */
+  listQueuedMessages?: () => ReadonlyArray<{ id: string; queuedAt: number; text: string }>;
+  /** Replace a still-queued message's text; false once delivered (immutable). */
+  editQueuedMessage?: (id: string, text: string) => boolean;
+  /** Remove a still-queued message before delivery; false once delivered. */
+  deleteQueuedMessage?: (id: string) => boolean;
+  /** Toggle the drill-in of the "used N memories" provenance chip (memory.showProvenance). */
+  toggleMemoryProvenance?: () => void;
+  /** The current host sleep-ownership projection (power.status.get, flattened) — chip, held-because, lid-split. */
+  getPowerState?: () => import('../core/power-status.ts').PowerSurfaceState;
+  /** Set the daemon-held keep-awake toggle (power.keepAwake.set), acquiring/releasing the inhibitor live; returns the new state. */
+  setKeepAwake?: (enabled: boolean) => Promise<import('../core/power-status.ts').PowerSurfaceState>;
   /** True while an LLM turn is actively streaming. Used to give Escape
    *  cancel-turn precedence over a focused panel's own escape handling. */
   isGenerating?: () => boolean;
@@ -139,7 +160,7 @@ export interface CommandShellUiOpeners {
   ) => void;
   openSettingsModal?: (target?: string) => void;
   /**
-   * Open a MIGRATE-TO-MODAL surface by name (W6.1 purge skeleton — WO-A/B
+   * Open a MIGRATE-TO-MODAL surface by name (purge skeleton — B
    * command runtimes call this instead of openCommandPanel once their panel
    * is converted to a ModalFactory config). Threaded from ui-openers.ts the
    * same way openSettingsModal is.
@@ -157,12 +178,21 @@ export interface CommandShellUiOpeners {
    */
   openCommandPalette?: () => void;
   /**
-   * Open (and optionally focus) a panel. UX-C focus rule: the command path is
+   * Command name -> reference-category label, from the same single source of
+   * truth as the generated command reference (categorizeBuiltinCommands),
+   * memoized by the shell. Lets registry-driven surfaces built inside command
+   * handlers (/help) group by category without importing the aggregation
+   * module — a static import there would cycle (commands.ts registers those
+   * very handlers).
+   */
+  getCommandCategories?: () => ReadonlyMap<string, string>;
+  /**
+   * Open (and optionally focus) a panel. focus rule: the command path is
    * "the user is mid-command-flow" — opening a panel this way leaves keyboard
    * focus in the composer by default. Pass `{ focus: true }` for a caller that
    * genuinely wants to grab focus (chords use panelManager.focusPanels()
    * directly instead of this method, so no current call site needs it — but
-   * the intent is explicit rather than implicit here). `target` (DEBT-5) is a
+   * the intent is explicit rather than implicit here). `target` is a
    * fleet deep-link jump target forwarded to PanelManager.open.
    */
   showPanel?: (panelId: string, pane?: 'top' | 'bottom', target?: PanelDeepLinkTarget, opts?: { focus?: boolean }) => void;
@@ -207,7 +237,7 @@ export interface CommandSessionServices {
    * conversation's current message history. Call after a session resume
    * replays historical messages, before the next render, so the footer's
    * token counter reflects the resumed session's real usage instead of a
-   * fresh Orchestrator's zeroed default (W0.9).
+   * fresh Orchestrator's zeroed default.
    */
   readonly hydrateSessionUsage?: () => void;
   /** The orchestration engine's command-facing facade — see runtime/workstream-services.ts. */
@@ -221,7 +251,7 @@ export interface CommandSessionServices {
   /**
    * The MAIN interactive session's per-turn passive-injection
    * honesty ring — `Orchestrator.getTurnInjections()`, the main-session
-   * counterpart to `AgentRecord.turnInjections` (wo801). `/recall injections`
+   * counterpart to `AgentRecord.turnInjections`. `/recall injections`
    * with no agent id reads this. Optional so command contexts built without an
    * orchestrator (headless, tests) fall back to the honest empty state.
    */
@@ -262,7 +292,9 @@ export interface CommandWorkspaceServices
 export interface CommandPlatformConfigServices {
   readonly config: DeepReadonly<GoodVibesConfig>;
   readonly configManager: ConfigManager;
-  /** Feature-flag runtime — backs the `/flags` command's listing and runtime toggling. */
+  /** Per-device pairing tokens — backs the /devices command family. */
+  readonly pairingTokens?: import('@pellux/goodvibes-sdk/platform/pairing').PairingTokenManager;
+  /** Capability gate runtime — feature states derive from domain settings keys; surfaces read live/pending state here. */
   readonly featureFlagManager?: FeatureFlagManager;
   readonly voiceProviderRegistry?: VoiceProviderRegistry;
   readonly voiceService?: VoiceService;
@@ -325,11 +357,18 @@ export interface CommandContext
     readonly mcpApi?: McpApi;
     readonly opsApi?: OpsApi;
     readonly transport?: DirectTransport;
+    /**
+     * Durable user-origin permission rules (the persistent form of remembered
+     * approvals). The same in-process store the permission evaluator reads, so
+     * /permissions rules lists and revokes rules that take effect live. Served
+     * by the daemon's permissions.rules.list/.delete verbs to other surfaces.
+     */
+    readonly userPermissionRuleStore?: import('@pellux/goodvibes-sdk/platform/permissions').UserPermissionRuleStore;
   };
 }
 
 /**
- * UX-C palette curation (item 4): the "common" first tier the slash-command
+ * palette curation (item 4): the "common" first tier the slash-command
  * autocomplete dropdown shows before the alphabetical rest when it opens with
  * no filter typed yet (bare '/') — the "132-command palette unranked"
  * evaluator finding. Typed filtering (any non-empty query) is completely
@@ -379,6 +418,13 @@ export class CommandRegistry {
    * statically by the alias lint test).
    */
   register(command: SlashCommand): void {
+    // Every registered command is rendered with its description in /help, the
+    // command palette, and the generated reference (docs/commands-reference.md).
+    // A blank description would ship an unexplained row in all three, so it
+    // fails fast here — the release gate red-tests this invariant.
+    if (!command.description || command.description.trim().length === 0) {
+      throw new Error(`Command registration for "${command.name}" has no description — every command must describe itself.`);
+    }
     const existingByName = this.commands.get(command.name) ?? this.aliasIndex.get(command.name);
     if (existingByName) {
       throw new Error(
@@ -447,7 +493,7 @@ export class CommandRegistry {
       }
 
       if (bestScore > 0 || q === '') {
-        // UX-C: with no query yet, rank the curated common tier (score 2)
+        // with no query yet, rank the curated common tier (score 2)
         // ahead of everything else (score 1) — the tie-break below then sorts
         // each tier alphabetically, so the result is "common tier, then the
         // alphabetical rest" rather than one flat alphabetical list.