@pellux/goodvibes-tui 1.27.1 → 2.0.1

package/src/runtime/bootstrap.ts

@@ -10,32 +10,31 @@
  *   - lifecycle.ts: save/shutdown helpers
  */
 import { join } from 'node:path';
-import { Orchestrator, type OrchestratorUserInputOptions } from '../core/orchestrator.ts';
+import { Orchestrator, type OrchestratorUserInputOptions } from '@pellux/goodvibes-sdk/platform/core';
 import { AcpManager } from '@pellux/goodvibes-sdk/platform/acp';
 import { getTierPromptSupplement, getTierForContextWindow } from '@pellux/goodvibes-sdk/platform/providers';
 import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import type { PermissionRequestHandler } from '@pellux/goodvibes-sdk/platform/permissions';
-import type { WorkspaceTrustLevel } from './trust/workspace-trust.ts';
+import type { WorkspaceTrustLevel } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { CommandContext } from '../input/command-registry.ts';
 import type { InputHistory } from '../input/input-history.ts';
 import type { GitStatusProvider, GitHeaderInfo } from '../renderer/git-status.ts';
-import type { SelectionManager } from '../input/selection.ts';
+import type { SelectionManager } from '@pellux/goodvibes-terminal-shell';
 import type { Compositor } from '../renderer/compositor.ts';
 
 import type { RuntimeContext, BootstrapOptions } from './context.ts';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
 import {
   shutdownRuntime, fireSessionStart, createTaskManager, OpsControlPlane, AcpTaskAdapter,
-  emitSessionReady, emitSessionStarted, loadLastConversation,
+  emitSessionReady, emitSessionStarted, loadLastConversation, leaveHostedSessionOnExit,
   scheduleBackgroundMcpDiscovery, startBackgroundProviderRegistration, restoreSavedModel, startExternalServices,
   type ExternalServicesHandle, type HostServiceStatus, createHttpTransport, createDeferredStartupCoordinator,
 } from '@/runtime/index.ts';
-import { bindWriteLastSessionPointerToSurface } from './session-pointer-surface.ts';
+import { bindWriteLastSessionPointerToSurface } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 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 { createSpineAdoptionSync } from './client/spine-adoption.ts';
 import { pruneStaleOperatorTokens } from '@pellux/goodvibes-sdk/platform/pairing';
-import { resolveDaemonCompanionToken, workspaceOperatorTokenCandidates } from './operator-token-cleanup.ts';
+import { resolveDaemonCompanionToken, workspaceOperatorTokenCandidates } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { UiRuntimeServices } from './ui-services.ts';
 import { initializeBootstrapCore } from './bootstrap-core.ts';
 import { ensureBootModelResolvable } from './provider-fallback.ts';
@@ -43,11 +42,16 @@ import { createBootstrapShell } from './bootstrap-shell.ts';
 import { announceResumeState } from './resume-notice.ts';
 import { announceInstallHealth } from './install-self-check-startup.ts';
 import { buildSharedOrchestratorCoreServices, refreshMemoryRecallSnapshot } from './orchestrator-core-services.ts';
-import { consumeDaemonAttachNotices, consumeExternalDaemonAttachNotices } from './daemon-attach-notices.ts';
+import { consumeDaemonAttachNotices } from './daemon-attach-notices.ts';
 import { wireContextAccountingSource } from './context-accounting-source.ts';
-import { createEmbeddedServiceFactories } from './embedded-service-factories.ts';
-import { buildRelayExternalServiceMethods } from './relay-reachability-bridge.ts';
+import { autostartInstalledDaemon, createDaemonServiceControl, describeDaemonAutostart } from '@pellux/goodvibes-sdk/platform/runtime/client';
+import { createDaemonAttachHandshake } from './client/daemon-attach-handshake.ts';
+import {
+  createPendingServiceStatus, hostServiceIsActive, hostServiceIsBlocked,
+} from './client/host-service-status.ts';
+import { relayReadAccessors } from './relay-reachability-bridge.ts';
 import { startMcpConfigAutoReload } from '../mcp/runtime-reload.ts';
