@h-rig/cli 0.0.6-alpha.83 → 0.0.6-alpha.85

package/dist/src/app-opentui/theme.js

@@ -11,19 +11,25 @@ var RIG_UI = {
   bg: "#070809",
   bg2: "#0b0c0e",
   panel: "#101115",
-  panel2: "#101115",
-  glass: "#14161b",
-  ink: "#f2f3f6",
-  ink2: "#aeb0ba",
-  ink3: "#6c6e79",
-  ink4: "#44464f",
+  panel2: "#14161b",
+  glass: "#1e2230",
+  border: "#2a2e3a",
+  ink: "#f4f5f8",
+  ink2: "#c7c9d3",
+  ink3: "#9aa0ae",
+  ink4: "#787b86",
   lime: "#ccff4d",
   limeDim: "#a9d63f",
   cyan: "#56d8ff",
+  cyanDim: "#3f9fbd",
   red: "#ff5d5d",
   yellow: "#ffd24d",
   magenta: "#ff79b0"
 };
+var SELECTION_MARKER = "\u258C";
+var SELECTION_MARKER_IDLE = " ";
+var LABEL_WIDTH = 14;
+var COLUMN_GUTTER = "  ";
 var RIG_SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 var styles = {
   ink: otuiFg(RIG_UI.ink),
@@ -39,11 +45,11 @@ var styles = {
 };
 function statusColor(status) {
   switch (status) {
-    case "running":
     case "success":
     case "completed":
     case "merged":
       return RIG_UI.lime;
+    case "running":
     case "preparing":
     case "created":
     case "validating":
@@ -63,6 +69,46 @@ function statusColor(status) {
       return RIG_UI.ink3;
   }
 }
+function statusGlyph(status) {
+  switch (status) {
+    case "success":
+    case "completed":
+    case "merged":
+      return "\u2713";
+    case "running":
+      return "\u25CF";
+    case "preparing":
+    case "created":
+    case "validating":
+    case "reviewing":
+    case "closing-out":
+    case "stopping":
+    case "loading":
+    case "action":
+      return "\u25D0";
+    case "needs-attention":
+    case "needs_attention":
+      return "\u26A0";
+    case "failed":
+    case "error":
+      return "\u2717";
+    default:
+      return "\xB7";
+  }
+}
+function noColorActive() {
+  const noColor = process.env.NO_COLOR;
+  if (noColor !== undefined && noColor !== "") {
+    return true;
+  }
+  return process.env.RIG_NO_COLOR !== undefined;
+}
+function statusLabel(status) {
+  return {
+    glyph: statusGlyph(status),
+    color: noColorActive() ? RIG_UI.ink : statusColor(status)
+  };
+}
 function sceneTitle(title) {
   return t`${otuiBold(styles.ink(title))}`;
 }
@@ -75,14 +121,21 @@ function faint(text) {
 export {
   t,
   styles,
+  statusLabel,
+  statusGlyph,
   statusColor,
   sceneTitle,
+  noColorActive,
   otuiFg as fg,
   faint,
   otuiDim as dim,
   commandText,
   otuiBold as bold,
   TextAttributes,
+  SELECTION_MARKER_IDLE,
+  SELECTION_MARKER,
   RIG_UI,
-  RIG_SPINNER_FRAMES
+  RIG_SPINNER_FRAMES,
+  LABEL_WIDTH,
+  COLUMN_GUTTER
 };

package/dist/src/app-opentui/types.d.ts

@@ -1,7 +1,7 @@
 import type { StyledText } from "@opentui/core";
 import type { RunnerContext } from "../runner";
 import type { StageLayout } from "./layout";
-export type AppSceneId = "main" | "fleet" | "tasks" | "inbox" | "server" | "init" | "doctor" | "command" | "run-detail" | "handoff" | "help" | "error";
+export type AppSceneId = "main" | "fleet" | "tasks" | "inbox" | "server" | "init" | "doctor" | "command" | "run-detail" | "handoff" | "pi" | "plugin" | "repo" | "workspace" | "inspect" | "family" | "help" | "error";
 export type AppActionKind = "none" | "refresh" | "navigate" | "task-run-next" | "task-run-id" | "run-stop" | "run-attach" | "run-steer" | "inbox-approve" | "inbox-reject" | "inbox-answer" | "init-start" | "command-run" | "doctor-run";
 export type AppIntent = {
     readonly scene: AppSceneId;
@@ -22,10 +22,37 @@ export type AppFooterState = {
     readonly message?: string;
     readonly [key: string]: string | undefined;
 };
+/** Modal input model for the bottom command bar. nav = vim navigation
+ * (printable keys are shortcuts); search = live-filter the current list scene;
+ * command = type a full `rig …` command; prompt = capture one value for a
+ * pending inline action (inbox answer, run steer) without dropping to a PTY. */
+export type AppTypeBarMode = "nav" | "search" | "command" | "prompt";
+/** Describes an inline prompt: the next submitted value is folded into this
+ * intent under `payloadKey`, then dispatched. Keeps answer/steer in-app. */
+export type AppInlinePrompt = {
+    readonly label: string;
+    readonly scene: AppSceneId;
+    readonly argv: readonly string[];
+    readonly intentKind: AppActionKind;
+    readonly payloadBase: Record<string, unknown>;
+    readonly payloadKey: string;
+    /** When true, the typed value is tokenized and appended to `argv` (for
+     * collecting a parameterized command's args before running it) rather than
+     * folded into the action payload. Used by the actionable command catalog (#21). */
+    readonly appendValueToArgv?: boolean;
+};
 export type AppTypeBarState = {
     readonly value: string;
     readonly placeholder: string;
     readonly message?: string;
+    readonly mode?: AppTypeBarMode;
+    readonly prompt?: AppInlinePrompt;
+};
+/** A pending confirmation gate for a destructive action (#16). The held intent
+ * only dispatches on an explicit second Enter; esc cancels. */
+export type AppConfirmState = {
+    readonly label: string;
+    readonly intent: AppIntent;
 };
 export type AppErrorState = {
     readonly message: string;
@@ -42,6 +69,55 @@ export type AppSelectableItem = {
     readonly data?: Record<string, unknown>;
     readonly intent?: AppIntent;
     readonly message?: string;
+    /** Activating this item opens an inline prompt instead of dispatching an
+     * intent — the typed value is folded into the action (#15). */
+    readonly prompt?: AppInlinePrompt;
+};
+/** Typed state.data slices (#7). Scalar selections/flags are precisely typed so
+ * their reads don't need casts; heterogeneous server-record slices stay `unknown`
+ * (consumers narrow them) and the index signature keeps dynamic writes compiling.
+ * This retires the untyped `Record<string, unknown>` bag while staying compatible
+ * with every existing patch site. */
+export type AppData = {
+    readonly selectedRunId?: string;
+    readonly selectedTaskId?: string;
+    /** When set, the tasks scene shows that task's dedicated DETAIL screen
+     * (native-markdown body + actions) instead of the list (#3/#5/#7). */
+    readonly taskDetailId?: string;
+    readonly selectedInboxRequestId?: string;
+    readonly projectConfigured?: boolean;
+    readonly lastRefreshError?: string;
+    readonly fleet?: unknown;
+    readonly tasks?: unknown;
+    readonly inbox?: unknown;
+    readonly inboxOptimistic?: unknown;
+    readonly server?: unknown;
+    readonly runDetail?: unknown;
+    readonly inspect?: unknown;
+    /** Active sub-view of the inspect scene (logs/timeline/diff/failures). */
+    readonly inspectView?: string;
+    readonly pi?: unknown;
+    readonly plugin?: unknown;
+    readonly repo?: unknown;
+    readonly workspace?: unknown;
+    readonly piTerminal?: unknown;
+    readonly commandTerminal?: unknown;
+    /** Generic family-browser slice: the active family's catalog + live state. */
+    readonly family?: unknown;
+    /** Which CLI family the family scene is currently showing. */
+    readonly familyName?: string;
+    /** In-progress command-form state (selected subcommand + adapted field values). */
+    readonly familyForm?: unknown;
+    /** The drilled-into item id within the active family's bespoke surface — when
+     * set, the renderer shows that item's dedicated DETAIL screen (#5). */
+    readonly familyDrillId?: string;
+    readonly piAttach?: unknown;
+    readonly handoff?: unknown;
+    readonly doctor?: unknown;
+    readonly init?: unknown;
+    readonly dispatchingRun?: unknown;
+    readonly latestSubmittedRun?: unknown;
+    readonly [key: string]: unknown;
 };
 export type AppState = {
     readonly projectRoot: string;
@@ -53,16 +129,22 @@ export type AppState = {
     readonly typeBar: AppTypeBarState;
     readonly footer: AppFooterState;
     readonly selection: AppSelectionState;
-    readonly data: Record<string, unknown>;
+    readonly data: AppData;
     readonly runtimeReady: boolean;
     readonly actionLabel?: string;
     readonly error?: AppErrorState;
+    /** Scene back-stack for esc-pops-one-level navigation (#13). */
+    readonly history: readonly AppSceneId[];
+    /** Pending destructive-action confirmation gate (#16). */
+    readonly confirm?: AppConfirmState;
+    /** Wall-clock ms of the last successful data refresh, for "updated Ns ago" (#14). */
+    readonly dataUpdatedAtMs?: number;
 };
 export type AppStatePatch = Omit<Partial<AppState>, "typeBar" | "footer" | "selection" | "data"> & {
     readonly typeBar?: Partial<AppTypeBarState>;
     readonly footer?: Partial<AppFooterState>;
     readonly selection?: Partial<AppSelectionState>;
-    readonly data?: Record<string, unknown>;
+    readonly data?: AppData;
 };
 export type AppEvent = {
     readonly type: "scene.change";
@@ -104,6 +186,11 @@ export type AppEvent = {
     readonly message: string;
     readonly hint?: string;
     readonly cause?: unknown;
+} | {
+    readonly type: "confirm.request";
+    readonly confirm: AppConfirmState;
+} | {
+    readonly type: "confirm.cancel";
 };
 export type AppStore = {
     getState(): AppState;
@@ -123,8 +210,15 @@ export type AppSceneLine = {
     readonly bold?: boolean;
     readonly dim?: boolean;
     readonly align?: "left" | "center" | "right";
-    /** Zero-based selectable item index for keyboard/mouse navigation. */
+    /** Compacted selectable index into the rendered item list. Derived by the
+     * runtime at render time from `selectable`; scenes never set this directly. */
     readonly selectableIndex?: number;
+    /** Stable id of the selectable item this line activates. Derived from
+     * `selectable.id` at render time so clicks match by id, not position (#12). */
+    readonly selectableId?: string;
+    /** The full selectable item this line activates. The runtime DERIVES the
+     * scene's selectable list from these (single source of truth, #6/#12). */
+    readonly selectable?: AppSelectableItem;
     /** Activate on single click instead of only selecting/double-clicking. */
     readonly activateOnClick?: boolean;
 };
@@ -164,6 +258,27 @@ export type AppSceneFrame = {
     readonly hideTypeBar?: boolean;
     /** Raw keypresses should be forwarded to the embedded terminal host. */
     readonly terminalActive?: boolean;
+    /** Render this content with a NATIVE OpenTUI component (Tree-sitter code,
+     * diff, or markdown) inside a scrollbox, instead of the AppSceneLine pipeline
+     * (#7). The scene's own `lines` still render around it (header/tabs). */
+    readonly native?: AppNativeMount;
+};
+/** A scene's request to mount a native OpenTUI renderable in a panel rectangle. */
+export type AppNativeMount = {
+    readonly kind: "code" | "diff" | "markdown" | "table";
+    /** Source/diff/markdown text for code/diff/markdown kinds. */
+    readonly content: string;
+    /** Rows for `kind: "table"` — the first row is the header. Rendered with the
+     * native TextTableRenderable (read-only dense tables). */
+    readonly rows?: readonly (readonly string[])[];
+    /** Tree-sitter filetype for `kind: "code"` (e.g. "typescript", "json"). */
+    readonly filetype?: string;
+    readonly top?: number;
+    readonly left?: number;
+    readonly width?: number;
+    readonly height?: number;
+    /** Pin scroll to the bottom (log/diff tails). */
+    readonly stickyBottom?: boolean;
 };
 export type AppSceneRenderer = (state: AppState, layout?: StageLayout) => AppSceneFrame;
 export type AppRuntime = {
@@ -172,6 +287,8 @@ export type AppRuntime = {
     emit(event: AppEvent): void;
     setScene(scene: AppSceneId, intent?: AppIntent): void;
     runIntent(intent: AppIntent): Promise<void>;
+    /** Pop the scene back-stack one level (esc), refreshing the target (#13). */
+    goBack(): Promise<void>;
     getRunnerContext(): Promise<RunnerContext>;
     suspend(): void;
     resume(): void;

package/dist/src/commands/_authority-runs.d.ts

@@ -2,7 +2,7 @@ import { type AuthorityRunRecord } from "@rig/runtime/control-plane/authority-fi
 import type { RunStatus } from "@rig/contracts";
 export declare const RIG_WORKSPACE_ID = "rig-local-workspace";
 export type RuntimeAdapter = "claude-code" | "codex" | "pi";
-export declare function normalizeRuntimeAdapter(value: string | undefined): RuntimeAdapter;
+export declare function normalizeRuntimeAdapter(_value: string | undefined): RuntimeAdapter;
 export declare function readLatestBeadRecord(projectRoot: string, taskId: string): Record<string, unknown> | null;
 export declare function upsertAgentAuthorityRun(projectRoot: string, input: {
     runId: string;

package/dist/src/commands/_authority-runs.js

@@ -16,18 +16,8 @@ function resolveControlPlaneMonorepoRoot(projectRoot) {
 
 // packages/cli/src/commands/_authority-runs.ts
 var RIG_WORKSPACE_ID = "rig-local-workspace";
-function normalizeRuntimeAdapter(value) {
-  const normalized = value?.trim().toLowerCase();
-  if (!normalized) {
-    return "pi";
-  }
-  if (normalized === "codex" || normalized === "codex-cli" || normalized === "codex-app-server" || normalized === "gpt-codex") {
-    return "codex";
-  }
-  if (normalized === "pi" || normalized === "rig-pi" || normalized === "@rig/pi") {
-    return "pi";
-  }
-  return "claude-code";
+function normalizeRuntimeAdapter(_value) {
+  return "pi";
 }
 function readLatestBeadRecord(projectRoot, taskId) {
   const issuesPath = resolve(resolveControlPlaneMonorepoRoot(projectRoot), ".beads", "issues.jsonl");

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

@@ -254,30 +254,62 @@ var PRIMARY_GROUPS = [
   }
 ];
 var ADVANCED_GROUPS = [
-  { name: "setup", summary: "Bootstrap/check local setup.", usage: ["rig setup <bootstrap|check|preflight>"], commands: [{ command: "bootstrap|check|preflight", description: "Setup helpers." }] },
-  { name: "profile", summary: "Runtime profile/model defaults.", usage: ["rig profile <show|set>"], commands: [{ command: "show", description: "Show active profile." }] },
+  {
+    name: "setup",
+    summary: "Bootstrap/check local setup.",
+    usage: ["rig setup <bootstrap|check|preflight>"],
+    commands: [
+      { command: "bootstrap", description: "Bootstrap local setup dependencies.", primary: true },
+      { command: "check", description: "Check local setup state (toolchain, deps, config).", primary: true },
+      { command: "preflight", description: "Run preflight checks before a 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 greptile]", description: "Change review strictness/provider." }
+      { 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: ["Use `rig inbox approvals` for blocked run handoffs."]
   },
   {
     name: "browser",
-    summary: "Browser/app diagnostics for browser-required tasks.",
-    usage: ["rig browser <help|explain|demo|app|hp-next> [options]"],
+    summary: "Browser workstation actions for browser-required tasks: launch, check, CDP probe, profile reset, and app-specific smokes.",
+    usage: ["rig browser <help|explain|demo|hp-next|cdp-probe|profile-persistence|profile-lock-check|smoke-test> [options]"],
     commands: [
-      { command: "help", description: "Rich browser command help (canonical: `rig browser help`)." },
-      { command: "explain", description: "Explain the browser-required task contract." },
-      { command: "demo", description: "Run browser demo flows against a local page." },
-      { command: "app", description: "Launch the Rig Browser workstation app." },
-      { command: "hp-next <dev|check|e2e|reset>", description: "Drive the hp-next browser test harness." }
-    ]
+      { command: "help", description: "Rich browser command help (canonical: `rig browser help`).", primary: true },
+      { command: "explain", description: "Explain the browser-required task contract and runtime helper commands.", primary: true },
+      { command: "demo [--port <n>] [--profile <name>] [--state-dir <path>] [--target-url <url>] [--keep-open] [--no-build]", description: "Run a guided real browser/agent demo flow.", primary: true },
+      { command: "hp-next dev", description: "Start hp-next Rig Browser in dev/watch mode.", primary: true },
+      { command: "hp-next start", description: "Build/start the hp-next browser workstation without watch mode.", primary: true },
+      { command: "hp-next check", description: "Validate the hp-next CDP endpoint on the configured port.", primary: true },
+      { command: "hp-next e2e", description: "Run hp-next browser e2e smoke checks through Rig Browser.", primary: true },
+      { command: "hp-next reset", description: "Reset the hp-next browser profile when stale browser state is suspected.", primary: true },
+      { command: "cdp-probe", description: "Run an isolated CDP attach/evaluate/layout probe." },
+      { command: "profile-persistence", description: "Verify a named browser profile persists browser state." },
+      { command: "profile-lock-check", description: "Verify concurrent launches reject the same profile." },
+      { command: "smoke-test", description: "Run the browser package smoke test." }
+    ],
+    examples: [
+      "rig browser help",
+      "rig browser hp-next check",
+      "rig browser hp-next e2e",
+      "rig browser cdp-probe",
+      "rig browser profile-lock-check"
+    ],
+    next: ["Inside a task run, use rig-browser-launch, rig-browser-check, and rig-browser-attach-info from the worker PATH."]
   },
   {
     name: "pi",
@@ -292,12 +324,60 @@ var ADVANCED_GROUPS = [
     examples: ["rig pi search subagents", "rig pi add pi-subagents", "rig pi list"],
     next: ["Config-managed extensions: declare `runtime: { pi: { packages: [...] } }` in rig.config.ts \u2014 workers pick them up automatically."]
   },
-  { name: "queue", summary: "Run task queues locally.", usage: ["rig queue run [options]"], commands: [{ command: "run", description: "Process queue work." }] },
-  { name: "agent", summary: "Runtime agent workspace helpers.", usage: ["rig agent <list|prepare|run|cleanup>"], commands: [{ command: "list", description: "List prepared agents." }] },
+  {
+    name: "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: "inspector", summary: "Event stream and drift scanners.", usage: ["rig inspector <stream|scan-upstream-drift>"], commands: [{ command: "stream", description: "Stream events." }] },
-  { name: "dist", summary: "Build/install packaged Rig CLI.", usage: ["rig dist <build|install|doctor>"], commands: [{ command: "build", description: "Build distribution." }] },
+  {
+    name: "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: "Compatibility remote orchestration controls.", usage: ["rig remote <status|watch|pause|resume|...>"], commands: [{ command: "status", description: "Show remote state." }] },
+  {
+    name: "remote",
+    summary: "Compatibility 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: "Show the remote orchestration state.", primary: true },
+      { command: "tasks [--remote <alias>]", description: "List the remote's tracked tasks.", primary: true },
+      { command: "watch [--remote <alias>] [--seconds <n>] [--event <type>]", description: "Stream remote orchestration events.", primary: true },
+      { command: "pause [--remote <alias>]", description: "Pause the running remote orchestration.", primary: true },
+      { command: "resume [--remote <alias>] [--max-workers <n>] [--max-iterations <n>] [--direct-merge]", description: "Resume the remote with optional tuning.", primary: true },
+      { command: "continue [--remote <alias>]", description: "Continue a paused remote orchestration.", primary: true },
+      { command: "stop [--remote <alias>]", description: "Stop the remote orchestration.", primary: true },
+      { command: "refresh [--remote <alias>]", description: "Refresh remote state.", primary: true },
+      { command: "add-iterations [--count <n>] [--remote <alias>]", description: "Grant the remote more iterations.", primary: true },
+      { command: "remove-iterations [--count <n>] [--remote <alias>]", description: "Reduce the remote's iteration budget.", primary: true },
+      { command: "endpoint list", description: "List configured remote endpoints.", primary: true },
+      { command: "endpoint add --alias <alias> --host <host> --port <n> [--token <token>]", description: "Register a remote endpoint.", primary: true },
+      { command: "endpoint remove --alias <alias>", description: "Remove a remote endpoint.", primary: true },
+      { command: "endpoint test [--alias <alias>]", description: "Test connectivity to a remote endpoint.", primary: true },
+      { command: "endpoint doctor", description: "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." }] }

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

@@ -819,6 +819,14 @@ async function withSpinner(label, work, options = {}) {
 }
 
 // packages/cli/src/commands/_pi-frontend.ts
+var TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
+
+class OperatorTranscriptUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OperatorTranscriptUnavailableError";
+  }
+}
 function setTemporaryEnv(updates) {
   const previous = new Map;
   for (const [key, value] of Object.entries(updates)) {
@@ -846,6 +854,23 @@ function buildOperatorPiEnv(input) {
     ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
   };
 }
+function shouldRequireOperatorTranscript(status) {
+  return typeof status === "string" && TERMINAL_RUN_STATUSES.has(status.trim().toLowerCase());
+}
+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.`;
+}
+function statusFromRunDetails(run) {
+  if (!run || typeof run !== "object" || Array.isArray(run))
+    return;
+  const record = run;
+  if (typeof record.status === "string")
+    return record.status;
+  const nested = record.run;
+  return nested && typeof nested === "object" && !Array.isArray(nested) ? nested.status : undefined;
+}
 async function prepareOperatorConsole(context, runId, tempSessionDir) {
   const server = await ensureServerForCli(context.projectRoot);
   const localCwd = join(homedir2(), ".rig", "drones", runId.slice(0, 8));
@@ -875,6 +900,13 @@ async function prepareOperatorConsole(context, runId, tempSessionDir) {
       sessionFileArg = ["--session", localSessionPath];
     }
   } catch {}
+  if (sessionFileArg.length === 0) {
+    const run = await getRunDetailsViaServer(context, runId).catch(() => null);
+    const status = statusFromRunDetails(run);
+    if (shouldRequireOperatorTranscript(status)) {
+      throw new OperatorTranscriptUnavailableError(missingOperatorTranscriptMessage(runId, status));
+    }
+  }
   return { server, sessionFileArg };
 }
 var RIG_PI_THEME = {
@@ -1022,7 +1054,7 @@ async function attachRunBundledPiFrontend(context, input) {
 }
 
 // packages/cli/src/commands/_operator-view.ts
-var TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
+var TERMINAL_RUN_STATUSES2 = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
 function runStatusFromPayload(payload) {
   const run = payload.run && typeof payload.run === "object" && !Array.isArray(payload.run) ? payload.run : payload;
   return String(run.status ?? "unknown").toLowerCase();
@@ -1100,7 +1132,7 @@ async function attachRunOperatorView(context, input) {
     }
     const pollMs = Math.max(250, Math.trunc(input.pollMs ?? 2000));
     let timelineCursor = snapshot.timelineCursor;
-    while (!detached && !TERMINAL_RUN_STATUSES.has(runStatusFromPayload(snapshot.run))) {
+    while (!detached && !TERMINAL_RUN_STATUSES2.has(runStatusFromPayload(snapshot.run))) {
       await Bun.sleep(pollMs);
       snapshot = await readOperatorSnapshot(context, input.runId, { timelineCursor });
       timelineCursor = snapshot.timelineCursor;

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

@@ -20,6 +20,8 @@ export declare function buildOperatorPiEnv(input: {
     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;
 export declare function attachRunBundledPiFrontend(context: Pick<RunnerContext, "projectRoot" | "outputMode">, input: {
     readonly runId: string;
     readonly steered?: boolean;

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

@@ -585,6 +585,14 @@ async function withSpinner(label, work, options = {}) {
 }
 
 // packages/cli/src/commands/_pi-frontend.ts
+var TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
+
+class OperatorTranscriptUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OperatorTranscriptUnavailableError";
+  }
+}
 function setTemporaryEnv(updates) {
   const previous = new Map;
   for (const [key, value] of Object.entries(updates)) {
@@ -612,6 +620,23 @@ function buildOperatorPiEnv(input) {
     ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
   };
 }
+function shouldRequireOperatorTranscript(status) {
+  return typeof status === "string" && TERMINAL_RUN_STATUSES.has(status.trim().toLowerCase());
+}
+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.`;
+}
+function statusFromRunDetails(run) {
+  if (!run || typeof run !== "object" || Array.isArray(run))
+    return;
+  const record = run;
+  if (typeof record.status === "string")
+    return record.status;
+  const nested = record.run;
+  return nested && typeof nested === "object" && !Array.isArray(nested) ? nested.status : undefined;
+}
 async function prepareOperatorConsole(context, runId, tempSessionDir) {
   const server = await ensureServerForCli(context.projectRoot);
   const localCwd = join(homedir2(), ".rig", "drones", runId.slice(0, 8));
@@ -641,6 +666,13 @@ async function prepareOperatorConsole(context, runId, tempSessionDir) {
       sessionFileArg = ["--session", localSessionPath];
     }
   } catch {}
+  if (sessionFileArg.length === 0) {
+    const run = await getRunDetailsViaServer(context, runId).catch(() => null);
+    const status = statusFromRunDetails(run);
+    if (shouldRequireOperatorTranscript(status)) {
+      throw new OperatorTranscriptUnavailableError(missingOperatorTranscriptMessage(runId, status));
+    }
+  }
   return { server, sessionFileArg };
 }
 var RIG_PI_THEME = {
@@ -787,6 +819,8 @@ async function attachRunBundledPiFrontend(context, input) {
   };
 }
 export {
+  shouldRequireOperatorTranscript,
+  missingOperatorTranscriptMessage,
   buildOperatorPiEnv,
   attachRunBundledPiFrontend
 };

package/dist/src/commands/_server-events.d.ts

@@ -0,0 +1,26 @@
+export type RigLiveStatus = "connecting" | "connected" | "disconnected";
+export type RigLiveHandlers = {
+    /** Any snapshot-affecting change (run/task/inbox state). The canonical
+     * "something changed, re-pull what you show" signal. */
+    readonly onSnapshotInvalidated?: (payload: unknown) => void;
+    /** A run appended a log/timeline line — for live run-detail tails. */
+    readonly onRunLogAppended?: (payload: unknown) => void;
+    /** Sequence-numbered engine domain events. */
+    readonly onEngineEvent?: (payload: unknown) => void;
+    /** Socket health transitions; callers gate their polling fallback on this. */
+    readonly onStatus?: (status: RigLiveStatus) => void;
+};
+export type RigLiveSubscription = {
+    /** True while the push socket is connected — gate HTTP fallback polling on it. */
+    readonly connected: () => boolean;
+    readonly close: () => void;
+};
+/** http(s):// → ws(s)://, with the auth token as the `token` query param the
+ * server's upgrade handler authenticates against (packages/server/src/
+ * websocket.ts). Mirrors pi-rig's buildRigWebSocketUrl so every surface speaks
+ * the same dialect. */
+export declare function buildRigWebSocketUrl(baseUrl: string, authToken: string | null): string;
+/** Open a reconnecting push subscription to the Rig server for a project root.
+ * Resolves the same connection (local/remote + auth) the HTTP `…ViaServer`
+ * calls use, so the socket targets the exact server the surface reads from. */
+export declare function connectRigServerEvents(projectRoot: string, handlers: RigLiveHandlers): Promise<RigLiveSubscription>;