switchroom 0.19.19 → 0.19.22

package/dist/host-control/main.js

@@ -21120,7 +21120,7 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.19.19";
+var VERSION = "0.19.22";
 
 // src/cli/agent-config.ts
 import { join as join2 } from "node:path";
@@ -21172,6 +21172,47 @@ for (const name of SHARED_FRAGMENTS) {
   }
 }
 
+// src/litellm/timeout-budget.ts
+var LITELLM_ROUTER_MARGIN_S = 10;
+var LITELLM_TIMEOUT_TIERS = {
+  interactive: {
+    group: "gpt-oss-20b",
+    localTimeoutS: 90,
+    fallbackGroup: "gpt-oss-20b-openrouter",
+    fallbackTimeoutS: 60
+  },
+  retain: {
+    group: "gpt-oss-20b-retain",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-retain-openrouter",
+    fallbackTimeoutS: 90
+  },
+  consolidation: {
+    group: "gpt-oss-20b-consolidation",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-consolidation-openrouter",
+    fallbackTimeoutS: 90
+  }
+};
+function litellmChainSeconds(tier) {
+  assertPositive(tier.localTimeoutS, `${tier.group} localTimeoutS`);
+  if (tier.fallbackGroup === null)
+    return tier.localTimeoutS;
+  assertPositive(tier.fallbackTimeoutS, `${tier.fallbackGroup} fallbackTimeoutS`);
+  return tier.localTimeoutS + tier.fallbackTimeoutS;
+}
+function minimumClientBudgetSeconds(tier, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return litellmChainSeconds(tier) + marginS;
+}
+function clientBudgetSeconds(tier, floorS = 0, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return Math.max(Math.ceil(floorS), minimumClientBudgetSeconds(tier, marginS));
+}
+function assertPositive(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`litellm timeout budget: ${label} must be a positive number, got ${value}`);
+  }
+}
+
 // src/setup/hindsight.ts
 var HINDSIGHT_DEFAULT_API_PORT = 18888;
 var HINDSIGHT_DEFAULT_MCP_URL = `http://127.0.0.1:${HINDSIGHT_DEFAULT_API_PORT}/mcp/`;
@@ -21181,6 +21222,18 @@ var HINDSIGHT_IMAGE_REPO = "ghcr.io/switchroom/switchroom-hindsight";
 var HINDSIGHT_IMAGE = `${HINDSIGHT_IMAGE_REPO}:latest`;
 var HINDSIGHT_BROKER_SOCK_VOLUME = `auth-broker-${HINDSIGHT_CONSUMER_NAME}-sock`;
 var HINDSIGHT_CREDS_MIRROR_VOLUME = `consumer-creds-${HINDSIGHT_CONSUMER_NAME}`;
+var HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 16384;
+var HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND = 80.6;
+function hindsightRetainLlmTimeoutSeconds(maxCompletionTokens = HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS, tokensPerSecond = HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND) {
+  if (!(maxCompletionTokens > 0) || !(tokensPerSecond > 0)) {
+    throw new Error(`hindsight retain budget: maxCompletionTokens (${maxCompletionTokens}) and ` + `tokensPerSecond (${tokensPerSecond}) must both be positive`);
+  }
+  return Math.ceil(maxCompletionTokens / tokensPerSecond);
+}
+function hindsightRetainClientTimeoutSeconds() {
+  return clientBudgetSeconds(LITELLM_TIMEOUT_TIERS.retain, hindsightRetainLlmTimeoutSeconds());
+}
+var HINDSIGHT_RETAIN_CLIENT_DEADLINE_S = hindsightRetainClientTimeoutSeconds() + LITELLM_ROUTER_MARGIN_S;
 var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.request.urlopen("http://localhost:8888/health",timeout=4).getcode()==200 else 1)';
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 var DOCKER_PROBE_TIMEOUT_MS = 60 * 1000;

package/dist/vault/approvals/kernel-server.js

@@ -19147,6 +19147,47 @@ for (const name of SHARED_FRAGMENTS) {
   }
 }
 
