switchroom 0.20.12 → 0.20.13

package/telegram-plugin/gateway/captured-answer-resume.ts

@@ -68,7 +68,7 @@
  * `deliver` (via `deliverAnswer`), the durable oracle, and the obligation I/O.
  */
 
-import { hasOutboundWithText } from '../history.js'
+import { hasOutboundWithText as realHasOutboundWithText } from '../history.js'
 import type { BackstopDeliveryLedger } from './backstop-delivery.js'
 import type { CapturedDeliverySnapshot, Obligation } from './obligation-ledger.js'
 
@@ -168,6 +168,27 @@ export interface CapturedResumePorts {
   /** True when history is queryable (else the durable-text oracle reconcile that
    *  gives crash-idempotency — §2.3/A5 — is skipped). */
   historyEnabled: boolean
+  /**
+   * The durable outbound-text oracle. Defaults to the real `history.js`
+   * implementation; tests inject a fake here instead of module-mocking
+   * `../history.js`. A `vi.mock('../history.js', ...)` looks file-scoped
+   * under vitest but is NOT under bun's vitest-compat layer (`bun test`
+   * maps `vi.mock` onto the PROCESS-GLOBAL `mock.module`, which retroactively
+   * rebinds every other file's import of the same specifier in the same
+   * `bun-test-run` sweep — see check-bun-module-mock-scope.mjs). That leak
+   * was the actual root cause of #4488/#4491: a mocked `hasOutboundWithText`
+   * from this module's own test file silently answered
+   * `telegram-plugin/tests/history.test.ts`'s calls to the REAL function
+   * elsewhere in the same 651-file sweep, so a row `history.test.ts` had
+   * genuinely just written was reported as not found. Injecting via this
+   * port keeps the fake scoped to the dispatcher instance that receives it.
+   */
+  hasOutboundWithText?: (
+    chatId: string,
+    text: string,
+    threadId: number | null,
+    sinceMs?: number,
+  ) => boolean
   stderr?: (s: string) => void
 }
 
