switchroom 0.14.36 → 0.14.38

package/dist/agent-scheduler/index.js

@@ -11101,18 +11101,11 @@ var TelegramChannelSchema = exports_external.object({
   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,
@@ -11127,6 +11120,11 @@ var TelegramChannelSchema = exports_external.object({
       path: ["topic_aliases"]
     });
   }
+}).transform((tg) => {
+  if (tg && tg.chat_id != null && tg.default_topic_id == null) {
+    return { ...tg, default_topic_id: 1 };
+  }
+  return tg;
 });
 var ChannelsSchema = exports_external.object({
   telegram: TelegramChannelSchema

package/dist/auth-broker/index.js

@@ -11101,18 +11101,11 @@ var TelegramChannelSchema = exports_external.object({
   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,
@@ -11127,6 +11120,11 @@ var TelegramChannelSchema = exports_external.object({
       path: ["topic_aliases"]
     });
   }
+}).transform((tg) => {
+  if (tg && tg.chat_id != null && tg.default_topic_id == null) {
+    return { ...tg, default_topic_id: 1 };
+  }
+  return tg;
 });
 var ChannelsSchema = exports_external.object({
   telegram: TelegramChannelSchema

package/dist/cli/notion-write-pretool.mjs

@@ -11849,18 +11849,11 @@ var TelegramChannelSchema = exports_external.object({
   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,
@@ -11875,6 +11868,11 @@ var TelegramChannelSchema = exports_external.object({
       path: ["topic_aliases"]
     });
   }
+}).transform((tg) => {
+  if (tg && tg.chat_id != null && tg.default_topic_id == null) {
+    return { ...tg, default_topic_id: 1 };
+  }
+  return tg;
 });
 var ChannelsSchema = exports_external.object({
   telegram: TelegramChannelSchema

package/dist/cli/switchroom.js

@@ -13665,18 +13665,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,
@@ -13691,6 +13684,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
@@ -23654,7 +23652,7 @@ var init_docker_fleet = __esm(() => {
 
 // src/agents/lifecycle.ts
 import { execFileSync as execFileSync7, spawn, spawnSync } from "node:child_process";
-import { existsSync as existsSync15, mkdirSync as mkdirSync12, writeFileSync as writeFileSync7, renameSync as renameSync3, readFileSync as readFileSync13 } from "node:fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync12, writeFileSync as writeFileSync7, renameSync as renameSync4, readFileSync as readFileSync13 } from "node:fs";
 import { resolve as resolve13, join as join10 } from "node:path";
 import { connect } from "node:net";
 function cleanShutdownMarkerPathForAgent(name) {
@@ -23676,7 +23674,7 @@ function writeRestartReasonMarker(name, reason, opts = {}) {
     const marker = { ts: Date.now(), signal: "SIGTERM", reason };
     const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
     writeFileSync7(tmp, JSON.stringify(marker), "utf-8");
-    renameSync3(tmp, path);
+    renameSync4(tmp, path);
   } catch {}
 }
 function buildCliRestartReason(opts) {
@@ -24154,7 +24152,7 @@ import {
   mkdirSync as mkdirSync14,
   readFileSync as readFileSync17,
   readdirSync as readdirSync9,
-  renameSync as renameSync5,
+  renameSync as renameSync6,
   rmSync as rmSync4,
   statSync as statSync11,
   writeFileSync as writeFileSync9
@@ -24296,7 +24294,7 @@ function atomicCopy(src, dest, mode) {
   const tmp = `${dest}.tmp-${process.pid}-${randomBytes2(4).toString("hex")}`;
   try {
     writeFileSync9(tmp, contents, { mode });
-    renameSync5(tmp, dest);
+    renameSync6(tmp, dest);
   } catch (err) {
     try {
       rmSync4(tmp);
@@ -25835,7 +25833,7 @@ import {
   mkdirSync as mkdirSync17,
   readFileSync as readFileSync22,
   readdirSync as readdirSync14,
-  renameSync as renameSync6,
+  renameSync as renameSync7,
   rmSync as rmSync10,
   statSync as statSync15,
   writeFileSync as writeFileSync14
@@ -25972,7 +25970,7 @@ __export(exports_atomic, {
   atomicWriteFileSync: () => atomicWriteFileSync2
 });
 import { randomBytes as randomBytes3 } from "node:crypto";
-import { closeSync as closeSync5, constants, fsyncSync as fsyncSync3, openSync as openSync5, renameSync as renameSync7, rmSync as rmSync11, writeSync as writeSync3 } from "node:fs";
+import { closeSync as closeSync5, constants, fsyncSync as fsyncSync3, openSync as openSync5, renameSync as renameSync8, rmSync as rmSync11, writeSync as writeSync3 } from "node:fs";
 function atomicWriteFileSync2(destPath, contents, mode = 384) {
   const tmp = `${destPath}.tmp-${process.pid}-${randomBytes3(4).toString("hex")}`;
   const buf = typeof contents === "string" ? Buffer.from(contents, "utf-8") : contents;
@@ -25983,7 +25981,7 @@ function atomicWriteFileSync2(destPath, contents, mode = 384) {
     fsyncSync3(fd);
     closeSync5(fd);
     fd = null;
-    renameSync7(tmp, destPath);
+    renameSync8(tmp, destPath);
   } catch (err) {
     if (fd !== null) {
       try {
@@ -49440,8 +49438,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.36";
-var COMMIT_SHA = "127b6f28";
+var VERSION = "0.14.38";
+var COMMIT_SHA = "1529105b";
 
 // src/cli/agent.ts
 init_source();
@@ -49522,6 +49520,7 @@ import {
   writeFileSync as writeFileSync5,
   appendFileSync,
   readFileSync as readFileSync11,
+  renameSync as renameSync3,
   chmodSync as chmodSync2,
   symlinkSync as symlinkSync2,
   copyFileSync as copyFileSync4,
@@ -51637,6 +51636,7 @@ This file is auto-maintained. Do not edit manually.
 `;
   }, created, skipped, 384);
   writeIfMissing(join8(agentDir, "telegram", "access.json"), () => buildAccessJson2(agentConfig, telegramConfig, topicId, userId), created, skipped, 384);
+  reconcileConfiguredGroup(join8(agentDir, "telegram", "access.json"), agentConfig, telegramConfig);
   if (agentConfig.subagents) {
     const agentsDir2 = join8(agentDir, ".claude", "agents");
     mkdirSync9(agentsDir2, { recursive: true });
@@ -52760,6 +52760,36 @@ function rerenderWithFingerprint(filePath, contentFn, created, skipped, rewritte
   rewrittenWithBackup.push(filePath);
   created.push(filePath);
 }
+function resolveAgentForumChatId(agentConfig, telegramConfig) {
+  const override = agentConfig.channels?.telegram?.chat_id;
+  if (typeof override === "string" && override.length > 0)
+    return override;
+  return telegramConfig.forum_chat_id ?? "";
+}
+function reconcileConfiguredGroup(accessPath, agentConfig, telegramConfig) {
+  if (!existsSync13(accessPath))
+    return;
+  const forumChatId = resolveAgentForumChatId(agentConfig, telegramConfig);
+  const hasRealForumChat = forumChatId !== "" && forumChatId !== "0";
+  if (agentConfig.dm_only || !hasRealForumChat)
+    return;
+  let access;
+  try {
+    access = JSON.parse(readFileSync11(accessPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const groups = access.groups ??= {};
+  if (groups[forumChatId] !== undefined)
+    return;
+  const allowFrom = Array.isArray(access.allowFrom) ? access.allowFrom : [];
+  groups[forumChatId] = { requireMention: false, allowFrom };
+  const tmp = accessPath + ".tmp";
+  writeFileSync5(tmp, JSON.stringify(access, null, 2) + `
+`, { mode: 384 });
+  renameSync3(tmp, accessPath);
+  console.log(source_default.green(`  registered supergroup ${forumChatId} in access.json ` + `(responds to all topics; requireMention=false)`));
+}
 function buildAccessJson2(agentConfig, telegramConfig, resolvedTopicId, userId) {
   const allowFrom = userId ? [String(userId)] : [];
   if (allowFrom.length === 0) {
@@ -52769,7 +52799,7 @@ function buildAccessJson2(agentConfig, telegramConfig, resolvedTopicId, userId)
     dmPolicy: "allowlist",
     allowFrom
   };
-  const forumChatId = telegramConfig.forum_chat_id;
+  const forumChatId = resolveAgentForumChatId(agentConfig, telegramConfig);
   const hasRealForumChat = forumChatId !== "" && forumChatId !== "0";
   if (!agentConfig.dm_only && hasRealForumChat) {
     access.groups = {
@@ -53035,7 +53065,7 @@ import { join as join12 } from "node:path";
 import { execFileSync as execFileSync8 } from "node:child_process";
 
 // src/agents/handoff-summarizer.ts
-import { readFileSync as readFileSync14, writeFileSync as writeFileSync8, renameSync as renameSync4, mkdirSync as mkdirSync13, existsSync as existsSync16, statSync as statSync9, readdirSync as readdirSync8 } from "node:fs";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync8, renameSync as renameSync5, mkdirSync as mkdirSync13, existsSync as existsSync16, statSync as statSync9, readdirSync as readdirSync8 } from "node:fs";
 import { join as join11 } from "node:path";
 var DEFAULT_MAX_TURNS = 50;
 var TOPIC_MAX_CHARS = 117;
@@ -53177,8 +53207,8 @@ function writeSidecarsAtomic(agentDir, briefing, topic) {
   const topicTmp = topicPath + ".tmp";
   writeFileSync8(handoffTmp, briefing, "utf-8");
   writeFileSync8(topicTmp, topic, "utf-8");
-  renameSync4(handoffTmp, handoffPath);
-  renameSync4(topicTmp, topicPath);
+  renameSync5(handoffTmp, handoffPath);
+  renameSync5(topicTmp, topicPath);
 }
 async function buildHandoff(opts) {
   const maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
@@ -59057,7 +59087,7 @@ import { spawn as spawn4 } from "node:child_process";
 init_compose();
 init_vault();
 import * as net3 from "node:net";
-import { mkdirSync as mkdirSync22, chmodSync as chmodSync7, chownSync as chownSync2, existsSync as existsSync35, readFileSync as readFileSync30, readdirSync as readdirSync16, statSync as statSync19, unlinkSync as unlinkSync8, writeFileSync as writeFileSync19, renameSync as renameSync9 } from "node:fs";
+import { mkdirSync as mkdirSync22, chmodSync as chmodSync7, chownSync as chownSync2, existsSync as existsSync35, readFileSync as readFileSync30, readdirSync as readdirSync16, statSync as statSync19, unlinkSync as unlinkSync8, writeFileSync as writeFileSync19, renameSync as renameSync10 } from "node:fs";
 import { dirname as dirname6, resolve as resolve26, basename as basename4 } from "node:path";
 import * as os4 from "node:os";
 import * as path3 from "node:path";
@@ -59074,7 +59104,7 @@ import {
   openSync as openSync6,
   closeSync as closeSync6,
   readFileSync as readFileSync28,
-  renameSync as renameSync8,
+  renameSync as renameSync9,
   statSync as statSync18,
   symlinkSync as symlinkSync3,
   unlinkSync as unlinkSync7
@@ -59151,7 +59181,7 @@ function runMigration(home2, opts) {
       copyFileSync7(oldPath, tempNew);
       chmodSync4(tempNew, 384);
       fsyncFile(tempNew);
-      renameSync8(tempNew, newPath);
+      renameSync9(tempNew, newPath);
       fsyncDir(parent);
       atomicReplaceWithSymlink(oldPath, "vault/vault.enc");
       fsyncDir(switchroomRoot);
@@ -59240,7 +59270,7 @@ function atomicReplaceWithSymlink(target, linkTarget) {
     } catch {}
   }
   symlinkSync3(linkTarget, tmp);
-  renameSync8(tmp, target);
+  renameSync9(tmp, target);
 }
 function fsyncFile(path) {
   const fd = openSync6(path, "r+");
@@ -62880,7 +62910,7 @@ class VaultBroker {
         const tokenPath = path3.join(tokenDir, ".vault-token");
         const tmpPath = `${tokenPath}.tmp.${process.pid}`;
         writeFileSync19(tmpPath, mintResult.token, { mode: 384 });
-        renameSync9(tmpPath, tokenPath);
+        renameSync10(tmpPath, tokenPath);
         try {
           const uid = allocateAgentUid(agent);
           chownSync2(tokenPath, uid, uid);
@@ -64262,7 +64292,7 @@ import {
   openSync as openSync9,
   readdirSync as readdirSync17,
   readFileSync as readFileSync34,
-  renameSync as renameSync10,
+  renameSync as renameSync11,
   statSync as statSync20,
   symlinkSync as symlinkSync4,
   unlinkSync as unlinkSync10,
@@ -64414,7 +64444,7 @@ function backupVault(opts) {
     } catch {}
     throw new Error(`vault backup refused: '${fullPath}' already exists ` + `(sub-second collision with another backup). Retry in 1 second, ` + `or check for a concurrent backup process.`);
   }
-  renameSync10(tmpPath, fullPath);
+  renameSync11(tmpPath, fullPath);
   const stat = statSync20(fullPath);
   const sha256 = sha256OfFile(fullPath);
   const row = {
@@ -74106,7 +74136,7 @@ import {
   openSync as openSync11,
   readdirSync as readdirSync21,
   readFileSync as readFileSync50,
-  renameSync as renameSync11,
+  renameSync as renameSync12,
   statSync as statSync25,
   unlinkSync as unlinkSync11,
   writeFileSync as writeFileSync26,
@@ -74664,7 +74694,7 @@ function writeAll(stateDir, events) {
 `) + `
 `;
   writeFileSync26(tmp, body, "utf-8");
-  renameSync11(tmp, path4);
+  renameSync12(tmp, path4);
 }
 var ORPHAN_TMP_TTL_MS = 60000;
 var TMP_PREFIX = `${ISSUES_FILE}.tmp-`;
@@ -76504,7 +76534,7 @@ import {
   readdirSync as readdirSync23,
   unlinkSync as unlinkSync12,
   existsSync as existsSync64,
-  renameSync as renameSync12
+  renameSync as renameSync13
 } from "node:fs";
 import { join as join63, resolve as resolve41 } from "node:path";
 import { homedir as homedir37 } from "node:os";
@@ -76523,7 +76553,7 @@ function writeRecord(record2) {
   const tmp = `${target}.tmp${process.pid}`;
   writeFileSync30(tmp, JSON.stringify(record2, null, 2) + `
 `, { mode: 384 });
-  renameSync12(tmp, target);
+  renameSync13(tmp, target);
 }
 function readRecord(id) {
   const path7 = recordPath(id);
@@ -77842,7 +77872,7 @@ async function fetchToken(vaultKey) {
 
 // src/cli/apply.ts
 init_source();
-import { accessSync as accessSync3, chownSync as chownSync4, constants as fsConstants6, copyFileSync as copyFileSync11, existsSync as existsSync72, mkdirSync as mkdirSync40, readFileSync as readFileSync57, readdirSync as readdirSync26, renameSync as renameSync13, writeFileSync as writeFileSync35 } from "node:fs";
+import { accessSync as accessSync3, chownSync as chownSync4, constants as fsConstants6, copyFileSync as copyFileSync11, existsSync as existsSync72, mkdirSync as mkdirSync40, readFileSync as readFileSync57, readdirSync as readdirSync26, renameSync as renameSync14, writeFileSync as writeFileSync35 } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { spawnSync as childSpawnSync } from "node:child_process";
 import readline from "node:readline";
@@ -78692,7 +78722,7 @@ function writeInstallTypeCache(homeDir = homedir40()) {
     source_paths: ctx.source_paths
   };
   writeFileSync35(tmp, JSON.stringify(payload, null, 2), { mode: 420 });
-  renameSync13(tmp, out);
+  renameSync14(tmp, out);
   return out;
 }
 async function runApply(config, options, deps = {}, switchroomConfigPath) {
@@ -79764,7 +79794,7 @@ import {
   openSync as openSync13,
   readdirSync as readdirSync28,
   readFileSync as readFileSync60,
-  renameSync as renameSync14,
+  renameSync as renameSync15,
   statSync as statSync28,
   unlinkSync as unlinkSync14,
   writeSync as writeSync8
@@ -79846,7 +79876,7 @@ function writeOverlayEntry(agent, slug, yamlText, opts = {}) {
     } finally {
       closeSync13(fd);
     }
-    renameSync14(stagingPath, finalPath);
+    renameSync15(stagingPath, finalPath);
     return finalPath;
   });
 }
@@ -79863,7 +79893,7 @@ function writeSkillsOverlayEntry(agent, slug, yamlText, opts = {}) {
     } finally {
       closeSync13(fd);
     }
-    renameSync14(stagingPath, finalPath);
+    renameSync15(stagingPath, finalPath);
     return finalPath;
   });
 }
@@ -80063,7 +80093,7 @@ import {
   openSync as openSync14,
   readdirSync as readdirSync29,
   readFileSync as readFileSync61,
-  renameSync as renameSync15,
+  renameSync as renameSync16,
   unlinkSync as unlinkSync15,
   writeFileSync as writeFileSync36,
   writeSync as writeSync9
@@ -80106,7 +80136,7 @@ function stagePendingScheduleEntry(opts) {
     } finally {
       closeSync14(fd);
     }
-    renameSync15(yamlTmp, yamlPath);
+    renameSync16(yamlTmp, yamlPath);
   }
   writeFileSync36(metaPath, JSON.stringify(meta, null, 2) + `
 `, { mode: 384 });
@@ -80145,7 +80175,7 @@ function commitPendingScheduleEntry(opts) {
   if (existsSync76(finalPath)) {
     return { committed: false, reason: "slug_collision" };
   }
-  renameSync15(match.yamlPath, finalPath);
+  renameSync16(match.yamlPath, finalPath);
   unlinkSync15(match.metaPath);
   return { committed: true, path: finalPath, slug };
 }
@@ -80895,7 +80925,7 @@ import {
   readFileSync as readFileSync63,
   readdirSync as readdirSync30,
   realpathSync as realpathSync7,
-  renameSync as renameSync16,
+  renameSync as renameSync17,
   rmSync as rmSync16,
   statSync as statSync29,
   writeFileSync as writeFileSync37
@@ -81350,9 +81380,9 @@ function writePayload(poolDir, name, files) {
     } catch {}
     if (targetExists) {
       oldRename = `${target}.skill-apply-old-${Date.now()}`;
-      renameSync16(target, oldRename);
+      renameSync17(target, oldRename);
     }
-    renameSync16(staging, target);
+    renameSync17(staging, target);
     if (oldRename) {
       rmSync16(oldRename, { recursive: true, force: true });
       oldRename = null;
@@ -81366,7 +81396,7 @@ function writePayload(poolDir, name, files) {
         if (existsSync79(target)) {
           rmSync16(target, { recursive: true, force: true });
         }
-        renameSync16(oldRename, target);
+        renameSync17(oldRename, target);
       } catch {}
     }
     throw err2;
@@ -81446,7 +81476,7 @@ import {
   openSync as openSync16,
   readFileSync as readFileSync64,
   readdirSync as readdirSync31,
-  renameSync as renameSync17,
+  renameSync as renameSync18,
   rmSync as rmSync17,
   statSync as statSync30,
   utimesSync,
@@ -81509,7 +81539,7 @@ function mirrorToConfigRepo(agent, name, liveSkillDir) {
       sweepMirrorPriors(configSkillsRoot);
       if (existsSync80(dest)) {
         const trash = join77(configSkillsRoot, `.${name}-trash-${Date.now()}`);
-        renameSync17(dest, trash);
+        renameSync18(dest, trash);
       }
       return;
     }
@@ -81533,9 +81563,9 @@ function mirrorToConfigRepo(agent, name, liveSkillDir) {
     walk2(liveSkillDir, staging);
     if (existsSync80(dest)) {
       const prior = join77(configSkillsRoot, `.${name}-prior-${Date.now()}`);
-      renameSync17(dest, prior);
+      renameSync18(dest, prior);
     }
-    renameSync17(staging, dest);
+    renameSync18(staging, dest);
   } catch (err2) {
     process.stderr.write(source_default.yellow(`warning: mirror to ${dest} failed (${err2.message ?? err2}); ` + `live copy still works, but this skill is not version-controlled until next successful sync.
 `));
@@ -81718,9 +81748,9 @@ function writePersonalSkill(targetDir, files) {
     } catch {}
     if (targetExists) {
       oldRename = `${targetDir}.personal-old-${Date.now()}`;
-      renameSync17(targetDir, oldRename);
+      renameSync18(targetDir, oldRename);
     }
-    renameSync17(staging, targetDir);
+    renameSync18(staging, targetDir);
     if (oldRename) {
       rmSync17(oldRename, { recursive: true, force: true });
       oldRename = null;
@@ -81734,7 +81764,7 @@ function writePersonalSkill(targetDir, files) {
         if (existsSync80(targetDir)) {
           rmSync17(targetDir, { recursive: true, force: true });
         }
-        renameSync17(oldRename, targetDir);
+        renameSync18(oldRename, targetDir);
       } catch {}
     }
     throw err2;
@@ -81972,7 +82002,7 @@ function removePersonalAction(name, opts) {
   mkdirSync45(trashRoot, { recursive: true, mode: 493 });
   const ts = Date.now();
   const trashTarget = join77(trashRoot, `${name}-${ts}`);
-  renameSync17(target, trashTarget);
+  renameSync18(target, trashTarget);
   const now = new Date(ts);
   utimesSync(trashTarget, now, now);
   mirrorToConfigRepo(agent, name, null);

package/dist/host-control/main.js

@@ -13836,18 +13836,11 @@ var TelegramChannelSchema = exports_external.object({
   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,
@@ -13862,6 +13855,11 @@ var TelegramChannelSchema = exports_external.object({
       path: ["topic_aliases"]
     });
   }
+}).transform((tg) => {
+  if (tg && tg.chat_id != null && tg.default_topic_id == null) {
+    return { ...tg, default_topic_id: 1 };
+  }
+  return tg;
 });
 var ChannelsSchema = exports_external.object({
   telegram: TelegramChannelSchema

package/dist/vault/approvals/kernel-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/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.36",
+  "version": "0.14.38",
   "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": {

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
@@ -49571,6 +49569,20 @@ function backfillJsonlAgentId(db2, jsonlPath, agentId, log) {
   }
   db2.prepare("UPDATE subagents SET jsonl_agent_id = ? WHERE id = ?").run(agentId, candidate.id);
   log?.(`subagent-watcher: backfill linked ${agentId} \u2192 ${candidate.id}`);
+  try {
+    const linkedRow = db2.prepare("SELECT started_at, parent_turn_key FROM subagents WHERE id = ?").get(candidate.id);
+    if (linkedRow != null && linkedRow.parent_turn_key == null) {
+      const turn = db2.prepare(`SELECT turn_key FROM turns
+           WHERE started_at <= ? AND (ended_at IS NULL OR ended_at >= ?)
+           ORDER BY started_at DESC LIMIT 1`).get(linkedRow.started_at, linkedRow.started_at);
+      if (turn?.turn_key != null) {
+        db2.prepare("UPDATE subagents SET parent_turn_key = ? WHERE id = ?").run(turn.turn_key, candidate.id);
+        log?.(`subagent-watcher: backfill parent_turn_key ${candidate.id} \u2192 ${turn.turn_key}`);
+      }
+    }
+  } catch (err) {
+    log?.(`subagent-watcher: parent_turn_key backfill skipped for ${candidate.id} \u2014 ${err.message}`);
+  }
 }
 function readSubTail(entry, tail, now, onDescriptionUpdate, fs2, log, db2, parentStateDir, onUnstall, onFileVanished, onProgress) {
   try {
@@ -51782,10 +51794,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.36";
-var COMMIT_SHA = "127b6f28";
-var COMMIT_DATE = "2026-06-01T23:38:45Z";
-var LATEST_PR = 2074;
+var VERSION = "0.14.38";
+var COMMIT_SHA = "1529105b";
+var COMMIT_DATE = "2026-06-02T02:25:47Z";
+var LATEST_PR = 2079;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

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

@@ -156,6 +156,53 @@ function extractResultSummary(toolResponse) {
   return str.slice(0, 200) || null
 }
 
+/**
+ * Extract the full text of a PostToolUse tool_response (untruncated).
+ * Mirrors extractResultSummary's shape handling but returns the whole
+ * string so callers can pattern-match on it.
+ */
+function toolResponseText(toolResponse) {
+  if (!toolResponse) return ''
+  if (Array.isArray(toolResponse.content)) {
+    return toolResponse.content
+      .filter((c) => c && typeof c === 'object' && c.type === 'text' && typeof c.text === 'string')
+      .map((c) => c.text)
+      .join('\n')
+  }
+  if (typeof toolResponse.result === 'string') return toolResponse.result
+  if (typeof toolResponse.output === 'string') return toolResponse.output
+  if (typeof toolResponse === 'string') return toolResponse
+  return ''
+}
+
+/**
+ * Detect Claude Code's async-launch ACK in a PostToolUse tool_response.
+ *
+ * A `run_in_background` Agent/Task returns IMMEDIATELY with an
+ * acknowledgement ("Async agent launched successfully … The agent is working
+ * in the background …"), NOT the sub-agent's final result. This ACK is the
+ * authoritative, uniform signal that the dispatch was a background one — it is
+ * present even when Claude Code omits `run_in_background` from the tool_input
+ * the PREtool hook sees (observed on claude-code 2.1.159: a worker whose
+ * tool_input lacked the flag still returned this ACK and ran ~3 min past the
+ * 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.
+ */
+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
+  return false
+}
+
 // ---------------------------------------------------------------------------
 // DB write
 // ---------------------------------------------------------------------------
@@ -172,9 +219,18 @@ function extractResultSummary(toolResponse) {
  * recordSubagentEnd (driven by the JSONL turn_end event) remains the
  * authoritative end-of-life signal.
  *
+ * Mis-recorded background (DB background = 0 but `asyncLaunch` is true):
+ * Claude Code returned the async-launch ACK even though run_in_background was
+ * absent from the tool_input the pretool saw, so the row was wrongly recorded
+ * foreground. PROMOTE it to background = 1 and take the background path — do
+ * NOT terminalize, because the worker is still running (the ACK is a launch,
+ * not a completion). This is the authoritative correction that makes the
+ * gateway's worker-feed card fire (onProgress re-reads `background` per tick)
+ * AND prevents the premature `completed` the foreground path would write.
+ *
  * The done(err | null) callback is invoked after all DB operations complete.
  */
-function updateRow(dbPath, { id, status, resultSummary, now }, done) {
+function updateRow(dbPath, { id, status, resultSummary, now, asyncLaunch }, done) {
   // SQL to read the background flag so we can choose the right update path.
   const SELECT_SQL = `SELECT background FROM subagents WHERE id = ?`
 
@@ -194,12 +250,22 @@ function updateRow(dbPath, { id, status, resultSummary, now }, done) {
       AND status NOT IN ('completed', 'failed')
   `
 
+  // Promote a mis-recorded foreground row to background (sets background = 1),
+  // bumping activity but NOT terminalizing — same shape as BACKGROUND_SQL.
+  const PROMOTE_BACKGROUND_SQL = `
+    UPDATE subagents
+    SET background = 1, result_summary = COALESCE(?, result_summary), last_activity_at = ?
+    WHERE id = ?
+      AND status NOT IN ('completed', 'failed')
+  `
+
   // Snapshot all values used inside closures before setImmediate fires.
   const snapDbPath = dbPath
   const snapId = id
   const snapStatus = status
   const snapResultSummary = resultSummary
   const snapNow = now
+  const snapAsyncLaunch = asyncLaunch === true
 
   // Resolve a synchronous SQLite binding (node:sqlite under Node 22+,
   // bun:sqlite under bun, else null → CLI fallback). See helper docs.
@@ -216,6 +282,8 @@ function updateRow(dbPath, { id, status, resultSummary, now }, done) {
         const isBackground = row != null && row.background === 1
         if (isBackground) {
           db.prepare(BACKGROUND_SQL).run(snapResultSummary, snapNow, snapId)
+        } else if (snapAsyncLaunch) {
+          db.prepare(PROMOTE_BACKGROUND_SQL).run(snapResultSummary, snapNow, snapId)
         } else {
           db.prepare(FOREGROUND_SQL).run(snapNow, snapStatus, snapResultSummary, snapNow, snapId)
         }
@@ -239,6 +307,12 @@ function updateRow(dbPath, { id, status, resultSummary, now }, done) {
         fillPlaceholders(BACKGROUND_SQL.trim(), [snapResultSummary, snapNow, snapId]),
         done,
       )
+    } else if (snapAsyncLaunch) {
+      spawnSql(
+        snapDbPath,
+        fillPlaceholders(PROMOTE_BACKGROUND_SQL.trim(), [snapResultSummary, snapNow, snapId]),
+        done,
+      )
     } else {
       spawnSql(
         snapDbPath,
@@ -345,16 +419,26 @@ function main() {
 
   const toolResponse = event.tool_response ?? null
 
+  // Authoritative background signal: Claude Code's async-launch ACK. Trusted
+  // over the pretool's input-derived flag (which is missing whenever the
+  // model/runtime omits run_in_background from tool_input — see
+  // isAsyncLaunchAck). Gates both the nudge below and the promote path in
+  // updateRow.
+  const asyncLaunch = isAsyncLaunchAck(toolResponse)
+
   // conversational-pacing beat 4 (foreground half). A foreground
   // sub-agent's PostToolUse fires at real completion, mid-parent-turn,
   // with its result in tool_response — nudge the parent to synthesise a
   // user-facing handback. Background sub-agents are gated OUT: their
   // PostToolUse fires on the launch ACK (BACKGROUND_SQL leaves status
   // untouched for that reason), and their handback is driven by the
-  // gateway's subagent-watcher onFinish path instead. Fail-silent: an
-  // unknown background flag (null) skips the nudge.
+  // gateway's subagent-watcher onFinish path instead. A launch ACK is also
+  // gated out via `!asyncLaunch` — at this point the DB flag may still read 0
+  // (updateRow promotes it on the next tick), so the ACK is the reliable
+  // tell. Fail-silent: an unknown background flag (null) skips the nudge.
   if (
     process.env.SWITCHROOM_SUBAGENT_HANDBACK !== '0'
+    && !asyncLaunch
     && detectStatus(toolResponse) === 'completed'
     && readBackgroundFlagSync(dbPath, id) === 0
   ) {
@@ -368,6 +452,7 @@ function main() {
       status: detectStatus(toolResponse),
       resultSummary: extractResultSummary(toolResponse),
       now: Date.now(),
+      asyncLaunch,
     },
     (err) => {
       if (err) {

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

@@ -262,7 +262,17 @@ function main() {
     {
       id: event.tool_use_id ?? null,
       parentSessionId: event.session_id ?? null,
-      parentTurnKey: event.turn_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,
       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

@@ -387,8 +387,16 @@ describe('Bug 4 — result_summary always NULL (hook integration)', () => {
 
 // ─── Bug 5 — parent_turn_key always NULL ─────────────────────────────────────
 
-describe('Bug 5 — parent_turn_key always NULL (hook integration)', () => {
-  it('pretool stores parent_turn_key from event.turn_id', () => {
+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.
     const event = {
       session_id: 'sess-turnkey',
       turn_id: 'turn-abc-001',
@@ -406,8 +414,8 @@ describe('Bug 5 — parent_turn_key always NULL (hook integration)', () => {
       | undefined
 
     expect(row).toBeDefined()
-    // After fix: parent_turn_key should be populated from event.turn_id
-    expect(row!.parent_turn_key).toBe('turn-abc-001')
+    // The hook never trusts event.turn_id — gateway backfill owns this column.
+    expect(row!.parent_turn_key).toBeNull()
   })
 
   it('pretool stores parent_turn_key as NULL when turn_id absent (no regression)', () => {

package/telegram-plugin/subagent-watcher.ts

@@ -508,7 +508,10 @@ interface FsLike {
  *   - Row already linked to a different agentId: SQL `WHERE jsonl_agent_id IS
  *     NULL` skips it. Re-runs are safe.
  */
-function backfillJsonlAgentId(
+// Exported for unit-testing the parent_turn_key backfill (telegram-plugin/
+// tests/subagent-watcher-parent-turn-key.test.ts). Not intended for
+// consumption by other modules.
+export function backfillJsonlAgentId(
   db: SubagentLivenessDb,
   jsonlPath: string,
   agentId: string,
@@ -555,6 +558,47 @@ function backfillJsonlAgentId(
     .prepare('UPDATE subagents SET jsonl_agent_id = ? WHERE id = ?')
     .run(agentId, candidate.id)
   log?.(`subagent-watcher: backfill linked ${agentId} → ${candidate.id}`)
+
+  // Backfill parent_turn_key (gateway-side). The PreToolUse hook can't know
+  // the gateway-minted Telegram turn_key (a chat+topic+turn key) — it only
+  // sees Claude Code's session id — so the row was inserted with
+  // parent_turn_key=NULL. Resolve
+  // it now from the turn whose [started_at, ended_at] window contained the
+  // sub-agent's dispatch (its started_at). Keying on the historical
+  // started_at, NOT "the turn active now", is what makes this correct for a
+  // background worker that outlives its parent turn: the turn may have already
+  // ended by link time, but the containment match still finds it. Turns are
+  // processed serially per agent, so at most one window contains a given
+  // instant; the ORDER BY ... DESC LIMIT 1 is just a defensive tie-break.
+  //
+  // Without this, resolveSubagentOriginChat() returns null and the live
+  // worker card + handback fall back to the operator DM instead of the
+  // originating group/forum-topic, and resolveCallingSubagent()'s turn-scoped
+  // heuristic (WHERE parent_turn_key = ?) can never see the row. Best-effort:
+  // any failure leaves parent_turn_key NULL (today's behaviour) and never
+  // throws out of the watcher poll loop.
+  try {
+    const linkedRow = db
+      .prepare('SELECT started_at, parent_turn_key FROM subagents WHERE id = ?')
+      .get(candidate.id) as { started_at: number; parent_turn_key: string | null } | null
+    if (linkedRow != null && linkedRow.parent_turn_key == null) {
+      const turn = db
+        .prepare(
+          `SELECT turn_key FROM turns
+           WHERE started_at <= ? AND (ended_at IS NULL OR ended_at >= ?)
+           ORDER BY started_at DESC LIMIT 1`,
+        )
+        .get(linkedRow.started_at, linkedRow.started_at) as { turn_key: string } | null
+      if (turn?.turn_key != null) {
+        db
+          .prepare('UPDATE subagents SET parent_turn_key = ? WHERE id = ?')
+          .run(turn.turn_key, candidate.id)
+        log?.(`subagent-watcher: backfill parent_turn_key ${candidate.id} → ${turn.turn_key}`)
+      }
+    }
+  } catch (err) {
+    log?.(`subagent-watcher: parent_turn_key backfill skipped for ${candidate.id} — ${(err as Error).message}`)
+  }
 }
 
 // Exported for unit-testing the ENOENT/EACCES deregister path

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

@@ -271,6 +271,79 @@ describe('subagent-tracker-posttool', () => {
     expect(postResult.status).toBe(0)
     expect(postResult.stdout).not.toContain('additionalContext')
   })
+
+  // The async-launch ACK is Claude Code's verbatim immediate return for a
+  // run_in_background Agent/Task dispatch. The posttool trusts it over the
+  // pretool's input-derived background flag, which is missing whenever the
+  // runtime omits run_in_background from the tool_input the pretool saw
+  // (observed on claude-code 2.1.159 — the clerk worker that never surfaced).
+  const ASYNC_LAUNCH_ACK =
+    'Async agent launched successfully.\n'
+    + 'agentId: go-live-sync-a176dc93\n'
+    + 'The agent is working in the background. You will be notified '
+    + 'automatically when it completes.'
+
+  it('promotes a mis-recorded foreground row to background from the launch ACK', () => {
+    // Pretool sees NO run_in_background key (the production bug) → records
+    // background=0, status=running.
+    const preResult = runHook(PRETOOL_SCRIPT, {
+      session_id: 's-promote',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_promote1',
+      tool_input: { subagent_type: 'worker', description: 'Go-live sync' },
+    })
+    expect(preResult.status).toBe(0)
+
+    const db = openDb()
+    const before = db.prepare('SELECT background, status FROM subagents WHERE id = ?').get('toolu_promote1') as
+      | { background: number; status: string }
+      | undefined
+    expect(before?.background).toBe(0)
+    expect(before?.status).toBe('running')
+
+    // Posttool receives the async-launch ACK → promote to background, do NOT
+    // terminalize, and do NOT emit a foreground handback nudge.
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_promote1',
+      tool_response: { content: [{ type: 'text', text: ASYNC_LAUNCH_ACK }] },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).not.toContain('additionalContext')
+
+    const after = db.prepare('SELECT background, status, ended_at FROM subagents WHERE id = ?').get('toolu_promote1') as
+      | { background: number; status: string; ended_at: number | null }
+      | undefined
+    expect(after?.background).toBe(1)
+    expect(after?.status).toBe('running')
+    expect(after?.ended_at == null).toBe(true)
+  })
+
+  it('still terminalizes a genuine foreground completion (no false promote)', () => {
+    // A real foreground sub-agent whose final report happens to mention
+    // "background" must NOT be mistaken for a launch ACK — the promote path
+    // only fires on the specific async-launch phrasing.
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-noflip',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_noflip1',
+      tool_input: { subagent_type: 'worker', description: 'Real foreground task', run_in_background: false },
+    })
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_noflip1',
+      tool_response: { result: 'Done. The feature now runs as a background job.', 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_noflip1') 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

@@ -0,0 +1,155 @@
+/**
+ * Unit tests for the parent_turn_key backfill in subagent-watcher.ts
+ * (backfillJsonlAgentId).
+ *
+ * The PreToolUse hook records a sub-agent row with parent_turn_key=NULL — it
+ * only sees Claude Code's session id, never the Telegram turn_key
+ * (chat_id:msg_id) the gateway keys turns on. The gateway backfills
+ * parent_turn_key when it links the JSONL stem to the row, resolving it from
+ * the turn whose [started_at, ended_at] window contained the sub-agent's
+ * dispatch (its started_at). These tests pin that resolution — in particular
+ * that it stays correct for a background worker that outlives its parent turn.
+ *
+ * bun:sqlite — run under Bun:
+ *   bun test telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { openTurnsDbInMemory } from '../registry/turns-schema.js'
+import { applySubagentsSchema } from '../registry/subagents-schema.js'
+import { backfillJsonlAgentId } from '../subagent-watcher.js'
+
+type Db = ReturnType<typeof openTurnsDbInMemory>
+
+let tempDir: string
+let db: Db
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'sub-parent-turn-'))
+  db = openTurnsDbInMemory()
+  applySubagentsSchema(db)
+})
+
+afterEach(() => {
+  try { db.close() } catch { /* ignore */ }
+  try { rmSync(tempDir, { recursive: true, force: true }) } catch { /* ignore */ }
+})
+
+function insertTurn(args: {
+  turnKey: string
+  chatId: string
+  threadId?: string | null
+  startedAt: number
+  endedAt?: number | null
+}) {
+  db.prepare(`
+    INSERT INTO turns (turn_key, chat_id, thread_id, started_at, ended_at, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    args.turnKey,
+    args.chatId,
+    args.threadId ?? null,
+    args.startedAt,
+    args.endedAt ?? null,
+    args.startedAt,
+    args.startedAt,
+  )
+}
+
+function insertSub(args: {
+  id: string
+  agentType: string
+  description: string
+  startedAt: number
+  parentTurnKey?: string | null
+}) {
+  db.prepare(`
+    INSERT INTO subagents
+      (id, parent_session_id, parent_turn_key, agent_type, description,
+       background, started_at, last_activity_at, status, jsonl_agent_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', NULL)
+  `).run(
+    args.id,
+    'sess-1',
+    args.parentTurnKey ?? null,
+    args.agentType,
+    args.description,
+    1,
+    args.startedAt,
+    args.startedAt,
+  )
+}
+
+/** Write the meta.json the backfill reads to match a row by (agentType, description). */
+function writeMeta(agentType: string, description: string): string {
+  const jsonlPath = join(tempDir, 'worker.jsonl')
+  writeFileSync(join(tempDir, 'worker.meta.json'), JSON.stringify({ agentType, description }))
+  return jsonlPath
+}
+
+function readSub(id: string) {
+  return db.prepare('SELECT jsonl_agent_id, parent_turn_key FROM subagents WHERE id = ?').get(id) as
+    | { jsonl_agent_id: string | null; parent_turn_key: string | null }
+    | undefined
+}
+
+describe('backfillJsonlAgentId — parent_turn_key resolution', () => {
+  it('resolves parent_turn_key from the turn whose window contains the sub-agent started_at', () => {
+    insertTurn({ turnKey: '555:10', chatId: '555', threadId: '42', startedAt: 1000, endedAt: 2000 })
+    insertSub({ id: 'toolu_a', agentType: 'worker', description: 'Go-live sync', startedAt: 1500 })
+
+    const jsonlPath = writeMeta('worker', 'Go-live sync')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_a')
+
+    const row = readSub('toolu_a')
+    expect(row?.jsonl_agent_id).toBe('agentstem_a')
+    expect(row?.parent_turn_key).toBe('555:10')
+  })
+
+  it('resolves to the parent turn even after it has ended (background worker outlives the turn)', () => {
+    // Parent turn already ended at 1600; a later turn is active "now".
+    insertTurn({ turnKey: '555:10', chatId: '555', startedAt: 1000, endedAt: 1600 })
+    insertTurn({ turnKey: '555:20', chatId: '555', startedAt: 1700, endedAt: null })
+    // The worker was dispatched at 1500 — inside the FIRST (now-ended) turn.
+    insertSub({ id: 'toolu_b', agentType: 'worker', description: 'Long task', startedAt: 1500 })
+
+    const jsonlPath = writeMeta('worker', 'Long task')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_b')
+
+    // Must pick the containing (ended) turn, NOT the turn active at link time.
+    expect(readSub('toolu_b')?.parent_turn_key).toBe('555:10')
+  })
+
+  it('does NOT overwrite an already-populated parent_turn_key', () => {
+    insertTurn({ turnKey: '555:10', chatId: '555', startedAt: 1000, endedAt: 2000 })
+    insertSub({
+      id: 'toolu_c',
+      agentType: 'worker',
+      description: 'Preset',
+      startedAt: 1500,
+      parentTurnKey: '999:9',
+    })
+
+    const jsonlPath = writeMeta('worker', 'Preset')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_c')
+
+    expect(readSub('toolu_c')?.parent_turn_key).toBe('999:9')
+  })
+
+  it('leaves parent_turn_key NULL when no turn window contains the dispatch', () => {
+    insertTurn({ turnKey: '555:10', chatId: '555', startedAt: 1000, endedAt: 2000 })
+    // Dispatched at 50 — before any turn started.
+    insertSub({ id: 'toolu_d', agentType: 'worker', description: 'Orphan', startedAt: 50 })
+
+    const jsonlPath = writeMeta('worker', 'Orphan')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_d')
+
+    const row = readSub('toolu_d')
+    // Still linked, but no turn to attribute it to.
+    expect(row?.jsonl_agent_id).toBe('agentstem_d')
+    expect(row?.parent_turn_key == null).toBe(true)
+  })
+})