switchroom 0.18.7 → 0.18.8

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

package/telegram-plugin/uat/scenarios/vault-card-survives-gateway-restart-dm.test.ts

@@ -0,0 +1,140 @@
+/**
+ * UAT scenario named by `reference/jobs/approve-what-my-agent-can-touch.md`
+ * § Prove it — "Card survives a gateway restart (DM)".
+ *
+ * Contract under test (#2989 durability fix): an agent-initiated
+ * `vault_request_access` card issued BEFORE a gateway restart is still
+ * tappable AFTER it. The gateway persists card metadata to the durable
+ * pending-card store, restores it on boot, and a tap on the still-valid card
+ * grants and resumes the parked agent exactly like a pre-restart tap —
+ * never the "Card expired — ask the agent to re-request" tombstone while the
+ * agent is parked and structurally cannot re-request.
+ *
+ * Load-bearing assertions:
+ *   1. The post-restart tap does NOT produce the expired-card tombstone edit.
+ *   2. The approve flow completes (passphrase → Granted card edit).
+ *   3. The parked agent resumes on the grant with no driver nudge.
+ *
+ * **Skipped by default.** To unskip:
+ *
+ *   1. Standard UAT preflight (`uat/SETUP.md` §5-6).
+ *   2. NOPASSWD sudo on the runner host (the scenario restarts test-harness).
+ *   3. `TELEGRAM_UAT_VAULT_PASSPHRASE` set in env.
+ *   4. Pre-create a sacrificial vault key:
+ *
+ *      ```bash
+ *      TMPF=$(mktemp) && printf '%s' 'sentinel-2989-value' > "$TMPF" && \
+ *        switchroom vault set uat/card-survives-restart --file "$TMPF" \
+ *          --format string ; shred -u "$TMPF"
+ *      ```
+ *
+ *   5. Remove `describe.skip` below.
+ *
+ * Why skipped: mutates vault state (mints a grant) and bounces the harness
+ * agent. Cleanup is operator-side (`switchroom vault revoke <grant-id>`).
+ *
+ * Module-level twin (every CI run): the restart round-trip in
+ * `tests/approval-card-restart-outcome.test.ts` and the store contract in
+ * `tests/pending-card-store.test.ts`.
+ */
+
+import { describe, expect, it } from "vitest";
+import { execSync, spawn } from "node:child_process";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+const KEY = "uat/card-survives-restart";
+const CARD_BUDGET_MS = 120_000;
+const BOOT_BUDGET_MS = 180_000;
+const RESUME_BUDGET_MS = 180_000;
+
+function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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();
+}
+
+describe.skip("uat: approval card survives a gateway restart (DM, #2989)", () => {
+  it(
+    "card issued pre-restart is tappable post-restart: grant lands and the agent resumes",
+    async () => {
+      if (!canShellSudo()) {
+        throw new Error("NOPASSWD sudo required — see header to set up.");
+      }
+      const passphrase = process.env.TELEGRAM_UAT_VAULT_PASSPHRASE;
+      if (!passphrase) {
+        throw new Error(
+          "TELEGRAM_UAT_VAULT_PASSPHRASE must be set in env (see uat/SETUP.md).",
+        );
+      }
+      const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+      try {
+        // 1. Park the agent on an approval card.
+        await sc.sendDM(
+          `Please call your vault_request_access MCP tool for the key ` +
+          `\`${KEY}\` (scope read, 30d, reason "UAT #2989 card durability"). ` +
+          `END YOUR TURN cleanly and wait; when the operator approves, resume ` +
+          `by running \`switchroom vault get ${KEY}\` and reporting success.`,
+        );
+        const card = await sc.expectMessage(/wants vault access/, {
+          from: "bot",
+          timeout: CARD_BUDGET_MS,
+        });
+
+        // 2. Bounce the gateway BEFORE anyone taps.
+        kickRestartDetached(AGENT);
+        await new Promise((r) => setTimeout(r, BOOT_BUDGET_MS));
+
+        // 3. Tap Approve on the ORIGINAL, pre-restart card message.
+        const kb = await sc.driver.getKeyboard(sc.botUserId, card.messageId);
+        const approveButton = kb!
+          .flat()
+          .find((b) => b.callbackData !== undefined && /approve/i.test(b.text));
+        expect(approveButton).toBeDefined();
+        await sc.driver.pressButton(
+          sc.botUserId,
+          card.messageId,
+          approveButton!.callbackData!,
+        );
+
+        // 4. The restored card must run the REAL approve flow — the expired
+        //    tombstone ("expired before you tapped") is the pre-#2989 defect.
+        const next = await sc.expectMessage(
+          (m) =>
+            /Reply with your passphrase|Granted|expired before you tapped/i.test(m.text),
+          { from: "bot", timeout: 60_000 },
+        );
+        expect(next.text).not.toMatch(/expired before you tapped/i);
+
+        if (/passphrase/i.test(next.text)) {
+          await sc.sendDM(passphrase);
+        }
+
+        // 5. Grant lands and the parked agent resumes without a nudge.
+        //    Edits excluded — the "✅ Granted" edit of the card itself must
+        //    not satisfy this; only a NEW message from the resumed turn does.
+        const resumed = await sc.expectMessage(
+          (m) => !m.edited && /(granted|access|vault get|succe)/i.test(m.text) && m.text.length > 40,
+          { from: "bot", timeout: RESUME_BUDGET_MS },
+        );
+        expect(resumed.text.length).toBeGreaterThan(40);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    CARD_BUDGET_MS + BOOT_BUDGET_MS + RESUME_BUDGET_MS + 120_000,
+  );
+});

package/telegram-plugin/uat/scenarios/vault-deny-resumes-turn-dm.test.ts

@@ -0,0 +1,84 @@
+/**
+ * UAT scenario named by `reference/jobs/approve-what-my-agent-can-touch.md`
+ * § Prove it — "Denied request resumes the turn (DM)".
+ *
+ * Contract under test: the operator taps Deny on an agent-initiated
+ * `vault_request_access` card; the parked turn RESUMES (the gateway injects
+ * the `vault_grant_denied` synthetic), and the agent states plainly what it
+ * now can't do and continues or degrades — never left waiting on a card it
+ * already got an answer to, and never treating the denial as a reason to
+ * silently strand.
+ *
+ * Load-bearing assertion: after the Deny tap, the DRIVER sees a NEW bot turn
+ * that acknowledges the denial/degraded path WITHOUT the driver sending any
+ * further message. (The unit-level twin pins the synthetic's envelope in
+ * `tests/vault-grant-inbound-builders.test.ts`; this scenario proves the
+ * user-visible outcome over real Telegram.)
+ *
+ * Needs only the standard UAT preflight (`uat/SETUP.md` §5-6) — a Deny mints
+ * nothing and mutates no vault state, so no passphrase or sacrificial key is
+ * required. The requested key deliberately does not exist.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const KEY = "uat/deny-resume-nonexistent-key";
+const CARD_BUDGET_MS = 120_000;
+const RESUME_BUDGET_MS = 120_000;
+
+// The deny synthetic steers the model toward naming the blocked capability
+// and a fallback — this framing is the stable signal of a resumed turn.
+const DENY_RESUME_FRAMING =
+  /den(?:ied|ial)|can(?:'|no)t|won'?t be able|without (?:that|the) (?:key|access|credential)|not (?:been )?grant/i;
+
+describe("uat: denied vault request resumes the parked turn (DM)", () => {
+  it(
+    "operator taps Deny → parked turn resumes and the agent names what it can't do, with no nudge",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        // 1. Park the agent on an approval card.
+        await sc.sendDM(
+          `Please call your vault_request_access MCP tool for the key ` +
+          `\`${KEY}\` (scope read, reason "UAT deny-resumes-turn"). Then END ` +
+          `YOUR TURN cleanly and wait. When you hear the operator's decision, ` +
+          `resume: if denied, tell me plainly that you can't read that key ` +
+          `and what you'd do instead.`,
+        );
+
+        // 2. Wait for the approval card and find the Deny button.
+        const card = await sc.expectMessage(/wants vault access/, {
+          from: "bot",
+          timeout: CARD_BUDGET_MS,
+        });
+        const kb = await sc.driver.getKeyboard(sc.botUserId, card.messageId);
+        const denyButton = kb!
+          .flat()
+          .find((b) => b.callbackData !== undefined && /deny/i.test(b.text));
+        expect(denyButton).toBeDefined();
+
+        // 3. Tap Deny. NO further driver message after this point.
+        await sc.driver.pressButton(
+          sc.botUserId,
+          card.messageId,
+          denyButton!.callbackData!,
+        );
+
+        // 4. The deny synthetic must wake the parked turn: a substantive
+        //    bot reply that acknowledges the denial arrives unprompted.
+        //    Edits are excluded — the gateway's own "🚫 Denied" edit of the
+        //    approval card must not satisfy this; only a genuinely NEW
+        //    message from a resumed turn counts.
+        const reply = await sc.expectMessage(
+          (m) => !m.edited && DENY_RESUME_FRAMING.test(m.text) && m.text.length > 40,
+          { from: "bot", timeout: RESUME_BUDGET_MS },
+        );
+        expect(reply.text).toMatch(DENY_RESUME_FRAMING);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    CARD_BUDGET_MS + RESUME_BUDGET_MS + 60_000,
+  );
+});