@moretea-labs/forge 1.7.2 → 1.8.0

package/src/cli/controller/check-runner.ts

@@ -1,5 +1,6 @@
-import { createHash } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
 import { basename, dirname, join, normalize, relative, resolve } from 'path';
 import {
   capProcessOutput,
@@ -12,6 +13,21 @@ import { runBoundedChild } from '../../runtime/shared/bounded-child-supervisor';
 import { signalProcessTree } from '../../runtime/shared/process-tree';
 import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../../runtime/shared/process-environment';
 import { materializeManagedWorkspaceCheckDependencies } from '../../runtime/execution/managed-workspace';
+import {
+  isStructuredCheckFailureEvidence,
+  STRUCTURED_CHECK_RESULT_PATH_ENV,
+  type StructuredCheckFailureEvidence,
+} from '../../runtime/execution/process-runtime/check-result';
+import { readRuntimeReleaseAuthority } from '../../runtime/root/release-store';
+import { observeRuntimeStatus } from '../../runtime/root/status';
+import { readCurrentRecoveryRelease } from '../../runtime/standalone-recovery/release';
+import { acquireRecoveryOperationLock, recoveryOperationLockPath } from '../../runtime/standalone-recovery/operation-lock';
+import {
+  ensureRepositoryCheckStorage,
+  resolveRepositoryCheckStorage,
+  type RepositoryCheckStorageAuthority,
+  type ResolvedRepositoryCheckStorage,
+} from '../../runtime/execution/process-runtime/check-storage';
 
 export interface ControllerCheckEffects {
   /** Repository-relative read scopes. Use [\".\"] for the whole checkout. */
@@ -29,6 +45,7 @@ export interface ControllerCheckEffects {
 export type ControllerCheckCostClass = 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
 export type ControllerCheckRiskFloor = 'readonly' | 'low' | 'medium' | 'high' | 'destructive';
 export type ControllerCheckPhase = 'pre_edit' | 'post_edit' | 'pre_finalize' | 'release';
+export type ControllerCheckExecutionAuthority = 'isolated_controller_home' | 'live_controller_home';
 
 export interface ControllerCheckSelection {
   /** Execution cost only; it does not lower severity or automatically run the check. */
@@ -45,6 +62,8 @@ export interface ControllerCheck {
   cwd: string;
   timeoutMs: number;
   source: 'repo-config' | 'package-script';
+  /** Where authority-sensitive child state is resolved. Ordinary checks stay isolated. */
+  executionAuthority?: ControllerCheckExecutionAuthority;
   effects?: ControllerCheckEffects;
   /** Selection/preflight metadata; intentionally excluded from physical execution identity. */
   selection?: ControllerCheckSelection;
@@ -89,8 +108,8 @@ interface CheckConfig {
 
 const CHECK_CONFIG = '.forge/checks.json';
 const LEGACY_TRACKED_CHECK_CONFIG = '.repo-harness/checks.json';
-const CHECK_EVIDENCE_ROOT = '.ai/harness/checks/controller';
-const HEAVY_CHECK_LOCK = '.ai/harness/controller/heavy-check.lock';
+const CHECK_EVIDENCE_SUBDIR = 'controller';
+const HEAVY_CHECK_LOCK = 'heavy-check.lock';
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 const MAX_TIMEOUT_MS = 30 * 60 * 1000;
 const SAFE_PACKAGE_SCRIPT = /^(test(?::|$)|check(?::|$)|lint(?::|$)|typecheck(?::|$)|format:check$)/;
@@ -253,6 +272,14 @@ export function controllerCheckSelection(check: Pick<ControllerCheck, 'id' | 'se
 
 function inferredPackageCheckEffects(name: string): ControllerCheckEffects | undefined {
   const normalized = name.trim().toLowerCase();
+  if (normalized === 'check:stable-baseline') {
+    return { reads: ['.'], hostServices: ['canonical-runtime', 'forge-recovery'] };
+  }
+  if (normalized === 'check:task' || normalized === 'check:main') {
+    // Governed gates reject any candidate workspace mutation after every step
+    // and persist only content-bound receipts/caches outside repository source.
+    return { reads: ['.'], cache: 'write', temp: 'isolated', git: 'read' };
+  }
   const staticAnalysis = /(?:^|:)(?:type|typecheck|lint|format:check|runtime-architecture|mcp-compatibility|forge-runtime)$/.test(normalized);
   if (staticAnalysis) return { reads: ['.'], cache: 'write' };
   const isolatedReadOnlyCheck = /(?:^|:)(?:quality-harness|evaluation-framework|background-check-overlap|typescript-navigation|check-scheduling|bootstrap-files)$/.test(normalized);
@@ -312,6 +339,9 @@ function packageChecks(repoRoot: string): ControllerCheck[] {
       cwd: '.',
       timeoutMs: packageScriptTimeoutMs(name),
       source: 'package-script' as const,
+      executionAuthority: name.trim().toLowerCase() === 'check:stable-baseline'
+        ? 'live_controller_home' as const
+        : 'isolated_controller_home' as const,
       effects: inferredPackageCheckEffects(name),
       selection: inferredCheckSelection(name),
     }];
@@ -340,8 +370,9 @@ export interface ControllerCheckResult {
   validatedRevision?: string;
   /** Original process execution timestamp; retained when a result is served from cache. */
   originalExecutedAt?: string;
-  /** A non-zero check result is acceptance failure; runtime/process defects are infrastructure. */
+  /** Non-zero repository failures are acceptance failures unless bounded infrastructure evidence proves otherwise. */
   failureClass?: 'acceptance_failure' | 'infrastructure_failure';
+  failureEvidence?: StructuredCheckFailureEvidence;
 }
 
 export interface ControllerCheckEvidence {
@@ -365,54 +396,190 @@ export interface ControllerCheckEvidence {
   validatedRevision?: string;
   originalExecutedAt?: string;
   failureClass?: 'acceptance_failure' | 'infrastructure_failure';
+  failureEvidence?: StructuredCheckFailureEvidence;
+}
+
+const STRONG_TRANSPORT_FAILURE_PATTERNS = [
+  /\bjava\.net\.(?:SocketTimeoutException|UnknownHostException|ConnectException|NoRouteToHostException)\b/i,
+  /\b(?:EAI_AGAIN|ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH)\b/i,
+  /\bCould not resolve host\b/i,
+  /\b(?:connection|connect|read) timed out\b/i,
+  /\bNetwork is unreachable\b/i,
+  /\b(?:SSLHandshakeException|TLS handshake (?:failed|timeout|timed out)|CERTIFICATE_VERIFY_FAILED)\b/i,
+] as const;
+
+function classifyControllerCheckFailure(input: {
+  ok: boolean;
+  stale?: boolean;
+  timedOut: boolean;
+  runtimeFailure: boolean;
+  stdout: string;
+  stderr: string;
+}): 'acceptance_failure' | 'infrastructure_failure' | undefined {
+  if (input.ok && !input.stale) return undefined;
+  if (input.stale || input.timedOut || input.runtimeFailure) return 'infrastructure_failure';
+  const output = `${input.stdout}\n${input.stderr}`;
+  if (STRONG_TRANSPORT_FAILURE_PATTERNS.some((pattern) => pattern.test(output))) return 'infrastructure_failure';
+  return 'acceptance_failure';
+}
+
+const GOVERNED_TEST_GATES = new Map<string, string>([
+  ['package:test', 'affected'],
+  ['package:test:core', 'core'],
+  ['package:test:integration', 'integration'],
+  ['package:test:infrastructure', 'infrastructure'],
+  ['package:test:fault', 'fault'],
+  ['package:test:full', 'full'],
+  ['package:test:bun', 'full'],
+]);
+const MAX_STRUCTURED_CHECK_RESULT_BYTES = 64 * 1024;
+
+interface StructuredCheckObservation {
+  evidence?: StructuredCheckFailureEvidence;
+  error?: string;
+}
+
+function structuredCheckResultPath(check: ControllerCheck): string | undefined {
+  if (!GOVERNED_TEST_GATES.has(check.id)) return undefined;
+  return join(tmpdir(), `forge-check-result-${process.pid}-${randomUUID()}.json`);
+}
+
+function readStructuredCheckObservation(check: ControllerCheck, path: string | undefined): StructuredCheckObservation {
+  const expectedGate = GOVERNED_TEST_GATES.get(check.id);
+  if (!expectedGate) return {};
+  if (!path || !existsSync(path)) return { error: 'CHECK_STRUCTURED_RESULT_MISSING' };
+  try {
+    const bytes = readFileSync(path);
+    if (bytes.byteLength > MAX_STRUCTURED_CHECK_RESULT_BYTES) return { error: 'CHECK_STRUCTURED_RESULT_TOO_LARGE' };
+    const value = JSON.parse(bytes.toString('utf8')) as unknown;
+    if (!isStructuredCheckFailureEvidence(value) || value.gate !== expectedGate) return { error: 'CHECK_STRUCTURED_RESULT_INVALID' };
+    return { evidence: value };
+  } catch {
+    return { error: 'CHECK_STRUCTURED_RESULT_INVALID' };
+  }
+}
+
+function consumeStructuredCheckObservation(check: ControllerCheck, path: string | undefined): StructuredCheckObservation {
+  try {
+    return readStructuredCheckObservation(check, path);
+  } finally {
+    if (path) rmSync(path, { force: true });
+  }
+}
+
+function applyStructuredCheckObservation(processOk: boolean, observation: StructuredCheckObservation): {
+  ok: boolean;
+  failureClass?: 'acceptance_failure' | 'infrastructure_failure';
+  failureEvidence?: StructuredCheckFailureEvidence;
+  error?: string;
+} {
+  if (!observation.error && !observation.evidence) return { ok: processOk };
+  if (observation.error) return { ok: false, failureClass: 'infrastructure_failure', error: observation.error };
+  const evidence = observation.evidence!;
+  const reportOk = evidence.status === 'passed';
+  if (reportOk !== processOk) {
+    return { ok: false, failureClass: 'infrastructure_failure', failureEvidence: evidence, error: 'CHECK_STRUCTURED_RESULT_STATUS_MISMATCH' };
+  }
+  if (reportOk) return { ok: true, failureEvidence: evidence };
+  const sourceOnly = evidence.failureClasses.length > 0 && evidence.failureClasses.every((entry) => entry === 'source');
+  return {
+    ok: false,
+    failureClass: sourceOnly ? 'acceptance_failure' : 'infrastructure_failure',
+    failureEvidence: evidence,
+  };
 }
 
 function artifactSlug(id: string): string {
   return id.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'check';
 }
 
-function evidencePath(repoRoot: string, id: string): string {
-  return join(repoRoot, CHECK_EVIDENCE_ROOT, `latest-${artifactSlug(id)}.json`);
+function evidencePath(storage: ResolvedRepositoryCheckStorage, id: string): string {
+  return join(storage.physicalRoot, CHECK_EVIDENCE_SUBDIR, `latest-${artifactSlug(id)}.json`);
+}
+
+function historicalEvidencePath(storage: ResolvedRepositoryCheckStorage, id: string, cacheKey: string): string {
+  return join(storage.physicalRoot, CHECK_EVIDENCE_SUBDIR, artifactSlug(id), `${cacheKey}.json`);
 }
 
-function historicalEvidencePath(repoRoot: string, id: string, cacheKey: string): string {
-  return join(repoRoot, CHECK_EVIDENCE_ROOT, artifactSlug(id), `${cacheKey}.json`);
+function logicalEvidenceArtifactPath(id: string): string {
+  return `controller-home://checks/controller/latest-${artifactSlug(id)}.json`;
 }
 
 const CHECK_REVISION_EXCLUDES = [
-  '.ai/harness/jobs/**',
-  '.ai/harness/local-jobs/**',
-  '.ai/harness/checks/controller/**',
-  '.ai/harness/edit-sessions/**',
-  '.ai/harness/worktrees/**',
-  '.ai/harness/controller/**',
-  '.ai/harness/artifacts/**',
-  '.ai/harness/local-bridge/**',
-  '.ai/harness/ephemeral-issues/**',
+  // `.ai/harness` is Forge runtime/check state, not repository source. Checks
+  // are allowed to materialize artifacts such as design-system audit reports
+  // there; hashing those outputs would make a stable check invalidate itself.
+  '.ai/harness/**',
 ];
 
 function checkRevisionPathspecs(): string[] {
   return ['.', ...CHECK_REVISION_EXCLUDES.map((path) => `:(exclude)${path}`)];
 }
 
-export function currentControllerCheckRevision(repoRoot: string): string {
+interface ControllerCheckContentObservation {
+  revision: string;
+  fileDigests?: Map<string, string>;
+  listingAvailable: boolean;
+}
+
+function observeControllerCheckContent(
+  repoRoot: string,
+  options: { captureFileDigests?: boolean } = {},
+): ControllerCheckContentObservation {
   const files = runProcess('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z', '--', ...checkRevisionPathspecs()], {
     cwd: repoRoot,
     timeoutMs: 10_000,
     maxOutputBytes: 8 * 1024 * 1024,
   });
   const revision = createHash('sha256').update('controller-check-content-v2\n');
-  if (!files.ok) return revision.update(`git-error:${files.error || files.stderr}`).digest('hex').slice(0, 24);
+  const fileDigests = options.captureFileDigests ? new Map<string, string>() : undefined;
+  if (!files.ok) {
+    return {
+      revision: revision.update(`git-error:${files.error || files.stderr}`).digest('hex').slice(0, 24),
+      ...(fileDigests ? { fileDigests } : {}),
+      listingAvailable: false,
+    };
+  }
   for (const relativePath of files.stdout.split('\0').filter(Boolean).sort()) {
     if (relativePath.startsWith('tasks/') || relativePath.startsWith('plans/')) continue;
     revision.update(`${relativePath}\0`);
     try {
-      revision.update(readFileSync(resolve(repoRoot, relativePath)));
+      const content = readFileSync(resolve(repoRoot, relativePath));
+      revision.update(content);
+      fileDigests?.set(relativePath, createHash('sha256').update(content).digest('hex'));
     } catch (_error) {
       revision.update('missing');
+      fileDigests?.set(relativePath, 'missing');
     }
   }
-  return revision.digest('hex').slice(0, 24);
+  return {
+    revision: revision.digest('hex').slice(0, 24),
+    ...(fileDigests ? { fileDigests } : {}),
+    listingAvailable: true,
+  };
+}
+
+export function currentControllerCheckRevision(repoRoot: string): string {
+  return observeControllerCheckContent(repoRoot).revision;
+}
+
+function controllerCheckWriteScopeContainsPath(scope: string, relativePath: string): boolean {
+  return scope === '.' || relativePath === scope || relativePath.startsWith(`${scope}/`);
+}
+
+function controllerCheckInputIntegrityChanged(
+  check: ControllerCheck,
+  input: ControllerCheckContentObservation,
+  completed: ControllerCheckContentObservation,
+): boolean {
+  if (!input.listingAvailable || !completed.listingAvailable || !input.fileDigests || !completed.fileDigests) return true;
+  const writeScopes = check.effects?.writes ?? [];
+  const observedPaths = new Set([...input.fileDigests.keys(), ...completed.fileDigests.keys()]);
+  for (const relativePath of observedPaths) {
+    if (writeScopes.some((scope) => controllerCheckWriteScopeContainsPath(scope, relativePath))) continue;
+    if (input.fileDigests.get(relativePath) !== completed.fileDigests.get(relativePath)) return true;
+  }
+  return false;
 }
 
 function checkDefinitionDigest(check: ControllerCheck): string {
@@ -423,6 +590,7 @@ function checkDefinitionDigest(check: ControllerCheck): string {
     cwd: check.cwd,
     timeoutMs: check.timeoutMs,
     source: check.source,
+    executionAuthority: check.executionAuthority ?? 'isolated_controller_home',
     effects: check.effects,
   })).digest('hex');
 }
@@ -450,6 +618,7 @@ function validateControllerCheckSnapshot(repoRoot: string, snapshot: ControllerC
     cwd: normalizeCwd(repoRoot, snapshot.cwd),
     timeoutMs: boundedTimeout(snapshot.timeoutMs),
     source: snapshot.source,
+    executionAuthority: snapshot.executionAuthority ?? 'isolated_controller_home',
     effects: normalizeCheckEffects(repoRoot, snapshot.effects),
     selection: normalizeCheckSelection(snapshot.selection, snapshot.id),
   };
@@ -457,7 +626,72 @@ function validateControllerCheckSnapshot(repoRoot: string, snapshot: ControllerC
 
 const CONTROLLER_CHECK_EXECUTION_IDENTITY_VERSION = 'controller-check-execution-v2';
 
-function checkEnvironmentFingerprint(check: ControllerCheck): string {
+/**
+ * Bounded live-state identity for certification checks. This is read-only
+ * evidence, not lifecycle authority. It includes current release authority and
+ * observed Runtime liveness so a dead/replaced Runtime cannot reuse a prior
+ * green Stable Baseline receipt merely because its status file remained.
+ */
+export function controllerCheckLiveExecutionStateFingerprint(controllerHome: string, recoveryFenceInstanceId?: string): string {
+  const mutationLockPath = recoveryOperationLockPath(controllerHome);
+  try {
+    const raw = readFileSync(mutationLockPath, 'utf8');
+    if (recoveryFenceInstanceId?.trim()) {
+      try {
+        const owner = JSON.parse(raw) as { instanceId?: unknown };
+        if (owner?.instanceId === recoveryFenceInstanceId.trim()) {
+          // This check owns the real Recovery mutation fence; its own lock is not drift.
+        } else {
+          throw new Error('LIVE_CHECK_RECOVERY_MUTATION_IN_PROGRESS');
+        }
+      } catch (error) {
+        if (error instanceof Error && error.message === 'LIVE_CHECK_RECOVERY_MUTATION_IN_PROGRESS') throw error;
+        throw new Error('LIVE_CHECK_RECOVERY_MUTATION_STATE_UNREADABLE');
+      }
+    } else {
+      throw new Error('LIVE_CHECK_RECOVERY_MUTATION_IN_PROGRESS');
+    }
+  } catch (error) {
+    if (error instanceof Error && (
+      error.message === 'LIVE_CHECK_RECOVERY_MUTATION_IN_PROGRESS'
+      || error.message === 'LIVE_CHECK_RECOVERY_MUTATION_STATE_UNREADABLE'
+    )) throw error;
+    if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+      throw new Error('LIVE_CHECK_RECOVERY_MUTATION_STATE_UNREADABLE');
+    }
+  }
+  const release = readRuntimeReleaseAuthority(controllerHome);
+  const recoveryRelease = readCurrentRecoveryRelease(controllerHome);
+  const runtime = observeRuntimeStatus(controllerHome);
+  return createHash('sha256')
+    .update(JSON.stringify({
+      release: release ? {
+        revision: release.revision,
+        releaseId: release.active.releaseId,
+        artifactIdentity: release.active.artifactIdentity,
+        manifestSha256: release.active.manifestSha256,
+      } : null,
+      recoveryRelease: recoveryRelease ? {
+        releaseRevision: recoveryRelease.releaseRevision,
+        sourceCommit: recoveryRelease.sourceCommit,
+        manifestSha256: recoveryRelease.manifestSha256,
+      } : null,
+      runtime: {
+        running: runtime.running,
+        ready: runtime.ready,
+        stale: runtime.stale,
+        reasonCodes: [...runtime.reasonCodes].sort(),
+        runtimeInstanceId: runtime.snapshot?.runtimeInstanceId ?? null,
+        pid: runtime.snapshot?.pid ?? null,
+        releaseId: runtime.snapshot?.releaseId ?? null,
+        artifactIdentity: runtime.snapshot?.artifactIdentity ?? null,
+      },
+    }))
+    .digest('hex')
+    .slice(0, 24);
+}
+
+export function controllerCheckEnvironmentFingerprint(check: ControllerCheck, executionStateFingerprint?: string): string {
   const env = repositoryChildProcessEnvironment(process.env);
   return createHash('sha256')
     .update(JSON.stringify({
@@ -470,6 +704,8 @@ function checkEnvironmentFingerprint(check: ControllerCheck): string {
       // for the parent and forge-check-runner for the sidecar; process.execPath
       // therefore differs even though both execute the exact same check/toolchain.
       commandExecutable: check.command[0],
+      executionAuthority: check.executionAuthority ?? 'isolated_controller_home',
+      executionStateFingerprint: executionStateFingerprint?.trim() || '',
       path: env.PATH ?? '',
       home: env.HOME ?? env.USERPROFILE ?? '',
       bunInstall: env.BUN_INSTALL ?? '',
@@ -514,7 +750,7 @@ function buildCheckCacheKey(
   timeoutMs: number,
   revision: string,
   definitionDigest = checkDefinitionDigest(check),
-  environmentFingerprint = checkEnvironmentFingerprint(check),
+  environmentFingerprint = controllerCheckEnvironmentFingerprint(check),
 ): string {
   return createHash('sha256')
     .update(JSON.stringify({
@@ -531,11 +767,13 @@ function buildCheckCacheKey(
     .slice(0, 24);
 }
 
-export function controllerCheckExecutionIdentity(
+function controllerCheckExecutionIdentityForRevision(
   repoRoot: string,
   id: string,
+  revision: string,
   requestedTimeoutMs?: number,
   snapshot?: ControllerCheckSnapshot,
+  executionStateFingerprint?: string,
 ): ControllerCheckExecutionIdentity {
   const check = snapshot
     ? validateControllerCheckSnapshot(repoRoot, snapshot)
@@ -544,9 +782,8 @@ export function controllerCheckExecutionIdentity(
   const timeoutMs = requestedTimeoutMs === undefined
     ? check.timeoutMs
     : Math.min(check.timeoutMs, boundedTimeout(requestedTimeoutMs));
-  const revision = currentControllerCheckRevision(repoRoot);
   const definitionDigest = checkDefinitionDigest(check);
-  const environmentFingerprint = checkEnvironmentFingerprint(check);
+  const environmentFingerprint = controllerCheckEnvironmentFingerprint(check, executionStateFingerprint);
   const checkoutClean = checkWorkspaceClean(repoRoot);
   const crossCheckoutReusable = checkoutClean
     && checkEffectsAllowCrossCheckoutReuse(check)
@@ -565,8 +802,25 @@ export function controllerCheckExecutionIdentity(
   };
 }
 
-function persistCheckEvidence(
+export function controllerCheckExecutionIdentity(
   repoRoot: string,
+  id: string,
+  requestedTimeoutMs?: number,
+  snapshot?: ControllerCheckSnapshot,
+  executionStateFingerprint?: string,
+): ControllerCheckExecutionIdentity {
+  return controllerCheckExecutionIdentityForRevision(
+    repoRoot,
+    id,
+    currentControllerCheckRevision(repoRoot),
+    requestedTimeoutMs,
+    snapshot,
+    executionStateFingerprint,
+  );
+}
+
+function persistCheckEvidence(
+  storage: ResolvedRepositoryCheckStorage,
   result: Omit<ControllerCheckResult, 'artifactPath'>,
   meta: {
     revision?: string;
@@ -577,7 +831,7 @@ function persistCheckEvidence(
     validatedRevision?: string;
   } = {},
 ): string {
-  const path = evidencePath(repoRoot, result.check.id);
+  const path = evidencePath(storage, result.check.id);
   mkdirSync(dirname(path), { recursive: true });
   const evidence: ControllerCheckEvidence = {
     schemaVersion: 2,
@@ -600,30 +854,40 @@ function persistCheckEvidence(
     validatedRevision: meta.validatedRevision,
     originalExecutedAt: result.originalExecutedAt ?? result.executedAt,
     failureClass: result.failureClass,
+    failureEvidence: result.failureEvidence,
   };
   const serialized = `${JSON.stringify(evidence, null, 2)}\n`;
   atomicWriteFileSync(path, serialized);
   if (meta.cacheKey) {
-    const historicalPath = historicalEvidencePath(repoRoot, result.check.id, meta.cacheKey);
+    const historicalPath = historicalEvidencePath(storage, result.check.id, meta.cacheKey);
     mkdirSync(dirname(historicalPath), { recursive: true });
     atomicWriteFileSync(historicalPath, serialized);
   }
-  return relative(repoRoot, path).replace(/\\/g, '/');
+  return logicalEvidenceArtifactPath(result.check.id);
 }
 
-export function readLatestControllerCheckEvidence(repoRoot: string, id: string): ControllerCheckEvidence | undefined {
-  const path = evidencePath(repoRoot, id);
+export function readLatestControllerCheckEvidence(
+  repoRoot: string,
+  id: string,
+  storageAuthority?: RepositoryCheckStorageAuthority | ResolvedRepositoryCheckStorage,
+): ControllerCheckEvidence | undefined {
+  const storage = storageAuthority && 'physicalRoot' in storageAuthority
+    ? storageAuthority as ResolvedRepositoryCheckStorage
+    : resolveRepositoryCheckStorage(repoRoot, storageAuthority as RepositoryCheckStorageAuthority | undefined);
+  const path = evidencePath(storage, id);
   if (!existsSync(path)) return undefined;
   try {
     const value = JSON.parse(readFileSync(path, 'utf-8')) as ControllerCheckEvidence;
-    return value.schemaVersion === 2 && value.checkId === id ? value : undefined;
+    if (value.schemaVersion !== 2 || value.checkId !== id) return undefined;
+    if (value.failureEvidence !== undefined && !isStructuredCheckFailureEvidence(value.failureEvidence)) return undefined;
+    return value;
   } catch (_error) {
     return undefined;
   }
 }
 
-function readControllerCheckEvidenceByKey(repoRoot: string, id: string, cacheKey: string): ControllerCheckEvidence | undefined {
-  const path = historicalEvidencePath(repoRoot, id, cacheKey);
+function readControllerCheckEvidenceByKey(storage: ResolvedRepositoryCheckStorage, id: string, cacheKey: string): ControllerCheckEvidence | undefined {
+  const path = historicalEvidencePath(storage, id, cacheKey);
   if (!existsSync(path)) return undefined;
   try {
     const value = JSON.parse(readFileSync(path, 'utf-8')) as ControllerCheckEvidence;
@@ -638,16 +902,27 @@ function prepareControllerCheckDependencies(repoRoot: string, check: ControllerC
   materializeManagedWorkspaceCheckDependencies(repoRoot);
 }
 
-export function runControllerCheck(repoRoot: string, id: string, requestedTimeoutMs?: number, snapshot?: ControllerCheckSnapshot): ControllerCheckResult {
+export function runControllerCheck(
+  repoRoot: string,
+  id: string,
+  requestedTimeoutMs?: number,
+  snapshot?: ControllerCheckSnapshot,
+  storageAuthority?: RepositoryCheckStorageAuthority,
+): ControllerCheckResult {
   const check = snapshot ? validateControllerCheckSnapshot(repoRoot, snapshot) : listControllerChecks(repoRoot).find((entry) => entry.id === id);
   if (!check || check.id !== id) throw new Error(`check not found: ${id}`);
+  if (check.executionAuthority === 'live_controller_home') {
+    throw new Error('LIVE_CHECK_DURABLE_EXECUTION_REQUIRED');
+  }
+  const storage = ensureRepositoryCheckStorage(repoRoot, storageAuthority);
   prepareControllerCheckDependencies(repoRoot, check);
-  const identity = controllerCheckExecutionIdentity(repoRoot, id, requestedTimeoutMs, snapshot);
+  const inputIntegrity = observeControllerCheckContent(repoRoot, { captureFileDigests: true });
+  const identity = controllerCheckExecutionIdentityForRevision(repoRoot, id, inputIntegrity.revision, requestedTimeoutMs, snapshot);
   const timeoutMs = identity.timeoutMs;
   const revision = identity.revision;
   const cacheKey = identity.cacheKey;
-  const cached = readControllerCheckEvidenceByKey(repoRoot, id, cacheKey)
-    ?? readLatestControllerCheckEvidence(repoRoot, id);
+  const cached = readControllerCheckEvidenceByKey(storage, id, cacheKey)
+    ?? readLatestControllerCheckEvidence(repoRoot, id, storage);
   if (cached?.cacheKey === cacheKey && cached.ok) {
     return {
       check,
@@ -658,20 +933,23 @@ export function runControllerCheck(repoRoot: string, id: string, requestedTimeou
       stderr: cached.stderr,
       command: cached.command,
       executedAt: cached.executedAt,
-      artifactPath: relative(repoRoot, evidencePath(repoRoot, id)).replace(/\\/g, '/'),
+      artifactPath: logicalEvidenceArtifactPath(id),
       cacheHit: true,
       validatedRevision: cached.validatedRevision ?? cached.completedRevision ?? cached.revision ?? revision,
       originalExecutedAt: cached.originalExecutedAt ?? cached.executedAt,
       failureClass: cached.failureClass,
+      failureEvidence: cached.failureEvidence,
     };
   }
   const heavy = controllerCheckConcurrencyClass(id) === 'heavy';
-  const lease = heavy ? tryAcquireHeavyCheckLock(repoRoot, id) : undefined;
+  const lease = heavy ? tryAcquireHeavyCheckLock(storage, id) : undefined;
   if (heavy && !lease) throw new Error(`heavy check already running for repository: ${id}`);
+  const structuredResultPath = structuredCheckResultPath(check);
   let result: ProcessRunResult;
   try {
     const bridgeRuntime = resolveSyncSupervisorBridgeRuntime();
     const childEnvironment = repositoryChildProcessEnvironment();
+    if (structuredResultPath) childEnvironment[STRUCTURED_CHECK_RESULT_PATH_ENV] = structuredResultPath;
     delete childEnvironment[CHECK_BRIDGE_RUNTIME_ENV];
     childEnvironment.FORGE_SUPERVISED_REQUEST = Buffer.from(JSON.stringify({
       command: check.command[0],
@@ -736,17 +1014,23 @@ export function runControllerCheck(repoRoot: string, id: string, requestedTimeou
   } finally {
     lease?.release();
   }
-  const completedRevision = currentControllerCheckRevision(repoRoot);
-  const stale = completedRevision !== revision;
+  const structuredObservation = consumeStructuredCheckObservation(check, structuredResultPath);
+  const structuredDecision = applyStructuredCheckObservation(result.ok, structuredObservation);
+  const completedContent = observeControllerCheckContent(repoRoot, { captureFileDigests: true });
+  const completedRevision = completedContent.revision;
+  const stale = controllerCheckInputIntegrityChanged(check, inputIntegrity, completedContent);
   const executedAt = new Date().toISOString();
+  const effectiveOk = structuredDecision.ok && !stale;
+  const hardInfrastructureFailure = stale || result.timedOut || Boolean(result.error) || Boolean(result.signal);
   const withoutPath = {
     check,
-    ok: result.ok && !stale,
-    status: stale ? 1 : result.status,
+    ok: effectiveOk,
+    status: stale || (!structuredDecision.ok && result.status === 0) ? 1 : result.status,
     timedOut: result.timedOut,
     stdout: result.stdout,
     stderr: [
       result.stderr || result.error,
+      structuredDecision.error,
       stale ? 'repository revision changed while the check was running; evidence is stale and the check must be rerun' : '',
     ].filter(Boolean).join('\n'),
     command: result.command,
@@ -754,13 +1038,21 @@ export function runControllerCheck(repoRoot: string, id: string, requestedTimeou
     cacheHit: false,
     validatedRevision: stale ? completedRevision : revision,
     originalExecutedAt: executedAt,
-    failureClass: stale || result.timedOut || Boolean(result.error) || Boolean(result.signal)
+    failureClass: hardInfrastructureFailure
       ? 'infrastructure_failure' as const
-      : result.ok ? undefined : 'acceptance_failure' as const,
+      : structuredDecision.failureClass ?? classifyControllerCheckFailure({
+        ok: effectiveOk,
+        stale,
+        timedOut: result.timedOut,
+        runtimeFailure: Boolean(result.error) || Boolean(result.signal),
+        stdout: result.stdout,
+        stderr: [result.stderr, result.error, structuredDecision.error].filter(Boolean).join('\n'),
+      }),
+    failureEvidence: structuredDecision.failureEvidence,
   };
   return {
     ...withoutPath,
-    artifactPath: persistCheckEvidence(repoRoot, withoutPath, {
+    artifactPath: persistCheckEvidence(storage, withoutPath, {
       revision,
       completedRevision,
       stale,
@@ -773,6 +1065,11 @@ export function runControllerCheck(repoRoot: string, id: string, requestedTimeou
 
 export interface AsyncControllerCheckOptions {
   snapshot?: ControllerCheckSnapshot;
+  /** Exact live-state identity supplied by the persisted Work verifier for live certification checks. */
+  executionStateFingerprint?: string;
+  /** Explicit installed Controller Home; never inferred from ambient child environment. */
+  liveControllerHome?: string;
+  storageAuthority?: RepositoryCheckStorageAuthority;
   /** Explicit isolated authority for Candidate verification child processes. */
   isolatedControllerHome?: string;
   requestedTimeoutMs?: number;
@@ -823,8 +1120,8 @@ interface HeavyCheckLease {
   release(): void;
 }
 
-function tryAcquireHeavyCheckLock(repoRoot: string, checkId: string): HeavyCheckLease | undefined {
-  const path = join(repoRoot, HEAVY_CHECK_LOCK);
+function tryAcquireHeavyCheckLock(storage: ResolvedRepositoryCheckStorage, checkId: string): HeavyCheckLease | undefined {
+  const path = join(storage.lockRoot, HEAVY_CHECK_LOCK);
   mkdirSync(dirname(path), { recursive: true });
   const lockId = `${process.pid}:${Date.now()}:${checkId}`;
   const record: HeavyCheckLockRecord = {
@@ -851,7 +1148,7 @@ function tryAcquireHeavyCheckLock(repoRoot: string, checkId: string): HeavyCheck
     const orphaned = !isProcessAlive(existing?.controllerPid ?? existing?.pid) && !isProcessAlive(existing?.childPid);
     if (!existing || orphaned) {
       rmSync(path, { force: true });
-      return tryAcquireHeavyCheckLock(repoRoot, checkId);
+      return tryAcquireHeavyCheckLock(storage, checkId);
     }
     return undefined;
   }
@@ -873,10 +1170,10 @@ function tryAcquireHeavyCheckLock(repoRoot: string, checkId: string): HeavyCheck
   };
 }
 
-async function acquireHeavyCheckLock(repoRoot: string, checkId: string): Promise<HeavyCheckLease> {
+async function acquireHeavyCheckLock(storage: ResolvedRepositoryCheckStorage, checkId: string): Promise<HeavyCheckLease> {
   const deadline = Date.now() + MAX_TIMEOUT_MS * 2;
   while (true) {
-    const lease = tryAcquireHeavyCheckLock(repoRoot, checkId);
+    const lease = tryAcquireHeavyCheckLock(storage, checkId);
     if (lease) return lease;
     if (Date.now() >= deadline) throw new Error(`timed out waiting for repository heavy-check lock before ${checkId}`);
     await new Promise((resolvePromise) => setTimeout(resolvePromise, 50));
@@ -913,13 +1210,19 @@ async function executeControllerCheckAsync(
   repoRoot: string,
   check: ControllerCheck,
   timeoutMs: number,
+  storage: ResolvedRepositoryCheckStorage,
   onSpawn?: (pid: number) => void,
   isolatedControllerHome?: string,
+  liveControllerHome?: string,
 ): Promise<ControllerCheckResult> {
   const maxOutputBytes = 256 * 1024;
   const command = [check.command[0], ...check.command.slice(1)];
   const childEnvironment = repositoryChildProcessEnvironment();
-  if (isolatedControllerHome?.trim()) childEnvironment.FORGE_CONTROLLER_HOME = resolve(isolatedControllerHome);
+  const structuredResultPath = structuredCheckResultPath(check);
+  if (structuredResultPath) childEnvironment[STRUCTURED_CHECK_RESULT_PATH_ENV] = structuredResultPath;
+  if (isolatedControllerHome?.trim() && liveControllerHome?.trim()) throw new Error('CHECK_CONTROLLER_HOME_AUTHORITY_CONFLICT');
+  if (liveControllerHome?.trim()) childEnvironment.FORGE_CONTROLLER_HOME = resolve(liveControllerHome);
+  else if (isolatedControllerHome?.trim()) childEnvironment.FORGE_CONTROLLER_HOME = resolve(isolatedControllerHome);
   const supervised = await runBoundedChild(check.command[0], check.command.slice(1), {
     cwd: resolve(repoRoot, check.cwd),
     env: childEnvironment,
@@ -935,19 +1238,34 @@ async function executeControllerCheckAsync(
   const timeoutMessage = supervised.timedOut
     ? `process timed out after ${timeoutMs}ms: ${command.join(' ')}`
     : '';
+  const processOk = supervised.status === 0 && !supervised.failureCode;
+  const structuredObservation = consumeStructuredCheckObservation(check, structuredResultPath);
+  const structuredDecision = applyStructuredCheckObservation(processOk, structuredObservation);
+  const hardInfrastructureFailure = supervised.timedOut
+    || Boolean(supervised.failureCode)
+    || Boolean(supervised.error)
+    || Boolean(supervised.signal);
   const result = {
-    ok: supervised.status === 0 && !supervised.failureCode,
-    status: supervised.status,
+    ok: structuredDecision.ok,
+    status: !structuredDecision.ok && supervised.status === 0 ? 1 : supervised.status,
     timedOut: supervised.timedOut,
     stdout: capProcessOutput(redactProcessOutput(supervised.stdout), maxOutputBytes),
     stderr: capProcessOutput(redactProcessOutput([
       supervised.stderr,
       timeoutMessage || supervised.error || '',
       processTreeError,
+      structuredDecision.error,
     ].filter(Boolean).join('\n')), maxOutputBytes),
-    failureClass: supervised.failureCode
+    failureClass: hardInfrastructureFailure
       ? 'infrastructure_failure' as const
-      : supervised.status === 0 ? undefined : 'acceptance_failure' as const,
+      : structuredDecision.failureClass ?? classifyControllerCheckFailure({
+      ok: structuredDecision.ok,
+      timedOut: supervised.timedOut,
+      runtimeFailure: Boolean(supervised.failureCode) || Boolean(supervised.error) || Boolean(supervised.signal),
+      stdout: supervised.stdout,
+      stderr: [supervised.stderr, timeoutMessage, supervised.error, processTreeError, structuredDecision.error].filter(Boolean).join('\n'),
+    }),
+    failureEvidence: structuredDecision.failureEvidence,
   };
 
   const executedAt = new Date().toISOString();
@@ -964,8 +1282,9 @@ async function executeControllerCheckAsync(
     validatedRevision: undefined,
     originalExecutedAt: executedAt,
     failureClass: result.failureClass,
+    failureEvidence: result.failureEvidence,
   };
-  return { ...withoutPath, artifactPath: relative(repoRoot, evidencePath(repoRoot, check.id)).replace(/\\/g, '/') };
+  return { ...withoutPath, artifactPath: logicalEvidenceArtifactPath(check.id) };
 }
 
 export function runControllerCheckAsync(
@@ -980,19 +1299,68 @@ export function runControllerCheckAsync(
     return Promise.reject(error);
   }
   if (!check || check.id !== id) return Promise.reject(new Error(`check not found: ${id}`));
+  const liveCertification = check.executionAuthority === 'live_controller_home';
+  const liveControllerHome = options.liveControllerHome?.trim();
+  const expectedLiveState = options.executionStateFingerprint?.trim();
+  if (liveCertification) {
+    if (!liveControllerHome || !expectedLiveState) {
+      return Promise.reject(new Error('LIVE_CHECK_EXPLICIT_AUTHORITY_REQUIRED'));
+    }
+  } else if (liveControllerHome) {
+    return Promise.reject(new Error('LIVE_CHECK_AUTHORITY_NOT_DECLARED'));
+  }
+  let storage: ResolvedRepositoryCheckStorage;
   try {
+    storage = ensureRepositoryCheckStorage(repoRoot, options.storageAuthority);
     prepareControllerCheckDependencies(repoRoot, check);
   } catch (error) {
     return Promise.reject(error);
   }
-  const identity = controllerCheckExecutionIdentity(repoRoot, id, options.requestedTimeoutMs, options.snapshot);
+  const inputIntegrity = observeControllerCheckContent(repoRoot, { captureFileDigests: true });
+  const identity = controllerCheckExecutionIdentityForRevision(
+    repoRoot,
+    id,
+    inputIntegrity.revision,
+    options.requestedTimeoutMs,
+    options.snapshot,
+    options.executionStateFingerprint,
+  );
   const timeoutMs = identity.timeoutMs;
   const revision = identity.revision;
   const cacheKey = identity.cacheKey;
-  const cached = readControllerCheckEvidenceByKey(repoRoot, id, cacheKey)
-    ?? readLatestControllerCheckEvidence(repoRoot, id);
+  const cached = readControllerCheckEvidenceByKey(storage, id, cacheKey)
+    ?? readLatestControllerCheckEvidence(repoRoot, id, storage);
+  const withLiveRecoveryFence = async <T>(action: (recoveryFenceInstanceId?: string) => Promise<T> | T): Promise<T> => {
+    if (!liveCertification) return await action(undefined);
+    let attempt;
+    try {
+      attempt = acquireRecoveryOperationLock({
+        controllerHome: liveControllerHome!,
+        action: 'certify_stable_baseline',
+        requestId: `check:${id}:${cacheKey}`,
+        instanceIdPrefix: 'live-certification-',
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message === 'RECOVERY_OPERATION_LOCK_BUSY') throw new Error('LIVE_CHECK_RECOVERY_MUTATION_IN_PROGRESS');
+      throw new Error(`LIVE_CHECK_RECOVERY_MUTATION_STATE_UNREADABLE: ${message}`);
+    }
+    if (!attempt.acquired) throw new Error('LIVE_CHECK_RECOVERY_MUTATION_IN_PROGRESS');
+    try {
+      const observedLiveState = controllerCheckLiveExecutionStateFingerprint(
+        liveControllerHome!,
+        attempt.handle.record.instanceId,
+      );
+      if (observedLiveState !== expectedLiveState) {
+        throw new Error('LIVE_CHECK_STATE_CHANGED_BEFORE_EXECUTION');
+      }
+      return await action(attempt.handle.record.instanceId);
+    } finally {
+      attempt.handle.close();
+    }
+  };
   if (cached?.cacheKey === cacheKey && cached.ok) {
-    return Promise.resolve({
+    return withLiveRecoveryFence(() => ({
       check,
       ok: cached.ok,
       status: cached.status,
@@ -1001,12 +1369,12 @@ export function runControllerCheckAsync(
       stderr: cached.stderr,
       command: cached.command,
       executedAt: cached.executedAt,
-      artifactPath: relative(repoRoot, evidencePath(repoRoot, id)).replace(/\\/g, '/'),
+      artifactPath: logicalEvidenceArtifactPath(id),
       cacheHit: true,
       validatedRevision: cached.validatedRevision ?? cached.completedRevision ?? cached.revision ?? revision,
       originalExecutedAt: cached.originalExecutedAt ?? cached.executedAt,
       failureClass: cached.failureClass,
-    });
+    }));
   }
   const key = `${resolve(repoRoot)}\u0000${id}\u0000${cacheKey}`;
   const existing = activeAsyncChecks.get(key);
@@ -1052,48 +1420,69 @@ export function runControllerCheckAsync(
   };
   const execute = async (lease?: HeavyCheckLease) => {
     assertExecutionStillRequested();
-    const result = await executeControllerCheckAsync(repoRoot, check, timeoutMs, (pid) => {
-      lease?.setChildPid(pid);
-      notifySpawn(pid);
-    }, options.isolatedControllerHome);
-    const completedRevision = currentControllerCheckRevision(repoRoot);
-    const stale = completedRevision !== revision;
-    const finalized = {
-      ...result,
-      ...(stale ? {
-        ok: false,
-        status: 1,
-        stderr: [
-          result.stderr,
-          'repository revision changed while the check was running; evidence is stale and the check must be rerun',
-        ].filter(Boolean).join('\n'),
-        failureClass: 'infrastructure_failure' as const,
-      } : {}),
-      cacheHit: false,
-      validatedRevision: stale ? completedRevision : revision,
-    };
-    const { artifactPath: _artifactPath, ...withoutPath } = finalized;
-    const artifactPath = persistCheckEvidence(repoRoot, withoutPath, {
-      revision,
-      completedRevision,
-      stale,
-      cacheKey: stale ? undefined : cacheKey,
-      cacheHit: false,
-      validatedRevision: stale ? completedRevision : revision,
+    return withLiveRecoveryFence(async (recoveryFenceInstanceId) => {
+      assertExecutionStillRequested();
+      const result = await executeControllerCheckAsync(repoRoot, check, timeoutMs, storage, (pid) => {
+        lease?.setChildPid(pid);
+        notifySpawn(pid);
+      }, options.isolatedControllerHome, options.liveControllerHome);
+      const completedContent = observeControllerCheckContent(repoRoot, { captureFileDigests: true });
+      const completedRevision = completedContent.revision;
+      let liveStateStale = false;
+      if (liveCertification) {
+        try {
+          liveStateStale = controllerCheckLiveExecutionStateFingerprint(
+            liveControllerHome!,
+            recoveryFenceInstanceId,
+          ) !== expectedLiveState;
+        } catch {
+          liveStateStale = true;
+        }
+      }
+      const repositoryStale = controllerCheckInputIntegrityChanged(check, inputIntegrity, completedContent);
+      const stale = repositoryStale || liveStateStale;
+      const finalized = {
+        ...result,
+        ...(stale ? {
+          ok: false,
+          status: 1,
+          stderr: [
+            result.stderr,
+            repositoryStale
+              ? 'repository revision changed while the check was running; evidence is stale and the check must be rerun'
+              : '',
+            liveStateStale
+              ? 'live Runtime/Recovery authority changed while the check was running; evidence is stale and the check must be rerun'
+              : '',
+          ].filter(Boolean).join('\n'),
+          failureClass: 'infrastructure_failure' as const,
+        } : {}),
+        cacheHit: false,
+        validatedRevision: stale ? completedRevision : revision,
+      };
+      const { artifactPath: _artifactPath, ...withoutPath } = finalized;
+      const artifactPath = persistCheckEvidence(storage, withoutPath, {
+        revision,
+        completedRevision,
+        stale,
+        cacheKey: stale ? undefined : cacheKey,
+        cacheHit: false,
+        validatedRevision: stale ? completedRevision : revision,
+      });
+      return { ...finalized, artifactPath };
     });
-    return { ...finalized, artifactPath };
   };
   const executeHeavy = async (): Promise<ControllerCheckResult> => {
     assertExecutionStillRequested();
-    const lease = await acquireHeavyCheckLock(repoRoot, id);
+    const lease = await acquireHeavyCheckLock(storage, id);
     try {
       assertExecutionStillRequested();
       const currentRevision = currentControllerCheckRevision(repoRoot);
       if (currentRevision !== revision) {
         throw new Error(`repository revision changed while heavy check ${id} was queued; resubmit the check`);
       }
-      const refreshed = readControllerCheckEvidenceByKey(repoRoot, id, cacheKey)
-        ?? readLatestControllerCheckEvidence(repoRoot, id);
+      const refreshed = readControllerCheckEvidenceByKey(storage, id, cacheKey)
+        ?? readLatestControllerCheckEvidence(repoRoot, id, storage);
       if (refreshed?.cacheKey === cacheKey && refreshed.ok) {
         return {
           check,
@@ -1104,7 +1493,7 @@ export function runControllerCheckAsync(
           stderr: refreshed.stderr,
           command: refreshed.command,
           executedAt: refreshed.executedAt,
-          artifactPath: relative(repoRoot, evidencePath(repoRoot, id)).replace(/\\/g, '/'),
+          artifactPath: logicalEvidenceArtifactPath(id),
           cacheHit: true,
           validatedRevision: refreshed.validatedRevision ?? refreshed.completedRevision ?? refreshed.revision ?? revision,
           originalExecutedAt: refreshed.originalExecutedAt ?? refreshed.executedAt,