@bivy/bivy 0.15.0-staging.4 → 0.15.0-staging.41

package/README.md

@@ -117,10 +117,16 @@ curl -fsSL https://bivy.sh/install.sh | bash
 
 macOS and Linux. Requires Node.js 20 or newer. The installer puts the
 [`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) npm package and the
-`bivy` command on your `PATH` with optional bridges skipped for speed, then runs the guided `bivy setup` wizard — agent
-choice, selected-agent install if needed, remote access, and an auto-start background service (launchd on macOS,
-systemd on Linux). Re-running it on a machine that already has Bivy just applies
-the latest build and restarts the service.
+`bivy` command on your `PATH` with optional bridges skipped for speed, then runs
+`bivy setup` — agent choice, selected-agent install if needed, remote access,
+and an auto-start background service (launchd on macOS, systemd on Linux).
+
+If Claude Code, Codex, OpenCode, Gemini, or another agent is already installed,
+setup says so and uses that existing CLI, login, and configuration. Bivy does
+not replace the agent or copy its native credentials; it adds remote continuity
+and governance around the agent you already use. Re-running the installer on a
+machine that already has Bivy just applies the latest build and restarts the
+service.
 
 **What needs an account, and what doesn't.** The CLI alone — `bivy run`,
 `bivy resume`, `bivy sessions` — needs no account and no server; `bivy setup`
@@ -131,11 +137,19 @@ UI needs a control plane, because the node hosts none: use the hosted one at
 [self-host your own](docs/self-host-quickstart.md). Switch any time with
 `bivy relay:setup`.
 
+Prefer to inspect the installer first?
+
+```bash
+curl -fsSL https://bivy.sh/install.sh -o install.sh
+less install.sh
+bash install.sh
+```
+
 **What the installer does with sudo.** It escalates only when it must, and
 tells you when it does:
 
-- Debian/Ubuntu without a suitable Node.js: `sudo apt-get install build-essential
-  python3 curl`, then NodeSource's Node 22 setup script via `sudo`.
+- Debian/Ubuntu without a suitable Node.js: `sudo apt-get install curl
+  ca-certificates`, then NodeSource's Node 22 setup script via `sudo`.
 - Other Linux, or macOS, without a suitable Node.js: downloads the official
   Node 22 tarball from nodejs.org (sha256-checked) and installs it under
   `/usr/local` with `sudo`.
@@ -267,9 +281,9 @@ See [`docs/remote-access.md`](docs/remote-access.md) and
 
 ## Supported agents
 
-**Claude Code and Codex are the recommended, release-certified paths.** The
-broader catalog stays available under **More agents**; capabilities and fidelity
-vary by runtime.
+**Bivy maintains wrappers for the popular coding agents below.** Claude Code,
+Codex, Pi, and OpenCode have the richest release-tested capability sets today;
+capabilities and fidelity still vary by runtime.
 
 | Agent | Command | Notes |
 |---|---|---|

package/bin/agent-manifest.json

@@ -6,7 +6,7 @@
       "command": "codex",
       "hidden": true,
       "supportTier": "supported",
-      "certification": "unverified",
+      "certification": "adapter-tested",
       "headlessFlags": [
         "exec"
       ],
@@ -37,7 +37,7 @@
       "label": "Aider",
       "command": "aider",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "--yes-always",
@@ -53,8 +53,8 @@
       "label": "Hermes",
       "command": "hermes",
       "hidden": true,
-      "supportTier": "beta",
-      "certification": "adapter-tested",
+      "supportTier": "experimental",
+      "certification": "unverified",
       "headlessFlags": [],
       "install": {
         "kind": "npm",
@@ -66,7 +66,7 @@
       "label": "Goose",
       "command": "goose",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "run",
@@ -87,7 +87,7 @@
       "label": "Gemini CLI",
       "command": "gemini",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "-p",
@@ -105,7 +105,7 @@
       "label": "Qwen Code",
       "command": "qwen",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "-p",
@@ -123,7 +123,7 @@
       "label": "Cline",
       "command": "cline",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "-y",
@@ -139,7 +139,7 @@
       "label": "Crush",
       "command": "crush",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "run",
@@ -155,7 +155,7 @@
       "label": "Cursor",
       "command": "cursor-agent",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "--force",
@@ -172,7 +172,7 @@
       "label": "GitHub Copilot",
       "command": "copilot",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "--allow-all-tools",
@@ -188,7 +188,7 @@
       "label": "Grok",
       "command": "grok",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "-p",
@@ -205,7 +205,7 @@
       "label": "Amp",
       "command": "amp",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "-x",
@@ -222,7 +222,7 @@
       "label": "Auggie",
       "command": "auggie",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "--quiet",
@@ -238,7 +238,7 @@
       "label": "Droid",
       "command": "droid",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "exec",
@@ -256,7 +256,7 @@
       "label": "Continue",
       "command": "cn",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "--auto",
@@ -272,7 +272,7 @@
       "label": "Kilo Code",
       "command": "kilo",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "run",
@@ -289,7 +289,7 @@
       "label": "Rovo Dev",
       "command": "acli",
       "hidden": false,
-      "supportTier": "beta",
+      "supportTier": "supported",
       "certification": "adapter-tested",
       "headlessFlags": [
         "rovodev",

package/bin/bivy.mjs

@@ -543,6 +543,11 @@ function commandExists(cmd) {
   return runQuiet("sh", ["-lc", "command -v -- \"$1\" >/dev/null 2>&1", "sh", cmd]).code === 0;
 }
 
+function commandOnPath(cmd) {
+  const result = runQuiet("sh", ["-lc", "command -v -- \"$1\"", "sh", cmd]);
+  return result.code === 0 ? result.stdout.trim().split(/\r?\n/)[0] || "" : "";
+}
+
 function npmGlobalBinCommand(cmd) {
   if (!commandExists("npm")) return "";
   const prefix = runQuiet("npm", ["prefix", "-g"]);
@@ -552,9 +557,13 @@ function npmGlobalBinCommand(cmd) {
   return fs.existsSync(candidate) ? candidate : "";
 }
 
+function nodeAtLeast(minMajor, minMinor = 0) {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  return major > minMajor || (major === minMajor && minor >= minMinor);
+}
+
 function hasSupportedNode() {
-  const [major] = process.versions.node.split(".").map(Number);
-  return major >= 20;
+  return nodeAtLeast(20);
 }
 
 async function ensureDeps() {
@@ -612,8 +621,15 @@ function nodePackageInstalled(packageName) {
   return runQuiet(nodeBin, ["-e", "require.resolve(process.argv[1], { paths: [process.argv[2]] })", packageName, repoRoot]).code === 0;
 }
 
+function nodePackageLoadable(packageName) {
+  return runQuiet(nodeBin, ["-e", "require(require.resolve(process.argv[1], { paths: [process.argv[2]] }))", packageName, repoRoot]).code === 0;
+}
+
 async function ensureNodePackage(packageName) {
-  if (nodePackageInstalled(packageName)) return true;
+  if (nodePackageInstalled(packageName)) {
+    console.log(c.green(`  ✓ Found Bivy bridge package ${packageName}`));
+    return true;
+  }
   // Add with the package manager that owns this tree. Running `npm install` in a
   // pnpm workspace would write a competing package-lock.json and a hoisted
   // node_modules over pnpm's symlink layout, leaving the checkout in a state
@@ -626,7 +642,7 @@ async function ensureNodePackage(packageName) {
     console.error(c.red(`${cmd} is required to install ${packageName}.`));
     return false;
   }
-  console.log(c.dim(`Installing ${packageName}…`));
+  console.log(c.dim(`Installing Bivy bridge package ${packageName}…`));
   const code = await run(cmd, [...baseArgs, packageName], { cwd: repoRoot });
   return code === 0 && nodePackageInstalled(packageName);
 }
@@ -634,13 +650,18 @@ async function ensureNodePackage(packageName) {
 const userLocalPrefix = process.env.BIVY_NPM_GLOBAL_PREFIX || path.join(os.homedir(), ".local");
 
 async function ensureNpmCommand(command, packageName, label) {
-  if (commandExists(command)) return true;
+  const existing = commandOnPath(command);
+  if (existing) {
+    console.log(c.green(`  ✓ Found existing ${label}: ${existing}`));
+    console.log(c.dim(`    Bivy will use your installed ${label}; it will not replace its auth or configuration.`));
+    return true;
+  }
   if (!commandExists("npm")) {
     console.log(c.yellow(`Skipping ${label}: npm is not available.`));
     return false;
   }
   fs.mkdirSync(path.join(userLocalPrefix, "bin"), { recursive: true });
-  console.log(c.dim(`Installing ${label} (${packageName})…`));
+  console.log(c.dim(`Installing ${label} (${packageName}) because it was not found on PATH…`));
   const code = await run("npm", ["install", "--global", "--prefix", userLocalPrefix, packageName, "--no-audit", "--no-fund"]);
   return code === 0 && commandExists(command);
 }
@@ -4121,6 +4142,14 @@ async function cmdDoctor(args = []) {
 
   console.log(c.bold("\n  Bivy doctor\n"));
   console.log(`  ${mark(hasSupportedNode())} Node ${process.version}${hasSupportedNode() ? "" : c.dim("  (needs >= 20.0.0)")}`);
+  const ptyInstalled = nodePackageInstalled("node-pty");
+  const ptyUsable = ptyInstalled && nodePackageLoadable("node-pty");
+  console.log(`  ${mark(ptyUsable, true)} terminal PTY ${ptyUsable ? c.green("available") : ptyInstalled ? c.yellow("installed but not loadable — reinstall after installing build tools") : c.dim("optional dependency missing — interactive terminals unavailable; chat/exec still work")}`);
+  const claudeBridge = nodePackageInstalled("@anthropic-ai/claude-agent-sdk");
+  console.log(`  ${mark(claudeBridge, true)} Claude bridge ${claudeBridge ? c.green("installed") : c.dim("optional — installed on first Claude setup/use")}`);
+  const piBridge = nodePackageInstalled("@earendil-works/pi-coding-agent");
+  const piNodeOk = nodeAtLeast(22, 19);
+  console.log(`  ${mark(piBridge && piNodeOk, true)} Pi bridge ${piBridge ? (piNodeOk ? c.green("installed") : c.yellow("installed but needs Node >=22.19")) : c.dim("optional — installed only if you choose Pi")}`);
   console.log(`  ${mark(commandExists("git"), true)} git${commandExists("git") ? "" : c.dim("  (recommended for repo-backed sessions)")}`);
   // GitHub is optional (a "No repo" session needs none), so this only ever warns.
   // `gh` is NOT required — it's a token fallback; the primary path is Bivy's own
@@ -5091,8 +5120,10 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
       }
       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")}.`);
