switchroom 0.20.11 → 0.20.13

package/telegram-plugin/gateway/turn-record-status.ts

@@ -24,6 +24,37 @@
  */
 export type DeliveryOutcome = 'delivered' | 'failed' | 'suppressed'
 
+/**
+ * The ONE way a turn's `duration_ms` is computed, shared by every emitter
+ * (`buildTurnRecord` → turns.jsonl, and all three `turn_ended` runtime-metric
+ * sites: the two stream-render turn-end paths + the liveness framework_fallback).
+ *
+ * Why a single helper: the three `turn_ended` emitters each hand-rolled the
+ * subtraction, and one drifted. `stream-render.ts` guarded with
+ * `startedAt > 0 ? now - startedAt : 0`; the framework_fallback path in
+ * `liveness-wiring.ts` did a bare `Date.now() - turnStartedAt` with only a
+ * `!= null` presence check. When `activeTurnStartedAt` held `0` (or any
+ * non-positive / non-finite value), that path emitted `duration_ms = now - 0`,
+ * i.e. the absolute Unix-epoch-ms — a ~56,000-year "duration". This poisoned the
+ * analysed turn_ended dataset (observed: 110 rows where `duration_ms === ts`),
+ * making every latency aggregate unusable.
+ *
+ * The invariant this helper enforces: a `duration_ms` is ALWAYS a non-negative
+ * elapsed-milliseconds value derived from a positive, finite start stamp — never
+ * an absolute epoch value, never negative (clock step back), never NaN. A start
+ * that is missing / zero / bogus yields `0` (a bounded, filterable sentinel)
+ * instead of a value that destroys aggregates.
+ */
+export function computeTurnDurationMs(
+  startedAt: number | null | undefined,
+  now: number,
+): number {
+  if (typeof startedAt !== 'number' || !Number.isFinite(startedAt) || startedAt <= 0) {
+    return 0
+  }
+  return Math.max(0, now - startedAt)
+}
+
 /** The status strings written to turns.jsonl. `send_failed` is new in PR B. */
 export type TurnStatus = 'complete' | 'no_reply' | 'send_failed'
 
@@ -261,7 +292,7 @@ export function buildTurnRecord(
   return {
     ts: Math.floor(endedAt / 1000),
     agent: turn.agent,
-    duration_ms: turn.startedAt > 0 ? endedAt - turn.startedAt : 0,
+    duration_ms: computeTurnDurationMs(turn.startedAt, endedAt),
     tools: turn.toolCallCount ?? 0,
     status: computeTurnStatus(turn),
     turn_id: turn.turnId,

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

package/telegram-plugin/hooks/hooks.json

@@ -5,16 +5,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard-pretool.mjs\"",
             "timeout": 10
           }
         ]
       },
       {
+        "matcher": "^mcp__switchroom-telegram__(reply|stream_reply)$",
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/sentinel-reply-guard-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/sentinel-reply-guard-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -24,7 +25,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-pretool.mjs\"",
             "timeout": 10
           }
         ]
@@ -33,7 +34,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -43,7 +44,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/repo-context-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/repo-context-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -55,7 +56,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-posttool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-posttool.mjs\"",
             "timeout": 10
           }
         ]
@@ -65,7 +66,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-hint-posttool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-hint-posttool.mjs\"",
             "timeout": 3
           }
         ]
@@ -76,7 +77,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/compaction-marker-precompact.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/compaction-marker-precompact.mjs\"",
             "timeout": 5
           }
         ]
@@ -87,7 +88,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-scrub-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-scrub-stop.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -97,7 +98,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/silent-end-interrupt-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/silent-end-interrupt-stop.mjs\"",
             "timeout": 5
           }
         ]
@@ -106,7 +107,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/dispatch-claim-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/dispatch-claim-stop.mjs\"",
             "timeout": 5
           }
         ]
@@ -115,7 +116,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-stop.mjs\"",
             "timeout": 5,
             "async": true
           }

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

@@ -108,7 +108,7 @@ export function isStructuralNarration(text, followedByToolUse) {
  * follow-up, MF4). A text block followed ONLY by tools in this set is still the
  * TERMINAL answer for backstop-coalescing purposes — these tools carry no
  * model-authored answer text and are the only ones plausibly fired AFTER a
