switchroom 0.16.46 → 0.17.0

package/telegram-plugin/tests/slot-banner-boot-recovery.test.ts

@@ -0,0 +1,246 @@
+/**
+ * slot-banner boot-recovery (#421) — the crash-recovery path for the pinned
+ * OAuth slot banner, exercised against the REAL shared status-pin store +
+ * the REAL banner driver the gateway wires up.
+ *
+ * The bug this guards: the slot banner's pin state used to live ONLY in a
+ * module-global `let pinnedBannerState`. A gateway restart while a banner was
+ * pinned lost that record, so the orphaned banner stayed pinned forever. The
+ * fix routes the banner pin THROUGH the same status-pins.json store (a distinct
+ * `banner:` pinKey), so the ONE existing runStatusPinBootCleanup unpins it on
+ * boot — no parallel store, no second boot hook.
+ *
+ * We model the gateway's banner-persistence wiring faithfully with the SAME
+ * functions gateway.ts calls (refreshBanner + its persist hooks →
+ * persistStatusPins; runStatusPinBootCleanup) over an in-memory fs + a fake
+ * Telegram whose pin set we can inspect. A regression in the ordering / cleanup
+ * contract reds here.
+ *
+ * Variants:
+ *   (A) confirmed banner pin → crash before any clean unpin → recovered next boot.
+ *   (B) pending banner pin (crash INSIDE the persist-after-pin window) →
+ *       recovered next boot.
+ *   (C) clean unpin (return to default slot) → nothing left for boot cleanup.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  loadStatusPins,
+  persistStatusPins,
+  runStatusPinBootCleanup,
+  type PersistedStatusPin,
+  type StatusPinStoreFsSeam,
+} from "../gateway/status-pin-store.js";
+import { refreshBanner } from "../slot-banner-driver.js";
+import type { BannerState } from "../slot-banner.js";
+
+const PATH = "/state/agent/telegram/status-pins.json";
+const OWNER = "-100999";
+const AGENT = "clerk";
+const DEFAULT = "default";
+const BANNER_PIN_KEY = "banner:owner";
+
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed));
+  const fs: StatusPinStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`);
+      return files.get(p)!;
+    },
+    writeFileSync: (p, d) => files.set(p, d),
+    renameSync: (a, b) => {
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`);
+      files.set(b, files.get(a)!);
+      files.delete(a);
+    },
+    existsSync: (p) => files.has(p),
+  };
+  return { fs, files };
+}
+
+/** A fake Telegram that records the current pinned message set per chat, plus a
+ *  monotonic message-id source for sends, so we can assert an orphan is left
+ *  pinned after a crash and unpinned after boot. */
+function fakeTelegram(startMessageId = 500) {
+  const pinned = new Set<string>(); // `${chatId}:${messageId}`
+  let nextId = startMessageId;
+  return {
+    pinned,
+    bot: {
+      api: {
+        sendRichMessage: async (chat_id: string | number) => {
+          void chat_id;
+          return { message_id: nextId++ };
+        },
+        pinChatMessage: async (chat_id: string | number, message_id: number) => {
+          pinned.add(`${chat_id}:${message_id}`);
+        },
+        unpinChatMessage: async (chat_id: string | number, message_id: number) => {
+          pinned.delete(`${chat_id}:${message_id}`);
+        },
+        // Unused by the pin path but required by the BannerBotApi surface.
+        sendMessage: async (chat_id: string | number) => {
+          void chat_id;
+          return { message_id: nextId++ };
+        },
+        editMessageText: async () => undefined,
+      },
+    },
+  };
+}
+
+/**
+ * A faithful stand-in for the gateway's slot-banner persistence wiring — the
+ * SAME shape as gateway.ts's `persistBannerRow` + `snapshotStatusPins` (which
+ * folds the banner row into the shared status-pin set) + the banner driver's
+ * persist hooks + the ONE runStatusPinBootCleanup, with injectable fs + api so a
+ * single test can span a "crash" and a fresh boot.
+ */
+function makeGateway(fs: StatusPinStoreFsSeam, tg: ReturnType<typeof fakeTelegram>) {
+  let bannerPersistedRow: PersistedStatusPin | null = null;
+  let pinnedBannerState: BannerState | null = null;
+
+  // Mirrors gateway.ts snapshotStatusPins(): map-backed status pins (none in
+  // this isolated harness) PLUS the banner row.
+  const snapshotStatusPins = (): PersistedStatusPin[] =>
+    bannerPersistedRow ? [bannerPersistedRow] : [];
+
+  const persistBannerRow = (row: PersistedStatusPin | null): void => {
+    bannerPersistedRow = row;
+    persistStatusPins(PATH, fs, snapshotStatusPins(), () => {});
+  };
+
+  async function refreshPinnedBanner(currentSlot: string | null) {
+    pinnedBannerState = await refreshBanner({
+      bot: tg.bot as never,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot,
+      defaultSlot: DEFAULT,
+      prevState: pinnedBannerState,
+      onError: () => {},
+      persist: {
+        pending: (chatId, messageId) =>
+          persistBannerRow({ pinKey: BANNER_PIN_KEY, chatId, messageId, pending: true }),
+        confirm: (chatId, messageId) =>
+          persistBannerRow({ pinKey: BANNER_PIN_KEY, chatId, messageId }),
+        clear: () => persistBannerRow(null),
+      },
+    });
+  }
+
+  async function bootCleanup() {
+    return runStatusPinBootCleanup({
+      path: PATH,
+      fs,
+      unpin: (chatId, messageId) => tg.bot.api.unpinChatMessage(chatId, messageId),
+      log: () => {},
+    });
+  }
+
+  return {
+    refreshPinnedBanner,
+    bootCleanup,
+    get bannerState() {
+      return pinnedBannerState;
+    },
+  };
+}
+
+describe("slot-banner boot recovery (gateway wiring)", () => {
+  it("(A) confirmed banner pin → crash → next boot unpins the orphan + empties the store", async () => {
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+
+    // ── Session 1: agent fails over to a non-default slot → banner pinned. ──
+    const gw1 = makeGateway(fs, tg);
+    await gw1.refreshPinnedBanner("personal");
+
+    // Banner is live in Telegram and recorded on disk (confirmed).
+    expect(gw1.bannerState?.slot).toBe("personal");
+    const msgId = gw1.bannerState!.messageId;
+    expect(tg.pinned.has(`${OWNER}:${msgId}`)).toBe(true);
+    expect(loadStatusPins(PATH, fs)).toEqual([
+      { pinKey: BANNER_PIN_KEY, chatId: OWNER, messageId: msgId },
+    ]);
+
+    // ── CRASH: no clean unpin runs; gw1's in-memory state vanishes. ──
+    expect(tg.pinned.has(`${OWNER}:${msgId}`)).toBe(true);
+
+    // ── Session 2: brand-new gateway, empty state, SAME on-disk store. ──
+    const gw2 = makeGateway(fs, tg);
+    const res = await gw2.bootCleanup();
+
+    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(tg.pinned.has(`${OWNER}:${msgId}`)).toBe(false); // orphan unpinned
+    expect(loadStatusPins(PATH, fs)).toEqual([]); // store emptied
+  });
+
+  it("(B) pending banner pin (crash inside the persist-after-pin window) → recovered next boot", async () => {
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+
+    // Simulate the exact crash window: the message is sent + the pending record
+    // written, the pin API lands, then the process dies before the confirm
+    // rewrite. We reproduce that by calling refreshBanner but faulting the
+    // confirm hook (stands in for a SIGKILL between pin and confirm).
+    const bannerRow: PersistedStatusPin[] = [];
+    const persistRow = (row: PersistedStatusPin | null) => {
+      bannerRow.length = 0;
+      if (row) bannerRow.push(row);
+      persistStatusPins(PATH, fs, [...bannerRow], () => {});
+    };
+
+    await refreshBanner({
+      bot: tg.bot as never,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: "personal",
+      defaultSlot: DEFAULT,
+      prevState: null,
+      onError: () => {},
+      persist: {
+        pending: (chatId, messageId) =>
+          persistRow({ pinKey: BANNER_PIN_KEY, chatId, messageId, pending: true }),
+        // The confirm rewrite never runs (crash). The driver guards the hook,
+        // so throwing here models the process dying at exactly that point while
+        // leaving the pending record + live pin behind.
+        confirm: () => {
+          throw new Error("SIGKILL before confirm rewrite");
+        },
+        clear: () => persistRow(null),
+      },
+    });
+
+    // Orphan is live in Telegram; a PENDING record is on disk.
+    const rec = loadStatusPins(PATH, fs);
+    expect(rec).toHaveLength(1);
+    expect(rec[0].pending).toBe(true);
+    expect(tg.pinned.has(`${OWNER}:${rec[0].messageId}`)).toBe(true);
+
+    // Fresh boot recovers it from the pending record.
+    const gw2 = makeGateway(fs, tg);
+    const res = await gw2.bootCleanup();
+    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(tg.pinned.has(`${OWNER}:${rec[0].messageId}`)).toBe(false);
+    expect(loadStatusPins(PATH, fs)).toEqual([]);
+  });
+
+  it("(C) clean return to default slot unpins + drops the record → boot cleanup is a no-op", async () => {
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+    const gw1 = makeGateway(fs, tg);
+
+    await gw1.refreshPinnedBanner("personal");
+    const msgId = gw1.bannerState!.messageId;
+    expect(tg.pinned.has(`${OWNER}:${msgId}`)).toBe(true);
+
+    // Return to default: banner unpins and drops its persisted claim.
+    await gw1.refreshPinnedBanner(DEFAULT);
+    expect(gw1.bannerState).toBeNull();
+    expect(tg.pinned.has(`${OWNER}:${msgId}`)).toBe(false);
+    expect(loadStatusPins(PATH, fs)).toEqual([]);
+
+    const gw2 = makeGateway(fs, tg);
+    expect(await gw2.bootCleanup()).toEqual({ cleared: 0, total: 0 });
+  });
+});

