switchroom 0.19.26 → 0.19.28

package/profiles/_base/start.sh.hbs

@@ -475,11 +475,25 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
   #    mechanism — it runs because the container is up, needs no LLM turn of
   #    its own, and cannot be prompted away.
   #
-  #    SERIALISED. `flock -n` on a per-agent lockfile makes overlapping runs
-  #    impossible: a run that overshoots the interval causes the next tick to
-  #    SKIP, never to stack. The lock path is deliberately the one the
-  #    out-of-band recovery tooling also takes, so a manual sweep and this
-  #    loop mutually exclude instead of double-processing an entry.
+  #    SERIALISED, BUT NOT BY THIS FILE. `drain_pending.py` takes an
+  #    exclusive `fcntl.flock` on `$HOME/.hindsight/drain-pending.lock` for
+  #    the whole of `drain()` and does nothing at all if another drain holds
+  #    it. That is where the guarantee has to live: the queue has three
+  #    independent drain paths — the SessionStart hook (which imports
+  #    `drain` in-process, and boots while this loop may be mid-run), this
+  #    sidecar, and the `docker exec … drain_pending.py --backlog` that
+  #    `switchroom doctor` documents for operators — and a lock wrapped
+  #    around only ONE of them serialises nothing. Two drains on one queue
+  #    means the same entry POSTed twice, i.e. ~168s of a 4-slot fleet-wide
+  #    lane spent twice on one memory.
+  #
+  #    DO NOT WRAP THE CALL BELOW IN `flock`. It would take the very lock
+  #    the python then asks for, and the drain would skip every tick,
+  #    silently, forever. (This is also why the lock file is NOT the
+  #    `drain.lock` the interim host cron wraps its `docker exec` in — with
+  #    distinct names that wrapper stays merely redundant instead of
+  #    starving the drain it launched.) `tests/hindsight-drain-sidecar.test.ts`
+  #    fails if a `flock` reappears here.
   #
   #    LANE-RESPECTING. Retain extraction is served by a small fixed pool of
   #    LLM lanes (4 on this fleet, 2 boxes x 2 slots) SHARED with live
@@ -516,6 +530,22 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
   #    already queued ABOVE the current bound are recovered by re-splitting
   #    them, not by waiting longer. An operator who still wants a longer
   #    deadline moves HINDSIGHT_RETAIN_CLIENT_DEADLINE_S, which moves both.
+  #    THE ROWS OUTLIVE THE STOPGAP THAT PRODUCED THEM; the serialisation in
+  #    it does not. That stopgap is the interim host cron named above, whose
+  #    outer `flock` on `drain.lock` serialised only that cron against
+  #    itself, while the SessionStart hook's in-process drain and a bare
+  #    `docker exec` walked straight past it — the widening to all three is
+  #    the whole point of moving the lock inside `drain_pending.py`. What
+  #    the rows measure is one drain completing (or not) inside a deadline,
+  #    which is a property of the drain and not of who serialised it, so
+  #    they still stand. They are not a licence to reinstate the wrapper.
+  #
+  #    UNATTENDED, SO BOUNDED PER ENTRY. `drain_pending` parks an entry past
+  #    its attempt ceiling (default 20) instead of retrying it forever —
+  #    without that, one permanently-failing entry on a 3600s backlog budget
+  #    would burn most of this agent's wall-clock, and a share of the 4
+  #    lanes, indefinitely and with nobody watching. Parked entries stay
+  #    queued and are still reconciled for free; `--force` replays them.
   #
   #    Failure is never terminal: the drain exits non-zero only when it
   #    promoted entries to `.dead`, and the loop below ignores the status
@@ -524,13 +554,24 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
   #    (those are exported later, in the inner pass) — only $HOME, to find
   #    the queue.
   #
+  #    DOCKER RUNTIME ONLY. This whole block is inside the
+  #    `[ "$SWITCHROOM_RUNTIME" = "docker" ]` branch that ends at the `exec
+  #    tmux` below, so an agent on the legacy systemd path gets NO drain
+  #    sidecar and keeps the boot-only SessionStart behaviour. The fleet is
+  #    entirely docker; if systemd ever comes back, this needs an equivalent
+  #    timer, and until then the honest statement is that it is unsupported
+  #    there rather than silently absent.
+  #
   #    Kill switch: SWITCHROOM_HINDSIGHT_DRAIN=0 at the container level.
