sdd-agent-platform 0.3.0 → 0.4.1

package/packages/core/dist/run-state/inspect-run.d.ts

@@ -0,0 +1,102 @@
+import { TASK_RUN_EVIDENCE_CONTRACT_VERSION } from '../contracts.js';
+import type { ArtifactIndexEntry, InvocationLedgerEntry, RunState, RunStateArtifactIngestionRecord, RunStateWorktreeLifecycleRecord, RunStatus, RunSummary, RuntimeEvent } from './model.js';
+import { 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 declare function inspectRun(projectRoot: string, runId: string): Promise<RunInspection>;

package/packages/core/dist/run-state/inspect-run.js

@@ -0,0 +1,83 @@
+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 { readRunEvents } from './events.js';
+import { listInvocationLedgerEntries } from './invocation-ledger.js';
+import { readRunState, summarizeRunState } from './run-state.js';
+import { readTaskEvidenceView } from './task-evidence.js';
+export async function inspectRun(projectRoot, runId) {
+    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 }));
+    const teamSessionViews = teamSessions.map((record) => ({ ...record }));
+    const workerRuntimeViews = workerRuntimes.map((record) => ({ ...record }));
+    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, events, agentExecutions = [], teamSessions = [], workerRuntimes = [], invocationLedger = []) {
+    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, key) {
+    const value = data?.[key];
+    return typeof value === 'string' ? value : null;
+}
+function extractTaskGaps(taskState) {
+    if (!taskState || typeof taskState !== 'object' || !('gaps' in taskState)) {
+        return [];
+    }
+    const gaps = taskState.gaps;
+    return Array.isArray(gaps) ? gaps.filter(isTaskRunEvidenceGap) : [];
+}
+function isTaskRunEvidenceGap(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const gap = value;
+    return typeof gap.type === 'string' && typeof gap.severity === 'string' && typeof gap.field === 'string' && typeof gap.message === 'string' && typeof gap.recommendation === 'string';
+}
+//# sourceMappingURL=inspect-run.js.map

package/packages/core/dist/run-state/inspect-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-run.js","sourceRoot":"","sources":["../../src/run-state/inspect-run.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/run-state/invocation-ledger.d.ts

@@ -0,0 +1,18 @@
+import type { InvocationLedgerEntry } from './model.js';
+export declare function appendInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry>;
+export declare function listInvocationLedgerEntries(projectRoot: string, runId: string): Promise<InvocationLedgerEntry[]>;
+export declare function appendArtifactHashLedgerEntry(projectRoot: string, input: {
+    runId: string;
+    taskId?: string | null;
+    branch?: string | null;
+    artifactPath: string;
+    content: string;
+    status?: string;
+}): Promise<InvocationLedgerEntry>;
+export declare function appendUniqueInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry>;
+export declare function appendDeclaredCommandLedgerEntries(projectRoot: string, input: {
+    runId: string;
+    taskId: string;
+    branch: string;
+    commands: string[];
+}): Promise<void>;

package/packages/core/dist/run-state/invocation-ledger.js

