@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,6 +1,6 @@
-import { appendFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { ensureControllerHome } from '../../cli/repositories/controller-home';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'fs';
+import { appendFile, mkdir, rename, rm, stat } from 'fs/promises';
+import { join, resolve } from 'path';
 
 export interface McpTimingTrace {
   tool: string;
@@ -36,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;
@@ -56,10 +72,110 @@ export interface McpIncident {
   details?: Record<string, unknown>;
 }
 
+const MCP_DIAGNOSTIC_MAX_BYTES = 32 * 1024 * 1024;
+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;
+  readonly fileName: string;
+  pending: string[];
+  pendingBytes: number;
+  drain?: Promise<void>;
+}
+
+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');
+  const key = `${root}\0${fileName}`;
+  let ledger = diagnosticLedgers.get(key);
+  if (!ledger) {
+    ledger = { root, fileName, pending: [], pendingBytes: 0 };
+    diagnosticLedgers.set(key, ledger);
+  }
+  return ledger;
+}
+
+async function existingSize(path: string): Promise<number> {
+  try {
+    return (await stat(path)).size;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 0;
+    throw error;
+  }
+}
+
+async function rotateLedger(path: string): Promise<void> {
+  const previous = `${path}.previous`;
+  // This is diagnostic evidence, not a control-plane authority. Keep one bounded
+  // previous segment so a stalled disk cannot turn unbounded telemetry into MCP
+  // dispatch latency.
+  await rm(previous, { force: true });
+  await rename(path, previous);
+}
+
+async function drainLedger(ledger: PendingDiagnosticLedger): Promise<void> {
+  const path = join(ledger.root, ledger.fileName);
+  await mkdir(ledger.root, { recursive: true, mode: 0o700 });
+  let size = await existingSize(path);
+  while (ledger.pending.length > 0) {
+    const records: string[] = [];
+    let bytes = 0;
+    while (ledger.pending.length > 0 && (records.length === 0 || bytes < MCP_DIAGNOSTIC_MAX_BATCH_BYTES)) {
+      const record = ledger.pending.shift()!;
+      ledger.pendingBytes -= Buffer.byteLength(record);
+      records.push(record);
+      bytes += Buffer.byteLength(record);
+    }
+    if (size > 0 && size + bytes > MCP_DIAGNOSTIC_MAX_BYTES) {
+      await rotateLedger(path);
+      size = 0;
+    }
+    const batch = records.join('');
+    await appendFile(path, batch, 'utf-8');
+    size += bytes;
+  }
+}
+
+function scheduleLedgerDrain(ledger: PendingDiagnosticLedger): void {
+  if (ledger.drain) return;
+  ledger.drain = drainLedger(ledger)
+    // Observability is deliberately best-effort. A write failure must not turn
+    // into a failed tool request or retain an unbounded queue in memory.
+    .catch(() => {
+      ledger.pending.length = 0;
+      ledger.pendingBytes = 0;
+    })
+    .finally(() => {
+      ledger.drain = undefined;
+      if (ledger.pending.length > 0) scheduleLedgerDrain(ledger);
+    });
+}
+
 function appendDiagnostic(controllerHome: string, fileName: string, value: Record<string, unknown>): void {
-  const root = join(ensureControllerHome(controllerHome), 'audit');
-  mkdirSync(root, { recursive: true, mode: 0o700 });
-  appendFileSync(join(root, fileName), `${JSON.stringify(value)}\n`, 'utf-8');
+  const ledger = ledgerFor(controllerHome, fileName);
+  if (ledger.pending.length >= MCP_DIAGNOSTIC_MAX_PENDING_ENTRIES) return;
+  const record = `${JSON.stringify(value)}\n`;
+  ledger.pending.push(record);
+  ledger.pendingBytes += Buffer.byteLength(record);
+  scheduleLedgerDrain(ledger);
+}
+
+/** Wait for queued diagnostic evidence in tests and explicit diagnostic consumers. */
+export async function flushMcpDiagnostics(controllerHome?: string): Promise<void> {
+  const ledgers = controllerHome
+    ? [...diagnosticLedgers.values()].filter((ledger) => ledger.root === join(resolve(controllerHome), 'audit'))
+    : [...diagnosticLedgers.values()];
+  await Promise.all(ledgers.map(async (ledger) => {
+    while (ledger.drain) await ledger.drain;
+  }));
 }
 
 export function recordMcpTiming(controllerHome: string, trace: McpTimingTrace): void {
@@ -71,6 +187,20 @@ export function recordMcpTiming(controllerHome: string, trace: McpTimingTrace):
 }
 
 export function recordMcpIncident(controllerHome: string, incident: McpIncident): void {
+  const root = resolve(controllerHome);
+  let remembered = recentIncidents.get(root);
+  if (!remembered) {
+    if (recentIncidents.size >= MCP_INCIDENT_MEMORY_LEDGER_LIMIT) {
+      const oldest = recentIncidents.keys().next().value;
+      if (oldest) recentIncidents.delete(oldest);
+    }
+    remembered = [];
+    recentIncidents.set(root, remembered);
+  }
+  remembered.push({ ...incident, at: new Date().toISOString() });
+  if (remembered.length > MCP_INCIDENT_MEMORY_WINDOW_LIMIT) {
+    remembered.splice(0, remembered.length - MCP_INCIDENT_MEMORY_WINDOW_LIMIT);
+  }
   try {
     appendDiagnostic(controllerHome, 'mcp-incidents.jsonl', {
       schemaVersion: 1,
@@ -81,3 +211,106 @@ export function recordMcpIncident(controllerHome: string, incident: McpIncident)
     // Incident recording is diagnostic evidence; it must never change the tool result.
   }
 }
+
+/**
+ * The repair classifier needs to count immediately repeated incidents before an
+ * asynchronous diagnostic batch reaches disk. This bounded volatile view is
+ * supplemental evidence only; the JSONL ledger remains the restart-safe history.
+ */
+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/diagnostics/performance.ts

@@ -1,7 +1,8 @@
 import { execFileSync } from 'child_process';
-import { existsSync, lstatSync, readdirSync, rmSync, statfsSync } from 'fs';
+import { existsSync, lstatSync, readdirSync, rmSync } from 'fs';
 import { tmpdir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
+import { readStorageCapacity } from '../shared/storage-capacity';
 
 export interface RuntimeProcessSample {
   pid: number;
@@ -323,19 +324,10 @@ export function collectRuntimePerformanceDiagnostics(input: DiagnosticsInput): R
   const temp = input.includeTempDirs === false
     ? { roots: [] as string[], entries: [] as RuntimeTempEntry[] }
     : scanRuntimeTempEntries(processes);
-  let availableBytes: number | undefined;
-  try {
-    const fs = statfsSync(input.repoRoot);
-    availableBytes = Number(fs.bavail) * Number(fs.bsize);
-  } catch {}
-  const availableGiB = availableBytes === undefined ? undefined : Math.round((availableBytes / (1024 ** 3)) * 10) / 10;
-  const storagePressure: RuntimePerformanceDiagnostics['storage']['pressure'] = availableGiB === undefined
-    ? 'unknown'
-    : availableGiB < 30
-      ? 'critical'
-      : availableGiB < 50
-        ? 'warning'
-        : 'normal';
+  const storage = readStorageCapacity(input.repoRoot);
+  const availableBytes = storage.availableBytes;
+  const availableGiB = storage.availableGiB;
+  const storagePressure: RuntimePerformanceDiagnostics['storage']['pressure'] = storage.pressure;
   const managedCacheRoots = [
     join(input.repoRoot, '.forge', 'ios', 'DerivedData'),
     join(input.repoRoot, '.ai', 'harness'),

package/src/runtime/diagnostics/read-only-tool.ts

@@ -1,5 +1,5 @@
 import type { RepositoryRecord } from '../../cli/repositories/types';
-import { loadMcpRuntimeState } from '../../cli/mcp/auth';
+import { loadMcpRuntimeState } from '../../../adapters/mcp/auth';
 import { listControllerChecks } from '../../cli/controller/check-runner';
 import { listLocalBridgeJobSnapshots } from '../../cli/local-bridge/job-store';
 import { ensureRepositoryRuntimeStorage } from '../../cli/repositories/runtime-storage';

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

@@ -1,15 +1,18 @@
-import { randomUUID } from 'crypto';
-import { closeSync, mkdirSync, openSync, readSync, statSync } from 'fs';
+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, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+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,44 +146,124 @@ 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;
 }
 
-export function readExecutionArtifact(
+export interface ExecutionArtifactJobCleanupReport {
+  policyVersion: 'execution-artifact-job-cleanup-v1';
+  inspected: number;
+  matched: number;
+  removed: number;
+  scanTruncated: boolean;
+  blockers: string[];
+}
+
+/**
+ * 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,
   repoId: string,
+  jobId: string,
+  options: { maxScan?: number } = {},
+): ExecutionArtifactJobCleanupReport {
+  const report: ExecutionArtifactJobCleanupReport = {
+    policyVersion: 'execution-artifact-job-cleanup-v1', inspected: 0, matched: 0, removed: 0, scanTruncated: false, blockers: [],
+  };
+  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));
+  const directory = opendirSync(recordsRoot);
+  try {
+    for (;;) {
+      const entry = directory.readSync();
+      if (!entry) break;
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      if (report.inspected >= maxScan) { report.scanTruncated = true; break; }
+      report.inspected += 1;
+      const recordPath = join(recordsRoot, entry.name);
+      let record: ExecutionArtifactRecord;
+      try { record = readJsonFile<ExecutionArtifactRecord>(recordPath); } catch {
+        report.blockers.push(`invalid_metadata:${entry.name}`);
+        continue;
+      }
+      if (record.schemaVersion !== 1 || !record.artifactId || !record.jobId) {
+        report.blockers.push(`identity_mismatch:${entry.name}`);
+        continue;
+      }
+      const expectedName = `${sanitizeFileComponent(record.artifactId)}.json`;
+      if (entry.name !== expectedName) {
+        report.blockers.push(`artifact_key_mismatch:${entry.name}`);
+        continue;
+      }
+      if (record.jobId !== jobId || (record.repoId && record.repoId !== repoId)) continue;
+      report.matched += 1;
+      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;
+    }
+  } finally {
+    directory.closeSync();
+  }
+  report.blockers = report.blockers.slice(0, 16);
+  return report;
+}
+
+export function readExecutionArtifact(
+  controllerHome: 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,
@@ -91,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;
@@ -112,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,
@@ -144,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-...).`,
     },
   };
 }