switchroom 0.16.46 → 0.17.0

package/telegram-plugin/gateway/status-pin-store.ts

@@ -222,6 +222,79 @@ export type StatusPinPersistOp =
   | { kind: 'pin'; messageId: number }
   | { kind: 'clear' }
 
+/**
+ * Per-PATH async serial lock. status-pins.json has multiple concurrent writers
+ * (the fg:/wk: status-pin reconciles AND the banner:owner row), each of which
+ * is a read-modify-write against the shared file. Without serialisation two
+ * writers can interleave their load→persist and clobber each other's rows.
+ *
+ * `withStoreLock(path, fn)` chains `fn` after the current tail promise for that
+ * path and returns fn's result. The stored tail NEVER rejects (a failing op
+ * can't wedge the chain), and `fn` runs regardless of whether the prior op
+ * resolved or rejected.
+ */
+const storeLockTails = new Map<string, Promise<unknown>>()
+
+export function withStoreLock<T>(
+  path: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prev = storeLockTails.get(path) ?? Promise.resolve()
+  // Run fn after prev settles either way (fn ignores the settled value).
+  const run = prev.then(fn, fn)
+  // Keep a non-rejecting tail so one failed op can't poison every later one.
+  storeLockTails.set(
+    path,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  )
+  return run
+}
+
+/**
+ * READ-MODIFY-WRITE for exactly ONE pinKey's row, against the authoritative
+ * on-disk file. Loads the current snapshot from disk, drops any row for
+ * `pinKey`, appends `row` (unless null = removal), and persists atomically.
+ *
+ * Crucially the OTHER rows come from disk, never from an in-memory map that may
+ * lag disk — so a writer can never drop another key's pending/confirmed row.
+ * NOT locked itself; callers run it inside `withStoreLock`.
+ */
+function applyStatusPinRow(
+  path: string,
+  fs: StatusPinStoreFsSeam,
+  pinKey: string,
+  row: PersistedStatusPin | null,
+  log: (line: string) => void,
+): void {
+  const current = loadStatusPins(path, fs)
+  const others = current.filter((p) => p.pinKey !== pinKey)
+  const next = row == null ? others : [...others, row]
+  persistStatusPins(path, fs, next, log)
+}
+
+/**
+ * Public single-key mutation, serialised through the per-path lock. Upserts (or
+ * removes, when `row` is null) ONLY `pinKey`'s row, preserving every other row
+ * as it currently is ON DISK. This is the write path for pin kinds that don't
+ * need the pending→confirm dance (e.g. the banner:owner row); the status-pin
+ * reconcile uses `reconcileAndPersistStatusPin`, which holds the same lock
+ * across its whole pending→pin→confirm sequence.
+ */
+export function mutateStatusPinRow(
+  path: string,
+  fs: StatusPinStoreFsSeam,
+  pinKey: string,
+  row: PersistedStatusPin | null,
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): Promise<void> {
+  return withStoreLock(path, async () => {
+    applyStatusPinRow(path, fs, pinKey, row, log)
+  })
+}
+
 /**
  * Persist-ordering wrapper closing the persist-AFTER-pin leak window.
  *
@@ -237,21 +310,26 @@ export type StatusPinPersistOp =
  * pending record on disk, and boot cleanup unpins pending records too (see
  * runStatusPinBootCleanup), so the orphan is recovered next boot.
  *
- * `snapshotOthers` returns the OTHER live claims (every key except `pinKey`) so
- * the whole set is rewritten atomically each step — mirrors how the gateway
- * snapshots its Map. `applyPin` performs the real Telegram pin/unpin (the
- * gateway binds `reconcilePin`) and returns the next in-memory state so the
- * caller can update its Map. Never throws — persistence is best-effort/fail-open
- * and pin errors are already swallowed by `applyPin` (reconcilePin).
+ * CONCURRENCY: the ENTIRE op (pending write → await applyPin → confirm/clear
+ * write) runs under the per-path `withStoreLock`, so no other writer can
+ * interleave during the applyPin await window. Each disk write is a
+ * read-modify-write (`applyStatusPinRow`) keyed on THIS pinKey against the
+ * on-disk file — the other keys' rows (including a banner row, or another
+ * concurrent key's pending row) come from disk and are always preserved. This
+ * closes the race where a snapshot rebuilt from the (lagging) in-memory map
+ * dropped an in-flight key's row.
+ *
+ * `applyPin` performs the real Telegram pin/unpin (the gateway binds
+ * `reconcilePin`) and returns the next in-memory state so the caller can update
+ * its Map. Never throws — persistence is best-effort/fail-open and pin errors
+ * are already swallowed by `applyPin` (reconcilePin).
  */
