switchroom 0.18.6 → 0.18.8

package/telegram-plugin/typing-wrap.ts

@@ -1,10 +1,15 @@
 // Auto-wrap tool dispatch with a Telegram typing-indicator loop so the user
-// sees a live "agent is working" signal during the 3–30s gap where the
-// progress card is deliberately suppressed (its initialDelayMs is 3s).
-// The first tool call on a given (chat, thread) fires the typing loop
-// immediately so there's no silent dead window before the progress card
-// appears. Subsequent calls on the same lane honour the debounce to avoid
-// churn. Surface tools own their own loop — see isSurfaceTool.
+// sees a live "agent is working" signal for the run of a turn. This is now
+// the PRIMARY liveness signal for short tool-using turns, not a bridge to a
+// soon-to-appear pinned progress card: the pinned card is retired
+// (`unpinProgressCardForChat = null`, see
+// `docs/diagrams/deterministic-status-anatomy.spec.md`), and the worker
+// progress card only gates in at `elapsed >= 60s OR sub-agent appeared` — for
+// most short turns it never appears at all. The first tool call on a given
+// (chat, thread) fires the typing loop immediately so there's no silent dead
+// window at turn start. Subsequent calls on the same lane honour the
+// debounce to avoid churn. Surface tools own their own loop — see
+// isSurfaceTool.
 //
 // Keying changed from `chatId` to `(chatId, threadId)` in PR3 of the
 // supergroup-mode rollout. In supergroup mode one agent owns many topics
