switchroom 0.18.7 → 0.18.8

package/telegram-plugin/gateway/mental-model-propose-diff.ts

@@ -27,6 +27,49 @@
 import { parseDocument } from "yaml";
 import { generateUnifiedDiff } from "../../src/web/config-diff.js";
 
+/**
+ * Decode the canonical six HTML/XML entities to their literal characters — the
+ * config-write-boundary layer of the #2976 defense-in-depth.
+ *
+ * SCOPE / reachability (be honest about which half is load-bearing):
+ *   - `source_query` decode is the REACHABLE half. A model can copy escaped
+ *     entities out of its Telegram-HTML-rendered context into a proposal's
+ *     free-form `source_query`, and undecoded it would steer recall on `R&D`
+ *     instead of `R&D` — a durable, silent corruption of a memory-integrity
+ *     field. Normalizing here means an escaped query can never LAND in
+ *     `memory.mental_models[]`.
+ *   - `name` decode is REDUNDANT belt-and-suspenders. The `mental_model_propose`
+ *     gateway tool already slug-validates `name` against
+ *     /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/ BEFORE this runs, so an entity-bearing
+ *     name is rejected upstream and can't reach here. It's kept only so this
+ *     write boundary is self-contained if that gate ever moves.
+ *   - The observed in-NAME corruption (`Nutrition Protocol & Deficit Status`,
+ *     klanker 2026-07-06) actually arrived via the DIRECT `create_mental_model`
+ *     Hindsight tool (`ensureMentalModel`, undecoded), NOT this propose path.
+ *     That vector is OUT OF SCOPE here — covered by the steering.ts context-
+ *     hygiene + in-service `Dockerfile.hindsight` normalization follow-ups.
+ *
+ * SINGLE PASS by design (matches issue #2976's success criteria): a
+ * double-escaped `R&D` decodes ONE layer to `R&D`, not all the way
+ * to `R&D` — we only undo the escaping switchroom itself applied when it
+ * rendered the model's prior output, never the user's literal intent. `&`
+ * is decoded LAST so `&amp;lt;` collapses to `&lt;` (one layer), not `<`.
+ *
+ * Accepted tradeoff: a `source_query` a human genuinely intended to contain a
+ * literal `&amp;` / `&lt;` / etc. (rare — a reflection question, not markup)
+ * will have that one layer decoded. Steering queries reading as escaped HTML is
+ * the far more common and more harmful case, so we optimize for it.
+ */
+export function decodeCanonicalEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
 /**
  * A proposed mental model, in the same snake_case shape the
  * `memory.mental_models[]` schema (#2874) accepts. `name` + `source_query`
@@ -125,20 +168,33 @@ export function buildMentalModelAppendDiff(args: {
   }
 
   // Duplicate-name guard (defense-in-depth; the executor also checks up front
-  // so it never even posts a card for a dupe).
+  // so it never even posts a card for a dupe). Compare on the DECODED name so a
+  // re-propose of an entity-escaped variant collides with the already-stored
+  // literal (#2976) rather than sneaking in a corrupted twin.
+  const decodedName = decodeCanonicalEntities(spec.name);
   const existing = readDeclaredMentalModelNames(configText, agentName);
-  if (existing.includes(spec.name)) {
+  if (existing.includes(decodedName)) {
     return {
       ok: false,
       error: "duplicate",
-      detail: `mental model "${spec.name}" is already declared for ${agentName}`,
+      detail: `mental model "${decodedName}" is already declared for ${agentName}`,
     };
   }
 
+  // #2976 write-boundary normalization: decode any HTML/XML entities the model
+  // may have copied out of its own escaped context so the LITERAL characters
+  // land in config — never `&amp;` / `&lt;` etc. The load-bearing target is the
+  // free-form `source_query`; the `name` decode is redundant with the gateway
+  // slug gate (an entity-bearing name is rejected upstream) and kept only so
+  // this boundary is self-contained. Duplicate-name guard runs on the decoded
+  // name above.
+  const name = decodedName;
+  const source_query = decodeCanonicalEntities(spec.source_query);
+
   // Assemble the minimal, schema-clean declaration node.
   const item: Record<string, unknown> = {
-    name: spec.name,
-    source_query: spec.source_query,
+    name,
+    source_query,
   };
   if (spec.refresh_after_consolidation !== undefined) {
     item.refresh_after_consolidation = spec.refresh_after_consolidation;

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

@@ -149,7 +149,7 @@ export interface ModelCommandDeps {
    * Schedule a session-only switch TO a non-Claude (`sr-*` LiteLLM/OpenRouter)
    * model. claude's in-REPL `/model` picker rejects unknown `sr-*` ids, so an
    * inject can't set them. Instead the gateway writes the chosen token to the
-   * `.session-model-override` carrier file and gracefully restarts the agent;
+   * durable `.session-model` override and gracefully restarts the agent;
    * the next boot launches `claude --model <token>` directly (LiteLLM routes
    * it, no picker validation). Session-only: reverts to the configured default
    * on the following restart. Wired to the same restart dispatch as
@@ -175,7 +175,7 @@ export interface ModelCommandReply {
 }
 
 const PERSIST_NOTE =
-  '_Session-only — lasts until restart. To persist, set \`model:\` in switchroom.yaml and restart._'
+  '_Sticky across switchroom-managed relaunches (\`/new\`, watchdog recovery); reverts on \`/restart\`, agent restart, crash, or external container restart. \`/model default\` clears it. To persist, set \`model:\` in switchroom.yaml._'
 
 function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
   const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `\`${a}\``).join(' · ')
@@ -240,7 +240,7 @@ export async function handleModelCommand(
   // the proxy at session start, not by claude's own REPL. A graceful restart
   // is the only clean path back to the native OAuth route. Route it through the
   // SAME carrier mechanism as a Claude → sr-* switch (scheduleModelRelaunch)
-  // so the requested Claude model is written to `.session-model-override` and
+  // so the requested Claude model is written to the durable `.session-model` and
   // survives the restart — otherwise boot launches the configured default and
   // the operator's choice is silently dropped. start.sh's LiteLLM-down guard
   // only special-cases `sr-*` overrides, so a Claude token is never dropped.
@@ -294,7 +294,7 @@ export async function handleModelCommand(
     return {
       text: [
         `Switching to \`${deps.escapeHtml(model)}\` — restarting session (~30s).`,
-        '_Session-only — reverts to the configured default on the next restart._',
+        PERSIST_NOTE,
       ].join('\n'),
       html: true,
     }
@@ -744,13 +744,20 @@ export interface ModelCallbackOutcome {
   /**
    * The canonical `claude --model` token (alias or full `claude-*` id) for a
    * Claude selection, when derivable — distinct from `selectedModel` (a display
-   * name for /status). The gateway writes this to the `.session-model-override`
-   * carrier on an sr-* → Claude transition so the requested Claude model survives
-   * the restart (otherwise boot launches the configured default). Absent when the
-   * target has no derivable token (e.g. the "Default" row → boot the configured
-   * default).
+   * name for /status). The gateway persists this to the durable
+   * `.session-model` override so the confirmed switch survives
+   * switchroom-managed relaunches (and, on an sr-* → Claude transition, its own
+   * restart). Absent when the target has no derivable token.
    */
   selectedModelToken?: string
