switchroom 0.19.16 → 0.19.18

package/bin/run-hook.sh

@@ -16,6 +16,8 @@
 #     claude on stdout still work.
 #   - Stderr is teed: visible in journald as before AND captured to a
 #     buffer so we can attach the tail to the issue detail.
+#   - On EVERY invocation, success or failure: append one JSON line
+#     carrying `duration_ms` to the hook-timing log (#3564).
 #   - On exit 0: auto-resolve any prior unresolved issue with the same
 #     fingerprint. So a transient flake clears itself on next success.
 #   - On non-zero exit: record an issue with severity=error, code = the
@@ -27,6 +29,45 @@
 #
 # The wrapper exits with the original command's exit code, so claude
 # code's hook contract (block / allow / non-zero behaviour) is preserved.
+#
+# ── Timing log (#3564) ──────────────────────────────────────────────────
+#
+# Before this, the wrapper logged ONLY failures — no timestamps, no
+# durations. That is why `secret-guard-pretool` could sit at ~145ms per
+# tool call for months (#3543) and `workspace-dynamic-hook` at ~825ms-1.1s
+# per message (#3546) without producing a single log line: neither was
+# FAILING, merely slow, and slow-but-successful was invisible.
+#
+# So every invocation now appends one JSON line to
+#   ${TELEGRAM_STATE_DIR}/hook-timings-<Ddd>.log        (Mon..Sun)
+# shaped as:
+#   {"ts":"...","date":"YYYY-MM-DD","source":"hook:x","code":"x.mjs",
+#    "duration_ms":142,"status":0}
+# so `grep duration_ms` answers any future hook-cost question.
+#
+# Cost discipline — the wrapper's own overhead was measured at 0-2ms and
+# must stay there, so the whole timing path is FORK-FREE:
+#   - `EPOCHREALTIME` (bash 5 builtin) for start/end, integer arithmetic
+#     for the delta. No `date`, no `stat`, no subshell.
+#   - The file name embeds the weekday, giving a self-truncating 7-day
+#     ring: on the first write of a new day the existing file's first line
+#     carries last week's date, so we truncate instead of appending. The
+#     staleness check is a builtin `read` from the file — measured
+#     0.024ms/append vs 0.81ms for a single `stat` fork, which is why
+#     size-based rotation was rejected here.
+# Measured net cost of `log_timing` (2000-iteration in-shell loop, a busy
+# build host): 0.40-0.78ms per invocation, dominated by the append's
+# open/write/close. That fits inside the stated 0-2ms wrapper budget with
+# room to spare; a `date` + `stat` implementation would not.
+#
+# Env:
+#   SWITCHROOM_HOOK_TIMING=0        disable timing log entirely
+#   SWITCHROOM_HOOK_TIMING_DIR      override the log directory
+#   SWITCHROOM_HOOK_TIMING_MIN_MS   only log invocations at/above this
+#                                   duration (default 0 = log everything;
+#                                   the whole failure mode here is that
+#                                   slow-but-successful is invisible, so
+#                                   the default must not filter).
 
 set -u
 
@@ -82,9 +123,15 @@ STATE_DIR="${TELEGRAM_STATE_DIR:-}"
 STDERR_TMP="$(mktemp -t run-hook-stderr.XXXXXX 2>/dev/null || mktemp)"
 trap 'rm -f "$STDERR_TMP" 2>/dev/null || true' EXIT
 
+# Fork-free monotonic-ish start stamp. EPOCHREALTIME is a bash 5 builtin;
+# on bash 4 it is unset and timing degrades to a silent no-op.
+TIMING_START="${EPOCHREALTIME:-}"
+
 "$COMMAND" "$@" 2>"$STDERR_TMP"
 STATUS=$?
 
+TIMING_END="${EPOCHREALTIME:-}"
+
 # Replay captured stderr to our own stderr now that the command has
 # fully exited — preserves journald visibility without the streaming
 # property (which hooks don't need; they're short-lived).
@@ -96,6 +143,102 @@ emit_warn() {
   echo "run-hook.sh: $1" >&2
 }
 
+# ── Timing log (#3564) ────────────────────────────────────────────────────
+#
+# Everything below is deliberately FORK-FREE: no command substitution (which
+# forks a subshell), no `date`, no `stat`. Helpers return values by assigning
+# to a caller-visible global rather than via `$(...)`.
+
+# Split EPOCHREALTIME ("1753412345.123456") into whole milliseconds.
+# LC_NUMERIC can make the separator a comma, so accept either.
+# Sets `_EPOCH_MS`; returns 1 (and leaves _EPOCH_MS empty) on a bad shape.
+_EPOCH_MS=""
+_epoch_to_ms() {
+  local raw="$1" secs usecs
+  _EPOCH_MS=""
+  case "$raw" in
+    *[.,]*) secs="${raw%%[.,]*}"; usecs="${raw#*[.,]}" ;;
+    *)      secs="$raw"; usecs="0" ;;
+  esac
+  case "$secs" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  case "$usecs" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  # Pad/truncate the fractional part to exactly 6 digits, then force base 10
+  # so a leading zero is not read as octal.
+  usecs="${usecs}000000"
+  usecs="${usecs:0:6}"
+  _EPOCH_MS=$(( secs * 1000 + (10#$usecs) / 1000 ))
+  return 0
+}
+
+# JSON-escape into `_JSON_ESCAPED`. Hook sources and command basenames are
+# operator-authored and tame, but a backslash or quote in one must not be
+# able to emit a malformed line (or inject extra fields) into a log that
+# other tooling parses.
+_JSON_ESCAPED=""
+_json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  _JSON_ESCAPED="$s"
+}
+
+log_timing() {
+  [ "${SWITCHROOM_HOOK_TIMING:-1}" = "0" ] && return 0
+  [ -n "$TIMING_START" ] || return 0
+  [ -n "$TIMING_END" ] || return 0
+
+  local timing_dir="${SWITCHROOM_HOOK_TIMING_DIR:-$STATE_DIR}"
+  [ -n "$timing_dir" ] || return 0
+  [ -d "$timing_dir" ] || return 0
+
+  local start_ms end_ms duration_ms
+  _epoch_to_ms "$TIMING_START" || return 0
+  start_ms="$_EPOCH_MS"
+  _epoch_to_ms "$TIMING_END" || return 0
+  end_ms="$_EPOCH_MS"
+  duration_ms=$(( end_ms - start_ms ))
+  # A clock step backwards must not emit a negative duration.
+  [ "$duration_ms" -lt 0 ] && duration_ms=0
+
+  local min_ms="${SWITCHROOM_HOOK_TIMING_MIN_MS:-0}"
+  case "$min_ms" in
+    ''|*[!0-9]*) min_ms=0 ;;
+  esac
+  [ "$duration_ms" -lt "$min_ms" ] && return 0
+
+  # Builtin date formatting — no `date` fork.
+  local today dow ts
+  printf -v today '%(%Y-%m-%d)T' -1
+  printf -v dow '%(%a)T' -1
+  printf -v ts '%(%Y-%m-%dT%H:%M:%S%z)T' -1
+
+  local logfile="${timing_dir}/hook-timings-${dow}.log"
+
+  # 7-day self-truncating ring: the weekday-named file is either today's or
+  # exactly a week stale, so if its first line does not carry today's date,
+  # reset it. `read` from a file is a builtin — no fork.
+  if [ -s "$logfile" ]; then
+    local first=''
+    read -r first < "$logfile" 2>/dev/null || first=''
+    case "$first" in
+      *"\"date\":\"${today}\""*) : ;;
+      *) : > "$logfile" 2>/dev/null || return 0 ;;
+    esac
+  fi
+
+  local esc_source esc_code
+  _json_escape "$SOURCE"; esc_source="$_JSON_ESCAPED"
+  _json_escape "$CODE";   esc_code="$_JSON_ESCAPED"
+
+  printf '{"ts":"%s","date":"%s","source":"%s","code":"%s","duration_ms":%s,"status":%s}\n' \
+    "$ts" "$today" "$esc_source" "$esc_code" "$duration_ms" "$STATUS" \
+    >> "$logfile" 2>/dev/null || true
+}
+
 # When RUN_HOOK_DEBUG=1 is set, drop the stderr redirect on the
 # issues-CLI invocations so an operator debugging a broken record-path
 # sees the actual cause in journald instead of just the generic
