switchroom 0.17.5 → 0.17.10

package/telegram-plugin/dist/server.js

@@ -23876,6 +23876,7 @@ function createIpcClient(options) {
     onInbound,
     onPermission,
     onStatus,
+    onConnect,
     log = () => {},
     reconnectDelayMs = 2000,
     maxReconnectDelayMs = 30000,
@@ -24011,6 +24012,13 @@ function createIpcClient(options) {
             sendRegister();
             startHeartbeat();
             log(`connected to ${socketPath}`);
+            if (onConnect) {
+              try {
+                onConnect();
+              } catch (err) {
+                log(`onConnect hook threw: ${err}`);
+              }
+            }
             resolve();
           },
           data(sock, data) {
@@ -24232,10 +24240,52 @@ var init_permission_rule = __esm(() => {
   ]);
 });
 
+// bridge/permission-ledger.ts
+function createOutstandingPermissionLedger() {
+  const map2 = new Map;
+  return {
+    add(params) {
+      map2.set(params.request_id, params);
+    },
+    delete(requestId) {
+      map2.delete(requestId);
+    },
+    has(requestId) {
+      return map2.has(requestId);
+    },
+    all() {
+      return [...map2.values()];
+    },
+    get size() {
+      return map2.size;
+    }
+  };
+}
+
 // bridge/bridge.ts
 var exports_bridge = {};
 import { dirname as dirname3, join as join5 } from "path";
 import { homedir as homedir4 } from "os";
