@bivy/bivy 0.3.0 → 0.4.0-staging.51

package/bin/bivy.mjs

@@ -1528,7 +1528,7 @@ function cmdCompletions(args = []) {
   const shell = (args[0] || "").toLowerCase();
   const commands = [
     "run", "sessions", "ls", "resume", "promote", "rename", "nodes", "agents", "agents:install", "shim", "takeover", "token", "exec",
-    "send", "kill", "setup", "start", "stop", "restart", "status", "doctor", "logs", "login",
+    "send", "attach", "kill", "setup", "start", "stop", "restart", "status", "doctor", "logs", "login",
     "update", "update:log", "open", "service", "secrets", "voice", "link", "relay:setup",
     "github:connect", "github:app-create", "github:app-connect", "github:app-sync", "prune", "uninstall", "help", "version",
   ];
@@ -1974,6 +1974,62 @@ async function cmdSend(args = []) {
   process.exit(code);
 }
 
+// `bivy attach <file> [--caption "…"] [--session <id>]` — surface a file the
+// agent produced into the chat as an image/file attachment (the reverse of the
+// composer paperclip). The universal path: any agent that can run a shell command
+// can call this. The session id defaults to $BIVY_SESSION_ID, which the daemon
+// injects into the agent's subprocess env. The file is resolved to an absolute
+// path here (the CLI's cwd is the agent's workdir) and confined to the session
+// workspace server-side.
+async function cmdAttach(args = []) {
+  const flag = (name) => {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+  };
+  const sessionId = flag("--session") || process.env.BIVY_SESSION_ID;
+  const caption = flag("--caption");
+  const name = flag("--name");
+  const mimeType = flag("--mime") || flag("--mimeType");
+  const flagsWithValue = new Set(["--session", "--caption", "--name", "--mime", "--mimeType"]);
+  // First positional that isn't a flag or a flag's value.
+  let file;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("-")) { if (flagsWithValue.has(a)) i++; continue; }
+    if (i > 0 && flagsWithValue.has(args[i - 1])) continue;
+    file = a;
+    break;
+  }
+  if (!file) { console.error(c.red('Usage: bivy attach <file> [--caption "…"] [--session <id>]')); process.exit(1); return; }
+  if (!sessionId) { console.error(c.red("No session id. Set --session <id> or run inside an agent session ($BIVY_SESSION_ID).")); process.exit(1); return; }
+  const absPath = path.resolve(process.cwd(), file);
+  if (!fs.existsSync(absPath)) { console.error(c.red(`File not found: ${file}`)); process.exit(1); return; }
+
+  const config = loadConfig();
+  if (!(await ensureNodeRunning(config))) { console.error(c.red(`Could not reach the Bivy node at ${url(config)}.`)); process.exit(1); return; }
+  // A token isn't required on a single-user host (loopback bypasses auth), but
+  // include it when available so multi-user hosts work too.
+  let token;
+  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const headers = { "content-type": "application/json" };
+  if (token) headers.authorization = `Bearer ${token}`;
+  let res;
+  try {
+    res = await fetch(`${url(config)}/api/session/${encodeURIComponent(sessionId)}/attach`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ path: absPath, caption, name, mimeType }),
+    });
+  } catch (error) {
+    console.error(c.red(`Could not reach the Bivy node: ${error?.message || String(error)}`));
+    process.exit(1);
+    return;
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) { console.error(c.red(`Attach failed (${res.status}): ${body?.error || "unknown error"}`)); process.exit(1); return; }
+  console.log(c.green(`Attached ${body.name} (${body.kind}, ${body.size} bytes) to the chat.`));
+}
+
 // Map a saved session's runtime id to the `bivy run` agent whose native CLI can
 // resume it in a terminal. Only agents with a real native resume qualify; other
 // runtimes (generic-cli, SDK-only) have no terminal resume and open in the web app.
@@ -4128,6 +4184,9 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "send":
       await cmdSend(args);
       break;
+    case "attach":
+      await cmdAttach(args);
+      break;
     case "completions":
     case "completion":
       cmdCompletions(args);

package/dist/control-plane-tasks.js