@@ -198,6 +219,7 @@ export interface CapturedResumeDispatcher {
  */
 export function createCapturedResumeDispatcher(ports: CapturedResumePorts): CapturedResumeDispatcher {
   const stderr = ports.stderr ?? (() => {})
+  const hasOutboundWithText = ports.hasOutboundWithText ?? realHasOutboundWithText
   const inFlight = new Set<string>()
 
   /** Re-deliver the UNSENT tail of `o`'s captured answer, byte-identical,

package/telegram-plugin/gateway/gateway.ts

@@ -9919,6 +9919,7 @@ async function deliverCapturedProse(args: {
   text: string
   /** Turn elapsed for the honest "(waited Ns)" apology clause; optional. */
   turnDurationMs?: number; replyToolThrewThisTurn?: boolean // #4141: label prose recovered from a turn whose reply tool threw (see outbound-send-path.ts)
+  reviewOriginated?: boolean // #4490: review-turn provenance, threaded through to the SAME card-gate / title-framing rules (see outbound-send-path.ts)
 }): Promise<void> {
   // #2996 P2: body moved VERBATIM to outbound-send-path.ts (single tested
   // send module). Injects the ONE `outboundDedup` instance (Amendment 1/9).

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

@@ -62,10 +62,27 @@ import { journalExternalDelivery } from './outbox-sweep.js'
 import { sha256Hex } from '../outbox.js'
 // #4141: the ONE shared framing implementation, also used by the outbox sweep
 // and (for the classifier half) the unbundled Stop hooks.
+//
+// #4490: previously this import only pulled the reply-throw half. The
+// captured-prose bridge below is the ELECTED path's deliverer — it never
+// writes an outbox record, so without the audience gate / self-improvement
+// framing wired in here too, a review-turn's raw, unlabelled reasoning could
+// reach the operator whenever the single-writer election (in
+// `silent-end-interrupt-stop.mjs`) routes a 'trailing-text-after-reply' case
+// here instead of to the outbox sweep. Wiring the SAME shared predicates in
+// both places (rather than re-deriving a third, parallel implementation)
+// restores the #4141-style symmetry #4485 left one-sided.
 import {
   applyReplyThrowFraming,
   formatReplyThrowFraming,
   shouldFrameReplyThrow,
+  decideCaptureAudience,
+  isSelfImprovementCard,
+  shouldFrameSelfImprovement,
+  applySelfImprovementFraming,
+  formatSelfImprovementFraming,
+  formatInternalSuppression,
+  AUDIENCE_INTERNAL,
 } from '../hooks/audience-classify.mjs'
 import { queueFloodBlockedReply } from './flood-reply-queue.js'
 import { resolveChatIdFallback } from './chat-id-fallback.js'
@@ -2737,6 +2754,17 @@ export async function deliverCapturedProse(
    * record, so the sweep's framing can never reach the message.
    */
   replyToolThrewThisTurn?: boolean
+  /**
+   * #4490 — this turn originated from a self-improvement review inbound
+   * (`source="self_improve_review"`). Stamped by the Stop hook's
+   * single-writer election onto the `SilentEndState` file (the ONLY way this
+   * path — which never writes an outbox record — can learn a review turn's
+   * provenance) and threaded through `decideCapturedProseDelivery`. Gates the
+   * SAME audience-suppression / title-framing rules the outbox sweep applies
+   * to a review record, restoring the #4141-style symmetry #4485 left
+   * one-sided (card gate + title framing applied at the sweep only).
+   */
+  reviewOriginated?: boolean
   },
 ): Promise<void> {
   const {
@@ -2758,14 +2786,69 @@ export async function deliverCapturedProse(
     { replyToolThrewThisTurn: args.replyToolThrewThisTurn },
     { frameEnabled: process.env.SWITCHROOM_TG_OUTBOX_PROVENANCE_FRAMING !== '0' },
   )
-  // #3228 Finding 1 — the three settlement points (sent / skipped-dedup /
-  // failed) all funnel through the pure `settleCapturedProseDelivery` core so
-  // the failure posture is deterministic and unit-tested. `outcome` is set on
-  // each branch and applied ONCE at the bottom.
+  // #4490 — CARD GATE, primary: same two-layer design the outbox sweep uses
+  // (`audience-classify.mjs`'s module doc). `decideCaptureAudience` checks
+  // `reviewOriginated` independent of the reply-throw path above: a review
+  // turn's prose classifies `internal` UNLESS the text itself is the one
+  // sanctioned card (`isSelfImprovementCard`), in which case it's `user` and
+  // delivered normally. A non-review turn's `reviewOriginated` is `false`/
+  // `undefined`, which never enters this branch — so this can only ever
+  // ADD suppression to a review turn, never touch a normal answer.
+  const audienceGateEnabled = process.env.SWITCHROOM_TG_OUTBOX_AUDIENCE_GATE !== '0'
+  const audience = decideCaptureAudience({
+    reviewOriginated: args.reviewOriginated === true,
+    reviewTextIsCard: isSelfImprovementCard(text),
+  })
+  const suppressed = audienceGateEnabled && audience === AUDIENCE_INTERNAL
+  // #4490 — TITLE FRAMING, residual belt-and-braces: applied OUTERMOST, after
+  // the reply-throw banner, exactly mirroring `decideOutboxSweep`'s ordering
+  // (`outbox.ts`). Only reachable when the card gate is disabled (or a
+  // legacy/`user`-audience route) — a review record that IS delivered here
+  // must still carry the title so it can never appear as raw, unlabelled
+  // agent reasoning even in a degraded config. `!isSelfImprovementCard(text)`
+  // keeps this idempotent against a text that already opens with the title
+  // (#4489's fix, same discipline).
+  const selfImproveFramed =
+    !suppressed &&
+    shouldFrameSelfImprovement(
+      { reviewOriginated: args.reviewOriginated },
+      { frameEnabled: process.env.SWITCHROOM_TG_OUTBOX_SELF_IMPROVE_FRAMING !== '0' },
+    ) &&
+    !isSelfImprovementCard(text)
+  // #3228 Finding 1 — the settlement points (sent / skipped-dedup / failed /
+  // suppressed-internal) all funnel through the pure
+  // `settleCapturedProseDelivery` core so the failure posture is
+  // deterministic and unit-tested. `outcome` is set on each branch and
+  // applied ONCE at the bottom.
   let outcome: CapturedProseSendOutcome
+  if (suppressed) {
+    // #4490 — the gap this closes: previously this path had NO audience gate
+    // at all, so a non-card review turn's raw reasoning would be sent below
+    // exactly like any other captured prose. Suppress before the dedup check
+    // and before any send attempt — nothing is delivered, so there is nothing
+    // to dedup against.
+    journalExternalDelivery({
+      turnNonce: originTurnId,
+      text,
+      replyAlreadyDeliveredThisTurn: false,
+      audience,
+      suppressedAudience: AUDIENCE_INTERNAL,
+    })
+    process.stderr.write(
+      formatInternalSuppression({
+        turnNonce: originTurnId,
+        turnId: originTurnId,
+        chatId,
+        textSha256: sha256Hex(text),
+        source: 'captured-prose-bridge',
+      }),
+    )
+    outcome = 'suppressed-internal'
+  } else {
   const already = outboundDedup.check(chatId, threadId, text, now, registryKey)
   if (already == null) {
     let out = normalizeParagraphBreaks(repairEscapedWhitespace(framed ? applyReplyThrowFraming(text) : text))
+    out = selfImproveFramed ? applySelfImprovementFraming(out) : out
     out = redactOutboundText(out, 'captured_prose')
     const chunks = splitMarkdownChunks(out, RICH_MESSAGE_MAX_CHARS)
     const sentIds: number[] = []
@@ -2821,6 +2904,14 @@ export async function deliverCapturedProse(
         // `DeliveredEntry.framedProvenance`, so "was this labelled?" is
         // answerable from the journal alone, hours later.
         ...(framed ? { framedProvenance: 'reply-throw' as const } : {}),
+        // #4490 durable terminal stamp — parity with the sweep's
+        // `DeliveredEntry.framedSelfImprovement`.
+        ...(selfImproveFramed ? { framedSelfImprovement: 'self-improve' as const } : {}),
+        // #4490 — stamp the audience decision on every journal line from this
+        // site, not only the suppressed one, so "what audience did this
+        // classify as" is answerable from the journal alone even for a
+        // successful send (parity with the outbox sweep's journal rows).
+        audience,
       })
       process.stderr.write(
         `telegram gateway: captured-prose delivery — sent ${out.length} chars recovered from ` +
@@ -2837,6 +2928,17 @@ export async function deliverCapturedProse(
           }),
         )
       }
+      if (selfImproveFramed) {
+        process.stderr.write(
+          formatSelfImprovementFraming({
+            turnNonce: originTurnId,
+            turnId: originTurnId,
+            chatId,
+            textSha256: sha256Hex(text),
+            source: 'captured-prose-bridge',
+          }),
+        )
+      }
       outcome = 'sent'
     } catch (err) {
       // #3228 Finding 1 — the send threw, so the answer did NOT reach the user.
@@ -2861,9 +2963,12 @@ export async function deliverCapturedProse(
     )
     outcome = 'skipped-dedup'
   }
