@h-rig/cli 0.0.6-alpha.6 → 0.0.6-alpha.60

package/dist/src/commands/_help-catalog.js

@@ -0,0 +1,445 @@
+// @bun
+// packages/cli/src/commands/_help-catalog.ts
+import { intro, log, note, outro } from "@clack/prompts";
+import pc from "picocolors";
+var TOP_LEVEL_SECTIONS = [
+  {
+    title: "Start here",
+    subtitle: "one-time setup for a repo",
+    commands: [
+      { command: "rig init", description: "Wizard: config, GitHub auth, task source, server, Pi wiring." },
+      { command: "rig doctor", description: "Check every part of the wiring \u2014 run this when anything feels off." },
+      { command: "rig server use <alias|local>", description: "Pick which Rig server owns this repo (`rig server list` to see them)." }
+    ]
+  },
+  {
+    title: "Work",
+    subtitle: "find a task and put an agent on it",
+    commands: [
+      { command: "rig task list", description: "What's on the board (from the selected source/server)." },
+      { command: "rig task next", description: "The next ready task, as a card." },
+      { command: "rig task run --next", description: "Dispatch an agent; interactive mode opens the native Pi session." },
+      { command: "rig task run <id> --detach", description: "Fire-and-forget a specific task." }
+    ]
+  },
+  {
+    title: "Watch & steer",
+    subtitle: "live runs are observable and steerable, attached or not",
+    commands: [
+      { command: "rig run status", description: "Active and recent runs at a glance." },
+      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
+      { command: "rig run steer <id> -m <text>", description: "Drop a message into a live worker without attaching." },
+      { command: "rig run stop <id>", description: "Cancel a running worker." }
+    ]
+  },
+  {
+    title: "Unblock & gate",
+    subtitle: "answer what workers ask; control what merges",
+    commands: [
+      { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." },
+      { command: "rig inbox inputs", description: "Questions workers asked (then `rig inbox respond \u2026`)." },
+      { command: "rig review show|set", description: "The completion review gate (Greptile is mandatory on merges)." }
+    ]
+  },
+  {
+    title: "Extend",
+    subtitle: "more Pi, more plugins",
+    commands: [
+      { command: "rig pi search <term>", description: "Discover community Pi extensions on npm." },
+      { command: "rig pi add <pkg>", description: "Add a Pi extension to this project (workers pick it up too)." },
+      { command: "rig plugin list", description: "What the rig.config.ts plugins contribute." }
+    ]
+  }
+];
+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 opens the enriched bundled Pi (worker brain).", primary: true },
+      { command: "stop [<run-id>|--run <id>]", description: "Request stop for one run or local active runs.", primary: true },
+      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching." },
+      { 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 for a task.",
+    usage: ["rig inspect <logs|artifacts|failures|graph|audit|diff> --task <id>"],
+    commands: [
+      { command: "logs --task <id>", description: "Latest run log for a task (local or selected server)." },
+      { command: "artifacts --task <id>", description: "List the task's completion artifacts." },
+      { command: "failures --task <id>", description: "Recorded failures for a task." },
+      { command: "graph", description: "Task dependency graph." },
+      { command: "audit", description: "Controlled-command audit trail." },
+      { command: "diff --task <id>", description: "Changed files for a task." }
+    ]
+  },
+  { 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: "pi",
+    summary: "Manage Pi extension packages for this project (community extensions from npm/git).",
+    usage: ["rig pi <list|add|remove|search> [args]"],
+    commands: [
+      { command: "list", description: "Show project and user Pi extension packages." },
+      { command: "add <source>", description: "Add an npm/git Pi extension to .pi/settings.json (auto-installs at next session)." },
+      { command: "remove <source>", description: "Remove an operator-added Pi extension." },
+      { command: "search [term]", description: "Discover Pi extension packages on the npm registry." }
+    ],
+    examples: ["rig pi search subagents", "rig pi add pi-subagents", "rig pi list"],
+    next: ["Config-managed extensions: declare `runtime: { pi: { packages: [...] } }` in rig.config.ts \u2014 workers pick them up automatically."]
+  },
+  {
+    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 ADVANCED_COMMANDS = [
+  { command: "rig server task-run ...", description: "Internal server-owned task execution entry point." },
+  { command: "rig server notify-test [--event <type>]", description: "Internal event notification smoke command." },
+  { command: "rig run start|start-serial|start-parallel", description: "Local epic queue starters (server-owned tasks use `rig task run ...`)." },
+  { command: "rig remote orchestrate-*", description: "Compatibility remote orchestration commands." }
+];
+var ALL_GROUPS = [...PRIMARY_GROUPS, ...ADVANCED_GROUPS];
+function heading(title) {
+  return pc.bold(pc.cyan(title));
+}
+function renderRigBanner(version) {
+  const m = (s) => pc.bold(pc.magenta(s));
+  const c = (s) => pc.bold(pc.cyan(s));
+  const y = (s) => pc.yellow(s);
+  const d = (s) => pc.dim(s);
+  const lines = [
+    m("    \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 ") + d("  \u2591\u2592\u2593\u2588 "),
+    m("    \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D ") + d("\u2593\u2592\u2591"),
+    c("    \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2588\u2557") + d("    \u2591\u2592"),
+    c("    \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551") + d(" \u2588\u2593\u2591"),
+    y("    \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D") + d("   \u2592\u2591"),
+    y("    \u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D "),
+    "",
+    `    ${c("\u25E2\u25E4")} ${pc.bold("the control rig for autonomous coding agents")} ${m("//")} ${d("you are the operator")}`,
+    version ? `    ${d(`v${version} \xB7 jack in: rig task run --next`)}` : `    ${d("jack in: rig task run --next")}`
+  ];
+  return lines.join(`
+`);
+}
+function commandLine(command, description) {
+  const commandColumn = command.length >= 38 ? `${command}  ` : command.padEnd(38);
+  return `${pc.dim("\u2502")} ${pc.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}`,
+    "",
+    pc.bold("Usage"),
+    ...group.usage.map((line) => `  ${line}`),
+    "",
+    pc.bold("Commands"),
+    ...group.commands.map((entry) => commandLine(entry.command, entry.description))
+  ];
+  if (group.examples?.length) {
+    lines.push("", pc.bold("Examples"), ...group.examples.map((line) => `  ${pc.dim("$")} ${line}`));
+  }
+  if (group.next?.length) {
+    lines.push("", pc.bold("Next steps"), ...group.next.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  if (group.advanced?.length) {
+    lines.push("", pc.bold("Compatibility / advanced"), ...group.advanced.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  return lines.join(`
+`);
+}
+function renderTopLevelHelp() {
+  return [
+    `${heading("rig")} ${pc.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
+    pc.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) => [
+      `${pc.bold(pc.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc.dim(section.subtitle)}`,
+      renderCommandBlock(section.commands),
+      ""
+    ]),
+    pc.dim("More: `rig help --advanced` for dev/compatibility commands; `rig <group> --help` for rich per-group help; `rig --version` for the installed version."),
+    "",
+    pc.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 renderAdvancedHelp() {
+  return [
+    `${heading("rig advanced")} \u2014 compatibility, diagnostics, and internal surfaces`,
+    "",
+    pc.bold("Primary groups"),
+    "  server, task, run, inbox, review, init, doctor, github",
+    "",
+    pc.bold("Advanced commands"),
+    ...ADVANCED_COMMANDS.map((entry) => commandLine(entry.command, entry.description)),
+    "",
+    pc.bold("Advanced groups"),
+    ...ADVANCED_GROUPS.map((group) => commandLine(group.name, group.summary)),
+    "",
+    pc.dim("All groups remain callable. Prefer `rig server`, `rig task`, `rig run`, `rig inbox`, and `rig review` for day-to-day work.")
+  ].join(`
+`);
+}
+function renderGroupHelp(groupName) {
+  const group = ALL_GROUPS.find((candidate) => candidate.name === groupName);
+  return group ? renderGroup(group) : null;
+}
+function listHelpGroups() {
+  return ALL_GROUPS.map((group) => group.name);
+}
+function shouldUseClackOutput() {
+  return Boolean(process.stdout.isTTY) && process.env.RIG_CLI_PLAIN_HELP !== "1";
+}
+function printTopLevelHelp(state = {}) {
+  if (!shouldUseClackOutput()) {
+    console.log(renderTopLevelHelp());
+    return;
+  }
+  console.log(renderRigBanner(state.version));
+  console.log("");
+  if (state.projectInitialized === false) {
+    intro("no rig project in this directory");
+    note([
+      commandLine("rig init", "Set this repo up: config, GitHub auth, task source, server, Pi."),
+      commandLine("rig init --yes", "Same, non-interactive, sensible defaults."),
+      commandLine("rig doctor", "Already initialized somewhere else? Check the wiring.")
+    ].join(`
+`), "Get started");
+    outro("After init: rig task run --next puts an agent on your next task.");
+    return;
+  }
+  intro(state.selectedServer ? `server: ${state.selectedServer}` : "rig");
+  for (const section of TOP_LEVEL_SECTIONS) {
+    note(renderCommandBlock(section.commands), `${section.title} \u2014 ${section.subtitle}`);
+  }
+  log.info("More: rig help --advanced \xB7 rig <group> --help \xB7 rig --version");
+  note([
+    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("init \u2192 task run \u2192 watch/steer \u2192 inbox/review \u2192 merged.");
+}
+function printAdvancedHelp() {
+  if (!shouldUseClackOutput()) {
+    console.log(renderAdvancedHelp());
+    return;
+  }
+  intro("rig advanced");
+  note(ADVANCED_COMMANDS.map((entry) => commandLine(entry.command, entry.description)).join(`
+`), "Advanced commands");
+  note(ADVANCED_GROUPS.map((group) => commandLine(group.name, group.summary)).join(`
+`), "Advanced groups");
+  outro("Primary daily flow: rig server \xB7 rig task \xB7 rig run \xB7 rig inbox \xB7 rig review.");
+}
+function printGroupHelpDocument(groupName) {
+  const rendered = renderGroupHelp(groupName) ?? renderTopLevelHelp();
+  if (!shouldUseClackOutput()) {
+    console.log(rendered);
+    return;
+  }
+  const group = ALL_GROUPS.find((candidate) => candidate.name === groupName);
+  if (!group) {
+    printTopLevelHelp();
+    return;
+  }
+  intro(`rig ${group.name}`);
+  note(group.summary, "Purpose");
+  note(group.usage.join(`
+`), "Usage");
+  note(group.commands.map((entry) => commandLine(entry.command, entry.description)).join(`
+`), "Commands");
+  if (group.examples?.length)
+    note(group.examples.map((line) => `$ ${line}`).join(`
+`), "Examples");
+  if (group.next?.length)
+    note(group.next.map((line) => `\u203A ${line}`).join(`
+`), "Next steps");
+  if (group.advanced?.length)
+    log.info(group.advanced.join(`
+`));
+  outro("Run with --json when scripts need structured output.");
+}
+export {
+  renderTopLevelHelp,
+  renderRigBanner,
+  renderGroupHelp,
+  renderAdvancedHelp,
+  printTopLevelHelp,
+  printGroupHelpDocument,
+  printAdvancedHelp,
+  listHelpGroups
+};

package/dist/src/commands/_operator-surface.js

@@ -0,0 +1,220 @@
+// @bun
+// packages/cli/src/commands/_operator-surface.ts
+import { createInterface } from "readline";
+import { createInterface as createPromptInterface } from "readline/promises";
+var CANONICAL_STAGES = [
+  "Connect",
+  "GitHub/task sync",
+  "Prepare workspace",
+  "Launch Pi",
+  "Plan",
+  "Implement",
+  "Validate",
+  "Commit",
+  "Open PR",
+  "Review/CI",
+  "Merge",
+  "Complete"
+];
+function logDetail(log) {
+  return typeof log.detail === "string" ? log.detail.trim() : "";
+}
+function parseProviderProtocolLog(title, detail) {
+  if (title.trim().toLowerCase() !== "agent output")
+    return null;
+  if (!detail.startsWith("{") || !detail.endsWith("}"))
+    return null;
+  try {
+    const record = JSON.parse(detail);
+    if (!record || typeof record !== "object" || Array.isArray(record))
+      return null;
+    const type = record.type;
+    return typeof type === "string" && [
+      "assistant",
+      "message_start",
+      "message_update",
+      "message_end",
+      "stream_event",
+      "tool_result",
+      "tool_execution_start",
+      "tool_execution_update",
+      "tool_execution_end",
+      "turn_start",
+      "turn_end"
+    ].includes(type) ? record : null;
+  } catch {
+    return null;
+  }
+}
+function renderProviderProtocolLog(record) {
+  const type = typeof record.type === "string" ? record.type : "";
+  if (type === "tool_execution_start" || type === "tool_execution_update" || type === "tool_execution_end") {
+    const toolName = String(record.toolName ?? record.name ?? "tool");
+    const status = type === "tool_execution_start" ? "started" : type === "tool_execution_end" ? record.isError === true || record.result && typeof record.result === "object" && !Array.isArray(record.result) && record.result.isError === true ? "failed" : "completed" : "running";
+    return `[Pi tool] ${toolName} ${status}`;
+  }
+  return null;
+}
+function entryId(entry, fallback) {
+  return typeof entry.id === "string" && entry.id.trim() ? entry.id : fallback;
+}
+function renderOperatorSnapshot(snapshot) {
+  const run = snapshot.run.run && typeof snapshot.run.run === "object" ? snapshot.run.run : snapshot.run;
+  const runId = String(run.runId ?? run.id ?? "run");
+  const status = String(run.status ?? "unknown");
+  const logs = snapshot.logs ?? [];
+  const latestByStage = new Map;
+  for (const log of logs) {
+    const title = String(log.title ?? "").toLowerCase();
+    const stageName = String(log.stage ?? "").toLowerCase();
+    const stage = CANONICAL_STAGES.find((candidate) => candidate.toLowerCase() === title || candidate.toLowerCase() === stageName);
+    if (stage)
+      latestByStage.set(stage, log);
+  }
+  const stageLines = CANONICAL_STAGES.flatMap((stage) => {
+    const match = latestByStage.get(stage);
+    return match ? [`${stage}: ${String(match.status ?? status)}${logDetail(match) ? ` \u2014 ${logDetail(match)}` : ""}`] : [];
+  });
+  return [`Rig run ${runId}: ${status}`, ...stageLines].join(`
+`);
+}
+function createPiRunStreamRenderer(output = process.stdout) {
+  let lastSnapshot = "";
+  const assistantTextById = new Map;
+  const seenTimeline = new Set;
+  const seenLogs = new Set;
+  const writeLine = (line) => output.write(`${line}
+`);
+  return {
+    renderSnapshot(snapshot) {
+      const rendered = renderOperatorSnapshot(snapshot);
+      if (rendered && rendered !== lastSnapshot) {
+        writeLine(rendered);
+        lastSnapshot = rendered;
+      }
+    },
+    renderTimeline(entries) {
+      for (const [index, entry] of entries.entries()) {
+        const id = entryId(entry, `timeline:${index}:${String(entry.cursor ?? "")}`);
+        if (entry.type === "assistant_message" && typeof entry.text === "string") {
+          const text = entry.text;
+          const previousText = assistantTextById.get(id) ?? "";
+          if (!previousText && text.trim()) {
+            writeLine("[Pi assistant]");
+          }
+          if (text.startsWith(previousText)) {
+            const delta = text.slice(previousText.length);
+            if (delta)
+              output.write(delta);
+          } else if (text.trim() && text !== previousText) {
+            if (previousText)
+              writeLine(`
+[Pi assistant]`);
+            output.write(text);
+          }
+          assistantTextById.set(id, text);
+          continue;
+        }
+        if (seenTimeline.has(id))
+          continue;
+        seenTimeline.add(id);
+        if (entry.type === "tool_execution_start" || entry.type === "tool_execution_update" || entry.type === "tool_execution_end" || entry.type === "mcp_tool_call") {
+          writeLine(`[Pi tool] ${String(entry.toolName ?? entry.name ?? entry.title ?? entry.type)} ${String(entry.status ?? entry.state ?? "")}`.trim());
+          continue;
+        }
+        if (entry.type === "timeline_warning") {
+          writeLine(`[Rig timeline] ${String(entry.detail ?? entry.message ?? "timeline unavailable")}`);
+          continue;
+        }
+        if (entry.type === "action") {
+          const text = String(entry.detail ?? entry.message ?? entry.title ?? "").trim();
+          if (text)
+            writeLine(`[Rig action] ${text}`);
+          continue;
+        }
+        if (entry.type === "user_message") {
+          const text = String(entry.text ?? entry.message ?? entry.detail ?? "").trim();
+          if (text)
+            writeLine(`[Operator] ${text}`);
+          continue;
+        }
+        const fallback = String(entry.detail ?? entry.message ?? entry.text ?? entry.title ?? "").trim();
+        if (fallback)
+          writeLine(`[${String(entry.type ?? "timeline")}] ${fallback}`);
+      }
+    },
+    renderLogs(entries) {
+      for (const [index, entry] of entries.entries()) {
+        const id = entryId(entry, `log:${index}:${String(entry.createdAt ?? "")}:${String(entry.title ?? "")}`);
+        if (seenLogs.has(id))
+          continue;
+        seenLogs.add(id);
+        const title = String(entry.title ?? "");
+        if (CANONICAL_STAGES.some((stage) => stage.toLowerCase() === title.toLowerCase()))
+          continue;
+        const detail = logDetail(entry);
+        if (!detail)
+          continue;
+        const protocolRecord = parseProviderProtocolLog(title, detail);
+        if (protocolRecord) {
+          const protocolLine = renderProviderProtocolLog(protocolRecord);
+          if (protocolLine)
+            writeLine(protocolLine);
+          continue;
+        }
+        writeLine(`[${title || "Rig log"}] ${detail}`);
+      }
+    }
+  };
+}
+function createOperatorSurface(options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const errorOutput = options.errorOutput ?? process.stderr;
+  const renderer = createPiRunStreamRenderer(output);
+  const writeLine = (line) => output.write(`${line}
+`);
+  return {
+    mode: "pi-compatible-text",
+    ...renderer,
+    info: writeLine,
+    error: (message) => errorOutput.write(`${message}
+`),
+    attachCommandInput(handler) {
+      if (options.interactive === false || !input.isTTY)
+        return null;
+      const rl = createInterface({ input, output: process.stdout, terminal: false });
+      rl.on("line", (line) => {
+        Promise.resolve(handler(line)).catch((error) => writeLine(`Operator command failed: ${error instanceof Error ? error.message : String(error)}`));
+      });
+      return { close: () => rl.close() };
+    }
+  };
+}
+function taskId(task) {
+  return typeof task.id === "string" && task.id.trim() ? task.id : "<unknown>";
+}
+function taskTitle(task) {
+  return typeof task.title === "string" && task.title.trim() ? task.title : "Untitled task";
+}
+function taskStatus(task) {
+  return typeof task.status === "string" && task.status.trim() ? task.status : "unknown";
+}
+function renderTaskPickerRows(tasks) {
+  return tasks.map((task, index) => `${index + 1}. ${taskId(task)} \xB7 ${taskStatus(task)} \xB7 ${taskTitle(task)}`);
+}
+async function promptForTaskSelection(question) {
+  const rl = createPromptInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+export {
+  renderTaskPickerRows,
+  renderOperatorSnapshot,
+  promptForTaskSelection,
+  createPiRunStreamRenderer,
+  createOperatorSurface
+};