@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/control-plane/execution/work-preparation-service.ts

@@ -1,23 +1,20 @@
 import { createHash } from 'crypto';
 import { spawnSync } from 'child_process';
 import type { McpExecutionContext } from '../../../../packages/protocols/mcp/execution-context';
-import type { RepositoryRecord } from '../../../cli/repositories/types';
 import { getRepository, resolveRepositorySelection, selectRepositoryCheckout } from '../../../cli/repositories/registry';
 import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
 import { ensureManagedWorkspace } from '../../execution/managed-workspace';
+import { listRecoverableProcessRecords } from '../../execution/process-runtime/store';
 import { readRepositoryAccessPolicy } from '../governance/access-policy';
-import { activateWorkContract, appendWorkEvidence, failWorkContract, getWorkContract, recordWorkEvidenceState, updateWorkContract } from '../../../../packages/kernel/work/api/index';
-import { admitPreparedRepositoryWorkContract } from '../facade/repository-work-admission';
-import { isTerminalWorkContractStatus, type WorkReconciliationRecord } from '../facade/types';
-import { claimControllerSession, getControllerSession, resumeControllerSession } from '../../../../packages/kernel/controller/api/index';
+import { activateWorkContract, failWorkContract, getWorkContract } from '../../../../packages/kernel/work/api/index';
+import { admitPreparedRepositoryWorkContract, materializeRepositoryWorkPlacement } from '../facade/repository-work-admission';
+import { isTerminalSemanticWorkState } from '../facade/types';
 import { updateExecutionSession, type ExecutionSessionContext } from './session-store';
 import { currentPermissionSnapshotVersion, validateWorkHandle } from './validation';
-import { assertExecutionIdentity, executionIdentityFromCoordinates } from './execution-identity';
 import { withWorkPrepareRequest } from './work-prepare-request-store';
-import { markWorkHandleFailed, newWorkId, readWorkHandle, transitionWorkHandle, writeWorkHandle, type WorkFinalizationStages, type WorkHandleState } from './work-handle-store';
-import { assertWorkPathsWithinScope } from './work-path-scope';
+import { markWorkHandleFailed, newWorkId, readWorkHandle, relocateWorkHandlePlacementAtomically, writeWorkHandle, type WorkFinalizationStages, type WorkHandleState } from './work-handle-store';
 import { createGoalDelegation } from '../governance/authorization';
