switchroom 0.19.41 → 0.19.43

package/telegram-plugin/tests/handback-orphan-recovery.test.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs'
+
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  createHandbackOrphanRecovery,
+  formatOrphanEscalation,
+} from '../gateway/handback-orphan-recovery.js'
+import type { HandbackOrphanEscalation, PreTurnCardRecord } from '../gateway/handback-preturn-signal.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+/**
+ * Unit test for the gateway-side EFFECTS of deterministic handback-orphan
+ * recovery, extracted out of gateway.ts (switchroom#2996 ratchet). The seam's
+ * DECISION logic is covered by `handback-preturn-signal.test.ts`; this file
+ * asserts the three effects behave as the seam's contract requires:
+ *
+ *   - a genuine orphan's card is DELETED (never edited to a user-facing string)
+ *   - a delete failure is swallowed, so a reap is never wedged by a Telegram error
+ *   - the handback is re-injected through the pending-inbound buffer verbatim
+ *   - retry exhaustion emits greppable telemetry, NOT a chat message
+ *
+ * Uses injected spies + an injected `writeLog`, so it runs identically under
+ * vitest and bun (no fake timers, no module mocks).
+ */
+
+const record: PreTurnCardRecord = {
+  turnKey: 'preturn:chatA:_:1000',
+  chatId: 'chatA',
+  threadId: 7,
+  activityMessageId: 4242,
+  startedAt: 1000,
+  pinned: false,
+}
+
+const escalation: HandbackOrphanEscalation = {
+  statusKey: 'chatA:7',
+  chatId: 'chatA',
+  threadId: 7,
+  adoptTurnId: 'turn-abc',
+  reinjectCount: 2,
+  ageMs: 90_000,
+}
+
+function inbound(): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: 'chatA',
+    threadId: 7,
+    messageId: 900,
+    text: 'worker finished',
+    meta: { source: 'subagent_handback', handbackReinjectCount: '1' },
+  } as unknown as InboundMessage
+}
+
+describe('handback orphan recovery effects', () => {
+  it('deletes the frozen pre-turn card with its chat/message/thread identity', async () => {
+    const deleteMessage = vi.fn(async () => ({ ok: true }))
+    const r = createHandbackOrphanRecovery({
+      deleteMessage,
+      pushInbound: vi.fn(),
+      writeLog: vi.fn(),
+    })
+
+    await r.deleteCard(record)
+
+    expect(deleteMessage).toHaveBeenCalledTimes(1)
+    expect(deleteMessage).toHaveBeenCalledWith('chatA', 4242, 7)
+  })
+
+  it('swallows a delete failure so the reap is never wedged by a Telegram error', async () => {
+    const deleteMessage = vi.fn(async () => {
+      throw new Error('message to delete not found')
+    })
+    const r = createHandbackOrphanRecovery({
+      deleteMessage,
+      pushInbound: vi.fn(),
+      writeLog: vi.fn(),
+    })
+
+    await expect(r.deleteCard(record)).resolves.toBeUndefined()
+  })
+
+  it('re-injects the orphaned handback verbatim through the pending-inbound buffer', () => {
+    const pushInbound = vi.fn()
+    const r = createHandbackOrphanRecovery({
+      deleteMessage: vi.fn(async () => ({})),
+      pushInbound,
+      writeLog: vi.fn(),
+    })
+
+    const msg = inbound()
+    r.reinjectHandback(msg)
+
+    expect(pushInbound).toHaveBeenCalledTimes(1)
+    // Same object identity: the seam already stamped the retry counter on
+    // `meta`, and this effect must not rebuild or strip the inbound.
+    expect(pushInbound.mock.calls[0]?.[0]).toBe(msg)
+  })
+
+  it('escalates exhausted retries to telemetry with the fleet-health join keys, not to chat', () => {
+    const writeLog = vi.fn()
+    const pushInbound = vi.fn()
+    const deleteMessage = vi.fn(async () => ({}))
+    const r = createHandbackOrphanRecovery({ deleteMessage, pushInbound, writeLog })
+
+    r.escalateOrphan(escalation)
+
+    expect(writeLog).toHaveBeenCalledTimes(1)
+    const line = writeLog.mock.calls[0]?.[0] as string
+    expect(line).toContain('handback orphan escalation')
+    expect(line).toContain('key=chatA:7')
+    expect(line).toContain('turnId=turn-abc')
+    expect(line).toContain('reinjects=2')
+    expect(line).toContain('ageMs=90000')
+    expect(line.endsWith('\n')).toBe(true)
+    // Escalation is telemetry-only: it must not touch any chat transport.
+    expect(deleteMessage).not.toHaveBeenCalled()
+    expect(pushInbound).not.toHaveBeenCalled()
+  })
+
+  it('formatOrphanEscalation is a single line (one log record, not a multi-line blob)', () => {
+    const line = formatOrphanEscalation(escalation)
+    expect(line.trimEnd().split('\n')).toHaveLength(1)
+  })
+
+  it('the operator-facing "needs a nudge" string is gone from the recovery module', () => {
+    const src = readFileSync(new URL('../gateway/handback-orphan-recovery.ts', import.meta.url), 'utf8')
+    expect(src).not.toContain('it may need a nudge')
+  })
+})

