@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -269,7 +269,7 @@ export async function runPersistedCheckViaProcessRuntime(
       check,
       durable: {
         reason: 'multi_phase_or_release_check_requires_durable_workflow',
-        suggestedOperation: 'Claim the related WorkContract and run this check through an external Controller.',
+        suggestedOperation: 'Run this check through a Work-bound durable verification workflow.',
       },
       durableSideEffects: emptyEffects,
     };
@@ -312,7 +312,7 @@ export async function runPersistedCheckViaProcessRuntime(
   const liveCertification = check.executionAuthority === 'live_controller_home';
   if (liveCertification && input.allowDurableCheckExecution !== true) {
     cleanupVerificationSnapshot();
-    throw new Error('LIVE_CHECK_CONTROLLER_OWNERSHIP_REQUIRED');
+    throw new Error('LIVE_CHECK_DURABLE_AUTHORITY_REQUIRED');
   }
   const liveExecutionStateFingerprint = liveCertification
     ? controllerCheckLiveExecutionStateFingerprint(input.controllerHome)
@@ -422,7 +422,7 @@ export async function runPersistedCheckViaProcessRuntime(
       issueId: input.verificationBinding?.issueId,
       taskId: input.verificationBinding?.taskId,
       checkResultReceiptPath,
-      workVerificationSnapshot: Boolean(verificationSnapshot),
+      ...(verificationSnapshot ? { workVerificationSnapshot: true } : {}),
     },
     signal: input.signal,
   });

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

@@ -33,9 +33,11 @@ import {
   rmSync,
   writeFileSync,
 } from 'fs';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 import { spawn, type ChildProcess } from 'child_process';
 import { repositoryChildProcessEnvironment } from '../../shared/process-environment.ts';
+import { currentRuntimeWriteClaimEnvironment } from '../../root/write-fence.ts';
+import { readRuntimeReleaseAuthority } from '../../root/release-store.ts';
 import { StreamingSensitiveTextRedactor } from '../../evidence/sensitive-output.ts';
 import { PROCESS_RUNNER_RELEASE_CANARY_CHILD_ARG } from './canary.ts';
 
