@atlaso-labs/opencode 0.1.0 → 0.2.0

package/lib/capture_stats.ts

@@ -0,0 +1,318 @@
+/** Content-free capture-attempt counters — the TS port of the Python client's
+ *  capture_stats (atlaso_client/cache.py), one estimator across all hook tools
+ *  (lab ruling 85a5c41b: semantic parity required, reason labels MAP onto the
+ *  closed Python vocabulary — the server whitelist never grows).
+ *
+ *  Semantics (byte-identical to Python, non-negotiable):
+ *    attempts  = gate-passed evaluations (reasons `signal` | `substantive`)
+ *    accepted  = server-confirmed "added" ONLY (a "duplicate" result goes to
+ *                drops.duplicate — replaying one memory must read ~0%, not 100%)
+ *    per-UTC-day cumulative ints + hours_active/max_hour_attempts (hour spread)
+ *    accepted <= attempts clamped AT EMIT (a corrupt snapshot fails the tile
+ *                closed server-side — a well-behaved client never trips it)
+ *    payload   = last <=35 days, additive `capture_stats` field on the batch body
+ *
+ *  Counts only — no content and no content-derived hashes ever enter this file
+ *  or the payload (enforced by the vocabulary-whitelist test).
+ *
+ *  Cursor-specific hazard handled here: stop + sessionEnd can BOTH fire for one
+ *  turn (two processes). Gate evaluations dedupe on the turn's idempotency key,
+ *  and a "duplicate" result for a key we already counted is our own double-fire
+ *  echo, not a real replay — it is skipped.
+ *
+ *  Cross-process safety: read-modify-write under the shared flock helper; when
+ *  the lock is unavailable (held:false — e.g. Windows) we still write, and the
+ *  server's max-merge means a lost race can only UNDER-count, never inflate.
+ */
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { atlasoDir } from "./atlaso";
+import { withToolLock } from "./lock";
+
+// ── the closed vocabulary (lab ruling 85a5c41b) ─────────────────────────────
+// Every gate reason a TS connector can produce MUST map to exactly one of the
+// Python labels below. An unmappable reason is a build bug, never a reason to
+// extend the vocabulary (map-completeness test enforces totality).
+export const ATTEMPT_REASONS = ["signal", "substantive"] as const;
+export const REASON_MAP: Record<string, string> = {
+  empty: "empty",
+  chatter: "chatter",
+  too_short: "too_short",
+  too_long: "too_long",
+  system_turn: "system_turn",
+  // Cursor's meta_recall = "the user turn is our own injected recall block" —
+  // semantically a system-authored turn, so it maps there.
+  meta_recall: "system_turn",
+};
+
+const MAX_DAYS = 35;
+// Cursor fires stop AND sessionEnd for one turn seconds apart (two processes).
+// A same-key event inside this window is that echo and must not double-count;
+// beyond it, a repeated key is a REAL replay and counts — exactly like the
+// Python client, which has no double-fire and counts every replay.
+export const DOUBLE_FIRE_WINDOW_S = 120;
+
+type DayRow = {
+  attempts: number;
+  accepted: number;
+  drops: Record<string, number>;
+  hours: Record<string, number>; // "00".."23" → attempts that hour
+};
+// Result stamps carry the counted VERDICT and the day it landed on, so a
+// same-key echo can be reconciled order-independently (CodeRedTeam: the
+// server may answer the losing hook's "duplicate" BEFORE the winning hook's
+// "added" — the turn was captured, and the counters must say so whichever
+// response is processed first).
+type ResultStamp = { t: number; s: "added" | "duplicate"; d: string };
+type Store = {
+  version: 1;
+  days: Record<string, DayRow>;
+  // content-free turn-key hashes → unix seconds of the last COUNTED event
+  gate_seen: Record<string, number>;
+  result_seen: Record<string, ResultStamp>;
+  last_sent_hash: string | null;
+};
+
+export type CaptureStatsDay = {
+  day: string;
+  attempts: number;
+  accepted: number;
+  hours_active: number;
+  max_hour_attempts: number;
+  drops: Record<string, number>;
+};
+
+function statsPath(): string {
+  return join(atlasoDir(), "capture_stats.json");
+}
+function lockPath(): string {
+  return join(atlasoDir(), "capture_stats.lock");
+}
+
+export function utcDay(d = new Date()): string {
+  return d.toISOString().slice(0, 10);
+}
+function utcHour(d = new Date()): string {
+  return d.toISOString().slice(11, 13);
+}
+
+function emptyStore(): Store {
+  return { version: 1, days: {}, gate_seen: {}, result_seen: {}, last_sent_hash: null };
+}
+
+function load(): Store {
+  try {
+    const raw = JSON.parse(readFileSync(statsPath(), "utf8"));
+    if (raw && raw.version === 1 && typeof raw.days === "object") {
+      raw.gate_seen = raw.gate_seen ?? {};
+      // Tolerate pre-reconciliation stamps (bare unix seconds): keep the
+      // timestamp, assume the safe verdict ("added" never triggers an
+      // upgrade), and let the window expire them naturally.
+      const rs: Record<string, ResultStamp> = {};
+      for (const [k, v] of Object.entries(raw.result_seen ?? {})) {
+        if (typeof v === "number") rs[k] = { t: v, s: "added", d: "" };
+        else if (v && typeof (v as ResultStamp).t === "number") rs[k] = v as ResultStamp;
+      }
+      raw.result_seen = rs;
+      return raw as Store;
+    }
+  } catch {
+    /* missing / malformed → fresh */
+  }
+  return emptyStore();
+}
+
+function save(s: Store): void {
+  // prune to the newest MAX_DAYS so the file never grows unbounded
+  const days = Object.keys(s.days).sort();
+  for (const d of days.slice(0, Math.max(0, days.length - MAX_DAYS))) delete s.days[d];
+  // prune stale dedupe stamps relative to the NEWEST stamp (a logical clock —
+  // wall-clock pruning would wrongly drop stamps after a clock jump, and breaks
+  // deterministic tests that inject historical times)
+  {
+    const stamps = Object.values(s.gate_seen);
+    if (stamps.length) {
+      const cutoff = Math.max(...stamps) - 2 * DOUBLE_FIRE_WINDOW_S;
+      for (const k of Object.keys(s.gate_seen)) if (s.gate_seen[k] < cutoff) delete s.gate_seen[k];
+    }
+  }
+  {
+    const stamps = Object.values(s.result_seen).map((v) => v.t);
+    if (stamps.length) {
+      const cutoff = Math.max(...stamps) - 2 * DOUBLE_FIRE_WINDOW_S;
+      for (const k of Object.keys(s.result_seen)) {
+        if (s.result_seen[k].t < cutoff) delete s.result_seen[k];
+      }
+    }
+  }
+  const target = statsPath();
+  const dir = dirname(target);
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.capture_stats.${process.pid}.${randomUUID()}.tmp`);
+  const fd = openSync(tmp, "wx", 0o600);
+  try {
+    writeFileSync(fd, JSON.stringify(s));
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, target);
+}
+
+function day(s: Store, key: string): DayRow {
+  let row = s.days[key];
+  if (!row) {
+    row = { attempts: 0, accepted: 0, drops: {}, hours: {} };
+    s.days[key] = row;
+  }
+  return row;
+}
+
+async function mutate(fn: (s: Store) => void): Promise<void> {
+  try {
+    await withToolLock(lockPath(), async () => {
+      const s = load();
+      fn(s);
+      save(s);
+    });
+  } catch {
+    /* counters are best-effort — never break capture */
+  }
+}
+
+/** Record one gate evaluation. `turnKey` (the deposit idempotency key) dedupes
+ *  the stop+sessionEnd double-fire: the same key inside DOUBLE_FIRE_WINDOW_S is
+ *  an echo and is skipped; beyond the window it counts (real-replay parity with
+ *  the Python client). */
+export async function recordGate(
+  reason: string,
+  opts: { turnKey?: string | null; now?: Date } = {},
+): Promise<void> {
+  const now = opts.now ?? new Date();
+  const nowS = Math.floor(now.getTime() / 1000);
+  const dk = utcDay(now);
+  await mutate((s) => {
+    if (opts.turnKey) {
+      const last = s.gate_seen[opts.turnKey];
+      if (last !== undefined && nowS - last < DOUBLE_FIRE_WINDOW_S) return; // echo
+      s.gate_seen[opts.turnKey] = nowS;
+    }
+    const row = day(s, dk);
+    if ((ATTEMPT_REASONS as readonly string[]).includes(reason)) {
+      row.attempts += 1;
+      const h = utcHour(now);
+      row.hours[h] = (row.hours[h] ?? 0) + 1;
+    } else {
+      const mapped = REASON_MAP[reason];
+      if (!mapped) return; // unmappable = build bug; never invent a label
+      row.drops[mapped] = (row.drops[mapped] ?? 0) + 1;
+    }
+  });
+}
+
+/** Count the server's per-item verdicts: "added" → accepted; "duplicate" → the
+ *  duplicate bucket — UNLESS the item's key is one we already counted (that is
+ *  our own double-fire echo, not a real replay).
+ *
+ *  Order-independent reconciliation (CodeRedTeam gate): when stop+sessionEnd
+ *  race, the server hands one hook "added" and the other "duplicate", and the
+ *  LOCAL processing order of those two responses is arbitrary. Whichever lands
+ *  first, one captured turn must read accepted=1, duplicate=0 — so a same-key
+ *  "added" inside the window UPGRADES an earlier "duplicate" (the pair's truth
+ *  is "captured"), and everything else is a skip. Only counted verdicts stamp
+ *  the window: an "error"/"invalid" result must never suppress the retry's
+ *  real verdict. */
+export async function recordDepositResults(
+  results: Array<{ client_id?: string; status?: string }>,
+  opts: { now?: Date } = {},
+): Promise<void> {
+  if (!Array.isArray(results) || results.length === 0) return;
+  const now = opts.now ?? new Date();
+  const nowS = Math.floor(now.getTime() / 1000);
+  const dk = utcDay(now);
+  await mutate((s) => {
+    for (const r of results) {
+      const status =
+        r?.status === "added" ? "added" : r?.status === "duplicate" ? "duplicate" : null;
+      if (!status) continue; // uncounted verdicts never stamp the echo window
+      const key = r?.client_id;
+      if (key) {
+        const prev = s.result_seen[key];
+        if (prev && nowS - prev.t < DOUBLE_FIRE_WINDOW_S) {
+          if (prev.s === "duplicate" && status === "added") {
+            // adverse order: the echo's duplicate landed first — undo it and
+            // credit the accept on the same day it was counted.
+            const row0 = s.days[prev.d];
+            if (row0 && (row0.drops["duplicate"] ?? 0) > 0) {
+              row0.drops["duplicate"] -= 1;
+              if (row0.drops["duplicate"] === 0) delete row0.drops["duplicate"];
+              row0.accepted += 1;
+            } else {
+              day(s, dk).accepted += 1;
+            }
+            s.result_seen[key] = { t: prev.t, s: "added", d: prev.d };
+          }
+          continue; // echo — never double-counts
+        }
+        s.result_seen[key] = { t: nowS, s: status, d: dk };
+      }
+      const row = day(s, dk);
+      if (status === "added") {
+        row.accepted += 1;
+      } else {
+        row.drops["duplicate"] = (row.drops["duplicate"] ?? 0) + 1;
+      }
+    }
+  });
+}
+
+/** The additive batch-body payload: last <=35 UTC days, cumulative, clamped. */
+export function buildCaptureStats(store?: Store): CaptureStatsDay[] {
+  const s = store ?? load();
+  return Object.keys(s.days)
+    .sort()
+    .slice(-MAX_DAYS)
+    .map((dk) => {
+      const row = s.days[dk];
+      const hours = Object.values(row.hours ?? {});
+      return {
+        day: dk,
+        attempts: row.attempts,
+        accepted: Math.min(row.accepted, row.attempts), // emit invariant
+        hours_active: Math.min(24, hours.filter((n) => n > 0).length),
+        max_hour_attempts: hours.length ? Math.max(...hours) : 0,
+        drops: { ...row.drops },
+      };
+    })
+    .filter((d) => d.attempts > 0 || d.accepted > 0 || Object.keys(d.drops).length > 0);
+}
+
+function payloadHash(days: CaptureStatsDay[]): string {
+  // hash of COUNTS ONLY — content never enters this module
+  return createHash("sha256").update(JSON.stringify(days)).digest("hex");
+}
+
+/** Returns the payload when the counters changed since the last confirmed send,
+ *  else null (skip attaching). Call markStatsSent() after a successful push. */
+export function pendingCaptureStats(): CaptureStatsDay[] | null {
+  const s = load();
+  const days = buildCaptureStats(s);
+  if (days.length === 0) return null;
+  return payloadHash(days) === s.last_sent_hash ? null : days;
+}
+
+export async function markStatsSent(days: CaptureStatsDay[]): Promise<void> {
+  const h = payloadHash(days);
+  await mutate((s) => {
+    s.last_sent_hash = h;
+  });
+}

package/lib/connect.ts

@@ -24,7 +24,7 @@ import { spawn } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import {
   appendFileSync, chmodSync, closeSync, fsyncSync, mkdirSync, openSync,
-  renameSync, statSync, unlinkSync, writeFileSync, writeSync,
+  renameSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync,
 } from "node:fs";
 import { createServer, type Server } from "node:http";
 import { hostname } from "node:os";
@@ -37,6 +37,7 @@ const LOCK_NAME = ".connecting";
 const LOCK_TTL_MS = 15 * 60 * 1000;
 const START_TIMEOUT_MS = 15000;
 const POLL_TIMEOUT_MS = 15000;
+const LOCK_HEARTBEAT_MS = 60 * 1000;
 
 export function hasToken(): boolean {
   return !!loadAuth()?.token;
@@ -50,11 +51,14 @@ function lockPath(): string {
  *  unpredictable temp name (O_EXCL, no symlink follow), fsync the file, atomic
  *  rename, then fsync the directory. Mirrors the Python `connect.save_auth`. */
 export function writeAuth(
-  server: string,
-  token: string,
-  user_id: string,
-  device_id: string | null,
+  opts: {
+    server: string;
+    token: string;
+    user_id: string;
+    device_id: string | null;
+  },
 ): string {
+  const { server, token, user_id, device_id } = opts;
   const dir = atlasoDir();
   mkdirSync(dir, { recursive: true });
   try {
@@ -95,7 +99,11 @@ function openBrowser(url: string): void {
     const plt = process.platform;
     const cmd = plt === "darwin" ? "open" : plt === "win32" ? "cmd" : "xdg-open";
     const args = plt === "win32" ? ["/c", "start", "", url] : [url];
-    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    // spawn failures arrive asynchronously on EventEmitter.error, outside the
+    // surrounding try/catch. Swallow them: the URL is also written to connect.log.
+    child.once("error", () => {});
+    child.unref();
   } catch {
     /* best-effort */
   }
@@ -158,6 +166,18 @@ function waitForCode(server: Server, expectedState: string, timeoutMs: number):
 /** Run the connect handshake to completion. 0 on success. Releases the lock. */
 export async function runConnect(): Promise<number> {
   let server: Server | null = null;
+  // Authorization can outlive the stale-lock TTL advertised by the server. Refresh
+  // the lock while this process is alive so another sessionStart cannot reclaim it
+  // and launch a second browser flow.
+  const heartbeat = setInterval(() => {
+    try {
+      const now = new Date();
+      utimesSync(lockPath(), now, now);
+    } catch {
+      /* manual connect or unwritable lock — best-effort */
+    }
+  }, LOCK_HEARTBEAT_MS);
+  heartbeat.unref();
   try {
     const base = (process.env.ATLASO_SERVER || loadAuth()?.server || defaultServer()).replace(/\/+$/, "");
     const label = (hostname() || "this device").slice(0, 80);
@@ -226,11 +246,17 @@ export async function runConnect(): Promise<number> {
     }
     if (t?.status === "approved") {
       if (!t.token || !t.user_id) return 1;
-      writeAuth(base, t.token, t.user_id, t.device_id ?? null);
+      writeAuth({
+        server: base,
+        token: t.token,
+        user_id: t.user_id,
+        device_id: t.device_id ?? null,
+      });
       return 0;
     }
     return 1;
   } finally {
+    clearInterval(heartbeat);
     try {
       server?.close();
     } catch {
@@ -292,13 +318,19 @@ export function maybeAutoconnect(tool = "opencode"): boolean {
   const lock = lockPath();
   if (!acquireLock(lock)) return false;
   try {
-    // lib/ → ../src/connect-entry.ts (the detached browser-authorize process)
-    const entry = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "connect-entry.ts");
-    spawn("bun", ["run", entry], {
+    const entry = join(dirname(fileURLToPath(import.meta.url)), "..", "hooks", "connect.ts");
+    // Reuse the exact Bun executable running this hook. This avoids PATH drift in
+    // GUI launches; the override exists for deterministic failure-path tests.
+    const bun = process.env.ATLASO_BUN_PATH || process.execPath || "bun";
+    const child = spawn(bun, ["run", entry], {
       stdio: "ignore",
       detached: true,
       env: { ...process.env, ATLASO_TOOL: tool },
-    }).unref();
+    });
+    // ENOENT and similar failures are emitted asynchronously, not thrown. Release
+    // our filesystem lock so the next session can retry immediately.
+    child.once("error", () => releaseConnectLock());
+    child.unref();
     return true;
   } catch {
     try {

package/lib/credential.ts

@@ -0,0 +1,148 @@
+/** Per-tool credential resolution — the TS port of the Python client's
+ *  `_credential.py` resolve()/exchange() state machine.
+ *
+ *  Every Atlaso integration on a machine shares ONE bearer (~/.atlaso/auth.json), so
+ *  the brain can't tell two tools on a device apart — "remove tool X" can't actually
+ *  stop X. The fix: each tool trades the shared bearer for its OWN credential at
+ *  ~/.atlaso/tools/<tool>.json, minted via POST /v1/device/exchange, under a kernel
+ *  lock only that tool participates in. The brain then keys off the tool's own token.
+ *
+ *  Two invariants are load-bearing (break either and the feature is a lie):
+ *   1. NEVER BRICK. Only a VERIFIED verdict from our own server (x-atlaso-response: 1)
+ *      may take a tool offline. A failed exchange / edge 403 / 5xx / lock-miss is NOT
+ *      a verdict — keep the shared bearer and retry next run. (On a normal device the
+ *      shared bearer still works on the data plane; this is the WAF-brick lesson.)
+ *   2. TOMBSTONE. A verified `tool_revoked` means the user removed this tool — go
+ *      local-only and do NOT fall back to the shared bearer, or we'd resurrect it.
+ *      Only an EXPLICIT reconnect (the browser flow) lifts it, never this automatic path.
+ */
+import {
+  clearToolAuth, defaultServer, loadAuth, loadToolAuth, saveToolAuth,
+  toolLockPath, toolsDir, type Auth,
+} from "./atlaso";
+import { withToolLock } from "./lock";
+import { mkdirSync } from "node:fs";
+import * as state from "./state";
+
+const EXCHANGE_TIMEOUT_MS = 8000;
+
+/** A credential can't be attributed unless server + user + device all match the
+ *  shared bearer — a reconnect into a different account must not reuse a stale
+ *  tool file. A null device id is a valid legacy identity when BOTH files agree. */
+function sameIdentity(a: Auth, b: Auth): boolean {
+  return (
+    !!a.server && !!a.user_id &&
+    a.server === b.server &&
+    a.user_id === b.user_id &&
+    (a.device_id ?? null) === (b.device_id ?? null)
+  );
+}
+
+type ExchangeResult =
+  | { kind: "minted"; token: string }
+  | { kind: "revoked" } // verified 403 tool_revoked — the user removed this tool
+  | { kind: "not_entitled" } // verified 409 — free plan, another tool owns the slot
+  | { kind: "unverified" }; // network / edge / 5xx / 200-without-token — not a verdict
+
+/** Trade the shared bearer for this tool's own token. Only a 200-with-token mints;
+ *  every unverified outcome returns `unverified` so the caller keeps the shared
+ *  bearer. Verified 403 tool_revoked / 409 are the only offline-taking verdicts. */
+async function exchange(shared: Auth, tool: string): Promise<ExchangeResult> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), EXCHANGE_TIMEOUT_MS);
+  try {
+    const res = await fetch(shared.server.replace(/\/+$/, "") + "/v1/device/exchange", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${shared.token}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ tool }),
+      signal: ctrl.signal,
+    });
+    const verified = res.headers?.get("x-atlaso-response") === "1";
+    if (res.ok) {
+      const data = (await res.json().catch(() => null)) as { token?: unknown } | null;
+      if (data && typeof data.token === "string" && data.token) return { kind: "minted", token: data.token };
+      return { kind: "unverified" }; // 200 but no token → treat as transient, keep shared
+    }
+    if (verified) {
+      const err = res.headers?.get("x-atlaso-error") || "";
+      if (res.status === 403 && err === "tool_revoked") return { kind: "revoked" };
+      if (res.status === 409) return { kind: "not_entitled" };
+      // A verified 401 means the SHARED bearer itself is dead — not this tool. Fall
+      // back so the subsequent data-plane call retires the shared bearer (its job).
+    }
+    return { kind: "unverified" };
+  } catch {
+    return { kind: "unverified" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Resolve the credential to make cloud calls with for `tool`.
+ *   - own credential present + same identity → use it (fast path, no network).
+ *   - else mint one under the kernel lock (POST /v1/device/exchange).
+ *   - unverified failure / no lock → the SHARED bearer (never-brick).
+ *   - verified tombstone / not-entitled → null (go local-only, do NOT fall back).
+ * Returns null only when the tool must stay offline this run (or we're not connected).
+ */
+export async function resolveCredential(tool: string): Promise<Auth | null> {
+  const shared = loadAuth();
+  if (!tool) return shared ? { ...shared, source: "shared" } : null;
+  // Not connected at all → nothing to mint from.
+  if (!shared || !shared.token || !shared.server) return null;
+
+  // Fast path: our own credential, provably ours → use it, no round-trip.
+  const own = loadToolAuth(tool);
+  if (own && sameIdentity(own, shared)) return { ...own, source: "own", tool };
+
+  // Mint under the lock. Ensure the dir exists so the lock file can be created.
+  try {
+    mkdirSync(toolsDir(), { recursive: true });
+  } catch {
+    /* if we can't make the dir, withToolLock will fail to lock → shared bearer */
+  }
+
+  return await withToolLock(toolLockPath(tool), async (held) => {
+    if (!held) {
+      // No kernel lock (Windows, or contended past the deadline) → don't mint
+      // unlocked; ride the shared bearer this run and retry next time.
+      return { ...shared, source: "shared" } as Auth;
+    }
+    // Re-check under the lock — a peer may have minted while we waited.
+    const fresh = loadToolAuth(tool);
+    if (fresh && sameIdentity(fresh, shared)) return { ...fresh, source: "own", tool } as Auth;
+    if (fresh && !sameIdentity(fresh, shared)) clearToolAuth(tool); // foreign leftover
+
+    const r = await exchange(shared, tool);
+    if (r.kind === "minted") {
+      const cred = {
+        server: shared.server, token: r.token,
+        user_id: shared.user_id, device_id: shared.device_id, tool, version: 1,
+      };
+      try {
+        saveToolAuth(tool, cred);
+      } catch {
+        /* couldn't persist — still usable this run */
+      }
+      // A fresh mint must not inherit the previous (dead) credential's suppression.
+      state.invalidate();
+      return { ...cred, source: "own" } as Auth;
+    }
+    if (r.kind === "revoked") {
+      clearToolAuth(tool);
+      // Tombstone: stay down; falling back to the shared bearer would resurrect a
+      // tool the user just removed. Only an explicit reconnect lifts this.
+      state.setLocalOnly(state.REVOKED, { tool, device_id: shared.device_id ?? null });
+      return null;
+    }
+    if (r.kind === "not_entitled") {
+      // Free plan, a different tool owns the single slot → local-only. Don't fall
+      // back to the shared bearer (that would let this tool masquerade as entitled).
+      state.setLocalOnly(state.NOT_ENTITLED, { tool, device_id: shared.device_id ?? null });
+      return null;
+    }
+    // Unverified → never-brick: keep the shared bearer, retry next run.
+    return { ...shared, source: "shared" } as Auth;
+  });
+}