@bivy/bivy 0.18.11-staging.8 → 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,17 +2466,26 @@ 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]
        bivy delegate wait <run-id> [--timeout <seconds>] [--json]
 
 Hands a self-contained task to another agent (and/or another machine on your account) as a
 delegated Run tied to this session ($BIVY_SESSION_ID). With --wait (or 'wait'), prints the
-child's final answer and any branch/PR it produced once it finishes. 'bivy nodes' lists machines.`;
+child's final answer and any branch/PR it produced once it finishes. --to sends the same task
+to several agents/machines at once (up to 3) so the results can be compared.
+'machines' lists your machines and the agents installed on each.`;
 
 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"]);
+  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;
@@ -2502,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;
@@ -2525,11 +2535,46 @@ async function cmdDelegate(args = []) {
   };
   try {
     const [action, runId] = positional;
+    if (action === "machines" && positional.length === 1) {
+      const res = await fetch(`${url(config)}/api/machines`, { headers: token ? { authorization: `Bearer ${token}` } : {} });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(data?.error || `HTTP ${res.status}`);
+      if (json) { console.log(JSON.stringify(data.machines, null, 2)); return; }
+      for (const m of data.machines || []) {
+        const agents = m.agents ? m.agents.map((a) => a.id).join(", ") || "none" : m.error ? `unknown (${m.error})` : "unknown while offline";
+        console.log(`${m.name}${m.self ? " (this machine)" : ""} — ${m.online ? "online" : "offline"} — agents: ${agents}`);
+      }
+      return;
+    }
     if (action === "status" && runId) return print(await call(`/${encodeURIComponent(runId)}`));
     if (action === "wait" && runId) return print(await waitFor(runId, Number(flag("--timeout") ?? 600)));
     const instructions = positional.join(" ").trim();
     if (!instructions) { console.error(c.red(DELEGATE_USAGE)); process.exit(1); return; }
-    const started = await call("", { instructions, agent: flag("--agent"), machine: flag("--machine"), model: flag("--model"), repo: flag("--repo") });
+    // Fan-out: the same task to several agent@machine targets, one group, so the
+    // parent's transcript shows them side by side to compare.
+    const to = flag("--to");
+    if (to) {
+      const targets = to.split(",").map((t) => t.trim()).filter(Boolean).map((t) => {
+        const [agent, machine] = t.split("@");
+        return { agent: agent ? governedChatAgentId(agent) : undefined, machine: machine || undefined, label: t };
+      });
+      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"), ...safetyFlags(), group }) });
+      }
+      if (waitIndex < 0) {
+        if (json) console.log(JSON.stringify(runs.map((r) => r.run), null, 2));
+        else for (const { target, run } of runs) console.log(`${target.label}: run ${run.runId} (${run.status})`);
+        return;
+      }
+      const finished = await Promise.all(runs.map(async ({ target, run }) => ({ target, run: await waitFor(run.runId, Number(waitArg ?? 600)) })));
+      if (json) { console.log(JSON.stringify(finished.map((f) => f.run), null, 2)); return; }
+      for (const { target, run } of finished) { console.log(`\n── ${target.label}`); print(run); }
+      return;
+    }
+    const agent = flag("--agent");
+    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);
@@ -3129,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)
@@ -3196,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),
@@ -3224,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/agent-instructions.js

@@ -44,7 +44,8 @@ export const BIVY_AGENT_NOTE = [
         "write it to stand on its own, with paths relative to the project root.",
     "- Only when the user asks for another agent or another of their machines to take part: " +
         '`bivy delegate "<self-contained task>" --agent <id> [--machine <name>] --wait` runs it there and prints ' +
-        "its answer and any branch/PR (`bivy nodes` lists machines). Use your own sub-agents for everything else.",
+        "its answer and any branch/PR; `--to codex,grok@<machine>` asks several to compare, `bivy delegate machines` " +
+        "lists machines and their agents. Use your own sub-agents for everything else.",
 ].join("\n");
 const PREAMBLE = "The user's global Bivy instructions follow. They apply to every workspace; where they conflict with " +
     "instructions from the current repository (AGENTS.md, CLAUDE.md, …), the repository's instructions win.";

package/dist/apps/styles.css

@@ -354,6 +354,9 @@ input, textarea, select { font-family: inherit; font-size: 16px; }
 @keyframes dot-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.6; } }
 .session-row { position: relative; display: flex; align-items: center; }
 .session-row .session-item { flex: 1; min-width: 0; }
+/* A delegated child under its parent session (sessionNesting.ts). */
+.session-row.nested { padding-inline-start: var(--space-4); }
+.session-row.nested::before { content: ""; position: absolute; inset-block: var(--space-2); inset-inline-start: var(--space-2); border-inline-start: 1px solid var(--line-strong); }
 .pending-launch-actions { display: flex; flex: none; gap: 4px; padding-right: 6px; }
 .pending-launch-actions button { min-height: var(--space-7); min-width: var(--space-7); border: 1px solid var(--line-strong); border-radius: var(--radius-sm); background: var(--surface-2); color: var(--ink); padding: 5px 8px; font-size: 12px; cursor: pointer; }
 .pending-launch-actions button:last-child { color: var(--muted); background: transparent; }
@@ -3107,6 +3110,26 @@ p.setup-note .btn.link { min-height: 44px; margin-block: calc((1lh - 44px) / 2);
 .suggestion-actions, .suggestion-all { display: flex; flex-wrap: wrap; gap: var(--space-2); margin-top: var(--space-2); }
 .suggestion-all { padding-top: var(--space-2); border-top: 1px solid var(--line); }
 .suggestion-status { margin: var(--space-2) 0 0; display: flex; align-items: center; gap: var(--space-2); color: var(--ok); font-size: var(--text-sm); font-weight: var(--weight-medium); }
+/* Delegation (DelegationCard.tsx): a task handed to another agent/machine.
+   Shell from .card, status from .badge; layout only here. A fan-out renders as
+   one group whose members sit side by side where there is room. */
+.delegation-card { max-inline-size: 440px; display: flex; flex-direction: column; gap: var(--space-1); }
+.delegation-eyebrow { margin: 0; color: var(--muted); font-size: var(--text-xs); font-weight: var(--weight-semibold); }
+.delegation-head { display: flex; align-items: center; justify-content: space-between; gap: var(--space-2); }
+.delegation-head { align-items: flex-start; }
+.delegation-target { display: flex; flex-direction: column; font-weight: var(--weight-semibold); overflow-wrap: anywhere; min-inline-size: 0; }
+.delegation-machine { color: var(--muted); font-size: var(--text-xs); font-weight: var(--weight-normal); }
+.delegation-task { margin: 0; color: var(--muted); font-size: var(--text-sm); overflow-wrap: anywhere; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+.delegation-failure { margin: 0; color: var(--danger); font-size: var(--text-sm); overflow-wrap: anywhere; }
+.delegation-answer summary { cursor: pointer; color: var(--muted); font-size: var(--text-sm); }
+.delegation-answer p { margin: var(--space-1) 0 0; font-size: var(--text-sm); white-space: pre-wrap; overflow-wrap: anywhere; max-block-size: 18em; overflow-y: auto; }
+.delegation-refs { margin: 0; display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-2); font-size: var(--text-sm); }
+.delegation-refs code { overflow-wrap: anywhere; }
+.delegation-actions { display: flex; flex-wrap: wrap; gap: var(--space-2); }
+.delegation-group { display: flex; flex-direction: column; gap: var(--space-1); margin-block: var(--space-2); }
+.delegation-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: var(--space-2); }
+.delegation-member { display: flex; flex-direction: column; gap: var(--space-1); min-inline-size: 0; }
+.delegation-member > .btn { align-self: flex-start; }
 /* Review card (ReviewCard.tsx): the app at a moment worth judging. The
    screenshot is shown whole, phone-shaped, on a quiet stage; Before/Now is the
    canonical .segmented switch; one primary action. */

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/runtime/tool-call-map.js

@@ -111,7 +111,7 @@ const PATH_KEYS = ["path", "file_path", "filePath", "filename", "fileName", "fil
  */
 function bivyDelegation(command) {
     const match = /^\s*bivy\s+delegate\b(.*)$/s.exec(command);
-    if (!match || /^\s+(status|wait|--help|-h)\b/.test(match[1]))
+    if (!match || /^\s+(status|wait|machines|--help|-h)\b/.test(match[1]))
         return undefined;
     const rest = match[1];
     const flag = (name) => new RegExp(`--${name}(?:=|\\s+)("([^"]*)"|'([^']*)'|(\\S+))`).exec(rest);
