switchroom 0.19.0 → 0.19.2

package/telegram-plugin/external-spend.ts

@@ -0,0 +1,135 @@
+/**
+ * External (non-Claude / OpenRouter cash) spend for the `/usage` card.
+ *
+ * Layout B (operator-locked 2026-07-19):
+ * ```
+ * - 💸 External
+ * - 24h `$X.XX` · 7d `$Y.YY`
+ * - top `model $a` · `model $b` · `model $c`
+ * ```
+ *
+ * **Durable path:** the auth-broker holds the LiteLLM master key and
+ * serves a sanitized summary via `get-external-spend`. Agents never
+ * receive the master key. Soft-fail → omit the External block.
+ *
+ * Pure helpers (filter/format) live in `src/litellm/external-spend.ts`
+ * and are re-exported here for card rendering + tests.
+ */
+
+import {
+  formatUsd,
+  type ExternalSpendSummary,
+  type ExternalSpendTopModel,
+} from '../src/litellm/external-spend.js';
+
+export type { ExternalSpendSummary, ExternalSpendTopModel };
+export {
+  isExternalModel,
+  shortModelLabel,
+  formatUsd,
+  summarizeExternalSpend,
+  normalizeSpendLogRows,
+  utcDateString,
+  addUtcDays,
+  EXTERNAL_SPEND_CACHE_TTL_MS,
+  type LiteLLMDaySpendRow,
+} from '../src/litellm/external-spend.js';
+
+/** Soft client-side cache so strip double-taps of /usage within a process. */
+const CLIENT_CACHE_TTL_MS = 30_000;
+let clientCache: { atMs: number; summary: ExternalSpendSummary } | null = null;
+
+/** Test seam. */
+export function clearExternalSpendCache(): void {
+  clientCache = null;
+}
+
+/**
+ * Render layout-B bullet lines (no trailing freshness).
+ * Returns `[]` when summary is null/undefined so callers can omit.
+ * Zero totals still render — honest "no external spend".
+ */
+export function formatExternalSpendBlock(
+  summary: ExternalSpendSummary | null | undefined,
+): string[] {
+  if (summary == null) return [];
+  const lines = [
+    '- 💸 External',
+    `- 24h \`${formatUsd(summary.day24hUsd)}\` · 7d \`${formatUsd(summary.day7dUsd)}\``,
+  ];
+  if (summary.top.length > 0) {
+    const topParts = summary.top.map((t) => `\`${t.label} ${formatUsd(t.usd)}\``);
+    lines.push(`- top ${topParts.join(' · ')}`);
+  }
+  return lines;
+}
+
+export interface FetchExternalSpendDeps {
+  now?: Date;
+  /** Prefer injected client for tests; defaults to env agent socket. */
+  getExternalSpend?: (forceLive?: boolean) => Promise<{
+    available: boolean;
+    day24hUsd?: number;
+    day7dUsd?: number;
+    top?: Array<{ label: string; usd: number }>;
+    capturedAtMs?: number;
+    served?: 'live' | 'cache';
+    reason?: string;
+  }>;
+  forceLive?: boolean;
+  bypassCache?: boolean;
+  cacheTtlMs?: number;
+}
+
+/**
+ * Best-effort fleet External spend for `/usage`.
+ * Primary: auth-broker `get-external-spend` (master key stays in broker).
+ * Returns null when unavailable — caller omits the block.
+ */
+export async function fetchExternalSpendSummary(
+  nowOrDeps: Date | FetchExternalSpendDeps = {},
+): Promise<ExternalSpendSummary | null> {
+  const deps: FetchExternalSpendDeps =
+    nowOrDeps instanceof Date ? { now: nowOrDeps } : nowOrDeps;
+  const ttl = deps.cacheTtlMs ?? CLIENT_CACHE_TTL_MS;
+  if (!deps.bypassCache && clientCache && Date.now() - clientCache.atMs < ttl) {
+    return clientCache.summary;
+  }
+
+  try {
+    let data: Awaited<ReturnType<NonNullable<FetchExternalSpendDeps['getExternalSpend']>>>;
+    if (deps.getExternalSpend) {
+      data = await deps.getExternalSpend(deps.forceLive);
+    } else {
+      // Lazy import avoids pulling the full client graph into pure test paths.
+      const { AuthBrokerClient } = await import('../src/auth/broker/client.js');
+      const client = new AuthBrokerClient();
+      try {
+        data = await client.getExternalSpend(deps.forceLive);
+      } finally {
+        try {
+          await client.close();
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    if (!data?.available) return null;
+    if (
+      typeof data.day24hUsd !== 'number' ||
+      typeof data.day7dUsd !== 'number' ||
+      !Array.isArray(data.top)
+    ) {
+      return null;
+    }
+    const summary: ExternalSpendSummary = {
+      day24hUsd: data.day24hUsd,
+      day7dUsd: data.day7dUsd,
+      top: data.top.map((t) => ({ label: String(t.label), usd: Number(t.usd) })),
+    };
+    clientCache = { atMs: Date.now(), summary };
+    return summary;
+  } catch {
+    return null;
+  }
+}

package/telegram-plugin/gateway/gateway.ts

@@ -42,6 +42,7 @@ import {
   resolveSafeBoundaryEnabled,
 } from './interrupt-defer.js'
 import { parseStopKeyword, buildStopReply } from './stop-command.js'
+import { shouldMaskUsageLabels } from './usage-mask.js'
 import { shouldPostBusyAck, formatBusyAckText, BUSY_ACK_STEP_AGE_THRESHOLD_MS } from './busy-ack.js'
 import {
   resolveStickerSendArgs,
@@ -537,6 +538,9 @@ import {
   modelCommandReceiptLine,
   handleModelCommand,
   classifyModelSwitchConfirmation,
+  formatModelRelaunchDiagLog,
+  formatModelSwitchConfirmationBody,
+  formatModelRelaunchSuppressNotAppliedLog,
   buildModelMenu,
   handleModelMenuCallback,
   isValidModelArg,
@@ -651,6 +655,7 @@ import {
   mutateStatusPinRow,
   reconcileAndPersistStatusPin,
   runStatusPinBootCleanup,
+  withPinReconcileLock,
   type PersistedStatusPin,
   type StatusPinPersistOp,
 } from './status-pin-store.js'
@@ -877,7 +882,7 @@ import {
   decideAnnouncementDelivery,
   foldAnnouncementIntoCard,
 } from '../fallback-card-collapse.js'
-import { buildSnapshotsFromState, buildSnapshotsFromCachedState, zipProbeResults } from '../auth-snapshot-format.js'
+import { buildSnapshotsFromState, buildSnapshotsFromCachedState, zipProbeResults, deriveUsageFooterFreshness } from '../auth-snapshot-format.js'
 import { maskUsername } from '../demo-mask.js'
 import {
   writeTurnActiveMarker,
@@ -8440,6 +8445,10 @@ const PIN_STATUS_WHILE_WORKING = (() => {
 // handlers unconditionally unpinning on every send) and runs NO polling
 // watchdog / getChat().pinned_message reconciler.
 const statusPinState = new Map<string, PinState>()
+// F2 serialization: same-pinKey reconciles run one-at-a-time via
+// `withPinReconcileLock` (status-pin-store.ts — kept there so it's
+// unit-testable) so each reads a fresh `prev`; see its doc for the stale-`prev`
+// race it closes. Adds zero Telegram API calls (a serialized noop still no-ops).
 // Companion registry: pinKey → chatId, so the pre-restart sweep can unpin
 // owned pins without threading the chat id through every call site. Written on
 // every desired-pinned reconcile, cleared alongside the state on unpin.
@@ -9023,7 +9032,10 @@ async function reconcileStatusPin(
   // absorbed. (The `pin_message` MCP tool still surfaces failures to the agent
   // as a normal tool-error — that path is `executePinMessage`, not this one.)
   try {
-    await reconcileStatusPinInner(pinKey, chatId, desired)
+    // Serialize per pinKey (F2): reconcileStatusPinInner reads `prev` from the
+    // in-memory claim map at its top, so overlapping same-key reconciles must
+    // run one-at-a-time or a stale `prev` clears the disk row under a live pin.
+    await withPinReconcileLock(pinKey, () => reconcileStatusPinInner(pinKey, chatId, desired))
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
     process.stderr.write(
@@ -9040,14 +9052,11 @@ async function reconcileStatusPinInner(
 ): Promise<void> {
   if (!PIN_STATUS_WHILE_WORKING) return
   if (chatId.length === 0) return
-  // NOTE (invisible-worker-cards review, intentionally left): this reconcile is
-  // NOT serialized per pinKey — it snapshots `prev` then awaits. Two edits that
-  // fire `syncPin` in the same microtask window after a dropped claim can both
-  // read `prev=null` and both issue a `pinChatMessage` for the SAME id. That is
-  // benign and self-healing: re-pinning an already-pinned id is idempotent on
-  // Telegram, and the first reconcile to set the claim makes every subsequent
-  // edit a no-op — it converges in one round, never a storm. A per-key mutex
-  // would remove the duplicate pin but adds lock complexity for zero UX gain.
+  // Serialized per pinKey by `withPinReconcileLock` at the caller (F2), so this
+  // `prev` snapshot is taken only after any prior same-key reconcile fully
+  // settled — always the true current claim. Closes the stale-`prev` race (a
+  // turn-end clear dropping the disk row under a flood-delayed open-pin) and the
+  // older duplicate-pin concern (two edits both reading prev=null).
   const prev = statusPinState.get(pinKey) ?? null
 
   const runReconcile = () =>
@@ -14333,6 +14342,26 @@ function isAuthorizedSender(ctx: Context): boolean {
   return false
 }
 
+// Adversarial-review F4 — a group configured with an EMPTY `allowFrom`
+// authorizes every member (isAuthorizedSender returns true for any sender in
+// that group). That's an intentional "whole-group" access mode, but it means
+// `/usage` would expose per-account email labels + quota headroom to every
+// member of a broadly-shared group. Harden minimally: for the quota-bearing
+// card in a non-private chat, mask account labels (reusing the demo-mask
+// machinery) UNLESS the group pinned a non-empty `allowFrom` — i.e. an
+// explicit operator-curated member list is treated as trusted enough to see
+// the real labels. Private (operator DM) chats are never masked. This changes
+// only what /usage REVEALS, not who may run it. The pure decision lives in
+// ./usage-mask.ts (shouldMaskUsageLabels) so it is unit-testable without
+// importing the whole gateway module.
+function shouldMaskAccountLabels(ctx: Context): boolean {
+  const groupAllowFrom =
+    ctx.chat?.type === 'group' || ctx.chat?.type === 'supergroup'
+      ? loadAccess().groups[String(ctx.chat.id)]?.allowFrom
+      : undefined
+  return shouldMaskUsageLabels(ctx.chat?.type, groupAllowFrom)
+}
+
 // safeName moved to ./media-message-handlers.ts (switchroom#2996 P6 cluster A);
 // imported above and shared with the attachment handlers still inline here.
 
@@ -21444,7 +21473,12 @@ bot.command('issues', async ctx => {
 })
 bot.command('usage', async ctx => {
   if (!isAuthorizedSender(ctx)) return
-  const demo = hasDemoFlag(getCommandArgs(ctx))
+  // `demo` is the explicit `/usage demo` opt-in mask. F4 additionally masks
+  // account labels for a non-private chat whose group has no pinned
+  // `allowFrom` (open-membership group) — see shouldMaskAccountLabels. The
+  // effective mask feeds the label-rendering paths (renderUsageCard,
+  // buildSnapshotKeyboard) exactly as `demo` did.
+  const demo = hasDemoFlag(getCommandArgs(ctx)) || shouldMaskAccountLabels(ctx)
   // Format 2 path: enumerate every account in the broker's known set,
   // probe live quota in parallel, render the health-grouped snapshot.
   // Falls back to the legacy single-agent shape when the broker is
@@ -21484,26 +21518,34 @@ bot.command('usage', async ctx => {
         // segment, just relative instead of absolute — no info lost; the
         // recommendation + cached/live footer the table used to carry are
         // preserved by renderUsageCard.
+        // External OpenRouter/$ block (layout B) — best-effort; omitted when
+        // LiteLLM admin key is unavailable or the spend endpoint fails.
+        const { fetchExternalSpendSummary } = await import('../external-spend.js')
+        const externalSpend = await fetchExternalSpendSummary(renderNow).catch(() => null)
         const exhaustedByLabel = new Map<string, boolean>(
           state.accounts.map((a) => [a.label, a.exhausted]),
         )
         const text = renderUsageCard(snapshots, exhaustedByLabel, {
           now: renderNow,
           demo,
+          externalSpend,
           // #2495 Change 2 — a TTL-hit / failed-probe fallback is tagged
           // served:"cache"; surface it as `⚠ cached Nm ago` instead of a
           // false live stamp. Otherwise stamp the live refresh time.
           // Honesty backstop: a TOTAL probe failure (the .catch above
           // returned `{results: []}` and nothing was served from cache)
           // must render an explicit "probe failed" marker, NOT a false
-          // "Live" stamp next to "⚠️ no data" rows. Without this the
-          // footer claimed "Live · refreshed 0s ago" while every account
-          // row said "no data — probe failed" (#2959 review finding).
-          ...(staleCachedAtMs != null
-            ? { staleCachedAtMs }
-            : probeResp.results.length > 0
-              ? { liveProbedAtMs: renderNow.getTime() }
-              : { probeFailed: true }),
+          // "Live" stamp next to "⚠️ no data" rows (#2959 review finding).
+          // Honesty invariant (adversarial-review F1): the live stamp is
+          // derived from whether ANY row carries usable data, NOT from the
+          // array length — a failed live probe against an empty cache returns
+          // a non-empty results array of all-`ok:false` rows. Full rationale
+          // in deriveUsageFooterFreshness (auth-snapshot-format.ts).
+          ...deriveUsageFooterFreshness(
+            probeResp.results,
+            staleCachedAtMs,
+            renderNow.getTime(),
+          ),
         })
         // Preserve the Switch/Refresh/usage/Add inline keyboard on the
         // rich-message render — the table card carries the same actions the
@@ -23868,62 +23910,36 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 // scraped pane or an optimistic record.
                 const isApplyBoot = launched.length > 0 && launched !== configured
                 sessionModelSource.setOverride(isApplyBoot ? launched : null)
-                // Diagnosability (rev 5): the applied model is now always
-                // greppable — `grep 'gw /model relaunch applied'`. F4 note:
-                // `launched` is the REQUESTED token start.sh wrote before `exec
-                // claude` (it is NOT a post-launch confirmation). If a shape-valid
-                // but unknown Claude id was requested, `--fallback-model` may mask
-                // it: claude serves a fallback while this records the requested
-                // token. That divergence is NOT a persistent lie — the transcript's
-                // `message.model` (noteTranscriptModel) reclaims the source from
-                // this override on the first assistant line, correcting /status to
-                // the model actually serving calls. The pre-first-assistant window
-                // is the only optimistic window (G2), and it is bounded and
-                // self-healing; it is documented, not silently asserted as success.
+                // F1/N4: classify + log + one confirmation card. Formatters live
+                // in model-command.ts so this file does not inflate (#2996 ratchet).
+                const confirmation = modelSwitchReason != null
+                  ? classifyModelSwitchConfirmation({
+                      reason: modelSwitchReason,
+                      launched,
+                      configured,
+                    })
+                  : null
                 process.stderr.write(
-                  `telegram gateway: gw /model relaunch applied agent=${getMyAgentName()} launched=${launched || '(none)'} configured=${configured} override=${isApplyBoot ? 'set' : 'cleared'}\n`,
-                )
-                // Switch-confirmation (F1 / PLAN §4 step 2): on a /model apply-boot
-                // with a known initiating chat, send ONE confirmation built from the
-                // ACTUAL launched model — never optimistic. Keyed on the DETERMINISTIC
-                // /model switch reason (from the clean-shutdown marker), not on
-                // `launched !== configured`, so it ALSO fires when a switch landed on
-                // the configured default (`/model default`, or `/model <configured>`)
-                // — N4. The generic boot card is suppressed for this boot (N3), so
-                // this is the single card the operator sees for the switch.
-                if (modelSwitchReason != null && modelSwitchMarkerChat) {
-                  const chat = modelSwitchMarkerChat
-                  // Derive the confirmation from the DETERMINISTIC post-boot
-                  // signals. A non-default switch that reverted to the configured
-                  // default (a wedged/consumed apply-boot — the silent-revert bug)
-                  // must WARN, not print a misleading green "✅ Now running
-                  // <default>" card. `applied` / `default` keep the honest green
-                  // card (N4: the default/revert case still confirms).
-                  const confirmation = classifyModelSwitchConfirmation({
-                    reason: modelSwitchReason,
+                  formatModelRelaunchDiagLog({
+                    agent: getMyAgentName(),
                     launched,
                     configured,
-                  })
-                  // LOW-2 dedup: the config-default-changed / proxy-down revert
-                  // paths in start.sh write a TAILORED `.session-model-alert`
-                  // (relayed to operators below) that already explains why the
-                  // switch didn't apply and how to re-issue it. Suppress the
-                  // generic not-applied card when such an alert is present for
-                  // this boot so the operator isn't double-warned — the alert is
-                  // the more specific message. The not-applied card still fires
-                  // for the plain wedge/revert case (no alert on disk).
+                    confirmation,
+                    isApplyBoot,
+                  }),
+                )
+                if (confirmation != null && modelSwitchMarkerChat) {
+                  const chat = modelSwitchMarkerChat
                   const hasSessionModelAlert = existsSync(join(smAgentDir, '.session-model-alert'))
                   if (confirmation.kind === 'not-applied' && hasSessionModelAlert) {
                     process.stderr.write(
-                      `telegram gateway: gw /model relaunch applied — suppressing not-applied confirmation (a .session-model-alert is present and will be relayed) agent=${getMyAgentName()} target=${confirmation.target}\n`,
+                      formatModelRelaunchSuppressNotAppliedLog({
+                        agent: getMyAgentName(),
+                        target: confirmation.target,
+                      }),
                     )
                   } else {
-                    const body =
-                      confirmation.kind === 'applied'
-                        ? `✅ Now running \`${confirmation.launched}\` — session-only, reverts to the configured model on the next restart. Fresh session; memory and the handoff briefing carry the context.`
-                        : confirmation.kind === 'not-applied'
-                          ? `⚠️ Your switch to \`${confirmation.target}\` didn't apply — the agent reverted to \`${confirmation.revertedTo}\` (the apply-boot didn't complete). Re-issue \`/model ${confirmation.target}\` to try again.`
-                          : `✅ Now running \`${confirmation.launched}\` (the configured default) — fresh session; memory and the handoff briefing carry the context.`
+                    const body = formatModelSwitchConfirmationBody(confirmation)
                     // allow-raw-bot-api: one-shot boot confirmation, same shape as the session-model alert relay below
                     void lockedBot.api
                       .sendMessage(chat.chatId, body, {

package/telegram-plugin/gateway/model-command.ts

@@ -188,6 +188,112 @@ export function classifyModelSwitchConfirmation(input: {
   return { kind: 'default', launched: revertedTo }
 }
 
+/**
+ * Diagnostic stderr lines for a /model apply-boot rehydration.
+ * Pure strings so gateway.ts stays thin (line-ratchet #2996).
+ */
+export function formatModelRelaunchDiagLog(input: {
+  agent: string
+  launched: string
+  configured: string
+  confirmation: ModelSwitchConfirmation | null
+  isApplyBoot: boolean
+}): string {
+  const { agent, launched, configured, confirmation, isApplyBoot } = input
+  const L = launched || '(none)'
+  if (confirmation == null) {
+    return (
+      'telegram gateway: gw /model relaunch applied agent=' +
+      agent +
+      ' launched=' +
+      L +
+      ' configured=' +
+      configured +
+      ' override=' +
+      (isApplyBoot ? 'set' : 'cleared') +
+      '\n'
+    )
+  }
+  if (confirmation.kind === 'not-applied') {
+    return (
+      'telegram gateway: gw /model relaunch NOT-APPLIED agent=' +
+      agent +
+      ' target=' +
+      confirmation.target +
+      ' launched=' +
+      L +
+      ' configured=' +
+      configured +
+      ' revertedTo=' +
+      confirmation.revertedTo +
+      '\n'
+    )
+  }
+  if (confirmation.kind === 'applied') {
+    return (
+      'telegram gateway: gw /model relaunch applied agent=' +
+      agent +
+      ' launched=' +
+      L +
+      ' configured=' +
+      configured +
+      ' override=set outcome=applied\n'
+    )
+  }
+  return (
+    'telegram gateway: gw /model relaunch applied agent=' +
+    agent +
+    ' launched=' +
+    L +
+    ' configured=' +
+    configured +
+    ' override=cleared outcome=default\n'
+  )
+}
+
+/** Telegram body for the single switch-confirmation card (F1/N4). */
+export function formatModelSwitchConfirmationBody(
+  confirmation: ModelSwitchConfirmation,
+): string {
+  if (confirmation.kind === 'applied') {
+    return (
+      '✅ Now running `' +
+      confirmation.launched +
+      '` — session-only, reverts to the configured model on the next restart. Fresh session; memory and the handoff briefing carry the context.'
+    )
+  }
+  if (confirmation.kind === 'not-applied') {
+    return (
+      "⚠️ Your switch to `" +
+      confirmation.target +
+      "` didn't apply — the agent reverted to `" +
+      confirmation.revertedTo +
+      "` (the apply-boot didn't complete). Re-issue `/model " +
+      confirmation.target +
+      "` to try again."
+    )
+  }
+  return (
+    '✅ Now running `' +
+    confirmation.launched +
+    '` (the configured default) — fresh session; memory and the handoff briefing carry the context.'
+  )
+}
+
+export function formatModelRelaunchSuppressNotAppliedLog(input: {
+  agent: string
+  target: string
+}): string {
+  return (
+    'telegram gateway: gw /model relaunch NOT-APPLIED — suppressing not-applied confirmation (a .session-model-alert is present and will be relayed) agent=' +
+    input.agent +
+    ' target=' +
+    input.target +
+    '\n'
+  )
+}
+
+
 export type ParsedModelCommand =
   | { kind: 'show' }
   | { kind: 'set'; model: string }

package/telegram-plugin/gateway/narrative-lane.ts

@@ -389,7 +389,18 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
             // mid-turn has something to finalize on next boot instead of
             // leaving this card frozen forever. Fire-and-forget/best-effort:
             // a failed persist degrades to the pre-fix (in-memory-only)
-            // behaviour, never blocks the card opening.
+            // behaviour, never blocks the card opening (writeActivityCardRecord
+            // → persistActivityCards swallows write errors — it never throws).
+            //
+            // F6 (persist-intent-first ordering): this write is the FIRST action
+            // taken after the send resolves and BEFORE the status-pin reconcile
+            // below — no `await` sits between the send and this persist, so the
+            // crash window in which a sent card has no durable record (and is
+            // thus unreapable by the boot reaper) is the minimum achievable. A
+            // true pre-send provisional record is impossible: the reaper keys
+            // its finalizing edit on `activityMessageId`, which only exists once
+            // sendRichMessage returns. Keep this persist synchronous and ahead
+            // of the pin; do not move it after an await.
             if (activityCardPersistEnabled) {
               writeActivityCardRecord(ACTIVITY_CARD_STORE_PATH, activityCardStoreFs, {
                 turnKey: statusKey(chat, thread),
@@ -397,15 +408,18 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
                 threadId: thread ?? null,
                 activityMessageId: sent.message_id,
                 startedAt: turn.startedAt,
-                // Mirror the ACTUAL pin decision, not an unconditional `true`:
-                // the OPEN below silently-pins the fresh card only when
-                // `PIN_STATUS_WHILE_WORKING` is on (`reconcileStatusPin` no-ops
-                // when it's off, and can also fail on missing supergroup
-                // rights). Persisting `pinned: true` regardless would make the
-                // boot reaper attempt an unpin on a card that was never pinned.
-                // The reaper's unpin is defense-in-depth anyway
+                // F5 (persist-intent honesty): mirror the ACTUAL pin decision,
+                // not an unconditional `true`. The OPEN below silently-pins the
+                // fresh card only when `PIN_STATUS_WHILE_WORKING` is on
+                // (`reconcileStatusPin` no-ops when it's off, and can also fail
+                // on missing supergroup rights). Persisting `pinned: true`
+                // regardless would make the boot reaper attempt an unpin on a
+                // card that was never pinned. The persist is intentionally
+                // written BEFORE the fire-and-forget pin resolves (intent, not
+                // outcome); the reaper's unpin is idempotent defense-in-depth
                 // (`statusPinBootCleanup` owns the primary unpin), so tracking
-                // the flag honestly is what matters here.
+                // the DECISION honestly — pinned iff we will actually attempt a
+                // pin — is what matters here, not the async pin's result.
                 pinned: PIN_STATUS_WHILE_WORKING,
               })
             }

package/telegram-plugin/gateway/status-pin-store.ts

@@ -313,6 +313,40 @@ export function withStoreLock<T>(
   return run
 }
 
+/**
+ * Per-pinKey async serial lock (F2, invisible-worker-cards review).
+ *
+ * The gateway's status-pin reconcile reads its `prev` claim from an in-memory
+ * map at the TOP of the reconcile, then awaits the persist+pin. Two overlapping
+ * reconciles for the SAME key could each capture a stale `prev`: a turn-end
+ * `{pinned:false}` reading prev=null no-ops and clears the durable row while a
+ * flood-delayed open-pin lands right after — a stuck pin with NO on-disk record.
+ *
+ * Chaining every reconcile for one pinKey through this tail map guarantees the
+ * NEXT reconcile reads `prev` only after the prior one for that key has fully
+ * settled (its in-memory Maps updated), so the pin decision always sees the true
+ * current claim. Different keys never contend. Same non-rejecting-tail contract
+ * as `withStoreLock`. Keyed by pinKey, held by the gateway around the WHOLE
+ * read-prev → decide → reconcileAndPersistStatusPin → update-Maps sequence.
+ */
+const pinReconcileTails = new Map<string, Promise<unknown>>()
+
+export function withPinReconcileLock<T>(
+  pinKey: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prev = pinReconcileTails.get(pinKey) ?? Promise.resolve()
+  const run = prev.then(fn, fn)
+  pinReconcileTails.set(
+    pinKey,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  )
+  return run
+}
+
 /**
  * READ-MODIFY-WRITE for exactly ONE pinKey's row, against the authoritative
  * on-disk file. Loads the current snapshot from disk, drops any row for
@@ -431,11 +465,37 @@ export function reconcileAndPersistStatusPin(args: {
       return next
     }
 
-    // clear: unpin (best-effort) THEN drop the record. Ordering is safe here —
-    // if we crash after the unpin but before the rewrite, the stale record just
-    // gets unpinned again next boot (idempotent), never a lingering pin.
+    // clear: unpin (best-effort) THEN reconcile the record with the OUTCOME.
+    //
+    // F1 (invisible-worker-cards review): a `clear` op covers BOTH a genuine
+    // unpin AND a `noop: already pinned` — the pin decision maps every non-`pin`
+    // action here (see decidePinAction → the gateway's op mapping). For a real
+    // unpin, applyPin drops the claim and returns null → we remove the row. But
+    // for a noop-already-pinned, reconcilePin returns the LIVE claim unchanged
+    // (non-null) and issues NO Telegram call — the pin is still up. The worker
+    // feed calls syncPin on EVERY steady-state edit, so a noop-clear fires
+    // constantly; unconditionally deleting the row there erased the durable
+    // status-pins.json entry for a still-live pin. A crash after that left a
+    // stuck pinned card boot cleanup could never see. So: only drop the row when
+    // the claim is actually gone (next == null); when applyPin returns a live
+    // claim, PRESERVE the row (rewritten confirmed) so the durable record keeps
+    // tracking the pin that is genuinely still up. No extra Telegram API call is
+    // added — applyPin already ran; this only changes the disk write's content.
+    // Ordering for the real-unpin case is safe: if we crash after the unpin but
+    // before the rewrite, the stale record just gets unpinned again next boot
+    // (idempotent), never a lingering pin.
     const next = await args.applyPin()
-    applyStatusPinRow(path, fs, pinKey, null, log)
+    if (next == null) {
+      applyStatusPinRow(path, fs, pinKey, null, log)
+    } else {
+      applyStatusPinRow(
+        path,
+        fs,
+        pinKey,
+        { pinKey, chatId, messageId: next.messageId },
+        log,
+      )
+    }
     return next
   })
 }

package/telegram-plugin/gateway/usage-mask.ts

@@ -0,0 +1,29 @@
+/**
+ * Adversarial-review F4 — account-label masking policy for the `/usage` card.
+ *
+ * A group configured with an EMPTY `allowFrom` authorizes every member
+ * (`isAuthorizedSender` returns true for any sender in that group). That is an
+ * intentional "whole-group" access mode, but it means `/usage` would expose
+ * per-account email labels + quota headroom to every member of a broadly
+ * shared group. This predicate decides whether to mask account labels for the
+ * quota-bearing card, reusing the existing demo-mask machinery:
+ *
+ *   - private (operator DM) chat  → never mask
+ *   - group / supergroup with a NON-empty pinned `allowFrom` → trusted,
+ *     operator-curated member list → don't mask
+ *   - group / supergroup with an EMPTY `allowFrom` (open membership) → mask
+ *   - any other chat type reaching a quota render → mask defensively
+ *
+ * This changes only what `/usage` REVEALS, not who may run it — general
+ * command authorization semantics are untouched.
+ */
+export function shouldMaskUsageLabels(
+  chatType: string | undefined,
+  groupAllowFrom: readonly string[] | undefined,
+): boolean {
+  if (chatType === 'private') return false
+  if (chatType === 'group' || chatType === 'supergroup') {
+    return (groupAllowFrom ?? []).length === 0
+  }
+  return true
+}