@vellumai/assistant 0.11.8-staging.2 → 0.11.9-dev.202609040043.7972a34

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:**
 
@@ -145,8 +145,8 @@ 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.
+- Every prompt includes a `requestCode` (6-char alphanumeric). Guardians can reply with `<requestCode> approve` or `<requestCode> reject` on any channel. The instruction saying so travels only in the card's `plainTextFallback`, which a transport appends when it sends text without buttons; composed copy and `questionText` never carry it.
+- `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`.
 
@@ -199,7 +199,7 @@ The guardian request system provides a channel-agnostic, unified domain for all
 
 4. **Deterministic API (prompt listing and decision endpoints):** Desktop clients and API consumers use `GET /v1/guardian-actions/pending` and `POST /v1/guardian-actions/decision` (HTTP). These endpoints surface guardian requests alongside legacy pending interactions and channel approval records, with deduplication to avoid double-rendering.
 
-5. **Buttons first, text fallback:** All request kinds (`tool_approval`, `pending_question`, `access_request`) are rendered as structured button cards when displayed in macOS guardian conversations. Each prompt also embeds deterministic text fallback instructions (request-code-based approve/reject directives, and for `access_request` the "open invite flow" phrase) so text-based channels and manual fallback always work. Code-only messages (just a request code without decision text) return clarification instead of auto-approving. Disambiguation with multiple pending requests stays fail-closed — no auto-resolve when the target is ambiguous.
+5. **Buttons first, text fallback:** All request kinds (`tool_approval`, `pending_question`, `access_request`) are rendered as structured button cards when displayed in macOS guardian conversations. Each card also carries deterministic text fallback instructions (request-code-based directives, and for `access_request` the "open invite flow" phrase) in its `plainTextFallback`, appended by a transport only when it sends text without buttons, so text-based channels and manual fallback always work without the instructions duplicating the buttons. Code-only messages (just a request code without decision text) return clarification instead of auto-approving. Disambiguation with multiple pending requests stays fail-closed: no auto-resolve when the target is ambiguous.
 
 **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.
 

package/Dockerfile

@@ -143,6 +143,14 @@ COPY plugins/marketplace.json /app/assistant/src/cli/lib/bundled-marketplace.jso
 RUN printf '#!/usr/bin/env sh\nexec bun run /app/assistant/src/index.ts "$@"\n' > /usr/local/bin/assistant && \
     chmod +x /usr/local/bin/assistant
 
+# The image ships no Node, so `bunx <pkg>` follows a bin's `#!/usr/bin/env node`
+# shebang into this launcher. It hands off to a real Node when one is installed
+# later and otherwise runs the bin under Bun with the auto-serve shim preloaded,
+# so a CLI whose bundle default-exports an object with `fetch` exits instead of
+# being turned into an HTTP server by `bun:main`. Installing it here also stops
+# Bun synthesizing its own `node` shim in /tmp/bun-node-<hash> at daemon launch.
+RUN ln -s /app/assistant/docker-node-launcher.sh /usr/local/bin/node
+
 # Create non-root user that also has sudo access so it can like install stuff
 RUN groupadd --system --gid 1001 assistant && \
     useradd --system --uid 1001 --gid assistant --create-home --shell /bin/bash assistant && \
@@ -186,53 +194,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,9 +240,12 @@ 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 \
+    /app/assistant/docker-node-launcher.sh \
     /usr/local/bin/vellum-block-volume-common.sh \
     /usr/local/bin/vellum-block-volume-init.sh \
     /usr/local/bin/vellum-block-volume-mount.sh \

package/docker-bun-no-autoserve.js

@@ -0,0 +1,38 @@
+// Neuters Bun's implicit auto-serve of an entrypoint module whose default
+// export carries a `fetch` method: `bun:main` calls `Bun.serve()` on that
+// export, and the process then stays alive forever waiting on the socket.
+//
+// The assistant image ships no Node, so `bunx <pkg>` follows a bin's
+// `#!/usr/bin/env node` shebang into the `node` launcher the Dockerfile
+// installs, which is Bun with this file preloaded. Without the shim, any
+// third-party CLI whose bundle ends in something like `export { cli as
+// default }` prints its answer and then hangs until the bash tool times out.
+//
+// Only the implicit call is suppressed. Bun's auto-serve frame is `bun:main`,
+// so an explicit `Bun.serve()` from user code (whose immediate caller frame is
+// that user code) passes straight through to the real implementation.
+const realServe = Bun.serve;
+
+Bun.serve = function (options) {
+  const caller = ((new Error().stack || "").split("\n")[2] || "").trim();
+  if (!caller.startsWith("at bun:main")) {
+    return realServe.call(Bun, options);
+  }
+  // Bun announces the auto-started server on the next console.debug call.
+  const realDebug = console.debug;
+  console.debug = (...args) => {
+    console.debug = realDebug;
+    if (!String(args[0]).startsWith("Started ")) {
+      realDebug(...args);
+    }
+  };
+  return {
+    stop() {},
+    reload() {},
+    port: 0,
+    hostname: "localhost",
+    protocol: "http",
+    development: false,
+    url: new URL("http://localhost:0"),
+  };
+};

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/docker-node-launcher.sh

