@pellux/goodvibes-tui 1.9.1 → 1.10.0

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

@@ -0,0 +1,289 @@
+/**
+ * memory-spine-transport.ts
+ *
+ * The TUI memory-spine cutover: the thin wire adapter that lets the TUI's
+ * bootstrap activate the SDK's
+ * `@pellux/goodvibes-sdk/platform/runtime/memory-spine` `MemorySpineClient`
+ * over the daemon's memory.records.* HTTP routes, mirroring
+ * session-spine-transport.ts's pattern for the session spine.
+ *
+ * The SDK does not (yet) ship a typed operator client for these routes (unlike
+ * `HttpTransport.operator.sessions`), so this adapter builds a small REST
+ * client directly against the known routes — exactly what the SDK's own
+ * `MemoryTransport` doc comment describes as the expected consumer shape.
+ *
+ * FULL DETACH (SDK 1.2.0). Beyond the five 1.1.0 CORE routes (add, search,
+ * get, review, delete) this now implements the full 1.2.0 EXTENDED catalog
+ * (list, search-semantic, update, links.list, links.add, export, import,
+ * vector, doctor, review-queue) — see
+ * docs/decisions/2026-07-06-memory-wire-full-detach.md in the SDK repo. This
+ * is what lets `/recall`'s browse/link/queue/export/import subcommands and
+ * the per-turn knowledge-injection bulk read fully detach from the local
+ * store file when a daemon is adopted: every one of those ops now has a wire
+ * equivalent, so this transport implements every EXTENDED verb rather than
+ * leaving some optional.
+ *
+ * HONESTY. Unlike the session mirror (fire-and-forget, folded into a soft
+ * 'offline' result), memory reads/writes return data the caller depends on —
+ * a transport failure here is NOT swallowed. It propagates as a rejected
+ * promise, matching `MemorySpineClient`'s documented contract: a wire client
+ * must never silently fall back to a divergent local copy in place of a real
+ * failure.
+ *
+ * A 404 is disambiguated by its RESPONSE CODE (`classifyMemoryWireError`, from
+ * the SDK's `platform/runtime/memory-spine` — this transport no longer inlines
+ * its own copy of the discriminator), never by the bare status. A record-missing
+ * 404 carries `MEMORY_RECORD_NOT_FOUND`: on a nullable verb
+ * (`get`/`updateReview`/`update`/`link`) it maps to the documented `null` "not
+ * found"; on a non-nullable verb (`linksFor` etc.) it is not representable as
+ * null so it propagates as a thrown error. ANY OTHER 404 — a route-not-found
+ * from an older daemon that never registered this route, or a bare legacy 404
+ * with no code — is treated as "this daemon does not serve this verb" and
+ * rejects with a stated reason on EVERY verb, never a silent `null`. That is
+ * what lets `/recall` surface an honest degraded message on a version-skewed
+ * daemon instead of reporting an existing record as gone.
+ */
+import { buildUrl, createJsonRequestInit, requestJsonRaw } from '@pellux/goodvibes-sdk/transport-http';
+import {
+  classifyMemoryWireError,
+  memoryVerbUnavailableError,
+  type MemoryAccess,
+  type MemoryTransport,
+  type MemoryUpdatePatch,
+} from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
+import type {
+  HonestMemorySearchOptions,
+  HonestMemorySearchResult,
+  MemoryAddOptions,
+  MemoryBundle,
+  MemoryDoctorReport,
+  MemoryLink,
+  MemoryRecord,
+  MemoryScope,
+  MemorySearchFilter,
+  MemorySemanticSearchResult,
+} from '@pellux/goodvibes-sdk/platform/state';
+import type { MemoryVectorStats } from '@pellux/goodvibes-sdk/platform/state';
+
+/** Derived from `MemoryAccess` itself rather than imported by name — `MemoryReviewPatch` is not re-exported from the SDK's public `platform/state` entry point. */
+type MemoryReviewPatch = Parameters<MemoryAccess['updateReview']>[1];
+/** Same reasoning — `MemoryImportResult` is not re-exported from a public SDK entry point. */
+type MemoryImportResult = Awaited<ReturnType<MemoryAccess['importBundle']>>;
+
+/**
+ * The 404 discriminator and the "daemon does not serve this verb" rejection are
+ * now the SDK's own `classifyMemoryWireError` / `memoryVerbUnavailableError`
+ * (`@pellux/goodvibes-sdk/platform/runtime/memory-spine`) rather than a copy
+ * inlined in this transport — this surface's SDK pin now ships them as a
+ * shared constant/discriminator, so the two thin folds below just delegate.
+ */
+
+/** Fold for a NULLABLE record-scoped verb: record-miss → null; version-skew → honest reject; else rethrow. */
+function foldNullableMemoryWire404(verb: string, error: unknown): null {
+  const kind = classifyMemoryWireError(error);
+  if (kind === 'record-missing') return null;
+  if (kind === 'method-unavailable') throw memoryVerbUnavailableError(verb, error);
+  throw error;
+}
+
+/** Fold for a NON-NULLABLE (collection or record-required) verb: version-skew → honest reject; else rethrow. */
+function rethrowMemoryWire404(verb: string, error: unknown): never {
+  if (classifyMemoryWireError(error) === 'method-unavailable') throw memoryVerbUnavailableError(verb, error);
+  throw error;
+}
+
+export interface MemorySpineWireOptions {
+  readonly baseUrl: string;
+  readonly authToken: string | null;
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Build the `MemorySpineClient` wire transport: a thin REST adapter over the
+ * adopted daemon's full memory.records.* route catalog (five CORE routes plus
+ * the ten 1.2.0 EXTENDED routes). `bootstrap.ts` activates a client built from
+ * this the same way it adopts the session spine.
+ */
+export function createTuiMemorySpineTransport(options: MemorySpineWireOptions): MemoryTransport {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const token = options.authToken;
+  const url = (path: string): string => buildUrl(options.baseUrl, path);
+  return {
+    add: async (opts: MemoryAddOptions): Promise<MemoryRecord> => {
+      const response = await requestJsonRaw<{ record: MemoryRecord }>(
+        fetchImpl, url('/api/memory/records'), createJsonRequestInit(token, opts, 'POST'),
+      );
+      return response.record;
+    },
+    honestSearch: async (filter?: MemorySearchFilter, searchOptions?: HonestMemorySearchOptions): Promise<HonestMemorySearchResult> => {
+      const body = { ...(filter ?? {}), ...(searchOptions?.recall !== undefined ? { recall: searchOptions.recall } : {}) };
+      return await requestJsonRaw<HonestMemorySearchResult>(
+        fetchImpl, url('/api/memory/records/search'), createJsonRequestInit(token, body, 'POST'),
+      );
+    },
+    get: async (id: string): Promise<MemoryRecord | null> => {
+      try {
+        const response = await requestJsonRaw<{ record: MemoryRecord }>(
+          fetchImpl, url(`/api/memory/records/${encodeURIComponent(id)}`), createJsonRequestInit(token),
+        );
+        return response.record;
+      } catch (error) {
+        return foldNullableMemoryWire404('get', error);
+      }
+    },
+    updateReview: async (id: string, patch: MemoryReviewPatch): Promise<MemoryRecord | null> => {
+      try {
+        const response = await requestJsonRaw<{ record: MemoryRecord }>(
+          fetchImpl, url(`/api/memory/records/${encodeURIComponent(id)}/review`), createJsonRequestInit(token, patch, 'POST'),
+        );
+        return response.record;
+      } catch (error) {
+        return foldNullableMemoryWire404('updateReview', error);
+      }
+    },
+    delete: async (id: string): Promise<boolean> => {
+      const response = await requestJsonRaw<{ id: string; deleted: boolean }>(
+        fetchImpl, url(`/api/memory/records/${encodeURIComponent(id)}`), createJsonRequestInit(token, undefined, 'DELETE'),
+      );
+      return response.deleted;
+    },
+
+    // ── Extended verbs (1.2.0 full-detach) ──────────────────────────────────
+
+    list: async (filter?: MemorySearchFilter): Promise<readonly MemoryRecord[]> => {
+      try {
+        const response = await requestJsonRaw<{ records: readonly MemoryRecord[] }>(
+          fetchImpl, url('/api/memory/records/list'), createJsonRequestInit(token, filter ?? {}, 'POST'),
+        );
+        return response.records;
+      } catch (error) {
+        return rethrowMemoryWire404('list', error);
+      }
+    },
+    searchSemantic: async (filter?: MemorySearchFilter): Promise<readonly MemorySemanticSearchResult[]> => {
+      try {
+        const response = await requestJsonRaw<{ results: readonly MemorySemanticSearchResult[] }>(
+          fetchImpl, url('/api/memory/records/search-semantic'), createJsonRequestInit(token, filter ?? {}, 'POST'),
+        );
+        return response.results;
+      } catch (error) {
+        return rethrowMemoryWire404('searchSemantic', error);
+      }
+    },
+    update: async (id: string, patch: MemoryUpdatePatch): Promise<MemoryRecord | null> => {
+      try {
+        const response = await requestJsonRaw<{ record: MemoryRecord }>(
+          fetchImpl, url(`/api/memory/records/${encodeURIComponent(id)}/update`), createJsonRequestInit(token, patch, 'POST'),
+        );
+        return response.record;
+      } catch (error) {
+        return foldNullableMemoryWire404('update', error);
+      }
+    },
+    link: async (fromId: string, toId: string, relation: string): Promise<MemoryLink | null> => {
+      try {
+        const response = await requestJsonRaw<{ link: MemoryLink }>(
+          fetchImpl, url(`/api/memory/records/${encodeURIComponent(fromId)}/links`), createJsonRequestInit(token, { toId, relation }, 'POST'),
+        );
+        return response.link;
+      } catch (error) {
+        return foldNullableMemoryWire404('link', error);
+      }
+    },
+    linksFor: async (id: string): Promise<readonly MemoryLink[]> => {
+      try {
+        const response = await requestJsonRaw<{ links: readonly MemoryLink[] }>(
+          fetchImpl, url(`/api/memory/records/${encodeURIComponent(id)}/links`), createJsonRequestInit(token),
+        );
+        return response.links;
+      } catch (error) {
+        return rethrowMemoryWire404('linksFor', error);
+      }
+    },
+    reviewQueue: async (limit?: number, scope?: MemoryScope): Promise<readonly MemoryRecord[]> => {
+      const params = new URLSearchParams();
+      if (limit !== undefined) params.set('limit', String(limit));
+      if (scope !== undefined) params.set('scope', scope);
+      const query = params.toString();
+      try {
+        const response = await requestJsonRaw<{ records: readonly MemoryRecord[] }>(
+          fetchImpl, url(`/api/memory/review-queue${query ? `?${query}` : ''}`), createJsonRequestInit(token),
+        );
+        return response.records;
+      } catch (error) {
+        return rethrowMemoryWire404('reviewQueue', error);
+      }
+    },
+    exportBundle: async (filter?: MemorySearchFilter): Promise<MemoryBundle> => {
+      try {
+        const response = await requestJsonRaw<{ bundle: MemoryBundle }>(
+          fetchImpl, url('/api/memory/records/export'), createJsonRequestInit(token, filter ?? {}, 'POST'),
+        );
+        return response.bundle;
+      } catch (error) {
+        return rethrowMemoryWire404('exportBundle', error);
+      }
+    },
+    importBundle: async (bundle: MemoryBundle): Promise<MemoryImportResult> => {
+      try {
+        const response = await requestJsonRaw<{ result: MemoryImportResult }>(
+          fetchImpl, url('/api/memory/records/import'), createJsonRequestInit(token, { bundle }, 'POST'),
+        );
+        return response.result;
+      } catch (error) {
+        return rethrowMemoryWire404('importBundle', error);
+      }
+    },
+    vectorStats: async (): Promise<MemoryVectorStats> => {
+      try {
+        const response = await requestJsonRaw<{ vector: MemoryVectorStats }>(
+          fetchImpl, url('/api/memory/vector'), createJsonRequestInit(token),
+        );
+        return response.vector;
+      } catch (error) {
+        return rethrowMemoryWire404('vectorStats', error);
+      }
+    },
+    doctor: async (): Promise<MemoryDoctorReport> => {
+      try {
+        return await requestJsonRaw<MemoryDoctorReport>(
+          fetchImpl, url('/api/memory/doctor'), createJsonRequestInit(token),
+        );
+      } catch (error) {
+        return rethrowMemoryWire404('doctor', error);
+      }
+    },
+  };
+}
+
+/** Mutable one-slot ref tracking which adopted daemon's baseUrl the memory spine is currently wired to (mirrors bootstrap.ts's `spineActiveForBaseUrl`). */
+export interface MemorySpineActiveRef { value: string | null }
+
+/**
+ * Sync the memory spine to the current daemon-adoption status — the SAME
+ * signal bootstrap.ts's `syncSessionSpineToHostStatus` uses. 'external' (an
+ * adopted, separately-running daemon) activates the wire transport; every
+ * other mode ('embedded' — this process IS the daemon host, so its own store
+ * is already canonical — plus 'disabled'/'blocked'/'incompatible'/'unavailable')
+ * deactivates back to local access.
+ */
+export function syncMemorySpineToHostStatus(
+  memorySpine: { activate: (transport: MemoryTransport) => void; deactivate: (reason: string) => void },
+  daemonMode: string,
+  daemonBaseUrl: string,
+  sharedDaemonToken: string,
+  activeRef: MemorySpineActiveRef,
+  log: { info: (message: string) => void },
+): void {
+  if (daemonMode !== 'external') {
+    if (activeRef.value !== null) {
+      memorySpine.deactivate(`daemon mode changed to '${daemonMode}'`);
+      activeRef.value = null;
+    }
+    return;
+  }
+  if (activeRef.value === daemonBaseUrl) return; // already wired to this exact adopted daemon
+  memorySpine.activate(createTuiMemorySpineTransport({ baseUrl: daemonBaseUrl, authToken: sharedDaemonToken }));
+  activeRef.value = daemonBaseUrl;
+  log.info(`[bootstrap] memory spine: adopted external daemon at ${daemonBaseUrl} — routing memory ops over the wire`);
+}

