@fnclaude/cli 1.1.1 → 2.0.0

package/src/handoff/awaiter.ts

@@ -0,0 +1,140 @@
+/**
+ * §8.5 — Production wiring for the kill-and-exec side-promise.
+ *
+ * `startHandoffAwaiter` is the parent-side glue that hooks the trigger
+ * (fired by MCP dispatch) up to the kill sequence + process re-exec.
+ * Spec: docs/design.mcp.md §6.
+ *
+ * The returned promise is "fire-and-forget" by design — if no handoff
+ * ever fires, the awaiter sits idle for the lifetime of the session,
+ * then the orphaned promise gets garbage-collected with the rest of
+ * main.ts's state when the parent exits naturally. If a handoff DOES
+ * fire, the kill sequence runs, claude exits, and then the re-exec
+ * either swaps the process image (true execve, not available under
+ * Bun) or in the Bun.spawn-based shim, spawns a child, waits, then
+ * `process.exit`s with the child's code.
+ *
+ * Tests pass injected `execve`/`signalSend`/`sleep` so they can
+ * exercise the wiring without actually killing or re-executing.
+ */
+
+import { killAndExec, type KillAndExecArgs, type SignalName } from './kill-and-exec.ts';
+import type { HandoffTrigger } from './trigger.ts';
+
+export interface StartHandoffAwaiterArgs {
+  trigger: HandoffTrigger;
+  proc: Pick<Bun.Subprocess, 'exited' | 'kill'>;
+  /** Optional override for the kill-and-exec primitive (test seam). */
+  killAndExec?: (a: KillAndExecArgs) => Promise<void>;
+  /** Optional override for the signal sender (test seam). */
+  signalSend?: (signal: SignalName) => void;
+  /** Optional override for sleep (test seam). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Optional override for the re-exec primitive (test seam). */
+  execve?: (argv: string[]) => void | Promise<void>;
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Start the awaiter. Returns the side-promise (caller is expected to
+ * fire-and-forget; no need to await unless you want the kill+exec to
+ * complete first). If the trigger never fires, the promise sits
+ * pending until process exit.
+ */
+export function startHandoffAwaiter(args: StartHandoffAwaiterArgs): Promise<void> {
+  const platform = args.platform ?? process.platform;
+  const sleep =
+    args.sleep ??
+    ((ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms)));
+  const signalSend =
+    args.signalSend ??
+    ((signal: SignalName): void => {
+      // proc.kill returns false if the process has already exited; that's
+      // expected after the 200 ms grace window when SIGTERM landed. Don't
+      // throw — the parent's only job left is to await `exited` and
+      // re-exec.
+      try {
+        args.proc.kill(signal);
+      } catch {
+        // ESRCH/EPERM: already-reaped or out-of-our-pgrp. Ignore.
+      }
+    });
+  const execve = args.execve ?? defaultExecve;
+  const killFn = args.killAndExec ?? killAndExec;
+
+  return (async (): Promise<void> => {
+    await args.trigger.awaitTrigger();
+    const stashedArgv = args.trigger.getStashedArgv();
+    if (stashedArgv === null) {
+      // Trigger fired but nothing stashed — shouldn't happen under the
+      // §6.1 contract (the dispatcher always stashes before firing), but
+      // bail rather than re-exec into a nil argv if it ever does.
+      return;
+    }
+    await killFn({
+      proc: args.proc,
+      stashedArgv,
+      signalSend,
+      sleep,
+      execve,
+      platform,
+    });
+  })();
+}
+
+/**
+ * Default re-exec primitive. Wraps the reusable `reexecSelf` helper —
+ * shared with §9.3's cross-cwd silent relaunch path.
+ */
+async function defaultExecve(argv: string[]): Promise<void> {
+  await reexecSelf({ argv });
+}
+
+/**
+ * Process image replacement via Bun.spawn — shared between §8.5's
+ * handoff exec and §9.3's cross-cwd silent relaunch.
+ *
+ * Bun has no `execve` binding — true process image replacement isn't
+ * possible. The closest stable analog is
+ * `Bun.spawn(process.execPath, [bin, ...argv])`, then await the
+ * child's exit and `process.exit` with the child's code.
+ *
+ * The fnc bin lives at `process.argv[1]` (already resolved by the
+ * shim) by default; callers can override via `args.fncBin`. The same
+ * runtime that's currently executing (`process.execPath` by default)
+ * hosts the child so any preflight/argv-rehydration step runs
+ * identically on the relaunch.
+ *
+ * Never returns on success — `process.exit(code)` ends the parent
+ * before this promise resolves. The signature is `Promise<never>` to
+ * keep TypeScript honest about the control-flow.
+ *
+ * Deviation from Go canonical (true execve) is documented in
+ * docs/decisions.md.
+ */
+export interface ReexecSelfArgs {
+  /** Argv to hand the new fnclaude process (excluding bin path / runtime). */
+  argv: string[];
+  /** Override the Bun executable. Defaults to `process.execPath`. */
+  bunExec?: string;
+  /**
+   * Override the fnc bin path passed to bun as argv[0]. Defaults to
+   * `process.argv[1] ?? ''` — the same script that the parent is
+   * running.
+   */
+  fncBin?: string;
+}
+
+export async function reexecSelf(args: ReexecSelfArgs): Promise<never> {
+  const bunExec = args.bunExec ?? process.execPath;
+  const fncBin = args.fncBin ?? process.argv[1] ?? '';
+  const child = Bun.spawn([bunExec, fncBin, ...args.argv], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  const code = await child.exited;
+  process.exit(code);
+}

package/src/handoff/clean-env.ts

@@ -0,0 +1,45 @@
+/**
+ * §8.3 — pure env scrubber for `fnc_spawn_session`.
+ *
+ * The spawned sibling fnclaude is its own independent session, so the
+ * three session-scoped vars must NOT leak across the spawn boundary:
+ *
+ *   - `FNC_SOCKET` points at *this* parent's listener; the sibling has
+ *     to compute its own socket path. If we leaked it, the new
+ *     claude's MCP subprocess would dial back into us instead of its
+ *     own parent.
+ *   - `FNCLAUDE_HANDOFF` was injected for *this* session's claude.
+ *   - `CLAUDE_CODE_SESSION_ID` likewise scopes to this session.
+ *
+ * Everything else (`PATH`, `XDG_*`, exec.env contributions, etc.)
+ * passes through unchanged so the sibling inherits the same user
+ * environment.
+ *
+ * Ports Go canonical's `cleanEnvForSpawn` (`fnclaude@fnrhombus/src/spawn.go`).
+ * The TS shape is a `Record<string,string>` because Bun.spawn's `env`
+ * option takes the object form; Go was producing `KEY=VALUE` slices for
+ * `exec.Cmd.Env`. Same semantics either way.
+ */
+
+const DROP: ReadonlySet<string> = new Set([
+  'FNC_SOCKET',
+  'FNCLAUDE_HANDOFF',
+  'CLAUDE_CODE_SESSION_ID',
+]);
+
+/**
+ * Return a fresh env object with the three session-scoped keys removed.
+ * Non-string values (undefined slots on process.env) are skipped — the
+ * Bun.spawn `env` contract is `Record<string,string>`.
+ */
+export function cleanEnvForSpawn(
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (DROP.has(k)) continue;
+    if (typeof v !== 'string') continue;
+    out[k] = v;
+  }
+  return out;
+}

