@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/control-plane/execution/work-evidence-policy.ts

@@ -97,25 +97,6 @@ export function evaluateWorkImplementationEvidence(
   };
 }
 
-export function evaluateReadOnlyReviewSourceIdentity(
-  work: WorkContract,
-  currentRevision?: string,
-  currentWorkspaceChangedPaths?: readonly string[],
-): { status: 'complete' | 'incomplete'; reasons: string[] } {
-  if (work.workKind !== 'read_only_review') return { status: 'complete', reasons: [] };
-  const reasons: string[] = [];
-  if (!work.baseRevision?.trim()) reasons.push('Read-only review has no frozen base revision.');
-  if (!currentRevision?.trim()) reasons.push('Current source revision is unavailable, so unchanged-source proof is incomplete.');
-  if (work.baseRevision && currentRevision && work.baseRevision !== currentRevision) {
-    reasons.push(`Read-only review source drifted from frozen base ${work.baseRevision} to ${currentRevision}.`);
-  }
-  if (currentWorkspaceChangedPaths === undefined) {
-    reasons.push('Current workspace changed-path proof is unavailable for read-only review.');
-  } else if (currentWorkspaceChangedPaths.length > 0) {
-    reasons.push(`Read-only review workspace is not unchanged: ${[...new Set(currentWorkspaceChangedPaths)].slice(0, 12).join(', ')}.`);
-  }
-  return { status: reasons.length === 0 ? 'complete' : 'incomplete', reasons };
-}
 
 export function evaluateWorkCompletionEvidence(
   work: WorkContract,
@@ -133,23 +114,9 @@ export function evaluateWorkCompletionEvidence(
     applicableCheckRefs.map((record) => ({ checkId: record.checkId, outcome: record.outcome, recordedAt: record.recordedAt })),
   );
   const missingChecks = work.checks.filter((checkId) => !history.validPasses.includes(checkId));
-  const readOnlySourceIdentity = evaluateReadOnlyReviewSourceIdentity(work, currentRevision, currentWorkspaceChangedPaths);
-  const readOnlyEvidence = work.readOnlyReviewEvidence;
-  const readOnlyEvidenceMatchesCurrentSource = Boolean(
-    work.workKind === 'read_only_review'
-    && readOnlyEvidence
-    && currentRevision
-    && readOnlyEvidence.sourceRevision === currentRevision
-    && (readOnlyEvidence.workspaceFingerprint === undefined
-      || currentWorkspaceFingerprint === undefined
-      || readOnlyEvidence.workspaceFingerprint === currentWorkspaceFingerprint),
-  );
-  const cleanReadOnlyReviewEvidence = Boolean(
-    readOnlyEvidenceMatchesCurrentSource
-    && readOnlySourceIdentity.status === 'complete'
-    && (readOnlyEvidence?.inspectedPaths.length ?? 0) > 0
-    && (readOnlyEvidence?.findings.length ?? 0) === 0,
-  );
+  // Review findings are recorded observations, never a completion gate. A
+  // read-only review Work closes like any other Work; its inspected paths and
+  // findings stay durable evidence for the model/user to act on.
   const workEvidenceIds = work.evidenceRefs.flatMap((evidence) => [evidence.evidenceId, evidence.artifactId])
     .map((value) => value?.trim())
     .filter((value): value is string => Boolean(value));
@@ -157,9 +124,16 @@ export function evaluateWorkCompletionEvidence(
     ...workEvidenceIds,
     ...workBoundProcessEvidenceIds.map((value) => value.trim()).filter(Boolean),
   ]);
+  // Recorded read-only review scope is durable observation evidence for this Work
+  // kind; findings inside it never gate completion.
+  const readOnlyReviewEvidenceRecorded = Boolean(
+    work.workKind === 'read_only_review'
+    && work.readOnlyReviewEvidence
+    && (work.readOnlyReviewEvidence.inspectedPaths.length > 0 || work.readOnlyReviewEvidence.findings.length > 0),
+  );
   const durableResultEvidence = availableDurableEvidenceIds.size > 0
     || applicableCheckRefs.some((record) => isAuthoritativeCurrentWorkVerification(work, record, currentRevision))
-    || cleanReadOnlyReviewEvidence;
+    || readOnlyReviewEvidenceRecorded;
   const sourceDeltaRequiresImplementationReview = work.workKind === 'local_effect'
     && (currentWorkspaceChangedPaths?.length ?? 0) > 0;
   const requiresSemanticAcceptance = work.workKind === 'local_effect'
@@ -188,17 +162,6 @@ export function evaluateWorkCompletionEvidence(
   if (missingChecks.length > 0) {
     reasons.push(`Declared checks are missing valid_pass evidence: ${missingChecks.join(', ')}.`);
   }
-  if (work.workKind === 'read_only_review') {
-    reasons.push(...readOnlySourceIdentity.reasons);
-    if (!readOnlyEvidence || readOnlyEvidence.inspectedPaths.length === 0) {
-      reasons.push('Read-only review has no persisted inspected-path evidence.');
-    } else if (!readOnlyEvidenceMatchesCurrentSource) {
-      reasons.push('Persisted read-only review evidence is stale for the current source/workspace identity.');
-    }
-    if ((readOnlyEvidence?.findings.length ?? 0) > 0) {
-      reasons.push(`Read-only review has unresolved semantic findings (${readOnlyEvidence!.findings.length}); clean no-change completion is not allowed.`);
-    }
-  }
   if (work.checks.length === 0 && !durableResultEvidence) {
     const staleWorkVerification = work.checkRefs.some((record) =>
       Boolean(record.receipt)
@@ -217,8 +180,7 @@ export function evaluateWorkCompletionEvidence(
     && history.invalidCheckIds.length === 0
     && missingChecks.length === 0
     && (work.checks.length > 0 || durableResultEvidence)
-    && semanticAcceptanceComplete
-    && (work.workKind !== 'read_only_review' || cleanReadOnlyReviewEvidence);
+    && semanticAcceptanceComplete;
   return {
     status: complete ? 'complete' : 'incomplete',
     history,

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,