@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/AGENTS.md

@@ -87,6 +87,10 @@ The module-level dependency-injection pattern (`registerFooDeps()`) used by some
 
 Telemetry event types are defined by a platform-generated wire contract (`src/telemetry/telemetry-wire.generated.ts`) that `src/telemetry/types.ts` layers over, with pre-flush validation against it. Adding a new event type starts platform-side, not here. The mechanics, the drift guards, and the cross-repo ordering are documented next to the code they govern: see [`src/telemetry/AGENTS.md`](src/telemetry/AGENTS.md).
 
+## Daemon i18n
+
+User-facing copy the daemon generates as a hardcoded constant goes through `src/i18n/`. Persist the message key. Resolve with `t(key, locale)` at the HTTP/CLI/channel edge. Never persist a translated string, and never match stored display strings back to keys. See [`src/i18n/AGENTS.md`](src/i18n/AGENTS.md).
+
 ## Code comments
 
 When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.

package/ARCHITECTURE.md

@@ -609,9 +609,11 @@ Every phone call connects over Twilio Media Streams: the voice webhook emits `<C
 
 Transcription mode is selected once per session in `media-stream-stt-session.ts`:
 
-- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials.
+- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials. While something is interruptible (an assistant turn in flight, thinking or speaking, or a completed turn's tail still playing from Twilio's buffer), caller speech arms the shared sustained-speech barge-in guard (`src/calls/barge-in-guard.ts`, the same accounting live voice uses: speech accumulates toward 250 ms, short gaps are tolerated, a run that is mostly silence resets) and every inbound frame feeds it; outside that window the guard is dropped, so the caller's own utterance never carries into a turn that starts before the local VAD ends it. Only a fired guard reaches `CallController.handleBargeIn`, which interrupts a turn in either phase and ignores an idle controller (the playing tail is cleared instead).
 - **Batch fallback**: otherwise the session segments turns with the energy-based `MediaTurnDetector` and transcribes each completed turn via the same role's batch API. Both halves of a call read the `telephony` role, which is why a role names its consumer rather than a boundary.
 
+Every phone turn runs the same two-leg triage as live voice through `startVoiceTurn` (`src/calls/voice-session-bridge.ts`): `call-controller.ts` opens on a toolless front-door leg (`routingLeg: "front-door"`, the `voiceFrontDoor` call site) and drives it through the shared `createFrontDoorLegCoordinator` (`src/calls/voice-leg-coordinator.ts`), which reads the stream through the verdict machine and sequences the hand-off (pause narration, abort the leg, resolve and speak the bridge, mark it as the floor holder, start the escalated leg pinned to the conversation's own model, re-arm narration); each driver supplies only a host for how text and the bridge are spoken, how a leg is started or aborted, and (live voice only) the speculative hold and commit. Phone has no partial transcripts, so the hold verdict is never taught and routing is escalate-only. The controller also passes the bridge's turn callbacks (tool activity is recorded as `tool_use_started` / `tool_use_completed` call events, persisted row ids ride the `assistant_spoke` event), `launchedAtMs` for dispatch timing, and a `voiceTelemetry` bag keyed by the call session with a `phone_inbound` / `phone_outbound` entry. Both drivers share the spoken progress narration cadence (`src/calls/voice-progress-cadence.ts`, tuned by `voice.frontModel.progress`): the cadence owns the tool-activity log, the triggers (an ops burst, a long operation completing, a full interval of audible silence with news, the `maxSilenceMs` heartbeat) and the generated or static phrase, while each driver supplies its own view of audible silence (live voice from its TTS queue and playback-tail estimate; the media-stream transport from `isPlaybackIdle()` and a running sum of sent frame durations) and how to speak a phrase.
+
 A credential preflight (`resolveTelephonyCredentialReadiness()` in `src/calls/telephony-credential-preflight.ts`) gates every call: it requires a credentialed, telephony-capable STT provider **and** a media-stream-playable TTS provider (the configured one or a credentialed playable fallback). Inbound calls that fail the preflight receive `<Say>` setup-required copy plus `<Hangup/>` instead of a doomed stream; outbound placement fails before dialing via `preflightVoiceIngress()` with the same user-facing message.
 
 Key modules:
@@ -729,9 +731,9 @@ The assistant-side live voice module is intentionally bounded under `src/live-vo
 | `live-voice-archive.ts`         | Audio artifact creation/linking for user utterance and assistant response message IDs                                                                       |
 | `live-voice-metrics.ts`         | Per-session and per-turn latency snapshots emitted as `metrics` frames                                                                                      |
 