package/src/handoff/kill-and-exec.ts

@@ -0,0 +1,110 @@
+/**
+ * §8.5 — Kill sequence + process image replacement.
+ *
+ * When the parent's `awaitTrigger()` resolves (the MCP dispatcher fired
+ * a handoff), the parent has to:
+ *
+ *   1. Send SIGTERM to the claude subprocess.
+ *   2. Wait 200 ms.
+ *   3. If claude hasn't exited, send SIGKILL.
+ *   4. Await `proc.exited` so we know claude is reaped.
+ *   5. Replace the parent's process image with `fnclaude <stashed argv>`.
+ *
+ * On Windows the kill sequence collapses to a single TerminateProcess-
+ * equivalent (no graceful path), per design.mcp.md §6.1.
+ *
+ * **Why a side-effect injection seam:** the real `execve` and the real
+ * `process.kill` are end-of-line operations — once they fire, the
+ * process is gone or has different bytes in memory. Tests must run them
+ * as injected callbacks so the test harness keeps running afterwards.
+ *
+ * **Why not real execve:** TS/Bun has no `execve` binding (Go's
+ * `syscall.Exec` swaps the running process image in place). The closest
+ * stable analog under Bun is `Bun.spawn(process.execPath, [bin, ...argv])`
+ * — a child that inherits stdio and that the parent waits on. The
+ * decision to use spawn-and-wait instead of true execve is documented
+ * in docs/decisions.md ("Process image replacement via Bun.spawn").
+ *
+ * Design: docs/design.mcp.md §6.1, §6.2.
+ */
+
+export type SignalName = 'SIGTERM' | 'SIGKILL';
+
+export interface KillAndExecArgs {
+  /** Subprocess to terminate. Only `exited` is awaited; killing is via signalSend. */
+  proc: Pick<Bun.Subprocess, 'exited'>;
+  /** Argv to relaunch with after claude exits. */
+  stashedArgv: string[];
+  /**
+   * Deliver a signal to the subprocess. Injected so tests can record
+   * signals without actually killing anything. Production wires this
+   * to `proc.kill(<signal>)`.
+   */
+  signalSend: (signal: SignalName) => void;
+  /** Async sleep, injected so tests don't actually wait. */
+  sleep: (ms: number) => Promise<void>;
+  /**
+   * Process-image-replacement. Injected so tests don't actually re-exec.
+   * Production wires this to a `Bun.spawn` + `await child.exited` →
+   * `process.exit(<code>)` sequence (see docs/decisions.md for why
+   * Bun.spawn instead of native execve).
+   */
+  execve: (argv: string[]) => void | Promise<void>;
+  /** `process.platform`. `win32` collapses the kill sequence to one signal. */
+  platform: NodeJS.Platform;
+}
+
+const KILL_GRACE_MS = 200;
+
+export async function killAndExec(args: KillAndExecArgs): Promise<void> {
+  if (args.platform === 'win32') {
+    // No graceful path on Windows — the closest analog to TerminateProcess
+    // is a hard kill, surfaced through the same signalSend seam (callers
+    // map it to `proc.kill()` on win32).
+    args.signalSend('SIGKILL');
+  } else {
+    args.signalSend('SIGTERM');
+    await args.sleep(KILL_GRACE_MS);
+    // Race-aware: if proc has already exited by now, SIGKILL on a reaped
+    // PID is a no-op error at the OS level; we hand it to signalSend
+    // anyway and let production wiring (proc.kill) swallow the EPERM/
+    // ESRCH. Tests that resolve `exited` on SIGTERM never see a SIGKILL
+    // because we check before sending.
+    const stillAlive = await isStillRunning(args.proc.exited);
+    if (stillAlive) {
+      args.signalSend('SIGKILL');
+    }
+  }
+
+  // Wait for claude to be fully reaped before we re-exec. On Unix this
+  // is the moment after the kernel delivers the signal and the parent
+  // collects the exit status; without it the new process image could
+  // race against the dying child's last writes to the controlling TTY.
+  await args.proc.exited;
+
+  await args.execve(args.stashedArgv);
+}
+
+/**
+ * Resolve true iff `exited` has NOT resolved by the next macrotask.
+ * Used to gate the SIGKILL escalation — we only want to send the
+ * hard-kill if SIGTERM didn't already cause the process to exit during
+ * the 200 ms grace window.
+ *
+ * The `setTimeout(0)` is important: a plain `Promise.resolve()` race
+ * loses to an already-settled `exited` only if the .then() chain has
+ * already drained. A short macrotask boundary gives the existing
+ * promise pipeline (including .then chains hung off `exited` by the
+ * test fake or by Bun.Subprocess itself) time to settle before we
+ * decide whether to escalate.
+ */
+async function isStillRunning(exited: Promise<unknown>): Promise<boolean> {
+  const marker = Symbol('still-alive');
+  const result = await Promise.race([
+    exited.then(() => 'exited' as const),
+    new Promise<typeof marker>((resolve) => {
+      setTimeout(() => resolve(marker), 0);
+    }),
+  ]);
+  return result === marker;
+}

