switchroom 0.17.6 → 0.17.10

package/skills/mental-model-curator/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: mental-model-curator
+description: >
+  Review the agent's OWN Hindsight memory bank with the most capable model and
+  PROPOSE well-formed mental models ("knowledge models") to the operator via the
+  approve/deny proposal card, instead of blindly creating them. Use to curate,
+  seed, or audit the standing models the agent maintains over its specialty.
+  Triggers on phrasings like: "curate mental models", "propose knowledge models",
+  "review my memory bank", "what standing models should I have", "bootstrap
+  mental models", "suggest mental models from my bank", "audit my mental models",
+  "what recurring questions do I keep re-deriving", and typos like "propose
+  knowlege models". Do NOT use for storing a single fact/preference/decision —
+  that is retain, not a mental model. Do NOT use for identity or "who is the
+  user" — that lives in profile banks, so never propose an identity model here
+  (the operator's review of the card, not any code guard, is the only gate — so
+  it's on you to honor).
+  Even when the operator directly asks you to CREATE one specific named model
+  whose shape you know, PROPOSE it through the approve/deny card — never call
+  create_mental_model directly (it is not pre-approved; the propose card is the
+  only sanctioned write path, Fix 1.2 / #2903).
+allowed-tools: mcp__hindsight__list_banks mcp__hindsight__get_bank_stats mcp__hindsight__list_mental_models mcp__hindsight__get_mental_model mcp__hindsight__reflect mcp__hindsight__recall mcp__switchroom-telegram__mental_model_propose
+---
+
+# mental-model-curator — Propose standing knowledge models from your own bank
+
+A **mental model** in Hindsight is a pre-computed semantic summary backed by
+reflection over the memory bank — a standing answer to a recurring DOMAIN
+question the agent keeps re-deriving (e.g. a coach's "current training plan,
+recent sessions, and open adjustments"). This skill's job is to use your most
+capable model to survey your OWN bank and PROPOSE a few well-earned models to
+the operator through the approve/deny card — never to bulk-create noise.
+
+You cannot self-approve. Every proposal renders a card the operator taps. Your
+job is to make each proposal so obviously right that a glance is enough.
+
+## Why propose instead of create
+
+You do NOT have direct `create_mental_model` access — it is deliberately not
+pre-approved (Fix 1.2 / #2903). Every mental-model write routes through
+`mcp__switchroom-telegram__mental_model_propose`, because a
+standing model is a persistent, always-in-context artifact with real cost
+(recall/reflect spend, and — if `refresh_after_consolidation` is on — invisible
+post-consolidation spend). A human should decide which of those the agent runs.
+Bulk self-creation is how banks fill with overlapping, stale, or wrong-fact
+models. Propose the few that are earned; let the operator ratify.
+
+## Modes
+
+- **Propose mode (default):** run the full workflow and fire proposal cards, one
+  at a time, up to the rate limit.
+- **Dry-run / preview mode:** when the user says "preview", "dry run", "just
+  show me the candidates", "what would you propose", or you're testing against an
+  unfamiliar bank — run steps 1–4, then OUTPUT the ranked candidate list as text
+  (name + source_query + one-line reason) and STOP. Do NOT call
+  `mental_model_propose` in this mode. This is the safe way to run against any
+  bank.
+
+## Workflow
+
+### 1. Identify the bank and check it's worth analyzing
+
+Resolve the session's bank (`mcp__hindsight__list_banks`, or the bank bound to
+this agent's session). Then pull `mcp__hindsight__get_bank_stats`.
+
+If the bank is **empty or thin**, STOP and report "not enough content to
+synthesize models yet — the bank needs more accumulated memories before standing
+models are meaningful." Synthesizing over an empty or thin bank produces
+confident noise: models with no grounding that read as authoritative. A handful
+of memories is not a domain. Do not propose against a thin bank, even in dry-run.
+
+### 2. Read what already exists (dedupe)
+
+Call `mcp__hindsight__list_mental_models`, and `get_mental_model` on each to read
+its `source_query`. Build a dedupe set of the questions already covered.
+
+The propose flow hard-rejects an EXACT-name duplicate before a card posts, but
+that is not enough — a near-duplicate under a fresh name is still waste. You must
+**semantically** dedupe: if a candidate's source_query asks substantially the
+same thing as an existing model (even reworded), drop it. Only propose genuinely
+new coverage.
+
+### 3. Survey recurring themes
+
+Use `mcp__hindsight__reflect` and `mcp__hindsight__recall` to find the DOMAIN
+questions this agent keeps re-deriving — the standing state of its specialty.
+Good prompts: "What questions do I repeatedly answer from scratch?", "What are
+the recurring themes in this bank?", "What standing state would I want summarized
+before every relevant turn?" Cluster the answers into candidate standing
+questions. Each cluster must be backed by memories the bank ACTUALLY holds — if
+you can't point to the underlying content, it's not a candidate.
+
+### 4. Frame each candidate correctly
+
+- **`source_query` must be a DOMAIN question**, never an identity / "who is the
+  user" question. Identity lives in dedicated profile banks; never propose an
+  identity-based model — the operator, not the platform, is the only gate, so
+  this is on you to honor (one previously caused a wrong-fact contradiction bug).
+  If a candidate is really "facts about the user", discard it.
+- **`refresh_after_consolidation` defaults OFF.** Only set it true when the model
+  genuinely tracks fast-moving state that must be current the moment memory
+  consolidates. It adds invisible post-consolidation spend and timeout risk, so
+  the default answer is off.
+- **Keep models tight.** recall/reflect tiers cap around ~1024 tokens; a model
+  that tries to summarize everything summarizes nothing. Set a modest `max_tokens`
+  if the default would overrun. Narrow, answerable source_queries beat broad ones.
+- **Few models per bank.** Each must be earned by content the bank holds. Quality
+  over quantity — a bank with three sharp models beats one with ten vague ones.
+
+### 5. Propose within limits
+
+Rank the surviving candidates by how much re-derivation they save and how well
+the bank supports them. Propose only the **top few**.
+
+**HARD LIMIT: 5 proposal cards per hour per agent (sliding window).** Batch and
+prioritize — never fire one card per cluster. If you have more than 5 worthwhile
+candidates, propose the best 5 and mention the rest in text for a later pass.
+
+Propose **one at a time**:
+
+```
+mcp__switchroom-telegram__mental_model_propose(
+  chat_id=<the current chat_id>,
+  name=<slug>,
+  source_query=<the domain question>,
+  reason=<CRISP one line — the operator sees this on the card and denies vague ones>,
+  ...  # refresh_after_consolidation / max_tokens only when justified above
+)
+```
+
+The `reason` is load-bearing: it's the one line the operator reads before
+tapping. "Tracks the athlete's current plan + open adjustments so I stop
+rebuilding it each session" earns a tap; "useful model" gets denied.
+
+After firing a card, **END THE TURN CLEANLY.** The flow resumes on its own via a
+synthetic inbound (`mental_model_proposal_applied` / `mental_model_proposal_denied`)
+when the operator taps. Do not loop, do not poll, do not fire the next card in the
+same turn. You cannot self-approve — that's by design.
+
+### 6. Scheduled-sweep note (future extension)
+
+Unattended cron proposing is **NOT supported today.** `mental_model_propose`
+needs a live turn with an operator present to tap the card — firing cards into an
+empty topic at 3am is useless and noisy. If invoked from a scheduled sweep,
+**STAGE** the ranked candidates (retain them, or hold them) and surface them on
+the next interactive turn instead of firing cards unattended. Treat live-turn,
+operator-present proposing as the only supported path for now.
+
+## Anti-patterns
+
+- ❌ Proposing against an empty or thin bank — synthesizes to noise.
+- ❌ An identity / "who is the user" source_query — forbidden; profile banks own that.
+- ❌ Ten near-duplicate models under different names — semantically dedupe first.
+- ❌ Firing a card per cluster — respect the 5/hour limit; propose the top few.
+- ❌ `refresh_after_consolidation: true` by default — it's an invisible cost; leave it off unless the model tracks fast-moving state.
+- ❌ A vague `reason` — the operator denies it and you've burned a slot.
+- ❌ Looping/polling after a proposal — end the turn; the resume inbound wakes you.
+
+## Output
+
+In propose mode: a short line naming what you proposed and that the operator's
+tap will resume the flow. In dry-run mode: the ranked candidate list (name +
+source_query + reason) and nothing fired.

package/telegram-plugin/bridge/bridge.ts

@@ -30,6 +30,7 @@ import { createIpcClient, type IpcClientHandle } from './ipc-client.js'
 import { buildEffectiveToolSchemas, LINEAR_ENV } from './tool-filter.js'
 import type { InboundMessage, PermissionEvent, StatusEvent } from '../gateway/ipc-protocol.js'
 import { matchesAllowRule } from '../permission-rule.js'
+import { createOutstandingPermissionLedger } from './permission-ledger.js'
 
 installPluginLogger()
 
@@ -417,6 +418,24 @@ const TOOL_SCHEMAS = [
       required: ['chat_id', 'key'],
     },
   },
+  {
+    name: 'mental_model_propose',
+    description:
+      "Propose a Hindsight MENTAL MODEL for the operator to approve (agent-proposes → human-approves, hindsight Phase 5). Use this when — over real work — 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 — appended to your `memory.mental_models[]` in switchroom.yaml via the operator-approved config-edit path — 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 — it is the leashed, human-gated way to add a DURABLE declared model to your config. After firing this tool, END YOUR TURN cleanly — 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 — 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 — 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 — 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:
@@ -582,6 +601,40 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
 // added by either is honoured by all.
 const sessionAllowRules = new Set<string>()
 
+// #2861: outstanding permission-request ledger. Every permission_request from
+// claude is recorded here and re-sent on each IPC (re)connect, so a request
+// that arrives while the gateway is down (or that the gateway lost across a
+// restart) is redelivered instead of dropped. Deleted in onPermission when a
+// verdict is delivered. Kill switch: SWITCHROOM_PERMISSION_REARM=0 reverts to
+// the legacy drop-when-disconnected behavior.
+const outstandingPermissions = createOutstandingPermissionLedger()
+const permissionRearmEnabled = process.env.SWITCHROOM_PERMISSION_REARM !== '0'
+
+/**
+ * Re-send every outstanding permission_request to the gateway. Called on each
+ * IPC (re)connect via the ipc-client onConnect hook. The gateway dedupes /
+ * re-arms them idempotently (gateway/permission-rearm.ts), so re-sending on
+ * every reconnect is safe. Never answers a card — re-transmits the question.
+ */
+function flushOutstandingPermissionRequests(): void {
+  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\n`,
+  )
+  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,
+    })
+  }
+}
+
 mcp.setNotificationHandler(
   z.object({
     method: z.literal('notifications/claude/channel/permission_request'),
@@ -615,8 +668,29 @@ mcp.setNotificationHandler(
         return
       }
     }
+    // #2861: record the request in the outstanding ledger BEFORE the connect
+    // check so it survives a disconnected gateway and is re-sent on reconnect.
+    // It's deleted in onPermission when the verdict is delivered.
+    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\n')
+      // BUFFER, don't drop (#2861 R2). The request is in the ledger; the
+      // onConnect flush re-sends it once the gateway is reachable. Falls back
+      // to the legacy drop only when re-arm is killed.
+      if (permissionRearmEnabled) {
+        process.stderr.write(
+          `telegram bridge: permission_request buffered (gateway offline), will re-send on reconnect ` +
+          `request_id=${params.request_id}\n`,
+        )
+      } else {
+        process.stderr.write('telegram bridge: permission_request received but not connected to gateway\n')
+      }
       return
     }
     ipc.sendPermissionRequest({
@@ -658,6 +732,9 @@ function onPermission(msg: PermissionEvent): void {
   if (msg.rule) {
     sessionAllowRules.add(msg.rule)
   }
+  // #2861: verdict delivered → drop the request from the outstanding ledger so
+  // a later reconnect doesn't re-send an already-resolved approval.
+  outstandingPermissions.delete(msg.requestId)
   mcp.notification({
     method: 'notifications/claude/channel/permission',
     params: {
@@ -836,6 +913,8 @@ async function main(): Promise<void> {
     onInbound,
     onPermission,
     onStatus,
+    // #2861: re-send outstanding permission requests on every (re)connect.
+    onConnect: flushOutstandingPermissionRequests,
     log: (msg) => process.stderr.write(`telegram bridge: ipc: ${msg}\n`),
     // #2307 Tier-1: the cron-session bridge shares the agent's STATE_DIR
     // (access.json / history / gateway.sock) but writes its liveness file to a

package/telegram-plugin/bridge/ipc-client.ts

@@ -48,6 +48,14 @@ export interface IpcClientOptions {
   onInbound: (msg: InboundMessage) => void;
   onPermission: (msg: PermissionEvent) => void;
   onStatus: (msg: StatusEvent) => void;
+  /**
+   * Called every time the socket (re)connects and has registered — i.e. on
+   * the initial connect AND on each background reconnect. The bridge uses
+   * this to flush its outstanding permission-request ledger so approvals
+   * that arrived while the gateway was down are re-sent (#2861). Best-effort:
+   * a throw here is logged, never propagated into the socket open path.
+   */
+  onConnect?: () => void;
   log?: (msg: string) => void;
   reconnectDelayMs?: number;
   maxReconnectDelayMs?: number;
@@ -93,6 +101,7 @@ export function createIpcClient(options: IpcClientOptions): Promise<IpcClientHan
     onInbound,
     onPermission,
     onStatus,
+    onConnect,
     log = () => {},
     reconnectDelayMs = 2000,
     maxReconnectDelayMs = 30000,
@@ -237,6 +246,16 @@ export function createIpcClient(options: IpcClientOptions): Promise<IpcClientHan
             sendRegister();
             startHeartbeat();
             log(`connected to ${socketPath}`);
+            // Fire the (re)connect hook AFTER register + heartbeat so the
+            // bridge's ledger flush writes onto a live, registered socket.
+            // Best-effort: never let a callback throw abort the open path.
+            if (onConnect) {
+              try {
+                onConnect();
+              } catch (err) {
+                log(`onConnect hook threw: ${err}`);
+              }
+            }
             resolve();
           },
           data(sock, data) {

package/telegram-plugin/bridge/permission-ledger.ts

@@ -0,0 +1,61 @@
+/**
+ * Bridge-side outstanding permission-request ledger (#2861 / umbrella #2859).
+ *
+ * Problem it closes (R2): the bridge's `permission_request` handler used to
+ * DROP the request when the gateway IPC was down
+ * (`if (!ipc || !ipc.isConnected()) { log; return }`). claude stays suspended
+ * inside the MCP permission call, no card is ever posted, the turn wedges
+ * forever. There was no record of the ask to re-send once the gateway came
+ * back.
+ *
+ * Fix: every `permission_request` notification from claude is recorded here,
+ * keyed by request_id. When the IPC (re)connects, the bridge re-sends every
+ * outstanding request (the gateway dedupes / re-arms them idempotently — see
+ * `gateway/permission-rearm.ts`). An entry is deleted the moment a verdict is
+ * delivered back to claude (`onPermission`), so a resolved request is never
+ * re-sent.
+ *
+ * This never answers a card — it only re-transmits the QUESTION
+ * (no-self-escalation invariant). Pure in-memory bookkeeping: no model
+ * callsite, no I/O.
+ */
+
+/** The claude-side `permission_request` params the bridge forwards. */
+export interface OutstandingPermissionParams {
+  request_id: string
+  tool_name: string
+  description: string
+  input_preview: string
+}
+
+export interface OutstandingPermissionLedger {
+  /** Record a request. Idempotent on request_id (latest params win). */
+  add(params: OutstandingPermissionParams): void
+  /** Remove a request once its verdict has been delivered. */
+  delete(requestId: string): void
+  has(requestId: string): boolean
+  /** Snapshot of all outstanding requests (insertion order). */
+  all(): OutstandingPermissionParams[]
+  readonly size: number
+}
+
+export function createOutstandingPermissionLedger(): OutstandingPermissionLedger {
+  const map = new Map<string, OutstandingPermissionParams>()
+  return {
+    add(params) {
+      map.set(params.request_id, params)
+    },
+    delete(requestId) {
+      map.delete(requestId)
+    },
+    has(requestId) {
+      return map.has(requestId)
+    },
+    all() {
+      return [...map.values()]
+    },
+    get size() {
+      return map.size
+    },
+  }
+}

package/telegram-plugin/consolidation-legibility.ts

@@ -0,0 +1,279 @@
+/**
+ * Consolidation-driven chat-legible memory surface — hindsight Phase 4,
+ * the "updated what I know about Y" side (RFC
+ * `reference/rfcs/hindsight-synthesis-layers.md`, Phase 4).
+ *
+ * #2858 shipped the STORE/CORRECT side driven by deterministic tool-call
+ * observation of the interactive session (`create_directive` →
+ * "📌 remembered", `invalidate_memory` / demote → "✂️ forgot"). That path
+ * sees only what the *foreground* agent explicitly does with memory tools.
+ *
+ * The RFC also names the poll-free UPDATE side: when the *background*
+ * consolidation engine actually distils new durable observations (or
+ * supersedes stale ones) it emits a `consolidation.completed` webhook, and
+ * that is the honest signal for a terse "🧠 updated what I know about Y"
+ * line. This module is the consumer for that webhook.
+ *
+ * Two hard constraints from the RFC and the `remember-across-sessions` job
+ * shape every choice here:
+ *
+ *   1. **Sparse + material-only.** Consolidation fires on *every* retain
+ *      (`retainEveryNTurns=1`), so the raw webhook stream is per-turn. A
+ *      line per fire would BE the "regurgitating old facts unprompted just
+ *      to prove it remembered" anti-pattern the job forbids. So we surface
+ *      a line ONLY when a consolidation genuinely *stored* or *corrected* a
+ *      durable memory (`detectConsolidationEvent` returns null otherwise),
+ *      AND we rate-limit hard (`ConsolidationRateLimiter`) so bursts of
+ *      material consolidations collapse to at most one line per interval.
+ *
+ *   2. **OFF by default.** Unlike the #2858 tool-observation path (default
+ *      ON — it fires on rare, unambiguous, user-initiated tool calls), this
+ *      path is driven by an unbounded background engine and by a webhook the
+ *      pinned hindsight image does not yet emit. It stays OFF until an
+ *      operator opts in (`SWITCHROOM_CONSOLIDATION_LEGIBILITY=1`), matching
+ *      the RFC's "sparse, not per-turn … clearly gated" language.
+ *
+ * No model call, no polling, no `claude -p` — this is a pure consumer of a
+ * webhook the receiver already verified + forwarded (claude-native clean).
+ */
+
+import { stripMarkdown, truncate } from './card-format.js'
+
+/** The hindsight webhook source + event this module consumes. */
+export const HINDSIGHT_WEBHOOK_SOURCE = 'hindsight'
+export const CONSOLIDATION_COMPLETED_EVENT = 'consolidation.completed'
+
+/**
+ * OPT-IN — the operator must set SWITCHROOM_CONSOLIDATION_LEGIBILITY to a
+ * truthy value ('1' / 'true' / 'on' / 'yes') to enable. Default OFF: the
+ * literal opposite of the #2858 tool-observation path's default-ON switch,
+ * deliberately, because this side is driven by an unbounded background
+ * engine (RFC: "sparse, not per-turn"; "clearly gated").
+ */
+export function isConsolidationLegibilityEnabled(envVal: string | undefined): boolean {
+  if (envVal == null) return false
+  const v = envVal.trim().toLowerCase()
+  return v === '1' || v === 'true' || v === 'on' || v === 'yes'
+}
+
+export type ConsolidationLegibilityKind = 'updated' | 'revised'
+
+export interface ConsolidationLegibilityEvent {
+  /** `updated` — new durable observation(s) distilled; `revised` — an
+   *  existing memory was superseded/invalidated by consolidation. `revised`
+   *  is the higher-signal framing and wins when both happened. */
+  kind: ConsolidationLegibilityKind
+  /** Best-effort human subject ("your deploy preferences"). May be empty —
+   *  the render then falls back to a bare "updated what I know about you".
+   *  Raw (unescaped); `renderConsolidationLine` cleans it. */
+  topic: string
+}
+
+function asString(v: unknown): string {
+  return typeof v === 'string' ? v : ''
+}
+
+/** Coerce a numeric-ish field (number, or a numeric string) to a count ≥ 0. */
+function asCount(v: unknown): number {
+  if (typeof v === 'number' && Number.isFinite(v)) return v > 0 ? Math.floor(v) : 0
+  if (typeof v === 'string') {
+    const n = Number(v)
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0
+  }
+  // An array field (e.g. `observations: [...]`) counts by length.
+  if (Array.isArray(v)) return v.length
+  return 0
+}
+
+/** First non-empty count across a set of tolerant field aliases. */
+function firstCount(payload: Record<string, unknown>, keys: string[]): number {
+  for (const k of keys) {
+    const c = asCount(payload[k])
+    if (c > 0) return c
+  }
+  return 0
+}
+
+/**
+ * Best-effort human subject of the consolidation. The webhook is RFC-only
+ * (the pinned image does not emit it yet), so tolerate a range of shapes:
+ * an explicit `subject` / `topic`, the first entry of `subjects`/`entities`,
+ * or the `subject`/`statement` of the first observation. Anything opaque
+ * (a bank_id, a uuid) is left to the empty fallback.
+ */
+function extractTopic(payload: Record<string, unknown>): string {
+  const direct = asString(payload.subject).trim() || asString(payload.topic).trim()
+  if (direct) return direct
+
+  for (const key of ['subjects', 'entities', 'topics']) {
+    const arr = payload[key]
+    if (Array.isArray(arr)) {
+      for (const el of arr) {
+        if (typeof el === 'string' && el.trim()) return el.trim()
+        if (el && typeof el === 'object') {
+          const name = asString((el as Record<string, unknown>).name).trim()
+          if (name) return name
+        }
+      }
+    }
+  }
+
+  const obs = payload.observations
+  if (Array.isArray(obs) && obs.length > 0 && obs[0] && typeof obs[0] === 'object') {
+    const o = obs[0] as Record<string, unknown>
+    const sub = asString(o.subject).trim()
+    if (sub) return sub
+    const stmt = asString(o.statement).trim()
+    if (stmt) return stmt
+  }
+  return ''
+}
+
+/**
+ * Decide whether a `consolidation.completed` payload represents a MATERIAL
+ * durable change — a genuine store or correct — or null if it is a routine
+ * no-op consolidation (the common case, which must surface NO line).
+ *
+ * Pure, no I/O. Tolerant of the RFC-only payload's exact field names.
+ */
+export function detectConsolidationEvent(
+  payload: Record<string, unknown> | undefined,
+): ConsolidationLegibilityEvent | null {
+  if (payload == null || typeof payload !== 'object') return null
+
+  const stored = firstCount(payload, [
+    'stored',
+    'created',
+    'added',
+    'new_observations',
+    'observations_created',
+    'observations',
+  ])
+  const corrected = firstCount(payload, [
+    'corrected',
+    'invalidated',
+    'superseded',
+    'removed',
+    'demoted',
+  ])
+
+  // Immaterial: nothing durable stored, nothing corrected. This is the
+  // overwhelming majority of consolidation fires — surface nothing.
+  if (stored === 0 && corrected === 0) return null
+
+  // A correction ("what I believed changed") is higher-signal than another
+  // stored fact, so it wins the framing when both happened.
+  const kind: ConsolidationLegibilityKind = corrected > 0 ? 'revised' : 'updated'
+  return { kind, topic: extractTopic(payload) }
+}
+
+/** HTML-escape for parse_mode:'HTML' (escape the 3 entity-significant chars). */
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/** Max chars of subject shown on the one-liner. */
+const TOPIC_MAX = 120
+
+/**
+ * Render the terse one-line surface (Telegram HTML). Sent as a real
+ * `sendMessage` with notifications suppressed — a status surface, never a
+ * device ping.
+ *
+ *   🧠 <i>updated what I know</i> about "your deploy preferences"
+ *   🧠 <i>revised what I know</i> about "the old runbook"
+ *   🧠 <i>updated what I know about you.</i>        (no legible subject)
+ */
+export function renderConsolidationLine(ev: ConsolidationLegibilityEvent): string {
+  const verb = ev.kind === 'revised' ? 'revised' : 'updated'
+  const clean = truncate(stripMarkdown(ev.topic).replace(/\s+/g, ' ').trim(), TOPIC_MAX)
+  if (clean.length === 0) return `🧠 <i>${verb} what I know about you.</i>`
+  return `🧠 <i>${verb} what I know</i> about "${escapeHtml(clean)}"`
+}
+
+export interface ConsolidationRateLimiterOptions {
+  /** Minimum gap between ANY two surfaced lines for one agent. Collapses a
+   *  burst of material consolidations to at most one line per window.
+   *  Default 10 min. */
+  minIntervalMs?: number
+  /** Suppress an IDENTICAL line (same kind+topic) for this long even if the
+   *  min-interval has passed — stops "updated about X" repeating as the
+   *  engine re-derives the same observation. Default 1 hour. */
+  dedupWindowMs?: number
+  /** Clock override (tests). */
+  now?: () => number
+}
+
+const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000
+const DEFAULT_DEDUP_WINDOW_MS = 60 * 60 * 1000
+/** Cap on retained per-signature timestamps so the map can't grow unbounded
+ *  under a long-lived gateway. */
+const MAX_TRACKED_SIGNATURES = 512
+
+/**
+ * Per-agent rate limiter for the consolidation surface. Two independent
+ * gates, both must pass:
+ *
+ *   - **min-interval** — at most one line per agent per `minIntervalMs`,
+ *     regardless of subject. This is the anti-spam floor.
+ *   - **dedup** — the same (kind+topic) signature is suppressed for
+ *     `dedupWindowMs` even across the interval boundary.
+ *
+ * Stateful + long-lived: the gateway constructs ONE instance and reuses it
+ * across events. Deterministic under an injected clock (tests).
+ */
+export class ConsolidationRateLimiter {
+  private readonly minIntervalMs: number
+  private readonly dedupWindowMs: number
+  private readonly clock: () => number
+  private readonly lastEmit = new Map<string, number>()
+  private readonly recentSig = new Map<string, number>()
+
+  constructor(opts: ConsolidationRateLimiterOptions = {}) {
+    this.minIntervalMs = opts.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS
+    this.dedupWindowMs = opts.dedupWindowMs ?? DEFAULT_DEDUP_WINDOW_MS
+    this.clock = opts.now ?? Date.now
+  }
+
+  /**
+   * True when a line for (`agent`, `signature`) may be surfaced now, and
+   * records the emit. False (and records nothing) when either gate blocks.
+   * `signature` should be stable for identical lines (e.g. `kind:topic`).
+   */
+  allow(agent: string, signature: string, now?: number): boolean {
+    const t = now ?? this.clock()
+
+    const last = this.lastEmit.get(agent)
+    if (last !== undefined && t - last < this.minIntervalMs) return false
+
+    const sigKey = `${agent}\0${signature}`
+    const seen = this.recentSig.get(sigKey)
+    if (seen !== undefined && t - seen < this.dedupWindowMs) return false
+
+    this.lastEmit.set(agent, t)
+    this.recentSig.set(sigKey, t)
+    this.pruneSignatures(t)
+    return true
+  }
+
+  /** Drop signature entries older than the dedup window; hard-cap the map. */
+  private pruneSignatures(now: number): void {
+    for (const [k, ts] of this.recentSig) {
+      if (now - ts >= this.dedupWindowMs) this.recentSig.delete(k)
+    }
+    if (this.recentSig.size > MAX_TRACKED_SIGNATURES) {
+      // Evict oldest until back under the cap (insertion order ≈ age).
+      const excess = this.recentSig.size - MAX_TRACKED_SIGNATURES
+      let i = 0
+      for (const k of this.recentSig.keys()) {
+        if (i++ >= excess) break
+        this.recentSig.delete(k)
+      }
+    }
+  }
+}
+
+/** Stable dedup signature for an event (kind + normalised topic). */
+export function consolidationSignature(ev: ConsolidationLegibilityEvent): string {
+  return `${ev.kind}:${ev.topic.replace(/\s+/g, ' ').trim().toLowerCase()}`
+}