switchroom 0.13.20 → 0.13.21

package/telegram-plugin/handoff-continuity.ts

@@ -5,7 +5,7 @@
  * (written by the summarizer Stop hook). On the FIRST assistant reply
  * of the new session the plugin prepends a subtle one-liner:
  *
- *   ↩️ Picked up where we left off — <topic>
+ *   ↩️ Picked up where we left off, <topic>
  *
  * The sidecar is consumed (read + deleted) so the line only fires once.
  * All helpers here are filesystem-only or env-only — no Telegram side
@@ -175,7 +175,13 @@ export function formatHandoffLine(
   topic: string,
   format: HandoffFormat,
 ): string {
-  const prefix = "↩️ Picked up where we left off — ";
+  // Comma instead of em-dash: the framework-emitted prefix is
+  // concatenated AFTER scrubVoice runs on the model body (gateway.ts
+  // executeReply), so any em-dash here bypasses the v0.13.20 voice
+  // scrub. Replacing at the template source is one mechanical change
+  // that closes the dominant residual em-dash leak (16 of 17 dashed
+  // messages on test-harness were this template per 2026-05-24 audit).
+  const prefix = "↩️ Picked up where we left off, ";
   if (format === "html") {
     return `<i>${prefix}${escapeHtml(topic)}</i>\n\n`;
   }

package/telegram-plugin/recent-outbound-dedup.ts

@@ -57,6 +57,16 @@ interface DedupEntry {
   /** First 80 chars of the original (un-normalized) text — for
    *  operator-facing log lines that show what got deduped. */
   preview: string
+  /** The `currentTurn.registryKey` at record time, or `null` if the
+   *  recording site had no turn context. Threaded through so check()
+   *  can distinguish within-turn retries (#546 bug class — keep
+   *  protecting) from cross-turn coincidences (2026-05-23 audit found
+   *  identical mid-turn + final replies across two turns ~30s apart
+   *  silently swallowing the second turn's answer; the user gets
+   *  no response to their second question). Null on either side
+   *  matches as before, preserving the boot-time / edge-case behaviour
+   *  the original tests pin. */
+  turnKey: string | null
 }
 
 /**
@@ -75,8 +85,21 @@ export class OutboundDedupCache {
   /** Record an outbound message. Caller should invoke this after a
    *  successful send, regardless of which path sent it (turn-flush,
    *  executeReply, executeStreamReply, etc.). Short content is not
-   *  recorded — see DEDUP_MIN_CONTENT_LEN. */
-  record(chatId: string, threadId: number | undefined, text: string, now: number): void {
+   *  recorded — see DEDUP_MIN_CONTENT_LEN.
+   *
+   *  `turnKey` lets check() tell within-turn retries (the #546 race
+   *  this module exists to catch) apart from cross-turn coincidences
+   *  (a user asking similar questions in different turns). Pass
+   *  `null` if the recording site has no turn context — that matches
+   *  legacy behaviour and is what the early-boot / fallback callers
+   *  pass. */
+  record(
+    chatId: string,
+    threadId: number | undefined,
+    text: string,
+    now: number,
+    turnKey: string | null = null,
+  ): void {
     if (text.length < DEDUP_MIN_CONTENT_LEN) return
     const key = makeKey(chatId, threadId)
     const list = this.entries.get(key) ?? []
@@ -85,6 +108,7 @@ export class OutboundDedupCache {
       hash: normalizeForDedup(text),
       ts: now,
       preview: text.slice(0, 80),
+      turnKey,
     })
     this.entries.set(key, list)
   }
@@ -92,12 +116,24 @@ export class OutboundDedupCache {
   /** Check whether the given text was already sent recently to the
    *  same chat. Returns the matched entry's preview + age on hit, or
    *  null on miss. Caller decides what to do with the answer
-   *  (skip-send, log, etc.). */
+   *  (skip-send, log, etc.).
+   *
+   *  Cross-turn carve-out (2026-05-23 fix): when both sides of a hash
+   *  match carry non-null `turnKey` AND those keys differ, treat as
+   *  miss. The duplicate-reply race this module was built for (#546)
+   *  is strictly within-turn (the same turn's buffered text replays
+   *  via a stream_reply retry), so within-turn retries continue to
+   *  hit. A user typing two similar prompts back-to-back used to lose
+   *  the second turn's reply because the hashes collided across
+   *  turns; that no longer happens. Null on EITHER side (legacy /
+   *  no-turn-context callers) still matches — preserves backward
+   *  compatibility with the original test suite + early-boot paths. */
   check(
     chatId: string,
     threadId: number | undefined,
     text: string,
     now: number,
+    turnKey: string | null = null,
   ): { matched: true; preview: string; ageMs: number } | null {
     if (text.length < DEDUP_MIN_CONTENT_LEN) return null
     const key = makeKey(chatId, threadId)
@@ -106,9 +142,19 @@ export class OutboundDedupCache {
     this.evict(list, now)
     const candidateHash = normalizeForDedup(text)
     for (const entry of list) {
-      if (entry.hash === candidateHash) {
-        return { matched: true, preview: entry.preview, ageMs: now - entry.ts }
+      if (entry.hash !== candidateHash) continue
+      // Cross-turn carve-out: distinct, non-null turnKeys on both
+      // sides ⇒ different turns ⇒ not a #546 retry. Skip past this
+      // entry and keep scanning (a same-turn match later in the list
+      // should still hit).
+      if (
+        turnKey != null
+        && entry.turnKey != null
+        && entry.turnKey !== turnKey
+      ) {
+        continue
       }
+      return { matched: true, preview: entry.preview, ageMs: now - entry.ts }
     }
     return null
   }

package/telegram-plugin/runtime-metrics.ts

@@ -158,7 +158,11 @@ export type RuntimeMetricEvent =
       kind: 'voice_scrub_applied'
       chatKey: string
       replaced: number
-      site: 'reply' | 'edit_message' | 'progress_update' | 'answer_stream'
+      // `stream_reply` and `turn_flush` added in v0.13.21 — modern
+      // Claude routes most multi-paragraph replies through the
+      // answer-stream / draft-stream path, bypassing the v0.13.20
+      // executeReply scrub site. The two new sites close that gap.
+      site: 'reply' | 'edit_message' | 'progress_update' | 'answer_stream' | 'stream_reply' | 'turn_flush'
     }
 
 /**

package/telegram-plugin/subagent-watcher.ts

@@ -459,7 +459,10 @@ function backfillJsonlAgentId(
   log?.(`subagent-watcher: backfill linked ${agentId} → ${candidate.id}`)
 }
 
-function readSubTail(
+// Exported for unit-testing the ENOENT/EACCES deregister path
+// (telegram-plugin/tests/subagent-watcher-enoent-deregister.test.ts).
+// Not intended for consumption by other modules.
+export function readSubTail(
   entry: WorkerEntry,
   tail: SubTail,
   now: number,
@@ -472,6 +475,14 @@ function readSubTail(
    *  previously-stalled entry. Closes the resume edge the schema doc
    *  has always promised. */
   onUnstall?: (agentId: string, description: string) => void,
+  /** Fires when the JSONL file is no longer accessible (ENOENT — file
+   *  reaped by Claude Code when the parent session ends; EACCES —
+   *  permission change mid-poll). The caller deregisters the entry so
+   *  the 1s poll loop stops re-statting a dead path. Without this
+   *  callback, every poll re-emits the error log line — on 2026-05-23
+   *  the clerk agent logged 540k ENOENT lines in 3 days (30/sec
+   *  sustained) AND leaked one fs.watch FD per stranded entry. */
+  onFileVanished?: (agentId: string, code: 'ENOENT' | 'EACCES') => void,
 ): void {
   try {
     const stat = fs.statSync(entry.filePath)
@@ -639,6 +650,17 @@ function readSubTail(
     }
     tail.hasEmittedStart = startState.hasEmittedStart
   } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'ENOENT' || code === 'EACCES') {
+      // JSONL is gone (Claude Code reaped the parent session's
+      // subagents/ dir) or permission flipped under us. Deregister the
+      // entry so the periodic poll stops re-emitting this same line
+      // forever. Logged ONCE per agent — operators can still audit
+      // which entries got reaped without 30 lines/sec of noise.
+      log?.(`subagent-watcher: JSONL vanished for ${entry.agentId} (${code}) — deregistering`)
+      onFileVanished?.(entry.agentId, code)
+      return
+    }
     log?.(`subagent-watcher: read error ${entry.agentId}: ${(err as Error).message}`)
   }
 }
@@ -841,7 +863,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
         if (!entry || !t) return
         readSubTail(entry, t, nowFn(), (desc) => {
           log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
-        }, fs, log, db, parentStateDir, config.onUnstall)
+        }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent)
         maybySendStateTransition(agentId)
       })
     } catch (err) {
@@ -1179,7 +1201,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       if (!tail) continue
       readSubTail(entry, tail, n, (desc) => {
         log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
-      }, fs, log, db, parentStateDir, config.onUnstall)
+      }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent)
       maybySendStateTransition(agentId)
     }
 

