@h-rig/server 0.0.6-alpha.0

package/dist/src/server-helpers/snapshot-orchestrator.js

@@ -0,0 +1,832 @@
+// @bun
+// packages/server/src/server-helpers/snapshot-orchestrator.ts
+import { dirname as dirname4, resolve as resolve5 } from "path";
+import {
+  listAuthorityRuns as listAuthorityRuns3,
+  readAuthorityRun as readAuthorityRun2
+} from "@rig/runtime/control-plane/authority-files";
+
+// packages/server/src/server-helpers/normalizers.ts
+function normalizeString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function normalizeSequence(value) {
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : NaN;
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+// packages/server/src/server-helpers/summaries.ts
+function toTaskSummary(workspaceId, task) {
+  const createdAt = task.createdAt ?? task.updatedAt ?? new Date().toISOString();
+  const updatedAt = task.updatedAt ?? task.createdAt ?? createdAt;
+  const description = task.description ?? task.acceptanceCriteria ?? "";
+  return {
+    id: task.id,
+    workspaceId,
+    graphId: null,
+    externalId: task.externalRef,
+    title: task.title,
+    description,
+    status: task.status,
+    priority: task.priority,
+    role: task.role,
+    scope: task.scope,
+    validationKeys: task.validation,
+    sourceIssueId: task.sourceIssueId,
+    dependencies: task.dependencies,
+    parentChildDeps: task.parentChildDeps,
+    metadata: {
+      acceptanceCriteria: task.acceptanceCriteria,
+      issueType: task.issueType,
+      sourceIssueId: task.sourceIssueId,
+      ...task.sourceStatus ? { sourceStatus: task.sourceStatus } : {},
+      dependencies: task.dependencies,
+      parentChildDeps: task.parentChildDeps,
+      labels: task.labels
+    },
+    createdAt,
+    updatedAt
+  };
+}
+function buildWorkspaceGraphSummary(workspace, tasks) {
+  const timestamps = [
+    workspace.updatedAt,
+    ...tasks.map((task) => task.updatedAt),
+    ...tasks.map((task) => task.createdAt)
+  ].filter((value) => typeof value === "string" && value.length > 0);
+  const updatedAt = timestamps.toSorted().at(-1) ?? workspace.updatedAt;
+  const taskCount = tasks.length;
+  return {
+    id: `graph:${workspace.id}`,
+    workspaceId: workspace.id,
+    title: `${workspace.title} graph`,
+    description: taskCount > 0 ? `${taskCount} imported task${taskCount === 1 ? "" : "s"} from the connected Rig workspace` : "No imported tasks are available yet for this workspace",
+    createdAt: workspace.createdAt,
+    updatedAt
+  };
+}
+function toApprovalSummary(record) {
+  const createdAt = normalizeString(record.record.createdAt) ?? normalizeString(record.record.requestedAt) ?? new Date().toISOString();
+  const resolvedAt = normalizeString(record.record.resolvedAt) ?? normalizeString(record.record.respondedAt) ?? null;
+  return {
+    id: record.requestId ?? `${record.runId}-approval-${createdAt}`,
+    runId: record.runId,
+    actionId: normalizeString(record.record.actionId),
+    requestKind: normalizeString(record.record.requestKind) ?? normalizeString(record.record.kind) ?? "approval",
+    status: record.status === "resolved" ? "resolved" : "pending",
+    payload: record.record,
+    createdAt,
+    resolvedAt
+  };
+}
+function toUserInputSummary(record) {
+  const createdAt = normalizeString(record.record.createdAt) ?? normalizeString(record.record.requestedAt) ?? new Date().toISOString();
+  const resolvedAt = normalizeString(record.record.resolvedAt) ?? normalizeString(record.record.respondedAt) ?? null;
+  return {
+    id: record.requestId ?? `${record.runId}-input-${createdAt}`,
+    runId: record.runId,
+    status: record.status === "resolved" ? "resolved" : "pending",
+    payload: record.record,
+    createdAt,
+    resolvedAt
+  };
+}
+function toRunSummary(run, approvals, userInputs) {
+  const pendingApprovalCount = approvals.filter((entry) => entry.status !== "resolved").length;
+  const pendingUserInputCount = userInputs.filter((entry) => entry.status !== "resolved").length;
+  const runStatus = pendingApprovalCount > 0 ? "waiting-approval" : pendingUserInputCount > 0 ? "waiting-user-input" : run.status === "waiting" ? "queued" : run.status === "preparing" ? "preparing" : run.status === "stopped" ? "cancelled" : run.status === "done" || run.status === "completed" ? "completed" : run.status === "error" || run.status === "failed" ? "failed" : run.status === "running" ? "running" : "created";
+  const runMode = normalizeString(run.runMode) === "autonomous" ? "autonomous" : normalizeString(run.runMode) === "supervised" ? "supervised" : "interactive";
+  const runtimeMode = normalizeString(run.runtimeMode) ?? "approval-required";
+  const interactionMode = normalizeString(run.interactionMode) ?? "default";
+  return {
+    id: run.runId,
+    workspaceId: run.workspaceId,
+    taskId: run.taskId,
+    title: run.title,
+    runKind: run.taskId ? "task" : "adhoc",
+    mode: runMode,
+    runtimeMode,
+    interactionMode,
+    status: runStatus,
+    runtimeAdapter: run.runtimeAdapter,
+    model: normalizeString(run.model),
+    initialPrompt: normalizeString(run.initialPrompt),
+    executionTarget: run.mode === "remote" ? "remote" : "local",
+    remoteHostId: run.hostId,
+    remoteLeaseId: run.endpointId,
+    remoteLeaseClaimedAt: null,
+    activeRuntimeId: null,
+    latestMessageId: normalizeString(run.latestMessageId),
+    pendingApprovalCount,
+    pendingUserInputCount,
+    branch: normalizeString(run.branch),
+    worktreePath: run.worktreePath,
+    errorText: normalizeString(run.errorText),
+    createdAt: run.createdAt,
+    updatedAt: run.updatedAt,
+    startedAt: run.startedAt,
+    completedAt: run.completedAt
+  };
+}
+
+// packages/server/src/server-helpers/run-io.ts
+import { dirname, resolve } from "path";
+import { closeSync, existsSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "fs";
+import {
+  listAuthorityRuns,
+  readAuthorityRun,
+  readJsonlFile,
+  resolveAuthorityRunDir
+} from "@rig/runtime/control-plane/authority-files";
+function matchesRunFilter(entry, filter) {
+  return (!filter.runId || entry.runId === filter.runId) && (!filter.taskId || entry.taskId === filter.taskId);
+}
+function readApprovalsForRuns(projectRoot, runs, filter = {}) {
+  return runs.filter((entry) => matchesRunFilter(entry, filter)).flatMap((entry) => readJsonlFile(resolve(resolveAuthorityRunDir(projectRoot, entry.runId), "approvals.jsonl")).flatMap((record) => {
+    if (!record || typeof record !== "object") {
+      return [];
+    }
+    const value = record;
+    return [
+      {
+        runId: entry.runId,
+        taskId: entry.taskId,
+        requestId: normalizeString(value.requestId) ?? normalizeString(value.id),
+        status: normalizeString(value.status),
+        record: value
+      }
+    ];
+  }));
+}
+function readUserInputsForRuns(projectRoot, runs, filter = {}) {
+  return runs.filter((entry) => matchesRunFilter(entry, filter)).flatMap((entry) => readJsonlFile(resolve(resolveAuthorityRunDir(projectRoot, entry.runId), "user-input.jsonl")).flatMap((record) => {
+    if (!record || typeof record !== "object") {
+      return [];
+    }
+    const value = record;
+    return [
+      {
+        runId: entry.runId,
+        taskId: entry.taskId,
+        requestId: normalizeString(value.requestId) ?? normalizeString(value.id),
+        status: normalizeString(value.status),
+        record: value
+      }
+    ];
+  }));
+}
+function runTimelinePath(projectRoot, runId) {
+  return resolve(resolveAuthorityRunDir(projectRoot, runId), "timeline.jsonl");
+}
+function runLogsPath(projectRoot, runId) {
+  return resolve(resolveAuthorityRunDir(projectRoot, runId), "logs.jsonl");
+}
+function parseJsonlRecords(lines) {
+  return lines.map((line) => line.trim()).filter(Boolean).flatMap((line) => {
+    try {
+      return [JSON.parse(line)];
+    } catch {
+      return [];
+    }
+  });
+}
+function readJsonlFileTail(path, options) {
+  const limit = Math.max(0, Math.trunc(options.limit));
+  if (limit === 0 || !existsSync(path))
+    return [];
+  const maxBytes = Math.max(1024, Math.trunc(options.maxBytes ?? 256 * 1024));
+  const size = statSync(path).size;
+  if (size === 0)
+    return [];
+  const start = Math.max(0, size - maxBytes);
+  const length = size - start;
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, "r");
+  try {
+    readSync(fd, buffer, 0, length, start);
+  } finally {
+    closeSync(fd);
+  }
+  const text = buffer.toString("utf8");
+  const lines = text.split(/\r?\n/);
+  const completeLines = start > 0 ? lines.slice(1) : lines;
+  return parseJsonlRecords(completeLines.filter(Boolean).slice(-limit));
+}
+var INITIAL_RUN_LOG_TAIL_MAX_BYTES = 8 * 1024 * 1024;
+
+// packages/server/src/server-helpers/queue-state.ts
+import { resolve as resolve3 } from "path";
+import { readJsonFile, writeJsonFile } from "@rig/runtime/control-plane/authority-files";
+
+// packages/server/src/server-helpers/server-paths.ts
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import { resolveMonorepoRoot } from "@rig/runtime/control-plane/native/utils";
+function resolveServerAuthorityPaths(projectRoot) {
+  const taskWorkspace = process.env.RIG_TASK_WORKSPACE?.trim();
+  const explicitStateDir = process.env.RIG_STATE_DIR?.trim();
+  const explicitLogsDir = process.env.RIG_LOGS_DIR?.trim();
+  const explicitSessionFile = process.env.RIG_SESSION_FILE?.trim();
+  const monorepoRoot = resolveMonorepoRoot(projectRoot);
+  const stateRoot = taskWorkspace ? resolve2(taskWorkspace, ".rig") : explicitStateDir ? dirname2(resolve2(explicitStateDir)) : explicitLogsDir ? dirname2(resolve2(explicitLogsDir)) : explicitSessionFile ? dirname2(dirname2(resolve2(explicitSessionFile))) : resolve2(monorepoRoot, ".rig");
+  const stateDir = explicitStateDir ? resolve2(explicitStateDir) : resolve2(stateRoot, "state");
+  const logsDir = explicitLogsDir ? resolve2(explicitLogsDir) : resolve2(stateRoot, "logs");
+  const sessionFile = explicitSessionFile ? resolve2(explicitSessionFile) : resolve2(stateRoot, "session", "session.json");
+  const artifactsDir = taskWorkspace ? resolve2(taskWorkspace, "artifacts") : resolve2(monorepoRoot, "artifacts");
+  return {
+    stateRoot,
+    stateDir,
+    logsDir,
+    controlPlaneEventsFile: resolve2(logsDir, "control-plane.events.jsonl"),
+    sessionFile,
+    artifactsDir
+  };
+}
+
+// packages/server/src/server-helpers/queue-state.ts
+function resolveQueueStatePath(projectRoot) {
+  return resolve3(resolveServerAuthorityPaths(projectRoot).stateDir, "task-queue.json");
+}
+function readQueueState(projectRoot) {
+  const queue = readJsonFile(resolveQueueStatePath(projectRoot), null);
+  if (!Array.isArray(queue))
+    return [];
+  return queue.filter((entry) => entry && typeof entry === "object").map((entry, index) => ({
+    taskId: normalizeString(entry.taskId),
+    score: typeof entry.score === "number" ? Math.max(0, Math.trunc(entry.score)) : 0,
+    unblockCount: typeof entry.unblockCount === "number" ? Math.max(0, Math.trunc(entry.unblockCount)) : 0,
+    position: typeof entry.position === "number" ? Math.max(0, Math.trunc(entry.position)) : index
+  })).filter((entry) => Boolean(entry.taskId)).sort((left, right) => right.score - left.score || left.position - right.position).map((entry, index) => ({ ...entry, position: index }));
+}
+
+// packages/server/src/server-helpers/remote-snapshots.ts
+import { listAuthorityRemoteEndpoints } from "@rig/runtime/control-plane/authority-files";
+function toRemoteConnectionStatus(status) {
+  switch (status) {
+    case "connected":
+    case "connecting":
+    case "authenticating":
+    case "reconnecting":
+    case "error":
+    case "disconnected":
+      return status;
+    case "ready":
+    case "busy":
+    case "degraded":
+    case "draining":
+      return "connected";
+    case "registering":
+      return "connecting";
+    case "offline":
+    case "quarantined":
+      return "error";
+    default:
+      return "disconnected";
+  }
+}
+function hostToRemoteEndpoint(host) {
+  let hostName = "127.0.0.1";
+  let port = 7890;
+  try {
+    const url = new URL(host.baseUrl);
+    hostName = url.hostname || hostName;
+    port = Number.parseInt(url.port || "80", 10) || port;
+  } catch {}
+  return {
+    id: host.hostId,
+    alias: host.name,
+    host: hostName,
+    port,
+    token: "",
+    tokenConfigured: false,
+    autoConnect: true,
+    addedAt: host.registeredAt,
+    lastConnectedAt: host.lastHeartbeatAt
+  };
+}
+function buildRemoteEndpointSnapshot(projectRoot, remoteHosts) {
+  const authorityEndpoints = listAuthorityRemoteEndpoints(projectRoot).map((entry) => ({
+    id: entry.id,
+    alias: entry.alias,
+    host: entry.host,
+    port: entry.port,
+    token: "",
+    tokenConfigured: entry.token.trim().length > 0,
+    autoConnect: entry.autoConnect,
+    addedAt: entry.addedAt,
+    lastConnectedAt: entry.lastConnectedAt
+  }));
+  const hostEndpoints = Array.from(remoteHosts.values()).map(hostToRemoteEndpoint);
+  const deduped = new Map;
+  for (const entry of [...authorityEndpoints, ...hostEndpoints]) {
+    deduped.set(entry.id, entry);
+  }
+  return Array.from(deduped.values()).sort((left, right) => left.alias.localeCompare(right.alias));
+}
+function buildRemoteConnectionSnapshot(remoteHosts, remoteConnections, endpoints) {
+  const connections = new Map;
+  for (const [endpointId, summary] of remoteConnections.entries()) {
+    connections.set(endpointId, summary);
+  }
+  for (const host of remoteHosts.values()) {
+    if (connections.has(host.hostId))
+      continue;
+    connections.set(host.hostId, {
+      endpointId: host.hostId,
+      status: toRemoteConnectionStatus(host.status),
+      error: host.status === "offline" || host.status === "quarantined" ? host.status : null,
+      connectedAt: host.lastHeartbeatAt,
+      tokenExpiresAt: null,
+      latencyMs: null,
+      subscribedEvents: []
+    });
+  }
+  for (const endpoint of endpoints) {
+    if (connections.has(endpoint.id))
+      continue;
+    connections.set(endpoint.id, {
+      endpointId: endpoint.id,
+      status: "disconnected",
+      error: null,
+      connectedAt: endpoint.lastConnectedAt,
+      tokenExpiresAt: null,
+      latencyMs: null,
+      subscribedEvents: []
+    });
+  }
+  return Array.from(connections.values()).sort((left, right) => String(left.endpointId).localeCompare(String(right.endpointId)));
+}
+function normalizeIsoTimestamp(value) {
+  const normalized = normalizeString(value);
+  if (!normalized)
+    return null;
+  const timestamp = Date.parse(normalized);
+  return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : null;
+}
+
+// packages/server/src/server-helpers/conversation-snapshot.ts
+import { existsSync as existsSync2, readdirSync, statSync as statSync2 } from "fs";
+import { dirname as dirname3, resolve as resolve4 } from "path";
+import {
+  listAuthorityRuns as listAuthorityRuns2,
+  readJsonlFile as readJsonlFile2
+} from "@rig/runtime/control-plane/authority-files";
+function readClaudeSessionRecords(run) {
+  if (!run.worktreePath)
+    return [];
+  const runtimeRoot = dirname3(run.worktreePath);
+  const projectsRoot = resolve4(runtimeRoot, "home", ".claude", "projects");
+  if (!existsSync2(projectsRoot))
+    return [];
+  const candidatePaths = [];
+  const visit = (dirPath, depth) => {
+    if (depth > 2)
+      return;
+    for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+      const nextPath = resolve4(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        visit(nextPath, depth + 1);
+        continue;
+      }
+      if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        candidatePaths.push(nextPath);
+      }
+    }
+  };
+  visit(projectsRoot, 0);
+  const entries = candidatePaths.map((path) => {
+    const records2 = readJsonlFile2(path).filter((raw) => !!raw && typeof raw === "object" && !Array.isArray(raw));
+    return {
+      path,
+      mtimeMs: statSync2(path).mtimeMs,
+      records: records2
+    };
+  }).filter((entry) => {
+    const normalizedWorktree = run.worktreePath.replaceAll("\\", "/");
+    return entry.records.some((record) => {
+      const cwd = normalizeString(record.cwd)?.replaceAll("\\", "/");
+      return cwd === normalizedWorktree;
+    });
+  }).sort((left, right) => left.mtimeMs - right.mtimeMs);
+  if (entries.length === 0)
+    return [];
+  const startedAt = Date.parse(run.startedAt ?? run.createdAt);
+  const completedAt = run.completedAt ? Date.parse(run.completedAt) : Number.POSITIVE_INFINITY;
+  const lookbackMs = 60000;
+  const lookaheadMs = 5 * 60000;
+  const records = [];
+  for (const entry of entries) {
+    for (const record of entry.records) {
+      const timestamp = Date.parse(normalizeIsoTimestamp(record.timestamp) ?? "");
+      if (Number.isFinite(startedAt) && Number.isFinite(timestamp)) {
+        if (timestamp < startedAt - lookbackMs)
+          continue;
+        if (Number.isFinite(completedAt) && timestamp > completedAt + lookaheadMs)
+          continue;
+      }
+      records.push(record);
+    }
+  }
+  return records.sort((left, right) => {
+    const leftAt = Date.parse(normalizeIsoTimestamp(left.timestamp) ?? "") || 0;
+    const rightAt = Date.parse(normalizeIsoTimestamp(right.timestamp) ?? "") || 0;
+    return leftAt - rightAt;
+  });
+}
+function buildClaudeStreamLogs(run) {
+  const sessionRecords = readClaudeSessionRecords(run);
+  if (sessionRecords.length === 0)
+    return [];
+  const logs = [];
+  const pendingToolUses = new Map;
+  for (const record of sessionRecords) {
+    const entryType = normalizeString(record.type);
+    const createdAt = normalizeIsoTimestamp(record.timestamp) ?? run.updatedAt;
+    if (entryType === "summary") {
+      continue;
+    }
+    if (entryType === "system" || entryType === "result") {
+      logs.push({
+        id: normalizeString(record.uuid) ?? `${run.runId}-claude-${logs.length + 1}`,
+        runId: run.runId,
+        title: entryType === "result" ? "Agent result" : "Agent session initialized",
+        detail: JSON.stringify(record),
+        tone: entryType === "result" && record.is_error === true ? "error" : "info",
+        status: run.completedAt ? "completed" : "running",
+        payload: record,
+        createdAt
+      });
+      continue;
+    }
+    const message = record.message;
+    if (!message || typeof message !== "object" || Array.isArray(message))
+      continue;
+    const messageRecord = message;
+    const role = normalizeString(messageRecord.role) ?? entryType ?? "assistant";
+    const content = Array.isArray(messageRecord.content) ? messageRecord.content : [];
+    for (const item of content) {
+      if (!item || typeof item !== "object" || Array.isArray(item))
+        continue;
+      const contentRecord = item;
+      const contentType = normalizeString(contentRecord.type);
+      if (contentType === "tool_use") {
+        const toolUseId = normalizeString(contentRecord.id);
+        if (!toolUseId)
+          continue;
+        pendingToolUses.set(toolUseId, {
+          id: toolUseId,
+          name: normalizeString(contentRecord.name),
+          input: contentRecord.input ?? {},
+          timestamp: createdAt,
+          record: contentRecord
+        });
+        continue;
+      }
+      if (contentType === "tool_result") {
+        const toolUseId = normalizeString(contentRecord.tool_use_id);
+        const pending = toolUseId ? pendingToolUses.get(toolUseId) ?? null : null;
+        if (pending && toolUseId) {
+          pendingToolUses.delete(toolUseId);
+        }
+        const detail2 = JSON.stringify({
+          type: "claude_tool_activity",
+          session_id: normalizeString(record.sessionId) ?? normalizeString(record.session_id),
+          uuid: normalizeString(record.uuid),
+          tool_use_id: toolUseId,
+          tool_name: pending?.name ?? null,
+          tool_input: pending?.input ?? null,
+          tool_result: contentRecord.content ?? contentRecord,
+          is_error: contentRecord.is_error === true,
+          raw: {
+            toolUse: pending?.record ?? null,
+            toolResult: contentRecord
+          }
+        });
+        logs.push({
+          id: toolUseId ? `${run.runId}-claude-tool-${toolUseId}` : normalizeString(record.uuid) ?? `${run.runId}-claude-${logs.length + 1}`,
+          runId: run.runId,
+          title: "Tool activity",
+          detail: detail2,
+          tone: contentRecord.is_error === true ? "error" : "tool",
+          status: run.completedAt ? "completed" : "running",
+          payload: {
+            toolUseId,
+            toolName: pending?.name ?? null,
+            toolInput: pending?.input ?? null,
+            content: contentRecord.content ?? null,
+            isError: contentRecord.is_error === true
+          },
+          createdAt: pending?.timestamp ?? createdAt
+        });
+        continue;
+      }
+      const detail = JSON.stringify({
+        type: role,
+        message: {
+          role,
+          content: [contentRecord]
+        },
+        session_id: normalizeString(record.sessionId) ?? normalizeString(record.session_id),
+        uuid: normalizeString(record.uuid)
+      });
+      logs.push({
+        id: normalizeString(record.uuid) ? `${normalizeString(record.uuid)}:${contentType ?? "content"}:${logs.length + 1}` : `${run.runId}-claude-${logs.length + 1}`,
+        runId: run.runId,
+        title: role === "assistant" ? "Assistant output" : role === "user" ? "Tool activity" : "Agent output",
+        detail,
+        tone: contentType === "text" ? "info" : "tool",
+        status: run.completedAt ? "completed" : "running",
+        payload: contentRecord,
+        createdAt
+      });
+    }
+  }
+  for (const pending of pendingToolUses.values()) {
+    logs.push({
+      id: `${run.runId}-claude-tool-${pending.id}`,
+      runId: run.runId,
+      title: "Tool activity",
+      detail: JSON.stringify({
+        type: "claude_tool_use",
+        tool_use_id: pending.id,
+        tool_name: pending.name,
+        tool_input: pending.input,
+        raw: pending.record
+      }),
+      tone: "tool",
+      status: "running",
+      payload: {
+        toolUseId: pending.id,
+        toolName: pending.name,
+        toolInput: pending.input
+      },
+      createdAt: pending.timestamp
+    });
+  }
+  return logs.sort((left, right) => Date.parse(left.createdAt) - Date.parse(right.createdAt));
+}
+var snapshotCache = new Map;
+var RUN_LOG_SNAPSHOT_TAIL_LIMIT = 200;
+function runListSignature(runs) {
+  return runs.slice().sort((a, b) => a.runId.localeCompare(b.runId)).map((run) => `${run.runId}|${run.updatedAt ?? ""}|${run.completedAt ?? ""}`).join(";");
+}
+function buildConversationSnapshot(projectRoot, options = {}) {
+  const runs = listAuthorityRuns2(projectRoot);
+  const signature = runListSignature(runs);
+  if (!options.force) {
+    const cached = snapshotCache.get(projectRoot);
+    if (cached && cached.signature === signature) {
+      return cached.snapshot;
+    }
+  }
+  const conversations = [];
+  const messages = [];
+  const logs = [];
+  const actions = [];
+  for (const run of runs) {
+    const conversationId = `conversation:${run.runId}`;
+    conversations.push({
+      id: conversationId,
+      runId: run.runId,
+      title: run.title,
+      createdAt: run.createdAt,
+      updatedAt: run.updatedAt
+    });
+    const timeline = readJsonlFile2(runTimelinePath(projectRoot, run.runId));
+    for (const raw of timeline) {
+      if (!raw || typeof raw !== "object")
+        continue;
+      const entry = raw;
+      const type = normalizeString(entry.type) ?? "system_message";
+      const createdAt = normalizeString(entry.createdAt) ?? run.updatedAt;
+      if (type === "user_message" || type === "assistant_message" || type === "system_message") {
+        const role = type === "assistant_message" ? "assistant" : type === "user_message" ? "user" : "system";
+        messages.push({
+          id: normalizeString(entry.id) ?? `${run.runId}-${messages.length + 1}`,
+          conversationId,
+          role,
+          text: typeof entry.text === "string" ? entry.text : "",
+          attachments: Array.isArray(entry.attachments) ? entry.attachments : [],
+          state: normalizeString(entry.state) === "streaming" ? "streaming" : normalizeString(entry.state) === "interrupted" ? "interrupted" : normalizeString(entry.state) === "errored" ? "errored" : "completed",
+          createdAt,
+          completedAt: normalizeString(entry.completedAt) ?? (normalizeString(entry.state) === "streaming" ? null : createdAt)
+        });
+        continue;
+      }
+      if (type === "action") {
+        actions.push({
+          id: normalizeString(entry.id) ?? `${run.runId}-action-${actions.length + 1}`,
+          runId: run.runId,
+          messageId: normalizeString(entry.messageId),
+          actionType: normalizeString(entry.actionType) ?? "task",
+          title: normalizeString(entry.title) ?? "Run step",
+          detail: normalizeString(entry.detail),
+          state: normalizeString(entry.state) ?? "completed",
+          payload: entry.payload ?? {},
+          startedAt: createdAt,
+          completedAt: normalizeString(entry.completedAt) ?? null
+        });
+      }
+    }
+    const runLogs = readJsonlFileTail(runLogsPath(projectRoot, run.runId), {
+      limit: RUN_LOG_SNAPSHOT_TAIL_LIMIT,
+      maxBytes: 512 * 1024
+    });
+    const claudeStreamLogs = buildClaudeStreamLogs(run);
+    const hasClaudeStreamLogs = claudeStreamLogs.length > 0;
+    for (const raw of runLogs) {
+      if (!raw || typeof raw !== "object")
+        continue;
+      const entry = raw;
+      const createdAt = normalizeString(entry.createdAt) ?? run.updatedAt;
+      const rawDetail = normalizeString(entry.detail);
+      if (hasClaudeStreamLogs && rawDetail) {
+        try {
+          const parsed = JSON.parse(rawDetail);
+          const parsedType = normalizeString(parsed.type);
+          if (parsedType === "assistant" || parsedType === "user" || parsedType === "system" || parsedType === "result") {
+            continue;
+          }
+        } catch {}
+      }
+      logs.push({
+        id: normalizeString(entry.id) ?? `${run.runId}-log-${logs.length + 1}`,
+        runId: run.runId,
+        title: normalizeString(entry.title) ?? "Run log",
+        detail: normalizeString(entry.detail),
+        tone: normalizeString(entry.tone) === "error" ? "error" : normalizeString(entry.tone) === "tool" ? "tool" : normalizeString(entry.tone) === "thinking" ? "thinking" : "info",
+        status: normalizeString(entry.status),
+        payload: entry.payload ?? {},
+        createdAt
+      });
+    }
+    logs.push(...claudeStreamLogs);
+  }
+  logs.sort((left, right) => Date.parse(left.createdAt) - Date.parse(right.createdAt));
+  const snapshot = { conversations, messages, logs, actions };
+  snapshotCache.set(projectRoot, { signature, snapshot });
+  return snapshot;
+}
+
+// packages/server/src/server-helpers/snapshot-orchestrator.ts
+async function buildTaskPrompt(projectRoot, taskId, readers) {
+  const task = (await readers.readWorkspaceTasks(projectRoot)).find((entry) => entry.id === taskId);
+  if (!task) {
+    return `Work on task ${taskId}.`;
+  }
+  const sections = [
+    `You are working on task ${task.id}: ${task.title}.`,
+    task.description ? `Description:
+${task.description}` : null,
+    task.acceptanceCriteria ? `Acceptance criteria:
+${task.acceptanceCriteria}` : null,
+    task.scope.length > 0 ? `Scope:
+- ${task.scope.join(`
+- `)}` : null,
+    task.validation.length > 0 ? `Validation:
+- ${task.validation.join(`
+- `)}` : null,
+    "Work directly in the assigned runtime workspace and leave the result in a reviewable state."
+  ];
+  return sections.filter((value) => Boolean(value)).join(`
+
+`);
+}
+async function buildRigSnapshotPayload(projectRoot, readers) {
+  const workspace = await readers.readWorkspaceSummaryRecord(projectRoot);
+  const queue = readQueueState(projectRoot);
+  const queuedTaskIds = new Set(queue.map((entry) => entry.taskId));
+  const graph = buildWorkspaceGraphSummary(workspace, []);
+  const taskSummaries = (await readers.readWorkspaceTasks(projectRoot)).map((task) => ({
+    ...toTaskSummary(workspace.id, {
+      ...task,
+      status: queuedTaskIds.has(task.id) && (task.status === "open" || task.status === "ready" || task.status === "draft") ? "queued" : task.status
+    }),
+    graphId: graph.id
+  }));
+  const populatedGraph = buildWorkspaceGraphSummary(workspace, taskSummaries);
+  const authorityRuns = listAuthorityRuns3(projectRoot);
+  const approvalRecords = readApprovalsForRuns(projectRoot, authorityRuns);
+  const userInputRecords = readUserInputsForRuns(projectRoot, authorityRuns);
+  const approvals = approvalRecords.map(toApprovalSummary);
+  const userInputs = userInputRecords.map(toUserInputSummary);
+  const runs = authorityRuns.map((run) => toRunSummary(run, approvalRecords.filter((entry) => entry.runId === run.runId), userInputRecords.filter((entry) => entry.runId === run.runId)));
+  const artifacts = await readers.listArtifactSummaries(projectRoot, null, { knownRuns: authorityRuns });
+  return {
+    workspace,
+    snapshot: {
+      workspaces: [workspace],
+      graphs: [populatedGraph],
+      tasks: taskSummaries,
+      runs,
+      approvals,
+      userInputs,
+      artifacts,
+      queue,
+      updatedAt: workspace.updatedAt
+    },
+    approvals,
+    userInputs,
+    graphs: [populatedGraph],
+    tasks: taskSummaries,
+    runs,
+    artifacts,
+    queue
+  };
+}
+function buildRuntimeSnapshot(inputs) {
+  const { projectRoot, runProcesses, agentRuntimes } = inputs;
+  const runtimes = [];
+  const worktrees = [];
+  const runtimesById = new Map(agentRuntimes.map((runtime) => [runtime.id, runtime]));
+  for (const processState of runProcesses.values()) {
+    const run = readAuthorityRun2(projectRoot, processState.runId);
+    if (!run)
+      continue;
+    const runtimeId = normalizeString(run.branch);
+    const runtime = runtimeId ? runtimesById.get(runtimeId) ?? null : null;
+    const updatedAt = run.updatedAt;
+    const workspaceDir = runtime?.workspaceDir ?? run.worktreePath ?? null;
+    const logsDir = runtime?.logsDir ?? (workspaceDir ? resolve5(workspaceDir, ".rig", "logs") : run.logRoot);
+    const stateDir = runtime?.stateDir ?? (workspaceDir ? resolve5(workspaceDir, ".rig", "state") : null);
+    const sessionDir = runtime?.sessionDir ?? (workspaceDir ? resolve5(workspaceDir, ".rig", "session") : run.sessionPath ? dirname4(run.sessionPath) : null);
+    const sessionLogPath = runtime?.sessionDir || workspaceDir ? logsDir ? resolve5(logsDir, "session.log") : null : run.sessionLogPath;
+    runtimes.push({
+      id: runtimeId ?? `runtime:${run.runId}`,
+      workspaceId: run.workspaceId,
+      runId: run.runId,
+      adapterKind: run.runtimeAdapter,
+      executionTarget: run.mode === "remote" ? "remote" : "local",
+      remoteHostId: run.hostId,
+      status: run.status === "failed" ? "failed" : run.status === "stopped" ? "interrupted" : run.status === "running" ? "running" : run.status === "preparing" ? "starting" : "exited",
+      sandboxMode: normalizeString(run.runtimeMode) === "full-access" ? "danger-full-access" : "workspace-write",
+      isolationMode: "worktree",
+      workspaceDir,
+      homeDir: runtime?.homeDir ?? null,
+      tmpDir: runtime?.tmpDir ?? null,
+      cacheDir: runtime?.cacheDir ?? null,
+      logsDir,
+      stateDir,
+      sessionDir,
+      sessionLogPath,
+      pid: processState.child?.pid ?? null,
+      startedAt: run.startedAt,
+      updatedAt,
+      exitedAt: run.completedAt
+    });
+    if (workspaceDir) {
+      worktrees.push({
+        id: `worktree:${run.runId}`,
+        workspaceId: run.workspaceId,
+        runId: run.runId,
+        taskId: run.taskId,
+        branchName: runtimeId ?? `run:${run.runId}`,
+        path: workspaceDir,
+        status: run.completedAt ? "preserved" : "active",
+        createdAt: run.startedAt ?? run.createdAt,
+        cleanedAt: null
+      });
+    }
+  }
+  return { runtimes, worktrees };
+}
+async function buildEngineSnapshotPayload(inputs) {
+  const payload = await buildRigSnapshotPayload(inputs.projectRoot, inputs.readers);
+  const { conversations, messages, logs, actions } = buildConversationSnapshot(inputs.projectRoot);
+  const { runtimes, worktrees } = buildRuntimeSnapshot({
+    projectRoot: inputs.projectRoot,
+    runProcesses: inputs.runProcesses,
+    agentRuntimes: inputs.agentRuntimes
+  });
+  const remoteEndpoints = buildRemoteEndpointSnapshot(inputs.projectRoot, inputs.remoteHosts);
+  const remoteConnections = buildRemoteConnectionSnapshot(inputs.remoteHosts, inputs.remoteConnections, remoteEndpoints);
+  return {
+    snapshotSequence: normalizeSequence(inputs.sequence) ?? 0,
+    workspaces: payload.snapshot.workspaces,
+    graphs: payload.snapshot.graphs,
+    tasks: payload.snapshot.tasks,
+    runs: payload.snapshot.runs,
+    runtimes,
+    conversations,
+    messages,
+    actions,
+    logs,
+    approvals: payload.snapshot.approvals,
+    userInputs: payload.snapshot.userInputs,
+    validations: [],
+    reviews: [],
+    artifacts: payload.snapshot.artifacts,
+    policyDecisions: [],
+    queue: payload.queue,
+    worktrees,
+    remoteEndpoints,
+    remoteConnections,
+    remoteOrchestrations: [],
+    updatedAt: payload.snapshot.updatedAt
+  };
+}
+export {
+  buildTaskPrompt,
+  buildRuntimeSnapshot,
+  buildRigSnapshotPayload,
+  buildEngineSnapshotPayload
+};