@snowyroad/braid 0.78.0 → 0.79.1

package/dist/cli.js

@@ -848,6 +848,10 @@ var RelayClient = class {
   cardPin = /* @__PURE__ */ new Map();
   // no-downgrade pin: name → pinned jkt
   signWarned = false;
+  /** BL-228 task 3: activity-derived member-channel inventory (resume-cursor keys +
+   *  added - removed). Covers channels GET /channels' RLS may drop (e.g. a cross-org
+   *  guest channel) since this is fed by the same push frames the bridge already gets. */
+  memberChannels = /* @__PURE__ */ new Set();
   /** Fail-open signing: any problem -> unsigned post + one warning per process. */
   trySign(f) {
     if (!this.cfg.signMessage) return void 0;
@@ -1399,12 +1403,14 @@ var RelayClient = class {
         this.seenByChannel.delete(ch);
         this.caughtUp.delete(ch);
         this.lastGapResumeAt.delete(ch);
+        this.memberChannels.delete(ch);
         this.removedCb?.(ch);
         break;
       }
       case "added": {
         const ch = String(msg.channelId ?? "");
         if (!ch) break;
+        this.memberChannels.add(ch);
         this.addedCb?.(ch);
         break;
       }
@@ -1432,6 +1438,7 @@ var RelayClient = class {
         const resume = msg?.resume;
         if (resume && typeof resume === "object") {
           for (const [ch, seqRaw] of Object.entries(resume)) {
+            this.memberChannels.add(ch);
             const seq = Number(seqRaw);
             if (Number.isFinite(seq) && seq > this.cursorOf(ch)) this.cursors.set(ch, seq);
             const floor = this.cursorOf(ch);
@@ -1723,6 +1730,27 @@ var RelayClient = class {
   isScribeFor(channelId) {
     return this.selfScribeCache.get(channelId) ?? false;
   }
+  /** BL-228 task 3: this agent's member channels from the relay (`GET /channels`, RLS-scoped
+   *  to the caller). Best-effort like fetchRoster/fetchChannelName: never throws, [] on any
+   *  failure (HTTP error, network failure, malformed body). Lets the handoff controller offer
+   *  COLD channels (member but no live session) alongside the live-session set. */
+  async fetchMemberChannels() {
+    const r = await this.httpJson(`/channels`, { requestClass: "relay.channels.list" });
+    if (!r.ok) {
+      console.warn("[braid] member channels HTTP", r.status ?? r.category);
+      return [];
+    }
+    const body = r.json;
+    const arr = Array.isArray(body?.channels) ? body.channels : [];
+    return arr.filter((c) => typeof c?.id === "string" && c.id.length > 0).map((c) => ({ id: String(c.id), name: typeof c.name === "string" ? c.name : typeof c.title === "string" ? c.title : null }));
+  }
+  /** BL-228 task 3: synchronous in-memory member-channel set (resume-cursor keys at hello,
+   *  plus `added` minus `removed`), activity-derived from push frames — no network. Covers
+   *  a channel GET /channels' RLS may drop (e.g. a cross-org guest channel) that the bridge
+   *  still holds live membership of via the WS. Returns a snapshot copy, not a live view. */
+  knownMemberChannelIds() {
+    return new Set(this.memberChannels);
+  }
   /** Spread optional usage into the outbound body. Omits undefined fields so a no-usage
    *  call produces a body byte-identical to the pre-billing shape. */
   usageBody(u) {
@@ -2736,8 +2764,14 @@ ${fence(slackTaint ? "slack message" : "messages mentioning you", addressed)}
   hasPendingWork() {
     return this.pendingTurns.length > 0;
   }
+  /** Open the inbound hold WITHOUT stopping the client (BL-228: start-held warm
+   *  for on-demand handoff). Idempotent: an already-open hold is preserved so
+   *  nothing queued during the warm is lost. */
+  openHold() {
+    if (!this.holdQueue) this.holdQueue = [];
+  }
   async handoffPause() {
-    this.holdQueue = [];
+    if (!this.holdQueue) this.holdQueue = [];
     await this.session?.handoffPause?.();
   }
   async handoffResume() {
@@ -4276,33 +4310,18 @@ function resolveHandoffBinary(name, install) {
   handoffBinaryAbs.set(name, found);
   return found;
 }
+var HANDOFF_RESUME_SPECS = {
+  "claude-code": (sessionId, cwd) => ({ command: resolveHandoffBinary("claude", "Claude Code"), args: ["--resume", sessionId], cwd }),
+  codex: (sessionId, cwd) => ({ command: resolveHandoffBinary("codex", "the Codex CLI"), args: ["resume", sessionId], cwd }),
+  grok: (sessionId, cwd) => ({ command: resolveHandoffBinary("grok", "xAI's Grok CLI"), args: ["--resume", sessionId], cwd }),
+  opencode: (sessionId, cwd) => ({ command: resolveHandoffBinary("opencode", "the opencode CLI"), args: ["--session", sessionId], cwd })
+};
+function interactiveHandoffSupported(agent) {
+  return Object.prototype.hasOwnProperty.call(HANDOFF_RESUME_SPECS, agent);
+}
 function interactiveResumeSpecFor(agent, sessionId, cwd) {
-  switch (agent) {
-    case "claude-code":
-      return { command: resolveHandoffBinary("claude", "Claude Code"), args: ["--resume", sessionId], cwd };
-    case "codex":
-      return { command: resolveHandoffBinary("codex", "the Codex CLI"), args: ["resume", sessionId], cwd };
-    // grok (2026-07-02): 3-leg probe over `grok agent stdio` — session/new id ==
-    // `grok --resume <id>` id (cwd-keyed store; the bridge's canonical process.cwd()
-    // matches) AND session/load recalled the marker. NOTE: grok's session store is
-    // keyed by CANONICAL cwd; sessionId alone is not enough if cwd were a symlink.
-    case "grok":
-      return { command: resolveHandoffBinary("grok", "xAI's Grok CLI"), args: ["--resume", sessionId], cwd };
-    // opencode (2026-07-02): 3-leg probe over `opencode acp` — `ses_` id resumable by
-    // BOTH the TUI (`opencode --session <id>`) and headless `run --session` (marker
-    // recalled), AND session/load recalled the marker (shared store).
-    case "opencode":
-      return { command: resolveHandoffBinary("opencode", "the opencode CLI"), args: ["--session", sessionId], cwd };
-    // gemini: REFUTED for the handoff 2026-07-02 — native `--resume <uuid>` works, but
-    // ACP session/load returns success while restoring NO conversation context, so the
-    // hand-back leg would silently fork the thread. Do not enable until gemini-cli's
-    // ACP loadSession actually rehydrates context.
-    // cursor: REFUTED 2026-07-02 — `~/.cursor/acp-sessions/` and the native chat store
-    // are separate namespaces; `cursor-agent --resume <acp-id>` exits 0 and silently
-    // opens a FRESH thread (the exact failure mode this gate exists to prevent).
-    default:
-      return null;
-  }
+  const build = HANDOFF_RESUME_SPECS[agent];
+  return build ? build(sessionId, cwd) : null;
 }
 var defaultAcpClientFactory = (launch) => new AcpClient(launch);
 var MAX_CONSECUTIVE_RESTARTS = 3;
@@ -5808,7 +5827,7 @@ function startHandoffConversation(conn, ctl, initialChannelId, writeLine, log2)
     }
     channelId = id;
     phase = "offered";
-    writeLine({ handoff: "offer", channel: res.channel, provider: res.provider, pendingWork: res.pendingWork });
+    writeLine({ handoff: "offer", channel: res.channel, provider: res.provider, pendingWork: res.pendingWork, warm: res.warm });
   };
   conn.on("close", () => {
     const p = phase;
@@ -6247,6 +6266,7 @@ function renderEvent(ev) {
 // src/observe/socketHandoff.ts
 function makeSocketHandoffController(deps) {
   const specFor = deps.specFor ?? interactiveResumeSpecFor;
+  const handoffSupported = deps.handoffSupported ?? interactiveHandoffSupported;
   const scopedLaunchFn = deps.scopedLaunchFn ?? scopedLaunch;
   const log2 = deps.log ?? (() => {
   });
@@ -6262,57 +6282,91 @@ function makeSocketHandoffController(deps) {
     if (g.state === "orphaned") return { ok: false, error: "handoff_orphaned" };
     return null;
   };
-  const preflight = (channelId) => {
+  const classify = (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 (session) {
+      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, kind: "live", session, spec: raw };
+    }
+    if (deps.memberChannelIds().has(channelId) && deps.warmSession) {
+      if (!handoffSupported(deps.provider)) return { ok: false, error: "provider_unverified" };
+      return { ok: true, kind: "cold" };
     }
-    if (!raw) return { ok: false, error: "provider_unverified" };
-    return { ok: true, session, sessionId, spec: raw };
+    return { ok: false, error: "unknown_channel" };
   };
   return {
     listChannels() {
-      return [...deps.sessions.entries()].map(([id, s]) => ({
-        id,
-        label: label(id),
-        provider: deps.provider,
-        pendingWork: s.hasPendingWork?.() === true
-      }));
+      const rows = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const [id, s] of deps.sessions.entries()) {
+        seen.add(id);
+        rows.push({ id, label: label(id), provider: deps.provider, pendingWork: s.hasPendingWork?.() === true, live: true });
+      }
+      for (const id of deps.memberChannelIds()) {
+        if (seen.has(id)) continue;
+        rows.push({ id, label: label(id), provider: deps.provider, pendingWork: false, live: false });
+      }
+      return rows;
     },
     offer(channelId) {
-      const pre = preflight(channelId);
-      if (!pre.ok) return pre;
+      const c = classify(channelId);
+      if (!c.ok) return c;
       return {
         ok: true,
         channel: { id: channelId, label: label(channelId) },
         provider: deps.provider,
-        pendingWork: pre.session.hasPendingWork?.() === true
+        pendingWork: c.kind === "live" ? c.session.hasPendingWork?.() === true : false,
+        warm: c.kind === "cold"
       };
     },
     async begin(channelId) {
-      const pre = preflight(channelId);
-      if (!pre.ok) return pre;
+      const c = classify(channelId);
+      if (!c.ok) return c;
       if (!deps.gate.tryAcquire(channelId, "socket")) return gateBlocked() ?? { ok: false, error: "handoff_active" };
       let pauseAttempted = false;
+      let warmedCold = false;
+      let session;
       try {
-        const scoped = await scopedLaunchFn({ command: pre.spec.command, args: pre.spec.args, cwd: pre.spec.cwd }, { scope: deps.scope }, deps.provider);
+        let spec;
+        if (c.kind === "cold") {
+          session = await deps.warmSession(channelId);
+          warmedCold = true;
+          const sessionId = session.liveSessionId();
+          if (!sessionId) throw new Error("warm produced no resumable session");
+          const raw = specFor(deps.provider, sessionId, deps.cwdFor(channelId));
+          if (!raw) throw new Error("provider_unverified");
+          spec = raw;
+          log2(`[braid] handoff: warmed ${label(channelId)} on demand for a socket client`);
+        } else {
+          session = c.session;
+          spec = c.spec;
+        }
+        const scoped = await scopedLaunchFn({ command: spec.command, args: spec.args, cwd: spec.cwd }, { scope: deps.scope }, deps.provider);
         pauseAttempted = true;
-        await pre.session.handoffPause();
-        active = { channelId, session: pre.session };
+        await session.handoffPause();
+        active = { channelId, 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) {
+        if (pauseAttempted && session) {
+          try {
+            await session.handoffResume();
+          } catch {
+          }
+        } else if (warmedCold && session) {
           try {
-            await pre.session.handoffResume();
+            await session.handoffPause();
+            await session.handoffResume();
           } catch {
           }
         }
@@ -6513,11 +6567,20 @@ async function startBridge(cfg, relay, deps) {
       console.warn("[braid] self card publish on connect failed:", sanitizeForTty(String(e)));
     }
   }
-  async function ensureSession(channelId) {
+  async function ensureSession(channelId, opts) {
     const live = sessions.get(channelId);
-    if (live) return live;
+    if (live) {
+      if (opts?.startHeld) live.openHold();
+      return live;
+    }
     const inFlight = pending.get(channelId);
-    if (inFlight) return inFlight;
+    if (inFlight) {
+      if (opts?.startHeld) return inFlight.then((s) => {
+        s.openHold();
+        return s;
+      });
+      return inFlight;
+    }
     const p = (async () => {
       console.log(`[braid] Warming up #${sanitizeForTty(channelId)}\u2026`);
       void (async () => {
@@ -6608,6 +6671,7 @@ async function startBridge(cfg, relay, deps) {
         clearInterval(warmupHeartbeat);
         relay.sendActivity(channelId, "stop");
       }
+      if (opts?.startHeld) session.openHold();
       brokers.set(channelId, broker);
       sessions.set(channelId, session);
       pending.delete(channelId);
@@ -6703,6 +6767,18 @@ async function startBridge(cfg, relay, deps) {
       cwdFor: (id) => handoffCwdFor(cfg, id),
       scope: cfg.scope,
       gate: cs.handoffGate,
+      // BL-228 task 4/8: the in-memory member set RelayClient tracks (Task 3) is
+      // sufficient on its own — no union with sessions.keys() needed. listChannels()
+      // already unions deps.sessions (live) with deps.memberChannelIds() (Task 4), so
+      // any channel with a live session appears via the sessions map regardless of
+      // whether it's also in the member set; unioning sessions.keys() into
+      // memberChannelIds() here would be redundant belt-and-suspenders with no
+      // behavioral effect, not a real gap closed.
+      memberChannelIds: () => relay.knownMemberChannelIds(),
+      // BL-228 task 8: warm a cold member channel on demand — the router's own
+      // ensureSession, with startHeld so the socket handoff's begin() (task 5) never
+      // races a headless turn between warm-complete and handoffPause.
+      warmSession: (id) => ensureSession(id, { startHeld: true }),
       log: (line) => console.log(line)
     }) : void 0;
     try {
@@ -7770,7 +7846,7 @@ function validateSpec(line) {
 }
 async function pickChannel(channels, filter, promptFn, write) {
   if (channels.length === 0) {
-    write("[handoff] no channels are available to take over\n");
+    write("[handoff] this agent is not a member of any channel - no channels to take over yet.\n");
     return null;
   }
   if (filter && filter.trim() !== "") {
@@ -7797,7 +7873,8 @@ async function pickChannel(channels, filter, promptFn, write) {
 }
 function listChannels(write, channels) {
   channels.forEach((c, i) => {
-    write(`  [${i + 1}] ${sanitizeForTty(c.label)}${c.pendingWork ? " (working)" : ""}
+    const mark = c.live === false ? " (cold - will start a session)" : c.pendingWork ? " (working)" : "";
+    write(`  [${i + 1}] ${sanitizeForTty(c.label)}${mark}
 `);
   });
 }
@@ -7805,19 +7882,25 @@ function renderOffer(write, offer) {
   const channel = offer["channel"] ?? {};
   const label = sanitizeForTty(String(channel.label ?? ""));
   const pendingWork = offer["pendingWork"] === true;
+  const warm = offer["warm"] === 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."
-      ] : []
+      ...warm ? [
+        "NOTE: this channel has NO running session - taking control will START",
+        "one now, then drop you into it."
+      ] : [
+        "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."
+        ] : []
+      ]
     ])
   );
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@snowyroad/braid",
-  "version": "0.78.0",
+  "version": "0.79.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@snowyroad/braid",
-      "version": "0.78.0",
+      "version": "0.79.1",
       "license": "SEE LICENSE IN LICENSE.md",
       "dependencies": {
         "@agentclientprotocol/sdk": "0.25.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowyroad/braid",
-  "version": "0.78.0",
+  "version": "0.79.1",
   "description": "Braid: connect your own coding agent (Claude Code, Codex, Gemini, Grok) to a Braid channel and collaborate with other agents and humans.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "SnowyRoad",