sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/run-state/artifacts.ts

@@ -1,118 +1,126 @@
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { getEvidenceAttachmentPath, getLegacyArtifactPath, getRunRelativeArtifactPath, normalizeArtifactRootRelativePath } from '../runtime-paths.js';
-import { readRuntimeRunState, recordRuntimeArtifactPayload, recordRuntimeEvidenceAttachment, resolveRuntimeArtifactPayload, runtimeScopedId, withRuntimeStore } from '../storage/runtime-store.js';
-import { appendArtifactHashLedgerEntry } from './invocation-ledger.js';
-
-export async function writeArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string): Promise<{ absolutePath: string; runRelativePath: string }> {
-  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
-  const runRelativePath = getRunRelativeArtifactPath(normalized);
-  const runScope = await resolveRunScope(projectRoot, runId);
-  const contentHash = hashDocumentContent(content);
-  const physicalPayloadPath = uniquePhysicalPayloadPath(runRelativePath, runId, contentHash);
-  const absolutePath = getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, physicalPayloadPath);
-  await mkdir(path.dirname(absolutePath), { recursive: true });
-  await writeFile(absolutePath, content, 'utf8');
-  await appendArtifactHashLedgerEntry(projectRoot, {
-    runId,
-    artifactPath: runRelativePath,
-    content,
-    status: 'written'
-  });
-  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'written', taskId: runScope.taskId });
-  await recordRuntimeArtifactPayload(projectRoot, {
-    payloadId: runtimeScopedId(runId, runRelativePath, contentHash),
-    runId,
-    sourceRunId: runId,
-    branchSlug: runScope.branchSlug,
-    taskId: runScope.taskId,
-    logicalRef: runRelativePath,
-    physicalPayloadPath,
-    artifactRole: artifactKind(runRelativePath),
-    digest: contentHash,
-    status: 'active',
-    payload: { logicalRef: runRelativePath, physicalPayloadPath, artifactPath: runRelativePath, status: 'written' }
-  });
-  await recordRuntimeEvidenceAttachment(projectRoot, {
-    branchSlug: runScope.branchSlug,
-    runId,
-    taskId: runScope.taskId,
-    kind: artifactKind(runRelativePath),
-    relativePath: physicalPayloadPath,
-    contentHash,
-    bytes: Buffer.byteLength(content, 'utf8'),
-    payload: { logicalRef: runRelativePath, physicalPayloadPath, status: 'written' }
-  });
-  return { absolutePath, runRelativePath };
-}
-
-export async function readArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string): Promise<string> {
-  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
-  const runRelativePath = getRunRelativeArtifactPath(normalized);
-  const payload = await resolveRuntimeArtifactPayload(projectRoot, runId, runRelativePath);
-  const runScope = await resolveRunScope(projectRoot, runId);
-  const evidencePath = getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, payload?.physicalPayloadPath ?? runRelativePath);
-  if (payload) {
-    return readFile(evidencePath, 'utf8');
-  }
-  try {
-    return await readFile(evidencePath, 'utf8');
-  } catch {
-    return readFile(getLegacyArtifactPath(projectRoot, runId, normalized), 'utf8');
-  }
-}
-
-function uniquePhysicalPayloadPath(logicalRef: string, runId: string, digest: string): string {
-  const parsed = path.posix.parse(logicalRef.replace(/\\/g, '/'));
-  const suffix = `${runId}-${digest.slice(0, 12)}`;
-  return path.posix.join(parsed.dir, `${parsed.name}-${suffix}${parsed.ext}`);
-}
-
-export function artifactKind(artifactPath: string): string {
-  const fileName = path.posix.basename(artifactPath.replace(/\\/g, '/'));
-  if (fileName.startsWith('implement-')) {
-    return 'implement';
-  }
-  if (fileName.startsWith('review-')) {
-    return 'review';
-  }
-  if (fileName.startsWith('debug-')) {
-    return 'debug';
-  }
-  if (fileName.startsWith('test-validation-')) {
-    return 'test-validation';
-  }
-  if (fileName.startsWith('validation-')) {
-    return 'validation';
-  }
-  if (fileName.startsWith('gap-report-')) {
-    return 'gap-report';
-  }
-  if (fileName === 'sync-back-proposal.md') {
-    return 'sync-back-proposal';
-  }
-  return 'artifact';
-}
-
-async function recordRuntimeArtifact(projectRoot: string, input: { runId: string; path: string; content: string; status: string; taskId?: string | null; agent?: string | null }): Promise<void> {
-  const contentHash = hashDocumentContent(input.content);
-  const now = new Date().toISOString();
-  const payload = JSON.stringify({ path: input.path, status: input.status, taskId: input.taskId ?? null, agent: input.agent ?? null });
-  await withRuntimeStore(projectRoot, ({ db }) => {
-    db.prepare('INSERT OR REPLACE INTO artifacts (artifact_id, run_id, path, kind, task_id, agent, content_hash, bytes, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
-      .run(runtimeScopedId(input.runId, input.path, contentHash), input.runId, input.path, artifactKind(input.path), input.taskId ?? null, input.agent ?? null, contentHash, Buffer.byteLength(input.content, 'utf8'), input.status, now, payload);
-  });
-}
-
-async function resolveRunScope(projectRoot: string, runId: string): Promise<{ branchSlug: string; taskId: string | null }> {
-  const state = await readRuntimeRunState(projectRoot, runId);
-  return {
-    branchSlug: state?.gitBranch ?? state?.partition ?? 'unscoped',
-    taskId: state?.taskId ?? state?.currentTask ?? null
-  };
-}
-
-function hashDocumentContent(raw: string): string {
-  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-}
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getEvidenceAttachmentPath, getLegacyArtifactPath, getRunRelativeArtifactPath, normalizeArtifactRootRelativePath } from '../runtime-paths.js';
+import { readRuntimeRunState, recordRuntimeArtifactPayload, recordRuntimeEvidenceAttachment, resolveRuntimeArtifactPayload, runtimeScopedId, withRuntimeStore } from '../storage/runtime-store.js';
+import { appendArtifactHashLedgerEntry } from './invocation-ledger.js';
+
+export async function writeArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string): Promise<{ absolutePath: string; runRelativePath: string }> {
+  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
+  const runRelativePath = getRunRelativeArtifactPath(normalized);
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const contentHash = hashDocumentContent(content);
+  const physicalPayloadPath = uniquePhysicalPayloadPath(runRelativePath, runId, contentHash);
+  const absolutePath = getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, physicalPayloadPath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, content, 'utf8');
+  await appendArtifactHashLedgerEntry(projectRoot, {
+    runId,
+    artifactPath: runRelativePath,
+    content,
+    status: 'written'
+  });
+  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'written', taskId: runScope.taskId });
+  await recordRuntimeArtifactPayload(projectRoot, {
+    payloadId: runtimeScopedId(runId, runRelativePath, contentHash),
+    runId,
+    sourceRunId: runId,
+    branchSlug: runScope.branchSlug,
+    taskId: runScope.taskId,
+    logicalRef: runRelativePath,
+    physicalPayloadPath,
+    artifactRole: artifactKind(runRelativePath),
+    digest: contentHash,
+    status: 'active',
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, artifactPath: runRelativePath, status: 'written' }
+  });
+  await recordRuntimeEvidenceAttachment(projectRoot, {
+    branchSlug: runScope.branchSlug,
+    runId,
+    taskId: runScope.taskId,
+    kind: artifactKind(runRelativePath),
+    relativePath: physicalPayloadPath,
+    contentHash,
+    bytes: Buffer.byteLength(content, 'utf8'),
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, status: 'written' }
+  });
+  return { absolutePath, runRelativePath };
+}
+
+export async function recordRuntimeOnlyArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string, _metadata: { logicalRef?: string; branch?: string; taskId?: string; artifactRole?: string } = {}): Promise<{ absolutePath: string; runRelativePath: string }> {
+  return writeArtifact(projectRoot, runId, artifactRootRelativePath, content);
+}
+
+export async function recordStageEvidenceArtifact(projectRoot: string, runId: string, stageEvidenceRef: string, content: string, _metadata: { taskId?: string; artifactRole?: string } = {}): Promise<{ absolutePath: string; runRelativePath: string }> {
+  return writeArtifact(projectRoot, runId, stageEvidenceRef, content);
+}
+
+export async function readArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string): Promise<string> {
+  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
+  const runRelativePath = getRunRelativeArtifactPath(normalized);
+  const payload = await resolveRuntimeArtifactPayload(projectRoot, runId, runRelativePath);
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const evidencePath = getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, payload?.physicalPayloadPath ?? runRelativePath);
+  if (payload) {
+    return readFile(evidencePath, 'utf8');
+  }
+  try {
+    return await readFile(evidencePath, 'utf8');
+  } catch {
+    return readFile(getLegacyArtifactPath(projectRoot, runId, normalized), 'utf8');
+  }
+}
+
+function uniquePhysicalPayloadPath(logicalRef: string, runId: string, digest: string): string {
+  const parsed = path.posix.parse(logicalRef.replace(/\\/g, '/'));
+  const suffix = `${runId}-${digest.slice(0, 12)}`;
+  return path.posix.join(parsed.dir, `${parsed.name}-${suffix}${parsed.ext}`);
+}
+
+export function artifactKind(artifactPath: string): string {
+  const fileName = path.posix.basename(artifactPath.replace(/\\/g, '/'));
+  if (fileName.startsWith('implement-')) {
+    return 'implement';
+  }
+  if (fileName.startsWith('review-')) {
+    return 'review';
+  }
+  if (fileName.startsWith('debug-')) {
+    return 'debug';
+  }
+  if (fileName.startsWith('test-validation-')) {
+    return 'test-validation';
+  }
+  if (fileName.startsWith('validation-')) {
+    return 'validation';
+  }
+  if (fileName.startsWith('gap-report-')) {
+    return 'gap-report';
+  }
+  if (fileName === 'sync-back-proposal.md') {
+    return 'sync-back-proposal';
+  }
+  return 'artifact';
+}
+
+async function recordRuntimeArtifact(projectRoot: string, input: { runId: string; path: string; content: string; status: string; taskId?: string | null; agent?: string | null }): Promise<void> {
+  const contentHash = hashDocumentContent(input.content);
+  const now = new Date().toISOString();
+  const payload = JSON.stringify({ path: input.path, status: input.status, taskId: input.taskId ?? null, agent: input.agent ?? null });
+  await withRuntimeStore(projectRoot, ({ db }) => {
+    db.prepare('INSERT OR REPLACE INTO artifacts (artifact_id, run_id, path, kind, task_id, agent, content_hash, bytes, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+      .run(runtimeScopedId(input.runId, input.path, contentHash), input.runId, input.path, artifactKind(input.path), input.taskId ?? null, input.agent ?? null, contentHash, Buffer.byteLength(input.content, 'utf8'), input.status, now, payload);
+  });
+}
+
+async function resolveRunScope(projectRoot: string, runId: string): Promise<{ branchSlug: string; taskId: string | null }> {
+  const state = await readRuntimeRunState(projectRoot, runId);
+  return {
+    branchSlug: state?.gitBranch ?? state?.partition ?? 'unscoped',
+    taskId: state?.taskId ?? state?.currentTask ?? null
+  };
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}

package/node_modules/@sdd-agent-platform/core/src/run-state/events.ts

@@ -1,27 +1,27 @@
-
-import path from 'node:path';
-import { EVENT_LOG_CONTRACT } from '../contracts.js';
-import { getLegacyRunDir } from '../runtime-paths.js';
-
-import { importLegacyRunEventsIfNeeded, readRuntimeRunEvents, recordRuntimeEvent } from '../storage/runtime-store.js';
-import type { RuntimeEvent } from './model.js';
-
-export async function appendEvent(projectRoot: string, runId: string, event: Omit<RuntimeEvent, 'contract' | 'time'>): Promise<RuntimeEvent> {
-  const nextEvent: RuntimeEvent = {
-    contract: EVENT_LOG_CONTRACT,
-    time: new Date().toISOString(),
-    ...event
-  };
-  await recordRuntimeEvent(projectRoot, nextEvent);
-  return nextEvent;
-}
-
-export async function readRunEvents(projectRoot: string, runId: string): Promise<RuntimeEvent[]> {
-  const storedEvents = await readRuntimeRunEvents(projectRoot, runId);
-  if (storedEvents.length > 0) {
-    return storedEvents;
-  }
-  const eventPath = path.join(getLegacyRunDir(projectRoot, runId), 'events.jsonl');
-  await importLegacyRunEventsIfNeeded(projectRoot, runId, eventPath);
-  return readRuntimeRunEvents(projectRoot, runId);
-}
+
+import path from 'node:path';
+import { EVENT_LOG_CONTRACT } from '../contracts.js';
+import { getLegacyRunDir } from '../runtime-paths.js';
+
+import { importLegacyRunEventsIfNeeded, readRuntimeRunEvents, recordRuntimeEvent } from '../storage/runtime-store.js';
+import type { RuntimeEvent } from './model.js';
+
+export async function appendEvent(projectRoot: string, runId: string, event: Omit<RuntimeEvent, 'contract' | 'time'>): Promise<RuntimeEvent> {
+  const nextEvent: RuntimeEvent = {
+    contract: EVENT_LOG_CONTRACT,
+    time: new Date().toISOString(),
+    ...event
+  };
+  await recordRuntimeEvent(projectRoot, nextEvent);
+  return nextEvent;
+}
+
+export async function readRunEvents(projectRoot: string, runId: string): Promise<RuntimeEvent[]> {
+  const storedEvents = await readRuntimeRunEvents(projectRoot, runId);
+  if (storedEvents.length > 0) {
+    return storedEvents;
+  }
+  const eventPath = path.join(getLegacyRunDir(projectRoot, runId), 'events.jsonl');
+  await importLegacyRunEventsIfNeeded(projectRoot, runId, eventPath);
+  return readRuntimeRunEvents(projectRoot, runId);
+}

package/node_modules/@sdd-agent-platform/core/src/run-state/inspect-run.ts

@@ -1,172 +1,172 @@
-import { TASK_RUN_EVIDENCE_CONTRACT_VERSION } from '../contracts.js';
-import { listAgentExecutionRecords as listRuntimeBackedAgentExecutionRecords, listTeamSessionRecords as listRuntimeBackedTeamSessionRecords } from '../execution/agent-execution-records.js';
-import { listResidentWorkerRuntimeRecords as listRuntimeBackedResidentWorkerRuntimeRecords } from '../execution/resident-worker.js';
-import type { ArtifactIndexEntry, InvocationLedgerEntry, RunState, RunStateArtifactIngestionRecord, RunStateWorktreeLifecycleRecord, RunStatus, RunSummary, RuntimeEvent } from './model.js';
-import { readRunEvents } from './events.js';
-import { listInvocationLedgerEntries } from './invocation-ledger.js';
-import { readRunState, summarizeRunState } from './run-state.js';
-import { readTaskEvidenceView, type TaskEvidenceView } from './task-evidence.js';
-
-export interface TaskRunEvidenceGap {
-  type: string;
-  severity: string;
-  taskId?: string | null;
-  field: string;
-  message: string;
-  recommendation: string;
-}
-
-export interface AgentExecutionRecordView {
-  executionId: string;
-  runId?: string;
-  taskId: string;
-  profile: string;
-  status: string;
-  artifacts: string[];
-  toolPermission: { profile?: string } | null;
-  routeId: string;
-  routeDecision: { recommendedProfile?: string | null };
-  createdAt: string;
-  [key: string]: unknown;
-}
-
-export interface TeamSessionRecordView {
-  teamId: string;
-  runId?: string;
-  taskId?: string | null;
-  status: string;
-  teamMode: { mode: string; activation: string; costClass: string; reason: string };
-  chiefProfile: string;
-  memberProfiles: string[];
-  artifacts: string[];
-  createdAt: string;
-  [key: string]: unknown;
-}
-
-export interface ResidentWorkerRuntimeRecordView {
-  runtimeId: string;
-  runId?: string;
-  taskId: string;
-  agent: string;
-  delegationId: string;
-  status: string;
-  leaseExpiresAt: string;
-  updatedAt: string;
-  [key: string]: unknown;
-}
-
-export interface TaskRunEvidenceContract {
-  version: typeof TASK_RUN_EVIDENCE_CONTRACT_VERSION;
-  runId: string;
-  state: { status: RunStatus; phase: string | null; currentTask: string | null };
-  events: Array<{ event: string; summary: string | null; task: string | null; agent: string | null; gate: string | null; validation: string | null; gap: string | null }>;
-  artifacts: ArtifactIndexEntry[];
-  validation: RunState['validation'];
-  gaps: TaskRunEvidenceGap[];
-  syncBackProposal: string | null;
-  invocationLedger: InvocationLedgerEntry[];
-  agentExecutions: AgentExecutionRecordView[];
-  teamSessions: TeamSessionRecordView[];
-  workerRuntimes: ResidentWorkerRuntimeRecordView[];
-}
-
-export interface RunInspection {
-  summary: RunSummary;
-  state: RunState;
-  events: RuntimeEvent[];
-  eventCount: number;
-  recentEvents: RuntimeEvent[];
-  artifacts: ArtifactIndexEntry[];
-  artifactIngestions: RunStateArtifactIngestionRecord[];
-  worktrees: RunStateWorktreeLifecycleRecord[];
-  validation: RunState['validation'];
-  syncBack: RunState['syncBack'];
-  tasks: Record<string, unknown>;
-  taskRunEvidence: TaskRunEvidenceContract;
-  taskEvidenceView: TaskEvidenceView | null;
-  agentExecutions: AgentExecutionRecordView[];
-  invocationLedger: InvocationLedgerEntry[];
-  teamSessions: TeamSessionRecordView[];
-  workerRuntimes: ResidentWorkerRuntimeRecordView[];
-}
-
-export async function inspectRun(projectRoot: string, runId: string): Promise<RunInspection> {
-  const state = await readRunState(projectRoot, runId);
-  const [events, agentExecutions, teamSessions, workerRuntimes, invocationLedger] = await Promise.all([
-    readRunEvents(projectRoot, runId),
-    listRuntimeBackedAgentExecutionRecords(projectRoot, runId),
-    listRuntimeBackedTeamSessionRecords(projectRoot, runId),
-    listRuntimeBackedResidentWorkerRuntimeRecords(projectRoot, runId),
-    listInvocationLedgerEntries(projectRoot, runId)
-  ]);
-  const agentExecutionViews = agentExecutions.map((record) => ({ ...record }) as AgentExecutionRecordView);
-  const teamSessionViews = teamSessions.map((record) => ({ ...record }) as TeamSessionRecordView);
-  const workerRuntimeViews = workerRuntimes.map((record) => ({ ...record }) as ResidentWorkerRuntimeRecordView);
-  const taskEvidenceView = state.partition && state.taskId ? await readTaskEvidenceView(projectRoot, { branch: state.partition, taskId: state.taskId }) : null;
-  return {
-    summary: summarizeRunState(state),
-    state,
-    events,
-    eventCount: events.length,
-    recentEvents: events.slice(-10),
-    artifacts: state.artifacts,
-    artifactIngestions: Object.values(state.artifactIngestions ?? {}),
-    worktrees: Object.values(state.worktrees ?? {}),
-    validation: state.validation,
-    syncBack: state.syncBack,
-    taskRunEvidence: buildTaskRunEvidence(state, events, agentExecutionViews, teamSessionViews, workerRuntimeViews, invocationLedger),
-    taskEvidenceView,
-    tasks: state.tasks,
-    agentExecutions: agentExecutionViews,
-    teamSessions: teamSessionViews,
-    workerRuntimes: workerRuntimeViews,
-    invocationLedger
-  };
-}
-
-
-function buildTaskRunEvidence(state: RunState, events: RuntimeEvent[], agentExecutions: AgentExecutionRecordView[] = [], teamSessions: TeamSessionRecordView[] = [], workerRuntimes: ResidentWorkerRuntimeRecordView[] = [], invocationLedger: InvocationLedgerEntry[] = []): TaskRunEvidenceContract {
-  return {
-    version: TASK_RUN_EVIDENCE_CONTRACT_VERSION,
-    runId: state.runId,
-    state: { status: state.status, phase: state.phase, currentTask: state.currentTask },
-    events: events.map((event) => ({
-      event: event.event,
-      summary: event.summary ?? null,
-      task: stringData(event.data, 'task'),
-      agent: stringData(event.data, 'agent'),
-      gate: stringData(event.data, 'gate'),
-      validation: stringData(event.data, 'status') ?? stringData(event.data, 'validation'),
-      gap: stringData(event.data, 'gap')
-    })),
-    artifacts: state.artifacts,
-    validation: state.validation,
-    gaps: Object.values(state.tasks).flatMap(extractTaskGaps),
-    syncBackProposal: state.syncBack.proposalPath,
-    agentExecutions,
-    teamSessions,
-    workerRuntimes,
-    invocationLedger
-  };
-}
-
-function stringData(data: Record<string, unknown> | undefined, key: string): string | null {
-  const value = data?.[key];
-  return typeof value === 'string' ? value : null;
-}
-
-function extractTaskGaps(taskState: unknown): TaskRunEvidenceGap[] {
-  if (!taskState || typeof taskState !== 'object' || !('gaps' in taskState)) {
-    return [];
-  }
-  const gaps = (taskState as { gaps?: unknown }).gaps;
-  return Array.isArray(gaps) ? gaps.filter(isTaskRunEvidenceGap) : [];
-}
-
-function isTaskRunEvidenceGap(value: unknown): value is TaskRunEvidenceGap {
-  if (!value || typeof value !== 'object') {
-    return false;
-  }
-  const gap = value as Partial<TaskRunEvidenceGap>;
-  return typeof gap.type === 'string' && typeof gap.severity === 'string' && typeof gap.field === 'string' && typeof gap.message === 'string' && typeof gap.recommendation === 'string';
-}
+import { TASK_RUN_EVIDENCE_CONTRACT_VERSION } from '../contracts.js';
+import { listAgentExecutionRecords as listRuntimeBackedAgentExecutionRecords, listTeamSessionRecords as listRuntimeBackedTeamSessionRecords } from '../execution/agent-execution-records.js';
+import { listResidentWorkerRuntimeRecords as listRuntimeBackedResidentWorkerRuntimeRecords } from '../execution/resident-worker.js';
+import type { ArtifactIndexEntry, InvocationLedgerEntry, RunState, RunStateArtifactIngestionRecord, RunStateWorktreeLifecycleRecord, RunStatus, RunSummary, RuntimeEvent } from './model.js';
+import { readRunEvents } from './events.js';
+import { listInvocationLedgerEntries } from './invocation-ledger.js';
+import { readRunState, summarizeRunState } from './run-state.js';
+import { readTaskEvidenceView, type TaskEvidenceView } from './task-evidence.js';
+
+export interface TaskRunEvidenceGap {
+  type: string;
+  severity: string;
+  taskId?: string | null;
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface AgentExecutionRecordView {
+  executionId: string;
+  runId?: string;
+  taskId: string;
+  profile: string;
+  status: string;
+  artifacts: string[];
+  toolPermission: { profile?: string } | null;
+  routeId: string;
+  routeDecision: { recommendedProfile?: string | null };
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+export interface TeamSessionRecordView {
+  teamId: string;
+  runId?: string;
+  taskId?: string | null;
+  status: string;
+  teamMode: { mode: string; activation: string; costClass: string; reason: string };
+  chiefProfile: string;
+  memberProfiles: string[];
+  artifacts: string[];
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+export interface ResidentWorkerRuntimeRecordView {
+  runtimeId: string;
+  runId?: string;
+  taskId: string;
+  agent: string;
+  delegationId: string;
+  status: string;
+  leaseExpiresAt: string;
+  updatedAt: string;
+  [key: string]: unknown;
+}
+
+export interface TaskRunEvidenceContract {
+  version: typeof TASK_RUN_EVIDENCE_CONTRACT_VERSION;
+  runId: string;
+  state: { status: RunStatus; phase: string | null; currentTask: string | null };
+  events: Array<{ event: string; summary: string | null; task: string | null; agent: string | null; gate: string | null; validation: string | null; gap: string | null }>;
+  artifacts: ArtifactIndexEntry[];
+  validation: RunState['validation'];
+  gaps: TaskRunEvidenceGap[];
+  syncBackProposal: string | null;
+  invocationLedger: InvocationLedgerEntry[];
+  agentExecutions: AgentExecutionRecordView[];
+  teamSessions: TeamSessionRecordView[];
+  workerRuntimes: ResidentWorkerRuntimeRecordView[];
+}
+
+export interface RunInspection {
+  summary: RunSummary;
+  state: RunState;
+  events: RuntimeEvent[];
+  eventCount: number;
+  recentEvents: RuntimeEvent[];
+  artifacts: ArtifactIndexEntry[];
+  artifactIngestions: RunStateArtifactIngestionRecord[];
+  worktrees: RunStateWorktreeLifecycleRecord[];
+  validation: RunState['validation'];
+  syncBack: RunState['syncBack'];
+  tasks: Record<string, unknown>;
+  taskRunEvidence: TaskRunEvidenceContract;
+  taskEvidenceView: TaskEvidenceView | null;
+  agentExecutions: AgentExecutionRecordView[];
+  invocationLedger: InvocationLedgerEntry[];
+  teamSessions: TeamSessionRecordView[];
+  workerRuntimes: ResidentWorkerRuntimeRecordView[];
+}
+
+export async function inspectRun(projectRoot: string, runId: string): Promise<RunInspection> {
+  const state = await readRunState(projectRoot, runId);
+  const [events, agentExecutions, teamSessions, workerRuntimes, invocationLedger] = await Promise.all([
+    readRunEvents(projectRoot, runId),
+    listRuntimeBackedAgentExecutionRecords(projectRoot, runId),
+    listRuntimeBackedTeamSessionRecords(projectRoot, runId),
+    listRuntimeBackedResidentWorkerRuntimeRecords(projectRoot, runId),
+    listInvocationLedgerEntries(projectRoot, runId)
+  ]);
+  const agentExecutionViews = agentExecutions.map((record) => ({ ...record }) as AgentExecutionRecordView);
+  const teamSessionViews = teamSessions.map((record) => ({ ...record }) as TeamSessionRecordView);
+  const workerRuntimeViews = workerRuntimes.map((record) => ({ ...record }) as ResidentWorkerRuntimeRecordView);
+  const taskEvidenceView = state.partition && state.taskId ? await readTaskEvidenceView(projectRoot, { branch: state.partition, taskId: state.taskId }) : null;
+  return {
+    summary: summarizeRunState(state),
+    state,
+    events,
+    eventCount: events.length,
+    recentEvents: events.slice(-10),
+    artifacts: state.artifacts,
+    artifactIngestions: Object.values(state.artifactIngestions ?? {}),
+    worktrees: Object.values(state.worktrees ?? {}),
+    validation: state.validation,
+    syncBack: state.syncBack,
+    taskRunEvidence: buildTaskRunEvidence(state, events, agentExecutionViews, teamSessionViews, workerRuntimeViews, invocationLedger),
+    taskEvidenceView,
+    tasks: state.tasks,
+    agentExecutions: agentExecutionViews,
+    teamSessions: teamSessionViews,
+    workerRuntimes: workerRuntimeViews,
+    invocationLedger
+  };
+}
+
+
+function buildTaskRunEvidence(state: RunState, events: RuntimeEvent[], agentExecutions: AgentExecutionRecordView[] = [], teamSessions: TeamSessionRecordView[] = [], workerRuntimes: ResidentWorkerRuntimeRecordView[] = [], invocationLedger: InvocationLedgerEntry[] = []): TaskRunEvidenceContract {
+  return {
+    version: TASK_RUN_EVIDENCE_CONTRACT_VERSION,
+    runId: state.runId,
+    state: { status: state.status, phase: state.phase, currentTask: state.currentTask },
+    events: events.map((event) => ({
+      event: event.event,
+      summary: event.summary ?? null,
+      task: stringData(event.data, 'task'),
+      agent: stringData(event.data, 'agent'),
+      gate: stringData(event.data, 'gate'),
+      validation: stringData(event.data, 'status') ?? stringData(event.data, 'validation'),
+      gap: stringData(event.data, 'gap')
+    })),
+    artifacts: state.artifacts,
+    validation: state.validation,
+    gaps: Object.values(state.tasks).flatMap(extractTaskGaps),
+    syncBackProposal: state.syncBack.proposalPath,
+    agentExecutions,
+    teamSessions,
+    workerRuntimes,
+    invocationLedger
+  };
+}
+
+function stringData(data: Record<string, unknown> | undefined, key: string): string | null {
+  const value = data?.[key];
+  return typeof value === 'string' ? value : null;
+}
+
+function extractTaskGaps(taskState: unknown): TaskRunEvidenceGap[] {
+  if (!taskState || typeof taskState !== 'object' || !('gaps' in taskState)) {
+    return [];
+  }
+  const gaps = (taskState as { gaps?: unknown }).gaps;
+  return Array.isArray(gaps) ? gaps.filter(isTaskRunEvidenceGap) : [];
+}
+
+function isTaskRunEvidenceGap(value: unknown): value is TaskRunEvidenceGap {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const gap = value as Partial<TaskRunEvidenceGap>;
+  return typeof gap.type === 'string' && typeof gap.severity === 'string' && typeof gap.field === 'string' && typeof gap.message === 'string' && typeof gap.recommendation === 'string';
+}