@h-rig/cli-surface-plugin 0.0.6-alpha.146

package/dist/src/commands/_pi-install.d.ts

@@ -0,0 +1,42 @@
+export type PiInstallCheck = {
+    readonly ok: boolean;
+    readonly label: string;
+    readonly detail?: string;
+    readonly hint?: string;
+};
+export type CommandRunner = (command: string[], options?: {
+    cwd?: string;
+}) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
+export type PiRigInstallStatus = {
+    readonly pi: PiInstallCheck;
+    readonly piRig: PiInstallCheck;
+    readonly extensionPath: string;
+};
+export declare function resolvePiRigExtensionPath(homeDir: string): string;
+export declare function resolvePiRigPackageSource(projectRoot: string, exists?: (path: string) => boolean): string;
+export declare function checkPiRigInstall(input?: {
+    readonly homeDir?: string;
+    readonly commandRunner?: CommandRunner;
+    readonly exists?: (path: string) => boolean;
+}): Promise<PiRigInstallStatus>;
+export declare function ensurePiRigInstalled(input: {
+    readonly projectRoot: string;
+    readonly homeDir?: string;
+    readonly commandRunner?: CommandRunner;
+}): Promise<PiRigInstallStatus & {
+    installedPath: string;
+}>;
+export declare function ensureRemotePiRigInstalled(input: {
+    readonly requestJson: (pathname: string, init?: RequestInit) => Promise<unknown>;
+}): Promise<PiRigInstallStatus & {
+    readonly remote: true;
+}>;
+export declare function buildPiSetupChecks(input?: {
+    readonly homeDir?: string;
+    readonly commandRunner?: CommandRunner;
+    readonly exists?: (path: string) => boolean;
+}): Promise<PiInstallCheck[]>;

package/dist/src/commands/_pi-install.js

