switchroom 0.18.12 → 0.18.13

package/telegram-plugin/tests/reaction-gate-routing.test.ts

@@ -0,0 +1,173 @@
+/**
+ * #3155 — `setMessageReaction` must route through the send gate + flood breaker.
+ *
+ * Before this change ~13 raw `bot.api.setMessageReaction(...)` /
+ * `lockedBot.api.setMessageReaction(...)` call sites (early-ack 👀, status
+ * reactions, stop/interrupt ⚡, permission verdict ✅/❌, refusal 🚫, ack-only,
+ * the MCP `react` tool, the crash-recovery sweeps, the auth-code 🔑 redact)
+ * fired reactions OUTSIDE both:
+ *
+ *   (a) the send gate — so reaction churn was never paced/shed under flood
+ *       pressure even with the gate ON; and
+ *   (b) the flood circuit breaker — a 429 from a reaction never reached the
+ *       retry module's `onFloodWait` hook, so the ban went unrecorded.
+ *
+ * Reactions were therefore a residual flood vector even when the gate is on.
+ * The gateway now funnels every reaction through ONE seam,
+ * `robustApiCall(() => lockedBot.api.setMessageReaction(...), { priorityClass:
+ * 'cosmetic', verb: 'set-message-reaction' })`.
+ *
+ * Two levels of coverage:
+ *   1. BEHAVIOURAL — compose the real `send-gate` + `retry-api-call` modules the
+ *      same way `gateway.ts` wires `robustApiCall`, and prove a cosmetic
+ *      reaction is (a) shed when a flood window is open and (b) visible to
+ *      `onFloodWait` on a 429.
+ *   2. LOAD-BEARING SOURCE SCAN — assert the gateway has exactly ONE runtime
+ *      `setMessageReaction` call and that it is the cosmetic seam. This FAILS if
+ *      any future change re-introduces a raw (ungated, breaker-blind) reaction.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { createSendGate, type Clock } from '../send-gate.js'
+import { createRetryApiCall } from '../retry-api-call.js'
+import { errors } from './fake-bot-api.js'
+
+const GATEWAY_SRC = fileURLToPath(new URL('../gateway/gateway.ts', import.meta.url))
+
+/** Fixed-time clock; `sleep` is a no-op so nothing actually waits under test. */
+function fixedClock(now: number): Clock {
+  return { now: () => now, sleep: () => Promise.resolve() }
+}
+
+/**
+ * Reconstruct the gateway's outbound wiring for reactions: `robustApiCall =
+ * gate(rawRetry)`, and a `sendReaction` closure that tags the call `cosmetic`
+ * exactly like `gatedSetMessageReaction` in gateway.ts.
+ */
+function wireReactionPath(opts: {
+  clock: Clock
+  enabled: boolean
+  windowUntilTs?: number
+  onFloodWait?: (retryAfterSec: number) => void
+}) {
+  const setMessageReaction = vi.fn(async () => true as const)
+  const sendGate = createSendGate({
+    enabled: opts.enabled,
+    clock: opts.clock,
+    ...(opts.windowUntilTs != null
+      ? { initialWindows: [{ scopeKey: 'global', untilTs: opts.windowUntilTs }] }
+      : {}),
+  })
+  const rawRetry = createRetryApiCall({
+    maxRetries: 2,
+    sleep: async () => {},
+    ...(opts.onFloodWait ? { onFloodWait: opts.onFloodWait } : {}),
+  })
+  const robustApiCall = <T>(
+    fn: () => Promise<T>,
+    o?: Parameters<typeof rawRetry<T>>[1],
+  ): Promise<T> => sendGate.gate(() => rawRetry(fn, o), o)
+
+  // Mirrors gateway.ts `gatedSetMessageReaction` / `sendReaction`.
+  const sendReaction = (chatId: string, messageId: number, emoji: string): Promise<unknown> =>
+    robustApiCall(() => setMessageReaction(chatId, messageId, [{ type: 'emoji', emoji }]), {
+      chat_id: chatId,
+      verb: 'set-message-reaction',
+      priorityClass: 'cosmetic',
+    })
+
+  return { sendReaction, setMessageReaction, sendGate }
+}
+
+describe('#3155 reactions route through the send gate (cosmetic)', () => {
+  it('SHEDS a reaction while a flood window is open (paced/shed by the gate)', async () => {
+    const now = 1_000_000
+    const { sendReaction, setMessageReaction, sendGate } = wireReactionPath({
+      clock: fixedClock(now),
+      enabled: true,
+      windowUntilTs: now + 60_000, // an open global ban window
+    })
+
+    const result = await sendReaction('chatA', 42, '👀')
+
+    // Cosmetic + a covering window ⇒ shed: the API is NEVER hit, the promise
+    // resolves undefined (fire-and-forget callers .catch nothing), and the gate
+    // counts the shed.
+    expect(setMessageReaction).not.toHaveBeenCalled()
+    expect(result).toBeUndefined()
+    expect(sendGate.stats().global.shed).toBe(1)
+  })
+
+  it('does NOT shed when the gate is OFF (proves the gate is what sheds)', async () => {
+    const now = 1_000_000
+    const { sendReaction, setMessageReaction } = wireReactionPath({
+      clock: fixedClock(now),
+      enabled: false, // gate disabled ⇒ pure passthrough
+      windowUntilTs: now + 60_000,
+    })
+
+    await sendReaction('chatA', 42, '👀')
+
+    // Flag OFF ⇒ the reaction still fires (the window only bites when enabled).
+    expect(setMessageReaction).toHaveBeenCalledTimes(1)
+  })
+
+  it('records a 429 on a reaction to the flood breaker via onFloodWait', async () => {
+    const now = 1_000_000
+    const onFloodWait = vi.fn()
+    const { sendReaction, setMessageReaction } = wireReactionPath({
+      clock: fixedClock(now),
+      enabled: true, // gate on, no open window ⇒ the cosmetic call is admitted
+      onFloodWait,
+    })
+    // The reaction send hits a Telegram 429 flood-wait.
+    setMessageReaction.mockRejectedValue(errors.floodWait(7, 'setMessageReaction'))
+
+    // Fire-and-forget semantics: callers swallow. The point is the SIDE EFFECT.
+    await sendReaction('chatA', 42, '🤝').catch(() => {})
+
+    // The reaction actually reached the API (was admitted, not shed)...
+    expect(setMessageReaction).toHaveBeenCalled()
+    // ...and its 429 was recorded by the breaker — the whole gap this closes.
+    expect(onFloodWait).toHaveBeenCalledWith(7)
+  })
+})
+
+describe('#3155 load-bearing: gateway.ts sends no reaction raw', () => {
+  const src = readFileSync(GATEWAY_SRC, 'utf-8')
+  const lines = src.split('\n')
+
+  /** Non-comment source lines that call `(bot|lockedBot).api.setMessageReaction`. */
+  const rawReactionLines = lines
+    .map((text, i) => ({ text, n: i + 1 }))
+    .filter(({ text }) => {
+      const t = text.trim()
+      if (t.startsWith('*') || t.startsWith('//') || t.startsWith('/*')) return false
+      return /\b(bot|lockedBot)\.api\.setMessageReaction\b/.test(text)
+    })
+
+  it('has EXACTLY ONE runtime setMessageReaction callsite (the shared seam)', () => {
+    // If this fails with >1, a raw reaction was re-introduced somewhere —
+    // ungated and invisible to the flood breaker. Route it through
+    // `sendReaction` / `gatedSetMessageReaction` instead.
+    expect(rawReactionLines).toHaveLength(1)
+  })
+
+  it('the sole seam is tagged cosmetic and routed through robustApiCall', () => {
+    const seamLine = rawReactionLines[0]!.n
+    // Look at the seam line + a small window for its opts object.
+    const window = lines.slice(seamLine - 2, seamLine + 6).join('\n')
+    expect(window).toContain('robustApiCall(')
+    expect(window).toContain("priorityClass: 'cosmetic'")
+    expect(window).toContain("verb: 'set-message-reaction'")
+  })
+
+  it('no reaction is fired as a raw fire-and-forget bot.api call', () => {
+    // Belt-and-braces: the old `bot.api.setMessageReaction(...).catch(() => {})`
+    // shape must be gone entirely.
+    expect(src).not.toMatch(/bot\.api\.setMessageReaction\([^)]*\)\s*\.catch/)
+    // And the fire-and-forget callers now go through the helper.
+    expect(src).toContain('void sendReaction(')
+  })
+})

