appduct 0.9.0

package/dist/daemon/event-bus.js

@@ -0,0 +1,111 @@
+/**
+ * Typed in-process event bus (ARCHITECTURE.md §5 event kinds). The RPC layer (for
+ * `events.subscribe`/`events.since`) and audit subscribe here; this module owns fan-out plus a
+ * per-session retention ring buffer, and must never let a throwing subscriber take down the daemon
+ * or another subscriber.
+ *
+ * Retention (issue #6): every session-scoped event (`sessionId` set), except the high-frequency
+ * kinds in `EXCLUDED_FROM_RETENTION`, is appended to a per-session ring buffer with a
+ * monotonically increasing `seq`, capped at `bufferSize` entries (oldest dropped first). A
+ * session's buffer is discarded the moment it emits a terminal event (`session_expired` /
+ * `session_revoked`) — "terminal states free the alias" (sessions.ts) applies to retained events
+ * too, matching "no persisted history" (ARCHITECTURE.md §3/§13) — or via an explicit `drop()` for
+ * the pending-link discard paths that never reach one of those event kinds. Daemon-wide events (no
+ * `sessionId`, e.g. `daemon_started`) are fanned out but never buffered.
+ */
+/** Terminal event kinds whose arrival for a session discards that session's retained buffer. */
+const TERMINAL_EVENT_KINDS = new Set(["session_expired", "session_revoked"]);
+/** Fanned out live like any other event, but never appended to the retention buffer: a single
+ * chatty `tools.call` can emit far more of these than `bufferSize` allows, which would otherwise
+ * evict every retained `app_event` for the session — defeating the reason the buffer exists.
+ * `tool_call_started`/`tool_call_finished` (one pair per call, not per progress tick) are still
+ * retained. */
+const EXCLUDED_FROM_RETENTION = new Set(["tool_call_progress"]);
+export const createEventBus = (options = {}) => {
+    const clock = options.clock ?? { now: () => new Date() };
+    const bufferSize = options.bufferSize ?? 256;
+    const listeners = new Set();
+    const buffers = new Map();
+    const cursors = new Map();
+    const appendToBuffer = (sessionId, notification) => {
+        const buffer = buffers.get(sessionId) ?? [];
+        buffer.push(notification);
+        if (buffer.length > bufferSize) {
+            buffer.splice(0, buffer.length - bufferSize);
+        }
+        buffers.set(sessionId, buffer);
+    };
+    return {
+        emit: (event) => {
+            const sessionId = event.sessionId;
+            const seq = sessionId !== undefined ? (cursors.get(sessionId) ?? 0) + 1 : 0;
+            if (sessionId !== undefined) {
+                cursors.set(sessionId, seq);
+            }
+            const notification = {
+                ...event,
+                ts: event.ts ?? clock.now().getTime(),
+                seq,
+            };
+            if (sessionId !== undefined) {
+                if (TERMINAL_EVENT_KINDS.has(notification.kind)) {
+                    // The terminal event itself is still delivered live (fan-out below) and reported through
+                    // `since`'s `cursor`, but is not retained — nothing can legitimately ask for it again once
+                    // the session is gone.
+                    buffers.delete(sessionId);
+                    cursors.delete(sessionId);
+                }
+                else if (!EXCLUDED_FROM_RETENTION.has(notification.kind)) {
+                    appendToBuffer(sessionId, notification);
+                }
+            }
+            for (const listener of listeners) {
+                try {
+                    listener(notification);
+                }
+                catch {
+                    // A misbehaving subscriber must never crash the daemon or block other subscribers.
+                }
+            }
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        since: (sessionId, query = {}) => {
+            const buffer = buffers.get(sessionId) ?? [];
+            const sessionCursor = cursors.get(sessionId) ?? 0;
+            // Never hand back the live buffer array itself — `emit()` keeps pushing into it after this
+            // call returns, and a caller that gets `events` by reference (the common case: no filter
+            // narrows it below) would see it mutate underneath it.
+            let events = buffer.slice();
+            if (query.since !== undefined) {
+                events = events.filter((event) => event.seq > query.since);
+            }
+            if (query.kinds !== undefined) {
+                const kinds = new Set(query.kinds);
+                events = events.filter((event) => kinds.has(event.kind));
+            }
+            if (query.limit !== undefined && events.length > query.limit) {
+                // Keep the OLDEST N, not the newest: `limit` exists to bound one response, not to skip
+                // ahead — a caller pages forward by re-calling with `since` set to the response's own
+                // `cursor`. Keeping the newest N instead would make that same re-call return the same
+                // window forever, silently and unrecoverably losing whatever `limit` cut off.
+                events = events.slice(0, query.limit);
+            }
+            // The cursor a caller should resume from: the last event actually returned, so paging
+            // through a `limit`-truncated response with `since: cursor` always advances. Only when
+            // nothing was returned (empty buffer, or every retained event was filtered out) does it fall
+            // back to the session's true high-water mark, so an empty page still lets a caller skip past
+            // events it explicitly filtered out (by `kinds`) rather than re-fetching them forever.
+            const cursor = events.length > 0 ? events[events.length - 1].seq : sessionCursor;
+            return { events, cursor };
+        },
+        drop: (sessionId) => {
+            buffers.delete(sessionId);
+            cursors.delete(sessionId);
+        },
+    };
+};

package/dist/daemon/links.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pending-link minting (ARCHITECTURE.md §6 PENDING state, §8 bootstrap payload). A link is a
+ * short-lived, single-use claim ticket: `sessionId` + `token`, encoded into the deep-link
+ * bootstrap payload and backed by a TTL timer that discards it if nobody claims it in time.
+ * Pending links are cheap and re-issuable — they are never persisted and never appear in
+ * `sessions.list`/`sessions.describe` (only claimed sessions do; see sessions.ts).
+ */
+import { type AgentEndpoint } from "@appduct/shared";
+import type { Clock } from "../cli/types.js";
+import type { EventBus } from "./event-bus.js";
+import type { TimerFns } from "./timers.js";
+export type PendingLink = {
+    sessionId: string;
+    /** Raw 32-byte token; compared with `crypto.timingSafeEqual`, never logged. */
+    token: Buffer;
+    createdAt: Date;
+    expiresAt: Date;
+};
+export type CreatedLink = {
+    link: PendingLink;
+    deepLinkPayload: string;
+    endpoint: AgentEndpoint;
+};
+export type PendingLinkRegistryOptions = {
+    /** Resolves the current advertised endpoint at mint time (address may be re-detected). */
+    getEndpoint: () => AgentEndpoint;
+    clock: Clock;
+    timers: TimerFns;
+    eventBus: EventBus;
+};
+export type PendingLinkRegistry = {
+    /** `addressOverride` forces the endpoint address encoded into this one link's bootstrap payload
+     * (the emulator/simulator fast path: `127.0.0.1`), leaving the detected endpoint used by
+     * every other link unaffected. */
+    create: (ttlSeconds: number, addressOverride?: string) => CreatedLink;
+    /** Looks up a pending link without consuming it (used to distinguish "unknown" from "already claimed"). */
+    get: (sessionId: string) => PendingLink | undefined;
+    /** Removes and returns the link (successful claim consumes its single use). */
+    consume: (sessionId: string) => PendingLink | undefined;
+    /** Records a failed claim attempt; returns the attempt count so far. */
+    recordFailedAttempt: (sessionId: string) => number;
+    /** Discards a link outright (TTL expiry, attempt-limit exceeded, or explicit revoke). */
+    discard: (sessionId: string) => void;
+    /** How many links are still claimable right now: minted, unclaimed, and not past their TTL
+     * (`daemon.status`'s `pendingLinks`). Deliberately not `records.size` — a record outlives its
+     * TTL by a further grace window purely so a late claim can be told "expired" rather than
+     * "unknown", and an expired QR nobody will scan must not hold off a daemon upgrade for another
+     * whole TTL (issue #30). */
+    claimableCount: () => number;
+    /** Clears every outstanding TTL timer (daemon shutdown). */
+    disposeAll: () => void;
+};
+export declare const createPendingLinkRegistry: (options: PendingLinkRegistryOptions) => PendingLinkRegistry;
+//# sourceMappingURL=links.d.ts.map

package/dist/daemon/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/daemon/links.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE1F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,aAAa,CAAC;AAKzD,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,0FAA0F;IAC1F,WAAW,EAAE,MAAM,aAAa,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC;;sCAEkC;IAClC,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,KAAK,WAAW,CAAC;IACtE,2GAA2G;IAC3G,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IACpD,+EAA+E;IAC/E,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IACxD,wEAAwE;IACxE,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnD,yFAAyF;IACzF,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;;gCAI4B;IAC5B,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAoBF,eAAO,MAAM,yBAAyB,GAAI,SAAS,0BAA0B,KAAG,mBAkH/E,CAAC"}

package/dist/daemon/links.js

@@ -0,0 +1,118 @@
+/**
+ * Pending-link minting (ARCHITECTURE.md §6 PENDING state, §8 bootstrap payload). A link is a
+ * short-lived, single-use claim ticket: `sessionId` + `token`, encoded into the deep-link
+ * bootstrap payload and backed by a TTL timer that discards it if nobody claims it in time.
+ * Pending links are cheap and re-issuable — they are never persisted and never appear in
+ * `sessions.list`/`sessions.describe` (only claimed sessions do; see sessions.ts).
+ */
+import { randomBytes } from "node:crypto";
+import { encodeBootstrap } from "@appduct/shared";
+const SESSION_ID_BYTES = 12;
+const TOKEN_BYTES = 32;
+const generateSessionId = () => {
+    // Re-rolled if it starts with "-": v1 ids starting with "-" broke CLI flag parsing
+    // (e.g. `appduct tools -abc123...` was parsed as a flag, not a selector).
+    let candidate = randomBytes(SESSION_ID_BYTES).toString("base64url");
+    while (candidate.startsWith("-")) {
+        candidate = randomBytes(SESSION_ID_BYTES).toString("base64url");
+    }
+    return candidate;
+};
+export const createPendingLinkRegistry = (options) => {
+    const records = new Map();
+    const discard = (sessionId) => {
+        const record = records.get(sessionId);
+        if (!record) {
+            return;
+        }
+        options.timers.clearTimeout(record.timer);
+        records.delete(sessionId);
+        // Covers every discard path uniformly, including the ones with no dedicated event kind
+        // (attempt-limit exceeded, the TTL free-timer) — `link_expired`/`session_revoked` also reach
+        // here for the paths that do emit one, so this is a harmless no-op in those cases (the
+        // corresponding event already dropped the buffer, if `event-bus.ts` treats that kind as
+        // terminal) or the only thing that does (issue #6: an unclaimed link must not retain events
+        // forever).
+        options.eventBus.drop(sessionId);
+    };
+    return {
+        create: (ttlSeconds, addressOverride) => {
+            const sessionId = generateSessionId();
+            const token = randomBytes(TOKEN_BYTES);
+            const createdAt = options.clock.now();
+            const expiresAt = new Date(createdAt.getTime() + ttlSeconds * 1000);
+            const detectedEndpoint = options.getEndpoint();
+            // Overriding only ever changes the address (and its family); the port stays the daemon's
+            // real wss port, since the listener already binds all interfaces (ARCHITECTURE.md §8).
+            const endpoint = addressOverride
+                ? {
+                    family: (addressOverride.includes(":") ? 6 : 4),
+                    address: addressOverride,
+                    port: detectedEndpoint.port,
+                }
+                : detectedEndpoint;
+            // Deliberately does not delete the record the instant the TTL fires: a claim attempt arriving
+            // just after must still see the (now-expired) link and be told "expired" rather than
+            // "unknown" — the distinction the rejection matrix requires. `handleClaim`'s own `expiresAt`
+            // check discards the record (and reports `link_expired`) the moment anything touches it.
+            // But the record must not live forever if nobody ever touches it again: a second timer frees
+            // it after an equal further grace window (late claims within that window still see
+            // `link_expired`; a long-lived daemon with many unclaimed links does not leak memory
+            // unboundedly). `disposeAll` clears whichever timer (TTL or free) is still outstanding on
+            // daemon shutdown.
+            const timer = options.timers.setTimeout(() => {
+                // `link_expired` is its own event kind, distinct from `session_expired` (reserved for the
+                // SUSPENDED -> EXPIRED grace-window transition of a *claimed* session — ARCHITECTURE.md §6).
+                options.eventBus.emit({ kind: "link_expired", sessionId, data: { reason: "link_ttl_expired" } });
+                const record = records.get(sessionId);
+                if (record) {
+                    record.timer = options.timers.setTimeout(() => discard(sessionId), ttlSeconds * 1000);
+                }
+            }, ttlSeconds * 1000);
+            const link = { sessionId, token, createdAt, expiresAt };
+            records.set(sessionId, { link, attempts: 0, timer });
+            const deepLinkPayload = encodeBootstrap({
+                ...endpoint,
+                sessionId,
+                token: token.toString("base64url"),
+                expiresAt: Math.floor(expiresAt.getTime() / 1000),
+            });
+            options.eventBus.emit({ kind: "link_created", sessionId, data: { expiresAt: link.expiresAt.toISOString() } });
+            return { link, deepLinkPayload, endpoint };
+        },
+        get: (sessionId) => records.get(sessionId)?.link,
+        consume: (sessionId) => {
+            const record = records.get(sessionId);
+            if (!record) {
+                return undefined;
+            }
+            options.timers.clearTimeout(record.timer);
+            records.delete(sessionId);
+            return record.link;
+        },
+        recordFailedAttempt: (sessionId) => {
+            const record = records.get(sessionId);
+            if (!record) {
+                return 0;
+            }
+            record.attempts += 1;
+            return record.attempts;
+        },
+        discard,
+        claimableCount: () => {
+            const now = options.clock.now().getTime();
+            let count = 0;
+            for (const record of records.values()) {
+                if (record.link.expiresAt.getTime() > now) {
+                    count += 1;
+                }
+            }
+            return count;
+        },
+        disposeAll: () => {
+            for (const sessionId of Array.from(records.keys())) {
+                discard(sessionId);
+            }
+        },
+    };
+};

package/dist/daemon/listener.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The pinned-TLS WebSocket listener (ARCHITECTURE.md §7). A thin frame-level gate in front of
+ * `SessionManager`: JSON/binary/size hygiene, the pre-claim timeout, and post-claim
+ * type/session-id routing. All state-machine decisions (claim/resume/registry/close-code choice)
+ * live in sessions.ts — this module never inspects session state itself.
+ *
+ * Every socket gets an `error` listener the instant it is accepted, and the server itself gets one
+ * too: v1's fatal defect was an unhandled `'error'` event crashing the whole daemon. A socket
+ * closing — for any reason — must never stop the listener or any other session.
+ */
+import { type Server as HttpsServer } from "node:https";
+import { WebSocketServer } from "ws";
+import { type SessionManager } from "./sessions.js";
+import type { TlsManager, TlsMaterial } from "./tls.js";
+import { type TimerFns } from "./timers.js";
+export type ListenerOptions = {
+    port: number;
+    tls: TlsManager;
+    sessionManager: SessionManager;
+    preClaimTimeoutMs?: number;
+    timers?: TimerFns;
+};
+export type DaemonListener = {
+    httpsServer: HttpsServer;
+    wss: WebSocketServer;
+    port: () => number | undefined;
+    /** Applies freshly-minted cert/key material to already-accepted-connections' future TLS
+     * handshakes (`tls.Server.setSecureContext`, ARCHITECTURE.md §4/§8: re-mint on advertised-IP
+     * change). Existing connections are unaffected — only new handshakes see the new SAN. */
+    applyTls: (material: Pick<TlsMaterial, "certPem" | "keyPem">) => void;
+    close: () => Promise<void>;
+};
+export declare const startListener: (options: ListenerOptions) => Promise<DaemonListener>;
+//# sourceMappingURL=listener.d.ts.map

package/dist/daemon/listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../../src/daemon/listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAqC,KAAK,MAAM,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3F,OAAO,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAErC,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK1D,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,UAAU,CAAC;IAChB,cAAc,EAAE,cAAc,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,GAAG,EAAE,eAAe,CAAC;IACrB,IAAI,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC/B;;6FAEyF;IACzF,QAAQ,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC,KAAK,IAAI,CAAC;IACtE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAMF,eAAO,MAAM,aAAa,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,cAAc,CA4IpF,CAAC"}

package/dist/daemon/listener.js

@@ -0,0 +1,132 @@
+/**
+ * The pinned-TLS WebSocket listener (ARCHITECTURE.md §7). A thin frame-level gate in front of
+ * `SessionManager`: JSON/binary/size hygiene, the pre-claim timeout, and post-claim
+ * type/session-id routing. All state-machine decisions (claim/resume/registry/close-code choice)
+ * live in sessions.ts — this module never inspects session state itself.
+ *
+ * Every socket gets an `error` listener the instant it is accepted, and the server itself gets one
+ * too: v1's fatal defect was an unhandled `'error'` event crashing the whole daemon. A socket
+ * closing — for any reason — must never stop the listener or any other session.
+ */
+import { createServer as createHttpsServer } from "node:https";
+import { isSessionClaimMessage, isSessionResumeMessage, isSessionBoundMessage } from "@appduct/shared";
+import { WebSocketServer } from "ws";
+import { isPostClaimMessageType } from "./sessions.js";
+import { systemTimers } from "./timers.js";
+const DEFAULT_PRE_CLAIM_TIMEOUT_MS = 10_000;
+const MAX_PAYLOAD_BYTES = 256 * 1024;
+const isRecord = (value) => {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+export const startListener = async (options) => {
+    const timers = options.timers ?? systemTimers;
+    const preClaimTimeoutMs = options.preClaimTimeoutMs ?? DEFAULT_PRE_CLAIM_TIMEOUT_MS;
+    const material = options.tls.current();
+    const httpsServer = createHttpsServer({ key: material.keyPem, cert: material.certPem });
+    httpsServer.on("error", () => {
+        // A listener-level error (e.g. a transient accept failure) must never crash the daemon.
+        // Startup failures are still surfaced via the one-shot listener below.
+    });
+    const wss = new WebSocketServer({ server: httpsServer, maxPayload: MAX_PAYLOAD_BYTES });
+    wss.on("error", () => {
+        // Same contract as the https server: never let a listener-level error take the daemon down.
+    });
+    wss.on("connection", (socket) => {
+        socket.on("error", () => {
+            // The 'close' event still fires after 'error' and drives session suspend/cleanup.
+        });
+        let claimedSessionId = null;
+        const preClaimTimer = timers.setTimeout(() => {
+            if (!claimedSessionId) {
+                socket.close(1008, "pre_claim_timeout");
+            }
+        }, preClaimTimeoutMs);
+        socket.once("close", () => {
+            timers.clearTimeout(preClaimTimer);
+        });
+        socket.on("message", (data, isBinary) => {
+            if (isBinary) {
+                socket.close(1003, "binary_frame_not_supported");
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(data.toString("utf8"));
+            }
+            catch {
+                socket.close(1008, "invalid_json");
+                return;
+            }
+            if (!isRecord(parsed)) {
+                socket.close(1008, "invalid_json");
+                return;
+            }
+            if (claimedSessionId === null) {
+                if (isSessionClaimMessage(parsed)) {
+                    const result = options.sessionManager.handleClaim(socket, parsed);
+                    if (result) {
+                        claimedSessionId = result;
+                        timers.clearTimeout(preClaimTimer);
+                    }
+                    return;
+                }
+                if (isSessionResumeMessage(parsed)) {
+                    const result = options.sessionManager.handleResume(socket, parsed);
+                    if (result) {
+                        claimedSessionId = result;
+                        timers.clearTimeout(preClaimTimer);
+                    }
+                    return;
+                }
+                socket.close(1008, "expected_claim_or_resume");
+                return;
+            }
+            if (!isPostClaimMessageType(parsed.type)) {
+                socket.close(1008, "unknown_message_type");
+                return;
+            }
+            if (!isSessionBoundMessage(parsed) || parsed.session_id !== claimedSessionId) {
+                socket.close(1008, "session_mismatch");
+                return;
+            }
+            options.sessionManager.handlePostClaimMessage(claimedSessionId, socket, parsed);
+        });
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            httpsServer.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            httpsServer.off("error", onError);
+            resolve();
+        };
+        httpsServer.once("error", onError);
+        httpsServer.once("listening", onListening);
+        httpsServer.listen(options.port);
+    });
+    return {
+        httpsServer,
+        wss,
+        port: () => {
+            const address = httpsServer.address();
+            return address && typeof address !== "string" ? address.port : undefined;
+        },
+        applyTls: (nextMaterial) => {
+            // Keep this guard for compatibility with runtimes whose `node:https` shim omits the method.
+            const server = httpsServer;
+            server.setSecureContext?.({ key: nextMaterial.keyPem, cert: nextMaterial.certPem });
+        },
+        close: () => new Promise((resolve) => {
+            for (const client of wss.clients) {
+                client.terminate();
+            }
+            wss.close(() => {
+                // `server.close()` alone only stops accepting new connections — it waits for existing
+                // (including idle keep-alive) sockets to end, which could hang shutdown indefinitely.
+                httpsServer.closeAllConnections();
+                httpsServer.close(() => resolve());
+            });
+        }),
+    };
+};

package/dist/daemon/log-rotation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `daemon.log` rotation (ARCHITECTURE.md §3/§4, issue #32). The daemon's stdout/stderr is appended
+ * to `daemon.log` for the whole life of the process, so nothing inside a running daemon can safely
+ * truncate it — the only safe moment is just before a *new* daemon is spawned, while no writer
+ * holds the file open. {@link rotateDaemonLogIfNeeded} is therefore called from the spawn path
+ * (`rpc/client.ts`'s `defaultSpawn`, which is also what `appduct daemon start` spawns through),
+ * never from the daemon itself.
+ *
+ * "Nothing answered the socket" is not by itself proof that nothing is writing the log: a daemon
+ * that is still booting, wedged, or mid-shutdown holds its log fd while its socket is unreachable,
+ * and the spawn lock is released as soon as the child is spawned rather than when it is ready. A
+ * rename under such a process would send its output to `daemon.log.1`, and the *next* rotation
+ * would then unlink the inode it is still writing to — output lost, with nothing on disk to show
+ * for it. So rotation asks twice, as late as it can, and declines on either answer:
+ *
+ * - the pidfile must not name a live process (the same probe the pidfile takeover and the
+ *   stale-socket unlink use); and
+ * - `daemon.sock` must not accept a connection, re-checked immediately before the rename.
+ *
+ * **This narrows the window; it does not close it.** A daemon spawned microseconds ago holds its
+ * log fd before it has written `daemon.pid` or bound its socket, and no check performed before the
+ * rename can see it — the file it is writing to is simply not distinguishable, from the outside,
+ * from one nobody holds. What is left is a race measured in the milliseconds between a child being
+ * spawned and it writing its pidfile, entered only by a *second* spawner that also finds the log
+ * over its cap. The consequence is bounded (that daemon's output continues into `daemon.log.1`,
+ * and is lost if a later rotation replaces that backup), and a just-spawned daemon's log is far
+ * below any sane cap, so in practice the second spawner does not rotate at all. Closing it
+ * properly needs an advisory lock held across spawn-and-ready rather than released at spawn.
+ *
+ * One backup is enough (`daemon.log.1`): the point is a bounded footprint, not a full history. A
+ * rotation failure is warned and swallowed — a daemon that cannot rotate its log must still start.
+ */
+export declare const daemonLogBackupPath: (logFilePath: string) => string;
+export type RotateDaemonLogOptions = {
+    logFilePath: string;
+    /** Rotate once the log is strictly larger than this. */
+    maxBytes: number;
+    /** When given, an over-cap log is left alone if this pidfile names a live process — see the
+     * module doc comment. Omit only when the caller has already established that nothing holds the
+     * log open. */
+    pidFilePath?: string;
+    /** When given, an over-cap log is left alone if this control socket accepts a connection,
+     * re-checked immediately before the rename. Catches a daemon that is up but was unreachable
+     * when the caller decided to spawn. */
+    socketPath?: string;
+    /** Sink for rotation-failure diagnostics; defaults to `process.stderr`. Injectable for tests. */
+    warn?: (message: string) => void;
+};
+export type RotateDaemonLogResult = {
+    rotated: boolean;
+    /** Size of the log that was moved aside; only set when `rotated` is `true`. */
+    rotatedBytes?: number;
+    /** Why an over-cap log was deliberately left in place. */
+    skipped?: "daemon_running";
+};
+/**
+ * Moves `daemon.log` to `daemon.log.1` when it exceeds `maxBytes`, replacing any previous backup.
+ * A missing log, a log within the cap, a log a live daemon still holds, or any failure is a no-op
+ * — never throws.
+ */
+export declare const rotateDaemonLogIfNeeded: (options: RotateDaemonLogOptions) => Promise<RotateDaemonLogResult>;
+/**
+ * Best-effort enforcement of `daemon.log`'s ARCHITECTURE.md §3 mode. `open(path, "a", 0o600)`
+ * already creates it at `0600` (the umask can only remove bits), so this exists for the file that
+ * was *not* created by us — an operator's `touch`, a `cp` from elsewhere — and is a no-op
+ * otherwise.
+ *
+ * Never throws. It sits directly on the auto-spawn path, where every CLI and MCP command that
+ * needs a daemon passes through: a filesystem that answers `chmod` with EPERM or ENOTSUP (a
+ * drvfs/NFS/SMB-backed state dir, a root-owned log under a non-root user) would otherwise brick
+ * every one of those commands over a permission bit. A daemon that cannot tighten its log mode
+ * must still start — loudly, but it must start.
+ */
+export declare const ensureDaemonLogMode: (logFilePath: string, warn?: (message: string) => void) => Promise<boolean>;
+/**
+ * `config.daemonLogMaxBytes` for a state dir, falling back to the default when `config.json` is
+ * missing or unreadable. Deliberately forgiving: this runs on the spawn path, where a bad config
+ * is the daemon's problem to report properly once it starts — not a reason to fail rotation (and
+ * with it the spawn) with a duplicate error.
+ */
+export declare const resolveDaemonLogMaxBytes: (stateDir: string) => Promise<number>;
+//# sourceMappingURL=log-rotation.d.ts.map

package/dist/daemon/log-rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-rotation.d.ts","sourceRoot":"","sources":["../../src/daemon/log-rotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAYH,eAAO,MAAM,mBAAmB,GAAI,aAAa,MAAM,KAAG,MAA4B,CAAC;AAEvF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB;;mBAEe;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;2CAEuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B,CAAC;AAcF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,sBAAsB,KAC9B,OAAO,CAAC,qBAAqB,CAsD/B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,MAAM,EACnB,OAAM,CAAC,OAAO,EAAE,MAAM,KAAK,IAAwD,KAClF,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAM/E,CAAC"}