@vellumai/assistant 0.11.7 → 0.11.8-dev.202609012313.7a1acce

package/ARCHITECTURE.md

@@ -120,7 +120,7 @@ Scoped approval grants allow a guardian's approval decision on one channel (e.g.
 
 ### Guardian Decision Primitive
 
-All guardian approval decisions — regardless of how they arrive — route through a single primitive in `src/approvals/guardian-decision-primitive.ts`, which centralizes decision logic for callback button handlers, the conversational approval engine, and channel reactions/text.
+All guardian approval decisions, regardless of how they arrive, route through a single primitive in `src/approvals/guardian-decision-primitive.ts`, which centralizes decision logic for callback button handlers, the conversational approval engine, and channel text replies.
 
 **Core API:**
 
@@ -203,7 +203,7 @@ The guardian request system provides a channel-agnostic, unified domain for all
 
 **Resolver registry:** Kind-specific resolvers (`src/approvals/guardian-request-resolvers.ts`) handle side effects after CAS resolution. Built-in resolvers: `tool_approval` (channel/desktop approval path), `pending_question` (voice call question path), and `access_request` (trusted-contact verification session creation). New request kinds register resolvers without touching the core primitive.
 
-**Expiry:** the daemon's 60-second sweep (`src/runtime/routes/guardian-expiry-sweep.ts`) asks the gateway to CAS-expire pending requests past `expiresAt` (`guardian_requests_sweep_expired`) and fans out card withdrawal + requester notices from the returned rows; interaction-bound kinds (`tool_approval`, `pending_question`) are expired at daemon boot via `guardian_requests_expire_interaction_bound` since they die with the in-memory pending-interactions map. `src/calls/guardian-action-sweep.ts` sends the guardian-facing expiry notices for voice questions.
+**Expiry:** the daemon's 60-second sweep (`src/runtime/routes/guardian-expiry-sweep.ts`) lists a bounded batch of past-deadline pending requests (`guardian_requests_list_expired_pending`, read-only), fans out card withdrawal + requester notices per row, and only then confirms each with the per-request `guardian_requests_expire` CAS, so a lost response or crash leaves the row listed for the next round; interaction-bound kinds (`tool_approval`, `pending_question`) are expired at daemon boot via `guardian_requests_expire_interaction_bound` since they die with the in-memory pending-interactions map, and the boot call never touches persistent kinds. `src/calls/guardian-action-sweep.ts` sends the guardian-facing expiry notices for voice questions.
 
 **Key source files:**
 