package/telegram-plugin/tests/handback-preturn-signal.test.ts

@@ -1,9 +1,13 @@
+import { readFileSync } from 'node:fs'
+
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import {
   createHandbackPreturnSignal,
   isHandbackInbound,
+  HANDBACK_REINJECT_COUNT_META_KEY,
   PRETURN_TURNKEY_PREFIX,
+  type HandbackOrphanEscalation,
   type HandbackPreturnSignalDeps,
   type PreTurnCardRecord,
 } from '../gateway/handback-preturn-signal.js'
@@ -136,9 +140,13 @@ interface Harness {
   sched: ReturnType<typeof makeScheduler>
   sendChatAction: ReturnType<typeof vi.fn>
   openCard: ReturnType<typeof vi.fn>
-  finalizeCard: ReturnType<typeof vi.fn>
+  deleteCard: ReturnType<typeof vi.fn>
+  reinjectHandback: ReturnType<typeof vi.fn>
+  escalateOrphan: ReturnType<typeof vi.fn>
   records: Map<string, PreTurnCardRecord>
-  finalizedIds: number[]
+  deletedIds: number[]
+  reinjected: InboundMessage[]
+  escalations: HandbackOrphanEscalation[]
 }
 
 const harnesses: Harness[] = []
@@ -168,9 +176,19 @@ function makeHarness(overrides: Partial<HandbackPreturnSignalDeps> = {}): Harnes
     if (cur != null && cur.activityMessageId === activityMessageId) records.delete(turnKey)
   }
 
-  const finalizedIds: number[] = []
-  const finalizeCard = vi.fn<(r: PreTurnCardRecord) => void>((r) => {
-    finalizedIds.push(r.activityMessageId)
+  const deletedIds: number[] = []
+  const deleteCard = vi.fn<(r: PreTurnCardRecord) => void>((r) => {
+    deletedIds.push(r.activityMessageId)
+  })
+
+  const reinjected: InboundMessage[] = []
+  const reinjectHandback = vi.fn<(m: InboundMessage) => void>((m) => {
+    reinjected.push(m)
+  })
+
+  const escalations: HandbackOrphanEscalation[] = []
+  const escalateOrphan = vi.fn<(e: HandbackOrphanEscalation) => void>((e) => {
+    escalations.push(e)
   })
 
   const signal = createHandbackPreturnSignal({
@@ -179,7 +197,9 @@ function makeHarness(overrides: Partial<HandbackPreturnSignalDeps> = {}): Harnes
     startTypingLoop: (c, t) => typing.start(c, t),
     stopTypingLoop: (c, t) => typing.stop(c, t),
     openCard,
-    finalizeCard,
+    deleteCard,
+    reinjectHandback,
+    escalateOrphan,
     writeCardRecord,
     clearCardRecord,
     now: sched.now,
@@ -187,10 +207,28 @@ function makeHarness(overrides: Partial<HandbackPreturnSignalDeps> = {}): Harnes
     clearTimer: sched.clearTimer,
     debounceMs: 700,
     adoptTimeoutMs: 30_000,
+    // Default the delivered-window TTL to 0 so tests that exercise the reap
+    // MECHANICS (idle-orphan, #3544 typing, isClaudeBusy gate) see the reap fire
+    // at the adopt timeout exactly as before this fix. Tests that specifically
+    // assert the delivered-but-not-yet-streaming deferral opt into a real TTL.
+    deliveredTtlMs: 0,
     ...overrides,
   })
 
-  const h: Harness = { signal, typing, sched, sendChatAction, openCard, finalizeCard, records, finalizedIds }
+  const h: Harness = {
+    signal,
+    typing,
+    sched,
+    sendChatAction,
+    openCard,
+    deleteCard,
+    reinjectHandback,
+    escalateOrphan,
+    records,
+    deletedIds,
+    reinjected,
+    escalations,
+  }
   harnesses.push(h)
   return h
 }
@@ -283,7 +321,7 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     expect(h.signal.pendingCount()).toBe(0)
   })
 
