@vellumai/assistant 0.11.8 → 0.11.9-staging.2

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:**
 
@@ -146,7 +146,7 @@ All guardian approval decisions — regardless of how they arrive — route thro
 **Text fallback path (always available):**
 
 - Every prompt includes a `requestCode` (6-char alphanumeric). Guardians can reply with `<requestCode> approve` or `<requestCode> reject` on any channel.
-- `access_request` prompts additionally embed explicit text directives in `questionText`: the request-code approve/reject directive and the `"open invite flow"` phrase for starting the Trusted Contacts invite flow.
+- `access_request` prompts carry the request-code verify/trust/reject/block directive in the card's `plainTextFallback`, appended by a transport only when it sends text without buttons; the `"open invite flow"` phrase for starting the Trusted Contacts invite flow stays in the text on every surface because nothing offers a button for it.
 - `pending_question` prompts (voice-originated) support `<requestCode> <your answer>` for free-text answers.
 - The `routeGuardianReply` router processes text replies through a priority-ordered pipeline: callback parsing -> request code parsing -> NL classification. All paths converge on `applyGuardianDecision`.
 

package/Dockerfile

@@ -186,53 +186,11 @@ RUN printf '%s\n' \
     >> /home/assistant/.bashrc && \
     chown assistant:assistant /home/assistant/.bashrc
 
-RUN printf '%s\n' \
-    '#!/usr/bin/env sh' \
-    'set -eu' \
-    '. /app/assistant/docker-kata-runtime-family.sh' \
-    'if ! vellum_is_kata_family_runtime; then' \
-    '  exec /usr/bin/apt-get "$@"' \
-    'fi' \
-    'export DEBIAN_FRONTEND=noninteractive' \
-    'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
-    '/app/assistant/docker-init-apt-root.sh' \
-    'if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/apt-get" ] && [ -f "${DATA_ROOT}/.rootfs-initialized" ] && ! grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then' \
-    '  exec chroot "${DATA_ROOT}" /usr/bin/apt-get "$@"' \
-    'fi' \
-    'exec /usr/bin/apt-get "$@"' \
-    > /usr/local/bin/apt-get && \
-    chmod +x /usr/local/bin/apt-get && \
-    printf '%s\n' \
-    '#!/usr/bin/env sh' \
-    'set -eu' \
-    '. /app/assistant/docker-kata-runtime-family.sh' \
-    'if ! vellum_is_kata_family_runtime; then' \
-    '  exec /usr/bin/apt "$@"' \
-    'fi' \
-    'export DEBIAN_FRONTEND=noninteractive' \
-    'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
-    '/app/assistant/docker-init-apt-root.sh' \
-    'if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/apt" ] && [ -f "${DATA_ROOT}/.rootfs-initialized" ] && ! grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then' \
-    '  exec chroot "${DATA_ROOT}" /usr/bin/apt "$@"' \
-    'fi' \
-    'exec /usr/bin/apt "$@"' \
-    > /usr/local/bin/apt && \
-    chmod +x /usr/local/bin/apt && \
-    printf '%s\n' \
-    '#!/usr/bin/env sh' \
-    'set -eu' \
-    '. /app/assistant/docker-kata-runtime-family.sh' \
-    'if ! vellum_is_kata_family_runtime; then' \
-    '  exec /usr/bin/dpkg "$@"' \
-    'fi' \
-    'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
-    '/app/assistant/docker-init-apt-root.sh' \
-    'if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/dpkg" ] && [ -f "${DATA_ROOT}/.rootfs-initialized" ] && ! grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then' \
-    '  exec chroot "${DATA_ROOT}" /usr/bin/dpkg "$@"' \
-    'fi' \
-    'exec /usr/bin/dpkg "$@"' \
-    > /usr/local/bin/dpkg && \
-    chmod +x /usr/local/bin/dpkg
+# apt/apt-get/dpkg must persist like pip: on Kata-family runtimes the wrapper
+# routes package operations into the persistent apt chroot.
+RUN ln -s /app/assistant/docker-kata-apt-wrapper.sh /usr/local/bin/apt-get && \
+    ln -s /app/assistant/docker-kata-apt-wrapper.sh /usr/local/bin/apt && \
+    ln -s /app/assistant/docker-kata-apt-wrapper.sh /usr/local/bin/dpkg
 
 # pip must persist like apt: on Kata-family runtimes the wrapper routes root
 # installs into the persistent apt chroot.
