faberun 0.3.0

package/src/cli/contract.mjs

@@ -0,0 +1,67 @@
+/**
+ * `contract validate`: validate an authored contract from the command line and
+ * print the report the authoring turn reads (TECH-SPEC lean, rule 4: a
+ * partly finished run is continued by `resume`, never re-authored, so this is
+ * the only contract operation the CLI carries).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { loadPersistedContract, validateContract } from "../contract/index.mjs";
+
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+
+/** Flags are scoped to the operation that declares them; all others are rejected. */
+/** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
+const OPERATION_OPTIONS = {
+  validate: {},
+};
+
+/**
+ * @param {string[]} args
+ * @returns {void}
+ */
+export function contractCli(args) {
+  const operation = args[0];
+  if (!operation || !Object.hasOwn(OPERATION_OPTIONS, operation)) return usage();
+  const target = args[1];
+  if (!target || args.length > 2) return usage();
+  if (operation === "validate") validateContractFile(resolve(target));
+}
+
+/**
+ * Validate an authored contract and print the same report the `validate`
+ * command has always printed. A single-node contract is simply valid.
+ *
+ * A contract.json that sits beside a run.json is a persisted run's frozen copy,
+ * not an authored contract: it takes the tree-free persisted path and must
+ * match the digest recorded at launch. Every other target keeps today's
+ * authoring validation, tree reads included.
+ *
+ * @param {string} path
+ * @returns {ValidatedContract}
+ */
+export function validateContractFile(path) {
+  const runJsonPath = join(dirname(path), "run.json");
+  const contract = existsSync(runJsonPath)
+    ? loadPersistedContract(path, readRunDigest(runJsonPath))
+    : validateContract(JSON.parse(readFileSync(path, "utf8")), path);
+  const count = contract.warnings.length;
+  process.stdout.write(`valid${count ? ` (${count} warning${count === 1 ? "" : "s"})` : ""}\n`);
+  for (const warning of contract.warnings) process.stdout.write(`[warn] ${warning}\n`);
+  return contract;
+}
+
+/**
+ * @param {string} runJsonPath
+ * @returns {string|undefined}
+ */
+function readRunDigest(runJsonPath) {
+  const metadata = JSON.parse(readFileSync(runJsonPath, "utf8"));
+  return typeof metadata.contractDigest === "string" ? metadata.contractDigest : undefined;
+}
+
+/** @returns {void} */
+function usage() {
+  process.stderr.write("usage: faberun contract validate <contract.json>\n");
+  process.exitCode = 2;
+}

package/src/cli/init.mjs

