@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -8,8 +8,10 @@
  * - Durable: explicit Work/external/release boundaries only.
  */
 
-import type { RepositoryRecord } from '../../../cli/repositories/types';
-import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
+import {
+  commandExecutionScopeKey,
+  type RepositoryCommandScopeTarget,
+} from '../../../cli/repositories/command-scope';
 import { classifyRepositoryCommand, fixedShellWrapperCommand, shellSegments, shellWordsPreservingQuotes } from '../../../cli/repositories/command-classifier';
 import {
   executeRepositoryCommandAsync,
@@ -34,15 +36,17 @@ import { DEFAULT_INTERACTIVE_WAIT_MS } from './types';
 import { durationAwareInteractiveWaitMs } from './interactive-admission';
 import { isFocusedCheckCommand } from '../thin-harness/execution-router';
 import { assertExecutionIdentity, type ResolvedExecutionIdentity } from '../../control-plane/execution/execution-identity';
-import { readWorkHandle, transitionWorkHandle } from '../../control-plane/execution/work-handle-store';
+import { settleWorkHandleExpectedHeadAfterRepositoryCommand } from '../../control-plane/execution/work-head-settlement';
 import {
   cancelLightweightProcess,
   getLightweightProcessHandle,
   isLightweightProcessId,
+  lightweightProcessScopeKey,
   readLightweightProcessLogs,
   startLightweightRepositoryCommand,
   waitForLightweightProcess,
 } from './lightweight-managed';
+import { isForgeInstanceProcessScopeKey, processScopeKeyForHandle } from './process-scope';
 
 export type RepositoryCommandRoute =
   | 'process_direct'
@@ -52,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;
@@ -65,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;
@@ -114,77 +121,6 @@ const emptyEffects = {
   projectionUpdateCount: 0,
 };
 
-export type WorkHeadSettlementReason =
-  | 'settled'
-  | 'no_work'
-  | 'command_not_successful'
-  | 'work_handle_missing'
-  | 'identity_mismatch'
-  | 'terminal_handle'
-  | 'branch_changed'
-  | 'head_unavailable'
-  | 'head_unchanged'
-  | 'concurrent_lifecycle_write';
-
-export interface WorkHeadSettlementResult {
-  settled: boolean;
-  reason: WorkHeadSettlementReason;
-  previousHead?: string;
-  currentHead?: string;
-}
-
-/**
- * Settle the one legitimate post-command Work HEAD transition without weakening
- * the pre-command execution identity fence. The command has already been
- * admitted only if repo/checkout/branch/expectedHead matched the WorkHandle.
- * After success, adopt the exact current HEAD only while the same checkout and
- * branch still own the Work. CAS failure is a bounded no-op: finalization keeps
- * failing closed instead of accepting a concurrent lifecycle writer.
- */
-export function settleWorkHandleExpectedHeadAfterRepositoryCommand(input: {
-  controllerHome: string;
-  repository: RepositoryRecord;
-  executionIdentity: ResolvedExecutionIdentity;
-  workId?: string;
-  ok?: boolean;
-  cancelled?: boolean;
-  timedOut?: boolean;
-}): WorkHeadSettlementResult {
-  const workId = input.workId?.trim();
-  if (!workId) return { settled: false, reason: 'no_work' };
-  if (input.ok !== true || input.cancelled === true || input.timedOut === true) {
-    return { settled: false, reason: 'command_not_successful' };
-  }
-  const handle = readWorkHandle(input.controllerHome, input.repository.repoId, workId);
-  if (!handle) return { settled: false, reason: 'work_handle_missing' };
-  if (
-    handle.repositoryId !== input.executionIdentity.repositoryId
-    || handle.checkoutId !== input.executionIdentity.checkoutId
-    || handle.workId !== input.executionIdentity.workId
-  ) return { settled: false, reason: 'identity_mismatch' };
-  if (handle.state === 'merged' || handle.state === 'cleaned' || handle.state === 'failed_terminal_cleanup') {
-    return { settled: false, reason: 'terminal_handle' };
-  }
-  const status = repositoryGitStatus(input.repository);
-  if (!status.branch || status.branch !== handle.branch) {
-    return { settled: false, reason: 'branch_changed', previousHead: handle.expectedHead, currentHead: status.head ?? undefined };
-  }
-  const currentHead = status.head?.trim();
-  if (!currentHead) return { settled: false, reason: 'head_unavailable', previousHead: handle.expectedHead };
-  if (currentHead === handle.expectedHead) {
-    return { settled: false, reason: 'head_unchanged', previousHead: handle.expectedHead, currentHead };
-  }
-  try {
-    transitionWorkHandle(input.controllerHome, handle, handle.state, { expectedHead: currentHead });
-    return { settled: true, reason: 'settled', previousHead: handle.expectedHead, currentHead };
-  } catch (error) {
-    if (error instanceof Error && error.message.includes('CONTROL_PLANE_REVISION_CONFLICT')) {
-      return { settled: false, reason: 'concurrent_lifecycle_write', previousHead: handle.expectedHead, currentHead };
-    }
-    throw error;
-  }
-}
-
 const STANDALONE_RECOVERY_LIFECYCLE_COMMANDS = new Set([
   'restart-runtime',
   'bootstrap-cutover',
@@ -237,9 +173,15 @@ function repositoryCommandRecoveryLifecycle(command: string | readonly string[])
   return wrapped ? recoveryLifecycleFromShell(wrapped) : undefined;
 }
 
-function gitCommitWordsRequireExplicitPathScope(words: readonly string[]): boolean | undefined {
+export type RepositoryGitCommitCommandScope =
+  | { kind: 'not_commit' }
+  | { kind: 'explicit_paths'; paths: string[] }
+  | { kind: 'staged_index' }
+  | { kind: 'unsafe'; reason: 'scope_widening' | 'compound_unscoped_commit' };
+
+function gitCommitWordsScope(words: readonly string[]): RepositoryGitCommitCommandScope {
   const executable = commandBasename(words[0] ?? '');
-  if (executable !== 'git') return undefined;
+  if (executable !== 'git') return { kind: 'not_commit' };
   const args = words.slice(1);
   let index = 0;
   while (index < args.length && args[index]?.startsWith('-')) {
@@ -248,29 +190,45 @@ function gitCommitWordsRequireExplicitPathScope(words: readonly string[]): boole
     else if (['--git-dir=', '--work-tree=', '--namespace='].some((prefix) => option.startsWith(prefix))) index += 1;
     else index += 1;
   }
-  if (args[index]?.toLowerCase() !== 'commit') return undefined;
+  if (args[index]?.toLowerCase() !== 'commit') return { kind: 'not_commit' };
   const commitArgs = args.slice(index + 1);
   const pathSeparator = commitArgs.indexOf('--');
   const paths = pathSeparator >= 0 ? commitArgs.slice(pathSeparator + 1).filter(Boolean) : [];
-  const widensScope = commitArgs.some((arg) => ['-a', '--all', '-i', '--include', '--interactive', '-p', '--patch'].includes(arg));
-  return paths.length === 0 || widensScope;
+  const wideningFlags = ['-a', '--all', '-i', '--include', '--interactive', '-p', '--patch', '--amend', '--pathspec-from-file'];
+  const widensScope = commitArgs.some((arg) => wideningFlags.some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+  if (widensScope) return { kind: 'unsafe', reason: 'scope_widening' };
+  return paths.length > 0 ? { kind: 'explicit_paths', paths } : { kind: 'staged_index' };
 }
 
-function rawGitCommitRequiresExplicitPathScope(command: string | readonly string[]): boolean {
+function aggregateShellCommitScope(shellCommand: string): RepositoryGitCommitCommandScope {
+  const segments = shellSegments(shellCommand);
+  const commits = segments
+    .map((segment) => gitCommitWordsScope(shellWordsPreservingQuotes(segment)))
+    .filter((scope) => scope.kind !== 'not_commit');
+  if (commits.length === 0) return { kind: 'not_commit' };
+  const unsafe = commits.find((scope): scope is Extract<RepositoryGitCommitCommandScope, { kind: 'unsafe' }> => scope.kind === 'unsafe');
+  if (unsafe) return unsafe;
+  if (segments.length > 1 && commits.some((scope) => scope.kind === 'staged_index')) {
+    return { kind: 'unsafe', reason: 'compound_unscoped_commit' };
+  }
+  const staged = commits.find((scope) => scope.kind === 'staged_index');
+  if (staged) return staged;
+  const paths = commits.flatMap((scope) => scope.kind === 'explicit_paths' ? scope.paths : []);
+  return { kind: 'explicit_paths', paths: [...new Set(paths)] };
+}
+
+export function classifyRawGitCommitScope(command: string | readonly string[]): RepositoryGitCommitCommandScope {
   const normalized = normalizeRepositoryCommand(command);
   if (normalized.kind === 'argv') {
-    const direct = gitCommitWordsRequireExplicitPathScope([
+    const direct = gitCommitWordsScope([
       normalized.executable ?? '',
       ...(normalized.args ?? []),
     ]);
-    if (direct !== undefined) return direct;
+    if (direct.kind !== 'not_commit') return direct;
     const wrapped = fixedShellWrapperCommand(normalized.value as string[]);
-    if (!wrapped) return false;
-    return shellSegments(wrapped)
-      .some((segment) => gitCommitWordsRequireExplicitPathScope(shellWordsPreservingQuotes(segment)) === true);
+    return wrapped ? aggregateShellCommitScope(wrapped) : { kind: 'not_commit' };
   }
-  return shellSegments(normalized.shellCommand ?? '')
-    .some((segment) => gitCommitWordsRequireExplicitPathScope(shellWordsPreservingQuotes(segment)) === true);
+  return aggregateShellCommitScope(normalized.shellCommand ?? '');
 }
 
 function toProcessCommand(command: string | readonly string[], cwd: string): ProcessCommandSpec {
@@ -305,7 +263,8 @@ export function classifyRepositoryCommandRoute(
   if (repositoryCommandRecoveryLifecycle(command)) {
     return { route: 'reject', reason: 'standalone_recovery_lifecycle_required' };
   }
-  if (rawGitCommitRequiresExplicitPathScope(command)) {
+  const commitScope = classifyRawGitCommitScope(command);
+  if (commitScope.kind === 'unsafe') {
     return { route: 'reject', reason: 'git_commit_requires_explicit_path_scope' };
   }
   if (options.forceDurable) {
@@ -402,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) {
@@ -425,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 = {
@@ -444,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
@@ -468,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) => {
@@ -476,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,
@@ -485,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;
@@ -575,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),
@@ -612,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 } : {}) };
+}