@botcord/daemon 0.1.1

package/dist/gateway/runtimes/gemini.js

@@ -0,0 +1,29 @@
+import { readCommandVersion, resolveCommandOnPath, } from "./probe.js";
+/** Resolve the Gemini CLI executable on PATH. */
+export function resolveGeminiCommand(deps = {}) {
+    return resolveCommandOnPath("gemini", deps);
+}
+/** Probe whether the Gemini CLI is installed and report its version. */
+export function probeGemini(deps = {}) {
+    const command = resolveGeminiCommand(deps);
+    if (!command)
+        return { available: false };
+    return {
+        available: true,
+        path: command,
+        version: readCommandVersion(command, [], deps) ?? undefined,
+    };
+}
+/**
+ * Gemini adapter stub — probe() is wired up so `botcord-daemon doctor` can report it.
+ * run() is not implemented yet; routing a turn here will surface the error upstream.
+ */
+export class GeminiAdapter {
+    id = "gemini";
+    probe() {
+        return probeGemini();
+    }
+    async run(_opts) {
+        throw new Error("gemini adapter not implemented");
+    }
+}

package/dist/gateway/runtimes/ndjson-stream.d.ts

@@ -0,0 +1,43 @@
+import type { RuntimeAdapter, RuntimeProbeResult, RuntimeRunOptions, RuntimeRunResult, StreamBlock } from "../types.js";
+/**
+ * Mutable state threaded through event callbacks while a single turn runs.
+ * The base class reads these fields to assemble the final RuntimeRunResult.
+ */
+export interface NdjsonRunState {
+    /** Session id to persist for `--resume`. Seeded with the incoming sessionId. */
+    newSessionId: string;
+    /** Final text reported by a terminal "result"/"completed" event, if any. */
+    finalText: string;
+    /** Streamed assistant text chunks; concatenated as a fallback when finalText is empty. */
+    assistantTextChunks: string[];
+    /** Running byte total of everything pushed to assistantTextChunks. */
+    assistantTextBytes: number;
+    /** True once the per-turn text cap was hit; further chunks are dropped. */
+    assistantTextCapped: boolean;
+    costUsd?: number;
+    errorText?: string;
+}
+/** Per-event context handed to subclasses from the ndjson dispatch loop. */
+export interface NdjsonEventCtx {
+    state: NdjsonRunState;
+    /** 1-based sequence within this turn, identical to what `onBlock` would see. */
+    seq: number;
+    /** Forward a normalized StreamBlock to the caller's onBlock handler. */
+    emitBlock: (block: StreamBlock) => void;
+    /**
+     * Push streamed assistant text while respecting the per-turn byte cap.
+     * Subclasses should use this instead of `state.assistantTextChunks.push(...)`.
+     */
+    appendAssistantText: (text: string) => void;
+}
+/** Base class for runtime adapters that drive a CLI emitting newline-delimited JSON. */
+export declare abstract class NdjsonStreamAdapter implements RuntimeAdapter {
+    abstract readonly id: string;
+    probe?(): RuntimeProbeResult;
+    protected abstract resolveBinary(opts: RuntimeRunOptions): string;
+    protected abstract buildArgs(opts: RuntimeRunOptions): string[];
+    protected abstract handleEvent(obj: unknown, ctx: NdjsonEventCtx): void;
+    /** Override to tweak env (FORCE_COLOR=0, NO_COLOR=1, etc). */
+    protected spawnEnv(_opts: RuntimeRunOptions): NodeJS.ProcessEnv;
+    run(opts: RuntimeRunOptions): Promise<RuntimeRunResult>;
+}

package/dist/gateway/runtimes/ndjson-stream.js

