@bivy/bivy 0.8.2 → 0.8.3-staging.117

package/bin/bivy.mjs

@@ -388,11 +388,11 @@ function hasModelConfig(config) {
 
 const SETUP_AGENT_CHOICES = [
   { key: "p", label: "Pi (default, sign in to ChatGPT/Claude/Copilot or paste a model key)", runtimeId: "pi", needsBivyModel: true },
-  { key: "c", label: "Claude Code", runtimeId: "claude-code-sdk", needsBivyModel: false, loginHint: "If Claude asks you to sign in, run: claude" },
-  { key: "x", label: "Codex", runtimeId: "codex", needsBivyModel: false, loginHint: "If Codex asks you to sign in, run: codex" },
-  { key: "o", label: "OpenCode", runtimeId: "opencode", needsBivyModel: false },
-  { key: "g", label: "Gemini CLI", runtimeId: "gemini", needsBivyModel: false, loginHint: "If Gemini asks you to sign in, run: gemini" },
-  { key: "q", label: "Qwen Code", runtimeId: "qwen", needsBivyModel: false, loginHint: "If Qwen asks you to sign in, run: qwen" },
+  { key: "c", label: "Claude Code", runtimeId: "claude-code-sdk", command: "claude", authProbe: ["auth", "status"], needsBivyModel: false, loginHint: "Sign in through Claude Code" },
+  { key: "x", label: "Codex", runtimeId: "codex", command: "codex", authProbe: ["login", "status"], needsBivyModel: false, loginHint: "Sign in through Codex" },
+  { key: "o", label: "OpenCode", runtimeId: "opencode", command: "opencode", needsBivyModel: false },
+  { key: "g", label: "Gemini CLI", runtimeId: "gemini", command: "gemini", needsBivyModel: false, loginHint: "Sign in through Gemini" },
+  { key: "q", label: "Qwen Code", runtimeId: "qwen", command: "qwen", needsBivyModel: false, loginHint: "Sign in through Qwen" },
   { key: "a", label: "Aider", runtimeId: "aider", needsBivyModel: true },
   { key: "l", label: "Cline", runtimeId: "cline", needsBivyModel: false },
   { key: "r", label: "Crush", runtimeId: "crush", needsBivyModel: false },
@@ -402,6 +402,25 @@ function setupAgentByRuntime(runtimeId) {
   return SETUP_AGENT_CHOICES.find((choice) => choice.runtimeId === runtimeId);
 }
 
+function setupAgentDefaultKey(config) {
+  const saved = setupAgentByRuntime(String(config?.env?.BIVY_RUNTIME || ""));
+  if (saved) return saved.key;
+  const installed = SETUP_AGENT_CHOICES.find((choice) => choice.command && commandExists(choice.command));
+  return installed?.key || "p";
+}
+
+function nativeAgentAuthDetected(choice) {
+  if (!choice?.command || !commandExists(choice.command)) return false;
+  if (Array.isArray(choice.authProbe)) {
+    const result = runQuiet(choice.command, choice.authProbe, { timeout: 10_000 });
+    if (result.code === 0) return true;
+  }
+  // Conservative file fallbacks for older CLI versions without a status command.
+  if (choice.command === "codex") return fs.existsSync(path.join(os.homedir(), ".codex", "auth.json"));
+  if (choice.command === "claude") return fs.existsSync(path.join(os.homedir(), ".claude", ".credentials.json"));
+  return false;
+}
+
 function url(config) {
   return `http://localhost:${config.port}`;
 }
@@ -3205,11 +3224,20 @@ async function cmdSetup(args = []) {
   }
   console.log(c.dim(`Workspace: ${config.workspace}  ·  local port: ${config.port}  (change both in Settings)`));
 
-  // 2. Default agent — stays Pi unless one was already chosen. Pi is the built-in
-  // default and is changeable per-session or in Settings, so setup doesn't ask.
-  // Model/provider sign-in is left to the agent's own CLI/TUI or Settings.
-  const setupAgent = setupAgentByRuntime(String(config.env.BIVY_RUNTIME || "pi")) || setupAgentByRuntime("pi");
-  if (!config.env.BIVY_RUNTIME && setupAgent) {
+  // 2. Agent first: authentication depends on who owns the selected agent's
+  // credentials. Prefer an already-installed native agent on a fresh machine,
+  // while retaining the saved choice when setup is re-run.
+  console.log(c.bold("\n  Agent\n"));
+  const agentChoice = await askChoice(
+    "Which agent do you want to try first?",
+    SETUP_AGENT_CHOICES.map((choice) => ({
+      key: choice.key,
+      label: `${choice.label}${choice.command && commandExists(choice.command) ? " (installed)" : ""}`,
+    })),
+    setupAgentDefaultKey(config),
+  );
+  const setupAgent = SETUP_AGENT_CHOICES.find((choice) => choice.key === agentChoice) || setupAgentByRuntime("pi");
+  if (setupAgent) {
     config.env = { ...config.env, BIVY_RUNTIME: setupAgent.runtimeId };
     saveConfig(config);
   }
@@ -3218,7 +3246,7 @@ async function cmdSetup(args = []) {
     agentReady = await ensureSetupAgent(setupAgent);
     if (!agentReady) console.log(c.yellow(`${setupAgent.label} was not fully installed. Install it later from the app or with 'bivy agents:install'.`));
   }
-  console.log(c.dim(`Default agent: ${setupAgent?.label || "Pi"}  (change in Settings; sign into your model from the agent's CLI/TUI or Settings → Keys & OAuth)`));
+  console.log(c.dim(`Default agent: ${setupAgent?.label || "Pi"}  (change any time in Settings)`));
 
   // 3. Secure remote web/PWA access is what makes a Bivy-managed CLI useful:
   // without a relay/control plane it adds nothing over running the agent
@@ -3306,7 +3334,9 @@ async function cmdSetup(args = []) {
   // Bivy's provider login; offer it inline so setup cannot imply the first task
   // is ready while the required credential is still absent. Agent-native auth is
   // explained in the readiness checklist below because those CLIs own the flow.
-  if (setupAgent?.needsBivyModel && !hasModelConfig(config)) {
+  let agentAuthReady = setupAgent?.needsBivyModel ? hasModelConfig(config) : nativeAgentAuthDetected(setupAgent);
+  if (setupAgent?.needsBivyModel && !agentAuthReady) {
+    console.log("\nBivy stores this credential encrypted on your machine, reuses it with compatible agents, and syncs it E2E-encrypted to your other Bivy nodes. Bivy Cloud never receives it in plaintext.");
     const signInNow = await askYesNo("Sign in to a model now so your first task can run?", true);
     if (signInNow) {
       rl.pause();
@@ -3315,13 +3345,33 @@ async function cmdSetup(args = []) {
       if (loginCode !== 0 || !hasModelConfig(loadConfig())) {
         console.log(c.yellow("Model sign-in did not complete. The node can start, but an agent reply still requires 'bivy login'."));
       }
+      agentAuthReady = hasModelConfig(loadConfig());
+    }
+  } else if (setupAgent && !setupAgent.needsBivyModel) {
+    if (agentAuthReady) {
+      console.log(c.green(`\n  ✓ Existing ${setupAgent.label} login detected — Bivy will reuse it in the terminal and PWA.`));
+    } else if (setupAgent.command) {
+      console.log(`\n${setupAgent.label} owns its login; Bivy reuses that native login and does not copy it into the shared vault.`);
+      const signInNow = await askYesNo(`Open ${setupAgent.label} now to sign in? (Exit it when sign-in is complete.)`, true);
+      if (signInNow) {
+        rl.pause();
+        const loginCode = await run(setupAgent.command, [], { cwd: config.workspace, env: startEnv(config) });
+        rl.resume();
+        agentAuthReady = loginCode === 0 || nativeAgentAuthDetected(setupAgent);
+      }
     }
   }
 
   // 4. Background service — always installed so the node keeps running (and stays
   // reachable remotely) after you close this terminal. No prompt.
   let started = false;
-  if (config.service) {
+  if (process.env.BIVY_SETUP_SKIP_SERVICE === "1") {
+    // Isolation seam for disposable/container smoke tests: the caller starts a
+    // node with this BIVY_DATA_DIR/port and setup exercises the real wizard
+    // without installing or replacing the host user's system service.
+    started = await isReachable(config);
+    console.log(c.dim(`\nBackground-service install skipped; using the isolated node already running at ${url(config)}.`));
+  } else if (config.service) {
     console.log(c.dim("\nBackground service already configured; restarting it."));
     started = restartService();
   } else {
@@ -3337,18 +3387,20 @@ async function cmdSetup(args = []) {
   }
 
   const finalConfig = loadConfig();
-  const modelReady = !setupAgent?.needsBivyModel || hasModelConfig(finalConfig);
+  const modelReady = setupAgent?.needsBivyModel ? hasModelConfig(finalConfig) : agentAuthReady;
   console.log(c.bold(c.green("\n  ✓ Node running. Check first-task readiness below.\n")));
   console.log(`  ${c.green("✓")} node reachable at ${url(finalConfig)}`);
   console.log(`  ${agentReady ? c.green("✓") : c.yellow("!")} runtime ${agentReady ? `${setupAgent?.label || "Pi"} available` : "not installed — run 'bivy agents:install'"}`);
-  console.log(`  ${modelReady ? (setupAgent?.needsBivyModel ? c.green("✓") : c.dim("○")) : c.yellow("!")} model ${modelReady ? (setupAgent?.needsBivyModel ? "credential configured" : "agent-managed — verified by the first task") : "not configured — run 'bivy login'"}`);
+  console.log(`  ${modelReady ? c.green("✓") : c.yellow("!")} model ${modelReady ? (setupAgent?.needsBivyModel ? "credential configured" : "native agent login ready") : (setupAgent?.needsBivyModel ? "not configured — run 'bivy login'" : `${setupAgent?.loginHint || "sign in through the selected agent"}`)}`);
   console.log(`  ${c.dim("○")} repository chosen from the directory where you start Bivy`);
   const ghReady = githubConnected(finalConfig);
   console.log(`  ${ghReady ? c.green("✓") : c.dim("○")} GitHub ${ghReady ? "connected — your repos will list in the app" : c.dim("not connected — 'bivy github:connect' to list repos (optional)")}`);
   console.log(`  ${agentReady && modelReady ? c.green("✓") : c.yellow("!")} first task ${agentReady && modelReady ? "ready to try" : "blocked by the stage above"}`);
   console.log(`  ${fs.existsSync(relayConfigPath) ? c.green("✓") : c.yellow("!")} remote ${fs.existsSync(relayConfigPath) ? "configured" : "not configured — run 'bivy relay:setup'"}\n`);
-  printFirstRunSteps(modelReady, finalConfig);
+  // Get the user into the product immediately; terminal commands are the
+  // fallback/next-step checklist after the remote app has been opened or linked.
   await finishSetupRemote(finalConfig, setupSession);
+  printFirstRunSteps(modelReady, finalConfig, setupAgent);
 }
 
 // Read and delete the one-time account-session handoff written by relay:setup
@@ -3448,10 +3500,15 @@ function githubConnected(config = null) {
   return Boolean(token);
 }
 
-function printFirstRunSteps(modelReady = false, config = null) {
+function printFirstRunSteps(modelReady = false, config = null, setupAgent = null) {
   console.log("  Run your first task:");
   let n = 0;
-  if (!modelReady) console.log(`    ${++n}. Model access:   ${c.cyan("bivy login")}  ${c.dim("(for Pi; other agents use their own login)")}`);
+  if (!modelReady) {
+    const login = setupAgent?.needsBivyModel
+      ? `${c.cyan("bivy login")}  ${c.dim("(stored in Bivy's encrypted vault)")}`
+      : c.cyan(setupAgent?.command || "the selected agent's native CLI");
+    console.log(`    ${++n}. Model access:   ${login}`);
+  }
   // GitHub is optional — "No repo" sessions work without it — so this only shows
   // when nothing is connected yet, and never blocks the flow.
   if (!githubConnected(config)) {

package/dist/runtime/auth-errors.js

@@ -21,7 +21,7 @@ export function isModelAuthError(raw) {
     const text = String(raw || "");
     // Generic: an explicit 401, "unauthorized"/"authentication", or a
     // missing/invalid bearer/api-key/token phrase.
-    if (/\b401\b|unauthorized|authentication|invalid x-api-key|(missing|invalid)[\s\S]*(bearer|api[\s_-]?key|token)/i.test(text))
+    if (/\b401\b|unauthorized|authentication|invalid x-api-key|(missing|no|invalid)[\s\S]*(bearer|api[\s_-]?key|token)/i.test(text))
         return true;
     // Codex app-server: websocket connect rejected with an HTTP 401/403.
     if (/failed to connect to websocket[\s\S]*http error:\s*40[13]/i.test(text))

package/dist/runtime/credential-store.js

@@ -34,6 +34,17 @@ function isStoredCredential(value) {
 function providerId(id) {
     return String(id ?? "").trim().toLowerCase();
 }
+function sameCredentialContent(a, b) {
+    if (!a)
+        return false;
+    const { updatedAt: _a, ...left } = a;
+    const { updatedAt: _b, ...right } = b;
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function withoutStoreMetadata(credential) {
+    const { updatedAt: _updatedAt, ...projected } = credential;
+    return projected;
+}
 /**
  * Should an `incoming` credential replace the `local` one during a non-destructive
  * `importAll` merge? Pure and exported so the convergence rule is unit-testable
@@ -65,6 +76,19 @@ export function preferIncomingCredential(local, incoming) {
         return it > lt;
     return (Number(incoming.expires) || 0) > (Number(local.expires) || 0);
 }
+/** A tombstone wins only when it is newer than the credential it would remove. */
+export function tombstoneWins(credential, deletedAt) {
+    if (!Number.isFinite(deletedAt) || deletedAt <= 0)
+        return false;
+    if (!credential)
+        return true;
+    const updatedAt = Number(credential.updatedAt);
+    const refreshedAt = credential.type === "oauth" ? Number(credential.refreshedAt) : 0;
+    const credentialTime = Number.isFinite(updatedAt) && updatedAt > 0
+        ? updatedAt
+        : Number.isFinite(refreshedAt) && refreshedAt > 0 ? refreshedAt : 0;
+    return deletedAt > credentialTime;
+}
 /**
  * Encrypted, cross-process-locked credential vault backed by `<vaultDir>/auth.enc`.
  *
@@ -104,10 +128,11 @@ export class BivyCredentialStore {
         const id = providerId(provider);
         if (!id)
             return undefined;
-        return this.readBlob()[id];
+        const credential = this.readDocument().providers[id];
+        return credential ? withoutStoreMetadata(credential) : undefined;
     }
     async list() {
-        return Object.entries(this.readBlob()).map(([id, cred]) => ({
+        return Object.entries(this.readDocument().providers).map(([id, cred]) => ({
             providerId: id,
             type: cred.type,
             ...(cred.type === "oauth" ? { expiresAt: cred.expires } : {}),
@@ -126,15 +151,18 @@ export class BivyCredentialStore {
         return this.enqueue(id, async () => {
             await this.acquireLock();
             try {
-                const vault = this.readBlob();
+                const document = this.readDocument();
+                const vault = document.providers;
                 const next = await fn(vault[id]);
                 if (next === undefined)
                     return vault[id];
                 if (!isStoredCredential(next))
                     throw new Error(`Invalid credential for "${id}"`);
-                vault[id] = next;
-                this.writeBlob(vault);
-                return next;
+                const stamped = { ...next, updatedAt: Date.now() };
+                vault[id] = stamped;
+                delete document.deletedAt[id];
+                this.writeDocument(document);
+                return stamped;
             }
             finally {
                 await this.releaseLock();
@@ -148,11 +176,14 @@ export class BivyCredentialStore {
         await this.enqueue(id, async () => {
             await this.acquireLock();
             try {
-                const vault = this.readBlob();
-                if (!(id in vault))
+                const document = this.readDocument();
+                const hadCredential = id in document.providers;
+                delete document.providers[id];
+                const deletedAt = Date.now();
+                if (!hadCredential && (document.deletedAt[id] ?? 0) >= deletedAt)
                     return;
-                delete vault[id];
-                this.writeBlob(vault);
+                document.deletedAt[id] = deletedAt;
+                this.writeDocument(document);
             }
             finally {
                 await this.releaseLock();
@@ -169,7 +200,11 @@ export class BivyCredentialStore {
     }
     /** Every stored credential, keyed by provider id — the cross-node snapshot. */
     async exportAll() {
-        return this.readBlob();
+        return this.readDocument().providers;
+    }
+    /** Provider deletions retained for cross-node convergence. */
+    async exportTombstones() {
+        return this.readDocument().deletedAt;
     }
     /** The plaintext `auth.json` path an agent's own CLI/TUI reads (`<plaintextDir>/auth.json`). */
     get legacyAuthPath() {
@@ -184,7 +219,7 @@ export class BivyCredentialStore {
      * `ingestPlaintext()` to fold TUI-time logins back into the vault.
      */
     materializePlaintext() {
-        const vault = this.readBlob();
+        const vault = Object.fromEntries(Object.entries(this.readDocument().providers).map(([id, credential]) => [id, withoutStoreMetadata(credential)]));
         const next = `${JSON.stringify(vault, null, 2)}\n`;
         // Write only when the projection actually changes. This keeps the file's
         // mtime stable so a live re-materialize (on a vault change while a native Pi
@@ -222,17 +257,25 @@ export class BivyCredentialStore {
      * (rotated refresh tokens are single-use — importing a stale one breaks the
      * next refresh). Runs under the lock so it can't race a refresh.
      */
-    async importAll(snapshot) {
+    async importAll(snapshot, deletedAt = {}) {
         await this.acquireLock();
         try {
-            const vault = this.readBlob();
+            const document = this.readDocument();
+            const vault = document.providers;
             let imported = 0;
             let changed = false;
             for (const [rawId, incoming] of Object.entries(snapshot ?? {})) {
                 const id = providerId(rawId);
                 if (!id || !isStoredCredential(incoming))
                     continue;
+                if (tombstoneWins(incoming, document.deletedAt[id] ?? 0))
+                    continue;
                 const local = vault[id];
+                // Store-owned timestamps are intentionally not part of credential
+                // content. An older sender may re-state the same key without updatedAt;
+                // preserve the local stamp and avoid a pointless re-encrypt/watch loop.
+                if (sameCredentialContent(local, incoming))
+                    continue;
                 // Freshest-wins, rotation-safe (see preferIncomingCredential): a lagging
                 // or refresh-less snapshot must not overwrite a fresher local login.
                 if (!preferIncomingCredential(local, incoming))
@@ -245,11 +288,31 @@ export class BivyCredentialStore {
                 // vault watcher (materialize → ingest → import loop protection).
                 if (JSON.stringify(local) !== JSON.stringify(incoming)) {
                     vault[id] = incoming;
+                    const incomingUpdatedAt = Number(incoming.updatedAt);
+                    if (!Number.isFinite(document.deletedAt[id]) || incomingUpdatedAt > document.deletedAt[id]) {
+                        delete document.deletedAt[id];
+                    }
                     changed = true;
                 }
             }
+            for (const [rawId, rawDeletedAt] of Object.entries(deletedAt ?? {})) {
+                const id = providerId(rawId);
+                const deletionTime = Number(rawDeletedAt);
+                if (!id || !Number.isFinite(deletionTime) || deletionTime <= 0)
+                    continue;
+                if ((document.deletedAt[id] ?? 0) >= deletionTime)
+                    continue;
+                // A later re-login makes an older tombstone obsolete; do not retain and
+                // re-export it alongside the live credential.
+                if (vault[id] && !tombstoneWins(vault[id], deletionTime))
+                    continue;
+                document.deletedAt[id] = deletionTime;
+                if (tombstoneWins(vault[id], deletionTime))
+                    delete vault[id];
+                changed = true;
+            }
             if (changed)
-                this.writeBlob(vault);
+                this.writeDocument(document);
             return imported;
         }
         finally {
@@ -281,14 +344,14 @@ export class BivyCredentialStore {
         catch { /* best effort */ }
         return key;
     }
-    readBlob() {
+    readDocument() {
         this.ensureMigrated();
         let raw;
         try {
             raw = fs.readFileSync(this.blobFile, "utf8");
         }
         catch {
-            return {};
+            return { v: 2, providers: {}, deletedAt: {} };
         }
         let parsed;
         try {
@@ -297,13 +360,26 @@ export class BivyCredentialStore {
         catch {
             // A truncated/corrupt/undecryptable vault is treated as empty rather than
             // taking the node down: every caller already handles "no credential".
-            return {};
+            return { v: 2, providers: {}, deletedAt: {} };
+        }
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && parsed.v === 2) {
+            const raw = parsed;
+            const tombstones = {};
+            if (raw.deletedAt && typeof raw.deletedAt === "object" && !Array.isArray(raw.deletedAt)) {
+                for (const [id, value] of Object.entries(raw.deletedAt)) {
+                    const normalized = providerId(id);
+                    const stamp = Number(value);
+                    if (normalized && Number.isFinite(stamp) && stamp > 0)
+                        tombstones[normalized] = stamp;
+                }
+            }
+            return { v: 2, providers: normalizeMap(raw.providers), deletedAt: tombstones };
         }
-        return normalizeMap(parsed);
+        return { v: 2, providers: normalizeMap(parsed), deletedAt: {} };
     }
-    writeBlob(vault) {
+    writeDocument(document) {
         fs.mkdirSync(this.vaultDir, { recursive: true, mode: 0o700 });
-        const ciphertext = seal(this.key(), JSON.stringify(vault));
+        const ciphertext = seal(this.key(), JSON.stringify(document));
         const tmp = `${this.blobFile}.${process.pid}.tmp`;
         fs.writeFileSync(tmp, `${ciphertext}\n`, { mode: 0o600 });
         fs.renameSync(tmp, this.blobFile);
@@ -335,7 +411,7 @@ export class BivyCredentialStore {
         if (Object.keys(map).length === 0)
             return;
         try {
-            this.writeBlob(map);
+            this.writeDocument({ v: 2, providers: map, deletedAt: {} });
         }
         catch {
             // If we can't write the encrypted vault, fall back to reading legacy on

package/dist/runtime/pi-auth.js

@@ -31,6 +31,10 @@ export async function listProviders(credsDir, piDir) {
 export async function exportProviderAuth(credsDir) {
     return createCredentialVault(credsDir).exportAll();
 }
+/** Export provider revocations for cross-node convergence. */
+export async function exportProviderAuthTombstones(credsDir) {
+    return createCredentialVault(credsDir).exportTombstones();
+}
 /**
  * Import a cross-node provider auth snapshot into the local vault.
  *
@@ -40,8 +44,8 @@ export async function exportProviderAuth(credsDir) {
  * snapshot (rotated refresh tokens are single-use). Provider removal propagates
  * via removeProvider() re-pushing, not destructive imports.
  */
-export async function importProviderAuth(credsDir, providers) {
-    await createCredentialVault(credsDir).importAll(providers);
+export async function importProviderAuth(credsDir, providers, deletedAt = {}) {
+    await createCredentialVault(credsDir).importAll(providers, deletedAt);
 }
 /** Store an API key for a model provider (shared by every agent via the vault). */
 export async function setProviderApiKey(credsDir, provider, key) {

package/dist/server.js

@@ -32,7 +32,7 @@ import { decideOAuthLoginSweep } from "./runtime/oauth/oauth-login-sweep.js";
 import { listCodexSessions, loadCodexTranscript, discoverCodexSessionForCwd } from "./runtime/codex-sessions.js";
 import { dedupeSessionSummaries } from "./session-identity.js";
 import { discoverPiSessionForCwd } from "./runtime/pi-session-discovery.js";
-import { exportProviderAuth, importProviderAuth, listProviders, removeProvider, setProviderApiKey, setProviderCredential } from "./runtime/pi-auth.js";
+import { exportProviderAuth, exportProviderAuthTombstones, importProviderAuth, listProviders, removeProvider, setProviderApiKey, setProviderCredential } from "./runtime/pi-auth.js";
 import { loadLocalModels, upsertLocalProvider, removeLocalProviderEntry, listLocalProviderSummaries, exportLocalModels, importLocalModels, toPiModelsConfig, normalizeProviderId, } from "./runtime/local-model-store.js";
 import { execEphemeralRequest } from "./ephemeral-exec.js";
 import { ApprovalManager } from "./approval.js";
@@ -3577,7 +3577,7 @@ const RELAY_COMMANDS = {
             // this the relay client (PWA) is stranded on "Working…" forever with
             // only a session.error toast. Clear working so a terminal state reaches it.
             clearSessionWorking(record);
-            broadcast({ type: "session.error", sessionId: record.id, error: String(error?.stack ?? error) });
+            broadcast({ type: "session.error", sessionId: record.id, error: actionableAgentError(record.runtimeId, error) });
         });
     },
     async "session.fork.export"(msg) {
@@ -3901,6 +3901,12 @@ function writeLocalModelAuthVaultKey(vaultKeyB64) {
     }
     catch { /* best effort */ }
 }
+function forgetLocalModelAuthVaultKey() {
+    try {
+        fs.rmSync(modelAuthVaultKeyPath, { force: true });
+    }
+    catch { /* best effort */ }
+}
 function ensureLocalModelAuthVaultKey() {
     const existing = readLocalModelAuthVaultKey();
     if (existing)
@@ -3914,13 +3920,13 @@ function ensureLocalModelAuthVaultKey() {
 // internal credential shape, so nodes on different agent/pi versions can't
 // silently exchange an incompatible structure. `decrypt` tolerates a bare map
 // for forward-safety.
-const MODEL_AUTH_ENVELOPE_VERSION = 1;
-function encryptModelAuthProviders(providers, localModels, vaultKeyB64) {
-    const envelope = { v: MODEL_AUTH_ENVELOPE_VERSION, providers, localModels };
+const MODEL_AUTH_ENVELOPE_VERSION = 2;
+function encryptModelAuthProviders(providers, deletedAt, localModels, vaultKeyB64) {
+    const envelope = { v: MODEL_AUTH_ENVELOPE_VERSION, providers, deletedAt, localModels };
     return seal(Buffer.from(vaultKeyB64, "base64"), JSON.stringify(envelope));
 }
 function decryptModelAuthEnvelope(ciphertext, vaultKeyB64) {
-    const empty = { providers: {}, localModels: {} };
+    const empty = { providers: {}, deletedAt: {}, localModels: {} };
     const parsed = JSON.parse(open(Buffer.from(vaultKeyB64, "base64"), ciphertext));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
         return empty;
@@ -3929,11 +3935,12 @@ function decryptModelAuthEnvelope(ciphertext, vaultKeyB64) {
     if (typeof envelope.v === "number" && envelope.providers && typeof envelope.providers === "object") {
         return {
             providers: envelope.providers,
+            deletedAt: envelope.deletedAt && typeof envelope.deletedAt === "object" ? envelope.deletedAt : {},
             localModels: (envelope.localModels && typeof envelope.localModels === "object" ? envelope.localModels : {}),
         };
     }
     // Back-compat: a bare `{ [id]: Credential }` map (pre-envelope / other sender).
-    return { providers: parsed, localModels: {} };
+    return { providers: parsed, deletedAt: {}, localModels: {} };
 }
 async function modelAuthFetch(pathname, init = {}) {
     if (!sessionAdvertiseTarget)
@@ -4023,8 +4030,23 @@ async function syncModelAuthFromControlPlane() {
             writeLocalModelAuthVaultKey(vaultKeyB64);
         }
         if (data.vault?.ciphertext && vaultKeyB64) {
-            const { providers, localModels } = decryptModelAuthEnvelope(data.vault.ciphertext, vaultKeyB64);
-            await importProviderAuth(credsDir, providers);
+            let decrypted;
+            try {
+                decrypted = decryptModelAuthEnvelope(data.vault.ciphertext, vaultKeyB64);
+            }
+            catch (error) {
+                // Most commonly this node cached the previous generation while another
+                // survivor completed a revoke-triggered re-key. Forget it and request a
+                // wrap of the current key; retaining it would make every poll fail forever.
+                forgetLocalModelAuthVaultKey();
+                lastPushedModelAuthCiphertext = "";
+                await modelAuthFetch("/node/model-auth-key/request", { method: "POST", body: JSON.stringify({ publicKey: pairingStore.nodePublicKeyB64() }) });
+                ensureModelAuthColdStart();
+                console.warn("[auth-sync] cached vault key is stale; requested the rotated key:", error.message);
+                return;
+            }
+            const { providers, deletedAt, localModels } = decrypted;
+            await importProviderAuth(credsDir, providers, deletedAt);
             importLocalModels(localModelsDir, localModels);
             // A synced key or config change can both alter the projection, so always
             // regenerate it (and refresh the panel) after importing the vault.
@@ -4035,6 +4057,8 @@ async function syncModelAuthFromControlPlane() {
             // the cold-start race is over.
             stopModelAuthColdStart();
             broadcast({ type: "providers.list", providers: await listProvidersUnified() });
+            if (data.vault.needsRotation)
+                await pushModelAuthToControlPlane(true);
         }
         else if (data.vault?.ciphertext && !vaultKeyB64) {
             await modelAuthFetch("/node/model-auth-key/request", { method: "POST", body: JSON.stringify({ publicKey: pairingStore.nodePublicKeyB64() }) });
@@ -4067,7 +4091,7 @@ async function processModelAuthKeyRequests(requests) {
         });
     }
 }
-async function pushModelAuthToControlPlane() {
+async function pushModelAuthToControlPlane(rotateKey = false) {
     if (!sessionAdvertiseTarget)
         return;
     // Piggyback the (plaintext, non-secret) provider status summary on every
@@ -4078,12 +4102,25 @@ async function pushModelAuthToControlPlane() {
     await pushProviderSummaryToControlPlane();
     try {
         const providers = await exportProviderAuth(credsDir);
+        const deletedAt = await exportProviderAuthTombstones(credsDir);
         const localModels = exportLocalModels(localModelsDir);
-        const vaultKeyB64 = ensureLocalModelAuthVaultKey();
-        const ciphertext = encryptModelAuthProviders(providers, localModels, vaultKeyB64);
-        if (ciphertext === lastPushedModelAuthCiphertext)
+        const previousKey = readLocalModelAuthVaultKey();
+        const vaultKeyB64 = rotateKey ? randomBytes(32).toString("base64") : ensureLocalModelAuthVaultKey();
+        if (rotateKey)
+            writeLocalModelAuthVaultKey(vaultKeyB64);
+        const ciphertext = encryptModelAuthProviders(providers, deletedAt, localModels, vaultKeyB64);
+        if (!rotateKey && ciphertext === lastPushedModelAuthCiphertext)
             return;
-        await modelAuthFetch("/node/model-auth-vault", { method: "PUT", body: JSON.stringify({ ciphertext }) });
+        const push = await modelAuthFetch("/node/model-auth-vault", { method: "PUT", body: JSON.stringify({ ciphertext, rotated: rotateKey }) });
+        if (!push?.ok) {
+            if (rotateKey) {
+                if (previousKey)
+                    writeLocalModelAuthVaultKey(previousKey);
+                else
+                    forgetLocalModelAuthVaultKey();
+            }
+            throw new Error(`model-auth vault push failed (${push?.status ?? "offline"})`);
+        }
         await modelAuthFetch("/node/model-auth-key/wrapped", {
             method: "PUT",
             body: JSON.stringify({ targetNodeId: identity.nodeId, wrappedByPublicKey: pairingStore.nodePublicKeyB64(), wrappedKey: pairingStore.wrapForNodePublicKey(pairingStore.nodePublicKeyB64(), vaultKeyB64) }),
@@ -7353,6 +7390,20 @@ function humanizeAgentError(raw) {
     }
     return text;
 }
+function actionableAgentError(runtimeId, error) {
+    const raw = humanizeAgentError(error instanceof Error ? error.message : String(error));
+    const id = String(runtimeId || "").toLowerCase();
+    if (isModelAuthError(raw) || /reading ['"]provider['"]|no api key found/i.test(raw)) {
+        if (id.includes("claude"))
+            return "Claude Code is not signed in. Run `claude` once, complete sign-in, then retry; the same login works from Bivy and the PWA.";
+        if (id.startsWith("codex"))
+            return "Codex is not signed in. Run `codex login`, then retry; the same login works from Bivy and the PWA.";
+        if (id === "pi" || id === "aider")
+            return "No model credential is configured. Run `bivy login`, then retry. This is only required once and compatible credentials sync E2E-encrypted to your other Bivy nodes.";
+        return "The selected agent needs model authentication. Sign in through its native CLI, then retry.";
+    }
+    return raw;
+}
 /**
  * A turn that ended in a *terminal* model/provider failure the runtime would
  * otherwise swallow. `agent_end` carries the turn's messages and whether the
@@ -7579,7 +7630,7 @@ function attachSessionListeners(record) {
                 record.lastFailureAt = Date.now();
                 metadata.touchSession(record.id, "failed");
                 scheduleAdvertise();
-                broadcast({ type: "session.error", sessionId: record.id, error: messageError });
+                broadcast({ type: "session.error", sessionId: record.id, error: actionableAgentError(record.runtimeId, messageError) });
                 // If the terminal error is an auth failure (expired key/token → 4xx),
                 // also raise the sign-in sheet for the failing provider.
                 maybeSignalAuthRequired(record, messageError);
@@ -10041,7 +10092,7 @@ app.post("/api/session", async (req, res, next) => {
         res.json({ id: session.id, workspace: session.workspace, source: session.source, branch: session.worktree?.branch, prUrl: session.prUrl, sessionFile: session.sessionFile, name: session.session.getName(), runtimeId: session.runtimeId, agentName: getRuntime(session.runtimeId).displayName, model: publicModel(session.session.getCurrentModel(), session.session.getCurrentModel()) });
     }
     catch (error) {
-        res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
+        res.status(400).json({ error: actionableAgentError(agentFrom(req.body ?? {}) ?? defaultRuntimeId, error) });
     }
 });
 app.get("/api/github/issues", async (_req, res, next) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.8.2",
+  "version": "0.8.3-staging.117",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",