+// src/litellm/timeout-budget.ts
+var LITELLM_ROUTER_MARGIN_S = 10;
+var LITELLM_TIMEOUT_TIERS = {
+  interactive: {
+    group: "gpt-oss-20b",
+    localTimeoutS: 90,
+    fallbackGroup: "gpt-oss-20b-openrouter",
+    fallbackTimeoutS: 60
+  },
+  retain: {
+    group: "gpt-oss-20b-retain",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-retain-openrouter",
+    fallbackTimeoutS: 90
+  },
+  consolidation: {
+    group: "gpt-oss-20b-consolidation",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-consolidation-openrouter",
+    fallbackTimeoutS: 90
+  }
+};
+function litellmChainSeconds(tier) {
+  assertPositive(tier.localTimeoutS, `${tier.group} localTimeoutS`);
+  if (tier.fallbackGroup === null)
+    return tier.localTimeoutS;
+  assertPositive(tier.fallbackTimeoutS, `${tier.fallbackGroup} fallbackTimeoutS`);
+  return tier.localTimeoutS + tier.fallbackTimeoutS;
+}
+function minimumClientBudgetSeconds(tier, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return litellmChainSeconds(tier) + marginS;
+}
+function clientBudgetSeconds(tier, floorS = 0, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return Math.max(Math.ceil(floorS), minimumClientBudgetSeconds(tier, marginS));
+}
+function assertPositive(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`litellm timeout budget: ${label} must be a positive number, got ${value}`);
+  }
+}
+
 // src/setup/hindsight.ts
 var HINDSIGHT_DEFAULT_API_PORT = 18888;
 var HINDSIGHT_DEFAULT_MCP_URL = `http://127.0.0.1:${HINDSIGHT_DEFAULT_API_PORT}/mcp/`;
@@ -19156,6 +19197,18 @@ var HINDSIGHT_IMAGE_REPO = "ghcr.io/switchroom/switchroom-hindsight";
 var HINDSIGHT_IMAGE = `${HINDSIGHT_IMAGE_REPO}:latest`;
 var HINDSIGHT_BROKER_SOCK_VOLUME = `auth-broker-${HINDSIGHT_CONSUMER_NAME}-sock`;
 var HINDSIGHT_CREDS_MIRROR_VOLUME = `consumer-creds-${HINDSIGHT_CONSUMER_NAME}`;
+var HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 16384;
+var HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND = 80.6;
+function hindsightRetainLlmTimeoutSeconds(maxCompletionTokens = HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS, tokensPerSecond = HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND) {
+  if (!(maxCompletionTokens > 0) || !(tokensPerSecond > 0)) {
+    throw new Error(`hindsight retain budget: maxCompletionTokens (${maxCompletionTokens}) and ` + `tokensPerSecond (${tokensPerSecond}) must both be positive`);
+  }
+  return Math.ceil(maxCompletionTokens / tokensPerSecond);
+}
+function hindsightRetainClientTimeoutSeconds() {
+  return clientBudgetSeconds(LITELLM_TIMEOUT_TIERS.retain, hindsightRetainLlmTimeoutSeconds());
+}
+var HINDSIGHT_RETAIN_CLIENT_DEADLINE_S = hindsightRetainClientTimeoutSeconds() + LITELLM_ROUTER_MARGIN_S;
 var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.request.urlopen("http://localhost:8888/health",timeout=4).getcode()==200 else 1)';
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 var DOCKER_PROBE_TIMEOUT_MS = 60 * 1000;

package/dist/vault/broker/server.js

@@ -18820,6 +18820,47 @@ for (const name of SHARED_FRAGMENTS) {
   }
 }
 
+// src/litellm/timeout-budget.ts
+var LITELLM_ROUTER_MARGIN_S = 10;
+var LITELLM_TIMEOUT_TIERS = {
+  interactive: {
+    group: "gpt-oss-20b",
+    localTimeoutS: 90,
+    fallbackGroup: "gpt-oss-20b-openrouter",
+    fallbackTimeoutS: 60
+  },
+  retain: {
+    group: "gpt-oss-20b-retain",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-retain-openrouter",
+    fallbackTimeoutS: 90
+  },
+  consolidation: {
+    group: "gpt-oss-20b-consolidation",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-consolidation-openrouter",
+    fallbackTimeoutS: 90
+  }
+};
+function litellmChainSeconds(tier) {
+  assertPositive(tier.localTimeoutS, `${tier.group} localTimeoutS`);
+  if (tier.fallbackGroup === null)
+    return tier.localTimeoutS;
+  assertPositive(tier.fallbackTimeoutS, `${tier.fallbackGroup} fallbackTimeoutS`);
+  return tier.localTimeoutS + tier.fallbackTimeoutS;
+}
+function minimumClientBudgetSeconds(tier, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return litellmChainSeconds(tier) + marginS;
+}
+function clientBudgetSeconds(tier, floorS = 0, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return Math.max(Math.ceil(floorS), minimumClientBudgetSeconds(tier, marginS));
+}
+function assertPositive(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`litellm timeout budget: ${label} must be a positive number, got ${value}`);
+  }
+}
+
 // src/setup/hindsight.ts
 var HINDSIGHT_DEFAULT_API_PORT = 18888;
 var HINDSIGHT_DEFAULT_MCP_URL = `http://127.0.0.1:${HINDSIGHT_DEFAULT_API_PORT}/mcp/`;
