@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/execution/managed-workspace.ts

@@ -16,10 +16,13 @@ import { resolveGitExecutable } from '../../effects/git-executable';
 import { runProcess } from '../../effects/process-runner';
 import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../shared/process-environment';
 import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
+import { ensureForgeInstanceIdentity, getOwnedResource, ownedResourceLocatorFingerprint, recordOwnedResource, type OwnedResourceLocator } from '../../../packages/kernel/identity/api/index';
 
 export interface EnsureManagedWorkspaceInput {
   requestId: string;
   title: string;
+  /** Semantic Work provenance for durable ownership; never an execution mutex. */
+  associatedWorkId?: string;
   baseRef?: string;
   branchName?: string;
   /** Explicitly materialize lockfile-backed Node dependencies in this isolated worktree. */
@@ -65,6 +68,21 @@ function suffix(repoId: string, requestId: string): string {
   return createHash('sha256').update(`${repoId}:${requestId}`).digest('hex').slice(0, 12);
 }
 
+export function managedWorkspaceOwnedResourceId(repoId: string, checkoutId: string): string {
+  return `managed-worktree:${repoId}:${checkoutId}`;
+}
+
+export function managedBranchOwnedResourceId(repoId: string, checkoutId: string): string {
+  return `managed-branch:${repoId}:${checkoutId}`;
+}
+
+export function managedBranchOwnedResourceLocator(repositoryRoot: string, checkoutId: string, branch: string): OwnedResourceLocator {
+  return {
+    kind: 'git_ref',
+    value: `${realpathSync(repositoryRoot)}\0${checkoutId.trim()}\0refs/heads/${branch.trim()}`,
+  };
+}
+
 function git(root: string, args: string[], timeoutMs = 30_000): string {
   const result = runProcess(resolveGitExecutable(), ['-C', root, ...args], {
     timeoutMs,
@@ -385,6 +403,10 @@ export function ensureManagedWorkspace(
         throw new Error(`MANAGED_WORKSPACE_REQUEST_CONFLICT: ${requestId}`);
       }
       const branch = manifest?.branch ?? requestedBranch;
+      // Persisted manifests are Forge provenance. Without one, an already-existing
+      // branch/worktree is never adopted as cleanup-owned merely because its name/path matches.
+      let workspaceOwnedByForge = Boolean(manifest);
+      let branchOwnedByForge = Boolean(manifest);
       // Persisted manifests are authoritative evidence; never move an active worktree in place.
       const path = manifest?.path ? resolve(manifest.path) : requestedPath;
       const baseRevision = manifest?.baseRevision ?? git(sourceRoot, ['rev-parse', '--verify', `${requestedBaseRef}^{commit}`]);
@@ -396,8 +418,11 @@ export function ensureManagedWorkspace(
           // A daemon crash may leave stale worktree administration behind even after the directory is gone.
           git(sourceRoot, ['worktree', 'prune', '--expire', 'now'], 120_000);
           git(sourceRoot, ['worktree', 'add', path, branch], 120_000);
+          workspaceOwnedByForge = true;
         } else {
           git(sourceRoot, ['worktree', 'add', '-b', branch, path, baseRevision], 120_000);
+          workspaceOwnedByForge = true;
+          branchOwnedByForge = true;
         }
       }
       if (!repositoryCheckoutRootMatches(repository, path)) {
@@ -425,6 +450,38 @@ export function ensureManagedWorkspace(
       );
       if (!checkout) throw new Error(`MANAGED_WORKSPACE_CHECKOUT_NOT_REGISTERED: ${path}`);
       const selected = selectRepositoryCheckout(record, checkout.checkoutId);
+      const ownerForgeInstanceId = ensureForgeInstanceIdentity({ controllerHome }).instanceId;
+      const workspaceResourceId = managedWorkspaceOwnedResourceId(repository.repoId, checkout.checkoutId);
+      const branchResourceId = managedBranchOwnedResourceId(repository.repoId, checkout.checkoutId);
+      const existingWorkspaceResource = getOwnedResource(controllerHome, workspaceResourceId);
+      const existingBranchResource = getOwnedResource(controllerHome, branchResourceId);
+      if (existingWorkspaceResource?.cleanupCapable === false) workspaceOwnedByForge = false;
+      if (existingBranchResource?.cleanupCapable === false) branchOwnedByForge = false;
+      recordOwnedResource(controllerHome, {
+        resourceId: workspaceResourceId,
+        kind: 'worktree',
+        targetRef: selected.canonicalRoot,
+        cleanupCapable: workspaceOwnedByForge,
+        creator: 'forge:managed-workspace',
+        ownerForgeInstanceId,
+        associatedWorkId: input.associatedWorkId,
+        repoId: repository.repoId,
+        retentionIntent: 'temporary',
+      });
+      const branchLocator = managedBranchOwnedResourceLocator(repository.canonicalRoot, checkout.checkoutId, branch);
+      recordOwnedResource(controllerHome, {
+        resourceId: branchResourceId,
+        kind: 'git_branch',
+        targetRef: branch,
+        locator: branchLocator,
+        identityFingerprint: ownedResourceLocatorFingerprint(ownerForgeInstanceId, branchLocator),
+        cleanupCapable: branchOwnedByForge,
+        creator: 'forge:managed-workspace',
+        ownerForgeInstanceId,
+        associatedWorkId: input.associatedWorkId,
+        repoId: repository.repoId,
+        retentionIntent: 'retain_on_failure',
+      });
       if (!manifest) {
         writeJsonAtomic(statePath, {
           schemaVersion: 1,

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

@@ -153,7 +153,7 @@ export async function runCheckViaProcessRuntime(
       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,
     };

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

@@ -1,5 +1,5 @@
 /**
- * repository_command_execute → three explicit execution lanes.
+ * execute_command → three explicit execution lanes.
  *
  * - Ephemeral Direct: bounded ordinary reads and commands that finish inside
  *   the interactive budget.
@@ -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;
@@ -337,7 +345,7 @@ export async function executeRepositoryCommandViaProcessRuntime(
       durableSideEffects: emptyEffects,
       suggestedOperation: decision.reason === 'standalone_recovery_lifecycle_required'
         ? 'Use the standalone Forge Recovery connector for canonical Runtime/connector lifecycle operations.'
-        : 'repository_command_execute via Durable Work / Local Job',
+        : 'execute_command via Durable Work / Local Job',
       externalEffect: decision.route === 'durable'
         ? {
             outcome: 'not_started',
@@ -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),
@@ -536,7 +550,7 @@ export async function executeRepositoryCommandViaProcessRuntime(
     resourceClaims: toProcessClaims(claims),
     origin: {
       surface: 'command',
-      toolName: 'repository_command_execute',
+      toolName: 'execute_command',
       requestId: input.requestId,
       correlationId: input.workId,
     },
@@ -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 ?? '');