@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162314.7778bc8

package/.env.example

@@ -2,6 +2,8 @@
 ANTHROPIC_API_KEY=sk-ant-...
 OPENAI_API_KEY=sk-...
 GEMINI_API_KEY=...
+# Optional. TypeSafe / Jev System One decision model.
+TYPESAFE_API_KEY=...
 # Optional for authenticated/proxied Ollama deployments
 OLLAMA_API_KEY=
 # Optional override (defaults to http://127.0.0.1:11434/v1)

package/AGENTS.md

@@ -16,7 +16,7 @@ When you introduce a new env var that the assistant process needs to read at run
 
 **Default to including it.** If the var doesn't contain secrets (e.g. a URL, a feature flag, a path, a mode string), add it. Only omit it if it carries credential material (tokens, passwords, private keys) — those must stay isolated to CES.
 
-`CES_LOCAL_SOCKET` is intentionally included despite the socket exposing credential RPCs: assistant subprocesses are expected to reach CES. Credential protection is rules-based access control inside CES, not socket-path secrecy (see root `AGENTS.md`). `CES_SERVICE_TOKEN` and `CES_CREDENTIAL_URL` are also forwarded: managed children still resolve connections through CES HTTP, and the socket path is not a sufficient substitute yet. See the comment on those keys in `src/tools/terminal/safe-env.ts` before attempting to strip them.
+`CES_BOOTSTRAP_SOCKET_DIR` is forwarded so children can reach CES over IPC. `CES_SERVICE_TOKEN` and `CES_CREDENTIAL_URL` are also forwarded so children can fail over to CES HTTP until that transport is removed. Credential protection is rules-based access control inside CES, not socket-path secrecy (see root `AGENTS.md`).
 
 ## Daemon startup philosophy
 
@@ -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/Dockerfile

@@ -130,13 +130,13 @@ RUN bun run scripts/smoke-container-workspace-dependencies.ts
 # The repo-root .dockerignore decides which skills (and files) ship.
 COPY skills /app/skills
 
-# Materialize the git-ignored offline plugin manifest from its canonical source.
-# `assistant/src/cli/lib/plugin-catalog-local.ts` statically imports this JSON
-# (loaded even when platform features are enabled), so it must exist in the image
-# — the build installs with --ignore-scripts, so the postinstall sync that
-# regenerates it in dev never runs here. Mirrors how CI materializes the
-# feature-flag registry before building.
-COPY plugins/marketplace.json /app/assistant/src/cli/lib/bundled-marketplace.json
+# Materialize the git-ignored offline marketplace and reviewed local packages.
+# The build installs with --ignore-scripts, so the postinstall sync that creates
+# these static imports in development never runs here.
+COPY plugins /app/plugins
+COPY meta/sync-bundled-copies.ts /app/meta/
+RUN cd /app && bun run meta/sync-bundled-copies.ts --plugins-only && \
+    bun run assistant/scripts/generate-bundled-plugin-packages.ts
 
 # Install assistant CLI launcher backed by the bundled assistant package
 RUN printf '#!/usr/bin/env sh\nexec bun run /app/assistant/src/index.ts "$@"\n' > /usr/local/bin/assistant && \

package/docs/architecture/integrations.md

@@ -552,6 +552,13 @@ Message content (stored as JSON `ContentBlock[]` in the DB) is flattened for the
 
 Attachments are materialized into `conversations/<conversation>/attachments/` as soon as they are linked to a message. During disk-view sync, the JSONL record reuses those filenames directly and only falls back to materializing legacy rows that have not been projected yet. Filename collisions are still resolved by appending a numeric suffix (e.g., `photo-2.png`, `photo-3.png`).
 
+Computer-use screenshot media is materialized while its tool-result row is
+finalized, so earlier frames remain represented in tool history, JSONL, and
+compaction inputs. The final screenshot-bearing invocation reuses that same
+attachment ID for an additional reply link. A single attachment can therefore
+appear on both a tool-result row and a reply row without creating a second
+attachment-store object.
+
 ### Backfill Migration
 
 Existing conversations created before the disk view was introduced are backfilled by workspace migration `009-backfill-conversation-disk-view`, which replays all conversations and their messages through the disk-view sync functions.

package/docs/architecture/memory.md