+  /**
+   * True when the confirmed selection was the "Default (recommended)" row —
+   * i.e. the session is now on the configured default and any sticky
+   * `.session-model` override must be CLEARED (there is no token to persist;
+   * persisting nothing while leaving a stale override would re-apply the old
+   * model on the next keep-relaunch).
+   */
+  clearedDefault?: boolean
   /** Short toast for answerCallbackQuery. */
   answer: string
   /** Replacement dashboard (message edit). */
@@ -872,7 +879,7 @@ export async function handleModelMenuCallback(
       answer: `Switching to ${friendlyName} — restarting (~30s)`,
       reply: await menuWithBannerStatic(
         deps,
-        `🔄 Switching session to **${deps.escapeHtml(friendlyName)}** — restarting (~30s). _Session-only; reverts to the configured default on the next restart._`,
+        `🔄 Switching session to **${deps.escapeHtml(friendlyName)}** — restarting (~30s).\n${PERSIST_NOTE}`,
       ),
       selectedModel: srName,
     }
@@ -949,11 +956,16 @@ export async function handleModelMenuCallback(
   // "Default (recommended)". If neither resolves, record nothing rather than lie.
   const token = canonicalClaudeToken(target.label)
   const selectedModel = sessionModelFromConfirmation(result.confirmation) ?? token ?? undefined
+  // The "Default (recommended)" row has no derivable token BY DESIGN — a
+  // confirmed switch to it means "back on the configured default", which the
+  // gateway must translate into clearing the sticky override.
+  const clearedDefault = token == null && /^default\b/i.test(target.label.trim())
   return {
     answer: deps.escapeHtml(result.confirmation),
     reply: await menuWithBanner(deps, `✅ ${deps.escapeHtml(result.confirmation)}`),
     ...(selectedModel ? { selectedModel } : {}),
     ...(token ? { selectedModelToken: token } : {}),
+    ...(clearedDefault ? { clearedDefault: true } : {}),
   }
 }
 
