switchroom 0.19.38 → 0.19.40

package/telegram-plugin/tests/queued-card-surface.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Part B (#3927 follow-up) — the queued-turn card.
+ *
+ * Since #3927 a genuinely-queued mid-turn message is PARKED with no surface at
+ * all until it dequeues: on the machine-authoritative path the legacy Hook A
+ * placeholder never fires (it lives in the buffer-until-idle branch that returns
+ * before the machine enqueues). These tests assert the fix's lifecycle against
+ * the REAL `handleSessionEvent`:
+ *
+ *   • park    → a "⏳ Queued" card is posted ONCE, reply-anchored to the parked
+ *               message, in the envelope's own chat/thread.
+ *   • dequeue → the SAME card id is adopted as the turn's activityMessageId and
+ *               EDITED in place (not re-sent) — one continuous lifecycle.
+ *   • remove  → the card is finalized as "folded into the current task".
+ *   • TTL     → the card is finalized as timed-out, never left frozen.
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  handleSessionEvent,
+  __resetParkedTurnStartsForTest,
+  __parkedTurnStartCountForTest,
+} from '../gateway/stream-render.js'
+import { makeHarness, enqueue, CHAT, type Harness } from './turn-mint-harness.js'
+import { deriveTurnId } from '../gateway/derive-turn-id.js'
+
+interface SendRec { chatId: string; markdown: string; opts: Record<string, unknown>; id: number }
+interface EditRec { chatId: string; messageId: number; markdown: string }
+interface DelRec { chatId: string; messageId: number }
+
+/** Attach a recording bot to a harness so the queued-card send/edit/delete calls
+ *  are observable. `sendRichMessage` returns an incrementing message id. */
+function withRecordingBot(h: Harness) {
+  const sends: SendRec[] = []
+  const edits: EditRec[] = []
+  const deletes: DelRec[] = []
+  let nextId = 9001
+  ;(h.deps as unknown as { bot: unknown }).bot = {
+    api: {
+      sendRichMessage: async (chatId: string, msg: { markdown: string }, opts: Record<string, unknown>) => {
+        const id = nextId++
+        sends.push({ chatId, markdown: msg.markdown, opts, id })
+        return { message_id: id }
+      },
+      editMessageText: async (chatId: string, messageId: number, msg: { markdown: string }) => {
+        edits.push({ chatId, messageId, markdown: msg.markdown })
+        return true
+      },
+      deleteMessage: async (chatId: string, messageId: number) => {
+        deletes.push({ chatId, messageId })
+        return true
+      },
+    },
+  }
+  return { sends, edits, deletes }
+}
+
+/** Flush the microtask + macrotask queue so the async card send's `.then` (which
+ *  stores the card id on the parked envelope) has run. */
+const settle = () => new Promise((r) => setTimeout(r, 0))
+
+beforeEach(() => {
+  __resetParkedTurnStartsForTest()
+})
+
+describe('Part B — queued card is posted at park and adopted on dequeue', () => {
+  it('parks with a reply-anchored "Queued" card, then EDITS that same card in place on dequeue', async () => {
+    const h = makeHarness()
+    const rec = withRecordingBot(h)
+
+    // Turn A mints on an idle session.
+    handleSessionEvent(h.deps, enqueue('501'))
+    const turnA = h.current()!
+    expect(rec.sends).toHaveLength(0) // idle mint posts no queued card
+
+    // Message B arrives mid-turn → parks → queued card is posted ONCE.
+    handleSessionEvent(h.deps, enqueue('502', 'also check the vault'))
+    await settle()
+    expect(__parkedTurnStartCountForTest()).toBe(1)
+    expect(rec.sends).toHaveLength(1)
+    const card = rec.sends[0]!
+    expect(card.markdown).toContain('Queued')
+    // Reply-anchored to B's own message id, in B's chat.
+    expect((card.opts.reply_parameters as { message_id: number }).message_id).toBe(502)
+    expect(card.chatId).toBe('1001')
+
+    // Turn A ends; the CLI drains the queue → B mints and ADOPTS the card.
+    turnA.endedAt = Date.now()
+    handleSessionEvent(h.deps, { kind: 'dequeue' })
+    const turnB = h.current()!
+    expect(turnB).not.toBe(turnA)
+    expect(turnB.sourceMessageId).toBe(502)
+    // The queued card became the live progress card — same id, adopted in place.
+    expect(turnB.activityMessageId).toBe(card.id)
+    expect(turnB.activityEverOpened).toBe(true)
+    // No SECOND card was ever sent (edited in place, not re-posted).
+    expect(rec.sends).toHaveLength(1)
+  })
+
+  it('posts one card PER envelope (multiple queued messages each get their own)', async () => {
+    const h = makeHarness()
+    const rec = withRecordingBot(h)
+
+    handleSessionEvent(h.deps, enqueue('601'))
+    handleSessionEvent(h.deps, enqueue('602'))
+    handleSessionEvent(h.deps, enqueue('603'))
+    await settle()
+    expect(__parkedTurnStartCountForTest()).toBe(2)
+    expect(rec.sends).toHaveLength(2)
+    expect(new Set(rec.sends.map((s) => s.id)).size).toBe(2)
+  })
+})
+
+describe('Part B — queued card is finalized, never frozen', () => {
+  it('finalizes the card as "folded" when the message is removed (folded into the running turn)', async () => {
+    const h = makeHarness()
+    const rec = withRecordingBot(h)
+
+    handleSessionEvent(h.deps, enqueue('701'))
+    const queued = enqueue('702', 'while you are in there…')
+    handleSessionEvent(h.deps, queued)
+    await settle()
+    expect(rec.sends).toHaveLength(1)
+    const cardId = rec.sends[0]!.id
+
+    handleSessionEvent(h.deps, { kind: 'queue_remove', rawContent: queued.rawContent })
+    expect(__parkedTurnStartCountForTest()).toBe(0)
+    // The card was edited (finalized) in place — folded, not left on "Queued".
+    expect(rec.edits).toHaveLength(1)
+    expect(rec.edits[0]!.messageId).toBe(cardId)
+    expect(rec.edits[0]!.markdown).toContain('Folded')
+  })
+
+  it('finalizes the card as timed-out on TTL expiry (a dequeue that never arrives)', async () => {
+    // Runner-agnostic: the TTL prune reads wall-clock `Date.now()` (it is NOT a
+    // scheduled setTimeout), so we drive it by advancing `Date.now` around the
+    // dequeue rather than a vitest-only fake-timer API (`vi.runAllTimersAsync`
+    // is absent under bun — the same reason handback-preturn-signal.test.ts
+    // injects its own scheduler). `parkedAt` is stamped with the REAL clock at
+    // park; only the prune's `now` is advanced, so the entry ages past the TTL.
+    const h = makeHarness()
+    const rec = withRecordingBot(h)
+
+    handleSessionEvent(h.deps, enqueue('1201'))
+    const turnA = h.current()!
+    handleSessionEvent(h.deps, enqueue('1202'))
+    await settle() // real microtask/macrotask flush → the card id lands on the entry
+    expect(rec.sends).toHaveLength(1)
+    const cardId = rec.sends[0]!.id
+
+    // 31 minutes pass with neither dequeue nor remove; a stray dequeue prunes it.
+    const realNow = Date.now
+    Date.now = () => realNow() + 31 * 60_000
+    try {
+      turnA.endedAt = Date.now()
+      handleSessionEvent(h.deps, { kind: 'dequeue' })
+    } finally {
+      Date.now = realNow
+    }
+    await settle()
+
+    expect(__parkedTurnStartCountForTest()).toBe(0)
+    expect(h.current()).toBe(turnA) // 1202 was NOT minted 31 min late
+    expect(rec.edits).toHaveLength(1)
+    expect(rec.edits[0]!.messageId).toBe(cardId)
+    expect(rec.edits[0]!.markdown).toContain('timed out')
+  })
+})
+
+/**
+ * Regression for the handback-while-busy MAJOR (adversarial review of #4040).
+ *
+ * The COMMON worker-handoff case: a worker hands back while the parent session
+ * is busy → the handback pre-turn signal arms a card for that turn → the same
+ * handback inbound parks → (before the fix) the park posted a SECOND "⏳ Queued"
+ * card unconditionally → on dequeue the handback `tryAdopt` won the surface, so
+ * the Part B `activityMessageId == null` guard was false and the queued card was
+ * neither adopted nor finalized → TWO cards for one message, the queued one
+ * FROZEN forever.
+ *
+ * The shared harness hardcodes `HANDBACK_PRETURN_ENABLED:false` +
+ * `tryAdopt:()=>null`, so it never exercised this; here we turn the signal ON
+ * with a card-bearing `tryAdopt`, matching prod. Both tests fail on the current
+ * HEAD (a queued card is posted and then frozen) and pass after the fix.
+ */
+const HANDBACK_CARD_ID = 7777
+
+/** Turn the handback pre-turn signal ON for message `msgId`'s turn. `pendingAtPark`
+ *  models whether `noteHandbackRelease` has already armed the entry by the time the
+ *  message parks (true = the common case; false = the sub-second race the beginTurn
+ *  safety net covers). `tryAdopt` always returns the handback card for that turn. */
+function withHandbackFor(h: Harness, msgId: string, pendingAtPark: boolean) {
+  const tid = deriveTurnId(CHAT, null, msgId)!
+  const d = h.deps as unknown as {
+    HANDBACK_PRETURN_ENABLED: boolean
+    handbackPreturnSignal: {
+      hasPendingForTurnId: (t: string) => boolean
+      tryAdopt: (t: string) => { activityMessageId: number | null; statusKey: string } | null
+    }
+  }
+  d.HANDBACK_PRETURN_ENABLED = true
+  d.handbackPreturnSignal = {
+    hasPendingForTurnId: (t: string) => pendingAtPark && t === tid,
+    tryAdopt: (t: string) =>
+      t === tid ? { activityMessageId: HANDBACK_CARD_ID, statusKey: `${CHAT}:main` } : null,
+  }
+  return tid
+}
+
+describe('Part B — handback-while-busy: exactly one card, never a frozen "Queued"', () => {
+  it('SUPPRESSES the queued card at park when a handback signal already owns the turn (common case)', async () => {
+    const h = makeHarness()
+    const rec = withRecordingBot(h)
+    withHandbackFor(h, '502', /* pendingAtPark */ true)
+
+    // Turn A mints on an idle session.
+    handleSessionEvent(h.deps, enqueue('501'))
+    const turnA = h.current()!
+
+    // The handback inbound (502) parks while A is busy. The handback signal
+    // already owns 502's surface → NO queued card is posted.
+    handleSessionEvent(h.deps, enqueue('502', 'handback: worker done'))
+    await settle()
+    expect(rec.sends).toHaveLength(0) // ← fails on HEAD (a 2nd card was posted)
+
+    // A ends → 502 dequeues → adopts the HANDBACK card as its one surface.
+    turnA.endedAt = Date.now()
+    handleSessionEvent(h.deps, { kind: 'dequeue' })
+    const turnB = h.current()!
+    expect(turnB.activityMessageId).toBe(HANDBACK_CARD_ID)
+    // No queued card was ever posted, edited, or left frozen.
+    expect(rec.sends).toHaveLength(0)
+    expect(rec.edits).toHaveLength(0)
+    expect(rec.deletes).toHaveLength(0)
+  })
+
+  it('DELETES the orphaned queued card at dequeue when the handback armed after park (the race)', async () => {
+    const h = makeHarness()
+    const rec = withRecordingBot(h)
+    withHandbackFor(h, '502', /* pendingAtPark */ false)
+
+    handleSessionEvent(h.deps, enqueue('501'))
+    const turnA = h.current()!
+
+    // 502 parks BEFORE the handback entry armed → the queued card is posted.
+    handleSessionEvent(h.deps, enqueue('502', 'handback: worker done'))
+    await settle()
+    expect(rec.sends).toHaveLength(1)
+    const queuedCardId = rec.sends[0]!.id
+
+    // A ends → 502 dequeues → the handback adoption WINS the surface, and the
+    // now-orphaned queued card is DELETED so it never freezes on "⏳ Queued".
+    turnA.endedAt = Date.now()
+    handleSessionEvent(h.deps, { kind: 'dequeue' })
+    const turnB = h.current()!
+    expect(turnB.activityMessageId).toBe(HANDBACK_CARD_ID) // handback card is the surface
+    expect(rec.deletes).toHaveLength(1) // ← fails on HEAD (no cleanup, card frozen)
+    expect(rec.deletes[0]!.messageId).toBe(queuedCardId)
+    // One live card total: the handback card. The queued card was removed, not
+    // left as a frozen "Queued" and not finalized as folded/timed-out.
+    expect(rec.edits).toHaveLength(0)
+  })
+})

