@h-rig/cli 0.0.6-alpha.9 → 0.0.6-alpha.90

package/dist/src/commands/task-report-bug.d.ts

@@ -0,0 +1,19 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime/control-plane/runtime/types";
+type BugPromptStyleOptions = {
+    color?: boolean;
+};
+export declare function executeTaskReportBug(context: RunnerContext, args: string[]): Promise<CommandOutcome>;
+export declare function promptBugText(message: string, defaultValue: string | undefined, options?: {
+    placeholder?: string;
+    required?: boolean;
+}): Promise<string>;
+export declare function validateRequiredBugPromptValue(value: string | undefined, label: string): string | undefined;
+type BugPromptExampleSection = "incident" | "reproduction" | "evidence" | "routing" | "browser";
+export declare function bugPromptExampleText(section: BugPromptExampleSection, options?: BugPromptStyleOptions): string;
+export declare function promptBugConfirm(message: string, initialValue: boolean): Promise<boolean>;
+export declare function formatDroppedAssetDefault(value: string): string;
+export declare function splitDroppedAssetList(value: string | undefined, options?: {
+    splitWhitespace?: boolean;
+}): string[];
+export {};

package/dist/src/commands/task-report-bug.js

@@ -2,17 +2,213 @@
 // packages/cli/src/commands/task-report-bug.ts
 import { existsSync as existsSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
 import { resolve as resolve3 } from "path";
-import * as clack from "@clack/prompts";
+
+// packages/cli/src/app/drone-ui.ts
+import { ProcessTerminal, TUI, Text, Input, SelectList, matchesKey } from "@earendil-works/pi-tui";
+
+// packages/cli/src/app/theme.ts
+var RIG_PALETTE = {
+  ink: "#f2f3f6",
+  ink2: "#aeb0ba",
+  ink3: "#6c6e79",
+  ink4: "#44464f",
+  accent: "#ccff4d",
+  accentDim: "#a9d63f",
+  cyan: "#56d8ff",
+  red: "#ff5d5d",
+  yellow: "#ffd24d"
+};
+function hexToRgb(hex) {
+  const value = hex.replace("#", "");
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16)
+  ];
+}
+function fg(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  return (text) => `\x1B[38;2;${r};${g};${b}m${text}\x1B[39m`;
+}
+var ink = fg(RIG_PALETTE.ink);
+var ink2 = fg(RIG_PALETTE.ink2);
+var ink3 = fg(RIG_PALETTE.ink3);
+var ink4 = fg(RIG_PALETTE.ink4);
+var accent = fg(RIG_PALETTE.accent);
+var accentDim = fg(RIG_PALETTE.accentDim);
+var cyan = fg(RIG_PALETTE.cyan);
+var red = fg(RIG_PALETTE.red);
+var yellow = fg(RIG_PALETTE.yellow);
+function bold(text) {
+  return `\x1B[1m${text}\x1B[22m`;
+}
+var DRONE_ART = [
+  "  .-=-.                   .-=-.   ",
+  " ( !!! )                 ( !!! )  ",
+  "  '-=-'._               _.'-=-'   ",
+  "        '._           _.'         ",
+  "           '=$$$$$$$=.'           ",
+  "          =$$$$$$$$$$$=           ",
+  "         $$$@@@@@@@@@@$$$         ",
+  "        $$$@@        @@$$$        ",
+  "        $$@    ?     @$$$         ",
+  "        $$$@   '-'   @$$$         ",
+  "        $$$@@        @@$$$        ",
+  "         $$$@@@@@@@@@@$$$         ",
+  "          =$$$$$$$$$$$=           ",
+  "           '=$$$$$$$=.'           ",
+  "        _.'           '._         ",
+  "  .-=-.'                 '.-=-.   ",
+  " ( !!! )                 ( !!! )  ",
+  "  '-=-'                   '-=-'   "
+];
+var EYE_FRAMES = ["@", "o", "."];
+var DRONE_WIDTH = DRONE_ART[0].length;
+var DRONE_HEIGHT = DRONE_ART.length;
+var MICRO_BLADES = ["---", "\\\\\\", "|||", "///"];
+function microDroneFrame(tick) {
+  const blade = MICRO_BLADES[tick % MICRO_BLADES.length];
+  const eye = EYE_FRAMES[Math.floor(tick / 2) % EYE_FRAMES.length];
+  return `(${blade})${eye}(${blade})`;
+}
+var MICRO_DRONE_FRAMES = Array.from({ length: 12 }, (_, index) => microDroneFrame(index));
+
+// packages/cli/src/app/drone-ui.ts
+var isTty = () => Boolean(process.stdout.isTTY);
+function hairline(width = Math.min(process.stdout.columns ?? 80, 100)) {
+  return ink4("\u2500".repeat(Math.max(10, width)));
+}
+function droneIntro(title, subtitle) {
+  console.log("");
+  console.log(` ${accent("\u258D")}${bold(ink(title))}${subtitle ? ink3(` \u2014 ${subtitle}`) : ""}`);
+  console.log(hairline());
+}
+function droneOutro(text) {
+  console.log(hairline());
+  console.log(` ${accent("\u25C6")} ${ink2(text)}`);
+  console.log("");
+}
+function droneNote(message, title) {
+  if (title)
+    console.log(` ${accentDim("\u25C7")} ${bold(ink2(title))}`);
+  for (const line of message.split(`
+`)) {
+    console.log(` ${ink4("\u2502")} ${line}`);
+  }
+}
+function droneStep(text) {
+  console.log(` ${accent("\u203A")} ${ink(text)}`);
+}
+function droneInfo(text) {
+  console.log(` ${cyan("\xB7")} ${ink2(text)}`);
+}
+function droneCancel(text) {
+  console.log(` ${red("\u2716")} ${ink3(text)}`);
+}
+var SELECT_THEME = {
+  selectedPrefix: (text) => accent(text),
+  selectedText: (text) => bold(ink(text)),
+  description: (text) => ink3(text),
+  scrollInfo: (text) => ink4(text),
+  noMatch: (text) => ink3(text)
+};
+async function runMiniTui(build) {
+  const terminal = new ProcessTerminal;
+  const tui = new TUI(terminal);
+  let settled = false;
+  return await new Promise((resolve) => {
+    const finish = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      tui.stop();
+      resolve(result);
+    };
+    build(tui, finish);
+    tui.start();
+  });
+}
+async function droneSelect(input) {
+  if (!isTty() || input.options.length === 0) {
+    return input.initialValue ?? input.options[0]?.value ?? null;
+  }
+  return runMiniTui((tui, finish) => {
+    tui.addChild(new Text(` ${accent("\u258D")}${bold(ink(input.message))}`));
+    const items = input.options.map((option) => ({
+      value: option.value,
+      label: option.label,
+      ...option.hint ? { description: option.hint } : {}
+    }));
+    const list = new SelectList(items, Math.min(items.length, 12), SELECT_THEME);
+    const initialIndex = input.initialValue ? items.findIndex((item) => item.value === input.initialValue) : -1;
+    if (initialIndex > 0)
+      list.setSelectedIndex(initialIndex);
+    list.onSelect = (item) => finish(item.value);
+    list.onCancel = () => finish(null);
+    tui.addChild(list);
+    tui.addChild(new Text(ink4(" \u2191\u2193 navigate \xB7 enter select \xB7 esc cancel")));
+    tui.setFocus(list);
+    tui.addInputListener((data) => {
+      if (matchesKey(data, "ctrl+c") || matchesKey(data, "escape")) {
+        finish(null);
+        return { consume: true };
+      }
+      return;
+    });
+  });
+}
+async function droneText(input) {
+  if (!isTty())
+    return input.initialValue ?? null;
+  return runMiniTui((tui, finish) => {
+    tui.addChild(new Text(` ${accent("\u258D")}${bold(ink(input.message))}${input.placeholder ? ink4(`  (${input.placeholder})`) : ""}`));
+    const field = new Input;
+    if (input.initialValue)
+      field.setValue(input.initialValue);
+    field.onSubmit = (value) => finish(value);
+    field.onEscape = () => finish(null);
+    tui.addChild(field);
+    tui.addChild(new Text(ink4(" enter submit \xB7 esc cancel")));
+    tui.setFocus(field);
+    tui.addInputListener((data) => {
+      if (matchesKey(data, "ctrl+c")) {
+        finish(null);
+        return { consume: true };
+      }
+      return;
+    });
+  });
+}
+async function droneConfirm(input) {
+  const answer = await droneSelect({
+    message: input.message,
+    options: [
+      { value: "yes", label: "Yes" },
+      { value: "no", label: "No" }
+    ],
+    initialValue: input.initialValue === false ? "no" : "yes"
+  });
+  return answer === null ? null : answer === "yes";
+}
+
+// packages/cli/src/commands/task-report-bug.ts
 import pc from "picocolors";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+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(" ");
 }