package/src/handoff/spawn-launcher.ts

@@ -0,0 +1,185 @@
+/**
+ * §8.3 — spawn-launcher decision + dispatch for `fnc_spawn_session`.
+ *
+ * Decision order (per design.mcp.md §4.3):
+ *
+ *   1. `auto.spawnCommand` from config — tokenize on whitespace,
+ *      substitute `{bin}` / `{dest}` / `{name}` / `{summary}` per token.
+ *   2. `$TMUX` in env — use the built-in
+ *      `tmux new-window -d {bin} {dest} --name {name} @{summary}`
+ *      template. Being inside tmux is an explicit declaration that
+ *      tmux is the windowing layer.
+ *   3. Nothing — caller falls back to paste-flow.
+ *
+ * Earlier ports also sniffed `$KITTY_WINDOW_ID`, `$TERM_PROGRAM=WezTerm`,
+ * and `$WT_SESSION`. Those allowlist heuristics grew indefinitely and
+ * silently failed for everyone else. The `auto.spawnCommand` config
+ * knob is strictly better: one surface, every terminal.
+ *
+ * Ports Go canonical's `spawnSiblingImpl` + `autoDetectSpawnCommand` +
+ * `buildSpawnArgv` from `fnclaude@fnrhombus/src/spawn.go`. Substitution
+ * is per-token after whitespace splitting — a `{dest}` expanding to a
+ * path with spaces stays one argv entry, no shell involvement.
+ *
+ * Pure module: no I/O, no env reads, no Bun.spawn calls of its own.
+ * The caller supplies env, fncBin, the spawn function, and the
+ * autoSpawnCommand config value. Tests inject everything.
+ */
+
+const TMUX_TEMPLATE = 'tmux new-window -d {bin} {dest} --name {name} @{summary}';
+
+/**
+ * Minimal spawn surface the launcher exercises. The real shape is a
+ * thin adapter over `Bun.spawn` in production (see {@link defaultSpawn}).
+ */
+export interface SpawnFn {
+  (
+    argv: readonly string[],
+    opts: { env: Record<string, string> },
+  ): { unref?: () => void };
+}
+
+export interface ChooseAndSpawnArgs {
+  /** `cfg.auto.spawnCommand` — empty string means "not configured". */
+  autoSpawnCommand: string;
+  /** Env to consult for `$TMUX` auto-detection. */
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  /** Cleaned env to pass through to the spawn (already scrubbed of session vars). */
+  spawnEnv: Record<string, string>;
+  /** Absolute fnclaude binary path for `{bin}` substitution. */
+  fncBin: string;
+  /** `{dest}` substitution — destination project ref / path. */
+  dest: string;
+  /** `{name}` substitution — session label. */
+  name: string;
+  /** `{summary}` substitution — absolute path to the written summary file. */
+  summary: string;
+  /** Override extras to append after the templated argv (override flags from applyOverrides). */
+  extraArgs: readonly string[];
+  /** Injected spawn fn (production: {@link defaultSpawn}). */
+  spawn: SpawnFn;
+}
+
+export type ChooseAndSpawnResult =
+  | { ok: true }
+  /** No launcher resolved — caller falls back to paste-flow. `command` is the
+   *  rendered relaunch command for the user to paste. */
+  | { ok: false; command: string };
+
+/**
+ * Pick a launcher and dispatch. Returns `{ ok: true }` on a clean
+ * `spawn()` call; returns `{ ok: false, command }` when neither
+ * `autoSpawnCommand` nor `$TMUX` resolved a template.
+ *
+ * Throws only when a launcher WAS resolved but `spawn` itself threw —
+ * matches Go canonical's `(false, err)` shape (caller surfaces the
+ * error response). Empty-argv-from-template is also an error.
+ */
+export function chooseAndSpawn(args: ChooseAndSpawnArgs): ChooseAndSpawnResult {
+  const tmpl = pickTemplate(args.autoSpawnCommand, args.env);
+  if (tmpl === '') {
+    return { ok: false, command: renderSpawnCommand(args) };
+  }
+
+  const argv = buildSpawnArgv(tmpl, args.fncBin, args.dest, args.name, args.summary);
+  if (argv.length === 0) {
+    throw new Error(`spawn template produced empty argv: ${JSON.stringify(tmpl)}`);
+  }
+  const fullArgv = [...argv, ...args.extraArgs];
+
+  const proc = args.spawn(fullArgv, { env: args.spawnEnv });
+  // Detach so the launcher (tmux, kitty @, etc.) can outlive the parent.
+  // tmux's `-d` already does the daemonization; unref is best-effort
+  // belt-and-braces for spawners that wait by default.
+  try {
+    proc.unref?.();
+  } catch {
+    // ignore — process already detached
+  }
+  return { ok: true };
+}
+
+/**
+ * Decide which launcher template to use:
+ *
+ *   - Non-empty `autoSpawnCommand` wins.
+ *   - `$TMUX` non-empty → built-in tmux template.
+ *   - Otherwise empty string (caller falls back to paste-flow).
+ */
+function pickTemplate(
+  autoSpawnCommand: string,
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
+): string {
+  if (autoSpawnCommand !== '') return autoSpawnCommand;
+  const tmux = env.TMUX;
+  if (typeof tmux === 'string' && tmux !== '') return TMUX_TEMPLATE;
+  return '';
+}
+
+/**
+ * Whitespace-tokenize `tmpl`, then per-token substitute the four
+ * placeholders. No shell involvement — each token becomes one argv
+ * entry verbatim. A `{dest}` expanding to a path with spaces stays
+ * one argv entry.
+ */
+export function buildSpawnArgv(
+  tmpl: string,
+  bin: string,
+  dest: string,
+  name: string,
+  summary: string,
+): string[] {
+  // .split(/\s+/) leaves a leading "" when tmpl starts with whitespace;
+  // filter empties to match Go's strings.Fields behavior.
+  const tokens = tmpl.split(/\s+/).filter((t) => t !== '');
+  const out: string[] = [];
+  for (const t of tokens) {
+    out.push(
+      t
+        .replaceAll('{bin}', bin)
+        .replaceAll('{dest}', dest)
+        .replaceAll('{name}', name)
+        .replaceAll('{summary}', summary),
+    );
+  }
+  return out;
+}
+
+/**
+ * Render the user-visible relaunch command for paste-flow Responses.
+ * Mirrors Go canonical's `renderSpawnCommand`: `fnclaude <dest> --name
+ * <name> @<summary> [extra args]`. Override values are controlled-
+ * vocabulary strings (model aliases, effort levels, etc.); space-
+ * joining them is shell-safe by construction.
+ */
+export function renderSpawnCommand(args: {
+  dest: string;
+  name: string;
+  summary: string;
+  extraArgs: readonly string[];
+}): string {
+  let cmd = `fnclaude ${args.dest} --name ${args.name} @${args.summary}`;
+  if (args.extraArgs.length > 0) {
+    cmd += ' ' + args.extraArgs.join(' ');
+  }
+  return cmd;
+}
+
+/**
+ * Production spawn adapter. Thin wrapper over `Bun.spawn` — pipes nothing,
+ * inherits no stdio (the spawned launcher is its own session under its
+ * own terminal). Detached so the launcher outlives the parent fnclaude.
+ */
+export const defaultSpawn: SpawnFn = (argv, opts) => {
+  const proc = Bun.spawn([...argv], {
+    env: opts.env,
+    stdin: 'ignore',
+    stdout: 'ignore',
+    stderr: 'ignore',
+  });
+  return {
+    unref(): void {
+      proc.unref();
+    },
+  };
+};