package/telegram-plugin/tests/send-reply-golden.test.ts

@@ -547,6 +547,53 @@ describe('deliverCapturedProse — silent-end recovery (routed into the send mod
     expect(h.calls).toHaveLength(0)
   })
 
+  it('PERSIST PARITY: the exhausted-boundary plain-text fallback records the recovered answer to history', async () => {
+    // #3228 exhausted-boundary: the rich send fails on the attempt where the
+    // re-prompt budget is already spent, so deliverCapturedProse delivers the
+    // real answer as PLAIN text. Pre-fix that plain-text delivery recorded only
+    // to the in-memory dedup and NEVER called recordOutbound — so the recovered
+    // answer reached the user but was silently absent from history.db. This
+    // asserts recordOutbound now fires once with the delivered message_id + the
+    // recovered text.
+    const dedup = new OutboundDedupCache()
+    // Rich send parse-rejects (one chunk → one queued failure); the plain
+    // sendMessage fallback succeeds.
+    const { api, calls } = makeFakeBot({ sendRichMessage: [grammy400("can't parse entities")] })
+    const recorded: Array<{ chat_id: string; thread_id: number | null; message_ids: number[]; texts: string[] }> = []
+    const text = 'The exhausted-boundary recovered answer.'
+    const deps: DeliverCapturedProseDeps = {
+      outboundDedup: dedup,
+      bot: { api } as unknown as DeliverCapturedProseDeps['bot'],
+      robustApiCall: (fn) => fn(),
+      redactOutboundText: (t) => redact(t),
+      recordOutbound: (rec) => recorded.push({ chat_id: rec.chat_id, thread_id: rec.thread_id, message_ids: rec.message_ids, texts: rec.texts }),
+      HISTORY_ENABLED: true,
+      OBLIGATION_LEDGER_ENABLED: true,
+      obligationLedger: { close: () => {} },
+      clearSilentEndState: () => {},
+      // Budget already spent → the fallback path fires.
+      recordUndeliveredTurnEnd: () => ({ exhausted: true }),
+      hasOutboundDeliveredSince: () => false,
+    }
+    await deliverCapturedProse(deps, {
+      chatId: CHAT,
+      threadId: undefined,
+      statusKeyStr: `${CHAT}:main`,
+      registryKey: null,
+      originTurnId: 'turn-45',
+      text,
+    })
+    // The plain-text fallback actually delivered.
+    const plainSends = calls.filter((c) => c.method === 'sendMessage')
+    expect(plainSends).toHaveLength(1)
+    expect(plainSends[0]!.text).toBe(text)
+    // …and it was persisted to history exactly once with the delivered id + text.
+    expect(recorded).toHaveLength(1)
+    expect(recorded[0]!.chat_id).toBe(CHAT)
+    expect(recorded[0]!.message_ids).toEqual([plainSends[0]!.message_id])
+    expect(recorded[0]!.texts).toEqual([text])
+  })
+
   it('already-deduped content settles bookkeeping WITHOUT a wire send', async () => {
     const dedup = new OutboundDedupCache()
     const text = 'Already went out earlier via the stream.'

package/telegram-plugin/tests/sidechain-label-filter-pretool.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Regression: the PreToolUse hook must NOT write labels for SIDECHAIN
+ * (sub-agent) tool calls into the parent session's sidecar.
+ *
+ * The bug (log-verified): Claude Code fires PreToolUse for sub-agent tool
+ * calls too, and passes the PARENT `session_id`. The hook wrote the worker's
+ * label into `tool-labels-<parentSession>.jsonl`; the gateway's real-time
+ * draft-mirror tails that file and emits a main-tier `tool_label` event per
+ * line, binding it to whatever turn is live — so a still-running background
+ * worker dispatched by the PREVIOUS turn streamed its Bash step labels into an
+ * unrelated new turn's progress card, and inflated that turn's
+ * `labeledToolCount` / re-armed its orphaned-reply fuse.
+ *
+ * The fix severs the chain at its cheapest, at-source link: the hook drops
+ * sidechain calls, so a sub-agent `toolUseId` never reaches the parent sidecar
+ * → never becomes a `tool_label` event → never touches an unrelated card.
+ * These tests assert that OUTCOME (no foreign sidecar line), plus the pure
+ * predicate that distinguishes main-tier from sub-agent payloads.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+// The hook exports isSubagentToolCall for unit testing (see the "Skip main()
+// when imported" guard at the bottom of the hook).
+import { isSubagentToolCall, hasAttributionSignal } from '../hooks/tool-label-pretool.mjs'
+
+const HOOK_PATH = resolve(__dirname, '..', 'hooks', 'tool-label-pretool.mjs')
+const FIXTURE_DIR = resolve(__dirname, 'fixtures')
+
+/** Load a committed real-shape PreToolUse fixture (see the drift-canary block). */
+function loadFixture(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(FIXTURE_DIR, name), 'utf8'))
+}
+
+/** Run the hook once with a payload; return the sidecar file's lines (if any). */
+function runHook(payload: Record<string, unknown>): {
+  stateDir: string
+  lines: string[]
+  sidecarPath: string
+  stderr: string
+} {
+  const stateDir = mkdtempSync(join(tmpdir(), 'sidechain-label-'))
+  const sessionId = String(payload.session_id ?? 'sess')
+  const sidecarPath = join(stateDir, `tool-labels-${sessionId}.jsonl`)
+  const res = spawnSync(process.execPath, [HOOK_PATH], {
+    input: JSON.stringify(payload),
+    env: { ...process.env, TELEGRAM_STATE_DIR: stateDir },
+    encoding: 'utf8',
+  })
+  // The hook must always exit 0 (exit 2 would BLOCK the tool call).
+  expect(res.status).toBe(0)
+  const lines = existsSync(sidecarPath)
+    ? readFileSync(sidecarPath, 'utf8').split('\n').filter(Boolean)
+    : []
+  return { stateDir, lines, sidecarPath, stderr: res.stderr ?? '' }
+}
+
+describe('isSubagentToolCall — main-tier vs sidechain discrimination', () => {
+  it('treats agent_type "main" as main-tier (keep)', () => {
+    expect(isSubagentToolCall({ agent_type: 'main', agent_id: 's1', session_id: 's1' })).toBe(false)
+  })
+
+  it('treats an ABSENT agent_type as main-tier (safe default — keep)', () => {
+    expect(isSubagentToolCall({ session_id: 's1' })).toBe(false)
+    expect(isSubagentToolCall({ agent_id: 's1', session_id: 's1' })).toBe(false)
+  })
+
+  it('flags every concrete non-"main" agent_type as sidechain (drop)', () => {
+    for (const at of ['worker', 'general-purpose', 'Explore', 'Plan', 'researcher', 'my-custom-agent']) {
+      expect(isSubagentToolCall({ agent_type: at, session_id: 'parent' })).toBe(true)
+    }
+  })
+
+  it('flags a distinct agent_id (sub-agent id ≠ parent session) as sidechain', () => {
+    // Corroborating signal even if agent_type were somehow absent.
+    expect(isSubagentToolCall({ agent_id: 'sub-abc', session_id: 'parent-xyz' })).toBe(true)
+  })
+
+  it('does not flag main when agent_id equals session_id', () => {
+    expect(isSubagentToolCall({ agent_id: 'same', session_id: 'same' })).toBe(false)
+  })
+
+  it('is robust to a null/undefined event', () => {
+    expect(isSubagentToolCall(null)).toBe(false)
+    expect(isSubagentToolCall(undefined)).toBe(false)
+  })
+})
+
+describe('PreToolUse hook — sidechain calls never reach the parent sidecar', () => {
+  it('writes a sidecar line for a MAIN-tier Bash call', () => {
+    const { stateDir, lines } = runHook({
+      session_id: 'parent-sess',
+      tool_use_id: 'toolu_main_1',
+      tool_name: 'Bash',
+      tool_input: { command: 'git status', description: 'Check status' },
+      agent_type: 'main',
+      agent_id: 'parent-sess',
+    })
+    try {
+      expect(lines.length).toBe(1)
+      const row = JSON.parse(lines[0])
+      expect(row.tool_use_id).toBe('toolu_main_1')
+      expect(row.label).toBe('Check status')
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+
+  it('DROPS a sub-agent Bash call (no line in the parent sidecar)', () => {
+    // The exact shape of the log-verified bug: a background worker's Bash call,
+    // carrying the PARENT session_id but a "worker" agent_type.
+    const { stateDir, lines, sidecarPath } = runHook({
+      session_id: 'parent-sess',
+      tool_use_id: 'toolu_worker_9',
+      tool_name: 'Bash',
+      tool_input: { command: 'npm run build', description: 'Build the worker output' },
+      agent_type: 'worker',
+      agent_id: 'sub-agent-42',
+    })
+    try {
+      // No sidecar row at all → the draft-mirror never emits a foreign
+      // tool_label → the live turn's card / labeledToolCount / fuse are
+      // untouched. This is the regression that would have caught the bug.
+      expect(lines.length).toBe(0)
+      expect(existsSync(sidecarPath)).toBe(false)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+
+  it('DROPS a sub-agent call flagged only by a distinct agent_id', () => {
+    const { stateDir, lines } = runHook({
+      session_id: 'parent-sess',
+      tool_use_id: 'toolu_worker_10',
+      tool_name: 'Read',
+      tool_input: { file_path: '/etc/hosts' },
+      agent_id: 'sub-agent-77',
+    })
+    try {
+      expect(lines.length).toBe(0)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+})
+
+/**
+ * DRIFT CANARY — the compile-time half.
+ *
+ * The hand-built payloads above all use the field NAMES this reviewer round
+ * happened to expect (`agent_type`, `agent_id`). If a future Claude Code
+ * renamed BOTH (e.g. `agent_type`→`agentType`), those tests would stay green
+ * while the hook silently fails open and the cross-turn contamination bug
+ * returns. These two fixtures are the REAL 2.1.219 PreToolUse shape, verified
+ * field-by-field against the installed binary's base `Kf(...)` hook-input
+ * builder:
+ *   { session_id, transcript_path, cwd, prompt_id?, permission_mode,
+ *     agent_id, agent_type, effort?, hook_event_name, tool_name, tool_input,
+ *     tool_use_id }
+ * Piping the genuine object shape through the real hook proves the predicate
+ * works against what claude actually emits (not a mental model of it), and
+ * pins the field names so a rename that reaches these fixtures fails CI. The
+ * runtime WARNING below covers the residual case (a live CLI drift the frozen
+ * fixture can't see).
+ */
+describe('drift canary — real 2.1.219 PreToolUse payload shape', () => {
+  it('DROPS a genuine sub-agent payload (full Kf shape) — zero sidecar lines, no file', () => {
+    const fixture = loadFixture('pretool-subagent-2.1.219.json')
+    // Sanity: the fixture really is a sidechain shape (parent session_id, own
+    // agent_id, concrete agent_type) — if a maintainer refreshes it from a
+    // future CLI and the schema moved, this predicate assertion trips first.
+    expect(isSubagentToolCall(fixture)).toBe(true)
+    const { stateDir, lines, sidecarPath } = runHook(fixture)
+    try {
+      expect(lines.length).toBe(0)
+      expect(existsSync(sidecarPath)).toBe(false)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+
+  it('KEEPS a genuine main-tier payload (full Kf shape) — one sidecar line', () => {
+    const fixture = loadFixture('pretool-main-2.1.219.json')
+    expect(isSubagentToolCall(fixture)).toBe(false)
+    const { stateDir, lines } = runHook(fixture)
+    try {
+      expect(lines.length).toBe(1)
+      const row = JSON.parse(lines[0])
+      expect(row.tool_use_id).toBe('toolu_01MainReadCall4z')
+      expect(row.label).toBe('Reading index.ts')
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+})
+
+/**
+ * SYMMETRIC FALSE-POSITIVE guard — an explicit "main" must win over identity.
+ *
+ * The predicate's identity fallback (`agent_id !== session_id` ⇒ sidechain)
+ * must never override an explicit `agent_type: "main"`. If a FUTURE main-tier
+ * payload stopped setting `agent_id === session_id`, the old ordering would
+ * have wrongly DROPPED legit main labels (the whole live feed for that turn).
+ */
+describe('agent_type "main" is authoritative — never a false-positive drop', () => {
+  it('KEEPS a "main" payload even when agent_id differs from session_id', () => {
+    expect(
+      isSubagentToolCall({ agent_type: 'main', agent_id: 'different-id', session_id: 's1' }),
+    ).toBe(false)
+    const { stateDir, lines } = runHook({
+      session_id: 's1',
+      tool_use_id: 'toolu_main_diverged',
+      tool_name: 'Read',
+      tool_input: { file_path: '/x/y.ts' },
+      agent_type: 'main',
+      agent_id: 'different-id',
+    })
+    try {
+      expect(lines.length).toBe(1)
+      expect(JSON.parse(lines[0]).tool_use_id).toBe('toolu_main_diverged')
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+})
+
+/**
+ * FAIL-LOUD guard — a payload with NEITHER identity field is anomalous on
+ * 2.1.219 and means the schema may have drifted out from under the predicate.
+ * The hook must warn (so plugin-logger surfaces it) but NOT drop (dropping
+ * every label on drift would dark-out the whole feed).
+ */
+describe('hasAttributionSignal + the schema-drift warning', () => {
+  it('hasAttributionSignal is true with either field, false with neither', () => {
+    expect(hasAttributionSignal({ agent_type: 'main' })).toBe(true)
+    expect(hasAttributionSignal({ agent_id: 'x' })).toBe(true)
+    expect(hasAttributionSignal({ agent_type: '', agent_id: '' })).toBe(false)
+    expect(hasAttributionSignal({ session_id: 's1', tool_use_id: 't' })).toBe(false)
+    expect(hasAttributionSignal(null)).toBe(false)
+  })
+
+  it('WARNS but still writes when a real tool call carries neither agent_type nor agent_id', () => {
+    const { stateDir, lines, stderr } = runHook({
+      session_id: 's1',
+      tool_use_id: 'toolu_no_attribution',
+      tool_name: 'Read',
+      tool_input: { file_path: '/x/y.ts' },
+      // No agent_type, no agent_id — the both-fields-dropped drift scenario.
+    })
+    try {
+      // Loud: the drift warning fires (plugin-logger tails stderr)…
+      expect(stderr).toContain('sidechain-attribution invariant may be')
+      // …but NOT dropped — main-tier labels still flow so the feed isn't dark.
+      expect(lines.length).toBe(1)
+      expect(JSON.parse(lines[0]).tool_use_id).toBe('toolu_no_attribution')
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+
+  it('does NOT warn on a normal 2.1.219 payload (both fields present)', () => {
+    const { stateDir, stderr } = runHook(loadFixture('pretool-main-2.1.219.json'))
+    try {
+      expect(stderr).not.toContain('sidechain-attribution invariant may be')
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+})