channels.tools 0.1.0

package/src/connection.test.ts

@@ -0,0 +1,299 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { ConnectionManager } from "./connection.ts";
+import type { ChannelEvent } from "./envelope.ts";
+
+const FAKE = join(import.meta.dirname, "..", "test", "fake-channel-server.ts");
+
+function manager(overrides: { retryBaseMs?: number; retryMaxMs?: number } = {}) {
+  const events: ChannelEvent[] = [];
+  const statuses: string[] = [];
+  const logs: string[] = [];
+  const mgr = new ConnectionManager({
+    onEvent: (e) => events.push(e),
+    onStatus: (s) => statuses.push(s),
+    log: (m) => logs.push(m),
+    ...overrides,
+  });
+  return { mgr, events, statuses, logs };
+}
+
+test("connects a server declaring the channel capability and captures instructions and tools", async () => {
+  const { mgr } = manager();
+  const conns = await mgr.connectAll({ fake: { command: process.execPath, args: [FAKE] } });
+  assert.equal(conns.length, 1);
+  assert.equal(conns[0].name, "fake");
+  assert.equal(conns[0].instructions, "FAKE CORE INSTRUCTIONS");
+  assert.equal(conns[0].tools.length, 1);
+  assert.equal(conns[0].tools[0].name, "fake_status");
+  await mgr.closeAll();
+});
+
+test("rejects a server that does not declare the capability", async () => {
+  const { mgr, logs } = manager();
+  const conns = await mgr.connectAll({
+    nope: { command: process.execPath, args: [FAKE], env: { FAKE_NO_CAPABILITY: "1" } },
+  });
+  assert.equal(conns.length, 0);
+  assert.ok(logs.some((l) => /capability/i.test(l)), `expected a capability log, got: ${logs.join(" | ")}`);
+  // Capability rejection is a permanent incompatibility, not a transient
+  // fault — it must never be retried.
+  assert.ok(!logs.some((l) => /retry|retrying/i.test(l)), `expected no retry log, got: ${logs.join(" | ")}`);
+  await mgr.closeAll();
+});
+
+test("a missing binary is reported, not thrown, and is retried", async () => {
+  const { mgr, logs } = manager();
+  const conns = await mgr.connectAll({ ghost: { command: "definitely-not-a-real-binary-xyz" } });
+  assert.equal(conns.length, 0);
+  assert.ok(logs.some((l) => /ghost/.test(l)));
+  assert.ok(logs.some((l) => /retry|retrying/i.test(l)), `expected a retry log, got: ${logs.join(" | ")}`);
+  await mgr.closeAll();
+});
+
+test("an inbound channel notification reaches onEvent tagged with its source", async () => {
+  const { mgr, events } = manager();
+  await mgr.connectAll({
+    fake: { command: process.execPath, args: [FAKE], env: { FAKE_PUSH_AFTER_MS: "50" } },
+  });
+  await new Promise((r) => setTimeout(r, 400));
+  assert.equal(events.length, 1);
+  assert.equal(events[0].source, "fake");
+  assert.match(events[0].content, /something happened/);
+  assert.equal(events[0].meta.intent, "fyi");
+  await mgr.closeAll();
+});
+
+test("notifications other than the channel notification are ignored", async () => {
+  const { mgr, events } = manager();
+  const conns = await mgr.connectAll({ fake: { command: process.execPath, args: [FAKE] } });
+  conns[0].client.notify("notifications/unrelated", { x: 1 });
+  await new Promise((r) => setTimeout(r, 100));
+  assert.equal(events.length, 0);
+  await mgr.closeAll();
+});
+
+test("closeAll is idempotent and leaves no connections", async () => {
+  const { mgr } = manager();
+  await mgr.connectAll({ fake: { command: process.execPath, args: [FAKE] } });
+  await mgr.closeAll();
+  await mgr.closeAll();
+  assert.equal(mgr.connections().length, 0);
+});
+
+test("connectAll after a previous connect replaces rather than duplicates", async () => {
+  const { mgr } = manager();
+  await mgr.connectAll({ fake: { command: process.execPath, args: [FAKE] } });
+  await mgr.connectAll({ fake: { command: process.execPath, args: [FAKE] } });
+  assert.equal(mgr.connections().length, 1);
+  await mgr.closeAll();
+});
+
+test("a child that dies mid-handshake is not accepted, reports unhealthy, is retried, and connectAll returns promptly", async () => {
+  const { mgr, logs, statuses } = manager();
+  const start = Date.now();
+  // This process spawns successfully but exits immediately without ever
+  // reading stdin or writing a response — a deterministic way to die before
+  // `initialize` can complete, without racing a timer against a fixture.
+  const conns = await mgr.connectAll({
+    dead: { command: process.execPath, args: ["-e", "process.exit(1)"] },
+  });
+  const elapsed = Date.now() - start;
+  assert.equal(conns.length, 0);
+  assert.equal(mgr.connections().length, 0);
+  assert.ok(logs.some((l) => /handshake/i.test(l)), `expected a mid-handshake log, got: ${logs.join(" | ")}`);
+  assert.ok(logs.some((l) => /retry|retrying/i.test(l)), `expected a retry log, got: ${logs.join(" | ")}`);
+  assert.ok(statuses.some((s) => /DEGRADED/.test(s)), `expected a DEGRADED status, got: ${statuses.join(" | ")}`);
+  assert.ok(elapsed < 5000, `connectAll took ${elapsed}ms — it must not stall on the JSON-RPC 30s timeout`);
+  await mgr.closeAll();
+});
+
+test("a channel that dies after connecting is marked degraded and a retry is scheduled", async () => {
+  const { mgr, logs, statuses } = manager();
+  const conns = await mgr.connectAll({
+    fake: { command: process.execPath, args: [FAKE], env: { FAKE_EXIT_AFTER_MS: "50" } },
+  });
+  assert.equal(conns.length, 1);
+  await new Promise((r) => setTimeout(r, 300));
+  assert.equal(mgr.connections().length, 0);
+  assert.ok(statuses.some((s) => /DEGRADED/.test(s)), `expected a DEGRADED status, got: ${statuses.join(" | ")}`);
+  assert.ok(logs.some((l) => /retrying/i.test(l)), `expected a retry log, got: ${logs.join(" | ")}`);
+  await mgr.closeAll();
+});
+
+test("closeAll while a connect is mid-handshake kills the pending child promptly and it never becomes live", async () => {
+  const { mgr } = manager();
+  // Never responds to initialize and never exits on its own — the only way
+  // this settles is if closeAll() actively kills it.
+  const connectPromise = mgr.connectAll({
+    hang: { command: process.execPath, args: ["-e", "setTimeout(() => {}, 60000)"] },
+  });
+  await new Promise((r) => setTimeout(r, 150));
+  const start = Date.now();
+  await mgr.closeAll();
+  const conns = await connectPromise;
+  const elapsed = Date.now() - start;
+  assert.equal(conns.length, 0);
+  assert.equal(mgr.connections().length, 0);
+  assert.ok(elapsed < 5000, `closeAll + settle took ${elapsed}ms — the pending child must be killed, not waited out`);
+});
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+test("closeAll kills a child that ignores SIGTERM, and it exits promptly", async () => {
+  const { mgr, logs } = manager();
+  // A real muster channel process ignores SIGTERM outright — only SIGKILL
+  // ends it. Without the escalation in killChild(), this child (and the
+  // real one) survives closeAll() as an orphan, holding its stdio pipes
+  // open and hanging the process that spawned it.
+  await mgr.connectAll({
+    stubborn: { command: process.execPath, args: [FAKE], env: { FAKE_IGNORE_SIGTERM: "1" } },
+  });
+  const pidLine = logs.find((l) => l.includes("PID:"));
+  assert.ok(pidLine, `expected the fake server to report its pid, got: ${logs.join(" | ")}`);
+  const pid = Number(pidLine.split("PID:")[1]);
+  assert.ok(isAlive(pid), `expected pid ${pid} to be alive before closeAll()`);
+
+  const start = Date.now();
+  await mgr.closeAll();
+  while (isAlive(pid)) {
+    assert.ok(Date.now() - start < 2000, `pid ${pid} is still alive ${Date.now() - start}ms after closeAll()`);
+    await new Promise((r) => setTimeout(r, 20));
+  }
+});
+
+test("connections() is ordered by configured server order, not handshake completion order (F4)", async () => {
+  const { mgr } = manager();
+  // "slow" is listed first in the config but will finish its handshake
+  // later — a fake server has no artificial handshake delay knob, so this
+  // relies on "fast" being pushed a channel event to prove genuine liveness,
+  // while ordering itself is asserted purely from `defs` key order.
+  await mgr.connectAll({
+    zeta: { command: process.execPath, args: [FAKE] },
+    alpha: { command: process.execPath, args: [FAKE] },
+    mid: { command: process.execPath, args: [FAKE] },
+  });
+  const names = mgr.connections().map((c) => c.name);
+  assert.deepEqual(names, ["zeta", "alpha", "mid"], `expected configured order, got: ${names.join(", ")}`);
+  await mgr.closeAll();
+});
+
+test("a live stream error is logged rather than silently swallowed (F3)", async () => {
+  const { mgr, logs } = manager();
+  const conns = await mgr.connectAll({ fake: { command: process.execPath, args: [FAKE] } });
+  const entry = (mgr as unknown as { live: Map<string, { child: { stdout: NodeJS.ReadableStream } }> }).live.get(
+    "fake",
+  );
+  assert.ok(entry, "fake must be live");
+  entry!.child.stdout.emit("error", new Error("EPIPE synthetic"));
+  assert.ok(
+    logs.some((l) => /stdout error/i.test(l) && /EPIPE synthetic/.test(l)),
+    `expected a logged stdout error, got: ${logs.join(" | ")}`,
+  );
+  assert.equal(conns.length, 1);
+  await mgr.closeAll();
+});
+
+test("a retry that reconnects fires onConnected with the up-to-date connection list (F1)", async () => {
+  const events: ChannelEvent[] = [];
+  const statuses: string[] = [];
+  const logs: string[] = [];
+  const onConnectedCalls: string[][] = [];
+  const mgr = new ConnectionManager({
+    onEvent: (e) => events.push(e),
+    onStatus: (s) => statuses.push(s),
+    log: (m) => logs.push(m),
+    onConnected: (conns) => onConnectedCalls.push(conns.map((c) => c.name)),
+    retryBaseMs: 40,
+    retryMaxMs: 40,
+  });
+  // A process that spawns and exits immediately without responding to
+  // initialize: a deterministic mid-handshake death on the *first* attempt.
+  // The retry's own connectOne (same command/args) will hit the same fate
+  // every time with this fixture, so instead swap the def in place before
+  // the retry fires: scheduleRetry reads `this.defs[name]` fresh each time,
+  // so mutating the manager's stored def changes what the retry spawns.
+  const conns = await mgr.connectAll({ flaky: { command: process.execPath, args: ["-e", "process.exit(1)"] } });
+  assert.equal(conns.length, 0);
+  (mgr as unknown as { defs: Record<string, unknown> }).defs.flaky = { command: process.execPath, args: [FAKE] };
+  await new Promise((r) => setTimeout(r, 400));
+  assert.ok(onConnectedCalls.length > 0, "onConnected must fire once the retry connects");
+  assert.deepEqual(onConnectedCalls.at(-1), ["flaky"]);
+  assert.equal(mgr.connections().length, 1);
+  await mgr.closeAll();
+});
+
+test("an unexpected rejection from a retry's connectOne is caught, not left unhandled (F7)", async () => {
+  const { mgr, logs } = manager({ retryBaseMs: 40, retryMaxMs: 40 });
+  await mgr.connectAll({ ghost: { command: "definitely-not-a-real-binary-xyz" } });
+
+  // Force the retry's own connectOne to throw, simulating an unexpected
+  // failure inside handshake (e.g. child.kill() EPERM) rather than one of
+  // connectOne's normal resolve-to-undefined error paths.
+  const patched = mgr as unknown as { connectOne: (...args: unknown[]) => Promise<unknown> };
+  patched.connectOne = async () => {
+    throw new Error("synthetic handshake throw");
+  };
+
+  let unhandled: unknown;
+  const onUnhandled = (reason: unknown) => { unhandled = reason; };
+  process.once("unhandledRejection", onUnhandled);
+  await new Promise((r) => setTimeout(r, 250));
+  process.removeListener("unhandledRejection", onUnhandled);
+
+  assert.equal(unhandled, undefined, `expected no unhandled rejection, got: ${String(unhandled)}`);
+  assert.ok(
+    logs.some((l) => /retry attempt failed/.test(l) && /synthetic handshake throw/.test(l)),
+    `expected a logged retry failure, got: ${logs.join(" | ")}`,
+  );
+  await mgr.closeAll();
+});
+
+test("closing a connection twice in the same tick does not stack kill timers or exit listeners (F11)", async () => {
+  const { mgr, logs } = manager();
+  const conns = await mgr.connectAll({
+    stubborn3: { command: process.execPath, args: [FAKE], env: { FAKE_IGNORE_SIGTERM: "1" } },
+  });
+  const pidLine = logs.find((l) => l.includes("PID:"));
+  assert.ok(pidLine, `expected the fake server to report its pid, got: ${logs.join(" | ")}`);
+  const pid = Number(pidLine.split("PID:")[1]);
+  assert.ok(isAlive(pid), `expected pid ${pid} to be alive before close()`);
+
+  const start = Date.now();
+  conns[0].close();
+  conns[0].close(); // same tick: must not register a second SIGKILL timer / exit listener
+  while (isAlive(pid)) {
+    assert.ok(Date.now() - start < 2000, `pid ${pid} is still alive ${Date.now() - start}ms after double close()`);
+    await new Promise((r) => setTimeout(r, 20));
+  }
+});
+
+test("two concurrent connectAll calls do not interleave — the second supersedes the first cleanly", async () => {
+  const { mgr } = manager();
+  const p1 = mgr.connectAll({ a: { command: process.execPath, args: [FAKE] } });
+  const p2 = mgr.connectAll({ b: { command: process.execPath, args: [FAKE] } });
+  const [r1, r2] = await Promise.all([p1, p2]);
+
+  // Both calls settle successfully (the first is superseded, not aborted),
+  // but they must run one after the other — never interleaved.
+  assert.equal(r1.length, 1);
+  assert.equal(r1[0].name, "a");
+  assert.equal(r2.length, 1);
+  assert.equal(r2[0].name, "b");
+
+  // The surviving live state must match the second call's defs exactly —
+  // not a mix of both, and not zero connections.
+  const conns = mgr.connections();
+  assert.equal(conns.length, 1, `expected exactly one live connection, got: ${conns.map((c) => c.name).join(", ")}`);
+  assert.equal(conns[0].name, "b");
+
+  await mgr.closeAll();
+});

