switchroom 0.14.37 → 0.14.39

package/dist/vault/broker/server.js

@@ -11422,18 +11422,11 @@ var init_schema = __esm(() => {
     webhook_via_gateway: exports_external.boolean().optional().describe("Route verified webhook events to the agent's in-container gateway " + "over a peercred-gated UDS (<agent>/telegram/webhook.sock) instead " + "of having the host-side web receiver write the agent dir directly. " + "Required under the Docker runtime: the receiver runs as the host " + "operator UID and cannot write the per-agent-UID-owned agent dir " + "(EACCES 500) nor connect the gateway socket. When true the gateway " + "(running as the agent UID) becomes the sole writer of " + "webhook-events.jsonl + dedup/cooldown state and also fires " + "webhook_dispatch. Off by default for back-compat with host-runtime " + "installs. See docs/rfcs/webhook-via-gateway-socket.md."),
     webhook_require_edge: exports_external.boolean().optional().describe("Cloudflare-only edge lock: require the X-Switchroom-Edge header " + "(injected by a Cloudflare Transform Rule on hooks.switchroom.ai) to " + "match the operator's edge secret at ~/.switchroom/webhook-edge-secret " + "before any HMAC verification; reject 403 otherwise. Proves the " + "request entered through our Cloudflare edge — the per-agent HMAC " + "alone can't (it proves body provenance, not network path). Stacks " + "on the GitHub-IP WAF + per-agent HMAC. Fail-closed: when required " + "but the secret file is missing/empty every request is rejected. Off " + "by default. See docs/rfcs/webhook-cloudflare-edge-lock.md."),
     chat_id: exports_external.string().regex(/^-\d+$/, 'supergroup chat_id must be a negative integer as a string (e.g. "-1001234567890")').optional().describe("Per-agent supergroup ID — overrides fleet `telegram.forum_chat_id`. " + "When set, requires `default_topic_id`. Negative integer as string. " + "Forbidden when `dm_only: true`. See docs/rfcs/supergroup-mode.md."),
-    default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Required when `chat_id` is set. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field — the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
+    default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Defaults to General (topic 1) when " + "`chat_id` is set and this is omitted — set it only to pin a different " + "fallback topic. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field — the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
     topic_aliases: exports_external.record(exports_external.string(), exports_external.number().int().positive()).optional().describe("Operator-friendly names for forum topic IDs (e.g. " + "`{ general: 1, planning: 17, cron: 23, admin: 31, alerts: 41 }`). " + "Referenced from per-cron `topic:` fields and the outbound router " + "for autonomous events (boot → alerts, hostd → admin, etc.). " + "Cascades per-key through defaults → profile → agent.")
   }).optional().superRefine((tg, ctx) => {
     if (!tg)
       return;
-    if (tg.chat_id != null && tg.default_topic_id == null) {
-      ctx.addIssue({
-        code: exports_external.ZodIssueCode.custom,
-        message: "`channels.telegram.chat_id` requires `default_topic_id` — supergroup-mode agents need a fallback topic for unclassified outbounds.",
-        path: ["default_topic_id"]
-      });
-    }
     if (tg.default_topic_id != null && tg.chat_id == null) {
       ctx.addIssue({
         code: exports_external.ZodIssueCode.custom,
@@ -11448,6 +11441,11 @@ var init_schema = __esm(() => {
         path: ["topic_aliases"]
       });
     }
+  }).transform((tg) => {
+    if (tg && tg.chat_id != null && tg.default_topic_id == null) {
+      return { ...tg, default_topic_id: 1 };
+    }
+    return tg;
   });
   ChannelsSchema = exports_external.object({
     telegram: TelegramChannelSchema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.37",
+  "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

@@ -23807,18 +23807,11 @@ var init_schema = __esm(() => {
     webhook_via_gateway: exports_external.boolean().optional().describe("Route verified webhook events to the agent's in-container gateway " + "over a peercred-gated UDS (<agent>/telegram/webhook.sock) instead " + "of having the host-side web receiver write the agent dir directly. " + "Required under the Docker runtime: the receiver runs as the host " + "operator UID and cannot write the per-agent-UID-owned agent dir " + "(EACCES 500) nor connect the gateway socket. When true the gateway " + "(running as the agent UID) becomes the sole writer of " + "webhook-events.jsonl + dedup/cooldown state and also fires " + "webhook_dispatch. Off by default for back-compat with host-runtime " + "installs. See docs/rfcs/webhook-via-gateway-socket.md."),
     webhook_require_edge: exports_external.boolean().optional().describe("Cloudflare-only edge lock: require the X-Switchroom-Edge header " + "(injected by a Cloudflare Transform Rule on hooks.switchroom.ai) to " + "match the operator's edge secret at ~/.switchroom/webhook-edge-secret " + "before any HMAC verification; reject 403 otherwise. Proves the " + "request entered through our Cloudflare edge \u2014 the per-agent HMAC " + "alone can't (it proves body provenance, not network path). Stacks " + "on the GitHub-IP WAF + per-agent HMAC. Fail-closed: when required " + "but the secret file is missing/empty every request is rejected. Off " + "by default. See docs/rfcs/webhook-cloudflare-edge-lock.md."),
     chat_id: exports_external.string().regex(/^-\d+$/, 'supergroup chat_id must be a negative integer as a string (e.g. "-1001234567890")').optional().describe("Per-agent supergroup ID \u2014 overrides fleet `telegram.forum_chat_id`. " + "When set, requires `default_topic_id`. Negative integer as string. " + "Forbidden when `dm_only: true`. See docs/rfcs/supergroup-mode.md."),
-    default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Required when `chat_id` is set. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field \u2014 the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
+    default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Defaults to General (topic 1) when " + "`chat_id` is set and this is omitted \u2014 set it only to pin a different " + "fallback topic. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field \u2014 the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
     topic_aliases: exports_external.record(exports_external.string(), exports_external.number().int().positive()).optional().describe("Operator-friendly names for forum topic IDs (e.g. " + "`{ general: 1, planning: 17, cron: 23, admin: 31, alerts: 41 }`). " + "Referenced from per-cron `topic:` fields and the outbound router " + "for autonomous events (boot \u2192 alerts, hostd \u2192 admin, etc.). " + "Cascades per-key through defaults \u2192 profile \u2192 agent.")
   }).optional().superRefine((tg, ctx) => {
     if (!tg)
       return;
-    if (tg.chat_id != null && tg.default_topic_id == null) {
-      ctx.addIssue({
-        code: exports_external.ZodIssueCode.custom,
-        message: "`channels.telegram.chat_id` requires `default_topic_id` \u2014 supergroup-mode agents need a fallback topic for unclassified outbounds.",
-        path: ["default_topic_id"]
-      });
-    }
     if (tg.default_topic_id != null && tg.chat_id == null) {
       ctx.addIssue({
         code: exports_external.ZodIssueCode.custom,
@@ -23833,6 +23826,11 @@ var init_schema = __esm(() => {
         path: ["topic_aliases"]
       });
     }
+  }).transform((tg) => {
+    if (tg && tg.chat_id != null && tg.default_topic_id == null) {
+      return { ...tg, default_topic_id: 1 };
+    }
+    return tg;
   });
   ChannelsSchema = exports_external.object({
     telegram: TelegramChannelSchema
@@ -51796,10 +51794,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.37";
-var COMMIT_SHA = "90d0c420";
-var COMMIT_DATE = "2026-06-02T02:10:03Z";
-var LATEST_PR = 2078;
+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)', () => {