@bivy/bivy 0.8.3-staging.116 → 0.8.3-staging.118

package/bin/bivy.mjs

@@ -131,6 +131,7 @@ const packaged = fs.existsSync(path.join(repoRoot, "dist", "server.js"));
 const serverEntry = path.join(repoRoot, packaged ? "dist/server.js" : "src/server.ts");
 const nativePiEntry = path.join(repoRoot, packaged ? "dist/native-pi.js" : "src/native-pi.ts");
 const bivyLoginEntry = path.join(repoRoot, packaged ? "dist/bivy-login.js" : "src/bivy-login.ts");
+const credentialIngestEntry = path.join(repoRoot, packaged ? "dist/credential-ingest-cli.js" : "src/credential-ingest-cli.ts");
 const relaySetupEntry = path.join(repoRoot, packaged ? "dist/relay-setup.js" : "src/relay-setup.ts");
 // Dependency-free hosted-endpoint helper. Shipped to dist/ in the release
 // artifact (src/ is not packaged), so resolve it the same packaged-aware way as
@@ -388,11 +389,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 +403,36 @@ 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;
+}
+
+async function ingestSetupAgentLogin(choice) {
+  if (!choice || !["claude-code-sdk", "codex"].includes(choice.runtimeId)) return false;
+  const code = await run(nodeBin, [
+    ...nodeScriptArgs(credentialIngestEntry),
+    choice.runtimeId,
+    path.join(appDir, "credentials"),
+    path.join(appDir, "pi"),
+  ], { cwd: repoRoot, env: process.env, stdio: "ignore" });
+  return code === 0;
+}
+
 function url(config) {
   return `http://localhost:${config.port}`;
 }