+        console.log(c.yellow("Remote access is not configured on this machine yet."));
+        console.log("The local node hosts only an API/WebSocket, not the Bivy PWA.");
+        console.log(`Run ${c.cyan("bivy relay:setup")} to connect this node to the hosted or self-hosted remote web/PWA app, then run ${c.cyan("bivy open")} again.`);
+        process.exitCode = 1;
       } else if (!canOpenBrowser()) {
         console.log(`Open the Bivy app here: ${c.cyan(remote.remoteBase)}`);
       }

package/dist/agents/pi/capabilities.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import { withExactCapabilitySurface } from "../../runtime/types.js";
+/**
+ * The ONE capability table for Pi, shared by the real `PiRuntime` and the
+ * `LazyPiRuntime` facade the registry hands out before the SDK is loaded.
+ *
+ * This module deliberately imports nothing from the pi SDK so the lazy facade
+ * can use it without defeating its purpose. Keeping a single source of truth is
+ * a correctness requirement, not tidiness: the daemon reads flags such as
+ * `sessionRefIsPath` off whichever runtime object the registry returns — the
+ * facade — *before* any session is opened. When the facade's copy of this table
+ * drifted from the real one and lost `sessionRefIsPath`, the daemon treated every
+ * pi resume ref as an opaque id, stripped the transcript path to its basename,
+ * and pi created a brand-new empty session for every message sent to a closed
+ * chat (the "sending to a closed session creates a new one" regression).
+ */
+export const PI_CAPABILITIES = withExactCapabilitySurface({
+    toolInterception: true,
+    modelSelection: true,
+    packages: true,
+    resume: true,
+    fork: false,
+    // pi resumes by session-file path (under the node's sessions dir), so the
+    // daemon applies its path-traversal guard to these refs.
+    sessionRefIsPath: true,
+    // pi's TUI ships with the node, so the chat<->TUI hand-off is always offered.
+    interactiveTui: true,
+    usageReporting: true,
+    // pi can find a prior on-disk session by cwd + start time, so a `bivy run`
+    // terminal with no pinned sessionId can still be continued as a governed chat.
+    sessionDiscovery: true,
+    // pi transcripts are structured messages that round-trip through the session
+    // store, so a pi->pi fork is full fidelity (see exportForFork/importForFork).
+    forkTransport: true,
+    // pi can also stand up a session from portable {role,text} history, so a fork
+    // FROM another agent INTO pi is a true replay, not a seeded summary.
+    forkHistoryImport: true,
+    // The pi-coding-agent SDK implements both explicitly: prompting mid-turn
+    // with no streamingBehavior hint throws, forcing every caller to choose.
+    streamingBehaviors: ["steer", "followUp"],
+});

package/dist/agents/pi/integration.js

@@ -4,19 +4,8 @@ import { spawnSync } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import { defineAgentIntegration } from "../definition.js";
-import { withExactCapabilitySurface } from "../../runtime/types.js";
+import { PI_CAPABILITIES } from "./capabilities.js";
 export const PI_TESTED_VERSION = "0.84.3";
-const PI_CAPABILITIES = withExactCapabilitySurface({
-    toolInterception: true,
-    modelSelection: true,
-    packages: true,
-    resume: true,
-    fork: false,
-    interactiveTui: true,
-    usageReporting: true,
-    sessionDiscovery: true,
-    streamingBehaviors: ["steer", "followUp"],
-});
 export function piAgentDir() {
     return process.env.PI_CODING_AGENT_DIR?.trim() || path.join(os.homedir(), ".pi", "agent");
 }
