channels.tools 0.1.0

package/src/envelope.test.ts

@@ -0,0 +1,132 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { splitGuidance, renderBatch, strictestIntent } from "./envelope.ts";
+
+test("splitGuidance separates on the first --- sentinel", () => {
+  const r = splitGuidance("line one\n\n---\nGUIDANCE HERE");
+  assert.equal(r.body, "line one");
+  assert.equal(r.guidance, "GUIDANCE HERE");
+});
+
+test("splitGuidance leaves content without a sentinel untouched", () => {
+  const r = splitGuidance("just an envelope line");
+  assert.equal(r.body, "just an envelope line");
+  assert.equal(r.guidance, undefined);
+});
+
+test("splitGuidance splits only on the first sentinel so guidance may contain one", () => {
+  const r = splitGuidance("body\n\n---\nfirst\n\n---\nsecond");
+  assert.equal(r.body, "body");
+  assert.equal(r.guidance, "first\n\n---\nsecond");
+});
+
+test("a single event renders as a channel block with meta as attributes", () => {
+  const out = renderBatch("muster-channel", [{
+    source: "muster-channel",
+    content: 'muster: reply from pi/pi-setup on thread #305 "x" — call get_thread 305.',
+    meta: { kind: "reply", from: "pi/pi-setup", thread_id: "305", intent: "action-requested", count: "1" },
+  }]);
+  assert.match(out, /^<channel source="muster-channel" /);
+  assert.match(out, /kind="reply"/);
+  assert.match(out, /from="pi\/pi-setup"/);
+  assert.match(out, /thread_id="305"/);
+  assert.match(out, /intent="action-requested"/);
+  assert.match(out, /call get_thread 305\./);
+  assert.match(out, /<\/channel>$/);
+});
+
+test("identical guidance across a batch is emitted once", () => {
+  const ev = (id: string) => ({
+    source: "galley",
+    content: `galley: revise on doc-${id}\n\n---\nNEVER REWRITE THE WHOLE FILE`,
+    meta: { reason: "revise", doc: `doc-${id}` },
+  });
+  const out = renderBatch("galley", [ev("a"), ev("b")]);
+  assert.equal(out.match(/NEVER REWRITE THE WHOLE FILE/g)?.length, 1);
+  assert.match(out, /doc-a/);
+  assert.match(out, /doc-b/);
+});
+
+test("distinct guidance blocks are all kept, in first-appearance order", () => {
+  const out = renderBatch("muster-channel", [
+    { source: "muster-channel", content: "a\n\n---\nFYI GUIDANCE", meta: { intent: "fyi" } },
+    { source: "muster-channel", content: "b\n\n---\nACTION GUIDANCE", meta: { intent: "action-requested" } },
+  ]);
+  assert.match(out, /FYI GUIDANCE/);
+  assert.match(out, /ACTION GUIDANCE/);
+  assert.ok(out.indexOf("FYI GUIDANCE") < out.indexOf("ACTION GUIDANCE"));
+});
+
+test("a batch attributes count and the strictest intent present", () => {
+  const out = renderBatch("muster-channel", [
+    { source: "muster-channel", content: "a", meta: { intent: "fyi" } },
+    { source: "muster-channel", content: "b", meta: { intent: "action-requested" } },
+    { source: "muster-channel", content: "c", meta: { intent: "reply-requested" } },
+  ]);
+  assert.match(out, /count="3"/);
+  assert.match(out, /intent="action-requested"/);
+});
+
+test("attribute values with quotes and angle brackets are escaped", () => {
+  const out = renderBatch("muster-channel", [
+    { source: "muster-channel", content: "x", meta: { subject: 'he said "hi" <b>' } },
+  ]);
+  assert.match(out, /subject="he said &quot;hi&quot; &lt;b&gt;"/);
+  assert.doesNotMatch(out.split("\n")[0], /<b>/);
+});
+
+test("a multi-event batch drops per-event identity attributes, keeping only count and intent (F9)", () => {
+  const out = renderBatch("muster-channel", [
+    { source: "muster-channel", content: "a", meta: { thread_id: "305", from: "x", kind: "reply", intent: "fyi" } },
+    { source: "muster-channel", content: "b", meta: { thread_id: "999", from: "y", kind: "reply", intent: "action-requested" } },
+  ]);
+  assert.doesNotMatch(out, /thread_id=/);
+  assert.doesNotMatch(out, /from=/);
+  assert.doesNotMatch(out, /kind=/);
+  assert.match(out, /count="2"/);
+  assert.match(out, /intent="action-requested"/);
+});
+
+test("a meta key literally named 'source' does not produce a duplicate attribute (F10)", () => {
+  const out = renderBatch("muster-channel", [
+    { source: "muster-channel", content: "x", meta: { source: "evil" } },
+  ]);
+  const matches = out.match(/source="/g) ?? [];
+  assert.equal(matches.length, 1);
+  assert.match(out, /source="muster-channel"/);
+});
+
+test("strictestIntent orders action-requested over reply-requested over fyi", () => {
+  assert.equal(strictestIntent(["fyi", "action-requested", "reply-requested"]), "action-requested");
+  assert.equal(strictestIntent(["fyi", "reply-requested"]), "reply-requested");
+  assert.equal(strictestIntent(["fyi"]), "fyi");
+  assert.equal(strictestIntent([]), undefined);
+  assert.equal(strictestIntent(["unknown-thing"]), "unknown-thing");
+});
+
+test("a server's own count is preserved, not overwritten by the notification count", () => {
+  // muster coalesces server-side: one push can represent many threads, and it
+  // says so in meta.count. Ours counts notifications. Overwriting theirs tells
+  // the agent one thing arrived when three did.
+  const out = renderBatch("muster-channel", [
+    { source: "muster-channel", content: "muster: 3 new — …", meta: { count: "3", intent: "action-requested" } },
+  ]);
+  assert.match(out, /count="3"/);
+});
+
+test("coalescing sums the servers' counts rather than counting notifications", () => {
+  const out = renderBatch("muster-channel", [
+    { source: "muster-channel", content: "a", meta: { count: "3", intent: "fyi" } },
+    { source: "muster-channel", content: "b", meta: { count: "2", intent: "action-requested" } },
+  ]);
+  assert.match(out, /count="5"/);
+  assert.match(out, /intent="action-requested"/);
+});
+
+test("events without a server count fall back to counting notifications", () => {
+  const out = renderBatch("galley", [
+    { source: "galley", content: "a", meta: { reason: "revise" } },
+    { source: "galley", content: "b", meta: { reason: "revise" } },
+  ]);
+  assert.match(out, /count="2"/);
+});

package/src/envelope.ts

@@ -0,0 +1,94 @@
+export type ChannelEvent = {
+  source: string;
+  content: string;
+  meta: Record<string, string>;
+};
+
+const GUIDANCE_SENTINEL = "\n\n---\n";
+
+// Strictness rises with index. An unknown intent sorts above every known
+// one: a server that grows a new intent must not have it silently ranked
+// as the least urgent thing in the batch.
+const STRICTNESS = ["fyi", "reply-requested", "action-requested"];
+
+export function splitGuidance(content: string): { body: string; guidance?: string } {
+  const at = content.indexOf(GUIDANCE_SENTINEL);
+  if (at < 0) return { body: content };
+  return {
+    body: content.slice(0, at),
+    guidance: content.slice(at + GUIDANCE_SENTINEL.length),
+  };
+}
+
+export function strictestIntent(intents: string[]): string | undefined {
+  let best: string | undefined;
+  let bestRank = -1;
+  for (const intent of intents) {
+    if (intent === "") continue;
+    const known = STRICTNESS.indexOf(intent);
+    const rank = known < 0 ? STRICTNESS.length : known;
+    if (rank > bestRank) {
+      bestRank = rank;
+      best = intent;
+    }
+  }
+  return best;
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export function renderBatch(source: string, events: ChannelEvent[]): string {
+  const bodies: string[] = [];
+  const guidance: string[] = [];
+  const intents: string[] = [];
+
+  for (const event of events) {
+    const split = splitGuidance(event.content);
+    if (split.body !== "") bodies.push(split.body);
+    if (split.guidance !== undefined && !guidance.includes(split.guidance)) {
+      guidance.push(split.guidance);
+    }
+    if (event.meta.intent) intents.push(event.meta.intent);
+  }
+
+  // Attributes describe the batch. A single event's identity facts
+  // (thread_id, from, kind, doc, reason, …) are trustworthy verbatim. Once
+  // more than one event is coalesced, those per-event facts no longer
+  // describe "the" event — carrying event[0]'s thread_id while count says 3
+  // is an actively false attribute an agent could act on — so only the
+  // recomputed count and intent survive into a multi-event batch. The
+  // body lines still carry each event's own facts.
+  const attrs: Record<string, string> = events.length > 1 ? {} : { ...(events[0]?.meta ?? {}) };
+  // "source" is reserved for the hardcoded server-name attribute below; a
+  // meta key literally named `source` must not produce a duplicate.
+  delete attrs.source;
+  // A server may coalesce before we do: some servers send one push
+  // representing several events and say how many in meta.count. Overwriting that with our
+  // notification count tells the agent one thing arrived when three did, so
+  // sum the servers' own counts and fall back to counting notifications only
+  // for events that carry none.
+  attrs.count = String(
+    events.reduce((total, event) => {
+      const declared = Number(event.meta.count);
+      return total + (Number.isFinite(declared) && declared > 0 ? declared : 1);
+    }, 0),
+  );
+  const strictest = strictestIntent(intents);
+  if (strictest !== undefined) attrs.intent = strictest;
+  else delete attrs.intent;
+
+  const rendered = Object.entries(attrs)
+    .map(([k, v]) => `${k}="${escapeAttr(v)}"`)
+    .join(" ");
+
+  const parts = [bodies.join("\n")];
+  if (guidance.length > 0) parts.push(guidance.join("\n\n"));
+
+  return `<channel source="${escapeAttr(source)}" ${rendered}>\n${parts.join("\n\n---\n")}\n</channel>`;
+}

package/src/identity.test.ts

@@ -0,0 +1,34 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyIdentity } from "./identity.ts";
+
+test("sets AGENT_SESSION_ID on the given environment", () => {
+  const env: NodeJS.ProcessEnv = {};
+  applyIdentity("session-abc", env);
+  assert.equal(env.AGENT_SESSION_ID, "session-abc");
+});
+
+test("never sets CLAUDE_CODE_SESSION_ID — a pi session must not claim to be Claude Code", () => {
+  const env: NodeJS.ProcessEnv = {};
+  applyIdentity("session-abc", env);
+  assert.equal(env.CLAUDE_CODE_SESSION_ID, undefined);
+});
+
+test("an inherited CLAUDE_CODE_SESSION_ID is left untouched", () => {
+  const env: NodeJS.ProcessEnv = { CLAUDE_CODE_SESSION_ID: "outer" };
+  applyIdentity("session-abc", env);
+  assert.equal(env.CLAUDE_CODE_SESSION_ID, "outer");
+});
+
+test("a later session id replaces an earlier one, as resume and fork require", () => {
+  const env: NodeJS.ProcessEnv = {};
+  applyIdentity("first", env);
+  applyIdentity("second", env);
+  assert.equal(env.AGENT_SESSION_ID, "second");
+});
+
+test("an undefined session id clears the variable rather than writing 'undefined'", () => {
+  const env: NodeJS.ProcessEnv = { AGENT_SESSION_ID: "stale" };
+  applyIdentity(undefined, env);
+  assert.equal(env.AGENT_SESSION_ID, undefined);
+});

package/src/identity.ts

@@ -0,0 +1,13 @@
+export const SESSION_ID_VAR = "AGENT_SESSION_ID";
+
+// Deliberately does NOT set CLAUDE_CODE_SESSION_ID. Some channel servers
+// read that variable to decide whether a session is Claude Code, and a pi
+// session must never claim to be one. Servers wanting this session's id
+// should read the neutral AGENT_SESSION_ID.
+export function applyIdentity(sessionId: string | undefined, env: NodeJS.ProcessEnv = process.env): void {
+  if (sessionId === undefined || sessionId === "") {
+    delete env[SESSION_ID_VAR];
+    return;
+  }
+  env[SESSION_ID_VAR] = sessionId;
+}

package/src/index.test.ts

@@ -0,0 +1,293 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { mkdtempSync, rmSync } from "node:fs";
+import { createExtension } from "./index.ts";
+
+const FAKE = join(import.meta.dirname, "..", "test", "fake-channel-server.ts");
+const FLAKY = join(import.meta.dirname, "..", "test", "flaky-channel-server.ts");
+
+type Handler = (event: unknown, ctx: unknown) => unknown;
+
+type ToolDef = { name: string; execute(id: string, params: unknown): Promise<unknown> };
+
+function fakePi() {
+  const handlers = new Map<string, Handler[]>();
+  const sent: Array<{ msg: unknown; opts: unknown }> = [];
+  const registered: string[] = [];
+  const unregistered: string[] = [];
+  const tools = new Map<string, ToolDef>();
+  const statuses: string[] = [];
+  const pi = {
+    on(event: string, handler: Handler) {
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+    },
+    sendUserMessage(content: unknown, opts: unknown) { sent.push({ msg: content, opts }); },
+    registerTool(def: ToolDef) { registered.push(def.name); tools.set(def.name, def); },
+    unregisterTool(name: string) { unregistered.push(name); tools.delete(name); },
+    getAllTools() { return [{ name: "bash" }, { name: "read" }]; },
+    getActiveTools() { return ["bash", "read"]; },
+    setActiveTools(_names: string[]) {},
+  };
+  const ctx = {
+    sessionManager: { getSessionId: () => "session-xyz" },
+    ui: { setStatus: (_k: string, v?: string) => { statuses.push(v ?? ""); } },
+    hasUI: true,
+    cwd: process.cwd(),
+  };
+  async function fire(event: string, payload: unknown = {}): Promise<unknown[]> {
+    const out: unknown[] = [];
+    for (const h of handlers.get(event) ?? []) out.push(await h(payload, ctx));
+    return out;
+  }
+  return { pi, ctx, fire, sent, registered, unregistered, tools, statuses };
+}
+
+test("session_start sets AGENT_SESSION_ID before any server is spawned", async () => {
+  const { pi, fire } = fakePi();
+  const spawnOrder: string[] = [];
+  const env: NodeJS.ProcessEnv = {};
+  createExtension(pi as never, {
+    env,
+    loadConfig: () => ({ fake: { command: process.execPath, args: [FAKE] } }),
+    onBeforeSpawn: () => { spawnOrder.push(`env=${env.AGENT_SESSION_ID ?? "unset"}`); },
+  });
+  await fire("session_start", { reason: "startup" });
+  assert.deepEqual(spawnOrder, ["env=session-xyz"],
+    "identity must be set before spawn: galley channel reads it at its own startup");
+  // session_start's connectAll() spawns and fully handshakes the fake server;
+  // leaving it open here leaks the child process and hangs node --test.
+  await fire("session_shutdown");
+});
+
+test("an inbound event while idle is delivered as a user message through the full prompt pipeline", async () => {
+  const { pi, fire, sent } = fakePi();
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: () => ({ fake: { command: process.execPath, args: [FAKE], env: { FAKE_PUSH_AFTER_MS: "50" } } }),
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 500));
+  assert.equal(sent.length, 1);
+  const opts = sent[0].opts as { deliverAs?: string };
+  assert.equal(opts.deliverAs, "steer");
+  const text = sent[0].msg as string;
+  assert.match(text, /<channel source="fake"/);
+  await fire("session_shutdown");
+});
+
+test("a server's tools are registered under their own names", async () => {
+  const { pi, fire, registered } = fakePi();
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: () => ({ fake: { command: process.execPath, args: [FAKE] } }),
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 300));
+  assert.ok(registered.includes("fake_status"), `registered: ${registered.join(", ")}`);
+  await fire("session_shutdown");
+});
+
+test("before_agent_start injects the connected server's instructions", async () => {
+  const { pi, fire } = fakePi();
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: () => ({ fake: { command: process.execPath, args: [FAKE] } }),
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 300));
+  const results = await fire("before_agent_start", { systemPrompt: "BASE PROMPT" });
+  const returned = results.find((r): r is { systemPrompt: string } =>
+    typeof r === "object" && r !== null && "systemPrompt" in r);
+  assert.ok(returned, "before_agent_start must return a modified systemPrompt");
+  assert.match(returned.systemPrompt, /BASE PROMPT/);
+  assert.match(returned.systemPrompt, /FAKE CORE INSTRUCTIONS/);
+  await fire("session_shutdown");
+});
+
+test("before_agent_start returns undefined when nothing is connected", async () => {
+  const { pi, fire } = fakePi();
+  createExtension(pi as never, { env: {}, loadConfig: () => ({}) });
+  await fire("session_start", { reason: "startup" });
+  const results = await fire("before_agent_start", { systemPrompt: "BASE PROMPT" });
+  assert.deepEqual(results, [undefined]);
+  await fire("session_shutdown");
+});
+
+test("session_shutdown closes connections and clears status", async () => {
+  const { pi, fire, statuses } = fakePi();
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: () => ({ fake: { command: process.execPath, args: [FAKE] } }),
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 300));
+  await fire("session_shutdown");
+  assert.equal(statuses.at(-1), "");
+});
+
+test("a tool still works after a resume re-registers it against a fresh connection", async () => {
+  const { pi, fire, tools } = fakePi();
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: () => ({ fake: { command: process.execPath, args: [FAKE] } }),
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 300));
+  // Simulate a resume: session_start fires again, connectAll() closes the
+  // first connection's client and spawns a fresh one. A stale registration
+  // guard would leave the tool's execute() bound to the now-closed client.
+  await fire("session_start", { reason: "resume" });
+  await new Promise((r) => setTimeout(r, 300));
+  const tool = tools.get("fake_status");
+  assert.ok(tool, "fake_status must still be registered after resume");
+  const result = (await tool.execute("call-1", {})) as { content: Array<{ text: string }> };
+  assert.deepEqual(result.content, [{ type: "text", text: "fake ok" }]);
+  await fire("session_shutdown");
+});
+
+test("a tool result with isError:true is signaled by throwing, not returned silently", async () => {
+  const { pi, fire, tools } = fakePi();
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: () => ({
+      fake: { command: process.execPath, args: [FAKE], env: { FAKE_TOOL_ISERROR: "1" } },
+    }),
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 300));
+  const tool = tools.get("fake_status");
+  assert.ok(tool, "fake_status must be registered");
+  await assert.rejects(() => tool!.execute("call-1", {}), /FAKE TOOL ERROR TEXT/);
+  await fire("session_shutdown");
+});
+
+test("a retry that lands before connectAll resolves does not have its tools dropped as stale", async () => {
+  // The race F1's own fix created: `fake` fails, schedules a 50ms retry, and
+  // reconnects while `slow` is still handshaking. onConnected registers
+  // fake_status. Then session_start's own registerTools() runs — and if it
+  // registers from connectAll's returned array (which cannot contain `fake`,
+  // whose first attempt failed) instead of manager.connections(), it treats
+  // fake_status as stale and unregisters it. The channel is live, its
+  // instructions are injected, its events wake the agent, and its tool is gone
+  // for the rest of the session with no further retry scheduled.
+  const { pi, fire, tools, unregistered } = fakePi();
+  const dir = mkdtempSync(join(tmpdir(), "pi-channels-race-"));
+  const counterFile = join(dir, "count.txt");
+  try {
+    createExtension(pi as never, {
+      env: {},
+      loadConfig: () => ({
+        fake: { command: process.execPath, args: [FLAKY], env: { FLAKY_COUNTER_FILE: counterFile } },
+        // A DISTINCT tool name is essential: if both servers advertised
+        // fake_status, the stale computation would never drop it and this test
+        // would pass against the buggy code.
+        slow: {
+          command: process.execPath,
+          args: [FAKE],
+          env: { FAKE_INIT_DELAY_MS: "400", FAKE_TOOL_NAME: "slow_status" },
+        },
+      }),
+      retryBaseMs: 50,
+      retryMaxMs: 50,
+    });
+    // session_start does not resolve until `slow` finishes its 400ms handshake,
+    // so the 50ms retry lands squarely inside it.
+    await fire("session_start", { reason: "startup" });
+    assert.ok(
+      tools.has("fake_status"),
+      `fake_status must survive session_start's registerTools; unregistered: ${unregistered.join(", ")}`,
+    );
+    assert.ok(
+      !unregistered.includes("fake_status"),
+      "fake_status must not be treated as stale — the retry had already registered it",
+    );
+    const tool = tools.get("fake_status");
+    const result = (await tool!.execute("call-1", {})) as { content: Array<{ text: string }> };
+    assert.deepEqual(result.content, [{ type: "text", text: "fake ok" }], "the surviving tool must still work");
+  } finally {
+    // In the finally, not after the assertions: a failing assertion would
+    // otherwise skip it and leave the channels open, hanging the test runner.
+    await fire("session_shutdown");
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a channel that reconnects via retry gets its tools re-registered (F1)", async () => {
+  const { pi, fire, tools } = fakePi();
+  const dir = mkdtempSync(join(tmpdir(), "pi-channels-flaky-"));
+  const counterFile = join(dir, "count.txt");
+  try {
+    createExtension(pi as never, {
+      env: {},
+      loadConfig: () => ({
+        fake: { command: process.execPath, args: [FLAKY], env: { FLAKY_COUNTER_FILE: counterFile } },
+      }),
+      retryBaseMs: 50,
+      retryMaxMs: 50,
+    });
+    await fire("session_start", { reason: "startup" });
+    // The first attempt dies mid-handshake, so session_start's own
+    // registerTools() call runs with zero connections — this is the state
+    // pre-fix leaves the channel in forever.
+    assert.ok(!tools.has("fake_status"), "the first (failed) attempt must not have registered anything yet");
+    // 50ms later the retry connects for real.
+    await new Promise((r) => setTimeout(r, 500));
+    const tool = tools.get("fake_status");
+    assert.ok(tool, "fake_status must be registered once the retry reconnects");
+    const result = (await tool!.execute("call-1", {})) as { content: Array<{ text: string }> };
+    assert.deepEqual(result.content, [{ type: "text", text: "fake ok" }]);
+    await fire("session_shutdown");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("stale tools are dropped from the active set when unregisterTool is unavailable (F5)", async () => {
+  const { pi, fire, tools } = fakePi();
+  (pi as { unregisterTool?: unknown }).unregisterTool = undefined;
+  const activeToolsCalls: string[][] = [];
+  pi.getActiveTools = () => ["bash", "read", "fake_status"];
+  pi.setActiveTools = (names: string[]) => { activeToolsCalls.push(names); };
+  let channelConfigured = true;
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: (): Record<string, import("./config.ts").ChannelServerDef> =>
+      channelConfigured ? { fake: { command: process.execPath, args: [FAKE] } } : {},
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 300));
+  assert.ok(tools.has("fake_status"));
+  // Simulate a resume where the channel is no longer configured: connectAll
+  // tears down the old connection and there is nothing left to register, so
+  // "fake_status" is now stale.
+  channelConfigured = false;
+  await fire("session_start", { reason: "resume" });
+  await new Promise((r) => setTimeout(r, 100));
+  assert.ok(
+    activeToolsCalls.some((names) => !names.includes("fake_status")),
+    `expected setActiveTools to be called without fake_status, got: ${JSON.stringify(activeToolsCalls)}`,
+  );
+  await fire("session_shutdown");
+});
+
+test("a registerTool failure during session_start does not block the mail gate from opening", async () => {
+  const { pi, fire, sent } = fakePi();
+  pi.registerTool = () => {
+    throw new Error("boom: registerTool exploded");
+  };
+  createExtension(pi as never, {
+    env: {},
+    loadConfig: () => ({
+      fake: { command: process.execPath, args: [FAKE], env: { FAKE_PUSH_AFTER_MS: "50" } },
+    }),
+  });
+  await fire("session_start", { reason: "startup" });
+  await new Promise((r) => setTimeout(r, 500));
+  assert.equal(sent.length, 1,
+    "mail must still be delivered even though session_start's registerTool step threw");
+  await fire("session_shutdown");
+});