@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/ipc-server.js

@@ -0,0 +1,429 @@
+/**
+ * IPC server for the CELLO daemon.
+ *
+ * Pseudocode:
+ * 1. createIpcServer(config, handlers):
+ *    a. Create net.Server bound to Unix domain socket
+ *    b. Set socket permissions to 0o600 (SI-001: owner-only access)
+ *    c. On connection:
+ *       - Check connectionCount < maxConnections (16)
+ *       - If limit reached, send error frame and close
+ *       - Otherwise, increment counter, assign connectionId
+ *       - Log daemon.ipc.connected
+ *       - Set up newline-delimited JSON parser on the socket
+ *       - For each parsed request, dispatch to handler map
+ *       - On close, decrement counter, log daemon.ipc.disconnected
+ *    d. Return server handle with start() and stop() methods
+ *
+ * 2. IPC framing: JSON-newline-delimited
+ *    - Each message is a single JSON object followed by \n
+ *    - Requests: {id: string, method: string, params?: object}
+ *    - Responses: {id: string, result: any} or {id: string, error: {code, message, guidance}}
+ *
+ * 3. Graceful shutdown:
+ *    a. Stop accepting new connections
+ *    b. Wait for in-flight requests to complete (with timeout)
+ *    c. Send shutdown frame to all connected clients
+ *    d. Close all connections
+ *    e. Unlink socket file
+ */
+import { createServer } from "node:net";
+import { chmod, stat, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { extractErrorMessage } from "./error-message.js";
+import { DOCUMENTS_FLAG_ENV } from "./document-flag.js";
+import { isDocumentVerbName } from "./vocabulary.js";
+export function createIpcServer(config, 
+/**
+ * Looked up per request, never enumerated. Typed as the lookup alone so the daemon can pass a
+ * LATE-BINDING view over its handler map rather than a snapshot — a snapshot made registration
+ * order load-bearing, and anything registered after the copy answered `method_not_found`.
+ */
+handlers) {
+    const { socketPath, maxConnections, logger } = config;
+    let server = null;
+    const connections = new Map();
+    let stopping = false;
+    // DOD-DAEMON-CLEANUP-1 (AC2): the identity — not the path — of the socket THIS server created.
+    // dev+ino is the only thing that survives another daemon rebinding the same path.
+    let createdSocket = null;
+    /**
+     * What is sitting at socketPath right now?
+     *   "ours"    — the socket this server created; we may remove it.
+     *   "gone"    — nothing there; nothing to do.
+     *   "foreign" — a DIFFERENT socket. Another daemon rebound the path. Hands off.
+     *
+     * The distinction is by inode, not by path. A path tells you a file exists; only the inode tells
+     * you it is the same file you made.
+     */
+    async function socketOwnership() {
+        let current;
+        try {
+            current = await stat(socketPath);
+        }
+        catch {
+            // Nothing at the path (ENOENT is the only realistic case) — there is nothing to own.
+            return "gone";
+        }
+        if (createdSocket === null) {
+            // Unreachable: stop() returns early unless the server is listening, and a listening server has
+            // been through start(), which sets this or throws. Say so rather than inventing an answer —
+            // guessing here is what the whole unit is about.
+            throw new Error("ipc server: socket identity unknown — stop() ran without a completed start()");
+        }
+        return current.dev === createdSocket.dev && current.ino === createdSocket.ino ? "ours" : "foreign";
+    }
+    let disconnectHandler = null;
+    function handleConnection(socket) {
+        if (stopping) {
+            socket.destroy();
+            return;
+        }
+        if (connections.size >= maxConnections) {
+            logger.warn("daemon.ipc.connection.limit.reached", {
+                currentCount: connections.size,
+                maxCount: maxConnections,
+            });
+            // Destroy immediately — the client has no pending requests to correlate
+            // an error response against. Client's connectToDaemon() will reject with
+            // a socket error, which is the correct signal.
+            socket.destroy();
+            return;
+        }
+        const connectionId = randomUUID();
+        const conn = { id: connectionId, socket, inFlightCount: 0, shutdownReason: null };
+        connections.set(connectionId, conn);
+        logger.info("daemon.ipc.accepted", { connectionId });
+        // CELLO-M7-MSG-001: the IPC buffer cap MUST exceed the application content cap
+        // (MAX_CONTENT_BYTES = 1 MB) plus the JSON request envelope, or a max-size
+        // cello_send message would trip this overflow and the connection would be killed
+        // BEFORE cello_send's content_too_large check could run — turning a clean,
+        // recoverable "content_too_large" into a fatal connection drop, and making even a
+        // VALID 1 MB message unsendable. 4 MB matches the it-length-prefixed transport
+        // default (IT_LENGTH_PREFIX_DEFAULT_MAX) so the IPC, app-cap, and transport layers
+        // are coherent: content up to the 1 MB cap always traverses IPC, oversize content
+        // reaches cello_send and is rejected with content_too_large, and only a payload
+        // beyond the transport frame is a hard stop. Must stay in sync with the matching
+        // constant in adapter-claude-code/src/ipc-proxy.ts.
+        const MAX_BUFFER_SIZE = 4 * 1024 * 1024; // 4MB per connection (> 1MB content cap + envelope)
+        let buffer = "";
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString("utf-8");
+            if (buffer.length > MAX_BUFFER_SIZE) {
+                logger.warn("daemon.ipc.buffer.overflow", { connectionId, bufferSize: buffer.length });
+                buffer = "";
+                socket.removeAllListeners("data");
+                socket.destroy();
+                return;
+            }
+            let newlineIdx;
+            while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                const line = buffer.slice(0, newlineIdx);
+                buffer = buffer.slice(newlineIdx + 1);
+                if (line.trim().length === 0)
+                    continue;
+                handleMessage(conn, line);
+            }
+        });
+        socket.on("close", () => {
+            connections.delete(connectionId);
+            const reason = conn.shutdownReason || "client_closed";
+            /**
+             * ONE LINE, and the handler contributes to it — review F8.
+             *
+             * `DOD-M15-IPCVISIBLE-1` added a SECOND `daemon.ipc.disconnected` from the daemon's own
+             * handler, carrying clientType and the attended agent. Two lines under one event name, with
+             * disjoint fields and neither carrying the whole picture — and a naive count doubled, so a
+             * shutdown with five clients emitted ten. For a unit whose entire subject is that the log is
+             * readable, that is the wrong shape.
+             *
+             * The handler now RETURNS its context and it is merged here. `reason` lives on this side
+             * because only the socket knows it.
+             */
+            const extra = disconnectHandler ? disconnectHandler(connectionId) : undefined;
+            logger.info("daemon.ipc.disconnected", { connectionId, reason, ...(extra ?? {}) });
+        });
+        // Set shutdownReason so the 'close' handler (which always fires after 'error') logs it.
+        // Do NOT call disconnectHandler or log here — 'close' fires immediately after 'error'.
+        socket.on("error", (err) => {
+            conn.shutdownReason = err.message;
+        });
+    }
+    function handleMessage(conn, line) {
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            // Cannot recover the request ID from unparseable input.
+            // Close the connection — client's pending promises will all reject
+            // with "Connection closed", which correctly propagates the failure.
+            logger.warn("daemon.ipc.parse.error", { connectionId: conn.id });
+            conn.socket.destroy();
+            return;
+        }
+        if (!request.id || !request.method) {
+            // If id is missing/falsy, we can't correlate an error response.
+            // Close the connection rather than sending an unmatchable frame.
+            logger.warn("daemon.ipc.invalid.request", { connectionId: conn.id, hasId: !!request.id, hasMethod: !!request.method });
+            conn.socket.destroy();
+            return;
+        }
+        const handler = handlers.get(request.method);
+        if (!handler) {
+            /**
+             * ⚠️ A GATED DOCUMENT VERB IS NOT A VERSION SKEW, AND THE DEFAULT GUIDANCE SAYS IT IS.
+             *
+             * 074-DOCSFLAG gates the document layer off by default, so the fourteen `cello_doc_*` verbs are
+             * genuinely absent from this map — which is the point. But the guidance below names the wrong
+             * subsystem: it sends the operator to check that the shim and the daemon are the same version,
+             * for a flag that is off by design.
+             *
+             * **This is reachable in ordinary operation, not a corner.** The shim and the daemon are
+             * separate processes with separate environments — the MCP client spawns one, `cello login`
+             * starts the other — so a shim whose environment HAS the flag advertises fourteen tools against
+             * a daemon whose environment does not. An operator running an older `@cello-protocol/connect`
+             * reaches the same place. Either way the only statement of the truth is a
+             * `document.layer.gated` line written at boot, minutes or days earlier.
+             *
+             * So the cause is named where it surfaces, and nothing is registered to do it: this is the same
+             * `method_not_found` refusal with the right reason attached, so the enumerated verb count is
+             * unchanged and no gated verb becomes answerable.
+             */
+            // Asked of the vocabulary rather than matched against a prefix here: a bare `cello_doc_`
+            // literal in this file is a dead tool name to the source audit, and it is right to say so.
+            //
+            // ⚠️ NO `!documentsEnabled()` HERE, AND IT USED TO BE — review found it adds nothing and can only
+            // be wrong. Reaching this branch means the handler map has no entry for the method; when documents
+            // are ON all fourteen are registered, so a MISS on a document verb can only mean the gate was
+            // closed when that map was built. Worse, the map is built once at boot while an env read is live,
+            // so a process whose environment gains the flag afterwards would answer a genuinely gated verb
+            // with the version-skew guidance again — the exact defect this branch exists to remove.
+            const gatedDocumentVerb = isDocumentVerbName(request.method);
+            const errorResp = {
+                id: request.id,
+                error: {
+                    code: "method_not_found",
+                    message: gatedDocumentVerb
+                        ? `Unknown method: ${request.method} — collaborative documents are disabled on this daemon`
+                        : `Unknown method: ${request.method}`,
+                    guidance: gatedDocumentVerb
+                        ? `Collaborative documents are turned OFF on this daemon, so '${request.method}' is not ` +
+                            `registered. This is deliberate: the layer is paused while the base protocol is ` +
+                            `finished. To turn it on, set ${DOCUMENTS_FLAG_ENV}=1 in the environment that starts ` +
+                            `the daemon AND in the environment that starts cello-mcp, then restart both — the two ` +
+                            `are separate processes and setting it in only one leaves the tool advertised and ` +
+                            `unanswerable. Otherwise, stop using the document tools and say documents are disabled.`
+                        : `Unknown IPC method '${request.method}'. Check that cello-mcp and the daemon are the same version. Run 'cello status' to verify the daemon is running.`,
+                },
+            };
+            if (gatedDocumentVerb) {
+                // The log keeps the forensic half: the response is the control, and both are required.
+                logger.warn("document.verb.refused", {
+                    connectionId: conn.id,
+                    method: request.method,
+                    reason: "documents_disabled",
+                    consequence: "a document tool was called against a daemon that does not register one",
+                    remedy: `set ${DOCUMENTS_FLAG_ENV}=1 for BOTH the daemon and cello-mcp, or stop calling document verbs`,
+                });
+            }
+            conn.socket.write(JSON.stringify(errorResp) + "\n");
+            return;
+        }
+        conn.inFlightCount++;
+        Promise.resolve(handler(request.params, conn.id))
+            .then((result) => {
+            try {
+                // `DOD-M15-SELECTION-1`'s fallback notice used to be spread in HERE. It moved up into the
+                // daemon's `renderedHandlers` wrapper: this point is downstream of `renderForSurface`, so
+                // the notice's own guidance never got translated and a CLI operator was told to run
+                // `cello_use_agent`, which is not a command. It also sits outside the request's async
+                // context, which is what let a notice ride a concurrent call's response.
+                const resp = { id: request.id, result };
+                conn.socket.write(JSON.stringify(resp) + "\n");
+            }
+            catch {
+                // Socket closed before response could be written
+            }
+        })
+            .catch((err) => {
+            // extractErrorMessage, NOT String(err): handlers reject with structured plain objects as
+            // well as Errors, and String() on a plain object yields the literal "[object Object]" —
+            // the cause is destroyed at the point of reporting. The SAME extracted text goes to the
+            // log, so a failure is diagnosable from the daemon log alone; the response's guidance
+            // sends the reader there and is only true because of this log line.
+            const message = extractErrorMessage(err);
+            // `reason` alongside the message, because extractErrorMessage returns only the prose and
+            // the transport's structured throws carry the discriminator separately — `no_connection`
+            // vs `connection_lost` is what decides whether re-dialling can help (transport node.ts).
+            // Dropping it here would leave the log the guidance points at unable to answer the first
+            // question its reader has.
+            const reason = err && typeof err === "object" && !(err instanceof Error)
+                && typeof err.reason === "string"
+                ? err.reason
+                : undefined;
+            logger.error("daemon.ipc.request.failed", {
+                connectionId: conn.id,
+                method: request.method,
+                requestId: request.id,
+                error: message,
+                ...(reason !== undefined ? { reason } : {}),
+            });
+            try {
+                const resp = {
+                    id: request.id,
+                    error: {
+                        code: "internal_error",
+                        message,
+                        guidance: "An unexpected error occurred. Check daemon logs for details.",
+                    },
+                };
+                conn.socket.write(JSON.stringify(resp) + "\n");
+            }
+            catch {
+                // Socket closed before error could be written
+            }
+        })
+            .finally(() => {
+            conn.inFlightCount--;
+        });
+    }
+    return {
+        async start() {
+            // Remove stale socket file if it exists
+            try {
+                await unlink(socketPath);
+            }
+            catch (err) {
+                if (err.code !== "ENOENT") {
+                    throw err;
+                }
+            }
+            server = createServer(handleConnection);
+            await new Promise((resolve, reject) => {
+                server.on("error", (err) => {
+                    reject(err);
+                });
+                server.listen(socketPath, () => {
+                    resolve();
+                });
+            });
+            // SI-001: Set socket permissions to owner-only
+            await chmod(socketPath, 0o600);
+            // DOD-DAEMON-CLEANUP-1 (AC2): remember WHICH socket we created, by identity — not merely that
+            // a file exists at this path. If another daemon later rebinds the path, its listen() replaces
+            // the file with a different inode, and stop() must be able to tell the two apart so it does not
+            // unlink a socket it does not own.
+            //
+            // No fallback here, deliberately. Swallowing this stat and leaving the identity unknown would
+            // make stop() treat our OWN socket as foreign: it would then never close the server, so the
+            // daemon would go on accepting IPC connections into a torn-down handler stack after stop()
+            // returned, and would leave its socket behind. A daemon that cannot identify the socket it just
+            // bound has no business coming up — and startup failure is already handled cleanly.
+            const created = await stat(socketPath);
+            createdSocket = { dev: created.dev, ino: created.ino };
+        },
+        async stop() {
+            stopping = true;
+            if (!server)
+                return;
+            // Wait for in-flight requests to complete (max 5 seconds)
+            const deadline = Date.now() + 5000;
+            let totalInFlight = 0;
+            while (Date.now() < deadline) {
+                totalInFlight = 0;
+                for (const conn of connections.values()) {
+                    totalInFlight += conn.inFlightCount;
+                }
+                if (totalInFlight === 0)
+                    break;
+                await new Promise((r) => setTimeout(r, 50));
+            }
+            if (totalInFlight > 0) {
+                logger.warn("daemon.ipc.shutdown.timeout", { abandonedRequests: totalInFlight });
+            }
+            // Send shutdown notification to all connected clients.
+            // Uses IpcNotification shape — distinct from IpcResponse so clients
+            // never confuse it with a response to their request.
+            const shutdownNotification = { notification: "shutdown" };
+            const shutdownFrame = JSON.stringify(shutdownNotification) + "\n";
+            for (const conn of connections.values()) {
+                try {
+                    conn.shutdownReason = "daemon_shutdown";
+                    conn.socket.write(shutdownFrame);
+                    conn.socket.end();
+                }
+                catch {
+                    // Connection may already be closed
+                }
+            }
+            // DOD-DAEMON-CLEANUP-1 (AC2): decide ownership BEFORE closing, because close() is itself a
+            // blind unlink.
+            //
+            // Node's server.close() removes the unix socket path it bound — by PATH, with no check on what
+            // is actually there now. If another daemon has since rebound this path, closing our server
+            // deletes THEIR socket, and they are left alive, serving, and unreachable. Guarding our own
+            // explicit unlink is not enough; the close would already have done the damage.
+            const ownership = await socketOwnership();
+            if (ownership === "foreign") {
+                // We must not close: that would unlink the healthy daemon's socket out from under it. Drop
+                // the handle from the event loop instead and let process exit reclaim the fd. The listening
+                // socket is already inert — its path was taken from it, so nothing can reach it. Leaking an
+                // unreachable fd for the last moments of a dying process is a trade we make happily against
+                // disarming a live peer.
+                logger.info("daemon.ipc.socket.not_ours", { socketPath, ourIno: createdSocket?.ino ?? null });
+                server.unref();
+            }
+            else {
+                await new Promise((resolve) => {
+                    server.close(() => resolve());
+                });
+                // close() normally unlinks the path for us. Re-check rather than assume: only remove the file
+                // if it is STILL the socket we created. Between the close and here, the singleton lock is
+                // still held (the daemon releases it after this returns), so no successor can have bound the
+                // path — but the cost of re-checking is one stat, and the cost of being wrong is the bug this
+                // whole unit exists to kill.
+                if (await socketOwnership() === "ours") {
+                    try {
+                        await unlink(socketPath);
+                    }
+                    catch (err) {
+                        if (err.code !== "ENOENT") {
+                            logger.warn("daemon.ipc.socket.unlink.failed", {
+                                socketPath,
+                                error: extractErrorMessage(err),
+                            });
+                        }
+                    }
+                }
+            }
+            server = null;
+        },
+        getConnectionCount() {
+            return connections.size;
+        },
+        onDisconnect(handler) {
+            disconnectHandler = handler;
+        },
+        sendNotification(connectionId, notification) {
+            const conn = connections.get(connectionId);
+            if (!conn)
+                return false;
+            try {
+                const frame = JSON.stringify(notification) + "\n";
+                return conn.socket.write(frame);
+            }
+            catch (err) {
+                logger.debug("daemon.ipc.notification.write.failed", {
+                    connectionId,
+                    error: extractErrorMessage(err),
+                });
+                return false;
+            }
+        },
+        getConnectionIds() {
+            return Array.from(connections.keys());
+        },
+    };
+}
+//# sourceMappingURL=ipc-server.js.map

