@moretea-labs/forge 1.7.0 → 1.7.1

package/src/runtime/control-plane/facade/work-contract-store.ts

@@ -12,6 +12,7 @@ import {
   writeControlPlaneRecordWithinTransaction,
 } from '../persistence/sqlite-store';
 import { assertWorkAdmissionAllowed } from './work-admission-policy';
+import { phaseIndex, suggestedActionsForStatus, transitionPhaseEvidence, validateWorkSemanticTransition, validateWorkSemantics } from './work-state-machine';
 import {
   type EvidenceRef,
   type CompletionOutcome,
@@ -32,7 +33,6 @@ import {
   type WorkPhaseEvidenceState,
   type WorkContractStore,
   isDirectEditWorkCompletionReceipt,
-  isRemoteEffectCompletionReceipt,
   isRepositoryCompletionReceipt,
   isTerminalWorkContractStatus,
 } from './types';
@@ -173,10 +173,6 @@ function inferredEvidenceState(status: WorkContractStatus): EvidenceState {
   return 'none';
 }
 
-function phaseIndex(phase: WorkPhase): number {
-  return ['implementation', 'verification', 'delivery', 'cleanup'].indexOf(phase);
-}
-
 function legacyPhaseEvidence(
   contract: Pick<WorkContract, 'phase' | 'status' | 'evidenceRefs' | 'completionReceipt' | 'updatedAt'>,
   source: WorkPhaseEvidence['source'] = 'legacy_inferred',
@@ -207,210 +203,6 @@ function legacyPhaseEvidence(
   })) as WorkPhaseEvidenceMap;
 }
 
