tmux-ide 2.6.1 → 2.8.0

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,
+    };
+}

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

@@ -0,0 +1,23 @@
+/**
+ * NDJSON framing for the control socket — PURE.
+ *
+ * One frame = one JSON object on one `\n`-terminated line. TCP-style streams
+ * deliver arbitrary chunk boundaries, so the splitter buffers a partial
+ * trailing line across feeds and hands back only COMPLETE lines. Encoding is
+ * the trivial inverse; it lives here so every writer produces identical
+ * frames (a `JSON.stringify` can never contain a raw newline, so one write
+ * call per frame is atomic on the wire).
+ */
+/** Refuse to buffer a partial line beyond this — a client streaming an
+ *  unterminated megabyte is broken or hostile, not slow. */
+export declare const MAX_FRAME_BYTES: number;
+/** Serialize one frame: the JSON line plus its terminator. */
+export declare function encodeFrame(message: unknown): string;
+/**
+ * A stateful chunk → complete-lines splitter. Feed it raw socket data; it
+ * returns every COMPLETE line received so far (blank lines are dropped) and
+ * keeps the trailing partial line buffered for the next feed. Throws when the
+ * partial line outgrows {@link MAX_FRAME_BYTES} — the caller should drop the
+ * connection.
+ */
+export declare function createFrameSplitter(): (chunk: string) => string[];

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