@@ -1030,7 +1042,7 @@ export function isKeptModelConfirmation(confirmation: string): boolean {
 
 /**
  * Normalize a picker ROW LABEL to a canonical `claude --model` token suitable
- * for the `.session-model-override` carrier (aliases and full `claude-*` ids —
+ * for the durable `.session-model` override (aliases and full `claude-*` ids —
  * NOT display strings like "Default (recommended)" or "Opus 4.8", which the CLI
  * flag rejects). Returns null when the label is a pure display label with no
  * derivable token: for the "Default" row that correctly means "boot the

package/telegram-plugin/gateway/session-model-file.ts

@@ -0,0 +1,198 @@
+/**
+ * Durable session-model stickiness — file helpers shared by the gateway.
+ *
+ * Two files in the bind-mounted agent state dir carry the contract
+ * (reference/rfcs/session-model-stickiness.md):
+ *
+ *   - `.session-model` — the DURABLE session override written on every
+ *     positively-confirmed `/model` switch. One-line JSON
+ *     `{"model","configuredDefaultAtWrite","ts"}`. It is NOT consumed by a
+ *     keep-path boot; start.sh deletes it on revert / invalidation /
+ *     corruption / 7-day staleness, and the gateway deletes it on
+ *     `/model default`.
+ *
+ *   - `.relaunch-model-intent` — the ONE-SHOT intent bit for the next boot.
+ *     One-line JSON `{"intent":"keep"|"revert","reason","ts"}`, atomic
+ *     write, last-writer-wins. Boot default is REVERT (operator decision:
+ *     a raw `docker restart` / host reboot / crash must revert to the yaml
+ *     model), so every switchroom-managed KEEP path must stamp keep-intent
+ *     BEFORE the bounce. start.sh consumes it (rm -f) every boot; a stale
+ *     (>10 min by the embedded ts) or corrupt intent counts as no intent.
+ *
+ * The `model` token is always a canonical `claude --model` token (alias,
+ * `claude-*` id, or `sr-*` id) — NEVER a display label like "Opus 4.8".
+ * Shape-gated on write with the same regex start.sh greps with.
+ */
+
+import { readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { isValidModelArg } from './model-command.js'
+
+export const SESSION_MODEL_FILE = '.session-model'
+export const RELAUNCH_MODEL_INTENT_FILE = '.relaunch-model-intent'
+export const CONFIGURED_DEFAULT_MODEL_FILE = '.configured-default-model'
+
+export type RelaunchModelIntent = 'keep' | 'revert'
+
+export interface SessionModelRecord {
+  model: string
+  configuredDefaultAtWrite: string
+  ts: number
+}
+
+/**
+ * Restart reasons whose semantics are "revert the session model to the
+ * configured default". Everything else `triggerSelfRestart` fires with is a
+ * switchroom-managed relaunch (watchdog recovery, drain-cap bounce,
+ * turn-complete deferred restart, fleet-fallback resume, sr-to-claude model
+ * switch, grant restarts) and KEEPS the override — the whole point of the
+ * stickiness contract. Enumerated in the RFC §3; default-keep here is safe
+ * because only gateway code calls triggerSelfRestart, and a bounce nobody
+ * stamped (crash, raw docker restart, deploy) reverts by boot default anyway.
+ */
+const REVERT_RESTART_REASONS: ReadonlySet<string> = new Set(['inline-button-restart'])
+
+/** Classify a triggerSelfRestart reason into the intent the boot should honor. */
+export function intentForRestartReason(reason: string): RelaunchModelIntent {
+  return REVERT_RESTART_REASONS.has(reason) ? 'revert' : 'keep'
+}
+
+function atomicWrite(path: string, content: string): void {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(tmp, content, 'utf8')
+  renameSync(tmp, path)
+}
+
+/** Serialize a `.session-model` record (one line + trailing newline). */
+export function serializeSessionModel(rec: SessionModelRecord): string {
+  return `${JSON.stringify({
+    model: rec.model,
+    configuredDefaultAtWrite: rec.configuredDefaultAtWrite,
+    ts: rec.ts,
+  })}\n`
+}
+
+/**
+ * Parse `.session-model` content. Returns null on corrupt JSON, a missing /
+ * non-string field, or a model token that fails the MODEL_ARG_RE shape gate
+ * (never trust an unvalidated string near `claude --model`).
+ */
+export function parseSessionModel(text: string): SessionModelRecord | null {
+  try {
+    const raw = JSON.parse(text) as Partial<SessionModelRecord>
+    if (
+      typeof raw.model !== 'string' ||
+      typeof raw.configuredDefaultAtWrite !== 'string' ||
+      typeof raw.ts !== 'number' ||
+      !isValidModelArg(raw.model)
+    ) {
+      return null
+    }
+    return { model: raw.model, configuredDefaultAtWrite: raw.configuredDefaultAtWrite, ts: raw.ts }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write the durable session override. Throws on a non-canonical token —
+ * callers must pass a `claude --model` token, never a display label
+ * (regression guard for the "Opus 4.5 persisted" class).
+ */
+export function writeSessionModelFile(
+  agentDir: string,
+  model: string,
+  configuredDefaultAtWrite: string,
+): void {
+  if (!isValidModelArg(model)) {
+    throw new Error(`refusing to persist non-canonical session model token: ${JSON.stringify(model)}`)
+  }
+  atomicWrite(
+    join(agentDir, SESSION_MODEL_FILE),
+    serializeSessionModel({ model, configuredDefaultAtWrite, ts: Date.now() }),
+  )
+}
+
+/** Raw file text (for rollback snapshots), or null when absent/unreadable. */
+export function readSessionModelFileRaw(agentDir: string): string | null {
+  try {
+    return readFileSync(join(agentDir, SESSION_MODEL_FILE), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** Parsed durable override, or null when absent/corrupt. */
+export function readSessionModelFile(agentDir: string): SessionModelRecord | null {
+  const raw = readSessionModelFileRaw(agentDir)
+  return raw == null ? null : parseSessionModel(raw)
+}
+
+/** Delete the durable override (`/model default`, rollback). Best-effort. */
+export function clearSessionModelFile(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, SESSION_MODEL_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Restore a rollback snapshot taken with readSessionModelFileRaw. */
+export function restoreSessionModelFileRaw(agentDir: string, raw: string | null): void {
+  if (raw == null) {
+    clearSessionModelFile(agentDir)
+    return
+  }
+  try {
+    atomicWrite(join(agentDir, SESSION_MODEL_FILE), raw)
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Stamp the one-shot relaunch intent. MUST be called synchronously BEFORE
+ * the restart signal/dispatch it describes (write-before-kill invariant —
+ * the next start.sh boot reads this to decide keep vs revert). Best-effort:
+ * a failed write means the boot falls back to the default (revert), which
+ * is the safe side.
+ */
+export function writeRelaunchModelIntent(
+  agentDir: string,
+  intent: RelaunchModelIntent,
+  reason: string,
+): void {
+  try {
+    atomicWrite(
+      join(agentDir, RELAUNCH_MODEL_INTENT_FILE),
+      `${JSON.stringify({ intent, reason, ts: Date.now() })}\n`,
+    )
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: relaunch-model-intent write failed (boot will revert): ${(err as Error)?.message ?? String(err)}\n`,
+    )
+  }
+}
+
+/** Remove a stamped intent (rollback of a failed dispatch). Best-effort. */
+export function clearRelaunchModelIntent(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, RELAUNCH_MODEL_INTENT_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * The resolved configured default start.sh recorded this boot
+ * (`.configured-default-model`, written before override resolution — the
+ * same resolver output the invalidation compare uses). Null when missing.
+ */
+export function readConfiguredDefaultModel(agentDir: string): string | null {
+  try {
+    const v = readFileSync(join(agentDir, CONFIGURED_DEFAULT_MODEL_FILE), 'utf8').trim()
+    return v.length > 0 ? v : null
+  } catch {
+    return null
+  }
+}

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

@@ -12,10 +12,13 @@
  * a dead session lingers.
  *
  * This makes cleanup self-contained across restart: every pin claim persists
- * here; on boot the gateway loads the persisted set and unpins each entry
- * (a status pin from a PRIOR session is stale by definition — the turn it
- * represented is over or crashed), then clears the store. It does NOT re-adopt
- * or re-pin — it only cleans up.
+ * here; on boot the gateway loads the persisted set and unpins each
+ * work-scoped entry (a status pin from a PRIOR session is stale by definition
+ * — the turn it represented is over or crashed), dropping rows only after a
+ * successful unpin (failed ones are retained with an attempt counter for a
+ * next-boot retry — see runStatusPinBootCleanup). Time-scoped `tool:` rows
+ * (the `pin_message` MCP tool, #3001) survive boots until their `expiresAt`.
+ * It does NOT re-adopt or re-pin — it only cleans up.
  *
  * Shape choice — SNAPSHOT, not append-log, mirroring obligation-store.ts. The
  * claim set is tiny and bounded (one entry per in-flight pinned key, normally
@@ -55,8 +58,27 @@ export interface PersistedStatusPin {
   messageId: number
   /** True while the pin API call is in-flight / unconfirmed (see above). */
   pending?: boolean
+  /** Wall-clock ms after which this pin is stale and boot cleanup unpins it.
+   *  Rows WITHOUT this field are work-scoped (fg:/wk:/banner:) — stale the
+   *  moment their owning session dies, so boot cleanup unpins them
+   *  unconditionally. Rows WITH it (the `tool:` pins written by the
+   *  `pin_message` MCP tool, #3001) represent deliberate agent pins that have
+   *  no "work finished" event: they SURVIVE restarts and are only swept once
+   *  expired. */
+  expiresAt?: number
+  /** Boot-cleanup unpin retry counter (#3001). Incremented each boot the
+   *  unpin fails (flood-wait exhausted / transient 5xx); the row is retained
+   *  for retry until BOOT_UNPIN_MAX_ATTEMPTS, then forfeited. Absent = 0. */
+  attempts?: number
 }
 
+/** How many boots may retry a failing boot-cleanup unpin before the row is
+ *  forfeited. Unpins are idempotent (unpinning an already-unpinned or deleted
+ *  message no-ops), so retrying across boots is safe; the cap only bounds a
+ *  permanently-undeliverable unpin (chat gone, bot removed) so it cannot
+ *  re-fail on every boot forever. */
+export const BOOT_UNPIN_MAX_ATTEMPTS = 5
+
 /** Envelope version. v1 had no `pending` field; a v1 row loads as a confirmed
  *  pin (pending undefined). v2 adds the optional `pending` flag. Both load
  *  fail-open — an unknown/newer version yields []. */
@@ -74,7 +96,9 @@ function isPinRow(x: unknown): x is PersistedStatusPin {
     typeof o.chatId === 'string' &&
     o.chatId.length > 0 &&
     typeof o.messageId === 'number' &&
-    (o.pending === undefined || typeof o.pending === 'boolean')
+    (o.pending === undefined || typeof o.pending === 'boolean') &&
+    (o.expiresAt === undefined || typeof o.expiresAt === 'number') &&
+    (o.attempts === undefined || typeof o.attempts === 'number')
   )
 }
 
@@ -170,16 +194,27 @@ export function pinnedMessageIsOurs(
  * the ordering + best-effort contract is unit-testable against the REAL code
  * (the gateway's thin wrapper just binds the live fs / unpin api / logger).
  *
- * Any pin persisted by a PRIOR session is stale by definition — its turn ended
- * or the session crashed before its unpin reconcile ran. This includes records
- * left `pending` (the persist-intent-first write from `reconcileAndPersist-
- * StatusPin`): a crash between the pin API call and its confirming rewrite
- * leaves a pending record whose pin MAY have landed in Telegram, so we must
- * treat it exactly like a confirmed one and unpin it. We therefore best-effort
- * unpin EVERY persisted entry (confirmed and pending alike — a failure is
- * non-fatal) and then EMPTY the store regardless, so a permanently-
- * undeliverable unpin can't re-run on every boot. We do NOT re-adopt or re-pin.
- * Returns the counts for logging/testing.
+ * The restart rule (#3001): a WORK-SCOPED pin persisted by a PRIOR session
+ * (fg:/wk:/banner: — any row without `expiresAt`) is stale by definition — its
+ * work ended or the session crashed before its unpin reconcile ran, so
+ * restart = reset: it is unpinned here. This includes records left `pending`
+ * (the persist-intent-first write from `reconcileAndPersistStatusPin`): a
+ * crash between the pin API call and its confirming rewrite leaves a pending
+ * record whose pin MAY have landed in Telegram, so we must treat it exactly
+ * like a confirmed one and unpin it.
+ *
+ * TIME-SCOPED rows (`tool:` pins from the `pin_message` MCP tool, carrying
+ * `expiresAt`) have no "work finished" event, so a restart does NOT reset
+ * them: an unexpired row is RETAINED untouched across boots and only unpinned
+ * once `now >= expiresAt`.
+ *
+ * RETRY-SAFETY (#3001): a row is dropped only AFTER its unpin resolves. A
+ * failing unpin (flood-wait exhausted / transient 5xx) retains the row with an
+ * incremented `attempts` counter so the NEXT boot retries, up to
+ * BOOT_UNPIN_MAX_ATTEMPTS — then the row is forfeited (a permanently-
+ * undeliverable unpin must not re-fail on every boot forever). Unpins are
+ * idempotent, so the retry can never double-unpin harmfully. We do NOT
+ * re-adopt or re-pin. Returns the counts for logging/testing.
  *
  * CRITICAL: the caller MUST only invoke this AFTER winning the startup mutex.
  * The store is a shared per-agent file; on a double-boot a losing gateway
@@ -189,27 +224,52 @@ export async function runStatusPinBootCleanup(args: {
   path: string
   fs: StatusPinStoreFsSeam
   unpin: (chatId: string, messageId: number) => Promise<unknown>
+  now?: number
   log?: (line: string) => void
-}): Promise<{ cleared: number; total: number }> {
+}): Promise<{ cleared: number; retained: number; kept: number; total: number }> {
   const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const now = args.now ?? Date.now()
   const persisted = loadStatusPins(args.path, args.fs)
-  if (persisted.length === 0) return { cleared: 0, total: 0 }
+  if (persisted.length === 0) return { cleared: 0, retained: 0, kept: 0, total: 0 }
   let cleared = 0
+  let retained = 0
+  let kept = 0
+  const next: PersistedStatusPin[] = []
   for (const pin of persisted) {
+    // Unexpired time-scoped row (tool: pin): deliberately survives the
+    // restart — keep it as-is, no unpin.
+    if (pin.expiresAt != null && pin.expiresAt > now) {
+      next.push(pin)
+      kept++
+      continue
+    }
     try {
       await args.unpin(pin.chatId, pin.messageId)
       cleared++
     } catch (err) {
+      const attempts = (pin.attempts ?? 0) + 1
       log(
         `status-pin-store: boot cleanup unpin failed ` +
-          `(chat=${pin.chatId} msg=${pin.messageId}): ${(err as Error).message}\n`,
+          `(chat=${pin.chatId} msg=${pin.messageId} attempt=${attempts}): ` +
+          `${(err as Error).message}\n`,
       )
+      if (attempts < BOOT_UNPIN_MAX_ATTEMPTS) {
+        // Retain for a retry on the next boot instead of forfeiting the
+        // orphan permanently (retry-safe boot sweep, #3001).
+        next.push({ ...pin, attempts })
+        retained++
+      } else {
+        log(
+          `status-pin-store: boot cleanup FORFEITING pin after ` +
+            `${attempts} failed unpin attempts ` +
+            `(key=${pin.pinKey} chat=${pin.chatId} msg=${pin.messageId}) — ` +
+            `will not retry again\n`,
+        )
+      }
     }
   }
-  // Empty the store regardless — these claims belong to a dead session; leaving
-  // them would re-attempt the same (already-tried) unpins on every future boot.
-  persistStatusPins(args.path, args.fs, [], log)
-  return { cleared, total: persisted.length }
+  persistStatusPins(args.path, args.fs, next, log)
+  return { cleared, retained, kept, total: persisted.length }
 }
 
 /**

package/telegram-plugin/gateway/worker-pin-reaper.ts

@@ -0,0 +1,114 @@
+/**
+ * worker-pin-reaper.ts — pure decision for the mid-session `wk:` pin sweep
+ * (#3001).
+ *
+ * Why this exists: the background-worker pin (`wk:<agentId>`, pinned on the
+ * `🛠 Worker` feed message while the worker runs) is normally unpinned by the
+ * worker's completion handler (`reconcileWorkerPin(agentId, null, false)` on
+ * the watcher's onFinish). But that event can be MISSED — watcher crash, SDK
+ * subprocess SIGKILL, a dropped JSONL tail — and then nothing ever unpins the
+ * worker's message until the next gateway boot. Log evidence on one agent:
+ * ~1120 pinChatMessage vs ~1014 unpinChatMessage with zero logged failures —
+ * a long tail of stale pins glued to the top of the chat.
+ *
+ * This module is the pure half (mirrors `runActivityCardMidSessionReaper`'s
+ * decide-over-injected-seams shape): given the currently-claimed `wk:` pins,
+ * a terminality predicate over the sub-agent registry, and a TTL, it returns
+ * the pins that should be unpinned NOW. The gateway executes each reap via
+ * `reconcileStatusPin(key, chat, { pinned: false })` so the in-memory claim
+ * AND the durable store row clear together.
+ *
+ * A pin is reaped when EITHER:
+ *   - `terminal` — the registry says the worker reached a terminal status
+ *     (completed | failed): its work is finished, the pin must go, however
+ *     young it is. (A missed onFinish is exactly this case.)
+ *   - `ttl` — the pin has been held past `ttlMs` AND the registry cannot
+ *     vouch for the worker (no row / never linked / `stalled` / lookup
+ *     error). A registry-confirmed RUNNING row exempts the pin from the TTL
+ *     entirely: a healthy 7h worker keeps its pin for the whole run instead
+ *     of churning unpin→re-pin every TTL. The stall detector demotes a dead
+ *     worker's row out of 'running' within ~60s, so the TTL still catches
+ *     true zombies.
+ *
+ * A worker the registry can't vouch for is still never touched before the
+ * TTL — the sweep can only ever shorten a stale pin's life, not a live one's.
+ */
+
+/** Default TTL for a held worker pin: 6 hours. Rationale: worker turns are
+ *  expected to run minutes-to-a-couple-of-hours (the watcher's own stall
+ *  detection fires after ~60s of JSONL inactivity, and the longest sanctioned
+ *  background dispatches are bounded by a single Claude session's lifetime).
+ *  6h comfortably exceeds any legitimate worker turn while bounding the
+ *  stale-pin window to the same day instead of "until the next restart". */
+export const WORKER_PIN_TTL_MS_DEFAULT = 6 * 60 * 60_000
+
+export const WORKER_PIN_KEY_PREFIX = 'wk:'
+
+/** One currently-claimed worker pin, flattened from the gateway's Maps. */
+export interface WorkerPinCandidate {
+  /** Full pin key, `wk:<agentId>` shape. */
+  pinKey: string
+  /** Chat the pin lives in (from the gateway's pinKey → chatId registry). */
+  chatId: string
+  /** Wall-clock ms the claim was first taken (gateway's pinnedAt registry). */
+  pinnedAt: number
+}
+
+export interface WorkerPinReap extends WorkerPinCandidate {
+  reason: 'terminal' | 'ttl'
+}
+
+/** Extract the agentId from a `wk:<agentId>` pin key, or null for any other
+ *  key shape (fg:/banner:/tool: keys are never worker-reaped). */
+export function workerAgentIdOfPinKey(pinKey: string): string | null {
+  if (!pinKey.startsWith(WORKER_PIN_KEY_PREFIX)) return null
+  const agentId = pinKey.slice(WORKER_PIN_KEY_PREFIX.length)
+  return agentId.length > 0 ? agentId : null
+}
+
+/** The registry's view of a worker, distilled for the reap decision.
+ *  - 'terminal' — row exists in completed | failed: reap now.
+ *  - 'running'  — row exists and is still 'running': NEVER reap, not even
+ *    past the TTL. A healthy 7h worker must not get unpinned mid-run only
+ *    for the next feed edit to re-pin it (pin/unpin churn every TTL). The
+ *    subagent-watcher's stall detection demotes a dead worker's row out of
+ *    'running' within ~60s of its JSONL going quiet, so a true zombie can
+ *    only hold 'running' briefly — the TTL still catches everything the
+ *    registry has lost track of.
+ *  - 'unknown'  — no row / never linked / 'stalled' / lookup error: the
+ *    TTL gate applies (the registry can't vouch for it). */
+export type WorkerRegistryStatus = 'terminal' | 'running' | 'unknown'
+
+/**
+ * Decide which claimed worker pins to unpin now. Pure: the registry lookup is
+ * an injected predicate (`statusOf` must return 'terminal' ONLY for a row in
+ * completed | failed, 'running' only for a live 'running' row, and 'unknown'
+ * for stalled / missing / lookup-error; a DB hiccup must degrade to 'unknown'
+ * — kept until the TTL — never to a spurious 'terminal' unpin).
+ */
+export function decideWorkerPinReaps(args: {
+  pins: Iterable<WorkerPinCandidate>
+  statusOf: (agentId: string) => WorkerRegistryStatus
+  ttlMs: number
+  now: number
+}): WorkerPinReap[] {
+  const reaps: WorkerPinReap[] = []
+  for (const pin of args.pins) {
+    const agentId = workerAgentIdOfPinKey(pin.pinKey)
+    if (agentId == null) continue // not a worker pin — never ours to reap
+    if (pin.chatId.length === 0) continue // can't unpin without a chat
+    const status = args.statusOf(agentId)
+    if (status === 'terminal') {
+      reaps.push({ ...pin, reason: 'terminal' })
+      continue
+    }
+    // A registry-confirmed RUNNING worker keeps its pin regardless of age —
+    // the TTL only reaps pins the registry can't vouch for (see
+    // WorkerRegistryStatus doc).
+    if (status === 'running') continue
+    if (args.now - pin.pinnedAt >= args.ttlMs) {
+      reaps.push({ ...pin, reason: 'ttl' })
+    }
+  }
+  return reaps
+}