-Live voice STT uses the same `resolveStreamingTranscriber()` path as conversation streaming. For V1 latency-sensitive behavior, the selected `services.stt.provider` must resolve to a `daemon-streaming` transcriber whose catalog entry has `conversationStreamingMode: "realtime-ws"` and usable credentials. Providers that only support batch or incremental-batch transcription remain valid for other voice surfaces, but do not satisfy live voice's streaming STT requirement.
+Live voice STT uses the same `resolveStreamingTranscriber()` path as conversation streaming, dialed with the provider the `liveVoice` STT role resolves to after managed-speech defaulting (`resolveEffectiveSpeechProviders`, see `config/managed-speech-defaults.ts`). For V1 latency-sensitive behavior, that provider must resolve to a `daemon-streaming` transcriber whose catalog entry has `conversationStreamingMode: "realtime-ws"` and usable credentials. Providers that only support batch or incremental-batch transcription remain valid for other voice surfaces, but do not satisfy live voice's streaming STT requirement.
 
-Live voice TTS uses `streamLiveVoiceTtsAudio()` and the configured `services.tts.provider`. The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Providers whose catalog entry advertises `supportsStreaming` (currently all four catalog providers: ElevenLabs, Fish Audio, Deepgram, and xAI) satisfy this requirement; a buffered-only provider would remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
+Live voice TTS uses `streamLiveVoiceTtsAudio()` and the TTS provider that `resolveEffectiveSpeechProviders` settles on (the configured `services.tts.provider`, or the managed `vellum` provider when the configured one has no usable credentials). The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Providers whose catalog entry advertises `supportsStreaming` (currently all five catalog providers: ElevenLabs, Fish Audio, Deepgram, xAI, and the managed Vellum provider) satisfy this requirement; a buffered-only provider would remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
 
 The `voiceFrontDoor` prompt skips current-turn legacy and v3 memory retrieval, while prior frozen memory cards and static memory context remain available. The front-door rule escalates rather than guessing when required personal context is absent. The escalated leg runs the ordinary memory pipeline against the latest visible caller prompt before the quality model, with low selector effort. This keeps memory work off the front-door TTFT path without cross-leg speculative state.
 
@@ -1294,9 +1296,8 @@ graph TB
         RM_DIR["rmSync skill directory"]
     end
 
-    subgraph "File Watcher"
-        WATCHER["Skills directory watcher<br/>detects changes"]
-        EVICT["Session eviction<br/>+ recreation"]
+    subgraph "Capability reseed"
+        RESEED["SKILL.md mtime poll<br/>reseeds capability cards"]
     end
 
     SNIPPET --> EVAL_TOOL
@@ -1309,14 +1310,12 @@ graph TB
     SCAFFOLD --> MANAGED_STORE
     MANAGED_STORE --> SKILL_DIR
 
-    SKILL_DIR --> WATCHER
-    WATCHER --> EVICT
-
+    SKILL_DIR --> RESEED
     SKILL_DIR --> SKILL_LOAD
     SKILL_LOAD --> SESSION
 
     DELETE --> RM_DIR