@@ -87,8 +87,17 @@ graph LR
   nesting existed still parse, since an unindented body line that is not itself
   entry-shaped is read as a continuation.
 - **Consolidation** (`substrate/consolidation-job.ts`) is a background
-  agent conversation that files buffer entries into concept pages, rewrites
-  the aggregate views, and trims the buffer. Scheduling
+  agent conversation that files buffer entries into concept pages and
+  rewrites the aggregate views. The agent never writes the buffer: the job
+  snapshots `buffer.md`, hands the run its pass's entries verbatim in the
+  prompt, and after the run removes exactly those entries itself through
+  `buffer-file.ts` (the module that also owns the append path, so the two
+  writers of the buffer share one protocol). Removal happens only when the
+  run's persisted messages hold a page-writing tool call with a non-error
+  result, the same evidence bar the retrospective's cursor advance uses; a
+  run that wrote nothing, failed, or timed out leaves the buffer intact for
+  the next pass. Entries deferred past the per-run cap and entries appended
+  while the run was in flight are therefore never lost. Scheduling
   (`maybeEnqueueGraphMaintenanceJobs` in `jobs-worker.ts`):
   - interval-based (`memory.v2.consolidation_interval_hours`, default 8h),
     skipped below `MIN_BUFFER_LINES_FOR_CONSOLIDATION` (10) **unless** the

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/credential-execution-service.md

@@ -221,7 +221,7 @@ These invariants are enforced by guard tests and code review:
 4. **Grants and audit logs are CES-internal**: The assistant cannot read CES grant tables or audit logs directly. CES exposes grant status and audit summaries via RPC responses.
 5. **No generic authenticated HTTP clients in secure commands**: `curl`, `wget`, `httpie`, interpreters, and shell trampolines are structurally denied as secure command entrypoints. This is checked at manifest validation and re-checked at execution time.
 6. **Managed CES container runs as non-root**: The CES Docker image runs as `uid 1001` (user `ces`). The CES data volume is owned by this user.
-7. **Single active bootstrap connection**: In managed mode, CES accepts one connection on the bootstrap socket and unlinks the socket path while that connection is live, so no second process can connect concurrently. CES is a long-lived sidecar: when the active session ends (the assistant disconnects or its container restarts), CES re-binds the socket and awaits the assistant's reconnection rather than shutting down. At most one connection is ever active; the sidecar only exits on SIGTERM/SIGINT.
+7. **Multi-connection bootstrap socket**: In managed mode, CES listens on the bootstrap socket as a concurrent multi-connection server and keeps the path bound. The assistant and its child processes each open their own RPC connection. CES is a long-lived sidecar: it stays up across assistant restarts and only exits on SIGTERM/SIGINT.
 
 ## Guarantees by deployment mode
 

package/docs/desktop-browser-cli.md