@@ -267,19 +267,19 @@ Guardian requests (tool approvals, access requests, voice ASK_GUARDIAN questions
 
 **Voice consultation timeout:** When a voice call's ASK_GUARDIAN consultation times out before the guardian responds, the call controller expires the request via the gateway (`guardian_requests_expire` — deliveries expire with it), sends expiry notices to every surface the approval card reached (vellum conversations get an assistant message; external channels get a direct channel reply), and injects a `[GUARDIAN_TIMEOUT]` instruction so the model apologizes to the caller and offers a message or callback on the next voice turn.
 
-**Background expiry sweep:** Independent of any active call, a 60-second sweep asks the gateway to CAS-expire pending guardian requests past their `expiresAt` (`guardian_requests_sweep_expired` — a concurrent decision that wins the race is never overwritten), then fans out the side effects per expired row: withdrawing the approval cards on every surface, notifying the requester, and releasing any in-memory pending interaction.
+**Background expiry sweep:** Independent of any active call, a 60-second sweep lists pending guardian requests past their `expiresAt` (`guardian_requests_list_expired_pending`), runs the side effects per row (withdrawing the approval cards on every surface, notifying the requester, releasing any in-memory pending interaction), and then confirms each with the per-request `guardian_requests_expire` CAS; a decision arriving past the deadline loses to expiry atomically, since the decide CAS guards on `expires_at`.
 
 **Generated messaging requirement:** All user-facing copy in the guardian timeout/expiry path is generated through the `guardian-action-message-composer.ts` composition system, which uses a 2-tier priority chain: (1) daemon-injected LLM generator for natural, varied text; (2) deterministic fallback templates for reliability. No hardcoded user-facing strings exist in the flow files outside of internal log messages and LLM-instruction prompts. A guard test (`guardian-action-no-hardcoded-copy.test.ts`) enforces this invariant.
 
 **Key source files:**
 
-| File                                              | Purpose                                                                                                                                            |
-| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/channels/gateway-guardian-requests.ts`       | Gateway-backed guardian-request client: typed wrappers over the `guardian_requests_*` IPC routes that own request/delivery state and expiry        |
-| `src/runtime/routes/guardian-expiry-sweep.ts`     | Periodic 60s sweep: gateway CAS-expiry (`guardian_requests_sweep_expired`) plus card-withdrawal, requester-notice, and pending-interaction fan-out |
-| `src/calls/call-controller.ts`                    | Voice timeout handling: expires the request, sends expiry notices, injects `[GUARDIAN_TIMEOUT]` instruction for the generated voice response       |
-| `src/calls/guardian-action-sweep.ts`              | Expiry notice delivery to guardian destinations (vellum conversation message or direct channel reply)                                              |
-| `src/runtime/guardian-action-message-composer.ts` | 2-tier text generation: daemon-injected LLM generator with deterministic fallback templates                                                        |
+| File                                              | Purpose                                                                                                                                                   |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/channels/gateway-guardian-requests.ts`       | Gateway-backed guardian-request client: typed wrappers over the `guardian_requests_*` IPC routes that own request/delivery state and expiry               |
+| `src/runtime/routes/guardian-expiry-sweep.ts`     | Periodic 60s sweep: bounded expired-pending list, per-row card-withdrawal, requester-notice, and pending-interaction fan-out, then per-request expire CAS |
+| `src/calls/call-controller.ts`                    | Voice timeout handling: expires the request, sends expiry notices, injects `[GUARDIAN_TIMEOUT]` instruction for the generated voice response              |
+| `src/calls/guardian-action-sweep.ts`              | Expiry notice delivery to guardian destinations (vellum conversation message or direct channel reply)                                                     |
+| `src/runtime/guardian-action-message-composer.ts` | 2-tier text generation: daemon-injected LLM generator with deterministic fallback templates                                                               |
 
 ### WhatsApp Channel (Meta Cloud API)
 
@@ -2066,7 +2066,7 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | ---------------------------------------- | ------------------------------------------------------ | ----------------------------------- | ---------------------------------- | ------------------------------------------------------- |
 | API key                                  | CES / encrypted file store                             | Encrypted binary                    | CES API / `secure-keys.ts`         | Permanent                                               |
 | Credential secrets                       | CES / encrypted file store                             | Encrypted binary                    | `secure-keys.ts` wrapper           | Permanent (until deleted via tool)                      |
-| Credential metadata                      | `$VELLUM_WORKSPACE_DIR/data/credentials/metadata.json` | JSON                                | Atomic file write                  | Permanent (until deleted via tool)                      |
+| Credential records                       | CES `<cesDataRoot>/metadata.json`                      | JSON                                | CES RPC/HTTP + atomic file write   | Permanent (until deleted via tool)                      |
 | Integration OAuth tokens                 | CES / encrypted file store (via `secure-keys.ts`)      | Encrypted binary                    | `TokenManager` auto-refresh        | Until disconnected or revoked                           |
 | User preferences                         | UserDefaults                                           | plist                               | Foundation                         | Permanent                                               |
 | Session logs                             | `~/Library/.../logs/session-*.json`                    | JSON per session                    | Swift Codable                      | Unbounded                                               |

package/Dockerfile

@@ -117,6 +117,7 @@ RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 COPY --from=builder /app /app
 
 # Copy source after installing dependencies for better layer caching.
+COPY packages/avatar-catalog /app/packages/avatar-catalog
 COPY packages/avatar-manifest /app/packages/avatar-manifest
 COPY packages/ces-client /app/packages/ces-client
 COPY packages/service-contracts /app/packages/service-contracts

package/docs/architecture/security.md

@@ -229,7 +229,7 @@ User messages are scanned at ingress (`secret-ingress.ts`) against known credent
 | Component           | Location                                               | What it stores                                                                                                                                                   |
 | ------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Secret values       | CES credential store or encrypted file store           | Encrypted credential values keyed as `credential/{service}/{field}`. Stored via CES RPC (primary), CES HTTP (containerized), or encrypted file store (fallback). |
-| Credential metadata | `$VELLUM_WORKSPACE_DIR/data/credentials/metadata.json` | Service, field, label, policy (allowedTools, allowedDomains), timestamps                                                                                         |
+| Credential records  | CES `<cesDataRoot>/metadata.json`                      | Service, field, alias, policy (`allowedTools`, `allowedDomains`, `injectionTemplates`), timestamps. Served over CES RPC/HTTP.                                    |
 | Config              | `$VELLUM_WORKSPACE_DIR/config.*`                       | `secretDetection` settings: enabled, blockIngress, allowOneTimeSend, blockTokenShapedMessages (default `true` — whole-message token-shape heuristic)             |
 
 ### Key Files

package/docs/error-handling.md

@@ -52,7 +52,7 @@ interface ToolExecutionResult {
 }
 ```
 
-Existing examples: `EditEngineResult` in `edit-engine.ts`, `PathResult` in `path-policy.ts`, `ToolExecutionResult` in `tools/types.ts`, `MemoryRecallResult` in `memory/retriever.ts`.
+Existing examples: `EditEngineResult` in `edit-engine.ts`, `PathResult` in `path-policy.ts`, `ToolExecutionResult` in `tools/types.ts`.
 
 ## 3. Never return null/undefined to indicate failure
 
@@ -66,7 +66,6 @@ Returning `undefined` is acceptable only for **lookup functions** where "not fou
 | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | Agent loop (`agent/loop.ts`)                          | Throws + catch-and-emit                                                         | Unrecoverable provider errors break the loop; expected errors (abort, tool-use limits) are caught and emitted as events        |
 | Tool executor (`tools/executor.ts`)                   | Result object (`ToolExecutionResult`)                                           | Tool failures are expected operational outcomes — permission denied, unknown tool, sandbox violations. Never throws to callers |
-| Memory retriever (`memory/retriever.ts`)              | Result object (`MemoryRecallResult`) with degraded/reason fields                | Graceful degradation — embedding failures, search failures degrade quality without crashing                                    |
 | Filesystem tools (`path-policy.ts`, `edit-engine.ts`) | Discriminated union (`{ ok, reason }`)                                          | Validation outcomes that the caller must handle (out of bounds, not found, ambiguous)                                          |
 | Subagent manager (`subagent/manager.ts`)              | Throws for precondition violations, string literal unions for expected outcomes | Depth limit exceeded is a bug; `sendMessage` returns `'not_found' \| 'terminal' \| 'queue_full'` as expected states            |
 | Interactive UI (`cli/commands/ui.ts`)                 | Result object (`InteractiveUiResult`) with `status` + exit codes                | User cancel and timeout are expected operational outcomes, not errors. IPC failures are exceptional.                           |

package/docs/guardian-request-flow.md

@@ -28,10 +28,10 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
   telegram: inline keyboard; slack: blocks;       vellum: conversation card via approval-card-builder)
   card deliveries recorded per channel            (guardian-delivery-recorder.ts → guardian_request_deliveries)
         │
-        ▼ user responds: button tap / emoji reaction / "CODE <reply>" / bare text
+        ▼ user responds: button tap / "CODE <reply>" / bare text
   guardian reply router                          (runtime/guardian-reply-router.ts, invoked from
-  reactions → callbacks → request codes →         routes/inbound-stages/guardian-reply-intercept.ts,
-  bare answer → explicit approve/reject → NL      BEFORE background dispatch — replies to parked
+  callbacks → request codes → bare answer →       routes/inbound-stages/guardian-reply-intercept.ts,
+  explicit approve/reject → NL                    BEFORE background dispatch: replies to parked
         │                                         prompts resolve inline, never deferred)
         ▼ one decision primitive
   applyGuardianDecision                          (approvals/guardian-decision-primitive.ts:
@@ -45,24 +45,63 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
 
 ## Who owns what
 
-| Concern                                 | Owner                                                    | Never                               |
-| --------------------------------------- | -------------------------------------------------------- | ----------------------------------- |
-| The "what": card text, actions, options | broadcaster context build (once per broadcast)           | built per-adapter                   |
-| The "how": channel-native rendering     | `notifications/adapters/<channel>`                       | domain logic, payload parsing       |
-| Request state                           | gateway `guardian_requests` (+ deliveries)               | daemon-side request tables          |
-| Decisions                               | `applyGuardianDecision` (CAS, atomic ACL outcome)        | inline decision logic at call sites |
-| Kind-specific follow-through            | resolver registry (`kind` → resolver)                    | switch statements in the router     |
-| Reply understanding                     | guardian reply router (codes, buttons, reactions, modes) | per-feature inbound intercepts      |
+| Concern                                 | Owner                                             | Never                               |
+| --------------------------------------- | ------------------------------------------------- | ----------------------------------- |
+| The "what": card text, actions, options | broadcaster context build (once per broadcast)    | built per-adapter                   |
+| The "how": channel-native rendering     | `notifications/adapters/<channel>`                | domain logic, payload parsing       |
+| Request state                           | gateway `guardian_requests` (+ deliveries)        | daemon-side request tables          |
+| Decisions                               | `applyGuardianDecision` (CAS, atomic ACL outcome) | inline decision logic at call sites |
+| Kind-specific follow-through            | resolver registry (`kind` → resolver)             | switch statements in the router     |
+| Reply understanding                     | guardian reply router (codes, buttons, modes)     | per-feature inbound intercepts      |
+
+## The canonical home-feed projection
+
+Every pending request is also exactly one home-feed item, the bell's
+"Needs attention" row. `notifications/guardian-feed-projection.ts` owns
+it end to end:
+
+- The pipeline's feed side effect writes it keyed
+  `guardian:<requestId>`, so the feed's replace-in-place merge keeps one
+  item per request. Its typed `guardianRequest` field
+  (`FeedItemGuardianRequestSchema` in `api/responses/home.ts`) is a read
+  projection of the gateway row: intent, status, requester, tool, and
+  source reference. It is never a delivery row of its own; clients
+  derive every affordance from `status`.
+- `withdrawGuardianRequestCards` rewrites it into a terminal receipt as
+  one of the surfaces it settles, and its failure gates `complete` the
+  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 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.
+- The guardian expiry sweep runs `reconcileGuardianFeedProjections()`
+  each round: pending requests missing an item are backfilled from the
+  request row (no conversation is generated), and an item still
+  actionable for a terminal request is receipted with a loud log line.
+
+Routing policy for channel-delivered cards: a guardian card sent to a
+channel chat (Slack, Telegram, Discord, WhatsApp) is a delivery
+projection, not conversation content. Channel deliveries are not
+paired with any conversation (`conversation-pairing.ts` skips every
+non-vellum guardian delivery), and the Slack DM cold backfill skips
+messages whose ts matches a recorded guardian delivery for the chat
+(`guardian_requests_list_deliveries_by_chat`), so a card never enters
+a Vellum transcript. The in-app homes of a request are the feed item
+and the source conversation's pinned vellum card.
 
 ## Cards are not conversation history
 
-`pairDeliveryWithConversation` persists one message row per delivery so the
-card renders and deep-links. For a guardian card that row is addressed to a
+`pairDeliveryWithConversation` persists one message row for the vellum
+delivery so the card renders and deep-links. That row is addressed to a
 conversation the request is _about_, not one the assistant is speaking in:
 `buildVellumCardAffinity` pins the vellum card to the originating
-conversation, and a channel card lands in whatever conversation the guardian's
-chat binds to. Either way the row is written straight to the DB by the
-notification pipeline, so the live turn's in-memory history never sees it.
+conversation. Channel guardian deliveries pair no conversation (see the
+routing policy above), so the vellum row is the only card row written; it
+goes straight to the DB by the notification pipeline, so the live turn's
+in-memory history never sees it. Rows that channel deliveries paired
+before the projection-only policy still exist and are covered by the same
+filter below.
 
 That row must never be replayed to the model. The conversation it lands in is
 typically parked mid-approval, with its last assistant message carrying the
@@ -147,8 +186,8 @@ chat the turn is running in. On Slack that chat can be a shared room, and the
 card carries the tool, a command preview and live buttons.
 `resolveGuardianPromptDelivery` addresses it to the guardian's bound DM
 instead, by chat id rather than user id because that address is written to the
-delivery row and read back to match reactions, scope plain-text replies and
-edit the decided card. It returns the address and its route together, since
+delivery row and read back to scope plain-text replies and edit the decided
+card. It returns the address and its route together, since
 the turn's own callback carries a `threadTs` naming a thread that does not
 exist in the DM. When no private address resolves it returns nothing and the
 prompt is left to the in-app confirmation, because the room is the disclosure
@@ -156,3 +195,10 @@ this exists to prevent. Telegram group chats carry the same exposure and are
 not covered: only Slack has a chat whose privacy can be read off its id. They remain load-bearing for that flow, and
 the reply router runs first for everything the pipeline owns. Converge new
 work on the pipeline; do not extend the legacy interception.
+
+Any flow that resolves a confirmation in-memory first (this rail, the in-app
+`/v1/confirm` route, the auto-deny sweeps) brings the gateway row to the
+matching terminal status through `approvals/guardian-request-status-sync.ts`,
+which also runs the same cross-surface card withdrawal the decision primitive
+runs whenever its CAS is the one that landed: no projection of a resolved
+request may stay actionable, whichever rail resolved it.

package/docs/trusted-contact-access.md

@@ -68,12 +68,12 @@ requested -> pending_guardian -> verification_pending -> active | denied | expir
 
 Identity binding ensures the verification code can only be consumed by the intended recipient on the intended channel. The binding fields are set on the gateway `channel_verification_sessions` record when the session is created; the check itself is `checkIdentityMatch` (`gateway/src/verification/identity-match.ts`).
 
-| Channel   | Identity fields                                                                  | Binding behavior                                                                                                                                                                                                                                                                                                         |
-| --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Telegram  | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID | Both are taken from the original denied message's metadata. The `identityBindingStatus` is `'bound'`. Verification requires the actor's user ID or chat ID to match (user ID required when both are set on a shared chat).                                                                                               |
-| Voice     | `expectedPhoneE164` = phone number in E.164 format                               | Phone-based identity binding. Verification requires the caller's number to match the expected phone.                                                                                                                                                                                                                     |
+| Channel   | Identity fields                                                                                                                                                                                                                                                              | Binding behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Telegram  | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID                                                                                                                                                                                             | Both are taken from the original denied message's metadata. The `identityBindingStatus` is `'bound'`. Verification requires the actor's user ID or chat ID to match (user ID required when both are set on a shared chat).                                                                                                                                                                                                                                                                                                       |
+| Voice     | `expectedPhoneE164` = phone number in E.164 format                                                                                                                                                                                                                           | Phone-based identity binding. Verification requires the caller's number to match the expected phone.                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | Discord   | `expectedExternalUserId` = Discord user snowflake. `expectedChatId` is unset on the guardian-initiated and trusted-contact paths, and is the originating guild channel on the access-request approval path (`mint_outbound_session`), which sets it for every channel alike. | The code is delivered to a DM and answered there, but the DM channel does not exist until it is opened, so those two paths have no chat id to record at mint time. Where the approval path does set one, it is a room rather than an identity and never becomes a sufficient credential on its own: `checkIdentityMatch` requires the `expectedExternalUserId` match whenever both fields are set. That path also writes the room into `destinationAddress`, where it describes nothing the code is ever sent to (see LUM-3110). |
-| Bootstrap | none yet (`identityBindingStatus: 'pending_bootstrap'`)                          | Unbound deep-link sessions use a 32-byte hex token instead of a numeric code; the identity is bound when the token is redeemed (`verification_sessions_bind_identity`).                                                                                                                                                  |
+| Bootstrap | none yet (`identityBindingStatus: 'pending_bootstrap'`)                                                                                                                                                                                                                      | Unbound deep-link sessions use a 32-byte hex token instead of a numeric code; the identity is bound when the token is redeemed (`verification_sessions_bind_identity`).                                                                                                                                                                                                                                                                                                                                                          |
 
 **Anti-oracle invariant:** When identity verification fails, the error message is identical to the "invalid or expired code" message. This prevents attackers from distinguishing between a wrong code and a wrong identity, which would leak information about which identities have pending sessions.
 
@@ -129,10 +129,10 @@ Separately, the admitted-mode introduction **nudge** (for a contact who cleared
 
 ### Stage: `expired`
 
-| Store                                            | Table                           | Record                                                                                                    |
-| ------------------------------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| gateway `guardian-request-store.ts` (gateway DB) | `guardian_requests`             | Updated to `status: 'expired'` via `guardian_requests_sweep_expired` (the daemon's sweep runs every 60s). |
-| `session-store.ts` (gateway DB)                  | `channel_verification_sessions` | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingSessionByHash()`.           |
+| Store                                            | Table                           | Record                                                                                                                                           |
+| ------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| gateway `guardian-request-store.ts` (gateway DB) | `guardian_requests`             | Updated to `status: 'expired'` via the per-request `guardian_requests_expire` CAS, after the daemon's 60s sweep has run that row's side effects. |
+| `session-store.ts` (gateway DB)                  | `channel_verification_sessions` | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingSessionByHash()`.                                                  |
 
 ### Invites (alternative path)
 
@@ -216,10 +216,11 @@ sequenceDiagram
 
     else Guardian never responds
         Note over A: runGuardianExpirySweep()<br/>runs every 60 seconds
-        A->>GW: guardian_requests_sweep_expired (IPC)
-        GW->>GW: Approval TTL elapsed → status: 'expired' (CAS)
+        A->>GW: guardian_requests_list_expired_pending (IPC)
         A->>A: Withdraw approval cards on all surfaces
         A-->>U: "Your access request has expired."
+        A->>GW: guardian_requests_expire (IPC)
+        GW->>GW: status: 'expired' (CAS, the fan-out's receipt)
 
     else Code expires (requester never enters it)
         Note over GW: Verification session TTL: 10 min
@@ -232,7 +233,7 @@ sequenceDiagram
 
 ### Guardian never responds
 
-- The `runGuardianExpirySweep()` timer (`runtime/routes/guardian-expiry-sweep.ts`) runs every 60 seconds; the gateway CAS-transitions pending requests past their `expiresAt` to `status: 'expired'` (`guardian_requests_sweep_expired`) and returns the expired rows.
+- The `runGuardianExpirySweep()` timer (`runtime/routes/guardian-expiry-sweep.ts`) runs every 60 seconds; the gateway returns a bounded, read-only batch of pending requests past their `expiresAt` (`guardian_requests_list_expired_pending`), and the daemon confirms each row with the per-request `guardian_requests_expire` CAS only after running its side effects, so the fan-out is recoverable from state.
 - The daemon then withdraws the now-stale approval cards on every surface and notifies the requester that the request expired.
 
 ### Verification code expires

package/knip.json

@@ -15,6 +15,7 @@
   "ignore": ["src/config/preloaded-apps/**"],
   "ignoreDependencies": [
     "@microsoft/api-extractor",
+    "@vellumai/avatar-catalog",
     "@vellumai/avatar-manifest",
     "@vellumai/ces-client",
     "@vellumai/credential-storage",

package/node_modules/@vellumai/avatar-catalog/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@vellumai/avatar-catalog",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./colors": "./src/colors.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/{src/avatar/character-components.ts → node_modules/@vellumai/avatar-catalog/src/catalog.ts}

@@ -1,43 +1,18 @@
-interface BodyShapeDefinition {
-  id: string;
-  viewBox: { width: number; height: number };
-  faceCenter: { x: number; y: number };
-  svgPath: string;
-}
-
-interface EyePathDefinition {
-  svgPath: string;
-  color: string; // hex e.g. "#F2F2F2"
-}
-
-interface EyeStyleDefinition {
-  id: string;
-  sourceViewBox: { width: number; height: number };
-  eyeCenter: { x: number; y: number };
-  paths: EyePathDefinition[];
-}
-
-interface ColorDefinition {
-  id: string;
-  hex: string; // e.g. "#4C9B50"
-}
-
-interface FaceCenterOverride {
-  bodyShape: string;
-  eyeStyle: string;
-  faceCenter: { x: number; y: number };
-}
-
-interface CharacterComponents {
-  bodyShapes: BodyShapeDefinition[];
-  eyeStyles: EyeStyleDefinition[];
-  colors: ColorDefinition[];
-  faceCenterOverrides: FaceCenterOverride[];
-}
+import { AVATAR_COLORS } from "./colors.js";
+import type { CharacterComponents } from "./types.js";
 
 const SCLERA = "#F2F2F2";
 const PUPIL = "#1A1A1A";
 
+/**
+ * Every body shape, eye style, and face-centre override an avatar can be
+ * composed from, plus the palette re-exposed on `colors`.
+ *
+ * This is the single definition. The daemon serves it over
+ * `/avatar/character-components`; clients that must compose an avatar before
+ * the daemon answers (a hatching screen, a chooser card) import it directly
+ * so no copy has to be kept in step with this one.
+ */
 export function getCharacterComponents(): CharacterComponents {
   return {
     bodyShapes: [
@@ -369,14 +344,7 @@ export function getCharacterComponents(): CharacterComponents {
       },
     ],
 
-    colors: [
-      { id: "green", hex: "#4C9B50" },
-      { id: "orange", hex: "#E9642F" },
-      { id: "pink", hex: "#DB4B77" },
-      { id: "purple", hex: "#A665C9" },
-      { id: "teal", hex: "#0E9B8B" },
-      { id: "yellow", hex: "#E9C91A" },
-    ],
+    colors: AVATAR_COLORS,
 
     faceCenterOverrides: [
       // Ghost body — shift non-native eyes from y=167 -> y=200

package/node_modules/@vellumai/avatar-catalog/src/colors.ts

@@ -0,0 +1,19 @@
+import type { ColorDefinition } from "./types.js";
+
+/**
+ * The avatar colour palette, in the order the picker offers it.
+ *
+ * Its own module because the palette is the one part of the catalog that
+ * boot-path code needs: a sidebar pin resolves a stored colour id on first
+ * render, and the accent CSS variable falls back to the first entry before
+ * the daemon's own catalog arrives. Importing the shapes to reach six hex
+ * values would put ~47 kB of SVG path data on that path.
+ */
+export const AVATAR_COLORS: ColorDefinition[] = [
+  { id: "green", hex: "#4C9B50" },
+  { id: "orange", hex: "#E9642F" },
+  { id: "pink", hex: "#DB4B77" },
+  { id: "purple", hex: "#A665C9" },
+  { id: "teal", hex: "#0E9B8B" },
+  { id: "yellow", hex: "#E9C91A" },
+];

package/node_modules/@vellumai/avatar-catalog/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @vellumai/avatar-catalog: the single definition of the components an
+ * assistant's character avatar is composed from.
+ *
+ * The daemon serves this catalog over `/avatar/character-components` and
+ * renders PNGs from it; clients bundle it because an avatar has to compose
+ * before the daemon can answer (the hatching screen, the assistant chooser,
+ * a transcript's subagent chips). Bundling is why this is a package rather
+ * than a daemon module every client copies.
+ *
+ * The palette is deliberately not re-exported here. It lives behind
+ * `@vellumai/avatar-catalog/colors`, and importing it from that subpath is
+ * what keeps boot-path code (a sidebar pin resolving a stored colour id, the
+ * accent variable's fallback) off the ~47 kB of SVG path data the shapes
+ * carry. Re-exporting it would make the expensive import the convenient one.
+ *
+ * The shapes' types stay internal for the same reason they were private to
+ * the daemon module this package replaces: the wire contract for this data is
+ * the route's `responseBody` schema, which clients consume through their
+ * generated OpenAPI types. A hand-written type exported from here would be a
+ * second name for that shape, and the closer one to reach for.
+ *
+ * Leaf package: no dependencies, no runtime imports.
+ */
+export { getCharacterComponents } from "./catalog.js";

package/node_modules/@vellumai/avatar-catalog/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Shapes for the catalog literal in this package.
+ *
+ * Declared here rather than derived from the generated OpenAPI types because
+ * this is a leaf package with no dependencies, and the clients that consume
+ * those generated types depend on it rather than the other way round. The
+ * canonical wire shape is the `avatar/character-components` route's
+ * `responseBody` schema; these are not exported so no consumer picks them up
+ * as a second name for it.
+ */
+
+export interface BodyShapeDefinition {
+  id: string;
+  viewBox: { width: number; height: number };
+  faceCenter: { x: number; y: number };
+  svgPath: string;
+}
+
+export interface EyePathDefinition {
+  svgPath: string;
+  color: string; // hex e.g. "#F2F2F2"
+}
+
+export interface EyeStyleDefinition {
+  id: string;
+  sourceViewBox: { width: number; height: number };
+  eyeCenter: { x: number; y: number };
+  paths: EyePathDefinition[];
+}
+
+export interface ColorDefinition {
+  id: string;
+  hex: string; // e.g. "#4C9B50"
+}
+
+export interface FaceCenterOverride {
+  bodyShape: string;
+  eyeStyle: string;
+  faceCenter: { x: number; y: number };
+}
+
+export interface CharacterComponents {
+  bodyShapes: BodyShapeDefinition[];
+  eyeStyles: EyeStyleDefinition[];
+  colors: ColorDefinition[];
+  faceCenterOverrides: FaceCenterOverride[];
+}

package/node_modules/@vellumai/avatar-catalog/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -11,6 +11,7 @@
     "./client-metadata": "./src/client-metadata.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
     "./ingress": "./src/ingress.ts",
+    "./no-response": "./src/no-response.ts",
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
     "./twilio-ingress": "./src/twilio-ingress.ts",
     "./trust-rules": "./src/trust-rules.ts",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -66,6 +66,13 @@ export function isChannelId(value: unknown): value is ChannelId {
  * That irregularity is why this is stated rather than derived from the key,
  * and it is stated here because this file already owns what a channel is.
  *
+ * Both senses can hold a user token, which is the sharpest edge. The `slack`
+ * integration's persisted token *is* the installer's user token, held on its
+ * OAuth connection. `slack_channel` holds an optional `user_token` in the
+ * credential store, beside its bot and app tokens. Same words, different
+ * homes, and only the second is a credential-store key: a pasted token is
+ * always the channel's, because the integration's never leaves the exchange.
+ *
  * Deliberately only the key. What fields each credential requires is declared
  * once already, per service, in the gateway's credential specs; restating it
  * here would be a second copy of a different fact.

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/index.ts

@@ -27,6 +27,7 @@ export * from "./handles.js";
 export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
+export * from "./no-response.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";
 export * from "./url-normalization.js";

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/no-response.ts

@@ -0,0 +1,84 @@
+/**
+ * The `<no_response/>` sentinel: the cross-service convention for a turn
+ * that deliberately produces no user-visible reply.
+ *
+ * The model emits it, the daemon stamps and strips it, channel delivery
+ * suppresses it, and clients hold live-streamed prefixes of it back from
+ * display. One definition here keeps every consumer's parsing identical;
+ * a hand-rolled copy in any one of them is how the case-sensitivity of a
+ * regex drifts.
+ */
+
+/** Matches a message whose entire content is the sentinel. */
+const NO_RESPONSE_ONLY_RE = /^\s*<no_response\s*\/?>\s*$/i;
+
+/**
+ * Whether `text` is nothing but the sentinel: the whole reply is a
+ * deliberate non-response, as opposed to real content with an inline
+ * sentinel mixed in.
+ */
+export function isNoResponseOnlyText(text: string): boolean {
+  return NO_RESPONSE_ONLY_RE.test(text);
+}
+
+/** Matches every sentinel occurrence for stripping it out of mixed content. */
+export const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/gi;
+
+/**
+ * Detection variant without the `g` flag: a `g`-flagged regex is stateful
+ * under `.test()` (it resumes from `lastIndex`), so reusing
+ * {@link NO_RESPONSE_INLINE_RE} for detection would alternate between
+ * matches and misses across calls.
+ */
+const NO_RESPONSE_MARKER_RE = new RegExp(NO_RESPONSE_INLINE_RE.source, "i");
+
+/** Whether `text` contains the sentinel anywhere. */
+export function containsNoResponseMarker(text: string): boolean {
+  return NO_RESPONSE_MARKER_RE.test(text);
+}
+
+/** Removes every sentinel occurrence, trimming the leftover whitespace. */
+export function stripNoResponseMarkers(text: string): string {
+  return text.replace(NO_RESPONSE_INLINE_RE, "").trim();
+}
+
+const NO_RESPONSE_SENTINEL_FORMS = [
+  "<no_response/>",
+  "<no_response />",
+  "<no_response>",
+] as const;
+
+/**
+ * Whether `text` could still grow into the sentinel, i.e. it is a leading
+ * substring of one of its forms. Holding on these keeps a slowly-streamed
+ * `<no_response/>` from surfacing as visible partial content.
+ */
+export function isPotentialNoResponsePrefix(text: string): boolean {
+  const lower = text.trim().toLowerCase();
+  if (lower.length === 0) {
+    return false;
+  }
+  return NO_RESPONSE_SENTINEL_FORMS.some((sentinel) =>
+    sentinel.startsWith(lower),
+  );
+}
+
+/**
+ * Whether `text` carries user-visible content worth acting on now. Returns
+ * `false` for empty text, the standalone sentinel, and any prefix that could
+ * still complete into one; returns `true` once real content remains after
+ * stripping inline sentinels.
+ */
+export function hasDeliverableAssistantText(text: string): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return false;
+  }
+  if (NO_RESPONSE_ONLY_RE.test(trimmed)) {
+    return false;
+  }
+  if (isPotentialNoResponsePrefix(trimmed)) {
+    return false;
+  }
+  return stripNoResponseMarkers(trimmed).length > 0;
+}