@moretea-labs/forge 1.7.2 → 1.8.1

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 { MultiRepositoryMcpToolContext } from '../../../cli/mcp/multi-repository';
-import type { RepositoryRecord } from '../../../cli/repositories/types';
+import type { McpExecutionContext } from '../../../../packages/protocols/mcp/execution-context';
 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 { appendWorkEvidence, getWorkContract, updateWorkContract } from '../facade/work-contract-store';
-import { admitPreparedRepositoryWorkContract } from '../facade/repository-work-admission';
-import { isTerminalWorkContractStatus, type WorkReconciliationRecord } from '../facade/types';
-import { claimControllerSession, getControllerSession, resumeControllerSession } from '../facade/controller-session-store';
+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, 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() : '';
@@ -25,7 +22,7 @@ function requireExplicitRepoId(args: Record<string, unknown>): string {
   return value;
 }
 
-function selectedRepository(ctx: MultiRepositoryMcpToolContext, session: ExecutionSessionContext, args: Record<string, unknown>, allowSession = true) {
+function selectedRepository(ctx: McpExecutionContext, session: ExecutionSessionContext, args: Record<string, unknown>, allowSession = true) {
   const requested = typeof args.repo_id === 'string' && args.repo_id.trim() ? args.repo_id.trim() : undefined;
   const selectedRepoId = requested ?? (allowSession ? session.activeRepositoryId : undefined);
   if (!selectedRepoId) throw new Error('SESSION_REPOSITORY_REQUIRED: bind a repository before using this work tool');
@@ -39,21 +36,7 @@ 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) : [];
@@ -74,231 +57,16 @@ function workPrepareFingerprint(input: {
   return createHash('sha256').update(JSON.stringify({ schemaVersion: 1, operation: 'work_prepare', ...input })).digest('hex');
 }
 
-function claimPreparedWorkOwnership(
-  ctx: MultiRepositoryMcpToolContext,
-  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: MultiRepositoryMcpToolContext,
-  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: MultiRepositoryMcpToolContext,
-  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 {
-    updateWorkContract({ controllerHome: ctx.controllerHome, repoId: handle.repositoryId }, contract.workId, {
-      evidenceState: contract.checkRefs.length === 0
-        ? contract.evidenceState
-        : contract.evidenceState === 'valid' || contract.evidenceState === 'stale'
-          ? 'stale'
-          : 'partial',
-      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: MultiRepositoryMcpToolContext, session: ExecutionSessionContext, reason: string): void {
+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);
 }
 
-export function bindSessionRepository(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): Record<string, unknown> {
+export function bindSessionRepository(ctx: McpExecutionContext, args: Record<string, unknown>): Record<string, unknown> {
   const session = requireSession(ctx, args);
   const repository = resolveRepositorySelection({ repoId: requireExplicitRepoId(args), checkoutId: typeof args.checkout_id === 'string' ? args.checkout_id : undefined, controllerHome: ctx.controllerHome, allowSoleRepository: false });
   const switching = session.activeRepositoryId !== undefined && (session.activeRepositoryId !== repository.repoId || session.activeCheckoutId !== repository.activeCheckoutId);
@@ -314,7 +82,86 @@ export function bindSessionRepository(ctx: MultiRepositoryMcpToolContext, args:
   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 };
 }
 
-export function prepareWork(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>): Record<string, unknown> {
+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');
+  }
+  if (existing.state !== 'prepared' && existing.state !== 'editing') {
+    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,
+    deliveryBaseCommit: adoptCandidateHead,
+    expectedHead: adoptCandidateHead,
+    validationRun: undefined,
+    validatedInputFingerprint: undefined,
+    finalization: initialStage(),
+    failureReason: undefined,
+  };
+  validateWorkHandle(ctx.controllerHome, candidate, identityFor(ctx, args), 'cheap', 'inspect');
+  return writeWorkHandle(ctx.controllerHome, 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);
   if (!session.activeRepositoryId) {
@@ -325,12 +172,16 @@ export function prepareWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
     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 };
+    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() : '';
@@ -346,8 +197,12 @@ export function prepareWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
   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,
@@ -374,25 +229,24 @@ export function prepareWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
     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') {
-        updateWorkContract({ controllerHome: ctx.controllerHome, repoId: repository.repoId }, createdWorkId, { status: 'running', worktreeRef: existingHandle.worktreePath });
+      if (existingContract.semanticState === 'open') {
+        activateWorkContract(
+          { controllerHome: ctx.controllerHome, repoId: repository.repoId },
+          createdWorkId,
+          { phase: 'implementation', summary: 'Prepared Work resumed on the existing WorkHandle.', worktreeRef: existingHandle.worktreePath },
+        );
       }
       const delegation = createGoalDelegation({
         sessionId: session.sessionId,
@@ -405,8 +259,7 @@ export function prepareWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
         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);
@@ -414,8 +267,8 @@ export function prepareWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
     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(
@@ -449,30 +302,53 @@ export function prepareWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
         ? 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() },
       };
       writeWorkHandle(ctx.controllerHome, handle);
-      updateWorkContract({ controllerHome: ctx.controllerHome, repoId: repository.repoId }, contract.workId, { status: 'running', worktreeRef: checkout.canonicalRoot });
+      activateWorkContract(
+        { controllerHome: ctx.controllerHome, repoId: repository.repoId },
+        contract.workId,
+        { 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) {
-      updateWorkContract({ controllerHome: ctx.controllerHome, repoId: repository.repoId }, contract.workId, { status: 'failed' });
+      failWorkContract(
+        { controllerHome: ctx.controllerHome, repoId: repository.repoId },
+        contract.workId,
+        { phase: 'implementation', summary: `Repository Work preparation failed: ${error instanceof Error ? error.message : String(error)}` },
+      );
       throw error;
     }
   });

package/src/runtime/control-plane/execution/work-remote-delivery.ts

@@ -1,7 +1,6 @@
 import { spawnSync } from 'child_process';
 import type { RepositoryRecord } from '../../../cli/repositories/types';
-import { getWorkContract } from '../facade/work-contract-store';
-import { isTerminalWorkContractStatus } from '../facade/types';
+import { getWorkContract, semanticWorkState } from '../../../../packages/kernel/work/api/index';
 import { executeRepositoryCommandViaProcessRuntime, waitRepositoryCommandProcess } from '../../execution/process-runtime/command-facade';
 import { executionIdentityForRepository } from './execution-identity';
 
@@ -59,7 +58,7 @@ function assertActiveWork(input: {
     !contract
     || contract.repoId !== input.repository.repoId
     || (contract.checkoutId && contract.checkoutId !== input.repository.activeCheckoutId)
-    || isTerminalWorkContractStatus(contract.status)
+    || semanticWorkState(contract) !== 'open'
     || Boolean(contract.completionReceipt)
   ) {
     throw new Error(`WORK_REMOTE_DELIVERY_ACTIVE_AUTHORITY_REQUIRED: ${input.workId}`);

package/src/runtime/control-plane/execution/work-revision-diff.ts

@@ -0,0 +1,39 @@
+import { spawnSync } from 'child_process';
+
+function gitText(repoRoot: string, args: string[]): string {
+  const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf-8' });
+  if (result.status !== 0 || result.error || typeof result.stdout !== 'string') {
+    throw new Error(`WORK_REVISION_DIFF_GIT_FAILED: git ${args.join(' ')}`);
+  }
+  return result.stdout.trim();
+}
+
+function commitRevision(repoRoot: string, revision: string | undefined, label: string): string {
+  if (!revision?.trim()) throw new Error(`WORK_REVISION_DIFF_${label}_MISSING`);
+  return gitText(repoRoot, ['rev-parse', `${revision.trim()}^{commit}`]);
+}
+
+export function changedPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
+  const result = spawnSync('git', ['diff', '--name-only', '-z', baseRevision, targetRevision], {
+    cwd: repoRoot,
+    encoding: 'utf-8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.status !== 0 || result.error || typeof result.stdout !== 'string') {
+    throw new Error('WORK_REVISION_DIFF_CHANGED_PATHS_UNAVAILABLE');
+  }
+  return [...new Set(result.stdout.split('\0').filter(Boolean))].sort();
+}
+
+export function changedPathsFromUnbornBase(repoRoot: string, targetRevision: string): string[] {
+  const targetCommit = commitRevision(repoRoot, targetRevision, 'TARGET_REVISION');
+  const result = spawnSync('git', ['ls-tree', '-r', '--name-only', '-z', targetCommit], {
+    cwd: repoRoot,
+    encoding: 'utf-8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.status !== 0 || result.error || typeof result.stdout !== 'string') {
+    throw new Error('WORK_REVISION_DIFF_UNBORN_CHANGED_PATHS_UNAVAILABLE');
+  }
+  return [...new Set(result.stdout.split('\0').filter(Boolean))].sort();
+}