-    RM_DIR --> WATCHER
+    RM_DIR --> RESEED
 ```
 
 **Key design decisions:**
@@ -1324,7 +1323,7 @@ graph TB
 - `evaluate_typescript_code` always forces `sandbox.enabled = true` regardless of global config.
 - Snippet contract: must export `default` or `run` with signature `(input: unknown) => unknown | Promise<unknown>`.
 - Managed-store writes are atomic (tmp file + rename) to prevent partial `SKILL.md` files.
-- After persist or delete, the file watcher triggers conversation eviction; the next turn runs in a fresh conversation. The model's system prompt instructs it to continue normally.
+- After persist or delete, capability cards reseed from the `SKILL.md` set. The next turn continues in the same conversation.
 - macOS UI shows Inspect and Delete controls for managed skills only (source = "managed").
 - `skill_load` resolves the recursive include graph (via `include-graph.ts`) before emitting output. Missing children are listed as suggested skills without child `<loaded_skill>` markers; cycles still produce `isError: true` with no marker. Valid includes produce an "Included Skills (immediate)" metadata section showing child ID, name, description, and path.
 
@@ -1407,15 +1406,15 @@ skills/<skill-id>/
 
 The following capabilities ship as bundled skills in `assistant/src/config/bundled-skills/`:
 
-| Skill ID        | Tools                                                                                                                                                                                                                                                             | Purpose                                                                                                                                                                                                                                                                                              |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `browser`       | `browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_close`, `browser_click`, `browser_type`, `browser_press_key`, `browser_wait_for`, `browser_extract`, `browser_fill_credential`                                                             | Headless browser automation — web scraping, form filling, interaction (previously core-registered as `headless-browser`; now skill-provided with default allow rules)                                                                                                                                |
-| `gmail`         | Gmail search, archive, send, etc.                                                                                                                                                                                                                                 | Email management via OAuth2 integration                                                                                                                                                                                                                                                              |
-| `computer-use`  | `computer_use_observe`, `computer_use_click`, `computer_use_type_text`, `computer_use_key`, `computer_use_scroll`, `computer_use_drag`, `computer_use_wait`, `computer_use_open_app`, `computer_use_run_applescript`, `computer_use_done`, `computer_use_respond` | Computer-use proxy tools preactivated via `preactivatedSkillIds` in desktop sessions. Each tool forwards actions to a compatible connected desktop host via `HostCuProxy`, which handles request/resolve proxying, step counting, loop detection, and observation formatting in the same agent loop. |
-| `weather`       | `get-weather`                                                                                                                                                                                                                                                     | Fetch current weather data                                                                                                                                                                                                                                                                           |
-| `app-builder`   | `app_create`, `app_delete`, `app_refresh`, `app_generate_icon`                                                                                                                                                                                                    | Dynamic app authoring — create and manage persistent apps; file editing uses generic file tools plus `app_refresh` (activated via `skill_load app-builder`; `app_open` remains a core proxy tool)                                                                                                    |
-| `self-upgrade`  | (instruction-only)                                                                                                                                                                                                                                                | Self-improvement workflow                                                                                                                                                                                                                                                                            |
-| `start-the-day` | (instruction-only)                                                                                                                                                                                                                                                | Morning briefing routine                                                                                                                                                                                                                                                                             |
+| Skill ID        | Tools                                                                                                                                                                                                                                                                                      | Purpose                                                                                                                                                                                                                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browser`       | `browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_close`, `browser_click`, `browser_type`, `browser_press_key`, `browser_wait_for`, `browser_extract`, `browser_fill_credential`                                                                                      | Headless browser automation: web scraping, form filling, interaction (previously core-registered as `headless-browser`; now skill-provided with default allow rules)                                                                                                                                 |
+| `gmail`         | Gmail search, archive, send, etc.                                                                                                                                                                                                                                                          | Email management via OAuth2 integration                                                                                                                                                                                                                                                              |
+| `computer-use`  | `computer_use_observe`, `computer_use_click`, `computer_use_type_text`, `computer_use_key`, `computer_use_scroll`, `computer_use_drag`, `computer_use_wait`, `computer_use_open_app`, `computer_use_run_applescript`, `computer_use_sequence`, `computer_use_done`, `computer_use_respond` | Computer-use proxy tools preactivated via `preactivatedSkillIds` in desktop sessions. Each tool forwards actions to a compatible connected desktop host via `HostCuProxy`, which handles request/resolve proxying, step counting, loop detection, and observation formatting in the same agent loop. |
+| `weather`       | `get-weather`                                                                                                                                                                                                                                                                              | Fetch current weather data                                                                                                                                                                                                                                                                           |
+| `app-builder`   | `app_create`, `app_delete`, `app_refresh`, `app_generate_icon`                                                                                                                                                                                                                             | Dynamic app authoring: create and manage persistent apps; file editing uses generic file tools plus `app_refresh` (activated via `skill_load app-builder`; `app_open` remains a core proxy tool)                                                                                                     |
+| `self-upgrade`  | (instruction-only)                                                                                                                                                                                                                                                                         | Self-improvement workflow                                                                                                                                                                                                                                                                            |
+| `start-the-day` | (instruction-only)                                                                                                                                                                                                                                                                         | Morning briefing routine                                                                                                                                                                                                                                                                             |
 
 ### Activation and Projection Flow
 