@@ -0,0 +1,167 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_pi-install.ts
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { resolve } from "path";
+var PI_RIG_PACKAGE_NAME = "@h-rig/pi-rig";
+async function defaultCommandRunner(command, options = {}) {
+  const proc = Bun.spawn(command, { cwd: options.cwd, stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited
+  ]);
+  return { exitCode, stdout, stderr };
+}
+function resolvePiRigExtensionPath(homeDir) {
+  return resolve(homeDir, ".pi", "agent", "extensions", "pi-rig");
+}
+function resolvePiRigPackageSource(projectRoot, exists = existsSync) {
+  const localPackage = resolve(projectRoot, "packages", "pi-rig");
+  if (exists(resolve(localPackage, "package.json")))
+    return localPackage;
+  return `npm:${PI_RIG_PACKAGE_NAME}`;
+}
+function resolvePiHomeDir(inputHomeDir) {
+  return inputHomeDir ?? process.env.RIG_PI_HOME_DIR?.trim() ?? homedir();
+}
+function piListContainsPiRig(output) {
+  return output.split(/\r?\n/).some((line) => {
+    const normalized = line.trim();
+    return normalized.includes(PI_RIG_PACKAGE_NAME) || /(?:^|[\\/])packages[\\/]pi-rig(?:$|\s)/.test(normalized);
+  });
+}
+async function safeRun(runner, command, options) {
+  try {
+    return await runner(command, options);
+  } catch (error) {
+    return { exitCode: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+}
+function splitInstallCommand(value) {
+  return value.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((part) => part.replace(/^['"]|['"]$/g, "")) ?? [];
+}
+async function ensurePiBinaryAvailable(input) {
+  const current = await safeRun(input.runner, ["pi", "--version"]);
+  if (current.exitCode === 0) {
+    const updateCommand = process.env.RIG_PI_UPDATE_COMMAND?.trim();
+    if (updateCommand) {
+      const parts2 = splitInstallCommand(updateCommand);
+      if (parts2.length > 0)
+        await safeRun(input.runner, parts2, input.projectRoot ? { cwd: input.projectRoot } : undefined);
+    }
+    return { ok: true, detail: (current.stdout || current.stderr).trim() || undefined };
+  }
+  const installCommand = process.env.RIG_PI_INSTALL_COMMAND?.trim();
+  if (!installCommand) {
+    return {
+      ok: false,
+      error: `${(current.stderr || current.stdout).trim() || "pi --version failed"}. Set RIG_PI_INSTALL_COMMAND to a supported installer or install Pi manually.`
+    };
+  }
+  const parts = splitInstallCommand(installCommand);
+  if (parts.length === 0) {
+    return { ok: false, error: (current.stderr || current.stdout).trim() || "pi --version failed" };
+  }
+  const install = await safeRun(input.runner, parts, input.projectRoot ? { cwd: input.projectRoot } : undefined);
+  if (install.exitCode !== 0) {
+    return { ok: false, installedOrUpdated: true, error: (install.stderr || install.stdout).trim() || `Pi install command failed (${install.exitCode})` };
+  }
+  const next = await safeRun(input.runner, ["pi", "--version"]);
+  return {
+    ok: next.exitCode === 0,
+    installedOrUpdated: true,
+    detail: (next.stdout || next.stderr).trim() || undefined,
+    ...next.exitCode === 0 ? {} : { error: (next.stderr || next.stdout).trim() || "pi --version failed after install" }
+  };
+}
+async function checkPiRigInstall(input = {}) {
+  const home = resolvePiHomeDir(input.homeDir);
+  const extensionPath = resolvePiRigExtensionPath(home);
+  if (process.env.RIG_TEST_FAKE_PI_INSTALL === "1") {
+    return {
+      extensionPath,
+      pi: { ok: true, label: "pi", detail: "fake-pi" },
+      piRig: { ok: true, label: "pi-rig global extension", detail: extensionPath }
+    };
+  }
+  const runner = input.commandRunner ?? defaultCommandRunner;
+  const piResult = await safeRun(runner, ["pi", "--version"]);
+  const piListResult = piResult.exitCode === 0 ? await safeRun(runner, ["pi", "list"]) : { exitCode: 1, stdout: "", stderr: "" };
+  const hasPiRig = piListResult.exitCode === 0 && piListContainsPiRig(`${piListResult.stdout}
+${piListResult.stderr}`);
+  const hasLegacyBridgeScaffold = !hasPiRig && (input.exists ?? existsSync)(extensionPath);
+  return {
+    extensionPath,
+    pi: {
+      ok: piResult.exitCode === 0,
+      label: "pi",
+      detail: (piResult.stdout || piResult.stderr).trim() || undefined,
+      hint: piResult.exitCode === 0 ? undefined : "Install Pi/OMP manually or set RIG_PI_INSTALL_COMMAND before verifying with bare `rig` / Cockpit \u2192 Doctor."
+    },
+    piRig: {
+      ok: hasPiRig,
+      label: "pi-rig global extension",
+      detail: hasPiRig ? piListResult.stdout.trim() || PI_RIG_PACKAGE_NAME : hasLegacyBridgeScaffold ? `legacy bridge scaffold at ${extensionPath}` : undefined,
+      hint: hasPiRig ? undefined : `Install the Rig OMP extension with \`pi install ${PI_RIG_PACKAGE_NAME}\`, then verify with bare \`rig\` / Cockpit \u2192 Doctor.`
+    }
+  };
+}
+async function ensurePiRigInstalled(input) {
+  const home = resolvePiHomeDir(input.homeDir);
+  if (process.env.RIG_TEST_FAKE_PI_INSTALL === "1") {
+    const status = await checkPiRigInstall({ homeDir: home, commandRunner: input.commandRunner });
+    return { ...status, installedPath: status.extensionPath };
+  }
+  const runner = input.commandRunner ?? defaultCommandRunner;
+  const piAvailable = await ensurePiBinaryAvailable({ runner, projectRoot: input.projectRoot });
+  if (!piAvailable.ok) {
+    throw new Error(`Pi install/update failed: ${piAvailable.error ?? "pi unavailable"}`);
+  }
+  const packageSource = resolvePiRigPackageSource(input.projectRoot);
+  const install = await runner(["pi", "install", packageSource], { cwd: input.projectRoot });
+  if (install.exitCode !== 0) {
+    throw new Error(`pi-rig install failed: ${(install.stderr || install.stdout).trim() || `exit ${install.exitCode}`}`);
+  }
+  const next = await checkPiRigInstall({ homeDir: home, commandRunner: runner });
+  return { ...next, installedPath: packageSource };
+}
+async function ensureRemotePiRigInstalled(input) {
+  const payload = await input.requestJson("/api/pi-rig/install", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ package: PI_RIG_PACKAGE_NAME, scope: "global" })
+  });
+  const record = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  const piOk = record.piOk === true || record.ok === true;
+  const piRigOk = record.piRigOk === true || record.installed === true || record.ok === true;
+  const extensionPath = typeof record.extensionPath === "string" ? record.extensionPath : "remote:~/.pi/agent/extensions/pi-rig";
+  return {
+    remote: true,
+    extensionPath,
+    pi: {
+      ok: piOk,
+      label: "pi",
+      detail: typeof record.piVersion === "string" ? record.piVersion : undefined,
+      hint: piOk ? undefined : "Install/update Pi on the selected remote control host, then verify with bare `rig` / Cockpit \u2192 Doctor."
+    },
+    piRig: {
+      ok: piRigOk,
+      label: "pi-rig global extension",
+      detail: extensionPath,
+      hint: piRigOk ? undefined : `Install/enable the Rig OMP extension (${PI_RIG_PACKAGE_NAME}) on the selected remote control host, then verify with bare \`rig\` / Cockpit \u2192 Doctor.`
+    }
+  };
+}
+async function buildPiSetupChecks(input = {}) {
+  const status = await checkPiRigInstall(input);
+  return [status.pi, status.piRig];
+}
+export {
+  resolvePiRigPackageSource,
+  resolvePiRigExtensionPath,
+  ensureRemotePiRigInstalled,
+  ensurePiRigInstalled,
+  checkPiRigInstall,
+  buildPiSetupChecks
+};

package/dist/src/commands/_policy.d.ts

@@ -0,0 +1,8 @@
+import { type RunnerContext } from "../runner";
+export type PolicyMode = "off" | "observe" | "enforce";
+export declare function resolveEffectivePolicyMode(context: RunnerContext): PolicyMode;
+export declare function appendControlledBashAudit(context: RunnerContext, mode: PolicyMode, command: string, args: string[], matchedRuleIds: string[], action?: "warn" | "blocked"): void;
+export declare function enforceNativeCommandPolicy(context: RunnerContext, args: string[], options: {
+    commandPrefix: string;
+    writeAuditLog: boolean;
+}): Promise<void>;

package/dist/src/commands/_policy.js

@@ -0,0 +1,138 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_policy.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// packages/cli-surface-plugin/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
+function formatCommand(parts) {
+  return parts.map((part) => /[^a-zA-Z0-9_./:-]/.test(part) ? JSON.stringify(part) : part).join(" ");
+}
+
+// packages/cli-surface-plugin/src/commands/_paths.ts
+import { resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/runtime/layout";
+function resolveControlPlaneHostStateRoot(projectRoot) {
+  return resolve(projectRoot, ".rig");
+}
+function resolveControlPlaneHostLogsDir(projectRoot) {
+  return resolve(resolveControlPlaneHostStateRoot(projectRoot), "logs");
+}
+function resolveControlPlaneDefinitionRoot(projectRoot) {
+  return resolve(projectRoot, "rig");
+}
+
+// packages/cli-surface-plugin/src/commands/_policy.ts
+function loadPolicyFile(projectRoot) {
+  const policyPath = resolve2(resolveControlPlaneDefinitionRoot(projectRoot), "policy", "policy.json");
+  if (!existsSync(policyPath)) {
+    return { mode: "observe", rules: [] };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(policyPath, "utf8"));
+    const mode = parsed.mode === "off" || parsed.mode === "observe" || parsed.mode === "enforce" ? parsed.mode : "observe";
+    const rules = Array.isArray(parsed.rules) ? parsed.rules.filter((value) => Boolean(value && typeof value === "object" && !Array.isArray(value))).map((value, index) => {
+      const rule = {
+        id: typeof value.id === "string" && value.id.trim() ? value.id.trim() : `rule-${index + 1}`
+      };
+      const reason = typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : null;
+      const match = typeof value.match === "string" && value.match.trim() ? value.match.trim() : null;
+      const command = typeof value.command === "string" && value.command.trim() ? value.command.trim() : null;
+      if (reason)
+        return { ...rule, reason };
+      if (match && command)
+        return { ...rule, match, command };
+      if (match)
+        return { ...rule, match };
+      if (command)
+        return { ...rule, command };
+      return rule;
+    }) : [];
+    return { mode, rules };
+  } catch {
+    return { mode: "observe", rules: [] };
+  }
+}
+function matchingRules(command, rules) {
+  return rules.filter((rule) => {
+    const rawPattern = rule.command ?? rule.match;
+    if (!rawPattern)
+      return false;
+    try {
+      return new RegExp(rawPattern, "i").test(command);
+    } catch {
+      return command.includes(rawPattern);
+    }
+  });
+}
+function resolveEffectivePolicyMode(context) {
+  const envMode = process.env.RIG_BASH_MODE;
+  if (envMode === "off" || envMode === "observe" || envMode === "enforce") {
+    return envMode;
+  }
+  return context.policyMode ?? loadPolicyFile(context.projectRoot).mode;
+}
+function appendControlledBashAudit(context, mode, command, args, matchedRuleIds, action) {
+  if (mode === "off") {
+    return;
+  }
+  const logsDir = resolveControlPlaneHostLogsDir(context.projectRoot);
+  const logFile = resolve2(logsDir, "controlled-bash.jsonl");
+  mkdirSync(logsDir, { recursive: true });
+  const payload = {
+    timestamp: new Date().toISOString(),
+    mode,
+    cwd: process.cwd(),
+    pid: process.pid,
+    ppid: process.ppid,
+    argv: args,
+    command,
+    matchedRuleIds
+  };
+  if (action) {
+    payload.action = action;
+  }
+  appendFileSync(logFile, `${JSON.stringify(payload)}
+`, "utf-8");
+}
+async function enforceNativeCommandPolicy(context, args, options) {
+  const mode = resolveEffectivePolicyMode(context);
+  const command = formatCommand([options.commandPrefix, ...args]);
+  const rules = matchingRules(command, loadPolicyFile(context.projectRoot).rules);
+  const matchedRuleIds = rules.map((rule) => rule.id);
+  const action = rules.length === 0 ? "allow" : mode === "enforce" ? "block" : "warn";
+  await context.emitEvent("policy.decision", {
+    target: "command",
+    command,
+    mode,
+    allowed: action !== "block",
+    matchedRuleIds,
+    reasons: rules.map((rule) => rule.reason).filter(Boolean)
+  });
+  if (options.writeAuditLog) {
+    appendControlledBashAudit(context, mode, command, args, matchedRuleIds, action === "block" ? "blocked" : action === "warn" ? "warn" : undefined);
+  }
+  if (action === "block") {
+    throw new CliError(`Policy blocked command: ${command}`, 126, {
+      hint: "Review rig/policy/policy.json, or re-run with `--policy-mode observe` to log instead of block."
+    });
+  }
+}
+export {
+  resolveEffectivePolicyMode,
+  enforceNativeCommandPolicy,
+  appendControlledBashAudit
+};

package/dist/src/commands/_probes.d.ts

@@ -0,0 +1 @@
+export declare function runQuietBinaryProbe(binaryPath: string, args: string[], cwd: string): Promise<boolean>;

package/dist/src/commands/_probes.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_probes.ts
+async function runQuietBinaryProbe(binaryPath, args, cwd) {
+  try {
+    const run = await Bun.$`${binaryPath} ${args}`.cwd(cwd).quiet().nothrow();
+    return run.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+export {
+  runQuietBinaryProbe
+};

package/dist/src/commands/_run-driver-helpers.d.ts

@@ -0,0 +1,26 @@
+export type SourceTaskContract = {
+    id: string;
+    title?: string | null;
+    description?: string | null;
+    body?: string | null;
+    acceptanceCriteria?: string | null;
+    acceptance_criteria?: string | null;
+    sourceIssueId?: string | null;
+    status?: string | null;
+    issueType?: string | null;
+    role?: string | null;
+    validation?: string[];
+    validators?: string[];
+    labels?: string[];
+    scope?: string[];
+};
+export declare function buildRunPrompt(input: {
+    projectRoot: string;
+    taskId?: string | undefined;
+    fallbackTitle?: string | undefined;
+    fallbackDescription?: string | undefined;
+    fallbackAcceptanceCriteria?: string | undefined;
+    sourceTask?: SourceTaskContract | null;
+    initialPrompt?: string;
+    runtimeAdapter: "pi";
+}): string;

package/dist/src/commands/_run-driver-helpers.js

@@ -0,0 +1,132 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_run-driver-helpers.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// packages/cli-surface-plugin/src/commands/_paths.ts
+import { resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/runtime/layout";
+function resolveControlPlaneMonorepoRoot(projectRoot) {
+  return resolveMonorepoRoot(projectRoot);
+}
+function resolveControlPlaneTaskConfigPath(projectRoot) {
+  return resolve(resolveControlPlaneMonorepoRoot(projectRoot), ".rig", "task-config.json");
+}
+
+// packages/cli-surface-plugin/src/commands/_run-driver-helpers.ts
+function readLatestBeadRecord(projectRoot, taskId) {
+  const issuesPath = resolve2(resolveControlPlaneMonorepoRoot(projectRoot), ".beads", "issues.jsonl");
+  if (!existsSync(issuesPath)) {
+    return null;
+  }
+  let latest = null;
+  for (const line of readFileSync(issuesPath, "utf8").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed)
+      continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        continue;
+      const record = parsed;
+      if (record.id === taskId)
+        latest = record;
+    } catch {}
+  }
+  return latest;
+}
+function firstPromptString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim())
+      return value.trim();
+  }
+  return null;
+}
+function uniqueStrings(values) {
+  return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
+}
+function renderSourceTaskContract(task, validation) {
+  if (!task)
+    return validation.length > 0 ? [`Validation: ${validation.join(", ")}`] : [];
+  const lines = [`id: ${task.id}`];
+  if (task.sourceIssueId)
+    lines.push(`source issue: ${task.sourceIssueId}`);
+  if (task.status)
+    lines.push(`status: ${task.status}`);
+  if (task.issueType)
+    lines.push(`issue type: ${task.issueType}`);
+  if (task.role)
+    lines.push(`role: ${task.role}`);
+  if (validation.length > 0)
+    lines.push(`validation: ${validation.join(", ")}`);
+  return lines;
+}
+function renderSourceScopeValidation(task, validation) {
+  if (task || validation.length === 0)
+    return "";
+  return `Validation:
+- ${validation.join(`
+- `)}`;
+}
+function readTaskScopeText(projectRoot, taskId) {
+  try {
+    const parsed = JSON.parse(readFileSync(resolveControlPlaneTaskConfigPath(projectRoot), "utf8"));
+    const entry = parsed[taskId] ?? {};
+    const scope = Array.isArray(entry.scope) ? entry.scope.filter((item) => typeof item === "string") : [];
+    const validation = Array.isArray(entry.validation) ? entry.validation.filter((item) => typeof item === "string") : [];
+    const lines = [];
+    if (scope.length > 0)
+      lines.push(`Scope:
+- ${scope.join(`
+- `)}`);
+    if (validation.length > 0)
+      lines.push(`Validation:
+- ${validation.join(`
+- `)}`);
+    return lines.join(`
+
+`);
+  } catch {
+    return "";
+  }
+}
+function providerInstructionLines(_runtimeAdapter) {
+  return ["Keep file writes inside the scoped task workspace and use the bridged Pi tooling for shell and follow-up prompts."];
+}
+function buildRunPrompt(input) {
+  const initialPrompt = input.initialPrompt?.trim() || null;
+  if (!input.taskId) {
+    return initialPrompt ?? input.fallbackTitle?.trim() ?? "Continue the requested run and complete the work.";
+  }
+  const bead = readLatestBeadRecord(input.projectRoot, input.taskId);
+  const sourceTask = input.sourceTask ?? null;
+  const sourceDescription = firstPromptString(sourceTask?.description, sourceTask?.body);
+  const sourceAcceptance = firstPromptString(sourceTask?.acceptanceCriteria, sourceTask?.acceptance_criteria);
+  const sourceValidation = uniqueStrings([...sourceTask?.validation ?? [], ...sourceTask?.validators ?? []]);
+  const title = (bead && typeof bead.title === "string" ? bead.title : null) ?? firstPromptString(sourceTask?.title) ?? input.fallbackTitle ?? input.taskId;
+  const description = (bead && typeof bead.description === "string" ? bead.description : null) ?? sourceDescription ?? input.fallbackDescription ?? "";
+  const acceptance = (bead && typeof bead.acceptance_criteria === "string" ? bead.acceptance_criteria : null) ?? sourceAcceptance ?? input.fallbackAcceptanceCriteria ?? "";
+  const scopeText = readTaskScopeText(input.projectRoot, input.taskId);
+  const sourceContractLines = renderSourceTaskContract(sourceTask, sourceValidation);
+  const providerLines = providerInstructionLines(input.runtimeAdapter);
+  return [
+    `You are working on task ${input.taskId}: ${title}.`,
+    description ? `Description:
+${description}` : null,
+    acceptance ? `Acceptance criteria:
+${acceptance}` : null,
+    sourceContractLines.length > 0 ? `Source task contract:
+${sourceContractLines.join(`
+`)}` : null,
+    scopeText || renderSourceScopeValidation(sourceTask, sourceValidation) || null,
+    initialPrompt ? `Additional operator guidance:
+${initialPrompt}` : null,
+    providerLines.length > 0 ? `Provider-specific runtime tooling:
+${providerLines.join(" ")}` : null
+  ].filter((value) => Boolean(value)).join(`
+
+`);
+}
+export {
+  buildRunPrompt
+};