@@ -38,17 +43,55 @@ export interface TypingWrapper {
 interface Entry {
   chatId: string
   threadId: number | null
+  lane: string
   timer: ReturnType<typeof setTimeout>
+}
+
+/**
+ * Per-lane bookkeeping: `count` is the number of outstanding (dispatched but
+ * not yet resulted) tool-uses on the lane; `started` is whether the typing
+ * loop is currently believed to be running for it. Ref-counted rather than a
+ * boolean-per-lane `Set` (pre-fix#7 shape) because two PARALLEL tool_use
+ * blocks on one lane must both hold the lane open: with a plain Set,
+ * `onToolResult` for the first one deleted the lane and stopped the loop
+ * while the second tool was still running, flickering the typing indicator
+ * off until the next tool re-fired it. Only the count reaching zero may stop
+ * the loop.
+ */
+interface LaneState {
+  count: number
   started: boolean
 }
 
 export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
   const debounceMs = deps.debounceMs ?? 500
   const pending = new Map<string, Entry>()
-  // Track per-(chat,thread) lanes that already have an active typing loop
-  // so the first tool call on a lane fires immediately while subsequent
-  // calls on the same lane use the debounce.
-  const activeLanes = new Set<string>()
+  const lanes = new Map<string, LaneState>()
+
+  function laneFor(lane: string): LaneState {
+    let s = lanes.get(lane)
+    if (s == null) {
+      s = { count: 0, started: false }
+      lanes.set(lane, s)
+    }
+    return s
+  }
+
+  // Decrement the lane's outstanding count. Returns true iff the count just
+  // reached zero AND the loop was running — i.e. iff the CALLER must now
+  // call `stopTypingLoop`. This is the ref-count release: the loop only
+  // stops once every outstanding tool-use on the lane has resulted.
+  function release(lane: string): boolean {
+    const s = lanes.get(lane)
+    if (s == null) return false
+    s.count = Math.max(0, s.count - 1)
+    if (s.count === 0) {
+      const wasStarted = s.started
+      lanes.delete(lane)
+      return wasStarted
+    }
+    return false
+  }
 
   return {
     onToolUse(toolUseId, chatId, toolName, threadId) {
@@ -60,19 +103,21 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
       const prior = pending.get(toolUseId)
       if (prior) {
         clearTimeout(prior.timer)
-        if (prior.started) deps.stopTypingLoop(prior.chatId, prior.threadId)
+        if (release(prior.lane)) deps.stopTypingLoop(prior.chatId, prior.threadId)
         pending.delete(toolUseId)
       }
-      // First tool on this lane: fire immediately rather than waiting for
-      // the debounce — this closes the silent dead window before the first
-      // progress card appears.
-      if (!activeLanes.has(lane)) {
+      const state = laneFor(lane)
+      state.count += 1
+      // First outstanding tool-use on this lane: fire immediately rather
+      // than waiting for the debounce — this closes the silent dead window
+      // at turn start.
+      if (state.count === 1) {
         deps.startTypingLoop(chatId, tid)
-        activeLanes.add(lane)
+        state.started = true
         const entry: Entry = {
           chatId,
           threadId: tid,
-          started: true,
+          lane,
           timer: setTimeout(() => {}, 0), // no-op sentinel
         }
         pending.set(toolUseId, entry)
@@ -81,10 +126,10 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
       const entry: Entry = {
         chatId,
         threadId: tid,
-        started: false,
+        lane,
         timer: setTimeout(() => {
           deps.startTypingLoop(chatId, tid)
-          entry.started = true
+          state.started = true
         }, debounceMs),
       }
       pending.set(toolUseId, entry)
@@ -95,20 +140,22 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
       const entry = pending.get(toolUseId)
       if (!entry) return
       clearTimeout(entry.timer)
-      if (entry.started) {
-        deps.stopTypingLoop(entry.chatId, entry.threadId)
-        activeLanes.delete(chatKey(entry.chatId, entry.threadId) as string)
-      }
+      if (release(entry.lane)) deps.stopTypingLoop(entry.chatId, entry.threadId)
       pending.delete(toolUseId)
     },
 
     drainAll() {
+      const stoppedLanes = new Set<string>()
       for (const entry of pending.values()) {
         clearTimeout(entry.timer)
-        if (entry.started) deps.stopTypingLoop(entry.chatId, entry.threadId)
+        const state = lanes.get(entry.lane)
+        if (state?.started && !stoppedLanes.has(entry.lane)) {
+          deps.stopTypingLoop(entry.chatId, entry.threadId)
+          stoppedLanes.add(entry.lane)
+        }
       }
       pending.clear()
-      activeLanes.clear()
+      lanes.clear()
     },
   }
 }

package/telegram-plugin/uat/scenarios/jtbd-deliberate-restart-resumes-dm.test.ts

@@ -0,0 +1,118 @@
+/**
+ * JTBD scenario named by `reference/jobs/survive-reboots-and-real-life.md`
+ * § Prove it — "Deliberate restart resumes, bounded (DM)".
+ *
+ * Contract under test (#2988): a DELIBERATE restart (operator
+ * `switchroom agent restart`, i.e. a clean SIGTERM shutdown with a
+ * clean-shutdown marker) that lands MID-TURN resumes the interrupted turn
+ * like a crash-class interruption. The quota-saving suppression applies only
+ * when nothing was in flight — it never swallows mid-turn work. And the
+ * resume is bounded: AT MOST ONCE per interruption (the loop-guard caps the
+ * resume chain), so we also assert no second resume-framed turn fires after
+ * the first completes.
+ *
+ * Sibling: `jtbd-interrupted-turn-resumes-dm.test.ts` (same interruption
+ * mechanics; this scenario adds the deliberate-restart class + the
+ * at-most-once bound). Decision-level twin: `decideBootResumeKind` cases in
+ * `tests/resume-inbound-builder.test.ts` (BOUNDED CHAIN) and
+ * `shouldSuppressBootResume` in `tests/gateway-clean-shutdown-marker.test.ts`.
+ *
+ * Self-skips green without NOPASSWD sudo.
+ */
+
+import { describe, it, expect } from "vitest";
+import { execSync, spawn } from "node:child_process";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+const MID_TURN_MS = 10_000;        // let the turn get in-flight before the bounce
+const RESUME_BUDGET_MS = 180_000;  // boot + resume + reply
+const QUIET_WINDOW_MS = 90_000;    // after the resume completes, no second resume may fire
+// Messages landing within this window of the FIRST resume-framed reply are
+// treated as the same resumed turn (e.g. a progress line plus the final
+// answer of one turn) — only a resume-framed message AFTER it counts as a
+// second resume for the at-most-once bound.
+const SAME_TURN_GRACE_MS = 20_000;
+
+const RESUME_FRAMING = /resum|picking .*back|interrupted|cut off|just restarted/i;
+
+function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function kickRestartDetached(name: string): void {
+  // A deliberate operator restart: clean SIGTERM path, clean-shutdown marker
+  // written — the exact class #2988 makes resume in-flight work through.
+  const child = spawn(
+    "sudo",
+    ["-n", "env", `PATH=${process.env.PATH}`, `HOME=${process.env.HOME}`,
+      "switchroom", "agent", "restart", name, "--force"],
+    { detached: true, stdio: "ignore" },
+  );
+  child.unref();
+}
+
+const sudoOk = canShellSudo();
+
+(sudoOk ? describe : describe.skip)(
+  "uat: deliberate restart mid-turn resumes exactly once (DM, #2988)",
+  () => {
+    it(
+      "an operator restart mid-turn resumes the work once, and never a second time",
+      async () => {
+        const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+        try {
+          // A task long enough to still be in flight at MID_TURN_MS.
+          await sc.sendDM(
+            `Please write a thorough, detailed ~300-word explanation of how a ` +
+            `player piano's pneumatic action reads a music roll, step by step. ` +
+            `Take your time and be complete.`,
+          );
+
+          await new Promise((r) => setTimeout(r, MID_TURN_MS));
+          kickRestartDetached(AGENT);
+
+          // 1. In-flight work resumes: quota-saving suppression must NOT
+          //    swallow a turn that was mid-flight at the bounce. Edits are
+          //    excluded — a progress-card edit must not satisfy this; only
+          //    a genuinely NEW message from the resumed turn counts.
+          const reply = await sc.expectMessage(
+            (m) => !m.edited && RESUME_FRAMING.test(m.text),
+            { from: "bot", timeout: RESUME_BUDGET_MS },
+          );
+          expect(reply.text).toMatch(RESUME_FRAMING);
+          expect(reply.text.length).toBeGreaterThan(40);
+
+          // 2. Bounded chain: with the interruption resolved, no SECOND
+          //    resume-framed turn may fire (at-most-once per interruption).
+          //    Edits are excluded, and messages within SAME_TURN_GRACE_MS of
+          //    the first reply are deduped as part of the SAME resumed turn
+          //    (two resume-ish lines in one turn are not a second resume).
+          const firstReplyAt = reply.date.getTime();
+          let second: unknown = null;
+          try {
+            second = await sc.expectMessage(
+              (m) =>
+                !m.edited &&
+                m.messageId !== reply.messageId &&
+                m.date.getTime() > firstReplyAt + SAME_TURN_GRACE_MS &&
+                RESUME_FRAMING.test(m.text),
+              { from: "bot", timeout: QUIET_WINDOW_MS },
+            );
+          } catch {
+            // timeout is the PASS: no repeat resume.
+          }
+          expect(second).toBeNull();
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      RESUME_BUDGET_MS + QUIET_WINDOW_MS + 120_000,
+    );
+  },
+);

package/telegram-plugin/uat/scenarios/jtbd-midflight-busy-ack-dm.test.ts

@@ -0,0 +1,201 @@
+/**
+ * JTBD scenario — mid-flight busy ack (#2995).
+ *
+ * Serves: `reference/jobs/steer-or-queue-mid-flight.md` — the third
+ * mid-flight class (a quick question that neither steers nor queues
+ * work of its own) and its latency promise: a mid-flight message
+ * arriving while the agent sits inside ONE long blocking tool call
+ * gets a visible, silent ack naming the blocking activity within
+ * seconds — never minutes of dead air behind a `--watch`-style call.
+ *
+ * ## What the scenario drives
+ *
+ * 1. Prompt the agent into a deliberately slow BLOCKING foreground
+ *    Bash (`sleep`) — explicitly instructed NOT to background it.
+ * 2. Wait past the busy-ack step-age threshold (12s), then send a
+ *    trivial mid-turn status question. It buffers (unmarked mid-turn
+ *    follow-up = queue).
+ * 3. Assert a bot message matching the deterministic busy-ack shape
+ *    ("⏳ Queued — currently inside `…`") lands within ACK_SLA_MS of
+ *    the ping, and is SILENT (disable_notification).
+ * 4. Assert the real answer to the question arrives later (after the
+ *    blocking step returns and the buffer flushes).
+ * 5. Assert the busy-ack card was cleaned up (deleted) once the
+ *    answer landed — never a dangling "Queued" line.
+ *
+ * Negative case: a ping during a SHORT blocking step (well under the 12s
+ * threshold, and finished before the deferred re-check could ever see a
+ * 12s-old step) gets NO busy-ack card at any point — an ack that fires
+ * when the agent was seconds from answering is the job spec's explicit
+ * Bad bullet. (A young-step ping during a LONG step DOES get a deferred
+ * card once the step ages past the threshold — that is the re-check
+ * behaviour, covered by the positive case's latency budget.)
+ *
+ * ## Conventions
+ *
+ * - mtcute harness (`spinUp`), skip discipline like siblings: env
+ *   handled by load-env; the suite hard-fails without creds by design
+ *   (CI path-gates it to the uat-host runner).
+ * - `!m.edited` filters on every observation (PR #2991 lesson — the
+ *   live draft/feed edits stream constantly; edits must never satisfy
+ *   a fresh-message expectation).
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+
+// The gateway constant is 12s (BUSY_ACK_STEP_AGE_THRESHOLD_MS). The
+// warmup is anchored to the SEND, not to observed tool start — the agent
+// needs a few seconds to open the turn and enter the Bash step — so it
+// carries a large margin: even if the tool starts ~15s after the send,
+// the step is comfortably past the threshold when the ping lands.
+const STEP_WARMUP_MS = 35_000;
+
+// Latency promise: user-visible ack within seconds of the ping. The card
+// is posted synchronously by the gateway (no model). When the ping lands
+// past the threshold the card is immediate; if the step turns out to be
+// just under, the deferred re-check posts it within (threshold − age).
+// 10s + jitter headroom covers both.
+const ACK_SLA_MS = 10_000;
+
+// The blocking sleep. Long enough that warmup + ping + ack all land while
+// the step is still open (even with a late tool start); short enough to
+// keep wall-clock sane.
+const SLEEP_SECS = 120;
+
+const BUSY_ACK_RE = /⏳ Queued — currently inside `.+`.*I'll answer when this step finishes/s;
+
+const SLOW_PROMPT =
+  `For a latency test, run this exact command in the FOREGROUND with your ` +
+  `Bash tool (do NOT use run_in_background, do NOT split it up): ` +
+  `\`sleep ${SLEEP_SECS} && echo done\`. When it completes, reply with ` +
+  `exactly: SLEEP_DONE. Do not send any message before it completes.`;
+
+const PING = "Quick question while you work: are you still there? One word is fine.";
+
+describe("uat: mid-flight busy ack during a long blocking tool call (#2995)", () => {
+  it(
+    "a mid-turn ping behind a long blocking Bash gets a silent Queued ack naming the activity, then the real answer, then cleanup",
+    async () => {
+      const sc = await spinUp({ agent: AGENT });
+      try {
+        await sc.sendDM(SLOW_PROMPT);
+
+        // Let the blocking step age past the busy-ack threshold.
+        await new Promise((r) => setTimeout(r, STEP_WARMUP_MS));
+
+        const pingAt = Date.now();
+        await sc.sendDM(PING);
+
+        // The deterministic busy-ack must land within the SLA, silent,
+        // naming the blocking activity. `!m.edited` — feed/draft edits
+        // must never satisfy this.
+        const ack = await sc.expectMessage(
+          (m: ObservedMessage) => m.fromBot && !m.edited && BUSY_ACK_RE.test(m.text),
+          { from: "bot", timeout: ACK_SLA_MS + 5_000 },
+        );
+        const ackLatency = Date.now() - pingAt;
+        expect(
+          ackLatency,
+          `busy-ack landed ${ackLatency}ms after the ping — the <10s ` +
+            `latency promise for a mid-flight quick question is broken.`,
+        ).toBeLessThan(ACK_SLA_MS + 5_000);
+        expect(
+          ack.silent,
+          `busy-ack pinged the user's device (silent=false) — the card ` +
+            `must carry disable_notification:true.`,
+        ).toBe(true);
+        // Names the blocking activity (the Bash sleep), not a generic line.
+        expect(ack.text).toMatch(/`.*(Bash|sleep).*`/i);
+
+        // The real answer to the ping arrives AFTER the blocking step
+        // returns and the buffer flushes. Any fresh non-card bot message
+        // that isn't the busy-ack or the SLEEP_DONE completion counts —
+        // the SLEEP_DONE exclusion is explicit (it answers the FIRST
+        // prompt, not the ping).
+        const answer = await sc.expectMessage(
+          (m: ObservedMessage) =>
+            m.fromBot &&
+            !m.edited &&
+            m.messageId !== ack.messageId &&
+            !BUSY_ACK_RE.test(m.text) &&
+            !/SLEEP_DONE/i.test(m.text) &&
+            m.text.trim().length > 0,
+          { from: "bot", timeout: (SLEEP_SECS + 90) * 1000 },
+        );
+        expect(answer.text.trim().length).toBeGreaterThan(0);
+
+        // Cleanup: once answers land and the turns wrap, the busy-ack
+        // card is deleted (delete-on-answer lifecycle). Poll briefly —
+        // the reap is fire-and-forget after the answer/turn-end.
+        const cleanupDeadline = Date.now() + 60_000;
+        let cardGone = false;
+        while (Date.now() < cleanupDeadline) {
+          const still = await sc.driver.getMessage(sc.botUserId, ack.messageId);
+          if (still == null) {
+            cardGone = true;
+            break;
+          }
+          await new Promise((r) => setTimeout(r, 3_000));
+        }
+        expect(
+          cardGone,
+          `busy-ack card (msg ${ack.messageId}) still present 60s after ` +
+            `the answer — a stale "Queued" line is dangling in the chat.`,
+        ).toBe(true);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    // warmup + sleep + flush + answer + cleanup poll + settle headroom
+    (STEP_WARMUP_MS + SLEEP_SECS * 1000 + 200_000),
+  );
+
+  it(
+    "negative: a ping during a SHORT step (finishes under the threshold) never gets a busy-ack card",
+    async () => {
+      const sc = await spinUp({ agent: AGENT });
+      try {
+        // An 8s sleep can NEVER age past the 12s threshold — neither the
+        // direct evaluation nor the deferred re-check may produce a card
+        // (the re-check re-reads live state and finds the step gone).
+        await sc.sendDM(
+          `For a latency test, run this exact command in the FOREGROUND ` +
+            `with your Bash tool (do NOT use run_in_background): ` +
+            `\`sleep 8 && echo done\`. When it completes, reply with ` +
+            `exactly: SHORT_SLEEP_DONE. Do not send any message before it completes.`,
+        );
+
+        // Give the agent a beat to enter the Bash step, then ping while
+        // the short step is (at most) a few seconds old.
+        await new Promise((r) => setTimeout(r, 4_000));
+        await sc.sendDM("Still with me?");
+
+        // Watch through the step end + the widest possible re-check window
+        // + the answer. No message matching the busy-ack shape may appear.
+        let prematureAck: ObservedMessage | null = null;
+        try {
+          prematureAck = await sc.expectMessage(
+            (m: ObservedMessage) => m.fromBot && !m.edited && BUSY_ACK_RE.test(m.text),
+            { from: "bot", timeout: 45_000 },
+          );
+        } catch {
+          // timeout = the correct outcome (no ack, ever)
+        }
+        expect(
+          prematureAck,
+          `a busy-ack fired for a step that never reached the threshold ` +
+            `(${JSON.stringify(prematureAck?.text.slice(0, 120))}) — the ` +
+            `agent was seconds from answering; the threshold/re-check ` +
+            `gates are not holding.`,
+        ).toBeNull();
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    150_000,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-worker-pin-lifecycle-dm.test.ts

@@ -0,0 +1,208 @@
+/**
+ * JTBD — worker-pin lifecycle + the restart rule (#3001, DM).
+ *
+ * The job spec (`reference/jobs/know-what-my-agent-is-doing.md`) sanctions
+ * exactly one pin: silently pinning the already-rendered status message while
+ * its work is in flight, auto-unpinned when the work completes. #3001's
+ * operator report was the failure mode: worker (`wk:`) pins with no
+ * mid-session reaper and a forfeit-on-failure boot sweep left a long tail of
+ * stale pinned `🛠 Worker` messages. The restart rule this scenario pins:
+ * **agent restart = reset any pinned message whose work didn't finish.**
+ *
+ * Two acceptance criteria, shared setup (a long background dispatch):
+ *
+ *   AC-1 — lifecycle: the `🛠 Worker` feed message is PINNED while the
+ *          background worker runs, and UNPINNED after it completes (the
+ *          normal completion unpin — no restart involved).
+ *   AC-2 — restart rule: with a SECOND dispatch pinned mid-flight, a forced
+ *          gateway restart orphans the pin; the next boot's sweep
+ *          (statusPinBootCleanup, reading status-pins.json) unpins it. The
+ *          restart half self-skips green without NOPASSWD sudo, mirroring
+ *          jtbd-message-during-restart-dm.
+ *
+ * Observation shape: pins/unpins are SERVICE events, not message sends or
+ * edits — the worker card EDITS in place the whole time it is pinned, so a
+ * message-observer predicate would fire on edits and prove nothing. We
+ * assert via `driver.observePins` (raw `updatePinnedMessages`), keyed to the
+ * exact pinned messageId, and explicitly ignore `m.edited` traffic.
+ *
+ * Env note: requires the harness agent's default
+ * `pin_status_while_working` (ON) and the worker activity feed enabled —
+ * same env as bg-sub-agent-dispatch-dm (SETUP.md §6).
+ */
+
+import { describe, it, expect } from "vitest";
+import { execSync, spawn } from "node:child_process";
+import { spinUp } from "../harness.js";
+import type { ObservedPin } from "../driver.js";
+import { WORKER_FEED_RE } from "../assertions.js";
+
+const AGENT = "test-harness";
+
+// Same deterministic Option-1 dispatch prompt shape as
+// bg-sub-agent-dispatch-dm: this scenario verifies the PIN infra, not the
+// model's delegation judgment. ~60s of paced background work — long enough
+// for the feed to paint (8s first-paint floor) and the wk: pin to land.
+function bgDispatchPrompt(steps: number): string {
+  return (
+    `Use the Agent tool with subagent_type "general-purpose" and ` +
+    `run_in_background: true to dispatch a worker with this exact task: ` +
+    `"Do ${steps} steps, ONE AT A TIME, k = 1 through ${steps}. Before each ` +
+    `step write a brief one-sentence narration, 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. Do not stop early; complete all ${steps} steps." After ` +
+    `dispatching, send a brief reply saying you've kicked off the worker.`
+  );
+}
+
+/** Wait for the next pin/unpin event matching `pred`. observePins yields
+ *  service-level pin transitions only — message EDITS never surface here,
+ *  which is exactly why this scenario observes pins, not messages. */
+async function nextPinEvent(
+  iter: AsyncIterator<ObservedPin>,
+  pred: (p: ObservedPin) => boolean,
+  timeoutMs: number,
+  what: string,
+): Promise<ObservedPin> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const race = await Promise.race([
+      iter.next(),
+      new Promise<"timeout">((r) => setTimeout(() => r("timeout"), remaining)),
+    ]);
+    if (race === "timeout") break;
+    if (race.done === true) break;
+    if (pred(race.value)) return race.value;
+  }
+  throw new Error(`nextPinEvent: no ${what} within ${timeoutMs}ms`);
+}
+
+function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Kick a marker-safe restart and return immediately (detached) — same shape
+ *  as jtbd-message-during-restart-dm. */
+function kickRestartDetached(name: string): void {
+  const child = spawn(
+    "sudo",
+    ["-n", "env", `PATH=${process.env.PATH}`, `HOME=${process.env.HOME}`,
+      "switchroom", "agent", "restart", name, "--force"],
+    { detached: true, stdio: "ignore" },
+  );
+  child.unref();
+}
+
+const sudoOk = canShellSudo();
+
+describe("uat: worker-pin lifecycle + restart rule (#3001, DM)", () => {
+  it(
+    "AC-1: the worker feed message is pinned while the bg dispatch runs and unpinned after completion",
+    async () => {
+      const sc = await spinUp({ agent: AGENT });
+      const pinIter = sc.driver
+        .observePins(sc.botUserId)
+        [Symbol.asyncIterator]();
+      try {
+        await sc.sendDM(bgDispatchPrompt(10));
+
+        // Parent ack — the dispatch happened.
+        await sc.expectMessage(/.+/, { from: "bot", timeout: 45_000 });
+
+        // The wk: pin lands once the worker feed paints (~8s first-paint) —
+        // a PIN service event, not a send/edit.
+        const pinned = await nextPinEvent(
+          pinIter,
+          (p) => p.pinned,
+          90_000,
+          "worker pin",
+        );
+        expect(pinned.messageId).toBeGreaterThan(0);
+
+        // Sanity: what got pinned is the 🛠 Worker feed message (fetch by id
+        // — the card keeps EDITING in place; we never assert on edits).
+        const msg = await sc.driver.getMessage(sc.botUserId, pinned.messageId);
+        expect(msg, "pinned message vanished").not.toBeNull();
+        expect(msg!.text).toMatch(WORKER_FEED_RE);
+
+        // Completion unpins it. Budget mirrors bg-sub-agent-dispatch-dm's
+        // done-window: worker (~60s) + watcher stall detection (60s) + slack.
+        const unpinned = await nextPinEvent(
+          pinIter,
+          (p) => !p.pinned && p.messageId === pinned.messageId,
+          240_000,
+          `unpin of worker pin msg=${pinned.messageId}`,
+        );
+        expect(unpinned.pinned).toBe(false);
+      } finally {
+        await pinIter.return?.();
+        await sc.tearDown();
+      }
+    },
+    // 45s ack + 90s pin + 240s unpin + spinUp/teardown slack.
+    420_000,
+  );
+
+  (sudoOk ? it : it.skip)(
+    "AC-2 (restart rule): a worker pin orphaned by a forced gateway restart is unpinned by the next boot's sweep",
+    async () => {
+      const sc = await spinUp({ agent: AGENT });
+      const pinIter = sc.driver
+        .observePins(sc.botUserId)
+        [Symbol.asyncIterator]();
+      try {
+        // Longer dispatch (~2min of steps) so the restart reliably lands
+        // while the worker — and its pin — are still in flight.
+        await sc.sendDM(bgDispatchPrompt(30));
+        await sc.expectMessage(/.+/, { from: "bot", timeout: 45_000 });
+
+        // Latch onto the 🛠 Worker feed pin specifically — the parent turn's
+        // own fg: status pin can land first, and a bare `p.pinned` predicate
+        // would seize it and then wait on the wrong messageId's unpin. Keep
+        // consuming pin events until one resolves to a worker-feed message
+        // (AC-1's sanity fetch, applied inside the wait loop).
+        const pinDeadline = Date.now() + 90_000;
+        let pinned: ObservedPin | null = null;
+        while (pinned == null) {
+          const candidate = await nextPinEvent(
+            pinIter,
+            (p) => p.pinned,
+            Math.max(1, pinDeadline - Date.now()),
+            "worker-feed pin",
+          );
+          const msg = await sc.driver
+            .getMessage(sc.botUserId, candidate.messageId)
+            .catch(() => null);
+          if (msg != null && WORKER_FEED_RE.test(msg.text)) pinned = candidate;
+        }
+
+        // Force the restart MID-dispatch: the wk: claim is persisted in
+        // status-pins.json; the dying session never runs its completion
+        // unpin. The next boot's statusPinBootCleanup must unpin it.
+        kickRestartDetached(AGENT);
+
+        const unpinned = await nextPinEvent(
+          pinIter,
+          (p) => !p.pinned && p.messageId === pinned.messageId,
+          // Restart (docker recreate + gateway boot + startup mutex + boot
+          // sweep) comfortably inside this window.
+          240_000,
+          `boot-sweep unpin of orphaned worker pin msg=${pinned.messageId}`,
+        );
+        expect(unpinned.pinned).toBe(false);
+      } finally {
+        await pinIter.return?.();
+        await sc.tearDown();
+      }
+    },
+    420_000,
+  );
+});