package/dist/ipc-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-server.js","sourceRoot":"","sources":["../src/ipc-server.ts"],"names":[],"mappings":"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"}

package/dist/ipc-surface.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The handler map as the IPC server sees it — every response rendered for the surface that asked.
+ *
+ * The daemon is where an operator actually MEETS the tool names. A refused send says "call
+ * cello_receive first", and those strings are written with the MCP names, so an MCP caller gets them
+ * verbatim while a CLI caller must be told `cello receive` — the thing they can type. Wrapping the
+ * map is the ONE choke point that has both the response and the connection's client type; doing it
+ * per-handler would mean sixty call sites and the sixty-first would forget.
+ *
+ * ⚠️ RESOLVED AT DISPATCH, NEVER SNAPSHOTTED. This was once a `for…of` that copied `handlers` into a
+ * second map, which made the ORDER of registration load-bearing in a file thousands of lines long:
+ * anything registered after that line went into a map nothing dispatched from. The document surface
+ * landed below it and every `cello_doc_*` verb answered `method_not_found` — whose guidance blames
+ * version skew, so an operator would re-pin, reinstall and restart, and find both sides matching.
+ * Late binding makes that unrepresentable rather than forbidden by a comment.
+ */
+import { type IpcHandler, type IpcServer } from "./ipc-server.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Logger } from "./types.js";
+export interface IpcSurfaceDeps {
+    logger: Logger;
+    socketPath: string;
+    maxConnections: number;
+    /** Read at DISPATCH — see the header. Never copied. */
+    handlers: Map<string, IpcHandler>;
+    perConnectionState: ReadonlyMap<string, {
+        clientType?: string;
+    }>;
+    fallbackNoticeStore: AsyncLocalStorage<{
+        notice?: Record<string, unknown>;
+    }>;
+    /**
+     * ⚠️ A GETTER, AND THE HONEST REASON IS NOT THE OBVIOUS ONE. `stop` is a hoisted `function`
+     * declaration, so passing it by value would work TODAY. The getter is there so that turning it
+     * into a `const` — which is what every other extraction in this order did to its neighbours —
+     * cannot silently break the `shutdown` verb. An earlier version of this comment claimed a crash
+     * that cannot happen, which is the wrong lesson: the silent shape is a `let` assigned below.
+     */
+    getStop: () => (reason: string) => Promise<void>;
+}
+export declare function createIpcSurface(deps: IpcSurfaceDeps): {
+    ipcServer: IpcServer;
+};
+//# sourceMappingURL=ipc-surface.d.ts.map