@@ -0,0 +1,169 @@
+import { spawn } from "node:child_process";
+import { consoleLogger } from "../log.js";
+const log = consoleLogger;
+/**
+ * Common scaffold for CLI adapters that emit newline-delimited JSON on stdout.
+ * Subclasses plug in:
+ *   - resolveBinary() — which executable to spawn
+ *   - buildArgs()     — argv tail (excluding the binary itself)
+ *   - handleEvent()   — how to interpret one parsed JSON object
+ *
+ * The base class handles spawn, abort wiring, stderr capping, line splitting,
+ * and exit-code error synthesis so every new runtime only writes the parts
+ * that are actually runtime-specific.
+ */
+/** How much stderr is retained for error reporting. */
+const STDERR_TAIL_CAP = 8 * 1024;
+/** How much of the retained stderr is included in the synthesized exit-code error. */
+const STDERR_ERROR_SNIPPET = 500;
+/** Cap on total streamed assistant text bytes per turn — guards against a runaway CLI. */
+const ASSISTANT_TEXT_CAP = 1 * 1024 * 1024;
+/** Grace period between SIGTERM and SIGKILL when an abort is requested. */
+const KILL_GRACE_MS = 5_000;
+/** Base class for runtime adapters that drive a CLI emitting newline-delimited JSON. */
+export class NdjsonStreamAdapter {
+    /** Override to tweak env (FORCE_COLOR=0, NO_COLOR=1, etc). */
+    spawnEnv(_opts) {
+        return process.env;
+    }
+    async run(opts) {
+        if (opts.signal.aborted) {
+            return {
+                text: "",
+                newSessionId: opts.sessionId ?? "",
+                error: `${this.id} aborted before spawn`,
+            };
+        }
+        const binary = this.resolveBinary(opts);
+        const args = this.buildArgs(opts);
+        log.debug(`${this.id} spawn`, {
+            cwd: opts.cwd,
+            sessionId: opts.sessionId,
+            argv: args,
+        });
+        const child = spawn(binary, args, {
+            cwd: opts.cwd,
+            env: this.spawnEnv(opts),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Attach abort listener immediately — spawn is synchronous, but a racing
+        // `.abort()` between `spawn` and a listener added later would be lost.
+        let killTimer = null;
+        const onAbort = () => {
+            if (child.killed)
+                return;
+            child.kill("SIGTERM");
+            // Escalate to SIGKILL if the child ignores the polite request.
+            killTimer = setTimeout(() => {
+                if (!child.killed) {
+                    log.warn(`${this.id} did not exit after SIGTERM; sending SIGKILL`);
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+            }, KILL_GRACE_MS);
+            if (typeof killTimer.unref === "function")
+                killTimer.unref();
+        };
+        opts.signal.addEventListener("abort", onAbort, { once: true });
+        const state = {
+            newSessionId: opts.sessionId ?? "",
+            finalText: "",
+            assistantTextChunks: [],
+            assistantTextBytes: 0,
+            assistantTextCapped: false,
+        };
+        const appendAssistantText = (text) => {
+            if (!text)
+                return;
+            if (state.assistantTextCapped)
+                return;
+            const budget = ASSISTANT_TEXT_CAP - state.assistantTextBytes;
+            if (budget <= 0) {
+                state.assistantTextCapped = true;
+                log.warn(`${this.id} assistant text exceeded ${ASSISTANT_TEXT_CAP} bytes; dropping further chunks`);
+                return;
+            }
+            if (text.length > budget) {
+                state.assistantTextChunks.push(text.slice(0, budget));
+                state.assistantTextBytes += budget;
+                state.assistantTextCapped = true;
+                log.warn(`${this.id} assistant text hit ${ASSISTANT_TEXT_CAP}-byte cap`);
+                return;
+            }
+            state.assistantTextChunks.push(text);
+            state.assistantTextBytes += text.length;
+        };
+        let stderrTail = "";
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CAP);
+        });
+        let seq = 0;
+        let stdoutBuf = "";
+        child.stdout.setEncoding("utf8");
+        const dispatchLine = (line) => {
+            if (!line)
+                return;
+            let obj;
+            try {
+                obj = JSON.parse(line);
+            }
+            catch {
+                log.warn(`${this.id} non-json stdout line`, { line: line.slice(0, 200) });
+                return;
+            }
+            seq += 1;
+            try {
+                this.handleEvent(obj, {
+                    state,
+                    seq,
+                    emitBlock: (b) => opts.onBlock?.(b),
+                    appendAssistantText,
+                });
+            }
+            catch (err) {
+                log.warn(`${this.id} event handler threw`, { err: String(err) });
+            }
+        };
+        child.stdout.on("data", (chunk) => {
+            stdoutBuf += chunk;
+            let idx;
+            while ((idx = stdoutBuf.indexOf("\n")) !== -1) {
+                const line = stdoutBuf.slice(0, idx).trim();
+                stdoutBuf = stdoutBuf.slice(idx + 1);
+                dispatchLine(line);
+            }
+        });
+        let code = 0;
+        try {
+            code = await new Promise((resolve, reject) => {
+                child.on("error", reject);
+                child.on("close", (c) => resolve(c ?? 0));
+            });
+        }
+        finally {
+            opts.signal.removeEventListener("abort", onAbort);
+            if (killTimer)
+                clearTimeout(killTimer);
+        }
+        // Flush any final line that lacked a terminating newline.
+        const residual = stdoutBuf.trim();
+        if (residual)
+            dispatchLine(residual);
+        if (code !== 0 && !state.errorText) {
+            state.errorText = `${this.id} exited with code ${code}: ${stderrTail.slice(-STDERR_ERROR_SNIPPET)}`;
+        }
+        const rawText = state.finalText || state.assistantTextChunks.join("").trim();
+        const text = rawText.length > ASSISTANT_TEXT_CAP ? rawText.slice(0, ASSISTANT_TEXT_CAP) : rawText;
+        return {
+            text,
+            newSessionId: state.newSessionId,
+            ...(state.costUsd !== undefined ? { costUsd: state.costUsd } : {}),
+            ...(state.errorText ? { error: state.errorText } : {}),
+        };
+    }
+}

