@particle-academy/fancy-term-host 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,777 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Ports — the injected interfaces that keep the terminal CORE runtime-agnostic.
+ *
+ * The terminal core (manager / sessions / shells / host-lifecycle / host-client)
+ * must never import `electron` or `../db`. Instead it receives these small ports
+ * and EMITS events for the things that used to be direct DB writes. Genie's
+ * adapter (genie-adapter.ts + ipc.ts) is the ONE place that builds the Electron /
+ * SQLite implementations and subscribes to the events to persist + broadcast.
+ *
+ * This is Phase 1 of the @particle-academy/fancy-term-host extraction (see
+ * .ai/_discovery/fancy-term-host-extraction.md §3): inverting the coupling so the
+ * core can be lifted into a package near-mechanically. The shapes here match the
+ * brief's §3 interfaces verbatim.
+ */
+/**
+ * Read-only settings access. Replaces the core's old `getAllSettings()` reach
+ * into `../db`. The adapter implements `{ get: k => getAllSettings()[k] }`.
+ */
+interface SettingsProvider {
+    get(key: string): string | undefined;
+}
+/**
+ * At-rest cipher for snapshot bytes (T1). The adapter wraps Electron
+ * `safeStorage`; a plain-node consumer could pass a passthrough or libsodium
+ * implementation. `isAvailable()` mirrors `safeStorage.isEncryptionAvailable()`
+ * so the core can still take the plaintext-magic fallback when encryption is
+ * unavailable, exactly as before.
+ */
+interface Encryptor {
+    isAvailable(): boolean;
+    encrypt(b: Buffer): Buffer;
+    decrypt(b: Buffer): Buffer;
+}
+/**
+ * Everything the snapshot store (T1) needs that used to come from `electron`:
+ * the base directory (was `app.getPath('userData')`) and the cipher (was
+ * `safeStorage`). The store appends `/sessions` under `baseDir` itself, matching
+ * the historical on-disk path.
+ */
+interface SnapshotStoreConfig {
+    baseDir: string;
+    encryptor: Encryptor;
+}
+/**
+ * The detached-host spawn surface (T3). The connect-or-spawn-or-fallback LOGIC
+ * is core; only these three OS/Electron-specific operations are injected:
+ *   - resolveHostScript(): dev vs asar.unpacked path resolution.
+ *   - spawnDetached(): the ABI-correct exec (Electron: execPath +
+ *     ELECTRON_RUN_AS_NODE), detached + unref.
+ *   - userDataDir(): the directory pidfile/socket live under (was
+ *     app.getPath('userData')).
+ */
+interface HostSpawner {
+    resolveHostScript(): string | null;
+    spawnDetached(scriptPath: string, env: Record<string, string>): void;
+    userDataDir(): string;
+}
+
+/**
+ * Shared terminal-subsystem types.
+ *
+ * Lifted out of manager.ts so both the in-process manager and the Tier 3
+ * HostClient (which proxies the same shapes over a socket) can reference them
+ * without a circular import through the PtyBackend interface.
+ */
+interface CreateTerminalOpts {
+    /** Stable id chosen by the renderer (ulid). The manager uses it as the key. */
+    id: string;
+    /** Working directory for the spawned shell. */
+    cwd: string;
+    /** Shell executable. Defaults to the user's preferred login shell per platform. */
+    shell?: string;
+    /** Extra args for the shell. */
+    args?: string[];
+    /** Initial cols × rows. Renderer should send a `resize` immediately after mount. */
+    cols?: number;
+    rows?: number;
+    /** Extra env overrides. Merged on top of process.env. */
+    env?: Record<string, string>;
+}
+interface TerminalInfo {
+    id: string;
+    pid: number;
+    shell: string;
+}
+interface AttachResult extends TerminalInfo {
+    /** True when an existing pty was returned (caller is "joining"). */
+    existing: boolean;
+    /** Bounded scrollback so a late-joining window can replay history. */
+    scrollback: string;
+    /**
+     * A previous-session snapshot to replay, present ONLY on a COLD spawn that
+     * found a snapshot on disk. On a warm reattach this is omitted — the live
+     * scrollback already covers the history. The renderer frames it as
+     * "— previous session —" then resets before the fresh shell.
+     */
+    snapshot?: {
+        serialized: string;
+        savedAt: number;
+    };
+}
+
+/**
+ * PtyBackend — the abstraction the IPC layer (main/terminal/ipc.ts), Tier 1
+ * (snapshots) and Tier 2 (retained set) talk to, instead of talking to a
+ * concrete pty pool directly.
+ *
+ * Two implementations:
+ *
+ *   • InProcessBackend (the TerminalManager singleton) — node-pty instances live
+ *     IN the Electron main process. This is today's behaviour and the T1/T2
+ *     floor: snapshots survive a full quit, retained ptys survive a window
+ *     detach (but die on a real quit, degrading to T1 snapshots).
+ *
+ *   • HostClient (Tier 3) — node-pty instances live in a DETACHED headless
+ *     pty-host process. The backend proxies every call over a local socket; the
+ *     ptys (and the host's own scrollback ring buffer) SURVIVE A FULL QUIT of
+ *     the Electron app, so reopening reattaches to the still-running shells.
+ *
+ * ipc.ts is oblivious to which one it holds: same method names, same shapes,
+ * same data/exit event subscription. The active backend is chosen once at
+ * startup (selectBackend, see manager.ts) and swapped behind this interface.
+ *
+ * The data/exit subscription mirrors EventEmitter semantics so the InProcess
+ * backend can BE an EventEmitter and satisfy this for free, while HostClient
+ * fans host-pushed messages out to the same callback shape.
+ */
+interface PtyBackend {
+    /** Spawn (or rejoin an existing) pty for opts.id. */
+    create(opts: CreateTerminalOpts): AttachResult;
+    write(id: string, data: string): boolean;
+    resize(id: string, cols: number, rows: number): boolean;
+    /** Explicit kill (user delete). Clears retained flag + scrollback. */
+    kill(id: string): boolean;
+    /** Tear down every pty. Called on a real quit for the in-process backend;
+     *  a NO-OP for the host client (the whole point of T3 is they survive). */
+    killAll(): void;
+    list(): TerminalInfo[];
+    isLive(id: string): boolean;
+    setRetained(id: string, retained: boolean): void;
+    isRetained(id: string): boolean;
+    retainedCount(): number;
+    retainedIds(): string[];
+    getScrollback(id: string): string | undefined;
+    /** Subscribe to pushed pty output. */
+    on(event: 'data', listener: (id: string, data: string) => void): this;
+    /** Subscribe to pty exit. */
+    on(event: 'exit', listener: (id: string, payload: {
+        exitCode: number;
+        signal?: number;
+    }) => void): this;
+    /**
+     * Subscribe to live-cwd changes learned from OSC-7 (debounced). Replaces the
+     * core's old direct `updateTerminalSpec({ live_cwd })` write — the adapter
+     * subscribes here and persists. The in-process backend emits this; the host
+     * client simply never fires it (the detached host tracks cwd on its own side
+     * and the client doesn't observe OSC-7), so a no-op subscription is harmless.
+     */
+    on(event: 'cwd', listener: (id: string, cwd: string) => void): this;
+}
+/**
+ * The typed core event surface (brief §3). The in-process backend EMITS these;
+ * Genie's adapter SUBSCRIBES and persists/broadcasts:
+ *   - 'data'        (id, data)                 — pushed pty output            (unchanged)
+ *   - 'exit'        (id, { exitCode, signal }) — pty exit                     (unchanged)
+ *   - 'cwd'         (id, cwd)                  — was updateTerminalSpec({live_cwd})
+ *   - 'snapshot'    (id, bytes, at)            — was the snapshot-pointer write in ipc
+ *   - 'host-status' (status)                   — was the BrowserWindow fallback toast
+ *
+ * `snapshot` is emitted by the snapshot persistence path and `host-status` by
+ * the host lifecycle; both are surfaced here as the contract a packaged core
+ * exposes. In Genie's Phase-1 adapter the snapshot write + toast broadcast still
+ * originate in the adapter (ipc.ts / the injected host-status sink), so these two
+ * are documented rather than carried on PtyBackend itself.
+ */
+interface HostStatus {
+    message: string;
+    level: 'info' | 'warn';
+}
+
+interface SnapshotRead {
+    serialized: string;
+    /** Epoch ms the file was last written (from its mtime). */
+    savedAt: number;
+}
+/**
+ * The snapshot persistence surface (T1). Returned by createSnapshotStore so the
+ * core can read/write/delete snapshots without knowing where the bytes live or
+ * how they're encrypted.
+ */
+interface SnapshotStore {
+    /**
+     * Persist a snapshot for `id`. Returns the on-disk byte size (so the caller
+     * can record `snapshot_bytes`), or null when nothing was written (empty
+     * input or an I/O error — never throws).
+     */
+    writeSnapshot(id: string, serialized: string): number | null;
+    /**
+     * Read a snapshot for `id`, or null when absent / unreadable / corrupt.
+     * Never throws.
+     */
+    readSnapshot(id: string): SnapshotRead | null;
+    /** Best-effort delete. Never throws; a missing file is success. */
+    deleteSnapshot(id: string): void;
+}
+/**
+ * Build a SnapshotStore bound to the given base directory + Encryptor. All the
+ * gzip / trim / `.plain`-fallback / read-tolerates-corrupt logic is UNCHANGED
+ * from the original module — only `app.getPath` → `config.baseDir` and
+ * `safeStorage.*` → `config.encryptor.*`.
+ */
+declare function createSnapshotStore(config: SnapshotStoreConfig): SnapshotStore;
+
+/**
+ * Dependencies the in-process backend needs that used to be direct `../db` /
+ * `electron` reaches: a SettingsProvider (cwd-hook gating) and a SnapshotStore
+ * (cold-spawn restore). Injected by the composition root via
+ * configureInProcessBackend; defaults are inert so a test/pre-config load is
+ * harmless (no settings → cwd hook degrades to {}, no-op snapshot store → no
+ * restore), preserving the historical "db not ready → best-effort" behaviour.
+ */
+interface BackendDeps {
+    settings: SettingsProvider;
+    snapshots: SnapshotStore;
+}
+/**
+ * InProcessBackend — node-pty instances owned directly by the Electron main
+ * process. This is the historical TerminalManager body verbatim; it now also
+ * formally implements the PtyBackend interface so the IPC layer can hold it
+ * behind that abstraction interchangeably with the Tier 3 HostClient.
+ *
+ * EventEmitter gives us the `on('data'|'exit', …)` half of PtyBackend for free.
+ */
+declare class InProcessBackend extends EventEmitter implements PtyBackend {
+    private deps;
+    constructor(deps?: BackendDeps);
+    /** Swap injected deps (only used if configure lands after lazy construction). */
+    setDeps(deps: BackendDeps): void;
+    private readonly ptys;
+    private readonly scrollback;
+    private readonly shells;
+    /** Last cwd reported by each pty via OSC-7 (in-memory, authoritative). */
+    private readonly liveCwd;
+    /** Pending debounced cwd-persist timers, keyed by terminal id. */
+    private readonly cwdTimers;
+    /**
+     * Tier 2: ids that must keep their pty alive even with zero attached
+     * windows (a disabled-but-retained terminal — e.g. a dev server the user
+     * suspended). The IPC layer consults this in detachOwner: a retained id is
+     * left running on the last detach instead of killed, so re-enable reattaches
+     * to the LIVE session (scrollback replays) rather than spawning fresh.
+     * Insertion order is preserved so the cap can evict the oldest if needed.
+     */
+    private readonly retained;
+    /**
+     * Spawn a new pty for the given id, OR return the existing one if a
+     * window has already attached. Idempotent: a Stage window can attach
+     * to a spec that TheFloor is already running and get the same live
+     * shell + a buffered scrollback to catch up.
+     */
+    create(opts: CreateTerminalOpts): AttachResult;
+    private scheduleCwdPersist;
+    private cleanupCwd;
+    /** Last cwd reported by this pty via OSC-7, or undefined when unknown. */
+    getLiveCwd(id: string): string | undefined;
+    write(id: string, data: string): boolean;
+    resize(id: string, cols: number, rows: number): boolean;
+    kill(id: string): boolean;
+    killAll(): void;
+    list(): TerminalInfo[];
+    isLive(id: string): boolean;
+    /**
+     * Mark/unmark a terminal as retained. A retained terminal's pty is kept
+     * alive by the IPC layer even when its last window detaches. Returns the
+     * resulting retained-id set size. Retaining a terminal that isn't live is
+     * harmless (the flag simply has no pty to protect yet).
+     */
+    setRetained(id: string, retained: boolean): void;
+    isRetained(id: string): boolean;
+    /** Number of currently-retained terminals (for the resource cap). */
+    retainedCount(): number;
+    /** Snapshot of retained ids in insertion order (oldest first). */
+    retainedIds(): string[];
+    /**
+     * Buffered scrollback for a live pty (raw ANSI text), or undefined when the
+     * id has no pty. Tier 2 uses this to serialize a windowless retained pty at
+     * quit so its post-disable output still lands in a snapshot (T2→T1 degrade).
+     */
+    getScrollback(id: string): string | undefined;
+}
+/** Back-compat alias. The class was renamed InProcessBackend in Tier 3; existing
+ *  imports of `TerminalManager` as a TYPE keep working. */
+type TerminalManager = InProcessBackend;
+/**
+ * Wire the in-process backend's settings + snapshot store. Must be called by the
+ * adapter at app-ready, before any terminal is created. Idempotent if the
+ * singleton hasn't been built yet; if it already exists this updates the deps it
+ * uses (the adapter calls this exactly once, before first use).
+ */
+declare function configureInProcessBackend(deps: BackendDeps): void;
+declare function inProcessBackend(): InProcessBackend;
+declare function terminalManager(): PtyBackend;
+/**
+ * Subscribers that want to follow whichever backend is active (the IPC layer's
+ * data/exit fan-out). Re-bound on every backend swap so events always come from
+ * the LIVE backend, not a stale one left behind after a fallback.
+ */
+interface BackendEventHandlers {
+    onData: (id: string, data: string) => void;
+    onExit: (id: string, payload: {
+        exitCode: number;
+        signal?: number;
+    }) => void;
+}
+/**
+ * Register the data/exit fan-out once. Binds to the current active backend and
+ * is automatically re-bound to any backend swapped in via setActiveBackend, so
+ * the IPC layer never has to know the backend changed underneath it.
+ */
+declare function subscribeBackendEvents(handlers: BackendEventHandlers): void;
+/**
+ * Swap the active backend (Tier 3 connect/spawn success → HostClient). Idempotent
+ * and safe to call before any pty exists. Passing null reverts to the in-process
+ * backend — used by the graceful-fallback path when the host dies mid-session.
+ * Re-binds the IPC event fan-out to the new backend.
+ */
+declare function setActiveBackend(backend: PtyBackend | null): void;
+declare function defaultShell(): string;
+
+declare class HostClient extends EventEmitter implements PtyBackend {
+    private readonly socketPath;
+    private readonly snapshots;
+    private socket;
+    private readonly decoder;
+    private seq;
+    private readonly pending;
+    private readonly mirror;
+    private readonly retained;
+    /** Host pid, learned from hello-ok — surfaced for diagnostics. */
+    hostPid: number;
+    private connected;
+    private constructor();
+    /**
+     * Connect to a running host at `socketPath`, perform the version handshake,
+     * and seed the local mirror from the host's live ptys (list + per-pty
+     * scrollback). Resolves to a ready client, or rejects on connect failure /
+     * version mismatch / timeout — the caller then falls back to in-process.
+     *
+     * `snapshots` is the injected snapshot store used by cold-create to surface
+     * any on-disk previous-session snapshot (was a direct `./sessions` import).
+     */
+    static connect(socketPath: string, snapshots: SnapshotStore, timeoutMs?: number): Promise<HostClient>;
+    private wireSocket;
+    private handleSocketError;
+    private handleHostMessage;
+    private nextSeq;
+    /** Send a request and await the correlated reply. */
+    private request;
+    /** Fire-and-forget send for messages with no reply (write/resize/kill/…). */
+    private send;
+    /** Seed the local mirror from the host's live ptys after a (re)connect. */
+    private seedFromHost;
+    /** Ids the host currently has live — used by the lifecycle layer to drive
+     *  the reattach (renderer remounts these specs, replaying host scrollback). */
+    liveIds(): string[];
+    isConnected(): boolean;
+    /** Disconnect WITHOUT killing host ptys (before-quit leave-running). */
+    disconnect(): void;
+    create(opts: CreateTerminalOpts): AttachResult;
+    write(id: string, data: string): boolean;
+    resize(id: string, cols: number, rows: number): boolean;
+    kill(id: string): boolean;
+    /**
+     * NO-OP for the host backend. The whole point of Tier 3 is that ptys survive
+     * a full quit, so the before-quit teardown must NOT kill them. The lifecycle
+     * layer disconnects the client and leaves the host running instead.
+     */
+    killAll(): void;
+    list(): TerminalInfo[];
+    isLive(id: string): boolean;
+    setRetained(id: string, retained: boolean): void;
+    isRetained(id: string): boolean;
+    retainedCount(): number;
+    retainedIds(): string[];
+    getScrollback(id: string): string | undefined;
+}
+
+/**
+ * Tier 3 lifecycle: decide the backend at app-ready, manage the detached
+ * pty-host, and handle graceful fallback.
+ *
+ * The flow (initTerminalBackend):
+ *   1. If the `detached_terminals` setting is OFF (the default — see below) →
+ *      use the in-process backend. Done. This is today's T1/T2 behaviour.
+ *   2. ON → try to CONNECT to an existing host (pidfile alive + version match +
+ *      socket reachable). Success → HostClient, reattach existing ptys.
+ *   3. No usable host → SPAWN one detached, await its pidfile, then connect.
+ *   4. Any failure (spawn, timeout, version mismatch, socket error) → fall back
+ *      to the in-process backend and surface a NON-FATAL toast. The app stays
+ *      fully functional.
+ *
+ * SETTING DEFAULT — `detached_terminals` defaults OFF.
+ *   Rationale: T3 is the heaviest tier and its #1 risk is the dev-vs-packaged
+ *   host-script path. Shipping it default-ON would put every user on an
+ *   unproven detached process the first launch after upgrade. Default-OFF means
+ *   the proven in-process T1/T2 path remains the out-of-box experience; users
+ *   opt in via Settings → Terminal → "Keep terminals running after quit".
+ *
+ * RUNTIME-AGNOSTIC: this module imports neither `electron` nor `../db`. The
+ * connect-or-spawn-or-fallback LOGIC is core; the Electron specifics are
+ * injected:
+ *   - HostSpawner       — resolveHostScript / spawnDetached / userDataDir
+ *                         (was app.getPath + child_process.spawn with execPath +
+ *                          ELECTRON_RUN_AS_NODE).
+ *   - SettingsProvider  — the `detached_terminals` read (was getAllSettings).
+ *   - SnapshotStore     — passed to HostClient for cold-create snapshot probe.
+ *   - onHostStatus      — the fallback toast sink, emits `host-status` instead of
+ *                         a direct BrowserWindow broadcast.
+ * Genie's adapter (genie-adapter.ts) supplies all four via configureHostLifecycle.
+ */
+interface HostLifecycleDeps {
+    spawner: HostSpawner;
+    settings: SettingsProvider;
+    snapshots: SnapshotStore;
+    onHostStatus: (status: HostStatus) => void;
+}
+/**
+ * Wire the host lifecycle's injected ports. Called once by the adapter at
+ * app-ready, before initTerminalBackend. NEVER configured = in-process only
+ * (detachedEnabled below returns false defensively).
+ */
+declare function configureHostLifecycle(d: HostLifecycleDeps): void;
+/** True when the active backend is the detached host (diagnostics + before-quit). */
+declare function isHostBacked(): boolean;
+declare function getHostClient(): HostClient | null;
+/**
+ * Initialise the terminal backend at app-ready. Returns the list of host pty ids
+ * that should be reattached by the renderer (empty for the in-process path or a
+ * cold host). NEVER throws — every failure degrades to in-process.
+ */
+declare function initTerminalBackend(): Promise<{
+    host: boolean;
+    reattachIds: string[];
+}>;
+/**
+ * before-quit, host-backed: DO NOT kill the host ptys. Snapshot (T1) already ran
+ * via the normal before-quit path; here we just disconnect the client and leave
+ * the host running so the next launch reattaches.
+ */
+declare function disconnectHostLeaveRunning(): void;
+
+/**
+ * Absolute path to the bundled detached pty-host script (Tier 3), so a
+ * `HostSpawner` can launch it as a detached child without knowing this
+ * package's dist layout:
+ *
+ * ```ts
+ * import { spawn } from 'node:child_process';
+ * import { ptyHostScriptPath } from '@particle-academy/fancy-term-host';
+ *
+ * const child = spawn(process.execPath, [ptyHostScriptPath(), userDataDir], {
+ *   detached: true, stdio: 'ignore',
+ * });
+ * child.unref();
+ * ```
+ *
+ * The host script is emitted alongside this module in `dist/` as
+ * `pty-host.js`. Works in both the ESM and CJS builds (esbuild fills in
+ * `import.meta.url` for the CJS output; `__dirname` is used when present).
+ */
+declare function ptyHostScriptPath(): string;
+
+/**
+ * Path + pidfile resolution for the detached pty-host (Tier 3).
+ *
+ * Kept ELECTRON-FREE on the resolution side that the host itself uses (the host
+ * is a plain node process — no `app`), so the userData path is passed IN. The
+ * in-app side (host-client lifecycle) imports `app` separately and feeds it here.
+ */
+interface Pidfile {
+    pid: number;
+    socketPath: string;
+    protocolVersion: number;
+    startedAt: number;
+}
+/** Short, stable per-user hash so two OS users don't collide on the Windows
+ *  pipe name (the pipe namespace is machine-global). */
+declare function userHash(): string;
+/**
+ * The local IPC transport address.
+ *   • Windows: a named pipe `\\.\pipe\genie-ptyhost-<userhash>`. The default
+ *     Windows pipe ACL is per-logon-session, so another user on the same machine
+ *     can't open it — that's our ACL. (Documented; we don't tighten further.)
+ *   • POSIX: a unix domain socket under userData (preferred — survives /tmp
+ *     cleaners and is per-user by directory perms) named `ptyhost.sock`.
+ */
+declare function socketPathFor(userDataDir: string): string;
+declare function pidfilePath(userDataDir: string): string;
+declare function writePidfile(userDataDir: string, pf: Pidfile): void;
+declare function readPidfile(userDataDir: string): Pidfile | null;
+declare function deletePidfile(userDataDir: string): void;
+/** True when a process with `pid` is alive (signal 0 probes without killing). */
+declare function isPidAlive(pid: number): boolean;
+/**
+ * Decide whether an existing pidfile points at a usable host.
+ * Usable = pid alive AND protocol versions match. A stale/dead/mismatched
+ * pidfile means we must spawn a fresh host.
+ */
+declare function pidfileUsable(pf: Pidfile | null): boolean;
+/**
+ * Resolve the compiled pty-host script on disk, trying multiple candidate paths
+ * so it works in BOTH `npm run dev` (script at app/pty-host.js next to
+ * background.js) AND a packaged asar build. node-pty's native binding can't load
+ * from inside an asar, so the host (which requires node-pty) must run UNPACKED —
+ * `app.asar.unpacked/...`. We try the unpacked path first, then the in-asar path,
+ * then a dev-relative path. Returns the first that exists, or null.
+ *
+ * `dirname` is main/background's __dirname (the directory the compiled main
+ * bundle lives in). The host script is emitted alongside it as `pty-host.js`.
+ */
+declare function resolveHostScript(dirname: string): string | null;
+
+/**
+ * Pty-host wire protocol (Tier 3).
+ *
+ * The detached pty-host (main/terminal/pty-host.ts) and the in-app HostClient
+ * (main/terminal/host-client.ts) talk over a local IPC transport — a named pipe
+ * on Windows, a unix domain socket on POSIX — using a tiny length-prefixed JSON
+ * framing so there's no heavy dependency. This module is PURE (no electron, no
+ * node-pty, no net): just the message shapes + the encode/decode for the framing,
+ * so it can be imported by both ends AND unit-tested in isolation.
+ *
+ * Framing: each message is `[4-byte big-endian uint32 length][utf8 JSON body]`.
+ * The length prefix is the byte length of the JSON body. A FrameDecoder buffers
+ * partial reads and yields whole messages as they complete — TCP/pipe streams
+ * don't preserve message boundaries, so we can't assume one `data` event == one
+ * message.
+ */
+/**
+ * Protocol version. Bumped whenever the message shapes change in a way that
+ * makes an old host incompatible with a new client (or vice-versa). The client
+ * refuses to attach to a host whose pidfile reports a different version and
+ * spawns a fresh host instead — see host-client.ts connect-or-spawn.
+ */
+declare const PROTOCOL_VERSION = 1;
+/** Requests the client sends to the host. `seq` correlates a reply. */
+type ClientMessage = {
+    kind: 'hello';
+    seq: number;
+    protocolVersion: number;
+} | {
+    kind: 'create';
+    seq: number;
+    opts: {
+        id: string;
+        cwd: string;
+        shell?: string;
+        args?: string[];
+        cols?: number;
+        rows?: number;
+        env?: Record<string, string>;
+    };
+} | {
+    kind: 'write';
+    id: string;
+    data: string;
+} | {
+    kind: 'resize';
+    id: string;
+    cols: number;
+    rows: number;
+} | {
+    kind: 'kill';
+    id: string;
+} | {
+    kind: 'list';
+    seq: number;
+} | {
+    kind: 'set-retained';
+    id: string;
+    retained: boolean;
+} | {
+    kind: 'get-scrollback';
+    seq: number;
+    id: string;
+} | {
+    kind: 'ping';
+    seq: number;
+};
+/** Pushes + replies the host sends to the client. */
+type HostMessage = {
+    kind: 'hello-ok';
+    seq: number;
+    protocolVersion: number;
+    pid: number;
+} | {
+    kind: 'created';
+    seq: number;
+    result: {
+        id: string;
+        pid: number;
+        shell: string;
+        existing: boolean;
+        scrollback: string;
+    };
+} | {
+    kind: 'list-result';
+    seq: number;
+    terminals: Array<{
+        id: string;
+        pid: number;
+        shell: string;
+    }>;
+} | {
+    kind: 'scrollback-result';
+    seq: number;
+    scrollback: string | null;
+} | {
+    kind: 'pong';
+    seq: number;
+} | {
+    kind: 'data';
+    id: string;
+    data: string;
+} | {
+    kind: 'exit';
+    id: string;
+    exitCode: number;
+    signal?: number;
+};
+type Frame = ClientMessage | HostMessage;
+/** Encode a message as a length-prefixed JSON frame ready for the socket. */
+declare function encodeFrame(msg: Frame): Buffer;
+/**
+ * Streaming frame decoder. Feed it raw socket chunks via `push`; it returns the
+ * complete messages that became available (zero or more), buffering any partial
+ * tail until the rest arrives. One decoder per socket.
+ *
+ * Resilient by design: a malformed JSON body is skipped (the frame is consumed
+ * but yields nothing) rather than throwing — a corrupt frame must not wedge the
+ * whole stream. An absurd length prefix (> MAX_FRAME) is treated as a desync and
+ * the buffer is reset; the caller can decide whether to drop the connection.
+ */
+declare class FrameDecoder {
+    private buffer;
+    /** Hard cap on a single frame (16 MB). Guards against a runaway/garbage
+     *  length prefix allocating unbounded memory. node-pty data chunks are tiny;
+     *  a serialized scrollback is bounded well under this. */
+    static readonly MAX_FRAME: number;
+    /** True when the last push hit an oversized/desynced frame. The caller
+     *  should drop the connection — the stream can't be trusted to realign. */
+    desynced: boolean;
+    push(chunk: Buffer): Frame[];
+}
+
+/**
+ * Shell detection + default-shell resolution for the terminal subsystem.
+ *
+ * Mirrors main/editors.ts: probe well-known install paths, return what's
+ * actually present. Ids line up with fancy-term's BUILTIN_SHELLS so the
+ * renderer can map detections straight onto ShellProfile entries
+ * (cmd · powershell · pwsh · git-bash · bash · zsh · wsl).
+ *
+ * Default policy (Windows): Git Bash when detected — it's the shell the
+ * Tynn toolchain assumes — then pwsh, then Windows PowerShell, then cmd.
+ * On macOS/Linux the user's $SHELL wins, falling back to bash.
+ */
+interface ShellInfo {
+    /** Stable id, matches fancy-term BUILTIN_SHELLS where possible. */
+    id: string;
+    /** Display label, e.g. "Git Bash". */
+    label: string;
+    /** Absolute executable path (or bare command when resolved via PATH). */
+    command: string;
+    /** Default args for an interactive session. */
+    args: string[];
+}
+declare function detectShells(): ShellInfo[];
+/** Default policy: Git Bash > pwsh > powershell > cmd (win); $SHELL > bash (unix). */
+declare function defaultShellId(detected: ShellInfo[]): string | null;
+/**
+ * Split a manual "executable line" into command + args. Honors double
+ * quotes around the executable path ("C:\Program Files\Git\bin\bash.exe"
+ * --login -i). Single-token lines pass through untouched.
+ */
+declare function parseCommandLine(line: string): {
+    command: string;
+    args: string[];
+};
+/** Coarse shell family, derived from the executable name, used to decide which
+ *  OSC-7 prompt hook (if any) we can inject. */
+type ShellKind = 'powershell' | 'bash' | 'zsh' | 'fish' | 'cmd' | 'other';
+declare function shellKind(command: string): ShellKind;
+/** The spawn additions (env + extra args) a shell needs to emit OSC-7 cwd. */
+interface CwdHook {
+    /** Extra env entries to merge into the pty's environment. */
+    env: Record<string, string>;
+    /** Extra args to APPEND to the shell's launch args (PowerShell needs these). */
+    args: string[];
+}
+/**
+ * Build the spawn additions (env + args) that make a shell emit OSC-7 cwd
+ * reports on every prompt, so resumed terminals know where they were
+ * (Tier 1.5). Gated by the `track_cwd` setting (default ON). Returns an empty
+ * hook when tracking is off or the shell genuinely can't be hooked — the
+ * manager then degrades to the static cwd.
+ *
+ * Coverage (all overlay, never clobber the user's own prompt/rc):
+ *   - **bash** — prepend an OSC-7 `printf` to `PROMPT_COMMAND` (env only). The
+ *     portable, reliable case (Git Bash on Windows, bash on POSIX).
+ *   - **zsh** — point `ZDOTDIR` at a generated dir whose `.zshrc` sources the
+ *     user's real `.zshrc`, restores `ZDOTDIR`, then registers a `precmd`
+ *     emitter; `.zshenv` sources the user's real `.zshenv` first.
+ *   - **fish** — prepend a generated dir to `XDG_DATA_DIRS` carrying a
+ *     `fish/vendor_conf.d/osc7.fish` that hooks `--on-event fish_prompt`
+ *     (vendor conf overlays the user's config rather than replacing it).
+ *   - **PowerShell (pwsh/powershell)** — write a profile shim that wraps any
+ *     existing `prompt` and emits OSC-7, dot-sourced via appended
+ *     `-NoExit -Command ". '<shim>'"` args (PS has no env-var prompt hook).
+ *   - **cmd.exe (best-effort)** — set `PROMPT` to emit OSC-7 via the `$E`
+ *     escape before the normal `$P$G`. Renders only where the console honors
+ *     VT sequences in the prompt; otherwise degrades to static cwd.
+ *
+ * The emitted payload is always `file:///<path>` (empty authority, forward
+ * slashes / Windows drive) so it round-trips through {@link scanOsc7Cwd}.
+ */
+declare function cwdHookSpawn(command: string, settings: SettingsProvider): CwdHook;
+/**
+ * Back-compat env-only view of {@link cwdHookSpawn} — returns just the env
+ * additions. Shells that also need launch args (PowerShell) are only fully
+ * hooked via `cwdHookSpawn`; callers using this alone get the env half.
+ */
+declare function cwdHookEnv(command: string, settings: SettingsProvider): Record<string, string>;
+/**
+ * Resolve the user's configured default shell to a concrete spawn target.
+ * Reads the `terminal_shell` setting (a detected id, or 'custom' paired
+ * with `terminal_custom_cmd`). Anything unresolvable falls back to the
+ * detection-based default so the terminal always opens SOMETHING.
+ */
+declare function resolveDefaultShell(settings: SettingsProvider): {
+    command: string;
+    args: string[];
+};
+
+/**
+ * OSC-7 cwd reporting (Tier 1.5).
+ *
+ * A shell that emits OSC-7 tells the terminal its current working directory on
+ * every prompt:
+ *
+ *   ESC ] 7 ; file://HOST/PATH  (BEL | ESC \)
+ *
+ * We scan raw pty output for these and parse out an absolute filesystem path so
+ * a fresh shell spawned on resume can start where the old one left off. The
+ * sequence is terminated by either BEL (\x07) or ST (ESC \, i.e. \x1b\x5c).
+ *
+ * Path forms handled:
+ *   file:///home/user/proj          → /home/user/proj
+ *   file://hostname/home/user/proj  → /home/user/proj   (host ignored)
+ *   file:///C:/Users/me/proj        → C:\Users\me\proj  (Windows drive)
+ *   percent-encoded segments (%20)  → decoded
+ */
+/**
+ * Parse a `file://...` URL from an OSC-7 payload into a local filesystem path.
+ * Returns null when the payload isn't a usable file URL.
+ */
+declare function parseFileUrl(payload: string): string | null;
+/**
+ * Scan a chunk of pty output and return the LAST cwd reported via OSC-7, or
+ * null when the chunk contains no (parseable) OSC-7 sequence. We take the last
+ * one because a single chunk can carry several prompts; the most recent wins.
+ */
+declare function scanOsc7Cwd(chunk: string): string | null;
+
+export { type AttachResult, type BackendDeps, type ClientMessage, type CreateTerminalOpts, type CwdHook, type Encryptor, type Frame, FrameDecoder, HostClient, type HostMessage, type HostSpawner, type HostStatus, PROTOCOL_VERSION, type Pidfile, type PtyBackend, type SettingsProvider, type ShellInfo, type ShellKind, type SnapshotRead, type SnapshotStore, type SnapshotStoreConfig, type TerminalInfo, type TerminalManager, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, deletePidfile, detectShells, disconnectHostLeaveRunning, encodeFrame, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, isPidAlive, parseCommandLine, parseFileUrl, pidfilePath, pidfileUsable, ptyHostScriptPath, readPidfile, resolveDefaultShell, resolveHostScript, scanOsc7Cwd, setActiveBackend, shellKind, socketPathFor, subscribeBackendEvents, terminalManager, userHash, writePidfile };