appduct 0.9.0

package/dist/daemon/daemon.js

@@ -0,0 +1,560 @@
+/**
+ * Daemon composition root (ARCHITECTURE.md §4): state dir → config → pidfile → TLS → session
+ * engine → listener → RPC server. Implements `daemon.status`/`daemon.shutdown`, the session RPC
+ * surface (`link.create`, `sessions.list`, `sessions.describe`, `sessions.revoke`), and the
+ * invocation surface (`tools.list`, `tools.call`, `events.subscribe`), and policy + audit
+ * (ARCHITECTURE.md §12): every `tools.call` attempt is evaluated against `config.policy` and
+ * recorded to the audit log inline in the `tools.call` handler below.
+ */
+import { rm } from "node:fs/promises";
+import { RPC_METHODS, EVENT_KINDS, } from "@appduct/shared";
+import { getDaemonReportedVersion } from "../package-version.js";
+import { detectAdvertisedAddress } from "./address.js";
+import { argsSha256, createAuditLogger } from "./audit.js";
+import { createCallsManager } from "./calls.js";
+import { loadConfig } from "./config.js";
+import { createEventBus } from "./event-bus.js";
+import { startListener } from "./listener.js";
+import { evaluate as evaluatePolicy } from "./policy.js";
+import { acquirePidfile } from "./pidfile.js";
+import { RpcApplicationError, startRpcServer } from "./rpc-server.js";
+import { createSessionManager } from "./sessions.js";
+import { ensureStateDir, getSocketPath, getStateDirPaths } from "./state-dir.js";
+import { systemTimers } from "./timers.js";
+import { createTlsManager, toAgentEndpoint } from "./tls.js";
+/** Used to validate `events.subscribe`/`events.since`'s `kinds` filter. */
+const KNOWN_EVENT_KINDS = new Set(EVENT_KINDS);
+/**
+ * What this daemon reports as its version over `daemon.status` and in `daemon_started`. Read per
+ * call rather than at module load so `APPDUCT_DAEMON_VERSION_OVERRIDE` (issue #30's test seam)
+ * takes effect for an in-process daemon started by a test that set it after import.
+ */
+const packageVersion = () => getDaemonReportedVersion();
+/** How often audit retention runs after the startup prune (ARCHITECTURE.md §3: "once a day"). */
+export const AUDIT_PRUNE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const buildStatusResult = async (config, startedAt, tls, sessionManager, auditLogger, auditDir) => {
+    // The audit directory footprint is measured on demand rather than tracked incrementally: this
+    // handler runs at most once per `appduct daemon status`, and a stat per day file is cheaper
+    // and far harder to get wrong than a running total that must survive pruning and restarts.
+    const stats = await auditLogger.stats();
+    return {
+        version: packageVersion(),
+        pid: process.pid,
+        startedAt: startedAt.toISOString(),
+        wssPort: config.wssPort,
+        pinnedKeys: tls.pinnedKeys(),
+        sessions: sessionManager.list(),
+        pendingLinks: sessionManager.pendingLinkCount(),
+        policy: config.policy,
+        audit: {
+            path: auditDir,
+            failedWrites: auditLogger.failedWrites(),
+            failedPrunes: auditLogger.failedPrunes(),
+            retentionDays: config.auditRetentionDays,
+            files: stats.files,
+            bytes: stats.bytes,
+        },
+    };
+};
+const asSelectorParams = (params) => {
+    if (params === undefined || params === null) {
+        return {};
+    }
+    if (typeof params !== "object" || Array.isArray(params)) {
+        throw new RpcApplicationError("invalid_request", "Params must be an object.");
+    }
+    const selector = params.selector;
+    if (selector !== undefined && typeof selector !== "string") {
+        throw new RpcApplicationError("invalid_request", '"selector" must be a string.');
+    }
+    return { selector };
+};
+const asRecordParams = (params) => {
+    if (params === undefined || params === null) {
+        return {};
+    }
+    if (typeof params !== "object" || Array.isArray(params)) {
+        throw new RpcApplicationError("invalid_request", "Params must be an object.");
+    }
+    return params;
+};
+const asToolsCallParams = (params) => {
+    const record = asRecordParams(params);
+    const selector = record.selector;
+    if (selector !== undefined && typeof selector !== "string") {
+        throw new RpcApplicationError("invalid_request", '"selector" must be a string.');
+    }
+    if (typeof record.name !== "string" || record.name.length === 0) {
+        throw new RpcApplicationError("invalid_request", '"name" must be a non-empty string.');
+    }
+    const args = record.args;
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        throw new RpcApplicationError("invalid_request", '"args" must be a JSON object.');
+    }
+    const timeoutMs = record.timeoutMs;
+    if (timeoutMs !== undefined && (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs))) {
+        throw new RpcApplicationError("invalid_request", '"timeoutMs" must be a number.');
+    }
+    const caller = record.caller;
+    if (caller !== undefined && caller !== "cli" && caller !== "mcp" && caller !== "client") {
+        throw new RpcApplicationError("invalid_request", '"caller" must be "cli", "mcp", or "client".');
+    }
+    const consent = record.consent;
+    if (consent !== undefined && consent !== "client" && consent !== "elicitation") {
+        throw new RpcApplicationError("invalid_request", '"consent" must be "client" or "elicitation".');
+    }
+    return {
+        selector: selector,
+        name: record.name,
+        args: args,
+        timeoutMs: timeoutMs,
+        caller: caller,
+        consent: consent,
+    };
+};
+const asToolsCancelParams = (params) => {
+    const record = asRecordParams(params);
+    const selector = record.selector;
+    if (selector !== undefined && typeof selector !== "string") {
+        throw new RpcApplicationError("invalid_request", '"selector" must be a string.');
+    }
+    if (typeof record.callId !== "string" || record.callId.length === 0) {
+        throw new RpcApplicationError("invalid_request", '"callId" must be a non-empty string.');
+    }
+    const reason = record.reason;
+    if (reason !== undefined && typeof reason !== "string") {
+        throw new RpcApplicationError("invalid_request", '"reason" must be a string.');
+    }
+    return {
+        selector: selector,
+        callId: record.callId,
+        reason: reason,
+    };
+};
+const asEventsSubscribeParams = (params) => {
+    const record = asRecordParams(params);
+    const sessionSelector = record.sessionSelector;
+    if (sessionSelector !== undefined && typeof sessionSelector !== "string") {
+        throw new RpcApplicationError("invalid_request", '"sessionSelector" must be a string.');
+    }
+    const kindsRaw = record.kinds;
+    let kinds;
+    if (kindsRaw !== undefined) {
+        if (!Array.isArray(kindsRaw) || !kindsRaw.every((kind) => typeof kind === "string" && KNOWN_EVENT_KINDS.has(kind))) {
+            throw new RpcApplicationError("invalid_request", '"kinds" must be an array of known event kinds.');
+        }
+        kinds = kindsRaw;
+    }
+    return { sessionSelector: sessionSelector, kinds };
+};
+const asEventsSinceParams = (params) => {
+    const record = asRecordParams(params);
+    const selector = record.selector;
+    if (selector !== undefined && typeof selector !== "string") {
+        throw new RpcApplicationError("invalid_request", '"selector" must be a string.');
+    }
+    const since = record.since;
+    if (since !== undefined && (typeof since !== "number" || !Number.isInteger(since) || since < 0)) {
+        throw new RpcApplicationError("invalid_request", '"since" must be a non-negative integer.');
+    }
+    const kindsRaw = record.kinds;
+    let kinds;
+    if (kindsRaw !== undefined) {
+        if (!Array.isArray(kindsRaw) || !kindsRaw.every((kind) => typeof kind === "string" && KNOWN_EVENT_KINDS.has(kind))) {
+            throw new RpcApplicationError("invalid_request", '"kinds" must be an array of known event kinds.');
+        }
+        kinds = kindsRaw;
+    }
+    const limit = record.limit;
+    if (limit !== undefined && (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0)) {
+        throw new RpcApplicationError("invalid_request", '"limit" must be a positive integer.');
+    }
+    return {
+        selector: selector,
+        since: since,
+        kinds,
+        limit: limit,
+    };
+};
+const asLinkCreateParams = (params) => {
+    if (params === undefined || params === null) {
+        return {};
+    }
+    if (typeof params !== "object" || Array.isArray(params)) {
+        throw new RpcApplicationError("invalid_request", "Params must be an object.");
+    }
+    const record = params;
+    const ttlSeconds = record.ttlSeconds;
+    if (ttlSeconds !== undefined && (typeof ttlSeconds !== "number" || !Number.isInteger(ttlSeconds) || ttlSeconds <= 0)) {
+        throw new RpcApplicationError("invalid_request", '"ttlSeconds" must be a positive integer.');
+    }
+    const addressOverride = record.addressOverride;
+    if (addressOverride !== undefined && (typeof addressOverride !== "string" || addressOverride.length === 0)) {
+        throw new RpcApplicationError("invalid_request", '"addressOverride" must be a non-empty string.');
+    }
+    return { ttlSeconds, addressOverride: addressOverride };
+};
+export const startDaemon = async (options) => {
+    const clock = options.clock ?? { now: () => new Date() };
+    const timers = options.timers ?? systemTimers;
+    const paths = getStateDirPaths(options.stateDir);
+    await ensureStateDir(options.stateDir);
+    const config = await loadConfig(paths, { warn: options.warn });
+    const startedAt = clock.now();
+    // Created eagerly (before anything else can fail) so shutdown can always flush it, and so a
+    // startup failure before the RPC server exists still gets a chance to record what happened.
+    const auditLogger = createAuditLogger({
+        auditDir: paths.auditDir,
+        clock,
+        retentionDays: config.auditRetentionDays,
+        warn: options.warn,
+    });
+    let auditPruneInterval;
+    let pidfile;
+    let server;
+    let listener;
+    let sessionManager;
+    let callsManager;
+    let eventBus;
+    let shuttingDown = false;
+    let resolveExited;
+    const exited = new Promise((resolve) => {
+        resolveExited = resolve;
+    });
+    const shutdown = async () => {
+        if (shuttingDown) {
+            return exited;
+        }
+        shuttingDown = true;
+        try {
+            // Cleared first so a long teardown can't have the daily sweep fire into a half-torn-down
+            // daemon, and so nothing keeps the event loop (or a test runner) alive after `exited`.
+            if (auditPruneInterval !== undefined) {
+                timers.clearInterval(auditPruneInterval);
+                auditPruneInterval = undefined;
+            }
+            // Reject any calls still in flight before the sockets that would have answered them go away.
+            callsManager?.disposeAll();
+            // ARCHITECTURE.md §4: close all device sockets (1001) before tearing down the control plane.
+            sessionManager?.disposeAll(1001, "daemon_shutdown");
+            await listener?.close();
+            await server?.close();
+            await pidfile?.release();
+            await rm(getSocketPath(paths), { force: true });
+            // Flush the audit queue last: nothing else here writes audit records, but this makes sure a
+            // record enqueued by the very last `tools.call` before shutdown actually lands on disk.
+            await auditLogger.flush();
+        }
+        finally {
+            resolveExited();
+        }
+    };
+    try {
+        pidfile = await acquirePidfile(paths.pidFilePath, {
+            onStaleTakeover: async () => {
+                await rm(getSocketPath(paths), { force: true });
+            },
+        });
+        eventBus = createEventBus({ clock, bufferSize: config.eventBufferSize });
+        const activeEventBus = eventBus;
+        const detectAddress = options.detectAddress ??
+            (() => detectAdvertisedAddress({ override: config.advertisedIp }));
+        const tls = await createTlsManager({ keyPath: config.keyPath, detectAddress, warn: options.warn });
+        sessionManager = createSessionManager({
+            graceSeconds: config.graceSeconds,
+            keepaliveIntervalSeconds: config.keepaliveIntervalSeconds,
+            linkTtlSeconds: config.linkTtlSeconds,
+            getEndpoint: () => toAgentEndpoint(tls.current().advertisedAddress, config.wssPort),
+            eventBus: activeEventBus,
+            clock,
+            onToolFrame: (message) => {
+                switch (message.type) {
+                    case "tool_result":
+                        callsManager?.handleToolResult(message);
+                        return;
+                    case "tool_error":
+                        callsManager?.handleToolError(message);
+                        return;
+                    case "tool_call_progress":
+                        callsManager?.handleToolCallProgress(message);
+                }
+            },
+            onAppEvent: (sessionId, alias, message) => {
+                activeEventBus.emit({
+                    kind: "app_event",
+                    sessionId,
+                    alias,
+                    data: { name: message.name, payload: message.payload, ts: message.ts },
+                });
+            },
+        });
+        const activeSessionManager = sessionManager;
+        callsManager = createCallsManager({
+            send: (sessionId, message) => activeSessionManager.sendToolCall(sessionId, message),
+            sendCancel: (sessionId, message) => activeSessionManager.sendToolCancel(sessionId, message),
+            eventBus: activeEventBus,
+        });
+        const activeCallsManager = callsManager;
+        listener = await startListener({
+            port: config.wssPort,
+            tls,
+            sessionManager,
+        });
+        const activeListener = listener;
+        // `events.subscribe` fan-out: one global listener pushes matching notifications to every RPC
+        // connection currently marked as a subscriber (state stashed by the `events.subscribe` handler
+        // below). `RpcServer.notify` itself guards against a slow/dead subscriber backing up the daemon.
+        activeEventBus.subscribe((event) => {
+            for (const connection of server?.connections() ?? []) {
+                const subscription = connection.state.eventSubscription;
+                if (!subscription) {
+                    continue;
+                }
+                if (subscription.kinds && !subscription.kinds.has(event.kind)) {
+                    continue;
+                }
+                if (subscription.sessionSelector !== undefined &&
+                    event.sessionId !== subscription.sessionSelector &&
+                    event.alias !== subscription.sessionSelector) {
+                    continue;
+                }
+                server?.notify(connection, event);
+            }
+        });
+        server = await startRpcServer({
+            socketPath: getSocketPath(paths),
+            dispatch: {
+                [RPC_METHODS.daemonStatus]: async () => {
+                    return buildStatusResult(config, startedAt, tls, activeSessionManager, auditLogger, paths.auditDir);
+                },
+                [RPC_METHODS.daemonShutdown]: (_params, context) => {
+                    context.afterSend(() => {
+                        void shutdown();
+                    });
+                    return { ok: true };
+                },
+                [RPC_METHODS.linkCreate]: async (params) => {
+                    const { ttlSeconds, addressOverride } = asLinkCreateParams(params);
+                    // Re-detect the advertised address on every mint (ARCHITECTURE.md §4/§8): a long-lived
+                    // daemon that changed networks must not keep minting links with a stale address/SAN.
+                    // `refresh` only re-mints the certificate when the address actually changed; applying the
+                    // (possibly unchanged) secure context is a cheap no-op the rest of the time, but comparing
+                    // material identity avoids even that when nothing changed.
+                    const previousMaterial = tls.current();
+                    const nextMaterial = await tls.refresh();
+                    if (nextMaterial !== previousMaterial) {
+                        activeListener.applyTls(nextMaterial);
+                    }
+                    // `tls.refresh()` just ran above, so `pinnedKeys()[0]` reflects the material this link's
+                    // endpoint will actually serve (opt-in hardening dev-mode: the CLI composes this into the
+                    // deep link's `pin` query param — see `LinkCreateResult.pin`).
+                    return { ...activeSessionManager.createLink(ttlSeconds, addressOverride), pin: tls.pinnedKeys()[0] };
+                },
+                [RPC_METHODS.sessionsList]: () => {
+                    return activeSessionManager.list();
+                },
+                [RPC_METHODS.sessionsDescribe]: (params) => {
+                    const { selector } = asSelectorParams(params);
+                    return activeSessionManager.describe(selector);
+                },
+                [RPC_METHODS.sessionsRevoke]: (params) => {
+                    const { selector } = asSelectorParams(params);
+                    activeSessionManager.revoke(selector);
+                    return { ok: true };
+                },
+                [RPC_METHODS.toolsList]: (params) => {
+                    const { selector } = asSelectorParams(params);
+                    // ARCHITECTURE.md §5: tools.list works for ACTIVE and SUSPENDED sessions alike (the
+                    // retained registry survives suspend); only tools.call requires ACTIVE.
+                    const resolved = activeSessionManager.resolveForTools(selector);
+                    // Each entry carries its effective policy decision (ARCHITECTURE.md §12) so the MCP
+                    // server can emit `_meta["anthropic/requiresUserInteraction"]` for "prompt" tools
+                    // without a second round trip (issue #14).
+                    return resolved.registry.list().map((descriptor) => ({
+                        ...descriptor,
+                        policy: evaluatePolicy(descriptor, { alias: resolved.alias }, config.policy),
+                    }));
+                },
+                // This handler is the single seam every `tools.call` passes through: policy (ARCHITECTURE.md
+                // §12) is evaluated once the target tool descriptor is known, and one audit record is
+                // written for every attempt that reaches a resolved session, across ok/error/denied.
+                [RPC_METHODS.toolsCall]: async (params, context) => {
+                    const { selector, name, args, timeoutMs, caller, consent } = asToolsCallParams(params);
+                    const effectiveCaller = caller ?? "cli";
+                    const resolved = activeSessionManager.resolveForTools(selector);
+                    const auditStartedAt = clock.now().getTime();
+                    const writeAudit = (outcome, errorType, grantedConsent, deniedReason) => {
+                        auditLogger.record({
+                            sessionId: resolved.sessionId,
+                            alias: resolved.alias,
+                            tool: name,
+                            argsSha256: argsSha256(args),
+                            outcome,
+                            errorType,
+                            deniedReason,
+                            durationMs: clock.now().getTime() - auditStartedAt,
+                            caller: effectiveCaller,
+                            consent: grantedConsent,
+                        });
+                    };
+                    if (resolved.state !== "active") {
+                        const errorType = resolved.state === "suspended" ? "session_suspended" : "session_not_active";
+                        writeAudit("error", errorType);
+                        throw new RpcApplicationError(errorType, `Session "${resolved.alias}" is not active.`);
+                    }
+                    const tool = resolved.registry.get(name);
+                    if (!tool) {
+                        // Deliberately no frame is sent to the app for an unknown tool.
+                        writeAudit("error", "tool_not_found");
+                        throw new RpcApplicationError("tool_not_found", `Tool "${name}" is not registered.`);
+                    }
+                    const policyDecision = evaluatePolicy(tool, { alias: resolved.alias }, config.policy);
+                    // "prompt" fails closed (ARCHITECTURE.md §12): it proceeds only when the caller carried
+                    // `consent: "client"` (issue #14) or `consent: "elicitation"` (issue #10). Either value is
+                    // trusted verbatim once present — the daemon does not and cannot re-derive whether an MCP
+                    // client's `_meta` flag was actually honored or its elicitation reply actually came from a
+                    // human, the same way it doesn't re-verify any other RPC param. `consent` is only ever
+                    // justified when set by this codebase's own MCP server (mcp/server.ts), which sets
+                    // `"client"` solely after confirming both that it emitted
+                    // `_meta["anthropic/requiresUserInteraction"]` for this exact tool on this connection's
+                    // most recent listing and that the connected client is known to enforce it, and sets
+                    // `"elicitation"` solely after sending an `elicitation/create` request over this
+                    // connection and receiving `action: "accept"` back. Any other local process with access to
+                    // `daemon.sock` — including the CLI, or an agent with shell access, which is the typical
+                    // setup this feature targets — could send either value directly; that is not a bypass of
+                    // this feature so much as a restatement of this codebase's existing trust boundary
+                    // (docs/SECURITY.md: anything that can reach the socket already has full daemon control).
+                    // "prompt" guards against a compliant MCP client silently auto-approving on the caller's
+                    // behalf, not against a hostile process on the operator's own machine.
+                    const grantedConsent = policyDecision === "prompt" && (consent === "client" || consent === "elicitation") ? consent : undefined;
+                    if (policyDecision === "deny" || (policyDecision === "prompt" && grantedConsent === undefined)) {
+                        // Denied → no frame reaches the app, and the call never starts.
+                        activeEventBus.emit({
+                            kind: "tool_call_finished",
+                            sessionId: resolved.sessionId,
+                            alias: resolved.alias,
+                            data: { name, outcome: "denied" },
+                        });
+                        if (policyDecision === "prompt") {
+                            writeAudit("denied", undefined, undefined, "no_consent_channel");
+                            throw new RpcApplicationError("policy_denied", `Policy requires prompt consent to call "${name}" on session "${resolved.alias}", but no consent channel confirmed it.`, -32000, {
+                                reason: "no_consent_channel",
+                                hint: `This caller did not confirm human consent for "${name}". An MCP client that declares the "elicitation" capability confirms it via an elicitation/create prompt, and Claude Code ≥ v2.1.199 confirms it via the requiresUserInteraction flag, automatically over MCP; every other caller (including the CLI) is denied by design. To change this tool's policy, edit "policy.tools[\"${resolved.alias}/${name}\"]" (or policy.default/policy.destructive) in ${paths.configPath}.`,
+                            });
+                        }
+                        writeAudit("denied", undefined, undefined, "policy");
+                        throw new RpcApplicationError("policy_denied", `Policy denies calling "${name}" on session "${resolved.alias}".`, -32000, { hint: `Edit "policy" in ${paths.configPath} (policy.default/policy.destructive/policy.tools) to change this.` });
+                    }
+                    const startedAt = clock.now().getTime();
+                    const session = { sessionId: resolved.sessionId, alias: resolved.alias };
+                    // `callId` is available synchronously (before the app has answered) precisely so it can
+                    // be exposed to the RPC caller and stamped on every event in this call's lifecycle — the
+                    // MCP server correlates its own in-flight `tools.call` against `tool_call_progress`
+                    // notifications by this id, unambiguous under concurrent calls.
+                    const { callId, result: callResult } = activeCallsManager.call(session, name, args, 
+                    // The caller's explicit `timeoutMs` wins; otherwise the tool's own declared deadline is
+                    // the default, and only if it declares none does `clampTimeout` fall back to
+                    // DEFAULT_CALL_TIMEOUT_MS (issue #25).
+                    timeoutMs ?? tool.timeout_ms);
+                    // If the connection that issued this tools.call drops while the call is still pending
+                    // (CLI Ctrl-C, MCP client disconnect), tell the app to stop rather than leaving an
+                    // orphaned handler running for a caller nobody is waiting on anymore. Unregistered once
+                    // this call settles either way — otherwise a long-lived connection issuing many calls
+                    // (e.g. the MCP server's persistent stream) leaks one closure per call for its lifetime.
+                    const unregisterOnClose = context.onClose(() => {
+                        activeCallsManager.cancel(resolved.sessionId, callId, "connection_closed");
+                    });
+                    activeEventBus.emit({
+                        kind: "tool_call_started",
+                        sessionId: resolved.sessionId,
+                        alias: resolved.alias,
+                        data: { name, callId },
+                    });
+                    try {
+                        const result = await callResult;
+                        activeEventBus.emit({
+                            kind: "tool_call_finished",
+                            sessionId: resolved.sessionId,
+                            alias: resolved.alias,
+                            data: { name, callId, durationMs: clock.now().getTime() - startedAt, outcome: "ok" },
+                        });
+                        writeAudit("ok", undefined, grantedConsent);
+                        return { result, callId };
+                    }
+                    catch (error) {
+                        const errorType = error instanceof RpcApplicationError ? error.type : "tool_execution_error";
+                        const outcome = errorType === "tool_cancelled" ? "cancelled" : "error";
+                        activeEventBus.emit({
+                            kind: "tool_call_finished",
+                            sessionId: resolved.sessionId,
+                            alias: resolved.alias,
+                            data: { name, callId, durationMs: clock.now().getTime() - startedAt, outcome, errorType },
+                        });
+                        writeAudit(outcome, errorType, grantedConsent);
+                        throw error;
+                    }
+                    finally {
+                        unregisterOnClose();
+                    }
+                },
+                [RPC_METHODS.toolsCancel]: (params) => {
+                    const { selector, callId, reason } = asToolsCancelParams(params);
+                    const resolved = activeSessionManager.resolveForTools(selector);
+                    const cancelled = activeCallsManager.cancel(resolved.sessionId, callId, reason ?? "client_cancelled");
+                    return { cancelled };
+                },
+                [RPC_METHODS.eventsSubscribe]: (params, context) => {
+                    const { sessionSelector, kinds } = asEventsSubscribeParams(params);
+                    context.connection.state.eventSubscription = {
+                        sessionSelector,
+                        kinds: kinds ? new Set(kinds) : undefined,
+                    };
+                    return { ok: true };
+                },
+                [RPC_METHODS.eventsSince]: (params) => {
+                    const { selector, since, kinds, limit } = asEventsSinceParams(params);
+                    // Resolved the same way as every other selector-taking method (`sessions.describe`,
+                    // `tools.list`): defaults to the sole active/suspended session, errors on ambiguity, and
+                    // works for a suspended session too — a suspended app's already-retained events are still
+                    // fair game to drain.
+                    const resolved = activeSessionManager.describe(selector);
+                    return activeEventBus.since(resolved.sessionId, { since, kinds, limit });
+                },
+            },
+        });
+        // ARCHITECTURE.md §3: audit retention runs once at startup and once a day thereafter. Both are
+        // fire-and-forget — `prune` never rejects, and a daemon must start (and keep running) whether
+        // or not it can delete an old day file. The interval is cleared in `shutdown` (and in the
+        // startup-failure path below) so it never outlives the daemon that scheduled it.
+        auditPruneInterval = timers.setInterval(() => {
+            void auditLogger.prune();
+        }, AUDIT_PRUNE_INTERVAL_MS);
+        void auditLogger.prune();
+    }
+    catch (error) {
+        // Never leave a half-acquired pidfile/listener/socket behind when startup fails partway through.
+        if (auditPruneInterval !== undefined) {
+            timers.clearInterval(auditPruneInterval);
+            auditPruneInterval = undefined;
+        }
+        callsManager?.disposeAll();
+        sessionManager?.disposeAll(1001, "daemon_startup_failed");
+        await listener?.close();
+        await pidfile?.release();
+        throw error;
+    }
+    // ARCHITECTURE.md §5 lists `daemon_started` among the real event kinds; emitted once startup has
+    // fully succeeded (pidfile/TLS/listener/RPC server all up) so a subscriber never sees it followed
+    // by a startup failure.
+    eventBus.emit({ kind: "daemon_started", data: { version: packageVersion(), pid: process.pid } });
+    return {
+        paths,
+        config,
+        startedAt,
+        server,
+        listener,
+        eventBus,
+        exited,
+        shutdown,
+    };
+};

