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

package/dist/src/commands/stats.js

@@ -0,0 +1,1051 @@
+// @bun
+// packages/cli/src/commands/stats.ts
+import pc4 from "picocolors";
+
+// packages/cli/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
+function takeOption(args, option) {
+  const rest = [];
+  let value;
+  for (let index = 0;index < args.length; index += 1) {
+    const current = args[index];
+    if (current === option) {
+      const next = args[index + 1];
+      if (!next || next.startsWith("-")) {
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
+      }
+      value = next;
+      index += 1;
+      continue;
+    }
+    if (current !== undefined) {
+      rest.push(current);
+    }
+  }
+  return { value, rest };
+}
+function requireNoExtraArgs(args, usage) {
+  if (args.length > 0) {
+    throw new CliError(`Unexpected arguments: ${args.join(" ")}
+Usage: ${usage}`);
+  }
+}
+
+// packages/cli/src/commands/stats.ts
+import { computeRigStats } from "@rig/runtime/control-plane/native/run-stats";
+
+// packages/cli/src/commands/_connection-state.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+function resolveGlobalConnectionsPath(env = process.env) {
+  const explicit = env.RIG_CONNECTIONS_FILE?.trim();
+  if (explicit)
+    return resolve(explicit);
+  const stateDir = env.RIG_GLOBAL_STATE_DIR?.trim();
+  if (stateDir)
+    return resolve(stateDir, "connections.json");
+  return resolve(homedir(), ".rig", "connections.json");
+}
+function resolveRepoConnectionPath(projectRoot) {
+  return resolve(projectRoot, ".rig", "state", "connection.json");
+}
+function readJsonFile(path) {
+  if (!existsSync(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
+  }
+}
+function writeJsonFile(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function normalizeConnection(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return null;
+  const record = value;
+  if (record.kind === "local")
+    return { kind: "local", mode: "auto" };
+  if (record.kind === "remote" && typeof record.baseUrl === "string" && record.baseUrl.trim()) {
+    const baseUrl = record.baseUrl.trim().replace(/\/+$/, "");
+    return { kind: "remote", baseUrl };
+  }
+  return null;
+}
+function readGlobalConnections(options = {}) {
+  const path = resolveGlobalConnectionsPath(options.env ?? process.env);
+  const payload = readJsonFile(path);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return { connections: {} };
+  }
+  const rawConnections = payload.connections;
+  const connections = {};
+  if (rawConnections && typeof rawConnections === "object" && !Array.isArray(rawConnections)) {
+    for (const [alias, raw] of Object.entries(rawConnections)) {
+      const connection = normalizeConnection(raw);
+      if (connection)
+        connections[alias] = connection;
+    }
+  }
+  return { connections };
+}
+function readRepoConnection(projectRoot) {
+  const payload = readJsonFile(resolveRepoConnectionPath(projectRoot));
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const selected = typeof record.selected === "string" ? record.selected.trim() : "";
+  if (!selected)
+    return null;
+  return {
+    selected,
+    project: typeof record.project === "string" ? record.project : undefined,
+    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined,
+    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined
+  };
+}
+function writeRepoConnection(projectRoot, state) {
+  writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
+}
+function resolveSelectedConnection(projectRoot, options = {}) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return null;
+  if (repo.selected === "local")
+    return { alias: "local", connection: { kind: "local", mode: "auto" }, serverProjectRoot: repo.serverProjectRoot };
+  const global = readGlobalConnections(options);
+  const connection = global.connections[repo.selected];
+  if (!connection) {
+    throw new CliError(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
+  }
+  return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
+}
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
+}
+function isRemoteConnectionSelected(projectRoot) {
+  return resolveSelectedConnection(projectRoot)?.connection.kind === "remote";
+}
+
+// packages/cli/src/commands/_server-client.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
+var scopedGitHubBearerTokens = new Map;
+var serverPhaseListener = null;
+function setServerPhaseListener(listener) {
+  const previous = serverPhaseListener;
+  serverPhaseListener = listener;
+  return previous;
+}
+function reportServerPhase(label) {
+  serverPhaseListener?.(label);
+}
+function cleanToken(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+function readPrivateRemoteSessionToken(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "github-auth.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return cleanToken(typeof parsed.apiSessionToken === "string" ? parsed.apiSessionToken : typeof parsed.sessionToken === "string" ? parsed.sessionToken : undefined);
+  } catch {
+    return null;
+  }
+}
+function readGitHubBearerTokenForRemote(projectRoot) {
+  const scopedKey = resolve2(projectRoot);
+  if (scopedGitHubBearerTokens.has(scopedKey))
+    return scopedGitHubBearerTokens.get(scopedKey) ?? null;
+  const privateSession = readPrivateRemoteSessionToken(projectRoot);
+  if (privateSession)
+    return privateSession;
+  return cleanToken(process.env.RIG_SERVER_AUTH_TOKEN) ?? cleanToken(process.env.RIG_REMOTE_AUTH_TOKEN);
+}
+function readStoredGitHubAuthToken(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "github-auth.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return cleanToken(typeof parsed.token === "string" ? parsed.token : undefined);
+  } catch {
+    return null;
+  }
+}
+function readLocalConnectionFallbackToken(projectRoot) {
+  return readGitHubBearerTokenForRemote(projectRoot) ?? cleanToken(process.env.RIG_GITHUB_TOKEN) ?? readStoredGitHubAuthToken(projectRoot);
+}
+async function ensureServerForCli(projectRoot) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected?.connection.kind === "remote") {
+      reportServerPhase(`Connecting to ${selected.alias}\u2026`);
+      const authToken = readGitHubBearerTokenForRemote(projectRoot);
+      const serverProjectRoot = selected.serverProjectRoot ?? await backfillRemoteServerProjectRoot(projectRoot, selected.connection.baseUrl, authToken);
+      return {
+        baseUrl: selected.connection.baseUrl,
+        authToken,
+        connectionKind: "remote",
+        serverProjectRoot
+      };
+    }
+    reportServerPhase("Starting local Rig server\u2026");
+    const connection = await ensureLocalRigServerConnection(projectRoot);
+    return {
+      baseUrl: connection.baseUrl,
+      authToken: connection.authToken ?? readLocalConnectionFallbackToken(projectRoot),
+      connectionKind: "local",
+      serverProjectRoot: resolve2(projectRoot)
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new CliError(error.message, 1);
+    }
+    throw error;
+  }
+}
+async function backfillRemoteServerProjectRoot(projectRoot, baseUrl, authToken) {
+  const repo = readRepoConnection(projectRoot);
+  const slug = repo?.project?.trim();
+  if (!slug)
+    return null;
+  try {
+    const response = await fetch(`${baseUrl}/api/projects/${encodeURIComponent(slug)}`, {
+      headers: mergeHeaders(undefined, authToken)
+    });
+    if (!response.ok)
+      return null;
+    const payload = await response.json();
+    const project = payload.project && typeof payload.project === "object" && !Array.isArray(payload.project) ? payload.project : null;
+    const checkouts = Array.isArray(project?.checkouts) ? project.checkouts : [];
+    const latestCheckout = [...checkouts].reverse().find((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.path === "string"));
+    const path = typeof latestCheckout?.path === "string" && latestCheckout.path.trim() ? latestCheckout.path.trim() : null;
+    if (path)
+      writeRepoServerProjectRoot(projectRoot, path);
+    return path;
+  } catch {
+    return null;
+  }
+}
+function mergeHeaders(headers, authToken) {
+  const merged = new Headers(headers);
+  if (authToken) {
+    merged.set("authorization", `Bearer ${authToken}`);
+  }
+  return merged;
+}
+function diagnosticMessage(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const diagnostics = Array.isArray(record.diagnostics) ? record.diagnostics : [];
+  const messages = diagnostics.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      return [];
+    const diagnostic = entry;
+    const kind = typeof diagnostic.kind === "string" ? diagnostic.kind : "task-source";
+    const message = typeof diagnostic.message === "string" ? diagnostic.message : null;
+    return message ? [`${kind}: ${message}`] : [];
+  });
+  return messages.length > 0 ? messages.join("; ") : null;
+}
+var serverReachabilityCache = new Map;
+async function probeServerReachability(baseUrl, authToken) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/api/server/status`, {
+      headers: mergeHeaders(undefined, authToken),
+      signal: AbortSignal.timeout(1500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+function cachedServerReachability(projectRoot, baseUrl, authToken) {
+  const key = resolve2(projectRoot);
+  const cached = serverReachabilityCache.get(key);
+  if (cached)
+    return cached;
+  const probe = probeServerReachability(baseUrl, authToken);
+  serverReachabilityCache.set(key, probe);
+  return probe;
+}
+function describeSelectedServer(projectRoot, server) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected) {
+      return {
+        alias: selected.alias,
+        target: selected.connection.kind === "remote" ? selected.connection.baseUrl : server.baseUrl
+      };
+    }
+  } catch {}
+  return { alias: server.connectionKind === "remote" ? "remote" : "local", target: server.baseUrl };
+}
+async function buildServerFailureContext(projectRoot, server) {
+  const { alias, target } = describeSelectedServer(projectRoot, server);
+  const reachable = await cachedServerReachability(projectRoot, server.baseUrl, server.authToken);
+  const reachability = reachable ? "server is reachable" : "server is unreachable";
+  return {
+    contextLine: `Currently connected to: ${alias} at ${target} (${reachability}).`,
+    hint: "Check the selected server with `rig server status`, or switch with `rig server use <alias|local>`."
+  };
+}
+async function requestServerJson(context, pathname, init = {}) {
+  const server = await ensureServerForCli(context.projectRoot);
+  const headers = mergeHeaders(init.headers, server.authToken);
+  if (server.serverProjectRoot)
+    headers.set("x-rig-project-root", server.serverProjectRoot);
+  reportServerPhase(`${(init.method ?? "GET").toUpperCase()} ${pathname.split("?")[0]}\u2026`);
+  let response;
+  try {
+    response = await fetch(`${server.baseUrl}${pathname}`, {
+      ...init,
+      headers
+    });
+  } catch (error) {
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed: ${error instanceof Error ? error.message : String(error)}
+${failure.contextLine}`, 1, { hint: failure.hint });
+  }
+  const text = await response.text();
+  const payload = text.trim().length > 0 ? (() => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  })() : null;
+  if (!response.ok) {
+    const diagnostics = diagnosticMessage(payload);
+    const rawDetail = diagnostics ?? (text || response.statusText);
+    const detail = diagnostics ? rawDetail : rawDetail.split(`
+`).map((line) => line.trim()).find((line) => line.length > 0)?.slice(0, 200) ?? response.statusText;
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed (${response.status}): ${detail}
+${failure.contextLine}`, 1, { hint: failure.hint });
+  }
+  return payload;
+}
+var RESUMABLE_RUN_STATUSES = new Set([
+  "created",
+  "preparing",
+  "running",
+  "validating",
+  "reviewing",
+  "stopped",
+  "failed",
+  "needs-attention",
+  "needs_attention"
+]);
+
+// 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));
+function renderMicroDroneFrame(tick) {
+  const blade = MICRO_BLADES[tick % MICRO_BLADES.length];
+  const eye = EYE_FRAMES[Math.floor(tick / 2) % EYE_FRAMES.length];
+  return `${ink4("(")}${cyan(blade)}${ink4(")")}${bold(accent(eye))}${ink4("(")}${cyan(blade)}${ink4(")")}`;
+}
+
+// packages/cli/src/commands/_spinner.ts
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function createTtySpinner(input) {
+  const output = input.output ?? process.stdout;
+  const isTty = output.isTTY === true;
+  const frames = input.frames && input.frames.length > 0 ? input.frames : SPINNER_FRAMES;
+  let label = input.label;
+  let frame = 0;
+  let paused = false;
+  let stopped = false;
+  let lastPrintedLabel = "";
+  const render = () => {
+    if (stopped || paused)
+      return;
+    if (!isTty) {
+      if (label !== lastPrintedLabel) {
+        output.write(`${label}
+`);
+        lastPrintedLabel = label;
+      }
+      return;
+    }
+    frame = (frame + 1) % frames.length;
+    const glyph = frames[frame] ?? frames[0] ?? "";
+    output.write(`\r\x1B[2K${input.styleFrame ? input.styleFrame(glyph) : glyph} ${label}`);
+  };
+  const clearLine = () => {
+    if (isTty)
+      output.write("\r\x1B[2K");
+  };
+  render();
+  const timer = isTty ? setInterval(render, input.intervalMs ?? 120) : null;
+  return {
+    setLabel(next) {
+      label = next;
+      render();
+    },
+    pause() {
+      paused = true;
+      clearLine();
+    },
+    resume() {
+      if (stopped)
+        return;
+      paused = false;
+      render();
+    },
+    stop(finalLine) {
+      if (stopped)
+        return;
+      stopped = true;
+      if (timer)
+        clearInterval(timer);
+      clearLine();
+      if (finalLine)
+        output.write(`${finalLine}
+`);
+    }
+  };
+}
+
+// packages/cli/src/app/drone-ui.ts
+function droneNote(message, title) {
+  if (title)
+    console.log(` ${accentDim("\u25C7")} ${bold(ink2(title))}`);
+  for (const line of message.split(`
+`)) {
+    console.log(` ${ink4("\u2502")} ${line}`);
+  }
+}
+
+// packages/cli/src/commands/_cli-format.ts
+import pc from "picocolors";
+var themeDim = (value) => ink3(value);
+function shouldUseClackOutput() {
+  return Boolean(process.stdout.isTTY) && process.env.RIG_CLI_PLAIN_HELP !== "1";
+}
+function printFormattedOutput(message, options = {}) {
+  if (!shouldUseClackOutput()) {
+    console.log(message);
+    return;
+  }
+  droneNote(message, options.title);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(accent("\u25C6"))} ${pc.bold(title)}${subtitle ? themeDim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc.bold("Next"), ...steps.map((step) => `${accent("\u203A")} ${step}`)];
+}
+
+// packages/cli/src/commands/_async-ui.ts
+import pc2 from "picocolors";
+var DONE_SYMBOL = pc2.green("\u25C7");
+var FAIL_SYMBOL = pc2.red("\u25A0");
+var activeUpdate = null;
+async function withSpinner(label, work, options = {}) {
+  if (options.outputMode === "json") {
+    return work(() => {});
+  }
+  if (activeUpdate) {
+    const outer = activeUpdate;
+    outer(label);
+    return work(outer);
+  }
+  const output = options.output ?? process.stderr;
+  const isTty = output.isTTY === true;
+  let lastLabel = label;
+  if (!isTty) {
+    output.write(`${label}
+`);
+    const update2 = (next) => {
+      lastLabel = next;
+    };
+    activeUpdate = update2;
+    const previousListener2 = setServerPhaseListener(update2);
+    try {
+      return await work(update2);
+    } finally {
+      activeUpdate = null;
+      setServerPhaseListener(previousListener2);
+    }
+  }
+  const spinner = createTtySpinner({
+    label,
+    output,
+    frames: MICRO_DRONE_FRAMES,
+    styleFrame: (frame) => renderMicroDroneFrame(Math.max(0, MICRO_DRONE_FRAMES.indexOf(frame)))
+  });
+  const update = (next) => {
+    lastLabel = next;
+    spinner.setLabel(next);
+  };
+  activeUpdate = update;
+  const previousListener = setServerPhaseListener(update);
+  try {
+    const result = await work(update);
+    spinner.stop(options.doneLabel ? `${DONE_SYMBOL} ${options.doneLabel}` : undefined);
+    return result;
+  } catch (error) {
+    spinner.stop(`${FAIL_SYMBOL} ${lastLabel}`);
+    throw error;
+  } finally {
+    activeUpdate = null;
+    setServerPhaseListener(previousListener);
+  }
+}
+
+// packages/cli/src/commands/_help-catalog.ts
+import pc3 from "picocolors";
+var TOP_LEVEL_SECTIONS = [
+  {
+    title: "Pi console",
+    subtitle: "the operator surface \u2014 every attach opens the run's FULL Pi session",
+    commands: [
+      { command: "rig run attach <run-id>", description: "Open the run's Pi console: complete transcript (live AND finished runs), worker turns streaming in live." },
+      { command: "type a message", description: "Inside the console, plain text steers the worker mid-turn \u2014 it lands in the agent's context, not a local model." },
+      { command: "!<command>", description: "Inside the console, runs shell in the WORKER's workspace; output streams back into the transcript." },
+      { command: "/<command>", description: "The palette includes the WORKER session's slash commands ([worker]-tagged) next to /rig." },
+      { command: "/rig abort | /rig stop", description: "Abort the worker's current turn, or stop the whole run, from inside the console." },
+      { command: "rig run steer <id> --message <text>", description: "Steer without attaching \u2014 queue a message; the worker picks it up within seconds." }
+    ]
+  },
+  {
+    title: "Start here",
+    subtitle: "one-time setup, pick a server",
+    commands: [
+      { command: "rig init", description: "Wizard: config, GitHub auth, task source, server, Pi wiring." },
+      { command: "rig server use <alias|local>", description: "Pick which Rig server owns this repo (`rig server list` to see them)." },
+      { command: "rig server status", description: "Show the selected server for this repo." }
+    ]
+  },
+  {
+    title: "Work",
+    subtitle: "find a task, put an agent on it, answer what it asks",
+    commands: [
+      { command: "rig task list", description: "What's on the board (from the selected source/server)." },
+      { command: "rig task run --next", description: "Dispatch an agent on the next ready task; interactive mode drops you into its Pi console." },
+      { command: "rig run status", description: "Active and recent runs at a glance." },
+      { command: "rig run attach <id> --follow", description: "Same as plain attach \u2014 the Pi console is always the interactive surface." },
+      { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." }
+    ]
+  },
+  {
+    title: "Watch",
+    subtitle: "fleet metrics and per-task forensics",
+    commands: [
+      { command: "rig stats [--since 7d]", description: "Fleet metrics: completion/failure rates, median run time, steering, stalls." },
+      { command: "rig inspect logs --task <id>", description: "Latest run log for a task." },
+      { command: "rig inspect diff --task <id>", description: "Changed files for a task." }
+    ]
+  },
+  {
+    title: "Unblock",
+    subtitle: "diagnose wiring, fix auth",
+    commands: [
+      { command: "rig doctor", description: "Check every part of the wiring \u2014 run this when anything feels off." },
+      { command: "rig github auth status", description: "GitHub auth state on the selected server." }
+    ]
+  },
+  {
+    title: "Extend",
+    subtitle: "plugins contribute validators, hooks, task sources, commands",
+    commands: [
+      { command: "rig plugin list", description: "What the rig.config.ts plugins contribute." },
+      { command: "rig plugin run <command-id>", description: "Execute a plugin-contributed CLI command." }
+    ]
+  }
+];
+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."]
+  },
+  {
+    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|@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: "ready", description: "List task IDs that are runnable now." },
+      { 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: "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. `attach` opens the Pi console \u2014 the full worker session, live.",
+    usage: ["rig run <list|status|show|attach|steer|stop|resume|restart> [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>", description: "Open the run's Pi console \u2014 see 'Inside the console' below. Works on live AND finished runs.", primary: true },
+      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching \u2014 delivered into the agent's context within seconds.", primary: true },
+      { command: "stop [<run-id>|--run <id>]", description: "Request stop for one run or local active runs.", primary: true },
+      { command: "resume [<run-id>]", description: "Resume an interrupted run on the selected server (defaults to the most recent resumable)." },
+      { command: "restart [<run-id>]", description: "Re-dispatch a run from a clean runtime, reopening its Pi session where possible." },
+      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events (scripts; humans should attach)." },
+      { command: "replay <run-id>|--run <id> [--with-session]", description: "Print the run's consolidated run.jsonl as a merged timeline; --with-session interleaves the Pi session log." },
+      { command: "delete|cleanup", description: "Remove completed run records/artifacts." }
+    ],
+    examples: [
+      "rig run attach <run-id>          # full session console \u2014 live mirror, steering, worker shell",
+      "rig run steer <run-id> --message 'focus on the failing test first'",
+      "rig run list",
+      "rig run show <run-id>",
+      "rig run stop <run-id>"
+    ],
+    next: [
+      "Inside the console: the run's COMPLETE transcript loads on open (finished runs too), and new worker turns stream in live.",
+      "Inside the console: plain text = steering into the worker's context \xB7 !<cmd> = shell in the WORKER workspace \xB7 /<cmd> includes the worker session's commands \xB7 /rig abort stops the current turn.",
+      "The console is read-write but remote-only: nothing runs on your machine; the worker keeps running when you exit.",
+      "Use `rig task run --next` to create a new run; interactive mode drops you straight into its console.",
+      "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: "stats",
+    summary: "Fleet metrics computed from on-disk run journals (no server required).",
+    usage: ["rig stats [show] [--since <7d|30d|ISO date>]"],
+    commands: [
+      { command: "show [--since <window>]", description: "Total runs, completion/failure/needs-attention rates, median run time, steering, stalls, approvals.", primary: true }
+    ],
+    examples: [
+      "rig stats",
+      "rig stats --since 7d",
+      "rig stats --since 2026-06-01 --json"
+    ],
+    next: ["Inspect outliers with `rig run list` and `rig run show <run-id>`.", "Use `--json` for the schema'd envelope (see docs/cli-json.md)."]
+  },
+  {
+    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).", primary: true },
+      { command: "artifacts --task <id>", description: "List the task's completion artifacts.", primary: true },
+      { command: "failures --task <id>", description: "Recorded failures for a task.", primary: true },
+      { command: "diff --task <id>", description: "Changed files for a task.", primary: true },
+      { command: "graph", description: "Task dependency graph." },
+      { command: "audit", description: "Controlled-command audit trail." }
+    ],
+    examples: ["rig inspect logs --task <id>", "rig inspect diff --task <id>"],
+    next: ["Use `rig stats` for fleet-level metrics across runs."]
+  },
+  {
+    name: "repo",
+    summary: "Repository sync/baseline helpers for the Rig-managed checkout.",
+    usage: ["rig repo <sync|reset-baseline>"],
+    commands: [
+      { command: "sync", description: "Sync project repository state.", primary: true },
+      { command: "reset-baseline", description: "Reset the managed baseline for the repo." }
+    ],
+    examples: ["rig repo sync"]
+  },
+  {
+    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.", primary: true },
+      { command: "validate --task <id>", description: "Run plugin-contributed validators for a task.", primary: true },
+      { command: "run <command-id> [args...]", description: "Execute a plugin-contributed CLI command (also callable as `rig <command-id>`)." }
+    ],
+    examples: ["rig plugin list", "rig plugin run <command-id>"]
+  },
+  {
+    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 --demo", description: "Offline demo project: files task source + 3 sample tasks, zero GitHub.", 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 --demo",
+      "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: "setup", summary: "Bootstrap/check local setup.", usage: ["rig setup <bootstrap|check|preflight>"], commands: [{ command: "bootstrap|check|preflight", description: "Setup helpers." }] },
+  { name: "profile", summary: "Runtime profile/model defaults.", usage: ["rig profile <show|set>"], commands: [{ command: "show", description: "Show active profile." }] },
+  {
+    name: "review",
+    summary: "Inspect or change completion review gate policy.",
+    usage: ["rig review <show|set>"],
+    commands: [
+      { command: "show", description: "Show current review gate settings." },
+      { command: "set <off|advisory|required> [--provider greptile]", description: "Change review strictness/provider." }
+    ],
+    examples: ["rig review show", "rig review set required --provider greptile"],
+    next: ["Use `rig inbox approvals` for blocked run handoffs."]
+  },
+  {
+    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: "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 pc3.bold(pc3.cyan(title));
+}
+function commandLine(command, description) {
+  const commandColumn = command.length >= 38 ? `${command}  ` : command.padEnd(38);
+  return `${pc3.dim("\u2502")} ${pc3.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}`,
+    "",
+    pc3.bold("Usage"),
+    ...group.usage.map((line) => `  ${line}`),
+    "",
+    pc3.bold("Commands"),
+    ...group.commands.map((entry) => commandLine(entry.command, entry.description))
+  ];
+  if (group.examples?.length) {
+    lines.push("", pc3.bold("Examples"), ...group.examples.map((line) => `  ${pc3.dim("$")} ${line}`));
+  }
+  if (group.next?.length) {
+    lines.push("", pc3.bold("Next steps"), ...group.next.map((line) => `  ${pc3.dim("\u203A")} ${line}`));
+  }
+  if (group.advanced?.length) {
+    lines.push("", pc3.bold("Compatibility / advanced"), ...group.advanced.map((line) => `  ${pc3.dim("\u203A")} ${line}`));
+  }
+  return lines.join(`
+`);
+}
+function renderTopLevelHelp() {
+  return [
+    `${heading("rig")} ${pc3.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
+    pc3.dim("The loop: pick a task, dispatch an agent, open its Pi console (`rig run attach <id>`) to watch and steer it live, clear inbox gates, merge."),
+    "",
+    ...TOP_LEVEL_SECTIONS.flatMap((section) => [
+      `${pc3.bold(pc3.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc3.dim(section.subtitle)}`,
+      renderCommandBlock(section.commands),
+      ""
+    ]),
+    pc3.dim("More: `rig help --advanced` for dev/compatibility commands; `rig <group> --help` for rich per-group help; `rig --version` for the installed version."),
+    "",
+    pc3.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 printGroupHelpDocument(groupName) {
+  console.log(renderGroupHelp(groupName) ?? renderTopLevelHelp());
+}
+
+// packages/cli/src/commands/stats.ts
+var DAY_MS = 24 * 60 * 60 * 1000;
+function parseSinceOption(value, now = new Date) {
+  if (!value?.trim())
+    return null;
+  const trimmed = value.trim();
+  const relative = trimmed.match(/^(\d+)d$/i);
+  if (relative?.[1]) {
+    return new Date(now.getTime() - Number.parseInt(relative[1], 10) * DAY_MS);
+  }
+  const parsed = Date.parse(trimmed);
+  if (!Number.isFinite(parsed)) {
+    throw new CliError(`Invalid --since value: ${trimmed}. Use <n>d (e.g. 7d, 30d) or an ISO date (e.g. 2026-06-01).`, 2, { hint: "Re-run with a valid window, e.g. `rig stats --since 7d` or `rig stats --since 2026-06-01`." });
+  }
+  return new Date(parsed);
+}
+function formatPercent(value) {
+  if (value === null)
+    return "\u2014";
+  return `${(value * 100).toFixed(1)}%`;
+}
+function formatDuration(ms) {
+  if (ms === null)
+    return "\u2014";
+  if (ms < 1000)
+    return `${Math.round(ms)}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60)
+    return `${seconds.toFixed(0)}s`;
+  const minutes = seconds / 60;
+  if (minutes < 60)
+    return `${Math.floor(minutes)}m ${Math.round(seconds % 60)}s`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${Math.round(minutes % 60)}m`;
+}
+function formatStatsReport(stats) {
+  const window = stats.since ? `since ${stats.since}` : "all time";
+  const rows = [
+    ["runs", String(stats.totalRuns)],
+    ["completed", `${stats.completedRuns} (${formatPercent(stats.completionRate)})`],
+    ["failed", `${stats.failedRuns} (${formatPercent(stats.failureRate)})`],
+    ["needs attn", `${stats.needsAttentionRuns} (${formatPercent(stats.needsAttentionRate)})`],
+    ["median time", formatDuration(stats.medianCompletionMs)],
+    ["steering", `${stats.steeringTotal} total \xB7 ${stats.steeringPerRun === null ? "\u2014" : stats.steeringPerRun.toFixed(2)}/run`],
+    ["stalls", String(stats.stallTotal)],
+    ["approvals", `${stats.approvalsRequested} requested \xB7 ${stats.approvalsApproved} approved \xB7 ${stats.approvalsRejected} rejected \xB7 ${stats.approvalsPending} pending`]
+  ];
+  const keyWidth = Math.max(...rows.map(([key]) => key.length));
+  const lines = [
+    formatSection("Fleet stats", window),
+    ...rows.map(([key, value]) => `${pc4.dim("\u2502")} ${pc4.dim(key.padEnd(keyWidth + 2))} ${value}`)
+  ];
+  const otherStatuses = Object.entries(stats.statusCounts).filter(([status]) => !["completed", "failed", "needs-attention"].includes(status)).sort(([, left], [, right]) => right - left);
+  if (otherStatuses.length > 0) {
+    lines.push(`${pc4.dim("\u2502")} ${pc4.dim("other".padEnd(keyWidth + 2))} ${otherStatuses.map(([status, count]) => `${status}:${count}`).join(" ")}`);
+  }
+  lines.push("", ...formatNextSteps([
+    "Inspect a run: `rig run list` then `rig run show <run-id>`",
+    "Narrow the window: `rig stats --since 7d`"
+  ]));
+  return lines.join(`
+`);
+}
+async function executeStats(context, args) {
+  const [first, ...rest] = args;
+  const isImplicitShow = first === undefined || first.startsWith("-");
+  const command = isImplicitShow ? "show" : first;
+  const pending = isImplicitShow ? args : rest;
+  switch (command) {
+    case "show": {
+      const sinceResult = takeOption(pending, "--since");
+      requireNoExtraArgs(sinceResult.rest, "rig stats [show] [--since <7d|30d|ISO date>]");
+      const since = parseSinceOption(sinceResult.value);
+      const remoteStats = isRemoteConnectionSelected(context.projectRoot);
+      const stats = await withSpinner(remoteStats ? "Computing fleet stats on the server\u2026" : "Scanning local run state\u2026", async () => remoteStats ? await requestServerJson(context, `/api/stats${since ? `?since=${encodeURIComponent(since.toISOString())}` : ""}`) : computeRigStats(context.projectRoot, { since }), { outputMode: context.outputMode });
+      if (context.outputMode === "text") {
+        printFormattedOutput(formatStatsReport(stats));
+      }
+      return {
+        ok: true,
+        group: "stats",
+        command: "show",
+        details: stats
+      };
+    }
+    case "help": {
+      if (context.outputMode === "text")
+        printGroupHelpDocument("stats");
+      return { ok: true, group: "stats", command: "help" };
+    }
+    default:
+      throw new CliError(`Unknown stats command: ${command}. Use \`rig stats\` or \`rig stats show [--since <7d|30d|ISO date>]\`.`, 2, { hint: "Run `rig stats --since 7d` for the last week, or `rig stats --help` for usage." });
+  }
+}
+export {
+  parseSinceOption,
+  formatStatsReport,
+  executeStats,
+  computeRigStats
+};