@bivy/bivy 0.16.25-staging.3 → 0.16.25-staging.30

package/bin/acp-shim.mjs

@@ -313,6 +313,13 @@ function onSessionUpdate(params) {
     if (!content) return "";
     if (typeof content === "string") return content;
     if (Array.isArray(content)) return content.map(textOf).join("");
+    // ACP's ToolCallContent wraps a ContentBlock: `{ type: "content", content:
+    // { type: "text", text } }`. Unwrap it (recursively) so a tool's real output
+    // — a command's stdout, a fetched document, a read's text — isn't dropped,
+    // which collapsed the tool_result to the bare status ("completed"). opencode
+    // and most spec-compliant ACP agents deliver tool output in this wrapped
+    // shape, so reading only the bare `{type:"text"}` form lost it in production.
+    if (content.type === "content" && content.content != null) return textOf(content.content);
     if (content.type === "text" && typeof content.text === "string") return content.text;
     if (typeof content.text === "string") return content.text;
     return "";

package/bin/agent-manifest.json

@@ -22,7 +22,7 @@
       "hidden": false,
       "supportTier": "supported",
       "certification": "release-tested",
-      "testedVersion": "1.18.30",
+      "testedVersion": "1.18.31",
       "headlessFlags": [
         "run",
         "-s"

package/bin/codex-app-server-shim.mjs

@@ -415,6 +415,16 @@ function onNotification(m) {
       bivy({ type: "session.status", status: "working" });
       return;
     case "turn/completed": {
+      // The completion event is authoritative about a terminal failure: a turn
+      // that hit a usage limit (or any provider error) arrives here as
+      // `status: "failed"` carrying `turn.error`. Capture it directly instead of
+      // depending on a separate `error` notification landing first — otherwise a
+      // completion that omits that notification seals as session.done and the
+      // user sees a silent empty turn (fail loud, never swallow the error).
+      const turnError =
+        params?.turn?.error?.message ||
+        (params?.turn?.status === "failed" ? params?.error?.message || params?.message || "Codex turn failed" : undefined);
+      if (turnError && !sawError) sawError = turnError;
       // Codex 0.147 can publish turn/completed just before the final
       // collabAgentToolCall item/completed notification. Sealing immediately
       // leaves the sub-agent card running forever and drops its persisted

package/bin/patch-pi-dependencies.mjs

@@ -37,8 +37,8 @@ const piPackage = findDependency(path.join("@earendil-works", "pi-coding-agent")
 if (!piPackage) process.exit(0);
 
 const patches = [
-  { name: "brace-expansion", version: "5.0.9" },
-  { name: "undici", version: "8.10.0" },
+  { name: "brace-expansion", version: "5.0.12" },
+  { name: "undici", version: "8.10.2" },
 ];
 
 for (const patch of patches) {

package/dist/agents/claude-code/integration.js

@@ -4,13 +4,21 @@ import { defineAgentIntegration } from "../definition.js";
 import { withExactCapabilitySurface } from "../../runtime/types.js";
 import { createCredentialStore } from "../../runtime/credentials.js";
 import { ClaudeCodeRuntime, claudeRuntimeFromEnv, claudeSdkInstalled, } from "./runtime.js";
-export const CLAUDE_TESTED_VERSION = "0.3.270";
+export const CLAUDE_TESTED_VERSION = "0.3.278";
 const CLAUDE_CAPABILITIES = withExactCapabilitySurface({
     toolInterception: true,
     modelSelection: true,
     packages: false,
     resume: true,
     fork: true,
+    // Must mirror ClaudeCodeRuntime.capabilities (runtime.ts): the catalog is a
+    // consumed source of truth (the fork-fidelity matrix and any fork-target
+    // fidelity preview read these), so under-reporting here makes Claude look
+    // like a seeded-only fork target when its runtime actually delivers a
+    // byte-exact same-runtime fork (forkTransport) and a full cross-runtime
+    // transcript replay INTO it (forkHistoryImport, via importHistoryForFork).
+    forkTransport: true,
+    forkHistoryImport: true,
     usageReporting: true,
     nativeSessionDiscovery: true,
     nativeSessionAdoption: true,

package/dist/agents/codex/integration.js

@@ -9,7 +9,7 @@ import { codexCredentialPreflight } from "../../runtime/codex-preflight.js";
 import { deleteCodexSession, discoverNativeCodexSessions, loadCodexTranscript, writeCodexRollout, exportCodexRollout, importCodexRollout, } from "../../runtime/codex-sessions.js";
 import { ProtocolRuntime } from "../../runtime/protocol.js";
 import { codexSlashCommands } from "../../runtime/slash-commands.js";
-export const CODEX_TESTED_VERSION = "0.154.0";
+export const CODEX_TESTED_VERSION = "0.155.1";
 const CODEX_AVAILABLE_CACHE = new Map();
 function codexCommand() {
     return process.env.BIVY_CODEX_BIN?.trim() || "codex";
@@ -146,6 +146,14 @@ export function codexIntegration(origin) {
                     resume: true,
                     packages: false,
                     fork: true,
+                    // Mirror the ProtocolRuntime this integration builds (createCodexRuntime
+                    // above wires exportForFork+importForFork and writeHistory, which flip
+                    // capabilities.forkTransport/forkHistoryImport on). The catalog is a
+                    // consumed source of truth (fork-fidelity matrix / fork-target preview),
+                    // so omitting these made Codex look seeded-only when its runtime does a
+                    // byte-exact codex→codex fork and a full transcript replay INTO it.
+                    forkTransport: true,
+                    forkHistoryImport: true,
                     usageReporting: true,
                     interactiveTui: installed,
                     nativeSessionDiscovery: true,

package/dist/agents/pi/integration.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { defineAgentIntegration } from "../definition.js";
 import { PI_CAPABILITIES } from "./capabilities.js";
-export const PI_TESTED_VERSION = "0.85.1";
+export const PI_TESTED_VERSION = "0.86.1";
 export function piAgentDir() {
     return process.env.PI_CODING_AGENT_DIR?.trim() || path.join(os.homedir(), ".pi", "agent");
 }

package/dist/agents/pi/runtime.js

@@ -268,8 +268,29 @@ class PiSession {
      * reload. Async because that resolution reads the store.
      */
     async getModels() {
-        const models = await this.session.modelRuntime.getAvailable();
-        return models.map((model) => toModelInfo(model, true));
+        const runtime = this.session.modelRuntime;
+        try {
+            const models = await runtime.getAvailable();
+            return models.map((model) => toModelInfo(model, true));
+        }
+        catch (error) {
+            // The runtime's availability refresh is a Promise.all across every
+            // provider's auth check, so one broken provider (an unreachable custom
+            // endpoint, a single failing credential read) rejects the whole catalog
+            // and the picker shows nothing. Degrade to per-provider listing and
+            // skip only the broken ones; rethrow only when truly nothing survives.
+            const models = [];
+            for (const provider of runtime.getProviders()) {
+                try {
+                    for (const model of await runtime.getAvailable(provider.id))
+                        models.push(toModelInfo(model, true));
+                }
+                catch { /* this provider is broken — the rest still list */ }
+            }
+            if (models.length)
+                return models;
+            throw error instanceof Error ? error : new Error(String(error));
+        }
     }
     /**
      * Every model Pi knows about — built-in and custom, regardless of whether
@@ -281,7 +302,10 @@ class PiSession {
     async getAllModels() {
         const runtime = this.session.modelRuntime;
         // Refresh availability first so `hasConfiguredAuth` reflects current creds.
-        await runtime.getAvailable();
+        // Best-effort: a failed refresh (one broken provider rejects the shared
+        // Promise.all) must not blank the full catalog — the flags then reflect
+        // the last successful refresh, which the picker can still act on.
+        await runtime.getAvailable().catch(() => { });
         return runtime.getModels().map((model) => toModelInfo(model, runtime.hasConfiguredAuth(model.provider)));
     }
     /** Reload the projected models.json in-place so a live session immediately

package/dist/agents/profiles.js

@@ -43,7 +43,7 @@ export const AGENT_PROFILES = {
         // Approve/Deny + session/load resume + a real model picker), the same bar Pi,
         // Claude Code, and Codex clear. See `acp` below for the version fallback.
         supportTier: "supported",
-        testedVersion: "1.18.30",
+        testedVersion: "1.18.31",
         blurb: "The most widely used open-source coding harness (OpenCode CLI).",
         // `opencode run -s <id> "<prompt>"` continues a prior session by its own id
         // (`-s, --session  session id to continue`, per `opencode run --help`).
@@ -398,13 +398,21 @@ export const AGENT_PROFILES = {
             flag: "-m",
             models: [
                 // Official Grok CLI (1.x) advertises grok-4.6 as the default subscription
-                // model (verified against `grok models`); the older grok-4.5 / grok-4-latest
-                // / grok-code-fast-1 ids now return "unknown model id". Keep the list
-                // honest; operators can override with BIVY_GROK_MODELS if their install
-                // exposes more.
+                // model (verified against the authenticated `~/.grok/models_cache.json`,
+                // origin cli-chat-proxy.grok.com/v1/models); the older grok-4.5 /
+                // grok-4-latest / grok-code-fast-1 ids now return "unknown model id".
+                // Keep the list honest; operators can override with BIVY_GROK_MODELS if
+                // their install exposes more.
                 { id: "grok-4.6", name: "Grok 4.6", provider: "xai" },
             ],
         },
+        // Grok's reasoning models expose a `--reasoning-effort <EFFORT>` flag
+        // (verified against `grok --help`, 1.0.0); the authenticated model catalog
+        // lists low/medium/high/xhigh with `high` as the default. `{level}` fills
+        // the value; insertAt: 0 keeps the trailing `-p` prompt flag last so the
+        // prompt still lands as its value. Threads through the resume path too, so a
+        // continued turn keeps the chosen effort. Override with BIVY_GROK_THINKING.
+        thinking: { levels: ["low", "medium", "high", "xhigh"], default: "high", template: ["--reasoning-effort", "{level}"], insertAt: 0 },
         promptMode: "argv",
         install: {
             kind: "curl",

package/dist/certification/generated.js

@@ -3,9 +3,9 @@
 export const CERTIFICATION_MATRIX = {
     schemaVersion: 1,
     agents: [
-        { id: "claude-code-sdk", status: "active", executionMode: "protocol", pinnedVersion: "0.3.270", capabilities: ["toolInterception", "modelSelection", "resume"] },
-        { id: "codex-approvals", status: "active", executionMode: "protocol", pinnedVersion: "0.154.0", capabilities: ["toolInterception", "modelSelection", "resume"] },
-        { id: "pi", status: "active", executionMode: "protocol", pinnedVersion: "0.85.1", capabilities: ["toolInterception", "modelSelection", "resume"] },
-        { id: "opencode", status: "active", executionMode: "protocol", pinnedVersion: "1.18.30", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "claude-code-sdk", status: "active", executionMode: "protocol", pinnedVersion: "0.3.278", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "codex-approvals", status: "active", executionMode: "protocol", pinnedVersion: "0.155.1", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "pi", status: "active", executionMode: "protocol", pinnedVersion: "0.86.1", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "opencode", status: "active", executionMode: "protocol", pinnedVersion: "1.18.31", capabilities: ["toolInterception", "modelSelection", "resume"] },
     ]
 };

package/dist/controllers/credential-commands.js

@@ -95,7 +95,8 @@ export function createCredentialCommands(deps) {
         async "credential.remove"(msg, ctx) {
             try {
                 await removeProviderCredential(credsDir, String(msg.provider ?? ""), String(msg.label ?? ""));
-                await deps.pushModelAuthToControlPlane();
+                // Deleting a granted credential must also remove its escrowed cloud copy.
+                await deps.pushModelAuthToControlPlane({ allowEmptyHostedEscrow: true });
                 await deps.refreshSessionAfterAuth();
                 deps.sendEvent({ type: "credentials.records", records: await listCredentialRecords(credsDir) });
                 deps.broadcast({ type: "providers.list", providers: await deps.listProvidersUnified() });
@@ -111,7 +112,8 @@ export function createCredentialCommands(deps) {
             try {
                 const sync = msg.sync === "node" ? "node" : "account";
                 await setCredentialSync(credsDir, String(msg.provider ?? ""), String(msg.label ?? ""), sync);
-                await deps.pushModelAuthToControlPlane();
+                // Demoting to machine-only revokes any custody grant; let it clear the escrow.
+                await deps.pushModelAuthToControlPlane({ allowEmptyHostedEscrow: sync === "node" });
                 deps.sendEvent({ type: "credentials.records", records: await listCredentialRecords(credsDir) });
                 ctx.reply({ type: "credential.sync.set.ok", requestId: msg.requestId });
             }
@@ -127,7 +129,10 @@ export function createCredentialCommands(deps) {
             const previous = (await listCredentialRecords(credsDir)).find((record) => record.provider === provider.trim().toLowerCase() && record.label === label)?.unattended === true;
             try {
                 await setCredentialUnattended(credsDir, provider, label, msg.unattended === true);
-                await deps.pushModelAuthToControlPlane();
+                // Fail loud: the grant reply must reflect whether the encrypted cloud
+                // copy actually reached the control plane. An explicit disable is the
+                // one caller allowed to publish an empty escrow snapshot.
+                await deps.pushModelAuthToControlPlane({ throwOnFailure: true, allowEmptyHostedEscrow: msg.unattended !== true });
                 deps.sendEvent({ type: "credentials.records", records: await listCredentialRecords(credsDir) });
                 ctx.reply({ type: "credential.unattended.set.ok", requestId: msg.requestId });
             }

package/dist/credentials/document.js

@@ -87,17 +87,22 @@ function sameRecordContent(a, b) {
     const strip = ({ updatedAt: _drop, ...rest }) => rest;
     return JSON.stringify(strip(a)) === JSON.stringify(strip(b));
 }
+const stable = (value) => {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+        .map(([key, child]) => [key, stable(child)]));
+};
 function canonicalCredential(credential) {
     const { updatedAt: _drop, ...content } = credential;
-    const stable = (value) => {
-        if (Array.isArray(value))
-            return value.map(stable);
-        if (!value || typeof value !== "object")
-            return value;
-        return Object.fromEntries(Object.entries(value)
-            .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
-            .map(([key, child]) => [key, stable(child)]));
-    };
+    return JSON.stringify(stable(content));
+}
+/** Stable record content sans the store-owned stamp — the final merge tie-break. */
+function canonicalRecord(record) {
+    const { updatedAt: _drop, ...content } = record;
     return JSON.stringify(stable(content));
 }
 /**
@@ -132,6 +137,19 @@ export function preferIncomingRecord(local, incoming) {
     const incomingOauth = oauthOf(incoming);
     if (!localOauth || !incomingOauth)
         return true;
+    // Identical token content means this is a metadata-only change (an
+    // unattended-runs grant/revoke, a sync-tier move). Token freshness cannot
+    // order those, so the newer record write wins — without this, a grant made
+    // on one machine never reaches its peers, and a peer's next hosted-escrow
+    // push would read as "nothing granted". Equal stamps fall back to canonical
+    // record content so both merge directions still converge.
+    if (canonicalCredential(localOauth) === canonicalCredential(incomingOauth)) {
+        const localAt = Number(local.updatedAt) || 0;
+        const incomingAt = Number(incoming.updatedAt) || 0;
+        if (incomingAt !== localAt)
+            return incomingAt > localAt;
+        return canonicalRecord(incoming) > canonicalRecord(local);
+    }
     return preferIncomingOAuthCredential(localOauth, incomingOauth);
 }
 /** A tombstone wins only when it is newer than the record it would remove. */
@@ -251,7 +269,14 @@ export function mergeDocuments(local, incomingCredentials, incomingDeletedAt = {
             continue;
         if (!(key in credentials))
             imported += 1;
-        credentials[key] = incoming;
+        // An incoming record with no opinion on unattended custody (undefined — the
+        // v2 wire and plaintext ingest never carry the flag) must not strip an
+        // explicit local grant/revoke: agent-side token refreshes flow through this
+        // merge, and dropping the flag would make the node's next escrow push
+        // silently revoke the encrypted cloud copy the user still relies on.
+        credentials[key] = localRecord && incoming.unattended === undefined && localRecord.unattended !== undefined
+            ? { ...incoming, unattended: localRecord.unattended }
+            : incoming;
         const incomingUpdatedAt = Number(incoming.updatedAt);
         if (!Number.isFinite(deletedAt[key]) || incomingUpdatedAt > deletedAt[key])
             delete deletedAt[key];

package/dist/credentials/store.js

@@ -554,6 +554,23 @@ export class BivyCredentialStore {
             // engine (merge-never-destroy, freshest-OAuth-wins, rotation-safe,
             // tombstone-newer-wins — see document.ts).
             const incoming = migrateToV3({ v: 2, providers: snapshot, deletedAt });
+            // The v2 wire carries no record metadata, so migrateToV3 synthesizes
+            // defaults (sync: "account", origin: "bivy", no unattended flag). Those
+            // defaults must not clobber local intent — a machine-only sync tier or an
+            // unattended-runs custody grant — when only the token content is newer
+            // (e.g. an agent's own TUI refreshed the OAuth token set). Inherit the
+            // existing record's metadata; the merge engine still decides freshness.
+            for (const [key, record] of Object.entries(incoming.credentials)) {
+                const existing = document.credentials[key];
+                if (!existing)
+                    continue;
+                incoming.credentials[key] = {
+                    ...record,
+                    sync: existing.sync,
+                    origin: existing.origin,
+                    ...(existing.unattended !== undefined ? { unattended: existing.unattended } : {}),
+                };
+            }
             const result = mergeDocuments(document, incoming.credentials, incoming.deletedAt);
             if (result.changed)
                 this.writeDocument(result.document);

package/dist/hosted-custody.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// One pure policy decision: does THIS daemon hold only control-plane-custodied
+// credentials (the separately escrowed unattended snapshot), or is it a normal
+// personal node that owns its vault?
+//
+// The distinction matters everywhere model-auth sync branches: a custody node
+// never pushes/pulls the account vault, never publishes the unattended escrow,
+// and treats the control plane's filtered snapshot as an authoritative set
+// (reconcile deletes what a newer snapshot omits). Getting this wrong on a
+// personal node silently breaks credential sync AND makes the unattended-runs
+// toggle a no-op — the "Allowed — encrypted cloud copy enabled" UI then lies,
+// and every Bivy Cloud session fails with "credential didn't reach Bivy Cloud".
+/**
+ * True when this daemon must run with hosted-custody semantics:
+ *  - `BIVY_HOSTED_CREDENTIAL_CUSTODY` — the dedicated flag the provisioner sets
+ *    on managed (Bivy Cloud) machines; always authoritative.
+ *  - `BIVY_GITHUB_HOSTED_TASKS` + `BIVY_EPHEMERAL` — back-compat for
+ *    provisioned user-owned queue runners that predate the dedicated flag.
+ *
+ * `BIVY_GITHUB_HOSTED_TASKS` ALONE is not custody: it is persisted onto any
+ * long-lived personal node when a GitHub App is connected (it only means "poll
+ * the hosted task queue"). Such a node owns its own logins and must keep full
+ * personal-vault semantics — account sync, escrow publishing, loud toggles.
+ */
+export function hostedCustodyNode(env = process.env) {
+    if (env.BIVY_HOSTED_CREDENTIAL_CUSTODY)
+        return true;
+    return Boolean(env.BIVY_GITHUB_HOSTED_TASKS && env.BIVY_EPHEMERAL);
+}

package/dist/runtime/cli-parsers.js

@@ -696,6 +696,25 @@ function rawExitCode(raw) {
     const exit = o.exit_code ?? o.exitCode ?? o.code;
     return typeof exit === "number" ? exit : undefined;
 }
+/** Decode a UTF-8 byte array carried as a JSON `number[]` (Grok's
+ * `rawOutput.output` transports command output this way). Returns the decoded
+ * string, or undefined when the value isn't a plausible byte array. Used only as
+ * a LAST resort — a clean ACP `content` block is always preferred — so a result
+ * frame with no display content still renders readable text instead of a raw
+ * number array (`[97,46,116,120,116]`). */
+function decodeByteArray(v) {
+    if (!Array.isArray(v) || v.length === 0)
+        return undefined;
+    if (!v.every((n) => typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= 255))
+        return undefined;
+    try {
+        const text = Buffer.from(v).toString("utf8");
+        return text.includes("\uFFFD") ? undefined : text;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Extract an ACP-style tool update. Two transports converge here:
  *   1. A JSON-RPC `session/update` notification (`params.update`), the true ACP
  *      wire form used by Gemini/Qwen/Copilot etc.
@@ -735,8 +754,16 @@ function acpToolUpdate(msg) {
         // the exit code from the raw payload when we take the content text instead.
         const contentText = flattenAcpContent(update.content);
         const exit = rawExitCode(raw);
-        const output = contentText !== undefined
-            ? (exit !== undefined ? { content: contentText, exit_code: exit } : contentText)
+        // Last-resort text when no clean ACP `content` block is present: decode a
+        // byte-array payload (Grok's rawOutput.output) so the card shows readable
+        // output instead of a raw `[97,46,…]` number array. Never overrides a real
+        // content block.
+        const decoded = contentText === undefined
+            ? (decodeByteArray(raw) ?? (raw && typeof raw === "object" && !Array.isArray(raw) ? decodeByteArray(raw.output) : undefined))
+            : undefined;
+        const text = contentText ?? decoded;
+        const output = text !== undefined
+            ? (exit !== undefined ? { content: text, exit_code: exit } : text)
             : (raw ?? update.content);
         return { kind: "result", id, output, error: status === "failed" || status === "error" };
     }

package/dist/runtime/index.js

@@ -53,6 +53,7 @@ import { ProtocolRuntime, protocolRuntimeFromEnv, protocolCommandsFromEnv } from
 import { codexSlashCommands, opencodeSlashCommands } from "./slash-commands.js";
 import { withExactCapabilitySurface } from "./types.js";
 import { installedAgentContributions } from "../plugins/store.js";
+import { forkCapsFromInfo } from "../session/fork-matrix.js";
 import { currentBivyVersion } from "../app-version.js";
 const PREFLIGHT_BEHAVIORS = {
     codex: (env) => codexCredentialPreflight(env),
@@ -552,6 +553,17 @@ function cliAgentInfo(id, spec) {
     }
     const authOwner = spec.authOwner ?? "agent";
     const credentialProviders = [...new Set((spec.model?.models ?? []).flatMap((model) => model.provider ? [model.provider] : []))];
+    // Fork fidelity, mirrored from what makeCliRuntime actually wires up. An
+    // ACP-promoted agent with a portable session store (OpenCode's SQLite) gets
+    // export/import + writeHistory hooks in acpRuntimeOptions, so its runtime
+    // advertises a byte-exact same-runtime fork (forkTransport) AND a full
+    // cross-runtime transcript replay INTO it (forkHistoryImport). Reporting a
+    // blanket fork:false here hid a full-fidelity fork target from the catalog
+    // and the generated fork matrix. Gated on the shipped default (acp.preferred)
+    // rather than a live binary probe so the capability is install-independent —
+    // the honest "what this adapter does by default", matching how resume/model
+    // are described before the optional BIVY_AGENT_PROBE refinement.
+    const nativeStoreFork = spec.behaviors?.sessionStore === "opencode" && spec.acp?.preferred === true;
     return {
         id,
         executionMode,
@@ -570,7 +582,8 @@ function cliAgentInfo(id, spec) {
             modelSelection,
             resume,
             packages: false,
-            fork: false,
+            fork: nativeStoreFork,
+            ...(nativeStoreFork ? { forkTransport: true, forkHistoryImport: true } : {}),
             usageReporting,
             // Any agent with a readable on-disk session store (Codex, OpenCode) or
             // native-session behavior (Grok) can locate the session a `bivy run`
@@ -1009,6 +1022,22 @@ function agentRegistry(pluginDataDir) {
 export function listRegisteredAgents() {
     return agentRegistry().list().map((entry) => applyCertification(entry.describe()));
 }
+// Meta/host rows that are not concrete coding agents (they describe the generic
+// transports themselves), plus the hidden plain-`codex` exec runtime, which is a
+// duplicate of the governed `codex-approvals` we surface as "Codex".
+const FORK_MATRIX_EXCLUDE = new Set(["generic-cli", "bivy-agent-protocol", "acp", "codex"]);
+/** The built-in coding agents and their fork capabilities, derived from the live
+ *  registry, for docs/fork-matrix.md and its drift-guard test. Restricted to the
+ *  maintained (distribution) integrations so the generated doc is deterministic
+ *  regardless of which agents happen to be installed or which plugins are present. */
+export function forkMatrixAgents() {
+    return listRegisteredAgents()
+        .filter((info) => info.status !== "planned" &&
+        !FORK_MATRIX_EXCLUDE.has(info.id) &&
+        info.source?.kind === "package" &&
+        info.source.location === "distribution")
+        .map(forkCapsFromInfo);
+}
 /** Resolve an id or historical alias through the authoritative registry. */
 export function canonicalAgentId(id) {
     return agentRegistry().get(id.toLowerCase())?.id;

package/dist/runtime/protocol.js

@@ -711,14 +711,41 @@ class ProtocolSession {
             return;
         }
         if (type === "session.error") {
+            const errorText = String(msg.error || "Protocol agent error");
+            // Preserve whatever the failed turn already streamed — a partial assistant
+            // reply and its tool calls/results — persisted exactly as session.done
+            // persists a clean turn. The old handler wiped turnContent here, so a mid-
+            // turn failure dropped all of that work from the reopened transcript.
+            const hadTools = this.turnContent.length > 0 || this.turnToolResults.length > 0;
+            if (hadTools) {
+                this.flushPendingTurnText();
+                if (this.turnContent.length)
+                    this.messages.push({ role: "assistant", content: this.turnContent, timestamp: Date.now() });
+                if (this.turnToolResults.length)
+                    this.messages.push({ role: "user", content: this.turnToolResults, timestamp: Date.now() });
+            }
+            else if (this.assistantText) {
+                this.messages.push({ role: "assistant", content: this.assistantText, timestamp: Date.now() });
+            }
+            // Append a terminal error marker in the shape store-render + terminalTurnError
+            // recognize (stopReason "error" + errorMessage), so the failure itself
+            // survives a reload as an inline error instead of the turn reopening blank
+            // ("looks done, no reply"). Matches the live session.error emitted just below.
+            const errored = { role: "assistant", content: "", stopReason: "error", errorMessage: errorText, timestamp: Date.now() };
+            this.messages.push(errored);
             this.streaming = false;
+            this.assistantText = "";
+            this.assistantItemBoundary = false;
             this.reasoningText = "";
             this.turnContent = [];
             this.turnTextFlushed = "";
             this.turnToolResults = [];
             this.toolDetailsByCallId.clear();
             this.openToolIds = [];
-            this.emit({ type: "session.error", error: String(msg.error || "Protocol agent error") });
+            // message_end drives the daemon's base-transcript snapshot (agent_end does
+            // not), so the preserved content + error marker are durably persisted.
+            this.emit({ type: "message_end", message: errored });
+            this.emit({ type: "session.error", error: errorText });
             this.emit({ type: "agent_end" });
             return;
         }
@@ -872,7 +899,10 @@ class ProtocolSession {
         const preflightError = await this.preparePreflight();
         if (preflightError) {
             this.streaming = false;
-            const message = { role: "assistant", content: "", errorMessage: preflightError };
+            // stopReason "error" is what store-render keys on to re-render this as an
+            // inline error on reload (without it the turn reopened blank); it also
+            // matches the terminal-error message shape every other failure path uses.
+            const message = { role: "assistant", content: "", stopReason: "error", errorMessage: preflightError };
             this.messages.push(message);
             this.emit({ type: "message_start", message: { role: "assistant", content: "" } });
             this.emit({ type: "session.error", error: preflightError });

package/dist/server.js

@@ -80,6 +80,7 @@ import { forceAbortTurn } from "./session/abort-recovery.js";
 import { runRequiredAutomationChecks } from "./automation-checks.js";
 import { configToLegacySettings, mergeLegacyIntoNodeConfig, readNodeConfig, writeNodeConfig } from "./node-config.js";
 import { loadProjectPolicy, resolveProjectSafety } from "./project-policy.js";
+import { hostedCustodyNode } from "./hosted-custody.js";
 import { PolicyEngine } from "./policy/policy-engine.js";
 import { SessionAllowRules } from "./policy/session-allow.js";
 import { TerminalManager } from "./terminal.js";
@@ -1966,7 +1967,7 @@ const RELAY_COMMANDS = {
         credsDir,
         sendEvent: (event) => relay?.sendEvent(event),
         broadcast,
-        pushModelAuthToControlPlane,
+        pushModelAuthToControlPlane: (opts) => pushModelAuthToControlPlane(false, opts?.throwOnFailure === true, opts?.allowEmptyHostedEscrow === true),
         refreshSessionAfterAuth,
         listProvidersUnified,
     }),
@@ -2407,7 +2408,19 @@ const RELAY_COMMANDS = {
         // this a models.list answered for one agent (e.g. Codex's models) could
         // linger on the composer/picker after the user switched to another agent
         // (e.g. Claude) — the "Claude shows Codex models" bug.
-        relay?.sendEvent(await modelsListEventFor(record));
+        let event;
+        try {
+            event = await modelsListEventFor(record);
+        }
+        catch (error) {
+            // A catalog read failure must never answer with silence: the generic
+            // relay catch would swallow the rejection and the client (notably a
+            // Cloud launch waiting to validate its saved model) could only guess
+            // via timeout. Name the real reason on the session instead.
+            relay?.sendEvent({ type: "session.error", sessionId: requestedSessionId ?? record.id, error: `Couldn't read this machine's model catalog: ${error instanceof Error ? error.message : String(error)}` });
+            return;
+        }
+        relay?.sendEvent(event);
     },
     "models.prefetch"(msg) {
         // The composer's agent picker opened: warm the scratch session for each
@@ -2569,7 +2582,8 @@ const RELAY_COMMANDS = {
                 }
             }
             await removeProvider(credsDir, id);
-            await pushModelAuthToControlPlane();
+            // Deleting a granted credential must also remove its escrowed cloud copy.
+            await pushModelAuthToControlPlane(false, false, true);
             await refreshSessionAfterAuth();
             broadcast({ type: "provider.oauth.reset", provider: id, ok: true, providers: await listProvidersUnified() });
             broadcast({ type: "providers.list", providers: await listProvidersUnified() });
@@ -2581,7 +2595,8 @@ const RELAY_COMMANDS = {
     async "provider.remove"(msg) {
         try {
             await removeProvider(credsDir, String(msg.provider ?? msg.id ?? ""));
-            await pushModelAuthToControlPlane();
+            // Deleting a granted credential must also remove its escrowed cloud copy.
+            await pushModelAuthToControlPlane(false, false, true);
             await refreshSessionAfterAuth();
             broadcast({ type: "providers.list", providers: await listProvidersUnified() });
         }
@@ -3065,7 +3080,11 @@ const hostedImportedRecordsPath = path.join(appDir, "model-auth-hosted-records.j
 let lastPushedModelAuthCiphertext = "";
 let lastPushedHostedModelAuthCiphertext = "";
 let lastPushedHostedModelAuthRevision = -1;
-const isHostedCustodyNode = () => Boolean(process.env.BIVY_HOSTED_CREDENTIAL_CUSTODY || process.env.BIVY_GITHUB_HOSTED_TASKS);
+// Custody semantics are keyed on the dedicated flag (plus an ephemeral
+// back-compat case) — see src/hosted-custody.ts. A persistent personal node
+// that polls the hosted GitHub queue is NOT a custody guest: it owns its
+// logins and must keep account sync and unattended-escrow publishing.
+const isHostedCustodyNode = () => hostedCustodyNode();
 function readLocalModelAuthVaultKey() {
     try {
         const parsed = JSON.parse(fs.readFileSync(modelAuthVaultKeyPath, "utf8"));
@@ -3376,12 +3395,19 @@ async function processModelAuthKeyRequests(requests) {
         });
     }
 }
-async function pushHostedModelAuthToControlPlane() {
+async function pushHostedModelAuthToControlPlane(allowEmpty = false) {
     const [records, revision] = await Promise.all([exportUnattendedRecords(credsDir), unattendedCredentialRevision(credsDir)]);
     // A setup guest must not establish an empty snapshot when the credential is
     // first saved (before the explicit grant command follows). Otherwise its
     // one allowed initial write would be consumed by an unusable vault.
-    if (isHostedCustodyNode() && Object.keys(records).length === 0)
+    //
+    // And an IMPLICIT empty push must never revoke the escrow: an empty snapshot
+    // is how "disable unattended runs" removes the cloud copy, but every vault
+    // change funnels through here — so a node whose copy simply lacks the grant
+    // (not yet synced, or granted elsewhere) would otherwise wipe the encrypted
+    // cloud copy the user's other machines just published. Only an explicit
+    // local revoke/delete (allowEmpty) may publish an empty snapshot.
+    if (Object.keys(records).length === 0 && (!allowEmpty || isHostedCustodyNode()))
         return;
     if (revision === lastPushedHostedModelAuthRevision)
         return;
@@ -3413,7 +3439,7 @@ async function pushHostedModelAuthToControlPlane() {
         throw new Error(`hosted model-auth push failed (${response?.status ?? "offline"})`);
     }
 }
-async function pushModelAuthToControlPlane(rotateKey = false, throwOnFailure = false) {
+async function pushModelAuthToControlPlane(rotateKey = false, throwOnFailure = false, allowEmptyHostedEscrow = false) {
     if (!sessionAdvertiseTarget)
         return;
     // Piggyback the (plaintext, non-secret) provider status summary on every
@@ -3448,7 +3474,7 @@ async function pushModelAuthToControlPlane(rotateKey = false, throwOnFailure = f
             writeLocalModelAuthVaultKey(vaultKeyB64);
         const ciphertext = encryptModelAuthProviders(providers, deletedAt, localModels, vaultKeyB64, records, recordsDeletedAt);
         if (!rotateKey && ciphertext === lastPushedModelAuthCiphertext) {
-            await pushHostedModelAuthToControlPlane();
+            await pushHostedModelAuthToControlPlane(allowEmptyHostedEscrow);
             return;
         }
         const push = await modelAuthFetch("/node/model-auth-vault", { method: "PUT", body: JSON.stringify({ ciphertext, rotated: rotateKey }) });
@@ -3469,7 +3495,7 @@ async function pushModelAuthToControlPlane(rotateKey = false, throwOnFailure = f
         // Publish a DIFFERENT ciphertext under a DIFFERENT key containing only
         // records with `unattended:true`. Escrowing this key cannot decrypt the E2E
         // account vault, which is the critical custody separation.
-        await pushHostedModelAuthToControlPlane();
+        await pushHostedModelAuthToControlPlane(allowEmptyHostedEscrow);
     }
     catch (error) {
         console.warn("[auth-sync] could not push model auth:", error.message);
@@ -9295,7 +9321,7 @@ async function modelsListEventFor(record) {
     const current = session.getCurrentModel();
     const models = await publicModelsList(session, current);
     const thinking = publicThinkingInfo(session);
-    return { type: "models.list", sessionId: record.id, runtimeId: record.runtimeId, current: current ? publicModel(current, current) : null, models, thinking };
+    return { type: "models.list", sessionId: record.id, runtimeId: record.runtimeId, modelSelection: getRuntime(record.runtimeId).capabilities.modelSelection !== false, current: current ? publicModel(current, current) : null, models, thinking };
 }
 function publicThinkingInfo(session) {
     const supports = typeof session.supportsThinking === "function" ? session.supportsThinking() : false;
@@ -9322,7 +9348,7 @@ app.get("/api/models", async (req, res, next) => {
         const current = session.getCurrentModel();
         const models = await publicModelsList(session, current);
         const thinking = publicThinkingInfo(session);
-        res.json({ sessionId: record.id, current: current ? publicModel(current, current) : null, models, thinking });
+        res.json({ sessionId: record.id, modelSelection: getRuntime(record.runtimeId).capabilities.modelSelection !== false, current: current ? publicModel(current, current) : null, models, thinking });
     }
     catch (error) {
         next(error);
@@ -9678,7 +9704,8 @@ app.post("/api/auth/credentials", async (req, res, next) => {
 app.delete("/api/auth/credentials/:provider/:label", async (req, res, next) => {
     try {
         await removeProviderCredential(credsDir, String(req.params.provider), String(req.params.label));
-        await pushModelAuthToControlPlane();
+        // Deleting a granted credential must also remove its escrowed cloud copy.
+        await pushModelAuthToControlPlane(false, false, true);
         await refreshSessionAfterAuth();
         res.json({ ok: true, records: await listCredentialRecords(credsDir), providers: await listProvidersUnified() });
     }
@@ -9690,7 +9717,8 @@ app.post("/api/auth/credentials/:provider/:label/availability", async (req, res,
     try {
         const sync = req.body?.sync === "node" ? "node" : "account";
         await setCredentialSync(credsDir, String(req.params.provider), String(req.params.label), sync);
-        await pushModelAuthToControlPlane();
+        // Demoting to machine-only revokes any custody grant; let that clear the escrow.
+        await pushModelAuthToControlPlane(false, false, sync === "node");
         res.json({ ok: true, records: await listCredentialRecords(credsDir) });
     }
     catch (error) {
@@ -9698,12 +9726,21 @@ app.post("/api/auth/credentials/:provider/:label/availability", async (req, res,
     }
 });
 app.post("/api/auth/credentials/:provider/:label/unattended", async (req, res, next) => {
-    try {
-        await setCredentialUnattended(credsDir, String(req.params.provider), String(req.params.label), req.body?.unattended === true);
-        await pushModelAuthToControlPlane();
+    const provider = String(req.params.provider);
+    const label = String(req.params.label);
+    const enable = req.body?.unattended === true;
+    const previous = (await listCredentialRecords(credsDir).catch(() => []))
+        .find((record) => record.provider === provider.trim().toLowerCase() && record.label === label)?.unattended === true;
+    try {
+        await setCredentialUnattended(credsDir, provider, label, enable);
+        // Fail loud (mirrors the relay command): the UI must never claim an
+        // encrypted cloud copy exists when custody publication failed. An explicit
+        // disable is the one caller allowed to publish an empty escrow snapshot.
+        await pushModelAuthToControlPlane(false, true, !enable);
         res.json({ ok: true, records: await listCredentialRecords(credsDir) });
     }
     catch (error) {
+        await setCredentialUnattended(credsDir, provider, label, previous).catch(() => { });
         next(error);
     }
 });

package/dist/session/fork-matrix.js

@@ -28,6 +28,18 @@ export function forkTier(source, dest) {
         return "replayed";
     return "seeded";
 }
+/** Project a registry RuntimeInfo onto the two flags that decide fork fidelity.
+ *  Keeps the registry the single source of truth: an agent that declares its
+ *  real fork capabilities (see the maintained integrations + cliAgentInfo)
+ *  appears with the correct tier automatically. */
+export function forkCapsFromInfo(info) {
+    return {
+        id: info.id,
+        ...(info.displayName ? { displayName: info.displayName } : {}),
+        forkTransport: info.capabilities.forkTransport === true,
+        forkHistoryImport: info.capabilities.forkHistoryImport === true,
+    };
+}
 /** Every ordered (source, dest) pair and its tier. */
 export function forkMatrix(agents) {
     const cells = [];

package/dist/worktree.js

@@ -94,7 +94,15 @@ export async function createWorktree(opts) {
         else if (base !== "HEAD" && !(await refExists(repoRoot, base)))
             base = "HEAD";
         // Fail closed on path collisions; never delete an unrelated directory.
-        await exec("git", ["-C", repoRoot, "worktree", "add", "-b", branch, wtPath, base]);
+        if (base === "HEAD" && !(await refExists(repoRoot, "HEAD"))) {
+            // Empty repo (e.g. a freshly created GitHub repo with no commits): HEAD is
+            // unborn, so it can't seed a worktree. Start the branch as an orphan —
+            // the session's first commit becomes the repo's root commit.
+            await exec("git", ["-C", repoRoot, "worktree", "add", "--orphan", "-b", branch, wtPath]);
+        }
+        else {
+            await exec("git", ["-C", repoRoot, "worktree", "add", "-b", branch, wtPath, base]);
+        }
     }
     // Opportunistically reuse a sibling worktree's installed deps (node_modules,
     // target, .venv) via copy-on-write when the filesystem supports it, so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.16.25-staging.3",
+  "version": "0.16.25-staging.30",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -39,21 +39,21 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "brace-expansion": "5.0.9",
+    "brace-expansion": "5.0.12",
     "express": "^5.2.1",
-    "express-rate-limit": "^8.6.2",
+    "express-rate-limit": "^8.7.0",
     "node-pty": "^1.1.0",
     "semver": "^7.7.2",
-    "typebox": "^1.3.19",
-    "undici": "8.10.0",
+    "typebox": "^1.3.34",
+    "undici": "8.10.2",
     "ws": "^8.21.3",
-    "yaml": "^2.9.0",
-    "zod": "^4.0.0"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
   "optionalDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.270",
-    "@earendil-works/pi-ai": "0.85.1",
-    "@earendil-works/pi-coding-agent": "0.85.1"
+    "@anthropic-ai/claude-agent-sdk": "0.3.278",
+    "@earendil-works/pi-ai": "0.86.1",
+    "@earendil-works/pi-coding-agent": "0.86.1"
   },
   "overrides": {
     "fast-uri": "3.1.6",
@@ -62,12 +62,13 @@
     "@hono/node-server": "2.0.12",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@earendil-works/pi-coding-agent": {
-      "brace-expansion": "5.0.9",
-      "undici": "8.10.0"
+      "brace-expansion": "5.0.12",
+      "undici": "8.10.2"
     },
-    "brace-expansion": "5.0.9",
+    "brace-expansion": "5.0.12",
     "nanoid": "3.3.18",
-    "undici": "8.10.0"
+    "lodash-es": "4.18.1",
+    "undici": "8.10.2"
   },
   "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 your machines and use them from anywhere — from a phone,\nbrowser, terminal, GitHub issue, Slack message, schedule, or webhook.**\n\nBivy is an open-source workspace for coding-agent work. Turn prompts, GitHub\nissues, CI failures, Slack messages, and schedules into live sessions on your\nmachines. Choose the agent and model, sync supported API keys and OAuth logins,\nand steer and review the work from your browser, phone, or terminal.\n\nKeep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your\nrepos, tools, and development environment. Bivy connects them into a workflow\nthat doesn't end when you leave your desk.\n\n**[Start free on Bivy Cloud](https://app.bivy.sh)** ·\n**[Quickstart](docs/quickstart.md)** ·\n**[Documentation](docs/README.md)** ·\n**[Self-host](docs/deploy-images.md)** ·\n**[Website](https://bivy.sh)**\n\n**Recommended:** sign in at [app.bivy.sh](https://app.bivy.sh), then copy your\npersonalized **Connect a Machine** command into a terminal on your Mac or Linux\ncomputer. It installs and enrolls the machine without another Bivy login. The\nbrowser connects automatically; choose a repository and send your first task\nright there.\n\nPrefer starting from the terminal?\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash  # install + guided setup\ncd your-repo\nbivy run claude                            # or codex, pi, opencode\nbivy open                                  # continue in the web app (needs remote setup)\n```\n\nBivy Cloud hosts the app, control plane, and relay—not the machines running your\nagents. Connect a Mac, Linux computer, or existing server and bring your own\nagent subscription, model API key, or local model. You can also self-host the\nentire remote-access stack.\n\n> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the\n> release-tested paths. Credential sync, resume, handoffs, approvals, and\n> sandboxing depend on the runtime. See the\n> [runtime support matrix](docs/runtime-support-matrix.md).\n\n## More than remote access\n\nRemote access lets you reach an agent. Bivy also connects **what starts the\nwork, where it runs, which agent and credentials it uses, and how you review\nwhat happened**.\n\n| Capability | What it means for you |\n|---|---|\n| **One workspace, multiple agents** | Use different agents and models for different tasks without maintaining a separate workflow for each. |\n| **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |\n| **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |\n| **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |\n| **Live sessions from anywhere** | Start at your desk, answer a question or approve an action from your phone, then return to the terminal. |\n| **Reviewable results** | See changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |\n| **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |\n\n## One workflow, from trigger to review\n\n```text\nPrompt · GitHub issue · CI failure · Linear · Slack · Schedule · Webhook\n                                 │\n                                 ▼\n                   Choose machine + agent + model\n                     + supported credentials\n                                 │\n                                 ▼\n                         Live agent session\n                     Join · steer · approve · stop\n                                 │\n                                 ▼\n                    Changes · checks · artifacts · PR\n```\n\nA **Machine** is a computer or server you connect. A **Session** is live agent\nwork on that machine. A **Run** is delegated background work that creates a\nsession and tracks its outcome. An **Automation** is a reusable definition that\ncreates runs when an event matches.\n\nManual and automated work use the same kind of live session. You can join a run\nwhen it needs help rather than wait for a black-box job to finish.\n\n### Work in the environment you already have\n\nA clean cloud sandbox isn't always enough. Your agent may need the database\nrunning on localhost, an uncommitted change, an internal API behind your VPN,\nor a model running on your GPU. Bivy runs the agent where those things already\nexist, subject to that machine's permissions and the runtime's protection.\n\nConnect several machines to the same account: a laptop for interactive work,\na Linux server for background jobs, or a GPU box for local inference. Choose\nthe machine for each session or pin it in an automation. Repository runs can\nuse isolated Git worktrees without rebuilding the whole development environment.\n\n**The execution machine must stay awake and online.** To close your laptop and\nleave work running, run the agent on a different, always-on machine.\n\n[Environment and multi-machine recipes →](docs/capability-recipes.md)\n\n### Use multiple agents, not multiple disconnected workflows\n\nRun Claude Code for one task, Codex for another, and Pi or OpenCode where they\nfit. Bivy supplies the shared session, remote-access, automation, and review\nsurfaces; your chosen agent still does the coding and uses your model provider.\n\n- Choose an agent and, where supported, a model for each session or run.\n- Import existing Claude Code and Codex sessions.\n- Fork or move work to another agent or machine when a different setup fits\n  better. Continuation fidelity varies: some paths preserve native history,\n  while others replay portable turns or seed the destination with context.\n- Use agent-native logins, Bivy-managed credentials, or local inference.\n  Bivy's custom OpenAI-compatible endpoint registry currently feeds Pi;\n  other agents may need their own provider configuration.\n- Register your own ACP or headless process agent with `bivy agent add`.\n\nBivy does not replace your agent, provide model inference, or make every agent's\nfeatures identical. Consult the [support matrix](docs/runtime-support-matrix.md)\nand [handoff recipes](docs/capability-recipes.md#fork-or-move-a-session).\n\n### Less signing in. Less copying secrets.\n\nBivy syncs **Bivy-managed API keys and supported OAuth credentials** across\nenrolled machines for compatible runtimes. Connect supported credentials once\nand reuse them where you run work, rather than manually distributing keys to\neach machine.\n\nFor ordinary account sync, credentials are encrypted on the node before upload.\nThe control plane stores ciphertext and wrapped-key metadata; enrolled nodes\nshare access by wrapping the vault key to one another. Bivy Cloud does not\nreceive plaintext credentials through this sync path.\n\nYou can also keep credentials local, use labeled keys and project presets, or\nreference environment variables and 1Password instead of embedding secrets in\nconfiguration:\n\n```bash\nbivy provider login\nbivy credentials add anthropic work\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\n```\n\n**Not every CLI login syncs.** Native agent logins may still be per-machine;\nGitHub App private-key sync is separately opt-in. If you lose every node and\ndevice able to unwrap a vault, you must sign in to providers again. Explicit\nhosted-provisioning custody grants are separate from ordinary encrypted sync.\n\n[Credential sync and runtime coverage →](docs/credential-sync.md) ·\n[Credentials guide →](docs/credentials-guide.md) ·\n[Key storage →](docs/key-management.md)\n\n### Let events start the work\n\nAutomations turn recurring or incoming work into sessions you can join,\nsupervise, and review. Choose the repository, machine, agent, model, approval\nmode, sandbox setting, and maximum attempts.\n\n| Trigger | Example workflow |\n|---|---|\n| **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |\n| **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |\n| **Linear** | Label an issue to start work without copying its description into an agent. |\n| **Slack** | Send a request from the conversation where the work came up. |\n| **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |\n| **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |\n\nConfigure automations in the app or version them with your repository in\n`.bivy/automations.yaml`:\n\n```bash\nbivy automation init\n# Edit the generated definition for your repository and workflow.\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml  # supply a local event fixture\nbivy automation apply\n```\n\nOr delegate a one-off job without creating an automation:\n\n```bash\nbivy runs start \"Review outdated dependencies and propose a small, tested update.\"\nbivy runs wait <id>\n```\n\nRuns keep routing and lifecycle evidence, check results, and output references\nin a reviewable Receipt. For unattended issue work, Bivy runs declared repository\nchecks after the agent's turn; failed required checks fail the run even if the\nagent reports success. A completed process alone is not proof that the task\nsucceeded.\n\n[Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·\n[Automations as code →](docs/automations-as-code.md) ·\n[Run outcomes and reliability limits →](docs/automation-runs.md)\n\n### Start at your desk. Continue anywhere.\n\nOpen the same session in the browser, phone PWA, or terminal. Watch work live,\nanswer questions, approve supported tool calls, or stop the agent.\n\n- Send screenshots, images, logs, and other files from your phone.\n- Download reports and artifacts the agent creates.\n- Use voice input and read-aloud where supported; provider-backed voice may\n  send audio or text to the selected provider.\n- Keep a native terminal workflow or use structured chat, depending on the agent.\n\n```bash\nbivy run claude --no-follow  # start without attaching\nbivy open                    # open the web app\nbivy resume                  # return to the session in your terminal\nbivy link                    # pair a device directly via QR\n```\n\nNo phone app installation is required. Open [app.bivy.sh](https://app.bivy.sh)\nin your browser; adding it to your home screen is optional.\n\n[Remote access →](docs/remote-access.md) ·\n[Voice, files, and terminal recipes →](docs/capability-recipes.md)\n\n## Get started\n\n### Install\n\nBivy supports **macOS and Linux with Node.js 20+**. The installer installs the\n`@bivy/bivy` package, runs guided setup, and starts a launchd or systemd service:\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nSetup helps you choose an agent and configure remote access. Existing agents\nkeep their command, login, and configuration. The installer may use `sudo` to\ninstall missing Node.js or Debian/Ubuntu build tools, but never for `npm install`. To inspect it first,\ndownload it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.\n\nAlready have Node.js and want to avoid sudo?\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nThen try one small task:\n\n```bash\ncd your-repo\nbivy run claude\n# Ask: \"Explain this repo and make one small, safe improvement. Run the relevant checks.\"\nbivy open\n```\n\nOpen that same session on your phone while it runs. Once that works, connect\nanother machine or add your first automation.\n\n**Local-only works too.** `bivy run`, `bivy resume`, and `bivy sessions` need no\naccount or server. Choose **local only for now** during setup; use `bivy login`\nlater. Browser and phone access need a hosted or self-hosted control plane;\nthe node itself does not serve a web UI.\n\n[Full quickstart →](docs/quickstart.md) ·\n[Installer options, service management, and uninstall →](docs/install.md)\n\n### Choose hosted or self-hosted\n\n| Option | What you get |\n|---|---|\n| **Free Cloud — $0** | Every launch feature, including automations; 10 new remote sessions per rolling seven days. No credit card required. |\n| **Cloud — $15/month** | The same features with unlimited remote sessions. |\n| **Self-hosted Core** | Operate the app, control plane, and relay yourself, with no Bivy usage limits. |\n\nManual and automated sessions share the Cloud allowance. Resuming existing\nsessions and viewing history do not consume it. Agent subscriptions and model\nprovider charges are separate. See [current pricing](https://bivy.sh#pricing).\n\n**Self-host anywhere:** deploy the public control-plane (including the web app)\nand relay images with Postgres and [a small set of environment variables](docs/deploy-images.md).\nYour server or container platform handles HTTPS. Set up owner access in the\nbrowser—no SSH, external authentication provider, or Bivy Cloud account required.\nFor a bare VPS, the [Compose installer](docs/self-host-quickstart.md) automates the\nsame stack. These onboarding features require a release containing them.\n\nStart on Cloud and self-host later if you prefer. Deploy the stack, reconnect\nmachines with `bivy relay:setup`, and pair devices to your server. This is not a\none-click migration of your Cloud account; your local repos and agent\nconfiguration stay in place.\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nSelf-hosting is community-supported: you own TLS, backups, upgrades, and\nhardening. Public multi-architecture images are available as\n`ghcr.io/bivysh/bivy-control-plane` and `ghcr.io/bivysh/bivy-relay`; pin a release\nversion or full commit SHA.\n\n[Deploy the images anywhere →](docs/deploy-images.md) ·\n[Optional VPS installer →](docs/self-host-quickstart.md) ·\n[Operations reference →](docs/self-host.md)\n\n## Architecture\n\nYour environment, with clear security boundaries:\n\n```text\nYour machine                         Hosted or self-hosted\n┌──────────────────────┐             ┌──────────────────────┐\n│ Node daemon          │──outbound──▶│ Relay                │\n│ Agents, repos, tools │             │ Encrypted frames     │\n│ Local credentials    │             └──────────┬───────────┘\n└──────────────────────┘                        │\n                                    Browser / phone\n                                    + control plane\n                                    (app, accounts, metadata)\n```\n\n- **Execution stays on your machine.** Bivy Cloud does not run your agents.\n  Your model provider still sees whatever the agent sends it.\n- **Interactive traffic is end-to-end encrypted** between the node and paired\n  devices. The relay forwards opaque frames; your node dials out, so no inbound\n  public port is required.\n- **Ordinary credential sync uploads ciphertext, not plaintext keys.**\n  Supported credentials and recovery limits are documented separately.\n- **Encryption is not universal across integrations.** Slack commands and\n  generic webhook instructions reach the control plane in plaintext. Do not\n  put secrets in them. Routing and bounded run metadata are also visible there.\n- **Device authorization matters.** QR pairing authorizes a device directly\n  through the node. Hosted account pairing trusts the control plane to authorize\n  devices and serve the web app that holds client keys.\n- **Bivy is not an OS-level sandbox.** The default approval mode is\n  `autonomous`; protection depends on the runtime. Some agents enforce sandbox\n  tiers, while process agents may run with your full user permissions.\n  Heuristic tool checks help prevent accidents but are not isolation.\n\nReview the runtime's Protection label and configure approval/sandbox settings\nfor the task, especially before enabling unattended work.\n\n[Security model and known limitations →](docs/security-model.md) ·\n[Runtime protection matrix →](docs/runtime-support-matrix.md) ·\n[Configuration →](docs/configuration.md)\n\n## Agents and everyday commands\n\n**Claude Code, Codex, Pi, and OpenCode are release-tested.** Additional adapters\ninclude Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub Copilot,\nGrok, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,\nresume, model selection, and tool protection vary—see the\n[support matrix](docs/runtime-support-matrix.md) and [agent guides](docs/agents/README.md).\n\nRun an arbitrary command with `bivy run -- ./your-agent --flags`, register a\nreusable entry with `bivy agent add`, or package a declarative integration with\nexperimental [plugins](docs/plugins.md).\n\n```bash\nbivy run claude       # launch a durable session; also codex, pi, opencode\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires remote setup)\nbivy nodes            # list connected account machines\nbivy runs list        # inspect delegated work\nbivy automation init  # scaffold repo-owned automations\nbivy provider login   # connect supported model credentials\nbivy agent add        # register an ACP or process agent\nbivy doctor           # check installation and connectivity\nbivy logs -f          # follow node logs\nbivy update           # update and restart the service\n```\n\n`bivy update` uses your original installation method and waits for an active\nturn to finish before restarting. Use `--force` to skip that wait.\n\n[CLI reference →](docs/cli-reference.md) ·\n[Node and project configuration →](docs/config-as-code.md) ·\n[GitHub setup →](docs/github-setup.md) ·\n[Linear setup →](docs/linear-work-queue.md)\n\n## Development and contributions\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server\n```\n\n| Directory | Contents |\n|---|---|\n| `src/`, `bin/` | Node daemon, CLI, runtime adapters, sessions, approvals, secrets |\n| `packages/core/` | Shared protocol, pairing, and wire format |\n| `packages/web/`, `packages/ui/` | React PWA and shared design system |\n| `services/relay/` | Self-hostable encrypted relay |\n| `services/control-plane/` | Self-hostable control plane |\n| `deploy/` | Deployment examples |\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\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Releases\nare published from CI with provenance attestations; see\n[release verification](docs/releasing.md).\n\n**Found a security issue?** Use\n[GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new),\nnot a public issue. See [SECURITY.md](SECURITY.md).\n\n### In development—not available at launch\n\nAutomatically provisioned, short-lived **ephemeral machines** are in development\nfor hosted and bring-your-own-cloud deployments. Neither path is ready or\nsupported for this launch. Use an existing computer or server you operate.\nExperimental provisioning has different credential-custody and encryption\nboundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md).\n\n## License\n\nEverything in this repository—node, CLI, web/PWA, relay, and control plane—is\nfree and open-source **AGPL-3.0-only Core**, with no Bivy usage limits. You may\nuse, modify, and self-host it under that license. If users interact with your\nmodified version over a network, section 13 requires you to offer its\ncorresponding source. See [LICENSE](LICENSE).\n\nBivy Cloud is the hosted operation of that stack plus billing and plans, in a\nseparate private repository. Contributions use the\n[DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
   "readmeFilename": "README.md"