+import { GOODVIBES_TUI_SURFACE_ROOT } from '../config/surface.ts';
 
 type ExternalServiceFactories = NonNullable<Parameters<typeof startExternalServices>[4]>;
 
@@ -196,9 +200,6 @@ export async function bootstrapRuntime(
   } = services;
   // A saved custom-provider model must never crash boot — see provider-fallback.ts.
   await ensureBootModelResolvable(providerRegistry, configManager);
-  // A liveness flip is only PAINTED once something calls requestRender(); without
-  // this, the footer's spine segment sat correct-but-undrawn until incidental activity redrew it (minutes, during an idle stretch).
-  sessionUnionCache.setOnTransition(() => requestRender());
 
   // ── Phase 6: Orchestrator + AcpManager ───────────────────────────────────
 
@@ -350,103 +351,28 @@ export async function bootstrapRuntime(
 
   const deferredStartup = createDeferredStartupCoordinator();
 
-  const formatHostServiceBaseUrl = (host: string, port: number): string => {
-    const normalized = host.trim().toLowerCase();
-    const probeHost = normalized === '0.0.0.0'
-      ? '127.0.0.1'
-      : normalized === '::' || normalized === '[::]'
-        ? '::1'
-        : host;
-    const urlHost = probeHost.includes(':') && !probeHost.startsWith('[') ? `[${probeHost}]` : probeHost;
-    return `http://${urlHost}:${port}`;
-  };
-
-  const createPendingServiceStatus = (
-    service: 'daemon' | 'httpListener',
-  ): HostServiceStatus => {
-    const host = String(configManager.get(service === 'daemon' ? 'controlPlane.host' : 'httpListener.host') ?? '127.0.0.1');
-    const port = Number(configManager.get(service === 'daemon' ? 'controlPlane.port' : 'httpListener.port') ?? (service === 'daemon' ? 3421 : 3422));
-    return {
-      mode: 'unavailable',
-      host,
-      port,
-      baseUrl: formatHostServiceBaseUrl(host, port),
-      reason: 'Background service startup has not completed yet',
-    };
-  };
-
-  const hostServiceIsActive = (status: HostServiceStatus): boolean => status.mode === 'embedded' || status.mode === 'external';
-
-  // 'blocked' (occupied by an unverified process) and 'incompatible' (occupied
-  // by a GoodVibes daemon we refused to adopt on a wire-version mismatch) both
-  // mean the configured port is held and unusable by this TUI instance.
-  const hostServiceIsBlocked = (status: HostServiceStatus): boolean => status.mode === 'blocked' || status.mode === 'incompatible';
-
-  // PERMANENT DESIGN (docs/decisions/2026-07-06-session-spine-mode-branch-is-permanent.md):
-  // 'embedded'/'external' are two distinct, both-supported daemon topologies, not
-  // migration stages — the ONE client-selection point for the session spine, driven by
-  // the SAME authoritative HostServiceMode adopt-or-start already computed above.
-  // 'embedded' (daemon.embedInProcess=true) means THIS process's own SharedSessionBroker
-  // already IS the daemon's broker — nothing to mirror TO, so the spine stays
-  // permanently dormant. Every other mode ('disabled'/'blocked'/'incompatible'/
-  // 'unavailable') also stays local-only and honest. Only 'external' (a separately-
-  // running daemon this TUI adopted) activates the wire mirror.
-  let spineActiveForBaseUrl: string | null = null;
-  // Same adoption signal drives the memory spine (WO memory-adopt) — see
-  // memory-spine-transport.ts. 'embedded' (this process hosts its own daemon)
-  // stays local: the daemon's canonical store IS this process's own
-  // memoryRegistry, so there is no wire hop to make.
-  const memorySpineActiveRef: MemorySpineActiveRef = { value: null };
-  const syncSessionSpineToHostStatus = (daemonStatus: HostServiceStatus, sharedDaemonToken: string): void => {
-    syncMemorySpineToHostStatus(services.memorySpine, daemonStatus.mode, daemonStatus.baseUrl, sharedDaemonToken, memorySpineActiveRef, logger);
-    if (daemonStatus.mode !== 'external') {
-      if (spineActiveForBaseUrl !== null) {
-        sessionSpine.deactivate(`daemon mode changed to '${daemonStatus.mode}'`);
-        sessionInboundInputs.deactivate(`daemon mode changed to '${daemonStatus.mode}'`);
-        spineActiveForBaseUrl = null;
-      }
-      // Keep the read facade honest per topology (permanent, not staged): 'embedded'
-      // means this process's broker IS the daemon's broker (local reads are the whole
-      // truth); every other non-external mode is local-only/dormant.
-      if (daemonStatus.mode === 'embedded') sessionUnionCache.markEmbedded();
-      else sessionUnionCache.deactivate(`daemon mode '${daemonStatus.mode}'`);
-      logger.info(`[bootstrap] session spine: daemon mode '${daemonStatus.mode}' — local-only (no spine mirror)`);
-      return;
-    }
-    const baseUrl = daemonStatus.baseUrl;
-    if (spineActiveForBaseUrl === baseUrl) return; // already wired to this exact adopted daemon
-    const httpTransport = createHttpTransport({ baseUrl, authToken: sharedDaemonToken });
-    const sessionsClient: SpineSessionsClient = {
-      register: (input) => httpTransport.operator.sessions.register(input),
-      close: (sessionId) => httpTransport.operator.sessions.close(sessionId),
-    };
-    sessionSpine.activate(createTuiSpineTransport(sessionsClient));
-    // Adopt the same daemon's wire for the INBOUND steer path — collect
-    // steer/follow-up inputs another live surface queued for this session and
-    // inject them into the turn machinery (acking delivery on the wire).
-    sessionInboundInputs.activate({
-      listInputs: async (sessionId, opts) => ({
-        inputs: await httpTransport.operator.sessions.inputs(sessionId, opts.limit, { state: opts.state, since: opts.since }),
-      }),
-      deliverInput: (sessionId, inputId, opts) => httpTransport.operator.sessions.deliverInput(sessionId, inputId, opts),
-    });
-    // 'external' only: adopt the same daemon's wire as the read facade's cross-surface
-    // union source (interval-refreshed; served synchronously to panels).
-    sessionUnionCache.activate({ list: (limit) => httpTransport.operator.sessions.list(limit) });
-    spineActiveForBaseUrl = baseUrl;
-    logger.info(`[bootstrap] session spine: adopted external daemon at ${baseUrl} — mirroring session identity`);
-    // Legacy fold: one-time (marker-guarded) import of this project's own
-    // pre-spine control-plane sessions.json into the now-adopted daemon.
-    const legacyStorePath = services.shellPaths.resolveProjectPath('tui', 'control-plane', 'sessions.json');
-    const fold = foldLegacySpineStore(sessionSpine, {
-      storePath: legacyStorePath,
-      markerPath: `${legacyStorePath}.spine-migrated`,
-      project: services.workingDirectory,
-    });
-    if (fold.folded > 0) {
-      logger.info(`[bootstrap] session spine: folded ${fold.folded} legacy local session(s) into the adopted daemon`);
-    }
-  };
+  // Adopting a daemon: session identity, the inbound steer path, the
+  // cross-surface union read, and the memory spine — see client/spine-adoption.ts.
+  const syncSessionSpineToHostStatus = createSpineAdoptionSync({
+    sessionSpine,
+    memorySpine: services.memorySpine,
+    sessionInboundInputs: sessionInboundInputs as unknown as Parameters<typeof createSpineAdoptionSync>[0]['sessionInboundInputs'],
+    sessionUnionCache: sessionUnionCache as unknown as Parameters<typeof createSpineAdoptionSync>[0]['sessionUnionCache'],
+    legacyStorePath: services.shellPaths.resolveProjectPath('tui', 'control-plane', 'sessions.json'),
+    workingDirectory: services.workingDirectory,
+    // Both ride adoption. A message submitted into a session this surface hosts
+    // must reach the loop here, because the loop is here; and a rewind driven
+    // from the web app or another terminal is answerable only by the process
+    // holding the messages, which is also here.
+    onAdopted: (client) => {
+      services.wireSessionDispatch.activate(client as never);
+      if (runtime.sessionId) services.conversationRewindHost.start(runtime.sessionId);
+    },
+    onDetached: (reason) => {
+      services.wireSessionDispatch.deactivate(reason);
+      void services.conversationRewindHost.stop();
+    },
+  });
 
   const inspectExternalServices = () => {
     const daemonStatus = externalServices.daemonStatus;
@@ -467,29 +393,61 @@ export async function bootstrapRuntime(
     };
   };
 
-  const waitForConfigDrivenRestarts = async (handle: ExternalServicesHandle): Promise<void> => {
-    const waitForRestart = async (service: unknown): Promise<void> => {
-      const maybeRestarting = service as { waitForRestart?: unknown } | null;
-      if (typeof maybeRestarting?.waitForRestart === 'function') {
-        await maybeRestarting.waitForRestart();
-      }
-    };
+  // ADOPT ONLY. This app never constructs a DaemonServer or an HttpListener: the
+  // daemon is a separate product with its own binary and its own service unit.
+  // The factories carry the shared bearer and the daemon's state directory so an
+  // adopted daemon is authenticated the same way it always was — no factory that
+  // BUILDS anything is passed, and `adoptOnly` makes the SDK refuse to start one
+  // even if a future caller did.
+  //
+  // `daemonRuntimeDir` names the daemon's own STATE directory
+  // (`<home>/.goodvibes/daemon`), which is where operator-tokens.json,
+  // auth-users.json and daemon-settings.json live — not the home above it. Every
+  // reader in this repository resolves it that way.
+  const createExternalServiceFactories = (token: string): ExternalServiceFactories => ({
+    sharedDaemonToken: token,
+    daemonRuntimeDir: join(services.homeDirectory, '.goodvibes', 'daemon'),
+    adoptOnly: true,
+  });
 
-    await Promise.all([
-      waitForRestart(handle.daemonServer),
-      waitForRestart(handle.httpListener),
-    ]);
+  // The one bounded recovery step: a daemon that is INSTALLED on this machine
+  // and simply stopped gets started once and waited for, rather than becoming
+  // the user's homework. Every boundary is in the SDK's client/daemon-autostart.ts.
+  const maybeStartInstalledDaemon = async (): Promise<void> => {
+    try {
+      const outcome = await autostartInstalledDaemon({
+        daemonMode: externalServices.daemonStatus.mode,
+        control: createDaemonServiceControl({
+          configManager,
+          workingDirectory: services.workingDirectory,
+          homeDirectory: services.homeDirectory,
+        }),
+        isReachable: async () => await sessionSpine.probeReachability() === 'online',
+      });
+      if (outcome.action === 'started' || outcome.action === 'came-online') {
+        const companionTokenRecord = resolveDaemonCompanionToken(join(services.homeDirectory, '.goodvibes', 'daemon'), GOODVIBES_TUI_SURFACE_ROOT);
+        externalServicesPromise = startExternalServices(
+          configManager, runtimeBus, hookDispatcher, services,
+          createExternalServiceFactories(companionTokenRecord.token),
+        );
+        externalServices = await externalServicesPromise;
+        await daemonHandshake.attach(companionTokenRecord.token);
+      }
+      const notice = describeDaemonAutostart(
+        outcome,
+        externalServices.daemonStatus.mode === 'external',
+        externalServices.daemonStatus.reason ?? externalServices.daemonStatus.mode,
+      );
+      if (notice) systemMessageRouter[notice.level](notice.text);
+    } catch (error) {
+      logger.debug('Boot-time daemon start check failed', { error: summarizeError(error) });
+    }
   };
 
-  // Embedded DaemonServer/HttpListener factories (incl. the facade auto-update
-  // suppression), plus the daemon STATE directory — see embedded-service-factories.ts.
-  const createExternalServiceFactories = (token: string): ExternalServiceFactories =>
-    createEmbeddedServiceFactories(token, services.clusterCoordinator, services.clusterGroup.verbs, join(services.homeDirectory, '.goodvibes', 'daemon'));
-
   let externalServices: ExternalServicesHandle = {
     daemonServer: null, httpListener: null,
-    daemonStatus: createPendingServiceStatus('daemon'),
-    httpListenerStatus: createPendingServiceStatus('httpListener'),
+    daemonStatus: createPendingServiceStatus(configManager, 'daemon'),
+    httpListenerStatus: createPendingServiceStatus(configManager, 'httpListener'),
     listRecentControlPlaneEvents: () => [],
     async stop(): Promise<void> {},
   };
@@ -498,11 +456,12 @@ export async function bootstrapRuntime(
     externalServices: NonNullable<typeof uiServices.platform.externalServices>;
   };
   platformExternalServices.externalServices = {
-    ...buildRelayExternalServiceMethods(() => externalServices.daemonServer),
+    // The relay is a DAEMON feature and reading an adopted daemon's relay state
+    // is a verb this contract does not carry, so these two report 'unavailable'
+    // rather than a state this process is in no position to know — see
+    // relay-reachability-bridge.ts.
+    ...relayReadAccessors,
     inspect: inspectExternalServices,
-    // Undelivered daemon receipts (update/crash/migration) for the attach-time
-    // consuming read; empty when no daemon runs. Marked delivered once served.
-    collectDaemonReceipts: () => (externalServices.daemonServer as { collectDaemonReceipts?: () => readonly { id: string; text: string; at: number }[] } | null)?.collectDaemonReceipts?.() ?? [],
     restart: async () => {
       if (externalServicesPromise) {
         try {
@@ -511,10 +470,9 @@ export async function bootstrapRuntime(
           // A failed previous startup should not prevent a restart attempt.
         }
       }
-      await waitForConfigDrivenRestarts(externalServices);
       await externalServices.stop();
       const daemonHomeDir = join(services.homeDirectory, '.goodvibes', 'daemon');
-      const companionTokenRecord = resolveDaemonCompanionToken(daemonHomeDir);
+      const companionTokenRecord = resolveDaemonCompanionToken(daemonHomeDir, GOODVIBES_TUI_SURFACE_ROOT);
       externalServicesPromise = startExternalServices(
         configManager,
         runtimeBus,
@@ -524,23 +482,39 @@ export async function bootstrapRuntime(
       );
       externalServices = await externalServicesPromise;
       controlPlaneRecentEventsRef.value = (limit) => externalServices.listRecentControlPlaneEvents(limit);
-      syncSessionSpineToHostStatus(externalServices.daemonStatus, companionTokenRecord.token);
-      await renderDaemonAttachNotices(companionTokenRecord.token);
+      await daemonHandshake.attach(companionTokenRecord.token);
       requestRender();
       return inspectExternalServices();
     },
   };
-  // The attach-time consuming read, exactly once as notices. An adopted EXTERNAL daemon has no in-process handle (daemonServer null), so read its own /status?receipts=consume over HTTP; the embedded daemon keeps the in-process fold.
-  const renderDaemonAttachNotices = async (daemonToken: string): Promise<void> => {
-    const daemonStatus = externalServices.daemonStatus;
-    const notices = daemonStatus.mode === 'external' && daemonStatus.baseUrl
-      ? await consumeExternalDaemonAttachNotices({ baseUrl: daemonStatus.baseUrl, authToken: daemonToken })
-      : consumeDaemonAttachNotices({ configManager, collectReceipts: () => platformExternalServices.externalServices.collectDaemonReceipts() });
-    for (const notice of notices) systemMessageRouter.high(`[Daemon] ${notice}`);
-  };
+  // Attaching to a daemon settles both build floors and its undelivered
+  // receipts off one /status read — see client/daemon-attach-handshake.ts.
+  const daemonHandshake = createDaemonAttachHandshake({
+    clientBuildGuard: services.clientBuildGuard,
+    readDaemonStatus: () => externalServices.daemonStatus,
+    recordRefusal: (status) => { externalServices = { ...externalServices, daemonStatus: status }; },
+    adopt: (status, daemonToken) => syncSessionSpineToHostStatus(status, daemonToken),
+    notify: (text) => { systemMessageRouter.high(`[Daemon] ${text}`); requestRender(); },
+  });
+  // A liveness flip is only PAINTED once something calls requestRender(); without
+  // this, the footer's spine segment sat correct-but-undrawn until incidental activity redrew it (minutes, during an idle stretch).
+  // The same flip is what tells the handshake a daemon came back.
+  sessionUnionCache.setOnTransition((online) => {
+    requestRender();
+    daemonHandshake.onLivenessTransition(online);
+  });
   deferredStartup.schedule({
     label: 'plugins',
     run: async () => {
+      // Plugin loading stays here: a plugin's commands, tools, providers, voice
+      // and media providers and embedding providers all reach things a turn
+      // needs in THIS process. Three of the eleven registries a plugin can
+      // reach are the daemon's now — gateway methods, channel plugins and
+      // delivery strategies — and a registration into those reaches nothing
+      // from here. No plugin is affected today (none is installed, and this
+      // package bundles none); the classification and the open question about
+      // where a daemon-side plugin is loaded are recorded in
+      // docs/decisions/2026-07-30-plugin-registrations-split-verb-side-and-surface-side.md.
       await pluginManager.init({
         runtimeBus,
         commandRegistry: pluginCommandRegistry,
@@ -570,9 +544,9 @@ export async function bootstrapRuntime(
     run: async () => {
       // Register the persistent companion-pairing token as the daemon's shared
       // bearer, so tokens scanned from the /qrcode panel's QR actually
-      // authenticate against the embedded daemon this surface starts.
+      // authenticate against the daemon this surface adopts.
       const daemonHomeDir = join(services.homeDirectory, '.goodvibes', 'daemon');
-      const companionTokenRecord = resolveDaemonCompanionToken(daemonHomeDir);
+      const companionTokenRecord = resolveDaemonCompanionToken(daemonHomeDir, GOODVIBES_TUI_SURFACE_ROOT);
       // Fix (TUI 0.19.20): remove stale pre-0.21.28 workspace-scoped operator
       // token files so only the canonical <daemonHomeDir>/operator-tokens.json survives.
       // The prune is best-effort — it silently skips missing files, no-ops when tokens
@@ -580,7 +554,7 @@ export async function bootstrapRuntime(
       // See `pruneStaleOperatorTokens` in the SDK for semantics.
       const prune = pruneStaleOperatorTokens({
         daemonHomeDir,
-        candidatePaths: workspaceOperatorTokenCandidates(services.workingDirectory),
+        candidatePaths: workspaceOperatorTokenCandidates(services.workingDirectory, GOODVIBES_TUI_SURFACE_ROOT),
       });
       if (prune.prunedPaths.length > 0) {
         logger.info(`[bootstrap] Pruned ${prune.prunedPaths.length} stale operator-token file(s): ${prune.prunedPaths.join(', ')}`);
@@ -596,13 +570,10 @@ export async function bootstrapRuntime(
         createExternalServiceFactories(companionTokenRecord.token),
       );
       externalServices = await externalServicesPromise;
-      // Join the coordination group even with no embedded daemon: the inbox
-      // poller is gated on leadership and nothing else would start it when
-      // daemon.enabled is false. Idempotent with the DaemonServer's own call.
-      await services.startCluster();
+      // Installed-but-stopped recovery, before anything reads the status.
+      await maybeStartInstalledDaemon();
       controlPlaneRecentEventsRef.value = (limit) => externalServices.listRecentControlPlaneEvents(limit);
-      syncSessionSpineToHostStatus(externalServices.daemonStatus, companionTokenRecord.token);
-      await renderDaemonAttachNotices(companionTokenRecord.token);
+      await daemonHandshake.attach(companionTokenRecord.token);
       requestRender();
     },
     onError: (error) => {
@@ -743,9 +714,9 @@ export async function bootstrapRuntime(
       // a no-op when the spine was never activated (embedded/local-only topology).
       sessionSpine.close(runtime.sessionId);
       sessionSpine.dispose();
-      sessionInboundInputs.dispose(); // stop the inbound steer poll interval on exit
-      sessionUnionCache.dispose(); // stop the wire-refresh interval on exit
-      await deferredStartup.drain(100);
+      sessionInboundInputs.dispose(); sessionUnionCache.dispose(); // stop the inbound-steer poll and the wire-refresh interval on exit
+      // Quitting has to SAY it is leaving: a hosted session's detach policy applies when the LAST client detaches, so an exit that never detaches leaves a kill-policy session (the shipped default) alive, attached to a process that is gone. Bounded and non-throwing — see client/hosted-exit.ts.
+      await Promise.all([leaveHostedSessionOnExit({ configManager, homeDirectory: services.homeDirectory }), deferredStartup.drain(100)]);
       if (externalServicesPromise) {
         try {
           externalServices = await externalServicesPromise;

package/src/runtime/client/approval-updates.ts

@@ -0,0 +1,82 @@
+/**
+ * approval-updates.ts — this terminal's subscription to approval decisions made
+ * somewhere else.
+ *
+ * ── What this replaces ────────────────────────────────────────────────────
+ *
+ * The SDK's client raiser (approval-raiser.ts) raises an ask on the daemon and
+ * prompts locally at the same time, and then has to learn about a decision made
+ * on another surface — a phone, the web UI, a second terminal. Without a push
+ * channel wired it learns by RE-READING the record on an interval, which is
+ * both slower than it needs to be and the thing the `control.approval_update`
+ * event exists to end. Wiring this seam makes a remote decision arrive in the
+ * time one frame takes.
+ *
+ * The interval is deliberately KEPT as the fallback, not removed: a terminal
+ * whose daemon refuses the stream (no daemon, a 401, a proxy that will not hold
+ * a connection) still has to be able to answer a tool call. `watchApprovalUpdates`
+ * reports failure by returning null rather than throwing, and the raiser then
+ * behaves exactly as it did before this seam existed. Push is the fast path, not
+ * a new dependency — and the raiser's own discipline of doing one immediate read
+ * after subscribing stays intact, because a decision can land between the raise
+ * and the subscription and no push channel can deliver what happened before it
+ * opened.
+ *
+ * ── Why the product owns this and the SDK does not ────────────────────────
+ *
+ * Resolving "which daemon" and proving this surface may subscribe to it are
+ * trust-boundary concerns the SDK core deliberately never reaches into (the
+ * same carve-out `DaemonVerbCaller` records). The resolution here is the one
+ * every other client seam in this repo uses: operator-endpoint.ts.
+ */
+import { watchApprovalUpdates } from '@pellux/goodvibes-sdk/platform/runtime/client';
+import type { ApprovalUpdateSubscriber } from '@pellux/goodvibes-sdk/platform/runtime/client';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { resolveDaemonEnabled } from '@pellux/goodvibes-sdk/platform/config';
+import { getOrCreateCompanionToken } from '@pellux/goodvibes-sdk/platform/pairing';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { resolveControlPlaneBaseUrl, resolveDaemonStateDirectory } from './operator-endpoint.ts';
+
+export interface TerminalApprovalUpdateSubscriberOptions {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string | (() => string);
+  /** Injectable fetch (tests, or a relay-tunnelled fetch). */
+  readonly fetchImpl?: typeof fetch | undefined;
+}
+
+/**
+ * Build the subscriber the SDK raiser takes.
+ *
+ * Every refusal is a null return, never a throw: this runs on the path that
+ * decides a tool call, and a subscription that cannot be opened must degrade to
+ * the interval rather than take the ask down with it.
+ */
+export function createTerminalApprovalUpdateSubscriber(
+  options: TerminalApprovalUpdateSubscriberOptions,
+): ApprovalUpdateSubscriber {
+  return async (onUpdate) => {
+    if (!resolveDaemonEnabled(options.configManager)) return null;
+    const baseUrl = resolveControlPlaneBaseUrl(options.configManager);
+    if (!baseUrl) return null;
+    let token: string;
+    try {
+      const homeDirectory = typeof options.homeDirectory === 'function'
+        ? options.homeDirectory()
+        : options.homeDirectory;
+      token = getOrCreateCompanionToken('tui', {
+        daemonHomeDir: resolveDaemonStateDirectory(homeDirectory),
+      }).token;
+    } catch (error) {
+      logger.debug('[approvals] no bearer token could be read for the approval-update stream', {
+        error: summarizeError(error),
+      });
+      return null;
+    }
+    return await watchApprovalUpdates({
+      baseUrl,
+      getAuthToken: () => token,
+      onUpdate,
+      ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+    });
+  };
+}