switchroom 0.14.36 → 0.14.37

package/dist/cli/switchroom.js

@@ -49440,8 +49440,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.36";
-var COMMIT_SHA = "127b6f28";
+var VERSION = "0.14.37";
+var COMMIT_SHA = "90d0c420";
 
 // src/cli/agent.ts
 init_source();

package/package.json

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

@@ -49571,6 +49571,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 +51796,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.37";
+var COMMIT_SHA = "90d0c420";
+var COMMIT_DATE = "2026-06-02T02:10:03Z";
+var LATEST_PR = 2078;
 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)
+  })
+})