@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/diagnostics/mcp-timing.ts

@@ -1,3 +1,4 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from 'fs';
 import { appendFile, mkdir, rename, rm, stat } from 'fs/promises';
 import { join, resolve } from 'path';
 
@@ -35,12 +36,28 @@ export interface McpTimingTrace {
   gatewayProxyConnectionState?: 'reused' | 'cold_connect' | 'coalesced_connect' | 'identity_reconnect';
   totalToolDurationMs: number;
   sessionId?: string;
+  /** Request-scoped ChatGPT conversation correlation from MCP host metadata; diagnostic only, never semantic authority. */
+  hostConversationSessionId?: string;
   repoId?: string;
   workId?: string;
   processId?: string;
   route?: string;
 }
 
+
+export type McpTransportEventKind = 'interruption' | 'session_initialized';
+
+export interface McpTransportEvent {
+  schemaVersion: 1;
+  at: string;
+  kind: McpTransportEventKind;
+  sessionId: string;
+  connectionId: string;
+  route: string;
+  principalId: string;
+  reason?: string;
+}
+
 export interface McpIncident {
   traceId: string;
   requestId: string;
@@ -60,6 +77,8 @@ const MCP_DIAGNOSTIC_MAX_PENDING_ENTRIES = 4_096;
 const MCP_DIAGNOSTIC_MAX_BATCH_BYTES = 256 * 1024;
 const MCP_INCIDENT_MEMORY_WINDOW_LIMIT = 1_024;
 const MCP_INCIDENT_MEMORY_LEDGER_LIMIT = 64;
+const MCP_TRANSPORT_EVENT_TAIL_BYTES = 256 * 1024;
+const MCP_TRANSPORT_EVENT_READ_LIMIT = 64;
 
 interface PendingDiagnosticLedger {
   readonly root: string;
@@ -71,6 +90,7 @@ interface PendingDiagnosticLedger {
 
 const diagnosticLedgers = new Map<string, PendingDiagnosticLedger>();
 const recentIncidents = new Map<string, Array<McpIncident & { at: string }>>();
+const recentTransportEvents = new Map<string, McpTransportEvent[]>();
 
 function ledgerFor(controllerHome: string, fileName: string): PendingDiagnosticLedger {
   const root = join(resolve(controllerHome), 'audit');
@@ -200,3 +220,97 @@ export function recordMcpIncident(controllerHome: string, incident: McpIncident)
 export function recentMcpIncidents(controllerHome: string): Array<McpIncident & { at: string }> {
   return [...(recentIncidents.get(resolve(controllerHome)) ?? [])];
 }
+
+
+function readDiagnosticTail<T>(controllerHome: string, fileName: string, maxBytes: number): T[] {
+  const path = join(resolve(controllerHome), 'audit', fileName);
+  if (!existsSync(path)) return [];
+  let fd: number | undefined;
+  try {
+    const size = statSync(path).size;
+    const length = Math.min(size, maxBytes);
+    const start = Math.max(0, size - length);
+    const buffer = Buffer.alloc(length);
+    fd = openSync(path, 'r');
+    const read = readSync(fd, buffer, 0, length, start);
+    let text = buffer.subarray(0, read).toString('utf8');
+    if (start > 0) {
+      const newline = text.indexOf('\n');
+      text = newline >= 0 ? text.slice(newline + 1) : '';
+    }
+    return text.split(/\r?\n/).filter(Boolean).flatMap((line) => {
+      try {
+        const parsed = JSON.parse(line) as T;
+        return parsed && typeof parsed === 'object' ? [parsed] : [];
+      } catch {
+        return [];
+      }
+    });
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/**
+ * Durable transport evidence only. It is deliberately separate from MCP tool
+ * incidents so normal reconnects cannot trigger incident-repair Work. The
+ * bounded JSONL tail survives Gateway restart without owning any lifecycle.
+ */
+export function recordMcpTransportEvent(
+  controllerHome: string,
+  event: Omit<McpTransportEvent, 'schemaVersion' | 'at'> & { at?: string },
+): void {
+  try {
+    const root = resolve(controllerHome);
+    const record: McpTransportEvent = {
+      schemaVersion: 1,
+      at: event.at ?? new Date().toISOString(),
+      kind: event.kind,
+      sessionId: event.sessionId,
+      connectionId: event.connectionId,
+      route: event.route,
+      principalId: event.principalId,
+      ...(event.reason ? { reason: event.reason } : {}),
+    };
+    const remembered = recentTransportEvents.get(root) ?? [];
+    remembered.push(record);
+    if (remembered.length > MCP_TRANSPORT_EVENT_READ_LIMIT) {
+      remembered.splice(0, remembered.length - MCP_TRANSPORT_EVENT_READ_LIMIT);
+    }
+    recentTransportEvents.set(root, remembered);
+    appendDiagnostic(controllerHome, 'mcp-transport-events.jsonl', { ...record });
+  } catch {
+    // Transport observability is diagnostic-only and must never affect protocol
+    // initialization, request routing, or session lifecycle.
+  }
+}
+
+export function readRecentMcpTransportEvents(
+  controllerHome: string,
+  limit = MCP_TRANSPORT_EVENT_READ_LIMIT,
+): McpTransportEvent[] {
+  const boundedLimit = Math.max(1, Math.min(limit, MCP_TRANSPORT_EVENT_READ_LIMIT));
+  const durable = readDiagnosticTail<McpTransportEvent>(
+    controllerHome,
+    'mcp-transport-events.jsonl',
+    MCP_TRANSPORT_EVENT_TAIL_BYTES,
+  );
+  const memory = recentTransportEvents.get(resolve(controllerHome)) ?? [];
+  const unique = new Map<string, McpTransportEvent>();
+  for (const event of [...durable, ...memory]) {
+    if (event.schemaVersion !== 1
+      || (event.kind !== 'interruption' && event.kind !== 'session_initialized')
+      || typeof event.at !== 'string'
+      || !Number.isFinite(Date.parse(event.at))
+      || typeof event.sessionId !== 'string'
+      || typeof event.connectionId !== 'string'
+      || typeof event.route !== 'string'
+      || typeof event.principalId !== 'string') continue;
+    unique.set(`${event.at}\0${event.kind}\0${event.sessionId}`, event);
+  }
+  return [...unique.values()]
+    .sort((a, b) => Date.parse(b.at) - Date.parse(a.at))
+    .slice(0, boundedLimit);
+}

package/src/runtime/evidence/artifact-store.ts

@@ -1,15 +1,18 @@
-import { randomUUID } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import { closeSync, existsSync, mkdirSync, opendirSync, openSync, readSync, statSync } from 'fs';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { controllerSystemRoot, repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import type { ExecutionJob } from '../execution/jobs/types';
 import { readJsonFile, removeFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+import { deleteOutputHandleIndexEntry, recordOutputHandleIndexEntry, readOutputHandleIndexEntry, type OutputHandleStorage } from './output-handle-index';
 
 export interface ExecutionArtifactRecord {
   schemaVersion: 1;
   artifactId: string;
-  repoId: string;
+  /** Repository provenance only. */
+  repoId?: string;
   jobId: string;
+  principalId?: string;
   kind: 'job-result' | 'job-error' | 'command-output' | 'evidence';
   mediaType: 'application/json' | 'text/plain';
   path: string;
@@ -17,18 +20,123 @@ export interface ExecutionArtifactRecord {
   createdAt: string;
 }
 
-function artifactRoot(controllerHome: string, repoId: string): string {
-  const root = join(repositoryControllerRoot(controllerHome, repoId), 'artifacts');
-  mkdirSync(root, { recursive: true });
+function canonicalArtifactRoot(controllerHome: string): string {
+  const root = join(controllerSystemRoot(controllerHome), 'outputs', 'artifacts');
+  mkdirSync(join(root, 'data'), { recursive: true });
+  mkdirSync(join(root, 'records'), { recursive: true });
   return root;
 }
 
-function artifactDataPath(controllerHome: string, repoId: string, artifactId: string): string {
-  return join(artifactRoot(controllerHome, repoId), 'data', `${sanitizeFileComponent(artifactId)}.json`);
+function legacyArtifactRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'artifacts');
 }
 
-function metadataPath(controllerHome: string, repoId: string, artifactId: string): string {
-  return join(artifactRoot(controllerHome, repoId), 'records', `${sanitizeFileComponent(artifactId)}.json`);
+function artifactRoot(controllerHome: string, storage: OutputHandleStorage): string {
+  return storage.scope === 'instance'
+    ? canonicalArtifactRoot(controllerHome)
+    : legacyArtifactRoot(controllerHome, storage.repositoryId);
+}
+
+function artifactDataPath(controllerHome: string, storage: OutputHandleStorage, artifactId: string): string {
+  return join(artifactRoot(controllerHome, storage), 'data', `${sanitizeFileComponent(artifactId)}.json`);
+}
+
+function metadataPath(controllerHome: string, storage: OutputHandleStorage, artifactId: string): string {
+  return join(artifactRoot(controllerHome, storage), 'records', `${sanitizeFileComponent(artifactId)}.json`);
+}
+
+function artifactFingerprint(record: ExecutionArtifactRecord, value: unknown): string {
+  return createHash('sha256').update(JSON.stringify({
+    artifactId: record.artifactId,
+    jobId: record.jobId,
+    principalId: record.principalId ?? null,
+    kind: record.kind,
+    mediaType: record.mediaType,
+    createdAt: record.createdAt,
+    value,
+  })).digest('hex');
+}
+
+function registerArtifact(
+  controllerHome: string,
+  record: ExecutionArtifactRecord,
+  value: unknown,
+  storage: OutputHandleStorage,
+): void {
+  recordOutputHandleIndexEntry(controllerHome, {
+    handleId: record.artifactId,
+    kind: 'artifact',
+    storage,
+    repositoryId: record.repoId,
+    principalId: record.principalId,
+    operationId: record.jobId,
+    fingerprint: artifactFingerprint(record, value),
+  });
+}
+
+function loadArtifactAt(
+  controllerHome: string,
+  artifactId: string,
+  storage: OutputHandleStorage,
+): { artifact: ExecutionArtifactRecord; content: unknown; dataPath: string } {
+  const stored = readJsonFile<ExecutionArtifactRecord>(metadataPath(controllerHome, storage, artifactId));
+  if (stored.artifactId !== artifactId) throw new Error('ARTIFACT_IDENTITY_MISMATCH');
+  if (storage.scope === 'legacy_repository' && stored.repoId && stored.repoId !== storage.repositoryId) {
+    throw new Error('ARTIFACT_REPOSITORY_PROVENANCE_MISMATCH');
+  }
+  const path = artifactDataPath(controllerHome, storage, artifactId);
+  const content = readJsonFile<unknown>(path);
+  return {
+    artifact: {
+      ...stored,
+      ...(storage.scope === 'legacy_repository' && !stored.repoId ? { repoId: storage.repositoryId } : {}),
+      path,
+    },
+    content,
+    dataPath: path,
+  };
+}
+
+function resolveArtifact(
+  controllerHome: string,
+  artifactId: string,
+  legacyRepoId?: string,
+): { artifact: ExecutionArtifactRecord; content: unknown; dataPath: string; storage: OutputHandleStorage } {
+  if (legacyRepoId) {
+    const storage: OutputHandleStorage = { scope: 'legacy_repository', repositoryId: legacyRepoId };
+    const loaded = loadArtifactAt(controllerHome, artifactId, storage);
+    registerArtifact(controllerHome, loaded.artifact, loaded.content, storage);
+    return { ...loaded, storage };
+  }
+
+  const indexed = readOutputHandleIndexEntry(controllerHome, artifactId);
+  if (indexed) {
+    if (indexed.kind !== 'artifact') throw new Error(`OUTPUT_HANDLE_KIND_MISMATCH: ${artifactId}`);
+    const loaded = loadArtifactAt(controllerHome, artifactId, indexed.storage);
+    if (artifactFingerprint(loaded.artifact, loaded.content) !== indexed.fingerprint) {
+      throw new Error(`OUTPUT_HANDLE_FINGERPRINT_MISMATCH: ${artifactId}`);
+    }
+    return { ...loaded, storage: indexed.storage };
+  }
+
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  if (!existsSync(metadataPath(controllerHome, storage, artifactId))) {
+    throw new Error(`ARTIFACT_LOCATOR_NOT_FOUND: ${artifactId}; supply repo_id only once when adopting a historical repository artifact`);
+  }
+  const loaded = loadArtifactAt(controllerHome, artifactId, storage);
+  registerArtifact(controllerHome, loaded.artifact, loaded.content, storage);
+  return { ...loaded, storage };
+}
+
+function assertArtifactAccess(record: ExecutionArtifactRecord, principalId?: string): void {
+  // Omitting principalId is reserved for trusted in-process integrity readers.
+  // External adapters must always provide an explicit principal (or anonymous).
+  if (principalId === undefined) return;
+  const owner = record.principalId?.trim();
+  const caller = principalId.trim();
+  if (owner && caller !== owner) {
+    throw new Error('ARTIFACT_ACCESS_DENIED: artifact belongs to another principal');
+  }
 }
 
 export function writeExecutionArtifact(
@@ -38,20 +146,24 @@ export function writeExecutionArtifact(
   value: unknown,
 ): ExecutionArtifactRecord {
   const artifactId = `ART-${Date.now()}-${randomUUID().slice(0, 8)}`;
-  const dataPath = artifactDataPath(controllerHome, job.repoId, artifactId);
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  const dataPath = artifactDataPath(controllerHome, storage, artifactId);
   writeJsonAtomic(dataPath, value);
+  const principalId = job.origin.actor?.trim();
   const record: ExecutionArtifactRecord = {
     schemaVersion: 1,
     artifactId,
-    repoId: job.repoId,
+    ...(job.repoId?.trim() ? { repoId: job.repoId.trim() } : {}),
     jobId: job.jobId,
+    ...(principalId ? { principalId } : {}),
     kind,
     mediaType: 'application/json',
     path: dataPath,
     byteLength: statSync(dataPath).size,
     createdAt: new Date().toISOString(),
   };
-  writeJsonAtomic(metadataPath(controllerHome, job.repoId, artifactId), record);
+  writeJsonAtomic(metadataPath(controllerHome, storage, artifactId), record);
+  registerArtifact(controllerHome, record, value, storage);
   return record;
 }
 
@@ -65,9 +177,9 @@ export interface ExecutionArtifactJobCleanupReport {
 }
 
 /**
- * Reclaim only artifacts whose immutable metadata names the exact retired Job.
- * Stored path strings are never followed; metadata/data paths are re-derived
- * from the validated artifact id under this repository's Controller Home.
+ * Reclaim only canonical instance artifacts whose immutable metadata names the
+ * exact retired Job. Historical repository partitions are intentionally
+ * read-only after the output-handle cutover.
  */
 export function cleanupExecutionArtifactsForJob(
   controllerHome: string,
@@ -78,7 +190,8 @@ export function cleanupExecutionArtifactsForJob(
   const report: ExecutionArtifactJobCleanupReport = {
     policyVersion: 'execution-artifact-job-cleanup-v1', inspected: 0, matched: 0, removed: 0, scanTruncated: false, blockers: [],
   };
-  const root = join(repositoryControllerRoot(controllerHome, repoId), 'artifacts');
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  const root = canonicalArtifactRoot(controllerHome);
   const recordsRoot = join(root, 'records');
   if (!existsSync(recordsRoot)) return report;
   const maxScan = Math.max(1, Math.min(Math.trunc(options.maxScan ?? 5_000), 5_000));
@@ -96,7 +209,7 @@ export function cleanupExecutionArtifactsForJob(
         report.blockers.push(`invalid_metadata:${entry.name}`);
         continue;
       }
-      if (record.schemaVersion !== 1 || record.repoId !== repoId || !record.artifactId || !record.jobId) {
+      if (record.schemaVersion !== 1 || !record.artifactId || !record.jobId) {
         report.blockers.push(`identity_mismatch:${entry.name}`);
         continue;
       }
@@ -105,9 +218,23 @@ export function cleanupExecutionArtifactsForJob(
         report.blockers.push(`artifact_key_mismatch:${entry.name}`);
         continue;
       }
-      if (record.jobId !== jobId) continue;
+      if (record.jobId !== jobId || (record.repoId && record.repoId !== repoId)) continue;
       report.matched += 1;
-      removeFile(join(root, 'data', expectedName));
+      const dataPath = artifactDataPath(controllerHome, storage, record.artifactId);
+      let value: unknown;
+      try {
+        value = readJsonFile<unknown>(dataPath);
+      } catch {
+        report.blockers.push(`artifact_data_missing:${record.artifactId}`);
+        continue;
+      }
+      const fingerprint = artifactFingerprint(record, value);
+      deleteOutputHandleIndexEntry(controllerHome, {
+        handleId: record.artifactId,
+        kind: 'artifact',
+        expectedFingerprint: fingerprint,
+      });
+      removeFile(dataPath);
       removeFile(recordPath);
       report.removed += 1;
     }
@@ -120,25 +247,23 @@ export function cleanupExecutionArtifactsForJob(
 
 export function readExecutionArtifact(
   controllerHome: string,
-  repoId: string,
   artifactId: string,
   maxBytes = 512 * 1024,
+  options: { legacyRepoId?: string; principalId?: string } = {},
 ): { artifact: ExecutionArtifactRecord; content: unknown; truncated: boolean } {
-  const artifact = readJsonFile<ExecutionArtifactRecord>(metadataPath(controllerHome, repoId, artifactId));
-  if (artifact.repoId !== repoId || artifact.artifactId !== artifactId) throw new Error('ARTIFACT_IDENTITY_MISMATCH');
+  const resolved = resolveArtifact(controllerHome, artifactId, options.legacyRepoId);
+  assertArtifactAccess(resolved.artifact, options.principalId);
   const bounded = Math.max(1_024, Math.min(maxBytes, 2 * 1024 * 1024));
-  // Derive the path from trusted identifiers. Never follow a path stored in mutable metadata.
-  const dataPath = artifactDataPath(controllerHome, repoId, artifactId);
-  const byteLength = statSync(dataPath).size;
+  const byteLength = statSync(resolved.dataPath).size;
   const length = Math.min(byteLength, bounded);
   const buffer = Buffer.alloc(length);
-  const descriptor = openSync(dataPath, 'r');
+  const descriptor = openSync(resolved.dataPath, 'r');
   try { readSync(descriptor, buffer, 0, length, 0); } finally { closeSync(descriptor); }
   if (byteLength <= bounded) {
-    return { artifact: { ...artifact, path: dataPath, byteLength }, content: JSON.parse(buffer.toString('utf8')), truncated: false };
+    return { artifact: { ...resolved.artifact, byteLength }, content: JSON.parse(buffer.toString('utf8')), truncated: false };
   }
   return {
-    artifact: { ...artifact, path: dataPath, byteLength },
+    artifact: { ...resolved.artifact, byteLength },
     content: {
       preview: buffer.toString('utf8'),
       byteLength,
@@ -154,8 +279,6 @@ export function boundExecutionResult(
   result: Record<string, unknown>,
   kind: ExecutionArtifactRecord['kind'] = 'job-result',
 ): { result: Record<string, unknown>; artifact?: ExecutionArtifactRecord } {
-  // Default success budget stays compact (~16KB). Callers still fetch full
-  // content via get_artifact when externalized.
   const DEFAULT_INLINE_SUCCESS = 16 * 1024;
   const DEFAULT_INLINE_ERROR = 32 * 1024;
   const configured = typeof job.payload.maxOutputBytes === 'number' ? job.payload.maxOutputBytes : DEFAULT_INLINE_SUCCESS;
@@ -175,25 +298,21 @@ export function boundExecutionResult(
         referenceType: 'artifact',
         artifactId: artifact.artifactId,
         artifactKind: artifact.kind,
-        // Keep a short human message, never the full JSON dump.
         message: typeof result.message === 'string'
           ? String(result.message).slice(0, 800)
           : (typeof result.error === 'string' ? String(result.error).slice(0, 800) : 'Job failed; full details externalized.'),
         detailPointer: {
           tool: 'get_artifact',
-          repoId: job.repoId,
           artifactId: artifact.artifactId,
           maxBytes,
         },
-        next: `Call get_artifact with repo_id=${job.repoId} and artifact_id=${artifact.artifactId} (ART-..., not EVD-...).`,
+        next: `Call get_artifact with artifact_id=${artifact.artifactId} (ART-..., not EVD-...).`,
       },
     };
   }
 
-  if (bytes <= maxBytes) {
-    // Prefer inlining compact stdout/stderr when present.
-    return { result };
-  }
+  if (bytes <= maxBytes) return { result };
+
   const artifact = writeExecutionArtifact(controllerHome, job, kind, result);
   return {
     artifact,
@@ -207,11 +326,10 @@ export function boundExecutionResult(
       preview: serialized.slice(0, Math.min(2 * 1024, serialized.length)),
       detailPointer: {
         tool: 'get_artifact',
-        repoId: job.repoId,
         artifactId: artifact.artifactId,
         maxBytes,
       },
-      next: `Call get_artifact with repo_id=${job.repoId} and artifact_id=${artifact.artifactId} (ART-..., not EVD-...).`,
+      next: `Call get_artifact with artifact_id=${artifact.artifactId} (ART-..., not EVD-...).`,
     },
   };
 }

package/src/runtime/evidence/evidence-store.ts

@@ -1,16 +1,20 @@
 import { createHash, randomUUID } from 'crypto';
+import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { controllerSystemRoot, repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
 import type { ExecutionJob } from '../execution/jobs/types';
+import { recordOutputHandleIndexEntry, readOutputHandleIndexEntry, type OutputHandleStorage } from './output-handle-index';
 
 export interface ExecutionEvidence {
   schemaVersion: 1;
   evidenceId: string;
-  repoId: string;
+  /** Repository provenance only. */
+  repoId?: string;
   checkoutId?: string;
   jobId: string;
+  principalId?: string;
   revision: string;
   operation: string;
   environmentFingerprint: string;
@@ -33,13 +37,109 @@ function environmentFingerprint(): string {
   })).digest('hex').slice(0, 24);
 }
 
-function executionEvidencePath(controllerHome: string, repoId: string, evidenceId: string): string {
+function canonicalEvidencePath(controllerHome: string, evidenceId: string): string {
+  return join(controllerSystemRoot(controllerHome), 'outputs', 'evidence', `${sanitizeFileComponent(evidenceId)}.json`);
+}
+
+function legacyEvidencePath(controllerHome: string, repoId: string, evidenceId: string): string {
   return join(repositoryControllerRoot(controllerHome, repoId), 'evidence', `${sanitizeFileComponent(evidenceId)}.json`);
 }
 
-export function readExecutionEvidence(controllerHome: string, repoId: string, evidenceId: string): ExecutionEvidence {
-  const evidence = readJsonFile<ExecutionEvidence>(executionEvidencePath(controllerHome, repoId, evidenceId));
-  if (evidence.repoId !== repoId || evidence.evidenceId !== evidenceId) throw new Error('EVIDENCE_IDENTITY_MISMATCH');
+function evidencePath(controllerHome: string, storage: OutputHandleStorage, evidenceId: string): string {
+  return storage.scope === 'instance'
+    ? canonicalEvidencePath(controllerHome, evidenceId)
+    : legacyEvidencePath(controllerHome, storage.repositoryId, evidenceId);
+}
+
+function evidenceFingerprint(evidence: ExecutionEvidence): string {
+  return createHash('sha256').update(JSON.stringify({
+    evidenceId: evidence.evidenceId,
+    checkoutId: evidence.checkoutId ?? null,
+    jobId: evidence.jobId,
+    principalId: evidence.principalId ?? null,
+    revision: evidence.revision,
+    operation: evidence.operation,
+    environmentFingerprint: evidence.environmentFingerprint,
+    executedAt: evidence.executedAt,
+    outcome: evidence.outcome,
+    details: evidence.details ?? null,
+  })).digest('hex');
+}
+
+function registerEvidence(
+  controllerHome: string,
+  evidence: ExecutionEvidence,
+  storage: OutputHandleStorage,
+): void {
+  recordOutputHandleIndexEntry(controllerHome, {
+    handleId: evidence.evidenceId,
+    kind: 'evidence',
+    storage,
+    repositoryId: evidence.repoId,
+    principalId: evidence.principalId,
+    operationId: evidence.jobId,
+    fingerprint: evidenceFingerprint(evidence),
+  });
+}
+
+function loadEvidenceAt(
+  controllerHome: string,
+  evidenceId: string,
+  storage: OutputHandleStorage,
+): ExecutionEvidence {
+  const stored = readJsonFile<ExecutionEvidence>(evidencePath(controllerHome, storage, evidenceId));
+  if (stored.evidenceId !== evidenceId) throw new Error('EVIDENCE_IDENTITY_MISMATCH');
+  if (storage.scope === 'legacy_repository' && stored.repoId && stored.repoId !== storage.repositoryId) {
+    throw new Error('EVIDENCE_REPOSITORY_PROVENANCE_MISMATCH');
+  }
+  return {
+    ...stored,
+    ...(storage.scope === 'legacy_repository' && !stored.repoId ? { repoId: storage.repositoryId } : {}),
+  };
+}
+
+function assertEvidenceAccess(evidence: ExecutionEvidence, principalId?: string): void {
+  // Omitting principalId is reserved for trusted in-process integrity readers.
+  // External adapters must always provide an explicit principal (or anonymous).
+  if (principalId === undefined) return;
+  const owner = evidence.principalId?.trim();
+  const caller = principalId.trim();
+  if (owner && owner !== caller) {
+    throw new Error('EVIDENCE_ACCESS_DENIED: evidence belongs to another principal');
+  }
+}
+
+export function readExecutionEvidence(
+  controllerHome: string,
+  evidenceId: string,
+  options: { legacyRepoId?: string; principalId?: string } = {},
+): ExecutionEvidence {
+  if (options.legacyRepoId) {
+    const storage: OutputHandleStorage = { scope: 'legacy_repository', repositoryId: options.legacyRepoId };
+    const evidence = loadEvidenceAt(controllerHome, evidenceId, storage);
+    registerEvidence(controllerHome, evidence, storage);
+    assertEvidenceAccess(evidence, options.principalId);
+    return evidence;
+  }
+
+  const indexed = readOutputHandleIndexEntry(controllerHome, evidenceId);
+  if (indexed) {
+    if (indexed.kind !== 'evidence') throw new Error(`OUTPUT_HANDLE_KIND_MISMATCH: ${evidenceId}`);
+    const evidence = loadEvidenceAt(controllerHome, evidenceId, indexed.storage);
+    if (evidenceFingerprint(evidence) !== indexed.fingerprint) {
+      throw new Error(`OUTPUT_HANDLE_FINGERPRINT_MISMATCH: ${evidenceId}`);
+    }
+    assertEvidenceAccess(evidence, options.principalId);
+    return evidence;
+  }
+
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  if (!existsSync(evidencePath(controllerHome, storage, evidenceId))) {
+    throw new Error(`EVIDENCE_LOCATOR_NOT_FOUND: ${evidenceId}; supply repo_id only once when adopting historical repository evidence`);
+  }
+  const evidence = loadEvidenceAt(controllerHome, evidenceId, storage);
+  registerEvidence(controllerHome, evidence, storage);
+  assertEvidenceAccess(evidence, options.principalId);
   return evidence;
 }
 
@@ -50,12 +150,14 @@ export function recordExecutionEvidence(
   outcome: 'succeeded' | 'failed',
   details?: Record<string, unknown>,
 ): ExecutionEvidence {
+  const principalId = job.origin.actor?.trim();
   const evidence: ExecutionEvidence = {
     schemaVersion: 1,
     evidenceId: `EVD-${Date.now()}-${randomUUID().slice(0, 8)}`,
-    repoId: job.repoId,
+    ...(job.repoId?.trim() ? { repoId: job.repoId.trim() } : {}),
     checkoutId: job.checkoutId,
     jobId: job.jobId,
+    ...(principalId ? { principalId } : {}),
     revision: gitRevision(repoRoot),
     operation: job.payload.operation,
     environmentFingerprint: environmentFingerprint(),
@@ -63,6 +165,8 @@ export function recordExecutionEvidence(
     outcome,
     details,
   };
-  writeJsonAtomic(executionEvidencePath(controllerHome, job.repoId, evidence.evidenceId), evidence);
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  writeJsonAtomic(evidencePath(controllerHome, storage, evidence.evidenceId), evidence);
+  registerEvidence(controllerHome, evidence, storage);
   return evidence;
 }