package/telegram-plugin/tests/gateway-disconnect-flush.test.ts

@@ -142,3 +142,117 @@ describe('flushOnAgentDisconnect — registered agent disconnects (existing beha
     expect(deps.activeDraftParseModes.size).toBe(0)
   })
 })
+
+describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)', () => {
+  // The race that motivates this: the canonical reply path fires
+  // `setDone()` on the StatusReactionController BEFORE purgeReactionTracking
+  // runs `activeTurnStartedAt.delete(key)`. If the bridge crashes between
+  // those two steps, the controller loop sees an EMPTY activeStatusReactions
+  // (already cleared by setDone) but activeTurnStartedAt still has the key.
+  // Without the sweep, that key orphans and the next inbound is "held mid-
+  // turn" against a ghost.
+
+  it('sweeps activeTurnStartedAt keys the controller loop missed', () => {
+    // Construct the exact race: activeStatusReactions is EMPTY (setDone
+    // already cleared it on the reply path) but activeTurnStartedAt still
+    // has an entry.
+    const onDanglingTurnsSwept = vi.fn()
+    const clearActiveReactions = vi.fn()
+    const disposeProgressDriver = vi.fn()
+    const log = vi.fn()
+    const deps = {
+      agentName: 'clerk',
+      activeStatusReactions: new Map<string, FakeCtrl>(),
+      activeReactionMsgIds: new Map<string, { chatId: string; messageId: number }>([
+        ['ghost:thr:msg', { chatId: 'ghost', messageId: 42 }],
+      ]),
+      activeTurnStartedAt: new Map<string, number>([['ghost:thr:msg', 100]]),
+      activeDraftStreams: new Map<string, FakeStream>(),
+      activeDraftParseModes: new Map<string, 'HTML' | 'MarkdownV2' | undefined>(),
+      clearActiveReactions,
+      disposeProgressDriver,
+      onDanglingTurnsSwept,
+      log,
+    }
+
+    flushOnAgentDisconnect(deps)
+
+    // The sweep fired and cleared the dangling entry.
+    expect(deps.activeTurnStartedAt.size).toBe(0)
+    expect(deps.activeReactionMsgIds.size).toBe(0)
+    expect(onDanglingTurnsSwept).toHaveBeenCalledTimes(1)
+    expect(onDanglingTurnsSwept.mock.calls[0][0]).toEqual(['ghost:thr:msg'])
+    // The log line names what happened so the operator can audit.
+    expect(
+      log.mock.calls.some((c: unknown[]) =>
+        typeof c[0] === 'string' && /swept .* dangling turn/.test(c[0]),
+      ),
+    ).toBe(true)
+  })
+
+  it('does not fire the sweep when the controller loop already cleaned up everything', () => {
+    // Normal-path disconnect: activeStatusReactions had entries, the
+    // controller loop ran setDone + delete on each, activeTurnStartedAt
+    // is already empty by the end of the loop. No dangling to sweep.
+    const { spies, deps } = makeDeps('clerk')
+    const onDanglingTurnsSwept = vi.fn()
+    const depsWithCallback = { ...deps, onDanglingTurnsSwept }
+
+    flushOnAgentDisconnect(depsWithCallback)
+
+    // Controller loop already cleaned both entries.
+    expect(deps.activeTurnStartedAt.size).toBe(0)
+    // Callback NOT fired — nothing left to sweep after the loop.
+    expect(onDanglingTurnsSwept).not.toHaveBeenCalled()
+    // Regression: the existing setDone path still works.
+    expect(spies.setDoneA).toHaveBeenCalledTimes(1)
+    expect(spies.setDoneB).toHaveBeenCalledTimes(1)
+  })
+
+  it('does NOT sweep for anonymous disconnects (no agent registered)', () => {
+    // Critical regression guard: the sweep MUST be gated by the
+    // agentName-null early-return. Anonymous one-shot IPC clients
+    // (recall.py, etc.) disconnect constantly and must never touch
+    // turn state.
+    const onDanglingTurnsSwept = vi.fn()
+    const deps = {
+      agentName: null,
+      activeStatusReactions: new Map<string, FakeCtrl>(),
+      activeReactionMsgIds: new Map<string, { chatId: string; messageId: number }>(),
+      activeTurnStartedAt: new Map<string, number>([['real-turn:thr:msg', 100]]),
+      activeDraftStreams: new Map<string, FakeStream>(),
+      activeDraftParseModes: new Map<string, 'HTML' | 'MarkdownV2' | undefined>(),
+      clearActiveReactions: vi.fn(),
+      disposeProgressDriver: vi.fn(),
+      onDanglingTurnsSwept,
+      log: vi.fn(),
+    }
+
+    flushOnAgentDisconnect(deps)
+
+    // Anonymous disconnect: turn state preserved, sweep callback not fired.
+    expect(deps.activeTurnStartedAt.size).toBe(1)
+    expect(onDanglingTurnsSwept).not.toHaveBeenCalled()
+  })
+
+  it('omitting onDanglingTurnsSwept is safe (optional callback)', () => {
+    // Backward-compat guard — existing callers that don't pass the new
+    // callback still work without runtime error.
+    const deps = {
+      agentName: 'clerk',
+      activeStatusReactions: new Map<string, FakeCtrl>(),
+      activeReactionMsgIds: new Map<string, { chatId: string; messageId: number }>(),
+      activeTurnStartedAt: new Map<string, number>([['ghost:thr:msg', 100]]),
+      activeDraftStreams: new Map<string, FakeStream>(),
+      activeDraftParseModes: new Map<string, 'HTML' | 'MarkdownV2' | undefined>(),
+      clearActiveReactions: vi.fn(),
+      disposeProgressDriver: vi.fn(),
+      // onDanglingTurnsSwept intentionally omitted.
+      log: vi.fn(),
+    }
+
+    expect(() => flushOnAgentDisconnect(deps)).not.toThrow()
+    // The sweep still happens, just without the callback observation.
+    expect(deps.activeTurnStartedAt.size).toBe(0)
+  })
+})

