switchroom 0.19.35 → 0.19.36

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/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,

package/telegram-plugin/secret-detect/inert-values.ts

@@ -0,0 +1,147 @@
+/**
+ * Inert VALUES — placeholders, variable references and already-masked
+ * text that occupy a credential-shaped slot without being a credential.
+ *
+ * Masking one of these buys nothing and costs real information:
+ *
+ *   - `POSTGRES_PASSWORD: vault:pg/password` — the vault KEY NAME is
+ *     precisely what an agent is supposed to remember. Redacting it
+ *     deletes the pointer and keeps nothing.
+ *   - `JWT_SECRET=<generate-with-openssl-rand>` — an instruction.
+ *   - `const API_KEY = process.env.ANTHROPIC_API_KEY` — a reference.
+ *
+ * Before #3982's review this list existed only inside the new
+ * `memorable_password` rule, so letter case decided the outcome:
+ * `password: ${DB_PASSWORD}` survived while `PASSWORD: ${DB_PASSWORD}`
+ * (matched by the ALL-CAPS `env_key_value` rule) was destroyed. Every
+ * rule whose capture is a LABELLED slot now shares the list —
+ * `env_key_value`, `json_secret_field`, `cli_flag` and
+ * `memorable_password`.
+ *
+ * Mirrored in `vendor/hindsight-memory/scripts/lib/secret_redact.py`
+ * (`_INERT_VALUE_RES` / `_INERT_GATED_RULES`) and pinned across both
+ * engines by `secret_redaction_vectors.json`.
+ */
+
+export const INERT_VALUE_RE = [
+  // Our own marker (idempotence). `maskToken` only ever emits
+  // `[REDACTED]` or `[REDACTED:<rule_id>]`, so the closing bracket is
+  // part of the shape.
+  /^\[REDACTED(?::[A-Za-z0-9_]+)?\]$/i,
+  /^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/, // $PASSWORD, ${DB_PASSWORD}
+  // `.` is spelled out: JS `.` and Python `.` exclude different line
+  // terminators, and the two engines must agree byte for byte.
+  /^\{\{[^\n\r\u2028\u2029]*\}\}$/, // {{ handlebars }}
+  /^<[^<>\n\r\u2028\u2029]*>$/, // <your-password-here>
+  /^%[A-Za-z_][A-Za-z0-9_]*%$/, // %PASSWORD% (Windows)
+  /^vault:[A-Za-z0-9_./-]*$/i, // switchroom vault reference
+  /^[*x•.]+$/i, // ***, xxxx, ••••
+  // Code reference — `process.env.FOO`, `import.meta.env.VITE_X`,
+  // `os.environ["FOO"]`. The member path is PART OF THE SHAPE: a bare
+  // prefix followed by anything else is not a reference.
+  /^(?:process\.env|import\.meta\.env|os\.environ)(?:\.[A-Za-z_$][A-Za-z0-9_$]*|\[["']?[A-Za-z_$][A-Za-z0-9_$]*["']?\])*$/,
+  // Well-known "fill this in" values. A live credential never begins
+  // with the word telling you to replace it.
+  /^(?:changeme|change-me|replaceme|replace-me|placeholder|todo|tbd|yourkey|your-key|yourpassword|your-password|yoursecret|your-secret|yourtoken|your-token)(?:[-_][A-Za-z0-9-]+)?$/i,
+  // A lowercase English phrase — a help string or a JSON doc value such
+  // as `{"token": "the bearer token to use"}`, never a credential.
+  /^[a-z]+(?: [a-z]+){2,}$/,
+]
+
+/**
+ * An unbroken run of `[A-Za-z0-9]` long enough to BE a credential.
+ *
+ * Placeholder text is words joined by separators (`your-password-here`,
+ * `generate-with-openssl-rand`, `pg/password`, `ANTHROPIC_API_KEY`) — the
+ * longest alphanumeric run across every value this list protects is 10
+ * (`production`). A credential is the opposite shape: one dense run.
+ */
+const CREDENTIAL_RUN_RE = /[A-Za-z0-9]{12,}/g
+
+/**
+ * Mixed-class floor — `ENV_KV_MIN_LEN`, the length below which the env
+ * scanner already declines to call something a secret. Must not exceed
+ * `CREDENTIAL_RUN_RE`'s own floor.
+ */
+const MIXED_CLASS_RUN_MIN = 12
+
+/**
+ * Single-class floor. A run of only letters or only digits is far more
+ * likely to be an English word than a credential (`authentication`,
+ * `configuration`), so it gets more rope — but not unlimited rope:
+ * `abcdefghijklmnop` and a 40-`x` filler are values `main` masked, and no
+ * word in the protected corpus reaches 16.
+ */
+const SINGLE_CLASS_RUN_MIN = 16
+
+function runIsCredentialShaped(run: string): boolean {
+  // Classes present among {lower, upper, digit}. Hex, base62 and
+  // CamelCase-with-digits tokens are two or three; `yourtokenhere` and
+  // the segments of `YOUR_TOKEN_HERE` are one.
+  let classes = 0
+  if (/[a-z]/.test(run)) classes++
+  if (/[A-Z]/.test(run)) classes++
+  if (/[0-9]/.test(run)) classes++
+  return (
+    run.length >= (classes >= 2 ? MIXED_CLASS_RUN_MIN : SINGLE_CLASS_RUN_MIN)
+  )
+}
+
+/**
+ * True when `value` carries a credential-shaped run anywhere inside it.
+ *
+ * #3982 review, MAJOR 7. The inert SHAPES above are necessary but not
+ * sufficient: `<a8f3…40 hex…>` and `{{tok_…}}` are legal instances of the
+ * `<…>` / `{{…}}` shapes, and a wrapper left behind after someone filled
+ * the value in (`vault:pg/password<secret>`, `[REDACTED]<secret>`,
+ * `changeme-<secret>`) turned a false-positive fix into a bypass of
+ * already-shipped coverage. "Inert shape AND carries no credential" is
+ * the property actually wanted; end-anchoring alone is not enough,
+ * because `<secret>` is a well-formed instance of the shape.
+ */
+export function hasCredentialShapedRun(value: string): boolean {
+  for (const run of value.match(CREDENTIAL_RUN_RE) ?? []) {
+    if (runIsCredentialShaped(run)) return true
+  }
+  return false
+}
+
+/** True when `value` is a placeholder / reference rather than a secret. */
+export function isInertValue(value: string): boolean {
+  if (!INERT_VALUE_RE.some((re) => re.test(value))) return false
+  return !hasCredentialShapedRun(value)
+}
+
+/**
+ * Rule ids whose captured value is a labelled slot, and which therefore
+ * honour `isInertValue`. Keep in sync with `_INERT_GATED_RULES` in
+ * `secret_redact.py`.
+ */
+export const INERT_GATED_RULES = new Set([
+  'env_key_value',
+  'json_secret_field',
+  'cli_flag',
+])
+
+/**
+ * The heuristic KEY=VALUE scanner honours the same list — it is the rule
+ * that ate `ANTHROPIC_API_KEY: vault:anthropic/api_key` and
+ * `const API_KEY = process.env.ANTHROPIC_API_KEY`. Kept as its own
+ * export because `scanKeyValue` applies it directly rather than through
+ * the `ALL_PATTERNS` loop.
+ */
+export const KV_ENTROPY_RULE_ID = 'kv_entropy'
+
+/**
+ * Trailing punctuation an English sentence puts AFTER a value. The value
+ * character classes are `[^\s"']`-shaped, so a sentence-final `.` or a
+ * list comma is swallowed INTO the value — and a `.` alone supplies a
+ * second character class, which is what made
+ * "The password is required." redact as a credential (#3982 review,
+ * BLOCKER 2).
+ */
+const TRAILING_PUNCT_RE = /[.,;:!?)\]}]+$/
+
+export function stripTrailingPunctuation(value: string): string {
+  return value.replace(TRAILING_PUNCT_RE, '')
+}