@fnclaude/cli 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnclaude/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "fnclaude CLI implementation (TypeScript rewrite, in progress)",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.98.0"
+    "@anthropic-ai/sdk": "^0.98.0",
+    "node-pty": "1.1.0"
   }
 }

package/src/index.ts

@@ -78,3 +78,20 @@ export {
   transferDenyBareOK,
   transferDenyFlags,
 } from './args/preserve.js';
+
+// PTY runner + shared helpers (ring buffer, cross-cwd detection,
+// reconstructArgv, ensureCWD).
+export {
+  clearScreen,
+  crossCwdRe,
+  detectCrossCwd,
+  ensureCWD,
+  RING_BUFFER_SIZE,
+  reconstructArgv,
+  RingBuffer,
+  runWithPTY,
+  type CrossCwdMatch,
+  type EnsureCWDHandle,
+  type RunOptions,
+  type RunResult,
+} from './pty.js';

package/src/pty/unix.ts

@@ -0,0 +1,278 @@
+/**
+ * Unix PTY runner — spawn claude under a node-pty pseudo-terminal, tee its
+ * output to stdout + a ring buffer, forward stdin / SIGWINCH, integrate the
+ * AF_UNIX socket listener for handoff, and return the exit code + tail +
+ * (optional) handoff argv.
+ *
+ * Ported from src/pty_run_unix.go in the Go reference (fnclaude@fnrhombus).
+ *
+ * Library choice: `node-pty` (Microsoft, MIT, currently v1.1.0). Verified
+ * to load under Bun 1.3.x via the N-API compat layer — both spawn() and the
+ * onData/onExit/kill surface work as documented. There's no native Bun PTY
+ * primitive yet; if/when Bun ships one, this file is the natural place to
+ * swap implementations behind the shared RunOptions API.
+ */
+
+import { spawn as ptySpawn, type IPty } from 'node-pty';
+import { envFromConfig } from '../config.js';
+import { handoffEnv } from '../handoff.js';
+import { SocketListener } from '../mcp/socketListener.js';
+import {
+  ensureCWD,
+  RING_BUFFER_SIZE,
+  RingBuffer,
+  type RunOptions,
+  type RunResult,
+} from '../pty.js';
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+/** Convert a `KEY=VALUE` string array into the object shape node-pty wants. */
+function envArrayToObject(
+  base: NodeJS.ProcessEnv,
+  extras: readonly string[],
+): { [k: string]: string | undefined } {
+  // Start from the inherited env. Last-wins, so extras override on
+  // duplicate keys (matches Go's append semantics in exec.Command).
+  const out: { [k: string]: string | undefined } = { ...base };
+  for (const kv of extras) {
+    const eq = kv.indexOf('=');
+    if (eq < 0) continue;
+    out[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+  return out;
+}
+
+function getTerminalSize(): { cols: number; rows: number } {
+  // node:tty `WriteStream` exposes columns/rows when stdout is a TTY.
+  const cols = process.stdout.columns ?? 80;
+  const rows = process.stdout.rows ?? 24;
+  return { cols, rows };
+}
+
+function isTTY(stream: { isTTY?: boolean }): boolean {
+  return stream.isTTY === true;
+}
+
+// ── runWithPTY ─────────────────────────────────────────────────────────────
+
+export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
+  const { claudeArgv, launchCWD, cfg, handoff } = opts;
+
+  // claudeArgv[0] is the conventional program name and is ignored — node-pty
+  // takes file + args separately (mirrors exec.Command).
+  if (claudeArgv.length === 0) {
+    process.stderr.write('fnclaude: empty argv passed to runWithPTY\n');
+    return { exitCode: 1, tail: null, handoffArgv: null };
+  }
+
+  // Build the env. Order matches Go: os env → exec.env → handoff env.
+  // Last-wins on dupes, so handoff env beats user-supplied dupes.
+  const envExtras: string[] = [...envFromConfig(cfg)];
+  if (handoff !== null) {
+    envExtras.push(...handoffEnv(handoff.mode, handoff.socketPath));
+  }
+  const childEnv = envArrayToObject(process.env, envExtras);
+
+  // Start the AF_UNIX listener BEFORE the child so the socket is ready the
+  // moment claude (and thus the `fnclaude mcp` subprocess) starts. On
+  // listener-startup failure we abort the run — handoff is core behavior,
+  // not optional.
+  let listener: SocketListener | null = null;
+  if (handoff !== null) {
+    try {
+      listener = await SocketListener.start({
+        spec: handoff,
+        cfg,
+        launchCWD,
+        origArgs: handoff.originalArgs,
+      });
+    } catch (err) {
+      process.stderr.write(
+        `fnclaude: socket listener failed to start: ${(err as Error).message}\n`,
+      );
+      return { exitCode: 1, tail: null, handoffArgv: null };
+    }
+  }
+
+  // Resuming a session whose stored cwd no longer exists used to surface as
+  // a misleading ENOENT-against-claude-binary. Fabricate the tree before
+  // spawn, then immediately unwind it once claude has chdir'd in.
+  let cleanupCWD: (() => Promise<void>) | null = null;
+  try {
+    const h = await ensureCWD(launchCWD);
+    cleanupCWD = h.cleanup;
+  } catch (err) {
+    process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
+    if (listener !== null) await listener.close();
+    return { exitCode: 1, tail: null, handoffArgv: null };
+  }
+
+  // Spawn under the PTY.
+  const { cols, rows } = getTerminalSize();
+  let pty: IPty;
+  try {
+    pty = ptySpawn(claudeArgv[0] as string, claudeArgv.slice(1), {
+      name: process.env.TERM ?? 'xterm-256color',
+      cols,
+      rows,
+      cwd: launchCWD,
+      env: childEnv,
+      encoding: null, // emit raw Buffers so the ring tail is byte-accurate
+    });
+  } catch (err) {
+    if (cleanupCWD !== null) await cleanupCWD().catch(() => undefined);
+    if (listener !== null) await listener.close();
+    process.stderr.write(
+      `fnclaude: failed to start claude with PTY: ${(err as Error).message}\n`,
+    );
+    return { exitCode: 1, tail: null, handoffArgv: null };
+  }
+
+  // Unwind any fabricated cwd tree now that the child has been spawned —
+  // claude's kernel cwd is held by inode reference, so the path on disk
+  // is no longer load-bearing.
+  if (cleanupCWD !== null) {
+    try {
+      await cleanupCWD();
+    } catch (err) {
+      process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
+    }
+  }
+
+  // Put the controlling terminal into raw mode so the PTY behaves
+  // transparently (key-by-key, no local echo, etc.).
+  let restoreRaw: (() => void) | null = null;
+  if (isTTY(process.stdin)) {
+    const stdinRaw = process.stdin;
+    const wasRaw = stdinRaw.isRaw;
+    try {
+      stdinRaw.setRawMode(true);
+      restoreRaw = () => {
+        try {
+          stdinRaw.setRawMode(wasRaw);
+        } catch {
+          // best-effort — terminal may already be torn down
+        }
+      };
+    } catch {
+      // not a real TTY in some test harnesses — skip raw mode silently
+    }
+  }
+
+  // Ring buffer for post-exit cross-cwd scanning.
+  const ring = new RingBuffer(RING_BUFFER_SIZE);
+
+  // Tee PTY output → stdout + ring buffer. node-pty with encoding:null
+  // emits Buffer chunks; the type declaration still says string, but at
+  // runtime it's Buffer when encoding is null (the lib's docstring is
+  // explicit on this).
+  pty.onData((chunk: unknown) => {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string);
+    ring.write(buf);
+    process.stdout.write(buf);
+  });
+
+  // Forward SIGWINCH (terminal resize) to the PTY. Listener is detached in
+  // the finally block.
+  const onWinch = (): void => {
+    const sz = getTerminalSize();
+    try {
+      pty.resize(sz.cols, sz.rows);
+    } catch {
+      // ignore — child may have already exited
+    }
+  };
+  process.on('SIGWINCH', onWinch);
+
+  // Pump stdin → PTY master. We only forward when stdin is a real TTY —
+  // otherwise (test harness, piped invocation, headless run) we don't want
+  // to drain a non-TTY stdin pipe which could close the PTY prematurely.
+  // We attach a 'data' handler rather than pipe() so we can detach cleanly
+  // on exit without destroying stdin (which would leak into the parent's
+  // post-PTY state).
+  let onStdinData: ((chunk: Buffer) => void) | null = null;
+  if (isTTY(process.stdin)) {
+    onStdinData = (chunk: Buffer): void => {
+      try {
+        pty.write(chunk);
+      } catch {
+        // child gone — ignore
+      }
+    };
+    process.stdin.on('data', onStdinData);
+    if (typeof process.stdin.resume === 'function') process.stdin.resume();
+  }
+
+  // Handoff: when the listener fires triggered(), terminate claude.
+  // SIGTERM + brief grace + SIGKILL mirrors the legacy SIGUSR1 path
+  // — the listener marks "switch fired" and the parent gets out of
+  // the PTY loop ASAP.
+  let handoffKillTimer: NodeJS.Timeout | null = null;
+  if (listener !== null) {
+    void listener.triggered().then(() => {
+      try {
+        pty.kill('SIGTERM');
+      } catch {
+        // ignore
+      }
+      handoffKillTimer = setTimeout(() => {
+        try {
+          pty.kill('SIGKILL');
+        } catch {
+          // ignore
+        }
+      }, 200);
+    });
+  }
+
+  // Wait for the child to exit. Use a one-shot guard so we capture only
+  // the FIRST exit event — node-pty under Bun has been observed to emit
+  // a follow-up `exit` for the previous pty when a new one is started in
+  // the same process, which would pollute the next call's result.
+  const exitResult = await new Promise<{ exitCode: number; signal?: number }>(
+    (resolve) => {
+      let fired = false;
+      const disposable = pty.onExit((e) => {
+        if (fired) return;
+        fired = true;
+        disposable.dispose();
+        resolve(e);
+      });
+    },
+  );
+
+  // Tear down listeners / restore terminal state.
+  process.off('SIGWINCH', onWinch);
+  if (onStdinData !== null) {
+    process.stdin.off('data', onStdinData);
+    if (typeof process.stdin.pause === 'function') process.stdin.pause();
+  }
+  if (restoreRaw !== null) restoreRaw();
+  if (handoffKillTimer !== null) clearTimeout(handoffKillTimer);
+
+  // node-pty's exit shape: { exitCode, signal? }.
+  //
+  // Under Node: exitCode is set when the child exited normally; signal is
+  // set (with the signal number) when terminated by a signal. We could map
+  // signal-death to POSIX's `128 + signal`.
+  //
+  // Under Bun (1.3.x), node-pty's `signal` field is unreliable — observed
+  // value `1` on both normal exits AND deliberate SIGTERM kills, so we
+  // can't trust it to distinguish "exited normally" from "killed". The
+  // safest cross-runtime answer is to use `exitCode` as truth: it tracks
+  // the real exit code on both runtimes, and on signal-death it reports
+  // 0 (which is the correct "process didn't choose its exit code" answer).
+  //
+  // Callers that need to know "was this a handoff kill?" should inspect
+  // `handoffArgv !== null` (the listener's stash), not the exit code.
+  const exitCode = exitResult.exitCode;
+
+  let handoffArgv: string[] | null = null;
+  if (listener !== null) {
+    handoffArgv = listener.getHandoffArgv();
+    await listener.close();
+  }
+
+  return { exitCode, tail: ring.bytes(), handoffArgv };
+}

