@pellux/goodvibes-tui 1.13.1 → 1.15.0

package/src/runtime/bootstrap.ts

@@ -13,45 +13,37 @@ import { join } from 'node:path';
 import { Orchestrator, type OrchestratorUserInputOptions } from '../core/orchestrator.ts';
 import { AcpManager } from '@pellux/goodvibes-sdk/platform/acp';
 import { getTierPromptSupplement, getTierForContextWindow } from '@pellux/goodvibes-sdk/platform/providers';
-import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import type { PermissionRequestHandler } from '@pellux/goodvibes-sdk/platform/permissions';
 import type { CommandContext } from '../input/command-registry.ts';
 import type { InputHistory } from '../input/input-history.ts';
-import type { GitStatusProvider } from '../renderer/git-status.ts';
-import type { GitHeaderInfo } from '../renderer/git-status.ts';
+import type { GitStatusProvider, GitHeaderInfo } from '../renderer/git-status.ts';
 import type { SelectionManager } from '../input/selection.ts';
 import type { Compositor } from '../renderer/compositor.ts';
 
 import type { RuntimeContext, BootstrapOptions } from './context.ts';
-import { shutdownRuntime, fireSessionStart, saveSession } from '@/runtime/index.ts';
-import { createTaskManager } from '@/runtime/index.ts';
-import { OpsControlPlane } from '@/runtime/index.ts';
-import { AcpTaskAdapter } from '@/runtime/index.ts';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
-import { emitSessionReady, emitSessionStarted } from '@/runtime/index.ts';
 import {
-  loadLastConversation,
-  writeLastSessionPointer,
+  shutdownRuntime, fireSessionStart, saveSession, createTaskManager, OpsControlPlane, AcpTaskAdapter,
+  emitSessionReady, emitSessionStarted, loadLastConversation, writeLastSessionPointer,
+  scheduleBackgroundMcpDiscovery, startBackgroundProviderRegistration, restoreSavedModel, startExternalServices,
+  type ExternalServicesHandle, type HostServiceStatus, createHttpTransport, createDeferredStartupCoordinator,
 } from '@/runtime/index.ts';
-import { scheduleBackgroundMcpDiscovery, startBackgroundProviderRegistration } from '@/runtime/index.ts';
-import { restoreSavedModel } from '@/runtime/index.ts';
-import { startExternalServices, type ExternalServicesHandle, type HostServiceStatus } from '@/runtime/index.ts';
-import { createHttpTransport } from '@/runtime/index.ts';
 import { foldLegacySpineStore, deriveSpineFooterStatus } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
 import { createTuiSpineTransport, type SpineSessionsClient } from './session-spine-transport.ts';
 import { syncMemorySpineToHostStatus, type MemorySpineActiveRef } from './memory-spine-transport.ts';
 import { pruneStaleOperatorTokens } from '@pellux/goodvibes-sdk/platform/pairing';
 import { resolveDaemonCompanionToken, workspaceOperatorTokenCandidates } from './operator-token-cleanup.ts';
 import type { UiRuntimeServices } from './ui-services.ts';
-import { createDeferredStartupCoordinator } from '@/runtime/index.ts';
 import { initializeBootstrapCore } from './bootstrap-core.ts';
 import { createBootstrapShell } from './bootstrap-shell.ts';
 import { announceResumeState } from './resume-notice.ts';
+import { announceInstallSelfCheck } from './install-self-check-startup.ts';
 import { buildSharedOrchestratorCoreServices, refreshMemoryRecallSnapshot } from './orchestrator-core-services.ts';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-import { DaemonServer } from '@pellux/goodvibes-sdk/platform/daemon';
