@moretea-labs/forge 1.8.1 → 1.8.2

package/src/runtime/control-plane/execution/work-preparation-service.ts

@@ -12,7 +12,7 @@ import { isTerminalSemanticWorkState } from '../facade/types';
 import { updateExecutionSession, type ExecutionSessionContext } from './session-store';
 import { currentPermissionSnapshotVersion, validateWorkHandle } from './validation';
 import { withWorkPrepareRequest } from './work-prepare-request-store';
-import { markWorkHandleFailed, newWorkId, readWorkHandle, writeWorkHandle, type WorkFinalizationStages, type WorkHandleState } from './work-handle-store';
+import { markWorkHandleFailed, newWorkId, readWorkHandle, relocateWorkHandlePlacementAtomically, writeWorkHandle, type WorkFinalizationStages, type WorkHandleState } from './work-handle-store';
 import { createGoalDelegation } from '../governance/authorization';
 import { compactHandle, contractFor, findWorkHandle, gitHead, gitIsAncestor, identityFor, requireSession } from './work-execution-support';
 
@@ -42,6 +42,11 @@ function boundedStringArray(value: unknown, limit: number): string[] {
   return Array.isArray(value) ? value.map(String).slice(0, limit) : [];
 }
 
+function requestedWorkPrepareIsolation(args: Record<string, unknown>): 'reuse' | 'new_worktree' | 'auto' | undefined {
+  if (!Object.prototype.hasOwnProperty.call(args, 'isolation')) return undefined;
+  return args.isolation === 'reuse' || args.isolation === 'new_worktree' || args.isolation === 'auto' ? args.isolation : 'auto';
+}
+
 function workPrepareFingerprint(input: {
   repoId: string;
   requestedCheckoutId?: string;
@@ -112,7 +117,12 @@ function adoptExplicitSuccessorHead(
   if (!expectedPreviousHead || !adoptCandidateHead) {
     throw new Error('WORK_HANDLE_SUCCESSOR_ADOPTION_PAIR_REQUIRED: expected_previous_head and adopt_candidate_head must be supplied together');
   }
-  if (existing.state !== 'prepared' && existing.state !== 'editing') {
+  // A failed validation attempt may need an explicit, audited successor
+  // adoption before it can retry against the current checkout. Keep its
+  // failed state: only a fresh valid check may restore execution authority.
+  const retryableValidationFailure = existing.state === 'failed'
+    && existing.finalization.validation === 'failed';
+  if (existing.state !== 'prepared' && existing.state !== 'editing' && !retryableValidationFailure) {
     throw new Error(`WORK_HANDLE_SUCCESSOR_ADOPTION_STATE_INVALID: ${existing.state}`);
   }
   if (existing.expectedHead !== expectedPreviousHead) {
@@ -150,7 +160,8 @@ function adoptExplicitSuccessorHead(
   }
   const candidate: WorkHandleState = {
     ...existing,
-    deliveryBaseCommit: adoptCandidateHead,
+    // Successor adoption advances the Work candidate, not the delivery target.
+    // Preserve the canonical delivery base until authorized delivery or rebase.
     expectedHead: adoptCandidateHead,
     validationRun: undefined,
     validatedInputFingerprint: undefined,
@@ -161,6 +172,86 @@ function adoptExplicitSuccessorHead(
   return writeWorkHandle(ctx.controllerHome, candidate);
 }
 
+function relocateExistingWorkToManagedCheckout(
+  ctx: McpExecutionContext,
+  args: Record<string, unknown>,
+  session: ExecutionSessionContext,
+  repository: ReturnType<typeof selectedRepository>,
+  existing: WorkHandleState,
+): Record<string, unknown> {
+  const prior = typeof args.expected_previous_head === 'string' ? args.expected_previous_head.trim() : '';
+  const candidate = typeof args.adopt_candidate_head === 'string' ? args.adopt_candidate_head.trim() : '';
+  const baseRef = typeof args.base_ref === 'string' ? args.base_ref.trim() : '';
+  if (!prior || !candidate || baseRef !== candidate || !/^[0-9a-f]{40}$/.test(candidate)) {
+    throw new Error('WORK_RELOCATION_EXACT_HEADS_REQUIRED: supply expected_previous_head and matching base_ref/adopt_candidate_head');
+  }
+  if (existing.principalId !== session.principalId) throw new Error('WORK_HANDLE_ACCESS_DENIED');
+  if (existing.expectedHead !== prior && !(existing.managedWorktree && existing.expectedHead === candidate)) {
+    throw new Error('WORK_RELOCATION_PREVIOUS_HEAD_MISMATCH');
+  }
+  if (existing.managedWorktree) {
+    if (existing.expectedHead !== candidate) throw new Error('WORK_RELOCATION_ALREADY_ISOLATED');
+    validateWorkHandle(ctx.controllerHome, existing, identityFor(ctx, args), 'cheap', 'inspect');
+    updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), {
+      activeRepositoryId: existing.repositoryId, activeCheckoutId: existing.checkoutId,
+      activeWorkId: existing.workId, permissionSnapshotVersion: existing.permissionSnapshotVersion,
+    });
+    return { session: requireSession(ctx, args), work: compactHandle(existing), reused: true, relocated: true };
+  }
+  if (existing.state !== 'prepared' && existing.state !== 'editing') throw new Error('WORK_RELOCATION_STATE_INVALID');
+  if (existing.finalization.validation !== 'pending' || existing.finalization.commit !== 'pending' || existing.finalization.merge !== 'pending'
+      || existing.finalization.worktreeCleanup !== 'pending' || existing.finalization.branchCleanup !== 'pending'
+      || existing.cleanupReceipt || existing.validatedInputFingerprint || existing.validationRun) {
+    throw new Error('WORK_RELOCATION_FINALIZATION_IN_PROGRESS');
+  }
+  const contract = getWorkContract({ controllerHome: ctx.controllerHome, repoId: existing.repositoryId }, existing.workId);
+  if (!contract || contract.semanticState !== 'open' || contract.completionReceipt || contract.completionOutcome
+      || contract.checkoutId !== existing.checkoutId) throw new Error('WORK_RELOCATION_CONTRACT_MISMATCH');
+  if (existing.checkoutId !== repository.activeCheckoutId || existing.worktreePath !== repository.canonicalRoot
+      || existing.branch !== repositoryGitStatus(repository).branch) throw new Error('WORK_RELOCATION_SOURCE_MISMATCH');
+  if (!gitIsAncestor(existing.worktreePath, prior, candidate)) throw new Error('WORK_RELOCATION_NONLINEAR');
+  const changedPaths = gitPathSet(existing.worktreePath, ['diff', '--name-only', prior + '..' + candidate], 'WORK_RELOCATION_DIFF_UNAVAILABLE');
+  const dirtyPaths = currentDirtyPaths(existing.worktreePath);
+  const overlap = [...changedPaths].filter((path) => dirtyPaths.has(path));
+  if (overlap.length) throw new Error('WORK_RELOCATION_DIRTY_OVERLAP: ' + overlap.sort().join(','));
+  if (listRecoverableProcessRecords(ctx.controllerHome, existing.repositoryId).some((record) => record.workId === existing.workId)) {
+    throw new Error('WORK_RELOCATION_ACTIVE_PROCESS');
+  }
+  const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+  if (!requestId) throw new Error('WORK_RELOCATION_REQUEST_ID_REQUIRED');
+  // A deterministic request identity makes physical worktree creation safe to
+  // resume after a process crash before the authoritative database transaction.
+  const workspace = ensureManagedWorkspace(ctx.controllerHome, repository, {
+    requestId: 'relocate:' + existing.workId + ':' + candidate,
+    title: 'Relocate existing Work to managed checkout',
+    associatedWorkId: existing.workId,
+    baseRef: candidate,
+    prepareDependencies: false,
+  });
+  if (!workspace.managed || !workspace.checkoutId || !workspace.root || !workspace.branch) {
+    throw new Error('WORK_RELOCATION_TARGET_NOT_MANAGED');
+  }
+  const selectedTarget = resolveRepositorySelection({
+    repoId: existing.repositoryId, checkoutId: workspace.checkoutId,
+    controllerHome: ctx.controllerHome, allowSoleRepository: false,
+  });
+  const targetStatus = repositoryGitStatus(selectedTarget);
+  if (!targetStatus.clean || targetStatus.head !== candidate || targetStatus.branch !== workspace.branch
+      || workspace.checkoutId === existing.checkoutId || selectedTarget.canonicalRoot !== workspace.root) {
+    throw new Error('WORK_RELOCATION_TARGET_CHANGED');
+  }
+  const refreshed = relocateWorkHandlePlacementAtomically(ctx.controllerHome, existing, {
+    checkoutId: workspace.checkoutId, root: workspace.root,
+    branch: workspace.branch, head: candidate,
+  });
+  updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), {
+    activeRepositoryId: refreshed.repositoryId, activeCheckoutId: refreshed.checkoutId,
+    activeWorkId: refreshed.workId, permissionSnapshotVersion: refreshed.permissionSnapshotVersion,
+  });
+  return { session: requireSession(ctx, args), work: compactHandle(refreshed), relocated: true,
+    previousCheckoutId: existing.checkoutId, previousHead: prior, currentHead: candidate };
+}
+
 export function prepareWork(ctx: McpExecutionContext, args: Record<string, unknown>): Record<string, unknown> {
   const session = requireSession(ctx, args);
   const repository = selectedRepository(ctx, session, args, true);
@@ -168,10 +259,23 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
     updateExecutionSession(ctx.controllerHome, identityFor(ctx, args), { activeRepositoryId: repository.repoId, activeCheckoutId: repository.activeCheckoutId, permissionSnapshotVersion: currentPermissionSnapshotVersion(ctx.controllerHome, repository.repoId) });
   }
   const existingId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  if (args.relocate_to_new_worktree === true && !existingId) throw new Error('WORK_RELOCATION_EXISTING_WORK_ID_REQUIRED');
+  const requestedIsolation = requestedWorkPrepareIsolation(args);
   if (existingId) {
     const existing = readWorkHandle(ctx.controllerHome, repository.repoId, existingId)
       ?? findWorkHandle(ctx, session, { ...args, work_id: existingId, repo_id: repository.repoId });
     if (existing.principalId !== session.principalId) throw new Error('WORK_HANDLE_ACCESS_DENIED');
+    if (args.relocate_to_new_worktree === true) {
+      if (requestedIsolation !== undefined) throw new Error('WORK_RELOCATION_ISOLATION_CONFLICT');
+      return relocateExistingWorkToManagedCheckout(ctx, args, session, repository, existing);
+    }
+    if (requestedIsolation !== undefined) {
+      const requestedWorkspaceMode = requestedIsolation === 'reuse' ? 'current' : 'isolated';
+      const existingWorkspaceMode = existing.managedWorktree ? 'isolated' : 'current';
+      if (requestedWorkspaceMode !== existingWorkspaceMode) {
+        throw new Error(`WORK_PREPARE_PLACEMENT_CONFLICT: ${existingId}; existing=${existingWorkspaceMode}; requested=${requestedWorkspaceMode}`);
+      }
+    }
     const adopted = adoptExplicitSuccessorHead(ctx, args, repository, existing);
     const active = adopted ?? existing;
     if (!adopted) validateWorkHandle(ctx.controllerHome, active, identityFor(ctx, args), 'cheap', 'inspect');
@@ -186,7 +290,7 @@ export function prepareWork(ctx: McpExecutionContext, args: Record<string, unkno
 
   const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
   if (!requestId) throw new Error('WORK_PREPARE_REQUEST_ID_REQUIRED: new work preparation requires request_id');
-  const isolation = args.isolation === 'reuse' || args.isolation === 'new_worktree' || args.isolation === 'auto' ? args.isolation : 'auto';
+  const isolation = requestedWorkPrepareIsolation(args) ?? 'auto';
   const objective = String(args.objective ?? 'Controller-managed repository work').trim().slice(0, 2_000);
   const goalId = typeof args.goal_id === 'string' && args.goal_id.trim() ? args.goal_id.trim() : undefined;
   const acceptanceCriteria = boundedStringArray(args.acceptance_criteria, 20);

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

@@ -27,7 +27,7 @@ function isSuccessfulWorkRepositoryProcess(
   return record.workId === input.workId
     && record.checkoutId === input.checkoutId
     && record.origin?.surface === 'command'
-    && record.origin.toolName === 'repository_command_execute'
+    && record.origin.toolName === 'execute_command'
     && record.origin.correlationId === input.workId
     && isManagedProcessTerminal(record)
     && record.terminalWritten === true
@@ -42,7 +42,7 @@ function isSuccessfulWorkRepositoryProcess(
  * Re-derive bounded completion evidence from the canonical durable Process store.
  *
  * This deliberately does not create a second evidence authority. A qualifying
- * record must be the terminal successful repository_command_execute Process for
+ * record must be the terminal successful execute_command Process for
  * the exact Work + checkout, and the command-origin correlation must still name
  * the same Work. Lightweight handles never enter listProcessRecords(), so they
  * cannot satisfy this contract.

package/src/runtime/control-plane/execution/work-terminal-cleanup.ts

@@ -170,6 +170,11 @@ function createVerifiedBundle(controllerHome: string, handle: WorkHandleState, t
   }
   const verified = git(targetRoot, ['bundle', 'verify', path], 60_000);
   if (!verified.ok) throw new Error(verified.stderr || 'git bundle verify failed');
+  const branchHead = git(targetRoot, ['rev-parse', '--verify', `refs/heads/${handle.branch}^{commit}`]);
+  const bundleHead = git(targetRoot, ['bundle', 'list-heads', path, `refs/heads/${handle.branch}`]);
+  if (!branchHead.ok || !bundleHead.ok || bundleHead.stdout !== `${branchHead.stdout} refs/heads/${handle.branch}`) {
+    throw new Error('BRANCH_BUNDLE_HEAD_MISMATCH: verified bundle does not preserve the current branch tip');
+  }
   return { path, sha256: hashText(readFileSync(path)) };
 }
 
@@ -489,9 +494,13 @@ function prepareManagedBranchPreservation(
   current: WorkHandleState,
   target: ReturnType<typeof getRepository>,
   targetBranch: string,
-): { uniqueCommits: number; branchPreserved: boolean } {
+): { uniqueCommits: number; branchPreserved: boolean; branchHead?: string } {
   let uniqueCommits = 0;
+  let branchHead: string | undefined;
   if (branchExists(target.canonicalRoot, current.branch)) {
+    const observed = git(target.canonicalRoot, ['rev-parse', '--verify', `refs/heads/${current.branch}^{commit}`]);
+    if (!observed.ok || !observed.stdout) addBlocker(receipt, 'BRANCH_REVISION_UNKNOWN');
+    else branchHead = observed.stdout;
     if (!branchExists(target.canonicalRoot, targetBranch)) {
       addBlocker(receipt, `TARGET_BRANCH_MISSING: ${targetBranch}`);
     } else {
@@ -502,11 +511,12 @@ function prepareManagedBranchPreservation(
   }
   receipt.branchCleanup.uniqueCommits = uniqueCommits;
 
+  const retirement = receipt.preservation.bundleRetirement;
   let branchPreserved = Boolean(
-    receipt.preservation.bundleRetirement?.status === 'not_needed'
-    || receipt.preservation.bundleRetirement?.status === 'removed',
+    branchHead && retirement?.protectedRevision === branchHead
+    && (retirement.status === 'not_needed' || retirement.status === 'removed'),
   );
-  if (receipt.preservation.bundlePath && !branchPreserved) {
+  if (branchHead && receipt.preservation.bundlePath && !branchPreserved) {
     try {
       const bundle = createVerifiedBundle(input.controllerHome, current, target.canonicalRoot);
       if (receipt.preservation.bundleSha256 && receipt.preservation.bundleSha256 !== bundle.sha256) {
@@ -519,7 +529,7 @@ function prepareManagedBranchPreservation(
     }
   }
   if (uniqueCommits > 0 && !branchPreserved && receipt.blockers.length === 0) {
-    const proof = proveWorkPreservationContained(target.canonicalRoot, { ...current, cleanupReceipt: receipt }, targetBranch);
+    const proof = proveWorkPreservationContained(target.canonicalRoot, current, targetBranch, branchHead);
     if (proof.contained) {
       receipt.preservation.bundleRetirement = {
         status: 'not_needed',
@@ -547,7 +557,7 @@ function prepareManagedBranchPreservation(
       }
     }
   }
-  return { uniqueCommits, branchPreserved };
+  return { uniqueCommits, branchPreserved, branchHead };
 }
 
 function applyManagedBranchCleanup(
@@ -559,6 +569,7 @@ function applyManagedBranchCleanup(
   receipt: WorkCleanupReceipt,
   uniqueCommits: number,
   branchPreserved: boolean,
+  expectedBranchHead: string | undefined,
 ): void {
   if (!deleteBranch) {
     receipt.branchCleanup.status = 'retained';
@@ -578,6 +589,10 @@ function applyManagedBranchCleanup(
     receipt.branchCleanup.status = 'retained';
     receipt.branchCleanup.reason = 'Unique commits are not archived.';
     addBlocker(receipt, `BRANCH_UNPRESERVED: ${current.branch}`);
+  } else if (!expectedBranchHead) {
+    receipt.branchCleanup.status = 'retained';
+    receipt.branchCleanup.reason = 'Exact branch revision is unavailable.';
+    addBlocker(receipt, 'BRANCH_REVISION_UNKNOWN');
   } else {
     // Branch deletion requires the canonical OwnedResource witness in addition
     // to Git relation checks. Repository/ref shape alone is not cleanup authority.
@@ -594,12 +609,10 @@ function applyManagedBranchCleanup(
       addBlocker(receipt, `OWNED_BRANCH_CLEANUP_FENCED: ${receipt.branchCleanup.reason}`);
       return;
     }
-    // We already proved the exact branch relation against targetBranch above.
-    // `git branch -d` instead consults the checkout's current HEAD, which may be
-    // an older/stale source checkout and can falsely reject a branch that is
-    // fully contained in the explicit target branch. After that target-branch
-    // proof (or a verified archive for unique commits), delete the ref directly.
-    const deleted = git(target.canonicalRoot, ['branch', '-D', current.branch]);
+    // Delete only the exact tip whose containment or bundle was proved above.
+    // A concurrent successor must retain its ref rather than inherit an older
+    // WorkHandle or preservation receipt's deletion authority.
+    const deleted = git(target.canonicalRoot, ['update-ref', '-d', `refs/heads/${current.branch}`, expectedBranchHead]);
     if (!deleted.ok && branchExists(target.canonicalRoot, current.branch)) {
       receipt.branchCleanup.status = 'failed';
       receipt.branchCleanup.reason = deleted.stderr || 'branch delete failed';
@@ -671,6 +684,7 @@ function reconcileCleanedManagedBranchRetirement(
       receipt,
       preservation.uniqueCommits,
       preservation.branchPreserved,
+      preservation.branchHead,
     );
   } else if (receipt.branchCleanup.status === 'pending') {
     receipt.branchCleanup.status = 'retained';
@@ -975,7 +989,7 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     receipt.worktree.status = 'already_removed';
   }
 
-  const { uniqueCommits, branchPreserved } = prepareManagedBranchPreservation(
+  const { uniqueCommits, branchPreserved, branchHead } = prepareManagedBranchPreservation(
     input,
     receipt,
     current,
@@ -1049,6 +1063,7 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     receipt,
     uniqueCommits,
     branchPreserved,
+    branchHead,
   );
 
   const pruned = git(target.canonicalRoot, ['worktree', 'prune']);

package/src/runtime/control-plane/execution/work-validation-reconciler.ts

@@ -120,9 +120,13 @@ function settleInfrastructureFailure(
   handle: WorkHandleState,
   summary: string,
 ): WorkValidationReconciliation {
-  const next = transitionWorkHandle(controllerHome, handle, 'failed', {
+  // Infrastructure/receipt uncertainty invalidates validation authority,
+  // not the underlying Work. Resume the pre-validation state so the same Work
+  // can repair and retry without opening a replacement lifecycle.
+  const next = transitionWorkHandle(controllerHome, handle, handle.validationRun?.resumeState ?? 'editing', {
     finalization: { ...handle.finalization, validation: 'failed', failureCode: undefined, lastError: summary },
     validationRun: undefined,
+    validatedInputFingerprint: undefined,
     failureReason: summary,
   });
   projectWorkValidationOutcome(controllerHome, next, 'infrastructure_failure', summary);

package/src/runtime/control-plane/execution/work-verification-snapshot.ts

@@ -18,7 +18,7 @@ import {
 import { dirname, join, resolve, sep } from 'path';
 import { spawnSync } from 'child_process';
 import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
-import { globMatches, normalizeMcpRelativePath } from '../../../cli/mcp/paths';
+import { globMatches, normalizeMcpRelativePath } from '../../../../adapters/mcp/paths';
 import { sanitizeFileComponent } from '../../shared/json-files';
 import { measureReclaimablePath, RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION } from '../lifecycle-retention-metrics';
 

package/src/runtime/control-plane/facade/capability-registry.ts

@@ -647,6 +647,8 @@ export function getCoreCapabilityExecutionSchema(capabilityId: string): Record<s
             session_id: { type: 'string', minLength: 1, maxLength: 256 },
             work_id: { type: 'string', minLength: 1, maxLength: 256 },
             target_branch: { type: 'string', minLength: 1, maxLength: 512 },
+            complete_work: { type: 'boolean' },
+            allow_merge_commit: { type: 'boolean' },
           },
         },
       },

package/src/runtime/control-plane/facade/work-continuation.ts

@@ -1,5 +1,5 @@
 import type { WorkContract, WorkReconciliationRecord } from './types';
-import { redactMcpText } from '../../../cli/mcp/redaction';
+import { redactMcpText } from '../../../../adapters/mcp/redaction';
 
 export interface WorkContinuationSnapshot {
   schemaVersion: 1;