@bivy/bivy 0.18.11-staging.9 → 0.19.0-staging.1

package/bin/bivy.mjs

@@ -35,7 +35,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { randomBytes, createCipheriv, createDecipheriv, randomUUID, createHash, verify as cryptoVerify } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import vm from "node:vm";
-import { selectStaleSessions, sessionActivityMs } from "./prune-sessions.mjs";
+import { linkSessionWorktrees, selectStaleSessions, sessionActivityMs } from "./prune-sessions.mjs";
 import { nativeResumeRef, resolveSessionsLimit, truncateSavedSessions } from "./sessions-list.mjs";
 import { renderManagedBlock, upsertManagedBlock, removeManagedBlock, rcFileForShell } from "./shim-path.mjs";
 import { removeInstallAndState } from "./uninstall-paths.mjs";
@@ -2466,7 +2466,7 @@ async function cmdSuggest(args = []) {
 // self-contained task from this session to another agent, optionally on another
 // account machine, and get its answer back. Agent-agnostic — any agent with a
 // shell can call it — and meant for when the user asks for another agent/machine.
-const DELEGATE_USAGE = `Usage: bivy delegate "<task>" [--agent <id>] [--machine <name>] [--model <model>] [--repo owner/repo] [--wait [seconds]] [--json]
+const DELEGATE_USAGE = `Usage: bivy delegate "<task>" [--agent <id>] [--machine <name>] [--model <model>] [--repo owner/repo] [--approval never|risky|always|autonomous] [--sandbox <tier>] [--wait [seconds]] [--json]
        bivy delegate "<task>" --to <agent>[@<machine>],<agent>[@<machine>],… [--wait [seconds]]
        bivy delegate machines [--json]
        bivy delegate status <run-id> [--json]
@@ -2480,7 +2480,12 @@ to several agents/machines at once (up to 3) so the results can be compared.
 
 async function cmdDelegate(args = []) {
   if (!args.length || args.some((a) => a === "-h" || a === "--help")) { console.log(DELEGATE_USAGE); return; }
-  const flagsWithValue = new Set(["--session", "--agent", "--machine", "--model", "--repo", "--timeout", "--to"]);
+  const flagsWithValue = new Set(["--session", "--agent", "--machine", "--model", "--repo", "--timeout", "--to", "--approval", "--sandbox"]);
+  // Children inherit this session's approval/sandbox unless set here.
+  const safetyFlags = () => {
+    const safety = { approval: flag("--approval"), sandbox: flag("--sandbox") };
+    return safety.approval || safety.sandbox ? { safety } : {};
+  };
   const flag = (name) => {
     const i = args.indexOf(name);
     return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
@@ -2506,7 +2511,8 @@ async function cmdDelegate(args = []) {
     if (!res.ok) throw new Error(data?.error || `HTTP ${res.status}`);
     return data;
   };
-  const terminal = (run) => ["succeeded", "failed", "cancelled"].includes(run?.status);
+  // needs_attention = parked by the machine's policy; it won't move on its own.
+  const terminal = (run) => ["succeeded", "failed", "cancelled", "needs_attention"].includes(run?.status);
   // The node caps one wait at 300s; loop until the child ends or our budget does.
   const waitFor = async (runId, seconds) => {
     const deadline = Date.now() + seconds * 1000;
@@ -2555,7 +2561,7 @@ async function cmdDelegate(args = []) {
       const group = `fanout-${Date.now().toString(36)}`;
       const runs = [];
       for (const target of targets) {
-        runs.push({ target, run: await call("", { instructions, agent: target.agent, machine: target.machine, model: flag("--model"), repo: flag("--repo"), group }) });
+        runs.push({ target, run: await call("", { instructions, agent: target.agent, machine: target.machine, model: flag("--model"), repo: flag("--repo"), ...safetyFlags(), group }) });
       }
       if (waitIndex < 0) {
         if (json) console.log(JSON.stringify(runs.map((r) => r.run), null, 2));
@@ -2568,7 +2574,7 @@ async function cmdDelegate(args = []) {
       return;
     }
     const agent = flag("--agent");
-    const started = await call("", { instructions, agent: agent ? governedChatAgentId(agent) : undefined, machine: flag("--machine"), model: flag("--model"), repo: flag("--repo") });
+    const started = await call("", { instructions, agent: agent ? governedChatAgentId(agent) : undefined, machine: flag("--machine"), model: flag("--model"), repo: flag("--repo"), ...safetyFlags() });
     if (waitIndex < 0) {
       if (!json) console.log(`Delegated as run ${started.runId} (${started.status}). Follow it with 'bivy delegate wait ${started.runId}'.`);
       else print(started);
@@ -3168,6 +3174,11 @@ ${c.bold("bivy prune")} — remove old sessions, --clone workspaces, and git wor
   is never pruned while the node is running, regardless of --keep/--older-than —
   only idle worktrees are removed. If the node is down, nothing is live to guard.
 
+  A session and its worktree are removed together: pruning a worktree also
+  removes the sessions that ran in it, pruning a session also removes its
+  worktree (once no remaining session uses it), and sessions whose worktree is
+  already gone are removed — so no session is left pointing at a deleted checkout.
+
   Paths (default to the installed node)
     --data-dir <dir>      node data dir (default: this install's .bivy, or $BIVY_DATA_DIR)
     --workspace <dir>     also scan this workspace for worktrees (default: configured workspace)
@@ -3235,12 +3246,41 @@ async function cmdPrune(args = []) {
   const now = Date.now();
   const plan = [];
   let worktreeGuard = { reachable: false, protected: 0 };
-  if (doSessions) {
-    // Sessions live in the metadata index (all agents) plus each agent's own
-    // transcript store — not just .bivy/pi/sessions. Select from metadata so
-    // shim/native (Claude Code, Codex, …) sessions are actually covered; the old
-    // pi-sessions-only scan silently no-oped for every terminal-started session.
-    const staleSessions = selectStaleSessions(loadMetadataSessions(dataDir).sessions, keepFor("sessions"), ageMs, now);
+  // Sessions live in the metadata index (all agents) plus each agent's own
+  // transcript store — not just .bivy/pi/sessions. Select from metadata so
+  // shim/native (Claude Code, Codex, …) sessions are actually covered; the old
+  // pi-sessions-only scan silently no-oped for every terminal-started session.
+  const allSessions = loadMetadataSessions(dataDir).sessions;
+  const selectedSessions = doSessions ? selectStaleSessions(allSessions, keepFor("sessions"), ageMs, now) : [];
+  // Worktrees: keep the newest N overall (across all roots), matching the node
+  // prune script. Scan roots: the data dir plus the configured workspace repo.
+  const worktreeRoots = findWorktreeRoots([dataDir, workspace].filter(Boolean));
+  const staleWorktrees = doWorktrees ? selectStale(worktreeRoots.flatMap((r) => pruneListEntries(r, "dir")), keepFor("worktrees"), ageMs, now) : [];
+  // Guard: never delete a worktree a live agent is using. Ask the daemon what's
+  // live (it owns every runtime and PTY); protected worktrees drop out of the
+  // removal set entirely, so an aggressive --older-than can't nuke a running
+  // agent's checkout. Node down ⇒ nothing live ⇒ policy alone is safe.
+  const live = await liveWorktreePaths(config);
+  const isLive = (p) => isLiveWorktree(p, live.paths);
+  const idleWorktrees = staleWorktrees.filter((e) => !isLive(e.path));
+  worktreeGuard = { reachable: live.reachable, protected: staleWorktrees.length - idleWorktrees.length };
+  // A session and its worktree go together: removing one without the other left
+  // sessions pointing at a deleted checkout (or checkouts nobody can reach).
+  const linked = linkSessionWorktrees({
+    sessions: allSessions,
+    staleSessions: selectedSessions,
+    staleWorktrees: idleWorktrees.map((e) => e.path),
+    isLive,
+    exists: (p) => fs.existsSync(p),
+  });
+  const staleSessions = linked.sessions;
+  const worktreeMtime = new Map(idleWorktrees.map((e) => [path.resolve(e.path), e.mtimeMs]));
+  const worktreesToRemove = linked.worktrees.map((p) => {
+    let mtimeMs = worktreeMtime.get(p);
+    if (mtimeMs === undefined) { try { mtimeMs = fs.statSync(p).mtimeMs; } catch { mtimeMs = now; } }
+    return { path: p, mtimeMs };
+  }).sort((a, b) => b.mtimeMs - a.mtimeMs);
+  if (doSessions || staleSessions.length) {
     plan.push({
       kind: "sessions",
       root: metadataFilePath(dataDir),
@@ -3263,20 +3303,8 @@ async function cmdPrune(args = []) {
     const dir = path.join(dataDir, "workspaces");
     plan.push({ kind: "workspaces", root: dir, remove: selectStale(pruneListEntries(dir, "dir"), keepFor("workspaces"), ageMs, now) });
   }
-  if (doWorktrees) {
-    // Keep the newest N worktrees overall (across all roots), matching the node
-    // prune script. Scan roots: the data dir plus the configured workspace repo.
-    const roots = findWorktreeRoots([dataDir, workspace].filter(Boolean));
-    const all = roots.flatMap((r) => pruneListEntries(r, "dir"));
-    const stale = selectStale(all, keepFor("worktrees"), ageMs, now);
-    // Guard: never delete a worktree a live agent is using. Ask the daemon what's
-    // live (it owns every runtime and PTY); protected worktrees drop out of the
-    // removal set entirely, so an aggressive --older-than can't nuke a running
-    // agent's checkout. Node down ⇒ nothing live ⇒ policy alone is safe.
-    const live = await liveWorktreePaths(config);
-    const remove = stale.filter((e) => !isLiveWorktree(e.path, live.paths));
-    worktreeGuard = { reachable: live.reachable, protected: stale.length - remove.length };
-    plan.push({ kind: "worktrees", root: roots.join(", ") || "(none found)", remove });
+  if (doWorktrees || worktreesToRemove.length) {
+    plan.push({ kind: "worktrees", root: worktreeRoots.join(", ") || "(none found)", remove: worktreesToRemove });
   }
   const total = plan.reduce((n, p) => n + p.remove.length, 0);
 

package/bin/prune-sessions.mjs

@@ -9,6 +9,8 @@
 // not just Pi's `.bivy/pi/sessions`. Prune selects from that index; these helpers
 // decide which entries are stale. No I/O here on purpose.
 
+import path from "node:path";
+
 // Mirrors the server's isEmptyUntitledSummary: a session with no real title, no
 // first message and no messages is the hidden "Untitled" noise the sidebar filters
 // out. Keep-N protects only *real* sessions; empties are always eligible.
@@ -30,6 +32,42 @@ export function sessionActivityMs(s) {
   return 0;
 }
 
+// A Bivy-managed worktree lives at <repo>/.bivy/worktrees/<slug>. Only those are
+// ever removed on a session's behalf — never an arbitrary path a record names.
+export function isManagedWorktreePath(p) {
+  const parts = path.resolve(String(p ?? "")).split(path.sep);
+  return parts.length >= 3 && parts[parts.length - 3] === ".bivy" && parts[parts.length - 2] === "worktrees";
+}
+
+// Sessions and their worktrees are pruned as one unit, so neither outlives the
+// other. Selection runs per kind (sessions and worktrees have different keep
+// counts), then this links the two removal sets:
+//   - a session goes when its worktree goes, or when its worktree is already
+//     gone from disk (a session that can no longer open its checkout);
+//   - a worktree goes when every session using it goes (and no live agent holds it).
+// Live ("working") sessions are never added, and their worktree is never removed. `isLive(path)` / `exists(path)` are
+// the caller's I/O; paths are compared resolved. Returns the widened sets.
+export function linkSessionWorktrees({ sessions, staleSessions, staleWorktrees, isLive = () => false, exists = () => true }) {
+  const removeSessions = new Map(staleSessions.map((s) => [s.id, s]));
+  const removeWorktrees = new Set(staleWorktrees.map((p) => path.resolve(p)));
+  const byWorktree = new Map();
+  for (const s of sessions) {
+    if (!s.worktree || !isManagedWorktreePath(s.worktree)) continue;
+    const wt = path.resolve(s.worktree);
+    byWorktree.set(wt, [...(byWorktree.get(wt) ?? []), s]);
+  }
+  for (const [wt, owners] of byWorktree) {
+    if (owners.some((s) => s.status === "working")) removeWorktrees.delete(wt);
+    else if (exists(wt) && owners.every((s) => removeSessions.has(s.id)) && !isLive(wt)) removeWorktrees.add(wt);
+  }
+  for (const [wt, owners] of byWorktree) {
+    if (!removeWorktrees.has(wt) && exists(wt)) continue;
+    for (const s of owners) if (s.status !== "working") removeSessions.set(s.id, s);
+  }
+  const sorted = [...removeSessions.values()].sort((a, b) => sessionActivityMs(b) - sessionActivityMs(a));
+  return { sessions: sorted, worktrees: [...removeWorktrees] };
+}
+
 // Removal set for sessions. Live ("working") sessions are never touched. The
 // newest `keep` NON-EMPTY sessions (across every agent) survive; empty/untitled
 // sessions are always beyond the keep window. An item is removed only when it is

package/dist/control-plane-tasks.js

@@ -121,8 +121,13 @@ export async function fetchPendingWork(cfg) {
 /** Consume the authoritative claim snapshot, not the earlier queue listing. */
 export async function claimWork(cfg, id) {
     const res = await cp(cfg, "POST", `/node/work/${encodeURIComponent(id)}/claim`, randomUUID());
-    if (!res.ok)
+    if (!res.ok) {
+        // 409 is the normal "another node won" race; anything else would otherwise
+        // leave an item silently pending forever.
+        if (res.status !== 409)
+            console.warn(`[control-plane-tasks] claim ${id} failed: HTTP ${res.status}`);
         return undefined;
+    }
     const data = await res.json();
     return data.item ?? { id }; // compatibility with older control planes
 }

package/dist/run-tools.js

@@ -12,6 +12,9 @@ export const RUN_TOOL_LIMITS = {
     maxAnswer: 8_000,
 };
 const TERMINAL = new Set(["succeeded", "failed", "cancelled"]);
+// Parked by the node's policy (usage limit, missing credentials): it won't
+// progress without a person, so waiting ends there and the reason comes back.
+const SETTLED = new Set([...TERMINAL, "needs_attention"]);
 const STATUSES = new Set(["pending", "claimed", "running", "waiting", "needs_attention", "succeeded", "failed", "cancelled"]);
 const SOURCE_PREFIX = "agent-delegation:v1:";
 const bounded = (v, n) => typeof v === "string" && v ? v.slice(0, n) : undefined;
@@ -109,7 +112,7 @@ export class RunDelegationService {
         if (!raw || provenance?.parentSessionId !== sessionId)
             throw new Error("delegated Run not found");
         const value = safeRun(raw, provenance);
-        if (TERMINAL.has(value.status) && this.backend.answer) {
+        if (SETTLED.has(value.status) && this.backend.answer) {
             // Best-effort: an unreachable machine still leaves status + references.
             const answer = cached?.value.answer ?? await this.backend.answer(raw).catch(() => undefined);
             if (answer)
@@ -132,7 +135,9 @@ export class RunDelegationService {
             const existing = expectedSource ? recent.find((r) => r.source === expectedSource) : undefined;
             if (existing)
                 return safeRun(existing, provenance);
-            const active = recent.filter((r) => parseDelegationSource(r.source)?.parentSessionId === sessionId && !TERMINAL.has(r.status)).length;
+            // A parked child (needs_attention) runs nothing until a person acts, so it
+            // doesn't hold one of the parent's concurrent slots.
+            const active = recent.filter((r) => parseDelegationSource(r.source)?.parentSessionId === sessionId && !SETTLED.has(r.status)).length;
             if (active >= RUN_TOOL_LIMITS.maxConcurrentChildren)
                 throw new Error(`concurrent child Run limit (${RUN_TOOL_LIMITS.maxConcurrentChildren}) reached`);
             const raw = await this.backend.start(sessionId, input, provenance);
@@ -155,7 +160,7 @@ export class RunDelegationService {
             if (signal?.aborted)
                 throw signal.reason ?? new Error("wait cancelled; the child Run may still be running");
             const result = await this.authorized(sessionId, runId, true);
-            if (TERMINAL.has(result.status))
+            if (SETTLED.has(result.status))
                 return result;
             if (this.now() >= deadline)
                 return { ...result, timedOut: true, wait: { timedOut: true, childContinues: true } };

package/dist/server.js

@@ -527,7 +527,7 @@ const runDelegation = new RunDelegationService({
             throw error;
         }
     },
-    start: async (_sessionId, input, provenance) => {
+    start: async (sessionId, input, provenance) => {
         const machine = input.machine?.trim() || identity.name;
         const nodes = await delegatedRunRequest("/nodes");
         const target = Array.isArray(nodes) ? nodes.find((node) => node && typeof node === "object" && node.name === machine) : undefined;
@@ -545,13 +545,20 @@ const runDelegation = new RunDelegationService({
             method: "POST",
             body: JSON.stringify({
                 title: "Delegated Run",
-                body: `bivy-room-v1:${targetId}:${seal(pairingStore.roomKey(), input.instructions)}`,
+                // Only the target machine can open its Run body, so seal with ITS room
+                // key: this machine's own for local work, the sibling's (learned over
+                // the sealed pairing handshake) for another machine.
+                body: `bivy-room-v1:${targetId}:${seal(targetId === identity.nodeId ? pairingStore.roomKey() : await siblingRoomKey(targetId), input.instructions)}`,
                 repo: input.repo,
                 node: machine,
                 runtimeId: input.agent,
                 model: input.model,
-                approvalMode: input.safety?.approval,
-                sandbox: input.safety?.sandbox,
+                // A child acts for the same user in the same context as its parent, so
+                // it inherits the parent session's safety unless the caller set one. The
+                // queue's own default ("risky" with nobody to approve) denied ordinary
+                // commands, leaving children that could only describe what they'd do.
+                approvalMode: input.safety?.approval ?? openSessions.get(sessionId)?.approvalMode,
+                sandbox: input.safety?.sandbox ?? openSessions.get(sessionId)?.sandbox,
                 maxAttempts: input.safety?.maxAttempts ?? 2,
                 idempotencyKey: input.idempotencyKey,
                 parentSessionId: provenance.parentSessionId,
@@ -568,7 +575,8 @@ const runDelegation = new RunDelegationService({
         if (!sessionId)
             return undefined;
         const routing = raw.routing && typeof raw.routing === "object" ? raw.routing : {};
-        const machine = typeof routing.nodeLabel === "string" && routing.nodeLabel ? routing.nodeLabel : identity.name;
+        // The queue routes by label `bivy/<machine>`.
+        const machine = typeof routing.nodeLabel === "string" && routing.nodeLabel ? routing.nodeLabel.replace(/^bivy\//, "") : identity.name;
         if (machine === identity.name)
             return delegationAnswer(sessionId);
         const target = (await accountMachines()).find((m) => m.name === machine);
@@ -604,6 +612,19 @@ async function siblingRequest(nodeId, command, timeoutMs = 20_000) {
         client.close();
     }
 }
+/** Another machine's room key, from a sealed pairing with it. */
+async function siblingRoomKey(nodeId) {
+    if (!sessionAdvertiseTarget)
+        throw new Error("This machine is not signed in to an account.");
+    const client = new SiblingClient({ controlPlaneUrl: sessionAdvertiseTarget.controlPlaneUrl, enrollmentToken: sessionAdvertiseTarget.enrollmentToken, siblingNodeId: nodeId, label: "Bivy delegation" });
+    try {
+        await client.connect();
+        return client.roomKey();
+    }
+    finally {
+        client.close();
+    }
+}
 /** Agents this machine can run a delegated task with (installed ones). */
 function localAgents() {
     return runtimeList().filter((rt) => rt.status === "available").map((rt) => ({ id: rt.id, name: String(rt.displayName || rt.id) }));
@@ -4650,11 +4671,7 @@ async function runIssueTaskInner(cfg, issue, source, overrides = {}) {
     sessionNamer.setSessionName(record, issueSessionTitle(issue));
     // Best-effort model selection for runtimes that support it (e.g. claude-code, pi).
     if (directives.model && typeof record.session.setModel === "function") {
-        try {
-            assertSessionModel(record, directives.model);
-            await record.session.setModel("", directives.model);
-        }
-        catch { }
+        await applyRequestedModel(record, { provider: "", id: directives.model });
     }
     if (!record.worktree)
         throw new Error("worktree was not created for the issue session");
@@ -4849,8 +4866,16 @@ async function runSessionTurn(record, prompt, signal) {
     if (signal?.aborted)
         throw signal.reason ?? new Error("Run cancelled");
     let unsubscribe = () => { };
+    // A turn the agent failed (usage limit, auth, crash) still ends with
+    // agent_end; remember why so the Run fails instead of reporting success.
+    let turnError = "";
     const finished = new Promise((resolve) => {
         unsubscribe = record.session.subscribe((event) => {
+            const e = event;
+            if (e.type === "session.error" && typeof e.error === "string")
+                turnError ||= e.error;
+            if (e.type === "message_end" && e.message?.stopReason === "error" && typeof e.message.errorMessage === "string")
+                turnError ||= e.message.errorMessage;
             if (event.type === "agent_end")
                 resolve();
         });
@@ -4865,6 +4890,8 @@ async function runSessionTurn(record, prompt, signal) {
     try {
         await turnWatchdog.promptWithWatchdog(record, prompt);
         await (signal ? Promise.race([finished, cancelled]) : finished);
+        if (turnError)
+            throw new Error(turnError);
     }
     finally {
         signal?.removeEventListener("abort", onAbort);
@@ -5324,12 +5351,23 @@ async function delegationAnswer(sessionId) {
         const message = messages[i];
         if (message?.role !== "assistant")
             continue;
+        // A turn the agent failed (usage limit, auth) ends on an error marker, not
+        // prose: hand the parent the reason instead of an empty answer.
+        if (message.stopReason === "error" && typeof message.errorMessage === "string" && message.errorMessage.trim())
+            return `The delegated agent failed: ${message.errorMessage.trim()}`;
         const text = runtimeContentText(message.content).trim();
         if (text)
             return text;
     }
     return undefined;
 }
+/** A delegated task's first line, bounded, as its child session's title. */
+function delegatedSessionTitle(instructions) {
+    const line = instructions?.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+    if (!line)
+        return undefined;
+    return line.length > 80 ? `${line.slice(0, 79).trimEnd()}…` : line;
+}
 /** Text of the most recent user message in a session's transcript, if any. */
 function lastUserMessageText(record) {
     const messages = record.session.getMessages();
@@ -5484,12 +5522,8 @@ async function executeWorkItem(item, report, signal) {
             approvalMode: safety.approval,
         });
         sessionNamer.setSessionName(record, `${issue.identifier}: ${issue.title}`);
-        if (item.model) {
-            try {
-                await record.session.setModel("", item.model);
-            }
-            catch { }
-        }
+        if (item.model)
+            await applyRequestedModel(record, { provider: "", id: item.model });
         await report({ output: { sessionId: record.id, branch }, events: [{ at: new Date().toISOString(), kind: "branch", summary: "Linear issue working branch and session created.", ref: branch, url: issue.url }] });
         await runSessionTurn(record, buildLinearTaskPrompt(issue, item.body), signal);
         if (signal.aborted)
@@ -5563,13 +5597,13 @@ async function executeWorkItem(item, report, signal) {
     // sends after the Run is mistaken for the Session's first naming prompt (the
     // internal Run turn does not pass through the interactive prompt handler), so
     // rows named after the Run suddenly become "status", "continue", etc.
-    sessionNamer.setSessionName(record, item.title);
+    // A delegated child's queue title is generic ("Delegated Run": the task is
+    // sealed, the queue never sees it). Name it after the task itself, which
+    // only this machine can read, so it's recognizable in the session list.
+    sessionNamer.setSessionName(record, delegatedProvenance ? delegatedSessionTitle(item.body) ?? item.title : item.title);
     persistSessionMetadata(record);
     if (item.model) {
-        try {
-            await record.session.setModel("", item.model);
-        }
-        catch { }
+        await applyRequestedModel(record, { provider: "", id: item.model });
     }
     // Record the session id with the control plane BEFORE the (potentially long)
     // turn runs, not just after it completes. A machine restart mid-turn must leave

package/dist/session/sibling-client.js

@@ -30,6 +30,7 @@ export class SiblingClient {
     opts;
     ws;
     cipher;
+    siblingRoomKey;
     keypair = newDeviceKeypair();
     reassembler = new FrameReassembler({ onReject: () => this.ws?.close() });
     transfers = new EventTransferReceiver({
@@ -80,7 +81,23 @@ export class SiblingClient {
         ws.on("message", (data) => this.onMessage(String(data), grant));
         ws.on("close", () => this.handleClose());
         ws.on("error", (err) => this.rejectPaired?.(err));
-        await this.paired;
+        // A sibling that never answers pairing (offline behind a stale "online",
+        // or an incompatible build) must fail, not hang its caller forever.
+        const timeoutMs = this.opts.pairTimeoutMs ?? 20_000;
+        let timer;
+        try {
+            await Promise.race([
+                this.paired,
+                new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("sibling did not answer pairing")), timeoutMs); }),
+            ]);
+        }
+        catch (err) {
+            this.close();
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     async onMessage(raw, grant) {
         let msg;
@@ -94,11 +111,23 @@ export class SiblingClient {
             // Begin account pairing to obtain the sibling's room key.
             // `ephemeral`: a sibling replica is a node↔node bridge, not a user device —
             // authorized for the room key but never listed as a signed-in device.
-            this.sendControl({ t: "pair", p: { k: "pair.account", sessionToken: grant, devicePublicKeyB64: this.keypair.publicKeyB64, label: this.opts.label ?? "Bivy replica", ephemeral: true } });
+            // Pair payloads travel as a JSON string, as the node's relay client
+            // expects (it ignores any other shape) and as it replies.
+            this.sendControl({ t: "pair", p: JSON.stringify({ k: "pair.account", sessionToken: grant, devicePublicKeyB64: this.keypair.publicKeyB64, label: this.opts.label ?? "Bivy replica", ephemeral: true }) });
             return;
         }
         if (msg.t === "pair") {
-            this.handlePair(msg.p);
+            let pair = msg.p;
+            if (typeof pair === "string") {
+                try {
+                    pair = JSON.parse(pair);
+                }
+                catch {
+                    return;
+                }
+            }
+            if (pair && typeof pair === "object")
+                this.handlePair(pair);
             return;
         }
         if (msg.t === "frame" && typeof msg.p === "string" && this.cipher) {
@@ -119,6 +148,7 @@ export class SiblingClient {
         if (k === "pair.welcome") {
             try {
                 const roomKey = acceptWelcome(this.keypair, { nodePublicKeyB64: String(p.nodePublicKeyB64 ?? ""), wrapped: String(p.wrapped ?? "") });
+                this.siblingRoomKey = roomKey;
                 this.cipher = new RoomCipher(roomKey);
                 this.resolvePaired?.();
             }
@@ -141,6 +171,13 @@ export class SiblingClient {
         }
         this.opts.onEvent?.(event);
     }
+    /** The sibling's room key, once paired: what seals content only it can read
+     *  (e.g. a delegated Run's instructions queued for that machine). */
+    roomKey() {
+        if (!this.siblingRoomKey)
+            throw new Error("sibling client not paired");
+        return this.siblingRoomKey;
+    }
     /** Send a command and await its correlated reply event (by requestId). */
     request(command, timeoutMs = 30_000) {
         const requestId = `repl-${++this.reqSeq}-${Date.now()}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.18.11-staging.9",
+  "version": "0.19.0-staging.1",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",