@@ -2192,7 +2191,7 @@ The `TtsUseCase` discriminator (`"phone-call"` or `"message-playback"`) lets pro
 - **`native-twilio`** — the text-token path: spoken text is sent via `sendTextToken()`, which the media-stream transport re-synthesizes through daemon TTS. Collapsing this mode into `synthesized-play` is a documented deferred follow-up.
 - **`synthesized-play`** — The assistant synthesises audio via the provider's HTTP API and streams it through the audio store / `sendPlayUrl()` path.
 
-**Phone call integration:** Phone calls run on the media-stream transport, where the daemon synthesises speech via the configured TTS provider and transcodes it to mu-law 8 kHz frames (`media-stream-output.ts`). Each catalog entry declares `mediaStreamPlayback.outputFormat` (`pcm`, `wav`, or `none`); `resolveTelephonyTtsCapability()` (`src/calls/telephony-tts-capability.ts`) combines that field with credential availability into a playable / not-playable verdict, and the call TTS resolver falls back to a credentialed playable provider rather than producing silence.
+**Phone call integration:** Phone calls run on the media-stream transport, where the daemon synthesises speech via the effective TTS provider (the configured one after managed-speech defaulting, `resolveEffectiveSpeechProviders`, the same substitution live voice makes) and transcodes it to mu-law 8 kHz frames (`media-stream-output.ts`). Each catalog entry declares `mediaStreamPlayback.outputFormat` (`pcm`, `wav`, or `none`); `resolveTelephonyTtsCapability()` (`src/calls/telephony-tts-capability.ts`) combines that field with credential availability into a playable / not-playable verdict, and the call TTS resolver falls back to a credentialed playable provider rather than producing silence.
 
 **Adding a new TTS provider (catalog-first checklist):**
 

package/docs/architecture/turn-actor.md

@@ -60,14 +60,21 @@ and restore the prior value afterwards, each guarding the restore so a turn that
 started in between is not clobbered. They are supplying the acting actor for
 their run, and are covered by this contract.
 
-A queued message commits to a run at its drain, not at its enqueue. The drains
-(`drainSingleMessage` and `drainBatch` in `conversation-process.ts`) stamp the
-queued sender the way `processMessage` stamps its committing actor, and re-scope
-the resident history to them, so a turn drained behind another actor's turn
-runs as its sender everywhere the resting actor is read, not only in the
-per-turn snapshot. A steered drain skips the re-scope: its sender owned the
-turn it cut off, and the resident history may carry the in-memory repair of the
-abandoned `tool_use`.
+The queue drains are deliberately not in that set. `drainSingleMessage` and
+`drainBatch` carry the queued sender on the per-turn field and into the run,
+and leave the resting slot alone: at the point they stamp, the drain has not
+yet proved it holds the processing lock. Its `isProcessing()` check is a
+time-of-check guard whose documented backstop is the persist that can still
+fail busy, and the requeue on that path restores the queue and the steer flag
+only. A drain that stamped the slot would therefore leave the conversation
+attributed to a sender whose turn never ran.
+
+The consequence is that a cross-actor drain runs against history scoped for the
+previous actor, because `ensureActorScopedHistory` reads the slot. That is a
+real defect and it is LUM-3344's, which owns the fix: scope the transcript at
+assembly time from the turn's actor, rather than mutating a shared transcript
+and tracking who it was scoped for. Do not close it by making the drain stamp
+the slot first.
 
 `call-controller` keeps its own `trustContext` on its own object and never reads
 the conversation's. It is outside this contract.

