switchroom 0.19.4 → 0.19.6

package/telegram-plugin/render/line-start-guard.ts

@@ -43,11 +43,20 @@
 // punctuation may be backslash-escaped" rule; Telegram's rich parser strips
 // the backslash the same way `escapeMarkdown` relies on for `~ = | * _`.
 //
+// ── Accidental heading (`#3460`, `#foo`) — guarded by guardAccidentalHeading ─
+//   Telegram's Bot API rich-markdown parser is NON-spec: it promotes ANY
+//   line-leading `#{1,6}` run to a heading even WITHOUT the CommonMark-required
+//   trailing space (`#3460 done` renders as a huge heading). This is
+//   deterministically disambiguable: a `#{1,6}` run followed by a space,
+//   another `#`, or end-of-line is an INTENDED heading (or ambiguous) and is
+//   LEFT ALONE; a run glued to a non-space, non-`#` char (`#3460`, `#foo`,
+//   `###x`) is the accidental Telegram-only heading and IS escaped. See
+//   `guardAccidentalHeading` below — it mirrors the render.ts:escapeLineLeadingHash
+//   fix (#3306) but runs at the universal wire seam, independent of the
+//   SWITCHROOM_RICH_RENDER kill-switch, so cards/banners/status/approval sends
+//   (which bypass the rich renderer) are also covered.
+//
 // ── What is DEFERRED (left to the rich-formatting workstream) ────────────
-//   • Heading `# ` (with the required space): indistinguishable from an
-//     INTENDED heading. `#1` / `#foo` (NO space) is not a GFM heading at all
-//     (ATX headings require `#`+space) → Telegram renders it literally → no
-//     guard needed. So there is no safely-guardable heading sub-case.
 //   • Bullet lists `-`/`+`/`*` + space (`- 5 degrees`): genuinely ambiguous
 //     with the heavily-used bullet construct; the glued form `-5` (no space)
 //     is not a list item → already literal → no guard needed. Escaping the
@@ -165,3 +174,66 @@ export function guardAccidentalBlockConstructs(text: string): string {
 
   return out;
 }
