switchroom 0.19.35 → 0.19.37

package/telegram-plugin/format.ts

@@ -718,21 +718,37 @@ export function normalizePunctuation(text: string): string {
   const restoreLinks = (s: string): string =>
     s.replace(linkRestoreRe, (_m, idx: string) => linkMasks[Number(idx)] ?? _m)
 
+  // The dash rewrite runs per line so blockquote lines can be exempted:
+  // `>` blockquotes are reserved for VERBATIM quoted text, and rewriting an
+  // author's ` — ` to `, ` inside a quotation would corrupt what they quoted.
+  // The expandable-blockquote opener `**>` is a blockquote line too even though
+  // isBlockquoteLine (which keys on a leading `>`) doesn't catch the `**`
+  // prefix, so exempt it explicitly. Code spans and link hrefs stay masked
+  // throughout, so their dashes are already protected on every line.
+  const rewriteDashes = (line: string): string =>
+    line
+      // 1. Space-flanked em/en dash. Numeric range keeps a hyphen. The right
+      //    flank is a LOOKAHEAD (captured, not consumed) so consecutive spaced
+      //    dashes ("a — b — c") all normalize in one pass — a consumed \S would
+      //    swallow the char that anchors the next match.
+      .replace(/(\S)[ \t][—–][ \t](?=(\S))/g, (_m, a: string, b: string) =>
+        /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
+      )
+      // 2. Bare em-dash between word chars. Numeric range keeps a hyphen.
+      //    Right flank is a lookahead for the same consecutive-match reason.
+      .replace(/(\w)—(?=(\w))/g, (_m, a: string, b: string) =>
+        /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
+      )
+      // 3. Bare en-dash between word chars → hyphen (ranges: 2019–2024).
+      .replace(/(\w)–(?=\w)/g, '$1-')
+
+  const isQuotedLine = (line: string): boolean =>
+    isBlockquoteLine(line) || line.trimStart().startsWith('**>')
+
   let out = maskedAutolinks
-    // 1. Space-flanked em/en dash. Numeric range keeps a hyphen. The right
-    //    flank is a LOOKAHEAD (captured, not consumed) so consecutive spaced
-    //    dashes ("a — b — c") all normalize in one pass — a consumed \S would
-    //    swallow the char that anchors the next match.
-    .replace(/(\S)[ \t][—–][ \t](?=(\S))/g, (_m, a: string, b: string) =>
-      /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
-    )
-    // 2. Bare em-dash between word chars. Numeric range keeps a hyphen.
-    //    Right flank is a lookahead for the same consecutive-match reason.
-    .replace(/(\w)—(?=(\w))/g, (_m, a: string, b: string) =>
-      /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
-    )
-    // 3. Bare en-dash between word chars → hyphen (ranges: 2019–2024).
-    .replace(/(\w)–(?=\w)/g, '$1-')
+    .split('\n')
+    .map((line) => (isQuotedLine(line) ? line : rewriteDashes(line)))
+    .join('\n')
 
   // Restore link hrefs now that the dash passes are done — before the bullet
   // pass and the code restore.
@@ -761,6 +777,35 @@ function isFullyBolded(fragment: string): boolean {
   return /^\*\*[^*]+\*\*[.,:;!?]?$/.test(fragment.trim())
 }
 
+/**
+ * Max length (markers included) of a standalone fully-bolded line that is
+ * treated as a legitimate pseudo-heading (`**Section**`) rather than an
+ * over-bolded paragraph. Single source of truth for BOTH the per-block rule
+ * and the global-ratio heading exemption.
+ */
+const PSEUDO_HEADING_MAX_CHARS = 48
+
+/**
+ * True when a blank-line-delimited block is a single-line pseudo-heading: one
+ * non-empty line that is a single fully-bolded span of ≤PSEUDO_HEADING_MAX_CHARS
+ * characters (`**Summary**`, `**Next steps:**`). Multi-line blocks are never
+ * headings, so this can never mislabel a bolded paragraph as exempt.
+ */
+function isPseudoHeadingBlock(block: string): boolean {
+  const lines = block.split('\n').filter((l) => l.trim() !== '')
+  if (lines.length !== 1) return false
+  const t = lines[0].trim()
+  return t.length <= PSEUDO_HEADING_MAX_CHARS && isFullyBolded(t)
+}
+
+/** Diagnostic emitted when the over-bold tripwire actually removes bold. */
+export interface ExcessBoldStripDiagnostic {
+  /** Which rule fired: the whole-message ratio, or per-block flattening. */
+  rule: 'global' | 'per-block'
+  /** Measured bold ratio: bold chars / visible (non-code) chars. */
+  ratio: number
+}
+
 /** Strip `**bold**` markers from a fragment, keeping the text. */
 function unbold(fragment: string): string {
   return fragment.replace(/\*\*([^*]+)\*\*/g, '$1')
@@ -778,16 +823,24 @@ function unbold(fragment: string): string {
  * Deliberately conservative:
  *   - Messages under 100 non-code characters are exempt (a short reply whose
  *     one key fact is bolded is exactly the house style).
- *   - A single-line fully-bolded paragraph of ≤48 chars is treated as a
- *     pseudo-heading (the "**Section**" label the fleet style encourages) and
- *     is NOT stripped by the per-block rule (it still counts toward the
- *     global ratio).
+ *   - A single-line fully-bolded paragraph of ≤PSEUDO_HEADING_MAX_CHARS chars
+ *     is treated as a pseudo-heading (the "**Section**" label the fleet style
+ *     encourages) and is NOT stripped — neither by the per-block rule NOR by
+ *     the global-ratio rule (it still counts toward the global ratio, so a
+ *     genuinely over-bolded message still trips, but its section headings
+ *     survive instead of the whole reply going plain).
  *   - A list with any non-fully-bolded item is left alone.
  *
  * Code spans/fences are masked (maskCodeRegions) and never counted or
  * modified. Idempotent: stripped output has no `**` spans left to trip on.
+ *
+ * `onStrip` is an optional diagnostic sink invoked exactly once, only when
+ * bold is actually removed, carrying which rule fired and the measured ratio.
  */
-export function stripExcessBold(text: string): string {
+export function stripExcessBold(
+  text: string,
+  onStrip?: (d: ExcessBoldStripDiagnostic) => void,
+): string {
   if (!text.includes('**')) return text
 
   const nonce = Math.random().toString(36).slice(2)
@@ -800,14 +853,24 @@ export function stripExcessBold(text: string): string {
 
   let boldChars = 0
   for (const m of visible.matchAll(/\*\*([^*]+)\*\*/g)) boldChars += m[1].length
+  const ratio = boldChars / visible.length
+
+  // Blank-line-delimited blocks of the masked text (shared by both rules).
+  const blocks = masked.split(/\n{2,}/)
 
-  if (boldChars / visible.length > 0.3) {
-    // Clearly over-bolded — strip every bold span, keep the text.
-    return restore(unbold(masked))
+  if (ratio > 0.3) {
+    // Clearly over-bolded — strip every bold span, keeping the text, EXCEPT
+    // standalone short pseudo-heading blocks (`**Section**`), which stay bold
+    // so a bold-dense digest keeps its section headings.
+    const rebuilt = blocks.map((block) =>
+      isPseudoHeadingBlock(block) ? block : unbold(block),
+    )
+    const out = rejoinBlocks(masked, rebuilt)
+    if (out !== masked) onStrip?.({ rule: 'global', ratio })
+    return restore(out)
   }
 
-  // Per-block check on blank-line-delimited blocks of the masked text.
-  const blocks = masked.split(/\n{2,}/)
+  // Per-block check on the same blocks.
   const rebuilt = blocks.map((block) => {
     const lines = block.split('\n').filter((l) => l.trim() !== '')
     if (lines.length === 0 || !block.includes('**')) return block
@@ -824,17 +887,25 @@ export function stripExcessBold(text: string): string {
     const isProseBlock = lines.every((l) => !isMarkerLine(l, placeholder))
     if (!isProseBlock) return block
     if (!lines.every((l) => isFullyBolded(l))) return block
-    if (lines.length === 1 && lines[0].trim().length <= 48) return block
+    if (isPseudoHeadingBlock(block)) return block
     return unbold(block)
   })
 
-  // Rejoin with the original gap shapes: split() lost them, so re-split the
-  // masked text capturing the separators and interleave.
+  const out = rejoinBlocks(masked, rebuilt)
+  if (out !== masked) onStrip?.({ rule: 'per-block', ratio })
+  return restore(out)
+}
+
+/**
+ * Rejoin blocks produced by `masked.split(/\n{2,}/)` after per-block mapping,
+ * restoring the ORIGINAL blank-gap shapes (split() drops the separators, so
+ * re-capture them from the masked source and interleave).
+ */
+function rejoinBlocks(masked: string, rebuilt: string[]): string {
   const seps = masked.match(/\n{2,}/g) ?? []
   let out = rebuilt[0] ?? ''
   for (let i = 1; i < rebuilt.length; i++) out += (seps[i - 1] ?? '\n\n') + rebuilt[i]
-
-  return restore(out)
+  return out
 }
 
 // ---------------------------------------------------------------------------

package/telegram-plugin/gateway/gateway.ts

@@ -550,6 +550,9 @@ import {
   handleModelCommand,
   classifyModelSwitchConfirmation,
   formatModelRelaunchDiagLog,
+  parseModelSwitchTarget,
+  resolveSessionModelResolutionTimeoutMs,
+  waitForSessionModelResolution,
   servedModelMatchesRequested,
   buildServedModelDivergenceHandler,
   deliverModelSwitchBootNotice,
@@ -23665,23 +23668,26 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
           }
         } catch {}
 
-        // ─── Session-model re-hydration + LiteLLM-down alert (session relaunch) ───
-        //
-        // start.sh writes the EFFECTIVE launched model to `.active-session-model`
-        // on every boot (the model actually passed to `claude --model`). Re-hydrate
-        // the in-memory session-model override from it so `/status` and the welcome
-        // card stay honest after a session-relaunch restart. Only treat it as an
-        // override when it differs from the configured/default model — a plain boot
-        // on the configured model leaves the override null.
-        //
-        // Also consume the `.session-model-alert` sentinel: start.sh drops it when
-        // it had to DROP an sr-* override because LiteLLM was unreachable at boot
-        // (booting on the configured default instead of 4xx-ing against Anthropic).
-        // We turn it into a loud Telegram message to the operator, then delete it.
+        // Rehydrate only after start.sh publishes this boot's resolved outputs.
         try {
           const smAgentDir = resolveAgentDirFromEnv()
           if (smAgentDir) {
-            const activePath = join(smAgentDir, '.active-session-model')
+            const resolutionTimeoutMs = resolveSessionModelResolutionTimeoutMs(
+              process.env.SWITCHROOM_SESSION_MODEL_RESOLUTION_TIMEOUT_MS,
+            )
+            const resolved = await waitForSessionModelResolution({
+              barrierExists: () => existsSync(join(smAgentDir, '.session-model-resolved')),
+              timeoutMs: resolutionTimeoutMs,
+            })
+            if (!resolved) {
+              const target = modelSwitchReason == null
+                ? '(none)'
+                : (parseModelSwitchTarget(modelSwitchReason) ?? '(unknown)')
+              process.stderr.write(
+                `telegram gateway: gw /model relaunch UNRESOLVED agent=${getMyAgentName()} target=${target} (barrier timeout after ${resolutionTimeoutMs}ms)\n`,
+              )
+            } else {
+              const activePath = join(smAgentDir, '.active-session-model')
             if (existsSync(activePath)) {
               try {
                 const launched = readFileSync(activePath, 'utf8').trim()
@@ -23697,21 +23703,9 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                   // a phantom session override.
                   return resolveMainModel(raw ?? undefined)
                 })()
-                // `launched !== configured` is the DETERMINISTIC "a model switch
-                // landed" signal (F1): the carrier is consume-once, so a launched
-                // model that differs from the configured default only ever
-                // happens on a genuine apply-boot. Seed the in-memory override
-                // from it — this is the ONLY success reporting, sourced from the
-                // real post-boot signal (`.active-session-model`), never from a
-                // scraped pane or an optimistic record.
+                // A launched model differing from configured is a genuine apply boot.
                 const isApplyBoot = launched.length > 0 && launched !== configured
-                // { verify: true } (#3427 item 4 / H1): ONLY this site arms the
-                // requested-vs-served tripwire — `launched` IS the token of the
-                // session now serving. Command-time setOverride never arms.
                 sessionModelSource.setOverride(isApplyBoot ? launched : null, { verify: true })
-                // Boot /model cards (#3427): the divergence tripwire warn and
-                // the switch confirmation share one deps surface; the card
-                // logic lives in model-command.ts (#2996 ratchet).
                 const modelBootCardDeps: ModelBootCardDeps = {
                   agent: getMyAgentName(),
                   chat: modelSwitchMarkerChat,
@@ -23722,8 +23716,6 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 if (isApplyBoot) {
                   sessionModelSource.setDivergenceHandler(buildServedModelDivergenceHandler(modelBootCardDeps))
                 }
-                // F1/N4: classify + log + one confirmation card. Formatters live
-                // in model-command.ts so this file does not inflate (#2996 ratchet).
                 const confirmation = modelSwitchReason != null
                   ? classifyModelSwitchConfirmation({
                       reason: modelSwitchReason,
@@ -23793,6 +23785,7 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 process.stderr.write(`telegram gateway: session-model: LiteLLM-down override drop — ${alertText}\n`)
               }
             }
+            }
           }
         } catch (err) {
           process.stderr.write(`telegram gateway: session-model re-hydration failed: ${(err as Error)?.message ?? String(err)}\n`)

package/telegram-plugin/gateway/ipc-server.ts

@@ -25,6 +25,7 @@ import type {
   ToolCallResult,
 } from "./ipc-protocol.js";
 import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
+import { OPERATOR_EVENT_KINDS } from "../operator-events.js";
 
 export interface IpcServerOptions {
   socketPath: string;
@@ -196,21 +197,23 @@ type SocketData = { clientId: string; buffer: string };
  *  data without newline delimiters, which would cause unbounded memory growth. */
 const MAX_BUFFER_SIZE = 1024 * 1024;
 
-/** Allowlist of OperatorEventKind values that can arrive over IPC. Mirrors
- *  the union in `telegram-plugin/operator-events.ts` — kept as a literal Set
- *  here so the validator has zero cross-package type dependencies. If the
- *  taxonomy grows, update both places. */
-const VALID_OPERATOR_KINDS = new Set([
-  "credentials-expired",
-  "credentials-invalid",
-  "credit-exhausted",
-  "quota-exhausted",
-  "rate-limited",
-  "agent-crashed",
-  "agent-restarted-unexpectedly",
-  "unknown-4xx",
-  "unknown-5xx",
-]);
+/** Allowlist of OperatorEventKind values that can arrive over IPC. DERIVED
+ *  from the canonical `OPERATOR_EVENT_KINDS` array in
+ *  `telegram-plugin/operator-events.ts` — the single source of truth for the
+ *  taxonomy — so the validator can NEVER drift out of sync with it again.
+ *
+ *  History: this used to be a hand-maintained literal Set that missed the
+ *  `provider-credit-exhausted` / `mcp-dependency-blocked` / `proxy-misconfig`
+ *  kinds after they were added to the union. The bridge forwarded a
+ *  `provider-credit-exhausted` operator_event; this validator rejected it as an
+ *  "invalid IPC message shape" and dropped it, so an OpenRouter/LiteLLM 402
+ *  credit wall produced NO loud Telegram card (the 2026-07-30 incident).
+ *  Deriving from the canonical array closes that drift class structurally.
+ *
+ *  `operator-events.ts` is a pure module (its only imports are the pure
+ *  `format` / `raw-error-scrub` / `model-unavailable` / `provider-credit`
+ *  leaves), so importing it here introduces no cycle back into the gateway. */
+const VALID_OPERATOR_KINDS = new Set<string>(OPERATOR_EVENT_KINDS);
 
 /** Same regex as `assertSafeAgentName` and the op:* callback handler in
  *  gateway.ts — keeps every entry-point that touches an agent name on the

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

@@ -96,6 +96,40 @@ export function isValidModelArg(arg: string): boolean {
   return MODEL_ARG_RE.test(arg)
 }
 
+export const DEFAULT_SESSION_MODEL_RESOLUTION_TIMEOUT_MS = 180_000
+export const SESSION_MODEL_RESOLUTION_POLL_MS = 250
+
+/** Parse the bounded boot-resolution wait without allowing NaN/negative hangs. */
+export function resolveSessionModelResolutionTimeoutMs(raw: string | undefined): number {
+  if (raw == null || raw.trim() === '') return DEFAULT_SESSION_MODEL_RESOLUTION_TIMEOUT_MS
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0
+    ? value
+    : DEFAULT_SESSION_MODEL_RESOLUTION_TIMEOUT_MS
+}
+
+/**
+ * Asynchronously wait until start.sh atomically publishes this boot's resolved
+ * session-model outputs. The deadline is checked on every iteration, including
+ * timeout=0, so a missing barrier can never hang gateway startup indefinitely.
+ */
+export async function waitForSessionModelResolution(input: {
+  barrierExists: () => boolean
+  timeoutMs: number
+  pollMs?: number
+  sleep?: (ms: number) => Promise<void>
+}): Promise<boolean> {
+  const pollMs = input.pollMs ?? SESSION_MODEL_RESOLUTION_POLL_MS
+  const sleep = input.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+  const startedAt = Date.now()
+  for (;;) {
+    if (input.barrierExists()) return true
+    const remaining = input.timeoutMs - (Date.now() - startedAt)
+    if (remaining <= 0) return false
+    await sleep(Math.min(pollMs, remaining))
+  }
+}
+
 /** True when `name` is an sr-* (LiteLLM/OpenRouter) model identifier. */
 export function isSrModel(name: string): boolean {
   return name.startsWith('sr-')

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -191,7 +191,18 @@ export function normalizeOutboundBody(
   if (!literalText) text = normalizeParagraphBreaks(text)
   text = redact(text, site)
   if (!literalText) {
-    let formatted = stripExcessBold(normalizePunctuation(text))
+    let formatted = stripExcessBold(normalizePunctuation(text), (d) => {
+      // Observability: the over-bold tripwire silently flattened formatting.
+      // Emit one diagnostic line naming the rule + measured ratio so a lost
+      // reply is traceable (it previously vanished with no signal).
+      try {
+        process.stderr.write(
+          `telegram gateway: strip-excess-bold: fired site=${site} rule=${d.rule} ratio=${d.ratio.toFixed(3)}\n`,
+        )
+      } catch {
+        // stderr write must never break the send path. Swallow.
+      }
+    })
     if (addSpacers) formatted = addParagraphSpacers(formatted)
     text = formatted
     // Temporal normalization (#3501): UTC/Zulu → local wall clock, then

package/telegram-plugin/operator-events.ts

@@ -23,11 +23,32 @@ import {
 
 // ─── Taxonomy ────────────────────────────────────────────────────────────────
 
-export type OperatorEventKind =
-  | 'credentials-expired'
-  | 'credentials-invalid'
-  | 'proxy-misconfig'
-  | 'credit-exhausted'
+/**
+ * The CANONICAL runtime list of every operator-event kind — the SINGLE source
+ * of truth for the taxonomy. The `OperatorEventKind` type is derived from it
+ * (below), and every other place that needs the set at RUNTIME (notably the
+ * gateway IPC validator's `VALID_OPERATOR_KINDS` in `gateway/ipc-server.ts`)
+ * imports THIS array rather than re-declaring a hand-maintained literal.
+ *
+ * WHY THIS IS AN ARRAY, NOT JUST A TYPE (the drift this closes)
+ * ------------------------------------------------------------
+ * A TypeScript union erases at compile time, so a runtime allowlist could only
+ * mirror it by hand — and it drifted: `ipc-server.ts` shipped a 9-entry Set
+ * that never gained `provider-credit-exhausted` / `mcp-dependency-blocked` /
+ * `proxy-misconfig` when those kinds were added here. The bridge forwarded a
+ * `provider-credit-exhausted` operator_event; the gateway validator rejected it
+ * as an "invalid IPC message shape" and DROPPED it — so a real OpenRouter/
+ * LiteLLM 402 credit wall produced NO loud Telegram card at all (the 2026-07-30
+ * incident). Deriving both the type and the runtime allowlist from this one
+ * array makes that class of silent drop structurally impossible.
+ *
+ * Order is not significant. Adding a kind is a one-line edit HERE.
+ */
+export const OPERATOR_EVENT_KINDS = [
+  'credentials-expired',
+  'credentials-invalid',
+  'proxy-misconfig',
+  'credit-exhausted',
   /**
    * A THIRD-PARTY model provider (OpenRouter / OpenAI / Perplexity) reports no
    * credit remaining — HTTP 402 `payment_required`, "insufficient credits",
@@ -37,7 +58,7 @@ export type OperatorEventKind =
    * must not share a card. Operator-actionable (top up in the vendor console),
    * never user-actionable — see {@link OPERATOR_ACTIONABLE_KINDS}.
    */
-  | 'provider-credit-exhausted'
+  'provider-credit-exhausted',
   /**
    * A paid MCP dependency (Perplexity, Eraser, Brevo, Postiz, Meta/Google Ads,
    * Cloudflare …) is refusing work because its KEY is the problem — out of
@@ -49,16 +70,19 @@ export type OperatorEventKind =
    * `mcp-credential-failure.ts`. Operator-actionable: only the operator can top
    * up or re-issue a key.
    */
-  | 'mcp-dependency-blocked'
-  | 'quota-exhausted'
-  | 'rate-limited'
-  | 'agent-crashed'
-  | 'agent-restarted-unexpectedly'
-  | 'unknown-4xx'
-  | 'unknown-5xx'
-  | 'config-warning'
-  | 'always-allow-persist-failed'
-  | 'mental-model-persist-failed'
+  'mcp-dependency-blocked',
+  'quota-exhausted',
+  'rate-limited',
+  'agent-crashed',
+  'agent-restarted-unexpectedly',
+  'unknown-4xx',
+  'unknown-5xx',
+  'config-warning',
+  'always-allow-persist-failed',
+  'mental-model-persist-failed',
+] as const
+
+export type OperatorEventKind = (typeof OPERATOR_EVENT_KINDS)[number]
 
 export interface OperatorEvent {
   kind: OperatorEventKind

package/telegram-plugin/render/unsupported-token-guard.ts

@@ -59,12 +59,16 @@ import { splitProtectedSegments } from "./code-segments.js";
  *  `a^2+b^2=c^2`, `2^8`, and `x^n` all pass through untouched. */
 const CARET_PAIR = /\^([A-Za-z0-9]+)\^/g;
 
-/** Footnote reference marker `[^N]` (digits only) NOT immediately followed by
- *  `:` (which would make it a footnote DEFINITION line we leave intact). Removed
- *  entirely. Restricting the id to digits keeps this off in-prose bracket
- *  literals like `array[^index]` and regex-ish `[^/]`, which are NOT footnotes
- *  and would otherwise be silently eaten. */
-const FOOTNOTE_MARKER = /\[\^\d+\](?!:)/g;
+/** Footnote reference marker `[^id]` where the id is a short alphanumeric run
+ *  (`[^1]`, `[^note]`, `[^ref]`) NOT immediately followed by `:` (which would
+ *  make it a footnote DEFINITION line we leave intact). Removed entirely.
+ *  Requiring the id to be 1–10 ALPHANUMERIC chars keeps this off regex-ish
+ *  literals like `[^/]`, `[^\s]`, `[^-a-z]`, whose bodies contain punctuation
+ *  and so never match. In-prose subscript-ish `array[^i]` outside a code span
+ *  is a rare theoretical false positive (an `i` id matches); code spans are
+ *  masked upstream by splitProtectedSegments so real code is safe, and prose
+ *  that writes a literal `[^i]` reads as footnote noise anyway. */
+const FOOTNOTE_MARKER = /\[\^[A-Za-z0-9]{1,10}\](?!:)/g;
 
 /** `<details>…</details>` with an optional leading `<summary>…</summary>`.
  *  Dot-all via `[\s\S]`; non-greedy so adjacent blocks don't merge. */

package/telegram-plugin/secret-detect/db-uri.ts

@@ -0,0 +1,90 @@
+/**
+ * Database / service connection-URI credential scanner.
+ *
+ * Gap closed (2026-07 hindsight write-path audit): a connection string
+ * like `postgres://appuser:<password>@db.internal:5432/prod` passed the
+ * whole detection stack untouched and was stored verbatim in agent
+ * memory. `url-redact.ts` only rewrites `http(s)`/`ws(s)`/`ftp` (its
+ * `URL_RE` is scheme-limited), and no pattern in `patterns.ts` describes
+ * the `scheme://user:pass@host` shape, so a production database password
+ * was invisible to every caller of `detectSecrets`.
+ *
+ * This scanner is deliberately SCHEME-AGNOSTIC — it matches any
+ * `<scheme>://<user>:<password>@<host>` — so postgres, mysql, mongodb,
+ * redis, amqp, clickhouse, mssql and whatever ships next are all covered
+ * without a scheme allowlist to keep current. Precision comes from the
+ * shape, not from the scheme list: userinfo-with-password in a URI is a
+ * credential by construction.
+ *
+ * Only the PASSWORD bytes are reported. The username is left intact: it
+ * is rarely the secret, and keeping it preserves the diagnostic value of
+ * the stored line ("which account", not just "some database").
+ *
+ * Confidence is `ambiguous`, NOT `high`. `pipeline.ts` auto-writes every
+ * high-confidence inbound hit to the vault and the caller DELETES the
+ * user's Telegram message; promoting this rule to `high` would change
+ * inbound gating as a side effect of a redaction fix. `redact()` masks
+ * ambiguous hits, which is what this change is for.
+ */
+import type { RawHit } from './kv-scanner.js'
+
+/**
+ * `<scheme>://<user>:<password>@<host>`.
+ *
+ * - scheme: RFC 3986 shape, at least two chars so a Windows drive letter
+ *   (`c://`) can't anchor a match.
+ * - user: no `/`, `@`, `:` or whitespace.
+ * - password: anything up to an authority TERMINATOR (`/`, `?`, `#` or
+ *   whitespace) — `@` deliberately INCLUDED. Greedy matching then backs
+ *   off to the LAST `@` in the authority, which is where the host
+ *   actually starts.
+ *
+ *   #3982 review, MAJOR 3: excluding `@` (so the match stopped at the
+ *   FIRST one) looked conservative and was the opposite. An unencoded
+ *   `@` in a pasted DSN is common, and
+ *   `postgres://appuser:p@ssW0rd123@db.internal:5432/prod` masked one
+ *   byte and stored the other ten in clear —
+ *   `postgres://appuser:[REDACTED:db_uri_password]@ssW0rd123@db.internal…`
+ *   — while also telling a reader exactly how long the masked prefix
+ *   was. `url-redact.ts` already did this right for http(s) by taking
+ *   `lastIndexOf('@')` over the authority; this is the same rule for the
+ *   non-HTTP schemes.
+ * - host: at least one non-delimiter byte, so `user:pass@` with nothing
+ *   after it is not a connection string.
+ */
+const DB_URI_RE =
+  /\b([a-zA-Z][a-zA-Z0-9+.-]+):\/\/([^\s:/@]+):([^\s/?#]+)@([^\s/@?#]+)/g
+
+export const DB_URI_RULE_ID = 'db_uri_password'
+
+/** Values that are already masked or are obviously not a live credential. */
+function isInertPassword(value: string): boolean {
+  if (value.startsWith('[REDACTED')) return true
+  // `redactUrls()` rewrites `user:pass@` to `***@` (empty password), but a
+  // hand-written `***`/`xxx` mask should not round-trip into a detection
+  // either.
+  return /^[*x]+$/i.test(value)
+}
+
+export function scanDbUris(text: string): RawHit[] {
+  const hits: RawHit[] = []
+  DB_URI_RE.lastIndex = 0
+  let m: RegExpExecArray | null
+  while ((m = DB_URI_RE.exec(text)) !== null) {
+    const scheme = m[1]!
+    const user = m[2]!
+    const password = m[3]!
+    if (isInertPassword(password)) continue
+    // Offset of the password = match start + scheme + "://" + user + ":".
+    const start = m.index + scheme.length + 3 + user.length + 1
+    hits.push({
+      rule_id: DB_URI_RULE_ID,
+      start,
+      end: start + password.length,
+      matched_text: password,
+      key_name: `${scheme}_password`,
+      confidence: 'ambiguous',
+    })
+  }
+  return hits
+}

package/telegram-plugin/secret-detect/index.ts

@@ -30,7 +30,9 @@
  * scrub-coverage PR. Gitleaks TOML is loaded via `gitleaks-loader.ts`.
  */
 import { ALL_PATTERNS } from './patterns.js'
-import { scanKeyValue, type RawHit } from './kv-scanner.js'
+import { scanKeyValue, scanMemorablePasswords, type RawHit } from './kv-scanner.js'
+import { scanDbUris } from './db-uri.js'
+import { INERT_GATED_RULES, isInertValue } from './inert-values.js'
 import { scanGenericSecrets } from './generic-entropy.js'
 import { shannonEntropy } from './entropy.js'
 import { chunk } from './chunker.js'
@@ -87,6 +89,17 @@ export function detectSecrets(text: string): Detection[] {
         const globalEnd = globalStart + cap.length
         // For env_key_value (captureIndex=3), the LHS is group 1.
         const keyName = p.rule_id === 'env_key_value' ? m[1] : undefined
+        // Inert VALUE gate. `PASSWORD: ${DB_PASSWORD}`,
+        // `POSTGRES_PASSWORD: vault:pg/password`,
+        // `JWT_SECRET=<generate-with-openssl-rand>` and `--token <value>`
+        // are documentation, not credentials — and a vault key NAME is
+        // exactly what an agent is meant to remember, so masking it
+        // deletes information and keeps none. Until #3982's review this
+        // list applied only inside the memorable-password rule, so letter
+        // case decided the outcome: `password: ${DB_PASSWORD}` survived
+        // and `PASSWORD: ${DB_PASSWORD}` was destroyed. See
+        // inert-values.ts.
+        if (INERT_GATED_RULES.has(p.rule_id) && isInertValue(cap)) continue
         // 2026-05-12: shape gate on env_key_value — the pattern matches
         // any value after an ALLCAPS *_KEY/_TOKEN/_SECRET/_PASSWORD
         // identifier, which previously fired on casual chat like
@@ -125,6 +138,16 @@ export function detectSecrets(text: string): Detection[] {
     for (const h of kvHits) {
       raw.push({ ...h, start: h.start + win.offset, end: h.end + win.offset })
     }
+    // Connection-URI credentials (`postgres://user:pass@host`) — the
+    // scheme-agnostic shape url-redact.ts cannot see.
+    for (const h of scanDbUris(win.text)) {
+      raw.push({ ...h, start: h.start + win.offset, end: h.end + win.offset })
+    }
+    // Human-memorable passwords behind an explicit `password` label — the
+    // shape the Shannon-entropy gate above is structurally blind to.
+    for (const h of scanMemorablePasswords(win.text)) {
+      raw.push({ ...h, start: h.start + win.offset, end: h.end + win.offset })
+    }
     // Generic bare-high-entropy fallback (ambiguous). Catches standalone
     // tokens no prefix/KV rule matched. dropOverlaps/dedupeRaw below prefer
     // a high-confidence pattern hit over a generic one on the same range,