@h-rig/cli-surface-plugin 0.0.6-alpha.157 → 0.0.6-alpha.159

package/dist/src/commands/stats.js

@@ -1,20 +1,661 @@
 // @bun
 // packages/cli-surface-plugin/src/commands/stats.ts
-import { computeStats } from "@rig/run-worker/runs";
+import { RUN_READ_MODEL } from "@rig/contracts";
+import { defineCapability } from "@rig/core/capability";
+import { requireCapabilityForRoot } from "@rig/core/capability-loaders";
 
 // packages/cli-surface-plugin/src/runner.ts
-import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
-import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+import { EventBus } from "@rig/core/runtime-events";
+import { CliError as RuntimeCliError } from "@rig/contracts";
 
+// packages/cli-surface-plugin/src/control-plane/guard.ts
+import { optimizeNextInvocation } from "bun:jsc";
+import { existsSync, readFileSync, statSync } from "fs";
+import { resolve } from "path";
+
+// packages/cli-surface-plugin/src/control-plane/scope.ts
+import { getScopeRules } from "@rig/core/scope-rules";
+var scopeRegexCache = new Map;
+function unique(values) {
+  return [...new Set(values)];
+}
+function normalizeRelativeScopePath(inputPath) {
+  let normalized = inputPath.replace(/^\.\//, "");
+  const rules = getScopeRules();
+  if (rules?.stripPrefixes) {
+    for (const prefix of rules.stripPrefixes) {
+      if (normalized.startsWith(prefix)) {
+        normalized = normalized.slice(prefix.length);
+      }
+    }
+  }
+  return normalized;
+}
+function normalizePathToScope(projectRoot, monorepoRoot, inputPath) {
+  let normalized = inputPath.replace(/^\.\//, "");
+  if (normalized.startsWith(projectRoot + "/")) {
+    normalized = normalized.slice(projectRoot.length + 1);
+  }
+  if (normalized.startsWith(monorepoRoot + "/")) {
+    normalized = normalized.slice(monorepoRoot.length + 1);
+  }
+  return normalizeRelativeScopePath(normalized);
+}
+function scopeGlobToRegex(glob) {
+  const cached = scopeRegexCache.get(glob);
+  if (cached) {
+    return cached;
+  }
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "__GLOBSTAR__").replace(/\*/g, "[^/]*").replace(/__GLOBSTAR__/g, ".*");
+  const compiled = new RegExp(`^${escaped}$`);
+  scopeRegexCache.set(glob, compiled);
+  return compiled;
+}
+function scopeMatches(path, scopes) {
+  const pathVariants = unique([path, normalizeRelativeScopePath(path)]);
+  for (const scope of scopes) {
+    const scopeVariants = unique([scope, normalizeRelativeScopePath(scope)]);
+    for (const candidatePath of pathVariants) {
+      for (const candidateScope of scopeVariants) {
+        if (candidatePath === candidateScope || scopeGlobToRegex(candidateScope).test(candidatePath)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+// packages/cli-surface-plugin/src/control-plane/guard.ts
+import {
+  POLICY_VERSION
+} from "@rig/contracts";
+var DEFAULT_SCOPE = {
+  fail_closed: true,
+  harness_paths_exempt: true,
+  runtime_paths_exempt: true
+};
+var DEFAULT_SANDBOX = {
+  mode: "enforce",
+  network: true,
+  read_deny: [],
+  write_allow_from_runtime: true
+};
+var DEFAULT_ISOLATION = {
+  default_mode: "worktree",
+  repo_symlink_fallback: false,
+  strict_provisioning: true,
+  fail_closed_on_provision_error: true
+};
+var DEFAULT_COMPLETION = {
+  derive_checks_from_scope: true,
+  checks: [],
+  typescript_config_probe: ["tsconfig.json"],
+  eslint_config_probe: [".eslintrc.js", ".eslintrc.json", "eslint.config.js"]
+};
+var DEFAULT_RUNTIME_IMAGE = {
+  deps: {
+    monorepo_install: false,
+    hp_next_install: false
+  },
+  plugins_require_binaries: true
+};
+var DEFAULT_RUNTIME_SNAPSHOT = {
+  enabled: true
+};
+function defaultPolicy() {
+  return {
+    version: POLICY_VERSION,
+    mode: "enforce",
+    scope: { ...DEFAULT_SCOPE },
+    rules: [],
+    sandbox: { ...DEFAULT_SANDBOX },
+    isolation: { ...DEFAULT_ISOLATION },
+    completion: { ...DEFAULT_COMPLETION },
+    runtime_image: {
+      deps: { ...DEFAULT_RUNTIME_IMAGE.deps },
+      plugins_require_binaries: DEFAULT_RUNTIME_IMAGE.plugins_require_binaries
+    },
+    runtime_snapshot: { ...DEFAULT_RUNTIME_SNAPSHOT }
+  };
+}
+var policyCache = null;
+var policyCachePath = null;
+var seededPolicyConfig = null;
+var compiledRegexCache = new Map;
+function loadPolicy(projectRoot) {
+  if (seededPolicyConfig) {
+    return seededPolicyConfig;
+  }
+  const configPath = resolve(projectRoot, "rig/policy/policy.json");
+  if (!existsSync(configPath)) {
+    return defaultPolicy();
+  }
+  let mtimeMs;
+  try {
+    mtimeMs = statSync(configPath).mtimeMs;
+  } catch {
+    return defaultPolicy();
+  }
+  if (policyCache && policyCachePath === configPath && policyCache.mtimeMs === mtimeMs) {
+    return policyCache.config;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return defaultPolicy();
+  }
+  const config = mergeWithDefaults(parsed);
+  policyCache = { mtimeMs, config };
+  policyCachePath = configPath;
+  return config;
+}
+function mergeWithDefaults(parsed) {
+  const base = defaultPolicy();
+  if (typeof parsed.mode === "string" && isValidMode(parsed.mode)) {
+    base.mode = parsed.mode;
+  }
+  if (parsed.scope && typeof parsed.scope === "object" && !Array.isArray(parsed.scope)) {
+    const s = parsed.scope;
+    if (typeof s.fail_closed === "boolean")
+      base.scope.fail_closed = s.fail_closed;
+    if (typeof s.harness_paths_exempt === "boolean")
+      base.scope.harness_paths_exempt = s.harness_paths_exempt;
+    if (typeof s.runtime_paths_exempt === "boolean")
+      base.scope.runtime_paths_exempt = s.runtime_paths_exempt;
+  }
+  if (Array.isArray(parsed.rules)) {
+    base.rules = precompilePolicyRuleRegexes(parsed.rules.filter(isValidRule));
+  }
+  if (Array.isArray(parsed.deny) && base.rules.length === 0) {
+    base.rules = precompilePolicyRuleRegexes(migrateLegacyDeny(parsed.deny));
+  }
+  if (parsed.sandbox && typeof parsed.sandbox === "object" && !Array.isArray(parsed.sandbox)) {
+    const sb = parsed.sandbox;
+    if (typeof sb.mode === "string" && isValidMode(sb.mode))
+      base.sandbox.mode = sb.mode;
+    if (typeof sb.network === "boolean")
+      base.sandbox.network = sb.network;
+    if (Array.isArray(sb.read_deny))
+      base.sandbox.read_deny = sb.read_deny.filter((v) => typeof v === "string");
+    if (typeof sb.write_allow_from_runtime === "boolean")
+      base.sandbox.write_allow_from_runtime = sb.write_allow_from_runtime;
+  }
+  if (parsed.isolation && typeof parsed.isolation === "object" && !Array.isArray(parsed.isolation)) {
+    const iso = parsed.isolation;
+    if (iso.default_mode === "worktree")
+      base.isolation.default_mode = iso.default_mode;
+    if (typeof iso.repo_symlink_fallback === "boolean")
+      base.isolation.repo_symlink_fallback = iso.repo_symlink_fallback;
+    if (typeof iso.strict_provisioning === "boolean")
+      base.isolation.strict_provisioning = iso.strict_provisioning;
+    if (typeof iso.fail_closed_on_provision_error === "boolean")
+      base.isolation.fail_closed_on_provision_error = iso.fail_closed_on_provision_error;
+  }
+  if (parsed.completion && typeof parsed.completion === "object" && !Array.isArray(parsed.completion)) {
+    const comp = parsed.completion;
+    if (typeof comp.derive_checks_from_scope === "boolean")
+      base.completion.derive_checks_from_scope = comp.derive_checks_from_scope;
+    if (Array.isArray(comp.checks))
+      base.completion.checks = comp.checks.filter((v) => typeof v === "string");
+    if (Array.isArray(comp.typescript_config_probe))
+      base.completion.typescript_config_probe = comp.typescript_config_probe.filter((v) => typeof v === "string");
+    if (Array.isArray(comp.eslint_config_probe))
+      base.completion.eslint_config_probe = comp.eslint_config_probe.filter((v) => typeof v === "string");
+  }
+  if (parsed.runtime_image && typeof parsed.runtime_image === "object" && !Array.isArray(parsed.runtime_image)) {
+    const runtimeImage = parsed.runtime_image;
+    if (runtimeImage.deps && typeof runtimeImage.deps === "object" && !Array.isArray(runtimeImage.deps)) {
+      const deps = runtimeImage.deps;
+      if (typeof deps.monorepo_install === "boolean") {
+        base.runtime_image.deps.monorepo_install = deps.monorepo_install;
+      }
+      if (typeof deps.hp_next_install === "boolean") {
+        base.runtime_image.deps.hp_next_install = deps.hp_next_install;
+      }
+    }
+    if (typeof runtimeImage.plugins_require_binaries === "boolean") {
+      base.runtime_image.plugins_require_binaries = runtimeImage.plugins_require_binaries;
+    }
+  }
+  if (parsed.runtime_snapshot && typeof parsed.runtime_snapshot === "object" && !Array.isArray(parsed.runtime_snapshot)) {
+    const runtimeSnapshot = parsed.runtime_snapshot;
+    if (typeof runtimeSnapshot.enabled === "boolean") {
+      base.runtime_snapshot.enabled = runtimeSnapshot.enabled;
+    }
+  }
+  return base;
+}
+function isValidMode(value) {
+  return value === "off" || value === "observe" || value === "enforce";
+}
+function isValidRule(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const r = value;
+  return typeof r.id === "string" && typeof r.category === "string" && r.match != null && typeof r.match === "object";
+}
+function migrateLegacyDeny(deny) {
+  const rules = [];
+  for (const entry of deny) {
+    if (typeof entry.id !== "string")
+      continue;
+    const match = {};
+    if (typeof entry.pattern === "string")
+      match.pattern = entry.pattern;
+    if (typeof entry.regex === "string")
+      match.regex = entry.regex;
+    if (!match.pattern && !match.regex)
+      continue;
+    rules.push({
+      id: entry.id,
+      category: "command",
+      match,
+      action: "block",
+      ...typeof entry.description === "string" ? { description: entry.description } : {}
+    });
+  }
+  return rules;
+}
+function precompilePolicyRuleRegexes(rules) {
+  return rules.map((rule) => {
+    const compiledRegex = rule.match.regex ? compileSafeRegex(rule.match.regex, `rules.${rule.id}.match.regex`, true) : undefined;
+    const compiledUnlessRegex = rule.unless?.regex ? compileSafeRegex(rule.unless.regex, `rules.${rule.id}.unless.regex`, true) : undefined;
+    return {
+      ...rule,
+      ...compiledRegex ? { compiledRegex } : {},
+      ...compiledUnlessRegex ? { compiledUnlessRegex } : {}
+    };
+  });
+}
+function getRegexUnsafeReason(pattern) {
+  if (pattern.length > 512) {
+    return "pattern exceeds max safe length (512 chars)";
+  }
+  if (/\\[1-9]/.test(pattern)) {
+    return "pattern uses backreferences";
+  }
+  if (/\((?:[^()\\]|\\.)*[+*](?:[^()\\]|\\.)*\)\s*[*+{]/.test(pattern)) {
+    return "pattern contains nested quantifiers";
+  }
+  if (/\((?:[^()\\]|\\.)*\.\\?[+*](?:[^()\\]|\\.)*\)\s*[*+{]/.test(pattern)) {
+    return "pattern contains nested broad quantifiers";
+  }
+  return null;
+}
+function compileSafeRegex(pattern, sourceLabel, logOnFailure) {
+  const cached = compiledRegexCache.get(pattern);
+  if (cached !== undefined) {
+    return cached ?? undefined;
+  }
+  const unsafeReason = getRegexUnsafeReason(pattern);
+  if (unsafeReason) {
+    if (logOnFailure) {
+      console.warn(`[policy] Skipping unsafe regex in ${sourceLabel}: ${unsafeReason}`);
+    }
+    compiledRegexCache.set(pattern, null);
+    return;
+  }
+  try {
+    const compiled = new RegExp(pattern);
+    compiledRegexCache.set(pattern, compiled);
+    return compiled;
+  } catch (error) {
+    if (logOnFailure) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[policy] Skipping invalid regex in ${sourceLabel}: ${message}`);
+    }
+    compiledRegexCache.set(pattern, null);
+    return;
+  }
+}
+function matchRule(rule, input) {
+  const { match } = rule;
+  if (match.pattern && input.includes(match.pattern)) {
+    return true;
+  }
+  if (match.regex) {
+    const compiled = rule.compiledRegex || compileSafeRegex(match.regex, `rules.${rule.id}.match.regex`, false);
+    if (!compiled) {
+      return false;
+    }
+    try {
+      return compiled.test(input);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function matchRuleUnless(rule, command, taskId) {
+  if (!rule.unless)
+    return false;
+  if (rule.unless.regex) {
+    const compiled = rule.compiledUnlessRegex || compileSafeRegex(rule.unless.regex, `rules.${rule.id}.unless.regex`, false);
+    if (!compiled) {
+      return false;
+    }
+    try {
+      if (compiled.test(command))
+        return true;
+    } catch {}
+  }
+  if (rule.unless.task_in && taskId) {
+    if (rule.unless.task_in.includes(taskId))
+      return true;
+  }
+  return false;
+}
+function resolveAction(mode, matched) {
+  if (matched.length === 0)
+    return "allow";
+  if (mode === "off")
+    return "allow";
+  if (mode === "observe")
+    return "warn";
+  return "block";
+}
+function resolveAbsolutePath(projectRoot, rawPath) {
+  if (rawPath.startsWith("/"))
+    return resolve(rawPath);
+  return resolve(projectRoot, rawPath);
+}
+function isHarnessPath(projectRoot, rawPath) {
+  const absPath = resolveAbsolutePath(projectRoot, rawPath);
+  const managedRoots = [
+    resolve(projectRoot, "rig"),
+    resolve(projectRoot, ".rig"),
+    resolve(projectRoot, "artifacts")
+  ];
+  return managedRoots.some((root) => absPath === root || absPath.startsWith(root + "/"));
+}
+function isRuntimePath(projectRoot, rawPath, taskWorkspace) {
+  const absPath = resolveAbsolutePath(projectRoot, rawPath);
+  if (taskWorkspace) {
+    const workspaceRigRoot = resolve(taskWorkspace, ".rig");
+    const workspaceArtifactsRoot = resolve(taskWorkspace, "artifacts");
+    if (absPath === workspaceRigRoot || absPath.startsWith(workspaceRigRoot + "/") || absPath === workspaceArtifactsRoot || absPath.startsWith(workspaceArtifactsRoot + "/")) {
+      return true;
+    }
+  }
+  const runtimeRoot = resolve(projectRoot, ".rig/runtime/agents");
+  return absPath === runtimeRoot || absPath.startsWith(runtimeRoot + "/");
+}
+function isTestFile(path) {
+  return /\.(test|spec)\.(ts|tsx|js|jsx)$/.test(path) || /\/(__tests__|tests|test)\//.test(path);
+}
+function evaluate(context) {
+  const policy = loadPolicy(context.projectRoot);
+  switch (context.evaluation.type) {
+    case "tool-call":
+      return evaluateToolCall(policy, context);
+    case "command":
+      return evaluateCommand(policy, context);
+    case "content-write":
+      return evaluateContent(policy, context);
+    case "file-access":
+      return evaluateScope(policy, context, context.evaluation.file_path, context.evaluation.access);
+  }
+}
+function evaluateScope(policy, context, filePath, access) {
+  const allowed = () => ({
+    allowed: true,
+    matchedRules: [],
+    action: "allow",
+    failClosed: false
+  });
+  if (policy.scope.harness_paths_exempt && isHarnessPath(context.projectRoot, filePath)) {
+    return allowed();
+  }
+  if (policy.scope.runtime_paths_exempt && isRuntimePath(context.projectRoot, filePath, context.taskWorkspace)) {
+    return allowed();
+  }
+  if (!context.taskId) {
+    if (access === "write" && policy.scope.fail_closed) {
+      return {
+        allowed: false,
+        matchedRules: [],
+        action: resolveAction(policy.mode, [{ id: "scope:no-task", category: "command", reason: "No active task; fail-closed for write operations" }]),
+        failClosed: true
+      };
+    }
+    return allowed();
+  }
+  const scopes = context.taskScopes || [];
+  if (scopes.length === 0) {
+    return allowed();
+  }
+  if (context.taskWorkspace && context.taskWorkspace !== context.projectRoot && filePath.startsWith("/")) {
+    const absPath = resolve(filePath);
+    if (!absPath.startsWith(context.taskWorkspace + "/") && !isHarnessPath(context.projectRoot, filePath)) {
+      const reason2 = `Absolute path '${filePath}' is outside task runtime boundary. Allowed root: ${context.taskWorkspace}`;
+      const matched2 = [{ id: "scope:workspace-boundary", category: "command", reason: reason2 }];
+      return {
+        allowed: policy.mode !== "enforce",
+        matchedRules: matched2,
+        action: resolveAction(policy.mode, matched2),
+        failClosed: false
+      };
+    }
+  }
+  const monorepoRoot = context.monorepoRoot || process.env.MONOREPO_ROOT?.trim() || context.taskWorkspace || context.projectRoot;
+  let normalizedPath = filePath;
+  if (context.taskWorkspace && context.taskWorkspace !== context.projectRoot && filePath.startsWith(context.taskWorkspace + "/")) {
+    normalizedPath = filePath.slice(context.taskWorkspace.length + 1);
+  }
+  normalizedPath = normalizePathToScope(context.projectRoot, monorepoRoot, normalizedPath);
+  if (scopeMatches(filePath, scopes) || scopeMatches(normalizedPath, scopes)) {
+    return allowed();
+  }
+  const reason = `File '${filePath}' (normalized: '${normalizedPath}') is outside scope of task ${context.taskId}`;
+  const matched = [{ id: "scope:out-of-scope", category: "command", reason }];
+  return {
+    allowed: policy.mode !== "enforce",
+    matchedRules: matched,
+    action: resolveAction(policy.mode, matched),
+    failClosed: false
+  };
+}
+function evaluateCommand(policy, context) {
+  const evaluation = context.evaluation;
+  if (evaluation.type !== "command") {
+    return { allowed: true, matchedRules: [], action: "allow", failClosed: false };
+  }
+  const command = evaluation.command;
+  const matchedRules = [];
+  for (const rule of policy.rules) {
+    if (rule.category !== "command")
+      continue;
+    if (!matchRule(rule, command))
+      continue;
+    if (matchRuleUnless(rule, command, context.taskId))
+      continue;
+    matchedRules.push({
+      id: rule.id,
+      category: rule.category,
+      ...rule.description !== undefined ? { description: rule.description } : {},
+      reason: rule.description || `Matched rule ${rule.id}`
+    });
+  }
+  const writeTarget = extractWriteTarget(command);
+  if (writeTarget && !/^\/dev\//.test(writeTarget) && !/^\/proc\//.test(writeTarget)) {
+    const scopeResult = evaluateScope(policy, context, writeTarget, "write");
+    if (!scopeResult.allowed || scopeResult.matchedRules.length > 0) {
+      matchedRules.push(...scopeResult.matchedRules);
+    }
+  }
+  const action = resolveAction(policy.mode, matchedRules);
+  return {
+    allowed: action !== "block",
+    matchedRules,
+    action,
+    failClosed: false
+  };
+}
+function extractWriteTarget(command) {
+  const redirect = command.match(/>>?\s+([^\s;|&]+)/);
+  if (redirect?.[1])
+    return redirect[1];
+  const tee = command.match(/tee\s+(-a\s+)?([^\s;|&]+)/);
+  if (tee?.[2])
+    return tee[2];
+  return "";
+}
+function evaluateContent(policy, context) {
+  const evaluation = context.evaluation;
+  if (evaluation.type !== "content-write") {
+    return { allowed: true, matchedRules: [], action: "allow", failClosed: false };
+  }
+  const { content, file_path } = evaluation;
+  const matchedRules = [];
+  const scopeResult = evaluateScope(policy, context, file_path, "write");
+  if (scopeResult.matchedRules.length > 0) {
+    matchedRules.push(...scopeResult.matchedRules);
+  }
+  for (const rule of policy.rules) {
+    if (rule.category !== "content" && rule.category !== "import" && rule.category !== "test-integrity")
+      continue;
+    if (rule.applies_to === "test-files" && !isTestFile(file_path))
+      continue;
+    if (!matchRule(rule, content))
+      continue;
+    if (matchRuleUnless(rule, content, context.taskId))
+      continue;
+    matchedRules.push({
+      id: rule.id,
+      category: rule.category,
+      ...rule.description !== undefined ? { description: rule.description } : {},
+      reason: rule.description || `Matched rule ${rule.id}`
+    });
+  }
+  const action = resolveAction(policy.mode, matchedRules);
+  return {
+    allowed: action !== "block",
+    matchedRules,
+    action,
+    failClosed: false
+  };
+}
+function evaluateToolCall(policy, context) {
+  const evaluation = context.evaluation;
+  if (evaluation.type !== "tool-call") {
+    return { allowed: true, matchedRules: [], action: "allow", failClosed: false };
+  }
+  const { tool_name, tool_input } = evaluation;
+  const allMatched = [];
+  const filePaths = extractFilePathsFromToolInput(tool_name, tool_input);
+  for (const fp of filePaths) {
+    const access = isWriteTool(tool_name) ? "write" : "read";
+    const scopeResult = evaluateScope(policy, context, fp, access);
+    if (scopeResult.matchedRules.length > 0) {
+      allMatched.push(...scopeResult.matchedRules);
+    }
+  }
+  const content = extractContentFromToolInput(tool_input);
+  if (content) {
+    const filePath = filePaths[0] || "";
+    const contentContext = {
+      ...context,
+      evaluation: { type: "content-write", file_path: filePath, content }
+    };
+    const contentPolicy = loadPolicy(context.projectRoot);
+    for (const rule of contentPolicy.rules) {
+      if (rule.category !== "content" && rule.category !== "import" && rule.category !== "test-integrity")
+        continue;
+      if (rule.applies_to === "test-files" && !isTestFile(filePath))
+        continue;
+      if (!matchRule(rule, content))
+        continue;
+      if (matchRuleUnless(rule, content, context.taskId))
+        continue;
+      allMatched.push({
+        id: rule.id,
+        category: rule.category,
+        ...rule.description !== undefined ? { description: rule.description } : {},
+        reason: rule.description || `Matched rule ${rule.id}`
+      });
+    }
+  }
+  if (tool_name === "Bash") {
+    const command = String(tool_input.command || tool_input.cmd || "");
+    if (command) {
+      const cmdContext = {
+        ...context,
+        evaluation: { type: "command", command }
+      };
+      const cmdResult = evaluateCommand(policy, cmdContext);
+      if (cmdResult.matchedRules.length > 0) {
+        allMatched.push(...cmdResult.matchedRules);
+      }
+    }
+  }
+  const seen = new Set;
+  const deduplicated = [];
+  for (const rule of allMatched) {
+    if (!seen.has(rule.id)) {
+      seen.add(rule.id);
+      deduplicated.push(rule);
+    }
+  }
+  const action = resolveAction(policy.mode, deduplicated);
+  return {
+    allowed: action !== "block",
+    matchedRules: deduplicated,
+    action,
+    failClosed: false
+  };
+}
+function isWriteTool(toolName) {
+  return toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit";
+}
+function extractFilePathsFromToolInput(toolName, input) {
+  const paths = [];
+  const add = (value) => {
+    if (typeof value === "string" && value.trim()) {
+      paths.push(value.trim());
+    }
+  };
+  if (toolName === "Read" || toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
+    add(input.file_path);
+    add(input.path);
+  } else if (toolName === "Glob") {
+    add(input.path);
+  } else if (toolName === "Grep") {
+    add(input.path);
+  } else {
+    add(input.file_path);
+    add(input.path);
+  }
+  return paths;
+}
+function extractContentFromToolInput(input) {
+  if (typeof input.content === "string")
+    return input.content;
+  if (typeof input.new_string === "string")
+    return input.new_string;
+  return "";
+}
+var guardHotPathPrimed = false;
+function primeGuardHotPaths() {
+  if (guardHotPathPrimed) {
+    return;
+  }
+  guardHotPathPrimed = true;
+  try {
+    optimizeNextInvocation(matchRule);
+    optimizeNextInvocation(evaluate);
+  } catch {}
+}
+primeGuardHotPaths();
+
+// packages/cli-surface-plugin/src/control-plane/agent-binary-build.ts
+import { runtimeProvisioningEnv } from "@rig/core/runtime-provisioning-env";
+
+// packages/cli-surface-plugin/src/runner.ts
 class CliError extends RuntimeCliError {
-  hint;
   constructor(message, exitCode = 1, options = {}) {
-    super(message, exitCode);
-    if (options.hint?.trim()) {
-      this.hint = options.hint.trim();
-    }
+    super(message, exitCode, options);
   }
 }
 function takeOption(args, option) {
@@ -46,7 +687,6 @@ Usage: ${usage}`);
 
 // packages/cli-surface-plugin/src/commands/_cli-format.ts
 import pc from "picocolors";
-import { runStatusColorRole, runStatusText, statusColorRole } from "@rig/run-worker/runs";
 var dim = pc.dim;
 var faintBar = pc.dim("\u2502");
 var accent = pc.cyan;
@@ -69,13 +709,646 @@ function formatStatsTable(rows) {
 
 // packages/cli-surface-plugin/src/commands/_help-catalog.ts
 import pc2 from "picocolors";
-import {
-  ADVANCED_COMMANDS,
-  ADVANCED_GROUPS,
-  ALL_GROUPS,
-  helpCatalog,
-  TOP_LEVEL_SECTIONS
-} from "@rig/contracts";
+
+// packages/cli-surface-plugin/src/help-catalog-data.ts
+var TOP_LEVEL_SECTIONS = [
+  {
+    title: "Open Rig",
+    subtitle: "the cockpit \u2014 bare rig opens the Rig Cockpit inside an OMP collab session",
+    commands: [
+      {
+        command: "rig",
+        description: "Open the Rig Cockpit (OMP collaboration substrate) for the current workspace.",
+        usecase: "Day-to-day entry point: drive everything (tasks, runs, inbox) from the board.",
+        examples: ["cd my-project && rig", "rig            # in a repo with rig.config.ts"]
+      },
+      {
+        command: "rig --workspace <path>",
+        description: "Open the cockpit for another workspace instead of the current dir.",
+        usecase: "Operate a project without cd-ing into it.",
+        examples: ["rig --workspace ~/work/humanwork", "rig --workspace ../other-repo"]
+      },
+      {
+        command: "rig join <link>",
+        description: "Join an encrypted OMP collaborative session from another operator.",
+        usecase: "Pair on a teammate's live run from the join link they shared.",
+        examples: ["rig join where.rig-does.work/r/AbC123\u2026"]
+      },
+      { command: "/rig", description: "From inside an OMP session, (re)open the Rig Cockpit screen.", usecase: "Jump back to the board after dropping into the raw agent session." },
+      { command: "rig --version", description: "Print the installed Rig CLI version.", examples: ["rig --version"] }
+    ]
+  },
+  {
+    title: "Runs \u2014 dispatch & control task runs",
+    subtitle: "every run is an isolated, collaborative OMP session on the selected target",
+    commands: [
+      {
+        command: "rig run [start] <task|#issue|--next>",
+        description: "Dispatch a run for a task (refuses if one is already active; --force overrides).",
+        usecase: "Kick off work on a specific issue, or let Rig pick the next ready one.",
+        examples: [
+          "rig run 204                  # by task/issue id",
+          "rig run --next               # next ready task by deps/priority",
+          "rig run --title 'Fix API' 204 # title override before the task ref",
+          "rig run start 204 --force    # dispatch even if a run is already active",
+          "rig run start 204 --model opus-4.8 --prompt 'focus tests'"
+        ]
+      },
+      {
+        command: "rig run start-parallel [--limit n]",
+        description: "Dispatch all ready tasks concurrently up to the limit.",
+        usecase: "Burn down a backlog of independent tasks at once.",
+        examples: ["rig run start-parallel", "rig run start-parallel --limit 3"]
+      },
+      {
+        command: "rig run start-serial",
+        description: "Dispatch the next ready task; re-run to continue the serial queue.",
+        usecase: "Work a queue one-at-a-time (e.g. dependent tasks, limited capacity).",
+        examples: ["rig run start-serial"]
+      },
+      {
+        command: "rig run list",
+        description: "List every discoverable run (live registry + local) with status and links.",
+        usecase: "See what's running anywhere (local + remote) and grab ids/join links.",
+        examples: ["rig run list", "rig run list | grep running"]
+      },
+      { command: "rig run status", description: "Active vs recent runs at a glance.", examples: ["rig run status"] },
+      {
+        command: "rig run show <id>",
+        description: "Run card: status, task, PR, join link, pending approvals/inputs, error summary.",
+        usecase: "Get the full picture of one run before attaching or steering.",
+        examples: ["rig run show 019ee11f", "rig run show 019ee11f   # copy the join link"]
+      },
+      {
+        command: "rig run attach <id>",
+        description: "Attach to a run's live OMP collab session (write access).",
+        usecase: "Watch/drive a run interactively \u2014 type to the agent, see its work live.",
+        examples: ["rig run attach 019ee11f"]
+      },
+      {
+        command: "rig run steer <id> --message <text>",
+        description: "Send a steering message into a running session (remote routes to its host).",
+        usecase: "Course-correct an autonomous run without attaching.",
+        examples: [
+          "rig run steer 019ee11f --message 'focus on the API first'",
+          "rig run steer 019ee11f --message 'stop and open the PR now'"
+        ]
+      },
+      {
+        command: "rig run stop <id> [--reason <text>]",
+        description: "Request a graceful stop of a run (terminal).",
+        usecase: "Halt a run that's off-track or no longer needed.",
+        examples: ["rig run stop 019ee11f", "rig run stop 019ee11f --reason 'superseded by #210'"]
+      },
+      {
+        command: "rig run pause <id>",
+        description: "Park a live run (running \u2192 paused) without finalizing; the session stays attachable.",
+        usecase: "Hold an autonomous run mid-flight \u2014 free the agent without losing its place.",
+        examples: ["rig run pause 019ee11f"]
+      },
+      {
+        command: "rig run resume <id>",
+        description: "Resume a paused run (paused \u2192 running); the agent continues. A dead/stale run is re-dispatched fresh instead.",
+        usecase: "Un-pause a parked run, or retry a finished one.",
+        examples: ["rig run resume 019ee11f"]
+      },
+      {
+        command: "rig run restart <id>",
+        description: "Re-dispatch a task as a fresh run (new runId, clean runtime).",
+        usecase: "Retry a failed/stopped run from a clean slate.",
+        examples: ["rig run restart 019ee11f"]
+      },
+      {
+        command: "rig run timeline|replay <id>",
+        description: "Inspect a run's folded timeline / replay its journal.",
+        usecase: "Audit what an agent did, step by step, after the fact.",
+        examples: ["rig run timeline 019ee11f", "rig run replay 019ee11f"]
+      },
+      { command: "rig run cleanup", description: "Prune dead/stale run state.", usecase: "Clear out finished/orphaned run entries cluttering the board.", examples: ["rig run cleanup"] }
+    ]
+  },
+  {
+    title: "Tasks \u2014 the configured task source",
+    subtitle: "github-issues / files task sources feed dispatch",
+    commands: [
+      {
+        command: "rig task list [--search <t>] [--state <open|closed>]",
+        description: "List tasks from the configured source, with filters.",
+        usecase: "Find what's available to dispatch; filter by text or lifecycle status.",
+        examples: [
+          "rig task list",
+          "rig task list --state open",
+          "rig task list --search 'auth'"
+        ]
+      },
+      { command: "rig task next", description: "Show the next ready task by dependency/priority.", usecase: "Decide what to run next without scanning the whole list.", examples: ["rig task next"] },
+      {
+        command: "rig task show|info <id>",
+        description: "Task detail: title, body, status, labels, scope, deps, URL.",
+        usecase: "Read the full issue before dispatching a run for it.",
+        examples: ["rig task show 204", "rig task info 204"]
+      },
+      {
+        command: "rig task scope|deps --task <id>; rig task status",
+        description: "Inspect a task's scope globs/dependencies, or show project task status.",
+        usecase: "Check what files a run may touch / what's blocking it.",
+        examples: ["rig task scope --task 204", "rig task deps --task 204", "rig task status"]
+      },
+      { command: "rig task lookup <term>", description: "Find a task by id/title substring.", examples: ["rig task lookup revoke-invite"] },
+      { command: "rig task record \u2026", description: "Write task state/metadata back to the source.", usecase: "Programmatically update task lifecycle from scripts/CI." },
+      { command: "rig task artifacts <id>", description: "List/inspect a task's run artifacts.", examples: ["rig task artifacts 204"] },
+      { command: "rig triage", description: "Run the configured issueAnalysis pass once (schedule via cron/CI for continuous).", usecase: "Auto-classify/label/scope new issues in a batch.", examples: ["rig triage"] }
+    ]
+  },
+  {
+    title: "Planning, graph & supervisor",
+    subtitle: "dependency graph, blocker classification, rollups, planning, drift, and autonomous loop control",
+    commands: [
+      { command: "rig pipeline show [--json]", description: "Show the resolved default lifecycle pipeline.", examples: ["rig pipeline show", "rig pipeline show --json"] },
+      { command: "rig graph [--json|--dot]", description: "Render the workspace dependency graph from the configured task source.", examples: ["rig graph --json", "rig graph --dot"] },
+      { command: "rig blockers [--json]", description: "Classify task, human, approval, and external-input blockers.", examples: ["rig blockers"] },
+      { command: "rig status [--json]", description: "Show graph/run/blocker workspace status at a glance.", examples: ["rig status"] },
+      { command: "rig summary [--json]", description: "Roll up progress by epic and assignee.", examples: ["rig summary"] },
+      { command: "rig loop [--task <id>] [--max-tasks <n>] [--concurrency <n>]", description: "Run the autonomous supervisor loop over ready tasks, optionally restricted to one task.", examples: ["rig loop --task 106 --max-tasks 1", "rig loop --max-tasks 3 --concurrency 2"] },
+      { command: "rig unblock [task-id]", description: "Pick and optionally dispatch the highest-unblock task or blockers for one task.", examples: ["rig unblock --dry-run", "rig unblock 204 --dry-run"] },
+      { command: "rig plan --text <prd>|--prd <file>|--issue <id>", description: "Generate and optionally materialize a task plan.", examples: ["rig plan --issue 20 --json", "rig plan --prd docs/product/prd.md"] },
+      { command: "rig drift [--docs <csv>]", description: "Scan documentation for stale source references.", examples: ["rig drift", "rig drift --docs docs/**"] }
+    ]
+  },
+  {
+    title: "Config \u2014 everything through rig.config.ts",
+    subtitle: "resolution: ambient env \u2192 rig.config.ts \u2192 computed default",
+    commands: [
+      {
+        command: "rig config get [<key>]",
+        description: "Effective value(s) + which layer won (env / rig.config.ts / default).",
+        usecase: "Debug why a value is what it is \u2014 see the winning layer.",
+        examples: [
+          "rig config get                 # all effective values + sources",
+          "rig config get sshTarget       # one key + winning layer",
+          "rig config get relayUrl"
+        ]
+      },
+      {
+        command: "rig config set <key> <value>",
+        description: "Write an override (relayUrl/registryUrl/sshTarget or any RIG_*) into rig.config.ts.",
+        usecase: "Persist a setting so it survives across runs without env vars.",
+        examples: [
+          "rig config set sshTarget ubuntu@host        # remote placement",
+          "rig config set relayUrl wss://my-relay",
+          "rig config set RIG_ANYTHING value           # any RIG_* knob"
+        ]
+      },
+      {
+        command: "rig init",
+        description: "Create rig.config.ts (project, task source, placement/sshTarget) interactively.",
+        usecase: "First-time setup of a repo for Rig.",
+        examples: ["rig init"]
+      },
+      {
+        command: "runtime.server in rig.config.ts",
+        description: "Backbone (relay/registry/secret) + remote placement (sshTarget); defaults under the hood.",
+        usecase: "Pin a project's relay/registry and remote host in code.",
+        examples: [
+          "runtime: { server: { sshTarget: 'ubuntu@host' } }   // remote placement",
+          "runtime: { server: { relayUrl: 'wss://\u2026', registryUrl: 'https://\u2026/registry' } }"
+        ]
+      }
+    ]
+  },
+  {
+    title: "Placement & target \u2014 local vs remote execution",
+    subtitle: "where runs execute; the backbone relay/registry is shared",
+    commands: [
+      { command: "rig server status", description: "Show the selected placement (local/remote) and task source.", examples: ["rig server status"] },
+      { command: "rig server list", description: "List configured server targets.", examples: ["rig server list"] },
+      {
+        command: "rig server use <local|alias>",
+        description: "Select a server target (execution placement).",
+        usecase: "Switch a repo between local and a remote host for run execution.",
+        examples: ["rig server use local", "rig server use prod-box"]
+      },
+      {
+        command: "rig server add --alias <alias> --host <host> [--port <n>] | remove <alias>",
+        description: "Configure or remove a remote server target.",
+        examples: ["rig server add --alias prod-box --host ubuntu@host", "rig server remove prod-box"]
+      },
+      {
+        command: "rig remote <list|add|test|status|\u2026>",
+        description: "Lower-level remote endpoint management + run control over a remote.",
+        examples: ["rig remote list", "rig remote test prod-box", "rig remote status"]
+      }
+    ]
+  },
+  {
+    title: "Inbox & Doctor \u2014 approvals and health",
+    subtitle: "answer pending workflow entries; probe setup",
+    commands: [
+      {
+        command: "rig inbox approvals|inputs",
+        description: "List pending approval / user-input workflow entries.",
+        usecase: "See what a run is blocked on waiting for you.",
+        examples: ["rig inbox approvals", "rig inbox inputs"]
+      },
+      {
+        command: "rig inbox approve --run <id> --request <id> --decision approve|reject | respond --run <id> --request <id> --text <answer>",
+        description: "Attempt to resolve an approval or answer a user-input prompt; attach if one-shot delivery is unavailable.",
+        usecase: "Resolve pending requests from automation when the live run accepts out-of-band resolution.",
+        examples: ["rig inbox approve --run run1 --request abc123 --decision approve", "rig inbox respond --run run1 --request abc123 --text 'use option B'"]
+      },
+      { command: "rig inbox watch", description: "Stream inbox changes live.", examples: ["rig inbox watch"] },
+      { command: "rig doctor", description: "Cheap health checks: session discovery, registry, selected target, workflow entries.", usecase: "First thing to run when something seems off.", examples: ["rig doctor"] }
+    ]
+  },
+  {
+    title: "Inspect & stats \u2014 observability",
+    subtitle: "logs, artifacts, diffs, failure analysis",
+    commands: [
+      {
+        command: "rig inspect run-logs --run <id> | logs --task <id>",
+        description: "Print run/session log lines.",
+        usecase: "Debug why a run failed or stalled.",
+        examples: ["rig inspect run-logs --run 019ee11f", "rig inspect logs --task 204"]
+      },
+      { command: "rig inspect runs", description: "List runs from on-disk runtime state.", examples: ["rig inspect runs"] },
+      { command: "rig inspect artifact --task <id> --file <name> | artifacts --task <id>", description: "Inspect a task/run's artifacts.", examples: ["rig inspect artifacts --task 204", "rig inspect artifact --task 204 --file task-result.json"] },
+      { command: "rig inspect diff --task <id> | graph [--task <id>]", description: "Run diff / task dependency graph.", examples: ["rig inspect diff --task 204", "rig inspect graph --task 204"] },
+      { command: "rig inspect failures --task <id>", description: "Classified failure diagnostics for a task's runs.", usecase: "Triage repeated failures on one task.", examples: ["rig inspect failures --task 204"] },
+      { command: "rig stats", description: "Aggregate run stats over a window.", examples: ["rig stats", "rig stats --since 7d"] }
+    ]
+  },
+  {
+    title: "Setup & integrations",
+    subtitle: "initialize, authenticate, and wire the project",
+    commands: [
+      { command: "rig init", description: "Set up a new repo: rig.config.ts, task source, placement, state.", examples: ["rig init"] },
+      { command: "rig setup", description: "Run/repair the full setup wizard (repo, placement, GitHub auth, labels, verify).", usecase: "Re-run when auth/labels/placement drift or after onboarding.", examples: ["rig setup"] },
+      {
+        command: "rig github status|token|import-gh",
+        description: "GitHub auth status, token management, issue import.",
+        examples: ["rig github status", "rig github import-gh"]
+      },
+      { command: "rig repo|git \u2026", description: "Repo/source helpers (clone, credentials, git ops).", examples: ["rig repo status", "rig git \u2026"] },
+      { command: "rig review", description: "Inspect or change the completion-review (Greptile) gate policy.", examples: ["rig review"] }
+    ]
+  },
+  {
+    title: "Extend & build",
+    subtitle: "plugins, OMP/Pi packages, binaries, workspaces",
+    commands: [
+      { command: "rig plugin list|validate|run", description: "Inspect and exercise plugin-contributed channels.", examples: ["rig plugin list", "rig plugin validate", "rig plugin run <name>"] },
+      { command: "rig pi list|add|remove|search", description: "Manage OMP/Pi extension packages for sessions/workers.", examples: ["rig pi list", "rig pi add <pkg>", "rig pi search <term>"] },
+      {
+        command: "rig dist build|install",
+        description: "Build/install the self-contained rig binary distribution.",
+        usecase: "Produce/refresh the single-file rig binary.",
+        examples: ["rig dist build", "rig dist install"]
+      },
+      { command: "rig workspace summary|topology", description: "Multi-root workspace inspection.", examples: ["rig workspace summary", "rig workspace topology"] },
+      { command: "rig.config.ts plugins / runtime.pi.packages", description: "Declare task sources, validators, hooks, skills, roles + team OMP/Pi packages.", examples: ["plugins: [...standardPlugins()]", "runtime: { pi: { packages: ['@me/my-ext'] } }"] }
+    ]
+  }
+];
+var PRIMARY_GROUPS = [
+  {
+    name: "pipeline",
+    summary: "Default lifecycle pipeline inspection.",
+    usage: ["rig pipeline show [--json]"],
+    commands: [{ command: "show [--json]", description: "Show resolved default lifecycle stages, mutation annotations, dropped anchors, and cycles.", primary: true }],
+    examples: ["rig pipeline show", "rig pipeline show --json"]
+  },
+  {
+    name: "graph",
+    summary: "Workspace dependency graph.",
+    usage: ["rig graph [--json|--dot]"],
+    commands: [{ command: "[--json|--dot]", description: "Build the workspace dependency graph and print summary, JSON, or DOT.", primary: true }],
+    examples: ["rig graph", "rig graph --json", "rig graph --dot"]
+  },
+  {
+    name: "blockers",
+    summary: "Workspace blocker classification.",
+    usage: ["rig blockers [--json]"],
+    commands: [{ command: "[--json]", description: "Classify machine, human, approval, and external-input blockers.", primary: true }],
+    examples: ["rig blockers", "rig blockers --json"]
+  },
+  {
+    name: "status",
+    summary: "Workspace graph/run status.",
+    usage: ["rig status [--json]"],
+    commands: [{ command: "[--json]", description: "Show active runs, attention counts, rollup counts, and blocker counts.", primary: true }],
+    examples: ["rig status"]
+  },
+  {
+    name: "summary",
+    summary: "Workspace progress rollups.",
+    usage: ["rig summary [--json]"],
+    commands: [{ command: "[--json]", description: "Roll up progress by epic and assignee.", primary: true }],
+    examples: ["rig summary", "rig summary --json"]
+  },
+  {
+    name: "loop",
+    summary: "Autonomous supervisor loop.",
+    usage: ["rig loop [--task <id>] [--max-tasks <n>] [--concurrency <n>] [--stop-when <csv>] [--dry-run] [--json]"],
+    commands: [{ command: "[--task <id>] [--max-tasks <n>] [--concurrency <n>] [--dry-run]", description: "Select ready tasks, dispatch runs, and await terminal outcomes.", primary: true }],
+    examples: ["rig loop --task 106 --max-tasks 1", "rig loop --max-tasks 3 --concurrency 2"]
+  },
+  {
+    name: "unblock",
+    summary: "Highest-unblock task dispatcher.",
+    usage: ["rig unblock [task-id] [--dry-run] [--json]"],
+    commands: [{ command: "[task-id] [--dry-run]", description: "Dispatch the highest-unblock ready task, or blockers for one task.", primary: true }],
+    examples: ["rig unblock --dry-run", "rig unblock 204 --dry-run"]
+  },
+  {
+    name: "plan",
+    summary: "PRD-to-task planning.",
+    usage: ["rig plan --text <prd>|--prd <file>|--issue <id> [--title <title>] [--materialize] [--json]"],
+    commands: [{ command: "--text <prd>|--prd <file>|--issue <id> [--materialize]", description: "Generate a plan and optionally create tasks through the configured task source.", primary: true }],
+    examples: ["rig plan --issue 20 --json", "rig plan --prd docs/product/prd.md"]
+  },
+  {
+    name: "drift",
+    summary: "Documentation drift scanner.",
+    usage: ["rig drift [--docs <csv>] [--ignore <csv>] [--json]"],
+    commands: [{ command: "[--docs <csv>] [--ignore <csv>] [--json]", description: "Scan documentation for stale code references with the standard drift plugin.", primary: true }],
+    examples: ["rig drift", "rig drift --docs docs/**"]
+  },
+  {
+    name: "server",
+    summary: "Compatibility server selector; the product Server target screen lives in Rig Cockpit.",
+    usage: ["rig server <status|list|add|use|remove> [options]"],
+    commands: [
+      { command: "status", description: "Legacy automation-only: show the selected placement and task source.", primary: true },
+      { command: "use local", description: "Legacy automation-only: switch this repo to local execution placement.", primary: true },
+      { command: "add --alias <alias> --host <host> [--port <n>]", description: "Legacy automation-only: save a remote execution target.", primary: true },
+      { command: "use <alias>", description: "Legacy automation-only: select a remote execution target alias.", primary: true },
+      { command: "remove <alias>", description: "Legacy automation-only: remove a saved remote execution target.", primary: true },
+      { command: "list", description: "Legacy automation-only: list saved local/remote server aliases.", primary: true }
+    ],
+    examples: [
+      "rig server status        # legacy automation only",
+      "rig server use local     # legacy automation only"
+    ],
+    next: ["For normal UX, run bare `rig`, open Cockpit Server, then continue to Tasks."]
+  },
+  {
+    name: "task",
+    summary: "Legacy automation-only task-source inspection and dispatch helpers.",
+    usage: ["rig task <list|next|show|run> [options]"],
+    commands: [
+      { command: "list [--assignee <login|me|@me>] [--state open|closed]", description: "Legacy automation-only: list tasks from the configured source.", primary: true },
+      { command: "next [filters]", description: "Legacy automation-only: render the next matching task card.", primary: true },
+      { command: "show <id>|--task <id> [--raw]", description: "Legacy automation-only: show a task payload for scripts.", primary: true },
+      { command: "run [#<issue>|<task-id>|--task <id>] [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", description: "Legacy/fenced: dispatch through the CLI run path; not the task-detail dispatch path.", primary: true },
+      { command: "ready", description: "Legacy automation-only: list task IDs that old dispatch can run now." },
+      { command: "validate|verify [--task <id>]", description: "Legacy automation-only: run configured task checks/review gates; failing checks exit nonzero." },
+      { command: "details --task <id>", description: "Legacy automation-only: show full task info from the configured source." },
+      { command: "reopen [--task <id> | --all] [--reason <text>]", description: "Legacy automation-only: reopen closed task(s) in the configured source." },
+      { command: "artifacts|artifact-dir|artifact-write", description: "Legacy automation-only: inspect or write task artifacts." }
+    ],
+    examples: [
+      "rig task list --assignee @me --limit 20   # legacy automation only",
+      "rig task show 123 --raw                   # legacy automation only",
+      "rig task run #123 --model opus-4.8 --prompt 'focus tests'"
+    ],
+    next: ["For normal UX, run bare `rig`, use Cockpit Server/Tasks, then dispatch from Task detail."]
+  },
+  {
+    name: "run",
+    summary: "Legacy automation-only run-record inspection; OMP Runs/collab is the live surface.",
+    usage: ["rig run [start] <task|#issue|--next> [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", "rig run <list|status|show|steer|stop|resume|restart> [options]"],
+    commands: [
+      { command: "[start] <task|#issue|--next> [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", description: "Legacy automation-only: dispatch a task run through the unified run launcher.", primary: true },
+      { command: "list", description: "Legacy automation-only: list old run records from selected server/local state.", primary: true },
+      { command: "status", description: "Legacy automation-only: render old active/recent run-record groups; not live OMP status.", primary: true },
+      { command: "show <id>|--run <id> [--raw]", description: "Legacy automation-only: show an old run-record payload for scripts.", primary: true },
+      { command: "attach <run-id>|--run <id>", description: "Legacy/fenced: not the Rig Cockpit attach path; use OMP Runs or `rig join <link>`.", primary: true },
+      { command: "steer <run-id> --message <text>", description: "Legacy automation-only: queue steering into an old live worker.", primary: true },
+      { command: "stop <run-id>|--run <id> [--reason <text>]", description: "Legacy automation-only: request stop for old run records.", primary: true },
+      { command: "resume <run-id>|--run <id>", description: "Legacy automation-only: resume an interrupted old run record." },
+      { command: "restart <run-id>|--run <id>", description: "Legacy automation-only: re-dispatch an old run from a clean runtime." },
+      { command: "timeline|replay <run-id>|--run <id> [--with-session]", description: "Legacy automation-only: print an old consolidated run timeline." },
+      { command: "delete|cleanup [<run-id>|--run <id>]", description: "Legacy automation-only: remove stale live-registry entries; journals are retained." }
+    ],
+    examples: [
+      "rig run 204          # dispatch task 204",
+      "rig run --title 'Fix API' 204",
+      "rig run stop <run-id> # legacy automation only"
+    ],
+    next: [
+      "For live sessions, use bare `rig`, the OMP Runs screen, or `rig join <collab-link>`.",
+      "Use `--json` only for scripts that still consume legacy compatibility records."
+    ]
+  },
+  {
+    name: "inbox",
+    summary: "Legacy automation-only request view; normal UX is the OMP Inbox screen.",
+    usage: ["rig inbox <approvals|approve|inputs|respond> [options]"],
+    commands: [
+      { command: "approvals [--run <id>] [--task <id>]", description: "Legacy automation-only: list pending approval records.", primary: true },
+      { command: "inputs [--run <id>] [--task <id>]", description: "Legacy automation-only: list pending user-input records.", primary: true },
+      { command: "approve --run <id> --request <id> --decision approve|reject", description: "Legacy automation-only: resolve an approval record." },
+      { command: "respond --run <id> --request <id> --text <answer> | --answer <answer>", description: "Legacy automation-only: answer a user-input record." }
+    ],
+    examples: [
+      "rig inbox approvals # legacy automation only"
+    ],
+    next: ["For normal UX, use bare `rig`, then the OMP Inbox screen."]
+  },
+  {
+    name: "stats",
+    summary: "Legacy automation-only metrics over old run records; not the OMP live UX.",
+    usage: ["rig stats [show] [--since <7d|30d|ISO date>]"],
+    commands: [
+      { command: "show [--since <window>]", description: "Legacy automation-only: totals, completion/failure rates, run time, steering, stalls, approvals.", primary: true }
+    ],
+    examples: [
+      "rig stats --json # legacy automation only"
+    ],
+    next: ["For normal UX, use the OMP Runs screen."]
+  },
+  {
+    name: "inspect",
+    summary: "Legacy automation-only artifact/log inspection; normal UX is OMP session history.",
+    usage: ["rig inspect <logs|artifact|artifacts|run-logs|runs|failures|graph|diff> [options]"],
+    commands: [
+      { command: "logs --task <id>", description: "Legacy automation-only: latest old run log for a task.", primary: true },
+      { command: "run-logs --run <id>", description: "Legacy automation-only: log lines for a specific run.", primary: true },
+      { command: "runs", description: "Legacy automation-only: list projected runs." },
+      { command: "artifact --task <id> --file <name>", description: "Legacy automation-only: preview one completion artifact." },
+      { command: "artifacts --task <id>", description: "Legacy automation-only: list completion artifacts.", primary: true },
+      { command: "diff --task <id>", description: "Legacy automation-only: list task changed files." },
+      { command: "failures --task <id>", description: "Legacy automation-only: recorded failures for a task.", primary: true },
+      { command: "graph [--task <id>]", description: "Legacy automation-only: task dependency graph." }
+    ],
+    next: ["For normal UX, use the OMP Runs screen and OMP session history."]
+  },
+  {
+    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: "Legacy automation-only config bootstrap/repair helper; not root onboarding.",
+    usage: ["rig init [--yes] [--server local|remote] [--repo owner/repo] [--remote-url <url>]"],
+    commands: [
+      { command: "init", description: "Legacy/fenced setup wizard for compatibility projects; not onboarding.", primary: true },
+      { command: "init --demo", description: "Legacy/fenced offline demo project for compatibility tests.", primary: true },
+      { command: "init --yes", description: "Legacy/fenced non-interactive setup for old automation.", primary: true },
+      { command: "init --server remote --remote-url <url>", description: "Legacy/fenced remote server link setup.", primary: true },
+      { command: "init --repair", description: "Legacy/fenced repair of missing private compatibility state." }
+    ],
+    examples: [
+      "rig init --demo   # legacy compatibility only",
+      "rig init --repair # legacy compatibility only"
+    ],
+    next: ["For onboarding and normal UX, run bare `rig`, then use Cockpit Server/Tasks and dispatch from Task detail."]
+  },
+  {
+    name: "doctor",
+    summary: "Diagnostic-only compatibility checks; normal health lives in the OMP Doctor screen.",
+    usage: ["rig doctor"],
+    commands: [
+      { command: "doctor", description: "Diagnostic/legacy-only: check compatibility setup/runtime state; not onboarding.", primary: true },
+      { command: "check", description: "Diagnostic/legacy-only spelling for compatibility checks." }
+    ],
+    examples: ["rig doctor --json # legacy diagnostic automation only"],
+    next: ["For normal UX, use the OMP Doctor screen."]
+  },
+  {
+    name: "github",
+    summary: "Legacy automation-only GitHub auth helpers for selected compatibility servers.",
+    usage: ["rig github auth <status|import-gh|token>"],
+    commands: [
+      { command: "auth status", description: "Legacy automation-only: show GitHub auth state.", primary: true },
+      { command: "auth import-gh", description: "Legacy automation-only: import the current `gh` token into the selected server." },
+      { command: "auth token --token <token>", description: "Legacy automation-only: store a token on the selected server." }
+    ],
+    examples: ["rig github auth status # legacy automation only"],
+    next: ["For normal UX, use bare `rig` and the OMP extension cockpit."]
+  }
+];
+var ADVANCED_GROUPS = [
+  {
+    name: "setup",
+    summary: "Legacy automation-only setup bootstrap/check helpers.",
+    usage: ["rig setup <bootstrap|check|preflight>"],
+    commands: [
+      { command: "bootstrap", description: "Legacy automation-only: bootstrap local setup dependencies.", primary: true },
+      { command: "check", description: "Legacy automation-only: check local setup state (toolchain, deps, config).", primary: true },
+      { command: "preflight", description: "Legacy automation-only: run preflight checks before an old run.", primary: true }
+    ]
+  },
+  {
+    name: "profile",
+    summary: "Runtime profile/model defaults.",
+    usage: ["rig profile <show|set>"],
+    commands: [
+      { command: "show", description: "Show the active execution profile.", primary: true },
+      { command: "set [--model <model>] [--runtime <runtime>] [--plugin <plugin>]", description: "Set model/runtime/plugin profile defaults.", primary: true }
+    ]
+  },
+  {
+    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 <provider>]", description: "Change review strictness/provider (e.g. --provider greptile)." }
+    ],
+    examples: ["rig review show", "rig review set required --provider greptile"],
+    next: ["For normal workflow handoffs, use the OMP Inbox screen."]
+  },
+  {
+    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 [--workers <n>] [--max-tasks <n>] [--action validate|verify|pipeline] [--isolation off|worktree] [--no-runtime-reuse] [--fail-fast] [--skip-project-sync]"],
+    commands: [
+      { command: "run [--workers <n>] [--max-tasks <n>] [--action validate|verify|pipeline] [--isolation off|worktree] [--no-runtime-reuse] [--fail-fast] [--skip-project-sync]", description: "Process queue work: drain matching tasks with N workers, optional per-task action and isolation.", primary: true }
+    ]
+  },
+  {
+    name: "agent",
+    summary: "Runtime agent workspace helpers.",
+    usage: ["rig agent <list|prepare|run|cleanup>"],
+    commands: [
+      { command: "list", description: "List prepared agent runtimes.", primary: true },
+      { command: "prepare [--id <id>] [--mode <mode>] [--task <task>]", description: "Prepare an isolated agent runtime workspace.", primary: true },
+      { command: "run [--id <id>] [--mode <mode>] [--task <task>] [--skip-project-sync]", description: "Prepare (if needed) and run an agent in its workspace.", primary: true },
+      { command: "cleanup [--all] [--id <id>]", description: "Remove prepared agent workspaces.", primary: true }
+    ]
+  },
+  {
+    name: "dist",
+    summary: "Build/install packaged Rig CLI.",
+    usage: ["rig dist <build|install|doctor|rebuild-agent>"],
+    commands: [
+      { command: "build [--output-dir <dir>]", description: "Build the distributable Rig CLI.", primary: true },
+      { command: "install [--scope <scope>] [--path <path>]", description: "Install the built CLI to a scope/path.", primary: true },
+      { command: "doctor", description: "Diagnose the dist toolchain and install state.", primary: true },
+      { command: "rebuild-agent", description: "Rebuild the agent runtime image, pruning stale images.", primary: true }
+    ]
+  },
+  { name: "workspace", summary: "Workspace topology/service helpers.", usage: ["rig workspace <summary|topology|remote-hosts>"], commands: [{ command: "summary", description: "Show workspace summary." }] },
+  {
+    name: "remote",
+    summary: "Legacy automation-only remote orchestration controls.",
+    usage: ["rig remote <status|tasks|watch|pause|resume|continue|stop|refresh|add-iterations|remove-iterations|endpoint ...>"],
+    commands: [
+      { command: "status [--remote <alias>]", description: "Legacy automation-only: show old remote orchestration state.", primary: true },
+      { command: "tasks [--remote <alias>]", description: "Legacy automation-only: list the old remote's tracked tasks.", primary: true },
+      { command: "watch [--remote <alias>] [--seconds <n>] [--event <type>]", description: "Legacy automation-only: stream old remote orchestration events.", primary: true },
+      { command: "pause [--remote <alias>]", description: "Legacy automation-only: pause old remote orchestration.", primary: true },
+      { command: "resume [--remote <alias>] [--max-workers <n>] [--max-iterations <n>] [--direct-merge]", description: "Legacy automation-only: resume old remote orchestration with optional tuning.", primary: true },
+      { command: "continue [--remote <alias>]", description: "Legacy automation-only: continue a paused old remote.", primary: true },
+      { command: "stop [--remote <alias>]", description: "Legacy automation-only: stop old remote orchestration.", primary: true },
+      { command: "refresh [--remote <alias>]", description: "Legacy automation-only: refresh old remote state.", primary: true },
+      { command: "add-iterations [--count <n>] [--remote <alias>]", description: "Legacy automation-only: grant an old remote more iterations.", primary: true },
+      { command: "remove-iterations [--count <n>] [--remote <alias>]", description: "Legacy automation-only: reduce an old remote's iteration budget.", primary: true },
+      { command: "endpoint list", description: "Legacy automation-only: list configured remote endpoints.", primary: true },
+      { command: "endpoint add --alias <alias> --host <host> --port <n> [--token <token>]", description: "Legacy automation-only: register a remote endpoint.", primary: true },
+      { command: "endpoint remove --alias <alias>", description: "Legacy automation-only: remove a remote endpoint.", primary: true },
+      { command: "endpoint test [--alias <alias>]", description: "Legacy diagnostic-only: test connectivity to a remote endpoint.", primary: true },
+      { command: "endpoint doctor", description: "Legacy diagnostic-only: diagnose remote endpoint configuration.", primary: true }
+    ]
+  },
+  { 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];
+
+// packages/cli-surface-plugin/src/commands/_help-catalog.ts
 function heading(title) {
   return pc2.bold(pc2.cyan(title));
 }
@@ -149,6 +1422,7 @@ function printGroupHelpDocument(groupName) {
 
 // packages/cli-surface-plugin/src/commands/stats.ts
 var DAY_MS = 24 * 60 * 60 * 1000;
+var RunReadModelCap = defineCapability(RUN_READ_MODEL);
 function parseSinceOption(value, now = new Date) {
   if (!value?.trim())
     return null;
@@ -206,8 +1480,13 @@ async function executeStats(context, args, deps = {}) {
     throw new CliError(`Unknown stats command: ${command}`, 1, { hint: "Run `rig stats --help` \u2014 the default command is `show`." });
   const sinceResult = takeOption(commandArgs, "--since");
   requireNoExtraArgs(sinceResult.rest, "rig stats [show] [--since <7d|30d|ISO date>]");
-  const statsOptions = deps.listRuns ? { since: parseSinceOption(sinceResult.value), listRuns: deps.listRuns } : { since: parseSinceOption(sinceResult.value) };
-  const details = await computeStats(context.projectRoot, statsOptions);
+  const since = parseSinceOption(sinceResult.value);
+  const readModel = await requireCapabilityForRoot(context.projectRoot, RunReadModelCap, "No run-worker plugin provides run read model for this project root.");
+  const details = await readModel.getStats({
+    projectRoot: context.projectRoot,
+    since: since ? since.toISOString() : null,
+    ...deps.listRuns ? { runs: await deps.listRuns(context.projectRoot) } : {}
+  });
   if (context.outputMode === "text")
     printFormattedOutput(formatStatsTable(formatStatsRows(details)));
   return { ok: true, group: "stats", command, details };