+
+/** Line-start `#{1,6}` run glued DIRECTLY to a non-space, non-`#` char — the
+ *  Telegram-non-spec accidental heading (`#3460`, `#foo`, `###x`). The negative
+ *  lookahead `(?=[^\s#])` requires a following char that is neither whitespace,
+ *  a `#`, nor end-of-line, so an intended `# Title` / `## Sub` (space-delimited)
+ *  and a bare `#` / `##` (end-of-line) are NEVER matched. Up to 3 leading spaces
+ *  are permitted (4+ is indented code, and the `{0,3}` bound then leaves a space
+ *  before the `#`, so it correctly does not match). Only the first `#` of the run
+ *  is backslash-escaped, which is sufficient to stop Telegram promoting the line
+ *  to a heading. Idempotent: an already-escaped `\#3460` starts with `\`, so the
+ *  `#{1,6}` no longer sits at the (post-indent) line start. */
+const ACCIDENTAL_HEADING = /^([ \t]{0,3})(#{1,6})(?=[^\s#])/;
+
+/**
+ * Escape the accidental heading trigger at the start of ONE line (the string
+ * must NOT contain a newline; the caller guarantees a true line start). A no-op
+ * unless the line begins with a `#{1,6}` run glued to a non-space, non-`#` char.
+ */
+function escapeAccidentalHeadingLine(line: string): string {
+  return line.replace(ACCIDENTAL_HEADING, "$1\\$2");
+}
+
+/**
+ * Neutralise accidental line-start HEADING promotion (`#3460 done` → giant
+ * heading) on the FINAL rendered rich-markdown string. Telegram's Bot API
+ * parser promotes a line-leading `#{1,6}` run to a heading even without the
+ * CommonMark-required trailing space; this escapes ONLY the space-less,
+ * non-`#`-adjacent form and leaves genuine `# Title` / `## Sub` headings
+ * untouched. Code spans / fenced blocks / link destinations / table rows are
+ * never touched (shared `splitProtectedSegments`). Idempotent and a strict
+ * no-op absent a real signal. Mirrors render.ts:escapeLineLeadingHash (#3306)
+ * but runs at the universal wire seam, so it also covers the card / banner /
+ * status / approval sends that bypass the rich renderer.
+ */
+export function guardAccidentalHeading(text: string): string {
+  // Cheap short-circuit: no `#` at all => no-op.
+  if (!text.includes("#")) return text;
+
+  const segments = splitProtectedSegments(text);
+  let out = "";
+  // True at text start and immediately after any emitted `\n`.
+  let atLineStart = true;
+
+  for (const seg of segments) {
+    if (seg.code) {
+      out += seg.text;
+      atLineStart = seg.text.endsWith("\n");
+      continue;
+    }
+    const lines = seg.text.split("\n");
+    for (let k = 0; k < lines.length; k++) {
+      // A prose segment can begin MID-LINE (right after an inline code span),
+      // so its first line is a real line start only if the running flag says so.
+      const lineIsAtStart = k === 0 ? atLineStart : true;
+      const processed = lineIsAtStart ? escapeAccidentalHeadingLine(lines[k]) : lines[k];
+      out += processed;
+      if (k < lines.length - 1) out += "\n";
+    }
+    atLineStart = seg.text.endsWith("\n");
+  }
+
+  return out;
+}

package/telegram-plugin/reply-owner-resolve.ts

@@ -84,6 +84,37 @@ function latestEndedAccepted(candidates: ReplyOwnerCandidates): boolean {
   return age <= ttl
 }
 
+/**
+ * Which precedence tier resolved a reply's owner turn.
+ *
+ *   - `'live'` / `'origin'` / `'quoted'` are POSITIVE attributions: the reply
+ *     is tied to a specific turn by a live atom, the model's own echo, or the
+ *     framework-owned quoted message id — it IS that turn's answer.
+ *   - `'latest-ended'` is the ambiguous FALLBACK: no positive link exists, so
+ *     the reply is merely attributed to the chat's most-recently-ended turn.
+ *     This tier cannot tell the turn's OWN late reply from an async sub-agent
+ *     handback that has no live turn and no quote linkage — both land here with
+ *     the same resolved turnId (#3429). The supersede content gate
+ *     (`flushedAnswerMatchesReply`) is therefore applied ONLY on this tier.
+ *   - `'none'` — every lookup missed (a genuinely unattributable reply).
+ */
+export type ReplyOwnerTier = 'live' | 'origin' | 'quoted' | 'latest-ended' | 'none'
+
+/**
+ * The tier that WINS owner resolution for these candidates — the single source
+ * of the precedence order, consumed by both `resolveReplyOwnerTurnId` (which id)
+ * and the gateway (which discrimination the supersede applies). Same precedence,
+ * first non-null wins; the destructive latest-ended tier is honoured only when
+ * fresh (`latestEndedAccepted`).
+ */
+export function resolveReplyOwnerTier(candidates: ReplyOwnerCandidates): ReplyOwnerTier {
+  if (candidates.liveTurnId != null) return 'live'
+  if (candidates.originTurnId != null) return 'origin'
+  if (candidates.quotedTurnId != null) return 'quoted'
+  if (latestEndedAccepted(candidates)) return 'latest-ended'
+  return 'none'
+}
+
 /**
  * Resolve the turnId that OWNS a landing reply, using the SAME full chain the
  * thread-router uses. Precedence, first non-null wins:
@@ -98,13 +129,18 @@ function latestEndedAccepted(candidates: ReplyOwnerCandidates): boolean {
  * to delete any turnId-bearing flush record.
  */
 export function resolveReplyOwnerTurnId(candidates: ReplyOwnerCandidates): string | null {
-  return (
-    candidates.liveTurnId ??
-    candidates.originTurnId ??
-    candidates.quotedTurnId ??
-    (latestEndedAccepted(candidates) ? candidates.latestEndedTurnId : null) ??
-    null
-  )
+  switch (resolveReplyOwnerTier(candidates)) {
+    case 'live':
+      return candidates.liveTurnId
+    case 'origin':
+      return candidates.originTurnId
+    case 'quoted':
+      return candidates.quotedTurnId
+    case 'latest-ended':
+      return candidates.latestEndedTurnId
+    case 'none':
+      return null
+  }
 }
 
 /**

package/telegram-plugin/rich-send.ts

@@ -20,7 +20,7 @@
 import { GrammyError } from 'grammy'
 import { guardDollarMath } from './render/dollar-math-guard.js'
 import { guardAccidentalEmphasis } from './render/emphasis-guard.js'
-import { guardAccidentalBlockConstructs } from './render/line-start-guard.js'
+import { guardAccidentalBlockConstructs, guardAccidentalHeading } from './render/line-start-guard.js'
 import { guardAccidentalInlinePairs } from './render/inline-pairs-guard.js'
 
 /** The `InputRichMessage` shape grammy 1.44 accepts on send AND edit. */
@@ -36,6 +36,12 @@ export interface InputRichMessageMarkdown {
  * idempotent and safe to apply once per send.
  *
  * ── Ordering (deliberate, not arbitrary) ──────────────────────────────────
+ * `guardAccidentalHeading` runs right after emphasis and before block-constructs.
+ * It only ever inserts `\` before a line-leading `#{1,6}` run; `#` is inspected
+ * and inserted by no other guard (disjoint char set), so its position among the
+ * siblings is order-independent — it neither creates nor destroys a signal for
+ * any of them.
+ *
  * `guardDollarMath` runs LAST. It backslash-escapes `$` → `\$`, and the
  * inline-pairs guard's approximation-tilde signal is `~(?=\$?\.?\d)` — a `~`
  * glued to a `$digit`. If the dollar guard ran first, a body like
@@ -51,6 +57,7 @@ export interface InputRichMessageMarkdown {
 export function guardAccidentalFormatting(markdown: string): string {
   let out = markdown
   out = guardAccidentalEmphasis(out)
+  out = guardAccidentalHeading(out)
   out = guardAccidentalBlockConstructs(out)
   out = guardAccidentalInlinePairs(out)
   out = guardDollarMath(out)

package/telegram-plugin/tests/command-format.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Direct unit tests for `gateway/command-format.ts` — the pure
+ * slash-command formatting/keyboard helpers extracted from gateway.ts
+ * in switchroom#3461 (testability win tracked by #3460).
+ *
+ * These assert real rendered outcomes (exact strings, keyboard shapes,
+ * thrown errors), not just that the code runs.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  formatSwitchroomOutput,
+  stripAnsi,
+  escapeHtmlForTg,
+  preBlock,
+  getCommandArgs,
+  hasDemoFlag,
+  assertSafeAgentName,
+  formatAuthOutputForTelegram,
+  buildAuthUrlKeyboard,
+  buildDeferredSecretKeyboard,
+  renderVaultOpFailure,
+  statusIcon,
+  renderAuthCodeOutcome,
+  buildDoctorScopeKeyboard,
+  formatDoctorReport,
+} from '../gateway/command-format.js'
+import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import type { Context } from 'grammy'
+
+describe('formatSwitchroomOutput', () => {
+  it('trims and passes short output through unchanged', () => {
+    expect(formatSwitchroomOutput('  hello\nworld  ')).toBe('hello\nworld')
+  })
+  it('truncates past the rich-message cap with a marker', () => {
+    const big = 'x'.repeat(RICH_MESSAGE_MAX_CHARS + 100)
+    const out = formatSwitchroomOutput(big)
+    expect(out.endsWith('\n... (truncated)')).toBe(true)
+    expect(out.length).toBeLessThanOrEqual(RICH_MESSAGE_MAX_CHARS)
+  })
+  it('honours an explicit maxLen', () => {
+    expect(formatSwitchroomOutput('abcdefghij'.repeat(10), 50)).toBe(
+      'abcdefghij'.repeat(10).slice(0, 30) + '\n... (truncated)',
+    )
+  })
+})
+
+describe('stripAnsi', () => {
+  it('removes CSI escape sequences and keeps text', () => {
+    expect(stripAnsi('\x1b[31mred\x1b[0m plain')).toBe('red plain')
+  })
+})
+
+describe('escapeHtmlForTg', () => {
+  it('backslash-escapes GFM specials', () => {
+    expect(escapeHtmlForTg('a*b_c`d[e]f|g~h=i\\j')).toBe(
+      'a\\*b\\_c\\`d\\[e\\]f\\|g\\~h\\=i\\\\j',
+    )
+  })
+  it('leaves ordinary text alone', () => {
+    expect(escapeHtmlForTg('hello world 123')).toBe('hello world 123')
+  })
+})
+
+describe('preBlock', () => {
+  it('wraps content in a fenced code block', () => {
+    expect(preBlock('ls -la')).toBe('```\nls -la\n```')
+  })
+  it('defuses embedded triple-backticks so the fence cannot break', () => {
+    const out = preBlock('a```b')
+    expect(out.startsWith('```\n')).toBe(true)
+    expect(out.endsWith('\n```')).toBe(true)
+    // interior fence broken up (zero-width space injected)
+    expect(out.slice(4, -4)).not.toContain('```')
+  })
+})
+
+describe('getCommandArgs', () => {
+  it('prefers ctx.match when present', () => {
+    const ctx = { match: '  foo bar  ', msg: { text: '/cmd other' } } as unknown as Context
+    expect(getCommandArgs(ctx)).toBe('foo bar')
+  })
+  it('falls back to parsing the message text', () => {
+    const ctx = { match: undefined, msg: { text: '/restart alpha beta' } } as unknown as Context
+    expect(getCommandArgs(ctx)).toBe('alpha beta')
+  })
+  it('returns empty string for a bare command', () => {
+    const ctx = { match: '', msg: { text: '/status' } } as unknown as Context
+    expect(getCommandArgs(ctx)).toBe('')
+  })
+})
+
+describe('hasDemoFlag', () => {
+  it('matches trailing demo token case-insensitively', () => {
+    expect(hasDemoFlag('demo')).toBe(true)
+    expect(hasDemoFlag('show DEMO')).toBe(true)
+  })
+  it('does not match demo as a prefix of another token', () => {
+    expect(hasDemoFlag('demo-foo')).toBe(false)
+    expect(hasDemoFlag('demo mid')).toBe(false)
+  })
+})
+
+describe('assertSafeAgentName', () => {
+  it('accepts alphanumeric/hyphen/underscore names and the all keyword', () => {
+    expect(() => assertSafeAgentName('my-agent_01')).not.toThrow()
+    expect(() => assertSafeAgentName('all')).not.toThrow()
+  })
+  it('rejects shell metacharacters and over-long names', () => {
+    expect(() => assertSafeAgentName('a;rm -rf')).toThrow(/invalid agent name/)
+    expect(() => assertSafeAgentName('x'.repeat(65))).toThrow(/invalid agent name/)
+  })
+})
+
+describe('formatAuthOutputForTelegram', () => {
+  it('returns a plain pre-block when no URL is present', () => {
+    const { text, url } = formatAuthOutputForTelegram('\x1b[32mno link here\x1b[0m')
+    expect(url).toBeNull()
+    expect(text).toBe('```\nno link here\n```')
+  })
+  it('extracts the URL, drops CLI hint lines, and appends mobile guidance', () => {
+    const raw = [
+      'Started Claude auth for agent overlord',
+      'Open this URL to authorize:',
+      'https://claude.ai/oauth/authorize?code=abc123',
+      'switchroom auth code overlord <code>',
+      'Cancel with: switchroom auth cancel overlord',
+    ].join('\n')
+    const { text, url } = formatAuthOutputForTelegram(raw)
+    expect(url).toBe('https://claude.ai/oauth/authorize?code=abc123')
+    expect(text).not.toContain('switchroom auth code')
+    expect(text).not.toContain('Cancel with:')
+    expect(text).toContain('**Started Claude auth for agent overlord**')
+    expect(text).toContain('_Open this URL to authorize:_')
+    expect(text.trimEnd().endsWith(url as string)).toBe(true)
+  })
+})
+
+describe('keyboards', () => {
+  it('buildAuthUrlKeyboard produces a single url button', () => {
+    const kb = buildAuthUrlKeyboard('https://example.com/x')
+    const rows = kb.inline_keyboard
+    expect(rows).toHaveLength(1)
+    expect(rows[0]).toHaveLength(1)
+    expect(rows[0][0]).toMatchObject({ text: '🔐 Open Claude auth', url: 'https://example.com/x' })
+  })
+  it('buildDeferredSecretKeyboard encodes unlock/cancel callback_data', () => {
+    const kb = buildDeferredSecretKeyboard('123:456')
+    const row = kb.inline_keyboard[0]
+    expect(row.map(b => (b as { callback_data?: string }).callback_data)).toEqual([
+      'vd:unlock:123:456',
+      'vd:cancel:123:456',
+    ])
+  })
+  it('buildDeferredSecretKeyboard throws on a 64-byte callback_data overflow', () => {
+    expect(() => buildDeferredSecretKeyboard('9'.repeat(80))).toThrow(/callback_data overflow/)
+  })
+  it('buildDoctorScopeKeyboard offers fleet and self scopes', () => {
+    const row = buildDoctorScopeKeyboard().inline_keyboard[0]
+    expect(row.map(b => (b as { callback_data?: string }).callback_data)).toEqual([
+      'dr:fleet',
+      'dr:self',
+    ])
+  })
+})
+
+describe('renderVaultOpFailure', () => {
+  it('falls back to a raw pre-block for unrecognised CLI output', () => {
+    const out = renderVaultOpFailure('get', 'some random failure', 'mykey')
+    expect(out).toBe('**vault get failed:**\n```\nsome random failure\n```')
+  })
+  it('routes recognised broker-denied markers through the structured renderer', () => {
+    const out = renderVaultOpFailure('get', 'VAULT-BROKER-DENIED: no grant for key', 'mykey')
+    expect(out).not.toContain('**vault get failed:**')
+    expect(out.length).toBeGreaterThan(0)
+  })
+})
+
+describe('statusIcon', () => {
+  it('maps statuses to glyphs', () => {
+    expect(statusIcon('running')).toBe('🟢')
+    expect(statusIcon('active')).toBe('🟢')
+    expect(statusIcon('stopped')).toBe('🔴')
+    expect(statusIcon('failed')).toBe('⚠️')
+    expect(statusIcon('whatever')).toBe('⚪')
+  })
+})
+
+describe('renderAuthCodeOutcome', () => {
+  it('returns null for success or missing outcome', () => {
+    expect(renderAuthCodeOutcome(null)).toBeNull()
+    expect(renderAuthCodeOutcome({ kind: 'success' } as never)).toBeNull()
+  })
+  it('renders invalid-code with escaped pane tail', () => {
+    const out = renderAuthCodeOutcome({ kind: 'invalid-code', paneTailText: 'bad*code' } as never)
+    expect(out).toContain('Code rejected by Claude')
+    expect(out).toContain('bad\\*code')
+  })
+  it('renders pane-not-ready and timeout variants', () => {
+    expect(renderAuthCodeOutcome({ kind: 'pane-not-ready' } as never)).toContain('Auth pane not ready')
+    expect(renderAuthCodeOutcome({ kind: 'timeout' } as never)).toContain('Still waiting after 2 min')
+  })
+})
+
+describe('formatDoctorReport', () => {
+  it('swaps check glyphs for traffic lights inside a pre block', () => {
+    const raw = '\x1b[32m✓ ok check\x1b[0m\n✗ bad check\n! warn check'
+    expect(formatDoctorReport(raw)).toBe('```\n🟢 ok check\n🔴 bad check\n🟡 warn check\n```')
+  })
+  it('handles empty output', () => {
+    expect(formatDoctorReport('  \x1b[0m ')).toBe('doctor: no output')
+  })
+})

package/telegram-plugin/tests/flushed-turn-supersede.test.ts

@@ -381,3 +381,92 @@ describe('#3429 — decideSupersede new-content gate', () => {
     expect(reg.peek('chat9', undefined, { liveTurnId: 'turn-F', now: now + 21_000 }).reason).toBe('no-record')
   })
 })
+
+/**
+ * The tier discriminator (fix/backstop-duplicate-reply). `positiveAttribution`
+ * lets the gateway bypass the #3429 content gate when the reply's owner turn was
+ * resolved by POSITIVE attribution (live / origin echo / quoted) rather than the
+ * ambiguous latest-ended fallback. On a positive tier a genuinely-DIFFERENT
+ * (reworded) reply for the same turn still supersedes — closing the reworded
+ * same-turn duplicate — while the latest-ended path keeps the content gate so a
+ * true async handback still sends fresh.
+ */
+describe('positiveAttribution — tier-gated content check', () => {
+  const FLUSHED = 'Narration first.\n\nHere is the finished summary of the incident you asked about.'
+  const REWORDED =
+    'So, to wrap up: the incident boiled down to a stale cache entry, and it is fully resolved now.'
+
+  it('positiveAttribution=true: same turn + DIFFERENT (reworded) content STILL supersedes', () => {
+    // Guard: the reworded text is genuinely new vs the flushed blob (would be
+    // declined new-content without the tier bypass).
+    expect(flushedAnswerMatchesReply(FLUSHED, REWORDED)).toBe(false)
+
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(true)
+    expect(d.reason).toBe('supersede')
+    expect(d.deleteMessageIds).toEqual([101, 102])
+  })
+
+  it('positiveAttribution=false (latest-ended): the SAME reworded content declines as new-content', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: REWORDED,
+      positiveAttribution: false,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('new-content')
+  })
+
+  it('positiveAttribution=true still requires turn IDENTITY (different turn never supersedes)', () => {
+    const d = decideSupersede(rec({ turnId: 'turn-A', text: FLUSHED }), {
+      liveTurnId: 'turn-B',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('different-turn')
+  })
+
+  it('positiveAttribution=true still respects the TTL (expired record never supersedes)', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: 1_000_000 + DEFAULT_SUPERSEDE_TTL_MS + 1,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('expired')
+  })
+
+  it('registry take() threads positiveAttribution through to the decision', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    const now = 1_000_000
+    reg.record('chatT', undefined, { turnId: 'turn-Q', messageIds: [8001], text: FLUSHED }, now)
+
+    // latest-ended (positiveAttribution falsey): reworded → new-content, kept.
+    const ambiguous = reg.peek('chatT', undefined, {
+      liveTurnId: 'turn-Q',
+      replyText: REWORDED,
+      now: now + 5_000,
+    })
+    expect(ambiguous.reason).toBe('new-content')
+
+    // positive tier: same reworded reply supersedes and consumes the record.
+    const positive = reg.take('chatT', undefined, {
+      liveTurnId: 'turn-Q',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: now + 6_000,
+    })
+    expect(positive.supersede).toBe(true)
+    expect(positive.deleteMessageIds).toEqual([8001])
+    expect(reg.peek('chatT', undefined, { liveTurnId: 'turn-Q', now: now + 7_000 }).reason).toBe('no-record')
+  })
+})