@@ -2636,9 +2667,11 @@ function createPrompter() {
   };
 
   const askChoice = async (question, choices, fallback) => {
-    const labels = choices.map((choice) => `${choice.key}=${choice.label}`).join(", ");
     for (;;) {
-      const answer = (await ask(`${question} (${labels})`, fallback)).toLowerCase();
+      const menu = choices.map((choice) => `    ${c.cyan(choice.key)}  ${choice.label}`).join("\n");
+      const suffix = fallback ? c.dim(` [default: ${fallback}]`) : "";
+      process.stdout.write(`\n${c.cyan("›")} ${question}\n${menu}\n  >${suffix} `);
+      const answer = String(await nextLine()).trim().toLowerCase() || fallback || "";
       const match = choices.find((choice) => answer === choice.key || answer === choice.label.toLowerCase());
       if (match) return match.key;
       console.log(c.yellow(`Please choose one of: ${choices.map((choice) => choice.key).join(", ")}`));
@@ -3205,11 +3238,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 +3260,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
@@ -3238,7 +3280,7 @@ async function cmdSetup(args = []) {
     const syncChoice = await askChoice(
       "Remote access",
       [
-        { key: "h", label: "hosted (recommended — one node is free)" },
+        { key: "h", label: "hosted (recommended — first 25 remotely accessible sessions are free; nothing caps your local usage)" },
         { key: "s", label: "self-hosted (your own control plane + relay)" },
       ],
       selfHostEnv ? "s" : "h",
@@ -3306,7 +3348,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 +3359,35 @@ 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) {
+      const imported = await ingestSetupAgentLogin(setupAgent);
+      console.log(c.green(`\n  ✓ Existing ${setupAgent.label} login detected — Bivy will reuse it in the terminal and PWA${imported ? " and stored it in the encrypted vault" : ""}.`));
+    } else if (setupAgent.command) {
+      console.log(`\n${setupAgent.label} owns its login. After sign-in, Bivy stores compatible credential fields in its encrypted vault so the terminal, PWA, and your other Bivy nodes can reuse them.`);
+      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);
+        if (agentAuthReady) await ingestSetupAgentLogin(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 +3403,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(`  ${ghReady ? c.green("✓") : c.dim("○")} GitHub ${ghReady ? "connected — your repos will list in the app" : c.dim("optional — connect later in the app under Settings → GitHub App")}`);
   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, setupAgent);
 }
 
 // Read and delete the one-time account-session handoff written by relay:setup
@@ -3377,20 +3445,18 @@ function consumeSetupSession() {
 // `/nodes` return only this one node, so a user with other nodes appeared to land
 // on a different/empty account until they signed out and back in.
 //
-// The separately minted node-scoped paired link (E2E key embedded) is reserved
-// for the QR below, which is meant to be scanned by *another* device to pair it
-// with this node — there, node-scoping is the right least-privilege choice.
-// Everything is also printed as text so servers without a browser can copy it.
 // Open this node's REMOTE control-plane app in a local browser (best effort) and
-// return the URLs involved. The node no longer hosts a UI, so the web/PWA app
+// return the URL involved. The node no longer hosts a UI, so the web/PWA app
 // always comes from the hosted or self-hosted control plane. Prefers, in order:
 // an account sign-in URL (only available right after `relay:setup`, when a
-// setupSession is supplied) → a freshly minted node-scoped paired link → the
-// plain remote base URL. Prints a clean "Opening <base>" line — never the
-// tokenized fragment, so no session/pairing secret lands in terminal scrollback.
+// setupSession is supplied) → the plain remote base URL, where the user signs
+// in normally. Pairing is deliberately reserved for the explicit `bivy link`
+// command; ordinary setup/open should establish the full account experience.
+// Prints a clean "Opening <base>" line — never the tokenized fragment, so no
+// account secret lands in terminal scrollback.
 // Returns null when no relay is configured (caller should send the user to
 // `bivy relay:setup`).
-async function openRemoteApp(config, { setupSession = null, open = true } = {}) {
+async function openRemoteApp({ setupSession = null, open = true, remotePath = "" } = {}) {
   const relay = loadRelayConfig();
   if (!relay) return null;
 
@@ -3408,31 +3474,15 @@ async function openRemoteApp(config, { setupSession = null, open = true } = {})
       session: setupSession.session,
       ...(setupSession.nodeId ? { node: { id: setupSession.nodeId } } : {}),
     };
-    accountUrl = `${remoteBase}/#${Buffer.from(JSON.stringify(payload)).toString("base64url")}`;
-  }
-
-  // Try to mint a node-scoped paired link (safe to embed in a QR another device
-  // scans). Needs the node reachable, so wait briefly first.
-  let pairedUrl = "";
-  await waitForNode(config).catch(() => {});
-  try {
-    const token = await localDeviceToken(config);
-    const data = await localApi(config, "/api/relay/link", {
-      method: "POST",
-      headers: { authorization: `Bearer ${token}` },
-      body: "{}",
-    });
-    if (data?.url) pairedUrl = data.url;
-  } catch {
-    // fall back to the plain remote app URL below
+    accountUrl = `${remoteBase}${remotePath}/#${Buffer.from(JSON.stringify(payload)).toString("base64url")}`;
   }
 
-  const openUrl = accountUrl || pairedUrl || remoteBase;
+  const openUrl = accountUrl || `${remoteBase}${remotePath}`;
   if (open && canOpenBrowser() && openUrl) {
     console.log(`  Opening ${c.cyan(remoteBase || openUrl)} …`);
     openBrowser(openUrl);
   }
-  return { relay, remoteBase, accountUrl, pairedUrl, openUrl };
+  return { relay, remoteBase, accountUrl, openUrl };
 }
 
 // Whether GitHub is connected for repo listing/cloning. Bivy's own connect flow
@@ -3448,22 +3498,24 @@ function githubConnected(config = null) {
   return Boolean(token);
 }
 
-function printFirstRunSteps(modelReady = false, config = 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)")}`);
-  // 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)) {
-    console.log(`    ${++n}. GitHub ${c.dim("(optional)")}: ${c.cyan("bivy github:connect")}  ${c.dim("— lets the app list your repos; required for private ones")}`);
+function printFirstRunSteps(modelReady = false, setupAgent = null) {
+  console.log("  Start your first session:");
+  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(`    Model access: ${login}`);
   }
-  console.log(`    ${++n}. Start chatting: ${c.cyan("bivy")}`);
-  console.log(`       Starter task:  ${c.cyan('bivy exec "explain this repository and identify one low-risk improvement"')}\n`);
+  const agent = setupAgent?.command || setupAgent?.runtimeId || resolveDefaultAgent();
+  const remoteApp = String(loadRelayConfig()?.clientBaseUrl || "https://app.bivy.sh").replace(/\/+$/, "");
+  console.log(`    • In the terminal: ${c.cyan(`bivy run ${agent}`)}`);
+  console.log(`      Then use the remote app to watch the session or take over in chat.`);
+  console.log(`    • Or start in chat: ${c.cyan(remoteApp)}\n`);
 }
 
 async function finishSetupRemote(config, setupSession = null) {
   const openable = canOpenBrowser();
-  const remote = await openRemoteApp(config, { setupSession });
+  const remote = await openRemoteApp({ setupSession });
 
   if (!remote) {
     console.log("\n  Almost there — enable remote access to open the Bivy app:");
@@ -3472,19 +3524,14 @@ async function finishSetupRemote(config, setupSession = null) {
     return;
   }
 
-  const { remoteBase, pairedUrl } = remote;
-  if (pairedUrl) {
-    const qr = terminalQr(pairedUrl);
-    if (qr) console.log(qr + "\n");
-  }
+  const { remoteBase } = remote;
 
   console.log("\n  Access Bivy from anywhere:");
   if (remoteBase) console.log(`    • Remote app:     ${c.cyan(remoteBase)}  (sign in with the same GitHub/email you just used)`);
-  console.log(`    • Link a device:  ${c.cyan("bivy link")}  (prints a QR to pair a phone/laptop with this node)`);
   console.log(`    • Check status:   ${c.cyan("bivy status")}`);
   if (!openable) {
     console.log(c.dim("\n  No browser on this machine (headless server)? Open the Remote app URL above"));
-    console.log(c.dim("  on your phone or laptop and sign in, or scan the QR above to pair a device with this node."));
+    console.log(c.dim("  on your phone or laptop and sign in with the same GitHub account or email."));
   }
   console.log("");
 }
@@ -4205,7 +4252,7 @@ ${c.bold("bivy")} — Bivy node CLI
   ${c.cyan("bivy kill <id>")}    Stop a session/terminal (--delete also removes a saved session)
   ${c.cyan("bivy prune")}         Delete old sessions/workspaces/worktrees (--keep N, --older-than 7d, --dry-run)
   ${c.cyan("bivy exec")} "<prompt>"  One-shot headless run: prints the answer to stdout (pipe-friendly)
-  ${c.cyan("bivy")}              Launch the default agent (pi) as a managed, relay-visible session
+  ${c.cyan("bivy")}              Show this help
   ${c.cyan("bivy setup")}      First-run wizard: workspace, remote access + sign-in, background service
   ${c.cyan("bivy start")}      Run the daemon in the foreground
   ${c.cyan("bivy stop")}       Stop the background service
@@ -4225,7 +4272,7 @@ ${c.bold("bivy")} — Bivy node CLI
   ${c.cyan("bivy github:app-create")}            One-click: create + connect a GitHub App
   ${c.cyan("bivy github:app-connect")}           Connect an existing GitHub App (--app-id --key)
   ${c.cyan("bivy github:app-sync")} [on|off]     Sync connected GitHub App keys to this account's other opted-in nodes
-  ${c.cyan("bivy github:connect")} [owner/repo]  Authorize repo access for the repo picker (device flow)
+  ${c.cyan("bivy github:connect")} [owner/repo]  Connect GitHub in the app (or use a configured self-hosted device flow)
   ${c.cyan("bivy secrets")}    list | set | ref | delete | doctor | resolve
   ${c.cyan("bivy voice")}      Configure speech-to-text: provider | key | remove | status
   ${c.cyan("bivy completions")} <bash|zsh|fish>  Print a shell completion script
@@ -4238,10 +4285,7 @@ async function main() {
   const [command, ...args] = argv;
   switch (command) {
     case undefined:
-      // First run opens the guided setup; after setup, bare `bivy` launches the
-      // default agent's native CLI/TUI as a managed, relay-visible `bivy run`.
-      if (fs.existsSync(cliConfigPath)) await cmdRun([]);
-      else await cmdSetup();
+      printHelp();
       break;
     case "setup":
     case "init":
@@ -4378,8 +4422,7 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
         console.log("Usage: bivy open\n\nOpen the remote web/PWA app in your browser (requires 'bivy relay:setup' first).");
         break;
       }
-      const config = loadConfig();
-      const remote = await openRemoteApp(config);
+      const remote = await openRemoteApp();
       if (!remote) {
         console.log("No remote access configured yet.");
         console.log(`Run ${c.cyan("bivy relay:setup")} to enable the web/PWA app, then ${c.cyan("bivy open")}.`);
@@ -4403,7 +4446,17 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "github:connect":
     case "connect-repo":
       if (args.includes("-h") || args.includes("--help")) {
-        console.log("Usage: bivy github:connect [owner/repo]\n\nAuthorize repo access for the repo picker via GitHub's device flow. The resulting repo-scoped token is stored in this node's encrypted local vault.");
+        console.log("Usage: bivy github:connect [owner/repo]\n\nOpen Settings → GitHub App in the remote app. Self-hosted deployments with BIVY_GITHUB_OAUTH_CLIENT_ID configured use GitHub's device flow instead.");
+        break;
+      }
+      if (!String(process.env.BIVY_GITHUB_OAUTH_CLIENT_ID || loadConfig().env?.BIVY_GITHUB_OAUTH_CLIENT_ID || "").trim()) {
+        const remote = await openRemoteApp({ remotePath: "/settings/github" });
+        if (!remote) {
+          console.log("Remote access is not configured yet.");
+          console.log(`Run ${c.cyan("bivy relay:setup")}, then connect GitHub in the app under Settings → GitHub App.`);
+        } else if (!canOpenBrowser()) {
+          console.log(`Open GitHub setup in the Bivy app: ${c.cyan(remote.openUrl)}`);
+        }
         break;
       }
       if (!(await ensureDeps())) process.exit(1);

package/dist/credential-ingest-cli.js

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Small setup-time entry point: normalize a native agent login into Bivy's
+// encrypted model credential vault without passing credential material on argv.
+import { ingestAgentCredentials } from "./runtime/credential-ingest.js";
+const [agentId, credsDir, piDir] = process.argv.slice(2);
+if (!agentId || !credsDir || !piDir)
+    process.exit(2);
+try {
+    const imported = await ingestAgentCredentials(agentId, credsDir, piDir);
+    process.exit(imported > 0 ? 0 : 3);
+}
+catch (error) {
+    if (process.env.BIVY_DEBUG)
+        console.error(error);
+    process.exit(1);
+}

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.3-staging.116",
+  "version": "0.8.3-staging.118",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",