package/docs/guardian-request-flow.md

@@ -72,6 +72,22 @@ it end to end:
   same way a failed card edit does. The write-vs-resolve race converges
   from the other side too: the feed writer re-checks canonical status
   after its append.
+- The receipt is the whole retire mechanism, so everything that must
+  stop happening lives in `writeGuardianFeedReceipt`: the terminal
+  `guardianRequest.status` withdraws every client affordance, urgency
+  drops to `medium` to leave the "Needs attention" treatment, and a
+  still-`new` item is marked `seen` (unread means the user has
+  something to review, which a resolved request is not). That clear
+  runs only on the edge into terminal, so re-running the fan-out
+  neither pulls a cleared receipt back into the bell nor undoes a user
+  who marked the receipt unread again.
+- Terminal receipts that never passed the edge are cleared once for
+  each assistant by `healLegacyGuardianReceiptUnread`, which the sweep calls
+  ahead of its gateway read. One-shot rather than recurring: such a row
+  and a `new` the user set deliberately are indistinguishable, so a
+  completion sentinel in the daemon checkpoint ledger records the
+  boundary instead. The transition is re-evaluated inside the writer
+  queue and moves only `new`, exactly as the edge does.
 - The feed writer's bulk-dismiss pass skips pending guardian items
   (`isPendingGuardianFeedItem`), so "Clear all" can never retire an
   unresolved request; only its receipt is clearable.

package/node_modules/@vellumai/slack-text/src/index.ts

