@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/control-plane/execution/work-handle-authority.ts

@@ -2,12 +2,10 @@ import { resolve } from 'path';
 import type { RepositoryRecord } from '../../../cli/repositories/types';
 import { getRepository, resolveRepositorySelection, selectRepositoryCheckout } from '../../../cli/repositories/registry';
 import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
-import { appendWorkEvidence, getWorkContract, promoteWorkToRepositoryChange, updateWorkContract } from '../../../../packages/kernel/work/api/index';
-import { controllerSessionPrincipalId, getControllerSession } from '../../../../packages/kernel/controller/api/index';
-import { isTerminalWorkContractStatus } from '../facade/types';
+import { appendWorkEvidence, getWorkContract, promoteWorkToRepositoryChange, recordWorkEvidenceState, semanticWorkState } from '../../../../packages/kernel/work/api/index';
 import { currentPermissionSnapshotVersion } from './validation';
 import { listWorkHandles, readWorkHandle, transitionWorkHandle, writeWorkHandle, type WorkHandleState } from './work-handle-store';
-import { inspectDirectCanonicalPreMutationReconciliation } from './direct-canonical-work-reconciliation';
+import { gitIsAncestor } from './work-execution-support';
 
 export interface RepositoryWorkHandleControllerIdentity {
   sessionId: string;
@@ -46,10 +44,11 @@ export function assertCanonicalRepositoryMutationWorkHandleAvailable(input: {
         handle.workId,
       );
       // A stale physical handle cannot outlive canonical Work lifecycle authority.
-      // Missing WorkContract evidence remains fail-closed for legacy/unreconciled
-      // handles; only an explicit terminal status or completion receipt releases
-      // durable canonical writer ownership.
-      return !contract || (!isTerminalWorkContractStatus(contract.status) && !contract.completionReceipt);
+      // Delivery receipts are mechanical evidence only; an explicitly open Work
+      // continues to own its concrete mutation surface until semantic completion
+      // or cancellation releases that authority.
+      if (!contract) return false;
+      return semanticWorkState(contract) === 'open';
     })
     .sort((left, right) => left.workId.localeCompare(right.workId));
   if (owners.length === 0) return;