@@ -0,0 +1,37 @@
+/**
+ * NDJSON framing for the control socket — PURE.
+ *
+ * One frame = one JSON object on one `\n`-terminated line. TCP-style streams
+ * deliver arbitrary chunk boundaries, so the splitter buffers a partial
+ * trailing line across feeds and hands back only COMPLETE lines. Encoding is
+ * the trivial inverse; it lives here so every writer produces identical
+ * frames (a `JSON.stringify` can never contain a raw newline, so one write
+ * call per frame is atomic on the wire).
+ */
+/** Refuse to buffer a partial line beyond this — a client streaming an
+ *  unterminated megabyte is broken or hostile, not slow. */
+export const MAX_FRAME_BYTES = 4 * 1024 * 1024;
+/** Serialize one frame: the JSON line plus its terminator. */
+export function encodeFrame(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+/**
+ * A stateful chunk → complete-lines splitter. Feed it raw socket data; it
+ * returns every COMPLETE line received so far (blank lines are dropped) and
+ * keeps the trailing partial line buffered for the next feed. Throws when the
+ * partial line outgrows {@link MAX_FRAME_BYTES} — the caller should drop the
+ * connection.
+ */
+export function createFrameSplitter() {
+    let buffer = "";
+    return (chunk) => {
+        buffer += chunk;
+        const parts = buffer.split("\n");
+        buffer = parts.pop() ?? "";
+        if (buffer.length > MAX_FRAME_BYTES) {
+            buffer = "";
+            throw new Error(`frame exceeds ${MAX_FRAME_BYTES} bytes without a newline`);
+        }
+        return parts.filter((line) => line.trim().length > 0);
+    };
+}

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

@@ -0,0 +1,45 @@
+import { type SpawnPlacement } from "../tui/mirror/agent-lifecycle.ts";
+/** Resolve `kind`/`command` params to the command that actually launches. */
+export declare function resolveLaunchCommand(params: {
+    kind?: string;
+    command?: string;
+}): string;
+export interface SpawnOutcome {
+    paneId: string;
+    session: string;
+    command: string;
+    placement: SpawnPlacement | "new-session";
+}
+/**
+ * Spawn an agent. With `session` the shared placement argv is used (window /
+ * split); without it a fresh detached session named `sessionName` starts in
+ * `dir`. `-P -F #{pane_id}` is threaded right after the tmux subcommand so
+ * the caller learns WHICH pane the agent got (the argv builders stay
+ * untouched — the app's flows don't want the print).
+ */
+export declare function spawnAgent(params: {
+    command: string;
+    session?: string;
+    sessionName?: string;
+    dir?: string;
+    placement?: SpawnPlacement;
+    paneId?: string;
+}): Promise<SpawnOutcome>;
+/** Stop the agent in `paneId`: interrupt + authority cleanup. The pane (and
+ *  its shell, if any) stays open — `kill-pane` is deliberately NOT offered
+ *  over the socket; that is a human, confirmed-destructive verb. */
+export declare function stopAgent(paneId: string): Promise<{
+    paneId: string;
+    stopped: true;
+}>;
+/**
+ * Restart the agent in `paneId` running `command`, using the app's two
+ * strategies: a SHELL-hosted agent is interrupted and relaunched via
+ * send-keys (the shell survives to type into); an agent that IS the pane's
+ * own process is respawned in place (ctrl-c would end the pane).
+ */
+export declare function restartAgent(paneId: string, command: string): Promise<{
+    paneId: string;
+    command: string;
+    strategy: "relaunch" | "respawn";
+}>;

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

@@ -0,0 +1,114 @@
+/**
+ * Agent lifecycle io for the control socket — spawn / restart / stop.
+ *
+ * The MODEL (kind → launch command, exact tmux argv, the shell-vs-own-process
+ * restart decision, interrupt timing) is the pure `tui/mirror/agent-lifecycle`
+ * module the unified app already runs on; this file is only the async tmux
+ * plumbing around it, so the socket drives the SAME lifecycle path as the app.
+ */
+import { execFile } from "node:child_process";
+import { INTERRUPT_TAP_GAP_MS, RESTART_GRACE_MS, clearAuthorityArgs, interruptArgs, launchCommandFor, paneHostsShell, relaunchArgs, respawnArgs, spawnAgentArgs, spawnSessionArgs, } from "../tui/mirror/agent-lifecycle.js";
+import { getManifests } from "../tui/detect/manifest-loader.js";
+import { ControlVerbError } from "./dispatch.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** One tmux call; resolves stdout, rejects on a tmux error. */
+function tmuxRun(args) {
+    return new Promise((resolve, reject) => {
+        execFile("tmux", args, (err, stdout) => (err ? reject(err) : resolve(stdout.trimEnd())));
+    });
+}
+/** Like {@link tmuxRun} but errors are swallowed — for best-effort steps
+ *  (a dead pane target is a normal race, the fleet shows the truth later). */
+async function tmuxTry(args) {
+    await tmuxRun(args).catch(() => { });
+}
+/** Resolve `kind`/`command` params to the command that actually launches. */
+export function resolveLaunchCommand(params) {
+    if (params.command)
+        return params.command;
+    return launchCommandFor(params.kind, getManifests());
+}
+/**
+ * Spawn an agent. With `session` the shared placement argv is used (window /
+ * split); without it a fresh detached session named `sessionName` starts in
+ * `dir`. `-P -F #{pane_id}` is threaded right after the tmux subcommand so
+ * the caller learns WHICH pane the agent got (the argv builders stay
+ * untouched — the app's flows don't want the print).
+ */
+export async function spawnAgent(params) {
+    const dir = params.dir ?? null;
+    const argv = params.session
+        ? spawnAgentArgs(params.placement ?? "window", { session: params.session, paneId: params.paneId }, dir, params.command)
+        : spawnSessionArgs(params.sessionName, dir, params.command);
+    const [subcommand, ...rest] = argv;
+    let paneId;
+    try {
+        paneId = await tmuxRun([subcommand, "-P", "-F", "#{pane_id}", ...rest]);
+    }
+    catch (err) {
+        throw new ControlVerbError("not-found", `tmux refused to spawn: ${err.message}`);
+    }
+    const session = params.session ?? params.sessionName;
+    // Mark a fresh session as ours (mirrors the app's spawn flow).
+    if (!params.session)
+        await tmuxTry(["set-environment", "-t", session, "TMUX_IDE", "1"]);
+    return {
+        paneId,
+        session,
+        command: params.command,
+        placement: params.session ? (params.placement ?? "window") : "new-session",
+    };
+}
+/** The double ctrl-c (see agent-lifecycle: one taps, the quick second exits). */
+async function interruptAgent(paneId) {
+    await tmuxTry(interruptArgs(paneId));
+    await sleep(INTERRUPT_TAP_GAP_MS);
+    await tmuxTry(interruptArgs(paneId));
+}
+/** Out-of-band stop hygiene: no hook fires, so unset the authority stamps. */
+async function clearAgentAuthority(paneId) {
+    for (const args of clearAuthorityArgs(paneId))
+        await tmuxTry(args);
+}
+/** The pane's root command + cwd, or null when the pane is gone. */
+function paneStartAndPath(paneId) {
+    return tmuxRun(["display", "-p", "-t", paneId, "#{pane_start_command}\t#{pane_current_path}"])
+        .then((out) => {
+        const [start = "", path = ""] = out.split("\t");
+        return { start, path };
+    })
+        .catch(() => null);
+}
+/** Stop the agent in `paneId`: interrupt + authority cleanup. The pane (and
+ *  its shell, if any) stays open — `kill-pane` is deliberately NOT offered
+ *  over the socket; that is a human, confirmed-destructive verb. */
+export async function stopAgent(paneId) {
+    const live = await paneStartAndPath(paneId);
+    if (!live)
+        throw new ControlVerbError("not-found", `no pane "${paneId}"`);
+    await interruptAgent(paneId);
+    await clearAgentAuthority(paneId);
+    return { paneId, stopped: true };
+}
+/**
+ * Restart the agent in `paneId` running `command`, using the app's two
+ * strategies: a SHELL-hosted agent is interrupted and relaunched via
+ * send-keys (the shell survives to type into); an agent that IS the pane's
+ * own process is respawned in place (ctrl-c would end the pane).
+ */
+export async function restartAgent(paneId, command) {
+    const live = await paneStartAndPath(paneId);
+    if (!live)
+        throw new ControlVerbError("not-found", `no pane "${paneId}"`);
+    if (paneHostsShell(live.start, getManifests())) {
+        await interruptAgent(paneId);
+        await clearAgentAuthority(paneId);
+        await sleep(RESTART_GRACE_MS);
+        for (const args of relaunchArgs(paneId, command))
+            await tmuxTry(args);
+        return { paneId, command, strategy: "relaunch" };
+    }
+    await clearAgentAuthority(paneId);
+    await tmuxTry(respawnArgs(paneId, command, live.path || null));
+    return { paneId, command, strategy: "respawn" };
+}

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

@@ -0,0 +1,16 @@
+/** The default socket path — under the state home so `TMUX_IDE_HOME` scopes
+ *  tests away from the real user socket. */
+export declare function defaultControlSocketPath(): string;
+export interface ControlServerOptions {
+    socketPath?: string;
+    /** Diagnostics sink (the CLI passes stderr). Default: silent. */
+    log?: (message: string) => void;
+    /** Event-tick cadence override (tests); defaults to the updater's TICK_MS. */
+    tickMs?: number;
+}
+export interface ControlServer {
+    socketPath: string;
+    close(): Promise<void>;
+}
+/** Start the server. Resolves once the socket is listening (mode 0600). */
+export declare function startControlServer(opts?: ControlServerOptions): Promise<ControlServer>;

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

@@ -0,0 +1,214 @@
+/**
+ * The control-socket server — `tmux-ide serve` (M23.3).
+ *
+ * NDJSON frames over a local Unix socket (default `~/.tmux-ide/control.sock`,
+ * mode 0600). Agent loops connect once and drive the fleet — request/response
+ * verbs plus PUSHED agent-status events after `subscribe` — instead of
+ * spawning a CLI process per call. Protocol schemas live in
+ * `@tmux-ide/contracts` (control.ts); verb handlers in `./verbs.ts` call the
+ * SAME data layer the CLI cases do.
+ *
+ * HOST DECISION (the tradeoff, considered before building):
+ *   (a) `tmux-ide serve` — an EXPLICIT foreground process. Costs the user a
+ *       deliberate start, dies with them, trivially restartable after a code
+ *       change, and its lifetime states its purpose.
+ *   (b) piggyback on the `_tmux-ide-chrome` updater tick — always running for
+ *       adopted fleets, but chrome-lifecycle-coupled: unadopting the last
+ *       session would kill the API mid-conversation, `adopt` would grow a
+ *       network-ish responsibility, and the updater's contract ("never let a
+ *       bad tick break the bars") is the wrong place for a protocol surface.
+ *   (c) socket-activated per-connection handlers — zero resident cost, but
+ *       every connection pays a full node boot (the latency the socket exists
+ *       to remove) and no resident process means no push events and no
+ *       persistent status tracker (the cross-tick `done` needs history).
+ *   CHOSEN: (a), deliberately WITHOUT auto-start. The old command-center HTTP
+ *   server is the cautionary tale: an implicitly-running daemon accretes
+ *   scope. This surface stays minimal — session-control verbs only, no feed,
+ *   no chat, no network listener — and the CLI only uses the socket
+ *   OPPORTUNISTICALLY (`--socket` fast-paths fall back to polling when no
+ *   server is up). An agent that wants the socket runs `tmux-ide serve`
+ *   itself; the process it spawned is the process it owns.
+ *
+ * SECURITY: local user only. The socket is chmod 0600, there is no network
+ * transport, no tokens (filesystem permissions ARE the auth). The #90 bridge
+ * that exposes this to a native app layers a WS server ON TOP later — each
+ * NDJSON frame maps 1:1 to a WS text message, so that bridge is mechanical
+ * and this file never grows remote scope.
+ *
+ * EVENTS: while at least one connection is subscribed, a detection tick
+ * (same cadence and diff as the chrome updater, one persistent tracker)
+ * computes the fleet and pushes session-level status transitions. No
+ * subscribers → no tick → an idle server does nothing. The tick does NOT
+ * write events.jsonl — the chrome updater owns the log; this stream is
+ * transport, not history.
+ */
+import { chmodSync, existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
+import { createServer, connect } from "node:net";
+import { dirname, join } from "node:path";
+import { CONTROL_PROTOCOL_VERSION } from "@tmux-ide/contracts";
+import { IdeError } from "../lib/errors.js";
+import { tuiStateHome } from "../lib/tui-binary.js";
+import { createStatusTracker } from "../tui/detect/classify.js";
+import { diffFleet } from "../tui/chrome/events.js";
+import { fleetStatuses, TICK_MS } from "../tui/chrome/updater.js";
+import { listTeamProjects } from "../tui/team/projects.js";
+import { dispatchLine } from "./dispatch.js";
+import { createFanout } from "./fanout.js";
+import { createFrameSplitter, encodeFrame } from "./frames.js";
+import { createVerbHandlers } from "./verbs.js";
+/** The default socket path — under the state home so `TMUX_IDE_HOME` scopes
+ *  tests away from the real user socket. */
+export function defaultControlSocketPath() {
+    return join(tuiStateHome(), "control.sock");
+}
+/**
+ * Claim `path`: refuse anything that exists and is not a socket (NEVER
+ * unlink a foreign file), refuse a socket another live server answers on,
+ * and unlink a stale socket left by a dead server.
+ */
+async function claimSocketPath(path) {
+    if (!existsSync(path))
+        return;
+    if (!statSync(path).isSocket()) {
+        throw new IdeError(`${path} exists and is not a socket — refusing to remove it. ` +
+            `Pass a different --socket path.`, { code: "USAGE", exitCode: 1 });
+    }
+    const alive = await new Promise((resolve) => {
+        const probe = connect(path);
+        const done = (result) => {
+            probe.destroy();
+            resolve(result);
+        };
+        probe.once("connect", () => done(true));
+        probe.once("error", () => done(false));
+        probe.setTimeout(500, () => done(false));
+    });
+    if (alive) {
+        throw new IdeError(`another server is already listening on ${path}`, {
+            code: "USAGE",
+            exitCode: 1,
+        });
+    }
+    unlinkSync(path); // stale socket from a dead server — safe to rebind
+}
+/** Start the server. Resolves once the socket is listening (mode 0600). */
+export async function startControlServer(opts = {}) {
+    const socketPath = opts.socketPath ?? defaultControlSocketPath();
+    const log = opts.log ?? (() => { });
+    const tickMs = opts.tickMs ?? TICK_MS;
+    mkdirSync(dirname(socketPath), { recursive: true });
+    await claimSocketPath(socketPath);
+    // ONE tracker for the server's lifetime, shared by the verbs and the event
+    // tick — cross-tick `done` (working→idle) is only observable with history.
+    const tracker = createStatusTracker();
+    const handlers = createVerbHandlers({ tracker });
+    // The event tick: runs ONLY while subscribers exist (fanout edges), diffs
+    // the fleet exactly like the chrome updater, pushes transitions.
+    const prevState = new Map();
+    let timer = null;
+    const tick = () => {
+        try {
+            const { events, state } = diffFleet(prevState, fleetStatuses(listTeamProjects(tracker)));
+            prevState.clear();
+            for (const [name, status] of state)
+                prevState.set(name, status);
+            const ts = new Date().toISOString();
+            for (const ev of events)
+                fanout.emit({ ts, ...ev });
+        }
+        catch (err) {
+            log(`event tick failed: ${err.message}`);
+        }
+    };
+    const fanout = createFanout({
+        onFirst: () => {
+            tick(); // seed immediately — the first events carry the current fleet (from: null)
+            timer = setInterval(tick, tickMs);
+        },
+        onLast: () => {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            prevState.clear();
+        },
+    });
+    const connections = new Set();
+    const server = createServer((conn) => {
+        connections.add(conn);
+        conn.setEncoding("utf8");
+        const split = createFrameSplitter();
+        let unsubscribe = null;
+        const push = (ev) => {
+            // One write per frame — JSON.stringify never contains a raw newline,
+            // so frames from concurrent requests can never interleave mid-message.
+            conn.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, event: "agent-status", data: ev }));
+        };
+        const ctx = {
+            subscribe: () => {
+                unsubscribe ??= fanout.add(push);
+            },
+        };
+        conn.on("data", (chunk) => {
+            let lines;
+            try {
+                lines = split(chunk);
+            }
+            catch {
+                conn.destroy(); // frame overflow — a broken client, not a slow one
+                return;
+            }
+            for (const line of lines) {
+                // Handled CONCURRENTLY: a long `wait` must not block this
+                // connection's other requests (responses correlate by id).
+                void dispatchLine(line, handlers, ctx).then((response) => {
+                    if (!conn.destroyed)
+                        conn.write(encodeFrame(response));
+                });
+            }
+        });
+        conn.on("close", () => {
+            unsubscribe?.();
+            connections.delete(conn);
+        });
+        conn.on("error", () => {
+            // close follows; nothing to do — never let a client error kill serve
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", (err) => {
+            // Unix sockets cap the path at ~104 bytes (macOS sun_path) — surfaced
+            // as a bare EINVAL. Say what actually went wrong and how to fix it.
+            if ((err.code === "EINVAL" || err.code === "ENAMETOOLONG") && socketPath.length > 100) {
+                reject(new IdeError(`socket path is too long for a Unix socket (${socketPath.length} chars; the OS caps it around 104): ${socketPath}\n` +
+                    `Pass a shorter path: tmux-ide serve --socket /tmp/tmux-ide-control.sock`, { code: "USAGE", exitCode: 1 }));
+                return;
+            }
+            reject(err);
+        });
+        server.listen(socketPath, () => {
+            server.removeAllListeners("error");
+            resolve();
+        });
+    });
+    chmodSync(socketPath, 0o600);
+    log(`listening on ${socketPath}`);
+    return {
+        socketPath,
+        close: () => new Promise((resolve) => {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            for (const conn of connections)
+                conn.destroy(); // clients see EOF
+            server.close(() => {
+                try {
+                    unlinkSync(socketPath);
+                }
+                catch {
+                    // already gone
+                }
+                resolve();
+            });
+        }),
+    };
+}

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

@@ -0,0 +1,11 @@
+import type { StatusTracker } from "../tui/detect/classify.ts";
+import { type VerbHandler } from "./dispatch.ts";
+/**
+ * Build the handler map. `tracker` is the server's ONE persistent status
+ * tracker (shared with the event tick) so `fleet`/`agents` see the
+ * cross-tick `done` transition exactly like the chrome updater does —
+ * a fresh tracker per call could never observe working→idle.
+ */
+export declare function createVerbHandlers(ctx: {
+    tracker: StatusTracker;
+}): Record<string, VerbHandler>;