switchroom 0.14.38 → 0.14.40

package/telegram-plugin/hooks/subagent-tracker-pretool.mjs

@@ -191,6 +191,24 @@ function writeRow(dbPath, { id, parentSessionId, parentTurnKey, agentType, descr
           db.exec('ALTER TABLE subagents ADD COLUMN jsonl_agent_id TEXT')
           db.exec('CREATE INDEX IF NOT EXISTS subagents_jsonl_id ON subagents(jsonl_agent_id)')
         }
+        // Verify the marker-derived parent_turn_key (snapParams[2]) actually has
+        // a row in the turns table before trusting it. The gateway writes the
+        // turn-active marker even when recordTurnStart's INSERT failed (the two
+        // writes have independent failure surfaces), so a marker can name a
+        // turn_key with no turns row. Stamping that phantom key would route the
+        // worker card to the operator DM AND block the watcher's NULL-guarded
+        // window backfill from recovering it. Downgrade to NULL so the backfill
+        // stays eligible — this also defends against a stale/corrupted marker.
+        if (snapParams[2] != null) {
+          let turnRow = null
+          try {
+            turnRow = db.prepare('SELECT 1 FROM turns WHERE turn_key = ? LIMIT 1').get(snapParams[2])
+          } catch {
+            // turns table may not exist yet on a brand-new agent — treat as no row.
+            turnRow = null
+          }
+          if (turnRow == null) snapParams[2] = null
+        }
         db.prepare(snapInsertSql).run(...snapParams)
         db.close()
         done(null)
@@ -202,12 +220,65 @@ function writeRow(dbPath, { id, parentSessionId, parentTurnKey, agentType, descr
   }
 
   // sqlite3 CLI fallback — two non-blocking spawns sequenced via callbacks.
+  // This legacy path (neither node:sqlite nor bun:sqlite available) can't
+  // cheaply verify the marker's turn_key against the turns table, so drop
+  // parent_turn_key and let the gateway's window backfill attribute it.
+  // Production agents use node:sqlite; bun test uses bun:sqlite — both take
+  // the verified path above.
+  params[2] = null
   spawnSql(dbPath, SCHEMA_SQL.replace(/\n\s+/g, ' '), (err) => {
     if (err) { done(err); return }
     spawnSql(dbPath, fillPlaceholders(INSERT_SQL.trim(), params), done)
   })
 }
 
+// ---------------------------------------------------------------------------
+// Active-turn resolution (the parent_turn_key the row belongs to)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the gateway's turn-active marker to learn the turn_key of the turn that
+ * is active *right now* — the turn whose tool call is dispatching this
+ * sub-agent. The gateway writes `<TELEGRAM_STATE_DIR>/turn-active.json`
+ * synchronously at turn-start (gateway/turn-active-marker.ts), keyed
+ * `{turnKey, chatId, threadId, startedAt}`, and removes it at turn-complete.
+ * `telegramDir` here resolves to that same `TELEGRAM_STATE_DIR` in production
+ * (verified: identical inode to the registry.db dir), so the marker is a
+ * sibling of registry.db.
+ *
+ * Stamping parent_turn_key from this marker at INSERT time — instead of
+ * leaving it NULL for the gateway to reconstruct from a started_at time-window
+ * at jsonl-link time — fixes two bugs:
+ *   - #2081: the time-window backfill mis-attributes when turn windows overlap
+ *     (supergroup forum topics multiplex many concurrent turns under one
+ *     chat_id; `ended_at` is unreliable/batch-swept). The live marker is the
+ *     ground truth for "which turn dispatched this", so there is nothing to
+ *     reconstruct and no overlap to disambiguate.
+ *   - #2083: the backfill only runs when a sub-agent's JSONL links; ~8% never
+ *     link and were never attributed. Stamping at INSERT is independent of
+ *     linking.
+ *
+ * `turnKey` equals `turns.turn_key` (both minted by chatKeyWithSuffix at
+ * turn-start), so resolveSubagentOriginChat()'s getTurnByKey() finds the exact
+ * (chat_id, thread_id) and routes the worker card to the originating topic.
+ *
+ * Best-effort: if no turn is active (no marker — e.g. a sub-agent dispatched
+ * outside a turn) or the marker is unreadable/malformed, return null and let
+ * the gateway's started_at backfill remain the fallback (today's behaviour).
+ * Never throws; never blocks the tool call.
+ */
+function readActiveTurnKey(telegramDir) {
+  try {
+    // Mirrors TURN_ACTIVE_MARKER_FILE in gateway/turn-active-marker.ts.
+    const raw = readFileSync(join(telegramDir, 'turn-active.json'), 'utf8')
+    const marker = JSON.parse(raw)
+    const turnKey = marker?.turnKey
+    return typeof turnKey === 'string' && turnKey.length > 0 ? turnKey : null
+  } catch {
+    return null
+  }
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -257,22 +328,22 @@ function main() {
   }
 
   const input = event.tool_input ?? {}
+  // Resolve parent_turn_key from the live turn-active marker (the turn whose
+  // tool call is dispatching this sub-agent). Claude Code's PreToolUse payload
+  // carries only its own session id, never the gateway-minted Telegram turn_key
+  // — but the gateway writes that turn_key to <telegramDir>/turn-active.json
+  // for the duration of the turn, so we read it directly here. Stamping it at
+  // INSERT (vs leaving NULL for the gateway's started_at time-window backfill)
+  // fixes overlapping-window mis-attribution (#2081) and attributes sub-agents
+  // whose JSONL never links (#2083). NULL when no turn is active → the gateway
+  // backfill remains the fallback. See readActiveTurnKey().
+  const parentTurnKey = readActiveTurnKey(telegramDir)
   writeRow(
     dbPath,
     {
       id: event.tool_use_id ?? null,
       parentSessionId: event.session_id ?? null,
-      // parent_turn_key is intentionally NULL here. Claude Code's PreToolUse
-      // payload carries its own session id, not the gateway-minted Telegram
-      // turn_key (a chat+topic+turn key) the `turns` table is keyed on —
-      // `event.turn_id` is always undefined, and even if a future CLI
-      // populated it, it would not match a `turns.turn_key`. The gateway
-      // resolves parent_turn_key from the
-      // sub-agent's started_at at jsonl-link time (subagent-watcher.ts
-      // backfillJsonlAgentId), which works even after the parent turn ends.
-      // Writing a bogus value here would defeat that backfill's
-      // `parent_turn_key IS NULL` guard.
-      parentTurnKey: null,
+      parentTurnKey,
       agentType: input.subagent_type ?? null,
       description: input.description ?? null,
       background: input.run_in_background === true ? 1 : 0,

package/telegram-plugin/registry/subagents-bugs.test.ts

@@ -12,7 +12,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
-import { mkdtempSync, mkdirSync, rmSync } from 'fs'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { spawnSync } from 'child_process'
@@ -385,26 +385,62 @@ describe('Bug 4 — result_summary always NULL (hook integration)', () => {
   })
 })
 
-// ─── Bug 5 — parent_turn_key always NULL ─────────────────────────────────────
-
-describe('Bug 5 — parent_turn_key backfilled by gateway, not the hook', () => {
-  it('pretool writes parent_turn_key=NULL even when event.turn_id is present', () => {
-    // Claude Code's PreToolUse payload carries its own session id, never the
-    // gateway-minted Telegram turn_key (a chat+topic+turn key) the `turns`
-    // table is keyed on. `event.turn_id` — even if a future CLI populated it —
-    // would not match a `turns.turn_key`, so the hook intentionally writes
-    // NULL and lets the gateway backfill parent_turn_key from the sub-agent's
-    // started_at at jsonl-link time (subagent-watcher.ts backfillJsonlAgentId).
-    // Writing a bogus value here would defeat that backfill's
-    // `parent_turn_key IS NULL` guard.
+// ─── Bug 5 — parent_turn_key stamped from the live turn-active marker ─────────
+// (#2081 / #2083) The PreToolUse hook reads <telegramDir>/turn-active.json —
+// the gateway-written marker for the turn whose tool call is dispatching this
+// sub-agent — and stamps parent_turn_key = marker.turnKey at INSERT. This
+// captures the EXACT active turn (no started_at time-window reconstruction at
+// jsonl-link time), so it can't mis-attribute under overlapping turn windows
+// (#2081) and works even for sub-agents whose JSONL never links (#2083).
+
+/** Write the gateway's turn-active marker into the agent's telegram dir. */
+function writeTurnActiveMarker(turnKey: string, chatId = '12345', threadId: string | null = null) {
+  writeFileSync(
+    join(agentDir, 'telegram', 'turn-active.json'),
+    JSON.stringify({ turnKey, chatId, threadId, startedAt: Date.now() }, null, 2) + '\n',
+  )
+}
+
+/**
+ * Seed a turns row so the hook's phantom-turn_key guard (it only stamps a
+ * marker turn_key that actually has a turns row) is satisfied. In production
+ * the gateway writes this row via recordTurnStart at turn-start.
+ */
+function seedTurn(turnKey: string, chatId = '12345', threadId: string | null = null) {
+  const { Database } = require('bun:sqlite') as {
+    Database: new (path: string) => {
+      prepare(sql: string): { run(...p: unknown[]): unknown }
+      exec(sql: string): void
+      close(): void
+    }
+  }
+  const db = new Database(dbPath)
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS turns (
+      turn_key TEXT PRIMARY KEY, chat_id TEXT, thread_id TEXT,
+      started_at INTEGER, ended_at INTEGER, created_at INTEGER, updated_at INTEGER
+    )`,
+  )
+  const now = Date.now()
+  db.prepare(
+    'INSERT OR IGNORE INTO turns (turn_key, chat_id, thread_id, started_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)',
+  ).run(turnKey, chatId, threadId, now, now, now)
+  db.close()
+}
+
+describe('Bug 5 — parent_turn_key stamped from the turn-active marker', () => {
+  it('stamps parent_turn_key = marker.turnKey when a turn is active', () => {
+    // Supergroup forum-topic turn_key (chat:thread:startedAt).
+    const turnKey = '-1003831053471:4:1780370238492'
+    seedTurn(turnKey, '-1003831053471', '4')
+    writeTurnActiveMarker(turnKey, '-1003831053471', '4')
+
     const event = {
       session_id: 'sess-turnkey',
-      turn_id: 'turn-abc-001',
       tool_name: 'Agent',
       tool_use_id: 'toolu_turnkey001',
       tool_input: { description: 'Task with turn context', run_in_background: false },
     }
-
     const result = runHook(PRETOOL_SCRIPT, event)
     expect(result.status).toBe(0)
 
@@ -414,18 +450,43 @@ describe('Bug 5 — parent_turn_key backfilled by gateway, not the hook', () =>
       | undefined
 
     expect(row).toBeDefined()
-    // The hook never trusts event.turn_id — gateway backfill owns this column.
+    expect(row!.parent_turn_key).toBe(turnKey)
+  })
+
+  it('downgrades to NULL when the marker names a turn_key with no turns row (phantom-marker guard)', () => {
+    // The gateway writes the marker even if recordTurnStart's INSERT failed, so
+    // a marker can point at a turn_key with no row. Stamping it would mis-route
+    // the worker card AND block the watcher backfill (NULL guard). The hook must
+    // verify the row exists and fall back to NULL.
+    seedTurn('12345:_:1780000000000') // a DIFFERENT, real turn exists…
+    writeTurnActiveMarker('12345:_:9999999999999') // …but the marker names a phantom.
+
+    const event = {
+      session_id: 'sess-phantom',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_phantom001',
+      tool_input: { description: 'Task', run_in_background: false },
+    }
+    const result = runHook(PRETOOL_SCRIPT, event)
+    expect(result.status).toBe(0)
+
+    const db = openDb()
+    const row = db.prepare('SELECT parent_turn_key FROM subagents WHERE id = ?').get('toolu_phantom001') as
+      | { parent_turn_key: string | null }
+      | undefined
+    expect(row).toBeDefined()
     expect(row!.parent_turn_key).toBeNull()
   })
 
-  it('pretool stores parent_turn_key as NULL when turn_id absent (no regression)', () => {
+  it('writes parent_turn_key=NULL when no turn is active (gateway backfill fallback)', () => {
+    // No marker written → no active turn → hook leaves NULL and the gateway's
+    // started_at backfill remains the fallback (today's behaviour).
     const event = {
       session_id: 'sess-noturnkey',
       tool_name: 'Agent',
       tool_use_id: 'toolu_noturn001',
       tool_input: { description: 'Task without turn context', run_in_background: false },
     }
-
     runHook(PRETOOL_SCRIPT, event)
 
     const db = openDb()
@@ -434,7 +495,47 @@ describe('Bug 5 — parent_turn_key backfilled by gateway, not the hook', () =>
       | undefined
 
     expect(row).toBeDefined()
-    // When no turn_id in event, parent_turn_key should be NULL — no crash
+    expect(row!.parent_turn_key).toBeNull()
+  })
+
+  it('ignores event.turn_id — only the marker is authoritative', () => {
+    // A future CLI populating event.turn_id must NOT be trusted: it is Claude
+    // Code's session turn, never a gateway turns.turn_key. With no marker the
+    // result is NULL regardless of turn_id.
+    const event = {
+      session_id: 'sess-turnid-only',
+      turn_id: 'turn-abc-001',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_turnid001',
+      tool_input: { description: 'Task', run_in_background: false },
+    }
+    runHook(PRETOOL_SCRIPT, event)
+
+    const db = openDb()
+    const row = db.prepare('SELECT parent_turn_key FROM subagents WHERE id = ?').get('toolu_turnid001') as
+      | { parent_turn_key: string | null }
+      | undefined
+
+    expect(row).toBeDefined()
+    expect(row!.parent_turn_key).toBeNull()
+  })
+
+  it('a malformed marker degrades to NULL (never crashes the dispatch)', () => {
+    writeFileSync(join(agentDir, 'telegram', 'turn-active.json'), '{ not valid json')
+    const event = {
+      session_id: 'sess-badmarker',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_badmarker001',
+      tool_input: { description: 'Task', run_in_background: false },
+    }
+    const result = runHook(PRETOOL_SCRIPT, event)
+    expect(result.status).toBe(0)
+
+    const db = openDb()
+    const row = db.prepare('SELECT parent_turn_key FROM subagents WHERE id = ?').get('toolu_badmarker001') as
+      | { parent_turn_key: string | null }
+      | undefined
+    expect(row).toBeDefined()
     expect(row!.parent_turn_key).toBeNull()
   })
 

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

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  ackDelivery,
+  createDeliveryQueue,
+  forgetDelivery,
+  sweep,
+  trackDelivery,
+  type DeliveryQueue,
+} from '../gateway/inbound-delivery-confirm.js'
+
+/**
+ * Regression coverage for the marko drop-wedge.
+ *
+ * An inbound delivered to claude's TUI composer strands unsubmitted when the
+ * auto-submit races turn-completion. claude never emits `enqueue`, so the
+ * gateway used to sit "typing…" for 300s then DROP the message.
+ *
+ * The queue's contract: a delivered inbound is acked ONLY by `enqueue`; until
+ * then it is re-delivered every `timeoutMs`, forever, never dropped — and an
+ * acked delivery never re-fires (no duplicate turns).
+ */
+type Msg = { text: string }
+const TIMEOUT = 15_000
+
+function fresh(): DeliveryQueue<Msg> {
+  return createDeliveryQueue<Msg>()
+}
+
+describe('inbound-delivery-confirm (reliable deliver-until-acked queue)', () => {
+  it('an acked delivery is never re-delivered (happy path — no duplicate turns)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'hi' }, 1_000)
+    expect(ackDelivery(q, 'chat:_')).toBe(true) // enqueue arrived
+    expect(sweep(q, 1_000 + 999_999, TIMEOUT)).toHaveLength(0)
+    expect(q.pending.size).toBe(0)
+  })
+
+  it('within the timeout, an un-acked delivery is left alone (claude may still be picking it up)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'hi' }, 1_000)
+    expect(sweep(q, 1_000 + 14_999, TIMEOUT)).toHaveLength(0)
+    expect(q.pending.size).toBe(1)
+  })
+
+  it('a strand (no ack) is re-delivered after the timeout, and the clock resets', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'draft nurture email' }, 1_000)
+    const r = sweep(q, 1_000 + 15_000, TIMEOUT)
+    expect(r).toHaveLength(1)
+    expect(r[0]!.inbound.text).toBe('draft nurture email')
+    expect(r[0]!.lastAttemptAt).toBe(1_000 + 15_000) // clock reset
+    // not re-swept until another full timeout elapses
+    expect(sweep(q, 1_000 + 15_000 + 14_999, TIMEOUT)).toHaveLength(0)
+  })
+
+  it('keeps re-delivering forever until acked — never drops (the reliability invariant)', () => {
+    const q = fresh()
+    let t = 0
+    trackDelivery(q, 'chat:_', { text: 'x' }, t)
+    for (let i = 0; i < 50; i++) {
+      t += 15_000
+      expect(sweep(q, t, TIMEOUT)).toHaveLength(1) // still trying after 50 strands
+    }
+    expect(q.pending.size).toBe(1) // never dropped
+    // claude finally picks it up → acked → stops.
+    expect(ackDelivery(q, 'chat:_')).toBe(true)
+    expect(sweep(q, t + 999_999, TIMEOUT)).toHaveLength(0)
+  })
+
+  it('an ack that lands right after a re-delivery stops further re-delivery (no duplicate turns)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'x' }, 0)
+    sweep(q, 15_000, TIMEOUT) // strand → re-delivered
+    expect(ackDelivery(q, 'chat:_')).toBe(true) // the re-delivered copy landed
+    expect(sweep(q, 999_999, TIMEOUT)).toHaveLength(0)
+    expect(q.pending.size).toBe(0)
+  })
+
+  it('keys are independent — a strand on one topic does not affect another (DM + supergroup topics)', () => {
+    const q = fresh()
+    trackDelivery(q, '-100:4', { text: 'crm topic msg' }, 0) // supergroup CRM topic
+    trackDelivery(q, '555:_', { text: 'dm msg' }, 0) // a DM
+    ackDelivery(q, '555:_') // the DM submits fine
+    const r = sweep(q, 15_000, TIMEOUT)
+    expect(r).toHaveLength(1)
+    expect(r[0]!.key).toBe('-100:4') // only the stranded topic re-delivers
+  })
+
+  it('tracking the same key twice keeps only the latest inbound (gate serialises per key)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'first' }, 0)
+    trackDelivery(q, 'chat:_', { text: 'second' }, 100)
+    expect(q.pending.size).toBe(1)
+    expect(sweep(q, 100 + 15_000, TIMEOUT)[0]!.inbound.text).toBe('second')
+  })
+
+  it('ack on an unknown key is a harmless no-op', () => {
+    expect(ackDelivery(fresh(), 'never-tracked')).toBe(false)
+  })
+
+  it('forgetDelivery clears without acking or re-delivering (bridge went offline)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'x' }, 0)
+    forgetDelivery(q, 'chat:_')
+    expect(q.pending.size).toBe(0)
+    expect(sweep(q, 999_999, TIMEOUT)).toHaveLength(0)
+  })
+})

package/telegram-plugin/tests/subagent-tracker-hooks.test.ts

@@ -344,6 +344,117 @@ describe('subagent-tracker-posttool', () => {
     expect(row?.background).toBe(0)
     expect(row?.status).toBe('completed')
   })
+
+  // ─── async-launch ACK contract — drift tolerance (#2084) ────────────────────
+  // Tier 3 of isAsyncLaunchAck keys on the functional `agentId: <stem>` token
+  // (the most wording-stable part of the ACK) so promotion survives a
+  // claude-code bump that rewords BOTH the launch verb AND the "working in the
+  // background" phrase. The context-word requirement keeps it from tripping on
+  // a foreground report that merely mentions an agentId.
+  it('promotes on reworded ACK prose when the agentId token + a context word survive', () => {
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-drift',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_drift1',
+      tool_input: { subagent_type: 'worker', description: 'Drifted ACK' },
+    })
+    // Neither "async agent launched" nor "working in the background" — a
+    // hypothetical reworded ACK — but the agentId token + "background" remain.
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_drift1',
+      tool_response: {
+        content: [{ type: 'text', text: 'Background worker started.\nagentId: drift-7f3a91\nYou will be notified when it finishes.' }],
+      },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).not.toContain('additionalContext')
+
+    const db = openDb()
+    const row = db.prepare('SELECT background, status, ended_at FROM subagents WHERE id = ?').get('toolu_drift1') as
+      | { background: number; status: string; ended_at: number | null }
+      | undefined
+    expect(row?.background).toBe(1)
+    expect(row?.status).toBe('running')
+    expect(row?.ended_at == null).toBe(true)
+  })
+
+  it('does NOT promote when an agentId token appears without any launch/background context word', () => {
+    // A genuine foreground report mentioning an agentId in passing — no
+    // launch/background/async/dispatch word — must terminalize, not promote.
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-falsepos',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_falsepos1',
+      tool_input: { subagent_type: 'worker', description: 'Foreground lookup', run_in_background: false },
+    })
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_falsepos1',
+      tool_response: { result: 'Done. Verified the record; agentId: svc-42 is valid and active.', is_error: false },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).toContain('additionalContext')
+
+    const db = openDb()
+    const row = db.prepare('SELECT background, status FROM subagents WHERE id = ?').get('toolu_falsepos1') as
+      | { background: number; status: string }
+      | undefined
+    expect(row?.background).toBe(0)
+    expect(row?.status).toBe('completed')
+  })
+
+  it('does NOT promote a foreground orchestrator narrative that embeds an agentId mid-sentence', () => {
+    // The #2085-review false-positive: a coordinator agent reporting on other
+    // agents. The agentId is mid-sentence (not on its own line), so tier 3's
+    // own-line anchor rejects it even though "background"/"dispatching" appear.
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-orch',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_orch1',
+      tool_input: { subagent_type: 'worker', description: 'Coordinator', run_in_background: false },
+    })
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_orch1',
+      tool_response: { result: 'agentId: coord-x is managing background work and dispatching checks.', is_error: false },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).toContain('additionalContext')
+
+    const db = openDb()
+    const row = db.prepare('SELECT background, status FROM subagents WHERE id = ?').get('toolu_orch1') as
+      | { background: number; status: string }
+      | undefined
+    expect(row?.background).toBe(0)
+    expect(row?.status).toBe('completed')
+  })
+
+  it('does NOT promote an own-line agentId with no launch/background context word (boundary)', () => {
+    // Documents the accepted tier-3 boundary: an own-line bare agentId alone
+    // (no background/launch/dispatch/async/notify word) is not enough to
+    // promote — guards a foreground report that prints an id on its own line.
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-bound',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_bound1',
+      tool_input: { subagent_type: 'worker', description: 'Infra', run_in_background: false },
+    })
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_bound1',
+      tool_response: { content: [{ type: 'text', text: 'Created the worker.\nagentId: svc-99\nIt is ready.' }] },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).toContain('additionalContext')
+
+    const db = openDb()
+    const row = db.prepare('SELECT background, status FROM subagents WHERE id = ?').get('toolu_bound1') as
+      | { background: number; status: string }
+      | undefined
+    expect(row?.background).toBe(0)
+    expect(row?.status).toBe('completed')
+  })
 })
 
 describe('agent-dir resolution (RFC §Bug 2)', () => {

package/telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts

@@ -153,3 +153,53 @@ describe('backfillJsonlAgentId — parent_turn_key resolution', () => {
     expect(row?.parent_turn_key == null).toBe(true)
   })
 })
+
+// ─── #2081: overlapping windows + hook-stamped value precedence ───────────────
+// The backfill is now only a FALLBACK — the PreToolUse hook stamps
+// parent_turn_key from the live turn-active marker at dispatch
+// (subagent-tracker-pretool.mjs readActiveTurnKey). These tests pin the two
+// guarantees that make the hook fix correct end-to-end.
+describe('backfillJsonlAgentId — overlapping windows / hook precedence (#2081)', () => {
+  it('does NOT overwrite a hook-stamped parent_turn_key, even when overlapping windows would resolve differently', () => {
+    // Supergroup: two forum topics under one chat with OVERLAPPING windows.
+    // Topic A (thread 4) started first and is still open; topic B (thread 7)
+    // started later. A sub-agent dispatched at 1500 falls inside BOTH windows.
+    insertTurn({ turnKey: '-100:4:1000', chatId: '-100', threadId: '4', startedAt: 1000, endedAt: null })
+    insertTurn({ turnKey: '-100:7:1400', chatId: '-100', threadId: '7', startedAt: 1400, endedAt: null })
+
+    // The hook already stamped the CORRECT parent (topic A) from the marker.
+    insertSub({
+      id: 'toolu_overlap',
+      agentType: 'worker',
+      description: 'Topic-A worker',
+      startedAt: 1500,
+      parentTurnKey: '-100:4:1000',
+    })
+
+    const jsonlPath = writeMeta('worker', 'Topic-A worker')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_overlap')
+
+    const row = readSub('toolu_overlap')
+    expect(row?.jsonl_agent_id).toBe('agentstem_overlap')
+    // The IS NULL guard means the hook's correct value survives — NOT the
+    // window query's ORDER BY started_at DESC pick (which would be topic B).
+    expect(row?.parent_turn_key).toBe('-100:4:1000')
+  })
+
+  it('fallback window-match (NULL parent) picks the latest-started overlapping turn — the documented fallback limitation', () => {
+    // When the hook left parent_turn_key NULL (no active marker at dispatch),
+    // the backfill falls back to the started_at window match. With overlapping
+    // windows it resolves to the latest-started containing turn. This is a
+    // best-effort fallback for the no-marker case — the hook path above is the
+    // correct primary. Pinned here so the fallback behaviour is explicit.
+    insertTurn({ turnKey: '-100:4:1000', chatId: '-100', threadId: '4', startedAt: 1000, endedAt: null })
+    insertTurn({ turnKey: '-100:7:1400', chatId: '-100', threadId: '7', startedAt: 1400, endedAt: null })
+    insertSub({ id: 'toolu_fallback', agentType: 'worker', description: 'No-marker worker', startedAt: 1500 })
+
+    const jsonlPath = writeMeta('worker', 'No-marker worker')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_fallback')
+
+    const row = readSub('toolu_fallback')
+    expect(row?.parent_turn_key).toBe('-100:7:1400')
+  })
+})

package/telegram-plugin/uat/scenarios/inbound-no-drop-rapid-fire-dm.test.ts

@@ -0,0 +1,64 @@
+/**
+ * E2E regression — inbound is NEVER dropped under rapid fire (the drop-wedge).
+ *
+ * The bug: a Telegram inbound reaches claude as an MCP channel notification
+ * the unmodified CLI appends to its composer and auto-submits only when the
+ * composer is empty + idle. A message arriving the instant the prior turn
+ * completes races that auto-submit and strands unsubmitted — claude never
+ * starts the turn, the gateway sits "typing…", and the 300s silence-poke
+ * DROPS the message. Observed recurring on `marko` (supergroup topics + DMs).
+ *
+ * This scenario drives the exact failure timing: it fires each message the
+ * instant the prior reply lands (i.e. right at turn-completion, the strand
+ * window) and asserts EVERY message gets its own unique token back. With the
+ * deliver-until-acked queue (inbound-delivery-confirm.ts) a strand self-heals
+ * via re-delivery; without it, a stranded message yields NO reply within the
+ * timeout and this test fails on exactly the message that was swallowed.
+ *
+ * Each message carries a random token and the assertion matches THAT token,
+ * so a reply to message N-1 can never be mistaken for message N's reply — the
+ * test proves every distinct message was actually processed, not merely that
+ * "some replies came back".
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+
+describe("uat: rapid-fire inbound — no message is ever dropped (drop-wedge)", () => {
+  it(
+    "every back-to-back message gets its own reply (delivery never strands)",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const N = 8;
+        const dropped: number[] = [];
+        for (let i = 1; i <= N; i++) {
+          const token = `acktok-${i}-${Math.random().toString(36).slice(2, 8)}`;
+          await sc.sendDM(
+            `Reply with exactly this token and nothing else: ${token}`,
+          );
+          try {
+            const reply = await sc.expectMessage((m) => m.text.includes(token), {
+              from: "bot",
+              timeout: 75_000,
+            });
+            expect(reply.text).toContain(token);
+          } catch {
+            // The message stranded — no reply carrying its token arrived.
+            dropped.push(i);
+          }
+          // Deliberately NO delay: fire the next message the instant this
+          // reply lands, so it arrives in the turn-completion strand window.
+        }
+        expect(
+          dropped,
+          `messages dropped (no reply within timeout): ${dropped.join(", ")} of ${N}`,
+        ).toEqual([]);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    // N messages × (turn + up to one ~15-20s strand recovery) — generous.
+    900_000,
+  );
+});