@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/control-plane/execution/work-execution-support.ts

@@ -1,13 +1,12 @@
 import type { McpExecutionContext } from '../../../../packages/protocols/mcp/execution-context';
 import { getRepository, listRepositories, RepositoryCheckoutSelectionError, selectRepositoryCheckout } from '../../../cli/repositories/registry';
 import { reconcileWorkValidation } from './work-validation-reconciler';
-import { assertControllerOwnershipAuthority, claimControllerSession, controllerSessionPrincipalId, getControllerSession, releaseControllerSessionWithAuthority, resumeControllerSession } from '../../../../packages/kernel/controller/api/index';
 import { appendWorkEvidence, getWorkContract, transitionWorkContractPhase } from '../../../../packages/kernel/work/api/index';
 import { resolveLegacyWorkContractIdentity } from './execution-identity';
 import type { ExecutionSessionContext, SessionIdentity } from './session-store';
 import { currentControllerInstanceId, requireExecutionSession, updateExecutionSession } from './session-store';
 import type { WorkHandleState, WorkTerminalOutcome } from './work-handle-store';
-import { readWorkHandle, writeWorkHandle } from './work-handle-store';
+import { readWorkHandle, rebindWorkHandleControllerIdentity, writeWorkHandle } from './work-handle-store';
 import { cleanupTerminalWork } from './work-terminal-cleanup';
 import { spawnSync } from 'child_process';
 import { writeControllerResult } from '../../evidence/result-store';
@@ -69,34 +68,14 @@ export function gitHead(root: string): string | undefined {
   return gitRevision(root, 'HEAD');
 }
 
