switchroom 0.7.15 → 0.10.0

package/telegram-plugin/uat/scenarios/vault-request-access-end-to-end-dm.test.ts

@@ -0,0 +1,158 @@
+/**
+ * End-to-end UAT scenario for the agent-initiated vault_request_access
+ * flow — closes the test-coverage gap that allowed #1053 to ship.
+ *
+ * #1053: an agent called `vault_request_access`, operator approved,
+ * passphrase was entered, broker minted a grant token and wrote it
+ * to `.vault-token` — BUT the agent's subsequent `vault get` still
+ * returned VAULT-BROKER-DENIED because the CLI's get path didn't
+ * forward the token. Every unit test passed (gateway, broker, CLI
+ * each looked right in isolation) but the integration was broken.
+ *
+ * The lesson the operator drew: "test and prevent these kinds of
+ * things using the full telegram test bot." This scenario is that
+ * test — it round-trips through real Telegram, real broker, real
+ * agent, asserting the final state (vault get succeeds) rather
+ * than any single component's contract.
+ *
+ * Sibling: `vault-audit-allow-dm.test.ts` exercises the OPERATOR-
+ * initiated path (operator opens /vault audit, taps Allow on a
+ * recent denial). This scenario exercises the AGENT-initiated path
+ * (agent calls vault_request_access, operator approves the card
+ * the agent's tool emitted) — a different gateway handler
+ * (handleVaultRequestAccessCallback vs handleVaultRecentDenialCallback)
+ * but the same broker token-writing + grant-validation backend.
+ *
+ * **Skipped by default.** To unskip:
+ *
+ * 1. Standard UAT preflight (`uat/SETUP.md` §5-6) — test-harness
+ *    agent live, driver session auth'd, env vars set.
+ *
+ * 2. **Operator passphrase visibility.** The scenario must enter
+ *    the operator's vault passphrase in chat as part of the
+ *    approve flow. Set `TELEGRAM_UAT_VAULT_PASSPHRASE` in the
+ *    env so the scenario can send it. The gateway deletes the
+ *    passphrase message from chat history immediately after
+ *    caching it (see `deleteSensitiveMessage` in gateway.ts) so
+ *    no plaintext lingers.
+ *
+ * 3. **Sacrificial vault key.** Same convention as the
+ *    `/vault audit` scenario — pre-create a key the harness can
+ *    request. Suggested:
+ *
+ *    ```bash
+ *    TMPF=$(mktemp) && printf '%s' 'sentinel-1053-value' > "$TMPF" && \
+ *      switchroom vault set uat/req-access-target --file "$TMPF" \
+ *        --format string ; shred -u "$TMPF"
+ *    ```
+ *
+ *    Slash-namespaced shape on purpose — also exercises #1047
+ *    (vault-key regex allowing '/').
+ *
+ * 4. Remove `describe.skip` below.
+ *
+ * Why skipped: mutates host vault state (mints a 30-day grant on
+ * test-harness) — opt-in only. Cleanup is operator-side
+ * (`switchroom vault revoke <grant-id>` after the run).
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const SENTINEL_VALUE = "sentinel-1053-value";
+const TARGET_KEY = "uat/req-access-target";
+
+describe.skip("uat: vault_request_access end-to-end (#1053 regression)", () => {
+  it(
+    "agent calls tool → operator approves + enters passphrase → agent reads the value",
+    async () => {
+      const operatorPassphrase = process.env.TELEGRAM_UAT_VAULT_PASSPHRASE;
+      if (!operatorPassphrase) {
+        throw new Error(
+          "TELEGRAM_UAT_VAULT_PASSPHRASE must be set in env for this scenario " +
+          "(see SETUP.md). The scenario sends it via DM as part of the approve " +
+          "flow; the gateway deletes the message immediately after caching.",
+        );
+      }
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        // 1. Tell the agent to call the MCP tool. The agent's reply
+        //    is what fires the approval card — we don't fire it
+        //    from the driver side because the WHOLE POINT is to
+        //    cover the agent → gateway → broker → token-file
+        //    → agent path.
+        await sc.sendDM(
+          `Please call your vault_request_access MCP tool with ` +
+          `key="${TARGET_KEY}", scope="read", reason="UAT regression for #1053". ` +
+          `Then attempt to read the key once the operator confirms.`,
+        );
+
+        // 2. Wait for the bot's approval card. Anchor on the
+        //    headline emoji + tool-specific copy.
+        const card = await sc.expectMessage(/🔐.*wants vault access/, {
+          from: "bot",
+          timeout: 60_000,
+        });
+
+        // 3. Confirm the card carries the right inline keyboard.
+        //    Locate the [✅ Approve] button.
+        const kb = await sc.driver.getKeyboard(sc.botUserId, card.messageId);
+        expect(kb).not.toBeNull();
+        const approveButton = kb!
+          .flat()
+          .find((b) => b.callbackData !== undefined && /approve/i.test(b.text));
+        expect(approveButton, "card should have an [✅ Approve] button").toBeDefined();
+
+        // 4. Tap Approve. With no cached passphrase yet, the gateway
+        //    edits the card to prompt for the passphrase as the
+        //    next message (vault_request_access tap-to-unlock flow
+        //    from #1012 Phase 2 / #1034).
+        await sc.driver.pressButton(
+          sc.botUserId,
+          card.messageId,
+          approveButton!.callbackData!,
+        );
+        await sc.expectMessage(/Vault is locked.*Reply with your passphrase/, {
+          from: "bot",
+          timeout: 15_000,
+        });
+
+        // 5. Send the passphrase. Gateway caches it, deletes the
+        //    chat message via deleteSensitiveMessage, then auto-
+        //    resumes the mint flow. Card edits to the "Granted"
+        //    state when the broker accepts the attestation.
+        await sc.sendDM(operatorPassphrase);
+        await sc.expectMessage(/Granted.*read access/, {
+          from: "bot",
+          timeout: 30_000,
+        });
+
+        // 6. THE LOAD-BEARING ASSERTION FOR #1053: ask the agent
+        //    to fetch the key. The agent's `switchroom vault get`
+        //    MUST forward the freshly-minted token. If it doesn't
+        //    (the pre-#1053-fix state), the broker denies on the
+        //    peercred ACL and the agent reports VAULT-BROKER-DENIED.
+        //    Post-fix: the get succeeds and returns the sentinel
+        //    value the operator pre-staged.
+        await sc.sendDM(
+          `Now run: switchroom vault get ${TARGET_KEY} — and tell me ` +
+          `exactly what the command printed (including any error markers).`,
+        );
+        const replyAfterGet = await sc.expectMessage(
+          new RegExp(SENTINEL_VALUE),
+          { from: "bot", timeout: 60_000 },
+        );
+        expect(replyAfterGet.text).toContain(SENTINEL_VALUE);
+        // The bot's reply MUST NOT contain the denial marker. This
+        // is the regression guard: a future bug that reintroduces
+        // the silent token-drop would surface VAULT-BROKER-DENIED
+        // alongside the value (or instead of it).
+        expect(replyAfterGet.text).not.toMatch(/VAULT-BROKER-DENIED/);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    300_000, // 5 min — covers card render + Approve tap + passphrase
+             // round-trip + grant mint + agent's next turn + vault get.
+  );
+});

package/telegram-plugin/uat/scenarios/voice-inbound-dm.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Voice-inbound scenario — driver sends a voice note (OGG/Opus)
+ * to the test bot, gateway's `voice_in` skill transcribes it,
+ * bot replies with text.
+ *
+ * Part of: https://github.com/switchroom/switchroom/issues/866
+ *
+ * **Gated by fixture + bot config.** To unskip:
+ *
+ * 1. Generate a 1-second silent OGG/Opus fixture:
+ *
+ *    ```bash
+ *    mkdir -p telegram-plugin/uat/fixtures/voice
+ *    ffmpeg -f lavfi -i anullsrc=r=48000:cl=mono -t 1 \
+ *      -c:a libopus -b:a 32k \
+ *      telegram-plugin/uat/fixtures/voice/silence-1s.opus
+ *    ```
+ *
+ *    (Fixture is intentionally NOT committed to git — keep the repo
+ *    light. Generate locally before unskipping.)
+ *
+ * 2. Verify the test-harness agent has `voice_in` configured. The
+ *    default profile may not enable it; check `switchroom config
+ *    show test-harness` for `channels.telegram.voice_in.enabled`.
+ *
+ * 3. Remove the `describe.skip` below.
+ *
+ * Why skipped by default: voice transcription costs money per call
+ * (OpenAI/Whisper) and slow turns are expected — keeping this off
+ * the default UAT path until someone explicitly tests voice.
+ */
+
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const FIXTURE = path.resolve(
+  __dirname,
+  "..",
+  "fixtures",
+  "voice",
+  "silence-1s.opus",
+);
+
+describe.skip("uat: voice-inbound DM round-trip", () => {
+  it("driver sends a voice note, bot transcribes + replies within 60s", async () => {
+    if (!existsSync(FIXTURE)) {
+      throw new Error(
+        `voice fixture not found at ${FIXTURE} — see scenario header to generate one`,
+      );
+    }
+    const sc = await spinUp({ agent: "test-harness" });
+    try {
+      await sc.driver.sendVoice(sc.botUserId, FIXTURE);
+      const reply = await sc.expectMessage(/.+/, {
+        from: "bot",
+        timeout: 60_000,
+      });
+      expect(reply.text.length).toBeGreaterThan(0);
+    } finally {
+      await sc.tearDown();
+    }
+  });
+});

