@bivy/bivy 0.1.0-staging.9 → 0.1.0

package/README.md

@@ -25,30 +25,83 @@ reports around agents you already use.
 curl -fsSL https://bivy.sh/install.sh | bash
 ```
 
-macOS and Linux. Requires Node 22.19 or newer; the installer sets it up if
-missing. It installs the [`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package
-from npm, then runs the guided `bivy setup` wizard — workspace, relay/control-
-plane sign-in, and an auto-start background service (launchd on macOS, systemd
-on Linux).
+macOS and Linux. Requires Node.js 22.19 or newer; the installer installs it for
+you on Debian/Ubuntu and otherwise points you at nodejs.org. It installs the
+[`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package from npm, puts
+the `bivy` command on your `PATH`, then runs the guided `bivy setup` wizard —
+workspace, relay/control-plane sign-in, 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.
 
-Already have Node? The installer is optional:
+Already have Node.js 22.19+? The installer is optional:
 
 ```bash
 npm install -g @bivy/bivy
 bivy setup
 ```
 
-Releases are published from CI with provenance attestations; verify with
-`npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).
+Or try it once without installing anything (`npx` always fetches the latest):
 
-Already have the repository checked out:
+```bash
+npx @bivy/bivy setup
+```
+
+Releases are published from CI with provenance attestations; verify a build's
+origin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).
+
+### Install options
+
+Environment variables passed to the one-line installer change what it does:
+
+| Goal | Variable |
+|---|---|
+| Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |
+| Pin an exact version | `BIVY_VERSION=0.1.0` |
+| Install without sudo, into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |
+| Preinstall every bundled agent runtime | `BIVY_INSTALL_ALL_AGENTS=1` |
+
+For example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.
+
+Working from a checkout of this repository instead:
 
 ```bash
 npm install
 npm run setup
 ```
 
-See [`docs/install.md`](docs/install.md) for service management and uninstall.
+See [`docs/install.md`](docs/install.md) for where data lives, service
+management, and uninstall.
+
+## Updating
+
+```bash
+bivy update
+```
+
+`bivy update` detects how Bivy was installed and does the right thing, then
+waits for any active session to finish its current turn and restarts the
+background service so the node reconnects on the new build:
+
+| Install kind | What `bivy update` does |
+|---|---|
+| npm global (`npm i -g`) | `npm install -g @bivy/bivy@<channel>`, then restart the service |
+| installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |
+| git checkout | `git pull --ff-only` + `npm ci`, then restart |
+| `npx` run | nothing to update — each run already fetches the latest |
+
+Updates follow the release **channel** recorded at install time — `latest`
+(production) by default, or `staging` if you installed with
+`BIVY_CHANNEL=staging`. Switch channels (the choice is remembered for next
+time), or skip the wait for a busy session:
+
+```bash
+bivy update --staging   # move to the dev channel
+bivy update --stable    # move back to production (latest)
+bivy update --force     # don't wait for an in-flight turn to finish
+```
+
+The daemon also checks the registry periodically and posts an in-session notice
+when a newer build is available.
 
 ## Architecture
 
@@ -90,7 +143,7 @@ Nineteen agents are available in the picker, each driven through its native inte
 | Pi | `bivy run pi` | Default; bundled |
 | Claude Code | `bivy run claude` | Bundled SDK |
 | Codex | `bivy run codex` | Installs `@openai/codex` |
-| OpenCode | `bivy run opencode` | Installs `opencode-ai/opencode` |
+| OpenCode | `bivy run opencode` | Installs `opencode-ai` |
 | Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |
 | Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |
 | Goose | `bivy run goose` | Requires `goose` on PATH |
@@ -154,7 +207,7 @@ If you want to be asked about more, set the mode explicitly:
 
 ```bash
 BIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits
-BIVY_APPROVAL_MODE=always   # prompt on every tool call
+BIVY_APPROVAL_MODE=always   # prompt on all shell commands and file edits
 BIVY_APPROVAL_MODE=never    # no prompts beyond the hard floor
 ```
 
@@ -178,8 +231,9 @@ bivy secrets ref github.repo-token op://Bivy/GitHub/repo-token
 bivy secrets doctor
 ```
 
-`secret://`, `env://`, and `op://` (1Password) references are resolved before the
-daemon starts. See [`docs/key-management.md`](docs/key-management.md).
+`secret://`, `env://`, and `op://` (1Password) references are resolved on demand
+when the daemon provisions an agent run, so the raw values never sit in your
+config. See [`docs/key-management.md`](docs/key-management.md).
 
 ## GitHub work queue
 
@@ -237,14 +291,30 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ## Self-hosting
 