package/src/handoff/summary-file.ts

@@ -0,0 +1,86 @@
+/**
+ * Handoff summary content file — pure write.
+ *
+ * `fnc_switch_project` and `fnc_spawn_session` write the markdown
+ * summary that the destination session auto-loads (via `@<path>` in the
+ * relaunch argv) to a fresh file on disk. The path formula:
+ *
+ *   <base>/fnclaude-handoff-content-<16hex>.md
+ *
+ * `<base>` resolves from `$XDG_RUNTIME_DIR` if set (Linux/systemd
+ * tmpfs, mode 700, cleared on logout — restrictive by default so other
+ * users on the box can't read the content). Otherwise `os.tmpdir()`
+ * (the OS-native fallback: macOS launchd / Windows per-user TEMP both
+ * already have restrictive ACLs). See design.md §14.
+ *
+ * The file itself is written with mode 0600 — same belt-and-suspenders
+ * the Go canonical uses, since the surrounding tmpfs already restricts
+ * access. Handoff summaries can contain conversation context, tool
+ * results, etc.
+ *
+ * `<16hex>` is 8 bytes of crypto-random hex. PID + nanosecond is
+ * NOT used as the primary form here (Go's fallback path) — Node's
+ * `crypto.randomBytes` doesn't fail on a healthy system, so a tighter
+ * always-random shape stays adequate without the extra branch.
+ *
+ * The base-dir resolver and random-hex source are both injected for
+ * tests. Production callers use the defaults (`defaultBaseDir`,
+ * `defaultRandomHex`).
+ *
+ * Design: docs/design.mcp.md §4.2, docs/design.md §14.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Resolve the base directory for handoff content files. */
+export type BaseDirResolver = () => string;
+
+/** Generate 16 hex characters (8 bytes of entropy) for the filename token. */
+export type RandomHexFn = () => string;
+
+export interface WriteSummaryFileArgs {
+  summary: string;
+  baseDir?: BaseDirResolver;
+  randomHex?: RandomHexFn;
+}
+
+export interface WriteSummaryFileResult {
+  path: string;
+}
+
+/**
+ * Write `summary` to `<base>/fnclaude-handoff-content-<16hex>.md` with
+ * mode 0600 and return the resolved path. Throws if the write fails —
+ * the caller (switch handler) surfaces that as an `action: 'error'`
+ * response.
+ */
+export async function writeSummaryFile(
+  args: WriteSummaryFileArgs,
+): Promise<WriteSummaryFileResult> {
+  const baseDir = (args.baseDir ?? defaultBaseDir)();
+  const hex = (args.randomHex ?? defaultRandomHex)();
+  const path = join(baseDir, `fnclaude-handoff-content-${hex}.md`);
+  await writeFile(path, args.summary, { mode: 0o600 });
+  return { path };
+}
+
+/**
+ * Default base dir: `$XDG_RUNTIME_DIR` if set, else `os.tmpdir()`.
+ * Mirrors Go canonical's `handoffBaseDir`.
+ */
+export const defaultBaseDir: BaseDirResolver = () => {
+  const xdg = process.env.XDG_RUNTIME_DIR;
+  if (xdg !== undefined && xdg !== '') {
+    return xdg;
+  }
+  return tmpdir();
+};
+
+/**
+ * Default random-hex source: 8 bytes of crypto entropy → 16 hex chars.
+ * Matches Go canonical's `rand.Read(make([]byte, 8))` + `hex.EncodeToString`.
+ */
+export const defaultRandomHex: RandomHexFn = () => randomBytes(8).toString('hex');

