switchroom 0.15.45 → 0.16.4

package/telegram-plugin/gateway/auth-command.ts

@@ -34,6 +34,7 @@ import {
   renderAuthSnapshotFormat2,
   buildSnapshotKeyboard,
 } from '../auth-snapshot-format.js'
+import { maskEmail } from '../demo-mask.js'
 
 // ─── Parser ────────────────────────────────────────────────────────────────
 
@@ -237,7 +238,19 @@ export interface AuthBrokerClient {
   probeQuota(
     accounts: readonly string[],
     timeoutMs?: number,
-  ): Promise<{ results: Array<{ label: string; result: import('../quota-check.js').QuotaResult }> }>
+    /** #2495 Change 2/3 — bypass the broker's probe-on-open TTL (quota-watch
+     *  alarm corroboration). Normal card opens omit it (TTL-gated). */
+    forceLive?: boolean,
+  ): Promise<{
+    results: Array<{
+      label: string
+      result: import('../quota-check.js').QuotaResult
+      /** #2495 Change 2 — how this result was sourced ("live" vs "cache"). */
+      served?: 'live' | 'cache'
+      /** Unix ms the served snapshot was captured (set when served==="cache"). */
+      capturedAt?: number
+    }>
+  }>
   /**
    * Fleet notification-dedup claim (quota-watch). First caller of `key`
    * inside `windowMs` gets `granted: true` and sends; everyone else
@@ -280,9 +293,29 @@ export interface AuthCommandContext {
    */
   liveQuotas?: (
     accounts: AccountState[],
-  ) => Promise<import('../quota-check.js').QuotaResult[]>
+  ) => Promise<LiveQuotasResult>
   /** Operator timezone forwarded to the Format 2 renderer. */
   tz?: string