-Node, relay, and control plane are all in this repository, and the CLI accepts
-flags to point at your own deployment:
+Node, relay, and control plane are all in this repository. Point a node at your
+own deployment by passing URLs to `bivy relay:setup` — re-running it switches an
+existing node over to the new endpoints:
 
 ```bash
-bivy relay:setup --relay wss://relay.example.com \
-                 --control-plane https://bivy.example.com
+bivy relay:setup \
+  --control-plane https://bivy.example.com \
+  --relay wss://relay.example.com
 ```
 
+Each URL has a flag and an environment-variable equivalent (the flag wins):
+
+| Flag | Environment variable | Points at | Default |
+|---|---|---|---|
+| `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |
+| `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |
+| `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |
+
+Sign-in defaults to GitHub device login (`--github`); pass
+`--email you@example.com` for an email magic-link, or `--session-token <token>`
+to skip interactive sign-in. `relay:setup` checks the control plane is reachable, enrolls
+this node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,
+`bivy link`, and `bivy update` all keep using your deployment afterwards.
+
 **Self-hosting is unsupported** — no SLA, community best-effort via GitHub
 issues. You own TLS, backups, upgrades, and hardening. See
 [`docs/self-host.md`](docs/self-host.md).

package/bin/bivy.mjs

@@ -37,6 +37,7 @@ import { selectStaleSessions, sessionActivityMs } from "./prune-sessions.mjs";
 import { resolveSessionsLimit, truncateSavedSessions } from "./sessions-list.mjs";
 import { renderManagedBlock, upsertManagedBlock, removeManagedBlock, rcFileForShell } from "./shim-path.mjs";
 import { removeExcept } from "./uninstall-paths.mjs";
+import { findAvailablePort, reconcilePort } from "./port-picker.mjs";
 
 const selfScript = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(selfScript);
@@ -403,6 +404,12 @@ function url(config) {
   return `http://localhost:${config.port}`;
 }
 