@@ -113,7 +113,7 @@ export async function buildSlackUserLabelMap(
       // that label directly; only queue a lookup when the label is missing,
       // empty, or ID-shaped. Mirrors the channel builder below.
       const [, embeddedLabel] = splitSlackLabel(match[0].slice(1, -1));
-      const sanitizedEmbeddedLabel = sanitizeOptionalLabel(embeddedLabel);
+      const sanitizedEmbeddedLabel = sanitizeEmbeddedSlackLabel(embeddedLabel);
       if (sanitizedEmbeddedLabel && sanitizedEmbeddedLabel !== id) continue;
       if (seen.has(id)) continue;
       seen.add(id);
@@ -151,7 +151,7 @@ export async function buildSlackChannelLabelMap(
     for (const match of text.matchAll(SLACK_CHANNEL_REFERENCE_RE)) {
       const id = match[1];
       const [, embeddedLabel] = splitSlackLabel(match[0].slice(1, -1));
-      const sanitizedEmbeddedLabel = sanitizeOptionalLabel(embeddedLabel);
+      const sanitizedEmbeddedLabel = sanitizeEmbeddedSlackLabel(embeddedLabel);
       if (sanitizedEmbeddedLabel && sanitizedEmbeddedLabel !== id) continue;
       if (!seen.has(id)) {
         seen.add(id);
@@ -192,9 +192,7 @@ function renderUserMention(
   // prefer it over a lookup, mirroring renderChannelReference. The embedded
   // label is Slack-sourced (part of the token), so entities decode before
   // sanitization; the caller-resolved label below is not.
-  const embeddedLabel = sanitizeOptionalLabel(
-    label === undefined ? undefined : decodeSlackHtmlEntities(label),
-  );
+  const embeddedLabel = sanitizeEmbeddedSlackLabel(label);
   if (embeddedLabel && embeddedLabel !== id) {
     return `@${embeddedLabel}`;
   }
@@ -219,9 +217,7 @@ function renderChannelReference(
   );
   // The embedded label is Slack-sourced (part of the token), so entities
   // decode before sanitization; the caller-resolved label below is not.
-  const embeddedLabel = sanitizeOptionalLabel(
-    label === undefined ? undefined : decodeSlackHtmlEntities(label),
-  );
+  const embeddedLabel = sanitizeEmbeddedSlackLabel(label);
   if (embeddedLabel && embeddedLabel !== channelId) {
     return `#${embeddedLabel}`;
   }
@@ -320,6 +316,15 @@ export function sanitizeSlackLabel(
   return sanitized || undefined;
 }
 
+// Slack-sourced labels are decoded before validation in both lookup and render.
+function sanitizeEmbeddedSlackLabel(
+  label: string | undefined,
+): string | undefined {
+  return sanitizeOptionalLabel(
+    label === undefined ? undefined : decodeSlackHtmlEntities(label),
+  );
+}
+
 function sanitizeOptionalLabel(label: string | undefined): string | undefined {
   return sanitizeSlackLabel(label);
 }

package/node_modules/@vellumai/slack-text/src/label-resolution-entities.test.ts

@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import { describe, test } from "bun:test";
+import {
+  buildSlackChannelLabelMap,
+  buildSlackUserLabelMap,
+  renderSlackTextForModel,
+} from "./index.js";
+
+describe("Slack embedded-label lookup parity", () => {
+  const cases = [
+    { id: "U123", prefix: "@", build: buildSlackUserLabelMap, mapKey: "userLabels" },
+    {
+      id: "C123",
+      prefix: "#",
+      build: buildSlackChannelLabelMap,
+      mapKey: "channelLabels",
+    },
+  ] as const;
+
+  for (const { id, prefix, build, mapKey } of cases) {
+    for (const label of ["<>", `<${id}>`, "< @# >"]) {
+      test(`${prefix} resolves label ${label} after Slack entity decoding`, async () => {
+        const text = `<${prefix}${id}|${label}>`;
+        const requested: string[] = [];
+        const labels = await build([text], async (value) => {
+          requested.push(value);
+          return "Example Name";
+        });
+        assert.deepEqual(requested, [id]);
+        assert.equal(
+          renderSlackTextForModel(text, { [mapKey]: labels }),
+          `${prefix}Example Name`,
+        );
+      });
+    }
+
+    for (const label of ["&lt;Example&gt;", "R&amp;D", "&amp;lt;&amp;gt;"]) {
+      test(`${prefix} keeps usable embedded label ${label} without lookup`, async () => {
+        const requested: string[] = [];
+        const text = `<${prefix}${id}|${label}>`;
+        const labels = await build([text], async (value) => {
+          requested.push(value);
+          return "Wrong Label";
+        });
+        assert.deepEqual(requested, []);
+        assert.deepEqual(labels, {});
+        const expected =
+          label === "&lt;Example&gt;"
+            ? "Example"
+            : label === "R&amp;D"
+              ? "R&D"
+              : "&lt;&gt;";
+        assert.equal(
+          renderSlackTextForModel(text, { [mapKey]: labels }),
+          `${prefix}${expected}`,
+        );
+      });
+    }
+
+    test(`${prefix} deduplicates required lookups across encoded and bare mentions`, async () => {
+      const requested: string[] = [];
+      const labels = await build(
+        [`<${prefix}${id}|&lt;&gt;>`, `<${prefix}${id}>`],
+        async (value) => {
+          requested.push(value);
+          return "Example";
+        },
+      );
+      assert.deepEqual(requested, [id]);
+      assert.deepEqual(labels, { [id]: "Example" });
+    });
+
+    test(`${prefix} does not decode caller-resolved entity text`, async () => {
+      const text = `<${prefix}${id}|&lt;&gt;>`;
+      const labels = await build([text], async () => "&lt;Example&gt;");
+      assert.equal(
+        renderSlackTextForModel(text, { [mapKey]: labels }),
+        `${prefix}&lt;Example&gt;`,
+      );
+    });
+
+    test(`${prefix} preserves unknown fallback after a failed required lookup`, async () => {
+      let attempts = 0;
+      const text = `<${prefix}${id}|&lt;&gt;>`;
+      const labels = await build([text], async () => {
+        attempts++;
+        throw new Error("unavailable");
+      });
+      assert.equal(attempts, 1);
+      assert.deepEqual(labels, {});
+      const expected = prefix === "@" ? "@unknown-user" : "#unknown-channel";
+      assert.equal(renderSlackTextForModel(text, { [mapKey]: labels }), expected);
+    });
+  }
+});