@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/control-plane/facade/types.ts

@@ -1,13 +1,14 @@
 import type { ProcessCheckReceiptEvidence } from '../../evidence/process-check-receipt';
 import type { CompletionReceipt as RepositoryCompletionReceipt } from '../../../cli/controller/types';
 import type { AccessMode } from '../governance/access-policy';
-import { decideRoute, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
+import { decideRoute, type ExplicitTaskMode, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
 
 export const EXECUTION_MODES = ['direct_control', 'goal_workloop', 'handoff_only'] as const;
 export type ExecutionMode = (typeof EXECUTION_MODES)[number];
 
 export const FACADE_TOOLS = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work'] as const;
 export type FacadeTool = (typeof FACADE_TOOLS)[number];
+export type CapabilityExecutionSurface = FacadeTool | 'plugin_action_execute';
 
 export const FACADE_STATUSES = ['ok', 'blocked', 'failed', 'approval_required', 'not_found'] as const;
 export type FacadeStatus = (typeof FACADE_STATUSES)[number];
@@ -156,18 +157,35 @@ export interface LocalEffectCompletionReceipt {
   recordedAt: string;
 }
 
+/** Durable completion authority for one typed remote plugin effect. */
+export interface RemoteEffectCompletionReceipt {
+  schemaVersion: 1;
+  /** Reuse the authoritative PLG-* receipt id rather than manufacturing parallel evidence. */
+  receiptId: string;
+  source: 'remote_effect';
+  workId: string;
+  pluginId: string;
+  actionId: string;
+  requestId: string;
+  semanticKey: string;
+  resultDigest: string;
+  recordedAt: string;
+}
+
 /**
  * Completion authority for a standalone Direct Edit that is not bound to the
- * retired Issue/Task completion model. The receipt proves that one finalized
- * edit session is present at an exact reachable Git revision with clean owned
- * paths, while keeping the WorkContract as the canonical lifecycle authority.
+ * retired Issue/Task completion model. Normal completion proves one finalized
+ * edit session at an exact reachable Git revision. Historical completion may
+ * instead reference one explicit reviewed reconciliation after exact revision,
+ * path-scope, verification, reachability, and cleanup proof checks.
  */
 export interface DirectEditWorkCompletionReceipt {
   schemaVersion: 1;
   receiptId: string;
   source: 'direct_edit_work';
   workId: string;
-  editSessionId: string;
+  editSessionId?: string;
+  reconciliationId?: string;
   targetBranch: string;
   targetRevision: string;
   sourceRevision?: string;
@@ -179,12 +197,18 @@ export interface DirectEditWorkCompletionReceipt {
   recordedAt: string;
 }
 
-export type WorkCompletionReceipt = RepositoryCompletionReceipt | DirectEditWorkCompletionReceipt | LocalEffectCompletionReceipt;
+export type WorkCompletionReceipt = RepositoryCompletionReceipt | DirectEditWorkCompletionReceipt | LocalEffectCompletionReceipt | RemoteEffectCompletionReceipt;
 
 export function isRepositoryCompletionReceipt(
   receipt: WorkCompletionReceipt,
 ): receipt is RepositoryCompletionReceipt {
-  return receipt.source !== 'local_effect' && receipt.source !== 'direct_edit_work';
+  return receipt.source !== 'local_effect' && receipt.source !== 'remote_effect' && receipt.source !== 'direct_edit_work';
+}
+
+export function isRemoteEffectCompletionReceipt(
+  receipt: WorkCompletionReceipt,
+): receipt is RemoteEffectCompletionReceipt {
+  return receipt.source === 'remote_effect';
 }
 
 export function isDirectEditWorkCompletionReceipt(
@@ -330,6 +354,8 @@ export interface WorkContractConstraints {
   conflictsWithThinHarnessPolicy?: boolean;
   /** True when the change alters the default routing or execution mode visible to users. */
   changesDefaultExecutionStrategy?: boolean;
+  /** Repository-change delivery must publish the exact integrated revision before Work terminalization. */
+  remoteDeliveryRequired?: boolean;
 }
 
 export interface WorkContractDriverPolicy {
@@ -431,6 +457,10 @@ export interface WorkContract {
   phaseEvidence: WorkPhaseEvidenceMap;
   /** Explicit v2 execution semantics. `status` is retained for compatibility. */
   workKind: WorkKind;
+  /** Primary is an objective-level business execution lane; execution_child is a resumable low-level operation handle owned by a primary Work or standalone caller. */
+  lifecycleRole?: 'primary' | 'execution_child';
+  /** Optional objective-level parent when this Work is only an execution child. */
+  parentWorkId?: string;
   dispatchState: DispatchState;
   evidenceState: EvidenceState;
   completionOutcome?: CompletionOutcome;
@@ -449,6 +479,18 @@ export interface WorkContract {
   planStepId?: string;
   planSourceRevision?: string;
   scopeSummary?: string;
+  /**
+   * Discovery evidence, never an authorization boundary. Initial guesses,
+   * inspected paths, and observed changes remain distinct so early retrieval
+   * cannot masquerade as complete implementation scope.
+   */
+  scopeEvidence?: {
+    initialLikelyPaths: string[];
+    inspectedPaths: string[];
+    actualChangedPaths: string[];
+    recordedAt: string;
+  };
+  /** Explicit policy fence. This is not semantic completeness evidence. */
   allowedPaths: string[];
   forbiddenPaths: string[];
   checks: string[];
@@ -468,13 +510,12 @@ export interface WorkContract {
   continuationPrompt?: string;
   worktreeRef?: string;
   workerRef?: string;
-  /** Stable idempotency key when this Work was accepted via work_submit. */
   requestId?: string;
-  /** Accepted Kernel operation envelope. Does not imply ExecutionJob creation. */
+  /** Typed execution metadata; it does not imply ExecutionJob creation. */
   submittedOperation?: SubmittedWorkOperation;
 }
 
-/** Operation metadata retained on WorkContracts accepted through work_submit. */
+/** Typed execution metadata retained on execution-child WorkContracts. */
 export interface SubmittedWorkOperation {
   name: string;
   semanticKey: string;
@@ -603,7 +644,7 @@ export interface CapabilityDescriptor {
   group: CapabilityGroup;
   operationClass: CapabilityOperationClass;
   risk: CapabilityRisk;
-  exposedVia: FacadeTool;
+  exposedVia: CapabilityExecutionSurface;
   schemaExposure: CapabilitySchemaExposure;
   summary: string;
 }
@@ -612,6 +653,7 @@ export interface CapabilityGroupSummary {
   group: CapabilityGroup;
   capabilityCount: number;
   domains: CapabilityDomain[];
+  executionSurfaces: CapabilityExecutionSurface[];
   facadeTools: FacadeTool[];
   operationClasses: CapabilityOperationClass[];
   risks: CapabilityRisk[];
@@ -640,6 +682,7 @@ export interface ExecutionModeSelectionInput {
   requiresInvestigation?: boolean;
   requiresLongRunningChecks?: boolean;
   requiresParallelism?: boolean;
+  explicitMode?: ExplicitTaskMode;
   needsDependencies?: boolean;
   requiresRecovery?: boolean;
   /** True only when the user explicitly requested an agent/worker executor. Complexity alone must not enable workers. */
@@ -690,6 +733,7 @@ export function selectExecutionMode(input: ExecutionModeSelectionInput): Executi
       requiresInvestigation: input.requiresInvestigation,
       requiresLongRunningChecks: input.requiresLongRunningChecks,
       requiresParallelism: input.requiresParallelism,
+      explicitMode: input.explicitMode,
       needsDependencies: input.needsDependencies,
       agentRequested: input.requiresWorker,
     },

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

@@ -18,10 +18,10 @@ import {
   type DispatchState,
   type EvidenceState,
   type PolicyDecision,
-  type SubmittedWorkOperation,
   type SuggestedNextAction,
   type VerificationRecord,
   type WorkReconciliationRecord,
+  type SubmittedWorkOperation,
   type WorkContract,
   type WorkContractStatus,
   type WorkRisk,
@@ -32,6 +32,7 @@ import {
   type WorkPhaseEvidenceState,
   type WorkContractStore,
   isDirectEditWorkCompletionReceipt,
+  isRemoteEffectCompletionReceipt,
   isRepositoryCompletionReceipt,
   isTerminalWorkContractStatus,
 } from './types';
@@ -195,7 +196,7 @@ function legacyPhaseEvidence(
       state,
       source: completedByReceipt ? 'recorded' : source,
       summary: completedByReceipt
-        ? `Phase ${phase} accepted by Work completion receipt ${contract.completionReceipt!.receiptId}.`
+        ? `Phase ${phase} satisfied by Work completion receipt ${contract.completionReceipt!.receiptId}.`
         : index < currentIndex
           ? `Legacy Work advanced beyond ${phase}.`
           : `Legacy Work phase ${phase} is ${state}.`,
@@ -285,13 +286,20 @@ function validateWorkSemantics(contract: WorkContract): WorkContract {
       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)) {
-      if (!receipt.editSessionId.trim()) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_SESSION_REQUIRED');
+      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');
@@ -335,6 +343,9 @@ function validateWorkSemantics(contract: WorkContract): WorkContract {
   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');
   }
@@ -359,11 +370,25 @@ const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceStat
   failed: ['failed', 'partial', 'valid', 'contradictory'],
 };
 
-function validateWorkSemanticTransition(current: WorkContract, next: WorkContract): WorkContract {
+function validateWorkSemanticTransition(
+  current: WorkContract,
+  next: WorkContract,
+  options: { allowRetainedCancelledResume?: boolean } = {},
+): WorkContract {
   const retryingFailedWork = current.status === 'failed'
     && !current.completionOutcome
     && ['claimed', 'launching', 'running', 'blocked'].includes(next.dispatchState);
-  if (!retryingFailedWork && !DISPATCH_TRANSITIONS[current.dispatchState].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)) {
@@ -372,9 +397,20 @@ function validateWorkSemanticTransition(current: WorkContract, next: WorkContrac
   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.
@@ -412,6 +448,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 }
@@ -524,7 +561,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({
@@ -544,6 +581,8 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
       constraints: input.constraints ?? { requireHandoffOnAmbiguity: true },
       risk: input.risk ?? 'medium',
       workKind: input.workKind ?? 'repository_change',
+      lifecycleRole: input.lifecycleRole ?? 'primary',
+      parentWorkId: input.parentWorkId?.trim() || undefined,
       dispatchState: input.dispatchState ?? inferredDispatchState(input.status ?? 'open'),
       evidenceState: input.evidenceState ?? inferredEvidenceState(input.status ?? 'open'),
       completionOutcome: input.completionOutcome,
@@ -566,6 +605,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),
@@ -599,6 +644,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}`);
@@ -610,7 +672,8 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
     };
     writeWorkContractStore(options, nextStore);
     return contract;
-  });
+  };
+  return create();
 }
 
 interface WorkRequestIndexRecord {
@@ -628,25 +691,6 @@ function workRequestIndexPath(controllerHome: string, requestId: string): string
   return join(root, `${hash}.json`);
 }
 
-export interface AcceptSubmittedWorkInput {
-  requestId: string;
-  repoId: 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,
@@ -667,8 +711,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,
@@ -676,46 +720,39 @@ 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');
+  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);
+    if (!parent) throw new Error(`PARENT_WORK_NOT_FOUND: ${parentWorkId}`);
+    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}`);
   }
-  if (!input.operation?.name?.trim()) {
-    throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): operation');
-  }
-
-  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,
       principalId: input.principalId,
       controllerInstanceId: input.controllerInstanceId,
       mode: input.mode ?? 'direct_control',
-      objective: (input.objective ?? `Accepted operation ${input.operation.name}`).slice(0, 2_000),
+      lifecycleRole: 'execution_child',
+      parentWorkId,
+      objective: (input.objective ?? `Typed operation ${input.operation.name}`).slice(0, 2_000),
       acceptanceCriteria: input.acceptanceCriteria ?? [],
       workKind: input.workKind,
       risk: input.risk,
@@ -725,13 +762,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',
@@ -741,15 +774,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 };
   });
 }
@@ -936,6 +961,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);
@@ -993,13 +1019,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 });
@@ -1015,6 +1041,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,
@@ -1097,6 +1200,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',
@@ -1114,5 +1220,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'];
+}