@vellumai/assistant 0.7.2 → 0.7.3

package/src/daemon/host-transfer-proxy.ts

@@ -9,6 +9,11 @@ import {
   assistantEventHub,
   broadcastMessage,
 } from "../runtime/assistant-event-hub.js";
+import {
+  ambiguousSameUserError,
+  enforceSameActorOrErrorResult,
+  pickSameUserAutoResolve,
+} from "../runtime/auth/same-actor.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import type { ToolExecutionResult } from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
@@ -31,6 +36,13 @@ interface TransferEntry {
   sha256?: string;
   fileBuffer?: Buffer;
   targetClientId?: string;
+  /**
+   * Snapshot of `targetClientId`'s `actorPrincipalId` taken at registration
+   * time. Persisted so the GET/PUT content routes compare against a stable
+   * value rather than the live hub — the target client's SSE subscription
+   * may briefly disconnect between dispatch and content fetch/upload.
+   */
+  targetActorPrincipalId?: string;
 }
 
 /**
@@ -124,6 +136,8 @@ export class HostTransferProxy {
       targetClientId?: string;
     },
     signal?: AbortSignal,
+    // Principal ID of the actor on whose behalf this request is initiated.
+    sourceActorPrincipalId?: string,
   ): Promise<ToolExecutionResult> {
     if (signal?.aborted) {
       return Promise.resolve({ content: "Aborted", isError: true });
@@ -145,8 +159,29 @@ export class HostTransferProxy {
         });
       }
     } else {
-      const capable = assistantEventHub.listClientsByCapability("host_file");
-      if (capable.length === 1) resolvedTargetClientId = capable[0].clientId;
+      // Auto-resolve to the unique same-user client; reject ambiguous
+      // (multi-machine) cases so a single targeted-style transfer cannot
+      // fan out across the user's machines.
+      const resolved = pickSameUserAutoResolve({
+        hub: assistantEventHub,
+        capability: "host_file",
+        sourceActorPrincipalId,
+      });
+      if (resolved.kind === "ambiguous") {
+        return Promise.resolve(ambiguousSameUserError("host_file"));
+      }
+      resolvedTargetClientId =
+        resolved.kind === "match" ? resolved.clientId : undefined;
+    }
+
+    if (resolvedTargetClientId != null) {
+      const rejection = enforceSameActorOrErrorResult({
+        hub: assistantEventHub,
+        sourceActorPrincipalId,
+        targetClientId: resolvedTargetClientId,
+        op: "host_transfer",
+      });
+      if (rejection != null) return Promise.resolve(rejection);
     }
 
     const requestId = uuid();
@@ -220,12 +255,24 @@ export class HostTransferProxy {
             sha256,
             fileBuffer,
             targetClientId: resolvedTargetClientId,
+            targetActorPrincipalId:
+              resolvedTargetClientId != null
+                ? assistantEventHub.getActorPrincipalIdForClient(
+                    resolvedTargetClientId,
+                  )
+                : undefined,
           });
 
           pendingInteractions.register(requestId, {
             conversationId: input.conversationId,
             kind: "host_transfer",
             targetClientId: resolvedTargetClientId,
+            targetActorPrincipalId:
+              resolvedTargetClientId != null
+                ? assistantEventHub.getActorPrincipalIdForClient(
+                    resolvedTargetClientId,
+                  )
+                : undefined,
             rpcResolve: resolve,
             rpcReject: reject,
             timer,
@@ -291,6 +338,8 @@ export class HostTransferProxy {
       targetClientId?: string;
     },
     signal?: AbortSignal,
+    // Principal ID of the actor on whose behalf this request is initiated.
+    sourceActorPrincipalId?: string,
   ): Promise<ToolExecutionResult> {
     if (signal?.aborted) {
       return Promise.resolve({ content: "Aborted", isError: true });
@@ -312,8 +361,29 @@ export class HostTransferProxy {
         });
       }
     } else {
-      const capable = assistantEventHub.listClientsByCapability("host_file");
-      if (capable.length === 1) resolvedTargetClientId = capable[0].clientId;
+      // Auto-resolve to the unique same-user client; reject ambiguous
+      // (multi-machine) cases so a single targeted-style transfer cannot
+      // fan out across the user's machines.
+      const resolved = pickSameUserAutoResolve({
+        hub: assistantEventHub,
+        capability: "host_file",
+        sourceActorPrincipalId,
+      });
+      if (resolved.kind === "ambiguous") {
+        return Promise.resolve(ambiguousSameUserError("host_file"));
+      }
+      resolvedTargetClientId =
+        resolved.kind === "match" ? resolved.clientId : undefined;
+    }
+
+    if (resolvedTargetClientId != null) {
+      const rejection = enforceSameActorOrErrorResult({
+        hub: assistantEventHub,
+        sourceActorPrincipalId,
+        targetClientId: resolvedTargetClientId,
+        op: "host_transfer",
+      });
+      if (rejection != null) return Promise.resolve(rejection);
     }
 
     const requestId = uuid();
@@ -374,12 +444,24 @@ export class HostTransferProxy {
         filePath: input.destPath,
         overwrite: input.overwrite,
         targetClientId: resolvedTargetClientId,
+        targetActorPrincipalId:
+          resolvedTargetClientId != null
+            ? assistantEventHub.getActorPrincipalIdForClient(
+                resolvedTargetClientId,
+              )
+            : undefined,
       });
 
       pendingInteractions.register(requestId, {
         conversationId: input.conversationId,
         kind: "host_transfer",
         targetClientId: resolvedTargetClientId,
+        targetActorPrincipalId:
+          resolvedTargetClientId != null
+            ? assistantEventHub.getActorPrincipalIdForClient(
+                resolvedTargetClientId,
+              )
+            : undefined,
         rpcResolve: resolve,
         rpcReject: reject,
         timer,
@@ -623,6 +705,15 @@ export class HostTransferProxy {
     return this.transfers.get(transferId)?.targetClientId ?? null;
   }
 
+  /**
+   * Look up the persisted `targetActorPrincipalId` for a given transferId
+   * without consuming the entry. Routes call this for the same-actor
+   * binding check so it's stable across brief SSE reconnects.
+   */
+  getTargetActorPrincipalIdForTransfer(transferId: string): string | undefined {
+    return this.transfers.get(transferId)?.targetActorPrincipalId;
+  }
+
   dispose(): void {
     for (const entry of pendingInteractions.getByKind("host_transfer")) {
       const transferId = entry.metadata?.transferId as string | undefined;

package/src/daemon/lifecycle.ts

@@ -54,7 +54,6 @@ import { startMemoryJobsWorker } from "../memory/jobs-worker.js";
 import { initQdrantClient, resolveQdrantUrl } from "../memory/qdrant-client.js";
 import { QdrantManager } from "../memory/qdrant-manager.js";
 import { rotateToolInvocations } from "../memory/tool-usage-store.js";
-import { deleteOldTraceEvents } from "../memory/trace-event-store.js";
 import {
   emitNotificationSignal,
   registerBroadcastFn,
@@ -62,6 +61,7 @@ import {
 import { backfillManualTokenConnections } from "../oauth/manual-token-connection.js";
 import { seedOAuthProviders } from "../oauth/seed-providers.js";
 import { loadUserPlugins } from "../plugins/user-loader.js";
+import { backfillGuardIfNeeded } from "../proactive-artifact/index.js";
 import { ensurePromptFiles } from "../prompts/system-prompt.js";
 import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
@@ -105,6 +105,11 @@ import {
   cleanupPidFileIfOwner,
   writePid,
 } from "./daemon-control.js";
+import {
+  evaluateDiskPressureNow,
+  startDiskPressureGuard,
+  stopDiskPressureGuard,
+} from "./disk-pressure-guard.js";
 import { bootstrapPlugins } from "./external-plugins-bootstrap.js";
 import {
   createGuardianActionCopyGenerator,
@@ -125,11 +130,57 @@ import { DaemonServer } from "./server.js";
 import { installShutdownHandlers } from "./shutdown-handlers.js";
 
 const log = getLogger("lifecycle");
+let diskPressureStartupSampleTimer: ReturnType<typeof setTimeout> | null = null;
 
 function loadDotEnv(): void {
   dotenvConfig({ path: getDotEnvPath(), quiet: true });
 }
 
+function runDeferredDiskPressureStartupSample(): void {
+  diskPressureStartupSampleTimer = null;
+  try {
+    const status = evaluateDiskPressureNow();
+    if (status.error) {
+      log.warn(
+        { error: status.error },
+        "Disk pressure guard sample failed during startup — continuing unlocked",
+      );
+    }
+  } catch (err) {
+    log.warn(
+      { err },
+      "Disk pressure guard failed during startup — continuing unlocked",
+    );
+  }
+}
+
+export function startDiskPressureGuardForLifecycle(): void {
+  try {
+    const startedStatus = startDiskPressureGuard();
+    if (!startedStatus.enabled) return;
+    if (!diskPressureStartupSampleTimer) {
+      diskPressureStartupSampleTimer = setTimeout(
+        runDeferredDiskPressureStartupSample,
+        0,
+      );
+      (diskPressureStartupSampleTimer as { unref?: () => void }).unref?.();
+    }
+  } catch (err) {
+    log.warn(
+      { err },
+      "Disk pressure guard failed during startup — continuing unlocked",
+    );
+  }
+}
+
+export function stopDiskPressureGuardForLifecycle(): void {
+  if (diskPressureStartupSampleTimer) {
+    clearTimeout(diskPressureStartupSampleTimer);
+    diskPressureStartupSampleTimer = null;
+  }
+  stopDiskPressureGuard();
+}
+
 export interface CesStartupResult {
   client: CesClient | undefined;
   processManager: CesProcessManager | undefined;
@@ -448,12 +499,22 @@ export async function runDaemon(): Promise<void> {
       }
     } // end if (dbReady)
 
-    // Seed managed inference profiles into the workspace config. Runs
-    // after workspace migrations (which may have created the initial
-    // profile slots) and before mergeDefaultWorkspaceConfig / loadConfig
-    // so the profiles are on disk for the first config load.
+    // Merge CLI-provided default config (from VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH)
+    // into the workspace config file before profile seeding and the first
+    // loadConfig() call so onboarding/platform preferences are visible to the
+    // seeder and persisted alongside schema defaults.
+    const defaultConfigMerge = mergeDefaultWorkspaceConfig();
+
+    // Seed managed inference profiles into the workspace config. Runs after
+    // workspace migrations and default-config merge, but before loadConfig() so
+    // fresh hatches have profiles on disk before the first config load. Any
+    // profile fields explicitly supplied by the default overlay stay
+    // authoritative for this startup.
     try {
-      seedInferenceProfiles();
+      seedInferenceProfiles({
+        preserveProfileNames: defaultConfigMerge.providedLlmProfileNames,
+        preserveActiveProfile: defaultConfigMerge.providedLlmActiveProfile,
+      });
       log.info("Inference profile seeding complete");
     } catch (err) {
       log.warn(
@@ -462,11 +523,6 @@ export async function runDaemon(): Promise<void> {
       );
     }
 
-    // Merge CLI-provided default config (from VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH)
-    // into the workspace config file before the first loadConfig() call so
-    // onboarding preferences are persisted alongside schema defaults.
-    mergeDefaultWorkspaceConfig();
-
     log.info("Daemon startup: loading config");
     const config = loadConfig();
 
@@ -625,6 +681,7 @@ export async function runDaemon(): Promise<void> {
 
     await server.start();
     log.info("Daemon startup: DaemonServer started");
+    startDiskPressureGuardForLifecycle();
 
     // Kick off the update bulletin background job AFTER `server.start()`
     // resolves. The conversation store must be initialized before wake
@@ -1198,22 +1255,6 @@ export async function runDaemon(): Promise<void> {
       }
     }
 
-    // Prune trace events older than 7 days to keep the database lean.
-    // Deferred so synchronous cleanup doesn't block the startup path.
-    setTimeout(() => {
-      try {
-        const deletedTraceEvents = deleteOldTraceEvents(7);
-        if (deletedTraceEvents > 0) {
-          log.debug(
-            { deletedTraceEvents },
-            `Pruned ${deletedTraceEvents} trace event(s) older than 7 days`,
-          );
-        }
-      } catch (err) {
-        log.warn({ err }, "Trace event cleanup failed");
-      }
-    }, 0);
-
     const workspaceHeartbeat = new WorkspaceHeartbeatService();
     workspaceHeartbeat.start();
 
@@ -1236,6 +1277,12 @@ export async function runDaemon(): Promise<void> {
       "Heartbeat service configured",
     );
 
+    try {
+      backfillGuardIfNeeded();
+    } catch (err) {
+      log.warn({ err }, "Proactive artifact backfill failed");
+    }
+
     // Filing yields to the memory v2 consolidation job when the flag is on —
     // both serve the same role (periodic background memory processing) and
     // running both is redundant. The consolidation job runs through the
@@ -1281,10 +1328,14 @@ export async function runDaemon(): Promise<void> {
       getQdrantManager: () => bgRefs.qdrantManager,
       mcpManager,
       telemetryReporter,
-      cleanupPidFile,
+      cleanupPidFile: () => {
+        stopDiskPressureGuardForLifecycle();
+        cleanupPidFile();
+      },
     });
   } catch (err) {
     log.error({ err }, "Daemon startup failed — cleaning up");
+    stopDiskPressureGuardForLifecycle();
     cleanupPidFileIfOwner(process.pid);
     throw err;
   }

package/src/daemon/meet-host-supervisor.ts

@@ -72,7 +72,7 @@ import { getLogger } from "../util/logger.js";
  * keeps the supervisor free of path assumptions and simplifies
  * tests.
  */
-export interface MeetHostManifest {
+interface MeetHostManifest {
   /** SHA-256 of the shipped skill source tree. */
   sourceHash: string;
 }
@@ -84,7 +84,7 @@ export interface MeetHostManifest {
  * protocol version) can be threaded through later without a
  * signature break.
  */
-export interface MeetHostHandshakePayload {
+interface MeetHostHandshakePayload {
   sourceHash: string;
 }
 
@@ -97,7 +97,7 @@ export interface MeetHostHandshakePayload {
  * supervisor unaware of the rest of the IPC server's surface and avoids a
  * circular import in tests that already stub `skill-server.js`.
  */
-export interface SkillRequestSender {
+interface SkillRequestSender {
   sendRequest(
     connection: SkillIpcConnection,
     method: string,
@@ -111,7 +111,7 @@ export interface SkillRequestSender {
  * child. All are optional on construction — production callers
  * rely on the defaults and tests override one or two at a time.
  */
-export interface MeetHostSupervisorDeps {
+interface MeetHostSupervisorDeps {
   /** Absolute path to the shipped `meet-join` skill dir, containing `register.ts`. */
   skillRuntimePath: string;
   /** Absolute path to a standalone bun binary, or `"bun"` for PATH lookup. */

package/src/daemon/meet-manifest-loader.ts

@@ -109,7 +109,6 @@ const SERIALIZABLE_TOOL_CONTEXT_KEYS = [
   "callSessionId",
   "principal",
   "toolUseId",
-  "memoryScopeId",
   "requesterExternalUserId",
   "requesterChatId",
   "requesterIdentifier",

package/src/daemon/memory-v2-startup.ts

@@ -13,10 +13,12 @@ import { getLogger } from "../util/logger.js";
 const log = getLogger("memory-v2-startup");
 
 /**
- * Fire-and-forget seed of the v2 parallel skill embedding collection. Gated
- * on both the `memory-v2-enabled` feature flag and the workspace-level
- * `config.memory.v2.enabled` switch so v2 modules stay out of the v1 startup
- * path when v2 is off.
+ * Fire-and-forget seed of the v2 skill entries (now indexed alongside concept
+ * pages in `memory_v2_concept_pages` under the `skills/<id>` slug prefix), and
+ * a one-shot best-effort cleanup of the legacy `memory_v2_skills` Qdrant
+ * collection. Gated on both the `memory-v2-enabled` feature flag and the
+ * workspace-level `config.memory.v2.enabled` switch so v2 modules stay out of
+ * the v1 startup path when v2 is off.
  *
  * Uses a dynamic import so v2 code does not load unless the gate passes.
  * Never awaits — startup must not block on this (see `assistant/CLAUDE.md`
@@ -32,4 +34,12 @@ export function maybeSeedMemoryV2Skills(config: AssistantConfig): void {
   void import("../memory/v2/skill-store.js")
     .then(({ seedV2SkillEntries }) => seedV2SkillEntries())
     .catch((err) => log.warn({ err }, "Failed to seed v2 skill entries"));
+  void import("../memory/v2/qdrant.js")
+    .then(({ dropLegacySkillsCollection }) => dropLegacySkillsCollection())
+    .catch((err) =>
+      log.warn(
+        { err },
+        "Failed to drop legacy memory_v2_skills collection — non-fatal",
+      ),
+    );
 }

package/src/daemon/message-protocol.ts

@@ -20,6 +20,7 @@ export * from "./message-types/computer-use.js";
 export * from "./message-types/contacts.js";
 export * from "./message-types/conversations.js";
 export * from "./message-types/diagnostics.js";
+export * from "./message-types/disk-pressure.js";
 export * from "./message-types/documents.js";
 export * from "./message-types/guardian-actions.js";
 export * from "./message-types/home.js";
@@ -71,6 +72,7 @@ import type {
   _DiagnosticsClientMessages,
   _DiagnosticsServerMessages,
 } from "./message-types/diagnostics.js";
+import type { _DiskPressureServerMessages } from "./message-types/disk-pressure.js";
 import type {
   _DocumentsClientMessages,
   _DocumentsServerMessages,
@@ -203,6 +205,7 @@ export type ServerMessage =
   | _NotificationsServerMessages
   | _UpgradesServerMessages
   | _AcpServerMessages
+  | _DiskPressureServerMessages
   | SubagentEvent;
 
 // === Contract schema ===

package/src/daemon/message-types/conversations.ts

@@ -29,6 +29,8 @@ interface BaseTransportMetadata {
   uxBrief?: string;
   /** Chat type from the gateway (e.g. "private", "group", "supergroup", "channel"). */
   chatType?: string;
+  /** IANA timezone reported by the active client for the current turn. */
+  clientTimezone?: string;
 }
 
 /**
@@ -522,6 +524,7 @@ export interface CompactionCircuitClosed {
 export type ConversationErrorCode =
   | "PROVIDER_NETWORK"
   | "PROVIDER_RATE_LIMIT"
+  | "MANAGED_USAGE_LIMIT"
   | "PROVIDER_OVERLOADED"
   | "PROVIDER_API"
   | "PROVIDER_BILLING"
@@ -532,6 +535,7 @@ export type ConversationErrorCode =
   | "CONTEXT_TOO_LARGE"
   | "CONVERSATION_ABORTED"
   | "CONVERSATION_PROCESSING_FAILED"
+  | "DISK_SPACE_CRITICAL"
   | "REGENERATE_FAILED"
   | "UNKNOWN";
 

package/src/daemon/message-types/disk-pressure.ts

@@ -0,0 +1,9 @@
+import type { DiskPressureStatus } from "../disk-pressure-guard.js";
+
+/** Server push when the disk pressure status snapshot changes. */
+export interface DiskPressureStatusChanged {
+  type: "disk_pressure_status_changed";
+  status: DiskPressureStatus;
+}
+
+export type _DiskPressureServerMessages = DiskPressureStatusChanged;

package/src/daemon/message-types/messages.ts

@@ -236,10 +236,13 @@ export interface MessageComplete {
 export interface ErrorMessage {
   type: "error";
   conversationId?: string;
+  requestId?: string;
   code?: string;
   message: string;
   /** Categorizes the error so the client can offer contextual actions (e.g. "Send Anyway" for secret_blocked). */
   category?: string;
+  /** Machine-readable conversation error category for clients that need source-aware recovery UI. */
+  errorCategory?: string;
 }
 
 export interface MessageQueued {

package/src/daemon/profiler-run-store.ts

@@ -73,7 +73,7 @@ const DEFAULT_MIN_FREE_MB = 200;
 
 // ── Result type ─────────────────────────────────────────────────────────
 
-export interface ProfilerSweepResult {
+interface ProfilerSweepResult {
   /** Number of completed runs pruned during this sweep. */
   prunedCount: number;
   /** Total bytes freed by pruning. */
@@ -159,7 +159,7 @@ function getFreeDiskBytes(path: string): number {
 // ── Core operations ─────────────────────────────────────────────────────
 
 /** Options for {@link rescanRuns}. */
-export interface RescanRunsOptions {
+interface RescanRunsOptions {
   /**
    * When true, skip all `writeManifest()` calls — just read existing
    * manifests and recompute sizes without mutating the filesystem.
@@ -384,7 +384,7 @@ export function runProfilerSweep(): ProfilerSweepResult {
 // health-endpoint reporting and control-plane polling.
 
 /** Budget state for the active profiler run. */
-export interface ProfilerBudgetStatus {
+interface ProfilerBudgetStatus {
   /** Configured maximum bytes across all runs. */
   maxBytes: number;
   /** Bytes remaining before the byte-count budget is exceeded. */
@@ -398,7 +398,7 @@ export interface ProfilerBudgetStatus {
 }
 
 /** Summary of the most recently completed profiler run. */
-export interface ProfilerLastCompletedRun {
+interface ProfilerLastCompletedRun {
   runId: string;
   totalBytes: number;
   artifactCount: number;
@@ -407,7 +407,7 @@ export interface ProfilerLastCompletedRun {
 }
 
 /** Full runtime status snapshot for health-endpoint embedding. */
-export interface ProfilerRuntimeStatus {
+interface ProfilerRuntimeStatus {
   /** Whether profiling is enabled (env vars present). */
   enabled: boolean;
   /** The profiling mode ("cpu", "heap", "cpu+heap"), or null when disabled. */

package/src/daemon/tool-setup-types.ts

@@ -21,8 +21,8 @@ export interface ToolSetupContext extends SurfaceConversationContext {
   abortController: AbortController | null;
   /** When set, only tools in this set may execute during the current turn. */
   allowedToolNames?: Set<string>;
-  /** Conversation memory policy used to propagate scopeId into ToolContext. */
-  memoryPolicy: { scopeId: string };
+  /** Turn-scoped disk-pressure cleanup mode flag. */
+  diskPressureCleanupModeActive?: boolean;
   /** True when the conversation has no connected client (HTTP-only path). */
   hasNoClient?: boolean;
   /** When true, the conversation is executing a task run and must not become interactive. */

package/src/documents/document-store.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared document persistence service.
+ *
+ * Extracted from documents-routes.ts so that both HTTP route handlers and
+ * background jobs (e.g. proactive artifact generation) can persist documents
+ * without going through the HTTP layer.
+ */
+import { rawRun } from "../memory/raw-query.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("document-store");
+
+// ---------------------------------------------------------------------------
+// Junction table helper
+// ---------------------------------------------------------------------------
+
+/** Insert a document–conversation association (idempotent via INSERT OR IGNORE). */
+export function addDocumentConversation(
+  surfaceId: string,
+  conversationId: string,
+): void {
+  rawRun(
+    /*sql*/ `INSERT OR IGNORE INTO document_conversations (surface_id, conversation_id, created_at) VALUES (?, ?, ?)`,
+    surfaceId,
+    conversationId,
+    Date.now(),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Document persistence
+// ---------------------------------------------------------------------------
+
+export function saveDocument(params: {
+  surfaceId: string;
+  conversationId: string;
+  title: string;
+  content: string;
+  wordCount: number;
+}): { success: true; surfaceId: string } | { success: false; error: string } {
+  try {
+    const now = Date.now();
+    rawRun(
+      `INSERT INTO documents (surface_id, conversation_id, title, content, word_count, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(surface_id) DO UPDATE SET
+         title = excluded.title,
+         content = excluded.content,
+         word_count = excluded.word_count,
+         updated_at = excluded.updated_at`,
+      params.surfaceId,
+      params.conversationId,
+      params.title,
+      params.content,
+      params.wordCount,
+      now,
+      now,
+    );
+    log.info(
+      { surfaceId: params.surfaceId, title: params.title },
+      "Saved document",
+    );
+
+    // Best-effort: associate the document with the conversation.
+    // Failures (e.g. migration not yet applied, table missing) must not
+    // cause the save response to report failure — the document itself is
+    // already persisted at this point.
+    try {
+      addDocumentConversation(params.surfaceId, params.conversationId);
+    } catch (err) {
+      log.warn(
+        { err, surfaceId: params.surfaceId },
+        "Failed to record document–conversation association",
+      );
+    }
+
+    return { success: true, surfaceId: params.surfaceId };
+  } catch (error) {
+    log.error({ err: error, surfaceId: params.surfaceId }, "Save error");
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}