switchroom 0.19.18 → 0.19.22

package/profiles/_base/start.sh.hbs

@@ -195,11 +195,33 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
   # the child keeps appending to the same (now-empty) inode. Worst-case
   # race is a few log lines written between the cp and the truncate being
   # lost; acceptable for a debug trace log. Keeps at most ~2×cap on disk
-  # (live + one .1 generation). Cap + interval are env-overridable.
+  # (live + one .1 generation), and since #3596 that .1 is compressed on
+  # rotate and age-reaped, so it can't outlive its usefulness. Cap,
+  # interval, max-age and compression are all env-overridable.
   _switchroom_log_rotator() {
     local _logfile="$1"
     local _max="${SWITCHROOM_SIDECAR_LOG_MAX_BYTES:-52428800}"   # 50 MiB default
     local _interval="${SWITCHROOM_SIDECAR_LOG_ROTATE_INTERVAL_SEC:-300}"  # 5 min
+    # #3596: the `.1` generation was written once and then NEVER reaped.
+    # A log that grows fast during an incident and slowly afterwards keeps
+    # its giant `.1` forever — on the live host clerk/gateway-supervisor.log.1
+    # was 582 MB (dated Jul 11) while the live log sat at ~5 MB, i.e. months
+    # away from ever being overwritten by the next rotation. Two bounds:
+    #   * compress on rotate (gzip typically takes a text log to <10%), and
+    #   * an AGE bound — a `.1`/`.1.gz` older than this is deleted on the
+    #     next check even if no rotation happens.
+    # Be honest about what the age bound COSTS (#3600 review): right after
+    # a rotation the `.1` holds everything and the live log is empty, so
+    # if the agent then goes quiet for 14 days that history is DELETED
+    # while the near-empty live log survives. This is deliberate for a
+    # debug trace log — bounding shared host disk beats retaining stale
+    # traces — but it is deletion of the only copy, not merely eviction of
+    # a superseded backup. Raise SWITCHROOM_SIDECAR_LOG_ROTATE_MAX_AGE_SEC
+    # (or set it to 0 to disable the reaper) where that matters. Agent
+    # AUDIT trails are not affected: those are the hostd/vault logs, which
+    # rotate by count, never by age.
+    local _max_age_sec="${SWITCHROOM_SIDECAR_LOG_ROTATE_MAX_AGE_SEC:-1209600}"  # 14 days
+    local _compress="${SWITCHROOM_SIDECAR_LOG_COMPRESS:-1}"
     # Validate BOTH env overrides up front; garbage falls back to the
     # default. Unvalidated, a non-numeric interval makes `sleep` fail
     # instantly and the `while true` loop hot-spins a CPU core for the
@@ -208,12 +230,28 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
     # interval would also hot-spin, so it falls back too.
     case "$_max" in ''|*[!0-9]*) _max=52428800;; esac
     case "$_interval" in ''|0|*[!0-9]*) _interval=300;; esac
+    # Same garbage guard for the age bound; 0 disables the age reaper
+    # (the size-triggered overwrite still applies).
+    case "$_max_age_sec" in ''|*[!0-9]*) _max_age_sec=1209600;; esac
+    # `find -mmin` takes MINUTES; round up so a sub-minute age still reaps.
+    local _max_age_min=$(( (_max_age_sec + 59) / 60 ))
     # A cap of 0 disables rotation entirely (operator escape hatch).
     # (Negative values contain '-' → non-numeric per the guard above →
     # default cap, i.e. rotation stays on.)
     [ "$_max" -eq 0 ] && return 0
+    local _dir _base
+    _dir=$(dirname "$_logfile")
+    _base=$(basename "$_logfile")
     while true; do
       sleep "$_interval"
