@roamcode.ai/server 1.0.0 → 1.0.1

package/dist/start.d.ts

@@ -1,8 +1,588 @@
-import type { ClaudeAvailability, ClaudeVersionProbe } from "./diag.js";
-import type { CreateServerResult } from "./transport.js";
-import type { ProviderAvailability } from "./providers/types.js";
-export declare function providerPreflightWarning(name: string, availability: ProviderAvailability): string | undefined;
-export declare function runProviderPreflight(providers: ReadonlyArray<{
+import { FastifyInstance } from 'fastify';
+
+/**
+ * Wiring for the mcp-send server (Claude → user attachments). When present, the spawn layer writes a
+ * per-session 0600 MCP config FILE (carrying the loopback base URL, this session's id, and the access
+ * token via env) and passes its PATH to the terminal spawn as `--mcp-config <path>`. The token therefore
+ * NEVER lands in any process's argv (where `ps`/`/proc` would expose it to other local users) — it
+ * lives only in the mode-0600 file. ABSENT → spawn exactly as before (the feature is additive).
+ */
+interface AttachSpawnOptions {
+    /** Loopback base URL of roamcode (e.g. http://127.0.0.1:4280) the tool POSTs back to. */
+    baseUrl: string;
+    /** The access token the mcp-send tool sends as `Authorization: Bearer <token>`. */
+    token: string;
+    /** Absolute path to the built dist/mcp-send.js node script. */
+    mcpScriptPath: string;
+    /** Host data dir (mode 0700) the per-session 0600 mcp-config-<id>.json is written into. */
+    dataDir: string;
+}
+
+type ProviderId = "claude" | "codex";
+interface ProviderAvailability {
+    terminalAvailable: boolean;
+    metadataAvailable: boolean;
+    version?: string;
+    detail?: string;
+}
+type ClaudeSessionOptions = {
+    provider: "claude";
+    model?: string;
+    effort?: string;
+    permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
+    dangerouslySkip?: boolean;
+    addDirs?: string[];
+    legacyArgs?: string[];
+};
+type CodexSessionOptions = {
+    provider: "codex";
+    model?: string;
+    reasoningEffort?: string;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+    approvalPolicy?: "untrusted" | "on-request" | "never";
+    profile?: string;
+    webSearch?: boolean;
+    dangerouslyBypassApprovalsAndSandbox?: boolean;
+    addDirs?: string[];
+};
+type ProviderSessionOptions = ClaudeSessionOptions | CodexSessionOptions;
+type LaunchIntent = "fresh" | "resume";
+interface ProcessSpec {
+    executable: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cleanupPaths: string[];
+    /** Revalidates ephemeral launch proof immediately before the terminal process is spawned. */
+    preSpawnCheck?: () => void | Promise<void>;
+    integration?: {
+        attachments: "ready" | "degraded";
+        activity: "ready" | "degraded";
+        detail?: string;
+    };
+}
+interface ProviderProcessContext {
+    roamSessionId: string;
+    cwd: string;
+    intent: LaunchIntent;
+    options: ProviderSessionOptions;
+    providerSessionId?: string;
+    /** Late-bound after listen so both providers share the real loopback MCP callback configuration. */
+    attach?: AttachSpawnOptions;
+    /** Transfer temporary-artifact ownership as soon as paths exist, so a later build rejection is cleanable. */
+    registerCleanupPaths?(paths: readonly string[]): void;
+}
+type ProviderRuntimeSignal = {
+    type: "working";
+} | {
+    type: "blocked";
+} | {
+    type: "idle";
+} | {
+    type: "provider-session-id";
+    id: string;
+};
+interface ProviderRuntimeSignalParser {
+    push(chunk: string): ProviderRuntimeSignal[];
+}
+interface ProviderRuntimeMetadata {
+    model?: string;
+    effort?: string;
+}
+interface AgentProvider {
+    readonly id: ProviderId;
+    readonly displayName: string;
+    readonly resumeIdentity: "optional" | "required";
+    probe(): Promise<ProviderAvailability>;
+    buildProcess(context: ProviderProcessContext): Promise<ProcessSpec>;
+    /** Stateful parsers must be created per spawned process; providers are registry singletons. */
+    createRuntimeSignalParser?(): ProviderRuntimeSignalParser;
+    runtimeSignals(chunk: string): ProviderRuntimeSignal[];
+    classifyPane(pane: string): "working" | "blocked" | "idle";
+    /** Read provider-owned live model/effort chrome from a captured pane. Optional because not every TUI
+     * exposes these values. A missing/invalid result must leave launch metadata untouched. */
+    runtimeMetadata?(pane: string): ProviderRuntimeMetadata | undefined;
+    cleanup(paths: readonly string[]): void;
+}
+
+interface ClaudeAvailability {
+    available: boolean;
+    /** The parsed version string (e.g. "1.2.3") when available; absent otherwise. */
+    version?: string;
+}
+interface ClaudeVersionProbe {
+    /** Resolve the (cached) availability. Never rejects. */
+    get(): Promise<ClaudeAvailability>;
+}
+
+interface AuthGateOptions {
+    token?: string;
+    /** Consecutive failures from one client before it is locked out. Default 10. */
+    maxFailures?: number;
+    /** Lockout duration in ms. Default 60000. */
+    lockoutMs?: number;
+    /**
+     * Grace window (ms) after {@link AuthGate.rotateToken} during which the PREVIOUS token is still
+     * accepted, so a callback already in flight with the old token (e.g. a running mcp-send subprocess that
+     * captured RC_TOKEN at spawn) survives the rotation instead of 401-ing mid-conversation. Default 60000.
+     */
+    graceMs?: number;
+    /** Injectable clock for tests. Default Date.now. */
+    now?: () => number;
+}
+type AuthCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "locked" | "invalid" | "missing-token-config";
+};
+/**
+ * Verifies a bearer access token in constant time and applies a per-client
+ * lockout after repeated failures. Pure / I/O-free so it is unit-testable;
+ * Task 8 wires it as a single global Fastify `preHandler` that also gates the
+ * WebSocket upgrade.
+ *
+ * Proxy lockout caveat: the lockout is keyed by `clientKey` (`request.ip`).
+ * Behind a reverse proxy (Caddy / Cloudflare) `request.ip` is the proxy's IP
+ * for EVERY client, collapsing the per-client lockout to one shared key. To
+ * stop that from self-DoS-ing the sole legitimate user, {@link check} validates
+ * the token FIRST: a CORRECT token is ALWAYS accepted, even while its key is
+ * locked out — the lockout only ever throttles WRONG guesses. Supplying a real
+ * per-client key (Fastify `trustProxy` scoped to the proxy) still makes the
+ * throttle per-client, but is no longer required to keep the user from being
+ * locked out by someone else's bad traffic.
+ */
+declare class AuthGate {
+    private token?;
+    private previousToken?;
+    private previousValidUntil;
+    private readonly maxFailures;
+    private readonly lockoutMs;
+    private readonly graceMs;
+    private readonly now;
+    private readonly clients;
+    constructor(opts: AuthGateOptions);
+    check(presentedToken: string | undefined, clientKey: string): AuthCheckResult;
+    /**
+     * Atomically swap in a fresh access token (POST /token/rotate). Every subsequent {@link check} compares
+     * against the new token; the OLD token is accepted only for a brief grace window (graceMs) so in-flight
+     * callbacks holding it (a running mcp-send subprocess) survive the rotation instead of 401-ing mid-turn.
+     * A 2nd rotation within the window REPLACES previousToken with the most-recent old token (no list grows).
+     * Also clears all per-client lockout state — rotation is an explicit administrative reset, so a fresh
+     * slate is correct (and avoids leaving a client locked out against a token that no longer exists).
+     */
+    rotateToken(newToken: string): void;
+    /** Drop entries whose lockout has expired and whose failure count is 0 — keeps the map bounded. */
+    private sweepExpired;
+    /** TEST ONLY: number of tracked clients currently locked (lockedUntil in the future). */
+    lockedClientCount(): number;
+}
+
+interface SessionDefaults {
+    effort: string;
+    model?: string;
+    dangerouslySkip: boolean;
+    permissionMode?: string;
+    codex?: {
+        model?: string;
+        reasoningEffort?: string;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+        approvalPolicy?: "untrusted" | "on-request" | "never";
+        profile?: string;
+        webSearch?: boolean;
+        addDirs?: string[];
+        dangerouslyBypassApprovalsAndSandbox?: boolean;
+    };
+}
+interface StoredSessionDefaults {
+    defaults: SessionDefaults;
+    revision: number;
+    updatedAt: number;
+}
+
+type StoredStatus = "running" | "dormant" | "errored" | "stopped";
+interface StoredSessionBase {
+    id: string;
+    cwd: string;
+    status: StoredStatus;
+    createdAt: number;
+    lastActivityAt: number;
+    /** Always "terminal" — the only session kind. Kept so rehydrate can filter/guard on it. */
+    mode: "terminal";
+    /** Optional user-set display name (PATCH /sessions/:id). Absent = unnamed (the UI shows the cwd). */
+    name?: string;
+}
+interface StoredClaudeSession extends StoredSessionBase {
+    provider: "claude";
+    dangerouslySkip: boolean;
+    /** The USER-chosen spawn flags the session was created with (`--model`/`--effort`/`--permission-mode`/
+     *  `--dangerously-skip-permissions`/`--add-dir …`) — everything EXCEPT the ephemeral per-session
+     *  `--mcp-config`/`--settings` paths (those are regenerated per spawn). Persisted so a RESTART can
+     *  respawn the ended session with the same settings instead of a bare claude. Absent = no extra flags. */
+    spawnArgs?: string[];
+    providerSessionId?: never;
+    launchOptions?: never;
+    integrationStatus?: never;
+}
+interface StoredIntegrationStatus {
+    attachments: "ready" | "degraded";
+    activity: "ready" | "degraded";
+    detail?: string;
+}
+interface StoredCodexSession extends StoredSessionBase {
+    provider: "codex";
+    launchOptions: CodexSessionOptions;
+    providerSessionId?: string;
+    integrationStatus?: StoredIntegrationStatus;
+    dangerouslySkip?: never;
+    spawnArgs?: never;
+}
+type StoredSession = StoredClaudeSession | StoredCodexSession;
+/** How a store is actually backed: "sqlite" (durable) or "memory-fallback" (the native module failed to
+ *  load — NOT durable across restarts). Surfaced so start.ts can warn loudly + /diag can report it. */
+type StoreMode = "sqlite" | "memory-fallback";
+interface SessionStore {
+    /** Atomically claim a brand-new physical id. Rejects any existing owner without changing its data. */
+    claimNew(session: StoredSession): void;
+    upsert(session: StoredSession): void;
+    /** True when any physical provider table owns the id, including corrupt or cross-table ambiguous rows. */
+    has(id: string): boolean;
+    get(id: string): StoredSession | undefined;
+    list(): StoredSession[];
+    setStatus(id: string, status: StoredStatus): void;
+    touch(id: string, at: number): void;
+    /** Set/clear a session's display name (undefined clears — the row's `name` goes back to NULL). */
+    setName(id: string, name: string | undefined): void;
+    /** Persist/clear the exact resumable identity for Codex sessions only. Claude rows are never touched. */
+    setProviderSessionId(id: string, value: string | undefined): void;
+    /** Claim a hidden, non-resumable identity pending exact-thread cross-check. */
+    markProvisionalProviderSessionId(id: string, value: string): void;
+    /** Remove only the matching hidden provisional identity. */
+    clearProvisionalProviderSessionId(id: string, value: string): void;
+    /** Atomically promote only the matching hidden provisional identity to resumable state. */
+    commitProvisionalProviderSessionId(id: string, value: string): void;
+    getSessionDefaults(): StoredSessionDefaults | undefined;
+    putSessionDefaults(defaults: SessionDefaults, expectedRevision: number, updatedAt: number): StoredSessionDefaults;
+    delete(id: string): void;
+    close(): void;
+    /** "sqlite" when better-sqlite3 loaded; "memory-fallback" when it didn't (non-durable). */
+    readonly mode: StoreMode;
+}
+
+declare global {
+    /** Stable package version injected by tsup. Source/test builds fall back to package.json. */
+    const __SERVER_VERSION__: string | undefined;
+}
+
+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;
+}
+type PtySpawn = (file: string, args: string[], opts: {
+    name: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => IPty;
+
+type PaneStatus = "working" | "blocked" | "idle";
+
+declare class ProviderRegistry {
+    private readonly byId;
+    constructor(providers: readonly AgentProvider[]);
+    get(id: ProviderId): AgentProvider;
+    list(): AgentProvider[];
+}
+
+interface CodexSpawnLease {
+    readonly started: Promise<void>;
+    cancel(): Promise<void>;
+}
+
+interface CodexThreadPersistence {
+    markProvisional(id: string): void;
+    clear(id: string): void;
+    commit(id: string): void;
+}
+
+interface CodexThreadInventoryEntry {
+    readonly id: string;
+    readonly cwd: string;
+    readonly source: "cli" | "vscode" | "exec" | "appServer" | "unknown" | Record<string, unknown>;
+    /** Current protocol uses Unix seconds; milliseconds are normalized defensively for compatible revisions. */
+    readonly createdAt: number;
+}
+type ReadCodexThreadInventory = () => Promise<readonly CodexThreadInventoryEntry[]>;
+interface CodexThreadResolverOptions {
+    readonly inventory: ReadCodexThreadInventory;
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    readonly deadlineMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly maxInventoryItems?: number;
+    readonly creationSkewMs?: number;
+    readonly cancellationAckMs?: number;
+}
+interface ResolveCodexThreadOptions {
+    readonly cwd: string;
+    /** The launch callback is intentionally inside the process-wide identity mutex. */
+    readonly spawn: (signal: AbortSignal) => CodexSpawnLease;
+    readonly persistence: CodexThreadPersistence;
+    readonly signal?: AbortSignal;
+}
+declare class CodexThreadResolver {
+    private readonly inventory;
+    private readonly now;
+    private readonly sleep;
+    private readonly deadlineMs;
+    private readonly pollIntervalMs;
+    private readonly maxInventoryItems;
+    private readonly creationSkewMs;
+    private readonly cancellationAckMs;
+    private readonly maxPolls;
+    constructor(options: CodexThreadResolverOptions);
+    resolveAfterSpawn(options: ResolveCodexThreadOptions): Promise<string>;
+    private resolveLocked;
+    private readInventory;
+    private candidates;
+    private sameIdentity;
+    private throwIfCancelled;
+}
+
+interface TerminalMeta {
+    id: string;
+    provider: ProviderId;
+    cwd: string;
+    mode: "terminal";
+    status: "running" | "ended";
+    createdAt: number;
+    lastActivityAt: number;
+    /**
+     * The session's LIVE activity, derived every ~2.5s from its rendered tmux pane by the capture-pane monitor
+     * (TerminalManager.refreshActivity → pane-status.classifyPaneStatus). UNIVERSAL (no hooks) + works while
+     * detached. Surfaced in GET /sessions to drive the rail's per-session status:
+     *   - "working" — actively generating (main spinner OR background agents still developing);
+     *   - "blocked" — claude is WAITING ON YOUR DECISION (a permission or plan prompt) → the loud
+     *     "needs you". This is the ONLY state that alerts;
+     *   - "idle"    — a finished turn sitting at an empty prompt, nothing running, nothing to decide (calm).
+     */
+    activity: PaneStatus;
+    /**
+     * Back-compat boolean = `activity === "blocked"`. Drives the loud "needs you" badge/chip, the away push, and
+     * the badge count. Kept as a distinct field so existing consumers (awaitingCount, the push gate) don't all
+     * have to learn the 3-state enum. Set together with `activity` by the monitor.
+     */
+    awaiting: boolean;
+    /**
+     * Whether this session's claude runs with `--dangerously-skip-permissions` (RCE-by-design: claude can run
+     * any tool without asking). Derived at create() from the spawn args, persisted, and surfaced in GET /sessions
+     * so the web rail can badge a session as running in skip-permissions mode.
+     */
+    dangerouslySkip: boolean;
+    /** The effective model: initialized from launch options, then refreshed from live provider chrome when the
+     *  TUI exposes it. Surfaced in GET /sessions so the chat header/rail follow in-session changes. */
+    model?: string;
+    /** Effective effort/reasoning: initialized from launch options, then refreshed from live provider chrome.
+     *  Absent means the provider controls its default. */
+    effort?: string;
+    /** Provider-native safety controls captured at launch for exact UI display. */
+    permissionMode?: ClaudeSessionOptions["permissionMode"];
+    sandbox?: CodexSessionOptions["sandbox"];
+    approvalPolicy?: CodexSessionOptions["approvalPolicy"];
+    /** User-set display name (PATCH /sessions/:id). SERVER-side so a rename shows on every device, not just
+     *  the one that typed it. Persisted; absent = unnamed (the UI falls back to the cwd). */
+    name?: string;
+    /** Codex exact-thread capture state. Claude sessions do not need a provider resume identity. */
+    identityState?: "pending" | "exact" | "ambiguous";
+    providerSessionId?: string;
+}
+interface TerminalSub {
+    unsubscribe(): void;
+}
+interface TerminalManagerDeps {
+    store: SessionStore;
+    providers: ProviderRegistry;
+    now: () => number;
+    ptySpawn?: PtySpawn;
+    runTmux?: (args: string[]) => void;
+    /** Dedicated tmux server socket. Defaults to the unchanged production socket; integration tests inject a
+     * unique socket so spawn, capture, resume, and cleanup cannot touch a live RoamCode instance. */
+    tmuxSocket?: string;
+    /**
+     * Best-effort notifier fired on a false→true `awaiting` transition WHEN NO CLIENT IS ATTACHED (i.e. the
+     * user is away from the desk). Wired by the transport to the push dispatcher; omitted in tests. Called in
+     * a try/catch — a throw here can NEVER break the terminal.
+     */
+    onAwaiting?: (id: string) => void;
+    /**
+     * Best-effort notifier fired when a session's claude exits (the "done" ping). `wasAttached` reports whether
+     * a client was still attached at the moment of exit — captured BEFORE the subs are torn down — so the
+     * transport can gate the away-from-desk push on "nobody was watching" (you already see the WS close when you
+     * are). Same never-throw contract.
+     */
+    onFinished?: (id: string, wasAttached: boolean) => void;
+    /**
+     * Capture a tmux session's CURRENT rendered pane as plain text (READ-ONLY). Injected for tests; in
+     * production it defaults to a real `capture-pane -p` on {@link TMUX_SOCKET}. Drives {@link refreshActivity},
+     * the universal (hook-free) working-vs-awaiting classifier.
+     */
+    capturePane?: (sessionName: string) => Promise<string>;
+    /** Builds the cwd-scoped exact-thread resolver used around a fresh Codex TUI spawn. */
+    codexThreadResolver?: (cwd: string) => CodexThreadResolver;
+}
+type CreateTerminalOptions = {
+    id: string;
+    cwd: string;
+    provider: "claude";
+    options: ClaudeSessionOptions;
+    cols?: number;
+    rows?: number;
+} | {
+    id: string;
+    cwd: string;
+    provider: "codex";
+    options: CodexSessionOptions;
+    cols?: number;
+    rows?: number;
+};
+type LegacyCreateTerminalOptions = {
+    id: string;
+    cwd: string;
+    claudeArgs?: string[];
+    cols?: number;
+    rows?: number;
+};
+declare class TerminalManager {
+    private readonly deps;
+    private readonly records;
+    private readonly providers;
+    private attachConfig?;
+    constructor(deps: TerminalManagerDeps);
+    /** Late-bound (after listen(), which resolves the loopback port) — same config the chat SessionManager
+     *  gets. When set, each terminal's claude is spawned with `--mcp-config` so send_image/send_file work. */
+    setAttachConfig(attach: AttachSpawnOptions | undefined): void;
+    create(explicit: CreateTerminalOptions): TerminalMeta;
+    /** Temporary explicit-Claude seam for the pre-provider transport. */
+    createLegacyClaude(opts: LegacyCreateTerminalOptions): TerminalMeta;
+    /**
+     * Delete stale per-session 0600 files that hold the access token — `mcp-config-<id>.json`, `hooks-<id>.json`,
+     * `hook-auth-<id>`, and `codex-mcp-token-<id>`. A file is stale when no live session owns its id: leaked by a
+     * crash, an orphan-reap, a rehydrated record (which carries no such paths, so stop() never unlinks its files),
+     * or a token rotation. Call at boot AFTER rehydrate + setAttachConfig so `records` reflects the surviving
+     * sessions. No-op without an attach config.
+     */
+    sweepStaleMcpConfigs(): number;
+    /**
+     * Kill running terminal sessions with NO attached client that have been idle longer than `ttlMs`. OFF by
+     * default (ttlMs <= 0) and opt-in via env (SESSION_IDLE_TTL_MS): sessions intentionally survive a
+     * disconnect for later reattach, so reaping them must never be the default — it's only for hosts that
+     * choose to bound the accumulation of detached claude+tmux processes. Returns the number reaped.
+     */
+    reapIdle(ttlMs: number): number;
+    /**
+     * Push a JSON control message to every attached client of a terminal session. An `attach` (file/image)
+     * frame is ALSO buffered (bounded, oldest-dropped) so a client that (re)connects later still sees files
+     * that arrived while it was away — see {@link attach}'s replay. Other control frames (e.g. `ask`, which
+     * has its own answer/replay flow in the transport) are delivered live only.
+     */
+    pushControl(id: string, msg: unknown): boolean;
+    /**
+     * Set a session's `awaiting` flag ("claude is blocked on YOU"). The capture-pane monitor
+     * ({@link refreshActivity}) is the authority for this flag in production; this explicit setter exists for
+     * direct overrides and is exercised by the manager's tests. Deterministic — no timers, no terminal scraping.
+     * A missing session is a no-op. Does NOT fire the away-from-desk push — the monitor owns that so it can gate
+     * on {@link isAttached}.
+     */
+    setAwaiting(id: string, value: boolean): void;
+    /** Clear the awaiting flag (user is active / session ended). */
+    private clearAwaiting;
+    /** Whether a session currently has ≥1 attached client (a live browser WS). The hook route uses this so the
+     *  away-from-desk push fires ONLY when nobody is watching. */
+    isAttached(id: string): boolean;
+    /** How many sessions are currently `awaiting` you. Threaded into each away-from-desk push as `badgeCount`
+     *  so the home-screen app badge tracks "how many sessions need you" (Android/desktop badge; iOS can't). */
+    awaitingCount(): number;
+    /**
+     * Set/clear a session's display name (PATCH /sessions/:id). `undefined` clears back to unnamed. Written
+     * through to the store so the name survives restarts + rehydrate. Returns false for an unknown id so the
+     * route can 404 without a separate lookup.
+     */
+    setName(id: string, name: string | undefined): boolean;
+    /**
+     * Re-derive every RUNNING session's `awaiting` flag from its LIVE rendered tmux pane (`capture-pane`) — the
+     * single, UNIVERSAL source of truth for working / blocked / idle. Works for EVERY session (no per-session
+     * hooks needed → correct for sessions created before hooks existed) and works while the browser is DETACHED
+     * (it reads tmux directly). Called on a ~2.5s timer from start.ts. Read-only: it can never disturb a live
+     * session.
+     *
+     * {@link classifyPaneStatus} decides. A capture that returns "" (tmux hiccup) leaves the last value
+     * untouched so the status never flaps on a transient miss.
+     *
+     * `awaiting` (the loud "needs you" flag) tracks activity==="blocked" ONLY — a finished-but-idle session, or
+     * one whose background agents are still developing, is NOT "needs you". Fires
+     * {@link TerminalManagerDeps.onAwaiting} (the away push) on a not-blocked→blocked transition when no client is
+     * attached, so the nudge is universal + fires only for a genuine block.
+     */
+    refreshActivity(): Promise<void>;
+    /**
+     * Nudge tmux to repaint the WHOLE screen for a session whose pty is already running — used when a client
+     * REATTACHES (a fresh xterm) to a still-live tmux client that drew its screen earlier and won't redraw on
+     * its own, so the new client would otherwise show only a blinking cursor until something changes. A brief
+     * pty size wiggle (+1 row, then back) sends SIGWINCH, which makes tmux redraw — exactly what the manual
+     * window-resize the user found does, minus the manual part. Deferred so the new client's own initial resize
+     * lands first (rec.cols/rec.rows are then the final size we wiggle around). Best-effort + unref'd timers.
+     */
+    private forceRedraw;
+    /** Subscribe to provider output, spawning lazily through the owning provider on the first attach. */
+    attach(id: string, handlers: {
+        onData: (chunk: string) => void;
+        onExit?: () => void;
+        onControl?: (msg: string) => void;
+    }, size?: {
+        cols: number;
+        rows: number;
+    }, opts?: {
+        respawn?: "continue" | "fresh";
+        signal?: AbortSignal;
+    }): Promise<TerminalSub | undefined>;
+    private spawnForRecord;
+    private cleanupProviderPaths;
+    private cleanupRecordPaths;
+    private applyRuntimeSignal;
+    write(id: string, data: string): void;
+    resize(id: string, cols: number, rows: number): void;
+    stop(id: string): void;
+    get(id: string): TerminalMeta | undefined;
+    list(): TerminalMeta[];
+    /**
+     * After a server/OTA restart: adopt stored terminal sessions whose tmux session is still alive (so they
+     * reappear, resumable), prune store rows whose tmux session is gone, AND kill ORPHAN tmux sessions — live
+     * `rc-*` sessions with no store row (leaked by a crash or an interrupted cleanup) — so they don't pile up.
+     */
+    rehydrate(opts: {
+        liveTmuxNames: string[];
+    }): void;
+    /** Kill a tmux session for an id without needing a live proc (reuses TerminalProcess's socketed kill). */
+    private killTmux;
+}
+
+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;
+}
+
+declare function providerPreflightWarning(name: string, availability: ProviderAvailability): string | undefined;
+declare function runProviderPreflight(providers: ReadonlyArray<{
     name: string;
     probe(): Promise<ProviderAvailability>;
 }>, warn?: (msg: string) => void): Promise<void>;
@@ -12,14 +592,14 @@ export declare function runProviderPreflight(providers: ReadonlyArray<{
  * to surface WHY in the logs immediately, like the better-sqlite3 fallback warning. Returns `undefined`
  * when claude is available (no warning). PURE so it's unit-testable without spawning.
  */
-export declare function claudePreflightWarning(availability: ClaudeAvailability): string | undefined;
+declare function claudePreflightWarning(availability: ClaudeAvailability): string | undefined;
 /**
  * Run the startup preflight: best-effort probe `claude --version` and print {@link claudePreflightWarning}
  * if it's missing/failing. NEVER throws and NEVER blocks boot — a hung/slow claude can't stall startup
  * (the probe is short-timeout-guarded). Injectable probe + log sink so it's testable without a spawn.
  */
-export declare function runClaudePreflight(probe: ClaudeVersionProbe, warn?: (msg: string) => void): Promise<void>;
-export declare function startServer(env?: NodeJS.ProcessEnv): Promise<CreateServerResult & {
+declare function runClaudePreflight(probe: ClaudeVersionProbe, warn?: (msg: string) => void): Promise<void>;
+declare function startServer(env?: NodeJS.ProcessEnv): Promise<CreateServerResult & {
     url: string;
     token?: string;
     tokenGenerated: boolean;
@@ -28,4 +608,6 @@ export declare function startServer(env?: NodeJS.ProcessEnv): Promise<CreateServ
  *  `error` (e.g. a write-after-teardown on a dying claude child, or a detached updater spawn failure)
  *  LOGS instead of taking the whole server down — for an always-on self-hosted server, staying up beats
  *  crashing. Install ONCE at a process entry (never in startServer, which tests call repeatedly). */
-export declare function installCrashGuards(): void;
+declare function installCrashGuards(): void;
+
+export { claudePreflightWarning, installCrashGuards, providerPreflightWarning, runClaudePreflight, runProviderPreflight, startServer };