switchroom 0.8.1 → 0.11.0

package/telegram-plugin/fleet-fallback-gate.ts

@@ -0,0 +1,105 @@
+/**
+ * Re-entry guard + dedup window for fleet-wide auto-fallback.
+ *
+ * Lifted out of gateway.ts so the dedup state is constructable per-test
+ * (gateway.ts module state was hard to reach from vitest — every test
+ * shared the same in-flight Promise + last-fired timestamp).
+ *
+ * Contract (the "honesty contract" from PR #1317 review):
+ *
+ *   `wouldFire()` is the SYNCHRONOUS read the model-unavailable card
+ *   uses to decide whether to advertise "Auto-failover in progress".
+ *   It MUST agree with the dispatcher's actual behavior — otherwise
+ *   the card lies (claims a swap is coming when the dispatcher will
+ *   dedup-drop or bail).
+ *
+ *   Three reasons `wouldFire()` returns false:
+ *     1. A swap is already in flight (collapse concurrent fires).
+ *     2. The post-trigger dedup window is still active (the user
+ *        already saw a swap announcement; another one would oscillate).
+ *     3. The broker is unreachable — the dispatcher would just bail
+ *        with `reason=no-broker-client`, leaving the card to lie.
+ *        Optional: only checked when `brokerReachable` is supplied.
+ *
+ *   `markFired()` is called ONLY on actual swaps (kind: 'switched').
+ *   No-ops (no broker, no eligible target, idempotent skip) DO NOT
+ *   arm the suppression window — otherwise a transient hiccup blocks
+ *   the next 30s of legitimate fires.
+ */
+
+export interface FleetFallbackGateOptions {
+  /** Suppression window in ms after a successful swap. */
+  dedupMs: number;
+  /** Time source (overridable in tests). */
+  nowFn?: () => number;
+  /**
+   * Synchronous probe of broker reachability. Optional. Returning false
+   * makes `wouldFire()` return false so the card stays honest about a
+   * fire that would otherwise bail in the dispatcher.
+   *
+   * Synchronous on purpose: `wouldFire()` runs on the card-render path
+   * and must not block. A connection-cached flag (e.g. a UDS reachability
+   * check populated by a background heartbeat) fits this shape.
+   */
+  brokerReachable?: () => boolean;
+}
+
+export interface FleetFallbackGate {
+  /** True iff a fresh fire would actually invoke the dispatcher. */
+  wouldFire(): boolean;
+  /** Run a fire-and-forget action under the gate. Collapses concurrent
+   *  callers to the same in-flight Promise. The action's resolved value
+   *  controls whether the dedup window arms (true = arm, false = skip).
+   *  Caller-thrown errors are swallowed (logged via `onError`). */
+  fire(action: () => Promise<boolean>, onError?: (err: unknown) => void): Promise<void>;
+  /** Test seam — reset to fresh state. Production code should not call this. */
+  reset(): void;
+  /** Test/debug — current internal state. */
+  inspect(): { inFlight: boolean; lastFiredAtMs: number };
+}
+
+export function createFleetFallbackGate(opts: FleetFallbackGateOptions): FleetFallbackGate {
+  const nowFn = opts.nowFn ?? (() => Date.now());
+  let inFlight: Promise<void> | null = null;
+  // -Infinity = never fired. Concrete number = wall-clock ms of the
+  // last actual swap. Sentinel matters in tests (fake clocks at t=0
+  // would otherwise look like "just fired" and falsely arm dedup).
+  let lastFiredAtMs = Number.NEGATIVE_INFINITY;
+
+  function wouldFire(): boolean {
+    if (inFlight) return false;
+    if (nowFn() - lastFiredAtMs < opts.dedupMs) return false;
+    if (opts.brokerReachable && !opts.brokerReachable()) return false;
+    return true;
+  }
+
+  function fire(action: () => Promise<boolean>, onError?: (err: unknown) => void): Promise<void> {
+    if (inFlight) return inFlight;
+    if (nowFn() - lastFiredAtMs < opts.dedupMs) return Promise.resolve();
+    if (opts.brokerReachable && !opts.brokerReachable()) return Promise.resolve();
+
+    inFlight = (async () => {
+      try {
+        const didSwap = await action();
+        if (didSwap) lastFiredAtMs = nowFn();
+      } catch (err) {
+        if (onError) onError(err);
+      } finally {
+        inFlight = null;
+      }
+    })();
+    return inFlight;
+  }
+
+  return {
+    wouldFire,
+    fire,
+    reset() {
+      inFlight = null;
+      lastFiredAtMs = Number.NEGATIVE_INFINITY;
+    },
+    inspect() {
+      return { inFlight: inFlight !== null, lastFiredAtMs };
+    },
+  };
+}

