@sjawhar/claude-envoy 0.0.0 → 1.1.0

package/scripts/smoke-channel.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# smoke-channel.sh — real Claude Code channel delivery smoke.
+# See README.md for prerequisites, configuration, and why this is not CI.
+set -euo pipefail
+
+readonly envoy_url="${ENVOY_URL:-http://127.0.0.1:9020}"
+readonly nats_url="${ENVOY_NATS_URL:?set ENVOY_NATS_URL to the live Envoy NATS listener}"
+readonly claude_bin="${CLAUDE_BIN:-claude}"
+readonly channel_entry="${CLAUDE_CHANNEL_ENTRY:?set CLAUDE_CHANNEL_ENTRY, e.g. plugin:claude-envoy@<marketplace>}"
+# `--channels` only works for an entry managed settings allowlist (`allowedChannelPlugins`);
+# here that is the `legion-plugins` marketplace. Everything else (a dev marketplace, a
+# bare `server:` entry) needs the development bypass. Always overridable.
+if [[ -n "${CLAUDE_CHANNEL_FLAG:-}" ]]; then
+  readonly channel_flag="$CLAUDE_CHANNEL_FLAG"
+elif [[ "$channel_entry" == *"@legion-plugins" ]]; then
+  readonly channel_flag="--channels"
+else
+  readonly channel_flag="--dangerously-load-development-channels"
+fi
+readonly plugin_dir="${CLAUDE_PLUGIN_DIR:-}"
+readonly mcp_config="${CLAUDE_MCP_CONFIG:-}"
+readonly startup_timeout=60
+readonly session_timeout=45
+readonly delivery_timeout=90
+readonly teardown_timeout=15
+
+fail() {
+  printf 'FAIL: %s\n' "$*" >&2
+  [[ -n "${tmux_session:-}" ]] && tmux capture-pane -pt "$tmux_session" >&2 || true
+  if [[ -n "${claude_output:-}" && -f "$claude_output" ]]; then
+    printf -- '--- claude pane output (%s) ---\n' "$claude_output" >&2
+    cat "$claude_output" >&2 || true
+  fi
+  exit 1
+}
+
+command -v "$claude_bin" >/dev/null 2>&1 || fail "$claude_bin is not on PATH"
+command -v tmux >/dev/null 2>&1 || fail "tmux is required"
+command -v curl >/dev/null 2>&1 || fail "curl is required"
+command -v jq >/dev/null 2>&1 || fail "jq is required"
+
+readonly nonce="$(od -An -N4 -tx1 /dev/urandom | tr -d ' \n')"
+readonly target_session="claude-channel-smoke-${nonce}"
+readonly message="channel-smoke-payload-${nonce}"
+workdir="$(mktemp -d "/tmp/${target_session}.XXXXXX")"
+readonly workdir
+# The smoke runs its own tmux server on a socket in its scratch directory, so its cleanup can end
+# only the session it started: `tmux kill-session` on the shared default server could end anyone's.
+readonly tmux_socket="${workdir}/tmux.sock"
+tmux() { command tmux -S "$tmux_socket" "$@"; }
+readonly received_file="${workdir}/received.txt"
+readonly claude_output="${workdir}/claude-output.txt"
+readonly delivery_instruction="Envoy channel smoke: use Bash to write exactly ${message}, with no trailing newline, to ${received_file}; then reply CHANNEL_SMOKE_DONE."
+tmux_session=""
+
+cleanup() {
+  [[ -n "$tmux_session" ]] && tmux kill-session -t "$tmux_session" 2>/dev/null || true
+  rm -rf "$workdir"
+}
+trap cleanup EXIT INT TERM
+
+# Claude Code shows up to three dialogs before its prompt, in an order that
+# depends on what this machine has already consented to: folder trust, the
+# development-channel warning, and first-use MCP server consent. Poll the pane
+# and answer whichever is showing until the prompt appears.
+answer_startup_dialogs() {
+  local deadline=$((SECONDS + startup_timeout)) pane
+  while (( SECONDS < deadline )); do
+    pane="$(tmux capture-pane -pt "$tmux_session" 2>/dev/null || true)"
+    if [[ "$pane" == *"Yes, I trust this folder"* ]]; then
+      tmux send-keys -t "$tmux_session" Down Enter
+    elif [[ "$pane" == *"I am using this for local development"* ]]; then
+      tmux send-keys -t "$tmux_session" Enter
+    elif [[ "$pane" == *"New MCP server found"* ]]; then
+      tmux send-keys -t "$tmux_session" Enter
+    elif [[ "$pane" == *"shift+tab to cycle"* || "$pane" == *"? for shortcuts"* ]]; then
+      # The permission-mode status line is drawn only once the prompt is live.
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+wait_for_session() {
+  local deadline=$((SECONDS + session_timeout)) response
+  while (( SECONDS < deadline )); do
+    response="$(curl --connect-timeout 2 --max-time 5 -fsS "${envoy_url}/v1/sessions?dir=${workdir}" 2>/dev/null || true)"
+    if jq -e --arg id "$target_session" '.[] | select(.session_id == $id)' <<<"$response" >/dev/null 2>&1; then
+      session_row="$(jq -c --arg id "$target_session" '.[] | select(.session_id == $id) | {session_id, dir, capabilities}' <<<"$response")"
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+wait_for_delivery() {
+  local deadline=$((SECONDS + delivery_timeout))
+  while (( SECONDS < deadline )); do
+    if [[ -f "$received_file" ]] && [[ "$(cat "$received_file")" == "$message" ]]; then
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+# wait_for_teardown returns 0 once a read of the session list leaves the session out, 1 when the
+# last list it read still held the session at the deadline, and 2 when it never read the list. A
+# read that fails (no answer, a non-200 such as the listener's refilling 503, a body that is not a
+# list) says nothing about the session, so it is retried, never taken for its absence;
+# teardown_read_error keeps the last such failure for the message.
+teardown_read_error=""
+wait_for_teardown() {
+  local deadline=$((SECONDS + teardown_timeout)) response listed=0 rc
+  local curl_error="${workdir}/teardown-curl.err"
+  while (( SECONDS < deadline )); do
+    if response="$(curl --connect-timeout 2 --max-time 5 -fsS "${envoy_url}/v1/sessions?dir=${workdir}" 2>"$curl_error")"; then
+      rc=0
+      jq -e --arg id "$target_session" 'any(.[]; .session_id == $id)' <<<"$response" >/dev/null 2>&1 || rc=$?
+      case "$rc" in
+        0) listed=1 ;;
+        1) return 0 ;;
+        *) teardown_read_error="GET /v1/sessions answered a body that is not a session list: ${response:0:200}" ;;
+      esac
+    else
+      teardown_read_error="$(tr '\n' ' ' <"$curl_error")"
+    fi
+    sleep 1
+  done
+  (( listed )) && return 1
+  return 2
+}
+
+# The channel server gets a known direct Envoy route through the QA override.
+# The smoke starts an interactive Claude Code session: channel notifications are
+# meant to wake an already-open session, while -p has no interactive consent or
+# plan-approval surfaces.
+tmux_session="${target_session}"
+session_row=""
+claude_command=("$claude_bin")
+[[ -z "$plugin_dir" ]] || claude_command+=(--plugin-dir "$plugin_dir")
+[[ -z "$mcp_config" ]] || claude_command+=(--mcp-config "$mcp_config")
+tmux new-session -d -s "$tmux_session" -x 220 -y 50 -c "$workdir" \
+  env ENVOY_NATS_URL="$nats_url" ENVOY_URL="$envoy_url" ENVOY_SESSION_ID="$target_session" \
+  CLAUDE_PROJECT_DIR="$workdir" CLAUDE_PLUGIN_DATA="${workdir}/plugin-data" \
+  "${claude_command[@]}" "$channel_flag" "$channel_entry"
+tmux set-option -t "$tmux_session" remain-on-exit on
+# Everything Claude prints, dialogs included, lands in a file the failure path dumps.
+tmux pipe-pane -t "$tmux_session" -o "cat >> '${claude_output}'"
+answer_startup_dialogs || fail "Claude did not reach its prompt within ${startup_timeout}s"
+
+printf 'starting interactive Claude channel smoke %s with %s %s; watch it with: tmux -S %s attach -t %s\n' \
+  "$target_session" "$channel_flag" "$channel_entry" "$tmux_socket" "$tmux_session"
+wait_for_session || fail "channel session did not register with Envoy within ${session_timeout}s"
+printf 'registered Envoy channel session %s\n' "$session_row"
+
+response_file="$(mktemp)"
+trap 'rm -f "$response_file"; cleanup' EXIT INT TERM
+status="$(curl --connect-timeout 2 --max-time 5 -sS -o "$response_file" -w '%{http_code}' \
+  -X POST -H 'Content-Type: application/json' "${envoy_url}/v1/messages/send" \
+  --data "$(jq -nc --arg target "$target_session" --arg body "$delivery_instruction" '{source:"human", target_session:$target, message:$body, idempotency_key:("channel-smoke-" + $target)}')" 2>/dev/null || true)"
+[[ "$status" == "200" ]] || fail "Envoy direct send returned ${status}: $(cat "$response_file")"
+printf 'sent direct Envoy event; waiting up to %ss for Claude to consume the channel notification\n' "$delivery_timeout"
+wait_for_delivery || fail "Claude did not write the exact channel payload within ${delivery_timeout}s"
+
+printf 'delivery observed; terminating Claude session and checking deregistration\n'
+tmux kill-session -t "$tmux_session" || fail "tmux kill-session failed"
+tmux_session=""
+teardown_rc=0
+wait_for_teardown || teardown_rc=$?
+case "$teardown_rc" in
+  0) ;;
+  1) fail "Envoy session remained registered after ${teardown_timeout}s" ;;
+  *) fail "could not read Envoy's session list within ${teardown_timeout}s of the teardown, so deregistration is unproven: ${teardown_read_error:-no read finished}" ;;
+esac
+printf 'PASS: Envoy event arrived through Claude Code channel notifications and the session deregistered — %s\n' "$session_row"