@@ -40,6 +29,15 @@ export function piCommandAvailable() {
 export function invalidatePiCommandProbe() {
     PI_COMMAND_CACHE.clear();
 }
+export function piBridgeInstalled() {
+    try {
+        import.meta.resolve("@earendil-works/pi-coding-agent");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function unsupportedNodeMessage() {
     return `Pi requires Node.js 22.19+ (found ${process.version}). Upgrade Node, or select another agent such as Claude Code/Codex/OpenCode.`;
 }
@@ -87,13 +85,15 @@ export function piIntegration(origin) {
         visible: true,
         origin,
         describe: () => {
-            const installed = piCommandAvailable();
+            const commandInstalled = piCommandAvailable();
+            const bridgeInstalled = piBridgeInstalled();
+            const installed = commandInstalled && bridgeInstalled && nodeSupportsPi();
             return {
                 id: "pi",
                 executionMode: "protocol",
                 displayName: "Pi",
                 description: "The operator-installed Pi coding agent connected to Bivy for durable sessions, governance, packages, and model selection.",
-                status: installed && nodeSupportsPi() ? "available" : "external",
+                status: installed ? "available" : "external",
                 packageName: "@earendil-works/pi-coding-agent",
                 language: "TypeScript",
                 capabilities: PI_CAPABILITIES,
@@ -105,7 +105,9 @@ export function piIntegration(origin) {
                     ? unsupportedNodeMessage()
                     : installed
                         ? "Uses the Pi command and agent-owned auth/configuration already on this node, and hands sessions back to that native TUI."
-                        : "Install and sign in to Pi on this node; Bivy will connect to that existing agent.",
+                        : commandInstalled
+                            ? "Pi is on PATH, but Bivy's optional Pi bridge is not installed. Select Pi in setup or run 'bivy agents:install'."
+                            : "Install and sign in to Pi on this node; Bivy will connect to that existing agent.",
                 install: installed ? undefined : {
                     label: "Install Pi",
                     description: "Installs the upstream Pi coding agent on this node.",
@@ -116,6 +118,8 @@ export function piIntegration(origin) {
         create: (options) => {
             if (!piCommandAvailable())
                 throw new Error(`Pi command not found on PATH: ${piCommand()}`);
+            if (!piBridgeInstalled())
+                throw new Error("Bivy's optional Pi bridge is not installed. Run 'bivy setup' and choose Pi, or run 'bivy agents:install'.");
             // Vault-backed credentials (see catalogRuntimes): the daemon-hosted Pi
             // session reads the shared vault the user signed in to, not Pi's own
             // plaintext auth.json. The agent dir still supplies config/models/packages.

package/dist/agents/pi/runtime.js

@@ -15,7 +15,7 @@ import { toModelInfo as sharedToModelInfo } from "../../runtime/normalize.js";
 import { provisionPiAuthJson } from "../../runtime/credential-provisioning.js";
 import { isNativeOAuthProvider } from "../../runtime/oauth/model-oauth-providers.js";
 import { bivySessionEnv } from "../../runtime/session-env.js";
-import { withExactCapabilitySurface } from "../../runtime/types.js";
+import { PI_CAPABILITIES } from "./capabilities.js";
 import { mapToolCall, mapToolResult } from "../../runtime/tool-call-map.js";
 import { BackgroundShellTracker, createBackgroundAwareBashOperations } from "./background-shell.js";
 /**
@@ -406,28 +406,9 @@ export class PiRuntime {
     options;
     id = "pi";
     displayName = "Pi";
-    capabilities = withExactCapabilitySurface({
-        toolInterception: true,
-        modelSelection: true,
-        packages: true,
-        resume: true,
-        fork: false,
-        // pi resumes by session-file path (under the node's sessions dir), so the
-        // daemon applies its path-traversal guard to these refs.
-        sessionRefIsPath: true,
-        // pi's TUI ships with the node, so the chat<->TUI hand-off is always offered.
-        interactiveTui: true,
-        usageReporting: true,
-        // pi transcripts are structured messages that round-trip through the session
-        // store, so a pi->pi fork is full fidelity (see exportForFork/importForFork).
-        forkTransport: true,
-        // pi can also stand up a session from portable {role,text} history, so a fork
-        // FROM another agent INTO pi is a true replay, not a seeded summary.
-        forkHistoryImport: true,
-        // The pi-coding-agent SDK implements both explicitly: prompting mid-turn
-        // with no streamingBehavior hint throws, forcing every caller to choose.
-        streamingBehaviors: ["steer", "followUp"],
-    });
+    // Shared with LazyPiRuntime (the facade the registry actually hands out) —
+    // see capabilities.ts for why the two must never drift.
+    capabilities = PI_CAPABILITIES;
     constructor(options) {
         this.options = options;
     }

package/dist/agents/profiles.js

@@ -82,7 +82,7 @@ export const AGENT_PROFILES = {
         // git-aware turn and exits instead of dropping into the REPL.
         args: ["--yes-always", "--message"],
         promptMode: "argv",
-        supportTier: "beta",
+        supportTier: "supported",
         authOwner: "mixed",
         blurb: "Popular git-native pair-programming agent (Aider).",
         // `aider --model <id> …` — a leading option (insertAt: 0). Aider resolves its
@@ -116,6 +116,7 @@ export const AGENT_PROFILES = {
         // Hidden from the picker: dumb-pipe adapter with no validated JSON parser or
         // documented session/resume flag (still runnable via BIVY_RUNTIME=hermes).
         hidden: true,
+        supportTier: "experimental",
         // No `resume`: no documented session/resume flag.
         install: { kind: "npm", pkg: "hermes-agent" },
     },
@@ -137,7 +138,7 @@ export const AGENT_PROFILES = {
         // BIVY_GOOSE_ACP=1 (or global BIVY_PREFER_ACP=1); off by default until validated.
         acp: { args: ["acp"] },
         promptMode: "argv",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Block's open-source agent with a structured stream-json protocol (Goose).",
         // Homebrew isn't present on stock Linux nodes (brew → ENOENT); the official
         // download script installs the goose binary on both Linux and macOS.
@@ -154,7 +155,7 @@ export const AGENT_PROFILES = {
         displayName: "Gemini CLI",
         command: "gemini",
         packageName: "@google/gemini-cli",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Google's terminal coding agent (Gemini CLI).",
         // `gemini -m <id> … -p "<prompt>"` — a leading option before the trailing `-p`
         // (insertAt: 0). The prompt flag stays last, so prepending is safe.
@@ -197,7 +198,7 @@ export const AGENT_PROFILES = {
         displayName: "Qwen Code",
         command: "qwen",
         packageName: "@qwen-code/qwen-code",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Alibaba's Qwen Code CLI (a Gemini-CLI fork tuned for Qwen-Coder models).",
         // Gemini-CLI fork: same `-m <id> … -p` model flag (insertAt: 0).
         model: {
@@ -241,7 +242,7 @@ export const AGENT_PROFILES = {
         displayName: "Cline",
         command: "cline",
         packageName: "cline",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Cline's standalone terminal agent (the CLI sibling of the Cline IDE extension).",
         // `cline -y "<prompt>"` runs one autonomous, non-interactive task (‑y/‑‑yolo
         // skips per-tool prompts so a piped run doesn't wedge on approval). Bivy's
@@ -264,7 +265,7 @@ export const AGENT_PROFILES = {
         displayName: "Crush",
         command: "crush",
         packageName: "@charmland/crush",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Charm's glamourous open-source coding agent (Crush).",
         // `crush run "<prompt>"` runs a single non-interactive prompt and exits;
         // `-q/--quiet` suppresses the spinner UI so stdout is just the reply.
@@ -285,7 +286,7 @@ export const AGENT_PROFILES = {
         displayName: "Cursor",
         command: "cursor-agent",
         packageName: "cursor (curl https://cursor.com/install)",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Cursor's standalone terminal coding agent (cursor-agent) — the editor's engine on the CLI.",
         // `cursor-agent --force -p "<prompt>"` runs one non-interactive print turn and
         // exits (`-p/--print`); `--force` auto-approves tool/command execution so a
@@ -320,7 +321,7 @@ export const AGENT_PROFILES = {
         displayName: "GitHub Copilot",
         command: "copilot",
         packageName: "@github/copilot",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "GitHub's official terminal coding agent (Copilot CLI).",
         // `copilot --allow-all-tools -p "<prompt>"` runs one programmatic turn and
         // exits; --allow-all-tools skips per-tool approval so a piped run doesn't
@@ -352,7 +353,7 @@ export const AGENT_PROFILES = {
         behaviors: { preflight: "grok", prepare: "grok-auth", nativeSessions: "grok" },
         command: "grok",
         packageName: "grok (curl -fsSL https://x.ai/cli/install.sh | bash)",
-        supportTier: "beta",
+        supportTier: "supported",
         authOwner: "mixed",
         blurb: "xAI's official Grok coding agent (Grok CLI) — SuperGrok/X subscription or API key.",
         // Official CLI: `grok -p "<prompt>"` (alias `--single`) runs one headless
@@ -392,7 +393,7 @@ export const AGENT_PROFILES = {
         displayName: "Amp",
         command: "amp",
         packageName: "@sourcegraph/amp",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Sourcegraph's autonomous coding agent with persistent threads (Amp).",
         // `amp -x "<prompt>"` (`--execute`) runs one thread turn and streams to stdout;
         // Amp doesn't gate tools per-run (governed by its own allowlist config), so no
@@ -414,7 +415,7 @@ export const AGENT_PROFILES = {
         displayName: "Auggie",
         command: "auggie",
         packageName: "@augmentcode/auggie",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Augment Code's terminal agent backed by its codebase context engine (Auggie).",
         // `auggie --quiet --print "<prompt>"` runs one non-interactive turn and prints
         // the final reply (`--print`); `--quiet` drops the UI chatter. Prompt trails.
@@ -428,7 +429,7 @@ export const AGENT_PROFILES = {
         displayName: "Droid",
         command: "droid",
         packageName: "droid (curl https://app.factory.ai/cli)",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Factory AI's autonomous terminal coding agent (Droid).",
         // `droid exec --auto high "<prompt>"` runs one headless task at high autonomy
         // (auto-approves) and streams to stdout. Prompt trails the `exec` subcommand.
@@ -456,7 +457,7 @@ export const AGENT_PROFILES = {
         displayName: "Continue",
         command: "cn",
         packageName: "@continuedev/cli",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Continue's headless terminal agent (cn) driving configurable assistants.",
         // `cn --auto -p "<prompt>"` runs one headless turn (`-p` = no TUI) and prints
         // the final response; `--auto` allows all tools without prompting. Prompt
@@ -484,7 +485,7 @@ export const AGENT_PROFILES = {
         displayName: "Kilo Code",
         command: "kilo",
         packageName: "@kilocode/cli",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Kilo Code's terminal CLI (an OpenCode fork) for pipeline-friendly agentic coding.",
         // `kilo run --auto "<prompt>"` runs one non-interactive turn (`run`) with
         // auto-approved permissions (`--auto`) and streams to stdout. Prompt trails.
@@ -518,7 +519,7 @@ export const AGENT_PROFILES = {
         displayName: "Rovo Dev",
         command: "acli",
         packageName: "atlassian acli (rovodev)",
-        supportTier: "beta",
+        supportTier: "supported",
         blurb: "Atlassian's Rovo Dev terminal coding agent, run through the acli CLI.",
         // `acli rovodev run --yolo "<prompt>"` runs one instruction headlessly; --yolo
         // skips tool-approval prompts. Prompt trails the `rovodev run` subcommand.

package/dist/certification/index.js

@@ -3,9 +3,11 @@ export function certificationEntry(id) {
     return CERTIFICATION_MATRIX.agents.find((entry) => entry.id === id);
 }
 /**
- * The paid Supported promise is derived from certification, never merely copied
- * from a profile. A suspended/missing entry, wrong adapter mode, stale pin, or
- * missing required runtime capability is downgraded to Beta in the picker.
+ * Supported means Bivy maintains a wrapper for this integration. Certification is
+ * a separate fidelity signal: an active matrix entry verifies the richer release-
+ * tested capability set for a pinned adapter version, while drift or a different
+ * configured path keeps the wrapper Supported but marks the capability surface as
+ * adapter-tested instead of release-tested.
  */
 export function applyCertification(runtime) {
     if (runtime.supportTier !== "supported")
@@ -18,9 +20,8 @@ export function applyCertification(runtime) {
     if (!eligible) {
         return {
             ...runtime,
-            supportTier: "beta",
-            certification: "adapter-tested",
-            notes: `${runtime.notes ? `${runtime.notes} ` : ""}This configured path is not the release-certified execution mode.`,
+            certification: runtime.certification ?? "adapter-tested",
+            notes: `${runtime.notes ? `${runtime.notes} ` : ""}This wrapper is maintained by Bivy; its current configured path is adapter-tested rather than release-tested.`,
         };
     }
     return { ...runtime, certification: "release-tested", testedVersion: entry.pinnedVersion };

package/dist/linear-tasks.js

@@ -34,7 +34,7 @@ export function linearBranchName(identifier) {
     const slug = identifier.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
     return `bivy/linear-${slug || "issue"}`;
 }
-export function buildLinearTaskPrompt(issue) {
+export function buildLinearTaskPrompt(issue, instructions) {
     return [
         `You are working on Linear issue ${issue.identifier}: ${issue.title}`,
         "",
@@ -42,8 +42,8 @@ export function buildLinearTaskPrompt(issue) {
         "",
         issue.url ? `Issue: ${issue.url}` : "",
         "",
-        "Understand the issue and surrounding codebase, implement it completely, and run the project's tests, linter, and type-checker.",
+        instructions?.trim() || "Understand the issue and surrounding codebase, implement it completely, and run the project's tests, linter, and type-checker.",
         "",
-        `When finished, commit and push your changes and open a pull request yourself. Include a link to ${issue.identifier} in the pull request description.`,
+        instructions?.trim() ? "" : `When finished, commit and push your changes and open a pull request yourself. Include a link to ${issue.identifier} in the pull request description.`,
     ].filter((part, index, all) => part !== "" || all[index - 1] !== "").join("\n");
 }

package/dist/metadata.js

@@ -103,7 +103,14 @@ export class MetadataStore {
         const prev = this.data.sessions[input.id];
         const createdAt = input.createdAt ?? prev?.createdAt ?? nowIso();
         const updatedAt = input.updatedAt ?? nowIso();
-        this.data.sessions[input.id] = { ...prev, ...input, createdAt, updatedAt };
+        // Runtime adapters do not all expose the same resume fields. In particular,
+        // an adapter can temporarily have no sessionFile while it is being rebuilt.
+        // Do not let that partial snapshot erase the durable resume ref (or any
+        // other field) already recorded for the session. The old object spread did
+        // exactly that: `{ path: undefined }` replaced the Pi transcript path, so
+        // reopening the saved row fell through to a fresh session.
+        const defined = Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+        this.data.sessions[input.id] = { ...prev, ...defined, createdAt, updatedAt };
         this.save();
     }
     touchSession(id, status) {

package/dist/runtime/auth-errors.js

@@ -77,3 +77,12 @@ export function authProviderForSession(runtimeId, modelProvider) {
         return provider;
     return undefined;
 }
+/** Convert a provider failure into the safe wire shape consumed by clients.
+ * Raw provider text can contain stack frames, paths, or tokens and must never
+ * be used as the user-facing auth error. */
+export function classifyModelAuthError(raw, runtimeId, modelProvider) {
+    if (!isModelAuthError(raw))
+        return null;
+    const provider = authProviderForSession(runtimeId, modelProvider);
+    return provider ? { kind: "model_auth", provider } : null;
+}

package/dist/runtime/index.js

@@ -277,8 +277,8 @@ export function cliAgentManifest() {
             label: spec.displayName,
             command: spec.command,
             hidden: Boolean(spec.hidden),
-            supportTier: spec.supportTier ?? "beta",
-            certification: spec.testedVersion ? "release-tested" : (spec.supportTier ?? "beta") === "beta" ? "adapter-tested" : "unverified",
+            supportTier: spec.supportTier ?? "supported",
+            certification: spec.testedVersion ? "release-tested" : (spec.supportTier ?? "supported") === "supported" || (spec.supportTier ?? "supported") === "beta" ? "adapter-tested" : "unverified",
             ...(spec.testedVersion ? { testedVersion: spec.testedVersion } : {}),
             headlessFlags: [...headless].filter((a) => !a.includes("{")),
             install: spec.install ?? null,
@@ -1015,7 +1015,7 @@ function runtimeCertification(runtime) {
         };
     if (runtime.testedVersion)
         return { certification: "release-tested", testedVersion: runtime.testedVersion };
-    return { certification: runtime.supportTier === "beta" ? "adapter-tested" : "unverified" };
+    return { certification: runtime.supportTier === "supported" || runtime.supportTier === "beta" ? "adapter-tested" : "unverified" };
 }
 function runtimeProtection(runtime) {
     // Native SDK/CLI sandboxes receive the requested read-only/workspace/full tier

package/dist/server.js

@@ -34,7 +34,7 @@ import { InMemoryLocationRegistry } from "./runtime/location-registry.js";
 import { ControlPlaneSessionLocationRegistry, LayeredSessionLocationRegistry } from "./runtime/control-plane-location.js";
 import { attachAdoptedSessions, classifyAttachFailure } from "./runtime/adoption.js";
 import { createCredentialStore, testProviderCredential } from "./runtime/credentials.js";
-import { isModelAuthError, authProviderForSession } from "./runtime/auth-errors.js";
+import { isModelAuthError, authProviderForSession, classifyModelAuthError } from "./runtime/auth-errors.js";
 import { createCredentialVault, migrateVaultDir } from "./runtime/credential-store.js";
 import { probeAnthropicAccess } from "./runtime/anthropic-preflight.js";
 import { createSessionNamer, fallbackSessionName } from "./session/session-namer.js";
@@ -930,6 +930,7 @@ function harnessDirFor(record) {
 function harnessBeginTurn(record) {
     const dir = harnessDirFor(record);
     record.harnessTurnReady = undefined;
+    record.harnessTurnFinished = false;
     if (!dir)
         return;
     const previous = record.workspaceState === "dirty" ? "dirty" : "clean";
@@ -954,6 +955,14 @@ function harnessBeginTurn(record) {
     })();
 }
 /** After a turn, snapshot again and broadcast the structured diff it produced. */
+function finishHarnessTurn(record) {
+    if (record.harnessTurnFinished)
+        return;
+    record.harnessTurnFinished = true;
+    void harnessEndTurn(record).finally(() => {
+        void replication.onTurnComplete(record.id);
+    });
+}
 async function harnessEndTurn(record) {
     const previous = record.workspaceState === "dirty" ? "dirty" : "clean";
     try {
@@ -1643,11 +1652,14 @@ function stampSessionEvent(payload) {
     return payload;
 }
 // Collapse the burst of assistant `message_update`s (one per agent stdout line,
-// each carrying the FULL text so far) into ~1 fan-out per tick. See
-// session-event-coalescer.ts for the rationale (kills the O(n^2) re-serialize).
+// each carrying the FULL text so far) to a human-smooth 4 fps. A 16 ms window
+// still allowed up to 62 cumulative snapshots/second, making a long answer
+// quadratic and surprisingly expensive over a phone's relay connection. The
+// latest snapshot supersedes every skipped one, and non-update events flush it
+// immediately, so 250 ms changes neither final content nor event ordering.
 // The coalescer's emit stamps the surviving (latest) update, so only ~one seq is
-// spent per tick — the ring holds turn-scale events, not every stdout line.
-const SESSION_UPDATE_COALESCE_MS = 16;
+// spent per window — the ring holds turn-scale events, not every stdout line.
+const SESSION_UPDATE_COALESCE_MS = 250;
 const sessionEvents = new SessionEventCoalescer({
     coalesceMs: SESSION_UPDATE_COALESCE_MS,
     emit: (payload) => broadcastCoalesced(stampSessionEvent(payload)),
@@ -2842,7 +2854,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: actionableAgentError(record.runtimeId, error) });
+            broadcast({ type: "session.error", sessionId: record.id, error: sessionAgentError(record, error) });
         });
     },
     async "session.new"(msg) {
@@ -4212,7 +4224,7 @@ async function runIssueTaskInner(cfg, issue, source, overrides = {}) {
     try {
         recordRunAuditCorrelation(record, overrides.correlation);
         emit(record, "started", `Started work on ${cfg.owner}/${cfg.repo}#${issue.number}.`);
-        await runSessionTurn(record, buildTaskPrompt(issue, nodeGithubIssuePrompt()), overrides.signal);
+        await runSessionTurn(record, buildTaskPrompt(issue, overrides.instructions ?? nodeGithubIssuePrompt()), overrides.signal);
         if (overrides.signal?.aborted)
             throw overrides.signal.reason ?? new Error("Run cancelled");
         emit(record, "agent_done", `Agent finished issue #${issue.number}; running deterministic checks.`);
@@ -4918,6 +4930,7 @@ async function runWorkItem(item, report, signal) {
             sandbox: normalizeSandboxTier(item.sandbox),
             approvalMode: approvalModeFrom(item.approvalMode),
             onEvidence: report,
+            instructions: item.body,
             signal,
             correlation: { runId: item.id, attempt: item.attempt ?? 1, machineId: identity.nodeId },
         });
@@ -4938,7 +4951,7 @@ async function runWorkItem(item, report, signal) {
             throw new Error(`Linear work item has an invalid repo "${repoSlug}"`);
         // Case B: a re-dispatch the control plane correlated to an existing session
         // continues it as a normal chat instead of starting cold (mirrors GitHub).
-        if (await continueCorrelatedSession(item, buildLinearTaskPrompt(issue), report, { resumeOnMissing: item.targetKind === "existing_session", signal }))
+        if (await continueCorrelatedSession(item, buildLinearTaskPrompt(issue, item.body), report, { resumeOnMissing: item.targetKind === "existing_session", signal }))
             return;
         const githubToken = await resolveGitHubToken();
         if (!githubToken)
@@ -4965,7 +4978,7 @@ async function runWorkItem(item, report, signal) {
             catch { }
         }
         await report({ output: { sessionId: record.id, branch }, events: [{ at: new Date().toISOString(), kind: "branch", summary: "Linear issue working branch and session created.", ref: branch, url: issue.url }] });
-        await runSessionTurn(record, buildLinearTaskPrompt(issue), signal);
+        await runSessionTurn(record, buildLinearTaskPrompt(issue, item.body), signal);
         if (signal.aborted)
             throw signal.reason ?? new Error("Run cancelled");
         await branchPublish.maybePushWorktreeBranch(record);
@@ -5958,6 +5971,7 @@ async function sessionListRows() {
             agent: meta?.runtimeId ?? s.agent,
             agentName: meta?.agentName ?? s.agentName,
             source: rec?.source ?? meta?.source,
+            bivyCreated: Boolean(meta),
             forkedFrom: rec?.forkedFrom ?? meta?.forkedFrom,
             branch: rec?.worktree?.branch ?? meta?.branch,
             sandbox: rec?.sandbox ?? normalizeSandboxTier(meta?.sandbox),
@@ -7174,6 +7188,11 @@ function actionableAgentError(runtimeId, error) {
     }
     return raw;
 }
+function sessionAgentError(record, error) {
+    const raw = humanizeAgentError(error instanceof Error ? error.message : String(error));
+    return classifyModelAuthError(raw, record.runtimeId, record.session.getCurrentModel()?.provider)
+        ?? actionableAgentError(record.runtimeId, error);
+}
 /**
  * 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
@@ -7230,7 +7249,7 @@ function attachSessionListeners(record) {
             policy: sessionRunPolicy,
             onNotice: (n) => broadcast({ type: "session.notice", sessionId: record.id, level: n.level, message: n.message }),
             onModelChanged: () => broadcast({ type: "model.updated", sessionId: record.id, model: publicModel(record.session.getCurrentModel(), record.session.getCurrentModel()) }),
-            onFailed: (message) => broadcast({ type: "session.error", sessionId: record.id, error: message }),
+            onFailed: (message) => broadcast({ type: "session.error", sessionId: record.id, error: sessionAgentError(record, message) }),
         });
     }
     record.unsubscribe = record.session.subscribe((event) => {
@@ -7327,9 +7346,14 @@ function attachSessionListeners(record) {
             transcripts.resolveInlineImages(record);
         }
         // Durably persist the throttled sidecars at the turn boundary so a crash
-        // loses at most the in-flight turn's UI detail, not the whole turn.
-        if (event.type === "turn_end")
+        // loses at most the in-flight turn's UI detail, not the whole turn. A
+        // runtime may keep its agent process alive and never emit agent_end (Pi),
+        // so turn_end is also authoritative for the interactive working state.
+        if (event.type === "turn_end") {
             eventLog.flush(record.id);
+            clearSessionWorking(record);
+            finishHarnessTurn(record);
+        }
         // AskUserQuestion is intercepted and answered by the daemon's guardian /
         // QuestionManager (see guardianInterceptor), which broadcasts
         // session.question(.resolved) from its own listeners — runtimes no longer
@@ -7364,14 +7388,9 @@ function attachSessionListeners(record) {
             transcripts.clearLiveIntermediate(record.id);
             clearSessionWorking(record);
             void refreshSessionUsage(record);
-            // Snapshot the worktree and broadcast the structured diff this turn made —
-            // universal edit review + rewind target, for every runtime.
-            // Warm-replicate this turn to the standby AFTER the checkpoint is committed
-            // (so the shipped frame carries this turn's transcript AND its checkpoint).
-            // Gated on session sync — inert by default.
-            void harnessEndTurn(record).finally(() => {
-                void replication.onTurnComplete(record.id);
-            });
+            // Snapshot/diff at whichever completion boundary arrived first. Pi keeps
+            // its process alive after turn_end; other runtimes also emit agent_end.
+            finishHarnessTurn(record);
             // A turn that ended in a terminal model/provider error (e.g. an expired
             // credential or a 4xx from the API) otherwise vanished: working cleared,
             // no reply, no signal. Surface it as a session-scoped error so the client
@@ -7433,7 +7452,7 @@ function attachSessionListeners(record) {
                 scheduleAdvertise();
                 broadcast({ type: "session.failed", sessionId: record.id, failedAt: record.lastFailureAt });
                 if (messageError)
-                    broadcast({ type: "session.error", sessionId: record.id, error: actionableAgentError(record.runtimeId, messageError) });
+                    broadcast({ type: "session.error", sessionId: record.id, error: sessionAgentError(record, 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, turnError);
@@ -8057,7 +8076,7 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
     void refreshSessionUsage(record);
     if (makeActive)
         active = record;
-    broadcast({ type: "session.created", sessionId, name: record.session.getName(), workspace: sessionWorkspace, sessionFile: record.sessionFile, source: record.source, branch: worktree?.branch, prUrl: record.prUrl, runtimeId: rt.id, agentName: rt.displayName, modelFallbackMessage, bivySession: bivySessionEnvelope(record), capabilities: capabilitiesWithCommands(rt.id, record.session) });
+    broadcast({ type: "session.created", sessionId, name: record.session.getName(), workspace: sessionWorkspace, sessionFile: record.sessionFile, source: record.source, bivyCreated: true, branch: worktree?.branch, prUrl: record.prUrl, runtimeId: rt.id, agentName: rt.displayName, modelFallbackMessage, bivySession: bivySessionEnvelope(record), capabilities: capabilitiesWithCommands(rt.id, record.session) });
     void maybeNotifyBivyUpdate();
     scheduleAdvertise();
     return record;
@@ -8074,6 +8093,12 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
  * of the same session onto one promise fixes both.
  */
 const resumingSessions = new Map();
+// Keep an id index as well as the resolved runtime ref. A prompt can arrive
+// while session.open is still resolving and may not carry the session's path;
+// without this index it cannot discover the in-flight open from metadata and
+// is incorrectly reported as "Session not found". Both commands must join the
+// same resume operation by the identity the client actually supplied.
+const resumingSessionsById = new Map();
 /**
  * Resolve the session a client command targets, resuming it from durable
  * metadata when it isn't currently held in memory. A session survives being
@@ -8096,6 +8121,9 @@ async function resolveOrResumeSession(sessionId, sessionPath) {
     const open = openSessions.get(id);
     if (open)
         return open;
+    const byId = resumingSessionsById.get(id);
+    if (byId)
+        return byId;
     const pathRef = typeof sessionPath === "string" && sessionPath.trim() ? sessionPath.trim() : undefined;
     const meta = metadata.getSession(id) ?? (pathRef ? metadata.getSession(pathRef) : undefined);
     // A run that only kept its terminal log has nothing to resume — it opens as a
@@ -8151,15 +8179,23 @@ async function resolveOrResumeSession(sessionId, sessionPath) {
         }
     }
     const inflight = resumingSessions.get(key);
-    if (inflight)
+    if (inflight) {
+        resumingSessionsById.set(id, inflight);
         return inflight;
+    }
     const resume = createSession(defaultWorkspace, ref, { runtimeId, makeActive: false });
     resumingSessions.set(key, resume);
+    resumingSessionsById.set(id, resume);
     try {
         return await resume;
     }
     finally {
         resumingSessions.delete(key);
+        // Only delete our promise. A future implementation may replace an entry
+        // after a failed resume, and must not have its newer attempt removed by an
+        // older finally block.
+        if (resumingSessionsById.get(id) === resume)
+            resumingSessionsById.delete(id);
     }
 }
 // Enumerating a runtime's models needs a live session (the model registry lives
@@ -9835,6 +9871,7 @@ app.get("/api/sessions", async (_req, res, next) => {
                 agent: meta?.runtimeId ?? s.agent,
                 agentName: meta?.agentName ?? s.agentName,
                 source: rec?.source ?? meta?.source,
+                bivyCreated: Boolean(meta),
                 forkedFrom: rec?.forkedFrom ?? meta?.forkedFrom,
                 branch: rec?.worktree?.branch ?? meta?.branch,
                 prUrl: rec?.prUrl ?? meta?.prUrl,
@@ -9856,7 +9893,18 @@ app.get("/api/sessions", async (_req, res, next) => {
 });
 app.post("/api/sessions/open", async (req, res, next) => {
     try {
-        const session = await createSession(defaultWorkspace, String(req.body?.path ?? ""), { runtimeId: agentFrom(req.body ?? {}) });
+        // Direct transports use this endpoint for both opening a saved session and
+        // the legacy path-only open flow.  The old path-only implementation ignored
+        // sessionId, so a direct client sending into a closed chat opened a brand-new
+        // session instead of reopening the selected conversation.
+        const requestedId = typeof req.body?.sessionId === "string" && req.body.sessionId.trim()
+            ? req.body.sessionId.trim()
+            : undefined;
+        const session = requestedId
+            ? await resolveOrResumeSession(requestedId, req.body?.path)
+            : await createSession(defaultWorkspace, String(req.body?.path ?? ""), { runtimeId: agentFrom(req.body ?? {}) });
+        if (!session)
+            return res.status(404).json({ error: "Session not found" });
         res.json({
             id: session.id,
             workspace: session.workspace,

package/dist/session/session-contract-values.js

@@ -104,7 +104,7 @@ export function resolveSessionContract(input) {
     };
     const supportTier = input.supportTier ?? "experimental";
     const hasProtectionDegradation = degradedReasons.some((r) => PROTECTION_AREAS.has(r.area));
-    const requiresAcknowledgement = supportTier === "supported" && hasProtectionDegradation && !input.acknowledgedAt;
+    const requiresAcknowledgement = input.certification === "release-tested" && hasProtectionDegradation && !input.acknowledgedAt;
     return {
         schemaVersion: SESSION_CONTRACT_SCHEMA_VERSION,
         resolvedAt: input.now,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.15.0-staging.4",
+  "version": "0.15.0-staging.41",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -66,6 +66,6 @@
     "nanoid": "3.3.18",
     "undici": "8.10.0"
   },
-  "readme": "# Bivy\n\n[![npm](https://img.shields.io/npm/v/@bivy/bivy?color=2b6cb0&label=%40bivy%2Fbivy)](https://www.npmjs.com/package/@bivy/bivy)\n[![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-2b6cb0)](LICENSE)\n[![node](https://img.shields.io/badge/node-%E2%89%A520-2b6cb0)](https://nodejs.org)\n\n**Run coding agents on the machines you already own — then reach them from your\nphone, browser, or another terminal.**\n\nStart Claude Code on your workstation, right where the repo, the running dev\nserver, and the staging database already live. Walk away. On the train, open\nyour phone: read what the agent did, answer its question, approve the migration\n— over a link only your devices can decrypt. The work never left your machine.\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash   # install + guided setup\ncd your-repo\nbivy run claude                                 # start an agent where your work lives\nbivy open                                        # pick it up from your phone or browser\n```\n\nFirst thing to try: ask the agent to explain the repository, make one small safe\nchange, then open the same Session in the web app or on your phone while it runs.\n\n**[Quickstart](docs/quickstart.md)** ·\n**[Docs](docs/README.md)** ·\n**[Why Bivy](docs/why-bivy.md)** ·\n**[Security model](docs/security-model.md)** ·\n**[bivy.sh](https://bivy.sh)**\n\n> **0.x software.** The core loop is solid and used daily. Interfaces and\n> cross-runtime fidelity still change between releases — check the\n> [runtime support matrix](docs/runtime-support-matrix.md) before you depend on\n> a specific agent capability.\n\n## Why not just a cloud sandbox?\n\nA hosted sandbox starts from an *approximation* of your environment. A Bivy\nMachine **is** your environment — the actual working tree, the services already\nrunning, the caches already warm.\n\n|  | Cloud sandbox | Bivy Machine |\n|---|---|---|\n| Your repository | a cloned copy | the real working tree, uncommitted changes and all |\n| Dev server & database | mocked, or absent | already running, right beside the agent |\n| Private networks & internal APIs | out of reach | reachable |\n| Toolchains, package caches | cold, reinstalled each time | warm, already installed |\n| GPUs / local inference | rented separately | the ones on your box |\n| Where your code sits | someone else's infrastructure | the machine you already trust |\n\nYou keep the environment. Bivy adds the part that was missing: **reaching that\nenvironment from anywhere, and leaving it working while you're gone.**\n\n## What you can do\n\nBivy gives you two ways to put an agent to work.\n\n### Sessions — interactive, and portable\n\nStart an agent, watch it work, jump in to steer, stop, or approve. Then leave\nyour desk and keep going:\n\n```bash\nbivy run claude              # or codex, pi, gemini, and a dozen more\nbivy open                    # continue the same session in the browser or PWA\nbivy resume                  # pick it back up in the terminal\nbivy run claude --no-follow  # start it in the background instead of attaching\nbivy run claude --chat       # start the governed app session and open it in the browser\n```\n\n- **Reconnect from anywhere** — phone, browser, or another terminal — to the\n  same live Session. The PWA adds voice input, read-aloud, phone-to-agent\n  file/image uploads, and agent-to-phone attachments.\n- **Move work without starting over.** Import existing Claude Code and Codex\n  Sessions, or fork, copy, and move a Bivy Session to another agent, model, or\n  Machine.\n- **Run more than one Machine** — a workstation, a private-network server, a GPU\n  box — on one account, and pick the environment each Session needs.\n\n### Runs — unattended, and accountable\n\nQueue one on demand, or let an event kick it off — either way it returns\nimmediately and reports back:\n\n```bash\nbivy runs start \"...\"    # queue a one-off unattended Run, then `bivy runs wait <id>`\nbivy automation init     # or define governed jobs in .bivy/automations.yaml\n```\n\n- **Trigger from real events** — a failed CI job, a GitHub or Linear issue,\n  Slack, a schedule, or a signed webhook.\n- **Pin the guardrails** — Machine, agent, model, sandbox, approval mode, and a\n  hard attempt ceiling — right next to the job.\n- **Get a Receipt** — every Run reports the checks it ran and how it turned out,\n  not just a wall of output.\n\nTry the [capability recipes](docs/capability-recipes.md) to see each of these\nend to end, or the [runtime support matrix](docs/runtime-support-matrix.md) for\nexactly what each agent supports.\n\n## Bring your own stack\n\nUse provider subscriptions through native agent logins, API keys stored in\nBivy's vault, or local / OpenAI-compatible inference. Claude Code, Codex, and Pi\nhave first-class SDK integrations; any other ACP or headless agent needs no\nadapter at all — it's a data row you add with one command:\n\n```bash\nbivy agent add       # register an existing ACP or process agent\n```\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nmacOS and Linux. Requires Node.js 20 or newer. The installer puts the\n[`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) npm package and the\n`bivy` command on your `PATH` with optional bridges skipped for speed, then runs the guided `bivy setup` wizard — agent\nchoice, selected-agent install if needed, remote access, and an auto-start background service (launchd on macOS,\nsystemd on Linux). Re-running it on a machine that already has Bivy just applies\nthe latest build and restarts the service.\n\n**What needs an account, and what doesn't.** The CLI alone — `bivy run`,\n`bivy resume`, `bivy sessions` — needs no account and no server; `bivy setup`\nlets you pick **local only for now** and skip remote access. A browser or phone\nUI needs a control plane, because the node hosts none: use the hosted one at\n`app.bivy.sh` (sign in with GitHub or email; free tier plus a paid plan — see\n[bivy.sh#pricing](https://bivy.sh#pricing)) or\n[self-host your own](docs/self-host-quickstart.md). Switch any time with\n`bivy relay:setup`.\n\n**What the installer does with sudo.** It escalates only when it must, and\ntells you when it does:\n\n- Debian/Ubuntu without a suitable Node.js: `sudo apt-get install build-essential\n  python3 curl`, then NodeSource's Node 22 setup script via `sudo`.\n- Other Linux, or macOS, without a suitable Node.js: downloads the official\n  Node 22 tarball from nodejs.org (sha256-checked) and installs it under\n  `/usr/local` with `sudo`.\n- If npm's global prefix isn't writable it falls back to `~/.local` — it never\n  runs `npm install` under `sudo`.\n- It appends a marked PATH block to `~/.bashrc` or `~/.zshrc`\n  (`BIVY_NO_RC_UPDATE=1` to opt out).\n\nWant no sudo at all? Bring your own Node.js 20+ and skip the script:\n\n```bash\nnpm install -g @bivy/bivy && bivy setup     # install globally\nnpx @bivy/bivy setup                         # or try it once, no install\n```\n\nReleases are published from CI with provenance attestations; verify a build's\norigin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).\n\n### Your first session\n\nOnce `bivy setup` finishes, use Bivy from inside an existing repo. The first win\nis simple: start the local agent, give it a real task in that environment, then\nreopen the same Session from another surface.\n\n```bash\ncd your-repo\nbivy run claude    # start an agent as a durable session in the current repo\n# Try: \"Explain this repo and suggest one small, safe improvement.\"\nbivy open          # open that same session in the web app (needs relay setup)\nbivy resume        # or pick it back up here in the terminal\n```\n\nFrom here the [quickstart](docs/quickstart.md) walks through Runs, multiple\nMachines, and automations.\n\n### Install options\n\nEnvironment variables passed to the one-line installer change what it does:\n\n| Goal | Variable |\n|---|---|\n| Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |\n| Pin an exact version | `BIVY_VERSION=0.1.0` |\n| Install the npm package into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |\n| Install optional Bivy bridges/native terminal dependency up front | `BIVY_INSTALL_OPTIONAL_DEPS=1` |\n| Don't touch `~/.bashrc` / `~/.zshrc`; print the PATH line instead | `BIVY_NO_RC_UPDATE=1` |\n\nFor example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.\n\nWorking from a checkout of this repository instead:\n\n```bash\npnpm install\npnpm run setup\n```\n\nSee [`docs/install.md`](docs/install.md) for where data lives, service\nmanagement, and uninstall.\n\n## Updating\n\n```bash\nbivy update\n```\n\n`bivy update` detects how Bivy was installed and does the right thing, then\nwaits for any active session to finish its current turn and restarts the\nbackground service so the node reconnects on the new build:\n\n| Install kind | What `bivy update` does |\n|---|---|\n| npm global (`npm i -g`) | `npm install -g @bivy/bivy@<channel>`, then restart the service |\n| installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |\n| git checkout | `git pull --ff-only` + `pnpm install --frozen-lockfile`, then restart |\n| `npx` run | nothing to update — each run already fetches the latest |\n\nUpdates follow the release **channel** recorded at install time — `latest`\n(production) by default, or `staging` if you installed with\n`BIVY_CHANNEL=staging`. Switch channels (the choice is remembered for next\ntime), or skip the wait for a busy session:\n\n```bash\nbivy update --staging   # move to the dev channel\nbivy update --stable    # move back to production (latest)\nbivy update --force     # don't wait for an in-flight turn to finish\n```\n\nThe daemon also checks the registry periodically and posts an in-session notice\nwhen a newer build is available.\n\n## Architecture\n\nBivy has three parts. **Only the first one holds your data.**\n\n```text\n  your machine                     hosted or self-hosted\n\n  ┌──────────────┐               ┌─────────┐        ┌───────────────┐\n  │ node daemon  │  ──dials──▶   │  relay  │ ◀────▶ │ control plane │\n  │ agents, keys │    outbound   │ opaque  │        │ accounts, web │\n  │ repo, tools  │               │ frames  │        │ app, metadata │\n  └──────────────┘               └─────────┘        └───────────────┘\n         ▲                                                  ▲\n         └────────── end-to-end encrypted session ───────────┘\n                     phone · browser · another terminal\n```\n\n- **Node** — a daemon on your machine. Owns the workspace, credentials, and agent\n  processes. Serves an API and WebSocket on `http://localhost:4317` plus a\n  `/healthz` probe. **It hosts no web UI.**\n- **Relay** — forwards encrypted frames between your node and your devices. Your\n  node dials out, so no inbound port is opened. The relay cannot read the frames.\n- **Control plane** — holds your account, node registry, and session index, and\n  serves the web/PWA client. Use the hosted one or run your own.\n\nBecause the node serves no UI, a browser or phone needs a control plane — hosted\nat `app.bivy.sh`, or one you deploy yourself. The terminal CLI needs neither.\nInteractive Session traffic is end-to-end encrypted between a Machine and its\npaired devices: the relay never sees plaintext and cannot decrypt it. Who can\n*authorize* a device depends on how you pair — with a QR / `bivy link` pairing,\nor on a self-hosted deployment, the control plane can't read your Sessions\neither; with hosted account sign-in you trust the control plane to authorize\ndevices and to serve the web app that holds the keys. See\n[known limitations](docs/security-model.md#known-limitations-for-0x).\n\nSee [`docs/remote-access.md`](docs/remote-access.md) and\n[`docs/security-model.md`](docs/security-model.md).\n\n## Supported agents\n\n**Claude Code and Codex are the recommended, release-certified paths.** The\nbroader catalog stays available under **More agents**; capabilities and fidelity\nvary by runtime.\n\n| Agent | Command | Notes |\n|---|---|---|\n| Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |\n| Codex | `bivy run codex` | Installs `@openai/codex` |\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\n| OpenCode | `bivy run opencode` | Installs `opencode-ai` |\n| Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |\n| Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |\n| Goose | `bivy run goose` | Requires `goose` on PATH |\n| Aider | `bivy run aider` | No session resume (upstream gap) |\n| Cline | `bivy run cline` | Installs `cline` |\n| Crush | `bivy run crush` | No session resume (upstream gap) |\n| Cursor | `bivy run cursor` | ACP-capable |\n| GitHub Copilot | `bivy run copilot` | ACP-capable |\n| Grok | `bivy run grok` | Model selection |\n| Amp | `bivy run amp` | Native thread resume |\n| Auggie | `bivy run auggie` | Headless CLI |\n| Droid | `bivy run droid` | Model selection |\n| Continue | `bivy run continue` | Headless CLI |\n| Kilo Code | `bivy run kilocode` | ACP-capable |\n| Rovo Dev | `bivy run rovodev` | Installed out of band |\n\nAlso defined but hidden from the picker as *Experimental* — runnable via\n`BIVY_RUNTIME=<id>`: Codebuff (`codebuff`, no verified headless mode upstream\nyet), Hermes (`hermes`, generic process adapter), and OpenClaw (`openclaw`,\nCLI adapter only, no resume yet).\n\nAny other command works via `bivy run -- ./your-agent --flags`. ACP-capable\nagents can be promoted to Bivy's governed protocol path for per-tool approvals\nand native resume. To add a reusable process or ACP agent to both the CLI and web\npicker without changing Bivy, run `bivy agent add`, or scaffold and install a\ndeclarative [plugin manifest](docs/plugins.md) with `bivy plugin init`\n(declarative plugins are Experimental, `v1alpha1`, and run out of process).\n\n[`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly\nwhat each agent supports — resume, model selection, approvals, sandboxing.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run claude       # launch Claude Code as a durable session\nbivy run codex        # run a different agent\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires relay setup)\nbivy automation init  # create .bivy/automations.yaml\nbivy agent add        # connect an existing ACP or process agent\nbivy plugin list      # installed declarative integration packages\nbivy status           # config summary and node reachability\nbivy doctor           # health check\nbivy logs -f          # tail node logs\nbivy update           # update Bivy and restart the service\n```\n\nFull command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).\n\n## Configuration\n\nThe common knobs:\n\n```bash\nBIVY_WORKSPACE=/path/to/repo    # default workspace\nBIVY_SANDBOX=read-only          # read-only | workspace-write (default) | danger-full-access\nBIVY_APPROVAL_MODE=risky        # never | risky | always | autonomous (default)\n```\n\nCreate and inspect the typed node configuration, or add repository-owned\nsafety/check/retry policy:\n\n```bash\nbivy config init\nbivy config set defaults.agent codex\nbivy config explain defaults.sandbox\nbivy config init --project       # .bivy/policy.yaml\n```\n\nSee [`docs/config-as-code.md`](docs/config-as-code.md). Every environment\nvariable and precedence rule lives in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**: agents act without per-action\nprompts. How much that actually protects you depends on the runtime. Native-sandbox\nagents enforce the chosen access tier; structured runtimes also pass tool calls\nthrough Bivy's policy and approval layer. Process agents that Bivy cannot\nintercept run with your OS user permissions — the picker flags this and requires\nconfirmation before you pick that path.\n\nWhere Bivy receives structured shell/file calls, a heuristic floor blocks known\ncatastrophic commands and structured writes outside the workspace, and a\nbackstop set (force-push, publish, deploy, sudo) pauses for a human. This catches\naccidents; **it is not an adversarial isolation boundary.**\n\nWant to be asked about more? Set the mode explicitly:\n\n```bash\nBIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits\nBIVY_APPROVAL_MODE=always   # prompt on all shell commands and file edits\nBIVY_APPROVAL_MODE=never    # no prompts; structured-tool heuristic blocks still apply where available\n```\n\nApprove from the terminal, browser, or phone.\n\nSandbox tiers (`read-only`, `workspace-write`, `danger-full-access`) are enforced\nnatively by agents that support them — Codex, Claude Code, Gemini CLI, Qwen Code.\nAgents without a native sandbox may expose structured tool or MCP controls, but\nthose don't cover activity the agent performs outside those channels; some\nprocess adapters run entirely with your user permissions. Check the picker's\nProtection label. **Bivy does not currently ship its own OS-level jail.**\n\n## Credentials\n\nInteractive prompts, transcripts, and workspace files stay encrypted across the\nrelay. Credentials can remain on a Machine or in a vault you control:\n\n```bash\nbivy secrets list\nbivy secrets set github.repo-token\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\nbivy secrets doctor\n```\n\n`secret://`, `env://`, and `op://` (1Password) references resolve on demand when\nthe daemon provisions an agent run, so raw values never sit in your config.\n\n**One deliberate exception to relay blindness:** if you explicitly enable hosted\nunattended provisioning, Bivy Cloud may store encrypted cloud, repository,\nmodel, or key-escrow material that the service can technically access. Treat this\nas an explicit hosted-custody mode. See the\n[security model](docs/security-model.md#what-the-control-plane-sees) and\n[`docs/key-management.md`](docs/key-management.md).\n\n## Automations as code\n\nDefine governed jobs in `.bivy/automations.yaml`, validate them, and simulate\ntrigger events locally before applying anything:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nInstructions are encrypted on the applying node before upload. Safety policy\nlives beside the job — sandbox, approval mode, and a hard attempt ceiling that\nretry/fallback rules cannot exceed. See\n[`docs/automations-as-code.md`](docs/automations-as-code.md).\n\n## GitHub Runs\n\nLabel an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the\nBivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an\nisolated worktree, executes configured checks, and reports an explicit outcome.\n\nCore applies no commercial usage limits. Bivy Cloud billing and commercial\npolicy live in the separate Cloud repository.\n\nA private GitHub App only installs on the account that owns it, so connect one\napp per GitHub account — one for your personal repos, one per organization\n(`bivy github:app-create --org <org>`). A node can serve several at once, each\nwith its own key and `@`-mention handle.\n\nSee [`docs/github-work-queue.md`](docs/github-work-queue.md).\n\n## Linear Runs\n\nApply `bivy` or `bivy/<machine>` to a Linear issue to create a Run on the selected\nMachine. The Machine fetches issue content directly from Linear, works in an\nisolated GitHub worktree, and asks the agent to open a pull request. See\n[`docs/linear-work-queue.md`](docs/linear-work-queue.md).\n\n## Development\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server (proxies /api and /ws to the node)\n```\n\nChecks — all of these run in CI:\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nRepository layout:\n\n- `src/` — node daemon, runtime adapters, approvals, secrets, sessions\n- `bin/` — the `bivy` CLI\n- `packages/core` — shared protocol, pairing, wire format\n- `packages/web` — the React/Vite PWA client (`@bivy/web`)\n- `services/relay` — self-hostable relay\n- `services/control-plane` — self-hostable control plane\n- `deploy/` — self-host deployment examples\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Self-hosting\n\nNode, relay, and control plane are all in this repository. Point a node at your\nown deployment by passing URLs to `bivy relay:setup` — re-running it switches an\nexisting node over to the new endpoints:\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nEach URL has a flag and an environment-variable equivalent (the flag wins):\n\n| Flag | Environment variable | Points at | Default |\n|---|---|---|---|\n| `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |\n| `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |\n| `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |\n\nSign-in defaults to GitHub device login (`--github`); pass\n`--email you@example.com` for an email magic-link, or `--session-token <token>`\nto skip interactive sign-in. `relay:setup` checks the control plane is reachable,\nenrolls this node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,\n`bivy link`, and `bivy update` all keep using your deployment afterwards.\n\n**Self-hosting is community-supported** — no SLA, best-effort help via GitHub\nissues. You own TLS, backups, upgrades, and hardening. Start with the\none-command VPS path in\n[`docs/self-host-quickstart.md`](docs/self-host-quickstart.md); the ops\nreference (backups, rotation, security boundary) is\n[`docs/self-host.md`](docs/self-host.md).\n\n## Security\n\nReport vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).\nPlease don't open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,\nresponse times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)\nfor the trust model and known limitations.\n\n## License\n\nBivy Core is free and open-source software under the GNU Affero General Public\nLicense, version 3.0 only (AGPL-3.0-only). You may use, study, modify, and\nself-host it under that license. If you modify Bivy and let users interact with\nit over a network, section 13 requires you to offer them the corresponding\nsource code. See [`LICENSE`](LICENSE).\n\n**Where the open-core line is.** Everything in this repository — node, CLI,\nrelay, control plane, and the web/PWA client — is AGPL Core, with no usage\nlimits. **Bivy Cloud** is the hosted operation of that stack plus billing and\nplans, and lives in a separate private repository. Contributions are accepted\nunder the [DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
+  "readme": "# Bivy\n\n[![npm](https://img.shields.io/npm/v/@bivy/bivy?color=2b6cb0&label=%40bivy%2Fbivy)](https://www.npmjs.com/package/@bivy/bivy)\n[![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-2b6cb0)](LICENSE)\n[![node](https://img.shields.io/badge/node-%E2%89%A520-2b6cb0)](https://nodejs.org)\n\n**Run coding agents on the machines you already own — then reach them from your\nphone, browser, or another terminal.**\n\nStart Claude Code on your workstation, right where the repo, the running dev\nserver, and the staging database already live. Walk away. On the train, open\nyour phone: read what the agent did, answer its question, approve the migration\n— over a link only your devices can decrypt. The work never left your machine.\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash   # install + guided setup\ncd your-repo\nbivy run claude                                 # start an agent where your work lives\nbivy open                                        # pick it up from your phone or browser\n```\n\nFirst thing to try: ask the agent to explain the repository, make one small safe\nchange, then open the same Session in the web app or on your phone while it runs.\n\n**[Quickstart](docs/quickstart.md)** ·\n**[Docs](docs/README.md)** ·\n**[Why Bivy](docs/why-bivy.md)** ·\n**[Security model](docs/security-model.md)** ·\n**[bivy.sh](https://bivy.sh)**\n\n> **0.x software.** The core loop is solid and used daily. Interfaces and\n> cross-runtime fidelity still change between releases — check the\n> [runtime support matrix](docs/runtime-support-matrix.md) before you depend on\n> a specific agent capability.\n\n## Why not just a cloud sandbox?\n\nA hosted sandbox starts from an *approximation* of your environment. A Bivy\nMachine **is** your environment — the actual working tree, the services already\nrunning, the caches already warm.\n\n|  | Cloud sandbox | Bivy Machine |\n|---|---|---|\n| Your repository | a cloned copy | the real working tree, uncommitted changes and all |\n| Dev server & database | mocked, or absent | already running, right beside the agent |\n| Private networks & internal APIs | out of reach | reachable |\n| Toolchains, package caches | cold, reinstalled each time | warm, already installed |\n| GPUs / local inference | rented separately | the ones on your box |\n| Where your code sits | someone else's infrastructure | the machine you already trust |\n\nYou keep the environment. Bivy adds the part that was missing: **reaching that\nenvironment from anywhere, and leaving it working while you're gone.**\n\n## What you can do\n\nBivy gives you two ways to put an agent to work.\n\n### Sessions — interactive, and portable\n\nStart an agent, watch it work, jump in to steer, stop, or approve. Then leave\nyour desk and keep going:\n\n```bash\nbivy run claude              # or codex, pi, gemini, and a dozen more\nbivy open                    # continue the same session in the browser or PWA\nbivy resume                  # pick it back up in the terminal\nbivy run claude --no-follow  # start it in the background instead of attaching\nbivy run claude --chat       # start the governed app session and open it in the browser\n```\n\n- **Reconnect from anywhere** — phone, browser, or another terminal — to the\n  same live Session. The PWA adds voice input, read-aloud, phone-to-agent\n  file/image uploads, and agent-to-phone attachments.\n- **Move work without starting over.** Import existing Claude Code and Codex\n  Sessions, or fork, copy, and move a Bivy Session to another agent, model, or\n  Machine.\n- **Run more than one Machine** — a workstation, a private-network server, a GPU\n  box — on one account, and pick the environment each Session needs.\n\n### Runs — unattended, and accountable\n\nQueue one on demand, or let an event kick it off — either way it returns\nimmediately and reports back:\n\n```bash\nbivy runs start \"...\"    # queue a one-off unattended Run, then `bivy runs wait <id>`\nbivy automation init     # or define governed jobs in .bivy/automations.yaml\n```\n\n- **Trigger from real events** — a failed CI job, a GitHub or Linear issue,\n  Slack, a schedule, or a signed webhook.\n- **Pin the guardrails** — Machine, agent, model, sandbox, approval mode, and a\n  hard attempt ceiling — right next to the job.\n- **Get a Receipt** — every Run reports the checks it ran and how it turned out,\n  not just a wall of output.\n\nTry the [capability recipes](docs/capability-recipes.md) to see each of these\nend to end, or the [runtime support matrix](docs/runtime-support-matrix.md) for\nexactly what each agent supports.\n\n## Bring your own stack\n\nUse provider subscriptions through native agent logins, API keys stored in\nBivy's vault, or local / OpenAI-compatible inference. Claude Code, Codex, and Pi\nhave first-class SDK integrations; any other ACP or headless agent needs no\nadapter at all — it's a data row you add with one command:\n\n```bash\nbivy agent add       # register an existing ACP or process agent\n```\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nmacOS and Linux. Requires Node.js 20 or newer. The installer puts the\n[`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) npm package and the\n`bivy` command on your `PATH` with optional bridges skipped for speed, then runs\n`bivy setup` — agent choice, selected-agent install if needed, remote access,\nand an auto-start background service (launchd on macOS, systemd on Linux).\n\nIf Claude Code, Codex, OpenCode, Gemini, or another agent is already installed,\nsetup says so and uses that existing CLI, login, and configuration. Bivy does\nnot replace the agent or copy its native credentials; it adds remote continuity\nand governance around the agent you already use. Re-running the installer on a\nmachine that already has Bivy just applies the latest build and restarts the\nservice.\n\n**What needs an account, and what doesn't.** The CLI alone — `bivy run`,\n`bivy resume`, `bivy sessions` — needs no account and no server; `bivy setup`\nlets you pick **local only for now** and skip remote access. A browser or phone\nUI needs a control plane, because the node hosts none: use the hosted one at\n`app.bivy.sh` (sign in with GitHub or email; free tier plus a paid plan — see\n[bivy.sh#pricing](https://bivy.sh#pricing)) or\n[self-host your own](docs/self-host-quickstart.md). Switch any time with\n`bivy relay:setup`.\n\nPrefer to inspect the installer first?\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh -o install.sh\nless install.sh\nbash install.sh\n```\n\n**What the installer does with sudo.** It escalates only when it must, and\ntells you when it does:\n\n- Debian/Ubuntu without a suitable Node.js: `sudo apt-get install curl\n  ca-certificates`, then NodeSource's Node 22 setup script via `sudo`.\n- Other Linux, or macOS, without a suitable Node.js: downloads the official\n  Node 22 tarball from nodejs.org (sha256-checked) and installs it under\n  `/usr/local` with `sudo`.\n- If npm's global prefix isn't writable it falls back to `~/.local` — it never\n  runs `npm install` under `sudo`.\n- It appends a marked PATH block to `~/.bashrc` or `~/.zshrc`\n  (`BIVY_NO_RC_UPDATE=1` to opt out).\n\nWant no sudo at all? Bring your own Node.js 20+ and skip the script:\n\n```bash\nnpm install -g @bivy/bivy && bivy setup     # install globally\nnpx @bivy/bivy setup                         # or try it once, no install\n```\n\nReleases are published from CI with provenance attestations; verify a build's\norigin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).\n\n### Your first session\n\nOnce `bivy setup` finishes, use Bivy from inside an existing repo. The first win\nis simple: start the local agent, give it a real task in that environment, then\nreopen the same Session from another surface.\n\n```bash\ncd your-repo\nbivy run claude    # start an agent as a durable session in the current repo\n# Try: \"Explain this repo and suggest one small, safe improvement.\"\nbivy open          # open that same session in the web app (needs relay setup)\nbivy resume        # or pick it back up here in the terminal\n```\n\nFrom here the [quickstart](docs/quickstart.md) walks through Runs, multiple\nMachines, and automations.\n\n### Install options\n\nEnvironment variables passed to the one-line installer change what it does:\n\n| Goal | Variable |\n|---|---|\n| Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |\n| Pin an exact version | `BIVY_VERSION=0.1.0` |\n| Install the npm package into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |\n| Install optional Bivy bridges/native terminal dependency up front | `BIVY_INSTALL_OPTIONAL_DEPS=1` |\n| Don't touch `~/.bashrc` / `~/.zshrc`; print the PATH line instead | `BIVY_NO_RC_UPDATE=1` |\n\nFor example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.\n\nWorking from a checkout of this repository instead:\n\n```bash\npnpm install\npnpm run setup\n```\n\nSee [`docs/install.md`](docs/install.md) for where data lives, service\nmanagement, and uninstall.\n\n## Updating\n\n```bash\nbivy update\n```\n\n`bivy update` detects how Bivy was installed and does the right thing, then\nwaits for any active session to finish its current turn and restarts the\nbackground service so the node reconnects on the new build:\n\n| Install kind | What `bivy update` does |\n|---|---|\n| npm global (`npm i -g`) | `npm install -g @bivy/bivy@<channel>`, then restart the service |\n| installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |\n| git checkout | `git pull --ff-only` + `pnpm install --frozen-lockfile`, then restart |\n| `npx` run | nothing to update — each run already fetches the latest |\n\nUpdates follow the release **channel** recorded at install time — `latest`\n(production) by default, or `staging` if you installed with\n`BIVY_CHANNEL=staging`. Switch channels (the choice is remembered for next\ntime), or skip the wait for a busy session:\n\n```bash\nbivy update --staging   # move to the dev channel\nbivy update --stable    # move back to production (latest)\nbivy update --force     # don't wait for an in-flight turn to finish\n```\n\nThe daemon also checks the registry periodically and posts an in-session notice\nwhen a newer build is available.\n\n## Architecture\n\nBivy has three parts. **Only the first one holds your data.**\n\n```text\n  your machine                     hosted or self-hosted\n\n  ┌──────────────┐               ┌─────────┐        ┌───────────────┐\n  │ node daemon  │  ──dials──▶   │  relay  │ ◀────▶ │ control plane │\n  │ agents, keys │    outbound   │ opaque  │        │ accounts, web │\n  │ repo, tools  │               │ frames  │        │ app, metadata │\n  └──────────────┘               └─────────┘        └───────────────┘\n         ▲                                                  ▲\n         └────────── end-to-end encrypted session ───────────┘\n                     phone · browser · another terminal\n```\n\n- **Node** — a daemon on your machine. Owns the workspace, credentials, and agent\n  processes. Serves an API and WebSocket on `http://localhost:4317` plus a\n  `/healthz` probe. **It hosts no web UI.**\n- **Relay** — forwards encrypted frames between your node and your devices. Your\n  node dials out, so no inbound port is opened. The relay cannot read the frames.\n- **Control plane** — holds your account, node registry, and session index, and\n  serves the web/PWA client. Use the hosted one or run your own.\n\nBecause the node serves no UI, a browser or phone needs a control plane — hosted\nat `app.bivy.sh`, or one you deploy yourself. The terminal CLI needs neither.\nInteractive Session traffic is end-to-end encrypted between a Machine and its\npaired devices: the relay never sees plaintext and cannot decrypt it. Who can\n*authorize* a device depends on how you pair — with a QR / `bivy link` pairing,\nor on a self-hosted deployment, the control plane can't read your Sessions\neither; with hosted account sign-in you trust the control plane to authorize\ndevices and to serve the web app that holds the keys. See\n[known limitations](docs/security-model.md#known-limitations-for-0x).\n\nSee [`docs/remote-access.md`](docs/remote-access.md) and\n[`docs/security-model.md`](docs/security-model.md).\n\n## Supported agents\n\n**Bivy maintains wrappers for the popular coding agents below.** Claude Code,\nCodex, Pi, and OpenCode have the richest release-tested capability sets today;\ncapabilities and fidelity still vary by runtime.\n\n| Agent | Command | Notes |\n|---|---|---|\n| Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |\n| Codex | `bivy run codex` | Installs `@openai/codex` |\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\n| OpenCode | `bivy run opencode` | Installs `opencode-ai` |\n| Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |\n| Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |\n| Goose | `bivy run goose` | Requires `goose` on PATH |\n| Aider | `bivy run aider` | No session resume (upstream gap) |\n| Cline | `bivy run cline` | Installs `cline` |\n| Crush | `bivy run crush` | No session resume (upstream gap) |\n| Cursor | `bivy run cursor` | ACP-capable |\n| GitHub Copilot | `bivy run copilot` | ACP-capable |\n| Grok | `bivy run grok` | Model selection |\n| Amp | `bivy run amp` | Native thread resume |\n| Auggie | `bivy run auggie` | Headless CLI |\n| Droid | `bivy run droid` | Model selection |\n| Continue | `bivy run continue` | Headless CLI |\n| Kilo Code | `bivy run kilocode` | ACP-capable |\n| Rovo Dev | `bivy run rovodev` | Installed out of band |\n\nAlso defined but hidden from the picker as *Experimental* — runnable via\n`BIVY_RUNTIME=<id>`: Codebuff (`codebuff`, no verified headless mode upstream\nyet), Hermes (`hermes`, generic process adapter), and OpenClaw (`openclaw`,\nCLI adapter only, no resume yet).\n\nAny other command works via `bivy run -- ./your-agent --flags`. ACP-capable\nagents can be promoted to Bivy's governed protocol path for per-tool approvals\nand native resume. To add a reusable process or ACP agent to both the CLI and web\npicker without changing Bivy, run `bivy agent add`, or scaffold and install a\ndeclarative [plugin manifest](docs/plugins.md) with `bivy plugin init`\n(declarative plugins are Experimental, `v1alpha1`, and run out of process).\n\n[`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly\nwhat each agent supports — resume, model selection, approvals, sandboxing.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run claude       # launch Claude Code as a durable session\nbivy run codex        # run a different agent\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires relay setup)\nbivy automation init  # create .bivy/automations.yaml\nbivy agent add        # connect an existing ACP or process agent\nbivy plugin list      # installed declarative integration packages\nbivy status           # config summary and node reachability\nbivy doctor           # health check\nbivy logs -f          # tail node logs\nbivy update           # update Bivy and restart the service\n```\n\nFull command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).\n\n## Configuration\n\nThe common knobs:\n\n```bash\nBIVY_WORKSPACE=/path/to/repo    # default workspace\nBIVY_SANDBOX=read-only          # read-only | workspace-write (default) | danger-full-access\nBIVY_APPROVAL_MODE=risky        # never | risky | always | autonomous (default)\n```\n\nCreate and inspect the typed node configuration, or add repository-owned\nsafety/check/retry policy:\n\n```bash\nbivy config init\nbivy config set defaults.agent codex\nbivy config explain defaults.sandbox\nbivy config init --project       # .bivy/policy.yaml\n```\n\nSee [`docs/config-as-code.md`](docs/config-as-code.md). Every environment\nvariable and precedence rule lives in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**: agents act without per-action\nprompts. How much that actually protects you depends on the runtime. Native-sandbox\nagents enforce the chosen access tier; structured runtimes also pass tool calls\nthrough Bivy's policy and approval layer. Process agents that Bivy cannot\nintercept run with your OS user permissions — the picker flags this and requires\nconfirmation before you pick that path.\n\nWhere Bivy receives structured shell/file calls, a heuristic floor blocks known\ncatastrophic commands and structured writes outside the workspace, and a\nbackstop set (force-push, publish, deploy, sudo) pauses for a human. This catches\naccidents; **it is not an adversarial isolation boundary.**\n\nWant to be asked about more? Set the mode explicitly:\n\n```bash\nBIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits\nBIVY_APPROVAL_MODE=always   # prompt on all shell commands and file edits\nBIVY_APPROVAL_MODE=never    # no prompts; structured-tool heuristic blocks still apply where available\n```\n\nApprove from the terminal, browser, or phone.\n\nSandbox tiers (`read-only`, `workspace-write`, `danger-full-access`) are enforced\nnatively by agents that support them — Codex, Claude Code, Gemini CLI, Qwen Code.\nAgents without a native sandbox may expose structured tool or MCP controls, but\nthose don't cover activity the agent performs outside those channels; some\nprocess adapters run entirely with your user permissions. Check the picker's\nProtection label. **Bivy does not currently ship its own OS-level jail.**\n\n## Credentials\n\nInteractive prompts, transcripts, and workspace files stay encrypted across the\nrelay. Credentials can remain on a Machine or in a vault you control:\n\n```bash\nbivy secrets list\nbivy secrets set github.repo-token\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\nbivy secrets doctor\n```\n\n`secret://`, `env://`, and `op://` (1Password) references resolve on demand when\nthe daemon provisions an agent run, so raw values never sit in your config.\n\n**One deliberate exception to relay blindness:** if you explicitly enable hosted\nunattended provisioning, Bivy Cloud may store encrypted cloud, repository,\nmodel, or key-escrow material that the service can technically access. Treat this\nas an explicit hosted-custody mode. See the\n[security model](docs/security-model.md#what-the-control-plane-sees) and\n[`docs/key-management.md`](docs/key-management.md).\n\n## Automations as code\n\nDefine governed jobs in `.bivy/automations.yaml`, validate them, and simulate\ntrigger events locally before applying anything:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nInstructions are encrypted on the applying node before upload. Safety policy\nlives beside the job — sandbox, approval mode, and a hard attempt ceiling that\nretry/fallback rules cannot exceed. See\n[`docs/automations-as-code.md`](docs/automations-as-code.md).\n\n## GitHub Runs\n\nLabel an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the\nBivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an\nisolated worktree, executes configured checks, and reports an explicit outcome.\n\nCore applies no commercial usage limits. Bivy Cloud billing and commercial\npolicy live in the separate Cloud repository.\n\nA private GitHub App only installs on the account that owns it, so connect one\napp per GitHub account — one for your personal repos, one per organization\n(`bivy github:app-create --org <org>`). A node can serve several at once, each\nwith its own key and `@`-mention handle.\n\nSee [`docs/github-work-queue.md`](docs/github-work-queue.md).\n\n## Linear Runs\n\nApply `bivy` or `bivy/<machine>` to a Linear issue to create a Run on the selected\nMachine. The Machine fetches issue content directly from Linear, works in an\nisolated GitHub worktree, and asks the agent to open a pull request. See\n[`docs/linear-work-queue.md`](docs/linear-work-queue.md).\n\n## Development\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server (proxies /api and /ws to the node)\n```\n\nChecks — all of these run in CI:\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nRepository layout:\n\n- `src/` — node daemon, runtime adapters, approvals, secrets, sessions\n- `bin/` — the `bivy` CLI\n- `packages/core` — shared protocol, pairing, wire format\n- `packages/web` — the React/Vite PWA client (`@bivy/web`)\n- `services/relay` — self-hostable relay\n- `services/control-plane` — self-hostable control plane\n- `deploy/` — self-host deployment examples\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Self-hosting\n\nNode, relay, and control plane are all in this repository. Point a node at your\nown deployment by passing URLs to `bivy relay:setup` — re-running it switches an\nexisting node over to the new endpoints:\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nEach URL has a flag and an environment-variable equivalent (the flag wins):\n\n| Flag | Environment variable | Points at | Default |\n|---|---|---|---|\n| `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |\n| `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |\n| `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |\n\nSign-in defaults to GitHub device login (`--github`); pass\n`--email you@example.com` for an email magic-link, or `--session-token <token>`\nto skip interactive sign-in. `relay:setup` checks the control plane is reachable,\nenrolls this node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,\n`bivy link`, and `bivy update` all keep using your deployment afterwards.\n\n**Self-hosting is community-supported** — no SLA, best-effort help via GitHub\nissues. You own TLS, backups, upgrades, and hardening. Start with the\none-command VPS path in\n[`docs/self-host-quickstart.md`](docs/self-host-quickstart.md); the ops\nreference (backups, rotation, security boundary) is\n[`docs/self-host.md`](docs/self-host.md).\n\n## Security\n\nReport vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).\nPlease don't open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,\nresponse times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)\nfor the trust model and known limitations.\n\n## License\n\nBivy Core is free and open-source software under the GNU Affero General Public\nLicense, version 3.0 only (AGPL-3.0-only). You may use, study, modify, and\nself-host it under that license. If you modify Bivy and let users interact with\nit over a network, section 13 requires you to offer them the corresponding\nsource code. See [`LICENSE`](LICENSE).\n\n**Where the open-core line is.** Everything in this repository — node, CLI,\nrelay, control plane, and the web/PWA client — is AGPL Core, with no usage\nlimits. **Bivy Cloud** is the hosted operation of that stack plus billing and\nplans, and lives in a separate private repository. Contributions are accepted\nunder the [DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
   "readmeFilename": "README.md"
 }