@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/recovery/maintenance-executor.ts

@@ -1,14 +1,16 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
 import { basename, dirname, join, relative, resolve } from 'path';
 import { tmpdir } from 'os';
+import { runProcess } from '../../effects/process-runner';
 import { cleanupEditSession, getEditSession, listEditSessions, reconcileEditSession } from '../../cli/editing/edit-session';
 import { ensureRepositoryRuntimeStorage, type RepositoryRuntimeStorageReport } from '../../cli/repositories/runtime-storage';
 import type { RepositoryRecord } from '../../cli/repositories/types';
 import { rebuildRepositoryProjection } from '../projections/materialized-view';
 import { getWorkContract, readWorkContractStore, transitionWorkContractPhase } from '../control-plane/facade/work-contract-store';
-import { getControllerSession } from '../control-plane/facade/controller-session-store';
+import { getControllerSession, withControllerSessionTerminalizationFence } from '../control-plane/facade/controller-session-store';
 import { listPlanContracts } from '../control-plane/facade/plan-contract-store';
 import { readRequirement } from '../control-plane/persistence/requirement-store';
+import { listControlPlaneRecords, type ControlPlaneRecord } from '../control-plane/persistence/sqlite-store';
 import { isTerminalWorkContractStatus, type WorkContract } from '../control-plane/facade/types';
 import { listSchedules } from '../workflow/schedules/store';
 import {
@@ -40,11 +42,14 @@ export type RuntimeMaintenanceCandidateKind =
   | 'runtime_storage_warning'
   | 'stale_runtime_temp_entry'
   | 'stale_work_contract'
-  | 'stale_edit_session';
+  | 'stale_edit_session'
+  | 'retained_migrated_work'
+  | 'unowned_managed_worktree';
 
 export interface RuntimeMaintenanceRepository {
   repoId: string;
   canonicalRoot: string;
+  defaultBranch?: string;
   /** Test-only or embedded-runtime override. Production defaults to system temp roots. */
   runtimeTempRoots?: string[];
 }
@@ -83,6 +88,11 @@ export interface RuntimeMaintenanceCandidate {
   deadlineAt?: string;
   suggestedAction: RuntimeMaintenanceActionId;
   ownershipStatus?: 'explicit' | 'unknown';
+  sourceControllerHome?: string;
+  objective?: string;
+  continuationPrompt?: string;
+  disposition?: 'resume_or_supersede_review' | 'completion_reconciliation' | 'ownership_reconciliation' | 'source_preservation_required';
+  sourceState?: 'no_managed_source' | 'clean_integrated' | 'dirty_worktree' | 'unintegrated_commits' | 'source_state_unknown';
 }
 
 export interface RuntimeMaintenanceSummary {
@@ -97,6 +107,8 @@ export interface RuntimeMaintenanceSummary {
   staleRuntimeTempEntries: number;
   staleWorkContracts: number;
   staleEditSessions: number;
+  retainedMigratedWork: number;
+  unownedManagedWorktrees: number;
 }
 
 export interface RuntimeMaintenanceStatus {
@@ -227,6 +239,8 @@ function summarize(candidates: RuntimeMaintenanceCandidate[]): RuntimeMaintenanc
     staleRuntimeTempEntries: candidates.filter((candidate) => candidate.kind === 'stale_runtime_temp_entry').length,
     staleWorkContracts: candidates.filter((candidate) => candidate.kind === 'stale_work_contract').length,
     staleEditSessions: candidates.filter((candidate) => candidate.kind === 'stale_edit_session').length,
+    retainedMigratedWork: candidates.filter((candidate) => candidate.kind === 'retained_migrated_work').length,
+    unownedManagedWorktrees: candidates.filter((candidate) => candidate.kind === 'unowned_managed_worktree').length,
   };
 }
 
@@ -393,6 +407,282 @@ function scanRuntimeTempCandidates(
     }));
 }
 
