tmux-ide 2.7.0 → 2.8.0

package/packages/contracts/src/__tests__/control.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Schema tests for the control-socket protocol (M23.3): the versioned
+ * envelope and the per-verb params. These pin the WIRE contract — a change
+ * that breaks one of these breaks every connected agent loop.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  CONTROL_PROTOCOL_VERSION,
+  CONTROL_WAIT_MAX_TIMEOUT_MS,
+  agentStatusEventSchema,
+  controlEventSchema,
+  controlRequestSchema,
+  controlResponseSchema,
+  restartAgentParamsSchema,
+  sendParamsSchema,
+  spawnParamsSchema,
+  waitParamsSchema,
+} from "../control";
+
+describe("controlRequestSchema", () => {
+  it("accepts a minimal request (params optional)", () => {
+    const r = controlRequestSchema.parse({ v: 1, id: 1, verb: "fleet" });
+    expect(r.verb).toBe("fleet");
+    expect(r.params).toBeUndefined();
+  });
+
+  it("accepts string ids and object params", () => {
+    const r = controlRequestSchema.parse({
+      v: 1,
+      id: "req-7",
+      verb: "send",
+      params: { session: "s", target: "%1", message: "hi" },
+    });
+    expect(r.id).toBe("req-7");
+  });
+
+  it("keeps verb an OPEN string — unknown verbs parse (dispatch answers them)", () => {
+    expect(controlRequestSchema.parse({ v: 1, id: 1, verb: "verb-from-the-future" }).verb).toBe(
+      "verb-from-the-future",
+    );
+  });
+
+  it("rejects a wrong or missing version", () => {
+    expect(() => controlRequestSchema.parse({ v: 2, id: 1, verb: "fleet" })).toThrow();
+    expect(() => controlRequestSchema.parse({ id: 1, verb: "fleet" })).toThrow();
+  });
+
+  it("rejects a missing id or empty verb", () => {
+    expect(() => controlRequestSchema.parse({ v: 1, verb: "fleet" })).toThrow();
+    expect(() => controlRequestSchema.parse({ v: 1, id: 1, verb: "" })).toThrow();
+  });
+});
+
+describe("controlResponseSchema", () => {
+  it("accepts an ok response with arbitrary data", () => {
+    const r = controlResponseSchema.parse({ v: 1, id: 3, ok: true, data: { projects: [] } });
+    expect(r.ok).toBe(true);
+  });
+
+  it("accepts an error response with a null id (uncorrelatable frame)", () => {
+    const r = controlResponseSchema.parse({
+      v: 1,
+      id: null,
+      ok: false,
+      error: { code: "bad-request", message: "unparseable frame" },
+    });
+    expect(r.ok).toBe(false);
+  });
+
+  it("rejects an error response without the error object", () => {
+    expect(() => controlResponseSchema.parse({ v: 1, id: 1, ok: false })).toThrow();
+  });
+});
+
+describe("controlEventSchema + agentStatusEventSchema", () => {
+  it("accepts an event frame and its agent-status payload", () => {
+    const frame = controlEventSchema.parse({
+      v: CONTROL_PROTOCOL_VERSION,
+      event: "agent-status",
+      data: { ts: "2026-07-10T12:00:00Z", session: "zz-x", from: null, to: "working" },
+    });
+    const ev = agentStatusEventSchema.parse(frame.data);
+    expect(ev.from).toBeNull();
+    expect(ev.to).toBe("working");
+  });
+
+  it("rejects an unknown status in the payload", () => {
+    expect(() =>
+      agentStatusEventSchema.parse({ ts: "t", session: "s", from: null, to: "sleeping" }),
+    ).toThrow();
+  });
+});
+
+describe("waitParamsSchema", () => {
+  it("accepts both kinds", () => {
+    expect(
+      waitParamsSchema.parse({ kind: "agent-status", session: "s", status: "done" }).kind,
+    ).toBe("agent-status");
+    expect(waitParamsSchema.parse({ kind: "output", target: "%1", match: "ok" }).kind).toBe(
+      "output",
+    );
+  });
+
+  it("caps timeoutMs", () => {
+    expect(() =>
+      waitParamsSchema.parse({
+        kind: "output",
+        target: "%1",
+        match: "ok",
+        timeoutMs: CONTROL_WAIT_MAX_TIMEOUT_MS + 1,
+      }),
+    ).toThrow();
+  });
+});
+
+describe("spawnParamsSchema", () => {
+  it("requires exactly one of kind/command", () => {
+    expect(() => spawnParamsSchema.parse({ session: "s" })).toThrow();
+    expect(() => spawnParamsSchema.parse({ session: "s", kind: "claude", command: "x" })).toThrow();
+    expect(spawnParamsSchema.parse({ session: "s", kind: "claude" }).kind).toBe("claude");
+  });
+
+  it("requires a session or a sessionName", () => {
+    expect(() => spawnParamsSchema.parse({ kind: "claude" })).toThrow();
+    expect(spawnParamsSchema.parse({ sessionName: "zz-new", kind: "claude" }).sessionName).toBe(
+      "zz-new",
+    );
+  });
+
+  it("requires paneId for split placements only", () => {
+    expect(() =>
+      spawnParamsSchema.parse({ session: "s", kind: "claude", placement: "split-h" }),
+    ).toThrow();
+    expect(
+      spawnParamsSchema.parse({ session: "s", kind: "claude", placement: "window" }).placement,
+    ).toBe("window");
+  });
+});
+
+describe("sendParamsSchema / restartAgentParamsSchema", () => {
+  it("send requires session, target and a non-empty message", () => {
+    expect(() => sendParamsSchema.parse({ session: "s", target: "%1", message: "" })).toThrow();
+    expect(sendParamsSchema.parse({ session: "s", target: "%1", message: "go" }).noEnter).toBe(
+      undefined,
+    );
+  });
+
+  it("restart requires kind or command", () => {
+    expect(() => restartAgentParamsSchema.parse({ paneId: "%1" })).toThrow();
+    expect(restartAgentParamsSchema.parse({ paneId: "%1", command: "claude" }).command).toBe(
+      "claude",
+    );
+  });
+});

