@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/control-plane/runtime-cleanup.ts

@@ -8,7 +8,7 @@ import {
   rmSync,
   type Dirent,
 } from 'fs';
-import { join, relative, resolve } from 'path';
+import { basename, dirname, join, relative, resolve } from 'path';
 import { ensureControllerHome } from '../../cli/repositories/controller-home';
 import { cleanupTerminalEditSessionRecords } from '../../cli/editing/edit-session';
 import { listRepositories } from '../../cli/repositories/registry';
@@ -17,7 +17,8 @@ import { migrateManagedWorkspacePhysicalDependenciesToCanonical } from '../execu
 import { cleanupStaleCodegraphLocators } from '../context/codegraph-cache-boundary';
 import { listActiveLeases } from '../resources/leases/store';
 import { cleanupScheduleOccurrenceHistory } from '../../../packages/kernel/scheduler/api/index';
-import { isTerminalWorkContractStatus, readWorkContractStore } from '../../../packages/kernel/work/api/index';
+import { isTerminalSemanticWorkState, readWorkContractStore } from '../../../packages/kernel/work/api/index';
+import { assertOwnedResourceCleanupTarget, listOwnedResources, markOwnedResourceCleaned, type OwnedResource } from '../../../packages/kernel/identity/api/index';
 import { appendJsonLine, readJsonFile, writeJsonAtomic } from '../shared/json-files';
 import { cleanupControllerReleaseHistory } from './release-retention';
 import { cleanupWorkPreservationArtifacts } from './cleanup-artifact-retention';
@@ -25,12 +26,17 @@ import { cleanupCodegraphCaches, CODEGRAPH_CACHE_RETENTION_POLICY_VERSION } from
 import { cleanupRetiredRepositoryNamespaces } from './repository-namespace-retention';
 import { maintainControlPlaneDatabase, type ControlPlaneDatabaseMaintenanceReport } from './persistence/sqlite-store';
 import { cleanupExpiredExperiences } from './persistence/experience-store';
-import { retireTerminalPlanBoundWorkAuthorities } from './facade/plan-contract-store';
 import { reconcileOwnerlessWorkAuthorities } from './execution/work-authority-reconciler';
 import {
   measureReclaimablePath,
   RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION,
 } from './lifecycle-retention-metrics';