package/telegram-plugin/vault-approval-posture.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve the vault grant-card approval posture from switchroom config.
+ *
+ * Pre-#1115-follow-up this module also loaded the auto-unlock blob
+ * (file-based on legacy installs, broker-IPC `get_unlock_passphrase`
+ * on Docker) and surfaced the plaintext passphrase to the gateway so
+ * it could attest mint_grant calls. The reviewer flagged that as a
+ * bypass surface (claude in the same agent container could exfiltrate
+ * the passphrase via /proc or broker socket). Pivoted to broker-
+ * mediated attestation: the passphrase NEVER leaves the broker
+ * process; the gateway just signals operator-tap intent via
+ * `attest_via_posture: true` on mint_grant / list_grants.
+ *
+ * What this module does NOW: read `vault.broker.approvalAuth` from
+ * the operator's switchroom.yaml and tell the gateway whether to
+ * branch into the silent-mint code path. Nothing else.
+ *
+ * Behaviour:
+ *  - `approvalAuth` absent / `passphrase` → passphrase posture.
+ *  - `approvalAuth: telegram-id` → telegram-id posture (gateway will
+ *    use attest_via_posture on broker calls).
+ *  - `approvalAuth` set to anything else → passphrase posture (the
+ *    schema rejects unknown values at startup; this is defence in
+ *    depth in case the schema is bypassed).
+ */
+
+export interface VaultBrokerPostureConfig {
+  approvalAuth?: string
+}
+
+export interface ResolvedPosture {
+  mode: 'passphrase' | 'telegram-id'
+}
+
+export function resolveVaultApprovalPosture(
+  broker: VaultBrokerPostureConfig | undefined,
+): ResolvedPosture {
+  if (broker?.approvalAuth === 'telegram-id') {
+    return { mode: 'telegram-id' }
+  }
+  return { mode: 'passphrase' }
+}