package/packages/contracts/src/control.ts

@@ -0,0 +1,217 @@
+/**
+ * The local control-socket protocol (M23.3) — newline-delimited JSON frames
+ * over a Unix socket (`~/.tmux-ide/control.sock` by default). This is the
+ * scriptable surface for agent loops: connect once, drive the fleet, get
+ * events PUSHED instead of spawning a CLI per poll.
+ *
+ * Every frame is one JSON object on one line. Three frame shapes:
+ *
+ *   request   {v:1, id, verb, params?}          client → server
+ *   response  {v:1, id, ok, data|error}         server → client (id-correlated)
+ *   event     {v:1, event, data}                server → client (after `subscribe`)
+ *
+ * The envelope is VERSIONED from day one (`v: 1`) and `verb` is an open
+ * string in the envelope (unknown verbs are answered with an `unknown-verb`
+ * error, not a parse failure) so a v2 can add verbs without breaking v1
+ * clients. The future native-app bridge (#90) layers on mechanically: each
+ * NDJSON frame maps 1:1 to a WebSocket text message — id correlation and the
+ * unsolicited event channel already match WS semantics, so the bridge is a
+ * transport swap, not a protocol change.
+ *
+ * Params schemas are per-verb and STRICT about types but tolerant of absence
+ * (`params` may be omitted for verbs that need none).
+ */
+import { z } from "zod";
+
+/** The protocol version every frame carries. Bump only on breaking changes. */
+export const CONTROL_PROTOCOL_VERSION = 1;
+
+/** Request ids are client-chosen; responses echo them verbatim. */
+export const controlIdSchema = z.union([z.string(), z.number()]);
+export type ControlId = z.infer<typeof controlIdSchema>;
+
+/** The agent statuses the detection layer produces (mirrors the daemon's `AgentStatus`). */
+export const agentStatusSchema = z.enum(["blocked", "working", "done", "idle", "unknown"]);
+export type ControlAgentStatus = z.infer<typeof agentStatusSchema>;
+
+/** The verbs a v1 server understands (dispatch also answers unknown strings honestly). */
+export const CONTROL_VERBS = [
+  "fleet",
+  "agents",
+  "send",
+  "wait",
+  "spawn",
+  "restart-agent",
+  "stop-agent",
+  "explain",
+  "subscribe",
+] as const;
+export type ControlVerb = (typeof CONTROL_VERBS)[number];
+
+/**
+ * The request envelope. `verb` stays an open string here — verb existence is
+ * a DISPATCH concern (answered with `unknown-verb`), not a parse failure, so
+ * newer clients get an honest error from an older server.
+ */
+export const controlRequestSchema = z.object({
+  v: z.literal(CONTROL_PROTOCOL_VERSION),
+  id: controlIdSchema,
+  verb: z.string().min(1),
+  params: z.record(z.string(), z.unknown()).optional(),
+});
+export type ControlRequest = z.infer<typeof controlRequestSchema>;
+
+/** Machine-readable error codes a response can carry. */
+export const controlErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+});
+export type ControlError = z.infer<typeof controlErrorSchema>;
+
+/**
+ * The response envelope. `id` is null only for frames the server could not
+ * correlate (unparseable JSON / envelope) — everything else echoes the
+ * request id.
+ */
+export const controlResponseSchema = z.discriminatedUnion("ok", [
+  z.object({
+    v: z.literal(CONTROL_PROTOCOL_VERSION),
+    id: controlIdSchema.nullable(),
+    ok: z.literal(true),
+    data: z.unknown(),
+  }),
+  z.object({
+    v: z.literal(CONTROL_PROTOCOL_VERSION),
+    id: controlIdSchema.nullable(),
+    ok: z.literal(false),
+    error: controlErrorSchema,
+  }),
+]);
+export type ControlResponse = z.infer<typeof controlResponseSchema>;
+
+/** An unsolicited push frame (only sent to connections that ran `subscribe`). */
+export const controlEventSchema = z.object({
+  v: z.literal(CONTROL_PROTOCOL_VERSION),
+  event: z.string().min(1),
+  data: z.unknown(),
+});
+export type ControlEventFrame = z.infer<typeof controlEventSchema>;
+
+/** The one v1 event stream: session-level agent-status transitions
+ *  (`from` is null the first time the subscriber's server sees a session). */
+export const agentStatusEventSchema = z.object({
+  ts: z.string(),
+  session: z.string(),
+  from: agentStatusSchema.nullable(),
+  to: agentStatusSchema,
+});
+export type AgentStatusEvent = z.infer<typeof agentStatusEventSchema>;
+
+// ---------------------------------------------------------------------------
+// Per-verb params
+// ---------------------------------------------------------------------------
+
+/** `agents` — flat per-pane agent entries, optionally scoped to one session. */
+export const agentsParamsSchema = z.object({
+  session: z.string().optional(),
+});
+export type AgentsParams = z.infer<typeof agentsParamsSchema>;
+
+/**
+ * `send` — deliver text to a pane in `session`. `target` accepts the same
+ * forms as `tmux-ide send`: a pane id (%N), an @ide_name, a title, a role, or
+ * a partial title. `dir` (optional) is the project dir long messages are
+ * dispatched through as a file; without it long text is sent directly.
+ */
+export const sendParamsSchema = z.object({
+  session: z.string().min(1),
+  target: z.string().min(1),
+  message: z.string().min(1),
+  noEnter: z.boolean().optional(),
+  dir: z.string().optional(),
+});
+export type SendParams = z.infer<typeof sendParamsSchema>;
+
+/** Server-side cap on a single `wait` — protects the resident process. */
+export const CONTROL_WAIT_MAX_TIMEOUT_MS = 600_000;
+
+const waitTimeoutSchema = z.number().int().positive().max(CONTROL_WAIT_MAX_TIMEOUT_MS).optional();
+
+/** `wait` — block (server-side) until a condition holds. Two kinds, mirroring
+ *  `tmux-ide wait agent-status` and `tmux-ide wait output`. */
+export const waitParamsSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("agent-status"),
+    session: z.string().min(1),
+    status: agentStatusSchema,
+    timeoutMs: waitTimeoutSchema,
+  }),
+  z.object({
+    kind: z.literal("output"),
+    target: z.string().min(1),
+    match: z.string().min(1),
+    timeoutMs: waitTimeoutSchema,
+  }),
+]);
+export type WaitParams = z.infer<typeof waitParamsSchema>;
+
+/** Where a spawned agent lands (mirrors the app's lifecycle placements). */
+export const spawnPlacementSchema = z.enum(["window", "split-h", "split-v"]);
+
+/**
+ * `spawn` — start an agent via the SAME lifecycle argv builders the app uses.
+ * Exactly one of `kind` (a detection-manifest id, resolved to its launch
+ * command) or `command` (verbatim) must be given. With `session` the agent
+ * lands in that live session (`placement`, default a new window; splits need
+ * `paneId`); without it a fresh detached session named `sessionName` is
+ * created in `dir`.
+ */
+export const spawnParamsSchema = z
+  .object({
+    kind: z.string().min(1).optional(),
+    command: z.string().min(1).optional(),
+    session: z.string().min(1).optional(),
+    sessionName: z.string().min(1).optional(),
+    dir: z.string().optional(),
+    placement: spawnPlacementSchema.optional(),
+    paneId: z.string().optional(),
+  })
+  .refine((p) => Boolean(p.kind) !== Boolean(p.command), {
+    message: "exactly one of `kind` or `command` is required",
+  })
+  .refine((p) => Boolean(p.session) || Boolean(p.sessionName), {
+    message: "`session` (spawn into it) or `sessionName` (create it) is required",
+  })
+  .refine((p) => !(p.placement && p.placement !== "window") || Boolean(p.paneId), {
+    message: "split placements need `paneId`",
+  });
+export type SpawnParams = z.infer<typeof spawnParamsSchema>;
+
+/** `restart-agent` — restart the agent in `paneId`, relaunching `command`
+ *  (or `kind`'s launch command). One of the two is required. */
+export const restartAgentParamsSchema = z
+  .object({
+    paneId: z.string().min(1),
+    kind: z.string().min(1).optional(),
+    command: z.string().min(1).optional(),
+  })
+  .refine((p) => Boolean(p.kind) || Boolean(p.command), {
+    message: "`kind` or `command` is required",
+  });
+export type RestartAgentParams = z.infer<typeof restartAgentParamsSchema>;
+
+/** `stop-agent` — interrupt the agent in `paneId` (the pane stays open). */
+export const stopAgentParamsSchema = z.object({
+  paneId: z.string().min(1),
+});
+export type StopAgentParams = z.infer<typeof stopAgentParamsSchema>;
+
+/** `explain` — the detection debugger for one pane (or a session's active pane). */
+export const explainParamsSchema = z.object({
+  target: z.string().min(1),
+});
+export type ExplainParams = z.infer<typeof explainParamsSchema>;
+
+/** `subscribe` — flip this connection into receiving event frames. */
+export const subscribeParamsSchema = z.object({}).loose();
+export type SubscribeParams = z.infer<typeof subscribeParamsSchema>;

