@h-rig/cli-surface-plugin 0.0.6-alpha.146

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

@@ -0,0 +1,157 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_help-catalog.ts
+import pc from "picocolors";
+import {
+  ADVANCED_COMMANDS,
+  ADVANCED_GROUPS,
+  ALL_GROUPS,
+  helpCatalog,
+  TOP_LEVEL_SECTIONS
+} from "@rig/contracts";
+function heading(title) {
+  return pc.bold(pc.cyan(title));
+}
+function renderRigBanner(version) {
+  const m = (s) => pc.bold(pc.magenta(s));
+  const c = (s) => pc.bold(pc.cyan(s));
+  const y = (s) => pc.yellow(s);
+  const d = (s) => pc.dim(s);
+  const lines = [
+    m("    \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 ") + d("  \u2591\u2592\u2593\u2588 "),
+    m("    \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D ") + d("\u2593\u2592\u2591"),
+    c("    \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2588\u2557") + d("    \u2591\u2592"),
+    c("    \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551") + d(" \u2588\u2593\u2591"),
+    y("    \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D") + d("   \u2592\u2591"),
+    y("    \u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D "),
+    "",
+    `    ${c("\u25E2\u25E4")} ${pc.bold("OMP extension cockpit for autonomous coding agents")} ${m("//")} ${d("you are the operator")}`,
+    version ? `    ${d(`v${version} \xB7 jack in: rig`)}` : `    ${d("jack in: rig")}`
+  ];
+  return lines.join(`
+`);
+}
+function commandLine(command, description) {
+  const commandColumn = command.length >= 38 ? `${command}  ` : command.padEnd(38);
+  return `${pc.dim("\u2502")} ${pc.bold(commandColumn)} ${description}`;
+}
+function renderCommandBlock(commands) {
+  const indent = `${pc.dim("\u2502")} ${" ".repeat(38)} `;
+  return commands.map((entry) => {
+    const lines = [commandLine(entry.command, entry.description)];
+    if (entry.usecase) {
+      lines.push(`${indent}${pc.dim("when:")} ${pc.dim(entry.usecase)}`);
+    }
+    for (const example of entry.examples ?? []) {
+      lines.push(`${indent}${pc.dim("$")} ${pc.cyan(example)}`);
+    }
+    return lines.join(`
+`);
+  }).join(`
+`);
+}
+function renderGroup(group) {
+  const lines = [
+    `${heading(`rig ${group.name}`)} \u2014 ${group.summary}`,
+    "",
+    pc.bold("Usage"),
+    ...group.usage.map((line) => `  ${line}`),
+    "",
+    pc.bold("Commands"),
+    ...group.commands.map((entry) => commandLine(entry.command, entry.description))
+  ];
+  if (group.examples?.length) {
+    lines.push("", pc.bold("Examples"), ...group.examples.map((line) => `  ${pc.dim("$")} ${line}`));
+  }
+  if (group.next?.length) {
+    lines.push("", pc.bold("Next steps"), ...group.next.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  if (group.advanced?.length) {
+    lines.push("", pc.bold("Compatibility / advanced"), ...group.advanced.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  return lines.join(`
+`);
+}
+function renderTopLevelHelp() {
+  return [
+    `${heading("rig")} ${pc.dim("\u2014 Rig Cockpit for autonomous coding agents")}`,
+    pc.dim("The loop: bare `rig` \u2192 Cockpit \u2192 Server target \u2192 Tasks \u2192 Task detail \u2192 Dispatch/Attach; every run uses OMP collaboration as the session substrate."),
+    "",
+    ...TOP_LEVEL_SECTIONS.flatMap((section) => [
+      `${pc.bold(pc.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc.dim(section.subtitle)}`,
+      renderCommandBlock(section.commands),
+      ""
+    ]),
+    pc.dim("More: `rig help --advanced` for fenced legacy/diagnostic commands; `rig <group> --help` for per-group compatibility help; `rig --version` for the installed version."),
+    "",
+    pc.bold("Root options"),
+    commandLine("--workspace <path>", "Open Rig Cockpit for a workspace instead of the current directory."),
+    commandLine("--json", "Compatibility flag for fenced legacy/diagnostic subcommands."),
+    commandLine("--dry-run", "Compatibility flag for fenced legacy/diagnostic subcommands.")
+  ].join(`
+`).trimEnd();
+}
+function renderAdvancedHelp() {
+  return [
+    `${heading("rig advanced")} \u2014 fenced legacy compatibility, diagnostics, and internal surfaces`,
+    "",
+    pc.bold("Normal public UX"),
+    "  rig, rig --workspace <path>, rig join <collab-link>, and /rig inside OMP",
+    "",
+    pc.bold("Legacy/diagnostic groups"),
+    "  init, server, task, run, inbox, inspect, stats, doctor, github, setup, remote",
+    "",
+    pc.bold("Advanced commands"),
+    ...ADVANCED_COMMANDS.map((entry) => commandLine(entry.command, entry.description)),
+    "",
+    pc.bold("Advanced groups"),
+    ...ADVANCED_GROUPS.map((group) => commandLine(group.name, group.summary)),
+    "",
+    pc.dim("Legacy groups remain callable for old automation and diagnostics. Prefer bare `rig` and the OMP cockpit for day-to-day work.")
+  ].join(`
+`);
+}
+function renderGroupHelp(groupName) {
+  const group = ALL_GROUPS.find((candidate) => candidate.name === groupName);
+  return group ? renderGroup(group) : null;
+}
+function listHelpGroups() {
+  return ALL_GROUPS.map((group) => group.name);
+}
+function suggestGroupCommandForWord(word, liveGroups) {
+  const normalized = word.trim().toLowerCase();
+  if (!normalized)
+    return null;
+  for (const group of ALL_GROUPS) {
+    if (liveGroups && !liveGroups.has(group.name))
+      continue;
+    for (const entry of group.commands) {
+      const firstToken = entry.command.split(/\s+/)[0] ?? "";
+      const names = firstToken.split("|").map((name) => name.trim().toLowerCase());
+      if (names.includes(normalized)) {
+        return `rig ${group.name} ${normalized}`;
+      }
+    }
+  }
+  return null;
+}
+function printTopLevelHelp(state = {}) {
+  console.log(renderTopLevelHelp());
+}
+function printAdvancedHelp() {
+  console.log(renderAdvancedHelp());
+}
+function printGroupHelpDocument(groupName) {
+  console.log(renderGroupHelp(groupName) ?? renderTopLevelHelp());
+}
+export {
+  suggestGroupCommandForWord,
+  renderTopLevelHelp,
+  renderRigBanner,
+  renderGroupHelp,
+  renderAdvancedHelp,
+  printTopLevelHelp,
+  printGroupHelpDocument,
+  printAdvancedHelp,
+  listHelpGroups,
+  helpCatalog
+};

package/dist/src/commands/_inprocess-services.d.ts

@@ -0,0 +1,33 @@
+import { saveGitHubTokenForProject, type GitHubAuthStatus } from "@rig/runtime/control-plane/github/index";
+export type GitHubAuthStatusResponse = {
+    readonly ok: true;
+} & GitHubAuthStatus;
+export type GitHubTokenPostResponse = Awaited<ReturnType<typeof saveGitHubTokenForProject>> & {
+    readonly authenticated: boolean;
+    readonly apiSessionToken: string;
+};
+export declare function setGitHubBearerTokenForCurrentProcess(token: string | null, projectRoot?: string): void;
+export declare function getGitHubAuthStatusInProcess(context: {
+    projectRoot: string;
+}): Promise<GitHubAuthStatusResponse>;
+export declare function postGitHubTokenInProcess(context: {
+    projectRoot: string;
+}, token: string, options?: {
+    readonly selectedRepo?: string;
+    readonly projectRoot?: string;
+}): Promise<GitHubTokenPostResponse>;
+export declare function listGitHubProjectsInProcess(context: {
+    projectRoot: string;
+}, owner: string, options?: {
+    readonly authToken?: string | null;
+    readonly baseUrl?: string | null;
+}): Promise<Record<string, unknown>>;
+export declare function getGitHubProjectStatusFieldInProcess(context: {
+    projectRoot: string;
+}, projectId: string, options?: {
+    readonly authToken?: string | null;
+    readonly baseUrl?: string | null;
+}): Promise<Record<string, unknown>>;
+export declare function requestGitHubAuthJsonInProcess(context: {
+    projectRoot: string;
+}, pathname: string, init?: RequestInit): Promise<unknown>;

package/dist/src/commands/_inprocess-services.js

@@ -0,0 +1,102 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_inprocess-services.ts
+import { resolve } from "path";
+import {
+  beginGitHubDeviceFlow,
+  checkGitHubRepoPermissions,
+  createGitHubAuthStore,
+  listGitHubProjects,
+  pollGitHubDeviceFlow,
+  resolveGitHubAuthStatus,
+  resolveProjectStatusField,
+  saveGitHubTokenForProject
+} from "@rig/runtime/control-plane/github/index";
+var scopedGitHubBearerTokens = new Map;
+function cleanToken(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+function cleanString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function oauthClientId() {
+  return cleanToken(process.env.RIG_GITHUB_OAUTH_CLIENT_ID);
+}
+function tokenForProject(projectRoot, override) {
+  const scoped = scopedGitHubBearerTokens.get(resolve(projectRoot));
+  return cleanToken(override) ?? scoped ?? createGitHubAuthStore(projectRoot).readToken() ?? cleanToken(process.env.RIG_GITHUB_TOKEN);
+}
+function setGitHubBearerTokenForCurrentProcess(token, projectRoot) {
+  scopedGitHubBearerTokens.set(resolve(projectRoot ?? process.cwd()), cleanToken(token));
+}
+async function getGitHubAuthStatusInProcess(context) {
+  return { ok: true, ...resolveGitHubAuthStatus({ projectRoot: context.projectRoot, oauthConfigured: Boolean(oauthClientId()) }) };
+}
+async function postGitHubTokenInProcess(context, token, options = {}) {
+  const targetRoot = options.projectRoot?.trim() || context.projectRoot;
+  const result = await saveGitHubTokenForProject({
+    projectRoot: targetRoot,
+    token,
+    tokenSource: "manual-token",
+    selectedRepo: options.selectedRepo ?? null
+  });
+  const store = createGitHubAuthStore(targetRoot);
+  const session = store.createApiSession();
+  if (targetRoot !== context.projectRoot) {
+    store.copyToLocalProjectRoot(context.projectRoot);
+  }
+  return { ...result, authenticated: result.signedIn, apiSessionToken: session.token };
+}
+async function listGitHubProjectsInProcess(context, owner, options = {}) {
+  const token = tokenForProject(context.projectRoot, options.authToken);
+  if (!token)
+    return { ok: false, error: "missing-token", projects: [] };
+  const projects = await listGitHubProjects({ owner, token });
+  return { ok: true, projects };
+}
+async function getGitHubProjectStatusFieldInProcess(context, projectId, options = {}) {
+  const token = tokenForProject(context.projectRoot, options.authToken);
+  if (!token)
+    return { ok: false, error: "missing-token" };
+  const field = await resolveProjectStatusField({ projectId, token });
+  return { ok: true, field };
+}
+async function requestGitHubAuthJsonInProcess(context, pathname, init = {}) {
+  const method = (init.method ?? "GET").toUpperCase();
+  if (pathname === "/api/github/auth/status")
+    return getGitHubAuthStatusInProcess(context);
+  if (pathname === "/api/github/repo/permissions") {
+    return checkGitHubRepoPermissions({ projectRoot: context.projectRoot, oauthConfigured: Boolean(oauthClientId()) });
+  }
+  if (pathname === "/api/github/auth/device/start" && method === "POST") {
+    const clientId = oauthClientId();
+    if (!clientId)
+      return { ok: false, oauthConfigured: false, error: "RIG_GITHUB_OAUTH_CLIENT_ID is not configured." };
+    const body = init.body ? JSON.parse(String(init.body)) : {};
+    return beginGitHubDeviceFlow({
+      projectRoot: context.projectRoot,
+      clientId,
+      ...cleanString(body.scope) ? { scope: cleanString(body.scope) } : {},
+      selectedRepo: cleanString(body.repoSlug)
+    });
+  }
+  if (pathname === "/api/github/auth/device/poll" && method === "POST") {
+    const clientId = oauthClientId();
+    if (!clientId)
+      return { ok: false, oauthConfigured: false, error: "RIG_GITHUB_OAUTH_CLIENT_ID is not configured." };
+    const body = init.body ? JSON.parse(String(init.body)) : {};
+    const pollId = cleanString(body.pollId);
+    if (!pollId)
+      return { ok: false, status: "error", error: "pollId is required" };
+    return pollGitHubDeviceFlow({ projectRoot: context.projectRoot, clientId, pollId, selectedRepo: cleanString(body.repoSlug) });
+  }
+  throw new Error(`No in-process GitHub auth API for ${method} ${pathname}`);
+}
+export {
+  setGitHubBearerTokenForCurrentProcess,
+  requestGitHubAuthJsonInProcess,
+  postGitHubTokenInProcess,
+  listGitHubProjectsInProcess,
+  getGitHubProjectStatusFieldInProcess,
+  getGitHubAuthStatusInProcess
+};

package/dist/src/commands/_json-output.d.ts

@@ -0,0 +1,11 @@
+import { type RigCliOutputEnvelope } from "@rig/contracts";
+/**
+ * Build the versioned `{ v: 1, command, data }` envelope for a command
+ * outcome, or null when the command has no output schema (legacy payload)
+ * or the details fail validation (warned on stderr, legacy payload).
+ */
+export declare function buildCliJsonEnvelope(outcome: unknown, options?: {
+    warn?: (message: string) => void;
+}): RigCliOutputEnvelope | null;
+/** Commands with a versioned --json envelope (for help/docs/tests). */
+export declare function listSchematizedCliCommands(): string[];

package/dist/src/commands/_json-output.js

@@ -0,0 +1,54 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_json-output.ts
+import { Schema } from "effect";
+import {
+  RigDoctorCheckOutput,
+  RigInboxApprovalsOutput,
+  RigInboxInputsOutput,
+  RigRunListOutput,
+  RigRunShowOutput,
+  RigStatsOutput,
+  RigTaskListOutput,
+  RigTaskShowOutput
+} from "@rig/contracts";
+var CLI_OUTPUT_SCHEMAS = {
+  "task list": RigTaskListOutput,
+  "task show": RigTaskShowOutput,
+  "run list": RigRunListOutput,
+  "run show": RigRunShowOutput,
+  "inbox approvals": RigInboxApprovalsOutput,
+  "inbox inputs": RigInboxInputsOutput,
+  "doctor check": RigDoctorCheckOutput,
+  "stats show": RigStatsOutput
+};
+function isCommandOutcomeLike(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const record = value;
+  return typeof record.group === "string" && typeof record.command === "string";
+}
+function buildCliJsonEnvelope(outcome, options = {}) {
+  if (!isCommandOutcomeLike(outcome))
+    return null;
+  const commandKey = `${outcome.group} ${outcome.command}`;
+  const schema = CLI_OUTPUT_SCHEMAS[commandKey];
+  if (!schema)
+    return null;
+  const warn = options.warn ?? ((message) => console.error(message));
+  const envelope = { v: 1, command: commandKey, data: outcome.details ?? {} };
+  try {
+    Schema.decodeUnknownSync(schema)(JSON.parse(JSON.stringify(envelope)));
+    return envelope;
+  } catch (error) {
+    warn(`[rig] --json output for "${commandKey}" failed schema validation; printing legacy payload. ` + `(${error instanceof Error ? error.message.split(`
+`)[0] : String(error)})`);
+    return null;
+  }
+}
+function listSchematizedCliCommands() {
+  return Object.keys(CLI_OUTPUT_SCHEMAS).sort();
+}
+export {
+  listSchematizedCliCommands,
+  buildCliJsonEnvelope
+};

package/dist/src/commands/_parsers.d.ts

@@ -0,0 +1,15 @@
+import type { TaskSourceConfig } from "@rig/contracts";
+import type { RigPluginWithRuntime } from "@rig/core";
+export declare function parsePositiveInt(value: string | undefined, option: string, fallback: number): number;
+export declare function parseOptionalPositiveInt(value: string | undefined, option: string): number | undefined;
+export declare function parseRequiredPositiveInt(value: string | undefined, option: string): number;
+export declare function parseAction(value: string | undefined): "validate" | "verify" | "pipeline";
+export declare function parseIsolationMode(value: string | undefined, allowOff: true): "off" | "worktree";
+export declare function parseIsolationMode(value: string | undefined, allowOff: false): "worktree";
+export declare function parseInstallScope(value: string | undefined): "user" | "system";
+export declare function resolveInstallDir(scope: "user" | "system", explicitPath: string | undefined): string;
+export type CliRigConfig = {
+    plugins?: readonly RigPluginWithRuntime[];
+    taskSource?: TaskSourceConfig;
+};
+export declare function loadRigConfigOrNull(projectRoot: string): Promise<CliRigConfig | null>;

package/dist/src/commands/_parsers.js

@@ -0,0 +1,114 @@
+// @bun
+var __require = import.meta.require;
+
+// packages/cli-surface-plugin/src/commands/_parsers.ts
+import { homedir } from "os";
+import { resolve } from "path";
+
+// 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";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
+
+// packages/cli-surface-plugin/src/commands/_parsers.ts
+function parsePositiveInt(value, option, fallback) {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
+  }
+  return parsed;
+}
+function parseOptionalPositiveInt(value, option) {
+  if (!value) {
+    return;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
+  }
+  return parsed;
+}
+function parseRequiredPositiveInt(value, option) {
+  if (!value) {
+    throw new CliError(`Missing value for ${option}.`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} 10\`.` });
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
+  }
+  return parsed;
+}
+function parseAction(value) {
+  if (!value || value === "validate") {
+    return "validate";
+  }
+  if (value === "verify") {
+    return "verify";
+  }
+  if (value === "pipeline") {
+    return "pipeline";
+  }
+  throw new CliError(`Invalid --action value: ${value}. Use validate, verify, or pipeline.`);
+}
+function parseIsolationMode(value, allowOff) {
+  if (!value) {
+    return "worktree";
+  }
+  if (value === "worktree") {
+    return value;
+  }
+  if (allowOff && value === "off") {
+    return value;
+  }
+  throw new CliError(`Invalid isolation mode: ${value}. Use ${allowOff ? "off|" : ""}worktree.`);
+}
+function parseInstallScope(value) {
+  if (!value || value === "user") {
+    return "user";
+  }
+  if (value === "system") {
+    return "system";
+  }
+  throw new CliError(`Invalid --scope value: ${value}. Use user|system.`);
+}
+function resolveInstallDir(scope, explicitPath) {
+  if (explicitPath) {
+    return resolve(explicitPath);
+  }
+  if (scope === "system") {
+    return "/usr/local/bin";
+  }
+  return resolve(homedir(), ".local/bin");
+}
+async function loadRigConfigOrNull(projectRoot) {
+  try {
+    const { loadConfig } = await import("@rig/core/load-config");
+    return await loadConfig(projectRoot);
+  } catch {
+    return null;
+  }
+}
+export {
+  resolveInstallDir,
+  parseRequiredPositiveInt,
+  parsePositiveInt,
+  parseOptionalPositiveInt,
+  parseIsolationMode,
+  parseInstallScope,
+  parseAction,
+  loadRigConfigOrNull
+};

package/dist/src/commands/_paths.d.ts

@@ -0,0 +1,11 @@
+export declare function resolveControlPlaneMonorepoRoot(projectRoot: string): string;
+export declare function resolveControlPlaneTaskConfigPath(projectRoot: string): string;
+export declare function resolveControlPlaneHostStateRoot(projectRoot: string): string;
+export declare function resolveControlPlaneHostStateDir(projectRoot: string): string;
+export declare function resolveControlPlaneHostLogsDir(projectRoot: string): string;
+export declare function resolveControlPlaneHostBinDir(projectRoot: string): string;
+export declare function resolveControlPlaneHostDistDir(projectRoot: string): string;
+export declare function resolveControlPlaneMonorepoStateRoot(projectRoot: string): string;
+export declare function resolveControlPlaneMonorepoRuntimeDir(projectRoot: string): string;
+export declare function resolveControlPlaneArtifactsDir(projectRoot: string): string;
+export declare function resolveControlPlaneDefinitionRoot(projectRoot: string): string;

package/dist/src/commands/_paths.js

@@ -0,0 +1,50 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_paths.ts
+import { resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/runtime/layout";
+function resolveControlPlaneMonorepoRoot(projectRoot) {
+  return resolveMonorepoRoot(projectRoot);
+}
+function resolveControlPlaneTaskConfigPath(projectRoot) {
+  return resolve(resolveControlPlaneMonorepoRoot(projectRoot), ".rig", "task-config.json");
+}
+function resolveControlPlaneHostStateRoot(projectRoot) {
+  return resolve(projectRoot, ".rig");
+}
+function resolveControlPlaneHostStateDir(projectRoot) {
+  return resolve(resolveControlPlaneHostStateRoot(projectRoot), "state");
+}
+function resolveControlPlaneHostLogsDir(projectRoot) {
+  return resolve(resolveControlPlaneHostStateRoot(projectRoot), "logs");
+}
+function resolveControlPlaneHostBinDir(projectRoot) {
+  return resolve(resolveControlPlaneHostStateRoot(projectRoot), "bin");
+}
+function resolveControlPlaneHostDistDir(projectRoot) {
+  return resolve(resolveControlPlaneHostStateRoot(projectRoot), "dist");
+}
+function resolveControlPlaneMonorepoStateRoot(projectRoot) {
+  return resolve(resolveControlPlaneMonorepoRoot(projectRoot), ".rig");
+}
+function resolveControlPlaneMonorepoRuntimeDir(projectRoot) {
+  return resolve(resolveControlPlaneMonorepoStateRoot(projectRoot), "runtime");
+}
+function resolveControlPlaneArtifactsDir(projectRoot) {
+  return resolve(resolveControlPlaneMonorepoRoot(projectRoot), "artifacts");
+}
+function resolveControlPlaneDefinitionRoot(projectRoot) {
+  return resolve(projectRoot, "rig");
+}
+export {
+  resolveControlPlaneTaskConfigPath,
+  resolveControlPlaneMonorepoStateRoot,
+  resolveControlPlaneMonorepoRuntimeDir,
+  resolveControlPlaneMonorepoRoot,
+  resolveControlPlaneHostStateRoot,
+  resolveControlPlaneHostStateDir,
+  resolveControlPlaneHostLogsDir,
+  resolveControlPlaneHostDistDir,
+  resolveControlPlaneHostBinDir,
+  resolveControlPlaneDefinitionRoot,
+  resolveControlPlaneArtifactsDir
+};

package/dist/src/commands/_pi-frontend.d.ts

@@ -0,0 +1,35 @@
+import type { RunnerContext } from "../runner";
+type AttachResult = {
+    readonly run: Record<string, unknown>;
+    readonly logs: Record<string, unknown>[];
+    readonly timeline: Record<string, unknown>[];
+    readonly timelineCursor: string | null;
+    readonly steered: boolean;
+    readonly rendered: string;
+    readonly detached?: boolean;
+};
+export declare function resolveOperatorDroneCwd(runId: string, homeDir?: string): string;
+/**
+ * Compose the operator-session environment used by the legacy interactive
+ * attach shim. Exported for tests that pin the env contract.
+ */
+export declare function buildOperatorPiEnv(input: {
+    readonly runId: string;
+    readonly serverUrl: string;
+    readonly authToken?: string | null;
+    readonly serverProjectRoot?: string | null;
+    readonly sessionDir: string;
+}): Record<string, string>;
+export declare function shouldRequireOperatorTranscript(status: unknown): boolean;
+export declare function missingOperatorTranscriptMessage(runId: string, status: unknown): string;
+/**
+ * Run `body` in-process while RETURNING (instead of terminating) when it calls
+ * `process.exit`. Exported for unit tests that pin the guard semantics.
+ */
+export declare function runWithProcessExitGuard(body: () => Promise<unknown>): Promise<number>;
+export declare function attachRunBundledPiFrontend(context: Pick<RunnerContext, "projectRoot" | "outputMode">, input: {
+    readonly runId: string;
+    readonly steered?: boolean;
+    readonly returnOnQuit?: boolean;
+}): Promise<AttachResult>;
+export {};

package/dist/src/commands/_pi-frontend.js

@@ -0,0 +1,64 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/_pi-frontend.ts
+import { homedir } from "os";
+import { join } from "path";
+import { assertPathInsideRoot, assertSafeRunId, safePathSegment } from "@rig/shared/safe-identifiers";
+var TERMINAL_RUN_STATUSES = { completed: true, failed: true, stopped: true, cancelled: true, canceled: true, closed: true, merged: true, needs_attention: true, "needs-attention": true };
+function resolveOperatorDroneCwd(runId, homeDir = homedir()) {
+  const safeRunId = assertSafeRunId(runId);
+  const dronesRoot = join(homeDir, ".rig", "drones");
+  return assertPathInsideRoot(dronesRoot, join(dronesRoot, safePathSegment(String(safeRunId).slice(0, 8), { fallback: "run", maxLength: 32 })), "operator drone cwd");
+}
+function buildOperatorPiEnv(input) {
+  return {
+    PI_CODING_AGENT_SESSION_DIR: input.sessionDir,
+    PI_SKIP_VERSION_CHECK: "1",
+    PI_HIDDEN_COMMANDS: "import,fork,clone,tree,new,resume,trust",
+    RIG_PI_OPERATOR_SESSION: "1",
+    RIG_RUN_ID: input.runId,
+    RIG_SERVER_URL: input.serverUrl,
+    ...input.authToken ? { RIG_AUTH_TOKEN: input.authToken } : {},
+    ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
+  };
+}
+function shouldRequireOperatorTranscript(status) {
+  return typeof status === "string" && TERMINAL_RUN_STATUSES[status.trim().toLowerCase()] === true;
+}
+function missingOperatorTranscriptMessage(runId, status) {
+  const shortRun = runId.trim().slice(0, 8) || "unknown";
+  const statusText = typeof status === "string" && status.trim() ? status.trim() : "terminal";
+  return `Run ${shortRun} is ${statusText}, but no worker Pi session transcript is recorded for this run. It likely failed before Pi started or predates full-session capture. Use \`rig run show ${runId}\` and \`rig run logs ${runId}\` for the lifecycle details.`;
+}
+async function runWithProcessExitGuard(body) {
+  const realExit = process.exit;
+  let exitCode = 0;
+  let signalQuit = () => {};
+  const quit = new Promise((resolve) => {
+    signalQuit = resolve;
+  });
+  const guardedExit = (code) => {
+    exitCode = typeof code === "number" ? code : 0;
+    signalQuit();
+    return;
+  };
+  process.exit = guardedExit;
+  try {
+    await Promise.race([Promise.resolve().then(body), quit]);
+  } finally {
+    process.exit = realExit;
+  }
+  return exitCode;
+}
+async function attachRunBundledPiFrontend(context, input) {
+  input.steered;
+  input.returnOnQuit;
+  throw new Error(`Interactive Pi attach for run ${input.runId} was removed in the OMP-collab cutover. Run bare \`rig\` and use the OMP cockpit run detail for the live session; legacy automation can request a non-interactive text snapshot with --once or --json.`);
+}
+export {
+  shouldRequireOperatorTranscript,
+  runWithProcessExitGuard,
+  resolveOperatorDroneCwd,
+  missingOperatorTranscriptMessage,
+  buildOperatorPiEnv,
+  attachRunBundledPiFrontend
+};