@@ -274,8 +232,10 @@ RUN chmod +x \
     /app/assistant/docker-entrypoint.sh \
     /app/assistant/docker-init-apt-root.sh \
     /app/assistant/docker-kata-apt-env.sh \
+    /app/assistant/docker-kata-apt-shims.sh \
+    /app/assistant/docker-kata-apt-wrapper.sh \
+    /app/assistant/docker-kata-chroot-exec.sh \
     /app/assistant/docker-kata-pip.sh \
-    /app/assistant/docker-kata-pip-chroot.sh \
     /app/assistant/docker-kata-runtime-family.sh \
     /usr/local/bin/vellum-block-volume-common.sh \
     /usr/local/bin/vellum-block-volume-init.sh \

package/docker-entrypoint.sh

@@ -11,7 +11,11 @@ KATA_APT_INIT_PID=""
 if vellum_is_kata_family_runtime && [ -x /app/assistant/docker-init-apt-root.sh ]; then
   export VELLUM_APT_DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"
   # Warm the chroot used by Kata-family apt wrappers without blocking assistant readiness.
-  /app/assistant/docker-init-apt-root.sh &
+  (
+    /app/assistant/docker-init-apt-root.sh
+    # Refresh persisted wrapper-script shims before commands use the overlay.
+    /app/assistant/docker-kata-apt-shims.sh || true
+  ) &
   KATA_APT_INIT_PID="$!"
 fi
 

package/docker-kata-apt-env.sh

@@ -36,6 +36,9 @@ _vellum_kata_prepend_library_path() {
   esac
 }
 
+# Shims for chroot wrapper scripts with hardcoded absolute paths must shadow
+# the broken originals in the chroot bin dirs below (docker-kata-apt-shims.sh).
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/.host-shims"
 _vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/bin"
 _vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/usr/local/sbin"
 _vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/usr/local/bin"

