fix(atlas): keep sessions through transient 403s, fix wallet gate edge cases, warn on stranded legacy config (#67)

- syncServices: only a 401 clears the session now. 403s also come from
  WAFs and rate limiters; treating them as revocation silently signed
  users out mid-session, which presented as the Atlas connection
  randomly dropping.
- wallet gate: getBalance returns null (not -1) when the balance can't
  be determined, so an overdraft of exactly -$1 no longer reads as
  'unavailable'; the gate blocks on any verified balance <= 0 instead of
  exactly 0 (negative wallets used to sail through); blocking drops the
  30s balance cache so a top-up is visible on the next attempt. The wire
  format still encodes unknown as -1.
- global: when both the legacy synsc dir and the new config dir exist,
  say the legacy one is ignored instead of silently stranding the auth
  and config inside it.

Author: aayambansal

backend/cli/src/global/index.ts

@@ -22,6 +22,12 @@ function migrateDir(base: string): string {
       return old
     }
   }
+  // Both dirs existing means the legacy one was restored (backup, dotfiles)
+  // after the new dir was created. It will never be read or migrated — say
+  // so instead of silently stranding whatever auth/config lives in it.
+  if (existsSync(next) && existsSync(old)) {
+    console.error(`openscience: ignoring legacy config at ${old} (${next} already exists) — merge or remove it`)
+  }
   return next
 }
 

backend/cli/src/openscience/index.ts

@@ -607,11 +607,19 @@ export namespace OpenScience {
       })
 
       if (!res.ok) {
-        if (res.status === 401 || res.status === 403) {
+        if (res.status === 401) {
           log.info("session invalid, clearing")
           await clearSession()
           return null
         }
+        if (res.status === 403) {
+          // 403s also come from WAFs and rate limiters, not just key
+          // revocation. Destroying the session on one silently signed the
+          // user out; keep it and let the next sync retry. A genuinely
+          // revoked key comes back as 401.
+          log.warn("sync got 403, keeping session")
+          return null
+        }
         if (res.status === 402) {
           // No active Atlas subscription. Don't clear the session
           // (the auth itself is fine) — surface the message so the
@@ -964,27 +972,40 @@ export namespace OpenScience {
   let cachedBalance: { value: number; at: number } | null = null
   const BALANCE_CACHE_TTL = 30 * 1000
 
+  /** Drop the cached balance so the next getBalance() refetches. Called when
+   *  the wallet gate blocks, so a top-up is visible on the next attempt
+   *  instead of after the cache TTL. */
+  export function invalidateBalance() {
+    cachedBalance = null
+  }
+
   /** Get current credit balance (cached for 30s).
-   *  Returns the balance in USD, or -1 on API failure (fail-closed). */
-  export async function getBalance(): Promise<number> {
+   *  Returns the balance in USD, or null when it can't be determined (no
+   *  session, API failure). null is distinct from a real negative balance —
+   *  the old -1 sentinel collided with an overdraft of exactly -$1. */
+  export async function getBalance(): Promise<number | null> {
     if (cachedBalance && Date.now() - cachedBalance.at < BALANCE_CACHE_TTL) {
       return cachedBalance.value
     }
     const session = await getSession()
-    if (!session) return -1
+    if (!session) return null
     try {
       const res = await fetch(`${API_BASE}/api/cli/balance`, {
         headers: { Authorization: `Bearer ${session.api_key}` },
       })
-      if (!res.ok) return -1
+      if (!res.ok) return null
       const data = await res.json()
-      const usd = typeof data.balance_usd === "number"
-        ? data.balance_usd
-        : (typeof data.balance_cents === "number" ? data.balance_cents / 100 : -1)
+      const usd =
+        typeof data.balance_usd === "number"
+          ? data.balance_usd
+          : typeof data.balance_cents === "number"
+            ? data.balance_cents / 100
+            : null
+      if (usd === null) return null
       cachedBalance = { value: usd, at: Date.now() }
       return usd
     } catch {
-      return -1
+      return null
     }
   }
 

backend/cli/src/server/routes/account.ts

@@ -63,7 +63,8 @@ export const AccountRoutes = lazy(() =>
       async (c) => {
         const session = await OpenScience.getSession()
         const sync = session ? await OpenScience.syncServices() : null
-        const balance = session ? await OpenScience.getBalance() : -1
+        // -1 is the wire encoding for "unknown" (schema: number)
+        const balance = (session ? await OpenScience.getBalance() : null) ?? -1
         const billing = session ? await OpenScience.getBillingMode() : null
         return c.json({
           session: !!session,
@@ -85,7 +86,7 @@ export const AccountRoutes = lazy(() =>
           },
         },
       }),
-      async (c) => c.json({ balance_usd: await OpenScience.getBalance() }),
+      async (c) => c.json({ balance_usd: (await OpenScience.getBalance()) ?? -1 }),
     )
     .get(
       "/devices",

backend/cli/src/server/routes/settings/billing.ts

@@ -30,7 +30,7 @@ const BillingPatch = z.object({
 async function readState(): Promise<BillingState> {
   const cfg = await Config.getGlobal()
   const session = await OpenScience.getSession().catch(() => null)
-  const balanceUsd = session ? await OpenScience.getBalance().catch(() => -1) : -1
+  const balanceUsd = (session ? await OpenScience.getBalance().catch(() => null) : null) ?? -1
   return {
     llm: cfg.billing?.llm ?? null,
     compute: cfg.billing?.compute ?? "byok",

backend/cli/src/session/processor.ts

@@ -70,13 +70,16 @@ export namespace SessionProcessor {
             }
 
             // Pre-flight wallet check for managed-proxy calls only. Block ONLY on a
-            // VERIFIED empty wallet (balance === 0). If the balance can't be verified
-            // (-1: no/expired Atlas session or a transient error), do NOT hard-block —
+            // VERIFIED empty or overdrafted wallet. If the balance can't be verified
+            // (null: no/expired Atlas session or a transient error), do NOT hard-block —
             // the managed proxy is the billing authority and returns 402 if actually
             // out of credits. Hard-blocking here strands a user whose session lapsed.
             if (requiresWalletBalance(credentialSource)) {
               const balance = await OpenScience.getBalance()
-              if (balance === 0) {
+              if (balance !== null && balance <= 0) {
+                // Drop the 30s cache so a top-up is visible on the next
+                // attempt instead of blocking until the TTL expires.
+                OpenScience.invalidateBalance()
                 throw new Error(
                   "Your Atlas wallet is empty. Top up at app.syntheticsciences.ai/cli, or switch LLM spend to BYOK in Settings → Spend — BYOK uses your own key and is never billed.",
                 )