+function flushOutstandingPermissionRequests() {
+  if (!permissionRearmEnabled)
+    return;
+  if (!ipc || !ipc.isConnected())
+    return;
+  const pending = outstandingPermissions.all();
+  if (pending.length === 0)
+    return;
+  process.stderr.write(`telegram bridge: re-sending ${pending.length} outstanding permission request(s) on gateway (re)connect
+`);
+  for (const p of pending) {
+    ipc.sendPermissionRequest({
+      type: "permission_request",
+      requestId: p.request_id,
+      toolName: p.tool_name,
+      description: p.description,
+      inputPreview: p.input_preview
+    });
+  }
+}
 function onInbound(msg) {
   mcp.notification({
     method: "notifications/claude/channel",
@@ -24252,6 +24302,7 @@ function onPermission(msg) {
   if (msg.rule) {
     sessionAllowRules.add(msg.rule);
   }
+  outstandingPermissions.delete(msg.requestId);
   mcp.notification({
     method: "notifications/claude/channel/permission",
     params: {
@@ -24305,6 +24356,7 @@ async function main() {
     onInbound,
     onPermission,
     onStatus,
+    onConnect: flushOutstandingPermissionRequests,
     log: (msg) => process.stderr.write(`telegram bridge: ipc: ${msg}
 `),
     livenessFilePath: process.env.SWITCHROOM_BRIDGE_ALIVE_PATH ?? join5(STATE_DIR, ".bridge-alive")
@@ -24318,7 +24370,7 @@ async function main() {
   }
   await mcp.connect(new StdioServerTransport);
 }
-var STATE_DIR, SOCKET_PATH, TOPIC_ID, AGENT_NAME, mcp, TOOL_SCHEMAS, EFFECTIVE_TOOL_SCHEMAS, sessionAllowRules, ipc = null, sessionTailEnabled, sessionTailHandle = null, ptyTailEnabled, ptyTailHandle = null;
+var STATE_DIR, SOCKET_PATH, TOPIC_ID, AGENT_NAME, mcp, TOOL_SCHEMAS, EFFECTIVE_TOOL_SCHEMAS, sessionAllowRules, outstandingPermissions, permissionRearmEnabled, ipc = null, sessionTailEnabled, sessionTailHandle = null, ptyTailEnabled, ptyTailHandle = null;
 var init_bridge = __esm(async () => {
   init_server2();
   init_stdio2();
@@ -24681,6 +24733,23 @@ var init_bridge = __esm(async () => {
         required: ["chat_id", "key"]
       }
     },
+    {
+      name: "mental_model_propose",
+      description: "Propose a Hindsight MENTAL MODEL for the operator to approve (agent-proposes \u2192 human-approves, hindsight Phase 5). Use this when \u2014 over real work \u2014 you notice a recurring, domain-specific question worth maintaining a standing, semantically-refreshed answer to from YOUR bank (e.g. a coach's `training-plan-state`, a lawyer's `open-matters`). You may PROPOSE but can NEVER self-approve: this renders a Telegram [Approve]/[Deny] card to the operator. On Approve the model is DECLARED \u2014 appended to your `memory.mental_models[]` in switchroom.yaml via the operator-approved config-edit path \u2014 and ensured in your bank (it then refreshes from your bank content). On Deny nothing is written. This is NOT for identity/'who is the user' (dedicated profile banks own that) and NOT a substitute for `retain` (store a fact) or `create_mental_model` where you already have direct Hindsight tools \u2014 it is the leashed, human-gated way to add a DURABLE declared model to your config. After firing this tool, END YOUR TURN cleanly \u2014 a fresh inbound arrives (`<channel source=\"mental_model_proposal_applied\">` / `mental_model_proposal_denied`) once the operator decides. Do NOT propose a model whose name is already declared (it is rejected), and do NOT spam (one card per proposal; the operator sees every one).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          chat_id: { type: "string", description: "Chat to render the approval card in (use the chat_id of the user message that triggered the workflow)." },
+          name: { type: "string", description: "Stable model name \u2014 the idempotent-ensure identity key (lowercase kebab/snake, e.g. `training-plan-state`). Must be UNIQUE among your already-declared models or the proposal is rejected." },
+          source_query: { type: "string", description: `The reflection query the model answers, semantically refreshed from your bank content (e.g. "What is the athlete's current training plan, recent sessions, and open adjustments?"). Frame it as a DOMAIN question, never an identity question.` },
+          reason: { type: "string", description: 'REQUIRED in practice \u2014 one-line rationale rendered on the card (e.g. "I keep re-deriving the plan state every session; a standing model would save the lookup"). Omitting it renders "why: not provided" and the operator will usually Deny.' },
+          refresh_after_consolidation: { type: "boolean", description: "Refresh this model after each consolidation. Defaults OFF \u2014 refresh adds bounded background model-spend + timeout risk (RFC Phase 5). Only set true when the model genuinely needs to track fast-moving state." },
+          max_tokens: { type: "number", description: "Optional cap on the synthesized model's token size." },
+          message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message if not specified." }
+        },
+        required: ["chat_id", "name", "source_query"]
+      }
+    },
     {
       name: "linear_agent_activity",
       description: 'Emit a structured Linear AgentActivity against an agent session (#2298). Use this ONLY inside a turn that was woken by a Linear agent session (the inbound carries meta.source="linear" and meta.agent_session_id) \u2014 pass that agent_session_id back here. Linear renders activities as status chips + a timeline on the issue, so the human sees acknowledge \u2192 work \u2192 result. Emit a `thought` within ~10s of being woken so the session does not look dead, then `message`(s) as you make progress, and finally exactly one terminal `complete` (work done) or `error` (you could not proceed). body is required for thought/message/error and optional for complete. Resolves the agent\'s Linear app token from the vault; on VAULT-BROKER-DENIED it returns an error instructing you to vault_request_access for `linear/<agent>/token`.',
@@ -24804,6 +24873,8 @@ var init_bridge = __esm(async () => {
     }
   });
   sessionAllowRules = new Set;
+  outstandingPermissions = createOutstandingPermissionLedger();
+  permissionRearmEnabled = process.env.SWITCHROOM_PERMISSION_REARM !== "0";
   mcp.setNotificationHandler(exports_external.object({
     method: exports_external.literal("notifications/claude/channel/permission_request"),
     params: exports_external.object({
@@ -24825,9 +24896,22 @@ var init_bridge = __esm(async () => {
         return;
       }
     }
+    if (permissionRearmEnabled) {
+      outstandingPermissions.add({
+        request_id: params.request_id,
+        tool_name: params.tool_name,
+        description: params.description,
+        input_preview: params.input_preview
+      });
+    }
     if (!ipc || !ipc.isConnected()) {
-      process.stderr.write(`telegram bridge: permission_request received but not connected to gateway
+      if (permissionRearmEnabled) {
+        process.stderr.write(`telegram bridge: permission_request buffered (gateway offline), will re-send on reconnect ` + `request_id=${params.request_id}
+`);
+      } else {
+        process.stderr.write(`telegram bridge: permission_request received but not connected to gateway
 `);
+      }
       return;
     }
     ipc.sendPermissionRequest({

package/telegram-plugin/feed-heartbeat-climb.ts

@@ -0,0 +1,206 @@
+/**
+ * Deterministic silent-turn card climb — the framework owns "alive" and "for how
+ * long"; the model owns "what".
+ *
+ * Implements Phase 1 (the keystone) of `reference/rfcs/deterministic-turn-liveness.md`.
+ * Serves `reference/jobs/know-what-my-agent-is-doing.md` (outcome: at any moment
+ * during a turn the user can see the agent is alive and how long it has been
+ * working, without asking).
+ *
+ * ## The bug this closes
+ *
+ * On the 0-label path of `feedHeartbeatTick` (a turn that has surfaced NO tool
+ * label — a long single `Bash`, or only suppressed-by-design tools), the tick
+ * delegated to `openLivenessFeedIfDue`, whose WHEN-gate `shouldEarlyOpenLiveness`
+ * returns `false` the moment a card is already open (`activityMessageId != null`).
+ * Result: once the "Working…" card opened, the 0-label branch NEVER edited it
+ * again during a silent tool — the card froze on its opening elapsed while the
+ * agent was busy for tens of seconds. The only remaining signal was the ambient
+ * "stuck" reaction flip, which reads as *done*, not *working*.
+ *
+ * ## The fix
+ *
+ * Give the 0-label branch the SAME climbing-elapsed EDIT the labelled branch
+ * already performs: when a card is open and `mirrorLines` is empty, re-render the
+ * minimal "Working…" card with a fresh wall-clock elapsed on every heartbeat tick.
+ * The render is derived PURELY from `ageMs` (`now - turn.startedAt`), so a tool
+ * call blocked mid-flight — emitting nothing — cannot starve it. Worst-case gap
+ * between visible edits is one to two `FEED_HEARTBEAT_MIN_STALE_MS` windows
+ * (~6-12s), versus the observed ~50s freeze.
+ *
+ * This is a card EDIT, not a text send: it edits the card the chat already owns,
+ * and Telegram card edits do not push-notify — squarely the Ambient layer of
+ * `reference/rfcs/conversational-pacing.md`, crossing no invariant (no parallel
+ * surface, no mid-turn device buzz). When the model DOES narrate, its words land
+ * on the same card chronologically (`mirrorLines` becomes non-empty and the
+ * labelled-feed heartbeat takes over) — the climb fills only the gaps the model
+ * leaves and never overwrites narration.
+ *
+ * Kept as a small pure function so the guarantee can be proven at the transport
+ * boundary (Phase 4b regression test) rather than by grepping the gateway source.
+ */
+import {
+  renderActivityFeedWithNested,
+  formatStepSuffix,
+  type SessionActivityHeader,
+} from './tool-activity-summary.js'
+
+/** The minimal placeholder line the silent-turn card carries when no tool label
+ *  has surfaced. Matches `openLivenessFeedIfDue`'s open render so the climb edit
+ *  is a clean continuation of the placeholder the OPEN path produced. */
+export const SILENT_TURN_PLACEHOLDER = 'Working…'
+
+export interface SilentTurnClimbInput {
+  /** `turn.mirrorLines.length`. 0 ⇒ no tool label has surfaced this turn (pure
+   *  thinking / only suppressed tools) — the case this climb owns. >0 ⇒ a real
+   *  label drives the labelled-feed heartbeat, which owns the climb instead. */
+  mirrorLineCount: number
+  /** `turn.activityMessageId`. `null` ⇒ no card is open yet, so the OPEN path
+   *  (`openLivenessFeedIfDue`) owns this tick; non-null ⇒ a card is open and this
+   *  branch must keep it climbing (the exact freeze this fix closes). */
+  activityMessageId: number | null
+  /** `turn.labeledToolCount` — surfaced in the card header's tool count. */
+  labeledToolCount: number
+  /** `now - turn.startedAt`: wall-clock elapsed since turn start. The single
+   *  signal the model can never supply while blocked inside a tool. */
+  ageMs: number
+}
+
+/**
+ * The deterministic 0-label climb render. Returns the card body HTML to EDIT the
+ * already-open "Working…" card with a climbing wall-clock elapsed, or `null` when
+ * this branch must NOT edit:
+ *   - `mirrorLineCount > 0` — a tool label surfaced; the labelled-feed heartbeat
+ *     owns the climb (its edit cleanly replaces this placeholder).
+ *   - `activityMessageId == null` — no card is open yet; the OPEN path
+ *     (`openLivenessFeedIfDue`) owns this tick.
+ *
+ * The header's `elapsedMs` carries the climbing clock, so each tick's edit shows
+ * a higher "Working · Ns" than the last. Model-independent by construction: it
+ * reads only wall-clock `ageMs`.
+ */
+export function silentTurnClimbRender(input: SilentTurnClimbInput): string | null {
+  if (input.mirrorLineCount > 0) return null
+  if (input.activityMessageId == null) return null
+  const header: SessionActivityHeader = {
+    label: 'Agent',
+    elapsedMs: input.ageMs,
+    toolCount: input.labeledToolCount,
+    state: 'running',
+  }
+  // Single "step" whose start is the turn start, so `ageMs` IS the step's own
+  // elapsed. formatStepSuffix keeps the `→` line timer-free until STEP_TIMER_MIN_MS;
+  // the header total still climbs every tick — that is the visible clock.
+  return renderActivityFeedWithNested(
+    [SILENT_TURN_PLACEHOLDER],
+    [],
+    false,
+    formatStepSuffix(input.ageMs),
+    undefined,
+    header,
+  )
+}
+
+/**
+ * The per-turn view `runSilentTurnHeartbeatTick` reads — a structural subset of
+ * the gateway's `CurrentTurn`, kept transport-free so this module (and its test)
+ * never imports the gateway.
+ */
+export interface SilentTurnTickView {
+  /** `turn.mirrorLines.length` at tick time. */
+  mirrorLineCount: number
+  /** `turn.activityMessageId` at tick time (null ⇒ no card open yet). */
+  activityMessageId: number | null
+  /** `turn.labeledToolCount` — surfaced in the card header. */
+  labeledToolCount: number
+  /** `now - turn.startedAt` at tick time. */
+  ageMs: number
+  /** The labelled branch's stale floor (`FEED_HEARTBEAT_MIN_STALE_MS`). The
+   *  climb applies the SAME guard for symmetry: a turn younger than one stale
+   *  window is fresh (its card just opened ~1.2s in), so no climb edit yet.
+   *  Without this the climb relied on the tick interval == the stale window
+   *  (both 6s today) — an implicit coupling this guard makes explicit. */
+  minStaleMs: number
+}
+
+/**
+ * The gateway seams the tick drives, injected as thunks so THIS function — the
+ * shipped 0-label branch of `feedHeartbeatTick` — is directly executable in a
+ * test with spies at each seam. The gateway wires the real implementations
+ * (`openLivenessFeedIfDue`, `turn.activityPendingRender = …`, `cardDrainGate`,
+ * `ea.mayDrain`, `ea.openOrEditCard('liveness', …)`,
+ * `drainActivitySummary(turn, 'liveness')`); the wiring is pinned structurally
+ * in tests/feed-heartbeat-liveness-open.test.ts.
+ */
+export interface SilentTurnTickDeps {
+  /** The one shared OPEN path (`openLivenessFeedIfDue(turn)`). Owns the open;
+   *  the climb never opens (reply-is-last gating lives on the open path). */
+  openLivenessFeedIfDue: () => void
+  /** Stage the climb render (`turn.activityPendingRender = rendered`). */
+  setPendingRender: (rendered: string) => void
+  /** The centralized chatLock-serialized card-drain gate
+   *  (`cardDrainGate(turn, ea, run)`). */
+  cardDrainGate: (run: () => void) => void
+  /** The single-flight pure read (`ea.mayDrain(turn)`). */
+  mayDrain: () => boolean
+  /** The emission-authority façade routing (`ea.openOrEditCard('liveness', apply)`).
+   *  With a card open this only ever EDITs — Telegram edits don't push-notify. */
+  openOrEditCard: (apply: () => void) => void
+  /** The drain kick-off (`turn.activityInFlight = drainActivitySummary(turn,
+   *  'liveness')`) — the transport writer (sendMessage / editMessageText via
+   *  robustApiCall) lives behind this seam. */
+  drain: () => void
+}
+
+/**
+ * The REAL 0-label branch of `feedHeartbeatTick` (deterministic-turn-liveness.md
+ * Phase 1) — extracted here so the shipped decision logic is directly under
+ * outcome-based test (`tests/silent-turn-climb-transport.test.ts`); the gateway
+ * IIFE cannot be imported in-process, so the tick body lives in this module and
+ * the gateway calls it with its real deps.
+ *
+ * Returns true when the tick was handled by the 0-label path (the caller must
+ * stop — the labelled-feed heartbeat does not run), false when a tool label has
+ * surfaced (`mirrorLineCount > 0`) and the labelled branch owns the tick.
+ *
+ * Behaviour:
+ *   - no card open yet → delegate to the one shared OPEN path (never opens here);
+ *   - card open + turn younger than `minStaleMs` → fresh, no edit yet (the same
+ *     stale-guard the labelled branch applies to its step elapsed);
+ *   - card open + stale → stage the climbing "Working · Ns" render and EDIT it
+ *     through the same cardDrainGate → mayDrain → openOrEditCard → drain gate
+ *     sequence the labelled branch uses. Deterministic + framework-owned: reads
+ *     only wall-clock `ageMs`, so a blocked tool call cannot starve it.
+ */
+export function runSilentTurnHeartbeatTick(
+  view: SilentTurnTickView,
+  deps: SilentTurnTickDeps,
+): boolean {
+  if (view.mirrorLineCount !== 0) return false
+  if (view.activityMessageId == null) {
+    deps.openLivenessFeedIfDue()
+    return true
+  }
+  // Stale-guard (symmetry with the labelled branch's `elapsed <
+  // FEED_HEARTBEAT_MIN_STALE_MS` check): the 0-label "step" starts at turn
+  // start, so `ageMs` IS its elapsed. A younger turn's card just opened.
+  if (view.ageMs < view.minStaleMs) return true
+  const rendered = silentTurnClimbRender({
+    mirrorLineCount: view.mirrorLineCount,
+    activityMessageId: view.activityMessageId,
+    labeledToolCount: view.labeledToolCount,
+    ageMs: view.ageMs,
+  })
+  if (rendered == null) return true
+  deps.setPendingRender(rendered)
+  deps.cardDrainGate(() => {
+    if (deps.mayDrain()) {
+      // Maintains an already-open card (guarded above on activityMessageId !=
+      // null) → only ever EDITs. 'liveness' producer is correct.
+      deps.openOrEditCard(() => {
+        deps.drain()
+      })
+    }
+  })
+  return true
+}

package/telegram-plugin/gateway/activity-card-store.ts

@@ -0,0 +1,293 @@
+/**
+ * activity-card-store.ts — durable handle for the mid-turn activity card, so a
+ * gateway restart mid-turn can finalize the orphaned card instead of leaving it
+ * frozen forever.
+ *
+ * Why this exists (reference/rfcs/deterministic-turn-liveness.md Known Gap 1):
+ * `CurrentTurn.activityMessageId` / `startedAt` and the live `currentTurn`
+ * itself live ONLY in gateway memory. If the gateway restarts while a turn's
+ * activity card is open, the new process has no handle to the old card — it
+ * is never edited again and sits frozen on its last pre-restart text forever.
+ * The resumed turn (if any) opens a FRESH card; the old one is orphaned.
+ *
+ * The fix mirrors `status-pin-store.ts` byte-for-byte in shape: a tiny durable
+ * snapshot on the per-agent state volume (STATE_DIR), written whenever a card
+ * OPENS, cleared the moment it closes/finalizes normally. On boot, AFTER this
+ * gateway wins the startup mutex (same ordering constraint as the status-pin
+ * cleanup — this is a shared per-agent file, so a losing double-boot must
+ * never touch it), a one-shot reaper reads any leftover record and finalizes
+ * the orphaned card with a SINGLE honest edit (never a new message — edits do
+ * not notify, so no ping). We do NOT attempt to resume climbing the old card
+ * across the restart; the resumed turn (if any) owns a fresh card. Honest
+ * finalization — not resumption — is the goal.
+ *
+ * Crash-safety: write-tmp + atomic rename (identical convention to
+ * status-pin-store.ts / obligation-store.ts). A corrupt or unreadable file
+ * fails open to `[]` — never crashes boot, worst case an orphan isn't cleaned
+ * up this boot, no worse than pre-fix behaviour.
+ *
+ * DELIVERED GUARANTEE — AT-MOST-ONCE finalization (be honest about it):
+ * the reaper deletes a record from the on-disk store BEFORE attempting its
+ * finalizing edit (not after) and swallows every Telegram failure with no
+ * retry. That ordering buys strict idempotency — a crash mid-reap, or a second
+ * boot re-reading the file, can never double-edit or double-unpin the same
+ * message — at the cost of durability: if the single edit fails (flood-wait
+ * exhausted, transient 5xx, chat momentarily unreachable), the orphaned card is
+ * FORFEIT and stays frozen, because its record is already gone. So the promise
+ * is NOT "finalized on the very next boot" — it is "finalized AT MOST ONCE, on
+ * the next boot, best-effort". We deliberately chose at-most-once over
+ * at-least-once: a retry-until-success design cannot preserve the
+ * second-boot-zero-edits property across a crash between a successful edit and
+ * its post-edit delete (that window would re-edit an already-finalized card),
+ * and a stale re-finalize on a chat the user has since moved on from is a worse
+ * failure than one frozen orphan. A benign-400 (message already
+ * deleted/vanished, or "not modified") is NOT counted as a finalize — nothing
+ * was delivered — see the `vanished` tally in `runActivityCardBootReaper`.
+ */
+
+export interface ActivityCardStoreFsSeam {
+  readFileSync: (path: string) => string
+  writeFileSync: (path: string, data: string) => void
+  /** Atomic same-dir replace (POSIX rename) so a crash mid-write can't tear
+   *  the snapshot. */
+  renameSync: (from: string, to: string) => void
+  existsSync: (path: string) => boolean
+}
+
+/** One persisted card handle: enough to identify and finalize the orphaned
+ *  Telegram message on a future boot, without any live turn state. */
+export interface ActivityCardRecord {
+  /** Stable per-topic key (`statusKey(chatId, threadId)` shape) — also the
+   *  upsert key: a fresh OPEN for the same topic replaces any stale row. */
+  turnKey: string
+  chatId: string
+  threadId: number | null
+  activityMessageId: number
+  /** Wall-clock ms the turn started — carried through so the finalize text
+   *  can be honest about elapsed time even after a restart. */
+  startedAt: number
+  /** Whether this card was silently pinned when it opened (the gateway pins
+   *  every fresh activity card via `reconcileStatusPin('fg:'+turnKey, …)`).
+   *  The boot reaper must unpin it too — a frozen card that's ALSO still
+   *  pinned is a worse orphan (it stays glued to the top of the chat
+   *  forever). Optional so a v1-shape record (pre-unpin-tracking) still
+   *  loads and degrades to "don't attempt an unpin", never a crash. */
+  pinned?: boolean
+}
+
+interface SnapshotEnvelope {
+  v: 1
+  cards: ActivityCardRecord[]
+}
+
+function isCardRow(x: unknown): x is ActivityCardRecord {
+  if (x == null || typeof x !== 'object') return false
+  const o = x as Record<string, unknown>
+  return (
+    typeof o.turnKey === 'string' &&
+    o.turnKey.length > 0 &&
+    typeof o.chatId === 'string' &&
+    o.chatId.length > 0 &&
+    (o.threadId === null || typeof o.threadId === 'number') &&
+    typeof o.activityMessageId === 'number' &&
+    typeof o.startedAt === 'number' &&
+    (o.pinned === undefined || typeof o.pinned === 'boolean')
+  )
+}
+
+/**
+ * Load the persisted card-handle set. Returns [] on a missing, unreadable, or
+ * malformed file — fail-open, never throws.
+ */
+export function loadActivityCards(
+  path: string,
+  fs: ActivityCardStoreFsSeam,
+): ActivityCardRecord[] {
+  if (!fs.existsSync(path)) return []
+  let raw = ''
+  try {
+    raw = fs.readFileSync(path)
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (parsed == null || typeof parsed !== 'object') return []
+  const env = parsed as Record<string, unknown>
+  if (env.v !== 1 || !Array.isArray(env.cards)) return []
+  return env.cards.filter(isCardRow)
+}
+
+/**
+ * Persist the card-handle set atomically (write sibling tmp → rename). Never
+ * throws — a write failure is logged and the store degrades to in-memory-only
+ * for this process (same contract as `status-pin-store.ts`).
+ */
+export function persistActivityCards(
+  path: string,
+  fs: ActivityCardStoreFsSeam,
+  snapshot: readonly ActivityCardRecord[],
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const env: SnapshotEnvelope = { v: 1, cards: [...snapshot] }
+  const tmp = path + '.tmp'
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(env))
+    fs.renameSync(tmp, path)
+  } catch (err) {
+    log(
+      `activity-card-store: persist FAILED path=${path}: ${(err as Error).message} — ` +
+        `durability degraded to in-memory\n`,
+    )
+  }
+}
+
+/**
+ * Upsert the card-handle row for `turnKey` (replacing any stale row for the
+ * same topic — e.g. a prior turn's card that was never cleared). Called the
+ * moment a card OPENs (activityMessageId transitions null → set).
+ */
+export function writeActivityCardRecord(
+  path: string,
+  fs: ActivityCardStoreFsSeam,
+  record: ActivityCardRecord,
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const current = loadActivityCards(path, fs)
+  const others = current.filter((c) => c.turnKey !== record.turnKey)
+  persistActivityCards(path, fs, [...others, record], log)
+}
+
+/**
+ * Remove the card-handle row for `turnKey`, if present. Called the moment a
+ * card closes/finalizes normally (clearActivitySummary), and by the boot
+ * reaper (BEFORE attempting the finalizing edit — the idempotency guard).
+ *
+ * REAP-RACE guard: when `activityMessageId` is supplied, only a row matching
+ * BOTH `turnKey` AND `activityMessageId` is removed. During a slow multi-record
+ * reap (e.g. a 429 flood-wait between records), a fresh live turn can upsert a
+ * NEW record under the same `turnKey` (its own, different `activityMessageId`).
+ * A turnKey-only clear would then delete the LIVE card's durable protection.
+ * Scoping the clear to the exact message id the reaper (or the closing turn) is
+ * handling leaves the live card's record intact. Omit `activityMessageId` only
+ * when you genuinely mean "clear whatever row exists for this topic".
+ */
+export function clearActivityCardRecord(
+  path: string,
+  fs: ActivityCardStoreFsSeam,
+  turnKey: string,
+  activityMessageId?: number,
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const current = loadActivityCards(path, fs)
+  if (current.length === 0) return
+  const next = current.filter(
+    (c) =>
+      c.turnKey !== turnKey ||
+      (activityMessageId !== undefined && c.activityMessageId !== activityMessageId),
+  )
+  if (next.length === current.length) return
+  persistActivityCards(path, fs, next, log)
+}
+
+/**
+ * Boot-time orphan reaper, extracted as a pure routine over injected seams
+ * (mirrors `runStatusPinBootCleanup`). The gateway's thin wrapper binds the
+ * live fs, a Telegram edit call, and the logger.
+ *
+ * CRITICAL ordering, identical constraint to the status-pin cleanup: the
+ * caller MUST only invoke this AFTER winning the startup mutex. The store is
+ * a shared per-agent file; a losing double-boot running this would finalize
+ * cards the still-alive holder's in-flight turn still legitimately owns.
+ *
+ * Deletes each record from disk BEFORE attempting its edit/unpin (not
+ * after), so a crash mid-reap, or a second boot re-reading the file, can
+ * never re-finalize (and thus never double-edit, never double-unpin) the
+ * same message. `finalizeCard` / `unpinCard` failures (message already
+ * deleted, chat unreachable, permissions changed, already-unpinned, etc.)
+ * are swallowed — non-fatal, logged, and never re-attempted since the
+ * record is already gone.
+ *
+ * Unpin runs AFTER the finalizing edit, only for a record with `pinned:
+ * true` (a v1-shape record with no `pinned` field is left un-unpinned —
+ * conservative degrade, not a crash), and its failure is independent of the
+ * edit's outcome (an edit failure — e.g. message already deleted — must not
+ * skip the unpin attempt, since Telegram allows unpinning a deleted
+ * message's id to no-op harmlessly, and conversely an unpin failure must
+ * never re-attempt the edit).
+ */
+export async function runActivityCardBootReaper(args: {
+  path: string
+  fs: ActivityCardStoreFsSeam
+  /** Returns the Telegram result: a truthy value (the edited Message) on a
+   *  real delivered edit, or `null`/`undefined` when the underlying
+   *  `robustApiCall` swallowed a benign 400 (message already deleted /
+   *  vanished / "not modified") — i.e. nothing was actually finalized. */
+  finalizeCard: (record: ActivityCardRecord) => Promise<unknown>
+  unpinCard: (record: ActivityCardRecord) => Promise<unknown>
+  log?: (line: string) => void
+}): Promise<{ finalized: number; vanished: number; unpinned: number; total: number }> {
+  const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const persisted = loadActivityCards(args.path, args.fs)
+  if (persisted.length === 0) return { finalized: 0, vanished: 0, unpinned: 0, total: 0 }
+  let finalized = 0
+  let vanished = 0
+  let unpinned = 0
+  for (const record of persisted) {
+    // Delete BEFORE attempting the edit/unpin — the idempotency guard. If the
+    // gateway crashes here, or a second boot re-reads the file, this record
+    // no longer exists on disk, so it can never be finalized or unpinned
+    // twice. Scoped to the exact activityMessageId (reap-race guard): a live
+    // turn that upserted a fresh card under the same turnKey mid-reap keeps
+    // its own (different-id) record.
+    clearActivityCardRecord(args.path, args.fs, record.turnKey, record.activityMessageId, log)
+    try {
+      // Count a finalize ONLY when the edit actually landed. robustApiCall
+      // resolves to undefined on a benign-400 (the card was already deleted or
+      // the chat is gone) — that delivered nothing, so it is a `vanished`
+      // orphan, not a `finalized` one. Counting it as finalized (the pre-fix
+      // behaviour) over-reported the guarantee in the boot log.
+      const res = await args.finalizeCard(record)
+      if (res != null) finalized++
+      else vanished++
+    } catch (err) {
+      log(
+        `activity-card-store: boot reaper finalize failed ` +
+          `(chat=${record.chatId} msg=${record.activityMessageId}): ` +
+          `${(err as Error).message}\n`,
+      )
+    }
+    if (record.pinned) {
+      try {
+        await args.unpinCard(record)
+        unpinned++
+      } catch (err) {
+        log(
+          `activity-card-store: boot reaper unpin failed ` +
+            `(chat=${record.chatId} msg=${record.activityMessageId}): ` +
+            `${(err as Error).message}\n`,
+        )
+      }
+    }
+  }
+  return { finalized, vanished, unpinned, total: persisted.length }
+}
+
+/**
+ * Honest finalize text for an orphaned card — the single edit the boot
+ * reaper applies. Mirrors `silentEndFallbackText`'s honesty-about-elapsed
+ * convention (`telegram-plugin/silent-end.ts`): degenerate/unknown durations
+ * omit the elapsed clause rather than printing a nonsensical "(0s)".
+ */
+export function restartOrphanCardFinalizeText(startedAt: number): string {
+  const elapsedMs = Date.now() - startedAt
+  const elapsed =
+    Number.isFinite(elapsedMs) && elapsedMs > 0
+      ? ` (was running ${Math.round(elapsedMs / 1000)}s)`
+      : ''
+  return `⚠️ Interrupted by a gateway restart${elapsed} — this turn did not finish.`
+}

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

@@ -403,7 +403,7 @@ export async function handleAuthCommand(
       let keyboard: AuthCommandReply['keyboard']
       if (liveQuotas && liveQuotas.length === state.accounts.length) {
         const snapshots = buildSnapshotsFromState(state, liveQuotas)
-        keyboard = buildSnapshotKeyboard(snapshots, { now: new Date() })
+        keyboard = buildSnapshotKeyboard(snapshots, { now: new Date(), demo: ctx.demo })
       }
       return {
         text: renderShowText(state, Date.now(), {