@rigkit/cli 0.0.0-canary-20260518T014918-c5bc0c2

package/src/cli.ts

@@ -0,0 +1,2496 @@
+#!/usr/bin/env bun
+import { existsSync, rmSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { Command, CommanderError, Option } from "commander";
+import inquirer from "inquirer";
+import * as ui from "./ui.ts";
+import {
+  getOrStartRuntime,
+  defaultRigkitHome,
+  type RuntimeClient,
+} from "@rigkit/runtime-client";
+import {
+  type DevMachineEvent,
+  type WorkflowPlan,
+  type SnapshotRecord,
+  type WorkspaceRecord,
+} from "@rigkit/engine";
+import {
+  cmuxHostCapabilities,
+  type CmuxHostCapabilityHandler,
+} from "@rigkit/provider-cmux/host";
+import { DEFAULT_CONFIG_FILE, discoverProjectConfigs, resolveConfigPaths, PROJECT_PACKAGE_NAME } from "./project.ts";
+import { RIGKIT_CLI_VERSION } from "./version.ts";
+import { initProject, normalizeMachineName, type InitProjectResult } from "./init.ts";
+import { openExternalTarget } from "./interaction.ts";
+import { createRunPresenter, type RunPresenter } from "./run-presenter.ts";
+import { createRunLogger, type RunLogger } from "./run-logger.ts";
+import {
+  completeRig,
+  formatCompletionItems,
+  renderCompletionScript,
+  resolveCompletionShell,
+  type CompletionShell,
+} from "./completion.ts";
+import { generateWorkspaceName } from "./workspace-name.ts";
+
+type GlobalOptions = {
+  chdir?: string;
+  config?: string;
+  state?: string;
+  json: boolean;
+};
+
+type CliInvocation = {
+  global: GlobalOptions;
+  json: boolean;
+};
+
+type InitOptions = {
+  force: boolean;
+  name?: string;
+  apiKey?: string;
+  packageManager?: PackageManager;
+};
+
+type CompletionOptions = {
+  shell?: CompletionShell;
+  index?: string;
+};
+
+type DoctorOptions = {
+  cli: boolean;
+};
+
+type RunOptions = {
+  all: boolean;
+  discover: boolean;
+};
+
+type ListOptions = {
+  target?: string;
+};
+
+type CacheClearOptions = {
+  local: boolean;
+  global: boolean;
+  all: boolean;
+};
+
+type PackageManager = "npm" | "bun" | "pnpm" | "skip";
+
+type InitInstallResult = {
+  packageManager: PackageManager;
+  command?: string;
+  skipped: boolean;
+  reported?: boolean;
+};
+
+type EngineProjectInfo = {
+  projectDir: string;
+  configPath: string;
+  statePath: string;
+  workflow?: {
+    name: string;
+    providers: string[];
+  };
+};
+
+type RuntimeOperationManifest = {
+  operations: RuntimeOperationDefinition[];
+  workspaceOperations?: RuntimeOperationDefinition[];
+};
+
+type RuntimeOperationDefinition = {
+  id: string;
+  aliases?: string[];
+  title?: string;
+  description?: string;
+  createsWorkspace?: boolean;
+  cli?: {
+    positionals?: Array<{ name: string; index: number }>;
+    options?: Array<{
+      name: string;
+      flag: string;
+      aliases?: string[];
+      required?: boolean;
+      runtime?: boolean;
+      type?: "string" | "boolean" | "number";
+    }>;
+  };
+  inputSchema?: {
+    properties?: Record<string, { type?: string; default?: unknown }>;
+    required?: string[];
+  };
+};
+
+type RuntimeOperationCliOption = NonNullable<NonNullable<RuntimeOperationDefinition["cli"]>["options"]>[number];
+
+type ParsedOperationInput = {
+  input: Record<string, unknown>;
+  hostOptions: Record<string, unknown>;
+};
+
+const CLI_HOST_METHODS = [
+  { id: "message.show" },
+  { id: "prompt.text" },
+  { id: "prompt.confirm" },
+  { id: "prompt.select" },
+  { id: "open.external" },
+  { id: "host.command.run", modes: ["capture", "interactive"] },
+];
+
+const CLI_HOST_CAPABILITY_HANDLERS = new Map<string, CmuxHostCapabilityHandler>(
+  cmuxHostCapabilities.map((capability) => [capability.id, capability]),
+);
+
+const CLI_HOST_CAPABILITIES: Array<{ id: string; schemaHash?: string }> = [
+  ...CLI_HOST_CAPABILITY_HANDLERS.values(),
+].map((capability) => ({
+  id: capability.id,
+  ...(capability.schemaHash ? { schemaHash: capability.schemaHash } : {}),
+}));
+
+const TERRAFORM_STYLE_GLOBAL_OPTIONS = new Set(["chdir", "config", "state", "json", "help", "version"]);
+const STATIC_COMMANDS = new Set([
+  "init",
+  "plan",
+  "apply",
+  "create",
+  "rm",
+  "run",
+  "ls",
+  "cache",
+  "projects",
+  "doctor",
+  "version",
+  "help",
+  "completion",
+]);
+
+if (process.argv[2] === "__complete") {
+  runCompletionEndpoint(process.argv.slice(3)).catch(handleCliError);
+} else {
+  runCli(normalizeCliArgv(process.argv)).catch(handleCliError);
+}
+
+function normalizeCliArgv(argv: string[]): string[] {
+  const normalized = argv.slice();
+  for (let index = 2; index < normalized.length; index += 1) {
+    const arg = normalized[index]!;
+    if (arg === "--") break;
+    if (!arg.startsWith("-")) {
+      if (STATIC_COMMANDS.has(arg)) break;
+      continue;
+    }
+
+    const match = /^-([A-Za-z][A-Za-z0-9-]*)(=.*)?$/.exec(arg);
+    if (!match) continue;
+    const name = match[1]!;
+    if (!TERRAFORM_STYLE_GLOBAL_OPTIONS.has(name)) continue;
+    normalized[index] = `--${name}${match[2] ?? ""}`;
+  }
+  return normalized;
+}
+
+async function runCli(argv: string[]): Promise<void> {
+  const program = new Command();
+  program
+    .name("rig")
+    .description("Rigkit workflow CLI")
+    .usage("[global options] <command> [args]")
+    .version(RIGKIT_CLI_VERSION, "-v, --version", "Show Rigkit CLI version")
+    .showHelpAfterError()
+    .exitOverride()
+    .argument("[command]")
+    .addOption(new Option("--chdir <dir>", `Switch to a directory containing ${DEFAULT_CONFIG_FILE} before running the command`).hideHelp())
+    .addOption(new Option("--config <file>", "Config file to load, relative to -chdir when set").hideHelp())
+    .addOption(new Option("--state <file>", "Local runtime state database path").hideHelp())
+    .addOption(new Option("--json", "Print machine-readable JSON where supported").hideHelp())
+    .addHelpText("after", [
+      "",
+      "Global Options:",
+      "  -chdir=DIR    Switch to a directory containing rig.config.ts before running the command",
+      "  -config=FILE  Config file to load, relative to -chdir when set",
+      "  -state=FILE   Local runtime state database path",
+      "  -json         Print machine-readable JSON where supported",
+    ].join("\n"))
+    .action(async (command?: string) => {
+      if (command) program.error(`unknown command '${command}'`);
+      await runHelp(makeInvocation(rootOptions(program)));
+    });
+
+  program
+    .command("init")
+    .description("Initialize a Rigkit project")
+    .option("--name <name>", "Project and workflow name")
+    .option("--api-key <apiKey>", "Freestyle API key")
+    .option("--package-manager <packageManager>", "Install with npm, bun, pnpm, or skip")
+    .option("--force", "Overwrite an existing config file")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: {
+      name?: string;
+      apiKey?: string;
+      packageManager?: string;
+      force?: boolean;
+      json?: boolean;
+    }) => {
+      await runInit(makeInvocation(rootOptions(program), options.json), {
+        name: options.name,
+        apiKey: options.apiKey,
+        packageManager: parsePackageManagerOption(options.packageManager),
+        force: Boolean(options.force),
+      });
+    });
+
+  for (const operation of ["plan", "apply"] as const) {
+    program
+      .command(`${operation} [args...]`)
+      .description(operation === "plan" ? "Plan project workflow changes" : "Apply project workflow changes")
+      .allowUnknownOption(true)
+      .option("--all", "Run against every discovered project")
+      .option("--discover", "Discover projects below the selected directory")
+      .option("--json", "Print machine-readable JSON")
+      .action(async (args: string[], options: { all?: boolean; discover?: boolean; json?: boolean }) => {
+        await runProjectOperation(makeInvocation(rootOptions(program), options.json), operation, args ?? [], {
+          all: Boolean(options.all),
+          discover: Boolean(options.discover),
+        });
+      });
+  }
+
+  program
+    .command("create [args...]")
+    .description("Create a workspace")
+    .allowUnknownOption(true)
+    .option("--json", "Print machine-readable JSON")
+    .action(async (args: string[], options: { json?: boolean }) => {
+      await runProjectOperation(makeInvocation(rootOptions(program), options.json), "create", args ?? [], {
+        all: false,
+        discover: false,
+      });
+    });
+
+  program
+    .command("rm [workspace]")
+    .description("Remove one workspace, several via multi-select, or every workspace")
+    .option("-y, --yes", "Remove without confirmation")
+    .option("--all", "Remove every workspace in this project")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (workspace: string | undefined, options: { yes?: boolean; all?: boolean; json?: boolean }) => {
+      await runRemove(
+        makeInvocation(rootOptions(program), options.json),
+        {
+          workspace,
+          yes: Boolean(options.yes),
+          all: Boolean(options.all),
+        },
+      );
+    });
+
+  program
+    .command("run <workspace> <operation> [args...]")
+    .description("Run a workspace operation")
+    .allowUnknownOption(true)
+    .option("--json", "Print machine-readable JSON")
+    .action(async (
+      workspace: string,
+      operation: string,
+      args: string[],
+      options: { json?: boolean },
+    ) => {
+      await runWorkspaceOperation(makeInvocation(rootOptions(program), options.json), workspace, operation, args ?? []);
+    });
+
+  program
+    .command("ls [target]")
+    .description("List project workspaces")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (target: string | undefined, options: { json?: boolean }) => {
+      await runList(makeInvocation(rootOptions(program), options.json), { target });
+    });
+
+  const cache = program
+    .command("cache")
+    .description("Inspect and clear Rigkit cache");
+
+  cache
+    .command("ls")
+    .description("List cache entries for the selected project config")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: { json?: boolean }) => {
+      await runCacheList(makeInvocation(rootOptions(program), options.json));
+    });
+
+  cache
+    .command("clear")
+    .description("Clear cache entries")
+    .option("--local", "Clear local cache entries for the selected config")
+    .option("--global", "Clear global cache fragments")
+    .option("--all", "With --global, clear every global fragment without loading a config")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: { local?: boolean; global?: boolean; all?: boolean; json?: boolean }) => {
+      await runCacheClear(makeInvocation(rootOptions(program), options.json), {
+        local: Boolean(options.local),
+        global: Boolean(options.global),
+        all: Boolean(options.all),
+      });
+    });
+
+  cache
+    .command("invalidate [step]")
+    .description("Invalidate cached task outputs so they re-run on next plan/apply")
+    .option("--all", "Invalidate every cached task in this project's workflow")
+    .option("-y, --yes", "Skip confirmation when invalidating --all")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (step: string | undefined, options: { all?: boolean; yes?: boolean; json?: boolean }) => {
+      await runCacheInvalidate(makeInvocation(rootOptions(program), options.json), {
+        step,
+        all: Boolean(options.all),
+        yes: Boolean(options.yes),
+      });
+    });
+
+  program
+    .command("projects")
+    .description("Discover Rigkit projects below the current directory")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: { json?: boolean }) => {
+      await runProjects(makeInvocation(rootOptions(program), options.json));
+    });
+
+  program
+    .command("doctor")
+    .description("Show Rigkit runtime diagnostics")
+    .option("--cli", "Show CLI diagnostics without connecting to a project runtime")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: { cli?: boolean; json?: boolean }) => {
+      await runDoctor(makeInvocation(rootOptions(program), options.json), { cli: Boolean(options.cli) });
+    });
+
+  program
+    .command("version")
+    .description("Show Rigkit CLI version")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: { json?: boolean }) => {
+      await runVersion(makeInvocation(rootOptions(program), options.json));
+    });
+
+  program
+    .command("help")
+    .description("Show Rigkit CLI help")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: { json?: boolean }) => {
+      await runHelp(makeInvocation(rootOptions(program), options.json));
+    });
+
+  program
+    .command("completion [shell]")
+    .description("Generate shell completion script")
+    .action((shell?: string) => {
+      console.log(renderCompletionScript(resolveCompletionShell(shell)));
+    });
+  await program.parseAsync(argv);
+}
+
+function rootOptions(program: Command): GlobalOptions {
+  const options = program.opts<{
+    chdir?: string;
+    config?: string;
+    state?: string;
+    json?: boolean;
+  }>();
+  return {
+    chdir: options.chdir,
+    config: options.config,
+    state: options.state,
+    json: Boolean(options.json),
+  };
+}
+
+function parsePackageManagerOption(value: string | undefined): PackageManager | undefined {
+  if (value === undefined) return undefined;
+  if (isPackageManager(value)) return value;
+  throw new Error(`Unknown package manager ${value}. Expected npm, bun, pnpm, or skip.`);
+}
+
+function makeInvocation(global: GlobalOptions, commandJson = false): CliInvocation {
+  return {
+    global,
+    json: Boolean(global.json || commandJson),
+  };
+}
+
+async function runCompletionEndpoint(args: string[]): Promise<void> {
+  const options = parseCompletionEndpointArgs(args);
+  const shell = resolveCompletionShell(options.shell);
+  const currentIndex = options.index === undefined ? undefined : Number(options.index);
+  const items = await completeRig({
+    words: options.words,
+    currentIndex: Number.isFinite(currentIndex) ? currentIndex : undefined,
+    cwd: process.cwd(),
+  });
+  const output = formatCompletionItems(items, shell);
+  if (output) console.log(output);
+}
+
+function parseCompletionEndpointArgs(args: string[]): CompletionOptions & { words: string[] } {
+  const words: string[] = [];
+  const options: CompletionOptions = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (arg === "--") {
+      words.push(...args.slice(index + 1));
+      break;
+    }
+    if (arg === "--shell") {
+      options.shell = args[++index] as CompletionShell | undefined;
+      continue;
+    }
+    if (arg.startsWith("--shell=")) {
+      options.shell = arg.slice("--shell=".length) as CompletionShell;
+      continue;
+    }
+    if (arg === "--index") {
+      options.index = args[++index];
+      continue;
+    }
+    if (arg.startsWith("--index=")) {
+      options.index = arg.slice("--index=".length);
+      continue;
+    }
+    words.push(arg);
+  }
+
+  return { ...options, words };
+}
+
+// Errors already rendered to the user (via printRunFailure or similar) carry
+// this sentinel so handleCliError doesn't re-print the message a second time.
+class DisplayedCliError extends Error {
+  readonly displayed = true as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "DisplayedCliError";
+  }
+}
+
+function handleCliError(error: unknown): void {
+  if (error instanceof CommanderError) {
+    process.exitCode = error.exitCode;
+    return;
+  }
+  if (error instanceof DisplayedCliError) {
+    process.exitCode = 1;
+    return;
+  }
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
+
+async function runInit(invocation: CliInvocation, options: InitOptions): Promise<void> {
+  const answers = await resolveInitAnswers(options, wantsJson(invocation));
+  const paths = resolveInitProjectPaths(invocation, answers.name);
+
+  if (existsSync(paths.configPath) && !options.force) {
+    throw new Error(`${paths.configPath} already exists. Pass --force to overwrite it.`);
+  }
+
+  const result = initProject({
+    projectDir: paths.projectDir,
+    configPath: paths.configPath,
+    name: answers.name,
+    apiKey: answers.apiKey,
+    force: options.force,
+  });
+  const install = await runPackageManagerInstall(paths.projectDir, answers.packageManager, wantsJson(invocation));
+
+  if (wantsJson(invocation)) {
+    printJson({ ...result, install });
+    return;
+  }
+
+  printInitResult(result, install);
+}
+
+async function resolveInitAnswers(
+  options: InitOptions,
+  jsonMode: boolean,
+): Promise<{ name: string; apiKey?: string; packageManager: PackageManager }> {
+  if (jsonMode && options.name === undefined) {
+    throw new Error(`rig init --json requires --name`);
+  }
+
+  if (jsonMode && options.packageManager && options.packageManager !== "skip") {
+    throw new Error(`rig init --json only supports --package-manager skip`);
+  }
+
+  if (options.name === undefined) {
+    assertInteractiveInit();
+  }
+
+  if (!jsonMode) {
+    console.log(`${ui.bold("rig")} ${ui.dim("· initialize")}`);
+    console.log("");
+  }
+
+  const name = options.name !== undefined
+    ? normalizeMachineName(options.name)
+    : await promptName();
+  const apiKey = options.apiKey?.trim();
+  const packageManager = options.packageManager ?? (jsonMode || !canPrompt() ? "skip" : await promptPackageManager("skip"));
+
+  return {
+    name,
+    apiKey,
+    packageManager,
+  };
+}
+
+function assertInteractiveInit(): void {
+  if (canPrompt()) return;
+  throw new Error(`rig init needs --name when not running in an interactive terminal`);
+}
+
+function canPrompt(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function resolveInitProjectPaths(invocation: CliInvocation, name: string): { projectDir: string; configPath: string } {
+  const options = invocation.global;
+  if (options.config) {
+    throw new Error(`rig init does not support -config. Use -chdir to choose the parent directory.`);
+  }
+
+  const parentDir = resolve(process.cwd(), options.chdir ?? ".");
+  const projectDir = resolve(parentDir, name);
+  return {
+    projectDir,
+    configPath: join(projectDir, DEFAULT_CONFIG_FILE),
+  };
+}
+
+async function promptName(): Promise<string> {
+  const answers = await inquirer.prompt<{ name: string }>([{
+    type: "input",
+    name: "name",
+    message: "Project name:",
+    validate(value: string) {
+      try {
+        normalizeMachineName(value);
+        return true;
+      } catch (error) {
+        return error instanceof Error ? error.message : String(error);
+      }
+    },
+    filter: (value: string) => normalizeMachineName(value),
+  }]);
+  return answers.name;
+}
+
+async function promptPackageManager(defaultValue: PackageManager): Promise<PackageManager> {
+  const choices: Array<{ value: PackageManager; label: string; hint: string }> = [
+    { value: "npm", label: "npm", hint: "npm install" },
+    { value: "bun", label: "bun", hint: "bun install" },
+    { value: "pnpm", label: "pnpm", hint: "pnpm install" },
+    { value: "skip", label: "skip", hint: "do not install now" },
+  ];
+  const answers = await inquirer.prompt<{ packageManager: PackageManager }>([{
+    type: "select",
+    name: "packageManager",
+    message: "Install dependencies?",
+    default: defaultValue,
+    choices: choices.map((choice) => ({
+      name: choice.label,
+      value: choice.value,
+      description: choice.hint,
+    })),
+  }]);
+  return answers.packageManager;
+}
+
+async function promptWorkspaceName(defaultValue: string): Promise<string> {
+  const answers = await inquirer.prompt<{ name: string }>([{
+    type: "input",
+    name: "name",
+    message: "Workspace name:",
+    default: defaultValue,
+    validate(value: string) {
+      return validateWorkspaceName(value.trim());
+    },
+    filter: (value: string) => value.trim(),
+  }]);
+  return answers.name;
+}
+
+const workspaceNamePattern = /^(?!-)[A-Za-z0-9._-]+$/;
+
+function validateWorkspaceName(value: string): true | string {
+  if (!value) return "Workspace name is required.";
+  if (!workspaceNamePattern.test(value)) {
+    return 'Use only letters, numbers, ".", "_", and "-", and do not start with "-".';
+  }
+  return true;
+}
+
+function assertValidWorkspaceName(value: unknown): void {
+  if (typeof value !== "string") throw new Error(`Workspace name must be a string`);
+  const valid = validateWorkspaceName(value);
+  if (valid !== true) throw new Error(`Invalid workspace name "${value}". ${valid}`);
+}
+
+async function defaultWorkspaceName(runtime: RuntimeClient): Promise<string> {
+  const existingNames = await runtime.control.workspaces()
+    .then((response) => response.workspaces.map((workspace) => workspace.name))
+    .catch(() => []);
+  return generateWorkspaceName(existingNames);
+}
+
+async function runPackageManagerInstall(
+  projectDir: string,
+  packageManager: PackageManager,
+  jsonMode: boolean,
+): Promise<InitInstallResult> {
+  if (packageManager === "skip") {
+    return { packageManager, skipped: true };
+  }
+
+  const command = packageManagerInstallCommand(packageManager);
+  if (!jsonMode) {
+    process.stderr.write(`${ui.accent(ui.sym.active)} ${ui.dim(`$ ${command.join(" ")}`)}\n`);
+  }
+
+  const proc = Bun.spawn(command, {
+    cwd: projectDir,
+    stdin: "inherit",
+    stdout: jsonMode ? "pipe" : "inherit",
+    stderr: jsonMode ? "pipe" : "inherit",
+  });
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    throw new Error(`${command.join(" ")} failed with exit code ${exitCode}`);
+  }
+
+  return { packageManager, command: command.join(" "), skipped: false };
+}
+
+function printInitResult(result: InitProjectResult, install: InitInstallResult): void {
+  console.log(`${ui.ok(ui.sym.ok)} ${ui.bold(result.name)} ${ui.dim("ready")}`);
+  console.log("");
+
+  const fileLines = [
+    ui.fileStatus(initStatus(result.created.config, false), shortPath(result.configPath)),
+    ui.fileStatus(initStatus(result.created.env, result.updated.envApiKey), shortPath(result.envPath)),
+    ui.fileStatus(initStatus(result.created.envExample, false), shortPath(result.envExamplePath)),
+    ui.fileStatus(initStatus(result.created.packageJson, result.updated.packageJson), shortPath(result.packageJsonPath)),
+    ui.fileStatus(initStatus(result.created.gitignore, result.updated.gitignore), shortPath(result.gitignorePath)),
+  ];
+  if (result.updated.sdkDependency) {
+    fileLines.push(ui.fileStatus("pinned", `${PROJECT_PACKAGE_NAME}@${RIGKIT_CLI_VERSION}`));
+  }
+  for (const line of fileLines) console.log(line);
+
+  if (!install.skipped && install.command && !install.reported) {
+    console.log(ui.fileStatus("created", install.command));
+  }
+
+  console.log("");
+  console.log(ui.bold("Next"));
+  console.log(ui.hint(`cd ${displayProjectDir(result.projectDir)}`));
+  if (install.skipped) {
+    console.log(ui.hint(detectInstallCommand(result.packageJsonPath)));
+  }
+  console.log(ui.hint("rig plan"));
+}
+
+function initStatus(created: boolean, updated: boolean): ui.FileStatus {
+  if (created) return "created";
+  if (updated) return "updated";
+  return "kept";
+}
+
+function shortPath(path: string): string {
+  const rel = relative(process.cwd(), path);
+  return rel && !rel.startsWith("..") ? rel : path;
+}
+
+function displayProjectDir(projectDir: string): string {
+  const path = relative(process.cwd(), projectDir);
+  return path && !path.startsWith("..") ? path : projectDir;
+}
+
+function detectInstallCommand(packageJsonPath: string): string {
+  const projectDir = dirname(packageJsonPath);
+  if (existsSync(join(projectDir, "bun.lock")) || existsSync(join(projectDir, "bun.lockb"))) return "bun install";
+  if (existsSync(join(projectDir, "pnpm-lock.yaml"))) return "pnpm install";
+  if (existsSync(join(projectDir, "yarn.lock"))) return "yarn install";
+  if (existsSync(join(projectDir, "package-lock.json"))) return "npm install";
+  return "npm install";
+}
+
+function isPackageManager(value: string): value is PackageManager {
+  return value === "npm" || value === "bun" || value === "pnpm" || value === "skip";
+}
+
+function packageManagerInstallCommand(packageManager: Exclude<PackageManager, "skip">): string[] {
+  switch (packageManager) {
+    case "bun":
+      return ["bun", "install"];
+    case "pnpm":
+      return ["pnpm", "install"];
+    case "npm":
+      return ["npm", "install"];
+  }
+}
+
+async function runProjectOperation(
+  invocation: CliInvocation,
+  requestedOperation: string,
+  args: string[],
+  options: RunOptions,
+): Promise<void> {
+  if (options.all || options.discover) {
+    await runDiscoveredProjectOperation(invocation, requestedOperation, args, { all: options.all });
+    return;
+  }
+
+  const runtime = await loadRuntime(invocation);
+  const { operation, parsed, result } = await executeRuntimeOperation(
+    invocation,
+    runtime,
+    requestedOperation,
+    args,
+  );
+
+  if (wantsJson(invocation)) {
+    printJson(result);
+    return;
+  }
+
+  await renderOperationResult(operation, result, parsed.hostOptions);
+  if (operation.createsWorkspace && isWorkspaceRecord(result)) {
+    await printWorkspaceNextSteps(runtime, result.name);
+  }
+  printInteractiveOutputGap(invocation);
+}
+
+async function runWorkspaceOperation(
+  invocation: CliInvocation,
+  workspaceName: string,
+  requestedOperation: string,
+  args: string[],
+): Promise<void> {
+  const runtime = await loadRuntime(invocation);
+  const manifest = await readRuntimeOperations(runtime);
+  const operation = (manifest.workspaceOperations ?? []).find((item) =>
+    item.id === requestedOperation || item.aliases?.includes(requestedOperation)
+  );
+  if (!operation) {
+    throw new Error(`This project does not define a workspace operation named "${requestedOperation}".`);
+  }
+
+  const workspaces = await runtime.control.workspaces()
+    .then((response) => response.workspaces as WorkspaceRecord[])
+    .catch(() => []);
+  if (!workspaces.some((workspace) => workspace.name === workspaceName)) {
+    throw new Error(`This project does not have a workspace named "${workspaceName}".`);
+  }
+
+  const parsed = parseOperationArgs(operation, args);
+  enforceHostOnlyBooleanGuards(operation, parsed);
+
+  const result = await runRuntimeOperation<unknown>(
+    runtime,
+    `${workspaceName}/${operation.id}`,
+    parsed.input,
+    { renderEvents: !wantsJson(invocation) },
+  );
+
+  if (wantsJson(invocation)) {
+    printJson(result);
+    return;
+  }
+
+  await renderOperationResult(operation, result, parsed.hostOptions);
+  printInteractiveOutputGap(invocation);
+}
+
+async function runRemove(
+  invocation: CliInvocation,
+  options: { workspace?: string; yes: boolean; all: boolean },
+): Promise<void> {
+  if (options.workspace && options.all) {
+    throw new Error(`rig rm accepts either a workspace name or --all, not both`);
+  }
+
+  if (options.workspace) {
+    await runRemoveWorkspaceOperation(invocation, options.workspace, { yes: options.yes });
+    return;
+  }
+
+  const runtime = await loadRuntime(invocation);
+  const workspaces = await runtime.control.workspaces()
+    .then((response) => response.workspaces as WorkspaceRecord[])
+    .catch(() => []);
+  if (workspaces.length === 0) {
+    if (wantsJson(invocation)) {
+      printJson({ removed: [] });
+      return;
+    }
+    console.log(ui.dim("no workspaces"));
+    return;
+  }
+
+  let targets: string[];
+  if (options.all) {
+    if (!options.yes && !wantsJson(invocation) && canPrompt()) {
+      const confirmed = await promptHostConfirm({
+        message: `Remove all ${workspaces.length} workspaces?`,
+        defaultValue: false,
+      });
+      if (!confirmed) throw new Error("Remove cancelled");
+    } else if (!options.yes && !canPrompt()) {
+      throw new Error(`rig rm --all needs --yes when not running in an interactive terminal`);
+    }
+    targets = workspaces.map((workspace) => workspace.name);
+  } else {
+    if (wantsJson(invocation) || !canPrompt()) {
+      throw new Error(`rig rm needs a workspace name or --all when not running in an interactive terminal`);
+    }
+    targets = await promptWorkspaceRemoveSelection(workspaces);
+    if (targets.length === 0) throw new Error("Nothing selected");
+  }
+
+  const removed: string[] = [];
+  for (const name of targets) {
+    await runRemoveWorkspaceOperation(invocation, name, { yes: true });
+    removed.push(name);
+  }
+  if (wantsJson(invocation)) printJson({ removed });
+}
+
+async function promptWorkspaceRemoveSelection(
+  workspaces: ReadonlyArray<Pick<WorkspaceRecord, "name" | "workflow">>,
+): Promise<string[]> {
+  const answers = await inquirer.prompt<{ names: string[] }>([{
+    type: "checkbox",
+    name: "names",
+    message: "Select workspaces to remove",
+    choices: workspaces.map((workspace) => ({
+      name: workspace.name,
+      value: workspace.name,
+      description: workspace.workflow ? `workflow ${workspace.workflow}` : undefined,
+    })),
+  }]);
+  return answers.names;
+}
+
+async function runRemoveWorkspaceOperation(
+  invocation: CliInvocation,
+  workspaceName: string,
+  options: { yes: boolean },
+): Promise<void> {
+  const runtime = await loadRuntime(invocation);
+  const manifest = await readRuntimeOperations(runtime);
+  const operation = (manifest.workspaceOperations ?? []).find((item) => item.id === "remove");
+  if (!operation) {
+    throw new Error(`This project does not define a removable workspace.`);
+  }
+
+  const workspaces = await runtime.control.workspaces()
+    .then((response) => response.workspaces as WorkspaceRecord[])
+    .catch(() => []);
+  if (!workspaces.some((workspace) => workspace.name === workspaceName)) {
+    throw new Error(`This project does not have a workspace named "${workspaceName}".`);
+  }
+
+  if (!options.yes && !wantsJson(invocation) && canPrompt()) {
+    const confirmed = await promptHostConfirm({
+      message: `Remove workspace ${workspaceName}?`,
+      defaultValue: false,
+    });
+    if (!confirmed) throw new Error("Remove cancelled");
+    options = { yes: true };
+  }
+
+  const parsed = parseOperationArgs(operation, options.yes ? ["--yes"] : []);
+  enforceHostOnlyBooleanGuards(operation, parsed);
+
+  const result = await runRuntimeOperation<unknown>(
+    runtime,
+    `${workspaceName}/remove`,
+    parsed.input,
+    { renderEvents: !wantsJson(invocation) },
+  );
+
+  if (wantsJson(invocation)) {
+    printJson(result);
+    return;
+  }
+
+  await renderOperationResult(operation, result, parsed.hostOptions);
+  printInteractiveOutputGap(invocation);
+}
+
+async function runDiscoveredProjectOperation(
+  invocation: CliInvocation,
+  requestedOperation: string,
+  args: string[],
+  options: { all: boolean },
+): Promise<void> {
+  const projects = discoverProjectConfigs({
+    chdir: invocation.global.chdir,
+    config: invocation.global.config,
+  });
+  if (projects.length === 0) {
+    throw new Error("No Rigkit projects found.");
+  }
+  if (!options.all && projects.length > 1) {
+    throw new Error([
+      "Multiple Rigkit projects found.",
+      "Use `rig projects` to list candidates, pass -chdir or -config to select one, or pass --all to run every discovered project.",
+      ...projects.map((project) => `- ${project.configPath}`),
+    ].join("\n"));
+  }
+  if (invocation.global.state && projects.length > 1) {
+    throw new Error(`--state cannot be used with multiple discovered projects`);
+  }
+
+  const results: Array<{
+    project: { projectDir: string; configPath: string };
+    operation: string;
+    result: unknown;
+  }> = [];
+
+  for (const project of projects) {
+    const runtime = await getOrStartRuntime({
+      projectDir: project.projectDir,
+      configPath: project.configPath,
+      statePath: invocation.global.state ? resolveGlobalPath(invocation, invocation.global.state) : undefined,
+    });
+    const { operation, parsed, result } = await executeRuntimeOperation(
+      invocation,
+      runtime,
+      requestedOperation,
+      args,
+    );
+    results.push({
+      project,
+      operation: operation.id,
+      result,
+    });
+
+    if (!wantsJson(invocation)) {
+      if (projects.length > 1) {
+        console.log(ui.bold(displayProjectDir(project.projectDir)));
+      }
+      await renderOperationResult(operation, result, parsed.hostOptions);
+      printInteractiveOutputGap(invocation);
+    }
+  }
+
+  if (wantsJson(invocation)) {
+    printJson({ projects: results });
+  }
+}
+
+async function runProjects(invocation: CliInvocation): Promise<void> {
+  const projects = discoverProjectConfigs({
+    chdir: invocation.global.chdir,
+    config: invocation.global.config,
+  });
+  if (wantsJson(invocation)) {
+    printJson({ projects });
+    return;
+  }
+  if (projects.length === 0) {
+    console.log(ui.dim("no Rigkit projects found"));
+    return;
+  }
+  const rows = projects.map((project) => [
+    { text: project.projectDir, style: ui.bold },
+    { text: project.configPath, style: ui.dim },
+  ]);
+  console.log(ui.columns(["project", "config"], rows));
+}
+
+async function runList(invocation: CliInvocation, options: ListOptions): Promise<void> {
+  const target = normalizeListTarget(options.target);
+  const runtime = await loadRuntime(invocation);
+
+  if (target === "workspaces") {
+    const { workspaces } = await runtime.control.workspaces();
+    if (wantsJson(invocation)) {
+      printJson({ workspaces });
+      return;
+    }
+    printWorkspaces(workspaces);
+    return;
+  }
+
+  if (target === "snapshots") {
+    const { snapshots } = await runtime.control.snapshots();
+    if (wantsJson(invocation)) {
+      printJson({ snapshots });
+      return;
+    }
+    printSnapshots(snapshots as SnapshotRecord[]);
+    return;
+  }
+
+  const project = await readRuntimeProject(runtime);
+  if (wantsJson(invocation)) {
+    printJson(project);
+    return;
+  }
+  printConfig(project);
+}
+
+async function runCacheList(invocation: CliInvocation): Promise<void> {
+  const runtime = await loadRuntime(invocation);
+  const cache = await runtime.control.cache();
+  if (wantsJson(invocation)) {
+    printJson(cache);
+    return;
+  }
+  printCacheEntries(cache.entries);
+}
+
+async function runCacheClear(invocation: CliInvocation, options: CacheClearOptions): Promise<void> {
+  if (options.all && !options.global) {
+    throw new Error(`rig cache clear --all must be combined with --global`);
+  }
+  if (options.local && options.global && !options.all) {
+    throw new Error(`Choose --local or --global, not both`);
+  }
+
+  if (options.global && options.all) {
+    if (invocation.global.chdir || invocation.global.config || invocation.global.state) {
+      throw new Error(`rig cache clear --global --all cannot be combined with -chdir, -config, or -state`);
+    }
+    const fragmentRoot = join(defaultRigkitHome(), "fragments");
+    rmSync(fragmentRoot, { recursive: true, force: true });
+    if (wantsJson(invocation)) {
+      printJson({ ok: true, deleted: null, scope: "global-all", fragmentRoot });
+      return;
+    }
+    console.log(`Cleared global fragment cache at ${fragmentRoot}`);
+    return;
+  }
+
+  const scope = options.local ? "local" : options.global ? "global" : "all";
+  const runtime = await loadRuntime(invocation);
+  const result = await runtime.control.clearCache({ scope });
+  if (wantsJson(invocation)) {
+    printJson(result);
+    return;
+  }
+  console.log(`Cleared ${result.deleted} cache ${result.deleted === 1 ? "entry" : "entries"}.`);
+}
+
+type CacheInvalidateOptions = {
+  step?: string;
+  all: boolean;
+  yes: boolean;
+};
+
+async function runCacheInvalidate(invocation: CliInvocation, options: CacheInvalidateOptions): Promise<void> {
+  if (options.step && options.all) {
+    throw new Error(`rig cache invalidate accepts either a step or --all, not both`);
+  }
+
+  const runtime = await loadRuntime(invocation);
+  let targets: string[] = [];
+
+  if (options.step) {
+    targets = [options.step];
+  } else if (options.all) {
+    if (!options.yes && !wantsJson(invocation) && canPrompt()) {
+      const confirmed = await promptHostConfirm({
+        message: "Invalidate every cached task in this project?",
+        defaultValue: false,
+      });
+      if (!confirmed) throw new Error("Invalidate cancelled");
+    } else if (!options.yes && !canPrompt()) {
+      throw new Error(`rig cache invalidate --all needs --yes when not running in an interactive terminal`);
+    }
+    targets = []; // empty = engine invalidates everything for the workflow
+  } else {
+    // Interactive: multi-select among currently-valid cache entries.
+    const cache = await runtime.control.cache();
+    const candidates = cache.entries
+      .filter((entry) => !entry.invalidated && entry.scope === "local")
+      .map((entry) => ({ path: entry.nodePath || entry.nodeName, workflow: entry.workflow }));
+    if (candidates.length === 0) {
+      if (wantsJson(invocation)) {
+        printJson({ ok: true, invalidated: 0 });
+        return;
+      }
+      console.log(ui.dim("no valid cache entries to invalidate"));
+      return;
+    }
+    if (wantsJson(invocation) || !canPrompt()) {
+      throw new Error(`rig cache invalidate needs a step name or --all when not running in an interactive terminal`);
+    }
+    const picked = await promptCacheInvalidateSelection(candidates);
+    if (picked.length === 0) throw new Error("Nothing selected");
+    targets = picked;
+  }
+
+  const result = await runtime.control.invalidateCache({ nodePaths: targets });
+  if (wantsJson(invocation)) {
+    printJson(result);
+    return;
+  }
+  console.log(
+    `${ui.ok(ui.sym.ok)} invalidated ${result.invalidated} cache ${result.invalidated === 1 ? "entry" : "entries"}`,
+  );
+}
+
+async function promptCacheInvalidateSelection(
+  candidates: Array<{ path: string; workflow: string }>,
+): Promise<string[]> {
+  const answers = await inquirer.prompt<{ paths: string[] }>([{
+    type: "checkbox",
+    name: "paths",
+    message: "Select tasks to invalidate",
+    choices: candidates.map((c) => ({
+      name: c.path,
+      value: c.path,
+      description: c.workflow ? `workflow ${c.workflow}` : undefined,
+    })),
+  }]);
+  return answers.paths;
+}
+
+async function executeRuntimeOperation(
+  invocation: CliInvocation,
+  runtime: RuntimeClient,
+  requestedOperation: string,
+  args: string[],
+): Promise<{
+  operation: RuntimeOperationDefinition;
+  parsed: ParsedOperationInput;
+  result: unknown;
+}> {
+  const manifest = await readRuntimeOperations(runtime);
+  const resolved = findRuntimeOperation(manifest, requestedOperation);
+  if (!resolved) {
+    throw new Error(`This project does not define a Rigkit operation named "${requestedOperation}".`);
+  }
+  const { operation, runOperation } = resolved;
+
+  const parsed = await parseOperationArgsWithPrompts(invocation, runtime, operation, args);
+  enforceHostOnlyBooleanGuards(operation, parsed);
+
+  const result = await runRuntimeOperation<unknown>(
+    runtime,
+    runOperation,
+    parsed.input,
+    { renderEvents: !wantsJson(invocation) },
+  );
+
+  return { operation, parsed, result };
+}
+
+function findRuntimeOperation(
+  manifest: RuntimeOperationManifest,
+  requestedOperation: string,
+): { operation: RuntimeOperationDefinition; runOperation: string } | undefined {
+  const operation = manifest.operations.find((operation) =>
+    operation.id === requestedOperation || operation.aliases?.includes(requestedOperation)
+  );
+  return operation ? { operation, runOperation: operation.id } : undefined;
+}
+
+async function parseOperationArgsWithPrompts(
+  invocation: CliInvocation,
+  runtime: RuntimeClient,
+  operation: RuntimeOperationDefinition,
+  args: string[],
+): Promise<ParsedOperationInput> {
+  const parsed = parseOperationArgs(operation, args, {
+    allowMissingRequired: !wantsJson(invocation) && canPrompt(),
+  });
+
+  if (
+    operation.createsWorkspace &&
+    parsed.input.name === undefined &&
+    !wantsJson(invocation) &&
+    canPrompt()
+  ) {
+    parsed.input.name = await promptWorkspaceName(await defaultWorkspaceName(runtime));
+  }
+  if (operation.createsWorkspace && parsed.input.name !== undefined) {
+    assertValidWorkspaceName(parsed.input.name);
+  }
+
+  enforceRequiredOperationInputs(operation, parsed);
+  return parsed;
+}
+
+function parseOperationArgs(
+  operation: RuntimeOperationDefinition,
+  args: string[],
+  options: { allowMissingRequired?: boolean } = {},
+): ParsedOperationInput {
+  const cli = inferCliMetadata(operation);
+  const input: Record<string, unknown> = {};
+  const hostOptions: Record<string, unknown> = {};
+  const positionals = cli.positionals ?? [];
+  let positionalIndex = 0;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+
+    if (arg === "--") {
+      for (const value of args.slice(index + 1)) {
+        assignPositional(positionals, positionalIndex++, value, input);
+      }
+      break;
+    }
+
+    if (arg.startsWith("--")) {
+      const [flag, inlineValue] = splitFlag(arg);
+      const option = cli.options?.find((item) => item.flag === flag || item.aliases?.includes(flag));
+      if (!option) throw new Error(`Unknown option ${flag} for operation ${operation.id}`);
+      const rawValue = option.type === "boolean"
+        ? inlineValue ?? true
+        : inlineValue ?? readOptionValue(args, ++index, flag);
+      assignCliValue(option, rawValue, input, hostOptions);
+      continue;
+    }
+
+    if (arg.startsWith("-") && arg !== "-") {
+      const option = cli.options?.find((item) => item.flag === arg || item.aliases?.includes(arg));
+      if (!option) throw new Error(`Unknown option ${arg} for operation ${operation.id}`);
+      const rawValue = option.type === "boolean" ? true : readOptionValue(args, ++index, arg);
+      assignCliValue(option, rawValue, input, hostOptions);
+      continue;
+    }
+
+    assignPositional(positionals, positionalIndex++, arg, input);
+  }
+
+  if (!options.allowMissingRequired) enforceRequiredOperationInputs(operation, { input, hostOptions });
+
+  return { input, hostOptions };
+}
+
+function enforceRequiredOperationInputs(
+  operation: RuntimeOperationDefinition,
+  parsed: ParsedOperationInput,
+): void {
+  const cli = inferCliMetadata(operation);
+  for (const option of cli.options ?? []) {
+    if (option.required && parsed.input[option.name] === undefined && parsed.hostOptions[option.name] === undefined) {
+      throw new Error(`Operation ${operation.id} requires ${option.flag}`);
+    }
+  }
+
+  for (const name of operation.inputSchema?.required ?? []) {
+    if (parsed.input[name] === undefined) {
+      throw new Error(`Operation ${operation.id} requires ${name}`);
+    }
+  }
+}
+
+function enforceHostOnlyBooleanGuards(
+  operation: RuntimeOperationDefinition,
+  parsed: ParsedOperationInput,
+): void {
+  const guard = operation.cli?.options?.find((option) =>
+    option.runtime === false &&
+    option.type === "boolean" &&
+    (option.name === "yes" || option.name === "confirm") &&
+    parsed.hostOptions[option.name] !== true
+  );
+  if (!guard) return;
+  throw new Error(`Operation ${operation.id} requires ${guard.flag}`);
+}
+
+function inferCliMetadata(operation: RuntimeOperationDefinition): Required<NonNullable<RuntimeOperationDefinition["cli"]>> {
+  const properties = operation.inputSchema?.properties ?? {};
+  return {
+    positionals: operation.cli?.positionals ?? [],
+    options: operation.cli?.options ?? Object.entries(properties).map(([name, schema]) => ({
+      name,
+      flag: `--${dashCase(name)}`,
+      required: operation.inputSchema?.required?.includes(name),
+      type: schema.type === "boolean" ? "boolean" : schema.type === "number" ? "number" : "string",
+    })),
+  };
+}
+
+function dashCase(value: string): string {
+  return value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+function splitFlag(arg: string): [string, string | undefined] {
+  const index = arg.indexOf("=");
+  return index < 0 ? [arg, undefined] : [arg.slice(0, index), arg.slice(index + 1)];
+}
+
+function readOptionValue(args: string[], index: number, flag: string): string {
+  const value = args[index];
+  if (value === undefined || value.startsWith("-")) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function assignCliValue(
+  option: RuntimeOperationCliOption,
+  rawValue: unknown,
+  input: Record<string, unknown>,
+  hostOptions: Record<string, unknown>,
+): void {
+  const value = coerceCliValue(rawValue, option.type ?? "string", option.flag);
+  const target = option.runtime === false ? hostOptions : input;
+  target[option.name] = value;
+}
+
+function assignPositional(
+  positionals: Array<{ name: string; index: number }>,
+  index: number,
+  value: string,
+  input: Record<string, unknown>,
+): void {
+  const positional = positionals.find((item) => item.index === index);
+  if (!positional) throw new Error(`Unexpected positional argument ${value}`);
+  input[positional.name] = value;
+}
+
+function coerceCliValue(value: unknown, type: "string" | "boolean" | "number", flag: string): unknown {
+  if (type === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new Error(`${flag} expects true or false`);
+  }
+  if (type === "number") {
+    const number = Number(value);
+    if (!Number.isFinite(number)) throw new Error(`${flag} expects a number`);
+    return number;
+  }
+  return String(value);
+}
+
+async function renderOperationResult(
+  operation: RuntimeOperationDefinition,
+  result: unknown,
+  hostOptions: Record<string, unknown>,
+): Promise<void> {
+  if (isWorkflowPlan(result)) {
+    printPlan(result);
+    return;
+  }
+
+  if (isRecord(result) && isWorkflowPlan(result.plan)) {
+    if (result.dryRun === true) {
+      printPlan(result.plan);
+      console.log("No changes applied.");
+      return;
+    }
+    console.log(`resolved ${result.plan.workflow}`);
+    return;
+  }
+
+  if (operation.createsWorkspace && isWorkspaceRecord(result)) {
+    // Only emit the bareword name when stdout is piped, so scripts can do
+    // `name=$(rig create)` while TTY users aren't shown a redundant line.
+    if (!process.stdout.isTTY) console.log(result.name);
+    return;
+  }
+
+  if (isRecord(result) && typeof result.command === "string") {
+    const commandResult = isRecord(result.commandResult) ? result.commandResult : undefined;
+    if (!commandResult || hostOptions.print === true) {
+      console.log(result.command);
+      return;
+    }
+    const exitCode = typeof commandResult.exitCode === "number" ? commandResult.exitCode : 0;
+    if (exitCode !== 0) throw new Error(`Host command failed with exit code ${exitCode}`);
+    return;
+  }
+
+  if (isWorkspaceRecord(result)) {
+    if (!process.stdout.isTTY) console.log(result.name);
+    return;
+  }
+
+  printJson(result);
+}
+
+async function runDoctor(invocation: CliInvocation, options: DoctorOptions): Promise<void> {
+  if (options.cli) {
+    const diagnostics = {
+      cliVersion: RIGKIT_CLI_VERSION,
+      binary: process.argv[1] ? resolve(process.argv[1]) : undefined,
+      node: process.version,
+      bun: typeof Bun !== "undefined" ? Bun.version : undefined,
+    };
+    if (wantsJson(invocation)) {
+      printJson(diagnostics);
+      return;
+    }
+    console.log(ui.kvList([
+      ["cli", diagnostics.cliVersion],
+      ["binary", diagnostics.binary ?? ""],
+      ["node", diagnostics.node],
+      ["bun", diagnostics.bun ?? ""],
+    ]));
+    return;
+  }
+
+  const runtime = await loadRuntime(invocation);
+  const [health, runtimeInfo, project] = await Promise.all([
+    runtime.control.health(),
+    runtime.control.runtime(),
+    readRuntimeProject(runtime),
+  ]);
+  const diagnostics = {
+    cliVersion: RIGKIT_CLI_VERSION,
+    project,
+    daemon: {
+      url: runtime.handle.url,
+      pid: runtime.handle.pid,
+      handlePath: runtime.paths.handlePath,
+      tokenPath: runtime.handle.tokenPath,
+      expiresAt: health.expiresAt ?? runtime.handle.expiresAt,
+    },
+    runtime: runtimeInfo,
+  };
+
+  if (wantsJson(invocation)) {
+    printJson(diagnostics);
+    return;
+  }
+
+  console.log(ui.kvList([
+    ["cli", RIGKIT_CLI_VERSION],
+    ["project", project.projectDir],
+    ["config", project.configPath],
+    ["runtime handle", runtime.paths.handlePath],
+    ["daemon", runtime.handle.url],
+    ["daemon pid", String(runtime.handle.pid)],
+    ["engine", runtimeInfo.engineVersion],
+    ["runtime", runtimeInfo.runtimeVersion],
+    ["api version", String(runtimeInfo.apiVersion)],
+    ["protocol", runtimeInfo.protocolHash],
+    ["state", project.statePath ?? ""],
+    ["expires", health.expiresAt ?? runtime.handle.expiresAt ?? ""],
+  ]));
+}
+
+async function runVersion(invocation: CliInvocation): Promise<void> {
+  if (wantsJson(invocation)) {
+    printJson({ cliVersion: RIGKIT_CLI_VERSION });
+    return;
+  }
+  console.log(RIGKIT_CLI_VERSION);
+}
+
+async function runHelp(invocation: CliInvocation): Promise<void> {
+  if (wantsJson(invocation)) {
+    printJson({
+      name: "rig",
+      version: RIGKIT_CLI_VERSION,
+      commands: [
+        { name: "help", description: "Show Rigkit CLI help" },
+        { name: "init", description: "Initialize a Rigkit project" },
+        { name: "plan", description: "Plan project workflow changes" },
+        { name: "apply", description: "Apply project workflow changes" },
+        { name: "create", description: "Create a workspace" },
+        { name: "rm", description: "Remove a workspace" },
+        { name: "run", description: "Run a workspace operation" },
+        { name: "ls", description: "List project workspaces" },
+        { name: "cache", description: "Inspect and clear Rigkit cache" },
+        { name: "projects", description: "Discover Rigkit projects below the current directory" },
+        { name: "doctor", description: "Show Rigkit runtime diagnostics" },
+        { name: "version", description: "Show Rigkit CLI version" },
+        { name: "completion", description: "Generate shell completion script" },
+      ],
+    });
+    return;
+  }
+  const cmd = (name: string, description: string): string =>
+    `  ${ui.bold(name.padEnd(10))}  ${description}`;
+  const opt = (flag: string, description: string): string =>
+    `  ${ui.bold(flag.padEnd(12))}  ${description}`;
+
+  console.log([
+    `${ui.bold("rig")} ${ui.dim(RIGKIT_CLI_VERSION)}`,
+    "",
+    ui.dim("Usage:"),
+    `  ${ui.accent(ui.sym.prompt)} rig [global options] <command> [args]`,
+    "",
+    ui.dim("Commands:"),
+    cmd("help",       "Show Rigkit CLI help"),
+    cmd("init",       "Initialize a Rigkit project"),
+    cmd("plan",       "Plan project workflow changes"),
+    cmd("apply",      "Apply project workflow changes"),
+    cmd("create",     "Create a workspace"),
+    cmd("rm",         "Remove a workspace"),
+    cmd("run",        "Run a workspace operation"),
+    cmd("ls",         "List project workspaces"),
+    cmd("cache",      "Inspect and clear Rigkit cache"),
+    cmd("projects",   "Discover Rigkit projects below the current directory"),
+    cmd("doctor",     "Show Rigkit runtime diagnostics"),
+    cmd("version",    "Show Rigkit CLI version"),
+    cmd("completion", "Generate shell completion script"),
+    "",
+    ui.dim("Options:"),
+    opt("-chdir=DIR",   "Switch to a directory containing rig.config.ts before running the command"),
+    opt("-config=FILE", "Config file to load, relative to -chdir when set"),
+    opt("-state=FILE",  "Local runtime state database path"),
+    opt("-json",        "Print machine-readable JSON where supported"),
+  ].join("\n"));
+}
+
+async function loadRuntime(invocation: CliInvocation): Promise<RuntimeClient> {
+  const engineOptions = resolveEngineOptions(invocation);
+  return await getOrStartRuntime(engineOptions);
+}
+
+async function readRuntimeProject(runtime: RuntimeClient): Promise<EngineProjectInfo> {
+  return await runtime.control.project() as EngineProjectInfo;
+}
+
+async function readRuntimeOperations(runtime: RuntimeClient): Promise<RuntimeOperationManifest> {
+  return await runtime.control.operations() as unknown as RuntimeOperationManifest;
+}
+
+async function runRuntimeOperation<T>(
+  runtime: RuntimeClient,
+  operation: string,
+  input: Record<string, unknown>,
+  options: { renderEvents: boolean },
+): Promise<T> {
+  const started = await runtime.control.startRun({ operation, input });
+  let presenter: RunPresenter | undefined = options.renderEvents
+    ? createRunPresenter(operation)
+    : undefined;
+  const logger: RunLogger | undefined = createRunLogger({
+    projectDir: runtime.handle.projectDir,
+    operation,
+    daemonStderrPath: runtime.paths.runtimeLogPath,
+  });
+  if (logger) {
+    logger.append({ type: "run.started", runId: started.runId, operation, input });
+  }
+  let result: T | undefined;
+  let failure: Error | undefined;
+  let failureCode: string | undefined;
+  let activeNodePath: string | undefined;
+
+  const handleEvent = async (
+    event: unknown,
+    respond?: (id: string, response: unknown) => void | Promise<void>,
+    sendSession?: (message: unknown) => void | Promise<void>,
+  ) => {
+    logger?.append(event);
+    if (isRecord(event)) {
+      if (event.type === "node.started" && typeof event.nodePath === "string") {
+        activeNodePath = event.nodePath;
+      }
+      if (event.type === "node.completed" && event.nodePath === activeNodePath) {
+        activeNodePath = undefined;
+      }
+    }
+    if (isHostRequestEvent(event)) {
+      const suspendPresenter = hostRequestNeedsTerminal(event);
+      if (suspendPresenter) presenter?.pause();
+      try {
+        if (respond) {
+          await answerHostRequestOverSession(respond, event, { quietOpen: Boolean(presenter) });
+        } else {
+          await answerHostRequest(runtime, event, { quietOpen: Boolean(presenter) });
+        }
+      } finally {
+        if (suspendPresenter) presenter?.resume();
+      }
+      return;
+    }
+    if (isHostCapabilityRequestEvent(event)) {
+      const suspendPresenter = hostCapabilityNeedsTerminal(event);
+      const logger = createHostCapabilityLogger(event, presenter);
+      if (suspendPresenter) presenter?.pause();
+      try {
+        if (sendSession) {
+          await answerHostCapabilityRequestOverSession(sendSession, event, { logger });
+        } else if (respond) {
+          await answerHostCapabilityRequestOverSession((message) => {
+            if (isRecord(message) && message.type === "response") {
+              const id = typeof message.id === "string" ? message.id : undefined;
+              if (id) return respond(id, "error" in message ? { error: message.error } : { result: message.result });
+            }
+            throw new Error(`Session response channel cannot send ${String(isRecord(message) ? message.type : typeof message)}`);
+          }, event, { logger });
+        } else {
+          await answerHostCapabilityRequest(runtime, event, { logger });
+        }
+      } finally {
+        if (suspendPresenter) presenter?.resume();
+      }
+      return;
+    }
+    if (isRecord(event) && event.type === "run.completed") {
+      presenter?.render({ ...event, type: "run.completed" });
+      result = event.result as T;
+      return;
+    }
+    if (isRecord(event) && event.type === "run.failed") {
+      const message = isRecord(event.error) && typeof event.error.message === "string"
+        ? event.error.message
+        : "Runtime operation failed";
+      failure = new Error(message);
+      failureCode = isRecord(event.error) && typeof event.error.code === "string"
+        ? event.error.code
+        : undefined;
+      presenter?.render({ ...event, type: "run.failed" });
+      return;
+    }
+    if (options.renderEvents && isDevMachineEvent(event)) {
+      if (presenter) presenter.render(event);
+      else renderEvent(event);
+    }
+  };
+
+  try {
+    if (started.sessionUrl) {
+      await runtime.runSession(started.runId, {
+        hello: {
+          type: "hello",
+          transportVersion: 1,
+          host: {
+            name: "rigkit-cli",
+            version: RIGKIT_CLI_VERSION,
+          },
+          hostMethods: CLI_HOST_METHODS,
+          hostCapabilities: CLI_HOST_CAPABILITIES,
+        },
+        onOpen(session) {
+          return installRunCancelHandler(session);
+        },
+        onClose() {
+          uninstallRunCancelHandler();
+        },
+        async onMessage(message, session) {
+          if (isRecord(message) && message.type === "hello.ack") return;
+          if (isRecord(message) && message.type === "run.event") {
+            await handleEvent(message.event);
+            return;
+          }
+          await handleEvent(
+            message,
+            (id, response) => session.send({ type: "response", id, ...(response as object) }),
+            (sessionMessage) => session.send(sessionMessage),
+          );
+          if (result !== undefined || failure) session.close();
+        },
+      });
+      uninstallRunCancelHandler();
+    } else {
+      await runtime.runEvents(started.runId, handleEvent);
+    }
+  } finally {
+    presenter?.close();
+    if (logger) {
+      logger.finish({
+        status: failure ? "failed" : "completed",
+        error: failure,
+        result,
+      });
+      logger.close();
+    }
+    uninstallRunCancelHandler();
+  }
+
+  if (failure) {
+    printRunFailure({
+      operation,
+      node: activeNodePath,
+      code: failureCode,
+      message: failure.message,
+      logPath: logger?.path,
+    });
+    throw new DisplayedCliError(failure.message);
+  }
+  if (result === undefined) throw new Error(`Runtime operation ${operation} finished without a result`);
+  return result;
+}
+
+function printRunFailure(input: {
+  operation: string;
+  node: string | undefined;
+  code: string | undefined;
+  message: string;
+  logPath: string | undefined;
+}): void {
+  const pairs: Array<[string, string]> = [];
+  if (input.node) pairs.push(["node", input.node]);
+  if (input.code) pairs.push(["code", ui.bold(input.code)]);
+  pairs.push(["reason", input.message]);
+
+  process.stderr.write("\n");
+  process.stderr.write(`${ui.err(ui.sym.err)} ${ui.bold(`${input.operation} failed`)}\n`);
+  process.stderr.write(`${ui.kvList(pairs)}\n`);
+  if (input.logPath) {
+    process.stderr.write("\n");
+    process.stderr.write(`${ui.dim("full log")}  ${shortPath(input.logPath)}\n`);
+    process.stderr.write(`${ui.dim("        ")}  ${ui.dim("daemon stderr appended on failure")}\n`);
+  }
+}
+
+// After a successful `rig create`, list the workspace's available operations so
+// the user doesn't have to guess what to do next. TTY-only — JSON consumers and
+// pipes get clean output.
+async function printWorkspaceNextSteps(runtime: RuntimeClient, workspaceName: string): Promise<void> {
+  if (!process.stderr.isTTY) return;
+
+  let manifest: RuntimeOperationManifest;
+  try {
+    manifest = await readRuntimeOperations(runtime);
+  } catch {
+    return;
+  }
+
+  const ops = (manifest.workspaceOperations ?? []).filter((op) => op.id !== "remove");
+  const invocations: Array<{ command: string; description: string }> = ops.map((op) => ({
+    command: `rig run ${workspaceName} ${op.id}`,
+    description: op.description ?? op.title ?? "",
+  }));
+  invocations.push({ command: `rig rm ${workspaceName}`, description: "Remove this workspace" });
+
+  const commandWidth = invocations.reduce((max, item) => Math.max(max, item.command.length), 0);
+
+  process.stderr.write("\n");
+  process.stderr.write(`${ui.bold("Next")}\n`);
+  for (const item of invocations) {
+    const command = `${ui.bold("rig")}${item.command.slice("rig".length)}`;
+    const padding = " ".repeat(Math.max(0, commandWidth - item.command.length));
+    const tail = item.description ? `  ${ui.dim(item.description)}` : "";
+    process.stderr.write(`${ui.dim(ui.sym.arrow)} ${command}${padding}${tail}\n`);
+  }
+}
+
+let uninstallActiveRunCancelHandler: (() => void) | undefined;
+
+function installRunCancelHandler(session: { send(message: unknown): void; close(code?: number, reason?: string): void }): void {
+  uninstallRunCancelHandler();
+  let cancelRequested = false;
+  const onSigint = () => {
+    if (cancelRequested) {
+      session.close(1000, "Run cancelled by host");
+      return;
+    }
+    cancelRequested = true;
+    session.send({ type: "run.cancel", reason: "user" });
+    process.once("SIGINT", onSigint);
+  };
+  process.once("SIGINT", onSigint);
+  uninstallActiveRunCancelHandler = () => {
+    process.off("SIGINT", onSigint);
+    uninstallActiveRunCancelHandler = undefined;
+  };
+}
+
+function uninstallRunCancelHandler(): void {
+  uninstallActiveRunCancelHandler?.();
+}
+
+function resolveEngineOptions(invocation: CliInvocation): { projectDir: string; configPath: string; statePath?: string } {
+  const paths = resolveCommandConfigPaths(invocation);
+  const options = invocation.global;
+  return {
+    projectDir: paths.projectDir,
+    configPath: paths.configPath,
+    statePath: options.state ? resolveGlobalPath(invocation, options.state) : undefined,
+  };
+}
+
+function resolveCommandConfigPaths(invocation: CliInvocation): { projectDir: string; configPath: string } {
+  const options = invocation.global;
+  return resolveConfigPaths({ chdir: options.chdir, config: options.config });
+}
+
+function resolveGlobalPath(invocation: CliInvocation, path: string): string {
+  return resolve(process.cwd(), invocation.global.chdir ?? ".", path);
+}
+
+type HostRequestEvent = {
+  type: "host.request";
+  requestId?: string;
+  id?: string;
+  method: string;
+  params: unknown;
+};
+
+type HostCapabilityRequestEvent = {
+  type: "host.capability.request";
+  requestId?: string;
+  id?: string;
+  nodePath?: string;
+  capability: string;
+  params: unknown;
+};
+
+type HostRequestHandlingOptions = {
+  quietOpen?: boolean;
+};
+
+type HostCapabilityLogOptions = {
+  stream?: "stdout" | "stderr" | "info";
+  label?: string;
+};
+
+type HostCapabilityRequestHandlingOptions = {
+  logger?: (data: string, options?: HostCapabilityLogOptions) => void;
+};
+
+class UnsupportedHostCapabilityError extends Error {
+  constructor(capability: string) {
+    super(
+      `Host capability "${capability}" is not registered in this Rigkit CLI host. ` +
+        `Install or enable a local host capability handler to use it from this host.`,
+    );
+    this.name = "UnsupportedHostCapabilityError";
+  }
+}
+
+async function answerHostRequest(
+  runtime: RuntimeClient,
+  event: HostRequestEvent,
+  options: HostRequestHandlingOptions = {},
+): Promise<void> {
+  if (!event.requestId) throw new Error(`Host request is missing requestId`);
+  try {
+    const result = await handleHostRequest(event.method, event.params, options);
+    await runtime.control.hostResponse(event.requestId, { result });
+  } catch (error) {
+    await runtime.control.hostResponse(event.requestId, {
+      error: {
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+async function answerHostRequestOverSession(
+  respond: (id: string, response: unknown) => void | Promise<void>,
+  event: HostRequestEvent,
+  options: HostRequestHandlingOptions = {},
+): Promise<void> {
+  const id = event.id ?? event.requestId;
+  if (!id) throw new Error(`Host request is missing id`);
+  try {
+    const result = await handleHostRequest(event.method, event.params, options);
+    await respond(id, { result });
+  } catch (error) {
+    await respond(id, {
+      error: {
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+async function answerHostCapabilityRequest(
+  runtime: RuntimeClient,
+  event: HostCapabilityRequestEvent,
+  options: HostCapabilityRequestHandlingOptions = {},
+): Promise<void> {
+  const requestId = event.requestId ?? event.id;
+  if (!requestId) throw new Error(`Host capability request is missing requestId`);
+  try {
+    const handled = await handleHostCapabilityRequest(event.capability, event.params, options);
+    await runtime.control.hostResponse(requestId, { result: handled.result });
+  } catch (error) {
+    await runtime.control.hostResponse(requestId, {
+      error: hostCapabilityError(error),
+    });
+  }
+}
+
+async function answerHostCapabilityRequestOverSession(
+  send: (message: unknown) => void | Promise<void>,
+  event: HostCapabilityRequestEvent,
+  options: HostCapabilityRequestHandlingOptions = {},
+): Promise<void> {
+  const id = event.id ?? event.requestId;
+  if (!id) throw new Error(`Host capability request is missing id`);
+  try {
+    const handled = await handleHostCapabilityRequest(event.capability, event.params, options);
+    await send({ type: "response", id, result: handled.result });
+    if (handled.closed) reportHostCapabilityClosed(send, id, handled.closed);
+  } catch (error) {
+    await send({
+      type: "response",
+      id,
+      error: hostCapabilityError(error),
+    });
+  }
+}
+
+async function handleHostRequest(
+  method: string,
+  params: unknown,
+  options: HostRequestHandlingOptions = {},
+): Promise<unknown> {
+  switch (method) {
+    case "message.show":
+      return showHostMessage(params);
+    case "prompt.text":
+      return await promptHostText(params);
+    case "prompt.confirm":
+      return await promptHostConfirm(params);
+    case "prompt.select":
+      return await promptHostSelect(params);
+    case "open.external":
+      return openHostExternal(params, options);
+    case "host.command.run":
+      return await runHostCommand(params);
+    default:
+      throw new Error(`Unsupported host method ${method}`);
+  }
+}
+
+function hostRequestNeedsTerminal(event: HostRequestEvent): boolean {
+  switch (event.method) {
+    case "open.external":
+      return false;
+    case "host.command.run":
+      return !isTrustedCaptureHostCommand(event.params);
+    default:
+      return true;
+  }
+}
+
+function hostCapabilityNeedsTerminal(event: HostCapabilityRequestEvent): boolean {
+  switch (event.capability) {
+    case "cmux.open":
+      return false;
+    default:
+      return true;
+  }
+}
+
+function createHostCapabilityLogger(
+  event: HostCapabilityRequestEvent,
+  presenter: RunPresenter | undefined,
+): (data: string, options?: HostCapabilityLogOptions) => void {
+  return (data, options = {}) => {
+    if (presenter) {
+      presenter.render({
+        type: "log.output",
+        nodePath: event.nodePath ?? "runtime",
+        stream: options.stream ?? "info",
+        label: options.label ?? event.capability,
+        data,
+      });
+      return;
+    }
+    console.error(data);
+  };
+}
+
+function isTrustedCaptureHostCommand(params: unknown): boolean {
+  return process.env.RIGKIT_TRUST_HOST_COMMANDS === "1" &&
+    isRecord(params) &&
+    params.mode !== "interactive";
+}
+
+type HandledHostCapability = {
+  result: unknown;
+  closed?: Promise<void>;
+};
+
+async function handleHostCapabilityRequest(
+  capability: string,
+  params: unknown,
+  options: HostCapabilityRequestHandlingOptions = {},
+): Promise<HandledHostCapability> {
+  const handler = CLI_HOST_CAPABILITY_HANDLERS.get(capability);
+  if (!handler) {
+    throw new UnsupportedHostCapabilityError(capability);
+  }
+  return normalizeHostCapabilityResult(await handler.handle(params, {
+    log: (data, logOptions) => options.logger?.(data, logOptions),
+  }));
+}
+
+function normalizeHostCapabilityResult(value: unknown): HandledHostCapability {
+  if (isRecord(value) && isPromiseLike(value.closed)) {
+    const { closed, ...result } = value as Record<string, unknown> & { closed: PromiseLike<unknown> };
+    return {
+      result,
+      closed: Promise.resolve(closed).then(() => undefined),
+    };
+  }
+  return { result: value };
+}
+
+function reportHostCapabilityClosed(
+  send: (message: unknown) => void | Promise<void>,
+  id: string,
+  closed: Promise<void>,
+): void {
+  void closed.then(
+    () => send({ type: "host.capability.closed", id }),
+    (error) => send({ type: "host.capability.closed", id, error: hostCapabilityError(error) }),
+  ).catch(() => {});
+}
+
+function hostCapabilityError(error: unknown): { code: string; message: string } {
+  return {
+    code: error instanceof UnsupportedHostCapabilityError ? "UNSUPPORTED_CAPABILITY" : "HOST_CAPABILITY_FAILED",
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+function showHostMessage(params: unknown): null {
+  const message = stringField(params, "message") ?? "";
+  const level = stringField(params, "level") ?? "info";
+  console.error(`${level}: ${message}`);
+  return null;
+}
+
+async function promptHostText(params: unknown): Promise<string> {
+  const message = stringField(params, "message") ?? "Enter value";
+  const defaultValue = stringField(params, "defaultValue");
+  if (!canPrompt()) {
+    if (defaultValue !== undefined) return defaultValue;
+    throw new Error(`Host prompt requires an interactive terminal: ${message}`);
+  }
+  const answers = await inquirer.prompt<{ value: string }>([{
+    type: "input",
+    name: "value",
+    message,
+    default: defaultValue,
+  }]);
+  return answers.value || defaultValue || "";
+}
+
+async function promptHostConfirm(params: unknown): Promise<boolean> {
+  const message = stringField(params, "message") ?? "Continue?";
+  const defaultValue = booleanField(params, "defaultValue") ?? false;
+  if (!canPrompt()) return defaultValue;
+  const answers = await inquirer.prompt<{ value: boolean }>([{
+    type: "confirm",
+    name: "value",
+    message,
+    default: defaultValue,
+  }]);
+  return answers.value;
+}
+
+async function promptHostSelect(params: unknown): Promise<string> {
+  const message = stringField(params, "message") ?? "Choose";
+  const options = isRecord(params) && Array.isArray(params.options)
+    ? params.options
+      .filter(isRecord)
+      .map((item) => ({
+        value: typeof item.value === "string" ? item.value : "",
+        label: typeof item.label === "string" ? item.label : typeof item.value === "string" ? item.value : "",
+        hint: typeof item.description === "string" ? item.description : undefined,
+      }))
+      .filter((item) => item.value)
+    : [];
+  if (options.length === 0) throw new Error(`Host select prompt has no options`);
+  const defaultValue = stringField(params, "defaultValue") ?? options[0]!.value;
+  if (!canPrompt()) return defaultValue;
+  const answers = await inquirer.prompt<{ value: string }>([{
+    type: "select",
+    name: "value",
+    message,
+    default: defaultValue,
+    choices: options.map((option) => ({
+      name: option.label,
+      value: option.value,
+      description: option.hint,
+    })),
+  }]);
+  return answers.value;
+}
+
+function openHostExternal(params: unknown, options: HostRequestHandlingOptions = {}): null {
+  const target = stringField(params, "target");
+  if (!target) throw new Error(`open.external requires target`);
+  if (!options.quietOpen) console.error(`open ${target}`);
+  openExternalTarget(target);
+  return null;
+}
+
+async function runHostCommand(params: unknown): Promise<{ exitCode: number; stdout: string | null; stderr: string | null }> {
+  if (!isRecord(params) || !Array.isArray(params.argv) || params.argv.some((item) => typeof item !== "string")) {
+    throw new Error(`host.command.run requires argv`);
+  }
+  const argv = params.argv as string[];
+  if (argv.length === 0) throw new Error(`host.command.run argv must not be empty`);
+  const mode = params.mode === "interactive" ? "interactive" : "capture";
+  const cwd = stringField(params, "cwd");
+  const reason = stringField(params, "reason");
+  const env = isRecord(params.env)
+    ? Object.fromEntries(Object.entries(params.env).filter(([, value]) => value === undefined || typeof value === "string")) as Record<string, string | undefined>
+    : undefined;
+  const stdin = params.stdin === null || typeof params.stdin === "string" ? params.stdin : undefined;
+
+  if (process.env.RIGKIT_TRUST_HOST_COMMANDS !== "1") {
+    const allowed = await confirmHostCommand({ argv, cwd, env, mode, reason });
+    if (!allowed) throw new Error(`Host command denied`);
+  }
+
+  if (mode === "interactive") {
+    const proc = Bun.spawn(argv, {
+      cwd,
+      env: env ? { ...process.env, ...env } : process.env,
+      stdin: stdin === undefined || stdin === null ? "inherit" : "pipe",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    if (stdin !== undefined && stdin !== null) {
+      const writer = proc.stdin;
+      if (!writer) throw new Error(`Host command stdin is unavailable`);
+      writer.write(stdin);
+      writer.end();
+    }
+    return { exitCode: await proc.exited, stdout: null, stderr: null };
+  }
+
+  const proc = Bun.spawn(argv, {
+    cwd,
+    env: env ? { ...process.env, ...env } : process.env,
+    stdin: stdin === undefined || stdin === null ? "ignore" : "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (stdin !== undefined && stdin !== null) {
+    const writer = proc.stdin;
+    if (!writer) throw new Error(`Host command stdin is unavailable`);
+    writer.write(stdin);
+    writer.end();
+  }
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+async function confirmHostCommand(input: {
+  argv: string[];
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  mode: "capture" | "interactive";
+  reason?: string;
+}): Promise<boolean> {
+  if (!canPrompt()) {
+    throw new Error(`Host command requires confirmation in an interactive terminal`);
+  }
+
+  const pairs: Array<[string, string]> = [
+    ["command", input.argv.map(shellDisplay).join(" ")],
+    ["mode", input.mode],
+  ];
+  if (input.cwd) pairs.push(["cwd", input.cwd]);
+  if (input.env && Object.keys(input.env).length > 0) {
+    pairs.push(["env", Object.keys(input.env).join(", ")]);
+  }
+  if (input.reason) pairs.push(["reason", input.reason]);
+
+  console.error("");
+  console.error(`${ui.warn("!")} ${ui.bold("this config wants to run a command on your machine")}`);
+  console.error("");
+  console.error(ui.kvList(pairs));
+  console.error("");
+  return await promptHostConfirm({ message: "Allow?", defaultValue: false });
+}
+
+function isHostRequestEvent(value: unknown): value is HostRequestEvent {
+  return isRecord(value) &&
+    value.type === "host.request" &&
+    (typeof value.requestId === "string" || typeof value.id === "string") &&
+    typeof value.method === "string";
+}
+
+function isHostCapabilityRequestEvent(value: unknown): value is HostCapabilityRequestEvent {
+  return isRecord(value) &&
+    value.type === "host.capability.request" &&
+    (typeof value.requestId === "string" || typeof value.id === "string") &&
+    (value.nodePath === undefined || typeof value.nodePath === "string") &&
+    typeof value.capability === "string";
+}
+
+function isWorkflowPlan(value: unknown): value is WorkflowPlan {
+  return isRecord(value) &&
+    typeof value.workflow === "string" &&
+    typeof value.cachedNodeCount === "number" &&
+    typeof value.nodeCount === "number" &&
+    Array.isArray(value.nodes);
+}
+
+function isWorkspaceRecord(value: unknown): value is WorkspaceRecord {
+  return isRecord(value) &&
+    typeof value.name === "string" &&
+    typeof value.workflow === "string" &&
+    isRecord(value.ctx);
+}
+
+function isDevMachineEvent(value: unknown): value is DevMachineEvent {
+  return isRecord(value) &&
+    typeof value.type === "string" &&
+    !value.type.startsWith("run.") &&
+    value.type !== "host.request" &&
+    value.type !== "host.capability.request";
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+  return isRecord(value) && typeof value[key] === "string" ? value[key] : undefined;
+}
+
+function booleanField(value: unknown, key: string): boolean | undefined {
+  return isRecord(value) && typeof value[key] === "boolean" ? value[key] : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return Boolean(value && typeof value === "object" && "then" in value && typeof value.then === "function");
+}
+
+function shellDisplay(value: string): string {
+  return /^[A-Za-z0-9_./:=@+-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
+function wantsJson(invocation: CliInvocation): boolean {
+  return invocation.json;
+}
+
+function printJson(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function printInteractiveOutputGap(invocation: CliInvocation): void {
+  if (wantsJson(invocation) || !process.stdout.isTTY) return;
+  console.log("");
+}
+
+function printPlan(plan: WorkflowPlan): void {
+  console.log(`${ui.bold(plan.workflow)}  ${ui.dim(`${plan.cachedNodeCount}/${plan.nodeCount} cached`)}`);
+  console.log("");
+
+  const rows = plan.nodes.map((node) => [
+    { text: String(node.index + 1), style: ui.dim },
+    { text: node.status, style: planStatusStyle(node.status) },
+    { text: node.path },
+    { text: node.reason ?? "", style: ui.dim },
+  ]);
+  console.log(ui.columns(["#", "status", "node", "reason"], rows));
+}
+
+function planStatusStyle(status: string): (text: string) => string {
+  switch (status) {
+    case "cached":
+    case "skipped":
+      return ui.dim;
+    case "pending":
+      return ui.warn;
+    case "completed":
+    case "ready":
+    case "applied":
+      return ui.ok;
+    case "failed":
+    case "error":
+      return ui.err;
+    default:
+      return ui.accent;
+  }
+}
+
+function printWorkspaces(
+  workspaces: ReadonlyArray<Pick<WorkspaceRecord, "name" | "workflow" | "createdAt">>,
+): void {
+  if (workspaces.length === 0) {
+    console.log(ui.dim("no workspaces"));
+    return;
+  }
+
+  const rows = workspaces.map((workspace) => [
+    { text: workspace.name, style: ui.bold },
+    { text: workspace.workflow },
+    { text: workspace.createdAt, style: ui.dim },
+    formatWorkspaceAge(workspace.createdAt),
+  ]);
+  console.log(ui.columns(["name", "workflow", "created", "age"], rows));
+}
+
+function formatWorkspaceAge(createdAt: string): { text: string; style: (text: string) => string } {
+  const createdTime = Date.parse(createdAt);
+  if (Number.isNaN(createdTime)) return { text: "unknown", style: ui.dim };
+
+  const ageMs = Math.max(0, Date.now() - createdTime);
+  const minute = 60 * 1000;
+  const hour = 60 * minute;
+  const day = 24 * hour;
+  const text = ageMs < hour
+    ? `${Math.max(1, Math.floor(ageMs / minute))}m`
+    : ageMs < day
+      ? `${Math.floor(ageMs / hour)}h`
+      : `${Math.floor(ageMs / day)}d`;
+
+  if (ageMs < day) return { text, style: ui.ok };
+  if (ageMs <= 3 * day) return { text, style: ui.warn };
+  return { text, style: ui.dim };
+}
+
+function printSnapshots(snapshots: SnapshotRecord[]): void {
+  if (snapshots.length === 0) {
+    console.log(ui.dim("no snapshots"));
+    return;
+  }
+
+  const rows = snapshots.map((snapshot) => [
+    { text: snapshot.id, style: ui.dim },
+    { text: snapshot.workflow },
+    { text: snapshot.nodePath, style: ui.bold },
+    { text: typeof snapshot.metadata.snapshotId === "string" ? snapshot.metadata.snapshotId : "" },
+    { text: snapshot.createdAt, style: ui.dim },
+  ]);
+  console.log(ui.columns(["run", "workflow", "node", "snapshot", "created"], rows));
+}
+
+function printCacheEntries(entries: ReadonlyArray<{
+  scope: "local" | "global";
+  workflow: string;
+  nodePath: string;
+  nodeName: string;
+  createdAt: string;
+  invalidated: boolean;
+  fragmentHash?: string;
+}>): void {
+  if (entries.length === 0) {
+    console.log(ui.dim("no cache entries"));
+    return;
+  }
+
+  const rows = entries.map((entry) => [
+    { text: entry.scope, style: ui.dim },
+    { text: entry.workflow },
+    { text: entry.nodePath || entry.nodeName, style: ui.bold },
+    {
+      text: entry.invalidated ? "invalidated" : "valid",
+      style: entry.invalidated ? ui.warn : ui.ok,
+    },
+    { text: entry.fragmentHash ? entry.fragmentHash.slice(0, 19) : "", style: ui.dim },
+    { text: entry.createdAt, style: ui.dim },
+  ]);
+  console.log(ui.columns(["scope", "workflow", "node", "status", "fragment", "created"], rows));
+}
+
+function printConfig(info: EngineProjectInfo): void {
+  console.log(ui.kvList([
+    ["config", info.configPath],
+    ["project", info.projectDir],
+    ["state", info.statePath ?? ""],
+    ["workflow", info.workflow?.name ?? ui.dim("(not loaded)")],
+    ["providers", info.workflow?.providers.join(", ") ?? ""],
+  ]));
+}
+
+function normalizeListTarget(target: string | undefined): "workspaces" | "snapshots" | "config" {
+  if (!target || target === "workspaces" || target === "workspace" || target === "vms" || target === "vm") {
+    return "workspaces";
+  }
+  if (target === "snapshots" || target === "snapshot") return "snapshots";
+  if (target === "config" || target === "machine" || target === "machines") return "config";
+  throw new Error(`Unknown ls target ${target}. Expected workspaces, snapshots, or config.`);
+}
+
+function renderEvent(event: DevMachineEvent): void {
+  const write = (line: string) => process.stderr.write(`${line}\n`);
+  switch (event.type) {
+    case "definition.loaded":
+      write(`${ui.dim(ui.sym.dot)} ${ui.dim(`loaded ${event.workflow}`)}`);
+      return;
+    case "plan.created":
+      write(`${ui.accent(ui.sym.active)} ${ui.bold(event.workflow)}  ${ui.dim(`${event.cachedNodeCount}/${event.nodeCount} cached`)}`);
+      return;
+    case "workflow.apply.started":
+      write(`${ui.accent(ui.sym.active)} workflow ${ui.bold(event.workflow)}`);
+      return;
+    case "workflow.apply.completed": {
+      const summary = event.nodeCount > 0
+        ? `  ${ui.dim(`${event.cachedNodeCount}/${event.nodeCount} cached`)}`
+        : "";
+      write(`${ui.ok(ui.sym.ok)} ${ui.bold(event.workflow)} ${ui.dim("prepared")}${summary}`);
+      return;
+    }
+    case "node.cached":
+      write(`  ${ui.dim(ui.sym.ok)} ${ui.dim(`${event.nodePath}  cached`)}`);
+      return;
+    case "vm.created":
+      write(`  ${ui.dim(event.fromSnapshotId ? `vm ${event.vmId} from ${event.fromSnapshotId}` : `vm ${event.vmId} created`)}`);
+      return;
+    case "node.started":
+      write(`  ${ui.accent(ui.sym.active)} ${ui.bold(String(event.nodePath))}`);
+      return;
+    case "node.completed":
+      write(`  ${ui.ok(ui.sym.ok)} ${event.nodePath}`);
+      return;
+    case "command.started":
+      write(`    ${ui.dim(`$ ${event.commandName}`)}`);
+      return;
+    case "command.output":
+      process.stderr.write(event.data);
+      return;
+    case "command.completed":
+      if (event.exitCode !== 0) {
+        write(`    ${ui.err(`${event.commandName} exited ${event.exitCode}`)}`);
+      }
+      return;
+    case "log.output": {
+      const prefix = event.stream && event.stream !== "info" && event.stream !== "stdout"
+        ? `[${event.stream}] `
+        : "";
+      for (const line of event.data.replace(/\r/g, "").split("\n")) {
+        if (!line) continue;
+        process.stderr.write(`${prefix}${line}\n`);
+      }
+      return;
+    }
+    case "interaction.awaiting_user":
+      write(`  ${ui.accent(ui.sym.arrow)} waiting on ${ui.bold(event.label)}`);
+      write(`    ${ui.dim(event.url)}`);
+      return;
+    case "interaction.completed":
+      write(`  ${ui.ok(ui.sym.ok)} ${ui.dim(`${event.label} completed`)}`);
+      return;
+    case "artifact.created":
+      write(`    ${ui.dim(`+ ${event.providerId}:${event.kind}`)}`);
+      return;
+    case "workspace.create.started":
+      write(`${ui.accent(ui.sym.active)} creating workspace ${ui.bold(String(event.workspaceName))}`);
+      return;
+    case "workspace.ready":
+      write(`${ui.ok(ui.sym.ok)} ${ui.bold(String(event.workspaceId))} ${ui.dim("ready")}`);
+      return;
+    case "workspace.remove.started":
+      write(`${ui.accent(ui.sym.active)} removing workspace ${ui.bold(String(event.workspaceName))}`);
+      return;
+    case "workspace.remove.completed":
+      write(`${ui.ok(ui.sym.ok)} removed ${ui.bold(String(event.workspaceName))}`);
+      return;
+    case "workspace.operation.started":
+      write(`${ui.accent(ui.sym.active)} running ${ui.bold(String(event.operationId))} on ${ui.bold(String(event.workspaceName))}`);
+      return;
+    case "workspace.operation.completed":
+      write(`${ui.ok(ui.sym.ok)} ran ${ui.bold(String(event.operationId))} on ${ui.bold(String(event.workspaceName))}`);
+      return;
+    default:
+      return;
+  }
+}