@fnclaude/cli 1.1.0 → 2.0.0

package/src/main.ts

@@ -1,477 +1,620 @@
-// Port of run() + main() from src/main.go (Go reference).
+// `fnc`: launch `claude` in the resolved cwd (or the noop fallback when
+// no positional was given). Bun-only (top-level await, Bun.spawn).
 //
-// The integration layer. Composes the already-ported modules into the
-// fnclaude orchestration loop:
-//
-//   1. Parse argv (with --help / --version / `mcp` subcommand short-circuits)
-//   2. Resolve user-typed cwd into an absolute path (path + repo lookups)
-//   3. Apply -w worktree intercept (may swap cwd to an existing worktree)
-//   4. Auto-name if the invocation qualifies (--, prompt, no --name, etc.)
-//   5. Sanitize any --name / -n values to a path-safe slug
-//   6. Build the claude argv (extra-dirs, self-MCP, auto-tmux, prompts)
-//   7. Spawn claude under a PTY with the AF_UNIX socket listener active
-//   8. On exit:
-//        - If the listener fired (auto-handoff): silentRelaunchHandoff
-//        - Else if claude printed a cross-cwd marker: silentRelaunch
-//        - Else: propagate claude's exit code
+// This file is the launcher entry. Argv parsing, path resolution, and
+// feature transforms live in their own modules under src/; main composes
+// them in order.
 
