parasor 0.1.0

package/server/pty/host-protocol/messages.d.ts

@@ -0,0 +1,140 @@
+import { Buffer } from "node:buffer";
+import type { IdeCommandConfig, PaneCommandConfig, Project, ProjectState, ServiceConfig, Session, SessionCommand, SessionEndReason } from "@parasor/shared";
+export declare const PROTOCOL_VERSION = "2.4.0";
+export interface HelloPayload {
+    protocolVersion: string;
+    serverPid: number;
+}
+export interface HelloAckPayload {
+    protocolVersion: string;
+    connectionId: number;
+    /** stringified bigint (JSON cannot carry u64 directly). */
+    generation: string;
+    daemonPid: number;
+    daemonStartedAt: string;
+}
+export type NackCode = "version-mismatch" | "evicted" | "daemon-shutting-down" | "frame-too-large" | "frame-invalid" | "unknown-frame-type" | "handshake-required" | "session-not-found" | "create-failed" | "restart-failed" | "persist-failed" | "internal-error";
+export interface NackPayload {
+    code: NackCode;
+    message: string;
+}
+export interface CreateReqPayload {
+    projectId: string;
+    command: SessionCommand;
+    cwd: string;
+    title?: string;
+    bootstrapInput?: string;
+}
+export interface CreateAckPayload {
+    session: Session;
+}
+export interface RestartReqPayload {
+    sessionId: string;
+}
+export interface RestartAckPayload {
+    session: Session;
+}
+export interface DisposeReqPayload {
+    sessionId: string;
+}
+export type EmptyAckPayload = Record<string, never>;
+export interface InitClientReqPayload {
+    sessionId: string;
+    clientId: string;
+    cols: number;
+    rows: number;
+    /**
+     * Attach fencing: server-side monotonic counter identifying this attach.
+     * Daemon stamps it onto its `attachedClients` entry so a stale
+     * DETACH_CLIENT (delivered after the new attach already overwrote the
+     * map slot) can be filtered against the current entry's stamp.
+     * Optional for older clients/peers that predate the fence.
+     */
+    attachToken?: number;
+}
+export interface InitClientAckPayload {
+    /** false when sessionId is unknown or daemon refuses (e.g. evicted). */
+    accepted: boolean;
+}
+export interface PersistProjectDomainsReqPayload {
+    projects: Project[];
+    projectStates: Record<string, ProjectState>;
+    serviceConfig: ServiceConfig;
+    paneCommands?: PaneCommandConfig[];
+    ideCommands?: IdeCommandConfig[];
+}
+export interface ResizePayload {
+    sessionId: string;
+    cols: number;
+    rows: number;
+}
+export interface RefreshPayload {
+    sessionId: string;
+}
+export interface FlowControlPayload {
+    sessionId: string;
+    clientId: string;
+}
+export interface DetachClientPayload {
+    sessionId: string;
+    clientId: string;
+    /**
+     * Attach fencing: when present, the daemon only deletes the entry whose
+     * stored attach-token matches. A stale onClose racing a new attach
+     * carries the old token; the daemon's current entry already holds the
+     * new token, so the delete is skipped and the live listener survives.
+     */
+    attachToken?: number;
+}
+export interface SetTitlePayload {
+    sessionId: string;
+    title: string;
+    titleManual?: boolean;
+}
+export interface SetPinnedPayload {
+    sessionId: string;
+    pinned: boolean;
+}
+export interface SetPtyEnvPayload {
+    env: Record<string, string>;
+}
+export interface SessionUpdatePayload {
+    session: Session;
+}
+export interface SessionListPayload {
+    sessions: Session[];
+}
+export interface SessionExitPayload {
+    sessionId: string;
+    /** Session.generation at the time the PTY exited (restart counter). */
+    sessionGeneration: number;
+    endReason: SessionEndReason;
+}
+export declare function encodeJsonPayload(value: unknown): Buffer;
+export declare function decodeJsonPayload<T>(payload: Buffer): T;
+interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export declare function parseSemver(input: string): Semver | null;
+/**
+ *  compat rule: MAJOR must match AND daemon.MINOR ≥ client.MINOR.
+ * Client = the side that initiates HELLO (server). Daemon side runs this
+ * on receiving HELLO; server side runs it after reading HELLO_ACK to
+ * detect the "daemon older than server" case.
+ */
+export declare function isCompatibleVersion(clientVersion: string, daemonVersion: string): boolean;
+/**
+ * daemon protocol mismatch recovery -- extract `(server, daemon)` versions from the daemon-side NACK
+ * message format `server X.Y.Z not compatible with daemon X.Y.Z`. The
+ * daemon emits this verbatim (host-daemon/daemon.ts:272). Returns null
+ * when the message shape changes -- recovery and probe paths fall back to
+ * `daemonProtocolVersion: "unknown"` in that case.
+ */
+export declare function parseVersionMismatch(msg: string): {
+    server: string;
+    daemon: string;
+} | null;
+export {};
+//# sourceMappingURL=messages.d.ts.map

