@moretea-labs/forge 1.7.1 → 1.8.0

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

@@ -1,16 +1,90 @@
 import { resolve } from 'path';
 import type { RepositoryRecord } from '../../../cli/repositories/types';
-import { resolveRepositorySelection, selectRepositoryCheckout } from '../../../cli/repositories/registry';
+import { getRepository, resolveRepositorySelection, selectRepositoryCheckout } from '../../../cli/repositories/registry';
 import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
-import { getWorkContract } from '../facade/work-contract-store';
+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 { currentPermissionSnapshotVersion } from './validation';
-import { readWorkHandle, writeWorkHandle, type WorkHandleState } from './work-handle-store';
+import { listWorkHandles, readWorkHandle, transitionWorkHandle, writeWorkHandle, type WorkHandleState } from './work-handle-store';
+import { inspectDirectCanonicalPreMutationReconciliation } from './direct-canonical-work-reconciliation';
 
 export interface RepositoryWorkHandleControllerIdentity {
   sessionId: string;
   principalId: string;
 }
 
+const DURABLE_CANONICAL_MUTATION_OWNER_STATES = new Set<WorkHandleState['state']>([
+  'editing',
+  'validating',
+  'failed_terminal_cleanup',
+  'failed',
+]);
+
+/**
+ * Fences repository mutations across Process/Lease lifetimes using the existing
+ * durable WorkHandle authority. Process leases prevent overlapping execution;
+ * this check prevents a later mutation call from taking over a canonical
+ * checkout whose mutable lifecycle still belongs to another Work.
+ */
+export function assertCanonicalRepositoryMutationWorkHandleAvailable(input: {
+  controllerHome: string;
+  repositoryId: string;
+  checkoutId: string;
+  workId?: string;
+}): void {
+  const owners = listWorkHandles(input.controllerHome, input.repositoryId, 5_000)
+    .filter((handle) => {
+      if (handle.workId === input.workId
+        || handle.checkoutId !== input.checkoutId
+        || handle.managedWorktree === true
+        || !DURABLE_CANONICAL_MUTATION_OWNER_STATES.has(handle.state)) {
+        return false;
+      }
+      const contract = getWorkContract(
+        { controllerHome: input.controllerHome, repoId: input.repositoryId },
+        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);
+    })
+    .sort((left, right) => left.workId.localeCompare(right.workId));
+  if (owners.length === 0) return;
+  if (owners.length > 1) {
+    throw new Error(
+      `WORK_CANONICAL_MUTATION_OWNERSHIP_AMBIGUOUS: checkout=${input.checkoutId}; owners=${owners.map((owner) => owner.workId).join(',')}; requested=${input.workId ?? 'unattributed'}`,
+    );
+  }
+  throw new Error(
+    `WORK_CANONICAL_MUTATION_OWNED: checkout=${input.checkoutId}; owner=${owners[0]!.workId}; state=${owners[0]!.state}; requested=${input.workId ?? 'unattributed'}`,
+  );
+}
+
+function resolveRepositoryWorkHandlePlacement(input: {
+  controllerHome: string;
+  repositoryId: string;
+  checkoutId: string;
+  worktreeRef?: string;
+}) {
+  const registeredRepository = getRepository(input.repositoryId, input.controllerHome, { includeRemoved: true });
+  const executionRepository = resolveRepositorySelection({ repoId: registeredRepository.repoId, checkoutId: input.checkoutId, controllerHome: input.controllerHome, allowSoleRepository: false });
+  const checkout = selectRepositoryCheckout(executionRepository, input.checkoutId, { allowArchived: true });
+  const registeredCheckout = registeredRepository.checkouts.find((entry) => entry.checkoutId === input.checkoutId);
+  if (!registeredCheckout) throw new Error(`WORK_CHECKOUT_NOT_REGISTERED: ${input.checkoutId}`);
+  const status = repositoryGitStatus(checkout);
+  const branch = status.branch;
+  if (!branch) throw new Error(`WORKTREE_DETACHED: ${input.checkoutId} has no branch`);
+  const managedWorktree = registeredCheckout.worktree === true
+    && Boolean(input.worktreeRef)
+    && resolve(input.worktreeRef!) === resolve(checkout.canonicalRoot)
+    && input.checkoutId !== registeredRepository.activeCheckoutId
+    && resolve(checkout.canonicalRoot) !== resolve(registeredRepository.canonicalRoot);
+  return { registeredRepository, registeredCheckout, checkout, status, branch, managedWorktree };
+}
+
 /**
  * Canonical compatibility repair for a goal-workloop Work whose durable
  * WorkContract exists but whose WorkHandle has not yet been materialized.
@@ -21,6 +95,7 @@ export function ensureRepositoryWorkHandle(input: {
   repository: RepositoryRecord;
   workId: string;
   identity: RepositoryWorkHandleControllerIdentity;
+  allowEffectWork?: boolean;
 }): WorkHandleState | undefined {
   const existing = readWorkHandle(input.controllerHome, input.repository.repoId, input.workId);
   if (existing) return existing;
@@ -28,22 +103,27 @@ export function ensureRepositoryWorkHandle(input: {
     { controllerHome: input.controllerHome, repoId: input.repository.repoId },
     input.workId,
   );
-  if (!contract || contract.workKind !== 'repository_change' || contract.mode !== 'goal_workloop' || !contract.checkoutId) {
+  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;
   }
-  const executionRepository = resolveRepositorySelection({
-    repoId: input.repository.repoId,
-    checkoutId: contract.checkoutId,
+  // 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.
+  const placement = resolveRepositoryWorkHandlePlacement({
     controllerHome: input.controllerHome,
-    allowSoleRepository: false,
+    repositoryId: input.repository.repoId,
+    checkoutId: contract.checkoutId,
+    worktreeRef: contract.worktreeRef,
   });
-  const checkout = selectRepositoryCheckout(executionRepository, contract.checkoutId, { allowArchived: true });
-  const status = repositoryGitStatus(checkout);
-  if (!status.branch) throw new Error(`WORKTREE_DETACHED: ${contract.checkoutId} has no branch`);
+  const { registeredRepository, checkout, status, branch, managedWorktree } = placement;
+  const sourceCheckoutId = registeredRepository.activeCheckoutId;
+  const sourceCheckout = selectRepositoryCheckout(registeredRepository, sourceCheckoutId, { allowArchived: true });
+  const sourceStatus = repositoryGitStatus(sourceCheckout);
+  if (!sourceStatus.branch) throw new Error(`WORK_DELIVERY_TARGET_DETACHED: source checkout ${sourceCheckoutId} has no branch`);
   const at = new Date().toISOString();
-  const managedWorktree = Boolean(contract.worktreeRef)
-    && resolve(contract.worktreeRef!) === resolve(checkout.canonicalRoot)
-    && resolve(checkout.canonicalRoot) !== resolve(input.repository.canonicalRoot);
   return writeWorkHandle(input.controllerHome, {
     schemaVersion: 1,
     workId: input.workId,
@@ -52,8 +132,9 @@ export function ensureRepositoryWorkHandle(input: {
     repositoryId: input.repository.repoId,
     checkoutId: contract.checkoutId,
     worktreePath: checkout.canonicalRoot,
-    branch: status.branch,
-    sourceCheckoutId: input.repository.activeCheckoutId,
+    branch,
+    sourceCheckoutId,
+    deliveryTargetBranch: sourceStatus.branch,
     managedWorktree,
     workContractId: contract.workId,
     baseCommit: contract.baseRevision ?? status.head ?? undefined,
@@ -74,6 +155,176 @@ export function ensureRepositoryWorkHandle(input: {
   });
 }
 
+/** Upgrade only a legacy false-negative managed-worktree classification after all durable placement authorities agree. */
+export function reconcileRepositoryWorkHandlePlacement(input: {
+  controllerHome: string;
+  repositoryId: string;
+  workId: string;
+}): WorkHandleState | undefined {
+  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.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;
+  if (placement.registeredCheckout.lifecycle !== 'active') throw new Error(`WORK_HANDLE_PLACEMENT_CHECKOUT_NOT_ACTIVE: ${input.workId}`);
+  if (resolve(existing.worktreePath) !== resolve(placement.checkout.canonicalRoot)) throw new Error(`WORK_HANDLE_PLACEMENT_PATH_MISMATCH: ${input.workId}`);
+  if (existing.branch !== placement.branch || (placement.registeredCheckout.branch && placement.registeredCheckout.branch !== placement.branch)) throw new Error(`WORK_HANDLE_PLACEMENT_BRANCH_MISMATCH: ${input.workId}`);
+  return writeWorkHandle(input.controllerHome, { ...existing, sourceCheckoutId: placement.registeredRepository.activeCheckoutId, managedWorktree: true });
+}
+
+function alignRepositoryMutationBase(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  contract: NonNullable<ReturnType<typeof getWorkContract>>;
+  handle: WorkHandleState;
+  freshlyMaterialized: boolean;
+}): 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}`);
+  }
+  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,
+  });
+  // A managed checkout has its own source lineage and does not participate in
+  // shared-canonical target-base alignment.
+  if (placement.managedWorktree) return input.handle;
+
+  const targetBranch = input.handle.deliveryTargetBranch ?? placement.branch;
+  const inspection = inspectDirectCanonicalPreMutationReconciliation({
+    handle: input.handle,
+    root: placement.checkout.canonicalRoot,
+    targetBranch,
+    status: placement.status,
+    freshlyMaterialized: input.freshlyMaterialized,
+  });
+  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}`);
+  }
+
+  const aligned = transitionWorkHandle(input.controllerHome, input.handle, input.handle.state, {
+    deliveryBaseCommit: inspection.targetHead,
+    expectedHead: inspection.targetHead,
+    failureReason: undefined,
+  });
+  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.`,
+      detailLevel: 'summary',
+    },
+  );
+  return aligned;
+}
+
+export function markRepositoryMutationStarted(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  expectedDeliveryBase?: string;
+}): 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);
+  }
+  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;
+  if (boundWorkId !== input.workId) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_HANDLE_IDENTITY_MISMATCH: expected ${boundWorkId}, found ${input.workId}`);
+  }
+  const deliveryBase = handle.deliveryBaseCommit ?? handle.baseCommit;
+  if (input.expectedDeliveryBase && deliveryBase !== input.expectedDeliveryBase) {
+    throw new Error(`WORK_REPOSITORY_MUTATION_BASE_CHANGED: expected ${input.expectedDeliveryBase}, found ${deliveryBase ?? 'none'}`);
+  }
+  return transitionWorkHandle(input.controllerHome, handle, 'editing');
+}
+
+/**
+ * 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.
+ */
+export function ensureRepositoryMutationWorkHandle(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  principalId: 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);
+  if (!contract) throw new Error(`WORK_NOT_FOUND: ${input.workId}`);
+  if (isTerminalWorkContractStatus(contract.status) || contract.completionReceipt) {
+    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}`);
+  }
+
+  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 });
+  }
+  assertCanonicalRepositoryMutationWorkHandleAvailable({
+    controllerHome: input.controllerHome,
+    repositoryId: input.repository.repoId,
+    checkoutId: mutationCheckoutId,
+    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}`);
+  }
+
+  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,
+  });
+  if (!handle) throw new Error(`WORK_REPOSITORY_MUTATION_HANDLE_REQUIRED: ${input.workId}`);
+  handle = alignRepositoryMutationBase({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.workId,
+    contract,
+    handle,
+    freshlyMaterialized: !existingHandle,
+  });
+  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

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