@@ -0,0 +1,35 @@
+# Virtual desktop browser CLI
+
+`assistant browser --virtual-desktop` uses the browser CLI's shared operation handlers against the Chrome process owned by `DesktopSessionManager`. It requires a platform-hosted container, the `assistant-desktop` flag, completed automatic desktop installation and an identified guardian conversation. Availability is checked before starting or reusing control and after asynchronous startup; loss of the flag or installation readiness cancels active control. The first eligible browser command waits for the shared installation job, starts Chrome, and executes the original action exactly once. Cancellation and feature revocation stop the pending action while shared installation can finish for other viewers. Browser CLI requests allow ten minutes, with an eight-minute setup wait limit. Eligible web conversations receive browser guidance in the bash tool description, including the configured shell timeout; native clients retain their existing tool description. Opening the picture-in-picture panel also starts setup and shows progress automatically; failed installs retain a retry action. The persistent profile remains `data/desktop-profile`; no data migration or extension installation is required.
+
+Automatic browser selection in platform-hosted web conversations uses the streamed Chrome when the desktop flag is enabled and the actor is an identified guardian. The macOS and Windows apps keep their existing browser selection and fallback behavior; they use the streamed desktop only with explicit `--virtual-desktop`. Their shared renderer reports a `web` transport, so selection also reads the active turn's frozen `clientOs`; it does not change transport identity or host capability checks. Explicit `--virtual-desktop`, `--browser-mode`, `--target-client-id` and active-tab requests override the default. Existing personal-browser sessions and tab pins remain on their selected browser. Tab commands use the same streamed-browser default as page commands. `--browser-mode local` selects assistant-side Playwright, not the user's Chrome.
+
+The legacy `--desktop` option remains an alias. The deployment flag key `assistant-desktop`, API paths, sync tags and persistent profile path are unchanged for compatibility. The shared `isVirtualDesktopEnabled` gate rejects self-hosted assistants, including local Docker, for setup, streaming and control.
+
+```mermaid
+flowchart LR
+  CLI[assistant browser --virtual-desktop] --> IPC[Existing browser IPC routes]
+  IPC --> Lease[DesktopAutomationLease conversation and actor lease]
+  Lease --> Shared[Shared browser operation handlers]
+  Shared --> CDP[Scoped desktop CDP client]
+  CDP --> Chrome[Managed Chrome on display :99]
+  Chrome --> Stream[Existing desktop stream]
+```
+
+Chrome and its dock launcher share the managed profile and loopback debug port. For Chrome reopened from the dock, the profile singleton lock identifies a candidate PID, validated against the installed executable, profile and loopback debug arguments. Discovery checks `/proc` socket ownership against that browser PID, refuses redirects and validates the returned browser WebSocket endpoint. The connection stays within the container. No CDP endpoint or token is exposed to the renderer.
+
+The desktop client bypasses personal-browser discovery, extension reconnect waits and backend fallback. It reuses the existing AX snapshot, DOM element resolution, mouse, keyboard, extraction and credential-fill implementations. Operation-scoped clients borrow the lease's connection; disposing one does not release the lease. `detach`, `close`, turn completion, cancellation, errors and idle expiry release control. Turn completion clears the activity indicator immediately and queues browser cleanup before the next automation session; it leaves Chrome and the current page open for the user. Only `tabs close` closes a Chrome tab.
+
+`assistant browser --virtual-desktop screenshot --output /tmp/desktop-page.jpg` captures a color page image through CDP `Page.captureScreenshot`. It excludes the browser toolbar and desktop dock. `snapshot` returns semantic page structure. Agents should use these interfaces and let the manager start the desktop, including when older memory notes describe manual Xvnc, `xdotool` or scratch XWD conversion scripts.
+
+Tab IDs are ephemeral numeric aliases for this managed browser's CDP target IDs. They are never personal extension tab IDs. Initial attachment selects an existing HTTP(S) page or opens a blank tab. Use `tabs list` and `tabs select --tab-id <id>` to choose explicitly. Navigation, tab selection, document replacement and release clear the desktop snapshot map. Personal-browser snapshots use a separate namespace.
+
+CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications are outside the browser CLI; users can interact with them directly in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation. For logins, the assistant uses saved credentials first and securely collects missing credentials with `assistant credentials prompt`, then fills the login form itself. Every CAPTCHA and bot-detection challenge, including sliders and press-and-hold checks, is handed to the user before the assistant attempts it. When human interaction is needed, the assistant calls `ask_question` with `desktopHelp: { message, doneLabel, skipLabel }` in the user's language. The tool releases held browser input and reserves the desktop before publishing a question with `presentation: "virtual_desktop"`. The live viewer mounts only in the attended Electron window, with browser focus as a fallback on older shells and the web, so conversations release it when focus changes. A busy viewer offers Reconnect if the previous connection has not finished closing. The compact card lives in the scrolling message transcript, with expandable instructions and a preview capped at 384 pixels wide. It hosts the shared live viewer, with Step In opening its full desktop modal and Done or Skip resolving the existing question response. The assistant retains an exclusive human-help reservation while waiting. Done resumes the same conversation's automation lease for its fresh snapshot; Skip, closure, timeout and cancellation release it. The browser idle timer does not expire a pending human-help reservation. The live preview connects after Show live preview or Step In, and reuses an already-open picture-in-picture viewer. Other devices receiving the card do not automatically open a stream. When the request resolves, its interactive viewer closes or returns to the read-only PiP session that was open before the request. Skip does not imply the obstacle was resolved. Older clients show the same request as a normal Done/Skip question, with model-localized labels retained in history. Channels without dynamic UI return guidance to continue in the app rather than waiting on an unusable card.
+
+The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Turn-triggered cancellation retries cleanup automatically until it succeeds or ownership changes. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
+
+`--use-active-tab` and personal browser targeting are rejected with `--virtual-desktop`. Download waiting is unsupported. Browser operations are bounded to two minutes and share the desktop lease's action budget and idle expiry.
+
+Validation: focused client tests exercise shared snapshot/click behavior, namespace isolation, stale references, target changes, cancellation and uncertain-input cleanup. Lease tests cover browser ownership, cancellation and cleanup independently of native input. The Linux smoke script exercises real Chrome, the CLI and visible pointer feedback.
+
+The desktop header icon pulses in the assistant's avatar accent color while a browser automation lease is active, including between browser commands. It shares the progress indicator's accent and neutral fallback. Reduced-motion clients show a solid accent. Setup status exposes the optional `automationActive` field; `desktop_activity_changed` events refresh it on acquisition and cancellation or release. Installation progress retains its `assistant:self:desktop` sync invalidations. The indicator reads status without starting installation, and reconnects refetch the current lease state.

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/environments/src/shell.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "./shell.js";
@@ -38,6 +39,26 @@ describe("buildShellInvocation", () => {
   });
 });
 
