switchroom 0.14.92 → 0.14.93

package/package.json

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

@@ -47637,18 +47637,21 @@ class ObligationLedger {
     return best;
   }
   decideAtIdle(opts) {
-    const o = opts != null && opts.graceMs > 0 ? this.oldestEligible(opts.now, opts.graceMs) : this.oldest();
+    const useEligible = opts != null && (opts.graceMs > 0 || opts.backgroundWorkActive === true);
+    const o = useEligible ? this.oldestEligible(opts.now, opts.graceMs, opts.backgroundWorkActive === true, opts.backgroundGraceMs ?? 0) : this.oldest();
     if (o === undefined)
       return { action: "none" };
     if (o.representCount >= this.maxRepresents)
       return { action: "escalate", obligation: o };
     return { action: "represent", obligation: o };
   }
-  oldestEligible(now, graceMs) {
+  oldestEligible(now, graceMs, backgroundWorkActive, backgroundGraceMs) {
     let best;
     for (const o of this.open.values()) {
       if (o.lastTurnEndedAt != null && now - o.lastTurnEndedAt < graceMs)
         continue;
+      if (backgroundWorkActive && backgroundGraceMs > 0 && now - o.openedAt < backgroundGraceMs)
+        continue;
       if (best === undefined || o.openedAt < best.openedAt)
         best = o;
     }
@@ -52957,13 +52960,22 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
     return false;
   }
 }
+function readTurnActiveMarkerAgeMs(stateDir, now) {
+  const path = join32(stateDir, TURN_ACTIVE_MARKER_FILE2);
+  try {
+    const st = statSync10(path);
+    return (now ?? Date.now()) - st.mtimeMs;
+  } catch {
+    return null;
+  }
+}
 
 // ../src/build-info.ts
-var VERSION = "0.14.92";
-var COMMIT_SHA = "cd0b9973";
-var COMMIT_DATE = "2026-06-10T06:33:22+10:00";
+var VERSION = "0.14.93";
+var COMMIT_SHA = "87b62902";
+var COMMIT_DATE = "2026-06-10T08:22:44+10:00";
 var LATEST_PR = null;
-var COMMITS_AHEAD_OF_TAG = 6;
+var COMMITS_AHEAD_OF_TAG = 3;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -54188,6 +54200,14 @@ var OBLIGATION_ESCALATE_GRACE_MS = (() => {
   const n = Number(raw);
   return Number.isFinite(n) && n >= 0 ? n : 45000;
 })();
+var OBLIGATION_BACKGROUND_WORK_GRACE_MS = (() => {
+  const raw = process.env.SWITCHROOM_OBLIGATION_BACKGROUND_WORK_GRACE_MS;
+  if (raw == null || raw === "")
+    return 1200000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 1200000;
+})();
+var TURN_ACTIVE_MARKER_FRESH_MS = 90000;
 var AUTOCLASSIFY_MIDTURN_SHADOW = process.env.SWITCHROOM_AUTOCLASSIFY_MIDTURN_SHADOW !== "0";
 var lastAgentOutputAt = new Map;
 var LAST_OUTPUT_MAX_KEYS = 512;
@@ -55705,6 +55725,13 @@ var inboundSpool = STATIC ? undefined : createInboundSpool({
   }
 });
 var pendingInboundBuffer = createPendingInboundBuffer({ spool: inboundSpool });