@@ -228,6 +371,11 @@ resolve_success() {
   fi
 }
 
+# Timing is emitted on EVERY path, including the degraded no-CLI path below
+# — it writes a file directly and does not need the switchroom CLI, so hook
+# cost stays observable even when issue tracking is off (#3564).
+log_timing
+
 if [ -z "$SWITCHROOM_CLI" ]; then
   # Degraded path. Emit a single warning so the operator knows visibility
   # is off, but don't change the hook's exit semantics.

package/bin/workspace-dynamic-hook.sh

@@ -66,24 +66,48 @@ mkdir -p "$CACHE_DIR" 2>/dev/null || true
 # Date-keyed cache filename: when the calendar day rolls over, the
 # `today's daily` file path the renderer reads changes (the template
 # embeds different filenames in its output), so we invalidate the cache
-# at midnight UTC by varying the filename. Yesterday's file lingers
-# harmlessly until the next sweep.
-CACHE_DATE="$(date -u +%Y-%m-%d)"
+# at midnight by varying the filename.
+#
+# Prior days' files are never cleaned up — there is no sweeper for this
+# directory anywhere in the repo. That is deliberate and cheap, not an
+# oversight: three small files per agent per day (~1100/year), a hash
+# and a signature of 65 bytes each plus a body bounded by
+# DEFAULT_DYNAMIC_TOTAL_MAX_CHARS. If that ever needs reclaiming it
+# should be a real sweeper, not a comment claiming one exists.
+#
+# LOCAL time, not UTC — this MUST match the renderer. See
+# `dailyMemoryRelativePath` in src/agents/workspace.ts, which derives
+# today's daily-memory path from getFullYear/getMonth/getDate (local)
+# on purpose: UTC would roll "today" over at early-morning for UTC+10
+# hosts. When the hook used `date -u` here, every day from 00:00 until
+# UTC midnight local the renderer's "today" file was absent from the
+# hook's watch set, so writes to it did not invalidate the cache and a
+# stale body was served.
+CACHE_DATE="$(date +%Y-%m-%d)"
 CACHE_FILE="$CACHE_DIR/workspace-dynamic.${CACHE_DATE}.hash"
 BODY_FILE="$CACHE_DIR/workspace-dynamic.${CACHE_DATE}.body"
+SIG_FILE="$CACHE_DIR/workspace-dynamic.${CACHE_DATE}.srcsig"
 
-# Mtime-fast-skip: if BODY_FILE exists AND is newer than every workspace
-# source the renderer reads, we can emit the cached body and skip the
+# Source-signature fast-skip: if BODY_FILE exists AND the signature of
+# the workspace source *set* is byte-identical to the signature recorded
+# when that body was produced, we can emit the cached body and skip the
 # ~800ms `switchroom workspace render` invocation entirely. The renderer
 # reads MEMORY.md, today's daily, yesterday's daily — see
 # `loadDynamicBootstrapFiles` in src/agents/workspace.ts.
 #
-# Skip semantics: a source file that doesn't exist contributes a "very
-# old" mtime (epoch-0 via stat fallback), which never invalidates the
-# cache. A source file that's been updated since BODY_FILE's mtime
-# triggers a fresh render. Forensics measured this fast-path saving
-# ~825ms on the common case (chat turns where MEMORY hasn't changed
-# since the last turn).
+# The signature covers each source's name + mtime + size, and records
+# missing files explicitly. A max-mtime comparison (the previous
+# approach) could not see a *deletion*: a missing source contributed
+# mtime 0, which never exceeded the body's mtime, so removing MEMORY.md
+# served the cached body forever. It also lost any source modified
+# between the render and the body write (the write-during-render race):
+# such a source ended up older than the body and became invisible
+# indefinitely. Capturing the signature *before* invoking the renderer
+# closes both: anything that changes during or after the render window
+# yields a different signature on the next turn.
+#
+# Forensics measured this fast-path saving ~825ms on the common case
+# (chat turns where no source has changed since the last turn).
 #
 # Resolve the agent's workspace dir. Switchroom uses
 # `~/.switchroom/agents/<name>/workspace/` by default. We avoid invoking