@@ -120,7 +120,8 @@ function bivyDelegation(command) {
     const machine = value(flag("machine"));
     const quoted = /(?:^|\s)("([^"]+)"|'([^']+)')/.exec(rest.replace(/--[a-z-]+(?:=|\s+)("[^"]*"|'[^']*'|\S+)/g, ""));
     const description = quoted ? (quoted[2] ?? quoted[3]) : undefined;
-    const label = [agent, machine && `@ ${machine}`].filter(Boolean).join(" ") || undefined;
+    const to = value(flag("to"))?.split(",").map((t) => t.trim().replace("@", " @ ")).filter(Boolean).join(", ");
+    const label = to || [agent, machine && `@ ${machine}`].filter(Boolean).join(" ") || undefined;
     return { ...(label ? { label } : {}), ...(description ? { description } : {}) };
 }
 /**

package/dist/server.js

@@ -161,6 +161,8 @@ import { synthesizeOpenAiSpeech } from "./tts.js";
 import { seal, open } from "./e2e.js";
 import { recoverModelAuthKey } from "./model-auth-key-recovery.js";
 import { RunDelegationService, parseDelegationSource } from "./run-tools.js";
+import { delegationCard } from "./session/delegation-cards.js";
+import { TERMINAL_DELEGATION, isDelegatedFrom } from "./session/delegations.js";
 import { ControlPlaneTaskPoller, resolveControlPlaneTaskConfig, } from "./control-plane-tasks.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..");
@@ -525,24 +527,38 @@ 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;
         const targetId = typeof target?.id === "string" ? target.id : machine === identity.name ? identity.nodeId : undefined;
         if (!targetId)
             throw new Error(`Machine not found on this account: ${machine}`);
+        // Fail up front, with what IS there, rather than when the machine claims the Run.
+        if (input.agent) {
+            const agents = targetId === identity.nodeId ? localAgents() : await siblingAgents(targetId).catch(() => undefined);
+            if (agents && !agents.some((agent) => agent.id === input.agent)) {
+                throw new Error(`Agent "${input.agent}" is not installed on ${machine} (it has: ${agents.map((agent) => agent.id).join(", ") || "none"})`);
+            }
+        }
         return delegatedRunRequest("/node/automation-runs", {
             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,
@@ -559,24 +575,130 @@ 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 nodes = await delegatedRunRequest("/nodes");
-        const target = Array.isArray(nodes) ? nodes.find((node) => node && typeof node === "object" && node.name === machine) : undefined;
-        if (typeof target?.id !== "string" || !sessionAdvertiseTarget)
+        const target = (await accountMachines()).find((m) => m.name === machine);
+        if (!target)
             return undefined;
-        const client = new SiblingClient({ controlPlaneUrl: sessionAdvertiseTarget.controlPlaneUrl, enrollmentToken: sessionAdvertiseTarget.enrollmentToken, siblingNodeId: target.id, label: "Bivy delegation" });
+        const reply = await siblingRequest(target.id, { kind: "delegation.answer", sessionId });
+        return typeof reply.answer === "string" ? reply.answer : undefined;
+    },
+});
+/** The account's machines (id, name, online), briefly cached. */
+let machinesCache;
+async function accountMachines() {
+    if (machinesCache && Date.now() - machinesCache.at < 20_000)
+        return machinesCache.machines;
+    const nodes = await delegatedRunRequest("/nodes");
+    const machines = (Array.isArray(nodes) ? nodes : []).flatMap((node) => {
+        const n = node && typeof node === "object" ? node : {};
+        return typeof n.id === "string" && typeof n.name === "string" ? [{ id: n.id, name: n.name, online: n.online === true }] : [];
+    });
+    machinesCache = { at: Date.now(), machines };
+    return machines;
+}
+/** One sealed request to a co-owned machine over the relay (node as client). */
+async function siblingRequest(nodeId, command, timeoutMs = 20_000) {
+    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 await client.request(command, timeoutMs);
+    }
+    finally {
+        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) }));
+}
+async function siblingAgents(nodeId) {
+    const reply = await siblingRequest(nodeId, { kind: "agents.available" }, 10_000);
+    return Array.isArray(reply.agents) ? reply.agents.flatMap((a) => {
+        const agent = a && typeof a === "object" ? a : {};
+        return typeof agent.id === "string" ? [{ id: agent.id, name: typeof agent.name === "string" ? agent.name : agent.id }] : [];
+    }) : [];
+}
+async function machinesWithAgents() {
+    const machines = await accountMachines();
+    return Promise.all(machines.map(async (m) => {
+        const self = m.id === identity.nodeId;
+        if (self)
+            return { ...m, online: true, self, agents: localAgents() };
+        if (!m.online)
+            return { ...m, self };
         try {
-            await client.connect();
-            const reply = await client.request({ kind: "delegation.answer", sessionId }, 20_000);
-            return typeof reply.answer === "string" ? reply.answer : undefined;
+            return { ...m, self, agents: await siblingAgents(m.id) };
         }
-        finally {
-            client.close();
+        catch (error) {
+            return { ...m, self, error: error instanceof Error ? error.message : String(error) };
         }
-    },
-});
+    }));
+}
+/** Fold a delegated Run's latest status into its card in the parent session. */
+function recordDelegation(parentSessionId, run, start) {
+    const record = resolveSession(parentSessionId);
+    if (!record)
+        return run;
+    const prev = eventLog.delegations(record.id).find((card) => card.id === run.runId);
+    const card = delegationCard(prev, run, start);
+    if (prev && JSON.stringify(prev) === JSON.stringify(card))
+        return run;
+    eventLog.appendDelegation(record.id, { afterMessageCount: record.session.getMessages().length, delegation: card });
+    broadcast(stampSessionEvent({ type: "session.event", sessionId: record.id, event: { type: "delegation", delegation: card } }));
+    if (card.childSessionId && !prev?.childSessionId)
+        void linkDelegatedChild(record, card).catch(() => { });
+    return run;
+}
+/** Tell the child session where it came from — locally, or on its machine. */
+async function linkDelegatedChild(parent, card) {
+    const from = { sessionId: parent.id, nodeId: identity.nodeId, machine: identity.name, ...(parent.session.getName() ? { title: parent.session.getName().slice(0, 256) } : {}) };
+    if (!card.nodeId || card.nodeId === identity.nodeId) {
+        applyDelegationLink(card.childSessionId, from);
+        return;
+    }
+    await siblingRequest(card.nodeId, { kind: "delegation.link", childSessionId: card.childSessionId, parent: from }, 10_000);
+}
+function applyDelegationLink(childSessionId, from) {
+    const record = resolveSession(childSessionId);
+    if (!record && !metadata.getSession(childSessionId))
+        return false;
+    if (record)
+        record.delegatedFrom = from;
+    metadata.upsertSession({ id: childSessionId, delegatedFrom: from });
+    if (record)
+        broadcast({ type: "session.updated", sessionId: record.id, sessionFile: record.sessionFile, bivySession: bivySessionEnvelope(record) });
+    scheduleAdvertise();
+    return true;
+}
+// Children rarely finish while someone is polling them: keep the parent's open
+// cards current in the background (cheap: cached, and only non-terminal ones).
+setInterval(() => {
+    for (const record of new Set(openSessions.values())) {
+        for (const card of eventLog.delegations(record.id)) {
+            if (TERMINAL_DELEGATION.has(card.status))
+                continue;
+            void runDelegation.getRunStatus(record.id, card.id).then((run) => recordDelegation(record.id, run)).catch(() => { });
+        }
+    }
+}, 15_000).unref();
 // Delegated Runs remain available through the explicit Session API, but are not
 // exposed as agent tools. Coding agents should use their own native sub-agent
 // facilities; advertising Runs here caused routine work to create noisy,
