@h-rig/cli 0.0.6-alpha.10 → 0.0.6-alpha.100

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

@@ -0,0 +1,146 @@
+// @bun
+// packages/cli/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) {
+  return commands.map((entry) => commandLine(entry.command, entry.description)).join(`
+`);
+}
+function renderGroup(group) {
+  const lines = [
+    `${heading(`rig ${group.name}`)} \u2014 ${group.summary}`,
+    "",
+    pc.bold("Usage"),
+    ...group.usage.map((line) => `  ${line}`),
+    "",
+    pc.bold("Commands"),
+    ...group.commands.map((entry) => commandLine(entry.command, entry.description))
+  ];
+  if (group.examples?.length) {
+    lines.push("", pc.bold("Examples"), ...group.examples.map((line) => `  ${pc.dim("$")} ${line}`));
+  }
+  if (group.next?.length) {
+    lines.push("", pc.bold("Next steps"), ...group.next.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  if (group.advanced?.length) {
+    lines.push("", pc.bold("Compatibility / advanced"), ...group.advanced.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  return lines.join(`
+`);
+}
+function renderTopLevelHelp() {
+  return [
+    `${heading("rig")} ${pc.dim("\u2014 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/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,
+      scope: cleanString(body.scope) ?? undefined,
+      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,60 @@
+// @bun
+// packages/cli/src/commands/_json-output.ts
+import { Schema } from "effect";
+import {
+  RigDoctorCheckOutput,
+  RigInboxApprovalsOutput,
+  RigInboxInputsOutput,
+  RigRunListOutput,
+  RigRunShowOutput,
+  RigServerRepairLinkOutput,
+  RigServerStatusOutput,
+  RigServerUseOutput,
+  RigStatsOutput,
+  RigTaskListOutput,
+  RigTaskShowOutput
+} from "@rig/contracts";
+var CLI_OUTPUT_SCHEMAS = {
+  "task list": RigTaskListOutput,
+  "task show": RigTaskShowOutput,
+  "run list": RigRunListOutput,
+  "run show": RigRunShowOutput,
+  "server use": RigServerUseOutput,
+  "server status": RigServerStatusOutput,
+  "server repair-link": RigServerRepairLinkOutput,
+  "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/_lazy-reconcile.d.ts

@@ -0,0 +1,34 @@
+import { SessionManager } from "@oh-my-pi/pi-coding-agent";
+import { type CollabRegistryFilter, type CollabSessionProjection } from "@oh-my-pi/pi-coding-agent/collab/api";
+import { type RunJournalProjection, type RunSessionCustomEntry } from "@rig/contracts";
+type SessionWriter = {
+    appendCustomEntry(customType: string, data: unknown): void;
+};
+export type CollabSessionProjectionLike = Pick<CollabSessionProjection, "collab" | "customEntries" | "source"> & {
+    readonly runId?: string;
+    readonly session: Pick<CollabSessionProjection["session"], "path" | "id">;
+};
+export type ProjectRunProjection = Pick<RunJournalProjection, "status">;
+export type ProjectRunFromSession = (source: Pick<SessionManager, "getEntries"> | ReadonlyArray<RunSessionCustomEntry> | readonly unknown[], runId: string) => ProjectRunProjection;
+export type LazyReconcileFlippedRun = {
+    readonly runId: string;
+    readonly sessionPath: string;
+    readonly reason: "lazy-reconcile:dead-pid";
+};
+export type LazyReconcileResult = {
+    readonly flipped: readonly LazyReconcileFlippedRun[];
+    readonly resumable: readonly LazyReconcileFlippedRun[];
+};
+type LazyReconcileDeps = {
+    readonly listCollabSessionProjections?: (filter: CollabRegistryFilter) => Promise<readonly CollabSessionProjectionLike[]>;
+    readonly projectRunFromSession?: ProjectRunFromSession;
+    readonly processExists?: (pid: number) => boolean;
+    readonly openSession?: (sessionPath: string) => Promise<SessionWriter>;
+    readonly nowIso?: () => string;
+};
+export type LazyReconcileInput = {
+    readonly workspaceRoot: string;
+    readonly identityFilter: CollabRegistryFilter;
+};
+export declare function runLazyReconcile(input: LazyReconcileInput, deps?: LazyReconcileDeps): Promise<LazyReconcileResult>;
+export {};

package/dist/src/commands/_lazy-reconcile.js

@@ -0,0 +1,102 @@
+// @bun
+var __require = import.meta.require;
+
+// packages/cli/src/commands/_lazy-reconcile.ts
+import { SessionManager } from "@oh-my-pi/pi-coding-agent";
+import {
+  listCollabSessionProjections as ompListCollabSessionProjections
+} from "@oh-my-pi/pi-coding-agent/collab/api";
+import {
+  CUSTOM_TYPE_FOR,
+  isTerminalRunStatus
+} from "@rig/contracts";
+var ACTIVE_LOCAL_RUN_STATUSES = new Set([
+  "created",
+  "preparing",
+  "running",
+  "validating",
+  "reviewing",
+  "closing-out"
+]);
+function processExists(pid) {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function defaultProjectRunFromSession(source, runId) {
+  const mod = await import("@rig/runtime/control-plane/run-session-projection");
+  const candidate = Reflect.get(mod, "projectRunFromSession");
+  if (typeof candidate !== "function") {
+    throw new Error("@rig/runtime/control-plane/run-session-projection does not export projectRunFromSession yet; inject projectRunFromSession until RunState lands it.");
+  }
+  return candidate(source, runId);
+}
+async function defaultOpenSession(sessionPath) {
+  return await SessionManager.open(sessionPath, undefined, undefined, { suppressBreadcrumb: true });
+}
+function projectionRunId(item) {
+  if (item.runId?.trim())
+    return item.runId.trim();
+  if (item.collab?.sessionId?.trim())
+    return item.collab.sessionId.trim();
+  if (item.session.id?.trim())
+    return item.session.id.trim();
+  return null;
+}
+function isLocallyDiscovered(item) {
+  return item.source === "session-list";
+}
+function isActiveStatus(status) {
+  if (status === null)
+    return false;
+  return !isTerminalRunStatus(status);
+}
+function shouldFlip(item, status, exists) {
+  if (!isActiveStatus(status))
+    return false;
+  if (item.collab?.stale === true)
+    return true;
+  const pid = item.collab?.pid;
+  return isLocallyDiscovered(item) && pid !== undefined && ACTIVE_LOCAL_RUN_STATUSES.has(status) && !exists(pid);
+}
+function failedStatusData(status, at) {
+  return {
+    type: "status-changed",
+    from: status,
+    to: "failed",
+    reason: "lazy-reconcile:dead-pid",
+    actor: { kind: "agent" },
+    at
+  };
+}
+async function runLazyReconcile(input, deps = {}) {
+  const listProjections = deps.listCollabSessionProjections ?? ompListCollabSessionProjections;
+  const projectRun = deps.projectRunFromSession ?? defaultProjectRunFromSession;
+  const exists = deps.processExists ?? processExists;
+  const openSession = deps.openSession ?? defaultOpenSession;
+  const nowIso = deps.nowIso ?? (() => new Date().toISOString());
+  const projections = await listProjections(input.identityFilter);
+  const flipped = [];
+  for (const item of projections) {
+    const runId = projectionRunId(item);
+    const sessionPath = item.session.path || item.collab?.sessionPath || "";
+    if (!runId || !sessionPath)
+      continue;
+    const projection = await projectRun(item.customEntries, runId);
+    const status = projection.status;
+    if (status === null || !shouldFlip(item, status, exists))
+      continue;
+    const session = await openSession(sessionPath);
+    session.appendCustomEntry(CUSTOM_TYPE_FOR["status-changed"], failedStatusData(status, nowIso()));
+    flipped.push({ runId, sessionPath, reason: "lazy-reconcile:dead-pid" });
+  }
+  return { flipped, resumable: flipped };
+}
+export {
+  runLazyReconcile
+};

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

@@ -7,12 +7,19 @@ import { resolve } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 
 // packages/cli/src/commands/_parsers.ts
 function parsePositiveInt(value, option, fallback) {
@@ -21,7 +28,7 @@ function parsePositiveInt(value, option, fallback) {
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
@@ -31,17 +38,17 @@ function parseOptionalPositiveInt(value, option) {
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    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 CliError2(`Missing value for ${option}.`);
+    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 CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
@@ -55,7 +62,7 @@ function parseAction(value) {
   if (value === "pipeline") {
     return "pipeline";
   }
-  throw new CliError2(`Invalid --action value: ${value}. Use validate, verify, or pipeline.`);
+  throw new CliError(`Invalid --action value: ${value}. Use validate, verify, or pipeline.`);
 }
 function parseIsolationMode(value, allowOff) {
   if (!value) {
@@ -67,7 +74,7 @@ function parseIsolationMode(value, allowOff) {
   if (allowOff && value === "off") {
     return value;
   }
-  throw new CliError2(`Invalid isolation mode: ${value}. Use ${allowOff ? "off|" : ""}worktree.`);
+  throw new CliError(`Invalid isolation mode: ${value}. Use ${allowOff ? "off|" : ""}worktree.`);
 }
 function parseInstallScope(value) {
   if (!value || value === "user") {
@@ -76,7 +83,7 @@ function parseInstallScope(value) {
   if (value === "system") {
     return "system";
   }
-  throw new CliError2(`Invalid --scope value: ${value}. Use user|system.`);
+  throw new CliError(`Invalid --scope value: ${value}. Use user|system.`);
 }
 function resolveInstallDir(scope, explicitPath) {
   if (explicitPath) {

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

@@ -1,7 +1,7 @@
 // @bun
 // packages/cli/src/commands/_paths.ts
 import { resolve } from "path";
-import { resolveMonorepoRoot } from "@rig/runtime/control-plane/native/utils";
+import { resolveMonorepoRoot } from "@rig/runtime/layout";
 function resolveControlPlaneMonorepoRoot(projectRoot) {
   return resolveMonorepoRoot(projectRoot);
 }

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 {};