+      # Age-reap the retained generation first — this runs every cycle,
+      # INDEPENDENT of whether the live log is over cap, which is exactly
+      # the case the old code never handled (#3596).
+      if [ "$_max_age_min" -gt 0 ]; then
+        find "$_dir" -maxdepth 1 -type f \
+          \( -name "$_base.1" -o -name "$_base.1.gz" \) \
+          -mmin "+$_max_age_min" -exec rm -f {} + 2>/dev/null || true
+      fi
       [ -f "$_logfile" ] || continue
       local _size
       _size=$(wc -c < "$_logfile" 2>/dev/null || echo 0)
@@ -222,6 +260,13 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
       if [ "$_size" -gt "$_max" ]; then
         if cp "$_logfile" "$_logfile.1" 2>/dev/null; then
           : > "$_logfile"
+          # Drop any stale compressed generation, then (best-effort)
+          # compress the fresh one. gzip failing (missing binary, ENOSPC)
+          # just leaves the plain `.1` — never fatal.
+          rm -f "$_logfile.1.gz" 2>/dev/null || true
+          if [ "$_compress" != "0" ] && command -v gzip >/dev/null 2>&1; then
+            gzip -f "$_logfile.1" 2>/dev/null || true
+          fi
           echo "[supervise] rotated $_logfile (${_size} bytes > ${_max} cap) → ${_logfile}.1" >> "$_logfile"
         else
           # cp failed (e.g. ENOSPC — exactly when rotation matters most).
@@ -1104,6 +1149,21 @@ if [ -f /opt/switchroom/webkite/config.toml ]; then
   unset sr_wk_target
 fi
 
+# Shared cloakbrowser Chromium cache (#TBD). The image pins
+# CLOAKBROWSER_CACHE_DIR to /opt/switchroom/cloakbrowser-cache and
+# compose bind-mounts the operator's single ~/.switchroom/cloakbrowser/
+# copy RO onto it. If that mount didn't materialise the dir is empty and
+# root-owned, so cloakbrowser cannot silently re-download its own ~700MB
+# private copy (verified live: it aborts with `[Errno 13] Permission
+# denied` instead of extracting) — it only loses local render. Warn
+# loudly, never fatally: webkite still cloud-renders when the
+# Cloudflare/Firecrawl credentials are present.
+sr_cb_dir="${CLOAKBROWSER_CACHE_DIR:-/opt/switchroom/cloakbrowser-cache}"
+if ! ls -d "$sr_cb_dir"/chromium-*/ >/dev/null 2>&1; then
+  echo "WARNING (cloakbrowser shared cache): shared cloakbrowser Chromium missing at $sr_cb_dir — webkite local render unavailable (cloud render still works if Cloudflare/Firecrawl creds are set). On the host run: CLOAKBROWSER_CACHE_DIR=~/.switchroom/cloakbrowser cloakbrowser install && switchroom apply" >&2
+fi
+unset sr_cb_dir
+
 # LiteLLM routing (opt-in, #litellm). When SWITCHROOM_LITELLM is set (compose
 # env, gated on litellm.enabled && keyConfirmed), route the unmodified `claude`
 # CLI through the operator's LiteLLM proxy at ANTHROPIC_BASE_URL: fetch the

package/skills/switchroom-release/SKILL.md