package/server/pty/host-protocol/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/pty/host-protocol/messages.ts"],"names":[],"mappings":"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"}

package/server/pty/host-protocol/messages.js

@@ -0,0 +1,117 @@
+/*
+ * Typed payload schemas for PtyHost IPC frames.
+ *
+ * Frame envelope (length, type, connectionId, generation, requestId) lives
+ * in `frames.ts`. This module defines the JSON payloads carried inside
+ * each frame type plus the  version-compat rule. Stream-payload frames
+ * (WRITE / DATA / SESSION_INPUT) bypass JSON entirely -- see
+ * `STREAM_FRAME_TYPES` and `encodeStreamPayload` in `frames.ts`.
+ */
+import { Buffer } from "node:buffer";
+/*
+ * 2.4.0 -- adds `ideCommands` to PERSIST_PROJECT_DOMAINS_REQ so custom
+ * IDE launchers persist through the daemon single-writer path. A 2.3.x
+ * daemon would ACK but silently ignore that field, so the minor bump forces
+ * a daemon restart before the server relies on it.
+ *
+ * 2.3.0 -- adds `paneCommands` to PERSIST_PROJECT_DOMAINS_REQ so server-side
+ * terminal launcher commands persist through the daemon single-writer path.
+ * A 2.2.x daemon would ACK but silently ignore that field, so the minor bump
+ * forces a daemon restart before the server relies on it.
+ *
+ * 2.2.0 -- adds PAUSE_OUTPUT / RESUME_OUTPUT fire-and-forget frames so
+ * terminal WebSocket backpressure can reach daemon-owned PTYs. The minor
+ * bump forces older 2.1 daemons to restart before a new server relies on
+ * the new frame types.
+ *
+ * 2.1.0 -- added optional `bootstrapInput` to CREATE_REQ so the daemon can
+ * feed one-shot startup input into a newly-spawned PTY. A 2.0.x daemon would
+ * ignore that field and create an empty shell, so the MINOR bump forces the
+ * upgraded server to restart the daemon before command-launcher sessions run.
+ *
+ * 2.0.0 -- MAJOR bump for PTY generation gate. Both WRITE (server->daemon, INPUT) and
+ * DATA (daemon->server, OUTPUT) frames now carry a uint32 BE generation
+ * field between sessionId and data: `[idLen][sessionId][gen:u32 BE][data]`.
+ * This is wire-incompatible with 1.x -- a 1.x daemon that received a 2.0
+ * WRITE frame would mis-parse the 4-byte gen as the leading bytes of
+ * `data` and corrupt the new shell's stdin; a 1.x server that received
+ * a 2.0 DATA frame would mis-parse it the same way. The `daemon.minor ≥
+ * client.minor` compat rule does NOT cover the inverse direction (older
+ * server vs newer daemon), so we MUST bump MAJOR -- `c.major !== d.major`
+ * cleanly rejects every 1.x ↔ 2.x pairing at handshake and forces the
+ * server to cold-restart the daemon before any WRITE/DATA flows. The
+ * MAJOR bump also subsumes the 1.3.0 force-restart goal -- any 1.x
+ * daemon (including 1.3.x) is rejected at handshake, so per-session
+ * uploadsDir injection from upload staging isolation is also picked up by the cold-restart.
+ *
+ * 1.3.0 -- upload staging isolation . Daemon-side `InProcessPtyHost`
+ * now consumes `uploadsDir` and stamps `PARASOR_UPLOAD_DIR=<dir>/<sid>`
+ * onto every spawned PTY's env via `buildSessionEnv`. A stale 1.2.x
+ * daemon would still hold the before upload staging isolation global `PARASOR_UPLOAD_DIR=<root>`
+ * (set by the old `setPtyEnv` path in the upgraded server's predecessor)
+ * -- the cross-session leak we fixed. Bumping the version forces the
+ *  handshake to NACK `version-mismatch`, which `host.ts` already
+ * routes through `terminateDaemon` + `spawnDaemon` so the replacement
+ * daemon picks up the new per-session injection. No payload schema
+ * changed; the bump is purely a forced-restart signal.
+ *
+ * 1.2.0 -- added `attachToken` to InitClientReq (server-minted, echoed
+ * on the matching ACK) and DetachClient payloads for attach fencing fencing-token
+ * detach. A pre-1.2.0 daemon ignores the field and treats DETACH_CLIENT
+ * as unconditional delete, which would re-open the same-clientId race
+ * during a daemon-running-across-upgrade window.
+ *  compat rule (daemon.minor ≥ client.minor) rejects 1.1.x daemons
+ * at handshake so the upgraded server cold-restarts the daemon before
+ * any WS attaches.
+ *
+ * 1.1.0 -- added PERSIST_PROJECT_DOMAINS_REQ/ACK (frame types 0x1c/0x1d)
+ * for daemon state ownership single-writer-of-state.json.
+ *
+ * 1.0.0 -- initial release.
+ */
+export const PROTOCOL_VERSION = "2.4.0";
+export function encodeJsonPayload(value) {
+    return Buffer.from(JSON.stringify(value), "utf8");
+}
+export function decodeJsonPayload(payload) {
+    return JSON.parse(payload.toString("utf8"));
+}
+export function parseSemver(input) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(input);
+    if (!m)
+        return null;
+    return {
+        major: Number(m[1]),
+        minor: Number(m[2]),
+        patch: Number(m[3]),
+    };
+}
+/**
+ *  compat rule: MAJOR must match AND daemon.MINOR ≥ client.MINOR.
+ * Client = the side that initiates HELLO (server). Daemon side runs this
+ * on receiving HELLO; server side runs it after reading HELLO_ACK to
+ * detect the "daemon older than server" case.
+ */
+export function isCompatibleVersion(clientVersion, daemonVersion) {
+    const c = parseSemver(clientVersion);
+    const d = parseSemver(daemonVersion);
+    if (!c || !d)
+        return false;
+    if (c.major !== d.major)
+        return false;
+    return d.minor >= c.minor;
+}
+/**
+ * daemon protocol mismatch recovery -- extract `(server, daemon)` versions from the daemon-side NACK
+ * message format `server X.Y.Z not compatible with daemon X.Y.Z`. The
+ * daemon emits this verbatim (host-daemon/daemon.ts:272). Returns null
+ * when the message shape changes -- recovery and probe paths fall back to
+ * `daemonProtocolVersion: "unknown"` in that case.
+ */
+export function parseVersionMismatch(msg) {
+    const m = msg.match(/server (\S+) not compatible with daemon (\S+)/);
+    if (!m)
+        return null;
+    return { server: m[1], daemon: m[2] };
+}
+//# sourceMappingURL=messages.js.map