@@ -0,0 +1,37 @@
+#!/bin/sh
+# Installed as /usr/local/bin/node. The image ships no Node, so `bunx <pkg>`
+# follows a bin's `#!/usr/bin/env node` shebang here.
+#
+# A real Node interpreter always wins. One can appear after the image is built:
+# `apt-get install nodejs` writes /usr/bin/node, and on Kata-family runtimes the
+# persistent apt chroot puts it under $VELLUM_APT_DATA_ROOT/usr/bin, which the
+# sandbox PATH carries. Delegating keeps Node CLIs on Node semantics.
+#
+# With no real Node on PATH the bin runs under Bun with the auto-serve shim
+# preloaded, so a CLI whose default export carries a `fetch` method exits
+# instead of being turned into an HTTP server by `bun:main`.
+#
+# Bun's own synthesized shim dirs (<temp>/bun-node-<hash>/node, symlinks to
+# bun) are skipped: that `node` is Bun without the preload, which is the hang
+# this launcher exists to prevent.
+
+launcher=/usr/local/bin/node
+shim=/app/assistant/docker-bun-no-autoserve.js
+
+IFS=:
+for dir in $PATH; do
+  [ -n "$dir" ] || continue
+  candidate="$dir/node"
+  case "$candidate" in
+    "$launcher" | */bun-node-*/node) continue ;;
+  esac
+  [ -f "$candidate" ] && [ -x "$candidate" ] || continue
+  if [ -L "$candidate" ] && [ "$(readlink -f "$candidate")" = "$launcher" ]; then
+    continue
+  fi
+  unset IFS
+  exec "$candidate" "$@"
+done
+unset IFS
+
+exec /usr/local/bin/bun --preload="$shim" "$@"

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,13 @@ 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.
+The "CODE <reply>" instruction lives in exactly one place: the
+`plainTextFallback` the broadcaster builds beside the card's actions. Composed
+copy never carries it (the decision engine strips a model's echo of it on
+every channel), and a transport appends it only when it sends text without
+buttons: a rich delivery that failed, or a request with no actions to draw,
+which is how an option-less voice question stays answerable. Every surface
+with buttons, and the bell, banner, and push, show the ask alone.
 
 ## Worked example: `ask_question` on a channel
 
@@ -186,8 +193,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/runbook-trusted-contacts.md

@@ -146,9 +146,13 @@ sqlite3 "file:$GW_DB?mode=ro" \
 
 ## 3b. Contact writes
 
-All write operations on contacts are gateway-owned. Use the gateway CLI, not
+Contact writes are gateway-owned, and they reach it two ways. An operator ACL
+write (a risk ceiling) goes through the gateway CLI directly, not through
 `assistant contacts`. From the host, run the same command via
-`vellum exec --service gateway --`.
+`vellum exec --service gateway --`. A write that changes the contact graph
+itself (the record, or a channel binding) goes through `assistant contacts`,
+which opens a form in the guardian's app and writes nothing until they submit
+it; the gateway still performs the write.
 
 ```bash
 gateway contacts set-risk-threshold <contactId> --threshold high
@@ -156,6 +160,13 @@ gateway contacts set-risk-threshold <contactId> --threshold high
 
 `inherit` clears the risk ceiling so the contact follows room and trust-class settings. Stored vocabulary is `none`, `low`, `medium`, or `high`.
 
+Binding an address to a contact goes through the guardian instead of the operator. The command below opens a form in the guardian's app naming that contact, and the gateway writes the channel only when they submit it. An address already held by a different contact is refused, naming that contact.
+
+```bash
+assistant contacts channels add <contactId> --channel <type> --address <addr>
+assistant contacts channels add <contactId> --channel email --address alice@example.com
+```
+
 ## 4. Force-Revoke a Trusted Contact
 
 ### Via CLI (preferred)

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/colors.ts

@@ -17,3 +17,11 @@ export const AVATAR_COLORS: ColorDefinition[] = [
   { id: "teal", hex: "#0E9B8B" },
   { id: "yellow", hex: "#E9C91A" },
 ];
+
+/** The palette hex for a colour id, or null for an id the palette does not have. */
+export function accentHexForColorId(colorId: string | null | undefined): string | null {
+  if (!colorId) {
+    return null;
+  }
+  return AVATAR_COLORS.find((c) => c.id === colorId)?.hex ?? null;
+}

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";