+describe("buildShellSpawnFlags", () => {
+  test("creates a POSIX process group and hides Windows consoles", () => {
+    expect(buildShellSpawnFlags("linux")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+    expect(buildShellSpawnFlags("darwin")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+  });
+
+  test("does not detach Windows children that use piped stdio", () => {
+    expect(buildShellSpawnFlags("win32")).toEqual({
+      detached: false,
+      windowsHide: true,
+    });
+  });
+});
+
 describe("path list handling", () => {
   test("uses the platform delimiter", () => {
     expect(pathListDelimiter("win32")).toBe(";");

package/node_modules/@vellumai/environments/src/shell.ts

@@ -5,6 +5,11 @@ export interface ShellInvocation {
   args: string[];
 }
 
+export interface ShellSpawnFlags {
+  detached: boolean;
+  windowsHide: true;
+}
+
 const WINDOWS_UTF8_PREAMBLE =
   "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}; " +
   "$OutputEncoding = [System.Text.Encoding]::UTF8; " +
@@ -43,6 +48,25 @@ export function buildShellInvocation(
   return { command: "bash", args: ["-c", "--", command] };
 }
 
+/**
+ * Spawn flags for assistant-owned shell children (sandbox bash, local
+ * host_bash fallback, sanitized CLI bash, skill runners, scheduled scripts).
+ *
+ * POSIX uses a new process group so timeout/abort can SIGKILL the tree via
+ * `-pid`. Windows process trees are torn down with `taskkill /T`, which does
+ * not need a detached process. Combining `DETACHED_PROCESS`,
+ * `CREATE_NO_WINDOW`, and piped stdio on Windows can emit `close` with exit
+ * 0 and empty pipes without running the encoded command.
+ */
+export function buildShellSpawnFlags(
+  hostPlatform: NodeJS.Platform = process.platform,
+): ShellSpawnFlags {
+  return {
+    detached: hostPlatform !== "win32",
+    windowsHide: true,
+  };
+}
+
 export function pathListDelimiter(
   hostPlatform: NodeJS.Platform = process.platform,
 ): string {

package/node_modules/@vellumai/gateway-client/src/inbound-contract.ts

@@ -83,8 +83,14 @@ export const SourceMetadataSchema = z
     clientTimezone: z.string().optional(),
     /** Channel command intent (e.g. Telegram /start). */
     commandIntent: CommandIntentSchema.optional(),
-    /** Slack-specific: whether the bot was @-mentioned. */
-    slackBotMentioned: z.boolean().optional(),
+    /**
+     * Whether the message addresses the assistant by name, an @-mention on
+     * the platforms that have one. Stated by the channel's normalizer only
+     * where it proved the answer; absent means "not established". Read to
+     * decide whether a reply is expected before any text exists, never to
+     * admit or deny: admission is the gate's job, upstream of this.
+     */
+    botMentioned: z.boolean().optional(),
     /**
      * Slack-specific: the `edited.ts` float-string from a `message_changed`
      * event. Used by the daemon to reject out-of-order edit deliveries whose

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);
+    });
+  }
+});