-function transitionPhaseEvidence(
-  current: Pick<WorkContract, 'phaseEvidence' | 'evidenceRefs'>,
-  targetPhase: WorkPhase,
-  input: {
-    status: WorkContractStatus;
-    summary: string;
-    evidenceRefs?: EvidenceRef[];
-    recordedAt: string;
-    source?: WorkPhaseEvidence['source'];
-  },
-): WorkPhaseEvidenceMap {
-  const targetIndex = phaseIndex(targetPhase);
-  const evidenceRefs = (input.evidenceRefs ?? current.evidenceRefs).slice(0, 20);
-  const source = input.source ?? 'recorded';
-  const phaseEvidence = { ...current.phaseEvidence };
-  for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
-    const index = phaseIndex(phase);
-    if (index < targetIndex) {
-      phaseEvidence[phase] = {
-        state: ['satisfied', 'skipped'].includes(phaseEvidence[phase].state) ? phaseEvidence[phase].state : 'satisfied',
-        source,
-        summary: `Advanced to ${targetPhase}: ${input.summary}`.slice(0, 1_000),
-        evidenceRefs,
-        recordedAt: input.recordedAt,
-      };
-    } else if (index > targetIndex) {
-      phaseEvidence[phase] = {
-        state: 'pending',
-        source,
-        summary: `Waiting for Work phase ${phase}.`,
-        evidenceRefs: [],
-        recordedAt: input.recordedAt,
-      };
-    }
-  }
-  phaseEvidence[targetPhase] = {
-    state: input.status === 'failed'
-      ? 'failed'
-      : input.status === 'cancelled'
-        ? 'skipped'
-        : input.status === 'blocked' || input.status === 'ready'
-          ? 'blocked'
-          : 'active',
-    source,
-    summary: input.summary.trim().slice(0, 1_000) || `Work entered ${targetPhase}.`,
-    evidenceRefs,
-    recordedAt: input.recordedAt,
-  };
-  return phaseEvidence;
-}
-
-function validateWorkSemantics(contract: WorkContract): WorkContract {
-  if (!contract.objective.trim()) throw new Error('WORK_OBJECTIVE_REQUIRED');
-  if (contract.status === 'completed' && !contract.completionReceipt) {
-    throw new Error('WORK_COMPLETION_RECEIPT_REQUIRED');
-  }
-  const currentPhaseIndex = phaseIndex(contract.phase);
-  for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
-    const checkpoint = contract.phaseEvidence?.[phase];
-    if (!checkpoint) throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
-    const index = phaseIndex(phase);
-    if (index < currentPhaseIndex && !['satisfied', 'skipped'].includes(checkpoint.state)) {
-      throw new Error(`WORK_PHASE_EVIDENCE_PREVIOUS_NOT_SATISFIED: ${phase}`);
-    }
-    if (index === currentPhaseIndex && checkpoint.state === 'pending') {
-      throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
-    }
-    if (index > currentPhaseIndex && checkpoint.state !== 'pending') {
-      throw new Error(`WORK_PHASE_EVIDENCE_FUTURE_NOT_PENDING: ${phase}`);
-    }
-  }
-  if (contract.completionReceipt) {
-    const receipt = contract.completionReceipt;
-    if (receipt.workId !== contract.workId) throw new Error('WORK_COMPLETION_RECEIPT_IDENTITY_MISMATCH');
-    if (isRepositoryCompletionReceipt(receipt)) {
-      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
-      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
-      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
-    } else if (isDirectEditWorkCompletionReceipt(receipt)) {
-      const directEditAuthorityCount = Number(Boolean(receipt.editSessionId?.trim())) + Number(Boolean(receipt.reconciliationId?.trim()));
-      if (directEditAuthorityCount !== 1) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_AUTHORITY_REQUIRED');
-      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
-      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
-      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
-      if (!['repository_change', 'completed_no_change'].includes(contract.workKind)) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_KIND_REQUIRED');
-      const expectedOutcome = contract.workKind === 'completed_no_change' ? 'completed_no_change' : 'completed_changed';
-      if (contract.completionOutcome !== expectedOutcome) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_OUTCOME_REQUIRED');
-    } else if (isRemoteEffectCompletionReceipt(receipt)) {
-      if (contract.workKind !== 'remote_effect') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_KIND_REQUIRED');
-      if (contract.completionOutcome !== 'completed_remote') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_OUTCOME_REQUIRED');
-      if (!receipt.pluginId.trim() || !receipt.actionId.trim() || !receipt.requestId.trim() || !receipt.semanticKey.trim() || !receipt.resultDigest.trim()) {
-        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_IDENTITY_REQUIRED');
-      }
-    } else {
-      if (contract.workKind !== 'local_effect') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_KIND_REQUIRED');
-      if (contract.completionOutcome !== 'completed_local') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_OUTCOME_REQUIRED');
-      if (!receipt.operation.trim() || !receipt.target.id.trim()) throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_TARGET_REQUIRED');
-    }
-    if (contract.status !== 'completed') throw new Error('WORK_COMPLETION_RECEIPT_REQUIRES_COMPLETED_WORK');
-    for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
-      if (!['satisfied', 'skipped'].includes(contract.phaseEvidence[phase].state)) {
-        throw new Error(`WORK_COMPLETION_PHASE_NOT_SATISFIED: ${phase}`);
-      }
-    }
-    for (const phase of ['delivery', 'cleanup'] as WorkPhase[]) {
-      if (contract.phaseEvidence[phase].receiptId !== receipt.receiptId) {
-        throw new Error(`WORK_COMPLETION_PHASE_RECEIPT_MISMATCH: ${phase}`);
-      }
-    }
-  }
-  const outcome = contract.completionOutcome;
-  if (!outcome) return contract;
-  if (contract.status !== 'completed' || !contract.completionReceipt) {
-    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires a completed Work receipt`);
-  }
-  if (contract.dispatchState !== 'terminal') {
-    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires terminal dispatch`);
-  }
-  if (contract.evidenceState !== 'valid') {
-    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires valid evidence`);
-  }
-  if (outcome === 'completed_changed' && contract.workKind !== 'repository_change') {
-    throw new Error('WORK_SEMANTICS_INVALID: completed_changed requires repository_change WorkKind');
-  }
-  if (outcome === 'completed_no_change' && contract.workKind !== 'completed_no_change') {
-    throw new Error('WORK_SEMANTICS_INVALID: completed_no_change requires completed_no_change WorkKind');
-  }
-  if (outcome === 'completed_local' && contract.workKind !== 'local_effect') {
-    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires local_effect WorkKind');
-  }
-  if (outcome === 'completed_local' && contract.completionReceipt?.source !== 'local_effect') {
-    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires a local_effect completion receipt');
-  }
-  if (outcome === 'completed_remote' && contract.workKind !== 'remote_effect') {
-    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires remote_effect WorkKind');
-  }
-  if (outcome === 'completed_remote' && contract.completionReceipt?.source !== 'remote_effect') {
-    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires a remote_effect completion receipt');
-  }
-  if (outcome === 'superseded' && contract.workKind !== 'superseded') {
-    throw new Error('WORK_SEMANTICS_INVALID: superseded requires superseded WorkKind');
-  }
-  return contract;
-}
-
-const DISPATCH_TRANSITIONS: Readonly<Record<DispatchState, readonly DispatchState[]>> = {
-  not_dispatched: ['not_dispatched', 'claimed', 'launching', 'running', 'blocked', 'terminal'],
-  claimed: ['claimed', 'launching', 'running', 'blocked', 'terminal'],
-  launching: ['launching', 'running', 'blocked', 'terminal'],
-  running: ['running', 'blocked', 'terminal'],
-  blocked: ['blocked', 'claimed', 'launching', 'running', 'terminal'],
-  terminal: ['terminal'],
-};
-
-const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceState[]>> = {
-  none: ['none', 'partial', 'valid', 'failed'],
-  partial: ['partial', 'valid', 'stale', 'contradictory', 'failed'],
-  valid: ['valid', 'stale', 'contradictory', 'failed'],
-  stale: ['stale', 'partial', 'valid', 'contradictory', 'failed'],
-  contradictory: ['contradictory', 'partial', 'valid', 'failed'],
-  failed: ['failed', 'partial', 'valid', 'contradictory'],
-};
-
-function validateWorkSemanticTransition(
-  current: WorkContract,
-  next: WorkContract,
-  options: { allowRetainedCancelledResume?: boolean } = {},
-): WorkContract {
-  const retryingFailedWork = current.status === 'failed'
-    && !current.completionOutcome
-    && ['claimed', 'launching', 'running', 'blocked'].includes(next.dispatchState);
-  const resumingRetainedCancelledWork = options.allowRetainedCancelledResume === true
-    && current.status === 'cancelled'
-    && current.dispatchState === 'terminal'
-    && current.phase === 'cleanup'
-    && current.phaseEvidence.cleanup.state === 'skipped'
-    && !current.completionReceipt
-    && !current.completionOutcome
-    && next.status === 'running'
-    && next.dispatchState === 'running'
-    && next.phase === 'implementation';
-  if (!retryingFailedWork && !resumingRetainedCancelledWork && !DISPATCH_TRANSITIONS[current.dispatchState].includes(next.dispatchState)) {
-    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: dispatch ${current.dispatchState} -> ${next.dispatchState}`);
-  }
-  if (!EVIDENCE_TRANSITIONS[current.evidenceState].includes(next.evidenceState)) {
-    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: evidence ${current.evidenceState} -> ${next.evidenceState}`);
-  }
-  if (current.completionOutcome && current.completionOutcome !== next.completionOutcome) {
-    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: completion outcome ${current.completionOutcome} is immutable`);
-  }
-  if ((current.lifecycleRole ?? 'primary') !== (next.lifecycleRole ?? 'primary')) {
-    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: lifecycleRole is immutable');
-  }
-  if (current.parentWorkId !== next.parentWorkId) {
-    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: parentWorkId is immutable');
-  }
-  return next;
-}
-
-function suggestedActionsForStatus(status: WorkContractStatus, actions: readonly SuggestedNextAction[]): SuggestedNextAction[] {
-  if (status === 'completed' || status === 'cancelled') return [];
-  return actions.slice(0, 8);
-}
-
 function sqliteBacked(options: WorkContractStoreOptions): options is WorkContractStoreOptions & { controllerHome: string; repoId: string } {
   // A caller-provided root is a test/portable compatibility store.  Runtime
   // controller state always carries controllerHome + repoId and is SQLite.
@@ -805,6 +597,8 @@ function wasPausedByRuntimeReconciliation(contract: WorkContract): boolean {
 
 function hasReviewableWorkOutput(contract: WorkContract): boolean {
   if (contract.checkRefs.length > 0 || contract.handoffRefs.length > 0) return true;
+  if ((contract.scopeEvidence?.inspectedPaths.length ?? 0) > 0) return true;
+  if ((contract.readOnlyReviewEvidence?.inspectedPaths.length ?? 0) > 0 || (contract.readOnlyReviewEvidence?.findings.length ?? 0) > 0) return true;
   return contract.evidenceRefs.some((evidence) =>
     Boolean(evidence.artifactId || evidence.evidenceId)
     || !SYSTEM_ONLY_EVIDENCE_TITLES.has(evidence.title));

package/src/runtime/control-plane/facade/work-state-machine.ts

@@ -0,0 +1,250 @@
+import {
+  isDirectEditWorkCompletionReceipt,
+  isReadOnlyReviewCompletionReceipt,
+  isRemoteEffectCompletionReceipt,
+  isRepositoryCompletionReceipt,
+  type DispatchState,
+  type EvidenceRef,
+  type EvidenceState,
+  type SuggestedNextAction,
+  type WorkContract,
+  type WorkContractStatus,
+  type WorkPhase,
+  type WorkPhaseEvidence,
+  type WorkPhaseEvidenceMap,
+} from './types';
+
+export function phaseIndex(phase: WorkPhase): number {
+  return ['implementation', 'verification', 'delivery', 'cleanup'].indexOf(phase);
+}
+
+export function transitionPhaseEvidence(
+  current: Pick<WorkContract, 'phaseEvidence' | 'evidenceRefs'>,
+  targetPhase: WorkPhase,
+  input: {
+    status: WorkContractStatus;
+    summary: string;
+    evidenceRefs?: EvidenceRef[];
+    recordedAt: string;
+    source?: WorkPhaseEvidence['source'];
+  },
+): WorkPhaseEvidenceMap {
+  const targetIndex = phaseIndex(targetPhase);
+  const evidenceRefs = (input.evidenceRefs ?? current.evidenceRefs).slice(0, 20);
+  const source = input.source ?? 'recorded';
+  const phaseEvidence = { ...current.phaseEvidence };
+  for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
+    const index = phaseIndex(phase);
+    if (index < targetIndex) {
+      phaseEvidence[phase] = {
+        state: ['satisfied', 'skipped'].includes(phaseEvidence[phase].state) ? phaseEvidence[phase].state : 'satisfied',
+        source,
+        summary: `Advanced to ${targetPhase}: ${input.summary}`.slice(0, 1_000),
+        evidenceRefs,
+        recordedAt: input.recordedAt,
+      };
+    } else if (index > targetIndex) {
+      phaseEvidence[phase] = {
+        state: 'pending',
+        source,
+        summary: `Waiting for Work phase ${phase}.`,
+        evidenceRefs: [],
+        recordedAt: input.recordedAt,
+      };
+    }
+  }
+  phaseEvidence[targetPhase] = {
+    state: input.status === 'failed'
+      ? 'failed'
+      : input.status === 'cancelled'
+        ? 'skipped'
+        : input.status === 'blocked' || input.status === 'ready'
+          ? 'blocked'
+          : 'active',
+    source,
+    summary: input.summary.trim().slice(0, 1_000) || `Work entered ${targetPhase}.`,
+    evidenceRefs,
+    recordedAt: input.recordedAt,
+  };
+  return phaseEvidence;
+}
+
+export function validateWorkSemantics(contract: WorkContract): WorkContract {
+  if (!contract.objective.trim()) throw new Error('WORK_OBJECTIVE_REQUIRED');
+  if (contract.status === 'completed' && !contract.completionReceipt) {
+    throw new Error('WORK_COMPLETION_RECEIPT_REQUIRED');
+  }
+  const currentPhaseIndex = phaseIndex(contract.phase);
+  for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
+    const checkpoint = contract.phaseEvidence?.[phase];
+    if (!checkpoint) throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
+    const index = phaseIndex(phase);
+    if (index < currentPhaseIndex && !['satisfied', 'skipped'].includes(checkpoint.state)) {
+      throw new Error(`WORK_PHASE_EVIDENCE_PREVIOUS_NOT_SATISFIED: ${phase}`);
+    }
+    if (index === currentPhaseIndex && checkpoint.state === 'pending') {
+      throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
+    }
+    if (index > currentPhaseIndex && checkpoint.state !== 'pending') {
+      throw new Error(`WORK_PHASE_EVIDENCE_FUTURE_NOT_PENDING: ${phase}`);
+    }
+  }
+  if (contract.completionReceipt) {
+    const receipt = contract.completionReceipt;
+    if (receipt.workId !== contract.workId) throw new Error('WORK_COMPLETION_RECEIPT_IDENTITY_MISMATCH');
+    if (isRepositoryCompletionReceipt(receipt)) {
+      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
+      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
+      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
+    } else if (isDirectEditWorkCompletionReceipt(receipt)) {
+      const directEditAuthorityCount = Number(Boolean(receipt.editSessionId?.trim())) + Number(Boolean(receipt.reconciliationId?.trim()));
+      if (directEditAuthorityCount !== 1) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_AUTHORITY_REQUIRED');
+      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
+      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
+      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
+      if (!['repository_change', 'completed_no_change'].includes(contract.workKind)) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_KIND_REQUIRED');
+      const expectedOutcome = contract.workKind === 'completed_no_change' ? 'completed_no_change' : 'completed_changed';
+      if (contract.completionOutcome !== expectedOutcome) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_OUTCOME_REQUIRED');
+    } else if (isReadOnlyReviewCompletionReceipt(receipt)) {
+      if (contract.workKind !== 'read_only_review') throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_no_change') throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_OUTCOME_REQUIRED');
+      if (!receipt.baseRevision.trim() || receipt.baseRevision !== receipt.sourceRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_SOURCE_REQUIRED');
+      if (contract.baseRevision && receipt.baseRevision !== contract.baseRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_BASE_MISMATCH');
+      if (receipt.workspaceChangedPaths.length !== 0) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_WORKSPACE_CHANGED');
+      const reviewEvidence = contract.readOnlyReviewEvidence;
+      if (!reviewEvidence || reviewEvidence.sourceRevision !== receipt.sourceRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_EVIDENCE_REQUIRED');
+      if (reviewEvidence.findings.length !== 0 || receipt.findingCount !== 0 || receipt.inspectedPaths.length === 0) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_CLEAN_SCOPE_REQUIRED');
+      const evidencePaths = [...new Set(reviewEvidence.inspectedPaths)].sort();
+      const receiptPaths = [...new Set(receipt.inspectedPaths)].sort();
+      if (evidencePaths.length !== receiptPaths.length || evidencePaths.some((path, index) => path !== receiptPaths[index])) {
+        throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_SCOPE_MISMATCH');
+      }
+      if (reviewEvidence.workspaceFingerprint && receipt.workspaceFingerprint && reviewEvidence.workspaceFingerprint !== receipt.workspaceFingerprint) {
+        throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_WORKSPACE_MISMATCH');
+      }
+    } else if (isRemoteEffectCompletionReceipt(receipt)) {
+      if (contract.workKind !== 'remote_effect') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_remote') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_OUTCOME_REQUIRED');
+      const authority = receipt.authority ?? 'plugin_action';
+      if (!receipt.actionId.trim() || !receipt.requestId.trim() || !receipt.semanticKey.trim() || !receipt.resultDigest.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_IDENTITY_REQUIRED');
+      }
+      if (authority === 'plugin_action' && !receipt.pluginId?.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_PLUGIN_IDENTITY_REQUIRED');
+      }
+      if (authority === 'repository_process' && !receipt.processId?.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_PROCESS_IDENTITY_REQUIRED');
+      }
+    } else {
+      if (contract.workKind !== 'local_effect') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_local') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_OUTCOME_REQUIRED');
+      if (!receipt.operation.trim() || !receipt.target.id.trim()) throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_TARGET_REQUIRED');
+    }
+    if (contract.status !== 'completed') throw new Error('WORK_COMPLETION_RECEIPT_REQUIRES_COMPLETED_WORK');
+    for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
+      if (!['satisfied', 'skipped'].includes(contract.phaseEvidence[phase].state)) {
+        throw new Error(`WORK_COMPLETION_PHASE_NOT_SATISFIED: ${phase}`);
+      }
+    }
+    for (const phase of ['delivery', 'cleanup'] as WorkPhase[]) {
+      if (contract.phaseEvidence[phase].receiptId !== receipt.receiptId) {
+        throw new Error(`WORK_COMPLETION_PHASE_RECEIPT_MISMATCH: ${phase}`);
+      }
+    }
+  }
+  const outcome = contract.completionOutcome;
+  if (!outcome) return contract;
+  if (contract.status !== 'completed' || !contract.completionReceipt) {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires a completed Work receipt`);
+  }
+  if (contract.dispatchState !== 'terminal') {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires terminal dispatch`);
+  }
+  if (contract.evidenceState !== 'valid') {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires valid evidence`);
+  }
+  if (outcome === 'completed_changed' && contract.workKind !== 'repository_change') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_changed requires repository_change WorkKind');
+  }
+  if (outcome === 'completed_no_change' && !['completed_no_change', 'read_only_review'].includes(contract.workKind)) {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_no_change requires completed_no_change or read_only_review WorkKind');
+  }
+  if (outcome === 'completed_no_change' && contract.workKind === 'read_only_review' && contract.completionReceipt?.source !== 'read_only_review') {
+    throw new Error('WORK_SEMANTICS_INVALID: read_only_review completed_no_change requires a read_only_review completion receipt');
+  }
+  if (outcome === 'completed_local' && contract.workKind !== 'local_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires local_effect WorkKind');
+  }
+  if (outcome === 'completed_local' && contract.completionReceipt?.source !== 'local_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires a local_effect completion receipt');
+  }
+  if (outcome === 'completed_remote' && contract.workKind !== 'remote_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires remote_effect WorkKind');
+  }
+  if (outcome === 'completed_remote' && contract.completionReceipt?.source !== 'remote_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires a remote_effect completion receipt');
+  }
+  if (outcome === 'superseded' && contract.workKind !== 'superseded') {
+    throw new Error('WORK_SEMANTICS_INVALID: superseded requires superseded WorkKind');
+  }
+  return contract;
+}
+
+const DISPATCH_TRANSITIONS: Readonly<Record<DispatchState, readonly DispatchState[]>> = {
+  not_dispatched: ['not_dispatched', 'claimed', 'launching', 'running', 'blocked', 'terminal'],
+  claimed: ['claimed', 'launching', 'running', 'blocked', 'terminal'],
+  launching: ['launching', 'running', 'blocked', 'terminal'],
+  running: ['running', 'blocked', 'terminal'],
+  blocked: ['blocked', 'claimed', 'launching', 'running', 'terminal'],
+  terminal: ['terminal'],
+};
+
+const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceState[]>> = {
+  none: ['none', 'partial', 'valid', 'failed'],
+  partial: ['partial', 'valid', 'stale', 'contradictory', 'failed'],
+  valid: ['valid', 'stale', 'contradictory', 'failed'],
+  stale: ['stale', 'partial', 'valid', 'contradictory', 'failed'],
+  contradictory: ['contradictory', 'partial', 'valid', 'failed'],
+  failed: ['failed', 'partial', 'valid', 'contradictory'],
+};
+
+export function validateWorkSemanticTransition(
+  current: WorkContract,
+  next: WorkContract,
+  options: { allowRetainedCancelledResume?: boolean } = {},
+): WorkContract {
+  const retryingFailedWork = current.status === 'failed'
+    && !current.completionOutcome
+    && ['claimed', 'launching', 'running', 'blocked'].includes(next.dispatchState);
+  const resumingRetainedCancelledWork = options.allowRetainedCancelledResume === true
+    && current.status === 'cancelled'
+    && current.dispatchState === 'terminal'
+    && current.phase === 'cleanup'
+    && current.phaseEvidence.cleanup.state === 'skipped'
+    && !current.completionReceipt
+    && !current.completionOutcome
+    && next.status === 'running'
+    && next.dispatchState === 'running'
+    && next.phase === 'implementation';
+  if (!retryingFailedWork && !resumingRetainedCancelledWork && !DISPATCH_TRANSITIONS[current.dispatchState].includes(next.dispatchState)) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: dispatch ${current.dispatchState} -> ${next.dispatchState}`);
+  }
+  if (!EVIDENCE_TRANSITIONS[current.evidenceState].includes(next.evidenceState)) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: evidence ${current.evidenceState} -> ${next.evidenceState}`);
+  }
+  if (current.completionOutcome && current.completionOutcome !== next.completionOutcome) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: completion outcome ${current.completionOutcome} is immutable`);
+  }
+  if ((current.lifecycleRole ?? 'primary') !== (next.lifecycleRole ?? 'primary')) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: lifecycleRole is immutable');
+  }
+  if (current.parentWorkId !== next.parentWorkId) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: parentWorkId is immutable');
+  }
+  return next;
+}
+
+export function suggestedActionsForStatus(status: WorkContractStatus, actions: readonly SuggestedNextAction[]): SuggestedNextAction[] {
+  if (status === 'completed' || status === 'cancelled') return [];
+  return actions.slice(0, 8);
+}