+  }
   // Apply the settlement bookkeeping through the pure core (#3228 Finding 1):
-  //   sent / skipped-dedup → close obligation + clear state (answer is with the
-  //                          user, so represent + exhausted fallback must not fire)
+  //   sent / skipped-dedup / suppressed-internal → close obligation + clear
+  //                          state (either the answer is with the user, or it
+  //                          was never meant to reach them — either way the
+  //                          represent + exhausted fallback must not fire).
   //   failed               → arm the Stop-hook re-prompt net (recordUndelivered),
   //                          do NOT close/clear.
   const settlement = settleCapturedProseDelivery(outcome, {

package/telegram-plugin/gateway/outbox-sweep.ts

@@ -47,8 +47,10 @@ import {
   AUDIENCE_INTERNAL,
   formatInternalSuppression,
   formatReplyThrowFraming,
+  formatSelfImprovementFraming,
   resolveRecordAudience,
   shouldSuppressForAudience,
+  type Audience,
 } from '../hooks/audience-classify.mjs'
 import { isShownBlock } from '../shown-ledger.js'
 import { richMessage, isParseEntitiesError } from '../rich-send.js'
@@ -162,6 +164,19 @@ export interface OutboxSweepDeps {
    * Defaults to `log`.
    */
   logProvenanceFraming?: (line: string) => void
+  /**
+   * Ken 2026-08-07 kill switch for the self-improvement title header. Defaults
+   * to `SWITCHROOM_TG_OUTBOX_SELF_IMPROVE_FRAMING !== '0'` (ON). Same
+   * injected-seam reasoning as {@link provenanceFramingEnabled}: a module-scope
+   * env read would be captured at import and a revert-check could not run.
+   */
+  selfImprovementFramingEnabled?: () => boolean
+  /**
+   * Ken 2026-08-07 telemetry sink for a self-improvement-framed delivery.
+   * Separate from {@link logProvenanceFraming} so the two framings are greppable
+   * apart. Defaults to `log`.
+   */
+  logSelfImprovementFraming?: (line: string) => void
 }
 
 export interface OutboxSweepSummary {
@@ -190,6 +205,12 @@ export interface OutboxSweepSummary {
    * delivery, not a skip.
    */
   provenanceFramed?: number
+  /**
+   * Ken 2026-08-07: deliveries this sweep that carried the self-improvement
+   * title header. These ARE counted in `delivered` — framing is a delivery, not
+   * a skip.
+   */
+  selfImprovementFramed?: number
 }
 
 /**
@@ -246,6 +267,9 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
   const provenanceFramingEnabled = deps.provenanceFramingEnabled?.() ??
     process.env.SWITCHROOM_TG_OUTBOX_PROVENANCE_FRAMING !== '0'
   const logProvenanceFraming = deps.logProvenanceFraming ?? log
+  const selfImprovementFramingEnabled = deps.selfImprovementFramingEnabled?.() ??
+    process.env.SWITCHROOM_TG_OUTBOX_SELF_IMPROVE_FRAMING !== '0'
+  const logSelfImprovementFraming = deps.logSelfImprovementFraming ?? log
 
   for (const record of records) {
     summary.scanned++
@@ -341,6 +365,11 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
       // exists to prevent. So we state the provenance instead, and the human
       // (who can tell the difference, unlike any classifier here) decides.
       provenanceFraming: provenanceFramingEnabled,
+      // Ken 2026-08-07: label any review-originated record that reaches delivery
+      // (the audience gate's default suppression already withheld it above; this
+      // covers the gate-off / `user`-route residual) with the self-improvement
+      // title, so review reasoning can never appear as raw, unlabelled prose.
+      selfImprovementFraming: selfImprovementFramingEnabled,
     })
 
     if (decision.action !== 'send' && decision.action !== 'send-delayed') {
@@ -423,6 +452,11 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
           ...(decision.framedProvenance != null
             ? { framedProvenance: decision.framedProvenance }
             : {}),
+          // Ken 2026-08-07: durable terminal stamp for a self-improvement-framed
+          // delivery — same reasoning as `framedProvenance`.
+          ...(decision.framedSelfImprovement != null
+            ? { framedSelfImprovement: decision.framedSelfImprovement }
+            : {}),
         },
         deps.stateDir,
       )
@@ -438,6 +472,18 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
           }),
         )
       }
+      if (decision.framedSelfImprovement != null) {
+        summary.selfImprovementFramed = (summary.selfImprovementFramed ?? 0) + 1
+        logSelfImprovementFraming(
+          formatSelfImprovementFraming({
+            turnNonce: record.turnNonce,
+            turnId: turnIdFromNonce(record.turnNonce),
+            chatId: resolvedChat.chatId,
+            textSha256: record.textSha256,
+            source: record.source,
+          }),
+        )
+      }
       // Persist parity (mirrors outbound-send-path.ts + backstop-delivery.ts):
       // record the delivered chunk ids + texts to history so a net-delivered
       // answer is not silently absent from history.db. Best-effort — a missing
@@ -980,6 +1026,26 @@ export function journalExternalDelivery(
      * bridge), hours later.
      */
     framedProvenance?: 'reply-throw'
+    /**
+     * #4490: the record's audience, carried onto the journal line — parity
+     * with the sweep's own `DeliveredEntry.audience`. Lets the captured-prose
+     * bridge (`outbound-send-path.ts`), the OTHER delivery machine, journal
+     * through this ONE shared function instead of a second, hand-rolled
+     * `appendDelivered` call.
+     */
+    audience?: Audience
+    /**
+     * #4490: this journal line is a TERMINAL SUPPRESSION (the audience gate
+     * withheld an `'internal'` record), not a delivery — mirrors
+     * `DeliveredEntry.suppressedAudience`.
+     */
+    suppressedAudience?: Audience
+    /**
+     * #4490: this delivery carried the self-improvement title framing —
+     * mirrors `DeliveredEntry.framedSelfImprovement`, applied on either
+     * delivery path.
+     */
+    framedSelfImprovement?: 'self-improve'
   },
   stateDir?: string,
   now: number = Date.now(),
@@ -1000,6 +1066,9 @@ export function journalExternalDelivery(
         ? {}
         : { replyAlreadyDeliveredThisTurn: args.replyAlreadyDeliveredThisTurn }),
       ...(args.framedProvenance == null ? {} : { framedProvenance: args.framedProvenance }),
+      ...(args.audience == null ? {} : { audience: args.audience }),
+      ...(args.suppressedAudience == null ? {} : { suppressedAudience: args.suppressedAudience }),
+      ...(args.framedSelfImprovement == null ? {} : { framedSelfImprovement: args.framedSelfImprovement }),
     },
     stateDir,
   )