@@ -95,25 +119,63 @@ BODY_FILE="$CACHE_DIR/workspace-dynamic.${CACHE_DATE}.body"
 AGENT_DIR="${SWITCHROOM_AGENT_DIR:-$HOME/.switchroom/agents/$AGENT_NAME}"
 WS_DIR="$AGENT_DIR/workspace"
 TODAY_FILE="$WS_DIR/memory/${CACHE_DATE}.md"
-YESTERDAY_DATE="$(date -u -d 'yesterday' +%Y-%m-%d 2>/dev/null || echo "")"
+# Local-time "yesterday", matching addDays(now, -1) in workspace.ts.
+YESTERDAY_DATE="$(date -d 'yesterday' +%Y-%m-%d 2>/dev/null || echo "")"
 YESTERDAY_FILE="$WS_DIR/memory/${YESTERDAY_DATE}.md"
 
-if [ -f "$BODY_FILE" ]; then
-  # Compare BODY_FILE mtime against every source. If any source is newer
-  # the cache is stale; fall through. If all sources are older (or
-  # missing), emit the cache and exit.
-  body_mtime=$(stat -c '%Y' "$BODY_FILE" 2>/dev/null || echo 0)
-  newest_src_mtime=0
-  for src in "$WS_DIR/MEMORY.md" "$TODAY_FILE" "$YESTERDAY_FILE"; do
-    if [ -f "$src" ]; then
-      src_mtime=$(stat -c '%Y' "$src" 2>/dev/null || echo 0)
-      if [ "$src_mtime" -gt "$newest_src_mtime" ]; then
-        newest_src_mtime="$src_mtime"
+# Signature of the source set: name + mtime + size for each source the
+# renderer reads, with missing files recorded explicitly so a deletion
+# changes the signature.
+#
+# `%.9Y` (nanosecond mtime), NOT `%Y`. With whole-second mtimes, a
+# content change that lands in the same second as the previous one and
+# happens to keep the same file size produces an identical signature, so
+# the edit is served stale indefinitely — until some later change moves
+# the second or the size. That is strictly worse than the max-mtime
+# comparison this replaced, which fell through on an equal-second
+# collision (`-gt` is false when equal) and re-rendered. Nanosecond
+# resolution closes it. If a filesystem reports a zero nanosecond field
+# the signature degrades to second precision, i.e. exactly the old
+# behaviour, never worse.
+_ws_source_signature() {
+  local src meta
+  {
+    for src in "$WS_DIR/MEMORY.md" "$TODAY_FILE" "$YESTERDAY_FILE"; do
+      if [ -f "$src" ]; then
+        meta=$(stat -c '%.9Y:%s' "$src" 2>/dev/null || echo "stat-error")
+        printf '%s\t%s\n' "$src" "$meta"
+      else
+        printf '%s\tMISSING\n' "$src"
       fi
-    fi
-  done
-  if [ "$body_mtime" -gt "$newest_src_mtime" ]; then
-    # Fast path: every source is older than the cached body.
+    done
+  } | sha256sum 2>/dev/null | cut -d' ' -f1
+}
+
+# Captured BEFORE the renderer runs, so a source mutated during the
+# render window is not falsely credited to this body.
+SRC_SIG="$(_ws_source_signature)"
+
+# Is the cached body intact? CACHE_FILE holds sha256 of the render output
+# with no trailing newline; BODY_FILE holds that same output plus one
+# trailing newline (or is empty for an empty render). Command substitution
+# strips trailing newlines, so this reproduces the recorded hash exactly in
+# both cases. Without it a body truncated by a crash mid-write is served to
+# the model verbatim and pinned into the fast path forever, because the
+# signature only vouches for the *sources*, never for the body. One sha256
+# over at most DEFAULT_DYNAMIC_TOTAL_MAX_CHARS is negligible against the
+# ~825ms render it guards.
+_ws_body_intact() {
+  local recorded actual
+  recorded=$(head -1 "$CACHE_FILE" 2>/dev/null || echo "")
+  [ -n "$recorded" ] || return 1
+  actual=$(printf '%s' "$(cat "$BODY_FILE" 2>/dev/null)" | sha256sum 2>/dev/null | cut -d' ' -f1)
+  [ -n "$actual" ] && [ "$actual" = "$recorded" ]
+}
+
+if [ -f "$BODY_FILE" ] && [ -f "$SIG_FILE" ] && [ -n "$SRC_SIG" ]; then
+  RECORDED_SIG=$(head -1 "$SIG_FILE" 2>/dev/null || echo "")
+  if [ "$RECORDED_SIG" = "$SRC_SIG" ] && _ws_body_intact; then
+    # Fast path: the source set is unchanged since this body was made.
     # In inject-on-change mode, also check the session-state file — if the
     # session_id matches the last-emitted session AND the hash matches, we
     # can suppress entirely (model already has this content in context).
@@ -155,11 +217,25 @@ fi
 # <50ms; 3s is generous headroom.
 WS_DYNAMIC=$(timeout 3 switchroom workspace render "$AGENT_NAME" --dynamic --warning-mode off 2>/dev/null || true)
 
-# Empty render → emit nothing AND do NOT cache the empty body. Caching an
-# empty body would re-emit empty forever even after MEMORY comes back online,
-# defeating the whole purpose of the hook.
-if [ -z "$WS_DYNAMIC" ]; then
-  exit 0
+# An empty render IS cached. It used to `exit 0` here without writing the
+# cache, on the theory that "caching an empty body would re-emit empty
+# forever even after MEMORY comes back online" — that justification is
+# obsolete: the fast-skip re-derives the source signature every turn, so a
+# MEMORY.md that later appears (or any daily-memory write) changes the
+# signature and forces a fresh render. Not caching it meant agents whose
+# render is empty never had a cached body, the fast-skip never engaged, and
+# they paid the full ~825ms-1.1s render on every single message to produce
+# nothing.
+#
+# BODY_OUT is the exact byte string emitted on both the fresh and the cached
+# path, so `cat "$BODY_FILE"` is byte-identical to a fresh emit (Anthropic's
+# prompt cache is keyed on byte equality). Empty render → empty body file →
+# empty stdout, not a bare newline.
+if [ -n "$WS_DYNAMIC" ]; then
+  BODY_OUT="$WS_DYNAMIC
+"
+else
+  BODY_OUT=""
 fi
 
 # Content-addressed dedupe sidecar. Anthropic's prompt cache is keyed on