@@ -36,7 +232,7 @@ function takeOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       value = next;
       index += 1;
@@ -241,15 +437,15 @@ function buildBugReportMarkdown(input, browser, screenshots, assets) {
     ...input.issueId ? [
       `- Canonical task assets live under \`artifacts/${input.issueId}/bug-report/\`.`,
       `- Start with \`artifacts/${input.issueId}/bug-report/task.md\` and the files in \`artifacts/${input.issueId}/bug-report/assets/\`.`,
-      browserRequired ? `- Run \`bun run rig task info --task ${input.issueId}\` to confirm browser wiring before debugging.` : `- Run \`bun run rig task info --task ${input.issueId}\` to confirm scope and artifact links before debugging.`
+      browserRequired ? `- Run \`rig task info --task ${input.issueId}\` to confirm browser wiring before debugging.` : `- Run \`rig task info --task ${input.issueId}\` to confirm scope and artifact links before debugging.`
     ] : [
-      "- Draft-only report: convert this into a beads task before assigning it to an agent run."
+      "- Draft-only report: convert this into a Rig task before assigning it to an agent run."
     ],
     "",
     "## Validation",
     "",
     "```bash",
-    ...input.issueId ? [`bun run rig task validate --task ${input.issueId}`] : [],
+    ...input.issueId ? [`rig task validate --task ${input.issueId}`] : [],
     ...browserRequired ? [
       "bun run app:check:browser:hp-next",
       "bun run app:e2e:browser:hp-next"
@@ -344,7 +540,7 @@ async function executeTaskReportBug(context, args) {
   const noBrowserFlag = takeFlag(pending, "--no-browser");
   pending = noBrowserFlag.rest;
   if (browserFlag.value && noBrowserFlag.value) {
-    throw new CliError2("Pass only one of --browser or --no-browser.");
+    throw new CliError("Pass only one of --browser or --no-browser.", 1, { hint: "Re-run `rig task report-bug` with just one of the flags." });
   }
   const overwriteFlag = takeFlag(pending, "--overwrite");
   pending = overwriteFlag.rest;
@@ -396,7 +592,7 @@ async function executeTaskReportBug(context, args) {
   pending = outputRootResult.rest;
   const slugResult = takeOption(pending, "--slug");
   pending = slugResult.rest;
-  requireNoExtraArgs(pending, "bun run rig report-bug [--no-prompt] [--no-beads] [--browser|--no-browser] --title <text> --url <url> [--asset <dragged-file>]");
+  requireNoExtraArgs(pending, "rig report-bug [--no-prompt] [--no-beads] [--browser|--no-browser] --title <text> --url <url> [--asset <dragged-file>]");
   let draft = {
     outputRoot: outputRootResult.value || "",
     title: titleResult.value,
@@ -428,7 +624,7 @@ async function executeTaskReportBug(context, args) {
   const shouldPrompt = !noPromptFlag.value;
   if (shouldPrompt) {
     if (context.outputMode !== "text" || !process.stdin.isTTY || !process.stdout.isTTY) {
-      throw new CliError2("Interactive bug reporting requires a TTY in text mode. Pass --no-prompt with flags for automation.");
+      throw new CliError("Interactive bug reporting requires a TTY in text mode. Pass --no-prompt with flags for automation.");
     }
     draft = await promptForBugReportDetails(draft);
   }
@@ -501,7 +697,7 @@ async function executeTaskReportBug(context, args) {
     console.log(`Evidence assets: ${result.assetDir}`);
     if (taskConfigPath) {
       console.log(`Task config: ${taskConfigPath}`);
-      console.log(`Run: bun run rig task info --task ${issueId}`);
+      console.log(`Run: rig task info --task ${issueId}`);
     }
   }
   return {
@@ -532,7 +728,7 @@ function validateBugReportInputFiles(input) {
   for (const { path, label } of files.map((item) => ({ ...item, path: item.path.trim() })).filter((item) => item.path)) {
     const source = resolve3(input.projectRoot, path);
     if (!existsSync2(source)) {
-      throw new CliError2(`${label} does not exist: ${source}`);
+      throw new CliError(`${label} does not exist: ${source}`, 1, { hint: "Check the path and re-run `rig task report-bug` with an existing file." });
     }
   }
 }
@@ -572,7 +768,7 @@ function createBugReportBeadsTask(monorepoRoot, input, draft) {
   const issue = tryRunBrJson(monorepoRoot, command);
   if (!issue.ok) {
     if (!isRecoverableBeadsJsonlFailure(issue.error)) {
-      throw new CliError2(issue.error);
+      throw new CliError(issue.error);
     }
     return {
       issueId: generateBugReportIssueId(monorepoRoot, input.title),
@@ -583,7 +779,7 @@ function createBugReportBeadsTask(monorepoRoot, input, draft) {
   }
   const issueId = issue.value.id?.trim();
   if (!issueId) {
-    throw new CliError2("br create did not return an issue id.");
+    throw new CliError("br create did not return an issue id.", 1, { hint: "Re-run `rig task report-bug`; if it persists, file the bug via your task source directly." });
   }
   return {
     issueId,
@@ -690,12 +886,12 @@ ${serializedEntry}
   }
   const insertAt = raw.lastIndexOf("}");
   if (insertAt < 0) {
-    throw new CliError2(`Invalid task config JSON object: ${taskConfigPath}`);
+    throw new CliError(`Invalid task config JSON object: ${taskConfigPath}`, 1, { hint: "Fix or reset that file (it must be a JSON object), then re-run `rig task report-bug`." });
   }
   const before = raw.slice(0, insertAt).replace(/\s*$/, "");
   const after = raw.slice(insertAt + 1).trim();
   if (after) {
-    throw new CliError2(`Invalid trailing content in task config: ${taskConfigPath}`);
+    throw new CliError(`Invalid trailing content in task config: ${taskConfigPath}`, 1, { hint: "Remove the trailing content so the file is a single JSON object, then retry." });
   }
   const comma = before.trim() === "{" ? "" : ",";
   writeFileSync2(taskConfigPath, `${before}${comma}
@@ -763,7 +959,7 @@ function generateBugReportIssueId(monorepoRoot, title) {
       return id;
     }
   }
-  throw new CliError2("Could not generate a unique bug task id.");
+  throw new CliError("Could not generate a unique bug task id.", 1, { hint: "Re-run `rig task report-bug`; pass an explicit title to vary the generated id." });
 }
 function isRecoverableBeadsJsonlFailure(message) {
   return /Invalid JSON|missing field|JSONL is newer than DB|stale database/i.test(message);
@@ -771,7 +967,7 @@ function isRecoverableBeadsJsonlFailure(message) {
 function runBrJson(cwd, command) {
   const result = tryRunBrJson(cwd, command);
   if (!result.ok) {
-    throw new CliError2(result.error);
+    throw new CliError(result.error);
   }
   return result.value;
 }
@@ -797,14 +993,14 @@ ${result.stdout.trim() || String(error)}`
   }
 }
 async function promptForBugReportDetails(initial) {
-  clack.intro("rig report-bug");
-  clack.note([
+  droneIntro("rig report-bug");
+  droneNote([
     "Creates an agent-ready issue with copied evidence files.",
     "When prompted for assets, drag screenshots/videos into the terminal and press Enter."
   ].join(`
 `), "Bug report wizard");
-  clack.log.step("1/5 Incident");
-  clack.note(bugPromptExampleText("incident"), "Input examples");
+  droneStep("1/5 Incident");
+  droneNote(bugPromptExampleText("incident"), "Input examples");
   const title = await promptBugText("Bug title", initial.title, {
     required: true,
     placeholder: "Login page never leaves loading"
@@ -825,8 +1021,8 @@ async function promptForBugReportDetails(initial) {
   const summary = await promptBugText("Short summary", initial.summary, {
     placeholder: "Email field never appears after navigating from credentials."
   });
-  clack.log.step("2/5 Reproduction");
-  clack.note(bugPromptExampleText("reproduction"), "Input examples");
+  droneStep("2/5 Reproduction");
+  droneNote(bugPromptExampleText("reproduction"), "Input examples");
   const steps = splitPromptList(await promptBugText("Repro steps (semicolon-separated)", initial.steps.join("; "), {
     placeholder: "Open /login; Enter qa@example.com; Press Continue"
   }));
@@ -836,14 +1032,14 @@ async function promptForBugReportDetails(initial) {
   const actual = await promptBugText("Actual behavior", initial.actual, {
     placeholder: "Loading shell stays forever."
   });
-  clack.log.step("3/5 Evidence");
-  clack.note(bugPromptExampleText("evidence"), "Input examples");
+  droneStep("3/5 Evidence");
+  droneNote(bugPromptExampleText("evidence"), "Input examples");
   const evidence = splitPromptList(await promptBugText("Evidence notes (console/network/API; semicolon-separated)", initial.evidence.join("; "), {
     placeholder: "Console: ChunkLoadError for credentials route; Network: /assets/app.js 404"
   }));
   const assets = splitDroppedAssetList(await promptBugText("Drag screenshots/videos here (Enter to skip)", initial.assets.map(formatDroppedAssetDefault).join(" "), { placeholder: "/Users/me/Desktop/login-loading.png /Users/me/Desktop/otp-flow.webm" }));
-  clack.log.step("4/5 Routing");
-  clack.note(bugPromptExampleText("routing"), "Input examples");
+  droneStep("4/5 Routing");
+  droneNote(bugPromptExampleText("routing"), "Input examples");
   const priority = await promptBugSelect("Priority", [
     { value: "P0", label: "P0", hint: "urgent / blocking" },
     { value: "P1", label: "P1", hint: "high" },
@@ -857,13 +1053,13 @@ async function promptForBugReportDetails(initial) {
   const parent = await promptBugText("Parent task or epic id (optional)", initial.parent, {
     placeholder: "bd-auth-epic-123"
   });
-  clack.log.step("5/5 Browser");
-  clack.note(bugPromptExampleText("browser"), "Input examples");
+  droneStep("5/5 Browser");
+  droneNote(bugPromptExampleText("browser"), "Input examples");
   const browserRequired = await promptBugConfirm("Does this task need Rig Browser wiring?", initial.browserRequired);
   let viewport = initial.viewport || "1440x900";
   let profile = initial.profile;
   if (browserRequired) {
-    clack.note([
+    droneNote([
       "A profile is the browser state bucket: cookies, localStorage, auth session, and cache.",
       "Use a bug-specific profile for clean login/OTP runs; use a shared profile only when saved auth matters."
     ].join(`
@@ -871,11 +1067,11 @@ async function promptForBugReportDetails(initial) {
     viewport = await promptBugText("Viewport", viewport, { placeholder: "1440x900" });
     profile = await promptBugText("Rig Browser profile", initial.profile || (title ? defaultBrowserBugProfile(title) : undefined), { placeholder: "hp-next-login-loading-clean" });
   } else {
-    clack.log.info("Browser wiring skipped. The task will keep assets and steps, but no browser block or browser validation.");
+    droneInfo("Browser wiring skipped. The task will keep assets and steps, but no browser block or browser validation.");
   }
   const outputRoot = initial.createBeadsTask ? initial.outputRoot : await promptBugText("Output directory", initial.outputRoot || "docs/bug-reports");
   const overwrite = await promptBugConfirm("Overwrite if report exists?", initial.overwrite);
-  clack.outro("Bug report input captured.");
+  droneOutro("Bug report input captured.");
   return {
     ...initial,
     outputRoot,
@@ -902,13 +1098,21 @@ async function promptForBugReportDetails(initial) {
   };
 }
 async function promptBugText(message, defaultValue, options = {}) {
-  const result = await clack.text({
-    message,
-    defaultValue: defaultValue?.trim() ? defaultValue : undefined,
-    placeholder: options.placeholder,
-    validate: options.required ? (value) => validateRequiredBugPromptValue(value, message) : undefined
-  });
-  return unwrapClackPrompt(result).trim();
+  for (;; ) {
+    const result = await droneText({
+      message,
+      ...options.placeholder ? { placeholder: options.placeholder } : {},
+      ...defaultValue?.trim() ? { initialValue: defaultValue } : {}
+    });
+    if (result === null) {
+      droneCancel("Bug report cancelled.");
+      throw new CliError("Bug report cancelled by user.");
+    }
+    const invalid = options.required ? validateRequiredBugPromptValue(result, message) : undefined;
+    if (!invalid)
+      return result.trim();
+    droneInfo(invalid);
+  }
 }
 function validateRequiredBugPromptValue(value, label) {
   return value?.trim() ? undefined : `${label} is required.`;
@@ -917,7 +1121,7 @@ function bugPromptExampleText(section, options = {}) {
   const c = pc.createColors(options.color ?? shouldColorizeCliOutput());
   const label = (value) => c.bold(c.cyan(value));
   const example = (value) => c.green(value);
-  const note2 = (value) => c.dim(value);
+  const note = (value) => c.dim(value);
   const rows = {
     incident: [
       ["Bug title", "Login page never leaves loading", "short user-visible failure"],
@@ -946,30 +1150,24 @@ function bugPromptExampleText(section, options = {}) {
     ]
   };
   return rows[section].map(([name, value, detail]) => {
-    const suffix = detail ? ` ${note2(`(${detail})`)}` : "";
+    const suffix = detail ? ` ${note(`(${detail})`)}` : "";
     return `${label(name)}: ${example(value)}${suffix}`;
   }).join(`
 `);
 }
 async function promptBugConfirm(message, initialValue) {
-  const result = await clack.confirm({
-    message,
-    initialValue
-  });
-  return unwrapClackPrompt(result);
+  const result = await droneConfirm({ message, initialValue });
+  if (result === null) {
+    droneCancel("Bug report cancelled.");
+    throw new CliError("Bug report cancelled by user.");
+  }
+  return result;
 }
 async function promptBugSelect(message, options, initialValue) {
-  const result = await clack.select({
-    message,
-    options,
-    initialValue
-  });
-  return unwrapClackPrompt(result);
-}
-function unwrapClackPrompt(result) {
-  if (clack.isCancel(result)) {
-    clack.cancel("Bug report cancelled.");
-    throw new CliError2("Bug report cancelled by user.");
+  const result = await droneSelect({ message, options, initialValue });
+  if (result === null) {
+    droneCancel("Bug report cancelled.");
+    throw new CliError("Bug report cancelled by user.");
   }
   return result;
 }
@@ -979,7 +1177,7 @@ function normalizeBugEnvironmentChoice(environment) {
 function requireReportBugValue(value, option) {
   const normalized = value?.trim();
   if (!normalized) {
-    throw new CliError2(`Missing ${option}. Run interactively or pass ${option} <value>.`);
+    throw new CliError(`Missing ${option}. Run interactively or pass ${option} <value>.`);
   }
   return normalized;
 }
@@ -1060,7 +1258,7 @@ function takeRepeatedOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError2(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       values.push(next);
       index += 1;

package/dist/src/commands/task-run-driver.d.ts

@@ -0,0 +1,132 @@
+import { type RunnerContext } from "../runner";
+import { updateConfiguredTaskSourceTask } from "@rig/runtime/control-plane/tasks/source-lifecycle";
+import { runPrAutomation, type GitCommandRunner, type GitHubCommandRunner, type PrAutomationResult, type RigAutomationConfig } from "@rig/runtime/control-plane/native/pr-automation";
+import { type SourceTaskContract } from "./_run-driver-helpers";
+export type TaskRunReviewState = {
+    approved?: boolean;
+    provider?: string;
+    mode?: string;
+    verdict?: string;
+    local_reasons?: string[];
+    ai_reasons?: string[];
+    ai_warnings?: string[];
+};
+declare const PI_CANONICAL_RUN_STAGES: readonly ["Connect", "GitHub/task sync", "Prepare workspace", "Launch Pi", "Plan", "Implement", "Validate", "Commit", "Open PR", "Review/CI", "Merge", "Complete"];
+export declare function canonicalPiRunStages(): string[];
+export declare function buildPiRigBridgeEnv(input: {
+    readonly projectRoot: string;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly serverUrl?: string | null;
+    readonly authToken?: string | null;
+    readonly githubToken?: string | null;
+}): Record<string, string>;
+export declare function applyDirtyBaselineSnapshot(input: {
+    readonly sourceRoot: string;
+    readonly targetRoot: string;
+}): {
+    applied: boolean;
+    copiedUntracked: number;
+    detail: string;
+};
+export declare function buildTaskRunReviewEnv(config?: TaskRunAutomationConfig | null): Record<string, string>;
+export declare function buildDirtyBaselineHandshakeEnv(input: {
+    readonly projectRoot: string;
+    readonly runId: string;
+    readonly baselineMode?: "head" | "dirty-snapshot";
+}): Record<string, string>;
+type TaskRunAutomationConfig = RigAutomationConfig & {
+    readonly github?: {
+        readonly issueUpdates?: "lifecycle" | "minimal" | "off";
+    };
+    readonly planning?: {
+        readonly mode?: "auto" | "always" | "off";
+        readonly requireForLabels?: readonly string[];
+        readonly skipForLabels?: readonly string[];
+    };
+};
+export declare function resolveTaskRunAutomationLimits(config?: TaskRunAutomationConfig | null, env?: Record<string, string | undefined>): {
+    maxValidationAttempts: number;
+    maxPrFixIterations: number;
+};
+export type PlanningClassification = {
+    readonly planningRequired: boolean;
+    readonly size: "small" | "medium" | "large";
+    readonly risk: "low" | "medium" | "high";
+    readonly reason: string;
+    readonly policy: "always" | "off" | "auto";
+};
+export declare function classifyPlanningNeed(input: {
+    readonly config?: TaskRunAutomationConfig | null;
+    readonly sourceTask?: SourceTaskContract | null;
+}): PlanningClassification;
+export declare function buildPiValidationRetrySteeringPrompt(input: {
+    taskId: string;
+    attempt: number;
+    maxAttempts: number;
+    failureDetail: string;
+    validationOutput?: string | null;
+}): string;
+export declare function classifyValidationRetryOutcome(input: {
+    attempt: number;
+    maxAttempts: number;
+    failureDetail: string;
+}): {
+    stage: "Validate failed";
+    status: "retry" | "needs_attention";
+    failureDetail: string;
+};
+export type TaskRunStageName = typeof PI_CANONICAL_RUN_STAGES[number] | "Needs attention" | "Failed";
+export declare function taskRunStageLogId(runId: string, stage: TaskRunStageName): string;
+export type TaskRunPostValidationLifecycleResult = {
+    readonly status: "completed" | "skipped" | "needs_attention";
+    readonly pr?: PrAutomationResult;
+};
+export declare function runTaskRunPostValidationLifecycle(input: {
+    readonly projectRoot: string;
+    readonly runId: string;
+    readonly taskId?: string;
+    readonly runtimeTaskId: string;
+    readonly runtimeWorkspace?: string | null;
+    readonly branch?: string | null;
+    readonly config?: TaskRunAutomationConfig | null;
+    readonly sourceTask: SourceTaskContract | null;
+    readonly uploadedSnapshot?: boolean;
+    readonly appendStage?: (stage: TaskRunStageName, detail?: string | null, status?: string, tone?: "info" | "tool" | "error") => void;
+    readonly ghCommand?: GitHubCommandRunner;
+    readonly gitCommand?: GitCommandRunner;
+    readonly prAutomation?: typeof runPrAutomation;
+    readonly steerPi?: (message: string) => Promise<void>;
+    readonly updateTaskSource?: typeof updateConfiguredTaskSourceTask;
+}): Promise<TaskRunPostValidationLifecycleResult>;
+export declare function classifyCompletionVerificationLine(line: string): {
+    isCompletionLine: boolean;
+    isVerifierReview: boolean;
+};
+export declare function createRunLogIdFactory(runId: string): () => string;
+export declare function summarizeTaskRunProcessFailure(input: {
+    exitCode: number | null;
+    signal: string | null;
+    stderrLines?: readonly string[];
+}): string;
+export declare function readTaskRunAcceptedArtifactState(input: {
+    taskId: string | null;
+    workspaceDir: string | null;
+    artifactNotBeforeMs?: number;
+}): {
+    accepted: boolean;
+    reason: string | null;
+};
+export declare function executeRigOwnedTaskRun(context: RunnerContext, input: {
+    runId: string;
+    taskId?: string;
+    title?: string;
+    runtimeAdapter: "claude-code" | "codex" | "pi";
+    model?: string;
+    runtimeMode: string;
+    interactionMode: string;
+    initialPrompt?: string;
+    baselineMode?: "head" | "dirty-snapshot";
+    prMode?: "auto" | "ask" | "off";
+}): Promise<void>;
+export {};