package/src/runtime/control-plane/global-scheduler/maintenance.ts

@@ -11,7 +11,7 @@ import {
   finishControllerRoundRelayDispatch,
 } from '../facade/controller-round-relay';
 import { assertAutomatedOperationAllowed } from '../governance/external-effects';
-import { runStandaloneChatgptPrompt } from '../launcher/chatgpt-work-continuation';
+import { runWorkChatgptContinuation } from '../launcher/chatgpt-work-continuation';
 
 export async function runSchedulerPeriodicCleanup(input: {
   controllerHome: string;
@@ -83,13 +83,13 @@ export async function runSchedulerValidationReconciliation(input: {
 export async function runSchedulerControllerRoundRecovery(input: {
   controllerHome: string;
   nowMs: number;
-  repositories: readonly Pick<RepositoryRecord, 'repoId'>[];
+  repositories: readonly Pick<RepositoryRecord, 'repoId' | 'canonicalRoot' | 'localRoot'>[];
   graceMs?: number;
   maxRecoveries?: number;
-  dispatchPrompt?: typeof runStandaloneChatgptPrompt;
+  dispatchPrompt?: typeof runWorkChatgptContinuation;
   authorizeWake?: typeof assertAutomatedOperationAllowed;
 }): Promise<{ claimed: number; dispatched: number; failed: number }> {
-  const dispatchPrompt = input.dispatchPrompt ?? runStandaloneChatgptPrompt;
+  const dispatchPrompt = input.dispatchPrompt ?? runWorkChatgptContinuation;
   const authorizeWake = input.authorizeWake ?? assertAutomatedOperationAllowed;
   const maxRecoveries = Math.max(1, Math.min(Math.trunc(input.maxRecoveries ?? 2), 8));
   let claimed = 0;
@@ -116,8 +116,9 @@ export async function runSchedulerControllerRoundRecovery(input: {
         const result = await dispatchPrompt({
           controllerHome: input.controllerHome,
           repoId: repository.repoId,
-          scopeId: `controller-relay:${record.relayScopeId}`,
-          prompt: buildControllerRoundRelayPrompt(store, record),
+          repoRoot: repository.canonicalRoot ?? repository.localRoot,
+          workId: record.originWorkId,
+          prompt: buildControllerRoundRelayPrompt(store, record, { exactOriginWork: true }),
           browserSessionId: record.browserSessionId,
           conversationUrl: record.conversationUrl,
           model: 'gpt-5.6',
@@ -135,7 +136,13 @@ export async function runSchedulerControllerRoundRecovery(input: {
         dispatched += 1;
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        finishControllerRoundRelayDispatch(store, { workId: record.originWorkId, ok: false, error: reason });
+        finishControllerRoundRelayDispatch(store, {
+          workId: record.originWorkId,
+          ok: false,
+          error: reason,
+          recovery: true,
+          nowMs: input.nowMs,
+        });
         failed += 1;
         console.error(`[forge controller relay] stalled round recovery failed for ${record.relayScopeId}:`, reason);
       }

package/src/runtime/control-plane/global-scheduler/scheduler.ts

@@ -199,8 +199,12 @@ export class GlobalScheduler {
   ) {
     this.controllerHome = controllerHome;
     this.controllerPid = runtime.controllerPid ?? process.pid;
-    this.actors = new RepoActorRegistry(controllerHome);
     this.config = normalizeSchedulerConfig(config);
+    // The per-repository mailbox must not impose a hidden concurrency ceiling
+    // below the scheduler's global worker budget. Resource leases still serialize
+    // conflicting workspace/path/integration claims, while independent jobs in a
+    // busy single repository may use the available global worker capacity.
+    this.actors = new RepoActorRegistry(controllerHome, { maxConcurrentWorkers: this.config.maxWorkers });
     this.runtimeSourceRoot = runtime.runtimeSourceRoot ? resolve(runtime.runtimeSourceRoot) : undefined;
     this.workerEntrypoint = runtime.workerEntrypoint ? resolve(runtime.workerEntrypoint) : undefined;
     this.fatalOnTickError = runtime.fatalOnTickError === true;

package/src/runtime/control-plane/launcher/chatgpt-work-binding-store.ts

@@ -47,6 +47,19 @@ export function parseChatgptConversationIdentity(value: string): { conversationU
   return { conversationUrl: url.toString(), conversationId };
 }
 
+export function hasChatgptConversationIdentity(value: string): boolean {
+  try {
+    parseChatgptConversationIdentity(value);
+    return true;
+  } catch (error) {
+    // ChatGPT root and Project URLs are valid launch seeds, but they are not
+    // durable conversation identities. Persist only the /c/<id> URL observed
+    // after the browser confirms submission.
+    if (error instanceof Error && error.message === 'CHATGPT_WORK_CONVERSATION_ID_MISSING') return false;
+    throw error;
+  }
+}
+
 function record(options: ChatgptWorkBindingStoreOptions, workId: string) {
   return readControlPlaneRecord<ChatgptWorkConversationBinding>(
     options.controllerHome,

package/src/runtime/control-plane/launcher/chatgpt-work-continuation.ts

@@ -5,6 +5,7 @@ import { getWorkContract } from '../facade/work-contract-store';
 import {
   bindChatgptWorkConversation,
   getChatgptWorkConversationBinding,
+  hasChatgptConversationIdentity,
   parseChatgptConversationIdentity,
   rebindChatgptWorkConversation,
   type ChatgptWorkConversationBinding,
@@ -256,7 +257,7 @@ async function findChatgptIntelligenceControl(
       // Prefer the composer/main region so sidebar history cannot crowd the
       // reasoning control out of a bounded query. Keep a larger global fallback
       // for ChatGPT layouts that place the control outside <main>.
-      limit: selector.startsWith('main ') ? 80 : 240,
+      limit: chatgptAutomationControlQueryLimit(selector),
       timeout_ms: timeoutMs ?? 60_000,
     }, timeoutMs);
     const match = queryMatches(result).find((candidate) => {
@@ -268,12 +269,19 @@ async function findChatgptIntelligenceControl(
   return undefined;
 }
 
+export function chatgptAutomationControlQueryLimit(selector: string): number {
+  // Long tool-heavy conversations can contribute well over 80 buttons before
+  // the composer controls. Keep the preferred <main> scan bounded but large
+  // enough that the current reasoning control is not crowded out by history.
+  return selector.startsWith('main ') ? 160 : 320;
+}
+
 export function chatgptAutomationControlWaitBudgets(timeoutMs?: number): { waitBudgetMs: number; probeTimeoutMs: number } {
   const waitBudgetMs = Math.min(Math.max(timeoutMs ?? 30_000, 1_000), 30_000);
-  // One probe checks both the preferred <main> scope and the global fallback.
-  // Keep each selector query short enough that one slow pre-hydration pass cannot
-  // consume the whole readiness window before React exposes the reasoning control.
-  return { waitBudgetMs, probeTimeoutMs: Math.min(waitBudgetMs, 2_500) };
+  // Native Chrome attachment has a few seconds of Apple Events/DOM latency on
+  // long conversations. Keep each probe bounded while allowing a real query to
+  // complete; the total readiness window remains capped at 30 seconds.
+  return { waitBudgetMs, probeTimeoutMs: Math.min(waitBudgetMs, 5_000) };
 }
 
 async function waitForChatgptIntelligenceControl(
@@ -433,6 +441,7 @@ export function chatgptAutomationNavigationRequiresReplacement(error: unknown):
     'BROWSER_AUTOMATION_BACKGROUND_NAVIGATION_REQUIRES_REPLACEMENT',
     'PLUGIN_BROWSER_SESSION_STATE_LOST',
     'PLUGIN_SESSION_NOT_FOUND',
+    'PLUGIN_BROWSER_NATIVE_TAB_IDENTITY_UNPROVEN',
   ].some((marker) => error.message.includes(marker));
 }
 
@@ -685,7 +694,7 @@ export async function runWorkChatgptContinuation(input: WorkChatgptContinuationI
       throw new Error(`CHATGPT_WORK_CONTRACT_NOT_FOUND: ${input.repoId}:${input.workId}`);
     }
     await ensureControllerChatgptBrowser(input.controllerHome, input.workId);
-    if (seedUrl && !binding) {
+    if (seedUrl && !binding && hasChatgptConversationIdentity(seedUrl)) {
       binding = bindChatgptWorkConversation(store, {
         workId: input.workId,
         conversationUrl: seedUrl,