package/src/handoff/trigger.ts

@@ -0,0 +1,90 @@
+/**
+ * §8.5 — Handoff trigger primitive.
+ *
+ * The parent's MCP dispatch goroutine fires `Triggered` when a `restart`
+ * or non-`never`-mode `switch` arrives; a separate awaiter (started at
+ * parent startup) blocks on it until then. Two pieces:
+ *
+ *   1. `stashArgv` — first-stash-wins shared field for the relaunch
+ *      argv. Mirrors Go canonical's `sync.Mutex` + nil-check pattern
+ *      (mcpserver.HandoffTrigger.Stash, see Go src/handoff.go for the
+ *      reference). The "rare race" in design.mcp.md §8 (concurrent
+ *      restart + switch) lands here: both stashes succeed at the JSON-
+ *      RPC layer; only the first one's argv survives to drive the kill.
+ *
+ *   2. `fire` + `awaitTrigger` — one-shot signal. `fire` is idempotent;
+ *      a second call is a no-op. `awaitTrigger` returns a promise that
+ *      resolves the moment `fire` runs, or immediately if `fire` already
+ *      ran before the await was created. Multiple awaiters are fine —
+ *      all resolve on the same fire.
+ *
+ * Design: docs/design.mcp.md §6.1, §8 (concurrent-dispatch race).
+ */
+
+export interface HandoffTrigger {
+  /**
+   * Stash the relaunch argv. Returns true on the first call (argv now
+   * owned by the trigger), false on every subsequent call (the caller's
+   * argv is dropped silently — first-stash-wins semantics).
+   */
+  stashArgv: (argv: string[]) => boolean;
+  /**
+   * Read back the stashed argv. Null when no stash has happened yet.
+   * The reference is shared — callers must not mutate.
+   */
+  getStashedArgv: () => string[] | null;
+  /**
+   * Fire the trigger. Idempotent — a second call is a no-op (the
+   * underlying promise stays resolved; no second resolution happens).
+   */
+  fire: () => void;
+  /**
+   * Resolve when `fire` has been called (now or in the future). Multiple
+   * awaiters all see the same fire. If `fire` already ran, the returned
+   * promise resolves on the next microtask.
+   */
+  awaitTrigger: () => Promise<void>;
+}
+
+/**
+ * Module-level singleton mirroring Go canonical's
+ * `mcpserver.HandoffTrigger`. The parent's MCP dispatch tools and the
+ * kill-and-exec awaiter both refer to this one instance; tests that
+ * exercise the trigger contract should use `createHandoffTrigger`
+ * directly to keep state hermetic.
+ */
+export const handoffTrigger: HandoffTrigger = createHandoffTriggerFactory();
+
+export function createHandoffTrigger(): HandoffTrigger {
+  return createHandoffTriggerFactory();
+}
+
+function createHandoffTriggerFactory(): HandoffTrigger {
+  let stashed: string[] | null = null;
+  let fired = false;
+  let resolveFn: (() => void) | null = null;
+  const triggered = new Promise<void>((resolve) => {
+    resolveFn = resolve;
+  });
+
+  return {
+    stashArgv(argv: string[]): boolean {
+      if (stashed !== null) return false;
+      stashed = argv;
+      return true;
+    },
+    getStashedArgv(): string[] | null {
+      return stashed;
+    },
+    fire(): void {
+      if (fired) return;
+      fired = true;
+      // `resolveFn` is always set by the time fire() can run — the
+      // Promise constructor runs its executor synchronously.
+      resolveFn!();
+    },
+    awaitTrigger(): Promise<void> {
+      return triggered;
+    },
+  };
+}