package/dist/src/commands/_run-subcommands.d.ts

@@ -0,0 +1,3 @@
+export declare const RUN_GROUP_SUBCOMMANDS: readonly string[];
+/** True when `rig run <first>` addresses the observe/control group (not a task dispatch). */
+export declare function isRunGroupInvocation(first: string | undefined): boolean;

package/dist/src/commands/_run-subcommands.js

@@ -0,0 +1,31 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_run-subcommands.ts
+var RUN_GROUP_SUBCOMMANDS = [
+  "list",
+  "status",
+  "start",
+  "start-serial",
+  "start-parallel",
+  "show",
+  "timeline",
+  "replay",
+  "attach",
+  "steer",
+  "stop",
+  "resume",
+  "restart",
+  "delete",
+  "cleanup"
+];
+var RUN_GROUP_SUBCOMMAND_SET = new Set(RUN_GROUP_SUBCOMMANDS);
+function isRunGroupInvocation(first) {
+  if (first === undefined)
+    return true;
+  if (first === "--help" || first === "-h" || first === "help")
+    return true;
+  return RUN_GROUP_SUBCOMMAND_SET.has(first);
+}
+export {
+  isRunGroupInvocation,
+  RUN_GROUP_SUBCOMMANDS
+};

package/dist/src/commands/_spinner.d.ts

