@pellux/goodvibes-tui 1.1.0 → 1.9.0

package/src/daemon/service-commands.ts

@@ -0,0 +1,329 @@
+/**
+ * D7a Layer 1 (TUI wiring) — `goodvibes-daemon install-service | uninstall-service
+ * | service-status`.
+ *
+ * The daemon is a SYSTEM SERVICE. These subcommands install it as a durable host
+ * service (systemd user unit on Linux, launchd agent on macOS, a Scheduled Task
+ * on Windows) so N surfaces share ONE daemon that survives reboots, instead of
+ * every surface spawning a session-scoped daemon.
+ *
+ * W3 drift note: the SDK's D7a-era `systemd-user-service.ts` (a Linux-only,
+ * bespoke systemd shim) was dead code and got deleted in SDK W3-S5. The SDK's
+ * REAL wired service machinery — reached in production by the daemon's own HTTP
+ * `/api/service/*` routes via facade-composition.ts — is
+ * `PlatformServiceManager` (`@pellux/goodvibes-sdk/platform/daemon`): a single
+ * systemd/launchd/windows-aware manager with install/uninstall/status/start/
+ * stop/restart and a `suggestedCommands` hint list. This module now rewires the
+ * three CLI subcommands onto that manager instead of the deleted shim.
+ *
+ * Two real behavioral differences from the old shim, called out honestly:
+ *   - `install()` only WRITES the unit/plist/task; it does not enable/start it.
+ *     So `install-service` here calls `install()` then `start()` to preserve the
+ *     old "install implies enabled + running" behavior.
+ *   - `uninstall()` only REMOVES the unit file; there is no manager-level
+ *     `disable` verb (only start/stop/restart exist). So `uninstall-service`
+ *     calls `stop()` then `uninstall()`, and honestly tells the caller that a
+ *     stray "enabled" symlink may remain until `systemctl --user daemon-reload`
+ *     (offered back as a suggested follow-up) or the next login cleans it up.
+ *
+ * W4-D1: a fourth subcommand, `migrate-service`, closes the Wave-3 "detect and
+ * disclose only" inheritance (W3 Finding 4, below) with a GUIDED, CONSENTED
+ * takeover of the legacy `goodvibes-daemon.service` unit. Design constraints,
+ * all load-bearing:
+ *   - NEVER auto-migrate. Without explicit consent (`confirmMigration`, wired
+ *     from the CLI's existing `-y`/`--yes` flag) this prints the exact plan
+ *     and touches nothing.
+ *   - NEW-UP-THEN-OLD-DOWN. The new `goodvibes.service` unit is installed,
+ *     started, and verified healthy (a fresh `status().running` read, which
+ *     honestly queries systemd via the injected actionRunner) BEFORE the
+ *     legacy unit is stopped, disabled, or removed. A failed or unhealthy new
+ *     unit rolls itself back (uninstalled) and never touches the legacy one
+ *     — a botched takeover must never cost the user their working daemon.
+ *   - ADOPT-OR-WARN, NEVER KILL. If the legacy unit file is simply absent but
+ *     something is already listening on the configured host:port (Mike's real
+ *     dev-host case: a manual `nohup`'d daemon with no unit at all), this is
+ *     an unidentified process, not a managed unit — there is nothing to stop
+ *     or disable, and this module will not attempt to kill it. It warns and
+ *     leaves the decision to the operator.
+ *   - Every action (legacy stop/disable, unit-file removal, daemon-reload)
+ *     goes through the SAME injectable `actionRunner`/`legacyUnitFileRemove`
+ *     seams tests already use — this module never has a code path that bypasses
+ *     them, so the migration is exercised deterministically via fakes and never
+ *     touches a real running service in tests.
+ */
+
+import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { PlatformServiceManager, type ManagedServiceStatus } from '@pellux/goodvibes-sdk/platform/daemon';
+import {
+  buildManagedDaemonServiceManager,
+  detectLegacyUnit,
+  legacyUnitNote,
+  resolveManagedUnitName,
+  runLegacyDaemonMigration,
+  LEGACY_SERVICE_UNIT_NAME,
+  MANAGED_SERVICE_NAME as SERVICE_NAME,
+  MANAGED_SERVICE_DESCRIPTION as SERVICE_DESCRIPTION,
+  type LegacyUnitInfo,
+  type ManagedServiceActionRunner,
+} from '../runtime/legacy-daemon-migration.ts';
+
+// `resolveInstalledDaemonBinary` lives in the runtime module (shared with the
+// onboarding guided UX) — re-exported here so this module stays the CLI's
+// stable public surface (and so existing test imports keep working).
+export {
+  resolveInstalledDaemonBinary,
+  type ResolveDaemonBinaryOptions,
+} from '../runtime/legacy-daemon-migration.ts';
+export type { ManagedServiceActionRunner } from '../runtime/legacy-daemon-migration.ts';
+
+// ---------------------------------------------------------------------------
+// W3 Finding 4: legacy-unit detection. W4-D1: guided migration.
+//
+// The prior D7a-era command installed the daemon's systemd unit under the
+// literal name `goodvibes-daemon.service`. This module (rewired onto
+// PlatformServiceManager, see the file banner above) manages a DIFFERENT
+// unit name (`goodvibes`, SERVICE_NAME). A host that still has the legacy
+// unit installed — this dev machine included — would otherwise see
+// service-status honestly report installed:false/running:false for the
+// tracked name while the legacy unit keeps running untouched underneath it,
+// uninstall-service would silently leave the legacy unit orphaned with no
+// mention, and install-service could start a SECOND daemon competing for the
+// same port.
+//
+// The detection (`detectLegacyUnit`/`legacyUnitNote`) and the guided
+// migration engine (`runLegacyDaemonMigration`) both live in
+// `../runtime/legacy-daemon-migration.ts` rather than here, so the TUI's
+// onboarding UX (`src/input/handler-onboarding-daemon-adopt.ts`) can reuse
+// them directly — the architecture gate forbids `src/input/**` from
+// importing `src/daemon/**` (input must stay entrypoint-agnostic), so the
+// shared engine lives in the entrypoint-agnostic `runtime` layer instead and
+// this CLI module is just one of its two consumers.
+//
+// This detection is entirely independent of PlatformServiceManager's own
+// status() — it does not rely on (or get invalidated by) the parallel SDK
+// fix that makes status().running itself query systemd honestly for the
+// TRACKED unit name.
+// ---------------------------------------------------------------------------
+
+export type DaemonServiceSubcommand = 'install-service' | 'uninstall-service' | 'service-status' | 'migrate-service';
+
+export function isDaemonServiceSubcommand(value: string | undefined): value is DaemonServiceSubcommand {
+  return value === 'install-service' || value === 'uninstall-service' || value === 'service-status' || value === 'migrate-service';
+}
+
+export interface DaemonServiceCliInput {
+  readonly subcommand: DaemonServiceSubcommand;
+  readonly binaryPath: string;
+  readonly homeDir: string;
+  readonly host: string;
+  readonly port: number;
+  /** Defaults to `homeDir` — overridable so tests can scope both to one tempdir. */
+  readonly workingDirectory?: string | undefined;
+  /** Injected in tests; a real `ConfigManager` rooted at `homeDir` otherwise. */
+  readonly configManager?: ConfigManager | undefined;
+  /** Injectable systemctl/launchctl/schtasks runner so tests never touch the host. */
+  readonly actionRunner?: ManagedServiceActionRunner | undefined;
+  /** Injectable existsSync for the legacy-unit file check (W3 Finding 4) so tests never touch the host filesystem. */
+  readonly legacyUnitFileExists?: ((path: string) => boolean) | undefined;
+  /**
+   * `migrate-service` only: explicit consent to actually execute the
+   * migration (wired from the CLI's `-y`/`--yes` flag). Without it, the
+   * subcommand prints the exact plan and changes nothing — never auto-migrate.
+   */
+  readonly confirmMigration?: boolean | undefined;
+  /**
+   * `migrate-service` only: injectable port-liveness check for the
+   * legacy-absent branch (never a raw network call in tests). Defaults to a
+   * real, read-only TCP connect attempt.
+   */
+  readonly portProbe?: ((host: string, port: number) => boolean | Promise<boolean>) | undefined;
+  /**
+   * `migrate-service` only: injectable removal of the legacy unit file, so
+   * tests never call a raw fs op against a real path. Defaults to a real
+   * `rmSync`.
+   */
+  readonly legacyUnitFileRemove?: ((path: string) => void) | undefined;
+}
+
+export interface DaemonServiceCliResult {
+  readonly ok: boolean;
+  readonly exitCode: number;
+  /** Honest, human-readable stdout lines describing exactly what happened. */
+  readonly lines: readonly string[];
+  readonly status: ManagedServiceStatus;
+}
+
+/**
+ * The manager's definition (`ExecStart` command/args, name, description) is
+ * built once, in `../runtime/legacy-daemon-migration.ts`, and shared with the
+ * onboarding guided UX — see that module's doc comment for why.
+ */
+function buildManager(input: DaemonServiceCliInput): PlatformServiceManager {
+  return buildManagedDaemonServiceManager({
+    binaryPath: input.binaryPath,
+    homeDir: input.homeDir,
+    host: input.host,
+    port: input.port,
+    workingDirectory: input.workingDirectory,
+    configManager: input.configManager,
+    actionRunner: input.actionRunner,
+  });
+}
+
+function statusLines(status: ManagedServiceStatus): string[] {
+  const lines = [
+    `platform: ${status.platform}`,
+    `installed: ${status.installed}`,
+    `running: ${status.running}`,
+    `unit path: ${status.path}`,
+  ];
+  if (status.pid !== undefined) lines.push(`pid: ${status.pid}`);
+  if (status.platform !== 'manual' && status.installed && !status.running) {
+    // W3 Finding 4: this used to assert "'running' here only reflects
+    // processes this tool started directly" — true for the pid-file-only
+    // check the (currently linked) SDK still uses, but the parallel SDK
+    // batch is making status().running query systemd honestly via
+    // `is-active`, which would make that specific claim stale. Drop the
+    // claim about HOW running was computed and just offer the escape
+    // hatch — true and useful under either SDK version.
+    lines.push(
+      `note: if this looks wrong, verify directly: ${status.suggestedCommands[status.suggestedCommands.length - 1] ?? 'the platform service-status command'}`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * Build the install-branch's result lines. Exported for direct unit
+ * coverage: the "suggested follow-ups" block is gated on the actual
+ * not-started case (W3 Finding 4 friction fix) rather than printed
+ * unconditionally, and driving that through the full
+ * PlatformServiceManager/systemd integration can't reliably produce
+ * `running: true` under the (currently linked) SDK build, whose systemd
+ * status check is still pid-file-only (see the honesty note above).
+ */
+export function buildInstallResultLines(status: ManagedServiceStatus): string[] {
+  const lines = [`installed the ${status.platform} service at ${status.path}`];
+  if (status.running) {
+    lines.push('service is enabled and running');
+  } else {
+    lines.push('suggested follow-ups if it did not start automatically:');
+    for (const cmd of status.suggestedCommands) lines.push(`  ${cmd}`);
+  }
+  return lines;
+}
+
+function ok(action: 'install' | 'uninstall' | 'status', status: ManagedServiceStatus, extra: string[] = []): DaemonServiceCliResult {
+  const lines: string[] = [];
+  if (action === 'install') {
+    lines.push(...buildInstallResultLines(status));
+  } else if (action === 'uninstall') {
+    lines.push(`removed the ${status.platform} service at ${status.path}`);
+    if (status.platform === 'systemd') {
+      lines.push(
+        "note: this removes the unit file but does not run `disable` — run " +
+          "`systemctl --user daemon-reload` to clear any stale enablement symlink.",
+      );
+    }
+  } else {
+    lines.push(...statusLines(status));
+  }
+  lines.push(...extra);
+  return { ok: true, exitCode: 0, lines, status };
+}
+
+function failed(action: 'install' | 'uninstall' | 'status', status: ManagedServiceStatus): DaemonServiceCliResult {
+  return {
+    ok: false,
+    exitCode: 1,
+    lines: [`service ${action} failed: ${status.actionError ?? 'unknown error'}`],
+    status,
+  };
+}
+
+/**
+ * `migrate-service`: the guided, consented takeover of the legacy
+ * `goodvibes-daemon.service` unit (W4-D1). Thin wrapper over
+ * `runLegacyDaemonMigration` (`../runtime/legacy-daemon-migration.ts`) — see
+ * that module for the design constraints (never auto-migrate,
+ * new-up-then-old-down, adopt-or-warn/never kill an unrecognized process,
+ * every action through an injectable seam) and the onboarding UX consumer.
+ */
+function runMigrateService(
+  input: DaemonServiceCliInput,
+  manager: PlatformServiceManager,
+  legacy: LegacyUnitInfo,
+): Promise<DaemonServiceCliResult> {
+  return runLegacyDaemonMigration(
+    {
+      host: input.host,
+      port: input.port,
+      trackedServiceName: SERVICE_NAME,
+      confirmMigration: input.confirmMigration,
+      portProbe: input.portProbe,
+      legacyUnitFileRemove: input.legacyUnitFileRemove,
+      actionRunner: input.actionRunner,
+    },
+    manager,
+    legacy,
+  );
+}
+
+/** Dispatch a daemon service subcommand to the SDK's `PlatformServiceManager`. */
+export async function runDaemonServiceCli(input: DaemonServiceCliInput): Promise<DaemonServiceCliResult> {
+  const manager = buildManager(input);
+  const legacy = detectLegacyUnit(input);
+  switch (input.subcommand) {
+    case 'migrate-service':
+      return runMigrateService(input, manager, legacy);
+    case 'install-service': {
+      // W3 Finding 4: refuse rather than risk starting a second daemon
+      // alongside an already-installed legacy unit. Refuses whenever the
+      // legacy unit is present at all (not just when currently active) —
+      // an installed-but-inactive legacy unit can still be enabled and
+      // start competing for the same port later, and "never silently
+      // start a second daemon" is the bar here, not "never right now."
+      if (legacy.present) {
+        const status = manager.status();
+        const resolvedName = resolveManagedUnitName(status);
+        return {
+          ok: false,
+          exitCode: 1,
+          lines: [
+            `service install refused: a service is already installed under the legacy name ${LEGACY_SERVICE_UNIT_NAME}.service.`,
+            legacyUnitNote(legacy, resolvedName),
+            `Installing this tool's ${resolvedName}.service alongside it risks two daemons competing for the same port.`,
+          ],
+          status,
+        };
+      }
+      const installed = manager.install();
+      if (installed.actionError) return failed('install', installed);
+      const started = manager.start();
+      // start()'s actionError (e.g. a platform this manager can't dispatch
+      // actions for) doesn't undo the write — report install as ok, but surface
+      // the follow-up problem honestly instead of claiming it is running.
+      return started.actionError
+        ? ok('install', { ...started, running: false }, [`could not start it automatically: ${started.actionError}`])
+        : ok('install', started);
+    }
+    case 'uninstall-service': {
+      const stopped = manager.stop();
+      const uninstalled = manager.uninstall();
+      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, per F2 — 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.
+      if (legacy.present) extra.push(legacyUnitNote(legacy, resolveManagedUnitName(uninstalled)));
+      return ok('uninstall', uninstalled, extra);
+    }
+    case 'service-status': {
+      const status = manager.status();
+      if (status.actionError) return failed('status', status);
+      return ok('status', status, legacy.present ? [legacyUnitNote(legacy, resolveManagedUnitName(status))] : []);
+    }
+  }
+}

package/src/export/cost-utils.ts

@@ -151,3 +151,39 @@ export function calcSessionCost(
   const billableInput = inputTokens + cacheRead + cacheWrite;
   return (billableInput * pricing.input + outputTokens * pricing.output) / 1_000_000;
 }
+
+/**
+ * computeBudgetBreach — pure predicate shared by CostTrackerPanel's render-time
+ * "OVER BUDGET" flag and the background budget-breach notifier
+ * (core/budget-breach-notifier.ts), so both agree on exactly one definition
+ * of "over budget". `budgetThreshold <= 0` means no budget is configured
+ * (disabled), which can never be breached.
+ */
+export function computeBudgetBreach(sessionCost: number, budgetThreshold: number): boolean {
+  return budgetThreshold > 0 && sessionCost > budgetThreshold;
+}
+
+/** Read/write access to the `behavior.budgetAlertUsd` TUI-local config key. Plain
+ * callbacks (rather than a ConfigManager reference) so callers can pass a
+ * generic-key-cast wrapper without this module depending on the SDK config types. */
+export interface BudgetAlertConfigAccess {
+  readonly get: (key: string) => unknown;
+  readonly set: (key: string, value: unknown) => void;
+}
+
+/** Default for the `behavior.budgetAlertUsd` synthetic setting: 0 = no budget configured. */
+export const BUDGET_ALERT_USD_DEFAULT = 0;
+
+/**
+ * readBudgetAlertUsd — read the session cost-budget alert threshold (USD) from
+ * config. This is the single source of truth CostTrackerPanel and the
+ * background budget-breach notifier (core/budget-breach-notifier.ts) both
+ * read, so a threshold set via the panel's 'b' key is immediately visible to
+ * the notifier and vice versa. Falls back to BUDGET_ALERT_USD_DEFAULT (off)
+ * when the key is absent or invalid.
+ */
+export function readBudgetAlertUsd(configGet: (key: string) => unknown): number {
+  const raw = configGet('behavior.budgetAlertUsd');
+  const parsed = typeof raw === 'number' ? raw : Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : BUDGET_ALERT_USD_DEFAULT;
+}

package/src/input/autocomplete.ts

@@ -1,4 +1,4 @@
-import type { SlashCommand } from './command-registry.ts';
+import { COMMON_COMMAND_NAMES, type SlashCommand } from './command-registry.ts';
 import type { CommandRegistry } from './command-registry.ts';
 
 /**
@@ -18,6 +18,14 @@ export interface AutocompleteState {
   query: string;
   results: AutocompleteResult[];
   selectedIndex: number;
+  /**
+   * UX-C (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
+   * before the alphabetical rest.
+   */
+  commonCount: number;
 }
 
 /**
@@ -35,6 +43,7 @@ export class AutocompleteEngine {
     query: '',
     results: [],
     selectedIndex: 0,
+    commonCount: 0,
   };
 
   constructor(private registry: CommandRegistry) {}
@@ -47,6 +56,22 @@ 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),
+    // 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
+    // its actual match quality, not tier, so the common/rest split does not
+    // apply — the resulting 0 is not a real answer to "how many are common"
+    // and is unused because renderAutocompleteOverlay itself gates on the
+    // query string too, but zeroing here keeps the field internally honest.
+    let commonCount = 0;
+    if (query === '') {
+      for (const result of this.state.results) {
+        if (!COMMON_COMMAND_NAMES.has(result.command.name)) break;
+        commonCount++;
+      }
+    }
+    this.state.commonCount = commonCount;
     // Clamp selection to new result count
     if (this.state.selectedIndex >= this.state.results.length) {
       this.state.selectedIndex = Math.max(0, this.state.results.length - 1);
@@ -79,6 +104,7 @@ export class AutocompleteEngine {
       query: '',
       results: [],
       selectedIndex: 0,
+      commonCount: 0,
     };
   }
 

package/src/input/command-registry.ts

@@ -7,7 +7,8 @@ import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
 import type { PermissionRequestHandler } from '@pellux/goodvibes-sdk/platform/permissions';
 import type { SelectionItem, SelectionResult, SelectionAction } from './selection-modal.ts';
 import type { FileUndoManager } from '@pellux/goodvibes-sdk/platform/state';
-import type { PanelManager } from '../panels/panel-manager.ts';
+import type { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
+import type { PanelManager, PanelDeepLinkTarget } from '../panels/panel-manager.ts';
 import type { KeybindingsManager } from './keybindings.ts';
 import type { OnboardingWizardMode } from './onboarding/onboarding-wizard.ts';
 import type { OpenOnboardingWizardOptions } from './handler-ui-state.ts';
@@ -47,6 +48,13 @@ export interface CommandRuntimeState {
   systemPrompt: string;
   reasoningEffort: string;
   sessionId: string;
+  /**
+   * 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.)
+   */
+  terminalWritesIntercepted?: number;
 }
 
 /**
@@ -68,6 +76,9 @@ export interface CommandUiActions {
   };
   executeCommand?: (name: string, args: string[]) => Promise<boolean>;
   cancelGeneration?: () => void;
+  /** 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;
   completeModelSelection?: (selection: {
     model: { id: string; provider: string; displayName: string; registryKey: string };
     effort: string;
@@ -75,6 +86,14 @@ export interface CommandUiActions {
     /** Which config target to write the selected model to. Defaults to 'main'. */
     target?: import('./model-picker.ts').ModelPickerTarget;
   }) => void;