@@ -18829,6 +18870,18 @@ var HINDSIGHT_IMAGE_REPO = "ghcr.io/switchroom/switchroom-hindsight";
 var HINDSIGHT_IMAGE = `${HINDSIGHT_IMAGE_REPO}:latest`;
 var HINDSIGHT_BROKER_SOCK_VOLUME = `auth-broker-${HINDSIGHT_CONSUMER_NAME}-sock`;
 var HINDSIGHT_CREDS_MIRROR_VOLUME = `consumer-creds-${HINDSIGHT_CONSUMER_NAME}`;
+var HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 16384;
+var HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND = 80.6;
+function hindsightRetainLlmTimeoutSeconds(maxCompletionTokens = HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS, tokensPerSecond = HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND) {
+  if (!(maxCompletionTokens > 0) || !(tokensPerSecond > 0)) {
+    throw new Error(`hindsight retain budget: maxCompletionTokens (${maxCompletionTokens}) and ` + `tokensPerSecond (${tokensPerSecond}) must both be positive`);
+  }
+  return Math.ceil(maxCompletionTokens / tokensPerSecond);
+}
+function hindsightRetainClientTimeoutSeconds() {
+  return clientBudgetSeconds(LITELLM_TIMEOUT_TIERS.retain, hindsightRetainLlmTimeoutSeconds());
+}
+var HINDSIGHT_RETAIN_CLIENT_DEADLINE_S = hindsightRetainClientTimeoutSeconds() + LITELLM_ROUTER_MARGIN_S;
 var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.request.urlopen("http://localhost:8888/health",timeout=4).getcode()==200 else 1)';
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 var DOCKER_PROBE_TIMEOUT_MS = 60 * 1000;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.19.19",
+  "version": "0.19.22",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {
@@ -28,11 +28,12 @@
     "test:vitest": "vitest run",
     "test:bun": "bun test telegram-plugin/tests/catch-all-forwarded-history.test.ts src/vault/grants.test.ts src/vault/grants-db.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-scope-persist.test.ts src/vault/broker/server-tokenless-scope.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/litellm/provision-apply-e2e.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/self-approval-bypass.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/uat/uat-driver.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-auth-test-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs && node scripts/check-stale-tool-descriptions.mjs && node scripts/check-mcp-instructions-budget.mjs && node scripts/check-web-subscription-honest.mjs && node scripts/check-no-unpinned-npx-playwright.mjs && node scripts/check-gateway-line-ratchet.mjs && node scripts/check-litellm-config-guard.mjs",
+    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-bun-module-mock-scope.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-auth-test-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs && node scripts/check-stale-tool-descriptions.mjs && node scripts/check-mcp-instructions-budget.mjs && node scripts/check-web-subscription-honest.mjs && node scripts/check-no-unpinned-npx-playwright.mjs && node scripts/check-gateway-line-ratchet.mjs && node scripts/check-litellm-config-guard.mjs && node scripts/check-release-asset-names.mjs",
     "lint:tsc": "tsc --noEmit",
     "lint:plugin-references": "node scripts/check-plugin-references.mjs",
     "lint:bot-api-wrapping": "bash scripts/check-bot-api-wrapping.sh",
     "lint:bun-test-imports": "node scripts/check-bun-test-imports.mjs",
+    "lint:bun-module-mock-scope": "node scripts/check-bun-module-mock-scope.mjs",
     "lint:no-pii": "node scripts/check-no-pii-secrets.mjs",
     "lint:auth-test-hermeticity": "node scripts/check-auth-test-hermeticity.mjs",
     "lint:web-subscription-honest": "node scripts/check-web-subscription-honest.mjs",
@@ -40,6 +41,7 @@
     "lint:gateway-line-ratchet": "node scripts/check-gateway-line-ratchet.mjs",
     "lint:mcp-instructions-budget": "node scripts/check-mcp-instructions-budget.mjs",
     "lint:litellm-config-guard": "node scripts/check-litellm-config-guard.mjs",
+    "lint:release-asset-contract": "node scripts/check-release-asset-names.mjs",
     "prepublishOnly": "npm run build && npm run lint && npm test"
   },
   "dependencies": {

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