+function agentHasInFlightBackgroundWork(now) {
+  if (countRunningWorkers() > 0)
+    return true;
+  const ageMs = readTurnActiveMarkerAgeMs(STATE_DIR, now);
+  return ageMs != null && ageMs < TURN_ACTIVE_MARKER_FRESH_MS;
+}
+var lastBgWorkDeferLogMs = 0;
 function obligationSweep() {
   if (!OBLIGATION_LEDGER_ENABLED)
     return;
@@ -55713,10 +55740,23 @@ function obligationSweep() {
   if (turnInFlightForGate())
     return;
   const agent = process.env.SWITCHROOM_AGENT_NAME ?? "";
-  const decision = obligationLedger.decideAtIdle(OBLIGATION_ESCALATE_GRACE_MS > 0 ? { now: Date.now(), graceMs: OBLIGATION_ESCALATE_GRACE_MS } : undefined);
+  const now = Date.now();
+  const backgroundWorkActive = OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 && agentHasInFlightBackgroundWork(now);
+  const decision = obligationLedger.decideAtIdle(OBLIGATION_ESCALATE_GRACE_MS > 0 || backgroundWorkActive ? {
+    now,
+    graceMs: OBLIGATION_ESCALATE_GRACE_MS,
+    backgroundWorkActive,
+    backgroundGraceMs: OBLIGATION_BACKGROUND_WORK_GRACE_MS
+  } : undefined);
   const o = decision.obligation;
-  if (decision.action === "none" || o == null)
+  if (decision.action === "none" || o == null) {
+    if (backgroundWorkActive && obligationLedger.hasOpen() && now - lastBgWorkDeferLogMs > 60000) {
+      lastBgWorkDeferLogMs = now;
+      process.stderr.write(`telegram gateway: obligation sweep deferred \u2014 in-flight autonomous sub-agent work ` + `(${obligationLedger.size()} open, bounded ${Math.round(OBLIGATION_BACKGROUND_WORK_GRACE_MS / 60000)}m from receipt)
+`);
+    }
     return;
+  }
   if (decision.action === "represent") {
     if (pendingInboundBuffer.depth(agent) > 0)
       return;

package/telegram-plugin/gateway/gateway.ts

@@ -429,6 +429,7 @@ import {
   touchTurnActiveMarker,
   removeTurnActiveMarker,
   sweepStaleTurnActiveMarker,
+  readTurnActiveMarkerAgeMs,
   TURN_ACTIVE_MARKER_FILE,
 } from './turn-active-marker.js'
 import {
@@ -1468,6 +1469,34 @@ const OBLIGATION_ESCALATE_GRACE_MS = (() => {
   return Number.isFinite(n) && n >= 0 ? n : 45_000
 })()
 
+// Background-work escalate-grace ceiling. The 45s grace above is far too short
+// for extended-autonomous sub-agent work: an agent that ack-firsts ("on it")
+// then delegates to a background worker OR an orphaned foreground sub-agent ends
+// its FOREGROUND turn in seconds, but the real answer lands minutes later. The
+// turn-in-flight machine (turn already ended) doesn't see that work, so the
+// sweep would re-present/escalate a false "⚠️ I may have missed this — re-send"
+// while the agent is genuinely researching (the gymbro liven-research case,
+// 2026-06-10). While `agentHasInFlightBackgroundWork()` holds, an open
+// obligation younger than THIS ceiling (from openedAt) is skipped. Bounded BY
+// CONSTRUCTION — a hard wall-clock ceiling, so even a stuck/leaked worker can't
+// suppress escalation forever; the obligation FSM still terminates. This also
+// preserves the represent budget across a restart that kills the work: with the
+// false represents suppressed, the hydrated obligation re-presents (resumes the
+// research) instead of prematurely escalating. Kill switch: =0 → pre-fix
+// behaviour (no background-work grace).
+const OBLIGATION_BACKGROUND_WORK_GRACE_MS = (() => {
+  const raw = process.env.SWITCHROOM_OBLIGATION_BACKGROUND_WORK_GRACE_MS
+  if (raw == null || raw === '') return 20 * 60_000 // 20 min — generous for real research, still bounded
+  const n = Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 20 * 60_000
+})()
+// Marker-freshness window for the orphaned-foreground signal. The turn-active
+// marker is touched on every foreground tool_use and on foreground sub-agent
+// JSONL growth, so an mtime younger than this means a sub-agent is touching it
+// RIGHT NOW; older ⇒ the work stopped (or the marker leaked) ⇒ not active.
+// Comfortably exceeds the sub-agent poll cadence so it doesn't flap.
+const TURN_ACTIVE_MARKER_FRESH_MS = 90_000
+
 // ─── Mid-turn auto-classify (steer-vs-queue), SHADOW mode ─────────────────────
 // Today a no-prefix mid-turn message always QUEUES. autoClassifyMidTurnInbound
 // (auto-classify-mid-turn.ts) is the basis for a smarter default using
@@ -5324,24 +5353,72 @@ const pendingInboundBuffer = createPendingInboundBuffer({ spool: inboundSpool })
 //       disconnect (disconnect-flush.ts), and by the 300s silence-poke watchdog;
 //   (3) the escalation send settles — bounded BY CONSTRUCTION via withDeadline
 //       below (grammy has no request timeout, so an unbounded send was the one
-//       way an obligation could get stuck OPEN forever — now closed).
+//       way an obligation could get stuck OPEN forever — now closed);
+//   (4) the background-work grace releases — an obligation skipped because
+//       agentHasInFlightBackgroundWork() is true is bounded by
+//       OBLIGATION_BACKGROUND_WORK_GRACE_MS (a hard wall-clock ceiling from
+//       openedAt). Even a permanently-stuck/leaked worker signal cannot suppress
+//       the act past the ceiling, so this adds NO unbounded liveness dependency:
+//       decideAtIdle ignores the work signal once now ≥ openedAt + ceiling, μ
+//       resumes decreasing, and termination still holds.
 // The only residual liveness assumption is the bridge eventually reconnecting /
 // the process restarting, which the entire gateway's inbound delivery already
 // depends on and which durable spool + boot-replay make self-healing.
+// True when the agent has in-flight autonomous sub-agent work the turn-in-flight
+// gate does NOT see: a running background worker (countRunningWorkers — its row
+// is INSERTed status='running' at dispatch, before the parent turn ends), OR an
+// orphaned/extended-autonomous FOREGROUND sub-agent that outlived its turn and is
+// still touching the turn-active marker (#2240; background activity deliberately
+// does NOT touch the parent marker, so the two signals are complementary).
+// Used ONLY by the obligation sweep to bound a false escalation during genuine
+// post-turn work. The caller already established the turn machine is idle (the
+// `turnInFlightForGate()` early-return), so a fresh marker here means orphaned
+// sub-agent activity (or a just-ended turn within the freshness window — a
+// harmless small extra grace, bounded by the ceiling either way).
+function agentHasInFlightBackgroundWork(now: number): boolean {
+  if (countRunningWorkers() > 0) return true
+  const ageMs = readTurnActiveMarkerAgeMs(STATE_DIR, now)
+  return ageMs != null && ageMs < TURN_ACTIVE_MARKER_FRESH_MS
+}
+// Throttle for the background-work defer diagnostic (the 5s sweep would otherwise
+// log every tick across a multi-minute research window).
+let lastBgWorkDeferLogMs = 0
 function obligationSweep(): void {
   if (!OBLIGATION_LEDGER_ENABLED) return
   if (!obligationLedger.hasOpen()) return
   if (turnInFlightForGate()) return // a turn is running — let it finish/answer
   const agent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+  const now = Date.now()
+  // Background-work grace: while genuine autonomous sub-agent work is in flight
+  // (a running worker, or an orphaned foreground sub-agent — neither visible to
+  // the turn machine), an obligation younger than the ceiling is NOT re-presented
+  // /escalated. Bounded by OBLIGATION_BACKGROUND_WORK_GRACE_MS so escalation
+  // always eventually fires. =0 disables it.
+  const backgroundWorkActive =
+    OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 && agentHasInFlightBackgroundWork(now)
   // Grace window: skip an obligation whose handling turn ended < grace ago — its
   // trailing slow/worker answer may still be landing (over-escalation fix).
   const decision = obligationLedger.decideAtIdle(
-    OBLIGATION_ESCALATE_GRACE_MS > 0
-      ? { now: Date.now(), graceMs: OBLIGATION_ESCALATE_GRACE_MS }
+    OBLIGATION_ESCALATE_GRACE_MS > 0 || backgroundWorkActive
+      ? {
+          now,
+          graceMs: OBLIGATION_ESCALATE_GRACE_MS,
+          backgroundWorkActive,
+          backgroundGraceMs: OBLIGATION_BACKGROUND_WORK_GRACE_MS,
+        }
       : undefined,
   )
   const o = decision.obligation
-  if (decision.action === 'none' || o == null) return
+  if (decision.action === 'none' || o == null) {
+    if (backgroundWorkActive && obligationLedger.hasOpen() && now - lastBgWorkDeferLogMs > 60_000) {
+      lastBgWorkDeferLogMs = now
+      process.stderr.write(
+        `telegram gateway: obligation sweep deferred — in-flight autonomous sub-agent work ` +
+          `(${obligationLedger.size()} open, bounded ${Math.round(OBLIGATION_BACKGROUND_WORK_GRACE_MS / 60_000)}m from receipt)\n`,
+      )
+    }
+    return
+  }
   if (decision.action === 'represent') {
     // Re-present goes through the bridge → buffer. Only the represent path is
     // gated on an empty buffer (let the existing drain run first, avoid

package/telegram-plugin/gateway/obligation-ledger.ts

@@ -187,22 +187,61 @@ export class ObligationLedger {
    * genuinely-stale one is still acted on while a freshly-ended one waits. Pure
    * (clock injected via opts.now, mirroring the builder convention). With no opts
    * (or graceMs<=0) this is the pre-grace behaviour exactly.
+   *
+   * BACKGROUND-WORK GRACE (opts.backgroundWorkActive): the 45s `graceMs` above is
+   * far too short for extended-autonomous sub-agent work — an agent that
+   * ack-firsts ("on it") then delegates to a background worker or an orphaned
+   * foreground sub-agent ends its FOREGROUND turn in seconds, but the real answer
+   * lands minutes later. The in-flight machine (turn already ended) does not see
+   * that work, so the sweep would re-present/escalate a false "did I miss this?
+   * re-send" while the agent is genuinely researching (the gymbro liven case,
+   * 2026-06-10). When the gateway reports `backgroundWorkActive` (a running worker
+   * or a freshly-touched turn-active marker), an obligation younger than
+   * `backgroundGraceMs` (measured from openedAt) is SKIPPED. Bounded BY
+   * CONSTRUCTION: `backgroundGraceMs` is a hard wall-clock ceiling, so even a
+   * pathologically-stuck/leaked worker cannot suppress the escalation forever —
+   * once openedAt+backgroundGraceMs passes, the obligation is acted on regardless
+   * of work state, and the FSM still terminates.
    */
-  decideAtIdle(opts?: { now: number; graceMs: number }): LedgerDecision {
-    const o =
-      opts != null && opts.graceMs > 0 ? this.oldestEligible(opts.now, opts.graceMs) : this.oldest()
+  decideAtIdle(opts?: {
+    now: number
+    graceMs: number
+    backgroundWorkActive?: boolean
+    backgroundGraceMs?: number
+  }): LedgerDecision {
+    const useEligible = opts != null && (opts.graceMs > 0 || opts.backgroundWorkActive === true)
+    const o = useEligible
+      ? this.oldestEligible(
+          opts!.now,
+          opts!.graceMs,
+          opts!.backgroundWorkActive === true,
+          opts!.backgroundGraceMs ?? 0,
+        )
+      : this.oldest()
     if (o === undefined) return { action: 'none' }
     if (o.representCount >= this.maxRepresents) return { action: 'escalate', obligation: o }
     return { action: 'represent', obligation: o }
   }
 
-  /** The oldest open obligation whose handling turn ended at least `graceMs` ago
-   *  (or never ended — a still-queued obligation has no lastTurnEndedAt and is
-   *  always eligible; it can't have a trailing answer in flight). */
-  private oldestEligible(now: number, graceMs: number): Obligation | undefined {
+  /** The oldest open obligation that is currently ELIGIBLE to act on — i.e. NOT
+   *  within either grace window:
+   *   - trailing-answer grace: its handling turn ended < `graceMs` ago (a queued
+   *     obligation with no lastTurnEndedAt can't have a trailing answer, so it is
+   *     always eligible on this axis); AND
+   *   - background-work grace: when `backgroundWorkActive`, it was opened <
+   *     `backgroundGraceMs` ago (genuine in-flight autonomous work — bounded by
+   *     the ceiling so a stale/leaked worker can't suppress escalation forever). */
+  private oldestEligible(
+    now: number,
+    graceMs: number,
+    backgroundWorkActive: boolean,
+    backgroundGraceMs: number,
+  ): Obligation | undefined {
     let best: Obligation | undefined
     for (const o of this.open.values()) {
-      if (o.lastTurnEndedAt != null && now - o.lastTurnEndedAt < graceMs) continue // within grace
+      if (o.lastTurnEndedAt != null && now - o.lastTurnEndedAt < graceMs) continue // trailing-answer grace
+      if (backgroundWorkActive && backgroundGraceMs > 0 && now - o.openedAt < backgroundGraceMs)
+        continue // in-flight autonomous work, bounded by the ceiling
       if (best === undefined || o.openedAt < best.openedAt) best = o
     }
     return best

package/telegram-plugin/gateway/turn-active-marker.ts

@@ -174,3 +174,25 @@ export function sweepStaleTurnActiveMarker(
     return false;
   }
 }
+
+/**
+ * Age (ms) of the turn-active marker's mtime, or null if the marker is
+ * absent/unstattable. The marker is touched on every foreground tool_use AND
+ * (via the subagent-watcher, #501) on foreground sub-agent JSONL growth — so a
+ * SMALL age means the agent, or an orphaned/extended-autonomous foreground
+ * sub-agent that outlived its turn (#2240), is actively working RIGHT NOW, even
+ * though the turn-in-flight machine has gone idle. A large age (or null) means
+ * the work stopped or the marker leaked. Used by the obligation sweep to avoid a
+ * false "did I miss this? re-send" escalation while genuine post-turn work is in
+ * flight. Pure read; clock injectable for tests. Never throws — a stat failure
+ * is reported as null (treated as "not working").
+ */
+export function readTurnActiveMarkerAgeMs(stateDir: string, now?: number): number | null {
+  const path = join(stateDir, TURN_ACTIVE_MARKER_FILE);
+  try {
+    const st = statSync(path);
+    return (now ?? Date.now()) - st.mtimeMs;
+  } catch {
+    return null; // ENOENT / unstattable → not working
+  }
+}

package/telegram-plugin/tests/obligation-determinism.test.ts

@@ -89,7 +89,13 @@ interface Sim {
   steps: number;
 }
 
-function runSchedule(msgs: Msg[], seed: number, graceMs = 0): Sim {
+function runSchedule(
+  msgs: Msg[],
+  seed: number,
+  graceMs = 0,
+  bgGraceMs = 0,
+  bgAlwaysActive = false,
+): Sim {
   const PATH = "/state/agent/telegram/obligations.json";
   const store = memStore();
   let ledger = new ObligationLedger(MAX_REPRESENTS, {
@@ -148,12 +154,23 @@ function runSchedule(msgs: Msg[], seed: number, graceMs = 0): Sim {
         threadId: 3,
         messageId: m.msgId,
         text: `msg ${m.id}`,
-        openedAt: 1000 + steps,
+        // When the background-work ceiling is exercised it is measured from
+        // openedAt against `clock`, so openedAt must live on the same virtual
+        // clock (the legacy proofs keep the tiny 1000+steps value — they never
+        // read openedAt against `now`).
+        openedAt: bgGraceMs > 0 ? clock : 1000 + steps,
       });
       deliverTurn(m.id); // original turn (attempt 0)
     } else if (open) {
       const decision =
-        graceMs > 0 ? ledger.decideAtIdle({ now: clock, graceMs }) : ledger.decideAtIdle();
+        graceMs > 0 || bgGraceMs > 0
+          ? ledger.decideAtIdle({
+              now: clock,
+              graceMs,
+              backgroundWorkActive: bgGraceMs > 0 && bgAlwaysActive,
+              backgroundGraceMs: bgGraceMs,
+            })
+          : ledger.decideAtIdle();
       if (decision.action === "none") {
         // Every open obligation is within its grace window — the sweep waits.
         // Advance the clock so grace deterministically expires; no livelock.
@@ -280,6 +297,49 @@ describe("obligation determinism — every inbound reaches a terminal, no silent
     }
   });
 
+  it("holds across 3000 schedules WITH background-work grace PERPETUALLY active (ceiling forces a terminal, never prevents one)", () => {
+    // The hardest case for the new bound: the agent appears to be doing
+    // autonomous sub-agent work for the ENTIRE run (backgroundWorkActive never
+    // clears). The ledger must still drive every obligation to its correct
+    // terminal — proving the OBLIGATION_BACKGROUND_WORK_GRACE_MS ceiling makes
+    // the suppression bounded BY CONSTRUCTION (no livelock, no silent loss), and
+    // that, like the trailing-answer grace, it only DELAYS: the terminal each
+    // message reaches is IDENTICAL to the no-grace run. If always-on terminates
+    // correctly, every intermittent work pattern does too (strictly less
+    // suppression).
+    const ANSWER = [0, 1, 2, 3, 99];
+    const ESCFAIL = [0, 1, 2, 3, 5];
+    const GRACE_MS = 45_000;
+    const BG_CEIL_MS = 20 * 60_000; // mirrors OBLIGATION_BACKGROUND_WORK_GRACE_MS default
+    for (let seed = 1; seed <= 3000; seed++) {
+      const r = rng(seed * 7919);
+      const n = 1 + Math.floor(r() * 5);
+      const msgs: Msg[] = [];
+      for (let i = 0; i < n; i++) {
+        const msgId = seed * 100 + i;
+        msgs.push({
+          id: `c:3#${msgId}`,
+          msgId,
+          answerOnAttempt: pick(ANSWER, r),
+          escalateFailsFor: pick(ESCFAIL, r),
+        });
+      }
+      const { terminals, steps } = runSchedule(msgs, seed * 104729, GRACE_MS, BG_CEIL_MS, true);
+      expect(steps).toBeLessThan(10_000); // ceiling forces progress — no bg-grace livelock
+      for (const m of msgs) {
+        const t = terminals.get(m.id);
+        expect(t, `bg seed=${seed} msg=${m.id} answer=${m.answerOnAttempt} escFail=${m.escalateFailsFor}`).toBeDefined();
+        if (m.answerOnAttempt <= MAX_REPRESENTS) {
+          expect(t).toBe("answered");
+        } else if (m.escalateFailsFor < ESCALATE_MAX) {
+          expect(t).toBe("escalation-delivered");
+        } else {
+          expect(t).toBe("escalation-give-up");
+        }
+      }
+    }
+  });
+
   it("a delivered-but-unanswered obligation survives a restart and is escalated, not lost", () => {
     // Deterministic single case: model NEVER answers, escalation succeeds first try,
     // with a restart forced mid-life via a seed that triggers the 0.15 branch.

package/telegram-plugin/tests/obligation-ledger.test.ts

@@ -326,3 +326,88 @@ describe("ObligationLedger — escalate-grace window (over-escalation fix)", ()
     expect(L.decideAtIdle({ now: 142000, graceMs: 45000 }).action).toBe("escalate");
   });
 });
+
+describe("ObligationLedger — background-work grace (extended-autonomous fix, gymbro 2026-06-10)", () => {
+  function input(id: string, openedAt: number) {
+    return { originTurnId: id, chatId: "-100123", threadId: 3, messageId: Number(id.split("#").pop() ?? 0), text: "research liven", openedAt };
+  }
+  // 20-min ceiling, mirroring OBLIGATION_BACKGROUND_WORK_GRACE_MS default.
+  const CEIL = 20 * 60_000;
+
+  it("skips an obligation younger than the ceiling while background work is active", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000)); // opened at t=1000
+    // 5 min later, a worker is running → genuine work in flight → wait.
+    expect(
+      L.decideAtIdle({ now: 1000 + 5 * 60_000, graceMs: 45000, backgroundWorkActive: true, backgroundGraceMs: CEIL }).action,
+    ).toBe("none");
+  });
+
+  it("acts once the obligation crosses the ceiling EVEN IF work is still active (bounded — no silent drop)", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000));
+    // 20m + 1s after openedAt, still flagged active → ceiling wins → act.
+    expect(
+      L.decideAtIdle({ now: 1000 + CEIL + 1000, graceMs: 45000, backgroundWorkActive: true, backgroundGraceMs: CEIL }).action,
+    ).toBe("represent");
+  });
+
+  it("backgroundWorkActive=false → no extra grace (pre-fix behaviour on this axis)", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000)); // still-queued, no turn end
+    expect(
+      L.decideAtIdle({ now: 2000, graceMs: 45000, backgroundWorkActive: false, backgroundGraceMs: CEIL }).action,
+    ).toBe("represent");
+  });
+
+  it("backgroundGraceMs=0 (kill switch) → work signal ignored, acts immediately", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000));
+    expect(
+      L.decideAtIdle({ now: 2000, graceMs: 45000, backgroundWorkActive: true, backgroundGraceMs: 0 }).action,
+    ).toBe("represent");
+  });
+
+  it("composes with the trailing-answer grace: both must clear before acting", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#1", 1000));
+    L.noteTurnEnded("c:3#1", 5000);
+    // turn-end grace cleared (60s later) but within bg ceiling + work active → still wait.
+    expect(
+      L.decideAtIdle({ now: 65000, graceMs: 45000, backgroundWorkActive: true, backgroundGraceMs: CEIL }).action,
+    ).toBe("none");
+    // same instant, work no longer active → trailing grace already clear → act.
+    expect(
+      L.decideAtIdle({ now: 65000, graceMs: 45000, backgroundWorkActive: false, backgroundGraceMs: CEIL }).action,
+    ).toBe("represent");
+  });
+
+  it("picks the oldest ELIGIBLE: a young in-work obligation does not block an ancient one past the ceiling", () => {
+    const L = new ObligationLedger();
+    L.openIfAbsent(input("c:3#old", 1000)); // ancient
+    L.openIfAbsent(input("c:3#new", 1000 + CEIL)); // opened CEIL later
+    const now = 1000 + CEIL + 5000; // old is past ceiling; new is only 5s old
+    const d = L.decideAtIdle({ now, graceMs: 45000, backgroundWorkActive: true, backgroundGraceMs: CEIL });
+    expect(d.action).toBe("represent");
+    expect(d.obligation?.originTurnId).toBe("c:3#old");
+  });
+
+  it("represent budget is preserved across the work window → resumes (not escalates) after a restart-kill", () => {
+    // Models the gymbro case: while the worker runs, the sweep must NOT burn the
+    // represent ladder. So after a restart kills the work (work now inactive),
+    // a never-represented obligation re-presents (resume) rather than escalates.
+    const L = new ObligationLedger(2);
+    L.openIfAbsent(input("c:3#1", 1000));
+    // During the work window, every sweep is a no-op (no markRepresented called).
+    for (const t of [60_000, 120_000, 300_000]) {
+      expect(
+        L.decideAtIdle({ now: t, graceMs: 45000, backgroundWorkActive: true, backgroundGraceMs: CEIL }).action,
+      ).toBe("none");
+    }
+    expect(L.list()[0].representCount).toBe(0); // budget intact
+    // Restart kills the work; obligation hydrated with representCount 0 → resume.
+    expect(
+      L.decideAtIdle({ now: 360_000, graceMs: 45000, backgroundWorkActive: false, backgroundGraceMs: CEIL }).action,
+    ).toBe("represent");
+  });
+});