package/src/pty/windows.ts

@@ -0,0 +1,124 @@
+/**
+ * Windows PTY runner — Windows stub. No PTY allocation, no ring-buffer
+ * scanning. claude is spawned with inherited stdio and the result tail is
+ * null so detectCrossCwd never matches — cross-cwd-resume is a no-op on
+ * Windows for now.
+ *
+ * Auto-handoff parity is implemented here in the same shape as Unix: when
+ * `handoff` is set, fnclaude starts the AF_UNIX socket listener before
+ * spawning claude and injects FNCLAUDE_HANDOFF / FNC_SOCKET into the child
+ * env. Node's `net.createServer` over an AF_UNIX path works on Windows 10
+ * build 17063+. When the listener fires triggered, the parent kills claude.
+ *
+ * Ported from src/pty_run_windows.go in the Go reference (fnclaude@fnrhombus).
+ */
+
+import { spawn as childSpawn } from 'node:child_process';
+import { envFromConfig } from '../config.js';
+import { handoffEnv } from '../handoff.js';
+import { SocketListener } from '../mcp/socketListener.js';
+import { ensureCWD, type RunOptions, type RunResult } from '../pty.js';
+
+export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
+  const { claudeArgv, launchCWD, cfg, handoff } = opts;
+  if (claudeArgv.length === 0) {
+    process.stderr.write('fnclaude: empty argv passed to runWithPTY\n');
+    return { exitCode: 1, tail: null, handoffArgv: null };
+  }
+
+  // Build env. Order matches Unix: os env → exec.env → handoff env;
+  // last-wins on dupes.
+  const envExtras: string[] = [...envFromConfig(cfg)];
+  if (handoff !== null) {
+    envExtras.push(...handoffEnv(handoff.mode, handoff.socketPath));
+  }
+  const childEnv: NodeJS.ProcessEnv = { ...process.env };
+  for (const kv of envExtras) {
+    const eq = kv.indexOf('=');
+    if (eq < 0) continue;
+    childEnv[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+
+  // Start the AF_UNIX listener before the child.
+  let listener: SocketListener | null = null;
+  if (handoff !== null) {
+    try {
+      listener = await SocketListener.start({
+        spec: handoff,
+        cfg,
+        launchCWD,
+        origArgs: handoff.originalArgs,
+      });
+    } catch (err) {
+      process.stderr.write(
+        `fnclaude: socket listener failed to start: ${(err as Error).message}\n`,
+      );
+      return { exitCode: 1, tail: null, handoffArgv: null };
+    }
+  }
+
+  // Fabricate the cwd tree if missing. Windows can't safely tear the cwd
+  // out from under a running child the way Unix can; defer the cleanup
+  // until the child exits.
+  let cleanupCWD: (() => Promise<void>) | null = null;
+  try {
+    const h = await ensureCWD(launchCWD);
+    cleanupCWD = h.cleanup;
+  } catch (err) {
+    process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
+    if (listener !== null) await listener.close();
+    return { exitCode: 1, tail: null, handoffArgv: null };
+  }
+
+  let exitCode = 0;
+  try {
+    const child = childSpawn(claudeArgv[0] as string, claudeArgv.slice(1), {
+      cwd: launchCWD,
+      env: childEnv,
+      stdio: 'inherit',
+      // On Windows, this matches Go's exec.Command default — no shell.
+      shell: false,
+    });
+
+    // Handoff: when the listener fires, kill the child. Windows doesn't
+    // honor SIGTERM/SIGKILL through Node's signal API; child.kill() maps
+    // to TerminateProcess which is the closest equivalent.
+    if (listener !== null) {
+      void listener.triggered().then(() => {
+        try {
+          child.kill();
+        } catch {
+          // ignore
+        }
+      });
+    }
+
+    exitCode = await new Promise<number>((resolve) => {
+      child.on('exit', (code, signal) => {
+        if (code !== null) resolve(code);
+        else if (signal !== null) resolve(1);
+        else resolve(0);
+      });
+      child.on('error', (err) => {
+        process.stderr.write(`fnclaude: failed to start claude: ${err.message}\n`);
+        resolve(1);
+      });
+    });
+  } finally {
+    if (cleanupCWD !== null) {
+      try {
+        await cleanupCWD();
+      } catch (err) {
+        process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
+      }
+    }
+  }
+
+  let handoffArgv: string[] | null = null;
+  if (listener !== null) {
+    handoffArgv = listener.getHandoffArgv();
+    await listener.close();
+  }
+
+  return { exitCode, tail: null, handoffArgv };
+}

package/src/pty.ts

@@ -0,0 +1,337 @@
+/**
+ * Shared PTY scaffolding — RingBuffer, cross-cwd detection regex,
+ * reconstructArgv helper, ensureCWD safety wrapper, and the platform-
+ * dispatching `runWithPTY` entry point.
+ *
+ * Ported from src/pty_run.go in the Go reference (fnclaude@fnrhombus).
+ *
+ * Platform-specific spawn lives in:
+ *   - src/pty/unix.ts    — node-pty under POSIX
+ *   - src/pty/windows.ts — direct child_process.spawn, no PTY (stub)
+ */
+
+import { mkdir, rmdir, stat } from 'node:fs/promises';
+import type { Stats } from 'node:fs';
+import { dirname } from 'node:path';
+import type { Config } from './config.js';
+import type { HandoffSpec } from './handoff.js';
+import { isFlag, isMagicWord, preserveArgs, splitLeadingMagic } from './args/preserve.js';
+
+// ── RingBuffer ─────────────────────────────────────────────────────────────
+
+/**
+ * Capacity of the PTY output tail kept for the post-exit cross-cwd scan.
+ *
+ * Sized to comfortably hold the cross-cwd message plus all the screen-cleanup
+ * escapes claude emits while tearing down its TUI on exit. An earlier 4 KB
+ * value was just big enough for the original captured fixture but failed in
+ * the wild when claude 2.1.143 emitted more trailing cleanup before exit —
+ * the message rotated out of the tail and the intercept silently failed.
+ */
+export const RING_BUFFER_SIZE = 64 * 1024;
+
+/**
+ * Fixed-capacity circular byte buffer. Writes that overflow the capacity
+ * discard the oldest data. Only the most recent `cap` bytes are kept, which
+ * is all we need for post-exit pattern scanning.
+ *
+ * Implementation note: backed by a Node Buffer (vs Uint8Array) so the
+ * outbound `bytes()` slice is already in the form that node:net /
+ * RegExp.exec(buffer.toString('utf8' | 'binary')) callers expect.
+ */
+export class RingBuffer {
+  private readonly buf: Buffer;
+  readonly cap: number;
+  private pos = 0;
+  private full = false;
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new RangeError(`RingBuffer capacity must be a positive integer, got ${capacity}`);
+    }
+    this.cap = capacity;
+    this.buf = Buffer.alloc(capacity);
+  }
+
+  /** Append data, dropping oldest bytes when full. */
+  write(p: Buffer | Uint8Array | string): void {
+    const data = typeof p === 'string' ? Buffer.from(p) : Buffer.from(p);
+    if (data.length === 0) return;
+    // Hot path for small writes: per-byte loop matches Go's reference impl.
+    // For large writes (> cap) skip ahead so we don't churn over discarded
+    // bytes that will immediately be overwritten.
+    let start = 0;
+    if (data.length > this.cap) {
+      start = data.length - this.cap;
+      this.full = true;
+      this.pos = 0;
+    }
+    for (let i = start; i < data.length; i++) {
+      this.buf[this.pos] = data[i] as number;
+      this.pos = (this.pos + 1) % this.cap;
+      if (this.pos === 0) this.full = true;
+    }
+  }
+
+  /** Return ring contents in chronological order (oldest first). */
+  bytes(): Buffer {
+    if (!this.full) {
+      return Buffer.from(this.buf.subarray(0, this.pos));
+    }
+    return Buffer.concat([
+      this.buf.subarray(this.pos),
+      this.buf.subarray(0, this.pos),
+    ]);
+  }
+}
+
+// ── cross-cwd detection ────────────────────────────────────────────────────
+
+/**
+ * Matches the cd-and-resume line claude prints when the selected session
+ * belongs to a different directory. SOURCE OF TRUTH — keep byte-for-byte
+ * identical to src/pty_run.go's `crossCwdRe`.
+ *
+ * We can't anchor on the "This conversation is from a different directory."
+ * preamble: claude's TUI emits cursor-right escapes (e.g. `\x1b[1C`) between
+ * words instead of literal spaces, so that sentence is never plain-text in
+ * the PTY stream. The "To resume, run:" line, by contrast, is rendered as
+ * plain ASCII with real spaces, as is the `cd <path> && claude --resume <uuid>`
+ * command — both anchors survive the TUI rendering intact.
+ *
+ * The `[\s\S]*?` between anchors swallows whatever ANSI / CR / cursor-move
+ * goo appears between the two lines (varies by terminal width and TUI
+ * layout — observed: `\x1b[K\r\x1b[1C\x1b[1B`).
+ */
+export const crossCwdRe =
+  /To resume, run:[\s\S]*?cd (\S+) && claude --resume ([0-9a-fA-F-]{36})/g;
+
+export interface CrossCwdMatch {
+  dest: string;
+  uuid: string;
+}
+
+/**
+ * Scan `tail` for the cross-cwd redirect message. Returns null when no
+ * match is found. When multiple matches appear (unlikely but defensive),
+ * the LAST match wins.
+ */
+export function detectCrossCwd(tail: Buffer): CrossCwdMatch | null {
+  // Reset regex internal state — crossCwdRe is `g`-flagged.
+  crossCwdRe.lastIndex = 0;
+  // Decode as Latin-1 so every byte maps to a code unit; the regex matches
+  // ASCII anchors so the multi-byte representation of any non-ASCII bytes
+  // never participates in a match. This is the JS equivalent of Go's
+  // []byte-scanning behavior.
+  const s = tail.toString('latin1');
+  let last: RegExpExecArray | null = null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: standard regex loop
+  for (let m: RegExpExecArray | null; (m = crossCwdRe.exec(s)) !== null; ) {
+    last = m;
+  }
+  if (last === null) return null;
+  return { dest: last[1]!, uuid: last[2]! };
+}
+
+// ── reconstructArgv ────────────────────────────────────────────────────────
+
+/**
+ * Build the new fnclaude argument list when silently relaunching after a
+ * cross-cwd session resume.
+ *
+ * `origArgs` is `process.argv.slice(2)` from the original invocation.
+ * `dest` is the destination directory extracted from claude's message;
+ * `uuid` is the session id to resume.
+ *
+ * Algorithm (delegated to preserveArgs): keep leading magic words, strip
+ * positional path tokens, keep everything from the first flag onward (no
+ * denylist — cross-cwd resume preserves all flags).
+ *
+ * Result: preserved_magic + [dest] + ["--resume", uuid] + rest.
+ *
+ * Note: if the original argv already contained --resume / -r / --continue /
+ * -c, the picker wouldn't have been shown, the cross-cwd pattern wouldn't
+ * have been emitted, and this function wouldn't be called. No special-case
+ * is needed for those flags.
+ */
+export function reconstructArgv(
+  origArgs: readonly string[],
+  dest: string,
+  uuid: string,
+): string[] {
+  const preserved = preserveArgs(origArgs, null, null);
+  const { magic, rest } = splitLeadingMagic(preserved);
+  return [...magic, dest, '--resume', uuid, ...rest];
+}
+
+// Re-export magic helpers so callers can do everything via the pty module.
+export { isFlag, isMagicWord, splitLeadingMagic };
+
+// ── clearScreen ────────────────────────────────────────────────────────────
+
+/**
+ * Write the ANSI escape sequence that clears the screen and moves the
+ * cursor to the top-left. Called before relaunching to hide the brief
+ * flicker of the "different directory" message that already scrolled to
+ * the terminal before we detected it.
+ */
+export function clearScreen(out: NodeJS.WriteStream = process.stdout): void {
+  out.write('\x1b[2J\x1b[H');
+}
+
+// ── ensureCWD ──────────────────────────────────────────────────────────────
+
+export interface EnsureCWDHandle {
+  /**
+   * Best-effort tear-down of any directory tree fabricated by ensureCWD.
+   * Walks back through the dirs we created (deepest first). A dir that
+   * was already removed by something else is treated as success
+   * (postcondition already satisfied). A dir that's unexpectedly
+   * non-empty surfaces as a thrown error.
+   */
+  cleanup(): Promise<void>;
+}
+
+/**
+ * Guarantee `dir` exists at the moment of process spawn.
+ *
+ * Motivation: when fnclaude resumes a session whose stored cwd no longer
+ * exists on disk, the kernel returns ENOENT during exec — but Node /
+ * Bun formats that against the binary path ("ENOENT … spawn …"), which
+ * falsely blames the claude binary. The fix is to ensure the cwd exists
+ * before spawn. When it doesn't, we fabricate the full tree, then
+ * IMMEDIATELY unwind it after the child has been spawned — once claude
+ * has chdir'd into the dir its kernel cwd is held by inode reference and
+ * the path on disk is no longer needed.
+ *
+ * If the path exists but isn't a directory, ensureCWD rejects without
+ * touching the filesystem. If the path doesn't exist and an ancestor is
+ * a file, ensureCWD likewise rejects without touching the filesystem.
+ */
+export async function ensureCWD(dir: string): Promise<EnsureCWDHandle> {
+  let info: Stats | null = null;
+  try {
+    info = await stat(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+  if (info !== null) {
+    if (!info.isDirectory()) {
+      throw new Error(`session cwd ${dir} exists but is not a directory`);
+    }
+    return { cleanup: async () => undefined };
+  }
+
+  // Walk up to find the deepest pre-existing ancestor, recording every
+  // missing level shallowest-first. We mkdir each level explicitly (rather
+  // than calling mkdir({recursive: true})) so cleanup only touches dirs
+  // we actually created.
+  const missing: string[] = [];
+  let p = dir;
+  for (;;) {
+    missing.unshift(p);
+    const parent = dirname(p);
+    if (parent === p) {
+      throw new Error(`session cwd ${dir} does not exist and has no existing ancestor`);
+    }
+    let parentInfo: Stats | null = null;
+    try {
+      parentInfo = await stat(parent);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+    if (parentInfo !== null) {
+      if (!parentInfo.isDirectory()) {
+        throw new Error(
+          `session cwd ${dir} cannot be created: ancestor ${parent} is not a directory`,
+        );
+      }
+      break;
+    }
+    p = parent;
+  }
+
+  const created: string[] = []; // shallowest-first; cleanup reverses
+  for (const level of missing) {
+    try {
+      await mkdir(level, { mode: 0o755 });
+    } catch (err) {
+      // Roll back what we already created so we leave the filesystem
+      // exactly as we found it.
+      for (let i = created.length - 1; i >= 0; i--) {
+        try {
+          await rmdir(created[i]!);
+        } catch {
+          // best-effort
+        }
+      }
+      throw new Error(
+        `session cwd ${dir} does not exist and could not be created: ${(err as Error).message}`,
+      );
+    }
+    created.push(level);
+  }
+
+  return {
+    cleanup: async () => {
+      for (let i = created.length - 1; i >= 0; i--) {
+        const level = created[i]!;
+        try {
+          // rmdir() — non-recursive — so a non-empty dir surfaces as an
+          // error rather than nuking unexpected content.
+          await rmdir(level);
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException).code;
+          if (code === 'ENOENT') continue; // already gone — fine
+          throw new Error(`could not clean up auto-created ${level}: ${(err as Error).message}`);
+        }
+      }
+    },
+  };
+}
+
+// ── runWithPTY ─────────────────────────────────────────────────────────────
+
+/**
+ * Result returned by `runWithPTY`. `tail` is the ring buffer contents at
+ * the moment the child exited; `handoffArgv` is populated only when the
+ * socket listener fired `triggered()` and stashed a relaunch argv.
+ *
+ * On Windows the tail is null (no PTY, no ring buffer, cross-cwd-resume
+ * is a no-op).
+ */
+export interface RunResult {
+  exitCode: number;
+  tail: Buffer | null;
+  handoffArgv: string[] | null;
+}
+
+export interface RunOptions {
+  /**
+   * argv to invoke. claudeArgv[0] is conventionally the program name and
+   * is ignored by the spawn; claudeArgv.slice(1) is passed as positional
+   * args to the child.
+   */
+  claudeArgv: string[];
+  launchCWD: string;
+  cfg: Config;
+  /** Null disables handoff (no env injection, no listener). */
+  handoff: HandoffSpec | null;
+}
+
+/**
+ * Spawn claude under a PTY (POSIX) or with inherited stdio (Windows),
+ * starting the AF_UNIX listener first when `handoff` is set so the socket
+ * is ready the moment the child starts.
+ *
+ * The implementation lives in pty/unix.ts or pty/windows.ts; this is the
+ * dispatcher.
+ */
+export async function runWithPTY(opts: RunOptions): Promise<RunResult> {
+  if (process.platform === 'win32') {
+    const mod = await import('./pty/windows.js');
+    return mod.runWithPTY(opts);
+  }
+  const mod = await import('./pty/unix.js');
+  return mod.runWithPTY(opts);
+}