+  /**
+   * Demo mode (the `/auth demo` suffix). Forwarded to the Format 2 renderer
+   * so the fleet snapshot masks account-email labels for a screen recording.
+   * Off by default; only the default dashboard view (`show`/`list`) honors
+   * it — destructive verbs are unaffected. Scope is the email-label PII tier.
+   */
+  demo?: boolean
+}
+
+/**
+ * #2495 Change 2 — the enriched probe result. `quotas` stays parallel to
+ * `state.accounts` (the contract `buildSnapshotsFromState` relies on);
+ * `staleCachedAtMs` is set when ANY account was served from the durable cache
+ * (probe-on-open TTL hit OR a failed live probe falling back to cache) — it
+ * carries the OLDEST such snapshot's `capturedAt` so the footer stamps
+ * "⚠ cached Nm ago" instead of a false "Live · refreshed 0s ago".
+ */
+export interface LiveQuotasResult {
+  quotas: import('../quota-check.js').QuotaResult[]
+  staleCachedAtMs?: number
 }
 
 export interface AuthCommandReply {
@@ -345,10 +378,18 @@ export async function handleAuthCommand(
       const state = await ctx.client.listState()
       let liveQuotas: import('../quota-check.js').QuotaResult[] | undefined
       let liveProbedAtMs: number | undefined
+      let staleCachedAtMs: number | undefined
       if (ctx.liveQuotas && state.accounts.length > 0) {
         try {
-          liveQuotas = await ctx.liveQuotas(state.accounts)
-          liveProbedAtMs = Date.now()
+          const enriched = await ctx.liveQuotas(state.accounts)
+          liveQuotas = enriched.quotas
+          // #2495 Change 2 — only claim a live "refreshed Ns ago" stamp when
+          // NOTHING was served from cache; otherwise show "⚠ cached Nm ago".
+          if (enriched.staleCachedAtMs != null) {
+            staleCachedAtMs = enriched.staleCachedAtMs
+          } else {
+            liveProbedAtMs = Date.now()
+          }
         } catch {
           // Live probe failed — fall back to legacy table silently.
           liveQuotas = undefined
@@ -361,13 +402,15 @@ export async function handleAuthCommand(
       let keyboard: AuthCommandReply['keyboard']
       if (liveQuotas && liveQuotas.length === state.accounts.length) {
         const snapshots = buildSnapshotsFromState(state, liveQuotas)
-        keyboard = buildSnapshotKeyboard(snapshots)
+        keyboard = buildSnapshotKeyboard(snapshots, { now: new Date() })
       }
       return {
         text: renderShowText(state, Date.now(), {
           liveQuotas,
           tz: ctx.tz,
           liveProbedAtMs,
+          staleCachedAtMs,
+          demo: ctx.demo,
         }),
         html: true,
         keyboard,
@@ -709,6 +752,13 @@ export interface RenderShowOpts {
   /** Wall-clock ms when the live probes returned, used for "refreshed
    *  Ns ago" footer. Omit to suppress that footer line. */
   liveProbedAtMs?: number
+  /** #2495 Change 2 — set when the render was served from the durable cache
+   *  (probe-on-open TTL hit or failed probe). Renders "⚠ cached Nm ago" in
+   *  the footer (takes precedence over liveProbedAtMs). */
+  staleCachedAtMs?: number
+  /** Demo mode (the `/auth demo` suffix). Masks account-email labels in both
+   *  the Format 2 snapshot and the legacy accounts table. Off by default. */
+  demo?: boolean
 }
 
 /**
@@ -745,6 +795,8 @@ export function renderShowText(
         tz: opts.tz,
         now: new Date(now),
         liveProbedAtMs: opts.liveProbedAtMs,
+        staleCachedAtMs: opts.staleCachedAtMs,
+        demo: opts.demo,
       }),
     )
   } else {
@@ -753,7 +805,7 @@ export function renderShowText(
       lines.push('')
       lines.push('<b>Accounts</b>')
       lines.push('<pre>')
-      lines.push(formatAccountsTable(state, now))
+      lines.push(formatAccountsTable(state, now, opts.demo ?? false))
       lines.push('</pre>')
     }
   }
@@ -762,7 +814,7 @@ export function renderShowText(
   if (state.agents.length > 0) {
     lines.push('<b>Agents</b>')
     lines.push('<pre>')
-    lines.push(formatAgentsTable(state))
+    lines.push(formatAgentsTable(state, opts.demo ?? false))
     lines.push('</pre>')
   }
 
@@ -770,7 +822,7 @@ export function renderShowText(
   if (state.consumers.length > 0) {
     lines.push('<b>Consumers</b>')
     lines.push('<pre>')
-    lines.push(formatConsumersTable(state, now))
+    lines.push(formatConsumersTable(state, now, opts.demo ?? false))
     lines.push('</pre>')
   }
 
@@ -784,7 +836,7 @@ export function renderShowText(
   return lines.join('\n')
 }
 
-function formatAccountsTable(state: ListStateData, now: number): string {
+function formatAccountsTable(state: ListStateData, now: number, demo = false): string {
   const rows: string[][] = [['ACCOUNT', 'STATUS', 'EXPIRES', 'QUOTA 5h·7d', 'QUOTA-RESET']]
   for (const acc of state.accounts) {
     const isActive = acc.label === state.active
@@ -800,7 +852,7 @@ function formatAccountsTable(state: ListStateData, now: number): string {
         ? formatRelativeMs(acc.exhausted_until - now)
         : '—'
     rows.push([
-      `${marker} ${escapeHtml(acc.label)}`,
+      `${marker} ${escapeHtml(demo ? maskEmail(acc.label) : acc.label)}`,
       status,
       expires,
       formatQuotaUtilCell(acc, now),
@@ -830,7 +882,9 @@ export function formatQuotaUtilCell(
   return `${Math.round(lq.fiveHourUtilizationPct)}%·${Math.round(lq.sevenDayUtilizationPct)}% (${ageStr} ago)`
 }
 
-function formatAgentsTable(state: ListStateData): string {
+function formatAgentsTable(state: ListStateData, demo = false): string {
+  // The ACTIVE column is an account-email label (in-scope PII); the AGENT
+  // name is topology (out of scope) and is never masked.
   const rows: string[][] = [['AGENT', 'ACTIVE', 'SOURCE']]
   for (const a of state.agents) {
     const source = a.override
@@ -838,7 +892,7 @@ function formatAgentsTable(state: ListStateData): string {
       : a.account === state.active
         ? 'fleet-active'
         : 'pinned'
-    rows.push([escapeHtml(a.name), escapeHtml(a.account), source])
+    rows.push([escapeHtml(a.name), escapeHtml(demo ? maskEmail(a.account) : a.account), source])
   }
   return alignTable(rows)
 }
@@ -885,14 +939,16 @@ export function renderAgentDetail(
   return lines.join('\n')
 }
 
-function formatConsumersTable(state: ListStateData, now: number): string {
+function formatConsumersTable(state: ListStateData, now: number, demo = false): string {
+  // ACTIVE is an account-email label (in-scope PII); CONSUMER name is
+  // topology (out of scope) and is never masked.
   const rows: string[][] = [['CONSUMER', 'ACTIVE', 'STATUS']]
   for (const c of state.consumers) {
     const status =
       c.last_seen_at == null
         ? 'socket bound'
         : `socket bound (last seen ${formatRelativeMs(now - c.last_seen_at)} ago)`
-    rows.push([escapeHtml(c.name), escapeHtml(c.account), status])
+    rows.push([escapeHtml(c.name), escapeHtml(demo ? maskEmail(c.account) : c.account), status])
   }
   return alignTable(rows)
 }

package/telegram-plugin/gateway/clean-shutdown-marker.ts

@@ -181,3 +181,47 @@ export function resolveShutdownMarker(
   }
   return { ts: now, signal, reason: EXTERNAL_RESTART_FALLBACK_REASON };
 }
+
+/**
+ * Pure decision: should the boot-resume path SUPPRESS the active
+ * resume_interrupted inbound because the prior shutdown was clean?
+ *
+ * A clean marker present and fresh (<= maxAgeMs, default 60s) means the
+ * prior shutdown was operator/roll/CLI-initiated — NOT a crash. In that
+ * case auto-resuming interrupted work is wasteful: the agent was asked to
+ * stop, it stopped cleanly, and the "interrupted" turn was implicitly
+ * abandoned by that decision. Burning a full model turn to replay it on
+ * every operator restart wastes subscription quota for no user benefit.
+ *
+ * Returns true ONLY when:
+ *   - a clean marker is present, AND
+ *   - the marker is younger than maxAgeMs (default 60s), AND
+ *   - the SWITCHROOM_BOOT_RESUME_ALWAYS escape hatch is not set.
+ *
+ * Returns false when:
+ *   - no marker (crash / OOM / unexpected kill — resume normally), OR
+ *   - marker is stale (>= maxAgeMs — something stalled; treat as crash), OR
+ *   - forceAlways is true (the escape hatch is active).
+ *
+ * The forceAlways parameter maps to the env var
+ * SWITCHROOM_BOOT_RESUME_ALWAYS=1, which restores the pre-gate behaviour
+ * unconditionally. Pass it in as a parsed boolean so this function stays
+ * pure and testable without touching process.env.
+ *
+ * Keeping this pure makes the decision unit-testable in bun test without
+ * spinning up the gateway.
+ */
+export function shouldSuppressBootResume(
+  marker: CleanShutdownMarker | null,
+  now: number,
+  { maxAgeMs = DEFAULT_MAX_AGE_MS, forceAlways = false }: {
+    maxAgeMs?: number;
+    forceAlways?: boolean;
+  } = {},
+): boolean {
+  if (forceAlways) return false;
+  if (marker === null) return false;
+  const age = now - marker.ts;
+  if (age < 0) return false; // clock skew defence — treat as stale
+  return age < maxAgeMs;
+}

package/telegram-plugin/gateway/config-approval-handler.test.ts

@@ -44,13 +44,28 @@ function fakeDeps(overrides: Partial<Parameters<typeof handleRequestConfigApprov
     chatId: number | string;
     messageId: number;
     text: string;
+    stripKeyboard?: boolean;
   }> = [];
   const deps = {
     agentName: "klanker",
     loadTargetChat: () => ({ chatId: 42 }),
     postCard: vi.fn(async () => ({ messageId: 1001 })),
-    buildKeyboard: () => ({ inline_keyboard: [] }),
-    editCard: async (a: { chatId: number | string; messageId: number; text: string }) => {
+    // Deterministic epoch so callback_data is assertable in tests.
+    mintEpoch: () => "cafe1234",
+    buildKeyboard: (requestId: string, epoch: string) => ({
+      inline_keyboard: [
+        [
+          { text: "✅ Approve", callback_data: `cfg:${requestId}:${epoch}:approve` },
+          { text: "🚫 Deny", callback_data: `cfg:${requestId}:${epoch}:deny` },
+        ],
+      ],
+    }),
+    editCard: async (a: {
+      chatId: number | string;
+      messageId: number;
+      text: string;
+      stripKeyboard?: boolean;
+    }) => {
       editCalls.push(a);
     },
     log: () => {},
@@ -227,9 +242,11 @@ describe("resolvePendingConfigApproval — double-tap and verdict propagation",
     const verdicts = sent.filter((s) => s.type === "config_approval_resolved");
     expect(verdicts.length).toBe(1);
     expect(verdicts[0]!.verdict).toBe("approve");
-    // Card edited once to the interim 'Applying' state.
+    // Card edited once to the interim 'Applying' state, with the keyboard
+    // stripped so the buttons stop being tappable.
     expect(editCalls.length).toBe(1);
     expect(editCalls[0]!.text).toMatch(/Applying/);
+    expect(editCalls[0]!.stripKeyboard).toBe(true);
   });
 
   it("returns false when no entry exists (unknown requestId)", async () => {
@@ -261,6 +278,8 @@ describe("timeout path", () => {
       expect(verdicts.length).toBe(1);
       expect(verdicts[0]!.verdict).toBe("timeout");
       expect(editCalls[0]!.text).toMatch(/Expired/);
+      // Expired card must also strip the keyboard (no stale tappable buttons).
+      expect(editCalls[0]!.stripKeyboard).toBe(true);
     } finally {
       vi.useRealTimers();
     }
@@ -437,7 +456,20 @@ describe("oversize diff → attachment fallback (#1762)", () => {
 });
 
 describe("parseConfigApprovalCallback", () => {
-  it("parses well-formed callbacks", () => {
+  it("parses the new epoch-bearing form cfg:<requestId>:<epoch>:<choice>", () => {
+    expect(parseConfigApprovalCallback("cfg:abc:cafe1234:approve")).toEqual({
+      requestId: "abc",
+      epoch: "cafe1234",
+      choice: "approve",
+    });
+    expect(parseConfigApprovalCallback("cfg:deadbeef:00ff:deny")).toEqual({
+      requestId: "deadbeef",
+      epoch: "00ff",
+      choice: "deny",
+    });
+  });
+
+  it("still parses the legacy 3-segment form (no epoch, back-compat)", () => {
     expect(parseConfigApprovalCallback("cfg:abc:approve")).toEqual({
       requestId: "abc",
       choice: "approve",
@@ -455,3 +487,58 @@ describe("parseConfigApprovalCallback", () => {
     expect(parseConfigApprovalCallback("cfg::approve")).toBeNull();
   });
 });
+
+describe("stale-tap rejection via per-card epoch", () => {
+  it("bakes the minted epoch into the posted card's callback_data", async () => {
+    const { client, deps } = fakeDeps();
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    const postCard = deps.postCard as ReturnType<typeof vi.fn>;
+    const kb = postCard.mock.calls[0]![0].replyMarkup as {
+      inline_keyboard: Array<Array<{ callback_data: string }>>;
+    };
+    expect(kb.inline_keyboard[0]![0]!.callback_data).toBe(
+      "cfg:req-1:cafe1234:approve",
+    );
+    expect(kb.inline_keyboard[0]![1]!.callback_data).toBe(
+      "cfg:req-1:cafe1234:deny",
+    );
+  });
+
+  it("resolves when the tap epoch matches the live card", async () => {
+    const { client, deps } = fakeDeps();
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    const ok = await resolvePendingConfigApproval(
+      "req-1",
+      "approve",
+      deps,
+      "cafe1234",
+    );
+    expect(ok).toBe(true);
+  });
+
+  it("rejects a stale tap whose epoch does NOT match the live card", async () => {
+    const { client, sent, deps, editCalls } = fakeDeps();
+    await handleRequestConfigApproval(client, baseMsg, deps);
+    // A tap carrying a DIFFERENT (stale) epoch must be a no-op — no verdict
+    // crosses the wire, no card edit happens, and the request stays live.
+    const stale = await resolvePendingConfigApproval(
+      "req-1",
+      "approve",
+      deps,
+      "deadbeef",
+    );
+    expect(stale).toBe(false);
+    expect(sent.filter((s) => s.type === "config_approval_resolved")).toEqual(
+      [],
+    );
+    expect(editCalls).toEqual([]);
+    // The correct (live) epoch still resolves it.
+    const live = await resolvePendingConfigApproval(
+      "req-1",
+      "approve",
+      deps,
+      "cafe1234",
+    );
+    expect(live).toBe(true);
+  });
+});

package/telegram-plugin/gateway/config-approval-handler.ts

@@ -2,6 +2,7 @@
 // card, resolves the verdict back to hostd over IPC, and flips the card to
 // a terminal state on finalize.
 
+import { randomBytes } from "node:crypto";
 import type { IpcClient } from "./ipc-server.js";
 import type {
   RequestConfigApprovalMessage,
@@ -12,6 +13,15 @@ import { truncateRawToFit } from "./oversize-card-body.js";
 /** Pending approval state — in-memory only (no SQLite per RFC §3.4). */
 interface PendingConfigApproval {
   requestId: string;
+  /**
+   * Per-card nonce embedded in the callback_data (`cfg:<requestId>:<epoch>:
+   * <choice>`). hostd's `approvalId` is only randomBytes(4)=32 bits and the
+   * callback_data carried no epoch, so a stale tap on a never-stripped old
+   * card could in principle resolve a same-id LIVE request. A tap whose epoch
+   * doesn't match the live pending entry is rejected as stale (see
+   * `resolvePendingConfigApproval`).
+   */
+  epoch: string;
   client: Pick<IpcClient, "send">;
   chatId: number | string;
   threadId?: number;
@@ -25,6 +35,12 @@ interface PendingConfigApproval {
 
 const pending = new Map<string, PendingConfigApproval>();
 
+/** Default per-card nonce: 8 hex chars (32 bits) — enough to make a stale
+ *  tap's epoch effectively never collide with a live card's. */
+function defaultEpoch(): string {
+  return randomBytes(4).toString("hex");
+}
+
 // Injected deps — gateway.ts wires these from the existing surface.
 
 export interface ConfigApprovalHandlerDeps {
@@ -43,13 +59,26 @@ export interface ConfigApprovalHandlerDeps {
     /** grammy InlineKeyboard, passed through verbatim. */
     replyMarkup: unknown;
   }) => Promise<{ messageId: number } | null>;
-  /** Build the inline keyboard with [✅ Approve] [🚫 Deny] buttons. */
-  buildKeyboard: (requestId: string) => unknown;
-  /** Edit a posted card to a new body. Best-effort — failures logged. */
+  /**
+   * Build the inline keyboard with [✅ Approve] [🚫 Deny] buttons. The
+   * `epoch` is a per-card nonce baked into the callback_data so a stale tap
+   * on an old card can never match a live request (see PendingConfigApproval).
+   */
+  buildKeyboard: (requestId: string, epoch: string) => unknown;
+  /** Mint a per-card nonce. Default: a short random hex (test seam). */
+  mintEpoch?: () => string;
+  /**
+   * Edit a posted card to a new body. Best-effort — failures logged.
+   * When `stripKeyboard` is set, the inline keyboard is removed so the
+   * [✅ Approve] [🚫 Deny] buttons stop being tappable on a card that has
+   * reached a terminal/interim state — a stale tap must never resolve a
+   * request (defense-in-depth alongside the per-card epoch in callback_data).
+   */
   editCard: (args: {
     chatId: number | string;
     messageId: number;
     text: string;
+    stripKeyboard?: boolean;
   }) => Promise<void>;
   /**
    * Send the full diff as a `.patch` document attachment when the
@@ -278,7 +307,11 @@ export async function handleRequestConfigApproval(
   // builder's structured `truncated` flag instead of substring-
   // matching the sentinel string (#1767 nit).
   const oversize = prelim !== msg.unifiedDiff || built.truncated;
-  const replyMarkup = deps.buildKeyboard(msg.requestId);
+  // Per-card nonce — baked into callback_data so a stale tap on a previously
+  // posted card (e.g. one already finalized/expired) can never match a live
+  // pending request even if hostd minted the same 32-bit requestId.
+  const epoch = (deps.mintEpoch ?? defaultEpoch)();
+  const replyMarkup = deps.buildKeyboard(msg.requestId, epoch);
 
   const posted = await deps.postCard({
     chatId: target.chatId,
@@ -296,6 +329,7 @@ export async function handleRequestConfigApproval(
 
   const entry: PendingConfigApproval = {
     requestId: msg.requestId,
+    epoch,
     client,
     chatId: target.chatId,
     ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
@@ -328,14 +362,30 @@ export async function handleRequestConfigApproval(
  *
  * Returns true if THIS call resolved the request (first call wins),
  * false if it was already resolved.
+ *
+ * `expectedEpoch` guards an OPERATOR tap: the callback_data carries the
+ * per-card nonce, which must match the live pending entry's `epoch`. A
+ * mismatch means the tap came from a STALE card (already finalized/expired,
+ * keyboard should have been stripped) — reject it as a no-op so it can never
+ * resolve a different live request that happens to share the 32-bit
+ * requestId. Internal callers (the per-request timeout timer, finalize) pass
+ * `undefined` to skip the check — they already hold the authoritative entry.
  */
 export async function resolvePendingConfigApproval(
   requestId: string,
   verdict: "approve" | "deny" | "timeout",
   deps: Pick<ConfigApprovalHandlerDeps, "editCard" | "log">,
+  expectedEpoch?: string,
 ): Promise<boolean> {
   const entry = pending.get(requestId);
   if (!entry || entry.resolved) return false;
+  if (expectedEpoch !== undefined && entry.epoch !== expectedEpoch) {
+    deps.log?.(
+      `config approval stale-tap rejected (requestId=${requestId}): ` +
+        `epoch mismatch (tap=${expectedEpoch} live=${entry.epoch})`,
+    );
+    return false;
+  }
   entry.resolved = true;
   if (entry.timer !== null) {
     clearTimeout(entry.timer);
@@ -364,10 +414,14 @@ export async function resolvePendingConfigApproval(
         ? "🚫 <b>Denied</b>"
         : "⏱ <b>Expired</b>";
   try {
+    // Strip the keyboard: once resolved (approve/deny/timeout) the buttons
+    // must not stay tappable — a stale tap could otherwise re-hit the
+    // callback path.
     await deps.editCard({
       chatId: entry.chatId,
       messageId: entry.messageId,
       text: interim,
+      stripKeyboard: true,
     });
   } catch (err) {
     deps.log?.(
@@ -425,10 +479,12 @@ export async function handleRequestConfigFinalize(
       ? `✅ <b>Applied</b>${msg.detail ? `\n${escapeHtml(msg.detail)}` : ""}${liveNote}`
       : `⚠️ <b>Reconcile failed; rolled back</b>${msg.detail ? `\n${escapeHtml(msg.detail)}` : ""}`;
   try {
+    // Finalize is terminal — strip the keyboard so the buttons are gone.
     await deps.editCard({
       chatId: entry.chatId,
       messageId: entry.messageId,
       text: body,
+      stripKeyboard: true,
     });
   } catch (err) {
     deps.log?.(
@@ -483,20 +539,45 @@ export function _peekPendingConfigApprovalForTest(
 }
 
 /**
- * Parse `cfg:<requestId>:<choice>` callback data. Returns null on
+ * Parse `cfg:<requestId>:<epoch>:<choice>` callback data. Returns null on
  * malformed input. The callback handler in gateway.ts uses this +
- * resolvePendingConfigApproval to drive the tap → resolve flow.
+ * resolvePendingConfigApproval (passing the parsed `epoch`) to drive the
+ * tap → resolve flow; the epoch is verified against the live pending entry
+ * so a stale tap can never resolve a same-id live request.
+ *
+ * The 3-segment legacy form `cfg:<requestId>:<choice>` (no epoch) is still
+ * parsed for back-compat with cards posted before this change — `epoch` is
+ * undefined there, so the resolver skips the epoch check (degrades to the
+ * keyboard-strip protection alone). New cards always carry an epoch.
  */
 export function parseConfigApprovalCallback(
   data: string,
-): { requestId: string; choice: "approve" | "deny" } | null {
+): { requestId: string; epoch?: string; choice: "approve" | "deny" } | null {
   if (!data.startsWith("cfg:")) return null;
   const rest = data.slice(4);
-  const colon = rest.lastIndexOf(":");
-  if (colon < 0) return null;
-  const requestId = rest.slice(0, colon);
-  const choice = rest.slice(colon + 1);
-  if (requestId.length === 0 || requestId.length > 64) return null;
+  const lastColon = rest.lastIndexOf(":");
+  if (lastColon < 0) return null;
+  const choice = rest.slice(lastColon + 1);
   if (choice !== "approve" && choice !== "deny") return null;
-  return { requestId, choice };
+  const head = rest.slice(0, lastColon);
+  // New form carries an epoch as the segment before the choice:
+  // <requestId>:<epoch>. The epoch is hex (no colon), so split on the LAST
+  // remaining colon to separate it from a requestId (which is also hex).
+  const epochColon = head.lastIndexOf(":");
+  let requestId: string;
+  let epoch: string | undefined;
+  if (epochColon >= 0) {
+    requestId = head.slice(0, epochColon);
+    epoch = head.slice(epochColon + 1);
+    if (epoch.length === 0 || epoch.length > 32 || !/^[0-9a-fA-F]+$/.test(epoch)) {
+      // Not a well-formed epoch — treat the whole head as the legacy
+      // requestId (back-compat for ids that themselves contain a colon).
+      requestId = head;
+      epoch = undefined;
+    }
+  } else {
+    requestId = head;
+  }
+  if (requestId.length === 0 || requestId.length > 64) return null;
+  return { requestId, ...(epoch !== undefined ? { epoch } : {}), choice };
 }