@@ -2434,6 +2556,16 @@ const RELAY_COMMANDS = {
     },
     // A co-owned node asking for a delegated child's answer over the sealed
     // node-to-node channel (see runDelegation.answer). Replies to the requester.
+    // Discovery: which agents this machine can run (docs/agent-delegation.md).
+    "agents.available"(msg, ctx) {
+        ctx.reply({ type: "agents.available", requestId: msg.requestId, machine: identity.name, agents: localAgents() });
+    },
+    // The parent of a delegated child session on this machine introduces itself,
+    // so the child can show and link where it came from.
+    "delegation.link"(msg, ctx) {
+        const linked = typeof msg.childSessionId === "string" && isDelegatedFrom(msg.parent) ? applyDelegationLink(msg.childSessionId, msg.parent) : false;
+        ctx.reply({ type: "delegation.link", requestId: msg.requestId, linked });
+    },
     async "delegation.answer"(msg, ctx) {
         const sessionId = typeof msg.sessionId === "string" ? msg.sessionId : "";
         const answer = sessionId ? await delegationAnswer(sessionId).catch(() => undefined) : undefined;
@@ -4539,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");
@@ -4738,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();
         });
@@ -4754,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);
@@ -5213,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();
@@ -5373,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)
@@ -5452,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
@@ -6384,6 +6529,7 @@ async function sessionListRows() {
             source: rec?.source ?? meta?.source,
             bivyCreated: Boolean(meta),
             forkedFrom: rec?.forkedFrom ?? meta?.forkedFrom,
+            delegatedFrom: rec?.delegatedFrom ?? meta?.delegatedFrom,
             branch: rec?.worktree?.branch ?? meta?.branch,
             sandbox: rec?.sandbox ?? normalizeSandboxTier(meta?.sandbox),
             approvalMode: rec?.approvalMode,
@@ -6669,6 +6815,7 @@ function persistSessionMetadata(record, status = sessionStatus(record)) {
         workspace: record.workspace,
         source: record.source ?? "manual",
         forkedFrom: record.forkedFrom,
+        delegatedFrom: record.delegatedFrom,
         automationRunId: record.automationRunId,
         delegationDepth: record.delegationDepth,
         runtimeId: record.runtimeId,
@@ -8493,7 +8640,7 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
     // Rehydrating (rather than leaving this undefined for a resumed session)
     // also avoids a persistSessionMetadata call later silently clobbering the
     // stored contract with undefined via its `{...prev, ...input}` merge.
-    const record = { id: sessionId, session, runtimeId: rt.id, credentialLabels, sandbox: sessionSandbox, approvalMode: sessionSafety.approval, automationRunId: storedMeta?.automationRunId, delegationDepth: storedMeta?.delegationDepth, workspace: sessionWorkspace, sessionFile: session.sessionFile, agentServiceAddress: attachedAddress ?? rt.agentServiceAddress, worktree, source, prUrl: storedMeta?.prUrl, prs: storedMeta?.prs, contract: storedMeta?.contract, lastTouchedAt: resumedLastActive ?? Date.now(), warning: modelFallbackMessage, ephemeral: opts.ephemeral, workspaceState: runGit(["status", "--porcelain", "--untracked-files=normal"], sessionWorkspace) ? "dirty" : "clean" };
+    const record = { id: sessionId, session, runtimeId: rt.id, credentialLabels, sandbox: sessionSandbox, approvalMode: sessionSafety.approval, automationRunId: storedMeta?.automationRunId, delegationDepth: storedMeta?.delegationDepth, workspace: sessionWorkspace, sessionFile: session.sessionFile, agentServiceAddress: attachedAddress ?? rt.agentServiceAddress, worktree, source, prUrl: storedMeta?.prUrl, prs: storedMeta?.prs, delegatedFrom: storedMeta?.delegatedFrom, contract: storedMeta?.contract, lastTouchedAt: resumedLastActive ?? Date.now(), warning: modelFallbackMessage, ephemeral: opts.ephemeral, workspaceState: runGit(["status", "--porcelain", "--untracked-files=normal"], sessionWorkspace) ? "dirty" : "clean" };
     // Migration: a session resumed/reopened from before this feature (or from a
     // node that predates it) has no stored contract. Stamp an honest one now
     // from currently-observed facts rather than leaving it blank forever or
@@ -10423,6 +10570,7 @@ app.get("/api/sessions", async (_req, res, next) => {
                 source: rec?.source ?? meta?.source,
                 bivyCreated: Boolean(meta),
                 forkedFrom: rec?.forkedFrom ?? meta?.forkedFrom,
+                delegatedFrom: rec?.delegatedFrom ?? meta?.delegatedFrom,
                 branch: rec?.worktree?.branch ?? meta?.branch,
                 prUrl: rec?.prUrl ?? meta?.prUrl,
                 prs: rec?.prs ?? meta?.prs,
@@ -11339,7 +11487,12 @@ app.post("/api/session/:id/suggest", (req, res) => {
 // authorizes every status lookup against this parent Session's provenance.
 app.post("/api/session/:id/delegated-runs", async (req, res) => {
     try {
-        res.status(201).json(await runDelegation.startRun(String(req.params.id), req.body));
+        const input = req.body;
+        const result = await runDelegation.startRun(String(req.params.id), input);
+        const machine = input.machine?.trim() || identity.name;
+        const nodeId = (await accountMachines().catch(() => [])).find((m) => m.name === machine)?.id ?? (machine === identity.name ? identity.nodeId : undefined);
+        recordDelegation(String(req.params.id), result, { instructions: input.instructions, agent: input.agent, machine, nodeId, group: typeof input.group === "string" ? input.group.slice(0, 64) : undefined });
+        res.status(201).json(result);
     }
     catch (error) {
         res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
@@ -11347,7 +11500,7 @@ app.post("/api/session/:id/delegated-runs", async (req, res) => {
 });
 app.get("/api/session/:id/delegated-runs/:runId", async (req, res) => {
     try {
-        res.json(await runDelegation.getRunStatus(String(req.params.id), String(req.params.runId)));
+        res.json(recordDelegation(String(req.params.id), await runDelegation.getRunStatus(String(req.params.id), String(req.params.runId))));
     }
     catch (error) {
         res.status(404).json({ error: error instanceof Error ? error.message : String(error) });
@@ -11355,7 +11508,18 @@ app.get("/api/session/:id/delegated-runs/:runId", async (req, res) => {
 });
 app.post("/api/session/:id/delegated-runs/:runId/wait", async (req, res) => {
     try {
-        res.json(await runDelegation.waitForRun(String(req.params.id), String(req.params.runId), Number(req.body?.timeoutSeconds), AbortSignal.timeout(305_000)));
+        res.json(recordDelegation(String(req.params.id), await runDelegation.waitForRun(String(req.params.id), String(req.params.runId), Number(req.body?.timeoutSeconds), AbortSignal.timeout(305_000))));
+    }
+    catch (error) {
+        res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
+    }
+});
+// The account's machines and the agents installed on each (asked of every
+// online machine over the sealed node-to-node channel), for `bivy delegate
+// machines` and for picking a valid agent @ machine up front.
+app.get("/api/machines", async (_req, res) => {
+    try {
+        res.json({ machines: await machinesWithAgents() });
     }
     catch (error) {
         res.status(400).json({ error: error instanceof Error ? error.message : String(error) });

package/dist/session/delegation-cards.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Pure: fold a delegated Run's latest status into its card in the parent
+// session (docs/agent-delegation.md). The server logs and broadcasts the result.
+import { MAX_DELEGATION_ANSWER, MAX_DELEGATION_TASK } from "./delegations.js";
+const bound = (value, max) => value && value.length > max ? `${value.slice(0, max - 1)}…` : value;
+export function delegationCard(prev, run, start) {
+    const refs = run.references ?? {};
+    const task = start ? bound(start.instructions.trim().split(/\r?\n/, 1)[0] ?? "", MAX_DELEGATION_TASK) : prev?.task ?? "";
+    const pick = (key, next) => (next ?? prev?.[key]);
+    const card = { id: run.runId, status: run.status, task };
+    const fields = {
+        agent: pick("agent", start?.agent),
+        machine: pick("machine", start?.machine),
+        nodeId: pick("nodeId", start?.nodeId),
+        group: pick("group", start?.group),
+        childSessionId: pick("childSessionId", refs.sessionId),
+        answer: pick("answer", bound(run.answer, MAX_DELEGATION_ANSWER)),
+        branch: pick("branch", refs.branch),
+        prUrl: pick("prUrl", refs.prUrl),
+        failure: pick("failure", refs.failure),
+    };
+    for (const [key, value] of Object.entries(fields))
+        if (value)
+            card[key] = value;
+    return card;
+}

package/dist/session/delegations.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+export const DELEGATION_BLOCK = "bivy_delegation";
+export const MAX_DELEGATION_TASK = 200;
+export const MAX_DELEGATION_ANSWER = 8000;
+export const TERMINAL_DELEGATION = new Set(["succeeded", "failed", "cancelled"]);
+const optionalString = (v) => v === undefined || typeof v === "string";
+export function isDelegationCard(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const d = value;
+    return typeof d.id === "string" && d.id.length > 0 && typeof d.status === "string" && typeof d.task === "string"
+        && [d.agent, d.machine, d.nodeId, d.group, d.childSessionId, d.answer, d.branch, d.prUrl, d.failure].every(optionalString);
+}
+export function isDelegatedFrom(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const d = value;
+    return typeof d.sessionId === "string" && d.sessionId.length > 0 && d.sessionId.length <= 256
+        && [d.nodeId, d.machine, d.title].every((v) => v === undefined || (typeof v === "string" && v.length <= 256));
+}

package/dist/session/event-log.js

@@ -29,6 +29,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { normalizedIntermediateText, thinkingTextFromContent, mergeTranscript } from "./transcript-merge.js";
+import { DELEGATION_BLOCK, isDelegationCard } from "./delegations.js";
 import { APP_PUBLICATION_BLOCK, APP_REVIEW_BLOCK, isAppReference, isAppReview } from "../apps/types.js";
 import { SUGGESTION_BLOCK, isTaskSuggestion } from "./suggestions.js";
 /**
@@ -254,6 +255,12 @@ function isSuggestionEntry(value) {
     const entry = value;
     return entry.bivyKind === "suggestion" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isTaskSuggestion(entry.suggestion);
 }
+function isDelegationEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return entry.bivyKind === "delegation" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isDelegationCard(entry.delegation);
+}
 function isAppReviewEntry(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -261,7 +268,7 @@ function isAppReviewEntry(value) {
     return entry.bivyKind === "app-review" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isAppReview(entry.review);
 }
 function isRecord(value) {
-    return isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isSuggestionEntry(value);
+    return isDelegationEntry(value) || isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isSuggestionEntry(value);
 }
 /**
  * Fold attachment records into a text→refs list: last write wins per text (a
@@ -383,11 +390,23 @@ export function replayExtras(entries) {
         role: "assistant", content: [{ type: APP_REVIEW_BLOCK, review: entry.review }],
         id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
     }));
+    // A delegation card keeps the place it was created and shows its latest state.
+    const delegations = new Map();
+    for (const entry of entries) {
+        if (entry.bivyKind !== "delegation")
+            continue;
+        const first = delegations.get(entry.id);
+        delegations.set(entry.id, first ? { ...first, delegation: entry.delegation } : entry);
+    }
+    const delegationCards = [...delegations.values()].map((entry) => ({
+        role: "assistant", content: [{ type: DELEGATION_BLOCK, delegation: entry.delegation }],
+        id: `delegation-${entry.id}`, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
+    }));
     const suggestions = entries.filter((entry) => entry.bivyKind === "suggestion").map((entry) => ({
         role: "assistant", content: [{ type: SUGGESTION_BLOCK, suggestion: entry.suggestion }],
         id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
     }));
-    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...suggestions];
+    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...delegationCards, ...suggestions];
 }
 /**
  * Fold the outbound (agent-sent) attachment records into time-anchored synthetic
@@ -683,6 +702,19 @@ export class EventLog {
         this.enqueue(id, `app:${entry.id}`, { ...entry, app: { ...entry.app }, bivyKind: "app-publication", createdAt: Date.now() });
     }
     /** `createdAt`/`afterMessageCount` place the card; an expired card keeps its original place. */
+    /** Record a delegation card's latest state; replay keeps its first position. */
+    appendDelegation(id, entry) {
+        this.load(id);
+        this.enqueue(id, this.syntheticKey(id), { bivyKind: "delegation", createdAt: Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.delegation.id, delegation: structuredClone(entry.delegation) });
+    }
+    /** The delegation cards this session holds, latest state each. */
+    delegations(id) {
+        const byId = new Map();
+        for (const entry of this.entries(id))
+            if (entry.bivyKind === "delegation")
+                byId.set(entry.id, entry.delegation);
+        return [...byId.values()];
+    }
     appendAppReview(id, entry) {
         this.load(id);
         this.enqueue(id, `review:${entry.review.id}`, { bivyKind: "app-review", createdAt: entry.createdAt ?? Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.review.id, review: structuredClone(entry.review) });

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.8",
+  "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.",