@roamcode.ai/server 1.0.0

package/dist/terminal-process.d.ts

@@ -0,0 +1,85 @@
+import { EventEmitter } from "node:events";
+export interface IPty {
+    onData(cb: (d: string) => void): void;
+    onExit(cb: (e: {
+        exitCode: number;
+    }) => void): void;
+    write(d: string): void;
+    resize(c: number, r: number): void;
+    kill(sig?: string): void;
+}
+export type PtySpawn = (file: string, args: string[], opts: {
+    name: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => IPty;
+export interface TerminalProcessOptions {
+    sessionId: string;
+    cwd: string;
+    executable: string;
+    args?: string[];
+    /** Attach to an already-proven live tmux session without supplying a provider command. If the session
+     * disappeared, tmux fails closed instead of silently creating a fresh, identity-ambiguous conversation. */
+    attachOnly?: boolean;
+    /** Enable tmux mouse history for this session only. Codex uses inline mode; Claude keeps its existing
+     * alternate-screen behavior and browser-owned selection. */
+    enableMouseHistory?: boolean;
+    tmuxBin?: string;
+    cols?: number;
+    rows?: number;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable PTY spawner (default loads node-pty). Tests pass a fake. */
+    ptySpawn?: PtySpawn;
+    /** Injectable one-shot tmux command runner (kill-session). Default: async fire-and-forget spawn. */
+    runTmux?: (args: string[]) => void;
+    /** Read the current global tmux update-environment array. The default reader invokes tmux with an argv
+     * array and returns variable NAMES only; injection keeps version-specific behavior deterministic in tests. */
+    readTmuxUpdateEnvironment?: () => readonly string[] | undefined;
+    /** Dedicated tmux server socket (`-L <socket>`). Defaults to {@link TMUX_SOCKET}. Injected by the
+     *  real-tmux integration test so it runs on a UNIQUE socket and can NEVER touch the live "roamcode"
+     *  server (a shared socket is how the full suite used to kill a running session). */
+    tmuxSocket?: string;
+}
+/** Dedicated tmux server socket — ISOLATES roamcode's sessions from the host user's own tmux (their
+ *  `tmux ls` never shows `rc-*`, a stray `kill-server` can't nuke ours, and our global options never touch
+ *  theirs). Every tmux invocation must pass `-L <SOCKET>`. Overridable via RC_TMUX_SOCKET so a SECOND
+ *  instance (a test/verification server) gets its own socket and never reaps the primary server's
+ *  sessions on boot (rehydrate treats unknown `rc-*` as orphans). Default is unchanged in production.
+ *
+ *  The default keeps the PRE-RENAME name "remote-coder" ON PURPOSE: live terminal sessions exist on this
+ *  socket, and an OTA update restarts the server in place — a renamed socket would boot into an empty tmux
+ *  server and strand every running session (still-running claudes, invisible to the UI). RC = RoamCode. */
+export declare const TMUX_SOCKET: string;
+/** The tmux session name for a roamcode session id. Stable so attach/kill always target the same one. */
+export declare function tmuxSessionName(id: string): string;
+export declare class TerminalProcess extends EventEmitter {
+    readonly tmuxName: string;
+    private readonly opts;
+    private pty?;
+    private started;
+    private readonly tmuxBin;
+    private readonly runTmux;
+    private readonly ptySpawn;
+    private readonly tmuxSocket;
+    private readonly readTmuxUpdateEnvironment;
+    constructor(opts: TerminalProcessOptions);
+    start(): void;
+    write(d: string): void;
+    resize(c: number, r: number): void;
+    /** Detach (kill the pty client; tmux + claude keep running). `kill:true` also kills the tmux session. */
+    stop(opts?: {
+        kill?: boolean;
+    }): void;
+}
+export interface TerminalProcess {
+    on(event: "data", listener: (chunk: string) => void): this;
+    on(event: "exit", listener: (info: {
+        exitCode: number;
+    }) => void): this;
+    emit(event: "data", chunk: string): boolean;
+    emit(event: "exit", info: {
+        exitCode: number;
+    }): boolean;
+}

package/dist/terminal-process.js

@@ -0,0 +1,238 @@
+// packages/server/src/terminal-process.ts
+import { spawn, spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+/** Dedicated tmux server socket — ISOLATES roamcode's sessions from the host user's own tmux (their
+ *  `tmux ls` never shows `rc-*`, a stray `kill-server` can't nuke ours, and our global options never touch
+ *  theirs). Every tmux invocation must pass `-L <SOCKET>`. Overridable via RC_TMUX_SOCKET so a SECOND
+ *  instance (a test/verification server) gets its own socket and never reaps the primary server's
+ *  sessions on boot (rehydrate treats unknown `rc-*` as orphans). Default is unchanged in production.
+ *
+ *  The default keeps the PRE-RENAME name "remote-coder" ON PURPOSE: live terminal sessions exist on this
+ *  socket, and an OTA update restarts the server in place — a renamed socket would boot into an empty tmux
+ *  server and strand every running session (still-running claudes, invisible to the UI). RC = RoamCode. */
+export const TMUX_SOCKET = process.env.RC_TMUX_SOCKET || "remote-coder";
+/** The tmux session name for a roamcode session id. Stable so attach/kill always target the same one. */
+export function tmuxSessionName(id) {
+    return `rc-${id}`;
+}
+const ROAMCODE_TMUX_ENVIRONMENT = ["RC_BASE_URL", "RC_SESSION_ID", "RC_TOKEN", "RC_TOKEN_FILE"];
+// tmux's compiled default. Used only when no dedicated server exists yet (or the read fails), so the first
+// RoamCode session retains tmux's normal display/auth forwarding instead of starting from an empty list.
+const DEFAULT_TMUX_UPDATE_ENVIRONMENT = [
+    "DISPLAY",
+    "KRB5CCNAME",
+    "MSYSTEM",
+    "SSH_ASKPASS",
+    "SSH_AUTH_SOCK",
+    "SSH_AGENT_PID",
+    "SSH_CONNECTION",
+    "WINDOWID",
+    "XAUTHORITY",
+];
+function readTmuxUpdateEnvironment(tmuxBin, tmuxSocket) {
+    try {
+        const result = spawnSync(tmuxBin, ["-L", tmuxSocket, "show-options", "-gv", "update-environment"], {
+            encoding: "utf8",
+            timeout: 1_000,
+        });
+        if (result.status !== 0 || typeof result.stdout !== "string")
+            return undefined;
+        return result.stdout
+            .split("\n")
+            .map((name) => name.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeTmuxUpdateEnvironment(current) {
+    const required = new Set(ROAMCODE_TMUX_ENVIRONMENT);
+    return [...(current ?? DEFAULT_TMUX_UPDATE_ENVIRONMENT).filter((name) => !required.has(name)), ...required];
+}
+/** Server-wide tmux options that make the embedded session behave like a plain, transparent terminal rather
+ *  than a visible tmux: NO status bar (it stole a row and made the TUI look shifted), instant escape-time (the
+ *  500ms default mangled Esc-prefixed sequences = arrow/alt keys), mouse + focus + clipboard passthrough, and
+ *  a 256-color terminfo. Set as ONE chained command BEFORE `new-session` so claude renders full-height from
+ *  its first frame (no status-bar reflow). Applied on our dedicated socket, so they never affect the user's tmux. */
+function tmuxConfigChain(updateEnvironment) {
+    const sets = [
+        ["-g", "status", "off"],
+        ["-s", "escape-time", "0"],
+        // Keep the server default OFF; Codex enables mouse history on its own session immediately before attach.
+        // This preserves Claude's current wheel and plain drag-to-select behavior exactly as-is.
+        ["-g", "mouse", "off"],
+        ["-g", "focus-events", "on"],
+        ["-g", "set-clipboard", "on"],
+        // Codex wraps OSC 9 notifications in tmux passthrough frames. `-q` keeps older tmux versions compatible
+        // if the option is unknown; supported versions forward the bounded frames to the runtime parser.
+        ["-gq", "allow-passthrough", "on"],
+        ["-g", "default-terminal", "tmux-256color"],
+        // remain-on-exit OFF: if claude exits, END the tmux session instead of leaving a frozen, untypeable
+        // [exited] pane that nothing respawns. The server forwards the exit to the client (which shows a
+        // Restart/Close overlay); a Restart re-attaches and `new-session -A` then spawns a FRESH claude.
+        ["-g", "remain-on-exit", "off"],
+    ];
+    return [
+        ...sets.flatMap(([scope, name, value]) => ["set-option", scope, name, value, ";"]),
+        // tmux is a long-lived server: without this allow-list, a later session inherits the FIRST tmux client's
+        // RC_* environment and Codex MCP can target the wrong RoamCode session. The list was read and normalized
+        // in Node because tmux 3.4 cannot expand this array through #{update-environment}. Only variable NAMES
+        // enter argv; token values remain solely in the PTY client's environment.
+        "set-option",
+        "-g",
+        "update-environment",
+        updateEnvironment.join(" "),
+        ";",
+        // tmux's stock first WheelUp only enters copy mode; it does not move. Enter AND scroll on that same
+        // gesture so Codex feels like a normal scrollable conversation from the first wheel/trackpad movement.
+        // Alternate-screen apps (Claude) and apps that request mouse input continue receiving the event.
+        "bind-key",
+        "-n",
+        "WheelUpPane",
+        "if-shell",
+        "-F",
+        "#{||:#{alternate_on},#{mouse_any_flag}}",
+        "send-keys -M",
+        "copy-mode -e; send-keys -X -N 5 scroll-up",
+        ";",
+    ];
+}
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class TerminalProcess extends EventEmitter {
+    tmuxName;
+    opts;
+    pty;
+    started = false;
+    tmuxBin;
+    runTmux;
+    ptySpawn;
+    tmuxSocket;
+    readTmuxUpdateEnvironment;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        this.tmuxName = tmuxSessionName(opts.sessionId);
+        this.tmuxBin = opts.tmuxBin ?? "tmux";
+        // Default runner is an ASYNC fire-and-forget spawn (was spawnSync, which BLOCKED the event loop for
+        // the full tmux round-trip on every kill — stalling every other live session's WS/pty traffic while a
+        // session closed). Nothing consumes the result: the tmux session is either killed or was already gone,
+        // so errors are swallowed and the child is unref'd (it must never hold the server process open).
+        // The injectable signature is unchanged — tests/callers that inject their own runner are unaffected.
+        this.runTmux =
+            opts.runTmux ??
+                ((args) => {
+                    try {
+                        const child = spawn(this.tmuxBin, args, { stdio: "ignore" });
+                        child.on("error", () => {
+                            /* tmux missing / spawn failed — nothing to kill */
+                        });
+                        child.unref();
+                    }
+                    catch {
+                        /* defensive: spawn with an args array shouldn't throw, but stop() must never crash a teardown */
+                    }
+                });
+        this.ptySpawn = opts.ptySpawn ?? defaultPtySpawn;
+        this.tmuxSocket = opts.tmuxSocket ?? TMUX_SOCKET;
+        this.readTmuxUpdateEnvironment =
+            opts.readTmuxUpdateEnvironment ?? (() => readTmuxUpdateEnvironment(this.tmuxBin, this.tmuxSocket));
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        const cols = Math.max(1, this.opts.cols ?? 80);
+        const rows = Math.max(1, this.opts.rows ?? 24);
+        const env = { ...(this.opts.env ?? process.env) };
+        // Strip TMUX/TMUX_PANE so a server itself running inside tmux can't make our `tmux` child think it's
+        // nesting (which makes it refuse / attach to the wrong server). Provider-specific env policy belongs to
+        // the provider that built this process spec.
+        delete env.TMUX;
+        delete env.TMUX_PANE;
+        // UTF-8 LOCALE: a server launched by launchd/systemd often has NO locale env, so tmux assumes a non-UTF-8
+        // terminal and DOWNGRADES wide/block-element glyphs to ASCII — that's what turned claude's logo (drawn
+        // with █▛▜▌▐) into coral dashes + black boxes in the browser. Guarantee a UTF-8 locale so tmux passes the
+        // glyphs through verbatim. (Belt-and-suspenders with tmux's `-u` flag below.)
+        if (!/utf-?8/i.test(env.LC_ALL ?? env.LC_CTYPE ?? env.LANG ?? "")) {
+            env.LANG = "en_US.UTF-8";
+            env.LC_CTYPE = "en_US.UTF-8";
+        }
+        // ONE command on our dedicated socket: configure the server, THEN attach-or-create the session running
+        // claude. `;` tokens are tmux command separators (no shell involved). `-A` = attach if it already exists.
+        // `-u` forces tmux to treat the (node-pty) client as UTF-8 capable regardless of the locale it detects.
+        const providerCommand = this.opts.attachOnly
+            ? ["attach-session", "-t", this.tmuxName]
+            : [
+                "new-session",
+                "-A",
+                "-s",
+                this.tmuxName,
+                "-x",
+                String(cols),
+                "-y",
+                String(rows),
+                "--",
+                this.opts.executable,
+                ...(this.opts.args ?? []),
+            ];
+        const terminalCommand = this.opts.enableMouseHistory
+            ? [
+                ...(this.opts.attachOnly ? [] : [...providerCommand.slice(0, 2), "-d", ...providerCommand.slice(2), ";"]),
+                "set-option",
+                "-t",
+                this.tmuxName,
+                "mouse",
+                "on",
+                ";",
+                "attach-session",
+                "-t",
+                this.tmuxName,
+            ]
+            : providerCommand;
+        const updateEnvironment = normalizeTmuxUpdateEnvironment(this.readTmuxUpdateEnvironment());
+        const args = ["-L", this.tmuxSocket, "-u", ...tmuxConfigChain(updateEnvironment), ...terminalCommand];
+        const pty = this.ptySpawn(this.tmuxBin, args, { name: "xterm-256color", cols, rows, cwd: this.opts.cwd, env });
+        this.pty = pty;
+        pty.onData((d) => this.emit("data", d));
+        pty.onExit((e) => this.emit("exit", e));
+    }
+    write(d) {
+        try {
+            this.pty?.write(d);
+        }
+        catch {
+            // pty gone (claude exited / detached) — drop the write rather than crash the connection.
+        }
+    }
+    resize(c, r) {
+        // Clamp BOTH ends: a transient 0/NaN from a pre-layout fit() or an absurd client value (e.g. 1e9) would
+        // otherwise hit ioctl(TIOCSWINSZ) and throw / allocate huge line buffers. 1000 is far beyond any viewport.
+        const clamp = (n) => Math.min(1000, Math.max(1, Math.trunc(n) || 1));
+        try {
+            this.pty?.resize(clamp(c), clamp(r));
+        }
+        catch {
+            // pty gone or rejected the dims — best-effort.
+        }
+    }
+    /** Detach (kill the pty client; tmux + claude keep running). `kill:true` also kills the tmux session. */
+    stop(opts = {}) {
+        if (opts.kill)
+            this.runTmux(["-L", this.tmuxSocket, "kill-session", "-t", this.tmuxName]);
+        try {
+            this.pty?.kill();
+        }
+        catch {
+            // pty already gone — best-effort
+        }
+        this.pty = undefined;
+    }
+}
+/** Default spawner: lazy-load node-pty so a missing native module never breaks module import. */
+const defaultPtySpawn = (file, args, opts) => {
+    const pty = require("node-pty");
+    return pty.spawn(file, args, opts);
+};

package/dist/terminal-shared.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where terminal file-exchange uploads live on disk.
+ *
+ * They are SERVER-OWNED scratch files (the user uploads a file so the terminal's claude can read it), so
+ * they must NEVER land in the user's project tree — a stray file there dirties the git checkout and the
+ * OTA updater then refuses to run (its dirty-tree guard). The original design wrote them to
+ * `<session cwd>/shared_files/`, i.e. straight into whatever repo the terminal was opened in. This module
+ * relocates them to the app DATA dir instead, one folder per session, with a 7-day TTL.
+ */
+/** Subdir (of the data dir / fsRoot fallback) that holds every terminal session's shared-files folder. */
+export declare const TERMINAL_SHARED_DIRNAME = "terminal-shared";
+/** Terminal uploads live 7 days — pruned on each upload and by a periodic sweep, so they never accumulate. */
+export declare const TERMINAL_FILE_TTL_MS: number;
+/** How often the periodic prune sweep runs. */
+export declare const TERMINAL_SWEEP_INTERVAL_MS: number;
+/**
+ * The BASE dir that holds every terminal session's shared-files folder.
+ *
+ * Prefers the app DATA dir (e.g. `~/.config/roamcode/terminal-shared`) — always outside the user's
+ * project tree, so uploads can never dirty a git checkout. The Files panel downloads these back through the
+ * fsRoot-confined `/fs/download`, so the base MUST also sit within fsRoot; the data dir does by default
+ * (`$HOME/.config/roamcode` ⊂ `$HOME`). If an operator set a NARROWER `FS_ROOT` that excludes the data
+ * dir — or the data dir is unset (some test configs) — fall back to a hidden dir INSIDE fsRoot so upload +
+ * download stay consistent (still outside any repo in the default `FS_ROOT=$HOME` case).
+ */
+export declare function terminalSharedBase(opts: {
+    dataDir?: string;
+    fsRoot: string;
+}): string;
+/** The shared-files folder for ONE terminal session — a child of {@link terminalSharedBase} keyed by the
+ *  session id, so different sessions never collide on a same-named upload and each ages out independently. */
+export declare function terminalSharedDir(opts: {
+    dataDir?: string;
+    fsRoot: string;
+    sessionId: string;
+}): string;

package/dist/terminal-shared.js

@@ -0,0 +1,43 @@
+import { join, resolve, sep } from "node:path";
+/**
+ * Where terminal file-exchange uploads live on disk.
+ *
+ * They are SERVER-OWNED scratch files (the user uploads a file so the terminal's claude can read it), so
+ * they must NEVER land in the user's project tree — a stray file there dirties the git checkout and the
+ * OTA updater then refuses to run (its dirty-tree guard). The original design wrote them to
+ * `<session cwd>/shared_files/`, i.e. straight into whatever repo the terminal was opened in. This module
+ * relocates them to the app DATA dir instead, one folder per session, with a 7-day TTL.
+ */
+/** Subdir (of the data dir / fsRoot fallback) that holds every terminal session's shared-files folder. */
+export const TERMINAL_SHARED_DIRNAME = "terminal-shared";
+/** Terminal uploads live 7 days — pruned on each upload and by a periodic sweep, so they never accumulate. */
+export const TERMINAL_FILE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** How often the periodic prune sweep runs. */
+export const TERMINAL_SWEEP_INTERVAL_MS = 12 * 60 * 60 * 1000;
+/** True when `path` is `root` itself or nested underneath it (same test FsService uses to confine paths). */
+function isWithinRoot(path, root) {
+    const p = resolve(path);
+    const r = resolve(root);
+    return p === r || p.startsWith(r + sep);
+}
+/**
+ * The BASE dir that holds every terminal session's shared-files folder.
+ *
+ * Prefers the app DATA dir (e.g. `~/.config/roamcode/terminal-shared`) — always outside the user's
+ * project tree, so uploads can never dirty a git checkout. The Files panel downloads these back through the
+ * fsRoot-confined `/fs/download`, so the base MUST also sit within fsRoot; the data dir does by default
+ * (`$HOME/.config/roamcode` ⊂ `$HOME`). If an operator set a NARROWER `FS_ROOT` that excludes the data
+ * dir — or the data dir is unset (some test configs) — fall back to a hidden dir INSIDE fsRoot so upload +
+ * download stay consistent (still outside any repo in the default `FS_ROOT=$HOME` case).
+ */
+export function terminalSharedBase(opts) {
+    const preferred = opts.dataDir ? join(opts.dataDir, TERMINAL_SHARED_DIRNAME) : undefined;
+    if (preferred && isWithinRoot(preferred, opts.fsRoot))
+        return preferred;
+    return join(opts.fsRoot, ".roamcode", TERMINAL_SHARED_DIRNAME);
+}
+/** The shared-files folder for ONE terminal session — a child of {@link terminalSharedBase} keyed by the
+ *  session id, so different sessions never collide on a same-named upload and each ages out independently. */
+export function terminalSharedDir(opts) {
+    return join(terminalSharedBase(opts), opts.sessionId);
+}

package/dist/tmux-list.d.ts

@@ -0,0 +1,11 @@
+/** Outcome of probing the tmux server. `ok:false` means the probe FAILED in a way we can't interpret —
+ *  the caller MUST NOT treat that as "zero live sessions" (doing so would prune every stored terminal). */
+export interface TmuxProbe {
+    ok: boolean;
+    out: string;
+}
+/**
+ * Live tmux session names, or `undefined` when the probe could not be determined (a transient tmux error).
+ * A definitive "no sessions" is `[]`; `undefined` signals the caller to NOT prune the store.
+ */
+export declare function listTmuxSessions(run?: () => TmuxProbe): string[] | undefined;

package/dist/tmux-list.js

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+import { TMUX_SOCKET } from "./terminal-process.js";
+function defaultRun() {
+    // spawnSync is FINE here: this probe runs only at BOOT (rehydrate, before listen()), where blocking a
+    // few ms is harmless and a definitive synchronous answer keeps the adopt-or-prune logic simple. Hot-path
+    // tmux calls (kill-session, capture-pane) are async elsewhere.
+    // MUST target the same dedicated `-L` socket the sessions were created on.
+    let r;
+    try {
+        r = spawnSync("tmux", ["-L", TMUX_SOCKET, "list-sessions", "-F", "#{session_name}"], { encoding: "utf8" });
+    }
+    catch {
+        return { ok: false, out: "" };
+    }
+    if (r.error)
+        return { ok: false, out: "" };
+    if (r.status === 0)
+        return { ok: true, out: typeof r.stdout === "string" ? r.stdout : "" };
+    // Exit nonzero: "no server running on <socket>" is the NORMAL empty case (no sessions exist yet) — that's a
+    // definitive "zero sessions". ANY other failure is ambiguous (transient tmux error) → report not-ok so the
+    // caller skips destructive pruning rather than deleting live, resumable sessions on a flaky probe.
+    const stderr = typeof r.stderr === "string" ? r.stderr : "";
+    if (/no server running/i.test(stderr))
+        return { ok: true, out: "" };
+    return { ok: false, out: "" };
+}
+/**
+ * Live tmux session names, or `undefined` when the probe could not be determined (a transient tmux error).
+ * A definitive "no sessions" is `[]`; `undefined` signals the caller to NOT prune the store.
+ */
+export function listTmuxSessions(run = defaultRun) {
+    const { ok, out } = run();
+    if (!ok)
+        return undefined;
+    return out
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}

package/dist/transport.d.ts

@@ -0,0 +1,123 @@
+import type { FastifyInstance } from "fastify";
+import { AuthGate } from "./auth.js";
+import { RateLimiter } from "./rate-limit.js";
+import { WsTicketStore } from "./ws-ticket.js";
+import type { ServerRuntimeConfig } from "./server-config.js";
+import type { SessionStore, StoreMode } from "./session-store.js";
+import type { PushStore } from "./push-store.js";
+import type { PushDispatcher } from "./push-dispatch.js";
+import type { Updater } from "./updater.js";
+import type { ClaudeVersionProbe } from "./diag.js";
+import type { UsageService } from "./usage-service.js";
+import type { ClaudeAuthService } from "./claude-auth-service.js";
+import type { ClaudeLatestService } from "./claude-latest-service.js";
+import { TerminalManager } from "./terminal-manager.js";
+import { ProviderRegistry } from "./providers/registry.js";
+import type { CodexMetadataService } from "./providers/codex-metadata-service.js";
+import type { ClaudeMetadataService } from "./providers/claude-metadata-service.js";
+import type { CodexLatestService } from "./providers/codex-latest-service.js";
+import type { CodexThreadResolver } from "./providers/codex-thread-resolver.js";
+export interface CreateServerDeps {
+    store?: SessionStore;
+    /** Absolute path to the built PWA (packages/web/dist). When set, the server also serves the UI. */
+    webDir?: string;
+    pushStore?: PushStore;
+    /** VAPID public key exposed at GET /push/vapid for the browser subscription. */
+    vapidPublicKey?: string;
+    /**
+     * Away-from-desk Web Push dispatcher (fan-out for awaiting/finished/file events). Wired by start.ts
+     * from the push store + VAPID keys. When omitted (tests / push not configured) the "get pinged" side of
+     * the loop is simply a no-op — every route/heuristic still functions, it just sends no notifications.
+     */
+    pushDispatcher?: PushDispatcher;
+    /**
+     * In-app OTA self-update (GET /version, POST /update, GET /update/status). Injected so tests can use a
+     * fixture release feed without network access. When omitted, a real stable-release updater is built.
+     */
+    updater?: Updater;
+    /**
+     * Claude usage limits (GET /usage → the session + weekly bars). Injected here so tests can pass a
+     * fake (no real `claude` spawn). When omitted the route reports `usage:null` (the feature is off in
+     * the UI). A real UsageService is wired by start.ts from the configured claude bin + the server env.
+     */
+    usage?: UsageService;
+    /**
+     * In-app Claude re-authentication (GET /auth/status, POST /auth/login/start|code|cancel). Injected so
+     * tests can pass a fake (no real `claude auth` spawn). When omitted the auth routes report "unavailable"
+     * (the UI hides the sign-in). A real ClaudeAuthService is wired by start.ts from the claude bin + env.
+     */
+    claudeAuth?: ClaudeAuthService;
+    /**
+     * The latest published claude CLI version (GET /claude/version → {installed, latest}), for update
+     * awareness. Injected so tests don't hit the npm registry; absent → latest:null (the UI hides the hint).
+     */
+    claudeLatest?: ClaudeLatestService;
+    /**
+     * How the session store is actually backed — "sqlite" (durable) or "memory-fallback" (better-sqlite3
+     * failed to load; NOT durable across restarts). Surfaced by the authed GET /diag for fleet observability.
+     * Threaded from start.ts (it opens the store). Defaults to "sqlite" when omitted.
+     */
+    storeMode?: StoreMode;
+    /**
+     * Cached best-effort `claude --version` probe for the authed GET /diag. Injected so tests pass a fake
+     * (no real spawn). When omitted a real probe is built from the configured claude bin + server env.
+     */
+    claudeVersionProbe?: ClaudeVersionProbe;
+    /**
+     * Global per-client request rate limiter (token bucket). Injected so tests can drive an injectable clock
+     * / a tiny limit. When omitted one is built from `config.rateLimitRpm`/`config.rateLimitBurst` (a
+     * rpm of 0 disables it). Applied in the global preHandler AFTER the auth gate + origin check.
+     */
+    rateLimiter?: RateLimiter;
+    /**
+     * CSPRNG token generator for POST /token/rotate (reuses data-dir.ts's default). Injected so tests get a
+     * deterministic rotated token. When omitted, resolveAccessToken's default 32-byte base64url generator.
+     */
+    generateToken?: () => string;
+    /**
+     * The token gate. Injected so tests can control the rotation grace window / clock (e.g. graceMs:0 to
+     * assert the OLD token is rejected the instant after rotation). When omitted one is built from
+     * `config.accessToken` with the default 60s rotation grace.
+     */
+    authGate?: AuthGate;
+    /**
+     * Whether terminal mode (tmux + node-pty) is available on this host. Injected so tests can force it
+     * on/off without real tmux/pty. When omitted, detectTerminalSupport() is called at boot.
+     */
+    terminalAvailable?: boolean;
+    /**
+     * Terminal session manager (injectable for tests; a real one is constructed from deps.store +
+     * config.claude.claudeBin when omitted).
+     */
+    terminalManager?: TerminalManager;
+    /** Exact provider registry shared with the terminal manager and provider capability routes. */
+    providers?: ProviderRegistry;
+    /** Auxiliary Codex app-server metadata. Its failure never disables terminal sessions. */
+    codexMetadata?: CodexMetadataService;
+    /** Auxiliary Claude model metadata. Its failure never disables terminal sessions. */
+    claudeMetadata?: ClaudeMetadataService;
+    /** Cached aggregate of every stable Codex metadata method/schema used by this server. */
+    codexCapabilityProbe?: {
+        get(): Promise<boolean>;
+    };
+    /** Installation-aware Codex version/update service. */
+    codexLatest?: CodexLatestService;
+    codexThreadResolver?: (cwd: string) => CodexThreadResolver;
+    disposeProviders?: () => void | Promise<void>;
+    /**
+     * Single-use terminal-WS ticket store (POST /ws-ticket → `?ticket=` on the WS URL, so the long-lived
+     * token stays OUT of WS URLs / proxy logs). Injectable so tests drive the clock/TTL; a real 30s-TTL
+     * store is built when omitted.
+     */
+    wsTickets?: WsTicketStore;
+}
+export interface CreateServerResult {
+    app: FastifyInstance;
+    authGate: AuthGate;
+    /** Exposed so startServer can late-bind the MCP attach config (after listen() resolves the port) —
+     *  this is what gives the terminal's claude send_image/send_file. */
+    terminalManager: TerminalManager;
+    /** False when tmux/node-pty is unavailable → terminal sessions are disabled (startServer warns loudly). */
+    terminalAvailable: boolean;
+}
+export declare function createServer(config: ServerRuntimeConfig, deps?: CreateServerDeps): CreateServerResult;