package/dist/daemon/event-bus.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+import type { EventKind, EventNotification } from "@appduct/shared";
+import type { Clock } from "../cli/types.js";
+export type EventBusEmitInput = Omit<EventNotification, "ts" | "seq"> & {
+    kind: EventKind;
+    ts?: number;
+};
+export type EventBusListener = (event: EventNotification) => void;
+export type EventsSinceQuery = {
+    since?: number;
+    kinds?: EventKind[];
+    limit?: number;
+};
+export type EventsSinceQueryResult = {
+    events: EventNotification[];
+    cursor: number;
+};
+export type EventBus = {
+    emit: (event: EventBusEmitInput) => void;
+    subscribe: (listener: EventBusListener) => () => void;
+    /** Drains the retained buffer for `sessionId`. Returns an empty result (`cursor: 0`) for a
+     * session with no retained events (nothing emitted yet, or its buffer already discarded). */
+    since: (sessionId: string, query?: EventsSinceQuery) => EventsSinceQueryResult;
+    /** Discards `sessionId`'s retained buffer outright, with no event required. Covers the pending-
+     * link discard paths that never reach a terminal event kind (attempt-limit exceeded, the TTL
+     * free-timer) — `TERMINAL_EVENT_KINDS` only catches the ones that *do* emit one. Idempotent. */
+    drop: (sessionId: string) => void;
+};
+export type CreateEventBusOptions = {
+    clock?: Clock;
+    /** Max retained events per session (ARCHITECTURE.md §5's `eventBufferSize`); default 256. */
+    bufferSize?: number;
+};
+export declare const createEventBus: (options?: CreateEventBusOptions) => EventBus;
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/daemon/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/daemon/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,KAAK,CAAC,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzG,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAYlE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IACtD;iGAC6F;IAC7F,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,KAAK,sBAAsB,CAAC;IAC/E;;oGAEgG;IAChG,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,UAAS,qBAA0B,KAAG,QAqGpE,CAAC"}