appduct 0.9.0

package/dist/daemon/sessions.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The session state machine (ARCHITECTURE.md §6, exactly): PENDING (owned by links.ts) →
+ * ACTIVE ⇄ SUSPENDED → EXPIRED, with REVOKED reachable from any live state. This module owns the
+ * live-session map, claim/resume handling (including the pre-auth hardening in the task's
+ * rejection matrix), alias assignment, keepalive-driven suspend, and grace-timer expiry.
+ *
+ * Pending links never enter `sessions` — they live in links.ts's `PendingLinkRegistry` and are
+ * only ever resolved during claim. `sessions` therefore only ever holds live (active/suspended)
+ * sessions; terminal transitions (revoked/expired) remove the entry immediately (ARCHITECTURE.md
+ * §6: "terminal states free the alias" — there is no persisted history, matching §3/§13's "no
+ * per-session files, all state in-daemon-memory").
+ */
+import { type EventMessage, type SessionClaimMessage, type SessionResumeMessage, type SessionSummary, type ToolCallMessage, type ToolCallProgressMessage, type ToolCancelMessage, type ToolErrorMessage, type ToolResultMessage } from "@appduct/shared";
+import type { WebSocket } from "ws";
+import type { Clock } from "../cli/types.js";
+import type { EventBus } from "./event-bus.js";
+import { type CreatedLink } from "./links.js";
+import { type ToolRegistry } from "./registry.js";
+import { type TimerFns } from "./timers.js";
+/** Wire message types allowed *after* claim (session_claim/session_resume are pre-claim only). */
+export declare const POST_CLAIM_MESSAGE_TYPES: Set<string>;
+export declare const isPostClaimMessageType: (type: unknown) => type is string;
+export declare const slugifyDeviceModel: (model?: string) => string;
+export declare const dedupeAlias: (base: string, existingAliases: ReadonlySet<string>) => string;
+export type SessionManagerOptions = {
+    graceSeconds: number;
+    keepaliveIntervalSeconds: number;
+    linkTtlSeconds: number;
+    getEndpoint: () => CreatedLink["endpoint"];
+    eventBus: EventBus;
+    clock?: Clock;
+    timers?: TimerFns;
+    /** Routes a validated `tool_result`/`tool_error`/`tool_call_progress` frame (`calls.ts`
+     * correlates it); wired by the composition root once both modules exist. */
+    onToolFrame?: (message: ToolResultMessage | ToolErrorMessage | ToolCallProgressMessage) => void;
+    /** Routes a validated app-side `event` frame; the composition root forwards it to the event bus
+     * as `app_event` (ARCHITECTURE.md §7). */
+    onAppEvent?: (sessionId: string, alias: string, message: EventMessage) => void;
+};
+export type LinkCreateResult = {
+    sessionId: string;
+    deepLinkPayload: string;
+    endpoint: CreatedLink["endpoint"];
+    expiresAt: number;
+};
+export type SessionManager = {
+    /** `addressOverride` forces the address encoded into this one link's bootstrap payload (task
+     * 07's emulator/simulator fast path); see `links.ts`'s `PendingLinkRegistry.create`. Omits
+     * `LinkCreateResult.pin` — the session manager has no `TlsManager` handle, so the RPC handler
+     * (`daemon.ts`) attaches the current SPKI pin itself before returning to the caller. */
+    createLink: (ttlSeconds?: number, addressOverride?: string) => Omit<LinkCreateResult, "pin">;
+    /** First message on a fresh socket. Returns the claimed sessionId, or `null` after closing the socket. */
+    handleClaim: (socket: WebSocket, message: SessionClaimMessage) => string | null;
+    /** First message on a resume socket. Returns the resumed sessionId, or `null` after closing the socket. */
+    handleResume: (socket: WebSocket, message: SessionResumeMessage) => string | null;
+    /** Dispatches an already-type-checked post-claim message; closes the socket on invalid content. */
+    handlePostClaimMessage: (sessionId: string, socket: WebSocket, message: Record<string, unknown>) => void;
+    list: () => SessionSummary[];
+    /** Links that are still claimable: minted, unclaimed, and inside their TTL. Not sessions (§6),
+     * but live state a daemon restart destroys, so `daemon.status` surfaces the count for issue
+     * #30's safety decision. */
+    pendingLinkCount: () => number;
+    describe: (selector?: string) => SessionSummary;
+    revoke: (selector?: string) => void;
+    /** Resolves a selector for the `tools.*` RPC surface: same selector rules as
+     * `describe`/`revoke` (no_session/ambiguous_session/unknown_session), but returns the pieces
+     * `tools.list`/`tools.call` need directly rather than a wire-shaped summary. */
+    resolveForTools: (selector?: string) => {
+        sessionId: string;
+        alias: string;
+        state: "active" | "suspended";
+        registry: ToolRegistry;
+    };
+    /** Sends a `tool_call` frame to the session's active socket; `false` if the session has no
+     * active socket right now (caller has typically already checked ACTIVE state via
+     * {@link resolveForTools}, but the socket can still disappear between check and send). */
+    sendToolCall: (sessionId: string, message: ToolCallMessage) => boolean;
+    /** Sends a `tool_cancel` frame to the session's active socket; `false` if the session has no
+     * active socket right now. A cancel for an unknown/finished call is the app's problem to
+     * no-op on — the daemon never knows which calls the app still considers in flight. */
+    sendToolCancel: (sessionId: string, message: ToolCancelMessage) => boolean;
+    /** Closes every live socket with the given code (daemon shutdown) and clears all timers. */
+    disposeAll: (code: number, reason: string) => void;
+};
+export declare const createSessionManager: (options: SessionManagerOptions) => SessionManager;
+//# sourceMappingURL=sessions.d.ts.map

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

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

package/dist/daemon/sessions.js

@@ -0,0 +1,429 @@
+/**
+ * The session state machine (ARCHITECTURE.md §6, exactly): PENDING (owned by links.ts) →
+ * ACTIVE ⇄ SUSPENDED → EXPIRED, with REVOKED reachable from any live state. This module owns the
+ * live-session map, claim/resume handling (including the pre-auth hardening in the task's
+ * rejection matrix), alias assignment, keepalive-driven suspend, and grace-timer expiry.
+ *
+ * Pending links never enter `sessions` — they live in links.ts's `PendingLinkRegistry` and are
+ * only ever resolved during claim. `sessions` therefore only ever holds live (active/suspended)
+ * sessions; terminal transitions (revoked/expired) remove the entry immediately (ARCHITECTURE.md
+ * §6: "terminal states free the alias" — there is no persisted history, matching §3/§13's "no
+ * per-session files, all state in-daemon-memory").
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { isEventMessage, isToolCallProgressMessage, isToolErrorMessage, isToolRegistryDeltaMessage, isToolRegistrySnapshotMessage, isToolResultMessage, parseSessionClaimDeviceFields, } from "@appduct/shared";
+import { createPendingLinkRegistry } from "./links.js";
+import { RpcApplicationError } from "./rpc-server.js";
+import { createToolRegistry } from "./registry.js";
+import { systemTimers } from "./timers.js";
+const RESUME_TOKEN_BYTES = 32;
+/** Wire message types allowed *after* claim (session_claim/session_resume are pre-claim only). */
+export const POST_CLAIM_MESSAGE_TYPES = new Set([
+    "tool_registry_snapshot",
+    "tool_registry_delta",
+    "tool_result",
+    "tool_error",
+    "tool_call_progress",
+    "event",
+]);
+export const isPostClaimMessageType = (type) => {
+    return typeof type === "string" && POST_CLAIM_MESSAGE_TYPES.has(type);
+};
+export const slugifyDeviceModel = (model) => {
+    if (!model) {
+        return "device";
+    }
+    const slug = model
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/gu, "-")
+        .replaceAll(/^-+|-+$/gu, "");
+    return slug.length > 0 ? slug : "device";
+};
+export const dedupeAlias = (base, existingAliases) => {
+    if (!existingAliases.has(base)) {
+        return base;
+    }
+    let suffix = 2;
+    while (existingAliases.has(`${base}-${suffix}`)) {
+        suffix += 1;
+    }
+    return `${base}-${suffix}`;
+};
+const decodeFixedLengthToken = (base64url, expectedLength) => {
+    let decoded;
+    try {
+        decoded = Buffer.from(base64url, "base64url");
+    }
+    catch {
+        return null;
+    }
+    return decoded.length === expectedLength ? decoded : null;
+};
+/** Constant-time-safe comparison: never calls `timingSafeEqual` on mismatched lengths (it throws). */
+const tokensMatch = (candidate, expected) => {
+    if (!candidate || candidate.length !== expected.length) {
+        return false;
+    }
+    return timingSafeEqual(candidate, expected);
+};
+const MAX_FAILED_CLAIM_ATTEMPTS = 5;
+const closeSocket = (socket, code, reason) => {
+    try {
+        socket.close(code, reason);
+    }
+    catch {
+        // The socket may already be closing/closed; never let a double-close crash the daemon.
+        socket.terminate();
+    }
+};
+export const createSessionManager = (options) => {
+    const clock = options.clock ?? { now: () => new Date() };
+    const timers = options.timers ?? systemTimers;
+    const sessions = new Map();
+    const pendingLinks = createPendingLinkRegistry({
+        getEndpoint: options.getEndpoint,
+        clock,
+        timers,
+        eventBus: options.eventBus,
+    });
+    const emit = (kind, sessionId, alias, data) => {
+        options.eventBus.emit({ kind, sessionId, alias, data });
+    };
+    const toSummary = (session) => {
+        return {
+            sessionId: session.sessionId,
+            alias: session.alias,
+            state: session.state,
+            device: session.device,
+            createdAt: session.createdAt.toISOString(),
+            claimedAt: session.claimedAt.toISOString(),
+            ...(session.suspendedAt ? { suspendedAt: session.suspendedAt.toISOString() } : {}),
+            toolCount: session.registry.count(),
+        };
+    };
+    const resolveSession = (selector) => {
+        const live = Array.from(sessions.values());
+        if (selector !== undefined) {
+            const match = live.find((session) => session.sessionId === selector || session.alias === selector);
+            if (!match) {
+                throw new RpcApplicationError("unknown_session", `No session matches "${selector}".`);
+            }
+            return match;
+        }
+        if (live.length === 0) {
+            throw new RpcApplicationError("no_session", "No active or suspended session, and none was specified.");
+        }
+        if (live.length > 1) {
+            throw new RpcApplicationError("ambiguous_session", `Multiple sessions are live (${live.map((session) => session.alias).join(", ")}); specify a selector.`);
+        }
+        return live[0];
+    };
+    const assignAlias = (model) => {
+        const base = slugifyDeviceModel(model);
+        const existing = new Set(Array.from(sessions.values(), (session) => session.alias));
+        return dedupeAlias(base, existing);
+    };
+    const sendAck = (socket, session) => {
+        const ack = {
+            type: "session_ack",
+            session_id: session.sessionId,
+            status: "ok",
+            alias: session.alias,
+            resume_token: session.resumeToken.toString("base64url"),
+            keepalive_interval_s: options.keepaliveIntervalSeconds,
+            grace_s: options.graceSeconds,
+        };
+        socket.send(JSON.stringify(ack), (error) => {
+            if (error) {
+                // The 'close'/'error' listeners (attached below) own recovery; a failed send must never
+                // throw into the socket library's event loop turn (v1's exact defect).
+                closeSocket(socket, 1011, "send_failed");
+            }
+        });
+    };
+    const suspend = (sessionId) => {
+        const session = sessions.get(sessionId);
+        if (!session || session.state !== "active") {
+            return;
+        }
+        session.state = "suspended";
+        session.suspendedAt = clock.now();
+        session.socket = undefined;
+        session.missedPongs = 0;
+        session.graceTimer = timers.setTimeout(() => expire(sessionId), options.graceSeconds * 1000);
+        emit("session_suspended", session.sessionId, session.alias, {});
+    };
+    const expire = (sessionId) => {
+        const session = sessions.get(sessionId);
+        if (!session || session.state !== "suspended") {
+            return;
+        }
+        sessions.delete(sessionId);
+        emit("session_expired", session.sessionId, session.alias, {});
+    };
+    const attachSocketHandlers = (session) => {
+        const socket = session.socket;
+        socket.on("error", () => {
+            // Never let an unhandled 'error' crash the daemon (v1's fatal defect) — 'close' still fires
+            // after 'error' and drives the suspend transition.
+        });
+        socket.on("pong", () => {
+            session.missedPongs = 0;
+        });
+        socket.on("close", () => {
+            if (session.socket === socket) {
+                suspend(session.sessionId);
+            }
+        });
+    };
+    // Server-side keepalive (ARCHITECTURE.md §7): ping every `keepaliveIntervalSeconds`; two missed
+    // pongs in a row is treated as socket loss and suspends the session (never crashes the daemon).
+    const keepaliveInterval = timers.setInterval(() => {
+        for (const session of sessions.values()) {
+            if (session.state !== "active" || !session.socket) {
+                continue;
+            }
+            if (session.missedPongs >= 2) {
+                const staleSocket = session.socket;
+                session.socket = undefined;
+                suspend(session.sessionId);
+                staleSocket.terminate();
+                continue;
+            }
+            session.missedPongs += 1;
+            try {
+                session.socket.ping();
+            }
+            catch {
+                // A ping failure is surfaced via the socket's own 'error'/'close' handlers.
+            }
+        }
+    }, options.keepaliveIntervalSeconds * 1000);
+    const createLink = (ttlSeconds, addressOverride) => {
+        const { link, deepLinkPayload, endpoint } = pendingLinks.create(ttlSeconds ?? options.linkTtlSeconds, addressOverride);
+        return {
+            sessionId: link.sessionId,
+            deepLinkPayload,
+            endpoint,
+            expiresAt: Math.floor(link.expiresAt.getTime() / 1000),
+        };
+    };
+    const handleClaim = (socket, message) => {
+        const pending = pendingLinks.get(message.session_id);
+        if (!pending) {
+            if (sessions.has(message.session_id)) {
+                closeSocket(socket, 1008, "already_claimed");
+            }
+            else {
+                closeSocket(socket, 1008, "unknown_session");
+            }
+            return null;
+        }
+        const nowMs = clock.now().getTime();
+        if (pending.expiresAt.getTime() <= nowMs) {
+            pendingLinks.discard(pending.sessionId);
+            closeSocket(socket, 1008, "link_expired");
+            return null;
+        }
+        const candidateToken = decodeFixedLengthToken(message.token, pending.token.length);
+        if (!tokensMatch(candidateToken, pending.token)) {
+            // ARCHITECTURE.md §6: the token is invalidated "after 5 failed claim attempts" — the 5th
+            // failure itself invalidates the link (a correct token on a would-be 6th attempt must not
+            // still claim).
+            const attempts = pendingLinks.recordFailedAttempt(pending.sessionId);
+            if (attempts >= MAX_FAILED_CLAIM_ATTEMPTS) {
+                pendingLinks.discard(pending.sessionId);
+                closeSocket(socket, 1008, "claim_attempts_exceeded");
+            }
+            else {
+                closeSocket(socket, 1008, "invalid_token");
+            }
+            return null;
+        }
+        pendingLinks.consume(pending.sessionId);
+        const deviceFields = parseSessionClaimDeviceFields(message);
+        const device = deviceFields && deviceFields !== "invalid" ? deviceFields : {};
+        const alias = assignAlias(device.model);
+        const sessionId = pending.sessionId;
+        const session = {
+            sessionId,
+            alias,
+            state: "active",
+            device,
+            createdAt: pending.createdAt,
+            claimedAt: clock.now(),
+            resumeToken: randomBytes(RESUME_TOKEN_BYTES),
+            socket,
+            missedPongs: 0,
+            registry: createToolRegistry(() => {
+                emit("tools_changed", sessionId, alias, { toolCount: session.registry.count() });
+            }),
+        };
+        sessions.set(sessionId, session);
+        attachSocketHandlers(session);
+        sendAck(socket, session);
+        emit("session_claimed", sessionId, alias, { device });
+        return sessionId;
+    };
+    const handleResume = (socket, message) => {
+        const session = sessions.get(message.session_id);
+        if (!session) {
+            closeSocket(socket, 1008, "unknown_session");
+            return null;
+        }
+        const candidateToken = decodeFixedLengthToken(message.resume_token, session.resumeToken.length);
+        if (!tokensMatch(candidateToken, session.resumeToken)) {
+            closeSocket(socket, 1008, "invalid_resume_token");
+            return null;
+        }
+        // Resuming an ACTIVE session is a socket replacement (e.g. app reconnected before the old
+        // socket's close event was observed) rather than an error: adopt the new socket, drop the old.
+        if (session.state === "active" && session.socket && session.socket !== socket) {
+            const staleSocket = session.socket;
+            session.socket = undefined; // prevents the stale socket's 'close' handler from suspending us
+            closeSocket(staleSocket, 1000, "session_replaced");
+        }
+        if (session.graceTimer) {
+            timers.clearTimeout(session.graceTimer);
+            session.graceTimer = undefined;
+        }
+        session.resumeToken = randomBytes(RESUME_TOKEN_BYTES);
+        session.state = "active";
+        session.suspendedAt = undefined;
+        session.socket = socket;
+        session.missedPongs = 0;
+        attachSocketHandlers(session);
+        sendAck(socket, session);
+        emit("session_resumed", session.sessionId, session.alias, {});
+        return session.sessionId;
+    };
+    const handlePostClaimMessage = (sessionId, socket, message) => {
+        const session = sessions.get(sessionId);
+        if (!session) {
+            closeSocket(socket, 1008, "unknown_session");
+            return;
+        }
+        switch (message.type) {
+            case "tool_registry_snapshot": {
+                if (!isToolRegistrySnapshotMessage(message)) {
+                    closeSocket(socket, 1008, "invalid_registry");
+                    return;
+                }
+                session.registry.snapshot(message.tools);
+                return;
+            }
+            case "tool_registry_delta": {
+                if (!isToolRegistryDeltaMessage(message)) {
+                    closeSocket(socket, 1008, "invalid_registry");
+                    return;
+                }
+                if (message.operation === "upsert") {
+                    session.registry.upsert(message.tool);
+                }
+                else {
+                    session.registry.remove(message.name);
+                }
+                return;
+            }
+            case "tool_result": {
+                if (!isToolResultMessage(message)) {
+                    closeSocket(socket, 1008, "invalid_message");
+                    return;
+                }
+                options.onToolFrame?.(message);
+                return;
+            }
+            case "tool_error": {
+                if (!isToolErrorMessage(message)) {
+                    closeSocket(socket, 1008, "invalid_message");
+                    return;
+                }
+                options.onToolFrame?.(message);
+                return;
+            }
+            case "tool_call_progress": {
+                if (!isToolCallProgressMessage(message)) {
+                    closeSocket(socket, 1008, "invalid_message");
+                    return;
+                }
+                options.onToolFrame?.(message);
+                return;
+            }
+            case "event": {
+                if (!isEventMessage(message)) {
+                    closeSocket(socket, 1008, "invalid_message");
+                    return;
+                }
+                options.onAppEvent?.(sessionId, session.alias, message);
+                return;
+            }
+            default:
+                closeSocket(socket, 1008, "unknown_message_type");
+        }
+    };
+    const revoke = (selector) => {
+        // sessions.revoke is reachable from any state (ARCHITECTURE.md §6), including an unclaimed
+        // pending link — but only when explicitly selected by sessionId (pending links have no alias
+        // and are never eligible for the "exactly one live session" implicit-selector default).
+        if (selector !== undefined && !sessions.has(selector) && pendingLinks.get(selector)) {
+            pendingLinks.discard(selector);
+            emit("session_revoked", selector, undefined, {});
+            return;
+        }
+        const session = resolveSession(selector);
+        if (session.graceTimer) {
+            timers.clearTimeout(session.graceTimer);
+        }
+        if (session.socket) {
+            closeSocket(session.socket, 1000, "revoked");
+        }
+        sessions.delete(session.sessionId);
+        emit("session_revoked", session.sessionId, session.alias, {});
+    };
+    const disposeAll = (code, reason) => {
+        timers.clearInterval(keepaliveInterval);
+        pendingLinks.disposeAll();
+        for (const session of sessions.values()) {
+            if (session.graceTimer) {
+                timers.clearTimeout(session.graceTimer);
+            }
+            if (session.socket) {
+                closeSocket(session.socket, code, reason);
+            }
+        }
+        sessions.clear();
+    };
+    const resolveForTools = (selector) => {
+        const session = resolveSession(selector);
+        return { sessionId: session.sessionId, alias: session.alias, state: session.state, registry: session.registry };
+    };
+    const sendToApp = (sessionId, message) => {
+        const session = sessions.get(sessionId);
+        if (!session || session.state !== "active" || !session.socket) {
+            return false;
+        }
+        const socket = session.socket;
+        socket.send(JSON.stringify(message), (error) => {
+            if (error) {
+                // A failed send must never throw into the socket library's event loop turn (v1's exact
+                // defect); the resulting 'close'/'error' drives suspend, which rejects the pending call.
+                closeSocket(socket, 1011, "send_failed");
+            }
+        });
+        return true;
+    };
+    return {
+        createLink,
+        handleClaim,
+        handleResume,
+        handlePostClaimMessage,
+        list: () => Array.from(sessions.values(), toSummary),
+        pendingLinkCount: () => pendingLinks.claimableCount(),
+        describe: (selector) => toSummary(resolveSession(selector)),
+        revoke,
+        resolveForTools,
+        sendToolCall: sendToApp,
+        sendToolCancel: sendToApp,
+        disposeAll,
+    };
+};