@@ -0,0 +1,170 @@
+/**
+ * `faberun init [--cwd <dir>] [--yes] [--no-skill] [--agentkit]
+ * [--greenfield|--stable] [--json]`: prepare a target repository for campaigns.
+ *
+ * Three facts are established in order: the target is a git work tree, `.runs/`
+ * is ignored, and the `faberun` skill is installed under `.claude/skills/`. The
+ * agent kit is optional, and its compatibility rule is always asked or given by
+ * flag -- never defaulted silently. The shipped shell script does the writing;
+ * this module owns only the questions and the check lines.
+ *
+ * Questions, streams and process facts are injected so tests never touch a
+ * terminal, the same split `cli/setup.mjs` uses.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { colorLevel, statusToken } from "./brand.mjs";
+import { installSkills } from "./skills.mjs";
+import { boundedGitSync } from "../repo/worktree.mjs";
+
+/** @typedef {(text: string) => void} Writer */
+/** @typedef {(question: string) => Promise<string>} Asker */
+/** @typedef {{ask: Asker, close: () => void}} AskerHandle */
+/** @typedef {"greenfield"|"stable"} Variant */
+/** @typedef {{cwd: string, runsIgnored: boolean, skillInstalled: boolean, agentkit: boolean}} InitReport */
+/**
+ * @typedef {object} InitOptions
+ * @property {string} [cwd]
+ * @property {boolean} [yes]
+ * @property {boolean} [skill] whether to install the faberun skill (default true)
+ * @property {boolean} [agentkit] install the agent kit without asking
+ * @property {Variant} [variant] the already-chosen compatibility rule
+ * @property {boolean} [json]
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {Asker} [ask]
+ * @property {Writer} [stdout]
+ * @property {Writer} [stderr]
+ * @property {boolean} [isTTY]
+ */
+
+/** The shipped installer that lays the agent kit down, resolved from this module rather than the caller's cwd. */
+const AGENTKIT_INSTALLER = fileURLToPath(new URL("../../skills/init-agentkit/scripts/install-agentkit.sh", import.meta.url));
+
+/**
+ * Prepare `cwd` for campaigns and return the process exit code.
+ *
+ * @param {InitOptions} [options]
+ * @returns {Promise<number>}
+ */
+export async function initCommand(options = {}) {
+  const env = options.env ?? process.env;
+  const stdout = options.stdout ?? ((text) => process.stdout.write(text));
+  const stderr = options.stderr ?? ((text) => process.stderr.write(text));
+  const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const json = options.json === true;
+  const cwd = resolve(options.cwd ?? ".");
+  const level = colorLevel(env, isTTY);
+  // `--yes` and `--json` are the two non-interactive paths; both take the
+  // flags as given and never wait on a terminal.
+  const interactive = isTTY && options.yes !== true && !json;
+  const report = /** @type {InitReport} */ ({ cwd, runsIgnored: false, skillInstalled: false, agentkit: false });
+
+  // The readline interface is created only if a question is actually asked, so
+  // a flag-driven or `--json` invocation never opens stdin. The holder object
+  // keeps the assignment inside the closure visible to the `finally` close.
+  const state = { asker: /** @type {AskerHandle|null} */ (null) };
+  /** @param {string} question @returns {Promise<string>} */
+  const askQuestion = async (question) => {
+    if (state.asker === null) {
+      if (options.ask) {
+        state.asker = { ask: options.ask, close: () => {} };
+      } else {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        state.asker = { ask: (text) => rl.question(text), close: () => rl.close() };
+      }
+    }
+    return (await state.asker.ask(question)).trim();
+  };
+
+  try {
+    if (!isGitWorkTree(cwd)) {
+      if (json) stdout(`${JSON.stringify(report, null, 2)}\n`);
+      else stdout(`${statusToken("fail", level)} git · ${cwd} is not a git work tree\n`);
+      return 1;
+    }
+
+    const gitignore = ensureRunsIgnored(cwd);
+    report.runsIgnored = true;
+    if (!json) stdout(`${statusToken("ok", level)} .runs ignored · ${gitignore}\n`);
+
+    let skill = options.skill !== false;
+    if (skill && interactive) {
+      skill = !(await askQuestion("Install the faberun skill into .claude/skills? [Y/n] ")).toLowerCase().startsWith("n");
+    }
+    if (skill) {
+      // `--json` still installs; the skill's own report lines are human output
+      // and would otherwise corrupt the one machine-readable object.
+      const skills = installSkills({
+        names: ["faberun"],
+        skillsDir: join(cwd, ".claude", "skills"),
+        force: false,
+        stdout: json ? { write: () => {} } : { write: stdout },
+      });
+      report.skillInstalled = skills.installed + skills.skipped > 0;
+    }
+
+    let agentkit = options.agentkit === true;
+    if (!agentkit && interactive) {
+      agentkit = (await askQuestion("Install the agent kit (AGENTS.md, docs/, ADRs, Sentrux gate)? [y/N] ")).toLowerCase().startsWith("y");
+    }
+    if (agentkit) {
+      let variant = /** @type {Variant} */ (options.variant === "stable" ? "stable" : "greenfield");
+      if (interactive && options.variant === undefined) {
+        const answer = (await askQuestion("Compatibility rule: greenfield (break freely) or stable (preserve published contracts)? [greenfield] ")).toLowerCase();
+        variant = answer.startsWith("s") ? "stable" : "greenfield";
+      }
+      const result = spawnSync("bash", [AGENTKIT_INSTALLER, cwd, `--${variant}`], { stdio: "inherit" });
+      if (result.error) {
+        stderr(`${result.error.message}\n`);
+        return 1;
+      }
+      if (result.status !== 0) return result.status ?? 1;
+      report.agentkit = true;
+    }
+
+    if (json) stdout(`${JSON.stringify(report, null, 2)}\n`);
+    else stdout(`next · faberun doctor --cwd ${cwd} · faberun campaign init <id> --cwd ${cwd} --goal "..."\n`);
+    return 0;
+  } finally {
+    state.asker?.close();
+  }
+}
+
+/**
+ * Whether `git -C cwd rev-parse --is-inside-work-tree` answers `true`.
+ *
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function isGitWorkTree(cwd) {
+  const result = boundedGitSync(["-C", cwd, "rev-parse", "--is-inside-work-tree"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return !result.error && result.status === 0 && String(result.stdout).trim() === "true";
+}
+
+/**
+ * Add a `.runs/` line to `cwd/.gitignore` unless an equivalent line already
+ * exists, creating the file when missing. A file that does not end in a newline
+ * gets one before the appended line, so the result is always a whole line.
+ *
+ * @param {string} cwd
+ * @returns {string} the `.gitignore` path written or confirmed
+ */
+function ensureRunsIgnored(cwd) {
+  const path = join(cwd, ".gitignore");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const ignored = existing.split(/\r?\n/u).some((line) => {
+    const trimmed = line.trim();
+    return trimmed === ".runs/" || trimmed === ".runs";
+  });
+  if (!ignored) {
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    writeFileSync(path, `${existing}${separator}.runs/\n`);
+  }
+  return path;
+}