+// The host the node will bind (mirrors src/server.ts). We probe on this same
+// address so a "free" port here is one the daemon can actually claim.
+function nodeBindHost() {
+  return process.env.BIVY_HOST ?? process.env.HOST ?? "127.0.0.1";
+}
+
 // --- process helpers --------------------------------------------------------
 
 function run(cmd, args, opts = {}) {
@@ -2637,6 +2644,11 @@ async function installService(config) {
     console.log(c.yellow(`No background-service template for ${process.platform}. Use 'bivy start' instead.`));
     return false;
   }
+  // Re-check the port before baking it into the unit: a second node on this
+  // machine may have claimed the saved port since setup, and unlike `bivy setup`
+  // this path used to write it in verbatim (so the node would fail to bind and
+  // silently exit). reconcileNodePort persists any change into `config` first.
+  await reconcileNodePort(config);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   if (kind === "launchd") {
     fs.writeFileSync(file, plistContent(config));
@@ -2726,6 +2738,57 @@ function restartService() {
   return false;
 }
 
+// Is `config.port` currently held by *this install's own* node, as opposed to a
+// foreign node (a second OS user's, a staging+prod pair) or an unrelated
+// process? We ask whoever is listening for its data dir via /api/status and
+// compare to ours: our own node reports the same appDir; a foreign bivy node
+// reports a different one (or rejects our device token and throws); a non-bivy
+// process makes the request throw. Only a match counts as "ours", so port
+// reconciliation never relocates a node off a port it legitimately owns.
+async function portHeldByOwnNode(config) {
+  try {
+    const status = await localApi(config, "/api/status");
+    return Boolean(status?.appDir) && path.resolve(status.appDir) === path.resolve(appDir);
+  } catch {
+    return false;
+  }
+}
+
+// Re-validate the saved node port before it is baked into a service unit or
+// restarted into, rolling it forward (and persisting the new value) if a second
+// node on this machine has claimed it since setup. An explicit `PORT=…` is
+// honored verbatim. Returns true when the port changed, so the caller knows to
+// rewrite the unit whose PORT env is now stale. See reconcilePort() for the
+// decision rules. Our own running node is never treated as a collision.
+async function reconcileNodePort(config) {
+  const current = Number(config.port) || 4317;
+  const chosen = await reconcilePort(current, nodeBindHost(), {
+    explicitPort: Number(process.env.PORT),
+    heldByOwnNode: () => portHeldByOwnNode(config),
+  });
+  if (chosen === current) return false;
+  console.log(
+    c.yellow(`Port ${current} is already in use by another node on this machine — moving this node to ${chosen}.`),
+  );
+  config.port = chosen;
+  saveConfig(config);
+  return true;
+}
+
+// Restart the background service, but first make sure the port it will bind is
+// still free. If a foreign node grabbed it while ours was down, relocate: the
+// unit's baked-in PORT is now stale, so a full reinstall rewrites it (and
+// reloads/relaunches). Otherwise a plain restart. Returns true if the service
+// was (re)started. Used by `bivy restart` and `bivy update` — the paths that
+// previously trusted the saved port verbatim.
+async function restartServiceReconciled(config) {
+  const { file } = servicePaths();
+  if (fs.existsSync(file) && (await reconcileNodePort(config))) {
+    return await installService(config);
+  }
+  return restartService();
+}
+
 // How long a restart triggered by `bivy update`/`bivy restart` will wait for
 // in-flight agent turns to finish before restarting anyway. Restarting the
 // service SIGTERMs every open session's agent process; done mid-turn that
@@ -2994,11 +3057,27 @@ async function cmdSetup(args = []) {
   // defaults to a dedicated ~/bivy-workspace folder that won't collide with the
   // user's own projects; the local port is for this machine only (remote access
   // goes through the relay). Both are changeable later in Settings.
+  //
+  // Port selection auto-avoids collisions so multiple nodes on one machine (e.g.
+  // a staging + production node, or one node per OS user) "just work" without the
+  // user picking ports: an explicit `PORT=… bivy setup` is honored verbatim,
+  // otherwise we take the first free port at or above 4317. Without this the
+  // second node would default to 4317 too and silently fail to bind.
   if (!existingConfig || config.workspace === repoRoot) {
     const workspace = config.workspace !== repoRoot ? config.workspace : path.join(os.homedir(), "bivy-workspace");
     if (!fs.existsSync(workspace)) fs.mkdirSync(workspace, { recursive: true });
     config.workspace = workspace;
-    config.port = Number(config.port) || 4317;
+    const explicitPort = Number(process.env.PORT);
+    const savedPort = Number(config.port);
+    if (explicitPort) {
+      config.port = explicitPort;
+    } else {
+      const preferred = savedPort || 4317;
+      config.port = await findAvailablePort(preferred, nodeBindHost());
+      if (config.port !== preferred) {
+        console.log(c.dim(`Port ${preferred} is already in use (another node?) — using ${config.port} for this node.`));
+      }
+    }
     saveConfig(config);
   }
   console.log(c.dim(`Workspace: ${config.workspace}  ·  local port: ${config.port}  (change both in Settings)`));
@@ -3532,7 +3611,7 @@ async function runUpdate(args = []) {
     await ensureBundledAgents();
     const config = loadConfig();
     await waitForIdleSessions(config, { skip: skipWait });
-    if (config.service && restartService()) {
+    if (config.service && (await restartServiceReconciled(config))) {
       console.log(c.green("Updated and restarted the background service."));
     } else {
       console.log(c.green("Updated. Run 'bivy start' (or restart your service) to apply."));
@@ -3568,7 +3647,7 @@ async function runUpdate(args = []) {
   await ensureBundledAgents();
   const config = loadConfig();
   await waitForIdleSessions(config, { skip: skipWait });
-  if (config.service && restartService()) {
+  if (config.service && (await restartServiceReconciled(config))) {
     console.log(c.green("Updated and restarted the background service."));
   } else {
     console.log(c.green("Updated. Run 'bivy start' (or restart your service) to apply."));
@@ -4014,8 +4093,10 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
         console.log("Usage: bivy restart [--force|--no-wait]\n\nRestart the background service. Waits for active sessions to finish a turn first; --force/--no-wait skips the wait.");
         break;
       }
-      await waitForIdleSessions(loadConfig(), { skip: args.includes("--force") || args.includes("--no-wait") });
-      if (restartService()) {
+      {
+      const restartConfig = loadConfig();
+      await waitForIdleSessions(restartConfig, { skip: args.includes("--force") || args.includes("--no-wait") });
+      if (await restartServiceReconciled(restartConfig)) {
         console.log(c.green("Service restarted."));
       } else if (fs.existsSync(servicePaths().file)) {
         console.error(c.red("Failed to restart the background service."));
@@ -4028,6 +4109,7 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
         console.log(c.yellow("No background service to restart. Run 'bivy setup' to install one so the node stays reachable."));
         process.exitCode = 1;
       }
+      }
       break;
     case "status":
       await cmdStatus(args);

package/bin/port-picker.mjs

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Free-port selection for `bivy setup`, extracted so it can be unit-tested
+// without executing the CLI (bin/bivy.mjs runs main() on import).
+//
+// Background: every node defaulted its local port to 4317, and setup never
+// checked whether that port was already taken. Running a second node on the same
+// machine — a staging + production node, or one node per OS user — therefore
+// collided: the loopback address 127.0.0.1:4317 is machine-wide, not per-user,
+// so whichever node started second failed to bind. Users had to discover this
+// and hand-pick a port. Setup now takes the first free port at or above the
+// preferred one, so additional nodes land on 4318, 4319, … automatically.
+import net from "node:net";
+
+// Is `port` bindable on `host` right now? Resolves false on EADDRINUSE (another
+// node/process already holds it — the exact collision two nodes hit when both
+// default to 4317), true when the port is free, and true on any other error so a
+// probe quirk never blocks setup on an otherwise-usable port.
+export function portIsFree(port, host) {
+  return new Promise((resolve) => {
+    const tester = net.createServer();
+    tester.once("error", (err) => {
+      tester.close();
+      resolve(err?.code !== "EADDRINUSE");
+    });
+    tester.once("listening", () => tester.close(() => resolve(true)));
+    tester.listen(port, host);
+  });
+}
+
+// First free port at or after `preferred`, so a second node on the same machine
+// lands on 4318, 4319, … automatically instead of failing to bind. Falls back to
+// `preferred` if the whole scan window is somehow busy (the daemon then reports a
+// clear EADDRINUSE rather than the CLI hanging). `isFree` is injectable for tests.
+export async function findAvailablePort(preferred, host, isFree = portIsFree) {
+  for (let port = preferred; port < preferred + 100; port++) {
+    if (await isFree(port, host)) return port;
+  }
+  return preferred;
+}
+
+// Decide which port a node should (re)start on, re-validating a *saved* port
+// right before it is baked into a service unit or restarted into. `bivy setup`
+// already auto-avoids collisions, but `bivy service install`, `bivy restart` and
+// `bivy update` used to trust the saved port verbatim — so a node whose 4317 had
+// since been claimed by a second node on the same machine would fail to bind
+// (EADDRINUSE) and silently exit. Rules, in order:
+//   - an explicit `PORT=…` override wins verbatim (the operator pinned it);
+//   - a free port is kept as-is (the common case — no collision);
+//   - a port still held by *our own* node is kept (a plain restart must not
+//     relocate a node off the port it already owns — `heldByOwnNode` tells ours
+//     apart from a foreign occupant);
+//   - otherwise roll forward to the first free port above it.
+// `isFree` and `heldByOwnNode` are injectable so the decision is unit-testable
+// without sockets or a live node. Returns the chosen port; callers compare it to
+// the current one to decide whether to persist and rewrite the unit.
+export async function reconcilePort(current, host, {
+  explicitPort = 0,
+  isFree = portIsFree,
+  heldByOwnNode = async () => false,
+} = {}) {
+  const pinned = Number(explicitPort);
+  if (pinned) return pinned;
+  const port = Number(current) || 4317;
+  if (await isFree(port, host)) return port;
+  if (await heldByOwnNode(port, host)) return port;
+  return findAvailablePort(port + 1, host, isFree);
+}

package/dist/server.js

@@ -66,6 +66,7 @@ import { thinkingTextFromContent } from "./session/transcript-merge.js";
 import { normalizeMessages } from "./session/transcript-normal.js";
 import { buildNativeImportSeedPrompt } from "./session/native-import.js";
 import { EventLog } from "./session/event-log.js";
+import { AttachmentStore, isValidAttachmentHash } from "./session/attachment-store.js";
 import { ReplicationService } from "./session/replication-service.js";
 import { createSessionNewDedupe } from "./session/session-new-dedupe.js";
 import { evaluateForkPrereqs, blockingForkPrereqs, missingForkPrereqs } from "./session/fork-prereqs.js";
@@ -855,9 +856,12 @@ function safeAttachmentName(value) {
     return String(value || "attachment").replace(/[\r\n]/g, " ").slice(0, 180);
 }
 /**
- * Split composer attachments into three channels:
+ * Split composer attachments into channels:
  *   - `images`     — base64 blobs passed to the model as vision.
  *   - `imageNotes` — one prose line per image for the persisted transcript.
+ *   - `imageRefs`  — durable AttachmentStore references for the images, persisted
+ *                    in the event log so they rehydrate after a reload / on
+ *                    another device (images used to be vision-only, then lost).
  *   - `files`      — decoded file attachments (bytes or text) to be written to
  *                    disk by materializeAttachments so the agent can open them
  *                    with its normal file tools. Any file type is supported;
@@ -865,9 +869,10 @@ function safeAttachmentName(value) {
  */
 function attachmentsFrom(value) {
     if (!Array.isArray(value))
-        return { images: [], imageNotes: [], files: [] };
+        return { images: [], imageNotes: [], imageRefs: [], files: [] };
     const images = [];
     const imageNotes = [];
+    const imageRefs = [];
     const files = [];
     for (const raw of value.slice(0, 12)) {
         if (!raw || typeof raw !== "object")
@@ -877,8 +882,17 @@ function attachmentsFrom(value) {
         const size = Number(attachment.size || 0);
         const mimeType = typeof attachment.mimeType === "string" && attachment.mimeType ? attachment.mimeType : undefined;
         if (attachment.kind === "image" && typeof attachment.data === "string") {
-            images.push({ type: "image", data: attachment.data, mimeType: mimeType ?? "image/png" });
+            const imgMime = mimeType ?? "image/png";
+            images.push({ type: "image", data: attachment.data, mimeType: imgMime });
             imageNotes.push(`[Image attachment: ${name}${size ? ` (${size} bytes)` : ""}]`);
+            // Persist the image bytes durably (dedup by hash). Best-effort: a store
+            // failure must not break vision for the turn, so it only costs the ref.
+            try {
+                imageRefs.push(attachmentStore.put(Buffer.from(attachment.data, "base64"), { name, mimeType: imgMime, kind: "image" }));
+            }
+            catch (error) {
+                console.warn("[attachments] failed to store image:", error instanceof Error ? error.message : String(error));
+            }
         }
         else if (attachment.kind === "file") {
             if (typeof attachment.data === "string" && attachment.data) {
@@ -891,7 +905,7 @@ function attachmentsFrom(value) {
             // nothing to write, so there is nothing to hand the agent — skip it.
         }
     }
-    return { images, imageNotes, files };
+    return { images, imageNotes, imageRefs, files };
 }
 /** Strip a user-supplied filename to a safe basename — no path traversal, no
  * characters that would break the placeholder note or the filesystem. */
@@ -914,7 +928,22 @@ function sanitizeAttachmentFilename(name) {
  */
 function materializeAttachments(record, files) {
     if (!files.length)
-        return "";
+        return { note: "", refs: [] };
+    const refs = [];
+    // Store every file durably in the global content-addressed store first (for
+    // re-findability), independent of the per-workdir copy below. Best-effort per
+    // file so one bad blob doesn't lose the others.
+    for (const file of files) {
+        const bytes = file.bytes ?? (typeof file.text === "string" ? Buffer.from(file.text, "utf8") : undefined);
+        if (!bytes)
+            continue;
+        try {
+            refs.push(attachmentStore.put(bytes, { name: sanitizeAttachmentFilename(file.name), mimeType: file.mimeType, kind: "file" }));
+        }
+        catch (error) {
+            console.warn("[attachments] failed to store file:", error instanceof Error ? error.message : String(error));
+        }
+    }
     const workdir = harnessDirFor(record);
     const dir = path.join(workdir, ".bivy-attachments");
     try {
@@ -922,7 +951,7 @@ function materializeAttachments(record, files) {
     }
     catch (error) {
         const why = error instanceof Error ? error.message : String(error);
-        return files.map((f) => `[File attachment: ${sanitizeAttachmentFilename(f.name)} could not be saved: ${why}]`).join("\n");
+        return { note: files.map((f) => `[File attachment: ${sanitizeAttachmentFilename(f.name)} could not be saved: ${why}]`).join("\n"), refs };
     }
     const notes = [];
     const used = new Set();
@@ -953,7 +982,7 @@ function materializeAttachments(record, files) {
             notes.push(`[File attachment: ${label} could not be saved: ${error instanceof Error ? error.message : String(error)}]`);
         }
     }
-    return notes.join("\n");
+    return { note: notes.join("\n"), refs };
 }
 function approvalModeFrom(value) {
     return value === "never" || value === "risky" || value === "always" || value === "autonomous" ? value : undefined;
@@ -1971,6 +2000,12 @@ function eventLogPath(sessionId) {
 // eventLog.deriveHistory. `redactSecrets` scrubs credentials at the single flush
 // choke point before anything lands on the synced-to-PWA disk.
 const eventLog = new EventLog(eventLogDir, eventLogPath, redactSecrets);
+// Global content-addressed store for message attachments (images + files). Unlike
+// the per-session `.bivy-attachments/` worktree copy (kept so the agent can open
+// files with its tools), this is durable, session-independent, and re-findable:
+// the transcript references blobs by hash, and clients rehydrate thumbnails by
+// hash after a reload or on another device. See src/session/attachment-store.ts.
+const attachmentStore = new AttachmentStore(path.join(appDir, "attachments"));
 // --- Warm session replication (docs/session-replication.md) -----------------
 // A standby's replica repo lives under appDir/replicas/<id>: a self-contained git
 // repo that receives checkpoint bundles and is checked out on promotion. Created
@@ -2228,6 +2263,9 @@ function buildHistoryEvent(opts) {
         prUrl: record?.prUrl ?? opts.prUrl,
         prs: record?.prs ?? opts.prs,
         bivySession: bSess,
+        // Durable attachment references (text→refs), so a client that never sent the
+        // attachment (a reload, or a different device) rehydrates thumbnails by hash.
+        attachmentRefs: opts.sessionId ? eventLog.readAttachments(opts.sessionId) : [],
     };
 }
 // Idempotency for `session.new` keyed by requestId: a client's post-reconnect
@@ -2248,6 +2286,27 @@ const RELAY_COMMANDS = {
     ping(msg, ctx) {
         ctx.reply({ type: "pong", requestId: typeof msg.requestId === "string" ? msg.requestId : undefined });
     },
+    // Fetch a stored attachment's bytes by content hash. The relay client (a phone
+    // not on the LAN) can't reach the GET /api/attachment endpoint, so it fetches
+    // over the encrypted tunnel instead; the relay framing chunks the base64 payload
+    // (the same mechanism that carries large image uploads). Direct/LAN clients use
+    // the HTTP endpoint. Both are authenticated — the relay tunnel by enrollment,
+    // the HTTP route by /api's authMiddleware.
+    "attachment.fetch"(msg, ctx) {
+        const requestId = typeof msg.requestId === "string" ? msg.requestId : undefined;
+        const hash = typeof msg.hash === "string" ? String(msg.hash) : "";
+        if (!isValidAttachmentHash(hash)) {
+            ctx.reply({ type: "attachment.error", requestId, hash, error: "Invalid attachment id" });
+            return;
+        }
+        const bytes = attachmentStore.read(hash);
+        if (!bytes) {
+            ctx.reply({ type: "attachment.error", requestId, hash, error: "Attachment not found" });
+            return;
+        }
+        const meta = attachmentStore.readMeta(hash);
+        ctx.reply({ type: "attachment.data", requestId, hash, mimeType: meta?.mimeType ?? "application/octet-stream", name: meta?.name, data: bytes.toString("base64") });
+    },
     "session.pause"(msg) {
         const record = resolveSession(msg.sessionId);
         if (record)
@@ -3039,7 +3098,7 @@ const RELAY_COMMANDS = {
     },
     async prompt(msg) {
         const text = String(msg.text ?? "").trim();
-        const { images, imageNotes, files } = attachmentsFrom(msg.attachments);
+        const { images, imageNotes, imageRefs, files } = attachmentsFrom(msg.attachments);
         if (!text && !images.length && !files.length)
             return;
         // Title/naming can only see what we have before the session exists; the file
@@ -3077,9 +3136,12 @@ const RELAY_COMMANDS = {
         touchSession(record);
         // Now that the session (and its workdir) exists, write file attachments to
         // disk and fold their path notes into the prompt the agent actually sees.
-        const fileNote = materializeAttachments(record, files);
+        const { note: fileNote, refs: fileRefs } = materializeAttachments(record, files);
         const promptText = [text, imageNotes.join("\n"), fileNote].filter(Boolean).join("\n\n") ||
             (images.length ? "Please review the attached image(s)." : files.length ? "Please review the attached file(s)." : "");
+        // Persist durable attachment refs keyed by the exact text the transcript
+        // stores for this user message, so history rehydrates thumbnails by hash.
+        eventLog.appendAttachments(record.id, promptText, [...imageRefs, ...fileRefs]);
         const agentPrompt = promptForAgent(record, promptText);
         const cmid = typeof msg.clientMessageId === "string" && msg.clientMessageId ? msg.clientMessageId : undefined;
         void dedupePrompt(cmid, async () => {
@@ -6340,7 +6402,10 @@ function maybeRenameWorktreeBranch(record, name) {
     const result = spawnSync("git", ["-C", wt.path, "branch", "-m", wt.branch, next], { encoding: "utf8", timeout: 10_000 });
     if (result.error || result.status !== 0) {
         const detail = String(result.stderr || result.error || "git branch rename failed").trim();
-        console.warn(`[branch-rename] could not rename ${wt.branch} to ${next}:`, detail);
+        // Pass the branch names as args, not spliced into the format string: a branch
+        // name containing a %-specifier would otherwise be interpreted by console.warn
+        // (CodeQL js/tainted-format-string).
+        console.warn("[branch-rename] could not rename %s to %s:", wt.branch, next, detail);
         return;
     }
     wt.branch = next;
@@ -9023,13 +9088,31 @@ app.get("/api/repos", async (_req, res) => {
 app.get("/api/repos/branches", async (req, res) => {
     res.json(await listRepoBranches(String(req.query.repo || "").trim()));
 });
+// Serve a stored attachment's bytes by content hash (direct/LAN clients). Behind
+// /api's authMiddleware. Content-addressed, so responses are immutably cacheable.
+// The hash is validated to a 64-char hex before it ever touches a path.
+app.get("/api/attachment/:hash", (req, res) => {
+    const hash = String(req.params.hash || "");
+    if (!isValidAttachmentHash(hash))
+        return res.status(400).json({ error: "Invalid attachment id" });
+    const bytes = attachmentStore.read(hash);
+    if (!bytes)
+        return res.status(404).json({ error: "Attachment not found" });
+    const meta = attachmentStore.readMeta(hash);
+    res.setHeader("Content-Type", meta?.mimeType || "application/octet-stream");
+    res.setHeader("Content-Length", String(bytes.length));
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    // Content-addressed: the bytes for a hash never change, so cache aggressively.
+    res.setHeader("Cache-Control", "private, max-age=31536000, immutable");
+    res.end(bytes);
+});
 app.post("/api/session/prompt", async (req, res, next) => {
     try {
         const text = String(req.body?.text ?? "").trim();
         if (text === "/login" || text.startsWith("/login ")) {
             return res.status(400).json({ error: "Use the Login / API tokens dialog from the phone UI. If it is not visible, refresh this page after updating Bivy." });
         }
-        const { images, imageNotes, files } = attachmentsFrom(req.body?.attachments);
+        const { images, imageNotes, imageRefs, files } = attachmentsFrom(req.body?.attachments);
         if (!text && !images.length && !files.length)
             return res.status(400).json({ error: "Missing text" });
         // File notes (with on-disk paths) are folded in once the workdir exists; the
@@ -9052,9 +9135,10 @@ app.post("/api/session/prompt", async (req, res, next) => {
             return res.status(409).json({ error: record.tuiRefreshing ? "This session is returning from the terminal. Try again in a moment." : "This session is open in the terminal (TUI). Close the TUI to chat here." });
         }
         const session = record.session;
-        const fileNote = materializeAttachments(record, files);
+        const { note: fileNote, refs: fileRefs } = materializeAttachments(record, files);
         const promptText = [text, imageNotes.join("\n"), fileNote].filter(Boolean).join("\n\n") ||
             (images.length ? "Please review the attached image(s)." : files.length ? "Please review the attached file(s)." : "");
+        eventLog.appendAttachments(record.id, promptText, [...imageRefs, ...fileRefs]);
         const agentPrompt = promptForAgent(record, promptText);
         const cmid = typeof req.body?.clientMessageId === "string" && req.body.clientMessageId ? req.body.clientMessageId : undefined;
         markSessionWorking(record, { type: "agent_start" });
@@ -9304,6 +9388,23 @@ const server = app.listen(port, host, async () => {
     if (!process.env.BIVY_MCP_ENDPOINT)
         process.env.BIVY_MCP_ENDPOINT = `http://127.0.0.1:${port}`;
 });
+// A failed bind is fatal and must be reported, not swallowed. `app.listen` emits
+// the error on the server; with no handler it reaches the global
+// `uncaughtException` net below, which keeps the process alive — leaving a node
+// that is "running" but listening on nothing. The common cause is another node
+// already on this port (two OS users, or a staging + production node, both
+// defaulting to 4317). Print an actionable message and exit so the supervisor
+// and `bivy logs` surface a real failure instead of a silent hang.
+server.on("error", (error) => {
+    if (error.code === "EADDRINUSE") {
+        console.error(`[bivy] Port ${port} is already in use — another Bivy node or process holds ${host}:${port}. ` +
+            `Give this node its own port (set PORT, or re-run 'bivy setup', which now picks a free one automatically) and start it again.`);
+    }
+    else {
+        console.error(`[bivy] Could not bind ${host}:${port}:`, error);
+    }
+    process.exit(1);
+});
 const wss = new WebSocketServer({ server, path: "/ws" });
 wss.on("connection", (socket, req) => {
     // Reject cross-origin / DNS-rebinding upgrades before auth: loopback bypasses

package/dist/session/attachment-store.js

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Content-addressed blob store for message attachments (images + files).
+//
+// Attachments used to be fragile and un-refindable: image bytes were passed to
+// the model as vision for a single turn and then dropped entirely (never written
+// anywhere), while file attachments were written only into the session's
+// ephemeral worktree at `<workdir>/.bivy-attachments/`. Nothing survived in a
+// stable, session-independent location, so a reload on another device — or after
+// the client's in-memory attachment cache aged out — showed only a bare
+// "[Image attachment: …]" placeholder.
+//
+// This store fixes that: every attachment is written ONCE to a global folder
+// under `<appDir>/attachments/`, addressed by the SHA-256 of its bytes. Identical
+// bytes dedupe for free (same hash → same path), the location is stable and
+// re-findable, and the transcript references a blob by hash instead of carrying
+// (or losing) the bytes. Paths are two-level sharded (`ab/cd/<hash>`) so a busy
+// node never piles millions of entries into one directory. A small sidecar
+// `<hash>.json` remembers a human name / mime / size for the blob.
+//
+// Out of scope for now (tracked as TODOs): garbage-collecting blobs no transcript
+// references any more, and a global size cap / LRU eviction on the store.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/** A 64-char lowercase-hex SHA-256, the only shape a valid hash can take. */
+const HASH_RE = /^[0-9a-f]{64}$/;
+/** Whether `value` is a well-formed content hash (guards path building). */
+export function isValidAttachmentHash(value) {
+    return typeof value === "string" && HASH_RE.test(value);
+}
+/**
+ * A global, content-addressed attachment store rooted at a single directory.
+ * All methods are best-effort and synchronous, matching the surrounding
+ * server code (EventLog, SidecarStore) — attachment persistence must never sink
+ * a turn, so a write failure surfaces as a thrown error the caller degrades to a
+ * text note rather than a crash.
+ */
+export class AttachmentStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** `<dir>/ab/cd` for a hash beginning `abcd…`. */
+    shardDir(hash) {
+        return path.join(this.dir, hash.slice(0, 2), hash.slice(2, 4));
+    }
+    blobPath(hash) {
+        return path.join(this.shardDir(hash), hash);
+    }
+    metaPath(hash) {
+        return path.join(this.shardDir(hash), `${hash}.json`);
+    }
+    /**
+     * Store `bytes` and return a durable reference. Content-addressed, so calling
+     * this twice with identical bytes writes the blob once and returns the same
+     * hash. The blob write is skipped when the file already exists (dedupe); the
+     * sidecar is written only the first time so the earliest name/mime wins.
+     */
+    put(bytes, opts) {
+        const hash = crypto.createHash("sha256").update(bytes).digest("hex");
+        const ref = { hash, name: opts.name, mimeType: opts.mimeType, size: bytes.length, kind: opts.kind };
+        fs.mkdirSync(this.shardDir(hash), { recursive: true });
+        const blob = this.blobPath(hash);
+        if (!fs.existsSync(blob))
+            fs.writeFileSync(blob, bytes);
+        if (!fs.existsSync(this.metaPath(hash))) {
+            const meta = { ...ref, createdAt: Date.now() };
+            try {
+                fs.writeFileSync(this.metaPath(hash), JSON.stringify(meta));
+            }
+            catch {
+                // A missing sidecar only costs us the remembered name/mime — the blob is
+                // what matters, so never let a sidecar write failure fail the store.
+            }
+        }
+        return ref;
+    }
+    /** The blob's metadata, or null if the hash is unknown/malformed. */
+    readMeta(hash) {
+        if (!isValidAttachmentHash(hash))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(this.metaPath(hash), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The on-disk path of a stored blob, or null if absent/malformed. */
+    getPath(hash) {
+        if (!isValidAttachmentHash(hash))
+            return null;
+        const blob = this.blobPath(hash);
+        return fs.existsSync(blob) ? blob : null;
+    }
+    /** Read a stored blob's raw bytes, or null if absent/malformed. */
+    read(hash) {
+        const p = this.getPath(hash);
+        if (!p)
+            return null;
+        try {
+            return fs.readFileSync(p);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/session/event-log.js

@@ -40,8 +40,35 @@ function isBase(value) {
     const record = value;
     return record.bivyKind === "base" && Array.isArray(record.messages) && typeof record.reset === "boolean";
 }
+function isAttachment(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.bivyKind === "attachment" && typeof record.text === "string" && Array.isArray(record.refs);
+}
 function isRecord(value) {
-    return isOverlay(value) || isBase(value);
+    return isOverlay(value) || isBase(value) || isAttachment(value);
+}
+/**
+ * Fold attachment records into a text→refs list: last write wins per text (a
+ * resent identical prompt re-keys onto the newest refs), preserving first-seen
+ * order. `mergeTranscript` never sees these — the client matches them onto the
+ * user messages by their persisted text, exactly as its in-memory attachment
+ * cache did, but now sourced durably from the log.
+ */
+export function replayAttachments(entries) {
+    const byText = new Map();
+    for (const entry of entries) {
+        if (entry.bivyKind !== "attachment")
+            continue;
+        if (!entry.text || !entry.refs.length)
+            continue;
+        // delete+set so a re-keyed text moves to the end (newest), matching the
+        // client's rememberAttachments last-wins semantics.
+        byText.delete(entry.text);
+        byText.set(entry.text, entry.refs);
+    }
+    return [...byText.entries()];
 }
 /**
  * Fold the intermediate-reasoning entries exactly as the legacy incremental
@@ -243,6 +270,22 @@ export class EventLog {
         this.baseKeys.set(id, nextKeys);
         this.enqueue(id, this.syntheticKey(id), record);
     }
+    /**
+     * Record the attachment references a user sent with a prompt, keyed by the
+     * prompt's persisted text. Id-less (synthetic key) so successive prompts never
+     * coalesce. A no-op when there are no refs.
+     */
+    appendAttachments(id, text, refs) {
+        if (!text || !refs.length)
+            return;
+        this.load(id);
+        const record = { bivyKind: "attachment", createdAt: Date.now(), text, refs: refs.map((r) => ({ ...r })) };
+        this.enqueue(id, this.syntheticKey(id), record);
+    }
+    /** Replay the attachment records (disk + pending) into a text→refs list. */
+    readAttachments(id) {
+        return replayAttachments(this.entries(id));
+    }
     /** Replay the overlay entries (disk + pending) into the flat `extras` list. */
     read(id) {
         return replayExtras(this.entries(id));

package/package.json

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