@pellux/goodvibes-agent 1.5.5 → 1.5.6

package/src/runtime/lan-scan-consent.ts

@@ -0,0 +1,253 @@
+/**
+ * LAN-scan consent gate (Wave-4 A7).
+ *
+ * The SDK's background provider-discovery pass (`startBackgroundProviderDiscovery`
+ * in `@pellux/goodvibes-sdk/platform/runtime`) probes every host on this
+ * computer's local subnet (254 addresses per non-internal network interface)
+ * looking for local model servers such as Ollama or LM Studio, then dumps one
+ * raw "[Scan] Found <name> at <host>:<port>" line per server straight into the
+ * activity feed. It ran unconditionally, with no consent step, and no way to
+ * turn it off.
+ *
+ * This module is the only place in the Agent that is allowed to call the SDK
+ * discovery entry point. It:
+ *   1. Gates the call behind a persisted, explicit consent decision. The very
+ *      first time the Agent starts, nothing is scanned; the user is told what
+ *      the feature does, what it touches (the local subnet — nothing beyond
+ *      it), and what it stores, then the decision defaults to "off" until the
+ *      user turns it on.
+ *   2. Reframes whatever the SDK emits when consent has been granted: instead
+ *      of one raw host:port line per server, the Agent surfaces a single
+ *      framed summary ("Discovered N local model servers ..."), with full
+ *      detail available on demand via /provider.
+ *
+ * The SDK scanner itself is not modified — see
+ * node_modules/@pellux/goodvibes-sdk/dist/platform/discovery/scanner.js and
+ * node_modules/@pellux/goodvibes-sdk/dist/platform/runtime/bootstrap-background.js.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import {
+  startBackgroundProviderRegistration,
+  type BackgroundProviderDiscoveryOptions,
+  type BackgroundRuntimeTaskHandle,
+  type HostSystemMessageSink,
+  type ShellPathService,
+} from '@/runtime/index.ts';
+
+export type LanScanDecision = 'granted' | 'declined';
+
+export interface LanScanConsentState {
+  readonly decision: LanScanDecision;
+  readonly decidedAt: string;
+}
+
+type ConsentRoots = Pick<ShellPathService, 'resolveUserPath'>;
+
+const CONSENT_FILE_NAME = 'network-discovery-consent.json';
+const DISCOVERED_PROVIDERS_FILE = 'discovered-providers.json';
+
+function consentFilePath(roots: ConsentRoots, surfaceRoot: string): string {
+  return roots.resolveUserPath(surfaceRoot, CONSENT_FILE_NAME);
+}
+
+/**
+ * The path the SDK persists discovered servers to, for display in user-facing
+ * copy (this module does not read or write that file — the SDK owns it).
+ */
+export function discoveredProvidersFilePath(roots: ConsentRoots, surfaceRoot: string): string {
+  return roots.resolveUserPath(surfaceRoot, DISCOVERED_PROVIDERS_FILE);
+}
+
+/**
+ * Load the persisted LAN-scan consent decision.
+ * Returns undefined when no decision has ever been recorded (true first run).
+ */
+export function loadLanScanConsent(roots: ConsentRoots, surfaceRoot: string): LanScanConsentState | undefined {
+  const path = consentFilePath(roots, surfaceRoot);
+  try {
+    if (!existsSync(path)) return undefined;
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<LanScanConsentState> | null;
+    if (!parsed || (parsed.decision !== 'granted' && parsed.decision !== 'declined')) {
+      logger.warn('[LanScanConsent] ignoring invalid consent file', { path });
+      return undefined;
+    }
+    return {
+      decision: parsed.decision,
+      decidedAt: typeof parsed.decidedAt === 'string' ? parsed.decidedAt : new Date(0).toISOString(),
+    };
+  } catch (err) {
+    logger.warn('[LanScanConsent] load failed; treating as undecided', { path, error: summarizeError(err) });
+    return undefined;
+  }
+}
+
+/** Persist the user's LAN-scan consent decision (explicit grant, decline, or the first-run default). */
+export function saveLanScanConsent(roots: ConsentRoots, surfaceRoot: string, decision: LanScanDecision): void {
+  const path = consentFilePath(roots, surfaceRoot);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const state: LanScanConsentState = { decision, decidedAt: new Date().toISOString() };
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+  } catch (err) {
+    logger.warn('[LanScanConsent] save failed; decision will not persist', { path, error: summarizeError(err) });
+  }
+}
+
+// ── Wording ──────────────────────────────────────────────────────────────
+
+export const NETWORK_SCAN_ENABLE_COMMAND = '/network-scan on';
+export const NETWORK_SCAN_DISABLE_COMMAND = '/network-scan off';
+export const NETWORK_SCAN_STATUS_COMMAND = '/network-scan';
+
+/** Shown exactly once — the very first time the Agent starts and no decision has been recorded yet. */
+export function firstRunConsentMessage(roots: ConsentRoots, surfaceRoot: string): string {
+  const storePath = discoveredProvidersFilePath(roots, surfaceRoot);
+  return (
+    '[Scan] Local network scanning for model servers is off by default. ' +
+    'If turned on, it checks other devices on this computer\'s local network (your subnet only — nothing beyond it) ' +
+    'for model servers such as Ollama or LM Studio, so they can be added as chat providers. ' +
+    `Servers it finds are saved to ${storePath}. ` +
+    `Turn it on with ${NETWORK_SCAN_ENABLE_COMMAND}; nothing is scanned until you do.`
+  );
+}
+
+/**
+ * F3 fix: the first-run explanation (firstRunConsentMessage) already told the
+ * user this is off and how to turn it on. Printing that reminder again on
+ * EVERY subsequent boot forever — with no way to quiet it short of turning
+ * the feature on — was the friction: an indefinitely repeating notice for a
+ * state the user already chose. The off state is still fully discoverable on
+ * demand via `/network-scan status`; boot itself stays silent about it from
+ * the second run onward. The granted-path behavior (framed scan summary) is
+ * unchanged.
+ */
+
+// ── Output framing ───────────────────────────────────────────────────────
+
+const FOUND_OR_RESTORED_RE = /\bat\s+\S+:\d+\s+\(\d+\s+models?\)/;
+const REMOVED_RE = /\bat\s+\S+:\d+\s+is no longer reachable\b/;
+const RAW_IP_PAREN_RE = /\s*\(\d{1,3}(?:\.\d{1,3}){3}\)/g;
+
+/** Strips a bare "(1.2.3.4)" parenthetical from an otherwise-fine message, defense in depth. */
+function stripRawIpMention(message: string): string {
+  return message.replace(RAW_IP_PAREN_RE, '');
+}
+
+/**
+ * Wraps the real system-message sink + requestRender callback so that the raw
+ * per-server "[Scan] Found X at host:port" / "[Local] X at host:port ... from
+ * last session" / "[Scan] X at host:port is no longer reachable" lines the SDK
+ * emits are never forwarded verbatim. Instead they are counted, and a single
+ * framed summary line is emitted the next time requestRender fires — which the
+ * SDK reliably calls exactly once per batch of emitted messages (see
+ * bootstrap-background.js), so this stays in lockstep with the underlying
+ * scan/restore passes without needing to touch the SDK.
+ */
+function createFramedDiscoverySink(
+  realRouter: HostSystemMessageSink,
+  realRequestRender: () => void,
+): { readonly sink: HostSystemMessageSink; readonly requestRender: () => void } {
+  let foundCount = 0;
+  let removedCount = 0;
+
+  const sink: HostSystemMessageSink = {
+    low(message: string) {
+      if (FOUND_OR_RESTORED_RE.test(message)) {
+        foundCount += 1;
+        return;
+      }
+      if (REMOVED_RE.test(message)) {
+        removedCount += 1;
+        return;
+      }
+      realRouter.low(stripRawIpMention(message));
+    },
+    high(message: string) {
+      realRouter.high(stripRawIpMention(message));
+    },
+  };
+
+  const requestRender = () => {
+    if (foundCount > 0) {
+      realRouter.low(
+        `[Scan] Discovered ${foundCount} local model server${foundCount === 1 ? '' : 's'} on this network — run /provider to see them.`,
+      );
+    }
+    if (removedCount > 0) {
+      realRouter.low(
+        `[Scan] ${removedCount} previously found server${removedCount === 1 ? '' : 's'} no longer reachable — removed.`,
+      );
+    }
+    foundCount = 0;
+    removedCount = 0;
+    realRequestRender();
+  };
+
+  return { sink, requestRender };
+}
+
+function noopHandle(): BackgroundRuntimeTaskHandle {
+  let stopped = false;
+  return {
+    get stopped() {
+      return stopped;
+    },
+    stop() {
+      stopped = true;
+    },
+  };
+}
+
+export interface LanScanGateOptions extends BackgroundProviderDiscoveryOptions {
+  readonly shellPaths: BackgroundProviderDiscoveryOptions['shellPaths'] & ConsentRoots;
+  /**
+   * Injectable seam for tests. Defaults to the real SDK discovery pass
+   * (`startBackgroundProviderRegistration`, which performs a real subnet
+   * scan). Tests must supply a fake here instead of exercising the real
+   * network — never let a test fall through to the default.
+   */
+  readonly startDiscovery?: (opts: BackgroundProviderDiscoveryOptions) => BackgroundRuntimeTaskHandle;
+}
+
+/**
+ * The single gated entry point to LAN provider discovery. Bootstrap's Phase 8
+ * and the /network-scan command are the only two callers; neither calls the
+ * SDK's startBackgroundProviderRegistration/startBackgroundProviderDiscovery
+ * directly.
+ *
+ * - No decision recorded (first run): shows the full consent explanation,
+ *   persists "declined" as the honest first-run default, and returns without
+ *   scanning.
+ * - Decision is "declined" (F3): stays silent and returns without scanning —
+ *   the first-run boot already explained the off state and how to turn it
+ *   on; the ongoing state is discoverable on demand via `/network-scan
+ *   status`, not repeated on every boot.
+ * - Decision is "granted": runs the SDK discovery pass through a framing
+ *   wrapper that replaces the raw per-server feed dump with a single summary
+ *   line.
+ */
+export function runGatedLanScan(options: LanScanGateOptions): BackgroundRuntimeTaskHandle {
+  const { shellPaths, surfaceRoot, systemMessageRouter, requestRender, startDiscovery = startBackgroundProviderRegistration } = options;
+  const existing = loadLanScanConsent(shellPaths, surfaceRoot);
+
+  if (!existing) {
+    saveLanScanConsent(shellPaths, surfaceRoot, 'declined');
+    systemMessageRouter.low(firstRunConsentMessage(shellPaths, surfaceRoot));
+    return noopHandle();
+  }
+
+  if (existing.decision === 'declined') {
+    return noopHandle();
+  }
+
+  const framed = createFramedDiscoverySink(systemMessageRouter, requestRender);
+  return startDiscovery({
+    ...options,
+    systemMessageRouter: framed.sink,
+    requestRender: framed.requestRender,
+  });
+}