package/scripts/smoke-clear-rebind.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# smoke-clear-rebind.sh — real Claude Code `/clear` handoff smoke: after `/clear`, the
+# registry entry of the new session id must list its own direct subject and never the old one.
+# See README.md "Manual smoke" for prerequisites; like smoke-channel.sh, never a CI step.
+set -euo pipefail
+
+readonly envoy_url="${ENVOY_URL:-http://127.0.0.1:9020}"
+readonly nats_url="${ENVOY_NATS_URL:?set ENVOY_NATS_URL to the live Envoy NATS listener}"
+readonly claude_bin="${CLAUDE_BIN:-claude}"
+readonly heartbeat_ms="${ENVOY_HEARTBEAT_MS:-5000}"
+readonly startup_timeout=60
+readonly registration_timeout=45
+readonly handoff_timeout=60
+
+command -v "$claude_bin" >/dev/null 2>&1 || { echo "FAIL: $claude_bin is not on PATH" >&2; exit 1; }
+for tool in tmux curl jq; do
+  command -v "$tool" >/dev/null 2>&1 || { echo "FAIL: $tool is required" >&2; exit 1; }
+done
+
+workdir="$(mktemp -d /tmp/claude-clear-rebind.XXXXXX)"
+readonly workdir
+# The smoke runs its own tmux server on a socket in its scratch directory, so its cleanup can end
+# only the session it started: `tmux kill-session` on the shared default server could end anyone's.
+readonly tmux_socket="${workdir}/tmux.sock"
+tmux() { command tmux -S "$tmux_socket" "$@"; }
+readonly claude_output="${workdir}/claude-output.txt"
+tmux_session="claude-clear-rebind-${workdir##*.}"
+session_ids=()
+claude_pid=""
+server_pid=""
+
+fail() {
+  printf 'FAIL: %s\n' "$*" >&2
+  [[ -n "$tmux_session" ]] && tmux capture-pane -pt "$tmux_session" >&2 || true
+  if [[ -f "$claude_output" ]]; then
+    printf -- '--- claude pane output (%s) ---\n' "$claude_output" >&2
+    cat "$claude_output" >&2 || true
+  fi
+  exit 1
+}
+
+cleanup() {
+  [[ -n "$tmux_session" ]] && tmux kill-session -t "$tmux_session" 2>/dev/null || true
+  # The channel server deregisters as it exits, and can outlive Claude; a registration
+  # still in flight then must land before the entries are removed below.
+  local deadline=$((SECONDS + 10)) pid
+  for pid in "$claude_pid" "$server_pid"; do
+    while [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null && (( SECONDS < deadline )); do
+      sleep 0.2
+    done
+  done
+  # A deregistered session keeps its interest entry until the listener reaps it; an
+  # unsubscribe with no topics removes the entry now.
+  for id in "${session_ids[@]}"; do
+    curl --connect-timeout 2 --max-time 5 -fsS -o /dev/null -X POST -H 'Content-Type: application/json' \
+      "${envoy_url}/v1/interests/unsubscribe" --data "{\"session_id\":\"${id}\",\"topics\":[]}" || true
+  done
+  # Claude Code keeps a transcript directory per project path, named after it.
+  rm -rf "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/${workdir//[^A-Za-z0-9]/-}" "$workdir"
+}
+trap cleanup EXIT INT TERM
+
+# The plugin under test: CLAUDE_PLUGIN_DIR when set, else a copy built from this tree into the
+# scratch directory (`scripts/build.ts --out`), since a pull request's tree carries no fresh
+# `dist/` or `legion/`.
+if [[ -n "${CLAUDE_PLUGIN_DIR:-}" ]]; then
+  plugin_dir="$(cd "$CLAUDE_PLUGIN_DIR" && pwd)"
+else
+  plugin_dir="${workdir}/claude-envoy"
+  bun "$(dirname "${BASH_SOURCE[0]}")/build.ts" --out "$plugin_dir" >/dev/null ||
+    fail "the plugin did not build into ${plugin_dir}"
+fi
+readonly plugin_dir
+
+# The registry rows this Claude session owns: it registers with its project directory.
+entries() {
+  local rows
+  rows="$(curl --connect-timeout 2 --max-time 5 -fsS "${envoy_url}/v1/sessions")" \
+    || fail "the Envoy listener at ${envoy_url} did not answer /v1/sessions"
+  jq -c --arg dir "$workdir" '[.[] | select(.dir == $dir) | {session_id, topics}]' <<<"$rows"
+}
+
+# Polls the entries until the jq filter prints something within `timeout` seconds; prints it.
+await_entries() {
+  local deadline=$((SECONDS + $1)) out
+  shift
+  while (( SECONDS < deadline )); do
+    out="$(entries | jq -cr "$@")"
+    [[ -n "$out" ]] && { printf '%s\n' "$out"; return 0; }
+    sleep 1
+  done
+  return 1
+}
+
+answer_startup_dialogs() {
+  local deadline=$((SECONDS + startup_timeout)) pane
+  while (( SECONDS < deadline )); do
+    pane="$(tmux capture-pane -pt "$tmux_session" 2>/dev/null || true)"
+    if [[ "$pane" == *"Yes, I trust this folder"* ]]; then
+      tmux send-keys -t "$tmux_session" Down Enter
+    elif [[ "$pane" == *"New MCP server found"* ]]; then
+      tmux send-keys -t "$tmux_session" Enter
+    elif [[ "$pane" == *"shift+tab to cycle"* || "$pane" == *"? for shortcuts"* ]]; then
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+# User settings stay out (`--setting-sources project,local`) so an installed copy of the
+# plugin does not start a second channel server in this session; `--plugin-dir` loads the
+# build under test with its SessionStart hook, which writes the handoff file `/clear` needs.
+printf 'starting Claude /clear rebind smoke %s; watch it with: tmux -S %s attach -t %s\n' \
+  "$tmux_session" "$tmux_socket" "$tmux_session"
+tmux new-session -d -s "$tmux_session" -x 220 -y 50 -c "$workdir" \
+  env ENVOY_NATS_URL="$nats_url" ENVOY_URL="$envoy_url" ENVOY_HEARTBEAT_MS="$heartbeat_ms" \
+  CLAUDE_PROJECT_DIR="$workdir" \
+  "$claude_bin" --setting-sources project,local --plugin-dir "$plugin_dir"
+tmux set-option -t "$tmux_session" remain-on-exit on
+claude_pid="$(tmux display-message -p -t "$tmux_session" '#{pane_pid}')"
+tmux pipe-pane -t "$tmux_session" -o "cat >> '${claude_output}'"
+answer_startup_dialogs || fail "Claude did not reach its prompt within ${startup_timeout}s"
+
+before="$(await_entries "$registration_timeout" 'if length == 1 then .[0].session_id else empty end')" \
+  || fail "no single registry entry for ${workdir} within ${registration_timeout}s: $(entries)"
+session_ids+=("$before")
+server_pid="$(pgrep -P "$claude_pid" -f 'dist/envoy-channel.js' | head -1)" || true
+[[ -n "$server_pid" ]] || fail "no channel server process (dist/envoy-channel.js) under Claude pid ${claude_pid}"
+printf 'registered %s\n' "$before"
+
+tmux send-keys -t "$tmux_session" "/clear" Enter
+cleared_at=$SECONDS
+# shellcheck disable=SC2016 # $old is a jq variable
+after_id="$(await_entries "$handoff_timeout" --arg old "$before" \
+  'if length == 1 and .[0].session_id != $old then .[0].session_id else empty end')" \
+  || fail "the entry did not move off ${before} within ${handoff_timeout}s: $(entries)"
+session_ids+=("$after_id")
+moved=$((SECONDS - cleared_at))
+printf 'the entry moved %ss after /clear (heartbeat every %sms)\n' "$moved" "$heartbeat_ms"
+
+# Checked at once and again two heartbeats later: a later registration must not bring it back.
+check_entry() {
+  local entry
+  entry="$(entries | jq -c --arg id "$after_id" '.[] | select(.session_id == $id)')"
+  printf '%s: %s\n' "$1" "$entry"
+  jq -e --arg own "notifications.agent.${after_id}" '(.topics // []) | index($own)' <<<"$entry" >/dev/null \
+    || fail "the new entry does not list its own direct subject notifications.agent.${after_id}"
+  if jq -e --arg old "notifications.agent.${before}" '(.topics // []) | index($old)' <<<"$entry" >/dev/null; then
+    fail "the new entry still lists the pre-/clear direct subject notifications.agent.${before}"
+  fi
+}
+check_entry "after /clear"
+# The server polls the handoff file; waiting for the heartbeat instead shows up here once the
+# heartbeat is long (ENVOY_HEARTBEAT_MS=60000 makes this a real check of the poll).
+move_limit=$((heartbeat_ms / 1000 - 1))
+(( move_limit > 10 )) && move_limit=10
+(( move_limit < 2 )) && move_limit=2
+(( moved <= move_limit )) \
+  || fail "the entry moved ${moved}s after /clear; the handoff poll should move it within ${move_limit}s"
+sleep $((2 * heartbeat_ms / 1000 + 1))
+check_entry "two heartbeats later"
+printf 'PASS: /clear moved the entry %s -> %s without the old direct subject (plugin %s)\n' \
+  "$before" "$after_id" "$plugin_dir"

package/scripts/smoke-session-title.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# smoke-session-title.sh — the live proof that the name a person gave a Claude Code session is
+# what this plugin registers with a real Envoy listener, that a rename replaces it, and that a
+# session nobody named keeps the folder-and-short-id fallback (dispatch://INFRA-92).
+#
+# It runs the bundles, not the TypeScript: a real nats-server, a real Envoy listener built from
+# this tree, and a copy of the plugin built from this tree into the scratch directory
+# (`scripts/build.ts --out`), whose `dist/session-hook.js` runs for each payload and
+# `dist/envoy-channel.js` as the session, read back through the listener's own
+# `GET /v1/sessions`. Its negative control is the same first case against the base revision's
+# committed `dist/envoy-channel.js`, which registers the folder name and not the chosen one.
+#
+# WHAT IS SIMULATED. This script does not start Claude Code (a pod can run it from bunx, as
+# scripts/e2e/envoy-session-delivery.sh does), so the two
+# hook payloads are JSON this script writes, shaped as Claude Code's hooks reference documents
+# them (https://code.claude.com/docs/en/hooks: a SessionStart hook receives `session_title`, "the
+# session's custom title, present when one is set, for example with `--name`, `/rename` …", and
+# "UserPromptSubmit hooks also receive `session_title` …"). The run proves that the real hook
+# bundle records what Claude Code would hand it and that the real channel server registers it
+# with a real listener. It does not prove that Claude Code sends the field; that rests on Claude
+# Code's own documentation.
+#
+# Like smoke-channel.sh and smoke-clear-rebind.sh, this is a manual smoke and never a CI step.
+#
+#   bash packages/claude-envoy/scripts/smoke-session-title.sh
+#
+# BASE_REV names the revision the negative control's bundle comes from: by default the parent of
+# 0306bcbe16df (#2154), the last revision without the fallback this smoke checks, since main has
+# carried it from then on.
+set -euo pipefail
+
+readonly base_rev="${BASE_REV:-0306bcbe16df-}"
+readonly heartbeat_ms="${ENVOY_HEARTBEAT_MS:-1000}"
+readonly chosen_name="eeny meeny"
+readonly renamed="miny moe"
+readonly register_timeout=30
+
+package_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+readonly package_dir
+repo_root="$(cd "${package_dir}/../.." && pwd)"
+readonly repo_root
+
+fail() {
+  printf 'FAIL: %s\n' "$*" >&2
+  [[ -s "${workdir:-}/server.log" ]] && { printf -- '--- channel server log ---\n'; cat "${workdir}/server.log"; } >&2
+  exit 1
+}
+
+# nats-server is a `go install` away and lands in GOPATH's bin, which is often off PATH.
+if ! command -v nats-server >/dev/null 2>&1; then
+  PATH="$(go env GOPATH 2>/dev/null)/bin:${PATH}"
+  export PATH
+fi
+for tool in bun curl jq go nats-server; do
+  command -v "$tool" >/dev/null 2>&1 ||
+    fail "$tool is required (nats-server: go install github.com/nats-io/nats-server/v2@v2.11.4)"
+done
+
+workdir="$(mktemp -d /tmp/claude-session-title.XXXXXX)"
+readonly workdir
+nats_pid=""
+listener_pid=""
+server_pid=""
+fifo_pid=""
+
+cleanup() {
+  [[ -n "$server_pid" ]] && kill "$server_pid" 2>/dev/null
+  [[ -n "$fifo_pid" ]] && kill "$fifo_pid" 2>/dev/null
+  [[ -n "$listener_pid" ]] && kill "$listener_pid" 2>/dev/null
+  [[ -n "$nats_pid" ]] && kill "$nats_pid" 2>/dev/null
+  wait 2>/dev/null || true
+  rm -rf "$workdir"
+  return 0
+}
+trap cleanup EXIT INT TERM
+
+# The plugin under test, built from this tree: a pull request's tree carries no fresh `dist/`.
+readonly plugin_dir="${workdir}/claude-envoy"
+bun "${package_dir}/scripts/build.ts" --out "$plugin_dir" >"${workdir}/build.log" 2>&1 ||
+  fail "the plugin did not build: $(cat "${workdir}/build.log")"
+
+# Both servers bind port 0, so the kernel chooses each port and nothing can take it before the
+# server serves on it, and each reports the port it got: nats-server (`-p -1`) on its `Listening for
+# client connections on` line, once it logs `Server is ready`, and the listener (PORT=0) as the
+# `addr` of its `envoy-listener listening` JSON line.
+nats-server -js -a 127.0.0.1 -p -1 -sd "${workdir}/nats" >"${workdir}/nats.log" 2>&1 &
+nats_pid=$!
+for _ in $(seq 60); do
+  grep -q 'Server is ready' "${workdir}/nats.log" && break
+  kill -0 "$nats_pid" 2>/dev/null || fail "nats-server exited at startup: $(cat "${workdir}/nats.log")"
+  sleep 0.5
+done
+grep -q 'Server is ready' "${workdir}/nats.log" || fail "nats-server was not ready within 30s: $(cat "${workdir}/nats.log")"
+nats_port="$(awk -F: '/Listening for client connections on/ {print $NF; exit}' "${workdir}/nats.log")"
+readonly nats_port
+[[ -n "$nats_port" ]] || fail "nats-server logged no client port: $(cat "${workdir}/nats.log")"
+
+(cd "${repo_root}/packages/envoy" && go build -o "${workdir}/envoy-listener" ./cmd/listener) ||
+  fail "the Envoy listener did not build"
+env PORT=0 ENVOY_LISTEN_HOST=127.0.0.1 ENVOY_MACHINE_ID=session-title-smoke \
+  NATS_URLS="nats://127.0.0.1:${nats_port}" \
+  "${workdir}/envoy-listener" >"${workdir}/listener.log" 2>&1 &
+listener_pid=$!
+listener_addr=""
+for _ in $(seq 60); do
+  listener_addr="$(jq -Rr 'fromjson? | select(.msg == "envoy-listener listening") | .addr' "${workdir}/listener.log")"
+  [[ -n "$listener_addr" ]] && break
+  kill -0 "$listener_pid" 2>/dev/null || fail "the listener exited at startup: $(cat "${workdir}/listener.log")"
+  sleep 0.5
+done
+[[ -n "$listener_addr" ]] || fail "the listener reported no address within 30s: $(cat "${workdir}/listener.log")"
+readonly envoy_url="http://${listener_addr}"
+printf 'nats-server on %s and an Envoy listener built from this tree on %s\n' "$nats_port" "$listener_addr"
+for _ in $(seq 60); do
+  [[ "$(curl -fsS --max-time 2 "${envoy_url}/healthz" 2>/dev/null)" == *healthy* ]] && break
+  sleep 0.5
+done
+[[ "$(curl -fsS --max-time 2 "${envoy_url}/healthz" 2>/dev/null)" == *healthy* ]] ||
+  fail "the listener was not healthy within 30s: $(cat "${workdir}/listener.log")"
+
+# The session's own scratch world: the envoy.json Claude Code's rule picks
+# (`$CLAUDE_CONFIG_DIR/envoy.json`), the plugin state directory the hook records titles in, the
+# `dispatch` command's state directory the registration stamps, and a project directory whose
+# name is the fallback title's first half.
+readonly config_dir="${workdir}/claude-config"
+readonly plugin_data="${workdir}/plugin-data"
+readonly dispatch_state="${workdir}/dispatch-state"
+readonly project_dir="${workdir}/probe-project"
+mkdir -p "$config_dir" "$plugin_data" "$dispatch_state" "$project_dir"
+# Dispatch is enabled against port 1, where nothing serves: the session stamps its title for the
+# `dispatch` command without this smoke needing a Dispatch server.
+jq -n --arg envoy "$envoy_url" --arg nats "nats://127.0.0.1:${nats_port}" \
+  --arg dispatch "http://127.0.0.1:1" \
+  '{dispatch: {enabled: true, serverUrl: $dispatch, token: "session-title-smoke"},
+    envoy: {enabled: true, url: $envoy, natsUrls: [$nats]}}' >"${config_dir}/envoy.json"
+
+# The channel server runs as Claude Code runs it: no ENVOY_SESSION_ID, because that QA override
+# also turns the `dispatch` command's title stamp off, and this smoke asserts the stamp.
+run_channel_server() {
+  local bundle="$1" sid="$2"
+  mkfifo "${workdir}/stdin"
+  sleep 600 >"${workdir}/stdin" &
+  fifo_pid=$!
+  env -i PATH="$PATH" HOME="$workdir" \
+    CLAUDE_CONFIG_DIR="$config_dir" CLAUDE_PLUGIN_DATA="$plugin_data" \
+    CLAUDE_PROJECT_DIR="$project_dir" CLAUDE_CODE_SESSION_ID="$sid" \
+    DISPATCH_STATE_DIR="$dispatch_state" ENVOY_HEARTBEAT_MS="$heartbeat_ms" \
+    bun "$bundle" <"${workdir}/stdin" >"${workdir}/server.log" 2>&1 &
+  server_pid=$!
+}
+
+stop_channel_server() {
+  [[ -n "$server_pid" ]] && kill "$server_pid" 2>/dev/null
+  [[ -n "$fifo_pid" ]] && kill "$fifo_pid" 2>/dev/null
+  # A killed job's status is its signal, which `set -e` would otherwise take for a failure.
+  wait "$server_pid" "$fifo_pid" 2>/dev/null || true
+  server_pid=""
+  fifo_pid=""
+  rm -f "${workdir}/stdin"
+  return 0
+}
+
+# The title the listener holds for the session `$1`, or empty when it holds no such session.
+registered_title() {
+  curl -fsS --max-time 5 "${envoy_url}/v1/sessions" 2>/dev/null |
+    jq -r --arg id "$1" '[.. | objects | select(.session_id? == $id)][0].title // empty'
+}
+
+# Waits up to `register_timeout` for the listener's title for the session `$1` to equal `$2`.
+await_title() {
+  local sid="$1" expected="$2" seen=""
+  for _ in $(seq $((register_timeout * 2))); do
+    seen="$(registered_title "$sid")"
+    [[ "$seen" == "$expected" ]] && return 0
+    sleep 0.5
+  done
+  printf 'the listener holds %q for %s, not %q\n' "$seen" "$sid" "$expected" >&2
+  return 1
+}
+
+# One hook run, with the environment Claude Code gives a hook and `payload` on its stdin. The
+# title hook is a bundle of its own and takes no mode argument: Claude Code blocks the user's
+# prompt on it, so it carries none of the SessionStart bundle's weight.
+run_hook() {
+  local mode="$1" payload="$2"
+  local -a command=("${plugin_dir}/dist/session-hook.js" "$mode")
+  if [[ "$mode" == session-title ]]; then
+    command=("${plugin_dir}/dist/session-title-hook.js")
+  fi
+  printf '%s' "$payload" | env -i PATH="$PATH" HOME="$workdir" \
+    CLAUDE_CONFIG_DIR="$config_dir" CLAUDE_PLUGIN_DATA="$plugin_data" \
+    CLAUDE_PROJECT_DIR="$project_dir" \
+    bun "${command[@]}" >"${workdir}/hook-${mode}.out" 2>&1 ||
+    fail "the ${mode} hook exited non-zero: $(cat "${workdir}/hook-${mode}.out")"
+}
+
+readonly session_id="smoke-title-0001"
+readonly short_id="${session_id:0:8}"
+readonly fallback="probe-project ${short_id}"
+
+printf '\ncase 1: a SessionStart payload carrying the name a person gave the session\n'
+run_hook open-asks "$(jq -nc --arg id "$session_id" --arg dir "$project_dir" --arg title "$chosen_name" \
+  '{session_id: $id, cwd: $dir, hook_event_name: "SessionStart", source: "startup", session_title: $title}')"
+run_channel_server "${plugin_dir}/dist/envoy-channel.js" "$session_id"
+await_title "$session_id" "$chosen_name" || fail "the chosen name did not reach the listener"
+printf 'the listener holds %q for %s\n' "$chosen_name" "$session_id"
+
+printf '\ncase 2: the session is renamed, and the next registration carries the new name\n'
+run_hook session-title "$(jq -nc --arg id "$session_id" --arg title "$renamed" \
+  '{session_id: $id, hook_event_name: "UserPromptSubmit", session_title: $title}')"
+await_title "$session_id" "$renamed" || fail "the rename did not reach the listener"
+printf 'the listener holds %q for %s\n' "$renamed" "$session_id"
+
+printf '\ncase 3: the name is taken away, and the folder-and-short-id fallback returns\n'
+run_hook session-title "$(jq -nc --arg id "$session_id" \
+  '{session_id: $id, hook_event_name: "UserPromptSubmit"}')"
+await_title "$session_id" "$fallback" || fail "the fallback did not return"
+printf 'the listener holds %q for %s\n' "$fallback" "$session_id"
+
+printf '\nthe dispatch command carries the same name on what this session writes\n'
+run_hook session-title "$(jq -nc --arg id "$session_id" --arg title "$renamed" \
+  '{session_id: $id, hook_event_name: "UserPromptSubmit", session_title: $title}')"
+await_title "$session_id" "$renamed" || fail "the rename did not reach the listener a second time"
+readonly stamp="${dispatch_state}/sessions/${session_id}/title"
+[[ -f "$stamp" ]] || fail "no title was stamped for the dispatch command at ${stamp}"
+[[ "$(cat "$stamp")" == "$renamed" ]] ||
+  fail "the dispatch command's title is $(cat "$stamp"), not ${renamed}"
+printf '%s holds %q\n' "$stamp" "$renamed"
+stop_channel_server
+
+printf '\nnegative control: the same recorded name against %s dist/envoy-channel.js\n' "$base_rev"
+readonly control_id="smoke-title-0002"
+readonly control_fallback="probe-project ${control_id:0:8}"
+run_hook open-asks "$(jq -nc --arg id "$control_id" --arg dir "$project_dir" --arg title "$chosen_name" \
+  '{session_id: $id, cwd: $dir, hook_event_name: "SessionStart", source: "startup", session_title: $title}')"
+jj -R "$repo_root" file show -r "$base_rev" packages/claude-envoy/dist/envoy-channel.js \
+  >"${workdir}/base-envoy-channel.js" ||
+  fail "could not read packages/claude-envoy/dist/envoy-channel.js at ${base_rev}"
+run_channel_server "${workdir}/base-envoy-channel.js" "$control_id"
+await_title "$control_id" "$control_fallback" ||
+  fail "the base bundle did not register the fallback it is supposed to"
+printf 'the base bundle registered %q and not %q\n' "$control_fallback" "$chosen_name"
+stop_channel_server
+
+printf '\nPASS: the chosen name registers, a rename replaces it, an unnamed session keeps the fallback, the dispatch command carries the same name, and the base bundle does none of it\n'