@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/control-plane/release-retention.ts

@@ -106,6 +106,60 @@ function releasePathFromAuthorityRecord(
   return canonical(releasePath);
 }
 
+function loadPackageConnectorReleaseProtection(controllerHome: string, releasesRoot: string): string | undefined {
+  const connectorRoot = join(controllerHome, 'runtime', 'connector-service');
+  if (!existsSync(connectorRoot)) return undefined;
+  const authorityPath = join(connectorRoot, 'authority.json');
+  if (!existsSync(authorityPath)) throw new Error('package connector release authority is missing');
+
+  const parsed = JSON.parse(readFileSync(authorityPath, 'utf8')) as Record<string, unknown>;
+  const releaseId = typeof parsed.releaseId === 'string' ? parsed.releaseId.trim() : '';
+  const releaseRootValue = typeof parsed.releaseRoot === 'string' ? parsed.releaseRoot.trim() : '';
+  const packageRoot = typeof parsed.packageRoot === 'string' ? parsed.packageRoot.trim() : '';
+  const endpoint = typeof parsed.endpoint === 'string' ? parsed.endpoint.trim() : '';
+  if (parsed.schemaVersion !== 1 || !releaseId || !releaseRootValue || !packageRoot || !endpoint) {
+    throw new Error('package connector release authority is invalid');
+  }
+  const releaseRoot = resolve(releaseRootValue);
+  if (basename(releaseRoot) !== releaseId || !directChild(releasesRoot, releaseRoot) || !existsSync(releaseRoot)) {
+    throw new Error('package connector release is outside runtime release authority or missing');
+  }
+  return canonical(releaseRoot);
+}
+
+function loadRecoveryKnownGoodReleaseProtection(controllerHome: string, releasesRoot: string): Set<string> {
+  const knownGoodPath = join(controllerHome, 'recovery', 'state', 'known-good.json');
+  const protectedPaths = new Set<string>();
+  if (!existsSync(knownGoodPath)) return protectedPaths;
+  const parsed = JSON.parse(readFileSync(knownGoodPath, 'utf8')) as Record<string, unknown>;
+  if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.releases)) {
+    throw new Error('standalone recovery known-good authority is invalid');
+  }
+  for (const raw of parsed.releases) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('standalone recovery known-good release record is invalid');
+    const record = raw as Record<string, unknown>;
+    const releaseId = typeof record.revision === 'string' ? record.revision.trim() : '';
+    const manifestPathValue = typeof record.path === 'string' ? record.path.trim() : '';
+    if (!releaseId || !manifestPathValue) throw new Error('standalone recovery known-good release identity is incomplete');
+    const manifestPath = resolve(manifestPathValue);
+    const releaseRoot = dirname(manifestPath);
+    if (
+      basename(manifestPath) !== 'manifest.json'
+      || basename(releaseRoot) !== releaseId
+      || !directChild(releasesRoot, releaseRoot)
+    ) {
+      throw new Error('standalone recovery known-good release is outside runtime releases');
+    }
+    // Known-good history is append-only recovery evidence. A historical record
+    // may legitimately outlive the retained release directory after a bounded
+    // cleanup pass. Missing historical artifacts therefore protect nothing and
+    // must not disable retention for the remaining authoritative releases.
+    if (!existsSync(manifestPath) || !existsSync(releaseRoot)) continue;
+    protectedPaths.add(canonical(releaseRoot));
+  }
+  return protectedPaths;
+}
+
 function loadRuntimeProtection(controllerHome: string): RuntimeProtection | undefined {
   const releasesRoot = join(controllerHome, 'runtime', 'releases');
   if (!existsSync(releasesRoot)) return undefined;
@@ -124,6 +178,11 @@ function loadRuntimeProtection(controllerHome: string): RuntimeProtection | unde
   if (previous !== undefined) {
     releasePaths.add(releasePathFromAuthorityRecord(releasesRoot, previous, 'previous'));
   }
+  const connectorRelease = loadPackageConnectorReleaseProtection(controllerHome, releasesRoot);
+  if (connectorRelease) releasePaths.add(connectorRelease);
+  for (const knownGoodRelease of loadRecoveryKnownGoodReleaseProtection(controllerHome, releasesRoot)) {
+    releasePaths.add(knownGoodRelease);
+  }
 
   const backupPaths = new Set<string>();
   let backupAuthoritySafe = true;
@@ -409,8 +468,9 @@ function scanLinkedReleaseFamily(
 /**
  * Reclaim immutable Controller release history while preserving the exact
  * rollback authorities. Runtime keeps active + previous + the previous DB
- * backup; Recovery/Supervisor keep current + previous. Missing or malformed
- * authority always fails closed.
+ * backup plus the immutable release backing the persistent public MCP Gateway;
+ * Recovery/Supervisor keep current + previous. Missing or malformed authority
+ * always fails closed.
  */
 export function cleanupControllerReleaseHistory(
   controllerHome: string,

package/src/runtime/control-plane/routing/route-policy.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'crypto';
 
-export const ROUTE_POLICY_VERSION = 'route-policy-v3' as const;
+export const ROUTE_POLICY_VERSION = 'route-policy-v4' as const;
 
 export type RouteExecutionMode = 'direct_control' | 'goal_workloop' | 'handoff_only';
 export type RouteWorkMode = 'direct_edit' | 'bounded_work' | 'quick_agent' | 'issue_task';
@@ -238,8 +238,6 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
     ? false
     : input.recovery.isolationRequired === true || explicitParallelMode;
   const requiresRecovery = input.recovery.required === true
-    || input.intent.requiresLongRunningChecks === true
-    || explicitMode === 'debug'
     || explicitMode === 'release'
     || explicitMode === 'scale';
   const coordinationRequired = explicitParallelMode || input.intent.requiresIndependentDeliverables === true
@@ -289,26 +287,21 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
   }
 
   if (input.workspace.dirty && mutation) {
-    reasons.push({ code: 'dirty_workspace_requires_explicit_adoption', message: 'Mutation against a dirty workspace requires an exact reviewed adoption or a clean isolated checkout.' });
-    return {
-      executionMode: 'handoff_only', executorKind: 'handoff_only', selectedProviderId: null,
-      workMode: 'direct_edit', executionPath: 'durable', requiresWork: true, requiresApproval: false,
-      requiresIsolation: true, requiresRecovery: true, createHandoff: true, waitForUser: false,
-      approvalState: 'approval_not_required', alternatives: [], ...decisionBase(input, reasons),
-    };
+    reasons.push({
+      code: 'dirty_workspace_preserve_existing_changes',
+      message: 'The checkout is already dirty; preserve unrelated changes and treat inspected/actual scope as evidence instead of creating Work solely for adoption.',
+    });
   }
   if (explicitMode) reasons.push({ code: `explicit_${explicitMode}`, message: `Explicit -${explicitMode} mode overrides automatic work topology while policy gates remain authoritative.` });
   if (protectedPath) reasons.push({ code: 'protected_path', message: 'The predicted scope includes a protected or release-sensitive path.' });
   if (requiresRecovery) reasons.push({ code: 'recovery_required', message: 'The operation needs resumable Work and bounded recovery.' });
   if (requiresIsolation) reasons.push({ code: 'isolation_required', message: 'The operation requires an isolated checkout or serialized lane.' });
-  if (input.intent.requiresLongRunningChecks) reasons.push({ code: 'long_checks', message: 'Long-running checks require durable continuation.' });
+  if (input.intent.requiresLongRunningChecks) reasons.push({ code: 'long_checks', message: 'Long-running checks may use a lightweight handle; duration alone does not require durable Work.' });
   if (input.intent.requiresInvestigation) reasons.push({ code: 'investigation', message: 'Investigation is required before or during implementation.' });
   if (input.intent.needsDependencies) reasons.push({ code: 'dependencies', message: 'Dependency ordering requires durable Work.' });
   if (coordinationRequired) reasons.push({ code: 'independent_deliverables', message: 'Multiple independent deliverables require durable PlanContract/Work coordination.' });
 
   const explicitBoundedMode = explicitMode === 'plan'
-    || explicitMode === 'debug'
-    || explicitMode === 'review'
     || explicitMode === 'release';
   const complex = explicitMode === 'direct'
     ? false
@@ -320,11 +313,9 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
     || input.capabilities.requiresWorker === true
     || input.capabilities.requiresExternalEffect === true
     || input.intent.needsDependencies === true
-    || protectedPath
     || destructive
     || remoteWrite
-    || secretAccess
-    || (mutation && (expectedFiles > 4 || expectedChangedLines > 200));
+    || secretAccess;
   const executionMode: RouteExecutionMode = complex ? 'goal_workloop' : 'direct_control';
   // Work topology is independent from executor/provider choice. Independent or
   // parallel deliverables stay in the durable Goal Workloop and are decomposed by

package/src/runtime/control-plane/runtime-status-client.ts

@@ -1,6 +1,5 @@
 import { resolveControllerHome } from '../../cli/repositories/controller-home';
 import { readSchedulerHealthSnapshot } from './global-scheduler/scheduler';
-import type { ControllerStartupRecoveryResult } from './startup-recovery';
 import type { RuntimeSourceIdentity } from './runtime-generation';
 import { readRuntimeOwner } from '../root/ownership';
 import { observeRuntimeStatus } from '../root/status';
@@ -26,7 +25,6 @@ export interface ForgeRuntimeStatus {
   gatewaySeparated?: boolean;
   workerIsolation?: boolean;
   degraded?: boolean;
-  recovery?: ControllerStartupRecoveryResult;
   generation?: string;
   source?: RuntimeSourceIdentity;
   restartRequired?: boolean;

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

@@ -7,6 +7,10 @@ export interface McpTimingTrace {
   traceId?: string;
   requestId?: string;
   rpcId?: string | number;
+  /** Public Connector ingress versus the authoritative loopback Runtime span. */
+  layer?: 'public_gateway' | 'canonical_runtime';
+  /** Wall-clock start for joining nested spans and later client-side timing when available. */
+  startedAt?: string;
   outcome?: 'ok' | 'error' | 'exception';
   errorCode?: string;
   sessionResolutionMs?: number;
@@ -17,10 +21,25 @@ export interface McpTimingTrace {
   commandExecutionMs?: number;
   resultSerializationMs?: number;
   resultPersistenceMs?: number;
+  /** Public Gateway only: resolve current Canonical Runtime identity/token/endpoint. */
+  gatewayProxyResolveMs?: number;
+  /** Public Gateway only: establish or await a Canonical Runtime MCP client connection. */
+  gatewayProxyConnectMs?: number;
+  /** Public Gateway only: MCP call duration after a client is acquired, including Canonical Runtime work. */
+  gatewayProxyCallMs?: number;
+  /** Public Gateway only: time from forwarding the tool call until the Canonical Runtime handler starts. */
+  gatewayProxyCanonicalDispatchLagMs?: number;
+  /** Canonical Runtime server duration projected back through the proxy response. */
+  gatewayProxyCanonicalDurationMs?: number;
+  /** Public Gateway only: response/transport tail after canonical handler completion. */
+  gatewayProxyReturnMs?: number;
+  gatewayProxyConnectionState?: 'reused' | 'cold_connect' | 'coalesced_connect' | 'identity_reconnect';
   totalToolDurationMs: number;
   sessionId?: string;
   repoId?: string;
   workId?: string;
+  processId?: string;
+  route?: string;
 }
 
 export interface McpIncident {

package/src/runtime/diagnostics/mcp-transport-benchmark.ts

@@ -0,0 +1,129 @@
+export type McpTransportTimingScope = 'tool_call' | 'connect_and_tool_call';
+
+export interface McpTransportLatencySample {
+  label: string;
+  tool: string;
+  timingScope?: McpTransportTimingScope;
+  clientTotalMs: number;
+  serverDurationMs: number;
+  traceId?: string;
+  requestId?: string;
+  observedAt?: string;
+}
+
+export interface McpTransportLatencyStats {
+  p50: number;
+  p95: number;
+  max: number;
+}
+
+export interface McpTransportLatencyGroup {
+  label: string;
+  tool: string;
+  timingScope: McpTransportTimingScope;
+  sampleCount: number;
+  clientTotalMs: McpTransportLatencyStats;
+  serverDurationMs: McpTransportLatencyStats;
+  externalResidualMs: McpTransportLatencyStats;
+  externalSharePct: McpTransportLatencyStats;
+  serverExceedsClientCount: number;
+}
+
+export interface McpTransportLatencyReport {
+  schemaVersion: 1;
+  sampleCount: number;
+  groups: McpTransportLatencyGroup[];
+}
+
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function percentile(values: number[], fraction: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1));
+  return round(sorted[index]!);
+}
+
+function stats(values: number[]): McpTransportLatencyStats {
+  return {
+    p50: percentile(values, 0.5),
+    p95: percentile(values, 0.95),
+    max: round(Math.max(...values, 0)),
+  };
+}
+
+function validDuration(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+export function normalizeMcpTransportLatencySample(value: unknown): McpTransportLatencySample {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: sample must be an object');
+  }
+  const record = value as Record<string, unknown>;
+  const label = typeof record.label === 'string' ? record.label.trim() : '';
+  const tool = typeof record.tool === 'string' ? record.tool.trim() : '';
+  const timingScope = record.timingScope === undefined || record.timingScope === 'tool_call'
+    ? 'tool_call'
+    : record.timingScope === 'connect_and_tool_call'
+      ? 'connect_and_tool_call'
+      : undefined;
+  if (!label) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: label is required');
+  if (!tool) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: tool is required');
+  if (!timingScope) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: timingScope must be tool_call or connect_and_tool_call');
+  if (!validDuration(record.clientTotalMs)) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: clientTotalMs must be a non-negative finite number');
+  if (!validDuration(record.serverDurationMs)) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: serverDurationMs must be a non-negative finite number');
+  return {
+    label,
+    tool,
+    timingScope,
+    clientTotalMs: record.clientTotalMs,
+    serverDurationMs: record.serverDurationMs,
+    ...(typeof record.traceId === 'string' && record.traceId.trim() ? { traceId: record.traceId.trim() } : {}),
+    ...(typeof record.requestId === 'string' && record.requestId.trim() ? { requestId: record.requestId.trim() } : {}),
+    ...(typeof record.observedAt === 'string' && record.observedAt.trim() ? { observedAt: record.observedAt.trim() } : {}),
+  };
+}
+
+export function extractForgeServerDuration(result: unknown): number | undefined {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return undefined;
+  const structured = (result as Record<string, unknown>).structuredContent;
+  if (!structured || typeof structured !== 'object' || Array.isArray(structured)) return undefined;
+  const responseMeta = (structured as Record<string, unknown>).responseMeta;
+  if (!responseMeta || typeof responseMeta !== 'object' || Array.isArray(responseMeta)) return undefined;
+  const duration = (responseMeta as Record<string, unknown>).serverDurationMs;
+  return validDuration(duration) ? duration : undefined;
+}
+
+export function aggregateMcpTransportLatencySamples(values: unknown[]): McpTransportLatencyReport {
+  const samples = values.map(normalizeMcpTransportLatencySample);
+  const grouped = new Map<string, McpTransportLatencySample[]>();
+  for (const sample of samples) {
+    const key = `${sample.label}\u0000${sample.tool}\u0000${sample.timingScope ?? 'tool_call'}`;
+    const entries = grouped.get(key) ?? [];
+    entries.push(sample);
+    grouped.set(key, entries);
+  }
+  const groups = [...grouped.values()].map((entries): McpTransportLatencyGroup => {
+    const client = entries.map((sample) => sample.clientTotalMs);
+    const server = entries.map((sample) => sample.serverDurationMs);
+    const residual = entries.map((sample) => Math.max(0, sample.clientTotalMs - sample.serverDurationMs));
+    const share = entries.map((sample, index) => client[index]! > 0 ? residual[index]! / client[index]! * 100 : 0);
+    return {
+      label: entries[0]!.label,
+      tool: entries[0]!.tool,
+      timingScope: entries[0]!.timingScope ?? 'tool_call',
+      sampleCount: entries.length,
+      clientTotalMs: stats(client),
+      serverDurationMs: stats(server),
+      externalResidualMs: stats(residual),
+      externalSharePct: stats(share),
+      serverExceedsClientCount: entries.filter((sample) => sample.serverDurationMs > sample.clientTotalMs).length,
+    };
+  }).sort((left, right) => left.label.localeCompare(right.label)
+    || left.tool.localeCompare(right.tool)
+    || left.timingScope.localeCompare(right.timingScope));
+  return { schemaVersion: 1, sampleCount: samples.length, groups };
+}

package/src/runtime/diagnostics/performance.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from 'child_process';
-import { existsSync, lstatSync, readdirSync, rmSync } from 'fs';
+import { existsSync, lstatSync, readdirSync, rmSync, statfsSync } from 'fs';
 import { tmpdir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
 
@@ -46,6 +46,7 @@ export interface RuntimePerformanceDiagnostics {
   };
   processes: RuntimeProcessSample[];
   temp: { scannedRoots: string[]; totalEntries: number; cleanupCandidates: number; entries: RuntimeTempEntry[] };
+  storage: { availableBytes?: number; availableGiB?: number; pressure: 'normal' | 'warning' | 'critical' | 'unknown'; managedCacheRoots: string[] };
   cleanupPreview?: { safeToTerminate: RuntimeProcessSample[]; safeToRemoveTempEntries: RuntimeTempEntry[]; requiresConfirmation: true };
   truncated: {
     summary: boolean;
@@ -322,7 +323,27 @@ 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 managedCacheRoots = [
+    join(input.repoRoot, '.forge', 'ios', 'DerivedData'),
+    join(input.repoRoot, '.ai', 'harness'),
+    join(input.repoRoot, '.repo-harness'),
+  ].filter((path) => existsSync(path));
   const findings: RuntimePerformanceDiagnostics['findings'] = [];
+  if (storagePressure === 'critical') findings.push({ severity: 'critical', code: 'LOW_DISK_SPACE', message: `Only ${availableGiB} GiB of repository volume space is available.` });
+  else if (storagePressure === 'warning') findings.push({ severity: 'warning', code: 'LOW_DISK_SPACE', message: `Repository volume free space is ${availableGiB} GiB.` });
   if (orphanWorkers.length > 0) findings.push({ severity: orphanWorkers.length >= 3 ? 'critical' : 'warning', code: 'ORPHAN_WORKERS', message: 'Detected ' + orphanWorkers.length + ' orphan worker process(es).' });
   const totalCpu = Math.round(repoProcesses.reduce((sum, process) => sum + process.cpu, 0) * 10) / 10;
   if (totalCpu >= 100 || highCpu.length >= 3) findings.push({ severity: 'warning', code: 'HIGH_FORGE_CPU', message: 'Forge-related CPU is ' + totalCpu + '%.' });
@@ -341,6 +362,7 @@ export function collectRuntimePerformanceDiagnostics(input: DiagnosticsInput): R
     ...(orphanWorkers.length ? ['Terminate orphan workers only after reviewing cleanupPreview.safeToTerminate.'] : []),
     ...(tempCleanupCandidates.length ? ['Remove stale temp entries through runtime_maintenance_apply after reviewing cleanupPreview.safeToRemoveTempEntries.'] : []),
     ...(highCpu.length ? ['Inspect highCpuProcesses before restarting the controller stack.'] : []),
+    ...(storagePressure === 'critical' ? ['Allow Forge generated-cache retention to reclaim stale DerivedData before starting another heavy iOS verification.'] : []),
   ];
   return {
     schemaVersion: 1,
@@ -358,6 +380,7 @@ export function collectRuntimePerformanceDiagnostics(input: DiagnosticsInput): R
       cleanupCandidates: tempCleanupCandidates.length,
       entries: temp.entries.slice(0, MAX_DIAGNOSTIC_TEMP_ENTRIES),
     },
+    storage: { availableBytes, availableGiB, pressure: storagePressure, managedCacheRoots },
     cleanupPreview: input.cleanupPreview === true
       ? {
         safeToTerminate: rawCleanupProcesses,

package/src/runtime/evidence/event-ledger.ts

@@ -18,7 +18,7 @@ export interface RuntimeEntityEvent {
   eventId: string;
   eventType: string;
   repoId: string;
-  entityType: 'job' | 'plugin' | 'schedule' | 'occurrence' | 'portfolio' | 'candidate-finding' | 'release' | 'lease' | 'schedule-decision' | 'assistant-action-proposal' | 'assistant-standing-grant';
+  entityType: 'job' | 'plugin' | 'schedule' | 'occurrence' | 'portfolio' | 'release' | 'lease' | 'schedule-decision';
   entityId: string;
   correlationId?: string;
   causationId?: string;

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

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'crypto';
 import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { ensureControllerHome, ensureRepositoryControllerLayout, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
-import { withControllerLock } from '../../../cli/repositories/locks';
+import { releaseControllerLock, tryAcquireControllerLock, withControllerLock } from '../../../cli/repositories/locks';
 import { appendJobEvent } from '../../evidence/event-ledger';
 import { writeExecutionArtifact } from '../../evidence/artifact-store';
 import { markRepositoryProjectionDirty } from '../../projections/invalidation';
@@ -206,7 +206,9 @@ function writeActiveIndex(controllerHome: string, index: ActiveJobIndex): void {
   writeJsonAtomic(activeIndexPath(controllerHome), {
     schemaVersion: 1,
     updatedAt: now(),
-    jobs: [...deduped.values()].sort((a, b) => a.queuedAt.localeCompare(b.queuedAt)).slice(-5000),
+    // Active work is correctness state, not a presentation window. Dropping an
+    // entry here makes Scheduler/recovery reads forget a durable non-terminal Job.
+    jobs: [...deduped.values()].sort((a, b) => a.queuedAt.localeCompare(b.queuedAt)),
   } satisfies ActiveJobIndex);
 }
 
@@ -258,7 +260,9 @@ export function rebuildExecutionJobIndexes(controllerHome: string, repoIds: stri
     for (const repoId of targetRepos) {
       const records = join(executionJobRoot(controllerHome, repoId), 'records');
       let names: string[] = [];
-      try { names = readdirSync(records).filter((name) => name.endsWith('.json')).slice(0, 5000); } catch { continue; }
+      // Startup repair must rebuild every active and request authority. Only the
+      // recent-history projection below is intentionally bounded.
+      try { names = readdirSync(records).filter((name) => name.endsWith('.json')); } catch { continue; }
       for (const name of names) {
         try {
           const job = readJsonFile<ExecutionJob>(join(records, name));
@@ -648,11 +652,61 @@ export function listActiveExecutionJobs(controllerHome: string, repoId?: string)
     try {
       const job = getExecutionJob(controllerHome, entry.repoId, entry.jobId);
       if (ACTIVE_JOB_STATUSES.has(job.status)) output.push(job);
-    } catch { /* stale index repaired below */ }
+    } catch { /* maintenance reconciliation owns stale-index repair */ }
   }
   return output;
 }
 
+/**
+ * Maintenance-only active-index convergence. The active index itself is the
+ * bounded candidate set; this never scans historical Job directories. Ordinary
+ * read APIs remain side-effect free, while the Scheduler can remove terminal or
+ * missing entries once and make subsequent idle reads genuinely cheap.
+ */
+export function reconcileActiveExecutionJobIndex(
+  controllerHome: string,
+  repoId?: string,
+): ExecutionJob[] {
+  const key = { scope: 'global' as const, resource: 'execution-index' };
+  const owner = `execution-index-active-reconcile:${repoId ?? 'all'}`;
+  const acquired = tryAcquireControllerLock(controllerHome, key, owner);
+  if (!acquired.acquired) return listActiveExecutionJobs(controllerHome, repoId);
+  try {
+    const index = readActiveIndex(controllerHome);
+    const jobs: ExecutionJob[] = [];
+    const retained: ActiveJobIndex['jobs'] = [];
+    let removed = 0;
+    for (const entry of index.jobs) {
+      if (repoId && entry.repoId !== repoId) {
+        retained.push(entry);
+        continue;
+      }
+      try {
+        const job = getExecutionJob(controllerHome, entry.repoId, entry.jobId);
+        if (!ACTIVE_JOB_STATUSES.has(job.status)) {
+          removed += 1;
+          continue;
+        }
+        jobs.push(job);
+        retained.push({
+          jobId: job.jobId,
+          repoId: job.repoId,
+          status: job.status,
+          priority: job.priority,
+          queuedAt: job.queuedAt,
+          updatedAt: job.updatedAt,
+        });
+      } catch {
+        removed += 1;
+      }
+    }
+    if (removed > 0) writeActiveIndex(controllerHome, { ...index, jobs: retained });
+    return jobs;
+  } finally {
+    releaseControllerLock(controllerHome, key, acquired.lock.lockId);
+  }
+}
+
 function executionJobApprovalRequestId(job: ExecutionJob): string | undefined {
   if (typeof job.result?.approvalRequestId === 'string') return job.result.approvalRequestId;
   const authorization = job.result?.authorization;

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

@@ -45,7 +45,7 @@ export interface ResourceClaimSpec {
 }
 
 export interface ExecutionJobOrigin {
-  surface: 'mcp' | 'local-ui' | 'mobile-intent' | 'chatgpt-action' | 'assistant-routine' | 'standing-grant' | 'cli' | 'schedule' | 'reconciliation' | 'system';
+  surface: 'mcp' | 'local-ui' | 'mobile-intent' | 'chatgpt-action' | 'cli' | 'schedule' | 'reconciliation' | 'system';
   actor?: string;
   correlationId?: string;
   causationId?: string;