@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/control-plane/execution/execution-identity.ts

@@ -134,6 +134,53 @@ function gitPath(root: string, args: string[]): string | undefined {
   }
 }
 
+interface GitExecutionSnapshot {
+  topLevel?: string;
+  commonDirectory?: string;
+  branch?: string;
+  head?: string;
+}
+
+function resolvedGitPath(root: string, value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  try {
+    return realpathSync(isAbsolute(value) ? value : resolve(root, value));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read the checkout identity in one Git child process on the normal committed
+ * path. This preserves the same fail-closed fields as the former six probes;
+ * unborn repositories fall back to the individual observations because HEAD is
+ * intentionally absent there.
+ */
+function gitExecutionSnapshot(root: string): GitExecutionSnapshot {
+  const combined = gitText(root, ['rev-parse', '--show-toplevel', '--git-common-dir', 'HEAD', '--abbrev-ref', 'HEAD']);
+  if (combined) {
+    const lines = combined.split('\n').map((line) => line.trim());
+    if (lines.length >= 4) {
+      return {
+        topLevel: resolvedGitPath(root, lines[0]),
+        commonDirectory: resolvedGitPath(root, lines[1]),
+        head: lines[2] || undefined,
+        branch: lines[3] && lines[3] !== 'HEAD' ? lines[3] : undefined,
+      };
+    }
+  }
+  // Rare unborn/failure fallback keeps legacy behavior rather than turning a
+  // missing HEAD into a false workspace identity failure.
+  const topLevel = gitPath(root, ['rev-parse', '--show-toplevel']);
+  const commonDirectory = gitPath(root, ['rev-parse', '--git-common-dir']);
+  return {
+    topLevel,
+    commonDirectory,
+    branch: topLevel ? gitText(topLevel, ['branch', '--show-current']) : undefined,
+    head: topLevel ? gitText(topLevel, ['rev-parse', '--verify', 'HEAD']) : undefined,
+  };
+}
+
 export function classifyGitCommonDirectoryDrift(input: {
   repoId: string;
   checkoutId: string;
@@ -304,18 +351,15 @@ export function assertExecutionIdentity(input: {
         actual: resolvedCwd,
       });
     }
-    const gitTopLevel = gitPath(resolvedCwd, ['rev-parse', '--show-toplevel']);
-    const gitCommonDirectory = gitPath(resolvedCwd, ['rev-parse', '--git-common-dir']);
-    const currentBranch = gitTopLevel ? gitText(gitTopLevel, ['branch', '--show-current']) : undefined;
-    const currentHead = gitTopLevel ? gitText(gitTopLevel, ['rev-parse', '--verify', 'HEAD']) : undefined;
+    const gitSnapshot = gitExecutionSnapshot(resolvedCwd);
     return Object.freeze({
       ...identity,
       canonicalRoot: workspaceRoot,
       resolvedCwd,
-      gitTopLevel,
-      gitCommonDirectory,
-      currentBranch,
-      currentHead,
+      gitTopLevel: gitSnapshot.topLevel,
+      gitCommonDirectory: gitSnapshot.commonDirectory,
+      currentBranch: gitSnapshot.branch,
+      currentHead: gitSnapshot.head,
     });
   }
 
@@ -377,7 +421,8 @@ export function assertExecutionIdentity(input: {
     });
   }
 
-  const gitTopLevel = gitPath(resolvedCwd, ['rev-parse', '--show-toplevel']);
+  const gitSnapshot = gitExecutionSnapshot(resolvedCwd);
+  const gitTopLevel = gitSnapshot.topLevel;
   if (!gitTopLevel || !samePath(gitTopLevel, registeredRoot)) {
     fail('GIT_TOPLEVEL_MISMATCH', 'Git top-level differs from expected checkout root', {
       repoId: identity.repositoryId,
@@ -387,9 +432,15 @@ export function assertExecutionIdentity(input: {
     });
   }
 
-  const gitCommonDirectory = gitPath(resolvedCwd, ['rev-parse', '--git-common-dir']);
-  const registeredCommonDirectory = gitPath(registeredRoot, ['rev-parse', '--git-common-dir']);
-  const repositoryCommonDirectory = gitPath(registered.canonicalRoot, ['rev-parse', '--git-common-dir']);
+  const gitCommonDirectory = gitSnapshot.commonDirectory;
+  // Once the observed top-level is proven equal to registeredRoot, querying the
+  // same checkout again cannot add identity evidence. Only a linked worktree
+  // needs one extra canonical-repository common-dir observation.
+  const registeredCommonDirectory = gitCommonDirectory;
+  const repositoryRoot = realpathOrFail(registered.canonicalRoot, 'WORKTREE_MISSING', 'repository canonical root');
+  const repositoryCommonDirectory = samePath(repositoryRoot, registeredRoot)
+    ? gitCommonDirectory
+    : gitPath(repositoryRoot, ['rev-parse', '--git-common-dir']);
   const commonDirectoryDrift = classifyGitCommonDirectoryDrift({
     repoId: identity.repositoryId,
     checkoutId: identity.checkoutId,
@@ -423,8 +474,8 @@ export function assertExecutionIdentity(input: {
     });
   }
 
-  const currentBranch = gitText(registeredRoot, ['branch', '--show-current']);
-  const currentHead = gitText(registeredRoot, ['rev-parse', '--verify', 'HEAD']);
+  const currentBranch = gitSnapshot.branch;
+  const currentHead = gitSnapshot.head;
   if (identity.branch && currentBranch !== identity.branch) {
     fail('WORK_HANDLE_BRANCH_CHANGED', 'branch drifted from execution identity', {
       repoId: identity.repositoryId,

package/src/runtime/control-plane/execution/session-store.ts

@@ -163,6 +163,24 @@ export function updateExecutionSession(
   return updated;
 }
 
+export function invalidateExecutionSession(
+  controllerHome: string,
+  sessionId: string,
+  reason: string,
+): ExecutionSessionContext | undefined {
+  const current = peekExecutionSession(controllerHome, sessionId);
+  if (!current || current.invalidatedAt) return current;
+  const at = now();
+  const invalidated: ExecutionSessionContext = {
+    ...current,
+    updatedAt: at,
+    invalidatedAt: at,
+    invalidationReason: reason.trim().slice(0, 512) || 'transport session closed',
+  };
+  writeExecutionSession(controllerHome, invalidated, 'session_invalidated');
+  return invalidated;
+}
+
 function writeExecutionSession(controllerHome: string, session: ExecutionSessionContext, action: string): void {
   writeControlPlaneRecord(controllerHome, {
     namespace: 'execution_session',

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

@@ -32,6 +32,10 @@ function gitText(root: string, args: string[]): string | undefined {
     : undefined;
 }
 
+function gitSucceeds(root: string, args: string[]): boolean {
+  return spawnSync('git', ['-C', root, ...args], { stdio: 'ignore', timeout: 10_000 }).status === 0;
+}
+
 function fail(code: string, message: string): never {
   throw new Error(`${code}: ${message}`);
 }
@@ -44,7 +48,7 @@ export function assertWorkHandleLifecycle(handle: WorkHandleState, operation: 'i
   const allowed: Record<typeof operation, readonly WorkHandleState['state'][]> = {
     inspect: ['prepared', 'editing', 'validating', 'committed', 'merged', 'failed', 'failed_terminal_cleanup', 'cleaned'],
     execute: ['prepared', 'editing'],
-    validate: ['prepared', 'editing', 'validating', 'committed', 'merged'],
+    validate: ['prepared', 'editing', 'validating', 'committed', 'merged', 'failed'],
     finalize: ['prepared', 'editing', 'validating', 'committed', 'merged', 'failed_terminal_cleanup', 'cleaned', 'failed'],
   };
   if (!allowed[operation].includes(handle.state)) {
@@ -99,7 +103,16 @@ export function validateWorkHandle(
   const currentBranch = gitText(root, ['branch', '--show-current']);
   const currentHead = gitText(root, ['rev-parse', '--verify', 'HEAD']);
   if (currentBranch !== handle.branch) fail('WORK_HANDLE_BRANCH_CHANGED', `expected ${handle.branch}, found ${currentBranch ?? 'detached'}`);
-  if (handle.expectedHead && currentHead !== handle.expectedHead) fail('WORK_HANDLE_HEAD_CHANGED', `expected ${handle.expectedHead}, found ${currentHead ?? 'missing'}`);
+  const managedWorkProgress = (operation === 'validate' || operation === 'finalize')
+    && handle.managedWorktree
+    && Boolean(handle.expectedHead && currentHead)
+    && gitSucceeds(root, ['merge-base', '--is-ancestor', handle.expectedHead!, currentHead!]);
+  if (handle.expectedHead && currentHead !== handle.expectedHead && !managedWorkProgress) {
+    fail('WORK_HANDLE_HEAD_CHANGED', `expected ${handle.expectedHead}, found ${currentHead ?? 'missing'}`);
+  }
+  if (managedWorkProgress && currentHead !== handle.expectedHead) {
+    warnings.push('Managed Worktree HEAD advanced from the prepared revision by Work-owned descendant commits; validation/finalization will use the current Work state.');
+  }
 
   if (level === 'full') {
     const validation = validateRepository(repository.repoId, controllerHome);

package/src/runtime/control-plane/execution/verification-evidence.ts

@@ -14,7 +14,6 @@ export interface VerificationEvidenceIdentity {
   workspaceFingerprint?: string;
   checkId: string;
   requestedChecks: string[];
-  commandId?: string;
 }
 
 export interface EffectiveVerificationEvidence {
@@ -23,6 +22,12 @@ export interface EffectiveVerificationEvidence {
   staleReason?: string;
 }
 
+export interface HistoricalVerificationEvidenceIdentity extends Omit<VerificationEvidenceIdentity, 'workspaceFingerprint'> {
+  repoId: string;
+  workId: string;
+  checkoutId?: string;
+}
+
 function decodeGitQuotedPath(rawPath: string): string {
   if (!rawPath.startsWith('"') && !rawPath.endsWith('"')) return rawPath;
   if (!rawPath.startsWith('"') || !rawPath.endsWith('"')) {
@@ -146,14 +151,13 @@ export function workValidationInputFingerprint(
   })).digest('hex');
 }
 
-/** Stable identity for inputs that make a check result reusable. */
+/** Stable identity for semantic inputs that make a check result reusable. Invocation ids are audited separately. */
 export function verificationInputFingerprint(input: VerificationEvidenceIdentity): string {
   return createHash('sha256').update(JSON.stringify({
     sourceRevision: input.sourceRevision,
     workspaceFingerprint: input.workspaceFingerprint ?? null,
     checkId: input.checkId,
     requestedChecks: [...input.requestedChecks].sort(),
-    commandId: input.commandId ?? null,
   })).digest('hex');
 }
 
@@ -161,6 +165,57 @@ export function commandFingerprint(checkId: string, commandId: string | undefine
   return createHash('sha256').update(JSON.stringify({ checkId, commandId: commandId ?? null })).digest('hex');
 }
 
+/**
+ * Selects immutable Work-bound verification evidence for an explicit historical
+ * revision. Unlike current-workspace reuse, the historical workspace identity
+ * comes from each durable receipt record and is verified against the record's
+ * persisted semantic and command fingerprints.
+ */
+export function historicalVerificationEvidenceAtRevision(
+  records: VerificationRecord[],
+  expected: HistoricalVerificationEvidenceIdentity,
+): EffectiveVerificationEvidence[] {
+  return records
+    .filter((record) => record.checkId === expected.checkId)
+    .map((record) => {
+      if (record.supersedes || record.outcome === 'superseded') {
+        return { record, current: false, staleReason: 'superseded' };
+      }
+      if (!record.sourceRevision || !record.workspaceFingerprint || !record.verificationInputFingerprint || !record.commandFingerprint) {
+        return { record, current: false, staleReason: 'historical evidence has no exact input identity' };
+      }
+      if (record.sourceRevision !== expected.sourceRevision) {
+        return { record, current: false, staleReason: `source revision changed: ${record.sourceRevision} -> ${expected.sourceRevision}` };
+      }
+      const receipt = record.receipt;
+      if (
+        !receipt
+        || receipt.repoId !== expected.repoId
+        || receipt.workId !== expected.workId
+        || receipt.checkId !== expected.checkId
+        || (expected.checkoutId !== undefined && receipt.checkoutId !== expected.checkoutId)
+      ) {
+        return { record, current: false, staleReason: 'historical receipt identity changed' };
+      }
+      if (receipt.status !== 'passed' || receipt.runtimeStatus !== 'succeeded' || !receipt.ok || receipt.timedOut || receipt.cancelled) {
+        return { record, current: false, staleReason: 'historical receipt is not a valid pass' };
+      }
+      const expectedFingerprint = verificationInputFingerprint({
+        sourceRevision: expected.sourceRevision,
+        workspaceFingerprint: record.workspaceFingerprint,
+        checkId: expected.checkId,
+        requestedChecks: expected.requestedChecks,
+      });
+      if (record.verificationInputFingerprint !== expectedFingerprint) {
+        return { record, current: false, staleReason: 'verification inputs changed' };
+      }
+      if (record.commandFingerprint !== commandFingerprint(record.checkId, receipt.commandId)) {
+        return { record, current: false, staleReason: 'check command identity changed' };
+      }
+      return { record, current: true };
+    });
+}
+
 /**
  * Keeps historical evidence auditable while preventing a previous revision or
  * changed check inputs from being selected as proof for the current Work.

package/src/runtime/control-plane/execution/work-handle-store.ts

@@ -3,6 +3,7 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent } from '../../shared/json-files';
+import type { ProcessCheckExecutionIdentity } from '../../execution/process-runtime/types';
 import { listControlPlaneRecords, mutateControlPlaneRecord, readOrImportControlPlaneRecord, writeControlPlaneRecord } from '../persistence/sqlite-store';
 
 export const WORK_HANDLE_STATES = [
@@ -99,7 +100,12 @@ export interface WorkValidationRunState {
   workspaceFingerprint: string;
   requestedChecks: string[];
   resumeState: WorkHandleStateName;
-  processes: Record<string, { processId: string; requestId: string }>;
+  processes: Record<string, {
+    processId: string;
+    requestId: string;
+    /** Exact producer-side Check identity for this Work verification snapshot. */
+    checkExecution?: ProcessCheckExecutionIdentity;
+  }>;
 }
 
 interface WorkValidationIndex {
@@ -146,6 +152,8 @@ export interface WorkHandleState {
   managedWorktree: boolean;
   workContractId?: string;
   baseCommit?: string;
+  /** Latest canonical target HEAD incorporated into this Work candidate. Legacy records fall back to baseCommit. */
+  deliveryBaseCommit?: string;
   expectedHead?: string;
   permissionSnapshotVersion: number;
   state: WorkHandleStateName;
@@ -161,10 +169,27 @@ export interface WorkHandleState {
     owner: 'work_finalizer';
     registeredAt: string;
   };
+  /**
+   * Explicit terminal resource disposition. This is separate from finalization
+   * stage `skipped`, which is too ambiguous in legacy records to prove that a
+   * controller intentionally retained a managed branch/worktree.
+   */
+  terminalResourceDisposition?: {
+    mode: 'retained_by_request';
+    retainWorktree: boolean;
+    retainBranch: boolean;
+    recordedAt: string;
+  };
   /** Durable terminal cleanup progress. It is intentionally independent from completion/verification receipts. */
   cleanupReceipt?: WorkCleanupReceipt;
 }
 
+export function workDeliveryBaseRevision(
+  handle: Pick<WorkHandleState, 'baseCommit' | 'deliveryBaseCommit'>,
+): string | undefined {
+  return handle.deliveryBaseCommit?.trim() || handle.baseCommit?.trim() || undefined;
+}
+
 function workHandlePath(controllerHome: string, handle: Pick<WorkHandleState, 'repositoryId' | 'workId'>): string {
   return join(repositoryControllerRoot(controllerHome, handle.repositoryId), 'work-handles', `${sanitizeFileComponent(handle.workId)}.json`);
 }
@@ -330,7 +355,7 @@ export function transitionWorkHandle(
   controllerHome: string,
   handle: WorkHandleState,
   nextState: WorkHandleStateName,
-  patch: Partial<Pick<WorkHandleState, 'failureReason' | 'expectedHead' | 'finalization' | 'validationRun' | 'validatedInputFingerprint' | 'cleanupReceipt'>> = {},
+  patch: Partial<Pick<WorkHandleState, 'failureReason' | 'deliveryBaseCommit' | 'expectedHead' | 'finalization' | 'validationRun' | 'validatedInputFingerprint' | 'cleanupReceipt'>> = {},
 ): WorkHandleState {
   if (handle.state !== nextState && !TRANSITIONS[handle.state].includes(nextState)) {
     throw new Error(`WORK_HANDLE_LIFECYCLE_INVALID: cannot transition ${handle.state} -> ${nextState}`);

package/src/runtime/control-plane/execution/work-lifecycle-audit.ts

@@ -0,0 +1,258 @@
+import { spawnSync } from 'child_process';
+import { existsSync, realpathSync } from 'fs';
+import { resolve } from 'path';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { listWorkContracts } from '../facade/work-contract-store';
+import { isTerminalWorkContractStatus } from '../facade/types';
+import { listWorkHandles } from './work-handle-store';
+
+export interface WorkLifecycleAttention {
+  jobId: string;
+  status: string;
+  message: string;
+}
+
+interface LinkedWorktree {
+  path: string;
+  branch?: string;
+}
+
+function git(repositoryRoot: string, args: string[]): string | undefined {
+  const result = spawnSync('git', ['-C', repositoryRoot, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 10_000,
+    maxBuffer: 4 * 1024 * 1024,
+  });
+  return result.status === 0 && typeof result.stdout === 'string' ? result.stdout.trim() : undefined;
+}
+
+export interface WorktreeGitSnapshot {
+  head?: string;
+  branch?: string;
+  clean: boolean;
+}
+
+export function gitCommitAtRef(repositoryRoot: string, ref: string): string | undefined {
+  const value = git(repositoryRoot, ['rev-parse', '--verify', `${ref}^{commit}`]);
+  return value?.trim() || undefined;
+}
+
+export function gitWorktreeSnapshot(repositoryRoot: string): WorktreeGitSnapshot | undefined {
+  const head = gitCommitAtRef(repositoryRoot, 'HEAD');
+  const branch = git(repositoryRoot, ['branch', '--show-current']);
+  const porcelain = git(repositoryRoot, ['status', '--porcelain']);
+  if (porcelain === undefined) return undefined;
+  return { head, branch: branch?.trim() || undefined, clean: porcelain.length === 0 };
+}
+
+function linkedWorktrees(repositoryRoot: string): LinkedWorktree[] {
+  const output = git(repositoryRoot, ['worktree', 'list', '--porcelain']);
+  if (output === undefined) return [];
+  const worktrees: LinkedWorktree[] = [];
+  let current: LinkedWorktree | undefined;
+  for (const line of output.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (current) worktrees.push(current);
+      current = { path: line.slice('worktree '.length) };
+    } else if (current && line.startsWith('branch refs/heads/')) {
+      current.branch = line.slice('branch refs/heads/'.length);
+    }
+  }
+  if (current) worktrees.push(current);
+  return worktrees;
+}
+
+function dirty(path: string): boolean | undefined {
+  const status = git(path, ['status', '--porcelain']);
+  return status === undefined ? undefined : status.length > 0;
+}
+
+function canonicalPath(path: string): string {
+  try { return realpathSync.native(path); }
+  catch { return resolve(path); }
+}
+
+function refReachableFromTarget(repositoryRoot: string, ref: string, targetBranch: string): boolean | undefined {
+  const result = spawnSync('git', ['-C', repositoryRoot, 'merge-base', '--is-ancestor', ref, targetBranch], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'ignore', 'ignore'],
+    timeout: 10_000,
+  });
+  if (result.status === 0) return true;
+  if (result.status === 1) return false;
+  return undefined;
+}
+
+function branchIntegrated(repositoryRoot: string, branch: string, targetBranch: string): boolean | undefined {
+  const reachable = refReachableFromTarget(repositoryRoot, branch, targetBranch);
+  if (reachable !== false) return reachable;
+
+  // Rebase/cherry-pick delivery can preserve every patch while changing ancestry.
+  // Treat the branch as integrated only when Git proves it has no unique patches.
+  const cherry = spawnSync('git', ['-C', repositoryRoot, 'cherry', targetBranch, branch], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 10_000,
+    maxBuffer: 4 * 1024 * 1024,
+  });
+  if (cherry.status !== 0 || typeof cherry.stdout !== 'string') return false;
+  return !cherry.stdout.split('\n').some((line) => line.startsWith('+ '));
+}
+
+function attention(code: string, identity: string, message: string): WorkLifecycleAttention {
+  return { jobId: `lifecycle:${code}:${identity}`, status: code, message };
+}
+
+/**
+ * Read-only reconciliation across canonical Work, WorkHandle, registry, and Git.
+ * It reports contradictions and live Work through the existing Runtime projection;
+ * it never changes lifecycle state or owns cleanup.
+ */
+export function collectWorkLifecycleAttention(
+  controllerHome: string,
+  repository: RepositoryRecord,
+): WorkLifecycleAttention[] {
+  const contracts = listWorkContracts({
+    controllerHome,
+    repoId: repository.repoId,
+    status: 'all',
+    limit: 100,
+  });
+  const handles = listWorkHandles(controllerHome, repository.repoId, 5_000);
+  const contractsByWork = new Map(contracts.map((contract) => [contract.workId, contract]));
+  const handlesByWork = new Map(handles.map((handle) => [handle.workContractId ?? handle.workId, handle]));
+  const findings: WorkLifecycleAttention[] = [];
+  const targetBranch = repository.defaultBranch || 'main';
+
+  for (const contract of contracts) {
+    const handle = handlesByWork.get(contract.workId);
+    const terminal = isTerminalWorkContractStatus(contract.status);
+    if (!terminal) {
+      findings.push(attention(
+        'work_active',
+        contract.workId,
+        `Work ${contract.workId} is ${contract.status} in ${contract.phase}; continue, block with a handoff, or finalize it explicitly.`,
+      ));
+      if (contract.workKind === 'repository_change' && !handle) {
+        findings.push(attention(
+          'active_work_handle_missing',
+          contract.workId,
+          `Repository Work ${contract.workId} is active but has no readable WorkHandle.`,
+        ));
+      }
+      if (handle?.managedWorktree && !existsSync(handle.worktreePath)) {
+        findings.push(attention(
+          'active_worktree_missing',
+          contract.workId,
+          `Active Work ${contract.workId} owns missing managed worktree ${handle.worktreePath}.`,
+        ));
+      }
+      continue;
+    }
+
+    if (contract.status === 'completed' && !contract.completionReceipt) {
+      findings.push(attention(
+        'completed_work_receipt_missing',
+        contract.workId,
+        `Completed Work ${contract.workId} has no Completion Receipt.`,
+      ));
+    }
+    if (contract.status === 'completed' && contract.completionReceipt?.source === 'controller_work') {
+      const receiptTargetRevision = contract.completionReceipt.targetRevision?.trim();
+      const receiptTargetBranch = contract.completionReceipt.targetBranch?.trim() || targetBranch;
+      if (!receiptTargetRevision || refReachableFromTarget(repository.canonicalRoot, receiptTargetRevision, receiptTargetBranch) !== true) {
+        findings.push(attention(
+          'completion_receipt_target_not_integrated',
+          contract.workId,
+          `Work ${contract.workId} receipt target ${receiptTargetRevision || 'missing'} is not reachable from ${receiptTargetBranch}.`,
+        ));
+      }
+    }
+    if (!handle || handle.terminalResourceDisposition?.mode === 'retained_by_request') continue;
+    const cleanupFailed = handle.finalization.branchCleanup === 'failed'
+      || handle.finalization.worktreeCleanup === 'failed';
+    const cleanupPending = handle.finalization.branchCleanup === 'pending'
+      || handle.finalization.worktreeCleanup === 'pending';
+    const repositoryOwnedCanonicalCheckout = !handle.managedWorktree
+      && canonicalPath(handle.worktreePath) === canonicalPath(repository.canonicalRoot)
+      && handle.branch === targetBranch;
+    const cleanupUnsettled = cleanupFailed || (cleanupPending && !repositoryOwnedCanonicalCheckout);
+    if (cleanupUnsettled) {
+      findings.push(attention(
+        'terminal_work_cleanup_unsettled',
+        contract.workId,
+        `Terminal Work ${contract.workId} still has unsettled branch/worktree cleanup stages.`,
+      ));
+    }
+    if (handle.state === 'cleaned' && handle.managedWorktree && existsSync(handle.worktreePath)) {
+      findings.push(attention(
+        'cleaned_worktree_still_present',
+        contract.workId,
+        `WorkHandle ${contract.workId} is cleaned but managed worktree ${handle.worktreePath} still exists.`,
+      ));
+    }
+  }
+
+  const activeBranches = new Set(
+    handles
+      .filter((handle) => {
+        const contract = contractsByWork.get(handle.workContractId ?? handle.workId);
+        return contract ? !isTerminalWorkContractStatus(contract.status) : false;
+      })
+      .map((handle) => handle.branch),
+  );
+  const retainedBranches = new Set(
+    handles
+      .filter((handle) => handle.terminalResourceDisposition?.retainBranch === true)
+      .map((handle) => handle.branch),
+  );
+  const activeRegistryRoots = new Set(
+    repository.checkouts
+      .filter((checkout) => (checkout.lifecycle ?? 'active') === 'active')
+      .map((checkout) => canonicalPath(checkout.canonicalRoot)),
+  );
+  const handleRoots = new Map(handles.map((handle) => [canonicalPath(handle.worktreePath), handle]));
+
+  for (const checkout of repository.checkouts) {
+    if ((checkout.lifecycle ?? 'active') === 'active' && !existsSync(checkout.canonicalRoot)) {
+      findings.push(attention(
+        'active_checkout_missing',
+        checkout.checkoutId,
+        `Registry checkout ${checkout.checkoutId} is active but ${checkout.canonicalRoot} is missing.`,
+      ));
+    }
+  }
+
+  const linked = linkedWorktrees(repository.canonicalRoot);
+  for (const worktree of linked) {
+    const root = canonicalPath(worktree.path);
+    if (activeRegistryRoots.has(root)) continue;
+    const isDirty = dirty(root);
+    const handle = handleRoots.get(root);
+    const code = isDirty === true ? 'dirty_linked_worktree_unregistered' : 'linked_worktree_unregistered';
+    findings.push(attention(
+      code,
+      handle?.workId ?? worktree.branch ?? root,
+      `Git worktree ${root}${worktree.branch ? ` on ${worktree.branch}` : ''} is linked but absent from the active checkout registry${isDirty === true ? ' and has uncommitted changes' : ''}.`,
+    ));
+  }
+
+  const branches = git(repository.canonicalRoot, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/work', 'refs/heads/codex'])
+    ?.split('\n')
+    .map((branch) => branch.trim())
+    .filter(Boolean) ?? [];
+  for (const branch of branches) {
+    if (activeBranches.has(branch) || retainedBranches.has(branch)) continue;
+    if (branchIntegrated(repository.canonicalRoot, branch, targetBranch) !== false) continue;
+    findings.push(attention(
+      'work_branch_not_integrated',
+      branch,
+      `Work branch ${branch} is not reachable from ${targetBranch} and is not owned by an active or explicitly retained Work.`,
+    ));
+  }
+
+  return Array.from(new Map(findings.map((finding) => [finding.jobId, finding])).values())
+    .sort((left, right) => left.jobId.localeCompare(right.jobId))
+    .slice(0, 100);
+}