package/src/connection.ts

@@ -0,0 +1,386 @@
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { JsonRpcClient } from "./client.ts";
+import type { ChannelServerDef } from "./config.ts";
+import type { ChannelEvent } from "./envelope.ts";
+
+export const CHANNEL_CAPABILITY = "claude/channel";
+export const CHANNEL_NOTIFICATION = "notifications/claude/channel";
+
+const PROTOCOL_VERSION = "2025-06-18";
+const RETRY_BASE_MS = 30_000;
+const RETRY_MAX_MS = 5 * 60_000;
+// Some real channel servers ignore SIGTERM outright — only SIGKILL ends
+// them. A well-behaved server exits on SIGTERM well inside this
+// window, so the escalation almost never fires against it. Deliberately not
+// unref'd: elsewhere in this file timers are unref'd so they cannot hold the
+// process open, but here that would let Node exit before the SIGKILL is
+// delivered, orphaning the very child this timer exists to kill.
+const KILL_GRACE_MS = 300;
+
+// Tracks children currently mid-kill so two killChild() calls landing in the
+// same tick (e.g. conn.close() followed by closeAll() sweeping `pending`)
+// don't each register their own SIGKILL timer and their own `exit` listener.
+const killing = new WeakSet<ChildProcess>();
+
+// SIGTERM, then SIGKILL after a short grace period if the child hasn't
+// exited on its own. Cleared the moment the child's 'exit' fires, so a
+// well-behaved server is never force-killed and a clean shutdown is never
+// delayed.
+function killChild(child: ChildProcess): void {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  if (killing.has(child)) return;
+  killing.add(child);
+  child.kill();
+  const timer = setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+  }, KILL_GRACE_MS);
+  child.once("exit", () => {
+    clearTimeout(timer);
+    killing.delete(child);
+  });
+}
+
+export type McpToolDef = {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+};
+
+export type Connection = {
+  name: string;
+  client: JsonRpcClient;
+  instructions?: string;
+  tools: McpToolDef[];
+  close(): void;
+};
+
+type ManagerOpts = {
+  onEvent: (event: ChannelEvent) => void;
+  onStatus: (status: string) => void;
+  log: (message: string) => void;
+  // Fired after a *retry* connects a server that was not part of the
+  // connections array most recently returned by connectAll()/connections().
+  // Without this, a channel that reconnects 30s after session_start is live
+  // in `this.live` (instructions injected, events waking the agent) but was
+  // never handed back to the caller to re-run tool registration — the exact
+  // "healthy-looking but deaf channel" failure this component exists to
+  // avoid.
+  onConnected?: (connections: Connection[]) => void;
+  // Test seams only: production always uses the real RETRY_BASE_MS/
+  // RETRY_MAX_MS. Overriding lets tests exercise the retry path (including
+  // onConnected above) without waiting out a real 30s backoff.
+  retryBaseMs?: number;
+  retryMaxMs?: number;
+};
+
+export class ConnectionManager {
+  private live = new Map<string, { conn: Connection; child: ChildProcess }>();
+  // Children that have spawned and are mid-handshake, not yet in `live`.
+  // closeAll() must kill these directly — they are otherwise invisible to it,
+  // which is how a hung handshake used to survive closeAll() as an orphan.
+  private pending = new Set<ChildProcess>();
+  private retries = new Map<string, { attempts: number; timer?: NodeJS.Timeout }>();
+  private defs: Record<string, ChannelServerDef> = {};
+
+  // Bumped by closeAll(). Every connectOne()/retry call captures the
+  // generation it started with; if the generation has moved on by the time
+  // it would mutate shared state (this.live), it backs out instead of
+  // resurrecting a connection the caller believes is torn down.
+  private generation = 0;
+
+  // Serializes connectAll() calls. closeAll() has no internal await, so two
+  // unawaited connectAll() calls would otherwise both run their `await
+  // this.closeAll()` before either resumes, letting the second call's
+  // generation bump land underneath the first call's continuation — both
+  // then pass the generation check and end up live together. Each
+  // connectAll() call chains onto this promise instead of running
+  // immediately, so a queued call always starts only after the previous one
+  // has fully settled (including its own closeAll()), and captures the
+  // generation it will actually run under.
+  private queue: Promise<void> = Promise.resolve();
+
+  // Field + body assignment, not a constructor parameter property: Node's
+  // strip-only TypeScript rejects those with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.
+  private readonly opts: ManagerOpts;
+  private readonly retryBaseMs: number;
+  private readonly retryMaxMs: number;
+
+  constructor(opts: ManagerOpts) {
+    this.opts = opts;
+    this.retryBaseMs = opts.retryBaseMs ?? RETRY_BASE_MS;
+    this.retryMaxMs = opts.retryMaxMs ?? RETRY_MAX_MS;
+  }
+
+  // Ordered by the configured server order (spec §4: "connection order for
+  // prefix stability"), not by whichever server happened to finish its
+  // handshake first — `this.live` is populated inside a `Promise.all`, so
+  // insertion order there varies run to run, and the instructions block
+  // built from this is a system-prompt prefix. A flipped order costs a full
+  // prompt-cache miss.
+  connections(): Connection[] {
+    const order = Object.keys(this.defs);
+    return [...this.live.values()]
+      .map((e) => e.conn)
+      .sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name));
+  }
+
+  // Deliberately not `async`: the chaining onto `this.queue` must happen
+  // synchronously, before control ever returns to the caller, so that a
+  // second connectAll() called back-to-back (no await in between) sees the
+  // link this call just made rather than the pre-call queue tail.
+  connectAll(defs: Record<string, ChannelServerDef>): Promise<Connection[]> {
+    const run = this.queue.then(() => this.runConnectAll(defs));
+    this.queue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  private async runConnectAll(defs: Record<string, ChannelServerDef>): Promise<Connection[]> {
+    await this.closeAll();
+    this.defs = defs;
+    const gen = this.generation;
+    const results = await Promise.all(
+      Object.entries(defs).map(([name, def]) => this.connectOne(name, def, gen)),
+    );
+    const ok = results.filter((c): c is Connection => c !== undefined);
+    this.publishStatus();
+    return ok;
+  }
+
+  private async connectOne(name: string, def: ChannelServerDef, gen: number): Promise<Connection | undefined> {
+    let child: ChildProcess;
+    try {
+      child = spawn(def.command, def.args ?? [], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env, ...(def.env ?? {}) },
+        ...(def.cwd ? { cwd: def.cwd } : {}),
+      });
+    } catch (error) {
+      this.opts.log(`channel ${name}: spawn failed: ${String(error)}`);
+      this.scheduleRetry(name, gen);
+      return undefined;
+    }
+
+    // spawn() is async: ENOENT arrives on 'error', not as a throw. Wiring the
+    // connection before this resolves turns a missing binary into a silent
+    // dead pipe. A failure here is transient-looking (the binary may appear
+    // later), so it is retried like any other startup failure.
+    const started = await new Promise<boolean>((resolve) => {
+      const onSpawn = () => { cleanup(); resolve(true); };
+      const onError = (err: Error) => {
+        cleanup();
+        this.opts.log(`channel ${name}: spawn failed: ${err.message}`);
+        resolve(false);
+      };
+      const cleanup = () => {
+        child.removeListener("spawn", onSpawn);
+        child.removeListener("error", onError);
+      };
+      child.once("spawn", onSpawn);
+      child.once("error", onError);
+    });
+
+    if (!started) {
+      this.scheduleRetry(name, gen);
+      return undefined;
+    }
+    if (!child.stdin || !child.stdout) {
+      killChild(child);
+      this.scheduleRetry(name, gen);
+      return undefined;
+    }
+    if (gen !== this.generation) {
+      // closeAll() ran while we were waiting on the spawn/error gate.
+      killChild(child);
+      return undefined;
+    }
+
+    this.pending.add(child);
+    try {
+      return await this.handshake(name, def, gen, child);
+    } finally {
+      this.pending.delete(child);
+    }
+  }
+
+  private async handshake(
+    name: string,
+    def: ChannelServerDef,
+    gen: number,
+    child: ChildProcess,
+  ): Promise<Connection | undefined> {
+    // If the child's own pipe is already broken (it died before we got here,
+    // or dies mid-write), a write must not surface as an unhandled 'error'
+    // event and crash the process — the exit handler below is what reports
+    // the death.
+    // The handler must stay — an unhandled stream 'error' crashes the
+    // process — but it must log. Silently swallowing a *live* pipe error
+    // stops delivery with no 'exit' event, so no retry is scheduled and
+    // publishStatus() keeps reporting healthy: mail is then lost silently
+    // and indefinitely with zero evidence.
+    child.stdin?.on("error", (err) => this.opts.log(`channel ${name}: stdin error: ${String(err)}`));
+    child.stdout?.on("error", (err) => this.opts.log(`channel ${name}: stdout error: ${String(err)}`));
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      const text = chunk.toString("utf-8").trim();
+      if (text !== "") this.opts.log(`channel ${name} stderr: ${text}`);
+    });
+
+    const client = new JsonRpcClient({ stdin: child.stdin!, stdout: child.stdout! });
+
+    // Registered BEFORE the handshake requests: a child that dies mid-
+    // handshake must not fire 'exit' into a void (a listener installed only
+    // after `initialize` resolves would miss it entirely, leaving a dead
+    // child silently inserted into `live` as if it were healthy). Closing
+    // the client here makes the in-flight request reject immediately
+    // instead of waiting out JsonRpcClient's 30s timeout.
+    let handshakeDone = false;
+    child.once("exit", (code) => {
+      const entry = this.live.get(name);
+      if (entry && entry.child === child) {
+        this.live.delete(name);
+        this.opts.log(`channel ${name}: exited (code ${code ?? "null"})`);
+        this.publishStatus();
+        this.scheduleRetry(name, gen);
+        return;
+      }
+      if (!handshakeDone) {
+        this.opts.log(`channel ${name}: exited during handshake (code ${code ?? "null"})`);
+        client.close();
+      }
+    });
+
+    let result: Record<string, unknown>;
+    try {
+      result = (await client.request("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "channels.tools", version: "0.1.0" },
+      })) as Record<string, unknown>;
+    } catch (error) {
+      this.opts.log(`channel ${name}: initialize failed: ${String(error)}`);
+      handshakeDone = true;
+      client.close();
+      killChild(child);
+      this.scheduleRetry(name, gen);
+      return undefined;
+    }
+
+    if (gen !== this.generation) {
+      handshakeDone = true;
+      client.close();
+      killChild(child);
+      return undefined;
+    }
+
+    const capabilities = (result.capabilities ?? {}) as { experimental?: Record<string, unknown> };
+    if (!capabilities.experimental || !(CHANNEL_CAPABILITY in capabilities.experimental)) {
+      this.opts.log(`channel ${name}: rejected — no ${CHANNEL_CAPABILITY} capability declared`);
+      handshakeDone = true;
+      client.close();
+      killChild(child);
+      // Permanent incompatibility, not a transient fault: never retried.
+      return undefined;
+    }
+
+    client.notify("notifications/initialized");
+
+    let tools: McpToolDef[] = [];
+    try {
+      const listed = (await client.request("tools/list", {})) as { tools?: McpToolDef[] };
+      tools = listed.tools ?? [];
+    } catch (error) {
+      this.opts.log(`channel ${name}: tools/list failed: ${String(error)}`);
+    }
+
+    handshakeDone = true;
+
+    if (gen !== this.generation) {
+      client.close();
+      killChild(child);
+      return undefined;
+    }
+
+    client.onNotification((method, params) => {
+      if (method !== CHANNEL_NOTIFICATION) return;
+      const p = (params ?? {}) as { content?: unknown; meta?: unknown };
+      const meta: Record<string, string> = {};
+      if (typeof p.meta === "object" && p.meta !== null) {
+        for (const [k, v] of Object.entries(p.meta as Record<string, unknown>)) {
+          if (v !== undefined && v !== null) meta[k] = String(v);
+        }
+      }
+      this.opts.onEvent({ source: name, content: String(p.content ?? ""), meta });
+    });
+
+    const conn: Connection = {
+      name,
+      client,
+      ...(typeof result.instructions === "string" ? { instructions: result.instructions } : {}),
+      tools,
+      close: () => { client.close(); killChild(child); },
+    };
+
+    this.live.set(name, { conn, child });
+    this.retries.delete(name);
+    return conn;
+  }
+
+  private scheduleRetry(name: string, gen: number): void {
+    if (gen !== this.generation) return;
+    const def = this.defs[name];
+    if (!def) return;
+    const state = this.retries.get(name) ?? { attempts: 0 };
+    state.attempts += 1;
+    const delay = Math.min(this.retryBaseMs * 2 ** (state.attempts - 1), this.retryMaxMs);
+    this.opts.log(`channel ${name}: retrying in ${Math.round(delay / 1000)}s (attempt ${state.attempts})`);
+    const timer = setTimeout(() => {
+      if (gen !== this.generation) return;
+      this.connectOne(name, def, gen)
+        .then((conn) => {
+          if (!conn || gen !== this.generation) return;
+          this.publishStatus();
+          // The caller (index.ts) is not otherwise notified that a
+          // previously-failed channel just came up: its instructions and
+          // events are now live via `this.live`, but the tool layer never
+          // heard about it without this callback.
+          this.opts.onConnected?.(this.connections());
+        })
+        .catch((error) => {
+          // connectOne's own error paths all resolve rather than reject;
+          // this only catches an unexpected throw (e.g. inside handshake).
+          // Without a rejection handler here, that throw becomes an
+          // unhandled rejection and exits the process under Node's default.
+          this.opts.log(`channel ${name}: retry attempt failed: ${String(error)}`);
+        });
+    }, delay);
+    if (typeof timer.unref === "function") timer.unref();
+    state.timer = timer;
+    this.retries.set(name, state);
+  }
+
+  private publishStatus(): void {
+    const configured = Object.keys(this.defs).length;
+    const up = this.live.size;
+    if (configured === 0) { this.opts.onStatus(""); return; }
+    // A dead channel loses mail silently, so degraded state must be visible.
+    this.opts.onStatus(up === configured ? `channels ${up}/${configured}` : `channels ${up}/${configured} DEGRADED`);
+  }
+
+  async closeAll(): Promise<void> {
+    this.generation++;
+    for (const [, state] of this.retries) if (state.timer) clearTimeout(state.timer);
+    this.retries.clear();
+    for (const [, entry] of this.live) entry.conn.close();
+    this.live.clear();
+    // Kill anything still mid-handshake too — otherwise a hung handshake
+    // outlives closeAll() as an orphan process.
+    for (const child of this.pending) killChild(child);
+    this.pending.clear();
+    this.defs = {};
+    this.opts.onStatus("");
+  }
+}