+import {
+  listReleaseSessions,
+  releaseSessionCandidateIsRetired,
+} from '../release/release-session';
+import { removeRetiredCandidateExecutionLane } from '../root/runtime-lane';
+import { observeRuntimeStatus } from '../root/status';
 
 function numericSetting(value: string | undefined, fallback: number, minimum: number): number {
   const parsed = Number(value);
@@ -193,6 +199,35 @@ export interface RuntimeCleanupLifecycleMetrics {
   blockerReasons: Record<string, number>;
 }
 
+export interface ReleaseSessionCandidatePhaseMetrics {
+  observedCount: number;
+  observedBytes: number;
+  unknownObservedByteCount: number;
+  retainedCount: number;
+  reclaimableCount: number;
+  removedCount: number;
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+}
+
+export interface ReleaseSessionCandidateRetentionReport {
+  inspected: number;
+  observedCount: number;
+  observedBytes: number;
+  unknownObservedByteCount: number;
+  retainedCount: number;
+  eligible: number;
+  attempted: number;
+  removedPaths: string[];
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  orphanDirectoryCount: number;
+  invalidSessionFiles: string[];
+  byPhase: Record<string, ReleaseSessionCandidatePhaseMetrics>;
+  errors: string[];
+  truncated: boolean;
+}
+
 export interface RuntimeCleanupReport {
   policyVersion: typeof RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION;
   at: string;
@@ -204,6 +239,7 @@ export interface RuntimeCleanupReport {
   removedTemporaryPaths: string[];
   removedCleanupArtifactPaths: string[];
   removedReleasePaths: string[];
+  releaseSessionCandidates: ReleaseSessionCandidateRetentionReport;
   removedScheduleOccurrencePaths: string[];
   removedScheduleDecisionPaths: string[];
   removedEditSessionPaths: string[];
@@ -212,8 +248,6 @@ export interface RuntimeCleanupReport {
   removedRepositoryNamespacePaths: string[];
   /** Physical SQLite checkpoint/compaction receipt; row lifecycle remains domain-owned. */
   sqliteMaintenance?: ControlPlaneDatabaseMaintenanceReport;
-  /** Historical non-terminal Work whose owning Plan was already terminal. Records remain for retention/audit. */
-  retiredPlanBoundWorkAuthorities: string[];
   /** Work retired only after exact per-Work liveness proved no durable continuation owner remains. */
   retiredOwnerlessWorkAuthorities: string[];
   skippedActiveWorktrees: string[];
@@ -456,6 +490,203 @@ function createScanBudget(maxEntries: number): ScanBudget {
   };
 }
 
+function emptyReleaseSessionCandidatePhaseMetrics(): ReleaseSessionCandidatePhaseMetrics {
+  return {
+    observedCount: 0,
+    observedBytes: 0,
+    unknownObservedByteCount: 0,
+    retainedCount: 0,
+    reclaimableCount: 0,
+    removedCount: 0,
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+  };
+}
+
+function emptyReleaseSessionCandidateRetentionReport(): ReleaseSessionCandidateRetentionReport {
+  return {
+    inspected: 0,
+    observedCount: 0,
+    observedBytes: 0,
+    unknownObservedByteCount: 0,
+    retainedCount: 0,
+    eligible: 0,
+    attempted: 0,
+    removedPaths: [],
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    orphanDirectoryCount: 0,
+    invalidSessionFiles: [],
+    byPhase: {},
+    errors: [],
+    truncated: false,
+  };
+}
+
+function candidatePhaseMetrics(
+  report: ReleaseSessionCandidateRetentionReport,
+  phase: string,
+): ReleaseSessionCandidatePhaseMetrics {
+  return report.byPhase[phase] ??= emptyReleaseSessionCandidatePhaseMetrics();
+}
+
+/**
+ * Physical retention only. ReleaseSession phase transitions and Candidate
+ * service retirement remain owned by standalone Recovery under its operation
+ * lock. Maintenance consumes durable phase evidence and the live Runtime owner
+ * projection, then applies the existing path-fenced Candidate removal.
+ */
+function cleanupReleaseSessionCandidateLanes(
+  controllerHome: string,
+  input: {
+    maxEntries: number;
+    sequence: number;
+    removalBudget: RemovalBudget;
+    skippedByReason: Record<string, number>;
+  },
+): ReleaseSessionCandidateRetentionReport {
+  const report = emptyReleaseSessionCandidateRetentionReport();
+  const candidateRoot = resolve(dirname(controllerHome), 'candidate-runtime-lanes');
+  const inventory = listReleaseSessions(controllerHome, { maxEntries: input.maxEntries });
+  report.invalidSessionFiles = [...inventory.invalidSessionFiles].sort();
+  report.inspected += inventory.inspected;
+  report.truncated = inventory.truncated;
+  if (inventory.truncated) {
+    input.skippedByReason.release_session_candidate_inventory_truncated =
+      (input.skippedByReason.release_session_candidate_inventory_truncated ?? 0) + 1;
+  }
+  if (inventory.invalidSessionFiles.length > 0) {
+    input.skippedByReason.release_session_candidate_authority_invalid =
+      (input.skippedByReason.release_session_candidate_authority_invalid ?? 0) + inventory.invalidSessionFiles.length;
+    report.errors.push(...inventory.invalidSessionFiles.map((name) => `invalid ReleaseSession authority: ${name}`));
+  }
+
+  const measurementBudget = createScanBudget(input.maxEntries);
+  const knownCandidateHomes = new Set<string>();
+  const sessions = [...inventory.sessions].sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+  if (sessions.length > 1) {
+    const offset = ((Math.trunc(input.sequence) % sessions.length) + sessions.length) % sessions.length;
+    sessions.push(...sessions.splice(0, offset));
+  }
+
+  for (const session of sessions) {
+    const candidateHome = resolve(session.candidate.controllerHome);
+    if (resolve(dirname(candidateHome)) !== candidateRoot || basename(candidateHome) !== session.sessionId) {
+      input.skippedByReason.release_session_candidate_path_invalid =
+        (input.skippedByReason.release_session_candidate_path_invalid ?? 0) + 1;
+      report.errors.push(`${session.sessionId}: RUNTIME_CANDIDATE_CLEANUP_PATH_INVALID`);
+      continue;
+    }
+    knownCandidateHomes.add(candidateHome);
+    if (!existsSync(candidateHome)) continue;
+
+    const phase = candidatePhaseMetrics(report, session.phase);
+    report.observedCount += 1;
+    phase.observedCount += 1;
+
+    let measuredBytes: number | undefined;
+    let measurementComplete = false;
+    if (measurementBudget.remaining > 0) {
+      const measurement = measureReclaimablePath(candidateHome, Math.min(256, measurementBudget.remaining));
+      measurementBudget.remaining = Math.max(0, measurementBudget.remaining - measurement.entries);
+      measurementBudget.inspected += measurement.entries;
+      measuredBytes = measurement.bytes;
+      measurementComplete = measurement.complete;
+    }
+    if (measurementComplete && measuredBytes !== undefined) {
+      report.observedBytes += measuredBytes;
+      phase.observedBytes += measuredBytes;
+    } else {
+      report.unknownObservedByteCount += 1;
+      phase.unknownObservedByteCount += 1;
+    }
+
+    if (!releaseSessionCandidateIsRetired(session)) {
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      input.skippedByReason.release_session_candidate_resumable =
+        (input.skippedByReason.release_session_candidate_resumable ?? 0) + 1;
+      continue;
+    }
+
+    report.eligible += 1;
+    phase.reclaimableCount += 1;
+    try {
+      if (observeRuntimeStatus(candidateHome).running) {
+        report.retainedCount += 1;
+        phase.retainedCount += 1;
+        input.skippedByReason.release_session_candidate_active_owner =
+          (input.skippedByReason.release_session_candidate_active_owner ?? 0) + 1;
+        continue;
+      }
+    } catch (error) {
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      report.errors.push(errorText(`${session.sessionId} Candidate Runtime observation`, error));
+      input.skippedByReason.release_session_candidate_owner_unknown =
+        (input.skippedByReason.release_session_candidate_owner_unknown ?? 0) + 1;
+      continue;
+    }
+
+    if (input.removalBudget.remaining <= 0) {
+      input.removalBudget.exhausted = true;
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      input.skippedByReason.release_session_candidate_cleanup_budget_exhausted =
+        (input.skippedByReason.release_session_candidate_cleanup_budget_exhausted ?? 0) + 1;
+      continue;
+    }
+
+    report.attempted += 1;
+    input.removalBudget.remaining -= 1;
+    try {
+      removeRetiredCandidateExecutionLane(session.stable, session.candidate);
+      const relativePath = `candidate-runtime-lanes/${session.sessionId}`;
+      report.removedPaths.push(relativePath);
+      phase.removedCount += 1;
+      if (measurementComplete && measuredBytes !== undefined) {
+        report.reclaimedBytes += measuredBytes;
+        phase.reclaimedBytes += measuredBytes;
+      } else {
+        report.unknownReclaimedByteCount += 1;
+        phase.unknownReclaimedByteCount += 1;
+      }
+    } catch (error) {
+      report.retainedCount += 1;
+      phase.retainedCount += 1;
+      report.errors.push(errorText(`${session.sessionId} Candidate lane removal`, error));
+    }
+  }
+
+  // A directory without readable ReleaseSession authority is visible debt, not
+  // deletion authority. Keep it and report it so Recovery can reconcile it.
+  if (!inventory.truncated && existsSync(candidateRoot)) {
+    const rootBudget = createScanBudget(input.maxEntries);
+    visitDirectoryEntries(candidateRoot, rootBudget, report.errors, (entry) => {
+      if (!entry.isDirectory()) return;
+      const path = resolve(candidateRoot, entry.name);
+      if (knownCandidateHomes.has(path)) return;
+      report.observedCount += 1;
+      report.retainedCount += 1;
+      report.orphanDirectoryCount += 1;
+      report.unknownObservedByteCount += 1;
+      const phase = candidatePhaseMetrics(report, 'authority_missing');
+      phase.observedCount += 1;
+      phase.retainedCount += 1;
+      phase.unknownObservedByteCount += 1;
+      input.skippedByReason.release_session_candidate_authority_missing =
+        (input.skippedByReason.release_session_candidate_authority_missing ?? 0) + 1;
+    });
+    report.inspected += rootBudget.inspected;
+    if (rootBudget.exhausted) report.truncated = true;
+  }
+
+  report.inspected += measurementBudget.inspected;
+  report.removedPaths.sort();
+  report.errors.sort();
+  return report;
+}
+
 function shouldProtectWorktreeReference(meta: AgentRunSnapshot, nowMs: number): boolean {
   if (meta.executionMode !== 'worktree' || meta.worktreeCleanedAt) return false;
   const status = typeof meta.status === 'string' ? meta.status.trim().toLowerCase() : '';
@@ -609,6 +840,11 @@ function cleanupOrphanWorktrees(
   const reclaim = emptyReclaimMetrics();
   const skippedByReason: Record<string, number> = {};
   const skip = (reason: string): void => { skippedByReason[reason] = (skippedByReason[reason] ?? 0) + 1; };
+  const ownedWorktreesByPath = new Map<string, OwnedResource>();
+  for (const resource of listOwnedResources(controllerHome, { kind: 'worktree', status: 'active' })) {
+    if (resource.cleanupCapable !== true || !resource.targetRef?.trim()) continue;
+    ownedWorktreesByPath.set(canonicalPath(resource.targetRef), resource);
+  }
   const repositoriesRoot = join(controllerHome, 'repositories');
   visitDirectoryEntries(repositoriesRoot, budget, errors, (repoEntry) => {
     if (!repoEntry.isDirectory()) return;
@@ -624,7 +860,25 @@ function cleanupOrphanWorktrees(
         skip(references.referenced.has(canonical) ? 'active_owner' : 'unknown_ownership');
         return;
       }
+      const ownedResource = ownedWorktreesByPath.get(canonical);
+      if (!ownedResource) {
+        skippedActive.push(relativePath);
+        skip('owned_resource_missing');
+        return;
+      }
       try {
+        try {
+          assertOwnedResourceCleanupTarget(controllerHome, {
+            resourceId: ownedResource.resourceId,
+            kind: 'worktree',
+            targetRef: path,
+          });
+        } catch (error) {
+          skippedActive.push(relativePath);
+          skip('owned_resource_identity_mismatch');
+          errors.push(errorText(`owned worktree cleanup fence ${relativePath}`, error));
+          return;
+        }
         if (nowMs - lstatSync(path).mtimeMs < ORPHAN_WORKTREE_TTL_MS) {
           skip('ttl_not_expired');
           return;
@@ -638,6 +892,7 @@ function cleanupOrphanWorktrees(
         const measurement = measureReclaimablePath(path);
         if (removeOrphanWorktreeDirectory(path, errors, relativePath)) {
           removed.push(relativePath);
+          markOwnedResourceCleaned(controllerHome, ownedResource.resourceId, 'forge:runtime-orphan-worktree-cleanup');
           if (measurement.complete) reclaim.reclaimedBytes += measurement.bytes;
           else reclaim.unknownReclaimedByteCount += 1;
         }
@@ -802,12 +1057,12 @@ function shouldPersistCleanupAudit(report: RuntimeCleanupReport): boolean {
     || report.removedTemporaryPaths.length
     || report.removedCleanupArtifactPaths.length
     || report.removedReleasePaths.length
+    || report.releaseSessionCandidates.removedPaths.length
     || report.removedCodegraphLocatorPaths.length
     || report.removedCodegraphCachePaths.length
     || report.removedRepositoryNamespacePaths.length
     || report.sqliteMaintenance?.vacuumed
     || report.sqliteMaintenance?.skippedReason === 'database_busy'
-    || report.retiredPlanBoundWorkAuthorities.length
     || report.retiredOwnerlessWorkAuthorities.length,
   );
   if (hadMutations || report.errors.length) return true;
@@ -839,14 +1094,12 @@ export function cleanupControllerRuntimeState(
   const errors: string[] = [];
   const skippedByReason: Record<string, number> = {};
   const sequence = options.periodicSequence ?? Math.floor(nowMs / 60_000);
+  const removalCycleSequence = Math.floor(sequence / REMOVAL_PHASES.length);
   const removalPhases = cleanupRemovalPhaseOrder(options.reason ?? 'manual', sequence);
   const periodic = (options.reason ?? 'manual') === 'periodic';
-  const retiredPlanBoundWorkAuthorities: string[] = [];
   const retiredOwnerlessWorkAuthorities: string[] = [];
   if (!periodic || removalPhases.includes('repository_namespaces')) try {
     for (const repository of listRepositories(home, { includeRemoved: true })) {
-      const retired = retireTerminalPlanBoundWorkAuthorities({ controllerHome: home, repoId: repository.repoId });
-      retiredPlanBoundWorkAuthorities.push(...retired.map((workId) => `${repository.repoId}:${workId}`));
       const ownerless = reconcileOwnerlessWorkAuthorities({
         controllerHome: home,
         repoId: repository.repoId,
@@ -870,6 +1123,7 @@ export function cleanupControllerRuntimeState(
   let temporaryCleanup: ReturnType<typeof cleanupTemporaryStatePaths> | undefined;
   let artifactRetention: ReturnType<typeof cleanupWorkPreservationArtifacts> | undefined;
   let releaseRetention: ReturnType<typeof cleanupControllerReleaseHistory> | undefined;
+  let releaseSessionCandidates: ReleaseSessionCandidateRetentionReport | undefined;
   let codegraphRetention: ReturnType<typeof cleanupCodegraphCaches> | undefined;
   let repositoryNamespaceRetention: ReturnType<typeof cleanupRetiredRepositoryNamespaces> | undefined;
   const removedCodegraphLocatorPaths: string[] = [];
@@ -920,6 +1174,7 @@ export function cleanupControllerRuntimeState(
         graceMs: options.cleanupArtifactRetentionGraceMs,
         maxEntries,
         maxRemovals: removalBudget.remaining,
+        scanSequence: removalCycleSequence,
       });
       removalBudget.remaining = Math.max(0, removalBudget.remaining - artifactRetention.attempted);
       if (artifactRetention.budgetExhausted) removalBudget.exhausted = true;
@@ -971,7 +1226,7 @@ export function cleanupControllerRuntimeState(
         let protectedWorkIds: string[];
         try {
           protectedWorkIds = readWorkContractStore({ controllerHome: home, repoId: repository.repoId }).contracts
-            .filter((contract) => !isTerminalWorkContractStatus(contract.status))
+            .filter((contract) => !isTerminalSemanticWorkState(contract.semanticState))
             .map((contract) => contract.workId);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
@@ -1082,6 +1337,14 @@ export function cleanupControllerRuntimeState(
       errors.push(...repositoryNamespaceRetention.errors.map((error) => `repository-namespace ${error}`));
       continue;
     }
+    releaseSessionCandidates = cleanupReleaseSessionCandidateLanes(home, {
+      maxEntries,
+      sequence,
+      removalBudget,
+      skippedByReason,
+    });
+    errors.push(...releaseSessionCandidates.errors.map((error) => `release-session-candidate ${error}`));
+
     releaseRetention = cleanupControllerReleaseHistory(home, {
       nowMs,
       graceMs: options.releaseRetentionGraceMs,
@@ -1103,8 +1366,9 @@ export function cleanupControllerRuntimeState(
     codegraphRetention ??= { policyVersion: CODEGRAPH_CACHE_RETENTION_POLICY_VERSION, removedPaths: [], attempted: 0, budgetExhausted: false, skippedByReason: {}, errors: [], inspected: 0, eligible: 0, retained: 0, reclaimedBytes: 0, unknownReclaimedByteCount: 0, observedBytes: 0, unknownObservedByteCount: 0, protected: 0, protectedOverCapacity: 0, truncated: false } as ReturnType<typeof cleanupCodegraphCaches>;
     repositoryNamespaceRetention ??= { policyVersion: 'repository-namespace-retention-v1', removedPaths: [], attempted: 0, budgetExhausted: false, skippedByReason: {}, errors: [], inspected: 0, eligible: 0, retained: 0, reclaimedBytes: 0, unknownReclaimedByteCount: 0 } as ReturnType<typeof cleanupRetiredRepositoryNamespaces>;
     releaseRetention ??= { removedPaths: [], removedBackupPaths: [], attempted: 0, budgetExhausted: false, skippedByReason: {}, errors: [], inspected: 0, eligible: 0, retained: 0, skipped: 0, reclaimedBytes: 0, unknownReclaimedByteCount: 0, reclaimedBackupBytes: 0, unknownReclaimedBackupByteCount: 0 } as ReturnType<typeof cleanupControllerReleaseHistory>;
+    releaseSessionCandidates ??= emptyReleaseSessionCandidateRetentionReport();
   }
-  if (!worktrees || !dependencyCleanup || !temporaryCleanup || !artifactRetention || !codegraphRetention || !repositoryNamespaceRetention || !releaseRetention) {
+  if (!worktrees || !dependencyCleanup || !temporaryCleanup || !artifactRetention || !codegraphRetention || !repositoryNamespaceRetention || !releaseRetention || !releaseSessionCandidates) {
     throw new Error('RUNTIME_CLEANUP_PHASE_INCOMPLETE');
   }
   const removedTemporaryPaths = temporaryCleanup.removed.sort();
@@ -1128,8 +1392,8 @@ export function cleanupControllerRuntimeState(
   } catch (error) {
     errors.push(errorText('SQLite maintenance', error));
   }
-  const inspectedPaths = referenceBudget.inspected + worktreeBudget.inspected + dependencyBudget.inspected + tempBudget.inspected + schedulerBudget.inspected + editSessionBudget.inspected + artifactRetention.inspected + codegraphLocatorInspected + codegraphRetention.inspected + repositoryNamespaceRetention.inspected + releaseRetention.inspected;
-  const budgetExhausted = referenceBudget.exhausted || worktreeBudget.exhausted || dependencyBudget.exhausted || tempBudget.exhausted || schedulerBudget.exhausted || editSessionBudget.exhausted || removalBudget.exhausted;
+  const inspectedPaths = referenceBudget.inspected + worktreeBudget.inspected + dependencyBudget.inspected + tempBudget.inspected + schedulerBudget.inspected + editSessionBudget.inspected + artifactRetention.inspected + codegraphLocatorInspected + codegraphRetention.inspected + repositoryNamespaceRetention.inspected + releaseRetention.inspected + releaseSessionCandidates.inspected;
+  const budgetExhausted = referenceBudget.exhausted || worktreeBudget.exhausted || dependencyBudget.exhausted || tempBudget.exhausted || schedulerBudget.exhausted || editSessionBudget.exhausted || removalBudget.exhausted || releaseSessionCandidates.truncated;
   if (pidFiles.skipped.length > 0 && removalBudget.exhausted) skippedByReason.cleanup_budget_exhausted = (skippedByReason.cleanup_budget_exhausted ?? 0) + pidFiles.skipped.length;
   if (pidFiles.skipped.length > 0 && !removalBudget.exhausted) skippedByReason.active_owner = (skippedByReason.active_owner ?? 0) + pidFiles.skipped.length;
   const physicalReclaimedByClass: Record<string, RuntimeCleanupLifecycleClassMetrics> = {
@@ -1158,6 +1422,11 @@ export function cleanupControllerRuntimeState(
       bytes: releaseRetention.reclaimedBackupBytes,
       unknownByteCount: releaseRetention.unknownReclaimedBackupByteCount,
     },
+    release_session_candidate: {
+      count: releaseSessionCandidates.removedPaths.length,
+      bytes: releaseSessionCandidates.reclaimedBytes,
+      unknownByteCount: releaseSessionCandidates.unknownReclaimedByteCount,
+    },
     scheduler_occurrence_history: {
       count: removedScheduleOccurrencePaths.length + removedScheduleDecisionPaths.length,
       bytes: schedulerHistory.reclaimedBytes,
@@ -1199,8 +1468,8 @@ export function cleanupControllerRuntimeState(
     reclaimedBytes: Object.values(physicalReclaimedByClass).reduce((total, entry) => total + entry.bytes, 0),
     unknownReclaimedByteCount: Object.values(physicalReclaimedByClass).reduce((total, entry) => total + entry.unknownByteCount, 0),
     reclaimedByClass: physicalReclaimedByClass,
-    logicalRetiredCount: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length,
-    logicalRetiredByClass: { work: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length },
+    logicalRetiredCount: retiredOwnerlessWorkAuthorities.length,
+    logicalRetiredByClass: { work: retiredOwnerlessWorkAuthorities.length },
     protectedActiveCount: Object.values(protectedByReason).reduce((total, count) => total + count, 0),
     protectedByReason,
     blockerReasons,
@@ -1216,6 +1485,7 @@ export function cleanupControllerRuntimeState(
     removedTemporaryPaths,
     removedCleanupArtifactPaths,
     removedReleasePaths,
+    releaseSessionCandidates,
     removedScheduleOccurrencePaths,
     removedScheduleDecisionPaths,
     removedEditSessionPaths,
@@ -1223,7 +1493,6 @@ export function cleanupControllerRuntimeState(
     removedCodegraphCachePaths,
     removedRepositoryNamespacePaths,
     sqliteMaintenance,
-    retiredPlanBoundWorkAuthorities: retiredPlanBoundWorkAuthorities.sort(),
     retiredOwnerlessWorkAuthorities: retiredOwnerlessWorkAuthorities.sort(),
     skippedActiveWorktrees: worktrees.skippedActive.sort(),
     inspectedPaths,
@@ -1233,11 +1502,11 @@ export function cleanupControllerRuntimeState(
     lifecycleMetrics,
     cycle: {
       scanned: inspectedPaths,
-      eligible: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.eligible + schedulerHistory.eligible + editSessionHistory.eligible + removedCodegraphLocatorPaths.length + codegraphRetention.eligible + repositoryNamespaceRetention.eligible + releaseRetention.eligible,
-      attempted: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.attempted + schedulerHistory.attempted + editSessionHistory.attempted + removedCodegraphLocatorPaths.length + codegraphRetention.attempted + repositoryNamespaceRetention.attempted + releaseRetention.attempted + errors.length,
-      removed: retiredPlanBoundWorkAuthorities.length + retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + removedCleanupArtifactPaths.length + removedScheduleOccurrencePaths.length + removedScheduleDecisionPaths.length + removedEditSessionPaths.length + removedCodegraphLocatorPaths.length + removedCodegraphCachePaths.length + removedRepositoryNamespacePaths.length + removedReleasePaths.length,
-      retained: pidFiles.skipped.length + worktrees.skippedActive.length + artifactRetention.retained + schedulerHistory.retained + editSessionHistory.retained + codegraphLocatorRetained + codegraphRetention.retained + repositoryNamespaceRetention.retained + releaseRetention.retained,
-      skipped: Math.max(0, inspectedPaths - pidFiles.removed.length - worktrees.removed.length - dependencyCleanup.migrated.length - removedTemporaryPaths.length - removedCleanupArtifactPaths.length - removedScheduleOccurrencePaths.length - removedScheduleDecisionPaths.length - removedEditSessionPaths.length - removedCodegraphLocatorPaths.length - removedCodegraphCachePaths.length - removedRepositoryNamespacePaths.length - removedReleasePaths.length - errors.length),
+      eligible: retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.eligible + schedulerHistory.eligible + editSessionHistory.eligible + removedCodegraphLocatorPaths.length + codegraphRetention.eligible + repositoryNamespaceRetention.eligible + releaseRetention.eligible + releaseSessionCandidates.eligible,
+      attempted: retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + artifactRetention.attempted + schedulerHistory.attempted + editSessionHistory.attempted + removedCodegraphLocatorPaths.length + codegraphRetention.attempted + repositoryNamespaceRetention.attempted + releaseRetention.attempted + releaseSessionCandidates.attempted + errors.length,
+      removed: retiredOwnerlessWorkAuthorities.length + pidFiles.removed.length + worktrees.removed.length + dependencyCleanup.migrated.length + removedTemporaryPaths.length + removedCleanupArtifactPaths.length + removedScheduleOccurrencePaths.length + removedScheduleDecisionPaths.length + removedEditSessionPaths.length + removedCodegraphLocatorPaths.length + removedCodegraphCachePaths.length + removedRepositoryNamespacePaths.length + removedReleasePaths.length + releaseSessionCandidates.removedPaths.length,
+      retained: pidFiles.skipped.length + worktrees.skippedActive.length + artifactRetention.retained + schedulerHistory.retained + editSessionHistory.retained + codegraphLocatorRetained + codegraphRetention.retained + repositoryNamespaceRetention.retained + releaseRetention.retained + releaseSessionCandidates.retainedCount,
+      skipped: Math.max(0, inspectedPaths - pidFiles.removed.length - worktrees.removed.length - dependencyCleanup.migrated.length - removedTemporaryPaths.length - removedCleanupArtifactPaths.length - removedScheduleOccurrencePaths.length - removedScheduleDecisionPaths.length - removedEditSessionPaths.length - removedCodegraphLocatorPaths.length - removedCodegraphCachePaths.length - removedRepositoryNamespacePaths.length - removedReleasePaths.length - releaseSessionCandidates.removedPaths.length - errors.length),
       failed: errors.length,
       truncated: budgetExhausted,
       budgetExhausted,

package/src/runtime/control-plane/workspace/project-onboarding.ts

@@ -0,0 +1,80 @@
+import { ensureForgeInstanceIdentity } from '../../../../packages/kernel/identity/api/index';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import {
+  normalizeRemoteUrl,
+  portableProjectSourceFingerprint,
+  stablePortableProjectId,
+} from '../../../cli/repositories/identity';
+import { loadProjectEngineeringContract } from '../../context/project-engineering-contract';
+import {
+  ensureProjectWorkspaceBinding,
+  type EnsureProjectWorkspaceBindingResult,
+} from './workspace-store';
+
+export type RepositoryProjectOnboardingResult =
+  | {
+      status: 'bound';
+      projectId: string;
+      workspaceId: string;
+      forgeInstanceId: string;
+      identitySource: 'project_contract' | 'canonical_remote';
+      createdWorkspace: boolean;
+      createdProject: boolean;
+      createdPlacement: boolean;
+    }
+  | {
+      status: 'unbound';
+      reason: 'portable_project_identity_unavailable';
+    };
+
+/**
+ * Bind a repository to portable Project/Workspace semantics only when Work
+ * admission actually treats it as a project. Repository registration remains a
+ * node-local placement concern and never creates semantic identity by itself.
+ */
+export function ensureRepositoryProjectOnboarding(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  sourceRevision?: string;
+}): RepositoryProjectOnboardingResult {
+  const contract = loadProjectEngineeringContract({
+    repoRoot: input.repository.canonicalRoot,
+    sourceRevision: input.sourceRevision?.trim() || 'working-tree',
+  });
+  const declaredProjectId = contract.status === 'ready' ? contract.contract.projectId : undefined;
+  const canonicalRemote = input.repository.canonicalRemote ?? normalizeRemoteUrl(input.repository.remoteUrl);
+  if (!declaredProjectId && !canonicalRemote) {
+    return { status: 'unbound', reason: 'portable_project_identity_unavailable' };
+  }
+
+  const sourceFingerprint = canonicalRemote
+    ? portableProjectSourceFingerprint(canonicalRemote)
+    : undefined;
+  const fallbackProjectId = canonicalRemote
+    ? stablePortableProjectId(canonicalRemote)
+    : undefined;
+  const instance = ensureForgeInstanceIdentity({
+    controllerHome: input.controllerHome,
+    label: 'Forge Runtime',
+  });
+  const binding: EnsureProjectWorkspaceBindingResult = ensureProjectWorkspaceBinding({
+    controllerHome: input.controllerHome,
+    preferredProjectId: declaredProjectId,
+    fallbackProjectId,
+    sourceFingerprint,
+    displayName: input.repository.displayName,
+    forgeInstanceId: instance.instanceId,
+    repositoryId: input.repository.repoId,
+  });
+
+  return {
+    status: 'bound',
+    projectId: binding.project.projectId,
+    workspaceId: binding.project.workspaceId,
+    forgeInstanceId: binding.placement.forgeInstanceId,
+    identitySource: declaredProjectId ? 'project_contract' : 'canonical_remote',
+    createdWorkspace: binding.createdWorkspace,
+    createdProject: binding.createdProject,
+    createdPlacement: binding.createdPlacement,
+  };
+}

package/src/runtime/control-plane/workspace/semantic-sync-service.ts

@@ -18,6 +18,7 @@ import { readForgeInstanceIdentity } from '../../../../packages/kernel/identity/
 import type { WorkContract } from '../../../../packages/kernel/work/api/index';
 import { semanticScopeRefForWork } from '../../../../packages/kernel/work/api/index';
 import type { PlanContract } from '../facade/types';
+import { SEMANTIC_SCOPE_KEY } from '../../../cli/repositories/controller-home';
 import type { Requirement } from '../persistence/requirement-store';
 import {
   ControlPlaneConflictError,
@@ -90,13 +91,15 @@ export interface WorkSemanticView {
   semanticScope: ReturnType<typeof semanticScopeRefForWork>;
   objective: string;
   acceptanceCriteria: string[];
-  status: WorkContract['status'];
+  state: WorkContract['semanticState'];
   phase: WorkContract['phase'];
   workKind: WorkContract['workKind'];
   lifecycleRole?: WorkContract['lifecycleRole'];
   requirementId?: string;
   planId?: string;
   planStepId?: string;
+  semanticParentWorkId?: string;
+  dependsOnWorkIds?: string[];
   predecessorWorkId?: string;
   supersedes?: string[];
   supersededBy?: string;
@@ -199,13 +202,15 @@ export function projectWorkSemantic(work: WorkContract): WorkSemanticView {
     semanticScope: semanticScopeRefForWork(work),
     objective: work.objective,
     acceptanceCriteria: [...work.acceptanceCriteria],
-    status: work.status,
+    state: work.semanticState,
     phase: work.phase,
     workKind: work.workKind,
     ...(work.lifecycleRole ? { lifecycleRole: work.lifecycleRole } : {}),
     ...(work.requirementId ? { requirementId: work.requirementId } : {}),
     ...(work.planId ? { planId: work.planId } : {}),
     ...(work.planStepId ? { planStepId: work.planStepId } : {}),
+    ...(work.semanticParentWorkId ? { semanticParentWorkId: work.semanticParentWorkId } : {}),
+    ...(work.dependsOnWorkIds?.length ? { dependsOnWorkIds: [...work.dependsOnWorkIds] } : {}),
     ...(work.predecessorWorkId ? { predecessorWorkId: work.predecessorWorkId } : {}),
     ...(work.supersedes ? { supersedes: [...work.supersedes] } : {}),
     ...(work.supersededBy ? { supersededBy: work.supersededBy } : {}),
@@ -311,9 +316,18 @@ function localRecordWithinTransaction(database: SqliteDatabase, input: { kind: S
   if (input.kind === 'workspace') return readControlPlaneRecordWithinTransaction(database, WORKSPACE_SEMANTIC_NAMESPACE, CONTROLLER_SCOPE, input.id);
   if (input.kind === 'project') return readControlPlaneRecordWithinTransaction(database, PROJECT_SEMANTIC_NAMESPACE, input.workspaceId, input.id);
   if (input.kind === 'requirement') return readControlPlaneRecordWithinTransaction(database, 'requirement', CONTROLLER_SCOPE, input.id);
-  if (!input.repositoryId) return undefined;
-  if (input.kind === 'plan') return readControlPlaneRecordWithinTransaction(database, 'plan_contract', input.repositoryId, input.id);
-  if (input.kind === 'work') return readControlPlaneRecordWithinTransaction(database, 'work_contract', input.repositoryId, input.id);
+  if (input.kind === 'plan') {
+    const semantic = readControlPlaneRecordWithinTransaction(database, 'plan_contract', SEMANTIC_SCOPE_KEY, input.id);
+    return semantic ?? (input.repositoryId
+      ? readControlPlaneRecordWithinTransaction(database, 'plan_contract', input.repositoryId, input.id)
+      : undefined);
+  }
+  if (input.kind === 'work') {
+    const semantic = readControlPlaneRecordWithinTransaction(database, 'work_contract', SEMANTIC_SCOPE_KEY, input.id);
+    return semantic ?? (input.repositoryId
+      ? readControlPlaneRecordWithinTransaction(database, 'work_contract', input.repositoryId, input.id)
+      : undefined);
+  }
   return undefined;
 }