@vellumai/assistant 0.11.5-dev.202608241517.6c95b21 → 0.11.5-dev.202608241702.d462ce2

package/openapi.yaml

@@ -21254,8 +21254,9 @@ paths:
       summary: Import a .vbundle archive
       description:
         Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes
-        (application/octet-stream), multipart/form-data, or a JSON body with `{ url }` carrying a signed URL the daemon
-        fetches.
+        (application/octet-stream), multipart/form-data, a JSON body with `{ url }` carrying a signed URL the daemon
+        fetches, or a JSON body with `{ path }` pointing at a file staged under the workspace `.restore-staging`
+        directory.
       tags:
         - migrations
       requestBody:
@@ -21266,11 +21267,13 @@ paths:
               type: object
               properties:
                 url:
+                  description: A signed GCS URL pointing to the .vbundle archive (JSON body path only).
                   type: string
                   format: uri
-                  description: A signed GCS URL pointing to the .vbundle archive (JSON body path only).
-              required:
-                - url
+                path:
+                  description: Workspace-relative or absolute path to a staged .vbundle under .restore-staging (JSON body path only).
+                  type: string
+                  minLength: 1
       responses:
         "200":
           description: Successful response
@@ -21353,9 +21356,23 @@ paths:
     post:
       operationId: migrations_importpreflight_post
       summary: Dry-run import analysis
-      description: Validate a .vbundle archive and return a report of what would change on import without modifying data.
+      description:
+        Validate a .vbundle archive and return a report of what would change on import without modifying data.
+        Accepts raw bytes, multipart form data, or JSON `{ path }` pointing at a file staged under the workspace
+        `.restore-staging` directory.
       tags:
         - migrations
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                path:
+                  description: Workspace-relative or absolute path to a staged .vbundle under .restore-staging (JSON body path only).
+                  type: string
+                  minLength: 1
       responses:
         "200":
           description: Successful response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.5-dev.202608241517.6c95b21",
+  "version": "0.11.5-dev.202608241702.d462ce2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/migration-import-from-path.test.ts

