@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -1,6 +1,6 @@
 import { existsSync, lstatSync, opendirSync, statSync, unlinkSync } from 'fs';
 import { join, relative } from 'path';
-import { isTerminalWorkContractStatus, type WorkContract } from '../../../../packages/kernel/work/api/index';
+import { isTerminalSemanticWorkState, type WorkContract } from '../../../../packages/kernel/work/api/index';
 import { listControlPlaneRecords } from '../../control-plane/persistence/sqlite-store';
 import { processLogDir } from './store';
 import { readPersistedCheckResultReceipt } from './check-result';
@@ -50,7 +50,7 @@ export function cleanupPersistedCheckResults(
   }
   for (const record of workRecords) {
     const work = record.value;
-    if (isTerminalWorkContractStatus(work.status)) continue;
+    if (isTerminalSemanticWorkState(work.semanticState)) continue;
     for (const verification of work.checkRefs ?? []) {
       const key = verification.receipt?.checkCacheKey?.trim();
       if (key) protectedCacheKeys.add(key);

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

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
 import { dirname, join } from 'path';
 import { processLogDir } from './store';
 import type { ManagedProcessRecord } from './types';
+import type { ProcessCheckCompletionReceipt } from './check-receipt';
 
 export const STRUCTURED_CHECK_RESULT_PATH_ENV = 'FORGE_CHECK_STRUCTURED_RESULT_PATH';
 export const MAX_STRUCTURED_CHECK_FAILURE_DETAILS = 32;
@@ -110,7 +111,17 @@ export function readPersistedCheckResultReceipt(path: string | undefined): Persi
   if (!path || !existsSync(path)) return undefined;
   try {
     const value = JSON.parse(readFileSync(path, 'utf8')) as PersistedCheckResultReceipt;
-    if (value?.schemaVersion !== 1 || typeof value.receiptId !== 'string' || typeof value.cacheKey !== 'string') return undefined;
+    if (
+      value?.schemaVersion !== 1
+      || typeof value.receiptId !== 'string'
+      || typeof value.checkId !== 'string'
+      || typeof value.cacheKey !== 'string'
+      || typeof value.ok !== 'boolean'
+      || typeof value.status !== 'number'
+      || typeof value.timedOut !== 'boolean'
+      || typeof value.executedAt !== 'string'
+      || (value.failureClass !== undefined && value.failureClass !== 'acceptance_failure' && value.failureClass !== 'infrastructure_failure')
+    ) return undefined;
     if (value.failureEvidence !== undefined && !isStructuredCheckFailureEvidence(value.failureEvidence)) return undefined;
     return value;
   } catch {
@@ -128,6 +139,9 @@ export interface PersistedCheckTerminalEvidence {
   state: PersistedCheckTerminalEvidenceState;
   failureClass?: PersistedCheckResultReceipt['failureClass'];
   failureEvidence?: StructuredCheckFailureEvidence;
+  semanticOk?: boolean;
+  semanticStatus?: number;
+  semanticTimedOut?: boolean;
   warning?: string;
   infrastructureReason?: string;
 }
@@ -173,6 +187,9 @@ export function classifyTerminalCheckEvidence(
  */
 export interface LegacyCheckEvidenceLike {
   cacheKey?: string;
+  ok?: boolean;
+  status?: number;
+  timedOut?: boolean;
   failureClass?: PersistedCheckResultReceipt['failureClass'];
   failureEvidence?: StructuredCheckFailureEvidence;
 }
@@ -207,6 +224,93 @@ export function classifyPersistedCheckTerminalEvidence(
       ...classified,
       failureClass: structuredMatches ? structured?.failureClass : legacy?.failureClass,
       failureEvidence: structuredMatches ? structured?.failureEvidence : legacy?.failureEvidence,
+      semanticOk: structuredMatches ? structured?.ok : legacy?.ok,
+      semanticStatus: structuredMatches ? structured?.status : legacy?.status,
+      semanticTimedOut: structuredMatches ? structured?.timedOut : legacy?.timedOut,
     }
     : classified;
 }
+
+export type TerminalCheckVerificationOutcome = 'valid_pass' | 'valid_fail' | 'infrastructure_failure';
+
+export interface TerminalCheckVerificationProjection {
+  outcome: TerminalCheckVerificationOutcome;
+  failureClass?: 'acceptance_failure' | 'infrastructure_failure';
+  isAcceptanceFailure: boolean;
+  isInfrastructureIssue: boolean;
+  boundedStatus: 'pass' | 'fail' | 'infrastructure_failure';
+  evidence: PersistedCheckTerminalEvidence;
+  infrastructureReason?: string;
+}
+
+/**
+ * Canonical Failure Contract projection from one exact terminal Check Process
+ * plus its semantic Check-result evidence into Work verification truth.
+ * Process exit state is necessary evidence, but never acceptance authority by
+ * itself. Missing, mismatched, interrupted, infrastructure, or contradictory
+ * evidence fails closed as infrastructure_failure.
+ */
+export function projectTerminalCheckVerification(
+  record: ManagedProcessRecord,
+  expectedCheckId: string,
+  receipt: ProcessCheckCompletionReceipt,
+  options: { legacyEvidence?: LegacyCheckEvidenceLike } = {},
+): TerminalCheckVerificationProjection {
+  const evidence = classifyPersistedCheckTerminalEvidence(record, expectedCheckId, options);
+  const semanticContradiction = evidence.state === 'matched' && Boolean(
+    (evidence.semanticOk !== undefined && evidence.semanticOk !== receipt.ok)
+    || (evidence.semanticTimedOut !== undefined && evidence.semanticTimedOut !== receipt.timedOut)
+    || (evidence.semanticOk === true && evidence.semanticStatus !== undefined && evidence.semanticStatus !== 0)
+    || (evidence.semanticOk === false && evidence.semanticStatus === 0)
+    || (receipt.ok && evidence.failureClass !== undefined)
+    || (evidence.semanticOk === true && evidence.failureClass !== undefined)
+    || (!receipt.ok && evidence.failureClass === undefined)
+    || (evidence.semanticOk === false && evidence.failureClass === undefined)
+  );
+  const infrastructureReason = evidence.infrastructureReason
+    ?? (semanticContradiction ? 'terminal Check Process and semantic result evidence contradict each other' : undefined);
+  const infrastructure = receipt.timedOut
+    || receipt.cancelled
+    || evidence.state !== 'matched'
+    || semanticContradiction
+    || evidence.failureClass === 'infrastructure_failure';
+  if (infrastructure) {
+    return {
+      outcome: 'infrastructure_failure',
+      failureClass: 'infrastructure_failure',
+      isAcceptanceFailure: false,
+      isInfrastructureIssue: true,
+      boundedStatus: 'infrastructure_failure',
+      evidence,
+      ...(infrastructureReason ? { infrastructureReason } : {}),
+    };
+  }
+  if (receipt.ok) {
+    return {
+      outcome: 'valid_pass',
+      isAcceptanceFailure: false,
+      isInfrastructureIssue: false,
+      boundedStatus: 'pass',
+      evidence,
+    };
+  }
+  if (evidence.failureClass === 'acceptance_failure') {
+    return {
+      outcome: 'valid_fail',
+      failureClass: 'acceptance_failure',
+      isAcceptanceFailure: true,
+      isInfrastructureIssue: false,
+      boundedStatus: 'fail',
+      evidence,
+    };
+  }
+  return {
+    outcome: 'infrastructure_failure',
+    failureClass: 'infrastructure_failure',
+    isAcceptanceFailure: false,
+    isInfrastructureIssue: true,
+    boundedStatus: 'infrastructure_failure',
+    evidence,
+    infrastructureReason: 'terminal Check failure lacks explicit acceptance-failure evidence',
+  };
+}

package/src/runtime/execution/process-runtime/check-runner-sidecar.ts

@@ -2,13 +2,8 @@
 import { createHash } from 'crypto';
 import { rmSync } from 'fs';
 import { resolve } from 'path';
-import {
-  controllerCheckExecutionIdentity,
-  runControllerCheckAsync,
-  snapshotControllerCheck,
-  type ControllerCheckSnapshot,
-} from '../../../cli/controller/check-runner';
-import { writePersistedCheckResultReceipt } from './check-result';
+import type { ControllerCheckSnapshot } from '../../../cli/controller/check-runner';
+import { materializeManagedWorkspaceDependencies } from '../managed-workspace';
 import { PROCESS_RUNTIME_RELEASE_CANARY_ARG } from './canary';
 
 interface ParsedArgs {
@@ -33,7 +28,6 @@ function requiredValue(argv: string[], flag: string): string {
   return value;
 }
 
-
 function decodeCheckSnapshot(value: string): ControllerCheckSnapshot {
   let decoded: unknown;
   try {
@@ -77,6 +71,22 @@ export async function runPersistedCheckSidecar(argv = process.argv.slice(2)): Pr
   const args = parseArgs(argv);
   const root = resolve(args.repo);
   try {
+    // A Work verification snapshot is disposable execution state. When exact
+    // canonical dependency reuse was unavailable during snapshot construction,
+    // establish the candidate's frozen dependency closure inside this Check
+    // Process before loading the candidate Check Runner module graph.
+    if (args.cleanupRoot && (!args.checkSnapshot || args.checkSnapshot.source === 'package-script')) {
+      materializeManagedWorkspaceDependencies(root);
+    }
+
+    const [
+      { controllerCheckExecutionIdentity, runControllerCheckAsync, snapshotControllerCheck },
+      { writePersistedCheckResultReceipt },
+    ] = await Promise.all([
+      import('../../../cli/controller/check-runner'),
+      import('./check-result'),
+    ]);
+
     // New callers carry the exact definition resolved from canonical repository
     // authority. The fallback keeps older package releases compatible.
     const snapshot = args.checkSnapshot ?? snapshotControllerCheck(root, args.checkId);

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

@@ -8,7 +8,10 @@
  * - Durable: explicit Work/external/release boundaries only.
  */
 
-import type { RepositoryRecord } from '../../../cli/repositories/types';
+import {
+  commandExecutionScopeKey,
+  type RepositoryCommandScopeTarget,
+} from '../../../cli/repositories/command-scope';
 import { classifyRepositoryCommand, fixedShellWrapperCommand, shellSegments, shellWordsPreservingQuotes } from '../../../cli/repositories/command-classifier';
 import {
   executeRepositoryCommandAsync,
@@ -38,10 +41,12 @@ import {
   cancelLightweightProcess,
   getLightweightProcessHandle,
   isLightweightProcessId,
+  lightweightProcessScopeKey,
   readLightweightProcessLogs,
   startLightweightRepositoryCommand,
   waitForLightweightProcess,
 } from './lightweight-managed';
+import { isForgeInstanceProcessScopeKey, processScopeKeyForHandle } from './process-scope';
 
 export type RepositoryCommandRoute =
   | 'process_direct'
@@ -51,7 +56,8 @@ export type RepositoryCommandRoute =
 
 export interface RepositoryCommandProcessInput {
   controllerHome: string;
-  repository: RepositoryRecord;
+  /** Repository identity is optional: an arbitrary workspace target carries a workspace scope key. */
+  repository: RepositoryCommandScopeTarget;
   command: string | readonly string[];
   cwd?: string;
   timeoutMs?: number;
@@ -64,6 +70,8 @@ export interface RepositoryCommandProcessInput {
   requestId?: string;
   workId?: string;
   commandId?: string;
+  /** Authenticated principal recorded with the process handle for principal-bound attachment. */
+  principalId?: string;
   signal?: AbortSignal;
   /** Explicit unregistered local workspace authority; never inferred from cwd. */
   allowNonGitWorkspace?: boolean;
@@ -353,9 +361,9 @@ export async function executeRepositoryCommandViaProcessRuntime(
     throw new Error('EXECUTION_IDENTITY_REQUIRED: repository command process path requires an immutable executionIdentity');
   }
   const executionIdentity = input.executionIdentity;
-  if (executionIdentity.repositoryId !== input.repository.repoId) {
+  if (executionIdentity.repositoryId !== commandExecutionScopeKey(input.repository)) {
     throw new Error(
-      `EXECUTION_IDENTITY_MISMATCH: repository ${input.repository.repoId} differs from identity ${executionIdentity.repositoryId}`,
+      `EXECUTION_IDENTITY_MISMATCH: repository ${commandExecutionScopeKey(input.repository)} differs from identity ${executionIdentity.repositoryId}`,
     );
   }
   if (executionIdentity.checkoutId !== input.repository.activeCheckoutId) {
@@ -376,13 +384,12 @@ export async function executeRepositoryCommandViaProcessRuntime(
   // immutable repository identity first, then execute through the authorized
   // non-persistent repository executor. Runtime/release durability is not a
   // command-execution tax.
-  const canonicalCommand = normalizeRepositoryCommand(input.command);
   if (decision.route === 'process_direct') {
     assertExecutionIdentity({
       controllerHome: input.controllerHome,
       identity: executionIdentity,
       cwd,
-      requestedRepoId: input.repository.repoId,
+      requestedRepoId: commandExecutionScopeKey(input.repository),
       requestedCheckoutId: input.repository.activeCheckoutId,
     });
     const directInput = {
@@ -395,8 +402,7 @@ export async function executeRepositoryCommandViaProcessRuntime(
       allowOpaqueLocalScript: decision.reason === 'lightweight_local_shell_wrapper'
         || decision.reason === 'lightweight_local_inline_interpreter',
     };
-    const readonly = canonicalCommand.kind === 'argv'
-      && classifyRepositoryCommand(input.command, input.repository.defaultBranch).risk === 'readonly';
+    const readonly = classifyRepositoryCommand(input.command, input.repository.defaultBranch).risk === 'readonly';
     if (!readonly) {
       const deferLongPreparation = decision.reason === 'ephemeral_local_build_or_test';
       const interactiveWaitMs = deferLongPreparation
@@ -419,6 +425,7 @@ export async function executeRepositoryCommandViaProcessRuntime(
         maxOutputBytes: input.maxOutputBytes,
         workId: input.workId,
         commandId: input.commandId ?? input.requestId,
+        ...(input.principalId ? { principalId: input.principalId } : {}),
         deferStart: deferLongPreparation,
         reuseActiveEquivalent: deferLongPreparation,
         onCompleted: (result) => {
@@ -427,7 +434,7 @@ export async function executeRepositoryCommandViaProcessRuntime(
           // evidence is unavailable. Finalization must keep failing closed until
           // a later authoritative repository inspection proves the new HEAD.
           if (result.evidenceError) return;
-          settleWorkHandleExpectedHeadAfterRepositoryCommand({
+          const settlement = settleWorkHandleExpectedHeadAfterRepositoryCommand({
             controllerHome: input.controllerHome,
             repository: input.repository,
             executionIdentity,
@@ -436,6 +443,12 @@ export async function executeRepositoryCommandViaProcessRuntime(
             cancelled: result.cancelled,
             timedOut: result.timedOut,
           });
+          if (!settlement.settled && settlement.reason === 'concurrent_lifecycle_write') {
+            result.evidenceError = {
+              code: 'WORK_HEAD_SETTLEMENT_UNRESOLVED',
+              message: `Work ${input.workId ?? 'unknown'} repository command succeeded, but expectedHead settlement remained contested after bounded retry (${settlement.previousHead ?? 'unknown'} -> ${settlement.currentHead ?? 'unknown'}).`,
+            };
+          }
         },
       });
       const handle = lightweight.handle;
@@ -526,6 +539,7 @@ export async function executeRepositoryCommandViaProcessRuntime(
     repoId: executionIdentity.repositoryId,
     checkoutId: executionIdentity.checkoutId,
     executionIdentity,
+    ...(input.principalId ? { principalId: input.principalId } : {}),
     workId: input.workId,
     commandId: input.commandId,
     command: toProcessCommand(input.command, cwd),
@@ -563,40 +577,78 @@ export async function executeRepositoryCommandViaProcessRuntime(
   };
 }
 
-export function getRepositoryCommandProcess(controllerHome: string, repoId: string, processId: string): ProcessHandle | undefined {
-  return isLightweightProcessId(processId)
-    ? getLightweightProcessHandle(controllerHome, repoId, processId)
-    : getProcessHandle(controllerHome, repoId, processId);
+/**
+ * Resolve the canonical Process scope of one process handle.
+ *
+ * Explicit placement stays authoritative and is validated by the lane itself.
+ * When the caller omits it, this Runtime's own lightweight memory or the
+ * instance-level handle index supplies the recorded scope, so attachment never
+ * requires replaying the original placement inputs or scanning repositories.
+ */
+function resolveCommandProcessScopeKey(
+  controllerHome: string,
+  repoId: string | undefined,
+  processId: string,
+): string | undefined {
+  const explicit = repoId?.trim();
+  if (explicit) return explicit;
+  if (isLightweightProcessId(processId)) {
+    const inMemory = lightweightProcessScopeKey(processId);
+    if (inMemory) return inMemory;
+  }
+  return processScopeKeyForHandle(controllerHome, processId);
 }
 
-export function waitRepositoryCommandProcess(
+export function getRepositoryCommandProcess(
   controllerHome: string,
-  repoId: string,
+  repoId: string | undefined,
+  processId: string,
+): ProcessHandle | undefined {
+  const scopeKey = resolveCommandProcessScopeKey(controllerHome, repoId, processId);
+  if (!scopeKey) return undefined;
+  if (!isLightweightProcessId(processId)) {
+    return getProcessHandle(controllerHome, scopeKey, processId);
+  }
+  return getLightweightProcessHandle(controllerHome, scopeKey, processId);
+}
+
+export async function waitRepositoryCommandProcess(
+  controllerHome: string,
+  repoId: string | undefined,
   processId: string,
   options?: Parameters<typeof waitForProcess>[3],
 ): Promise<ProcessHandle> {
-  return isLightweightProcessId(processId)
-    ? waitForLightweightProcess(controllerHome, repoId, processId, options)
-    : waitForProcess(controllerHome, repoId, processId, options);
+  const scopeKey = resolveCommandProcessScopeKey(controllerHome, repoId, processId);
+  if (!scopeKey) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
+  if (!isLightweightProcessId(processId)) {
+    return waitForProcess(controllerHome, scopeKey, processId, options);
+  }
+  return waitForLightweightProcess(controllerHome, scopeKey, processId, options);
 }
 
-export function cancelRepositoryCommandProcess(
+export async function cancelRepositoryCommandProcess(
   controllerHome: string,
-  repoId: string,
+  repoId: string | undefined,
   processId: string,
 ): Promise<ProcessHandle> {
-  return isLightweightProcessId(processId)
-    ? cancelLightweightProcess(controllerHome, repoId, processId)
-    : cancelProcess(controllerHome, repoId, processId);
+  const scopeKey = resolveCommandProcessScopeKey(controllerHome, repoId, processId);
+  if (!scopeKey) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
+  if (!isLightweightProcessId(processId)) {
+    return cancelProcess(controllerHome, scopeKey, processId);
+  }
+  return cancelLightweightProcess(controllerHome, scopeKey, processId);
 }
 
 export function readRepositoryCommandProcessLogs(
   controllerHome: string,
-  repoId: string,
+  repoId: string | undefined,
   processId: string,
   maxBytes?: number,
 ) {
-  return isLightweightProcessId(processId)
-    ? readLightweightProcessLogs(controllerHome, repoId, processId, maxBytes)
-    : readProcessLogs(controllerHome, repoId, processId, maxBytes);
+  const scopeKey = resolveCommandProcessScopeKey(controllerHome, repoId, processId);
+  if (!scopeKey) return undefined;
+  if (!isLightweightProcessId(processId)) {
+    return readProcessLogs(controllerHome, scopeKey, processId, maxBytes);
+  }
+  return readLightweightProcessLogs(controllerHome, scopeKey, processId, maxBytes);
 }

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

@@ -9,8 +9,9 @@
 import { existsSync, readFileSync, readdirSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { ensureRepositoryControllerLayout, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { isRepositoryProcessScopeKey, processScopeRoot } from './process-scope';
 import { getProcessRecord, listActiveProcessIds } from './store';
-import { reconcileStaleManagedProcessForMaintenance } from './runtime';
+import { reconcileStaleManagedProcessForMaintenance, releaseProcessLeasesOnce } from './runtime';
 import { isManagedProcessActive, type ProcessRuntimeStatus } from './types';
 import { assertRuntimeMayWrite } from '../../root/write-fence';
 import { isProcessAlive } from '../../shared/process-tree';
@@ -52,7 +53,12 @@ export interface ProcessGcResult {
 }
 
 function processesDir(controllerHome: string, repoId: string): string {
-  return join(ensureRepositoryControllerLayout(controllerHome, repoId), 'processes');
+  // Repository scopes keep their per-repository layout; instance and workspace
+  // scopes own sibling partitions so their process records are still collected.
+  const root = isRepositoryProcessScopeKey(repoId)
+    ? ensureRepositoryControllerLayout(controllerHome, repoId)
+    : processScopeRoot(controllerHome, repoId);
+  return join(root, 'processes');
 }
 
 function logDir(controllerHome: string, repoId: string): string {
@@ -196,6 +202,13 @@ export function gcTerminalProcesses(options: ProcessGcOptions): ProcessGcResult
         }
       }
       if (!TERMINAL.has(metadata.status)) continue;
+      // Terminal evidence and lease cleanup are separate durable phases. A
+      // crash/fence between them must not leave a workspace lease immortal just
+      // because the terminal record is still inside the retention window.
+      const terminalRecord = getProcessRecord(options.controllerHome, options.repoId, processId);
+      if (terminalRecord?.terminalWritten === true && terminalRecord.leasesReleased !== true) {
+        releaseProcessLeasesOnce(options.controllerHome, options.repoId, processId);
+      }
       // Do not delete terminal evidence that has never been read when maxAge is not exceeded
       // unless we are strictly over maxTerminalRecords budget (handled by sort below).
       const finished = Date.parse(metadata.finishedAt ?? metadata.updatedAt ?? '');

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

@@ -0,0 +1,176 @@
+/**
+ * Instance-level Process handle index.
+ *
+ * Process attachment (get/wait/logs/cancel) resolves the concrete execution
+ * target from the returned handle identity instead of replaying the original
+ * placement inputs or scanning every repository partition. The index lives in
+ * Controller Home, so it is a ForgeInstance-level locator: repository/checkout
+ * placement is target metadata, never the address space of the process itself.
+ *
+ * This is a rebuildable locator projection. The Process Runtime record and its
+ * exit receipt remain the only outcome evidence; a missing or stale index entry
+ * degrades attachment convenience and never becomes a capability gate.
+ */
+
+import { readForgeInstanceIdentity } from '../../../../packages/kernel/identity/api/index';
+import { mutateControlPlaneRecord, readControlPlaneRecord } from '../../control-plane/persistence/sqlite-store';
+
+export const PROCESS_HANDLE_INDEX_NAMESPACE = 'process_handle_index';
+const PROCESS_HANDLE_INDEX_SCOPE = 'instance';
+const PROCESS_HANDLE_INDEX_SCHEMA_VERSION = 1;
+
+export type ProcessExecutionTargetScope = 'forge_instance' | 'repository' | 'workspace';
+
+/** Typed execution target for one process handle. Repository placement is optional context. */
+export interface ProcessExecutionTarget {
+  schemaVersion: 1;
+  scope: ProcessExecutionTargetScope;
+  forgeInstanceId?: string;
+  repositoryId?: string;
+  /** Workspace scope id when the target is an arbitrary workspace without repository semantics. */
+  workspaceId?: string;
+  checkoutId?: string;
+}
+
+export interface ProcessHandleIndexEntry {
+  schemaVersion: 1;
+  processId: string;
+  lane: 'lightweight' | 'managed';
+  target: ProcessExecutionTarget;
+  /** Authenticated principal that owns the handle; opaque ids never authorize by themselves. */
+  principalId?: string;
+  workId?: string;
+  commandId?: string;
+  recordedAt: string;
+  updatedAt: string;
+}
+
+function boundedId(value: string | undefined): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized.slice(0, 512) : undefined;
+}
+
+export function forgeInstanceIdFor(controllerHome: string): string | undefined {
+  return readForgeInstanceIdentity(controllerHome)?.instanceId;
+}
+
+export function forgeInstanceExecutionTarget(controllerHome: string): ProcessExecutionTarget {
+  const forgeInstanceId = forgeInstanceIdFor(controllerHome);
+  return { schemaVersion: 1, scope: 'forge_instance', ...(forgeInstanceId ? { forgeInstanceId } : {}) };
+}
+
+export function repositoryExecutionTarget(
+  controllerHome: string,
+  repositoryId: string,
+  checkoutId?: string,
+): ProcessExecutionTarget {
+  const forgeInstanceId = forgeInstanceIdFor(controllerHome);
+  const repository = boundedId(repositoryId);
+  if (!repository) throw new Error('PROCESS_EXECUTION_TARGET_REPOSITORY_REQUIRED');
+  const checkout = boundedId(checkoutId);
+  return {
+    schemaVersion: 1,
+    scope: 'repository',
+    ...(forgeInstanceId ? { forgeInstanceId } : {}),
+    repositoryId: repository,
+    ...(checkout ? { checkoutId: checkout } : {}),
+  };
+}
+
+/** Target for an arbitrary workspace: no repository identity is created or implied. */
+export function workspaceExecutionTarget(controllerHome: string, workspaceId: string): ProcessExecutionTarget {
+  const workspace = boundedId(workspaceId);
+  if (!workspace) throw new Error('PROCESS_EXECUTION_TARGET_WORKSPACE_REQUIRED');
+  const forgeInstanceId = forgeInstanceIdFor(controllerHome);
+  return {
+    schemaVersion: 1,
+    scope: 'workspace',
+    ...(forgeInstanceId ? { forgeInstanceId } : {}),
+    workspaceId: workspace,
+  };
+}
+
+export function recordProcessHandleIndexEntry(
+  controllerHome: string,
+  input: Omit<ProcessHandleIndexEntry, 'schemaVersion' | 'recordedAt' | 'updatedAt'> & { now?: string },
+): ProcessHandleIndexEntry | undefined {
+  const processId = boundedId(input.processId);
+  if (!processId) return undefined;
+  const now = input.now ?? new Date().toISOString();
+  const principalId = boundedId(input.principalId);
+  const workId = boundedId(input.workId);
+  const commandId = boundedId(input.commandId);
+  try {
+    const record = mutateControlPlaneRecord<ProcessHandleIndexEntry>(controllerHome, {
+      namespace: PROCESS_HANDLE_INDEX_NAMESPACE,
+      scope: PROCESS_HANDLE_INDEX_SCOPE,
+      key: processId,
+      schemaVersion: PROCESS_HANDLE_INDEX_SCHEMA_VERSION,
+      action: 'process_handle_index_record',
+      mutate: (current) => ({
+        schemaVersion: PROCESS_HANDLE_INDEX_SCHEMA_VERSION,
+        processId,
+        lane: input.lane,
+        target: input.target,
+        ...(principalId ? { principalId } : {}),
+        ...(current?.value.principalId && !principalId ? { principalId: current.value.principalId } : {}),
+        ...(workId ? { workId } : {}),
+        ...(commandId ? { commandId } : {}),
+        recordedAt: current?.value.recordedAt ?? now,
+        updatedAt: now,
+      }),
+    });
+    return record.value;
+  } catch {
+    // A locator projection must never block an already-authorized process.
+    return undefined;
+  }
+}
+
+export function readProcessHandleIndexEntry(
+  controllerHome: string,
+  processId: string,
+): ProcessHandleIndexEntry | undefined {
+  const key = boundedId(processId);
+  if (!key) return undefined;
+  try {
+    const record = readControlPlaneRecord<ProcessHandleIndexEntry>(
+      controllerHome,
+      PROCESS_HANDLE_INDEX_NAMESPACE,
+      PROCESS_HANDLE_INDEX_SCOPE,
+      key,
+    );
+    const value = record?.value;
+    if (!value || value.schemaVersion !== PROCESS_HANDLE_INDEX_SCHEMA_VERSION || value.processId !== key) return undefined;
+    if (!value.target || value.target.schemaVersion !== 1) return undefined;
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolve the concrete execution target recorded for one process handle. */
+export function resolveProcessExecutionTarget(
+  controllerHome: string,
+  processId: string,
+): ProcessExecutionTarget | undefined {
+  return readProcessHandleIndexEntry(controllerHome, processId)?.target;
+}
+
+/**
+ * Principal that owns one process handle, when recorded. Opaque handle ids
+ * locate a record; they never authorize attachment on their own.
+ */
+export function processHandlePrincipalId(controllerHome: string, processId: string): string | undefined {
+  return readProcessHandleIndexEntry(controllerHome, processId)?.principalId;
+}
+
+/** Compatibility narrowing: the repository placement recorded for a process, when it has one. */
+export function resolveProcessRepositoryTarget(
+  controllerHome: string,
+  processId: string,
+): { repositoryId: string; checkoutId?: string } | undefined {
+  const target = resolveProcessExecutionTarget(controllerHome, processId);
+  if (!target?.repositoryId) return undefined;
+  return { repositoryId: target.repositoryId, ...(target.checkoutId ? { checkoutId: target.checkoutId } : {}) };
+}