@bivy/bivy 0.3.0-staging.40 → 0.3.0-staging.41

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/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/server.js

@@ -40,6 +40,9 @@ 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";
@@ -6142,10 +6145,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 +6528,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") {
@@ -9432,6 +9581,10 @@ 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();
     startGithubAppSyncWatcher();
     await startGitHubTasksIfConfigured();

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