@vellumai/assistant 0.10.12-staging.1 → 0.10.12-staging.2

package/docs/trusted-contact-access.md

@@ -39,7 +39,7 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 
    This ensures unknown inbound access attempts always trigger guardian notification, even when the requester's source channel has no guardian binding.
 
-4. **Guardian decides.** All decisions route through the guardian decision primitive (`applyGuardianDecision`, `approvals/guardian-decision-primitive.ts`) and commit via the gateway's `guardian_requests_decide` IPC op: the status CAS and the decision's ACL outcome execute in ONE gateway transaction, so an `approved` request can never exist without its ACL write. The introduction card supports four outcomes: **approve** (start the verification handshake), **trust** (activate directly, no code — used for workspace-vouched identities), **deny** (persist a terminal denial), and **block**.
+4. **Guardian decides.** All decisions route through the guardian decision primitive (`applyGuardianDecision`, `approvals/guardian-decision-primitive.ts`) and commit via the gateway's `guardian_requests_decide` IPC op: the status CAS and the decision's ACL outcome execute in ONE gateway transaction, so an `approved` request can never exist without its ACL write. The introduction card supports four outcomes: **approve** (start the verification handshake), **trust** (activate directly, no code — used for workspace-vouched identities), **leave unverified** (the `leave_unverified` action id — park the sender as an `unverified` contact, **silently**: the requester is not notified and only learns if they message again; a later trust-requiring inbound re-fires the flow), and **block** (revoke the sender's channel and notify them their request was declined). Note the `unverified` contact left by "leave unverified" is not a guaranteed keep-out — it is still admitted under the permissive admission floors (`any_contact`, `strangers`); **block** (→ revoked) is the hard keep-out.
 5. **On approval the gateway mints a verification session.** The decide op carries a `mint_outbound_session` outcome; inside the decide transaction the gateway (`gateway/src/verification/session-service.ts`) generates a 6-digit code, persists only its SHA-256 hash in `channel_verification_sessions` (identity-bound to the requester, `verificationPurpose: 'trusted_contact'`), and returns the raw secret to the daemon in the decide response for delivery.
 6. **The code is delivered.** The daemon delivers the code to the guardian's verified channel (ephemeral + DM on Slack shared channels so other members never see it). On Slack the code is also DM'd straight to the requester; on other channels the guardian relays it out-of-band (in person, text message, phone call). That out-of-band transfer is the trust anchor: it proves the requester has a real-world relationship with the guardian.
 7. **Requester enters the code** back to the assistant on the same channel. The **gateway** intercepts bare verification codes at ingress (`gateway/src/verification/text-verification.ts`) whenever an interceptable session exists for that channel — the daemon never sees verification code messages.
@@ -52,14 +52,14 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 requested -> pending_guardian -> verification_pending -> active | denied | expired
 ```
 
-| State                  | Description                                                                                                        | Store representation                                                                                                                                                     |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `requested`            | Unknown user messaged the assistant and was denied. The system records the access attempt.                         | No member record exists. The inbound is logged in `channel_inbound_events` (assistant DB). A notification signal is emitted via `emitNotificationSignal()`.              |
-| `pending_guardian`     | The guardian has been notified and a decision is pending.                                                          | A `guardian_requests` record (gateway DB) with `status: 'pending'`, `kind: 'access_request'`.                                                                            |
-| `verification_pending` | The guardian approved. A verification session is active with a 6-digit code waiting for the requester to enter.    | Gateway `channel_verification_sessions` record with `status: 'awaiting_response'`, identity-bound to the requester. The guardian request is `status: 'approved'`.        |
-| `active`               | The requester entered the correct code (or the guardian chose direct trust). They are now a trusted contact.       | Gateway `contact_channels` record with `status: 'active'`, `policy: 'allow'`; identity mirrored to the assistant DB. The verification session is `status: 'consumed'`.   |
-| `denied`               | The guardian explicitly denied the request.                                                                        | The guardian request has `status: 'denied'`. The sender is persisted as an unverified contact and later inbound is suppressed (terminal-deny).                           |
-| `expired`              | The guardian never responded (approval TTL elapsed) or the requester never entered the code (session TTL elapsed). | Guardian request: `status: 'expired'` (CAS-expired by the gateway via the daemon's expiry sweep). Verification session: expires naturally when `expiresAt < Date.now()`. |
+| State                  | Description                                                                                                        | Store representation                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requested`            | Unknown user messaged the assistant and was denied. The system records the access attempt.                         | No member record exists. The inbound is logged in `channel_inbound_events` (assistant DB). A notification signal is emitted via `emitNotificationSignal()`.                                                                                                                                                                                                                |
+| `pending_guardian`     | The guardian has been notified and a decision is pending.                                                          | A `guardian_requests` record (gateway DB) with `status: 'pending'`, `kind: 'access_request'`.                                                                                                                                                                                                                                                                              |
+| `verification_pending` | The guardian approved. A verification session is active with a 6-digit code waiting for the requester to enter.    | Gateway `channel_verification_sessions` record with `status: 'awaiting_response'`, identity-bound to the requester. The guardian request is `status: 'approved'`.                                                                                                                                                                                                          |
+| `active`               | The requester entered the correct code (or the guardian chose direct trust). They are now a trusted contact.       | Gateway `contact_channels` record with `status: 'active'`, `policy: 'allow'`; identity mirrored to the assistant DB. The verification session is `status: 'consumed'`.                                                                                                                                                                                                     |
+| `denied`               | The guardian resolved the request without granting access — `leave_unverified` (park) or `block` (keep-out).       | The guardian request has `status: 'denied'` for both. `leave_unverified` persists an `unverified` contact — a neutral park, so a later trust-requiring inbound **re-fires** the flow; `block` revokes the channel — a durable keep-out, so re-contact is suppressed. Suppression keys off the durable **contact status** (`revoked`/`blocked`), never this request status. |
+| `expired`              | The guardian never responded (approval TTL elapsed) or the requester never entered the code (session TTL elapsed). | Guardian request: `status: 'expired'` (CAS-expired by the gateway via the daemon's expiry sweep). Verification session: expires naturally when `expiresAt < Date.now()`.                                                                                                                                                                                                   |
 
 ## Identity Binding Rules
 
@@ -112,7 +112,16 @@ Identity binding ensures the verification code can only be consumed by the inten
 | -------------------------------------------------- | ------------------- | ------------------------------------------------------------- |
 | gateway `guardian-request-service.ts` (gateway DB) | `guardian_requests` | Updated to `status: 'denied'`, `decidedByExternalUserId` set. |
 
-No trusted-contact activation happens. The sender is persisted as an unverified contact, and the terminal-deny check suppresses re-prompting the guardian for the same sender.
+No trusted-contact activation happens. The `leave_unverified` outcome persists the sender as an `unverified` contact **and sends no requester notification** (silent park); `block` instead revokes the channel and **does** notify the requester ("Your access request was declined.").
+
+The two outcomes differ on re-contact. Suppression of re-prompting keys off the **durable contact status**, not this `denied` request status:
+
+- `leave_unverified` → `unverified` contact: a neutral park, **not** kept out. If the contact later does something that needs trust — e.g. DMs on a `trusted_contacts` channel — the deny-path flow **re-fires** (self-verify challenge + a fresh guardian card), so the guardian decides afresh. The guardian's way to stop the prompts is to `block`.
+- `block` → `revoked` contact: a durable keep-out. Re-contact is suppressed (no challenge, no guardian notification) on every floor.
+
+The resolved approval card mirrors this distinction on every surface (in-app, Slack): a `leave_unverified` park reads as a neutral **"Left unverified"**, while `block` reads as **"Denied"**. Both share the `denied` request status, so the card presentation is keyed off the decided action, not the status (see `PARK_ACTION_SET` / `isParkAction` in `runtime/channel-approval-types.ts`).
+
+Separately, the admitted-mode introduction **nudge** (for a contact who cleared the floor unclassified) is quieted once the guardian has decided the contact, so a classified contact is not re-nudged across conversations. That is distinct from the deny-path re-fire above.
 
 ### Stage: `expired`
 
@@ -191,10 +200,15 @@ sequenceDiagram
         GW->>A: Forward with allow verdict
         A->>A: Process message normally
 
-    else Guardian denies
-        G->>A: Deny (inline button / app / plain text)
-        A->>A: Resolver persists denial (terminal-deny)
-        A-->>U: (No notification — user only knows<br/>they were denied if they message again)
+    else Guardian leaves unverified
+        G->>A: Leave unverified (inline button / app / plain text)
+        A->>A: Resolver seeds unverified contact (neutral park —<br/>a trust-requiring re-contact re-fires the flow)
+        A-->>U: (No notification — user only learns<br/>if they message again)
+
+    else Guardian blocks
+        G->>A: Block
+        A->>A: Resolver revokes the channel (durable keep-out —<br/>re-contact suppressed)
+        A-->>U: "Your access request was declined."
 
     else Guardian never responds
         Note over A: runGuardianExpirySweep()<br/>runs every 60 seconds
@@ -241,7 +255,7 @@ sequenceDiagram
 
 - If the unknown user messages the assistant multiple times before the guardian responds, each message hits the ACL denial path independently.
 - `notifyGuardianOfAccessRequest()` dedupes on the existing pending guardian request for the same (assistant, channel, requester), and the notification pipeline's `dedupeKey` prevents duplicate notification events.
-- A prior terminal deny suppresses re-prompting entirely, and an approval whose verification window is still open suppresses a fresh request (the sender is told to enter their code instead).
+- A **durable keep-out** — a `revoked` or `blocked` contact — suppresses re-prompting entirely (`isKeptOutStatus(previousMemberStatus)`). A `leave_unverified` park (`unverified` contact) is **not** a keep-out and re-fires; only `block` stops the prompts. An approval whose verification window is still open also suppresses a fresh request (the sender is told to enter their code instead).
 
 ### Requester already has a member record in non-active state
 

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -109,12 +109,77 @@ export type RemoteWebPairingTokenResponse =
 // only) so both Node and browser callers share one implementation.
 
 /** Why a public base URL can't be advertised in a pairing challenge. */
-export type PublicBaseUrlRejection = "unparseable" | "loopback" | "non-https";
+export type PublicBaseUrlRejection =
+  | "unparseable"
+  | "loopback"
+  | "non-https"
+  | "service-website";
 
 export type PublicBaseUrlResult =
   | { ok: true; url: string }
   | { ok: false; reason: PublicBaseUrlRejection };
 
+/**
+ * Hosts that are a tunnel/ingress vendor's own website, not a user's assistant
+ * endpoint. These are the tunnel vendors our docs mention, and their sites are
+ * exactly where a lost user grabs a URL from — e.g. a Tailscale admin invite
+ * link (`login.tailscale.com/admin/invite/…`), which is https and non-loopback
+ * and so clears every other check. Pairing refuses them with a targeted message
+ * rather than minting a challenge the scanning device can never reach.
+ */
+export const TUNNEL_PROVIDER_WEBSITE_HOSTS = [
+  "login.tailscale.com",
+  "tailscale.com",
+  "www.tailscale.com",
+  "ngrok.com",
+  "dashboard.ngrok.com",
+  "dash.cloudflare.com",
+  "cloudflare.com",
+  "www.cloudflare.com",
+] as const;
+
+/**
+ * A URL whose exact host is a tunnel/ingress vendor's own website (see
+ * {@link TUNNEL_PROVIDER_WEBSITE_HOSTS}). Exact-host only: a user's real
+ * Tailscale endpoint (`*.ts.net`) or Cloudflare-fronted domain is never a
+ * listed host, so a legitimate address is never mistaken for a vendor site.
+ */
+export function isTunnelProviderWebsiteUrl(url: string): boolean {
+  let hostname: string;
+  try {
+    // WHATWG URL lowercases the hostname during parsing.
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return (TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(
+    hostname,
+  );
+}
+
+/**
+ * The display name of the tunnel/ingress vendor a service-website URL points
+ * at (`"Tailscale"` / `"ngrok"` / `"Cloudflare"`), or null when the host is not
+ * a known vendor site. Drives the "This is <Name>'s website" pairing guidance.
+ */
+export function tunnelProviderWebsiteName(url: string): string | null {
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  if (
+    !(TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(hostname)
+  ) {
+    return null;
+  }
+  if (hostname.includes("tailscale")) return "Tailscale";
+  if (hostname.includes("ngrok")) return "ngrok";
+  if (hostname.includes("cloudflare")) return "Cloudflare";
+  return null;
+}
+
 /**
  * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
  * encodes a loopback address is unreachable from the scanning device.
@@ -167,6 +232,9 @@ export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
   if (isLoopbackPublicUrl(normalized)) {
     return { ok: false, reason: "loopback" };
   }
+  if (isTunnelProviderWebsiteUrl(normalized)) {
+    return { ok: false, reason: "service-website" };
+  }
   if (new URL(normalized).protocol !== "https:") {
     return { ok: false, reason: "non-https" };
   }

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -109,12 +109,77 @@ export type RemoteWebPairingTokenResponse =
 // only) so both Node and browser callers share one implementation.
 
 /** Why a public base URL can't be advertised in a pairing challenge. */
-export type PublicBaseUrlRejection = "unparseable" | "loopback" | "non-https";
+export type PublicBaseUrlRejection =
+  | "unparseable"
+  | "loopback"
+  | "non-https"
+  | "service-website";
 
 export type PublicBaseUrlResult =
   | { ok: true; url: string }
   | { ok: false; reason: PublicBaseUrlRejection };
 
+/**
+ * Hosts that are a tunnel/ingress vendor's own website, not a user's assistant
+ * endpoint. These are the tunnel vendors our docs mention, and their sites are
+ * exactly where a lost user grabs a URL from — e.g. a Tailscale admin invite
+ * link (`login.tailscale.com/admin/invite/…`), which is https and non-loopback
+ * and so clears every other check. Pairing refuses them with a targeted message
+ * rather than minting a challenge the scanning device can never reach.
+ */
+export const TUNNEL_PROVIDER_WEBSITE_HOSTS = [
+  "login.tailscale.com",
+  "tailscale.com",
+  "www.tailscale.com",
+  "ngrok.com",
+  "dashboard.ngrok.com",
+  "dash.cloudflare.com",
+  "cloudflare.com",
+  "www.cloudflare.com",
+] as const;
+
+/**
+ * A URL whose exact host is a tunnel/ingress vendor's own website (see
+ * {@link TUNNEL_PROVIDER_WEBSITE_HOSTS}). Exact-host only: a user's real
+ * Tailscale endpoint (`*.ts.net`) or Cloudflare-fronted domain is never a
+ * listed host, so a legitimate address is never mistaken for a vendor site.
+ */
+export function isTunnelProviderWebsiteUrl(url: string): boolean {
+  let hostname: string;
+  try {
+    // WHATWG URL lowercases the hostname during parsing.
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return (TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(
+    hostname,
+  );
+}
+
+/**
+ * The display name of the tunnel/ingress vendor a service-website URL points
+ * at (`"Tailscale"` / `"ngrok"` / `"Cloudflare"`), or null when the host is not
+ * a known vendor site. Drives the "This is <Name>'s website" pairing guidance.
+ */
+export function tunnelProviderWebsiteName(url: string): string | null {
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  if (
+    !(TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(hostname)
+  ) {
+    return null;
+  }
+  if (hostname.includes("tailscale")) return "Tailscale";
+  if (hostname.includes("ngrok")) return "ngrok";
+  if (hostname.includes("cloudflare")) return "Cloudflare";
+  return null;
+}
+
 /**
  * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
  * encodes a loopback address is unreachable from the scanning device.
@@ -167,6 +232,9 @@ export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
   if (isLoopbackPublicUrl(normalized)) {
     return { ok: false, reason: "loopback" };
   }
+  if (isTunnelProviderWebsiteUrl(normalized)) {
+    return { ok: false, reason: "service-website" };
+  }
   if (new URL(normalized).protocol !== "https:") {
     return { ok: false, reason: "non-https" };
   }

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -109,12 +109,77 @@ export type RemoteWebPairingTokenResponse =
 // only) so both Node and browser callers share one implementation.
 
 /** Why a public base URL can't be advertised in a pairing challenge. */
-export type PublicBaseUrlRejection = "unparseable" | "loopback" | "non-https";
+export type PublicBaseUrlRejection =
+  | "unparseable"
+  | "loopback"
+  | "non-https"
+  | "service-website";
 
 export type PublicBaseUrlResult =
   | { ok: true; url: string }
   | { ok: false; reason: PublicBaseUrlRejection };
 
+/**
+ * Hosts that are a tunnel/ingress vendor's own website, not a user's assistant
+ * endpoint. These are the tunnel vendors our docs mention, and their sites are
+ * exactly where a lost user grabs a URL from — e.g. a Tailscale admin invite
+ * link (`login.tailscale.com/admin/invite/…`), which is https and non-loopback
+ * and so clears every other check. Pairing refuses them with a targeted message
+ * rather than minting a challenge the scanning device can never reach.
+ */
+export const TUNNEL_PROVIDER_WEBSITE_HOSTS = [
+  "login.tailscale.com",
+  "tailscale.com",
+  "www.tailscale.com",
+  "ngrok.com",
+  "dashboard.ngrok.com",
+  "dash.cloudflare.com",
+  "cloudflare.com",
+  "www.cloudflare.com",
+] as const;
+
+/**
+ * A URL whose exact host is a tunnel/ingress vendor's own website (see
+ * {@link TUNNEL_PROVIDER_WEBSITE_HOSTS}). Exact-host only: a user's real
+ * Tailscale endpoint (`*.ts.net`) or Cloudflare-fronted domain is never a
+ * listed host, so a legitimate address is never mistaken for a vendor site.
+ */
+export function isTunnelProviderWebsiteUrl(url: string): boolean {
+  let hostname: string;
+  try {
+    // WHATWG URL lowercases the hostname during parsing.
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return (TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(
+    hostname,
+  );
+}
+
+/**
+ * The display name of the tunnel/ingress vendor a service-website URL points
+ * at (`"Tailscale"` / `"ngrok"` / `"Cloudflare"`), or null when the host is not
+ * a known vendor site. Drives the "This is <Name>'s website" pairing guidance.
+ */
+export function tunnelProviderWebsiteName(url: string): string | null {
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  if (
+    !(TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(hostname)
+  ) {
+    return null;
+  }
+  if (hostname.includes("tailscale")) return "Tailscale";
+  if (hostname.includes("ngrok")) return "ngrok";
+  if (hostname.includes("cloudflare")) return "Cloudflare";
+  return null;
+}
+
 /**
  * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
  * encodes a loopback address is unreachable from the scanning device.
@@ -167,6 +232,9 @@ export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
   if (isLoopbackPublicUrl(normalized)) {
     return { ok: false, reason: "loopback" };
   }
+  if (isTunnelProviderWebsiteUrl(normalized)) {
+    return { ok: false, reason: "service-website" };
+  }
   if (new URL(normalized).protocol !== "https:") {
     return { ok: false, reason: "non-https" };
   }

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.10.11
+  version: 0.10.12
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -17480,8 +17480,8 @@ paths:
       summary: Create a memory by remembering a fact
       description:
         Append a user-authored fact to the memory buffer via handleRemember. The fact surfaces in the memory graph
-        immediately as a pending node, and a consolidation run is nudged (deduped, backoff-respecting) so it files into
-        concept pages promptly.
+        immediately as a pending node (its id is returned so clients can navigate to it), and a consolidation run is
+        nudged (deduped, backoff-respecting) so it files into concept pages promptly.
       tags:
         - memory
       requestBody:
@@ -17507,6 +17507,11 @@ paths:
                     type: string
                   success:
                     type: boolean
+                  pendingNodeId:
+                    description:
+                      Graph node id (`buffer:<hash>`) of the pending entry this create appended, for fly-to-node navigation.
+                      Absent when the buffer can't be re-read.
+                    type: string
                 required:
                   - message
                   - success
@@ -29396,6 +29401,12 @@ paths:
                     description:
                       Guardian-facing reply from the resolver (e.g. verification code for access-request approvals). Present only
                       when applied is true and the resolver produced a reply.
+                  decidedAction:
+                    type: string
+                    description:
+                      The action to present on the resolved card — the resolved outcome, not necessarily the raw button (an
+                      access-request 'reject' resolves to the 'leave_unverified' park). Present only when applied is
+                      true; lets a client completing the card optimistically render the correct tone.
                 required:
                   - ok
                 additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.12-staging.1",
+  "version": "0.10.12-staging.2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/call-setup-flow-name-capture.test.ts

@@ -19,6 +19,7 @@ import type {
   GuardianWaitStartParams,
 } from "../calls/guardian-wait-controller.js";
 import type { CallSession } from "../calls/types.js";
+import type { ChannelStatus } from "../contacts/types.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
 import type { TrustClass } from "../runtime/trust-class.js";
 
@@ -77,6 +78,51 @@ function makeResolved(trustClass: TrustClass = "unknown"): SetupResolved {
   };
 }
 
+/**
+ * A resolved context whose caller is a known member with the given channel
+ * status — used to exercise the `previousMemberStatus` threading into the
+ * guardian-notify call (a `revoked` caller reaches name capture when the phone
+ * admission floor is inactive; see `routeSetup`).
+ */
+function makeResolvedWithMemberStatus(status: ChannelStatus): SetupResolved {
+  const base = makeResolved(
+    status === "revoked" || status === "blocked"
+      ? "unknown"
+      : "unverified_contact",
+  );
+  return {
+    ...base,
+    actorTrust: {
+      ...base.actorTrust,
+      memberRecord: {
+        contact: {
+          id: "contact-caller",
+          displayName: "Sam Example",
+          notes: null,
+          createdAt: 0,
+          updatedAt: 0,
+          contactType: "human",
+          userFile: null,
+          channels: [],
+        },
+        channel: {
+          id: "channel-caller",
+          contactId: "contact-caller",
+          type: "phone",
+          address: PHONE_NUMBER,
+          isPrimary: true,
+          externalChatId: null,
+          updatedAt: null,
+          createdAt: 0,
+        },
+        status,
+        policy: "allow",
+        role: "contact",
+      },
+    },
+  };
+}
+
 function makeSession(overrides?: Partial<CallSession>): CallSession {
   return {
     id: CALL_SESSION_ID,
@@ -558,15 +604,31 @@ describe("CallSetupFlow name capture", () => {
     ]);
   });
 
-  test("a previously denied caller gets the denial copy, not the timeout copy", async () => {
+  test("a kept-out (revoked) caller reaching name capture is threaded + gets the denial copy", async () => {
+    // A `revoked` caller (trustClass `unknown`, status `revoked`, not `blocked`)
+    // reaches name capture when the phone admission floor is inactive — see
+    // routeSetup. startNameCapture threads the caller's channel status as
+    // `previousMemberStatus`, so the guardian-notify helper suppresses
+    // (contact_kept_out) and the caller hears the denial copy, not the timeout
+    // copy. Asserting the threaded param (not just the mocked reply) proves the
+    // wiring is live, not defensive dead code.
     const f = createFlow({
-      notifyResult: { notified: false, reason: "already_denied" },
+      notifyResult: { notified: false, reason: "contact_kept_out" },
     });
-    await f.flow.start(nameCaptureOutcome, makeResolved());
+    await f.flow.start(
+      nameCaptureOutcome,
+      makeResolvedWithMemberStatus("revoked"),
+    );
 
     f.flow.pushTranscriptFinal(CALLER_NAME);
     await sleep();
 
+    // The caller's durable status is threaded into the guardian-notify call.
+    expect(f.notifyCalls).toHaveLength(1);
+    expect(f.notifyCalls[0].previousMemberStatus).toBe("revoked");
+
+    // And the caller gets the denial copy rather than the "I'll let them know"
+    // timeout copy.
     expect(f.waits).toHaveLength(0);
     expect(
       f.events.find((e) => e.eventType === "inbound_acl_access_denied")