@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/evidence/operational-shadow.ts

@@ -0,0 +1,38 @@
+import type { ProcessCheckReceiptEvidence } from '../../../packages/kernel/work/api/index';
+import type { ScopeRef } from '../../../packages/kernel/identity/api/index';
+import { OPERATIONAL_TARGET_DEFINITIONS, type OperationalActionId, type OperationalMetricId, type OperationalObservation, type OperationalOutcomeClass, type OperationalTargetId } from '../../../packages/kernel/memory/api/index';
+import type { ExecutionJob } from '../execution/jobs/types';
+
+export interface OperationalExtractionIdentity {
+  targetId: OperationalTargetId;
+  actionId: OperationalActionId;
+  metricId: OperationalMetricId;
+  scope: ScopeRef;
+  consumerRequestId: string;
+  retainedUntil: string;
+  environmentFingerprint: string;
+}
+function elapsedMs(startedAt:string,finishedAt:string){const start=Date.parse(startedAt),finish=Date.parse(finishedAt);return Number.isFinite(start)&&Number.isFinite(finish)&&finish>=start?finish-start:0}
+function jobOutcomeClass(job:ExecutionJob):OperationalOutcomeClass{
+  if(job.status==='waiting_for_approval')return'admission_wait';
+  if(job.status.startsWith('waiting_for_'))return'contention_wait';
+  if(job.status==='cancelled')return'cancelled';
+  if(job.status==='timed_out')return'timeout';
+  if(job.status==='failed'&&job.outcome?.policy?.decision==='rejected')return'policy_denied';
+  if(job.status==='failed'&&job.outcome?.failureClass==='infrastructure_failure')return'infrastructure_failure';
+  if(job.status==='failed')return'executed_failure';
+  if(job.status==='succeeded')return'executed_success';
+  return'unknown';
+}
+function checkOutcomeClass(receipt:ProcessCheckReceiptEvidence):OperationalOutcomeClass{
+  if(receipt.status==='cancelled')return'cancelled';if(receipt.status==='timed_out')return'timeout';if(receipt.status==='failed')return'unknown';if(receipt.status==='passed')return'executed_success';return'unknown';
+}
+function valueForMetric(metric:OperationalMetricId,outcome:OperationalOutcomeClass,elapsed:number){return metric==='latency_ms'?elapsed:outcome==='executed_success'?1:0}
+export function extractExecutionJobShadowObservation(job:ExecutionJob,identity:OperationalExtractionIdentity):OperationalObservation{
+  const outcomeClass=jobOutcomeClass(job),observedAt=job.finishedAt??job.updatedAt,startAt=job.startedAt??job.queuedAt;
+  return{schemaVersion:1,observationId:`execution_job:${job.jobId}:${job.revision}:${identity.targetId}:${identity.actionId}:${identity.metricId}`,signalId:'execution_job.terminal_mechanical',targetId:identity.targetId,actionId:identity.actionId,metricId:identity.metricId,scope:identity.scope,source:{schema:'execution_job/v1',sourceId:job.jobId,eventKind:job.status,evidenceRef:`execution_job:${job.jobId}:${job.revision}`,requestId:job.requestId,observedAt,retainedUntil:identity.retainedUntil},attribution:{kind:identity.consumerRequestId===job.requestId?'exact':'ambiguous',consumerId:OPERATIONAL_TARGET_DEFINITIONS[identity.targetId].consumerId,requestId:identity.consumerRequestId,sourceId:job.jobId},outcomeClass,value:valueForMetric(identity.metricId,outcomeClass,elapsedMs(startAt,observedAt)),compatibility:{operation:job.payload.operation,environment:identity.environmentFingerprint}};
+}
+export function extractProcessCheckShadowObservation(receipt:ProcessCheckReceiptEvidence,identity:OperationalExtractionIdentity):OperationalObservation{
+  const outcomeClass=checkOutcomeClass(receipt),requestId=receipt.requestId??'';
+  return{schemaVersion:1,observationId:`process_check:${receipt.receiptId}:${identity.targetId}:${identity.actionId}:${identity.metricId}`,signalId:'process_check.terminal_mechanical',targetId:identity.targetId,actionId:identity.actionId,metricId:identity.metricId,scope:identity.scope,source:{schema:'process_check_receipt/v1',sourceId:receipt.receiptId,eventKind:receipt.status,evidenceRef:`process_check_receipt:${receipt.receiptId}`,requestId,observedAt:receipt.finishedAt,retainedUntil:identity.retainedUntil},attribution:{kind:requestId.length>0&&identity.consumerRequestId===requestId?'exact':'ambiguous',consumerId:OPERATIONAL_TARGET_DEFINITIONS[identity.targetId].consumerId,requestId:identity.consumerRequestId,sourceId:receipt.receiptId},outcomeClass,value:valueForMetric(identity.metricId,outcomeClass,elapsedMs(receipt.startedAt,receipt.finishedAt)),compatibility:{operation:`check:${receipt.checkId}`,environment:receipt.checkEnvironmentFingerprint??identity.environmentFingerprint}};
+}

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