-export async function reconcileAndPersistStatusPin(args: {
+export function reconcileAndPersistStatusPin(args: {
   path: string
   fs: StatusPinStoreFsSeam
   pinKey: string
   chatId: string
   op: StatusPinPersistOp
-  /** Live claims for every OTHER key (rewritten alongside on each step). */
-  snapshotOthers: () => PersistedStatusPin[]
   /** Execute the real pin/unpin; returns the confirmed message id (pin) or
    *  null (cleared). Must never throw — API errors are swallowed inside. */
   applyPin: () => Promise<{ messageId: number } | null>
@@ -260,43 +338,44 @@ export async function reconcileAndPersistStatusPin(args: {
   const { path, fs, pinKey, chatId, op } = args
   const log = args.log ?? ((l: string) => process.stderr.write(l))
 
-  if (op.kind === 'pin') {
-    // Persist INTENT first, marked pending — BEFORE the pin API call. If we
-    // crash after the pin lands but before the confirm rewrite, this pending
-    // record is what boot cleanup uses to unpin the orphan.
-    persistStatusPins(
-      path,
-      fs,
-      [
-        ...args.snapshotOthers(),
+  // Hold the per-path lock across the WHOLE op so no other writer (a banner
+  // persist, or another key's reconcile) can rebuild/overwrite the file during
+  // the applyPin await window and drop this key's pending/confirmed row.
+  return withStoreLock(path, async () => {
+    if (op.kind === 'pin') {
+      // Persist INTENT first, marked pending — BEFORE the pin API call. If we
+      // crash after the pin lands but before the confirm rewrite, this pending
+      // record is what boot cleanup uses to unpin the orphan.
+      applyStatusPinRow(
+        path,
+        fs,
+        pinKey,
         { pinKey, chatId, messageId: op.messageId, pending: true },
-      ],
-      log,
-    )
-    const next = await args.applyPin()
-    if (next == null) {
-      // Pin failed (claim NOT taken by reconcilePin). Clear the pending record
-      // so we don't leave a phantom claim for a pin that never landed.
-      persistStatusPins(path, fs, args.snapshotOthers(), log)
-      return null
-    }
-    // Pin confirmed — rewrite the record without the pending flag.
-    persistStatusPins(
-      path,
-      fs,
-      [
-        ...args.snapshotOthers(),
+        log,
+      )
+      const next = await args.applyPin()
+      if (next == null) {
+        // Pin failed (claim NOT taken by reconcilePin). Clear the pending
+        // record so we don't leave a phantom claim for a pin that never landed.
+        applyStatusPinRow(path, fs, pinKey, null, log)
+        return null
+      }
+      // Pin confirmed — rewrite the record without the pending flag.
+      applyStatusPinRow(
+        path,
+        fs,
+        pinKey,
         { pinKey, chatId, messageId: next.messageId },
-      ],
-      log,
-    )
-    return next
-  }
+        log,
+      )
+      return next
+    }
 
-  // clear: unpin (best-effort) THEN drop the record. Ordering is safe here —
-  // if we crash after the unpin but before the rewrite, the stale record just
-  // gets unpinned again next boot (idempotent), never a lingering pin.
-  const next = await args.applyPin()
-  persistStatusPins(path, fs, args.snapshotOthers(), log)
-  return next
+    // clear: unpin (best-effort) THEN drop the record. Ordering is safe here —
+    // if we crash after the unpin but before the rewrite, the stale record just
+    // gets unpinned again next boot (idempotent), never a lingering pin.
+    const next = await args.applyPin()
+    applyStatusPinRow(path, fs, pinKey, null, log)
+    return next
+  })
 }

package/telegram-plugin/gateway/worker-feed-dispatch.ts

@@ -8,6 +8,23 @@ export interface WorkerFeedDispatch {
    * ("🛠 Worker · <feedDescription>").
    */
   feedDescription: string
+  /**
+   * True when a registry row was found for the worker. A MISSING row must
+   * not be silently read as "foreground" by callers deciding the status
+   * surface — a row-less worker is most often a nested (depth-2+) dispatch
+   * whose row hasn't linked yet, and nesting it into an unrelated live main
+   * turn (or dropping it) is exactly the depth-2+ freeze/misroute bug.
+   */
+  hasRow: boolean
+  /**
+   * True when the row records a NESTED dispatch (spawned by another
+   * sub-agent — `parent_agent_id` set). A nested worker can never nest into
+   * the gateway's current turn (its parent is a worker, not a live turn),
+   * so callers must surface it via the worker feed regardless of its own
+   * background flag, and must not deliver a user handback for it (its
+   * result returns to its dispatching worker as the Task tool result).
+   */
+  isNested: boolean
 }
 
 /**
@@ -33,5 +50,7 @@ export function resolveWorkerFeedDispatch(
   return {
     isBackground: sub?.background ?? false,
     feedDescription: (sub?.description ?? '') || watcherDescription,
+    hasRow: sub != null,
+    isNested: sub?.parent_agent_id != null,
   }
 }

package/telegram-plugin/history.ts

@@ -140,6 +140,11 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
   // and survives crashes more cleanly than rollback journal.
   db.exec('PRAGMA journal_mode = WAL')
   db.exec('PRAGMA synchronous = NORMAL')
+  // Without a busy_timeout, bun:sqlite defaults to 0ms and a contending
+  // writer fails IMMEDIATELY with SQLITE_BUSY. History rows feed owed-reply
+  // logic (a dropped write can lose an owed reply), so wait-and-retry rather
+  // than drop. Mirrors the registry DB's pattern (turns-schema.ts).
+  db.exec('PRAGMA busy_timeout = 5000')
   db.exec(`
     CREATE TABLE IF NOT EXISTS messages (
       chat_id        TEXT    NOT NULL,

package/telegram-plugin/hooks/silent-end-interrupt-stop.mjs

@@ -193,8 +193,7 @@ function main() {
         'This turn is ending without your final answer reaching the user. ' +
         'If you wrote an answer as plain text (not via a tool), the user ' +
         'cannot see it — only text sent through the reply tool is delivered. ' +
-        'Send your final answer now by calling mcp__switchroom-telegram__reply ' +
-        '(or mcp__switchroom-telegram__stream_reply with done=true). ' +
+        'Send your final answer now by calling mcp__switchroom-telegram__reply. ' +
         'If your final answer has already reached the user, or you ' +
         'intentionally have nothing to add, reply with exactly NO_REPLY.',
     }),

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

@@ -54,7 +54,8 @@ const SCHEMA_SQL = `
     ended_at          INTEGER,
     status            TEXT    NOT NULL,
     result_summary    TEXT,
-    jsonl_agent_id    TEXT
+    jsonl_agent_id    TEXT,
+    parent_agent_id   TEXT
   );
   CREATE INDEX IF NOT EXISTS subagents_turn      ON subagents(parent_turn_key);
   CREATE INDEX IF NOT EXISTS subagents_status    ON subagents(status);
@@ -199,6 +200,13 @@ function writeRow(dbPath, { id, parentSessionId, parentTurnKey, agentType, descr
           db.exec('ALTER TABLE subagents ADD COLUMN jsonl_agent_id TEXT')
           db.exec('CREATE INDEX IF NOT EXISTS subagents_jsonl_id ON subagents(jsonl_agent_id)')
         }
+        // Migrate older DBs that pre-date parent_agent_id (nested-worker keying).
+        const hasParentAgentCol = db
+          .prepare("SELECT name FROM pragma_table_info('subagents') WHERE name = 'parent_agent_id'")
+          .get()
+        if (hasParentAgentCol == null) {
+          db.exec('ALTER TABLE subagents ADD COLUMN parent_agent_id TEXT')
+        }
         // Verify the marker-derived parent_turn_key (snapParams[2]) actually has
         // a row in the turns table before trusting it. The gateway writes the
         // turn-active marker even when recordTurnStart's INSERT failed (the two

package/telegram-plugin/registry/subagents-schema.ts

@@ -104,6 +104,18 @@ export interface Subagent {
   result_summary: string | null
   /** JSONL filename stem (e.g. "a37ad7639ae61476c") for watcher ID linkage. */
   jsonl_agent_id: string | null
+  /**
+   * JSONL stem of the DISPATCHING sub-agent, for a NESTED (depth-2+) worker
+   * — one spawned by another sub-agent rather than by the main session.
+   * NULL for a main-session dispatch. Written by the watcher when it
+   * observes an Agent/Task tool_use inside a worker's own JSONL
+   * (recordNestedSubagentDispatch). Enables transitive origin-chat
+   * resolution: a nested worker whose parent_turn_key can never be stamped
+   * (its dispatching context is a background worker that outlives the main
+   * turn, so turn-active.json is gone) inherits routing from its ancestor
+   * chain instead.
+   */
+  parent_agent_id: string | null
 }
 
 export interface RecordSubagentStartArgs {
@@ -194,7 +206,8 @@ const SUBAGENTS_SCHEMA_SQL = `
     ended_at          INTEGER,
     status            TEXT    NOT NULL,
     result_summary    TEXT,
-    jsonl_agent_id    TEXT
+    jsonl_agent_id    TEXT,
+    parent_agent_id   TEXT
   );
   CREATE INDEX IF NOT EXISTS subagents_turn      ON subagents(parent_turn_key);
   CREATE INDEX IF NOT EXISTS subagents_status    ON subagents(status);
@@ -221,6 +234,12 @@ export function applySubagentsSchema(db: SqliteDatabase): void {
   if (!hasJsonlId) {
     db.exec('ALTER TABLE subagents ADD COLUMN jsonl_agent_id TEXT')
   }
+  // Idempotent migration for DBs created before parent_agent_id existed
+  // (nested-worker keying — see the Subagent.parent_agent_id doc).
+  const hasParentAgentId = cols.some((c) => c.name === 'parent_agent_id')
+  if (!hasParentAgentId) {
+    db.exec('ALTER TABLE subagents ADD COLUMN parent_agent_id TEXT')
+  }
   // Always (re-)apply the index. `IF NOT EXISTS` makes this a no-op when it
   // already exists. Splitting it from SUBAGENTS_SCHEMA_SQL is what fixes the
   // pre-existing-table failure mode — by the time we reach this line, the
@@ -296,6 +315,7 @@ interface RawSubagentRow {
   status: string
   result_summary: string | null
   jsonl_agent_id: string | null
+  parent_agent_id?: string | null
 }
 
 function mapSubagentRow(row: RawSubagentRow): Subagent {
@@ -312,6 +332,7 @@ function mapSubagentRow(row: RawSubagentRow): Subagent {
     status: row.status as SubagentStatus,
     result_summary: row.result_summary,
     jsonl_agent_id: row.jsonl_agent_id,
+    parent_agent_id: row.parent_agent_id ?? null,
   }
 }
 
@@ -579,3 +600,107 @@ export function getSubagent(db: SqliteDatabase, id: string): Subagent | null {
     | undefined
   return row ? mapSubagentRow(row) : null
 }
+
+// ---------------------------------------------------------------------------
+// Nested (depth-2+) worker keying — the unified progress-card fix
+// ---------------------------------------------------------------------------
+
+export interface RecordNestedSubagentDispatchArgs {
+  /** tool_use id of the nested Agent/Task dispatch — the subagents PK the
+   *  child's meta.json `toolUseId` will later link against. */
+  toolUseId: string
+  /** JSONL stem of the DISPATCHING worker (the parent sub-agent). */
+  parentJsonlAgentId: string
+  agentType?: string | null
+  description?: string | null
+  /** `run_in_background` from the nested dispatch's tool_input. */
+  background: boolean
+  now: number
+}
+
+/**
+ * Record a NESTED sub-agent dispatch observed by the watcher in a worker's
+ * own JSONL (a `sub_agent_tool_use` whose tool is Agent/Task).
+ *
+ * Why this exists: the PreToolUse tracker hook derives `parent_turn_key`
+ * from the gateway's `turn-active.json` marker, which only exists during
+ * the MAIN turn. A nested worker is dispatched by a background depth-1
+ * worker that outlives that turn, so the marker is gone → the hook stamps
+ * NULL (or, under concurrent dispatch, the hook's write can be lost
+ * entirely). The row is then missing/unattributed: origin-chat resolution
+ * returns null (card misroutes to the owner DM), `resolveWorkerFeedDispatch`
+ * defaults the worker to foreground, and the card freezes on "starting…"
+ * forever. The watcher, however, tails the parent worker's JSONL and SEES
+ * the nested dispatch — so it is the reliable recorder for depth-2+.
+ *
+ * Behaviour (idempotent, safe to call on every observation):
+ *   - INSERT OR IGNORE a row keyed on the dispatch tool_use_id (harmless
+ *     no-op when the pretool hook's row already landed).
+ *   - Stamp `parent_agent_id` (the dispatching worker's JSONL stem) when
+ *     not already set.
+ *   - Inherit `parent_turn_key` transitively from the parent worker's row
+ *     when NULL — the parent's row was stamped at ITS dispatch (main turn
+ *     still active), so the chain bottoms out at a real turn key.
+ */
+export function recordNestedSubagentDispatch(
+  db: SqliteDatabase,
+  args: RecordNestedSubagentDispatchArgs,
+): void {
+  db.prepare(`
+    INSERT OR IGNORE INTO subagents
+      (id, parent_session_id, parent_turn_key, agent_type, description,
+       background, started_at, last_activity_at, status, jsonl_agent_id,
+       parent_agent_id)
+    VALUES (?, NULL, NULL, ?, ?, ?, ?, ?, 'running', NULL, ?)
+  `).run(
+    args.toolUseId,
+    args.agentType ?? null,
+    args.description ?? null,
+    args.background ? 1 : 0,
+    args.now,
+    args.now,
+    args.parentJsonlAgentId,
+  )
+  // Repair path for a hook-inserted row: stamp nested parentage and inherit
+  // the origin turn key from the parent worker's row when missing. COALESCE
+  // keeps any value already present (hook-stamped or previously inherited).
+  db.prepare(`
+    UPDATE subagents
+    SET parent_agent_id = COALESCE(parent_agent_id, ?),
+        parent_turn_key = COALESCE(
+          parent_turn_key,
+          (SELECT p.parent_turn_key FROM subagents p
+           WHERE p.jsonl_agent_id = ? LIMIT 1)
+        )
+    WHERE id = ?
+  `).run(args.parentJsonlAgentId, args.parentJsonlAgentId, args.toolUseId)
+}
+
+/**
+ * Resolve the ORIGIN turn key for a worker, walking the nested-parent chain.
+ *
+ * Depth-1: the row's own `parent_turn_key`. Depth-2+: when NULL, follow
+ * `parent_agent_id` (the dispatching worker's JSONL stem) up the chain until
+ * a row with a non-NULL `parent_turn_key` is found. Bounded (default 5 hops)
+ * and cycle-safe. Returns null when nothing in the chain is attributed —
+ * callers keep their existing DM fallback.
+ */
+export function resolveSubagentOriginTurnKey(
+  db: SqliteDatabase,
+  jsonlAgentId: string,
+  maxHops = 5,
+): string | null {
+  const seen = new Set<string>()
+  let currentJsonlId: string | null = jsonlAgentId
+  for (let hop = 0; hop <= maxHops && currentJsonlId != null; hop++) {
+    if (seen.has(currentJsonlId)) return null
+    seen.add(currentJsonlId)
+    const row = db
+      .prepare('SELECT parent_turn_key, parent_agent_id FROM subagents WHERE jsonl_agent_id = ? LIMIT 1')
+      .get(currentJsonlId) as { parent_turn_key: string | null; parent_agent_id: string | null } | undefined
+    if (row == null) return null
+    if (row.parent_turn_key != null && row.parent_turn_key.length > 0) return row.parent_turn_key
+    currentJsonlId = row.parent_agent_id ?? null
+  }
+  return null
+}

package/telegram-plugin/registry/turns-schema.ts

@@ -108,6 +108,18 @@ export interface Turn {
    * cleanly-restarted (`'restart'`) orphans.
    */
   interrupt_reason: string | null
+  /**
+   * Ms epoch at which a boot-resume/report inbound was durably queued for
+   * this interrupted turn (see `markTurnResumed`). It is the at-most-once
+   * ledger for resume: `findLatestTurnIfInterrupted` treats a turn with a
+   * non-null `resumed_at` as already handled and never re-fires it. This
+   * distinguishes "we already committed a resume for this turn (side
+   * effects may have run)" from "work incomplete, never resumed" — closing
+   * the accept-vs-consume double-execution window (#2793 part A) where the
+   * "latest turn not clean" proxy re-minted a fresh resume on every restart.
+   * Null for turns that were never resumed.
+   */
+  resumed_at: number | null
   created_at: number
   updated_at: number
 }
@@ -148,6 +160,7 @@ const SCHEMA_SQL = `
     assistant_reply_preview TEXT,
     tool_call_count         INTEGER,
     interrupt_reason        TEXT,
+    resumed_at              INTEGER,
     created_at              INTEGER NOT NULL,
     updated_at              INTEGER NOT NULL
   );
@@ -169,6 +182,14 @@ const PHASE2_MIGRATIONS = [
   `ALTER TABLE turns ADD COLUMN interrupt_reason TEXT`,
 ]
 
+// Column added for at-most-once resume (#2793 part A). Stamped when the
+// gateway durably queues a boot-resume inbound for an interrupted turn, so a
+// subsequent restart cannot re-mint a fresh resume for the same turn (which
+// would re-run side effects that already executed before the crash).
+const PHASE3_MIGRATIONS = [
+  `ALTER TABLE turns ADD COLUMN resumed_at INTEGER`,
+]
+
 function applySchema(db: SqliteDatabase): void {
   db.exec('PRAGMA journal_mode = WAL')
   db.exec('PRAGMA synchronous = NORMAL')
@@ -185,7 +206,7 @@ function applySchema(db: SqliteDatabase): void {
   // Run migrations. SQLite doesn't support "ADD COLUMN IF NOT EXISTS", so
   // we swallow the "duplicate column" error to stay idempotent on
   // pre-existing registry.db files.
-  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS]) {
+  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS, ...PHASE3_MIGRATIONS]) {
     try {
       db.exec(sql)
     } catch (err) {
@@ -261,6 +282,7 @@ interface RawTurnRow {
   assistant_reply_preview: string | null
   tool_call_count: number | null
   interrupt_reason: string | null
+  resumed_at: number | null
   created_at: number
   updated_at: number
 }
@@ -281,6 +303,7 @@ function mapRow(row: RawTurnRow): Turn {
     assistant_reply_preview: row.assistant_reply_preview,
     tool_call_count: row.tool_call_count,
     interrupt_reason: row.interrupt_reason,
+    resumed_at: row.resumed_at,
     created_at: row.created_at,
     updated_at: row.updated_at,
   }
@@ -559,6 +582,38 @@ const INTERRUPTED_VIA: ReadonlySet<TurnEndedVia> = new Set<TurnEndedVia>([
   'unknown',
 ])
 
+/**
+ * Stamp `resumed_at` on an interrupted turn at the moment the gateway has
+ * DURABLY committed to resuming it (the boot-resume inbound is on the
+ * inbound spool / in-memory buffer). This is the at-most-once ledger for
+ * resume: once stamped, `findLatestTurnIfInterrupted` no longer returns the
+ * turn, so a subsequent restart cannot mint a SECOND, distinct resume for
+ * the same turn and re-run side effects that already executed before the
+ * crash (#2793 part A).
+ *
+ * Ordering matters: the caller must stamp only AFTER the resume inbound is
+ * durably spooled (synchronously, before any async delivery can ack it), so
+ * a crash between "decide to resume" and "persist the resume" can never mark
+ * a turn resumed that was never actually spooled. The spool's own
+ * at-least-once redelivery (keyed on `resume_turn_key`) still guarantees the
+ * one committed resume is delivered; this ledger only prevents re-minting.
+ *
+ * Idempotent and first-write-wins: an already-stamped turn keeps its
+ * original `resumed_at`. No-ops if `turnKey` is not found.
+ */
+export function markTurnResumed(
+  db: SqliteDatabase,
+  turnKey: string,
+  now: number = Date.now(),
+): void {
+  db.prepare(`
+    UPDATE turns
+    SET resumed_at = ?,
+        updated_at = ?
+    WHERE turn_key = ? AND resumed_at IS NULL
+  `).run(now, now, turnKey)
+}
+
 /**
  * Return the single most-recently-started turn IFF it was interrupted
  * (`ended_at IS NULL`, or `ended_via` in {restart, sigterm, timeout,
@@ -576,6 +631,14 @@ const INTERRUPTED_VIA: ReadonlySet<TurnEndedVia> = new Set<TurnEndedVia>([
  * Ordering uses `started_at DESC` (not `updated_at`) so the boot reaper,
  * which mass-stamps orphans with identical timestamps, can't reorder the
  * temporal "last turn" the user actually remembers.
+ *
+ * At-most-once (#2793 part A): a turn that already carries `resumed_at` was
+ * committed to a resume on an earlier boot. Even if it never reached a clean
+ * `'stop'` (its resume ran side effects but the process died before the
+ * follow-up turn wrote `ended_at`, or the resume inbound was accepted but
+ * never consumed), it is NOT re-fired — the "latest turn not clean" proxy
+ * would otherwise re-mint a fresh resume on every restart and double-execute
+ * side effects. Resume is at-most-once per turn.
  */
 export function findLatestTurnIfInterrupted(db: SqliteDatabase): Turn | null {
   const row = db.prepare(`
@@ -585,6 +648,7 @@ export function findLatestTurnIfInterrupted(db: SqliteDatabase): Turn | null {
   `).get() as RawTurnRow | undefined
   if (!row) return null
   const turn = mapRow(row)
+  if (turn.resumed_at != null) return null
   if (turn.ended_at == null) return turn
   if (turn.ended_via != null && INTERRUPTED_VIA.has(turn.ended_via)) return turn
   return null

package/telegram-plugin/session-tail.ts

@@ -124,7 +124,19 @@ export type SessionEvent =
   | { kind: 'sub_agent_text'; agentId: string; text: string; blockIndex: number; lastInMessage: boolean }
   | { kind: 'sub_agent_tool_result'; agentId: string; toolUseId: string; isError?: boolean; errorText?: string }
   | { kind: 'sub_agent_turn_end'; agentId: string }
-  | { kind: 'sub_agent_nested_spawn'; agentId: string }
+  | {
+      kind: 'sub_agent_nested_spawn'
+      agentId: string
+      /** tool_use id of the nested Agent/Task dispatch — the `subagents`
+       *  registry PK the child's meta.json `toolUseId` links against. Lets
+       *  the watcher record/repair the nested worker's registry row
+       *  (recordNestedSubagentDispatch — the depth-2+ keying fix). */
+      toolUseId?: string | null
+      /** The dispatch tool_input (description / subagent_type /
+       *  run_in_background) — registry metadata only, never rendered
+       *  (design §5.5's "no recursion in rendering" rule is unchanged). */
+      input?: Record<string, unknown>
+    }
   /**
    * Emitted when a sub-agent JSONL has >= CAP_TOOL_USE_THRESHOLD tool_use
    * records but no terminal record (no `type:result`, `subtype:end`, or
@@ -146,9 +158,14 @@ function parseChannelMeta(content: string): {
   messageId: string | null
   threadId: string | null
 } {
-  // Look for `chat_id="..."` etc in the channel XML tag
+  // Look for `chat_id="..."` etc in the channel XML tag. LEFT-ANCHOR on an
+  // attribute boundary (start-of-string or a whitespace/quote before the name)
+  // so `message_id` matches ONLY the real attribute — never a same-suffix
+  // sibling like `target_message_id`, `reply_to_message_id`, or
+  // `original_message_id`. Without the boundary, grab('message_id') would
+  // match the FIRST `*_message_id` substring, mis-attributing the enqueue's id.
   const grab = (key: string): string | null => {
-    const m = content.match(new RegExp(`${key}="([^"]+)"`))
+    const m = content.match(new RegExp(`(?:^|[\\s"'])${key}="([^"]+)"`))
     return m ? m[1] : null
   }
   return {
@@ -480,7 +497,12 @@ export function projectSubagentLine(
         // that would surface the sub-sub-agent's description and break
         // the "no recursion in rendering" rule.
         if (name === 'Agent' || name === 'Task') {
-          events.push({ kind: 'sub_agent_nested_spawn', agentId })
+          events.push({
+            kind: 'sub_agent_nested_spawn',
+            agentId,
+            toolUseId: (c.id as string | undefined) ?? null,
+            input: (c.input as Record<string, unknown> | undefined) ?? undefined,
+          })
         } else {
           events.push({
             kind: 'sub_agent_tool_use',