+import { realpathSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import process from 'node:process';
-import { isAbsolute, join } from 'node:path';
-import {
-  defaultLlmClient,
-  claudeCliFn,
-  extractPrompt,
-  generateName,
-  shouldAutoName,
-  type LlmClientFn,
-} from './autoname.js';
-import { parseArgs } from './argParser.js';
-import {
-  brandResolved,
-  withPassthroughUpdate,
-  withResolved,
-  type InterceptedArgs,
-  type ResolvedArgs,
-} from './args.js';
-import { buildArgv } from './argv.js';
-import { loadConfig, type Config } from './config.js';
-import { handoffSocketPath, type HandoffSpec } from './handoff.js';
-import { helpText, version, wantsHelp, wantsVersion } from './help.js';
-import { loadHostAliases } from './hostAliases.js';
-import { expandTildePath } from './paths.js';
-import { loadPrompts, type PromptSet } from './prompts.js';
-import { detectCrossCwd, runWithPTY } from './pty.js';
-import { loadRepoSettings } from './repoSettings.js';
-import { Resolve, type RepoSettings, type ResolveDeps } from './resolver.js';
-import { sanitizeNamesInPassthrough } from './sanitize.js';
-import { runMCPServer } from './mcp/client.js';
-import { seedNoop } from './noop.js';
-import { silentRelaunch, silentRelaunchHandoff } from './silentRelaunch.js';
-import { applyWorktreeIntercept, type GitRunner } from './worktree.js';
-import { flushWarnings } from './warnings.js';
-import { errorMessage } from './errors.js';
-
-/**
- * `RunIO` — process-shaped seams. Streams, paths, the launch environment,
- * and the external behaviour the pipeline depends on (claude binary
- * lookup, PTY runner, relaunch, MCP dispatcher, noop seeder, autoname
- * LLM call). Plus the *inner* dependency seams of the pipeline modules
- * themselves — `gitRunner` (consumed by applyWorktreeIntercept) and
- * `resolveDeps` (consumed by Resolve) — surfaced here so tests can swap
- * the I/O each module does without a wrapper layer of outer functions.
- *
- * Earlier shape had both outer (`RunDeps.applyWorktreeIntercept`) and
- * inner (`applyWorktreeIntercept`'s `GitRunner` parameter) seams for the
- * same boundary. Collapsed to the inner seam only — the outer one was
- * dead weight in production (the function never varies) and in tests it
- * just wrapped the inner seam with two extra lines of closure plumbing.
- */
-export interface RunIO {
-  /** Source argv (typically `process.argv.slice(2)`). */
-  argv?: readonly string[];
-  /** Stream where the help/version/error text is written. */
-  stdout?: NodeJS.WriteStream;
-  stderr?: NodeJS.WriteStream;
-  /** User's home directory. */
-  home?: string;
-  /** Shell cwd at startup. */
-  cwd?: string;
-
-  /** PATH lookup for the claude binary; returns undefined when not found. */
-  lookupClaude?: (name: string) => string | undefined;
-  /** Override the run-with-pty step. */
-  runWithPTY?: typeof runWithPTY;
-  /** Override the silent-relaunch step (cross-cwd resume). */
-  silentRelaunch?: typeof silentRelaunch;
-  /** Override the silent-relaunch-handoff step. */
-  silentRelaunchHandoff?: typeof silentRelaunchHandoff;
-  /** Override runMCPServer (the `mcp` subcommand dispatcher). */
-  runMCPServer?: typeof runMCPServer;
-  /** Override seedNoop (best-effort dir seeder). */
-  seedNoop?: typeof seedNoop;
-  /** Override generateName for auto-name (skip the LLM call). */
-  generateName?: typeof generateName;
-
-  /**
-   * GitRunner for applyWorktreeIntercept. Tests that want to drive a
-   * fake `git worktree list` reply pass one here; production uses the
-   * module's `defaultGitRunner`.
-   */
-  gitRunner?: GitRunner;
-
-  /**
-   * Resolver I/O seams (path-exists check, gh CLI, clone). Tests pass a
-   * stub set so the resolver runs without touching the network or
-   * filesystem; production uses `productionDeps()` from resolver.ts.
-   */
-  resolveDeps?: ResolveDeps;
+import { dirname, join } from 'node:path';
+
+import { readArgv } from './argv/intake.ts';
+import { expandAliases } from './argv/expand.ts';
+import { parseArgs } from './argv/parse.ts';
+import { expandShortFlags } from './argv/short-flags.ts';
+import { loadConfig } from './config/load.ts';
+import { reexecSelf, startHandoffAwaiter } from './handoff/awaiter.ts';
+import { handoffTrigger } from './handoff/trigger.ts';
+import { getVersion, helpText, wantsHelp, wantsVersion } from './help-version.ts';
+import { composeEnv } from './launch/compose-env.ts';
+import { decideCrossCwdRelaunch } from './launch/cross-cwd-relaunch.ts';
+import { findClaude } from './launch/find-claude.ts';
+import { readLivePermissionMode } from './launch/live-permission-reader.ts';
+import { RingBuffer } from './launch/ring-buffer.ts';
+import { isMcpSubcommand, parseMcpFlags, runMcpServer } from './mcp/dispatch.ts';
+import { handleCopyToClipboard } from './mcp/handlers/clipboard.ts';
+import { createRestartHandler } from './mcp/handlers/restart.ts';
+import { createSpawnHandler } from './mcp/handlers/spawn.ts';
+import { createSwitchHandler } from './mcp/handlers/switch.ts';
+import { injectMcpConfig } from './mcp/inject-config.ts';
+import { startMcpListener } from './mcp/listener.ts';
+import { createParentDispatcher, stubParentHandlers } from './mcp/parent-dispatch.ts';
+import { computeSocketPath } from './mcp/socket-path.ts';
+import { autoName, shouldAutoName } from './name/auto-name.ts';
+import { AUTO_NAME_MODEL, AUTO_NAME_SYSTEM_PROMPT } from './name/llm-prompt.ts';
+import { sanitizeForPath } from './name/sanitize.ts';
+import { sdkLlmCall } from './name/sdk-llm.ts';
+import { findPromptSentinel, promptBody } from './argv/sentinel.ts';
+import { seedNoopDir } from './noop/seed.ts';
+import { resolveTemplateSourcePath } from './noop/template-source.ts';
+import { ensureCwd } from './path/ensure-cwd.ts';
+import { resolvePromptsDir } from './prompts/dir.ts';
+import { injectFragments, loadFragments } from './prompts/load.ts';
+import { isInteractiveSession, selectFragments } from './prompts/select.ts';
+import { buildCloneUrl, computeCloneDestination } from './repo/clone.ts';
+import { cloneRepo } from './repo/clone-exec.ts';
+import { runGhApi, runGhClone } from './repo/gh-runner.ts';
+import { loadHostAliases } from './repo/host-aliases.ts';
+import { findOwner } from './repo/owner-lookup.ts';
+import { loadRepoSettings } from './repo/repo-settings.ts';
+import { resolveInput } from './repo/resolve-input.ts';
+import { createWarningBuffer } from './warnings/buffer.ts';
+import { shouldInjectTmux } from './worktree/auto-tmux.ts';
+import { listWorktrees } from './worktree/git-list.ts';
+import { applyWorktreeIntercept } from './worktree/intercept.ts';
+
+const argv = readArgv();
+
+// Non-fatal warnings accumulate here; we flush after claude exits so the
+// user actually sees them. Terminal errors (the `exit(2)` / `exit(127)`
+// paths below) bypass the buffer and write straight to stderr — they're
+// the reason we're not launching, not background noise. Design: §27.
+const warnings = createWarningBuffer();
+
+// Internal test hook: dump raw argv before any other work. Lets e2e tests
+// verify the preflight + intake chain preserves `--` without spawning anything.
+if (process.env.FNC_INTERNAL_DUMP_ARGV === '1') {
+  process.stdout.write(`${JSON.stringify(argv)}\n`);
+  process.exit(0);
+}
+
+if (wantsHelp(argv)) {
+  process.stdout.write(helpText);
+  process.exit(0);
+}
+
+if (wantsVersion(argv)) {
+  const version = await getVersion();
+  process.stdout.write(`fnc ${version}\n`);
+  process.exit(0);
 }
 
-/**
- * `RunConfig` — pre-loaded data the pipeline reads. When a field is
- * supplied here, the corresponding loader (loadConfig / loadPrompts /
- * loadRepoSettings / loadHostAliases) is skipped and the supplied value
- * is used directly. Tests build a hermetic config payload up-front; in
- * production every field is omitted and the loaders run for real.
- *
- * These were previously expressed as `loadConfig: typeof loadConfig`
- * function seams in the unified `RunDeps`. The 1:1 thin-wrapper pattern
- * was double-injection — in production they have zero variance, and in
- * tests they were always loader stubs that returned a fixed payload.
- * Storing the payload directly removes a layer of function plumbing.
- */
-export interface RunConfig {
-  /** Pre-loaded config. Omit to call `loadConfig()`. */
-  config?: Config;
-  /** Pre-loaded prompts. Omit to call `loadPrompts()`. */
-  prompts?: PromptSet;
-  /** Pre-loaded repo settings. Omit to call `loadRepoSettings(home, cwd)`. */
-  repoSettings?: RepoSettings;
-  /** Pre-loaded host aliases. Omit to call `loadHostAliases(home)`. */
-  hostAliases?: Record<string, string>;
+if (isMcpSubcommand(argv)) {
+  const exitCode = await runMcpServer(parseMcpFlags(argv.slice(1)));
+  process.exit(exitCode);
 }
 
-/**
- * Top-level deps for `run()` — two named groups (`io` and `data`),
- * each optional, each with optional fields. Tests typically populate
- * only the fields they care about. Production omits everything (passes
- * `{}` or nothing) and lets every default kick in.
- */
-export interface RunDeps {
-  /** Process-shaped seams (streams, env, external behaviours). */
-  io?: RunIO;
-  /** Pre-loaded data payloads (skips the corresponding loaders). */
-  data?: RunConfig;
+// Parse argv into structured launcher inputs. Magic positionals, fnclaude-eaten
+// flags, subcommands, and the passthrough split happen here.
+const parsed = parseArgs(argv);
+if (!parsed.ok) {
+  process.stderr.write(`${parsed.error}\n`);
+  process.exit(2);
 }
 
-/**
- * Read the user's argv, preferring `FNC_ARGS_JSON` over `process.argv`.
- *
- * The umbrella shim (packages/fnclaude/bin/fnc.js) sets `FNC_ARGS_JSON`
- * on the env it spawns Bun with, because Bun strips the first `--`
- * from a script's argv (confirmed empirically across `bun script.js`,
- * `bun --`, `bun run`, and shebang invocations). Passing user args via
- * the env var sidesteps that — Bun never sees them as its own argv.
- *
- * We DELETE the var after consumption so any child processes the cli
- * spawns (claude, gh, the relaunch chain) don't inherit a stale value.
- *
- * Defensive: malformed or wrong-shape values fall through to
- * `process.argv.slice(2)` rather than throwing — a corrupted env var
- * shouldn't break the cli, just degrade to the pre-fix behaviour.
- */
-function readArgvFromEnvOrProcess(): readonly string[] {
-  const envArgs = process.env.FNC_ARGS_JSON;
-  if (envArgs !== undefined) {
-    delete process.env.FNC_ARGS_JSON;
-    try {
-      const parsed: unknown = JSON.parse(envArgs);
-      if (
-        Array.isArray(parsed) &&
-        parsed.every((x): x is string => typeof x === 'string')
-      ) {
-        return parsed;
+// Load fnclaude config (auto.tmux + other settings the launcher consults).
+const HOME = homedir();
+const shellCwd = process.cwd();
+const configBase = process.env.XDG_CONFIG_HOME ?? join(HOME, '.config');
+const config = await loadConfig({ path: join(configBase, 'fnclaude', 'config.toml') });
+
+// Load settings before resolution. Resolution-time settings only need user +
+// managed tiers (project/local require knowing projectRoot, which only matters
+// after launch). The managed-settings path is Linux-only for now; macOS &
+// Windows resolution to come.
+const settings = loadRepoSettings({
+  userPath: join(HOME, '.claude', 'settings.json'),
+  projectPath: join(shellCwd, '.claude', 'settings.json'),
+  localPath: join(shellCwd, '.claude', 'settings.local.json'),
+  managedPath: '/etc/claude-code/managed-settings.json',
+});
+const hostAliases = loadHostAliases({
+  systemPath: '/usr/share/fnrhombus/host-aliases.json',
+  userPath: join(HOME, '.local', 'share', 'fnrhombus', 'host-aliases.json'),
+});
+
+// Resolve the first positional (path or repo ref) to a launch cwd. The
+// resolver handles path short-circuit (/, ~, ~/) AND repo-ref refs whose owner
+// is already known (URL forms, owner/name, name@owner, gh:owner/name). Bare
+// names and clone execution route through the gh-CLI branches below; ambiguous
+// matches surface a clean error.
+const resolved = resolveInput({
+  input: parsed.firstPath,
+  shellCwd,
+  home: HOME,
+  xdgConfigHome: process.env.XDG_CONFIG_HOME,
+  settings: { cloneTemplate: settings.cloneTemplate, hostAliases },
+});
+
+let cwd: string;
+let usedNoopFallback = false;
+let workspaceFromRef = '';
+switch (resolved.kind) {
+  case 'launch':
+    cwd = resolved.launchCwd;
+    usedNoopFallback = resolved.usedNoopFallback;
+    workspaceFromRef = resolved.workspace;
+    if (usedNoopFallback) {
+      await mkdir(cwd, { recursive: true });
+      // Seed handoff.template.md on first noop-fallback launches (design.md
+      // §19). Resolves the template source from <exe-dir> sibling layouts
+      // and only copies if dest is missing — never clobbers an existing
+      // hand-edited template. Failures here don't block the launch.
+      const binPathForSeed = process.argv[1] ?? '';
+      const exeDirForSeed = binPathForSeed !== '' ? dirname(realpathSync(binPathForSeed)) : process.cwd();
+      const tmplSource = resolveTemplateSourcePath({
+        envOverride: process.env.FNC_NOOP_TEMPLATE_PATH,
+        exeDir: exeDirForSeed,
+      });
+      await seedNoopDir({ noopDir: cwd, templateSourcePath: tmplSource.path });
+    }
+    break;
+  case 'needs-clone': {
+    // Repo ref resolved cleanly but the destination doesn't exist on disk.
+    // Clone it, then launch in the new directory.
+    process.stderr.write(`fnclaude: cloning ${resolved.url} → ${resolved.destination}\n`);
+    const cloneR = await cloneRepo({
+      url: resolved.url,
+      destination: resolved.destination,
+      ghClone: runGhClone,
+      mkdirp: async (path) => {
+        await mkdir(path, { recursive: true });
+      },
+    });
+    if (!cloneR.ok) {
+      process.stderr.write(`fnclaude: ${cloneR.error}\n`);
+      process.exit(2);
+    }
+    cwd = resolved.destination;
+    workspaceFromRef = resolved.workspace;
+    break;
+  }
+  case 'needs-owner-lookup': {
+    // Bare-name ref — ask gh which org owns a repo by this name, then
+    // re-route through the resolver as if owner had been on the input.
+    const ownerR = await findOwner({ name: resolved.name, ghApi: runGhApi });
+    if (!ownerR.ok) {
+      if (ownerR.reason === 'gh-failed') {
+        process.stderr.write(
+          `fnclaude: bare name "${resolved.name}" — gh CLI lookup failed (not authenticated? no network?). Try \`gh auth login\` or pass owner explicitly (\`${resolved.name}@<owner>\` or \`<owner>/${resolved.name}\`).\n`,
+        );
+      } else {
+        process.stderr.write(
+          `fnclaude: no repo named "${resolved.name}" found under your gh user or any of your orgs.\n`,
+        );
       }
-    } catch {
-      // Fall through to process.argv.
+      process.exit(2);
+    }
+    // Build a synthetic ref for the resolved owner and recompute destination.
+    const syntheticRef = {
+      host: '',
+      owner: ownerR.owner,
+      name: resolved.name,
+      workspace: resolved.workspace,
+      original: resolved.name,
+    };
+    if (settings.cloneTemplate === '') {
+      process.stderr.write(
+        `fnclaude: cloneTemplate is not configured in repoSettings; cannot resolve bare-name refs.\n`,
+      );
+      process.exit(2);
+    }
+    const destR = computeCloneDestination({
+      ref: syntheticRef,
+      template: settings.cloneTemplate,
+      hostAliases,
+      home: HOME,
+    });
+    if (!destR.ok) {
+      process.stderr.write(`fnclaude: ${destR.error}\n`);
+      process.exit(2);
+    }
+    // If the destination already exists, just launch there. Otherwise clone.
+    const { existsSync } = await import('node:fs');
+    if (existsSync(destR.path)) {
+      cwd = destR.path;
+      workspaceFromRef = resolved.workspace;
+      break;
     }
+    const url = buildCloneUrl(syntheticRef);
+    process.stderr.write(`fnclaude: cloning ${url} → ${destR.path}\n`);
+    const cloneR = await cloneRepo({
+      url,
+      destination: destR.path,
+      ghClone: runGhClone,
+      mkdirp: async (path) => {
+        await mkdir(path, { recursive: true });
+      },
+    });
+    if (!cloneR.ok) {
+      process.stderr.write(`fnclaude: ${cloneR.error}\n`);
+      process.exit(2);
+    }
+    cwd = destR.path;
+    workspaceFromRef = resolved.workspace;
+    break;
+  }
+  case 'ambiguous': {
+    const both = resolved.cloneDestination ?? resolved.repoRef ?? '?';
+    process.stderr.write(
+      `fnclaude: ambiguous reference — could be the local directory ${resolved.path} OR ${both}. Disambiguate by typing './<name>' for the local path.\n`,
+    );
+    process.exit(2);
   }
-  return process.argv.slice(2);
+  case 'error':
+    process.stderr.write(`fnclaude: ${resolved.error}\n`);
+    process.exit(2);
 }
 
-function lookupClaudeFromPath(name: string): string | undefined {
-  // Bun's PATH lookup: Bun.which() returns null when not found. Coerce to
-  // undefined to keep the absent-value sentinel consistent with the rest of
-  // the codebase.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const bunWhich = (globalThis as any).Bun?.which;
-  if (typeof bunWhich === 'function') {
-    return bunWhich(name) ?? undefined;
-  }
-  // Fallback: walk PATH ourselves. Avoid `which` shell-out — synchronous and
-  // brittle. Use spawnSync('which', [name]) only if Bun.which is unavailable
-  // and we're not on Windows.
-  return undefined;
+// Worktree intercept: when -w <name> is set, possibly swap cwd to an
+// existing worktree's path. The intercept also pushes `--worktree`/`--name`
+// into passthrough as appropriate per spec §10.
+//
+// `+workspace` suffix on a repo ref (parsed by resolveInput) feeds into here
+// as if the user had typed `-w <workspace>` — but explicit `-w` always wins.
+const effectiveWorktreeSet = parsed.worktreeSet || workspaceFromRef !== '';
+const effectiveWorktreeArg = parsed.worktreeSet ? parsed.worktreeArg : workspaceFromRef;
+const intercept = applyWorktreeIntercept({
+  worktreeSet: effectiveWorktreeSet,
+  worktreeArg: effectiveWorktreeArg,
+  launchCwd: cwd,
+  passthrough: parsed.passthrough,
+  listWorktrees,
+});
+for (const w of intercept.warnings) warnings.add(w);
+cwd = intercept.launchCwd;
+const parsedWithIntercept = { ...parsed, passthrough: intercept.passthrough };
+
+// Build the final claude argv: prepend magic-captured flags (model/effort/
+// subcommand), then expand any short-flag clusters in the passthrough.
+const withAliases = expandAliases(parsedWithIntercept);
+const shortExpanded = expandShortFlags(withAliases);
+if (!shortExpanded.ok) {
+  process.stderr.write(`${shortExpanded.error}\n`);
+  process.exit(2);
 }
+let claudeArgs = shortExpanded.tokens;
 
-/**
- * The main run loop. Returns the integer exit code that the caller should
- * pass to `process.exit`. Never calls `process.exit` itself — that's left
- * to `main()` so tests can introspect the return value.
- *
- * On the silent-relaunch paths (cross-cwd resume or auto-handoff), the
- * silentRelaunch* implementations replace the process image on POSIX and
- * therefore never return. On any failure mode of the relaunch, we fall
- * through to returning claude's exit code, mirroring Go's behavior.
- */
-export async function run(deps: RunDeps = {}): Promise<number> {
-  const io = deps.io ?? {};
-  const data = deps.data ?? {};
-
-  const argv = io.argv ?? readArgvFromEnvOrProcess();
-  const stdout = io.stdout ?? process.stdout;
-  const stderr = io.stderr ?? process.stderr;
-  const home = io.home ?? process.env.HOME ?? homedir();
-  const shellCWD = io.cwd ?? process.cwd();
-  const lookupClaude = io.lookupClaude ?? lookupClaudeFromPath;
-  const runPTY = io.runWithPTY ?? runWithPTY;
-  const relaunch = io.silentRelaunch ?? silentRelaunch;
-  const relaunchHandoff = io.silentRelaunchHandoff ?? silentRelaunchHandoff;
-  const seedNoopFn = io.seedNoop ?? seedNoop;
-  const generateNameFn = io.generateName ?? generateName;
-  const runMCPServerFn = io.runMCPServer ?? runMCPServer;
-
-  // Defer-flush warnings on exit, AFTER claude has finished and the user is
-  // back at their shell. The silent-relaunch path uses execve which skips
-  // this defer; that's intentional — the relaunched fnclaude will re-emit
-  // any warnings that still apply.
-  //
-  // Loaders (loadConfig / loadRepoSettings / loadHostAliases / loadPrompts)
-  // and other setup steps return their warnings; we accumulate them in this
-  // local list and drain it via flushWarnings at the deferred-flush point.
-  // No module-global sink — keeps tests hermetic.
-  const warnings: string[] = [];
-  let flushed = false;
-  const flushOnce = (): void => {
-    if (flushed) return;
-    flushed = true;
-    flushWarnings(warnings, stderr);
+// Auto-tmux: if config has auto.tmux = "worktree" AND this is a brand-new
+// worktree (worktreeSet + no match) AND user didn't opt out, inject --tmux.
+if (
+  shouldInjectTmux({
+    configAutoTmux: config.autoTmux,
+    worktreeSet: parsed.worktreeSet,
+    worktreeMatched: intercept.worktreeMatched,
+    noTmux: parsed.noTmux,
+    passthrough: claudeArgs,
+  })
+) {
+  claudeArgs = [...claudeArgs, '--tmux'];
+}
+
+// Auto-name: when the user has typed a prompt body via `--` and hasn't given
+// --name / -n (and the session isn't print/resume/continue/from-pr), generate
+// a session name. Spec defaults: 15s timeout, heuristic fallback on error/
+// timeout. When ANTHROPIC_API_KEY is set we hit the API via the SDK directly
+// (saves a claude cold-start); otherwise we shell out to `claude -p`.
+//
+// FNC_INTERNAL_DISABLE_AUTONAME=1 is an internal test escape — when set,
+// autoName is skipped entirely so e2e tests don't have to wait on a real
+// claude -p call (and don't see --name pollute their assertion shapes).
+if (process.env.FNC_INTERNAL_DISABLE_AUTONAME !== '1' && shouldAutoName(parsedWithIntercept)) {
+  const sentinelIdx = findPromptSentinel(parsedWithIntercept.passthrough);
+  const body = promptBody(parsedWithIntercept.passthrough, sentinelIdx).join(' ').trim();
+  const claudePLlmCall = async (prompt: string): Promise<string> => {
+    const proc = Bun.spawn(
+      ['claude', '-p', '--model', AUTO_NAME_MODEL, `${AUTO_NAME_SYSTEM_PROMPT}\n\nUser request: ${prompt}`],
+      { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
+    );
+    const out = await new Response(proc.stdout).text();
+    const exit = await proc.exited;
+    if (exit !== 0) throw new Error(`claude -p exited ${exit}`);
+    return out;
   };
+  const llmCall = process.env.ANTHROPIC_API_KEY !== undefined ? sdkLlmCall : claudePLlmCall;
+  const generated = await autoName({ prompt: body, llmCall, timeoutMs: 15_000 });
+  const san = sanitizeForPath(generated);
+  const final = san.kind === 'invalid' ? generated : san.value;
+  claudeArgs = [...claudeArgs, '--name', final];
+}
 
-  try {
-    // ── --help / --version short-circuits (mirror Go's run()). ────────────
-    if (wantsHelp(argv)) {
-      stdout.write(helpText);
-      return 0;
-    }
-    if (wantsVersion(argv)) {
-      stdout.write(`fnclaude ${version}\n`);
-      return 0;
-    }
+// Inject prompt fragments via --append-system-prompt. Selection depends on
+// noop fallback + interactive (non-print) state of the session.
+const fragmentNames = selectFragments({ usedNoopFallback, passthrough: claudeArgs });
+if (fragmentNames.length > 0) {
+  // process.argv[1] is the BIN script (bin/fnc.js after preflight, or whatever
+  // node invoked). Realpath it so symlinked installs (npm's .bin/ → package
+  // bin/) resolve to the actual layout. The "prompts" directory candidates
+  // (../prompts, ../share/...) are sibling-relative to that resolved bin.
+  const binPath = process.argv[1] ?? '';
+  const exeDir = binPath !== '' ? dirname(realpathSync(binPath)) : process.cwd();
+  const promptsDir = resolvePromptsDir({
+    envOverride: process.env.FNC_PROMPTS_DIR,
+    exeDir,
+  });
+  if (promptsDir.dir !== null) {
+    const loaded = loadFragments(fragmentNames, promptsDir.dir);
+    for (const w of loaded.warnings) warnings.add(w);
+    claudeArgs = injectFragments(claudeArgs, loaded.content);
+  } else if (promptsDir.warning !== undefined) {
+    warnings.add(promptsDir.warning);
+  }
+}
 
-    // ── `fnclaude mcp` subcommand dispatch. ──────────────────────────────
-    if (argv.length >= 1 && argv[0] === 'mcp') {
-      let noop = false;
-      for (const a of argv.slice(1)) {
-        if (a === '--noop') noop = true;
-      }
-      return await runMCPServerFn({
-        noop,
-        stdin: process.stdin,
-        stdout: process.stdout,
-        socketPath: process.env.FNC_SOCKET ?? '',
-      });
-    }
+// Compute the MCP socket path. On Unix this also feeds FNC_SOCKET into
+// the child env so the MCP subprocess (which claude spawns per the
+// injected --mcp-config) knows where to dial. On win32, AF_UNIX over
+// Bun.listen({ unix }) isn't supported yet — skip the socket entirely
+// so the launcher still works without self-MCP.
+let mcpSocketPath: string | undefined;
+let mcpListenerStop: (() => Promise<void>) | undefined;
+if (process.platform !== 'win32') {
+  mcpSocketPath = computeSocketPath({
+    env: process.env,
+    pid: process.pid,
+    platform: process.platform,
+  });
+}
 
-    // ── Parse fnclaude's own argv. ────────────────────────────────────────
-    let parsed;
-    try {
-      parsed = parseArgs(argv, home);
-    } catch (err) {
-      stderr.write(`${errorMessage(err)}\n`);
-      return 1;
-    }
+// Compose the child env: process.env → [exec.env] from config → FNCLAUDE_HANDOFF
+// → FNC_SOCKET. Later entries win against same-name earlier entries per
+// design.md §5.
+const childEnv = composeEnv({
+  processEnv: process.env,
+  execEnv: config.execEnv,
+  handoff: config.autoHandoff,
+  socket: mcpSocketPath,
+});
 
-    // ── Seed the noop dir iff fallback was used. ─────────────────────────
-    if (parsed.usedNoopFallback) {
-      try {
-        await seedNoopFn(parsed.cwd);
-      } catch (err) {
-        warnings.push(`fnclaude: noop seed failed: ${errorMessage(err)}`);
-      }
-    }
+// Self-MCP --mcp-config injection (§7.4). Skipped when there's no socket
+// to dial back to (win32 — no listener), and gated to interactive
+// sessions per design.md §29. The fnc bin is realpath'd so symlinked
+// installs (npm's .bin/) resolve to the actual layout; process.execPath
+// is the bun runtime that will exec the subprocess script. Decision: bun
+// + script-path is a two-element shape because fnc.js is a bun script,
+// not a self-contained binary — see decisions.md 2026-05-27 entry.
+if (mcpSocketPath !== undefined) {
+  const binPathForMcp = process.argv[1] ?? '';
+  const fncBin = binPathForMcp !== '' ? realpathSync(binPathForMcp) : '';
+  claudeArgs = injectMcpConfig({
+    claudeArgs,
+    bunExec: process.execPath,
+    fncBin,
+    noop: usedNoopFallback,
+    interactive: isInteractiveSession(claudeArgs),
+  });
+}
 
-    // ── Config: pre-loaded or freshly loaded from disk. ──────────────────
-    let cfg: Config;
-    if (data.config !== undefined) {
-      cfg = data.config;
-    } else {
-      const loaded = loadConfig();
-      cfg = loaded.config;
-      warnings.push(...loaded.warnings);
+// Internal test hook: dump the launch plan as JSON and exit 0 BEFORE spawning
+// claude. Lets e2e tests verify the full pipeline composition (cwd + final
+// claude args) without needing a real claude on PATH or a fake-claude harness.
+if (process.env.FNC_INTERNAL_DUMP_PLAN === '1') {
+  // Dump only env values fnclaude actively manages (handoff/socket + execEnv
+  // keys) to keep the dump small and predictable in tests. The full process
+  // env would leak shell state into snapshots.
+  const dumpEnv: Record<string, string> = {};
+  if (config.execEnv !== undefined) {
+    for (const k of Object.keys(config.execEnv)) {
+      if (k in childEnv) dumpEnv[k] = childEnv[k]!;
     }
+  }
+  if ('FNCLAUDE_HANDOFF' in childEnv) dumpEnv.FNCLAUDE_HANDOFF = childEnv.FNCLAUDE_HANDOFF!;
+  if ('FNC_SOCKET' in childEnv) dumpEnv.FNC_SOCKET = childEnv.FNC_SOCKET!;
+  process.stdout.write(
+    `${JSON.stringify({ cwd, claudeArgs, usedNoopFallback, env: dumpEnv })}\n`,
+  );
+  process.exit(0);
+}
 
-    // ── Repo-reference resolver (path-or-repo two-lookup). ───────────────
-    //
-    // Produces a `ResolvedArgs` either way — the resolver path overwrites
-    // cwd (and possibly worktreeSet/worktreeArg), the tilde-only path
-    // expands cwd, and the absolute-path / noop-fallback path stamps the
-    // existing fields straight through.
-    let resolved: ResolvedArgs;
-    if (
-      !parsed.usedNoopFallback &&
-      parsed.cwd !== '' &&
-      !isAbsolute(parsed.cwd) &&
-      !parsed.cwd.startsWith('~')
-    ) {
-      let rs: RepoSettings;
-      if (data.repoSettings !== undefined) {
-        rs = data.repoSettings;
-      } else {
-        const loaded = loadRepoSettings(home, shellCWD);
-        rs = loaded.settings;
-        warnings.push(...loaded.warnings);
-      }
-      let aliases: Record<string, string>;
-      if (data.hostAliases !== undefined) {
-        aliases = data.hostAliases;
-      } else {
-        const loaded = loadHostAliases(home);
-        aliases = loaded.aliases;
-        warnings.push(...loaded.warnings);
-      }
-      let result;
-      try {
-        // Resolver's inner deps (path-exists, gh CLI, clone): use the
-        // injected ones in tests, fall back to productionDeps in real
-        // runs. Passing `undefined` lets Resolve default-construct
-        // productionDeps() itself.
-        result = await (io.resolveDeps
-          ? Resolve(
-              {
-                input: parsed.cwd,
-                cwd: shellCWD,
-                home,
-                settings: rs,
-                hostAliases: aliases,
-              },
-              io.resolveDeps,
-            )
-          : Resolve({
-              input: parsed.cwd,
-              cwd: shellCWD,
-              home,
-              settings: rs,
-              hostAliases: aliases,
-            }));
-      } catch (err) {
-        stderr.write(`${errorMessage(err)}\n`);
-        return 1;
-      }
-      // If the user's reference had a +workspace suffix AND they didn't
-      // pass -w explicitly, propagate the workspace to the intercept
-      // layer.
-      const promoteWorkspace = !!result.workspace && !parsed.worktreeSet;
-      resolved = withResolved(parsed, {
-        cwd: result.path,
-        ...(promoteWorkspace
-          ? { worktreeSet: true, worktreeArg: result.workspace! }
-          : {}),
-      });
-    } else if (parsed.cwd.startsWith('~')) {
-      // Tilde-expand absolute-shaped inputs that didn't go through the
-      // resolver (resolver expands tildes for its short-circuit path, but
-      // it isn't called for tilde-prefixed inputs here).
-      resolved = withResolved(parsed, { cwd: expandTildePath(parsed.cwd) });
-    } else {
-      resolved = brandResolved(parsed);
-    }
+// Verify claude is on PATH before doing any spawn-time setup. Failing here
+// gives a far better error than Bun.spawn's bare ENOENT.
+const claudeBin = findClaude({ pathEnv: process.env.PATH ?? '' });
+if (!claudeBin.ok) {
+  process.stderr.write(`${claudeBin.error}\n`);
+  process.exit(127);
+}
 
-    // ── -w / --worktree intercept. ───────────────────────────────────────
+// Bind the MCP listener (Unix only). Must happen BEFORE Bun.spawn so the
+// subprocess claude launches per --mcp-config can dial back over
+// $FNC_SOCKET. Bind failure is fatal per Go canonical — we can't run
+// without it once tools are wired (§8). design.mcp.md §2.1.
+if (mcpSocketPath !== undefined) {
+  try {
+    // §7.7 + §8.x: wire per-tool dispatch onto each accepted socket.
+    // §8.1 (restart), §8.2 (switch), §8.3 (spawn) and §8.4 (clipboard)
+    // replace their stubs; nothing remains stubbed in §8.
     //
-    // GitRunner is the inner seam — production uses the module's default
-    // (synchronous `git -C <dir> ...`); tests inject a stub that yields
-    // the fake `git worktree list --porcelain` shape they want.
-    const intercepted = io.gitRunner
-      ? applyWorktreeIntercept(resolved, shellCWD, io.gitRunner)
-      : applyWorktreeIntercept(resolved, shellCWD);
-
-    // ── Resolve the launch cwd relative to shell cwd. ────────────────────
-    const launchCWD = isAbsolute(intercepted.cwd)
-      ? intercepted.cwd
-      : join(shellCWD, intercepted.cwd);
-
-    // ── Auto-name if qualifying. ──────────────────────────────────────────
-    let named: InterceptedArgs = intercepted;
-    if (shouldAutoName(named.passthrough)) {
-      const prompt = extractPrompt(named.passthrough);
-      const apiKey = process.env.ANTHROPIC_API_KEY ?? '';
-      const llmFn: LlmClientFn = apiKey
-        ? defaultLlmClient(apiKey)
-        : claudeCliFn(cfg.name.model);
-      const name = await generateNameFn(prompt, cfg.name, apiKey, llmFn);
-      named = withPassthroughUpdate(named, {
-        passthrough: ['--name', name, ...named.passthrough],
-      });
-    }
-
-    // ── Sanitize any --name / -n value to a path-safe slug. ──────────────
-    const sanitizeResult = sanitizeNamesInPassthrough(named.passthrough);
-    warnings.push(...sanitizeResult.warnings);
-    const sanitized = withPassthroughUpdate(named, {
-      passthrough: sanitizeResult.args,
+    // Live permission-mode reader binds `cwd` (the launch cwd) at
+    // construction so both handlers consume the same
+    // `(sessionId) => string | null` shape. Reads claude's
+    // `~/.claude/projects/<encoded-cwd>/<sid>.jsonl` for the latest
+    // `{type:"permission-mode",...}` record — last-wins, null on miss.
+    const livePermissionModeReader = (sessionId: string): string | null =>
+      readLivePermissionMode(cwd, sessionId);
+    const restartHandler = createRestartHandler({
+      origArgs: argv,
+      launchCWD: cwd,
+      trigger: handoffTrigger,
+      livePermissionModeReader,
+    });
+    const switchHandler = createSwitchHandler({
+      origArgs: argv,
+      trigger: handoffTrigger,
+      livePermissionModeReader,
+    });
+    const binPathForListener = process.argv[1] ?? '';
+    const fncBinAbs = binPathForListener !== '' ? realpathSync(binPathForListener) : '';
+    const spawnHandler = createSpawnHandler({
+      config: { autoSpawnCommand: config.autoSpawnCommand },
+      processEnv: process.env,
+      fncBinPath: fncBinAbs,
+      handleCopyToClipboard,
     });
+    const dispatcher = createParentDispatcher({
+      handlers: {
+        ...stubParentHandlers,
+        restart: restartHandler,
+        switch: switchHandler,
+        spawn: spawnHandler,
+        copy_to_clipboard: handleCopyToClipboard,
+      },
+    });
+    const listener = await startMcpListener({
+      socketPath: mcpSocketPath,
+      onConnection: dispatcher,
+    });
+    mcpListenerStop = listener.stop;
+  } catch (err) {
+    process.stderr.write(`fnclaude: ${(err as Error).message}\n`);
+    process.exit(2);
+  }
+}
 
-    // ── Build the claude argv. ───────────────────────────────────────────
-    let prompts: PromptSet;
-    if (data.prompts !== undefined) {
-      prompts = data.prompts;
-    } else {
-      const loaded = loadPrompts();
-      prompts = loaded.prompts;
-      warnings.push(...loaded.warnings);
-    }
+// Fabricate the cwd tree if missing — Bun.spawn would otherwise return ENOENT
+// blaming the claude binary. The cleanup() unlinks any fabricated dirs right
+// after spawn, since the kernel holds the cwd by inode reference once the
+// child has chdir'd (which posix_spawn does before returning to us).
+const ensured = ensureCwd(cwd);
+if (!ensured.ok) {
+  process.stderr.write(`fnclaude: ${ensured.error}\n`);
+  process.exit(2);
+}
 
-    const claudeArgv = buildArgv(sanitized, shellCWD, cfg, prompts);
+// §9.0: spawn claude via Bun.Terminal on POSIX so the launcher can tee PTY
+// output through a ring buffer for cross-cwd resume detection (§9.1+). On
+// Windows we fall back to stdio inherit until Bun.Terminal lands on win32.
+// Non-TTY contexts (piped stdin, FNC_INTERNAL_DUMP_PLAN tests) also use the
+// inherit shape — raw-mode forwarding requires a real terminal anyway.
+const useTerminal =
+  process.platform !== 'win32' &&
+  process.stdin.isTTY === true &&
+  process.stdout.isTTY === true;
 
-    // ── Verify claude is on PATH before starting the PTY. ────────────────
-    if (lookupClaude('claude') === undefined) {
-      stderr.write(`fnclaude: claude not found in PATH\n`);
-      return 1;
-    }
+// Kernel routes Ctrl-C to the whole foreground pgrp; claude handles its
+// own SIGINT. Swallow it here so fnc survives to read claude's exit code.
+// Under Bun.Terminal the parent isn't in the same pgrp as the child, so
+// these handlers mostly cover the inherit branch — harmless either way.
+process.on('SIGINT', () => {});
+process.on('SIGTERM', () => {});
 
-    // ── Build the auto-handoff spec. ─────────────────────────────────────
-    const hspec: HandoffSpec = {
-      mode: cfg.auto.handoff,
-      socketPath: handoffSocketPath(process.pid),
-      originalArgs: [...argv],
-    };
+// §9.1: capture the tail of PTY output for §9.2's cross-cwd detection.
+// Hoisted here so it stays reachable after `proc.exited` resolves below.
+// Only meaningful on the useTerminal branch; under stdio inherit the
+// buffer stays empty and post-exit consumers will simply see no match.
+const ringBuffer = new RingBuffer();
 
-    const { exitCode, tail, handoffArgv } = await runPTY({
-      claudeArgv,
-      launchCWD,
-      cfg,
-      handoff: hspec,
+let exitCode: number;
+try {
+  let proc: Bun.Subprocess;
+  if (useTerminal) {
+    // Tee PTY output → process.stdout AND the ring buffer. §9.3 consumes
+    // the buffer after exit to scan for claude's cross-cwd resume hint.
+    const term = new Bun.Terminal({
+      cols: process.stdout.columns ?? 80,
+      rows: process.stdout.rows ?? 24,
+      data: (_t, chunk) => {
+        process.stdout.write(chunk);
+        ringBuffer.push(chunk);
+      },
     });
 
-    // ── Auto-handoff fires first. ────────────────────────────────────────
-    if (handoffArgv !== undefined && handoffArgv.length > 0) {
-      // Flush deferred warnings before relaunch since execve replaces the
-      // process image (the deferred flush below would be skipped).
-      flushOnce();
-      relaunchHandoff(handoffArgv);
-      // If we get here, execve failed; fall through to cross-cwd detection
-      // (won't match in practice) and return claude's exit code.
-    }
+    proc = Bun.spawn([claudeBin.path, ...claudeArgs], {
+      cwd,
+      env: childEnv,
+      terminal: term,
+    });
 
-    // ── Cross-cwd redirect detection. ────────────────────────────────────
-    if (tail !== undefined) {
-      const hit = detectCrossCwd(tail);
-      if (hit !== undefined) {
-        flushOnce();
-        relaunch(argv, hit.dest, hit.uuid);
-        // Same fallthrough as above.
-      }
-    }
+    // Forward user stdin → PTY. Raw mode so the shell line discipline
+    // doesn't eat control sequences (Ctrl-C, arrow keys, etc.) before
+    // claude sees them. bun#25779 (control bytes not delivering signals
+    // through Bun.Terminal.write) was fixed before 1.3.14 — verified
+    // empirically on this version; no byte-interception workaround
+    // needed.
+    process.stdin.setRawMode(true);
+    process.stdin.on('data', (chunk: Buffer) => {
+      term.write(chunk);
+    });
+
+    // SIGWINCH no longer reaches claude directly (the PTY is owned by the
+    // launcher), so plumb terminal resizes through manually.
+    process.stdout.on('resize', () => {
+      term.resize(process.stdout.columns ?? 80, process.stdout.rows ?? 24);
+    });
+  } else {
+    proc = Bun.spawn([claudeBin.path, ...claudeArgs], {
+      cwd,
+      env: childEnv,
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+    });
+  }
+
+  ensured.cleanup();
 
-    return exitCode;
-  } finally {
-    flushOnce();
+  // §8.5: arm the kill-and-exec awaiter as a side-promise. If an MCP
+  // tool dispatches a handoff during the session, the awaiter wakes,
+  // SIGTERMs claude (escalating to SIGKILL after 200 ms if needed),
+  // waits for proc.exited, then re-execs fnclaude with the stashed
+  // argv via Bun.spawn (no native execve binding — see decisions.md).
+  // If no handoff fires, this promise sits idle until process exit
+  // and gets GC'd; the orphaned-promise pattern matches Go canonical's
+  // background goroutine. design.mcp.md §6.
+  void startHandoffAwaiter({
+    trigger: handoffTrigger,
+    proc,
+  });
+
+  exitCode = await proc.exited;
+} finally {
+  // Stop the MCP listener + unlink the socket file even if spawn or
+  // proc.exited throws. design.mcp.md §7 — socket file cleanup is the
+  // parent's job.
+  if (mcpListenerStop !== undefined) {
+    await mcpListenerStop();
   }
 }
 
-/**
- * Process entry point. Invokes `run()` and exits with its return code.
- * Tests should call `run()` directly so they can introspect the value.
- */
-export async function main(): Promise<void> {
-  let code: number;
-  try {
-    code = await run();
-  } catch (err) {
-    process.stderr.write(`fnclaude: fatal: ${errorMessage(err)}\n`);
-    code = 1;
-  }
-  process.exit(code);
+if (useTerminal) {
+  // Restore the terminal so the user's shell prompt comes back in cooked
+  // mode. setRawMode is a no-op when stdin isn't a TTY; we only entered
+  // raw mode in the useTerminal branch, so this is safe to call.
+  process.stdin.setRawMode(false);
+  // Stop reading stdin so process.exit doesn't block on an open listener.
+  process.stdin.pause();
+}
+
+// §9.3: cross-cwd silent relaunch. After a clean exit, scan the ring
+// buffer for claude's "To resume, run: cd X && claude --resume UUID"
+// hint and silently re-exec fnclaude in the new cwd. Gated to skip
+// when an MCP handoff has already stashed argv (that path owns the
+// relaunch) and when claude exited non-zero (don't relaunch on a
+// crash). On Windows the ring buffer stays empty (inherit branch), so
+// the decision always returns false there — keeps the call shape
+// platform-uniform without a separate guard.
+const crossCwdDecision = decideCrossCwdRelaunch({
+  exitCode,
+  alreadyStashed: handoffTrigger.getStashedArgv() !== null,
+  ringSnapshot: ringBuffer.snapshot(),
+  origArgs: argv,
+});
+if (crossCwdDecision.relaunch) {
+  // Stash so future getStashedArgv() callers see this relaunch as
+  // owned. The cross-cwd path is "silent" — we skip the warnings
+  // flush below; the new fnclaude process re-evaluates and re-queues
+  // anything still applicable.
+  handoffTrigger.stashArgv(crossCwdDecision.argv);
+  await reexecSelf({ argv: crossCwdDecision.argv });
+  // Unreachable: reexecSelf calls process.exit. Typed as Promise<never>.
 }
+
+// Flush accumulated warnings to stderr now that claude has exited and the
+// user is back at their shell prompt where they have time to read them.
+// Silent-relaunch paths (cross-cwd resume above; MCP handoff via the
+// awaiter side-promise) skip this flush — the new fnclaude process
+// re-evaluates and re-queues any still-applicable warnings.
+warnings.flush(process.stderr);
+
+process.exit(exitCode);