switchroom 0.19.19 → 0.19.23

package/skills/dev-protocol/SKILL.md

@@ -13,51 +13,14 @@ description: >
 
 # Development Protocol — the playbook
 
-The always-loaded CLAUDE.md "Development Protocol" section is the summary.
-This skill is the long-form procedure. Work through the five phases in order;
-they are checkpoints, not vibes.
-
-## 1. Orient — ground before you build
-
-Before forming any theory or plan:
-
-- **Read the real source.** The repo's source files at the current HEAD — not
-  build artifacts (`dist/`, generated files, caches), not your memory of the
-  code, not the task description's paraphrase. If a claim matters, open the
-  file.
-- **Verify the root cause, not the first plausible cause.** Reproduce or trace
-  the failure to a specific mechanism before fixing. "This line looks wrong"
-  is a lead; the fix ships only when you can say *why* it produced the
-  observed symptom.
-- **Report contradicting evidence.** If what you find contradicts the task
-  description, the ticket, or your own working theory — say so explicitly and
-  stop to re-plan. Never force-fit evidence to the plan you already had.
-- **Cite everything.** Claims about the codebase carry `file:line`, commit
-  hashes, or PR numbers. "The scaffold appends fragments at
-  `src/agents/scaffold.ts:4113`" is a claim; "the scaffold appends fragments
-  somewhere" is not.
-
-## 2. Clarify vs proceed
-
-- **Infer first.** Most questions are answerable from the codebase, git
-  history, existing tests, or docs. Exhaust those before asking.
-- **One question at a time.** If genuinely unsure after inferring, ask the
-  single question whose answer unblocks the most work. Phrase it as a
-  decision with a default: state what you found, the 2–3 viable options, which
-  you'd pick and why, and ask for confirmation — e.g. *"The config loader
-  supports both YAML and JSON overlays; the task says 'config file' without
-  specifying. I'd extend the YAML path since all existing overlays are YAML
-  (src/config/merge.ts:88) — confirm, or should JSON be covered too?"* Never
-  send a questionnaire.
-- **Phase discipline.** Clarify during *planning*. Once the plan is agreed,
-  execute autonomously: make the reasonable call on small ambiguities, record
-  the assumption in your report, and keep moving. Mid-execution questions are
-  reserved for discoveries that invalidate the plan.
-
-## 3. Design-align on larger tasks
-
-**Classify the task first.** Treat it as "larger" (design-align before
-implementing) when ANY of these hold:
+The always-loaded CLAUDE.md "Development Protocol" section carries the
+judgement criteria. This skill carries the parts that are *this fleet's
+specific opinion* — the ones you would get wrong by defaulting to generic
+good practice, because our answer differs from the obvious one.
+
+## 1. Is this a "larger" task? (decides whether you design-align first)
+
+Treat it as larger — design report before implementing — when ANY of these hold:
 
 - It changes a public interface, schema, config shape, or on-disk format.
 - It cuts across 3+ modules or touches a load-bearing invariant.
@@ -67,65 +30,85 @@ implementing) when ANY of these hold:
   ("add flag Y").
 - It will land as more than one PR.
 