package/src/runtime/onboarding/snapshot.ts

@@ -403,12 +403,12 @@ export async function collectOnboardingSnapshot(
       snapshot: authSnapshotResult.value,
     },
     bindSettings: {
-      // danger.daemon (removed Wave 6 — see docs/decisions/2026-07-05-daemon-by-default.md)
-      // used to gate the pre-Wave-2 opt-in daemon posture; this site read it RAW
+      // danger.daemon (since removed — see docs/decisions/2026-07-05-daemon-by-default.md)
+      // used to gate the earlier opt-in daemon posture; this site read it RAW
       // (not through resolveDaemonEnabled) so the wizard's network-mode
       // classification tracked "did the user explicitly request the legacy
       // dangerous posture" rather than "does the daemon run" (which has defaulted
-      // true unconditionally since Wave 2, and would misclassify every default,
+      // true unconditionally since daemon-by-default landed, and would misclassify every default,
       // local-only install as server-mode if read here). Every realistic config
       // already evaluated this to `false` (unset, or an explicit `danger.daemon:
       // false` both did); the alias's removal migration preserves the one case

package/src/runtime/onboarding/types.ts

@@ -126,7 +126,7 @@ export interface OnboardingSurfacesSnapshot {
 }
 
 /**
- * W4-D1 wizard wiring: read-only detection of a legacy `goodvibes-daemon.service`
+ * Wizard wiring: read-only detection of a legacy `goodvibes-daemon.service`
  * systemd unit (see `../legacy-daemon-migration.ts`'s `LegacyUnitInfo`), carried
  * on the snapshot so the Network step can show the guided migration action only
  * when there is actually something to migrate. Never implies anything was
@@ -137,7 +137,7 @@ export interface OnboardingLegacyDaemonSnapshot {
   readonly active: boolean;
   readonly path: string;
   /**
-   * F2 follow-up: the unit name this tool actually manages on this host,
+   * Follow-up: the unit name this tool actually manages on this host,
    * resolved from the `service.serviceName` config key at snapshot-collection
    * time (`resolveConfiguredServiceName`, `../legacy-daemon-migration.ts`) —
    * so the wizard's detection banner names the real unit instead of the

package/src/runtime/operator-token-cleanup.ts

@@ -4,7 +4,7 @@
  * Shared helper that enumerates the legacy workspace-scoped `operator-tokens.json`
  * locations the TUI has written at various pre-0.21.28 versions. Used by both the
  * in-process bootstrap path (`src/runtime/bootstrap.ts`) and the standalone daemon
- * CLI (`src/daemon/cli.ts`) so F3 (stale-token pruning) has a single source of
+ * CLI (`src/daemon/cli.ts`) so stale-token pruning has a single source of
  * truth for where to look.
  *
  * Adding a new legacy location: append to `workspaceOperatorTokenCandidates` and
@@ -32,7 +32,7 @@ export function workspaceOperatorTokenCandidates(workingDirectory: string): read
 }
 
 /**
- * F1 (adopt-an-already-running-external-daemon): resolve the operator/companion
+ * External-daemon adoption: resolve the operator/companion
  * token this TUI process uses to authenticate with its daemon, honoring
  * `GOODVIBES_DAEMON_TOKEN` as a non-interactive override.
  *

package/src/runtime/orchestrator-core-services.ts

@@ -12,7 +12,7 @@ export type OrchestratorCoreServicesSource = Pick<
   | 'sessionMemoryStore'
   | 'sessionLineageTracker'
   | 'idempotencyStore'
-  | 'memoryRegistry'
+  | 'memorySpine'
   | 'codeIndexStore'
   | 'codeIndexReindexScheduler'
 >;
@@ -24,7 +24,7 @@ export type OrchestratorCoreServicesSource = Pick<
  * cacheHitTracker; main: favoritesStore) — setCoreServices() merges, so the
  * later main.ts call only overlays, never erases.
  *
- * Wave-5 (wo805) BLOCKER regression guard: `memoryRegistry` here is what turns
+ * BLOCKER regression guard: `memoryRegistry` here is what turns
  * on per-turn passive knowledge injection for the MAIN interactive session —
  * the SDK turn loop hard-gates on `coreServices.memoryRegistry` (undefined is
  * a silent no-op: Orchestrator.getTurnInjections() stays empty forever and
@@ -32,6 +32,18 @@ export type OrchestratorCoreServicesSource = Pick<
  * omitted it independently; routing them through this one function (with
  * src/test/runtime/orchestrator-core-services.test.ts pinning the field) is
  * what keeps that from regressing.
+ *
+ * SDK 1.2.0 FULL DETACH: the SDK's turn loop reads `memoryRegistry.getAll()`
+ * SYNCHRONOUSLY (`TurnKnowledgeRegistrySource`), but the memory spine's wire
+ * reads are asynchronous — a sync function cannot await the wire. Per
+ * docs/decisions/2026-07-06-memory-wire-full-detach.md (SDK repo) this is
+ * satisfied by the spine's freshness-stamped recall snapshot instead of the
+ * raw local `memoryRegistry`: `getAll()` reads `memorySpine.recallSnapshot()`,
+ * which returns whatever the last `refreshRecallSnapshot()` (an async
+ * pre-turn hook — see the `handleUserInput` call sites) captured, honestly
+ * empty/stale until refreshed. This is what lets per-turn knowledge injection
+ * detach from the local store file when a daemon is adopted, instead of
+ * always reading the (possibly divergent) local registry regardless of mode.
  */
 export function buildSharedOrchestratorCoreServices(input: {
   readonly services: OrchestratorCoreServicesSource;
@@ -47,8 +59,8 @@ export function buildSharedOrchestratorCoreServices(input: {
     sessionMemoryStore: services.sessionMemoryStore,
     sessionLineageTracker: services.sessionLineageTracker,
     idempotencyStore: services.idempotencyStore,
-    memoryRegistry: services.memoryRegistry,
-    // Wave-5 Stage B — main-session code auto-injection + tool-site reindex. Injection is
+    memoryRegistry: { getAll: () => services.memorySpine.recallSnapshot().records },
+    // Main-session code auto-injection + tool-site reindex. Injection is
     // additionally gated by the default-off `agent-passive-code-injection` flag inside the
     // SDK; here we supply the source, the live storage.codeIndexEnabled predicate, and the
     // reindex scheduler.
@@ -57,3 +69,16 @@ export function buildSharedOrchestratorCoreServices(input: {
     codeIndexReindexScheduler: services.codeIndexReindexScheduler,
   };
 }
+
+/**
+ * The async pre-turn hook: refreshes the memory spine's recall snapshot over
+ * the CURRENT route (wire when adopted, local otherwise) so the synchronous
+ * per-turn knowledge injection (`memoryRegistry.getAll()` above) reads
+ * up-to-date records instead of whatever the previous refresh captured.
+ * Failures are swallowed — an honest stale/empty snapshot (with its own
+ * degradation note, surfaced via `recallSnapshot().note`) is preferable to
+ * blocking the user's turn on a memory-read failure.
+ */
+export async function refreshMemoryRecallSnapshot(services: Pick<RuntimeServices, 'memorySpine'>): Promise<void> {
+  await services.memorySpine.refreshRecallSnapshot().catch(() => {});
+}

package/src/runtime/process-lifecycle.ts

@@ -57,7 +57,7 @@ export interface ProcessLifecycleDeps {
   readonly unsubs: ReadonlyArray<() => void>;
   readonly getRecoveryInterval: () => ReturnType<typeof setInterval> | null;
   readonly setRecoveryInterval: (value: ReturnType<typeof setInterval> | null) => void;
-  readonly getStopSpokenOutputForExit: () => (() => void) | null;
+  readonly getStopSpokenOutputForExit: () => (() => void | Promise<void>) | null;
 }
 
 export interface ProcessLifecycleHandlers {
@@ -153,7 +153,16 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
     // must not re-run teardown or double-fire ctx.shutdown.
     if (exiting) return;
     exiting = true;
-    getStopSpokenOutputForExit()?.();
+    // Exit lets the spoken audio the user is already hearing finish inside a
+    // short bounded window (capped inside stopForExit, under the 3s shutdown
+    // budget below) while the rest of teardown proceeds; queued-but-unplayed
+    // speech is dropped. Deliberate interrupts (Ctrl+C, /tts stop) still cut
+    // instantly through controller.stop() before this path is ever reached.
+    let spokenOutputDrain: Promise<void> = Promise.resolve();
+    try {
+      spokenOutputDrain = Promise.resolve(getStopSpokenOutputForExit()?.()).then(() => undefined);
+    } catch { /* non-fatal to exit */ }
+    spokenOutputDrain = spokenOutputDrain.catch(() => undefined);
     unsubs.forEach(fn => fn());
     const interval = getRecoveryInterval();
     if (interval !== null) { clearInterval(interval); setRecoveryInterval(null); }
@@ -169,9 +178,14 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
     try {
       // Race the graceful shutdown against a hard timeout — externalServices.stop() can hang
       // and we must still exit; deferredStartup.drain only budgets 100ms internally.
-      await Promise.race([
-        ctx.shutdown({ ...snapshot, ...buildPersistedSessionContext(snapshot.messages, ctx.conversation.getTitleSource(), buildSessionContinuityHints()) }).then(() => { shutdownOk = true; }),
-        new Promise<void>((resolve) => setTimeout(resolve, 3000)),
+      // The spoken-audio drain runs concurrently and is internally capped below
+      // this budget, so it never extends the exit beyond the hard timeout.
+      await Promise.all([
+        spokenOutputDrain,
+        Promise.race([
+          ctx.shutdown({ ...snapshot, ...buildPersistedSessionContext(snapshot.messages, ctx.conversation.getTitleSource(), buildSessionContinuityHints()) }).then(() => { shutdownOk = true; }),
+          new Promise<void>((resolve) => setTimeout(resolve, 3000)),
+        ]),
       ]);
     } catch (err) {
       logger.debug('ctx.shutdown error during exitApp (non-fatal)', { error: summarizeError(err) });

package/src/runtime/services.ts

@@ -24,6 +24,7 @@ import { MultimodalService } from '@pellux/goodvibes-sdk/platform/multimodal';
 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 { MemorySpineClient, createLocalMemoryAccess } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
 import { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
 import type { RuntimeEventBus } from '@/runtime/index.ts';
 import { createDomainDispatch } from './store/index.ts';
@@ -166,6 +167,8 @@ export interface RuntimeServices {
   readonly workPlanStore: WorkPlanStore;
   readonly memoryStore: MemoryStore;
   readonly memoryRegistry: MemoryRegistry;
+  /** Host-vs-client memory access: local until bootstrap.ts activates it for an adopted 'external' daemon (mirrors sessionSpine). */
+  readonly memorySpine: MemorySpineClient;
   readonly serviceRegistry: ServiceRegistry;
   readonly secretsManager: SecretsManager;
   readonly subscriptionManager: SubscriptionManager;
@@ -222,24 +225,19 @@ 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. */
+  /** 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. */
+  /** 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
+  readonly codeIndexReindexScheduler: CodeIndexReindexScheduler; // 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.
-   * Called by WorkspaceSwapManager after the new directory has been verified.
-   * Stores that require a process restart emit a warn-level log; they continue serving
-   * the old path until the daemon restarts with the new --working-dir.
-   */
+  /** Re-root path-bound stores (MemoryStore, ProjectIndex) to a new working directory, called by WorkspaceSwapManager after verification; stores needing a process restart just warn-log and keep serving the old path until the daemon restarts with the new --working-dir. */
   rerootStores(newWorkingDir: string): Promise<void>;
 }
 
@@ -338,7 +336,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     executor: agentOrchestrator,
     configManager,
   });
-  agentOrchestrator.setConversationSink({ // Wave-3 Part C6 bridge (mirrors the SDK's own createRuntimeServices)
+  agentOrchestrator.setConversationSink({ // Conversation-snapshot bridge (mirrors the SDK's own createRuntimeServices)
     register: (agentId, source) => agentManager.registerConversationSource(agentId, source),
     release: (agentId) => agentManager.releaseConversationSource(agentId),
   });
@@ -387,12 +385,16 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   });
   const artifactStore = new ArtifactStore({ configManager });
   const memoryEmbeddingRegistry = new MemoryEmbeddingProviderRegistry({ configManager });
-  // W6-C2 (E6): open the ONE home-scoped canonical store; legacy per-project TUI memory folds in at boot (foldTuiLegacyMemory).
+  // 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,
   });
   const memoryRegistry = new MemoryRegistry(memoryStore);
+  // Local-until-adopted access facade for spine-shaped consumers (the Memory
+  // modal): bootstrap.ts activates the wire transport when a compatible
+  // external daemon is adopted, same signal as the session spine.
+  const memorySpine = new MemorySpineClient({ local: createLocalMemoryAccess(memoryRegistry) });
   const deliveryManager = new AutomationDeliveryManager({
     configManager,
     serviceRegistry,
@@ -526,14 +528,10 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     automationBridge: automationManager,
   });
 
-  // Daemon handler surfaces: attach HOST handlers to the SDK-auto-registered
-  // builtin gateway descriptors (channels.* / email.* / calendar.*). The SDK
-  // owns every id/descriptor/schema; this only fills the handler slot via
-  // catalog.register(descriptor, handler, { replace: true }). Routing returns
-  // the resolver the inbox surface consumes; triage decorates channels.inbox.list.
-  // The remote surface reuses the SAME DistributedRuntimeManager the SDK facade
-  // injects, so its peer/work methods share one persistent store; remote.peers.*
-  // stay SDK-published routes (not catalog methods).
+  // Daemon handler surfaces: attach HOST handlers to the SDK-auto-registered builtin
+  // gateway descriptors (channels.* / email.* / calendar.*) via catalog.register(descriptor,
+  // handler, { replace: true }) — the SDK owns every id/descriptor/schema. The remote
+  // surface reuses the SAME DistributedRuntimeManager the SDK facade injects.
   const handlerLogger: HandlerLogger = {
     info: (message, meta) => console.info(message, meta ?? ''),
     warn: (message, meta) => console.warn(message, meta ?? ''),
@@ -595,18 +593,18 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     artifactStore,
   });
   const processManager = new ProcessManager();
-  // Wave 4 (wo703): the phase/work-item orchestration engine, constructed
+  // 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
+  // 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)
+  const codeInjectionOrchestratorDeps = { codeIndex: codeIndexStore, isCodeInjectionSettingEnabled: () => isCodeInjectionSettingEnabled(configManager), codeIndexReindexScheduler }; // Code-injection 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
@@ -614,15 +612,15 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   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
+    orchestrationEngine, // Folds workstream/phase/work-item nodes into the fleet
+    codeIndexService: codeIndexStore, // 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
+    messageBus: agentMessageBus, // Backs steer()/`steerable` (the Fleet steer composer builds on top)
+    automationManager, // 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) => {
@@ -681,7 +679,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     remoteRunnerRegistry,
     knowledgeService,
     memoryRegistry,
-    ...codeInjectionOrchestratorDeps, // Wave-5 Stage B: agent-run code injection + tool-site reindex
+    ...codeInjectionOrchestratorDeps, // Agent-run code injection + tool-site reindex
     archetypeLoader,
     configManager,
     providerRegistry,
@@ -725,6 +723,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     workPlanStore,
     memoryStore,
     memoryRegistry,
+    memorySpine,
     serviceRegistry,
     secretsManager,
     subscriptionManager,
@@ -790,7 +789,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     workspaceCheckpointManager,
     integrationHelpers,
     async rerootStores(newWorkingDir: string): Promise<void> {
-      // W6-C2 (E6): the memory store is the home-scoped canonical cross-surface store and
+      // 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));

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

@@ -1,7 +1,7 @@
 /**
  * session-inbound-inputs.ts
  *
- * D3 (One-Platform Wave 2, live-surface steer delivery — the inbound half of the
+ * 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.
  *

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

@@ -1,10 +1,10 @@
 /**
  * session-spine-transport.ts
  *
- * W3-T1 (One-Platform Wave 3, TUI session-spine cutover): the thin typed-client
+ * The 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.
+ * 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

package/src/runtime/ui-services.ts

@@ -114,7 +114,7 @@ export interface UiRuntimeSharedServices {
     readonly remoteSupervisor: RuntimeServices['remoteSupervisor'] & RemoteSupervisor;
     /** W2.2: the shared live process registry backing the Fleet panel. */
     readonly processRegistry: RuntimeServices['processRegistry'];
-    /** Wave-3 (W3.2): the shared runtime event bus — the Fleet panel subscribes to its 'communication' domain for the honest steer-consumed signal. */
+    /** The shared runtime event bus — the Fleet panel subscribes to its 'communication' domain for the honest steer-consumed signal. */
     readonly runtimeBus: RuntimeServices['runtimeBus'];
   };
 }