package/src/cli/launch.mjs

@@ -0,0 +1,239 @@
+/**
+ * The launcher half of `--detach`: spawn the controller, wait for it to prove it
+ * owns the run, acknowledge, and exit.
+ *
+ * The controller half is `engine/detach.mjs`. They are separate because only
+ * this side knows about `process.argv` and about exiting -- and because the
+ * engine importing the CLI was the one import cycle a layered tree could not
+ * express.
+ *
+ * `writeBootstrapFailure` is what makes a detached failure visible at all: a
+ * child that dies before taking the lock leaves nothing behind unless it writes
+ * why, and the launcher is already gone by then.
+ */
+import { SETTLED } from "../engine/prompts.mjs";
+import { bootstrapAckPath, bootstrapAttemptPath, bootstrapPath, cleanupBootstrapAttempts, readJson, writeJsonAtomic } from "../run/store.mjs";
+import { bootstrapFailureMatchesChild, bootstrapMatchesChild, processStartToken, readLock, sameProcessStartToken, validBootstrapNonce } from "../run/lock.mjs";
+import { cleanupBootstrapNonce } from "../engine/detach.mjs";
+import { delay, errorCode } from "../util.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readRunNodes } from "../engine/scheduler.mjs";
+import { spawn } from "node:child_process";
+import { validateContract } from "../contract/index.mjs";
+
+/**
+ * The file a detached child is spawned as. It must be the CLI and not this
+ * module: `cli.mjs` guards its dispatch on `process.argv[1]` being itself, so a
+ * child started as `launch.mjs` would run no command at all -- which is exactly
+ * what happened when this code moved out of `cli.mjs` and kept using
+ * `import.meta.url`.
+ */
+const CLI_ENTRY = fileURLToPath(new URL("../cli.mjs", import.meta.url));
+
+/** @typedef {import("../cli.mjs").BootstrapRecord} BootstrapRecord */
+/** @typedef {import("node:child_process").ChildProcess & {bootstrapNonce?: string, bootstrapProcessStartToken?: string|null}} DetachedChild */
+/** @typedef {import("../run/lock.mjs").ReadLockResult} ReadLockResult */
+
+/**
+ * @param {string} command
+ * @param {string} target
+ * @param {string[]} [extraArgs]
+ * @returns {DetachedChild}
+ */
+export function detachSelf(command, target, extraArgs = []) {
+  return detachArgv([command, target, ...extraArgs]);
+}
+
+/**
+ * Spawn this CLI as a detached child with a fresh bootstrap nonce, for argv
+ * shapes `detachSelf`'s (command, target) pair cannot express — a campaign
+ * watch is `campaign watch <id>`, not `<command> <target>`. stdio is discarded
+ * exactly as for every detached controller: a foreground launcher is the only
+ * moment an operator is present.
+ *
+ * @param {string[]} argv
+ * @param {{nonce?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {DetachedChild}
+ */
+export function detachArgv(argv, options = {}) {
+  const nonce = options.nonce ?? randomUUID();
+  const child = /** @type {DetachedChild} */ (spawn(process.execPath, [CLI_ENTRY, ...argv], {
+    cwd: process.cwd(),
+    env: { ...process.env, ...options.env, FABERUN_BOOTSTRAP_NONCE: nonce },
+    detached: process.platform !== "win32",
+    stdio: "ignore",
+  }));
+  child.unref();
+  child.bootstrapNonce = nonce;
+  child.bootstrapProcessStartToken = processStartToken(child.pid ?? null);
+  return child;
+}
+/**
+ * @param {string} runDir
+ * @param {number} pid
+ * @param {DetachedChild|null} [child]
+ * @param {number} [timeoutMs]
+ * @returns {Promise<BootstrapRecord>}
+ */
+export async function waitForBootstrap(runDir, pid, child = null, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs;
+  const nonce = child?.bootstrapNonce;
+  if (!nonce) throw new Error(`detached bootstrap has no start nonce for pid ${pid}`);
+  if (!validBootstrapNonce(nonce) || child.pid !== pid) throw new Error(`detached bootstrap has invalid child identity for pid ${pid}`);
+  let expectedProcessStartToken = child.bootstrapProcessStartToken ?? null;
+  let exited = false;
+  child?.once("exit", () => { exited = true; });
+  while (Date.now() < deadline) {
+    const childExited = exited || child?.exitCode !== null || child?.signalCode !== null;
+    if (expectedProcessStartToken === null && !childExited) expectedProcessStartToken = processStartToken(pid);
+    for (const path of [bootstrapAttemptPath(runDir, nonce), bootstrapPath(runDir)]) {
+      try {
+        const bootstrap = /** @type {BootstrapRecord} */ (readJson(path));
+        const childIdentity = bootstrapMatchesChild(bootstrap, pid, nonce, expectedProcessStartToken);
+        if (bootstrap.status === "failed" && bootstrapFailureMatchesChild(bootstrap, pid, nonce, expectedProcessStartToken)) {
+          cleanupBootstrapAttempts(runDir);
+          throw new Error(`detached bootstrap failed: ${bootstrap.error}`);
+        }
+        const lock = readLock(runDir);
+        const currentOwner = lockOwnedBy(lock, pid, expectedProcessStartToken);
+        if (!childExited && bootstrap.status === "ready" && childIdentity && currentOwner && runIsNonterminal(runDir)) {
+          cleanupBootstrapAttempts(runDir);
+          try {
+            writeBootstrapAcknowledgement(runDir, bootstrap, expectedProcessStartToken);
+          } catch (error) {
+            cleanupBootstrapNonce(runDir, nonce);
+            throw error;
+          }
+          return bootstrap;
+        }
+      } catch (error) {
+        if (errorCode(error) !== "ENOENT") {
+          cleanupBootstrapNonce(runDir, nonce);
+          cleanupBootstrapAttempts(runDir);
+          throw error;
+        }
+      }
+    }
+    if (childExited) {
+      try {
+        const failure = /** @type {BootstrapRecord} */ (readJson(bootstrapAttemptPath(runDir, nonce)));
+        if (failure.status === "failed" && bootstrapFailureMatchesChild(failure, pid, nonce, expectedProcessStartToken)) {
+          cleanupBootstrapAttempts(runDir);
+          throw new Error(`detached bootstrap failed: ${failure.error}`);
+        }
+      } catch (error) {
+        if (errorCode(error) !== "ENOENT") {
+          cleanupBootstrapNonce(runDir, nonce);
+          cleanupBootstrapAttempts(runDir);
+          throw error;
+        }
+      }
+      cleanupBootstrapNonce(runDir, nonce);
+      cleanupBootstrapAttempts(runDir);
+      throw new Error(`detached bootstrap failed before readiness for pid ${pid}`);
+    }
+    await delay(50);
+  }
+  cleanupBootstrapNonce(runDir, nonce);
+  cleanupBootstrapAttempts(runDir);
+  throw new Error(`detached bootstrap did not become ready for pid ${pid}`);
+}
+/**
+ * @param {string} runDir
+ * @param {BootstrapRecord} bootstrap
+ * @param {string|null} expectedProcessStartToken
+ */
+export function writeBootstrapAcknowledgement(runDir, bootstrap, expectedProcessStartToken) {
+  if (!bootstrap.nonce) throw new Error("bootstrap record has no nonce");
+  writeJsonAtomic(bootstrapAckPath(runDir, bootstrap.nonce), {
+    status: "acknowledged",
+    nonce: bootstrap.nonce,
+    pid: bootstrap.pid ?? null,
+    processStartToken: expectedProcessStartToken,
+    at: new Date().toISOString(),
+  });
+}
+/**
+ * @param {string} runDir
+ * @returns {boolean}
+ */
+export function runIsNonterminal(runDir) {
+  try {
+    const contractPath = join(runDir, "contract.json");
+    const contract = validateContract(JSON.parse(readFileSync(contractPath, "utf8")), contractPath, { persisted: true });
+    const nodes = readRunNodes(runDir, contract);
+    return nodes.length > 0 && nodes.some((node) => !SETTLED.has(node.status));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return false;
+    throw error;
+  }
+}
+/**
+ * @param {string} command
+ * @param {string|undefined} target
+ * @returns {string|null}
+ */
+export function bootstrapRunDir(command, target) {
+  try {
+    if (command === "run") {
+      if (!target) return null;
+      const path = resolve(target);
+      const contract = validateContract(JSON.parse(readFileSync(path, "utf8")), path);
+      return join(contract.cwd, ".runs", contract.id);
+    }
+    if (["resume", "cancel"].includes(command)) {
+      if (!target) return null;
+      return resolve(target);
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+/**
+ * @param {string} command
+ * @param {string|undefined} target
+ * @param {Error} error
+ */
+export function writeBootstrapFailure(command, target, error) {
+  const runDir = bootstrapRunDir(command, target);
+  if (!runDir || !existsSync(runDir)) return;
+  const nonce = validBootstrapNonce(process.env.FABERUN_BOOTSTRAP_NONCE) ? process.env.FABERUN_BOOTSTRAP_NONCE : null;
+  const failure = { status: "failed", pid: process.pid, processStartToken: processStartToken(process.pid), runDir, nonce, at: new Date().toISOString(), error: error.message };
+  if (command === "run" && existsSync(join(runDir, "contract.json"))) return;
+  /** @type {BootstrapRecord|null} */
+  let current = null;
+  try {
+    current = /** @type {BootstrapRecord} */ (readJson(bootstrapPath(runDir)));
+    const controllerLock = readLock(runDir);
+    const currentOwnerActive = current.status === "ready" && current.pid !== process.pid
+      && lockOwnedBy(controllerLock, current.pid, current.processStartToken);
+    if (currentOwnerActive) return;
+  } catch (readError) {
+    if (errorCode(readError) !== "ENOENT") return;
+  }
+  // Only a detached bootstrap child records an attempt file for its own nonce;
+  // a --detach parent that observed the failure must not recreate attempt
+  // artifacts with an ambient nonce it does not own.
+  if (nonce && !process.argv.includes("--detach") && !(current?.status === "ready" && current.pid === process.pid)) {
+    try { writeJsonAtomic(bootstrapAttemptPath(runDir, nonce), failure); } catch {
+      // Best-effort record: a failed attempt write must not mask the bootstrap error being reported.
+    }
+  }
+  try { writeJsonAtomic(bootstrapPath(runDir), failure); } catch {
+    // Best-effort record: there is nothing left to do if this write fails too.
+  }
+}
+/**
+ * @param {import("../run/lock.mjs").ReadLockResult} lock
+ * @param {number|undefined} pid
+ * @param {string|null|undefined} processStartToken
+ * @returns {boolean}
+ */
+function lockOwnedBy(lock, pid, processStartToken) {
+  return lock !== null && !lock.invalid && lock.pid === pid
+    && sameProcessStartToken(lock.processStartToken, processStartToken);
+}

package/src/cli/seat.mjs

@@ -0,0 +1,139 @@
+/**
+ * `seat` argv: start, attach, status, stop, switch.
+ *
+ * Per-operation options only, so a flag declared for one operation is rejected
+ * for the others. The facade in `src/seat/index.mjs` owns the behavior; this
+ * file owns the wire, the same split `campaign.mjs` uses.
+ */
+import { parseArgs as parseFlags } from "node:util";
+import { attachSeat, seatStatus, startSeat, stopSeat, switchSeat } from "../seat/index.mjs";
+
+/** @typedef {{cwd?: string, harness?: string, ssh?: string, json?: boolean}} SeatValues */
+
+/** Flags are scoped to the operations that declare them; all other flags are rejected. */
+/** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
+const OPERATION_OPTIONS = {
+  start: { cwd: { type: "string" }, harness: { type: "string" } },
+  attach: { cwd: { type: "string" }, ssh: { type: "string" } },
+  status: { cwd: { type: "string" }, json: { type: "boolean" } },
+  stop: { cwd: { type: "string" } },
+  switch: { cwd: { type: "string" }, harness: { type: "string" } },
+};
+
+/**
+ * @param {string[]} args
+ * @returns {void}
+ */
+export function seatCli(args) {
+  const operation = args[0];
+  if (!operation || !(operation in OPERATION_OPTIONS)) return usage();
+  let parsed;
+  try {
+    parsed = parseFlags({ args: args.slice(1), options: OPERATION_OPTIONS[operation], allowPositionals: true, strict: true });
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return usage();
+  }
+  const [campaign, ...extra] = parsed.positionals;
+  const values = /** @type {SeatValues} */ (parsed.values);
+  if (extra.length) return usage();
+  if (operation === "status") {
+    if (campaign !== undefined) return usage();
+    return reportStatus(values);
+  }
+  if (operation === "start") {
+    if (!campaign) return usage();
+    return reportStart(campaign, values);
+  }
+  if (operation === "attach") return reportAttach(campaign, values);
+  if (operation === "stop") return reportStop(campaign);
+  if (operation === "switch") {
+    if (!values.harness) return usage();
+    return reportSwitch(campaign, values);
+  }
+  return usage();
+}
+
+/**
+ * @param {string} campaign
+ * @param {SeatValues} values
+ */
+function reportStart(campaign, values) {
+  const result = startSeat({ campaign, harness: values.harness, cwd: values.cwd });
+  if (!result.ok) {
+    process.stderr.write(`[seat] ${result.message ?? result.reason}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`[seat] ${campaign} started with ${result.harness} · ${result.session}:${campaign}\n`);
+  process.stdout.write(`${result.attachCommand}\n`);
+}
+
+/**
+ * @param {string|undefined} campaign
+ * @param {SeatValues} values
+ */
+function reportAttach(campaign, values) {
+  const result = attachSeat({ campaign, ssh: values.ssh });
+  if (!result.ok) {
+    process.stderr.write(`[seat] ${result.message ?? "cannot reattach to the seat"}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${result.command}\n`);
+}
+
+/**
+ * @param {SeatValues} values
+ */
+function reportStatus(values) {
+  const status = seatStatus();
+  if (values.json === true) {
+    process.stdout.write(`${JSON.stringify(status)}\n`);
+    return;
+  }
+  if (!status.tmux) {
+    process.stdout.write("[seat] tmux is not available; no seat can be listed\n");
+    return;
+  }
+  if (!status.seats.length) {
+    process.stdout.write(`[seat] ${status.session} has no windows\n`);
+    return;
+  }
+  for (const seat of status.seats) {
+    process.stdout.write(`[seat] ${seat.campaign} · harness ${seat.harness ?? "unknown"} · ambient ${seat.canRenderAmbient ? "yes" : "no"}\n`);
+  }
+}
+
+/**
+ * @param {string|undefined} campaign
+ */
+function reportStop(campaign) {
+  const result = stopSeat({ campaign });
+  if (!result.ok) {
+    process.stderr.write(`[seat] ${result.reason ?? "stop failed"}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(campaign ? `[seat] ${campaign} stopped\n` : "[seat] seat session stopped\n");
+}
+
+/**
+ * @param {string|undefined} campaign
+ * @param {SeatValues} values
+ */
+function reportSwitch(campaign, values) {
+  const result = switchSeat({ campaign, harness: values.harness, cwd: values.cwd });
+  if (!result.ok) {
+    process.stderr.write(`[seat] ${result.message ?? result.reason}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`[seat] ${result.campaign} switched to ${result.harness} · ${result.session}:${result.window}\n`);
+  process.stdout.write(`${result.attachCommand}\n`);
+}
+
+function usage() {
+  process.stderr.write("usage: faberun seat <start|attach|status|stop|switch> [<campaign-id>] [--cwd <dir>] ...\n");
+  process.exitCode = 2;
+}