@moretea-labs/forge 1.6.0 → 1.7.1

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

@@ -0,0 +1,96 @@
+import { resolve } from 'path';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { resolveRepositorySelection, selectRepositoryCheckout } from '../../../cli/repositories/registry';
+import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
+import { getWorkContract } from '../facade/work-contract-store';
+import { currentPermissionSnapshotVersion } from './validation';
+import { readWorkHandle, writeWorkHandle, type WorkHandleState } from './work-handle-store';
+
+export interface RepositoryWorkHandleControllerIdentity {
+  sessionId: string;
+  principalId: string;
+}
+
+/**
+ * Canonical compatibility repair for a goal-workloop Work whose durable
+ * WorkContract exists but whose WorkHandle has not yet been materialized.
+ * Transport layers provide only the authenticated Controller identity.
+ */
+export function ensureRepositoryWorkHandle(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  identity: RepositoryWorkHandleControllerIdentity;
+}): WorkHandleState | undefined {
+  const existing = readWorkHandle(input.controllerHome, input.repository.repoId, input.workId);
+  if (existing) return existing;
+  const contract = getWorkContract(
+    { controllerHome: input.controllerHome, repoId: input.repository.repoId },
+    input.workId,
+  );
+  if (!contract || contract.workKind !== 'repository_change' || contract.mode !== 'goal_workloop' || !contract.checkoutId) {
+    return undefined;
+  }
+  const executionRepository = resolveRepositorySelection({
+    repoId: input.repository.repoId,
+    checkoutId: contract.checkoutId,
+    controllerHome: input.controllerHome,
+    allowSoleRepository: false,
+  });
+  const checkout = selectRepositoryCheckout(executionRepository, contract.checkoutId, { allowArchived: true });
+  const status = repositoryGitStatus(checkout);
+  if (!status.branch) throw new Error(`WORKTREE_DETACHED: ${contract.checkoutId} has no branch`);
+  const at = new Date().toISOString();
+  const managedWorktree = Boolean(contract.worktreeRef)
+    && resolve(contract.worktreeRef!) === resolve(checkout.canonicalRoot)
+    && resolve(checkout.canonicalRoot) !== resolve(input.repository.canonicalRoot);
+  return writeWorkHandle(input.controllerHome, {
+    schemaVersion: 1,
+    workId: input.workId,
+    sessionId: input.identity.sessionId,
+    principalId: input.identity.principalId,
+    repositoryId: input.repository.repoId,
+    checkoutId: contract.checkoutId,
+    worktreePath: checkout.canonicalRoot,
+    branch: status.branch,
+    sourceCheckoutId: input.repository.activeCheckoutId,
+    managedWorktree,
+    workContractId: contract.workId,
+    baseCommit: contract.baseRevision ?? status.head ?? undefined,
+    deliveryBaseCommit: contract.baseRevision ?? status.head ?? undefined,
+    expectedHead: status.head ?? contract.baseRevision,
+    permissionSnapshotVersion: currentPermissionSnapshotVersion(input.controllerHome, input.repository.repoId),
+    state: 'prepared',
+    createdAt: at,
+    updatedAt: at,
+    finalization: {
+      validation: 'pending',
+      commit: 'pending',
+      merge: 'pending',
+      branchCleanup: 'pending',
+      worktreeCleanup: 'pending',
+    },
+    cleanupResponsibility: { owner: 'work_finalizer', registeredAt: at },
+  });
+}
+
+/**
+ * Rebinds the durable WorkHandle to the Controller session that has already
+ * been admitted by the ControllerSession authority. The compare-and-swap
+ * revision on the read handle preserves fail-closed concurrent ownership.
+ */
+export function rebindRepositoryWorkHandleControllerIdentity(input: {
+  controllerHome: string;
+  repositoryId: string;
+  workId: string;
+  identity: RepositoryWorkHandleControllerIdentity;
+}): WorkHandleState | undefined {
+  const existing = readWorkHandle(input.controllerHome, input.repositoryId, input.workId);
+  if (!existing) return undefined;
+  if (existing.principalId === input.identity.principalId && existing.sessionId === input.identity.sessionId) return existing;
+  return writeWorkHandle(input.controllerHome, {
+    ...existing,
+    principalId: input.identity.principalId,
+    sessionId: input.identity.sessionId,
+  });
+}

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 '../../evidence/process-check-execution';
 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);
+}