@pellux/goodvibes-tui 1.9.2 → 1.10.0

package/src/panels/cost-tracker-panel.ts

@@ -22,7 +22,7 @@ import {
   DEFAULT_PANEL_PALETTE,
   type PanelWorkspaceSection,
 } from './polish.ts';
-import { calcSessionCost, isModelPriced, computeBudgetBreach, readBudgetAlertUsd, type BudgetAlertConfigAccess } from '../export/cost-utils.ts';
+import { calcSessionCost, isModelPriced, computeBudgetBreach, readBudgetAlertUsd, BUDGET_ALERT_USD_CONFIG_KEY, type BudgetAlertConfigAccess } from '../export/cost-utils.ts';
 import { abbreviateCount } from '../utils/format-number.ts';
 import { isTextBackspace } from '../input/delete-key-policy.ts';
 
@@ -332,7 +332,7 @@ export class CostTrackerPanel extends BasePanel {
   public setBudgetThreshold(usd: number): void {
     if (!Number.isFinite(usd) || usd < 0) return;
     this.budgetThreshold = usd;
-    this.configAccess?.set('behavior.budgetAlertUsd', usd);
+    this.configAccess?.set(BUDGET_ALERT_USD_CONFIG_KEY, usd);
     this.markDirty();
   }
 

package/src/panels/modals/memory-modal.ts

@@ -17,6 +17,16 @@ import type {
 // panel's selected-record scope/class/tags/provenance detail is folded into
 // each row label. `memoryRegistry` absent → the retired MemoryPanel's
 // "not configured" copy renders as an honest degraded state.
+//
+// Read path (memory-spine adoption): reads go through the spine client's
+// `honestSearch` — the MemoryAccess shape — not the raw registry, so a session
+// that has adopted an external daemon reads the SAME wire-served records a
+// wire failure is deliberately surfaced (never a silently stale local copy).
+// `buildView()` stays synchronous/pure per the ConfigModalSurface contract;
+// `refresh()` is async and calls the `requestRender` callback `onOpen` hands
+// it when the data lands. The Review Queue ranking is recomputed client-side
+// from the same honestSearch batch (see `rankForReview` below) rather than
+// through a second wire call — `reviewQueue` is not part of MemoryAccess.
 // ---------------------------------------------------------------------------
 
 /** Minimal read shape of a `MemoryRecord` this modal renders. */
@@ -33,16 +43,42 @@ interface MemoryRecordLike {
   readonly reviewedAt?: number | undefined;
   readonly reviewedBy?: string | undefined;
   readonly createdAt: number;
+  readonly updatedAt?: number | undefined;
   readonly provenance: readonly { readonly kind: string; readonly ref: string }[];
 }
 
 export interface MemoryModalDeps {
   readonly memoryRegistry?: {
-    search(filter?: { limit?: number }): readonly MemoryRecordLike[];
-    reviewQueue(limit?: number): readonly MemoryRecordLike[];
+    honestSearch(filter?: { limit?: number }): Promise<{
+      readonly records: readonly MemoryRecordLike[];
+      readonly indexUnavailableReason?: string | null | undefined;
+    }>;
   };
 }
 
+/**
+ * Client-side port of the SDK's MemoryStore.reviewQueue ranking
+ * (memory-store-helpers.ts reviewQueueScore/isReviewCandidate): all four
+ * review states are candidates, scored by state + inverse confidence (flagged
+ * states penalized), tie-broken by recency. Presentation ordering only — not
+ * a wire call, so exact parity with the server's own tie-breaking on ids it
+ * has never seen is not load-bearing.
+ */
+function rankForReview(records: readonly MemoryRecordLike[], limit: number): MemoryRecordLike[] {
+  const score = (r: MemoryRecordLike): number => {
+    let s = 0;
+    if (r.reviewState === 'fresh') s += 40;
+    if (r.reviewState === 'stale') s += 20;
+    if (r.reviewState === 'contradicted') s += 10;
+    s += Math.max(0, 100 - r.confidence);
+    if (r.reviewState === 'stale' || r.reviewState === 'contradicted') s -= 20;
+    return s;
+  };
+  return [...records]
+    .sort((a, b) => score(b) - score(a) || (b.updatedAt ?? b.createdAt) - (a.updatedAt ?? a.createdAt) || b.createdAt - a.createdAt)
+    .slice(0, limit);
+}
+
 // Mirrors registerKnowledgePanels's withUnconfiguredFallback copy for the
 // retired MemoryPanel (src/panels/builtin/knowledge.ts) verbatim.
 const NOT_CONFIGURED_TITLE = 'Memory registry not configured for this session.';
@@ -57,6 +93,9 @@ class MemoryModalSurface implements ConfigModalSurface {
   readonly title = 'Memory';
   private allRecords: MemoryRecordLike[] = [];
   private reviewRecords: MemoryRecordLike[] = [];
+  /** Honest note on the last read: a wire failure (client mode) or the index-unavailable fallback reason — never silently dropped. */
+  private loadNote: string | null = null;
+  private requestRender: (() => void) | null = null;
 
   constructor(private readonly deps: MemoryModalDeps) {}
 
@@ -71,12 +110,27 @@ class MemoryModalSurface implements ConfigModalSurface {
     { key: 'r', id: 'refresh', label: 'refresh' },
   ];
 
-  onOpen(): void { this.refresh(); }
+  onOpen(requestRender: () => void): void {
+    this.requestRender = requestRender;
+    void this.refresh();
+  }
+
+  onClose(): void {
+    this.requestRender = null;
+  }
 
-  private refresh(): void {
-    if (!this.deps.memoryRegistry) { this.allRecords = []; this.reviewRecords = []; return; }
-    this.allRecords = [...this.deps.memoryRegistry.search({ limit: 100 })];
-    this.reviewRecords = [...this.deps.memoryRegistry.reviewQueue(24)];
+  private async refresh(): Promise<void> {
+    if (!this.deps.memoryRegistry) { this.allRecords = []; this.reviewRecords = []; this.loadNote = null; return; }
+    try {
+      const result = await this.deps.memoryRegistry.honestSearch({ limit: 100 });
+      this.allRecords = [...result.records];
+      this.reviewRecords = rankForReview(result.records, 24);
+      this.loadNote = result.indexUnavailableReason ?? null;
+    } catch (error) {
+      // Client-mode wire failure: surfaced plainly, never masked by the last-known list.
+      this.loadNote = `Failed to reach memory over the wire: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    this.requestRender?.();
   }
 
   private recordFrom(id: string): MemoryRecordLike | undefined {
@@ -121,11 +175,15 @@ class MemoryModalSurface implements ConfigModalSurface {
         tabs: [{ id: 'all', label: 'All Records', rows: [] }],
       };
     }
-    return { title: 'Memory', tabs: [this.allTab(), this.reviewTab()] };
+    return {
+      title: 'Memory',
+      ...(this.loadNote ? { degraded: this.loadNote } : {}),
+      tabs: [this.allTab(), this.reviewTab()],
+    };
   }
 
   onAction(id: string, ctx: ConfigModalActionContext): void {
-    if (id === 'refresh') { this.refresh(); ctx.setStatus('Reloaded memory records.'); return; }
+    if (id === 'refresh') { void this.refresh(); ctx.setStatus('Reloading memory records...'); return; }
     const record = ctx.row ? this.recordFrom(ctx.row.id) : undefined;
     if (!record) return;
     const review = (state: string, confidence: number, reason?: string): void => {
@@ -150,9 +208,12 @@ export function createMemoryModalSurface(deps: MemoryModalDeps): ConfigModalSurf
 
 /**
  * Deterministic golden fixture: fixed memory records with frozen createdAt
- * timestamps — no live registry, no wall-clock, no random ids.
+ * timestamps — no live registry, no wall-clock, no random ids. Promise-backed
+ * (see ecosystem-modals-golden.test.ts): `honestSearch` is async even for this
+ * in-memory fixture (matching the real MemoryAccess shape), so the factory
+ * pre-awaits the initial `onOpen` refresh before handing back the surface.
  */
-export function memoryModalGoldenSurface(): ConfigModalSurface {
+export async function memoryModalGoldenSurface(): Promise<ConfigModalSurface> {
   const FIXED_CREATED_AT = 1735689600000; // 2025-01-01T00:00:00.000Z
   const records: readonly MemoryRecordLike[] = [
     {
@@ -171,10 +232,10 @@ export function memoryModalGoldenSurface(): ConfigModalSurface {
       createdAt: FIXED_CREATED_AT + 86400000, provenance: [],
     },
   ];
-  return createMemoryModalSurface({
-    memoryRegistry: {
-      search: () => records,
-      reviewQueue: () => records.filter((record) => record.reviewState !== 'reviewed'),
-    },
+  const surface = createMemoryModalSurface({
+    memoryRegistry: { honestSearch: async () => ({ records }) },
   });
+  surface.onOpen?.(() => {});
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  return surface;
 }

package/src/runtime/bootstrap-command-context.ts

@@ -2,6 +2,7 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { AdaptivePlanner } from '@pellux/goodvibes-sdk/platform/core';
 import type { ConversationManager } from '../core/conversation';
 import type { KnowledgeApi } from '@pellux/goodvibes-sdk/platform/knowledge';
+import type { MemorySpineClient } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
 import type { HookApi } from '@pellux/goodvibes-sdk/platform/hooks';
 import type { McpApi } from '@pellux/goodvibes-sdk/platform/mcp';
 import type { PanelManager } from '../panels/panel-manager.ts';
@@ -107,6 +108,7 @@ export type CreateBootstrapCommandContextOptions = {
   operatorClient?: OperatorClient;
   peerClient?: PeerClient;
   knowledgeApi?: KnowledgeApi;
+  memorySpine?: MemorySpineClient;
   hookApi?: HookApi;
   mcpApi?: McpApi;
   opsApi?: OpsApi;
@@ -195,6 +197,7 @@ export function createBootstrapCommandContext(
     operatorClient,
     peerClient,
     knowledgeApi,
+    memorySpine,
     hookApi,
     mcpApi,
     opsApi,
@@ -279,6 +282,7 @@ export function createBootstrapCommandContext(
     peerClient,
     providerApi,
     knowledgeApi,
+    memorySpine,
     hookApi,
     mcpApi,
     opsApi,

package/src/runtime/bootstrap-command-parts.ts

@@ -3,6 +3,7 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { AdaptivePlanner } from '@pellux/goodvibes-sdk/platform/core';
 import type { ConversationManager } from '../core/conversation';
 import type { KnowledgeApi } from '@pellux/goodvibes-sdk/platform/knowledge';
+import type { MemorySpineClient } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
 import type { HookApi } from '@pellux/goodvibes-sdk/platform/hooks';
 import type { McpApi } from '@pellux/goodvibes-sdk/platform/mcp';
 import type { PanelManager, PanelDeepLinkTarget } from '../panels/panel-manager.ts';
@@ -133,6 +134,7 @@ export interface BootstrapCommandSectionOptions {
   readonly peerClient?: PeerClient;
   readonly providerApi?: ProviderApi;
   readonly knowledgeApi?: KnowledgeApi;
+  readonly memorySpine?: MemorySpineClient;
   readonly hookApi?: HookApi;
   readonly mcpApi?: McpApi;
   readonly opsApi?: OpsApi;
@@ -421,7 +423,7 @@ export function createBootstrapCommandExtensionsSection(
 export function createBootstrapCommandClientsSection(
   options: Pick<
     BootstrapCommandSectionOptions,
-    'operatorClient' | 'peerClient' | 'providerApi' | 'knowledgeApi' | 'hookApi' | 'mcpApi' | 'opsApi' | 'directTransport'
+    'operatorClient' | 'peerClient' | 'providerApi' | 'knowledgeApi' | 'memorySpine' | 'hookApi' | 'mcpApi' | 'opsApi' | 'directTransport'
   >,
 ): BootstrapCommandClientSection {
   return {
@@ -429,6 +431,7 @@ export function createBootstrapCommandClientsSection(
     peer: options.peerClient,
     providerApi: options.providerApi,
     knowledgeApi: options.knowledgeApi,
+    memorySpine: options.memorySpine,
     hookApi: options.hookApi,
     mcpApi: options.mcpApi,
     opsApi: options.opsApi,

package/src/runtime/bootstrap-shell.ts

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { readBudgetAlertUsd, BUDGET_ALERT_USD_DEFAULT } from '../export/cost-utils.ts';
+import { refreshMemoryRecallSnapshot } from './orchestrator-core-services.ts';
 import { sumConversationUsage, type ConversationManager } from '../core/conversation';
 import type { Orchestrator } from '../core/orchestrator';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
@@ -189,7 +190,8 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     componentHealthMonitor: services.componentHealthMonitor,
     worktreeRegistry: services.worktreeRegistry,
     sandboxSessionRegistry: services.sandboxSessionRegistry,
-    memoryRegistry: services.memoryRegistry,
+    // Memory modal reads via the spine client, not the raw registry (see builtin/shared.ts).
+    memoryRegistry: services.memorySpine,
     uiServices,
     pluginManager: services.pluginManager,
     hookDispatcher: services.hookDispatcher,
@@ -299,6 +301,10 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     operatorClient: directTransport.operator,
     peerClient: directTransport.peer,
     knowledgeApi,
+    // /recall's browse/link/queue/export/import subcommands and the per-turn
+    // knowledge-injection read route through the spine client, not the raw
+    // local registry, so they fully detach when a daemon is adopted.
+    memorySpine: services.memorySpine,
     hookApi,
     mcpApi,
     opsApi,
@@ -309,9 +315,14 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     loadSystemPrompt: () => loadBootstrapSystemPrompt(configManager),
     activatePlan: (_planId, task) => {
       setTimeout(() => {
-        orchestrator.handleUserInput(task).catch((err) => {
-          logger.debug('activatePlan handler failed', { error: summarizeError(err) });
-        });
+        void (async () => {
+          // Refresh the recall snapshot before this plan-driven turn — see
+          // the matching comment in main.ts's submitInput.
+          await refreshMemoryRecallSnapshot(services);
+          orchestrator.handleUserInput(task).catch((err) => {
+            logger.debug('activatePlan handler failed', { error: summarizeError(err) });
+          });
+        })();
       }, 50);
     },
     completeModelSelectionSideEffect,

package/src/runtime/bootstrap.ts

@@ -39,6 +39,7 @@ import { startExternalServices, type ExternalServicesHandle, type HostServiceSta
 import { createHttpTransport } from '@/runtime/index.ts';
 import { foldLegacySpineStore, deriveSpineFooterStatus } from '@pellux/goodvibes-sdk/platform/runtime/session-spine';
 import { createTuiSpineTransport, type SpineSessionsClient } from './session-spine-transport.ts';
+import { syncMemorySpineToHostStatus, type MemorySpineActiveRef } from './memory-spine-transport.ts';
 import { pruneStaleOperatorTokens } from '@pellux/goodvibes-sdk/platform/pairing';
 import { resolveDaemonCompanionToken, workspaceOperatorTokenCandidates } from './operator-token-cleanup.ts';
 import type { UiRuntimeServices } from './ui-services.ts';
@@ -46,7 +47,7 @@ import { createDeferredStartupCoordinator } from '@/runtime/index.ts';
 import { initializeBootstrapCore } from './bootstrap-core.ts';
 import { createBootstrapShell } from './bootstrap-shell.ts';
 import { announceResumeState } from './resume-notice.ts';
-import { buildSharedOrchestratorCoreServices } from './orchestrator-core-services.ts';
+import { buildSharedOrchestratorCoreServices, refreshMemoryRecallSnapshot } from './orchestrator-core-services.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { DaemonServer } from '@pellux/goodvibes-sdk/platform/daemon';
 import { HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
@@ -238,9 +239,9 @@ export async function bootstrapRuntime(
     },
   });
   conversationFollowUpRef.value = (item) => orchestrator.enqueueConversationFollowUp(item);
-  // Wire orchestratorHandleUserInputRef so COMPANION_MESSAGE_RECEIVED fires a real LLM turn.
+  // Wire orchestratorHandleUserInputRef so COMPANION_MESSAGE_RECEIVED fires a real LLM turn (after a pre-turn recall-snapshot refresh; see main.ts's submitInput).
   orchestratorHandleUserInputRef.value = (text: string, options?: OrchestratorUserInputOptions) => {
-    orchestrator.handleUserInput(text, undefined, options).catch((err: unknown) => {
+    void refreshMemoryRecallSnapshot(services).then(() => orchestrator.handleUserInput(text, undefined, options)).catch((err: unknown) => {
       logger.debug('companion handleUserInput safety catch', { error: String(err) });
     });
   };
@@ -300,13 +301,10 @@ export async function bootstrapRuntime(
   wrfcPersistence.rehydrate();
   const commandRegistry = shell.commandRegistry;
   const commandContext = shell.commandContext;
-  // Boot resume notice (UX-D item 1): after rehydrate() so chain history is
-  // ready, before the operator can type anything. Fire-and-forget — the
-  // checkpoint-count lookup is async (WorkspaceCheckpointManager.list() awaits
-  // its own init()), and this must not block the rest of bootstrap the way
-  // main.ts's `void workspaceCheckpointManager.init().catch(() => {})`
-  // deliberately doesn't either. Local file I/O only; resolves well before a
-  // human can react to the first rendered frame.
+  // Boot resume notice (UX-D item 1): after rehydrate() so chain history is ready, before
+  // the operator can type anything. Fire-and-forget, same as main.ts's non-blocking
+  // `void workspaceCheckpointManager.init().catch(() => {})` — local file I/O only,
+  // resolves well before a human can react to the first rendered frame.
   void announceResumeState({
     workingDirectory: services.workingDirectory,
     homeDirectory: services.homeDirectory,
@@ -390,7 +388,13 @@ export async function bootstrapRuntime(
   // 'unavailable') also stays local-only and honest. Only 'external' (a separately-
   // running daemon this TUI adopted) activates the wire mirror.
   let spineActiveForBaseUrl: string | null = null;
+  // Same adoption signal drives the memory spine (WO memory-adopt) — see
+  // memory-spine-transport.ts. 'embedded' (this process hosts its own daemon)
+  // stays local: the daemon's canonical store IS this process's own
+  // memoryRegistry, so there is no wire hop to make.
+  const memorySpineActiveRef: MemorySpineActiveRef = { value: null };
   const syncSessionSpineToHostStatus = (daemonStatus: HostServiceStatus, sharedDaemonToken: string): void => {
+    syncMemorySpineToHostStatus(services.memorySpine, daemonStatus.mode, daemonStatus.baseUrl, sharedDaemonToken, memorySpineActiveRef, logger);
     if (daemonStatus.mode !== 'external') {
       if (spineActiveForBaseUrl !== null) {
         sessionSpine.deactivate(`daemon mode changed to '${daemonStatus.mode}'`);
@@ -450,14 +454,10 @@ export async function bootstrapRuntime(
       httpListenerPortInUse: hostServiceIsBlocked(httpListenerStatus),
       daemonStatus,
       httpListenerStatus,
-      // Honest session-spine posture, independent of daemonRunning —
-      // 'external'-adopted-but-currently-unreachable degrades to 'offline' here
-      // even though daemonRunning might still read true from a stale handle.
-      // sessionSpine.status() alone is ACTIVITY-gated (only updates on a
-      // register/heartbeat/close), so after the daemon dies mid-idle it would
-      // keep reading 'online'. Derive the footer status from the union cache's
-      // 5s liveness probe too — one signal, no new timer — so offline surfaces
-      // within one refresh interval of the daemon dying.
+      // Honest session-spine posture, independent of daemonRunning — degrades to 'offline'
+      // when adopted-but-unreachable even though daemonRunning might still read a stale
+      // handle as true; sessionSpine.status() alone is activity-gated, so it's derived
+      // together with the union cache's 5s liveness probe (one signal, no new timer).
       sessionSpineActive: sessionSpine.active,
       sessionSpineStatus: deriveSpineFooterStatus(sessionSpine.status(), sessionUnionCache.crossSurfaceView),
     };

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`);
+}