+  /**
+   * Commit an embedding-provider selection from the model picker's
+   * 'embeddingProvider' mode (the 'embeddings' target). Deliberately separate
+   * from completeModelSelection — embedding providers are not
+   * ModelDefinition-shaped, so routing them through the same commit path
+   * would require fabricating a fake model object.
+   */
+  completeEmbeddingProviderSelection?: (providerId: string) => void;
   clearScreen?: () => void;
   activatePlan?: (planId: string, task: string) => void;
   requestPermission?: PermissionRequestHandler;
@@ -103,16 +122,32 @@ export interface CommandShellUiOpeners {
   openSelection?: (
     title: string,
     items: SelectionItem[],
-    opts: { preSelectId?: string; allowSearch?: boolean; customActions?: Map<string, SelectionAction> } | undefined,
+    opts: { preSelectId?: string; allowSearch?: boolean; customActions?: Map<string, SelectionAction>; primaryVerbLabel?: string } | undefined,
     callback: (result: SelectionResult | null) => void,
   ) => void;
   openSettingsModal?: (target?: string) => void;
+  /**
+   * Open a MIGRATE-TO-MODAL surface by name (W6.1 purge skeleton — WO-A/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.
+   */
+  openModal?: (name: string) => void;
   openSessionPicker?: () => void;
   openProfilePicker?: () => void;
   openShortcutsOverlay?: () => void;
   getScrollTop?: () => number;
   openPanelPicker?: () => void;
-  showPanel?: (panelId: string, pane?: 'top' | 'bottom') => void;
+  /**
+   * Open (and optionally focus) a panel. UX-C 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
+   * fleet deep-link jump target forwarded to PanelManager.open.
+   */
+  showPanel?: (panelId: string, pane?: 'top' | 'bottom', target?: PanelDeepLinkTarget, opts?: { focus?: boolean }) => void;
   focusPanels?: () => void;
   focusPrompt?: () => void;
   openOpsPanel?: () => void;
@@ -157,6 +192,22 @@ export interface CommandSessionServices {
    * fresh Orchestrator's zeroed default (W0.9).
    */
   readonly hydrateSessionUsage?: () => void;
+  /** Wave 4 (wo703): the orchestration engine's command-facing facade — see runtime/workstream-services.ts. */
+  readonly workstreamEngine?: import('../runtime/workstream-services.ts').WorkstreamCommandService;
+  /** Wave 5 (wo804): the repo source-tree code index — see runtime/code-index-services.ts. */
+  readonly codeIndexStore?: import('@pellux/goodvibes-sdk/platform/state').CodeIndexStore;
+  /** Wave-5 Stage B: tool-site reindex scheduler — `/codebase status` reports its last activity. */
+  readonly codeIndexReindexScheduler?: import('@pellux/goodvibes-sdk/platform/state').CodeIndexReindexScheduler;
+  /** Wave-5 Stage B: whether the (default-off) `agent-passive-code-injection` flag is on — for `/codebase status`. */
+  readonly isPassiveCodeInjectionFlagEnabled?: () => boolean;
+  /**
+   * Wave 5 (wo805): the MAIN interactive session's per-turn passive-injection
+   * honesty ring — `Orchestrator.getTurnInjections()`, the main-session
+   * counterpart to `AgentRecord.turnInjections` (wo801). `/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.
+   */
+  readonly getMainSessionTurnInjections?: () => readonly import('../renderer/turn-injection.ts').TurnInjectionEntry[];
 }
 
 export interface CommandProviderServices {
@@ -173,6 +224,7 @@ export interface CommandProviderServices {
 export interface CommandWorkspaceUiServices {
   keybindingsManager?: KeybindingsManager;
   fileUndoManager?: FileUndoManager;
+  workspaceCheckpointManager?: WorkspaceCheckpointManager;
   panelManager?: PanelManager;
   profileManager?: import('@pellux/goodvibes-sdk/platform/profiles').ProfileManager;
   bookmarkManager?: import('@pellux/goodvibes-sdk/platform/bookmarks').BookmarkManager;
@@ -190,6 +242,11 @@ export interface CommandPlatformConfigServices {
   readonly configManager: ConfigManager;
   readonly voiceProviderRegistry?: VoiceProviderRegistry;
   readonly voiceService?: VoiceService;
+  /** Direct-command consumer (`/search`) alongside the existing agent-tool consumer. */
+  readonly webSearchService?: import('@pellux/goodvibes-sdk/platform/web-search').WebSearchService;
+  /** Direct-command consumer (`/image`) — first production caller of `.generate()`. */
+  readonly mediaProviders?: import('@pellux/goodvibes-sdk/platform/media').MediaProviderRegistry;
+  readonly artifactStore?: import('@pellux/goodvibes-sdk/platform/artifacts').ArtifactStore;
 }
 
 export interface CommandPlatformServices
@@ -202,7 +259,7 @@ export interface CommandOpsServices
 export interface CommandExtensionRegistryServices {
   readonly toolRegistry: ToolRegistry;
   readonly mcpRegistry: McpRegistry;
-  readonly evalRegistry?: import('../panels/eval-panel.ts').EvalRegistry;
+  readonly evalRegistry?: import('../panels/eval-registry.ts').EvalRegistry;
 }
 
 export interface CommandExtensionServices
@@ -235,6 +292,23 @@ export interface CommandContext
   };
 }
 
+/**
+ * UX-C 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
+ * unaffected — fuzzyMatch still searches every registered command exactly as
+ * before; this only reorders the empty-query case. Curated for breadth across
+ * the product's main workflows rather than raw usage frequency: help/config
+ * (orientation), panel/model (workspace + provider), recall/codebase/search
+ * (knowledge), workstream/checkpoint (control-plane), imagine (generation),
+ * sessions (continuity), quit (exit).
+ */
+export const COMMON_COMMAND_NAMES: ReadonlySet<string> = new Set([
+  'help', 'config', 'panel', 'model', 'recall', 'codebase',
+  'workstream', 'checkpoint', 'search', 'imagine', 'sessions', 'quit',
+]);
+
 /**
  * SlashCommand - A single slash command definition.
  */
@@ -337,7 +411,12 @@ export class CommandRegistry {
       }
 
       if (bestScore > 0 || q === '') {
-        results.push({ command: cmd, score: q === '' ? 1 : bestScore });
+        // UX-C: 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.
+        const score = q === '' ? (COMMON_COMMAND_NAMES.has(cmd.name) ? 2 : 1) : bestScore;
+        results.push({ command: cmd, score });
       }
     }