@@ -1,43 +1,5 @@
-export type ProcessCheckReceiptStatus = 'passed' | 'failed' | 'timed_out' | 'cancelled';
-export type ProcessCheckReceiptRuntimeStatus = 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
-
-/**
- * Stable, persistence-safe evidence contract shared by Edit Sessions, Work and Tasks.
- * It deliberately contains no execution-runtime implementation types.
- */
-export interface ProcessCheckReceiptEvidence {
-  schemaVersion: 1;
-  receiptId: string;
-  resultDigest: string;
-  repoId: string;
-  checkoutId?: string;
-  workId?: string;
-  executionSessionId?: string;
-  editSessionId?: string;
-  editRevision?: number;
-  issueId?: string;
-  taskId?: string;
-  checkId: string;
-  requestId?: string;
-  processId: string;
-  commandId?: string;
-  /** Physical checkout that executed the Check; differs from checkoutId on safe cross-checkout reuse. */
-  sourceCheckoutId?: string;
-  /** Existing controller-check cache identity proving content/definition/environment equivalence. */
-  checkCacheKey?: string;
-  checkRevision?: string;
-  checkDefinitionDigest?: string;
-  checkEnvironmentFingerprint?: string;
-  /** True when this consumer is bound to a physical Process originally launched by another consumer/checkout. */
-  reusedExecution?: boolean;
-  status: ProcessCheckReceiptStatus;
-  runtimeStatus: ProcessCheckReceiptRuntimeStatus;
-  ok: boolean;
-  exitCode?: number;
-  timedOut: boolean;
-  cancelled: boolean;
-  artifactPath: string;
-  summary: string;
-  startedAt: string;
-  finishedAt: string;
-}
+export type {
+  ProcessCheckReceiptEvidence,
+  ProcessCheckReceiptRuntimeStatus,
+  ProcessCheckReceiptStatus,
+} from '../../../packages/kernel/work/api/index';

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,10 +1,10 @@
 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';
@@ -789,3 +789,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),
+  };
+}

package/src/runtime/execution/managed-workspace.ts

@@ -1,5 +1,5 @@
-import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from 'fs';
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import type { RepositoryRecord } from '../../cli/repositories/types';
@@ -92,8 +92,8 @@ function assertBranch(root: string, branch: string): string {
   return normalized;
 }
 
-export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
-  if (!existsSync(join(repoRoot, 'package.json')) || existsSync(join(repoRoot, 'node_modules'))) return undefined;
+function detectManagedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
+  if (!existsSync(join(repoRoot, 'package.json'))) return undefined;
   const lockCandidates = [
     ['bun', 'bun.lock', ['bun', 'install', '--frozen-lockfile']],
     ['bun', 'bun.lockb', ['bun', 'install', '--frozen-lockfile']],
@@ -106,6 +106,11 @@ export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWo
   return { packageManager: detected[0], lockfile: detected[1], command: [...detected[2]] };
 }
 
