@moretea-labs/forge 1.6.0 → 1.7.1

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

@@ -12,16 +12,17 @@ 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,
   type DispatchState,
   type EvidenceState,
   type PolicyDecision,
-  type SubmittedWorkOperation,
   type SuggestedNextAction,
   type VerificationRecord,
   type WorkReconciliationRecord,
+  type SubmittedWorkOperation,
   type WorkContract,
   type WorkContractStatus,
   type WorkRisk,
@@ -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,191 +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): WorkContract {
-  const retryingFailedWork = current.status === 'failed'
-    && !current.completionOutcome
-    && ['claimed', 'launching', 'running', 'blocked'].includes(next.dispatchState);
-  if (!retryingFailedWork && !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 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.
@@ -429,6 +240,7 @@ function normalizeWorkContractStore(store: WorkContractStore): WorkContractStore
         workKind: legacy.workKind ?? 'repository_change',
         dispatchState: legacy.dispatchState ?? inferredDispatchState(status),
         evidenceState: legacy.evidenceState ?? inferredEvidenceState(status),
+        suggestedNextActions: suggestedActionsForStatus(status, legacy.suggestedNextActions ?? []),
         reconciliations: legacy.reconciliations ?? [],
         driver: (legacy.driver as unknown as { preferred?: string } | undefined)?.preferred === 'codex_worker'
           ? { ...legacy.driver, preferred: 'external_controller', allowWorker: false }
@@ -541,7 +353,7 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
   if (input.status === 'completed' || input.completionReceipt || input.completionOutcome) {
     throw new Error('WORK_COMPLETION_REQUIRES_RECORD_API');
   }
-  return withWorkContractStoreWrite(options, () => {
+  const create = (): WorkContract => {
     const at = input.createdAt ?? input.updatedAt ?? nowIso(options);
     const workId = sanitizeFileComponent(input.workId);
     const contract: WorkContract = validateWorkSemantics({
@@ -585,6 +397,12 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
       planStepId: input.planStepId,
       planSourceRevision: input.planSourceRevision,
       scopeSummary: input.scopeSummary?.slice(0, 1_000),
+      scopeEvidence: input.scopeEvidence ? {
+        initialLikelyPaths: [...new Set(input.scopeEvidence.initialLikelyPaths)].slice(0, 100),
+        inspectedPaths: [...new Set(input.scopeEvidence.inspectedPaths)].slice(0, 500),
+        actualChangedPaths: [...new Set(input.scopeEvidence.actualChangedPaths)].slice(0, 500),
+        recordedAt: input.scopeEvidence.recordedAt,
+      } : undefined,
       allowedPaths: (input.allowedPaths ?? []).slice(0, 50),
       forbiddenPaths: (input.forbiddenPaths ?? []).slice(0, 50),
       checks: (input.checks ?? []).slice(0, 30),
@@ -618,6 +436,23 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
       submittedOperation: input.submittedOperation,
     });
 
+    if (sqliteBacked(options)) {
+      withControlPlaneTransaction(options.controllerHome, (database) => {
+        if (readControlPlaneRecordWithinTransaction<WorkContract>(database, 'work_contract', options.repoId, contract.workId)) {
+          throw new Error(`work contract already exists: ${contract.workId}`);
+        }
+        writeControlPlaneRecordWithinTransaction(database, {
+          namespace: 'work_contract',
+          scope: options.repoId,
+          key: contract.workId,
+          schemaVersion: 2,
+          value: contract,
+          action: 'work_contract_created',
+          expectedRevision: null,
+        });
+      });
+      return contract;
+    }
     const store = readWorkContractStore(options);
     if (store.contracts.some((existing) => existing.workId === contract.workId)) {
       throw new Error(`work contract already exists: ${contract.workId}`);
@@ -629,7 +464,8 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
     };
     writeWorkContractStore(options, nextStore);
     return contract;
-  });
+  };
+  return create();
 }
 
 interface WorkRequestIndexRecord {
@@ -647,26 +483,6 @@ function workRequestIndexPath(controllerHome: string, requestId: string): string
   return join(root, `${hash}.json`);
 }
 
-export interface AcceptSubmittedWorkInput {
-  requestId: string;
-  repoId: string;
-  parentWorkId?: string;
-  semanticKey: string;
-  operation: SubmittedWorkOperation;
-  objective?: string;
-  mode?: WorkContract['mode'];
-  requestedBy?: WorkContract['requestedBy'];
-  principalId?: string;
-  controllerInstanceId?: string;
-  workKind?: WorkKind;
-  risk?: WorkRisk;
-  allowedPaths?: string[];
-  forbiddenPaths?: string[];
-  checks?: string[];
-  acceptanceCriteria?: string[];
-  constraints?: WorkContract['constraints'];
-}
-
 export function getWorkContractByRequestId(
   controllerHome: string,
   requestId: string,
@@ -687,8 +503,8 @@ export function getWorkContractByRequestId(
 }
 
 /**
- * Accept one work_submit operation as a WorkContract without creating ExecutionJobs.
- * Same controllerHome + requestId + semanticKey returns the original contract.
+ * Create or reuse the execution-child Work used by typed callers. This is not
+ * a generic MCP submission authority and never creates an ExecutionJob.
  */
 export function acceptSubmittedWorkContract(
   controllerHome: string,
@@ -696,20 +512,12 @@ export function acceptSubmittedWorkContract(
   options: WorkContractStoreOptions = {},
 ): { contract: WorkContract; deduplicated: boolean } {
   const home = ensureControllerHome(controllerHome);
-  const normalizedRequestId = input.requestId.trim();
-  if (!normalizedRequestId) {
-    throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): request_id');
-  }
-  const normalizedSemanticKey = input.semanticKey.trim();
-  if (!normalizedSemanticKey) {
-    throw new Error('INVALID_ARGUMENT: work_submit requires a semantic operation key');
-  }
-  if (!input.repoId.trim()) {
-    throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): repo_id');
-  }
-  if (!input.operation?.name?.trim()) {
-    throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): operation');
-  }
+  const requestId = input.requestId.trim();
+  const semanticKey = input.semanticKey.trim();
+  if (!requestId) throw new Error('INVALID_ARGUMENT: typed execution is missing request_id');
+  if (!semanticKey) throw new Error('INVALID_ARGUMENT: typed execution requires a semantic operation key');
+  if (!input.repoId.trim()) throw new Error('INVALID_ARGUMENT: typed execution is missing repo_id');
+  if (!input.operation?.name?.trim()) throw new Error('INVALID_ARGUMENT: typed execution is missing operation');
   const parentWorkId = input.parentWorkId?.trim() || undefined;
   if (parentWorkId) {
     const parent = getWorkContract({ controllerHome: home, repoId: input.repoId, now: options.now }, parentWorkId);
@@ -717,25 +525,17 @@ export function acceptSubmittedWorkContract(
     if (isTerminalWorkContractStatus(parent.status)) throw new Error(`PARENT_WORK_TERMINAL: ${parentWorkId}:${parent.status}`);
     if ((parent.lifecycleRole ?? 'primary') !== 'primary') throw new Error(`PARENT_WORK_NOT_PRIMARY: ${parentWorkId}`);
   }
-
-  const requestLockId = createHash('sha256').update(normalizedRequestId).digest('hex').slice(0, 24);
-  return withControllerLock(home, { scope: 'global', resource: `work-request-${requestLockId}` }, `accept-work:${normalizedRequestId}`, () => {
-    const recordPath = workRequestIndexPath(home, normalizedRequestId);
+  const lockId = createHash('sha256').update(requestId).digest('hex').slice(0, 24);
+  return withControllerLock(home, { scope: 'global', resource: `work-request-${lockId}` }, `accept-work:${requestId}`, () => {
+    const recordPath = workRequestIndexPath(home, requestId);
     if (existsSync(recordPath)) {
       const record = readJsonFile<WorkRequestIndexRecord>(recordPath);
-      if (record.repoId !== input.repoId) {
-        throw new Error(`REQUEST_ID_REPO_CONFLICT: ${normalizedRequestId} already belongs to repository ${record.repoId}`);
-      }
-      if (record.semanticKey !== normalizedSemanticKey) {
-        throw new Error(`REQUEST_ID_CONFLICT: ${normalizedRequestId} already belongs to ${record.semanticKey}`);
-      }
+      if (record.repoId !== input.repoId) throw new Error(`REQUEST_ID_REPO_CONFLICT: ${requestId} already belongs to repository ${record.repoId}`);
+      if (record.semanticKey !== semanticKey) throw new Error(`REQUEST_ID_CONFLICT: ${requestId} already belongs to ${record.semanticKey}`);
       const existing = getWorkContract({ controllerHome: home, repoId: record.repoId, now: options.now }, record.workId);
-      if (!existing) {
-        throw new Error(`WORK_ACCEPTANCE_LOST: request ${normalizedRequestId} is indexed without a readable WorkContract`);
-      }
+      if (!existing) throw new Error(`WORK_ACCEPTANCE_LOST: request ${requestId} is indexed without a readable WorkContract`);
       return { contract: existing, deduplicated: true };
     }
-
     const contract = createWorkContract({ controllerHome: home, repoId: input.repoId, now: options.now }, {
       workId: `WORK-${Date.now()}-${randomUUID().slice(0, 8)}`,
       repoId: input.repoId,
@@ -744,7 +544,7 @@ export function acceptSubmittedWorkContract(
       mode: input.mode ?? 'direct_control',
       lifecycleRole: 'execution_child',
       parentWorkId,
-      objective: (input.objective ?? `Accepted operation ${input.operation.name}`).slice(0, 2_000),
+      objective: (input.objective ?? `Typed operation ${input.operation.name}`).slice(0, 2_000),
       acceptanceCriteria: input.acceptanceCriteria ?? [],
       workKind: input.workKind,
       risk: input.risk,
@@ -754,13 +554,9 @@ export function acceptSubmittedWorkContract(
       checks: input.checks ?? [],
       requestedBy: input.requestedBy ?? 'chatgpt',
       status: 'open',
-      requestId: normalizedRequestId,
+      requestId,
       submittedOperation: input.operation,
-      driver: {
-        preferred: 'external_controller',
-        allowWorker: false,
-        allowDirectEdit: input.operation.mode === 'readonly' || input.operation.mode === 'mutating',
-      },
+      driver: { preferred: 'external_controller', allowWorker: false, allowDirectEdit: input.operation.mode === 'readonly' || input.operation.mode === 'mutating' },
       suggestedNextActions: [{
         label: 'Claim controller ownership',
         tool: 'rh_work',
@@ -770,15 +566,7 @@ export function acceptSubmittedWorkContract(
         reason: 'Claim this Work before launching an external SuperController or Process Runtime command.',
       }],
     });
-
-    writeJsonAtomic(recordPath, {
-      requestId: normalizedRequestId,
-      repoId: input.repoId,
-      workId: contract.workId,
-      semanticKey: normalizedSemanticKey,
-      createdAt: contract.createdAt,
-    } satisfies WorkRequestIndexRecord);
-
+    writeJsonAtomic(recordPath, { requestId, repoId: input.repoId, workId: contract.workId, semanticKey, createdAt: contract.createdAt } satisfies WorkRequestIndexRecord);
     return { contract, deduplicated: false };
   });
 }
@@ -809,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));
@@ -965,6 +755,7 @@ function updateWorkContractInternal(
   patch: Partial<Omit<WorkContract, 'schemaVersion' | 'workId' | 'repoId' | 'createdAt'>>,
   allowCompletionWrite: boolean,
   allowPhaseWrite = false,
+  allowRetainedCancelledResume = false,
 ): WorkContract {
   return withWorkContractStoreWrite(options, () => {
     const sanitizedId = sanitizeFileComponent(workId);
@@ -1022,13 +813,13 @@ function updateWorkContractInternal(
     completionOutcome: patch.completionOutcome ?? current.completionOutcome,
     evidenceRefs: (patch.evidenceRefs ?? current.evidenceRefs).slice(0, current.evidencePolicy.maxEvidenceRefs),
     handoffRefs: (patch.handoffRefs ?? current.handoffRefs).slice(0, 20),
-    suggestedNextActions: (patch.suggestedNextActions ?? current.suggestedNextActions).slice(0, 8),
+    suggestedNextActions: suggestedActionsForStatus(patch.status ?? current.status, patch.suggestedNextActions ?? current.suggestedNextActions),
     policyDecisions: (patch.policyDecisions ?? current.policyDecisions).slice(0, 20),
     checkRefs: (patch.checkRefs ?? current.checkRefs).slice(0, 50),
     reconciliations: (patch.reconciliations ?? current.reconciliations ?? []).slice(0, 20),
     objective: (patch.objective ?? current.objective).slice(0, 2_000),
     continuationPrompt: (patch.continuationPrompt ?? current.continuationPrompt)?.slice(0, 2_000),
-    }));
+    }), { allowRetainedCancelledResume });
     const contracts = [...store.contracts];
     contracts[index] = next;
     writeWorkContractStore(options, { schemaVersion: 2, updatedAt: at, contracts });
@@ -1044,6 +835,83 @@ export function updateWorkContract(
   return updateWorkContractInternal(options, workId, patch, false);
 }
 
+/**
+ * Reopen one explicitly retained cancelled repository Work after the facade has
+ * reauthenticated the same principal and revalidated physical Work ownership.
+ * Generic mutation APIs intentionally cannot perform terminal -> running.
+ */
+export function resumeRetainedCancelledWorkContract(
+  options: WorkContractStoreOptions,
+  workId: string,
+  input: {
+    principalId: string;
+    controllerInstanceId: string;
+    summary: string;
+    checkoutId?: string;
+    worktreeRef?: string;
+  },
+): WorkContract {
+  const current = getWorkContract(options, workId);
+  if (!current) throw new Error(`work contract not found: ${workId}`);
+  if (current.status !== 'cancelled' || current.dispatchState !== 'terminal' || current.phase !== 'cleanup') {
+    throw new Error(`WORK_CANCELLED_RESUME_STATUS_INVALID: ${workId}`);
+  }
+  if (current.workKind !== 'repository_change') throw new Error(`WORK_CANCELLED_RESUME_KIND_INVALID: ${workId}`);
+  if (current.completionReceipt || current.completionOutcome) throw new Error(`WORK_CANCELLED_RESUME_COMPLETION_CONFLICT: ${workId}`);
+  if (current.phaseEvidence.cleanup.state !== 'skipped' || current.phaseEvidence.cleanup.source !== 'recorded') {
+    throw new Error(`WORK_CANCELLED_RESUME_HISTORY_AMBIGUOUS: ${workId}`);
+  }
+  const originalPrincipal = current.principalId?.trim();
+  if (!originalPrincipal || originalPrincipal !== input.principalId.trim()) {
+    throw new Error(`WORK_CANCELLED_RESUME_PRINCIPAL_MISMATCH: ${workId}`);
+  }
+  const at = nowIso(options);
+  const evidenceRefs = [...current.evidenceRefs, {
+    title: 'explicit current-user Work reauthorization',
+    summary: input.summary.trim().slice(0, 1_000),
+    detailLevel: 'summary' as const,
+  }].slice(-current.evidencePolicy.maxEvidenceRefs);
+  const phaseEvidence = transitionPhaseEvidence({ ...current, evidenceRefs }, 'implementation', {
+    status: 'running',
+    summary: input.summary,
+    evidenceRefs,
+    recordedAt: at,
+    source: 'recorded',
+  });
+  return updateWorkContractInternal(options, workId, {
+    status: 'running',
+    phase: 'implementation',
+    phaseEvidence,
+    dispatchState: 'running',
+    evidenceRefs,
+    checkoutId: input.checkoutId ?? current.checkoutId,
+    worktreeRef: input.worktreeRef ?? current.worktreeRef,
+    controllerInstanceId: input.controllerInstanceId,
+    continuationPrompt: input.summary,
+  }, false, true, true);
+}
+
+/** Merge non-authoritative discovery/change evidence without changing policy fences. */
+export function recordWorkScopeEvidence(
+  options: WorkContractStoreOptions,
+  workId: string,
+  input: { initialLikelyPaths?: string[]; inspectedPaths?: string[]; actualChangedPaths?: string[] },
+): WorkContract {
+  const current = getWorkContract(options, workId);
+  if (!current) throw new Error(`work contract not found: ${workId}`);
+  const previous = current.scopeEvidence ?? {
+    initialLikelyPaths: [], inspectedPaths: [], actualChangedPaths: [], recordedAt: current.createdAt,
+  };
+  return updateWorkContract(options, workId, {
+    scopeEvidence: {
+      initialLikelyPaths: [...new Set([...previous.initialLikelyPaths, ...(input.initialLikelyPaths ?? [])])].slice(0, 100),
+      inspectedPaths: [...new Set([...previous.inspectedPaths, ...(input.inspectedPaths ?? [])])].slice(0, 500),
+      actualChangedPaths: [...new Set([...previous.actualChangedPaths, ...(input.actualChangedPaths ?? [])])].slice(0, 500),
+      recordedAt: nowIso(options),
+    },
+  });
+}
+
 export function transitionWorkContractPhase(
   options: WorkContractStoreOptions,
   workId: string,
@@ -1126,6 +994,9 @@ export function recordWorkCompletionReceipt(
     return current;
   }
   const recordedAt = receipt.recordedAt;
+  const receiptChangedPaths = isRepositoryCompletionReceipt(receipt) || isDirectEditWorkCompletionReceipt(receipt)
+    ? receipt.changedPaths
+    : [];
   const phaseEvidence = Object.fromEntries((['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]).map((phase) => [phase, {
     state: 'satisfied',
     source: 'recorded',
@@ -1143,5 +1014,30 @@ export function recordWorkCompletionReceipt(
     completionOutcome,
     ...(completionWorkKind ? { workKind: completionWorkKind } : {}),
     completionReceipt: receipt,
+    scopeEvidence: {
+      initialLikelyPaths: current.scopeEvidence?.initialLikelyPaths ?? current.allowedPaths,
+      inspectedPaths: current.scopeEvidence?.inspectedPaths ?? [],
+      actualChangedPaths: [...new Set(receiptChangedPaths)].slice(0, 500),
+      recordedAt,
+    },
   }, true, true);
 }
+export interface AcceptSubmittedWorkInput {
+  requestId: string;
+  repoId: string;
+  parentWorkId?: string;
+  semanticKey: string;
+  operation: SubmittedWorkOperation;
+  objective?: string;
+  mode?: WorkContract['mode'];
+  requestedBy?: WorkContract['requestedBy'];
+  principalId?: string;
+  controllerInstanceId?: string;
+  workKind?: WorkKind;
+  risk?: WorkRisk;
+  allowedPaths?: string[];
+  forbiddenPaths?: string[];
+  checks?: string[];
+  acceptanceCriteria?: string[];
+  constraints?: WorkContract['constraints'];
+}