package/packages/contracts/src/index.ts

@@ -22,3 +22,4 @@ export * from "./workspace.ts";
 export * from "./actions-contract.ts";
 export * from "./actions-errors.ts";
 export * from "./terminals.ts";
+export * from "./control.ts";

package/packages/daemon/dist/control/client.d.ts

@@ -0,0 +1,23 @@
+import { type ControlEventFrame } from "@tmux-ide/contracts";
+/** A failed verb, carrying the server's machine-readable error code. */
+export declare class ControlRequestError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface ControlClient {
+    /** Send one verb; resolves with the response `data`, rejects with
+     *  {@link ControlRequestError} on an error response or a dropped socket. */
+    request(verb: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Receive pushed event frames (also sends the `subscribe` verb). */
+    subscribe(onEvent: (event: ControlEventFrame) => void): Promise<void>;
+    close(): void;
+    /** Resolves when the connection ends (server shutdown → EOF). */
+    done: Promise<void>;
+}
+/**
+ * Connect to a control server. Rejects (quickly) when nothing is listening —
+ * callers treat that as "no server, fall back to polling".
+ */
+export declare function connectControl(opts?: {
+    socketPath?: string;
+}): Promise<ControlClient>;

package/packages/daemon/dist/control/client.js

@@ -0,0 +1,105 @@
+/**
+ * A minimal control-socket client — what the CLI's `--socket` fast-paths
+ * (`events --follow --socket`, `wait … --socket`) ride on. Connect, send
+ * id-correlated requests, optionally receive pushed event frames. Kept
+ * dependency-light on purpose: this is also the reference for "how would an
+ * agent drive the socket from node" (see skill/SKILL.md).
+ */
+import { connect } from "node:net";
+import { CONTROL_PROTOCOL_VERSION, controlEventSchema, controlResponseSchema, } from "@tmux-ide/contracts";
+import { createFrameSplitter, encodeFrame } from "./frames.js";
+import { defaultControlSocketPath } from "./server.js";
+/** A failed verb, carrying the server's machine-readable error code. */
+export class ControlRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Connect to a control server. Rejects (quickly) when nothing is listening —
+ * callers treat that as "no server, fall back to polling".
+ */
+export function connectControl(opts = {}) {
+    const path = opts.socketPath ?? defaultControlSocketPath();
+    return new Promise((resolve, reject) => {
+        const socket = connect(path);
+        socket.once("error", reject);
+        socket.once("connect", () => {
+            socket.removeListener("error", reject);
+            resolve(wrap(socket));
+        });
+    });
+}
+function wrap(socket) {
+    socket.setEncoding("utf8");
+    const split = createFrameSplitter();
+    const pending = new Map();
+    const eventSinks = [];
+    let nextId = 1;
+    let markDone;
+    const done = new Promise((r) => {
+        markDone = r;
+    });
+    socket.on("data", (chunk) => {
+        for (const line of split(chunk)) {
+            let raw;
+            try {
+                raw = JSON.parse(line);
+            }
+            catch {
+                continue; // a malformed server frame — skip, ids keep us honest
+            }
+            const event = controlEventSchema.safeParse(raw);
+            if (event.success) {
+                for (const sink of eventSinks)
+                    sink(event.data);
+                continue;
+            }
+            const response = controlResponseSchema.safeParse(raw);
+            if (!response.success || response.data.id === null)
+                continue;
+            const waiter = pending.get(response.data.id);
+            if (!waiter)
+                continue;
+            pending.delete(response.data.id);
+            if (response.data.ok)
+                waiter.resolve(response.data.data);
+            else {
+                waiter.reject(new ControlRequestError(response.data.error.code, response.data.error.message));
+            }
+        }
+    });
+    const teardown = () => {
+        for (const { reject } of pending.values()) {
+            reject(new ControlRequestError("disconnected", "control socket closed"));
+        }
+        pending.clear();
+        markDone();
+    };
+    socket.on("close", teardown);
+    socket.on("error", () => {
+        // 'close' follows and runs the teardown
+    });
+    const request = (verb, params) => {
+        const id = nextId++;
+        return new Promise((resolve, reject) => {
+            if (socket.destroyed) {
+                reject(new ControlRequestError("disconnected", "control socket closed"));
+                return;
+            }
+            pending.set(id, { resolve, reject });
+            socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, id, verb, params }));
+        });
+    };
+    return {
+        request,
+        subscribe: async (onEvent) => {
+            eventSinks.push(onEvent);
+            await request("subscribe");
+        },
+        close: () => socket.destroy(),
+        done,
+    };
+}