package/telegram-plugin/welcome-text.ts

@@ -159,6 +159,7 @@ export function helpText(agentName: string): string {
     ``,
     `<code>/start</code> — pairing instructions`,
     `<code>/status</code> — agent, model, auth`,
+    `<code>/vault audit &lt;agent&gt;</code> — admin: review agent's vault access + one-tap [🔓 Allow] on recent denials`,
     `<code>/commands</code> — full command list`,
   ].join("\n");
 }

package/telegram-plugin/active-pins-sweep.ts

@@ -1,204 +0,0 @@
-/**
- * Sweep logic for the active-pins sidecar.
- *
- * The sidecar (see `active-pins.ts`) records every progress-card
- * message the bot has pinned but not yet unpinned. Two lifecycle
- * events consume it:
- *
- *   1. Startup — when a new bot process boots, it sweeps any entries
- *      left over from a prior session that crashed or was killed
- *      mid-turn. Without this, the pins stay on Telegram forever
- *      because the in-memory map that tracks them died with the old
- *      process.
- *
- *   2. Pre-restart — when the /restart, /reconcile --restart, or
- *      /update commands fire a self-restart, the bot proactively
- *      unpins any still-pinned cards before it gets SIGTERM'd. This
- *      avoids a ~1s window where the restart ack is visible in chat
- *      but the previous turn's progress card is still pinned.
- *
- * Both consumers call `sweepActivePins`, which is shaped as a pure
- * function that takes the unpin callback as an argument. That keeps
- * it testable in isolation — the tests pass a fake unpin and assert
- * which pins were visited and whether the sidecar was cleared.
- */
-
-import { readActivePins, clearActivePins, type ActivePin } from "./active-pins.js";
-
-export type UnpinFn = (chatId: string, messageId: number) => Promise<unknown>;
-/**
- * Optional pre-unpin hook. Called once per sidecar entry before the
- * unpin fires. Used by the boot-time orphan-pin reaper (#689) to edit
- * the message body to a "Restart interrupted this work" banner, so the
- * user sees WHY the card stopped updating rather than silently losing
- * the pin.
- *
- * Hook errors are logged and swallowed: a banner edit failing must
- * never block the unpin (frozen card is worse than no card).
- */
-export type EditBeforeUnpinFn = (pin: ActivePin) => Promise<unknown>;
-
-export interface SweepOptions {
-  /** Upper bound on how long to wait for all unpin calls before returning. */
-  timeoutMs?: number;
-  /** Optional log hook — called with human-readable progress/error lines. */
-  log?: (msg: string) => void;
-  /**
-   * Optional per-pin edit hook fired BEFORE the unpin. Failures are
-   * caught and logged; the unpin still runs. See {@link EditBeforeUnpinFn}.
-   */
-  editBeforeUnpin?: EditBeforeUnpinFn;
-}
-
-export interface SweepResult {
-  swept: ActivePin[];
-  timedOut: boolean;
-}
-
-/**
- * Unpin every entry in the sidecar, then clear it. Bounded by
- * `timeoutMs` (default 2s) so a slow Telegram API can't block a
- * restart indefinitely. Unpin failures are logged and swallowed —
- * the sidecar is cleared regardless so stale entries don't pile up
- * on subsequent boots.
- */
-export async function sweepActivePins(
-  agentDir: string,
-  unpin: UnpinFn,
-  options: SweepOptions = {},
-): Promise<SweepResult> {
-  const log = options.log ?? (() => {});
-  const timeoutMs = options.timeoutMs ?? 2000;
-  const pins = readActivePins(agentDir);
-  if (pins.length === 0) return { swept: [], timedOut: false };
-
-  log(`sweeping ${pins.length} active pin(s)`);
-  const editBeforeUnpin = options.editBeforeUnpin;
-  const attempts = pins.map((pin) =>
-    Promise.resolve()
-      .then(async () => {
-        if (editBeforeUnpin != null) {
-          try {
-            await editBeforeUnpin(pin);
-          } catch (err) {
-            // Banner edits are best-effort — message may already be gone
-            // or the bot may have lost edit rights. Don't block unpin.
-            const msg = err instanceof Error ? err.message : String(err);
-            log(`banner edit failed for ${pin.chatId}/${pin.messageId}: ${msg}`);
-          }
-        }
-        return unpin(pin.chatId, pin.messageId);
-      })
-      .catch((err: unknown) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        log(`unpin failed for ${pin.chatId}/${pin.messageId}: ${msg}`);
-      }),
-  );
-
-  let timedOut = false;
-  await Promise.race([
-    Promise.allSettled(attempts),
-    new Promise<void>((resolve) =>
-      setTimeout(() => {
-        timedOut = true;
-        resolve();
-      }, timeoutMs),
-    ),
-  ]);
-
-  // By design: clear the sidecar on timeout even though in-flight unpins
-  // may not have landed. Telegram's unpin is idempotent, so a retried unpin
-  // on the next boot is a cheap no-op, whereas keeping the sidecar entries
-  // around would have the sweep re-fire forever whenever Telegram is slow.
-  clearActivePins(agentDir);
-  return { swept: pins, timedOut };
-}
-
-/**
- * A single pinned message returned from Telegram's `getChat` API,
- * narrowed to the fields this sweep needs. `fromId` is null when the
- * pinned message has no `from` (e.g., anonymous channel posts) — in
- * that case the sweep treats the pin as foreign and stops, since we
- * can only confidently unpin messages we authored ourselves.
- */
-export interface PinnedMessageInfo {
-  messageId: number;
-  fromId: number | null;
-}
-
-export type GetTopPinFn = (chatId: string) => Promise<PinnedMessageInfo | null>;
-
-export interface BotAuthoredSweepResult {
-  /** One entry per chat — how many bot-authored pins were unpinned there. */
-  perChat: Record<string, number>;
-  /** Total across all chats. */
-  total: number;
-}
-
-/**
- * Sweep bot-authored pinned messages from the given chats. Telegram's
- * Bot API doesn't expose a "list all pinned messages" endpoint, only
- * `getChat().pinned_message` which returns the topmost pin. This
- * iterates that endpoint: if the top pin is authored by our bot, we
- * unpin it and re-check — the next most recent pin bubbles up. We
- * stop when the top pin is either missing or authored by someone
- * else, which is the safe behavior: a user-pinned message acts as a
- * barrier so we never interfere with pins the user made themselves.
- *
- * The per-chat loop is bounded by `maxPerChat` (default 32) so a
- * chat with an unexpected pile of bot pins can't spin forever.
- * Failures from `getChat` or `unpin` are logged and tolerated — the
- * sweep advances to the next chat rather than aborting the boot
- * sequence.
- *
- * This complements `sweepActivePins`, which only touches entries
- * previously recorded in the sidecar. Some stale pins never land in
- * the sidecar (e.g., if a pin write raced a crash before `addActivePin`
- * ran, or if the sidecar file itself was lost). This function is the
- * belt-and-suspenders backstop that picks those up on the next boot.
- */
-export async function sweepBotAuthoredPins(
-  chatIds: ReadonlyArray<string>,
-  botUserId: number,
-  getTopPin: GetTopPinFn,
-  unpin: UnpinFn,
-  options: SweepOptions & { maxPerChat?: number } = {},
-): Promise<BotAuthoredSweepResult> {
-  const log = options.log ?? (() => {});
-  const maxPerChat = options.maxPerChat ?? 32;
-  const perChat: Record<string, number> = {};
-  let total = 0;
-
-  for (const chatId of chatIds) {
-    let unpinnedHere = 0;
-    for (let i = 0; i < maxPerChat; i++) {
-      let top: PinnedMessageInfo | null;
-      try {
-        top = await getTopPin(chatId);
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        log(`getChat failed for ${chatId}: ${msg}`);
-        break;
-      }
-      if (top == null) break;
-      if (top.fromId !== botUserId) break;
-      try {
-        await unpin(chatId, top.messageId);
-        unpinnedHere++;
-        total++;
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        log(`unpin failed for ${chatId}/${top.messageId}: ${msg}`);
-        // If unpin fails, the top pin stays — another loop iteration
-        // would fetch the same one and loop forever. Break out.
-        break;
-      }
-    }
-    if (unpinnedHere > 0) {
-      perChat[chatId] = unpinnedHere;
-      log(`unpinned ${unpinnedHere} bot-authored pin(s) in ${chatId}`);
-    }
-  }
-
-  return { perChat, total };
-}