-import { HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
+import { createContextAccountingSource } from './context-accounting-source.ts';
+import { DaemonServer, HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
 import { createSafeHostServeFactory } from '../daemon/safe-serve.ts';
+import { buildRelayExternalServiceMethods } from './relay-reachability-bridge.ts';
 import { startMcpConfigAutoReload } from '../mcp/runtime-reload.ts';
 
 type ExternalServiceFactories = NonNullable<Parameters<typeof startExternalServices>[4]>;
@@ -253,6 +245,13 @@ export async function bootstrapRuntime(
   });
   conversation.setSessionLineageTracker(services.sessionLineageTracker);
 
+  // Bind context_accounting's session source to the live Orchestrator (see context-accounting-source.ts).
+  const contextAccountingSourceHandle = createContextAccountingSource({
+    orchestrator, providerRegistry, sessionLineageTracker: services.sessionLineageTracker, runtimeBus, sessionId: runtime.sessionId,
+  });
+  services.contextAccountingHolder.setSource(contextAccountingSourceHandle.source);
+  bootstrapUnsubs.push(contextAccountingSourceHandle.dispose);
+
   const acpManager = new AcpManager({
     requestPermission: (request) => permissionPromptRef.requestPermission(request),
     runtimeBus,
@@ -317,9 +316,8 @@ export async function bootstrapRuntime(
   }).catch(() => {
     // Best-effort — never let the resume notice block or crash boot.
   });
-  const gitStatusProvider = shell.gitStatusProvider;
-  const inputHistory = shell.inputHistory;
-  const lastGitInfoRef = shell.lastGitInfoRef;
+  announceInstallSelfCheck(systemMessageRouter);
+  const { gitStatusProvider, inputHistory, lastGitInfoRef } = shell;
   // W1.6 FIX 2: dispose the header's live-repo-state poll (git-status.ts
   // startPolling) on shutdown, same pattern as acpTaskSyncInterval above.
   bootstrapUnsubs.push(() => gitStatusProvider.stopPolling());
@@ -494,8 +492,7 @@ export async function bootstrapRuntime(
   });
 
   let externalServices: ExternalServicesHandle = {
-    daemonServer: null,
-    httpListener: null,
+    daemonServer: null, httpListener: null,
     daemonStatus: createPendingServiceStatus('daemon'),
     httpListenerStatus: createPendingServiceStatus('httpListener'),
     listRecentControlPlaneEvents: () => [],
@@ -506,6 +503,7 @@ export async function bootstrapRuntime(
     externalServices: NonNullable<typeof uiServices.platform.externalServices>;
   };
   platformExternalServices.externalServices = {
+    ...buildRelayExternalServiceMethods(() => externalServices.daemonServer),
     inspect: inspectExternalServices,
     restart: async () => {
       if (externalServicesPromise) {

package/src/runtime/context-accounting-source.ts

@@ -0,0 +1,103 @@
+import type { Orchestrator } from '../core/orchestrator.ts';
+import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
+import type { SessionLineageTracker } from '@pellux/goodvibes-sdk/platform/core';
+import type { ContextAccountingSource } from '@pellux/goodvibes-sdk/platform/tools';
+
+/**
+ * Minimal runtime-bus surface this module needs: subscribe by event type.
+ * A narrow structural type (not the full RuntimeEventBus) so this module
+ * doesn't pull in `runtime/index.ts` — bootstrap.ts imports this module
+ * directly, and index.ts re-exports bootstrap.ts, so a barrel import here
+ * would be a 3-file cycle (see check-architecture.ts's cycle detector).
+ */
+export interface CompactionActivityBus {
+  on(eventType: string, callback: () => void): () => void;
+}
+
+/**
+ * Builds the interactive session's ContextAccountingSource — the honest
+ * backing for the SDK's `context_accounting` tool. Bound onto
+ * `RuntimeServices.contextAccountingHolder` once, at bootstrap (see
+ * bootstrap.ts, right after the live Orchestrator is constructed).
+ *
+ * Every field here reads a REAL, already-tracked value:
+ *  - getTurnInjections()  → Orchestrator.getTurnInjections() (the same bounded
+ *    ring `/recall injections` renders from).
+ *  - getTokenState()      → Orchestrator.usage / lastInputTokens (the same
+ *    counters the footer's context bar and CostTrackerPanel read), plus the
+ *    current model's context window from the provider registry.
+ *  - getCompactionState()  → compactionCount from SessionLineageTracker (the
+ *    same counter session-maintenance and /compact read); isCompacting is
+ *    tracked from real 'compaction' domain lifecycle events on the runtime
+ *    bus, since the Orchestrator has no public accessor for it — NOT
+ *    fabricated. Without a runtime bus (headless/test callers), isCompacting
+ *    honestly stays false rather than guessing.
+ */
+export interface ContextAccountingSourceDeps {
+  readonly orchestrator: Pick<Orchestrator, 'getTurnInjections' | 'usage' | 'lastInputTokens'>;
+  readonly providerRegistry: Pick<ProviderRegistry, 'getCurrentModel' | 'getContextWindowForModel'>;
+  readonly sessionLineageTracker: Pick<SessionLineageTracker, 'getCompactionCount'>;
+  readonly runtimeBus?: CompactionActivityBus | null | undefined;
+  readonly sessionId: string;
+  /** Human-readable scope label, e.g. "main session". Defaults to 'main session'. */
+  readonly scope?: string | undefined;
+}
+
+/** Events that mark a compaction run starting. */
+const COMPACTION_START_EVENT_TYPES = [
+  'COMPACTION_AUTOCOMPACT',
+  'COMPACTION_REACTIVE',
+  'COMPACTION_MICROCOMPACT',
+  'COMPACTION_COLLAPSE',
+] as const;
+
+/** Events that mark a compaction run ending (successfully, rejected, or failed). */
+const COMPACTION_END_EVENT_TYPES = [
+  'COMPACTION_DONE',
+  'COMPACTION_FAILED',
+  'COMPACTION_RECEIPT',
+] as const;
+
+export interface ContextAccountingSourceHandle {
+  readonly source: ContextAccountingSource;
+  /** Unsubscribe the compaction-activity listeners. Call on session teardown. */
+  readonly dispose: () => void;
+}
+
+export function createContextAccountingSource(deps: ContextAccountingSourceDeps): ContextAccountingSourceHandle {
+  let isCompacting = false;
+  const unsubs: Array<() => void> = [];
+  if (deps.runtimeBus) {
+    const bus = deps.runtimeBus;
+    for (const type of COMPACTION_START_EVENT_TYPES) {
+      unsubs.push(bus.on(type, () => { isCompacting = true; }));
+    }
+    for (const type of COMPACTION_END_EVENT_TYPES) {
+      unsubs.push(bus.on(type, () => { isCompacting = false; }));
+    }
+  }
+
+  const source: ContextAccountingSource = {
+    scope: deps.scope ?? 'main session',
+    sessionId: deps.sessionId,
+    getTurnInjections: () => deps.orchestrator.getTurnInjections(),
+    getTokenState: () => {
+      const currentModel = deps.providerRegistry.getCurrentModel();
+      const contextWindow = deps.providerRegistry.getContextWindowForModel(currentModel);
+      return {
+        measured: { ...deps.orchestrator.usage },
+        lastInputTokens: deps.orchestrator.lastInputTokens,
+        contextWindow: contextWindow > 0 ? contextWindow : null,
+      };
+    },
+    getCompactionState: () => ({
+      isCompacting,
+      compactionCount: deps.sessionLineageTracker.getCompactionCount(),
+    }),
+  };
+
+  return {
+    source,
+    dispose: () => { for (const unsub of unsubs) unsub(); },
+  };
+}

package/src/runtime/conversation-rewind-port.ts

@@ -0,0 +1,130 @@
+// ---------------------------------------------------------------------------
+// conversation-rewind-port.ts — the TUI's ConversationManager as the SDK unified
+// rewind service's RewindConversationPort.
+//
+// The SDK's UnifiedRewindService (platform/rewind) joins files rewind (workspace
+// checkpoints) with conversation rewind through two ports. The conversation port
+// is "a daemon-hosted mutable conversation store": preview() reports how many
+// messages would truncate to a recorded turn boundary, and rewind() performs the
+// truncation and captures the pre-/post-truncation snapshots so the reversal can
+// be undone and re-applied. The truncation boundary is the message count recorded
+// for the anchor's turnId at TURN_COMPLETED (rewind-turn-anchors.ts) — the same
+// join key files rewind uses against the workspace checkpoint.
+//
+// This module is the single implementation of that port for the TUI, consumed by
+// BOTH the in-process /rewind command (bound to one session's conversation) and
+// the composed daemon's rewind.plan/apply verbs (resolving the live conversation
+// per anchor.sessionId from the registry below), so the truncation semantics
+// cannot drift between the two surfaces.
+// ---------------------------------------------------------------------------
+
+import type {
+  RewindAnchor,
+  RewindConversationOutcome,
+  RewindConversationPort,
+  RewindConversationPreview,
+} from '@pellux/goodvibes-sdk/platform/rewind';
+import type { ConversationManager } from '../core/conversation.ts';
+import { resolveTurnAnchor } from '../core/rewind-turn-anchors.ts';
+
+type ConversationJson = Parameters<ConversationManager['fromJSON']>[0];
+
+/** The port plus the reversal accessors the TUI-side undo/redo needs. */
+export interface ConversationRewindPort extends RewindConversationPort {
+  /** Restore the pre-truncation conversation (the /undo direction). */
+  restoreBefore(undoSnapshotId: string): boolean;
+  /** Restore the post-truncation conversation (the /redo direction). */
+  restoreAfter(undoSnapshotId: string): boolean;
+}
+
+/** One truncation's captured state — the target conversation and its snapshots. */
+interface SnapshotPair {
+  readonly conv: ConversationManager;
+  readonly before: ConversationJson;
+  readonly after: ConversationJson;
+}
+
+/**
+ * Build a conversation rewind port. `resolveConversation` maps an anchor's
+ * sessionId to the live ConversationManager — for the single-session /rewind
+ * command it returns the one bound conversation; for the daemon it looks the
+ * session up in the live registry. A null resolution means no live conversation
+ * for that session, reported as "nothing to drop" rather than a fabricated count.
+ */
+export function createConversationRewindPort(
+  resolveConversation: (sessionId: string) => ConversationManager | null,
+): ConversationRewindPort {
+  const snapshots = new Map<string, SnapshotPair>();
+
+  function keepFor(anchor: RewindAnchor): { conv: ConversationManager | null; keep: number; total: number } {
+    const conv = resolveConversation(anchor.sessionId);
+    if (!conv) return { conv: null, keep: 0, total: 0 };
+    const total = conv.getMessageCount();
+    const rec = anchor.turnId ? resolveTurnAnchor(anchor.sessionId, anchor.turnId) : null;
+    const keep = rec ? Math.min(rec.messageCount, total) : total;
+    return { conv, keep, total };
+  }
+
+  function restore(snapshot: SnapshotPair | undefined, which: 'before' | 'after'): boolean {
+    if (!snapshot) return false;
+    snapshot.conv.fromJSON(snapshot[which]);
+    snapshot.conv.rebuildHistory();
+    return true;
+  }
+
+  return {
+    async preview(anchor: RewindAnchor): Promise<RewindConversationPreview> {
+      const { keep, total } = keepFor(anchor);
+      return { messagesToDrop: Math.max(0, total - keep), messagesRemaining: keep };
+    },
+
+    async rewind(anchor: RewindAnchor): Promise<RewindConversationOutcome> {
+      const { conv, keep, total } = keepFor(anchor);
+      const undoSnapshotId = `rwc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+      if (!conv) return { droppedMessages: 0, undoSnapshotId };
+      const before = conv.toJSON() as ConversationJson;
+      conv.removeMessagesAfter(keep);
+      conv.rebuildHistory();
+      const after = conv.toJSON() as ConversationJson;
+      snapshots.set(undoSnapshotId, { conv, before, after });
+      return { droppedMessages: Math.max(0, total - keep), undoSnapshotId };
+    },
+
+    restoreBefore(undoSnapshotId: string): boolean {
+      return restore(snapshots.get(undoSnapshotId), 'before');
+    },
+
+    restoreAfter(undoSnapshotId: string): boolean {
+      return restore(snapshots.get(undoSnapshotId), 'after');
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Live per-session conversation registry — the daemon-hosted mutable store the
+// composed daemon's rewind.plan/apply verbs resolve conversations from. The TUI
+// registers its active session's ConversationManager at bootstrap; a session
+// with no registration reports conversation rewind as "nothing to drop".
+// ---------------------------------------------------------------------------
+
+const liveConversations = new Map<string, ConversationManager>();
+
+/** Register a session's live conversation so the daemon rewind verbs can serve it. */
+export function registerSessionConversation(sessionId: string, conversation: ConversationManager): void {
+  if (sessionId) liveConversations.set(sessionId, conversation);
+}
+
+/** Drop a session's conversation registration. */
+export function unregisterSessionConversation(sessionId: string): void {
+  liveConversations.delete(sessionId);
+}
+
+/**
+ * The conversation rewind port the composed daemon threads into
+ * registerGatewayVerbGroups — it resolves each anchor's live conversation from
+ * the registry above, so the daemon's own rewind verbs serve conversation scope
+ * live in this process.
+ */
+export function createSessionConversationRewindPort(): ConversationRewindPort {
+  return createConversationRewindPort((sessionId) => liveConversations.get(sessionId) ?? null);
+}

package/src/runtime/fleet-needs-input-push.ts

@@ -0,0 +1,70 @@
+/**
+ * fleet-needs-input-push.ts — wires the fleet "needs-input" browser-push fan-out
+ * that the SDK's registerGatewayVerbGroups (reached through the terminal-shell's
+ * attachWsOnlyGatewayVerbHandlers wrapper) gates on two deps: `runtimeBus` and
+ * `sessionPresence` (see push/service.ts's attachFleetNeedsInputSource). When a
+ * fleet node blocks on the operator, it pushes an "Input needed" notification
+ * carrying the session/node deep link to every registered device — suppressed
+ * while an operator surface is already attached to that node's session.
+ *
+ * TWO seams have to be live for a real push, not just descriptor presence:
+ *  1. Fleet lifecycle deltas (FLEET_NODE_BLOCKED_ON_USER etc.) have to reach the
+ *     runtime bus's 'fleet' domain in the first place. That is
+ *     attachFleetEmitBridge, diffing the process registry's own coalesced
+ *     snapshot tick into per-node lifecycle events. The terminal-shell package's
+ *     createArchivableFleetRegistry only builds the registry — it does not
+ *     attach the bridge — so the composition root that owns both the registry
+ *     and the bus (this file) is the one place responsible for it. The SDK's
+ *     own daemon composition (platform/runtime/services.ts) attaches this same
+ *     bridge right after building its process registry.
+ *  2. registerGatewayVerbGroups has to be handed `runtimeBus` (to subscribe onto
+ *     that domain) and `sessionPresence` (to suppress a push when an operator is
+ *     already looking at the session).
+ *
+ * sessionPresence mirrors the SDK's own daemon composition: a session counts as
+ * attended when any participant heartbeated within the freshness window below.
+ * Reimplemented here on the broker's public getSession()/SharedSessionRecord
+ * shape rather than imported, because the SDK does not expose its own
+ * hasFreshSurfaceParticipant helper as public API.
+ */
+import { attachFleetEmitBridge } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
+import type { ArchivableProcessRegistry } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
+import type { SharedSessionBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { RuntimeEventBus } from '@/runtime/index.ts';
+
+/**
+ * How recently a participant must have been seen to count as actively
+ * attached. Mirrors the SDK's own (private) SURFACE_ROUTE_FRESHNESS_MS.
+ */
+const SURFACE_ATTACHED_FRESHNESS_MS = 2 * 60 * 1000;
+
+export interface FleetNeedsInputPushDeps {
+  readonly runtimeBus: RuntimeEventBus;
+  readonly sessionPresence: { isAttached(sessionId: string): boolean };
+}
+
+/**
+ * Attach the fleet emit-bridge (registry snapshot deltas -> runtime bus `fleet`
+ * domain) and build the presence lookup, returning both as the deps
+ * `attachWsOnlyGatewayVerbHandlers` spreads into its call so the needs-input
+ * push source registers for real instead of gracefully degrading to absent.
+ */
+export function wireFleetNeedsInputPush(input: {
+  readonly registry: ArchivableProcessRegistry;
+  readonly runtimeBus: RuntimeEventBus;
+  readonly sessionBroker: Pick<SharedSessionBroker, 'getSession'>;
+}): FleetNeedsInputPushDeps {
+  attachFleetEmitBridge({ registry: input.registry, bus: input.runtimeBus });
+  const sessionBroker = input.sessionBroker;
+  return {
+    runtimeBus: input.runtimeBus,
+    sessionPresence: {
+      isAttached: (sessionId: string) => {
+        const session = sessionBroker.getSession(sessionId);
+        if (!session) return false;
+        const now = Date.now();
+        return session.participants.some((participant) => now - participant.lastSeenAt < SURFACE_ATTACHED_FRESHNESS_MS);
+      },
+    },
+  };
+}

package/src/runtime/install-self-check-startup.ts

@@ -0,0 +1,36 @@
+/**
+ * install-self-check-startup.ts — the boot-time surfacing of the install
+ * self-check (install-self-check.ts). Called once from the runtime bootstrap,
+ * it wires the real host inputs (process exec path, the packaged root, the
+ * real daemon resolution, and existsSync) into the pure evaluator and prints
+ * any findings through the same SystemMessageRouter the rest of startup uses.
+ *
+ * It is intentionally cheap (existsSync-level, no network) and non-fatal:
+ * every failure is swallowed so a self-check can never block or crash boot.
+ * Each finding is printed as one high-priority system message ending in the
+ * exact repair command for the detected install kind.
+ *
+ * This module lives in the runtime layer and imports the daemon resolver from
+ * the cli layer; nothing in cli imports it back, so no import cycle forms.
+ */
+
+import { existsSync } from 'node:fs';
+import { getGoodVibesPackageRoot, resolveGoodVibesDaemonExecutable } from '../cli/service-posture.ts';
+import { runInstallSelfCheck } from './install-self-check.ts';
+import type { SystemMessageRouter } from '../core/system-message-router.ts';
+
+export function announceInstallSelfCheck(router: SystemMessageRouter): void {
+  try {
+    const findings = runInstallSelfCheck({
+      execPath: process.execPath,
+      packageRoot: getGoodVibesPackageRoot(),
+      daemon: resolveGoodVibesDaemonExecutable(),
+      fileExists: existsSync,
+    });
+    for (const finding of findings) {
+      router.high(`[Install] ${finding.summary} ${finding.detail} Repair: ${finding.repairCommand}`);
+    }
+  } catch {
+    // Best-effort — an install self-check must never block or crash boot.
+  }
+}

package/src/runtime/install-self-check.ts

@@ -0,0 +1,149 @@
+/**
+ * install-self-check.ts — cheap, non-fatal detection of an incomplete
+ * install, run at TUI startup and re-surfaced by `goodvibes doctor`.
+ *
+ * A packaged install (the standalone `install.sh` binary, or the
+ * `bun add -g` vendored package) is only usable if its release binaries are
+ * actually present: the app binary the user is running, plus the separate
+ * background daemon binary. Two things can go wrong after a partial or
+ * interrupted install:
+ *   1. the vendored release binaries were never downloaded into <root>/vendor
+ *      (scripts/postinstall.js downloads them for packaged installs), and
+ *   2. the daemon launch path resolves to nothing runnable, so any
+ *      daemon/control-plane/listener/web surface silently fails to start.
+ *
+ * This module decides those two facts from injected inputs only — an
+ * install kind, a package root, the resolved daemon executable, and a
+ * `fileExists` predicate — so it is pure and testable with fake paths and
+ * never touches the network. The production wiring (real existsSync + the
+ * real daemon resolution) lives in install-self-check-startup.ts and in the
+ * CLI status/doctor entrypoint; this file only makes the judgement.
+ *
+ * A `source` checkout run via `bun src/main.ts` is NOT an incomplete
+ * install — there is no vendor directory to populate and the daemon runs
+ * from source — so it is never flagged.
+ *
+ * Install-kind detection and the per-kind repair one-liner are reused from
+ * update-check.ts rather than re-derived here.
+ */
+
+import { join } from 'node:path';
+import { detectInstallKind, fallbackUpdateCommand, type InstallKind } from './update-check.ts';
+import { resolveArtifactNames } from './release-artifacts.ts';
+
+/**
+ * The subset of a resolved daemon executable this check needs. Structurally
+ * matches the CLI's DaemonExecutableResolution without importing it from the
+ * cli layer (that would create an import cycle: cli imports this pure module,
+ * so this module must not import back into cli).
+ */
+export interface DaemonPathResolution {
+  readonly command: string;
+  /** How the path was resolved. 'fallback' means no runnable file was found — a bare PATH command. */
+  readonly source: string;
+  readonly absolute: boolean;
+}
+
+export type InstallSelfCheckFindingId = 'missing-vendor-binaries' | 'broken-daemon-path';
+
+export interface InstallSelfCheckFinding {
+  readonly id: InstallSelfCheckFindingId;
+  readonly summary: string;
+  readonly detail: string;
+  /** The exact command to run to repair this install kind. */
+  readonly repairCommand: string;
+}
+
+export interface InstallSelfCheckInput {
+  readonly installKind: InstallKind;
+  readonly packageRoot: string;
+  readonly platform: string;
+  readonly arch: string;
+  readonly daemon: DaemonPathResolution;
+  readonly fileExists: (path: string) => boolean;
+}
+
+/**
+ * The exact repair command per install kind. A standalone `binary` install is
+ * repaired by re-running the installer (which places both binaries); the other
+ * non-binary kinds reuse update-check.ts's fallbackUpdateCommand verbatim.
+ */
+export function repairCommandForInstallKind(kind: InstallKind): string {
+  if (kind === 'binary') return 'curl -fsSL https://goodvibes.sh/install.sh | sh';
+  return fallbackUpdateCommand(kind);
+}
+
+/**
+ * Decide, from injected inputs only, whether this install is missing pieces.
+ * Returns zero findings for a source checkout (complete by definition) and for
+ * a healthy packaged install.
+ */
+export function evaluateInstallSelfCheck(input: InstallSelfCheckInput): InstallSelfCheckFinding[] {
+  if (input.installKind === 'source') return [];
+
+  const findings: InstallSelfCheckFinding[] = [];
+  const repairCommand = repairCommandForInstallKind(input.installKind);
+  const artifacts = resolveArtifactNames(input.platform, input.arch);
+
+  // (1) Missing vendored binaries. Only the vendored package install ships a
+  // <root>/vendor directory (postinstall.js downloads app + daemon there); a
+  // standalone compiled binary has none, so this check applies only to the
+  // bun-global-package kind.
+  if (input.installKind === 'bun-global-package' && artifacts) {
+    const vendorDir = join(input.packageRoot, 'vendor');
+    const missing = [artifacts.app, artifacts.daemon].filter(
+      (name) => !input.fileExists(join(vendorDir, name)),
+    );
+    if (missing.length > 0) {
+      findings.push({
+        id: 'missing-vendor-binaries',
+        summary: 'Vendored release binaries are missing from this install.',
+        detail: `${missing.join(', ')} not found under ${vendorDir}.`,
+        repairCommand,
+      });
+    }
+  }
+
+  // (2) Broken daemon path. The daemon runs as a separate binary; if the
+  // resolver fell back to a bare PATH command (nothing runnable was found on
+  // the packaged search paths) or the resolved absolute path does not exist,
+  // any daemon/control-plane/listener/web surface will fail to start.
+  const daemonMissing = input.daemon.source === 'fallback'
+    || (input.daemon.absolute && !input.fileExists(input.daemon.command));
+  if (daemonMissing) {
+    findings.push({
+      id: 'broken-daemon-path',
+      summary: 'The background daemon binary could not be located.',
+      detail: input.daemon.source === 'fallback'
+        ? `No daemon executable was found on the packaged search paths; the launcher falls back to a bare "${input.daemon.command}" on PATH.`
+        : `The resolved daemon path ${input.daemon.command} does not exist.`,
+      repairCommand,
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * Convenience wrapper that detects the install kind from an exec path (reusing
+ * update-check.ts) and then evaluates. Platform/arch default to the running
+ * host but are injectable for tests. The daemon resolution and fileExists are
+ * always injected so this stays free of process/filesystem coupling of its own.
+ */
+export function runInstallSelfCheck(input: {
+  readonly execPath: string;
+  readonly packageRoot: string;
+  readonly daemon: DaemonPathResolution;
+  readonly fileExists: (path: string) => boolean;
+  readonly platform?: string;
+  readonly arch?: string;
+}): InstallSelfCheckFinding[] {
+  return evaluateInstallSelfCheck({
+    installKind: detectInstallKind(input.execPath),
+    packageRoot: input.packageRoot,
+    platform: input.platform ?? process.platform,
+    arch: input.arch ?? process.arch,
+    daemon: input.daemon,
+    fileExists: input.fileExists,
+  });
+}