package/packages/daemon/dist/control/dispatch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Request dispatch for the control socket — PURE given its handler map.
+ *
+ * Takes one raw frame line, parses + validates the versioned envelope,
+ * routes to the verb's handler, and shapes the response envelope — including
+ * every failure mode (unparseable JSON, bad envelope, unknown verb, invalid
+ * params, handler error). Handlers are injected, so this whole layer unit-
+ * tests without a socket or a tmux server.
+ *
+ * Error codes on the wire:
+ *   bad-request    unparseable frame / envelope / params (message says which)
+ *   unknown-verb   the verb isn't in this server's handler map
+ *   not-found      the named pane/session/target doesn't exist
+ *   timeout        a `wait` ran out of time
+ *   internal       the handler threw something unexpected
+ */
+import { type ControlResponse } from "@tmux-ide/contracts";
+/** Thrown by handlers to reach the wire with a specific code. */
+export declare class ControlVerbError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** What a handler gets besides its (already unknown-typed) params. */
+export interface VerbContext {
+    /** Flip this connection into receiving event frames (the `subscribe` verb). */
+    subscribe: () => void;
+}
+export type VerbHandler = (params: unknown, ctx: VerbContext) => Promise<unknown> | unknown;
+/**
+ * Dispatch one raw line to `handlers`. ALWAYS resolves to a response frame —
+ * a protocol error is an answer, never a dropped request or a thrown error
+ * (only the transport decides to drop connections).
+ */
+export declare function dispatchLine(line: string, handlers: Record<string, VerbHandler>, ctx: VerbContext): Promise<ControlResponse>;

