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

package/dist/src/commands/_policy.js

@@ -1,36 +1,85 @@
 // @bun
 // packages/cli/src/commands/_policy.ts
-import { appendFileSync, mkdirSync } from "fs";
-import { resolve } from "path";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { resolve as resolve2 } 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();
+    }
+  }
+}
 function formatCommand(parts) {
   return parts.map((part) => /[^a-zA-Z0-9_./:-]/.test(part) ? JSON.stringify(part) : part).join(" ");
 }
 
+// packages/cli/src/commands/_paths.ts
+import { resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/runtime/layout";
+function resolveControlPlaneHostStateRoot(projectRoot) {
+  return resolve(projectRoot, ".rig");
+}
+function resolveControlPlaneHostLogsDir(projectRoot) {
+  return resolve(resolveControlPlaneHostStateRoot(projectRoot), "logs");
+}
+function resolveControlPlaneDefinitionRoot(projectRoot) {
+  return resolve(projectRoot, "rig");
+}
+
 // packages/cli/src/commands/_policy.ts
-import { evaluate as evaluate2, loadPolicy as loadPolicy2, resolveAction as resolveAction2 } from "@rig/runtime/control-plane/runtime/guard";
-import { resolveHarnessPaths } from "@rig/runtime/control-plane/native/utils";
+function loadPolicyFile(projectRoot) {
+  const policyPath = resolve2(resolveControlPlaneDefinitionRoot(projectRoot), "policy", "policy.json");
+  if (!existsSync(policyPath)) {
+    return { mode: "observe", rules: [] };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(policyPath, "utf8"));
+    const mode = parsed.mode === "off" || parsed.mode === "observe" || parsed.mode === "enforce" ? parsed.mode : "observe";
+    const rules = Array.isArray(parsed.rules) ? parsed.rules.filter((value) => Boolean(value && typeof value === "object" && !Array.isArray(value))).map((value, index) => ({
+      id: typeof value.id === "string" && value.id.trim() ? value.id.trim() : `rule-${index + 1}`,
+      reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+      match: typeof value.match === "string" && value.match.trim() ? value.match.trim() : undefined,
+      command: typeof value.command === "string" && value.command.trim() ? value.command.trim() : undefined
+    })) : [];
+    return { mode, rules };
+  } catch {
+    return { mode: "observe", rules: [] };
+  }
+}
+function matchingRules(command, rules) {
+  return rules.filter((rule) => {
+    const rawPattern = rule.command ?? rule.match;
+    if (!rawPattern)
+      return false;
+    try {
+      return new RegExp(rawPattern, "i").test(command);
+    } catch {
+      return command.includes(rawPattern);
+    }
+  });
+}
 function resolveEffectivePolicyMode(context) {
   const envMode = process.env.RIG_BASH_MODE;
   if (envMode === "off" || envMode === "observe" || envMode === "enforce") {
     return envMode;
   }
-  return context.policyMode || loadPolicy2(context.projectRoot).mode;
+  return context.policyMode ?? loadPolicyFile(context.projectRoot).mode;
 }
 function appendControlledBashAudit(context, mode, command, args, matchedRuleIds, action) {
   if (mode === "off") {
     return;
   }
-  const logsDir = resolveHarnessPaths(context.projectRoot).logsDir;
-  const logFile = resolve(logsDir, "controlled-bash.jsonl");
+  const logsDir = resolveControlPlaneHostLogsDir(context.projectRoot);
+  const logFile = resolve2(logsDir, "controlled-bash.jsonl");
   mkdirSync(logsDir, { recursive: true });
   const payload = {
     timestamp: new Date().toISOString(),
@@ -51,25 +100,24 @@ function appendControlledBashAudit(context, mode, command, args, matchedRuleIds,
 async function enforceNativeCommandPolicy(context, args, options) {
   const mode = resolveEffectivePolicyMode(context);
   const command = formatCommand([options.commandPrefix, ...args]);
-  const decision = evaluate2({
-    projectRoot: context.projectRoot,
-    evaluation: { type: "command", command }
-  });
-  const action = resolveAction2(mode, decision.matchedRules);
-  const matchedRuleIds = decision.matchedRules.map((rule) => rule.id);
+  const rules = matchingRules(command, loadPolicyFile(context.projectRoot).rules);
+  const matchedRuleIds = rules.map((rule) => rule.id);
+  const action = rules.length === 0 ? "allow" : mode === "enforce" ? "block" : "warn";
   await context.emitEvent("policy.decision", {
     target: "command",
     command,
     mode,
     allowed: action !== "block",
     matchedRuleIds,
-    reasons: decision.matchedRules.map((rule) => rule.reason)
+    reasons: rules.map((rule) => rule.reason).filter(Boolean)
   });
   if (options.writeAuditLog) {
     appendControlledBashAudit(context, mode, command, args, matchedRuleIds, action === "block" ? "blocked" : action === "warn" ? "warn" : undefined);
   }
   if (action === "block") {
-    throw new CliError2(`Policy blocked command: ${command}`, 126);
+    throw new CliError(`Policy blocked command: ${command}`, 126, {
+      hint: "Review rig/policy/policy.json, or re-run with `--policy-mode observe` to log instead of block."
+    });
   }
 }
 export {

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

@@ -0,0 +1 @@
+export declare function runQuietBinaryProbe(binaryPath: string, args: string[], cwd: string): Promise<boolean>;

package/dist/src/commands/_run-bridge.d.ts

@@ -0,0 +1,114 @@
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+import { type RegisteredTaskSource } from "@rig/contracts";
+import { type CollabRegistryFilter, type LiveCollabProjection } from "@oh-my-pi/pi-coding-agent/collab/api";
+export type RigExtensionTask = {
+    readonly id: string;
+    readonly title?: string | null;
+    readonly status?: string | null;
+    readonly source?: string | null;
+    readonly url?: string | null;
+    readonly body?: string | null;
+};
+export type RigExtensionServerState = {
+    readonly alias: string;
+    readonly kind: "local" | "remote";
+    readonly baseUrl?: string | null;
+    readonly projectRoot?: string | null;
+    readonly status?: string | null;
+    readonly taskSource?: string | null;
+};
+export type RigExtensionAttachResult = {
+    readonly sessionPath?: string | null;
+    readonly joinLink?: string | null;
+    readonly collabSessionId?: string | null;
+};
+export type RunRunProcessInput = {
+    readonly projectRoot?: string;
+    readonly taskId: string;
+    readonly runId?: string;
+    readonly title?: string | null;
+    readonly model?: string | null;
+    readonly prompt?: string | null;
+    readonly rigRunBin?: string;
+    readonly writeStdout?: (text: string) => void;
+};
+export type RunRunProcessResult = {
+    readonly runId: string;
+    readonly pid: number;
+    readonly sessionName: string;
+    readonly runtime: unknown;
+};
+export type RunRunProcess = (input: RunRunProcessInput) => Promise<RunRunProcessResult>;
+type SpawnFunction = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+type ListTasksDeps = {
+    readonly loadTaskSource?: (projectRoot: string) => Promise<{
+        readonly kind: string;
+        readonly source: RegisteredTaskSource;
+    }>;
+};
+type SpawnRunProcessDeps = {
+    readonly runRunProcess?: RunRunProcess;
+    readonly spawn?: SpawnFunction;
+    readonly uuid?: () => string;
+    readonly resolveRigRunBin?: () => string;
+    readonly env?: NodeJS.ProcessEnv;
+};
+type AttachViaRelayDeps = {
+    readonly listActiveCollabSessions?: (filter: CollabRegistryFilter) => Promise<readonly LiveCollabProjection[]>;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly now?: () => number;
+};
+export type SpawnRunProcessInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly title?: string | null;
+};
+export type AttachViaRelayInput = {
+    readonly runId: string;
+    readonly taskId?: string | null;
+    readonly identityFilter: CollabRegistryFilter;
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+};
+export declare function listTasksFromSource(projectRoot: string, deps?: ListTasksDeps): Promise<readonly RigExtensionTask[]>;
+export declare function getTaskFromSource(projectRoot: string, taskId: string, deps?: ListTasksDeps): Promise<RigExtensionTask | null>;
+export declare function readSelectedTarget(projectRoot: string, env?: NodeJS.ProcessEnv): Promise<RigExtensionServerState>;
+export declare function resolveRigRunBin(): string;
+export declare function spawnRunProcess(input: SpawnRunProcessInput, deps?: SpawnRunProcessDeps): Promise<{
+    readonly runId: string;
+}>;
+export type RunControl = {
+    readonly kind: "steer";
+    readonly message: string;
+} | {
+    readonly kind: "stop";
+    readonly reason: string;
+};
+export interface DeliverRemoteControlDeps {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly spawn?: SpawnFunction;
+}
+interface RemoteControlContext {
+    readonly checkout?: string | null;
+    readonly registryBaseUrl?: string | null;
+    readonly namespaceKey?: string | null;
+}
+/**
+ * Build the remote shell command that re-runs the operator's control VERB on the
+ * remote host. The run is LOCAL there (its session journal lives on the remote
+ * disk), so `rig run steer/stop <runId>` resolves it locally and the remote
+ * worker's own localRunChanges consumer applies it — fully symmetric with local
+ * placement. We SSH the verb (not a pre-built sentinel) so the remote rebuilds via
+ * its canonical stop path. Identity is passed inline (SSH does not forward local
+ * env); the registry HMAC secret is read from the remote env, never sent over argv.
+ */
+export declare function buildRemoteControlCommand(runId: string, control: RunControl, ctx: RemoteControlContext): string;
+/**
+ * Deliver a steer/stop control to a REMOTE run by running the verb on the remote
+ * host over SSH (login shell, identical to spawnRunProcess). Awaits the remote
+ * exit code so the operator gets an honest success/failure — not fire-and-forget.
+ */
+export declare function deliverRemoteRunControl(projectRoot: string, runId: string, control: RunControl, deps?: DeliverRemoteControlDeps): Promise<void>;
+export declare function listActiveRunCollab(filter: CollabRegistryFilter): Promise<readonly LiveCollabProjection[]>;
+export declare function attachViaRelay(input: AttachViaRelayInput, deps?: AttachViaRelayDeps): Promise<RigExtensionAttachResult | null>;
+export {};

package/dist/src/commands/_run-bridge.js

@@ -0,0 +1,387 @@
+// @bun
+var __require = import.meta.require;
+
+// packages/cli/src/commands/_run-bridge.ts
+import { randomUUID } from "crypto";
+import { spawn as nodeSpawn } from "child_process";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { CUSTOM_TYPE_FOR, sessionIdFromSessionFile } from "@rig/contracts";
+import { createPluginHost } from "@rig/core";
+import { loadConfig } from "@rig/core/load-config";
+import { resolveOwnerNamespaceKey, resolveRegistryBaseUrl, resolveRegistrySecret, resolveSelectedRemote } from "@rig/runtime/control-plane/remote";
+import { listAgentRuntimes } from "@rig/runtime/control-plane/runtime/isolation";
+import { createRegistryClient } from "@rig/relay-registry";
+import {
+  listActiveCollabSessions as ompListActiveCollabSessions
+} from "@oh-my-pi/pi-coding-agent/collab/api";
+var DEFAULT_ATTACH_TIMEOUT_MS = 15000;
+var DEFAULT_ATTACH_POLL_INTERVAL_MS = 250;
+function stringField(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function githubUserId(value) {
+  if (typeof value === "number" && Number.isInteger(value))
+    return String(value);
+  return stringField(value);
+}
+function readJsonRecord(path) {
+  if (!existsSync(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function publicIdentityEnv(projectRoot) {
+  const auth = readJsonRecord(resolve(projectRoot, ".rig", "state", "github-auth.json"));
+  const connection = readJsonRecord(resolve(projectRoot, ".rig", "state", "connection.json"));
+  const values = {};
+  const selectedRepo = stringField(auth?.selectedRepo) ?? stringField(connection?.project);
+  const userId = githubUserId(auth?.userId);
+  const login = stringField(auth?.login);
+  const namespaceKey = stringField(auth?.userNamespaceKey) ?? resolveOwnerNamespaceKey(projectRoot);
+  if (selectedRepo)
+    values.RIG_SELECTED_REPO = selectedRepo;
+  if (userId)
+    values.RIG_GITHUB_USER_ID = userId;
+  if (login)
+    values.RIG_GITHUB_LOGIN = login;
+  if (namespaceKey)
+    values.RIG_GITHUB_NAMESPACE_KEY = namespaceKey;
+  return values;
+}
+function taskText(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function taskUrl(record) {
+  const metadata = record;
+  return taskText(metadata.url) ?? taskText(metadata.html_url) ?? taskText(metadata.webUrl);
+}
+function taskBody(record) {
+  const metadata = record;
+  return taskText(metadata.body) ?? taskText(metadata.description);
+}
+function taskTitle(record) {
+  const metadata = record;
+  return taskText(metadata.title) ?? taskText(metadata.name) ?? record.id;
+}
+function toExtensionTask(record, sourceKind) {
+  return {
+    id: record.id,
+    title: taskTitle(record),
+    status: typeof record.status === "string" ? record.status : null,
+    source: sourceKind,
+    url: taskUrl(record),
+    body: taskBody(record)
+  };
+}
+async function loadConfiguredTaskSource(projectRoot) {
+  const normalizedRoot = resolve(projectRoot);
+  const config = await loadConfig(normalizedRoot);
+  const pluginHost = createPluginHost(config.plugins);
+  const taskSourceFactory = pluginHost.resolveTaskSourceFactoryByKind(config.taskSource.kind);
+  if (!taskSourceFactory) {
+    const kinds = pluginHost.listExecutableTaskSources().map((entry) => entry.kind).join(", ") || "none";
+    throw new Error(`No task source factory registered for kind "${config.taskSource.kind}". Registered kinds: ${kinds}.`);
+  }
+  return {
+    kind: config.taskSource.kind,
+    source: taskSourceFactory.factory(config.taskSource, { projectRoot: normalizedRoot })
+  };
+}
+async function listTasksFromSource(projectRoot, deps = {}) {
+  const { kind, source } = await (deps.loadTaskSource ?? loadConfiguredTaskSource)(projectRoot);
+  return (await source.list()).map((task) => toExtensionTask(task, kind));
+}
+async function getTaskFromSource(projectRoot, taskId, deps = {}) {
+  const tasks = await listTasksFromSource(projectRoot, deps);
+  return tasks.find((task) => task.id === taskId) ?? null;
+}
+async function readSelectedTarget(projectRoot, env = process.env) {
+  const config = await loadConfig(resolve(projectRoot));
+  const selected = resolveSelectedRemote(projectRoot, env);
+  return {
+    alias: selected?.alias ?? "local",
+    kind: selected ? "remote" : "local",
+    projectRoot,
+    status: "ready",
+    taskSource: config.taskSource.kind
+  };
+}
+function runningFromCompiledBinary() {
+  return import.meta.url.includes("$bunfs");
+}
+function resolveRigRunBin() {
+  if (runningFromCompiledBinary())
+    return resolve(dirname(process.execPath), "rig-run");
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../../../rig-host/bin/rig-run.ts");
+}
+async function defaultRunRunProcess(input) {
+  const { runRunProcess } = await import("@rig/rig-host");
+  return await runRunProcess(input);
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function readProjectSlug(projectRoot) {
+  const connection = readJsonRecord(resolve(projectRoot, ".rig", "state", "connection.json"));
+  return stringField(connection?.project) ?? null;
+}
+function resolveProjectOriginUrl(projectRoot) {
+  const slug = readProjectSlug(projectRoot);
+  return slug && /^[^/]+\/[^/]+$/.test(slug) ? `https://github.com/${slug}.git` : null;
+}
+async function spawnRunProcess(input, deps = {}) {
+  const runId = (deps.uuid ?? randomUUID)();
+  const env = deps.env ?? process.env;
+  const identityEnv = publicIdentityEnv(input.projectRoot);
+  const selected = resolveSelectedRemote(input.projectRoot, env);
+  const sshTarget = selected?.sshTarget ?? env.RIG_REMOTE_ALIAS?.trim();
+  if (sshTarget) {
+    const namespaceKey = identityEnv.RIG_GITHUB_NAMESPACE_KEY ?? resolveOwnerNamespaceKey(input.projectRoot, env) ?? "";
+    const sh = shellQuote;
+    const originUrl = resolveProjectOriginUrl(input.projectRoot);
+    const repoName = (readProjectSlug(input.projectRoot)?.split("/").pop() ?? "project").replace(/[^A-Za-z0-9._-]/g, "-");
+    const checkoutExpr = selected?.checkout ? sh(selected.checkout) : `"$HOME/.rig/checkouts/${repoName}"`;
+    const identityAssignments = Object.entries(identityEnv).map(([k, v]) => `${k}=${sh(v)}`);
+    if (namespaceKey && !identityEnv.RIG_GITHUB_NAMESPACE_KEY)
+      identityAssignments.push(`RIG_GITHUB_NAMESPACE_KEY=${sh(namespaceKey)}`);
+    const runInvocation = [
+      `RIG_RUN_ID=${sh(runId)}`,
+      `RIG_TASK_ID=${sh(input.taskId)}`,
+      ...identityAssignments,
+      selected?.registryBaseUrl ? `RIG_REGISTRY_URL=${sh(selected.registryBaseUrl)}` : "",
+      `rig run start --task ${sh(input.taskId)}`
+    ].filter(Boolean).join(" ");
+    const provisionAndRun = [
+      "set -e",
+      `CHECKOUT=${checkoutExpr}`,
+      originUrl ? `[ -d "$CHECKOUT/.git" ] || git clone ${sh(originUrl)} "$CHECKOUT"` : `[ -d "$CHECKOUT/.git" ] || { echo "rig: remote checkout $CHECKOUT missing and no origin to clone" >&2; exit 1; }`,
+      `cd "$CHECKOUT"`,
+      "git fetch origin --prune --quiet || true",
+      runInvocation
+    ].join("; ");
+    const child = (deps.spawn ?? nodeSpawn)("ssh", [sshTarget, `bash -lc ${sh(provisionAndRun)}`], {
+      cwd: input.projectRoot,
+      env: { ...env, ...identityEnv },
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+    return { runId };
+  }
+  await (deps.runRunProcess ?? defaultRunRunProcess)({
+    projectRoot: input.projectRoot,
+    taskId: input.taskId,
+    runId,
+    title: input.title,
+    rigRunBin: (deps.resolveRigRunBin ?? resolveRigRunBin)()
+  });
+  return { runId };
+}
+function buildRemoteControlCommand(runId, control, ctx) {
+  const verb = control.kind === "stop" ? `rig run stop ${shellQuote(runId)}${control.reason.trim() ? ` --reason ${shellQuote(control.reason)}` : ""}` : `rig run steer ${shellQuote(runId)} --message ${shellQuote(control.message)}`;
+  return [
+    ctx.checkout ? `cd ${shellQuote(ctx.checkout)} &&` : "",
+    ctx.namespaceKey ? `RIG_GITHUB_NAMESPACE_KEY=${shellQuote(ctx.namespaceKey)}` : "",
+    ctx.registryBaseUrl ? `RIG_REGISTRY_URL=${shellQuote(ctx.registryBaseUrl)}` : "",
+    verb
+  ].filter(Boolean).join(" ");
+}
+async function deliverRemoteRunControl(projectRoot, runId, control, deps = {}) {
+  const env = deps.env ?? process.env;
+  const selected = resolveSelectedRemote(projectRoot, env);
+  const sshTarget = selected?.sshTarget ?? env.RIG_REMOTE_ALIAS?.trim();
+  if (!sshTarget) {
+    throw new Error(`Run ${runId} is remote but no SSH target is configured (set one with \`rig server use <alias>\`).`);
+  }
+  const identityEnv = publicIdentityEnv(projectRoot);
+  const namespaceKey = identityEnv.RIG_GITHUB_NAMESPACE_KEY ?? resolveOwnerNamespaceKey(projectRoot, env) ?? "";
+  const remoteCommand = buildRemoteControlCommand(runId, control, {
+    checkout: selected?.checkout ?? null,
+    registryBaseUrl: selected?.registryBaseUrl ?? null,
+    namespaceKey
+  });
+  await new Promise((resolveDone, rejectDone) => {
+    const child = (deps.spawn ?? nodeSpawn)("ssh", [sshTarget, `bash -lc ${shellQuote(remoteCommand)}`], {
+      cwd: projectRoot,
+      env: { ...env, ...identityEnv },
+      stdio: ["ignore", "ignore", "pipe"]
+    });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", rejectDone);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolveDone();
+        return;
+      }
+      const detail = stderr.trim();
+      rejectDone(new Error(`remote \`rig run ${control.kind}\` exited ${code ?? "null"}${detail ? `: ${detail}` : ""}`));
+    });
+  });
+}
+function registrySecret(env = process.env) {
+  return resolveRegistrySecret(process.cwd(), env) ?? null;
+}
+function registryBaseUrl(env = process.env) {
+  return resolveRegistryBaseUrl(process.cwd(), env);
+}
+function collabFromRegistryEntry(entry) {
+  return {
+    sessionId: entry.roomId,
+    sessionPath: "",
+    cwd: "",
+    title: entry.title,
+    joinLink: entry.joinLink,
+    webLink: entry.webLink,
+    relayUrl: entry.relayUrl,
+    owner: entry.owner,
+    selectedRepo: entry.repo,
+    startedAt: entry.startedAt,
+    updatedAt: entry.heartbeatAt,
+    ...entry.pid === undefined ? {} : { pid: entry.pid },
+    stale: entry.stale
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readLocalRunCollab(runtime) {
+  if (!runtime.sessionDir || !existsSync(runtime.sessionDir))
+    return null;
+  let files;
+  try {
+    files = readdirSync(runtime.sessionDir).filter((f) => f.endsWith(".jsonl")).sort().reverse();
+  } catch {
+    return null;
+  }
+  for (const file of files) {
+    let lines;
+    try {
+      lines = readFileSync(resolve(runtime.sessionDir, file), "utf8").split(`
+`);
+    } catch {
+      continue;
+    }
+    let host = null;
+    for (const line of lines) {
+      if (!line.includes("collab-host-started"))
+        continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!isRecord(entry) || entry.customType !== CUSTOM_TYPE_FOR["timeline-entry"] || !isRecord(entry.data))
+        continue;
+      const payload = isRecord(entry.data.payload) ? entry.data.payload : entry.data;
+      if (payload.type !== "collab-host-started")
+        continue;
+      host = {
+        roomId: typeof payload.roomId === "string" ? payload.roomId : undefined,
+        joinLink: typeof payload.joinLink === "string" ? payload.joinLink : undefined,
+        webLink: typeof payload.webLink === "string" ? payload.webLink : undefined,
+        relayUrl: typeof payload.relayUrl === "string" ? payload.relayUrl : undefined,
+        at: typeof entry.data.at === "string" ? entry.data.at : undefined
+      };
+    }
+    if (!host?.joinLink)
+      continue;
+    const at = host.at ?? "";
+    const sessionId = host.roomId ?? sessionIdFromSessionFile(resolve(runtime.sessionDir, file)) ?? runtime.id;
+    return {
+      sessionId,
+      sessionPath: resolve(runtime.sessionDir, file),
+      cwd: runtime.workspaceDir,
+      joinLink: host.joinLink,
+      webLink: host.webLink ?? "",
+      relayUrl: host.relayUrl ?? "",
+      title: runtime.taskId ? `[${runtime.taskId}] Rig run ${sessionId}` : `Rig run ${sessionId}`,
+      startedAt: at,
+      updatedAt: at,
+      stale: false
+    };
+  }
+  return null;
+}
+async function listLocalRunCollabSessions(projectRoot) {
+  let runtimes;
+  try {
+    runtimes = await listAgentRuntimes(projectRoot);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const runtime of runtimes) {
+    const collab = readLocalRunCollab(runtime);
+    if (collab)
+      out.push(collab);
+  }
+  return out;
+}
+async function listActiveRunCollab(filter) {
+  return defaultListActiveCollabSessions(filter);
+}
+async function defaultListActiveCollabSessions(filter) {
+  const projectRoot = process.cwd();
+  const local = await listLocalRunCollabSessions(projectRoot);
+  const namespaceKey = filter.namespaceKey ?? resolveOwnerNamespaceKey(projectRoot);
+  const secret = registrySecret();
+  const remote = namespaceKey && secret ? (await createRegistryClient({ baseUrl: registryBaseUrl(), namespaceKey, secret }).listRoomsByOwner(filter)).map(collabFromRegistryEntry) : await ompListActiveCollabSessions(filter);
+  const seen = new Set(local.map((c) => c.sessionId));
+  return [...local, ...remote.filter((c) => !seen.has(c.sessionId))];
+}
+function sleep(ms) {
+  const { promise, resolve: resolveSleep } = Promise.withResolvers();
+  setTimeout(resolveSleep, ms);
+  return promise;
+}
+function matchesRun(collab, runId, taskId) {
+  if (collab.sessionId === runId)
+    return true;
+  if (runId && collab.title?.includes(runId))
+    return true;
+  return Boolean(taskId && collab.title?.includes(taskId));
+}
+async function attachViaRelay(input, deps = {}) {
+  const timeoutMs = input.timeoutMs ?? DEFAULT_ATTACH_TIMEOUT_MS;
+  const pollIntervalMs = input.pollIntervalMs ?? DEFAULT_ATTACH_POLL_INTERVAL_MS;
+  const listActive = deps.listActiveCollabSessions ?? defaultListActiveCollabSessions;
+  const now = deps.now ?? Date.now;
+  const pause = deps.sleep ?? sleep;
+  const deadline = now() + timeoutMs;
+  do {
+    const live = await listActive(input.identityFilter);
+    const match = live.find((collab) => matchesRun(collab, input.runId, input.taskId) && !collab.stale);
+    if (match) {
+      return {
+        sessionPath: match.sessionPath || null,
+        joinLink: match.joinLink || null,
+        collabSessionId: match.sessionId
+      };
+    }
+    if (now() >= deadline)
+      break;
+    await pause(pollIntervalMs);
+  } while (now() <= deadline);
+  return null;
+}
+export {
+  spawnRunProcess,
+  resolveRigRunBin,
+  readSelectedTarget,
+  listTasksFromSource,
+  listActiveRunCollab,
+  getTaskFromSource,
+  deliverRemoteRunControl,
+  buildRemoteControlCommand,
+  attachViaRelay
+};

package/dist/src/commands/_run-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { RunJournalProjection } from "@rig/contracts";
+/**
+ * Extract the most useful human-facing failure diagnostic from the folded run journal.
+ *
+ * The live projection deliberately does not retain log/timeline lines, so this mirrors the
+ * deleted server-side categorization using only fields that survive folding: record fields,
+ * status reasons, closeout details, and reducer anomalies.
+ */
+export declare function summarizeUsefulRunError(projection: RunJournalProjection): string | null;