@moretea-labs/forge 1.8.0 → 1.8.1

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, 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,
+  });
+  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(),
   });
-  // A managed checkout has its own source lineage and does not participate in
-  // shared-canonical target-base alignment.
-  if (placement.managedWorktree) return input.handle;
+  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' } {
   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,36 @@ 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 });
+  return { handle };
 }
+

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

@@ -1,7 +1,7 @@
 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';
@@ -227,7 +227,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 {
@@ -376,6 +376,23 @@ export function writeWorkHandle(controllerHome: string, handle: WorkHandleState)
   return { ...record.value, recordRevision: record.revision };
 }
 
+/**
+ * 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 +421,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,

package/src/runtime/control-plane/execution/work-head-settlement.ts

@@ -1,3 +1,4 @@
+import { commandExecutionScopeKey, type RepositoryCommandScopeTarget } from '../../../cli/repositories/command-scope';
 import type { RepositoryRecord } from '../../../cli/repositories/types';
 import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
 import type { ResolvedExecutionIdentity } from './execution-identity';
@@ -30,7 +31,7 @@ export interface WorkHeadSettlementResult {
  */
 export function settleWorkHandleExpectedHeadAfterRepositoryCommand(input: {
   controllerHome: string;
-  repository: RepositoryRecord;
+  repository: RepositoryCommandScopeTarget;
   executionIdentity: ResolvedExecutionIdentity;
   workId?: string;
   ok?: boolean;
@@ -42,33 +43,65 @@ export function settleWorkHandleExpectedHeadAfterRepositoryCommand(input: {
   if (input.ok !== true || input.cancelled === true || input.timedOut === true) {
     return { settled: false, reason: 'command_not_successful' };
   }
-  const handle = readWorkHandle(input.controllerHome, input.repository.repoId, workId);
-  if (!handle) return { settled: false, reason: 'work_handle_missing' };
-  if (
-    handle.repositoryId !== input.executionIdentity.repositoryId
-    || handle.checkoutId !== input.executionIdentity.checkoutId
-    || handle.workId !== input.executionIdentity.workId
-    || handle.branch !== input.executionIdentity.branch
-    || (input.executionIdentity.expectedHead !== undefined && handle.expectedHead !== input.executionIdentity.expectedHead)
-  ) return { settled: false, reason: 'identity_mismatch' };
-  if (handle.state === 'merged' || handle.state === 'cleaned' || handle.state === 'failed_terminal_cleanup') {
+  const originalHandle = readWorkHandle(input.controllerHome, commandExecutionScopeKey(input.repository), workId);
+  if (!originalHandle) return { settled: false, reason: 'work_handle_missing' };
+  const sameStaticExecutionIdentity = (handle: typeof originalHandle): boolean => (
+    handle.repositoryId === input.executionIdentity.repositoryId
+    && handle.checkoutId === input.executionIdentity.checkoutId
+    && handle.workId === input.executionIdentity.workId
+    && handle.branch === input.executionIdentity.branch
+  );
+  if (!sameStaticExecutionIdentity(originalHandle)) return { settled: false, reason: 'identity_mismatch' };
+  if (originalHandle.state === 'merged' || originalHandle.state === 'cleaned' || originalHandle.state === 'failed_terminal_cleanup') {
     return { settled: false, reason: 'terminal_handle' };
   }
-  const status = repositoryGitStatus(input.repository);
-  if (!status.branch || status.branch !== handle.branch) {
-    return { settled: false, reason: 'branch_changed', previousHead: handle.expectedHead, currentHead: status.head ?? undefined };
+  // A Work head settlement only runs for a Work-bound (repository) command, so
+  // the scope target is a registered repository record at this point.
+  const status = repositoryGitStatus(input.repository as RepositoryRecord);
+  if (!status.branch || status.branch !== originalHandle.branch) {
+    return { settled: false, reason: 'branch_changed', previousHead: originalHandle.expectedHead, currentHead: status.head ?? undefined };
   }
   const currentHead = status.head?.trim();
-  if (!currentHead) return { settled: false, reason: 'head_unavailable', previousHead: handle.expectedHead };
-  if (currentHead === handle.expectedHead) {
-    return { settled: false, reason: 'head_unchanged', previousHead: handle.expectedHead, currentHead };
+  if (!currentHead) return { settled: false, reason: 'head_unavailable', previousHead: originalHandle.expectedHead };
+  const originalAuthorityHead = input.executionIdentity.expectedHead;
+  if (originalHandle.expectedHead === currentHead) {
+    if (originalAuthorityHead !== undefined && originalAuthorityHead !== currentHead) {
+      return { settled: true, reason: 'settled', previousHead: originalAuthorityHead, currentHead };
+    }
+    return { settled: false, reason: 'head_unchanged', previousHead: originalHandle.expectedHead, currentHead };
+  }
+  if (originalAuthorityHead !== undefined && originalHandle.expectedHead !== originalAuthorityHead) {
+    return { settled: false, reason: 'identity_mismatch', previousHead: originalHandle.expectedHead, currentHead };
+  }
+  try {
+    transitionWorkHandle(input.controllerHome, originalHandle, originalHandle.state, { expectedHead: currentHead });
+    return { settled: true, reason: 'settled', previousHead: originalHandle.expectedHead, currentHead };
+  } catch (error) {
+    if (!(error instanceof Error) || !error.message.includes('CONTROL_PLANE_REVISION_CONFLICT')) throw error;
+  }
+
+  // One concurrent lifecycle write is allowed to win the first CAS. Re-read the
+  // exact Work authority and converge only when identity/branch are unchanged.
+  const refreshedHandle = readWorkHandle(input.controllerHome, commandExecutionScopeKey(input.repository), workId);
+  if (!refreshedHandle) return { settled: false, reason: 'work_handle_missing', previousHead: originalHandle.expectedHead, currentHead };
+  if (!sameStaticExecutionIdentity(refreshedHandle)) {
+    return { settled: false, reason: 'identity_mismatch', previousHead: refreshedHandle.expectedHead, currentHead };
+  }
+  if (refreshedHandle.expectedHead !== currentHead && originalAuthorityHead !== undefined && refreshedHandle.expectedHead !== originalAuthorityHead) {
+    return { settled: false, reason: 'identity_mismatch', previousHead: refreshedHandle.expectedHead, currentHead };
+  }
+  if (refreshedHandle.state === 'merged' || refreshedHandle.state === 'cleaned' || refreshedHandle.state === 'failed_terminal_cleanup') {
+    return { settled: false, reason: 'terminal_handle', previousHead: refreshedHandle.expectedHead, currentHead };
+  }
+  if (refreshedHandle.expectedHead === currentHead) {
+    return { settled: true, reason: 'settled', previousHead: originalHandle.expectedHead, currentHead };
   }
   try {
-    transitionWorkHandle(input.controllerHome, handle, handle.state, { expectedHead: currentHead });
-    return { settled: true, reason: 'settled', previousHead: handle.expectedHead, currentHead };
+    transitionWorkHandle(input.controllerHome, refreshedHandle, refreshedHandle.state, { expectedHead: currentHead });
+    return { settled: true, reason: 'settled', previousHead: refreshedHandle.expectedHead, currentHead };
   } catch (error) {
     if (error instanceof Error && error.message.includes('CONTROL_PLANE_REVISION_CONFLICT')) {
-      return { settled: false, reason: 'concurrent_lifecycle_write', previousHead: handle.expectedHead, currentHead };
+      return { settled: false, reason: 'concurrent_lifecycle_write', previousHead: refreshedHandle.expectedHead, currentHead };
     }
     throw error;
   }