package/telegram-plugin/tests/gateway-heartbeat.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Gateway liveness heartbeat writer (duplicate-message fix).
+ *
+ * The Stop hook's single-writer election only ALLOWS a stop (handing delivery
+ * to the gateway) when the gateway heartbeat file is fresh. This pins the
+ * writer: it creates the file, bumps its mtime on subsequent touches, and the
+ * hook's freshness reader agrees on the filename + bound.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, existsSync, rmSync, utimesSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import {
+  touchGatewayHeartbeat,
+  startGatewayHeartbeat,
+  GATEWAY_HEARTBEAT_FILE,
+} from '../gateway/gateway-heartbeat.js'
+import {
+  isGatewayHeartbeatFresh,
+  GATEWAY_HEARTBEAT_FILE as HOOK_HEARTBEAT_FILE,
+} from '../hooks/silent-end-scan.mjs'
+
+describe('gateway-heartbeat writer', () => {
+  it('creates the heartbeat file on first touch under a fresh state dir', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'gw-hb-w-'))
+    try {
+      const path = join(dir, GATEWAY_HEARTBEAT_FILE)
+      expect(existsSync(path)).toBe(false)
+      touchGatewayHeartbeat(dir)
+      expect(existsSync(path)).toBe(true)
+      // The hook's freshness reader agrees it's fresh.
+      expect(isGatewayHeartbeatFresh(dir)).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('refreshes an aged heartbeat back to fresh on a subsequent touch', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'gw-hb-w-'))
+    try {
+      const path = join(dir, GATEWAY_HEARTBEAT_FILE)
+      touchGatewayHeartbeat(dir)
+      // Backdate the mtime to stale, then touch again → back to fresh.
+      const old = new Date(Date.now() - 10 * 60_000)
+      utimesSync(path, old, old)
+      expect(isGatewayHeartbeatFresh(dir)).toBe(false)
+      touchGatewayHeartbeat(dir)
+      expect(isGatewayHeartbeatFresh(dir)).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('startGatewayHeartbeat writes immediately and returns an unref-able timer', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'gw-hb-w-'))
+    try {
+      const timer = startGatewayHeartbeat(dir, 60_000)
+      expect(existsSync(join(dir, GATEWAY_HEARTBEAT_FILE))).toBe(true)
+      clearInterval(timer)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('the writer filename and the hook reader filename are identical (no drift)', () => {
+    expect(GATEWAY_HEARTBEAT_FILE).toBe(HOOK_HEARTBEAT_FILE)
+    expect(GATEWAY_HEARTBEAT_FILE).toBe('gateway-heartbeat')
+  })
+})