package/telegram-plugin/tests/render/render.test.ts

@@ -48,6 +48,65 @@ describe("render: inline palette", () => {
       "[label](https://example.com)",
     );
   });
+  it("escapes a `)` in a link href so the URL is not truncated (F3)", () => {
+    // An angle-bracket destination is the only way to smuggle an UNBALANCED
+    // `)` into an href via the parser (a bare `)` would otherwise close the
+    // destination). CommonMark strips the angle brackets → href holds the `)`.
+    const doc = parse("[wiki](<https://example.com/a)b>)");
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://example.com/a)b"); // parser captured the full URL
+
+    const out = render(doc);
+    // The `)` is backslash-escaped so it can no longer terminate the `(...)`
+    // destination early — a valid Bot API 10.1 link, not a broken one.
+    expect(out).toContain("a\\)b");
+    // And it round-trips: re-parsing recovers the SAME href, not a truncated
+    // `https://example.com/a` with stray `b)` prose spilled after it.
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(reLink.href).toBe("https://example.com/a)b");
+  });
+  it("round-trips a balanced-paren href (Wikipedia disambiguation) without leaking a backslash", () => {
+    // A bare destination with BALANCED parens is legal CommonMark; the parser
+    // captures the whole URL including the inner `(...)`. Escaping only `)`
+    // (the old fix) would unbalance the parens and leak a literal backslash
+    // into the decoded href. Escaping both parens keeps it balanced.
+    const src = "[w](https://en.wikipedia.org/wiki/Foo_(disambiguation))";
+    const doc = parse(src);
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://en.wikipedia.org/wiki/Foo_(disambiguation)");
+
+    const out = render(doc);
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    // Re-parsed href is byte-for-byte the original — no truncation, no stray `\`.
+    expect(reLink.href).toBe("https://en.wikipedia.org/wiki/Foo_(disambiguation)");
+    expect(reLink.href).not.toContain("\\");
+  });
+  it("round-trips an href with multiple balanced paren groups", () => {
+    const src = "[m](https://example.com/a(b)c(d))";
+    const doc = parse(src);
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://example.com/a(b)c(d)");
+
+    const out = render(doc);
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(reLink.href).toBe("https://example.com/a(b)c(d)");
+    expect(reLink.href).not.toContain("\\");
+  });
+  it("round-trips an href with a lone unbalanced `)` without leaking a backslash", () => {
+    // Angle-bracket destination smuggles a lone `)` past the parser.
+    const doc = parse("[x](<https://example.com/a)b>)");
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://example.com/a)b");
+
+    const out = render(doc);
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(reLink.href).toBe("https://example.com/a)b");
+    expect(reLink.href).not.toContain("\\");
+  });
   it("underline", () => {
     expect(render(parse("__hi__"))).toBe("__hi__");
   });