package/dist/daemon/socket-probe.d.ts

@@ -0,0 +1,16 @@
+/**
+ * "Is anything listening on the control socket?" — the cheapest liveness signal the state dir
+ * offers, and the one that answers fastest when a daemon is up.
+ *
+ * It lives in its own module rather than in `rpc/client.ts` (its first caller) because
+ * `daemon/log-rotation.ts` needs it too, and `rpc/client.ts` already imports *that*. Keeping the
+ * probe here means neither has to import the other.
+ */
+/**
+ * Resolves `true` when a connection to `socketPath` is accepted. A refusal, a missing socket file,
+ * or any other error resolves `false` — this never rejects, so callers can use it as a plain
+ * predicate. Note it proves a listener exists *right now*; it cannot prove one will not appear a
+ * moment later.
+ */
+export declare const isSocketConnectable: (socketPath: string) => Promise<boolean>;
+//# sourceMappingURL=socket-probe.d.ts.map

package/dist/daemon/socket-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-probe.d.ts","sourceRoot":"","sources":["../../src/daemon/socket-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,KAAG,OAAO,CAAC,OAAO,CAcvE,CAAC"}

package/dist/daemon/socket-probe.js

@@ -0,0 +1,28 @@
+/**
+ * "Is anything listening on the control socket?" — the cheapest liveness signal the state dir
+ * offers, and the one that answers fastest when a daemon is up.
+ *
+ * It lives in its own module rather than in `rpc/client.ts` (its first caller) because
+ * `daemon/log-rotation.ts` needs it too, and `rpc/client.ts` already imports *that*. Keeping the
+ * probe here means neither has to import the other.
+ */
+import { connect } from "node:net";
+/**
+ * Resolves `true` when a connection to `socketPath` is accepted. A refusal, a missing socket file,
+ * or any other error resolves `false` — this never rejects, so callers can use it as a plain
+ * predicate. Note it proves a listener exists *right now*; it cannot prove one will not appear a
+ * moment later.
+ */
+export const isSocketConnectable = (socketPath) => {
+    return new Promise((resolve) => {
+        const socket = connect(socketPath);
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+};

package/dist/daemon/state-dir.d.ts

@@ -0,0 +1,31 @@
+/**
+ * State directory resolution and layout (ARCHITECTURE.md §3).
+ *
+ * Default `~/.appduct/`, overridable with `APPDUCT_STATE_DIR` (tests rely on the
+ * override). Created lazily with mode `0700`.
+ */
+export type StateDirPaths = {
+    /** The state directory root. */
+    root: string;
+    /** Unix domain control socket. Windows named pipes would plug in behind {@link getSocketPath}. */
+    socketPath: string;
+    pidFilePath: string;
+    logFilePath: string;
+    keyPath: string;
+    configPath: string;
+    auditDir: string;
+    /** Exclusive spawn-lock file used by the auto-spawning RPC client to prevent double-spawn races. */
+    spawnLockPath: string;
+};
+/** Resolves the state directory: explicit `override`, else `APPDUCT_STATE_DIR`, else `~/.appduct`. */
+export declare const resolveStateDir: (override?: string) => string;
+export declare const getStateDirPaths: (stateDir: string) => StateDirPaths;
+/**
+ * Single seam for the control-socket address. Today this is always the UDS path; a Windows
+ * named-pipe implementation (`\\.\pipe\appduct-<user>`) plugs in here without touching any
+ * caller (ARCHITECTURE.md §13 — best-effort, not blocking v2.0).
+ */
+export declare const getSocketPath: (paths: StateDirPaths) => string;
+/** Creates the state dir (and `audit/`) with mode `0700` if missing; tightens the mode if it exists. */
+export declare const ensureStateDir: (stateDir: string) => Promise<StateDirPaths>;
+//# sourceMappingURL=state-dir.d.ts.map

package/dist/daemon/state-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-dir.d.ts","sourceRoot":"","sources":["../../src/daemon/state-dir.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,aAAa,GAAG;IAC1B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,oGAAoG;IACpG,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,sGAAsG;AACtG,eAAO,MAAM,eAAe,GAAI,WAAW,MAAM,KAAG,MAEnD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,UAAU,MAAM,KAAG,aAWnD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,aAAa,KAAG,MAEpD,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,aAAa,CAU5E,CAAC"}

package/dist/daemon/state-dir.js

@@ -0,0 +1,43 @@
+/**
+ * State directory resolution and layout (ARCHITECTURE.md §3).
+ *
+ * Default `~/.appduct/`, overridable with `APPDUCT_STATE_DIR` (tests rely on the
+ * override). Created lazily with mode `0700`.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, chmod } from "node:fs/promises";
+/** Resolves the state directory: explicit `override`, else `APPDUCT_STATE_DIR`, else `~/.appduct`. */
+export const resolveStateDir = (override) => {
+    return override ?? process.env.APPDUCT_STATE_DIR ?? join(homedir(), ".appduct");
+};
+export const getStateDirPaths = (stateDir) => {
+    return {
+        root: stateDir,
+        socketPath: join(stateDir, "daemon.sock"),
+        pidFilePath: join(stateDir, "daemon.pid"),
+        logFilePath: join(stateDir, "daemon.log"),
+        keyPath: join(stateDir, "key.pem"),
+        configPath: join(stateDir, "config.json"),
+        auditDir: join(stateDir, "audit"),
+        spawnLockPath: join(stateDir, "daemon.spawn.lock"),
+    };
+};
+/**
+ * Single seam for the control-socket address. Today this is always the UDS path; a Windows
+ * named-pipe implementation (`\\.\pipe\appduct-<user>`) plugs in here without touching any
+ * caller (ARCHITECTURE.md §13 — best-effort, not blocking v2.0).
+ */
+export const getSocketPath = (paths) => {
+    return paths.socketPath;
+};
+/** Creates the state dir (and `audit/`) with mode `0700` if missing; tightens the mode if it exists. */
+export const ensureStateDir = async (stateDir) => {
+    const paths = getStateDirPaths(stateDir);
+    await mkdir(paths.auditDir, { recursive: true });
+    await chmod(paths.root, 0o700);
+    // `mkdir` honors the process umask (commonly 0o022, yielding drwxr-xr-x); tighten explicitly so
+    // `audit/` matches every other path under the state dir (ARCHITECTURE.md §3).
+    await chmod(paths.auditDir, 0o700);
+    return paths;
+};

package/dist/daemon/timers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Injectable timer seam (LOOP.md: "use injectable clock/timer seams for tests"). Every daemon
+ * module that schedules a TTL/grace/pre-claim/keepalive timer takes a {@link TimerFns} so tests
+ * can substitute an implementation that fires deterministically instead of waiting on real wall
+ * time, and so every timer this package creates can be traced back to a single seam for cleanup.
+ */
+export type TimerHandle = ReturnType<typeof setTimeout>;
+export type IntervalHandle = ReturnType<typeof setInterval>;
+export type TimerFns = {
+    setTimeout: (callback: () => void, ms: number) => TimerHandle;
+    clearTimeout: (handle: TimerHandle) => void;
+    setInterval: (callback: () => void, ms: number) => IntervalHandle;
+    clearInterval: (handle: IntervalHandle) => void;
+};
+export declare const systemTimers: TimerFns;
+//# sourceMappingURL=timers.d.ts.map