@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -4,6 +4,7 @@ import { dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import {
   controllerCheckExecutionIdentity,
+  controllerCheckLiveExecutionStateFingerprint,
   listControllerChecks,
   snapshotControllerCheck,
 } from '../../../cli/controller/check-runner';
@@ -16,6 +17,7 @@ import {
 } from '../../../cli/runtime-invocation';
 import { readRuntimeGeneration, resolveControllerRuntimeSourceRoot } from '../../control-plane/runtime-generation';
 import { cleanupWorkVerificationSnapshot, materializeWorkVerificationSnapshot } from '../../control-plane/execution/work-verification-snapshot';
+import { resolveBunExecutable } from '../../shared/process-environment';
 import {
   checkRequiresDurableWorkflow,
   processCheckSemanticScopeKey,
@@ -37,6 +39,7 @@ import { durationAwareInteractiveWaitMs } from './interactive-admission';
 export const DEFAULT_WORK_CHECK_LEASE_WAIT_MS = 30_000;
 
 const PERSISTED_CHECK_SOURCE_ENTRY = 'src/runtime/execution/process-runtime/check-runner-sidecar.ts';
+const PERSISTED_CHECK_NODE_LOADER = 'src/runtime/shared/node-ts-loader.mjs';
 
 export function resolvePersistedCheckCliInvocation(
   cliEntry: string,
@@ -78,6 +81,52 @@ export function resolveRuntimeCliEntry(controllerHome?: string): string {
   return resolveRuntimeCliTarget(controllerHome).entry;
 }
 
+export function shouldUseCandidatePersistedCheckRunner(input: {
+  repoId: string;
+  runtimeSourceRepoId?: string;
+  verificationSnapshot: boolean;
+  liveCertification: boolean;
+}): boolean {
+  return input.verificationSnapshot
+    && !input.liveCertification
+    && Boolean(input.runtimeSourceRepoId && input.runtimeSourceRepoId === input.repoId);
+}
+
+export function resolveCandidatePersistedCheckRunnerTarget(
+  candidateRoot: string,
+  sourceRevision: string,
+  options: { bunExecutable?: string; entryExists?: (path: string) => boolean } = {},
+): { cliTarget: CliRuntimeTarget; runtimeExecutable: string; executionStateFingerprint: string } {
+  const root = resolve(candidateRoot);
+  const revision = sourceRevision.trim();
+  if (!revision) throw new Error('PERSISTED_CHECK_CANDIDATE_REVISION_REQUIRED');
+  const entryExists = options.entryExists ?? existsSync;
+  const sourceEntry = resolve(root, PERSISTED_CHECK_SOURCE_ENTRY);
+  if (!entryExists(sourceEntry)) {
+    throw new Error(`PERSISTED_CHECK_CANDIDATE_RUNNER_MISSING: ${sourceEntry}`);
+  }
+  const runtimeExecutable = options.bunExecutable?.trim() || resolveBunExecutable();
+  const cliTarget: CliRuntimeTarget = {
+    entry: sourceEntry,
+    cwd: root,
+    runtimeKind: 'bun_source',
+    sourceRevision: revision,
+    immutable: false,
+    explanation: 'self-hosting Work verification snapshot candidate Check Runner',
+  };
+  const executionStateFingerprint = createHash('sha256')
+    .update(JSON.stringify({
+      schemaVersion: 1,
+      authority: 'self_hosting_work_verification_candidate',
+      runnerEntry: PERSISTED_CHECK_SOURCE_ENTRY,
+      runtimeKind: cliTarget.runtimeKind,
+      sourceRevision: revision,
+    }))
+    .digest('hex')
+    .slice(0, 24);
+  return { cliTarget, runtimeExecutable, executionStateFingerprint };
+}
+
 export function persistedCheckSemanticScopeKey(
   input: Pick<RunCheckFacadeInput, 'workId' | 'verificationBinding' | 'checkoutId'>,
   reuseScope: 'repository' | 'checkout',
@@ -108,25 +157,35 @@ export function resolvePersistedCheckProcessInvocation(
   if (cliTarget.runtimeKind === 'compiled_bun_release') {
     return { executable, args };
   }
+  const entryExists = options.entryExists ?? existsSync;
   const sourceEntry = resolve(cliTarget.cwd, PERSISTED_CHECK_SOURCE_ENTRY);
-  if (!(options.entryExists ?? existsSync)(sourceEntry)) {
+  if (!entryExists(sourceEntry)) {
     throw new Error(`PERSISTED_CHECK_SOURCE_RUNNER_MISSING: ${sourceEntry}`);
   }
+  let nodeSourceLoaderEntry: string | undefined;
+  if (cliTarget.runtimeKind === 'node_source') {
+    nodeSourceLoaderEntry = resolve(cliTarget.cwd, PERSISTED_CHECK_NODE_LOADER);
+    if (!entryExists(nodeSourceLoaderEntry)) {
+      throw new Error(`PERSISTED_CHECK_NODE_LOADER_MISSING: ${nodeSourceLoaderEntry}`);
+    }
+  }
   return resolvePersistedCheckCliInvocation(sourceEntry, args, {
     runtimeExecutable: executable,
     runtimeKind: cliTarget.runtimeKind,
     sourceRevision: cliTarget.sourceRevision,
     immutable: false,
+    ...(nodeSourceLoaderEntry ? { nodeSourceLoaderEntry } : {}),
     ...(cliTarget.runtimeKind === 'package_launcher' ? { launcherEntry: cliTarget.entry } : {}),
   });
 }
 
 /**
  * Run a registered check through Process Runtime while keeping check-runner
- * evidence authoritative. The managed OS process invokes the same immutable
- * forge CLI bundle with a hidden internal subcommand; that subcommand
- * executes runControllerCheck, writes the Artifact atomically, mirrors bounded
- * stdout/stderr, and exits with the exact check status.
+ * evidence authoritative. Ordinary repositories and live-runtime certification
+ * use the active immutable Runtime runner. Self-hosting Forge Work verification
+ * instead executes the exact candidate snapshot sidecar so pre-cutover evidence
+ * cannot be interpreted by an older Runtime release. Process/lease/receipt
+ * authority remains in the active Runtime in both cases.
  */
 export async function runPersistedCheckViaProcessRuntime(
   input: RunCheckFacadeInput,
@@ -169,6 +228,23 @@ export async function runPersistedCheckViaProcessRuntime(
       };
     }
   }
+  // Check-definition authority belongs to the canonical repository, while Work source
+  // verification may execute from an immutable snapshot that intentionally excludes
+  // machine-local registry files such as .forge/checks.json. Freeze the exact
+  // registered definition before materializing the source-under-test snapshot.
+  const check = listControllerChecks(input.repoRoot).find((entry) => entry.id === input.checkId);
+  if (!check) {
+    return {
+      mode: 'durable',
+      checkId: input.checkId,
+      durable: {
+        reason: 'check_not_found_or_requires_registry_lookup',
+        suggestedOperation: 'list_checks then run_check with a known check_id',
+      },
+      durableSideEffects: emptyEffects,
+    };
+  }
+  const checkSnapshot = snapshotControllerCheck(input.repoRoot, input.checkId);
   const verificationSnapshot = input.verificationSnapshot
     ? materializeWorkVerificationSnapshot({
         controllerHome: input.controllerHome,
@@ -181,18 +257,9 @@ export async function runPersistedCheckViaProcessRuntime(
   const cleanupVerificationSnapshot = () => {
     if (verificationSnapshot) cleanupWorkVerificationSnapshot(verificationSnapshot.root);
   };
-  const check = listControllerChecks(executionRoot).find((entry) => entry.id === input.checkId);
-  if (!check) {
+  if (check.id !== checkSnapshot.id) {
     cleanupVerificationSnapshot();
-    return {
-      mode: 'durable',
-      checkId: input.checkId,
-      durable: {
-        reason: 'check_not_found_or_requires_registry_lookup',
-        suggestedOperation: 'list_checks then run_check with a known check_id',
-      },
-      durableSideEffects: emptyEffects,
-    };
+    throw new Error(`CHECK_DEFINITION_AUTHORITY_MISMATCH: ${input.checkId}`);
   }
   if (input.forceDurable || (checkRequiresDurableWorkflow(input.checkId, check) && input.allowDurableCheckExecution !== true)) {
     cleanupVerificationSnapshot();
@@ -202,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,
     };
@@ -237,17 +304,48 @@ export async function runPersistedCheckViaProcessRuntime(
     executionIdentity.repositoryId,
     executionIdentity.checkoutId,
     check.effects,
+    check.executionAuthority,
   );
-  const checkSnapshot = snapshotControllerCheck(executionRoot, input.checkId);
   const checkFingerprint = createHash('sha256')
     .update(JSON.stringify(checkSnapshot))
     .digest('hex');
-  const semanticCheck = controllerCheckExecutionIdentity(
+  const liveCertification = check.executionAuthority === 'live_controller_home';
+  if (liveCertification && input.allowDurableCheckExecution !== true) {
+    cleanupVerificationSnapshot();
+    throw new Error('LIVE_CHECK_DURABLE_AUTHORITY_REQUIRED');
+  }
+  const liveExecutionStateFingerprint = liveCertification
+    ? controllerCheckLiveExecutionStateFingerprint(input.controllerHome)
+    : undefined;
+  const preliminarySemanticCheck = controllerCheckExecutionIdentity(
     executionRoot,
     input.checkId,
     timeoutMs,
     checkSnapshot,
+    liveExecutionStateFingerprint,
   );
+  const runtimeGeneration = verificationSnapshot && !liveCertification
+    ? readRuntimeGeneration(input.controllerHome)
+    : undefined;
+  const candidateRunner = shouldUseCandidatePersistedCheckRunner({
+    repoId: input.repoId,
+    runtimeSourceRepoId: runtimeGeneration?.source.sourceRepositoryId,
+    verificationSnapshot: Boolean(verificationSnapshot),
+    liveCertification,
+  })
+    ? resolveCandidatePersistedCheckRunnerTarget(executionRoot, preliminarySemanticCheck.revision)
+    : undefined;
+  const executionStateFingerprint = candidateRunner?.executionStateFingerprint
+    ?? liveExecutionStateFingerprint;
+  const semanticCheck = candidateRunner
+    ? controllerCheckExecutionIdentity(
+        executionRoot,
+        input.checkId,
+        timeoutMs,
+        checkSnapshot,
+        executionStateFingerprint,
+      )
+    : preliminarySemanticCheck;
   const processCheckExecution = {
     schemaVersion: 1 as const,
     checkId: semanticCheck.checkId,
@@ -259,7 +357,7 @@ export async function runPersistedCheckViaProcessRuntime(
     reuseScope: semanticCheck.reuseScope,
     scopeKey: persistedCheckSemanticScopeKey(input, semanticCheck.reuseScope),
   };
-  const cliTarget = resolveRuntimeCliTarget(input.controllerHome);
+  const cliTarget = candidateRunner?.cliTarget ?? resolveRuntimeCliTarget(input.controllerHome);
   const checkResultReceiptPath = allocatePersistedCheckResultReceiptPath(
     input.controllerHome,
     input.repoId,
@@ -268,20 +366,29 @@ export async function runPersistedCheckViaProcessRuntime(
   const checkArgs = [
     '--repo',
     executionRoot,
+    '--controller-home',
+    input.controllerHome,
+    '--repo-id',
+    input.repoId,
     '--check-id',
     input.checkId,
     '--timeout-ms',
     String(timeoutMs),
     '--expected-check-fingerprint',
     checkFingerprint,
+    '--check-snapshot',
+    Buffer.from(JSON.stringify(checkSnapshot)).toString('base64url'),
     '--result-receipt',
     checkResultReceiptPath,
     ...(verificationSnapshot ? [
-      '--isolated-controller-home', verificationSnapshot.isolatedControllerHome,
+      ...(liveCertification ? ['--live-controller-home'] : ['--isolated-controller-home', verificationSnapshot.isolatedControllerHome]),
+      ...(executionStateFingerprint ? ['--execution-state-fingerprint', executionStateFingerprint] : []),
       '--cleanup-root', verificationSnapshot.root,
     ] : []),
   ];
-  const invocation = resolvePersistedCheckProcessInvocation(cliTarget, checkArgs);
+  const invocation = resolvePersistedCheckProcessInvocation(cliTarget, checkArgs, candidateRunner
+    ? { runtimeExecutable: candidateRunner.runtimeExecutable }
+    : {});
   let handle;
   try {
     handle = await spawnManagedProcess({
@@ -315,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;
+}