+export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
+  if (existsSync(join(repoRoot, 'node_modules'))) return undefined;
+  return detectManagedWorkspaceDependencyBootstrap(repoRoot);
+}
+
 const DEPENDENCY_REUSE_CONFIG_PATHS = [
   '.npmrc',
   'bunfig.toml',
@@ -151,7 +156,7 @@ export function resolveManagedWorkspaceCanonicalDependencies(repoRoot: string):
   canonicalRoot: string;
   nodeModulesRoot: string;
 } | undefined {
-  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  const bootstrap = detectManagedWorkspaceDependencyBootstrap(repoRoot);
   if (!bootstrap) return undefined;
   const canonicalRoot = linkedWorkspaceCanonicalRoot(repoRoot);
   if (!canonicalRoot) return undefined;
@@ -162,6 +167,51 @@ export function resolveManagedWorkspaceCanonicalDependencies(repoRoot: string):
   return { canonicalRoot, nodeModulesRoot: realpathSync(nodeModulesRoot) };
 }
 
+/**
+ * Replace a legacy physical dependency copy with the already-authoritative
+ * canonical dependency tree. The caller must hold repository maintenance
+ * ownership and prove there is no active workspace lease before invoking this
+ * filesystem mutation. A temporary rename gives the operation an exact rollback
+ * point; any link/removal failure restores the original physical directory.
+ */
+export function migrateManagedWorkspacePhysicalDependenciesToCanonical(
+  repoRoot: string,
+): ManagedWorkspaceDependencyPreparation | undefined {
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  if (!existsSync(nodeModulesRoot)) return undefined;
+  const stats = lstatSync(nodeModulesRoot);
+  if (stats.isSymbolicLink()) return undefined;
+  if (!stats.isDirectory()) throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_PATH_INVALID: ${nodeModulesRoot}`);
+  const reusable = resolveManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (!reusable) return undefined;
+
+  const backupRoot = join(repoRoot, `.forge-node-modules-migration-${process.pid}-${randomUUID().slice(0, 8)}`);
+  renameSync(nodeModulesRoot, backupRoot);
+  try {
+    symlinkSync(reusable.nodeModulesRoot, nodeModulesRoot, process.platform === 'win32' ? 'junction' : 'dir');
+    rmSync(backupRoot, { recursive: true, force: true });
+  } catch (error) {
+    let rollbackError: unknown;
+    try {
+      if (existsSync(nodeModulesRoot)) rmSync(nodeModulesRoot, { recursive: true, force: true });
+      if (existsSync(backupRoot)) renameSync(backupRoot, nodeModulesRoot);
+    } catch (rollback) {
+      rollbackError = rollback;
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    if (rollbackError) {
+      const rollbackDetail = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+      throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_MIGRATION_ROLLBACK_FAILED: ${detail}; rollback=${rollbackDetail}`);
+    }
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_MIGRATION_FAILED: ${detail}`);
+  }
+  return {
+    mode: 'canonical_reuse',
+    nodeModulesRoot: realpathSync(nodeModulesRoot),
+    canonicalRoot: reusable.canonicalRoot,
+  };
+}
+
 function packageManifestRequiresDependencyMaterialization(repoRoot: string): boolean {
   const packagePath = join(repoRoot, 'package.json');
   if (!existsSync(packagePath)) return false;

package/src/runtime/execution/process-runtime/canary.ts

@@ -1,26 +1,40 @@
 import { resolve } from 'path';
 
 /**
- * Private child mode used only by the immutable release execution canary.
+ * Private child mode used only by immutable Runtime execution canaries.
  *
  * The canary must not use the parent process' process.execPath: inside a
  * compiled immutable Forge release that path is the packaged Runtime executable,
  * so spawning it would start a second Supervisor and collide on its control
- * port. Reusing the candidate Process Runner with an explicit no-op child mode
- * keeps the probe self-contained and portable.
+ * port. Reusing the candidate Process/Check Runner with an explicit no-op child
+ * mode keeps the probe self-contained and portable.
  */
-export const PROCESS_RUNNER_RELEASE_CANARY_CHILD_ARG = '--forge-release-canary-child';
+export const PROCESS_RUNTIME_RELEASE_CANARY_ARG = '--forge-release-canary-child';
+/** Compatibility name retained for the Process Runner entrypoint and existing callers. */
+export const PROCESS_RUNNER_RELEASE_CANARY_CHILD_ARG = PROCESS_RUNTIME_RELEASE_CANARY_ARG;
 
 export interface ProcessRunnerReleaseCanaryChildCommand {
   executable: string;
   args: string[];
 }
 
+export interface ProcessRuntimeReleaseCanaryCommand extends ProcessRunnerReleaseCanaryChildCommand {
+  name: 'process_runner' | 'check_runner';
+}
+
 export function processRunnerReleaseCanaryChildCommand(
   runnerPath: string,
 ): ProcessRunnerReleaseCanaryChildCommand {
   return {
     executable: resolve(runnerPath),
-    args: [PROCESS_RUNNER_RELEASE_CANARY_CHILD_ARG],
+    args: [PROCESS_RUNTIME_RELEASE_CANARY_ARG],
   };
 }
+
+export function processRuntimeReleaseCanaryCommands(releaseRoot: string): ProcessRuntimeReleaseCanaryCommand[] {
+  const root = resolve(releaseRoot);
+  return [
+    { name: 'process_runner', executable: resolve(root, 'process-runner.js'), args: [PROCESS_RUNTIME_RELEASE_CANARY_ARG] },
+    { name: 'check_runner', executable: resolve(root, 'forge-check-runner'), args: [PROCESS_RUNTIME_RELEASE_CANARY_ARG] },
+  ];
+}

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

@@ -0,0 +1,48 @@
+import {
+  controllerCheckSelection,
+  type ControllerCheck,
+} from '../../../cli/controller/check-runner';
+
+export type ControllerCheckExecutionClass = 'ordinary' | 'release' | 'live_controller_home';
+
+export interface ControllerCheckExecutionClassification {
+  executionClass: ControllerCheckExecutionClass;
+  requiresDurableWorkflow: boolean;
+  reason: 'ordinary_process_check' | 'release_phase' | 'live_controller_home';
+}
+
+/**
+ * Single semantic authority for Check execution placement.
+ *
+ * A caller must supply a registered ControllerCheck. Human-readable ids and
+ * descriptions are not lifecycle authority here. Compatibility inference, when
+ * unavoidable at repository ingress, must already have been normalized into
+ * the ControllerCheck contract before classification reaches this layer.
+ */
+export function classifyControllerCheckExecution(check: ControllerCheck): ControllerCheckExecutionClassification {
+  if (check.executionAuthority === 'live_controller_home') {
+    return {
+      executionClass: 'live_controller_home',
+      requiresDurableWorkflow: true,
+      reason: 'live_controller_home',
+    };
+  }
+
+  if (controllerCheckSelection(check).phases.includes('release')) {
+    return {
+      executionClass: 'release',
+      requiresDurableWorkflow: true,
+      reason: 'release_phase',
+    };
+  }
+
+  return {
+    executionClass: 'ordinary',
+    requiresDurableWorkflow: false,
+    reason: 'ordinary_process_check',
+  };
+}
+
+export function registeredCheckRequiresDurableWorkflow(check?: ControllerCheck): boolean {
+  return check ? classifyControllerCheckExecution(check).requiresDurableWorkflow : false;
+}

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

@@ -8,6 +8,7 @@
  */
 
 import {
+  controllerCheckEnvironmentFingerprint,
   controllerCheckExecutionIdentity,
   listControllerChecks,
   snapshotControllerCheck,
@@ -15,6 +16,7 @@ import {
   type ControllerCheckSnapshot,
 } from '../../../cli/controller/check-runner';
 import { claimsForCheck, scopeResourceClaims, toProcessClaims } from './resource-claims';
+import { resolveCheckCompletionGraceWaitMs } from '../../control-plane/persistence/operational-prior-store';
 import { spawnManagedProcess, waitForProcess, getProcessHandle } from './runtime';
 import {
   getLightweightProcessHandle,
@@ -26,6 +28,7 @@ import type { ProcessHandle } from './types';
 import { DEFAULT_INTERACTIVE_WAIT_MS } from './types';
 import { durationAwareInteractiveWaitMs } from './interactive-admission';
 import type { ResolvedExecutionIdentity } from '../../control-plane/execution/execution-identity';
+import { registeredCheckRequiresDurableWorkflow } from './check-classification';
 
 export type CheckExecutionMode = 'direct' | 'managed' | 'durable';
 
@@ -99,15 +102,17 @@ export interface RunCheckFacadeResult {
   };
 }
 
-const DURABLE_CHECK_ID = /(?:^|:)(?:release|migration|integrate|public-export|deploy)(?:$|:)/i;
 /**
- * True when a check requires external Controller handling (multi-phase / release).
- * Ordinary typecheck / lint / package test / focused validation stay on Process Runtime.
+ * Compatibility entry point while older internal callers still pass
+ * (checkId, registeredCheck). The id is deliberately ignored: lifecycle
+ * authority comes only from the registered ControllerCheck contract.
  */
-export function checkRequiresDurableWorkflow(checkId: string, check?: ControllerCheck): boolean {
-  if (DURABLE_CHECK_ID.test(checkId)) return true;
-  if (check && /release|rollback|blue.?green|migrate/i.test(check.description)) return true;
-  return false;
+export function checkRequiresDurableWorkflow(
+  checkOrLegacyId: ControllerCheck | string | undefined,
+  registeredCheck?: ControllerCheck,
+): boolean {
+  const check = typeof checkOrLegacyId === 'string' ? registeredCheck : checkOrLegacyId;
+  return registeredCheckRequiresDurableWorkflow(check);
 }
 
 function resolveCheck(repoRoot: string, checkId: string): ControllerCheck | undefined {
@@ -141,7 +146,7 @@ export async function runCheckViaProcessRuntime(
     };
   }
 
-  if (input.forceDurable || checkRequiresDurableWorkflow(input.checkId, check)) {
+  if (input.forceDurable || checkRequiresDurableWorkflow(check)) {
     return {
       mode: 'durable',
       checkId: input.checkId,
@@ -157,9 +162,17 @@ export async function runCheckViaProcessRuntime(
   // The wait budget is an interaction preference, not a persistence reason.
   // Ordinary checks stay in memory; only a real durable evidence consumer may
   // allocate Process/Lease state.
+  const learnedCompletionGraceMs = input.interactiveWaitMs === undefined
+    ? resolveCheckCompletionGraceWaitMs({
+        controllerHome: input.controllerHome,
+        repoId: input.repoId,
+        checkId: input.checkId,
+        environmentFingerprint: controllerCheckEnvironmentFingerprint(check),
+      })
+    : undefined;
   const interactiveWaitMs = durationAwareInteractiveWaitMs(
     check.command,
-    input.interactiveWaitMs,
+    input.interactiveWaitMs ?? learnedCompletionGraceMs,
     Math.min(250, DEFAULT_INTERACTIVE_WAIT_MS),
   );
   const timeoutMs = Math.min(
@@ -218,6 +231,7 @@ export async function runCheckViaProcessRuntime(
       executionIdentity.repositoryId,
       executionIdentity.checkoutId,
       check.effects,
+      check.executionAuthority,
     ),
     executionIdentity.repositoryId,
     executionIdentity.checkoutId,

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

@@ -43,7 +43,7 @@ function artifactSlug(id: string): string {
 }
 
 export function processCheckArtifactPath(checkId: string): string {
-  return `.ai/harness/checks/controller/latest-${artifactSlug(checkId)}.json`;
+  return `controller-home://checks/controller/latest-${artifactSlug(checkId)}.json`;
 }
 
 function receiptStatus(status: ProcessRuntimeStatus): ProcessCheckReceiptStatus {