package/server/pty/host-protocol/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/pty/host-protocol/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAYrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAuKxC,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAI,OAAe;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAM,CAAC;AACnD,CAAC;AAQD,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACpB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,aAAqB,EACrB,aAAqB;IAErB,MAAM,CAAC,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAW;IAEX,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACrE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC"}

package/server/pty/host.d.ts

@@ -0,0 +1,273 @@
+import type { Session, SessionCommand, SessionEndReason, TerminalCapabilities, TerminalLastSeen, TerminalReplayKind, TerminalServerState } from "@parasor/shared";
+import type { AppStateStore } from "../state/app-state.js";
+import type { InProcessPtyHostDaemonContext } from "./in-process-host.js";
+import type { ScrollbackLog } from "./scrollback-log.js";
+/**
+ * Capability declaration sent to `attachClient` on a fresh WS attach.
+ * `lastSeen` is the cursor stored in the client's `sessionStorage` and
+ * applies only when `chunkedReplay=true`.
+ */
+export interface AttachClientCapabilities {
+    binary: boolean;
+    chunkedReplay: boolean;
+    lastSeen?: TerminalLastSeen;
+}
+/**
+ * Result of a successful binary-capable `attachClient`. The host has
+ * already (atomically) registered the chunk listener for live broadcasts,
+ * computed the replay decision, and pre-loaded the chunks/payload the
+ * caller should hand to the WS client.
+ *
+ * `attachClient` receives the attaching client's dimensions, but those
+ * dimensions are authoritative only for first spawn and safe auto-resume.
+ * Passive attach to an already-running shared PTY must not resize it;
+ * later size changes flow through the explicit `resize()` method.
+ *
+ * -- the WS layer must emit init-
+ * ack first, then either (a) the JSON `replay` envelope (`replay="full"`)
+ * or (b) the binary OUTPUT frames in `chunks` (`replay="delta"`), or
+ * neither (`replay="none"`), before live OUTPUT can begin arriving.
+ */
+export interface AttachClientResponse {
+    ok: true;
+    capabilities: TerminalCapabilities;
+    serverState: TerminalServerState;
+    replay: TerminalReplayKind;
+    /** Populated when `replay === "delta"`. Already in seq order. */
+    chunks?: ReadonlyArray<{
+        generation: number;
+        seq: bigint;
+        data: Buffer;
+    }>;
+    /** Populated when `replay === "full"`. UTF-8 string. */
+    fullReplay?: string;
+    replayDiagnostics?: {
+        source: "headless-state" | "headless-rebuild" | "headless-snapshot" | "headless-fallback" | "raw-tail";
+        rawBytes: number;
+        replayBytes: number;
+        headlessDurationMs?: number;
+        headlessBufferLines?: number;
+        headlessEmittedLines?: number;
+        scrollbackLines?: number;
+        maxBytes?: number;
+    };
+    /**
+     * Attach fencing fence -- monotonic identifier for this attach.
+     * The WS handler stashes it in its per-WS state and hands it back via
+     * `detachClient(..., expectedToken)` so a stale onClose firing after a
+     * new attach (same `clientId`) cannot wipe the new listener.
+     */
+    attachToken: number;
+}
+export type AttachClientResult = AttachClientResponse | {
+    ok: false;
+};
+/**
+ * Listener pair for binary-capable clients. The PTY broadcast site fires
+ * `onChunk` once per batched flush (1 broadcast = 1 seq), and `onExit`
+ * once when the PTY exits. Listener faults are isolated by the host so
+ * one bad sink does not starve siblings.
+ */
+export interface AttachClientSink {
+    onChunk: (generation: number, seq: bigint, data: Buffer) => void;
+    onExit?: (exitCode: number) => void;
+}
+/**
+ * Inputs for `PtyHost.create()`. Shared by `InProcessPtyHost` and
+ * `RemotePtyHost`; kept here so the interface is independent of any one
+ * implementation.
+ */
+export interface CreateSessionInput {
+    projectId: string;
+    command: SessionCommand;
+    cwd: string;
+    title?: string;
+    bootstrapInput?: string;
+}
+export type PtyHostMode = "in-process" | "remote";
+/**
+ * Abstract PTY host.
+ *
+ * Two implementations:
+ * - `InProcessPtyHost`: owns the PTY descriptors
+ *   directly inside the server process.
+ * - `RemotePtyHost`: proxies the same API over a local Unix socket to the
+ *   `parasor-pty-host` daemon.
+ *
+ * The factory `createPtyHost()` picks the implementation from the
+ * `PARASOR_PTY_DAEMON` env. Daemon mode is the default (auto-spawned on
+ * first use, detached so it survives foreground parasor restarts) so
+ * that npm-style updates and freeze-recovery restarts can preserve PTY
+ * children. Set `PARASOR_PTY_DAEMON=0` to opt back into in-process mode
+ * (used by `pnpm dev` to keep the daemon socket scoped to the dev
+ * tsx-watch process and avoid colliding with a production daemon).
+ *
+ * --- Consistency contract ---
+ *
+ * Liskov substitutability is governed by the table below. Callers
+ * should be tolerant of `RemotePtyHost`-specific failure modes; the
+ * in-process path is the strict / safe-side baseline.
+ *
+ * | Aspect              | InProcess              | Remote (connected)                              | Remote (reconnecting)                         |
+ * | ------------------- | ---------------------- | ----------------------------------------------- | --------------------------------------------- |
+ * | list()/get()        | sync, always latest    | mirror, up to last SESSION_LIST                 | stale possible; do not trust after `reconnecting` |
+ * | create() ack order  | sync return            | resolves on IPC ack (may precede SESSION_UPDATE)| in-flight rejected (epoch fence, )          |
+ * | initClient() errors | spawn failures only    | + ipc-timeout / version-mismatch / evicted      | + connection-dropped                          |
+ * | state event order   | strict (sync emit)     | best-effort (commit < ack < broadcast)          | snapshot rebuild on reconnect                 |
+ * | failure type        | Error                  | Error or RemotePtyHostError(code)               | RemotePtyHostError(code: "reconnecting")      |
+ *
+ * `shutdownAll()` carries two meanings:
+ * - in-process: kills every live PTY and persists `server-graceful` end
+ *   reasons so sessions can be restored on next start.
+ * - remote: `detach()` only -- closes the IPC connection but leaves
+ *   daemon-side sessions alive. Use the dedicated `terminateAll()` CLI
+ *   command to actually SIGTERM all daemon-side sessions.
+ *   The interface today exposes `shutdownAll()` semantics matching
+ *   in-process; the remote implementation will widen this when added.
+ */
+export interface PtyHost {
+    /** Merge env vars into the per-PTY environment. Subsequent calls accumulate. */
+    setPtyEnv(env: Record<string, string>): void;
+    list(): Session[];
+    get(id: string): Session | undefined;
+    listByProject(projectId: string): Session[];
+    getScrollback(id: string): string | null;
+    getForegroundProcess(id: string): string | null;
+    create(input: CreateSessionInput): Promise<Session>;
+    restart(id: string): Promise<Session>;
+    setTitle(id: string, title: string, titleManual?: boolean): boolean;
+    setPinned(id: string, pinned: boolean): boolean;
+    /**
+     * Write user input to the PTY's stdin.
+     *
+     * `generation` (PTY generation gate): when supplied, the host drops the write if the
+     * client's tagged generation no longer matches the session's current
+     * one. This eliminates the auto-resume race where in-flight terminal-
+     * response sequences (DECRPM/DSR/DA replies the previous TUI's
+     * queries triggered) would otherwise land on the new shell's stdin.
+     * Omitted = no gating (legacy callers + non-input-path writes).
+     */
+    write(id: string, data: string, generation?: number): void;
+    resize(id: string, cols: number, rows: number): void;
+    refresh(id: string): void;
+    pauseOutput(id: string, clientId: string): void;
+    resumeOutput(id: string, clientId: string): void;
+    /**
+     * Legacy (non-binary) attach. Retained for older clients that send
+     * `init` without `capabilities.binary`. `cols` / `rows` follow the same
+     * authority rule as binary attach: first spawn and safe auto-resume may
+     * use them, but passive attach to an already-running shared PTY must not
+     * resize it. Returns `{ ok: false }` on spawn / session-unavailable
+     * failures, otherwise the new attach's fence token (attach fencing) the WS
+     * layer should hand back on detach.
+     *
+     * `attachToken` is normally minted internally and returned. It is
+     * caller-supplied only by the daemon's IPC handler so the daemon-side
+     * `attachedClients` entry stamps the same value the server-side
+     * `RemotePtyHost.bySession` carries -- keeping the fence consistent
+     * across the IPC boundary.
+     */
+    initClient(id: string, clientId: string, cols: number, rows: number, listener: (data: string) => void, attachToken?: number): Promise<{
+        ok: true;
+        attachToken: number;
+    } | {
+        ok: false;
+    }>;
+    /**
+     * Binary-capable attach. The WS handler routes to this method when the
+     * client's `init` declared `capabilities.binary`.
+     * Returns `{ ok: false }` for missing/unattachable sessions; otherwise
+     * the WS layer is responsible for emitting init-ack + replay (full or
+     * delta) on the wire, then registering itself for live `onChunk`s.
+     *
+     * Only `InProcessPtyHost` advertises full chunked-replay support.
+     * `RemotePtyHost` declares `binary=false / chunkedReplay=false` in its
+     * response (the daemon's STREAM_DATA frame does not yet carry chunk
+     * headers) but still forwards live OUTPUT through `sink.onChunk` with
+     * a synthetic gen=0 / per-attach seq counter; daemon-mode chunked
+     * replay is tracked separately.
+     */
+    attachClient(id: string, clientId: string, cols: number, rows: number, capabilities: AttachClientCapabilities, sink: AttachClientSink): Promise<AttachClientResult>;
+    /**
+     * Attach fencing fence: when `expectedToken` is supplied, the entry is
+     * removed only if its stored attach-token matches. A late onClose
+     * from a stale WS therefore cannot drop the listener that a fresh
+     * attach has just registered for the same `clientId`. Internal
+     * cleanup paths (dispose / disposeAll) keep the unconditional shape
+     * by omitting the argument.
+     */
+    detachClient(id: string, clientId: string, expectedToken?: number): void;
+    dispose(id: string): Promise<void>;
+    disposeAll(): Promise<void>;
+    shutdownAll(reason?: SessionEndReason): Promise<void>;
+    loadPersistedSession(session: Session, wasGracefulShutdown: boolean): void;
+    onSessionInput(listener: (sessionId: string, data: string) => void): void;
+    /**
+     * `generation` (PTY generation gate): the PTY generation that produced this OUTPUT
+     * batch. Daemon-mode broadcasters forward this to remote attached
+     * clients so the WS layer can stamp it into binary OUTPUT frames; the
+     * client then echoes it back on INPUT so this host can drop stale
+     * input that targets a generation that no longer exists. Always the
+     * spawn-time generation of the closure that produced the batch (so
+     * mid-flight auto-resume cannot mis-tag old PTY data with the new
+     * generation -- see in-process-host.ts:929).
+     */
+    onSessionData(listener: (sessionId: string, data: string, generation: number) => void): void;
+    onSessionExit: ((sessionId: string, generation: number, endReason: SessionEndReason) => void) | null;
+}
+/**
+ * Read the runtime mode from env. Daemon mode is the default so that a
+ * foreground `parasor` invocation gets the same session-survival
+ * properties as the canonical service install -- npm-style updates and
+ * server-process restarts can preserve PTY children when they live in a
+ * detached daemon. Set `PARASOR_PTY_DAEMON=0` to opt back into
+ * in-process mode (used by the dev script to keep PTYs scoped to the
+ * tsx-watch process and the legacy single-process layout).
+ */
+export declare function resolvePtyHostMode(env?: NodeJS.ProcessEnv): PtyHostMode;
+/**
+ * Factory: pick a `PtyHost` implementation from the environment.
+ *
+ * Asking for an unavailable mode throws so callers don't silently fall back
+ * and leak ownership semantics.
+ *
+ * The factory is intentionally lazy -- it imports `InProcessPtyHost`
+ * at call time so that consumers depending only on the `PtyHost`
+ * interface (e.g. application/route layers) don't pull in the heavy
+ * `node-pty` module at module-eval time.
+ */
+export interface CreatePtyHostDeps {
+    store: AppStateStore;
+    scrollbackLog?: ScrollbackLog | null;
+    mode?: PtyHostMode;
+    /**
+     * In-process mode only -- passed straight through to InProcessPtyHost
+     * to enable SessionRecord persistence.
+     * Required for `parasor pty-host doctor` to surface session state in
+     * in-process mode; the daemon path constructs its own context inside
+     * bootstrap.ts. Optional so existing test sites (no orphan checks)
+     * keep working.
+     */
+    daemonContext?: InProcessPtyHostDaemonContext;
+    /**
+     * Canonical absolute uploads root. In-process mode uses it to inject
+     * a per-session `PARASOR_UPLOAD_DIR=<uploadsDir>/<sessionId>` env var
+     * into every spawned PTY (upload staging isolation reviewed for correctness 1). Remote mode
+     * ignores it -- the daemon will plumb its own value once upload staging isolation's daemon
+     * path is wired.
+     */
+    uploadsDir?: string;
+    /**
+     * daemon protocol mismatch recovery -- invoked once when the remote-mode bootstrap detects a
+     * `version-mismatch` from the running daemon, terminates it, spawns a
+     * fresh daemon, and successfully completes the second handshake.
+     * Caller (index.ts) wires this to ServerNoticesStore so the web banner
+     * can explain why the session list is empty post-upgrade.
+     */
+    onDaemonAutoRestarted?: (detail: {
+        serverProtocolVersion: string;
+        daemonProtocolVersion: string;
+    }) => void;
+}
+export declare function createPtyHost(deps: CreatePtyHostDeps): Promise<PtyHost>;
+//# sourceMappingURL=host.d.ts.map

package/server/pty/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/pty/host.ts"],"names":[],"mappings":"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"}