-  it('never-adopted handback self-reaps its frozen card past the TTL', async () => {
+  it('never-adopted handback self-reaps: DELETES the frozen card and re-injects (deterministic recovery, no nudge)', async () => {
     const h = makeHarness()
     h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatD', messageId: 77 }))
     await h.sched.advance(700)
@@ -291,10 +329,15 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     expect(h.typing.activeCount()).toBe(1)
     expect(h.records.size).toBe(1)
 
-    // No enqueue ever arrives. Past the adopt TTL the orphan self-reaps.
+    // No enqueue ever arrives. Past the adopt TTL the orphan self-reaps into
+    // deterministic recovery: the frozen card is DELETED (never rewritten to a
+    // user-facing "needs a nudge" string) and the handback is re-injected.
     await h.sched.advance(30_000)
 
-    expect(h.finalizedIds).toEqual([resolvedId]) // finalized exactly THAT card
+    expect(h.deletedIds).toEqual([resolvedId]) // deleted exactly THAT card
+    expect(h.reinjected).toHaveLength(1) // re-injected for the machine to recover itself
+    expect(h.reinjected[0]!.meta[HANDBACK_REINJECT_COUNT_META_KEY]).toBe('1')
+    expect(h.escalations).toEqual([]) // first orphan → recover, do NOT escalate
     expect(h.typing.activeCount()).toBe(0) // typing stopped
     expect(h.records.size).toBe(0) // durable record cleared (at-most-once)
     expect(h.signal.pendingCount()).toBe(0) // map empty
@@ -326,18 +369,20 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     // DEFER each time: no false orphan card, entry still live, typing still lit.
     await h.sched.advance(30_000)
     await h.sched.advance(30_000)
-    expect(h.finalizedIds).toEqual([]) // NEVER posted the "never started" nudge
+    expect(h.deletedIds).toEqual([]) // NEVER reaped: card intact
+    expect(h.reinjected).toEqual([]) // NEVER re-injected while enqueued
     expect(h.signal.pendingCount()).toBe(1) // still queued, not reaped
     expect(h.typing.activeCount()).toBe(1) // indicator kept while queued
 
     // The parent turn finally ends and the handback mints its own turn: it
-    // adopts the SAME card (an edit, not a second send / not an orphan finalize).
+    // adopts the SAME card (an edit, not a second send / not an orphan reap).
     busy = false
     const turnId = deriveTurnId('chatBusy', null, 700)!
     const adoption = h.signal.tryAdopt(turnId)
     expect(adoption).not.toBeNull()
     expect(adoption!.activityMessageId).toBe(resolvedId)
-    expect(h.finalizedIds).toEqual([]) // adopted, never finalized as orphan
+    expect(h.deletedIds).toEqual([]) // adopted, never reaped as orphan
+    expect(h.reinjected).toEqual([])
     expect(h.openCard).toHaveBeenCalledTimes(1) // no double-send
     expect(h.signal.pendingCount()).toBe(0)
   })
@@ -345,7 +390,7 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
   // The deferred reap is not a leak: once claude goes idle and the handback has
   // STILL not been adopted (genuine bridge-death / dropped inbound), the re-armed
   // reap finalizes honestly — the degenerate case the reap exists for.
-  it('finalizes a genuine orphan once claude goes idle, even after deferring while busy', async () => {
+  it('recovers a genuine orphan once claude goes idle, even after deferring while busy', async () => {
     let busy = true
     const h = makeHarness({ isClaudeBusy: () => busy })
     h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatIdleOrphan', messageId: 710 }))
@@ -354,19 +399,169 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
 
     // Busy: the first reap defers.
     await h.sched.advance(30_000)
-    expect(h.finalizedIds).toEqual([])
+    expect(h.deletedIds).toEqual([])
+    expect(h.reinjected).toEqual([])
     expect(h.signal.pendingCount()).toBe(1)
 
     // Claude goes idle but NO adopting turn ever mints (the inbound was dropped).
-    // The re-armed reap now finalizes the genuine orphan.
+    // The re-armed reap now recovers the genuine orphan: delete + re-inject.
     busy = false
     await h.sched.advance(30_000)
-    expect(h.finalizedIds).toEqual([resolvedId])
+    expect(h.deletedIds).toEqual([resolvedId])
+    expect(h.reinjected).toHaveLength(1)
     expect(h.typing.activeCount()).toBe(0)
     expect(h.records.size).toBe(0)
     expect(h.signal.pendingCount()).toBe(0)
   })
 
+  // ── #4027 coverage gap: delivered-but-not-yet-streaming is NOT an orphan ──
+  // A handback that WAS delivered into claude's queue but whose adopting turn
+  // has not started streaming yet reads as idle (`isClaudeBusy()` false) + un-
+  // adopted — which #4027 still finalized as a false "needs a nudge" card. The
+  // `deliveredAwaitingTurnStart` gate DEFERS the reap for the whole delivered
+  // TTL. This test FAILS on revert of the gate: without it the reap fires at the
+  // 30 s adopt timeout (idle, un-adopted) and reaps a healthy delivery.
+  it('does NOT reap a delivered-but-not-yet-streaming handback within the delivered TTL', async () => {
+    // Real delivered TTL, no busy signal — the ONLY thing that can defer the
+    // reap here is the delivered-window gate.
+    const h = makeHarness({ deliveredTtlMs: 300_000 })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatDeliv', messageId: 800 }))
+    await h.sched.advance(700)
+    const resolvedId = await h.openCard.mock.results[0]!.value
+    expect(h.records.size).toBe(1)
+
+    // Well past the 30 s adopt timeout but comfortably within the 5 min TTL: the
+    // reap must DEFER every tick — no delete, no re-inject, entry still live,
+    // typing still lit. (Pre-fix this fired a false orphan at 30 s.)
+    await h.sched.advance(120_000)
+    expect(h.deletedIds).toEqual([])
+    expect(h.reinjected).toEqual([])
+    expect(h.escalations).toEqual([])
+    expect(h.signal.pendingCount()).toBe(1)
+    expect(h.typing.activeCount()).toBe(1)
+
+    // The turn finally starts streaming and adopts the SAME card — an edit, not
+    // an orphan reap, and no double-send.
+    const turnId = deriveTurnId('chatDeliv', null, 800)!
+    const adoption = h.signal.tryAdopt(turnId)
+    expect(adoption).not.toBeNull()
+    expect(adoption!.activityMessageId).toBe(resolvedId)
+    expect(h.deletedIds).toEqual([])
+    expect(h.reinjected).toEqual([])
+    expect(h.openCard).toHaveBeenCalledTimes(1)
+    expect(h.signal.pendingCount()).toBe(0)
+  })
+
+  it('reaps a delivered handback ONCE the delivered TTL elapses (deterministic recovery, still no nudge)', async () => {
+    const h = makeHarness({ deliveredTtlMs: 300_000 })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatStuck', messageId: 801 }))
+    await h.sched.advance(700)
+    const resolvedId = await h.openCard.mock.results[0]!.value
+
+    // Within the TTL: deferred.
+    await h.sched.advance(120_000)
+    expect(h.deletedIds).toEqual([])
+
+    // Past the TTL a truly-stuck delivery finally reaps into recovery rather than
+    // hanging forever — delete + re-inject, never a nudge card.
+    await h.sched.advance(210_000)
+    expect(h.deletedIds).toEqual([resolvedId])
+    expect(h.reinjected).toHaveLength(1)
+    expect(h.escalations).toEqual([])
+    expect(h.signal.pendingCount()).toBe(0)
+  })
+
+  // ── deterministic-recovery retry cap: re-inject up to 2×, THEN escalate ──
+  // A genuine orphan whose re-injections keep coming back orphaned must not loop
+  // forever, and must NEVER fall back to a chat nudge. After `maxReinjects` it
+  // escalates to fleet-health telemetry (the `escalateOrphan` sink). The retry
+  // counter rides `HANDBACK_REINJECT_COUNT_META_KEY` on the inbound across the
+  // buffer round trip, so the cap survives the drop-and-recreate of the entry.
+  it('re-injects a persistently-orphaned handback up to the cap, then escalates (never a nudge)', async () => {
+    const sched = makeScheduler()
+    const sendChatAction = vi.fn<(c: string, t: number | null) => void>()
+    const typing = createTurnTypingLoop({
+      sendChatAction,
+      chatKey: (c, t) => chatKey(c, t),
+      refreshMs: 4000,
+    })
+    let msgSeq = 5000
+    const deletedIds: number[] = []
+    const reinjectedCounts: (string | undefined)[] = []
+    const escalations: HandbackOrphanEscalation[] = []
+    const records = new Map<string, PreTurnCardRecord>()
+
+    // eslint-disable-next-line prefer-const
+    let signal: ReturnType<typeof createHandbackPreturnSignal>
+    signal = createHandbackPreturnSignal({
+      chatKey: (c, t) => chatKey(c, t),
+      deriveTurnId,
+      startTypingLoop: (c, t) => typing.start(c, t),
+      stopTypingLoop: (c, t) => typing.stop(c, t),
+      openCard: async () => ++msgSeq,
+      deleteCard: (r) => {
+        deletedIds.push(r.activityMessageId)
+      },
+      // Simulate the buffer round trip: a re-injected orphan comes straight back
+      // through the release chokepoint carrying its stamped retry counter.
+      reinjectHandback: (m) => {
+        reinjectedCounts.push(m.meta[HANDBACK_REINJECT_COUNT_META_KEY])
+        signal.noteHandbackRelease(m)
+      },
+      escalateOrphan: (e) => {
+        escalations.push(e)
+      },
+      writeCardRecord: (r) => {
+        records.set(r.turnKey, r)
+      },
+      clearCardRecord: (turnKey, id) => {
+        const cur = records.get(turnKey)
+        if (cur != null && cur.activityMessageId === id) records.delete(turnKey)
+      },
+      now: sched.now,
+      setTimer: sched.setTimer,
+      clearTimer: sched.clearTimer,
+      debounceMs: 700,
+      adoptTimeoutMs: 30_000,
+      deliveredTtlMs: 0, // no delivered-window deferral: exercise the retry cap directly
+      maxReinjects: 2,
+    })
+
+    try {
+      signal.noteHandbackRelease(handbackInbound({ chatId: 'chatCap', messageId: 802 }))
+      // Drive several reap cycles: each orphan deletes its card, re-injects (up
+      // to the cap), which re-arms the seam via the simulated round trip.
+      await sched.advance(200_000)
+
+      // Exactly 2 re-injections, stamped 1 then 2, then a single escalation.
+      expect(reinjectedCounts).toEqual(['1', '2'])
+      expect(escalations).toHaveLength(1)
+      expect(escalations[0]!.reinjectCount).toBe(2)
+      // One card deleted per orphan cycle (initial + 2 re-injected), never edited
+      // to a "needs a nudge" string.
+      expect(deletedIds).toHaveLength(3)
+      expect(signal.pendingCount()).toBe(0)
+    } finally {
+      typing.stopAll()
+    }
+  })
+
+  // ── the user-facing "needs a nudge" string is GONE from the gateway source ──
+  // Part A of the fix removed the operator-facing card text entirely; the orphan
+  // path now deletes + re-injects. This is a durable regression guard: it FAILS
+  // if the string is reintroduced anywhere in the gateway source.
+  it('the "may need a nudge" user-facing string is absent from the gateway source', () => {
+    const gatewaySrc = readFileSync(
+      new URL('../gateway/gateway.ts', import.meta.url),
+      'utf8',
+    )
+    // The literal user-facing phrase must not appear as a rendered string. (The
+    // only surviving mentions are historical CODE COMMENTS explaining the removal
+    // — assert the load-bearing card fragment is gone from any send/edit call.)
+    expect(gatewaySrc).not.toContain('it may need a nudge')
+    expect(gatewaySrc).not.toContain('HANDBACK_PRETURN_ORPHAN_HTML')
+  })
+
   it('identity race: a user inbound on the same topic never mis-adopts the handback, no double-send', async () => {
     const h = makeHarness()
     h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatE', messageId: 200 }))

package/telegram-plugin/tests/helpers/liveness-wiring-fixture.ts

@@ -154,6 +154,9 @@ export function makeLivenessFixture(
     purgeReactionTracking: () => {},
     getPendingInboundBuffer: () => ({ drain: () => [] }),
     trackRedeliveredInbound: () => {},
+    // Default: no parked store wired (returns 0). Tests exercising the parked
+    // drain override this with the real `drainParkedTurnStartsForChat`.
+    drainParkedTurnStarts: (_chatId: string, _threadId: number | null) => 0,
     closeActivityLane: () => {},
     closeProgressLane: () => {},
     hangRestart: null,

package/telegram-plugin/tests/nested-indent-idiom.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { renderBootCard } from '../gateway/boot-card.js'
+import { renderUpdateOutcomeLine } from '../gateway/update-announce.js'
+import { NESTED_PREFIX } from '../status-no-truncate.js'
+
+/**
+ * #4115 — ONE indent idiom in the repo, and it is the one that actually
+ * renders.
+ *
+ * #3668 fixed the status card's nested lines by moving `NESTED_PREFIX` off
+ * ASCII spaces onto U+2800 BRAILLE PATTERN BLANK: card bodies reach Telegram
+ * as GFM markdown parsed SERVER-SIDE, and that parser left-trims a leading
+ * whitespace run off a content line, so an ASCII (or U+00A0) indent is dropped
+ * on the wire and the line renders FLAT. Live-verified on a phone 2026-07-26 —
+ * the record is on `WORKER_STEP_INDENT` in `status-no-truncate.ts`.
+ *
+ * The boot card and the update-announce line were NOT migrated by that PR, so
+ * they kept shipping the collapsed non-indent to the user. These tests assert
+ * what RENDERS (the leading run survives a server-side left-trim), not merely
+ * that a constant was referenced — a byte-equality assertion against the old
+ * literal is exactly what let the pre-#3668 indent ship green and inert.
+ */
+
+/** Every rule a server-side trimmer could plausibly use. */
+const isTrimmableWhitespace = (ch: string): boolean =>
+  /\s/u.test(ch) || /\p{White_Space}/u.test(ch) || /\p{Zs}/u.test(ch)
+
+/**
+ * The assertion that ties to rendering: after a leading-whitespace left-trim
+ * of the kind Telegram applies, the line STILL carries its full indent, and it
+ * does not lead with either character already proven flat on a phone.
+ */
+function expectSurvivesLeftTrim(line: string): void {
+  expect(line.startsWith(NESTED_PREFIX)).toBe(true)
+  expect(
+    line.replace(/^[\s\p{White_Space}]+/u, '').startsWith(NESTED_PREFIX),
+    `nested line "${line.slice(0, 40)}…" loses its indent to a leading-whitespace trim — ` +
+      `it renders FLAT on a phone (#3668/#4115). Use NESTED_PREFIX.`,
+  ).toBe(true)
+  expect(line.startsWith(' ')).toBe(false)
+  expect(line.startsWith(' ')).toBe(false)
+  const indent = [...line.slice(0, line.indexOf('↳'))]
+  expect(indent.length).toBeGreaterThan(0)
+  for (const ch of indent) expect(isTrimmableWhitespace(ch)).toBe(false)
+}
+
+/** Card lines with the stack's own break chrome removed. */
+function linesOf(card: string): string[] {
+  return card.split('\n').map((l) => l.replace(/[ \t]+$/, ''))
+}
+
+describe('boot card nested lines render as a real indent (#4115)', () => {
+  it("a probe's next-step continuation line survives a server-side left-trim", () => {
+    // Fail-before: this row was `'    ↳ ' + nextStep` — four ASCII spaces, all
+    // of them trimmed, so the line rendered flush against its probe row.
+    const out = renderBootCard({
+      agentName: 'lawgpt',
+      version: 'v0.7.16',
+      probes: {
+        skills: {
+          status: 'degraded',
+          label: 'Skills',
+          detail: '10/10 dangling: a, b, c +7 more',
+          nextStep: 'Run `switchroom agent reconcile lawgpt` to rebuild symlinks',
+        },
+      },
+    })
+    const nested = linesOf(out).filter((l) => l.includes('↳'))
+    expect(nested.length).toBe(1)
+    expectSurvivesLeftTrim(nested[0])
+  })
+
+  it('the crash row tail-logs continuation line survives a server-side left-trim', () => {
+    const out = renderBootCard({
+      agentName: 'lawgpt',
+      version: 'v0.7.16',
+      restartReason: 'crash',
+      restartAgeMs: 6_100,
+    })
+    const nested = linesOf(out).filter((l) => l.includes('↳'))
+    expect(nested.length).toBe(1)
+    expect(nested[0]).toContain('Tail logs:')
+    expectSurvivesLeftTrim(nested[0])
+  })
+})
+
+describe('update-announce recovery line renders as a real indent (#4115)', () => {
+  it('the failure card\'s recovery continuation survives a server-side left-trim', () => {
+    // Fail-before: the recovery row was `'    ↳ Recovery: …'`.
+    const line = renderUpdateOutcomeLine({
+      ts: '2026-05-17T11:59:00.000Z',
+      op: 'update_apply',
+      caller: { kind: 'operator' },
+      request_id: 'req-2',
+      result: 'error',
+      exit_code: 1,
+      duration_ms: 100,
+      phase: 'terminal',
+      stderr_tail: 'compose pull failed: registry timeout',
+      install_context: { install_type: 'binary', detected_at: '2026-05-17T11:00:00Z' },
+    })
+    const nested = linesOf(line).filter((l) => l.includes('↳'))
+    expect(nested.length).toBe(1)
+    expect(nested[0]).toContain('Recovery:')
+    expectSurvivesLeftTrim(nested[0])
+  })
+})
+
+describe('GUARD: no ASCII-space nested indent may reappear in the source (#4115)', () => {
+  // A run of ASCII spaces/tabs immediately before the `↳` nesting glyph — the
+  // exact shape that renders flat. The one exported constant is the only legal
+  // way to indent a nested card line.
+  const ASCII_INDENT_BEFORE_ARROW = /[ \t]{2,}↳/
+
+  const here = fileURLToPath(import.meta.url)
+  const repoRoot = join(here, '..', '..', '..')
+  const ROOTS = ['telegram-plugin', 'src']
+  const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', 'coverage'])
+
+  function walk(dir: string, out: string[]): string[] {
+    for (const name of readdirSync(dir)) {
+      if (SKIP_DIRS.has(name)) continue
+      const p = join(dir, name)
+      if (statSync(p).isDirectory()) walk(p, out)
+      else if (p.endsWith('.ts') && p !== here) out.push(p)
+    }
+    return out
+  }
+
+  it('no source file hardcodes an ASCII-indent-plus-↳ nested line', () => {
+    const offenders: string[] = []
+    for (const root of ROOTS) {
+      for (const file of walk(join(repoRoot, root), [])) {
+        const text = readFileSync(file, 'utf8')
+        text.split('\n').forEach((line, i) => {
+          if (ASCII_INDENT_BEFORE_ARROW.test(line)) {
+            offenders.push(`${relative(repoRoot, file)}:${i + 1}: ${line.trim().slice(0, 100)}`)
+          }
+        })
+      }
+    }
+    expect(
+      offenders,
+      `Hardcoded ASCII indent before a '↳' nesting glyph. Telegram left-trims a leading ` +
+        `ASCII-whitespace run off a content line, so this renders FLAT on a phone (#3668/#4115). ` +
+        `Import NESTED_PREFIX from status-no-truncate.js instead:\n  ${offenders.join('\n  ')}`,
+    ).toEqual([])
+  })
+
+  it('the guard actually fires on the shape it is guarding against', () => {
+    // A guard that cannot fail is not a guard: pin the detector on the exact
+    // literal the two migrated call sites used to carry.
+    expect(ASCII_INDENT_BEFORE_ARROW.test("degradedRows.push(`    ↳ ${next}`)")).toBe(true)
+    expect(ASCII_INDENT_BEFORE_ARROW.test('   ↳ Recovery: reinstall')).toBe(true)
+    // …and stays quiet on the legal idiom and on prose that merely mentions ↳.
+    expect(ASCII_INDENT_BEFORE_ARROW.test(`${NESTED_PREFIX}Recovery: reinstall`)).toBe(false)
+    expect(ASCII_INDENT_BEFORE_ARROW.test('the nested ↳ block is windowed')).toBe(false)
+  })
+})