@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/calls/voice-session-bridge.ts

@@ -70,8 +70,8 @@ import {
   CALL_VERIFICATION_COMPLETE_MARKER,
   ESCALATE_VERDICT_TOKEN,
   HOLD_VERDICT_TOKEN,
-  MINIMIZE_ROOM_MARKER,
   stripInternalSpeechMarkers,
+  terminalControlMarkerLength,
 } from "./voice-control-protocol.js";
 import {
   createFrontDoorStreamGate,
@@ -188,6 +188,34 @@ function frontDoorRuleWithDigest(
   });
 }
 
+/**
+ * The triage-and-escalate rule a turn's leg adds to its control prompt: the
+ * front-door leg decides and may hand off, the escalated leg continues the
+ * answer after a holding phrase was already spoken. Null when routing is off.
+ * One rule for both prompt shapes, the auto-built phone prompt and a
+ * caller-supplied one, so the front-door model is anchored to the same
+ * caller words on every transport.
+ */
+function routingLegRuleFor(
+  opts: Pick<
+    VoiceTurnOptions,
+    "routingLeg" | "unifiedVerdict" | "spokenEscalationBridge"
+  >,
+  callerUtterance: string,
+): string | null {
+  switch (opts.routingLeg) {
+    case "front-door":
+      return frontDoorRuleWithDigest(
+        opts.unifiedVerdict === true,
+        callerUtterance,
+      );
+    case "escalated":
+      return escalatedContinuationRule(opts.spokenEscalationBridge);
+    default:
+      return null;
+  }
+}
+
 /**
  * Exact message thrown when `opts.signal` aborts while the turn is waiting
  * for the conversation to become available. The call controller's abort
@@ -373,8 +401,9 @@ export interface VoiceTurnOptions {
    *
    * Deliberately separate from {@link userMessageInterface}: that field feeds
    * `resolveChannelCapabilities` and decides what the turn may do, so it is not
-   * free to carry attribution. Absent for phone calls and for clients that send
-   * no identity on the start frame.
+   * free to carry attribution. A phone call passes its call session id and a
+   * `phone_*` entry naming the call's direction, with no client. Absent for
+   * clients that send no identity on the start frame.
    */
   voiceTelemetry?: {
     sessionId: string;
@@ -447,7 +476,7 @@ export interface VoiceTurnOptions {
   onComplete?: () => void;
   /** Called when the agent loop encounters an error. */
   onError?: (message: string) => void;
-  /** Event-name callbacks used by non-phone voice clients. */
+  /** Event-name callbacks: tool activity, persisted row ids, raw stream. */
   callbacks?: VoiceTurnCallbacks;
   /**
    * Called when this turn leaves a confirmation for the user to answer instead
@@ -482,10 +511,9 @@ export interface VoiceTurnOptions {
    */
   overrideProfile?: string;
   /**
-   * Which leg of a triaged turn this is, so the auto-built phone control prompt
-   * can add the front-door triage rule or the escalated continuation rule.
-   * Undefined = routing off; no routing rules are added. Ignored when a caller
-   * supplies its own `voiceControlPrompt`.
+   * Which leg of a triaged turn this is, so the control prompt (auto-built or
+   * caller-supplied) carries the front-door triage rule or the escalated
+   * continuation rule. Undefined = routing off; no routing rules are added.
    */
   routingLeg?: VoiceRoutingLeg;
   /**
@@ -611,9 +639,8 @@ function buildVoiceCallControlPrompt(opts: {
   task?: string | null;
   isCallerGuardian?: boolean;
   skipDisclosure?: boolean;
-  routingLeg?: VoiceRoutingLeg;
-  spokenEscalationBridge?: string;
-  unifiedVerdict?: boolean;
+  /** The turn's routing-leg rule (see {@link routingLegRuleFor}), if any. */
+  routingLegRule?: string | null;
 }): string {
   const config = getConfig();
   const disclosureEnabled =
@@ -665,22 +692,18 @@ function buildVoiceCallControlPrompt(opts: {
     );
   }
 
-  lines.push(
-    '6. When caller text includes [SPEAKER id="..." label="..."], treat each speaker as a distinct person and personalize responses using that speaker\'s prior context in this call.',
-  );
-
   if (opts.isInbound) {
     if (opts.isCallerGuardian) {
       lines.push(
-        '7. If the latest user turn is "(call connected — deliver opening greeting)", this is your user calling you. Answer casually and briefly, like picking up a call from someone you know well. For example: "Hey!" or "What\'s up?" Do NOT introduce yourself, do NOT say you are calling on behalf of anyone, and do NOT ask how you can help in a formal way. Keep it short and natural.',
+        '6. If the latest user turn is "(call connected — deliver opening greeting)", this is your user calling you. Answer casually and briefly, like picking up a call from someone you know well. For example: "Hey!" or "What\'s up?" Do NOT introduce yourself, do NOT say you are calling on behalf of anyone, and do NOT ask how you can help in a formal way. Keep it short and natural.',
       );
     } else {
       lines.push(
-        '7. If the latest user turn is "(call connected — deliver opening greeting)", this is an inbound call you are answering (not a call you initiated). Greet the caller warmly and ask how you can help. Introduce yourself once at the start using your assistant name if you know it (for example: "Hey there, this is Ava, Sam\'s assistant. How can I help?"). If your assistant name is not known, skip the name and just identify yourself as the guardian\'s assistant. Never use a UUID-shaped internal assistant ID as your spoken name. Do NOT say "I\'m calling" or "I\'m calling on behalf of". Vary the wording; do not use a fixed template.',
+        '6. If the latest user turn is "(call connected — deliver opening greeting)", this is an inbound call you are answering (not a call you initiated). Greet the caller warmly and ask how you can help. Introduce yourself once at the start using your assistant name if you know it (for example: "Hey there, this is Ava, Sam\'s assistant. How can I help?"). If your assistant name is not known, skip the name and just identify yourself as the guardian\'s assistant. Never use a UUID-shaped internal assistant ID as your spoken name. Do NOT say "I\'m calling" or "I\'m calling on behalf of". Vary the wording; do not use a fixed template.',
       );
     }
     lines.push(
-      "8. If the latest user turn includes [CALL_OPENING_ACK], treat it as the caller acknowledging your greeting and continue the conversation naturally.",
+      "7. If the latest user turn includes [CALL_OPENING_ACK], treat it as the caller acknowledging your greeting and continue the conversation naturally.",
     );
   } else {
     const disclosureReminder =
@@ -688,27 +711,22 @@ function buildVoiceCallControlPrompt(opts: {
         ? " However, the disclosure text from rule 0 is separate from self-introduction and must always be included in your opening greeting, even if the Task does not mention introducing yourself."
         : "";
     lines.push(
-      '7. If the latest user turn is "(verification completed — transitioning into conversation)", the caller just completed a phone verification code challenge on this call. Greet them naturally and ask if there is anything you can help with. Keep it casual and brief.',
-      `If the latest user turn is "(call connected — deliver opening greeting)", deliver your opening greeting based solely on the Task context above. The Task already describes how to open the call — follow it directly without adding any extra introduction on top. If the Task says to introduce yourself, do so once. If the Task does not mention introducing yourself, skip the introduction.${disclosureReminder} Vary the wording naturally; do not use a fixed template.`,
-      "8. If the latest user turn includes [CALL_OPENING_ACK], treat it as the callee acknowledging your opener and continue the conversation naturally without re-introducing yourself or repeating the initial check-in question.",
+      '6. If the latest user turn is "(verification completed — transitioning into conversation)", the caller just completed a phone verification code challenge on this call. Greet them naturally and ask if there is anything you can help with. Keep it casual and brief.',
+      `If the latest user turn is "(call connected — deliver opening greeting)", deliver your opening greeting based solely on the Task context above. The Task already describes how to open the call, so follow it directly without adding any extra introduction on top. If the Task says to introduce yourself, do so once. If the Task does not mention introducing yourself, skip the introduction.${disclosureReminder} Vary the wording naturally; do not use a fixed template.`,
+      "7. If the latest user turn includes [CALL_OPENING_ACK], treat it as the callee acknowledging your opener and continue the conversation naturally without re-introducing yourself or repeating the initial check-in question.",
     );
   }
 
   lines.push(
-    "9. After the opening greeting turn, treat the Task field as background context only — do not re-execute its instructions on subsequent turns.",
-    '10. Do not make up information. If you are unsure, use [ASK_GUARDIAN: your question] to consult your guardian. For tool permission requests, use [ASK_GUARDIAN_APPROVAL: {"question":"...","toolName":"...","input":{...}}].',
-    `11. ${SPOKEN_REPLY_PLAIN_TEXT_RULE} Protocol markers like ${opts.isCallerGuardian ? "[END_CALL]" : "[ASK_GUARDIAN: ...] and [END_CALL]"} are not spoken text and should still be used normally.`,
-    `12. Speak the caller's language: reply in the language of the caller's most recent actual speech, and follow them if they switch languages mid-call. Synthetic user turns (parenthetical markers like the call-connected and verification-completed notices) are not caller speech and never set the language. Before the caller has spoken, such as on the opening greeting turn, ${preSpeechLanguageRuleFragment(config.services.stt.language, sttCatalogKeyForRole(config.services.stt, "telephony"))}.`,
-    `13. ${PHONE_NO_SETUP_FLOWS_RULE}`,
+    "8. After the opening greeting turn, treat the Task field as background context only. Do not re-execute its instructions on subsequent turns.",
+    '9. Do not make up information. If you are unsure, use [ASK_GUARDIAN: your question] to consult your guardian. For tool permission requests, use [ASK_GUARDIAN_APPROVAL: {"question":"...","toolName":"...","input":{...}}].',
+    `10. ${SPOKEN_REPLY_PLAIN_TEXT_RULE} Protocol markers like ${opts.isCallerGuardian ? "[END_CALL]" : "[ASK_GUARDIAN: ...] and [END_CALL]"} are not spoken text and should still be used normally.`,
+    `11. Speak the caller's language: reply in the language of the caller's most recent actual speech, and follow them if they switch languages mid-call. Synthetic user turns (parenthetical markers like the call-connected and verification-completed notices) are not caller speech and never set the language. Before the caller has spoken, such as on the opening greeting turn, ${preSpeechLanguageRuleFragment(config.services.stt.language, sttCatalogKeyForRole(config.services.stt, "telephony"))}.`,
+    `12. ${PHONE_NO_SETUP_FLOWS_RULE}`,
   );
 
-  // Triage-and-escalate routing rules. The front-door leg decides and may
-  // hand off; the escalated leg continues the answer after a holding phrase
-  // was already spoken.
-  if (opts.routingLeg === "front-door") {
-    lines.push(`14. ${frontDoorRuleWithDigest(opts.unifiedVerdict === true)}`);
-  } else if (opts.routingLeg === "escalated") {
-    lines.push(`14. ${escalatedContinuationRule(opts.spokenEscalationBridge)}`);
+  if (opts.routingLegRule) {
+    lines.push(`13. ${opts.routingLegRule}`);
   }
 
   lines.push("</voice_call_control>");
@@ -749,17 +767,22 @@ function stripMarkersFromBlocks(blocks: ContentBlock[]): ContentBlock[] {
 }
 
 /**
- * Remove the terminal MINIMIZE_ROOM_MARKER from the end of a row's text,
- * walking text blocks from the last one backward so a marker split across
- * block boundaries (e.g. `"Done [-"` + `"1]"`) is removed whole — the
- * per-block strip in {@link stripMarkersFromBlocks} only sees fragments and
- * would leave both halves in place. Callers must have established that the
- * row's joined text ends with the marker after trimming trailing whitespace.
+ * Remove a terminal control marker (the minimize marker or a session control,
+ * `markerLength` characters long) from the end of a row's text, walking text
+ * blocks from the last one backward so a marker split across block boundaries
+ * (e.g. `"Done [-"` + `"1]"`) is removed whole — the per-block strip in
+ * {@link stripMarkersFromBlocks} only sees fragments and would leave both
+ * halves in place. Callers must have established, with
+ * {@link terminalControlMarkerLength}, that the row's joined text ends with
+ * the marker after trimming trailing whitespace.
  */
-function stripTerminalMinimizeMarker(blocks: ContentBlock[]): ContentBlock[] {
+function stripTerminalControlMarker(
+  blocks: ContentBlock[],
+  markerLength: number,
+): ContentBlock[] {
   const result = blocks.map((block) => ({ ...block }));
   const joined = joinedTextOfBlocks(result);
-  const cutAt = joined.trimEnd().length - MINIMIZE_ROOM_MARKER.length;
+  const cutAt = joined.trimEnd().length - markerLength;
   let blockEnd = joined.length;
   for (let i = result.length - 1; i >= 0 && blockEnd > cutAt; i--) {
     const block = result[i]!;
@@ -956,6 +979,10 @@ export async function startVoiceTurn(
   // control markers (ASK_GUARDIAN, END_CALL, etc.) and recognize opener turns.
   const isCallerGuardian = opts.trustContext?.trustClass === "guardian";
 
+  // The front-door rule anchors on the words the model sees as the user
+  // turn, which for a phone sentinel is its neutral persisted form rather
+  // than the marker itself.
+  const routingLegRule = routingLegRuleFor(opts, persistedContent);
   let voiceCallControlPrompt: string | null;
   if (opts.voiceControlPrompt === undefined) {
     voiceCallControlPrompt = buildVoiceCallControlPrompt({
@@ -963,23 +990,14 @@ export async function startVoiceTurn(
       task: opts.task,
       isCallerGuardian,
       skipDisclosure: opts.skipDisclosure,
-      routingLeg: opts.routingLeg,
-      spokenEscalationBridge: opts.spokenEscalationBridge,
-      unifiedVerdict: opts.unifiedVerdict,
+      routingLegRule,
     });
   } else {
-    // A caller-supplied prompt (e.g. live-voice) bypasses
-    // buildVoiceCallControlPrompt, which is where the triage-and-escalate rule
-    // is normally injected from `routingLeg`. Append it here too — without it
-    // the front-door leg would run on the fast profile but never learn the
-    // verdict protocol, so it could not hold or hand off to the escalated leg.
+    // A caller-supplied prompt (live voice) replaces the phone prompt, so the
+    // routing-leg rule is appended to it here. Without it the front-door leg
+    // would run on the fast profile but never learn the verdict protocol, so
+    // it could not hold or hand off to the escalated leg.
     voiceCallControlPrompt = opts.voiceControlPrompt;
-    const routingLegRule =
-      opts.routingLeg === "front-door"
-        ? frontDoorRuleWithDigest(opts.unifiedVerdict === true, opts.content)
-        : opts.routingLeg === "escalated"
-          ? escalatedContinuationRule(opts.spokenEscalationBridge)
-          : null;
     if (voiceCallControlPrompt != null && routingLegRule) {
       voiceCallControlPrompt = `${voiceCallControlPrompt}\n\n${routingLegRule}`;
     }
@@ -1797,14 +1815,14 @@ export async function startVoiceTurn(
    *   never the verdict token or the text streamed past the cap (issue
    *   #37850). A row with no spoken bridge (canned-fallback case — that
    *   bridge is audio-only) is deleted.
-   * - Any leg whose row ENDS with the `[-1]` minimize marker (swallowed
-   *   before TTS on the live path) has its text blocks rewritten through
+   * - Any leg whose row ENDS with the `[-1]` minimize marker or a session
+   *   control marker (`[END_CALL]`, `[MUTE]`, `[MUTE:<seconds>]`), all
+   *   swallowed before TTS, has its text blocks rewritten through
    *   `stripInternalSpeechMarkers` so the marker never renders in the chat
-   *   transcript. This covers front-door answers too: that leg is never
-   *   taught the marker, but it can parrot one from visible conversation
-   *   history, and the parroted marker is never spoken and never minimizes
-   *   the room. Deliberately scoped to that marker: rows without it
-   *   persist byte-identical.
+   *   transcript. This covers front-door answers too: a front-door answer
+   *   may end with a session control, and it can parrot `[-1]` from visible
+   *   conversation history. Deliberately scoped to terminal markers: rows
+   *   without one persist byte-identical.
    *
    * After a rewrite, in-memory history is reloaded from the clean DB before
    * the escalated leg — blocked on this turn's teardown — snapshots it, so
@@ -1838,6 +1856,9 @@ export async function startVoiceTurn(
         action = "delete_discarded";
       } else {
         const row = getMessageById(reservedAssistantRowId, opts.conversationId);
+        const terminalMarkerLength = row
+          ? terminalControlMarkerLength(joinedTextOfBlocks(row.content))
+          : 0;
         const cut =
           row && opts.routingLeg === "front-door"
             ? cutFrontDoorContentAtVerdict(row.content)
@@ -1856,19 +1877,18 @@ export async function startVoiceTurn(
             action = "delete_empty";
           }
         } else if (
-          // Terminal position only — mirrors the live latch in
-          // createControlMarkerHoldback: a reply whose CONTENT contains
-          // "[-1]" mid-text never minimized the room, so its transcript
-          // keeps that content untouched too. Front-door answer rows (no
-          // verdict token to cut) take this branch as well.
-          joinedTextOfBlocks(row.content)
-            .trimEnd()
-            .endsWith(MINIMIZE_ROOM_MARKER)
+          // Terminal position only — mirrors parseTerminalSessionControl: a
+          // reply whose CONTENT contains a marker mid-text never acted on it,
+          // so its transcript keeps that content untouched too. Front-door
+          // answer rows (no verdict token to cut) take this branch as well.
+          terminalMarkerLength > 0
         ) {
           // Terminal marker first (boundary-aware — it may span text blocks),
           // then the per-block strip for any interior complete markers.
           const cleaned = trimOuterTextEdges(
-            stripMarkersFromBlocks(stripTerminalMinimizeMarker(row.content)),
+            stripMarkersFromBlocks(
+              stripTerminalControlMarker(row.content, terminalMarkerLength),
+            ),
           );
           // A marker-only reply (the model said nothing beyond "[-1]") strips
           // to nothing at all; keeping the row would render a blank assistant
@@ -1882,7 +1902,7 @@ export async function startVoiceTurn(
               reservedAssistantRowId,
               JSON.stringify(cleaned),
             );
-            action = "strip_minimize_marker";
+            action = "strip_control_marker";
           }
         }
       }

package/src/calls/voice-triage-escalate.ts

@@ -27,7 +27,10 @@
  */
 
 import { NON_LATIN_SENTENCE_ENDING_PUNCTUATION } from "../tts/speakable-segments.js";
-import { localizedOrDefault } from "../util/language-subtag.js";
+import {
+  fixedPhraseLanguage,
+  localizedOrDefault,
+} from "../util/language-subtag.js";
 import {
   ESCALATE_VERDICT_TOKEN,
   HOLD_VERDICT_TOKEN,
@@ -103,6 +106,36 @@ export function fallbackEscalationBridgeFor(language?: string): string {
  */
 export const MIN_SPOKEN_BRIDGE_CHARS = 3;
 
+/**
+ * The phrase spoken across an escalation hand-off, for both voice drivers:
+ * the front-door leg's own capped bridge when it is a real bridge, else the
+ * canned fallback in the caller's language. `usesFallback` marks the canned
+ * phrase as audio-only: the model never produced it, so no transcript row
+ * carries it (the bridge's hygiene pass deletes the leg's row), and the
+ * driver keeps it out of the turn's recorded text. `language` is the TTS
+ * hint the phrase must carry: "en" when the canned table has no entry for
+ * the caller's language (the phrase is English text then), undefined when
+ * the phrase rides the turn's own language.
+ */
+export function resolveSpokenEscalationBridge(
+  cappedBridge: string,
+  language?: string,
+): { spokenBridge: string; usesFallback: boolean; language?: string } {
+  const usesFallback = cappedBridge.length < MIN_SPOKEN_BRIDGE_CHARS;
+  if (!usesFallback) {
+    return { spokenBridge: cappedBridge, usesFallback };
+  }
+  const fixedLanguage = fixedPhraseLanguage(
+    FALLBACK_ESCALATION_BRIDGE_BY_LANGUAGE,
+    language,
+  );
+  return {
+    spokenBridge: fallbackEscalationBridgeFor(language),
+    usesFallback,
+    ...(fixedLanguage !== undefined ? { language: fixedLanguage } : {}),
+  };
+}
+
 /**
  * Hard cap on the spoken escalation bridge. The bridge is supposed to be a
  * single short sentence; the cap bounds the hand-off delay (and the audio)
@@ -159,14 +192,20 @@ export function isEscalationBridgeComplete(rawBridge: string): boolean {
  * output leads with {@link ESCALATE_VERDICT_TOKEN} (a stray token later in
  * an answer is not an escalation under the verdict-first protocol), else
  * the capped bridge that followed the token. Used by transcript hygiene to
- * reconstruct what the caller heard from a persisted row.
+ * reconstruct what the caller heard from a persisted row, by running the
+ * same verdict machine the live stream ran through.
  */
 export function spokenBridgeText(frontDoorText: string): string {
-  const leading = frontDoorText.trimStart();
-  if (!leading.startsWith(ESCALATE_VERDICT_TOKEN)) {
+  const machine = createFrontDoorVerdictMachine(false);
+  const step = machine.push(frontDoorText);
+  if (step.kind !== "escalate") {
     return "";
   }
-  return capEscalationBridge(leading.slice(ESCALATE_VERDICT_TOKEN.length));
+  if (step.bridge !== null) {
+    return step.bridge;
+  }
+  const finished = machine.finish();
+  return finished.kind === "bridge" ? finished.bridge : "";
 }
 
 /**
@@ -224,107 +263,187 @@ export function classifyFrontDoorLeading(
 }
 
 /**
- * Verdict-first gate over a front-door leg's delta stream: given the leg's
- * raw deltas in order, it releases only the text the caller actually hears.
- * A front-door leg's raw stream is a control plane, not assistant speech,
- * until its leading tokens classify, so anything downstream of the model
- * that shows text to a person reads the stream through this gate.
+ * One step of a front-door leg's stream under the verdict-first protocol,
+ * as returned by {@link FrontDoorVerdictMachine.push}.
+ */
+export type FrontDoorStep =
+  /** The leading tokens could still become a verdict token: keep buffering. */
+  | { readonly kind: "pending" }
+  /** Hold verdict: the leg is discarded and listening continues. */
+  | { readonly kind: "hold" }
+  /**
+   * The leg's output is the answer. `text` is the raw text this delta
+   * released; on the transition it includes the leading text held while the
+   * verdict was pending.
+   */
+  | { readonly kind: "answer"; readonly text: string }
+  /**
+   * Escalate verdict, decided by this delta. `bridge` is the capped holding
+   * phrase when this delta already completed it, else null while the phrase
+   * keeps streaming.
+   */
+  | { readonly kind: "escalate"; readonly bridge: string | null }
+  /** Post-verdict text still buffering toward the capped bridge. */
+  | { readonly kind: "bridging" }
+  /** The capped bridge is complete: hand off to the escalated leg. */
+  | { readonly kind: "bridge"; readonly bridge: string }
+  /** The leg already held, handed off, or finished; nothing more happens. */
+  | { readonly kind: "done" };
+
+/**
+ * The verdict-first state machine over a front-door leg's delta stream. One
+ * implementation drives every consumer of that stream: the live-voice
+ * session (which acts on the steps), the conversation-hub stream gate
+ * (which releases only the text the caller hears), and transcript hygiene
+ * (which replays a persisted row through it).
  *
- * `push` returns the text released by that delta (empty while the gate is
- * holding). `finish` is called when the leg completes normally and releases
- * a bridge that stopped short of a sentence terminator. A leg that is
- * cancelled instead spoke nothing past what `push` already released, so it
- * simply never calls `finish`.
+ * `push` feeds one delta and reports what it decided. `finish` is called
+ * when the leg completes normally: a bridge that stopped short of a
+ * sentence terminator hands off with what arrived. A leg that is cancelled
+ * instead never calls `finish`.
  */
-export interface FrontDoorStreamGate {
-  push(deltaText: string): string;
-  finish(): string;
+export interface FrontDoorVerdictMachine {
+  push(deltaText: string): FrontDoorStep;
+  finish(): FrontDoorStep;
 }
 
+const PENDING_STEP: FrontDoorStep = { kind: "pending" };
+const HOLD_STEP: FrontDoorStep = { kind: "hold" };
+const BRIDGING_STEP: FrontDoorStep = { kind: "bridging" };
+const DONE_STEP: FrontDoorStep = { kind: "done" };
+
 /**
- * Build a {@link FrontDoorStreamGate}. `holdEnabled` mirrors
+ * Build a {@link FrontDoorVerdictMachine}. `holdEnabled` mirrors
  * {@link classifyFrontDoorLeading}: true only for speculative (unified
  * front-door) legs, whose decision rule is the only one that teaches the
  * hold token.
  *
- * The three verdicts release differently, matching what the caller hears:
- *
- * - `hold`: the leg is discarded and its row deleted, so nothing is ever
- *   released.
- * - `escalate`: the only spoken text is the capped holding phrase, released
- *   in one piece once the bridge is complete (exactly what
- *   {@link capEscalationBridge} yields, so the released text, the audio, and
- *   the persisted row agree). The verdict token and anything streamed past
- *   the cap are dropped. A bridge shorter than
- *   {@link MIN_SPOKEN_BRIDGE_CHARS} releases nothing at all: the session
- *   substitutes an audio-only canned fallback for it, so there is no
- *   displayed text for the gate to agree with.
- * - `answer`: the leg's output IS the reply, so every delta passes through,
- *   including the leading text held back while the verdict was pending.
+ * The bridge handed off is exactly what {@link capEscalationBridge} yields,
+ * so the audio, the released text, the persisted row, and the phrase quoted
+ * to the escalated leg all agree. The verdict token and anything streamed
+ * past the cap are never released.
  */
-export function createFrontDoorStreamGate(
+export function createFrontDoorVerdictMachine(
   holdEnabled: boolean,
-): FrontDoorStreamGate {
+): FrontDoorVerdictMachine {
   let raw = "";
   let stage: "deciding" | "answer" | "bridging" | "done" = "deciding";
   let bridgeRaw = "";
   let releasedChars = 0;
 
-  const releaseBridge = (): string => {
+  const completeBridge = (): Extract<FrontDoorStep, { kind: "bridge" }> => {
     stage = "done";
-    const capped = capEscalationBridge(bridgeRaw);
-    // Below the spoken threshold the session throws the model's bridge away
-    // and plays a canned fallback that is audio-only, deleting the row rather
-    // than persisting a phrase the model never really produced (see
-    // `usesFallbackBridge` in `live-voice-session.ts`). Releasing the capped
-    // text here would put words on a subscriber's screen that the caller never
-    // heard, which is the same spoken/displayed divergence this gate exists to
-    // prevent.
-    return capped.length < MIN_SPOKEN_BRIDGE_CHARS ? "" : capped;
+    return { kind: "bridge", bridge: capEscalationBridge(bridgeRaw) };
   };
 
   return {
-    push(deltaText: string): string {
+    push(deltaText: string): FrontDoorStep {
       raw += deltaText;
       if (stage === "done") {
-        return "";
+        return DONE_STEP;
       }
       if (stage === "bridging") {
         bridgeRaw += deltaText;
-        return isEscalationBridgeComplete(bridgeRaw) ? releaseBridge() : "";
+        return isEscalationBridgeComplete(bridgeRaw)
+          ? completeBridge()
+          : BRIDGING_STEP;
       }
       if (stage === "deciding") {
         const verdict = classifyFrontDoorLeading(raw.trimStart(), holdEnabled);
         if (verdict === "pending") {
-          return "";
+          return PENDING_STEP;
         }
         if (verdict === "hold") {
           stage = "done";
-          return "";
+          return HOLD_STEP;
         }
         if (verdict === "escalate") {
           stage = "bridging";
           bridgeRaw = raw.trimStart().slice(ESCALATE_VERDICT_TOKEN.length);
-          return isEscalationBridgeComplete(bridgeRaw) ? releaseBridge() : "";
+          return {
+            kind: "escalate",
+            bridge: isEscalationBridgeComplete(bridgeRaw)
+              ? completeBridge().bridge
+              : null,
+          };
         }
         stage = "answer";
       }
       // Answer stage: release everything not yet released, which on the
       // transition includes the leading text the pending verdict held.
-      const chunk = raw.slice(releasedChars);
+      const text = raw.slice(releasedChars);
       releasedChars = raw.length;
-      return chunk;
+      return { kind: "answer", text };
     },
-    finish(): string {
+    finish(): FrontDoorStep {
       if (stage === "bridging") {
-        return releaseBridge();
+        return completeBridge();
       }
       stage = "done";
-      return "";
+      return DONE_STEP;
     },
   };
 }
 
+/**
+ * Verdict-first gate over a front-door leg's delta stream: given the leg's
+ * raw deltas in order, it releases only the text the caller actually hears.
+ * A front-door leg's raw stream is a control plane, not assistant speech,
+ * until its leading tokens classify, so anything downstream of the model
+ * that shows text to a person reads the stream through this gate.
+ *
+ * `push` returns the text released by that delta (empty while the gate is
+ * holding). `finish` is called when the leg completes normally and releases
+ * a bridge that stopped short of a sentence terminator. A leg that is
+ * cancelled instead spoke nothing past what `push` already released, so it
+ * simply never calls `finish`.
+ */
+export interface FrontDoorStreamGate {
+  push(deltaText: string): string;
+  finish(): string;
+}
+
+/**
+ * Build a {@link FrontDoorStreamGate} over a {@link FrontDoorVerdictMachine}.
+ *
+ * The three verdicts release differently, matching what the caller hears:
+ *
+ * - `hold`: the leg is discarded and its row deleted, so nothing is ever
+ *   released.
+ * - `escalate`: the only spoken text is the capped holding phrase, released
+ *   in one piece once the bridge is complete. A bridge shorter than
+ *   {@link MIN_SPOKEN_BRIDGE_CHARS} releases nothing at all: the session
+ *   substitutes an audio-only canned fallback for it (see
+ *   `usesFallbackBridge` in `live-voice-session.ts`) and deletes the row
+ *   rather than persisting a phrase the model never really produced, so
+ *   there is no displayed text for the gate to agree with.
+ * - `answer`: the leg's output IS the reply, so every delta passes through,
+ *   including the leading text held back while the verdict was pending.
+ */
+export function createFrontDoorStreamGate(
+  holdEnabled: boolean,
+): FrontDoorStreamGate {
+  const machine = createFrontDoorVerdictMachine(holdEnabled);
+  const releasable = (bridge: string): string =>
+    bridge.length < MIN_SPOKEN_BRIDGE_CHARS ? "" : bridge;
+  const release = (step: FrontDoorStep): string => {
+    switch (step.kind) {
+      case "answer":
+        return step.text;
+      case "escalate":
+        return step.bridge === null ? "" : releasable(step.bridge);
+      case "bridge":
+        return releasable(step.bridge);
+      default:
+        return "";
+    }
+  };
+  return {
+    push: (deltaText) => release(machine.push(deltaText)),
+    finish: () => release(machine.finish()),
+  };
+}
+
 /**
  * The escalated leg runs as its own voice turn. Rather than re-persist the
  * caller's utterance (it is already in history from the front-door leg), the
@@ -417,8 +536,8 @@ export function frontDoorDecisionRule(opts?: {
     "- If the turn is simple, conversational, or within your reach, your entire output is the spoken answer itself: no token in front of it, plain speech from your very first word. Most turns are answers; when unsure between answering and escalating, answer. Answer in the language the caller is speaking.",
     "- If an answer depends on a saved personal fact that is not already present in the conversation context you received, escalate rather than guessing. Personal context that is already present is yours to use directly.",
     `- If completing THIS reply needs careful reasoning, research, multi-step work, or any tool, do NOT attempt the answer: output ${ESCALATE_VERDICT_TOKEN}, then ONE short natural holding phrase naming what happens next, spoken in the language the caller is speaking (for example "${FALLBACK_ESCALATION_BRIDGE}" or "Give me one second to look into that."; those examples are English only), and stop after that single sentence. A stronger model finishes the turn while your phrase is spoken.`,
-    `${ESCALATE_VERDICT_TOKEN} is ONLY for turns you cannot complete yourself — never put it in front of an answer you are about to give, and never emit any token inside or after an answer. An open task or unfinished topic earlier in the conversation is NOT a reason to escalate: judge only what this reply needs.`,
-    "Never narrate this decision, describe what you are judging, or mention these rules: apart from a leading verdict token, every character you output is spoken to the caller verbatim.",
+    `${ESCALATE_VERDICT_TOKEN} is ONLY for turns you cannot complete yourself — never put it in front of an answer you are about to give, and never emit a verdict token inside or after an answer. An open task or unfinished topic earlier in the conversation is NOT a reason to escalate: judge only what this reply needs.`,
+    "Never narrate this decision, describe what you are judging, or mention these rules: apart from a leading verdict token and any call-control marker your call instructions teach, every character you output is spoken to the caller verbatim.",
   ].join("\n");
   return opts?.capabilityDigest ? `${rule}\n${opts.capabilityDigest}` : rule;
 }
@@ -446,7 +565,7 @@ export function escalatedContinuationRule(spokenBridge?: string): string {
     'Do NOT greet again, do NOT say things like "as I was saying", and do NOT repeat, paraphrase, or re-announce that holding phrase —',
     'opening with another "Let me check", "One moment", or any restatement of what you are about to do sounds broken, because the caller just heard that.',
     "Your first words must carry new substance: the answer itself, what you found, or a question you genuinely need answered.",
-    `Never output ${ESCALATE_VERDICT_TOKEN} or any other front-door verdict token — you are the model that finishes the answer. (The [-1] room-minimize marker from your call instructions is not a verdict token and stays allowed.)`,
+    `Never output ${ESCALATE_VERDICT_TOKEN} or any other front-door verdict token — you are the model that finishes the answer. (Call-control markers your call instructions teach, such as [END_CALL], are not verdict tokens and stay allowed.)`,
     "Reply in the same language as the caller's question.",
   ].join(" ");
 }