@moretea-labs/forge 1.7.0 → 1.7.1

package/src/runtime/control-plane/launcher/launch-reservation-store.ts

@@ -5,6 +5,7 @@ import {
   writeControlPlaneRecord,
 } from '../persistence/sqlite-store';
 import type { ControllerType } from '../facade/types';
+import { redactProcessOutput } from '../../../effects/process-runner';
 
 const NAMESPACE = 'external_controller_launch_reservation';
 const DEFAULT_TTL_MS = 2 * 60_000;
@@ -24,6 +25,9 @@ export interface ExternalControllerLaunchReservation {
   exitSignal?: string;
   releasedAt?: string;
   releaseReason?: string;
+  /** Bounded, redacted provider output captured only during launcher startup. */
+  stdoutTail?: string;
+  stderrTail?: string;
 }
 
 export interface LaunchReservationStoreOptions {
@@ -57,6 +61,14 @@ export function getExternalControllerLaunchReservation(
   return active(record(options, workId)?.value);
 }
 
+/** Read the latest reservation record including released/failed startup evidence. */
+export function readExternalControllerLaunchReservationRecord(
+  options: LaunchReservationStoreOptions,
+  workId: string,
+): ExternalControllerLaunchReservation | undefined {
+  return record(options, workId)?.value;
+}
+
 export function reserveExternalControllerLaunch(
   options: LaunchReservationStoreOptions,
   input: {
@@ -131,11 +143,43 @@ export function attachExternalControllerLaunchPid(
   );
 }
 
+export function recordExternalControllerLaunchDiagnostics(
+  options: LaunchReservationStoreOptions,
+  workId: string,
+  reservationId: string,
+  diagnostics: { stdoutTail?: string; stderrTail?: string },
+): ExternalControllerLaunchReservation | undefined {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-launch-${workId}` },
+    `controller-launch-diagnostics:${reservationId}`,
+    () => {
+      const existing = record(options, workId);
+      if (!existing || existing.value.reservationId !== reservationId) return existing?.value;
+      const next: ExternalControllerLaunchReservation = {
+        ...existing.value,
+        ...(diagnostics.stdoutTail ? { stdoutTail: redactProcessOutput(diagnostics.stdoutTail).slice(-8 * 1024) } : {}),
+        ...(diagnostics.stderrTail ? { stderrTail: redactProcessOutput(diagnostics.stderrTail).slice(-8 * 1024) } : {}),
+      };
+      writeControlPlaneRecord(options.controllerHome, {
+        namespace: NAMESPACE,
+        scope: options.repoId,
+        key: workId,
+        schemaVersion: 1,
+        value: next,
+        action: 'external_controller_launch_diagnostics',
+        expectedRevision: existing.revision,
+      });
+      return next;
+    },
+  );
+}
+
 export function recordExternalControllerLaunchExit(
   options: LaunchReservationStoreOptions,
   workId: string,
   reservationId: string,
-  exit: { exitCode: number | null; signal: string | null },
+  exit: { exitCode: number | null; signal: string | null; stdoutTail?: string; stderrTail?: string },
 ): ExternalControllerLaunchReservation | undefined {
   return withControllerLock(
     options.controllerHome,
@@ -143,16 +187,21 @@ export function recordExternalControllerLaunchExit(
     `controller-launch-exit:${reservationId}`,
     () => {
       const existing = record(options, workId);
-      if (!existing || existing.value.reservationId !== reservationId || existing.value.releasedAt) return existing?.value;
+      if (!existing || existing.value.reservationId !== reservationId) return existing?.value;
       const exitedAt = nowIso(options);
+      const alreadyReleased = Boolean(existing.value.releasedAt);
       const next: ExternalControllerLaunchReservation = {
         ...existing.value,
-        expiresAt: exitedAt,
+        expiresAt: alreadyReleased ? existing.value.expiresAt : exitedAt,
         exitedAt,
         ...(exit.exitCode === null ? {} : { exitCode: exit.exitCode }),
         ...(exit.signal ? { exitSignal: exit.signal } : {}),
-        releasedAt: exitedAt,
-        releaseReason: `process_exit:code=${String(exit.exitCode ?? 'null')}:signal=${exit.signal ?? 'none'}`.slice(0, 240),
+        ...(exit.stdoutTail ? { stdoutTail: redactProcessOutput(exit.stdoutTail).slice(-8 * 1024) } : {}),
+        ...(exit.stderrTail ? { stderrTail: redactProcessOutput(exit.stderrTail).slice(-8 * 1024) } : {}),
+        ...(alreadyReleased ? {} : {
+          releasedAt: exitedAt,
+          releaseReason: `process_exit:code=${String(exit.exitCode ?? 'null')}:signal=${exit.signal ?? 'none'}`.slice(0, 240),
+        }),
       };
       writeControlPlaneRecord(options.controllerHome, {
         namespace: NAMESPACE,

package/src/runtime/control-plane/launcher/thin-launcher.ts

@@ -7,6 +7,7 @@ import {
 } from '../facade';
 import {
   attachExternalControllerLaunchPid,
+  recordExternalControllerLaunchDiagnostics,
   recordExternalControllerLaunchExit,
   releaseExternalControllerLaunchReservation,
   reserveExternalControllerLaunch,
@@ -16,6 +17,7 @@ import { getControllerSession } from '../facade/controller-session-store';
 import { codexMcpConfigArgs, resolveProviderMcpBootstrap, type ProviderMcpBootstrap } from './provider-mcp-bootstrap';
 import { getChatgptWorkConversationBinding } from './chatgpt-work-binding-store';
 import { repositoryChildProcessEnvironment } from '../../shared/process-environment';
+import { redactProcessOutput } from '../../../effects/process-runner';
 
 export interface ThinLauncherRequest {
   controllerType: Exclude<ControllerType, 'human'>;
@@ -47,7 +49,22 @@ export interface ThinLauncherResult {
 
 const LAUNCHER_STARTUP_GRACE_MS = 250;
 const CODEX_WORK_CLAIM_TIMEOUT_MS = 30_000;
+const CODEX_WORK_CLAIM_SETTLEMENT_GRACE_MS = 1_500;
 const CODEX_WORK_CLAIM_POLL_INTERVAL_MS = 100;
+const STARTUP_DIAGNOSTIC_BYTES = 8 * 1024;
+
+function appendStartupDiagnosticTail(current: string, chunk: unknown): string {
+  const text = redactProcessOutput(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk ?? ''));
+  const buffer = Buffer.from(`${current}${text}`, 'utf8');
+  return buffer.length <= STARTUP_DIAGNOSTIC_BYTES
+    ? buffer.toString('utf8')
+    : buffer.subarray(buffer.length - STARTUP_DIAGNOSTIC_BYTES).toString('utf8');
+}
+
+function startupDiagnosticSummary(stdoutTail: string, stderrTail: string): string {
+  const value = redactProcessOutput(stderrTail.trim() || stdoutTail.trim()).replace(/\s+/g, ' ').slice(0, 1200);
+  return value ? `; startup_output=${value}` : '';
+}
 
 interface ExternalControllerClaimExpectation {
   controllerType: 'codex';
@@ -59,6 +76,7 @@ interface ExternalControllerClaimExpectation {
 export interface ThinLauncherDependencies {
   resolveProviderMcpBootstrap?: typeof resolveProviderMcpBootstrap;
   claimTimeoutMs?: number;
+  claimSettlementGraceMs?: number;
   claimPollIntervalMs?: number;
 }
 
@@ -102,11 +120,31 @@ async function awaitExternalControllerStartup(
   workId: string,
   reservationId: string,
   claimExpectation?: ExternalControllerClaimExpectation,
-  options: { claimTimeoutMs?: number; claimPollIntervalMs?: number } = {},
+  options: { claimTimeoutMs?: number; claimSettlementGraceMs?: number; claimPollIntervalMs?: number } = {},
 ): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     let startupSettled = false;
     let timer: ReturnType<typeof setTimeout> | undefined;
+    let stdoutTail = '';
+    let stderrTail = '';
+    const captureStdout = (chunk: unknown) => { stdoutTail = appendStartupDiagnosticTail(stdoutTail, chunk); };
+    const captureStderr = (chunk: unknown) => { stderrTail = appendStartupDiagnosticTail(stderrTail, chunk); };
+    child.stdout?.on('data', captureStdout);
+    child.stderr?.on('data', captureStderr);
+    const closeStartupPipes = () => {
+      child.stdout?.off('data', captureStdout);
+      child.stderr?.off('data', captureStderr);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+    };
+    const persistDiagnostics = () => {
+      if (!stdoutTail && !stderrTail) return;
+      try {
+        recordExternalControllerLaunchDiagnostics(stores.work, workId, reservationId, { stdoutTail, stderrTail });
+      } catch {
+        // Startup diagnostics are evidence only; preserve the primary ownership/claim outcome.
+      }
+    };
     const clearTimer = () => {
       if (timer) clearTimeout(timer);
       timer = undefined;
@@ -126,9 +164,12 @@ async function awaitExternalControllerStartup(
       if (startupSettled) return;
       startupSettled = true;
       clearTimer();
+      persistDiagnostics();
+      closeStartupPipes();
       if (terminate) terminateUnclaimedChild();
       releaseFailure(reason);
-      reject(error);
+      const diagnostics = startupDiagnosticSummary(stdoutTail, stderrTail);
+      reject(diagnostics ? new Error(`${error.message}${diagnostics}`) : error);
     };
     const expectedClaimMatches = (): { matches: boolean; mismatch?: string } => {
       if (!claimExpectation) return { matches: true };
@@ -156,6 +197,8 @@ async function awaitExternalControllerStartup(
         recordExternalControllerLaunchExit(stores.work, workId, reservationId, {
           exitCode,
           signal: signal ? String(signal) : null,
+          stdoutTail,
+          stderrTail,
         });
       } catch {
         // Exit evidence is best-effort after another authority has already released the reservation.
@@ -163,22 +206,26 @@ async function awaitExternalControllerStartup(
       if (startupSettled) return;
       startupSettled = true;
       clearTimer();
+      closeStartupPipes();
       const phase = claimExpectation ? 'before exact Work claim became live' : 'during startup grace';
-      reject(new Error(`LAUNCHER_STARTUP_FAILED: external Controller exited ${phase} (code=${String(exitCode ?? 'null')}, signal=${signal ?? 'none'})`));
+      reject(new Error(`LAUNCHER_STARTUP_FAILED: external Controller exited ${phase} (code=${String(exitCode ?? 'null')}, signal=${signal ?? 'none'})${startupDiagnosticSummary(stdoutTail, stderrTail)}`));
     });
 
     if (!claimExpectation) {
       timer = setTimeout(() => {
         if (startupSettled) return;
         startupSettled = true;
+        closeStartupPipes();
         resolve();
       }, LAUNCHER_STARTUP_GRACE_MS);
       return;
     }
 
     const claimTimeoutMs = Math.max(100, Math.min(options.claimTimeoutMs ?? CODEX_WORK_CLAIM_TIMEOUT_MS, 60_000));
+    const claimSettlementGraceMs = Math.max(0, Math.min(options.claimSettlementGraceMs ?? CODEX_WORK_CLAIM_SETTLEMENT_GRACE_MS, 5_000));
     const claimPollIntervalMs = Math.max(10, Math.min(options.claimPollIntervalMs ?? CODEX_WORK_CLAIM_POLL_INTERVAL_MS, 1_000));
     const claimDeadline = Date.now() + claimTimeoutMs;
+    const claimSettlementDeadline = claimDeadline + claimSettlementGraceMs;
     const pollClaim = () => {
       if (startupSettled) return;
       let observation: ReturnType<typeof expectedClaimMatches>;
@@ -213,14 +260,15 @@ async function awaitExternalControllerStartup(
           }
           startupSettled = true;
           timer = undefined;
+          closeStartupPipes();
           resolve();
         }, LAUNCHER_STARTUP_GRACE_MS);
         return;
       }
-      if (Date.now() >= claimDeadline) {
+      if (Date.now() >= claimSettlementDeadline) {
         fail(
-          new Error(`LAUNCHER_CLAIM_TIMEOUT: Codex pid=${String(child.pid ?? 'unknown')} did not claim exact Work ${workId} through Forge MCP within ${claimTimeoutMs}ms`),
-          `claim_timeout:${claimTimeoutMs}ms`,
+          new Error(`LAUNCHER_CLAIM_TIMEOUT: Codex pid=${String(child.pid ?? 'unknown')} did not claim exact Work ${workId} through Forge MCP within ${claimTimeoutMs}ms plus ${claimSettlementGraceMs}ms settlement grace`),
+          `claim_timeout:${claimTimeoutMs}ms+${claimSettlementGraceMs}ms_settlement`,
           true,
         );
         return;
@@ -345,7 +393,7 @@ export async function launchSuperController(
     const child = spawn(invocation.executable, invocation.args, {
       cwd: request.cwd,
       detached: true,
-      stdio: 'ignore',
+      stdio: ['ignore', 'pipe', 'pipe'],
       env: launcherProcessEnvironment(mcpBootstrap?.env ?? process.env),
     });
     attachExternalControllerLaunchPid(stores.work, work.workId, reservation.reservationId, child.pid);
@@ -362,6 +410,7 @@ export async function launchSuperController(
       } : undefined,
       {
         claimTimeoutMs: dependencies.claimTimeoutMs,
+        claimSettlementGraceMs: dependencies.claimSettlementGraceMs,
         claimPollIntervalMs: dependencies.claimPollIntervalMs,
       },
     );

package/src/runtime/control-plane/persistence/requirement-store.ts

@@ -165,18 +165,6 @@ export function updateRequirement(
   });
 }
 
-/** @deprecated Migration/legacy compatibility only. New Plan creation must bind Plan.requirementId and derive active Plan slices by query. */
-export function setRequirementPlan(
-  options: RequirementStoreOptions,
-  input: { requirementId: string; planId: string; action?: string },
-): Requirement {
-  return updateRequirement(options, {
-    requirementId: input.requirementId,
-    action: input.action ?? 'requirement_active_plan_bound',
-    mutate: (current) => ({ ...current, activePlanId: id(input.planId) }),
-  });
-}
-
 export interface RequirementCompletionInput {
   requirementId: string;
   work: Pick<WorkContract,

package/src/runtime/control-plane/repo-actor/registry.ts

@@ -2,16 +2,18 @@ import { RepoActor } from './actor';
 
 export class RepoActorRegistry {
   private readonly controllerHome: string;
+  private readonly defaultMaxConcurrentWorkers: number;
   private readonly actors = new Map<string, RepoActor>();
-  constructor(controllerHome: string) {
+  constructor(controllerHome: string, options: { maxConcurrentWorkers?: number } = {}) {
     this.controllerHome = controllerHome;
+    this.defaultMaxConcurrentWorkers = Math.max(1, options.maxConcurrentWorkers ?? 4);
   }
 
   get(repoId: string): RepoActor {
     let actor = this.actors.get(repoId);
     if (!actor) {
       actor = new RepoActor(this.controllerHome, repoId, {
-        maxConcurrentWorkers: Number(process.env.FORGE_PER_REPO_WORKERS ?? 2),
+        maxConcurrentWorkers: Number(process.env.FORGE_PER_REPO_WORKERS ?? this.defaultMaxConcurrentWorkers),
       });
       this.actors.set(repoId, actor);
     }

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

@@ -1,6 +1,6 @@
 import { createHash } from 'crypto';
 
-export const ROUTE_POLICY_VERSION = 'route-policy-v4' as const;
+export const ROUTE_POLICY_VERSION = 'route-policy-v5' as const;
 
 export type RouteExecutionMode = 'direct_control' | 'goal_workloop' | 'handoff_only';
 export type RouteWorkMode = 'direct_edit' | 'bounded_work' | 'quick_agent' | 'issue_task';
@@ -50,6 +50,10 @@ export interface RoutePolicyInput {
     dirty?: boolean;
     checkoutId?: string;
     fingerprint?: string;
+    /** Canonical typed placement constraint resolved before routing. */
+    placement?: 'current' | 'isolated' | 'auto';
+    /** Admission fence: Direct Control/current-main mutation is not permitted. */
+    directMainProhibited?: boolean;
   };
   policy: {
     risk?: string;
@@ -234,9 +238,11 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
   const protectedPath = paths.some((path) => PROTECTED_PATH.test(path));
   const explicitMode = input.intent.explicitMode;
   const explicitParallelMode = explicitMode === 'scale';
-  const requiresIsolation = explicitMode === 'direct'
-    ? false
-    : input.recovery.isolationRequired === true || explicitParallelMode;
+  const placementIsolationRequired = input.workspace.placement === 'isolated'
+    || input.workspace.directMainProhibited === true;
+  const requiresIsolation = placementIsolationRequired
+    || input.recovery.isolationRequired === true
+    || explicitParallelMode;
   const requiresRecovery = input.recovery.required === true
     || explicitMode === 'release'
     || explicitMode === 'scale';
@@ -295,6 +301,8 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
   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 (input.workspace.placement === 'isolated') reasons.push({ code: 'placement_isolated', message: 'Typed Work admission requires an isolated workspace.' });
+  if (input.workspace.directMainProhibited === true) reasons.push({ code: 'direct_main_prohibited', message: 'Typed Work admission forbids the Direct Control/current-main mutation lane.' });
   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 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.' });
@@ -303,7 +311,11 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
 
   const explicitBoundedMode = explicitMode === 'plan'
     || explicitMode === 'release';
-  const complex = explicitMode === 'direct'
+  const directModeCanRemainFast = explicitMode === 'direct'
+    && !requiresIsolation
+    && !requiresRecovery
+    && !coordinationRequired;
+  const complex = directModeCanRemainFast
     ? false
     : coordinationRequired
     || explicitBoundedMode
@@ -320,7 +332,7 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
   // Work topology is independent from executor/provider choice. Independent or
   // parallel deliverables stay in the durable Goal Workloop and are decomposed by
   // PlanContract/Work rather than introducing another project-level lifecycle.
-  const workMode: RouteWorkMode = explicitMode === 'direct'
+  const workMode: RouteWorkMode = directModeCanRemainFast
     ? 'direct_edit'
     : coordinationRequired
     ? 'bounded_work'

package/src/runtime/control-plane/routing/workspace-admission.ts

@@ -0,0 +1,70 @@
+export type WorkspacePlacementMode = 'current' | 'isolated' | 'auto';
+
+export interface WorkspaceAdmissionConstraintInput {
+  workspaceMode?: WorkspacePlacementMode;
+  requireWorktree?: boolean;
+  /**
+   * Forbid repository mutation through the current/direct-main lane. This is
+   * an admission constraint, not a routing hint: callers must never silently
+   * downgrade it to Direct Control.
+   */
+  directMainProhibited?: boolean;
+}
+
+export interface WorkspaceAdmissionConstraint {
+  workspaceMode: WorkspacePlacementMode;
+  requireWorktree: boolean;
+  directMainProhibited: boolean;
+  requiresIsolation: boolean;
+}
+
+export type WorkspaceAdmissionResolution =
+  | { ok: true; constraint: WorkspaceAdmissionConstraint }
+  | { ok: false; code: 'WORKSPACE_PLACEMENT_CONSTRAINT_CONFLICT'; message: string };
+
+/**
+ * Canonicalize Work placement before Route Policy runs. Placement is a policy
+ * fence: explicit isolation / direct-main prohibition has precedence over an
+ * operator request for the fast Direct Control topology.
+ */
+export function resolveWorkspaceAdmissionConstraint(
+  input: WorkspaceAdmissionConstraintInput = {},
+): WorkspaceAdmissionResolution {
+  const workspaceMode = input.workspaceMode ?? 'auto';
+  const directMainProhibited = input.directMainProhibited === true;
+
+  if (workspaceMode === 'current' && input.requireWorktree === true) {
+    return {
+      ok: false,
+      code: 'WORKSPACE_PLACEMENT_CONSTRAINT_CONFLICT',
+      message: 'workspaceMode=current conflicts with requireWorktree=true.',
+    };
+  }
+  if (workspaceMode === 'isolated' && input.requireWorktree === false) {
+    return {
+      ok: false,
+      code: 'WORKSPACE_PLACEMENT_CONSTRAINT_CONFLICT',
+      message: 'workspaceMode=isolated conflicts with requireWorktree=false.',
+    };
+  }
+  if (workspaceMode === 'current' && directMainProhibited) {
+    return {
+      ok: false,
+      code: 'WORKSPACE_PLACEMENT_CONSTRAINT_CONFLICT',
+      message: 'workspaceMode=current conflicts with directMainProhibited=true because the current lane cannot prove a non-main placement at admission time.',
+    };
+  }
+
+  const requiresIsolation = workspaceMode === 'isolated'
+    || input.requireWorktree === true
+    || directMainProhibited;
+  return {
+    ok: true,
+    constraint: {
+      workspaceMode: requiresIsolation ? 'isolated' : workspaceMode,
+      requireWorktree: requiresIsolation,
+      directMainProhibited,
+      requiresIsolation,
+    },
+  };
+}

package/src/runtime/evidence/process-check-execution.ts

@@ -0,0 +1,18 @@
+/**
+ * Content-bound Check identity shared by Process Runtime and Work validation.
+ *
+ * This is durable evidence metadata, not Process lifecycle state. Keeping the
+ * contract outside Process Runtime prevents WorkHandle persistence from
+ * depending on the Process implementation layer.
+ */
+export interface ProcessCheckExecutionIdentity {
+  schemaVersion: 1;
+  checkId: string;
+  cacheKey: string;
+  revision: string;
+  definitionDigest: string;
+  environmentFingerprint: string;
+  timeoutMs: number;
+  reuseScope: 'repository' | 'checkout';
+  scopeKey: string;
+}

package/src/runtime/execution/jobs/child-reference.ts

@@ -1,5 +1,9 @@
 import type { ExecutionJob } from './types';
-import type { OperationReceipt } from './receipt-store';
+
+export interface ChildReferenceReceiptLike {
+  childReference?: unknown;
+  result?: Record<string, unknown>;
+}
 
 /** Durable pointer from a short-lived parent Execution Job to its child Agent Run. */
 export interface ExecutionChildReference {
@@ -72,7 +76,7 @@ export function childReferenceFromUnknown(value: unknown): ExecutionChildReferen
   return pickChildReference(value as Record<string, unknown>);
 }
 
-export function childReferenceFromReceipt(receipt: OperationReceipt | undefined): ExecutionChildReference | undefined {
+export function childReferenceFromReceipt(receipt: ChildReferenceReceiptLike | undefined): ExecutionChildReference | undefined {
   if (!receipt) return undefined;
   return childReferenceFromUnknown(receipt.childReference)
     ?? childReferenceFromUnknown(receipt.result);

package/src/runtime/execution/process-runtime/check-result.ts

@@ -66,6 +66,37 @@ export interface PersistedCheckTerminalEvidence {
   infrastructureReason?: string;
 }
 
+export interface TerminalCheckEvidenceClassificationInput {
+  processError?: { code: string; message: string };
+  structuredPresent: boolean;
+  structuredMatches: boolean;
+  legacyPresent: boolean;
+  legacyMatches: boolean;
+}
+
+/**
+ * Compatibility-level classifier for terminal Check evidence. Keep this pure so
+ * legacy/public callers and the Process Runtime record adapter share one semantic
+ * authority instead of carrying duplicate decision trees.
+ */
+export function classifyTerminalCheckEvidence(
+  input: TerminalCheckEvidenceClassificationInput,
+): PersistedCheckTerminalEvidence {
+  if (input.structuredMatches || input.legacyMatches) return { state: 'matched' };
+  if (!input.structuredPresent && !input.legacyPresent && input.processError?.message?.trim()) {
+    const reason = input.processError.message.trim().slice(0, 512);
+    return {
+      state: 'process_runtime_failed_before_result',
+      warning: `check process failed before structured result receipt: ${reason}`,
+      infrastructureReason: reason,
+    };
+  }
+  if (input.structuredPresent || input.legacyPresent) {
+    return { state: 'mismatch', warning: 'check result receipt did not match the terminal Process semantic identity' };
+  }
+  return { state: 'missing', warning: 'check result receipt is missing for the terminal Check Process' };
+}
+
 /**
  * Classify one terminal Check Process using the structured result emitted by
  * the check-runner sidecar. A Process Runtime/admission failure can terminate
@@ -74,9 +105,15 @@ export interface PersistedCheckTerminalEvidence {
  * rejected the candidate. Missing/mismatched result identity also fails closed
  * as infrastructure rather than manufacturing acceptance evidence.
  */
+export interface LegacyCheckEvidenceLike {
+  cacheKey?: string;
+  failureClass?: PersistedCheckResultReceipt['failureClass'];
+}
+
 export function classifyPersistedCheckTerminalEvidence(
   record: ManagedProcessRecord,
   expectedCheckId: string,
+  options: { legacyEvidence?: LegacyCheckEvidenceLike } = {},
 ): PersistedCheckTerminalEvidence {
   const structured = readPersistedCheckResultReceipt(record.origin?.checkResultReceiptPath);
   const structuredMatches = Boolean(
@@ -85,22 +122,20 @@ export function classifyPersistedCheckTerminalEvidence(
     && structured.checkId === expectedCheckId
     && structured.cacheKey === record.checkExecution.cacheKey,
   );
-  if (structuredMatches) {
-    return { state: 'matched', failureClass: structured?.failureClass };
-  }
-  if (!structured && record.error?.message?.trim()) {
-    const reason = record.error.message.trim().slice(0, 512);
-    return {
-      state: 'process_runtime_failed_before_result',
-      warning: `check process failed before structured result receipt: ${reason}`,
-      infrastructureReason: reason,
-    };
-  }
-  if (structured) {
-    return {
-      state: 'mismatch',
-      warning: 'check result receipt did not match the terminal Process semantic identity',
-    };
-  }
-  return { state: 'missing', warning: 'check result receipt is missing for the terminal Check Process' };
+  const legacy = options.legacyEvidence;
+  const legacyMatches = Boolean(
+    legacy?.cacheKey
+    && record.checkExecution?.cacheKey
+    && legacy.cacheKey === record.checkExecution.cacheKey,
+  );
+  const classified = classifyTerminalCheckEvidence({
+    processError: record.error,
+    structuredPresent: Boolean(structured),
+    structuredMatches,
+    legacyPresent: Boolean(legacy),
+    legacyMatches,
+  });
+  return classified.state === 'matched'
+    ? { ...classified, failureClass: structuredMatches ? structured?.failureClass : legacy?.failureClass }
+    : classified;
 }

package/src/runtime/execution/process-runtime/check-runner-sidecar.ts

@@ -16,6 +16,7 @@ interface ParsedArgs {
   expectedCheckFingerprint: string;
   resultReceiptPath?: string;
   cleanupRoot?: string;
+  isolatedControllerHome?: string;
 }
 
 function requiredValue(argv: string[], flag: string): string {
@@ -38,6 +39,7 @@ function parseArgs(argv: string[]): ParsedArgs {
     expectedCheckFingerprint: requiredValue(argv, '--expected-check-fingerprint'),
     resultReceiptPath: argv.includes('--result-receipt') ? requiredValue(argv, '--result-receipt') : undefined,
     cleanupRoot: argv.includes('--cleanup-root') ? requiredValue(argv, '--cleanup-root') : undefined,
+    isolatedControllerHome: argv.includes('--isolated-controller-home') ? requiredValue(argv, '--isolated-controller-home') : undefined,
   };
 }
 
@@ -51,7 +53,11 @@ export async function runPersistedCheckSidecar(argv = process.argv.slice(2)): Pr
       throw new Error('CHECK_SNAPSHOT_CHANGED: registered check changed before Process Runtime execution');
     }
     const identity = controllerCheckExecutionIdentity(root, args.checkId, args.timeoutMs, snapshot);
-    const result = await runControllerCheckAsync(root, args.checkId, { requestedTimeoutMs: args.timeoutMs, snapshot });
+    const result = await runControllerCheckAsync(root, args.checkId, {
+      requestedTimeoutMs: args.timeoutMs,
+      snapshot,
+      isolatedControllerHome: args.isolatedControllerHome,
+    });
     if (args.resultReceiptPath) {
       writePersistedCheckResultReceipt(args.resultReceiptPath, {
         checkId: args.checkId,