@roamcode.ai/server 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -1,82 +1,2406 @@
-export declare const SERVER_PACKAGE = "@roamcode.ai/server";
-export { loadConfig, buildMcpConfigDocument, mcpConfigPathFor, buildHooksSettingsDocument, hooksSettingsPathFor, hookAuthPathFor, hookAuthFileContent, } from "./config.js";
-export type { ServerConfig, AttachSpawnOptions, McpConfigDocument, HooksSettingsDocument } from "./config.js";
-export { loadServerConfig, isLoopbackAddress, assertConfigAllowsStart } from "./server-config.js";
-export type { ServerRuntimeConfig } from "./server-config.js";
-export { AuthGate, extractBearerToken } from "./auth.js";
-export type { AuthGateOptions, AuthCheckResult } from "./auth.js";
-export { FsService, FsError, SEARCH_MAX_DEPTH, SEARCH_MAX_DIRS, SEARCH_MAX_RESULTS } from "./fs-service.js";
-export type { DirEntry, DirListing, DirSearchResult, FsServiceOptions, FsErrorCode } from "./fs-service.js";
-export { openSessionStore } from "./session-store.js";
-export type { SessionStore, StoredSession, StoredStatus, OpenSessionStoreOptions, StoreMode } from "./session-store.js";
-export { normalizeSessionDefaults, SessionDefaultsConflictError } from "./session-defaults.js";
-export type { SessionDefaults, StoredSessionDefaults } from "./session-defaults.js";
-export { resolveDataDir, ensureDataDir, resolveAccessToken, generateAccessToken, persistAccessToken, } from "./data-dir.js";
-export type { ResolveAccessTokenOptions } from "./data-dir.js";
-export { isOriginAllowed, normalizeOrigin, parseAllowedOrigins } from "./origin-check.js";
-export type { OriginCheckOptions } from "./origin-check.js";
-export { RateLimiter } from "./rate-limit.js";
-export type { RateLimiterOptions, RateLimitDecision } from "./rate-limit.js";
-export { resolveVapidKeys } from "./vapid.js";
-export type { VapidKeys, ResolveVapidKeysOptions } from "./vapid.js";
-export { createServer } from "./transport.js";
-export type { CreateServerResult, CreateServerDeps } from "./transport.js";
-export { registerStatic, isPublicPath, isPublicForRequest, isShellPath, pathForGate, hasEncodedSep, looksLikeAssetRequest, API_PATH_DENYLIST, SHELL_PATH_ALLOWLIST, } from "./static-routes.js";
-export type { RegisterStaticOptions } from "./static-routes.js";
-export { startServer, claudePreflightWarning, runClaudePreflight, providerPreflightWarning, runProviderPreflight, } from "./start.js";
-export { TerminalProcess, tmuxSessionName } from "./terminal-process.js";
-export type { TerminalProcessOptions, IPty, PtySpawn } from "./terminal-process.js";
-export { TerminalManager } from "./terminal-manager.js";
-export type { TerminalMeta, TerminalSub, TerminalManagerDeps } from "./terminal-manager.js";
-export { detectTerminalSupport } from "./terminal-capability.js";
-export { listTmuxSessions } from "./tmux-list.js";
-export { classifyPaneStatus, capturePane, CLASSIFIER_TESTED_UP_TO, isNewerMajorMinor, classifierVersionWarning, } from "./pane-status.js";
-export type { PaneStatus, CaptureOptions } from "./pane-status.js";
-export { WsTicketStore, WS_TICKET_TTL_MS } from "./ws-ticket.js";
-export type { WsTicketStoreOptions } from "./ws-ticket.js";
-export { openPushStore } from "./push-store.js";
-export type { PushStore, PushSubscriptionRecord, OpenPushStoreOptions } from "./push-store.js";
-export { createWebPushSend } from "./web-push-send.js";
-export type { CreateWebPushSendOptions, PushSendFn, PushRecipient } from "./web-push-send.js";
-export { createPushDispatcher, buildPushPayload } from "./push-dispatch.js";
-export type { PushDispatcher, PushEvent, PushPayload, PushEventKind, CreatePushDispatcherDeps, } from "./push-dispatch.js";
-export { Updater, createUpdater, defaultUpdaterFs, defaultFetchReleases, defaultFetchManifest, stableReleases, normalizeRelease, parseReleaseNotes, relativeWhen, computeInstallDrift, RUNNING_VERSION, CHECK_CACHE_MS, FETCH_TIMEOUT_MS, } from "./updater.js";
-export type { UpdaterDeps, UpdaterFs, FetchReleases, FetchManifest, GitHubRelease, ReleaseRecord, ChangelogEntry, VersionInfo, UpdateState, UpdateStatus, UpdateAction, InstallationKind, } from "./updater.js";
-export { RUNNING_BUILD, computeBuildDrift } from "./updater.js";
-export { resolveInstallRoot, managedPaths, readActiveVersion, readPreviousVersion, writeManagedLauncher, renderManagedLauncher, installManagedRelease, isStableVersion, compareVersions, } from "./managed-runtime.js";
-export type { ManagedPaths, ManagedInstallOptions, ManagedInstallResult, ManagedInstallStatus, } from "./managed-runtime.js";
-export { installService, readServiceRecord, migrateServiceToLauncher, restartService, enableService, renderLaunchdPlist, renderSystemdUnit, buildServicePath, } from "./service-install.js";
-export type { InstallServiceContext, InstallServiceResult, ServiceRecord, RenderLaunchdOptions, RenderSystemdOptions, } from "./service-install.js";
-export { createClaudeVersionProbe, defaultRunClaudeVersion, parseClaudeVersion, normalizeProviderAvailability, CLAUDE_VERSION_CACHE_MS, CLAUDE_VERSION_TIMEOUT_MS, } from "./diag.js";
-export type { ClaudeAvailability, ClaudeVersionProbe, RunClaudeVersion } from "./diag.js";
-export { UsageService, createUsageService, createUsageRunner, parseUsage, USAGE_CACHE_MS, USAGE_TIMEOUT_MS, } from "./usage-service.js";
-export type { UsageInfo, Bar, ModelWeekBar, RunUsage, UsageServiceDeps } from "./usage-service.js";
-export { ClaudeAuthService, createClaudeAuthService, parseAuthStatus, extractLoginUrl } from "./claude-auth-service.js";
-export type { ClaudeAuthStatus, ClaudeAuthDeps } from "./claude-auth-service.js";
-export { ClaudeLatestService, createClaudeLatestService, parseNpmLatest, CLAUDE_LATEST_CACHE_MS, } from "./claude-latest-service.js";
-export type { ClaudeLatestDeps, FetchLatest } from "./claude-latest-service.js";
-export { ProviderError } from "./providers/types.js";
-export type { ProviderId, ProviderAvailability, ClaudeSessionOptions, CodexSessionOptions, ProviderSessionOptions, LaunchIntent, ProcessSpec, ProviderProcessContext, ProviderRuntimeSignal, ProviderRuntimeSignalParser, AgentProvider, } from "./providers/types.js";
-export { ProviderOptionsError, parseProviderOptions, parseLegacyClaudeArgs } from "./providers/options.js";
-export { ProviderRegistry } from "./providers/registry.js";
-export { createClaudeProvider } from "./providers/claude-provider.js";
-export type { CreateClaudeProviderOptions } from "./providers/claude-provider.js";
-export { ClaudeMetadataService, createClaudeMetadataRunner } from "./providers/claude-metadata-service.js";
-export type { ClaudeMetadataRunner, ClaudeModelCatalogItem } from "./providers/claude-metadata-service.js";
-export { createCodexProvider, buildCodexArgs } from "./providers/codex-provider.js";
-export type { CreateCodexProviderOptions } from "./providers/codex-provider.js";
-export { CodexMetadataService } from "./providers/codex-metadata-service.js";
-export type { CodexMetadataRpc, CodexMetadataServiceOptions, CodexAccount, CodexModel, CodexUsage, CodexDeviceLogin, CodexLoginCompletion, CodexLoginStatus, } from "./providers/codex-metadata-service.js";
-export { CodexAppServerClient } from "./providers/codex-app-server-client.js";
-export type { CodexAppServerClientOptions, CodexMetadataDiagnostics } from "./providers/codex-app-server-client.js";
-export { CodexLatestService, parseCodexVersion } from "./providers/codex-latest-service.js";
-export type { CodexVersionInfo, CodexInstallProvenance } from "./providers/codex-latest-service.js";
-export { createCodexProfileClientLifecycle, isCodexProfileClientLifecycle } from "./providers/codex-profile-client.js";
-export type { CodexProfileClientLifecycle, CreateCodexProfileClientLifecycleOptions, } from "./providers/codex-profile-client.js";
-export { createCodexThreadPersistence } from "./providers/codex-thread-persistence.js";
-export type { CodexThreadPersistence } from "./providers/codex-thread-persistence.js";
-export type { CodexSpawnLease } from "./providers/codex-thread-coordinator.js";
-export { CodexThreadResolver, createCodexThreadInventory, resetCodexThreadResolutionCoordinatorForTests, } from "./providers/codex-thread-resolver.js";
-export type { CodexThreadInventoryEntry, CodexThreadResolverOptions, ResolveCodexThreadOptions, } from "./providers/codex-thread-resolver.js";
-export { CODEX_CLASSIFIER_TESTED_UP_TO, CODEX_OSC_MAX_CARRY, classifyCodexPane, codexClassifierVersionWarning, createCodexOscParser, parseCodexOscNotifications, } from "./providers/codex-activity.js";
-export type { CodexOscParser } from "./providers/codex-activity.js";
+import * as better_sqlite3 from 'better-sqlite3';
+import { FastifyInstance } from 'fastify';
+import { spawn, ChildProcess, SpawnOptions } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { ZodType } from 'zod';
+
+interface ServerConfig {
+    claudeBin: string;
+}
+declare function loadConfig(env: NodeJS.ProcessEnv): ServerConfig;
+/**
+ * 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;
+}
+/** The `{ mcpServers: { ... } }` document written to the per-session 0600 config file. */
+interface McpConfigDocument {
+    mcpServers: {
+        roamcode: {
+            command: string;
+            args: string[];
+            env: {
+                RC_BASE_URL: string;
+                RC_SESSION_ID: string;
+                RC_TOKEN: string;
+            };
+        };
+    };
+}
+/**
+ * Build the MCP config document for a session. PURE: no fs, no token leakage — the caller writes the
+ * returned object to a 0600 file and passes its path to the terminal spawn as `--mcp-config`.
+ */
+declare function buildMcpConfigDocument(sessionId: string, attach: AttachSpawnOptions): McpConfigDocument;
+/** Absolute path of the per-session MCP config file inside the data dir. */
+declare function mcpConfigPathFor(dataDir: string, sessionId: string): string;
+/**
+ * Per-session Claude Code settings document (written 0600, passed as `--settings <path>`). Its HOOKS let
+ * claude signal turn boundaries DIRECTLY instead of us scraping the terminal (which can't tell "generating /
+ * running a background agent" from "waiting for you" — the source of the false "needs you"):
+ *   - `Stop`             → claude finished its turn and is now waiting on YOU (mark awaiting).
+ *   - `UserPromptSubmit` → you submitted a prompt → clear it.
+ * Each hook curls a loopback endpoint, reading the access token from a 0600 file via `-H '@authFile'` so the
+ * token never lands in the hook's argv (ps/proc), and ends in `|| true` so a hook can NEVER block/fail claude.
+ * Hooks fire in an interactive tmux pane, including under `--dangerously-skip-permissions` (verified).
+ */
+interface HookCommand {
+    type: "command";
+    command: string;
+}
+interface HooksSettingsDocument {
+    hooks: {
+        Stop: Array<{
+            hooks: HookCommand[];
+        }>;
+        UserPromptSubmit: Array<{
+            hooks: HookCommand[];
+        }>;
+    };
+}
+/** Build the per-session hooks settings. PURE: the caller writes it to a 0600 file + the 0600 `authFilePath`. */
+declare function buildHooksSettingsDocument(sessionId: string, attach: Pick<AttachSpawnOptions, "baseUrl">, authFilePath: string): HooksSettingsDocument;
+/** Absolute path of the per-session hooks settings file inside the data dir. */
+declare function hooksSettingsPathFor(dataDir: string, sessionId: string): string;
+/** Absolute path of the per-session 0600 auth-header file the hook curls read via `-H '@file'`. */
+declare function hookAuthPathFor(dataDir: string, sessionId: string): string;
+/** The exact bytes of that auth-header file (a single curl `-H` line). Keeps the token out of hook argv. */
+declare function hookAuthFileContent(token: string): string;
+
+interface ServerRuntimeConfig {
+    /** TCP port to listen on. Default 4280. */
+    port: number;
+    /** Address to bind. Default "127.0.0.1" (loopback). */
+    bindAddress: string;
+    /** Mandatory access token. Optional only for loopback binds (spec §9). */
+    accessToken?: string;
+    /** Root directory the file picker / fs-service is confined to. Default $HOME or cwd. */
+    fsRoot: string;
+    /** Max bytes accepted for an upload. Default 25 MiB. */
+    maxUploadBytes: number;
+    /** Host data dir for the SQLite DB + access token file. */
+    dataDir: string;
+    /**
+     * Trust X-Forwarded-* (passed to Fastify as `trustProxy`). Default false. PREFER a specific proxy IP/CIDR
+     * (e.g. "127.0.0.1" for a same-host cloudflared/Caddy) over `true`: `true` trusts EVERY hop and takes the
+     * left-most XFF entry, which a client can prepend to spoof `request.ip` and poison the rate limiter. A
+     * string here is Fastify's trustProxy spec (IP, CIDR, or comma-list); boolean true = trust all hops.
+     */
+    trustProxy?: boolean | string;
+    /**
+     * The public-facing origin (ROAMCODE_PUBLIC_URL). Used by the Origin/CSWSH guard as an allow-listed
+     * origin (the PWA is installed under this when behind a tunnel) AND by start.ts for push deep-links.
+     */
+    publicUrl?: string;
+    /**
+     * Extra Origins the CSWSH guard allows, beyond same-origin / loopback / publicUrl
+     * (ROAMCODE_ALLOWED_ORIGINS, comma-separated). Empty by default — the safe default already lets the
+     * real app through; this is only to permit an additional known front-end origin.
+     */
+    allowedOrigins: string[];
+    /**
+     * Global per-client request rate limit (token bucket). `rateLimitRpm` requests/minute sustained,
+     * `rateLimitBurst` instantaneous. Set rateLimitRpm to 0 to DISABLE the limiter entirely.
+     * (ROAMCODE_RATE_LIMIT_RPM / ROAMCODE_RATE_LIMIT_BURST.)
+     */
+    rateLimitRpm: number;
+    rateLimitBurst: number;
+    /** Max concurrent LIVE sessions/processes; POST /sessions is refused (429) at the cap. 0 disables the
+     *  cap. (ROAMCODE_MAX_SESSIONS.) */
+    maxSessions: number;
+    /** Kill running terminal sessions with NO attached client that have been idle longer than this many ms.
+     *  0 (default) DISABLES it — sessions survive a disconnect indefinitely for later reattach. Opt-in
+     *  (SESSION_IDLE_TTL_MS) for hosts that want to bound detached claude+tmux accumulation. Optional in the
+     *  type (older config literals / tests omit it); consumers treat an absent value as 0 (disabled). */
+    sessionIdleTtlMs?: number;
+    /** The claude-spawn config (claudeBin). */
+    claude: ServerConfig;
+    /** Codex CLI executable. Defaults to `codex`; independently overridable with CODEX_BIN. */
+    codexBin: string;
+}
+declare function loadServerConfig(env: NodeJS.ProcessEnv): ServerRuntimeConfig;
+declare function isLoopbackAddress(address: string): boolean;
+/** Spec §9: refuse to serve a non-loopback bind without a token. */
+declare function assertConfigAllowsStart(cfg: ServerRuntimeConfig): void;
+
+declare function extractBearerToken(authorizationHeader: string | undefined): string | undefined;
+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;
+}
+
+type FsErrorCode = "forbidden" | "not-found" | "exists";
+declare class FsError extends Error {
+    readonly code: FsErrorCode;
+    constructor(code: FsErrorCode, message: string);
+}
+interface DirEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isGitRepo: boolean;
+    gitBranch?: string;
+}
+interface DirListing {
+    path: string;
+    parent?: string;
+    entries: DirEntry[];
+}
+interface FsServiceOptions {
+    root: string;
+}
+/** One GET /fs/search hit — a DIRECTORY whose name matched, shaped for the picker. */
+interface DirSearchResult {
+    path: string;
+    name: string;
+    isGitRepo: boolean;
+}
+/** GET /fs/search walk bounds. Depth 5 / 400 dirs keeps the worst case (a huge home dir) to a bounded,
+ *  sub-second readdir sweep; 30 results is more than a picker list ever shows. */
+declare const SEARCH_MAX_DEPTH = 5;
+declare const SEARCH_MAX_DIRS = 400;
+declare const SEARCH_MAX_RESULTS = 30;
+declare class FsService {
+    private readonly root;
+    constructor(opts: FsServiceOptions);
+    /** Resolve a target (absolute or relative to root) and confine it to root. */
+    resolveWithinRoot(target: string): string;
+    /** Resolve real paths so a symlink inside root cannot point outside it. Missing -> not-found. */
+    private realWithinRoot;
+    listDirectory(target: string): Promise<DirListing>;
+    /** Read .git/HEAD cheaply; return the branch name or undefined if not a repo. */
+    private readGitBranch;
+    readFileForDownload(target: string): Promise<{
+        filename: string;
+        data: Buffer;
+    }>;
+    /**
+     * Validate that `target` is a real in-root file and describe it for an attachment frame WITHOUT
+     * reading its bytes. Reuses the same resolveWithinRoot + realpath defense as readFileForDownload so
+     * a traversal/symlink-escape path throws FsError("forbidden") and a missing path FsError("not-found").
+     */
+    describeForAttachment(target: string): Promise<{
+        name: string;
+        isImage: boolean;
+    }>;
+    writeUploadedFile(targetDir: string, filename: string, data: Buffer): Promise<{
+        path: string;
+    }>;
+    /** Ensure a directory (confined to root) exists, creating parents as needed; returns its absolute path. */
+    ensureDirWithinRoot(target: string): Promise<string>;
+    /**
+     * POST /fs/mkdir: create ONE new directory (recursive:false — the picker creates a single folder under
+     * an existing parent; a missing parent is a client bug, not something to silently paper over). Same
+     * confinement as listDirectory: resolveWithinRoot on the target + realpath on the PARENT (the target
+     * itself doesn't exist yet), so a symlinked parent can't smuggle the create outside root.
+     * Errors: "exists" (→409) when the path is already taken, "not-found" (→404) when the parent is
+     * missing, "forbidden" (→403) on any escape.
+     */
+    makeDirectory(target: string): Promise<{
+        path: string;
+    }>;
+    /**
+     * GET /fs/search: case-insensitive SUBSTRING match on DIRECTORY names under `base` (default root),
+     * for the project picker's "type to find your repo" flow. Breadth-first — so results come back
+     * shallowest-first without a sort — bounded by {@link SEARCH_MAX_DEPTH} / {@link SEARCH_MAX_DIRS} /
+     * {@link SEARCH_MAX_RESULTS} so a giant tree can never wedge the request. Dot-entries and node_modules
+     * are skipped (never a project root; node_modules alone would blow the dir budget). Unreadable dirs are
+     * skipped, not fatal. Same fsRoot confinement as every other fs route; entries are reported by their
+     * in-root path (symlinked children are NOT re-resolved — mirroring listDirectory).
+     */
+    searchDirectories(query: string, base?: string): Promise<DirSearchResult[]>;
+    /** Prune expired files inside EACH immediate subdirectory of `base` (confined to root). Used to age out
+     *  the terminal shared-files folders (one per session) in a single sweep — including ORPHANED folders
+     *  whose session no longer exists (the old per-live-session sweep leaked those forever). Best-effort:
+     *  returns the total files removed; a missing base / unreadable entry is skipped, not thrown. */
+    pruneChildDirsOlderThan(base: string, maxAgeMs: number, now?: number): Promise<number>;
+    /** Delete top-level regular files in `target` (confined to root) whose mtime is older than `maxAgeMs`.
+     *  Best-effort — returns how many were removed; a missing dir / unreadable entry is skipped, not thrown.
+     *  Subdirectories are left untouched. Used to give terminal shared-files uploads a bounded lifetime. */
+    pruneOlderThan(target: string, maxAgeMs: number, now?: number): Promise<number>;
+}
+
+type ProviderId = "claude" | "codex";
+interface ProviderAvailability {
+    terminalAvailable: boolean;
+    metadataAvailable: boolean;
+    version?: string;
+    detail?: string;
+}
+declare class ProviderError extends Error {
+    readonly code: "PROVIDER_UNAVAILABLE" | "INVALID_PROVIDER_OPTIONS" | "RESUME_IDENTITY_UNAVAILABLE" | "OSS_PROVIDER_DEFERRED";
+    constructor(code: "PROVIDER_UNAVAILABLE" | "INVALID_PROVIDER_OPTIONS" | "RESUME_IDENTITY_UNAVAILABLE" | "OSS_PROVIDER_DEFERRED", message: 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 CodexProfileLaunchProof {
+    readonly profile: string;
+    readonly codexHome: string;
+    readonly assertUnchanged: () => Promise<void>;
+}
+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 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;
+}
+declare function normalizeSessionDefaults(value: unknown): SessionDefaults;
+declare class SessionDefaultsConflictError extends Error {
+    readonly current: StoredSessionDefaults | undefined;
+    constructor(current: StoredSessionDefaults | undefined);
+}
+
+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;
+}
+interface OpenSessionStoreOptions {
+    /** Path to the SQLite file. ":memory:" uses an in-process DB. */
+    dbPath: string;
+    /** Injectable better-sqlite3 loader (the seam tests use to FORCE the in-memory fallback by throwing).
+     *  Defaults to `require("better-sqlite3")`. */
+    loadDatabase?: () => typeof better_sqlite3;
+}
+declare function openSessionStore(opts: OpenSessionStoreOptions): SessionStore;
+
+/**
+ * Host data dir for the SQLite DB + access token. Never inside the project tree by default.
+ *
+ * Rename compat (Remote Coder → RoamCode): installs that predate the rename keep their data where it
+ * already lives — the legacy `REMOTE_CODER_DATA_DIR` env still wins over defaults, and an existing
+ * `…/remote-coder` dir is preferred over creating a fresh `…/roamcode` (their token / service.json /
+ * session index MUST survive an OTA update). Only brand-new installs get the new directory name.
+ */
+declare function resolveDataDir(env: NodeJS.ProcessEnv, exists?: (p: string) => boolean): string;
+declare function ensureDataDir(dir: string): void;
+/**
+ * Strong default token: 32 bytes of CSPRNG entropy (>= spec §9 baseline),
+ * base64url-encoded (43 chars, no padding). Never Math.random / randomUUID.
+ */
+declare function generateAccessToken(): string;
+/**
+ * Persist a token to `<dataDir>/token` with mode 0600 (overwriting any prior file). Used by both first-run
+ * generation and POST /token/rotate. `writeFileSync`'s `mode` is honored only when CREATING a file, so we
+ * chmod unconditionally afterwards — a rotated secret can never land in a too-permissive (e.g. world-
+ * readable) file left behind by an earlier write.
+ */
+declare function persistAccessToken(dataDir: string, token: string): void;
+interface ResolveAccessTokenOptions {
+    /** From ACCESS_TOKEN; when set it wins and is not persisted. */
+    configured?: string;
+    dataDir: string;
+    /** Injectable generator for tests. Defaults to a 32-byte base64url CSPRNG token. */
+    generate?: () => string;
+}
+/**
+ * Spec §9: a long random secret generated on first run (printed once, stored).
+ * Precedence: explicit ACCESS_TOKEN > persisted token file > freshly generated.
+ *
+ * A configured (env) token is used verbatim and never written to disk. A
+ * generated token is persisted to `<dataDir>/token` with mode 0600 so other
+ * users on the host cannot read it; `generated: true` lets the caller print it
+ * once with the access URL.
+ */
+declare function resolveAccessToken(opts: ResolveAccessTokenOptions): {
+    token: string;
+    generated: boolean;
+};
+
+/**
+ * Origin / CSWSH (cross-site WebSocket hijacking) guard for the WS upgrade and state-changing HTTP.
+ *
+ * The token is the only auth boundary, and it can leak into a URL (`?token=` connect link, push deep
+ * link, browser history). The WS handshake (and any browser-driven HTTP) carries an `Origin` header the
+ * page CANNOT forge — so a malicious cross-origin page that somehow holds the token still can't make the
+ * BROWSER attach to our WS / drive our API, because the browser stamps its OWN origin on the request and
+ * we reject it. Without this check, a leaked-in-URL token is enough for a foreign page to puppet the host.
+ *
+ * SAFE DEFAULT (must never reject the real app): a request is allowed when
+ *   - the `Origin` header is ABSENT (native/non-browser clients, same-origin navigations + most
+ *     same-origin GETs omit it — the PWA's own fetches are same-origin), OR
+ *   - the Origin's host:port equals the request `Host` (same-origin — the PWA always is), OR
+ *   - the Origin matches the configured public URL (ROAMCODE_PUBLIC_URL), OR
+ *   - the Origin is a loopback/localhost origin (local dev), OR
+ *   - the Origin is in the explicit ROAMCODE_ALLOWED_ORIGINS allow-list.
+ * Only a PRESENT, cross-origin, non-allow-listed Origin is rejected (403).
+ */
+/** Normalize a URL/origin string to a comparable `scheme://host[:port]` origin (lowercased). Returns
+ *  undefined for anything that isn't a parseable absolute URL (so it can never match by accident). */
+declare function normalizeOrigin(value: string | undefined): string | undefined;
+interface OriginCheckOptions {
+    /** The configured public-facing origin (from ROAMCODE_PUBLIC_URL). May be a full URL. */
+    publicUrl?: string;
+    /** Extra allow-listed origins (ROAMCODE_ALLOWED_ORIGINS, comma-separated → array). */
+    allowedOrigins?: string[];
+}
+/**
+ * Decide whether a request's Origin is allowed. PURE / I/O-free so it is unit-testable; the transport
+ * preHandler passes `origin` (the header) and `host` (the request Host header).
+ *
+ * @param origin the request's `Origin` header (may be undefined)
+ * @param host   the request's `Host` header (e.g. `remotecode.example.com` or `127.0.0.1:4280`)
+ */
+declare function isOriginAllowed(origin: string | undefined, host: string | undefined, opts?: OriginCheckOptions): boolean;
+/** Parse a comma-separated ROAMCODE_ALLOWED_ORIGINS value into a trimmed, non-empty list. */
+declare function parseAllowedOrigins(raw: string | undefined): string[];
+
+/**
+ * Lightweight, in-memory, per-client rate limiter for the global preHandler. The per-IP auth LOCKOUT
+ * (auth.ts) only counts FAILED auth attempts and collapses behind a proxy; this adds a generous request
+ * cap so a flood (auth-guessing, scraping, accidental client loop) can't hammer the host — while staying
+ * well clear of any legitimate use (the PWA's periodic /sessions + /version poll, a burst of opens).
+ *
+ * Algorithm: a TOKEN BUCKET per client key (request.ip, honoring trustProxy — same key as the lockout).
+ * `capacity` tokens, refilled continuously at `capacity / windowMs` tokens/ms; each request spends one.
+ * A token bucket allows a short BURST (up to `capacity`) yet bounds the sustained rate — friendlier to
+ * bursty real traffic than a hard fixed window. PURE/I-O-free + an injectable clock so it is unit-testable.
+ *
+ * SAFE DEFAULTS (see server-config.ts): 600 requests / 60s sustained, burst 120 — orders of magnitude
+ * above the app's real cadence. Env-overridable and fully DISABLE-able (enabled:false → allow everything).
+ */
+interface RateLimiterOptions {
+    /** Sustained budget: `capacity` requests refill over `windowMs` (→ capacity/windowMs tokens per ms). */
+    capacity: number;
+    /** Refill window in ms for the full capacity. */
+    windowMs: number;
+    /** Max burst (bucket size). Defaults to `capacity`. A larger value tolerates a bigger instantaneous spike. */
+    burst?: number;
+    /** Master switch. false → {@link RateLimiter.take} always allows (the limiter is off). Default true. */
+    enabled?: boolean;
+    /** Injectable clock for tests. Default Date.now. */
+    now?: () => number;
+}
+interface RateLimitDecision {
+    /** True → allow the request (a token was spent or the limiter is off). */
+    allowed: boolean;
+    /** When NOT allowed, seconds the client should wait before retrying (for the Retry-After header). */
+    retryAfterSeconds: number;
+}
+declare class RateLimiter {
+    private readonly capacity;
+    private readonly windowMs;
+    private readonly burst;
+    private readonly enabled;
+    private readonly now;
+    private readonly ratePerMs;
+    private readonly clients;
+    constructor(opts: RateLimiterOptions);
+    /**
+     * Account for ONE request from `clientKey`. Refills the bucket by elapsed time, then spends a token if
+     * one is available. Returns {allowed:true} when a token was spent (or the limiter is disabled), else
+     * {allowed:false, retryAfterSeconds} — the whole-seconds wait until the next token is available.
+     */
+    take(clientKey: string): RateLimitDecision;
+    /** Drop fully-refilled buckets so the map stays bounded (a one-shot client doesn't linger forever). */
+    private sweepFull;
+    /** TEST ONLY: number of tracked client buckets. */
+    trackedClientCount(): number;
+}
+
+interface VapidKeys {
+    /** URL-safe base64 public key — safe to send to the browser for the push subscription. */
+    publicKey: string;
+    /** URL-safe base64 private key — NEVER leaves the server (signs pushes). */
+    privateKey: string;
+}
+interface ResolveVapidKeysOptions {
+    dataDir: string;
+    /** Injectable generator for tests. Defaults to web-push's NIST P-256 generator. */
+    generate?: () => VapidKeys;
+}
+/**
+ * Generate the VAPID keypair on first run and persist it to `<dataDir>/vapid.json` (mode 0600 — the
+ * private key is a server secret). On subsequent runs the persisted pair is reused so existing
+ * browser subscriptions stay valid (rotating the key would invalidate every subscription).
+ */
+declare function resolveVapidKeys(opts: ResolveVapidKeysOptions): VapidKeys;
+
+/**
+ * Single-use, short-lived tickets for the terminal WebSocket handshake.
+ *
+ * WHY: a browser WebSocket cannot send an Authorization header, so the client historically put the
+ * LONG-LIVED access token in the WS URL (`?token=`). Query strings are routinely written into proxy /
+ * tunnel / access logs, so that leaked a full-access credential. The flow now is: POST /ws-ticket (over
+ * the normal header-authed API) → get a 32-byte ticket → open the WS with `?ticket=`. A logged ticket is
+ * worthless: it is consumed by the very connection that carried it (single-use) and dies within TTL_MS
+ * anyway. The legacy `?token=` path is kept for old bundles (see transport.ts) but is deprecated.
+ */
+/** Ticket lifetime. Long enough for the client to turn the POST response into a WS connect (even on a
+ *  slow mobile link), short enough that a logged/leaked ticket is stale almost immediately. */
+declare const WS_TICKET_TTL_MS = 30000;
+interface WsTicketStoreOptions {
+    /** Override the TTL (tests). Default {@link WS_TICKET_TTL_MS}. */
+    ttlMs?: number;
+    /** Injectable clock for tests. Default Date.now. */
+    now?: () => number;
+    /** Injectable ticket generator for tests. Default: 32 CSPRNG bytes, base64url. */
+    generate?: () => string;
+}
+/**
+ * In-memory single-use ticket store. Deliberately NOT persisted: a ticket outliving a server restart
+ * would defeat its 30s point, and the client just re-POSTs on reconnect. Expired entries are swept
+ * LAZILY on each issue/consume — issuance is token-gated + rate-limited, so the map stays tiny without
+ * a timer.
+ */
+declare class WsTicketStore {
+    /** ticket → expiry (epoch ms). */
+    private readonly tickets;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly generate;
+    constructor(opts?: WsTicketStoreOptions);
+    /** Mint a fresh single-use ticket. The response shape is exactly what POST /ws-ticket returns. */
+    issue(): {
+        ticket: string;
+        expiresInMs: number;
+    };
+    /** Consume a ticket: true exactly ONCE for a live ticket; false for unknown, expired, or already-used
+     *  (the entry is deleted on first consume, so a replayed WS URL is rejected). */
+    consume(ticket: string): boolean;
+    /** Drop expired entries so an unconsumed flood can't grow the map (lazy — no timer to leak). */
+    private sweep;
+    /** TEST ONLY: how many un-consumed tickets are currently held (post-sweep count). */
+    size(): number;
+}
+
+interface PushSubscriptionRecord {
+    /** Browser push endpoint URL (PRIMARY KEY — one per subscription). */
+    endpoint: string;
+    /** PushSubscription.keys.p256dh (client public key). */
+    p256dh: string;
+    /** PushSubscription.keys.auth (client auth secret). */
+    auth: string;
+    /** Optional session scope; undefined = subscribed to ALL sessions. */
+    sessionId?: string;
+    createdAt: number;
+}
+interface PushStore {
+    upsert(sub: PushSubscriptionRecord): void;
+    /** All subscriptions, or — with { sessionId } — the global (NULL) ones UNION the session-scoped ones. */
+    list(opts?: {
+        sessionId?: string;
+    }): PushSubscriptionRecord[];
+    remove(endpoint: string): void;
+    close(): void;
+}
+interface OpenPushStoreOptions {
+    /** SQLite file path. ":memory:" uses an in-process DB. */
+    dbPath: string;
+}
+declare function openPushStore(opts: OpenPushStoreOptions): PushStore;
+
+interface PushRecipient {
+    endpoint: string;
+    p256dh: string;
+    auth: string;
+}
+type PushSendFn = (sub: PushRecipient, payload: string) => Promise<{
+    statusCode?: number;
+}>;
+interface CreateWebPushSendOptions {
+    vapid: VapidKeys;
+    /** VAPID subject: a mailto: or https: URL the push service can contact (web-push requires it). */
+    subject: string;
+}
+/**
+ * Bind a real Web Push sender. Maps our flat PushSubscriptionRecord to the {endpoint, keys} shape
+ * web-push.sendNotification expects, and normalizes the outcome to { statusCode } so the dispatcher
+ * can prune on 404/410 without depending on web-push's error type.
+ */
+declare function createWebPushSend(opts: CreateWebPushSendOptions): PushSendFn;
+
+/**
+ * The "away-from-desk" events that warrant a phone push. This is the whole point of roamcode: get
+ * pinged when claude needs you (awaiting), when it's done (finished), or when it hands you a file.
+ * "test" is the odd one out — a user-triggered "are notifications working?" ping (POST /push/test), which
+ * carries no session and never touches the home-screen badge.
+ */
+type PushEventKind = "awaiting" | "finished" | "file" | "test";
+interface PushEvent {
+    kind: PushEventKind;
+    /** The session the event is about — becomes the deep-link (`/?session=<id>`) AND the notification tag.
+     *  Absent for a "test" ping (which isn't about any session). */
+    sessionId?: string;
+    /** Optional enrichment: the file name (kind:"file") for the body. */
+    detail?: string;
+    /** Provider/session identity is bounded display metadata, never an auth or protocol payload. */
+    provider?: ProviderId;
+    label?: string;
+    /**
+     * Home-screen app-badge value = the count of sessions currently awaiting you. Stamped by the transport on
+     * every real dispatch (awaiting/finished/file) from {@link TerminalManager.awaitingCount}, so the SW
+     * can keep the badge in sync with "how many sessions need you". Omitted for a "test" ping (it must never
+     * clobber the badge). A missing value leaves the badge untouched on the client.
+     */
+    badgeCount?: number;
+}
+/**
+ * The Web Push payload the browser service worker consumes (packages/web `push` handler). The `tag` +
+ * `renotify` pair COLLAPSES repeated pushes for the same session into one re-alerting notification (so a
+ * flapping awaiting detector can't spam a phone), and `requireInteraction` keeps a "needs-you" alert
+ * sticky while a "done"/"file" alert can auto-dismiss.
+ */
+interface PushPayload {
+    title: string;
+    body: string;
+    /** Deep-link the notification opens — always `/?session=<sessionId>`. */
+    url: string;
+    /** Notification tag = sessionId, so the OS collapses per-session alerts (with renotify) rather than stack. */
+    tag: string;
+    renotify: boolean;
+    /** True for a waiting-for-user alert (awaiting); false for a done/file alert. */
+    requireInteraction: boolean;
+    /**
+     * The home-screen app-badge value the SW should apply (applyBadgeFromPush): the count of sessions currently
+     * awaiting you. Present on every real away-from-desk payload; ABSENT on a "test" ping (so it never clobbers
+     * the badge). The SW treats a missing value as "leave the badge alone" and 0 as "clear it". Android/desktop
+     * honor the app badge; iOS can't badge from a push.
+     */
+    badgeCount?: number;
+}
+interface PushDispatcher {
+    /**
+     * Build the payload for an away-from-desk event and fan it out over every matching subscription. NEVER
+     * throws (a push failure must never break the terminal / the calling route); dead subscriptions (404/410)
+     * are pruned from the store as a side effect.
+     */
+    dispatch(event: PushEvent): Promise<void>;
+}
+/**
+ * Map a semantic away-from-desk event to the Web Push payload the SW renders. Pure + exported so the exact
+ * contract is unit-testable (and the web agents can match it): every payload deep-links to the session and
+ * tags on the session id; only "needs-you" alerts (awaiting) set requireInteraction.
+ */
+declare function buildPushPayload(event: PushEvent): PushPayload;
+interface CreatePushDispatcherDeps {
+    pushStore: PushStore;
+    /** The bound Web Push sender (createWebPushSend). Injected so tests drive a fake without real crypto/HTTP. */
+    send: PushSendFn;
+    /** Optional log sink for a non-HTTP send failure (defaults to a no-op). */
+    log?: (msg: string) => void;
+}
+/**
+ * Build the push dispatcher. Fans an event out to the GLOBAL subscriptions UNION the ones scoped to the
+ * event's session (that's exactly what `pushStore.list({ sessionId })` returns), delivering to all in
+ * parallel. A send that reports 404 (Not Found) / 410 (Gone) means the browser subscription is dead — it's
+ * pruned from the store so it isn't retried forever. A non-HTTP failure (encryption, network throw) is
+ * logged and the sub is KEPT (it isn't known-dead). Never throws.
+ */
+declare function createPushDispatcher(deps: CreatePushDispatcherDeps): PushDispatcher;
+
+interface ManagedPaths {
+    root: string;
+    releases: string;
+    staging: string;
+    current: string;
+    previous: string;
+    bin: string;
+    launcher: string;
+    lock: string;
+}
+declare function resolveInstallRoot(env?: NodeJS.ProcessEnv, home?: string): string;
+declare function managedPaths(root: string): ManagedPaths;
+declare function isStableVersion(value: string): boolean;
+declare function compareVersions(a: string, b: string): number;
+declare function renderManagedLauncher(root: string, nodePath: string): string;
+declare function writeManagedLauncher(root: string, nodePath?: string): string;
+declare function readActiveVersion(root: string): string | undefined;
+declare function readPreviousVersion(root: string): string | undefined;
+interface ManagedInstallStatus {
+    operationId: string;
+    state: "starting" | "downloading" | "installing" | "verifying" | "activating" | "restarting" | "done" | "failed";
+    phase?: string;
+    target?: string;
+    fromVersion?: string;
+    error?: string;
+    log?: string;
+    updatedAt: number;
+}
+interface ManagedInstallOptions {
+    version: string;
+    installRoot: string;
+    dataDir: string;
+    operationId?: string;
+    expectedIntegrity?: string;
+    expectedIntegrities?: Record<string, string>;
+    nodePath?: string;
+    npmCommand?: string;
+    restart?: boolean;
+    rollback?: boolean;
+    now?: () => number;
+    onStatus?: (status: ManagedInstallStatus) => void;
+}
+interface ManagedInstallResult {
+    version: string;
+    previousVersion?: string;
+    releaseDir: string;
+    launcherPath: string;
+}
+declare function installManagedRelease(opts: ManagedInstallOptions): Promise<ManagedInstallResult>;
+
+declare global {
+    /** Stable package version injected by tsup. Source/test builds fall back to package.json. */
+    const __SERVER_VERSION__: string | undefined;
+}
+declare const RUNNING_VERSION: string;
+/** One-release compatibility export for diagnostics/tests that used the old SHA name. */
+declare const RUNNING_BUILD: string;
+declare const CHECK_CACHE_MS: number;
+declare const FETCH_TIMEOUT_MS = 20000;
+interface UpdaterFs {
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string) => string;
+    writeFileSync: (path: string, data: string, mode?: number) => void;
+    mkdirSync: (path: string) => void;
+    chmodSync: (path: string, mode: number) => void;
+    renameSync?: (from: string, to: string) => void;
+}
+declare const defaultUpdaterFs: UpdaterFs;
+interface GitHubReleaseAsset {
+    name: string;
+    browser_download_url: string;
+}
+interface GitHubRelease {
+    tag_name: string;
+    name?: string;
+    body?: string;
+    published_at?: string;
+    draft: boolean;
+    prerelease: boolean;
+    assets?: GitHubReleaseAsset[];
+}
+interface ReleaseRecord {
+    version: string;
+    tag: string;
+    name: string;
+    body: string;
+    publishedAt: string;
+    manifestUrl?: string;
+}
+interface ReleaseFetchResult {
+    releases?: GitHubRelease[];
+    etag?: string;
+    notModified?: boolean;
+}
+type FetchReleases = (etag?: string) => Promise<ReleaseFetchResult>;
+type FetchManifest = (url: string) => Promise<unknown>;
+interface ChangelogEntry {
+    id: string;
+    version: string;
+    subject: string;
+    group: "new" | "fixes" | "improvements" | "other";
+    when: string;
+    date: string;
+}
+type UpdateAction = "none" | "migrate" | "update" | "restart";
+type InstallationKind = "managed" | "legacy-git" | "unmanaged";
+interface VersionInfo {
+    current: string;
+    latest: string;
+    /** Compatibility alias: number of stable releases behind, never commit count. */
+    behind: number;
+    releaseCount: number;
+    updatable: boolean;
+    updateAvailable: boolean;
+    updateAction: UpdateAction;
+    installation: InstallationKind;
+    rollbackAvailable: boolean;
+    changelog: ChangelogEntry[];
+    runningVersion: string;
+    activeVersion?: string;
+    installDrift: boolean;
+    checkStatus: "fresh" | "stale" | "error";
+    checkedAt?: number;
+    error?: string;
+    /** Deprecated aliases retained until old precached clients have crossed the v1 bridge. */
+    runningBuild: string;
+    buildDrift: boolean;
+}
+type UpdateState = ManagedInstallStatus["state"] | "idle";
+interface UpdateStatus {
+    operationId?: string;
+    state: UpdateState;
+    phase?: string;
+    target?: string;
+    fromVersion?: string;
+    error?: string;
+    log?: string;
+    updatedAt?: number;
+}
+interface UpdaterDeps {
+    fs?: UpdaterFs;
+    spawn?: typeof spawn;
+    now?: () => number;
+    dataDir: string;
+    env?: NodeJS.ProcessEnv;
+    repoRoot?: string;
+    helperPath?: string;
+    fetchReleases?: FetchReleases;
+    fetchManifest?: FetchManifest;
+    runningVersion?: string;
+}
+declare function normalizeRelease(raw: GitHubRelease): ReleaseRecord | undefined;
+declare function stableReleases(raw: GitHubRelease[]): ReleaseRecord[];
+declare function relativeWhen(iso: string, now: number): string;
+declare function parseReleaseNotes(release: ReleaseRecord, now: number): ChangelogEntry[];
+declare function computeInstallDrift(runningVersion: string, activeVersion: string | undefined): boolean;
+/** Deprecated name retained as a version comparison alias. */
+declare const computeBuildDrift: (running: string, active: string) => boolean;
+declare function defaultFetchReleases(etag?: string): Promise<ReleaseFetchResult>;
+declare function defaultFetchManifest(url: string): Promise<unknown>;
+declare class Updater {
+    private readonly fs;
+    private readonly spawn;
+    private readonly now;
+    private readonly dataDir;
+    private readonly env;
+    private readonly repoRoot;
+    private readonly helperPath;
+    private readonly fetchReleases;
+    private readonly fetchManifest;
+    private readonly runningVersion;
+    private cache?;
+    private inFlight;
+    constructor(deps: UpdaterDeps);
+    private installRoot;
+    private installation;
+    private hasRestartableService;
+    private cachePath;
+    private loadPersistedReleaseCache;
+    private persistReleaseCache;
+    private refresh;
+    getVersion(force?: boolean): Promise<VersionInfo>;
+    readStatus(): UpdateStatus;
+    private writeStatus;
+    readLastGoodVersion(): string | undefined;
+    /** Deprecated compatibility method: rollback is now version/pointer based. */
+    readLastGoodSha(): string | undefined;
+    private updateIsRunning;
+    private finalizeRestartIfHealthy;
+    startUpdate(opts?: {
+        targetVersion?: string;
+        rollback?: boolean;
+    }): Promise<{
+        started: boolean;
+        reason?: string;
+        operationId?: string;
+        target?: string;
+    }>;
+}
+declare function createUpdater(opts: {
+    dataDir: string;
+    env?: NodeJS.ProcessEnv;
+    repoRoot?: string;
+    runningVersion?: string;
+}): Updater;
+
+/** Merge host and provider capability probes while replacing all provider/child detail with stable text. */
+declare function normalizeProviderAvailability(hostTerminalAvailable: boolean, probed: ProviderAvailability, metadataAvailable?: boolean): ProviderAvailability;
+/**
+ * Best-effort, CACHED `claude --version` probe for the authed GET /diag (fleet observability). It must
+ * NOT block the request long, so the spawn is timeout-guarded (short) and the result is cached for
+ * CLAUDE_VERSION_CACHE_MS — a /diag poll then never re-spawns within the window. A missing/erroring
+ * claude resolves to {available:false} (never throws), so /diag degrades instead of 500ing.
+ *
+ * The spawn is injectable (a function returning {stdout} or rejecting) so tests assert the caching +
+ * the available/unavailable shaping without spawning a real binary.
+ */
+/** How long a probe result (success OR failure) is reused before re-spawning. Long enough that the
+ *  /diag poll is cheap; short enough that a claude install/upgrade is reflected within a few minutes. */
+declare const CLAUDE_VERSION_CACHE_MS: number;
+/** Short hard timeout on the spawn so a hung claude never makes /diag hang. */
+declare const CLAUDE_VERSION_TIMEOUT_MS = 3000;
+interface ClaudeAvailability {
+    available: boolean;
+    /** The parsed version string (e.g. "1.2.3") when available; absent otherwise. */
+    version?: string;
+}
+/** Run `<bin> --version` (timeout-guarded), resolving its stdout. Rejects on spawn error / non-zero. */
+type RunClaudeVersion = () => Promise<{
+    stdout: string;
+}>;
+interface ClaudeVersionProbe {
+    /** Resolve the (cached) availability. Never rejects. */
+    get(): Promise<ClaudeAvailability>;
+}
+/** The real runner: `<claudeBin> --version` with the server env + a short timeout. */
+declare function defaultRunClaudeVersion(claudeBin: string, env: NodeJS.ProcessEnv): RunClaudeVersion;
+/**
+ * Extract a version-looking token from `claude --version` output (e.g. "1.2.3 (Claude Code)" → "1.2.3").
+ * Returns the trimmed raw string when no dotted-number token is found (still useful), or undefined for
+ * empty output.
+ */
+declare function parseClaudeVersion(raw: string): string | undefined;
+/** Build a cached probe over an injected runner + clock. */
+declare function createClaudeVersionProbe(deps: {
+    run: RunClaudeVersion;
+    now?: () => number;
+}): ClaudeVersionProbe;
+
+/**
+ * Claude usage limits (the `/usage` slash command), surfaced in the session rail and settings:
+ * the 5-hour SESSION limit, the all-model WEEKLY limit, and any provider-named weekly buckets.
+ *
+ * DATA SOURCE: the real `claude` CLI's `/usage` command returns the exact numbers. Invoked headlessly
+ * as `claudeBin -p "/usage" --output-format json --dangerously-skip-permissions` (clean exit, ONE JSON
+ * line). Its `.result` string carries the human-readable usage block we parse here, e.g.:
+ *
+ *   Current session: 12% used · resets Jun 25 at 11:30pm (Europe/Istanbul)
+ *   Current week (all models): 72% used · resets Jun 25 at 10pm (Europe/Istanbul)
+ *   Current week (Fable): 2% used · resets Jun 25 at 9:59pm (Europe/Istanbul)
+ *
+ * The spawn is the cost; a short TTL cache keeps it to ~once/3min regardless of how fast the rail
+ * polls. A failed/empty fetch (claude missing / not logged in / parse fail) degrades GRACEFULLY to the
+ * last good cached value, or null when there's none — the feature simply hides in the UI, never 500s.
+ *
+ * Deps are INJECTABLE (`runUsage` + `now`, mirroring the updater's style) so the parse + cache logic is
+ * unit-testable against fixture text with no real spawn.
+ */
+/** A single usage bar: percent used (0–100) plus a reset string when the provider supplies one. */
+interface Bar {
+    percent: number;
+    /** Claude omits this while a window is still at 0%, so reset time is optional. */
+    resets?: string;
+}
+interface ModelWeekBar extends Bar {
+    model: string;
+}
+/**
+ * Parsed usage snapshot. `session` is the 5-hour limit; `week` is the all-models weekly limit;
+ * `weekModels` contains provider-named weekly buckets. `weekSonnet` remains for older clients.
+ */
+interface UsageInfo {
+    session?: Bar;
+    week?: Bar;
+    /** Provider-named weekly buckets such as Fable or the legacy Sonnet-only limit. */
+    weekModels?: ModelWeekBar[];
+    /** Legacy compatibility for older clients; new code should prefer weekModels. */
+    weekSonnet?: Bar;
+    fetchedAt: number;
+}
+/** Resolve the raw `.result` string from `claude /usage`. NEVER rejects — resolves "" on any failure. */
+type RunUsage = () => Promise<string>;
+interface UsageServiceDeps {
+    runUsage: RunUsage;
+    /** Clock seam so the cache TTL is testable. */
+    now: () => number;
+    /** Cache TTL in ms (default USAGE_CACHE_MS). A getUsage within this window reuses the cache. */
+    ttlMs?: number;
+}
+interface UsagePty {
+    onData(cb: (data: string) => void): void;
+    onExit(cb: (event: {
+        exitCode: number;
+    }) => void): void;
+    kill(signal?: string): void;
+}
+type UsagePtySpawn = (file: string, args: string[], options: {
+    name: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => UsagePty;
+/** Cache TTL for a parsed usage snapshot. The rail polls ~every 60s; this throttles the real spawn to
+ * roughly once every few minutes regardless of poll rate. */
+declare const USAGE_CACHE_MS: number;
+/** Hard timeout for the `claude /usage` spawn so a hung CLI never blocks the /usage response. */
+declare const USAGE_TIMEOUT_MS = 15000;
+/**
+ * Parse the `/usage` result text into a UsageInfo. PURE: no spawn, no clock (the `now` arg stamps
+ * `fetchedAt`). Returns null when neither the session nor the all-models week line parses (the feature
+ * is then unavailable → the UI hides). Model-specific weeks and reset strings are optional. Reset
+ * strings are kept as-is (trimmed); the UI may shorten them further.
+ */
+declare function parseUsage(text: string, now?: number): UsageInfo | null;
+/**
+ * The real `runUsage` adapter. Claude 2.1.207+ omits account-limit lines when stdin is not a TTY, so a
+ * normal child-process pipe returns only the diagnostic "What's contributing" section and parses as no
+ * limits. Run the short-lived `/usage` command in its own isolated PTY instead. This is NOT a RoamCode tmux
+ * session; it exits with the command and never attaches to a user's chat. ANTHROPIC_API_KEY is stripped so
+ * subscription auth is used. NEVER rejects — resolves "" on spawn error, timeout, malformed JSON, or a
+ * missing `.result`.
+ */
+declare function createUsageRunner(opts: {
+    claudeBin: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    /** Test seam; production lazily loads node-pty, already required by terminal sessions. */
+    ptySpawn?: UsagePtySpawn;
+}): RunUsage;
+/**
+ * Resolves + caches the parsed Claude usage. The cache stores the LAST GOOD snapshot; the TTL governs
+ * when `runUsage` is re-run. A failed/empty fetch returns the last good value (or null), never throws.
+ */
+declare class UsageService {
+    private readonly runUsage;
+    private readonly now;
+    private readonly ttlMs;
+    private cache?;
+    constructor(deps: UsageServiceDeps);
+    /**
+     * Get the current usage. Within the TTL (and not forced) returns the cached snapshot WITHOUT
+     * re-spawning. Otherwise runs `runUsage`, parses, and (on success) caches it as the new last-good.
+     * A failed/empty refresh keeps the last good value (or null) and re-stamps the cache time so an
+     * outage doesn't re-spawn on every poll.
+     */
+    getUsage(force?: boolean): Promise<UsageInfo | null>;
+}
+/** Construct a UsageService with the real spawn adapter (the production wiring). */
+declare function createUsageService(opts: {
+    claudeBin: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    timeoutMs?: number;
+    ttlMs?: number;
+}): UsageService;
+
+/**
+ * In-app re-authentication of the `claude` CLI's Claude subscription, so a user whose server-side login
+ * expired (Anthropic returns 401 "Invalid authentication credentials" → every turn fails) can sign in
+ * again FROM THE APP instead of SSHing to the server to run `claude auth login`.
+ *
+ * It wraps `claude`'s OWN manual OAuth flow (no reverse-engineering of Anthropic's OAuth):
+ *   1. `claude auth login --claudeai` prints an authorize URL whose redirect is a HOSTED page
+ *      (platform.claude.com/oauth/code/callback — not localhost), then waits on stdin for a pasted code.
+ *   2. We spawn it, capture that URL, and hand it to the UI; the user opens it in ANY browser (their
+ *      phone), authorizes, and copies the code the callback page shows.
+ *   3. The UI posts the code back; we write it to the subprocess stdin; `claude` exchanges it and saves
+ *      FRESH credentials where every future claude spawn reads them — auth is restored, no restart needed.
+ *
+ * Single in-flight login at a time (a new start supersedes a stale one); a started login self-expires so
+ * an abandoned flow can't hold a subprocess forever. Spawn deps are injectable for unit tests.
+ */
+interface ClaudeAuthStatus {
+    /** Whether `claude` has stored credentials. NOTE: this reflects the LOCAL creds existing, not that they
+     *  still work — expired creds report loggedIn:true yet 401 on use, so re-auth is offered regardless. */
+    loggedIn: boolean;
+    email?: string;
+    /** "max" | "pro" | … (the Claude subscription tier), when reported. */
+    subscriptionType?: string;
+    authMethod?: string;
+    orgName?: string;
+}
+/** Parse `claude auth status` JSON output into a status. Returns {loggedIn:false} on any unparhseable/empty. */
+declare function parseAuthStatus(stdout: string): ClaudeAuthStatus;
+/** Pull the authorize URL out of `claude auth login` output ("…visit: https://…/oauth/authorize?…"). */
+declare function extractLoginUrl(output: string): string | undefined;
+interface ClaudeAuthDeps {
+    /** Spawn a claude subcommand: `claude <args>` with the server env (login-session creds resolve). */
+    spawn: (args: string[]) => ChildProcess;
+    now: () => number;
+    /** How long a started login waits for the URL before giving up (default 20s). */
+    urlTimeoutMs?: number;
+    /** How long a started login may sit awaiting its code before self-expiring (default 5min). */
+    loginTtlMs?: number;
+}
+declare class ClaudeAuthService {
+    private readonly deps;
+    private pending?;
+    constructor(deps: ClaudeAuthDeps);
+    /** Current `claude auth status` (which account is signed in). Never rejects → {loggedIn:false} on error. */
+    status(): Promise<ClaudeAuthStatus>;
+    /**
+     * Start a login: spawn `claude auth login --claudeai`, resolve with the authorize URL once it's printed.
+     * Supersedes any prior in-flight login. Rejects if the URL never appears (timeout / immediate exit).
+     */
+    startLogin(): Promise<{
+        loginId: string;
+        url: string;
+    }>;
+    /**
+     * Submit the pasted authorization code for an in-flight login: write it to the subprocess stdin and
+     * resolve once `claude` finishes the exchange. {ok:true} on a clean exit (fresh creds saved); {ok:false}
+     * + message otherwise. `loginId` must match the in-flight login (else it's stale/unknown).
+     */
+    submitCode(loginId: string, code: string): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    /** Abandon any in-flight login (e.g. the user cancels). */
+    cancel(): void;
+    private cancelIf;
+}
+/** Production wiring: spawn `claude <args>` with the server env (ANTHROPIC_API_KEY stripped → subscription
+ *  auth, mirroring the chat/usage spawns). stdin is piped so the code can be written for the login flow. */
+declare function createClaudeAuthService(opts: {
+    claudeBin: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+}): ClaudeAuthService;
+
+/**
+ * The LATEST published `claude` CLI version, for update-awareness: the UI compares a session's
+ * `claudeVersion` (what it spawned with) against this to show a subtle "update available" hint when a
+ * chat is running an older Claude than what's out.
+ *
+ * Source: the npm registry's dist-tag for `@anthropic-ai/claude-code` (the same release train as the
+ * native installer), fetched best-effort and TTL-cached so the rare /claude/version poll is cheap. Any
+ * failure (offline, timeout, registry hiccup) degrades to the last good value, or undefined — the UI
+ * simply hides the hint, never errors. The fetch is an INJECTABLE seam so the cache logic is unit-testable.
+ */
+declare const CLAUDE_LATEST_CACHE_MS: number;
+/** Resolve the latest version string (e.g. "2.1.195"). NEVER rejects — resolves undefined on any failure. */
+type FetchLatest = () => Promise<string | undefined>;
+interface ClaudeLatestDeps {
+    fetchLatest: FetchLatest;
+    now: () => number;
+    ttlMs?: number;
+}
+/** Pull `version` out of an npm dist-tag document (`{ "version": "2.1.195", … }`). */
+declare function parseNpmLatest(json: unknown): string | undefined;
+declare class ClaudeLatestService {
+    private readonly fetchLatest;
+    private readonly now;
+    private readonly ttlMs;
+    private cache?;
+    constructor(deps: ClaudeLatestDeps);
+    /** The latest version, TTL-cached. A failed refresh keeps the last good value (or undefined). */
+    getLatest(): Promise<string | undefined>;
+}
+/** The real fetch adapter: GET the npm dist-tag doc with a short timeout. Resolves undefined on any error. */
+declare function createClaudeLatestService(opts?: {
+    now?: () => number;
+    ttlMs?: number;
+}): ClaudeLatestService;
+
+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;
+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;
+}
+/** The tmux session name for a roamcode session id. Stable so attach/kill always target the same one. */
+declare function tmuxSessionName(id: string): string;
+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;
+}
+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;
+}
+
+type PaneStatus = "working" | "blocked" | "idle";
+/**
+ * The newest Claude Code MAJOR.MINOR the classifier's markers below were VERIFIED against on a live box.
+ * The whole classifier is tied to Claude Code's ENGLISH TUI strings — the load-bearing markers are:
+ *   - "Do you want to proceed" / "Would you like to proceed"   (blocked — permission/plan prompts)
+ *   - the gerund ellipsis "…" + "↓ <n>k tokens" live counter    (working — main spinner + live agents)
+ *   - a "…(<n>s"-style parenthesised spinner timer               (working — pre-token-flow window)
+ *   - "Waiting for … to finish" / "esc to interrupt"             (working)
+ * A NEWER claude may reword any of these and silently degrade every rail status to "idle", so boot logs a
+ * one-time warning (see start.ts) when the installed claude's MAJOR.MINOR exceeds this. Bump it after
+ * re-verifying the markers against a newer claude.
+ */
+declare const CLASSIFIER_TESTED_UP_TO = "2.1";
+/**
+ * True iff `current`'s MAJOR.MINOR is strictly NEWER than `testedUpTo`'s. Patch versions are ignored — a
+ * patch release doesn't reword the TUI. Unparseable input (either side) → false, so a weird version string
+ * can never produce a spurious warning. Pure.
+ */
+declare function isNewerMajorMinor(current: string, testedUpTo: string): boolean;
+/**
+ * The one-line boot warning when the RUNNING claude is newer than the classifier was verified against —
+ * or undefined when there is nothing to warn about (older/equal/unknown version). Pure so it's testable;
+ * start.ts logs it once via console.warn and NEVER throws (a version bump must not affect boot).
+ */
+declare function classifierVersionWarning(claudeVersion: string | undefined): string | undefined;
+/**
+ * Classify a session's live ACTIVITY from its RENDERED tmux pane (`capture-pane -p` — the CURRENT screen, not
+ * scrollback). UNIVERSAL: works for any running session regardless of how claude was spawned (no per-session
+ * hooks needed), and works while the browser is DETACHED (it reads the tmux session directly). Grounded in
+ * Claude Code's real output — see pane-status.test.ts for captured samples.
+ *
+ *   working → something is actively generating. The strongest tell is a LIVE token-flow counter "↓ 216.5k
+ *             tokens" — it appears on the MAIN spinner ("Schlepping… (1m 17s · ↓ 2.1k tokens)") AND on an
+ *             ACTIVE background agent ("⏺ general-purpose  Listing f… 24m 23s · ↓ 216.5k tokens"), and is GONE
+ *             the moment a turn finishes ("Baked for 23m 15s"). So a session whose MAIN loop is at the prompt
+ *             but has agents still developing in the background reads "working" — NOT idle (the user's
+ *             explicit correction). Also: a spinner's parenthesised timer, "Waiting for … to finish", or
+ *             "esc to interrupt".
+ *   blocked → claude is WAITING ON A DECISION FROM YOU: a permission prompt ("Do you want to proceed?"), a
+ *             plan-mode approval ("Would you like to proceed?"). This is the ONLY state that earns the loud
+ *             "needs you" — so it must stay RARE + real; that's why it's just the explicit-prompt phrasings.
+ *   idle    → none of the above: claude finished a turn and is sitting at an empty prompt with nothing running
+ *             and nothing to decide. A calm "your turn whenever" — NOT a loud alert.
+ *
+ * Order matters: blocked is checked first (a decision prompt overrides any stale spinner text), then working,
+ * else idle.
+ */
+declare function classifyPaneStatus(pane: string): PaneStatus;
+/** How capturePane locates a session's tmux pane. */
+interface CaptureOptions {
+    tmuxBin?: string;
+    socket: string;
+    sessionName: string;
+    timeoutMs?: number;
+}
+/**
+ * Capture a tmux session's CURRENT pane as plain text (`capture-pane -p`, no escape sequences). READ-ONLY —
+ * it never sends input or resizes, so it can NEVER disturb a live session. Best-effort: resolves "" on any
+ * error/timeout and never throws. Async (non-blocking) so the activity monitor doesn't stall the event loop.
+ */
+declare function capturePane(opts: CaptureOptions): Promise<string>;
+
+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;
+}
+/** Creates the only persistence object accepted by the exact-thread resolver. */
+declare function createCodexThreadPersistence(store: SessionStore, roamSessionId: string): CodexThreadPersistence;
+
+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 CodexThreadRpc {
+    request<T>(method: string, params: unknown, schema: ZodType<T>): Promise<T>;
+}
+interface CreateCodexThreadInventoryOptions {
+    readonly cwd: string;
+    readonly maxPages?: number;
+    readonly maxItems?: number;
+}
+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 function resetCodexThreadResolutionCoordinatorForTests(): void;
+/** Creates the bounded current-protocol `thread/list` reader used by resolver snapshots and polls. */
+declare function createCodexThreadInventory(rpc: CodexThreadRpc, options: CreateCodexThreadInventoryOptions): ReadCodexThreadInventory;
+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;
+}
+
+type DiagnosticIssue = "exit" | "malformed_json" | "notification_listener" | "spawn" | "stderr_limit" | "stdout_limit" | "transport_error" | "unknown_message" | "write_error";
+interface CodexMetadataDiagnostics {
+    readonly lastIssue?: DiagnosticIssue;
+    readonly stderrBytes: number;
+    readonly stderrTruncated: boolean;
+}
+interface CodexAppServerNotification {
+    readonly method: string;
+    readonly params?: unknown;
+}
+interface WritableTransport extends EventEmitter {
+    write(value: string | Uint8Array, callback?: (error?: Error | null) => void): boolean;
+    end(): void;
+}
+type ReadableTransport = EventEmitter;
+/** The intentionally small child-process surface used by the protocol client and its fake tests. */
+interface CodexAppServerTransport extends EventEmitter {
+    readonly stdin: WritableTransport;
+    readonly stdout: ReadableTransport;
+    readonly stderr: ReadableTransport;
+    kill(signal?: NodeJS.Signals): boolean | void;
+}
+type SpawnCodexAppServerTransport = (command: string, args: readonly string[], options?: {
+    readonly env?: NodeJS.ProcessEnv;
+}) => CodexAppServerTransport;
+interface CodexAppServerClientOptions {
+    readonly codexBin?: string;
+    /** Selects one validated `$CODEX_HOME/<name>.config.toml` layer before app-server starts. */
+    readonly profile?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly spawnTransport?: SpawnCodexAppServerTransport;
+    readonly timeoutMs?: number;
+    readonly maxStdoutLineBytes?: number;
+    readonly maxStdoutBufferBytes?: number;
+    readonly maxStderrBytes?: number;
+}
+/**
+ * Bounded JSON-lines client for the auxiliary Codex app-server metadata channel.
+ * It never participates in terminal streaming and deliberately knows no method-specific result schemas.
+ */
+declare class CodexAppServerClient {
+    readonly limits: {
+        readonly timeoutMs: number;
+        readonly maxStdoutLineBytes: number;
+        readonly maxStdoutBufferBytes: number;
+        readonly maxStderrBytes: number;
+    };
+    private readonly codexBin;
+    private readonly profile?;
+    private readonly env?;
+    private readonly spawnTransport;
+    private readonly notificationListeners;
+    private active?;
+    private startPromise?;
+    private stopPromise?;
+    private nextRequestId;
+    private nextGeneration;
+    private lastDiagnostics;
+    constructor(options?: CodexAppServerClientOptions);
+    get diagnostics(): CodexMetadataDiagnostics;
+    start(): Promise<void>;
+    request<T>(method: string, params: unknown, schema: ZodType<T>): Promise<T>;
+    onNotification(listener: (notification: CodexAppServerNotification) => void): () => void;
+    stop(): Promise<void>;
+    private createGeneration;
+    private installListeners;
+    private sendRequest;
+    private writeFrame;
+    private flushWrites;
+    private onStdout;
+    private onMessage;
+    private resolveResponse;
+    private rejectResponse;
+    private onStderr;
+    private failGeneration;
+    private removeListeners;
+    private recordIssue;
+}
+
+interface CodexProfileClientLifecycle {
+    readConfig<T>(profile: string, codexHome: string, cwd: string, schema: ZodType<T>): Promise<T>;
+}
+interface CreateCodexProfileClientLifecycleOptions {
+    readonly codexBin: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly spawnTransport?: SpawnCodexAppServerTransport;
+    readonly timeoutMs?: number;
+}
+/** Required selected-profile lifecycle. It owns Task 6 client construction, canonical env, start, and stop. */
+declare function createCodexProfileClientLifecycle(options: CreateCodexProfileClientLifecycleOptions): CodexProfileClientLifecycle;
+declare function isCodexProfileClientLifecycle(value: unknown): value is CodexProfileClientLifecycle;
+
+declare const CODEX_METADATA_ERROR_CODE: "CODEX_METADATA_UNAVAILABLE";
+interface CodexMetadataRpc {
+    request<T>(method: string, params: unknown, schema: ZodType<T>): Promise<T>;
+    onNotification(listener: (notification: {
+        method: string;
+        params?: unknown;
+    }) => void): () => void;
+    start?(): Promise<void>;
+    stop?(): Promise<void>;
+}
+interface CodexAccount {
+    readonly authenticated: boolean;
+    readonly authMethod: "none" | "apiKey" | "chatgpt";
+    readonly plan?: string;
+}
+interface CodexModel {
+    readonly value: string;
+    readonly id: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly isDefault: boolean;
+    readonly reasoningOptions: ReadonlyArray<{
+        value: string;
+        description: string;
+        isDefault: boolean;
+    }>;
+    readonly supportedReasoningEfforts: string[];
+    readonly defaultReasoningEffort: string;
+}
+interface CodexUsageBar {
+    readonly id: string;
+    readonly label: string;
+    readonly percent: number;
+    readonly resetsAt?: number;
+    readonly windowDurationMs?: number;
+}
+interface CodexUsage {
+    readonly bars: CodexUsageBar[];
+    readonly credits?: {
+        readonly hasCredits: boolean;
+        readonly unlimited: boolean;
+        readonly balance?: string;
+        readonly resetCreditsAvailable?: number;
+    };
+    readonly fetchedAt: number;
+}
+type CodexLoginCompletion = {
+    readonly status: "completed";
+} | {
+    readonly status: "failed";
+} | {
+    readonly status: "canceled";
+} | {
+    readonly status: "expired";
+};
+type CodexLoginStatus = CodexLoginCompletion | {
+    readonly status: "pending";
+} | {
+    readonly status: "notFound";
+};
+interface CodexDeviceLogin {
+    readonly loginId: string;
+    readonly userCode: string;
+    readonly verificationUrl: string;
+    readonly expiresAt: number;
+    readonly completion: Promise<CodexLoginCompletion>;
+}
+interface CodexMetadataServiceOptions {
+    readonly now?: () => number;
+    readonly loginTtlMs?: number;
+    readonly modelCacheTtlMs?: number;
+    readonly capabilityCacheTtlMs?: number;
+    readonly capabilityTimeoutMs?: number;
+    readonly maxModelPages?: number;
+    readonly maxModelItems?: number;
+    readonly codexHome?: string;
+    readonly profileClient?: CodexProfileClientLifecycle;
+}
+declare class CodexMetadataService {
+    private readonly rpc;
+    private readonly now;
+    private readonly loginTtlMs;
+    private readonly modelCacheTtlMs;
+    private readonly capabilityCacheTtlMs;
+    private readonly capabilityTimeoutMs;
+    private readonly maxModelPages;
+    private readonly maxModelItems;
+    private readonly codexHome?;
+    private readonly profileClient?;
+    private readonly activeLogins;
+    private readonly earlyLoginCompletions;
+    private readonly retiredLoginIds;
+    private readonly loginOutcomes;
+    private activeStartGeneration?;
+    private nextStartGeneration;
+    private startingLogin?;
+    private modelCache?;
+    private modelRequest?;
+    private lastUsageDiagnostic?;
+    private lastCapabilityDiagnostic?;
+    private capabilityCache?;
+    private capabilityRequest?;
+    private readonly unsubscribeNotification;
+    private disposed;
+    constructor(rpc: CodexMetadataRpc, options?: CodexMetadataServiceOptions);
+    get diagnostics(): {
+        readonly usage?: {
+            readonly code: typeof CODEX_METADATA_ERROR_CODE;
+            readonly message: string;
+        };
+        readonly capabilities?: {
+            readonly code: typeof CODEX_METADATA_ERROR_CODE;
+            readonly message: string;
+        };
+    };
+    probeCapabilities(cwd: string, readThreadInventory: ReadCodexThreadInventory): Promise<boolean>;
+    private loadCapabilities;
+    getAccount(): Promise<CodexAccount>;
+    startDeviceLogin(): Promise<CodexDeviceLogin>;
+    cancelLogin(loginId: string): Promise<{
+        status: "canceled" | "notFound";
+    }>;
+    getLoginStatus(loginId: string): CodexLoginStatus;
+    dispose(): void;
+    getModels(force?: boolean): Promise<CodexModel[]>;
+    validateModelSelection(model: string, reasoningEffort?: string): Promise<void>;
+    getUsage(): Promise<CodexUsage | null>;
+    listProfiles(): Promise<string[]>;
+    readonly validateProfile: (profile: string, cwd: string) => Promise<CodexProfileLaunchProof>;
+    private readProfileConfig;
+    private installLogin;
+    private onNotification;
+    private settleLogin;
+    private finishStartGeneration;
+    private retireLoginId;
+    private pruneEarlyLoginCompletions;
+    private pruneRetiredLoginIds;
+    private recordLoginOutcome;
+    private pruneLoginOutcomes;
+    private expireLogin;
+    private loadModels;
+    private appendSnapshotBars;
+}
+
+interface ClaudeModelCatalogItem {
+    value: string;
+    displayName: string;
+    description?: string;
+    supportedEffortLevels: string[];
+    isDefault: boolean;
+}
+interface ClaudeMetadataRunner {
+    run(): Promise<unknown>;
+    /** Claude 2.1.207+ no longer includes models in initialize; `/model` is the catalog fallback. */
+    runModelList?(): Promise<unknown>;
+    dispose?(): void | Promise<void>;
+}
+interface ClaudeMetadataChildProcess {
+    readonly stdin: {
+        end(chunk: string): unknown;
+        on(event: "error", listener: (error: Error) => void): unknown;
+        off(event: "error", listener: (error: Error) => void): unknown;
+    };
+    readonly stdout: NodeJS.ReadableStream;
+    readonly stderr: NodeJS.ReadableStream;
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+    off(event: "error", listener: (error: Error) => void): this;
+    off(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+    kill(): boolean;
+}
+type ClaudeMetadataSpawnProcess = (command: string, args: readonly string[], options: SpawnOptions) => ClaudeMetadataChildProcess;
+interface CreateClaudeMetadataRunnerOptions {
+    claudeBin: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    /** Process boundary injected by lifecycle tests. */
+    spawnProcess?: ClaudeMetadataSpawnProcess;
+    /** `/model` process boundary injected by fallback tests. */
+    modelListRun?: () => Promise<unknown>;
+}
+declare class ClaudeMetadataService {
+    private readonly runner;
+    private readonly now;
+    private readonly ttlMs;
+    private cache?;
+    private inFlight?;
+    private disposed;
+    constructor(runner: ClaudeMetadataRunner, options?: {
+        now?: () => number;
+        ttlMs?: number;
+    });
+    getModels(force?: boolean): Promise<ClaudeModelCatalogItem[]>;
+    validateModelSelection(model: string, effort?: string): Promise<void>;
+    dispose(): void | Promise<void>;
+    private loadModels;
+}
+declare function createClaudeMetadataRunner(options: CreateClaudeMetadataRunnerOptions): ClaudeMetadataRunner;
+
+type CodexInstallProvenance = "npm" | "chatgpt" | "homebrew" | "unknown";
+interface BoundedVersionRunOptions {
+    readonly timeoutMs: number;
+    readonly maxOutputBytes: number;
+}
+interface BoundedLatestFetchOptions {
+    readonly timeoutMs: number;
+    readonly maxResponseBytes: number;
+}
+type RunCodexVersion = (args: readonly string[], options: BoundedVersionRunOptions) => Promise<{
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}>;
+type DetectCodexProvenance = () => CodexInstallProvenance | Promise<CodexInstallProvenance>;
+type FetchNpmLatest = (packageName: string, options: BoundedLatestFetchOptions) => Promise<string>;
+interface CodexLatestServiceOptions {
+    readonly runVersion: RunCodexVersion;
+    readonly detectProvenance: DetectCodexProvenance;
+    readonly fetchNpmLatest: FetchNpmLatest;
+    readonly now?: () => number;
+    readonly cacheTtlMs?: number;
+}
+interface CodexVersionInfo {
+    readonly installed: string;
+    readonly provenance: CodexInstallProvenance;
+    readonly latest?: string;
+    readonly updateAvailable?: boolean;
+    readonly updateHint?: string;
+}
+declare function parseCodexVersion(stdout: string): string;
+declare class CodexLatestService {
+    private readonly options;
+    private readonly now;
+    private readonly cacheTtlMs;
+    private cache?;
+    private inFlight?;
+    constructor(options: CodexLatestServiceOptions);
+    getVersion(force?: boolean): Promise<CodexVersionInfo>;
+    private loadVersion;
+}
+
+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;
+}
+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 createServer(config: ServerRuntimeConfig, deps?: CreateServerDeps): CreateServerResult;
+
+/**
+ * Server-side mirror of the web SW's `apiNavigationDenylist` (packages/web/src/pwa/sw-exclusions.ts),
+ * EXTENDED with /health, /push and the /ws suffix. A request whose path matches one of these is a
+ * live API/WS/health/push route — the SPA navigation fallback must NOT serve index.html for it (it
+ * must hit the real handler), and the auth gate must NOT treat it as a public static asset.
+ *
+ * SYNC INVARIANT: this denylist (and `isPublicForRequest` below) decides which requests skip the
+ * token gate, while Fastify's find-my-way router decides which handler a request reaches. The two
+ * MUST agree on path normalization, or a request can look public to the gate yet reach a protected
+ * handler (an auth bypass). We gate on the DECODED path (`pathForGate`) to match the router's
+ * percent-decoding, and we reject encoded separators (`hasEncodedSep`). If Fastify is ever
+ * configured with `caseSensitive:false` or `ignoreDuplicateSlashes:true`, this gate must apply the
+ * SAME case/slash normalization first, or those options will silently reopen the bypass.
+ */
+declare const API_PATH_DENYLIST: RegExp[];
+/**
+ * The EXPLICIT public-shell allowlist — the only paths the auth gate lets a REGISTERED route serve
+ * without a token. It must cover exactly what an unauthenticated PWA boot needs (the login screen has to
+ * render before a token exists): the root shell, the Vite asset dir, and the top-level bundle files
+ * (index.html, sw.js, manifest.webmanifest, icons — matched by extension so a new icon the web build adds
+ * doesn't need a server change). Everything else — including any FUTURE route nobody remembered to gate —
+ * is token-gated by default (see the transport preHandler).
+ *
+ * SAFE because only static handlers live at these shapes: every API route is extensionless and no API
+ * route sits at `/` or under `/assets/`. Keep it that way — an API route named like a top-level static
+ * file (e.g. `/report.json`) would be silently public.
+ */
+declare const SHELL_PATH_ALLOWLIST: RegExp[];
+/** True for the static PWA shell paths above (the auth gate's explicit allowlist). */
+declare function isShellPath(path: string): boolean;
+/**
+ * Normalize a raw request URL to the path the FASTIFY ROUTER will route, for the auth gate.
+ * find-my-way routes the percent-DECODED path, so we must gate on the decoded path too — otherwise
+ * `GET /%73essions` (`%73`=`s`) looks public to a raw-path gate but routes to `/sessions`.
+ * A malformed escape (decodeURIComponent throws) falls back to the raw path (still gated by the
+ * caller's encoded-separator check), never crashing the gate.
+ */
+declare function pathForGate(rawUrl: string): string;
+/**
+ * True if the RAW (pre-decode) path carries an encoded slash or backslash (`%2f`/`%2F`/`%5c`/`%5C`).
+ * find-my-way's handling of encoded slashes can desync from a single `decodeURIComponent`, and any
+ * request that needs an encoded separator to look public is inherently suspicious — so we treat such
+ * requests as NON-public (gated) regardless of what they decode to.
+ */
+declare function hasEncodedSep(rawUrl: string): boolean;
+/**
+ * The auth-boundary decision for a real request: a request is public (skips the token gate / may get
+ * the SPA shell) IFF it has no encoded separator AND its decoded path is a public static/shell path.
+ * Both the preHandler bypass (transport.ts) and the SPA `setNotFoundHandler` MUST use this, so the
+ * gate and the router agree on what is reachable.
+ */
+declare function isPublicForRequest(rawUrl: string): boolean;
+/**
+ * True for the PUBLIC static shell (HTML/JS/CSS/icons/manifest/sw + SPA navigations) — served WITHOUT
+ * a token so the login screen can load and THEN authenticate. A path is public iff it is on the shell
+ * allowlist, OR it is an extensionless NAVIGATION path (an SPA client route like `/login` gets
+ * index.html on a hard refresh) outside the reserved API namespace. (The served bundle carries no
+ * secret: the token lives only in the browser localStorage.)
+ *
+ * NOTE this predicate alone is NOT the auth boundary for routes: the transport preHandler is
+ * DEFAULT-DENY — it only honors the navigation half of this when the request matched NO registered
+ * route (fastify's `is404`), so a real handler can never hide behind an extensionless path. The
+ * navigation half here also drives the SPA fallback in {@link registerStatic}'s notFound handler.
+ *
+ * INVARIANT: a built shell asset must NEVER live at a path starting `/sessions`, `/fs`, `/ws`,
+ * `/health`, or `/push`. This holds for the Vite build (assets are emitted under `/assets/`, plus
+ * root `/index.html`, `/icon-*.svg`, `/manifest.webmanifest`, `/sw.js`) — none collide with the
+ * denylist. If a future asset were ever emitted under one of those prefixes, this default-deny would
+ * wrongly 401 a real asset to an unauthenticated shell load (the shell would fail to boot). Keep the
+ * Vite output prefixes clear of the denylist, or special-case the asset path here.
+ */
+declare function isPublicPath(path: string): boolean;
+/**
+ * True if the path looks like a request for a static FILE — it lives under `/assets/` or its last
+ * segment has an extension (e.g. `.js`/`.css`/`.png`/`.svg`). A file request that reaches the
+ * notFound handler means the file does NOT exist on disk, so it must 404 — it must NOT fall back to
+ * index.html. Serving the HTML shell for a missing `.js` makes the browser block the module script
+ * (MIME mismatch → blank page) and can POISON a service-worker precache (HTML cached as the JS
+ * entry). Only extensionless navigation paths (client routes like `/`, `/login`) get the SPA shell.
+ *
+ * Operational note: `@fastify/static` with `wildcard:false` globs the dist and registers one route
+ * per file AT STARTUP, so after rebuilding the web bundle (new content-hashed filenames) the server
+ * must be RESTARTED for the new assets to get routes — otherwise they reach this handler and (now)
+ * correctly 404 instead of silently serving the shell.
+ */
+declare function looksLikeAssetRequest(path: string): boolean;
+interface RegisterStaticOptions {
+    /** Absolute path to the built PWA (packages/web/dist). */
+    webDir: string;
+}
+/**
+ * Serve the built PWA at `/` with an SPA fallback: a GET NAVIGATION (extensionless, public, non-API)
+ * that no static file matched returns index.html, so client routes (e.g. /login) work on a hard
+ * refresh. A request that looks like a missing FILE (`/assets/*`, or any `*.ext`) is served LIVE from
+ * disk when the file exists under webDir but @fastify/static's startup glob missed it (a build that
+ * landed after this server started — an OTA window / manual rebuild); otherwise it returns 404, never
+ * the shell — so a missing asset fails loudly instead of poisoning a browser/SW cache with HTML. An
+ * unknown /sessions/... still 404/401s from the real handlers / the gate.
+ */
+declare function registerStatic(app: FastifyInstance, opts: RegisterStaticOptions): void;
+
+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>;
+/**
+ * STARTUP PREFLIGHT (#7): format a prominent, actionable boot warning when `claude --version` couldn't
+ * run. The server still boots (sessions just won't start until the operator fixes it) — this is purely
+ * 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.
+ */
+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.
+ */
+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;
+}>;
+
+/** Terminal mode needs BOTH a tmux binary and a loadable node-pty. Injectable for tests. */
+declare function detectTerminalSupport(deps?: {
+    hasTmux?: () => boolean;
+    hasPty?: () => boolean;
+}): boolean;
+
+/** 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). */
+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.
+ */
+declare function listTmuxSessions(run?: () => TmuxProbe): string[] | undefined;
+
+declare function buildServicePath(nodePath: string, home: string): string;
+interface RenderLaunchdOptions {
+    label: string;
+    nodePath?: string;
+    cliPath?: string;
+    executablePath?: string;
+    dataDir: string;
+    installRoot?: string;
+    servicePath?: string;
+}
+declare function renderLaunchdPlist(opts: RenderLaunchdOptions): string;
+interface RenderSystemdOptions {
+    nodePath?: string;
+    cliPath?: string;
+    executablePath?: string;
+    dataDir: string;
+    installRoot?: string;
+    servicePath?: string;
+}
+declare function renderSystemdUnit(opts: RenderSystemdOptions): string;
+interface ServiceRecord {
+    manager: "launchd" | "systemd";
+    label: string;
+    path: string;
+    launcherPath?: string;
+    installRoot?: string;
+}
+interface InstallServiceContext {
+    nodePath: string;
+    cliPath?: string;
+    executablePath?: string;
+    dataDir: string;
+    installRoot?: string;
+    home?: string;
+    os?: NodeJS.Platform;
+    label?: string;
+}
+interface InstallServiceResult {
+    path: string;
+    instructions: string;
+    record: ServiceRecord;
+}
+declare function installService(ctx: InstallServiceContext): InstallServiceResult;
+declare function readServiceRecord(dataDir: string): ServiceRecord | undefined;
+declare function migrateServiceToLauncher(opts: {
+    dataDir: string;
+    installRoot: string;
+    launcherPath: string;
+    nodePath: string;
+}): ServiceRecord | undefined;
+declare function restartService(record: ServiceRecord): {
+    ok: boolean;
+    error?: string;
+};
+/** Enable the per-user service and start it immediately. This is only called by the explicit
+ * `roamcode install` command; OTA updates use restartService and never change enablement. */
+declare function enableService(record: ServiceRecord): {
+    ok: boolean;
+    error?: string;
+};
+
+declare class ProviderOptionsError extends ProviderError {
+    constructor(message: string);
+}
+declare function parseProviderOptions(provider: ProviderId, raw: unknown): ProviderSessionOptions;
+declare function parseLegacyClaudeArgs(args: readonly string[]): ClaudeSessionOptions;
+
+interface CreateClaudeProviderOptions {
+    claudeBin: string;
+    env?: NodeJS.ProcessEnv;
+    attach?: AttachSpawnOptions;
+    getAttach?: () => AttachSpawnOptions | undefined;
+    probe?: () => Promise<ProviderAvailability>;
+}
+declare function createClaudeProvider(options: CreateClaudeProviderOptions): AgentProvider;
+
+interface CreateCodexProviderOptions {
+    codexBin: string;
+    env?: NodeJS.ProcessEnv;
+    attach?: AttachSpawnOptions;
+    getAttach?: () => AttachSpawnOptions | undefined;
+    probe?: () => Promise<ProviderAvailability>;
+    /** Task 7 supplies the effective-provider capability check; this adapter never reads profile files. */
+    validateProfile?(profile: string, cwd: string): CodexProfileLaunchProof | Promise<CodexProfileLaunchProof>;
+}
+type CodexAttachContext = Pick<AttachSpawnOptions, "baseUrl" | "token" | "mcpScriptPath">;
+declare function buildCodexArgs(context: ProviderProcessContext, attach?: CodexAttachContext): string[];
+declare function createCodexProvider(options: CreateCodexProviderOptions): AgentProvider;
+
+declare const CODEX_OSC_MAX_CARRY: number;
+declare const CODEX_CLASSIFIER_TESTED_UP_TO = "0.144";
+interface CodexOscParser extends ProviderRuntimeSignalParser {
+    readonly bufferedLength: number;
+}
+declare function createCodexOscParser(): CodexOscParser;
+declare function parseCodexOscNotifications(input: string): ProviderRuntimeSignal[];
+declare function classifyCodexPane(pane: string): PaneStatus;
+declare function codexClassifierVersionWarning(codexVersion: string | undefined): string | undefined;
+
+declare const SERVER_PACKAGE = "@roamcode.ai/server";
+
+export { API_PATH_DENYLIST, type AgentProvider, type AttachSpawnOptions, type AuthCheckResult, AuthGate, type AuthGateOptions, type Bar, CHECK_CACHE_MS, CLASSIFIER_TESTED_UP_TO, CLAUDE_LATEST_CACHE_MS, CLAUDE_VERSION_CACHE_MS, CLAUDE_VERSION_TIMEOUT_MS, CODEX_CLASSIFIER_TESTED_UP_TO, CODEX_OSC_MAX_CARRY, type CaptureOptions, type ChangelogEntry, type ClaudeAuthDeps, ClaudeAuthService, type ClaudeAuthStatus, type ClaudeAvailability, type ClaudeLatestDeps, ClaudeLatestService, type ClaudeMetadataRunner, ClaudeMetadataService, type ClaudeModelCatalogItem, type ClaudeSessionOptions, type ClaudeVersionProbe, type CodexAccount, CodexAppServerClient, type CodexAppServerClientOptions, type CodexDeviceLogin, type CodexInstallProvenance, CodexLatestService, type CodexLoginCompletion, type CodexLoginStatus, type CodexMetadataDiagnostics, type CodexMetadataRpc, CodexMetadataService, type CodexMetadataServiceOptions, type CodexModel, type CodexOscParser, type CodexProfileClientLifecycle, type CodexSessionOptions, type CodexSpawnLease, type CodexThreadInventoryEntry, type CodexThreadPersistence, CodexThreadResolver, type CodexThreadResolverOptions, type CodexUsage, type CodexVersionInfo, type CreateClaudeProviderOptions, type CreateCodexProfileClientLifecycleOptions, type CreateCodexProviderOptions, type CreatePushDispatcherDeps, type CreateServerDeps, type CreateServerResult, type CreateWebPushSendOptions, type DirEntry, type DirListing, type DirSearchResult, FETCH_TIMEOUT_MS, type FetchLatest, type FetchManifest, type FetchReleases, FsError, type FsErrorCode, FsService, type FsServiceOptions, type GitHubRelease, type HooksSettingsDocument, type IPty, type InstallServiceContext, type InstallServiceResult, type InstallationKind, type LaunchIntent, type ManagedInstallOptions, type ManagedInstallResult, type ManagedInstallStatus, type ManagedPaths, type McpConfigDocument, type ModelWeekBar, type OpenPushStoreOptions, type OpenSessionStoreOptions, type OriginCheckOptions, type PaneStatus, type ProcessSpec, type ProviderAvailability, ProviderError, type ProviderId, ProviderOptionsError, type ProviderProcessContext, ProviderRegistry, type ProviderRuntimeSignal, type ProviderRuntimeSignalParser, type ProviderSessionOptions, type PtySpawn, type PushDispatcher, type PushEvent, type PushEventKind, type PushPayload, type PushRecipient, type PushSendFn, type PushStore, type PushSubscriptionRecord, RUNNING_BUILD, RUNNING_VERSION, type RateLimitDecision, RateLimiter, type RateLimiterOptions, type RegisterStaticOptions, type ReleaseRecord, type RenderLaunchdOptions, type RenderSystemdOptions, type ResolveAccessTokenOptions, type ResolveCodexThreadOptions, type ResolveVapidKeysOptions, type RunClaudeVersion, type RunUsage, SEARCH_MAX_DEPTH, SEARCH_MAX_DIRS, SEARCH_MAX_RESULTS, SERVER_PACKAGE, SHELL_PATH_ALLOWLIST, type ServerConfig, type ServerRuntimeConfig, type ServiceRecord, type SessionDefaults, SessionDefaultsConflictError, type SessionStore, type StoreMode, type StoredSession, type StoredSessionDefaults, type StoredStatus, TerminalManager, type TerminalManagerDeps, type TerminalMeta, TerminalProcess, type TerminalProcessOptions, type TerminalSub, USAGE_CACHE_MS, USAGE_TIMEOUT_MS, type UpdateAction, type UpdateState, type UpdateStatus, Updater, type UpdaterDeps, type UpdaterFs, type UsageInfo, UsageService, type UsageServiceDeps, type VapidKeys, type VersionInfo, WS_TICKET_TTL_MS, WsTicketStore, type WsTicketStoreOptions, assertConfigAllowsStart, buildCodexArgs, buildHooksSettingsDocument, buildMcpConfigDocument, buildPushPayload, buildServicePath, capturePane, classifierVersionWarning, classifyCodexPane, classifyPaneStatus, claudePreflightWarning, codexClassifierVersionWarning, compareVersions, computeBuildDrift, computeInstallDrift, createClaudeAuthService, createClaudeLatestService, createClaudeMetadataRunner, createClaudeProvider, createClaudeVersionProbe, createCodexOscParser, createCodexProfileClientLifecycle, createCodexProvider, createCodexThreadInventory, createCodexThreadPersistence, createPushDispatcher, createServer, createUpdater, createUsageRunner, createUsageService, createWebPushSend, defaultFetchManifest, defaultFetchReleases, defaultRunClaudeVersion, defaultUpdaterFs, detectTerminalSupport, enableService, ensureDataDir, extractBearerToken, extractLoginUrl, generateAccessToken, hasEncodedSep, hookAuthFileContent, hookAuthPathFor, hooksSettingsPathFor, installManagedRelease, installService, isCodexProfileClientLifecycle, isLoopbackAddress, isNewerMajorMinor, isOriginAllowed, isPublicForRequest, isPublicPath, isShellPath, isStableVersion, listTmuxSessions, loadConfig, loadServerConfig, looksLikeAssetRequest, managedPaths, mcpConfigPathFor, migrateServiceToLauncher, normalizeOrigin, normalizeProviderAvailability, normalizeRelease, normalizeSessionDefaults, openPushStore, openSessionStore, parseAllowedOrigins, parseAuthStatus, parseClaudeVersion, parseCodexOscNotifications, parseCodexVersion, parseLegacyClaudeArgs, parseNpmLatest, parseProviderOptions, parseReleaseNotes, parseUsage, pathForGate, persistAccessToken, providerPreflightWarning, readActiveVersion, readPreviousVersion, readServiceRecord, registerStatic, relativeWhen, renderLaunchdPlist, renderManagedLauncher, renderSystemdUnit, resetCodexThreadResolutionCoordinatorForTests, resolveAccessToken, resolveDataDir, resolveInstallRoot, resolveVapidKeys, restartService, runClaudePreflight, runProviderPreflight, stableReleases, startServer, tmuxSessionName, writeManagedLauncher };