+interface RetainedMigratedWork {
+  migrationId: string;
+  sourceHome: string;
+  work: WorkContract;
+}
+
+interface AppliedControllerHomeMigrationRecord {
+  migrationId: string;
+  status: 'applied' | 'rolled_back';
+  sourceHome: string;
+}
+
+function listRetainedMigratedWork(destinationHomeInput: string, repoId: string): RetainedMigratedWork[] {
+  const destinationHome = resolve(destinationHomeInput);
+  const destinationWorkIds = new Set(
+    listControlPlaneRecords<WorkContract>(destinationHome, { namespace: 'work_contract', scope: repoId, limit: 5_000 })
+      .map((record) => record.key),
+  );
+  const migrations = listControlPlaneRecords<AppliedControllerHomeMigrationRecord>(destinationHome, {
+    namespace: 'controller_home_migration',
+    scope: 'controller',
+    limit: 100,
+  });
+  const retained: RetainedMigratedWork[] = [];
+  for (const record of migrations) {
+    const migration = record.value;
+    if (migration.status !== 'applied') continue;
+    const sourceHome = resolve(migration.sourceHome);
+    if (!existsSync(join(sourceHome, 'control-plane.sqlite'))) continue;
+    let sourceWork: ControlPlaneRecord<WorkContract>[];
+    try {
+      sourceWork = listControlPlaneRecords<WorkContract>(sourceHome, { namespace: 'work_contract', limit: 5_000 });
+    } catch {
+      continue;
+    }
+    for (const source of sourceWork) {
+      const work = source.value;
+      if (work.repoId !== repoId || !isTerminalWorkContractStatus(work.status)) continue;
+      if (!work.worktreeRef?.trim() || !existsSync(work.worktreeRef)) continue;
+      if (destinationWorkIds.has(work.workId)) continue;
+      retained.push({ migrationId: migration.migrationId, sourceHome, work });
+    }
+  }
+  return retained.sort((left, right) => left.work.updatedAt.localeCompare(right.work.updatedAt));
+}
+
+function gitWorktreePaths(repoRoot: string): string[] {
+  const result = runProcess('git', ['worktree', 'list', '--porcelain'], {
+    cwd: repoRoot,
+    timeoutMs: 10_000,
+    maxOutputBytes: 500_000,
+  });
+  if (!result.ok) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith('worktree '))
+    .map((line) => resolve(line.slice('worktree '.length).trim()))
+    .filter(Boolean);
+}
+
+function looksLikeForgeManagedWorktree(path: string): boolean {
+  const normalized = resolve(path).replace(/\\/g, '/');
+  return normalized.includes('/.forge/managed-worktrees/')
+    || normalized.includes('/.forge/controller/managed-worktrees/')
+    || normalized.includes('/.repo-harness/managed-worktrees/')
+    || normalized.includes('/managed-worktrees/repo_');
+}
+
+type StaleWorkSourceState = NonNullable<RuntimeMaintenanceCandidate['sourceState']>;
+
+interface StaleWorkSourceInspection {
+  safeToCancel: boolean;
+  state: StaleWorkSourceState;
+  path?: string;
+  detail: string;
+}
+
+function inspectStaleWorkRepositorySource(
+  repository: RuntimeMaintenanceRepository,
+  contract: WorkContract,
+): StaleWorkSourceInspection {
+  const recordedPath = contract.worktreeRef?.trim();
+  if (!recordedPath) {
+    return {
+      safeToCancel: true,
+      state: 'no_managed_source',
+      detail: 'Work has no recorded managed worktree source.',
+    };
+  }
+  const path = resolve(recordedPath);
+  if (!looksLikeForgeManagedWorktree(path)) {
+    return {
+      safeToCancel: true,
+      state: 'no_managed_source',
+      path,
+      detail: 'Recorded Work path is not a Forge-managed worktree and is not disposable maintenance source.',
+    };
+  }
+  if (!existsSync(path)) {
+    return {
+      safeToCancel: false,
+      state: 'source_state_unknown',
+      path,
+      detail: 'Recorded managed worktree path is absent, so maintenance cannot prove that no unique branch/source remains recoverable through Git or checkout metadata; destructive stale-Work cancellation is fenced.',
+    };
+  }
+
+  const status = runProcess('git', ['status', '--porcelain', '--untracked-files=all'], {
+    cwd: path,
+    timeoutMs: 10_000,
+    maxOutputBytes: 500_000,
+  });
+  if (!status.ok) {
+    return {
+      safeToCancel: false,
+      state: 'source_state_unknown',
+      path,
+      detail: `Managed worktree source state could not be read (${status.stderr || 'git status failed'}); destructive stale-Work cancellation is fenced.`,
+    };
+  }
+  if (status.stdout.trim()) {
+    return {
+      safeToCancel: false,
+      state: 'dirty_worktree',
+      path,
+      detail: 'Managed worktree contains uncommitted or untracked repository source; durable metadata/process evidence is not a substitute for preserving the live source checkout.',
+    };
+  }
+
+  const head = runProcess('git', ['rev-parse', 'HEAD'], {
+    cwd: path,
+    timeoutMs: 10_000,
+    maxOutputBytes: 100_000,
+  });
+  const targetBranch = repository.defaultBranch?.trim() || 'main';
+  const target = runProcess('git', ['rev-parse', '--verify', `refs/heads/${targetBranch}`], {
+    cwd: repository.canonicalRoot,
+    timeoutMs: 10_000,
+    maxOutputBytes: 100_000,
+  });
+  if (!head.ok || !head.stdout.trim() || !target.ok || !target.stdout.trim()) {
+    return {
+      safeToCancel: false,
+      state: 'source_state_unknown',
+      path,
+      detail: `Managed worktree HEAD or target branch ${targetBranch} could not be resolved; destructive stale-Work cancellation is fenced.`,
+    };
+  }
+  const unique = runProcess('git', ['rev-list', '--count', `${target.stdout.trim()}..${head.stdout.trim()}`], {
+    cwd: repository.canonicalRoot,
+    timeoutMs: 10_000,
+    maxOutputBytes: 100_000,
+  });
+  if (!unique.ok || !/^\d+$/.test(unique.stdout.trim())) {
+    return {
+      safeToCancel: false,
+      state: 'source_state_unknown',
+      path,
+      detail: 'Managed worktree unique-commit state could not be proven; destructive stale-Work cancellation is fenced.',
+    };
+  }
+  if (Number(unique.stdout.trim()) > 0) {
+    return {
+      safeToCancel: false,
+      state: 'unintegrated_commits',
+      path,
+      detail: `Managed worktree HEAD has ${unique.stdout.trim()} commit(s) not reachable from ${targetBranch}; explicit semantic adoption or cleanup authority is required.`,
+    };
+  }
+  return {
+    safeToCancel: true,
+    state: 'clean_integrated',
+    path,
+    detail: `Managed worktree is clean and its HEAD is already reachable from ${targetBranch}.`,
+  };
+}
+
+function staleWorkCandidateReason(source: StaleWorkSourceInspection): string {
+  return source.safeToCancel
+    ? `Nonterminal WorkContract exceeded the explicit maintenance age threshold and has no active Plan, Requirement, Schedule, or Controller authority. ${source.detail} Explicit full maintenance may cancel Work metadata while retaining durable evidence.`
+    : `Protected stale Work: no active lifecycle authority remains, but repository source preservation is required. ${source.detail} The Work must remain nonterminal until source is explicitly adopted, delivered, or cleanup is semantically authorized.`;
+}
+
+function scanRetainedWorktreeCandidates(
+  repository: RuntimeMaintenanceRepository,
+  controllerHome: string,
+  maxCandidates: number,
+): RuntimeMaintenanceCandidate[] {
+  const worktreePaths = gitWorktreePaths(repository.canonicalRoot);
+  if (worktreePaths.length === 0) return [];
+  const normalizedInventory = new Set(worktreePaths.map((path) => resolve(path)));
+  const currentContracts = readWorkContractStore({ controllerHome, repoId: repository.repoId }).contracts;
+  const currentOwnedPaths = new Set(
+    currentContracts
+      .map((contract) => contract.worktreeRef?.trim())
+      .filter((path): path is string => Boolean(path))
+      .map((path) => resolve(path)),
+  );
+  const candidates: RuntimeMaintenanceCandidate[] = [];
+  const retained = listRetainedMigratedWork(controllerHome, repository.repoId);
+  const retainedByPath = new Map(retained.map((entry) => [resolve(entry.work.worktreeRef!), entry]));
+
+  for (const path of worktreePaths) {
+    const normalized = resolve(path);
+    if (normalized === resolve(repository.canonicalRoot) || currentOwnedPaths.has(normalized)) continue;
+    const migrated = retainedByPath.get(normalized);
+    if (migrated) {
+      const completed = migrated.work.status === 'completed';
+      candidates.push({
+        kind: 'retained_migrated_work',
+        id: migrated.work.workId,
+        path: normalized,
+        status: migrated.work.status,
+        safe: false,
+        reason: completed
+          ? 'A terminal Work from a retired Controller Home still owns a Git worktree and requires completion/cleanup reconciliation under the current Controller before lifecycle health can be reported.'
+          : 'A terminal Work from a retired Controller Home still owns preserved implementation state in a Git worktree. Review and explicitly resume or supersede it under current authority; automatic maintenance must not delete it.',
+        suggestedAction: 'full_maintenance_pass',
+        ownershipStatus: 'explicit',
+        sourceControllerHome: migrated.sourceHome,
+        objective: migrated.work.objective,
+        continuationPrompt: migrated.work.continuationPrompt,
+        disposition: completed ? 'completion_reconciliation' : 'resume_or_supersede_review',
+      });
+      continue;
+    }
+    if (!looksLikeForgeManagedWorktree(normalized)) continue;
+    candidates.push({
+      kind: 'unowned_managed_worktree',
+      id: `managed-worktree:${basename(normalized)}`,
+      path: normalized,
+      safe: false,
+      reason: 'Git reports a Forge-managed worktree for this repository, but the current Controller has no WorkContract ownership and no retained migration identity for it. Ownership must be reconciled before lifecycle health can be reported.',
+      suggestedAction: 'full_maintenance_pass',
+      ownershipStatus: 'unknown',
+      disposition: 'ownership_reconciliation',
+    });
+  }
+
+  // A retained migrated Work whose referenced path still exists but is no longer
+  // in Git inventory remains preservation debt rather than disappearing silently.
+  for (const migrated of retained) {
+    const normalized = resolve(migrated.work.worktreeRef!);
+    if (normalizedInventory.has(normalized) || currentOwnedPaths.has(normalized)) continue;
+    // Legacy WorkContract records sometimes stored the repository checkout/root
+    // in worktreeRef even though it was not a Controller-managed worktree. Such
+    // historical references remain audit evidence, but must not turn every old
+    // repository root into current lifecycle debt. Only known Forge/RepoHarness
+    // managed-worktree storage can represent preserved implementation here.
+    if (!looksLikeForgeManagedWorktree(normalized)) continue;
+    // A removed legacy campaign may leave an empty managed-storage directory
+    // behind after its Git metadata and contents are already gone. That is not
+    // preserved implementation and must not block lifecycle health. A retained
+    // path outside current Git inventory only remains lifecycle debt when its
+    // worktree .git marker still exists for manual reconciliation.
+    if (!existsSync(join(normalized, '.git'))) continue;
+    const completed = migrated.work.status === 'completed';
+    candidates.push({
+      kind: 'retained_migrated_work',
+      id: migrated.work.workId,
+      path: normalized,
+      status: migrated.work.status,
+      safe: false,
+      reason: 'A terminal Work retained by a migrated Controller Home still has preserved filesystem state, but Git no longer reports it as a registered worktree. Manual lifecycle reconciliation is required; automatic cleanup is forbidden.',
+      suggestedAction: 'full_maintenance_pass',
+      ownershipStatus: 'explicit',
+      sourceControllerHome: migrated.sourceHome,
+      objective: migrated.work.objective,
+      continuationPrompt: migrated.work.continuationPrompt,
+      disposition: completed ? 'completion_reconciliation' : 'resume_or_supersede_review',
+    });
+  }
+
+  return candidates.slice(0, maxCandidates);
+}
+
 function normalizedOptions(options: RuntimeMaintenanceOptions = {}): Required<RuntimeMaintenanceOptions> {
   return {
     minAgeMinutes: clampNumber(options.minAgeMinutes, DEFAULT_MIN_AGE_MINUTES, 0, 7 * 24 * 60),
@@ -438,23 +728,107 @@ function scanStaleWorkContractCandidates(
       return { contract, ageMinutes };
     })
     .filter(({ ageMinutes }) => ageMinutes >= options.minAgeMinutes)
+    .flatMap(({ contract, ageMinutes }) => {
+      const authorityRefs = activeWorkAuthorityRefs(repository, controllerHome, contract);
+      // A live Plan/Requirement/Schedule/Controller reference is lifecycle authority,
+      // not maintenance debt. Keep the Work fenced until that authority disappears;
+      // if it later becomes unowned, the next scan will surface it as stale.
+      if (authorityRefs.length > 0) return [];
+      return [{ contract, ageMinutes, source: inspectStaleWorkRepositorySource(repository, contract) }];
+    })
     .sort((left, right) => right.ageMinutes - left.ageMinutes)
     .slice(0, options.maxCandidates)
-    .map(({ contract, ageMinutes }) => {
-      const authorityRefs = activeWorkAuthorityRefs(repository, controllerHome, contract);
+    .map(({ contract, ageMinutes, source }) => ({
+      kind: 'stale_work_contract' as const,
+      id: contract.workId,
+      path: source.path,
+      status: contract.status,
+      safe: source.safeToCancel,
+      reason: staleWorkCandidateReason(source),
+      ageMinutes,
+      suggestedAction: 'full_maintenance_pass' as const,
+      ownershipStatus: 'explicit' as const,
+      sourceState: source.state,
+      disposition: source.safeToCancel ? undefined : ('source_preservation_required' as const),
+    }));
+}
+
+export function applyStaleWorkContractMaintenanceCandidate(
+  repository: RuntimeMaintenanceRepository,
+  controllerHome: string,
+  candidate: RuntimeMaintenanceCandidate,
+): RuntimeMaintenanceCandidate & { applied: boolean; result: string } {
+  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, candidate.id);
+  if (!work || isTerminalWorkContractStatus(work.status)) {
+    return { ...candidate, applied: false, result: 'already_terminal' };
+  }
+
+  // The stale scan is discovery only. Re-evaluate every non-Controller authority
+  // while holding the canonical ControllerSession lock, then perform the Work
+  // transition before releasing it. A newer controller_claim therefore either
+  // wins the lock first and fences this mutation, or starts only after an already
+  // completed maintenance terminalization; there is no check-then-cancel gap.
+  const fenced = withControllerSessionTerminalizationFence(
+    { controllerHome, repoId: repository.repoId },
+    { workId: work.workId, actor: `runtime-maintenance-terminalize:${work.workId}` },
+    () => {
+      const current = getWorkContract({ controllerHome, repoId: repository.repoId }, work.workId);
+      if (!current || isTerminalWorkContractStatus(current.status)) {
+        return { ...candidate, applied: false, result: 'already_terminal' };
+      }
+      const authorityRefs = activeWorkAuthorityRefs(repository, controllerHome, current);
+      if (authorityRefs.length > 0) {
+        return {
+          ...candidate,
+          applied: false,
+          result: `work_authority_became_active:${authorityRefs.join(',')}`,
+        };
+      }
+      // Discovery and mutation are separated by an arbitrary Controller/MCP delay.
+      // Re-probe the live worktree while the canonical ControllerSession fence is
+      // held so neither a newer Controller claim nor a late source write can be
+      // raced by stale maintenance terminalization.
+      const source = inspectStaleWorkRepositorySource(repository, current);
+      if (!source.safeToCancel) {
+        return {
+          ...candidate,
+          path: source.path ?? candidate.path,
+          safe: false,
+          reason: staleWorkCandidateReason(source),
+          sourceState: source.state,
+          disposition: 'source_preservation_required' as const,
+          applied: false,
+          result: `work_source_preserved:${source.state}`,
+        };
+      }
+      transitionWorkContractPhase({ controllerHome, repoId: repository.repoId }, current.workId, {
+        phase: 'cleanup',
+        status: 'cancelled',
+        state: 'skipped',
+        summary: 'Cancelled by explicit full maintenance stale Work cleanup after proving no unique live repository source; durable evidence retained.',
+        evidenceRefs: current.evidenceRefs,
+      });
       return {
-        kind: 'stale_work_contract' as const,
-        id: contract.workId,
-        status: contract.status,
-        safe: authorityRefs.length === 0,
-        reason: authorityRefs.length > 0
-          ? `Nonterminal WorkContract is old but still has active lifecycle authority (${authorityRefs.join(', ')}); maintenance must not cancel it from age alone.`
-          : 'Nonterminal WorkContract exceeded the explicit maintenance age threshold and has no active Plan, Requirement, Schedule, or Controller authority; explicit full maintenance may cancel it while retaining evidence.',
-        ageMinutes,
-        suggestedAction: 'full_maintenance_pass' as const,
-        ownershipStatus: 'explicit' as const,
+        ...candidate,
+        path: source.path ?? candidate.path,
+        safe: true,
+        reason: staleWorkCandidateReason(source),
+        sourceState: source.state,
+        disposition: undefined,
+        applied: true,
+        result: 'work_contract_cancelled_evidence_retained',
       };
-    });
+    },
+  );
+  if (!fenced.allowed) {
+    const generation = fenced.owner?.claimGeneration;
+    return {
+      ...candidate,
+      applied: false,
+      result: `work_terminalization_fenced:${fenced.reason}${typeof generation === 'number' ? `:claim_generation=${generation}` : ''}`,
+    };
+  }
+  return fenced.value;
 }
 
 function scanStaleEditSessionCandidates(
@@ -552,7 +926,8 @@ export function buildRuntimeMaintenanceStatus(
   const tempCandidates = scanRuntimeTempCandidates(repository, normalized.maxCandidates);
   const staleWorkCandidates = scanStaleWorkContractCandidates(repository, controllerHome, normalized);
   const staleEditCandidates = scanStaleEditSessionCandidates(repository, controllerHome, normalized);
-  const candidates = [...localJobCandidates, ...storageCandidates, ...staleWorkCandidates, ...staleEditCandidates, ...tempCandidates].slice(0, normalized.maxCandidates);
+  const retainedWorktreeCandidates = scanRetainedWorktreeCandidates(repository, controllerHome, normalized.maxCandidates);
+  const candidates = [...localJobCandidates, ...storageCandidates, ...staleWorkCandidates, ...staleEditCandidates, ...retainedWorktreeCandidates, ...tempCandidates].slice(0, normalized.maxCandidates);
   const summary = summarize(candidates);
   const blockingCandidates = candidates.filter((candidate) => candidate.kind !== 'stale_runtime_temp_entry');
   const readyForExecution = storage.report?.readyForExecution === true
@@ -588,6 +963,7 @@ export function buildRuntimeMaintenanceStatus(
       'Pending approvals are not cancelled unless cancel_pending_approvals is explicitly enabled.',
       'System temp cleanup only removes direct forge-prefixed children of approved temp roots after a 24-hour retention period and a fresh process-occupancy check.',
       'Runtime lifecycle changes and source repair are outside the runtime maintenance executor.',
+      'Retained or unowned managed worktrees are review-only lifecycle blockers. Runtime maintenance never deletes or modifies their preserved implementation state.',
     ],
   };
 }
@@ -806,18 +1182,7 @@ export function applyRuntimeMaintenance(
         };
       }
       if (candidate.kind === 'stale_work_contract') {
-        const work = getWorkContract({ controllerHome, repoId: repository.repoId }, candidate.id);
-        if (!work || isTerminalWorkContractStatus(work.status)) {
-          return { ...candidate, applied: false, result: 'already_terminal' };
-        }
-        transitionWorkContractPhase({ controllerHome, repoId: repository.repoId }, work.workId, {
-          phase: 'cleanup',
-          status: 'cancelled',
-          state: 'skipped',
-          summary: 'Cancelled by explicit full maintenance stale Work cleanup; durable evidence retained.',
-          evidenceRefs: work.evidenceRefs,
-        });
-        return { ...candidate, applied: true, result: 'work_contract_cancelled_evidence_retained' };
+        return applyStaleWorkContractMaintenanceCandidate(repository, controllerHome, candidate);
       }
       if (candidate.kind === 'stale_edit_session') {
         const cleaned = cleanupEditSession(repository.canonicalRoot, candidate.id, {