switchroom 0.21.7 → 0.21.9

package/telegram-plugin/gateway/approval-outcome-sources.ts

@@ -0,0 +1,274 @@
+/**
+ * The single registry of "this inbound carries an approval OUTCOME".
+ *
+ * An approval outcome is a synthetic inbound that reports the RESULT of an
+ * operator decision the agent is blocked on: a vault grant approved/denied,
+ * a secret provided/declined, a mental-model proposal applied, a button tap.
+ * It is structurally different from an ordinary chat message in one way that
+ * matters to the inbound buffer: **the operator cannot resend it.** If a
+ * `vault_grant_approved` is dropped, telling the user "please resend that
+ * message" is meaningless — the tap already happened, the grant already
+ * exists, and the agent waits forever for a wake-up that will never come.
+ *
+ * That asymmetry is why cap eviction in `pending-inbound-buffer.ts` may not
+ * pick its victim blindly. An ordinary user message is resendable; an
+ * approval outcome is not. So the buffer evicts the oldest NON-outcome first
+ * and only touches an outcome when there is genuinely nothing else to drop.
+ *
+ * Membership is deliberately a closed literal set rather than a prefix/regex
+ * match on `meta.source`: a new source string must be classified by a human
+ * (or an agent reading this comment), not silently inherit protection from a
+ * naming coincidence. The set is exhaustive against `telegram-plugin/gateway/`
+ * as of this commit.
+ *
+ * No imports beyond the inbound type. The set, the predicate and the notice
+ * builder are pure, so the buffer hot path can import them freely;
+ * `createApprovalOutcomeDropNotifier` is the one stateful export (the gateway's
+ * re-entrancy latch) and lives here rather than inline in `gateway.ts` so the
+ * production wiring is the thing tests drive, not a copy of it.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+/**
+ * `meta.source` values that identify an inbound as an approval outcome.
+ *
+ * Grepped exhaustively from `telegram-plugin/gateway/` (both quote styles —
+ * the `mental_model_proposal_*` builders use double quotes, which is how an
+ * earlier single-quote-only survey missed them).
+ *
+ * Deliberately EXCLUDED, with reasons:
+ *   - `missed_approval_retry` — carries no verdict. It ASKS the agent to
+ *     re-attempt actions that timed out (`missed-approvals-card.ts:117-161`),
+ *     and the operator can tap "retry" again. Resendable ⇒ ordinary.
+ *   - `obligation_represent` / `subagent_handback` / `subagent_progress` /
+ *     `resume_*` / `warmup` / `reaction` / `bridge_dead_restart` — internal
+ *     nudges and lifecycle wake-ups, all regenerated by their own sweeps.
+ *
+ * `eval_case_applied` / `eval_case_rejected` / `eval_case_apply_failed` are
+ * listed AHEAD of the branch that introduces them. Listing an unused source
+ * is inert (nothing ever carries it), and it removes any ordering constraint
+ * between the two changes — the alternative is a window where eval-case
+ * verdicts are evictable.
+ *
+ * `eval_case_suppressed` is protected for the SAME reason, and it is the one
+ * member that is not a verdict card at all. It is the gateway's own notice
+ * that a re-proposed eval case was dropped against a live dismissal — the
+ * agent's turn is blocked on it and NO sweep regenerates it (it fires exactly
+ * once, at the moment of suppression, and the suppression path posts no card).
+ * Unprotected it would be tier-1's preferred victim, so a cap overflow would
+ * restore the silent block the notice exists to close.
+ */
+export const APPROVAL_OUTCOME_SOURCES: ReadonlySet<string> = Object.freeze(
+  new Set([
+    // vault grant decisions (#1150 — the original dropped-wake-up class)
+    'vault_grant_approved',
+    'vault_grant_denied',
+    'vault_grant_timeout',
+    // vault save decisions
+    'vault_save_completed',
+    'vault_save_discarded',
+    'vault_save_failed',
+    'vault_save_timeout',
+    // secret-request decisions
+    'secret_provided',
+    'secret_declined',
+    'secret_provide_failed',
+    'secret_request_timeout',
+    // mental-model proposal decisions
+    'mental_model_proposal_applied',
+    'mental_model_proposal_denied',
+    'mental_model_proposal_failed',
+    'mental_model_propose_timeout',
+    // skill proposal decision
+    'skill_proposal_apply',
+    // eval-case proposal decisions (forward-listed; see doc comment)
+    'eval_case_applied',
+    'eval_case_rejected',
+    'eval_case_apply_failed',
+    // #4664's suppressed-proposal notice. Not itself a tap, but it reports the
+    // standing effect of one the operator ALREADY made (the Dismiss that
+    // recorded the rejection), and it is the only thing that ends the agent's
+    // wait — see the doc comment above.
+    'eval_case_suppressed',
+  ]),
+) as ReadonlySet<string>
+
+/**
+ * `meta.source` stamped on the synthetic notice the gateway pushes when an
+ * approval outcome had to be dropped anyway (every buffered entry was an
+ * outcome). Deliberately NOT a member of `APPROVAL_OUTCOME_SOURCES`: the
+ * notice must be the PREFERRED victim of the next overflow, which is what
+ * structurally bounds the notice→evict→notice recursion.
+ */
+export const APPROVAL_OUTCOME_DROPPED_SOURCE = 'approval_outcome_dropped'
+
+/**
+ * True when `msg` reports the result of an operator decision.
+ *
+ * TWO conditions, both required — a button tap has NO `meta.source` at all.
+ * `agent-button-callback-handler.ts:123-133` stamps only
+ * `meta.button_callback = 'true'` (plus `button_callback_data` / `button_text`),
+ * so a source-only check silently leaves every agent-card tap evictable.
+ */
+export function isApprovalOutcome(msg: InboundMessage): boolean {
+  const meta = msg.meta
+  if (meta == null) return false
+  if (meta.source != null && APPROVAL_OUTCOME_SOURCES.has(meta.source)) return true
+  return meta.button_callback === 'true'
+}
+
+/** Human label for an outcome in logs / notices. Taps carry no source. */
+export function approvalOutcomeLabel(msg: InboundMessage): string {
+  const src = msg.meta?.source
+  if (src != null && src !== '') return src
+  if (msg.meta?.button_callback === 'true') return 'button_callback'
+  return '-'
+}
+
+/**
+ * Build the synthetic inbound that tells the agent an approval outcome was
+ * dropped, so it stops waiting on a wake-up that is never arriving. Pure.
+ *
+ * It names the dropped source(s) rather than paraphrasing, because the agent's
+ * next move depends on which one it was (a dropped `vault_grant_approved`
+ * means "retry the vault read and see if the grant exists"; a dropped
+ * `secret_declined` means "the operator said no").
+ */
+export function buildApprovalOutcomeDroppedInbound(opts: {
+  agent: string
+  chatId: string
+  threadId?: number
+  sources: string[]
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  const list = opts.sources.length > 0 ? opts.sources.join(', ') : 'unknown'
+  const plural = opts.sources.length === 1 ? 'an approval outcome' : 'approval outcomes'
+  const msg: InboundMessage = {
+    type: 'inbound',
+    chatId: opts.chatId,
+    ...(opts.threadId != null ? { threadId: opts.threadId } : {}),
+    messageId: ts,
+    user: 'gateway',
+    userId: 0,
+    ts,
+    text:
+      `⚠️ Your inbound buffer overflowed while every queued message was ${plural}, ` +
+      `so the oldest had to be dropped: ${list}. Do NOT keep waiting on it — ` +
+      `re-check the underlying state directly (e.g. retry the vault read to see ` +
+      `whether the grant exists) and tell the operator plainly what was lost.`,
+    meta: {
+      source: APPROVAL_OUTCOME_DROPPED_SOURCE,
+      agent: opts.agent,
+      ...(opts.threadId != null ? { message_thread_id: String(opts.threadId) } : {}),
+      dropped_sources: list,
+      dropped_count: String(opts.sources.length),
+    },
+  }
+  return msg
+}
+
+/** Max follow-up notice hops per burst. See `createApprovalOutcomeDropNotifier`. */
+export const APPROVAL_OUTCOME_NOTICE_HOPS = 2
+
+/**
+ * Build the `onEvictCritical` handler the gateway wires into the pending
+ * inbound buffer: log at a distinct greppable tag, then enqueue ONE synthetic
+ * notice naming every outcome dropped since the last notice.
+ *
+ * Two properties this exists to guarantee, both of which a hand-inlined
+ * version in `gateway.ts` would get wrong:
+ *
+ *  - **Never pushes inside the `push` frame.** `onEvictCritical` is invoked
+ *    from the middle of `push`, on a queue sitting at cap. Pushing there
+ *    recurses. Every enqueue goes through `queueMicrotask`.
+ *  - **Terminates.** Deferring alone does not stop recursion, it only turns a
+ *    stack overflow into an unbounded microtask loop. Termination is
+ *    structural: the notice carries `approval_outcome_dropped`, which is NOT a
+ *    member of `APPROVAL_OUTCOME_SOURCES`, so the moment one is resident it
+ *    becomes the PREFERRED eviction victim and no further critical eviction can
+ *    fire until it drains. The `scheduled` latch collapses a burst into one
+ *    notice, and `hops` is a hard budget on top of the structural bound so a
+ *    future change to victim selection degrades into a truncated chain rather
+ *    than a spin.
+ *
+ * KNOWN COST, accepted deliberately: in the pathological state (every one of
+ * the 32 slots is a fresh approval outcome) the notice's own push evicts one
+ * MORE outcome to make room for itself. So that state costs two dropped
+ * outcomes instead of one. The exchange is that the agent is TOLD — the
+ * alternative is 32 resident outcomes and an agent blocked forever on a
+ * wake-up that was silently discarded. Reaching this state at all requires 32
+ * simultaneously-undelivered operator decisions for one agent.
+ */
+export function createApprovalOutcomeDropNotifier(opts: {
+  /** Enqueue the notice. Wired to the buffer's own `push`. */
+  push: (agent: string, msg: InboundMessage) => void
+  log?: (line: string) => void
+  /** Defer seam. Defaults to `queueMicrotask`. */
+  defer?: (fn: () => void) => void
+  nowMs?: () => number
+  hops?: number
+}): (agent: string, evicted: InboundMessage) => void {
+  const log = opts.log ?? ((line: string) => process.stderr.write(line))
+  const defer = opts.defer ?? ((fn: () => void) => queueMicrotask(fn))
+  const hops = opts.hops ?? APPROVAL_OUTCOME_NOTICE_HOPS
+  /** agent → labels of outcomes dropped since the last notice was built. */
+  const pending = new Map<string, string[]>()
+  /** agent → a notice enqueue is already scheduled (the re-entrancy latch). */
+  const scheduled = new Set<string>()
+
+  return (agent, evicted) => {
+    const label = approvalOutcomeLabel(evicted)
+    log(
+      `telegram gateway: APPROVAL-OUTCOME-DROPPED agent=${agent} source=${label} ` +
+      `chat=${evicted.chatId} ts=${evicted.ts}\n`,
+    )
+    const list = pending.get(agent) ?? []
+    list.push(label)
+    pending.set(agent, list)
+    if (scheduled.has(agent)) return
+    scheduled.add(agent)
+    const chatId = evicted.chatId
+    const threadId = evicted.threadId
+
+    const flush = (budget: number): void => {
+      // CUMULATIVE, and deliberately not cleared before the push: the notice we
+      // are about to enqueue can itself be the entry a later overflow evicts
+      // (it is the preferred victim, by design). If each hop named only the
+      // drops since the last one, the surviving notice would omit the earliest
+      // dropped source — the one the agent is most likely to be blocked on. So
+      // every hop restates the whole burst and the list is cleared only when
+      // the chain ends.
+      const sources = [...(pending.get(agent) ?? [])]
+      const before = sources.length
+      try {
+        opts.push(
+          agent,
+          buildApprovalOutcomeDroppedInbound({
+            agent,
+            chatId,
+            ...(threadId != null ? { threadId } : {}),
+            sources,
+            ...(opts.nowMs != null ? { nowMs: opts.nowMs() } : {}),
+          }),
+        )
+      } catch (e) {
+        log(`telegram gateway: APPROVAL-OUTCOME-DROPPED notice push failed: ${String(e)}\n`)
+      } finally {
+        scheduled.delete(agent)
+      }
+      // The push above ran against a queue at cap, so it may itself have
+      // evicted one more outcome (re-entering this handler with the latch still
+      // set, which recorded the label but scheduled nothing). A GROWN list is
+      // the signal that happened. Re-state, once more, then stop.
+      if (budget > 0 && (pending.get(agent)?.length ?? 0) > before) {
+        scheduled.add(agent)
+        defer(() => flush(budget - 1))
+      } else {
+        pending.delete(agent)
+      }
+    }
+    defer(() => flush(hops))
+  }
+}

package/telegram-plugin/gateway/bridge-dead-watchdog.ts

@@ -228,16 +228,28 @@ export function writeBridgeDeadEscalationMarker(
 /**
  * Read + consume the escalation marker at boot. Returns the marker only
  * when it is fresh (< maxAgeMs); a stale or malformed marker is cleared
- * and ignored. The file is ALWAYS removed — the cause note must surface
- * on exactly the boot that follows the escalation, never a later one.
+ * and ignored. Whenever this function runs the file IS removed — the cause
+ * note must surface on exactly the boot that follows the escalation, never
+ * a later one.
  *
- * Known race window (accepted, documented per review): the marker is
- * written by gateway boot N and consumed by whichever gateway boots NEXT.
- * Normally that is the post-container-restart gateway (the SIGTERM to
- * PID 1 fires ~1.5s after the write and takes the whole container down).
- * But if the escalating gateway PROCESS dies and its supervisor relaunches
- * a new gateway inside the same container before the SIGTERM lands, that
- * interim gateway consumes the marker instead — the cause note is then
+ * Since #4641 the caller does not always run: the gateway's boot-resume
+ * block `break`s before reaching this call when the per-container-boot
+ * generation token says only the GATEWAY respawned. That narrows — and for
+ * the common shape closes — the race documented below, so it is an
+ * improvement rather than a hole; the marker is left on disk for the boot
+ * that genuinely follows the container restart. See "What `break
+ * bootResumeInit` skips" in agent-process-liveness.ts.
+ *
+ * Known race window (accepted, documented per review; largely closed by the
+ * #4641 guard above): the marker is written by gateway boot N and consumed
+ * by whichever gateway boots NEXT and reaches this call. Normally that is
+ * the post-container-restart gateway (the SIGTERM to PID 1 fires ~1.5s
+ * after the write and takes the whole container down). But if the
+ * escalating gateway PROCESS dies and its supervisor relaunches a new
+ * gateway inside the same container before the SIGTERM lands, and that
+ * interim gateway's boot block is NOT suppressed by the generation token
+ * (i.e. no gateway in this generation had completed its boot resume yet),
+ * the interim gateway consumes the marker instead — the cause note is then
  * surfaced (or dropped with the interim process) one boot early, and the
  * post-restart boot sees no marker. Consequences are bounded and safe:
  * the honesty note may be lost for one incident (the loud supervisor-log

package/telegram-plugin/gateway/callback-query-handlers.ts

@@ -75,6 +75,11 @@ import {
   getEvalCaseProposal,
   setEvalCaseProposalStatus,
 } from '../../src/self-improve/eval-case-proposals.js'
+import {
+  buildEvalCaseAppliedInbound,
+  buildEvalCaseRejectedInbound,
+  buildEvalCaseApplyFailedInbound,
+} from './eval-case-proposal-inbound-builders.js'
 import { maskToken } from '../secret-detect/mask.js'
 import {
   defaultVaultWrite,
@@ -464,6 +469,19 @@ export interface CallbackQueryHandlersDeps {
   brokerList?: typeof realListViaBroker
   brokerListGrants?: typeof realListGrantsViaBroker
   brokerVaultTokenFilePath?: typeof realVaultTokenFilePath
+
+  /**
+   * Run the DETERMINISTIC eval-case applier for an approved proposal. Returns
+   * `ok` plus the applier's combined output tail (both go on the card footer
+   * and into the outcome inbound the agent is woken with).
+   *
+   * Injectable for the same reason as the broker seams above: production leaves
+   * it unset and gets the real `switchroom self-improve apply-eval-case`
+   * `execFileSync`, but a unit test cannot shell out to a real CLI, so the
+   * approve path's two branches (applied / apply-failed) were untestable while
+   * this was a bare static import.
+   */
+  runEvalCaseApply?: (id: string) => { ok: boolean; out: string }
 }
 
 // Freshness throttle for the /auth dashboard ↻ refresh button — one live
@@ -625,6 +643,27 @@ export function createCallbackQueryHandlers(deps: CallbackQueryHandlersDeps) {
   const listViaBroker = deps.brokerList ?? realListViaBroker
   const listGrantsViaBroker = deps.brokerListGrants ?? realListGrantsViaBroker
   const vaultTokenFilePath = deps.brokerVaultTokenFilePath ?? realVaultTokenFilePath
+  // Eval-case applier seam. The default body is verbatim the execFileSync that
+  // used to sit inline in handleEvalCaseProposalCallback.
+  const runEvalCaseApply =
+    deps.runEvalCaseApply ??
+    ((id: string): { ok: boolean; out: string } => {
+      const cli = process.env.SWITCHROOM_CLI_PATH ?? 'switchroom'
+      try {
+        const out = execFileSync(
+          cli,
+          ['self-improve', 'apply-eval-case', '--id', id],
+          { encoding: 'utf8', timeout: 15000, env: process.env },
+        ).trim()
+        return { ok: true, out }
+      } catch (err) {
+        const e = err as { stdout?: string; stderr?: string; message?: string }
+        return {
+          ok: false,
+          out: [e.stdout, e.stderr, e.message].filter(Boolean).join('\n').trim(),
+        }
+      }
+    })
 
 /**
  * Handle a callback_query from an auth dashboard button. Parses the
@@ -1377,8 +1416,31 @@ async function handleEvalCaseProposalCallback(ctx: Context, data: string): Promi
     return
   }
 
+  // Same idiom as the skill handler above: the card's own chat/topic is where
+  // the proposing agent was working, so the outcome inbound resumes it there.
+  const cbChatId = String(ctx.chat?.id ?? ctx.from?.id ?? '')
+  const cbThreadId = resolveThreadId(cbChatId, ctx.callbackQuery?.message?.message_thread_id)
+  const inboundCtx = {
+    agent,
+    chat_id: cbChatId,
+    ...(cbThreadId != null ? { threadId: cbThreadId } : {}),
+  }
+
   if (parsed.action === 'deny') {
     setEvalCaseProposalStatus(stateDir, parsed.id, 'rejected')
+    // The agent is TOLD it was dismissed. The skill handler stays silent here;
+    // silence is the defect — a dismissed proposal left the agent waiting on a
+    // wake-up that never came.
+    const denied = deliverResumeSyntheticOrBuffer(
+      agent,
+      buildEvalCaseRejectedInbound({
+        ctx: inboundCtx,
+        proposalId: proposal.id,
+        skillSlug: proposal.skill_slug,
+        heldOut: proposal.held_out,
+        operatorId: senderId,
+      }),
+    )
     await ctx.answerCallbackQuery({ text: '🚫 Dismissed.' }).catch(() => {})
     if (ctx.callbackQuery?.message && 'text' in ctx.callbackQuery.message) {
       await ctx
@@ -1388,6 +1450,10 @@ async function handleEvalCaseProposalCallback(ctx: Context, data: string): Promi
         )
         .catch(() => {})
     }
+    process.stderr.write(
+      `telegram gateway: eval_case_rejected agent=${agent} proposal=${proposal.id} ` +
+      `slug=${proposal.skill_slug} delivered=${denied}\n`,
+    )
     return
   }
 
@@ -1395,20 +1461,7 @@ async function handleEvalCaseProposalCallback(ctx: Context, data: string): Promi
   setEvalCaseProposalStatus(stateDir, parsed.id, 'approved')
   await ctx.answerCallbackQuery({ text: '✅ Adding the eval case…' }).catch(() => {})
 
-  const cli = process.env.SWITCHROOM_CLI_PATH ?? 'switchroom'
-  let applyOk = true
-  let applyOut = ''
-  try {
-    applyOut = execFileSync(
-      cli,
-      ['self-improve', 'apply-eval-case', '--id', parsed.id],
-      { encoding: 'utf8', timeout: 15000, env: process.env },
-    ).trim()
-  } catch (err) {
-    applyOk = false
-    const e = err as { stdout?: string; stderr?: string; message?: string }
-    applyOut = [e.stdout, e.stderr, e.message].filter(Boolean).join('\n').trim()
-  }
+  const { ok: applyOk, out: applyOut } = runEvalCaseApply(parsed.id)
 
   const footer = applyOk
     ? '✅ <i>Added as a regression test.</i>'
@@ -1421,9 +1474,28 @@ async function handleEvalCaseProposalCallback(ctx: Context, data: string): Promi
       )
       .catch(() => {})
   }
+  // Tell the agent the OUTCOME, not just that a tap happened — applied and
+  // apply-failed are different instructions (resume vs. don't assume it exists).
+  const outcomeInbound = applyOk
+    ? buildEvalCaseAppliedInbound({
+        ctx: inboundCtx,
+        proposalId: proposal.id,
+        skillSlug: proposal.skill_slug,
+        heldOut: proposal.held_out,
+        operatorId: senderId,
+      })
+    : buildEvalCaseApplyFailedInbound({
+        ctx: inboundCtx,
+        proposalId: proposal.id,
+        skillSlug: proposal.skill_slug,
+        heldOut: proposal.held_out,
+        operatorId: senderId,
+        applyOut,
+      })
+  const delivered = deliverResumeSyntheticOrBuffer(agent, outcomeInbound)
   process.stderr.write(
     `telegram gateway: eval_case_apply agent=${agent} proposal=${proposal.id} ` +
-    `slug=${proposal.skill_slug} ok=${applyOk}\n`,
+    `slug=${proposal.skill_slug} ok=${applyOk} delivered=${delivered}\n`,
   )
 }
 

package/telegram-plugin/gateway/eval-case-proposal-inbound-builders.ts

@@ -0,0 +1,197 @@
+/**
+ * Pure builders for the synthetic inbounds the gateway injects after the
+ * operator taps Approve / Dismiss on a self-improve EVAL-CASE proposal card
+ * (RFC amendment §"corrections as eval cases"). Mirrors
+ * `mental-model-propose-inbound-builders.ts`.
+ *
+ * WHY THIS MODULE EXISTS AT ALL: `handleEvalCaseProposalCallback` was a copy of
+ * `handleSkillProposalCallback` that dropped the
+ * `deliverResumeSyntheticOrBuffer` line. Both of its exits — dismiss and
+ * approve — edited the card and returned, so the PROPOSING AGENT was never
+ * told the outcome. It had been steered to end its turn cleanly and wait for a
+ * wake-up that no code path ever sent: every candidate second delivery path is
+ * empty (the self-improve Stop hook reads eval integrity baselines, not
+ * proposal status; `switchroom self-improve eval-case propose` is
+ * fire-and-forget and returns `ok:true` for POSTING THE CARD, never for the
+ * outcome). These three builders are the inbound half of that fix.
+ *
+ * The shape is load-bearing — `meta.source` is what the bridge keys on to
+ * render `<channel source="eval_case_applied">` / `eval_case_rejected` /
+ * `eval_case_apply_failed` blocks, and the
+ * `meta.{agent,proposal_id,skill_slug,held_out,operator_id}` fields are the
+ * forensic anchor tying the woken turn back to the exact proposal and the
+ * operator who decided it.
+ *
+ * A regression that drops a meta field or changes the source string would
+ * silently break the agent's wake-up: the bridge would route it as a generic
+ * channel event, the model wouldn't know its proposal resolved, and the
+ * conversation would drift back to the silent-block this module fixes. Pinning
+ * these against fixture tests is cheaper than catching that downstream.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+/** Subset of the stored proposal the builders need. Kept narrow so callers
+ *  don't have to pass the full `EvalCaseProposal` record. */
+export interface EvalCaseProposalInboundContext {
+  agent: string
+  /** Telegram chat id where the approval card lived. Used as the inbound's
+   *  chatId so the synthesized turn stays associated with the originating
+   *  conversation. */
+  chat_id: string
+  /** Supergroup forum topic (message_thread_id) the agent was working in when
+   *  it proposed — so the resumed turn's reply lands back in that topic, not
+   *  General. Undefined for DM / non-topic proposals. */
+  threadId?: number
+}
+
+/** The meta every eval-case outcome inbound carries, minus `source`. */
+function commonMeta(opts: {
+  ctx: EvalCaseProposalInboundContext
+  proposalId: string
+  skillSlug: string
+  heldOut: boolean
+  operatorId: string
+}): Record<string, string> {
+  return {
+    agent: opts.ctx.agent,
+    ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
+    proposal_id: opts.proposalId,
+    skill_slug: opts.skillSlug,
+    held_out: String(opts.heldOut),
+    operator_id: opts.operatorId,
+  }
+}
+
+/**
+ * Build the synthetic InboundMessage for an approval whose DETERMINISTIC
+ * applier succeeded — the case is now on disk (in the skill's `evals.json`, or
+ * the held-out sink when `heldOut`). Nothing is left for the agent to write.
+ */
+export function buildEvalCaseAppliedInbound(opts: {
+  ctx: EvalCaseProposalInboundContext
+  proposalId: string
+  skillSlug: string
+  heldOut: boolean
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  const sink = opts.heldOut ? 'the held-out sink' : `\`${opts.skillSlug}\`'s \`evals.json\``
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts, // synthetic — no Telegram message id exists
+    user: 'self-improve',
+    userId: 0,
+    ts,
+    text:
+      `✅ Operator approved your proposed eval case for \`${opts.skillSlug}\` ` +
+      `(proposal ${opts.proposalId}). The case was applied DETERMINISTICALLY by ` +
+      `the gateway and is already written to ${sink} — do NOT write it yourself ` +
+      `and do NOT re-propose it. Resume whatever you were doing.`,
+    meta: {
+      source: 'eval_case_applied',
+      ...commonMeta({
+        ctx: opts.ctx,
+        proposalId: opts.proposalId,
+        skillSlug: opts.skillSlug,
+        heldOut: opts.heldOut,
+        operatorId: opts.operatorId,
+      }),
+    },
+  }
+}
+
+/**
+ * Build the synthetic InboundMessage for an operator dismissal. NOTHING was
+ * written. Steers the agent onward rather than into a re-propose loop.
+ *
+ * This has no sibling in the skill-proposal handler (which stays silent on
+ * dismiss). Silence is the defect being fixed: a dismissed proposal left the
+ * agent waiting on a wake-up that never came.
+ */
+export function buildEvalCaseRejectedInbound(opts: {
+  ctx: EvalCaseProposalInboundContext
+  proposalId: string
+  skillSlug: string
+  heldOut: boolean
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts,
+    user: 'self-improve',
+    userId: 0,
+    ts,
+    text:
+      `🚫 Operator dismissed your proposed eval case for \`${opts.skillSlug}\` ` +
+      `(proposal ${opts.proposalId}). NOTHING was written — no eval case was ` +
+      `added. Carry on with the original task without it. Do NOT re-propose the ` +
+      `same case without first asking the user.`,
+    meta: {
+      source: 'eval_case_rejected',
+      ...commonMeta({
+        ctx: opts.ctx,
+        proposalId: opts.proposalId,
+        skillSlug: opts.skillSlug,
+        heldOut: opts.heldOut,
+        operatorId: opts.operatorId,
+      }),
+    },
+  }
+}
+
+/**
+ * Build the synthetic InboundMessage for an approval whose applier FAILED
+ * (`switchroom self-improve apply-eval-case` non-zero, timeout, missing skill
+ * dir, a stale/rejected proposal the applier's own status check refused).
+ * The operator tapped Approve but the case did NOT land — be honest so the
+ * agent doesn't assume the regression test exists.
+ *
+ * `applyOut` is the applier's combined stdout/stderr tail, truncated so a
+ * runaway stack trace can't dominate the woken turn's context.
+ */
+export function buildEvalCaseApplyFailedInbound(opts: {
+  ctx: EvalCaseProposalInboundContext
+  proposalId: string
+  skillSlug: string
+  heldOut: boolean
+  operatorId: string
+  applyOut: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  const tail = opts.applyOut.trim().slice(0, 500)
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts,
+    user: 'self-improve',
+    userId: 0,
+    ts,
+    text:
+      `⚠️ The operator approved your proposed eval case for \`${opts.skillSlug}\` ` +
+      `(proposal ${opts.proposalId}) but the applier FAILED. The case was NOT ` +
+      `written — do NOT assume the regression test exists. Applier output:\n` +
+      `${tail.length > 0 ? tail : '(no output)'}\n` +
+      `Carry on with the original task; report the failure to the operator if it ` +
+      `still matters.`,
+    meta: {
+      source: 'eval_case_apply_failed',
+      ...commonMeta({
+        ctx: opts.ctx,
+        proposalId: opts.proposalId,
+        skillSlug: opts.skillSlug,
+        heldOut: opts.heldOut,
+        operatorId: opts.operatorId,
+      }),
+    },
+  }
+}