package/packages/daemon/dist/control/dispatch.js

@@ -0,0 +1,83 @@
+/**
+ * Request dispatch for the control socket — PURE given its handler map.
+ *
+ * Takes one raw frame line, parses + validates the versioned envelope,
+ * routes to the verb's handler, and shapes the response envelope — including
+ * every failure mode (unparseable JSON, bad envelope, unknown verb, invalid
+ * params, handler error). Handlers are injected, so this whole layer unit-
+ * tests without a socket or a tmux server.
+ *
+ * Error codes on the wire:
+ *   bad-request    unparseable frame / envelope / params (message says which)
+ *   unknown-verb   the verb isn't in this server's handler map
+ *   not-found      the named pane/session/target doesn't exist
+ *   timeout        a `wait` ran out of time
+ *   internal       the handler threw something unexpected
+ */
+import { CONTROL_PROTOCOL_VERSION, controlRequestSchema, } from "@tmux-ide/contracts";
+import { IdeError } from "../lib/errors.js";
+/** Thrown by handlers to reach the wire with a specific code. */
+export class ControlVerbError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const ok = (id, data) => ({
+    v: CONTROL_PROTOCOL_VERSION,
+    id,
+    ok: true,
+    data,
+});
+const fail = (id, code, message) => ({
+    v: CONTROL_PROTOCOL_VERSION,
+    id,
+    ok: false,
+    error: { code, message },
+});
+/** Best-effort id recovery from a frame that failed envelope validation. */
+function extractId(value) {
+    if (typeof value === "object" && value !== null && "id" in value) {
+        const id = value.id;
+        if (typeof id === "string" || typeof id === "number")
+            return id;
+    }
+    return null;
+}
+/**
+ * Dispatch one raw line to `handlers`. ALWAYS resolves to a response frame —
+ * a protocol error is an answer, never a dropped request or a thrown error
+ * (only the transport decides to drop connections).
+ */
+export async function dispatchLine(line, handlers, ctx) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        return fail(null, "bad-request", "frame is not valid JSON");
+    }
+    const parsed = controlRequestSchema.safeParse(raw);
+    if (!parsed.success) {
+        return fail(extractId(raw), "bad-request", `invalid request envelope (need {v:${CONTROL_PROTOCOL_VERSION}, id, verb})`);
+    }
+    const { id, verb, params } = parsed.data;
+    const handler = handlers[verb];
+    if (!handler) {
+        return fail(id, "unknown-verb", `unknown verb "${verb}"`);
+    }
+    try {
+        return ok(id, await handler(params ?? {}, ctx));
+    }
+    catch (err) {
+        if (err instanceof ControlVerbError)
+            return fail(id, err.code, err.message);
+        if (err instanceof IdeError) {
+            // Data-layer errors carry honest codes already (SESSION_NOT_FOUND, …).
+            const code = err.code === "USAGE" ? "bad-request" : "not-found";
+            return fail(id, code, err.message);
+        }
+        return fail(id, "internal", err?.message ?? "internal error");
+    }
+}

