@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,15 +1,17 @@
-import { randomUUID } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import { chmodSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
 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 { recordOutputHandleIndexEntry, readOutputHandleIndexEntry, refreshOutputHandleFingerprint, type OutputHandleStorage } from './output-handle-index';
 import { redactSensitiveValue, type SensitiveRedactionCount } from './sensitive-output';
 
 export interface ControllerResultRecord {
   schemaVersion: 1;
   resultId: string;
   resultRef: string;
-  repoId: string;
+  /** Repository provenance only. It is not part of the canonical result locator. */
+  repoId?: string;
   sessionId: string;
   principalId: string;
   workId?: string;
@@ -24,19 +26,29 @@ export interface ControllerResultRecord {
   };
 }
 
-function resultRoot(controllerHome: string, repoId: string): string {
-  const root = join(repositoryControllerRoot(controllerHome, repoId), 'results');
+function canonicalResultRoot(controllerHome: string): string {
+  const root = join(controllerSystemRoot(controllerHome), 'outputs', 'results');
   mkdirSync(join(root, 'records'), { recursive: true, mode: 0o700 });
   mkdirSync(join(root, 'data'), { recursive: true, mode: 0o700 });
   return root;
 }
 
-function recordPath(controllerHome: string, repoId: string, resultId: string): string {
-  return join(resultRoot(controllerHome, repoId), 'records', `${sanitizeFileComponent(resultId)}.json`);
+function legacyResultRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'results');
 }
 
-function dataPath(controllerHome: string, repoId: string, resultId: string): string {
-  return join(resultRoot(controllerHome, repoId), 'data', `${sanitizeFileComponent(resultId)}.json`);
+function resultRoot(controllerHome: string, storage: OutputHandleStorage): string {
+  return storage.scope === 'instance'
+    ? canonicalResultRoot(controllerHome)
+    : legacyResultRoot(controllerHome, storage.repositoryId);
+}
+
+function recordPath(controllerHome: string, storage: OutputHandleStorage, resultId: string): string {
+  return join(resultRoot(controllerHome, storage), 'records', `${sanitizeFileComponent(resultId)}.json`);
+}
+
+function dataPath(controllerHome: string, storage: OutputHandleStorage, resultId: string): string {
+  return join(resultRoot(controllerHome, storage), 'data', `${sanitizeFileComponent(resultId)}.json`);
 }
 
 function writePrivateJson(path: string, value: unknown): void {
@@ -53,33 +65,131 @@ function redactionMetadata(redactions: SensitiveRedactionCount[]): NonNullable<C
   };
 }
 
-function sanitizeStoredResult(
+function canonicalResultRef(resultId: string): string {
+  return `result://${resultId}`;
+}
+
+function resultFingerprint(record: ControllerResultRecord, value: unknown): string {
+  return createHash('sha256').update(JSON.stringify({
+    resultId: record.resultId,
+    sessionId: record.sessionId,
+    principalId: record.principalId,
+    workId: record.workId ?? null,
+    kind: record.kind,
+    createdAt: record.createdAt,
+    value,
+  })).digest('hex');
+}
+
+function registerResult(
   controllerHome: string,
   record: ControllerResultRecord,
+  value: unknown,
+  storage: OutputHandleStorage,
+): void {
+  recordOutputHandleIndexEntry(controllerHome, {
+    handleId: record.resultId,
+    kind: 'result',
+    storage,
+    repositoryId: record.repoId,
+    principalId: record.principalId,
+    sessionId: record.sessionId,
+    workId: record.workId,
+    fingerprint: resultFingerprint(record, value),
+  });
+}
+
+function parseRef(resultRef: string): { resultId: string; legacyRepoId?: string } {
+  const normalized = resultRef.trim();
+  const canonical = /^result:\/\/([^/]+)$/.exec(normalized);
+  if (canonical) return { resultId: canonical[1]! };
+  const legacy = /^result:\/\/([^/]+)\/([^/]+)$/.exec(normalized);
+  if (legacy) return { legacyRepoId: legacy[1]!, resultId: legacy[2]! };
+  throw new Error('RESULT_REF_INVALID: expected result://<resultId>');
+}
+
+function loadResultAt(
+  controllerHome: string,
+  resultId: string,
+  storage: OutputHandleStorage,
+): { record: ControllerResultRecord; value: unknown } {
+  const stored = readJsonFile<ControllerResultRecord>(recordPath(controllerHome, storage, resultId));
+  if (stored.resultId !== resultId) throw new Error('RESULT_IDENTITY_MISMATCH');
+  const value = readJsonFile<unknown>(dataPath(controllerHome, storage, resultId));
+  const record: ControllerResultRecord = {
+    ...stored,
+    resultRef: canonicalResultRef(resultId),
+    ...(storage.scope === 'legacy_repository' && !stored.repoId ? { repoId: storage.repositoryId } : {}),
+  };
+  return { record, value };
+}
+
+function resolveStoredResult(
+  controllerHome: string,
+  resultId: string,
+  legacyRepoId?: string,
+): { record: ControllerResultRecord; value: unknown; storage: OutputHandleStorage } {
+  if (legacyRepoId) {
+    const storage: OutputHandleStorage = { scope: 'legacy_repository', repositoryId: legacyRepoId };
+    const loaded = loadResultAt(controllerHome, resultId, storage);
+    registerResult(controllerHome, loaded.record, loaded.value, storage);
+    return { ...loaded, storage };
+  }
+
+  const indexed = readOutputHandleIndexEntry(controllerHome, resultId);
+  if (indexed) {
+    if (indexed.kind !== 'result') throw new Error(`OUTPUT_HANDLE_KIND_MISMATCH: ${resultId}`);
+    const loaded = loadResultAt(controllerHome, resultId, indexed.storage);
+    if (resultFingerprint(loaded.record, loaded.value) !== indexed.fingerprint) {
+      throw new Error(`OUTPUT_HANDLE_FINGERPRINT_MISMATCH: ${resultId}`);
+    }
+    return { ...loaded, storage: indexed.storage };
+  }
+
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  const canonicalRecord = recordPath(controllerHome, storage, resultId);
+  if (!existsSync(canonicalRecord)) {
+    throw new Error(`RESULT_LOCATOR_NOT_FOUND: ${resultId}; legacy results require their historical result://<repoId>/<resultId> reference once`);
+  }
+  const loaded = loadResultAt(controllerHome, resultId, storage);
+  registerResult(controllerHome, loaded.record, loaded.value, storage);
+  return { ...loaded, storage };
+}
+
+function sanitizeResolvedResult(
+  controllerHome: string,
+  record: ControllerResultRecord,
+  value: unknown,
+  storage: OutputHandleStorage,
 ): { record: ControllerResultRecord; value: unknown; changed: boolean } {
-  const path = dataPath(controllerHome, record.repoId, record.resultId);
-  const raw = readJsonFile<unknown>(path);
-  const sanitized = redactSensitiveValue(raw);
-  if (!sanitized.changed) return { record, value: raw, changed: false };
-  writePrivateJson(path, sanitized.value);
+  const sanitized = redactSensitiveValue(value);
+  if (!sanitized.changed) return { record, value, changed: false };
   const next: ControllerResultRecord = {
     ...record,
-    byteLength: statSync(path).size,
     redaction: redactionMetadata(sanitized.redactions),
   };
-  writePrivateJson(recordPath(controllerHome, record.repoId, record.resultId), next);
+  if (storage.scope === 'instance') {
+    const previousFingerprint = resultFingerprint(record, value);
+    const nextFingerprint = resultFingerprint(next, sanitized.value);
+    const path = dataPath(controllerHome, storage, record.resultId);
+    writePrivateJson(path, sanitized.value);
+    next.byteLength = statSync(path).size;
+    writePrivateJson(recordPath(controllerHome, storage, record.resultId), next);
+    refreshOutputHandleFingerprint(controllerHome, {
+      handleId: record.resultId,
+      kind: 'result',
+      expectedFingerprint: previousFingerprint,
+      nextFingerprint,
+    });
+  }
+  // Historical repository partitions are immutable after the cutover. Apply
+  // current redaction in-memory without rewriting legacy bytes.
   return { record: next, value: sanitized.value, changed: true };
 }
 
-function parseRef(resultRef: string): { repoId: string; resultId: string } {
-  const match = /^result:\/\/([^/]+)\/([^/]+)$/.exec(resultRef.trim());
-  if (!match) throw new Error('RESULT_REF_INVALID: expected result://<repoId>/<resultId>');
-  return { repoId: match[1]!, resultId: match[2]! };
-}
-
 export function writeControllerResult(input: {
   controllerHome: string;
-  repoId: string;
+  repoId?: string;
   sessionId: string;
   principalId: string;
   workId?: string;
@@ -87,15 +197,16 @@ export function writeControllerResult(input: {
   value: unknown;
 }): ControllerResultRecord {
   const resultId = `res_${randomUUID().replace(/-/g, '')}`;
-  const resultRef = `result://${input.repoId}/${resultId}`;
-  const path = dataPath(input.controllerHome, input.repoId, resultId);
+  const resultRef = canonicalResultRef(resultId);
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  const path = dataPath(input.controllerHome, storage, resultId);
   const sanitized = redactSensitiveValue(input.value);
   writePrivateJson(path, sanitized.value);
   const record: ControllerResultRecord = {
     schemaVersion: 1,
     resultId,
     resultRef,
-    repoId: input.repoId,
+    ...(input.repoId?.trim() ? { repoId: input.repoId.trim() } : {}),
     sessionId: input.sessionId,
     principalId: input.principalId,
     ...(input.workId ? { workId: input.workId } : {}),
@@ -104,7 +215,8 @@ export function writeControllerResult(input: {
     createdAt: new Date().toISOString(),
     ...(sanitized.changed ? { redaction: redactionMetadata(sanitized.redactions) } : {}),
   };
-  writePrivateJson(recordPath(input.controllerHome, input.repoId, resultId), record);
+  writePrivateJson(recordPath(input.controllerHome, storage, resultId), record);
+  registerResult(input.controllerHome, record, sanitized.value, storage);
   return record;
 }
 
@@ -123,10 +235,9 @@ export function readControllerResult(input: {
   limit?: number;
 }): { record: ControllerResultRecord; items: unknown; cursor: number; nextCursor?: number; truncated: boolean } {
   const parsed = parseRef(input.resultRef);
-  const record = readJsonFile<ControllerResultRecord>(recordPath(input.controllerHome, parsed.repoId, parsed.resultId));
-  if (record.resultRef !== input.resultRef || record.repoId !== parsed.repoId) throw new Error('RESULT_IDENTITY_MISMATCH');
-  authorizeRecord(record, input.sessionId, input.principalId, input.workId);
-  const sanitized = sanitizeStoredResult(input.controllerHome, record);
+  const resolved = resolveStoredResult(input.controllerHome, parsed.resultId, parsed.legacyRepoId);
+  authorizeRecord(resolved.record, input.sessionId, input.principalId, input.workId);
+  const sanitized = sanitizeResolvedResult(input.controllerHome, resolved.record, resolved.value, resolved.storage);
   const value = sanitized.value;
   const cursor = Math.max(0, Math.trunc(input.cursor ?? 0));
   const limit = Math.max(1, Math.min(500, Math.trunc(input.limit ?? 100)));
@@ -143,6 +254,11 @@ export function readControllerResult(input: {
     const items = source.slice(cursor, cursor + limit);
     return { record: sanitized.record, items, cursor, ...(cursor + items.length < source.length ? { nextCursor: cursor + items.length } : {}), truncated: cursor + items.length < source.length };
   }
+  if (value && typeof value === 'object') {
+    const source = JSON.stringify(value, null, 2);
+    const items = source.slice(cursor, cursor + limit * 4_096);
+    return { record: sanitized.record, items, cursor, ...(cursor + items.length < source.length ? { nextCursor: cursor + items.length } : {}), truncated: cursor + items.length < source.length };
+  }
   return { record: sanitized.record, items: value, cursor, truncated: false };
 }
 
@@ -156,10 +272,9 @@ export function searchControllerResult(input: {
   limit?: number;
 }): { record: ControllerResultRecord; matches: Array<{ line: number; text: string }>; truncated: boolean } {
   const parsed = parseRef(input.resultRef);
-  const record = readJsonFile<ControllerResultRecord>(recordPath(input.controllerHome, parsed.repoId, parsed.resultId));
-  if (record.resultRef !== input.resultRef || record.repoId !== parsed.repoId) throw new Error('RESULT_IDENTITY_MISMATCH');
-  authorizeRecord(record, input.sessionId, input.principalId, input.workId);
-  const sanitized = sanitizeStoredResult(input.controllerHome, record);
+  const resolved = resolveStoredResult(input.controllerHome, parsed.resultId, parsed.legacyRepoId);
+  authorizeRecord(resolved.record, input.sessionId, input.principalId, input.workId);
+  const sanitized = sanitizeResolvedResult(input.controllerHome, resolved.record, resolved.value, resolved.storage);
   const value = sanitized.value;
   const query = input.query.trim().toLowerCase();
   if (!query) throw new Error('RESULT_QUERY_REQUIRED');
@@ -169,17 +284,15 @@ export function searchControllerResult(input: {
   return { record: sanitized.record, matches, truncated: lines.filter((text) => text.toLowerCase().includes(query)).length > matches.length };
 }
 
-/**
- * Bounded maintenance entry point for historical result artifacts. It returns
- * only counts and ids; sensitive contents are never included in the report.
- */
-export function sanitizeControllerResultStore(controllerHome: string, repoId: string, limit = 10_000): {
+/** Bounded maintenance of the canonical instance Result store only. */
+export function sanitizeControllerResultStore(controllerHome: string, _repoId: string, limit = 10_000): {
   scanned: number;
   changed: number;
   failed: number;
   resultIds: string[];
 } {
-  const root = resultRoot(controllerHome, repoId);
+  const storage: OutputHandleStorage = { scope: 'instance' };
+  const root = canonicalResultRoot(controllerHome);
   const recordsDir = join(root, 'records');
   let scanned = 0;
   let changed = 0;
@@ -192,11 +305,12 @@ export function sanitizeControllerResultStore(controllerHome: string, repoId: st
     scanned += 1;
     try {
       const record = readJsonFile<ControllerResultRecord>(join(recordsDir, entry));
-      if (!record?.resultId || record.repoId !== repoId || !existsSync(dataPath(controllerHome, repoId, record.resultId))) {
+      if (!record?.resultId || !existsSync(dataPath(controllerHome, storage, record.resultId))) {
         failed += 1;
         continue;
       }
-      const sanitized = sanitizeStoredResult(controllerHome, record);
+      const raw = readJsonFile<unknown>(dataPath(controllerHome, storage, record.resultId));
+      const sanitized = sanitizeResolvedResult(controllerHome, record, raw, storage);
       if (sanitized.changed) {
         changed += 1;
         resultIds.push(record.resultId);

package/src/runtime/evidence/sensitive-output.ts

@@ -59,13 +59,13 @@ const SENSITIVE_PATTERNS: readonly SensitivePattern[] = [
   },
   {
     type: 'secret_assignment',
-    pattern: /((?:^|[^\w]))([A-Za-z0-9_.-]*(?:api[_-]?key|access[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key|password|passwd|secret|credentials?|auth[_-]?token|token|cookie)[A-Za-z0-9_.-]*)\s*(=>|:=|=|:)\s*(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,}\r\n]+)/gim,
-    replacement: '$1$2$3[REDACTED]',
+    pattern: /((?:^|[^\w]))(["']?)([A-Za-z0-9_.-]*(?:api[_-]?key|access[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key|password|passwd|secret|credentials?|auth[_-]?token|token|cookie)[A-Za-z0-9_.-]*)\2(\s*(?:=>|:=|=|:)\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,}\r\n]+)/gim,
+    replacement: '$1$2$3$2$4[REDACTED]',
   },
   {
     type: 'database_url_assignment',
-    pattern: /((?:^|[^\w])(?:DATABASE_URL|POSTGRES_URL|MONGODB_URI|REDIS_URL)\s*(?:=>|:=|=|:)\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,}\r\n]+)/gim,
-    replacement: '$1[REDACTED]',
+    pattern: /((?:^|[^\w]))(["']?)((?:DATABASE_URL|POSTGRES_URL|MONGODB_URI|REDIS_URL))\2(\s*(?:=>|:=|=|:)\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,}\r\n]+)/gim,
+    replacement: '$1$2$3$2$4[REDACTED]',
   },
   {
     type: 'url_userinfo',

package/src/runtime/execution/jobs/receipt-recovery.ts

@@ -1,4 +1,4 @@
-import { settleScheduledExecution } from '../../workflow/schedules/settlement';
+import { settleScheduledExecution } from '../../../../packages/kernel/scheduler/api/index';
 import {
   buildDelegatedExecutionResult,
   childReferenceFromJob,

package/src/runtime/execution/jobs/store.ts

@@ -1,16 +1,16 @@
 import { createHash, randomUUID } from 'crypto';
-import { existsSync, readdirSync } from 'fs';
+import { existsSync, opendirSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { ensureControllerHome, ensureRepositoryControllerLayout, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { releaseControllerLock, tryAcquireControllerLock, withControllerLock } from '../../../cli/repositories/locks';
 import { appendJobEvent } from '../../evidence/event-ledger';
-import { writeExecutionArtifact } from '../../evidence/artifact-store';
+import { cleanupExecutionArtifactsForJob, writeExecutionArtifact } from '../../evidence/artifact-store';
 import { markRepositoryProjectionDirty } from '../../projections/invalidation';
 import { touchSchedulerWakeSignal } from '../../control-plane/global-scheduler/wake-signal';
 import { readJsonFile, removeFile, sanitizeFileComponent, writeJsonAtomic } from '../../shared/json-files';
 import { terminateProcessTree } from '../../shared/process-tree';
 import { releaseExecutionLeases } from '../../resources/leases/store';
-import { assertRuntimeMayWriteOrThrow } from '../../root/write-fence';
+import { assertRuntimeMayWriteOrThrow, isRuntimeWriteFenceError } from '../../root/write-fence';
 import {
   ACTIVE_JOB_STATUSES,
   TERMINAL_JOB_STATUSES,
@@ -122,11 +122,10 @@ function artifactPointerFor(job: ExecutionJob, artifact: ReturnType<typeof write
     artifactKind: artifact.kind,
     detailPointer: {
       tool: 'get_artifact',
-      repoId: job.repoId,
       artifactId: artifact.artifactId,
       maxBytes: 512 * 1024,
     },
-    next: `Call get_artifact with repo_id=${job.repoId} and artifact_id=${artifact.artifactId}.`,
+    next: `Call get_artifact with artifact_id=${artifact.artifactId}.`,
   };
 }
 
@@ -439,7 +438,7 @@ export function transitionExecutionJob(
     try {
       assertRuntimeMayWriteOrThrow('write_workflow_terminal', controllerHome);
     } catch (error) {
-      if (error instanceof Error && error.message.startsWith('WRITER_FENCED:')) throw error;
+      if (isRuntimeWriteFenceError(error)) throw error;
     }
   }
   return updateExecutionJob(controllerHome, repoId, jobId, (current) => {
@@ -789,3 +788,122 @@ export function removeExecutionJobFromActiveIndex(controllerHome: string, job: E
 export function removeRequestIndex(controllerHome: string, requestId: string): void {
   removeFile(requestPath(controllerHome, requestId));
 }
+
+export interface RetiredExecutionJobCleanupReport {
+  policyVersion: 'retired-execution-job-retention-v1';
+  inspected: number;
+  terminal: number;
+  protectedActive: number;
+  eligible: number;
+  removed: number;
+  retained: number;
+  scanTruncated: boolean;
+  budgetExhausted: boolean;
+  blockers: string[];
+}
+
+const DEFAULT_RETIRED_JOB_RETENTION_MS = 30 * 24 * 60 * 60_000;
+const DEFAULT_MAX_RETAINED_TERMINAL_JOBS = 500;
+const DEFAULT_RETIRED_JOB_SCAN = 5_000;
+const DEFAULT_RETIRED_JOB_REMOVALS = 32;
+
+/**
+ * Bounded compatibility cleanup for the retired ExecutionJob authority. New
+ * execution is Work + Process, so this only reclaims proven-terminal legacy
+ * bundles and never participates in execution admission or effect recovery.
+ */
+export function cleanupRetiredExecutionJobs(
+  controllerHome: string,
+  repoId: string,
+  options: { nowMs?: number; retentionMs?: number; maxTerminalRecords?: number; maxScan?: number; maxRemovals?: number } = {},
+): RetiredExecutionJobCleanupReport {
+  assertRuntimeMayWriteOrThrow('cleanup', controllerHome);
+  if (!executionJobCreationRetired()) throw new Error('EXECUTION_JOB_RETENTION_REQUIRES_RETIRED_CREATION');
+  const nowMs = Number.isFinite(options.nowMs) ? Number(options.nowMs) : Date.now();
+  const retentionMs = Math.max(60_000, Math.trunc(options.retentionMs ?? DEFAULT_RETIRED_JOB_RETENTION_MS));
+  const maxTerminalRecords = Math.max(0, Math.min(Math.trunc(options.maxTerminalRecords ?? DEFAULT_MAX_RETAINED_TERMINAL_JOBS), 5_000));
+  const maxScan = Math.max(1, Math.min(Math.trunc(options.maxScan ?? DEFAULT_RETIRED_JOB_SCAN), 5_000));
+  const maxRemovals = Math.max(1, Math.min(Math.trunc(options.maxRemovals ?? DEFAULT_RETIRED_JOB_REMOVALS), 128));
+  const recordsRoot = join(executionJobRoot(controllerHome, repoId), 'records');
+  const scanned: Array<{ path: string; job: ExecutionJob; finishedAt: number }> = [];
+  let inspected = 0;
+  let protectedActive = 0;
+  let scanTruncated = false;
+  const blockers: string[] = [];
+
+  try {
+    const directory = opendirSync(recordsRoot);
+    try {
+      for (;;) {
+        const entry = directory.readSync();
+        if (!entry) break;
+        if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+        if (inspected >= maxScan) { scanTruncated = true; break; }
+        inspected += 1;
+        const path = join(recordsRoot, entry.name);
+        let job: ExecutionJob;
+        try { job = readJsonFile<ExecutionJob>(path); } catch { blockers.push(`invalid_record:${entry.name}`); continue; }
+        if (job.repoId !== repoId || !job.jobId || job.schemaVersion !== 1) { blockers.push(`identity_mismatch:${entry.name}`); continue; }
+        if (!TERMINAL_JOB_STATUSES.has(job.status)) { protectedActive += 1; continue; }
+        const finishedAt = Date.parse(job.finishedAt ?? job.updatedAt ?? job.createdAt);
+        scanned.push({ path, job, finishedAt: Number.isFinite(finishedAt) ? finishedAt : 0 });
+      }
+    } finally { directory.closeSync(); }
+  } catch {
+    return { policyVersion: 'retired-execution-job-retention-v1', inspected: 0, terminal: 0, protectedActive: 0, eligible: 0, removed: 0, retained: 0, scanTruncated: false, budgetExhausted: false, blockers: [] };
+  }
+
+  scanned.sort((a, b) => b.finishedAt - a.finishedAt);
+  const cutoff = nowMs - retentionMs;
+  const eligible = scanned.filter((entry, index) => index >= maxTerminalRecords || entry.finishedAt <= cutoff);
+  let removed = 0;
+  for (const candidate of eligible) {
+    if (removed >= maxRemovals) break;
+    const lockKey = { scope: 'task' as const, repoId, taskId: `execution-job-${candidate.job.jobId}` };
+    const acquired = tryAcquireControllerLock(controllerHome, lockKey, `retired-job-retention:${candidate.job.jobId}`);
+    if (!acquired.acquired) { blockers.push(`lock_contended:${candidate.job.jobId}`); continue; }
+    try {
+      let current: ExecutionJob;
+      try { current = getExecutionJob(controllerHome, repoId, candidate.job.jobId); } catch { continue; }
+      if (!TERMINAL_JOB_STATUSES.has(current.status)) { protectedActive += 1; continue; }
+      const currentFinishedAt = Date.parse(current.finishedAt ?? current.updatedAt ?? current.createdAt);
+      const expired = !Number.isFinite(currentFinishedAt) || currentFinishedAt <= cutoff;
+      const overCapacity = scanned.findIndex((entry) => entry.job.jobId === current.jobId) >= maxTerminalRecords;
+      if (!expired && !overCapacity) continue;
+
+      removeFile(candidate.path);
+      removeFile(join(executionJobRoot(controllerHome, repoId), 'receipts', `${sanitizeFileComponent(current.jobId)}.json`));
+      removeFile(join(repositoryControllerRoot(controllerHome, repoId), 'events', 'jobs', `${sanitizeFileComponent(current.jobId)}.jsonl`));
+      const artifactCleanup = cleanupExecutionArtifactsForJob(controllerHome, repoId, current.jobId);
+      blockers.push(...artifactCleanup.blockers.map((blocker) => `artifact:${current.jobId}:${blocker}`));
+      if (artifactCleanup.scanTruncated) blockers.push(`artifact_scan_truncated:${current.jobId}`);
+      if (current.requestId) removeFile(requestPath(controllerHome, current.requestId));
+      withControllerLock(controllerHome, { scope: 'global', resource: 'execution-index' }, `retired-job-index:${current.jobId}`, () => {
+        const active = readActiveIndex(controllerHome);
+        active.jobs = active.jobs.filter((entry) => entry.jobId !== current.jobId);
+        writeActiveIndex(controllerHome, active);
+        const recent = readRecentIndex(controllerHome);
+        recent.jobs = recent.jobs.filter((entry) => entry.jobId !== current.jobId);
+        writeRecentIndex(controllerHome, recent);
+      }, 10_000);
+      removed += 1;
+    } catch (error) {
+      blockers.push(error instanceof Error ? error.message : String(error));
+    } finally {
+      releaseControllerLock(controllerHome, lockKey, acquired.lock.lockId);
+    }
+  }
+
+  return {
+    policyVersion: 'retired-execution-job-retention-v1',
+    inspected,
+    terminal: scanned.length,
+    protectedActive,
+    eligible: eligible.length,
+    removed,
+    retained: Math.max(0, scanned.length - removed),
+    scanTruncated,
+    budgetExhausted: eligible.length > removed && removed >= maxRemovals,
+    blockers: blockers.slice(0, 16),
+  };
+}