package/telegram-plugin/tests/status-pin-boot-recovery.test.ts

@@ -28,7 +28,6 @@ import {
   persistStatusPins,
   reconcileAndPersistStatusPin,
   runStatusPinBootCleanup,
-  type PersistedStatusPin,
   type StatusPinStoreFsSeam,
 } from "../gateway/status-pin-store.js";
 import { reconcilePin } from "../status-pin-driver.js";
@@ -81,17 +80,6 @@ function makeGateway(fs: StatusPinStoreFsSeam, tg: ReturnType<typeof fakeTelegra
   const statusPinState = new Map<string, PinState>();
   const statusPinChatIds = new Map<string, string>();
 
-  const snapshotExcept = (exceptKey: string): PersistedStatusPin[] => {
-    const out: PersistedStatusPin[] = [];
-    for (const [pinKey, st] of statusPinState) {
-      if (pinKey === exceptKey) continue;
-      const chatId = statusPinChatIds.get(pinKey);
-      if (chatId == null) continue;
-      out.push({ pinKey, chatId, messageId: st.messageId });
-    }
-    return out;
-  };
-
   async function reconcileStatusPin(pinKey: string, chatId: string, desired: DesiredPin) {
     const prev = statusPinState.get(pinKey) ?? null;
     const action = decidePinAction(prev, desired);
@@ -105,7 +93,6 @@ function makeGateway(fs: StatusPinStoreFsSeam, tg: ReturnType<typeof fakeTelegra
       pinKey,
       chatId,
       op,
-      snapshotOthers: () => snapshotExcept(pinKey),
       applyPin: () =>
         reconcilePin({ api: tg.api, chatId, prevState: prev, desired }),
       log: () => {},
@@ -173,7 +160,6 @@ describe("status-pin boot recovery (gateway wiring)", () => {
         pinKey: "fg:c:3",
         chatId: "-100123",
         op: { kind: "pin", messageId: 715 },
-        snapshotOthers: () => [],
         applyPin: async () => {
           await tg.api.pinChatMessage("-100123", 715); // pin lands in Telegram
           throw new Error("SIGKILL before confirm rewrite");

package/telegram-plugin/tests/status-pin-store.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import {
   loadStatusPins,
+  mutateStatusPinRow,
   persistStatusPins,
   pinnedMessageIsOurs,
   reconcileAndPersistStatusPin,
@@ -258,6 +259,193 @@ describe("runStatusPinBootCleanup", () => {
   });
 });
 
+/**
+ * Concurrency race (multiple writers of status-pins.json). The store has two
+ * concurrent writers: `reconcileAndPersistStatusPin` (fg:/wk: rows) and
+ * `mutateStatusPinRow` (the banner:owner row). The race: a `pending` row is
+ * written to disk BEFORE the applyPin network call; if a SECOND writer runs
+ * DURING that await window and rebuilds the file, it can drop the in-flight
+ * pending/confirmed row. The per-path lock + read-modify-write must close it —
+ * BOTH rows survive.
+ */
+describe("status-pin-store — concurrent-writer race", () => {
+  it("a banner persist DURING the applyPin await window does NOT drop the status pin's pending row", async () => {
+    const { fs } = memFs();
+
+    // applyPin is a promise we control: it resolves only when we let it, so we
+    // can fire a concurrent writer squarely inside the await window.
+    let releaseApplyPin!: () => void;
+    const applyPinGate = new Promise<void>((r) => {
+      releaseApplyPin = r;
+    });
+    // Snapshot what's on disk at the moment the pin API is invoked (proves the
+    // pending row was written before the network call).
+    let onDiskAtPin: PersistedStatusPin[] = [];
+
+    const reconcile = reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      op: { kind: "pin", messageId: 715 },
+      applyPin: async () => {
+        onDiskAtPin = loadStatusPins(PATH, fs);
+        await applyPinGate; // in-flight: hold the pin open
+        return { messageId: 715 };
+      },
+      log: () => {},
+    });
+
+    // Let the reconcile reach its applyPin await (pending row now on disk).
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(onDiskAtPin).toEqual([
+      { pinKey: "fg:c:3", chatId: "-100123", messageId: 715, pending: true },
+    ]);
+
+    // Fire the banner persist DURING the await window. Under the per-path lock
+    // it must serialise AFTER the reconcile completes — its read-modify-write
+    // then sees the confirmed fg: row and preserves it.
+    const bannerPersist = mutateStatusPinRow(
+      PATH,
+      fs,
+      "banner:owner",
+      { pinKey: "banner:owner", chatId: "-100999", messageId: 42 },
+      () => {},
+    );
+
+    // Now release the pin so the reconcile confirms.
+    releaseApplyPin();
+    await reconcile;
+    await bannerPersist;
+
+    // BOTH rows survive: the status pin was NOT dropped by the concurrent
+    // banner write (the pre-fix bug), and the banner row is present.
+    const loaded = loadStatusPins(PATH, fs);
+    expect(loaded).toContainEqual({
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      messageId: 715,
+    });
+    expect(loaded).toContainEqual({
+      pinKey: "banner:owner",
+      chatId: "-100999",
+      messageId: 42,
+    });
+    expect(loaded).toHaveLength(2);
+  });
+
+  it("two concurrent key reconciles both survive (no lost pending row)", async () => {
+    const { fs } = memFs();
+
+    let releaseA!: () => void;
+    const gateA = new Promise<void>((r) => {
+      releaseA = r;
+    });
+
+    const reconcileA = reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      op: { kind: "pin", messageId: 715 },
+      applyPin: async () => {
+        await gateA;
+        return { messageId: 715 };
+      },
+      log: () => {},
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Second key's reconcile fires while A's pin is in-flight. Serialised by the
+    // lock, it runs after A confirms — its read-modify-write preserves A's row.
+    const reconcileB = reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey: "wk:agent-x",
+      chatId: "-100999",
+      op: { kind: "pin", messageId: 42 },
+      applyPin: async () => ({ messageId: 42 }),
+      log: () => {},
+    });
+
+    releaseA();
+    await reconcileA;
+    await reconcileB;
+
+    const loaded = loadStatusPins(PATH, fs);
+    expect(loaded).toContainEqual({
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      messageId: 715,
+    });
+    expect(loaded).toContainEqual({
+      pinKey: "wk:agent-x",
+      chatId: "-100999",
+      messageId: 42,
+    });
+    expect(loaded).toHaveLength(2);
+  });
+
+  // This is the case the LOCK (not just per-key RMW) is required for: two
+  // overlapping ops on the SAME pinKey. Different-key writers survive with or
+  // without serialisation (RMW alone preserves them), so the two tests above
+  // pass even against a no-op lock. Here a `clear` races a `pin` on one key:
+  // without the lock the clear runs inside the pin's await window, removes the
+  // pending row, and the pin's later confirm RESURRECTS a pin that was meant to
+  // be cleared. With the FIFO lock the clear waits until the pin fully confirms,
+  // then removes it — final state is correctly empty. Asserting absence is what
+  // distinguishes the real lock from a no-op one.
+  it("a clear racing a pin on the SAME key does not resurrect the cleared pin", async () => {
+    const { fs } = memFs();
+
+    let releasePin!: () => void;
+    const pinGate = new Promise<void>((r) => {
+      releasePin = r;
+    });
+
+    // Pin op acquires the lock first and holds it across its applyPin await.
+    const pin = reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      op: { kind: "pin", messageId: 715 },
+      applyPin: async () => {
+        await pinGate;
+        return { messageId: 715 };
+      },
+      log: () => {},
+    });
+    // Reach the applyPin await — pending row now on disk, lock held.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Clear the SAME key while the pin is in-flight. FIFO-serialised behind the
+    // pin, it must run only AFTER the pin confirms, leaving the key removed.
+    const clear = reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      op: { kind: "clear" },
+      applyPin: async () => null,
+      log: () => {},
+    });
+
+    releasePin();
+    await pin;
+    await clear;
+
+    // The later-submitted clear wins: the key is gone, NOT resurrected by the
+    // pin's confirm write (which would happen under a no-op lock).
+    const loaded = loadStatusPins(PATH, fs);
+    expect(loaded.find((r) => r.pinKey === "fg:c:3")).toBeUndefined();
+    expect(loaded).toHaveLength(0);
+  });
+});
+
 /**
  * Envelope versioning — a v1 snapshot (no `pending` field) must still load
  * fail-open as a confirmed pin, and v2 must round-trip the `pending` flag.
@@ -322,7 +510,6 @@ describe("reconcileAndPersistStatusPin — persist-before-pin ordering", () => {
       pinKey: "fg:c:3",
       chatId: "-100123",
       op: { kind: "pin", messageId: 715 },
-      snapshotOthers: () => [],
       applyPin: async () => {
         order.push("pin-api");
         onDiskAtPin = loadStatusPins(PATH, fs);
@@ -354,7 +541,6 @@ describe("reconcileAndPersistStatusPin — persist-before-pin ordering", () => {
         pinKey: "fg:c:3",
         chatId: "-100123",
         op: { kind: "pin", messageId: 715 },
-        snapshotOthers: () => [],
         applyPin: async () => {
           pinnedInTelegram = 715; // the pin landed in Telegram
           throw new Error("SIGKILL — process died before confirm rewrite");
@@ -395,7 +581,6 @@ describe("reconcileAndPersistStatusPin — persist-before-pin ordering", () => {
       pinKey: "fg:c:3",
       chatId: "-100123",
       op: { kind: "pin", messageId: 715 },
-      snapshotOthers: () => [],
       // reconcilePin returns null (prevState) when the pin API throws.
       applyPin: async () => null,
       log: () => {},
@@ -412,13 +597,15 @@ describe("reconcileAndPersistStatusPin — persist-before-pin ordering", () => {
       chatId: "-100999",
       messageId: 42,
     };
+    // Others now come from the on-disk file (read-modify-write), not a caller
+    // snapshot — seed the other key's row on disk first.
+    persistStatusPins(PATH, fs, [other]);
     await reconcileAndPersistStatusPin({
       path: PATH,
       fs,
       pinKey: "fg:c:3",
       chatId: "-100123",
       op: { kind: "pin", messageId: 715 },
-      snapshotOthers: () => [other],
       applyPin: async () => ({ messageId: 715 }),
       log: () => {},
     });
@@ -431,6 +618,35 @@ describe("reconcileAndPersistStatusPin — persist-before-pin ordering", () => {
     });
   });
 
+  it("uses on-disk OTHER rows (not a memory snapshot) — an on-disk key is preserved", async () => {
+    // The banner (or another key's) row can exist ON DISK without the reconcile
+    // caller knowing about it. Read-modify-write must carry it through.
+    const { fs } = memFs();
+    persistStatusPins(PATH, fs, [
+      { pinKey: "banner:owner", chatId: "-100999", messageId: 42 },
+    ]);
+    await reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      op: { kind: "pin", messageId: 715 },
+      applyPin: async () => ({ messageId: 715 }),
+      log: () => {},
+    });
+    const loaded = loadStatusPins(PATH, fs);
+    expect(loaded).toContainEqual({
+      pinKey: "banner:owner",
+      chatId: "-100999",
+      messageId: 42,
+    });
+    expect(loaded).toContainEqual({
+      pinKey: "fg:c:3",
+      chatId: "-100123",
+      messageId: 715,
+    });
+  });
+
   it("clear op: unpins then drops the record (post-pin ordering is safe)", async () => {
     const { fs } = memFs();
     persistStatusPins(PATH, fs, [pin({ pinKey: "fg:c:3", messageId: 715 })]);
@@ -440,7 +656,6 @@ describe("reconcileAndPersistStatusPin — persist-before-pin ordering", () => {
       pinKey: "fg:c:3",
       chatId: "-100123",
       op: { kind: "clear" },
-      snapshotOthers: () => [],
       applyPin: async () => null,
       log: () => {},
     });

package/telegram-plugin/tests/status-query-telemetry.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Truthful `status-query` telemetry — issue #109 (truthful-telemetry PR).
+ *
+ * Regression guard for a lying diagnostic: the mid-turn "status?" telemetry
+ * used to peek the pinned progress card via `progressDriver.peek(...)`. That
+ * card was retired (#1122/#1126) and `progressDriver` is now permanently null,
+ * so the peek ALWAYS reported idle/zero regardless of live background work.
+ * These tests assert the replacement reads the LIVE surfaces:
+ *
+ *   - a running background worker (or an active turn, feed entry, or pending
+ *     async dispatch) ⇒ NON-idle ⇒ NO false `ux-failure`;
+ *   - nothing running AND no active turn ⇒ idle ⇒ `ux-failure` emitted.
+ *
+ * The peek path previously had NO coverage — this closes that.
+ */
+import { describe, it, expect } from 'bun:test'
+import {
+  deriveStatusQueryTelemetry,
+  formatStatusQueryLine,
+  formatStatusQueryUxFailureLine,
+  type StatusQuerySurfaces,
+} from '../status-query-telemetry.js'
+
+const IDLE: StatusQuerySurfaces = {
+  turnActive: false,
+  turnAgeS: -1,
+  runningWorkers: 0,
+  workerFeedSize: 0,
+  pendingAsync: 0,
+}
+
+describe('status-query telemetry — reads the live surfaces', () => {
+  it('a running background worker ⇒ non-idle (no false ux-failure)', () => {
+    const t = deriveStatusQueryTelemetry({ ...IDLE, runningWorkers: 1 })
+    expect(t.idle).toBe(false)
+    expect(t.stage).toBe('background-work')
+  })
+
+  it('a tracked 🛠 Worker feed entry ⇒ non-idle', () => {
+    const t = deriveStatusQueryTelemetry({ ...IDLE, workerFeedSize: 2 })
+    expect(t.idle).toBe(false)
+    expect(t.stage).toBe('background-work')
+  })
+
+  it('a cross-turn pending-async dispatch ⇒ non-idle', () => {
+    const t = deriveStatusQueryTelemetry({ ...IDLE, pendingAsync: 1 })
+    expect(t.idle).toBe(false)
+    expect(t.stage).toBe('background-work')
+  })
+
+  it('an active turn ⇒ non-idle, stage turn-active', () => {
+    const t = deriveStatusQueryTelemetry({ ...IDLE, turnActive: true, turnAgeS: 12 })
+    expect(t.idle).toBe(false)
+    expect(t.stage).toBe('turn-active')
+  })
+
+  it('an active turn with a background worker still reports turn-active', () => {
+    const t = deriveStatusQueryTelemetry({
+      ...IDLE,
+      turnActive: true,
+      turnAgeS: 3,
+      runningWorkers: 1,
+    })
+    expect(t.idle).toBe(false)
+    expect(t.stage).toBe('turn-active')
+  })
+
+  it('nothing running AND no active turn ⇒ idle ⇒ ux-failure', () => {
+    const t = deriveStatusQueryTelemetry(IDLE)
+    expect(t.idle).toBe(true)
+    expect(t.stage).toBe('idle')
+  })
+
+  it('treats negative/garbage counts as empty (defensive) ⇒ idle', () => {
+    const t = deriveStatusQueryTelemetry({
+      ...IDLE,
+      runningWorkers: -1,
+      workerFeedSize: -3,
+      pendingAsync: -1,
+    })
+    expect(t.idle).toBe(true)
+  })
+})
+
+describe('status-query telemetry — log line formatting', () => {
+  it('primary line carries the "status-query" anchor and live fields', () => {
+    const s: StatusQuerySurfaces = {
+      turnActive: false,
+      turnAgeS: -1,
+      runningWorkers: 3,
+      workerFeedSize: 1,
+      pendingAsync: 0,
+    }
+    const line = formatStatusQueryLine('klanker', '123', 'none', s, deriveStatusQueryTelemetry(s))
+    expect(line).toContain('status-query')
+    expect(line).not.toContain('ux-failure')
+    expect(line).toContain('stage=background-work')
+    expect(line).toContain('running_workers=3')
+    expect(line).toContain('worker_feed=1')
+    expect(line).toContain('turn_age_s=-1')
+    expect(line).toContain('agent=klanker')
+    // The retired card fields must be gone — parsers keyed on them would
+    // otherwise silently read zeros forever.
+    expect(line).not.toContain('card_stage')
+    expect(line).not.toContain('card_subagents')
+    expect(line).not.toContain('card_items')
+  })
+
+  it('ux-failure line carries the "ux-failure: status-query" anchor', () => {
+    const line = formatStatusQueryUxFailureLine('klanker', '123', 'none')
+    expect(line).toContain('ux-failure: status-query')
+    expect(line).toContain('stage=idle')
+    expect(line).toContain('running_workers=0')
+  })
+})