package/dist/ipc-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-surface.d.ts","sourceRoot":"","sources":["../src/ipc-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AACvG,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,mBAAmB,EAAE,iBAAiB,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC7E;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc;;EA6FpD"}

package/dist/ipc-surface.js

@@ -0,0 +1,107 @@
+/**
+ * The handler map as the IPC server sees it — every response rendered for the surface that asked.
+ *
+ * The daemon is where an operator actually MEETS the tool names. A refused send says "call
+ * cello_receive first", and those strings are written with the MCP names, so an MCP caller gets them
+ * verbatim while a CLI caller must be told `cello receive` — the thing they can type. Wrapping the
+ * map is the ONE choke point that has both the response and the connection's client type; doing it
+ * per-handler would mean sixty call sites and the sixty-first would forget.
+ *
+ * ⚠️ RESOLVED AT DISPATCH, NEVER SNAPSHOTTED. This was once a `for…of` that copied `handlers` into a
+ * second map, which made the ORDER of registration load-bearing in a file thousands of lines long:
+ * anything registered after that line went into a map nothing dispatched from. The document surface
+ * landed below it and every `cello_doc_*` verb answered `method_not_found` — whose guidance blames
+ * version skew, so an operator would re-pin, reinstall and restart, and find both sides matching.
+ * Late binding makes that unrepresentable rather than forbidden by a comment.
+ */
+import { createIpcServer } from "./ipc-server.js";
+import { renderForSurface } from "./vocabulary.js";
+import { extractErrorMessage } from "./error-message.js";
+export function createIpcSurface(deps) {
+    const { logger, socketPath, maxConnections, handlers, perConnectionState, fallbackNoticeStore, getStop } = deps;
+    let shutdownPromise = null;
+    handlers.set("shutdown", async (_params, _connectionId) => {
+        if (!shutdownPromise) {
+            shutdownPromise = getStop()("logout_requested").catch((err) => {
+                logger.error("daemon.shutdown.failed", {
+                    signal: "logout",
+                    error: extractErrorMessage(err),
+                });
+            });
+        }
+        return { acknowledged: true };
+    });
+    // DOD-ONBOARD-HELP-1 §5 — render every response for the surface that asked.
+    //
+    // The daemon is where an operator actually MEETS the tool names: a refused send says "call
+    // cello_receive first". Those strings are written with the canonical MCP names, so an MCP caller
+    // gets them verbatim — but a CLI caller must be told `cello receive`, the thing they can type.
+    // (P2-7 was the one-off report of this; it is a whole CLASS, and this closes the class.)
+    //
+    // Wrapping the handler map is the ONE choke point that has both the response and the connection's
+    // clientType. Doing it per-handler would mean 60+ call sites, and the 61st would forget.
+    //
+    // RESOLVED AT DISPATCH, not copied at construction. This was a `for…of` that snapshotted
+    // `handlers` into a second map, which made the ORDER of registration load-bearing in a file
+    // 3,500 lines long: anything registered after this line was written into a map nothing
+    // dispatched from. The document surface landed 245 lines below it and every `cello_doc_*` verb
+    // answered `method_not_found` — whose guidance blames version skew between the shim and the
+    // daemon, so an operator would re-pin, reinstall and restart, and find both sides matching.
+    //
+    // A comment saying "register above this line" would have been one more rule to remember. Late
+    // binding makes the ordering unrepresentable instead: the map below reads `handlers` when a
+    // request arrives, so a handler registered at any point before the first request is dispatchable.
+    const renderedHandlers = {
+        get(method) {
+            const handler = handlers.get(method);
+            if (!handler)
+                return undefined;
+            return async (params, connectionId) => {
+                /**
+                 * ONE request, ONE store — and the fallback notice is spread in BEFORE `renderForSurface`.
+                 *
+                 * `DOD-M15-SELECTION-1` clause 2 first annotated the response out in `ipc-server.ts`, which
+                 * is downstream of this wrapper and therefore downstream of surface rendering. The notice
+                 * says *"Run cello_use_agent"*; `isInstructionKey` in `vocabulary.ts` rewrites any key
+                 * ending in `guidance`, so that WOULD have become `cello use-agent` for a terminal — but it
+                 * arrived after the rewrite had already run. An operator running `cello inbox` was handed a
+                 * verb that does not exist in a shell, which is the exact failure the vocabulary layer was
+                 * built to prevent. Annotating here puts it back in front of the renderer.
+                 */
+                const store = {};
+                const result = await fallbackNoticeStore.run(store, () => handler(params, connectionId));
+                /**
+                 * ⚠️ **THE NOTICE GOES FIRST, AND THAT ORDERING IS A SECURITY PROPERTY — review F2.**
+                 *
+                 * It used to be spread LAST, which reads as harmless because these keys are additive. It is
+                 * not: `cello_get_quarantined` returns a REFUSED MESSAGE as its final key, and the framing
+                 * that makes hostile content safe to read has NO CLOSING DELIMITER — the reader's one
+                 * structural guarantee is that nothing follows the payload. Three keys of genuine
+                 * CELLO-authored prose landing after it is exactly the shape a forged ending imitates, and
+                 * once a reader has seen real framing follow the payload, a forged one is credible.
+                 *
+                 * Not a corner case: `withIpc` in the CLI never sends `ipc.connect`, so a single-agent
+                 * daemon takes the sole-online fallback on EVERY plain `cello quarantined` invocation.
+                 *
+                 * Spreading first is safe in general and needs no per-handler knowledge: these keys cannot
+                 * collide with a handler's own (a collision would mean a handler already answered the
+                 * question the notice exists to answer), and every response then keeps its own key order at
+                 * the tail — which is where a payload-terminal key has to stay.
+                 */
+                const annotated = store.notice && result !== null && typeof result === "object" && !Array.isArray(result)
+                    ? { ...store.notice, ...result }
+                    : result;
+                // Default to "cli": a connection that never sent ipc.connect has no recorded surface, and
+                // the CLI verb is the safe answer — it is at least a real command an operator can run,
+                // whereas an MCP tool name is useless in a terminal.
+                const surface = perConnectionState.get(connectionId)?.clientType === "mcp" ? "mcp" : "cli";
+                return renderForSurface(annotated, surface);
+            };
+        },
+    };
+    // Create and start IPC server
+    const ipcServer = createIpcServer({ socketPath, maxConnections, logger }, renderedHandlers);
+    // `renderedHandlers` is not returned: its only consumer is the server constructed here.
+    return { ipcServer };
+}
+//# sourceMappingURL=ipc-surface.js.map

