@snowyroad/braid 0.76.1 → 0.77.0

package/dist/cli.js

@@ -66,7 +66,7 @@ import {
   validateReplacementToken,
   verifyCardSignature,
   wsToHttp
-} from "./chunk-IBUDDALN.js";
+} from "./chunk-SKUYOAV5.js";
 
 // src/health.ts
 var CEILING_STRIKES_TO_DEAD = 3;
@@ -5030,9 +5030,7 @@ import {
   writeFileSync as writeFileSync2,
   renameSync as renameSync2,
   chmodSync as chmodSync2,
-  readdirSync as readdirSync2,
-  statSync as statSync2,
-  existsSync as existsSync2
+  statSync as statSync2
 } from "fs";
 import { createHash } from "crypto";
 import { homedir as homedir3 } from "os";
@@ -5051,37 +5049,9 @@ function cardCacheReadPath(cfg) {
     ["card-cache", relayHostSegment(cfg.relayWsUrl), `${safe2(cfg.agentName)}.json`]
   );
 }
-function collectSkillMdPaths(root) {
-  const out = [];
-  if (!existsSync2(root)) return out;
-  function walk(dir) {
-    let entries;
-    try {
-      entries = readdirSync2(dir);
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const full = join4(dir, entry);
-      let st;
-      try {
-        st = statSync2(full);
-      } catch {
-        continue;
-      }
-      if (st.isDirectory()) {
-        walk(full);
-      } else if (entry === "SKILL.md") {
-        out.push(full);
-      }
-    }
-  }
-  walk(root);
-  return out;
-}
 function computeCapabilityFingerprint(cfg, skillsDir = process.env.BRAID_SKILLS_DIR ?? join4(homedir3(), ".claude", "skills"), pluginsDir = process.env.BRAID_PLUGINS_DIR ?? join4(homedir3(), ".claude", "plugins")) {
-  const paths1 = collectSkillMdPaths(skillsDir);
-  const paths2 = collectSkillMdPaths(pluginsDir);
+  const paths1 = collectSkillMd(skillsDir);
+  const paths2 = collectSkillMd(pluginsDir);
   const allPaths = [...paths1, ...paths2].sort();
   const pathEntries = allPaths.map((p) => {
     let mtimeMs = 0;
@@ -5143,6 +5113,67 @@ function saveCachedCard(cfg, fingerprint, unsignedCard) {
   }
 }
 
+// src/cardRefresh.ts
+var CARD_REFRESH_INTERVAL_MS = 3e5;
+var JITTER_RATIO = 0.2;
+function computeCardRefreshDelay(intervalMs, random) {
+  return Math.round(intervalMs * (1 - JITTER_RATIO + 2 * JITTER_RATIO * random()));
+}
+function startCardRefreshLoop(initialFingerprint, deps) {
+  const intervalMs = deps.intervalMs ?? CARD_REFRESH_INTERVAL_MS;
+  const random = deps.random ?? Math.random;
+  const log2 = deps.log ?? ((m) => console.warn(m));
+  let lastPushed = initialFingerprint;
+  let warnedEmptyFor = null;
+  let stopped = false;
+  let timer = null;
+  const schedule = () => {
+    if (stopped) return;
+    timer = setTimeout(() => {
+      void tick();
+    }, computeCardRefreshDelay(intervalMs, random));
+    timer.unref?.();
+  };
+  const tick = async () => {
+    try {
+      const fp = deps.computeFingerprint();
+      if (fp && fp !== lastPushed) {
+        const fields = deps.buildFromDisk();
+        if (!fields) {
+          if (warnedEmptyFor !== fp) {
+            warnedEmptyFor = fp;
+            log2("[braid] card refresh: skills changed but disk build yielded nothing \u2014 keeping the current card");
+          }
+        } else {
+          const unsigned = buildPartialCard(deps.agentName, fields);
+          let card = unsigned;
+          if (deps.signCard) card = await deps.signCard(card);
+          await deps.putAgentCard(card, "full");
+          deps.setCard(unsigned);
+          try {
+            deps.cacheSave(fp, unsigned);
+          } catch {
+          }
+          lastPushed = fp;
+          warnedEmptyFor = null;
+        }
+      }
+    } catch (e) {
+      log2(`[braid] card refresh: tick failed (will retry): ${String(e)}`);
+    } finally {
+      schedule();
+    }
+  };
+  schedule();
+  return () => {
+    stopped = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+}
+
 // src/shutdown.ts
 function restartHint(agentName) {
   const cmdName = isShellSafeName(agentName) ? agentName : "<agent-name>";
@@ -5217,11 +5248,11 @@ function installCrashGuard() {
 }
 
 // src/service/needsHumanMarker.ts
-import { mkdirSync as mkdirSync5, chmodSync as chmodSync4, writeFileSync as writeFileSync5, readFileSync as readFileSync6, existsSync as existsSync6, unlinkSync as unlinkSync2 } from "fs";
+import { mkdirSync as mkdirSync5, chmodSync as chmodSync4, writeFileSync as writeFileSync5, readFileSync as readFileSync6, existsSync as existsSync5, unlinkSync as unlinkSync2 } from "fs";
 import { join as join7 } from "path";
 
 // src/service/install.ts
-import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync4, readdirSync as readdirSync3, readFileSync as readFileSync5 } from "fs";
 import { join as join6 } from "path";
 
 // src/service/runtime.ts
@@ -5230,13 +5261,13 @@ import {
   mkdirSync as mkdirSync3,
   readFileSync as readFileSync4,
   writeFileSync as writeFileSync3,
-  readdirSync as readdirSync3,
+  readdirSync as readdirSync2,
   renameSync as renameSync3,
   rmSync,
   symlinkSync,
   readlinkSync,
   lstatSync as lstatSync2,
-  existsSync as existsSync3
+  existsSync as existsSync2
 } from "fs";
 import { execFileSync } from "child_process";
 import { createHash as createHash2 } from "crypto";
@@ -5250,18 +5281,18 @@ function defaultBraidDir() {
 function runtimeRootForRead(braidDir, platform) {
   const primary = join5(braidDir, "runtime");
   const markerOf = (root) => platform === "win32" ? currentTxtPath(root) : join5(root, "current");
-  if (existsSync3(markerOf(primary))) return primary;
+  if (existsSync2(markerOf(primary))) return primary;
   const override = process.env.BRAID_CONFIG_DIR?.trim();
   if (!override && braidDir === join5(homedir4(), ".braid")) {
     const legacy = join5(homedir4(), ".arp", "runtime");
-    if (existsSync3(markerOf(legacy))) return legacy;
+    if (existsSync2(markerOf(legacy))) return legacy;
   }
   return primary;
 }
 function runningPackageRoot() {
   let dir = dirname4(fileURLToPath(import.meta.url));
   for (let i = 0; i < 6; i++) {
-    if (existsSync3(join5(dir, "package.json")) && existsSync3(join5(dir, "dist"))) return dir;
+    if (existsSync2(join5(dir, "package.json")) && existsSync2(join5(dir, "dist"))) return dir;
     const parent = dirname4(dir);
     if (parent === dir) break;
     dir = parent;
@@ -5290,7 +5321,7 @@ function pinCurrentRuntime(opts = {}) {
   cpSync(join5(sourceDir, "dist"), join5(versionDir, "dist"), { recursive: true, force: true });
   cpSync(join5(sourceDir, "package.json"), join5(versionDir, "package.json"), { force: true });
   const shrinkwrapSrc = join5(sourceDir, "npm-shrinkwrap.json");
-  const hasShrinkwrap = existsSync3(shrinkwrapSrc);
+  const hasShrinkwrap = existsSync2(shrinkwrapSrc);
   if (hasShrinkwrap) {
     cpSync(shrinkwrapSrc, join5(versionDir, "npm-shrinkwrap.json"), { force: true });
   }
@@ -5318,7 +5349,7 @@ function populateNodeModules(sourceDir, versionDir, prodDeps, hasShrinkwrap, exe
   if (plainTree) {
     rmSync(dest, { recursive: true, force: true });
     cpSync(plainTree, dest, { recursive: true, force: true });
-    if (existsSync3(join5(dest, marker))) return "copy";
+    if (existsSync2(join5(dest, marker))) return "copy";
     rmSync(dest, { recursive: true, force: true });
   }
   return npmInstallProdDeps(versionDir, marker, hasShrinkwrap, exec);
@@ -5328,7 +5359,7 @@ function findCopyableNodeModules(sourceDir, marker) {
   for (let i = 0; i < 8; i++) {
     const nm = join5(dir, "node_modules");
     const markerPath = join5(nm, marker);
-    if (existsSync3(markerPath)) {
+    if (existsSync2(markerPath)) {
       if (!lstatSync2(markerPath).isSymbolicLink()) return nm;
       return null;
     }
@@ -5356,7 +5387,7 @@ function npmInstallProdDeps(versionDir, marker, hasShrinkwrap, exec) {
       `pinned runtime at ${versionDir} could not obtain its production dependencies (\`npm ${args[0]}\` failed \u2014 npm missing, no network, or shrinkwrap/platform mismatch?). Fix and re-run, or the service will crash-loop with ERR_MODULE_NOT_FOUND. Underlying error: ${detail}`
     );
   }
-  if (!existsSync3(join5(versionDir, "node_modules", marker))) {
+  if (!existsSync2(join5(versionDir, "node_modules", marker))) {
     throw new Error(
       `pinned runtime at ${versionDir} is missing dependency "${marker}" after \`npm ${args[0]}\`. Refusing to leave a runtime that will crash-loop with ERR_MODULE_NOT_FOUND.`
     );
@@ -5368,7 +5399,7 @@ function pruneOldVersions(runtimeRoot, currentVersion, previousVersion) {
   if (previousVersion && previousVersion !== currentVersion) keep.add(previousVersion);
   let entries;
   try {
-    entries = readdirSync3(runtimeRoot);
+    entries = readdirSync2(runtimeRoot);
   } catch {
     return;
   }
@@ -5445,7 +5476,7 @@ function installedClosureRecord(q = {}) {
 
 // src/service/socket.ts
 import * as net from "net";
-import { mkdirSync as mkdirSync4, chmodSync as chmodSync3, existsSync as existsSync4, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
+import { mkdirSync as mkdirSync4, chmodSync as chmodSync3, existsSync as existsSync3, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname5 } from "path";
 import { randomBytes as randomBytes2, timingSafeEqual } from "crypto";
 import { spawnSync as nodeSpawnSync2 } from "child_process";
@@ -5461,7 +5492,7 @@ function startControlSocket(opts) {
       chmodSync3(dir, 448);
     } catch {
     }
-    if (existsSync4(opts.sockPath)) {
+    if (existsSync3(opts.sockPath)) {
       if (!opts.ownsLock()) {
         return Promise.reject(
           new Error(
@@ -5532,13 +5563,13 @@ function startControlSocket(opts) {
           server.close(() => {
             if (!isWin32) {
               try {
-                if (existsSync4(opts.sockPath)) unlinkSync(opts.sockPath);
+                if (existsSync3(opts.sockPath)) unlinkSync(opts.sockPath);
               } catch {
               }
             }
             if (opts.tokenPath) {
               try {
-                if (existsSync4(opts.tokenPath)) unlinkSync(opts.tokenPath);
+                if (existsSync3(opts.tokenPath)) unlinkSync(opts.tokenPath);
               } catch {
               }
             }
@@ -5600,7 +5631,7 @@ async function probeStatus(sockPath, timeoutMs = 1500, token) {
 }
 function socketLive(sockPath, platform = process.platform, timeoutMs = 1e3) {
   if (platform !== "win32") {
-    return Promise.resolve(existsSync4(sockPath));
+    return Promise.resolve(existsSync3(sockPath));
   }
   return new Promise((resolve2) => {
     let settled = false;
@@ -5625,6 +5656,8 @@ function handleConnection(conn, opts, token, log2) {
   conn.setEncoding("utf8");
   let buf = "";
   let dispatched = false;
+  let onLine = null;
+  let ignoredBytes = 0;
   const writeLine = (obj) => {
     try {
       conn.write(JSON.stringify(obj) + "\n");
@@ -5637,19 +5670,7 @@ function handleConnection(conn, opts, token, log2) {
   };
   conn.on("error", () => {
   });
-  conn.on("data", (chunk) => {
-    if (dispatched) return;
-    buf += chunk;
-    const nl = buf.indexOf("\n");
-    if (nl < 0) {
-      if (buf.length > 64 * 1024) {
-        dispatched = true;
-        closeUnknown();
-      }
-      return;
-    }
-    dispatched = true;
-    const line = buf.slice(0, nl);
+  const dispatchFirst = (line) => {
     let req;
     try {
       req = JSON.parse(line);
@@ -5676,6 +5697,10 @@ function handleConnection(conn, opts, token, log2) {
         conn.end();
         return;
       }
+      if (opts.handoff) {
+        const g = opts.handoff.gateSnapshot();
+        if (g.state !== "idle") payload.handoff = g.state;
+      }
       writeLine(payload);
       conn.end();
       return;
@@ -5685,7 +5710,68 @@ function handleConnection(conn, opts, token, log2) {
       startAttachStream(conn, opts.hub, channelId);
       return;
     }
+    if (verb === "handoff") {
+      if (!opts.handoff) {
+        closeUnknown();
+        return;
+      }
+      const channelId = typeof req.channelId === "string" ? req.channelId : void 0;
+      onLine = startHandoffConversation(conn, opts.handoff, channelId, writeLine, log2);
+      return;
+    }
+    if (verb === "handoff.recover") {
+      if (!opts.handoff) {
+        closeUnknown();
+        return;
+      }
+      onLine = startRecoverConversation(conn, opts.handoff, writeLine, log2);
+      return;
+    }
     closeUnknown();
+  };
+  conn.on("data", (chunk) => {
+    buf += chunk;
+    if (dispatched && !onLine) {
+      ignoredBytes += chunk.length;
+      if (ignoredBytes > 64 * 1024) {
+        conn.destroy();
+        return;
+      }
+      buf = "";
+      return;
+    }
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl);
+      buf = buf.slice(nl + 1);
+      if (!dispatched) {
+        dispatched = true;
+        dispatchFirst(line);
+      } else if (onLine) {
+        let obj;
+        try {
+          obj = JSON.parse(line);
+        } catch {
+          conn.end();
+          return;
+        }
+        onLine(obj);
+      } else {
+        buf = "";
+        break;
+      }
+    }
+    if (!dispatched) {
+      if (buf.length > 64 * 1024) {
+        dispatched = true;
+        closeUnknown();
+      }
+    } else if (onLine) {
+      if (buf.length > 64 * 1024) {
+        conn.destroy();
+        return;
+      }
+    }
   });
 }
 function startAttachStream(conn, hub, channelId) {
@@ -5706,6 +5792,116 @@ function startAttachStream(conn, hub, channelId) {
   conn.on("error", cleanup);
   conn.on("end", cleanup);
 }
+function startHandoffConversation(conn, ctl, initialChannelId, writeLine, log2) {
+  let phase = "selecting";
+  let channelId = null;
+  const fail = (error) => {
+    phase = "closed";
+    writeLine({ error });
+    conn.end();
+  };
+  const doOffer = (id) => {
+    const res = ctl.offer(id);
+    if (!res.ok) {
+      fail(res.error);
+      return;
+    }
+    channelId = id;
+    phase = "offered";
+    writeLine({ handoff: "offer", channel: res.channel, provider: res.provider, pendingWork: res.pendingWork });
+  };
+  conn.on("close", () => {
+    const p = phase;
+    phase = "closed";
+    if (p === "spec_sent") {
+      ctl.orphan();
+      return;
+    }
+    if (p === "beginning") {
+      return;
+    }
+  });
+  if (initialChannelId !== void 0) doOffer(initialChannelId);
+  else writeLine({ handoff: "channels", channels: ctl.listChannels() });
+  return (obj) => {
+    const msg = obj;
+    if (phase === "selecting" && msg["handoff"] === "select" && typeof msg["channelId"] === "string") {
+      doOffer(msg["channelId"]);
+      return;
+    }
+    if (phase === "offered" && msg["handoff"] === "decline") {
+      phase = "closed";
+      conn.end();
+      return;
+    }
+    if (phase === "offered" && msg["handoff"] === "proceed" && channelId) {
+      phase = "beginning";
+      void ctl.begin(channelId).then((res) => {
+        if (phase === "closed") {
+          void ctl.abortAfterBegin();
+          return;
+        }
+        if (!res.ok) {
+          fail(res.error);
+          return;
+        }
+        phase = "spec_sent";
+        writeLine({ handoff: "spec", ...res.spec });
+      }).catch((e) => {
+        log2(`[braid] handoff begin failed: ${e.message}`);
+        if (phase !== "closed") fail("begin_failed");
+      });
+      return;
+    }
+    if (phase === "spec_sent" && msg["handoff"] === "done") {
+      phase = "resuming";
+      void ctl.complete().then(() => {
+        writeLine({ handoff: "resumed" });
+        phase = "closed";
+        conn.end();
+      }).catch((e) => {
+        log2(`[braid] handoff resume failed: ${e.message}`);
+        try {
+          conn.end();
+        } catch {
+        }
+      });
+      return;
+    }
+    fail("protocol_error");
+  };
+}
+function startRecoverConversation(conn, ctl, writeLine, log2) {
+  let offered = false;
+  const res = ctl.recoverOffer();
+  if (!res.ok) {
+    writeLine({ error: res.error });
+    conn.end();
+    return () => {
+    };
+  }
+  offered = true;
+  writeLine({ recover: "offer", channel: res.channel });
+  return (obj) => {
+    const msg = obj;
+    if (offered && msg["recover"] === "proceed") {
+      offered = false;
+      void ctl.recoverProceed().then(() => {
+        writeLine({ recover: "resumed" });
+        conn.end();
+      }).catch((e) => {
+        log2(`[braid] handoff resume failed: ${e.message}`);
+        try {
+          conn.end();
+        } catch {
+        }
+      });
+      return;
+    }
+    writeLine({ error: "protocol_error" });
+    conn.end();
+  };
+}
 
 // src/service/install.ts
 function validateServiceKey(name) {
@@ -5817,18 +6013,18 @@ function dedupe(names) {
 function isLegacyFamilyService(platform, name, homeDir) {
   if (platform === "darwin") {
     const dir = join6(homeDir, "Library", "LaunchAgents");
-    return !existsSync5(join6(dir, `com.snowyroad.braid.${name}.plist`)) && existsSync5(join6(dir, `dev.arp.bridge.${name}.plist`));
+    return !existsSync4(join6(dir, `com.snowyroad.braid.${name}.plist`)) && existsSync4(join6(dir, `dev.arp.bridge.${name}.plist`));
   }
   if (platform === "linux") {
     const dir = join6(homeDir, ".config", "systemd", "user");
-    return !existsSync5(join6(dir, `braid-${name}.service`)) && existsSync5(join6(dir, `arp-bridge-${name}.service`));
+    return !existsSync4(join6(dir, `braid-${name}.service`)) && existsSync4(join6(dir, `arp-bridge-${name}.service`));
   }
   return false;
 }
 function globNames(dir, pattern) {
   let entries = [];
   try {
-    entries = readdirSync4(dir);
+    entries = readdirSync3(dir);
   } catch {
     return [];
   }
@@ -5903,12 +6099,12 @@ function readNeedsHumanMarker(name, braidDir) {
 function clearNeedsHumanMarker(name, braidDir) {
   try {
     const p = needsHumanMarkerPath(name, braidDir);
-    if (existsSync6(p)) unlinkSync2(p);
+    if (existsSync5(p)) unlinkSync2(p);
   } catch {
   }
   try {
     const legacy = legacyTwinPath(braidDir, ["run", `${name}.needs-human`]);
-    if (legacy && existsSync6(legacy)) unlinkSync2(legacy);
+    if (legacy && existsSync5(legacy)) unlinkSync2(legacy);
   } catch {
   }
 }
@@ -6004,6 +6200,174 @@ var ObservationHub = class {
 import { decodeJwt as decodeJwt2 } from "jose";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import path3 from "path";
+
+// src/observe/render.ts
+function channelTag(channelId) {
+  return sanitizeForTty(channelId).slice(0, 8);
+}
+function renderEvent(ev) {
+  switch (ev.kind) {
+    case "activity": {
+      const a = ev.event;
+      const kind = a.kind ? sanitizeForTty(a.kind) : "tool";
+      const status = a.status ? sanitizeForTty(a.status) : "?";
+      const title = a.title ? sanitizeForTty(a.title) : "(untitled)";
+      const loc = a.locations && a.locations.length > 0 ? "  " + a.locations.map((l) => sanitizeForTty(l.path) + (l.line != null ? `:${l.line}` : "")).join(", ") : "";
+      return `
+  \xB7 [${kind}/${status}] ${title}${loc}`;
+    }
+    case "plan": {
+      const entries = ev.snapshot.entries;
+      const done = entries.filter((e) => e.status === "completed").length;
+      const total = entries.length;
+      const current = entries.find((e) => e.status === "in_progress");
+      const head = `
+  \u25B8 plan ${done}/${total}`;
+      return current ? `${head} - ${sanitizeForTty(current.content)}` : head;
+    }
+    case "message": {
+      const delta = sanitizeForTty(ev.delta);
+      return delta.length === 0 ? null : delta;
+    }
+    case "reply": {
+      const u = ev.usage;
+      const ctx = u?.contextUsed != null && u?.contextSize != null ? `  ctx ${u.contextUsed}/${u.contextSize}` : "";
+      const cost = u?.costUsed != null && u.costUsed > 0 ? `  cost ${u.costUsed}${u.costCurrency ? " " + sanitizeForTty(u.costCurrency) : ""}` : "";
+      const chars = sanitizeForTty(ev.text).length;
+      return `
+  \u2192 posted ${chars} chars${ctx}${cost}`;
+    }
+    default: {
+      const _exhaustive = ev;
+      return null;
+    }
+  }
+}
+
+// src/observe/socketHandoff.ts
+function makeSocketHandoffController(deps) {
+  const specFor = deps.specFor ?? interactiveResumeSpecFor;
+  const scopedLaunchFn = deps.scopedLaunchFn ?? scopedLaunch;
+  const log2 = deps.log ?? (() => {
+  });
+  let active = null;
+  const label = (channelId) => {
+    const name = deps.channelName(channelId);
+    const tag = channelTag(channelId);
+    return name ? `#${sanitizeForTty(name).slice(0, 40)} (${tag})` : `#${tag}`;
+  };
+  const gateBlocked = () => {
+    const g = deps.gate.snapshot();
+    if (g.state === "active") return { ok: false, error: "handoff_active" };
+    if (g.state === "orphaned") return { ok: false, error: "handoff_orphaned" };
+    return null;
+  };
+  const preflight = (channelId) => {
+    const blocked = gateBlocked();
+    if (blocked) return blocked;
+    const session = deps.sessions.get(channelId);
+    if (!session) return { ok: false, error: "unknown_channel" };
+    const sessionId = session.liveSessionId();
+    if (!sessionId) return { ok: false, error: "no_live_session" };
+    let raw;
+    try {
+      raw = specFor(deps.provider, sessionId, deps.cwdFor(channelId));
+    } catch (e) {
+      return { ok: false, error: sanitizeForTty(String(e?.message ?? e)) };
+    }
+    if (!raw) return { ok: false, error: "provider_unverified" };
+    return { ok: true, session, sessionId, spec: raw };
+  };
+  return {
+    listChannels() {
+      return [...deps.sessions.entries()].map(([id, s]) => ({
+        id,
+        label: label(id),
+        provider: deps.provider,
+        pendingWork: s.hasPendingWork?.() === true
+      }));
+    },
+    offer(channelId) {
+      const pre = preflight(channelId);
+      if (!pre.ok) return pre;
+      return {
+        ok: true,
+        channel: { id: channelId, label: label(channelId) },
+        provider: deps.provider,
+        pendingWork: pre.session.hasPendingWork?.() === true
+      };
+    },
+    async begin(channelId) {
+      const pre = preflight(channelId);
+      if (!pre.ok) return pre;
+      if (!deps.gate.tryAcquire(channelId, "socket")) return gateBlocked() ?? { ok: false, error: "handoff_active" };
+      let pauseAttempted = false;
+      try {
+        const scoped = await scopedLaunchFn({ command: pre.spec.command, args: pre.spec.args, cwd: pre.spec.cwd }, { scope: deps.scope }, deps.provider);
+        pauseAttempted = true;
+        await pre.session.handoffPause();
+        active = { channelId, session: pre.session };
+        log2(`[braid] handoff: paused ${label(channelId)} for a socket client`);
+        return { ok: true, spec: { command: scoped.command, args: scoped.args, cwd: scoped.cwd, env: scoped.env ?? null } };
+      } catch (e) {
+        if (pauseAttempted) {
+          try {
+            await pre.session.handoffResume();
+          } catch {
+          }
+        }
+        deps.gate.release();
+        return { ok: false, error: sanitizeForTty(String(e?.message ?? e)) };
+      }
+    },
+    async abortAfterBegin() {
+      if (!active) return;
+      const a = active;
+      active = null;
+      try {
+        await a.session.handoffResume();
+      } finally {
+        deps.gate.release();
+      }
+      log2(`[braid] handoff: client vanished before the spec was delivered \u2014 resumed ${label(a.channelId)}`);
+    },
+    async complete() {
+      if (!active) return;
+      const a = active;
+      active = null;
+      try {
+        await a.session.handoffResume();
+      } finally {
+        deps.gate.release();
+      }
+      log2(`[braid] handoff: owner handed back \u2014 resumed ${label(a.channelId)}`);
+    },
+    orphan() {
+      if (!active) return;
+      deps.gate.markOrphaned();
+      log2(`[braid] HANDOFF ORPHANED: the client vanished after receiving the session spec for ${label(active.channelId)}. The channel STAYS PAUSED (cannot prove the native session is closed). Recover with: braid handoff --recover  (or restart this bridge)`);
+    },
+    recoverOffer() {
+      const g = deps.gate.snapshot();
+      if (g.state !== "orphaned") return { ok: false, error: "not_orphaned" };
+      return { ok: true, channel: { id: g.channelId, label: label(g.channelId) } };
+    },
+    async recoverProceed() {
+      if (!active || deps.gate.snapshot().state !== "orphaned") return;
+      const a = active;
+      active = null;
+      try {
+        await a.session.handoffResume();
+      } finally {
+        deps.gate.release();
+      }
+      log2(`[braid] handoff: recovery attested \u2014 resumed ${label(a.channelId)}`);
+    },
+    gateSnapshot: () => deps.gate.snapshot()
+  };
+}
+
+// src/bridge.ts
 var REFRESH_MARGIN_MS = 24 * 60 * 60 * 1e3;
 var MIN_DELAY_MS = 60 * 1e3;
 var JOIN_HISTORY_LIMIT = 20;
@@ -6040,6 +6404,7 @@ async function startBridge(cfg, relay, deps) {
   const tornDownWhilePending = /* @__PURE__ */ new Set();
   let selfCardUnsigned = null;
   let cardRefreshTimer = null;
+  let stopCardContentRefresh = null;
   const WARMUP_LABEL_MS = 1e4;
   const WARMUP_HEARTBEAT_MS = 25e3;
   function scheduleCardRefresh(att) {
@@ -6128,6 +6493,19 @@ async function startBridge(cfg, relay, deps) {
             });
           }
         }
+        if (cfg.agent === "claude-code") {
+          stopCardContentRefresh?.();
+          stopCardContentRefresh = startCardRefreshLoop(fingerprint, {
+            computeFingerprint: () => computeCapabilityFingerprint(cfg),
+            buildFromDisk: () => buildCardFromDisk(),
+            setCard: onUnsigned,
+            cacheSave,
+            signCard: cfg.signCard,
+            putAgentCard: (c, scope) => relay.putAgentCard(c, scope),
+            agentName: cfg.agentName,
+            log: (m) => console.warn(sanitizeForTty(m))
+          });
+        }
       } else {
         await buildAndPublishSelfCard(cfg, relay, { converseLocal: async () => "" }, onUnsigned, onAtt);
       }
@@ -6318,6 +6696,15 @@ async function startBridge(cfg, relay, deps) {
       logsPath: cs.logsPath,
       http: snapshotHttpMetrics()
     });
+    const handoffCtl = cs.handoffGate ? makeSocketHandoffController({
+      sessions,
+      channelName: (id) => channelNames.get(id),
+      provider: cfg.agent,
+      cwdFor: (id) => handoffCwdFor(cfg, id),
+      scope: cfg.scope,
+      gate: cs.handoffGate,
+      log: (line) => console.log(line)
+    }) : void 0;
     try {
       const handle = await startControlSocket({
         sockPath: cs.sockPath,
@@ -6325,7 +6712,8 @@ async function startBridge(cfg, relay, deps) {
         getStatus: buildStatus,
         ownsLock: cs.ownsLock,
         log: (line) => console.log(line),
-        tokenPath: cs.tokenPath
+        tokenPath: cs.tokenPath,
+        ...handoffCtl ? { handoff: handoffCtl } : {}
       });
       controlSocketClose = handle.close;
     } catch (e) {
@@ -6520,6 +6908,10 @@ Commands:
                   service atomically.
   attach [name]   Watch a running service's live activity over the local control
                   socket (same machine only).
+  handoff [<agent>] [--channel <id-or-name>]
+                  take over the agent's live session on THIS terminal
+                  (quit the native UI to hand control back)
+  handoff --recover  resume a bridge left paused by a vanished handoff client
   version         Print the installed braid version (also --version, -v)
 
 Options for join/start (each also has an env twin; flag > env > file > default):
@@ -6540,6 +6932,7 @@ Options for join/start (each also has an env twin; flag > env > file > default):
   --allow-write <path>   widen sandbox write access (repeatable)
   --allow-read <path>    widen sandbox read access (repeatable)
   --allow-domain <host>  widen sandbox network egress (repeatable)
+  --no-socket        do not open the local control socket (on by default)
 At join, explicit choices persist to the saved agent; at start they apply to
 that run only.`;
 var SERVICE_VERBS = /* @__PURE__ */ new Set([
@@ -6631,6 +7024,30 @@ function parseCliArgs(argv) {
     const agent = argv[1] && !argv[1].startsWith("-") ? argv[1].trim() : void 0;
     return { kind: "attach", agent };
   }
+  if (first === "handoff") {
+    let agent;
+    let channel;
+    let recover = false;
+    const rest = argv.slice(1);
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === "--recover") {
+        recover = true;
+        continue;
+      }
+      if (a === "--channel") {
+        const v = rest[i + 1]?.trim();
+        if (v === void 0 || v === "" || v.startsWith("--")) return { kind: "usage", error: "Missing value for --channel" };
+        channel = v;
+        i++;
+        continue;
+      }
+      if (a.startsWith("-")) return { kind: "usage", error: `Unknown flag for handoff: ${a}` };
+      if (agent !== void 0) return { kind: "usage", error: "handoff takes at most one agent name" };
+      agent = a.trim();
+    }
+    return { kind: "handoff", agent, channel, recover };
+  }
   if (first === "version" || first === "--version" || first === "-v") {
     return { kind: "version" };
   }
@@ -6837,51 +7254,6 @@ function connectedBannerLines(opts) {
 // src/observe/attach.ts
 import * as readline from "readline";
 import * as net2 from "net";
-
-// src/observe/render.ts
-function channelTag(channelId) {
-  return sanitizeForTty(channelId).slice(0, 8);
-}
-function renderEvent(ev) {
-  switch (ev.kind) {
-    case "activity": {
-      const a = ev.event;
-      const kind = a.kind ? sanitizeForTty(a.kind) : "tool";
-      const status = a.status ? sanitizeForTty(a.status) : "?";
-      const title = a.title ? sanitizeForTty(a.title) : "(untitled)";
-      const loc = a.locations && a.locations.length > 0 ? "  " + a.locations.map((l) => sanitizeForTty(l.path) + (l.line != null ? `:${l.line}` : "")).join(", ") : "";
-      return `
-  \xB7 [${kind}/${status}] ${title}${loc}`;
-    }
-    case "plan": {
-      const entries = ev.snapshot.entries;
-      const done = entries.filter((e) => e.status === "completed").length;
-      const total = entries.length;
-      const current = entries.find((e) => e.status === "in_progress");
-      const head = `
-  \u25B8 plan ${done}/${total}`;
-      return current ? `${head} - ${sanitizeForTty(current.content)}` : head;
-    }
-    case "message": {
-      const delta = sanitizeForTty(ev.delta);
-      return delta.length === 0 ? null : delta;
-    }
-    case "reply": {
-      const u = ev.usage;
-      const ctx = u?.contextUsed != null && u?.contextSize != null ? `  ctx ${u.contextUsed}/${u.contextSize}` : "";
-      const cost = u?.costUsed != null && u.costUsed > 0 ? `  cost ${u.costUsed}${u.costCurrency ? " " + sanitizeForTty(u.costCurrency) : ""}` : "";
-      const chars = sanitizeForTty(ev.text).length;
-      return `
-  \u2192 posted ${chars} chars${ctx}${cost}`;
-    }
-    default: {
-      const _exhaustive = ev;
-      return null;
-    }
-  }
-}
-
-// src/observe/attach.ts
 var MAX_PICKER = 9;
 function createAttachController(deps) {
   const now = deps.now ?? (() => Date.now());
@@ -7208,6 +7580,355 @@ async function runHandoff(opts) {
   }
 }
 
+// src/service/handoffClient.ts
+import * as net3 from "net";
+import { createInterface } from "readline/promises";
+import { spawn as nodeSpawn2 } from "child_process";
+var YES = /^\s*(y|yes)\s*$/i;
+async function runHandoffCommand(opts) {
+  const env = opts.env ?? process.env;
+  const stdin = opts.stdin ?? process.stdin;
+  const stdout = opts.stdout ?? process.stdout;
+  const write = (s) => stdout.write(s);
+  const connectFn = opts.connectFn ?? ((p) => net3.createConnection(p));
+  const spawnFn = opts.spawnFn ?? nodeSpawn2;
+  const promptFn = opts.promptFn ?? ((q) => defaultPrompt(stdin, stdout, q));
+  if (!stdin.isTTY || !stdout.isTTY) {
+    write("[handoff] an interactive terminal is required (no --yes exists, by design)\n");
+    return 1;
+  }
+  const braidDir = configDir(env);
+  const names = listAgents(braidDir).map((e) => e.agent.agentName);
+  let name;
+  if (opts.agent && opts.agent.trim() !== "") {
+    const want = opts.agent.trim();
+    if (!names.includes(want)) {
+      const enrolled = names.length ? names.map(sanitizeForTty).join(", ") : "(none)";
+      write(`[handoff] no agent named "${sanitizeForTty(want)}" is enrolled. Enrolled: ${enrolled}
+`);
+      return 1;
+    }
+    name = want;
+  } else if (names.length === 1) {
+    name = names[0];
+  } else if (names.length === 0) {
+    write("[handoff] no agents are enrolled - run: braid join <code>\n");
+    return 1;
+  } else {
+    write(`[handoff] multiple agents enrolled (${names.map(sanitizeForTty).join(", ")}) - specify one: braid handoff <name>
+`);
+    return 1;
+  }
+  const safeName = sanitizeForTty(name);
+  const sockPath = await liveControlSocketPath(name, braidDir);
+  if (!await socketLive(sockPath)) {
+    write(`[handoff] ${safeName} isn't running - start it with: braid start ${safeName}
+`);
+    return 1;
+  }
+  const token = readControlToken(name, braidDir);
+  const socket = connectFn(sockPath);
+  const lc = lineClient(socket);
+  try {
+    return opts.recover ? await runRecover(lc, { write, promptFn, token, name: safeName }) : await runTakeover(lc, { write, promptFn, token, name: safeName, env, spawnFn, channel: opts.channel });
+  } catch (err) {
+    write(`[handoff] control socket error: ${sanitizeForTty(String(err?.message ?? err))}
+`);
+    return 1;
+  } finally {
+    try {
+      socket.destroy();
+    } catch {
+    }
+  }
+}
+async function runTakeover(lc, ctx) {
+  const { write, promptFn, token, name, env, spawnFn, channel } = ctx;
+  lc.send({ verb: "handoff", ...token ? { token } : {} });
+  const first = await lc.next();
+  if (typeof first["error"] === "string") return reportError(write, first["error"], name);
+  const channels = Array.isArray(first["channels"]) ? first["channels"] : [];
+  const picked = await pickChannel(channels, channel, promptFn, write);
+  if (!picked) return 1;
+  lc.send({ handoff: "select", channelId: picked.id });
+  const offer = await lc.next();
+  if (typeof offer["error"] === "string") return reportError(write, offer["error"], name);
+  renderOffer(write, offer);
+  const ans = await promptFn("take control now? [y/N] ");
+  if (!YES.test(ans)) {
+    lc.send({ handoff: "decline" });
+    await lc.drained(500);
+    write("[handoff] declined - the bridge stays in control\n");
+    return 0;
+  }
+  lc.send({ handoff: "proceed" });
+  const specLine = await lc.next();
+  if (typeof specLine["error"] === "string") return reportError(write, specLine["error"], name);
+  const sendDone = async () => {
+    lc.send({ handoff: "done" });
+    try {
+      await lc.next();
+    } catch {
+    }
+  };
+  const spec = validateSpec(specLine);
+  if (!spec.ok) {
+    await sendDone();
+    write(`[handoff] malformed session spec from the bridge: ${sanitizeForTty(spec.error)}
+`);
+    return 1;
+  }
+  const outcome = await new Promise((resolve2) => {
+    let settled = false;
+    const settle = (o) => {
+      if (!settled) {
+        settled = true;
+        resolve2(o);
+      }
+    };
+    try {
+      const child = spawnFn(spec.command, spec.args, {
+        stdio: "inherit",
+        cwd: spec.cwd,
+        env: buildAcpEnv(env, spec.env ?? void 0)
+      });
+      child.on("exit", () => settle({}));
+      child.on("error", (e) => settle({ error: e }));
+    } catch (e) {
+      settle({ error: e });
+    }
+  });
+  await sendDone();
+  if (outcome.error) {
+    write(`[handoff] failed to open the session: ${sanitizeForTty(String(outcome.error.message ?? outcome.error))}
+`);
+    return 1;
+  }
+  write("[handoff] control handed back - the bridge is driving again\n");
+  return 0;
+}
+function validateSpec(line) {
+  const command = line["command"];
+  if (typeof command !== "string" || command.trim() === "") return { ok: false, error: "command is not a non-empty string" };
+  const cwd = line["cwd"];
+  if (typeof cwd !== "string") return { ok: false, error: "cwd is not a string" };
+  const args = line["args"];
+  if (!Array.isArray(args) || args.some((a) => typeof a !== "string")) return { ok: false, error: "args is not an array of strings" };
+  const env = line["env"] ?? null;
+  if (env !== null) {
+    if (typeof env !== "object" || Array.isArray(env) || Object.values(env).some((v) => typeof v !== "string")) {
+      return { ok: false, error: "env is not a string-valued record or null" };
+    }
+  }
+  return { ok: true, command, args, cwd, env };
+}
+async function pickChannel(channels, filter, promptFn, write) {
+  if (channels.length === 0) {
+    write("[handoff] no channels are available to take over\n");
+    return null;
+  }
+  if (filter && filter.trim() !== "") {
+    const f = filter.trim();
+    const exact = channels.filter((c) => c.id === f);
+    if (exact.length === 1) return exact[0];
+    const matches = channels.filter((c) => c.id.startsWith(f) || c.label.includes(f));
+    if (matches.length === 1) return matches[0];
+    write(`[handoff] "${sanitizeForTty(f)}" ${matches.length === 0 ? "matched no channel" : `is ambiguous (${matches.length} channels)`} - available:
+`);
+    listChannels(write, channels);
+    return null;
+  }
+  if (channels.length === 1) return channels[0];
+  write("[handoff] which channel do you want to take over?\n");
+  listChannels(write, channels);
+  const ans = (await promptFn(`select a channel [1-${channels.length}]: `)).trim();
+  const idx = Number.parseInt(ans, 10);
+  if (!Number.isInteger(idx) || idx < 1 || idx > channels.length) {
+    write("[handoff] not a valid selection\n");
+    return null;
+  }
+  return channels[idx - 1];
+}
+function listChannels(write, channels) {
+  channels.forEach((c, i) => {
+    write(`  [${i + 1}] ${sanitizeForTty(c.label)}${c.pendingWork ? " (working)" : ""}
+`);
+  });
+}
+function renderOffer(write, offer) {
+  const channel = offer["channel"] ?? {};
+  const label = sanitizeForTty(String(channel.label ?? ""));
+  const pendingWork = offer["pendingWork"] === true;
+  write(
+    banner("handoff", `TAKING CONTROL of ${label}`, [
+      "pausing the bridge and opening the agent's REAL interactive session",
+      "on this terminal. Quit it (Ctrl-C or /exit) to hand control back.",
+      "",
+      "WARNING: changes you make inside PERSIST after you leave -",
+      "switching model or mode (or compacting/clearing) carries over into",
+      "how this agent serves the channel afterwards.",
+      ...pendingWork ? [
+        "",
+        "NOTE: a reply is being worked on right now; taking control interrupts",
+        "it. The interrupted message will re-run when you hand back."
+      ] : []
+    ])
+  );
+}
+async function runRecover(lc, ctx) {
+  const { write, promptFn, token, name } = ctx;
+  lc.send({ verb: "handoff.recover", ...token ? { token } : {} });
+  const first = await lc.next();
+  if (typeof first["error"] === "string") {
+    if (first["error"] === "not_orphaned") {
+      write("[handoff] nothing to recover - no orphaned handoff\n");
+      return 0;
+    }
+    return reportError(write, first["error"], name);
+  }
+  const channel = first["channel"] ?? {};
+  write(`[handoff] a previous handoff of ${sanitizeForTty(String(channel.label ?? ""))} was orphaned and the channel is PAUSED.
+`);
+  const ans = await promptFn("Is the interactive session fully closed? [y/N] ");
+  if (!YES.test(ans)) {
+    write("[handoff] recovery aborted - nothing changed\n");
+    return 0;
+  }
+  lc.send({ recover: "proceed" });
+  try {
+    await lc.next();
+  } catch {
+  }
+  write("[handoff] recovery confirmed - the bridge is driving again\n");
+  return 0;
+}
+function reportError(write, code, agent) {
+  write(`[handoff] ${codeToMessage(code, agent)}
+`);
+  return 1;
+}
+function codeToMessage(code, agent) {
+  switch (code) {
+    case "handoff_active":
+      return "another handoff is already in progress";
+    case "handoff_orphaned":
+      return `a previous handoff was orphaned - run: braid handoff ${agent} --recover`;
+    case "provider_unverified":
+      return "not available for this provider yet (verified for Claude Code, Codex, Grok, and opencode so far)";
+    case "no_live_session":
+      return "no live session yet for that channel";
+    case "unknown_channel":
+      return "that channel has no active session";
+    default:
+      return sanitizeForTty(code);
+  }
+}
+function lineClient(sock) {
+  sock.setEncoding("utf8");
+  let buf = "";
+  const queue = [];
+  let closed = false;
+  let sockErr = null;
+  let wake = null;
+  const bump = () => {
+    const w = wake;
+    wake = null;
+    w?.();
+  };
+  sock.on("data", (d) => {
+    buf += d;
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      queue.push(buf.slice(0, nl));
+      buf = buf.slice(nl + 1);
+    }
+    bump();
+  });
+  let onClose = null;
+  sock.on("close", () => {
+    closed = true;
+    onClose?.();
+    bump();
+  });
+  sock.on("error", (e) => {
+    sockErr = e;
+    bump();
+  });
+  return {
+    send(obj) {
+      try {
+        sock.write(JSON.stringify(obj) + "\n");
+      } catch {
+      }
+    },
+    drained(timeoutMs) {
+      if (closed) return Promise.resolve();
+      return new Promise((resolve2) => {
+        const t = setTimeout(() => {
+          onClose = null;
+          resolve2();
+        }, timeoutMs);
+        if (typeof t.unref === "function") t.unref();
+        onClose = () => {
+          clearTimeout(t);
+          resolve2();
+        };
+      });
+    },
+    async next() {
+      for (; ; ) {
+        if (queue.length > 0) {
+          const line = queue.shift();
+          try {
+            return JSON.parse(line);
+          } catch {
+            throw new Error("control socket sent a malformed line");
+          }
+        }
+        if (sockErr) throw sockErr;
+        if (closed) throw new Error("control socket closed before a response");
+        await new Promise((r) => {
+          wake = r;
+        });
+      }
+    }
+  };
+}
+async function defaultPrompt(stdin, stdout, question) {
+  const rl = createInterface({
+    input: stdin,
+    output: stdout
+  });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+// src/observe/handoffGate.ts
+var HandoffGate = class {
+  st = { state: "idle" };
+  /** Enter the critical section. False = another handoff is active or orphaned. */
+  tryAcquire(channelId, via) {
+    if (this.st.state !== "idle") return false;
+    this.st = { state: "active", channelId, via };
+    return true;
+  }
+  /** Leave the critical section (normal completion, pre-spec abort, or attested recovery). */
+  release() {
+    this.st = { state: "idle" };
+  }
+  /** Socket client vanished after the spec was sent: fail closed, stay paused. */
+  markOrphaned() {
+    if (this.st.state !== "active") return;
+    this.st = { state: "orphaned", channelId: this.st.channelId };
+  }
+  snapshot() {
+    return { ...this.st };
+  }
+};
+
 // src/scope/gate.ts
 function scopeStartupDecision(avail, toolMode, scopeOff, installerAvailable, platform = process.platform) {
   if (scopeOff) {
@@ -7269,8 +7990,8 @@ async function maybeOfferSandboxInstall(deps) {
 }
 function readlinePromptYesNo(input, output) {
   return import("readline").then(
-    ({ createInterface }) => new Promise((resolve2) => {
-      const rl = createInterface({ input, output });
+    ({ createInterface: createInterface2 }) => new Promise((resolve2) => {
+      const rl = createInterface2({ input, output });
       rl.once("line", (line) => {
         resolve2(line.trim().toLowerCase() === "y");
         rl.close();
@@ -7613,7 +8334,7 @@ import { execFile } from "child_process";
 import { homedir as homedir6 } from "os";
 
 // src/service/manager.ts
-import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync7, rmSync as rmSync2, existsSync as existsSync7 } from "fs";
+import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync7, rmSync as rmSync2, existsSync as existsSync6 } from "fs";
 import { join as join9 } from "path";
 
 // src/service/templates.ts
@@ -7785,7 +8506,7 @@ function schtasksXml(p) {
 }
 
 // src/service/win32.ts
-import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync6, readdirSync as readdirSync5, readFileSync as readFileSync7, unlinkSync as unlinkSync3 } from "fs";
+import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync6, readdirSync as readdirSync4, readFileSync as readFileSync7, unlinkSync as unlinkSync3 } from "fs";
 import { join as join8 } from "path";
 function win32LogDir(homeDir) {
   return join8(homeDir, "AppData", "Local", "braid", "logs");
@@ -7811,7 +8532,7 @@ function win32Manager(ctx) {
     const hostDirs = [];
     for (const agentsDir of agentDirs) {
       try {
-        for (const host of readdirSync5(agentsDir)) hostDirs.push(join8(agentsDir, host));
+        for (const host of readdirSync4(agentsDir)) hostDirs.push(join8(agentsDir, host));
       } catch {
       }
     }
@@ -7944,7 +8665,7 @@ function darwinManager(ctx) {
   const legacyLogDir = join9(ctx.homeDir, "Library", "Logs", "arp-bridge");
   const plistPath = (name) => join9(launchAgentsDir, `${launchdLabel(name)}.plist`);
   const legacyPlistPath = (name) => join9(launchAgentsDir, `${legacyLaunchdLabel(name)}.plist`);
-  const legacyInstalled = (name) => !existsSync7(plistPath(name)) && existsSync7(legacyPlistPath(name));
+  const legacyInstalled = (name) => !existsSync6(plistPath(name)) && existsSync6(legacyPlistPath(name));
   const domainTarget = `gui/${ctx.uid}`;
   const serviceTarget = (name) => `${domainTarget}/${legacyInstalled(name) ? legacyLaunchdLabel(name) : launchdLabel(name)}`;
   const write = (name) => {
@@ -7981,7 +8702,7 @@ function darwinManager(ctx) {
       }
     },
     async start(name) {
-      if (!existsSync7(plistPath(name)) && !existsSync7(legacyPlistPath(name))) write(name);
+      if (!existsSync6(plistPath(name)) && !existsSync6(legacyPlistPath(name))) write(name);
       await ctx.exec("launchctl", [
         "bootstrap",
         domainTarget,
@@ -7995,7 +8716,7 @@ function darwinManager(ctx) {
       await ctx.exec("launchctl", ["kickstart", "-k", serviceTarget(name)]);
     },
     async status(name) {
-      const installed = existsSync7(plistPath(name)) || existsSync7(legacyPlistPath(name));
+      const installed = existsSync6(plistPath(name)) || existsSync6(legacyPlistPath(name));
       if (!installed) return { installed: false, loaded: false, running: false };
       const res = await ctx.exec("launchctl", ["print", serviceTarget(name)]);
       const loaded = res.code === 0;
@@ -8004,7 +8725,7 @@ function darwinManager(ctx) {
         installed,
         loaded,
         running,
-        staleNodePath: !existsSync7(ctx.nodePath)
+        staleNodePath: !existsSync6(ctx.nodePath)
       };
     },
     logsPath(name) {
@@ -8018,7 +8739,7 @@ function linuxManager(ctx) {
   const legacyUnitName = (name) => `arp-bridge-${name}.service`;
   const newUnitPath = (name) => join9(unitDir, newUnitName(name));
   const legacyUnitPath = (name) => join9(unitDir, legacyUnitName(name));
-  const legacyInstalled = (name) => !existsSync7(newUnitPath(name)) && existsSync7(legacyUnitPath(name));
+  const legacyInstalled = (name) => !existsSync6(newUnitPath(name)) && existsSync6(legacyUnitPath(name));
   const unitName = (name) => legacyInstalled(name) ? legacyUnitName(name) : newUnitName(name);
   const unitPath = (name) => legacyInstalled(name) ? legacyUnitPath(name) : newUnitPath(name);
   const sc = (...args) => ctx.exec("systemctl", ["--user", ...args]);
@@ -8035,7 +8756,7 @@ function linuxManager(ctx) {
     async install(name) {
       write(name);
       await sc("daemon-reload");
-      if (existsSync7(legacyUnitPath(name))) {
+      if (existsSync6(legacyUnitPath(name))) {
         await sc("disable", "--now", legacyUnitName(name));
         try {
           rmSync2(legacyUnitPath(name), { force: true });
@@ -8047,7 +8768,7 @@ function linuxManager(ctx) {
     },
     async uninstall(name) {
       await sc("disable", "--now", newUnitName(name));
-      if (existsSync7(legacyUnitPath(name))) {
+      if (existsSync6(legacyUnitPath(name))) {
         await sc("disable", "--now", legacyUnitName(name));
       }
       try {
@@ -8061,7 +8782,7 @@ function linuxManager(ctx) {
       await sc("daemon-reload");
     },
     async start(name) {
-      if (!existsSync7(unitPath(name))) {
+      if (!existsSync6(unitPath(name))) {
         write(name);
         await sc("daemon-reload");
       }
@@ -8074,7 +8795,7 @@ function linuxManager(ctx) {
       await sc("restart", unitName(name));
     },
     async status(name) {
-      const installed = existsSync7(unitPath(name));
+      const installed = existsSync6(unitPath(name));
       if (!installed) return { installed: false, loaded: false, running: false };
       const active = await sc("is-active", unitName(name));
       const enabled = await sc("is-enabled", unitName(name));
@@ -8084,7 +8805,7 @@ function linuxManager(ctx) {
         installed,
         loaded,
         running,
-        staleNodePath: !existsSync7(ctx.nodePath)
+        staleNodePath: !existsSync6(ctx.nodePath)
       };
     },
     logsPath(name) {
@@ -8303,7 +9024,7 @@ import { dirname as dirname6, join as join10 } from "path";
 
 // src/service/logRotation.ts
 import {
-  existsSync as existsSync8,
+  existsSync as existsSync7,
   statSync as statSync3,
   renameSync as renameSync4,
   rmSync as rmSync3,
@@ -8317,7 +9038,7 @@ function rotateLogFileIfNeeded(logPath, opts = {}) {
   const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
   const keepCount = opts.keepCount ?? DEFAULT_KEEP_COUNT;
   try {
-    if (!existsSync8(logPath)) return;
+    if (!existsSync7(logPath)) return;
     let size;
     try {
       size = statSync3(logPath).size;
@@ -8327,12 +9048,12 @@ function rotateLogFileIfNeeded(logPath, opts = {}) {
     if (size <= maxBytes) return;
     const gz = (n) => `${logPath}.${n}.gz`;
     try {
-      if (existsSync8(gz(keepCount))) rmSync3(gz(keepCount), { force: true });
+      if (existsSync7(gz(keepCount))) rmSync3(gz(keepCount), { force: true });
     } catch {
     }
     for (let n = keepCount - 1; n >= 1; n--) {
       try {
-        if (existsSync8(gz(n))) renameSync4(gz(n), gz(n + 1));
+        if (existsSync7(gz(n))) renameSync4(gz(n), gz(n + 1));
       } catch {
       }
     }
@@ -8688,6 +9409,13 @@ async function main() {
   if (invocation.kind === "attach") {
     process.exit(await runAttach(invocation.agent));
   }
+  if (invocation.kind === "handoff") {
+    process.exit(await runHandoffCommand({
+      agent: invocation.agent,
+      channel: invocation.channel,
+      recover: invocation.recover
+    }));
+  }
   const cfg = await resolveConfig(invocation.argv, process.env);
   resolvedAgentName = cfg.agentName ?? "";
   {
@@ -8767,8 +9495,8 @@ async function main() {
       // operator types at, so passing it to rl.question (rather than pre-writing it)
       // means readline keeps it on screen instead of clearing it (BL-178).
       ask: async (prompt) => {
-        const { createInterface } = await import("readline/promises");
-        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        const { createInterface: createInterface2 } = await import("readline/promises");
+        const rl = createInterface2({ input: process.stdin, output: process.stderr });
         let cancelled = false;
         rl.on("SIGINT", () => {
           cancelled = true;
@@ -8879,7 +9607,8 @@ async function main() {
   console.log("[braid] connecting to the relay...");
   const keysLive = attachEligible(process.stdin, process.stdout, process.env);
   const serviceEligible = process.env.BRAID_SERVICE !== "1" && !!cfg.agentName;
-  const wantSocket = process.env.BRAID_SERVICE === "1" || invocation.argv.includes("--socket");
+  const wantSocket = process.env.BRAID_SERVICE === "1" || !invocation.argv.includes("--no-socket");
+  const handoffGate = new HandoffGate();
   let controlSocketCfg;
   if (wantSocket && cfg.agentName) {
     const braidDir = configDir(process.env);
@@ -8894,7 +9623,8 @@ async function main() {
       ownsLock: () => true,
       logsPath,
       blockedEndpoints: blockedEndpointHosts,
-      tokenPath: controlTokenPath(cfg.agentName, braidDir)
+      tokenPath: controlTokenPath(cfg.agentName, braidDir),
+      handoffGate
     };
   }
   const bridge = await createAndStartBridge(cfg, {
@@ -8955,7 +9685,17 @@ async function main() {
         out.write("\n[handoff] that session is no longer active\n");
         return;
       }
-      await runHandoff({ channelId, provider: cfg.agent, session, cwd: handoffCwdFor(cfg, channelId), out, channelLabel: channelLabel(channelId), scope: cfg.scope });
+      if (!handoffGate.tryAcquire(channelId, "terminal")) {
+        const g = handoffGate.snapshot();
+        out.write(g.state === "orphaned" ? `
+[handoff] a previous handoff was orphaned - run: braid handoff ${cfg.agentName ?? ""} --recover`.trimEnd() + "\n" : "\n[handoff] another handoff is already in progress\n");
+        return;
+      }
+      try {
+        await runHandoff({ channelId, provider: cfg.agent, session, cwd: handoffCwdFor(cfg, channelId), out, channelLabel: channelLabel(channelId), scope: cfg.scope });
+      } finally {
+        handoffGate.release();
+      }
     }
   });
 }