@@ -44,6 +46,7 @@ export interface ProcessCommandDescriptor {
   processId: string;
   repoId: string;
   controllerHome: string;
+  trustedRuntimeChild?: 'plugin_action_sidecar';
   command: {
     kind: 'argv' | 'shell';
     executable?: string;
@@ -101,9 +104,26 @@ function loadDescriptor(path: string): ProcessCommandDescriptor {
   return value;
 }
 
-function spawnCommand(command: ProcessCommandDescriptor['command']): ChildProcess {
+function commandEnvironment(descriptor: ProcessCommandDescriptor): NodeJS.ProcessEnv {
+  const command = descriptor.command;
+  const sanitized = repositoryChildProcessEnvironment({ ...process.env, ...(command.env ?? {}) });
+  if (descriptor.trustedRuntimeChild !== 'plugin_action_sidecar') return sanitized;
+  if (command.kind !== 'argv' || !command.executable) {
+    throw new Error('PROCESS_RUNNER_TRUSTED_RUNTIME_CHILD_INVALID: plugin action sidecar requires argv executable');
+  }
+  const authority = readRuntimeReleaseAuthority(descriptor.controllerHome);
+  if (!authority) throw new Error('PROCESS_RUNNER_TRUSTED_RUNTIME_CHILD_INVALID: Runtime release authority is missing');
+  const expected = resolve(dirname(authority.active.manifestPath), 'forge-plugin-action-sidecar');
+  if (resolve(command.executable) !== expected) {
+    throw new Error(`PROCESS_RUNNER_TRUSTED_RUNTIME_CHILD_INVALID: expected ${expected}`);
+  }
+  return { ...sanitized, ...currentRuntimeWriteClaimEnvironment(descriptor.controllerHome) };
+}
+
+function spawnCommand(descriptor: ProcessCommandDescriptor): ChildProcess {
+  const command = descriptor.command;
   const useProcessGroup = process.platform !== 'win32';
-  const env = repositoryChildProcessEnvironment({ ...process.env, ...(command.env ?? {}) });
+  const env = commandEnvironment(descriptor);
   if (command.kind === 'shell') {
     const shell = process.platform === 'win32' ? 'cmd.exe' : '/bin/bash';
     const shellArgs = process.platform === 'win32'
@@ -316,15 +336,37 @@ export async function runProcessRunnerFromDescriptor(
 
   let spawnedChild: ChildProcess;
   try {
-    spawnedChild = spawnCommand(descriptor.command);
+    spawnedChild = spawnCommand(descriptor);
     child = spawnedChild;
     if (pendingSignal) void killTree(spawnedChild);
   } catch (error) {
     process.removeListener('SIGTERM', onSigterm);
     process.removeListener('SIGINT', onSigint);
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(Buffer.from(`\n[process-runner] pre-spawn error: ${message}\n`));
     stdout.close();
     stderr.close();
-    throw error;
+    const outStats = stdout.stats();
+    const errStats = stderr.stats();
+    const receipt: ProcessRunnerExitReceipt = {
+      schemaVersion: 1,
+      processId: descriptor.processId,
+      exitCode: 1,
+      finishedAt: new Date().toISOString(),
+      startedAt: descriptor.startedAt,
+      stdoutBytes: outStats.totalBytes,
+      stderrBytes: errStats.totalBytes,
+      stdoutStoredBytes: outStats.storedBytes,
+      stderrStoredBytes: errStats.storedBytes,
+      logTruncated: outStats.truncated || errStats.truncated,
+      runnerPid: process.pid,
+      // The exactly-once logical Process attempt reached a deterministic terminal
+      // result before an external child could be spawned; the started claim is
+      // therefore consumed and must never authorize replay.
+      commandExecutedOnce: true,
+    };
+    atomicWrite(descriptor.exitReceiptPath, receipt);
+    return receipt;
   }
 
   const timeoutHandle = setTimeout(() => {

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

@@ -0,0 +1,160 @@
+/**
+ * Canonical Process/Operation storage scope.
+ *
+ * Repository placement is optional context for a process, never its address
+ * space. A process whose target is the Forge instance itself (host-local
+ * command, controller-global operation, ephemeral workspace command) is stored
+ * in the instance partition and is addressed by its process handle only.
+ *
+ * Scope keys are stable partition identifiers:
+ *   - repository scope key is the registered repository id (unchanged on disk)
+ *   - instance scope key is `instance`, which cannot collide with a registered
+ *     repository id (`repo_*`) or workspace id (`workspace_*`)
+ */
+
+import { join } from 'path';
+import {
+  isWorkspaceScopeKey,
+  repositoryControllerRoot,
+  workspaceScopeRoot,
+} from '../../../cli/repositories/controller-home';
+import {
+  forgeInstanceExecutionTarget,
+  repositoryExecutionTarget,
+  resolveProcessExecutionTarget,
+  workspaceExecutionTarget,
+  type ProcessExecutionTarget,
+} from './handle-index';
+
+export const FORGE_INSTANCE_PROCESS_SCOPE_KEY = 'instance';
+/** Reserved prefix for workspace process scopes; registered repository ids are `repo_*`. */
+export { WORKSPACE_SCOPE_PREFIX as WORKSPACE_PROCESS_SCOPE_PREFIX } from '../../../cli/repositories/controller-home';
+
+export interface RepositoryProcessScope {
+  schemaVersion: 1;
+  kind: 'repository';
+  repositoryId: string;
+  checkoutId?: string;
+}
+
+export interface ForgeInstanceProcessScope {
+  schemaVersion: 1;
+  kind: 'forge_instance';
+  forgeInstanceId?: string;
+}
+
+/**
+ * An arbitrary workspace target has no repository semantics, so its processes
+ * live in a workspace partition instead of a repository partition.
+ */
+export interface WorkspaceProcessScope {
+  schemaVersion: 1;
+  kind: 'workspace';
+  workspaceId: string;
+}
+
+export type ProcessScope = RepositoryProcessScope | ForgeInstanceProcessScope | WorkspaceProcessScope;
+
+function requireSegment(value: string, code: string): string {
+  const normalized = value.trim();
+  if (!normalized || normalized.length > 512) throw new Error(code);
+  return normalized;
+}
+
+export function repositoryProcessScope(repositoryId: string, checkoutId?: string): RepositoryProcessScope {
+  const repository = requireSegment(repositoryId, 'PROCESS_SCOPE_REPOSITORY_ID_REQUIRED');
+  if (repository === FORGE_INSTANCE_PROCESS_SCOPE_KEY) throw new Error('PROCESS_SCOPE_REPOSITORY_ID_RESERVED');
+  if (isWorkspaceScopeKey(repository)) throw new Error('PROCESS_SCOPE_REPOSITORY_ID_RESERVED');
+  const checkout = checkoutId?.trim();
+  return { schemaVersion: 1, kind: 'repository', repositoryId: repository, ...(checkout ? { checkoutId: checkout } : {}) };
+}
+
+export function forgeInstanceProcessScope(forgeInstanceId?: string): ForgeInstanceProcessScope {
+  const instanceId = forgeInstanceId?.trim();
+  return { schemaVersion: 1, kind: 'forge_instance', ...(instanceId ? { forgeInstanceId: instanceId } : {}) };
+}
+
+export function workspaceProcessScope(workspaceId: string): WorkspaceProcessScope {
+  return { schemaVersion: 1, kind: 'workspace', workspaceId: requireSegment(workspaceId, 'PROCESS_SCOPE_WORKSPACE_ID_REQUIRED') };
+}
+
+/** Stable storage/attachment partition key for one process scope. */
+export function processScopeKey(scope: ProcessScope): string {
+  if (scope.kind === 'forge_instance') return FORGE_INSTANCE_PROCESS_SCOPE_KEY;
+  if (scope.kind === 'workspace') return requireSegment(scope.workspaceId, 'PROCESS_SCOPE_WORKSPACE_ID_REQUIRED');
+  if (isWorkspaceScopeKey(scope.repositoryId)) throw new Error('PROCESS_SCOPE_REPOSITORY_ID_RESERVED');
+  return requireSegment(scope.repositoryId, 'PROCESS_SCOPE_REPOSITORY_ID_REQUIRED');
+}
+
+/**
+ * Normalize a scope key supplied by a caller. A bare repository id keeps its
+ * established meaning as the repository scope key; `instance` selects the
+ * ForgeInstance partition.
+ */
+export function normalizeProcessScopeKey(value: string): string {
+  const key = requireSegment(value, 'PROCESS_SCOPE_KEY_REQUIRED');
+  return key;
+}
+
+export function processScopeFromKey(key: string): ProcessScope {
+  const normalized = normalizeProcessScopeKey(key);
+  if (normalized === FORGE_INSTANCE_PROCESS_SCOPE_KEY) return forgeInstanceProcessScope();
+  if (isWorkspaceScopeKey(normalized)) return workspaceProcessScope(normalized);
+  return repositoryProcessScope(normalized);
+}
+
+export function isForgeInstanceProcessScopeKey(key: string): boolean {
+  return key.trim() === FORGE_INSTANCE_PROCESS_SCOPE_KEY;
+}
+
+/** An arbitrary workspace target is addressed by its workspace id, never by a repository id. */
+export function isWorkspaceProcessScopeKey(key: string): boolean {
+  return isWorkspaceScopeKey(key);
+}
+
+/** True when the scope key addresses a registered repository partition. */
+export function isRepositoryProcessScopeKey(key: string): boolean {
+  const normalized = key.trim();
+  return normalized.length > 0
+    && normalized !== FORGE_INSTANCE_PROCESS_SCOPE_KEY
+    && !isWorkspaceProcessScopeKey(normalized);
+}
+
+/**
+ * Controller-Home root for one process scope. Repository scopes keep their
+ * existing per-repository layout; instance and workspace scopes own ordinary
+ * sibling partitions so non-repository processes never require a synthetic
+ * repository identity.
+ */
+export function processScopeRoot(controllerHome: string, scopeKey: string): string {
+  const key = normalizeProcessScopeKey(scopeKey);
+  if (isForgeInstanceProcessScopeKey(key)) return join(controllerHome, FORGE_INSTANCE_PROCESS_SCOPE_KEY);
+  if (isWorkspaceProcessScopeKey(key)) return workspaceScopeRoot(controllerHome, key);
+  return repositoryControllerRoot(controllerHome, key);
+}
+
+/** Read-only legacy location for workspace-scoped facts written before the workspace partition existed. */
+export function legacyWorkspaceScopeRoot(controllerHome: string, scopeKey: string): string | undefined {
+  const key = normalizeProcessScopeKey(scopeKey);
+  return isWorkspaceProcessScopeKey(key) ? repositoryControllerRoot(controllerHome, key) : undefined;
+}
+
+/** Handle-index target for one scope, pinned to the serving ForgeInstance when available. */
+export function processScopeExecutionTarget(controllerHome: string, scope: ProcessScope): ProcessExecutionTarget {
+  if (scope.kind === 'repository') return repositoryExecutionTarget(controllerHome, scope.repositoryId, scope.checkoutId);
+  if (scope.kind === 'workspace') return workspaceExecutionTarget(controllerHome, scope.workspaceId);
+  return forgeInstanceExecutionTarget(controllerHome);
+}
+
+/**
+ * Scope key recorded for one process handle. The Process Runtime owns this
+ * instance-level index, so attachment resolves the target from the handle
+ * instead of scanning repositories or replaying placement inputs.
+ */
+export function processScopeKeyForHandle(controllerHome: string, processId: string): string | undefined {
+  const target = resolveProcessExecutionTarget(controllerHome, processId);
+  if (!target) return undefined;
+  if (target.scope === 'forge_instance') return FORGE_INSTANCE_PROCESS_SCOPE_KEY;
+  if (target.scope === 'workspace') return target.workspaceId;
+  return target.repositoryId;
+}

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

@@ -35,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');
 }
 
 /**
@@ -44,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 {
@@ -72,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 {
@@ -92,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 {
@@ -158,7 +158,7 @@ function iosSimulatorTestCommandClaims(
   }
   if (!matches) return undefined;
   return normalizeClaims([
-    claimWorkspaceRead(checkoutId),
+    claimWorkspaceRead(checkoutId, repoId),
     claimBuildCacheWrite(repoId),
     claimHostService('ios-simulator-test', 'write'),
   ]);
@@ -182,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();
@@ -198,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 {
@@ -236,7 +236,7 @@ function viteServiceClaims(
   if (!vite) return undefined;
   return normalizeClaims([
     claimBuildCacheWrite(repoId),
-    claimHostService(`vite:${checkoutScope(checkoutId)}`, 'write'),
+    claimHostService(`vite:${checkoutScope(checkoutId, repoId)}`, 'write'),
   ]);
 }
 
@@ -331,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 {
@@ -356,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') });
@@ -495,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),
     ];
   }
@@ -512,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);
   }
 
@@ -537,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,
@@ -563,15 +567,15 @@ export function claimsForCheck(
   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.
   const liveAuthorityClaims = executionAuthority === 'live_controller_home' ? [claimRelease(repoId)] : [];

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

@@ -31,6 +31,8 @@ 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';
@@ -1224,6 +1226,7 @@ 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,
@@ -1253,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, {
@@ -1489,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,
@@ -1627,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,
@@ -1634,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 });
@@ -1656,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) {
@@ -1744,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.