package/telegram-plugin/active-pins.ts

@@ -1,146 +0,0 @@
-/**
- * Pure helpers for tracking pinned progress-card message IDs across
- * restarts.
- *
- * The progress-card driver pins a per-turn card on first emit and
- * unpins on turn complete. That lifecycle is in-memory only, so a
- * crash or kill mid-turn leaves a pinned message with no cleanup
- * path — on restart, the in-memory map is empty and Telegram still
- * shows the stale pin.
- *
- * This module persists the set of currently-pinned cards to a
- * `.active-pins.json` sidecar under `$AGENT_DIR`. The server adds an
- * entry right after `pinChatMessage` succeeds, removes the entry
- * after `unpinChatMessage`, and on startup reads the file to sweep
- * any stale entries (best-effort unpin) before the driver starts.
- *
- * All helpers are filesystem-only — no Telegram side effects — so
- * they're unit-testable in isolation, mirroring `handoff-continuity.ts`.
- */
-
-import { readFileSync, writeFileSync, renameSync, existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-
-export const ACTIVE_PINS_FILENAME = ".active-pins.json";
-
-export interface ActivePin {
-  chatId: string;
-  messageId: number;
-  turnKey: string;
-  pinnedAt: number;
-  /**
-   * Per-agent identity for the pin. Optional in the on-disk shape so
-   * sidecars written before per-agent cards (#per-agent-cards) still
-   * parse cleanly — readers should treat a missing field as the parent
-   * sentinel (`__parent__`).
-   */
-  agentId?: string;
-}
-
-function pinsPath(agentDir: string): string {
-  return join(agentDir, ACTIVE_PINS_FILENAME);
-}
-
-/**
- * Read the active-pins sidecar. Missing, empty, or malformed files
- * return an empty array — callers never have to handle parse errors.
- * Entries that fail shape validation are dropped silently so a
- * corrupted file can't brick the startup sweep.
- */
-export function readActivePins(agentDir: string): ActivePin[] {
-  const p = pinsPath(agentDir);
-  if (!existsSync(p)) return [];
-  let raw: string;
-  try {
-    raw = readFileSync(p, "utf-8");
-  } catch {
-    return [];
-  }
-  if (raw.trim().length === 0) return [];
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return [];
-  }
-  if (!Array.isArray(parsed)) return [];
-  const out: ActivePin[] = [];
-  for (const item of parsed) {
-    if (
-      item != null &&
-      typeof item === "object" &&
-      typeof (item as ActivePin).chatId === "string" &&
-      typeof (item as ActivePin).messageId === "number" &&
-      typeof (item as ActivePin).turnKey === "string" &&
-      typeof (item as ActivePin).pinnedAt === "number"
-    ) {
-      const aid = (item as ActivePin).agentId;
-      const entry: ActivePin = aid != null && typeof aid === "string"
-        ? (item as ActivePin)
-        : { ...(item as ActivePin), agentId: undefined };
-      out.push(entry);
-    }
-  }
-  return out;
-}
-
-/**
- * Atomically overwrite the sidecar with the given list. Writing an
- * empty list deletes the file so a fresh restart sees no state.
- */
-export function writeActivePins(agentDir: string, pins: ActivePin[]): void {
-  const p = pinsPath(agentDir);
-  if (pins.length === 0) {
-    try {
-      unlinkSync(p);
-    } catch {
-      /* already gone */
-    }
-    return;
-  }
-  const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
-  try {
-    writeFileSync(tmp, JSON.stringify(pins) + "\n", "utf-8");
-    renameSync(tmp, p);
-  } catch {
-    /* best-effort — failsafe cleanup is cosmetic, not safety-critical */
-  }
-}
-
-/**
- * Append a new pin to the sidecar. Idempotent on `(chatId, messageId)`
- * — a duplicate add replaces the existing entry so `pinnedAt` reflects
- * the most recent pin.
- */
-export function addActivePin(agentDir: string, pin: ActivePin): void {
-  const existing = readActivePins(agentDir).filter(
-    (p) => !(p.chatId === pin.chatId && p.messageId === pin.messageId),
-  );
-  existing.push(pin);
-  writeActivePins(agentDir, existing);
-}
-
-/**
- * Remove the pin matching `(chatId, messageId)`. No-op when the
- * sidecar or entry is absent.
- */
-export function removeActivePin(agentDir: string, chatId: string, messageId: number): void {
-  const existing = readActivePins(agentDir);
-  const next = existing.filter(
-    (p) => !(p.chatId === chatId && p.messageId === messageId),
-  );
-  if (next.length === existing.length) return;
-  writeActivePins(agentDir, next);
-}
-
-/**
- * Delete the sidecar outright. Called after the startup sweep so the
- * next run starts clean regardless of unpin success.
- */
-export function clearActivePins(agentDir: string): void {
-  try {
-    unlinkSync(pinsPath(agentDir));
-  } catch {
-    /* already gone */
-  }
-}