@@ -226,6 +285,35 @@ describe("render: block palette", () => {
     const out = render(parse(md));
     expect(out).toContain("**bold** cell");
   });
+  it("neutralizes a `|` inside a code span in a table cell so the row survives (F4)", () => {
+    // Source pipe inside the code span is `\|`-escaped so the INPUT is a valid
+    // GFM table; the parser folds it to a code node whose text is `a|b`.
+    const md = ["| Col |", "| --- |", "| `a\\|b` |"].join("\n");
+    const doc = parse(md);
+    const srcCell = (doc.blocks[0] as TableNode).rows[0].cells[0].children.find(
+      (c: any) => c.type === "code",
+    ) as any;
+    expect(srcCell.text).toBe("a|b"); // parser captured the literal pipe
+
+    const out = render(doc);
+    // The `|` is re-escaped inside the code span so it can't be read as a
+    // column separator and tear the row — valid Bot API 10.1 GFM output.
+    expect(out).toContain("`a\\|b`");
+    // Every rendered table line stays a structurally-valid row (`|`-delimited,
+    // balanced) — a torn row would start with `|` but not end with one.
+    for (const line of out.split("\n")) {
+      if (line.trimStart().startsWith("|")) {
+        expect(line.trimEnd().endsWith("|")).toBe(true);
+      }
+    }
+    // And it round-trips: the re-parsed table still has ONE body cell whose
+    // code text is `a|b`, not a torn row with an unterminated code span.
+    const reparsed = parse(out);
+    const reRow = (reparsed.blocks[0] as TableNode).rows[0];
+    expect(reRow.cells).toHaveLength(1);
+    const reCell = reRow.cells[0].children.find((c: any) => c.type === "code") as any;
+    expect(reCell.text).toBe("a|b");
+  });
 });
 
 describe("render: full document", () => {

package/telegram-plugin/tests/scoped-approval.test.ts

@@ -270,6 +270,33 @@ describe('isDestructiveBashCommand — fail-closed denylist', () => {
     expect(timeBoxRule('Bash', bashInput('git status `rm -rf x`'))).toBeNull()
   })
 
+  it('flags destructive git checkout / stash forms that discard work (fail-closed)', () => {
+    for (const cmd of [
+      // checkout that discards uncommitted working-tree changes
+      'git checkout .', 'git checkout -f', 'git checkout -f main', 'git checkout --force',
+      'git checkout -- file.ts', 'git checkout HEAD -- .', 'git checkout HEAD~1 -- src/x.ts',
+      // `./` and `./<path>` are common spellings of `.` — same whole-tree /
+      // subtree discard; git refnames forbid a branch starting with `./`,
+      // so gating these carries no false-positive risk.
+      'git checkout ./', 'git checkout ./src',
+      // stash forms that irreversibly remove stash state
+      'git stash drop', 'git stash drop stash@{2}', 'git stash clear', 'git stash pop',
+    ]) {
+      expect(isDestructiveBashCommand(cmd), cmd).toBe(true)
+    }
+  })
+
+  it('does NOT flag safe git checkout / stash forms (no over-broadening)', () => {
+    for (const cmd of [
+      // branch switches / creation are reversible
+      'git checkout main', 'git checkout -b feature', 'git checkout feature.branch',
+      // stash inspection / non-removing forms keep the stash
+      'git stash', 'git stash list', 'git stash show', 'git stash apply',
+    ]) {
+      expect(isDestructiveBashCommand(cmd), cmd).toBe(false)
+    }
+  })
+
   it('does NOT flag ordinary safe commands', () => {
     for (const cmd of [
       'git status', 'git log --oneline -5', 'git diff', 'npm test', 'npm run build',

package/telegram-plugin/tests/secret-detect-chunk-overlap.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import { detectSecrets } from '../secret-detect/index.js'
+import { chunk, CHUNK_THRESHOLD, WINDOW_SIZE, OVERLAP } from '../secret-detect/chunker.js'
+
+/**
+ * OUTCOME test for tp-support F2 — the sliding-window overlap must exceed a
+ * real PEM private key so a boundary-straddling key in a >32 KB payload is
+ * still fully contained in (and therefore detected by) at least one window.
+ *
+ * The old 1 KB overlap was smaller than a 4096-bit RSA PEM (~3.2 KB), so a
+ * ~3.2 KB key straddling a 16 KB window boundary fell into the gap between
+ * consecutive windows and was scanned by NEITHER — it slipped past the
+ * scrubber unmasked. This pins the fix behaviorally: the key is detected.
+ *
+ * Proof-of-bite: reverting OVERLAP to 1024 (its pre-fix value) makes the
+ * boundary-straddling assertion below fail — the key lands in the gap.
+ */
+
+// A representative ~3.2 KB PEM private key (4096-bit RSA armor size). Body is
+// obviously-fake filler; only the BEGIN/END markers + non-empty body matter
+// for the `pem_private_key` regex. Assembled at runtime per CLAUDE.md.
+const PEM_BEGIN = '-----BEGIN RSA PRIVATE KEY-----'
+const PEM_END = '-----END RSA PRIVATE KEY-----'
+const PEM_BODY = 'A'.repeat(3100)
+const PEM = `${PEM_BEGIN}\n${PEM_BODY}\n${PEM_END}`
+
+describe('chunker overlap ≥ real PEM key size (tp-support F2)', () => {
+  it('overlap safely exceeds a 4096-bit RSA PEM (~3.2 KB)', () => {
+    // Guarantee: a secret is only missed if its length EXCEEDS OVERLAP.
+    expect(OVERLAP).toBeGreaterThanOrEqual(4 * 1024)
+    expect(PEM.length).toBeGreaterThan(1024) // the finding's ">1KB" threshold
+    expect(OVERLAP).toBeGreaterThan(PEM.length) // key fits inside the overlap
+  })
+
+  it('detects a >1KB PEM key straddling a window boundary in a >32KB payload', () => {
+    // Place the PEM so it straddles the first window boundary (16 KB): it
+    // starts before the boundary and ends after it. With the fixed 8 KB
+    // overlap the whole key sits inside the second window [8K, 24K]; with the
+    // old 1 KB overlap it fell into the gap between [0,16K] and [15.36K,31.74K].
+    const pemStart = WINDOW_SIZE - 1384 // 15000: before the 16384 boundary
+    const leading = 'a'.repeat(pemStart)
+    const trailing = 'a'.repeat(20000)
+    const text = leading + PEM + trailing
+
+    // Sanity: the payload is over the chunk threshold (so chunking is active)
+    // and the PEM genuinely straddles a real window boundary.
+    expect(text.length).toBeGreaterThan(CHUNK_THRESHOLD)
+    const windows = chunk(text)
+    expect(windows.length).toBeGreaterThan(1)
+    const pemEnd = pemStart + PEM.length
+    // Straddles the first boundary: starts before it, ends after it.
+    expect(pemStart).toBeLessThan(WINDOW_SIZE)
+    expect(pemEnd).toBeGreaterThan(WINDOW_SIZE)
+    // No single window before the fix (1 KB overlap) would have contained it,
+    // yet with the current overlap at least one window does.
+    const containing = windows.filter(
+      (w) => pemStart >= w.offset && pemEnd <= w.offset + w.text.length,
+    )
+    expect(containing.length).toBeGreaterThan(0)
+
+    // The actual outcome: the detector flags the straddling PEM.
+    const hits = detectSecrets(text)
+    expect(hits.some((h) => h.rule_id === 'pem_private_key')).toBe(true)
+  })
+})

package/telegram-plugin/tests/secret-detect-oauth-code.test.ts

@@ -210,10 +210,11 @@ describe('pendingReauthFlows intercept — deleteMessage sequencing (Blocker 1)'
     const window = src.slice(interceptIdx, interceptIdx + 2000)
     // Allow the optional 4th `log` argument added in #561 (diagnostic
     // sink for redaction failures) — required is the first three args.
-    // `bot.api` may be cast (e.g. `bot.api as never`) for the local
-    // BotApi-vs-grammy-Api type mismatch cleanup in #623; `msgId` may
-    // be narrowed (`msgId ?? null`).
-    expect(window).toMatch(/redactAuthCodeMessage\(bot\.api(?:\s+as\s+\w+)?,\s*chat_id,\s*msgId(?:\s*\?\?\s*null)?(?:,\s*[^)]+)?\)/)
+    // The first arg is the injected BotApi surface: historically `bot.api`
+    // (optionally cast, #623), now the gated `redactAuthCodeApi` adapter whose
+    // reaction routes through the send gate + flood breaker (#3155). `msgId`
+    // may be narrowed (`msgId ?? null`).
+    expect(window).toMatch(/redactAuthCodeMessage\((?:bot\.api|redactAuthCodeApi)(?:\s+as\s+\w+)?,\s*chat_id,\s*msgId(?:\s*\?\?\s*null)?(?:,\s*[^)]+)?\)/)
   })
 
   it('redaction lands AFTER the success/error reply renders', () => {

package/telegram-plugin/tests/session-tail-sidecar-reap.test.ts

@@ -0,0 +1,268 @@
+/**
+ * FD/timer-leak regression test for the session-tail PreToolUse sidecars
+ * (review finding M1).
+ *
+ * `ToolLabelSidecar`s (each holding a stat-poll timer + file handle) were only
+ * reaped in the global `stop()`. Every session rotation (`/clear`, compaction →
+ * new sessionId) and every finished sub-agent minted a fresh sidecar that then
+ * lived until process exit — hundreds of leaked timers/handles on a long-lived
+ * agent.
+ *
+ * We mock the sidecar factory so each instance is a cheap fake with a `stop`
+ * spy, then drive a real parent-session rotation and a real sub-agent reap and
+ * assert the ended session's sidecar was stopped. Both assertions FAIL on
+ * pre-fix code (stop only in `stop()`).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { startSessionTail, getProjectsDirForCwd } from '../session-tail.js'
+import type { SidecarOptions, ToolLabelSidecar } from '../tool-label-sidecar.js'
+
+// ─── Sidecar factory injection: record every fake instance keyed by sessionId ─
+// We do NOT `vi.mock('../tool-label-sidecar.js')`. Under bun's vitest-compat
+// layer `vi.mock` is PROCESS-GLOBAL (not file-scoped like vitest), and CI's
+// bun-test-run shard runs this whole `tests/` dir in ONE process — so a module
+// mock here would leak into the real `tool-label-sidecar.test.ts` suite and
+// replace the module under test, failing its 7 assertions. Instead we inject a
+// fake sidecar factory through `startSessionTail`'s `createSidecar` seam (the
+// repo's bun-safe DI precedent — see `vault-write-posture.test.ts`), so the
+// shared module cache is never touched. Sibling `subagent-watcher-fd-leak.test.ts`
+// uses the same injected-fake style.
+interface FakeSidecar extends ToolLabelSidecar {
+  sessionId: string
+  stop: ReturnType<typeof vi.fn>
+}
+const created = { instances: [] as FakeSidecar[] }
+const fakeSidecarFactory = (opts: SidecarOptions): ToolLabelSidecar => {
+  const inst: FakeSidecar = {
+    sessionId: opts.sessionId,
+    stop: vi.fn(),
+    getLabel: () => undefined,
+    onLabel: () => () => {},
+    poll: () => {},
+  }
+  created.instances.push(inst)
+  return inst
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const tempDirs: string[] = []
+let prevStateDir: string | undefined
+
+beforeEach(() => {
+  created.instances.length = 0
+  prevStateDir = process.env.TELEGRAM_STATE_DIR
+  const stateDir = mkdtempSync(join(tmpdir(), 'sidecar-state-'))
+  tempDirs.push(stateDir)
+  process.env.TELEGRAM_STATE_DIR = stateDir
+})
+
+afterEach(() => {
+  if (prevStateDir === undefined) delete process.env.TELEGRAM_STATE_DIR
+  else process.env.TELEGRAM_STATE_DIR = prevStateDir
+  for (const d of tempDirs) {
+    try { rmSync(d, { recursive: true, force: true }) } catch { /* ignore */ }
+  }
+  tempDirs.length = 0
+})
+
+function mkProjectsDir(): { claudeHome: string; cwd: string; projectsDir: string } {
+  const base = mkdtempSync(join(tmpdir(), 'session-tail-sidecar-'))
+  tempDirs.push(base)
+  const cwd = join(base, 'agent')
+  const claudeHome = join(base, 'claude-home')
+  const projectsDir = getProjectsDirForCwd(cwd, claudeHome)
+  mkdirSync(projectsDir, { recursive: true })
+  return { claudeHome, cwd, projectsDir }
+}
+
+const setMtime = (path: string, seconds: number): void => utimesSync(path, seconds, seconds)
+const wait = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+const assistantText = (text: string): string =>
+  JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text }] } }) + '\n'
+const toolUseLine = (name: string, id: string): string =>
+  JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }) + '\n'
+
+const findSidecar = (sessionId: string): FakeSidecar | undefined =>
+  created.instances.find((i) => i.sessionId === sessionId)
+
+describe('session-tail sidecar reap (M1) — parent session rotation', () => {
+  it('stops the prior session sidecar when the active file rotates', async () => {
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const first = join(projectsDir, 'session-one.jsonl')
+    const second = join(projectsDir, 'session-two.jsonl')
+
+    writeFileSync(first, assistantText('parent one'))
+    setMtime(first, 1_000_000)
+
+    const handle = startSessionTail({ cwd, claudeHome, rescanIntervalMs: 30, onEvent: () => {}, createSidecar: fakeSidecarFactory })
+    try {
+      await wait(120) // initial attach → sidecar 'session-one' created
+      expect(findSidecar('session-one')).toBeDefined()
+      expect(findSidecar('session-one')!.stop).not.toHaveBeenCalled()
+
+      // A newer session file appears (compaction / clear rotation).
+      const nowSec = Math.floor(Date.now() / 1000)
+      writeFileSync(second, assistantText('parent two'))
+      setMtime(second, nowSec + 20)
+      setMtime(first, nowSec + 5)
+      await wait(200) // rescan flips to session-two → session-one must be reaped
+
+      expect(findSidecar('session-two')).toBeDefined()
+      // The rotated-away session's sidecar is stopped at runtime, not left for stop().
+      expect(findSidecar('session-one')!.stop).toHaveBeenCalledTimes(1)
+      // The now-active session's sidecar stays alive.
+      expect(findSidecar('session-two')!.stop).not.toHaveBeenCalled()
+    } finally {
+      handle.stop()
+    }
+  })
+})
+
+describe('session-tail sidecar reap (M1) — idle sub-agent', () => {
+  it('stops a sub-agent sidecar when its idle sub-tail is reaped', async () => {
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const parent = join(projectsDir, 'parent.jsonl')
+    writeFileSync(parent, assistantText('parent'))
+    setMtime(parent, Math.floor(Date.now() / 1000))
+
+    // Sub-agents live under <parentSessionId>/subagents/agent-<id>.jsonl.
+    const subDir = join(projectsDir, 'parent', 'subagents')
+    mkdirSync(subDir, { recursive: true })
+    const subFile = join(subDir, 'agent-sub123.jsonl')
+    // A tool_use line makes the sub-tail lazily create its sidecar (keyed by
+    // the file stem 'agent-sub123').
+    writeFileSync(subFile, toolUseLine('Bash', 'toolu_1'))
+
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 30,
+      // Reap sub-tails idle for >1000ms so the test doesn't wait 5 minutes but
+      // still respects the L1 floor clamp (Math.max(1000, …) — a smaller value
+      // is silently lifted to 1s) and leaves a window to observe the
+      // not-yet-reaped state.
+      subTailIdleReapMs: 1000,
+      onEvent: () => {},
+      createSidecar: fakeSidecarFactory,
+    })
+    try {
+      await wait(100) // attach parent + sub, read tool_use → sidecar created
+      const sub = findSidecar('agent-sub123')
+      expect(sub).toBeDefined()
+      expect(sub!.stop).not.toHaveBeenCalled()
+
+      // Let the sub-tail go idle past the reap window; a rescan tick reaps it.
+      await wait(1300)
+      expect(sub!.stop).toHaveBeenCalledTimes(1)
+    } finally {
+      handle.stop()
+    }
+  })
+})
+
+describe('session-tail sidecar reap (L1) — reap window is floor-clamped', () => {
+  it('does NOT instant-reap a live sub-tail under a zero (or negative) idle window', async () => {
+    // A `subTailIdleReapMs` of 0 (or negative) would, without the
+    // Math.max(1000, …) clamp, make `reapIdleSubTails` compute
+    // `cutoff = Date.now() - 0`, which is ALWAYS ≥ a live sub-tail's slightly-
+    // earlier `lastActivityAt` — so every live sub-agent sidecar would be
+    // reaped on the very first rescan tick. The clamp lifts the effective
+    // window to the 1s floor, so a sub-tail active moments ago survives.
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const parent = join(projectsDir, 'parent.jsonl')
+    writeFileSync(parent, assistantText('parent'))
+    setMtime(parent, Math.floor(Date.now() / 1000))
+
+    const subDir = join(projectsDir, 'parent', 'subagents')
+    mkdirSync(subDir, { recursive: true })
+    const subFile = join(subDir, 'agent-subzero.jsonl')
+    writeFileSync(subFile, toolUseLine('Bash', 'toolu_z'))
+
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 30,
+      subTailIdleReapMs: 0, // pathological: pre-clamp this instant-reaps
+      onEvent: () => {},
+      createSidecar: fakeSidecarFactory,
+    })
+    try {
+      await wait(100) // attach parent + sub → sidecar 'agent-subzero' created
+      const sub = findSidecar('agent-subzero')
+      expect(sub).toBeDefined()
+      expect(sub!.stop).not.toHaveBeenCalled()
+
+      // Several rescan ticks pass (well under the 1s clamp floor). A live
+      // sub-tail whose activity is <1s old must NOT be reaped — so its sidecar
+      // stays alive. Pre-clamp, the first tick reaps it (sub.stop called once).
+      await wait(200)
+      expect(sub!.stop).not.toHaveBeenCalled()
+    } finally {
+      handle.stop()
+    }
+  })
+})
+
+describe('session-tail sidecar reap (M1) — namespace safety', () => {
+  it('a parent-session rotation does NOT stop a concurrently-live sub-agent sidecar', async () => {
+    // The rotation reap in attachToFile stops the sidecar keyed by the
+    // rotated-away parent's JSONL stem (a UUID). A live sub-agent's sidecar is
+    // keyed by its OWN file stem ('agent-<id>'). Because the two key namespaces
+    // never collide, rotating the parent must leave the sub-agent's sidecar
+    // untouched — otherwise a `/clear` or compaction mid-worker would silently
+    // kill the live worker's label sidecar. Reviewer verified by code-reading
+    // only; this locks it in.
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const first = join(projectsDir, 'session-one.jsonl')
+    const second = join(projectsDir, 'session-two.jsonl')
+
+    writeFileSync(first, assistantText('parent one'))
+    setMtime(first, 1_000_000)
+
+    // A live sub-agent under the CURRENT (session-one) parent. Its tool_use
+    // line makes the sub-tail create a sidecar keyed 'agent-subns'.
+    const subDir = join(projectsDir, 'session-one', 'subagents')
+    mkdirSync(subDir, { recursive: true })
+    const subFile = join(subDir, 'agent-subns.jsonl')
+    writeFileSync(subFile, toolUseLine('Bash', 'toolu_ns'))
+
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 30,
+      // Large window so the sub-tail is never idle-reaped during the test —
+      // we're isolating the rotation path, not the idle path.
+      subTailIdleReapMs: 60_000,
+      onEvent: () => {},
+      createSidecar: fakeSidecarFactory,
+    })
+    try {
+      await wait(120) // attach parent + sub → both sidecars created
+      const parentSidecar = findSidecar('session-one')
+      const subSidecar = findSidecar('agent-subns')
+      expect(parentSidecar).toBeDefined()
+      expect(subSidecar).toBeDefined()
+      expect(parentSidecar!.stop).not.toHaveBeenCalled()
+      expect(subSidecar!.stop).not.toHaveBeenCalled()
+
+      // Parent session rotates (compaction / clear → new sessionId).
+      const nowSec = Math.floor(Date.now() / 1000)
+      writeFileSync(second, assistantText('parent two'))
+      setMtime(second, nowSec + 20)
+      setMtime(first, nowSec + 5)
+      await wait(200) // rescan flips active file to session-two
+
+      // The rotated-away PARENT sidecar is reaped …
+      expect(parentSidecar!.stop).toHaveBeenCalledTimes(1)
+      // … but the concurrently-live SUB-agent sidecar is NOT — different stem
+      // namespace, so the rotation reap never targets it.
+      expect(subSidecar!.stop).not.toHaveBeenCalled()
+    } finally {
+      handle.stop()
+    }
+  })
+})