@particle-academy/fancy-term-host 0.1.0

package/dist/index.js

@@ -0,0 +1,1015 @@
+import { FrameDecoder, PROTOCOL_VERSION, encodeFrame, readPidfile, pidfileUsable, deletePidfile, resolveHostScript } from './chunk-2DQJKTG5.js';
+export { FrameDecoder, PROTOCOL_VERSION, deletePidfile, encodeFrame, isPidAlive, pidfilePath, pidfileUsable, readPidfile, resolveHostScript, socketPathFor, userHash, writePidfile } from './chunk-2DQJKTG5.js';
+import { spawn } from 'node-pty';
+import { EventEmitter } from 'events';
+import fs2 from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import zlib from 'zlib';
+import net from 'net';
+import { fileURLToPath } from 'url';
+
+// src/osc7.ts
+var OSC7_RE = /\x1b\]7;([^\x07\x1b]*)(?:\x07|\x1b\\)/g;
+function parseFileUrl(payload) {
+  if (!payload.startsWith("file://")) return null;
+  let rest = payload.slice("file://".length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) return null;
+  let pathPart = rest.slice(slash);
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathPart);
+  } catch {
+    decoded = pathPart;
+  }
+  const winDrive = /^\/([A-Za-z]):(.*)$/.exec(decoded);
+  if (winDrive) {
+    return `${winDrive[1]}:${winDrive[2]}`.replace(/\//g, "\\");
+  }
+  return decoded;
+}
+function scanOsc7Cwd(chunk) {
+  if (chunk.indexOf("\x1B]7;") === -1) return null;
+  let last = null;
+  OSC7_RE.lastIndex = 0;
+  let m;
+  while (m = OSC7_RE.exec(chunk)) {
+    const cwd = parseFileUrl(m[1]);
+    if (cwd) last = cwd;
+  }
+  return last;
+}
+function firstExisting(paths) {
+  for (const p of paths) {
+    try {
+      if (p && fs2.existsSync(p)) return p;
+    } catch {
+    }
+  }
+  return null;
+}
+function windowsCandidates() {
+  const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+  const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+  const localAppData = process.env.LOCALAPPDATA ?? "";
+  const systemRoot = process.env.SystemRoot ?? "C:\\Windows";
+  return [
+    {
+      id: "git-bash",
+      label: "Git Bash",
+      args: ["--login", "-i"],
+      paths: [
+        path.join(programFiles, "Git", "bin", "bash.exe"),
+        path.join(programFilesX86, "Git", "bin", "bash.exe"),
+        localAppData ? path.join(localAppData, "Programs", "Git", "bin", "bash.exe") : ""
+      ]
+    },
+    {
+      id: "pwsh",
+      label: "PowerShell 7",
+      args: ["-NoLogo"],
+      paths: [
+        path.join(programFiles, "PowerShell", "7", "pwsh.exe"),
+        localAppData ? path.join(localAppData, "Microsoft", "WindowsApps", "pwsh.exe") : ""
+      ]
+    },
+    {
+      id: "powershell",
+      label: "Windows PowerShell",
+      args: ["-NoLogo"],
+      paths: [
+        path.join(
+          systemRoot,
+          "System32",
+          "WindowsPowerShell",
+          "v1.0",
+          "powershell.exe"
+        )
+      ]
+    },
+    {
+      id: "cmd",
+      label: "Command Prompt",
+      args: [],
+      paths: [process.env.COMSPEC ?? path.join(systemRoot, "System32", "cmd.exe")]
+    },
+    {
+      id: "wsl",
+      label: "WSL",
+      args: [],
+      paths: [path.join(systemRoot, "System32", "wsl.exe")]
+    }
+  ];
+}
+function unixCandidates() {
+  return [
+    {
+      id: "zsh",
+      label: "zsh",
+      args: ["-l"],
+      paths: ["/bin/zsh", "/usr/bin/zsh", "/usr/local/bin/zsh", "/opt/homebrew/bin/zsh"]
+    },
+    {
+      id: "bash",
+      label: "bash",
+      args: ["-l"],
+      paths: ["/bin/bash", "/usr/bin/bash", "/usr/local/bin/bash"]
+    },
+    {
+      id: "fish",
+      label: "fish",
+      args: ["-l"],
+      paths: ["/usr/bin/fish", "/usr/local/bin/fish", "/opt/homebrew/bin/fish"]
+    }
+  ];
+}
+function detectShells() {
+  const candidates = process.platform === "win32" ? windowsCandidates() : unixCandidates();
+  const found = [];
+  for (const c of candidates) {
+    const command = firstExisting(c.paths);
+    if (command) found.push({ id: c.id, label: c.label, command, args: c.args });
+  }
+  if (process.platform !== "win32") {
+    const login = process.env.SHELL;
+    if (login && !found.some((s) => s.command === login) && fs2.existsSync(login)) {
+      found.unshift({
+        id: path.basename(login),
+        label: path.basename(login),
+        command: login,
+        args: ["-l"]
+      });
+    }
+  }
+  return found;
+}
+function defaultShellId(detected) {
+  const order = process.platform === "win32" ? ["git-bash", "pwsh", "powershell", "cmd"] : detected.map((s) => s.id);
+  for (const id of order) {
+    if (detected.some((s) => s.id === id)) return id;
+  }
+  return detected[0]?.id ?? null;
+}
+function parseCommandLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return { command: "", args: [] };
+  const tokens = [];
+  const re = /"([^"]*)"|(\S+)/g;
+  let m;
+  while (m = re.exec(trimmed)) tokens.push(m[1] ?? m[2]);
+  return { command: tokens[0] ?? "", args: tokens.slice(1) };
+}
+function shellKind(command) {
+  const base = path.basename(command).toLowerCase();
+  if (base.includes("pwsh") || base.includes("powershell")) return "powershell";
+  if (base.startsWith("zsh")) return "zsh";
+  if (base.startsWith("bash")) return "bash";
+  if (base.startsWith("fish")) return "fish";
+  if (base.startsWith("cmd")) return "cmd";
+  return "other";
+}
+function hookDir() {
+  const seed = `${os.userInfo().username}|${os.hostname()}`;
+  const hash = crypto.createHash("sha1").update(seed).digest("hex").slice(0, 12);
+  const dir = path.join(os.tmpdir(), "fancy-term-host", hash);
+  fs2.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function writeShim(file, contents) {
+  try {
+    fs2.writeFileSync(file, contents, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function cwdHookSpawn(command, settings) {
+  const empty = { env: {}, args: [] };
+  if (settings.get("track_cwd") === "off") return empty;
+  const kind = shellKind(command);
+  const host = os.hostname();
+  if (kind === "bash") {
+    const emit = `printf '\\033]7;file://${host}%s\\033\\\\' "$PWD"`;
+    const prev = process.env.PROMPT_COMMAND ? "; " + process.env.PROMPT_COMMAND : "";
+    return { env: { PROMPT_COMMAND: `${emit}${prev}` }, args: [] };
+  }
+  if (kind === "zsh") {
+    const orig = process.env.ZDOTDIR || os.homedir();
+    const dir = hookDir();
+    const okEnv = writeShim(
+      path.join(dir, ".zshenv"),
+      `# fancy-term-host (generated)
+[ -f "${orig}/.zshenv" ] && source "${orig}/.zshenv"
+`
+    );
+    const okRc = writeShim(
+      path.join(dir, ".zshrc"),
+      `# fancy-term-host (generated)
+ZDOTDIR="${orig}"
+[ -f "${orig}/.zshrc" ] && source "${orig}/.zshrc"
+__fth_osc7() { printf '\\033]7;file://%s\\033\\\\' "$PWD" }
+typeset -ga precmd_functions
+precmd_functions+=(__fth_osc7)
+`
+    );
+    return okEnv && okRc ? { env: { ZDOTDIR: dir }, args: [] } : empty;
+  }
+  if (kind === "fish") {
+    const dir = hookDir();
+    const confDir = path.join(dir, "fish", "vendor_conf.d");
+    try {
+      fs2.mkdirSync(confDir, { recursive: true });
+    } catch {
+      return empty;
+    }
+    const ok = writeShim(
+      path.join(confDir, "osc7.fish"),
+      `# fancy-term-host (generated)
+function __fth_osc7 --on-event fish_prompt
+    printf '\\x1b]7;file://%s\\x1b\\\\' "$PWD"
+end
+`
+    );
+    if (!ok) return empty;
+    const existing = process.env.XDG_DATA_DIRS || "/usr/local/share:/usr/share";
+    return { env: { XDG_DATA_DIRS: `${dir}${path.delimiter}${existing}` }, args: [] };
+  }
+  if (kind === "powershell") {
+    const dir = hookDir();
+    const shim = path.join(dir, "osc7-profile.ps1");
+    const ok = writeShim(
+      shim,
+      `# fancy-term-host (generated)
+$global:__fthPrev = $function:prompt
+function global:prompt {
+    $p = ($PWD.ProviderPath -replace '\\\\','/')
+    [Console]::Write("$([char]27)]7;file:///$p$([char]27)\\")
+    if ($global:__fthPrev) { & $global:__fthPrev } else { "PS $($PWD.ProviderPath)> " }
+}
+`
+    );
+    if (!ok) return empty;
+    return { env: {}, args: ["-NoExit", "-Command", `. '${shim}'`] };
+  }
+  if (kind === "cmd") {
+    return { env: { PROMPT: `$E]7;file:///$P$E\\$P$G` }, args: [] };
+  }
+  return empty;
+}
+function cwdHookEnv(command, settings) {
+  return cwdHookSpawn(command, settings).env;
+}
+function resolveDefaultShell(settings) {
+  const detected = detectShells();
+  const terminalShell = settings.get("terminal_shell");
+  if (terminalShell === "custom") {
+    const parsed = parseCommandLine(settings.get("terminal_custom_cmd") ?? "");
+    if (parsed.command) return parsed;
+  }
+  const pick = detected.find((s) => s.id === terminalShell) ?? detected.find((s) => s.id === defaultShellId(detected));
+  if (pick) return { command: pick.command, args: pick.args };
+  if (process.platform === "win32") {
+    return { command: process.env.COMSPEC ?? "cmd.exe", args: [] };
+  }
+  return { command: process.env.SHELL ?? "/bin/bash", args: [] };
+}
+
+// src/manager.ts
+var SCROLLBACK_MAX = 1e6;
+var CWD_PERSIST_DEBOUNCE_MS = 750;
+var inertDeps = {
+  settings: { get: () => void 0 },
+  snapshots: {
+    writeSnapshot: () => null,
+    readSnapshot: () => null,
+    deleteSnapshot: () => {
+    }
+  }
+};
+var InProcessBackend = class extends EventEmitter {
+  constructor(deps2 = inertDeps) {
+    super();
+    this.deps = deps2;
+    this.ptys = /* @__PURE__ */ new Map();
+    this.scrollback = /* @__PURE__ */ new Map();
+    this.shells = /* @__PURE__ */ new Map();
+    /** Last cwd reported by each pty via OSC-7 (in-memory, authoritative). */
+    this.liveCwd = /* @__PURE__ */ new Map();
+    /** Pending debounced cwd-persist timers, keyed by terminal id. */
+    this.cwdTimers = /* @__PURE__ */ new Map();
+    /**
+     * 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.
+     */
+    this.retained = /* @__PURE__ */ new Set();
+  }
+  /** Swap injected deps (only used if configure lands after lazy construction). */
+  setDeps(deps2) {
+    this.deps = deps2;
+  }
+  /**
+   * 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) {
+    const existing = this.ptys.get(opts.id);
+    if (existing) {
+      return {
+        id: opts.id,
+        pid: existing.pid,
+        shell: this.shells.get(opts.id) ?? existing.process,
+        existing: true,
+        scrollback: this.scrollback.get(opts.id) ?? ""
+      };
+    }
+    const shell = opts.shell ?? defaultShell();
+    const baseArgs = opts.args ?? defaultShellArgs(shell);
+    const hook = cwdHookSpawn(shell, this.deps.settings);
+    const args = hook.args.length ? [...baseArgs, ...hook.args] : baseArgs;
+    const env = {
+      ...process.env,
+      ...hook.env,
+      ...opts.env ?? {}
+    };
+    env.TERM = env.TERM || "xterm-256color";
+    const pty = spawn(shell, args, {
+      name: "xterm-color",
+      cwd: opts.cwd,
+      cols: opts.cols ?? 80,
+      rows: opts.rows ?? 24,
+      env
+    });
+    this.ptys.set(opts.id, pty);
+    this.shells.set(opts.id, shell);
+    this.scrollback.set(opts.id, "");
+    pty.onData((data) => {
+      const buf = this.scrollback.get(opts.id) ?? "";
+      const next = buf + data;
+      this.scrollback.set(
+        opts.id,
+        next.length > SCROLLBACK_MAX ? next.slice(-SCROLLBACK_MAX) : next
+      );
+      const cwd = scanOsc7Cwd(data);
+      if (cwd && cwd !== this.liveCwd.get(opts.id)) {
+        this.liveCwd.set(opts.id, cwd);
+        this.scheduleCwdPersist(opts.id, cwd);
+      }
+      this.emit("data", opts.id, data);
+    });
+    pty.onExit(({ exitCode, signal }) => {
+      this.cleanupCwd(opts.id);
+      this.ptys.delete(opts.id);
+      this.scrollback.delete(opts.id);
+      this.shells.delete(opts.id);
+      this.retained.delete(opts.id);
+      this.emit("exit", opts.id, { exitCode, signal });
+    });
+    const snap = this.deps.snapshots.readSnapshot(opts.id);
+    return {
+      id: opts.id,
+      pid: pty.pid,
+      shell,
+      existing: false,
+      scrollback: "",
+      snapshot: snap ?? void 0
+    };
+  }
+  scheduleCwdPersist(id, cwd) {
+    const existing = this.cwdTimers.get(id);
+    if (existing) clearTimeout(existing);
+    const t = setTimeout(() => {
+      this.cwdTimers.delete(id);
+      this.emit("cwd", id, cwd);
+    }, CWD_PERSIST_DEBOUNCE_MS);
+    if (typeof t.unref === "function") t.unref();
+    this.cwdTimers.set(id, t);
+  }
+  cleanupCwd(id) {
+    const t = this.cwdTimers.get(id);
+    if (t) {
+      clearTimeout(t);
+      this.cwdTimers.delete(id);
+    }
+    const cwd = this.liveCwd.get(id);
+    if (cwd) this.emit("cwd", id, cwd);
+    this.liveCwd.delete(id);
+  }
+  /** Last cwd reported by this pty via OSC-7, or undefined when unknown. */
+  getLiveCwd(id) {
+    return this.liveCwd.get(id);
+  }
+  write(id, data) {
+    const pty = this.ptys.get(id);
+    if (!pty) return false;
+    pty.write(data);
+    return true;
+  }
+  resize(id, cols, rows) {
+    const pty = this.ptys.get(id);
+    if (!pty) return false;
+    pty.resize(Math.max(1, cols | 0), Math.max(1, rows | 0));
+    return true;
+  }
+  kill(id) {
+    const pty = this.ptys.get(id);
+    if (!pty) return false;
+    try {
+      pty.kill();
+    } catch {
+    }
+    this.cleanupCwd(id);
+    this.ptys.delete(id);
+    this.scrollback.delete(id);
+    this.shells.delete(id);
+    this.retained.delete(id);
+    return true;
+  }
+  killAll() {
+    for (const id of Array.from(this.ptys.keys())) {
+      this.kill(id);
+    }
+  }
+  list() {
+    return Array.from(this.ptys.entries()).map(([id, pty]) => ({
+      id,
+      pid: pty.pid,
+      shell: this.shells.get(id) ?? pty.process
+    }));
+  }
+  isLive(id) {
+    return this.ptys.has(id);
+  }
+  // --- Tier 2: retained-PTY (disabled-not-deleted) -----------------------
+  /**
+   * 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, retained) {
+    if (retained) this.retained.add(id);
+    else this.retained.delete(id);
+  }
+  isRetained(id) {
+    return this.retained.has(id);
+  }
+  /** Number of currently-retained terminals (for the resource cap). */
+  retainedCount() {
+    return this.retained.size;
+  }
+  /** Snapshot of retained ids in insertion order (oldest first). */
+  retainedIds() {
+    return Array.from(this.retained);
+  }
+  /**
+   * 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) {
+    return this.scrollback.get(id);
+  }
+};
+var configuredDeps = inertDeps;
+function configureInProcessBackend(deps2) {
+  configuredDeps = deps2;
+  if (inProcess) inProcess.setDeps(deps2);
+}
+var inProcess = null;
+function inProcessBackend() {
+  if (!inProcess) inProcess = new InProcessBackend(configuredDeps);
+  return inProcess;
+}
+var active = null;
+function terminalManager() {
+  if (!active) active = inProcessBackend();
+  return active;
+}
+var eventHandlers = null;
+var boundBackends = /* @__PURE__ */ new WeakSet();
+function bindEvents(backend) {
+  if (!eventHandlers) return;
+  if (boundBackends.has(backend)) return;
+  boundBackends.add(backend);
+  backend.on("data", eventHandlers.onData);
+  backend.on("exit", eventHandlers.onExit);
+}
+function subscribeBackendEvents(handlers) {
+  eventHandlers = handlers;
+  bindEvents(terminalManager());
+}
+function setActiveBackend(backend) {
+  const next = backend ?? inProcessBackend();
+  if (next === active) return;
+  active = next;
+  bindEvents(active);
+}
+function defaultShell() {
+  if (process.platform === "win32") {
+    return process.env.COMSPEC ?? "cmd.exe";
+  }
+  return process.env.SHELL ?? "/bin/bash";
+}
+function defaultShellArgs(shell) {
+  const base = shell.toLowerCase();
+  if (base.endsWith("powershell.exe") || base.endsWith("pwsh.exe")) {
+    return ["-NoLogo"];
+  }
+  return [];
+}
+var MAX_SERIALIZED_BYTES = 256 * 1024;
+var MAGIC_ENCRYPTED = 1;
+var MAGIC_PLAINTEXT = 0;
+var warnedNoEncryption = false;
+function trimTail(serialized) {
+  const buf = Buffer.from(serialized, "utf8");
+  if (buf.length <= MAX_SERIALIZED_BYTES) return serialized;
+  return buf.subarray(buf.length - MAX_SERIALIZED_BYTES).toString("utf8");
+}
+function createSnapshotStore(config) {
+  const { encryptor } = config;
+  function sessionsDir() {
+    const dir = path.join(config.baseDir, "sessions");
+    if (!fs2.existsSync(dir)) fs2.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+  function snapPath(id) {
+    const safe = id.replace(/[^A-Za-z0-9_-]/g, "");
+    return path.join(sessionsDir(), `${safe}.snap`);
+  }
+  function encryptionAvailable() {
+    try {
+      return encryptor.isAvailable();
+    } catch {
+      return false;
+    }
+  }
+  function writeSnapshot(id, serialized) {
+    try {
+      if (!serialized) return null;
+      const trimmed = trimTail(serialized);
+      const gz = zlib.gzipSync(Buffer.from(trimmed, "utf8"));
+      let body;
+      let magic;
+      if (encryptionAvailable()) {
+        magic = MAGIC_ENCRYPTED;
+        body = encryptor.encrypt(Buffer.from(gz.toString("base64"), "utf8"));
+      } else {
+        if (!warnedNoEncryption) {
+          warnedNoEncryption = true;
+          console.warn(
+            "[sessions] OS encryption unavailable \u2014 writing terminal snapshots as plaintext gzip. Install libsecret/gnome-keyring on Linux to encrypt them at rest."
+          );
+        }
+        magic = MAGIC_PLAINTEXT;
+        body = gz;
+      }
+      const out = Buffer.concat([Buffer.from([magic]), body]);
+      const target = snapPath(id);
+      const tmp = `${target}.tmp`;
+      fs2.writeFileSync(tmp, out);
+      fs2.renameSync(tmp, target);
+      return out.length;
+    } catch {
+      return null;
+    }
+  }
+  function readSnapshot(id) {
+    try {
+      const file = snapPath(id);
+      const stat = fs2.statSync(file);
+      const raw = fs2.readFileSync(file);
+      if (raw.length < 2) return null;
+      const magic = raw[0];
+      const body = raw.subarray(1);
+      let gz;
+      if (magic === MAGIC_ENCRYPTED) {
+        if (!encryptionAvailable()) return null;
+        const b64 = encryptor.decrypt(body).toString("utf8");
+        gz = Buffer.from(b64, "base64");
+      } else if (magic === MAGIC_PLAINTEXT) {
+        gz = body;
+      } else {
+        return null;
+      }
+      const serialized = zlib.gunzipSync(gz).toString("utf8");
+      return { serialized, savedAt: stat.mtimeMs };
+    } catch {
+      return null;
+    }
+  }
+  function deleteSnapshot(id) {
+    try {
+      fs2.rmSync(snapPath(id), { force: true });
+    } catch {
+    }
+  }
+  return { writeSnapshot, readSnapshot, deleteSnapshot };
+}
+var SCROLLBACK_MAX2 = 1e6;
+var HostClient = class _HostClient extends EventEmitter {
+  constructor(socketPath, snapshots) {
+    super();
+    this.socketPath = socketPath;
+    this.snapshots = snapshots;
+    this.socket = null;
+    this.decoder = new FrameDecoder();
+    this.seq = 0;
+    this.pending = /* @__PURE__ */ new Map();
+    this.mirror = /* @__PURE__ */ new Map();
+    this.retained = /* @__PURE__ */ new Set();
+    /** Host pid, learned from hello-ok — surfaced for diagnostics. */
+    this.hostPid = 0;
+    this.connected = false;
+  }
+  /**
+   * 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, snapshots, timeoutMs = 3e3) {
+    return new Promise((resolve, reject) => {
+      const client2 = new _HostClient(socketPath, snapshots);
+      const sock = net.createConnection(socketPath);
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        try {
+          sock.destroy();
+        } catch {
+        }
+        reject(new Error("pty-host connect timeout"));
+      }, timeoutMs);
+      sock.on("error", (err) => {
+        if (settled) {
+          client2.handleSocketError(err);
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      });
+      sock.once("connect", async () => {
+        client2.socket = sock;
+        client2.wireSocket(sock);
+        try {
+          const hello = await client2.request({
+            kind: "hello",
+            seq: client2.nextSeq(),
+            protocolVersion: PROTOCOL_VERSION
+          });
+          if (hello.protocolVersion !== PROTOCOL_VERSION) {
+            throw new Error(
+              `pty-host protocol mismatch: host=${hello.protocolVersion} client=${PROTOCOL_VERSION}`
+            );
+          }
+          client2.hostPid = hello.pid;
+          client2.connected = true;
+          await client2.seedFromHost();
+          settled = true;
+          clearTimeout(timer);
+          resolve(client2);
+        } catch (err) {
+          settled = true;
+          clearTimeout(timer);
+          try {
+            sock.destroy();
+          } catch {
+          }
+          reject(err);
+        }
+      });
+    });
+  }
+  wireSocket(sock) {
+    sock.on("data", (chunk) => {
+      const frames = this.decoder.push(chunk);
+      if (this.decoder.desynced) {
+        this.handleSocketError(new Error("pty-host stream desync"));
+        return;
+      }
+      for (const frame of frames) this.handleHostMessage(frame);
+    });
+    sock.on("close", () => {
+      if (this.connected) {
+        this.connected = false;
+        this.emit("error", new Error("pty-host connection closed"));
+      }
+    });
+  }
+  handleSocketError(err) {
+    if (!this.connected) return;
+    this.connected = false;
+    this.emit("error", err);
+  }
+  handleHostMessage(msg) {
+    switch (msg.kind) {
+      case "data": {
+        const entry = this.mirror.get(msg.id);
+        if (entry) {
+          const next = entry.scrollback + msg.data;
+          entry.scrollback = next.length > SCROLLBACK_MAX2 ? next.slice(-SCROLLBACK_MAX2) : next;
+        }
+        this.emit("data", msg.id, msg.data);
+        return;
+      }
+      case "exit": {
+        this.mirror.delete(msg.id);
+        this.retained.delete(msg.id);
+        this.emit("exit", msg.id, {
+          exitCode: msg.exitCode,
+          signal: msg.signal
+        });
+        return;
+      }
+      default: {
+        const seq = msg.seq;
+        if (seq != null) {
+          const resolver = this.pending.get(seq);
+          if (resolver) {
+            this.pending.delete(seq);
+            resolver(msg);
+          }
+        }
+      }
+    }
+  }
+  nextSeq() {
+    return ++this.seq;
+  }
+  /** Send a request and await the correlated reply. */
+  request(msg) {
+    return new Promise((resolve, reject) => {
+      if (!this.socket) {
+        reject(new Error("pty-host not connected"));
+        return;
+      }
+      this.pending.set(msg.seq, resolve);
+      try {
+        this.socket.write(encodeFrame(msg));
+      } catch (err) {
+        this.pending.delete(msg.seq);
+        reject(err);
+      }
+    });
+  }
+  /** Fire-and-forget send for messages with no reply (write/resize/kill/…). */
+  send(msg) {
+    if (!this.socket) return;
+    try {
+      this.socket.write(encodeFrame(msg));
+    } catch {
+    }
+  }
+  /** Seed the local mirror from the host's live ptys after a (re)connect. */
+  async seedFromHost() {
+    const listed = await this.request({
+      kind: "list",
+      seq: this.nextSeq()
+    });
+    for (const t of listed.terminals) {
+      const sb = await this.request({
+        kind: "get-scrollback",
+        seq: this.nextSeq(),
+        id: t.id
+      });
+      this.mirror.set(t.id, {
+        pid: t.pid,
+        shell: t.shell,
+        scrollback: sb.scrollback ?? ""
+      });
+    }
+  }
+  /** Ids the host currently has live — used by the lifecycle layer to drive
+   *  the reattach (renderer remounts these specs, replaying host scrollback). */
+  liveIds() {
+    return Array.from(this.mirror.keys());
+  }
+  isConnected() {
+    return this.connected;
+  }
+  /** Disconnect WITHOUT killing host ptys (before-quit leave-running). */
+  disconnect() {
+    this.connected = false;
+    if (this.socket) {
+      try {
+        this.socket.end();
+      } catch {
+      }
+      this.socket = null;
+    }
+  }
+  // --- PtyBackend ---------------------------------------------------------
+  create(opts) {
+    const existing = this.mirror.get(opts.id);
+    if (existing) {
+      return {
+        id: opts.id,
+        pid: existing.pid,
+        shell: existing.shell,
+        existing: true,
+        scrollback: existing.scrollback
+      };
+    }
+    this.mirror.set(opts.id, { pid: 0, shell: opts.shell ?? "", scrollback: "" });
+    this.request({ kind: "create", seq: this.nextSeq(), opts }).then((reply) => {
+      if (reply.kind !== "created") return;
+      const entry = this.mirror.get(opts.id);
+      if (entry) {
+        entry.pid = reply.result.pid;
+        entry.shell = reply.result.shell;
+      }
+    }).catch(() => {
+    });
+    const snap = this.snapshots.readSnapshot(opts.id);
+    return {
+      id: opts.id,
+      pid: 0,
+      shell: opts.shell ?? "",
+      existing: false,
+      scrollback: "",
+      snapshot: snap ?? void 0
+    };
+  }
+  write(id, data) {
+    if (!this.mirror.has(id)) return false;
+    this.send({ kind: "write", id, data });
+    return true;
+  }
+  resize(id, cols, rows) {
+    if (!this.mirror.has(id)) return false;
+    this.send({
+      kind: "resize",
+      id,
+      cols: Math.max(1, cols | 0),
+      rows: Math.max(1, rows | 0)
+    });
+    return true;
+  }
+  kill(id) {
+    const had = this.mirror.delete(id);
+    this.retained.delete(id);
+    this.send({ kind: "kill", id });
+    return had;
+  }
+  /**
+   * 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() {
+  }
+  list() {
+    return Array.from(this.mirror.entries()).map(([id, e]) => ({
+      id,
+      pid: e.pid,
+      shell: e.shell
+    }));
+  }
+  isLive(id) {
+    return this.mirror.has(id);
+  }
+  setRetained(id, retained) {
+    if (retained) this.retained.add(id);
+    else this.retained.delete(id);
+    this.send({ kind: "set-retained", id, retained });
+  }
+  isRetained(id) {
+    return this.retained.has(id);
+  }
+  retainedCount() {
+    return this.retained.size;
+  }
+  retainedIds() {
+    return Array.from(this.retained);
+  }
+  getScrollback(id) {
+    return this.mirror.get(id)?.scrollback;
+  }
+};
+
+// src/host-lifecycle.ts
+var deps = null;
+function configureHostLifecycle(d) {
+  deps = d;
+}
+var client = null;
+var usingHost = false;
+function status(message, level = "warn") {
+  deps?.onHostStatus({ message, level });
+}
+function detachedEnabled() {
+  try {
+    return deps?.settings.get("detached_terminals") === "on";
+  } catch {
+    return false;
+  }
+}
+function isHostBacked() {
+  return usingHost && !!client && client.isConnected();
+}
+function getHostClient() {
+  return client;
+}
+async function awaitUsableHost(userData, timeoutMs = 4e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const pf = readPidfile(userData);
+    if (pidfileUsable(pf)) return true;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return false;
+}
+async function initTerminalBackend() {
+  setActiveBackend(inProcessBackend());
+  if (!deps || !detachedEnabled()) {
+    return { host: false, reattachIds: [] };
+  }
+  const { spawner, snapshots } = deps;
+  const userData = spawner.userDataDir();
+  try {
+    const hostScript = spawner.resolveHostScript();
+    let pf = readPidfile(userData);
+    if (!pidfileUsable(pf)) {
+      deletePidfile(userData);
+      if (!hostScript) {
+        status(
+          "Detached terminals unavailable (host not found) \u2014 using in-process. Sessions won't survive a full quit."
+        );
+        return { host: false, reattachIds: [] };
+      }
+      spawner.spawnDetached(hostScript, { GENIE_USERDATA: userData });
+      const up = await awaitUsableHost(userData);
+      if (!up) {
+        status(
+          "Detached terminals unavailable (host didn't start) \u2014 using in-process. Sessions won't survive a full quit."
+        );
+        return { host: false, reattachIds: [] };
+      }
+      pf = readPidfile(userData);
+    }
+    if (!pf) {
+      status(
+        "Detached terminals unavailable \u2014 using in-process. Sessions won't survive a full quit."
+      );
+      return { host: false, reattachIds: [] };
+    }
+    client = await HostClient.connect(pf.socketPath, snapshots);
+    client.on("error", onHostError);
+    setActiveBackend(client);
+    usingHost = true;
+    return { host: true, reattachIds: client.liveIds() };
+  } catch (err) {
+    console.error("[host-lifecycle] falling back to in-process:", err);
+    try {
+      client?.disconnect();
+    } catch {
+    }
+    client = null;
+    usingHost = false;
+    setActiveBackend(inProcessBackend());
+    status(
+      "Detached terminals unavailable \u2014 using in-process. Sessions won't survive a full quit."
+    );
+    return { host: false, reattachIds: [] };
+  }
+}
+function onHostError(err) {
+  if (!usingHost) return;
+  console.error("[host-lifecycle] host connection lost:", err.message);
+  usingHost = false;
+  client = null;
+  setActiveBackend(inProcessBackend());
+  status(
+    "Detached terminal host stopped \u2014 switched to in-process. Open terminals may need reopening."
+  );
+}
+function disconnectHostLeaveRunning() {
+  if (client) {
+    try {
+      client.disconnect();
+    } catch {
+    }
+  }
+}
+function ptyHostScriptPath() {
+  const here = typeof __dirname !== "undefined" ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+  return resolveHostScript(here) ?? path.join(here, "pty-host.js");
+}
+
+export { HostClient, configureHostLifecycle, configureInProcessBackend, createSnapshotStore, cwdHookEnv, cwdHookSpawn, defaultShell, defaultShellId, detectShells, disconnectHostLeaveRunning, getHostClient, inProcessBackend, initTerminalBackend, isHostBacked, parseCommandLine, parseFileUrl, ptyHostScriptPath, resolveDefaultShell, scanOsc7Cwd, setActiveBackend, shellKind, subscribeBackendEvents, terminalManager };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map