@@ -0,0 +1,99 @@
+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';
+export async function appendInvocationLedgerEntry(projectRoot, input) {
+    const timestamp = new Date().toISOString();
+    const entry = {
+        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, runId) {
+    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, input) {
+    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, input) {
+    const existing = await findMatchingInvocationLedgerEntry(projectRoot, input);
+    if (existing) {
+        return existing;
+    }
+    return appendInvocationLedgerEntry(projectRoot, input);
+}
+export async function appendDeclaredCommandLedgerEntries(projectRoot, input) {
+    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, runId, ledgerPath) {
+    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');
+            if (legacy?.content_hash === contentHash) {
+                return;
+            }
+            for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+                const entry = JSON.parse(line);
+                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, input) {
+    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) {
+    return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}
+function messageFromError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=invocation-ledger.js.map

package/packages/core/dist/run-state/invocation-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-ledger.js","sourceRoot":"","sources":["../../src/run-state/invocation-ledger.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/run-state/model.d.ts

@@ -0,0 +1,203 @@
+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/packages/core/dist/run-state/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map

package/packages/core/dist/run-state/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/run-state/model.ts"],"names":[],"mappings":""}

package/packages/core/dist/run-state/run-index.d.ts

@@ -0,0 +1,97 @@
+import { LOCAL_RUN_INDEX_CONTRACT_VERSION } from '../contracts.js';
+import type { RunState, RunStateDelegationRecord, RunStatus, RunSummary } from './model.js';
+export interface ContractValidationIssue {
+    field: string;
+    message: string;
+    recommendation: string;
+}
+export type DelegationQueueStatusSource = 'run_state_delegation';
+export interface DelegationQueueItem {
+    id: string;
+    runId: string;
+    delegationId: string;
+    taskId: string;
+    agent: string;
+    requestedCapabilityId: string;
+    dedupeKey: string;
+    status: RunStateDelegationRecord['status'];
+    statusSource: DelegationQueueStatusSource;
+    runMode: RunStateDelegationRecord['runMode'];
+    expectedArtifact: string;
+    requiredEvidence: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LocalRunIndexTaskEntry {
+    taskId: string;
+    partition: string | null;
+    gitBranch: string | null;
+    affectedFiles: string[];
+    status: string | null;
+    runId: string;
+    runStatus: RunStatus;
+    updatedAt: string;
+}
+export interface LocalRunIndexArtifactEntry {
+    path: string;
+    kind: string;
+    task: string | null;
+    agent: string | null;
+    runId: string;
+    createdAt: string;
+}
+export interface LocalRunIndexWaveSummary {
+    runId: string;
+    eventCount: number;
+    lastEvent: string | null;
+}
+export interface LocalRunIndexPartitionTaskEntry {
+    partition: string;
+    gitBranch: string | null;
+    taskId: string;
+    runId: string;
+    runStatus: RunStatus;
+    validationStatus: RunState['validation']['status'];
+    syncBackStatus: RunState['syncBack']['status'];
+    affectedFiles: string[];
+    updatedAt: string;
+}
+export interface LocalRunIndexAffectedFileEntry {
+    file: string;
+    partition: string;
+    gitBranch: string | null;
+    taskId: string;
+    runId: string;
+    runStatus: RunStatus;
+    syncBackStatus: RunState['syncBack']['status'];
+    updatedAt: string;
+}
+export interface LocalRunIndexQuery {
+    runId?: string;
+    taskId?: string;
+    partition?: string;
+    status?: RunStatus;
+    artifact?: string;
+}
+export interface LocalRunIndex {
+    contract: typeof LOCAL_RUN_INDEX_CONTRACT_VERSION;
+    generatedAt: string;
+    runs: RunSummary[];
+    tasks: LocalRunIndexTaskEntry[];
+    delegations: DelegationQueueItem[];
+    artifacts: LocalRunIndexArtifactEntry[];
+    waves: LocalRunIndexWaveSummary[];
+    latestByPartitionTask: LocalRunIndexPartitionTaskEntry[];
+    activeByAffectedFile: LocalRunIndexAffectedFileEntry[];
+}
+export interface LocalRunIndexInspection {
+    valid: boolean;
+    exists: boolean;
+    indexPath: string;
+    index: LocalRunIndex | null;
+    issues: ContractValidationIssue[];
+}
+export declare function rebuildLocalRunIndex(projectRoot: string): Promise<LocalRunIndex>;
+export declare function readLocalRunIndex(projectRoot: string): Promise<LocalRunIndex>;
+export declare function queryLocalRunIndex(projectRoot: string, query?: LocalRunIndexQuery): Promise<LocalRunIndex>;
+export declare function inspectLocalRunIndex(projectRoot: string): Promise<LocalRunIndexInspection>;