@@ -197,7 +273,41 @@ _ws_record_session_state() {
   fi
 }
 
+# Write a cache file atomically: fill a per-PID temp file, then rename it
+# into place. A plain `>` redirect truncates first, so a concurrent hook
+# process can observe (and cache, and serve) a half-written body. rename(2)
+# is atomic within a filesystem, so a reader sees either the whole old file
+# or the whole new one.
+_ws_write_atomic() {
+  local dest="$1" content="$2" tmp="$1.tmp.$$"
+  if printf '%s' "$content" > "$tmp" 2>/dev/null; then
+    mv -f "$tmp" "$dest" 2>/dev/null || rm -f "$tmp" 2>/dev/null || true
+  else
+    rm -f "$tmp" 2>/dev/null || true
+  fi
+}
+
+# Publish the body and the pre-render source signature that vouches for it.
+# Body first, signature second, both atomic: the signature is what arms the
+# fast path, so it must never become visible before the body it describes.
+# The signature is only written once the body file actually exists, so a
+# failed body write can never leave a "fresh" signature pointing at a stale
+# body.
+_ws_publish() {
+  _ws_write_atomic "$BODY_FILE" "$BODY_OUT"
+  if [ -n "$SRC_SIG" ] && [ -f "$BODY_FILE" ]; then
+    _ws_write_atomic "$SIG_FILE" "$SRC_SIG
+"
+  fi
+}
+
 if [ -n "$NEW_HASH" ] && [ "$NEW_HASH" = "$OLD_HASH" ] && [ -f "$BODY_FILE" ]; then
+  # Rewrite the body unconditionally, even though the hash says it is
+  # unchanged. NEW_HASH and OLD_HASH both derive from CACHE_FILE and the
+  # fresh render — neither validates BODY_FILE — so a body truncated by a
+  # crash mid-write would otherwise be cat'd to the model AND pinned into
+  # the fast path by the signature we are about to stamp on it.
+  _ws_publish
   # Content unchanged since last render. In inject-on-change mode, check if
   # we already injected this content in the current session — if so, suppress.
   if [ "$INJECT_ON_CHANGE" != "0" ] && [ -n "$SESSION_ID" ]; then
@@ -215,17 +325,16 @@ if [ -n "$NEW_HASH" ] && [ "$NEW_HASH" = "$OLD_HASH" ] && [ -f "$BODY_FILE" ]; t
   fi
   cat "$BODY_FILE"
 else
-  # Refresh sidecar: write hash + body, then echo body. Touch the body
-  # file last so the mtime fast-skip path next turn sees a fresh
-  # mtime (newer than every source we just consumed).
+  # Refresh sidecar: write hash + body, then echo body.
   if [ -n "$NEW_HASH" ]; then
-    printf '%s\n' "$NEW_HASH" > "$CACHE_FILE" 2>/dev/null || true
-    printf '%s\n' "$WS_DYNAMIC" > "$BODY_FILE" 2>/dev/null || true
+    _ws_write_atomic "$CACHE_FILE" "$NEW_HASH
+"
+    _ws_publish
     if [ "$INJECT_ON_CHANGE" != "0" ] && [ -n "$SESSION_ID" ]; then
       _ws_record_session_state "$NEW_HASH" "$SESSION_ID"
     fi
   fi
-  printf '%s\n' "$WS_DYNAMIC"
+  printf '%s' "$BODY_OUT"
 fi
 
 exit 0

package/dist/agent-scheduler/index.js

