switchroom 0.21.7 → 0.21.8

package/telegram-plugin/gateway/self-improve-proposal-wiring.ts

@@ -21,20 +21,86 @@
 
 import type { Bot, Context } from 'grammy'
 import type { RetryCallOpts } from '../retry-api-call.js'
-import type { PostSkillProposalMessage, PostEvalCaseProposalMessage } from './ipc-protocol.js'
+import type { PostSkillProposalMessage, PostEvalCaseProposalMessage, InboundMessage } from './ipc-protocol.js'
 import { renderSkillProposalCard, skillProposalKeyboard } from './skill-proposal-card.js'
 import { renderEvalCaseProposalCard, evalCaseProposalKeyboard } from './eval-case-proposal-card.js'
 import {
   enqueueProposal as enqueueSkillProposal,
   isSuppressed as isSkillProposalSuppressed,
+  REJECTION_TTL_MS,
 } from '../../src/self-improve/skill-proposals.js'
-import { enqueueEvalCaseProposal } from '../../src/self-improve/eval-case-proposals.js'
+import {
+  enqueueEvalCaseProposal,
+  readEvalCaseProposals,
+} from '../../src/self-improve/eval-case-proposals.js'
 
 /** Collaborators the gateway injects into each handler. */
 export interface ProposalWiringDeps {
   bot: Bot<Context>
   assertAllowedChat: (chatId: string) => void
   swallowingApiCall: <T>(fn: () => Promise<T>, opts?: RetryCallOpts) => Promise<T | undefined>
+  /**
+   * Wake the proposing agent with a synthetic inbound (gateway.ts's
+   * `deliverResumeSyntheticOrBuffer`). REQUIRED, not optional: the suppressed
+   * branch below is a silent exit, and a call site that forgot to wire this
+   * would reinstate exactly the wait-forever bug it exists to prevent — so the
+   * type system forces every caller to supply it.
+   */
+  deliverResumeSyntheticOrBuffer: (agent: string, inbound: InboundMessage) => boolean
+}
+
+/**
+ * Build the synthetic inbound that tells a proposing agent its eval case was
+ * SUPPRESSED as a duplicate of one the operator already dismissed.
+ *
+ * WHY THIS EXISTS (cross-PR, #4662 + #4664). #4662 makes the agent's contract
+ * "fire `add-eval-case`, end your turn, wait for the outcome inbound". #4664
+ * adds a branch that posts NO card. The propose CLI is fire-and-forget — it
+ * prints `ok:true` for the IPC SEND, never for a card being posted
+ * (src/cli/self-improve-eval-case.ts) — so without this the agent would end its
+ * turn and wait for a tap that can never come: the exact silent block #4662
+ * exists to eliminate, re-entering through a new door.
+ *
+ * The tone is deliberate. Suppression is the system working as designed, not a
+ * failure, so the text says so plainly — an agent told only "no card" would
+ * reasonably retry, which is the nagging loop #4664 is removing.
+ *
+ * Co-located here rather than in #4662's `eval-case-proposal-inbound-builders.ts`
+ * because that module does not exist on this branch; consolidating the four
+ * builders once both PRs land is a tracked follow-up.
+ */
+export function buildEvalCaseSuppressedInbound(opts: {
+  agent: string
+  chatId: string
+  threadId?: number
+  skillSlug: string
+  fingerprint: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return {
+    type: 'inbound',
+    chatId: opts.chatId,
+    ...(opts.threadId != null ? { threadId: opts.threadId } : {}),
+    messageId: ts, // synthetic — no Telegram message id exists
+    user: 'self-improve',
+    userId: 0,
+    ts,
+    text:
+      `ℹ️ Your proposed eval case for \`${opts.skillSlug}\` was NOT posted as a ` +
+      `card: the operator already dismissed this exact case, and the dismissal ` +
+      `is still in effect. This is EXPECTED and is not an error or a failure on ` +
+      `your part — nothing was written and no card is pending, so do NOT wait ` +
+      `for an approval tap. Do NOT re-propose this case. Carry on with the ` +
+      `original task without it.`,
+    meta: {
+      source: 'eval_case_suppressed',
+      agent: opts.agent,
+      ...(opts.threadId != null ? { message_thread_id: String(opts.threadId) } : {}),
+      skill_slug: opts.skillSlug,
+      fingerprint: opts.fingerprint,
+    },
+  }
 }
 
 /**
@@ -113,6 +179,61 @@ export function handlePostSkillProposal(
   )
 }
 
+/**
+ * True iff the operator already DISMISSED this exact eval case within the
+ * rejection TTL — the eval-case twin of `isSuppressed` in skill-proposals.ts.
+ *
+ * Matching is deliberately TIGHTER than the skill path's. A skill proposal is
+ * free prose, so that check has to fuzzy-match (jaccard over content words,
+ * with the slug only relaxing the threshold). An eval case carries a
+ * precomputed `fingerprint` — `caseFingerprint(prompt)`, a hash of the
+ * normalized prompt — and the CLI's own dedup against a skill's applied
+ * evals.json compares those fingerprints EXACTLY
+ * (src/cli/self-improve-eval-case.ts). So this requires exact fingerprint
+ * equality AND same-slug, matching the CLI's per-skill dedup scope: no fuzzy
+ * bar to tune, and a different PROMPT can never be swallowed.
+ *
+ * KNOWN CONSEQUENCE — identity is the PROMPT, not the whole case.
+ * `caseFingerprint` hashes the normalized prompt ONLY; an `EvalCase` also
+ * carries `expected_output` and `expectations` (src/self-improve/eval-cases.ts),
+ * and neither is in the hash. So re-proposing the SAME prompt with a CORRECTED
+ * expected_output/expectations fingerprints identically to the dismissed one and
+ * stays suppressed for the full TTL. This is deliberate, not an oversight: it is
+ * the same identity the CLI's own evals.json dedup uses, so a looser rule here
+ * would disagree with the applier and re-admit cases the CLI would then reject.
+ * To land a revised assertion for an already-dismissed prompt, reword the prompt
+ * (a genuinely different input) or wait out REJECTION_TTL_MS.
+ *
+ * The TTL semantics ARE mirrored (a dismissal shouldn't suppress forever), on
+ * the same REJECTION_TTL_MS window. The eval-case store records no
+ * `rejected_at`, so age is measured from `created_at`, which is always <= the
+ * rejection time — the window therefore expires no LATER than a true
+ * rejected_at basis would, erring towards re-surfacing rather than
+ * over-suppressing. A record with an unparseable timestamp is treated as
+ * expired, same as the skill path.
+ */
+export function isEvalCaseProposalSuppressed(
+  stateDir: string,
+  candidate: { skillSlug: string; fingerprint: string },
+  opts: { now?: () => number; ttlMs?: number } = {},
+): boolean {
+  // A missing/empty fingerprint carries no identity — never suppress on it.
+  if (typeof candidate.fingerprint !== 'string' || candidate.fingerprint.length === 0) {
+    return false
+  }
+  const now = (opts.now ?? Date.now)()
+  const ttl = opts.ttlMs ?? REJECTION_TTL_MS
+  for (const p of readEvalCaseProposals(stateDir)) {
+    if (p.status !== 'rejected') continue
+    if (p.skill_slug !== candidate.skillSlug) continue
+    if (p.fingerprint !== candidate.fingerprint) continue
+    const age = now - new Date(p.created_at).getTime()
+    if (!Number.isFinite(age) || age > ttl) continue // expired
+    return true
+  }
+  return false
+}
+
 /**
  * RFC amendment §"corrections as eval cases" — persist an eval-case proposal
  * and post its Approve/Dismiss card. On Approve the callback runs the
@@ -124,7 +245,7 @@ export function handlePostEvalCaseProposal(
   msg: PostEvalCaseProposalMessage,
   deps: ProposalWiringDeps,
 ): void {
-  const { bot, assertAllowedChat, swallowingApiCall } = deps
+  const { bot, assertAllowedChat, swallowingApiCall, deliverResumeSyntheticOrBuffer } = deps
   const self = process.env.SWITCHROOM_AGENT_NAME
   if (self && msg.agentName !== self) {
     process.stderr.write(
@@ -145,6 +266,34 @@ export function handlePostEvalCaseProposal(
     process.stderr.write(`telegram gateway: post_eval_case_proposal: TELEGRAM_STATE_DIR unset, skipping\n`)
     return
   }
+  // Dedup against still-live dismissals — never re-surface an eval case the
+  // operator already tapped Dismiss on (the skill path's guard, which the
+  // eval-case path was missing: a dismissed case re-posted the same card on
+  // every subsequent correction, since the CLI only dedups against evals.json
+  // entries that were already APPLIED).
+  if (isEvalCaseProposalSuppressed(stateDir, {
+    skillSlug: msg.skillSlug,
+    fingerprint: msg.fingerprint,
+  })) {
+    // Tell the agent, or this becomes a silent exit it waits on forever (see
+    // buildEvalCaseSuppressedInbound). No card is posted and nothing is written
+    // — the operator's dismissal already decided this case.
+    const delivered = deliverResumeSyntheticOrBuffer(
+      msg.agentName,
+      buildEvalCaseSuppressedInbound({
+        agent: msg.agentName,
+        chatId: msg.chatId,
+        ...(msg.threadId != null ? { threadId: msg.threadId } : {}),
+        skillSlug: msg.skillSlug,
+        fingerprint: msg.fingerprint,
+      }),
+    )
+    process.stderr.write(
+      `telegram gateway: post_eval_case_proposal suppressed (dismissed before) ` +
+      `slug=${msg.skillSlug} fp=${msg.fingerprint} delivered=${delivered}\n`,
+    )
+    return
+  }
   const proposal = enqueueEvalCaseProposal(stateDir, {
     skill_slug: msg.skillSlug,
     skill_dir: msg.skillDir,

package/telegram-plugin/gateway/subagent-handback-marker.ts

@@ -176,6 +176,25 @@ export const INBOUND_SOURCE_CLASSIFICATION: Record<string, { decoupledCompletion
   mental_model_proposal_failed: { decoupledCompletion: false },
   webhook: { decoupledCompletion: false },
   linear: { decoupledCompletion: false },
+  // Eval-case proposal outcomes (#4662) — the operator's Approve/Dismiss tap on
+  // an eval-case card wakes the PROPOSING agent with one of these, built in
+  // `eval-case-proposal-inbound-builders.ts` and injected via
+  // `deliverResumeSyntheticOrBuffer`. Exactly the `skill_proposal_apply` shape
+  // above: each lands as its OWN live inbound turn, so its reply resolves the
+  // live tier for its own turnId and structurally cannot supersede a different
+  // ended turn — it must NOT stamp. (Left unclassified, the fail-safe default
+  // stamps, holding the content gate chat-wide for 60 s after every eval-case
+  // decision and re-opening the reworded-own-answer visible dup in that window.)
+  eval_case_applied: { decoupledCompletion: false },
+  eval_case_rejected: { decoupledCompletion: false },
+  eval_case_apply_failed: { decoupledCompletion: false },
+  // Eval-case proposal SUPPRESSED (#4664): the gateway declined to post a card
+  // because the operator already dismissed this exact case, and tells the
+  // proposing agent so instead of exiting silently
+  // (buildEvalCaseSuppressedInbound, self-improve-proposal-wiring.ts). Delivered
+  // via `deliverResumeSyntheticOrBuffer` as its OWN live inbound turn, same as
+  // skill_proposal_apply above — it must NOT stamp.
+  eval_case_suppressed: { decoupledCompletion: false },
   // Buzz co-channel (Phase 1): a Nostr kind:9 group message the buzz sidecar
   // injects onto the gateway IPC queue as its OWN live inbound turn (anonymous
   // inject, `meta.source="buzz"`) — never a decoupled completion resolving a

package/telegram-plugin/tests/agent-process-liveness.test.ts

@@ -0,0 +1,406 @@
+/**
+ * switchroom#4641 — the boot-resume generation guard.
+ *
+ * Two mechanisms, tested for what each is actually responsible for:
+ *
+ *   - the per-container-boot GENERATION TOKEN (`.boot-resume-done`) is the
+ *     only thing that can say "suppress". start.sh deletes it once per
+ *     container boot before forking the gateway; the gateway stamps it after
+ *     completing its boot-resume block.
+ *   - the `/proc` AGENT RECORD is a VETO only: it can re-enable a boot resume
+ *     when the recorded agent is provably gone, never suppress one.
+ *
+ * Liveness assertions use REAL processes and the REAL `/proc`, not a mocked
+ * fs: a fixture that hand-writes both answers would pass against a probe that
+ * always says "alive". Every "alive" claim is anchored on a process this test
+ * spawned; every "dead" claim on one it killed.
+ *
+ * Deliberately NOT tested here, because it no longer exists: any comparison of
+ * the agent's `/proc` starttime against the gateway's. The previous revision
+ * suppressed on "the agent predates me", which was correct only by accident of
+ * the docker tmux re-exec (measured margin on a live container: one clock
+ * tick) and which broke outright when a gateway crashed during its own boot.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  parseProcStat,
+  readProcIdentity,
+  readAgentProcessRecord,
+  decideGatewayOnlyRespawn,
+  detectGatewayOnlyRespawn,
+  shouldSkipBootResumeForGatewayOnlyRespawn,
+  markBootResumeComplete,
+  bootResumeDonePath,
+  readBootResumeSentinel,
+  containerBootIdentity,
+  AGENT_PROCESS_RECORD_FILE,
+  BOOT_RESUME_DONE_FILE,
+} from '../gateway/agent-process-liveness.js'
+
+function starttimeOf(pid: number): string {
+  const id = readProcIdentity(pid)
+  expect(id, `pid ${pid} should be live`).not.toBeNull()
+  return id!.starttime
+}
+
+function spawnSleeper(): ChildProcess {
+  return spawn('sleep', ['120'], { stdio: 'ignore' })
+}
+
+async function waitForExit(child: ChildProcess): Promise<void> {
+  if (child.exitCode != null || child.signalCode != null) return
+  await new Promise<void>((res) => child.once('exit', () => res()))
+}
+
+let dir: string
+let agentProc: ChildProcess
+
+beforeAll(async () => {
+  dir = mkdtempSync(join(tmpdir(), 'agent-liveness-'))
+  agentProc = spawnSleeper()
+  await new Promise((r) => setTimeout(r, 20))
+})
+
+afterAll(() => {
+  try { agentProc.kill('SIGKILL') } catch { /* already gone */ }
+  rmSync(dir, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+  // Every case states its own generation-token state explicitly.
+  try { unlinkSync(bootResumeDonePath(dir)) } catch { /* absent */ }
+  try { unlinkSync(join(dir, AGENT_PROCESS_RECORD_FILE)) } catch { /* absent */ }
+})
+
+/** start.sh's outer-pass "open a new generation" step. */
+function clearToken(): void {
+  try { unlinkSync(bootResumeDonePath(dir)) } catch { /* absent */ }
+}
+
+function writeRecord(rec: unknown, name = AGENT_PROCESS_RECORD_FILE): string {
+  const p = join(dir, name)
+  writeFileSync(p, typeof rec === 'string' ? rec : JSON.stringify(rec))
+  return p
+}
+
+describe('parseProcStat', () => {
+  it('reads state + starttime past a comm containing spaces and parens', () => {
+    // A real-shaped line with a hostile comm — the naive `awk $22` split and a
+    // first-`)` split both return the wrong field here.
+    const raw =
+      '4242 (weird ) name) S 1 4242 4242 0 -1 4194304 167 0 0 0 0 0 0 0 20 0 1 0 ' +
+      '987654321 4165632 702 18446744073709551615 0 0 0 0 0 0 2 4 65536 1 0 0 17 0 0 0 0 0 0'
+    expect(parseProcStat(raw)).toEqual({
+      comm: 'weird ) name',
+      state: 'S',
+      starttime: '987654321',
+    })
+  })
+
+  it('agrees with awk on this process\'s own /proc entry', () => {
+    const raw = readFileSync(`/proc/${process.pid}/stat`, 'utf8')
+    const fields = raw.slice(raw.lastIndexOf(') ') + 2).trim().split(/\s+/)
+    expect(parseProcStat(raw)!.starttime).toBe(fields[19])
+  })
+
+  it('treats a zombie as dead', () => {
+    const raw = '4242 (claude) Z 1 4242 4242 0 -1 0 0 0 0 0 0 0 0 20 0 1 0 5 ' +
+      '0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0'
+    expect(parseProcStat(raw)!.state).toBe('Z')
+  })
+})
+
+describe('the generation token decides', () => {
+  it('suppresses ONLY after a gateway stamped the token this generation', () => {
+    writeRecord({ pid: agentProc.pid, starttime: starttimeOf(agentProc.pid!) })
+
+    // Fresh container boot: start.sh cleared the token, no gateway has
+    // finished its boot resume yet. The live agent record must NOT suppress.
+    expect(detectGatewayOnlyRespawn({ stateDir: dir })).toEqual({
+      gatewayOnly: false,
+      reason: 'no-boot-resume-sentinel',
+      pid: agentProc.pid,
+    })
+
+    // …the first gateway completes its boot-resume block…
+    markBootResumeComplete(dir)
+    expect(existsSync(bootResumeDonePath(dir))).toBe(true)
+
+    // …and a respawned gateway now sees the generation already handled.
+    expect(detectGatewayOnlyRespawn({ stateDir: dir })).toEqual({
+      gatewayOnly: true,
+      reason: 'gateway-only-respawn',
+      pid: agentProc.pid,
+    })
+  })
+
+  it('does NOT suppress when the gateway crashed during its own boot', () => {
+    // The #4641-motivating Bun crash-at-boot pattern: gateway #1 died before
+    // finishing the boot-resume block, so it never stamped the token — even
+    // though start.sh had already published a live agent record. Gateway #2
+    // MUST do the boot resume; the previous starttime-ordering guard
+    // suppressed here and lost the interrupted turn permanently.
+    writeRecord({ pid: agentProc.pid, starttime: starttimeOf(agentProc.pid!) })
+    const decision = detectGatewayOnlyRespawn({ stateDir: dir })
+    expect(decision.gatewayOnly).toBe(false)
+    expect(decision.reason).toBe('no-boot-resume-sentinel')
+  })
+
+  it('suppresses on a token with no record yet (gateway respawn pre-exec)', () => {
+    // The gateway boots long before start.sh reaches `exec claude`. A gateway
+    // that crashes in that window must still not repeat this generation's
+    // boot resume — repeating it would spool the resume synthetic twice.
+    markBootResumeComplete(dir)
+    expect(detectGatewayOnlyRespawn({ stateDir: dir })).toEqual({
+      gatewayOnly: true,
+      reason: 'gateway-only-respawn-no-record',
+      pid: null,
+    })
+  })
+
+  it('a container restart re-opens the generation (start.sh clears the token)', () => {
+    writeRecord({ pid: agentProc.pid, starttime: starttimeOf(agentProc.pid!) })
+    markBootResumeComplete(dir)
+    expect(detectGatewayOnlyRespawn({ stateDir: dir }).gatewayOnly).toBe(true)
+    clearToken()
+    expect(detectGatewayOnlyRespawn({ stateDir: dir }).gatewayOnly).toBe(false)
+  })
+})
+
+describe('the /proc record can only VETO a suppression', () => {
+  it('vetoes when the recorded agent process is really dead', async () => {
+    const doomed = spawnSleeper()
+    await new Promise((r) => setTimeout(r, 20))
+    writeRecord({ pid: doomed.pid, starttime: starttimeOf(doomed.pid!) })
+    doomed.kill('SIGKILL')
+    await waitForExit(doomed)
+    markBootResumeComplete(dir)
+
+    const decision = detectGatewayOnlyRespawn({ stateDir: dir })
+    expect(decision.gatewayOnly).toBe(false)
+    expect(decision.reason).toBe('agent-process-dead')
+  })
+
+  it('vetoes a recycled PID: same pid, different starttime', () => {
+    const live = starttimeOf(agentProc.pid!)
+    writeRecord({ pid: agentProc.pid, starttime: String(BigInt(live) - 1n) })
+    markBootResumeComplete(dir)
+    expect(detectGatewayOnlyRespawn({ stateDir: dir })).toEqual({
+      gatewayOnly: false,
+      reason: 'starttime-mismatch',
+      pid: agentProc.pid,
+    })
+  })
+
+  it('cannot manufacture a suppression on its own', () => {
+    // A live, matching, older record with NO token still runs the boot resume.
+    writeRecord({ pid: agentProc.pid, starttime: starttimeOf(agentProc.pid!) })
+    expect(detectGatewayOnlyRespawn({ stateDir: dir }).gatewayOnly).toBe(false)
+  })
+
+  it('fails open on a torn record even with the token present', () => {
+    markBootResumeComplete(dir)
+    writeRecord('{"pid": 12')
+    // Torn record is indistinguishable from "no record" — and with the token
+    // present that is a suppression, which is the safe answer here: the block
+    // demonstrably already ran this generation.
+    expect(detectGatewayOnlyRespawn({ stateDir: dir }).reason)
+      .toBe('gateway-only-respawn-no-record')
+  })
+
+  it('honours the SWITCHROOM_GATEWAY_RESPAWN_GUARD=0 escape hatch', () => {
+    writeRecord({ pid: agentProc.pid, starttime: starttimeOf(agentProc.pid!) })
+    markBootResumeComplete(dir)
+    const lines: string[] = []
+    const prev = process.env.SWITCHROOM_GATEWAY_RESPAWN_GUARD
+    process.env.SWITCHROOM_GATEWAY_RESPAWN_GUARD = '0'
+    try {
+      expect(
+        shouldSkipBootResumeForGatewayOnlyRespawn(dir, { log: (s) => lines.push(s) }),
+      ).toBe(false)
+    } finally {
+      if (prev == null) delete process.env.SWITCHROOM_GATEWAY_RESPAWN_GUARD
+      else process.env.SWITCHROOM_GATEWAY_RESPAWN_GUARD = prev
+    }
+    expect(lines.join('')).toContain('guard-disabled')
+  })
+
+  it('skips the boot-resume path (and says so) for a live agent + token', () => {
+    writeRecord({ pid: agentProc.pid, starttime: starttimeOf(agentProc.pid!) })
+    markBootResumeComplete(dir)
+    const lines: string[] = []
+    expect(shouldSkipBootResumeForGatewayOnlyRespawn(dir, { log: (s) => lines.push(s) })).toBe(true)
+    const out = lines.join('')
+    expect(out).toContain('GATEWAY-ONLY respawn')
+    // The log must name the side effects the break skips (the MEDIUM finding:
+    // it skips more than the resume synthetic).
+    expect(out).toContain('bridge-dead marker')
+    expect(out).toContain('crash-redelivery')
+  })
+})
+
+describe('markBootResumeComplete', () => {
+  it('writes the token atomically and leaves no tmp file behind', () => {
+    markBootResumeComplete(dir)
+    const p = bootResumeDonePath(dir)
+    expect(p.endsWith(BOOT_RESUME_DONE_FILE)).toBe(true)
+    expect(JSON.parse(readFileSync(p, 'utf8'))).toMatchObject({ pid: process.pid })
+    expect(existsSync(`${p}.tmp.${process.pid}`)).toBe(false)
+  })
+
+  it('never throws when the state dir is unwritable — it logs and continues', () => {
+    const lines: string[] = []
+    expect(() =>
+      markBootResumeComplete(join(dir, 'no', 'such', 'dir'), { log: (s) => lines.push(s) }),
+    ).not.toThrow()
+    expect(lines.join('')).toContain(BOOT_RESUME_DONE_FILE)
+  })
+})
+
+describe('decideGatewayOnlyRespawn (pure)', () => {
+  const record = { pid: 42, starttime: '1000' }
+  const live = { starttime: '1000', comm: 'claude', state: 'S' }
+
+  it('rejects a comm mismatch when the record carries one', () => {
+    expect(
+      decideGatewayOnlyRespawn({
+        sentinelPresent: true,
+        record: { ...record, comm: 'claude' },
+        live: { ...live, comm: 'imposter' },
+      }),
+    ).toEqual({ gatewayOnly: false, reason: 'comm-mismatch', pid: 42 })
+  })
+
+  it('never suppresses without the generation token, whatever /proc says', () => {
+    for (const l of [live, null]) {
+      expect(decideGatewayOnlyRespawn({ sentinelPresent: false, record, live: l }).gatewayOnly)
+        .toBe(false)
+    }
+  })
+})
+
+describe('readAgentProcessRecord', () => {
+  it('accepts the exact shape start.sh writes', () => {
+    const p = writeRecord({ pid: 7, starttime: '213153204', boot_at: 1786572493000 })
+    expect(readAgentProcessRecord(p)).toEqual({
+      pid: 7,
+      starttime: '213153204',
+      boot_at: 1786572493000,
+    })
+  })
+
+  it('rejects a nonsense pid', () => {
+    expect(readAgentProcessRecord(writeRecord({ pid: 0, starttime: '5' }))).toBeNull()
+    expect(readAgentProcessRecord(writeRecord({ pid: -1, starttime: '5' }))).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// #4648 LOW-2: the token carries the container-boot identity
+// ---------------------------------------------------------------------------
+
+describe('generation-token boot identity', () => {
+  it('stamps the live container-boot identity (PID 1 starttime) into the token', () => {
+    markBootResumeComplete(dir)
+    const body = JSON.parse(readFileSync(bootResumeDonePath(dir), 'utf8')) as { boot?: string }
+    expect(body.boot).toBe(containerBootIdentity()!)
+  })
+
+  it('treats a token from a DIFFERENT container boot as stale, not as a suppressor', () => {
+    // The failure this closes: start.sh's `rm -f … 2>/dev/null || true` swallows
+    // a per-file unlink failure, so a token can outlive its generation and
+    // suppress EVERY later resume — permanently and silently, since
+    // `gateway-only-respawn-no-record` needs no corroborating evidence.
+    writeFileSync(
+      bootResumeDonePath(dir),
+      JSON.stringify({ pid: 4242, at: Date.now(), boot: '1' }) + '\n',
+    )
+    const decision = detectGatewayOnlyRespawn({ stateDir: dir })
+    expect(decision.gatewayOnly).toBe(false)
+    expect(decision.reason).toBe('stale-boot-token')
+  })
+
+  it('still suppresses for a token stamped in THIS boot, with no record present', () => {
+    // The `gateway-only-respawn-no-record` path must survive the hardening:
+    // the gateway boots long before start.sh `exec`s claude.
+    markBootResumeComplete(dir)
+    expect(existsSync(join(dir, AGENT_PROCESS_RECORD_FILE))).toBe(false)
+    const decision = detectGatewayOnlyRespawn({ stateDir: dir })
+    expect(decision.gatewayOnly).toBe(true)
+    expect(decision.reason).toBe('gateway-only-respawn-no-record')
+  })
+
+  it('keeps the pre-existing behaviour when the token carries NO identity', () => {
+    // One-directional by design: only a positive MISMATCH is evidence. A
+    // legacy/identity-less token must not become a fail-open path, or the
+    // hardening would itself re-open #4641.
+    writeFileSync(bootResumeDonePath(dir), JSON.stringify({ pid: 4242, at: Date.now() }) + '\n')
+    expect(readBootResumeSentinel(bootResumeDonePath(dir))).toEqual({ present: true, stale: false })
+    expect(detectGatewayOnlyRespawn({ stateDir: dir }).gatewayOnly).toBe(true)
+  })
+
+  it('keeps the pre-existing behaviour when the token body is unparseable', () => {
+    writeFileSync(bootResumeDonePath(dir), 'not json at all')
+    expect(readBootResumeSentinel(bootResumeDonePath(dir))).toEqual({ present: true, stale: false })
+  })
+
+  it('keeps the pre-existing behaviour when /proc/1 is unreadable', () => {
+    // No live identity to compare against → no evidence → not stale.
+    writeFileSync(
+      bootResumeDonePath(dir),
+      JSON.stringify({ pid: 4242, at: Date.now(), boot: '1' }) + '\n',
+    )
+    const emptyProc = mkdtempSync(join(tmpdir(), 'noproc-'))
+    try {
+      expect(containerBootIdentity(emptyProc)).toBeNull()
+      expect(readBootResumeSentinel(bootResumeDonePath(dir), { procRoot: emptyProc }))
+        .toEqual({ present: true, stale: false })
+    } finally {
+      rmSync(emptyProc, { recursive: true, force: true })
+    }
+  })
+
+  it('reports absent when there is no token at all', () => {
+    clearToken()
+    expect(readBootResumeSentinel(bootResumeDonePath(dir))).toEqual({ present: false, stale: false })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// #4648 LOW-1: no env var may redirect the token/record paths
+// ---------------------------------------------------------------------------
+
+describe('path overrides are test-injection only (fail-open invariant)', () => {
+  it('ignores SWITCHROOM_BOOT_RESUME_DONE_FILE / SWITCHROOM_AGENT_PROCESS_FILE', () => {
+    // If these were honoured, start.sh (which hard-codes
+    // "$TELEGRAM_STATE_DIR/.boot-resume-done") would clear one path while the
+    // gateway read another: the token would never be cleared and EVERY boot
+    // would suppress its resume forever — the module's one fail-CLOSED path.
+    const decoy = mkdtempSync(join(tmpdir(), 'decoy-'))
+    const prevToken = process.env.SWITCHROOM_BOOT_RESUME_DONE_FILE
+    const prevRecord = process.env.SWITCHROOM_AGENT_PROCESS_FILE
+    try {
+      process.env.SWITCHROOM_BOOT_RESUME_DONE_FILE = join(decoy, 'token')
+      process.env.SWITCHROOM_AGENT_PROCESS_FILE = join(decoy, 'record')
+      clearToken()
+      // A token written into the decoy path must NOT be seen…
+      writeFileSync(join(decoy, 'token'), JSON.stringify({ pid: 1, at: Date.now() }) + '\n')
+      expect(shouldSkipBootResumeForGatewayOnlyRespawn(dir, { log: () => {} })).toBe(false)
+      // …and the stamp must land in stateDir, not the decoy.
+      markBootResumeComplete(dir)
+      expect(existsSync(bootResumeDonePath(dir))).toBe(true)
+      expect(shouldSkipBootResumeForGatewayOnlyRespawn(dir, { log: () => {} })).toBe(true)
+    } finally {
+      if (prevToken == null) delete process.env.SWITCHROOM_BOOT_RESUME_DONE_FILE
+      else process.env.SWITCHROOM_BOOT_RESUME_DONE_FILE = prevToken
+      if (prevRecord == null) delete process.env.SWITCHROOM_AGENT_PROCESS_FILE
+      else process.env.SWITCHROOM_AGENT_PROCESS_FILE = prevRecord
+      rmSync(decoy, { recursive: true, force: true })
+    }
+  })
+})

package/telegram-plugin/tests/approval-hold-record.test.ts

@@ -128,17 +128,30 @@ describe('blocked-approval record — the off-Telegram surface', () => {
   // meant the whole feature was a silent no-op in production.
   it('falls back to the agent\'s own state dir when the shared dir is not writable', () => {
     // Simulate the production failure: Docker auto-created the bind source as
-    // root:root, so this agent's uid can neither create the dir nor chmod it.
-    // Modelled as a read-only PARENT — the store can't mkdir the shared dir
-    // inside it, and can't chmod its way out either.
-    const readOnlyParent = join(root, 'root-owned')
-    mkdirSync(readOnlyParent, { recursive: true })
-    chmodSync(readOnlyParent, 0o555) // r-xr-xr-x
-    const unwritable = join(readOnlyParent, 'blocked-approvals') // cannot be created
+    // root:root, so this agent's uid cannot write inside it.
+    //
+    // This used to be modelled as a read-only PARENT (`chmod 0555`). uid 0
+    // IGNORES file modes, so under root the shared write SUCCEEDED, the fallback
+    // branch was never taken, and this test went red for the wrong reason (the
+    // suite runs as root in the fleet's debug container). Inject the EACCES
+    // instead — deterministic for every uid, and every branch of the real
+    // `write()` still runs.
+    const unwritable = join(root, 'root-owned', 'blocked-approvals')
     const ownDir = join(root, 'agent-state')
     mkdirSync(ownDir, { recursive: true })
 
-    const store = createBlockedApprovalStore(unwritable, 'overlord', ownDir)
+    const store = createBlockedApprovalStore(unwritable, 'overlord', ownDir, {
+      writeFileSync: ((file, data, opts) => {
+        if (String(file).startsWith(unwritable)) {
+          const e: NodeJS.ErrnoException = new Error(
+            `EACCES: permission denied, open '${String(file)}'`,
+          )
+          e.code = 'EACCES'
+          throw e
+        }
+        return writeFileSync(file, data, opts)
+      }) as typeof writeFileSync,
+    })
     store.write(REC)
 
     // The record MUST exist somewhere — never silently lost.