package/src/runtime/services.ts

@@ -3,6 +3,7 @@ import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { shell as runtimeShell } from '@pellux/goodvibes-sdk/platform/runtime';
 import type { shell as RuntimeShell } from '@pellux/goodvibes-sdk/platform/runtime';
 import { SecretsManager } from '../config/secrets.ts';
+import { FocusTracker } from '../core/focus-tracker.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';
@@ -10,6 +11,13 @@ import { ChannelPluginRegistry, ChannelPolicyManager, RouteBindingManager, Surfa
 import { ChannelDeliveryRouter } from '@pellux/goodvibes-sdk/platform/channels';
 import { ApprovalBroker, GatewayMethodCatalog, SharedSessionBroker } from '@pellux/goodvibes-sdk/platform/control-plane';
 import type { SharedSessionRoutingIntent } from '@pellux/goodvibes-sdk/platform/control-plane';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { AGENT_SPINE_PARTICIPANT, SessionSpineClient } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
+import {
+  createSpineConnectionResolver,
+  createSpineRestProbe,
+  createSpineRestTransport,
+} from './session-spine-rest-transport.ts';
 import { WatcherRegistry } from '@pellux/goodvibes-sdk/platform/watchers';
 import { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
 import {
@@ -32,11 +40,19 @@ 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 { CodeIndexStore } from '@pellux/goodvibes-sdk/platform/state';
+import { CodeIndexReindexScheduler } from '@pellux/goodvibes-sdk/platform/state';
+import { createProcessRegistry } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
+import { createOrchestrationEngine } from '@pellux/goodvibes-sdk/platform/orchestration';
+import { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
 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';
+// W6-C2 (E6): one canonical cross-surface memory store + no-loss legacy fold.
+import { resolveCanonicalMemoryDbPath, foldMemoryStores } from '@pellux/goodvibes-sdk/platform/state';
+import type { LegacyMemorySource, MemoryFoldReport } from '@pellux/goodvibes-sdk/platform/state';
 import type { RuntimeEventBus } from '@/runtime/index.ts';
 import { createDomainDispatch } from './store/index.ts';
 import type { DomainDispatch, RuntimeStore } from './store/index.ts';
@@ -228,7 +244,11 @@ function createDisabledAgentWrfcWorktreeOps(): AgentWrfcWorktreeOps {
     async cleanup(_agentId: string): Promise<void> {
       throw agentWrfcWorktreeError('cleanup');
     },
-    async commitWorkingTree(_message: string): Promise<string | null> {
+    // No explicit return-type annotation: this always throws before returning,
+    // so it structurally satisfies whatever CommitWorkingTreeResult shape the
+    // SDK's WrfcController#createWorktree option currently declares (derived
+    // via AgentWrfcWorktreeOps above) without importing that SDK-internal type.
+    async commitWorkingTree(_message: string) {
       throw agentWrfcWorktreeError('commit');
     },
     async currentHead(): Promise<string | null> {
@@ -395,6 +415,7 @@ export interface RuntimeServices extends SdkRuntimeServices {
   readonly watcherRegistry: WatcherRegistry;
   readonly approvalBroker: ApprovalBroker;
   readonly sessionBroker: SharedSessionBroker;
+  readonly sessionSpineClient: SessionSpineClient;
   readonly deliveryManager: AutomationDeliveryManager;
   readonly automationManager: AutomationManager;
   readonly gatewayMethods: GatewayMethodCatalog;
@@ -435,6 +456,8 @@ export interface RuntimeServices extends SdkRuntimeServices {
   readonly worktreeRegistry: WorktreeRegistry;
   readonly sandboxSessionRegistry: SandboxSessionRegistry;
   readonly webhookNotifier: WebhookNotifier;
+  /** W4-R3 — OS-level terminal focus tracker, ported from goodvibes-tui's W2.3 (core/focus-tracker.ts). */
+  readonly focusTracker: FocusTracker;
   readonly replayEngine: DeterministicReplayEngine;
   readonly providerOptimizer: ProviderOptimizer;
   readonly providerCapabilityRegistry: ProviderCapabilityRegistry;
@@ -590,6 +613,21 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     agentStatusProvider: agentManager,
     messageSender: agentMessageBus,
   });
+  // W3-A1: the SDK's extracted session-spine core, consumed via this surface's
+  // own REST transport adapter (session-spine-rest-transport.ts) — version-
+  // tolerant, since the agent may compile against a pinned SDK predating the
+  // typed sessions.register client. Live-immediately mode: passing `transport`
+  // at construction starts the keepalive now, for the whole process lifetime
+  // (no separate activate() step — the agent has none). Client-only; never
+  // starts the daemon. All calls are fire-and-forget; a down daemon degrades to
+  // an honest offline queue while the local broker keeps rendering.
+  const spineResolveConnection = createSpineConnectionResolver(configManager, homeDirectory);
+  const sessionSpineClient = new SessionSpineClient({
+    participant: AGENT_SPINE_PARTICIPANT,
+    transport: createSpineRestTransport({ resolveConnection: spineResolveConnection }),
+    probe: createSpineRestProbe({ resolveConnection: spineResolveConnection }),
+    log: logger,
+  });
   sessionBroker.setContinuationRunner(async ({ task, input }) => {
     const record = agentManager.spawn({
       mode: 'spawn',
@@ -601,7 +639,11 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   });
   const artifactStore = new ArtifactStore({ configManager });
   const memoryEmbeddingRegistry = new MemoryEmbeddingProviderRegistry({ configManager });
-  const memoryDbPath = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'memory.sqlite');
+  // W6-C2 (E6): the agent no longer owns a private per-surface memory.sqlite. It opens
+  // the ONE canonical cross-surface store so a fact learned here recalls in the TUI (and
+  // vice-versa). The old agent-global path is folded in at boot with no loss (see
+  // foldAgentLegacyMemory), then left in place — migration never deletes.
+  const memoryDbPath = resolveCanonicalMemoryDbPath(shellPaths.homeDirectory);
   const memoryStore = new MemoryStore(memoryDbPath, {
     embeddingRegistry: memoryEmbeddingRegistry,
   });
@@ -737,6 +779,10 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   const worktreeRegistry = createDisabledAgentWorktreeRegistry(workingDirectory);
   // Configured and attached to the runtime bus during bootstrap when webhook URLs are present.
   const webhookNotifier = new WebhookNotifier();
+  // W4-R3 — one shared instance for the process lifetime (mirrors goodvibes-tui's
+  // runtime/services.ts); fed from 'focus' tokens in handler-feed.ts and read by
+  // the approval-alert wiring in main.ts.
+  const focusTracker = new FocusTracker();
   const replayEngine = new DeterministicReplayEngine(workingDirectory);
   const providerOptimizer = new ProviderOptimizer(providerRegistry, providerCapabilityRegistry, false);
   const sessionMemoryStore = new SessionMemoryStore();
@@ -820,12 +866,70 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     workflowServices: workflow,
   });
 
+  // ── One-Platform Wave 0: RuntimeServices members required by SDK 0.38 ──────
+  // The Agent is delegation-only: it does not own local build/worktree work.
+  // These are constructed as real-but-inert SDK services purely to satisfy the
+  // RuntimeServices contract — none auto-start:
+  //   • orchestrationEngine  — never .start()ed here (delegation goes through
+  //                            /delegate to the TUI); worktree isolation is
+  //                            omitted so any accidental run degrades to shared.
+  //   • codeIndexStore       — constructed but neither schema-initialized nor
+  //                            auto-built; the Agent runs no repo source-tree
+  //                            code index (inert unless explicitly invoked).
+  //   • codeIndexReindexScheduler — real-but-inert twin of the above: isEnabled
+  //                            is a permanent `() => false`, so tool-driven
+  //                            reindex scheduling (Stage B, TUI-only feature)
+  //                            never fires for the Agent.
+  //   • processRegistry      — fleet observability over the managers the Agent
+  //                            already owns (agents, wrfc, processes, watchers).
+  //   • workspaceCheckpointManager — constructed without a runtimeBus so it
+  //                            never auto-subscribes to turn events / snapshots
+  //                            the workspace; inert unless explicitly invoked.
+  const orchestrationEngine = createOrchestrationEngine({
+    agentManager,
+    configManager,
+    runtimeBus: options.runtimeBus,
+    projectRoot: workingDirectory,
+  });
+  const codeIndexStore = new CodeIndexStore(
+    workingDirectory,
+    join(workingDirectory, '.goodvibes', 'agent', 'code-index.sqlite'),
+    memoryEmbeddingRegistry,
+  );
+  const codeIndexReindexScheduler = new CodeIndexReindexScheduler({
+    target: codeIndexStore,
+    workingDirectory,
+    isEnabled: () => false,
+  });
+  const processRegistry = createProcessRegistry({
+    agentManager,
+    wrfcController,
+    orchestrationEngine,
+    codeIndexService: codeIndexStore,
+    processManager,
+    watcherRegistry,
+    workflow,
+    approvalBroker,
+    sessionBroker,
+    messageBus: agentMessageBus,
+    automationManager,
+    runtimeBus: options.runtimeBus,
+  });
+  const workspaceCheckpointManager = new WorkspaceCheckpointManager({
+    workspaceRoot: workingDirectory,
+  });
+
   return {
     workingDirectory,
     homeDirectory,
     shellPaths,
     configManager,
     featureFlags,
+    orchestrationEngine,
+    codeIndexStore,
+    codeIndexReindexScheduler,
+    processRegistry,
+    workspaceCheckpointManager,
     runtimeBus: options.runtimeBus,
     runtimeStore: options.runtimeStore,
     runtimeDispatch,
@@ -838,6 +942,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     watcherRegistry,
     approvalBroker,
     sessionBroker,
+    sessionSpineClient,
     deliveryManager,
     automationManager,
     gatewayMethods,
@@ -877,6 +982,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     worktreeRegistry,
     sandboxSessionRegistry,
     webhookNotifier,
+    focusTracker,
     replayEngine,
     providerOptimizer,
     providerCapabilityRegistry,
@@ -912,3 +1018,22 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     },
   };
 }
+
+/**
+ * W6-C2 (E6): fold the agent's legacy per-surface memory store into the canonical
+ * cross-surface store. Called once at boot AFTER `memoryStore.init()` so any records
+ * written before unification survive. Id-keyed and idempotent — a re-run imports
+ * nothing new and never deletes the legacy file. Returns the report so boot can log
+ * exactly what moved (nothing is silently dropped).
+ */
+export async function foldAgentLegacyMemory(
+  memoryStore: MemoryStore,
+  memoryEmbeddingRegistry: MemoryEmbeddingProviderRegistry,
+  shellPaths: ShellPathService,
+): Promise<MemoryFoldReport> {
+  const legacyAgentGlobal = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'memory.sqlite');
+  const sources: LegacyMemorySource[] = [
+    { label: 'agent-global (pre-E6)', dbPath: legacyAgentGlobal },
+  ];
+  return foldMemoryStores(memoryStore, sources, { embeddingRegistry: memoryEmbeddingRegistry });
+}

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

@@ -0,0 +1,160 @@
+/**
+ * session-spine-rest-transport.ts
+ *
+ * The agent's REST transport adapter for the SDK's extracted session-spine core
+ * (`@pellux/goodvibes-sdk/platform/runtime/session-spine`). The core is
+ * transport-agnostic and never assumes a typed sessions client exists — that is
+ * exactly why the agent, which compiles against a pinned/version-tolerant npm
+ * SDK that may predate `sessions.register`, supplies this hand-rolled REST
+ * mirror instead of a typed client (see
+ * docs/decisions/2026-07-05-session-spine-sdk-extraction.md, divergence ruling
+ * #1). Do not switch this adapter to a typed client.
+ *
+ * Also agent-local (per the same decision record, ruling #6 and the SDK-side
+ * rejection of "pulling token-reading into the SDK"):
+ *  - `createSpineConnectionResolver`: builds the daemon base URL from
+ *    ConfigManager and reads the connected-host operator token via
+ *    ../runtime/connected-host-auth.ts (home-dir-specific, trust-boundary-bound
+ *    — the SDK core never reads token files; it only ever receives a
+ *    pre-built resolver through this adapter).
+ *  - register/close/probe TIMEOUTS: the SDK core no longer makes the wire
+ *    call (transport does), so it has nothing to time out. Timeouts are a REST
+ *    implementation concern and live here, in the adapter that owns fetch.
+ */
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { RegisterSharedSessionInput } from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { SpineResult, SpineTransport } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
+import {
+  postSessionClose,
+  postSessionRegister,
+  type SessionCloseResult,
+  type SessionRegisterResult,
+  type SessionRegistrationConnection,
+  type SessionRegistrationInput,
+} from '../agent/session-registration.ts';
+import { readConnectedHostOperatorToken } from './connected-host-auth.ts';
+
+const DEFAULT_REGISTER_TIMEOUT_MS = 1_500;
+const DEFAULT_CLOSE_TIMEOUT_MS = 500;
+const DEFAULT_PROBE_TIMEOUT_MS = 1_500;
+
+/**
+ * Builds a per-op connection resolver from the config manager (host/port,
+ * default 127.0.0.1:3421) and the connected-host operator token (env
+ * overrides + the canonical operator-tokens.json). Re-read every op so a
+ * token that appears after boot is picked up.
+ */
+export function createSpineConnectionResolver(
+  configManager: Pick<ConfigManager, 'get'>,
+  homeDirectory: string,
+): () => SessionRegistrationConnection {
+  return () => {
+    const hostValue = configManager.get('controlPlane.host');
+    const portValue = configManager.get('controlPlane.port');
+    const host = typeof hostValue === 'string' && hostValue.trim().length > 0 ? hostValue.trim() : '127.0.0.1';
+    const port = typeof portValue === 'number' && Number.isFinite(portValue) ? portValue : 3421;
+    const token = readConnectedHostOperatorToken(homeDirectory);
+    return { baseUrl: `http://${host}:${port}`, token: token.token, tokenPath: token.path };
+  };
+}
+
+/** Maps the SDK's canonical register input onto the REST mirror's wire shape. No `kind` field: the REST mirror always stamps SESSION_REGISTER_KIND server-side (see session-registration.ts), matching the SDK's `recordKind` left unset for this participant. */
+function toRegistrationInput(input: RegisterSharedSessionInput): SessionRegistrationInput {
+  return {
+    sessionId: input.sessionId,
+    ...(input.project ? { project: input.project } : {}),
+    ...(input.title ? { title: input.title } : {}),
+    participant: {
+      surfaceKind: input.participant.surfaceKind,
+      surfaceId: input.participant.surfaceId,
+      ...(input.participant.externalId ? { externalId: input.participant.externalId } : {}),
+      ...(input.participant.userId ? { userId: input.participant.userId } : {}),
+      ...(input.participant.displayName ? { displayName: input.participant.displayName } : {}),
+      ...(input.participant.routeId ? { routeId: input.participant.routeId } : {}),
+      lastSeenAt: input.participant.lastSeenAt,
+    },
+    ...(input.reopen ? { reopen: true } : {}),
+  };
+}
+
+/**
+ * Folds the REST mirror's richer failure vocabulary onto the SDK core's
+ * ok/offline/rejected outcome (decision-record ruling #5): `ok` stays `ok`;
+ * `connected_host_unavailable` (a transient connectivity fault) becomes
+ * `offline` so the core enqueues for reconnect replay; every DURABLE refusal
+ * (`auth_required`, `connected_host_route_unavailable`, `connected_host_error`)
+ * becomes `rejected` so the core logs it and never enqueues it (no
+ * retry-forever).
+ */
+function foldResult(result: SessionRegisterResult | SessionCloseResult): SpineResult {
+  if (result.ok) return { outcome: 'ok' };
+  if (result.kind === 'connected_host_unavailable') return { outcome: 'offline', error: result.error };
+  return { outcome: 'rejected', error: result.error };
+}
+
+export interface SpineRestTransportOptions {
+  readonly resolveConnection: () => SessionRegistrationConnection;
+  readonly registerTimeoutMs?: number;
+  readonly closeTimeoutMs?: number;
+}
+
+/**
+ * The agent's version-tolerant REST transport injected into the SDK
+ * `SessionSpineClient` at construction (live-immediately mode). Wraps
+ * postSessionRegister/postSessionClose and folds their result kinds onto
+ * {@link SpineResult}.
+ */
+export function createSpineRestTransport(options: SpineRestTransportOptions): SpineTransport {
+  const registerTimeoutMs = options.registerTimeoutMs ?? DEFAULT_REGISTER_TIMEOUT_MS;
+  const closeTimeoutMs = options.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS;
+  return {
+    async register(input: RegisterSharedSessionInput): Promise<SpineResult> {
+      const connection = options.resolveConnection();
+      const result = await postSessionRegister(connection, toRegistrationInput(input), { timeoutMs: registerTimeoutMs });
+      return foldResult(result);
+    },
+    async close(sessionId: string): Promise<SpineResult> {
+      const connection = options.resolveConnection();
+      const result = await postSessionClose(connection, sessionId, { timeoutMs: closeTimeoutMs });
+      return foldResult(result);
+    },
+  };
+}
+
+async function defaultProbe(connection: SessionRegistrationConnection, timeoutMs: number): Promise<boolean> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // Any HTTP response (even 401) means the host answered -> reachable. Auth is
+    // a separate concern surfaced by register/close results, not the probe.
+    await fetch(`${connection.baseUrl}/status`, {
+      headers: connection.token ? { authorization: `Bearer ${connection.token}` } : undefined,
+      signal: controller.signal,
+    });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface SpineRestProbeOptions {
+  readonly resolveConnection: () => SessionRegistrationConnection;
+  readonly probeTimeoutMs?: number;
+  /** Override for tests; default does a short GET {baseUrl}/status. */
+  readonly probeImpl?: (connection: SessionRegistrationConnection, timeoutMs: number) => Promise<boolean>;
+}
+
+/**
+ * Builds the zero-argument `probe` the SDK core calls directly from
+ * `probeReachability()` (its injected-probe shape takes no parameters — the
+ * core has no connection to hand it). This closure captures the resolver and
+ * timeout so the core stays connection-agnostic.
+ */
+export function createSpineRestProbe(options: SpineRestProbeOptions): () => Promise<boolean> {
+  const probeTimeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+  const probeImpl = options.probeImpl ?? defaultProbe;
+  return () => probeImpl(options.resolveConnection(), probeTimeoutMs);
+}

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

@@ -229,7 +229,12 @@ export function installTuiTerminalOutputGuard(options: TuiTerminalOutputGuardOpt
       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}`);
+      const notice = `[Terminal] Captured ${count} direct ${event.source} write${plural} that would have corrupted the TUI: ${event.preview}`;
+      // Keep the aggregate count reachable in the activity log even though the
+      // noise gate (system-message-noise.ts) drops the notice from the Recent
+      // feed — drop-from-the-feed, not delete. (W4-R2 honest degraded state.)
+      logger.info(notice, { source: event.source, count });
+      options.notify(notice);
     },
   });
 }

package/src/runtime/ui-services.ts

@@ -54,6 +54,8 @@ export interface UiPlatformServices {
   readonly tokenAuditor: RuntimeServices['tokenAuditor'];
   readonly replayEngine: RuntimeServices['replayEngine'];
   readonly webhookNotifier: RuntimeServices['webhookNotifier'];
+  /** W4-R3 — OS-level terminal focus tracker, ported from goodvibes-tui's W2.3. */
+  readonly focusTracker: RuntimeServices['focusTracker'];
   readonly policyRuntimeState: RuntimeServices['policyRuntimeState'];
   readonly externalServices?: {
     inspect(): {
@@ -165,6 +167,7 @@ export function createUiRuntimeServices(
       tokenAuditor: runtimeServices.tokenAuditor,
       replayEngine: runtimeServices.replayEngine,
       webhookNotifier: runtimeServices.webhookNotifier,
+      focusTracker: runtimeServices.focusTracker,
       policyRuntimeState: runtimeServices.policyRuntimeState,
     },
     planning: {