package/dist/gateway/runtimes/probe.d.ts

@@ -0,0 +1,17 @@
+import { execFileSync } from "node:child_process";
+/** Injection seam for PATH resolution + version probes, so tests can stub syscalls. */
+export interface ProbeDeps {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    execFileSyncFn?: typeof execFileSync;
+    existsSyncFn?: (p: string) => boolean;
+}
+/** Resolve a command name on PATH via `which`/`where`; returns null when missing. */
+export declare function resolveCommandOnPath(command: string, deps?: ProbeDeps): string | null;
+/** Return the first path in `candidates` that exists on disk, or null. */
+export declare function firstExistingPath(candidates: string[], deps?: ProbeDeps): string | null;
+/** Run `<command> [...args] --version` and return the first output line, or null. */
+export declare function readCommandVersion(command: string, args?: string[], deps?: ProbeDeps): string | null;
+/** Join `relativePath` against HOME (falls back to empty when unset). */
+export declare function resolveHomePath(relativePath: string, deps?: ProbeDeps): string;

package/dist/gateway/runtimes/probe.js

@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+function normalizeExecOutput(raw) {
+    return Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw ?? "");
+}
+/** Resolve a command name on PATH via `which`/`where`; returns null when missing. */
+export function resolveCommandOnPath(command, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const env = deps.env ?? process.env;
+    const execFn = deps.execFileSyncFn ?? execFileSync;
+    const locator = platform === "win32" ? "where" : "which";
+    try {
+        const out = normalizeExecOutput(execFn(locator, [command], {
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+        }));
+        const resolved = out.trim().split(/\r?\n/)[0];
+        return resolved || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Return the first path in `candidates` that exists on disk, or null. */
+export function firstExistingPath(candidates, deps = {}) {
+    const exists = deps.existsSyncFn ?? existsSync;
+    for (const c of candidates) {
+        if (exists(c))
+            return c;
+    }
+    return null;
+}
+/** Run `<command> [...args] --version` and return the first output line, or null. */
+export function readCommandVersion(command, args = [], deps = {}) {
+    const env = deps.env ?? process.env;
+    const execFn = deps.execFileSyncFn ?? execFileSync;
+    try {
+        const out = normalizeExecOutput(execFn(command, [...args, "--version"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env,
+            timeout: 5000,
+        }));
+        return out.trim().split(/\r?\n/)[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Join `relativePath` against HOME (falls back to empty when unset). */
+export function resolveHomePath(relativePath, deps = {}) {
+    const home = deps.homeDir ?? deps.env?.HOME ?? process.env.HOME ?? "";
+    return path.join(home, relativePath);
+}

package/dist/gateway/runtimes/registry.d.ts

@@ -0,0 +1,59 @@
+import type { RuntimeAdapter, RuntimeProbeResult } from "../types.js";
+/**
+ * Metadata + factory for a single runtime adapter, used by the registry.
+ * Add a new runtime by exporting one of these from the adapter file and
+ * registering it in `REGISTRY` below.
+ */
+export interface RuntimeModule {
+    id: string;
+    displayName: string;
+    /** Canonical PATH binary name — shown in `doctor` output. */
+    binary: string;
+    /**
+     * Env var that overrides the resolved CLI path for this adapter.
+     * Defaults to `BOTCORD_<ID>_BIN` with dashes → underscores, uppercased.
+     */
+    envVar?: string;
+    /** Module-level probe so callers don't have to instantiate the adapter. */
+    probe(): RuntimeProbeResult;
+    create(): RuntimeAdapter;
+    /**
+     * Whether `create().run()` is implemented. Defaults to true. Stubs
+     * (e.g. gemini until we wire its driver) should set `false` so the
+     * config loader rejects routing turns to this adapter.
+     */
+    supportsRun?: boolean;
+}
+/** Built-in runtime module entry for Claude Code. */
+export declare const claudeCodeModule: RuntimeModule;
+/** Built-in runtime module entry for Codex. */
+export declare const codexModule: RuntimeModule;
+/** Built-in runtime module entry for Gemini (probe-only stub). */
+export declare const geminiModule: RuntimeModule;
+/**
+ * Built-in runtime modules. To add a new runtime:
+ *   1. Create `runtimes/<name>.ts` extending `NdjsonStreamAdapter` (or
+ *      implementing `RuntimeAdapter` directly).
+ *   2. Add a `RuntimeModule` entry + register it here.
+ */
+export declare const RUNTIME_MODULES: readonly RuntimeModule[];
+/** Lookup a runtime module by id, or null when the id is unknown. */
+export declare function getRuntimeModule(id: string): RuntimeModule | null;
+/** All registered runtime ids in registration order. */
+export declare function listRuntimeIds(): string[];
+/** Env var name used to override the binary path for a given runtime id. */
+export declare function envVarForRuntime(id: string): string;
+/** Instantiate a single runtime adapter by id; throws if unknown. */
+export declare function createRuntime(id: string): RuntimeAdapter;
+/** Instantiate every registered runtime — used as the dispatcher default. */
+export declare function createAllRuntimes(): Record<string, RuntimeAdapter>;
+/** One probe result per registered runtime, for `doctor`-style listings. */
+export interface RuntimeProbeEntry {
+    id: string;
+    displayName: string;
+    binary: string;
+    supportsRun: boolean;
+    result: RuntimeProbeResult;
+}
+/** Probe every registered runtime and report installation status. */
+export declare function detectRuntimes(): RuntimeProbeEntry[];

package/dist/gateway/runtimes/registry.js

@@ -0,0 +1,94 @@
+import { ClaudeCodeAdapter, probeClaude } from "./claude-code.js";
+import { CodexAdapter, probeCodex } from "./codex.js";
+import { GeminiAdapter, probeGemini } from "./gemini.js";
+/** Built-in runtime module entry for Claude Code. */
+export const claudeCodeModule = {
+    id: "claude-code",
+    displayName: "Claude Code",
+    binary: "claude",
+    envVar: "BOTCORD_CLAUDE_BIN",
+    probe: () => probeClaude(),
+    create: () => new ClaudeCodeAdapter(),
+};
+/** Built-in runtime module entry for Codex. */
+export const codexModule = {
+    id: "codex",
+    displayName: "Codex CLI",
+    binary: "codex",
+    probe: () => probeCodex(),
+    create: () => new CodexAdapter(),
+};
+/** Built-in runtime module entry for Gemini (probe-only stub). */
+export const geminiModule = {
+    id: "gemini",
+    displayName: "Gemini CLI",
+    binary: "gemini",
+    probe: () => probeGemini(),
+    create: () => new GeminiAdapter(),
+    supportsRun: false,
+};
+/**
+ * Built-in runtime modules. To add a new runtime:
+ *   1. Create `runtimes/<name>.ts` extending `NdjsonStreamAdapter` (or
+ *      implementing `RuntimeAdapter` directly).
+ *   2. Add a `RuntimeModule` entry + register it here.
+ */
+export const RUNTIME_MODULES = [
+    claudeCodeModule,
+    codexModule,
+    geminiModule,
+];
+const BY_ID = new Map(RUNTIME_MODULES.map((m) => [m.id, m]));
+/** Lookup a runtime module by id, or null when the id is unknown. */
+export function getRuntimeModule(id) {
+    return BY_ID.get(id) ?? null;
+}
+/** All registered runtime ids in registration order. */
+export function listRuntimeIds() {
+    return RUNTIME_MODULES.map((m) => m.id);
+}
+/** Env var name used to override the binary path for a given runtime id. */
+export function envVarForRuntime(id) {
+    const mod = getRuntimeModule(id);
+    if (mod?.envVar)
+        return mod.envVar;
+    const token = id.replace(/-/g, "_").toUpperCase();
+    return `BOTCORD_${token}_BIN`;
+}
+/** Instantiate a single runtime adapter by id; throws if unknown. */
+export function createRuntime(id) {
+    const mod = getRuntimeModule(id);
+    if (!mod) {
+        throw new Error(`Unknown runtime "${id}". Registered runtimes: ${listRuntimeIds().join(", ")}`);
+    }
+    return mod.create();
+}
+/** Instantiate every registered runtime — used as the dispatcher default. */
+export function createAllRuntimes() {
+    const map = {};
+    for (const m of RUNTIME_MODULES) {
+        map[m.id] = m.create();
+    }
+    return map;
+}
+/** Probe every registered runtime and report installation status. */
+export function detectRuntimes() {
+    const out = [];
+    for (const m of RUNTIME_MODULES) {
+        let result = { available: false };
+        try {
+            result = m.probe();
+        }
+        catch {
+            result = { available: false };
+        }
+        out.push({
+            id: m.id,
+            displayName: m.displayName,
+            binary: m.binary,
+            supportsRun: m.supportsRun !== false,
+            result,
+        });
+    }
+    return out;
+}

package/dist/gateway/session-store.d.ts

@@ -0,0 +1,39 @@
+import type { GatewayLogger } from "./log.js";
+import type { GatewaySessionEntry, SessionKeyInput } from "./types.js";
+export declare const DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS: number;
+/** Derive the canonical session-store key for a runtime + channel + conversation. */
+export declare function sessionKey(input: SessionKeyInput): string;
+/** Options for constructing a `SessionStore`. */
+export interface SessionStoreOptions {
+    path: string;
+    log?: GatewayLogger;
+    /** Optional TTL for persisted entries. Omit to disable automatic pruning. */
+    maxEntryAgeMs?: number;
+}
+/** JSON-backed session store for runtime resume ids, keyed by `sessionKey()`. */
+export declare class SessionStore {
+    private readonly filePath;
+    private readonly log?;
+    private readonly maxEntryAgeMs?;
+    private data;
+    private loaded;
+    private writeQueue;
+    constructor(opts: SessionStoreOptions);
+    /** Load entries from disk. Tolerates missing or corrupt files. */
+    load(): Promise<void>;
+    /** Look up an entry by its full session key. */
+    get(key: string): GatewaySessionEntry | undefined;
+    /** Upsert an entry and persist the store atomically. */
+    set(entry: GatewaySessionEntry): Promise<void>;
+    /** Remove an entry and persist the store atomically. */
+    delete(key: string): Promise<void>;
+    /** Snapshot of all entries (for status/debugging). */
+    all(): GatewaySessionEntry[];
+    /** Remove entries whose `updatedAt` is older than `maxAgeMs`; returns count removed. */
+    pruneExpired(opts: {
+        maxAgeMs: number;
+        now?: number;
+    }): Promise<number>;
+    private persist;
+    private flushOnce;
+}

package/dist/gateway/session-store.js

@@ -0,0 +1,133 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+/** Derive the canonical session-store key for a runtime + channel + conversation. */
+export function sessionKey(input) {
+    const base = `${input.runtime}:${input.channel}:${input.accountId}:${input.conversationKind}:${input.conversationId}`;
+    const thread = input.threadId;
+    if (typeof thread === "string" && thread.length > 0) {
+        return `${base}:${thread}`;
+    }
+    return base;
+}
+function emptyFile() {
+    return { version: 1, entries: {} };
+}
+function isValidShape(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const o = x;
+    return o.version === 1 && !!o.entries && typeof o.entries === "object";
+}
+/** JSON-backed session store for runtime resume ids, keyed by `sessionKey()`. */
+export class SessionStore {
+    filePath;
+    log;
+    maxEntryAgeMs;
+    data = emptyFile();
+    loaded = false;
+    writeQueue = Promise.resolve();
+    constructor(opts) {
+        this.filePath = opts.path;
+        this.log = opts.log;
+        if (Number.isFinite(opts.maxEntryAgeMs) && opts.maxEntryAgeMs > 0) {
+            this.maxEntryAgeMs = opts.maxEntryAgeMs;
+        }
+    }
+    /** Load entries from disk. Tolerates missing or corrupt files. */
+    async load() {
+        let raw;
+        try {
+            raw = await readFile(this.filePath, "utf8");
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                this.data = emptyFile();
+                this.loaded = true;
+                return;
+            }
+            throw err;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (isValidShape(parsed)) {
+                this.data = { version: 1, entries: parsed.entries };
+            }
+            else {
+                this.log?.warn("gateway.session-store.invalid-shape", { path: this.filePath });
+                this.data = emptyFile();
+            }
+        }
+        catch (err) {
+            this.log?.warn("gateway.session-store.parse-error", {
+                path: this.filePath,
+                error: err.message,
+            });
+            this.data = emptyFile();
+        }
+        this.loaded = true;
+        if (this.maxEntryAgeMs !== undefined) {
+            await this.pruneExpired({ maxAgeMs: this.maxEntryAgeMs });
+        }
+    }
+    /** Look up an entry by its full session key. */
+    get(key) {
+        return this.data.entries[key];
+    }
+    /** Upsert an entry and persist the store atomically. */
+    async set(entry) {
+        const callerTs = entry.updatedAt;
+        const updatedAt = Number.isFinite(callerTs) && callerTs > 0 ? callerTs : Date.now();
+        this.data.entries[entry.key] = { ...entry, updatedAt };
+        await this.persist();
+    }
+    /** Remove an entry and persist the store atomically. */
+    async delete(key) {
+        if (this.data.entries[key] !== undefined) {
+            delete this.data.entries[key];
+        }
+        await this.persist();
+    }
+    /** Snapshot of all entries (for status/debugging). */
+    all() {
+        return Object.values(this.data.entries);
+    }
+    /** Remove entries whose `updatedAt` is older than `maxAgeMs`; returns count removed. */
+    async pruneExpired(opts) {
+        const maxAgeMs = opts.maxAgeMs;
+        if (!Number.isFinite(maxAgeMs) || maxAgeMs <= 0)
+            return 0;
+        const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+        const cutoff = now - maxAgeMs;
+        let removed = 0;
+        for (const [key, entry] of Object.entries(this.data.entries)) {
+            if (!Number.isFinite(entry.updatedAt) || entry.updatedAt < cutoff) {
+                delete this.data.entries[key];
+                removed += 1;
+            }
+        }
+        if (removed > 0) {
+            this.log?.info("gateway.session-store.pruned-expired", {
+                path: this.filePath,
+                removed,
+                maxAgeMs,
+            });
+            await this.persist();
+        }
+        return removed;
+    }
+    persist() {
+        const next = this.writeQueue.then(() => this.flushOnce());
+        this.writeQueue = next.catch(() => undefined);
+        return next;
+    }
+    async flushOnce() {
+        const dir = path.dirname(this.filePath);
+        await mkdir(dir, { recursive: true });
+        const tmp = `${this.filePath}.${process.pid}.tmp`;
+        const payload = JSON.stringify(this.data, null, 2);
+        await writeFile(tmp, payload, { mode: 0o600 });
+        await rename(tmp, this.filePath);
+    }
+}