-import { compactHandle, contractFor, findWorkHandle, gitChangedPaths, gitCommit, gitHead, gitMergeBase, identityFor, requireSession, selectWorkFinalizationTarget } from './work-execution-support';
+import { compactHandle, contractFor, findWorkHandle, gitHead, gitIsAncestor, identityFor, requireSession } from './work-execution-support';
 
 function requireExplicitRepoId(args: Record<string, unknown>): string {
   const value = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
@@ -39,26 +36,17 @@ function initialStage(): WorkFinalizationStages {
   return { validation: 'pending', commit: 'pending', merge: 'pending', branchCleanup: 'pending', worktreeCleanup: 'pending' };
 }
 
-/**
- * A previous finalization request may have validated a Work and explicitly
- * skipped every effectful stage without delivering or cleaning anything. That
- * is retryable preparation history, not an irreversible finalization boundary.
- * Any done/failed effectful stage or retained finalization error stays fenced.
- */
-export function workHeadAdoptionFinalizationIsRetryable(stages: WorkFinalizationStages): boolean {
-  if (stages.validation === 'failed' || stages.lastError) return false;
-  return [stages.commit, stages.merge, stages.branchCleanup, stages.worktreeCleanup]
-    .every((stage) => stage === 'pending' || stage === 'skipped');
-}
 
-function normalizedRequiredString(args: Record<string, unknown>, key: string): string | undefined {
-  return typeof args[key] === 'string' && args[key].trim() ? args[key].trim() : undefined;
-}
 
 function boundedStringArray(value: unknown, limit: number): string[] {
   return Array.isArray(value) ? value.map(String).slice(0, limit) : [];
 }
 
+function requestedWorkPrepareIsolation(args: Record<string, unknown>): 'reuse' | 'new_worktree' | 'auto' | undefined {
+  if (!Object.prototype.hasOwnProperty.call(args, 'isolation')) return undefined;
+  return args.isolation === 'reuse' || args.isolation === 'new_worktree' || args.isolation === 'auto' ? args.isolation : 'auto';
+}
+
 function workPrepareFingerprint(input: {
   repoId: string;
   requestedCheckoutId?: string;
@@ -74,231 +62,12 @@ function workPrepareFingerprint(input: {
   return createHash('sha256').update(JSON.stringify({ schemaVersion: 1, operation: 'work_prepare', ...input })).digest('hex');
 }
 
-function claimPreparedWorkOwnership(
-  ctx: McpExecutionContext,
-  session: ExecutionSessionContext,
-  handle: WorkHandleState,
-  args: Record<string, unknown>,
-): void {
-  const workIdValue = handle.workContractId ?? handle.workId;
-  const controllerId = typeof args.controller_id === 'string' && args.controller_id.trim()
-    ? args.controller_id.trim()
-    : session.principalId;
-  claimControllerSession({ controllerHome: ctx.controllerHome, repoId: handle.repositoryId }, {
-    workId: workIdValue,
-    controllerId,
-    controllerType: 'chatgpt',
-    sessionId: session.sessionId,
-    principalId: session.principalId,
-    controllerInstanceId: session.controllerInstanceId,
-    leaseMs: 3_600_000,
-  });
-}
-
-function claimHeadAdoptionOwnership(
-  ctx: McpExecutionContext,
-  session: ExecutionSessionContext,
-  handle: WorkHandleState,
-  args: Record<string, unknown>,
-): void {
-  const workIdValue = handle.workContractId ?? handle.workId;
-  const controllerId = normalizedRequiredString(args, 'controller_id') ?? session.principalId;
-  if (controllerId !== session.principalId) {
-    throw new Error('WORK_CONTROLLER_IDENTITY_MISMATCH: controller_id must match the authenticated principal');
-  }
-  const options = { controllerHome: ctx.controllerHome, repoId: handle.repositoryId };
-  const current = getControllerSession(options, workIdValue);
-  const input = {
-    workId: workIdValue,
-    controllerId,
-    controllerType: current?.controllerType ?? 'chatgpt' as const,
-    sessionId: session.sessionId,
-    principalId: session.principalId,
-    controllerInstanceId: session.controllerInstanceId,
-    expectedClaimGeneration: current?.claimGeneration ?? 0,
-    leaseMs: 3_600_000,
-  };
-  const claimed = current
-    ? resumeControllerSession(options, input)
-    : claimControllerSession(options, input);
-  if (
-    claimed.controllerId !== controllerId
-    || claimed.sessionId !== session.sessionId
-    || claimed.principalId !== session.principalId
-    || claimed.controllerInstanceId !== session.controllerInstanceId
-    || (claimed.claimGeneration ?? 0) < 1
-  ) {
-    throw new Error('WORK_HEAD_ADOPTION_OWNERSHIP_FENCE_MISMATCH');
-  }
-}
-
-function adoptExistingWorkHead(
-  ctx: McpExecutionContext,
-  session: ExecutionSessionContext,
-  repository: RepositoryRecord,
-  handle: WorkHandleState,
-  args: Record<string, unknown>,
-): Record<string, unknown> | undefined {
-  const previousInput = normalizedRequiredString(args, 'expected_previous_head');
-  const candidateInput = normalizedRequiredString(args, 'adopt_candidate_head');
-  if (!previousInput && !candidateInput) return undefined;
-  if (!previousInput || !candidateInput) {
-    throw new Error('WORK_HEAD_ADOPTION_ARGUMENTS_REQUIRED: expected_previous_head and adopt_candidate_head must be provided together');
-  }
-  const requestedCheckoutId = normalizedRequiredString(args, 'checkout_id');
-  if (!requestedCheckoutId) throw new Error('WORK_HEAD_ADOPTION_CHECKOUT_REQUIRED: checkout_id must be explicit');
-  if (repository.repoId !== handle.repositoryId) throw new Error('WORK_HEAD_ADOPTION_REPOSITORY_MISMATCH');
-  if (requestedCheckoutId !== handle.checkoutId || repository.activeCheckoutId !== handle.checkoutId) {
-    throw new Error(`WORK_HEAD_ADOPTION_CHECKOUT_MISMATCH: expected ${handle.checkoutId}, found ${requestedCheckoutId}`);
-  }
-  if (!handle.managedWorktree) throw new Error('WORK_HEAD_ADOPTION_MANAGED_WORKTREE_REQUIRED');
-  if (handle.principalId !== session.principalId) throw new Error('WORK_HANDLE_PRINCIPAL_MISMATCH: work handle belongs to another principal');
-  if (handle.state !== 'prepared' && handle.state !== 'editing') {
-    throw new Error(`WORK_HEAD_ADOPTION_STATE_INVALID: ${handle.state}`);
-  }
-  if (!workHeadAdoptionFinalizationIsRetryable(handle.finalization)) {
-    throw new Error('WORK_HEAD_ADOPTION_FINALIZATION_ALREADY_STARTED');
-  }
-
-  const registered = getRepository(handle.repositoryId, ctx.controllerHome, { includeRemoved: true });
-  const registeredCheckout = registered.checkouts.find((entry) => entry.checkoutId === handle.checkoutId);
-  if (!registeredCheckout || registeredCheckout.lifecycle !== 'active' || registeredCheckout.worktree !== true) {
-    throw new Error('WORK_HEAD_ADOPTION_CHECKOUT_NOT_ACTIVE_MANAGED');
-  }
-  const worktreeRepository = selectRepositoryCheckout(registered, handle.checkoutId);
-  const guarded = assertExecutionIdentity({
-    controllerHome: ctx.controllerHome,
-    identity: executionIdentityFromCoordinates({
-      repositoryId: handle.repositoryId,
-      checkoutId: handle.checkoutId,
-      canonicalRoot: handle.worktreePath,
-      workId: handle.workId,
-      worktreePath: handle.worktreePath,
-      branch: handle.branch,
-    }),
-    cwd: handle.worktreePath,
-    requestedRepoId: repository.repoId,
-    requestedCheckoutId,
-  });
-  const status = repositoryGitStatus(worktreeRepository);
-  if (!status.clean) throw new Error('WORK_HEAD_ADOPTION_WORKTREE_DIRTY');
-
-  const previousHead = gitCommit(handle.worktreePath, previousInput, 'PREVIOUS_HEAD');
-  const candidateHead = gitCommit(handle.worktreePath, candidateInput, 'CANDIDATE_HEAD');
-  const authoritativePrevious = handle.expectedHead ? gitCommit(handle.worktreePath, handle.expectedHead, 'AUTHORITATIVE_PREVIOUS_HEAD') : undefined;
-  if (!authoritativePrevious || authoritativePrevious !== previousHead) {
-    throw new Error(`WORK_HEAD_ADOPTION_PREVIOUS_HEAD_MISMATCH: expected ${authoritativePrevious ?? 'missing'}, found ${previousHead}`);
-  }
-  if (guarded.currentHead !== candidateHead || status.head !== candidateHead) {
-    throw new Error(`WORK_HEAD_ADOPTION_CANDIDATE_NOT_CURRENT: expected current HEAD ${candidateHead}, found ${guarded.currentHead ?? status.head ?? 'missing'}`);
-  }
-  if (previousHead === candidateHead) throw new Error('WORK_HEAD_ADOPTION_SUCCESSOR_REQUIRED');
-  const ancestry = spawnSync('git', ['-C', handle.worktreePath, 'merge-base', '--is-ancestor', previousHead, candidateHead], {
-    encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000,
-  });
-  if (ancestry.status !== 0 || ancestry.error) throw new Error('WORK_HEAD_ADOPTION_NOT_DESCENDANT');
-
-  const contract = contractFor(ctx, handle);
-  if (!contract || contract.repoId !== handle.repositoryId) throw new Error('WORK_HEAD_ADOPTION_CONTRACT_MISSING');
-  if (isTerminalWorkContractStatus(contract.status) || contract.completionReceipt) {
-    throw new Error('WORK_HEAD_ADOPTION_CONTRACT_TERMINAL');
-  }
-  // expectedHead can predate unrelated commits that landed on the source checkout
-  // before this Work was rebased. Scope adoption to the candidate's unique delta
-  // from the current source-checkout merge-base; otherwise those target-branch
-  // commits are incorrectly attributed to the Work and fail its allow-list.
-  const sourceRepository = selectWorkFinalizationTarget(registered, handle);
-  const sourceHead = handle.sourceCheckoutId && handle.sourceCheckoutId !== handle.checkoutId
-    ? repositoryGitStatus(sourceRepository).head
-    : undefined;
-  const scopeBaseHead = sourceHead ? gitMergeBase(handle.worktreePath, sourceHead, candidateHead) : previousHead;
-  const changedPaths = gitChangedPaths(handle.worktreePath, scopeBaseHead, candidateHead);
-  assertWorkPathsWithinScope(contract, changedPaths, {
-    forbidden: 'WORK_HEAD_ADOPTION_FORBIDDEN_PATH',
-    outOfScope: 'WORK_HEAD_ADOPTION_PATH_OUT_OF_SCOPE',
-  });
-
-  claimHeadAdoptionOwnership(ctx, session, handle, args);
-
-  const reviewedAt = new Date().toISOString();
-  const reconciliationId = `RECNC-${createHash('sha256').update([
-    handle.repositoryId, handle.workId, previousHead, candidateHead, handle.checkoutId, handle.branch,
-  ].join('\0')).digest('hex').slice(0, 16)}`;
-  const reconciliation: WorkReconciliationRecord = {
-    schemaVersion: 1,
-    reconciliationId,
-    originalExpectedRevision: previousHead,
-    observedTargetRevision: candidateHead,
-    baseRevision: gitCommit(handle.worktreePath, handle.baseCommit ?? previousHead, 'BASE_HEAD'),
-    targetBranch: handle.branch,
-    reachable: true,
-    method: 'exact_commit',
-    comparedPaths: changedPaths,
-    reviewer: session.principalId.slice(0, 200),
-    reviewedAt,
-    unrecoverableStages: [],
-    cleanupOwnershipProof: `No cleanup was performed; managed checkout ${handle.checkoutId} remains owned by Work finalizer.`,
-    rationale: 'Adopted an exact clean successor commit after repository, checkout, worktree, branch, controller ownership, ancestry, and WorkContract path-scope verification. This reconciliation is not completion evidence.',
-    outcome: 'accepted_equivalence',
-  };
-
-  const adopted = transitionWorkHandle(ctx.controllerHome, handle, 'editing', {
-    deliveryBaseCommit: scopeBaseHead,
-    expectedHead: candidateHead,
-    failureReason: undefined,
-    finalization: initialStage(),
-    validationRun: undefined,
-    validatedInputFingerprint: undefined,
-  });
-  try {
-    recordWorkEvidenceState(
-      { controllerHome: ctx.controllerHome, repoId: handle.repositoryId },
-      contract.workId,
-      contract.checkRefs.length === 0
-        ? contract.evidenceState
-        : contract.evidenceState === 'valid' || contract.evidenceState === 'stale'
-          ? 'stale'
-          : 'partial',
-    );
-    updateWorkContract({ controllerHome: ctx.controllerHome, repoId: handle.repositoryId }, contract.workId, {
-      reconciliations: [reconciliation, ...contract.reconciliations.filter((entry) => entry.reconciliationId !== reconciliationId)],
-    });
-    appendWorkEvidence({ controllerHome: ctx.controllerHome, repoId: handle.repositoryId }, contract.workId, {
-      title: 'audited WorkHandle successor HEAD adoption',
-      summary: `${previousHead} -> ${candidateHead}; ${changedPaths.length} candidate-unique path(s) from scope base ${scopeBaseHead} remained within the WorkContract allow-list. Historical validation and completion receipts were not rewritten.`,
-      detailLevel: 'summary',
-    });
-  } catch (error) {
-    try {
-      writeWorkHandle(ctx.controllerHome, { ...handle, recordRevision: adopted.recordRevision });
-    } catch (rollbackError) {
-      throw new Error(`WORK_HEAD_ADOPTION_AUDIT_WRITE_FAILED_AND_ROLLBACK_FAILED: ${String(error)}; ${String(rollbackError)}`);
-    }
-    throw error;
-  }
-  const nextSession = updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), {
-    activeRepositoryId: handle.repositoryId,
-    activeCheckoutId: handle.checkoutId,
-    activeWorkId: handle.workId,
-    permissionSnapshotVersion: handle.permissionSnapshotVersion,
-    lastValidatedAt: reviewedAt,
-  });
-  return {
-    session: nextSession,
-    work: compactHandle(adopted),
-    reused: true,
-    adopted: true,
-    adoption: { previousHead, candidateHead, changedPaths, reconciliationId },
-    controllerClaimed: true,
-  };
-}
-
 function invalidateActiveWork(ctx: McpExecutionContext, session: ExecutionSessionContext, reason: string): void {
   if (!session.activeRepositoryId || !session.activeWorkId) return;
   const handle = readWorkHandle(ctx.controllerHome, session.activeRepositoryId, session.activeWorkId);
   if (!handle || handle.state === 'cleaned') return;
   const contract = contractFor(ctx, handle);
-  if (contract?.status === 'completed') return;
+  if (contract?.semanticState === 'completed') return;
   markWorkHandleFailed(ctx.controllerHome, handle, reason);
 }
 
@@ -318,6 +87,171 @@ export function bindSessionRepository(ctx: McpExecutionContext, args: Record<str
   return { session: next, repository: { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, canonicalRoot: repository.canonicalRoot, branch: repository.checkouts.find((entry) => entry.checkoutId === repository.activeCheckoutId)?.branch ?? null }, switched: switching };
 }
 
+function gitPathSet(root: string, args: string[], code: string): Set<string> {
+  const result = spawnSync('git', ['-C', root, ...args, '-z'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10_000,
+  });
+  if (result.error || result.status !== 0) throw new Error(`${code}: ${result.error?.message ?? result.stderr?.trim() ?? `git ${args.join(' ')} failed`}`);
+  return new Set(String(result.stdout ?? '').split('\0').map((value) => value.trim()).filter(Boolean));
+}
+
+function currentDirtyPaths(root: string): Set<string> {
+  const paths = new Set<string>();
+  for (const path of gitPathSet(root, ['diff', '--name-only'], 'WORK_HANDLE_SUCCESSOR_ADOPTION_DIRTY_PATHS_UNAVAILABLE')) paths.add(path);
+  for (const path of gitPathSet(root, ['diff', '--cached', '--name-only'], 'WORK_HANDLE_SUCCESSOR_ADOPTION_DIRTY_PATHS_UNAVAILABLE')) paths.add(path);
+  for (const path of gitPathSet(root, ['ls-files', '--others', '--exclude-standard'], 'WORK_HANDLE_SUCCESSOR_ADOPTION_DIRTY_PATHS_UNAVAILABLE')) paths.add(path);
+  return paths;
+}
+
+function adoptExplicitSuccessorHead(
+  ctx: McpExecutionContext,
+  args: Record<string, unknown>,
+  repository: ReturnType<typeof selectedRepository>,
+  existing: WorkHandleState,
+): WorkHandleState | undefined {
+  const expectedPreviousHead = typeof args.expected_previous_head === 'string' ? args.expected_previous_head.trim() : '';
+  const adoptCandidateHead = typeof args.adopt_candidate_head === 'string' ? args.adopt_candidate_head.trim() : '';
+  if (!expectedPreviousHead && !adoptCandidateHead) return undefined;
+  if (!expectedPreviousHead || !adoptCandidateHead) {
+    throw new Error('WORK_HANDLE_SUCCESSOR_ADOPTION_PAIR_REQUIRED: expected_previous_head and adopt_candidate_head must be supplied together');
+  }
+  // A failed validation attempt may need an explicit, audited successor
+  // adoption before it can retry against the current checkout. Keep its
+  // failed state: only a fresh valid check may restore execution authority.
+  const retryableValidationFailure = existing.state === 'failed'
+    && existing.finalization.validation === 'failed';
+  if (existing.state !== 'prepared' && existing.state !== 'editing' && !retryableValidationFailure) {
+    throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_STATE_INVALID: ${existing.state}`);
+  }
+  if (existing.expectedHead !== expectedPreviousHead) {
+    throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_PREVIOUS_HEAD_MISMATCH: expected ${existing.expectedHead ?? 'missing'}, received ${expectedPreviousHead}`);
+  }
+  if (existing.repositoryId !== repository.repoId || existing.checkoutId !== repository.activeCheckoutId) {
+    throw new Error('WORK_HANDLE_SUCCESSOR_ADOPTION_CHECKOUT_MISMATCH');
+  }
+  const root = existing.worktreePath;
+  const currentHead = gitHead(root);
+  if (!currentHead || currentHead !== adoptCandidateHead) {
+    throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_CURRENT_HEAD_MISMATCH: expected ${adoptCandidateHead}, found ${currentHead ?? 'missing'}`);
+  }
+  if (!gitIsAncestor(root, expectedPreviousHead, adoptCandidateHead)) {
+    throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_NONLINEAR: ${expectedPreviousHead} is not an ancestor of ${adoptCandidateHead}`);
+  }
+  const changedPaths = gitPathSet(root, ['diff', '--name-only', `${expectedPreviousHead}..${adoptCandidateHead}`], 'WORK_HANDLE_SUCCESSOR_ADOPTION_DIFF_UNAVAILABLE');
+  const dirtyPaths = currentDirtyPaths(root);
+  if (existing.managedWorktree) {
+    if (dirtyPaths.size > 0) {
+      throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_MANAGED_DIRTY: ${[...dirtyPaths].sort().slice(0, 20).join(',')}`);
+    }
+    const blockingProcesses = listRecoverableProcessRecords(ctx.controllerHome, existing.repositoryId)
+      .filter((record) => record.workId === existing.workId)
+      .map((record) => record.processId)
+      .sort();
+    if (blockingProcesses.length > 0) {
+      throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_ACTIVE_PROCESS: ${blockingProcesses.slice(0, 20).join(',')}`);
+    }
+  } else {
+    const overlap = [...changedPaths].filter((path) => dirtyPaths.has(path)).sort();
+    if (overlap.length > 0) {
+      throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_DIRTY_OVERLAP: ${overlap.slice(0, 20).join(',')}`);
+    }
+  }
+  const candidate: WorkHandleState = {
+    ...existing,
+    // Successor adoption advances the Work candidate, not the delivery target.
+    // Preserve the canonical delivery base until authorized delivery or rebase.
+    expectedHead: adoptCandidateHead,
+    validationRun: undefined,
+    validatedInputFingerprint: undefined,
+    finalization: initialStage(),
+    failureReason: undefined,
+  };
+  validateWorkHandle(ctx.controllerHome, candidate, identityFor(ctx, args), 'cheap', 'inspect');
+  return writeWorkHandle(ctx.controllerHome, candidate);
+}
+
+function relocateExistingWorkToManagedCheckout(
+  ctx: McpExecutionContext,
+  args: Record<string, unknown>,
+  session: ExecutionSessionContext,
+  repository: ReturnType<typeof selectedRepository>,
+  existing: WorkHandleState,
+): Record<string, unknown> {
+  const prior = typeof args.expected_previous_head === 'string' ? args.expected_previous_head.trim() : '';
+  const candidate = typeof args.adopt_candidate_head === 'string' ? args.adopt_candidate_head.trim() : '';
+  const baseRef = typeof args.base_ref === 'string' ? args.base_ref.trim() : '';
+  if (!prior || !candidate || baseRef !== candidate || !/^[0-9a-f]{40}$/.test(candidate)) {
+    throw new Error('WORK_RELOCATION_EXACT_HEADS_REQUIRED: supply expected_previous_head and matching base_ref/adopt_candidate_head');
+  }
+  if (existing.principalId !== session.principalId) throw new Error('WORK_HANDLE_ACCESS_DENIED');
+  if (existing.expectedHead !== prior && !(existing.managedWorktree && existing.expectedHead === candidate)) {
+    throw new Error('WORK_RELOCATION_PREVIOUS_HEAD_MISMATCH');
+  }
+  if (existing.managedWorktree) {
+    if (existing.expectedHead !== candidate) throw new Error('WORK_RELOCATION_ALREADY_ISOLATED');
+    validateWorkHandle(ctx.controllerHome, existing, identityFor(ctx, args), 'cheap', 'inspect');
+    updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), {
+      activeRepositoryId: existing.repositoryId, activeCheckoutId: existing.checkoutId,
+      activeWorkId: existing.workId, permissionSnapshotVersion: existing.permissionSnapshotVersion,
+    });
+    return { session: requireSession(ctx, args), work: compactHandle(existing), reused: true, relocated: true };
+  }
+  if (existing.state !== 'prepared' && existing.state !== 'editing') throw new Error('WORK_RELOCATION_STATE_INVALID');
+  if (existing.finalization.validation !== 'pending' || existing.finalization.commit !== 'pending' || existing.finalization.merge !== 'pending'
+      || existing.finalization.worktreeCleanup !== 'pending' || existing.finalization.branchCleanup !== 'pending'
+      || existing.cleanupReceipt || existing.validatedInputFingerprint || existing.validationRun) {
+    throw new Error('WORK_RELOCATION_FINALIZATION_IN_PROGRESS');
+  }
+  const contract = getWorkContract({ controllerHome: ctx.controllerHome, repoId: existing.repositoryId }, existing.workId);
+  if (!contract || contract.semanticState !== 'open' || contract.completionReceipt || contract.completionOutcome
+      || contract.checkoutId !== existing.checkoutId) throw new Error('WORK_RELOCATION_CONTRACT_MISMATCH');
+  if (existing.checkoutId !== repository.activeCheckoutId || existing.worktreePath !== repository.canonicalRoot
+      || existing.branch !== repositoryGitStatus(repository).branch) throw new Error('WORK_RELOCATION_SOURCE_MISMATCH');
+  if (!gitIsAncestor(existing.worktreePath, prior, candidate)) throw new Error('WORK_RELOCATION_NONLINEAR');
+  const changedPaths = gitPathSet(existing.worktreePath, ['diff', '--name-only', prior + '..' + candidate], 'WORK_RELOCATION_DIFF_UNAVAILABLE');
+  const dirtyPaths = currentDirtyPaths(existing.worktreePath);
+  const overlap = [...changedPaths].filter((path) => dirtyPaths.has(path));
+  if (overlap.length) throw new Error('WORK_RELOCATION_DIRTY_OVERLAP: ' + overlap.sort().join(','));
+  if (listRecoverableProcessRecords(ctx.controllerHome, existing.repositoryId).some((record) => record.workId === existing.workId)) {
+    throw new Error('WORK_RELOCATION_ACTIVE_PROCESS');
+  }
+  const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+  if (!requestId) throw new Error('WORK_RELOCATION_REQUEST_ID_REQUIRED');
+  // A deterministic request identity makes physical worktree creation safe to
+  // resume after a process crash before the authoritative database transaction.
+  const workspace = ensureManagedWorkspace(ctx.controllerHome, repository, {
+    requestId: 'relocate:' + existing.workId + ':' + candidate,
+    title: 'Relocate existing Work to managed checkout',
+    associatedWorkId: existing.workId,
+    baseRef: candidate,
+    prepareDependencies: false,
+  });
+  if (!workspace.managed || !workspace.checkoutId || !workspace.root || !workspace.branch) {
+    throw new Error('WORK_RELOCATION_TARGET_NOT_MANAGED');
+  }
+  const selectedTarget = resolveRepositorySelection({
+    repoId: existing.repositoryId, checkoutId: workspace.checkoutId,
+    controllerHome: ctx.controllerHome, allowSoleRepository: false,
+  });
+  const targetStatus = repositoryGitStatus(selectedTarget);
+  if (!targetStatus.clean || targetStatus.head !== candidate || targetStatus.branch !== workspace.branch
+      || workspace.checkoutId === existing.checkoutId || selectedTarget.canonicalRoot !== workspace.root) {
+    throw new Error('WORK_RELOCATION_TARGET_CHANGED');
+  }
+  const refreshed = relocateWorkHandlePlacementAtomically(ctx.controllerHome, existing, {
+    checkoutId: workspace.checkoutId, root: workspace.root,
+    branch: workspace.branch, head: candidate,
+  });
+  updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), {
+    activeRepositoryId: refreshed.repositoryId, activeCheckoutId: refreshed.checkoutId,
+    activeWorkId: refreshed.workId, permissionSnapshotVersion: refreshed.permissionSnapshotVersion,
+  });
+  return { session: requireSession(ctx, args), work: compactHandle(refreshed), relocated: true,
+    previousCheckoutId: existing.checkoutId, previousHead: prior, currentHead: candidate };
+}
+
 export function prepareWork(ctx: McpExecutionContext, args: Record<string, unknown>): Record<string, unknown> {
   const session = requireSession(ctx, args);
   const repository = selectedRepository(ctx, session, args, true);
@@ -325,21 +259,38 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
     updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), { activeRepositoryId: repository.repoId, activeCheckoutId: repository.activeCheckoutId, permissionSnapshotVersion: currentPermissionSnapshotVersion(ctx.controllerHome, repository.repoId) });
   }
   const existingId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  if (args.relocate_to_new_worktree === true && !existingId) throw new Error('WORK_RELOCATION_EXISTING_WORK_ID_REQUIRED');
+  const requestedIsolation = requestedWorkPrepareIsolation(args);
   if (existingId) {
     const existing = readWorkHandle(ctx.controllerHome, repository.repoId, existingId)
       ?? findWorkHandle(ctx, session, { ...args, work_id: existingId, repo_id: repository.repoId });
     if (existing.principalId !== session.principalId) throw new Error('WORK_HANDLE_ACCESS_DENIED');
-    const adopted = adoptExistingWorkHead(ctx, session, repository, existing, args);
-    if (adopted) return adopted;
-    validateWorkHandle(ctx.controllerHome, existing, identityFor(ctx, args), 'cheap', 'inspect');
-    updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), { activeRepositoryId: existing.repositoryId, activeCheckoutId: existing.checkoutId, activeWorkId: existing.workId, permissionSnapshotVersion: existing.permissionSnapshotVersion });
-    claimPreparedWorkOwnership(ctx, session, existing, args);
-    return { session: requireSession(ctx, args), work: compactHandle(existing), reused: true, controllerClaimed: true };
+    if (args.relocate_to_new_worktree === true) {
+      if (requestedIsolation !== undefined) throw new Error('WORK_RELOCATION_ISOLATION_CONFLICT');
+      return relocateExistingWorkToManagedCheckout(ctx, args, session, repository, existing);
+    }
+    if (requestedIsolation !== undefined) {
+      const requestedWorkspaceMode = requestedIsolation === 'reuse' ? 'current' : 'isolated';
+      const existingWorkspaceMode = existing.managedWorktree ? 'isolated' : 'current';
+      if (requestedWorkspaceMode !== existingWorkspaceMode) {
+        throw new Error(`WORK_PREPARE_PLACEMENT_CONFLICT: ${existingId}; existing=${existingWorkspaceMode}; requested=${requestedWorkspaceMode}`);
+      }
+    }
+    const adopted = adoptExplicitSuccessorHead(ctx, args, repository, existing);
+    const active = adopted ?? existing;
+    if (!adopted) validateWorkHandle(ctx.controllerHome, active, identityFor(ctx, args), 'cheap', 'inspect');
+    updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), { activeRepositoryId: active.repositoryId, activeCheckoutId: active.checkoutId, activeWorkId: active.workId, permissionSnapshotVersion: active.permissionSnapshotVersion });
+    return {
+      session: requireSession(ctx, args),
+      work: compactHandle(active),
+      reused: true,
+      ...(adopted ? { adoptedSuccessor: { previousHead: existing.expectedHead, currentHead: adopted.expectedHead } } : {}),
+    };
   }
 
   const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
   if (!requestId) throw new Error('WORK_PREPARE_REQUEST_ID_REQUIRED: new work preparation requires request_id');
-  const isolation = args.isolation === 'reuse' || args.isolation === 'new_worktree' || args.isolation === 'auto' ? args.isolation : 'auto';
+  const isolation = requestedWorkPrepareIsolation(args) ?? 'auto';
   const objective = String(args.objective ?? 'Controller-managed repository work').trim().slice(0, 2_000);
   const goalId = typeof args.goal_id === 'string' && args.goal_id.trim() ? args.goal_id.trim() : undefined;
   const acceptanceCriteria = boundedStringArray(args.acceptance_criteria, 20);
@@ -350,8 +301,12 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
   const needsDependencies = args.needs_dependencies === true;
   const baseCheckoutId = repository.activeCheckoutId;
   const baseStatus = repositoryGitStatus(repository);
+  const deliveryTargetBranch = baseStatus.branch;
+  if (!deliveryTargetBranch) throw new Error(`WORK_DELIVERY_TARGET_DETACHED: source checkout ${baseCheckoutId} has no branch`);
   if (isolation === 'reuse' && !baseStatus.clean) throw new Error('WORKTREE_DIRTY: reuse was requested but the selected checkout is dirty; choose new_worktree or auto');
-  const useWorktree = isolation === 'new_worktree' || (isolation === 'auto' && !baseStatus.clean);
+  // A repository Work freezes its start revision on its own checkout. Sharing the
+  // canonical checkout is an explicit model choice (`reuse`), never the auto path.
+  const useWorktree = isolation !== 'reuse';
   const policy = readRepositoryAccessPolicy(ctx.controllerHome, repository.repoId);
   const fingerprint = workPrepareFingerprint({
     repoId: repository.repoId,
@@ -378,28 +333,23 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
     const createdWorkId = request.workId;
     const existingHandle = readWorkHandle(ctx.controllerHome, repository.repoId, createdWorkId);
     if (existingHandle) {
-      if (existingHandle.principalId !== session.principalId || existingHandle.sessionId !== session.sessionId) {
-        throw new Error(`WORK_PREPARE_REQUEST_INDEX_CORRUPT: ${requestId}`);
-      }
       const existingContract = getWorkContract({ controllerHome: ctx.controllerHome, repoId: repository.repoId }, createdWorkId);
       if (!existingContract) throw new Error(`WORK_PREPARE_RESULT_LOST: ${requestId} has a Work handle without its WorkContract`);
-      const terminal = isTerminalWorkContractStatus(existingContract.status)
-        && !(existingContract.status === 'failed' && request.status === 'claimed');
+      const terminal = isTerminalSemanticWorkState(existingContract.semanticState);
       if (terminal) {
         return {
           session: requireSession(ctx, args),
           work: compactHandle(existingHandle),
           reused: true,
           terminal: true,
-          workContractStatus: existingContract.status,
-          controllerClaimed: false,
+          workContractStatus: existingContract.semanticState,
         };
       }
-      if (existingContract.status === 'open' || existingContract.status === 'failed') {
+      if (existingContract.semanticState === 'open') {
         activateWorkContract(
           { controllerHome: ctx.controllerHome, repoId: repository.repoId },
           createdWorkId,
-          { phase: 'implementation', summary: 'Prepared Work ownership resumed on the existing WorkHandle.', worktreeRef: existingHandle.worktreePath },
+          { phase: 'implementation', summary: 'Prepared Work resumed on the existing WorkHandle.', worktreeRef: existingHandle.worktreePath },
         );
       }
       const delegation = createGoalDelegation({
@@ -413,8 +363,7 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
         source: 'gpt_risk_delegate',
       });
       const nextSession = updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), { activeRepositoryId: repository.repoId, activeCheckoutId: existingHandle.checkoutId, activeWorkId: createdWorkId, permissionSnapshotVersion: policy.revision, goalDelegation: delegation, lastValidatedAt: new Date().toISOString() });
-      claimPreparedWorkOwnership(ctx, nextSession, existingHandle, args);
-      return { session: nextSession, work: compactHandle(existingHandle), reused: true, isolation: existingHandle.managedWorktree ? 'isolated' : 'current', controllerClaimed: true };
+      return { session: nextSession, work: compactHandle(existingHandle), reused: true, isolation: existingHandle.managedWorktree ? 'isolated' : 'current' };
     }
 
     let contract = getWorkContract({ controllerHome: ctx.controllerHome, repoId: repository.repoId }, createdWorkId);
@@ -422,8 +371,8 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
     if (request.status === 'prepared') {
       throw new Error(`WORK_PREPARE_RESULT_LOST: ${requestId} completed without a readable Work handle`);
     }
-    if (contract && (contract.status === 'completed' || contract.status === 'cancelled')) {
-      throw new Error(`WORK_PREPARE_REQUEST_TERMINAL: ${requestId} belongs to ${contract.status} Work ${createdWorkId}`);
+    if (contract && (contract.semanticState === 'completed' || contract.semanticState === 'cancelled')) {
+      throw new Error(`WORK_PREPARE_REQUEST_TERMINAL: ${requestId} belongs to ${contract.semanticState} Work ${createdWorkId}`);
     }
     if (!contract) {
       contract = admitPreparedRepositoryWorkContract(
@@ -457,19 +406,35 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
         ? ensureManagedWorkspace(ctx.controllerHome, repository, {
           requestId: createdWorkId,
           title: objective,
+          associatedWorkId: createdWorkId,
           baseRef,
           prepareDependencies: needsDependencies,
         })
         : { mode: 'current' as const, checkoutId: baseCheckoutId, root: repository.canonicalRoot, branch: baseStatus.branch ?? 'detached', baseRevision: baseStatus.head ?? undefined, managed: false };
+      if (workspace.managed) {
+        const materialized = materializeRepositoryWorkPlacement(
+          { controllerHome: ctx.controllerHome, repoId: repository.repoId },
+          contract.workId,
+          () => workspace,
+        );
+        if (!materialized) throw new Error(`WORK_PLACEMENT_MATERIALIZATION_LOST: ${contract.workId}`);
+        contract = materialized;
+      }
       const refreshed = getRepository(repository.repoId, ctx.controllerHome);
       const checkout = selectRepositoryCheckout(refreshed, workspace.checkoutId);
+      if (workspace.managed && (
+        contract.checkoutId !== checkout.activeCheckoutId
+        || contract.worktreeRef !== checkout.canonicalRoot
+      )) {
+        throw new Error(`WORK_PLACEMENT_IDENTITY_DRIFT: contract=${contract.checkoutId ?? 'missing'}:${contract.worktreeRef ?? 'missing'}; checkout=${checkout.activeCheckoutId}:${checkout.canonicalRoot}`);
+      }
       const branch = workspace.branch || repositoryGitStatus(checkout).branch;
       if (!branch) throw new Error('WORKTREE_DETACHED: selected worktree has no branch');
       const head = gitHead(checkout.canonicalRoot);
       const handle: WorkHandleState = {
         schemaVersion: 1, workId: createdWorkId, sessionId: session.sessionId, principalId: session.principalId,
         repositoryId: repository.repoId, checkoutId: checkout.activeCheckoutId, worktreePath: checkout.canonicalRoot, branch,
-        sourceCheckoutId: baseCheckoutId, managedWorktree: workspace.managed, workContractId: contract.workId, goalId, delegationVersion: delegation.version,
+        sourceCheckoutId: baseCheckoutId, deliveryTargetBranch, managedWorktree: workspace.managed, workContractId: contract.workId, goalId, delegationVersion: delegation.version,
         baseCommit: workspace.baseRevision ?? head, deliveryBaseCommit: workspace.baseRevision ?? head, expectedHead: head, permissionSnapshotVersion: policy.revision,
         state: 'prepared', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), finalization: initialStage(),
         cleanupResponsibility: { owner: 'work_finalizer', registeredAt: new Date().toISOString() },
@@ -481,8 +446,7 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
         { phase: 'implementation', summary: 'Repository Work preparation completed and execution ownership is active.', worktreeRef: checkout.canonicalRoot },
       );
       const nextSession = updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), { activeRepositoryId: repository.repoId, activeCheckoutId: checkout.activeCheckoutId, activeWorkId: createdWorkId, permissionSnapshotVersion: policy.revision, goalDelegation: delegation, lastValidatedAt: new Date().toISOString() });
-      claimPreparedWorkOwnership(ctx, nextSession, handle, args);
-      return { session: nextSession, work: compactHandle(handle), reused: requestReused, isolation: workspace.mode, controllerClaimed: true };
+      return { session: nextSession, work: compactHandle(handle), reused: requestReused, isolation: workspace.mode };
     } catch (error) {
       failWorkContract(
         { controllerHome: ctx.controllerHome, repoId: repository.repoId },

package/src/runtime/control-plane/execution/work-process-evidence.ts

@@ -27,7 +27,7 @@ function isSuccessfulWorkRepositoryProcess(
   return record.workId === input.workId
     && record.checkoutId === input.checkoutId
     && record.origin?.surface === 'command'
-    && record.origin.toolName === 'repository_command_execute'
+    && record.origin.toolName === 'execute_command'
     && record.origin.correlationId === input.workId
     && isManagedProcessTerminal(record)
     && record.terminalWritten === true
@@ -42,7 +42,7 @@ function isSuccessfulWorkRepositoryProcess(
  * Re-derive bounded completion evidence from the canonical durable Process store.
  *
  * This deliberately does not create a second evidence authority. A qualifying
- * record must be the terminal successful repository_command_execute Process for
+ * record must be the terminal successful execute_command Process for
  * the exact Work + checkout, and the command-origin correlation must still name
  * the same Work. Lightweight handles never enter listProcessRecords(), so they
  * cannot satisfy this contract.