package/telegram-plugin/tests/turn-active-marker.test.ts

@@ -14,6 +14,7 @@ import {
   touchTurnActiveMarker,
   removeTurnActiveMarker,
   sweepStaleTurnActiveMarker,
+  readTurnActiveMarkerAgeMs,
 } from '../gateway/turn-active-marker.js'
 
 describe('turn-active-marker (#412)', () => {
@@ -192,4 +193,31 @@ describe('turn-active-marker (#412)', () => {
     const mode = statSync(path).mode & 0o777
     expect(mode).toBe(0o600)
   })
+
+  // readTurnActiveMarkerAgeMs — the orphaned-foreground "agent still working"
+  // signal for the obligation sweep (#2240 / gymbro 2026-06-10).
+  it('readTurnActiveMarkerAgeMs returns null when the marker is absent', () => {
+    expect(readTurnActiveMarkerAgeMs(tmp)).toBeNull()
+  })
+
+  it('readTurnActiveMarkerAgeMs returns a small age for a fresh marker', () => {
+    writeTurnActiveMarker(tmp, { turnKey: 'k', chatId: 'c', threadId: null, startedAt: 1 })
+    const age = readTurnActiveMarkerAgeMs(tmp)
+    expect(age).not.toBeNull()
+    // |age| is tiny for a just-written marker. It can be a hair negative when the
+    // filesystem mtime resolves slightly ahead of Date.now() — that's fine; what
+    // matters for the freshness signal is the small magnitude.
+    expect(Math.abs(age!)).toBeLessThan(5_000)
+  })
+
+  it('readTurnActiveMarkerAgeMs reflects a stale (back-dated) mtime against an injected clock', () => {
+    const path = join(tmp, TURN_ACTIVE_MARKER_FILE)
+    writeTurnActiveMarker(tmp, { turnKey: 'k', chatId: 'c', threadId: null, startedAt: 1 })
+    const tenMinAgo = new Date(Date.now() - 10 * 60_000)
+    utimesSync(path, tenMinAgo, tenMinAgo)
+    const now = tenMinAgo.getTime() + 10 * 60_000
+    const age = readTurnActiveMarkerAgeMs(tmp, now)
+    expect(age).not.toBeNull()
+    expect(Math.abs(age! - 10 * 60_000)).toBeLessThan(50) // ~10 min old
+  })
 })