@@ -12,7 +12,9 @@ Cut a release of `switchroom/switchroom` and get it live on the fleet. This is a
 
 - A release = a `vX.Y.Z` **git tag** on `main` (the merge commit of the CHANGELOG PR).
 - The tag is the version source of truth (`scripts/build.mjs:resolveVersion()`). `package.json` `version` is a **stale placeholder by design** — never bump it in a commit (the `//version` comment + #2733 discipline). The uncommitted pack-time bump happens in CI now, not by hand.
-- Cutting the tag fires TWO workflows in parallel on tag push: `docker-images` (builds + pushes the 6 ghcr images) and `npm-publish` (builds, packs, verifies, publishes to npm). **Rollout is gated on BOTH going green.**
+- Cutting the tag fires **two** workflows: `docker-images` (builds + pushes the 6 ghcr images) and `release` (the **orchestrator** — builds the four static binaries, attaches them, waits for `docker-images`, then calls `npm-publish`, then takes the GitHub Release out of draft).
+- **`npm-publish.yml` no longer has a tag trigger (#3654).** It is reachable only via `workflow_call` from `release.yml` and via `workflow_dispatch`. npm is the one leg that cannot be undone, so it runs last and only once everything else is green. It also re-proves both preconditions from inside its own run, so a hand dispatch cannot bypass the ordering either.
+- **The GitHub Release is created as a DRAFT and stays one until every leg is green.** `install.sh` resolves the version to install from `/releases/latest`, and that endpoint excludes drafts — so a half-finished release is invisible to `curl | sh` users and the previous complete release keeps serving them. This is not theoretical: v0.19.19 shipped published-with-zero-assets and broke the installer on every platform.
 
 ## Before you start — pre-flight (verify, don't assume)
 
@@ -28,30 +30,97 @@ Cut a release of `switchroom/switchroom` and get it live on the fleet. This is a
 - The release commit touches **CHANGELOG.md only**. Do NOT bump `package.json` (placeholder discipline).
 - Branch protection blocks direct push to `main`, so: create a `release/vX.Y.Z` branch, push it, open a `chore: release vX.Y.Z` PR (base `main`), arm auto-merge (squash, delete-branch) on green CI.
 
-## Step 2 — Cut the tag (on the merge commit, not the PR branch)
+## Step 2 — Create the DRAFT release on a PINNED SHA, then push the tag
 
-Once the changelog PR is merged:
-- `git fetch origin && git checkout main && git pull --ff-only`
-- Tag the merge commit and create the GitHub Release:
-  - `gh release create vX.Y.Z -R switchroom/switchroom --target main --title 'vX.Y.Z — <summary>' --notes-file <notes-file>`
+Once the changelog PR is merged. **Order matters, and so does the pin.**
+
+### 2a — Resolve and PIN the commit
+
+```bash
+git fetch origin
+SHA="$(git rev-parse origin/main)"
+git --no-pager log -1 --oneline "$SHA"    # show the operator exactly what is being released
+```
+
+**Never pass `--target main`.** `main` is resolved server-side at the moment the API call lands, and agents merge PRs in parallel here — a PR that merged in the seconds between your pre-flight check and your `gh release create` would be silently swallowed into the release. Resolve `$SHA` once, confirm it is the commit you inspected in pre-flight, and use that literal SHA everywhere below.
+
+### 2b — Create the release as a DRAFT
+
+```bash
+gh release create "vX.Y.Z" -R switchroom/switchroom \
+  --draft \
+  --target "$SHA" \
+  --title 'vX.Y.Z — <summary>' \
+  --notes-file <notes-file>
+```
+
+- **`--draft` is mandatory.** A published release with no assets immediately becomes `/releases/latest` and 404s every `curl | sh` install for the entire ~25-minute build window. `release.yml` will forcibly re-draft an incomplete published release within about a minute, but do not rely on the safety net — it exists for the case where this step was done wrong.
+- Creating the release object *before* the tag is what removes the race: `release.yml`'s `guard` job needs it to exist within ~150s of the tag push.
 - **Notes extraction gotcha (historical):** the naive `awk '/^## vX/,/^## v/' CHANGELOG` range collapses to a single line. Use a start-flag awk: `awk 'f{print} /^## vX\.Y\.Z/{print; f=1} f && /^## v/ && !/^## vX\.Y\.Z/{exit}'` — or extract the section to a temp file by line range.
-- **`gh release create` has been silently dropped in past runs.** After running it, verify: `gh release view vX.Y.Z` must return the release. If it didn't create, re-run.
+- **`gh release create` has been silently dropped in past runs.** Verify it exists and is a draft:
+  ```bash
+  gh release view vX.Y.Z -R switchroom/switchroom --json tagName,isDraft
+  ```
+  `gh` resolves drafts by tag name (it falls back to scanning the release list). Note the raw REST `GET /releases/tags/{tag}` does **not** — it 404s on a draft. That difference is why the workflow scripts use the list endpoint; don't "fix" them to use the by-tag endpoint.
 
-## Step 3 — Wait for BOTH tag-push workflows (hard gates)
+### 2c — Push the tag at that same pinned SHA
 
-The tag push triggers `docker-images` AND `npm-publish` in parallel. **Do not proceed to rollout until both are green AND verified.**
+GitHub does not create the tag ref for a *draft* release (it creates it on publish), so the tag push below is what actually starts the pipeline. Confirm that before pushing, because if the ref already existed at `$SHA` the push would be a silent no-op and **no workflow would fire**:
 
-### Gate A — npm publish (`npm-publish.yml`)
-- `gh run list --workflow=npm-publish.yml --limit 1` — wait for it to reach `completed` / `success`.
-- Verify the publish is live: `npm view switchroom version` must return `X.Y.Z` (not the old version). Retry a few times — npm registry propagation can lag a few seconds.
-- If this workflow fails: **the release is not published.** Do NOT roll. Diagnose (NPM_TOKEN unset? npm 5xx? empty dist?). Re-run via `gh workflow run npm-publish.yml --ref vX.Y.Z` after fixing.
+```bash
+git ls-remote --tags origin "refs/tags/vX.Y.Z"   # expect NO output
+git push origin "$SHA:refs/tags/vX.Y.Z"
+```
+
+Pushing the SHA-to-ref form rather than `git tag && git push --tags` guarantees the tag lands on the commit you pinned in 2a, not on whatever your local `main` happens to be. (If the ref *does* already exist at a different commit, the push is rejected — that is the safe direction. Do not force it; work out why first.)
+
+Then confirm both workflows actually started before you walk away:
+
+```bash
+gh run list -R switchroom/switchroom --branch vX.Y.Z --limit 5
+```
 
-### Gate B — docker images (`docker-images.yml`)
+You should see a `docker-images` run and a `release` run. If you see neither, the tag ref already existed and nothing fired.
+
+## Step 3 — Wait for the pipeline (two workflows, one of them orchestrated)
+
+The tag push triggers `docker-images` and `release`. `release` internally waits for `docker-images`, then publishes to npm, then un-drafts the GitHub Release. **Do not proceed to rollout until both are green AND verified.**
+
+### Gate A — docker images (`docker-images.yml`)
 - `gh run list --workflow=docker-images.yml --limit 1` — wait for `completed` / `success`.
-- Verify all 6 images are published: `docker manifest inspect ghcr.io/switchroom/<image>:vX.Y.Z` for `agent`, `auth-broker`, `kernel`, `broker`, `web`, `hostd`. Each must resolve.
-- If any image is missing: do NOT roll — the rollout canary version-assert fails on an unpublished tag. Wait + re-check.
+- Verify all 6 images are published. The repository name is `switchroom-<name>`, **not** `<name>` — `.github/workflows/docker-images.yml` builds `${REGISTRY}/${IMAGE_NAMESPACE}/switchroom-${{ matrix.image.name }}`, so `ghcr.io/switchroom/agent` does not exist and returns `manifest unknown`. Check each of:
+  ```bash
+  for n in agent auth-broker kernel broker web hostd; do
+    docker manifest inspect "ghcr.io/switchroom/switchroom-$n:vX.Y.Z" >/dev/null \
+      && echo "OK   switchroom-$n" || echo "MISS switchroom-$n"
+  done
+  ```
+  Each must resolve.
+- If any image is missing: do NOT roll — the rollout canary version-assert fails on an unpublished tag. Wait + re-check. `release` will block on this by itself, so a red image build means npm never publishes and the release never leaves draft. That is the design.
+
+### Gate B — the release pipeline (`release.yml`)
+- `gh run list --workflow=release.yml --limit 1` — wait for `completed` / `success`. Expect ~25-30 minutes: four native build legs plus the wait on `docker-images`.
+- Its jobs, in order: `guard` (release exists + held out of `latest`) → `build` ×4 → `bundle` → `publish` (attach) → `images-gate` (wait on docker-images) → `npm` → `finalize` (un-draft). A red job anywhere leaves the release a **draft** and npm **unpublished** — which is the correct, recoverable state.
+- Verify the release page actually has assets **and is no longer a draft**:
+  ```bash
+  gh release view vX.Y.Z -R switchroom/switchroom --json isDraft,assets \
+    --jq '{isDraft, assets: [.assets[].name]}'
+  ```
+  `isDraft` must be `false`, and `assets` must list all four binaries (`switchroom-{linux,macos}-{amd64,arm64}`) **and** `switchroom-checksums.txt`. This is the gate that did not exist through v0.19.19 — every release up to then shipped **zero** assets and the advertised `curl | sh` installer (`install.sh`) was dead on every platform (#3633).
+- Confirm the installer's own resolution path agrees:
+  ```bash
+  gh api repos/switchroom/switchroom/releases/latest --jq '{tag_name, assets: [.assets[].name]}'
+  ```
+  This is literally what `install.sh` calls. If it still reports the previous version, `finalize` did not run.
+
+### Gate C — npm publish
+- npm is published by the `npm` job **inside** the `release` run, not by a separate workflow run. `gh run list --workflow=npm-publish.yml` will show nothing new for a normal release — that is expected, not a failure.
+- Verify the publish is live: `npm view switchroom version` must return `X.Y.Z` (not the old version). Retry a few times — npm registry propagation can lag a few seconds.
+
+**Only when Gates A, B AND C are green + verified** do you proceed.
 
-**Only when Gate A AND Gate B are green + verified** do you proceed.
+### Rehearsing a workflow change without releasing anything
+`gh workflow run release.yml --ref <branch>` — `dry_run` defaults to `true`, so it builds, checksums and verifies the full bundle and attaches it as a workflow artifact, touching no GitHub Release, no npm, and no image tags. This is the only supported way to prove a change to the release pipeline before a real tag.
 
 ## Step 4 — Fleet rollout (operator-gated, canary-first)
 
@@ -63,14 +132,28 @@ The tag push triggers `docker-images` AND `npm-publish` in parallel. **Do not pr
 
 - **Never bump `package.json` `version` in a commit.** It's a stale placeholder; the tag is the source of truth and `npm-publish.yml` does the uncommitted pack-time bump.
 - **Never run `npm publish` by hand from the agent container.** You can't reach the operator's npm auth, and the workflow is the reliable path. If the workflow is broken, fix the workflow — don't side-step it.
-- **Never roll the fleet before Gate A (npm) AND Gate B (images) are both green + verified.** A release that's on the fleet but not on npm is the exact regression this skill exists to prevent.
+- **Never create the GitHub Release without `--draft`,** and **never `gh release create --target main`.** Pin the SHA (step 2a).
+- **Never take the release out of draft by hand** while the pipeline is still running. `finalize` is the only thing that should publish it; un-drafting early puts an incomplete release on `/releases/latest` and breaks every installer.
+- **Never roll the fleet before Gates A, B AND C are green + verified.** A release that's on the fleet but not on npm is the exact regression this skill exists to prevent.
 - **Never push directly to `main`.** The CHANGELOG PR goes through auto-merge on green.
 - **Never force-push `main` or bypass hooks (`--no-verify`).**
 
 ## If something goes wrong
 
-- **npm-publish failed but the tag is already pushed:** fix + `gh workflow run npm-publish.yml --ref vX.Y.Z`. Do NOT roll until it's green + `npm view` confirms.
-- **Images failed but npm succeeded:** the npm package is live but the fleet can't roll yet. Fix the image workflow / re-run. (npm being ahead of images is fine — the CLI is published for npm consumers; the fleet waits on images.)
+**The single recovery command for almost everything is a re-dispatch of the orchestrator:**
+
+```bash
+gh workflow run release.yml -R switchroom/switchroom --ref vX.Y.Z -f dry_run=false
+```
+
+It re-runs every leg — including `finalize`, which is what actually takes the release out of draft. Re-running one leg on its own generally leaves the release stuck as a draft.
+
+**But a re-dispatch cannot fix a defect that lives in the tag's own tree.** `workflow_dispatch` executes the workflow YAML **at the dispatched ref**, so `--ref vX.Y.Z` re-runs the same broken file and fails identically, every time. This is not theoretical — it is how v0.19.20 died (#3691). Before reaching for the re-dispatch, root-cause the failure in the workflow source **at that tag** (`git show vX.Y.Z:.github/workflows/release.yml`) and compare it to `main`. If the bug is in the tag's tree, the only path is a fix merged to `main` plus a **fresh tag**; abandon the old tag as a permanent draft (do not delete it, do not hand-publish it) and burn a patch version. Re-dispatch is for *transient* failures — a flaky runner, an npm 5xx, a `docker-images` run that has since gone green.
+
+- **`release` failed at `guard` ("no GitHub Release exists"):** step 2b was skipped or the tag name is misspelled. Create the draft release, then re-dispatch as above.
+- **`release` failed at `images-gate`:** `docker-images` was not green for this tag+commit. Fix it, `gh workflow run docker-images.yml --ref vX.Y.Z`, wait for green, then re-dispatch `release.yml`. Nothing was published to npm and the release is still a draft — nothing to undo.
+- **`release` failed at `npm` (e.g. a transient npm 5xx):** re-dispatch `release.yml` as above. `npm-publish` treats "already published" as success, so a re-run is safe and idempotent. Dispatching `npm-publish.yml --ref vX.Y.Z` directly also works and its own gates still apply, but it will NOT un-draft the release, so you would then have to re-dispatch `release.yml` anyway.
+- **Everything is green but the release is still a draft:** `finalize` did not run. Check `gh run view <run-id>` for a skipped job, then re-dispatch. Do not hand-publish — `finalize` re-verifies the asset set immediately before flipping the flag.
 - **Rollout started before publish verified (the old bug):** abort the rollout, publish, then re-roll. Do not let a half-published release sit on the fleet.
 
 ## Operator one-time setup (tell them once, not every release)

package/telegram-plugin/bridge/bridge.ts

@@ -133,6 +133,20 @@ const TOOL_SCHEMAS = [
       required: ['chat_id', 'text'],
     },
   },
+  {
+    name: 'progress_update',
+    description:
+      'Post a short interim progress line to Telegram mid-task ("still working through X"). Sends a NEW plain message to the chat — it is not an edit and not a card row, so use it sparingly and only when the user genuinely benefits from knowing where a long task stands. The gateway enforces its own limits: text is truncated at 300 chars, at most one update per 20s per chat+thread, and at most 5 per turn; over-limit calls return {ok:false, reason:"too_soon"|"turn_limit"} instead of sending. Prefer edit_message when you already own a message to update, and always deliver the actual answer with reply.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Chat to post the progress line in — pass chat_id from the inbound message.' },
+        text: { type: 'string', description: 'The progress line. One short sentence; truncated at 300 chars by the gateway.' },
+        message_thread_id: { type: 'string', description: 'Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified.' },
+      },
+      required: ['chat_id', 'text'],
+    },
+  },
   {
     name: 'react',
     description: 'Add an emoji reaction to a Telegram message. Telegram only accepts a fixed whitelist (👍 👎 ❤ 🔥 👀 🎉 etc) — non-whitelisted emoji will be rejected.',

package/telegram-plugin/card-format.ts

@@ -38,6 +38,69 @@ import { normalizeDashes } from './text-voice-scrub.js'
  */
 export { escapeMarkdown, codeSpanSafe }
 
+/**
+ * Separator appended to every card line that is followed by a hard break when
+ * `stackCardLines` runs in `collapseSafe` mode (#3666).
+ *
+ * It is a NO-BREAK SPACE (U+00A0), chosen deliberately:
+ *
+ *   - It is a real character in the message text, so it survives Telegram's
+ *     pinned-bar collapse (which drops the `\n` and substitutes nothing) and
+ *     keeps the two lines' glyphs apart in the one-line preview.
+ *   - It is NOT ASCII whitespace, so neither this module's own
+ *     trailing-whitespace strip nor the GFM parser's hard-break handling
+ *     (which consumes only the ASCII spaces immediately before the newline)
+ *     can eat it.
+ *   - It is invisible where the card is normally read — the chat feed — since
+ *     it lands at end-of-line. That is the whole reason a separator with
+ *     visible ink (`' ·'`, `' —'`) was rejected: it would put dangling
+ *     punctuation on every line of every pinned card to fix a defect that only
+ *     manifests on the pin bar.
+ *
+ * If a real-pin eyeball shows a single space is too weak a break, this constant
+ * is the one place to strengthen it (e.g. `' ·'`) — the seam is deliberate.
+ */
+export const COLLAPSE_SAFE_SEPARATOR = '\u00A0'
+
+/**
+ * Normalise a line's tail before `stackCardLines` re-terminates it.
+ *
+ * Two strips, both there for the SAME reason: this function must be idempotent,
+ * so re-stacking an already-stacked body can never accumulate terminator
+ * characters.
+ *
+ *   - trailing ASCII whitespace, so exactly one `  \n` hard break is emitted;
+ *   - in `collapseSafe` mode, any `COLLAPSE_SAFE_SEPARATOR` run the line
+ *     already carries (interleaved with ASCII whitespace, since a caller may
+ *     have split the body on `\n` rather than on `  \n`), so exactly one
+ *     separator is emitted.
+ *
+ * The separator strip is written against the CONSTANT, not against a hardcoded
+ * U+00A0, so it stays correct if the separator is ever strengthened to visible
+ * ink. That one-constant seam is what COLLAPSE_SAFE_SEPARATOR's own doc comment
+ * promises, and it would be a lie if this strip did not follow it.
+ */
+function normalizeLineTail(line: string, collapseSafe: boolean): string {
+  let out = line.replace(/[ \t\r]+$/, '')
+  // The length guard is not defensive noise: `''.endsWith('')` is true and
+  // `''.slice(0, -0)` is `''`, so an empty separator would spin this loop
+  // forever — a hang in the gateway's render path. The doc comment above the
+  // constant invites future edits to it, so make that edit unable to hang.
+  if (!collapseSafe || COLLAPSE_SAFE_SEPARATOR.length === 0) return out
+  while (out.endsWith(COLLAPSE_SAFE_SEPARATOR)) {
+    out = out.slice(0, -COLLAPSE_SAFE_SEPARATOR.length).replace(/[ \t\r]+$/, '')
+  }
+  return out
+}
+
+/** Options for `stackCardLines`. */
+export interface StackCardLinesOpts {
+  /** Append `COLLAPSE_SAFE_SEPARATOR` to each hard-broken line so the stack
+   *  stays readable on a surface that collapses it to one line (#3666).
+   *  Opt-in: only pinned cards pay the (tiny) extra character per line. */
+  collapseSafe?: boolean
+}
+
 /**
  * Join a card's pre-rendered, single-line entries so they STACK in the
  * Bot API 10.1 rich-message renderer (#2669) — the same visual result the
@@ -63,8 +126,19 @@ export { escapeMarkdown, codeSpanSafe }
  * This is the card-surface analogue of the reply path's
  * `normalizeParagraphBreaks`: it guarantees a card authored as stacked
  * bullet/step lines renders identically to a normal reply.
+ *
+ * `opts.collapseSafe` (#3666) additionally makes the stack survive being
+ * rendered on a surface that COLLAPSES the message to one line — Telegram's
+ * pinned-message bar drops the newlines and substitutes nothing, mashing the
+ * last glyph of each line into the first glyph of the next
+ * (`… · opus 5✓ Reading gateway.ts→ Running search …`). Opt-in, because it is
+ * only correct for cards that are actually pinned; see COLLAPSE_SAFE_SEPARATOR.
  */
-export function stackCardLines(lines: string[]): string {
+export function stackCardLines(
+  lines: string[],
+  opts?: StackCardLinesOpts,
+): string {
+  const collapseSafe = opts?.collapseSafe === true
   const pieces: string[] = []
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]
@@ -75,12 +149,27 @@ export function stackCardLines(lines: string[]): string {
     // A blank current or next line is a genuine `\n\n` paragraph gap — leave
     // the separator a plain newline so the blank entry reconstructs the gap.
     if (cur === '' || next === '') {
+      // The gap still needs a collapse separator when THIS line has content:
+      // a collapsing surface drops the `\n\n` with no substitute exactly as it
+      // drops a `  \n`, and the blank entry is the empty string, so it
+      // contributes NO character of its own to hold the two sides apart. Only
+      // when `cur` is blank is the separator skipped — appending it to a blank
+      // entry would turn the gap into a visible U+00A0 paragraph in the FEED.
+      if (collapseSafe && cur !== '') {
+        pieces[pieces.length - 1] = normalizeLineTail(line, true) + COLLAPSE_SAFE_SEPARATOR
+      }
       pieces.push('\n')
       continue
     }
     // Strip any trailing whitespace the line already carried so we emit
-    // exactly one `  \n` hard break (never accumulate spaces on a re-run).
-    pieces[pieces.length - 1] = line.replace(/[ \t\r]+$/, '')
+    // exactly one `  \n` hard break (never accumulate spaces on a re-run) and,
+    // under collapseSafe, exactly one separator — see normalizeLineTail.
+    // The collapse separator is appended AFTER the strip (it is not ASCII
+    // whitespace, so it survives both this strip and the markdown parser's
+    // own trailing-whitespace handling) and BEFORE the two hard-break spaces,
+    // which stay immediately adjacent to the `\n` so the break still parses.
+    pieces[pieces.length - 1] =
+      normalizeLineTail(line, collapseSafe) + (collapseSafe ? COLLAPSE_SAFE_SEPARATOR : '')
     pieces.push('  \n')
   }
   return pieces.join('')

package/telegram-plugin/dist/bridge/bridge.js

@@ -25004,6 +25004,19 @@ var TOOL_SCHEMAS = [
       required: ["chat_id", "text"]
     }
   },
+  {
+    name: "progress_update",
+    description: 'Post a short interim progress line to Telegram mid-task ("still working through X"). Sends a NEW plain message to the chat \u2014 it is not an edit and not a card row, so use it sparingly and only when the user genuinely benefits from knowing where a long task stands. The gateway enforces its own limits: text is truncated at 300 chars, at most one update per 20s per chat+thread, and at most 5 per turn; over-limit calls return {ok:false, reason:"too_soon"|"turn_limit"} instead of sending. Prefer edit_message when you already own a message to update, and always deliver the actual answer with reply.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat_id: { type: "string", description: "Chat to post the progress line in \u2014 pass chat_id from the inbound message." },
+        text: { type: "string", description: "The progress line. One short sentence; truncated at 300 chars by the gateway." },
+        message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified." }
+      },
+      required: ["chat_id", "text"]
+    }
+  },
   {
     name: "react",
     description: "Add an emoji reaction to a Telegram message. Telegram only accepts a fixed whitelist (\uD83D\uDC4D \uD83D\uDC4E \u2764 \uD83D\uDD25 \uD83D\uDC40 \uD83C\uDF89 etc) \u2014 non-whitelisted emoji will be rejected.",