switchroom 0.14.38 → 0.14.39

package/dist/cli/switchroom.js

@@ -49438,8 +49438,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.38";
-var COMMIT_SHA = "1529105b";
+var VERSION = "0.14.39";
+var COMMIT_SHA = "fb30b654";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.38",
+  "version": "0.14.39",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {
@@ -23,9 +23,9 @@
     "build": "node scripts/build.mjs",
     "build:cli": "node scripts/build.mjs && bun build --compile --target=bun-linux-x64 --minify bin/switchroom.ts --outfile switchroom-linux-amd64",
     "pretest": "npm run build",
-    "test": "vitest run && bun test telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts",
+    "test": "vitest run && bun test telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts",
     "test:vitest": "vitest run",
-    "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts src/vault/grants.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts",
+    "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts src/vault/grants.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts",
     "test:watch": "vitest",
     "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs",
     "lint:tsc": "tsc --noEmit",

package/telegram-plugin/dist/gateway/gateway.js

@@ -51794,10 +51794,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.38";
-var COMMIT_SHA = "1529105b";
-var COMMIT_DATE = "2026-06-02T02:25:47Z";
-var LATEST_PR = 2079;
+var VERSION = "0.14.39";
+var COMMIT_SHA = "fb30b654";
+var COMMIT_DATE = "2026-06-02T05:46:22Z";
+var LATEST_PR = 2086;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

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

@@ -188,18 +188,53 @@ function toolResponseText(toolResponse) {
  * parent turn, so the pretool recorded background=0 and the worker card never
  * fired). We therefore trust this ACK over the pretool's input-derived flag.
  *
- * Anchored on the specific "async agent launched" phrase (a foreground
- * sub-agent's final report is extremely unlikely to contain it), with a
- * structural backstop ("working in the background" + an agentId token) in case
- * the launch-verb wording drifts. A major wording change degrades to the
- * pretool flag — still correct whenever the model DID pass run_in_background,
- * never worse than before.
+ * Three tiers, widest-stable-signal last, so a Claude Code wording change has
+ * to defeat ALL of them before promotion silently regresses (#2084):
+ *
+ *   1. The canonical ACK phrase "async agent launched" — the exact current
+ *      claude-code wording. A foreground report is extremely unlikely to
+ *      contain it.
+ *   2. Structural backstop: the background-status phrase "working in the
+ *      background" + an agentId token. Survives a reworded launch verb.
+ *   3. Drift-tolerant STRUCTURAL match: `agentId: <stem>` as a bare identifier
+ *      on its OWN LINE — the functional, most wording-stable core of the ACK
+ *      (the parent references the worker by this id). claude-code emits it on
+ *      its own line; a foreground report that merely names an agent id embeds
+ *      it mid-sentence ("the agentId is X is managing …"), which the own-line
+ *      anchor rejects. Paired with a launch/background/async/dispatch/notify
+ *      context word so it can't trip on a foreground report that happens to
+ *      print a bare id on its own line. This survives BOTH prose phrases
+ *      (tiers 1 & 2) rewording in the same bump.
+ *
+ * If all three miss, promotion degrades to the pretool's input-derived flag —
+ * still correct whenever the model DID pass run_in_background, never worse than
+ * before. The exact ACK contract is pinned by drift-variant tests in
+ * subagent-tracker-hooks.test.ts ("async-launch ACK contract"); when bumping
+ * the pinned claude-code version, re-verify the live ACK against those.
+ *
+ * Known residual (accepted): an ACK reword that BOTH drops the own-line id
+ * form AND removes every context word degrades to the pretool flag; a
+ * foreground report that prints a bare `agentId: <id>` on its own line next to
+ * a launch/background word would false-promote. Both are narrow; the own-line
+ * + context-word conjunction is the balance point. Re-verify on a pin bump.
+ *
+ * ACK contract verified against claude-code 2.1.156 (the fleet pin):
+ *   "Async agent launched successfully.\n
+ *    agentId: <stem>\n
+ *    The agent is working in the background. You will be notified
+ *    automatically when it completes."
  */
 function isAsyncLaunchAck(toolResponse) {
   const t = toolResponseText(toolResponse).toLowerCase()
   if (!t) return false
   if (t.includes('async agent launched')) return true
   if (t.includes('working in the background') && t.includes('agentid')) return true
+  // Tier 3 — own-line `agentid: <bare-stem>` + a context word (leading \b so
+  // reworded/derived forms like "launched"/"dispatching"/"notified" still
+  // count). `m` flag anchors $ to line end so a mid-sentence id is rejected.
+  if (/agentid:\s*[a-z0-9][\w-]*\s*$/m.test(t) && /\b(background|launch|dispatch|async|notif)/.test(t)) {
+    return true
+  }
   return false
 }
 

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/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')
+  })
+})