@@ -0,0 +1,25 @@
+export declare const SPINNER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export type TtySpinner = {
+    setLabel(label: string): void;
+    /** Erase the spinner line so other output can print cleanly. */
+    pause(): void;
+    /** Resume rendering after pause(). */
+    resume(): void;
+    /** Stop for good; optionally leave a final line. */
+    stop(finalLine?: string): void;
+};
+/**
+ * A line-rewriting spinner for async CLI waits. On non-TTY outputs it prints
+ * the label once (and label changes) so logs stay readable without ANSI.
+ */
+export declare function createTtySpinner(input: {
+    label: string;
+    output?: Pick<NodeJS.WriteStream, "write"> & {
+        readonly isTTY?: boolean;
+    };
+    intervalMs?: number;
+    /** Frame glyph cycle; defaults to SPINNER_FRAMES. */
+    frames?: readonly string[];
+    /** Optional glyph decorator (e.g. color), applied on TTY renders only. */
+    styleFrame?: (frame: string) => string;
+}): TtySpinner;

package/dist/src/commands/_spinner.js

@@ -0,0 +1,65 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_spinner.ts
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function createTtySpinner(input) {
+  const output = input.output ?? process.stdout;
+  const isTty = output.isTTY === true;
+  const frames = input.frames && input.frames.length > 0 ? input.frames : SPINNER_FRAMES;
+  let label = input.label;
+  let frame = 0;
+  let paused = false;
+  let stopped = false;
+  let lastPrintedLabel = "";
+  const render = () => {
+    if (stopped || paused)
+      return;
+    if (!isTty) {
+      if (label !== lastPrintedLabel) {
+        output.write(`${label}
+`);
+        lastPrintedLabel = label;
+      }
+      return;
+    }
+    frame = (frame + 1) % frames.length;
+    const glyph = frames[frame] ?? frames[0] ?? "";
+    output.write(`\r\x1B[2K${input.styleFrame ? input.styleFrame(glyph) : glyph} ${label}`);
+  };
+  const clearLine = () => {
+    if (isTty)
+      output.write("\r\x1B[2K");
+  };
+  render();
+  const timer = isTty ? setInterval(render, input.intervalMs ?? 16) : null;
+  return {
+    setLabel(next) {
+      label = next;
+      render();
+    },
+    pause() {
+      paused = true;
+      clearLine();
+    },
+    resume() {
+      if (stopped)
+        return;
+      paused = false;
+      render();
+    },
+    stop(finalLine) {
+      if (stopped)
+        return;
+      stopped = true;
+      if (timer)
+        clearInterval(timer);
+      clearLine();
+      if (finalLine)
+        output.write(`${finalLine}
+`);
+    }
+  };
+}
+export {
+  createTtySpinner,
+  SPINNER_FRAMES
+};

package/dist/src/commands/agent.d.ts

@@ -0,0 +1,3 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime";
+export declare function executeAgent(context: RunnerContext, args: string[]): Promise<CommandOutcome>;