switchroom 0.14.23 → 0.14.25

package/dist/cli/switchroom.js

@@ -49420,8 +49420,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.23";
-var COMMIT_SHA = "8ac2987a";
+var VERSION = "0.14.25";
+var COMMIT_SHA = "f75f4f25";
 
 // src/cli/agent.ts
 init_source();

package/package.json

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

@@ -47505,6 +47505,18 @@ function decideSubagentProgress(input) {
   return { deliver: true, chatId, bucketIdx, inbound };
 }
 
+// gateway/foreground-nesting.ts
+function shouldRenderForegroundProgress(g) {
+  return g.nestingEnabled;
+}
+function foregroundFinishAction(i) {
+  if (!i.removed)
+    return "none";
+  if (i.replyCalled && i.remainingForeground === 0)
+    return "handoff-clear";
+  return "recompose";
+}
+
 // gateway/poll-health.ts
 var DEFAULT_LOG = (msg) => {
   process.stderr.write(msg.endsWith(`
@@ -49225,6 +49237,7 @@ var DEFAULT_RESCAN_MS = 1000;
 var DEFAULT_STALL_THRESHOLD_MS = 60000;
 var DEFAULT_SILENT_SYNTHESIS_STALL_THRESHOLD_MS = 300000;
 var DEFAULT_SILENT_STALL_TERMINAL_MS = 300000;
+var DEFAULT_INFLIGHT_PROMOTE_MAX_AGE_MS = 15 * 60000;
 var SUBAGENT_RESULT_TEXT_MAX = 3000;
 function parseEnvMs(varName) {
   const raw = process.env[varName];
@@ -49415,6 +49428,8 @@ function startSubagentWatcher(config) {
   const stallThresholdMs = config.stallThresholdMs ?? parseEnvMs("SWITCHROOM_SUBAGENT_STALL_MS") ?? DEFAULT_STALL_THRESHOLD_MS;
   const silentSynthesisStallThresholdMs = config.silentSynthesisStallThresholdMs ?? parseEnvMs("SWITCHROOM_SUBAGENT_SILENT_SYNTH_STALL_MS") ?? DEFAULT_SILENT_SYNTHESIS_STALL_THRESHOLD_MS;
   const silentStallTerminalMs = config.silentStallTerminalMs ?? parseEnvMs("SWITCHROOM_SUBAGENT_STALL_TERMINAL_MS") ?? DEFAULT_SILENT_STALL_TERMINAL_MS;
+  const inflightPromoteMaxAgeMs = config.inflightPromoteMaxAgeMs ?? parseEnvMs("SWITCHROOM_SUBAGENT_INFLIGHT_MAX_AGE_MS") ?? DEFAULT_INFLIGHT_PROMOTE_MAX_AGE_MS;
+  const bootPromoteEnabled = config.bootPromoteEnabled ?? process.env.SWITCHROOM_SUBAGENT_BOOT_PROMOTE !== "0";
   const reaperTtlMs = config.reaperTtlMs ?? DEFAULT_REAPER_TTL_MS;
   const reaperIntervalMs = config.reaperIntervalMs ?? DEFAULT_REAPER_INTERVAL_MS;
   const rescanMs = config.rescanMs ?? DEFAULT_RESCAN_MS;
@@ -49497,13 +49512,25 @@ function startSubagentWatcher(config) {
       log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`);
     }, fs2, log, db2, parentStateDir, config.onUnstall, undefined, config.onProgress);
     if (isHistorical && entry.state === "running") {
-      entry.historical = false;
-      log?.(`subagent-watcher: ${agentId} was in-flight at boot \u2014 promoting to live (predates watcher; user still awaiting handback)`);
-      if (db2 != null) {
-        try {
-          backfillJsonlAgentId(db2, filePath, agentId, log);
-        } catch (err) {
-          log?.(`subagent-watcher: backfill error for ${agentId}: ${err.message}`);
+      let fileAgeMs = Infinity;
+      try {
+        const st = fs2.statSync(filePath);
+        if (typeof st.mtimeMs === "number")
+          fileAgeMs = n - st.mtimeMs;
+      } catch {}
+      if (!bootPromoteEnabled) {
+        log?.(`subagent-watcher: ${agentId} running at boot but promotion disabled (SWITCHROOM_SUBAGENT_BOOT_PROMOTE=0) \u2014 leaving historical`);
+      } else if (fileAgeMs > inflightPromoteMaxAgeMs) {
+        log?.(`subagent-watcher: ${agentId} running at boot but stale (last write ${Math.round(fileAgeMs / 1000)}s ago > ${Math.round(inflightPromoteMaxAgeMs / 1000)}s) \u2014 leaving historical (dead prior-session worker, not in-flight)`);
+      } else {
+        entry.historical = false;
+        log?.(`subagent-watcher: ${agentId} was in-flight at boot \u2014 promoting to live (last write ${Math.round(fileAgeMs / 1000)}s ago; user still awaiting handback)`);
+        if (db2 != null) {
+          try {
+            backfillJsonlAgentId(db2, filePath, agentId, log);
+          } catch (err) {
+            log?.(`subagent-watcher: backfill error for ${agentId}: ${err.message}`);
+          }
         }
       }
     }
@@ -51442,10 +51469,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.23";
-var COMMIT_SHA = "8ac2987a";
-var COMMIT_DATE = "2026-05-31T22:03:26Z";
-var LATEST_PR = 2031;
+var VERSION = "0.14.25";
+var COMMIT_SHA = "f75f4f25";
+var COMMIT_DATE = "2026-06-01T00:05:32Z";
+var LATEST_PR = 2038;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -61961,12 +61988,22 @@ var didOneTimeSetup = false;
                 const isBackground = dispatch.isBackground;
                 if (!isBackground) {
                   const turn = currentTurn;
-                  if (turn != null && turn.foregroundSubAgents.delete(agentId) && !turn.replyCalled) {
-                    const rendered = composeTurnActivity(turn);
-                    if (rendered != null) {
-                      turn.activityPendingRender = rendered;
-                      if (turn.activityInFlight == null) {
-                        turn.activityInFlight = drainActivitySummary(turn);
+                  const removed = turn != null && turn.foregroundSubAgents.delete(agentId);
+                  if (turn != null && removed) {
+                    const action = foregroundFinishAction({
+                      removed,
+                      replyCalled: turn.replyCalled,
+                      remainingForeground: turn.foregroundSubAgents.size
+                    });
+                    if (action === "handoff-clear") {
+                      clearActivitySummary(turn);
+                    } else if (action === "recompose") {
+                      const rendered = composeTurnActivity(turn);
+                      if (rendered != null) {
+                        turn.activityPendingRender = rendered;
+                        if (turn.activityInFlight == null) {
+                          turn.activityInFlight = drainActivitySummary(turn);
+                        }
                       }
                     }
                   }
@@ -62033,10 +62070,13 @@ var didOneTimeSetup = false;
                 }
                 const isBackground = dispatch.isBackground;
                 if (!isBackground) {
-                  if (!foregroundNestingEnabled)
-                    return;
                   const turn = currentTurn;
-                  if (turn == null || turn.replyCalled)
+                  if (turn == null)
+                    return;
+                  if (!shouldRenderForegroundProgress({
+                    nestingEnabled: foregroundNestingEnabled,
+                    replyCalled: turn.replyCalled
+                  }))
                     return;
                   const child = latestSummary.trim().slice(0, 120);
                   if (child.length === 0)

package/telegram-plugin/gateway/foreground-nesting.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure state-transition helpers for Model A foreground sub-agent activity
+ * nesting (#2027). Extracted from gateway.ts so the `replyCalled` gate is
+ * unit-testable on its own — the exact seam #2027 shipped without, which let
+ * the feature silently no-op for every ack-first turn (reply "On it…" then
+ * delegate) and go unnoticed in production. See
+ * `tests/foreground-nesting.test.ts`.
+ *
+ * Subscription-honest: every caller is pure jsonl-tail → render, no model
+ * call. These functions decide *whether/what* to render; the gateway owns the
+ * `currentTurn` mutation and the Telegram edit.
+ */
+
+export interface ForegroundProgressGate {
+  /** `SWITCHROOM_FOREGROUND_SUBAGENT_NESTING !== '0'` — the kill-switch. */
+  nestingEnabled: boolean
+  /**
+   * Whether the parent turn has already emitted a reply. Accepted as input
+   * but intentionally NOT a gate: a foreground `Task` is a *blocking* call,
+   * so the parent cannot have issued its FINAL answer while the sub-agent is
+   * still running — any `replyCalled === true` observed here is therefore an
+   * *interim* ack. The pre-fix code bailed on this flag, which is precisely
+   * why ack-first turns showed zero live foreground activity.
+   */
+  replyCalled: boolean
+}
+
+/**
+ * Whether a foreground sub-agent progress tick should accumulate its narrative
+ * and re-render the activity feed. Gated ONLY by the kill-switch — never by
+ * `replyCalled` (see the field doc above).
+ */
+export function shouldRenderForegroundProgress(g: ForegroundProgressGate): boolean {
+  return g.nestingEnabled
+}
+
+export type ForegroundFinishAction = 'recompose' | 'handoff-clear' | 'none'
+
+export interface ForegroundFinishInput {
+  /** Was this agentId actually an active foreground sub-agent we tracked? */
+  removed: boolean
+  /** Has the parent turn already emitted a reply (an interim ack)? */
+  replyCalled: boolean
+  /** Foreground sub-agents still active AFTER removing the finished one. */
+  remainingForeground: number
+}
+
+/**
+ * What the gateway should do when a foreground sub-agent finishes:
+ *
+ *  - `'none'`         — it wasn't one we were tracking (e.g. background, or a
+ *                       stale boot row); leave the feed alone.
+ *  - `'handoff-clear'`— it was the LAST foreground sub-agent and the parent
+ *                       has already acked. The re-opened post-ack feed now
+ *                       hands off to the imminent final answer, mirroring the
+ *                       first-reply hand-off. (turn_end is the safety net if
+ *                       this is somehow missed.)
+ *  - `'recompose'`    — collapse the finished sub-agent's block and re-render
+ *                       (pre-ack flow, or other sub-agents still running).
+ */
+export function foregroundFinishAction(i: ForegroundFinishInput): ForegroundFinishAction {
+  if (!i.removed) return 'none'
+  if (i.replyCalled && i.remainingForeground === 0) return 'handoff-clear'
+  return 'recompose'
+}

package/telegram-plugin/gateway/gateway.ts

@@ -303,6 +303,10 @@ import {
   decideSubagentProgress,
   DEFAULT_PROGRESS_INTERVAL_MS,
 } from './subagent-progress-inbound-builder.js'
+import {
+  shouldRenderForegroundProgress,
+  foregroundFinishAction,
+} from './foreground-nesting.js'
 import { createPollHealthCheck, type PollHealthCheckHandle } from './poll-health.js'
 import type {
   ToolCallMessage,
@@ -17843,16 +17847,26 @@ void (async () => {
                   // tool result, so there's no handback to deliver. Reaction
                   // promotion already ran above.
                   const turn = currentTurn
-                  if (
-                    turn != null &&
-                    turn.foregroundSubAgents.delete(agentId) &&
-                    !turn.replyCalled
-                  ) {
-                    const rendered = composeTurnActivity(turn)
-                    if (rendered != null) {
-                      turn.activityPendingRender = rendered
-                      if (turn.activityInFlight == null) {
-                        turn.activityInFlight = drainActivitySummary(turn)
+                  const removed = turn != null && turn.foregroundSubAgents.delete(agentId)
+                  if (turn != null && removed) {
+                    const action = foregroundFinishAction({
+                      removed,
+                      replyCalled: turn.replyCalled,
+                      remainingForeground: turn.foregroundSubAgents.size,
+                    })
+                    if (action === 'handoff-clear') {
+                      // Post-ack: the last foreground sub-agent finished and
+                      // the parent will now produce its answer inline. Hand
+                      // the re-opened feed off to the answer, mirroring the
+                      // first-reply clear (turn_end is the safety net).
+                      clearActivitySummary(turn)
+                    } else if (action === 'recompose') {
+                      const rendered = composeTurnActivity(turn)
+                      if (rendered != null) {
+                        turn.activityPendingRender = rendered
+                        if (turn.activityInFlight == null) {
+                          turn.activityInFlight = drainActivitySummary(turn)
+                        }
                       }
                     }
                   }
@@ -17972,9 +17986,17 @@ void (async () => {
                   // activity draft rather than a separate worker message. Pure
                   // jsonl-tail → render (no model call), inside the
                   // subscription-honest boundary.
-                  if (!foregroundNestingEnabled) return // kill-switch: skip overhead
                   const turn = currentTurn
-                  if (turn == null || turn.replyCalled) return
+                  if (turn == null) return
+                  // Render regardless of `replyCalled` — a foreground Task
+                  // blocks the parent, so any reply seen while it runs is an
+                  // interim ack, never the final answer. Gating on replyCalled
+                  // (pre-#2032) made ack-first turns show zero live foreground
+                  // activity. Kill-switch lives in the predicate.
+                  if (!shouldRenderForegroundProgress({
+                    nestingEnabled: foregroundNestingEnabled,
+                    replyCalled: turn.replyCalled,
+                  })) return
                   const child = latestSummary.trim().slice(0, 120)
                   if (child.length === 0) return
                   let narrative = turn.foregroundSubAgents.get(agentId)

package/telegram-plugin/subagent-watcher.ts

@@ -208,6 +208,23 @@ export interface SubagentWatcherConfig {
    * synthesis; tests use a tiny value to exercise the path.
    */
   silentStallTerminalMs?: number
+  /**
+   * Freshness window (ms) for promoting a running-at-boot worker file to
+   * live. A file whose last write (mtime) is older than this is treated as
+   * a dead prior-session worker and stays historical/suppressed, NOT
+   * promoted. Default 15 min (DEFAULT_INFLIGHT_PROMOTE_MAX_AGE_MS); env
+   * override `SWITCHROOM_SUBAGENT_INFLIGHT_MAX_AGE_MS`. Guards the v0.14.23
+   * stale-handback replay regression.
+   */
+  inflightPromoteMaxAgeMs?: number
+  /**
+   * Kill-switch for the boot-scan promotion path. When false, a
+   * running-at-boot worker is never promoted — the watcher reverts to the
+   * pre-v0.14.23 behaviour of leaving every boot-scan file historical
+   * (suppressed). Default true; env `SWITCHROOM_SUBAGENT_BOOT_PROMOTE=0`
+   * disables it fleet-wide without a code change (emergency lever).
+   */
+  bootPromoteEnabled?: boolean
   /**
    * Reaper TTL (ms): background rows in `status='running'` whose
    * `last_activity_at` (or `started_at` if liveness never wrote) is older
@@ -382,6 +399,29 @@ const DEFAULT_SILENT_SYNTHESIS_STALL_THRESHOLD_MS = 300_000
  */
 const DEFAULT_SILENT_STALL_TERMINAL_MS = 300_000
 
+/**
+ * Freshness window for the boot-scan "in-flight at boot → promote to
+ * live" path. A worker file still in `running` state at boot is only
+ * promoted (un-suppressed) if its last write (file mtime) is within this
+ * window of now. The signal cleanly separates the two populations:
+ *
+ *  - A worker genuinely in-flight across a restart / fleet rollout was
+ *    writing right up until the container was recreated, so its mtime is
+ *    seconds-to-minutes before the new gateway boots — well inside the
+ *    window. The user is still awaiting it; promote it.
+ *  - A worker that died in a PRIOR session without writing a terminal
+ *    `turn_end` is also `running` in the file, but its mtime is hours-to-
+ *    weeks old. These accumulate by the dozen-to-hundred in a long-lived
+ *    agent's subagents dir. Promoting them replays stale handbacks
+ *    (often `failed`, from old error lines) on every boot — the v0.14.23
+ *    regression. Leave them historical/suppressed, exactly as before.
+ *
+ * 15 min is generous for any plausible restart gap (container recreate +
+ * image pull) yet far below the staleness of a dead prior-session file.
+ * Override with `SWITCHROOM_SUBAGENT_INFLIGHT_MAX_AGE_MS`.
+ */
+const DEFAULT_INFLIGHT_PROMOTE_MAX_AGE_MS = 15 * 60_000
+
 /**
  * Cap on the result text retained per sub-agent (`entry.lastResultText`)
  * and carried to the gateway via `onFinish`. The gateway feeds this into
@@ -810,6 +850,14 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     config.silentStallTerminalMs
     ?? parseEnvMs('SWITCHROOM_SUBAGENT_STALL_TERMINAL_MS')
     ?? DEFAULT_SILENT_STALL_TERMINAL_MS
+  const inflightPromoteMaxAgeMs =
+    config.inflightPromoteMaxAgeMs
+    ?? parseEnvMs('SWITCHROOM_SUBAGENT_INFLIGHT_MAX_AGE_MS')
+    ?? DEFAULT_INFLIGHT_PROMOTE_MAX_AGE_MS
+  // Kill-switch: not parseEnvMs (which rejects `0`) — an explicit `=0`
+  // here MUST disable promotion (revert to pre-v0.14.23 suppression).
+  const bootPromoteEnabled =
+    config.bootPromoteEnabled ?? (process.env.SWITCHROOM_SUBAGENT_BOOT_PROMOTE !== '0')
   const reaperTtlMs = config.reaperTtlMs ?? DEFAULT_REAPER_TTL_MS
   const reaperIntervalMs = config.reaperIntervalMs ?? DEFAULT_REAPER_INTERVAL_MS
   const rescanMs = config.rescanMs ?? DEFAULT_RESCAN_MS
@@ -961,18 +1009,40 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     // already `done` at boot stays historical and is short-circuited just
     // below — it finished before this session.)
     if (isHistorical && entry.state === 'running') {
-      entry.historical = false
-      log?.(`subagent-watcher: ${agentId} was in-flight at boot — promoting to live (predates watcher; user still awaiting handback)`)
-      // The prior gateway life's registration normally linked
-      // jsonl_agent_id already, but re-run the backfill idempotently in
-      // case that life crashed before the link persisted — the handback's
-      // isBackground lookup is keyed on jsonl_agent_id, and an unlinked row
-      // would mis-resolve the worker as foreground and drop the handback.
-      if (db != null) {
-        try {
-          backfillJsonlAgentId(db, filePath, agentId, log)
-        } catch (err) {
-          log?.(`subagent-watcher: backfill error for ${agentId}: ${(err as Error).message}`)
+      // Freshness gate (v0.14.24): only promote a file whose LAST WRITE is
+      // recent. A genuinely in-flight-across-a-restart worker was writing
+      // until the container was recreated (mtime seconds-to-minutes old); a
+      // dead prior-session worker that never wrote a terminal turn_end is
+      // also `running` but hours-to-weeks stale. Promoting the latter
+      // replayed stale `failed` handbacks on every boot (the v0.14.23
+      // fleet-wide regression). Unreadable mtime → treat as stale (suppress
+      // rather than risk re-spamming). The kill-switch reverts to pre-fix
+      // suppression entirely.
+      let fileAgeMs = Infinity
+      try {
+        const st = fs.statSync(filePath)
+        if (typeof st.mtimeMs === 'number') fileAgeMs = n - st.mtimeMs
+      } catch {
+        /* unreadable → Infinity → treated as stale below */
+      }
+      if (!bootPromoteEnabled) {
+        log?.(`subagent-watcher: ${agentId} running at boot but promotion disabled (SWITCHROOM_SUBAGENT_BOOT_PROMOTE=0) — leaving historical`)
+      } else if (fileAgeMs > inflightPromoteMaxAgeMs) {
+        log?.(`subagent-watcher: ${agentId} running at boot but stale (last write ${Math.round(fileAgeMs / 1000)}s ago > ${Math.round(inflightPromoteMaxAgeMs / 1000)}s) — leaving historical (dead prior-session worker, not in-flight)`)
+      } else {
+        entry.historical = false
+        log?.(`subagent-watcher: ${agentId} was in-flight at boot — promoting to live (last write ${Math.round(fileAgeMs / 1000)}s ago; user still awaiting handback)`)
+        // The prior gateway life's registration normally linked
+        // jsonl_agent_id already, but re-run the backfill idempotently in
+        // case that life crashed before the link persisted — the handback's
+        // isBackground lookup is keyed on jsonl_agent_id, and an unlinked row
+        // would mis-resolve the worker as foreground and drop the handback.
+        if (db != null) {
+          try {
+            backfillJsonlAgentId(db, filePath, agentId, log)
+          } catch (err) {
+            log?.(`subagent-watcher: backfill error for ${agentId}: ${(err as Error).message}`)
+          }
         }
       }
     }

package/telegram-plugin/tests/foreground-nesting.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Regression guard for the Model A foreground sub-agent nesting gate (#2032).
+ *
+ * #2027 shipped foreground nesting but gated every render path on
+ * `turn.replyCalled`. Because the framework's ack-first pattern replies
+ * "On it…" FIRST and then delegates, `replyCalled` was already true before any
+ * foreground sub-agent ran — so the feature silently produced ZERO live
+ * foreground activity for the exact case it was built for, and that went
+ * unnoticed because #2027 only tested the pure renderer, never the gate.
+ *
+ * These tests pin the gate decisions directly so the replyCalled-independence
+ * can never regress silently again.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  shouldRenderForegroundProgress,
+  foregroundFinishAction,
+} from '../gateway/foreground-nesting.js'
+import { renderActivityFeedWithNested } from '../tool-activity-summary.js'
+
+describe('shouldRenderForegroundProgress', () => {
+  it('renders even after the parent has acked (the #2027 blindspot)', () => {
+    // THE regression guard: ack-first sets replyCalled=true before the
+    // foreground sub-agent runs. It MUST still render.
+    expect(
+      shouldRenderForegroundProgress({ nestingEnabled: true, replyCalled: true }),
+    ).toBe(true)
+  })
+
+  it('renders before any reply (pre-ack flow, unchanged)', () => {
+    expect(
+      shouldRenderForegroundProgress({ nestingEnabled: true, replyCalled: false }),
+    ).toBe(true)
+  })
+
+  it('is independent of replyCalled — the flag never flips the outcome', () => {
+    const on = shouldRenderForegroundProgress({ nestingEnabled: true, replyCalled: true })
+    const off = shouldRenderForegroundProgress({ nestingEnabled: true, replyCalled: false })
+    expect(on).toBe(off)
+  })
+
+  it('honours the kill-switch regardless of replyCalled', () => {
+    expect(
+      shouldRenderForegroundProgress({ nestingEnabled: false, replyCalled: false }),
+    ).toBe(false)
+    expect(
+      shouldRenderForegroundProgress({ nestingEnabled: false, replyCalled: true }),
+    ).toBe(false)
+  })
+})
+
+describe('foregroundFinishAction', () => {
+  it('hands off to the answer when the last sub-agent finishes post-ack', () => {
+    expect(
+      foregroundFinishAction({ removed: true, replyCalled: true, remainingForeground: 0 }),
+    ).toBe('handoff-clear')
+  })
+
+  it('recomposes when other foreground sub-agents are still running post-ack', () => {
+    expect(
+      foregroundFinishAction({ removed: true, replyCalled: true, remainingForeground: 1 }),
+    ).toBe('recompose')
+  })
+
+  it('recomposes pre-ack (original behaviour preserved)', () => {
+    expect(
+      foregroundFinishAction({ removed: true, replyCalled: false, remainingForeground: 0 }),
+    ).toBe('recompose')
+  })
+
+  it('does nothing for an agent it was not tracking', () => {
+    expect(
+      foregroundFinishAction({ removed: false, replyCalled: true, remainingForeground: 0 }),
+    ).toBe('none')
+  })
+})
+
+describe('end-to-end render shape under ack-first', () => {
+  it('produces a live nested block from a post-ack foreground narrative', () => {
+    // marko's real scenario: parent acked with no prior steps (empty mirror),
+    // then a foreground researcher emits progress. The gate now ALLOWS this
+    // render; prove the render is a real, non-empty nested feed with a live
+    // bold "→ current" line — i.e. the user would actually see activity.
+    const html = renderActivityFeedWithNested(
+      [],
+      [
+        'searching Unsplash CC0 desk',
+        'checking license on 4 candidates',
+        'ranking by resolution',
+      ],
+    )
+    expect(html).not.toBeNull()
+    // newest child is the live, bold current step
+    expect(html).toContain('<b>→ ranking by resolution</b>')
+    // an earlier child is present as a done/italic step
+    expect(html).toContain('checking license on 4 candidates')
+  })
+})

package/telegram-plugin/tests/subagent-watcher-handback-gaps.test.ts

@@ -80,6 +80,14 @@ function makeHarness(opts: {
   stallThresholdMs?: number
   silentStallTerminalMs?: number
   rescanMs?: number
+  /** How long ago (ms) the boot file was last written, i.e. its mtime is
+   *  `currentTime - bootFileAgeMs` at registration. Default 0 (fresh, so the
+   *  freshness gate promotes it). Set large to simulate a dead prior-session
+   *  worker that must NOT be promoted. */
+  bootFileAgeMs?: number
+  /** Kill-switch passthrough; default true (promotion enabled). */
+  bootPromoteEnabled?: boolean
+  inflightPromoteMaxAgeMs?: number
 }): Harness {
   const {
     agentId = 'gap-agent',
@@ -87,6 +95,9 @@ function makeHarness(opts: {
     stallThresholdMs = 60_000,
     silentStallTerminalMs = 300_000,
     rescanMs = 500,
+    bootFileAgeMs = 0,
+    bootPromoteEnabled = true,
+    inflightPromoteMaxAgeMs,
   } = opts
 
   let currentTime = 1000
@@ -104,6 +115,10 @@ function makeHarness(opts: {
 
   const fileContents = new Map<string, Buffer>()
   fileContents.set(jsonlPath, Buffer.from(buildJSONL(...bootLines), 'utf-8'))
+  // Per-file mtime (ms). The boot file's last write is `bootFileAgeMs` in the
+  // past; appends bump it to currentTime. The freshness gate reads this.
+  const fileMtimes = new Map<string, number>()
+  fileMtimes.set(jsonlPath, 1000 - bootFileAgeMs)
 
   let lastOpenedPath: string | null = null
   const mockFs = {
@@ -121,7 +136,7 @@ function makeHarness(opts: {
       if (ps === subagentsDir) return [`agent-${agentId}.jsonl`]
       return []
     }) as unknown as typeof fs.readdirSync,
-    statSync: ((p: fs.PathLike) => ({ size: fileContents.get(String(p))?.length ?? 0 }) as fs.Stats) as typeof fs.statSync,
+    statSync: ((p: fs.PathLike) => ({ size: fileContents.get(String(p))?.length ?? 0, mtimeMs: fileMtimes.get(String(p)) ?? currentTime }) as fs.Stats) as typeof fs.statSync,
     openSync: ((p: fs.PathLike) => {
       lastOpenedPath = String(p)
       return 42
@@ -153,6 +168,8 @@ function makeHarness(opts: {
     silentSynthesisStallThresholdMs: stallThresholdMs,
     silentStallTerminalMs,
     rescanMs,
+    bootPromoteEnabled,
+    ...(inflightPromoteMaxAgeMs != null ? { inflightPromoteMaxAgeMs } : {}),
     onStallTerminal: (id) => stallTerminalCalls.push({ agentId: id }),
     onFinish: ({ agentId: id, outcome, resultText }) =>
       finishCalls.push({ agentId: id, outcome, resultText }),
@@ -186,6 +203,7 @@ function makeHarness(opts: {
     const cur = fileContents.get(jsonlPath) ?? Buffer.alloc(0)
     const more = buildJSONL(...lines)
     fileContents.set(jsonlPath, Buffer.concat([cur, Buffer.from(more, 'utf-8')]))
+    fileMtimes.set(jsonlPath, currentTime)
   }
 
   return { stallTerminalCalls, finishCalls, logs, advance, watcher, fileContents, jsonlPath, append }
@@ -245,6 +263,75 @@ describe('Gap 1 — background worker in-flight across a gateway restart', () =>
   })
 })
 
+describe('Gap 1 freshness gate — v0.14.24 stale-replay regression', () => {
+  // The v0.14.23 regression: promoting EVERY running-at-boot file replayed
+  // weeks-old dead prior-session workers as handbacks (often `failed`, from
+  // old error lines) on every boot, spamming the whole fleet. The gate
+  // promotes only files whose last write is recent.
+
+  it('a STALE running-at-boot worker (weeks-old mtime) is NOT promoted — no handback, no stall', () => {
+    const h = makeHarness({
+      agentId: 'gap1-stale-running',
+      bootLines: [subAgentUserMsg('bg task from weeks ago')], // running: no turn_end
+      bootFileAgeMs: 21 * 24 * 60 * 60_000, // 21 days old — clearly dead
+      silentStallTerminalMs: 120_000,
+    })
+
+    h.advance(600)
+    h.advance(600_000) // far past every stall/synthesis window
+    expect(h.finishCalls).toHaveLength(0) // pre-fix: a spurious (often failed) handback
+    expect(h.stallTerminalCalls).toHaveLength(0)
+    expect(h.logs.some((l) => l.includes('stale') && l.includes('leaving historical'))).toBe(true)
+  })
+
+  it('a FRESH running-at-boot worker (recent mtime) IS still promoted and hands back', () => {
+    // Preserve the genuine Gap 1 fix: a worker in-flight across a restart
+    // (wrote moments before the bounce) must still get promoted + handed back.
+    const h = makeHarness({
+      agentId: 'gap1-fresh-running',
+      bootLines: [subAgentUserMsg('bg task')],
+      bootFileAgeMs: 30_000, // 30s old — in-flight across a quick restart
+    })
+
+    h.append(subAgentText('Finished the migration'), subAgentTurnEnd())
+    h.advance(600)
+
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].outcome).toBe('completed')
+    expect(h.logs.some((l) => l.includes('promoting to live'))).toBe(true)
+  })
+
+  it('kill-switch (bootPromoteEnabled=false) suppresses even a fresh running-at-boot worker', () => {
+    const h = makeHarness({
+      agentId: 'gap1-killswitch',
+      bootLines: [subAgentUserMsg('bg task')],
+      bootFileAgeMs: 5_000, // fresh — would normally promote
+      bootPromoteEnabled: false,
+      silentStallTerminalMs: 120_000,
+    })
+
+    h.advance(600)
+    h.advance(600_000)
+    expect(h.finishCalls).toHaveLength(0)
+    expect(h.logs.some((l) => l.includes('promotion disabled'))).toBe(true)
+  })
+
+  it('a worker just past the freshness window is NOT promoted (boundary)', () => {
+    const h = makeHarness({
+      agentId: 'gap1-boundary',
+      bootLines: [subAgentUserMsg('bg task')],
+      inflightPromoteMaxAgeMs: 60_000, // 60s window
+      bootFileAgeMs: 90_000, // 90s old → just stale
+      silentStallTerminalMs: 120_000,
+    })
+
+    h.advance(600)
+    h.advance(600_000)
+    expect(h.finishCalls).toHaveLength(0)
+    expect(h.logs.some((l) => l.includes('stale'))).toBe(true)
+  })
+})
+
 describe('Gap 2 — failure honesty', () => {
   it('a terminal error line flips the outcome to failed and carries the detail', () => {
     const h = makeHarness({ agentId: 'gap2-failed', bootLines: [subAgentUserMsg('bg task')] })

package/telegram-plugin/uat/scenarios/jtbd-foreground-subagent-activity-dm.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Foreground sub-agent live activity nesting (#2032) — UAT.
+ *
+ * Background (#2027): a FOREGROUND sub-agent (Agent/Task WITHOUT
+ * run_in_background) runs INSIDE the parent turn, blocking it. Its live steps
+ * were meant to nest into the parent's activity-summary feed (Model A). But
+ * every render path bailed on `turn.replyCalled`, and the framework's
+ * ack-first pattern replies "On it…" FIRST — so the sub-agent ran with
+ * replyCalled already true and NOTHING ever painted. #2027 only tested the
+ * pure renderer, so the regression shipped silently (the "marko's researcher
+ * showed no Telegram activity" report). #2032 renders foreground progress
+ * regardless of replyCalled.
+ *
+ * This scenario forces the exact broken shape end-to-end:
+ *   1. Prompt the agent to send a quick ack FIRST (sets replyCalled=true),
+ *   2. THEN dispatch a FOREGROUND sub-agent (run_in_background:false) that
+ *      narrates ~10 paced steps so its jsonl keeps ticking under the
+ *      test-harness 5s stall floor and the feed can paint + edit,
+ *   3. then report done.
+ *
+ * Asserts the load-bearing proof: an activity-summary feed message appears
+ * carrying the NESTED foreground marker ("↳") with the sub-agent's narration —
+ * i.e. live foreground activity surfaced AFTER the ack. Pre-#2032 this message
+ * never existed. Logs every observed body so a human can read the real UX.
+ *
+ * NOT a draft: the activity-summary feed is a real sendMessage/editMessageText
+ * (gateway.ts drainActivitySummary), so mtcute can observe it — unlike the
+ * answer-stream draft, which mtcute cannot see.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+// Same paced-narration discipline as jtbd-worker-activity-feed-dm: each step
+// is its own Bash call with a one-line narration so the sub-agent emits a
+// `sub_agent_text` line every ~2s — under SWITCHROOM_SUBAGENT_STALL_MS=5000,
+// so the watcher never synth-terminates it mid-flight (which would suppress
+// onProgress and the feed would never paint). run_in_background:false makes it
+// FOREGROUND — the whole point.
+const FG_DISPATCH_PROMPT =
+  `First, immediately send me a one-line acknowledgement that you're starting ` +
+  `(just "On it — running a check now."). Then use the Agent tool with ` +
+  `subagent_type "general-purpose" and run_in_background: false (a FOREGROUND ` +
+  `sub-agent) with this exact task: "Do eight steps, ONE AT A TIME, k = 1 ` +
+  `through 8. Before each step write a brief one-sentence narration of what ` +
+  `you are about to do, then run \`sleep 2\` via the Bash tool, then run ` +
+  `\`echo step-k\` via the Bash tool (substitute the real number for k). Run ` +
+  `every sleep and every echo as its OWN separate Bash call — never batch or ` +
+  `chain them with && — and narrate before each so progress surfaces ` +
+  `incrementally. Do not stop early; complete all eight steps, then return a ` +
+  `one-line summary." Wait for the foreground sub-agent to finish, then send ` +
+  `me a brief reply telling me it's done.`;
+
+// The nested foreground block renders each child line prefixed with "↳"
+// (NESTED_PREFIX = "   ↳ "), newest as a bold "→ …" current step. Telegram
+// strips the bold but keeps the literal ↳ / → glyphs in message text.
+const NESTED_RE = /↳/;
+
+describe("uat: foreground sub-agent live activity nesting (#2032)", () => {
+  it(
+    "surfaces nested foreground activity in the feed AFTER the ack-first reply",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        await sc.sendDM(FG_DISPATCH_PROMPT);
+
+        // Ack-first reply — establishes replyCalled=true BEFORE the
+        // foreground sub-agent runs. This is the condition that broke #2027.
+        const ack = await sc.expectMessage(/.+/, {
+          from: "bot",
+          timeout: 60_000,
+        });
+        console.log(`[fg-activity UAT] ack-first reply: ${JSON.stringify(ack.text)}`);
+
+        // The activity-summary feed carrying the NESTED foreground narrative.
+        // First paint waits for the sub-agent to dispatch + narrate (~8s
+        // first-paint throttle), so give it a generous window. Its presence
+        // is the load-bearing proof of the fix: post-ack foreground activity.
+        const feed = await sc.expectMessage(NESTED_RE, {
+          from: "bot",
+          timeout: 90_000,
+        });
+        console.log(
+          `[fg-activity UAT] nested feed paint (id=${feed.messageId}): ${JSON.stringify(feed.text)}`,
+        );
+        expect(feed.messageId).toBeGreaterThan(0);
+        expect(feed.text).toMatch(NESTED_RE);
+
+        // Live edit: re-fetch the SAME message after the throttle + a few
+        // sub-agent steps. Body should change as the nested narrative
+        // advances — proving it's a live feed, not a one-shot post. Soft:
+        // log either way; the nested-paint above is the load-bearing proof.
+        const before = feed.text;
+        await new Promise((r) => setTimeout(r, 10_000));
+        const mid = await sc.driver.getMessage(sc.botUserId, feed.messageId);
+        console.log(
+          `[fg-activity UAT] same feed after 10s (id=${feed.messageId}): ${JSON.stringify(mid?.text ?? null)}`,
+        );
+
+        // Final answer — the parent resumes after the foreground sub-agent
+        // returns and reports done. The feed hands off (clears) to this
+        // answer. Confirms the turn completes cleanly, not wedged.
+        const done = await sc.expectMessage(/done|complete|finished|step-8|wrapped/i, {
+          from: "bot",
+          timeout: 120_000,
+        });
+        console.log(`[fg-activity UAT] final answer: ${JSON.stringify(done.text)}`);
+        expect(done.text.length).toBeGreaterThan(0);
+        // Did the nested narrative actually move while in flight?
+        if (mid?.text != null) {
+          console.log(
+            `[fg-activity UAT] body moved in-flight: ${mid.text !== before}`,
+          );
+        }
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    300_000,
+  );
+});