@moretea-labs/forge 1.6.0 → 1.7.1

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

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, realpathSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import type { RepositoryRecord } from '../../cli/repositories/types';
@@ -14,6 +14,7 @@ import { branchSlugSegment, validateBranchName } from '../../cli/repositories/br
 import { withControllerLock } from '../../cli/repositories/locks';
 import { resolveGitExecutable } from '../../effects/git-executable';
 import { runProcess } from '../../effects/process-runner';
+import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../shared/process-environment';
 import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
 
 export interface EnsureManagedWorkspaceInput {
@@ -21,6 +22,24 @@ export interface EnsureManagedWorkspaceInput {
   title: string;
   baseRef?: string;
   branchName?: string;
+  /** Explicitly materialize lockfile-backed Node dependencies in this isolated worktree. */
+  prepareDependencies?: boolean;
+}
+
+export interface ManagedWorkspaceDependencyBootstrap {
+  packageManager: 'bun' | 'pnpm' | 'npm' | 'yarn';
+  lockfile: string;
+  command: string[];
+}
+
+export interface ManagedWorkspaceDependencyPreparation {
+  mode: 'already_ready' | 'canonical_reuse' | 'installed';
+  nodeModulesRoot: string;
+  canonicalRoot?: string;
+}
+
+export interface ManagedWorkspaceDependencies {
+  materializeDependencies?: (workspaceRoot: string) => void;
 }
 
 export interface ManagedWorkspace {
@@ -73,6 +92,180 @@ 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;
+  const lockCandidates = [
+    ['bun', 'bun.lock', ['bun', 'install', '--frozen-lockfile']],
+    ['bun', 'bun.lockb', ['bun', 'install', '--frozen-lockfile']],
+    ['pnpm', 'pnpm-lock.yaml', ['pnpm', 'install', '--frozen-lockfile']],
+    ['npm', 'package-lock.json', ['npm', 'ci']],
+    ['yarn', 'yarn.lock', ['yarn', 'install', '--frozen-lockfile']],
+  ] as const;
+  const detected = lockCandidates.find(([, lockfile]) => existsSync(join(repoRoot, lockfile)));
+  if (!detected) return undefined;
+  return { packageManager: detected[0], lockfile: detected[1], command: [...detected[2]] };
+}
+
+const DEPENDENCY_REUSE_CONFIG_PATHS = [
+  '.npmrc',
+  'bunfig.toml',
+  'pnpm-workspace.yaml',
+  '.yarnrc.yml',
+] as const;
+
+function dependencyInputMatches(leftRoot: string, rightRoot: string, path: string): boolean {
+  const left = join(leftRoot, path);
+  const right = join(rightRoot, path);
+  const leftExists = existsSync(left);
+  const rightExists = existsSync(right);
+  if (leftExists !== rightExists) return false;
+  return !leftExists || readFileSync(left).equals(readFileSync(right));
+}
+
+function linkedWorkspaceCanonicalRoot(repoRoot: string): string | undefined {
+  const common = runProcess(resolveGitExecutable(), ['-C', repoRoot, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  if (!common.ok || !common.stdout.trim()) return undefined;
+  const canonicalRoot = dirname(resolve(common.stdout.trim()));
+  if (!existsSync(canonicalRoot)) return undefined;
+  try {
+    if (realpathSync(canonicalRoot) === realpathSync(repoRoot)) return undefined;
+  } catch {
+    return undefined;
+  }
+  const topLevel = runProcess(resolveGitExecutable(), ['-C', canonicalRoot, 'rev-parse', '--show-toplevel'], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  if (!topLevel.ok || !topLevel.stdout.trim()) return undefined;
+  try {
+    return realpathSync(topLevel.stdout.trim()) === realpathSync(canonicalRoot) ? canonicalRoot : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveManagedWorkspaceCanonicalDependencies(repoRoot: string): {
+  canonicalRoot: string;
+  nodeModulesRoot: string;
+} | undefined {
+  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  if (!bootstrap) return undefined;
+  const canonicalRoot = linkedWorkspaceCanonicalRoot(repoRoot);
+  if (!canonicalRoot) return undefined;
+  const nodeModulesRoot = join(canonicalRoot, 'node_modules');
+  if (!existsSync(nodeModulesRoot)) return undefined;
+  const dependencyInputs = ['package.json', bootstrap.lockfile, ...DEPENDENCY_REUSE_CONFIG_PATHS];
+  if (!dependencyInputs.every((path) => dependencyInputMatches(repoRoot, canonicalRoot, path))) return undefined;
+  return { canonicalRoot, nodeModulesRoot: realpathSync(nodeModulesRoot) };
+}
+
+function packageManifestRequiresDependencyMaterialization(repoRoot: string): boolean {
+  const packagePath = join(repoRoot, 'package.json');
+  if (!existsSync(packagePath)) return false;
+  let manifest: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return true;
+    manifest = parsed as Record<string, unknown>;
+  } catch {
+    // Preserve fail-closed dependency preparation for malformed manifests. The
+    // package manager remains the authority for the concrete parse error once a
+    // supported frozen lockfile is present.
+    return true;
+  }
+
+  const dependencyFields = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+    'bundleDependencies',
+    'bundledDependencies',
+  ] as const;
+  if (dependencyFields.some((field) => {
+    const value = manifest[field];
+    return Array.isArray(value)
+      ? value.length > 0
+      : Boolean(value && typeof value === 'object' && Object.keys(value as Record<string, unknown>).length > 0);
+  })) return true;
+
+  const workspaces = manifest.workspaces;
+  if (Array.isArray(workspaces)) return workspaces.length > 0;
+  if (workspaces && typeof workspaces === 'object') {
+    const packages = (workspaces as Record<string, unknown>).packages;
+    if (Array.isArray(packages)) return packages.length > 0;
+    return Object.keys(workspaces as Record<string, unknown>).length > 0;
+  }
+  return false;
+}
+
+function reuseManagedWorkspaceCanonicalDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  const reusable = resolveManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (!reusable) return undefined;
+  try {
+    symlinkSync(reusable.nodeModulesRoot, nodeModulesRoot, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch (error) {
+    if (!existsSync(nodeModulesRoot)) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_REUSE_FAILED: ${detail}`);
+    }
+  }
+  return {
+    mode: 'canonical_reuse',
+    nodeModulesRoot: realpathSync(nodeModulesRoot),
+    canonicalRoot: reusable.canonicalRoot,
+  };
+}
+
+export function materializeManagedWorkspaceDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  if (!existsSync(join(repoRoot, 'package.json'))) return undefined;
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  if (existsSync(nodeModulesRoot)) {
+    return { mode: 'already_ready', nodeModulesRoot: realpathSync(nodeModulesRoot) };
+  }
+  // A linked worktree may safely reuse canonical dependencies even when the
+  // package manifest itself declares no dependencies. The supported lockfile
+  // and dependency-reuse inputs remain the authority for proving equivalence.
+  const reused = reuseManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (reused) return reused;
+  // A package manifest can define dependency-free scripts (for example a
+  // built-in `node -e` check). Such checks do not need node_modules and must not
+  // be rejected merely because the repository intentionally has no lockfile.
+  if (!packageManifestRequiresDependencyMaterialization(repoRoot)) return undefined;
+  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  if (!bootstrap) {
+    throw new Error('MANAGED_WORKSPACE_DEPENDENCY_LOCK_REQUIRED: package.json declares dependencies but no supported lockfile was found');
+  }
+  const childEnv = repositoryChildProcessEnvironment();
+  const executable = bootstrap.packageManager === 'bun'
+    ? resolveBunExecutable(process.execPath, childEnv)
+    : bootstrap.command[0]!;
+  const result = runProcess(executable, bootstrap.command.slice(1), {
+    cwd: repoRoot,
+    env: childEnv,
+    timeoutMs: 10 * 60_000,
+    maxOutputBytes: 4 * 1024 * 1024,
+  });
+  if (!result.ok) {
+    const detail = result.stderr || result.error || `exit ${result.status}`;
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_INSTALL_FAILED: ${bootstrap.command.join(' ')}: ${detail}`);
+  }
+  if (!existsSync(nodeModulesRoot)) {
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_INSTALL_INCOMPLETE: ${bootstrap.command.join(' ')} completed without node_modules`);
+  }
+  return { mode: 'installed', nodeModulesRoot: realpathSync(nodeModulesRoot) };
+}
+
+export function materializeManagedWorkspaceCheckDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  if (!existsSync(join(repoRoot, 'package.json')) || existsSync(join(repoRoot, 'node_modules'))) return undefined;
+  if (!linkedWorkspaceCanonicalRoot(repoRoot)) return undefined;
+  return materializeManagedWorkspaceDependencies(repoRoot);
+}
+
 function existingWorkspace(path: string, branch: string): boolean {
   if (!existsSync(path)) return false;
   const root = runProcess(resolveGitExecutable(), ['-C', path, 'rev-parse', '--show-toplevel'], {
@@ -109,6 +302,7 @@ export function ensureManagedWorkspace(
   controllerHome: string,
   repository: RepositoryRecord,
   input: EnsureManagedWorkspaceInput,
+  dependencies: ManagedWorkspaceDependencies = {},
 ): ManagedWorkspace {
   const requestId = input.requestId.trim();
   if (!requestId) throw new Error('MANAGED_WORKSPACE_REQUEST_ID_REQUIRED');
@@ -159,6 +353,14 @@ export function ensureManagedWorkspace(
       if (!repositoryCheckoutRootMatches(repository, path)) {
         throw new Error(`MANAGED_WORKSPACE_REPOSITORY_MISMATCH: ${path}`);
       }
+      if (input.prepareDependencies === true) {
+        (dependencies.materializeDependencies ?? materializeManagedWorkspaceDependencies)(path);
+      } else {
+        // Reusing a byte-equivalent canonical dependency tree is cheap and
+        // deterministic, so isolated Work checkouts should get it even when a
+        // full package-manager install was not explicitly requested.
+        reuseManagedWorkspaceCanonicalDependencies(path);
+      }
 
       const record = addRepositoryCheckout({
         repoId: repository.repoId,

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

@@ -1,8 +1,9 @@
 /**
  * Lightweight run_check facade.
  *
- * Short checks complete via Process Runtime and return results directly.
- * Long checks return a Managed Process handle for the same OS process.
+ * Ordinary checks execute through an in-memory lightweight handle and return
+ * within the interactive budget without creating Process/Lease state. Checks
+ * with real Work/Edit/verification consumers keep persisted Process receipts.
  * Multi-phase and release checks require explicit external Controller handling.
  */
 
@@ -15,6 +16,12 @@ import {
 } from '../../../cli/controller/check-runner';
 import { claimsForCheck, scopeResourceClaims, toProcessClaims } from './resource-claims';
 import { spawnManagedProcess, waitForProcess, getProcessHandle } from './runtime';
+import {
+  getLightweightProcessHandle,
+  isLightweightProcessId,
+  startLightweightControllerCheck,
+  waitForLightweightProcess,
+} from './lightweight-managed';
 import type { ProcessHandle } from './types';
 import { DEFAULT_INTERACTIVE_WAIT_MS } from './types';
 import { durationAwareInteractiveWaitMs } from './interactive-admission';
@@ -37,10 +44,14 @@ export interface RunCheckFacadeInput {
    */
   leaseWaitMs?: number;
   requestId?: string;
+  /** Stable caller-owned semantic identity for safely reattaching the same request before rebuilding ephemeral execution inputs. */
+  requestSemanticFingerprint?: string;
   workId?: string;
   commandId?: string;
   /** Force durable workflow (release / multi-phase). */
   forceDurable?: boolean;
+  /** Internal-only: allow an already-authorized external Work Controller to execute a durable-class check through persisted Process Runtime. */
+  allowDurableCheckExecution?: boolean;
   signal?: AbortSignal;
   /** Immutable resolved identity — required; never inferred from main/active/cwd. */
   executionIdentity: ResolvedExecutionIdentity;
@@ -143,8 +154,9 @@ export async function runCheckViaProcessRuntime(
     };
   }
 
-  // Most checks are builds/tests; return their existing Process handle at once.
-  // Only predictable shell primitives keep a short synchronous admission.
+  // 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 interactiveWaitMs = durationAwareInteractiveWaitMs(
     check.command,
     input.interactiveWaitMs,
@@ -156,6 +168,14 @@ export async function runCheckViaProcessRuntime(
       ? Math.max(1_000, Math.trunc(input.timeoutMs))
       : check.timeoutMs,
   );
+  const durableVerificationBinding = Boolean(
+    input.workId
+    || input.verificationSnapshot
+    || input.verificationBinding?.executionSessionId
+    || input.verificationBinding?.editSessionId
+    || input.verificationBinding?.issueId
+    || input.verificationBinding?.taskId,
+  );
   if (!input.executionIdentity) {
     throw new Error('EXECUTION_IDENTITY_REQUIRED: run_check requires an immutable executionIdentity');
   }
@@ -170,6 +190,27 @@ export async function runCheckViaProcessRuntime(
       `CHECKOUT_ROUTE_MISMATCH: check checkout ${input.checkoutId} differs from identity ${executionIdentity.checkoutId}`,
     );
   }
+  if (!durableVerificationBinding) {
+    const lightweight = await startLightweightControllerCheck({
+      controllerHome: input.controllerHome,
+      repoId: input.repoId,
+      repoRoot: input.repoRoot,
+      checkId: input.checkId,
+      interactiveWaitMs,
+      timeoutMs,
+      workId: input.workId,
+      commandId: input.commandId ?? input.requestId,
+    });
+    const handle = lightweight.handle;
+    return {
+      mode: handle.completed ? 'direct' : 'managed',
+      checkId: input.checkId,
+      check,
+      process: handle,
+      ok: handle.completed ? handle.ok : undefined,
+      durableSideEffects: emptyEffects,
+    };
+  }
   const claims = scopeResourceClaims(
     claimsForCheck(
       input.checkId,
@@ -252,6 +293,9 @@ export async function waitForCheckProcess(
   processId: string,
   timeoutMs?: number,
 ): Promise<ProcessHandle> {
+  if (isLightweightProcessId(processId)) {
+    return waitForLightweightProcess(controllerHome, repoId, processId, { timeoutMs });
+  }
   return waitForProcess(controllerHome, repoId, processId, { timeoutMs });
 }
 
@@ -260,6 +304,9 @@ export function getCheckProcessHandle(
   repoId: string,
   processId: string,
 ): ProcessHandle | undefined {
+  if (isLightweightProcessId(processId)) {
+    return getLightweightProcessHandle(controllerHome, repoId, processId);
+  }
   return getProcessHandle(controllerHome, repoId, processId);
 }
 

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

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { processLogDir } from './store';
+import type { ManagedProcessRecord } from './types';
 
 export interface PersistedCheckResultReceipt {
   schemaVersion: 1;
@@ -51,3 +52,90 @@ export function readPersistedCheckResultReceipt(path: string | undefined): Persi
     return undefined;
   }
 }
+
+export type PersistedCheckTerminalEvidenceState =
+  | 'matched'
+  | 'process_runtime_failed_before_result'
+  | 'missing'
+  | 'mismatch';
+
+export interface PersistedCheckTerminalEvidence {
+  state: PersistedCheckTerminalEvidenceState;
+  failureClass?: PersistedCheckResultReceipt['failureClass'];
+  warning?: string;
+  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
+ * before that result exists (for example PROCESS_LEASE_CONFLICT); such a
+ * Process is infrastructure failure, never evidence that repository checks
+ * 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(
+    structured
+    && record.checkExecution
+    && structured.checkId === expectedCheckId
+    && structured.cacheKey === record.checkExecution.cacheKey,
+  );
+  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,

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

@@ -0,0 +1,114 @@
+import type { ControllerCheck } from '../../../cli/controller/check-runner';
+import type { ResourceClaimSpec } from '../jobs/types';
+import { resourceClaimsConflict } from '../../resources/claims/conflicts';
+import { claimsForCheck } from './resource-claims';
+
+export interface CheckExecutionWave {
+  wave: number;
+  checkIds: string[];
+  parallelSafe: boolean;
+}
+
+export interface CheckExecutionConflict {
+  leftCheckId: string;
+  rightCheckId: string;
+  resources: Array<{
+    left: Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>;
+    right: Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>;
+  }>;
+}
+
+interface ScheduledCheck {
+  check: ControllerCheck;
+  claims: ResourceClaimSpec[];
+}
+
+function conflictingResources(left: ScheduledCheck, right: ScheduledCheck): CheckExecutionConflict['resources'] {
+  const conflicts: CheckExecutionConflict['resources'] = [];
+  for (const leftClaim of left.claims) {
+    for (const rightClaim of right.claims) {
+      if (!resourceClaimsConflict(leftClaim, rightClaim)) continue;
+      conflicts.push({
+        left: { resourceKey: leftClaim.resourceKey, mode: leftClaim.mode },
+        right: { resourceKey: rightClaim.resourceKey, mode: rightClaim.mode },
+      });
+    }
+  }
+  return conflicts;
+}
+
+/**
+ * Produce deterministic execution waves from the exact same resource-claim model
+ * used by Process Runtime. Checks in one wave may overlap; waves run in order.
+ * This is advisory scheduling metadata, not a second lease authority.
+ */
+export function buildCheckExecutionSchedule(input: {
+  checks: ControllerCheck[];
+  requestedCheckIds: string[];
+  repoId: string;
+  checkoutId?: string;
+}): {
+  waves: CheckExecutionWave[];
+  conflicts: CheckExecutionConflict[];
+  invalidCheckIds: string[];
+  maxParallel: number;
+  guidance: string[];
+  claimsByCheck: Array<{ checkId: string; claims: Array<Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>> }>;
+} {
+  const byId = new Map(input.checks.map((check) => [check.id, check]));
+  const requested = [...new Set(input.requestedCheckIds.filter(Boolean))];
+  const invalidCheckIds = requested.filter((checkId) => !byId.has(checkId));
+  const scheduled: ScheduledCheck[] = requested.flatMap((checkId) => {
+    const check = byId.get(checkId);
+    if (!check) return [];
+    return [{
+      check,
+      claims: claimsForCheck(check.id, check.command, input.repoId, input.checkoutId, check.effects),
+    }];
+  });
+
+  const conflicts: CheckExecutionConflict[] = [];
+  for (let leftIndex = 0; leftIndex < scheduled.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < scheduled.length; rightIndex += 1) {
+      const left = scheduled[leftIndex]!;
+      const right = scheduled[rightIndex]!;
+      const resources = conflictingResources(left, right);
+      if (resources.length === 0) continue;
+      conflicts.push({ leftCheckId: left.check.id, rightCheckId: right.check.id, resources });
+    }
+  }
+
+  const waves: ScheduledCheck[][] = [];
+  for (const entry of scheduled) {
+    const compatible = waves.find((wave) => wave.every((other) => conflictingResources(entry, other).length === 0));
+    if (compatible) compatible.push(entry);
+    else waves.push([entry]);
+  }
+
+  const projectedWaves = waves.map((wave, index) => ({
+    wave: index + 1,
+    checkIds: wave.map((entry) => entry.check.id),
+    parallelSafe: wave.length > 1,
+  }));
+  const maxParallel = projectedWaves.reduce((max, wave) => Math.max(max, wave.checkIds.length), 0);
+  const guidance: string[] = [];
+  if (projectedWaves.length > 1) {
+    guidance.push('Run check waves in order; only checks within the same wave are resource-compatible for overlap.');
+  } else if (maxParallel > 1) {
+    guidance.push('Requested checks are resource-compatible and may run concurrently for this checkout.');
+  } else if (maxParallel === 1) {
+    guidance.push('Run the requested check as one focused verification unit.');
+  }
+
+  return {
+    waves: projectedWaves,
+    conflicts,
+    invalidCheckIds,
+    maxParallel,
+    guidance,
+    claimsByCheck: scheduled.map((entry) => ({
+      checkId: entry.check.id,
+      claims: entry.claims.map((claim) => ({ resourceKey: claim.resourceKey, mode: claim.mode })),
+    })),
+  };
+}