@vellumai/assistant 0.8.0 → 0.8.2

package/src/__tests__/workspace-migrations-runner.test.ts

@@ -137,9 +137,10 @@ describe("runWorkspaceMigrations", () => {
     expect(m1.run).toHaveBeenCalledTimes(1);
     expect(m2.run).toHaveBeenCalledTimes(1);
 
-    // Checkpoints saved: started m1, completed m1, started m2, failed m2 = 4 writes
-    expect(writeFileSyncFn).toHaveBeenCalledTimes(4);
-    expect(renameSyncFn).toHaveBeenCalledTimes(4);
+    // Checkpoints saved: started m1, completed m1, started m2, failed m2,
+    // then the post-loop flip clearing isNewWorkspace = 5 writes.
+    expect(writeFileSyncFn).toHaveBeenCalledTimes(5);
+    expect(renameSyncFn).toHaveBeenCalledTimes(5);
 
     // Verify the completed checkpoint contains m1
     // The second write is the "completed" marker for m1
@@ -246,6 +247,33 @@ describe("runWorkspaceMigrations", () => {
     expect(m1.run).not.toHaveBeenCalled();
   });
 
+  test("skips failed migrations by default", async () => {
+    mockCheckpointContents = JSON.stringify({
+      applied: {
+        "001": { appliedAt: "2025-01-01T00:00:00.000Z", status: "failed" },
+      },
+    });
+
+    const m1 = makeMigration("001");
+    await runWorkspaceMigrations(WORKSPACE_DIR, [m1]);
+
+    expect(m1.run).not.toHaveBeenCalled();
+  });
+
+  test("retries failed migrations that opt in", async () => {
+    mockCheckpointContents = JSON.stringify({
+      applied: {
+        "001": { appliedAt: "2025-01-01T00:00:00.000Z", status: "failed" },
+      },
+    });
+
+    const m1 = makeMigration("001");
+    m1.retryFailedCheckpoint = true;
+    await runWorkspaceMigrations(WORKSPACE_DIR, [m1]);
+
+    expect(m1.run).toHaveBeenCalledTimes(1);
+  });
+
   test("supports async migrations", async () => {
     const asyncMigration: WorkspaceMigration = {
       id: "001",
@@ -278,6 +306,86 @@ describe("runWorkspaceMigrations", () => {
     expect(m1.run).not.toHaveBeenCalled();
   });
 
+  test("persists isNewWorkspace=true on first creation, then flips to false after sweep", async () => {
+    // No checkpoint file → fresh workspace.
+    const m1 = makeMigration("001");
+    let observed: boolean | undefined;
+    (m1.run as ReturnType<typeof mock>).mockImplementation(
+      (_dir: string, ctx?: { isNewWorkspace: boolean }) => {
+        observed = ctx?.isNewWorkspace;
+      },
+    );
+
+    await runWorkspaceMigrations(WORKSPACE_DIR, [m1]);
+
+    // The migration saw the new-workspace flag.
+    expect(observed).toBe(true);
+
+    // The first persisted checkpoint (m1's "started" save) carries the flag.
+    const firstSave = JSON.parse(
+      (writeFileSyncFn.mock.calls[0] as unknown[])[1] as string,
+    );
+    expect(firstSave.isNewWorkspace).toBe(true);
+
+    // The final persisted checkpoint clears the flag so subsequent boots
+    // treat this workspace as an upgrade.
+    const finalSave = JSON.parse(
+      (writeFileSyncFn.mock.calls.at(-1) as unknown[])[1] as string,
+    );
+    expect(finalSave.isNewWorkspace).toBe(false);
+  });
+
+  test("preserves isNewWorkspace=true across a crash before seeding migrations run", async () => {
+    // Simulate a crash mid-first-boot: an earlier migration recorded its
+    // "started" marker (writing the checkpoint file) and the daemon then
+    // died before reaching the seeding migration. The persisted flag must
+    // survive the reboot so the seeding migration still observes the
+    // brand-new workspace.
+    mockCheckpointContents = JSON.stringify({
+      isNewWorkspace: true,
+      applied: {
+        "001": { appliedAt: "2025-01-01T00:00:00.000Z", status: "started" },
+      },
+    });
+
+    const seedingMigration = makeMigration("seed");
+    let observed: boolean | undefined;
+    (seedingMigration.run as ReturnType<typeof mock>).mockImplementation(
+      (_dir: string, ctx?: { isNewWorkspace: boolean }) => {
+        observed = ctx?.isNewWorkspace;
+      },
+    );
+
+    const m1 = makeMigration("001");
+    await runWorkspaceMigrations(WORKSPACE_DIR, [m1, seedingMigration]);
+
+    expect(m1.run).toHaveBeenCalledTimes(1);
+    expect(seedingMigration.run).toHaveBeenCalledTimes(1);
+    expect(observed).toBe(true);
+  });
+
+  test("treats pre-existing checkpoint without isNewWorkspace field as upgrade", async () => {
+    // Workspaces created before this field was introduced have a checkpoint
+    // file with only `applied`. They must not be re-seeded.
+    mockCheckpointContents = JSON.stringify({
+      applied: {
+        "001": { appliedAt: "2025-01-01T00:00:00.000Z", status: "completed" },
+      },
+    });
+
+    const seedingMigration = makeMigration("seed");
+    let observed: boolean | undefined;
+    (seedingMigration.run as ReturnType<typeof mock>).mockImplementation(
+      (_dir: string, ctx?: { isNewWorkspace: boolean }) => {
+        observed = ctx?.isNewWorkspace;
+      },
+    );
+
+    await runWorkspaceMigrations(WORKSPACE_DIR, [seedingMigration]);
+
+    expect(observed).toBe(false);
+  });
+
   test("warns on malformed checkpoint file", async () => {
     mockCheckpointContents = "not valid json";
 

package/src/__tests__/workspace-release-notes-feature-flag-guard.test.ts

@@ -0,0 +1,115 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+type Registry = {
+  flags: Array<{
+    key: string;
+    scope: string;
+    defaultEnabled: boolean;
+  }>;
+};
+
+const LEGACY_FLAGGED_RELEASE_NOTE_ALLOWLIST = new Map<string, string>([
+  [
+    "045-release-notes-meet-avatar.ts",
+    "Historical bulletin that already shipped before this guard existed.",
+  ],
+]);
+
+const FLAGGED_FEATURE_LANGUAGE_PATTERNS: Array<{
+  label: string;
+  pattern: RegExp;
+}> = [
+  { label: "feature flag", pattern: /\bfeature[- ]flag(?:ged)?\b/i },
+  { label: "rollout flag", pattern: /\brollout flag\b/i },
+  { label: "behind ... flag", pattern: /\bbehind\b[^\n.]{0,120}\bflag\b/i },
+  { label: "gated on", pattern: /\bgated on\b/i },
+  { label: "when enabled", pattern: /\bwhen enabled\b/i },
+];
+
+function getRepoRoot(): string {
+  return join(process.cwd(), "..");
+}
+
+function getReleaseNoteMigrationFiles(): string[] {
+  const migrationsDir = join(process.cwd(), "src", "workspace", "migrations");
+  return readdirSync(migrationsDir)
+    .filter((fileName) => /^\d+-release-notes-[a-z0-9-]+\.ts$/.test(fileName))
+    .sort();
+}
+
+function loadDefaultDisabledAssistantFlagKeys(): string[] {
+  const registryPath = join(
+    getRepoRoot(),
+    "meta",
+    "feature-flags",
+    "feature-flag-registry.json",
+  );
+  const registry = JSON.parse(readFileSync(registryPath, "utf-8")) as Registry;
+  return registry.flags
+    .filter((flag) => flag.scope === "assistant" && !flag.defaultEnabled)
+    .map((flag) => flag.key)
+    .sort();
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function featureFlagKeyPattern(key: string): RegExp {
+  const escaped = escapeRegExp(key);
+  if (key.includes("-")) {
+    return new RegExp(`(?:^|[^a-z0-9-])${escaped}(?:$|[^a-z0-9-])`, "i");
+  }
+
+  return new RegExp("[`'\"]" + escaped + "[`'\"]", "i");
+}
+
+describe("workspace release-note migrations feature flag guard", () => {
+  test("new release-note migrations do not announce default-disabled feature-flagged work", () => {
+    const migrationsDir = join(process.cwd(), "src", "workspace", "migrations");
+    const defaultDisabledFlagKeys = loadDefaultDisabledAssistantFlagKeys();
+    const violations: string[] = [];
+
+    for (const fileName of getReleaseNoteMigrationFiles()) {
+      if (LEGACY_FLAGGED_RELEASE_NOTE_ALLOWLIST.has(fileName)) {
+        continue;
+      }
+
+      const content = readFileSync(join(migrationsDir, fileName), "utf-8");
+
+      for (const { label, pattern } of FLAGGED_FEATURE_LANGUAGE_PATTERNS) {
+        if (pattern.test(content)) {
+          violations.push(
+            `${fileName}: contains flagged-feature language "${label}"`,
+          );
+        }
+      }
+
+      for (const key of defaultDisabledFlagKeys) {
+        if (featureFlagKeyPattern(key).test(content)) {
+          violations.push(
+            `${fileName}: references default-disabled assistant feature flag "${key}"`,
+          );
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "Release-note migrations write to UPDATES.md, which is processed without checking feature flags.",
+        "Do not announce features that are still behind default-disabled assistant flags or rollout flags.",
+        "Wait until GA and add a new append-only release-note migration with a new marker.",
+        "",
+        "Violations:",
+        ...violations.map((violation) => `  - ${violation}`),
+        "",
+        "If this is an already-shipped historical bulletin, add a narrow entry to",
+        "LEGACY_FLAGGED_RELEASE_NOTE_ALLOWLIST in workspace-release-notes-feature-flag-guard.test.ts.",
+      ].join("\n");
+
+      expect(violations, message).toEqual([]);
+    }
+  });
+});

package/src/acp/__tests__/helpers/which-stub.ts

@@ -11,7 +11,8 @@
  * in `afterAll` so the swap doesn't leak into other files.
  */
 
-type WhichStub = (command: string) => string | null;
+type WhichOptions = { PATH?: string; cwd?: string };
+type WhichStub = (command: string, options?: WhichOptions) => string | null;
 
 /**
  * Installs a process-global stub for Bun.which. Returns helpers to drive and
@@ -30,7 +31,8 @@ export function installWhichStub(): {
   const originalWhich = Bun.which;
   let whichStub: WhichStub = () => null;
 
-  (Bun as unknown as { which: WhichStub }).which = (cmd) => whichStub(cmd);
+  (Bun as unknown as { which: WhichStub }).which = (cmd, options) =>
+    whichStub(cmd, options);
 
   function setWhich(arg: Record<string, string | null> | WhichStub): void {
     whichStub = typeof arg === "function" ? arg : (cmd) => arg[cmd] ?? null;

package/src/acp/resolve-agent.test.ts

@@ -161,6 +161,31 @@ describe("resolveAcpAgent", () => {
     expect(result.hint).toBe("npm i -g @zed-industries/codex-acp");
   });
 
+  test("binary preflight honors agent.env.PATH override (matches spawn env)", () => {
+    // The actual spawn merges `agentConfig.env` into the child env, so a
+    // per-agent PATH override wins over the daemon's PATH. The preflight
+    // must use the same PATH or it will reject configs that would have
+    // spawned successfully.
+    config.setConfig({
+      agents: {
+        custom: {
+          command: "my-binary",
+          args: [],
+          env: { PATH: "/opt/custom/bin" },
+        },
+      },
+    });
+    which.setWhich((cmd, options) =>
+      cmd === "my-binary" && options?.PATH === "/opt/custom/bin"
+        ? "/opt/custom/bin/my-binary"
+        : null,
+    );
+
+    const result = resolveAcpAgent("custom");
+
+    expect(result.ok).toBe(true);
+  });
+
   test("ok result when user config provides agent and binary is on PATH", () => {
     config.setConfig({
       agents: {

package/src/acp/resolve-agent.ts

@@ -65,6 +65,17 @@ function installHintFor(command: string): string {
     : `Install '${command}' and ensure it is on PATH.`;
 }
 
+/**
+ * Resolve the binary using the same PATH the spawn will see. `AcpAgentProcess`
+ * spawns with `{ ...process.env, ...config.env }`, so a per-agent `env.PATH`
+ * override wins over the daemon's PATH. Mirror that here so a config that
+ * relies on a custom PATH to locate the binary doesn't fail preflight.
+ */
+function findAgentBinary(agent: AcpAgentConfig): string | null {
+  const PATH = agent.env?.PATH ?? process.env.PATH;
+  return Bun.which(agent.command, PATH != null ? { PATH } : undefined);
+}
+
 /**
  * Resolve an id against user config first, then bundled defaults. Returns the
  * resolved entry plus a `source` label so callers can surface "user override
@@ -122,7 +133,7 @@ export function resolveAcpAgent(id: string): ResolveAcpAgentResult {
   }
 
   const { agent } = found;
-  if (!Bun.which(agent.command)) {
+  if (!findAgentBinary(agent)) {
     return {
       ok: false,
       reason: "binary_not_found",
@@ -157,7 +168,7 @@ export function listAcpAgents(): {
   const agents: AcpAgentEntry[] = mergedAgentIds(userAgents).map((id) => {
     // Non-null: ids come from `mergedAgentIds` so the lookup always resolves.
     const { agent, source } = lookupAgent(userAgents, id)!;
-    const available = Bun.which(agent.command) !== null;
+    const available = findAgentBinary(agent) !== null;
     const entry: AcpAgentEntry = {
       id,
       command: agent.command,

package/src/acp/session-manager.ts

@@ -278,12 +278,26 @@ export class AcpSessionManager {
 
   /**
    * Kills the agent process and removes the session from tracking.
+   *
+   * Persists the buffered event log first so abort paths
+   * (`executeAcpAbort`, daemon shutdown) don't drop history. If the
+   * session is still in a non-terminal state, mark it cancelled so the
+   * persisted row reflects reality. The in-flight prompt's then/catch
+   * handler will short-circuit after teardown removes the entry.
    */
   close(acpSessionId: string): void {
     const entry = this.sessions.get(acpSessionId);
     if (!entry) {
       throw new Error(`ACP session "${acpSessionId}" not found`);
     }
+    if (
+      entry.state.status === "running" ||
+      entry.state.status === "initializing"
+    ) {
+      entry.state.status = "cancelled";
+      entry.state.completedAt = Date.now();
+    }
+    this.persistTerminal(acpSessionId, entry);
     this.teardownSession(acpSessionId, entry);
   }
 

package/src/agent/image-optimize.ts

@@ -21,6 +21,11 @@ const MAX_DIMENSION = 1568;
 // Threshold below which we skip optimization — small images don't need it.
 const OPTIMIZE_THRESHOLD_BYTES = 300 * 1024; // 300 KB
 
+// Anthropic rejects any single image whose source payload exceeds 5 MB,
+// regardless of pixel dimensions. Cap at ~3.5 MB raw so the base64-encoded
+// form (raw * 4/3) stays comfortably under 5 MB even after re-encoding.
+const MAX_TRANSPORT_BYTES = Math.floor(3.5 * 1024 * 1024); // ~3.5 MB raw
+
 const JPEG_QUALITY = 80;
 
 // Content-addressed disk cache to avoid re-running sips on the same image.
@@ -130,10 +135,13 @@ function runSips(inputBytes: Buffer): Buffer | null {
 /**
  * Decide whether an image needs to be rescaled before sending.
  *
- * Anthropic rejects many-image requests when any image exceeds 2000 px on a
- * side, so dimensions — not file size — are the authoritative gate. A sparse
- * screenshot can be under 300 KB while still being 3000+ px wide, which the
- * byte-size heuristic alone would let slip through.
+ * Two independent gates apply:
+ *   1. Pixel dimensions — Anthropic rejects many-image requests when any
+ *      image exceeds 2000 px on a side. A sparse screenshot can be under
+ *      300 KB while still being 3000+ px wide.
+ *   2. Byte size — Anthropic rejects any image whose source payload
+ *      exceeds 5 MB. A 1500×1500 high-color screenshot can produce a >5 MB
+ *      payload while staying well under the dimension cap.
  *
  * Exported for unit testing.
  */
@@ -141,8 +149,8 @@ export function shouldRescaleImage(
   dims: { width: number; height: number } | null,
   byteLength: number,
 ): boolean {
+  if (byteLength > MAX_TRANSPORT_BYTES) return true;
   if (dims) {
-    // Dimensions known — they are the authoritative check.
     return dims.width > MAX_DIMENSION || dims.height > MAX_DIMENSION;
   }
   // Dimensions unparseable — fall back to file size as a rough proxy.

package/src/approvals/guardian-request-resolvers.ts

@@ -13,8 +13,8 @@
 
 import { answerCall } from "../calls/call-domain.js";
 import { findContactChannel } from "../contacts/contact-store.js";
+import { upsertContactChannel } from "../contacts/contacts-write.js";
 import { findConversation } from "../daemon/conversation-store.js";
-import { emitFeedEvent } from "../home/emit-feed-event.js";
 import {
   type CanonicalGuardianRequest,
   getCanonicalGuardianRequest,
@@ -119,6 +119,12 @@ export type ResolverResult =
       applied: true;
       grantMinted?: boolean;
       guardianReplyText?: string;
+      activatedContact?: {
+        sourceChannel: string;
+        externalUserId: string;
+        externalChatId?: string;
+        displayName?: string;
+      };
     }
   | { ok: false; reason: string };
 
@@ -206,21 +212,6 @@ const pendingInteractionResolver: GuardianRequestResolver = {
       ctx.emissionContext,
     );
 
-    const approved = decision.action !== "reject";
-    void emitFeedEvent({
-      source: "assistant",
-      title: approved ? "Tool Request Approved" : "Tool Request Denied",
-      summary: `${approved ? "Approved" : "Denied"} access to ${request.toolName ?? "unknown tool"}.`,
-      dedupKey: `guardian-approval:${request.id}`,
-      urgency: approved ? undefined : "medium",
-      detailPanel: { kind: "toolPermission" },
-    }).catch((err) => {
-      log.warn(
-        { err, requestId: request.id },
-        "Failed to emit guardian approval feed event",
-      );
-    });
-
     log.info(
       {
         event: "resolver_tool_approval_applied",
@@ -467,20 +458,6 @@ const accessRequestResolver: GuardianRequestResolver = {
         }
       }
 
-      void emitFeedEvent({
-        source: "assistant",
-        title: "Access Request Denied",
-        summary: `Denied access request.`,
-        dedupKey: `guardian-access:${request.id}`,
-        urgency: "medium",
-        detailPanel: { kind: "permissionChat" },
-      }).catch((err) => {
-        log.warn(
-          { err, requestId: request.id },
-          "Failed to emit access request feed event",
-        );
-      });
-
       return {
         ok: true,
         applied: true,
@@ -496,6 +473,21 @@ const accessRequestResolver: GuardianRequestResolver = {
     // a verification session. The caller is already on the line and the
     // relay server's in-call wait loop will detect the approved status.
     if (channel === "phone") {
+      try {
+        upsertContactChannel({
+          sourceChannel: "phone",
+          externalUserId: requesterExternalUserId,
+          externalChatId: requesterChatId,
+          status: "active",
+          policy: "allow",
+        });
+      } catch (err) {
+        log.error(
+          { err, requesterExternalUserId },
+          "Access request resolver: failed to activate voice caller as trusted contact",
+        );
+      }
+
       log.info(
         {
           event: "resolver_access_request_voice_approved",
@@ -506,21 +498,16 @@ const accessRequestResolver: GuardianRequestResolver = {
         "Access request resolver: voice approval — direct trusted-contact activation (no verification session)",
       );
 
-      void emitFeedEvent({
-        source: "assistant",
-        title: "Access Request Approved",
-        summary: `Granted access request.`,
-        dedupKey: `guardian-access:${request.id}`,
-        urgency: undefined,
-        detailPanel: { kind: "permissionChat" },
-      }).catch((err) => {
-        log.warn(
-          { err, requestId: request.id },
-          "Failed to emit access request feed event",
-        );
-      });
-
-      return { ok: true, applied: true };
+      return {
+        ok: true,
+        applied: true,
+        activatedContact: {
+          sourceChannel: "phone",
+          externalUserId: requesterExternalUserId,
+          ...(requesterChatId ? { externalChatId: requesterChatId } : {}),
+          ...(requesterDisplayName ? { displayName: requesterDisplayName } : {}),
+        },
+      };
     }
 
     // Non-voice approvals: mint an identity-bound verification session so the
@@ -738,20 +725,6 @@ const accessRequestResolver: GuardianRequestResolver = {
       ? `Access approved for ${requesterLabel}. Give them this verification code: \`${session.secret}\`. The code expires in 10 minutes.`
       : `Access approved for ${requesterLabel}. Give them this verification code: \`${session.secret}\`. The code expires in 10 minutes. I could not notify them automatically, so please tell them to send the code manually.`;
 
-    void emitFeedEvent({
-      source: "assistant",
-      title: "Access Request Approved",
-      summary: `Granted access request.`,
-      dedupKey: `guardian-access:${request.id}`,
-      urgency: undefined,
-      detailPanel: { kind: "permissionChat" },
-    }).catch((err) => {
-      log.warn(
-        { err, requestId: request.id },
-        "Failed to emit access request feed event",
-      );
-    });
-
     return {
       ok: true,
       applied: true,
@@ -825,20 +798,6 @@ const toolGrantRequestResolver: GuardianRequestResolver = {
         }
       }
 
-      void emitFeedEvent({
-        source: "assistant",
-        title: "Tool Grant Denied",
-        summary: `Denied grant request for ${request.toolName ?? "unknown tool"}.`,
-        dedupKey: `guardian-grant:${request.id}`,
-        urgency: "medium",
-        detailPanel: { kind: "toolPermission" },
-      }).catch((err) => {
-        log.warn(
-          { err, requestId: request.id },
-          "Failed to emit tool grant denial feed event",
-        );
-      });
-
       return { ok: true, applied: true };
     }
 
@@ -936,20 +895,6 @@ const toolGrantRequestResolver: GuardianRequestResolver = {
       }
     }
 
-    void emitFeedEvent({
-      source: "assistant",
-      title: "Tool Grant Approved",
-      summary: `Approved grant request for ${request.toolName ?? "unknown tool"}.`,
-      dedupKey: `guardian-grant:${request.id}`,
-      urgency: undefined,
-      detailPanel: { kind: "toolPermission" },
-    }).catch((err) => {
-      log.warn(
-        { err, requestId: request.id },
-        "Failed to emit tool grant approval feed event",
-      );
-    });
-
     return { ok: true, applied: true, grantMinted: false };
   },
 };

package/src/calls/relay-server.ts

@@ -612,6 +612,12 @@ export class RelayConnection {
         );
         this.startNameCapture(outcome.assistantId, outcome.fromNumber);
         return;
+      case "unverified_caller":
+        await this.handleUnverifiedCaller(
+          outcome.displayName,
+          outcome.isGuardian,
+        );
+        return;
       case "verification":
         if (this.controller && resolved.actorTrust.trustClass !== "unknown") {
           this.controller.setTrustContext(
@@ -669,6 +675,35 @@ export class RelayConnection {
     });
   }
 
+  /** Speak verification guidance to a known-but-unverified caller, then disconnect. */
+  private async handleUnverifiedCaller(
+    displayName: string,
+    isGuardian: boolean,
+  ): Promise<void> {
+    recordCallEvent(this.callSessionId, "inbound_acl_unverified_caller", {
+      callSessionId: this.callSessionId,
+      isGuardian,
+    });
+    this.connectionState = "disconnecting";
+    updateCallSession(this.callSessionId, {
+      status: "failed",
+      endedAt: Date.now(),
+      lastError: "Inbound voice ACL: caller channel unverified",
+    });
+    const action = isGuardian
+      ? `To verify, open your assistant's contacts page, click Verify next to the phone channel, ` +
+        `and follow the prompts. Then call back once the verification session is active.`
+      : `Please reach out to the account guardian to start a new verification session, ` +
+        `then call back once the verification session is active.`;
+    const message =
+      `This number is registered as ${displayName}'s phone but has not been verified yet. ` +
+      action;
+    await speakSystemPrompt(this, message);
+    setTimeout(() => {
+      this.endSession("Inbound voice ACL: caller channel unverified");
+    }, getTtsPlaybackDelayMs());
+  }
+
   /** Deny an inbound call with a TTS message and schedule disconnect. */
   private async denyInboundCall(
     from: string,

package/src/calls/relay-setup-router.ts

@@ -56,6 +56,13 @@ type SetupOutcome =
       guardianName: string | null;
     }
   | { action: "name_capture"; assistantId: string; fromNumber: string }
+  | {
+      action: "unverified_caller";
+      assistantId: string;
+      fromNumber: string;
+      displayName: string;
+      isGuardian: boolean;
+    }
   | { action: "deny"; message: string; logReason: string };
 
 // ── Resolved context produced alongside the outcome ──────────────────
@@ -234,6 +241,35 @@ export function routeSetup(ctx: SetupContext): {
       };
     }
 
+    // Known caller whose channel hasn't passed verification yet —
+    // mirrors the gateway's pre-intercept (twilio-voice-webhook.ts) so
+    // calls slipping past it (e.g. canonicalization mismatch between
+    // gateway and assistant DBs) still get useful guidance instead of
+    // the "I don't recognize this number" name-capture script.
+    const unverifiedStatuses = new Set(["unverified", "pending"]);
+    const memberChannel = actorTrust.memberRecord?.channel;
+    if (memberChannel && unverifiedStatuses.has(memberChannel.status)) {
+      log.info(
+        {
+          callSessionId: ctx.callSessionId,
+          from: ctx.from,
+          channelId: memberChannel.id,
+          channelStatus: memberChannel.status,
+        },
+        "Inbound voice ACL: known but unverified caller — returning verification guidance",
+      );
+      return {
+        outcome: {
+          action: "unverified_caller",
+          assistantId,
+          fromNumber: ctx.from,
+          displayName: actorTrust.memberRecord!.contact.displayName,
+          isGuardian: actorTrust.memberRecord!.contact.role === "guardian",
+        },
+        resolved,
+      };
+    }
+
     // Unknown caller — name capture flow
     log.info(
       {