-  #    Interval: SWITCHROOM_HINDSIGHT_DRAIN_INTERVAL_S (default 900s).
+  #    Interval: SWITCHROOM_HINDSIGHT_DRAIN_INTERVAL_S (default 900s). That
+  #    is a COOLDOWN BETWEEN RUNS, not a fixed period — the loop is strictly
+  #    sequential, so the true tick-to-tick spacing is one drain's duration
+  #    (up to the 3600s backlog budget) plus the interval. Deliberate: a
+  #    fixed period would give a long, lane-heavy drain no cooldown at all.
   _hs_drain_script="{{agentDir}}/.claude/plugins/hindsight-memory/scripts/drain_pending.py"
-  if [ "$SWITCHROOM_HINDSIGHT_DRAIN" != "0" ] \
+  if [ "${SWITCHROOM_HINDSIGHT_DRAIN:-1}" != "0" ] \
      && [ -f "$_hs_drain_script" ] \
-     && command -v python3 >/dev/null 2>&1 \
-     && command -v flock >/dev/null 2>&1; then
+     && command -v python3 >/dev/null 2>&1; then
     _switchroom_hindsight_drain_loop() {
       local _script="$1"
       local _interval="${SWITCHROOM_HINDSIGHT_DRAIN_INTERVAL_S:-900}"
@@ -538,24 +579,38 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
       # against the LLM lane. 60s is the floor.
       case "$_interval" in ''|*[!0-9]*) _interval=900 ;; esac
       [ "$_interval" -lt 60 ] && _interval=60
-      local _lock="$HOME/.hindsight/drain.lock"
-      mkdir -p "$HOME/.hindsight" 2>/dev/null || true
       # Deterministic per-agent phase offset (see the note above).
       local _offset=0
       if command -v cksum >/dev/null 2>&1; then
         _offset=$(( $(printf '%s' "{{name}}" | cksum | cut -d' ' -f1) % _interval ))
       fi
-      echo "[hindsight-drain] starting: interval=${_interval}s offset=${_offset}s lock=${_lock}"
+      echo "[hindsight-drain] starting: interval=${_interval}s (cooldown between runs, not a fixed period) offset=${_offset}s serialised-by=drain_pending.py"
       sleep "$_offset"
       while true; do
-        # -n: if a drain (ours or an operator sweep) already holds the
-        # lock, skip this tick entirely instead of queueing behind it.
-        flock -n "$_lock" python3 "$_script" --backlog || true
+        # No `flock` here, by design — drain_pending.py locks itself, and a
+        # wrapper here would hold the lock it needs. See the note above.
+        python3 "$_script" --backlog || true
         sleep "$_interval"
       done
     }
     _switchroom_supervise hindsight-drain /var/log/switchroom/hindsight-drain.log \
       _switchroom_hindsight_drain_loop "$_hs_drain_script" &
+  else
+    # NEVER FAIL SILENTLY. Without this branch a failed precondition left no
+    # log line and no logfile at all, so "is the drain running?" was
+    # unanswerable from the logs — indistinguishable from a drain that was
+    # running and finding nothing to do.
+    if [ "${SWITCHROOM_HINDSIGHT_DRAIN:-1}" = "0" ]; then
+      _hs_drain_why="disabled by SWITCHROOM_HINDSIGHT_DRAIN=0"
+    elif [ ! -f "$_hs_drain_script" ]; then
+      _hs_drain_why="no drain script at $_hs_drain_script (hindsight plugin not installed, or an interrupted \`switchroom apply\`)"
+    else
+      _hs_drain_why="python3 is not on PATH in this image"
+    fi
+    _hs_drain_msg="[hindsight-drain] NOT STARTED: ${_hs_drain_why}. The memory queue will only be drained at session boot, which cannot clear a backlog."
+    echo "$_hs_drain_msg"
+    mkdir -p /var/log/switchroom 2>/dev/null || true
+    echo "$_hs_drain_msg" >> /var/log/switchroom/hindsight-drain.log 2>/dev/null || true
   fi
 {{/if}}
 