-Small, single-concern, obvious-approach changes skip straight to phase 4.
-
-For larger tasks:
-
-1. **Design report before code.** Send the user an evidence-grounded report:
-   what exists today (with citations), what will change, the chosen approach
-   and its rejected alternatives, and the PR staging plan. Get alignment
-   before implementation.
-2. **Red-team your own plan adversarially.** Review the design item by item.
-   Each item gets a verdict — `SOUND`, `RISK`, or `WRONG` — backed by
-   evidence (a file you read, a test you ran, a documented behavior), not
-   intuition. Fix every `WRONG` and address every `RISK` before starting.
-3. **Stage delivery as focused single-concern PRs.** One concern per PR:
-   reviewable in one sitting, revertable in one command. Never bundle a
-   refactor with a behavior change.
-
-## 4. Pipeline — how a change ships
-
-1. **Branch off fresh main.** `git fetch && git checkout -b <branch> origin/main`.
-2. **Implement with durable fixes.** Fix root causes. A workaround is
-   acceptable only with an explicit reason stated and a follow-up filed.
-   Prefer deterministic mechanisms (a check, a hook, a schema, a lint gate)
-   over model-dependent behavior — if code can enforce the guarantee, don't
-   leave it to prompt discipline.
-3. **Tests assert outcomes.** Every test must fail if the bug it guards
-   returns. A test that merely exercises the code path without asserting the
-   observable outcome is not a test.
-4. **Scoped tests + lint locally.** Run the test files covering what you
-   touched, plus the repo's lint gate. Local runs are a fast filter; **CI is
-   the full-suite authority** — never claim done off a local run alone.
-5. **Adversarial review of the diff.** Dispatch a reviewer (sub-agent or
-   fresh pass) with this structure:
-   - Input: the full diff, the task statement, and the design report if one
-     exists.
-   - Charge: *find reasons this change is wrong* — correctness, missed edge
-     cases, untested behavior, inconsistency with surrounding code, docs
-     drift, security/data-loss risk.
-   - Output: a findings list, each with severity (high/medium/low), the
-     evidence (`file:line`), and a concrete fix.
-6. **Fix ALL findings — including lows.** A low you skip is a bug you
-   shipped. If a finding is genuinely invalid, rebut it with evidence in
-   writing; silence is not a rebuttal.
-7. **Re-review the fix.** The re-review verdict must contain, per original
-   finding: the finding ID, what changed (`file:line` of the fix), whether it
-   fully resolves the finding (`RESOLVED` / `PARTIAL` / `REBUTTED` with
-   evidence), and whether the fix introduced anything new. A bare "fixed" is
-   not a verdict.
-8. **Merge only on CI green.** No exceptions. A red or flaky CI run is a
-   blocker to investigate, not to override.
-
-## 5. Communicate while you work
-
-- **Consolidated messages.** Batch related findings and results into one
-  substantive update; never send five fragments where one message serves.
-- **Always-visible progress.** Long-running work surfaces status the user can
-  see (progress card, interim edit, explicit "still running: X"). Never go
-  dark mid-task.
-- **No foreground watches over 30 seconds.** Anything longer — builds, CI
-  waits, deploys — runs in the background with a notification on completion.
-  Don't block a turn polling.
-- **Max 15 parallel sub-agents.** Fan out for genuinely parallel work
-  (independent reviews, independent modules), but cap the swarm at 15.
+Small, single-concern, obvious-approach changes skip straight to the pipeline.
+Design-aligning a one-liner is its own failure mode.
+
+## 2. Design report + red-team (larger tasks only)
+
+The report states what exists today **with citations**, what will change, the
+chosen approach, the alternatives you rejected and why, and the PR staging
+plan. Get alignment before implementing.
+
+Then red-team your own plan item by item. Each item gets a verdict —
+`SOUND`, `RISK`, or `WRONG` — backed by evidence you can point at (a file you
+read, a test you ran, documented behaviour), not intuition. Fix every `WRONG`
+and address every `RISK` before starting. A red-team that returns all-`SOUND`
+on a non-trivial plan is a red-team you didn't actually do.
+
+## 3. Ask one question, as a decision with a default
+
+If you're genuinely blocked after inferring from code and history, don't send
+a questionnaire. State what you found, the 2–3 viable options, which you'd
+pick and why, and ask for confirmation:
+
+> "The config loader supports both YAML and JSON overlays; the task says
+> 'config file' without specifying. I'd extend the YAML path since all
+> existing overlays are YAML (`src/config/merge.ts:88`) — confirm, or should
+> JSON be covered too?"
+
+Clarify during *planning*. Once the plan is agreed, execute autonomously:
+make the reasonable call on small ambiguities, record the assumption in your
+report, keep moving. Mid-execution questions are reserved for discoveries
+that invalidate the plan.
+
+## 4. Adversarial review — bounded on purpose
+
+Dispatch the review to a **fresh** pass or sub-agent; the coder cannot review
+its own work in-context. Structure it:
+
+- **Input:** the full diff, the task statement, and the design report if one exists.
+- **Charge:** *find reasons this change is wrong* — correctness, missed edge
+  cases, untested behaviour, inconsistency with surrounding code, docs drift,
+  security or data-loss risk.
+- **Output:** a findings list, each with a severity, the evidence (`file:line`),
+  and a concrete fix.
+
+**The severity gate — this is the fleet-specific part.** The old rule was
+"fix ALL findings including lows, then re-review". That is a loop generator by
+construction: an adversarial reviewer always surfaces lows (that is its job),
+fixing lows produces a new diff, and a new diff earned another re-review. It
+produced PRs going four rounds where the last round's only finding was an
+inaccurate doc comment. So:
+
+- **Blockers and mediums block the merge.** Fix them.
+- **Lows do NOT block.** Fix a low inline only if it's a genuine one-liner;
+  otherwise **file a follow-up issue and merge**. Filing is mandatory — an
+  unfiled low is a dropped bug, and there is no human team to catch it later.
+- **A re-review is earned only by a behavioural fix.** A docs-, comment-,
+  log-, or test-only fix commit does not earn another pass.
+- **Two rounds is the cap.** Prefix every commit answering a review round
+  `review-fix:` — `scripts/check-review-rounds.mjs` counts them and the
+  `review-rounds` check fails past two, unless a `review-cap-override` label
+  is on the PR.
+
+If a finding is genuinely invalid, rebut it with evidence in writing; silence
+is not a rebuttal.
+
+When you do re-review, the verdict states per original finding: the finding
+ID, what changed (`file:line` of the fix), whether it fully resolves the
+finding (`RESOLVED` / `PARTIAL` / `REBUTTED` with evidence), and whether the
+fix introduced anything new. A bare "fixed" is not a verdict.
+
+## 5. Non-obvious pipeline rules
+
+- **CI is the full-suite authority.** Local scoped tests are a fast filter,
+  never the merge evidence. Never claim done off a local run alone.
+- **A test that wouldn't fail on the bug it guards is not a test.** Assert the
+  observable outcome, not that the code path executed.
+- **Prefer a deterministic mechanism over prompt discipline.** If a check, a
+  hook, a schema, or a lint gate can enforce the guarantee, write that instead
+  of a convention — conventions demonstrably fail here.
+- **Never go dark, and never foreground-watch over 30 seconds.** Builds, CI
+  waits, and deploys run in the background with a notification. Batch related
+  findings into one substantive update rather than five fragments. Cap
+  parallel sub-agents at 15.

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/bunfig.toml

@@ -0,0 +1,10 @@
+# bun test configuration for runs whose CWD is telegram-plugin/ — CI's
+# `bun-test-run` job (scripts/bun-test-ci.sh) and `bun run --cwd telegram-plugin`.
+#
+# bun reads the bunfig.toml in its CWD only, so this file exists purely to load
+# the same state-dir hermeticity preload as the repo-root bunfig.toml. Keep the
+# two in sync; `npm run lint:agent-state-dir-hermeticity` fails if either stops
+# loading the guard. Rationale for the guard itself lives in
+# tests/vitest-setup/agent-state-dir-guard.mjs.
+[test]
+preload = ["../tests/vitest-setup/agent-state-dir-guard.mjs"]

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('')