sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +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';
+}

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

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { INVOCATION_LEDGER_CONTRACT_VERSION } from '../contracts.js';
+import { getLegacyInvocationLedgerPath } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { RuntimeStoreError, legacyImportId, readRuntimeActivities, recordLegacyImportFailure, recordRuntimeActivity, withRuntimeStore } from '../storage/runtime-store.js';
+import type { InvocationLedgerEntry } from './model.js';
+
+export async function appendInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry> {
+  const timestamp = new Date().toISOString();
+  const entry: InvocationLedgerEntry = {
+    contract: 'sdd-invocation-ledger-v1',
+    version: INVOCATION_LEDGER_CONTRACT_VERSION,
+    entryId: createHash('sha256').update(`${input.runId}:${input.kind}:${input.ref}:${timestamp}`).digest('hex').slice(0, 16),
+    timestamp,
+    ...input
+  };
+  await recordRuntimeActivity(projectRoot, entry);
+  return entry;
+}
+
+export async function listInvocationLedgerEntries(projectRoot: string, runId: string): Promise<InvocationLedgerEntry[]> {
+  const entries = await readRuntimeActivities(projectRoot, runId);
+  if (entries.length > 0) {
+    return entries;
+  }
+  const ledgerPath = getLegacyInvocationLedgerPath(projectRoot, runId);
+  await importLegacyInvocationLedgerIfNeeded(projectRoot, runId, ledgerPath);
+  return readRuntimeActivities(projectRoot, runId);
+}
+
+export async function appendArtifactHashLedgerEntry(projectRoot: string, input: { runId: string; taskId?: string | null; branch?: string | null; artifactPath: string; content: string; status?: string }): Promise<InvocationLedgerEntry> {
+  return appendUniqueInvocationLedgerEntry(projectRoot, {
+    runId: input.runId,
+    taskId: input.taskId ?? null,
+    branch: input.branch ?? null,
+    kind: 'artifact_hash',
+    ref: input.artifactPath,
+    status: input.status ?? 'observed',
+    artifactPath: input.artifactPath,
+    outputHash: hashDocumentContent(input.content),
+    materialRefs: [],
+    metadata: { bytes: Buffer.byteLength(input.content, 'utf8') }
+  });
+}
+
+export async function appendUniqueInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry> {
+  const existing = await findMatchingInvocationLedgerEntry(projectRoot, input);
+  if (existing) {
+    return existing;
+  }
+  return appendInvocationLedgerEntry(projectRoot, input);
+}
+
+export async function appendDeclaredCommandLedgerEntries(projectRoot: string, input: { runId: string; taskId: string; branch: string; commands: string[] }): Promise<void> {
+  for (const command of input.commands) {
+    await appendUniqueInvocationLedgerEntry(projectRoot, {
+      runId: input.runId,
+      taskId: input.taskId,
+      branch: input.branch,
+      kind: 'command',
+      ref: command,
+      status: 'declared',
+      materialRefs: [],
+      metadata: { source: 'task.validation' }
+    });
+  }
+}
+
+async function importLegacyInvocationLedgerIfNeeded(projectRoot: string, runId: string, ledgerPath: string): Promise<void> {
+  if (!await exists(ledgerPath)) {
+    return;
+  }
+  try {
+    const raw = await readFile(ledgerPath, 'utf8');
+    const contentHash = hashDocumentContent(raw);
+    await withRuntimeStore(projectRoot, ({ db }) => {
+      const legacy = db.prepare('SELECT content_hash FROM legacy_imports WHERE run_id = ? AND entity_type = ?').get(runId, 'invocations') as { content_hash?: string } | undefined;
+      if (legacy?.content_hash === contentHash) {
+        return;
+      }
+      for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+        const entry = JSON.parse(line) as InvocationLedgerEntry;
+        db.prepare('INSERT OR REPLACE INTO activities (activity_id, run_id, task_id, branch, kind, ref, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
+          .run(entry.entryId, entry.runId, entry.taskId ?? null, entry.branch ?? null, entry.kind, entry.ref, entry.status ?? null, entry.timestamp, JSON.stringify(entry));
+      }
+      db.prepare('INSERT OR REPLACE INTO legacy_imports (import_id, run_id, entity_type, content_hash, imported_at, status, issue) VALUES (?, ?, ?, ?, ?, ?, ?)')
+        .run(legacyImportId(runId, 'invocations'), runId, 'invocations', contentHash, new Date().toISOString(), 'imported', null);
+    });
+  } catch (error) {
+    await recordLegacyImportFailure(projectRoot, runId, 'invocations', error);
+    throw new RuntimeStoreError('LEGACY_IMPORT_FAILED', `Cannot import legacy invocation ledger for ${runId}: ${messageFromError(error)}`, { cause: error });
+  }
+}
+
+async function findMatchingInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry | null> {
+  const entries = await listInvocationLedgerEntries(projectRoot, input.runId);
+  return entries.find((entry) => entry.kind === input.kind && entry.ref === input.ref && entry.status === input.status && entry.outputHash === input.outputHash) ?? null;
+}
+
+
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}
+
+function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,231 @@
+import type {
+  ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION,
+  DELEGATION_LIVENESS_CONTRACT,
+  DELEGATION_LIVENESS_VERSION,
+  EVENT_LOG_CONTRACT,
+  INVOCATION_LEDGER_CONTRACT_VERSION,
+  LEGACY_LIFECYCLE_DECISION_CONTRACT,
+  LIFECYCLE_DECISION_CONTRACT,
+  LIFECYCLE_DECISION_VERSION,
+  RUN_STATE_CONTRACT,
+  RUNTIME_VERSION
+} from '../contracts.js';
+
+export type RunStatus = 'created' | 'running' | 'completed' | 'blocked' | 'failed' | 'archived';
+
+export interface ArtifactIndexEntry {
+  path: string;
+  kind: string;
+  task: string | null;
+  agent: string | null;
+  createdAt: string;
+}
+
+export interface RunDocumentSnapshot {
+  specHash: string | null;
+  planHash: string | null;
+  tasksHash: string | null;
+  specContractHash: string | null;
+  planContractHash: string | null;
+  tasksContractHash: string | null;
+  planBasedOnSpecHash: string | null;
+  tasksBasedOnPlanHash: string | null;
+  planBasedOnSpecContractHash: string | null;
+  tasksBasedOnPlanContractHash: string | null;
+}
+
+export interface RunStateContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface RunStateTaskGap {
+  type: 'Document Gap' | 'Task Gap' | 'Dependency Gap';
+  severity: 'blocking' | 'warning';
+  taskId: string | null;
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface RunStateLifecycleDecisionRecord {
+  contract: typeof LIFECYCLE_DECISION_CONTRACT | typeof LEGACY_LIFECYCLE_DECISION_CONTRACT;
+  version?: typeof LIFECYCLE_DECISION_VERSION;
+  model_version: string;
+  input_summary: Record<string, unknown>;
+  decision: {
+    profile: string | null;
+    confidence: string | null;
+    hard_gate_hits: string[];
+    required_stages: string[];
+    skipped_stages: string[];
+    human_checkpoint_required: boolean;
+  };
+  reasons: string[];
+  escalation_triggers: string[];
+  downgrade_reason: string | null;
+  audit: {
+    decided_at: string | null;
+    decided_by: string | null;
+    policy_version: string;
+    source_artifacts: string[];
+  };
+}
+
+export interface RunStateDelegationRecord {
+  contract: typeof DELEGATION_LIVENESS_CONTRACT;
+  version: typeof DELEGATION_LIVENESS_VERSION;
+  delegationId: string;
+  task: string;
+  agent: string;
+  runMode: 'foreground' | 'background';
+  blocking: boolean;
+  requiredForPhaseExit: boolean;
+  status: 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'RECOVERABLE' | 'STALE';
+  startedAt: string;
+  lastHeartbeatAt: string | null;
+  timeoutSeconds: number;
+  expectedArtifact: string;
+  terminalEventRequired: boolean;
+  terminalEventAt?: string | null;
+}
+
+export interface RunStateArtifactIngestionRecord {
+  contract: typeof ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION;
+  runId: string;
+  delegationId: string;
+  task: string;
+  agent: string;
+  artifactPath: string;
+  status: 'accepted' | 'rejected';
+  resultStatus: 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'TIMED_OUT' | 'CANCELLED' | null;
+  delegationStatus: RunStateDelegationRecord['status'] | null;
+  ingestedAt: string;
+  issues: RunStateContractValidationIssue[];
+  gaps: RunStateTaskGap[];
+}
+
+export interface RunStateWorktreeLifecycleRecord {
+  contract: 'phase-3.8-worktree-lifecycle-v1';
+  runId: string;
+  taskId: string;
+  worktreeId: string;
+  status: 'created' | 'kept' | 'removed';
+  branchName: string;
+  worktreePath: string;
+  baseRef: string;
+  createdAt: string;
+  updatedAt: string;
+  removedAt: string | null;
+  keepReason: string | null;
+  dirty: boolean;
+}
+
+export type RunTaskImplementationStatus = 'not_started' | 'running' | 'implemented' | 'blocked' | 'failed';
+
+export type RunTaskVerificationStatus = 'not_run' | 'pending_batch' | 'ready_for_validation' | 'running' | 'pass' | 'pass_with_gaps' | 'blocked' | 'failed';
+
+export interface RunStateTaskRuntime {
+  status: string;
+  implementationStatus?: RunTaskImplementationStatus;
+  verificationStatus?: RunTaskVerificationStatus;
+  validationBatch?: string | null;
+  validationTiming?: 'task_end' | 'batch_end' | 'wave_end';
+  requiresVerifyBeforeNext?: boolean;
+  gaps?: unknown[];
+  artifacts?: string[];
+  testStatus?: string;
+  validationStatus?: string;
+  verifyStatus?: string;
+  workflowGateStatus?: string;
+  workflowGateDecisionId?: string;
+  evidence?: string[];
+  acceptanceCoverage?: unknown[];
+}
+
+export interface RunState {
+  contract: typeof RUN_STATE_CONTRACT;
+  runtimeVersion: typeof RUNTIME_VERSION;
+  runId: string;
+  status: RunStatus;
+  phase: string | null;
+  currentTask: string | null;
+  partition: string | null;
+  gitBranch: string | null;
+  taskId: string | null;
+  affectedFiles: string[];
+  documentSnapshot: RunDocumentSnapshot;
+  createdAt: string;
+  updatedAt: string;
+  projectRoot: string;
+  projectConfigPath: string;
+  eventLogPath: string;
+  artifactRoot: string;
+  lifecycleDecision: RunStateLifecycleDecisionRecord | null;
+  tasks: Record<string, RunStateTaskRuntime>;
+  agents: Record<string, unknown>;
+  delegations: Record<string, RunStateDelegationRecord>;
+  artifacts: ArtifactIndexEntry[];
+  artifactIngestions: Record<string, RunStateArtifactIngestionRecord>;
+  worktrees: Record<string, RunStateWorktreeLifecycleRecord>;
+  validation: {
+    status: 'not_run' | 'pass' | 'pass_with_gaps' | 'fail' | 'blocked';
+    commands: string[];
+    evidence: string[];
+  };
+  syncBack: {
+    mode: 'proposal';
+    proposalPath: string | null;
+    proposalDigest?: string | null;
+    sourceVerifyStatus?: 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'completed' | 'blocked' | 'failed' | null;
+    status: 'not_created' | 'proposed' | 'applied';
+  };
+}
+
+export interface RunSummary {
+  runId: string;
+  status: RunStatus;
+  phase: string | null;
+  currentTask: string | null;
+  partition: string | null;
+  gitBranch: string | null;
+  taskId: string | null;
+  affectedFiles: string[];
+  documentSnapshot: RunDocumentSnapshot;
+  createdAt: string;
+  updatedAt: string;
+  validationStatus: RunState['validation']['status'];
+  syncBackStatus: RunState['syncBack']['status'];
+  taskIds: string[];
+  artifactCount: number;
+}
+
+export interface RuntimeEvent {
+  contract: typeof EVENT_LOG_CONTRACT;
+  time: string;
+  event: string;
+  runId: string;
+  summary?: string;
+  data?: Record<string, unknown>;
+}
+
+export type InvocationLedgerKind = 'command' | 'tool_invocation' | 'agent' | 'skill' | 'material' | 'policy_evaluation' | 'cache' | 'artifact_hash';
+
+export interface InvocationLedgerEntry {
+  contract: 'sdd-invocation-ledger-v1';
+  version: typeof INVOCATION_LEDGER_CONTRACT_VERSION;
+  entryId: string;
+  runId: string;
+  taskId: string | null;
+  branch: string | null;
+  kind: InvocationLedgerKind;
+  ref: string;
+  status: string;
+  timestamp: string;
+  artifactPath?: string | null;
+  inputHash?: string | null;
+  outputHash?: string | null;
+  materialRefs: string[];
+  metadata: Record<string, string | number | boolean | null>;
+}

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

@@ -0,0 +1,52 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { createDelegationRecord } from '../delegation/validation.js';
+import { validResultArtifact } from '../test-support/fixtures.js';
+import { writeArtifact } from './artifacts.js';
+import { appendEvent } from './events.js';
+import { createRun, writeRunState } from './run-state.js';
+import { inspectLocalRunIndex, queryLocalRunIndex, rebuildLocalRunIndex } from './run-index.js';
+
+test('local run index rebuilds and queries derived run evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-local-run-index-'));
+  try {
+    await initProject(root);
+    const run = await createRun(root, { runId: 'run-index' });
+    const delegation = createDelegationRecord({
+      delegationId: 'D-T1-implementer-001',
+      task: 'T1',
+      agent: 'implementer',
+      expectedArtifact: 'artifacts/implementer-T1.md'
+    });
+    await writeArtifact(root, run.runId, 'implementer-T1.md', validResultArtifact('implementer', 'T1', 'PASS', 'artifacts/implementer-T1.md'));
+    await writeRunState(root, {
+      ...run,
+      status: 'completed',
+      currentTask: 'T1',
+      tasks: { T1: { status: 'completed' } },
+      delegations: { [delegation.delegationId]: { ...delegation, status: 'COMPLETED', terminalEventAt: '2026-05-07T00:00:00.000Z' } },
+      artifacts: [{ path: 'artifacts/implementer-T1.md', kind: 'sdd-result', task: 'T1', agent: 'implementer', createdAt: '2026-05-07T00:00:00.000Z' }]
+    });
+    await appendEvent(root, run.runId, { event: 'wave_executor_started', runId: run.runId });
+
+    const index = await rebuildLocalRunIndex(root);
+    const queried = await queryLocalRunIndex(root, { taskId: 'T1', status: 'completed', artifact: 'artifacts/implementer-T1.md' });
+    const inspection = await inspectLocalRunIndex(root);
+
+    assert.equal(index.contract, 'phase-3.13-local-run-index-v1');
+    assert.deepEqual(index.runs.map((entry) => entry.runId), ['run-index']);
+    assert.deepEqual(index.tasks.map((entry) => `${entry.runId}:${entry.taskId}:${entry.status}`), ['run-index:T1:completed']);
+    assert.equal(index.delegations.length, 1);
+    assert.equal(index.artifacts[0]?.path, 'artifacts/implementer-T1.md');
+    assert.equal(index.waves[0]?.lastEvent, 'wave_executor_started');
+    assert.deepEqual(queried.runs.map((entry) => entry.runId), ['run-index']);
+    assert.equal(inspection.valid, true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});