package/telegram-plugin/tests/handoff-continuity.test.ts

@@ -219,7 +219,7 @@ describe("shouldShowHandoffLine", () => {
 describe("formatHandoffLine", () => {
   it("wraps the topic in italic HTML with the return emoji", () => {
     const line = formatHandoffLine("fixing the bug", "html");
-    expect(line).toBe("<i>↩️ Picked up where we left off — fixing the bug</i>\n\n");
+    expect(line).toBe("<i>↩️ Picked up where we left off, fixing the bug</i>\n\n");
   });
 
   it("escapes HTML-unsafe chars in the topic", () => {
@@ -238,7 +238,7 @@ describe("formatHandoffLine", () => {
 
   it("produces plain text for 'text' format", () => {
     const line = formatHandoffLine("simple", "text");
-    expect(line).toBe("↩️ Picked up where we left off — simple\n\n");
+    expect(line).toBe("↩️ Picked up where we left off, simple\n\n");
   });
 
   it("always ends with a blank-line separator", () => {
@@ -246,4 +246,17 @@ describe("formatHandoffLine", () => {
       expect(formatHandoffLine("t", fmt).endsWith("\n\n")).toBe(true);
     }
   });
+
+  // Regression guard: the handoff prefix was an em-dash bypass for the
+  // v0.13.20 voice scrubber (the framework prefix is concatenated AFTER
+  // scrubVoice runs in executeReply). Replacing the em-dash with a
+  // comma at the template source closes that leak. Pin it so a future
+  // operator who "fixes typography" doesn't re-introduce the dash.
+  it("does NOT contain an em-dash or en-dash in any format (voice-scrub guard)", () => {
+    for (const fmt of ["html", "markdownv2", "text"] as const) {
+      const line = formatHandoffLine("anything goes here", fmt);
+      expect(line).not.toContain("—");
+      expect(line).not.toContain("–");
+    }
+  });
 });

package/telegram-plugin/tests/inbound-delivery-gate.test.ts

@@ -41,13 +41,86 @@ describe('decideInboundDelivery', () => {
     ).toBe('deliver')
   })
 
-  it('is total: the ONLY deferral path is mid-turn AND not steering', () => {
+  it('is total: the ONLY deferral path is mid-turn AND not steering AND not interrupt', () => {
     for (const turnInFlight of [true, false]) {
       for (const isSteering of [true, false]) {
-        const decision = decideInboundDelivery({ turnInFlight, isSteering })
-        const expectBuffer = turnInFlight && !isSteering
-        expect(decision).toBe(expectBuffer ? 'buffer-until-idle' : 'deliver')
+        for (const isInterrupt of [true, false]) {
+          const decision = decideInboundDelivery({ turnInFlight, isSteering, isInterrupt })
+          const expectBuffer = turnInFlight && !isSteering && !isInterrupt
+          expect(decision).toBe(expectBuffer ? 'buffer-until-idle' : 'deliver')
+        }
       }
     }
   })
+
+  // ─── Interrupt-marker carve-out (2026-05-24 fix for the stranded-body bug) ──
+  // Live UAT trace: user fires `! actually do X` mid-turn. SIGINT delivered
+  // to claude via tmux send-keys. The killed turn does NOT emit
+  // turn_complete in many cases (mid-tool-call kill, in-flight subagent),
+  // so the post-`!` body sits in pendingInboundBuffer forever — the
+  // turn-complete drain trigger never fires. The user never gets a reply
+  // to their replacement instruction.
+  //
+  // The carve-out is a peer of isSteering: an interrupt body is by
+  // definition an intentional mid-turn delivery — the user explicitly
+  // asked for "stop and do this instead".
+  describe('interrupt-marker carve-out', () => {
+    it('delivers a `!`-interrupt body mid-turn (does NOT buffer)', () => {
+      // The headline regression fix. Without the carve-out the killed turn
+      // strands the body indefinitely.
+      expect(
+        decideInboundDelivery({
+          turnInFlight: true,
+          isSteering: false,
+          isInterrupt: true,
+        }),
+      ).toBe('deliver')
+    })
+
+    it('delivers a `!`-interrupt body even when claude is idle (no harm)', () => {
+      expect(
+        decideInboundDelivery({
+          turnInFlight: false,
+          isSteering: false,
+          isInterrupt: true,
+        }),
+      ).toBe('deliver')
+    })
+
+    it('isInterrupt is optional — omitting it preserves legacy behavior', () => {
+      // Backward-compat for callers that haven't been updated yet. Mirrors
+      // the optional-default pattern used in other gateway predicates this
+      // session (silent-reply-anchor wasOverPingSuppressed, recent-outbound-
+      // dedup turnKey).
+      expect(
+        decideInboundDelivery({ turnInFlight: true, isSteering: false }),
+      ).toBe('buffer-until-idle')
+      expect(
+        decideInboundDelivery({ turnInFlight: false, isSteering: false }),
+      ).toBe('deliver')
+    })
+
+    it('explicit isInterrupt:false is identical to omitting it', () => {
+      expect(
+        decideInboundDelivery({
+          turnInFlight: true,
+          isSteering: false,
+          isInterrupt: false,
+        }),
+      ).toBe('buffer-until-idle')
+    })
+
+    it('interrupt + steering combination delivers (both are exempt paths)', () => {
+      // Pathological prompt: `! /steer change tactics`. parseInterruptMarker
+      // strips the `!`, then steering parse sees `/steer`. Either flag
+      // alone delivers; both together still deliver. No regression.
+      expect(
+        decideInboundDelivery({
+          turnInFlight: true,
+          isSteering: true,
+          isInterrupt: true,
+        }),
+      ).toBe('deliver')
+    })
+  })
 })

package/telegram-plugin/tests/recent-outbound-dedup.test.ts

@@ -190,3 +190,75 @@ describe('OutboundDedupCache — multiple entries per chat', () => {
     expect(cache.check('chat', undefined, LONG_HTML, 6000)).not.toBeNull()
   })
 })
+
+// ─── turnKey carve-out (2026-05-23 cross-turn-swallow fix) ───────────────────
+// Without turnKey awareness, the 60s TTL eats the SECOND turn's reply when a
+// user asks similar questions back-to-back (forensic audit on midturn-silent
+// UAT). The carve-out: both sides non-null + distinct ⇒ treat as miss.
+// Within-turn (#546 retry race) protection unchanged: same turnKey on both
+// sides ⇒ legacy hit. Null on either side ⇒ legacy hit.
+
+const LONG_TEXT = 'long enough text to count as content for the dedup floor'
+
+describe('OutboundDedupCache — turnKey carve-out', () => {
+  it('cross-turn identical content with distinct non-null turnKeys MISSES', () => {
+    // The headline bug: dedup was eating user replies across turns.
+    const cache = new OutboundDedupCache()
+    cache.record('chat', undefined, LONG_TEXT, 1000, 'turn-A')
+    expect(
+      cache.check('chat', undefined, LONG_TEXT, 5000, 'turn-B'),
+    ).toBeNull()
+  })
+
+  it('within-turn duplicates (same turnKey) STILL HIT — preserves #546 protection', () => {
+    // Same-turn retry race the module was built for.
+    const cache = new OutboundDedupCache()
+    cache.record('chat', undefined, LONG_TEXT, 1000, 'turn-A')
+    expect(
+      cache.check('chat', undefined, LONG_TEXT, 10_000, 'turn-A'),
+    ).not.toBeNull()
+  })
+
+  it('record-null + check-non-null → legacy hit', () => {
+    // Boot-time / silent-marker callers pass null on record; later
+    // executeReply checks with a turnKey. Legacy match must persist
+    // for the #546 protection to cover these cross-context cases.
+    const cache = new OutboundDedupCache()
+    cache.record('chat', undefined, LONG_TEXT, 1000, null)
+    expect(
+      cache.check('chat', undefined, LONG_TEXT, 5000, 'turn-A'),
+    ).not.toBeNull()
+  })
+
+  it('record-non-null + check-null → legacy hit', () => {
+    // Symmetric direction: turn-flush records with turnKey, a later
+    // null-context probe (rare but possible) still matches.
+    const cache = new OutboundDedupCache()
+    cache.record('chat', undefined, LONG_TEXT, 1000, 'turn-A')
+    expect(
+      cache.check('chat', undefined, LONG_TEXT, 5000, null),
+    ).not.toBeNull()
+  })
+
+  it('cross-turn entry does NOT shadow a same-turn match later in the list', () => {
+    // Edge case the predicate must handle: when the scan hits a stale
+    // cross-turn entry whose hash matches, it must keep scanning past
+    // it to find a real same-turn match. (The carve-out is implemented
+    // as `continue`, not `return null`.)
+    const cache = new OutboundDedupCache()
+    cache.record('chat', undefined, LONG_TEXT, 1000, 'turn-A') // older, cross-turn
+    cache.record('chat', undefined, LONG_TEXT, 3000, 'turn-B') // newer, same turn as query
+    expect(
+      cache.check('chat', undefined, LONG_TEXT, 5000, 'turn-B'),
+    ).not.toBeNull()
+  })
+
+  it('legacy 4-arg API still compiles + matches (default turnKey=null)', () => {
+    // Backward-compat smoke test — older callers that haven't been
+    // updated to pass turnKey continue to behave as the original test
+    // suite pins.
+    const cache = new OutboundDedupCache()
+    cache.record('chat', undefined, LONG_TEXT, 1000)
+    expect(cache.check('chat', undefined, LONG_TEXT, 5000)).not.toBeNull()
+  })
+})

package/telegram-plugin/tests/subagent-watcher-enoent-deregister.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Tests for the readSubTail ENOENT/EACCES deregister path.
+ *
+ * Production symptom: clerk agent's gateway-supervisor.log was growing
+ * at ~30 ENOENT lines/sec sustained (540k+ in 3 days) because the
+ * watcher's poll loop kept statx-ing JSONL files Claude Code had
+ * already reaped along with the parent session's `subagents/` dir.
+ * Same shape on klanker with EACCES (635 events) — likely a perm
+ * flip during cleanup.
+ *
+ * Fix shape: when readSubTail's statSync throws ENOENT or EACCES,
+ * log ONE line + invoke the onFileVanished callback so the watcher
+ * factory can call cleanupTerminalAgent and stop polling. Other
+ * errors (parse, malformed JSONL) keep the legacy per-poll log line.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { readSubTail } from '../subagent-watcher.js'
+import type { WorkerEntry } from '../subagent-watcher.js'
+
+function fakeFsThrowingFromStat(code: 'ENOENT' | 'EACCES' | 'EOTHER') {
+  const err = new Error(`fake ${code}`) as NodeJS.ErrnoException
+  err.code = code
+  return {
+    existsSync: () => true,
+    readdirSync: () => [],
+    statSync: () => { throw err },
+    openSync: () => -1,
+    closeSync: () => {},
+    readSync: () => 0,
+    watch: () => ({ close: () => {} } as ReturnType<typeof require>),
+  } as unknown as Parameters<typeof readSubTail>[4]
+}
+
+function makeEntry(): WorkerEntry {
+  return {
+    agentId: 'a1234567890abcdef',
+    filePath: '/tmp/fake/agent-a1234567890abcdef.jsonl',
+    dispatchedAt: 0,
+    lastActivityAt: 0,
+    toolCount: 0,
+    state: 'running',
+    completionNotified: false,
+    stallNotified: false,
+    historical: false,
+    description: '',
+    lastSummaryLine: '',
+    lastResultText: '',
+  }
+}
+
+function makeTail() {
+  return {
+    cursor: 0,
+    pendingPartial: '',
+    hasEmittedStart: false,
+    watcher: null,
+  }
+}
+
+describe('readSubTail — ENOENT/EACCES deregister', () => {
+  it('fires onFileVanished and logs ONCE on ENOENT', () => {
+    const onFileVanished = vi.fn()
+    const log = vi.fn()
+    const entry = makeEntry()
+
+    readSubTail(
+      entry,
+      makeTail(),
+      0,
+      vi.fn(),
+      fakeFsThrowingFromStat('ENOENT'),
+      log,
+      null,
+      null,
+      undefined,
+      onFileVanished,
+    )
+
+    expect(onFileVanished).toHaveBeenCalledTimes(1)
+    expect(onFileVanished).toHaveBeenCalledWith('a1234567890abcdef', 'ENOENT')
+    expect(log).toHaveBeenCalledTimes(1)
+    expect(log.mock.calls[0][0]).toMatch(/JSONL vanished for a1234567890abcdef \(ENOENT\) — deregistering/)
+    expect(log.mock.calls[0][0]).not.toMatch(/read error/)
+  })
+
+  it('fires onFileVanished and logs ONCE on EACCES (klanker pattern)', () => {
+    const onFileVanished = vi.fn()
+    const log = vi.fn()
+
+    readSubTail(
+      makeEntry(),
+      makeTail(),
+      0,
+      vi.fn(),
+      fakeFsThrowingFromStat('EACCES'),
+      log,
+      null,
+      null,
+      undefined,
+      onFileVanished,
+    )
+
+    expect(onFileVanished).toHaveBeenCalledTimes(1)
+    expect(onFileVanished).toHaveBeenCalledWith('a1234567890abcdef', 'EACCES')
+    expect(log).toHaveBeenCalledTimes(1)
+    expect(log.mock.calls[0][0]).toMatch(/EACCES/)
+  })
+
+  it('still logs the legacy "read error" for unexpected error codes', () => {
+    // Regression guard: parse errors, EIO, EBUSY, etc. must still
+    // surface their detail. Only file-vanished codes are deregistered.
+    const onFileVanished = vi.fn()
+    const log = vi.fn()
+
+    readSubTail(
+      makeEntry(),
+      makeTail(),
+      0,
+      vi.fn(),
+      fakeFsThrowingFromStat('EOTHER'),
+      log,
+      null,
+      null,
+      undefined,
+      onFileVanished,
+    )
+
+    expect(onFileVanished).not.toHaveBeenCalled()
+    expect(log).toHaveBeenCalledTimes(1)
+    expect(log.mock.calls[0][0]).toMatch(/read error a1234567890abcdef/)
+  })
+
+  it('omitting onFileVanished is safe (optional callback)', () => {
+    const log = vi.fn()
+
+    expect(() =>
+      readSubTail(
+        makeEntry(),
+        makeTail(),
+        0,
+        vi.fn(),
+        fakeFsThrowingFromStat('ENOENT'),
+        log,
+        null,
+        null,
+        undefined,
+      ),
+    ).not.toThrow()
+    expect(log).toHaveBeenCalledTimes(1)
+  })
+})