@@ -59,6 +59,16 @@ export interface WorkCleanupReceipt {
     patchArchiveSha256?: string;
     bundlePath?: string;
     bundleSha256?: string;
+    bundleRetirement?: {
+      status: 'eligible' | 'removed' | 'not_needed';
+      reason: 'no_source_delta' | 'target_and_remote_content_contained';
+      protectedRevision: string;
+      targetRevision?: string;
+      remoteRevision?: string;
+      comparedPaths: string[];
+      provedAt: string;
+      removedAt?: string;
+    };
     recoveryInstructions?: string;
   };
   worktree: {
@@ -85,12 +95,18 @@ export interface WorkCleanupReceipt {
   blockers: string[];
 }
 
+export type WorkFinalizationFailureCode =
+  | 'WORK_HANDLE_HEAD_CHANGED'
+  | 'WORK_TARGET_ADVANCE_LINEAR_HISTORY_VIOLATION';
+
 export interface WorkFinalizationStages {
   validation: 'pending' | 'done' | 'failed';
   commit: 'pending' | 'done' | 'skipped' | 'failed';
   merge: 'pending' | 'done' | 'skipped' | 'failed';
   branchCleanup: 'pending' | 'done' | 'skipped' | 'failed';
   worktreeCleanup: 'pending' | 'done' | 'skipped' | 'failed';
+  /** Typed recovery classification. lastError remains diagnostic text only. */
+  failureCode?: WorkFinalizationFailureCode;
   lastError?: string;
 }
 
@@ -147,6 +163,8 @@ export interface WorkHandleState {
   worktreePath: string;
   branch: string;
   sourceCheckoutId?: string;
+  /** Canonical branch this repository-change Work is authorized to deliver into. Absent only for legacy handles. */
+  deliveryTargetBranch?: string;
   goalId?: string;
   delegationVersion?: number;
   managedWorktree: boolean;
@@ -190,6 +208,24 @@ export function workDeliveryBaseRevision(
   return handle.deliveryBaseCommit?.trim() || handle.baseCommit?.trim() || undefined;
 }
 
+export function resolveWorkDeliveryTargetBranch(
+  handle: Pick<WorkHandleState, 'workId' | 'deliveryTargetBranch'>,
+  repositoryDefaultBranch?: string,
+  explicitTargetBranch?: string,
+): string {
+  const bound = handle.deliveryTargetBranch?.trim();
+  const explicit = explicitTargetBranch?.trim();
+  if (bound) {
+    if (explicit && explicit !== bound) {
+      throw new Error(
+        `WORK_DELIVERY_TARGET_BRANCH_MISMATCH: work ${handle.workId} is bound to ${bound}; omit target_branch or use ${bound}, not ${explicit}`,
+      );
+    }
+    return bound;
+  }
+  return explicit || repositoryDefaultBranch?.trim() || 'main';
+}
+
 function workHandlePath(controllerHome: string, handle: Pick<WorkHandleState, 'repositoryId' | 'workId'>): string {
   return join(repositoryControllerRoot(controllerHome, handle.repositoryId), 'work-handles', `${sanitizeFileComponent(handle.workId)}.json`);
 }
@@ -368,6 +404,47 @@ 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

@@ -0,0 +1,75 @@
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
+import type { ResolvedExecutionIdentity } from './execution-identity';
+import { readWorkHandle, transitionWorkHandle } from './work-handle-store';
+
+export type WorkHeadSettlementReason =
+  | 'settled'
+  | 'no_work'
+  | 'command_not_successful'
+  | 'work_handle_missing'
+  | 'identity_mismatch'
+  | 'terminal_handle'
+  | 'branch_changed'
+  | 'head_unavailable'
+  | 'head_unchanged'
+  | 'concurrent_lifecycle_write';
+
+export interface WorkHeadSettlementResult {
+  settled: boolean;
+  reason: WorkHeadSettlementReason;
+  previousHead?: string;
+  currentHead?: string;
+}
+
+/**
+ * Settle the one legitimate post-command Work HEAD transition without weakening
+ * the pre-command execution identity fence. The immutable execution identity is
+ * the authority captured before spawn; a concurrent lifecycle writer or branch
+ * drift must not be adopted after the command returns.
+ */
+export function settleWorkHandleExpectedHeadAfterRepositoryCommand(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  executionIdentity: ResolvedExecutionIdentity;
+  workId?: string;
+  ok?: boolean;
+  cancelled?: boolean;
+  timedOut?: boolean;
+}): WorkHeadSettlementResult {
+  const workId = input.workId?.trim();
+  if (!workId) return { settled: false, reason: 'no_work' };
+  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') {
+    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 };
+  }
+  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 };
+  }
+  try {
+    transitionWorkHandle(input.controllerHome, handle, handle.state, { expectedHead: currentHead });
+    return { settled: true, reason: 'settled', previousHead: handle.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 };
+    }
+    throw error;
+  }
+}