@@ -0,0 +1,349 @@
+/**
+ * HTTP tests for JSON `{ path }` on POST /v1/migrations/import and
+ * POST /v1/migrations/import-preflight.
+ *
+ * The daemon only opens a regular `.vbundle` that realpath-resolves
+ * under `${workspace}/.restore-staging/`.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+mock.module("../permissions/trust-store.js", () => ({
+  getAllRules: () => [],
+  isStarterBundleAccepted: () => false,
+  clearCache: () => {},
+}));
+
+mock.module("../config/env.js", () => ({
+  isHttpAuthDisabled: () => true,
+  hasUngatedHttpAuthDisabled: () => false,
+  getGatewayInternalBaseUrl: () => "http://127.0.0.1:7830",
+  getGatewayPort: () => 7830,
+  getRuntimeHttpPort: () => 7821,
+  getRuntimeHttpHost: () => "127.0.0.1",
+  getRuntimeGatewayOriginSecret: () => undefined,
+  getIngressPublicBaseUrl: () => undefined,
+  setIngressPublicBaseUrl: () => {},
+}));
+
+import { defaultV1Options } from "../runtime/migrations/__tests__/v1-test-helpers.js";
+import { RESTORE_STAGING_DIRNAME } from "../runtime/migrations/staged-import-path.js";
+import { buildVBundle } from "../runtime/migrations/vbundle-builder.js";
+import {
+  handleMigrationImport,
+  handleMigrationImportPreflight,
+} from "../runtime/routes/migration-routes.js";
+import { callHandler } from "./helpers/call-route-handler.js";
+
+const originalWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+
+function freshWorkspaceRoot(): string {
+  const parent = realpathSync(
+    mkdtempSync(join(tmpdir(), "migration-import-from-path-")),
+  );
+  const workspaceDir = join(parent, "workspace");
+  mkdirSync(workspaceDir, { recursive: true });
+  return workspaceDir;
+}
+
+function setWorkspaceDir(dir: string): void {
+  process.env.VELLUM_WORKSPACE_DIR = dir;
+}
+
+function makeSmallValidBundle(): Uint8Array {
+  const { archive } = buildVBundle({
+    files: [
+      {
+        path: "workspace/data/db/assistant.db",
+        data: new TextEncoder().encode("SQLite format 3\0"),
+      },
+      {
+        path: "workspace/config.json",
+        data: new TextEncoder().encode(
+          JSON.stringify({ provider: "anthropic", model: "test-model" }),
+        ),
+      },
+    ],
+    ...defaultV1Options(),
+  });
+  return archive;
+}
+
+function stageBundle(workspaceDir: string, archive: Uint8Array): string {
+  const staging = join(workspaceDir, RESTORE_STAGING_DIRNAME);
+  mkdirSync(staging, { recursive: true });
+  const filename = "backup.vbundle";
+  writeFileSync(join(staging, filename), archive);
+  return `${RESTORE_STAGING_DIRNAME}/${filename}`;
+}
+
+interface ImportCommitResponse {
+  success: boolean;
+  summary: {
+    total_files: number;
+    files_created: number;
+    files_overwritten: number;
+    files_skipped: number;
+    backups_created: number;
+  };
+  files: Array<{ path: string }>;
+  manifest: Record<string, unknown>;
+}
+
+interface PreflightResponse {
+  can_import: boolean;
+  summary?: {
+    files_to_create: number;
+    files_to_overwrite: number;
+    files_unchanged: number;
+    total_files: number;
+  };
+  validation?: { is_valid: false; errors: Array<{ code: string }> };
+}
+
+interface BadRequestResponse {
+  error: { code: string; message: string };
+}
+
+let testWorkspaceRoot: string;
+let testParent: string;
+
+beforeEach(() => {
+  testWorkspaceRoot = freshWorkspaceRoot();
+  testParent = join(testWorkspaceRoot, "..");
+  setWorkspaceDir(testWorkspaceRoot);
+});
+
+afterEach(() => {
+  try {
+    rmSync(testParent, { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+});
+
+afterAll(() => {
+  if (originalWorkspaceDir !== undefined) {
+    process.env.VELLUM_WORKSPACE_DIR = originalWorkspaceDir;
+  } else {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  }
+});
+
+describe("handleMigrationImport — JSON {path} body", () => {
+  test("happy path: streams a staged .vbundle and imports it", async () => {
+    const relativePath = stageBundle(
+      testWorkspaceRoot,
+      makeSmallValidBundle(),
+    );
+
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: relativePath }),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    const body = (await res.json()) as ImportCommitResponse;
+
+    expect(res.status).toBe(200);
+    expect(body.success).toBe(true);
+    expect(body.summary.total_files).toBeGreaterThan(0);
+    expect(body.files.length).toBeGreaterThan(0);
+    expect(existsSync(join(testWorkspaceRoot, "data", "db", "assistant.db"))).toBe(
+      true,
+    );
+    expect(existsSync(join(testWorkspaceRoot, "config.json"))).toBe(true);
+  });
+
+  test("absolute path inside staging is accepted", async () => {
+    const relativePath = stageBundle(
+      testWorkspaceRoot,
+      makeSmallValidBundle(),
+    );
+    const absolutePath = join(testWorkspaceRoot, relativePath);
+
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: absolutePath }),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as ImportCommitResponse;
+    expect(body.success).toBe(true);
+  });
+
+  test("both url and path returns 400", async () => {
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        url: "https://storage.googleapis.com/b/o?X-Goog-Signature=x",
+        path: `${RESTORE_STAGING_DIRNAME}/backup.vbundle`,
+      }),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    const body = (await res.json()) as BadRequestResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message).toContain("exactly one");
+  });
+
+  test("missing staged file returns 400", async () => {
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        path: `${RESTORE_STAGING_DIRNAME}/missing.vbundle`,
+      }),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    const body = (await res.json()) as BadRequestResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message.toLowerCase()).toContain("not found");
+  });
+
+  test("traversal out of staging returns 400", async () => {
+    writeFileSync(join(testWorkspaceRoot, "secret.vbundle"), "nope");
+
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        path: `${RESTORE_STAGING_DIRNAME}/../secret.vbundle`,
+      }),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    const body = (await res.json()) as BadRequestResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message.toLowerCase()).toContain("staging");
+  });
+
+  test("path outside the workspace returns 400", async () => {
+    const outside = join(testParent, "outside.vbundle");
+    writeFileSync(outside, "nope");
+
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: outside }),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    const body = (await res.json()) as BadRequestResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message.toLowerCase()).toContain("staging");
+  });
+
+  test("symlink in staging returns 400", async () => {
+    const relativePath = stageBundle(
+      testWorkspaceRoot,
+      makeSmallValidBundle(),
+    );
+    const target = join(testWorkspaceRoot, relativePath);
+    const link = join(testWorkspaceRoot, RESTORE_STAGING_DIRNAME, "alias.vbundle");
+    symlinkSync(target, link);
+
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        path: `${RESTORE_STAGING_DIRNAME}/alias.vbundle`,
+      }),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    const body = (await res.json()) as BadRequestResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message.toLowerCase()).toContain("symlink");
+  });
+});
+
+describe("handleMigrationImportPreflight — JSON {path} body", () => {
+  test("happy path: analyzes a staged .vbundle without writing files", async () => {
+    const relativePath = stageBundle(
+      testWorkspaceRoot,
+      makeSmallValidBundle(),
+    );
+
+    const req = new Request("http://localhost/v1/migrations/import-preflight", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: relativePath }),
+    });
+
+    const res = await callHandler(handleMigrationImportPreflight, req);
+    const body = (await res.json()) as PreflightResponse;
+
+    expect(res.status).toBe(200);
+    expect(body.can_import).toBe(true);
+    expect(body.summary?.total_files).toBeGreaterThan(0);
+    expect(existsSync(join(testWorkspaceRoot, "config.json"))).toBe(false);
+  });
+
+  test("empty path returns 400", async () => {
+    const req = new Request("http://localhost/v1/migrations/import-preflight", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: "" }),
+    });
+
+    const res = await callHandler(handleMigrationImportPreflight, req);
+    const body = (await res.json()) as BadRequestResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("BAD_REQUEST");
+  });
+
+  test("non-.vbundle staging file returns 400", async () => {
+    const staging = join(testWorkspaceRoot, RESTORE_STAGING_DIRNAME);
+    mkdirSync(staging, { recursive: true });
+    writeFileSync(join(staging, "notes.txt"), "nope");
+
+    const req = new Request("http://localhost/v1/migrations/import-preflight", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: `${RESTORE_STAGING_DIRNAME}/notes.txt` }),
+    });
+
+    const res = await callHandler(handleMigrationImportPreflight, req);
+    const body = (await res.json()) as BadRequestResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message.toLowerCase()).toContain(".vbundle");
+  });
+});

package/src/live-voice/__tests__/live-voice-session-telemetry.test.ts

@@ -147,9 +147,12 @@ describe("live-voice session telemetry", () => {
 
     await session.close("client_end");
 
+    // These sessions reach `ready` and are closed without ever sending audio,
+    // so they are silent by construction and the reason says which layer
+    // stopped short. See `telemetry/live-voice-funnel.ts`.
     expect(recordLiveVoiceSessionEnded).toHaveBeenCalledWith({
       sessionId: "session-123",
-      screen: "ended_client_end",
+      screen: "ended_client_end:silent_no_audio",
       outcome: "completed",
     });
   });
@@ -164,7 +167,7 @@ describe("live-voice session telemetry", () => {
     // the reason on `screen` is what distinguishes a drop from a hangup.
     expect(recordLiveVoiceSessionEnded).toHaveBeenCalledWith({
       sessionId: "session-123",
-      screen: "ended_websocket_close",
+      screen: "ended_websocket_close:silent_no_audio",
       outcome: "completed",
     });
   });

package/src/live-voice/live-voice-session.ts

@@ -71,7 +71,10 @@ import type {
   SttStreamServerEvent,
 } from "../stt/types.js";
 import { getSubagentManager } from "../subagent/index.js";
-import { liveVoiceEndScreen } from "../telemetry/live-voice-funnel.js";
+import {
+  liveVoiceEndScreen,
+  liveVoiceSilenceReason,
+} from "../telemetry/live-voice-funnel.js";
 import { getToolOwner } from "../tools/registry.js";
 import {
   createReasoningTagFilter,
@@ -1126,6 +1129,20 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
    * session that never failed.
    */
   private failureCode: LiveVoiceProtocolErrorCode | null = null;