package/docker-kata-apt-shims.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env sh
+# Regenerates host-side shims for chroot-installed commands whose bin entry
+# is a pure trampoline script exec'ing a hardcoded absolute path (Debian
+# 7zip's /usr/bin/7z execs /usr/lib/7zip/7z, for example). Those targets only
+# exist inside the chroot, so running the wrapper through the host PATH
+# overlay fails; each shim execs the chroot-prefixed target instead.
+# docker-kata-apt-env.sh and buildSanitizedEnv put the shim dir on PATH ahead
+# of the chroot bin dirs so shims shadow the broken wrappers.
+set -eu
+
+DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"
+SHIM_DIR="${DATA_ROOT}/.host-shims"
+MARKER="# vellum-apt-shim:"
+# dpkg-managed dirs that can hold trampolines (Debian policy keeps packages
+# out of /usr/local; /bin and /sbin are usrmerge symlinks into these).
+SCAN_DIRS="usr/bin usr/sbin usr/games"
+# Every overlay bin dir in PATH priority order (usrmerge collapses bin/sbin
+# into their usr counterparts): precedence must also see the /usr/local dirs
+# that chroot pip installs populate, so a dpkg trampoline never shims over a
+# higher-priority local command.
+PRIORITY_DIRS="usr/bin usr/local/sbin usr/local/bin usr/sbin usr/games"
+
+[ -d "${DATA_ROOT}/usr/bin" ] || exit 0
+mkdir -p "${SHIM_DIR}"
+
+# Scanning the bin dirs forks a few processes per file; skip it when the
+# overlay state is unchanged (read-only invocations like `apt list` or
+# `dpkg -l`). The stamp covers command names, links, effective modes, and small
+# executable contents so reinstalls and pip changes invalidate stale shims.
+STAMP_FILE="${SHIM_DIR}/.overlay-stamp"
+STAMP="$(
+  {
+    md5sum "${DATA_ROOT}/var/lib/dpkg/status" 2>/dev/null
+    for d in ${PRIORITY_DIRS}; do
+      printf '%s\0' "${d}"
+      find "${DATA_ROOT}/${d}" -mindepth 1 -maxdepth 1 -printf '%P %y %m %l\0' 2>/dev/null | sort -z
+      find -L "${DATA_ROOT}/${d}" -mindepth 1 -maxdepth 1 -printf '%P %y %m\0' 2>/dev/null | sort -z
+    done
+    for d in ${SCAN_DIRS}; do
+      find -L "${DATA_ROOT}/${d}" -mindepth 1 -maxdepth 1 -type f -size -513c -perm /111 -print0 2>/dev/null |
+        sort -z |
+        xargs -0 -r md5sum -z
+    done
+  } | md5sum | cut -d' ' -f1
+)"
+if [ "${STAMP}" = "$(cat "${STAMP_FILE}" 2>/dev/null || true)" ]; then
+  exit 0
+fi
+
+# Prints the target of a pure trampoline: a tiny script whose body is nothing
+# but the shebang, comments, blank lines, and a single `exec /abs/path "$@"`
+# line. Wrappers that do anything else (export env vars, cd, pass extra
+# flags) print nothing: a direct-exec shim would bypass that setup.
+wrapper_target() {
+  [ -f "$1" ] && [ -x "$1" ] || return 0
+  [ "$(wc -c <"$1")" -le 512 ] || return 0
+  case "$(head -c 2 "$1" 2>/dev/null)" in
+    '#!') ;;
+    *) return 0 ;;
+  esac
+  body="$(sed -e '1d' -e '/^[[:space:]]*#/d' -e '/^[[:space:]]*$/d' "$1")"
+  [ -n "${body}" ] || return 0
+  [ "$(printf '%s' "${body}" | wc -l)" -eq 0 ] || return 0
+  printf '%s\n' "${body}" | sed -n 's/^[[:space:]]*exec[[:space:]][[:space:]]*\(\/[^"[:space:]][^"[:space:]]*\)[[:space:]][[:space:]]*"\$@"[[:space:]]*$/\1/p'
+}
+
+# Highest-priority overlay dir that holds an entry for this shim name.
+shim_source() {
+  for d in ${PRIORITY_DIRS}; do
+    candidate="${DATA_ROOT}/${d}/$1"
+    if [ -f "${candidate}" ] && [ -x "${candidate}" ]; then
+      printf '%s\n' "${candidate}"
+      return 0
+    fi
+  done
+}
+
+generation_failed=0
+for d in ${SCAN_DIRS}; do
+  for bin in "${DATA_ROOT}/${d}/"*; do
+    # Shims outrank every chroot bin dir on PATH, so only the
+    # highest-priority entry for a name may produce one: a trampoline in a
+    # lower dir must not shadow a real command above it.
+    [ "$(shim_source "${bin##*/}")" = "${bin}" ] || continue
+    target="$(wrapper_target "${bin}")"
+    [ -n "${target}" ] || continue
+    # Only shim when the hardcoded path is broken on the host but real in
+    # the chroot.
+    if [ -e "${target}" ] || [ ! -x "${DATA_ROOT}${target}" ]; then
+      continue
+    fi
+    shim="${SHIM_DIR}/${bin##*/}"
+    if ! tmp="$(mktemp "${SHIM_DIR}/.shim.XXXXXX")"; then
+      generation_failed=1
+      continue
+    fi
+    if printf '%s\n' \
+      '#!/bin/sh' \
+      "${MARKER} ${target}" \
+      "exec \"${DATA_ROOT}${target}\" \"\$@\"" \
+      >"${tmp}" &&
+      chmod 0755 "${tmp}" &&
+      mv -f "${tmp}" "${shim}"; then
+      :
+    else
+      rm -f "${tmp}"
+      generation_failed=1
+    fi
+  done
+done
+
+if [ "${generation_failed}" -ne 0 ]; then
+  exit 1
+fi
+
+# Drop shims that remain stale after desired replacements are installed.
+for shim in "${SHIM_DIR}"/*; do
+  [ -f "${shim}" ] || continue
+  grep -qs "^${MARKER}" "${shim}" || continue
+  target="$(sed -n "s|^${MARKER} ||p" "${shim}" | sed -n '1p')"
+  src="$(shim_source "$(basename "${shim}")")"
+  if [ -z "${target}" ] || [ -z "${src}" ] || [ ! -x "${DATA_ROOT}${target}" ] || [ "$(wrapper_target "${src}")" != "${target}" ]; then
+    rm -f "${shim}"
+  fi
+done
+
+printf '%s\n' "${STAMP}" >"${STAMP_FILE}"

package/docker-kata-apt-wrapper.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env sh
+# apt/apt-get/dpkg wrapper (symlinked from /usr/local/bin). On Kata-family
+# runtimes, package operations are routed into the persistent apt chroot so
+# they survive machine saves; the image rootfs is discarded on every save.
+# The chroot runs through docker-kata-chroot-exec.sh in a private mount
+# namespace with /dev, /dev/pts and /proc available, so apt can allocate a
+# pty for term.log and maintainer scripts see a normal system.
+set -eu
+
+TOOL_NAME="$(basename "$0")"
+case "${TOOL_NAME}" in
+  apt | apt-get | dpkg) ;;
+  *) TOOL_NAME="apt-get" ;;
+esac
+
+. /app/assistant/docker-kata-runtime-family.sh
+
+if ! vellum_is_kata_family_runtime; then
+  exec "/usr/bin/${TOOL_NAME}" "$@"
+fi
+
+if [ "${TOOL_NAME}" != "dpkg" ]; then
+  export DEBIAN_FRONTEND=noninteractive
+fi
+DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"
+
+/app/assistant/docker-init-apt-root.sh
+if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/${TOOL_NAME}" ] && [ -f "${DATA_ROOT}/.rootfs-initialized" ] && ! grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then
+  rc=0
+  # Platform kata pods are privileged inside their per-assistant VM, so
+  # unshare -m works there; if this environment can't create a mount
+  # namespace, fall back to a bare chroot: installs still persist, but with
+  # no /dev/pts or /proc apt logs a pty warning and the caller's cwd is not
+  # restored.
+  if unshare -m true 2>/dev/null; then
+    unshare -m /app/assistant/docker-kata-chroot-exec.sh "${DATA_ROOT}" "${PWD}" "/usr/bin/${TOOL_NAME}" "$@" || rc=$?
+  else
+    chroot "${DATA_ROOT}" "/usr/bin/${TOOL_NAME}" "$@" || rc=$?
+  fi
+  # Packages can install wrapper scripts that hardcode absolute paths which
+  # only resolve inside the chroot; refresh host-side shims for those.
+  /app/assistant/docker-kata-apt-shims.sh || true
+  exit "${rc}"
+fi
+exec "/usr/bin/${TOOL_NAME}" "$@"

package/docker-kata-chroot-exec.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env sh
+# Runs a command inside the persistent apt chroot. Must be invoked under
+# `unshare -m` (see docker-kata-pip.sh and docker-kata-apt-wrapper.sh): the
+# bind mounts below live in a private mount namespace so they disappear with
+# the process and are never visible to other processes; a lingering /data
+# bind inside the chroot would create a path cycle (/data/system/data/system/...)
+# for anything walking /data.
+set -eu
+
+DATA_ROOT="$1"
+CALLER_CWD="$2"
+shift 2
+
+for dir in /workspace /data /tmp /var/tmp; do
+  [ -d "${dir}" ] || continue
+  mkdir -p "${DATA_ROOT}${dir}"
+  mount --bind "${dir}" "${DATA_ROOT}${dir}" 2>/dev/null || true
+done
+
+# /proc and /dev make the chroot behave like a normal system: apt needs a pty
+# (posix_openpt via /dev/ptmx) to write /var/log/apt/term.log, and package
+# maintainer scripts routinely read /proc. The recursive /dev bind carries the
+# container's /dev/pts along; the devpts mount is a fallback for environments
+# where it did not produce one.
+mkdir -p "${DATA_ROOT}/proc" "${DATA_ROOT}/dev"
+mount --bind /proc "${DATA_ROOT}/proc" 2>/dev/null || true
+mount --rbind /dev "${DATA_ROOT}/dev" 2>/dev/null || true
+if [ ! -e "${DATA_ROOT}/dev/pts/ptmx" ]; then
+  mkdir -p "${DATA_ROOT}/dev/pts" 2>/dev/null || true
+  mount -t devpts -o gid=5,mode=620,ptmxmode=666 devpts "${DATA_ROOT}/dev/pts" 2>/dev/null || true
+fi
+
+# chroot(1) always chdirs to /; restore the caller's cwd when it exists inside
+# the chroot so relative paths keep working.
+exec chroot "${DATA_ROOT}" /bin/sh -c 'cd "$1" 2>/dev/null || cd /; shift; exec "$@"' sh "${CALLER_CWD}" "$@"

package/docker-kata-pip.sh

@@ -38,10 +38,16 @@ if [ "$(id -u)" = "0" ]; then
       # unshare -m works there; if this environment can't create a mount
       # namespace, fall back to a bare chroot — index installs still persist,
       # only caller-path installs lose visibility.
+      rc=0
       if unshare -m true 2>/dev/null; then
-        exec unshare -m /app/assistant/docker-kata-pip-chroot.sh "${DATA_ROOT}" "${PWD}" "/usr/bin/${PIP_NAME}" "$@"
+        unshare -m /app/assistant/docker-kata-chroot-exec.sh "${DATA_ROOT}" "${PWD}" "/usr/bin/${PIP_NAME}" "$@" || rc=$?
+      else
+        chroot "${DATA_ROOT}" /bin/sh -c 'cd "$1" 2>/dev/null || cd /; shift; exec "$@"' sh "${PWD}" "/usr/bin/${PIP_NAME}" "$@" || rc=$?
       fi
-      exec chroot "${DATA_ROOT}" /bin/sh -c 'cd "$1" 2>/dev/null || cd /; shift; exec "$@"' sh "${PWD}" "/usr/bin/${PIP_NAME}" "$@"
+      # pip can add usr/local commands that outrank existing shims on the
+      # PATH overlay; refresh so a stale shim never shadows them.
+      /app/assistant/docker-kata-apt-shims.sh || true
+      exit "${rc}"
     fi
   fi
   echo "Warning: persistent pip root unavailable; falling back to the image pip (installs will not survive a save)" >&2

package/docs/architecture/memory.md

@@ -170,10 +170,14 @@ Ingested pages carry provenance frontmatter with distinct consumers:
 
 ### Read paths
 
-- **v3 (live)**: per-turn lane selection over concept pages — dense/sparse
-  retrieval (`substrate/sim.ts` over the concept-page collection),
-  learned edges, entity/hot/fresh/core sets — rendered as the `<memory>`
-  card by `v3/injector.ts`. The static `<info>` block
+- **v3 (live)**: per-turn lane selection over concept pages (dense/sparse
+  retrieval via `substrate/sim.ts` over the concept-page collection,
+  learned edges, entity/hot/fresh/core sets) rendered as the `<memory>`
+  card by `v3/injector.ts`. Frozen cards stay on historical user messages
+  so the provider prefix stays cacheable. Each turn's `<memory_spotlight>`
+  stays on the user message that was sent with it. A new spotlight is
+  added only on the new tail, so older messages are not rewritten. The
+  static `<info>` block
   (`substrate/static-context.ts`: essentials/threads/recent/buffer) also
   injects whenever the substrate is active.
 - **v2 (transitional)**: activation/router engine in `v2/`

package/docs/guardian-request-flow.md

@@ -21,17 +21,17 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
   notification pipeline                          (notifications/emit-signal.ts →
   decision engine → destination resolver →        decision-engine.ts → destination-resolver.ts →
   broadcaster builds the card context ONCE        broadcaster.ts: resolveApprovalContext /
-  (generic actions[] + plainTextFallback)         resolveQuestionOptionsContext)
+  (generic actions[] + plainTextFallback)         resolveQuestionContext)
         │
         ▼ per-channel rendering ONLY
   channel adapters                               (notifications/adapters/{telegram,slack,macos,platform},
   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,14 +45,14 @@ 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
 
@@ -131,6 +131,10 @@ routing after a restart even though the card is absent from the model's history.
 Two instruction modes exist per request kind (`notifications/guardian-question-mode.ts`):
 **approval** ("CODE approve" / approve–reject buttons) and **answer**
 ("CODE <your answer>" / option buttons). `pending_question` is answer-mode.
+Whether a channel's copy carries the "CODE <reply>" instruction at all is one
+rule, `guardianCopyCarriesReplyMechanics`: text chats do, while the vellum
+bell and banner, the platform push, and Slack approval cards act through the
+card and have it stripped.
 
 ## Worked example: `ask_question` on a channel
 
@@ -186,8 +190,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

package/docs/trusted-contact-access.md

@@ -24,13 +24,7 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 2. **The message is denied at the ingress ACL.** The gateway resolves the actor against its ACL DB and stamps a trust verdict onto the inbound metadata; the daemon's ACL stage (`runtime/routes/inbound-stages/acl-enforcement.ts`) consumes that verdict, finds no active member, replies _"Hmm looks like you don't have access to talk to me. I'll let <guardian> know you tried talking to me and get back to you."_ and returns `{ denied: true, reason: 'not_a_member' }`.
 3. **Notification pipeline alerts the guardian.** The denial triggers `notifyGuardianOfAccessRequest()` (`runtime/access-request-helper.ts`), which creates an access request in the gateway (`guardian_requests`, `kind: 'access_request'`, `toolName: 'ingress_access_request'`, via the `channels/gateway-guardian-requests.ts` client) and calls `emitNotificationSignal()` with `sourceEventName: 'ingress.access_request'`. The notification routes through the decision engine to the guardian's surfaces (vellum app, Telegram, Slack, etc.). The guardian sees who is requesting access, including a request code for approve/reject and an `open invite flow` option to start the Trusted Contacts invite flow.
 
-   **Access-request copy contract:** Every guardian-facing access-request notification must contain:
-   1. **Requester context** — best-available identity (display name, username, external ID, source channel), sanitized to prevent control-character injection.
-   2. **Request-code decision directive** — e.g., `Reply "A1B2C3 approve" to grant access or "A1B2C3 reject" to deny.`
-   3. **Invite directive** — the exact phrase `Reply "open invite flow" to start Trusted Contacts invite flow.`
-   4. **Revoked-member warning** (when applicable) — `Note: this user was previously revoked.`
-
-   Model-generated phrasing is permitted for the surrounding copy, but a post-generation enforcement step in the decision engine validates that all required directive elements are present. If any are missing, the full deterministic contract text is appended. This ensures the guardian can always parse and act on the notification regardless of LLM output quality.
+   **Access-request copy contract:** Every guardian-facing access-request notification carries the requester context (`buildAccessRequestContextText`): best-available identity (display name, username, external ID, source channel) sanitized to prevent control-character injection, the message preview, and a revoked-member warning when applicable (`Note: this user was previously revoked.`). The context also carries the invite directive (`Reply "open invite flow" to start Trusted Contacts invite flow.`), because no surface offers a button for the invite flow and typing the phrase is the only way to start it. The typed-reply mechanics are separate (`buildAccessRequestReplyMechanics`): the request-code directive (`Reply "A1B2C3 verify" ... "A1B2C3 trust" ... "A1B2C3 reject" ... "A1B2C3 block"`, without `verify` when no handshake is offered). It rides only in the card's `plainTextFallback`; a transport appends it when it sends text without buttons, and the decision engine strips any copy of it the model wrote into the composed text, so surfaces with buttons show the context alone.
 
    **Guardian identity resolution** is anchored on the assistant's vellum principal (`resolveAnchoredGuardian`), so access requests cannot bind to stale or cross-assistant contacts:
    1. A source-channel guardian binding (from the gateway contact list) that matches the vellum anchor principal.

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

@@ -1,7 +1,13 @@
 import { AVATAR_COLORS } from "./colors.js";
 import type { CharacterComponents } from "./types.js";
 
-const SCLERA = "#F2F2F2";
+/**
+ * The white of an eye. Exported because a consumer that reduces an eye pair to
+ * a silhouette (an Android themed-icon mask, say) has to tell the sclera paths
+ * from the pupils, and matching on this is the only way to do that from the
+ * path list alone.
+ */
+export const SCLERA = "#F2F2F2";
 const PUPIL = "#1A1A1A";
 
 /**

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

@@ -22,4 +22,4 @@
  *
  * Leaf package: no dependencies, no runtime imports.
  */
-export { getCharacterComponents } from "./catalog.js";
+export { getCharacterComponents, SCLERA } from "./catalog.js";

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

@@ -22,7 +22,10 @@
     "./redacted-credential": "./src/redacted-credential.ts",
     "./secret-detection": "./src/secret-detection.ts",
     "./stripe-currency": "./src/stripe-currency.ts",
-    "./error": "./src/error.ts"
+    "./error": "./src/error.ts",
+    "./reactions": "./src/reactions.ts",
+    "./guardian-requests": "./src/guardian-requests.ts",
+    "./platform-credential": "./src/platform-credential.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -0,0 +1,18 @@
+/**
+ * Canonical vocabulary for a guardian request's lifecycle status, shared by
+ * the gateway that owns the request rows, the daemon that decides and
+ * projects them, and the web that renders the projection.
+ */
+import { z } from "zod";
+
+export const GUARDIAN_REQUEST_STATUS_VALUES = [
+  "pending",
+  "approved",
+  "denied",
+  "expired",
+  "cancelled",
+] as const;
+export const GuardianRequestStatusSchema = z.enum(
+  GUARDIAN_REQUEST_STATUS_VALUES,
+);
+export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;

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

@@ -28,6 +28,7 @@ export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
+export * from "./platform-credential.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/platform-credential.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire contract for asking an assistant whether its stored platform-managed
+ * credential still authenticates.
+ *
+ * The daemon route is the authoritative serving side:
+ *   - `POST /v1/platform/verify-credential`
+ *       (`assistant/src/runtime/routes/platform-routes.ts`)
+ *
+ * The daemon's platform client produces the verdict, the route reports it,
+ * and the `vellum` CLI reads it before deciding whether a stored key can be
+ * re-injected (`cli/src/lib/assistant-api-key-resolution.ts`), so all three
+ * share one definition and cannot silently drift. The web app reads the same
+ * shape through its generated daemon client.
+ */
+import { z } from "zod";
+
+/**
+ * What the platform said about the stored credential, right now.
+ *
+ *   - `valid`: the platform accepted it.
+ *   - `rejected`: the platform refused it (unauthorized or forbidden); the
+ *     credential needs replacing.
+ *   - `unknown`: the check itself could not run (no credential stored, the
+ *     platform unreachable, a server error). Not evidence either way.
+ */
+export const PlatformCredentialVerificationStatusSchema = z.enum([
+  "valid",
+  "rejected",
+  "unknown",
+]);
+export type PlatformCredentialVerificationStatus = z.infer<
+  typeof PlatformCredentialVerificationStatusSchema
+>;
+
+/** `POST /v1/platform/verify-credential` response body. */
+export const PlatformVerifyCredentialResponseSchema = z.object({
+  status: PlatformCredentialVerificationStatusSchema,
+});
+export type PlatformVerifyCredentialResponse = z.infer<
+  typeof PlatformVerifyCredentialResponseSchema
+>;

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

@@ -0,0 +1,60 @@
+/**
+ * Canonical vocabulary for a reaction's emoji, shared by every service that
+ * handles one: the gateway that normalizes it, the daemon that stores and
+ * projects it, and the web that renders it.
+ *
+ * The kind is said by the channel rather than inferred from how the emoji
+ * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
+ * that separates the namespace from the name.
+ *
+ * `shortcode` is a name in a channel's own namespace whose kind the channel
+ * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
+ * for a workspace upload with nothing to tell them apart, and only the
+ * workspace token can resolve the second. It is a distinct kind from
+ * `unicode`, not a stand-in for an unknown one.
+ */
+import { z } from "zod";
+
+export const REACTION_EMOJI_KINDS = ["unicode", "shortcode", "custom"] as const;
+export type ReactionEmojiKind = (typeof REACTION_EMOJI_KINDS)[number];
+
+/**
+ * The typed emoji fields every schema that carries a reaction spreads in,
+ * so the wire contract, the stored envelopes, and the response projection
+ * describe one shape. Optional throughout: a persisted row or a replayed
+ * payload may carry only the spelling.
+ */
+export const ReactionEmojiFieldsSchema = z.object({
+  /** Which namespace the emoji was drawn from. */
+  emojiKind: z.enum(REACTION_EMOJI_KINDS).optional(),
+  /**
+   * The emoji's name in that namespace: the character itself for `unicode`,
+   * the bare name for `shortcode` and `custom`. Never a mention form.
+   */
+  emojiName: z.string().optional(),
+  /** The channel's id for a `custom` emoji, absent for every other kind. */
+  emojiId: z.string().optional(),
+  /** Whether a `custom` emoji animates. Absent for every other kind. */
+  emojiAnimated: z.boolean().optional(),
+});
+export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
+
+/**
+ * The typed emoji fields a source actually carries, with undefined ones
+ * omitted: an absent key and a present-but-undefined one serialize alike, but the
+ * stored envelope and the response should carry only what was declared. Every writer of a reaction shape (the wire
+ * payload, both stored envelopes, the response projection) copies the
+ * fields through this rather than restating the four-way pick.
+ */
+export function pickReactionEmojiFields(
+  source: ReactionEmojiFields,
+): ReactionEmojiFields {
+  return {
+    ...(source.emojiKind !== undefined ? { emojiKind: source.emojiKind } : {}),
+    ...(source.emojiName !== undefined ? { emojiName: source.emojiName } : {}),
+    ...(source.emojiId !== undefined ? { emojiId: source.emojiId } : {}),
+    ...(source.emojiAnimated !== undefined
+      ? { emojiAnimated: source.emojiAnimated }
+      : {}),
+  };
+}

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

@@ -22,7 +22,10 @@
     "./redacted-credential": "./src/redacted-credential.ts",
     "./secret-detection": "./src/secret-detection.ts",
     "./stripe-currency": "./src/stripe-currency.ts",
-    "./error": "./src/error.ts"
+    "./error": "./src/error.ts",
+    "./reactions": "./src/reactions.ts",
+    "./guardian-requests": "./src/guardian-requests.ts",
+    "./platform-credential": "./src/platform-credential.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",