@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/execution/process-runtime/resource-claims.ts

@@ -6,8 +6,13 @@
 import type { ResourceClaimSpec } from '../jobs/types';
 import { readFileSync } from 'fs';
 import { join } from 'path';
-import type { ControllerCheckEffects } from '../../../cli/controller/check-runner';
-import { classifyRepositoryCommand, fixedShellWrapperCommand } from '../../../cli/repositories/command-classifier';
+import type { ControllerCheckEffects, ControllerCheckExecutionAuthority } from '../../../cli/controller/check-runner';
+import {
+  classifyRepositoryCommand,
+  fixedShellWrapperCommand,
+  shellSegments,
+  shellWordsPreservingQuotes,
+} from '../../../cli/repositories/command-classifier';
 import { normalizeRepositoryCommand } from '../../../cli/repositories/command-normalization';
 import { isFocusedCheckCommand } from '../thin-harness/execution-router';
 import type { ProcessResourceClaim } from './types';
@@ -30,8 +35,12 @@ export type ResourceClaimKind =
   | 'heavy_check'
   | 'workspace_write';
 
-function checkoutScope(checkoutId?: string): string {
-  return checkoutId?.trim() || 'active';
+function checkoutScope(checkoutId?: string, repoId?: string): string {
+  const checkout = checkoutId?.trim();
+  if (checkout) return checkout;
+  const repository = repoId?.trim();
+  if (repository) return `repository-${repository.replace(/[^a-zA-Z0-9._-]+/g, '-')}`;
+  throw new Error('RESOURCE_CLAIM_PLACEMENT_REQUIRED');
 }
 
 /**
@@ -39,24 +48,24 @@ function checkoutScope(checkoutId?: string): string {
  * Conflict is expressed via mode (read vs write), not a separate key.
  * Legacy workspace-read:* keys are normalized in claims/conflicts.ts.
  */
-export function claimWorkspaceRead(checkoutId?: string): ResourceClaimSpec {
-  return { resourceKey: `workspace:${checkoutScope(checkoutId)}`, mode: 'read' };
+export function claimWorkspaceRead(checkoutId?: string, repoId?: string): ResourceClaimSpec {
+  return { resourceKey: `workspace:${checkoutScope(checkoutId, repoId)}`, mode: 'read' };
 }
 
-export function claimPathRead(path: string, checkoutId?: string): ResourceClaimSpec {
-  if (path === '.') return claimWorkspaceRead(checkoutId);
+export function claimPathRead(path: string, checkoutId?: string, repoId?: string): ResourceClaimSpec {
+  if (path === '.') return claimWorkspaceRead(checkoutId, repoId);
   const normalized = normalizeClaimPath(path);
-  if (!normalized) return claimWorkspaceRead(checkoutId);
-  return { resourceKey: `path:${checkoutScope(checkoutId)}:${normalized}`, mode: 'read' };
+  if (!normalized) return claimWorkspaceRead(checkoutId, repoId);
+  return { resourceKey: `path:${checkoutScope(checkoutId, repoId)}:${normalized}`, mode: 'read' };
 }
 
-export function claimPathWrite(path: string, checkoutId?: string): ResourceClaimSpec {
+export function claimPathWrite(path: string, checkoutId?: string, repoId?: string): ResourceClaimSpec {
   const normalized = normalizeClaimPath(path);
   if (!normalized) {
     // Unsafe / ambiguous path → escalate to whole-checkout workspace write.
-    return claimWorkspaceWrite(checkoutId);
+    return claimWorkspaceWrite(checkoutId, repoId);
   }
-  return { resourceKey: `path:${checkoutScope(checkoutId)}:${normalized}`, mode: 'write' };
+  return { resourceKey: `path:${checkoutScope(checkoutId, repoId)}:${normalized}`, mode: 'write' };
 }
 
 export function claimBuildCacheRead(repoId: string): ResourceClaimSpec {
@@ -67,12 +76,12 @@ export function claimBuildCacheWrite(repoId: string): ResourceClaimSpec {
   return { resourceKey: `build-cache:${repoId}`, mode: 'write' };
 }
 
-export function claimGitIndexRead(checkoutId?: string): ResourceClaimSpec {
-  return { resourceKey: `git-index:${checkoutScope(checkoutId)}`, mode: 'read' };
+export function claimGitIndexRead(checkoutId?: string, repoId?: string): ResourceClaimSpec {
+  return { resourceKey: `git-index:${checkoutScope(checkoutId, repoId)}`, mode: 'read' };
 }
 
-export function claimGitIndex(checkoutId?: string): ResourceClaimSpec {
-  return { resourceKey: `git-index:${checkoutScope(checkoutId)}`, mode: 'exclusive' };
+export function claimGitIndex(checkoutId?: string, repoId?: string): ResourceClaimSpec {
+  return { resourceKey: `git-index:${checkoutScope(checkoutId, repoId)}`, mode: 'exclusive' };
 }
 
 export function claimGitRefsRead(repoId: string): ResourceClaimSpec {
@@ -87,16 +96,12 @@ export function claimIntegration(repoId: string): ResourceClaimSpec {
   return { resourceKey: `integration:${repoId}`, mode: 'exclusive' };
 }
 
-export function claimRelease(repoId: string): ResourceClaimSpec {
-  return { resourceKey: `release:${repoId}`, mode: 'exclusive' };
+export function claimRelease(_repoId: string): ResourceClaimSpec {
+  return { resourceKey: 'release:runtime-authority', mode: 'exclusive' };
 }
 
-export function claimRemoteMutation(repoId: string): ResourceClaimSpec {
-  return { resourceKey: `remote:${repoId}`, mode: 'exclusive' };
-}
-
-export function claimWorkspaceWrite(checkoutId?: string): ResourceClaimSpec {
-  return { resourceKey: `workspace:${checkoutScope(checkoutId)}`, mode: 'write' };
+export function claimWorkspaceWrite(checkoutId?: string, repoId?: string): ResourceClaimSpec {
+  return { resourceKey: `workspace:${checkoutScope(checkoutId, repoId)}`, mode: 'write' };
 }
 
 export function claimHeavyCheck(repoId: string): ResourceClaimSpec {
@@ -153,7 +158,7 @@ function iosSimulatorTestCommandClaims(
   }
   if (!matches) return undefined;
   return normalizeClaims([
-    claimWorkspaceRead(checkoutId),
+    claimWorkspaceRead(checkoutId, repoId),
     claimBuildCacheWrite(repoId),
     claimHostService('ios-simulator-test', 'write'),
   ]);
@@ -177,7 +182,7 @@ function localHttpServerClaims(command: string | readonly string[]): ResourceCla
   return [claimHostService(`tcp-listen:${bind}:${port}`, 'write')];
 }
 
-function loopbackCurlClaims(command: string | readonly string[], repoId: string): ResourceClaimSpec[] | undefined {
+function loopbackCurlClaims(command: string | readonly string[], _repoId: string): ResourceClaimSpec[] | undefined {
   const canonical = normalizeRepositoryCommand(command);
   if (canonical.kind !== 'argv') return undefined;
   const program = (canonical.executable ?? '').split(/[\\/]/).at(-1)?.toLowerCase();
@@ -193,7 +198,7 @@ function loopbackCurlClaims(command: string | readonly string[], repoId: string)
       return !['127.0.0.1', 'localhost', '::1'].includes(host);
     } catch { return true; }
   })) return undefined;
-  return [claimNetwork(repoId, 'read')];
+  return [claimHostService('tcp-client:loopback', 'read')];
 }
 
 function simpleViteScript(script: string): boolean {
@@ -231,10 +236,56 @@ function viteServiceClaims(
   if (!vite) return undefined;
   return normalizeClaims([
     claimBuildCacheWrite(repoId),
-    claimHostService(`vite:${checkoutScope(checkoutId)}`, 'write'),
+    claimHostService(`vite:${checkoutScope(checkoutId, repoId)}`, 'write'),
   ]);
 }
 
+const HOMEBREW_HOST_MUTATION_SUBCOMMANDS = new Set([
+  'install',
+  'uninstall',
+  'reinstall',
+  'upgrade',
+  'update',
+  'cleanup',
+  'autoremove',
+  'tap',
+  'untap',
+]);
+
+function homebrewHostMutationClaims(command: string | readonly string[]): ResourceClaimSpec[] | undefined {
+  const canonical = normalizeRepositoryCommand(command);
+  let words: string[];
+
+  if (canonical.kind === 'argv') {
+    const argv = [canonical.executable ?? '', ...(canonical.args ?? [])];
+    const wrapped = fixedShellWrapperCommand(argv);
+    if (wrapped) {
+      const segments = shellSegments(wrapped);
+      if (segments.length !== 1) return undefined;
+      words = shellWordsPreservingQuotes(segments[0]!);
+    } else {
+      words = argv;
+    }
+  } else {
+    const segments = shellSegments(canonical.shellCommand ?? '');
+    if (segments.length !== 1) return undefined;
+    words = shellWordsPreservingQuotes(segments[0]!);
+  }
+
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'brew') return undefined;
+  const subcommand = words[1]?.toLowerCase();
+  if (!subcommand || !HOMEBREW_HOST_MUTATION_SUBCOMMANDS.has(subcommand)) return undefined;
+
+  // Keep local formula files, Brewfiles, and other path-shaped operands under
+  // conservative repository workspace coordination. Formula/cask identifiers
+  // are deliberately narrow so an ambiguous command still fails closed.
+  const positional = words.slice(2).filter((arg) => arg && !arg.startsWith('-'));
+  if (positional.some((arg) => !/^[A-Za-z0-9@+_.-]+$/.test(arg))) return undefined;
+
+  return [claimHostService('package-manager:homebrew', 'write')];
+}
+
 function hostOnlyCommandClaims(command: string | readonly string[], repoId: string, checkoutId?: string, repoRoot?: string): ResourceClaimSpec[] | undefined {
   const localServer = localHttpServerClaims(command);
   if (localServer) return localServer;
@@ -242,6 +293,8 @@ function hostOnlyCommandClaims(command: string | readonly string[], repoId: stri
   if (loopbackCurl) return loopbackCurl;
   const vite = viteServiceClaims(command, repoId, checkoutId, repoRoot);
   if (vite) return vite;
+  const homebrew = homebrewHostMutationClaims(command);
+  if (homebrew) return homebrew;
   const canonical = normalizeRepositoryCommand(command);
   if (canonical.kind === 'shell') {
     return browserAppleScriptHeredocClaims(canonical.shellCommand ?? '');
@@ -278,13 +331,10 @@ function hostOnlyCommandClaims(command: string | readonly string[], repoId: stri
   return undefined;
 }
 
-function claimTemp(checkId: string, repoId: string, scope: 'isolated' | 'shared'): ResourceClaimSpec {
+function claimTemp(checkId: string, repoId: string, scope: 'isolated' | 'shared', checkoutId?: string): ResourceClaimSpec {
   const identity = checkId.replace(/[^a-zA-Z0-9._-]+/g, '-');
-  return { resourceKey: scope === 'shared' ? `temp:${repoId}` : `temp:${repoId}:${identity}`, mode: 'write' };
-}
-
-function claimNetwork(repoId: string, mode: 'read' | 'write'): ResourceClaimSpec {
-  return { resourceKey: `network:${repoId}`, mode };
+  const placement = checkoutScope(checkoutId, repoId);
+  return { resourceKey: scope === 'shared' ? `temp:${placement}:shared` : `temp:${placement}:${identity}`, mode: 'write' };
 }
 
 function staticAnalysisCheckId(checkId: string): boolean {
@@ -303,22 +353,23 @@ function claimsForDeclaredCheckEffects(
 ): ResourceClaimSpec[] {
   const claims: ResourceClaimSpec[] = [];
   const hasDeclaredField = Object.keys(effects).length > 0;
-  if (!hasDeclaredField) return [claimWorkspaceWrite(checkoutId)];
+  if (!hasDeclaredField) return [claimWorkspaceWrite(checkoutId, repoId)];
 
   // Missing read scope is unknown, so custom checks fail closed. An explicit
   // reads: [] means the command does not inspect repository content.
-  if (effects.reads === undefined) claims.push(claimWorkspaceWrite(checkoutId));
-  else for (const path of effects.reads) claims.push(claimPathRead(path, checkoutId));
-  for (const path of effects.writes ?? []) claims.push(claimPathWrite(path, checkoutId));
+  if (effects.reads === undefined) claims.push(claimWorkspaceWrite(checkoutId, repoId));
+  else for (const path of effects.reads) claims.push(claimPathRead(path, checkoutId, repoId));
+  for (const path of effects.writes ?? []) claims.push(claimPathWrite(path, checkoutId, repoId));
 
   if (effects.cache === 'read') claims.push(claimBuildCacheRead(repoId));
   if (effects.cache === 'write') claims.push(claimBuildCacheWrite(repoId));
-  if (effects.temp) claims.push(claimTemp(checkId, repoId, effects.temp));
-  if (effects.git === 'read') claims.push(claimGitIndexRead(checkoutId), claimGitRefsRead(repoId));
-  if (effects.git === 'index') claims.push(claimGitIndex(checkoutId));
+  if (effects.temp) claims.push(claimTemp(checkId, repoId, effects.temp, checkoutId));
+  if (effects.git === 'read') claims.push(claimGitIndexRead(checkoutId, repoId), claimGitRefsRead(repoId));
+  if (effects.git === 'index') claims.push(claimGitIndex(checkoutId, repoId));
   if (effects.git === 'refs') claims.push(claimGitRefs(repoId));
-  if (effects.git === 'write') claims.push(claimWorkspaceWrite(checkoutId), claimGitIndex(checkoutId), claimGitRefs(repoId));
-  if (effects.network) claims.push(claimNetwork(repoId, effects.network));
+  if (effects.git === 'write') claims.push(claimWorkspaceWrite(checkoutId, repoId), claimGitIndex(checkoutId, repoId), claimGitRefs(repoId));
+  // A generic network bit has no concrete endpoint/provider identity. Checks
+  // that need serialization must name the real shared target in hostServices.
   for (const service of effects.hostServices ?? []) claims.push(claimHostService(service, 'write'));
 
   return normalizeClaims(claims, { readOnly: claims.every((claim) => claim.mode === 'read') });
@@ -442,15 +493,18 @@ export function claimsForRepositoryCommand(
   if (hostClaims) return hostClaims;
 
   if (classification.risk === 'readonly') {
-    return [claimWorkspaceRead(checkoutId)];
+    return [claimWorkspaceRead(checkoutId, repoId)];
   }
   if (classification.risk === 'remote_write') {
-    return [claimRemoteMutation(repoId), claimGitRefs(repoId)];
+    // Raw command text cannot prove the external provider/account target. Keep
+    // the concrete local Git-ref fence; typed domain APIs own remote-effect
+    // identity, idempotency and provider-target serialization.
+    return [claimGitRefs(repoId)];
   }
   if (classification.risk === 'destructive') {
     return [
-      claimWorkspaceWrite(checkoutId),
-      claimGitIndex(checkoutId),
+      claimWorkspaceWrite(checkoutId, repoId),
+      claimGitIndex(checkoutId, repoId),
       claimGitRefs(repoId),
     ];
   }
@@ -459,22 +513,22 @@ export function claimsForRepositoryCommand(
   // while ordinary focused tests are observation unless snapshot-update mode is
   // explicit. Both can share repository source reads without a workspace writer.
   if (isTypedTypeScriptNoEmit(command)) {
-    return [claimWorkspaceRead(checkoutId), claimBuildCacheWrite(repoId)];
+    return [claimWorkspaceRead(checkoutId, repoId), claimBuildCacheWrite(repoId)];
   }
   if (focused) {
-    if (!focusedTestRequestsWorkspaceMutation(command)) return [claimWorkspaceRead(checkoutId)];
-    const claims: ResourceClaimSpec[] = [claimWorkspaceRead(checkoutId)];
-    for (const path of extractLikelyPaths(command).slice(0, 16)) claims.push(claimPathWrite(path, checkoutId));
+    if (!focusedTestRequestsWorkspaceMutation(command)) return [claimWorkspaceRead(checkoutId, repoId)];
+    const claims: ResourceClaimSpec[] = [claimWorkspaceRead(checkoutId, repoId)];
+    for (const path of extractLikelyPaths(command).slice(0, 16)) claims.push(claimPathWrite(path, checkoutId, repoId));
     return normalizeClaims(claims);
   }
   if (looksLikeBuildOrTest(command)) {
     const paths = extractLikelyPaths(command);
     if (paths.length === 0) {
       // Broad or opaque build/test commands may create arbitrary artifacts.
-      return [claimWorkspaceWrite(checkoutId), claimBuildCacheWrite(repoId)];
+      return [claimWorkspaceWrite(checkoutId, repoId), claimBuildCacheWrite(repoId)];
     }
-    const claims: ResourceClaimSpec[] = [claimWorkspaceRead(checkoutId), claimBuildCacheWrite(repoId)];
-    for (const path of paths.slice(0, 16)) claims.push(claimPathWrite(path, checkoutId));
+    const claims: ResourceClaimSpec[] = [claimWorkspaceRead(checkoutId, repoId), claimBuildCacheWrite(repoId)];
+    for (const path of paths.slice(0, 16)) claims.push(claimPathWrite(path, checkoutId, repoId));
     return normalizeClaims(claims);
   }
 
@@ -484,23 +538,26 @@ export function claimsForRepositoryCommand(
   const sub = canonical.kind === 'argv' ? canonical.args?.[0]?.toLowerCase() : undefined;
   if (program === 'git') {
     if (sub === 'add' || sub === 'rm' || sub === 'mv' || sub === 'restore' || sub === 'apply') {
-      return [claimGitIndex(checkoutId), claimWorkspaceWrite(checkoutId)];
+      return [claimGitIndex(checkoutId, repoId), claimWorkspaceWrite(checkoutId, repoId)];
     }
     if (sub === 'commit' || sub === 'merge' || sub === 'rebase' || sub === 'cherry-pick' || sub === 'revert') {
-      return [claimGitIndex(checkoutId), claimGitRefs(repoId), claimWorkspaceWrite(checkoutId)];
+      return [claimGitIndex(checkoutId, repoId), claimGitRefs(repoId), claimWorkspaceWrite(checkoutId, repoId)];
     }
     if (sub === 'checkout' || sub === 'switch' || sub === 'branch' || sub === 'tag') {
-      return [claimGitRefs(repoId), claimWorkspaceWrite(checkoutId)];
+      return [claimGitRefs(repoId), claimWorkspaceWrite(checkoutId, repoId)];
     }
   }
 
   // Unknown mutating command — workspace write, not heavy-check exclusive.
-  return [claimWorkspaceWrite(checkoutId)];
+  return [claimWorkspaceWrite(checkoutId, repoId)];
 }
 
 /**
  * Claims for run_check by check id / command.
- * Only full CI / release / multi-phase checks take heavy-check exclusive.
+ * Full CI/release/multi-phase checks and compiler-intensive latency gates take
+ * heavy-check exclusive. The latter fence protects performance assertions from
+ * same-repository CPU/JSC contention; it does not replace their real read/cache
+ * claims.
  */
 export function claimsForCheck(
   checkId: string,
@@ -508,19 +565,23 @@ export function claimsForCheck(
   repoId: string,
   checkoutId?: string,
   effects?: ControllerCheckEffects,
+  executionAuthority?: ControllerCheckExecutionAuthority,
 ): ResourceClaimSpec[] {
-  const heavy = /(?:^|:)(?:test(?::coverage)?|check:(?:ci|forge-runtime|public-export|release(?:-[a-z0-9-]+)?))$/.test(checkId)
+  const heavy = /(?:^|:)(?:test(?::coverage)?|check:(?:ci|forge-runtime|public-export|release(?:-[a-z0-9-]+)?|type|typescript-navigation))$/.test(checkId)
     || /release|migration|integrate/i.test(checkId);
   const baseClaims = effects
     ? claimsForDeclaredCheckEffects(checkId, effects, repoId, checkoutId)
     : staticAnalysisCheckId(checkId)
-      ? [claimWorkspaceRead(checkoutId), claimBuildCacheWrite(repoId)]
+      ? [claimWorkspaceRead(checkoutId, repoId), claimBuildCacheWrite(repoId)]
       : command && command.length > 0
         ? claimsForRepositoryCommand(command, repoId, checkoutId)
-        : [claimWorkspaceWrite(checkoutId)];
+        : [claimWorkspaceWrite(checkoutId, repoId)];
   // Heavy-check is an additional cross-check serialization fence, not a
   // substitute for the resources the check actually reads or writes.
-  return heavy ? normalizeClaims([claimHeavyCheck(repoId), ...baseClaims]) : baseClaims;
+  const liveAuthorityClaims = executionAuthority === 'live_controller_home' ? [claimRelease(repoId)] : [];
+  return heavy
+    ? normalizeClaims([claimHeavyCheck(repoId), ...liveAuthorityClaims, ...baseClaims])
+    : normalizeClaims([...liveAuthorityClaims, ...baseClaims]);
 }
 
 export function scopeResourceClaims(

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

@@ -30,6 +30,9 @@ import {
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { capProcessOutput } from '../../../effects/process-runner';
+import { getRepository, selectRepositoryCheckout } from '../../../cli/repositories/registry';
+import { recordProcessHandleIndexEntry } from './handle-index';
+import { processScopeExecutionTarget, processScopeFromKey } from './process-scope';
 import { redactSensitiveText, sanitizeSensitiveTextFileInPlace } from '../../evidence/sensitive-output';
 import { isProcessAlive, terminateProcessTree } from '../../shared/process-tree';
 import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../../shared/process-environment';
@@ -54,6 +57,13 @@ import {
   updateProcessRecord,
 } from './store';
 import { assertExecutionIdentity } from '../../control-plane/execution/execution-identity';
+import { settleWorkHandleExpectedHeadAfterRepositoryCommand } from '../../control-plane/execution/work-head-settlement';
+import {
+  clearWorkExecutionConcurrencyWaitForAttempt,
+  evaluateManagedProcessWorkCompatibility,
+  executionConcurrencyWaitProjection,
+  recordWorkExecutionConcurrencyWait,
+} from '../../control-plane/concurrency/work-execution-concurrency';
 import {
   DEFAULT_INTERACTIVE_WAIT_MS,
   DEFAULT_MAX_OUTPUT_BYTES,
@@ -487,7 +497,7 @@ export function releaseProcessLeasesOnce(
       repoId,
       processId,
       expectedRefs,
-      { visibility: 'ephemeral', notifyScheduler: false, invalidateProjection: false, emitRuntimeEvent: false },
+      { visibility: 'ephemeral', notifyScheduler: Boolean(record.workId), invalidateProjection: false, emitRuntimeEvent: false },
     );
   } catch (error) {
     // Exact-set or token mismatch remains pending and retryable. Failed cleanup
@@ -587,6 +597,38 @@ export function completeProcessFromEvidence(
   const afterTerminal = completion.record ?? getProcessRecord(controllerHome, repoId, processId);
   if (afterTerminal && (completion.ok || completion.reason === 'already_terminal' || afterTerminal.terminalWritten === true)) {
     const released = releaseProcessLeasesOnce(controllerHome, repoId, processId) ?? afterTerminal;
+    // Successful repository mutation settlement is deliberately downstream of
+    // durable terminal persistence. Recovery may repeat this block, but the
+    // WorkHandle CAS plus immutable expectedHead makes reconciliation idempotent.
+    if (
+      released.status === 'succeeded'
+      && released.exitCode === 0
+      && released.cancelled !== true
+      && released.timedOut !== true
+      && released.workId
+      && released.executionIdentity
+    ) {
+      try {
+        const repository = selectRepositoryCheckout(
+          getRepository(released.executionIdentity.repositoryId, controllerHome),
+          released.executionIdentity.checkoutId,
+          { allowArchived: released.executionIdentity.allowArchived },
+        );
+        settleWorkHandleExpectedHeadAfterRepositoryCommand({
+          controllerHome,
+          repository,
+          executionIdentity: released.executionIdentity,
+          workId: released.workId,
+          ok: true,
+          cancelled: false,
+          timedOut: false,
+        });
+      } catch {
+        // Terminal Process evidence remains valid even when its exact historical
+        // checkout is no longer selectable. Never infer authority from active
+        // checkout/session state; Work finalization will continue to fail closed.
+      }
+    }
     cleanupTerminalRunnerReceipts(released);
     return released;
   }
@@ -737,16 +779,14 @@ export function resolveProcessRunnerRuntime(
   return resolveBunExecutable(execPath, env);
 }
 
-function runnerInvocation(entry: string, descriptorPath: string): { command: string; args: string[] } {
+export function resolveProcessRunnerInvocation(entry: string, descriptorPath: string): { command: string; args: string[] } {
   const scriptEntry = /\.(?:[cm]?js|tsx?)$/i.test(entry);
   let standalone = !scriptEntry && process.env.FORGE_RUNTIME_EXECUTION === 'standalone-binary';
-  if (!scriptEntry && !standalone) {
-    try {
-      const manifest = JSON.parse(readFileSync(join(dirname(entry), 'manifest.json'), 'utf8')) as { executionMode?: unknown };
-      standalone = manifest.executionMode === 'standalone-binary';
-    } catch {
-      /* source and legacy script releases have no execution manifest */
-    }
+  try {
+    const manifest = JSON.parse(readFileSync(join(dirname(entry), 'manifest.json'), 'utf8')) as { executionMode?: unknown };
+    if (manifest.executionMode === 'standalone-binary') standalone = true;
+  } catch {
+    /* source and legacy script releases have no execution manifest */
   }
   const args = ['--descriptor', descriptorPath];
   return standalone
@@ -1043,6 +1083,7 @@ function recordToHandle(
       : completed ? safeProcessText(safeRecord.stderrTail || persistedStderr || '') : undefined,
     stdoutTail: safeRecord.stdoutTail ? safeProcessText(safeRecord.stdoutTail) : undefined,
     stderrTail: safeRecord.stderrTail ? safeProcessText(safeRecord.stderrTail) : undefined,
+    concurrencyWait: safeRecord.concurrencyWait,
     durableSideEffects: {
       executionJobCount: 0,
       localJobCount: 0,
@@ -1061,7 +1102,7 @@ function spawnProcessRunner(descriptor: ProcessCommandDescriptor, descriptorPath
   writeFileSync(descriptorPath, `${JSON.stringify(descriptor, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
   const entry = resolveProcessRunnerEntryPath();
   const useProcessGroup = process.platform !== 'win32';
-  const invocation = runnerInvocation(entry, descriptorPath);
+  const invocation = resolveProcessRunnerInvocation(entry, descriptorPath);
   // Detached so Controller crash does not kill the runner.
   return spawn(invocation.command, invocation.args, {
     cwd: descriptor.command.cwd,
@@ -1185,7 +1226,9 @@ export async function spawnManagedProcess(input: SpawnManagedProcessInput): Prom
     processId,
     repoId: input.repoId,
     checkoutId: input.checkoutId,
+    ...(input.principalId ? { principalId: input.principalId } : {}),
     workId: input.workId,
+    executionIdentity: input.executionIdentity,
     commandId: input.commandId?.trim() || processId,
     requestFingerprint: requestId ? commandFingerprint : undefined,
     checkExecution: input.checkExecution,
@@ -1213,6 +1256,16 @@ export async function spawnManagedProcess(input: SpawnManagedProcessInput): Prom
     logPath: stdoutPath,
   };
   createProcessRecord(record);
+  // Instance-level locator so attachment resolves the target from the handle
+  // instead of replaying placement inputs or scanning repository partitions.
+  recordProcessHandleIndexEntry(input.controllerHome, {
+    processId,
+    lane: 'managed',
+    target: processScopeExecutionTarget(input.controllerHome, processScopeFromKey(input.repoId)),
+    principalId: input.principalId,
+    workId: input.workId,
+    commandId: record.commandId,
+  });
 
   if (input.signal?.aborted) {
     completeProcessFromEvidence(input.controllerHome, input.repoId, processId, fenceToken, {
@@ -1253,6 +1306,61 @@ export async function spawnManagedProcess(input: SpawnManagedProcessInput): Prom
     return recordToHandle(completed!, { completed: true });
   }
 
+  const leaseWaitMs = Math.max(
+    0,
+    Math.min(Math.trunc(input.leaseWaitMs ?? 0), 30_000),
+  );
+  let compatibility = evaluateManagedProcessWorkCompatibility({
+    controllerHome: input.controllerHome,
+    repoId: input.repoId,
+    processId,
+    workId: input.workId,
+    resourceClaims,
+    checkExecution: input.checkExecution,
+    origin: input.origin,
+  });
+  if (!compatibility.compatible && !compatibility.hardBlocked && leaseWaitMs > 0) {
+    const semanticDeadline = Date.now() + leaseWaitMs;
+    while (!compatibility.compatible && !compatibility.hardBlocked && Date.now() < semanticDeadline) {
+      if (input.signal?.aborted) break;
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 50));
+      compatibility = evaluateManagedProcessWorkCompatibility({
+        controllerHome: input.controllerHome,
+        repoId: input.repoId,
+        processId,
+        workId: input.workId,
+        resourceClaims,
+        checkExecution: input.checkExecution,
+        origin: input.origin,
+      });
+    }
+  }
+  if (!compatibility.compatible && compatibility.wait) {
+    recordWorkExecutionConcurrencyWait({
+      controllerHome: input.controllerHome,
+      repoId: input.repoId,
+      workId: input.workId,
+      attemptId: processId,
+      wait: compatibility.wait,
+      resourceClaims,
+      leaseRepoId: input.repoId,
+    });
+    updateProcessRecord(input.controllerHome, input.repoId, processId, { concurrencyWait: compatibility.wait });
+    const code = compatibility.hardBlocked ? 'PROCESS_WORK_COMPATIBILITY_INVALID' : 'PROCESS_WORK_COMPATIBILITY_WAIT';
+    completeProcessFromEvidence(input.controllerHome, input.repoId, processId, fenceToken, {
+      status: 'failed',
+      exitCode: 1,
+      errorMessage: `${code}: ${compatibility.wait.blockerCode}`,
+      exitReceiptPath,
+    }, { authority: 'durable_pre_spawn_abandonment' });
+    const blocked = getProcessRecord(input.controllerHome, input.repoId, processId)!;
+    return recordToHandle(blocked, {
+      completed: true,
+      stdout: '',
+      stderr: blocked.error?.message ?? `${code}: ${compatibility.wait.blockerCode}`,
+    });
+  }
+
   // Acquire real execution leases BEFORE spawning the runner. Fail closed on conflict.
   let leaseRefs: ProcessLeaseRef[] = [];
   if (resourceClaims.length > 0) {
@@ -1313,10 +1421,6 @@ export async function spawnManagedProcess(input: SpawnManagedProcessInput): Prom
     // Minimal bounded queue behavior: when the caller opts in, wait for
     // conflicting leases to release instead of failing immediately. The Lease
     // store remains the single conflict authority; this loop only polls it.
-    const leaseWaitMs = Math.max(
-      0,
-      Math.min(Math.trunc(input.leaseWaitMs ?? 0), 30_000),
-    );
     if (!acquisition.acquired && leaseWaitMs > 0) {
       const leaseDeadline = Date.now() + leaseWaitMs;
       while (!acquisition.acquired && Date.now() < leaseDeadline) {
@@ -1338,6 +1442,31 @@ export async function spawnManagedProcess(input: SpawnManagedProcessInput): Prom
       }
     }
     if (!acquisition.acquired) {
+      const resourceKeys = [...new Set(acquisition.blockers.map((blocker) => blocker.resourceKey))].sort();
+      const blockingWorkId = acquisition.blockers
+        .map((blocker) => blocker.ownerJobId.startsWith('process:')
+          ? getProcessRecord(input.controllerHome, input.repoId, blocker.ownerJobId.slice('process:'.length))?.workId
+          : undefined)
+        .find((value): value is string => Boolean(value));
+      const wait = executionConcurrencyWaitProjection({
+        source: 'resource_lease',
+        blockerCode: 'resource_claim_conflict',
+        disposition: 'wait',
+        blockingWorkId,
+        semanticScopeKeys: [],
+        resourceKeys,
+        wakeTrigger: { kind: 'resource_release', resourceKeys },
+      });
+      recordWorkExecutionConcurrencyWait({
+        controllerHome: input.controllerHome,
+        repoId: input.repoId,
+        workId: input.workId,
+        attemptId: processId,
+        wait,
+        resourceClaims,
+        leaseRepoId: input.repoId,
+    });
+      updateProcessRecord(input.controllerHome, input.repoId, processId, { concurrencyWait: wait });
       const blockers = acquisition.blockers
         .map((b) => `${b.resourceKey}@${b.ownerJobId}`)
         .join(', ');
@@ -1363,7 +1492,8 @@ export async function spawnManagedProcess(input: SpawnManagedProcessInput): Prom
       checkoutId: lease.checkoutId,
       workId: lease.workId,
     }));
-    updateProcessRecord(input.controllerHome, input.repoId, processId, { leaseRefs });
+    clearWorkExecutionConcurrencyWaitForAttempt({ controllerHome: input.controllerHome, repoId: input.repoId, workId: input.workId, attemptId: processId });
+    updateProcessRecord(input.controllerHome, input.repoId, processId, { leaseRefs, concurrencyWait: undefined });
   }
 
   const descriptor: ProcessCommandDescriptor = {
@@ -1372,6 +1502,7 @@ export async function spawnManagedProcess(input: SpawnManagedProcessInput): Prom
     repoId: input.repoId,
     controllerHome: input.controllerHome,
     command,
+    ...(input.trustedRuntimeChild ? { trustedRuntimeChild: input.trustedRuntimeChild } : {}),
     timeoutMs,
     maxStdoutBytes: maxOutputBytes,
     maxStderrBytes: maxOutputBytes,
@@ -1510,6 +1641,18 @@ function applyReceiptIfPresent(
   }, { authority: 'durable_exit_receipt' });
 }
 
+
+function reconcileObservedTerminalProcess(
+  controllerHome: string,
+  repoId: string,
+  record: ManagedProcessRecord,
+): ManagedProcessRecord {
+  if (record.terminalWritten !== true) return record;
+  const reconciled = releaseProcessLeasesOnce(controllerHome, repoId, record.processId) ?? record;
+  cleanupTerminalRunnerReceipts(reconciled);
+  return reconciled;
+}
+
 export function getProcessHandle(
   controllerHome: string,
   repoId: string,
@@ -1517,6 +1660,9 @@ export function getProcessHandle(
 ): ProcessHandle | undefined {
   const record = getProcessRecord(controllerHome, repoId, processId);
   if (!record) return undefined;
+  if (record.terminalWritten === true) {
+    return recordToHandle(reconcileObservedTerminalProcess(controllerHome, repoId, record), { completed: true });
+  }
   if (isManagedProcessActive(record) && !liveMonitors.has(processId)) {
     const fromReceipt = applyReceiptIfPresent(controllerHome, repoId, processId, record);
     if (fromReceipt) return recordToHandle(fromReceipt, { completed: true });
@@ -1539,7 +1685,9 @@ export async function waitForProcess(
 ): Promise<ProcessHandle> {
   const existing = getProcessRecord(controllerHome, repoId, processId);
   if (!existing) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
-  if (existing.terminalWritten) return recordToHandle(existing, { completed: true });
+  if (existing.terminalWritten) {
+    return recordToHandle(reconcileObservedTerminalProcess(controllerHome, repoId, existing), { completed: true });
+  }
 
   const monitor = liveMonitors.get(processId);
   if (monitor) {
@@ -1627,7 +1775,9 @@ export async function cancelProcess(
 ): Promise<ProcessHandle> {
   const record = getProcessRecord(controllerHome, repoId, processId);
   if (!record) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
-  if (record.terminalWritten) return recordToHandle(record, { completed: true });
+  if (record.terminalWritten) {
+    return recordToHandle(reconcileObservedTerminalProcess(controllerHome, repoId, record), { completed: true });
+  }
 
   // Process control is itself a writer mutation. Fence BEFORE sending any
   // signal so a passive/stale runtime cannot kill the active runtime's work.