package/telegram-plugin/gateway/stream-render.ts

@@ -2941,6 +2941,10 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
               // not what it chose to send. Pass the raw signal through so the
               // send states that provenance. It never gates delivery.
               replyToolThrewThisTurn: proseDecision.replyToolThrewThisTurn === true,
+              // #4490 — same pass-through for the review-origin signal, so the
+              // send path can apply the SAME card-gate / title-framing rules the
+              // outbox sweep applies to a review turn's prose.
+              reviewOriginated: proseDecision.reviewOriginated === true,
               // For the honest "(waited Ns)" clause if the exhaustion-boundary
               // apology fallback fires (#3228).
               turnDurationMs,

package/telegram-plugin/hooks/audience-classify.d.mts

@@ -3,9 +3,16 @@ export type Audience = 'user' | 'internal'
 export const AUDIENCE_USER: 'user'
 export const AUDIENCE_INTERNAL: 'internal'
 
+/** Mirror of `REVIEW_SOURCE` in `src/self-improve/review-prompt.ts`. */
+export const REVIEW_SOURCE: 'self_improve_review'
+
+export function isReviewOriginatedSource(source: string | null | undefined): boolean
+
 export function decideCaptureAudience(signals: {
   replyToolThrewThisTurn?: boolean
   openInboundObligation?: true | false | 'unknown'
+  reviewOriginated?: boolean
+  reviewTextIsCard?: boolean
 }): Audience
 
 export function resolveOpenObligation(args: {
@@ -39,6 +46,25 @@ export function formatReplyThrowFraming(s: {
   source?: string
 }): string
 
+export const SELF_IMPROVEMENT_TITLE: string
+
+export function isSelfImprovementCard(text: string | null | undefined): boolean
+
+export function shouldFrameSelfImprovement(
+  record: { reviewOriginated?: unknown },
+  opts?: { frameEnabled?: boolean },
+): boolean
+
+export function applySelfImprovementFraming(text: string): string
+
+export function formatSelfImprovementFraming(s: {
+  turnNonce: string
+  turnId?: string | null
+  chatId?: string | null
+  textSha256?: string
+  source?: string
+}): string
+
 export function formatInternalSuppression(s: {
   turnNonce: string
   turnId?: string | null

package/telegram-plugin/hooks/audience-classify.mjs

@@ -35,6 +35,39 @@ export const AUDIENCE_USER = 'user'
  */
 export const AUDIENCE_INTERNAL = 'internal'
 
+/**
+ * The `meta.source` a self-improvement review turn's synthesized inbound
+ * carries. MUST stay byte-identical to `REVIEW_SOURCE` in
+ * `src/self-improve/review-prompt.ts` — this unbundled `.mjs` cannot import the
+ * TS module, so the constant is mirrored here (same discipline as `MAX_RETRIES`
+ * / `isTurnFlushSafetyEnabledEnv`). `tests/self-improve-review-audience.test.ts`
+ * pins the equality so a rename on either side reds CI.
+ *
+ * WHY IT LIVES IN THE AUDIENCE MODULE. A self-improvement review turn is
+ * injected with an explicit contract (`buildReviewPrompt`): "act SILENTLY, do
+ * NOT reply to the operator, end the turn when done." Its trailing transcript
+ * prose is therefore the agent reasoning to ITSELF — an `internal` audience by
+ * construction, exactly the vocabulary this module owns. Ken hit the leak this
+ * closes: a silent review turn's mid-turn reasoning ("I own personal-garmin,
+ * but the script I hand-rolled…") was captured by the outbox backstop and
+ * delivered into his DM as a raw, unlabelled message.
+ */
+export const REVIEW_SOURCE = 'self_improve_review'
+
+/**
+ * Did the turn that produced this capture originate from a self-improvement
+ * review inbound? Deterministic: it keys ONLY on the enqueue envelope's
+ * `source="…"` attribute (parsed upstream by `parseChannelEnvelope`), never on
+ * prose shape or a wording heuristic — the same source tag the rest of the
+ * self-improve machinery already routes on.
+ *
+ * @param {string | null | undefined} source The capture/record `source` field.
+ * @returns {boolean}
+ */
+export function isReviewOriginatedSource(source) {
+  return source === REVIEW_SOURCE
+}
+
 /**
  * Obligation state for the resolved chat, as seen at capture time.
  *
@@ -72,13 +105,46 @@ export const AUDIENCE_INTERNAL = 'internal'
  * would let a heuristic prose-shape match silently swallow a real answer —
  * exactly the severity-3 error this function is built to avoid.
  *
+ * `reviewOriginated` is the ONE other positive signal, and it is deterministic
+ * rather than heuristic. A self-improvement review turn is injected with a
+ * SYNTHESIZED inbound (`source="self_improve_review"`); no operator is waiting on
+ * an answer to it. Its contract (`buildReviewPrompt`) gives it exactly ONE
+ * operator-facing output: a well-formed self-improvement CARD (leading
+ * `SELF_IMPROVEMENT_TITLE` line) when — and only when — it surfaces a real
+ * outcome; otherwise it stays silent. So the review branch is checked FIRST and
+ * routes on card-shape:
+ *
+ *   - review + text IS a card (`reviewTextIsCard === true`) ⇒ `user`. The card
+ *     is the sanctioned surfacing message; deliver it. It is self-labelled by
+ *     construction (it opens with the title), so it can never appear as raw,
+ *     unlabelled reasoning.
+ *   - review + text is NOT a card ⇒ `internal`. This is the leak Ken hit — a
+ *     review turn's mid-turn reasoning captured by the backstop — and it is
+ *     SUPPRESSED. Deterministic: the gate is an EXACT title-line prefix, not a
+ *     fuzzy prose-shape guess, and the failure direction is SAFE (a mis-typed
+ *     card is withheld, never a real answer swallowed — a review inbound has no
+ *     waiting question to swallow, so this never manufactures the severity-3
+ *     silent no-op the asymmetry above guards against).
+ *
+ * `reviewTextIsCard` is scoped to review turns ONLY; it can never affect a
+ * normal user turn's classification, so the "no prose-shape heuristic on user
+ * text" rule above is intact.
+ *
  * @param {{
  *   replyToolThrewThisTurn?: boolean,
  *   openInboundObligation?: true | false | 'unknown',
+ *   reviewOriginated?: boolean,
+ *   reviewTextIsCard?: boolean,
  * }} signals
  * @returns {'user' | 'internal'}
  */
 export function decideCaptureAudience(signals) {
+  // Self-improvement review turns (see the header note): the sanctioned card
+  // delivers (`user`); any other trailing prose is the leak and is suppressed
+  // (`internal`). Deterministic, independent of the reply-throw path below.
+  if (signals?.reviewOriginated === true) {
+    return signals?.reviewTextIsCard === true ? AUDIENCE_USER : AUDIENCE_INTERNAL
+  }
   const threw = signals?.replyToolThrewThisTurn === true
   if (!threw) return AUDIENCE_USER
   // Only a POSITIVE, known-empty obligation state clears the second gate.
@@ -330,6 +396,133 @@ export function formatReplyThrowFraming(s) {
   )
 }
 
+/**
+ * ── Self-improvement review labelling (Ken, 2026-08-07) ──────────────────────
+ *
+ * TWO layers, both in this one shared module so the hook (which classifies +
+ * stamps) and the sweep (which delivers) run identical rules:
+ *
+ *   1. CARD GATE (primary, `decideCaptureAudience` above). A review turn's
+ *      trailing backstop text is delivered to the operator ONLY IF it is a
+ *      well-formed self-improvement card — `isSelfImprovementCard`, an EXACT
+ *      leading-`SELF_IMPROVEMENT_TITLE` prefix. Non-card review prose (the raw
+ *      reasoning Ken saw leak) classifies `internal` and is suppressed. This is
+ *      the deterministic "never leak raw reasoning; the card is the only
+ *      operator-facing output" guarantee.
+ *
+ *   2. TITLE FRAMING (residual). The card gate delivers only text that is
+ *      ALREADY self-titled, so in the default config the delivered body needs no
+ *      relabelling. This block is the belt-and-braces for the degraded config:
+ *      if the audience gate is turned OFF (`SWITCHROOM_TG_OUTBOX_AUDIENCE_GATE=0`)
+ *      so a NON-card review record reaches delivery, the title is prepended so it
+ *      can still never appear as raw, unlabelled reasoning. Idempotent: text that
+ *      already opens with the title is left untouched (no double title on a real
+ *      card). Mirrors the reply-throw framing above — pure predicate + pure body
+ *      transform + telemetry — and is additive only, so it can never manufacture
+ *      silence.
+ */
+
+/**
+ * The title line every self-improvement card opens with, and the label the
+ * residual framing prepends. `🔧 **Self-improvement**` — a leading glyph + bold
+ * so the operator sees at a glance this is a review note, not a normal reply.
+ * The card contract (`buildReviewPrompt`) continues the same line with
+ * ` — <one-line outcome>`, so this is a PREFIX of a real card, which is exactly
+ * what `isSelfImprovementCard` keys on.
+ */
+export const SELF_IMPROVEMENT_TITLE = '🔧 **Self-improvement**'
+
+/**
+ * Is `text` a well-formed self-improvement card — i.e. does it open with the
+ * `SELF_IMPROVEMENT_TITLE` line? This is the deterministic gate that separates
+ * the sanctioned surfacing card (deliver) from raw review reasoning (suppress).
+ *
+ * EXACT structural prefix, not a fuzzy prose-shape match: the model is
+ * instructed to emit the title verbatim as the first line of its one surfacing
+ * message, and the failure direction is SAFE — a mis-formatted card is withheld
+ * (silence), never a real answer delivered. Leading whitespace is tolerated so a
+ * stray newline before the title does not defeat the gate.
+ *
+ * @param {string | null | undefined} text
+ * @returns {boolean}
+ */
+export function isSelfImprovementCard(text) {
+  if (typeof text !== 'string') return false
+  return text.trimStart().startsWith(SELF_IMPROVEMENT_TITLE)
+}
+
+/**
+ * Should this record's delivered text carry the residual title header?
+ *
+ * POSITIVE evidence only: an exact `true` on the record's persisted
+ * `reviewOriginated`. Missing / `undefined` / `'true'` / `1` — anything that is
+ * not the boolean — changes nothing, so a non-review record (every normal turn)
+ * delivers byte-for-byte as it does today. Text that is already a card is a
+ * no-op at `applySelfImprovementFraming` (idempotent), so this predicate stays
+ * simple: "is this a review record".
+ *
+ * `frameEnabled === false` is the kill switch, and it is the seam a revert-check
+ * flips.
+ *
+ * @param {{ reviewOriginated?: unknown }} record
+ * @param {{ frameEnabled?: boolean }} [opts]
+ * @returns {boolean}
+ */
+export function shouldFrameSelfImprovement(record, opts) {
+  if (opts?.frameEnabled === false) return false
+  return record?.reviewOriginated === true
+}
+
+/**
+ * Compose the title header onto the delivered body. Pure; the caller owns the
+ * `(delayed) ` / `(from background task) ` delivery prefixes, which stay OUTSIDE
+ * (they describe the delivery, this describes the text). The title is the
+ * OUTERMOST content line so it always reads first, even when the reply-throw
+ * banner is also present.
+ *
+ * IDEMPOTENT: text that already opens with the title (a real card) is returned
+ * unchanged, so a delivered card never carries a duplicated title.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function applySelfImprovementFraming(text) {
+  const body = typeof text === 'string' ? text : ''
+  // Empty body: the sweep's send adapter early-returns on empty text, and a
+  // title over nothing would be a message about nothing. Leave it.
+  if (body.trim().length === 0) return body
+  // Already a card — do not prepend a second title.
+  if (isSelfImprovementCard(body)) return body
+  return `${SELF_IMPROVEMENT_TITLE}\n\n${body}`
+}
+
+/**
+ * Structured telemetry for a self-improvement-framed delivery — the
+ * observability half of the rule, mirroring {@link formatReplyThrowFraming}.
+ * Framing changes what a human sees, so it must never be inferable only from the
+ * absence of a log line. Worded to match NONE of `GATEWAY_SIGNATURES` in
+ * `src/fleet-health/detect.ts`: a framed delivery IS a delivery, and must not
+ * page anyone.
+ *
+ * @param {{
+ *   turnNonce: string,
+ *   turnId?: string | null,
+ *   chatId?: string | null,
+ *   textSha256?: string,
+ *   source?: string,
+ * }} s
+ * @returns {string}
+ */
+export function formatSelfImprovementFraming(s) {
+  return (
+    `telegram gateway: outbox self-improvement framing nonce=${s.turnNonce} ` +
+    `turnId=${s.turnId ?? 'unknown'} chatId=${s.chatId ?? 'unresolved'} ` +
+    `sha=${(s.textSha256 ?? '').slice(0, 12)} source=${s.source ?? 'unknown'} ` +
+    `reviewOriginated=true — review-turn prose delivered with its self-improvement ` +
+    `title, never as raw unlabelled reasoning\n`
+  )
+}
+
 /**
  * The structured telemetry line emitted when the sweep suppresses an
  * `internal` record. Mirrors `formatOrphanEscalation` (#4104): an exported pure