@@ -11107,7 +11107,7 @@ var AgentMemorySchema = exports_external.object({
   recall: exports_external.object({
     max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
     cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
-    min_overlap: exports_external.number().min(0).max(1).optional().describe("Minimum Jaccard token overlap [0.0–1.0] between the user " + "prompt and a memory's text for the memory to be injected. " + "Drops low-relevance matches before the count cap so weak hits " + "don't fill the slot on real queries. 0.0 disables (default — " + "current behaviour). Try 0.10–0.20 to start; observe the " + "`overlap_dropped` field via `switchroom memory recall-log`."),
+    min_overlap: exports_external.number().min(0).max(1).optional().describe("Minimum containment token overlap [0.0–1.0] between the user " + "prompt and a memory's text for the memory to be injected. " + "A cheap FLOOR that removes candidates with (near-)zero lexical " + "relationship to the prompt — NOT a precision control: at the " + "recommended 0.10 the gate is near-passthrough, and the " + "effective precision control is the engine rerank plus the " + "max_memories head-slice. 0.0 disables (default — current " + "behaviour). Use 0.10; values at or above 0.20 measurably " + "starve recall — on production replay 0.20 leaves ~41.9% of " + "turns with NO memories at all, re-creating the bug #3541 " + "fixed. Observe the `overlap_dropped` field via " + "`switchroom memory recall-log`."),
     types: exports_external.array(exports_external.string()).optional().describe("Hindsight fact types to recall. Switchroom default is " + '["world", "experience", "observation"] — the synthesized ' + "`observation` tier is on by default. Set to " + '["world", "experience"] to opt out of observation-backed ' + "recall for this agent (or fleet-wide under defaults)."),
     additional_banks: exports_external.array(exports_external.string()).optional().describe("Extra Hindsight banks to recall from on every turn, merged into " + "the agent's own bank results — e.g. a shared operator/household " + "profile bank authored via `switchroom memory profile`. Each is " + "recalled with an 8s timeout and is non-fatal on failure. Stays " + "within the single tenant: all banks are the operator's data, in " + "the operator's Hindsight instance (see the `single-tenant` " + "invariant). Defaults to [] (no extra banks)."),
     sender_banks: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Per-speaker recall routing: a map of Telegram sender → extra " + "recall bank. When a message arrives, the agent also recalls the " + "speaker's bank (matched by Telegram username — a leading @ is " + "optional — or numeric user_id), merged " + "into its own results — so each trusted user gets their own " + "profile context. Additive recall scoping within the single " + "tenant: never an access boundary (who may drive an agent stays " + "the per-agent user assignment in `access.allowFrom`). Author the " + "banks via `switchroom memory profile`."),
@@ -11419,9 +11419,16 @@ var ReactionDispatchSchema = exports_external.object({
   enabled: exports_external.boolean().optional().describe("Master switch for the reaction-dispatch path. Default false — " + "with no reaction_dispatch block, reactions are persisted (and may " + "feed the `reactions` feedback path) but are NEVER dispatched as " + "event-driven inbound turns."),
   emojis: exports_external.array(exports_external.string()).optional().describe('Emoji allowlist that triggers a `<channel event="reaction">` ' + "inbound turn when reacted to any message. Default [] (nothing " + "fires). Cascade mode: REPLACE (not union) — a layer's list " + "replaces lower layers entirely so an operator can narrow per-agent.")
 }).optional();
-var ReleaseBlock = exports_external.object({
+var releaseBlockFields = {
   channel: exports_external.enum(["dev", "rc", "latest"]).optional(),
   pin: exports_external.string().regex(/^(sha-[0-9a-f]{7,40}|v\d+\.\d+\.\d+)$/).optional()
+};
+var ReleaseBlock = exports_external.object(releaseBlockFields).strict().refine((r) => !(r.channel && r.pin), {
+  message: "release.channel and release.pin are mutually exclusive"
+});
+var RootReleaseBlock = exports_external.object({
+  ...releaseBlockFields,
+  auto_update: exports_external.boolean().optional().describe("Opt-in unattended fleet auto-update (KEN-131). When true, hostd's " + "release watcher polls the published release version and, on a new " + "release, drives the EXISTING staggered canary rollout " + "(`switchroom rollout --pin vX.Y.Z`) unattended: canary-first, " + "per-agent version assert, durable pin persisted only after the " + "canary is green, abort + operator alert card on canary failure, " + "and compose rollback on a failed apply. Default false — with it " + "unset/false, behaviour is unchanged.")
 }).strict().refine((r) => !(r.channel && r.pin), {
   message: "release.channel and release.pin are mutually exclusive"
 });
@@ -11665,6 +11672,7 @@ var AutoReleaseCheckSchema = exports_external.object({
   enabled: exports_external.boolean().default(false).describe("When true, hostd polls the remote release tag every " + "`interval_minutes` and applies + restarts the fleet when a new " + "release is detected. Default false — opt-in."),
   interval_minutes: exports_external.number().int().min(5).max(1440).default(5).describe("Poll interval in minutes. Floor of 5m matches the agent-config " + "cron rate limit; ceiling of 1440m (24h) is a sanity cap."),
   apply_on_detect: exports_external.boolean().default(true).describe("When false, hostd logs `release_detected` but does NOT call " + "update_apply / restart all. Useful for dogfooding the detector " + "without rolling the fleet."),
+  notify_on_detect: exports_external.boolean().default(false).describe("KEN-129 — operator-in-the-loop update prompt. Only consulted " + "when apply_on_detect is false (auto-apply supersedes notify): " + "a newly detected release posts ONE operator approval card " + "('fleet is behind — tap to apply') via an admin agent's " + "gateway; Approve runs hostd's update_apply path (fleet-" + "mutation-locked, durable status rows, get_status-pollable). " + "Dedup on release id: the last-notified id persists in " + "~/.switchroom/release-notify-state.json, so a card that " + "reached the operator is never re-posted for the same release."),
   image_ref: exports_external.string().default("ghcr.io/switchroom/switchroom-agent:latest").describe("Image reference whose remote digest is compared to the local " + "image digest. Defaults to the agent image's :latest tag, which " + "is the canonical signal that a release has been promoted.")
 });
 var HostControlConfigSchema = exports_external.object({
@@ -11707,7 +11715,7 @@ var SwitchroomConfigSchema = exports_external.object({
     timezone: exports_external.string().regex(TIMEZONE_REGEX, "timezone must be an IANA zone name like 'Australia/Melbourne' or 'UTC'").optional().describe("Global default IANA timezone applied to every agent unless the " + "agent (or its profile) declares its own. See the per-agent " + "timezone field for the full cascade and auto-detection fallback.")
   }),
   telegram: TelegramConfigSchema,
-  release: ReleaseBlock.optional().describe("Fleet-wide default release-channel pin / pointer for the update " + "flow. Either `channel` (dev|rc|latest) or `pin` (sha-<hex>|v<semver>) " + "— mutually exclusive. Per-agent `release` REPLACES this entirely."),
+  release: RootReleaseBlock.optional().describe("Fleet-wide default release-channel pin / pointer for the update " + "flow. Either `channel` (dev|rc|latest) or `pin` (sha-<hex>|v<semver>) " + "— mutually exclusive. Per-agent `release` REPLACES this entirely " + "(except `auto_update`, which is root-only — a fleet property read by " + "hostd's release watcher, never per-agent)."),
   memory: MemoryBackendConfigSchema.optional(),
   hindsight: HindsightConfigSchema.optional().describe("Fleet-singleton Hindsight (memory backend) configuration. Currently " + "just the LLM knob (provider + model) used for retain/reflect/" + "consolidation. Both fields optional; when unset the container falls " + "back to provider=claude-code + the hard-coded HINDSIGHT_DEFAULT_MODEL " + "so nothing changes for operators who don't set it. Read at container " + "launch by startHindsight() (src/setup/hindsight.ts) — takes effect on " + "the next `switchroom apply` / `memory setup --recreate`."),
   vault: VaultConfigSchema.optional(),

package/dist/auth-broker/index.js

@@ -16749,7 +16749,7 @@ var AgentMemorySchema = exports_external.object({
   recall: exports_external.object({
     max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
     cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
-    min_overlap: exports_external.number().min(0).max(1).optional().describe("Minimum Jaccard token overlap [0.0–1.0] between the user " + "prompt and a memory's text for the memory to be injected. " + "Drops low-relevance matches before the count cap so weak hits " + "don't fill the slot on real queries. 0.0 disables (default — " + "current behaviour). Try 0.10–0.20 to start; observe the " + "`overlap_dropped` field via `switchroom memory recall-log`."),
+    min_overlap: exports_external.number().min(0).max(1).optional().describe("Minimum containment token overlap [0.0–1.0] between the user " + "prompt and a memory's text for the memory to be injected. " + "A cheap FLOOR that removes candidates with (near-)zero lexical " + "relationship to the prompt — NOT a precision control: at the " + "recommended 0.10 the gate is near-passthrough, and the " + "effective precision control is the engine rerank plus the " + "max_memories head-slice. 0.0 disables (default — current " + "behaviour). Use 0.10; values at or above 0.20 measurably " + "starve recall — on production replay 0.20 leaves ~41.9% of " + "turns with NO memories at all, re-creating the bug #3541 " + "fixed. Observe the `overlap_dropped` field via " + "`switchroom memory recall-log`."),
     types: exports_external.array(exports_external.string()).optional().describe("Hindsight fact types to recall. Switchroom default is " + '["world", "experience", "observation"] — the synthesized ' + "`observation` tier is on by default. Set to " + '["world", "experience"] to opt out of observation-backed ' + "recall for this agent (or fleet-wide under defaults)."),
     additional_banks: exports_external.array(exports_external.string()).optional().describe("Extra Hindsight banks to recall from on every turn, merged into " + "the agent's own bank results — e.g. a shared operator/household " + "profile bank authored via `switchroom memory profile`. Each is " + "recalled with an 8s timeout and is non-fatal on failure. Stays " + "within the single tenant: all banks are the operator's data, in " + "the operator's Hindsight instance (see the `single-tenant` " + "invariant). Defaults to [] (no extra banks)."),
     sender_banks: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Per-speaker recall routing: a map of Telegram sender → extra " + "recall bank. When a message arrives, the agent also recalls the " + "speaker's bank (matched by Telegram username — a leading @ is " + "optional — or numeric user_id), merged " + "into its own results — so each trusted user gets their own " + "profile context. Additive recall scoping within the single " + "tenant: never an access boundary (who may drive an agent stays " + "the per-agent user assignment in `access.allowFrom`). Author the " + "banks via `switchroom memory profile`."),
@@ -17061,9 +17061,16 @@ var ReactionDispatchSchema = exports_external.object({
   enabled: exports_external.boolean().optional().describe("Master switch for the reaction-dispatch path. Default false — " + "with no reaction_dispatch block, reactions are persisted (and may " + "feed the `reactions` feedback path) but are NEVER dispatched as " + "event-driven inbound turns."),
   emojis: exports_external.array(exports_external.string()).optional().describe('Emoji allowlist that triggers a `<channel event="reaction">` ' + "inbound turn when reacted to any message. Default [] (nothing " + "fires). Cascade mode: REPLACE (not union) — a layer's list " + "replaces lower layers entirely so an operator can narrow per-agent.")
 }).optional();
-var ReleaseBlock = exports_external.object({
+var releaseBlockFields = {
   channel: exports_external.enum(["dev", "rc", "latest"]).optional(),
   pin: exports_external.string().regex(/^(sha-[0-9a-f]{7,40}|v\d+\.\d+\.\d+)$/).optional()
+};
+var ReleaseBlock = exports_external.object(releaseBlockFields).strict().refine((r) => !(r.channel && r.pin), {
+  message: "release.channel and release.pin are mutually exclusive"
+});
+var RootReleaseBlock = exports_external.object({
+  ...releaseBlockFields,
+  auto_update: exports_external.boolean().optional().describe("Opt-in unattended fleet auto-update (KEN-131). When true, hostd's " + "release watcher polls the published release version and, on a new " + "release, drives the EXISTING staggered canary rollout " + "(`switchroom rollout --pin vX.Y.Z`) unattended: canary-first, " + "per-agent version assert, durable pin persisted only after the " + "canary is green, abort + operator alert card on canary failure, " + "and compose rollback on a failed apply. Default false — with it " + "unset/false, behaviour is unchanged.")
 }).strict().refine((r) => !(r.channel && r.pin), {
   message: "release.channel and release.pin are mutually exclusive"
 });
@@ -17307,6 +17314,7 @@ var AutoReleaseCheckSchema = exports_external.object({
   enabled: exports_external.boolean().default(false).describe("When true, hostd polls the remote release tag every " + "`interval_minutes` and applies + restarts the fleet when a new " + "release is detected. Default false — opt-in."),
   interval_minutes: exports_external.number().int().min(5).max(1440).default(5).describe("Poll interval in minutes. Floor of 5m matches the agent-config " + "cron rate limit; ceiling of 1440m (24h) is a sanity cap."),
   apply_on_detect: exports_external.boolean().default(true).describe("When false, hostd logs `release_detected` but does NOT call " + "update_apply / restart all. Useful for dogfooding the detector " + "without rolling the fleet."),
+  notify_on_detect: exports_external.boolean().default(false).describe("KEN-129 — operator-in-the-loop update prompt. Only consulted " + "when apply_on_detect is false (auto-apply supersedes notify): " + "a newly detected release posts ONE operator approval card " + "('fleet is behind — tap to apply') via an admin agent's " + "gateway; Approve runs hostd's update_apply path (fleet-" + "mutation-locked, durable status rows, get_status-pollable). " + "Dedup on release id: the last-notified id persists in " + "~/.switchroom/release-notify-state.json, so a card that " + "reached the operator is never re-posted for the same release."),
   image_ref: exports_external.string().default("ghcr.io/switchroom/switchroom-agent:latest").describe("Image reference whose remote digest is compared to the local " + "image digest. Defaults to the agent image's :latest tag, which " + "is the canonical signal that a release has been promoted.")
 });
 var HostControlConfigSchema = exports_external.object({
@@ -17349,7 +17357,7 @@ var SwitchroomConfigSchema = exports_external.object({
     timezone: exports_external.string().regex(TIMEZONE_REGEX, "timezone must be an IANA zone name like 'Australia/Melbourne' or 'UTC'").optional().describe("Global default IANA timezone applied to every agent unless the " + "agent (or its profile) declares its own. See the per-agent " + "timezone field for the full cascade and auto-detection fallback.")
   }),
   telegram: TelegramConfigSchema,
-  release: ReleaseBlock.optional().describe("Fleet-wide default release-channel pin / pointer for the update " + "flow. Either `channel` (dev|rc|latest) or `pin` (sha-<hex>|v<semver>) " + "— mutually exclusive. Per-agent `release` REPLACES this entirely."),
+  release: RootReleaseBlock.optional().describe("Fleet-wide default release-channel pin / pointer for the update " + "flow. Either `channel` (dev|rc|latest) or `pin` (sha-<hex>|v<semver>) " + "— mutually exclusive. Per-agent `release` REPLACES this entirely " + "(except `auto_update`, which is root-only — a fleet property read by " + "hostd's release watcher, never per-agent)."),
   memory: MemoryBackendConfigSchema.optional(),
   hindsight: HindsightConfigSchema.optional().describe("Fleet-singleton Hindsight (memory backend) configuration. Currently " + "just the LLM knob (provider + model) used for retain/reflect/" + "consolidation. Both fields optional; when unset the container falls " + "back to provider=claude-code + the hard-coded HINDSIGHT_DEFAULT_MODEL " + "so nothing changes for operators who don't set it. Read at container " + "launch by startHindsight() (src/setup/hindsight.ts) — takes effect on " + "the next `switchroom apply` / `memory setup --recreate`."),
   vault: VaultConfigSchema.optional(),
@@ -18357,7 +18365,23 @@ var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 
 // src/memory/hindsight.ts
-var DEFAULT_RETAIN_MISSION = "Extract user preferences, ongoing projects, recurring commitments, " + "important context, and durable facts that should help across future " + "conversations. Skip one-off chatter and temporary task noise, " + "including in-flight workflow/process narration (a sub-task started, " + "paused, or is still running) — only retain the outcome once a task " + "actually completes or a decision is made.";
+var DEFAULT_RETAIN_MISSION = "Extract durable facts that will still be true and useful weeks from now: " + "user preferences and standing rules, ongoing projects and recurring " + "commitments, technical and architectural decisions with their rationale, " + "and people/tool relationships. A preference revealed by a request is " + "durable — record the preference (what the user likes, wants, or always " + `does), not the request itself.
+
+` + `NEVER extract:
+` + "- Agent tool-use traces or narration of what the assistant did (e.g. " + `"the assistant used X to query Y", "ran a search", "sent the message").
+` + "- In-flight workflow/process narration (a sub-task started, paused, or is " + "still running) — retain the outcome only once the task completes or a " + `decision is made.
+` + `- Operation, request, batch or session IDs, UUIDs, hashes, or error codes.
+` + "- Hindsight's own errors, retries, backlogs, or internal state — the " + `memory system's self-reports are not memories.
+` + `- Restatements of the user's current request or the task in progress.
+` + "- Transient state (unread counts, build status, what is running right now) " + "unless the fact is explicitly dated, in which case record it as a dated " + `observation.
+` + `- Greetings, acknowledgements, and routine operational chatter.
+
+` + "If a candidate fact matches an exclusion, drop it rather than rewording " + "it. If nothing durable remains, return an empty facts list.";
+var SUPERSEDED_RETAIN_MISSIONS = [
+  "Extract technical decisions, architectural choices, user preferences, project context, and people/tool relationships. Ignore routine greetings and transient operational details.",
+  "Extract user preferences, ongoing projects, recurring commitments, " + "important context, and durable facts that should help across future " + "conversations. Skip one-off chatter and temporary task noise.",
+  "Extract user preferences, ongoing projects, recurring commitments, " + "important context, and durable facts that should help across future " + "conversations. Skip one-off chatter and temporary task noise, " + "including in-flight workflow/process narration (a sub-task started, " + "paused, or is still running) — only retain the outcome once a task " + "actually completes or a decision is made."
+];
 var PROFILE_MEMORY_DEFAULTS = {
   "health-coach": {
     disposition: { skepticism: 2, literalism: 2, empathy: 5 },
@@ -18742,6 +18766,7 @@ var materializedDirs = new Set;
 // src/agents/scaffold.ts
 var REPO_ROOT = resolve5(import.meta.dirname, "../..");
 var CLAUDE_MD_YOURS_PLACEHOLDER = "This space is yours. Add per-agent rules, exceptions, or context the " + "Switchroom template doesn't capture. Everything above the marker line is " + "regenerated on every apply; this section is preserved.";
+var pendingBankOps = new Set;
 var SWITCHROOM_OWNED_SETTINGS_KEYS = new Set([
   "permissions",
   "mcpServers",

package/dist/cli/notion-write-pretool.mjs

@@ -11865,7 +11865,7 @@ var AgentMemorySchema = exports_external.object({
   recall: exports_external.object({
     max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
     cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
-    min_overlap: exports_external.number().min(0).max(1).optional().describe("Minimum Jaccard token overlap [0.0\u20131.0] between the user " + "prompt and a memory's text for the memory to be injected. " + "Drops low-relevance matches before the count cap so weak hits " + "don't fill the slot on real queries. 0.0 disables (default \u2014 " + "current behaviour). Try 0.10\u20130.20 to start; observe the " + "`overlap_dropped` field via `switchroom memory recall-log`."),
+    min_overlap: exports_external.number().min(0).max(1).optional().describe("Minimum containment token overlap [0.0\u20131.0] between the user " + "prompt and a memory's text for the memory to be injected. " + "A cheap FLOOR that removes candidates with (near-)zero lexical " + "relationship to the prompt \u2014 NOT a precision control: at the " + "recommended 0.10 the gate is near-passthrough, and the " + "effective precision control is the engine rerank plus the " + "max_memories head-slice. 0.0 disables (default \u2014 current " + "behaviour). Use 0.10; values at or above 0.20 measurably " + "starve recall \u2014 on production replay 0.20 leaves ~41.9% of " + "turns with NO memories at all, re-creating the bug #3541 " + "fixed. Observe the `overlap_dropped` field via " + "`switchroom memory recall-log`."),
     types: exports_external.array(exports_external.string()).optional().describe("Hindsight fact types to recall. Switchroom default is " + '["world", "experience", "observation"] \u2014 the synthesized ' + "`observation` tier is on by default. Set to " + '["world", "experience"] to opt out of observation-backed ' + "recall for this agent (or fleet-wide under defaults)."),
     additional_banks: exports_external.array(exports_external.string()).optional().describe("Extra Hindsight banks to recall from on every turn, merged into " + "the agent's own bank results \u2014 e.g. a shared operator/household " + "profile bank authored via `switchroom memory profile`. Each is " + "recalled with an 8s timeout and is non-fatal on failure. Stays " + "within the single tenant: all banks are the operator's data, in " + "the operator's Hindsight instance (see the `single-tenant` " + "invariant). Defaults to [] (no extra banks)."),
     sender_banks: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Per-speaker recall routing: a map of Telegram sender \u2192 extra " + "recall bank. When a message arrives, the agent also recalls the " + "speaker's bank (matched by Telegram username \u2014 a leading @ is " + "optional \u2014 or numeric user_id), merged " + "into its own results \u2014 so each trusted user gets their own " + "profile context. Additive recall scoping within the single " + "tenant: never an access boundary (who may drive an agent stays " + "the per-agent user assignment in `access.allowFrom`). Author the " + "banks via `switchroom memory profile`."),
@@ -12177,9 +12177,16 @@ var ReactionDispatchSchema = exports_external.object({
   enabled: exports_external.boolean().optional().describe("Master switch for the reaction-dispatch path. Default false \u2014 " + "with no reaction_dispatch block, reactions are persisted (and may " + "feed the `reactions` feedback path) but are NEVER dispatched as " + "event-driven inbound turns."),
   emojis: exports_external.array(exports_external.string()).optional().describe('Emoji allowlist that triggers a `<channel event="reaction">` ' + "inbound turn when reacted to any message. Default [] (nothing " + "fires). Cascade mode: REPLACE (not union) \u2014 a layer's list " + "replaces lower layers entirely so an operator can narrow per-agent.")
 }).optional();
-var ReleaseBlock = exports_external.object({
+var releaseBlockFields = {
   channel: exports_external.enum(["dev", "rc", "latest"]).optional(),
   pin: exports_external.string().regex(/^(sha-[0-9a-f]{7,40}|v\d+\.\d+\.\d+)$/).optional()
+};
+var ReleaseBlock = exports_external.object(releaseBlockFields).strict().refine((r) => !(r.channel && r.pin), {
+  message: "release.channel and release.pin are mutually exclusive"
+});
+var RootReleaseBlock = exports_external.object({
+  ...releaseBlockFields,
+  auto_update: exports_external.boolean().optional().describe("Opt-in unattended fleet auto-update (KEN-131). When true, hostd's " + "release watcher polls the published release version and, on a new " + "release, drives the EXISTING staggered canary rollout " + "(`switchroom rollout --pin vX.Y.Z`) unattended: canary-first, " + "per-agent version assert, durable pin persisted only after the " + "canary is green, abort + operator alert card on canary failure, " + "and compose rollback on a failed apply. Default false \u2014 with it " + "unset/false, behaviour is unchanged.")
 }).strict().refine((r) => !(r.channel && r.pin), {
   message: "release.channel and release.pin are mutually exclusive"
 });
@@ -12423,6 +12430,7 @@ var AutoReleaseCheckSchema = exports_external.object({
   enabled: exports_external.boolean().default(false).describe("When true, hostd polls the remote release tag every " + "`interval_minutes` and applies + restarts the fleet when a new " + "release is detected. Default false \u2014 opt-in."),
   interval_minutes: exports_external.number().int().min(5).max(1440).default(5).describe("Poll interval in minutes. Floor of 5m matches the agent-config " + "cron rate limit; ceiling of 1440m (24h) is a sanity cap."),
   apply_on_detect: exports_external.boolean().default(true).describe("When false, hostd logs `release_detected` but does NOT call " + "update_apply / restart all. Useful for dogfooding the detector " + "without rolling the fleet."),
+  notify_on_detect: exports_external.boolean().default(false).describe("KEN-129 \u2014 operator-in-the-loop update prompt. Only consulted " + "when apply_on_detect is false (auto-apply supersedes notify): " + "a newly detected release posts ONE operator approval card " + "('fleet is behind \u2014 tap to apply') via an admin agent's " + "gateway; Approve runs hostd's update_apply path (fleet-" + "mutation-locked, durable status rows, get_status-pollable). " + "Dedup on release id: the last-notified id persists in " + "~/.switchroom/release-notify-state.json, so a card that " + "reached the operator is never re-posted for the same release."),
   image_ref: exports_external.string().default("ghcr.io/switchroom/switchroom-agent:latest").describe("Image reference whose remote digest is compared to the local " + "image digest. Defaults to the agent image's :latest tag, which " + "is the canonical signal that a release has been promoted.")
 });
 var HostControlConfigSchema = exports_external.object({
@@ -12465,7 +12473,7 @@ var SwitchroomConfigSchema = exports_external.object({
     timezone: exports_external.string().regex(TIMEZONE_REGEX, "timezone must be an IANA zone name like 'Australia/Melbourne' or 'UTC'").optional().describe("Global default IANA timezone applied to every agent unless the " + "agent (or its profile) declares its own. See the per-agent " + "timezone field for the full cascade and auto-detection fallback.")
   }),
   telegram: TelegramConfigSchema,
-  release: ReleaseBlock.optional().describe("Fleet-wide default release-channel pin / pointer for the update " + "flow. Either `channel` (dev|rc|latest) or `pin` (sha-<hex>|v<semver>) " + "\u2014 mutually exclusive. Per-agent `release` REPLACES this entirely."),
+  release: RootReleaseBlock.optional().describe("Fleet-wide default release-channel pin / pointer for the update " + "flow. Either `channel` (dev|rc|latest) or `pin` (sha-<hex>|v<semver>) " + "\u2014 mutually exclusive. Per-agent `release` REPLACES this entirely " + "(except `auto_update`, which is root-only \u2014 a fleet property read by " + "hostd's release watcher, never per-agent)."),
   memory: MemoryBackendConfigSchema.optional(),
   hindsight: HindsightConfigSchema.optional().describe("Fleet-singleton Hindsight (memory backend) configuration. Currently " + "just the LLM knob (provider + model) used for retain/reflect/" + "consolidation. Both fields optional; when unset the container falls " + "back to provider=claude-code + the hard-coded HINDSIGHT_DEFAULT_MODEL " + "so nothing changes for operators who don't set it. Read at container " + "launch by startHindsight() (src/setup/hindsight.ts) \u2014 takes effect on " + "the next `switchroom apply` / `memory setup --recreate`."),
   vault: VaultConfigSchema.optional(),