vericify 0.1.0

package/src/projection/runs.js

@@ -0,0 +1,809 @@
+import { fingerprintText, similarityFromText } from "../similarity/semantic-hash.js";
+import { asArray, firstDefined, hashText, isoNow, slugify, unique, workspaceRef } from "../core/util.js";
+import {
+  checkpointTriggerFromHandoff,
+  checkpointTriggerFromLedgerEntry,
+  checkpointTriggerFromProcessPost,
+  checkpointTriggerFromStatusEvent,
+  checkpointTriggerFromWorkspaceSummary,
+} from "../checkpoints/policy.js";
+
+function sortByUpdatedDescending(items) {
+  return [...items].sort((left, right) => String(right.updated_at).localeCompare(String(left.updated_at)));
+}
+
+function laneStatusFromHandoffStatus(status, isRecipient) {
+  if (status === "blocked") return "blocked";
+  if (status === "completed") return "completed";
+  if (isRecipient) return "running";
+  return "idle";
+}
+
+function inferRunStatus(values) {
+  if (values.some((value) => value === "blocked" || value === "failed")) return "blocked";
+  if (values.some((value) => value === "running")) return "running";
+  if (values.some((value) => value === "completed")) return "completed";
+  if (values.some((value) => value === "planned")) return "planned";
+  return "planned";
+}
+
+function runStatusFromNodes(nodes) {
+  if (nodes.some((node) => node.status === "blocked")) return "blocked";
+  if (nodes.length > 0 && nodes.every((node) => node.status === "done")) return "completed";
+  if (nodes.some((node) => node.status === "in_progress" || node.status === "gated")) return "running";
+  if (nodes.length > 0) return "planned";
+  return "planned";
+}
+
+function runStatusFromHandoff(status) {
+  if (status === "blocked") return "blocked";
+  if (status === "completed") return "completed";
+  if (status === "accepted") return "running";
+  return "planned";
+}
+
+function statusFromEventStatus(status) {
+  if (status === "blocked" || status === "fail") return "blocked";
+  if (status === "done" || status === "pass") return "completed";
+  if (status === "in_progress" || status === "started") return "running";
+  return "planned";
+}
+
+function statusFromLedgerCategory(category) {
+  if (category === "regression") return "blocked";
+  if (category === "major_update") return "running";
+  return "planned";
+}
+
+function statusFromProcessPostKind(kind) {
+  if (kind === "blocker") return "blocked";
+  if (kind === "completion") return "completed";
+  return "running";
+}
+
+function humanizeToken(value) {
+  return String(value ?? "")
+    .replace(/[-_]+/g, " ")
+    .trim();
+}
+
+function activityItemFromProcessPost(post) {
+  return {
+    activity_id: post.process_post_id,
+    run_id: post.run_id,
+    branch_id: post.branch_id,
+    lane_id: post.lane_id,
+    timestamp: post.timestamp ?? isoNow(),
+    source_kind: "process_post",
+    actor_id: post.agent_id ?? "unknown",
+    label: post.kind,
+    status: statusFromProcessPostKind(post.kind),
+    summary: post.summary,
+    refs: unique([...asArray(post.evidence_refs), ...asArray(post.tool_refs)]),
+  };
+}
+
+function activityItemFromStatusEvent(runId, event) {
+  return {
+    activity_id: event.event_id ?? `${runId}:event:${hashText(`${event.timestamp}:${event.source_module}:${event.event_type}`).slice(0, 10)}`,
+    run_id: runId,
+    branch_id: explicitBranchId(runId, event),
+    lane_id: explicitLaneId(runId, event),
+    timestamp: event.timestamp ?? isoNow(),
+    source_kind: "status_event",
+    actor_id: event.source_module ?? "unknown",
+    label: event.event_type,
+    status: statusFromEventStatus(event.status),
+    summary: event.payload?.summary ?? event.event_type,
+    refs: asArray(event.payload?.evidence_ref),
+  };
+}
+
+function activityItemFromLedgerEntry(runId, entry) {
+  return {
+    activity_id: entry.id ?? `${runId}:ledger:${hashText(`${entry.timestamp_utc}:${entry.tool}:${entry.message}`).slice(0, 10)}`,
+    run_id: runId,
+    branch_id: explicitBranchId(runId, entry),
+    lane_id: explicitLaneId(runId, entry),
+    timestamp: entry.timestamp_utc ?? isoNow(),
+    source_kind: "run_ledger",
+    actor_id: entry.tool ?? "unknown",
+    label: entry.category,
+    status: statusFromLedgerCategory(entry.category),
+    summary: entry.message,
+    refs: asArray(entry.artifacts),
+  };
+}
+
+function summarizeLaneHeartbeat(lane, latestActivity) {
+  const node = lane.current_node_id ? humanizeToken(lane.current_node_id) : "";
+  const nodePart = node ? ` on ${node}` : "";
+  const latestPart = latestActivity
+    ? ` Latest ${latestActivity.label}: ${latestActivity.summary}`
+    : lane.status === "idle"
+      ? " Awaiting new work."
+      : " Awaiting next signal.";
+  return `${lane.status}${nodePart}.${latestPart}`;
+}
+
+function activityItemFromLaneHeartbeat(runDetail, lane, latestActivity) {
+  const branch = runDetail.branches.find((candidate) => candidate.lane_ids?.includes(lane.lane_id));
+  return {
+    activity_id: `${runDetail.run.run_id}:lane-heartbeat:${slugify(lane.lane_id) || hashText(lane.lane_id).slice(0, 10)}`,
+    run_id: runDetail.run.run_id,
+    branch_id: branch?.branch_id,
+    lane_id: lane.lane_id,
+    timestamp: lane.updated_at ?? isoNow(),
+    source_kind: "lane_heartbeat",
+    actor_id: lane.agent_id ?? "unknown",
+    label: "heartbeat",
+    status: lane.status,
+    summary: summarizeLaneHeartbeat(lane, latestActivity),
+    refs: latestActivity?.refs ?? [],
+  };
+}
+
+function checkpointFromSummary({
+  checkpointId,
+  runId,
+  branchId,
+  laneId,
+  handoffId,
+  nodeRef,
+  timestamp,
+  summary,
+  taskDelta,
+  evidenceRefs,
+  gitCommitSha,
+  checkpointMeta = {},
+}) {
+  return {
+    checkpoint_id: checkpointId,
+    run_id: runId,
+    branch_id: branchId,
+    lane_id: laneId,
+    handoff_id: handoffId,
+    node_ref: nodeRef,
+    timestamp,
+    git_commit_sha: gitCommitSha,
+    checkpoint_policy_version: checkpointMeta.checkpoint_policy_version,
+    trigger_kind: checkpointMeta.trigger_kind,
+    trigger_reason: checkpointMeta.trigger_reason,
+    capture_mode: checkpointMeta.capture_mode,
+    semantic_fingerprint: fingerprintText(summary),
+    task_delta_summary: taskDelta,
+    evidence_refs: evidenceRefs ?? [],
+    process_summary: summary,
+  };
+}
+
+function sortByTimestamp(items, accessor) {
+  return [...items].sort((left, right) => String(accessor(left)).localeCompare(String(accessor(right))));
+}
+
+function explicitBranchId(runId, record) {
+  return firstDefined(record.branch_id, record.payload?.branch_id, record.metadata?.branch_id) ?? `${runId}:main`;
+}
+
+function explicitLaneId(runId, record) {
+  const direct = firstDefined(record.lane_id, record.payload?.lane_id, record.metadata?.lane_id);
+  if (direct) return direct;
+  const agent = firstDefined(record.agent_id, record.source_module, record.from_agent, record.from, "unknown");
+  const processId = firstDefined(record.process_id, record.payload?.process_id, record.metadata?.process_id);
+  const suffix = processId ? `${slugify(agent)}:${slugify(String(processId))}` : slugify(String(agent));
+  return `${runId}:lane:${suffix || "unknown"}`;
+}
+
+function runIdFromStatusEvent(event) {
+  return firstDefined(event.run_id, event.payload?.run_id) ??
+    (event.objective_id ? `objective:${event.objective_id}` : event.trace_id ? `trace:${event.trace_id}` : null);
+}
+
+function runIdFromLedgerEntry(entry) {
+  const metadata = entry.metadata ?? {};
+  return firstDefined(
+    metadata.run_id,
+    metadata.runId,
+    metadata.trace_id ? `trace:${metadata.trace_id}` : undefined,
+    metadata.objective_id ? `objective:${metadata.objective_id}` : undefined,
+    metadata.handoff_id ? `handoff:${metadata.handoff_id}` : undefined
+  );
+}
+
+function matchingRunIdsForHandoff(handoff) {
+  return unique([`handoff:${handoff.handoff_id}`, handoff.handoff_id]);
+}
+
+function deltaBetween(left, right, id) {
+  const layers = ["structural", "semantic", "operational"];
+  if (left?.git_commit_sha && right?.git_commit_sha) layers.unshift("exact");
+  return {
+    delta_id: id,
+    from_checkpoint_id: left.checkpoint_id,
+    to_checkpoint_id: right.checkpoint_id,
+    layers,
+    semantic_similarity: similarityFromText(left.process_summary, right.process_summary),
+    summary: `${left.process_summary.slice(0, 80)} -> ${right.process_summary.slice(0, 80)}`,
+  };
+}
+
+function summarizeRun(run, branches, lanes, nodes, handoffs, checkpoints, neighbors) {
+  const latestCheckpoint = checkpoints[checkpoints.length - 1];
+  return {
+    run_id: run.run_id,
+    title: run.title,
+    status: run.status,
+    branch_count: branches.length,
+    lane_count: lanes.length,
+    current_node_labels: unique(nodes.filter((node) => node.status !== "done").map((node) => node.title)).slice(0, 5),
+    last_handoff_at: handoffs.length ? handoffs[handoffs.length - 1].updated_at ?? handoffs[handoffs.length - 1].created_at : run.updated_at,
+    completion_confidence: run.status === "completed" ? 1 : run.status === "blocked" ? 0.2 : Math.min(0.9, 0.35 + checkpoints.length * 0.08),
+    updated_at: run.updated_at,
+    similar_runs: neighbors,
+    latest_checkpoint: latestCheckpoint,
+  };
+}
+
+function evidenceRefsFor(workspaceState, key, fallback) {
+  const refs = workspaceState.sourceRefs?.[key];
+  return Array.isArray(refs) && refs.length ? refs : fallback;
+}
+
+function buildHandoffRun(handoff, workspace) {
+  const runId = `handoff:${handoff.handoff_id}`;
+  const branchId = `${runId}:main`;
+  const roleAgents = unique([handoff.from, handoff.to]);
+  const lanes = roleAgents.map((agent) => ({
+    lane_id: `${runId}:lane:${slugify(agent)}`,
+    agent_id: agent,
+    status: laneStatusFromHandoffStatus(handoff.status, agent === handoff.to),
+    current_node_id: handoff.task_type ? slugify(handoff.task_type) : undefined,
+    updated_at: handoff.updated_at ?? handoff.created_at,
+  }));
+  const history = Array.isArray(handoff.history) && handoff.history.length
+    ? handoff.history
+    : [{ timestamp_utc: handoff.created_at, status: handoff.status, actor: handoff.from, note: handoff.title }];
+  const checkpoints = history.map((entry, index) => checkpointFromSummary({
+    checkpointId: `${runId}:cp:${index + 1}`,
+    runId,
+    branchId,
+    laneId: lanes[0]?.lane_id,
+    handoffId: handoff.handoff_id,
+    nodeRef: handoff.task_type ?? handoff.title,
+    timestamp: entry.timestamp_utc ?? handoff.updated_at ?? handoff.created_at,
+    summary: `${handoff.title}\n${entry.status}\n${entry.note ?? ""}\nfrom:${handoff.from} to:${handoff.to}`,
+    taskDelta: entry.note ?? handoff.title,
+    evidenceRefs: handoff.source_file ? [handoff.source_file] : [],
+    checkpointMeta: checkpointTriggerFromHandoff(handoff, entry),
+  }));
+  const deltas = checkpoints.length > 1
+    ? checkpoints.slice(1).map((checkpoint, index) => deltaBetween(checkpoints[index], checkpoint, `${runId}:delta:${index + 1}`))
+    : [];
+  const branch = {
+    branch_id: branchId,
+    run_id: runId,
+    name: "main",
+    status: runStatusFromHandoff(handoff.status),
+    lane_ids: lanes.map((lane) => lane.lane_id),
+  };
+  const run = {
+    run_id: runId,
+    workspace,
+    title: handoff.title ?? handoff.handoff_id,
+    objective: handoff.task_type ?? handoff.priority,
+    status: runStatusFromHandoff(handoff.status),
+    created_at: handoff.created_at,
+    updated_at: handoff.updated_at ?? handoff.created_at,
+    branch_ids: [branchId],
+    lane_ids: lanes.map((lane) => lane.lane_id),
+    checkpoint_ids: checkpoints.map((checkpoint) => checkpoint.checkpoint_id),
+  };
+  const handoffView = {
+    handoff_id: handoff.handoff_id,
+    run_id: runId,
+    branch_id: branchId,
+    lane_id: lanes[0]?.lane_id,
+    status: handoff.status,
+    from_agent: handoff.from,
+    to_agent: handoff.to,
+    node_ref: handoff.task_type ?? handoff.title,
+    created_at: handoff.created_at,
+    updated_at: handoff.updated_at ?? handoff.created_at,
+    checkpoint_id: checkpoints[checkpoints.length - 1]?.checkpoint_id,
+  };
+  return {
+    run,
+    branches: [branch],
+    lanes,
+    nodes: [],
+    handoff_timeline: { run_id: runId, items: [handoffView] },
+    recent_checkpoints: checkpoints,
+    deltas,
+    process_posts: [],
+    activity_items: [],
+    similarity: { target_run_id: runId, neighbors: [] },
+  };
+}
+
+function buildWorkspaceRun(workspaceState, workspace) {
+  if (
+    workspaceState.todoNodes.length === 0 &&
+    workspaceState.statusEvents.length === 0 &&
+    workspaceState.ledgerEntries.length === 0 &&
+    workspaceState.processPosts.length === 0
+  ) return null;
+  const runId = "workspace:current";
+  const branchId = `${runId}:main`;
+  const activeEvents = workspaceState.statusEvents.slice(-25);
+  const activeLedger = workspaceState.ledgerEntries.slice(-12);
+  const activePosts = workspaceState.processPosts.slice(-12);
+  const laneMap = new Map();
+  for (const event of activeEvents) {
+    const laneId = explicitLaneId(runId, event);
+    laneMap.set(laneId, {
+      lane_id: laneId,
+      agent_id: event.source_module ?? "unknown",
+      process_id: firstDefined(event.process_id, event.payload?.process_id),
+      status: statusFromEventStatus(event.status),
+      current_node_id: slugify(event.objective_id ?? event.event_type ?? "activity"),
+      updated_at: event.timestamp ?? isoNow(),
+    });
+  }
+  for (const post of activePosts) {
+    const laneId = explicitLaneId(runId, post);
+    laneMap.set(laneId, {
+      lane_id: laneId,
+      agent_id: post.agent_id ?? "unknown",
+      process_id: post.process_id,
+      status: statusFromProcessPostKind(post.kind),
+      current_node_id: slugify(post.summary),
+      updated_at: post.timestamp ?? isoNow(),
+    });
+  }
+  const lanes = [...laneMap.values()];
+  const checkpoints = [
+    checkpointFromSummary({
+      checkpointId: `${runId}:cp:1`,
+      runId,
+      branchId,
+      laneId: lanes[0]?.lane_id,
+      timestamp: isoNow(),
+      summary: [
+        "Workspace current run",
+        ...workspaceState.todoNodes.slice(0, 12).map((node) => `${node.status}:${node.title}`),
+        ...activeEvents.slice(-8).map((event) => `${event.source_module}:${event.event_type}:${event.status}`),
+        ...activeLedger.slice(-4).map((entry) => `${entry.tool}:${entry.category}:${entry.message}`),
+        ...activePosts.slice(-4).map((post) => `${post.agent_id}:${post.kind}:${post.summary}`),
+      ].join("\n"),
+      taskDelta: workspaceState.todoNodes.filter((node) => node.status !== "done").map((node) => node.title).slice(0, 6).join(", "),
+      evidenceRefs: unique([
+        ...evidenceRefsFor(workspaceState, "todoState", [".vericify/todo-state.json", "agent-state/todo-state.json"]),
+        ...evidenceRefsFor(workspaceState, "statusEvents", [".vericify/status-events.ndjson", "agent-state/STATUS_EVENTS.ndjson"]),
+        ...evidenceRefsFor(workspaceState, "runLedger", [".vericify/run-ledger.json", "agent-state/run-ledger.json"]),
+        ...evidenceRefsFor(workspaceState, "processPosts", [".vericify/process-posts.json", "agent-state/vericify/process-posts.json"]),
+      ]),
+      checkpointMeta: checkpointTriggerFromWorkspaceSummary(),
+    }),
+  ];
+  const branch = {
+    branch_id: branchId,
+    run_id: runId,
+    name: "main",
+    status: inferRunStatus([
+      runStatusFromNodes(workspaceState.todoNodes),
+      ...activeEvents.map((event) => statusFromEventStatus(event.status)),
+      ...activePosts.map((post) => statusFromProcessPostKind(post.kind)),
+    ]),
+    lane_ids: lanes.map((lane) => lane.lane_id),
+  };
+  const run = {
+    run_id: runId,
+    workspace,
+    title: "Workspace Current",
+    objective: "Current workspace execution state",
+    status: branch.status,
+    created_at: workspaceState.statusEvents[0]?.timestamp ?? isoNow(),
+    updated_at: firstDefined(
+      workspaceState.processPosts[workspaceState.processPosts.length - 1]?.timestamp,
+      workspaceState.statusEvents[workspaceState.statusEvents.length - 1]?.timestamp,
+      workspaceState.ledgerEntries[workspaceState.ledgerEntries.length - 1]?.timestamp_utc,
+      isoNow()
+    ),
+    branch_ids: [branchId],
+    lane_ids: lanes.map((lane) => lane.lane_id),
+    checkpoint_ids: checkpoints.map((checkpoint) => checkpoint.checkpoint_id),
+  };
+  return {
+    run,
+    branches: [branch],
+    lanes,
+    nodes: workspaceState.todoNodes.map((node) => ({
+      node_id: node.id,
+      title: node.title,
+      status: node.status,
+      priority: node.priority,
+    })),
+    handoff_timeline: { run_id: runId, items: [] },
+    recent_checkpoints: checkpoints,
+    deltas: [],
+    process_posts: sortByTimestamp(activePosts, (post) => post.timestamp),
+    activity_items: [],
+    similarity: { target_run_id: runId, neighbors: [] },
+  };
+}
+
+function buildObjectiveRuns(workspaceState, workspace) {
+  const grouped = new Map();
+  for (const event of workspaceState.statusEvents) {
+    const key = runIdFromStatusEvent(event);
+    if (!key) continue;
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key).push(event);
+  }
+  return [...grouped.entries()].map(([runId, events]) => {
+    const sortedEvents = sortByTimestamp(events, (event) => event.timestamp ?? "");
+    const branchIds = unique(sortedEvents.map((event) => explicitBranchId(runId, event)));
+    const laneIds = unique(sortedEvents.map((event) => explicitLaneId(runId, event)));
+    const branches = branchIds.map((branchId) => ({
+      branch_id: branchId,
+      run_id: runId,
+      name: branchId === `${runId}:main` ? "main" : branchId.split(":").at(-1) ?? "branch",
+      status: statusFromEventStatus(sortedEvents[sortedEvents.length - 1]?.status),
+      lane_ids: laneIds.filter((laneId) => laneId.startsWith(branchId) || branchId === `${runId}:main`),
+    }));
+    const lanes = laneIds.map((laneId) => {
+      const related = sortedEvents.filter((event) => explicitLaneId(runId, event) === laneId);
+      const latest = related[related.length - 1];
+      return {
+        lane_id: laneId,
+        agent_id: latest.source_module ?? "unknown",
+        process_id: firstDefined(latest.process_id, latest.payload?.process_id),
+        status: statusFromEventStatus(latest.status),
+        current_node_id: slugify(latest.event_type ?? latest.objective_id ?? "event"),
+        updated_at: latest.timestamp ?? isoNow(),
+      };
+    });
+    const checkpoints = sortedEvents.map((event, index) => checkpointFromSummary({
+      checkpointId: `${runId}:cp:${index + 1}`,
+      runId,
+      branchId: explicitBranchId(runId, event),
+      laneId: explicitLaneId(runId, event),
+      timestamp: event.timestamp ?? isoNow(),
+      summary: `${event.event_type}\n${event.status}\n${event.payload?.summary ?? ""}`,
+      taskDelta: event.payload?.summary ?? event.event_type,
+      evidenceRefs: event.payload?.evidence_ref ? [event.payload.evidence_ref] : [],
+      gitCommitSha: firstDefined(event.git_commit_sha, event.payload?.git_commit_sha, event.metadata?.git_commit_sha),
+      checkpointMeta: checkpointTriggerFromStatusEvent(event, sortedEvents[index - 1]),
+    }));
+    const deltas = checkpoints.length > 1
+      ? checkpoints.slice(1).map((checkpoint, index) => deltaBetween(checkpoints[index], checkpoint, `${runId}:delta:${index + 1}`))
+      : [];
+    const run = {
+      run_id: runId,
+      workspace,
+      title: sortedEvents[sortedEvents.length - 1]?.payload?.summary ?? runId,
+      objective: sortedEvents[0]?.objective_id ?? sortedEvents[0]?.trace_id ?? runId,
+      status: statusFromEventStatus(sortedEvents[sortedEvents.length - 1]?.status),
+      created_at: sortedEvents[0]?.timestamp ?? isoNow(),
+      updated_at: sortedEvents[sortedEvents.length - 1]?.timestamp ?? isoNow(),
+      branch_ids: branches.map((branch) => branch.branch_id),
+      lane_ids: lanes.map((lane) => lane.lane_id),
+      checkpoint_ids: checkpoints.map((checkpoint) => checkpoint.checkpoint_id),
+    };
+    return {
+      run,
+      branches,
+      lanes,
+      nodes: [],
+      handoff_timeline: { run_id: runId, items: [] },
+      recent_checkpoints: checkpoints,
+      deltas,
+      process_posts: [],
+      activity_items: [],
+      similarity: { target_run_id: runId, neighbors: [] },
+    };
+  });
+}
+
+function ensureBranch(runDetail, branchId) {
+  if (!runDetail.branches.some((branch) => branch.branch_id === branchId)) {
+    runDetail.branches.push({
+      branch_id: branchId,
+      run_id: runDetail.run.run_id,
+      name: branchId === `${runDetail.run.run_id}:main` ? "main" : branchId.split(":").at(-1) ?? "branch",
+      status: runDetail.run.status,
+      lane_ids: [],
+    });
+  }
+  return runDetail.branches.find((branch) => branch.branch_id === branchId);
+}
+
+function ensureLane(runDetail, lane) {
+  const existing = runDetail.lanes.find((candidate) => candidate.lane_id === lane.lane_id);
+  if (existing) {
+    Object.assign(existing, lane);
+    return existing;
+  }
+  runDetail.lanes.push(lane);
+  return lane;
+}
+
+function attachProcessPosts(runs, workspaceState, workspace) {
+  const byId = new Map();
+  for (const run of runs) {
+    byId.set(run.run.run_id, run);
+    if (run.run.run_id.startsWith("handoff:")) {
+      byId.set(run.run.run_id.slice("handoff:".length), run);
+    }
+  }
+  const postsByRun = new Map();
+  for (const post of sortByTimestamp(workspaceState.processPosts, (post) => post.timestamp ?? "")) {
+    const key = post.run_id;
+    if (!postsByRun.has(key)) postsByRun.set(key, []);
+    postsByRun.get(key).push(post);
+  }
+  for (const [runId, posts] of postsByRun.entries()) {
+    let runDetail = byId.get(runId);
+    if (!runDetail) {
+      const branchId = explicitBranchId(runId, posts[0]);
+      const laneId = explicitLaneId(runId, posts[0]);
+      runDetail = {
+        run: {
+          run_id: runId,
+          workspace,
+          title: posts[posts.length - 1].summary,
+          objective: runId,
+          status: statusFromProcessPostKind(posts[posts.length - 1].kind),
+          created_at: posts[0].timestamp ?? isoNow(),
+          updated_at: posts[posts.length - 1].timestamp ?? isoNow(),
+          branch_ids: [branchId],
+          lane_ids: [laneId],
+          checkpoint_ids: [],
+        },
+        branches: [{
+          branch_id: branchId,
+          run_id: runId,
+          name: branchId === `${runId}:main` ? "main" : branchId.split(":").at(-1) ?? "branch",
+          status: statusFromProcessPostKind(posts[posts.length - 1].kind),
+          lane_ids: [laneId],
+        }],
+        lanes: [{
+          lane_id: laneId,
+          agent_id: posts[0].agent_id,
+          status: statusFromProcessPostKind(posts[posts.length - 1].kind),
+          updated_at: posts[posts.length - 1].timestamp ?? isoNow(),
+        }],
+        nodes: [],
+        handoff_timeline: { run_id: runId, items: [] },
+        recent_checkpoints: [],
+        deltas: [],
+        process_posts: [],
+        activity_items: [],
+        similarity: { target_run_id: runId, neighbors: [] },
+      };
+      runs.push(runDetail);
+      byId.set(runId, runDetail);
+    }
+    for (const post of posts) {
+      const branchId = explicitBranchId(runDetail.run.run_id, post);
+      const laneId = explicitLaneId(runDetail.run.run_id, post);
+      const branch = ensureBranch(runDetail, branchId);
+      if (!branch.lane_ids.includes(laneId)) branch.lane_ids.push(laneId);
+      ensureLane(runDetail, {
+        lane_id: laneId,
+        agent_id: post.agent_id,
+        status: statusFromProcessPostKind(post.kind),
+        updated_at: post.timestamp ?? isoNow(),
+      });
+      runDetail.process_posts.push(post);
+      const checkpoint = checkpointFromSummary({
+        checkpointId: `${runDetail.run.run_id}:post:${runDetail.process_posts.length}`,
+        runId: runDetail.run.run_id,
+        branchId,
+        laneId,
+        timestamp: post.timestamp ?? isoNow(),
+        summary: `${post.kind}\n${post.summary}\nagent:${post.agent_id}`,
+        taskDelta: post.summary,
+        evidenceRefs: [...asArray(post.evidence_refs), ...asArray(post.tool_refs)],
+        checkpointMeta: checkpointTriggerFromProcessPost(post),
+      });
+      runDetail.recent_checkpoints.push(checkpoint);
+      runDetail.run.updated_at = checkpoint.timestamp;
+      runDetail.run.title = runDetail.run.title || post.summary;
+      runDetail.run.status = inferRunStatus([runDetail.run.status, statusFromProcessPostKind(post.kind)]);
+      if (!runDetail.run.branch_ids.includes(branchId)) runDetail.run.branch_ids.push(branchId);
+      if (!runDetail.run.lane_ids.includes(laneId)) runDetail.run.lane_ids.push(laneId);
+      runDetail.run.checkpoint_ids.push(checkpoint.checkpoint_id);
+    }
+  }
+}
+
+function attachActivityItems(runs, workspaceState) {
+  const byId = new Map();
+  for (const run of runs) {
+    byId.set(run.run.run_id, run);
+    if (run.run.run_id.startsWith("handoff:")) {
+      byId.set(run.run.run_id.slice("handoff:".length), run);
+    }
+  }
+  const workspaceRun = byId.get("workspace:current");
+
+  const pushActivity = (runDetail, item) => {
+    if (!runDetail) return;
+    if (!Array.isArray(runDetail.activity_items)) runDetail.activity_items = [];
+    runDetail.activity_items.push(item);
+  };
+
+  for (const post of sortByTimestamp(workspaceState.processPosts, (item) => item.timestamp ?? "")) {
+    const runDetail = byId.get(post.run_id);
+    const item = activityItemFromProcessPost(post);
+    pushActivity(runDetail, item);
+    if (workspaceRun && workspaceRun !== runDetail) {
+      pushActivity(workspaceRun, {
+        ...item,
+        activity_id: `${item.activity_id}:workspace`,
+        run_id: workspaceRun.run.run_id,
+      });
+    }
+  }
+
+  for (const event of sortByTimestamp(workspaceState.statusEvents, (item) => item.timestamp ?? "")) {
+    const runId = runIdFromStatusEvent(event) ?? "workspace:current";
+    const runDetail = byId.get(runId);
+    const item = activityItemFromStatusEvent(runId, event);
+    pushActivity(runDetail, item);
+    if (workspaceRun && workspaceRun !== runDetail) {
+      pushActivity(workspaceRun, {
+        ...item,
+        activity_id: `${item.activity_id}:workspace`,
+        run_id: workspaceRun.run.run_id,
+      });
+    }
+  }
+
+  for (const entry of sortByTimestamp(workspaceState.ledgerEntries, (item) => item.timestamp_utc ?? "")) {
+    const runId = runIdFromLedgerEntry(entry) ?? "workspace:current";
+    const runDetail = byId.get(runId);
+    const item = activityItemFromLedgerEntry(runId, entry);
+    pushActivity(runDetail, item);
+    if (workspaceRun && workspaceRun !== runDetail) {
+      pushActivity(workspaceRun, {
+        ...item,
+        activity_id: `${item.activity_id}:workspace`,
+        run_id: workspaceRun.run.run_id,
+      });
+    }
+  }
+}
+
+function attachLaneHeartbeats(runs) {
+  for (const runDetail of runs) {
+    const sourceItems = (runDetail.activity_items ?? []).filter((item) => item.source_kind !== "lane_heartbeat");
+    for (const lane of runDetail.lanes ?? []) {
+      const latestActivity = sortByTimestamp(
+        sourceItems.filter((item) => item.lane_id === lane.lane_id || (!item.lane_id && item.actor_id === lane.agent_id)),
+        (item) => item.timestamp ?? ""
+      ).at(-1);
+      runDetail.activity_items.push(activityItemFromLaneHeartbeat(runDetail, lane, latestActivity));
+    }
+  }
+}
+
+function attachLedgerEntries(runs, workspaceState) {
+  const byId = new Map(runs.map((run) => [run.run.run_id, run]));
+  for (const entry of sortByTimestamp(workspaceState.ledgerEntries, (item) => item.timestamp_utc ?? "")) {
+    const runId = runIdFromLedgerEntry(entry);
+    if (!runId) continue;
+    const runDetail = byId.get(runId);
+    if (!runDetail) continue;
+    const branchId = `${runDetail.run.run_id}:main`;
+    const laneId = `${runDetail.run.run_id}:lane:${slugify(entry.tool ?? "ledger")}`;
+    ensureBranch(runDetail, branchId);
+    ensureLane(runDetail, {
+      lane_id: laneId,
+      agent_id: entry.tool ?? "ledger",
+      status: statusFromLedgerCategory(entry.category),
+      updated_at: entry.timestamp_utc ?? isoNow(),
+    });
+    const checkpoint = checkpointFromSummary({
+      checkpointId: `${runDetail.run.run_id}:ledger:${entry.id ?? runDetail.recent_checkpoints.length + 1}`,
+      runId: runDetail.run.run_id,
+      branchId,
+      laneId,
+      timestamp: entry.timestamp_utc ?? isoNow(),
+      summary: `${entry.tool}\n${entry.category}\n${entry.message}`,
+      taskDelta: entry.message,
+      evidenceRefs: asArray(entry.artifacts),
+      gitCommitSha: firstDefined(entry.git_commit_sha, entry.metadata?.git_commit_sha),
+      checkpointMeta: checkpointTriggerFromLedgerEntry(entry),
+    });
+    runDetail.recent_checkpoints.push(checkpoint);
+    runDetail.run.updated_at = checkpoint.timestamp;
+    runDetail.run.status = inferRunStatus([runDetail.run.status, statusFromLedgerCategory(entry.category)]);
+    if (!runDetail.run.lane_ids.includes(laneId)) runDetail.run.lane_ids.push(laneId);
+    if (!runDetail.run.checkpoint_ids.includes(checkpoint.checkpoint_id)) {
+      runDetail.run.checkpoint_ids.push(checkpoint.checkpoint_id);
+    }
+  }
+}
+
+function finalizeRunDetails(runs) {
+  for (const run of runs) {
+    run.process_posts = sortByTimestamp(run.process_posts ?? [], (post) => post.timestamp ?? "");
+    run.activity_items = sortByTimestamp(run.activity_items ?? [], (item) => item.timestamp ?? "");
+    run.recent_checkpoints = sortByTimestamp(run.recent_checkpoints ?? [], (checkpoint) => checkpoint.timestamp ?? "");
+    run.deltas = run.recent_checkpoints.length > 1
+      ? run.recent_checkpoints.slice(1).map((checkpoint, index) => deltaBetween(run.recent_checkpoints[index], checkpoint, `${run.run.run_id}:delta:${index + 1}`))
+      : [];
+    run.run.branch_ids = unique(run.branches.map((branch) => branch.branch_id));
+    run.run.lane_ids = unique(run.lanes.map((lane) => lane.lane_id));
+    run.run.checkpoint_ids = unique(run.recent_checkpoints.map((checkpoint) => checkpoint.checkpoint_id));
+    run.run.updated_at = firstDefined(run.recent_checkpoints.at(-1)?.timestamp, run.run.updated_at, isoNow());
+    run.run.status = inferRunStatus([
+      run.run.status,
+      ...run.branches.map((branch) => branch.status),
+      ...run.lanes.map((lane) => lane.status),
+    ]);
+  }
+}
+
+function attachSimilarity(runs) {
+  for (const run of runs) {
+    const latest = run.recent_checkpoints[run.recent_checkpoints.length - 1];
+    if (!latest) continue;
+    const neighbors = runs
+      .filter((candidate) => candidate.run.run_id !== run.run.run_id)
+      .map((candidate) => {
+        const other = candidate.recent_checkpoints[candidate.recent_checkpoints.length - 1];
+        if (!other) return null;
+        return {
+          run_id: candidate.run.run_id,
+          score: similarityFromText(latest.process_summary, other.process_summary),
+          outcome: candidate.run.status,
+        };
+      })
+      .filter(Boolean)
+      .sort((left, right) => right.score - left.score)
+      .slice(0, 3);
+    run.similarity = {
+      target_run_id: run.run.run_id,
+      neighbors,
+    };
+    run.run_summary = summarizeRun(
+      run.run,
+      run.branches,
+      run.lanes,
+      run.nodes,
+      run.handoff_timeline.items,
+      run.recent_checkpoints,
+      neighbors
+    );
+  }
+}
+
+export function projectWorkspaceState(workspaceState) {
+  const workspace = workspaceRef(workspaceState.workspaceRoot);
+  const runs = [
+    ...workspaceState.handoffs.map((handoff) => buildHandoffRun(handoff, workspace)),
+    ...buildObjectiveRuns(workspaceState, workspace),
+  ];
+  const workspaceRun = buildWorkspaceRun(workspaceState, workspace);
+  if (workspaceRun) runs.push(workspaceRun);
+  attachProcessPosts(runs, workspaceState, workspace);
+  attachActivityItems(runs, workspaceState);
+  attachLaneHeartbeats(runs);
+  attachLedgerEntries(runs, workspaceState);
+  finalizeRunDetails(runs);
+  attachSimilarity(runs);
+  const sorted = sortByUpdatedDescending(runs.map((run) => ({
+    ...run,
+    updated_at: run.run.updated_at,
+  }))).map(({ updated_at, ...rest }) => rest);
+  return {
+    generated_at: isoNow(),
+    workspace,
+    adapter_profiles: workspaceState.adapterProfiles ?? [],
+    run_summaries: sorted.map((run) => run.run_summary),
+    runs: sorted,
+  };
+}