@h-rig/cli 0.0.6-alpha.27 → 0.0.6-alpha.29

package/dist/src/commands/task.js

@@ -9,8 +9,6 @@ import { cancel as cancel2, confirm, isCancel as isCancel2 } from "@clack/prompt
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
 import { CliError } 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";
 function takeFlag(args, flag) {
@@ -182,7 +180,7 @@ function resolveSelectedConnection(projectRoot, options = {}) {
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig connection "${repo.selected}" was not found. Run \`rig connect list\` or \`rig connect use local\`.`, 1);
+    throw new CliError2(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
   }
   return { alias: repo.selected, connection };
 }
@@ -562,7 +560,7 @@ async function runFastTaskRunPreflight(context, options = {}) {
     }
   }
   const repo = readRepoConnection(context.projectRoot);
-  checks.push(repo ? preflightCheck("project-link", "project linked to Rig connection", repo.project ? "pass" : "warn", `${repo.selected}${repo.project ? ` -> ${repo.project}` : ""}`, "Run `rig init --yes --repo owner/repo` to record the GitHub repo slug.") : preflightCheck("project-link", "project linked to Rig connection", legacyServerCompatibility ? "warn" : "fail", "missing .rig/state/connection.json", "Run `rig init` or `rig connect use <alias|local>`."));
+  checks.push(repo ? preflightCheck("project-link", "project linked to Rig server", repo.project ? "pass" : "warn", `${repo.selected}${repo.project ? ` -> ${repo.project}` : ""}`, "Run `rig init --yes --repo owner/repo` to record the GitHub repo slug.") : preflightCheck("project-link", "project linked to Rig server", legacyServerCompatibility ? "warn" : "fail", "missing .rig/state/connection.json", "Run `rig init` or `rig server use <alias|local>`."));
   try {
     const auth = await request("/api/github/auth/status");
     checks.push(isAuthenticated(auth) ? preflightCheck("github-auth", "GitHub auth valid", "pass") : preflightCheck("github-auth", "GitHub auth valid", legacyServerCompatibility ? "warn" : "fail", "not authenticated", "Run `rig github auth import-gh` or `rig github auth token --token <token>`."));
@@ -1622,11 +1620,16 @@ async function attachRunOperatorView(context, input) {
 }
 
 // packages/cli/src/commands/_cli-format.ts
+import { log, note } from "@clack/prompts";
 import pc from "picocolors";
 function stringField(record, key, fallback = "") {
   const value = record[key];
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
+function numberField(record, key) {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
 function arrayField(record, key) {
   const value = record[key];
   return Array.isArray(value) ? value.flatMap((entry) => typeof entry === "string" && entry.trim() ? [entry.trim()] : []) : [];
@@ -1647,16 +1650,40 @@ function pad(value, width) {
 }
 function statusColor(status) {
   const normalized = status.toLowerCase();
-  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected"].includes(normalized))
+  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected", "approved"].includes(normalized))
     return pc.green;
-  if (["failed", "needs_attention", "needs-attention", "blocked", "error"].includes(normalized))
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error", "rejected"].includes(normalized))
     return pc.red;
   if (["running", "reviewing", "validating", "in_progress", "in-progress", "remote"].includes(normalized))
     return pc.cyan;
-  if (["ready", "open", "queued", "created", "preparing", "local"].includes(normalized))
+  if (["ready", "open", "queued", "created", "preparing", "local", "pending"].includes(normalized))
     return pc.yellow;
   return pc.dim;
 }
+function compactValue(value) {
+  if (value === null || value === undefined)
+    return "";
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (Array.isArray(value))
+    return value.map(compactValue).filter(Boolean).join(", ");
+  return JSON.stringify(value);
+}
+function shouldUseClackOutput() {
+  return Boolean(process.stdout.isTTY) && process.env.RIG_CLI_PLAIN_HELP !== "1";
+}
+function printFormattedOutput(message2, options = {}) {
+  if (!shouldUseClackOutput()) {
+    console.log(message2);
+    return;
+  }
+  if (options.title)
+    note(message2, options.title);
+  else
+    log.message(message2);
+}
 function formatStatusPill(status) {
   const label = status || "unknown";
   return statusColor(label)(`\u25CF ${label}`);
@@ -1665,7 +1692,7 @@ function formatSection(title, subtitle) {
   return `${pc.bold(pc.cyan("\u25C6"))} ${pc.bold(title)}${subtitle ? pc.dim(` \u2014 ${subtitle}`) : ""}`;
 }
 function formatSuccessCard(title, rows = []) {
-  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${pc.dim("\u2502")} ${pc.dim(key.padEnd(9))} ${value}`);
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${pc.dim("\u2502")} ${pc.dim(key.padEnd(12))} ${value}`);
   return [formatSection(title), ...body].join(`
 `);
 }
@@ -1705,6 +1732,40 @@ function formatTaskList(tasks, options = {}) {
   return [formatSection("Tasks", `${rows.length} shown`), header, ...body, "", ...formatNextSteps(["Run one: `rig task run <id>` or `rig task run --next`", "Attach later: `rig run attach <run-id> --follow`"])].join(`
 `);
 }
+function formatTaskCard(task, options = {}) {
+  const raw = rawObject(task);
+  const id = stringField(task, "id", stringField(raw, "id", "<unknown>"));
+  const status = stringField(task, "status", stringField(raw, "status", "unknown"));
+  const title = stringField(task, "title", stringField(raw, "title", "Untitled task"));
+  const source = stringField(task, "source", stringField(raw, "source", ""));
+  const url = stringField(task, "url", stringField(raw, "url", ""));
+  const number = numberField(task, "number") ?? numberField(raw, "number");
+  const labels = arrayField(task, "labels").length > 0 ? arrayField(task, "labels") : arrayField(raw, "labels");
+  const assignees = arrayField(task, "assignees").length > 0 ? arrayField(task, "assignees") : arrayField(raw, "assignees");
+  const readiness = compactValue(task.readiness ?? raw.readiness);
+  const validators = compactValue(task.validators ?? raw.validators ?? task.validation ?? raw.validation);
+  const rows = [
+    ["task", pc.bold(id)],
+    ["status", formatStatusPill(status)],
+    ["title", title],
+    ["source", source],
+    ["number", number],
+    ["labels", labels.length ? labels.map((label) => `#${label}`).join(" ") : ""],
+    ["assignees", assignees.join(", ")],
+    ["readiness", readiness],
+    ["validators", validators],
+    ["url", url]
+  ];
+  return [
+    formatSuccessCard(options.title ?? (options.selected ? "Selected task" : "Task"), rows),
+    "",
+    ...formatNextSteps([`Start: \`rig task run ${id}\``, `Details: \`rig task show ${id} --raw\``])
+  ].join(`
+`);
+}
+function formatTaskDetails(task) {
+  return formatTaskCard(task, { title: "Task details" });
+}
 function formatSubmittedRun(input) {
   const rows = [["run", pc.bold(input.runId)]];
   if (input.task) {
@@ -1713,14 +1774,361 @@ function formatSubmittedRun(input) {
     const title = stringField(input.task, "title", "Untitled task");
     rows.push(["task", `${pc.bold(id)} ${formatStatusPill(status)} ${title}`]);
   }
+  const runtime = [input.runtimeAdapter || "pi", input.runtimeMode || "full-access", input.interactionMode || "default"].filter(Boolean).join(" \xB7 ");
+  rows.push(["runtime", runtime]);
   return [
     formatSuccessCard("Run submitted", rows),
     "",
-    ...formatNextSteps([`Attach: \`rig run attach ${input.runId} --follow\``, `Inspect: \`rig run show --run ${input.runId}\``])
+    ...formatNextSteps([
+      `Attach: \`rig run attach ${input.runId} --follow\``,
+      `Inspect: \`rig run show ${input.runId}\``,
+      input.detached ? "Submitted detached; attach when you are ready." : "Interactive mode opens the native bundled Pi frontend."
+    ])
   ].join(`
 `);
 }
 
+// packages/cli/src/commands/_help-catalog.ts
+import { intro, log as log2, note as note2, outro } from "@clack/prompts";
+import pc2 from "picocolors";
+var TOP_LEVEL_SECTIONS = [
+  {
+    title: "Server",
+    subtitle: "choose the local or remote Rig server that owns this repo",
+    commands: [
+      { command: "rig server status", description: "Show the selected local/remote server for this repo." },
+      { command: "rig server use local", description: "Switch this repo back to the local Rig server." },
+      { command: "rig server add <alias> <url>", description: "Save a remote Rig server alias." },
+      { command: "rig server use <alias>", description: "Switch this repo to a saved remote server." },
+      { command: "rig server list", description: "Show saved server aliases, including local." }
+    ]
+  },
+  {
+    title: "Tasks",
+    subtitle: "find work, inspect it, and submit Pi-backed workers",
+    commands: [
+      { command: "rig task list", description: "List tasks from the selected task source/server." },
+      { command: "rig task next", description: "Show the next matching task as a selected-task card." },
+      { command: "rig task show <id>", description: "Show a human task summary; add --raw or --json for the full payload." },
+      { command: "rig task run <id|--next> [--detach]", description: "Submit a task run; interactive mode follows with bundled Pi." }
+    ]
+  },
+  {
+    title: "Runs",
+    subtitle: "observe, attach to, and stop live or recent runs",
+    commands: [
+      { command: "rig run list", description: "List recent runs from the selected server or local state." },
+      { command: "rig run show <id>", description: "Show a human run summary; add --raw or --json for the full payload." },
+      { command: "rig run attach <id> --follow", description: "Open the native bundled Pi live view for a worker run." },
+      { command: "rig run stop <id>", description: "Request cancellation for a running worker." }
+    ]
+  },
+  {
+    title: "Review / inbox",
+    subtitle: "clear blocked runs and configure completion review",
+    commands: [
+      { command: "rig inbox approvals", description: "List pending approval requests from local/server run state." },
+      { command: "rig inbox inputs", description: "List pending user-input requests from local/server run state." },
+      { command: "rig review show|set", description: "Inspect or change the review gate policy." }
+    ]
+  },
+  {
+    title: "Health / setup",
+    subtitle: "bootstrap and diagnose the repo/server/GitHub/Pi path",
+    commands: [
+      { command: "rig init", description: "Interactive setup: config, GitHub auth, task source, server, checkout, Pi." },
+      { command: "rig doctor", description: "Diagnose project/server/GitHub/task/Pi wiring." },
+      { command: "rig github auth status", description: "Show GitHub auth state on the selected Rig server." }
+    ]
+  }
+];
+var PRIMARY_GROUPS = [
+  {
+    name: "server",
+    summary: "Choose, inspect, and start the Rig server that owns tasks and runs.",
+    usage: ["rig server <status|list|add|use|start> [options]"],
+    commands: [
+      { command: "status", description: "Show the selected server for this repo.", primary: true },
+      { command: "use local", description: "Switch this repo to the local Rig server.", primary: true },
+      { command: "add <alias> <url>", description: "Save a remote Rig server URL.", primary: true },
+      { command: "use <alias>", description: "Select a saved remote server alias.", primary: true },
+      { command: "list", description: "List saved local/remote server aliases.", primary: true },
+      { command: "start [--host <host>] [--port <n>]", description: "Start a local rig-server process." }
+    ],
+    examples: [
+      "rig server status",
+      "rig server add prod https://where.rig-does.work",
+      "rig server use prod",
+      "rig server use local",
+      "rig server start --port 3773"
+    ],
+    next: ["Use `rig task list` to see server-owned work.", "Use `rig run list` or `rig run attach <id> --follow` to monitor runs."],
+    advanced: ["Compatibility alias: `rig connect ...` remains callable."]
+  },
+  {
+    name: "task",
+    summary: "Find work, start Pi-backed runs, and validate task results.",
+    usage: ["rig task <list|next|show|run> [options]"],
+    commands: [
+      { command: "list [--assignee <login|@me>] [--state open|closed]", description: "List tasks from the selected server/source.", primary: true },
+      { command: "next [filters]", description: "Render the next matching task as a selected-task card.", primary: true },
+      { command: "show <id>|--task <id> [--raw]", description: "Show a human task summary; --raw prints the full payload.", primary: true },
+      { command: "run [#<issue>|<task-id>|--next|--task <id>]", description: "Submit a task run; interactive follows with bundled Pi.", primary: true },
+      { command: "validate|verify [--task <id>]", description: "Run configured task checks/review gates." },
+      { command: "details --task <id>", description: "Show full task info from the configured source." },
+      { command: "reopen [--task <id> | --all] [--reason <text>]", description: "Reopen closed task(s) in the configured source." },
+      { command: "reset --task <id>", description: "Compatibility spelling of `reopen --task <id>`." },
+      { command: "artifacts|artifact-dir|artifact-write", description: "Inspect or write task artifacts." },
+      { command: "report-bug", description: "Create a structured bug report/task." }
+    ],
+    examples: [
+      "rig task list --assignee @me --limit 20",
+      "rig task next",
+      "rig task show 123 --raw",
+      "rig task run --next",
+      "rig task run #123 --runtime-adapter pi",
+      "rig task run --title 'Investigate deploy drift' --initial-prompt 'Check server health'"
+    ],
+    next: ["Use `--detach` to submit without attaching.", "Use `rig run attach <run-id> --follow` to rejoin a live run."]
+  },
+  {
+    name: "run",
+    summary: "Observe, attach to, and control Rig runs.",
+    usage: ["rig run <list|status|show|attach|stop> [options]"],
+    commands: [
+      { command: "list", description: "List recent runs from the selected server or local state.", primary: true },
+      { command: "status", description: "Render active and recent run groups.", primary: true },
+      { command: "show <id>|--run <id> [--raw]", description: "Show a human run summary; --raw prints the full payload.", primary: true },
+      { command: "attach <run-id>|--run <id> [--follow]", description: "Attach to the run; --follow launches native bundled Pi for live Pi runs.", primary: true },
+      { command: "stop [<run-id>|--run <id>]", description: "Request stop for one run or local active runs.", primary: true },
+      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events." },
+      { command: "resume", description: "Resume the most recent interrupted local run." },
+      { command: "restart", description: "Restart the most recent local run from a clean runtime." },
+      { command: "delete|cleanup", description: "Remove completed run records/artifacts." }
+    ],
+    examples: [
+      "rig run list",
+      "rig run status",
+      "rig run show <run-id>",
+      "rig run attach <run-id> --follow",
+      "rig run stop <run-id>"
+    ],
+    next: ["Use `rig task run --next` to create a new run.", "Use `--json` when scripts need the full structured record."]
+  },
+  {
+    name: "inbox",
+    summary: "Review approval and user-input requests that block worker runs.",
+    usage: ["rig inbox <approvals|approve|inputs|respond> [options]"],
+    commands: [
+      { command: "approvals [--run <id>] [--task <id>]", description: "List pending approvals.", primary: true },
+      { command: "inputs [--run <id>] [--task <id>]", description: "List pending user-input requests.", primary: true },
+      { command: "approve --run <id> --request <id> --decision approve|reject", description: "Resolve an approval request." },
+      { command: "respond --run <id> --request <id> --answer key=value", description: "Answer a user-input request." }
+    ],
+    examples: [
+      "rig inbox approvals",
+      "rig inbox inputs --run <run-id>",
+      "rig inbox approve --run <run-id> --request <request-id> --decision approve"
+    ],
+    next: ["Rejoin the run after resolving a block: `rig run attach <run-id> --follow`."]
+  },
+  {
+    name: "review",
+    summary: "Inspect or change completion review gate policy.",
+    usage: ["rig review <show|set>"],
+    commands: [
+      { command: "show", description: "Show current review gate settings.", primary: true },
+      { command: "set <off|advisory|required> [--provider greptile]", description: "Change review strictness/provider.", primary: true }
+    ],
+    examples: ["rig review show", "rig review set required --provider greptile"],
+    next: ["Use `rig inbox approvals` for blocked run handoffs."]
+  },
+  {
+    name: "init",
+    summary: "Set up Rig for this repo: server, GitHub auth, checkout strategy, task source, and Pi wiring.",
+    usage: ["rig init [--yes] [--server local|remote] [--repo owner/repo] [--remote-url <url>]"],
+    commands: [
+      { command: "init", description: "Interactive setup wizard for a new or existing Rig repo.", primary: true },
+      { command: "init --yes", description: "Non-interactive setup using detected/default settings.", primary: true },
+      { command: "init --server remote --remote-url <url>", description: "Link this repo to a remote Rig server.", primary: true },
+      { command: "init --repair", description: "Repair missing private state without replacing project config." }
+    ],
+    examples: [
+      "rig init",
+      "rig init --yes --repo humanity-org/humanwork",
+      "rig init --server remote --remote-url https://where.rig-does.work --repo owner/repo"
+    ],
+    next: ["After init, run `rig server status`.", "Then use `rig task list` and `rig task run --next` for day-to-day work."]
+  },
+  {
+    name: "doctor",
+    summary: "Diagnostics for project/server/GitHub/Pi state.",
+    usage: ["rig doctor"],
+    commands: [
+      { command: "doctor", description: "Run setup and runtime diagnostics.", primary: true },
+      { command: "check", description: "Compatibility spelling for diagnostics." }
+    ],
+    examples: ["rig doctor", "rig doctor --json"],
+    next: ["Use `rig server status` and `rig github auth status` to inspect common failure points."]
+  },
+  {
+    name: "github",
+    summary: "GitHub auth helpers for the selected Rig server.",
+    usage: ["rig github auth <status|import-gh|token>"],
+    commands: [
+      { command: "auth status", description: "Show GitHub auth state.", primary: true },
+      { command: "auth import-gh", description: "Import the current `gh` token into the selected server." },
+      { command: "auth token --token <token>", description: "Store a token on the selected server." }
+    ],
+    examples: ["rig github auth status", "rig github auth import-gh"],
+    next: ["After auth is valid, use `rig task run --next`."]
+  }
+];
+var ADVANCED_GROUPS = [
+  { name: "connect", summary: "Compatibility alias for `rig server` selection commands.", usage: ["rig connect <status|list|add|use>"], commands: [{ command: "status|list|add|use", description: "Use `rig server ...` for the primary UX." }] },
+  { name: "setup", summary: "Bootstrap/check local setup.", usage: ["rig setup <bootstrap|check|preflight>"], commands: [{ command: "bootstrap|check|preflight", description: "Setup helpers." }] },
+  { name: "inspect", summary: "Inspect logs, artifacts, graphs, failures.", usage: ["rig inspect <logs|artifacts|failures|graph|audit|diff>"], commands: [{ command: "logs --task <id>", description: "Inspect task logs." }] },
+  { name: "repo", summary: "Repository sync/baseline helpers.", usage: ["rig repo <sync|reset-baseline>"], commands: [{ command: "sync", description: "Sync project repository state." }] },
+  { name: "profile", summary: "Runtime profile/model defaults.", usage: ["rig profile <show|set>"], commands: [{ command: "show", description: "Show active profile." }] },
+  {
+    name: "browser",
+    summary: "Browser/app diagnostics for browser-required tasks.",
+    usage: ["rig browser <help|explain|demo|app|hp-next> [options]"],
+    commands: [
+      { command: "help", description: "Rich browser command help (canonical: `rig browser help`)." },
+      { command: "explain", description: "Explain the browser-required task contract." },
+      { command: "demo", description: "Run browser demo flows against a local page." },
+      { command: "app", description: "Launch the Rig Browser workstation app." },
+      { command: "hp-next <dev|check|e2e|reset>", description: "Drive the hp-next browser test harness." }
+    ]
+  },
+  {
+    name: "plugin",
+    summary: "Plugin listing, validation, and plugin-contributed commands.",
+    usage: ["rig plugin <list|validate|run> [options]"],
+    commands: [
+      { command: "list", description: "List plugins declared in rig.config.ts and their contributions." },
+      { command: "validate --task <id>", description: "Run plugin-contributed validators for a task." },
+      { command: "run <command-id> [args...]", description: "Execute a plugin-contributed CLI command (also callable as `rig <command-id>`)." }
+    ]
+  },
+  { name: "queue", summary: "Run task queues locally.", usage: ["rig queue run [options]"], commands: [{ command: "run", description: "Process queue work." }] },
+  { name: "agent", summary: "Runtime agent workspace helpers.", usage: ["rig agent <list|prepare|run|cleanup>"], commands: [{ command: "list", description: "List prepared agents." }] },
+  { name: "inspector", summary: "Event stream and drift scanners.", usage: ["rig inspector <stream|scan-upstream-drift>"], commands: [{ command: "stream", description: "Stream events." }] },
+  { name: "dist", summary: "Build/install packaged Rig CLI.", usage: ["rig dist <build|install|doctor>"], commands: [{ command: "build", description: "Build distribution." }] },
+  { name: "workspace", summary: "Workspace topology/service helpers.", usage: ["rig workspace <summary|topology|remote-hosts>"], commands: [{ command: "summary", description: "Show workspace summary." }] },
+  { name: "remote", summary: "Compatibility remote orchestration controls.", usage: ["rig remote <status|watch|pause|resume|...>"], commands: [{ command: "status", description: "Show remote state." }] },
+  { name: "git", summary: "Pass through to Rig git-flow helper.", usage: ["rig git <args...>"], commands: [{ command: "<args...>", description: "Advanced git flow operations." }] },
+  { name: "harness", summary: "Pass through to runtime harness CLI.", usage: ["rig harness <args...>"], commands: [{ command: "<args...>", description: "Advanced harness operations." }] },
+  { name: "test", summary: "Project test wrappers.", usage: ["rig test <unit|e2e|all>"], commands: [{ command: "all", description: "Run configured project tests." }] }
+];
+var ALL_GROUPS = [...PRIMARY_GROUPS, ...ADVANCED_GROUPS];
+function heading(title) {
+  return pc2.bold(pc2.cyan(title));
+}
+function commandLine(command, description) {
+  const commandColumn = command.length >= 38 ? `${command}  ` : command.padEnd(38);
+  return `${pc2.dim("\u2502")} ${pc2.bold(commandColumn)} ${description}`;
+}
+function renderCommandBlock(commands) {
+  return commands.map((entry) => commandLine(entry.command, entry.description)).join(`
+`);
+}
+function renderGroup(group) {
+  const lines = [
+    `${heading(`rig ${group.name}`)} \u2014 ${group.summary}`,
+    "",
+    pc2.bold("Usage"),
+    ...group.usage.map((line) => `  ${line}`),
+    "",
+    pc2.bold("Commands"),
+    ...group.commands.map((entry) => commandLine(entry.command, entry.description))
+  ];
+  if (group.examples?.length) {
+    lines.push("", pc2.bold("Examples"), ...group.examples.map((line) => `  ${pc2.dim("$")} ${line}`));
+  }
+  if (group.next?.length) {
+    lines.push("", pc2.bold("Next steps"), ...group.next.map((line) => `  ${pc2.dim("\u203A")} ${line}`));
+  }
+  if (group.advanced?.length) {
+    lines.push("", pc2.bold("Compatibility / advanced"), ...group.advanced.map((line) => `  ${pc2.dim("\u203A")} ${line}`));
+  }
+  return lines.join(`
+`);
+}
+function renderTopLevelHelp() {
+  return [
+    `${heading("rig")} ${pc2.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
+    pc2.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox/review gates."),
+    "",
+    ...TOP_LEVEL_SECTIONS.flatMap((section) => [
+      `${pc2.bold(pc2.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc2.dim(section.subtitle)}`,
+      renderCommandBlock(section.commands),
+      ""
+    ]),
+    pc2.dim("More: `rig help --advanced` for dev/compatibility commands; `rig <group> --help` for rich per-group help; `rig --version` for the installed version."),
+    "",
+    pc2.bold("Global options"),
+    commandLine("--project <path>", "Use a project root instead of auto-discovery."),
+    commandLine("--json", "Emit structured output for scripts/agents."),
+    commandLine("--dry-run", "Print the command plan without mutating state.")
+  ].join(`
+`).trimEnd();
+}
+function renderGroupHelp(groupName) {
+  const group = ALL_GROUPS.find((candidate) => candidate.name === groupName);
+  return group ? renderGroup(group) : null;
+}
+function shouldUseClackOutput2() {
+  return Boolean(process.stdout.isTTY) && process.env.RIG_CLI_PLAIN_HELP !== "1";
+}
+function printTopLevelHelp() {
+  if (!shouldUseClackOutput2()) {
+    console.log(renderTopLevelHelp());
+    return;
+  }
+  intro("rig");
+  for (const section of TOP_LEVEL_SECTIONS) {
+    note2(renderCommandBlock(section.commands), `${section.title} \u2014 ${section.subtitle}`);
+  }
+  log2.info("More: rig help --advanced \xB7 rig <group> --help \xB7 rig --version");
+  note2([
+    commandLine("--project <path>", "Use a project root instead of auto-discovery."),
+    commandLine("--json", "Emit structured output for scripts/agents."),
+    commandLine("--dry-run", "Print the command plan without mutating state.")
+  ].join(`
+`), "Global options");
+  outro("Server \u2192 task \u2192 run \u2192 inbox/review.");
+}
+function printGroupHelpDocument(groupName) {
+  const rendered = renderGroupHelp(groupName) ?? renderTopLevelHelp();
+  if (!shouldUseClackOutput2()) {
+    console.log(rendered);
+    return;
+  }
+  const group = ALL_GROUPS.find((candidate) => candidate.name === groupName);
+  if (!group) {
+    printTopLevelHelp();
+    return;
+  }
+  intro(`rig ${group.name}`);
+  note2(group.summary, "Purpose");
+  note2(group.usage.join(`
+`), "Usage");
+  note2(group.commands.map((entry) => commandLine(entry.command, entry.description)).join(`
+`), "Commands");
+  if (group.examples?.length)
+    note2(group.examples.map((line) => `$ ${line}`).join(`
+`), "Examples");
+  if (group.next?.length)
+    note2(group.next.map((line) => `\u203A ${line}`).join(`
+`), "Next steps");
+  if (group.advanced?.length)
+    log2.info(group.advanced.join(`
+`));
+  outro("Run with --json when scripts need structured output.");
+}
+
 // packages/cli/src/commands/task.ts
 import { buildPluginHostContext } from "@rig/runtime/control-plane/plugin-host-context";
 import { loadConfig } from "@rig/core/load-config";
@@ -1872,27 +2280,30 @@ function summarizeTask(task, options = {}) {
     ...options.raw ? { raw: raw ?? task } : {}
   };
 }
-function printTaskSummary(task) {
-  console.log(formatTaskList([task]));
-}
 async function validatorRegistryForTaskCommands(projectRoot) {
   return buildPluginHostContext(projectRoot).then((ctx) => ctx?.validatorRegistry ?? undefined).catch(() => {
     return;
   });
 }
 async function executeTask(context, args, options) {
-  const [command = "info", ...rest] = args;
+  if (args.length === 0) {
+    if (context.outputMode === "text") {
+      printGroupHelpDocument("task");
+    }
+    return { ok: true, group: "task", command: "help" };
+  }
+  const [command = "help", ...rest] = args;
   switch (command) {
     case "list": {
       let pending = rest;
       const rawResult = takeFlag(pending, "--raw");
       pending = rawResult.rest;
       const { filters, rest: remaining } = parseTaskFilters(pending);
-      requireNoExtraArgs(remaining, "bun run rig task list [--raw] [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
+      requireNoExtraArgs(remaining, "rig task list [--raw] [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
       const tasks = await listWorkspaceTasksViaServer(context, filters);
       if (context.outputMode === "text") {
         const renderedTasks = rawResult.value ? tasks.map((task) => summarizeTask(task, { raw: true })) : tasks.map((task) => summarizeTask(task));
-        console.log(formatTaskList(renderedTasks, { raw: rawResult.value }));
+        printFormattedOutput(formatTaskList(renderedTasks, { raw: rawResult.value }));
       }
       return {
         ok: true,
@@ -1902,10 +2313,13 @@ async function executeTask(context, args, options) {
       };
     }
     case "show": {
-      const taskOption = takeOption(rest, "--task");
+      let pending = rest;
+      const rawResult = takeFlag(pending, "--raw");
+      pending = rawResult.rest;
+      const taskOption = takeOption(pending, "--task");
       const positional = taskOption.rest.length > 0 && taskOption.rest[0] && !taskOption.rest[0].startsWith("-") ? taskOption.rest[0] : undefined;
       const remaining = positional ? taskOption.rest.slice(1) : taskOption.rest;
-      requireNoExtraArgs(remaining, "bun run rig task show <id>|--task <id>");
+      requireNoExtraArgs(remaining, "rig task show <id>|--task <id> [--raw]");
       const taskId3 = normalizeTaskRunTaskId(taskOption.value ?? positional);
       if (!taskId3)
         throw new CliError2("task show requires a task id.", 2);
@@ -1913,19 +2327,20 @@ async function executeTask(context, args, options) {
       if (!task)
         throw new CliError2(`Task not found: ${taskId3}`, 3);
       const summary = summarizeTask(task, { raw: true });
-      if (context.outputMode === "text")
-        console.log(JSON.stringify(summary, null, 2));
-      return { ok: true, group: "task", command, details: { task: summary } };
+      if (context.outputMode === "text") {
+        printFormattedOutput(rawResult.value ? JSON.stringify(summary, null, 2) : formatTaskDetails(summary));
+      }
+      return { ok: true, group: "task", command, details: { task: summary, raw: rawResult.value } };
     }
     case "next": {
       const { filters, rest: remaining } = parseTaskFilters(rest);
-      requireNoExtraArgs(remaining, "bun run rig task next [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
+      requireNoExtraArgs(remaining, "rig task next [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
       const selected = await selectNextWorkspaceTaskViaServer(context, filters);
       if (context.outputMode === "text") {
         if (selected.task) {
-          printTaskSummary(selected.task);
+          printFormattedOutput(formatTaskCard(summarizeTask(selected.task, { raw: true }), { title: "Selected task", selected: true }));
         } else {
-          console.log("No matching tasks.");
+          printFormattedOutput("No matching tasks.\n\nNext\n\u203A Try `rig task list` to inspect available work.\n\u203A Check server: `rig server status`");
         }
       }
       return {
@@ -1941,31 +2356,31 @@ async function executeTask(context, args, options) {
     }
     case "info": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig task info [--task <beads-id>]");
+      requireNoExtraArgs(remaining, "rig task info [--task <task-id>]");
       await withMutedConsole(context.outputMode === "json", () => taskInfo(context.projectRoot, task || undefined));
       return { ok: true, group: "task", command, details: { task: task || null } };
     }
     case "scope": {
       const filesFlag = takeFlag(rest, "--files");
       const { value: task, rest: remaining } = takeOption(filesFlag.rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig task scope [--task <id>] [--files]");
+      requireNoExtraArgs(remaining, "rig task scope [--task <id>] [--files]");
       await withMutedConsole(context.outputMode === "json", () => taskScope(context.projectRoot, filesFlag.value, task || undefined));
       return { ok: true, group: "task", command, details: { files: filesFlag.value, task: task || null } };
     }
     case "deps":
-      requireNoExtraArgs(rest, "bun run rig task deps");
+      requireNoExtraArgs(rest, "rig task deps");
       await withMutedConsole(context.outputMode === "json", () => taskDeps(context.projectRoot));
       return { ok: true, group: "task", command };
     case "status":
-      requireNoExtraArgs(rest, "bun run rig task status");
+      requireNoExtraArgs(rest, "rig task status");
       withMutedConsole(context.outputMode === "json", () => taskStatus2(context.projectRoot));
       return { ok: true, group: "task", command };
     case "artifacts":
-      requireNoExtraArgs(rest, "bun run rig task artifacts");
+      requireNoExtraArgs(rest, "rig task artifacts");
       withMutedConsole(context.outputMode === "json", () => taskArtifacts(context.projectRoot));
       return { ok: true, group: "task", command };
     case "artifact-dir": {
-      requireNoExtraArgs(rest, "bun run rig task artifact-dir");
+      requireNoExtraArgs(rest, "rig task artifact-dir");
       const path = taskArtifactDir(context.projectRoot);
       if (context.outputMode === "text") {
         console.log(path);
@@ -1974,7 +2389,7 @@ async function executeTask(context, args, options) {
     }
     case "artifact-write": {
       if (rest.length < 1) {
-        throw new CliError2(`Usage: bun run rig task artifact-write <filename> [--file <path>]
+        throw new CliError2(`Usage: rig task artifact-write <filename> [--file <path>]
 ` + `  Reads content from stdin (or --file), writes to the active task artifact dir.
 ` + "  Example: echo '...' | rig task artifact-write collection-audit.md");
       }
@@ -1987,7 +2402,7 @@ async function executeTask(context, args, options) {
         content = await readStdin();
       }
       if (!artifactFilename) {
-        throw new CliError2("Usage: bun run rig task artifact-write <filename> [--file path]");
+        throw new CliError2("Usage: rig task artifact-write <filename> [--file path]");
       }
       withMutedConsole(context.outputMode === "json", () => taskArtifactWrite(context.projectRoot, artifactFilename, content));
       return { ok: true, group: "task", command, details: { filename: artifactFilename } };
@@ -1996,11 +2411,11 @@ async function executeTask(context, args, options) {
       return options.executeTaskReportBug(context, rest);
     case "lookup": {
       if (rest.length !== 1) {
-        throw new CliError2("Usage: bun run rig task lookup <beads-id>");
+        throw new CliError2("Usage: rig task lookup <task-id>");
       }
       const lookupId = rest[0];
       if (!lookupId) {
-        throw new CliError2("Usage: bun run rig task lookup <beads-id>");
+        throw new CliError2("Usage: rig task lookup <task-id>");
       }
       const result = taskLookup(context.projectRoot, lookupId);
       if (context.outputMode === "text") {
@@ -2010,17 +2425,17 @@ async function executeTask(context, args, options) {
     }
     case "record": {
       if (rest.length < 2) {
-        throw new CliError2("Usage: bun run rig task record <decision|failure> <text>");
+        throw new CliError2("Usage: rig task record <decision|failure> <text>");
       }
       const type = rest[0];
       if (type !== "decision" && type !== "failure") {
-        throw new CliError2("Usage: bun run rig task record <decision|failure> <text>");
+        throw new CliError2("Usage: rig task record <decision|failure> <text>");
       }
       withMutedConsole(context.outputMode === "json", () => taskRecord(context.projectRoot, type, rest.slice(1).join(" ")));
       return { ok: true, group: "task", command, details: { type: rest[0] } };
     }
     case "ready":
-      requireNoExtraArgs(rest, "bun run rig task ready");
+      requireNoExtraArgs(rest, "rig task ready");
       await withMutedConsole(context.outputMode === "json", () => taskReady(context.projectRoot));
       return { ok: true, group: "task", command };
     case "run": {
@@ -2057,7 +2472,7 @@ async function executeTask(context, args, options) {
       if (positionalTaskId) {
         pending = pending.slice(1);
       }
-      requireNoExtraArgs(pending, "bun run rig task run [#<issue>|<task-id>] [--next] [--task <id>] [--detach] [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--pr auto|ask|off] [--no-pr] [--dirty-baseline head|dirty-snapshot] [--skip-project-sync]");
+      requireNoExtraArgs(pending, "rig task run [#<issue>|<task-id>] [--next] [--task <id>] [--detach] [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--pr auto|ask|off] [--no-pr] [--dirty-baseline head|dirty-snapshot] [--skip-project-sync]");
       if (nextResult.value && (taskResult.value || positionalTaskId)) {
         throw new CliError2("task run cannot combine --next with an explicit task id.", 2);
       }
@@ -2111,10 +2526,24 @@ async function executeTask(context, args, options) {
       });
       let attachDetails = null;
       if (!detachResult.value && context.outputMode === "text") {
-        console.log(formatSubmittedRun({ runId: submitted.runId, task: selectedTask ? summarizeTask(selectedTask) : null }));
+        printFormattedOutput(formatSubmittedRun({
+          runId: submitted.runId,
+          task: selectedTask ? summarizeTask(selectedTask) : null,
+          runtimeAdapter,
+          runtimeMode: runtimeModeResult.value || projectDefaults.runtimeMode || "full-access",
+          interactionMode: interactionModeResult.value || "default",
+          detached: false
+        }));
         attachDetails = await attachRunOperatorView(context, { runId: submitted.runId, follow: true });
       } else if (context.outputMode === "text") {
-        console.log(formatSubmittedRun({ runId: submitted.runId, task: selectedTask ? summarizeTask(selectedTask) : null }));
+        printFormattedOutput(formatSubmittedRun({
+          runId: submitted.runId,
+          task: selectedTask ? summarizeTask(selectedTask) : null,
+          runtimeAdapter,
+          runtimeMode: runtimeModeResult.value || projectDefaults.runtimeMode || "full-access",
+          interactionMode: interactionModeResult.value || "default",
+          detached: true
+        }));
       }
       return {
         ok: true,
@@ -2138,7 +2567,7 @@ async function executeTask(context, args, options) {
     }
     case "validate": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig task validate [--task <beads-id>]");
+      requireNoExtraArgs(remaining, "rig task validate [--task <task-id>]");
       if (context.dryRun) {
         await context.runCommand(["rig", "task", "validate", ...task ? ["--task", task] : []]);
         return { ok: true, group: "task", command, details: { task: task || "active" } };
@@ -2151,12 +2580,12 @@ async function executeTask(context, args, options) {
     }
     case "verify": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig task verify [--task <beads-id>]");
+      requireNoExtraArgs(remaining, "rig task verify [--task <task-id>]");
       if (context.dryRun) {
         await context.runCommand(["rig", "task", "verify", ...task ? ["--task", task] : []]);
         return { ok: true, group: "task", command, details: { task: task || "active" } };
       }
-      const ok = await withMutedConsole(context.outputMode === "json", () => taskVerify(context.projectRoot, context.plugins, task || undefined));
+      const ok = await withMutedConsole(context.outputMode === "json", () => taskVerify(context.projectRoot, task || undefined));
       if (!ok) {
         throw new CliError2(`Verification rejected for ${task || "active task"}.`, 2);
       }
@@ -2164,15 +2593,19 @@ async function executeTask(context, args, options) {
     }
     case "reset": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig task reset --task <beads-id>");
-      const requiredTask = requireTask(task, "bun run rig task reset --task <beads-id>");
-      await context.runCommand(["br", "--no-db", "update", requiredTask, "--status", "open"]);
-      return { ok: true, group: "task", command, details: { task: requiredTask } };
+      requireNoExtraArgs(remaining, "rig task reset --task <task-id>");
+      const requiredTask = requireTask(task, "rig task reset --task <task-id>");
+      const summary = withMutedConsole(context.outputMode === "json", () => taskReopen(context.projectRoot, {
+        all: false,
+        taskId: requiredTask,
+        dryRun: false
+      }));
+      return { ok: true, group: "task", command, details: summary };
     }
     case "details": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig task details --task <beads-id>");
-      const requiredTask = requireTask(task, "bun run rig task details --task <beads-id>");
+      requireNoExtraArgs(remaining, "rig task details --task <task-id>");
+      const requiredTask = requireTask(task, "rig task details --task <task-id>");
       await withMutedConsole(context.outputMode === "json", () => taskInfo(context.projectRoot, requiredTask));
       return { ok: true, group: "task", command, details: { task: requiredTask } };
     }
@@ -2180,9 +2613,9 @@ async function executeTask(context, args, options) {
       const { value: task, rest: rest1 } = takeOption(rest, "--task");
       const allFlag = takeFlag(rest1, "--all");
       const { rest: remaining } = takeOption(allFlag.rest, "--reason");
-      requireNoExtraArgs(remaining, "bun run rig task reopen [--task <id> | --all] [--reason <text>]");
+      requireNoExtraArgs(remaining, "rig task reopen [--task <id> | --all] [--reason <text>]");
       if (!allFlag.value && !task) {
-        throw new CliError2("Usage: bun run rig task reopen [--task <id> | --all] [--reason <text>]");
+        throw new CliError2("Usage: rig task reopen [--task <id> | --all] [--reason <text>]");
       }
       const summary = withMutedConsole(context.outputMode === "json", () => taskReopen(context.projectRoot, {
         all: allFlag.value,