package/dist/ipc-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-surface.js","sourceRoot":"","sources":["../src/ipc-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,eAAe,EAAuD,MAAM,iBAAiB,CAAC;AAEvG,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAoBzD,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEhH,IAAI,eAAe,GAAyB,IAAI,CAAC;IACjD,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE;QACxD,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,eAAe,GAAG,OAAO,EAAE,CAAC,kBAAkB,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACrE,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE;oBACrC,MAAM,EAAE,QAAQ;oBAChB,KAAK,EAAE,mBAAmB,CAAC,GAAG,CAAC;iBAChC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,EAAE;IACF,2FAA2F;IAC3F,iGAAiG;IACjG,+FAA+F;IAC/F,yFAAyF;IACzF,EAAE;IACF,kGAAkG;IAClG,yFAAyF;IACzF,EAAE;IACF,yFAAyF;IACzF,4FAA4F;IAC5F,uFAAuF;IACvF,+FAA+F;IAC/F,4FAA4F;IAC5F,4FAA4F;IAC5F,EAAE;IACF,8FAA8F;IAC9F,4FAA4F;IAC5F,kGAAkG;IAClG,MAAM,gBAAgB,GAAkB;QACtC,GAAG,CAAC,MAAc;YAChB,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACrC,IAAI,CAAC,OAAO;gBAAE,OAAO,SAAS,CAAC;YAC/B,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE;gBACpC;;;;;;;;;;mBAUG;gBACH,MAAM,KAAK,GAAyC,EAAE,CAAC;gBACvD,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;gBACzF;;;;;;;;;;;;;;;;;mBAiBG;gBACH,MAAM,SAAS,GACb,KAAK,CAAC,MAAM,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;oBACrF,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,GAAI,MAAkC,EAAE;oBAC7D,CAAC,CAAC,MAAM,CAAC;gBACb,0FAA0F;gBAC1F,uFAAuF;gBACvF,qDAAqD;gBACrD,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,UAAU,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;gBAC3F,OAAO,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC9C,CAAC,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,8BAA8B;IAC9B,MAAM,SAAS,GAAc,eAAe,CAC1C,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,EACtC,gBAAgB,CACjB,CAAC;IAEF,wFAAwF;IACxF,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}