package/packages/daemon/dist/control/fanout.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Subscriber fan-out bookkeeping for the control server — PURE.
+ *
+ * Tracks the set of live subscribers and delivers each emitted event to all
+ * of them. The `onFirst`/`onLast` edges let the server run its detection
+ * tick ONLY while someone is listening (0→1 starts it, 1→0 stops it), so an
+ * idle `tmux-ide serve` costs nothing between requests.
+ */
+export interface Fanout<T> {
+    /** Register a sink. Returns its unsubscribe (idempotent). */
+    add(sink: (event: T) => void): () => void;
+    /** Deliver `event` to every sink. A throwing sink is dropped, not fatal. */
+    emit(event: T): void;
+    size(): number;
+}
+export declare function createFanout<T>(edges?: {
+    onFirst?: () => void;
+    onLast?: () => void;
+}): Fanout<T>;

package/packages/daemon/dist/control/fanout.js

@@ -0,0 +1,37 @@
+/**
+ * Subscriber fan-out bookkeeping for the control server — PURE.
+ *
+ * Tracks the set of live subscribers and delivers each emitted event to all
+ * of them. The `onFirst`/`onLast` edges let the server run its detection
+ * tick ONLY while someone is listening (0→1 starts it, 1→0 stops it), so an
+ * idle `tmux-ide serve` costs nothing between requests.
+ */
+export function createFanout(edges = {}) {
+    const sinks = new Set();
+    const remove = (sink) => {
+        if (!sinks.delete(sink))
+            return;
+        if (sinks.size === 0)
+            edges.onLast?.();
+    };
+    return {
+        add(sink) {
+            sinks.add(sink);
+            if (sinks.size === 1)
+                edges.onFirst?.();
+            return () => remove(sink);
+        },
+        emit(event) {
+            for (const sink of [...sinks]) {
+                try {
+                    sink(event);
+                }
+                catch {
+                    // A sink that throws (a torn-down connection) removes itself.
+                    remove(sink);
+                }
+            }
+        },
+        size: () => sinks.size,
+    };
+}