- * terminal answer (answer, then react / pin / typing / edit). Everything NOT in
+ * terminal answer (answer, then react / typing / edit). Everything NOT in
  * this set — work / deliverable tools (download_attachment, get_recent_messages,
  * send_checklist, ask_user, …) and every non-telegram tool (retain / read /
  * bash / web / …) — is turn-CONTINUING: a text block a real tool followed is
@@ -123,7 +123,6 @@ export function isStructuralNarration(text, followedByToolUse) {
 export const EPHEMERAL_TOOLS = new Set([
   'react',
   'send_typing',
-  'pin_message',
   'delete_message',
   'edit_message',
 ])

package/telegram-plugin/hooks/silent-end-interrupt-stop.mjs

@@ -72,6 +72,8 @@ import {
 import {
   decideCaptureAudience,
   resolveOpenObligation,
+  isReviewOriginatedSource,
+  isSelfImprovementCard,
   AUDIENCE_INTERNAL,
 } from './audience-classify.mjs'
 
@@ -129,6 +131,19 @@ function buildNextState(base, decision, retryCount) {
   } else {
     delete next.replyToolThrewThisTurn
   }
+  // #4490: same carry-through for review-turn provenance. The outbox capture
+  // path (`writeOutboxRecord` above) stamps `reviewOriginated` from the SAME
+  // envelope `source` tag; the ELECTED path ('trailing-text-after-reply') never
+  // writes an outbox record, so the captured-prose bridge (the delivering
+  // machine on this path) has no other way to learn it. Explicitly deleted
+  // when this turn's scan saw no review-source envelope, so a spread of a
+  // prior turn's file can never mislabel a normal turn's prose as a review
+  // turn's (or vice versa).
+  if (isReviewOriginatedSource(decision.source)) {
+    next.reviewOriginated = true
+  } else {
+    delete next.reviewOriginated
+  }
   return next
 }
 
@@ -181,7 +196,7 @@ function outboxAlreadyDelivered(outboxDir, nonce) {
  * `'unknown'` → the record delivers exactly as it does today.
  *
  * @param {string} stateDir
- * @param {{ chatId: string|null, originChatId?: string|null, replyToolThrewThisTurn?: boolean }} capture
+ * @param {{ chatId: string|null, originChatId?: string|null, replyToolThrewThisTurn?: boolean, source?: string|null }} capture
  * @returns {'user' | 'internal'}
  */
 function classifyCaptureAudience(stateDir, capture) {
@@ -212,6 +227,14 @@ function classifyCaptureAudience(stateDir, capture) {
     process.env.TELEGRAM_ACCESS_MODE !== 'static'
   return decideCaptureAudience({
     replyToolThrewThisTurn: capture.replyToolThrewThisTurn === true,
+    // A self-improvement review turn has exactly ONE sanctioned operator-facing
+    // output: a well-formed self-improvement CARD. Deterministic on the enqueue
+    // envelope's `source` tag (the same signal the rest of the self-improve
+    // machinery routes on) plus the EXACT card-shape of the captured text. A
+    // card delivers; any other trailing prose (the raw-reasoning leak) is
+    // suppressed. Independent of the reply-throw / obligation state below.
+    reviewOriginated: isReviewOriginatedSource(capture.source),
+    reviewTextIsCard: isSelfImprovementCard(capture.text),
     openInboundObligation: resolveOpenObligation({
       snapshotRaw,
       snapshotTrusted,
@@ -265,6 +288,13 @@ function writeOutboxRecord(stateDir, capture, audience) {
       // not catch (the foreground case). Stamped here because this is the last
       // point in the pipeline that can still see the transcript.
       replyToolThrewThisTurn: capture.replyToolThrewThisTurn === true,
+      // Ken 2026-08-07: did this turn originate from a self-improvement review
+      // inbound? `audience` already consumed it (with the card-shape signal) to
+      // deliver a well-formed card and suppress raw reasoning by default; the
+      // sweep consumes this raw flag again, on its own, to prepend the
+      // self-improvement TITLE to any review record delivered with the audience
+      // gate OFF, so review reasoning can never appear as raw, unlabelled prose.
+      reviewOriginated: isReviewOriginatedSource(capture.source),
     }
     const tmpPath = join(outboxDir, `.${capture.turnNonce}.${process.pid}.tmp`)
     writeFileSync(tmpPath, JSON.stringify(record), 'utf8')

package/telegram-plugin/hooks/silent-end-scan.mjs

@@ -41,7 +41,7 @@
 // Cross-checked the full tool surface in `telegram-plugin/bridge/bridge.ts`
 // (`TOOL_SCHEMAS`, kept in sync with `gateway/gateway.ts`): `edit_message`
 // explicitly does NOT ping/deliver a fresh answer (its own description says
-// "send a new reply when a long task completes"); `react`, `pin_message`,
+// "send a new reply when a long task completes"); `react`,
 // `delete_message`, `forward_message`, `send_typing`, `download_attachment`,
 // `get_recent_messages` carry no model-authored answer text at all;
 // `send_checklist` / `send_sticker` / `send_gif` / `ask_user` /
@@ -259,6 +259,13 @@ function buildTurnId(chatId, threadId, messageId) {
  */
 function buildBlockResult(envelope, reason, pendingText, hasTrailingProse, replyToolThrewThisTurn) {
   const block = { decided: 'block', reason }
+  // #4490: the enqueue envelope's RAW `source` tag, carried through exactly
+  // like `replyToolThrewThisTurn` above — the single-writer election needs it
+  // to derive `reviewOriginated` for the captured-prose bridge (the ELECTED
+  // path's deliverer, which never writes an outbox record and so has no other
+  // way to learn a review turn's provenance). Omitted when the envelope carried
+  // none, so a spread of a prior state file is never read as positive evidence.
+  if (envelope.source != null) block.source = envelope.source
   if (replyToolThrewThisTurn === true) block.replyToolThrewThisTurn = true
   // Single-writer election input (#duplicate-message fix): does ANY
   // non-empty, non-silent trailing text block exist after the last
@@ -360,7 +367,7 @@ function buildBlockResult(envelope, reason, pendingText, hasTrailingProse, reply
  * false-positive that burned retry budget on healthy turns.
  *
  * @param {string} jsonl
- * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnKey?: string, turnId?: string, chatId?: string, threadId?: number | null, pendingText?: string }}
+ * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnKey?: string, turnId?: string, chatId?: string, threadId?: number | null, pendingText?: string, source?: string, replyToolThrewThisTurn?: boolean }}
  */
 export function scanTurnForFinalReply(jsonl) {
   const lines = jsonl.split('\n')

package/telegram-plugin/outbox.ts

@@ -75,6 +75,9 @@ import type { Audience } from './hooks/audience-classify.mjs'
 import {
   applyReplyThrowFraming,
   shouldFrameReplyThrow,
+  applySelfImprovementFraming,
+  shouldFrameSelfImprovement,
+  isSelfImprovementCard,
 } from './hooks/audience-classify.mjs'
 
 export type { Audience }
@@ -162,6 +165,25 @@ export interface OutboxRecord {
    * exact boolean `true` changes anything — see `shouldFrameReplyThrow`.
    */
   replyToolThrewThisTurn?: boolean
+  /**
+   * Ken 2026-08-07: did the turn that produced this record originate from a
+   * self-improvement review inbound (`source="self_improve_review"`)? Stamped at
+   * capture by `hooks/silent-end-interrupt-stop.mjs` from the enqueue envelope's
+   * source tag.
+   *
+   * `audience` already consumed it once — a review turn classifies `'internal'`
+   * (`decideCaptureAudience`), so by default it is SUPPRESSED at the sweep's
+   * entry gate and never delivered. The sweep consumes this raw flag again, on
+   * its own, only for the residual: a review record that IS delivered (the
+   * audience gate turned off, or a legacy/`user` route) must carry the
+   * self-improvement TITLE so it can never appear as raw, unlabelled agent
+   * reasoning — the leak this closes.
+   *
+   * OPTIONAL: absent on every pre-change record and on non-review turns, which
+   * deliver unframed. Only an exact boolean `true` changes anything — see
+   * `shouldFrameSelfImprovement`.
+   */
+  reviewOriginated?: boolean
 }
 
 /** One line of the delivered-keys journal (`outbox/delivered.jsonl`). */
@@ -204,6 +226,16 @@ export interface DeliveredEntry {
    * framed delivery is a delivery.
    */
   framedProvenance?: 'reply-throw'
+  /**
+   * Ken 2026-08-07: this delivery carried the self-improvement TITLE header
+   * (`SELF_IMPROVEMENT_TITLE`) in front of a review-originated record's prose.
+   * Durable and terminal, for the same reason `framedProvenance` is: framing
+   * changes what a human sees, so the outcome is recorded as an explicit named
+   * state on the journal line rather than being inferable only from a log line
+   * that may have rotated away. `tgMessageId` IS present on these lines — a
+   * framed delivery is a delivery.
+   */
+  framedSelfImprovement?: 'self-improve'
 }
 
 export function sha256Hex(s: string): string {
@@ -519,6 +551,13 @@ export interface OutboxSweepDecision {
    * the rule.
    */
   framedProvenance?: 'reply-throw'
+  /**
+   * Ken 2026-08-07: `text` carries the self-improvement title header. Surfaced
+   * on the decision (rather than left implicit in a string compare) so the
+   * caller can journal the outcome and emit telemetry without re-deriving the
+   * rule — same shape as `framedProvenance`.
+   */
+  framedSelfImprovement?: 'self-improve'
 }
 
 /**
@@ -538,7 +577,7 @@ export interface OutboxSweepDecision {
 export function decideOutboxSweep(input: {
   record: Pick<
     OutboxRecord,
-    'turnNonce' | 'text' | 'createdAt' | 'replyToolThrewThisTurn'
+    'turnNonce' | 'text' | 'createdAt' | 'replyToolThrewThisTurn' | 'reviewOriginated'
   >
   now: number
   deliveredNonces: Set<string>
@@ -566,6 +605,13 @@ export function decideOutboxSweep(input: {
    * revert-check can flip it in-process.
    */
   provenanceFraming?: boolean
+  /**
+   * Ken 2026-08-07 kill switch for the self-improvement TITLE header. `false`
+   * restores the pre-change body byte-for-byte; the default is ON. Passed in
+   * rather than read from env here so this core stays pure and a revert-check
+   * can flip it in-process.
+   */
+  selfImprovementFraming?: boolean
 }): OutboxSweepDecision {
   const {
     record,
@@ -578,6 +624,7 @@ export function decideOutboxSweep(input: {
     maxAgeMs = OUTBOX_MAX_AGE_MS,
     shownLedgerHit = false,
     provenanceFraming = true,
+    selfImprovementFraming = true,
   } = input
   if (deliveredNonces.has(record.turnNonce)) return { action: 'skip-journaled' }
   if (shownLedgerHit) return { action: 'skip-ephemeral-shown' }
@@ -592,11 +639,30 @@ export function decideOutboxSweep(input: {
   // the banner describes the TEXT. It is additive only: it can never turn a
   // send into a skip, so this branch cannot manufacture silence.
   const framed = shouldFrameReplyThrow(record, { frameEnabled: provenanceFraming })
-  const body = framed ? applyReplyThrowFraming(record.text) : record.text
+  const provenanceBody = framed ? applyReplyThrowFraming(record.text) : record.text
+  // Ken 2026-08-07: the self-improvement title is the OUTERMOST content line, so
+  // it is applied AFTER the reply-throw banner — a review record that somehow
+  // also threw reads "🔧 Self-improvement" first, then the provenance note, then
+  // the prose. Additive only: it can never turn a send into a skip.
+  //
+  // #4489: idempotency is gated on the RAW `record.text`, NOT on `provenanceBody`.
+  // A real card's `record.text` opens with the title; the reply-throw banner
+  // above is PREPENDED in front of it, so `provenanceBody` no longer opens with
+  // the title even though the underlying card does. `applySelfImprovementFraming`
+  // alone can't see that — its idempotency check only looks at what it was
+  // handed — so gating the whole decision on the raw text is what keeps a real
+  // card from acquiring a second, duplicated title when both framings compose.
+  const selfImproveFramed =
+    shouldFrameSelfImprovement(record, { frameEnabled: selfImprovementFraming }) &&
+    !isSelfImprovementCard(record.text)
+  const body = selfImproveFramed ? applySelfImprovementFraming(provenanceBody) : provenanceBody
   return {
     action: delayed ? 'send-delayed' : 'send',
     text: prefix + body,
-    ...(framed && body !== record.text ? { framedProvenance: 'reply-throw' as const } : {}),
+    ...(framed && provenanceBody !== record.text ? { framedProvenance: 'reply-throw' as const } : {}),
+    ...(selfImproveFramed && body !== provenanceBody
+      ? { framedSelfImprovement: 'self-improve' as const }
+      : {}),
   }
 }