+  /**
+   * How far a session that never produced a turn actually got. Latched rather
+   * than derived at close, because every one of these is a transient the
+   * teardown has already destroyed by then: `state` has moved on, the current
+   * utterance is gone, and the turn detector is disposed.
+   *
+   * A quarter of sessions end with no turn at all, and these three booleans are
+   * what separate a microphone that never opened from one that was muted from a
+   * user who simply left. See `telemetry/live-voice-funnel.ts`.
+   */
+  private reachedActive = false;
+  private receivedAudio = false;
+  private detectedSpeech = false;
+  private dispatchedTurn = false;
   // Non-null iff the start frame requested turnDetection "server_vad".
   private readonly turnDetector: MediaTurnDetector | null;
   // Base energy gate for server-VAD speech classification. During estimated
@@ -1419,6 +1436,7 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
     // through the pending/pre-roll paths and flushes on arm. An arm failure
     // surfaces as a non-recoverable error frame instead of a start rejection.
     this.state = "active";
+    this.reachedActive = true;
     void this.armUtterance().catch(() => {});
     this.metrics.markReady();
     await this.sendFrame({
@@ -1522,9 +1540,22 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
     // `recorded_at` minus the started row's, so it must be written before the
     // teardown below, which awaits a pending continuation and can run long.
     const failed = this.state === "failed";
+    // Only a session that never dispatched a turn gets a silence reason; for
+    // every other session the question is meaningless.
+    const silenceReason = this.dispatchedTurn
+      ? null
+      : liveVoiceSilenceReason({
+          reachedActive: this.reachedActive,
+          receivedAudio: this.receivedAudio,
+          detectedSpeech: this.detectedSpeech,
+        });
     recordLiveVoiceSessionEnded({
       sessionId: this.context.sessionId,
-      screen: liveVoiceEndScreen(reason, failed ? this.failureCode : null),
+      screen: liveVoiceEndScreen(
+        reason,
+        failed ? this.failureCode : null,
+        silenceReason,
+      ),
       outcome: failed ? "failed" : "completed",
     });
 
@@ -1831,6 +1862,11 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
   }
 
   private async handleAudio(chunk: Buffer): Promise<void> {
+    // Both transports funnel through here, and this runs before any of the
+    // early returns below. The question it answers is "did the microphone ever
+    // open", which a chunk arriving at all settles regardless of what the
+    // session then does with it.
+    this.receivedAudio = true;
     if (this.turnDetector) {
       await this.handleServerVadAudio(this.turnDetector, chunk);
       return;
@@ -1849,6 +1885,10 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
     // The chunk belongs to an utterance the user is still holding the button
     // for, whether or not the transcriber has produced any text for it yet.
     utterance.manualAudioCaptured = true;
+    // Manual sessions have no VAD, so the user holding the talk button is
+    // the only speech signal available. Without this every abandoned manual
+    // session would be misfiled as `no_turn` instead of `no_speech`.
+    this.detectedSpeech = true;
     this.collectUserAudio(utterance, chunk);
     if (utterance.phase === "pending") {
       // The transcriber is still arming (session start overlaps the STT
@@ -1968,6 +2008,7 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
     // resets it.
     if (hasSpeech || this.vadPreRollHasSpeech) {
       utterance.speechRouted = true;
+      this.detectedSpeech = true;
     }
     for (const preRollChunk of this.takeVadPreRoll()) {
       await this.routeVadAudio(utterance, preRollChunk);
@@ -2221,6 +2262,7 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
     }
     if (preRollHadSpeech) {
       utterance.speechRouted = true;
+      this.detectedSpeech = true;
     }
   }
 
@@ -4725,6 +4767,14 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
     };
 
     try {
+      // Latched before the await, not after: this flag only decides whether the
+      // end event carries a silence classification, and the dashboard decides
+      // silence from persisted turn rows instead. Setting it after would let a
+      // dispatch that persisted a turn and then threw stamp "this session was
+      // silent" onto a session that has turns, a contradictory row. Setting it
+      // before can at worst leave a silent session unexplained, which is a gap
+      // rather than a false statement.
+      this.dispatchedTurn = true;
       const handle = await this.startVoiceTurn({
         conversationId: this.conversationId,
         voiceSessionId: this.context.sessionId,

package/src/runtime/migrations/__tests__/staged-import-path.test.ts

@@ -0,0 +1,104 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  resolveStagedImportPath,
+  RESTORE_STAGING_DIRNAME,
+  StagedImportPathError,
+} from "../staged-import-path.js";
+
+function stagingWorkspace(): { workspace: string; staging: string } {
+  const workspace = realpathSync(mkdtempSync(join(tmpdir(), "staged-import-")));
+  const staging = join(workspace, RESTORE_STAGING_DIRNAME);
+  mkdirSync(staging, { recursive: true });
+  return { workspace, staging };
+}
+
+describe("resolveStagedImportPath", () => {
+  test("resolves a relative path inside the staging directory", () => {
+    const { workspace, staging } = stagingWorkspace();
+    const file = join(staging, "backup.vbundle");
+    writeFileSync(file, "bundle");
+
+    expect(
+      resolveStagedImportPath(`${RESTORE_STAGING_DIRNAME}/backup.vbundle`, workspace),
+    ).toBe(realpathSync(file));
+  });
+
+  test("resolves an absolute path inside the staging directory", () => {
+    const { workspace, staging } = stagingWorkspace();
+    const file = join(staging, "backup.vbundle");
+    writeFileSync(file, "bundle");
+
+    expect(resolveStagedImportPath(file, workspace)).toBe(realpathSync(file));
+  });
+
+  test("rejects a missing file", () => {
+    const { workspace } = stagingWorkspace();
+    expect(() =>
+      resolveStagedImportPath(
+        `${RESTORE_STAGING_DIRNAME}/missing.vbundle`,
+        workspace,
+      ),
+    ).toThrow(StagedImportPathError);
+  });
+
+  test("rejects traversal out of the staging directory", () => {
+    const { workspace } = stagingWorkspace();
+    writeFileSync(join(workspace, "secret.vbundle"), "nope");
+
+    expect(() =>
+      resolveStagedImportPath(
+        `${RESTORE_STAGING_DIRNAME}/../secret.vbundle`,
+        workspace,
+      ),
+    ).toThrow(StagedImportPathError);
+  });
+
+  test("rejects a path outside the workspace", () => {
+    const { workspace } = stagingWorkspace();
+    const outside = join(tmpdir(), `outside-${Date.now()}.vbundle`);
+    writeFileSync(outside, "nope");
+
+    expect(() => resolveStagedImportPath(outside, workspace)).toThrow(
+      StagedImportPathError,
+    );
+  });
+
+  test("rejects a symlink even when it points at a staging file", () => {
+    const { workspace, staging } = stagingWorkspace();
+    const file = join(staging, "backup.vbundle");
+    writeFileSync(file, "bundle");
+    const link = join(staging, "alias.vbundle");
+    symlinkSync(file, link);
+
+    expect(() => resolveStagedImportPath(link, workspace)).toThrow(
+      StagedImportPathError,
+    );
+  });
+
+  test("rejects a non-.vbundle file in staging", () => {
+    const { workspace, staging } = stagingWorkspace();
+    const file = join(staging, "notes.txt");
+    writeFileSync(file, "nope");
+
+    expect(() =>
+      resolveStagedImportPath(`${RESTORE_STAGING_DIRNAME}/notes.txt`, workspace),
+    ).toThrow(StagedImportPathError);
+  });
+
+  test("rejects an empty path", () => {
+    const { workspace } = stagingWorkspace();
+    expect(() => resolveStagedImportPath("   ", workspace)).toThrow(
+      StagedImportPathError,
+    );
+  });
+});

package/src/runtime/migrations/staged-import-path.ts

@@ -0,0 +1,116 @@
+/**
+ * Resolve a caller-supplied staged-bundle path for local restore.
+ *
+ * The daemon only opens files that realpath into
+ * `${workspaceDir}/.restore-staging/`. Absolute host paths, `..`
+ * traversal, and symlink escapes are rejected.
+ */
+
+import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+
+export const RESTORE_STAGING_DIRNAME = ".restore-staging";
+
+export type StagedImportPathErrorCode =
+  | "empty"
+  | "not_found"
+  | "not_file"
+  | "symlink"
+  | "outside"
+  | "extension";
+
+export class StagedImportPathError extends Error {
+  public readonly code: StagedImportPathErrorCode;
+
+  constructor(code: StagedImportPathErrorCode, message: string) {
+    super(message);
+    this.name = "StagedImportPathError";
+    this.code = code;
+  }
+}
+
+/**
+ * Resolve `requestedPath` to a regular `.vbundle` file inside the
+ * workspace restore-staging directory.
+ */
+export function resolveStagedImportPath(
+  requestedPath: string,
+  workspaceDir: string,
+): string {
+  if (typeof requestedPath !== "string" || requestedPath.trim().length === 0) {
+    throw new StagedImportPathError("empty", "Staged bundle path is empty");
+  }
+  if (requestedPath.includes("\0")) {
+    throw new StagedImportPathError(
+      "empty",
+      "Staged bundle path is not a valid file path",
+    );
+  }
+
+  if (!existsSync(workspaceDir)) {
+    throw new StagedImportPathError(
+      "not_found",
+      "Staged bundle file not found",
+    );
+  }
+
+  const workspaceReal = realpathSync(workspaceDir);
+  const stagingRoot = resolve(workspaceReal, RESTORE_STAGING_DIRNAME);
+  const candidate = requestedPath.startsWith("/")
+    ? resolve(requestedPath)
+    : resolve(workspaceReal, requestedPath);
+
+  if (!existsSync(candidate)) {
+    throw new StagedImportPathError(
+      "not_found",
+      "Staged bundle file not found",
+    );
+  }
+
+  const linkStat = lstatSync(candidate);
+  if (linkStat.isSymbolicLink()) {
+    throw new StagedImportPathError(
+      "symlink",
+      "Staged bundle path must not be a symlink",
+    );
+  }
+
+  const realFile = realpathSync(candidate);
+  if (!existsSync(stagingRoot)) {
+    throw new StagedImportPathError(
+      "outside",
+      "Staged bundle path is not inside the restore staging directory",
+    );
+  }
+
+  const realStaging = realpathSync(stagingRoot);
+  const rel = relative(realStaging, realFile);
+  if (
+    rel === "" ||
+    rel.startsWith(`..${sep}`) ||
+    rel === ".." ||
+    rel.split(sep).includes("..")
+  ) {
+    throw new StagedImportPathError(
+      "outside",
+      "Staged bundle path is not inside the restore staging directory",
+    );
+  }
+
+  const fileStat = statSync(realFile);
+  if (!fileStat.isFile()) {
+    throw new StagedImportPathError(
+      "not_file",
+      "Staged bundle path is not a file",
+    );
+  }
+
+  if (!realFile.endsWith(".vbundle")) {
+    throw new StagedImportPathError(
+      "extension",
+      "Staged bundle must be a .vbundle file",
+    );
+  }
+
+  return realFile;
+}

package/src/runtime/routes/migration-routes.ts

@@ -7,9 +7,11 @@
  * POST /v1/migrations/import          — commit a .vbundle archive import to disk.
  *
  * Accepts raw binary body (Content-Type: application/octet-stream),
- * multipart form data with a "file" field, or — on /import only — a JSON
- * body of shape `{ "url": "<signed-gcs-url>" }` that causes the daemon to
- * fetch the bundle from GCS and stream it through `streamCommitImport`.
+ * multipart form data with a "file" field, or a JSON body of shape
+ * `{ "url": "<signed-gcs-url>" }` (import only) or `{ "path": "<staged>" }`
+ * (import and import-preflight). The path form streams a file the CLI
+ * staged under `${workspace}/.restore-staging/`. The URL form fetches the
+ * bundle from GCS and streams it through `streamCommitImport`.
  * Returns structured validation results with is_valid flag and detailed
  * error descriptions.
  */
@@ -58,6 +60,10 @@ import {
   migrationJobs,
 } from "../migrations/job-registry.js";
 import { getOriginMode } from "../migrations/origin-mode.js";
+import {
+  resolveStagedImportPath,
+  StagedImportPathError,
+} from "../migrations/staged-import-path.js";
 import type {
   VBundleAssistantInfo,
   VBundleCompatibility,
@@ -81,6 +87,11 @@ import {
   type ImportCommitResult,
 } from "../migrations/vbundle-importer.js";
 import { streamCommitImport } from "../migrations/vbundle-streaming-importer.js";
+import {
+  readAndValidateManifest,
+  StreamingValidationError,
+} from "../migrations/vbundle-streaming-validator.js";
+import { parseVBundleStream } from "../migrations/vbundle-tar-stream.js";
 import { validateVBundle } from "../migrations/vbundle-validator.js";
 import {
   BadGatewayError,
@@ -806,6 +817,8 @@ async function extractFileData(
  * The file can be sent as:
  * - Raw binary body with Content-Type: application/octet-stream
  * - Multipart form data with a "file" field
+ * - JSON body `{ "path": "<staged-relative-or-absolute>" }` pointing at a
+ *   `.vbundle` the caller placed under `${workspace}/.restore-staging/`
  *
  * Returns:
  *   200: {
@@ -825,7 +838,13 @@ async function extractFileData(
 export async function handleMigrationImportPreflight({
   rawBody,
   headers,
+  body,
 }: RouteHandlerArgs) {
+  const contentType = headers?.["content-type"] ?? "";
+  if (contentType.includes("application/json")) {
+    return handleMigrationPreflightFromPath(body);
+  }
+
   const fileData = await extractFileData(rawBody, headers);
 
   try {
@@ -872,15 +891,18 @@ export async function handleMigrationImportPreflight({
  * 5. Verifies post-write integrity (SHA-256 check)
  * 6. Returns a detailed report of what was imported
  *
- * The bundle can be supplied in any of three ways:
+ * The bundle can be supplied as:
  * - Raw binary body with Content-Type: application/octet-stream
  * - Multipart form data with a "file" field
  * - JSON body `{ "url": "<signed-gcs-url>" }` (Content-Type:
  *   application/json). The daemon fetches and streams the archive
  *   through `streamCommitImport`, so peak memory stays bounded by a
  *   single tar entry rather than bundle size.
+ * - JSON body `{ "path": "<staged>" }` pointing at a `.vbundle` the
+ *   caller placed under `${workspace}/.restore-staging/`. The daemon
+ *   streams that file through `streamCommitImport`.
  *
- * Returns (all three paths):
+ * Returns:
  *   200: {
  *     success: true,
  *     summary: { total_files, files_created, files_overwritten, files_skipped, backups_created },
@@ -900,11 +922,10 @@ export async function handleMigrationImport(
   args: RouteHandlerArgs,
 ): Promise<unknown> {
   const { body, rawBody, headers } = args;
-  // JSON body means the caller is asking us to fetch the bundle from a
-  // signed URL and stream it through the importer.
+  // JSON body is either a signed URL fetch or a staged local-file stream.
   const contentType = headers?.["content-type"] ?? "";
   if (contentType.includes("application/json")) {
-    return handleMigrationImportFromUrl(body);
+    return handleMigrationImportFromJson(body);
   }
 
   const fileData = await extractFileData(rawBody, headers);
@@ -1015,6 +1036,8 @@ const URL_FETCH_TIMEOUT_MS = 60 * 60 * 1000;
 
 const MigrationImportUrlBody = z.object({ url: z.string().min(1) });
 
+const MigrationImportPathBody = z.object({ path: z.string().min(1) });
+
 const MigrationImportFromGcsBody = z.object({ bundle_url: z.string().url() });
 
 /**
@@ -1591,6 +1614,174 @@ async function runGcsImport(
     : { ...result.report };
 }
 
+/**
+ * Dispatch a JSON import body to the URL-fetch or staged-path streamer.
+ * The body must include exactly one of `url` or `path`.
+ */
+async function handleMigrationImportFromJson(
+  body: Record<string, unknown> | undefined,
+): Promise<unknown> {
+  const hasUrl = typeof body?.url === "string";
+  const hasPath = typeof body?.path === "string";
+  if (hasUrl && hasPath) {
+    throw new BadRequestError(
+      "Request body must include exactly one of url or path",
+    );
+  }
+  if (hasPath) {
+    return handleMigrationImportFromPath(body);
+  }
+  return handleMigrationImportFromUrl(body);
+}
+
+async function handleMigrationImportFromPath(
+  body: Record<string, unknown> | undefined,
+): Promise<unknown> {
+  const parsed = MigrationImportPathBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "Request body must be { path: string } with a non-empty path",
+    );
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = resolveStagedImportPath(parsed.data.path, getWorkspaceDir());
+  } catch (err) {
+    if (err instanceof StagedImportPathError) {
+      throw new BadRequestError(err.message);
+    }
+    throw err;
+  }
+
+  const source = createReadStream(resolvedPath);
+  const pathResolver = new DefaultPathResolver(
+    getWorkspaceDir(),
+    getWorkspaceHooksDir(),
+  );
+  let credentialsImported: CredentialImportSummary | undefined;
+  const credentialImportWarningSink: CredentialWarningSink = { warnings: [] };
+
+  try {
+    const result = await streamCommitImport({
+      source,
+      pathResolver,
+      workspaceDir: getWorkspaceDir(),
+      importCredentials: async (bundleCredentials) => {
+        credentialsImported = await importBundleCredentialsIntoCes(
+          bundleCredentials,
+          credentialImportWarningSink,
+        );
+      },
+    });
+
+    if (!result.ok) {
+      throwImportCommitFailure(result);
+    }
+
+    if (credentialImportWarningSink.warnings.length > 0) {
+      result.report.warnings.push(...credentialImportWarningSink.warnings);
+    }
+
+    await reconcileVellumMetadataFromCes(result.report);
+    appendNewerMigrationWarningsIfAny(result.report);
+    return importCommitSuccessResult(result.report, credentialsImported);
+  } catch (err) {
+    if (err instanceof RouteError) {
+      throw err;
+    }
+    log.error({ err }, "Unexpected error during staged-path import");
+    throw new InternalError(
+      err instanceof Error ? err.message : "Unexpected import error",
+    );
+  } finally {
+    source.destroy();
+  }
+}
+
+async function handleMigrationPreflightFromPath(
+  body: Record<string, unknown> | undefined,
+): Promise<unknown> {
+  const parsed = MigrationImportPathBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "Request body must be { path: string } with a non-empty path",
+    );
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = resolveStagedImportPath(parsed.data.path, getWorkspaceDir());
+  } catch (err) {
+    if (err instanceof StagedImportPathError) {
+      throw new BadRequestError(err.message);
+    }
+    throw err;
+  }
+
+  const source = createReadStream(resolvedPath);
+  try {
+    const entries = parseVBundleStream(source);
+    const first = await entries.next();
+    if (first.done) {
+      return {
+        can_import: false,
+        validation: {
+          is_valid: false as const,
+          errors: [
+            {
+              code: "empty_archive",
+              message: "Bundle archive is empty",
+            },
+          ],
+        },
+      };
+    }
+
+    let manifest;
+    try {
+      ({ manifest } = await readAndValidateManifest(first.value));
+    } catch (err) {
+      if (err instanceof StreamingValidationError) {
+        return {
+          can_import: false,
+          validation: {
+            is_valid: false as const,
+            errors: [
+              {
+                code: err.code,
+                message: err.message,
+                ...(err.archivePath !== undefined && { path: err.archivePath }),
+              },
+            ],
+          },
+        };
+      }
+      throw err;
+    }
+
+    for await (const entry of entries) {
+      entry.body.resume();
+    }
+
+    const pathResolver = new DefaultPathResolver(
+      getWorkspaceDir(),
+      getWorkspaceHooksDir(),
+    );
+    return analyzeImport({ manifest, pathResolver });
+  } catch (err) {
+    if (err instanceof RouteError) {
+      throw err;
+    }
+    log.error({ err }, "Unexpected error during staged-path preflight");
+    throw new InternalError(
+      err instanceof Error ? err.message : "Unexpected import preflight error",
+    );
+  } finally {
+    source.destroy();
+  }
+}
+
 /**
  * Handle a JSON `{ "url": "..." }` body on POST /v1/migrations/import.
  *
@@ -2142,8 +2333,17 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Dry-run import analysis",
     description:
-      "Validate a .vbundle archive and return a report of what would change on import without modifying data.",
+      "Validate a .vbundle archive and return a report of what would change on import without modifying data. Accepts raw bytes, multipart form data, or JSON `{ path }` pointing at a file staged under the workspace `.restore-staging` directory.",
     tags: ["migrations"],
+    requestBody: z.object({
+      path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Workspace-relative or absolute path to a staged .vbundle under .restore-staging (JSON body path only).",
+        ),
+    }),
     responseBody: z.object({
       can_import: z.boolean(),
       summary: z.object({}).passthrough(),
@@ -2163,15 +2363,23 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Import a .vbundle archive",
     description:
-      "Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes (application/octet-stream), multipart/form-data, or a JSON body with `{ url }` carrying a signed URL the daemon fetches.",
+      "Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes (application/octet-stream), multipart/form-data, a JSON body with `{ url }` carrying a signed URL the daemon fetches, or a JSON body with `{ path }` pointing at a file staged under the workspace `.restore-staging` directory.",
     tags: ["migrations"],
     requestBody: z.object({
       url: z
         .string()
         .url()
+        .optional()
         .describe(
           "A signed GCS URL pointing to the .vbundle archive (JSON body path only).",
         ),
+      path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Workspace-relative or absolute path to a staged .vbundle under .restore-staging (JSON body path only).",
+        ),
     }),
     additionalResponses: {
       "502": {

package/src/telemetry/__tests__/live-voice-funnel.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  liveVoiceEndScreen,
+  liveVoiceSilenceReason,
+} from "../live-voice-funnel.js";
+
+describe("liveVoiceSilenceReason", () => {
+  it("blames the transport when the session never went active", () => {
+    // Nothing after `ready` can be held against a session that never got
+    // there: the user had no chance to speak.
+    expect(
+      liveVoiceSilenceReason({
+        reachedActive: false,
+        receivedAudio: false,
+        detectedSpeech: false,
+      }),
+    ).toBe("no_ready");
+  });
+
+  it("blames the transport even if stray audio arrived first", () => {
+    // Audio can land before the preflight resolves. The session still never
+    // became usable, and reporting that as a microphone problem would send
+    // someone looking in the wrong layer.
+    expect(
+      liveVoiceSilenceReason({
+        reachedActive: false,
+        receivedAudio: true,
+        detectedSpeech: true,
+      }),
+    ).toBe("no_ready");
+  });
+
+  it("reports a microphone that never opened", () => {
+    expect(
+      liveVoiceSilenceReason({
+        reachedActive: true,
+        receivedAudio: false,
+        detectedSpeech: false,
+      }),
+    ).toBe("no_audio");
+  });
+
+  it("separates a mic that opened but carried no speech", () => {
+    // The distinction that makes this taxonomy worth having: a denied
+    // permission and a muted mic both produce a silent session, and only this
+    // pair of flags tells them apart.
+    expect(
+      liveVoiceSilenceReason({
+        reachedActive: true,
+        receivedAudio: true,
+        detectedSpeech: false,
+      }),
+    ).toBe("no_speech");
+  });
+
+  it("reports speech that never became a turn", () => {
+    expect(
+      liveVoiceSilenceReason({
+        reachedActive: true,
+        receivedAudio: true,
+        detectedSpeech: true,
+      }),
+    ).toBe("no_turn");
+  });
+});
+
+describe("liveVoiceEndScreen", () => {
+  it("carries the close reason alone when nothing else applies", () => {
+    expect(liveVoiceEndScreen("client_end")).toBe("ended_client_end");
+  });
+
+  it("carries a failure code in the detail slot", () => {
+    expect(liveVoiceEndScreen("error", "invalid_field")).toBe(
+      "ended_error:invalid_field",
+    );
+  });
+
+  it("carries a silence reason when the session merely produced nothing", () => {
+    expect(liveVoiceEndScreen("client_end", null, "no_audio")).toBe(
+      "ended_client_end:silent_no_audio",
+    );
+  });
+
+  it("prefers the failure code when a session both failed and was silent", () => {
+    // A session that died on an error is explained by the error; its silence
+    // is a consequence, not a second finding.
+    expect(liveVoiceEndScreen("error", "invalid_field", "no_audio")).toBe(
+      "ended_error:invalid_field",
+    );
+  });
+
+  it("keeps every combination inside the wire field's 64-char bound", () => {
+    // `screen` is capped at 64 chars by the ingest serializer and an over-long
+    // value is dropped silently, taking the whole row with it.
+    const longest = liveVoiceEndScreen("transport_closed", null, "no_speech");
+    expect(longest.length).toBeLessThanOrEqual(64);
+  });
+
+  it("prefixes the silence value so it reads correctly in a mislabelled column", () => {
+    // It shares the detail slot with failure codes, and the admin dashboard
+    // renders that slot under a "failure code" header until it learns the
+    // difference. The prefix keeps the value honest meanwhile.
+    expect(liveVoiceEndScreen("client_end", null, "no_turn")).toContain(
+      "silent_",
+    );
+  });
+});

package/src/telemetry/live-voice-funnel.ts

@@ -58,18 +58,85 @@ export type LiveVoiceStepName =
 export type LiveVoiceSessionOutcome = "completed" | "failed";
 
 /**
- * The `screen` dimension for an ended session: how it closed, plus the
- * protocol error code when a failure is what closed it.
+ * How far a session that produced NO turn actually got.
  *
- * Both halves are the daemon's own vocabulary verbatim
- * (`LiveVoiceSessionCloseReason`, `LiveVoiceProtocolErrorCode`) rather than a
- * mapping, so a rename on either side surfaces here as a compile error instead
- * of a silently-empty dashboard facet. The longest pair this can produce is
- * well inside the wire field's 64-char bound.
+ * A quarter of live-voice sessions end without a single turn, at a median of a
+ * few seconds. That is the closest thing the telemetry has to a "voice didn't
+ * work for me" rate, and a bare connect/close row cannot separate a denied
+ * microphone from a muted one from someone deliberately backing out. Those have
+ * completely different fixes, so the reason is what makes the rate actionable.
+ *
+ * The four values are ordered by how far the session got, and each one narrows
+ * the cause to a different layer:
+ *
+ * - `no_ready`  never reached `active`: died in the credential preflight or
+ *               the transport, before the user could have said anything.
+ * - `no_audio`  reached `active` but not one audio chunk ever arrived, so the
+ *               microphone never opened. Permission denial looks like this.
+ * - `no_speech` audio arrived but the detector never classified any of it as
+ *               speech: a muted or dead mic, or a genuinely silent user.
+ * - `no_turn`   speech was detected but no turn was ever dispatched, so the
+ *               utterance was abandoned, aborted, or failed to arm.
+ */
+export type LiveVoiceSilenceReason =
+  | "no_ready"
+  | "no_audio"
+  | "no_speech"
+  | "no_turn";
+
+/**
+ * Classify a zero-turn session from what the session observed. Call only when
+ * the session really produced no turn: every branch here asserts silence, so a
+ * session that did dispatch a turn would be mislabelled by the last one.
+ */
+export function liveVoiceSilenceReason(signals: {
+  reachedActive: boolean;
+  receivedAudio: boolean;
+  detectedSpeech: boolean;
+}): LiveVoiceSilenceReason {
+  if (!signals.reachedActive) {
+    return "no_ready";
+  }
+  if (!signals.receivedAudio) {
+    return "no_audio";
+  }
+  if (!signals.detectedSpeech) {
+    return "no_speech";
+  }
+  return "no_turn";
+}
+
+/**
+ * The `screen` dimension for an ended session: how it closed, plus a detail
+ * half. That detail is the protocol error code when a failure closed it, or the
+ * silence classification when the session produced no turn at all.
+ *
+ * Every part is the daemon's own vocabulary verbatim
+ * (`LiveVoiceSessionCloseReason`, `LiveVoiceProtocolErrorCode`,
+ * {@link LiveVoiceSilenceReason}) rather than a mapping, so a rename on any of
+ * them surfaces here as a compile error instead of a silently-empty dashboard
+ * facet. The longest combination this can produce is well inside the wire
+ * field's 64-char bound.
+ *
+ * A failure code wins over a silence reason when both apply: a session that
+ * died on an error is explained by the error, and the silence is a consequence
+ * of it rather than a separate finding.
+ *
+ * The silence value carries a `silent_` prefix on purpose. It shares the detail
+ * slot with failure codes, and the admin dashboard currently renders that slot
+ * in a column labelled "failure code", so the value has to read correctly even
+ * where the column header is wrong, until that panel learns the difference.
  */
 export function liveVoiceEndScreen(
   reason: LiveVoiceSessionCloseReason,
   failureCode?: LiveVoiceProtocolErrorCode | null,
+  silenceReason?: LiveVoiceSilenceReason | null,
 ): string {
-  return failureCode ? `ended_${reason}:${failureCode}` : `ended_${reason}`;
+  if (failureCode) {
+    return `ended_${reason}:${failureCode}`;
+  }
+  if (silenceReason) {
+    return `ended_${reason}:silent_${silenceReason}`;
+  }
+  return `ended_${reason}`;
 }