@vellumai/assistant 0.12.3-staging.1 → 0.12.3

package/src/runtime/background-job-runner.ts

@@ -13,8 +13,8 @@
  *  - never re-throw — the caller always gets a structured result and decides
  *    whether to alert further
  *
- * Producers that have their own bespoke failure UX (e.g. heartbeat's existing
- * alerter banner) can opt out of the failure-emit via
+ * Producers whose failure alerting is owned elsewhere (e.g. the scheduler's
+ * retry policy) can opt out of the failure-emit via
  * `suppressFailureNotifications`.
  */
 
@@ -104,9 +104,9 @@ export interface RunBackgroundJobOptions {
   timeoutMs: number;
   /**
    * When true, failures do NOT emit an `activity.failed` notification.
-   * Use for jobs whose failure alerting is owned elsewhere: heartbeat's
-   * alerter banner, and the scheduler's retry policy (which alerts once,
-   * when retries are exhausted, instead of once per attempt).
+   * Use for jobs whose failure alerting is owned elsewhere, such as the
+   * scheduler's retry policy (which alerts once, when retries are
+   * exhausted, instead of once per attempt).
    */
   suppressFailureNotifications?: boolean;
   /** Conversation grouping id. Defaults to `"system:background"`. */

package/src/runtime/channel-retry-sweep.ts

@@ -547,6 +547,7 @@ export async function sweepFailedEvents(
       },
       assistantId,
       trustContext,
+      author: trustContext,
       isInteractive:
         resolveRoutingStateFromRuntime(trustContext).promptWaitingAllowed,
       onEvent: observeAgentEvent,

package/src/runtime/guardian-action-message-composer.ts

@@ -1,182 +1,29 @@
 /**
- * Layered guardian action message composition system.
+ * Guardian action message composition.
  *
- * Generates user-visible copy for guardian action scenarios through a
- * priority chain:
- *   1. Generator-produced text (when provided by daemon)
- *   2. Deterministic fallback templates (natural, scenario-specific messages)
- *
- * Follows the same pattern as approval-message-composer.ts.
+ * Returns the deterministic, voice-friendly copy for a guardian action
+ * notice. The only notice left is the one the expiry sweep
+ * (`calls/guardian-action-sweep.ts`) sends to each place a guardian request
+ * was delivered once the request expires unanswered.
  */
-import type {
-  ComposeGuardianActionMessageOptions,
-  GuardianActionMessageContext,
-} from "./message-composer-types.js";
+import type { GuardianActionMessageContext } from "./message-composer-types.js";
 
 export type {
-  ComposeGuardianActionMessageOptions,
   GuardianActionMessageContext,
   GuardianActionMessageScenario,
 } from "./message-composer-types.js";
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Compose user-facing guardian action copy using the daemon-injected generator
- * when available, with deterministic fallback for reliability.
- *
- * The generator parameter is the daemon-provided function that knows about
- * providers. When absent (or in test env), only the deterministic fallback
- * is used.
- */
-export async function composeGuardianActionMessageGenerative(
-  context: GuardianActionMessageContext,
-  options: ComposeGuardianActionMessageOptions = {},
-): Promise<string> {
-  const fallbackText =
-    options.fallbackText?.trim() || getGuardianActionFallbackMessage(context);
-
-  if (process.env.NODE_ENV === "test") {
-    return fallbackText;
-  }
-
-  return fallbackText;
-}
-
-/** @internal Exported for use by the daemon-injected generator implementation. */
-export function includesRequiredKeywords(
-  text: string,
-  requiredKeywords: string[] | undefined,
-): boolean {
-  if (!requiredKeywords || requiredKeywords.length === 0) {
-    return true;
-  }
-  return requiredKeywords.every((keyword) => {
-    const re = new RegExp(`\\b${RegExp.escape(keyword)}\\b`, "i");
-    return re.test(text);
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Deterministic fallback templates
-// ---------------------------------------------------------------------------
-
-/**
- * Return a scenario-specific deterministic fallback message.
- *
- * Each template produces natural, conversational text suitable for voice
- * delivery.
- */
-export function getGuardianActionFallbackMessage(
+/** Compose the user-facing copy for a guardian action notice. */
+export function composeGuardianActionMessage(
   context: GuardianActionMessageContext,
 ): string {
-  const listedCodes = formatGuardianRequestCodes(context.requestCodes);
-
   switch (context.scenario) {
-    case "caller_timeout_acknowledgment":
-      return context.guardianIdentifier
-        ? `I wasn't able to reach ${context.guardianIdentifier} right now. I'm sorry about that.`
-        : "I wasn't able to reach the guardian right now. I'm sorry about that.";
-
-    case "caller_timeout_continue":
-      return "Would you like me to leave a message for them to get back to you, or is there anything else I can help with?";
-
-    case "guardian_late_answer_followup":
-      return context.callerIdentifier
-        ? `${context.callerIdentifier} called earlier with a question, but I wasn't able to connect them. Would you like to call them back?`
-        : "Someone called earlier with a question, but I wasn't able to connect them. Would you like to call them back?";
-
-    case "guardian_followup_dispatching":
-      return context.followupAction
-        ? `Got it, I'll ${context.followupAction} now.`
-        : "Got it, I'm taking care of that now.";
-
-    case "guardian_followup_completed":
-      return context.followupAction
-        ? `Done! I've ${context.followupAction} successfully.`
-        : "Done! That's been taken care of.";
-
-    case "guardian_followup_failed":
-      return context.failureReason
-        ? `I'm sorry, I wasn't able to complete that. ${context.failureReason}`
-        : "I'm sorry, I wasn't able to complete that. Please try again later.";
-
-    case "guardian_followup_declined_ack":
-      return "No problem. Let me know if you change your mind or need anything else.";
-
-    case "guardian_followup_clarification":
-      return "Sorry, I didn't quite catch that. Would you like to call them back or skip it for now?";
-
-    case "guardian_pending_disambiguation":
-      return listedCodes
-        ? `You have multiple pending guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
-        : "You have multiple pending guardian questions. Please prefix your reply with the reference code so I know which question you're answering.";
-
-    case "guardian_expired_disambiguation":
-      return listedCodes
-        ? `You have multiple expired guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
-        : "You have multiple expired guardian questions. Please prefix your reply with the reference code so I know which question you're answering.";
-
-    case "guardian_followup_disambiguation":
-      return listedCodes
-        ? `You have multiple pending follow-up questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're responding to.`
-        : "You have multiple pending follow-up questions. Please prefix your reply with the reference code so I know which question you're responding to.";
-
-    case "guardian_stale_answered":
-      return "This question has already been answered from another channel.";
-
     case "guardian_stale_expired":
       return "That request has already expired. No further action is needed.";
 
-    case "guardian_stale_followup":
-      return "It looks like this follow-up has already been handled. No further action is needed.";
-
-    case "guardian_stale_superseded":
-      return "This request is no longer active. The call has ended and no further action is needed.";
-
-    case "guardian_unknown_code":
-      return context.unknownCode
-        ? `I don't recognize the code "${context.unknownCode}". Please check the reference code and try again.`
-        : "I don't recognize that reference code. Please check the code and try again.";
-
-    case "guardian_auto_matched":
-      return "Got it, routing your answer to the active request.";
-
-    case "guardian_superseded_remap":
-      return context.questionText
-        ? `Got it! Your answer has been applied to the current active request: "${context.questionText}"`
-        : "Got it! Your answer has been applied to the current active request on the call.";
-
-    case "followup_call_started":
-      return context.counterpartyPhone
-        ? `Got it! I'm calling ${context.counterpartyPhone} back now to relay your answer.`
-        : "Got it! I'm calling them back now to relay your answer.";
-
-    case "followup_action_failed":
-      return context.failureReason
-        ? `I'm sorry, I wasn't able to complete that. ${context.failureReason}`
-        : "I'm sorry, something went wrong and I couldn't complete that action. Please try again later.";
-
-    case "guardian_answer_delivery_failed":
-      return "I wasn't able to deliver your answer to the call. The call may have ended. Please try again or follow up directly.";
-
     default: {
       const _exhaustive: never = context.scenario;
       return `Guardian action update. ${String(_exhaustive)}`;
     }
   }
 }
-
-function formatGuardianRequestCodes(
-  requestCodes: string[] | undefined,
-): string {
-  if (!Array.isArray(requestCodes)) {
-    return "";
-  }
-  const cleaned = requestCodes
-    .map((code) => code.trim())
-    .filter((code) => code.length > 0);
-  return cleaned.join(", ");
-}

package/src/runtime/guardian-reply-router.ts

@@ -1,13 +1,24 @@
 /**
- * Shared guardian reply router for inbound channel messages.
+ * Shared guardian reply router.
  *
- * Provides a single entry point (`routeGuardianReply`) for all inbound
- * guardian reply processing across Telegram and WhatsApp. Routes
+ * Provides a single entry point (`routeGuardianReply`) for every guardian
+ * reply typed in the app (`daemon/conversation-process.ts`,
+ * `routes/conversation-routes.ts`) and every reply or button press arriving
+ * on a channel (`routes/inbound-stages/guardian-reply-intercept.ts`). App
+ * card buttons decide through `processGuardianDecision()` instead. Routes
  * through a priority-ordered pipeline:
  *
- *   1. Deterministic callback/ref parsing (button presses with `apr:<requestId>:<action>`)
+ *   1. Deterministic callback/ref parsing (channel button presses with `apr:<requestId>:<action>`)
  *   2. Request code parsing (6-char alphanumeric prefix matching)
- *   3. NL classification via the conversational approval engine
+ *   2.5. Invite handoff: "open invite flow" with a pending access request
+ *        passes through to the normal assistant turn
+ *   2.55. Bare-text answer to the single pending question, in the
+ *        conversation it was asked in
+ *   2.6. Explicit approve/reject phrase: applied when exactly one request is
+ *        pending, answered with a disambiguation reply when several are
+ *   3. NL classification via the conversational approval engine, only when
+ *      the caller passes an `approvalConversationGenerator` (app sessions do
+ *      not, so for them 2.6 is the last plain-text stage)
  *
  * All decisions flow through `applyGuardianDecision`, which handles identity
  * validation, expiry checks, the atomic gateway CAS+outcome commit,
@@ -317,17 +328,8 @@ function notConsumed(): GuardianReplyResult {
 // ---------------------------------------------------------------------------
 
 /**
- * Route an inbound guardian reply through the guardian decision pipeline.
- *
- * This is the single entry point for all inbound guardian reply processing.
- * It handles messages from any channel (Telegram, WhatsApp) and
- * routes through priority-ordered matching:
- *
- *   1. Deterministic callback parsing (button presses)
- *   2. Request code parsing (6-char alphanumeric prefix)
- *   3. NL classification via the conversational approval engine
- *
- * All decisions flow through `applyGuardianDecision`.
+ * Route a guardian reply through the priority-ordered pipeline described in
+ * the file header. All decisions flow through `applyGuardianDecision`.
  */
 export async function routeGuardianReply(
   ctx: GuardianReplyContext,
@@ -388,7 +390,7 @@ export async function routeGuardianReply(
       const request = await getGuardianRequestOrNull(answerTap.requestId);
       if (
         request &&
-        resolveRequestInstructionMode(request) === "answer" &&
+        resolveGuardianInstructionModeForRequest(request) === "answer" &&
         parseQuestionAnswerActionId(answerTap.token) &&
         !request.callSessionId &&
         hasLiveQuestionInteraction(request.id)
@@ -581,7 +583,7 @@ export async function routeGuardianReply(
   if (messageText.length > 0 && pendingRequests.length === 1) {
     const soleRequest = pendingRequests[0];
     if (
-      resolveRequestInstructionMode(soleRequest) === "answer" &&
+      resolveGuardianInstructionModeForRequest(soleRequest) === "answer" &&
       !soleRequest.callSessionId &&
       soleRequest.sourceConversationId === conversationId &&
       hasLiveQuestionInteraction(soleRequest.id)
@@ -663,11 +665,11 @@ export async function routeGuardianReply(
     );
 
     if (engineResult.disposition === "keep_pending") {
-      // When the engine returns keep_pending with multiple pending requests,
-      // this likely means the NL classification understood a decision intent
-      // but runApprovalConversationTurn fail-closed because no targetRequestId
-      // was provided. In this case, produce a disambiguation reply instead of
-      // a generic "I couldn't process that" message.
+      // keep_pending covers model indecision and every fail-closed path in
+      // runApprovalConversationTurn (generator error, malformed output, a
+      // decision without the targetRequestId that multi-pending requires).
+      // With several requests pending, answer with a disambiguation reply
+      // instead of a generic "I couldn't process that" message.
       if (pendingRequestsForClassification.length > 1) {
         log.info(
           {
@@ -1005,12 +1007,6 @@ function inferActionFromText(
   return "approve_once";
 }
 
-function resolveRequestInstructionMode(
-  request?: Pick<GuardianRequestWire, "kind" | "toolName"> | null,
-): "approval" | "answer" {
-  return resolveGuardianInstructionModeForRequest(request);
-}
-
 // ---------------------------------------------------------------------------
 // Failure reason reply text
 // ---------------------------------------------------------------------------
@@ -1044,7 +1040,7 @@ function failureReplyText(
       return "Something went wrong with this request on our end, so I couldn't apply your decision.";
     case "invalid_action":
       return buildGuardianInvalidActionReply(
-        resolveRequestInstructionMode(request),
+        resolveGuardianInstructionModeForRequest(request),
         requestCode ?? undefined,
       );
     default:
@@ -1063,7 +1059,7 @@ function failureReplyText(
  */
 function composeCodeOnlyClarification(request: GuardianRequestWire): string {
   const code = request.requestCode ?? "unknown";
-  const mode = resolveRequestInstructionMode(request);
+  const mode = resolveGuardianInstructionModeForRequest(request);
   return buildGuardianCodeOnlyClarification(mode, {
     requestCode: code,
     questionText: request.questionText,
@@ -1087,7 +1083,7 @@ function composeDisambiguationReply(
   const lines: string[] = [];
   const requestsWithMode = pendingRequests.map((request) => ({
     request,
-    mode: resolveRequestInstructionMode(request),
+    mode: resolveGuardianInstructionModeForRequest(request),
   }));
 
   if (engineReplyText) {

package/src/runtime/http-types.ts

@@ -70,6 +70,12 @@ export interface RuntimeMessageConversationOptions {
   };
   assistantId?: string;
   trustContext?: TrustContext;
+  /**
+   * The person whose own inbound message this turn persists. Channel ingress
+   * and its retry replay pass the sender's trust; it names the persisted user
+   * row's author (`PersistMessageOptions.author`).
+   */
+  author?: TrustContext;
   /**
    * Whether this turn should permit interactive approval prompts.
    * Channel ingress sets this true so confirmations can be resolved

package/src/runtime/message-composer-types.ts

@@ -13,36 +13,18 @@ export type ApprovalMessageScenario =
   | "standard_prompt"
   | "guardian_prompt"
   | "reminder_prompt"
-  | "guardian_delivery_failed"
-  | "guardian_request_forwarded"
-  | "guardian_disambiguation"
   | "guardian_identity_mismatch"
   | "request_pending_guardian"
-  | "guardian_decision_outcome"
-  | "guardian_expired_requester"
-  | "guardian_expired_guardian"
-  | "guardian_verify_success"
   | "guardian_verify_failed"
   | "guardian_verify_challenge_setup"
-  | "guardian_verify_status_bound"
-  | "guardian_verify_status_unbound"
-  | "guardian_deny_no_identity"
-  | "guardian_deny_no_binding"
-  | "requester_cancel"
-  | "approval_already_resolved"
-  | "guardian_text_unavailable";
+  | "approval_already_resolved";
 
 export interface ApprovalMessageContext {
   scenario: ApprovalMessageScenario;
   channel?: string;
   toolName?: string;
   requesterIdentifier?: string;
-  guardianIdentifier?: string;
-  pendingCount?: number;
-  decision?: "approved" | "denied";
   richUi?: boolean;
-  /** Pre-existing assistant text to reuse (macOS parity). */
-  assistantPreface?: string;
   verifyCommand?: string;
   ttlSeconds?: number;
   failureReason?: string;
@@ -77,49 +59,9 @@ export type ApprovalCopyGenerator = (
 // Guardian action message types
 // ---------------------------------------------------------------------------
 
-export type GuardianActionMessageScenario =
-  | "caller_timeout_acknowledgment"
-  | "caller_timeout_continue"
-  | "guardian_late_answer_followup"
-  | "guardian_followup_dispatching"
-  | "guardian_followup_completed"
-  | "guardian_followup_failed"
-  | "guardian_followup_declined_ack"
-  | "guardian_followup_clarification"
-  | "guardian_pending_disambiguation"
-  | "guardian_expired_disambiguation"
-  | "guardian_followup_disambiguation"
-  | "guardian_stale_answered"
-  | "guardian_stale_expired"
-  | "guardian_stale_followup"
-  | "guardian_stale_superseded"
-  | "guardian_superseded_remap"
-  | "guardian_unknown_code"
-  | "guardian_auto_matched"
-  | "followup_call_started"
-  | "followup_action_failed"
-  | "guardian_answer_delivery_failed";
+/** The one guardian-action notice still sent: a request expired unanswered. */
+export type GuardianActionMessageScenario = "guardian_stale_expired";
 
 export interface GuardianActionMessageContext {
   scenario: GuardianActionMessageScenario;
-  channel?: string;
-  questionText?: string;
-  callerIdentifier?: string;
-  guardianIdentifier?: string;
-  lateAnswerText?: string;
-  followupAction?: string;
-  failureReason?: string;
-  counterpartyPhone?: string;
-  requestCodes?: string[];
-  /** The code the guardian provided that was not recognized. */
-  unknownCode?: string;
-  /** The code of the active request that supersedes the one the guardian targeted. */
-  activeRequestCode?: string;
-}
-
-export interface ComposeGuardianActionMessageOptions {
-  fallbackText?: string;
-  requiredKeywords?: string[];
-  maxTokens?: number;
-  timeoutMs?: number;
 }

package/src/runtime/migrations/__tests__/vbundle-import-parity.test.ts

@@ -33,7 +33,10 @@ import { Readable } from "node:stream";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import { buildVBundle } from "../vbundle-builder.js";
-import { DefaultPathResolver } from "../vbundle-import-analyzer.js";
+import {
+  analyzeImport,
+  DefaultPathResolver,
+} from "../vbundle-import-analyzer.js";
 import { commitImport } from "../vbundle-importer.js";
 import { streamCommitImport } from "../vbundle-streaming-importer.js";
 import { defaultV1Options } from "./v1-test-helpers.js";
@@ -416,4 +419,67 @@ describe("vbundle import parity (buffer vs streaming)", () => {
     expect(bufferMap.has("marker.txt")).toBe(true);
     expect(streamMap.has("marker.txt")).toBe(true);
   });
+
+  test("F — debug-profile gateway entry: both importers drain it and write nothing", async () => {
+    const configJson = JSON.stringify({ version: 1 });
+    const { archive, manifest } = buildVBundle({
+      files: [
+        { path: "workspace/data/db/assistant.db", data: new Uint8Array(8) },
+        {
+          path: "workspace/config.json",
+          data: new TextEncoder().encode(configJson),
+        },
+        {
+          path: "gateway/export.tar.gz",
+          data: new TextEncoder().encode("not-a-real-tarball"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    // Preflight must not block on the gateway entry, or the CLI would
+    // refuse the restore before either importer runs.
+    const preflight = analyzeImport({
+      manifest,
+      pathResolver: new DefaultPathResolver(bufferWs),
+    });
+    expect(preflight.can_import).toBe(true);
+    expect(preflight.conflicts).toEqual([]);
+
+    mkdirSync(bufferWs, { recursive: true });
+    mkdirSync(streamWs, { recursive: true });
+
+    const bufferResult = commitImport({
+      archiveData: archive,
+      pathResolver: new DefaultPathResolver(bufferWs),
+      workspaceDir: bufferWs,
+    });
+    const streamResult = await streamCommitImport({
+      source: Readable.from([Buffer.from(archive)]),
+      pathResolver: new DefaultPathResolver(streamWs),
+      workspaceDir: streamWs,
+    });
+    if (!bufferResult.ok || !streamResult.ok) {
+      throw new Error("import unexpectedly failed");
+    }
+
+    const bufferMap = walkDiskTree(bufferWs);
+    const streamMap = walkDiskTree(streamWs);
+
+    expect(streamMap).toEqual(bufferMap);
+    expect(bufferMap.has("config.json")).toBe(true);
+    expect(bufferMap.has("data/db/assistant.db")).toBe(true);
+    for (const relPath of bufferMap.keys()) {
+      expect(relPath.startsWith("gateway")).toBe(false);
+    }
+    // Skipped silently, like a retired path: counted, but no
+    // "no known disk target" warning.
+    for (const { report } of [bufferResult, streamResult]) {
+      expect(report.warnings).toEqual([]);
+      const gateway = report.files.find(
+        (f) => f.path === "gateway/export.tar.gz",
+      );
+      expect(gateway?.action).toBe("skipped");
+    }
+  });
 });

package/src/runtime/migrations/vbundle-builder.ts

@@ -71,6 +71,12 @@ export interface VBundleExportOptions {
   include_logs: boolean;
   include_browser_state: boolean;
   include_memory_vectors: boolean;
+  /**
+   * Debug profile: the bundle carries `gateway/export.tar.gz`, the gateway's
+   * database and recent logs, for Vellum staff to inspect. Absent on
+   * ordinary migration bundles.
+   */
+  include_gateway?: boolean;
 }
 
 export interface BuildVBundleOptions {
@@ -697,6 +703,11 @@ export interface BuildExportVBundleOptions {
   checkpoint?: () => void | Promise<void>;
   /** Optional credential entries to include in the archive under credentials/ prefix. */
   credentials?: Array<{ account: string; value: string }>;
+  /**
+   * Extra in-memory entries at exact archive paths, outside `workspace/`.
+   * The debug profile uses this for `gateway/export.tar.gz`.
+   */
+  extraFiles?: Array<{ archivePath: string; data: Uint8Array }>;
 }
 
 /**
@@ -722,6 +733,7 @@ export function buildExportVBundle(
     checkpoint,
     workspaceDir,
     credentials,
+    extraFiles,
   } = options;
 
   // Flush WAL to the main database file before reading so the export
@@ -732,6 +744,9 @@ export function buildExportVBundle(
   }
 
   const files: VBundleFileEntry[] = [];
+  for (const extra of extraFiles ?? []) {
+    files.push({ path: extra.archivePath, data: extra.data });
+  }
 
   // Walk the entire workspace directory, including binary files (DB,
   // attachments) but skipping large/regenerable subdirectories.
@@ -1176,6 +1191,7 @@ export async function streamExportVBundle(
     checkpoint,
     workspaceDir,
     credentials,
+    extraFiles,
   } = options;
 
   // Flush WAL to the main database file before reading. Awaiting allows
@@ -1236,8 +1252,15 @@ export async function streamExportVBundle(
     });
   }
 
-  // Build in-memory entries for credentials (not disk-backed)
+  // Build in-memory entries for credentials and any extra files (not disk-backed)
   const inMemoryEntries: InMemoryEntry[] = [];
+  for (const extra of extraFiles ?? []) {
+    inMemoryEntries.push({
+      archivePath: extra.archivePath,
+      data: extra.data,
+      size: extra.data.length,
+    });
+  }
   if (credentials?.length) {
     for (const { account, value } of credentials) {
       const data = new TextEncoder().encode(value);

package/src/runtime/migrations/vbundle-import-analyzer.ts

@@ -19,7 +19,10 @@ import { join, resolve } from "node:path";
 
 import { resolveGuardianPersonaPath } from "../../prompts/persona-resolver.js";
 import { getLogger } from "../../util/logger.js";
-import { isRetiredArchivePath } from "./vbundle-import-policy.js";
+import {
+  isGatewayArchivePath,
+  isRetiredArchivePath,
+} from "./vbundle-import-policy.js";
 import type { ManifestType } from "./vbundle-validator.js";
 
 const log = getLogger("vbundle-import-analyzer");
@@ -123,7 +126,10 @@ export class DefaultPathResolver implements PathResolver {
     // must never resolve to a disk target — resolving would write them
     // back into the workspace on import. The analyzer and both importers
     // turn the resulting null into a silent non-blocking skip.
-    if (isRetiredArchivePath(archivePath)) {
+    if (
+      isRetiredArchivePath(archivePath) ||
+      isGatewayArchivePath(archivePath)
+    ) {
       return null;
     }
 
@@ -297,10 +303,13 @@ export function analyzeImport(
       // Retired-feature file from a legacy bundle: nothing consumes it
       // anymore, so drop it silently instead of blocking the restore with
       // an UNKNOWN_ARCHIVE_PATH conflict.
-      if (isRetiredArchivePath(fileEntry.path)) {
+      if (
+        isRetiredArchivePath(fileEntry.path) ||
+        isGatewayArchivePath(fileEntry.path)
+      ) {
         log.info(
           { path: fileEntry.path },
-          "Retired archive path in legacy bundle — will be skipped on import",
+          "Archive path is not workspace data — will be skipped on import",
         );
         files.push({
           path: fileEntry.path,

package/src/runtime/migrations/vbundle-import-policy.ts

@@ -57,6 +57,16 @@ export function isRetiredArchivePath(archivePath: string): boolean {
   return RETIRED_ARCHIVE_PATHS.has(archivePath);
 }
 
+/**
+ * `gateway/` holds the gateway's own database and logs, added by the debug
+ * export profile for Vellum staff to open on a debug clone. It is never
+ * part of a workspace, so preflight and both importers skip it silently,
+ * the same way they skip retired paths.
+ */
+export function isGatewayArchivePath(archivePath: string): boolean {
+  return archivePath.startsWith("gateway/");
+}
+
 export function isConfigArchivePath(archivePath: string): boolean {
   return CONFIG_ARCHIVE_PATHS.has(archivePath);
 }

package/src/runtime/migrations/vbundle-importer.ts

@@ -340,7 +340,10 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
         sha256: fileEntry.sha256,
         backup_path: null,
       });
-      if (!policy.isRetiredArchivePath(fileEntry.path)) {
+      if (
+        !policy.isRetiredArchivePath(fileEntry.path) &&
+        !policy.isGatewayArchivePath(fileEntry.path)
+      ) {
         warnings.push(
           `Skipped "${fileEntry.path}": no known disk target for this archive path`,
         );