package/telegram-plugin/gateway/approval-callback.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for `buildGrantedKeyboard` — the post-tap inline-keyboard
+ * surfaced on a granted approval card (RFC E §4.3 — granted-card
+ * confirmations gain the [ 📖 Open in Drive ] deep-link button).
+ *
+ * Scope-driven and pure, so the test runs without mocking grammy's
+ * Context or the approval kernel. The full handler in
+ * `approval-callback.ts` glues this onto the consumed-scope payload
+ * the kernel returns; the routing decision lives entirely in this
+ * builder.
+ */
+
+import { describe, expect, it } from "vitest";
+import { InlineKeyboard } from "grammy";
+import { buildGrantedKeyboard } from "./approval-callback.js";
+
+/**
+ * Helper — pull the `[{text, url}]` rows out of a grammy InlineKeyboard
+ * so we can assert without poking into its internal shape too hard.
+ */
+function rows(kb: InlineKeyboard): Array<Array<{ text: string; url?: string }>> {
+  return kb.inline_keyboard.map((row) =>
+    row.map((btn) => ({
+      text: btn.text,
+      ...("url" in btn ? { url: btn.url } : {}),
+    })),
+  );
+}
+
+describe("buildGrantedKeyboard — Drive scopes", () => {
+  it("emits Open-in-Drive for a single-doc grant", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:D1");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/file/d/D1/view",
+        },
+      ],
+    ]);
+  });
+
+  it("emits Open-in-Drive for a folder grant (canonical folder URL)", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:folder/F1/**");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/drive/folders/F1",
+        },
+      ],
+    ]);
+  });
+
+  it("emits Open-in-Drive for write-namespace grants on a single doc", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:write:D1");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/file/d/D1/view",
+        },
+      ],
+    ]);
+  });
+
+  it("emits Open-in-Drive for suggest-namespace folder grants", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:suggest:folder/F1/**");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/drive/folders/F1",
+        },
+      ],
+    ]);
+  });
+});
+
+describe("buildGrantedKeyboard — no button cases", () => {
+  it("returns undefined for the whole-Drive grant (no specific artifact)", () => {
+    expect(buildGrantedKeyboard("doc:gdrive:**")).toBeUndefined();
+    expect(buildGrantedKeyboard("doc:gdrive:suggest:**")).toBeUndefined();
+    expect(buildGrantedKeyboard("doc:gdrive:write:**")).toBeUndefined();
+  });
+
+  it("returns undefined for non-Drive scopes (secrets, system, vault)", () => {
+    expect(buildGrantedKeyboard("secret:OPENAI_API_KEY")).toBeUndefined();
+    expect(buildGrantedKeyboard("system:reconnect:gdrive")).toBeUndefined();
+    expect(buildGrantedKeyboard("vault:read:gdrive:klanker:refresh_token")).toBeUndefined();
+  });
+
+  it("returns undefined for unparseable Drive scopes (defense in depth)", () => {
+    // A folder id containing a slash slips past prefix matching but is
+    // rejected by parseDriveScope's id-charset check — the granted-card
+    // edit MUST NOT render a URL button derived from such a string.
+    expect(buildGrantedKeyboard("doc:gdrive:folder/abc/def/**")).toBeUndefined();
+    expect(buildGrantedKeyboard("doc:gdrive:write:abc?evil=1")).toBeUndefined();
+  });
+});

package/telegram-plugin/gateway/approval-callback.ts

@@ -21,13 +21,31 @@
  * approval_lookup (RFC §10) to discover the outcome and proceed.
  */
 
-import type { Context } from "grammy";
+import { type Context, InlineKeyboard } from "grammy";
 import { parseApprovalCallback, ttlMsFromToken } from "./approval-card.js";
 import {
   approvalConsume,
   approvalRecord,
 } from "../../src/vault/approvals/client.js";
 import type { ApprovalDecisionMode } from "../../src/vault/approvals/schema.js";
+import { scopeToOpenInDriveButton } from "../../src/drive/deep-links.js";
+
+/**
+ * Build the post-tap keyboard for a granted decision. Today this is
+ * just the `[ 📖 Open in Drive ]` button when the granted scope names
+ * a specific Drive doc or folder (RFC E §4.3 — granted-card
+ * confirmations gain the deep-link). Returns `undefined` when no
+ * post-tap keyboard applies, which the gateway translates into
+ * `reply_markup: undefined` to strip the original action buttons.
+ *
+ * Pure / scope-driven — no kernel I/O — so it stays unit-testable
+ * without mocking grammy's Context.
+ */
+export function buildGrantedKeyboard(scope: string): InlineKeyboard | undefined {
+  const btn = scopeToOpenInDriveButton(scope);
+  if (btn === null) return undefined;
+  return new InlineKeyboard().url(btn.text, btn.url);
+}
 
 export async function handleApprovalCallback(
   ctx: Context,
@@ -109,7 +127,10 @@ export async function handleApprovalCallback(
     return;
   }
 
-  // Edit the original card to its post-tap state and drop the keyboard.
+  // Edit the original card to its post-tap state. Drop the original
+  // action keyboard either way; on a successful grant for a Drive
+  // scope, surface `[ 📖 Open in Drive ]` so the user can jump
+  // straight from "agent has access" to the doc (RFC E §4.3).
   const icon = granted ? "✅" : "🚫";
   const newBody =
     `${icon} ${displayMode}` +
@@ -117,8 +138,15 @@ export async function handleApprovalCallback(
       ? ` · /approvals revoke <code>${decision_id}</code>`
       : "");
 
+  const postTapKeyboard = granted && consumed.scope
+    ? buildGrantedKeyboard(consumed.scope)
+    : undefined;
+
   try {
-    await ctx.editMessageText(newBody, { parse_mode: "HTML", reply_markup: undefined });
+    await ctx.editMessageText(newBody, {
+      parse_mode: "HTML",
+      reply_markup: postTapKeyboard,
+    });
   } catch {
     // Best-effort: card may have been edited or deleted under us.
   }

package/telegram-plugin/gateway/auth-add-flow.ts

@@ -0,0 +1,326 @@
+/**
+ * `/auth add <label>` Telegram chat flow (RFC H §4.3 add-account, §7.3).
+ *
+ * The headline use case: every account on the fleet is rate-limited,
+ * the LLM is unreachable, and the operator is on their phone. They
+ * need a deterministic — LLM-free — chat path to add a fresh Anthropic
+ * OAuth account. This module owns that flow end-to-end:
+ *
+ *   1. Operator sends `/auth add <label>`.
+ *   2. Gateway calls {@link startAccountAuthSession} → spawns
+ *      `claude setup-token` against a scratch directory under
+ *      `~/.switchroom/accounts/.in-progress/<label>-<rand>/`, captures
+ *      the OAuth authorize URL, and tucks pending state into
+ *      {@link pendingAuthAddFlows}.
+ *   3. Gateway replies to chat with the URL + paste instructions.
+ *   4. Operator opens URL, logs in, copies the browser code, pastes
+ *      into chat. Gateway's `pendingReauthFlows`-style intercept
+ *      catches the paste and calls {@link submitAccountAuthCode}.
+ *   5. Helper reads `<scratch>/.credentials.json` (the dotfile that
+ *      `claude setup-token` writes on success — pinned in
+ *      `src/auth/broker/server-add-account.test.ts`), builds the
+ *      {@link AddAccountCredentials} payload, and the gateway calls
+ *      broker `addAccount(label, credentials, replace=false)`.
+ *   6. Scratch dir is wiped on every code path — success, cancel,
+ *      paste-failure, TTL timeout, gateway shutdown.
+ *
+ * Why a separate module (vs reusing `src/auth/manager.ts`):
+ *
+ *   - `startAuthSession` writes `<agentDir>/.claude/.setup-token.session.json`
+ *     and is built around the per-agent OAuth flow. The `/auth add`
+ *     flow has no agent — the resulting credentials become a
+ *     broker-managed account that any agent can be set to. Threading
+ *     `agentDir` through it would corrupt the agent's own auth state
+ *     if the operator's add-flow collides with a normal reauth.
+ *   - The chat-flow surface is deterministic and stateless beyond
+ *     `pendingAuthAddFlows`. Reusing the full manager would inherit
+ *     legacy slot logic, tmp-dir cleanup heuristics, and stale-session
+ *     detection that doesn't apply when each `/auth add` creates a
+ *     fresh, unguessable scratch dir of its own.
+ *
+ * What we DO reuse: the pure parsing helpers — `parseSetupTokenUrl`
+ * (handles both claude.ai/oauth and claude.com/cai/oauth shapes),
+ * `extractCodeChallenge` (PKCE stale-session detection), and
+ * `readTokenFromCredentialsFile` (validates the `sk-ant-oat...` token
+ * shape). Those are label-agnostic.
+ *
+ * **Hard rule: NEVER touch the agent's claude process.** This flow runs
+ * as a deterministic chat handler in the gateway. The URL goes straight
+ * to chat via `bot.api.sendMessage`. The code paste is intercepted by
+ * the gateway, never forwarded to the agent's bridge. If every account
+ * on the fleet is rate-limited the LLM is unreachable — that's the
+ * whole point of the flow existing.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+import {
+  parseSetupTokenUrl,
+  readTokenFromCredentialsFile,
+} from '../../src/auth/manager.js'
+import type {
+  AddAccountCredentials,
+  AnthropicAddAccountCredentials,
+} from '../../src/auth/broker/client.js'
+
+/* ── Pending-state map ────────────────────────────────────────────────── */
+
+/**
+ * In-flight `/auth add` flow keyed by Telegram chat id. The gateway's
+ * generic message intercept (sibling to `pendingReauthFlows`) reads
+ * this map to decide whether a sk-ant-…-shaped paste belongs to an
+ * add flow or to a reauth flow.
+ *
+ * TTL matches `REAUTH_INTERCEPT_TTL_MS` (10 minutes); the reaper sweep
+ * in gateway.ts walks both maps each minute.
+ */
+export interface PendingAuthAddFlow {
+  label: string
+  scratchDir: string
+  /** PID of the spawned `claude setup-token` process, for cancel-kill. */
+  child: ChildProcess
+  startedAt: number
+}
+export const pendingAuthAddFlows = new Map<string, PendingAuthAddFlow>()
+
+/* ── Scratch dir lifecycle ────────────────────────────────────────────── */
+
+/**
+ * Pick a fresh scratch path under
+ * `~/.switchroom/accounts/.in-progress/<label>-<rand>/`.
+ *
+ * The leading dot keeps the dir hidden from `listAccounts(home)` in
+ * `src/auth/account-store.ts`, which enumerates accounts by scanning
+ * `~/.switchroom/accounts/`. That listing is the source of truth for
+ * broker `list-state` — a half-written add-in-progress must NOT
+ * appear there. `.in-progress/` is also outside the broker's
+ * managed-artifact whitelist, so a stray dir won't blow up on the
+ * next apply.
+ *
+ * Random suffix is 8 bytes of crypto-grade randomness so:
+ *   - two concurrent operators adding the same label can't collide
+ *     on the scratch path
+ *   - an attacker watching `~/.switchroom/accounts/.in-progress/`
+ *     can't predict the next dir name and squat a symlink
+ */
+export function pickScratchDir(label: string, home: string = homedir()): string {
+  const suffix = randomBytes(8).toString('hex')
+  return join(home, '.switchroom', 'accounts', '.in-progress', `${label}-${suffix}`)
+}
+
+/**
+ * Best-effort scratch-dir wipe. Used on every exit path — success,
+ * cancel, timeout, error. Synchronous because the caller has already
+ * settled the user-facing reply by the time we get here; an extra
+ * tick of latency is not worth event-loop juggling.
+ */
+export function cleanScratchDir(scratchDir: string): void {
+  try {
+    rmSync(scratchDir, { recursive: true, force: true })
+  } catch {
+    // best-effort
+  }
+}
+
+/* ── Subprocess lifecycle ─────────────────────────────────────────────── */
+
+export interface StartAccountAuthSessionResult {
+  loginUrl: string
+  scratchDir: string
+  child: ChildProcess
+}
+
+/**
+ * Spawn `claude setup-token` against a fresh scratch directory and
+ * resolve once the authorize URL has been parsed from its stdout/stderr.
+ *
+ * Why we *don't* use tmux: the `submitAuthCode` path in
+ * `src/auth/manager.ts` uses tmux because that flow is interactive —
+ * an operator on a host can `tmux attach` to inspect the auth prompt
+ * if anything goes wrong. The chat flow has no equivalent escape
+ * hatch (the operator is on their phone) and a pipe-based subprocess
+ * is far easier to lifecycle-manage from a long-running gateway. We
+ * write the code to the child's stdin in {@link submitAccountAuthCode}.
+ *
+ * The child is left running between {@link startAccountAuthSession}
+ * and {@link submitAccountAuthCode} — closing stdin before the code
+ * is pasted would tear down the OAuth session.
+ *
+ * Timeout default: 12 seconds to see the URL. claude setup-token
+ * typically prints the URL within ~3–5s; 12s covers an unloaded VM
+ * with slow startup. Caller passes the timeout via opts so tests can
+ * shorten it.
+ */
+export async function startAccountAuthSession(
+  label: string,
+  opts: {
+    home?: string
+    urlTimeoutMs?: number
+    /** Override the binary name (tests). */
+    claudeBinary?: string
+  } = {},
+): Promise<StartAccountAuthSessionResult> {
+  const home = opts.home ?? homedir()
+  const urlTimeoutMs = opts.urlTimeoutMs ?? 12_000
+  const binary = opts.claudeBinary ?? 'claude'
+
+  const scratchDir = pickScratchDir(label, home)
+  mkdirSync(scratchDir, { recursive: true, mode: 0o700 })
+
+  // BROWSER=/bin/true: same rationale as src/auth/manager.ts's
+  // startAuthSession — suppress claude setup-token's host-side browser
+  // auto-launch (would land on Claude's login page with no cookies on
+  // a headless box). The chat flow is paste-only.
+  const child = spawn(binary, ['setup-token'], {
+    env: {
+      ...process.env,
+      CLAUDE_CONFIG_DIR: scratchDir,
+      BROWSER: '/bin/true',
+    },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+
+  // Aggregate stdout+stderr; the URL can land on either channel
+  // depending on claude CLI version.
+  let buffer = ''
+  const collect = (chunk: Buffer): void => {
+    buffer += chunk.toString('utf8')
+  }
+  child.stdout?.on('data', collect)
+  child.stderr?.on('data', collect)
+
+  // Race: URL detection vs timeout vs child exit before URL appeared.
+  const loginUrl = await new Promise<string>((resolve, reject) => {
+    const deadline = setTimeout(() => {
+      cleanup()
+      reject(new Error(`claude setup-token did not print an OAuth URL within ${urlTimeoutMs}ms`))
+    }, urlTimeoutMs)
+
+    const tick = setInterval(() => {
+      const url = parseSetupTokenUrl(buffer)
+      if (url) {
+        cleanup()
+        resolve(url)
+      }
+    }, 200)
+
+    const onExit = (code: number | null): void => {
+      cleanup()
+      reject(new Error(`claude setup-token exited (code ${code}) before printing OAuth URL`))
+    }
+    child.once('exit', onExit)
+
+    function cleanup(): void {
+      clearTimeout(deadline)
+      clearInterval(tick)
+      child.removeListener('exit', onExit)
+    }
+  }).catch((err) => {
+    // Kill the child and wipe the scratch dir before re-raising so
+    // failed-to-start sessions don't leak.
+    try { child.kill('SIGTERM') } catch { /* best-effort */ }
+    cleanScratchDir(scratchDir)
+    throw err
+  })
+
+  return { loginUrl, scratchDir, child }
+}
+
+/**
+ * Paste the operator's browser code into the live `claude setup-token`
+ * child's stdin and wait for the success-written credentials.json.
+ *
+ * Returns the `AddAccountCredentials` shape the broker's add-account
+ * verb expects — same `claudeAiOauth: { accessToken, refreshToken,
+ * expiresAt, scopes, subscriptionType, rateLimitTier }` envelope.
+ *
+ * On success: the caller is responsible for invoking
+ * `cleanScratchDir(scratchDir)` after `addAccount` returns; we
+ * deliberately don't wipe here because the broker call might race the
+ * filesystem cleanup. On failure (invalid code, expired code, timeout)
+ * the helper throws and cleans the scratch dir itself.
+ *
+ * Poll interval default: 250ms — same as `submitAuthCode`'s 500ms
+ * halved because there's no tmux capture-pane overhead per tick.
+ * Timeout default: 120s, matching the env var in `submitAuthCode`.
+ */
+export async function submitAccountAuthCode(
+  flow: PendingAuthAddFlow,
+  code: string,
+  opts: { pollIntervalMs?: number; pollTimeoutMs?: number } = {},
+): Promise<AddAccountCredentials> {
+  const pollIntervalMs = opts.pollIntervalMs ?? 250
+  const pollTimeoutMs = opts.pollTimeoutMs ?? 120_000
+
+  const credentialsPath = join(flow.scratchDir, '.credentials.json')
+
+  // Write the code + newline to stdin. claude setup-token's prompt
+  // expects line-buffered input — see the manual-paste paste at the
+  // bottom of `submitAuthCode`. We use a single write here (vs the
+  // two send-keys calls of the tmux path) because there's no
+  // terminfo-flake concern over a pipe.
+  if (!flow.child.stdin || flow.child.stdin.destroyed) {
+    cleanScratchDir(flow.scratchDir)
+    throw new Error('claude setup-token process stdin is not writable (child may have exited)')
+  }
+  flow.child.stdin.write(code.trim() + '\n')
+
+  // Poll for the credentials file. Same two-channel design as
+  // submitAuthCode but tmux-pane-scrape and log-scrape are out (the
+  // pane scrape was a fallback for older claude CLI versions; the
+  // chat flow targets the current CLI by definition).
+  const deadline = Date.now() + pollTimeoutMs
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, pollIntervalMs))
+    if (existsSync(credentialsPath)) {
+      const token = readTokenFromCredentialsFile(credentialsPath)
+      if (token) {
+        // Parse the full credentials envelope to forward to the
+        // broker. readTokenFromCredentialsFile already validated the
+        // accessToken regex, so the JSON is well-formed.
+        try {
+          const raw = readFileSync(credentialsPath, 'utf-8')
+          const parsed = JSON.parse(raw) as { claudeAiOauth?: AnthropicAddAccountCredentials['claudeAiOauth'] }
+          if (parsed.claudeAiOauth?.accessToken) {
+            // Drain the child so it exits cleanly after success.
+            try { flow.child.stdin?.end() } catch { /* best-effort */ }
+            return { claudeAiOauth: parsed.claudeAiOauth }
+          }
+        } catch {
+          // fall through — file may be mid-write; next tick retries.
+        }
+      }
+    }
+    // Detect child early exit (invalid code → claude prints + exits).
+    if (flow.child.exitCode != null) {
+      cleanScratchDir(flow.scratchDir)
+      throw new Error(
+        `claude setup-token exited (code ${flow.child.exitCode}) — code may have been invalid or expired`,
+      )
+    }
+  }
+
+  // Timeout — kill the child + wipe scratch.
+  try { flow.child.kill('SIGTERM') } catch { /* best-effort */ }
+  cleanScratchDir(flow.scratchDir)
+  throw new Error(`No credentials file appeared at ${credentialsPath} within ${Math.round(pollTimeoutMs / 1000)}s`)
+}
+
+/**
+ * Cancel an in-flight `/auth add` flow: kill the `claude setup-token`
+ * child, wipe the scratch dir, and let the caller delete the
+ * `pendingAuthAddFlows` entry. Idempotent — safe to call when the
+ * child has already exited.
+ */
+export function cancelAccountAuthSession(flow: PendingAuthAddFlow): void {
+  try {
+    if (flow.child.exitCode == null) flow.child.kill('SIGTERM')
+  } catch {
+    // best-effort
+  }
+  cleanScratchDir(flow.scratchDir)
+}

package/telegram-plugin/gateway/auth-broker-client.ts

@@ -0,0 +1,75 @@
+/**
+ * Thin adapter between the gateway and `src/auth/broker/client.ts`.
+ *
+ * The broker client is a stateful class (holds a persistent UDS
+ * connection). The gateway constructs one per `/auth` command —
+ * cheap, and avoids dangling sockets on idle. The handler needs the
+ * five methods on the `AuthBrokerClient` interface in
+ * `./auth-command.ts` (listState / setActive / rmAccount /
+ * refreshAccount / setOverride); we narrow `BrokerClient` down to
+ * that surface so a test mock only has to stub those five.
+ */
+
+import { AuthBrokerClient as BrokerClient, type AddAccountCredentials } from '../../src/auth/broker/client.js'
+import type { AuthBrokerClient } from './auth-command.js'
+
+/**
+ * Construct an {@link AuthBrokerClient} for one `/auth` command. The
+ * caller is responsible for closing the underlying socket when done
+ * (do `await client.close()` after the reply lands).
+ */
+export function createAuthBrokerClient(): {
+  client: AuthBrokerClient
+  close: () => Promise<void>
+} {
+  const broker = new BrokerClient()
+  const client: AuthBrokerClient = {
+    listState: () => broker.listState(),
+    setActive: (label: string) => broker.setActive(label),
+    rmAccount: (label: string) => broker.rmAccount(label),
+    refreshAccount: (label: string) => broker.refreshAccount(label),
+    setOverride: (agent: string, account: string | null) =>
+      broker.setOverride(agent, account),
+  }
+  return { client, close: () => broker.close() }
+}
+
+/**
+ * Legacy `getAuthBrokerClient` entry — kept so the gateway's existing
+ * call site doesn't need rewiring. Returns the client object only;
+ * the underlying socket leaks unless the caller imports
+ * `createAuthBrokerClient` directly. Acceptable because:
+ *   - The gateway is long-lived (one process per agent).
+ *   - The broker tolerates many connections per peer.
+ *   - `/auth` is a low-frequency human-driven verb.
+ *
+ * If allocations become a concern, swap callers over to the structured
+ * variant above.
+ */
+export async function getAuthBrokerClient(
+  _agentName: string,
+): Promise<AuthBrokerClient | null> {
+  const { client } = createAuthBrokerClient()
+  return client
+}
+
+/**
+ * Add an account via the broker. Used exclusively by the `/auth add`
+ * chat flow — the narrow {@link AuthBrokerClient} surface in
+ * `auth-command.ts` deliberately omits `addAccount` because the verb
+ * is gateway-routed (not handler-routed). Constructs and closes a
+ * one-shot {@link BrokerClient} so the gateway doesn't need a
+ * long-lived handle just for this verb.
+ */
+export async function addAccountViaBroker(
+  label: string,
+  credentials: AddAccountCredentials,
+  opts: { replace?: boolean } = {},
+): Promise<{ label: string; expiresAt?: number }> {
+  const broker = new BrokerClient()
+  try {
+    return await broker.addAccount(label, credentials, opts.replace)
+  } finally {
+    await broker.close()
+  }
+}