@pellux/goodvibes-tui 1.1.0 → 1.9.0

package/src/runtime/services.ts

@@ -1,11 +1,9 @@
 import { join } from 'node:path';
-import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { FocusTracker } from '../core/focus-tracker.ts';
+import { ConfigManager, ServiceRegistry, SubscriptionManager, ToolLLM } from '@pellux/goodvibes-sdk/platform/config';
 import { SecretsManager } from '../config/secrets.ts';
-import { ServiceRegistry } from '@pellux/goodvibes-sdk/platform/config';
-import { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config';
 import { AutomationDeliveryManager, AutomationManager, AutomationRouteStore } from '@pellux/goodvibes-sdk/platform/automation';
-import { ChannelPluginRegistry, ChannelPolicyManager, RouteBindingManager, SurfaceRegistry } from '@pellux/goodvibes-sdk/platform/channels';
-import { ChannelDeliveryRouter } from '@pellux/goodvibes-sdk/platform/channels';
+import { ChannelDeliveryRouter, ChannelPluginRegistry, ChannelPolicyManager, RouteBindingManager, SurfaceRegistry } from '@pellux/goodvibes-sdk/platform/channels';
 import { ApprovalBroker, GatewayMethodCatalog, SharedSessionBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
 import { WatcherRegistry } from '@pellux/goodvibes-sdk/platform/watchers';
 import { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
@@ -23,16 +21,10 @@ import {
 } from '@pellux/goodvibes-sdk/platform/knowledge';
 import { MediaProviderRegistry, ensureBuiltinMediaProviders } from '@pellux/goodvibes-sdk/platform/media';
 import { MultimodalService } from '@pellux/goodvibes-sdk/platform/multimodal';
-import { AgentManager } from '@pellux/goodvibes-sdk/platform/tools';
-import { AgentMessageBus } from '@pellux/goodvibes-sdk/platform/agents';
-import { WrfcController } from '@pellux/goodvibes-sdk/platform/agents';
-import { AgentOrchestrator } from '@pellux/goodvibes-sdk/platform/agents';
-import { ArchetypeLoader } from '@pellux/goodvibes-sdk/platform/agents';
-import { ProcessManager } from '@pellux/goodvibes-sdk/platform/tools';
-import { ModeManager } from '@pellux/goodvibes-sdk/platform/state';
-import { FileUndoManager } from '@pellux/goodvibes-sdk/platform/state';
-import { MemoryRegistry } from '@pellux/goodvibes-sdk/platform/state';
-import { MemoryStore } from '@pellux/goodvibes-sdk/platform/state';
+import { AgentMessageBus, AgentOrchestrator, ArchetypeLoader, WrfcController } from '@pellux/goodvibes-sdk/platform/agents';
+import { AgentManager, OverflowHandler, ProcessManager, createWorkflowServices, type WorkflowServices } from '@pellux/goodvibes-sdk/platform/tools';
+import { FileStateCache, FileUndoManager, MemoryEmbeddingProviderRegistry, MemoryRegistry, MemoryStore, ModeManager, ProjectIndex, resolveCanonicalMemoryDbPath, type CodeIndexStore, type CodeIndexReindexScheduler } from '@pellux/goodvibes-sdk/platform/state';
+import { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
 import type { RuntimeEventBus } from '@/runtime/index.ts';
 import { createDomainDispatch } from './store/index.ts';
 import type { DomainDispatch, RuntimeStore } from './store/index.ts';
@@ -41,40 +33,20 @@ import { RemoteRunnerRegistry, RemoteSupervisor } from '@/runtime/index.ts';
 import { IntegrationHelperService } from '@/runtime/index.ts';
 import { VoiceProviderRegistry, VoiceService, ensureBuiltinVoiceProviders } from '@pellux/goodvibes-sdk/platform/voice';
 import { WebSearchProviderRegistry, WebSearchService } from '@pellux/goodvibes-sdk/platform/web-search';
-import { MemoryEmbeddingProviderRegistry } from '@pellux/goodvibes-sdk/platform/state';
 import { PanelManager } from '../panels/panel-manager.ts';
 import { HookActivityTracker } from '@pellux/goodvibes-sdk/platform/hooks';
 import { HookDispatcher, createHookWorkbench, type HookWorkbench } from '@pellux/goodvibes-sdk/platform/hooks';
 import { PluginManager } from '@pellux/goodvibes-sdk/platform/plugins';
 import { BookmarkManager } from '@pellux/goodvibes-sdk/platform/bookmarks';
 import { ProfileManager } from '@pellux/goodvibes-sdk/platform/profiles';
-import { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
-import { CrossSessionTaskRegistry } from '@pellux/goodvibes-sdk/platform/sessions';
-import { ApiTokenAuditor } from '@pellux/goodvibes-sdk/platform/security';
-import { UserAuthManager } from '@pellux/goodvibes-sdk/platform/security';
+import { SessionManager, CrossSessionTaskRegistry, SessionChangeTracker } from '@pellux/goodvibes-sdk/platform/sessions';
+import { ApiTokenAuditor, UserAuthManager } from '@pellux/goodvibes-sdk/platform/security';
 import { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
 import { McpRegistry } from '@pellux/goodvibes-sdk/platform/mcp';
-import { DeterministicReplayEngine } from '@pellux/goodvibes-sdk/platform/core';
-import { ProviderOptimizer } from '@pellux/goodvibes-sdk/platform/providers';
-import { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
-import type { ModelDefinition } from '@pellux/goodvibes-sdk/platform/providers';
-import { ProviderCapabilityRegistry } from '@pellux/goodvibes-sdk/platform/providers';
-import { CacheHitTracker } from '@pellux/goodvibes-sdk/platform/providers';
-import { FavoritesStore } from '@pellux/goodvibes-sdk/platform/providers';
-import { BenchmarkStore } from '@pellux/goodvibes-sdk/platform/providers';
-import { ModelLimitsService } from '@pellux/goodvibes-sdk/platform/providers';
-import { inferFallbackContextWindow } from '@pellux/goodvibes-sdk/platform/providers';
+import { BenchmarkStore, CacheHitTracker, FavoritesStore, inferFallbackContextWindow, type ModelDefinition, ModelLimitsService, ProviderCapabilityRegistry, ProviderOptimizer, ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
 import { KeybindingsManager } from '../input/keybindings.ts';
-import { SessionMemoryStore } from '@pellux/goodvibes-sdk/platform/core';
-import { SessionLineageTracker } from '@pellux/goodvibes-sdk/platform/core';
-import { SessionChangeTracker } from '@pellux/goodvibes-sdk/platform/sessions';
-import { ExecutionPlanManager } from '@pellux/goodvibes-sdk/platform/core';
-import { AdaptivePlanner } from '@pellux/goodvibes-sdk/platform/core';
-import { FileStateCache } from '@pellux/goodvibes-sdk/platform/state';
-import { ProjectIndex } from '@pellux/goodvibes-sdk/platform/state';
+import { AdaptivePlanner, DeterministicReplayEngine, ExecutionPlanManager, SessionLineageTracker, SessionMemoryStore } from '@pellux/goodvibes-sdk/platform/core';
 import { IdempotencyStore } from '@/runtime/index.ts';
-import { OverflowHandler } from '@pellux/goodvibes-sdk/platform/tools';
-import { ToolLLM } from '@pellux/goodvibes-sdk/platform/config';
 import { ComponentHealthMonitor } from '@/runtime/index.ts';
 import { WorktreeRegistry } from '@/runtime/index.ts';
 import { SandboxSessionRegistry } from '@/runtime/index.ts';
@@ -83,10 +55,10 @@ import { isFeatureFlagEnabled } from './surface-feature-flags.ts';
 import type { FeatureFlagManager } from '@/runtime/index.ts';
 import { createFeatureFlagManager } from '@/runtime/index.ts';
 import { PolicyRuntimeState } from '@/runtime/index.ts';
-import {
-  createWorkflowServices,
-  type WorkflowServices,
-} from '@pellux/goodvibes-sdk/platform/tools';
+import { createProcessRegistry, type ProcessRegistry } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
+import { calcSessionCost, isModelPriced } from '../export/cost-utils.ts';
+import { createWorkstreamServices, type OrchestrationEngine, type WorkstreamCommandService } from './workstream-services.ts';
+import { codeIndexDbPath, createCodeIndexServices, isCodeInjectionSettingEnabled } from './code-index-services.ts';
 import { WorkPlanStore } from '../work-plans/work-plan-store.ts';
 import {
   registerDaemonHandlers,
@@ -221,6 +193,8 @@ export interface RuntimeServices {
   readonly worktreeRegistry: WorktreeRegistry;
   readonly sandboxSessionRegistry: SandboxSessionRegistry;
   readonly webhookNotifier: WebhookNotifier;
+  /** Terminal focus tracker (W2.3) — fed by input/handler-feed.ts, read by the alert notifiers in core/. */
+  readonly focusTracker: FocusTracker;
   readonly replayEngine: DeterministicReplayEngine;
   readonly providerOptimizer: ProviderOptimizer;
   readonly providerCapabilityRegistry: ProviderCapabilityRegistry;
@@ -248,8 +222,17 @@ export interface RuntimeServices {
   readonly agentOrchestrator: AgentOrchestrator;
   readonly wrfcController: WrfcController;
   readonly processManager: ProcessManager;
+  /** Wave 4 (wo703): the phase/work-item orchestration engine — see runtime/workstream-services.ts. */
+  readonly orchestrationEngine: OrchestrationEngine;
+  readonly workstreamCommands: WorkstreamCommandService;
+  /** Wave 5 (wo804): the repo source-tree code index — see runtime/code-index-services.ts. */
+  readonly codeIndexStore: CodeIndexStore;
+  readonly codeIndexReindexScheduler: CodeIndexReindexScheduler; // Wave-5 Stage B tool-site reindex
+  /** W2.1/W2.2: unified live process registry (agents, WRFC chains, workflows, watchers, background processes) backing the Fleet panel. */
+  readonly processRegistry: ProcessRegistry;
   readonly modeManager: ModeManager;
   readonly fileUndoManager: FileUndoManager;
+  readonly workspaceCheckpointManager: WorkspaceCheckpointManager;
   readonly integrationHelpers: IntegrationHelperService;
   /**
    * Re-root path-bound stores (MemoryStore, ProjectIndex) to a new working directory.
@@ -272,6 +255,9 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   const runtimeDispatch = createDomainDispatch(options.runtimeStore);
   const gatewayMethods = new GatewayMethodCatalog();
   const panelManager = new PanelManager();
+  // W6.1 (the purge): MIGRATE-TO-MODAL surface + redirect registration moved to
+  // registerBuiltinPanels (builtin-panels.ts), where the panels' resolved deps
+  // are available for the surfaces to close over.
   const keybindingsManager = new KeybindingsManager({
     configPath: shellPaths.resolveUserPath('tui', 'keybindings.json'),
   });
@@ -352,6 +338,10 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     executor: agentOrchestrator,
     configManager,
   });
+  agentOrchestrator.setConversationSink({ // Wave-3 Part C6 bridge (mirrors the SDK's own createRuntimeServices)
+    register: (agentId, source) => agentManager.registerConversationSource(agentId, source),
+    release: (agentId) => agentManager.releaseConversationSource(agentId),
+  });
   agentManager.setRuntimeBus(options.runtimeBus);
   const wrfcController = new WrfcController(options.runtimeBus, agentMessageBus, {
     agentManager,
@@ -397,7 +387,8 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   });
   const artifactStore = new ArtifactStore({ configManager });
   const memoryEmbeddingRegistry = new MemoryEmbeddingProviderRegistry({ configManager });
-  const memoryDbPath = join(workingDirectory, '.goodvibes', 'tui', 'memory.sqlite');
+  // W6-C2 (E6): open the ONE home-scoped canonical store; legacy per-project TUI memory folds in at boot (foldTuiLegacyMemory).
+  const memoryDbPath = resolveCanonicalMemoryDbPath(homeDirectory);
   const memoryStore = new MemoryStore(memoryDbPath, {
     embeddingRegistry: memoryEmbeddingRegistry,
   });
@@ -580,6 +571,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   const componentHealthMonitor = new ComponentHealthMonitor();
   const worktreeRegistry = new WorktreeRegistry(workingDirectory);
   const webhookNotifier = new WebhookNotifier();
+  const focusTracker = new FocusTracker();
   const replayEngine = new DeterministicReplayEngine(workingDirectory);
   const providerOptimizer = new ProviderOptimizer(
     providerRegistry,
@@ -603,8 +595,58 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     artifactStore,
   });
   const processManager = new ProcessManager();
+  // Wave 4 (wo703): the phase/work-item orchestration engine, constructed
+  // before the process registry so its fleet nodes (workstream/phase/
+  // work-item) can be folded in below via the registry's optional
+  // orchestrationEngine dep.
+  const { orchestrationEngine, workstreamCommands } = createWorkstreamServices({
+    agentManager, configManager, adaptivePlanner, runtimeBus: options.runtimeBus, projectRoot: workingDirectory,
+  });
+  // Wave 5 (wo804): repo source-tree code index, sharing memoryEmbeddingRegistry
+  // with MemoryStore above. Auto-build is config-gated (default off) — see
+  // code-index-services.ts's header doc.
+  const { codeIndexStore, codeIndexReindexScheduler } = createCodeIndexServices({ workingDirectory, configManager, memoryEmbeddingRegistry });
+  const codeInjectionOrchestratorDeps = { codeIndex: codeIndexStore, isCodeInjectionSettingEnabled: () => isCodeInjectionSettingEnabled(configManager), codeIndexReindexScheduler }; // Wave-5 Stage B seam (agent here; main via orchestrator-core-services.ts)
+  // W2.1/W2.2: one shared process registry aggregating the managers above —
+  // the Fleet panel (panels/fleet-read-model.ts) is its first consumer.
+  // Constructed once here (not per-consumer) so the coalesced tick and the
+  // agent-activity side-table are shared, not duplicated.
+  const processRegistry = createProcessRegistry({
+    agentManager,
+    wrfcController,
+    orchestrationEngine, // Wave 4 (wo703): folds workstream/phase/work-item nodes into the fleet
+    codeIndexService: codeIndexStore, // Wave 5 (wo804): folds a single 'code-index' node into the fleet
+    processManager,
+    watcherRegistry,
+    workflow,
+    approvalBroker,
+    sessionBroker,
+    messageBus: agentMessageBus, // Wave-3: backs steer()/`steerable` (wo612 builds the composer UI on top)
+    automationManager, // Wave 6 (wo-F item d4): folds /schedule AutomationJobs into the fleet as 'schedule' nodes
+    runtimeBus: options.runtimeBus,
+    // Honest pricing: never fabricate a cost for an unrecognized model.
+    priceUsage: (model, usage) => {
+      const modelId = model ?? 'unknown';
+      if (!isModelPriced(modelId)) return null;
+      return calcSessionCost(usage.inputTokens, usage.outputTokens, usage.cacheReadTokens, usage.cacheWriteTokens, modelId);
+    },
+  });
   const modeManager = new ModeManager();
   const fileUndoManager = new FileUndoManager();
+  const workspaceCheckpointManager = new WorkspaceCheckpointManager({
+    workspaceRoot: workingDirectory,
+    runtimeBus: options.runtimeBus,
+  });
+  // Fire-and-forget: subscriptions go live immediately if init() succeeds.
+  // If it rejects, WorkspaceCheckpointManager caches that rejection on
+  // `initPromise` and never clears it, so every later call (create/list/
+  // diff/restore — each awaits init() first) re-throws the same error
+  // forever: checkpointing becomes entirely unavailable for the rest of the
+  // session, not "degraded to manual-only". The `.catch(() => {})` here only
+  // exists to prevent an unhandled rejection at startup; the checkpoint
+  // commands (checkpoint-runtime.ts) are what actually catch and report the
+  // failure to the user, on first use.
+  void workspaceCheckpointManager.init().catch(() => {});
   const integrationHelpers = new IntegrationHelperService({
     workingDirectory,
     homeDirectory,
@@ -639,6 +681,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     remoteRunnerRegistry,
     knowledgeService,
     memoryRegistry,
+    ...codeInjectionOrchestratorDeps, // Wave-5 Stage B: agent-run code injection + tool-site reindex
     archetypeLoader,
     configManager,
     providerRegistry,
@@ -709,6 +752,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     worktreeRegistry,
     sandboxSessionRegistry,
     webhookNotifier,
+    focusTracker,
     replayEngine,
     providerOptimizer,
     providerCapabilityRegistry,
@@ -736,12 +780,20 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     agentOrchestrator,
     wrfcController,
     processManager,
+    orchestrationEngine,
+    workstreamCommands,
+    codeIndexStore,
+    codeIndexReindexScheduler,
+    processRegistry,
     modeManager,
     fileUndoManager,
+    workspaceCheckpointManager,
     integrationHelpers,
     async rerootStores(newWorkingDir: string): Promise<void> {
-      const newMemoryDbPath = join(newWorkingDir, '.goodvibes', 'tui', 'memory.sqlite');
-      await memoryStore.reroot(newMemoryDbPath);
+      // W6-C2 (E6): the memory store is the home-scoped canonical cross-surface store and
+      // deliberately does NOT reroot per-project (that would re-silo memory, the E6
+      // regression). Only working-tree-bound stores (code index, project index) reroot.
+      await codeIndexStore.reroot(newWorkingDir, codeIndexDbPath(newWorkingDir));
       await projectIndex.reroot(newWorkingDir);
     },
   };

package/src/runtime/session-inbound-inputs.ts

@@ -0,0 +1,252 @@
+/**
+ * session-inbound-inputs.ts
+ *
+ * D3 (One-Platform Wave 2, live-surface steer delivery — the inbound half of the
+ * session spine): the TUI's INBOUND path for steer/follow-up inputs that another
+ * live surface (e.g. the webui) queued against THIS TUI's session.
+ *
+ * Charter: when the owning surface is LIVE (heartbeating within the daemon's
+ * SURFACE_ROUTE_FRESHNESS window), a steer is DELIVERED to that surface rather
+ * than spawning a daemon-side executor (which would fail on the daemon's empty
+ * model registry). The daemon already does its half — `sessions.steer` /
+ * `sessions.followUp` to a surface-managed session with a fresh participant
+ * QUEUES the input for the surface (mode 'queued-for-surface') instead of
+ * spawning. This poller is the surface completing that contract:
+ *
+ *   1. poll `sessions.inputs.list` for QUEUED inputs on ITS OWN sessionId
+ *      (the query is scoped by sessionId, so a steer for another session can
+ *      never land here — the per-session isolation the concurrent-sessions
+ *      charter requires);
+ *   2. hand each steer/follow-up to `onSteer` (the surface-side injection into
+ *      the TUI's turn machinery — narrate "steer received from <surface>" and
+ *      fire the next-turn boundary), skipping the TUI's own submissions;
+ *   3. acknowledge on the wire via `sessions.inputs.deliver` (queued → delivered)
+ *      so every surface sees delivery truth live and the input is not re-picked.
+ *
+ * Discipline (mirrors SessionSpineClient): every wire call is best-effort and
+ * never throws into the render/keystroke path; a failed poll leaves the cursor
+ * where it was so the input is retried on the next tick (deliver is the only
+ * de-dup — an input already advanced past 'queued' is not returned again).
+ */
+
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type {
+  SharedSessionInputIntent,
+  SharedSessionInputRecord,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+
+/** The TUI's own participant surfaceId — inputs it authored are never re-injected. */
+export const TUI_SURFACE_ID = 'surface:tui';
+
+/** The narrow inbound wire surface this poller needs. Structurally satisfied by
+ * the http operator client's `sessions.inputs` (list + deliver). Typed against
+ * this shape rather than the concrete client so tests inject a stub. */
+export interface SpineInboundInputsClient {
+  listInputs(
+    sessionId: string,
+    options: { readonly state?: string; readonly since?: number; readonly limit?: number },
+  ): Promise<{ readonly inputs: readonly SharedSessionInputRecord[] }>;
+  deliverInput(
+    sessionId: string,
+    inputId: string,
+    options?: { readonly consumed?: boolean },
+  ): Promise<unknown>;
+}
+
+/** A steer/follow-up collected from the wire for surface-side injection. */
+export interface InboundSteer {
+  readonly inputId: string;
+  readonly sessionId: string;
+  readonly intent: SharedSessionInputIntent;
+  readonly body: string;
+  readonly surfaceKind: string | undefined;
+  readonly surfaceId: string | undefined;
+  readonly displayName: string | undefined;
+}
+
+type InboundLogger = Pick<typeof logger, 'debug' | 'info'>;
+
+export interface SessionInboundInputPollerOptions {
+  /** Returns the TUI's current live sessionId, or null when there is none yet.
+   * Read on every tick so a session swap re-targets the poll automatically. */
+  readonly sessionId: () => string | null;
+  /** Surface-side injection: narrate + deliver the steer into the turn machinery. */
+  readonly onSteer: (steer: InboundSteer) => void;
+  readonly intervalMs?: number;
+  readonly now?: () => number;
+  readonly log?: InboundLogger;
+  /** The poller's own surfaceId — inputs it authored are skipped (default TUI). */
+  readonly ownSurfaceId?: string;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 4_000;
+
+export class SessionInboundInputPoller {
+  private readonly sessionId: () => string | null;
+  private readonly onSteer: (steer: InboundSteer) => void;
+  private readonly intervalMs: number;
+  private readonly now: () => number;
+  private readonly log: InboundLogger;
+  private readonly ownSurfaceId: string;
+
+  private client: SpineInboundInputsClient | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private polling = false;
+  /** Exclusive createdAt cursor, per session — a session swap resets it. */
+  private cursor = 0;
+  private cursorSessionId: string | null = null;
+
+  constructor(options: SessionInboundInputPollerOptions) {
+    this.sessionId = options.sessionId;
+    this.onSteer = options.onSteer;
+    this.intervalMs = Math.max(250, options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    this.now = options.now ?? (() => Date.now());
+    this.log = options.log ?? logger;
+    this.ownSurfaceId = options.ownSurfaceId ?? TUI_SURFACE_ID;
+  }
+
+  /** Whether a backend is attached (external daemon adopted). */
+  get active(): boolean {
+    return this.client !== null;
+  }
+
+  /**
+   * Attach the wire client and begin polling (external daemon adopted). Idempotent:
+   * re-activating swaps the client without stacking timers.
+   */
+  activate(client: SpineInboundInputsClient): void {
+    this.client = client;
+    if (this.timer === null) {
+      this.timer = setInterval(() => { void this.pollOnce(); }, this.intervalMs);
+      this.timer.unref?.();
+    }
+    this.log.info('session inbound-input poller activated — collecting queued steers for this surface', {});
+  }
+
+  /** Detach the backend and stop polling (daemon mode resolved to non-external, or lost). */
+  deactivate(reason: string): void {
+    this.client = null;
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.log.info('session inbound-input poller deactivated', { reason });
+  }
+
+  /** Stop the timer (shutdown). */
+  dispose(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * One poll pass: collect queued steer/follow-up inputs for the current session,
+   * inject each, and acknowledge delivery. Returns the number of steers delivered.
+   * Best-effort: any wire error is absorbed and the pass is retried next tick.
+   */
+  async pollOnce(): Promise<number> {
+    const client = this.client;
+    if (!client || this.polling) return 0;
+    const sessionId = this.sessionId();
+    if (!sessionId) return 0;
+
+    // A session swap resets the cursor so we never skip the new session's backlog.
+    if (sessionId !== this.cursorSessionId) {
+      this.cursor = 0;
+      this.cursorSessionId = sessionId;
+    }
+
+    this.polling = true;
+    let delivered = 0;
+    try {
+      const result = await client.listInputs(sessionId, { state: 'queued', since: this.cursor });
+      const inputs = result?.inputs ?? [];
+      for (const input of inputs) {
+        // Advance the cursor across every queued input we observe (even skipped
+        // ones) so it is monotonic; deliver() is the real de-dup for injected ones.
+        if (input.createdAt > this.cursor) this.cursor = input.createdAt;
+
+        if (input.state !== 'queued') continue;
+        if (input.intent !== 'steer' && input.intent !== 'follow-up') continue;
+        // Never re-inject this surface's OWN submissions.
+        if (input.surfaceId === this.ownSurfaceId) continue;
+
+        const steer: InboundSteer = {
+          inputId: input.id,
+          sessionId,
+          intent: input.intent,
+          body: input.body,
+          surfaceKind: input.surfaceKind,
+          surfaceId: input.surfaceId,
+          displayName: input.displayName,
+        };
+        try {
+          this.onSteer(steer);
+        } catch (error) {
+          // A failing injection must not wedge the poll loop or drop the ack —
+          // narrate-and-continue; the input is still acked so it is not re-picked.
+          this.log.debug('session inbound steer injection threw — continuing', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+        try {
+          // consumed:false → queued → delivered (surface has collected it).
+          await client.deliverInput(sessionId, input.id, { consumed: false });
+          delivered += 1;
+        } catch (error) {
+          this.log.debug('session inbound deliver ack failed — will retry', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    } catch (error) {
+      // Poll failed entirely (daemon gone, transient): keep the cursor, retry next tick.
+      this.log.debug('session inbound-input poll failed — retry next tick', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      this.polling = false;
+    }
+    return delivered;
+  }
+}
+
+/** Format the operator-facing narration for an inbound steer, e.g.
+ * "steer received from webui (Alice): resize the panel". */
+export function narrateInboundSteer(steer: InboundSteer): string {
+  const surface = steer.surfaceKind ?? steer.surfaceId ?? 'another surface';
+  const who = steer.displayName ? ` (${steer.displayName})` : '';
+  const verb = steer.intent === 'follow-up' ? 'follow-up received from' : 'steer received from';
+  return `${verb} ${surface}${who}: ${steer.body}`;
+}
+
+/**
+ * Build the standard bootstrap-time poller: sessionId tracks the live runtime
+ * session ref, and onSteer narrates the steer to the operator then injects it
+ * via the SAME path COMPANION_MESSAGE_RECEIVED uses (orchestrator.handleUserInput
+ * when wired, else a bare conversation append + render request as a fallback
+ * before the orchestrator ref is patched). Extracted from bootstrap-core.ts to
+ * keep this module (not the bootstrap god-function) the owner of the wiring.
+ */
+export function createBootstrapInboundInputPoller(deps: {
+  readonly runtimeSessionIdRef: { readonly value: string };
+  readonly routeOrBuffer: (text: string, priority: 'low' | 'high') => void;
+  readonly orchestratorHandleUserInputRef: { readonly value: ((text: string) => void) | null };
+  readonly conversation: { readonly addUserMessage: (text: string) => void };
+  readonly requestRender: () => void;
+}): SessionInboundInputPoller {
+  return new SessionInboundInputPoller({
+    sessionId: () => deps.runtimeSessionIdRef.value || null,
+    onSteer: (steer) => {
+      deps.routeOrBuffer(narrateInboundSteer(steer), 'low');
+      if (deps.orchestratorHandleUserInputRef.value) {
+        deps.orchestratorHandleUserInputRef.value(steer.body);
+      } else {
+        deps.conversation.addUserMessage(steer.body);
+        deps.requestRender();
+      }
+    },
+  });
+}

package/src/runtime/session-spine-transport.ts

@@ -0,0 +1,64 @@
+/**
+ * session-spine-transport.ts
+ *
+ * W3-T1 (One-Platform Wave 3, TUI session-spine cutover): the thin typed-client
+ * adapter that lets the TUI's bootstrap drive the SDK's
+ * `@pellux/goodvibes-sdk/platform/runtime/session-spine` `SessionSpineClient`
+ * (extracted in W3-S4) via its injected `SpineTransport` seam.
+ *
+ * The TUI is SDK-clean here: `SpineSessionsClient` is exactly the narrow wire
+ * surface the old TUI-local `session-spine-client.ts` declared (structurally
+ * satisfied by `HttpTransport.operator.sessions`), and `createTuiSpineTransport`
+ * folds it into the SDK's `SpineTransport` the SAME way the SDK's own
+ * consumability proof (`session-spine-daemon-integration.test.ts`) does:
+ * resolve -> `'ok'`, throw -> `'offline'`. The TUI never emits `'rejected'` — it
+ * has no durable-refusal vocabulary to fold (that distinction is the agent's
+ * REST mirror's job, per the SDK's divergence ruling #6/#7).
+ */
+import type {
+  RegisterSharedSessionInput,
+  SharedSessionRecord,
+  SharedSessionRegisterResult,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { SpineResult, SpineTransport } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
+
+/**
+ * The minimal wire surface this adapter needs. Structurally satisfied by BOTH
+ * the SDK's in-process `OperatorClient['sessions']` (DirectTransport) and the
+ * wire `HttpTransportOperatorClient['sessions']` (HttpTransport) — bootstrap.ts
+ * only ever constructs an Http-backed instance in practice, but this is
+ * deliberately typed against the narrow shape rather than either concrete
+ * transport type so it has no compile-time dependency on which transport
+ * backs it.
+ */
+export interface SpineSessionsClient {
+  register(input: RegisterSharedSessionInput): Promise<SharedSessionRegisterResult>;
+  close(sessionId: string): Promise<SharedSessionRecord | null>;
+}
+
+/**
+ * Adapt the TUI's typed `SpineSessionsClient` into the SDK `SessionSpineClient`'s
+ * injected `SpineTransport`. A rejecting wire call is treated as a transient
+ * connectivity fault (`'offline'`) rather than a durable refusal — the same
+ * binary reachability model the pre-extraction TUI-local client used.
+ */
+export function createTuiSpineTransport(sessionsClient: SpineSessionsClient): SpineTransport {
+  return {
+    register: async (input: RegisterSharedSessionInput): Promise<SpineResult> => {
+      try {
+        await sessionsClient.register(input);
+        return { outcome: 'ok' };
+      } catch (error) {
+        return { outcome: 'offline', error: error instanceof Error ? error.message : String(error) };
+      }
+    },
+    close: async (sessionId: string): Promise<SpineResult> => {
+      try {
+        await sessionsClient.close(sessionId);
+        return { outcome: 'ok' };
+      } catch (error) {
+        return { outcome: 'offline', error: error instanceof Error ? error.message : String(error) };
+      }
+    },
+  };
+}

package/src/runtime/terminal-output-guard.ts

@@ -40,7 +40,14 @@ export type TuiTerminalOutputGuardOptions = {
   readonly stdout: WritableStreamLike;
   readonly stderr?: WritableStreamLike;
   readonly active?: boolean;
-  readonly notify: (message: string) => void;
+  /**
+   * Called (rate-limited) after intercepts with the cumulative count of direct
+   * writes captured this session, so an honest quiet counter (e.g. /debug) can
+   * refresh. The per-write detail is already recorded to the activity log via
+   * logger.warn — this callback intentionally does NOT push transcript lines.
+   * (UX-B item 1a.)
+   */
+  readonly onCapture?: (total: number) => void;
 };
 
 const MAX_LOG_TEXT = 4_000;
@@ -208,21 +215,21 @@ export function installTerminalOutputGuard(options: TerminalOutputGuardOptions):
 }
 
 export function installTuiTerminalOutputGuard(options: TuiTerminalOutputGuardOptions): TerminalOutputGuard {
-  let capturedWriteCount = 0;
+  let totalInterceptedWrites = 0;
   let lastNoticeAt = 0;
   return installTerminalOutputGuard({
     stdout: options.stdout,
     stderr: options.stderr,
     active: options.active,
-    onIntercept: (event) => {
-      capturedWriteCount++;
+    onIntercept: () => {
+      // Each intercept is already logged (logger.warn in record()). Here we only
+      // maintain a cumulative counter and, rate-limited, refresh a quiet counter
+      // surface — no repeated transcript lines. (UX-B item 1a.)
+      totalInterceptedWrites++;
       const now = Date.now();
       if (now - lastNoticeAt < 5_000) return;
-      const count = capturedWriteCount;
-      capturedWriteCount = 0;
       lastNoticeAt = now;
-      const plural = count === 1 ? '' : 's';
-      options.notify(`[Terminal] Captured ${count} direct ${event.source} write${plural} that would have corrupted the TUI: ${event.preview}`);
+      options.onCapture?.(totalInterceptedWrites);
     },
   });
 }