@@ -117,6 +117,11 @@ export class ControlPlaneTaskPoller {
     poke() {
         void this.tick();
     }
+    /** Number of queue items currently running on this node. Lets an ephemeral
+     *  machine's self-teardown avoid exiting while it's mid-work. */
+    inFlightCount() {
+        return this.inFlight.size;
+    }
     /**
      * Replace the routing labels this live poller serves.
      *

package/dist/device-registry.js

@@ -6,6 +6,26 @@ import { randomUUID } from "node:crypto";
 import { generatePairingKeypair, generateRoomKey, generatePairSecret, deriveWrapKey, verifyPairingProof, wrapRoomKey, } from "./pairing-crypto.js";
 import { seal, open } from "./e2e.js";
 const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
+const ROOM_KEY_BYTES = 32;
+/**
+ * Validate + canonicalize a pre-shared room-key seed. Returns the canonical
+ * base64 of a well-formed 32-byte key, or undefined for anything malformed
+ * (missing, wrong length, non-base64) so the caller falls back to a fresh key
+ * rather than adopting a bad seed that would make every device unable to decrypt.
+ */
+function normalizeSeedRoomKey(seedRoomKeyB64) {
+    if (!seedRoomKeyB64)
+        return undefined;
+    try {
+        const buf = Buffer.from(seedRoomKeyB64, "base64");
+        if (buf.length !== ROOM_KEY_BYTES)
+            return undefined;
+        return buf.toString("base64");
+    }
+    catch {
+        return undefined;
+    }
+}
 export class PairingStore {
     filePath;
     data;
@@ -18,8 +38,17 @@ export class PairingStore {
      * Load (or create) the pairing state. A fresh state gets a randomly generated
      * room key; devices receive it (and every later rotation) over the X25519
      * pairing handshake, so there is no static seed to carry forward.
+     *
+     * `seedRoomKeyB64` (base64 32-byte key) is the ONE exception: an ephemeral
+     * REBUILD reuses a torn-down session's node id and must decrypt a snapshot
+     * sealed under that session's original room key. The launching device/CP bakes
+     * that key into relay.json (`e2eKey`) and the daemon passes it here, so a
+     * brand-new pairing state adopts it instead of minting a fresh one. It is used
+     * ONLY when there is no existing pairing.json — an already-paired node never
+     * has its room key overwritten. An absent/malformed seed falls back to a fresh
+     * random key (the ordinary first-run path).
      */
-    static load(appDir) {
+    static load(appDir, seedRoomKeyB64) {
         const filePath = path.join(appDir, "pairing.json");
         let raw;
         try {
@@ -55,9 +84,12 @@ export class PairingStore {
                 devices: Array.isArray(parsed.devices) ? parsed.devices : [],
             });
         }
+        // No pairing.json yet — first run. Adopt a valid pre-shared seed (ephemeral
+        // rebuild) if one was supplied; otherwise mint a fresh random room key.
+        const seededRoomKey = normalizeSeedRoomKey(seedRoomKeyB64);
         const data = {
             nodeKeypair: generatePairingKeypair(),
-            roomKeyB64: generateRoomKey().toString("base64"),
+            roomKeyB64: seededRoomKey ?? generateRoomKey().toString("base64"),
             devices: [],
         };
         const store = new PairingStore(filePath, data);

package/dist/ephemeral-exec.js

@@ -16,6 +16,7 @@ export const EPHEMERAL_ALLOWED_HOSTS = new Set([
     "api.machines.dev",
     "api.fly.io",
     "api.sprites.dev",
+    "api.e2b.app",
     "ec2.us-east-1.amazonaws.com",
     "ec2.us-west-2.amazonaws.com",
     "ec2.eu-west-1.amazonaws.com",

package/dist/ephemeral-teardown.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/** Parse the daemon's ephemeral-teardown config from the process env. */
+export function readEphemeralTeardownConfig(env = process.env) {
+    return {
+        enabled: env.BIVY_EPHEMERAL === "1",
+        provider: String(env.BIVY_EPHEMERAL_PROVIDER || "").toLowerCase(),
+        ttlMin: Number(env.BIVY_EPHEMERAL_TTL_MIN) || 60,
+        onFinish: env.BIVY_TEARDOWN_ON_FINISH === "1",
+        finishGraceMs: Number(env.BIVY_TEARDOWN_FINISH_GRACE_MS) || 10_000,
+        idleGraceMs: Number(env.BIVY_SESSION_IDLE_CLOSE_MS) || 30 * 60 * 1000,
+    };
+}
+/**
+ * Pure decision: should this ephemeral machine tear itself down now? True only
+ * when it has done work at least once and is now fully quiet — nothing running,
+ * no device attached, no queue work in flight — for longer than the applicable
+ * grace (short after an agent finishes, else the idle window).
+ */
+export function shouldSelfTeardown(cfg, state) {
+    if (!cfg.enabled)
+        return false;
+    if (!state.everBusy)
+        return false;
+    if (state.anyWorking || state.anyRemoteActive || state.inFlightWork > 0)
+        return false;
+    const grace = cfg.onFinish ? cfg.finishGraceMs : cfg.idleGraceMs;
+    return state.idleForMs >= grace;
+}
+let torndown = false;
+/** Reset the once-only latch — tests only. */
+export function __resetTeardownLatch() {
+    torndown = false;
+}
+/**
+ * Execute the teardown. Signals the control plane, then stops the daemon:
+ * - Fly: exiting the init process trips `auto_destroy` — the machine is reaped.
+ * - EC2: `shutdown -h now` self-terminates the instance, then we exit.
+ * - Hetzner: exiting takes the node offline; the control-plane reconciler issues
+ *   the provider DELETE (it can't self-reap on OS shutdown). The /node/settled
+ *   signal makes that prompt; the CP timer is the backstop.
+ * Once-only: a racing idle sweep + agent_end can both call this safely.
+ */
+export async function performSelfTeardown(deps) {
+    if (torndown)
+        return;
+    torndown = true;
+    const log = deps.log ?? ((m) => console.log(`[ephemeral-teardown] ${m}`));
+    const exit = deps.exit ?? ((c) => process.exit(c));
+    log(`machine idle — self-teardown (provider=${deps.provider})`);
+    try {
+        await deps.signalSettled?.();
+    }
+    catch {
+        /* best effort — the CP timer reconciler and TTL are the backstops */
+    }
+    if (deps.provider === "aws") {
+        try {
+            deps.shutdown?.();
+        }
+        catch {
+            /* fall through to exit; the TTL shutdown still backstops */
+        }
+    }
+    exit(0);
+}

package/dist/pairing-crypto.js

@@ -35,6 +35,7 @@ const PAIR_INFO = Buffer.from(HKDF_INFO.pair);
 const ROTATE_INFO = Buffer.from(HKDF_INFO.rotate);
 const MODEL_AUTH_VAULT_INFO = Buffer.from(HKDF_INFO.modelAuthVault);
 const GITHUB_APP_VAULT_INFO = Buffer.from(HKDF_INFO.githubAppVault);
+const DEVICE_VAULT_INFO = Buffer.from(HKDF_INFO.deviceVault);
 const EMPTY_SALT = Buffer.alloc(0);
 /** Generate a fresh X25519 keypair (node identity or device ephemeral). */
 export function generatePairingKeypair() {
@@ -73,7 +74,8 @@ export function deriveWrapKey(ourPrivateKeyB64, theirPublicKeyB64, purpose) {
     const info = purpose === "pair" ? PAIR_INFO
         : purpose === "rotate" ? ROTATE_INFO
             : purpose === "github-app-vault" ? GITHUB_APP_VAULT_INFO
-                : MODEL_AUTH_VAULT_INFO;
+                : purpose === "device-vault" ? DEVICE_VAULT_INFO
+                    : MODEL_AUTH_VAULT_INFO;
     return Buffer.from(hkdfSync("sha256", shared, EMPTY_SALT, info, WRAP_KEY_BYTES));
 }
 /** A fresh 32-byte symmetric room key. */

package/dist/relay-client.js

@@ -26,7 +26,8 @@ export function loadRelayConfig(appDir) {
         return null;
     const controlPlaneUrl = process.env.BIVY_CONTROL_PLANE_URL ?? raw.controlPlaneUrl;
     const clientBaseUrl = process.env.BIVY_CLIENT_BASE_URL ?? raw.clientBaseUrl ?? controlPlaneUrl;
-    return { url, enrollmentToken, controlPlaneUrl, clientBaseUrl };
+    const e2eKey = process.env.BIVY_ROOM_KEY ?? raw.e2eKey;
+    return { url, enrollmentToken, controlPlaneUrl, clientBaseUrl, e2eKey };
 }
 // Application-level keepalive. On flaky/mobile links the node→relay TCP socket
 // can half-open silently: the node still thinks it is connected and buffers

package/dist/repo-workspace.js

@@ -29,15 +29,60 @@ export function parseGitHubRemote(input) {
         return parseRepo(`${ssh[1]}/${ssh[2]}`);
     return undefined;
 }
-/** Infer owner/repo from a workspace's origin remote, if it is a GitHub checkout. */
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * A git failure that DEFINITIVELY means "this workspace is not a GitHub-connected
+ * checkout" — a genuine `undefined` answer — as opposed to a transient failure we
+ * must not mistake for one. `git remote get-url origin` reports "not a git
+ * repository" (no repo) or "No such remote" (a repo with no origin); both are
+ * real, stable answers. Anything else (notably `index.lock`/`config.lock`
+ * contention when many sessions touch the same shared clone at once) is transient.
+ */
+function isDefinitiveNonGitHubError(error) {
+    const e = error;
+    const text = `${e?.stderr ?? ""} ${e?.message ?? String(error)}`;
+    return /not a git repository|No such remote|does not appear to be a git repository/i.test(text);
+}
+/**
+ * Infer owner/repo from a workspace's origin remote, if it is a GitHub checkout.
+ *
+ * Retries transient git failures before giving up. Misclassifying a momentarily
+ * busy GitHub checkout as "not a repo" is what let a session skip worktree
+ * isolation and run directly in the shared clone root, where its `git
+ * checkout`/`git stash` collided with a concurrent session (the "sessions
+ * mixing" bug). So: a DEFINITIVE non-GitHub result (not a repo / no origin)
+ * resolves to `undefined` as before, but a transient error is retried and then
+ * THROWN — the caller must fail loudly rather than silently degrade to running
+ * the agent in the shared root.
+ */
 export async function inferGitHubRepoFromWorkspace(workspace) {
-    try {
-        const { stdout } = await exec("git", ["-C", workspace, "remote", "get-url", "origin"], { cwd: workspace });
-        return parseGitHubRemote(stdout);
-    }
-    catch {
-        return undefined;
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const { stdout } = await exec("git", ["-C", workspace, "remote", "get-url", "origin"], { cwd: workspace });
+            return parseGitHubRemote(stdout);
+        }
+        catch (error) {
+            if (isDefinitiveNonGitHubError(error))
+                return undefined;
+            lastError = error;
+            if (attempt < 2)
+                await delay(50 * (attempt + 1));
+        }
     }
+    throw new Error(`Could not determine the GitHub repo for ${workspace} (the checkout may be busy): ` +
+        `${lastError?.message ?? String(lastError)}`);
+}
+/**
+ * True when `dir` is a Bivy-managed shared clone root — a direct child of the
+ * repos root, i.e. `<reposRoot>/owner__repo` (see `cloneOrUpdateRepo`). Every
+ * session for a repo shares that one checkout, so an agent must NEVER run
+ * directly in it; it runs in a per-session worktree instead. Worktree paths live
+ * DEEPER (`<clone>/.bivy/worktrees/<slug>`) and are intentionally not matched, so
+ * this cleanly distinguishes "the shared root" from "an isolated worktree".
+ */
+export function isSharedCloneRoot(dir, reposRoot) {
+    return path.resolve(path.dirname(path.resolve(dir))) === path.resolve(reposRoot);
 }
 /** A GitHub token from env or the local `gh` login, or undefined (public only). */
 export async function resolveGitHubToken(env = process.env) {

package/dist/runtime/claude-code.js

@@ -671,6 +671,11 @@ class ClaudeSession {
         const env = { ...process.env, ...depCacheEnv(), ...this.runtimeOptions.env };
         const credEnv = await this.resolveCredentialEnv();
         Object.assign(env, credEnv);
+        // Let the agent's own shell surface a file into the chat via `bivy attach`
+        // (POST /api/session/:id/attach). The session id is otherwise invisible to
+        // the subprocess. Other runtimes should set this the same way to enable the
+        // universal attach path for their agents.
+        env.BIVY_SESSION_ID = this.id;
         this.spawnedToken = authTokenFromEnv(credEnv);
         const options = {
             cwd: this.cwd,

package/dist/runtime/oauth/oauth-login-sweep.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Pure decision for sweeping stale browser-initiated OAuth logins (see the
+// `oauthLogins` registry in src/server.ts). A login parks the node until the
+// remote device pastes its code; an abandoned one must be reaped (aborting it
+// closes the local callback http.Server) and a finished one dropped after a
+// short grace so clients can still read its final status. Kept pure + isolated
+// so the edge logic is unit-tested without importing the daemon.
+export function isTerminalOAuthStatus(status) {
+    return status === "done" || status === "error";
+}
+export function decideOAuthLoginSweep(status, ageMs, opts) {
+    const terminal = isTerminalOAuthStatus(status);
+    const expired = terminal ? ageMs > opts.graceMs : ageMs > opts.ttlMs;
+    if (!expired)
+        return { drop: false, abort: false };
+    return { drop: true, abort: !terminal };
+}

package/dist/server.js

@@ -27,6 +27,7 @@ import { provisionAgentRun } from "./runtime/credential-provisioning.js";
 import { ingestAgentCredentials } from "./runtime/credential-ingest.js";
 import { suggestNameFromSelectedModel } from "./runtime/model-namer.js";
 import { isNativeOAuthProvider, loginModelOAuth } from "./runtime/oauth/model-oauth.js";
+import { decideOAuthLoginSweep } from "./runtime/oauth/oauth-login-sweep.js";
 import { listCodexSessions, loadCodexTranscript, discoverCodexSessionForCwd } from "./runtime/codex-sessions.js";
 import { dedupeSessionSummaries } from "./session-identity.js";
 import { discoverPiSessionForCwd } from "./runtime/pi-session-discovery.js";
@@ -40,10 +41,13 @@ import { collectNodeStats } from "./node-stats.js";
 import { SessionEventCoalescer } from "./session-event-coalescer.js";
 import { authMiddleware, resolveAuth, isAuthorized, requestOriginAllowed } from "./auth.js";
 import { RelayConnector, loadRelayConfig } from "./relay-client.js";
+import { readEphemeralTeardownConfig, shouldSelfTeardown, performSelfTeardown } from "./ephemeral-teardown.js";
+import { buildSessionSnapshot, applySessionSnapshot } from "./session/snapshot.js";
+import { createCheckpointBundle, applyCheckpointBundle, materializeCheckpoint } from "./session/checkpoint-pack.js";
 import { PolicyEngine } from "./policy/policy-engine.js";
 import { TerminalManager } from "./terminal.js";
 import { listMultiplexerSessions, attachCommand } from "./multiplexer.js";
-import { createWorktree, removeWorktree, branchSlug } from "./worktree.js";
+import { createWorktree, removeWorktree, branchSlug, gitRepoRoot } from "./worktree.js";
 import { HarnessManager } from "./harness/manager.js";
 import { startEgressProxyIfEnabled } from "./harness/egress.js";
 import { initSharedDepCache, sharedDepCacheRoot } from "./harness/dep-cache.js";
@@ -51,7 +55,7 @@ import { evictToCap, dirSizeBytes } from "./harness/cache-evict.js";
 import { checkDiskAdmission } from "./harness/disk-admission.js";
 import { sandboxTier, setConfiguredSandboxTier, normalizeSandboxTier } from "./harness/sandbox.js";
 import { injectMcpProxyForSession } from "./harness/mcp-inject.js";
-import { parseRepo, inferGitHubRepoFromWorkspace, resolveGitHubToken, cloneOrUpdateRepo, resolveDefaultBaseRef, resolveBranchBaseRef, fetchOrigin } from "./repo-workspace.js";
+import { parseRepo, inferGitHubRepoFromWorkspace, isSharedCloneRoot, resolveGitHubToken, cloneOrUpdateRepo, resolveDefaultBaseRef, resolveBranchBaseRef, fetchOrigin } from "./repo-workspace.js";
 import { configureGitAuth, writeGitCredentialEndpoint } from "./git-auth.js";
 import { GitHubTaskPoller, resolveGitHubTaskConfig, buildTaskPrompt, buildResumePrompt, buildInteractiveResumePrompt, DEFAULT_ISSUE_INSTRUCTIONS, parseBivyDirectives, commitAll, pushBranch, mergeBaseIntoBranch, completeMerge, abortMerge, findOpenPullRequestForBranch, findPullRequestsForBranch, findMergedPullRequestForBranch, issueBranchName, getPullRequest, commentIssue, listOpenLabelledIssues, selectActionableIssues, getIssue, getIssueCommentBody, addLabel, removeLabel, announcePickup, } from "./github-tasks.js";
 import { buildLinearTaskPrompt, getLinearIssue, linearBranchName } from "./linear-tasks.js";
@@ -67,6 +71,7 @@ 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 { planAttachment, isAttachPlanError } from "./session/attach-to-chat.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";
@@ -737,8 +742,11 @@ function getRuntime(requested, sandbox) {
 }
 // Holds the node's X25519 identity key, the rotating room key, and the linked
 // device registry. The room key is generated fresh on first load and delivered
-// to devices via the X25519 pairing handshake — there is no static seed.
-const pairingStore = PairingStore.load(appDir);
+// to devices via the X25519 pairing handshake — there is no static seed, EXCEPT
+// on an ephemeral rebuild: relay.json carries the reused session's room key
+// (`e2eKey`) so a brand-new pairing state adopts it and can decrypt the restored
+// snapshot. Only seeds a first-run node; an existing pairing.json always wins.
+const pairingStore = PairingStore.load(appDir, loadRelayConfig(appDir)?.e2eKey);
 function syncPairingMetadata() {
     for (const device of pairingStore.listDevices()) {
         metadata.upsertDevice({ id: device.id, label: device.label, publicKeyB64: device.publicKeyB64, firstSeenAt: device.createdAt, lastSeenAt: device.lastSeenAt ?? undefined });
@@ -749,6 +757,40 @@ let relay;
 const clients = new Set();
 const commandProcesses = new Map();
 const oauthLogins = new Map();
+// A browser-initiated subscription login parks the node on `manualCodePromise`
+// until the remote device pastes the code (`provider.oauth.code`). If the user
+// abandons it, the entry — AND its local callback http.Server — would otherwise
+// linger until the process exits. That matters especially on a short-lived
+// ephemeral node. Sweep periodically: abort (which closes the callback server,
+// see startCallbackServer) + drop any in-flight login past its TTL, and drop a
+// finished one after a short grace so clients can still read the final status.
+const OAUTH_LOGIN_TTL_MS = 10 * 60_000;
+const OAUTH_LOGIN_DONE_GRACE_MS = 2 * 60_000;
+function sweepOauthLogins(now = Date.now()) {
+    for (const [id, login] of oauthLogins.entries()) {
+        const { drop, abort } = decideOAuthLoginSweep(login.status, now - login.createdAt, {
+            ttlMs: OAUTH_LOGIN_TTL_MS,
+            graceMs: OAUTH_LOGIN_DONE_GRACE_MS,
+        });
+        if (!drop)
+            continue;
+        if (abort) {
+            login.cancelled = true;
+            try {
+                login.abort.abort();
+            }
+            catch { /* already settled */ }
+        }
+        oauthLogins.delete(id);
+    }
+}
+let oauthLoginSweepTimer;
+function startOAuthLoginSweeper() {
+    if (oauthLoginSweepTimer)
+        return;
+    oauthLoginSweepTimer = setInterval(() => sweepOauthLogins(), 60_000);
+    oauthLoginSweepTimer.unref?.();
+}
 const openSessions = new Map();
 // Stage 2 (docs/agent-node-decoupling.md): sessionId -> agent-service address for
 // live REMOTE sessions the agent service keeps running across an eviction/
@@ -991,6 +1033,40 @@ function materializeAttachments(record, files) {
     }
     return { note: notes.join("\n"), refs };
 }
+/**
+ * Surface an AGENT-produced file into the chat as an attachment (image or file)
+ * — the reverse of the composer paperclip. Confines to the session workspace,
+ * stores the bytes in the content-addressed AttachmentStore, persists a durable
+ * outbound reference anchored at the current transcript position (so a reload or
+ * another device shows it), and emits the live `attachment` event so attached
+ * devices render the chip/thumbnail immediately. Shared by the HTTP endpoint and
+ * the `bivy attach` CLI. Returns the stored ref, or a human-readable error.
+ */
+function attachToChat(record, opts) {
+    const plan = planAttachment({
+        workspaceDir: harnessDirFor(record),
+        filePath: opts.filePath,
+        mimeType: opts.mimeType,
+        name: opts.name,
+    });
+    if (isAttachPlanError(plan))
+        return { error: plan.error };
+    let ref;
+    try {
+        ref = attachmentStore.put(plan.bytes, { name: plan.name, mimeType: plan.mimeType, kind: plan.kind });
+    }
+    catch (error) {
+        return { error: `Could not store the attachment: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const entryId = `att-${randomBytes(8).toString("hex")}`;
+    const caption = opts.caption ? String(opts.caption).slice(0, 2000) : undefined;
+    // Anchor at the current base length so history replay interleaves the
+    // attachment where it was emitted (see event-log outbound projection).
+    const afterMessageCount = record.session.getMessages().length;
+    eventLog.appendOutboundAttachment(record.id, { afterMessageCount, id: entryId, ref, caption });
+    broadcast({ type: "session.event", sessionId: record.id, event: { type: "attachment", id: entryId, ref, caption } });
+    return { ref };
+}
 function approvalModeFrom(value) {
     return value === "never" || value === "risky" || value === "always" || value === "autonomous" ? value : undefined;
 }
@@ -3417,7 +3493,14 @@ function startRelayIfConfigured() {
     terminals.dropClient(RELAY_CLIENT_ID);
     relay = new RelayConnector(config, (msg) => void handleRelayMessage(msg), {
         pairing: pairingStore,
-        onWorkAvailable: () => controlPlanePoller?.poke(),
+        onWorkAvailable: () => {
+            controlPlanePoller?.poke();
+            // A relay wake also means "something changed for this account" — kick a
+            // (debounced) model-auth sync so a peer node answers any pending vault-key
+            // request from a freshly-launched ephemeral runner without waiting for its
+            // 30s poll. Cheap and idempotent; coalesced to at most one sync per burst.
+            triggerModelAuthSyncSoon();
+        },
     });
     relay.start();
     if (config.controlPlaneUrl && config.enrollmentToken) {
@@ -3517,6 +3600,62 @@ async function modelAuthFetch(pathname, init = {}) {
         headers.set("content-type", "application/json");
     return fetch(`${sessionAdvertiseTarget.controlPlaneUrl.replace(/\/$/, "")}${pathname}`, { ...init, headers });
 }
+// Debounced model-auth sync trigger. A relay wake (`work.available`) fires this
+// so peers answer a new node's vault-key request promptly (event-driven) instead
+// of on the steady 30s poll. Coalesces a burst of wakes into one sync.
+let modelAuthSyncSoonTimer;
+function triggerModelAuthSyncSoon() {
+    if (modelAuthSyncSoonTimer)
+        return;
+    modelAuthSyncSoonTimer = setTimeout(() => {
+        modelAuthSyncSoonTimer = undefined;
+        void syncModelAuthFromControlPlane();
+    }, 250);
+    modelAuthSyncSoonTimer.unref?.();
+}
+// Cold-start fast-retry. A freshly-launched node (typically a short-lived
+// ephemeral runner) that holds vault ciphertext but no wrapped key yet must wait
+// for a peer node to answer its key request. The 30s steady poll is too slow for
+// a machine that may only live a minute, so once we've requested the key we
+// re-sync on a brief bounded cadence until the wrapped key arrives (a peer
+// answered) or we give up and let the steady poll continue. Peer-only by design:
+// the key is always answered by another node over the E2E wrap — nothing ever
+// transits the device or control plane in the clear.
+const MODEL_AUTH_COLDSTART_INTERVAL_MS = 2_000;
+const MODEL_AUTH_COLDSTART_MAX_ATTEMPTS = 30; // ~60s bounded
+let modelAuthColdStartActive = false;
+let modelAuthColdStartAttempts = 0;
+let modelAuthColdStartTimer;
+function stopModelAuthColdStart() {
+    modelAuthColdStartActive = false;
+    modelAuthColdStartAttempts = 0;
+    if (modelAuthColdStartTimer) {
+        clearTimeout(modelAuthColdStartTimer);
+        modelAuthColdStartTimer = undefined;
+    }
+}
+function ensureModelAuthColdStart() {
+    if (modelAuthColdStartActive)
+        return; // already retrying
+    modelAuthColdStartActive = true;
+    modelAuthColdStartAttempts = 0;
+    const tick = () => {
+        modelAuthColdStartTimer = undefined;
+        if (!modelAuthColdStartActive)
+            return;
+        // A concurrent sync may have already landed the key — stop as soon as we have it.
+        if (readLocalModelAuthVaultKey() || modelAuthColdStartAttempts >= MODEL_AUTH_COLDSTART_MAX_ATTEMPTS) {
+            stopModelAuthColdStart();
+            return;
+        }
+        modelAuthColdStartAttempts++;
+        void syncModelAuthFromControlPlane();
+        modelAuthColdStartTimer = setTimeout(tick, MODEL_AUTH_COLDSTART_INTERVAL_MS);
+        modelAuthColdStartTimer.unref?.();
+    };
+    modelAuthColdStartTimer = setTimeout(tick, MODEL_AUTH_COLDSTART_INTERVAL_MS);
+    modelAuthColdStartTimer.unref?.();
+}
 async function syncModelAuthFromControlPlane() {
     if (!sessionAdvertiseTarget)
         return;
@@ -3531,6 +3670,14 @@ async function syncModelAuthFromControlPlane() {
             vaultKeyB64 = pairingStore.unwrapFromNodePublicKey(data.wrappedKey.wrappedByPublicKey, data.wrappedKey.wrappedKey);
             writeLocalModelAuthVaultKey(vaultKeyB64);
         }
+        // Node-less inheritance: a lone HOSTED ephemeral (no peer to wrap the key)
+        // adopts the vault key the control plane escrowed for this hosted account, so
+        // it can decrypt the synced vault (incl. subscription OAuth) on cold start. The
+        // control plane serves `hostedKey` only for hosted-provisioning accounts.
+        if (!vaultKeyB64 && data.hostedKey && Buffer.from(data.hostedKey, "base64").length === 32) {
+            vaultKeyB64 = data.hostedKey;
+            writeLocalModelAuthVaultKey(vaultKeyB64);
+        }
         if (data.vault?.ciphertext && vaultKeyB64) {
             const { providers, localModels } = decryptModelAuthEnvelope(data.vault.ciphertext, vaultKeyB64);
             await importProviderAuth(credsDir, providers);
@@ -3540,10 +3687,17 @@ async function syncModelAuthFromControlPlane() {
             await writePiModelsProjection();
             await broadcastLocalModels();
             lastPushedModelAuthCiphertext = data.vault.ciphertext;
+            // Got the key and imported the vault (incl. any subscription-OAuth logins) —
+            // the cold-start race is over.
+            stopModelAuthColdStart();
             broadcast({ type: "providers.list", providers: await listProvidersUnified() });
         }
         else if (data.vault?.ciphertext && !vaultKeyB64) {
             await modelAuthFetch("/node/model-auth-key/request", { method: "POST", body: JSON.stringify({ publicKey: pairingStore.nodePublicKeyB64() }) });
+            // No peer has wrapped our key yet. Fast-retry (bounded) so a short-lived
+            // ephemeral runner picks up the key within seconds of a peer answering,
+            // rather than waiting for its next 30s poll.
+            ensureModelAuthColdStart();
         }
         else if (Object.keys(await exportProviderAuth(credsDir)).length > 0 ||
             Object.keys(exportLocalModels(localModelsDir)).length > 0) {
@@ -3590,6 +3744,13 @@ async function pushModelAuthToControlPlane() {
             method: "PUT",
             body: JSON.stringify({ targetNodeId: identity.nodeId, wrappedByPublicKey: pairingStore.nodePublicKeyB64(), wrappedKey: pairingStore.wrapForNodePublicKey(pairingStore.nodePublicKeyB64(), vaultKeyB64) }),
         });
+        // Node-less inheritance: a HOSTED node also escrows the vault key to the control
+        // plane (sealed at rest, hosted-only) so the account's NEXT hosted ephemeral —
+        // possibly the only node — can decrypt this vault without a peer to wrap the key.
+        // Gated to hosted nodes; the CP double-checks the account is hosted. Best effort.
+        if (process.env.BIVY_GITHUB_HOSTED_TASKS) {
+            await modelAuthFetch("/node/model-auth-key/hosted-escrow", { method: "PUT", body: JSON.stringify({ vaultKeyB64 }) }).catch(() => { });
+        }
         lastPushedModelAuthCiphertext = ciphertext;
     }
     catch (error) {
@@ -4724,6 +4885,19 @@ async function runWorkItem(item, report) {
             if (item.url)
                 issue.url = item.url;
         }
+        // Case B: the control plane asked us to CONTINUE an existing session for this
+        // issue (an inbound comment/issue on a thread that already has one). If that
+        // session isn't live on this node — e.g. its ephemeral machine was torn down —
+        // best-effort restore its snapshot first so its transcript + branch state are
+        // rebuilt and the work continues the thread instead of starting cold. On
+        // failure we fall through to the normal idempotent, remote-branch-adopting
+        // pickup, so this can only help, never break.
+        const issueSource = `issue:${parsed.owner}/${parsed.repo}#${item.issueNumber}`;
+        if (item.targetKind === "existing_session" && item.targetSessionId && !findIssueSession(issueSource)) {
+            await restoreSessionFromSnapshot(item.targetSessionId).catch((e) => {
+                console.warn(`[case-b] snapshot restore for ${item.targetSessionId} failed:`, e.message);
+            });
+        }
         await runIssueTask(cfg, issue, { runtimeId: item.runtimeId, model: item.model, onEvidence: report });
         return;
     }
@@ -5036,6 +5210,9 @@ async function startOAuthLogin(provider) {
     // OpenAI's browser flow redirects to http://localhost:1455. Listen on IPv6
     // wildcard so browsers resolving localhost to ::1 can reach the callback.
     process.env.PI_OAUTH_CALLBACK_HOST ||= "::";
+    // Opportunistically drop stale/abandoned logins whenever a new one starts, so a
+    // long-lived node doesn't accumulate them between sweeps (and tests can drive it).
+    sweepOauthLogins();
     const id = randomUUID();
     const abort = new AbortController();
     const state = { id, provider, status: "starting", abort, createdAt: Date.now(), progress: [] };
@@ -5383,6 +5560,22 @@ async function standUpFork(opts) {
         cwd = wt.path;
         worktree = wt;
     }
+    else {
+        // Non-repo-backed source. The fork would otherwise reuse the PARENT's cwd,
+        // putting two sessions in one working tree — so when that cwd is itself a git
+        // checkout (a local repo without a GitHub origin), cut the fork its own
+        // worktree on a fresh branch. Best-effort: a non-git workspace has no tree to
+        // isolate, so the fork keeps the fallback cwd (no git collisions possible).
+        const forkRepoRoot = await gitRepoRoot(cwd);
+        if (forkRepoRoot) {
+            const forkBranch = `bivy/fork-${randomBytes(6).toString("hex")}`;
+            const wt = await createWorktree({ repoDir: forkRepoRoot, id: forkBranch, branch: forkBranch });
+            applyDirtyPatch(wt.path, bundle.dirtyPatch);
+            workspace = forkRepoRoot;
+            cwd = wt.path;
+            worktree = wt;
+        }
+    }
     // Materialise the transcript, then stand the session up — resume the imported
     // transcript (full) or a fresh session the caller seeds with plan.seedPrompt.
     const plan = await materializeFork({ bundle, targetRuntime, ctx: { workspace, cwd }, seed: { transcriptUrl: opts.transcriptUrl } });
@@ -6142,10 +6335,153 @@ async function deleteSessionFile(opts) {
     scheduleAdvertise();
     return { sessionId: deletedSessionId, sessionFile: inRoot ? resolved : undefined };
 }
-const idleCloseTimer = setInterval(() => { closeIdleSessions(); pruneGhostSessions(); pruneEmptySessions(); }, idleCloseSweepMs);
+const idleCloseTimer = setInterval(() => { closeIdleSessions(); pruneGhostSessions(); pruneEmptySessions(); evaluateEphemeralTeardown(); }, idleCloseSweepMs);
 idleCloseTimer.unref?.();
 const worktreeCleanupTimer = setInterval(() => void sweepDiskGuardrails(), worktreeCleanupSweepMs);
 worktreeCleanupTimer.unref?.();
+// --- server-side ephemeral teardown ----------------------------------------
+// On a disposable machine (bootstrap set BIVY_EPHEMERAL=1) the daemon ends the
+// machine ITSELF once it goes idle, so teardown no longer needs the launching
+// device online. See src/ephemeral-teardown.ts + docs/ephemeral-sessions.md.
+const ephemeralTeardownCfg = readEphemeralTeardownConfig();
+let ephemeralEverBusy = false;
+let ephemeralLastBusyAt = Date.now();
+/** Best-effort "I've settled — reap me" signal to the control plane. Non-secret
+ *  (node id via the enrollment bearer); lets a hosted machine whose provider
+ *  can't self-reap on exit (Hetzner) be destroyed server-side. */
+async function signalSettledToControlPlane() {
+    if (!sessionAdvertiseTarget)
+        return;
+    await fetch(`${sessionAdvertiseTarget.controlPlaneUrl.replace(/\/$/, "")}/node/settled`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${sessionAdvertiseTarget.enrollmentToken}`, "content-type": "application/json" },
+        body: "{}",
+    }).catch(() => { });
+}
+/** Rebuild-resume (Gap B): on a freshly re-provisioned machine booted with
+ *  `BIVY_RESTORE=<sessionId>`, fetch the session's control-plane snapshot,
+ *  decrypt it with this machine's room key (reused from the torn-down session so
+ *  the seal matches), and apply it — restoring the transcript (EventLog) and the
+ *  git checkpoint into a repo the session can open. The runtime process starts
+ *  fresh/seeded from the restored transcript ("reconstructed", not byte-identical
+ *  — see docs/ephemeral-sessions.md). Best-effort: a missing/undecryptable
+ *  snapshot leaves a clean fresh machine. Reuses the standby-replica machinery. */
+async function restoreSessionFromSnapshot(sessionId) {
+    if (!sessionAdvertiseTarget)
+        return;
+    const cpBaseUrl = sessionAdvertiseTarget.controlPlaneUrl.replace(/\/$/, "");
+    try {
+        const res = await fetch(`${cpBaseUrl}/node/session-snapshot/${encodeURIComponent(sessionId)}`, {
+            headers: { authorization: `Bearer ${sessionAdvertiseTarget.enrollmentToken}` },
+        });
+        if (!res.ok) {
+            console.error(`[restore] no snapshot for ${sessionId} (${res.status})`);
+            return;
+        }
+        const data = (await res.json());
+        if (!data.ciphertext)
+            return;
+        const applied = await applySessionSnapshot(data.ciphertext, pairingStore.roomKey(), {
+            persistRecords: (id, records) => eventLog.rewrite(id, records),
+            applyBundle: async (id, buf) => applyCheckpointBundle(await ensureReplicaRepo(id), id, buf),
+            materialize: async (id) => materializeCheckpoint(await ensureReplicaRepo(id), id),
+        });
+        // Register the rebuilt session so it lists and opens (mirrors the standby's
+        // upsertReplicaMeta); the transcript replays from the restored EventLog.
+        try {
+            metadata.upsertSession({ id: sessionId, source: "restored", status: "saved" });
+        }
+        catch {
+            /* best-effort listing */
+        }
+        console.log(`[restore] session ${sessionId}: ${applied.recordCount} records, checkpoint ${applied.checkpointCommit ?? "none"}`);
+    }
+    catch (e) {
+        console.error(`[restore] session ${sessionId} failed: ${e?.message || e}`);
+    }
+}
+/** Flush a durable, E2E-encrypted snapshot of each open session to the control
+ *  plane before this disposable machine is torn down, so a destroy-lane session
+ *  can be rebuilt on a fresh machine later (Gap B). Sealed under the node room
+ *  key — the same key that seals the session title — so a restore machine that
+ *  reuses this session's room key can decrypt it; the control plane sees only
+ *  ciphertext. Best-effort per session; never blocks teardown for long. */
+async function flushSessionSnapshots() {
+    if (!sessionAdvertiseTarget)
+        return;
+    const roomKey = pairingStore.roomKey();
+    const cpBaseUrl = sessionAdvertiseTarget.controlPlaneUrl.replace(/\/$/, "");
+    for (const record of new Set(openSessions.values())) {
+        try {
+            const sealed = await buildSessionSnapshot(record.id, roomKey, {
+                readRecords: (id) => eventLog.entries(id),
+                epochOf: () => 0,
+                checkpointHead: async (id) => {
+                    try {
+                        return (await harness.checkpoints(id))[0]?.id;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                bundleCheckpoint: async (id, since) => createCheckpointBundle(harnessDirFor(record), id, since),
+                runtimeSessionRef: (id) => openSessions.get(id)?.sessionFile,
+                worktreeSync: () => true,
+            });
+            if (!sealed)
+                continue;
+            await fetch(`${cpBaseUrl}/node/session-snapshot/${encodeURIComponent(record.id)}`, {
+                method: "PUT",
+                headers: { authorization: `Bearer ${sessionAdvertiseTarget.enrollmentToken}`, "content-type": "application/json" },
+                body: JSON.stringify({ ciphertext: sealed }),
+            }).catch(() => { });
+        }
+        catch {
+            /* best effort per session — TTL/branch push remain the backstops */
+        }
+    }
+}
+let ephemeralTearingDown = false;
+/** Evaluate the quiet condition and self-terminate if the machine is done. Reads
+ *  live session/queue state each call, so it's safe to invoke from the idle
+ *  sweep and from agent_end. No-op on a persistent node (env absent). */
+function evaluateEphemeralTeardown() {
+    if (!ephemeralTeardownCfg.enabled || ephemeralTearingDown)
+        return;
+    const records = new Set(openSessions.values());
+    const anyWorking = [...records].some((r) => r.isWorking);
+    const anyRemoteActive = [...records].some((r) => r.remoteActive);
+    const inFlightWork = controlPlanePoller?.inFlightCount() ?? 0;
+    if (anyWorking || anyRemoteActive || inFlightWork > 0) {
+        ephemeralEverBusy = true;
+        ephemeralLastBusyAt = Date.now();
+        return;
+    }
+    const idleForMs = Date.now() - ephemeralLastBusyAt;
+    if (!shouldSelfTeardown(ephemeralTeardownCfg, { everBusy: ephemeralEverBusy, anyWorking, anyRemoteActive, inFlightWork, idleForMs }))
+        return;
+    ephemeralTearingDown = true;
+    void (async () => {
+        // Persist a rebuild snapshot BEFORE the machine goes away (Gap B), then reap.
+        await flushSessionSnapshots();
+        await performSelfTeardown({
+            provider: ephemeralTeardownCfg.provider,
+            signalSettled: signalSettledToControlPlane,
+            shutdown: () => { try {
+                spawnSync("shutdown", ["-h", "now"], { stdio: "ignore" });
+            }
+            catch { /* TTL backstops */ } },
+        });
+    })();
+}
+if (ephemeralTeardownCfg.enabled) {
+    // Sample often enough to honour the finish grace (~10s) without waiting for the
+    // 1–5min idle sweep. Ephemeral-only, so no cost on a persistent node.
+    const ephemeralEvalMs = Math.max(2_000, Math.min(ephemeralTeardownCfg.finishGraceMs, 15_000));
+    const ephemeralTeardownTimer = setInterval(() => evaluateEphemeralTeardown(), ephemeralEvalMs);
+    ephemeralTeardownTimer.unref?.();
+    console.log(`[ephemeral-teardown] armed: provider=${ephemeralTeardownCfg.provider} onFinish=${ephemeralTeardownCfg.onFinish} ttl=${ephemeralTeardownCfg.ttlMin}m`);
+}
 setTimeout(() => void sweepDiskGuardrails(), 30_000).unref?.();
 // One sweep shortly after boot clears ghosts left by a previous run before any
 // client paints its sidebar; the idle timer keeps it clean thereafter.
@@ -6382,6 +6718,9 @@ function attachSessionListeners(record) {
             // itself (gh/API/web) so the badge lights up.
             void maybePushWorktreeBranch(record)
                 .then(() => maybeDetectPullRequest(record));
+            // On a disposable machine, a finished turn with nobody watching is the cue
+            // to consider self-teardown promptly (the idle sweep is the backstop).
+            evaluateEphemeralTeardown();
         }
         const sessionEventPayload = { type: "session.event", sessionId: record.id, event };
         if (event.type === "message_update") {
@@ -6876,9 +7215,52 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
         if (!admission.allowed)
             throw new Error(`Not enough disk to start a new worktree session: ${admission.reason}`);
         const wtOpts = typeof opts.worktree === "object" ? opts.worktree : {};
-        worktree = await createWorktree({ repoDir: workspace, id: wtOpts.branch ?? `session-${Date.now()}`, branch: wtOpts.branch, base: wtOpts.base });
+        // A random suffix, never a timestamp: two sessions started in the same
+        // millisecond would otherwise resolve to the same slug → same worktree path
+        // and branch, and `createWorktree` would ADOPT the first's worktree, dropping
+        // the second session into a directory another session already owns.
+        worktree = await createWorktree({ repoDir: workspace, id: wtOpts.branch ?? `session-${randomBytes(6).toString("hex")}`, branch: wtOpts.branch, base: wtOpts.base });
         runtimeWorkspace = worktree.path;
     }
+    // Resume with a reaped worktree. When a repo-backed session is resumed but its
+    // worktree directory was removed while it was closed (disk cleanup, a manual
+    // rm, `git worktree remove`), restoredWorktree is undefined and we'd otherwise
+    // fall back to the shared clone root — which the invariant below then rejects.
+    // Re-provision a fresh worktree on the SAME branch instead (branches survive
+    // `git worktree remove`, so the agent's committed history is intact), restoring
+    // isolation so the resumed session is usable again. Best-effort: if the clone
+    // or branch is gone, we leave it to the invariant to fail safe rather than
+    // corrupt a neighbour. The clone root is reconstructed from `source`
+    // (`repo:owner/repo`) because stored `workspace` is the old worktree path.
+    if (requestedSessionFile && !worktree && storedMeta?.worktree && storedMeta?.branch) {
+        const parsedSource = parseRepoSource(storedMeta.source);
+        if (parsedSource) {
+            const repoDir = path.join(reposRoot, `${parsedSource.owner}__${parsedSource.repo}`);
+            try {
+                // Clear any stale registration left by a dir that was rm'd out from under
+                // git, so re-adding the branch's worktree doesn't hit "already checked out".
+                runGit(["worktree", "prune"], repoDir);
+                const reprovisioned = await createWorktree({ repoDir, id: storedMeta.branch, branch: storedMeta.branch });
+                worktree = reprovisioned;
+                runtimeWorkspace = reprovisioned.path;
+            }
+            catch (error) {
+                console.warn(`Could not re-provision worktree for resumed session on ${storedMeta.branch}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    // Isolation invariant. A session must NEVER run directly in a Bivy-managed
+    // shared clone root (`<reposRoot>/owner__repo`): every session for that repo
+    // shares that one checkout, so an agent running there collides with concurrent
+    // sessions on `git checkout`/`git stash` — exactly the "sessions mixing" bug.
+    // A GitHub-backed session is supposed to get its own worktree; reaching here
+    // without one means an earlier step degraded (e.g. a transient repo-inference
+    // failure, or a resume whose worktree was reaped). Fail loudly instead of
+    // silently sharing the tree and corrupting a neighbouring session's work.
+    if (!worktree && isSharedCloneRoot(runtimeWorkspace, reposRoot)) {
+        throw new Error(`Refusing to start a session in the shared clone root ${runtimeWorkspace} without an isolated worktree — ` +
+            `this would collide with concurrent sessions on the same repo. Retry; if it persists the checkout may be busy.`);
+    }
     const runtimeSessionOptions = { workspace: runtimeWorkspace, toolProvider: integrations.toolProvider(), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
     // Stage 2/3: prefer re-attaching to a still-live remote session — routed to its
     // OWN agent service — over re-opening a fresh copy from disk. Falls back to
@@ -6906,8 +7288,12 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
     if (requestedSessionFile && storedMeta?.name && !session.getName())
         session.setName(storedMeta.name);
     const sessionWorkspace = session.cwd || runtimeWorkspace;
-    const inferredRepo = opts.source || storedMeta?.source ? undefined : await inferGitHubRepoFromWorkspace(sessionWorkspace);
-    if (!worktree && requestedSessionFile && inferredRepo) {
+    // Best-effort here (unlike createWorkspaceSession, which must fail loudly):
+    // this only decides whether to ADOPT an already-checked-out branch as the
+    // session's worktree label, so a transient inference failure should quietly
+    // skip adoption rather than break resuming the session.
+    const inferredRepo = opts.source || storedMeta?.source ? undefined : await inferGitHubRepoFromWorkspace(sessionWorkspace).catch(() => undefined);
+    if (!worktree && requestedSessionFile && inferredRepo && !isSharedCloneRoot(sessionWorkspace, reposRoot)) {
         const branch = runGit(["branch", "--show-current"], sessionWorkspace) || runGit(["rev-parse", "--short", "HEAD"], sessionWorkspace) || undefined;
         if (branch) {
             const mainWorktree = runGit(["worktree", "list", "--porcelain"], sessionWorkspace)?.split("\n").find((line) => line.startsWith("worktree "))?.slice("worktree ".length);
@@ -9172,6 +9558,29 @@ app.get("/api/attachment/:hash", (req, res) => {
     res.setHeader("Cache-Control", "private, max-age=31536000, immutable");
     res.end(bytes);
 });
+// Let an AGENT push a file into the chat as an attachment (image/file) — the
+// reverse of the composer upload. Called by the agent's own shell (`bivy attach`)
+// or any local tool; on a single-user host the loopback bypass means no token is
+// needed. Behind /api's authMiddleware. `path` is resolved inside — and confined
+// to — the session's workspace (see planAttachment's security note).
+app.post("/api/session/:id/attach", (req, res) => {
+    const record = openSessions.get(String(req.params.id));
+    if (!record)
+        return res.status(404).json({ error: "Session not found" });
+    const filePath = String(req.body?.path ?? req.body?.filePath ?? "").trim();
+    if (!filePath)
+        return res.status(400).json({ error: "Missing file path" });
+    const result = attachToChat(record, {
+        filePath,
+        caption: typeof req.body?.caption === "string" ? req.body.caption : undefined,
+        mimeType: typeof req.body?.mimeType === "string" ? req.body.mimeType : undefined,
+        name: typeof req.body?.name === "string" ? req.body.name : undefined,
+    });
+    if ("error" in result)
+        return res.status(400).json({ error: result.error });
+    const { hash, name, mimeType, size, kind } = result.ref;
+    res.json({ ok: true, hash, name, mimeType, size, kind });
+});
 app.post("/api/session/prompt", async (req, res, next) => {
     try {
         const text = String(req.body?.text ?? "").trim();
@@ -9432,7 +9841,12 @@ const server = app.listen(port, host, async () => {
     console.log(`Agent data dir: ${piDir}`);
     console.log(`Workspace: ${defaultWorkspace}`);
     startRelayIfConfigured();
+    // Rebuild-resume (Gap B): if this machine was re-provisioned to restore a
+    // torn-down session, pull + apply its snapshot before serving. Non-blocking.
+    if (process.env.BIVY_RESTORE)
+        void restoreSessionFromSnapshot(String(process.env.BIVY_RESTORE));
     startModelAuthWatcher();
+    startOAuthLoginSweeper();
     startGithubAppSyncWatcher();
     await startGitHubTasksIfConfigured();
     startControlPlaneTasksIfConfigured();

package/dist/session/attach-to-chat.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Plan an AGENT-sent chat attachment: the reverse of the composer paperclip.
+// An agent points at a file it produced in the workspace (a rendered chart, a
+// screenshot, a report), and Bivy surfaces it into the chat as an image/file
+// chip. This module is the PURE, testable half — path confinement, size cap, and
+// mime/kind classification — returning bytes + metadata (or a human-readable
+// error). The server half stores the bytes in the content-addressed
+// AttachmentStore, emits the live `attachment` event, and persists the outbound
+// reference for durable history.
+//
+// Security posture: the resolved file MUST live inside the session's working
+// directory. An agent is a semi-trusted process; without confinement, a prompt
+// injection could turn "attach a file to the chat" into "exfiltrate /etc/passwd
+// (or ~/.ssh/id_rsa) to the user's phone". Symlinks are resolved before the
+// check so a symlink inside the workspace can't point out of it.
+import fs from "node:fs";
+import path from "node:path";
+/** Ceiling for a single agent attachment. Kept comfortably under the relay's
+ *  32 MiB reassembly limit (see packages/core/src/wire-format.ts) so a large
+ *  attachment still travels to a phone over the encrypted relay in chunks. */
+export const MAX_AGENT_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+export function isAttachPlanError(value) {
+    return typeof value.error === "string";
+}
+const EXT_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".avif": "image/avif",
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".zip": "application/zip",
+};
+/** Sniff a mime type from the leading magic bytes for the common image/PDF
+ *  formats, so a mislabeled or extension-less file still classifies correctly.
+ *  Returns "" when nothing matches (caller falls back to extension/default). */
+export function sniffMime(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return "image/png";
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    if (bytes.length >= 6 && (bytes.subarray(0, 6).toString("latin1") === "GIF87a" || bytes.subarray(0, 6).toString("latin1") === "GIF89a"))
+        return "image/gif";
+    if (bytes.length >= 12 && bytes.subarray(0, 4).toString("latin1") === "RIFF" && bytes.subarray(8, 12).toString("latin1") === "WEBP")
+        return "image/webp";
+    if (bytes.length >= 5 && bytes.subarray(0, 5).toString("latin1") === "%PDF-")
+        return "application/pdf";
+    return "";
+}
+/** Strip directory components and control/path characters from a filename so it
+ *  is safe to show and to store as an attachment display name. */
+export function sanitizeAttachmentName(name) {
+    const base = path.basename(String(name || "").trim());
+    const cleaned = base
+        .replace(/[/\\]+/g, "_")
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f]+/g, "")
+        .trim();
+    return cleaned.slice(0, 200) || "attachment";
+}
+/**
+ * Resolve, confine, size-check, read, and classify a file the agent asked to
+ * attach. `filePath` may be absolute or relative to `workspaceDir`; either way
+ * the resolved real path must sit inside `workspaceDir`.
+ */
+export function planAttachment(opts) {
+    const raw = String(opts.filePath || "").trim();
+    if (!raw)
+        return { error: "No file path given." };
+    const workspaceDir = path.resolve(opts.workspaceDir);
+    const resolved = path.resolve(workspaceDir, raw);
+    // Confinement, symlink-safe: resolve the real path of the file before comparing
+    // against the real workspace root. realpathSync also fails cleanly for a missing
+    // file.
+    let realFile;
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync(workspaceDir);
+    }
+    catch {
+        return { error: "Workspace directory is unavailable." };
+    }
+    try {
+        realFile = fs.realpathSync(resolved);
+    }
+    catch {
+        return { error: `File not found: ${raw}` };
+    }
+    const rel = path.relative(realRoot, realFile);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+        return { error: "Refusing to attach a file outside the session workspace." };
+    }
+    let stat;
+    try {
+        stat = fs.statSync(realFile);
+    }
+    catch {
+        return { error: `File not found: ${raw}` };
+    }
+    if (stat.isDirectory())
+        return { error: `Not a file: ${raw}` };
+    const maxBytes = opts.maxBytes ?? MAX_AGENT_ATTACHMENT_BYTES;
+    if (stat.size > maxBytes) {
+        return { error: `File is too large to attach (${stat.size} bytes; limit ${maxBytes}).` };
+    }
+    if (stat.size === 0)
+        return { error: "Refusing to attach an empty file." };
+    let bytes;
+    try {
+        bytes = fs.readFileSync(realFile);
+    }
+    catch {
+        return { error: `Could not read file: ${raw}` };
+    }
+    const ext = path.extname(realFile).toLowerCase();
+    const mimeType = (opts.mimeType && String(opts.mimeType).trim()) ||
+        sniffMime(bytes) ||
+        EXT_MIME[ext] ||
+        "application/octet-stream";
+    const kind = mimeType.startsWith("image/") ? "image" : "file";
+    const name = sanitizeAttachmentName(opts.name || path.basename(realFile));
+    return { bytes, name, mimeType, kind };
+}

package/dist/session/event-log.js

@@ -28,6 +28,10 @@
 // interleaved in any order on disk; each replay reads only its own kind.
 import fs from "node:fs";
 import { normalizedIntermediateText, thinkingTextFromContent, mergeTranscript } from "./transcript-merge.js";
+/** Content-block type carried by a folded outbound attachment. MUST match
+ *  `AGENT_ATTACHMENT_BLOCK` in packages/core/src/store-render.ts — the client's
+ *  renderHistory keys on this exact string to render the chip. */
+const AGENT_ATTACHMENT_BLOCK = "bivy_attachment";
 function isOverlay(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -46,8 +50,19 @@ function isAttachment(value) {
     const record = value;
     return record.bivyKind === "attachment" && typeof record.text === "string" && Array.isArray(record.refs);
 }
+function isOutboundAttachment(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (record.bivyKind === "outbound-attachment" &&
+        typeof record.afterMessageCount === "number" &&
+        typeof record.id === "string" &&
+        !!record.ref &&
+        typeof record.ref === "object" &&
+        typeof record.ref.hash === "string");
+}
 function isRecord(value) {
-    return isOverlay(value) || isBase(value) || isAttachment(value);
+    return isOverlay(value) || isBase(value) || isAttachment(value) || isOutboundAttachment(value);
 }
 /**
  * Fold attachment records into a text→refs list: last write wins per text (a
@@ -132,7 +147,32 @@ export function replayExtras(entries) {
         else if (entry.bivyKind === "tool")
             tool.push(entry);
     }
-    return [...foldIntermediate(intermediate), ...foldTool(tool)];
+    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries)];
+}
+/**
+ * Fold the outbound (agent-sent) attachment records into time-anchored synthetic
+ * assistant messages `mergeTranscript` interleaves into the transcript. Last write
+ * wins per id (a re-emitted id updates in place, matching the log's coalescing),
+ * preserving first-seen order. Each becomes one `bivy_attachment` block the client
+ * renders as a chip/thumbnail.
+ */
+export function replayOutboundAttachments(entries) {
+    const byId = new Map();
+    for (const entry of entries) {
+        if (entry.bivyKind !== "outbound-attachment")
+            continue;
+        // set() on an existing key updates the value in place (Map keeps first-seen
+        // insertion order), so last write wins while position is stable. Final
+        // placement is by time in mergeTranscript regardless.
+        byId.set(entry.id, entry);
+    }
+    return [...byId.values()].map((entry) => ({
+        role: "assistant",
+        content: [{ type: AGENT_ATTACHMENT_BLOCK, ref: entry.ref, caption: entry.caption }],
+        afterMessageCount: entry.afterMessageCount,
+        createdAt: entry.createdAt,
+        id: entry.id,
+    }));
 }
 /**
  * Replay a session's base records into the base transcript: `reset` replaces the
@@ -286,6 +326,23 @@ export class EventLog {
     readAttachments(id) {
         return replayAttachments(this.entries(id));
     }
+    /**
+     * Record an agent-sent (outbound) attachment, anchored at the current base
+     * length so history replay interleaves it where it was emitted. Coalesces on
+     * the transcript-entry id so a re-emit of the same attachment updates in place.
+     */
+    appendOutboundAttachment(id, entry) {
+        this.load(id);
+        const record = {
+            bivyKind: "outbound-attachment",
+            createdAt: Date.now(),
+            afterMessageCount: entry.afterMessageCount,
+            id: entry.id,
+            ref: { ...entry.ref },
+            ...(entry.caption ? { caption: entry.caption } : {}),
+        };
+        this.enqueue(id, `oa:${entry.id}`, record);
+    }
     /** Replay the overlay entries (disk + pending) into the flat `extras` list. */
     read(id) {
         return replayExtras(this.entries(id));

package/dist/session/snapshot.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Node-independent, encrypted SESSION SNAPSHOT (Gap B in docs/ephemeral-sessions.md).
+//
+// Warm replication (replicator.ts) ships a session's state node→node so a live
+// standby can take over — but that copy evaporates if every node goes away, which
+// is exactly the destroy-lane ephemeral case (Fly Machines/Hetzner/EC2 that are
+// torn down when the agent finishes). This reuses the SAME replication frame
+// (full transcript + git checkpoint bundle + runtimeSessionRef) but seals it under
+// the session room key and stores it as an opaque control-plane BLOB, so a
+// torn-down session can be rebuilt onto a fresh machine later. The control plane
+// only ever sees ciphertext — same posture as the E2E session title.
+//
+// This module is the pure build/apply core (injected deps, no daemon/relay), so
+// it's unit-testable like replicator.ts; the daemon wires the real EventLog /
+// checkpoint deps, the room key from relay.json, and the control-plane transport.
+import { OwnerReplicator, StandbyApplier } from "./replicator.js";
+import { seal, open } from "../e2e.js";
+/**
+ * Build a full, sealed snapshot of a session: a complete replication frame (ALL
+ * transcript records + a full git checkpoint bundle + the runtime resume token),
+ * serialized and encrypted under the session room key. Returns null when there's
+ * nothing to snapshot yet (no records and no checkpoint).
+ *
+ * A fresh `OwnerReplicator` has no cursor, so `buildTurnFrame` produces a FULL
+ * frame + full bundle — exactly what a from-scratch rebuild on a new machine
+ * needs (it holds no base to delta against).
+ */
+export async function buildSessionSnapshot(sessionId, roomKey, deps) {
+    const owner = new OwnerReplicator({ ...deps, worktreeSync: () => true });
+    const frame = await owner.buildTurnFrame(sessionId);
+    // Nothing worth persisting yet: no transcript and no checkpoint (a fresh owner
+    // has no cursor, so buildReplFrame emits a zero-record frame rather than null).
+    if (!frame || (frame.records.length === 0 && !frame.checkpointCommit))
+        return null;
+    return seal(roomKey, JSON.stringify(frame));
+}
+/**
+ * Decrypt and apply a sealed snapshot onto a fresh machine: rewrite the session's
+ * EventLog transcript, land the git checkpoint into the (replica) repo and
+ * materialize the working tree, and return the runtimeSessionRef so the caller
+ * can re-derive a resumable runtime session (writeHistory / seeded fallback).
+ * Throws on a bad key / corrupt blob, or if the frame can't apply cleanly.
+ */
+export async function applySessionSnapshot(sealed, roomKey, deps) {
+    const frame = JSON.parse(open(roomKey, sealed));
+    const applier = new StandbyApplier(deps);
+    const ack = await applier.receive(frame);
+    // We always ship a FULL frame + full bundle, so a fresh applier applies it
+    // outright ("applied"); "resync" is a benign already-current signal. A
+    // "needFull"/"stale" here means a corrupt/foreign blob.
+    if (ack.status !== "applied" && ack.status !== "resync") {
+        throw new Error(`snapshot apply failed: ${ack.status}`);
+    }
+    return {
+        runtimeSessionRef: frame.runtimeSessionRef,
+        recordCount: frame.records.length,
+        checkpointCommit: frame.checkpointCommit,
+    };
+}

package/dist/wire-format.js

@@ -29,6 +29,10 @@ export const HKDF_INFO = {
     modelAuthVault: "bivy-model-auth-vault-v1",
     /** GitHub App private-key vault delivery (node-only, opt-in — issue #88). */
     githubAppVault: "bivy-github-app-vault-v1",
+    /** Device→device ephemeral-provider-token vault delivery (opt-in). Unlike the
+     *  node vaults above, the recipients are the account's paired DEVICES, so a
+     *  second device can wake/reach a machine the first launched. */
+    deviceVault: "bivy-device-vault-v1",
 };
 /** Version byte stamped into every sealed frame's authenticated plaintext. */
 export const FRAME_VERSION = 1;

package/package.json

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