@@ -86,8 +85,9 @@ function resolveRepositoryWorkHandlePlacement(input: {
 }
 
 /**
- * Canonical compatibility repair for a goal-workloop Work whose durable
- * WorkContract exists but whose WorkHandle has not yet been materialized.
+ * Materialize concrete repository-mutation ownership for an optional semantic
+ * Work attribution. Thin Work does not classify execution kind; checkout/CAS
+ * placement and the WorkHandle resource fence own mutation safety.
  * Transport layers provide only the authenticated Controller identity.
  */
 export function ensureRepositoryWorkHandle(input: {
@@ -95,28 +95,35 @@ export function ensureRepositoryWorkHandle(input: {
   repository: RepositoryRecord;
   workId: string;
   identity: RepositoryWorkHandleControllerIdentity;
+  checkoutId?: string;
   allowEffectWork?: boolean;
 }): WorkHandleState | undefined {
   const existing = readWorkHandle(input.controllerHome, input.repository.repoId, input.workId);
-  if (existing) return existing;
+  if (existing) {
+    if (input.checkoutId?.trim() && existing.checkoutId !== input.checkoutId.trim()) {
+      throw new Error(`WORK_HANDLE_PLACEMENT_CHECKOUT_MISMATCH: ${input.workId}`);
+    }
+    return existing;
+  }
   const contract = getWorkContract(
     { controllerHome: input.controllerHome, repoId: input.repository.repoId },
     input.workId,
   );
-  const supportedKind = contract?.workKind === 'repository_change'
-    || contract?.workKind === 'completed_no_change'
-    || (input.allowEffectWork === true && (contract?.workKind === 'local_effect' || contract?.workKind === 'remote_effect'));
-  if (!contract || !supportedKind || contract.mode !== 'goal_workloop' || !contract.checkoutId) {
-    return undefined;
-  }
+  // allowEffectWork is retained only for source compatibility while old
+  // repository callers cut over. workKind is no longer an execution authority.
+  void input.allowEffectWork;
+  const checkoutId = input.checkoutId?.trim() || contract?.checkoutId?.trim();
+  if (!contract || !checkoutId) return undefined;
   // Callers may already be scoped to the Work checkout. Re-read the unselected
   // registry record so WorkHandle source/delivery authority never mistakes an
-  // isolated execution worktree for the canonical source checkout.
+  // isolated execution worktree for the canonical source checkout. Legacy
+  // WorkContract checkout/worktree fields remain migration-era placement hints;
+  // new Thin Work receives its concrete checkout from the repository target.
   const placement = resolveRepositoryWorkHandlePlacement({
     controllerHome: input.controllerHome,
     repositoryId: input.repository.repoId,
-    checkoutId: contract.checkoutId,
-    worktreeRef: contract.worktreeRef,
+    checkoutId,
+    worktreeRef: contract.checkoutId === checkoutId ? contract.worktreeRef : undefined,
   });
   const { registeredRepository, checkout, status, branch, managedWorktree } = placement;
   const sourceCheckoutId = registeredRepository.activeCheckoutId;
@@ -130,7 +137,7 @@ export function ensureRepositoryWorkHandle(input: {
     sessionId: input.identity.sessionId,
     principalId: input.identity.principalId,
     repositoryId: input.repository.repoId,
-    checkoutId: contract.checkoutId,
+    checkoutId,
     worktreePath: checkout.canonicalRoot,
     branch,
     sourceCheckoutId,
@@ -164,7 +171,7 @@ export function reconcileRepositoryWorkHandlePlacement(input: {
   const existing = readWorkHandle(input.controllerHome, input.repositoryId, input.workId);
   if (!existing || existing.managedWorktree) return existing;
   const contract = getWorkContract({ controllerHome: input.controllerHome, repoId: input.repositoryId }, input.workId);
-  if (!contract || contract.workKind !== 'repository_change' || contract.mode !== 'goal_workloop' || !contract.checkoutId) return existing;
+  if (!contract || !contract.checkoutId) return existing;
   if (contract.checkoutId !== existing.checkoutId) throw new Error(`WORK_HANDLE_PLACEMENT_CHECKOUT_MISMATCH: ${input.workId}`);
   const placement = resolveRepositoryWorkHandlePlacement({ controllerHome: input.controllerHome, repositoryId: input.repositoryId, checkoutId: contract.checkoutId, worktreeRef: contract.worktreeRef });
   if (!placement.managedWorktree) return existing;
@@ -174,58 +181,160 @@ export function reconcileRepositoryWorkHandlePlacement(input: {
   return writeWorkHandle(input.controllerHome, { ...existing, sourceCheckoutId: placement.registeredRepository.activeCheckoutId, managedWorktree: true });
 }
 
-function alignRepositoryMutationBase(input: {
+export function assertManagedRepositoryMutationAuthority(input: {
+  repository: RepositoryRecord;
+  handle: WorkHandleState;
+}): void {
+  if (!input.handle.managedWorktree) return;
+  if (input.handle.state !== 'prepared' && input.handle.state !== 'editing') {
+    throw new Error(`WORK_REPOSITORY_MUTATION_LIFECYCLE_INVALID: ${input.handle.workId}:${input.handle.state}`);
+  }
+  if (input.repository.activeCheckoutId !== input.handle.checkoutId) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_CHECKOUT_MISMATCH: expected ${input.handle.checkoutId}, found ${input.repository.activeCheckoutId}`);
+  }
+  const status = repositoryGitStatus(input.repository);
+  if (status.branch !== input.handle.branch) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_BRANCH_CHANGED: expected ${input.handle.branch}, found ${status.branch ?? 'detached'}`);
+  }
+  if (!input.handle.expectedHead || status.head !== input.handle.expectedHead) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_HEAD_CHANGED: expected ${input.handle.expectedHead ?? 'missing'}, found ${status.head ?? 'missing'}`);
+  }
+}
+
+export function rearmFailedPreservedWorkHandle(input: {
   controllerHome: string;
   repository: RepositoryRecord;
   workId: string;
   contract: NonNullable<ReturnType<typeof getWorkContract>>;
   handle: WorkHandleState;
-  freshlyMaterialized: boolean;
+  principalId: string;
+  sessionId: string;
 }): WorkHandleState {
-  if (input.handle.managedWorktree || input.handle.state !== 'prepared') return input.handle;
-  if (input.contract.phase !== 'implementation') {
-    throw new Error(`WORK_DIRECT_PRE_MUTATION_PHASE_INVALID: ${input.workId}:${input.contract.phase}`);
+  const { handle } = input;
+  if (!handle.managedWorktree || handle.state !== 'failed') return handle;
+  const validationRecoverable = handle.finalization.validation === 'pending'
+    || handle.finalization.validation === 'failed';
+  if (!validationRecoverable
+    || handle.finalization.commit !== 'pending'
+    || handle.finalization.merge !== 'pending'
+    || handle.finalization.branchCleanup !== 'pending'
+    || handle.finalization.worktreeCleanup !== 'pending'
+    || handle.cleanupReceipt
+    || input.contract.completionReceipt
+    || input.contract.completionOutcome) {
+    return handle;
+  }
+  if (handle.principalId !== input.principalId) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_PRINCIPAL_MISMATCH: ${input.workId}`);
   }
-  if (!input.contract.checkoutId) throw new Error(`WORK_REPOSITORY_MUTATION_CHECKOUT_REQUIRED: ${input.workId}`);
-
   const placement = resolveRepositoryWorkHandlePlacement({
     controllerHome: input.controllerHome,
     repositoryId: input.repository.repoId,
-    checkoutId: input.contract.checkoutId,
-    worktreeRef: input.contract.worktreeRef,
+    checkoutId: handle.checkoutId,
+    worktreeRef: handle.worktreePath,
   });
-  // A managed checkout has its own source lineage and does not participate in
-  // shared-canonical target-base alignment.
-  if (placement.managedWorktree) return input.handle;
+  if (!placement.managedWorktree || placement.registeredCheckout.lifecycle !== 'active') {
+    throw new Error(`WORK_REPOSITORY_MUTATION_FAILED_CHECKOUT_NOT_ACTIVE: ${input.workId}`);
+  }
+  if (resolve(placement.checkout.canonicalRoot) !== resolve(handle.worktreePath)
+    || placement.branch !== handle.branch
+    || (handle.expectedHead && placement.status.head !== handle.expectedHead)) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_FAILED_CHECKOUT_OWNERSHIP_MISMATCH: ${input.workId}`);
+  }
+  if (input.contract.evidenceState === 'valid') {
+    recordWorkEvidenceState(
+      { controllerHome: input.controllerHome, repoId: input.repository.repoId },
+      input.workId,
+      'stale',
+    );
+  }
+  const next = writeWorkHandle(input.controllerHome, {
+    ...handle,
+    principalId: input.principalId,
+    sessionId: input.sessionId,
+    state: 'editing',
+    validationRun: undefined,
+    validatedInputFingerprint: undefined,
+    failureReason: undefined,
+    finalization: { ...handle.finalization, validation: 'pending' },
+    updatedAt: new Date().toISOString(),
+  });
+  appendWorkEvidence(
+    { controllerHome: input.controllerHome, repoId: input.repository.repoId },
+    input.workId,
+    {
+      title: 'failed retained Work re-armed for same-Work mutation',
+      summary: `Re-armed preserved managed checkout ${handle.checkoutId} after proving the Work remained open, commit/merge/cleanup had not started, and exact checkout/path/branch/HEAD ownership still matched.`,
+      detailLevel: 'summary',
+    },
+  );
+  return next;
+}
+
+function rearmRetainedMergedWorkForMutation(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  contract: NonNullable<ReturnType<typeof getWorkContract>>;
+  handle: WorkHandleState;
+}): WorkHandleState {
+  const { handle } = input;
+  if (!handle.managedWorktree || handle.state !== 'merged') return handle;
+  const retained = handle.terminalResourceDisposition;
+  if (retained?.mode !== 'retained_by_request' || retained.retainWorktree !== true || retained.retainBranch !== true) return handle;
+  if (semanticWorkState(input.contract) !== 'open') throw new Error(`WORK_RETAINED_REARM_SEMANTIC_STATE_INVALID: ${input.workId}`);
+  if (!handle.expectedHead?.trim()) throw new Error(`WORK_RETAINED_REARM_EXPECTED_HEAD_REQUIRED: ${input.workId}`);
 
-  const targetBranch = input.handle.deliveryTargetBranch ?? placement.branch;
-  const inspection = inspectDirectCanonicalPreMutationReconciliation({
-    handle: input.handle,
-    root: placement.checkout.canonicalRoot,
-    targetBranch,
-    status: placement.status,
-    freshlyMaterialized: input.freshlyMaterialized,
+  const placement = resolveRepositoryWorkHandlePlacement({
+    controllerHome: input.controllerHome,
+    repositoryId: input.repository.repoId,
+    checkoutId: handle.checkoutId,
+    worktreeRef: input.contract.worktreeRef,
   });
-  if (inspection.reason === 'no_target_advance') return input.handle;
-  if (!inspection.alignable || !inspection.targetHead) {
-    throw new Error(`WORK_DIRECT_PRE_MUTATION_RECONCILIATION_BLOCKED: ${inspection.reason}`);
+  if (!placement.managedWorktree || placement.registeredCheckout.lifecycle !== 'active') {
+    throw new Error(`WORK_RETAINED_REARM_CHECKOUT_NOT_ACTIVE: ${input.workId}`);
+  }
+  if (resolve(placement.checkout.canonicalRoot) !== resolve(handle.worktreePath) || placement.branch !== handle.branch) {
+    throw new Error(`WORK_RETAINED_REARM_OWNERSHIP_MISMATCH: ${input.workId}`);
+  }
+  if (!placement.status.clean) throw new Error(`WORK_RETAINED_REARM_WORKTREE_DIRTY: ${input.workId}`);
+  if (placement.status.head !== handle.expectedHead) {
+    throw new Error(`WORK_RETAINED_REARM_HEAD_CHANGED: expected ${handle.expectedHead}, found ${placement.status.head ?? 'missing'}`);
+  }
+  const sourceCheckout = selectRepositoryCheckout(
+    placement.registeredRepository,
+    handle.sourceCheckoutId ?? placement.registeredRepository.activeCheckoutId,
+    { allowArchived: true },
+  );
+  const targetBranch = handle.deliveryTargetBranch?.trim();
+  if (!targetBranch || !gitIsAncestor(sourceCheckout.canonicalRoot, handle.expectedHead, targetBranch)) {
+    throw new Error(`WORK_RETAINED_REARM_TARGET_CONTAINMENT_REQUIRED: ${input.workId}`);
   }
 
-  const aligned = transitionWorkHandle(input.controllerHome, input.handle, input.handle.state, {
-    deliveryBaseCommit: inspection.targetHead,
-    expectedHead: inspection.targetHead,
+  const evidenceState = input.contract.evidenceState === 'valid' || input.contract.evidenceState === 'stale' ? 'stale' : 'partial';
+  if (input.contract.evidenceState !== evidenceState) recordWorkEvidenceState(
+    { controllerHome: input.controllerHome, repoId: input.repository.repoId }, input.workId, evidenceState,
+  );
+  const next = writeWorkHandle(input.controllerHome, {
+    ...handle,
+    state: 'editing',
+    terminalResourceDisposition: undefined,
+    validatedInputFingerprint: undefined,
+    validationRun: undefined,
+    cleanupReceipt: undefined,
     failureReason: undefined,
+    finalization: { validation: 'pending', commit: 'pending', merge: 'pending', branchCleanup: 'pending', worktreeCleanup: 'pending' },
   });
   appendWorkEvidence(
     { controllerHome: input.controllerHome, repoId: input.repository.repoId },
     input.workId,
     {
-      title: 'direct canonical pre-mutation target base aligned',
-      summary: `Before the first Work-owned repository mutation, canonical target ${targetBranch} advanced linearly ${inspection.previousDeliveryBase} -> ${inspection.targetHead} while the shared checkout remained clean. Forge advanced only deliveryBaseCommit/expectedHead; the Work remains prepared until the mutation surface proves that repository mutation actually started.`,
+      title: 'retained merged Work re-armed for same-Work mutation',
+      summary: `Re-armed retained merged Work at ${handle.expectedHead} only after proving semantic Work remains open, retained branch/worktree ownership, clean exact checkout identity, and target containment on ${targetBranch}. Prior validation/delivery authority is stale; no new Work was created.`,
       detailLevel: 'summary',
     },
   );
-  return aligned;
+  return next;
 }
 
 export function markRepositoryMutationStarted(input: {
@@ -236,9 +345,7 @@ export function markRepositoryMutationStarted(input: {
 }): WorkHandleState | undefined {
   const store = { controllerHome: input.controllerHome, repoId: input.repository.repoId };
   const contract = getWorkContract(store, input.workId);
-  if (contract?.workKind === 'local_effect' || contract?.workKind === 'remote_effect') {
-    promoteWorkToRepositoryChange(store, input.workId);
-  }
+  if (!contract) return undefined;
   const handle = readWorkHandle(input.controllerHome, input.repository.repoId, input.workId);
   if (!handle || handle.managedWorktree || handle.state !== 'prepared') return handle;
   const boundWorkId = handle.workContractId ?? handle.workId;
@@ -253,40 +360,30 @@ export function markRepositoryMutationStarted(input: {
 }
 
 /**
- * Upgrades an effect-only Work before the first governed repository mutation
- * and materializes the existing repository delivery authority. The durable
- * ControllerSession is the ownership source; the MCP transport session is not
- * allowed to become a second mutation authority.
+ * Materializes repository delivery authority for an optional semantic Work.
+ * Work is not a controller mutex or an execution-kind gate: authenticated caller
+ * identity is provenance while checkout/head/CAS/resource fences own mutation safety.
  */
 export function ensureRepositoryMutationWorkHandle(input: {
   controllerHome: string;
   repository: RepositoryRecord;
   workId: string;
   principalId: string;
+  sessionId?: string;
   deferEffectPromotion?: boolean;
-}): { handle: WorkHandleState; promotedFrom?: 'local_effect' | 'remote_effect' } {
+}): { handle: WorkHandleState; promotedFrom?: 'investigation' | 'local_effect' | 'remote_effect' } {
   const store = { controllerHome: input.controllerHome, repoId: input.repository.repoId };
-  let contract = getWorkContract(store, input.workId);
+  const contract = getWorkContract(store, input.workId);
   if (!contract) throw new Error(`WORK_NOT_FOUND: ${input.workId}`);
-  if (isTerminalWorkContractStatus(contract.status) || contract.completionReceipt) {
+  if (semanticWorkState(contract) !== 'open') {
     throw new Error(`WORK_REPOSITORY_MUTATION_TERMINAL: ${input.workId}`);
   }
   const principalId = input.principalId.trim();
-  if (!principalId) throw new Error(`WORK_CONTROLLER_AUTHENTICATED_PRINCIPAL_REQUIRED: ${input.workId}`);
-  const owner = getControllerSession(store, input.workId);
-  if (!owner) throw new Error(`WORK_CONTROLLER_CLAIM_REQUIRED: ${input.workId}`);
-  if (controllerSessionPrincipalId(owner) !== principalId) {
-    throw new Error(`WORK_CONTROLLER_OWNERSHIP_MISMATCH: ${input.workId}`);
-  }
+  if (!principalId) throw new Error(`WORK_AUTHENTICATED_PRINCIPAL_REQUIRED: ${input.workId}`);
+  const provenanceSessionId = input.sessionId?.trim() || `sessionless:${principalId}`;
 
-  let mutationCheckoutId = contract.checkoutId;
-  if (!mutationCheckoutId) {
-    if (contract.worktreeRef?.trim()) {
-      throw new Error(`WORK_REPOSITORY_MUTATION_CHECKOUT_REQUIRED: ${input.workId}`);
-    }
-    mutationCheckoutId = input.repository.activeCheckoutId;
-    contract = updateWorkContract(store, input.workId, { checkoutId: mutationCheckoutId });
-  }
+  const mutationCheckoutId = contract.checkoutId?.trim() || input.repository.activeCheckoutId;
+  if (!mutationCheckoutId) throw new Error(`WORK_REPOSITORY_MUTATION_CHECKOUT_REQUIRED: ${input.workId}`);
   assertCanonicalRepositoryMutationWorkHandleAvailable({
     controllerHome: input.controllerHome,
     repositoryId: input.repository.repoId,
@@ -294,54 +391,44 @@ export function ensureRepositoryMutationWorkHandle(input: {
     workId: input.workId,
   });
 
-  let promotedFrom: 'local_effect' | 'remote_effect' | undefined;
-  if (contract.workKind === 'local_effect' || contract.workKind === 'remote_effect') {
-    promotedFrom = contract.workKind;
-    if (input.deferEffectPromotion !== true) {
-      contract = promoteWorkToRepositoryChange(store, input.workId);
-    }
-  }
-  if (contract.workKind !== 'repository_change' && input.deferEffectPromotion !== true) {
-    throw new Error(`WORK_REPOSITORY_MUTATION_KIND_INVALID: ${input.workId}:${contract.workKind}`);
-  }
+  // deferEffectPromotion is a compatibility input from the retired Work-kind
+  // lifecycle. Repository mutation is now admitted by the concrete target fence.
+  void input.deferEffectPromotion;
 
-  const existingHandle = readWorkHandle(input.controllerHome, input.repository.repoId, input.workId);
   let handle = ensureRepositoryWorkHandle({
     controllerHome: input.controllerHome,
     repository: input.repository,
     workId: input.workId,
-    identity: { sessionId: owner.sessionId, principalId },
-    allowEffectWork: input.deferEffectPromotion === true,
+    identity: { sessionId: provenanceSessionId, principalId },
+    checkoutId: mutationCheckoutId,
+    allowEffectWork: true,
   });
   if (!handle) throw new Error(`WORK_REPOSITORY_MUTATION_HANDLE_REQUIRED: ${input.workId}`);
-  handle = alignRepositoryMutationBase({
+  handle = rearmFailedPreservedWorkHandle({
     controllerHome: input.controllerHome,
     repository: input.repository,
     workId: input.workId,
     contract,
     handle,
-    freshlyMaterialized: !existingHandle,
+    principalId,
+    sessionId: provenanceSessionId,
   });
-  return { handle, ...(promotedFrom ? { promotedFrom } : {}) };
-}
-
-/**
- * Rebinds the durable WorkHandle to the Controller session that has already
- * been admitted by the ControllerSession authority. The compare-and-swap
- * revision on the read handle preserves fail-closed concurrent ownership.
- */
-export function rebindRepositoryWorkHandleControllerIdentity(input: {
-  controllerHome: string;
-  repositoryId: string;
-  workId: string;
-  identity: RepositoryWorkHandleControllerIdentity;
-}): WorkHandleState | undefined {
-  const existing = readWorkHandle(input.controllerHome, input.repositoryId, input.workId);
-  if (!existing) return undefined;
-  if (existing.principalId === input.identity.principalId && existing.sessionId === input.identity.sessionId) return existing;
-  return writeWorkHandle(input.controllerHome, {
-    ...existing,
-    principalId: input.identity.principalId,
-    sessionId: input.identity.sessionId,
+  handle = rearmRetainedMergedWorkForMutation({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.workId,
+    contract,
+    handle,
   });
+  assertManagedRepositoryMutationAuthority({ repository: input.repository, handle });
+  // This is the first point at which concrete repository mutation has passed
+  // the exact WorkHandle checkout, ownership, and managed-worktree fences.
+  // WorkContract remains the sole writer for its semantic classification.
+  const promotedFrom = contract.workKind === 'investigation'
+    || contract.workKind === 'local_effect'
+    || contract.workKind === 'remote_effect'
+    ? contract.workKind
+    : undefined;
+  promoteWorkToRepositoryChange(store, input.workId);
+  return promotedFrom ? { handle, promotedFrom } : { handle };
 }

package/src/runtime/control-plane/execution/work-handle-store.ts

@@ -1,10 +1,11 @@
 import { randomUUID } from 'crypto';
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { scopedOperationRoot } from '../../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent } from '../../shared/json-files';
 import type { ProcessCheckExecutionIdentity } from '../../evidence/process-check-execution';
-import { listControlPlaneRecords, mutateControlPlaneRecord, readOrImportControlPlaneRecord, writeControlPlaneRecord } from '../persistence/sqlite-store';
+import { listControlPlaneRecords, listControlPlaneRecordsWithinTransaction, mutateControlPlaneRecord, readControlPlaneRecordWithinTransaction, readOrImportControlPlaneRecord, writeControlPlaneRecord, writeControlPlaneRecordWithinTransaction } from '../persistence/sqlite-store';
+import { updateWorkContractPlacementAtomically } from '../../../../packages/kernel/work/api/index';
 
 export const WORK_HANDLE_STATES = [
   'prepared',
@@ -227,7 +228,7 @@ export function resolveWorkDeliveryTargetBranch(
 }
 
 function workHandlePath(controllerHome: string, handle: Pick<WorkHandleState, 'repositoryId' | 'workId'>): string {
-  return join(repositoryControllerRoot(controllerHome, handle.repositoryId), 'work-handles', `${sanitizeFileComponent(handle.workId)}.json`);
+  return join(scopedOperationRoot(controllerHome, handle.repositoryId), 'work-handles', `${sanitizeFileComponent(handle.workId)}.json`);
 }
 
 function now(): string {
@@ -304,6 +305,9 @@ function updateValidationIndexMembership(
   validating: boolean,
 ): void {
   const existing = readValidationIndex(controllerHome, repositoryId);
+  // The index describes pending validation membership, not WorkHandle activity.
+  // Other lifecycle writes do not change its membership or need an index CAS.
+  if (existing && existing.workIds.includes(workId) === validating) return;
   if (!existing) {
     // The WorkHandle write is already durable. Rebuild once from authoritative
     // handles so legacy repositories establish an exact index without a scan
@@ -376,6 +380,71 @@ export function writeWorkHandle(controllerHome: string, handle: WorkHandleState)
   return { ...record.value, recordRevision: record.revision };
 }
 
+/**
+ * Atomically rebind the one existing execution handle and its Kernel Work
+ * placement. The application service already proved exact Git ancestry and
+ * clean exclusive target; this store owns only the two-record CAS mutation.
+ */
+export function relocateWorkHandlePlacementAtomically(
+  controllerHome: string,
+  prior: WorkHandleState,
+  target: { checkoutId: string; root: string; branch: string; head: string },
+): WorkHandleState {
+  const moved: WorkHandleState = {
+    ...prior, checkoutId: target.checkoutId, worktreePath: target.root, branch: target.branch,
+    expectedHead: target.head, managedWorktree: true,
+    validationRun: undefined, validatedInputFingerprint: undefined,
+    finalization: { validation: 'pending', commit: 'pending', merge: 'pending', branchCleanup: 'pending', worktreeCleanup: 'pending' },
+  };
+  updateWorkContractPlacementAtomically({ controllerHome, repoId: prior.repositoryId }, prior.workId, {
+    checkoutId: target.checkoutId,
+    worktreeRef: target.root,
+    executionPlacement: { schemaVersion: 1, repositoryId: prior.repositoryId, checkoutId: target.checkoutId },
+    worktreePolicy: { required: true, reason: 'Explicit identity-preserving managed checkout relocation', ref: target.root },
+  }, (database, updatedContract) => {
+    if (updatedContract.checkoutId !== moved.checkoutId) throw new Error('WORK_RELOCATION_TRANSACTION_CONTRACT_MISMATCH');
+    const row = readControlPlaneRecordWithinTransaction<WorkHandleState>(
+      database, 'execution_work_handle', prior.repositoryId, prior.workId,
+    );
+    if (!row || row.revision !== prior.recordRevision || row.value.checkoutId !== prior.checkoutId
+        || row.value.expectedHead !== prior.expectedHead) {
+      throw new Error('WORK_RELOCATION_HANDLE_CAS_CONFLICT');
+    }
+    const competing = listControlPlaneRecordsWithinTransaction<WorkHandleState>(database, {
+      namespace: 'execution_work_handle', scope: prior.repositoryId, limit: 5000,
+    }).some((entry) => entry.value.workId !== prior.workId && entry.value.checkoutId === target.checkoutId
+      && entry.value.state !== 'cleaned');
+    if (competing) throw new Error('WORK_RELOCATION_TARGET_OWNED');
+    const { recordRevision: _revision, ...persisted } = moved;
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: 'execution_work_handle', scope: prior.repositoryId, key: prior.workId,
+      schemaVersion: 1, expectedRevision: row.revision,
+      value: { ...persisted, updatedAt: new Date().toISOString() },
+      action: 'work_handle_checkout_relocated',
+    });
+  });
+  const refreshed = readWorkHandle(controllerHome, prior.repositoryId, prior.workId);
+  if (!refreshed || refreshed.checkoutId !== target.checkoutId) throw new Error('WORK_RELOCATION_COMMIT_NOT_VERIFIED');
+  return refreshed;
+}
+
+/**
+ * Refresh legacy controller identity fields as provenance only. Repository
+ * mutation authority remains WorkHandle CAS plus concrete checkout/resource fences.
+ */
+export function rebindWorkHandleControllerIdentity(
+  controllerHome: string,
+  handle: WorkHandleState,
+  identity: { principalId: string; sessionId: string },
+): WorkHandleState {
+  if (handle.principalId === identity.principalId && handle.sessionId === identity.sessionId) return handle;
+  return writeWorkHandle(controllerHome, {
+    ...handle,
+    principalId: identity.principalId,
+    sessionId: identity.sessionId,
+  });
+}
+
 const TRANSITIONS: Record<WorkHandleStateName, readonly WorkHandleStateName[]> = {
   prepared: ['editing', 'validating', 'committed', 'failed', 'failed_terminal_cleanup'],
   editing: ['validating', 'committed', 'merged', 'failed', 'failed_terminal_cleanup'],
@@ -404,47 +473,6 @@ export function transitionWorkHandle(
   });
 }
 
-export interface WorkHandleSuccessorAdoption {
-  candidateHead: string;
-  targetHead: string;
-}
-
-/**
- * Explicit WorkHandle authority transition for a conflict-repaired managed
- * candidate. Git lineage/scope/cleanliness must be proven by the finalizer
- * before this transition is called. Adopting a rewritten candidate never
- * transfers validation implicitly: the new source identity must obtain exact
- * verification/review authority before delivery can resume.
- */
-export function adoptWorkHandleSuccessorCandidate(
-  controllerHome: string,
-  handle: WorkHandleState,
-  adoption: WorkHandleSuccessorAdoption,
-): WorkHandleState {
-  const candidateHead = adoption.candidateHead.trim();
-  const targetHead = adoption.targetHead.trim();
-  if (!handle.managedWorktree) throw new Error('WORK_SUCCESSOR_ADOPTION_MANAGED_CHECKOUT_REQUIRED');
-  if (!candidateHead || !targetHead) throw new Error('WORK_SUCCESSOR_ADOPTION_REVISION_REQUIRED');
-  if (candidateHead === handle.expectedHead) throw new Error('WORK_SUCCESSOR_ADOPTION_NO_CHANGE');
-  return transitionWorkHandle(controllerHome, handle, 'validating', {
-    deliveryBaseCommit: targetHead,
-    expectedHead: candidateHead,
-    failureReason: undefined,
-    finalization: {
-      ...handle.finalization,
-      validation: 'pending',
-      commit: 'done',
-      merge: 'pending',
-      branchCleanup: 'pending',
-      worktreeCleanup: 'pending',
-      failureCode: undefined, lastError: undefined,
-    },
-    validationRun: undefined,
-    validatedInputFingerprint: undefined,
-    cleanupReceipt: undefined,
-  });
-}
-
 export function markWorkHandleFailed(controllerHome: string, handle: WorkHandleState, reason: string): WorkHandleState {
   return writeWorkHandle(controllerHome, {
     ...handle,