@@ -594,6 +649,30 @@ if [ ! -e "$HOME/.switchroom-config" ] || [ -L "$HOME/.switchroom-config" ]; the
 fi
 {{/if}}
 
+# --- Commit attribution: global git hooks path ---------------------------
+#
+# Every commit an agent makes is AUTHORED by the operator's GitHub account
+# (deliberate, and staying that way), which leaves `git log` unable to say
+# WHICH agent and WHICH model produced a change. The image ships a
+# `prepare-commit-msg` hook that stamps `Switchroom-Agent:` /
+# `Switchroom-Model:` trailers from $SWITCHROOM_AGENT_NAME and the launched
+# model — see bin/git-agent-attribution-hook.sh for the full rationale
+# (including why prepare-commit-msg, which `--no-verify` does NOT bypass).
+#
+# Set GLOBALLY, not per-repo: an agent clones repos on demand and a per-repo
+# install would mean every new clone starts out unattributed until someone
+# remembered to run a setup step. Repo-local `core.hooksPath` (husky et al)
+# still wins, and the hook chains to any displaced `.git/hooks` copy.
+#
+# Idempotent, and non-fatal: attribution must never be the reason a boot
+# fails. `git config --global` writes $HOME/.gitconfig, which lives on the
+# /state/agent bind mount and so persists — re-asserting it each boot is what
+# repairs an agent whose config was hand-edited.
+if command -v git >/dev/null 2>&1 && [ -x /opt/switchroom/git-hooks/prepare-commit-msg ]; then
+  git config --global core.hooksPath /opt/switchroom/git-hooks 2>/dev/null \
+    || echo "attribution: WARNING — could not set core.hooksPath; commits from this agent will not carry Switchroom-Agent/Switchroom-Model trailers and will fail the repo's attribution lint" >&2
+fi
+
 export NVM_DIR="$HOME/.nvm"
 [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
 export PATH="$HOME/.bun/bin:$PATH"
@@ -825,6 +904,78 @@ export HINDSIGHT_RECALL_REQUEST_TIMEOUT_SECONDS={{hindsightRecallRequestTimeoutS
 # Observe `injected_own_bank_count` via `switchroom memory recall-log <agent>`.
 export HINDSIGHT_RECALL_OWN_BANK_MIN_SLOTS={{hindsightRecallOwnBankMinSlots}}
 export HINDSIGHT_RECALL_ADDITIONAL_BANK_MIN_SLOTS={{hindsightRecallAdditionalBankMinSlots}}
+# Absolute relevance floor on an injected memory's engine score (#3837).
+# 0 = OFF, and 0 is what switchroom ships: at 0 recall.py drops nothing and the
+# injected set is exactly what it was before #3837.
+# It exists for the measured failure where the agent's own bank times out and
+# recall injects side-bank residue under the "relevant memories" banner —
+# 98.4% of degraded turns carry a best injected score below 0.01 against 28.4%
+# of healthy ones, and the agent cannot tell noise from recall. SCOPE decides
+# which turns a non-zero floor binds on: `degraded` (default) only when the own
+# bank timed out / was unreachable, `all` on every turn. `all` is NOT a
+# recommended fleet default — an unconditional 0.01 floor empties ~28% of
+# HEALTHY recalls (#3761), because `scores.final` is not calibrated across
+# queries. EXPORTED UNCONDITIONALLY for the #3774 reason above: a stale
+# hand-edited ~/.hindsight/claude-code.json must not be able to switch a recall
+# filter ON that switchroom ships OFF.
+# Observe `dropped_below_min_score` via `switchroom memory recall-log <agent>`.
+export HINDSIGHT_RECALL_MIN_SCORE={{hindsightRecallMinScore}}
+export HINDSIGHT_RECALL_MIN_SCORE_SCOPE={{hindsightRecallMinScoreScope}}
+# ── The remaining recall knobs (#3841) ───────────────────────────────────────
+# Everything else `recall.py` reads out of the plugin config, resolved from
+# `memory.recall.*` in switchroom.yaml and exported UNCONDITIONALLY for the
+# #3774 reason spelled out above: `~/.hindsight/claude-code.json` loads AFTER
+# the plugin's settings.json and survives an apply, so a knob switchroom does
+# not export is a knob a stale hand-edit owns. Every default below is the value
+# the fleet already ran before this block existed — an operator who sets none of
+# these gets byte-identical recall — and each is pinned against the vendored
+# plugin by tests/scaffold.recall-passthrough.test.ts so the two cannot drift.
+# Structural values are single-quoted JSON; `_cast_env` parses them and, unlike
+# an empty export, actually ASSIGNS (an empty one is skipped and hands authority
+# straight back to claude-code.json).
+#
+# How hard Hindsight searches: low (vector only, ~1-2s) | mid (+LLM rerank,
+# ~5s measured) | high. Switchroom ships `low` — mid was the second-largest
+# contributor to perceived dead air after model TTFT.
+export HINDSIGHT_RECALL_BUDGET={{hindsightRecallPass.budget}}
+# Token budget for the injected block. The count cap (…MAX_MEMORIES) is the
+# other bound and the tighter of the two wins.
+export HINDSIGHT_RECALL_MAX_TOKENS={{hindsightRecallPass.maxTokens}}
+# Bias toward the synthesized `observation` tier, backfilling slots freed by
+# superseded raw facts. On by default (memory.recall.prefer_observations).
+export HINDSIGHT_RECALL_PREFER_OBSERVATIONS={{hindsightRecallPass.preferObservations}}
+# Recent human turns composed into the query, and the transcript roles they may
+# be drawn from. 2 turns so a bare follow-up ("and the port?") embeds with its
+# antecedent instead of recalling on the pronoun alone.
+export HINDSIGHT_RECALL_CONTEXT_TURNS={{hindsightRecallPass.contextTurns}}
+export HINDSIGHT_RECALL_ROLES={{{hindsightRecallPass.rolesQ}}}
+# Character bound on the composed query, applied BEFORE …QUERY_MAX_TOKENS
+# shapes it; truncation keeps the latest turn and drops oldest context first.
+export HINDSIGHT_RECALL_MAX_QUERY_CHARS={{hindsightRecallPass.maxQueryChars}}
+# Tail bytes read from the session transcript for that composition — the read
+# stays O(1) on a session log that can grow to many MB. 0 = whole file.
+export HINDSIGHT_RECALL_TRANSCRIPT_TAIL_BYTES={{hindsightRecallPass.transcriptTailBytes}}
+# The banner above injected memories. The agent reads this line as the
+# instruction for how to treat the block, so it is behaviour, not cosmetics.
+export HINDSIGHT_RECALL_PROMPT_PREAMBLE={{{hindsightRecallPass.promptPreambleQ}}}
+# Tag filters (upstream 962140eef port). Dormant by default and exported at
+# their no-op values — `[]` / `{}` fold to None in recall.py, so nothing is
+# filtered unless an operator sets memory.recall.tags / .tag_groups.
+export HINDSIGHT_RECALL_TAGS={{{hindsightRecallPass.tagsQ}}}
+export HINDSIGHT_RECALL_TAGS_MATCH={{hindsightRecallPass.tagsMatch}}
+export HINDSIGHT_RECALL_TAG_GROUPS={{{hindsightRecallPass.tagGroupsQ}}}
+export HINDSIGHT_RECALL_ADDITIONAL_BANK_FILTERS={{{hindsightRecallPass.additionalBankFiltersQ}}}
+# Per-tag score multipliers — a DOWN-RANK, never a drop. Carries switchroom's
+# `sidechain: 0.8` seed (delegated sub-agent memories rank just under
+# first-party ones), merged with memory.recall.tag_weights.
+export HINDSIGHT_RECALL_TAG_WEIGHTS={{{hindsightRecallPass.tagWeightsQ}}}
+# Bounded transcript-grep fallback: only when EVERY bank returned zero AND no
+# bank hit its deadline. Covers the window between an abrupt kill and the next
+# boot reconciliation, where the fact layer never heard about the lost turns.
+export HINDSIGHT_RECALL_TRANSCRIPT_FALLBACK={{hindsightRecallPass.transcriptFallback}}
+# Parallel multi-bank fan-out: total latency is the SLOWEST slot, not the SUM.
+# false is the serial rollback lever.
+export HINDSIGHT_RECALL_PARALLEL={{hindsightRecallPass.parallel}}
 # Recall fact types (memory.recall.types cascade). Switchroom default is
 # world,experience,observation (the synthesized `observation` tier is ON
 # by default, set in the plugin settings.json). Export only when the
@@ -1893,6 +2044,15 @@ esac
 # welcome card honest. Overwrite (not consumed) — the gateway reads it at boot.
 printf '%s\n' "$_EFFECTIVE_MODEL" > "{{agentDir}}/.active-session-model" 2>/dev/null || true
 
+# Commit-attribution carrier for the model half of the trailer pair. Exported
+# here, from the SAME $_EFFECTIVE_MODEL the session is about to launch on, so a
+# `/model` override is reflected in the trailer rather than the configured
+# default. `exec claude` below inherits it, and so does every shell claude
+# spawns — which is where `git commit` actually runs.
+# Consumer: bin/git-agent-attribution-hook.sh (falls back to the static
+# SWITCHROOM_AGENT_MODEL that compose.ts writes, then to "unknown").
+export SWITCHROOM_SESSION_MODEL="$_EFFECTIVE_MODEL"
+
 # --- Routing-mode observability (.routing-mode, 2026-07-17 boot-race incident) ---
 #
 # Deterministic record of WHERE this boot actually landed, written immediately

package/telegram-plugin/card-layout.ts

@@ -0,0 +1,328 @@
+/**
+ * Card layout core — the ONE place a status/progress card is composed.
+ *
+ * Every card the gateway paints (🤖 agent, 🛠 single worker, 🛠 WORKERS
+ * combined, and their overflow/terminal variants) is expressed as a
+ * {@link CardSpec}: fixed `chrome` lines, N `sections` (each an optional
+ * header plus a windowed `✓`/`→` step trail), and fixed `footer` lines. The
+ * renderers in `tool-activity-summary.ts` / `worker-activity-feed.ts` are
+ * CONFIGURATIONS of this module, not parallel implementations.
+ *
+ * Two things used to exist twice and agreed only by hand (#3844):
+ *
+ *   1. **Header composition.** The combined card built its own row header
+ *      instead of going through `renderActivityHeader`, so the metrics run
+ *      (`{elapsed} · {n} tools · {t} tok · {model}`) was written out in two
+ *      places. It is now composed exactly once, by {@link metricsRun}, which
+ *      the agent header, the worker header, the combined row header and the
+ *      combined glance line all read.
+ *   2. **Char-budget enforcement.** The combined card carried its own
+ *      row-shrinking loop instead of the status card's `fitCardToBudget`.
+ *      There is now exactly one budget enforcer — {@link fitCardToBudget} —
+ *      a generic "render at progressively deeper shrink levels, take the
+ *      first that fits" loop. Each card supplies what a shrink level MEANS
+ *      (drop the oldest bullet / drop the newest row); nothing else compares
+ *      a rendered card against `STATUS_CARD_CHAR_BUDGET`.
+ *
+ * Nothing in here knows about workers, turns, or Telegram transport — it is
+ * pure string composition, so a card variant can be rendered (and asserted)
+ * without any of the feed machinery.
+ */
+
+import { escapeMarkdown, stripMarkdown, truncate, stackCardLines } from './card-format.js'
+import { formatModelLabel } from './model-label.js'
+import { STATUS_CARD_CHAR_BUDGET, STATUS_LINE_MAX, STATUS_ROLLING_LINES } from './status-no-truncate.js'
+
+// ─── Metrics composition (the single header vocabulary) ─────────────────────
+
+/** Format elapsed milliseconds for display in the activity header (e.g. "12s", "2m05s"). */
+export function formatFeedElapsed(ms: number): string {
+  const s = Math.floor(ms / 1000)
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  return `${m}m${(s % 60).toString().padStart(2, '0')}s`
+}
+
+/**
+ * Compact token-count formatter for the activity card's metrics line:
+ *   <1000        → raw          ("940")
+ *   ≥1000, <1e6  → one-decimal k ("12.4k", "1.0k")
+ *   ≥1e6         → one-decimal M ("1.2M")
+ * Negative / non-finite inputs clamp to "0". The caller appends " tok".
+ */
+export function formatTokenCount(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) return '0'
+  if (n < 1000) return String(Math.floor(n))
+  if (n < 1_000_000) {
+    // Round to the displayed 1-decimal k FIRST: inputs in [999_950, 999_999]
+    // round to "1000.0k", which must promote into the M branch rather than
+    // render a nonsense "1000.0k". Fall through when the rounded k reaches 1000.
+    const k = Number((n / 1000).toFixed(1))
+    if (k < 1000) return `${k.toFixed(1)}k`
+  }
+  return `${(n / 1_000_000).toFixed(1)}M`
+}
+
+/**
+ * The ` · {N} tok` metrics segment, or '' when there are no tokens to show.
+ * A 0 / undefined total (a worker that emitted no usage — e.g. a non-Claude
+ * transcript) OMITS the segment entirely so the line stays clean; every card
+ * that shows tokens reads this one predicate so they never diverge.
+ */
+export function tokenSegment(totalTokens: number | undefined): string {
+  if (totalTokens == null || totalTokens <= 0) return ''
+  return ` · ${formatTokenCount(totalTokens)} tok`
+}
+
+/** `tool` / `tools`, pluralised once for every surface that prints a tool count. */
+export function toolWord(n: number): string {
+  return n === 1 ? 'tool' : 'tools'
+}
+
+/** Terminal/running state a card (or a row on it) can report. */
+export type CardState = 'running' | 'done' | 'failed' | 'incomplete'
+
+/**
+ * The metrics RUN — the dot-separated `{elapsed} · {n} tools · {t} tok · {model}`
+ * text that every card header carries, WITHOUT the italic wrapper (callers own
+ * the wrapper because they place the leading separator differently).
+ *
+ * This is the single composition point the audit (#3844) found forked: the
+ * combined card's row header spelled the same run out by hand, so a change to
+ * (say) token placement had to be made twice and agreed only by inspection.
+ *
+ * `running` puts elapsed FIRST (it is the live fact); a terminal state leads
+ * with the state word and moves elapsed to the tail, so a failed or reaped
+ * worker never reads as done.
+ */
+export function metricsRun(
+  elapsedMs: number,
+  toolCount: number,
+  state: CardState,
+  totalTokens?: number,
+  model?: string,
+): string {
+  const elapsed = formatFeedElapsed(elapsedMs)
+  const tokPart = tokenSegment(totalTokens)
+  const modelLabel = formatModelLabel(model)
+  const modelPart = modelLabel != null ? ` · ${escapeMarkdown(modelLabel)}` : ''
+  return state === 'running'
+    ? `${elapsed} · ${toolCount} ${toolWord(toolCount)}${tokPart}${modelPart}`
+    : `${state} · ${toolCount} ${toolWord(toolCount)}${tokPart} · ${elapsed}${modelPart}`
+}
+
+/**
+ * Line 1 of a card: `<emoji> <b>LABEL</b> · <i>description</i>` (description
+ * optional). Shared by the agent card, the worker card and the static
+ * superseded notice, so the card's type chrome is composed in one place.
+ */
+export function renderCardTitleLine(emoji: string, label: string, description: string): string {
+  const descPart = description.length > 0 ? ` · _${escapeMarkdown(description)}_` : ''
+  return `${emoji} **${escapeMarkdown(label)}**${descPart}`
+}
+
+/**
+ * Render a two-line header for an activity card.
+ *
+ * Line 1: `<emoji> <b>Label</b> · <i>description</i>`  (description optional)
+ * Line 2: the metrics run, italicised.
+ *
+ * Returns a two-element array of ready Telegram markdown lines (no trailing
+ * newline).
+ */
+export function renderActivityHeader(
+  emoji: string,
+  label: string,
+  description: string,
+  elapsedMs: number,
+  toolCount: number,
+  state: CardState,
+  model?: string,
+  totalTokens?: number,
+): [string, string] {
+  return [
+    renderCardTitleLine(emoji, label, description),
+    `_${metricsRun(elapsedMs, toolCount, state, totalTokens, model)}_`,
+  ]
+}
+
+// ─── Per-line truncation pipeline ───────────────────────────────────────────
+//
+// Per RAW line, in this EXACT order:
+//   1. stripMarkdown(raw)
+//   2. .replace(/\s+/g, ' ').trim()
+//   3. truncate(_, STATUS_LINE_MAX)
+//   4. escapeMarkdown(_)   ← escape is ALWAYS the last per-line op.
+// Escaping last is load-bearing: clipping an already-escaped string can split
+// a markdown escape (\* → \), which renders wrong.
+
+/** Clean + clip + escape a single raw step line. Returns ready-to-wrap markdown. */
+export function escapeStepLine(raw: string): string {
+  const cleaned = stripMarkdown(raw).replace(/\s+/g, ' ').trim()
+  return escapeMarkdown(truncate(cleaned, STATUS_LINE_MAX))
+}
+
+/** The cleaned (unescaped) form of a raw line — the input to `truncate`. */
+export function cleanStepLine(raw: string): string {
+  return stripMarkdown(raw).replace(/\s+/g, ' ').trim()
+}
+
+// ─── Card spec ──────────────────────────────────────────────────────────────
+
+/**
+ * How a FINISHED step bullet is drawn.
+ *   'struck' — `~~_✓ step_~~`, the normal card body.
+ *   'plain'  — `_step_`, used by the char-budget shrink levels where the
+ *              strike/✓ chrome is spent bytes on a card already over the wire
+ *              limit.
+ */
+export type DoneStyle = 'struck' | 'plain'
+
+/** One section of a card: an optional header plus a windowed step trail. */
+export interface CardSection {
+  /** Ready lines emitted above this section's steps (the combined row header). */
+  header?: string[]
+  /** ALREADY-ESCAPED step lines, oldest → newest. */
+  steps: string[]
+  /** Trailing steps shown; the remainder collapses to a `+N earlier…` marker. */
+  window: number
+  /** When true every step renders done — no live `→` bullet. */
+  allDone?: boolean
+  /** Heartbeat suffix rendered INSIDE the newest in-progress bullet. */
+  liveSuffix?: string
+  /**
+   * Literal prefix on EVERY line this section emits (marker, bullets,
+   * placeholder), OUTSIDE the markdown spans so it never lands inside an
+   * emphasis run.
+   */
+  indent?: string
+  /**
+   * Token before a done step and inside the overflow marker. `'✓ '` on a normal
+   * body; `''` for the `↳` nested-child block, whose `↳` glyph already marks it.
+   */
+  doneMark?: string
+  /** See {@link DoneStyle}. Default 'struck'. */
+  doneStyle?: DoneStyle
+  /** Emitted (with `indent`) when this section has no steps at all. */
+  placeholder?: string
+}
+
+/** A whole card, as fixed chrome + sections + fixed footer. */
+export interface CardSpec {
+  /** Lines above every section — the card header, or the combined glance line. */
+  chrome?: string[]
+  sections: CardSection[]
+  /** Lines below every section — `✓ N steps`, the result block, the spill line. */
+  footer?: string[]
+}
+
+/**
+ * Emit one section's lines into `out`. This is the single `✓`/`→` bullet
+ * emitter: every step line on every card comes through here.
+ */
+export function emitSection(out: string[], section: CardSection): void {
+  const indent = section.indent ?? ''
+  const doneMark = section.doneMark ?? '✓ '
+  const doneStyle = section.doneStyle ?? 'struck'
+  const allDone = section.allDone === true
+  const liveSuffix = section.liveSuffix ?? ''
+  if (section.header != null) out.push(...section.header)
+  if (section.steps.length === 0) {
+    if (section.placeholder != null) out.push(`${indent}${section.placeholder}`)
+    return
+  }
+  const shown = section.steps.slice(-Math.max(1, section.window))
+  const hidden = section.steps.length - shown.length
+  if (hidden > 0) out.push(`${indent}_${doneMark}+${hidden} earlier…_`)
+  const lastIdx = shown.length - 1
+  shown.forEach((s, i) => {
+    if (!allDone && i === lastIdx) {
+      out.push(`${indent}**→ ${s}${liveSuffix}**`)
+      return
+    }
+    out.push(doneStyle === 'plain' ? `${indent}_${s}_` : `${indent}~~_${doneMark}${s}_~~`)
+  })
+}
+
+/**
+ * Shared step-feed emitter (back-compat signature). Appends `✓`/`→` bullet
+ * lines to `out` for the given ALREADY-ESCAPED step strings. Thin wrapper over
+ * {@link emitSection}.
+ */
+export function renderStepFeed(
+  out: string[],
+  steps: string[],
+  allDone: boolean,
+  liveSuffix = '',
+  window: number = STATUS_ROLLING_LINES,
+  indent = '',
+): void {
+  emitSection(out, { steps, window, allDone, liveSuffix, indent })
+}
+
+/** Flatten a spec to its ordered card lines. */
+export function cardSpecLines(spec: CardSpec): string[] {
+  const out: string[] = [...(spec.chrome ?? [])]
+  for (const section of spec.sections) emitSection(out, section)
+  out.push(...(spec.footer ?? []))
+  return out
+}
+
+/**
+ * Join card lines with GFM hard breaks so the styled prose lines don't collapse
+ * onto one visual line in the rich-message renderer — see `stackCardLines`.
+ *
+ * `collapseSafe` is unconditional here: every card this module renders is a
+ * PINNED surface, and Telegram's pinned bar shows a pinned message collapsed to
+ * one line with the newlines dropped and nothing substituted (#3666).
+ */
+export function stackCard(lines: string[]): string {
+  return stackCardLines(lines, { collapseSafe: true })
+}
+
+/** Render a spec straight to wire text, with no budget enforcement. */
+export function renderCardSpec(spec: CardSpec): string {
+  return stackCard(cardSpecLines(spec))
+}
+
+// ─── The one char-budget enforcer ───────────────────────────────────────────
+
+/** One shrink level's rendered candidate. */
+export interface CardCandidate {
+  spec: CardSpec
+  /**
+   * An additional card-specific ceiling this candidate violates (the combined
+   * card's total body-line budget). A candidate that fits the char budget but
+   * sets this is still rejected, so both ceilings are enforced by one loop.
+   */
+  overflow?: boolean
+}
+
+/**
+ * THE char-budget backstop — the only place a rendered card is measured against
+ * `STATUS_CARD_CHAR_BUDGET`.
+ *
+ * `build(level)` renders the card at progressively deeper shrink levels
+ * (level 0 = the full card). The first level whose rendered text fits the
+ * budget and clears its own `overflow` flag wins; if even `maxLevel` does not
+ * fit, that deepest render is returned — a card is always emitted, never
+ * dropped.
+ *
+ * What a level MEANS is the caller's business and is genuinely card-specific:
+ * the status card drops its oldest bullet (and, at its deepest level, truncates
+ * an oversized newest bullet), while the combined card drops its newest worker
+ * row into `+M more working…`. The MECHANISM — render, measure, accept or go
+ * deeper — exists only here.
+ */
+export function fitCardToBudget(
+  build: (level: number) => CardCandidate,
+  maxLevel: number,
+): string {
+  let text = ''
+  for (let level = 0; level <= maxLevel; level++) {
+    const candidate = build(level)
+    text = renderCardSpec(candidate.spec)
+    if (candidate.overflow !== true && text.length <= STATUS_CARD_CHAR_BUDGET) return text
+  }
+  return text
+}