-export function gitCommit(root: string, revision: string, label: string): string {
-  const output = spawnSync('git', ['-C', root, 'rev-parse', '--verify', `${revision}^{commit}`], {
+export function gitIsAncestor(root: string, ancestor: string, descendant: string): boolean {
+  const result = spawnSync('git', ['-C', root, 'merge-base', '--is-ancestor', ancestor, descendant], {
     encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000,
   });
-  if (output.status !== 0 || output.error || typeof output.stdout !== 'string' || !output.stdout.trim()) {
-    throw new Error(`WORK_HEAD_ADOPTION_${label}_INVALID: ${revision}`);
+  if (result.error || (result.status !== 0 && result.status !== 1)) {
+    throw new Error(`WORK_GIT_ANCESTRY_UNAVAILABLE: ${ancestor} -> ${descendant}`);
   }
-  return output.stdout.trim();
-}
-
-export function gitChangedPaths(root: string, previousHead: string, candidateHead: string): string[] {
-  const output = spawnSync('git', ['-C', root, 'diff', '--name-only', '-z', previousHead, candidateHead], {
-    encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000, maxBuffer: 8 * 1024 * 1024,
-  });
-  if (output.status !== 0 || output.error || typeof output.stdout !== 'string') {
-    throw new Error('WORK_HEAD_ADOPTION_CHANGED_PATHS_UNAVAILABLE');
-  }
-  return [...new Set(output.stdout.split('\0').filter(Boolean))].sort((left, right) => left.localeCompare(right));
-}
-
-export function gitMergeBase(root: string, leftHead: string, rightHead: string): string {
-  const output = spawnSync('git', ['-C', root, 'merge-base', leftHead, rightHead], {
-    encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000,
-  });
-  if (output.status !== 0 || output.error || typeof output.stdout !== 'string' || !output.stdout.trim()) {
-    throw new Error('WORK_HEAD_ADOPTION_SCOPE_BASE_UNAVAILABLE');
-  }
-  return output.stdout.trim();
+  return result.status === 0;
 }
 
 export function selectWorkFinalizationTarget(
@@ -178,30 +157,20 @@ export function findWorkHandle(
   });
 }
 
-function currentControllerClaimAuthorizesTerminalCleanup(
-  ctx: McpExecutionContext,
-  session: ExecutionSessionContext,
-  handle: WorkHandleState,
-): boolean {
-  if (!terminalCleanupOutcome(ctx, handle)) return false;
-  const workIdValue = handle.workContractId ?? handle.workId;
-  const owner = getControllerSession({ controllerHome: ctx.controllerHome, repoId: handle.repositoryId }, workIdValue);
-  if (!owner) return false;
-  return controllerSessionPrincipalId(owner) === session.principalId
-    && owner.controllerInstanceId === session.controllerInstanceId;
-}
-
 export function workForSession(
   ctx: McpExecutionContext,
   session: ExecutionSessionContext,
   args: Record<string, unknown>,
-  options: { reconcileValidation?: boolean; allowClaimedTerminalCleanup?: boolean } = {},
+  options: { reconcileValidation?: boolean } = {},
 ): WorkHandleState {
   let handle = findWorkHandle(ctx, session, args);
-  if (
-    handle.principalId !== session.principalId
-    && !(options.allowClaimedTerminalCleanup === true && currentControllerClaimAuthorizesTerminalCleanup(ctx, session, handle))
-  ) throw new Error('WORK_HANDLE_PRINCIPAL_MISMATCH: work handle belongs to another principal');
+  if (handle.principalId !== session.principalId || handle.sessionId !== session.sessionId) {
+    handle = rebindWorkHandleControllerIdentity(
+      ctx.controllerHome,
+      handle,
+      { principalId: session.principalId, sessionId: session.sessionId },
+    );
+  }
   if (options.reconcileValidation !== false) handle = reconcileWorkValidation(ctx.controllerHome, handle).handle;
   if (
     session.activeRepositoryId !== handle.repositoryId
@@ -219,115 +188,21 @@ export function workForSession(
   return handle;
 }
 
-export function assertWorkControllerOwnership(
-  ctx: McpExecutionContext,
-  session: ExecutionSessionContext,
-  handle: WorkHandleState,
-  args: Record<string, unknown>,
-) {
-  const workIdValue = handle.workContractId ?? handle.workId;
-  const options = { controllerHome: ctx.controllerHome, repoId: handle.repositoryId };
-  const owner = getControllerSession(options, workIdValue);
-  const controllerId = typeof args.controller_id === 'string' && args.controller_id.trim()
-    ? args.controller_id.trim()
-    : session.principalId;
-  if (controllerId !== session.principalId) {
-    throw new Error('WORK_CONTROLLER_IDENTITY_MISMATCH: controller_id must match the authenticated principal');
-  }
-  if (owner) {
-    const authority = assertControllerOwnershipAuthority(owner, {
-      workId: workIdValue,
-      controllerId,
-      principalId: session.principalId,
-      controllerInstanceId: session.controllerInstanceId,
-    });
-    const resumed = resumeControllerSession(options, {
-      workId: workIdValue,
-      controllerId,
-      controllerType: authority.controllerType,
-      sessionId: session.sessionId,
-      principalId: session.principalId,
-      controllerInstanceId: session.controllerInstanceId,
-      expectedClaimGeneration: authority.claimGeneration,
-      leaseMs: 3_600_000,
-    });
-    if (
-      resumed.controllerId !== authority.controllerId
-      || controllerSessionPrincipalId(resumed) !== authority.principalId
-      || resumed.controllerInstanceId !== authority.controllerInstanceId
-      || resumed.claimGeneration !== authority.claimGeneration
-    ) {
-      throw new Error(`WORK_CONTROLLER_OWNER_MISMATCH: ${workIdValue} ownership epoch changed during resume`);
-    }
-    return resumed;
-  }
-  return claimControllerSession(options, {
-    workId: workIdValue,
-    controllerId,
-    controllerType: 'chatgpt',
-    sessionId: session.sessionId,
-    principalId: session.principalId,
-    controllerInstanceId: session.controllerInstanceId,
-    expectedClaimGeneration: 0,
-    leaseMs: 3_600_000,
-  });
-}
-
-export function releasePreparedWorkOwnership(
-  ctx: McpExecutionContext,
-  handle: WorkHandleState,
-): 'released' | 'already_released' {
-  const workIdValue = handle.workContractId ?? handle.workId;
-  const options = { controllerHome: ctx.controllerHome, repoId: handle.repositoryId };
-  const current = getControllerSession(options, workIdValue);
-  if (!current) return 'already_released';
-
-  const callerPrincipal = principalFor(ctx);
-  const callerInstanceId = ctx.controllerInstanceId ?? currentControllerInstanceId();
-  const ownerPrincipal = current.principalId?.trim() || current.controllerId;
-  const ownerInstanceId = current.controllerInstanceId?.trim() || '';
-  if (ownerPrincipal !== callerPrincipal) {
-    throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${workIdValue}`);
-  }
-  if (!ownerInstanceId || ownerInstanceId !== callerInstanceId) {
-    throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${workIdValue}`);
-  }
-  if (typeof current.claimGeneration !== 'number' || current.claimGeneration < 1) {
-    throw new Error(`WORK_CONTROLLER_CLAIM_GENERATION_REQUIRED: ${workIdValue}`);
-  }
-
-  const released = releaseControllerSessionWithAuthority(options, {
-    workId: workIdValue,
-    actor: `legacy-work-release:${callerPrincipal}:${callerInstanceId}`,
-    authority: {
-      controllerId: current.controllerId,
-      controllerType: current.controllerType,
-      principalId: ownerPrincipal,
-      controllerInstanceId: ownerInstanceId,
-      claimGeneration: current.claimGeneration,
-    },
-  });
-  if (!released.allowed) {
-    throw new Error(`WORK_CONTROLLER_RELEASE_FENCED: ${workIdValue}:${released.reason}`);
-  }
-  return 'released';
-}
-
 export function terminalCleanupOutcome(
   ctx: McpExecutionContext,
   handle: WorkHandleState,
 ): WorkTerminalOutcome | undefined {
   if (handle.cleanupReceipt) return handle.cleanupReceipt.terminalOutcome;
   const contract = contractFor(ctx, handle);
-  if (contract?.status === 'cancelled') return 'cancelled';
-  if (contract?.status === 'completed') return 'completed_cleanup';
+  if (contract?.semanticState === 'cancelled') return 'cancelled';
+  if (contract?.semanticState === 'completed') return 'completed_cleanup';
   const reason = `${handle.failureReason ?? ''} ${handle.finalization.lastError ?? ''}`.toLowerCase();
-  if (contract?.status === 'blocked' && reason.includes('terminal')) return 'blocked_terminal';
+  if (contract?.dispatchState === 'blocked' && reason.includes('terminal')) return 'blocked_terminal';
   // `failed` is a retryable execution-handle state (its transition table allows
   // failed -> validating/editing). Do not reinterpret it as terminal cleanup
   // unless the durable Work itself is terminal. `failed_terminal_cleanup` is
   // the explicit point of no return for resource cleanup reconciliation.
-  if (contract?.status === 'failed' || handle.state === 'failed_terminal_cleanup') {
+  if (contract?.evidenceState === 'failed' || handle.state === 'failed_terminal_cleanup') {
     if (reason.includes('infrastructure') || reason.includes('timed out') || reason.includes('unavailable')) {
       return 'infrastructure_failed';
     }
@@ -345,16 +220,42 @@ export async function reconcileTerminalCleanup(
   outcome: WorkTerminalOutcome,
 ): Promise<Record<string, unknown>> {
   const wasComplete = handle.cleanupReceipt?.complete === true;
+  let cleanupHandle = handle;
+  const retained = handle.terminalResourceDisposition?.mode === 'retained_by_request'
+    ? handle.terminalResourceDisposition
+    : undefined;
+  if (retained) {
+    cleanupHandle = writeWorkHandle(ctx.controllerHome, {
+      ...handle,
+      terminalResourceDisposition: undefined,
+      finalization: {
+        ...handle.finalization,
+        branchCleanup: retained.retainBranch === true && args.delete_branch !== false ? 'pending' : handle.finalization.branchCleanup,
+        worktreeCleanup: retained.retainWorktree === true ? 'pending' : handle.finalization.worktreeCleanup,
+      },
+    });
+    appendWorkEvidence(
+      { controllerHome: ctx.controllerHome, repoId: cleanupHandle.repositoryId },
+      cleanupHandle.workContractId ?? cleanupHandle.workId,
+      {
+        title: 'terminal retention consumed by explicit cleanup request',
+        summary: 'An explicit cleanup=true request consumed the durable retained_by_request resource disposition; automatic maintenance did not infer this authorization from skipped cleanup stages.',
+        detailLevel: 'summary',
+      },
+    );
+  }
   const cleaned = await cleanupTerminalWork({
     controllerHome: ctx.controllerHome,
-    handle,
+    handle: cleanupHandle,
     targetBranch: typeof args.target_branch === 'string' ? args.target_branch : undefined,
     deleteBranch: args.delete_branch !== false,
     terminalOutcome: outcome,
     failureReason: handle.failureReason ?? handle.finalization.lastError,
   });
-  const ownership = releasePreparedWorkOwnership(ctx, cleaned.handle);
-  cleaned.receipt.ownership.controllerLease = ownership;
+  // ControllerSession is explicit continuation state, not a Work cleanup
+  // resource. Keep the legacy receipt projection inert until its final schema
+  // deletion; cleanup never claims or releases Controller authority.
+  cleaned.receipt.ownership.controllerLease = 'already_released';
   const persisted = writeWorkHandle(ctx.controllerHome, {
     ...cleaned.handle,
     cleanupReceipt: cleaned.receipt,
@@ -379,15 +280,14 @@ export async function reconcileTerminalCleanup(
       { controllerHome: ctx.controllerHome, repoId: persisted.repositoryId },
       persisted.workContractId ?? persisted.workId,
     );
-    if (terminalContract && (terminalContract.status === 'cancelled' || terminalContract.status === 'failed') && terminalContract.phase !== 'cleanup') {
+    if (terminalContract && (terminalContract.semanticState === 'cancelled') && terminalContract.phase !== 'cleanup') {
       transitionWorkContractPhase(
         { controllerHome: ctx.controllerHome, repoId: persisted.repositoryId },
         terminalContract.workId,
         {
           phase: 'cleanup',
-          status: terminalContract.status,
           state: 'satisfied',
-          summary: `Terminal cleanup ${cleaned.receipt.receiptId} completed; terminal Work status ${terminalContract.status} was preserved.`,
+          summary: `Terminal cleanup ${cleaned.receipt.receiptId} completed; semantic Work state ${terminalContract.semanticState} was preserved.`,
           evidenceRefs: terminalContract.evidenceRefs,
         },
       );
@@ -399,6 +299,7 @@ export async function reconcileTerminalCleanup(
     completed: false,
     cleanupCompleted: cleaned.receipt.complete,
     cleanupPartial: cleaned.receipt.partial,
+    cleanupRetained: cleaned.receipt.worktree.status === 'retained' || cleaned.receipt.branchCleanup.status === 'retained',
     failurePreserved: true,
     cleanupReceipt: cleaned.receipt,
     idempotent: wasComplete,