switchroom 0.18.7 → 0.18.9

package/telegram-plugin/tests/worker-pin-reaper.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import {
+  decideWorkerPinReaps,
+  workerAgentIdOfPinKey,
+  WORKER_PIN_TTL_MS_DEFAULT,
+  type WorkerPinCandidate,
+} from "../gateway/worker-pin-reaper.js";
+
+const NOW = 1_750_000_000_000;
+const TTL = WORKER_PIN_TTL_MS_DEFAULT;
+
+function pin(over: Partial<WorkerPinCandidate> = {}): WorkerPinCandidate {
+  return { pinKey: "wk:agent-1", chatId: "123", pinnedAt: NOW - 60_000, ...over };
+}
+
+describe("workerAgentIdOfPinKey", () => {
+  it("extracts the agentId from a wk: key", () => {
+    expect(workerAgentIdOfPinKey("wk:abc123")).toBe("abc123");
+  });
+  it("returns null for non-worker keys (fg:/banner:/tool:) and empty ids", () => {
+    expect(workerAgentIdOfPinKey("fg:123:5")).toBeNull();
+    expect(workerAgentIdOfPinKey("banner:owner")).toBeNull();
+    expect(workerAgentIdOfPinKey("tool:123:9")).toBeNull();
+    expect(workerAgentIdOfPinKey("wk:")).toBeNull();
+  });
+});
+
+describe("decideWorkerPinReaps (#3001 mid-session wk: sweep)", () => {
+  it("reaps a pin whose worker is terminal, however young the pin is", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - 1_000 })],
+      statusOf: () => 'terminal' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(1);
+    expect(reaps[0].reason).toBe("terminal");
+    expect(reaps[0].pinKey).toBe("wk:agent-1");
+  });
+
+  it("reaps a non-terminal pin once it exceeds the TTL", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - TTL })],
+      statusOf: () => 'unknown' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(1);
+    expect(reaps[0].reason).toBe("ttl");
+  });
+
+  it("NEVER touches a pin younger than the TTL when the registry cannot vouch (unknown)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - TTL + 1 })],
+      statusOf: () => 'unknown' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("ignores non-worker keys entirely (fg:/banner:/tool: are not its job)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [
+        pin({ pinKey: "fg:123:5", pinnedAt: NOW - 10 * TTL }),
+        pin({ pinKey: "banner:owner", pinnedAt: NOW - 10 * TTL }),
+        pin({ pinKey: "tool:123:9", pinnedAt: NOW - 10 * TTL }),
+      ],
+      statusOf: () => 'terminal' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("skips a candidate with no chat id (cannot unpin without one)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ chatId: "", pinnedAt: NOW - 10 * TTL })],
+      statusOf: () => 'terminal' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("a registry-confirmed RUNNING worker keeps its pin PAST the TTL (no unpin/re-pin churn on healthy long workers)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - 10 * TTL })],
+      statusOf: () => 'running' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("status is consulted per-agent: terminal reaps young, running exempts old, unknown falls to the TTL gate", () => {
+    const seen: string[] = [];
+    const reaps = decideWorkerPinReaps({
+      pins: [
+        pin({ pinKey: "wk:done", pinnedAt: NOW - 1_000 }),
+        pin({ pinKey: "wk:running-old", pinnedAt: NOW - TTL - 1 }),
+        pin({ pinKey: "wk:unknown-young", pinnedAt: NOW - 1_000 }),
+        pin({ pinKey: "wk:unknown-old", pinnedAt: NOW - TTL - 1 }),
+      ],
+      statusOf: (agentId) => {
+        seen.push(agentId);
+        if (agentId === "done") return "terminal";
+        if (agentId === "running-old") return "running";
+        return "unknown";
+      },
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(seen).toEqual(["done", "running-old", "unknown-young", "unknown-old"]);
+    expect(reaps.map((r) => [r.pinKey, r.reason])).toEqual([
+      ["wk:done", "terminal"],
+      ["wk:unknown-old", "ttl"],
+    ]);
+  });
+
+  it("registry hiccup ('unknown') never unpins a young pin — the caller's contract on statusOf degrade", () => {
+    // The gateway wraps its DB lookup and degrades to 'unknown'. This pins the
+    // pure module's side of the contract: unknown + young pin = untouched.
+    const reaps = decideWorkerPinReaps({
+      pins: [pin()],
+      statusOf: () => 'unknown' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+});

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,
+  );
+});