switchroom 0.16.28 → 0.16.38

package/telegram-plugin/quota-watch.ts

@@ -51,6 +51,7 @@ import {
   fmtPct,
 } from "./auth-snapshot-format.js";
 import type { QuotaUtilization } from "./quota-check.js";
+import { escapeMarkdown, codeSpanSafe } from "./card-format.js";
 
 const STATE_FILE = "quota-watch.json";
 
@@ -511,7 +512,7 @@ function buildFleetRecoveredMessage(
   accounts: Array<{ label: string; exhausted: boolean }>,
 ): string {
   const healthy = accounts.filter((a) => !a.exhausted).map((a) => a.label);
-  const which = healthy.length > 0 ? ` (\`${escapeHtml(healthy[0]!)}\`)` : "";
+  const which = healthy.length > 0 ? ` (\`${codeSpanSafe(healthy[0]!)}\`)` : "";
   return [
     `🟢 **Fleet recovered** — at least one account is healthy again${which}.`,
     ``,
@@ -521,7 +522,7 @@ function buildFleetRecoveredMessage(
 
 // ─── Message builders ─────────────────────────────────────────────────────────
 
-function buildThrottlingMessage(agentName: string, snap: AccountSnapshot): string {
+export function buildThrottlingMessage(agentName: string, snap: AccountSnapshot): string {
   const q = snap.quota!; // classifyHealth returned throttling, so quota is non-null
   const fiveStr = fmtPct(q.fiveHourUtilizationPct);
   const sevenStr = fmtPct(q.sevenDayUtilizationPct);
@@ -535,14 +536,14 @@ function buildThrottlingMessage(agentName: string, snap: AccountSnapshot): strin
 
   const activeNote = snap.isActive
     ? ""
-    : `\nThis is a non-active account. Consider \`/auth use ${escapeHtml(snap.label)}\` to switch, or keep it as a fallback reserve.`;
+    : `\nThis is a non-active account. Consider \`/auth use ${codeSpanSafe(snap.label)}\` to switch, or keep it as a fallback reserve.`;
 
   const altNote = snap.isActive
     ? `\nConsider \`/auth use <other-account>\` if you have a healthier account, or wait for the ${winLabel} window to refill${resetStr}.`
     : "";
 
   return [
-    `🟡 **Quota approaching limit** — \`${escapeHtml(snap.label)}\``,
+    `🟡 **Quota approaching limit** — \`${codeSpanSafe(snap.label)}\``,
     ``,
     `${fiveStr} of 5h  ·  ${sevenStr} of 7d`,
     `Binding window: ${winLabel}${resetStr}`,
@@ -556,14 +557,14 @@ function buildThrottlingMessage(agentName: string, snap: AccountSnapshot): strin
     .trim();
 }
 
-function buildRecoveryMessage(agentName: string, snap: AccountSnapshot): string {
+export function buildRecoveryMessage(agentName: string, snap: AccountSnapshot): string {
   const q = snap.quota;
   const utilLine = q
     ? `Current: ${fmtPct(q.fiveHourUtilizationPct)} of 5h  ·  ${fmtPct(q.sevenDayUtilizationPct)} of 7d`
     : "Current quota data unavailable.";
 
   return [
-    `🟢 **Quota back in healthy range** — \`${escapeHtml(snap.label)}\``,
+    `🟢 **Quota back in healthy range** — \`${codeSpanSafe(snap.label)}\``,
     ``,
     utilLine,
     ``,
@@ -571,10 +572,6 @@ function buildRecoveryMessage(agentName: string, snap: AccountSnapshot): string
   ].join("\n");
 }
 
-function escapeHtml(s: string): string {
-  return s.replace(/([\\`*_~=\[\]|])/g, "\\$1");
-}
-
 // ─── State persistence ────────────────────────────────────────────────────────
 
 export function loadQuotaWatchState(stateDir: string): QuotaWatchState {

package/telegram-plugin/server.ts

@@ -30,7 +30,9 @@
  * - Robust error handling: 429 retry, thread-not-found fallback, network retry
  * - SQLite history buffer (history.ts) for cross-restart recovery
  * - Vault-grant inline-keyboard wizard
- * - Pinned progress card with sub-agent visibility
+ * - Live in-conversation status feed with sub-agent visibility (the pinned
+ *   progress card was retired in #1122; the status message is now a regular
+ *   in-chat message, silently pinned while in-flight — status-pin.ts)
  *
  * State (access.json / pairing / allowlists) lives at
  * ~/.claude/channels/telegram/ — managed by the /telegram:access skill.

package/telegram-plugin/status-pin-driver.ts

@@ -0,0 +1,102 @@
+/**
+ * Status-pin driver — executes a PinAction against a Telegram Bot API.
+ *
+ * The pure decision lives in `status-pin.ts` (decidePinAction). This
+ * module is the side-effecting half: takes the previously-claimed state
+ * and the desired state, computes ONE action, executes it, and returns
+ * the next state. The state itself stays in the caller (the gateway holds
+ * a `Map<pinKey, PinState>` and re-passes the entry on every call).
+ *
+ * Copied from `slot-banner-driver.ts`. The load-bearing contract (see
+ * slot-banner-driver.ts:100-110):
+ *
+ *   - Pins are SILENT (`disable_notification: true`) — a status pin must
+ *     never buzz the device.
+ *   - We pin an EXISTING message (the already-rendered per-turn status /
+ *     `🛠 Worker` message). We NEVER send a new message to pin. This is
+ *     the boundary that keeps us inside the one sanctioned exception on
+ *     `chat-is-the-single-source-of-truth`.
+ *   - On UNPIN we DROP THE CLAIM (clear state) EVEN IF `unpinChatMessage`
+ *     throws. This is the whole point: pin state must never get stuck.
+ *     The message may have been unpinned out-of-band (operator, or a
+ *     crash) — re-claiming it would be more confusing than surfacing it
+ *     again later, and a stuck claim would leave a permanent pin.
+ *   - API failures are reported via `onError` but never throw; the caller
+ *     decides logging cadence.
+ *
+ * See `reference/invariants.md` § `chat-is-the-single-source-of-truth`
+ * (the sanctioned silent-pin exception) and the `know-what-my-agent-is-doing`
+ * job spec.
+ */
+
+import type { PinState, DesiredPin } from './status-pin.js'
+import { decidePinAction } from './status-pin.js'
+
+/** Minimal subset of grammy's `bot.api` the pin driver depends on.
+ *  Lets tests swap in a fake without dragging in the full Bot type. */
+export interface PinBotApi {
+  pinChatMessage(
+    chat_id: string | number,
+    message_id: number,
+    opts?: Record<string, unknown>,
+  ): Promise<unknown>
+  unpinChatMessage(
+    chat_id: string | number,
+    message_id: number,
+  ): Promise<unknown>
+}
+
+export interface ReconcilePinArgs {
+  api: PinBotApi
+  chatId: string
+  /** State the caller is holding from the last reconcile. `null` on first. */
+  prevState: PinState | null
+  /** What the caller wants pinned for this key right now. */
+  desired: DesiredPin
+  /** Optional API-failure observer. Default: silent. */
+  onError?: (phase: 'pin' | 'unpin', err: unknown) => void
+}
+
+/**
+ * Execute the next pin-state transition for one key. Returns the new
+ * `PinState` (or `null` when unpinned / nothing pinned). Always resolves;
+ * never throws — API errors route through `onError`.
+ *
+ *   - `pin`  : pins the existing message SILENTLY; on failure the claim is
+ *              NOT taken (returns prevState) so the next reconcile retries
+ *              rather than tracking a message it never pinned.
+ *   - `unpin`: unpins best-effort and returns `null` — the claim is dropped
+ *              EVEN IF the unpin throws (never leave state stuck pinned).
+ *   - `noop` : returns prevState unchanged.
+ */
+export async function reconcilePin(
+  args: ReconcilePinArgs,
+): Promise<PinState | null> {
+  const action = decidePinAction(args.prevState, args.desired)
+
+  if (action.kind === 'noop') return args.prevState
+
+  if (action.kind === 'unpin') {
+    try {
+      await args.api.unpinChatMessage(args.chatId, action.messageId)
+    } catch (err) {
+      args.onError?.('unpin', err)
+    }
+    // Drop the claim regardless of the unpin outcome. A stuck claim would
+    // leave a permanent pin on a crash / out-of-band unpin — the exact
+    // failure this driver exists to prevent (see slot-banner-driver.ts).
+    return null
+  }
+
+  // action.kind === 'pin' — pin an EXISTING message, silently.
+  try {
+    await args.api.pinChatMessage(args.chatId, action.messageId, {
+      disable_notification: true,
+    })
+  } catch (err) {
+    args.onError?.('pin', err)
+    // Don't claim a message we failed to pin — the next reconcile retries.
+    return args.prevState
+  }
+  return { messageId: action.messageId }
+}

package/telegram-plugin/status-pin.ts

@@ -0,0 +1,76 @@
+/**
+ * Status-pin — pure decision logic.
+ *
+ * Keeps an already-rendered status message pinned while its work is
+ * in-flight, and unpins it the moment the work completes. This is the
+ * ONE sanctioned pin under the `chat-is-the-single-source-of-truth`
+ * invariant (see `reference/invariants.md` §
+ * `chat-is-the-single-source-of-truth` and the
+ * `know-what-my-agent-is-doing` job spec): it re-surfaces a message the
+ * conversation ALREADY owns — the per-turn activity/status message and
+ * the `🛠 Worker` background-worker message — and never renders a new
+ * parallel surface.
+ *
+ * Why a pin at all: fast answers, more background workers, and much
+ * longer turns mean the conversation moves on quickly in the feed and
+ * the user loses sight of in-flight work — work now routinely outlives
+ * the visible window. Pinning the message the feed already holds keeps
+ * it in view; it carries no new content.
+ *
+ * This module is dependency-free so it's provable in isolation; the
+ * gateway (via `status-pin-driver.ts`) translates a `PinAction` into
+ * actual Telegram API calls. The design mirrors `slot-banner.ts` +
+ * `slot-banner-driver.ts` — one pure decision, one side-effecting
+ * reconcile, the claim dropped on unpin even when the API throws.
+ */
+
+/** The message the framework is currently claiming as pinned for a key. */
+export type PinState = {
+  /** Telegram message_id we pinned. */
+  messageId: number
+}
+
+/** What the caller wants pinned for a key right now. */
+export type DesiredPin =
+  /** Work is in-flight; this already-rendered message should be pinned. */
+  | { pinned: true; messageId: number }
+  /** Work is done (or never opened a message); nothing should be pinned. */
+  | { pinned: false }
+
+export type PinAction =
+  | { kind: 'noop'; reason: string }
+  /** Pin an EXISTING message. Caller pins, then records the message_id
+   *  back into PinState. No new message is sent — this pins a message the
+   *  chat already rendered. */
+  | { kind: 'pin'; messageId: number }
+  /** Unpin + forget. Caller unpins (best-effort) and clears state EVEN IF
+   *  the unpin call throws. */
+  | { kind: 'unpin'; messageId: number }
+
+/**
+ * Decide the single pin action for a key given the previously-claimed
+ * state and what the caller now wants.
+ *
+ * Exactly one action per (prev, desired) — the whole point is that pin
+ * state can never get stuck: an in-flight → done transition always yields
+ * an `unpin`, and the driver drops the claim on unpin regardless of API
+ * outcome.
+ */
+export function decidePinAction(
+  prev: PinState | null,
+  desired: DesiredPin,
+): PinAction {
+  if (!desired.pinned) {
+    if (prev) return { kind: 'unpin', messageId: prev.messageId }
+    return { kind: 'noop', reason: 'nothing pinned, nothing wanted' }
+  }
+  // desired.pinned === true
+  if (prev == null) return { kind: 'pin', messageId: desired.messageId }
+  if (prev.messageId === desired.messageId) {
+    return { kind: 'noop', reason: 'already pinned this message' }
+  }
+  // The message we want pinned changed (the feed re-posted after a stale
+  // edit dropped its id). Unpin the old claim; a subsequent desired-pin
+  // re-pins the new one on the next reconcile.
+  return { kind: 'unpin', messageId: prev.messageId }
+}

package/telegram-plugin/stream-reply-handler.ts

@@ -158,6 +158,14 @@ export interface StreamReplyDeps {
    * the raw (repaired) text is sent unchanged.
    */
   normalizeParagraphBreaks?: (text: string) => string
+  /**
+   * Insert a visible blank-line spacer into each prose `\n\n` gap so the rich
+   * GFM renderer shows a real empty line between paragraphs (the rich engine
+   * otherwise renders `\n\n` tight — the post-#2669 paragraph-spacing
+   * regression). Applied only on the rich path (never on `format:'text'`).
+   * Optional for backward compat; omitted → no spacers added.
+   */
+  addParagraphSpacers?: (text: string) => string
   /** Validates the chat id against the access list. Throws on deny. */
   assertAllowedChat: (chatId: string) => void
   /** Resolves the effective thread id (explicit, last-inbound, or undefined). */
@@ -337,7 +345,12 @@ export async function handleStreamReply(
   // markdown→HTML / MarkdownV2 rendering happens here anymore — the raw
   // text IS the wire payload.
   const literalText = format === 'text'
-  let effectiveText: string = rawText
+  // Paragraph-spacing fix (rich-message regression after #2669): inject a
+  // visible blank-line spacer into prose `\n\n` gaps on the rich path so
+  // multi-paragraph answers don't render jammed together. The literal
+  // (`format:'text'`) path must stay byte-exact, so it is left untouched.
+  let effectiveText: string =
+    !literalText && deps.addParagraphSpacers ? deps.addParagraphSpacers(rawText) : rawText
 
   // Inline status-accent header (issue #320 fallback). Prepended so it
   // leads the body. Since stream_reply callers pass the full text snapshot

package/telegram-plugin/subagent-watcher.ts

@@ -13,9 +13,12 @@
  * does not yet exist (Phase 2 Pre hook hasn't fired), the update is a no-op
  * and the event is logged — no INSERT here, identity belongs to Phase 2.
  *
- * Sub-agent state is surfaced to the user via the progress card's
- * [Sub-agents · N running] block (progress-card.ts), not a separate pinned
- * card. See issue #142.
+ * Sub-agent state is surfaced to the user in the conversation itself — a
+ * background worker via its in-chat `🛠 Worker` message (worker-activity-feed.ts),
+ * a foreground sub-agent nested in the parent turn's activity message. The
+ * pinned progress card was retired in #1122; the `🛠 Worker` message is now
+ * silently pinned while the worker runs (status-pin.ts), not a bespoke card.
+ * See issue #142.
  *
  * Architecture notes:
  *   - Option B from the spec: filesystem-driven, no IPC contract.

package/telegram-plugin/tests/auth-command-format2.test.ts

@@ -93,8 +93,12 @@ describe('renderShowText — Format 2 vs legacy', () => {
     });
     expect(out).toContain('🔋 **Auth — fleet status**');
     expect(out).toContain('Recommendation:');
-    expect(out).toContain('🔴 **BLOCKED**');
-    expect(out).toContain('🟢 **HEALTHY**');
+    // GFM table card (#2700): State emoji per row, not group headers.
+    expect(out).toContain('| State | Account | 5h | 7d | Status |');
+    expect(out).toContain('| 🔴 |'); // the blocked account's State cell
+    expect(out).toContain('| 🟢 |'); // a healthy account's State cell
+    expect(out).not.toContain('**BLOCKED**');
+    expect(out).not.toContain('**HEALTHY**');
     // Legacy ASCII column headers should be absent
     expect(out).not.toContain('ACCOUNT     STATUS');
   });

package/telegram-plugin/tests/auth-command-vernacular.test.ts

@@ -140,6 +140,24 @@ describe('parseAuthCommand — new verbs', () => {
     expect((p as { reason?: string }).reason).toMatch(/confirm/i)
   })
 
+  // Boundary-escaping (#2695 escaper de-dup): the help/reason strings now
+  // render dynamic user input via `codeSpanSafe` — the reason interpolates the
+  // value INSIDE a `code span`, where backslash escaping is wrong (#2695). A
+  // metacharacter-laden verb must come back LITERAL (no stray backslashes).
+  it('renders a metacharacter-laden unknown verb literally in the code span', () => {
+    const p = parseAuthCommand('/auth a_b*c')
+    expect(p?.kind).toBe('help')
+    expect((p as { reason?: string }).reason).toContain('`a_b*c`')
+    expect((p as { reason?: string }).reason).not.toContain('a\\_b\\*c')
+  })
+
+  it('renders a metacharacter-laden rm modifier literally in the code span', () => {
+    const p = parseAuthCommand('/auth rm spare x_y*z')
+    expect(p?.kind).toBe('help')
+    expect((p as { reason?: string }).reason).toContain('`x_y*z`')
+    expect((p as { reason?: string }).reason).not.toContain('x\\_y\\*z')
+  })
+
   it('rejects /auth rm with no label', () => {
     const p = parseAuthCommand('/auth rm')
     expect(p?.kind).toBe('help')