@moretea-labs/forge 1.8.0 → 1.8.1

package/packages/kernel/controller/domain/controller-round-transition-policy.ts

@@ -2,8 +2,14 @@ import { createHash } from 'crypto';
 import type { ControllerSession } from './types';
 import type { ControllerRoundDisposition, ControllerRoundRelayIdentity, ControllerRoundRelayRecord } from './controller-round';
 
-export function controllerRoundProviderEffectId(relayScopeId: string, authorityId: string): string {
-  return `crpe_${createHash('sha256').update(JSON.stringify([relayScopeId.trim(), authorityId.trim()])).digest('hex')}`;
+export function controllerRoundProviderEffectId(
+  round: Pick<ControllerRoundRelayRecord, 'relayScopeId' | 'originWorkId' | 'roundCount'>,
+): string {
+  return `crpe_${createHash('sha256').update(JSON.stringify([
+    round.relayScopeId.trim(),
+    round.originWorkId.trim(),
+    round.roundCount,
+  ])).digest('hex')}`;
 }
 
 export type ControllerRoundBlockerClass =
@@ -24,24 +30,40 @@ export function controllerRoundBlockerClass(record: Pick<ControllerRoundRelayRec
   return undefined;
 }
 
+/** Read-only claim admission shared by transport preflight and durable relay acknowledgement. */
+export function controllerRoundRelayClaimable(
+  record: Pick<ControllerRoundRelayRecord, 'status' | 'blockedReason'>,
+  options: { allowUserResume?: boolean } = {},
+): boolean {
+  if (['dispatching', 'dispatched', 'claimed'].includes(record.status)) return true;
+  if (record.status === 'waiting_for_user' && options.allowUserResume === true) return true;
+  const blocker = controllerRoundBlockerClass(record);
+  return blocker === 'provider_dispatch_outcome_unknown' || blocker === 'repeated_state';
+}
+
 export type ControllerRoundTransitionEvent =
-  | { type: 'occurrence_requested'; at: string; repoId: string; relayScopeId: string; originWorkId: string; requirementId?: string; identity: ControllerRoundRelayIdentity; stateFingerprint: string; proposedAuthorityId: string; maxRounds: number; maxRepeatedState: number; maxFailures: number; bindingId?: string; occurrenceId?: string; abandonedReleaseRecovery: boolean }
+  | { type: 'occurrence_requested'; at: string; repoId: string; relayScopeId: string; originWorkId: string; requirementId?: string; identity: ControllerRoundRelayIdentity; stateFingerprint: string; proposedAuthorityId: string; maxRounds: number; maxRepeatedState: number; maxFailures: number; bindingId?: string; occurrenceId?: string; abandonedReleaseRecovery: boolean; allowSemanticWaitRecovery?: boolean; authorizeRoundBudgetOccurrence?: boolean }
+  | { type: 'provider_dispatch_started'; at: string; providerDispatchEffectId: string; bindingId?: string }
   | { type: 'provider_dispatch_succeeded'; at: string; providerDispatchEffectId: string; bindingId?: string; providerDispatchReceiptId?: string }
   | { type: 'provider_dispatch_failed'; at: string; error: string; recovery: boolean; nextRecoveryAt?: string }
+  | { type: 'provider_retry_requested'; at: string; occurrenceId?: string }
   | { type: 'provider_dispatch_outcome_unknown'; at: string; error: string; providerDispatchEffectId: string }
   | { type: 'provider_user_action_required'; at: string; error: string; handoffId: string }
-  | { type: 'controller_claim_observed'; at: string; session: ControllerSession & { claimGeneration: number }; principalId: string; controllerInstanceId: string }
+  | { type: 'provider_user_action_resolved'; at: string; handoffId: string; occurrenceId: string }
+  | { type: 'controller_claim_observed'; at: string; session: ControllerSession & { claimGeneration: number }; principalId: string; controllerInstanceId: string; userResume?: boolean }
+  | { type: 'controller_turn_settled'; at: string; stateFingerprint: string; completionEvidenceId: string; blockingHandoffId?: string }
   | { type: 'semantic_state_changed'; at: string; stateFingerprint: string; session: ControllerSession & { claimGeneration: number }; principalId: string; controllerInstanceId: string }
   | { type: 'stalled_round_observed'; at: string; stateFingerprint: string; proposedAuthorityId: string; lastError?: string }
   | { type: 'provider_environment_recovered'; at: string; evidenceId: string }
   | { type: 'legacy_occurrence_bound'; at: string; occurrenceId: string }
-  | { type: 'semantic_disposition_submitted'; at: string; disposition: ControllerRoundDisposition; stateFingerprint: string; maxRounds: number; maxRepeatedState: number; maxFailures: number; controllerSession: Pick<ControllerSession, 'controllerId' | 'controllerType' | 'principalId' | 'controllerInstanceId' | 'sessionId' | 'claimGeneration'>; handoffId?: string; reason?: string; bindingId?: string; qualityDecisions?: ControllerRoundRelayRecord['qualityDecisions']; qualityAdjustmentResults?: ControllerRoundRelayRecord['qualityAdjustmentResults']; observationWindow?: ControllerRoundRelayRecord['observationWindow'] }
+  | { type: 'semantic_disposition_submitted'; at: string; disposition: ControllerRoundDisposition; stateFingerprint: string; maxRounds: number; maxRepeatedState: number; maxFailures: number; controllerSession: Pick<ControllerSession, 'controllerId' | 'controllerType' | 'principalId' | 'controllerInstanceId' | 'sessionId' | 'claimGeneration'>; terminalGoalComplete?: boolean; handoffId?: string; reason?: string; bindingId?: string; qualityDecisions?: ControllerRoundRelayRecord['qualityDecisions']; qualityAdjustmentResults?: ControllerRoundRelayRecord['qualityAdjustmentResults']; observationWindow?: ControllerRoundRelayRecord['observationWindow'] }
   | { type: 'successor_bound'; at: string; successorWorkId: string }
   | { type: 'controller_release_observed'; at: string; proposedAuthorityId: string }
   | { type: 'successor_release_handoff'; at: string; successorWorkId: string; successorStateFingerprint: string; proposedAuthorityId: string }
+  | { type: 'failed_dispatch_successor_handoff'; at: string; successorWorkId: string; successorStateFingerprint: string; proposedAuthorityId: string }
   | { type: 'terminal_work_observed'; at: string; error: string }
   | { type: 'abandoned_release_observed'; at: string; error: string }
-  | { type: 'authority_recovery_requested'; at: string; proposedAuthorityId: string; keepsConfirmedDispatch: boolean };
+  | { type: 'authority_recovery_requested'; at: string; proposedAuthorityId: string; keepsConfirmedDispatch: boolean; preserveBlockedState?: boolean; preserveWaitingForUserState?: boolean; reason?: string };
 
 export type ControllerRoundTransitionDecision =
   | { kind: 'accept'; next: ControllerRoundRelayRecord; action: string }
@@ -61,11 +83,19 @@ export function decideControllerRoundTransition(
   switch (event.type) {
     case 'occurrence_requested': {
       const previous = current;
+      if (previous && event.occurrenceId?.trim() && previous.occurrenceId === event.occurrenceId.trim()) {
+        return { kind: 'no_op', current: previous, reason: 'occurrence_request_already_applied' };
+      }
+      const previousBlocker = previous ? controllerRoundBlockerClass(previous) : undefined;
+      const startsAuthorizedRoundBudgetOccurrence = previousBlocker === 'round_budget_exhausted'
+        && event.authorizeRoundBudgetOccurrence === true
+        && Boolean(event.occurrenceId?.trim())
+        && previous?.occurrenceId !== event.occurrenceId?.trim();
       if (previous) {
         if (['pending_release', 'dispatching', 'dispatched', 'claimed'].includes(previous.status)) return { kind: 'reject', code: `CONTROLLER_RELAY_ROUND_ALREADY_OPEN:${previous.relayScopeId}` };
-        const blocker = controllerRoundBlockerClass(previous);
+        const blocker = previousBlocker;
         if (blocker === 'provider_dispatch_outcome_unknown') return { kind: 'reject', code: `CONTROLLER_RELAY_PROVIDER_DISPATCH_OUTCOME_UNKNOWN:${previous.relayScopeId}` };
-        if (blocker) return { kind: 'reject', code: `CONTROLLER_RELAY_BLOCKED_OCCURRENCE_FORBIDDEN:${blocker}` };
+        if (blocker && !startsAuthorizedRoundBudgetOccurrence) return { kind: 'reject', code: `CONTROLLER_RELAY_BLOCKED_OCCURRENCE_FORBIDDEN:${blocker}` };
         if (previous.status === 'waiting_for_user') return { kind: 'reject', code: 'CONTROLLER_RELAY_USER_RESUME_REQUIRED' };
         if (previous.status === 'goal_complete' || previous.status === 'handed_off') return { kind: 'reject', code: `CONTROLLER_RELAY_TERMINAL_OCCURRENCE_FORBIDDEN:${previous.status}` };
         // A terminal provider failure is still the same relay attempt.  The
@@ -76,8 +106,7 @@ export function decideControllerRoundTransition(
         // semantic states require an occurrence id so an external wake cannot
         // silently replay an old lineage.
         if (previous.status !== 'failed' && !event.abandonedReleaseRecovery && !event.occurrenceId?.trim()) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_OCCURRENCE_ID_REQUIRED' };
-        if (event.occurrenceId?.trim() && previous.occurrenceId === event.occurrenceId.trim()) return { kind: 'reject', code: `CONTROLLER_RELAY_OCCURRENCE_ALREADY_APPLIED:${event.occurrenceId.trim()}` };
-        if (previous.status === 'waiting' && previous.stateFingerprint === event.stateFingerprint) return { kind: 'reject', code: 'CONTROLLER_RELAY_WAITING_STATE_UNCHANGED' };
+        if (previous.status === 'waiting' && previous.stateFingerprint === event.stateFingerprint && !event.allowSemanticWaitRecovery) return { kind: 'reject', code: 'CONTROLLER_RELAY_WAITING_STATE_UNCHANGED' };
         if (previous.status === 'failed' && !event.abandonedReleaseRecovery && event.occurrenceId?.trim()) return { kind: 'reject', code: 'CONTROLLER_RELAY_FAILED_REQUIRES_EXPLICIT_RESUME' };
         if (event.abandonedReleaseRecovery && previous.status !== 'failed') return { kind: 'reject', code: 'CONTROLLER_RELAY_ABANDONED_RECOVERY_STATE_INVALID' };
       }
@@ -88,7 +117,10 @@ export function decideControllerRoundTransition(
       // launders round/repeated history back to an initial record. Provider failure
       // streak is responsibility-local, while providerFailureTotal below remains the
       // durable historical audit across occurrences.
-      const roundCount = previous ? previous.roundCount + 1 : 1;
+      // A distinct, authenticated launcher occurrence starts a new bounded round
+      // budget after the previous occurrence exhausted it. The old occurrence and
+      // its relay revisions remain durable; this does not reopen its authority.
+      const roundCount = startsAuthorizedRoundBudgetOccurrence ? 1 : previous ? previous.roundCount + 1 : 1;
       const repeatedStateCount = previous ? (previous.stateFingerprint === event.stateFingerprint ? previous.repeatedStateCount + 1 : 0) : 0;
       const consecutiveFailures = event.abandonedReleaseRecovery && previous ? previous.consecutiveFailures : 0;
       let blockedReason: string | undefined;
@@ -114,26 +146,49 @@ export function decideControllerRoundTransition(
       };
       return { kind: 'accept', next: record, action: blockedReason ? 'controller_round_initial_launch_blocked' : 'controller_round_initial_launch_begin' };
     }
+    case 'provider_dispatch_started': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status !== 'dispatching') return { kind: 'reject', code: `CONTROLLER_RELAY_DISPATCH_STATE_INVALID:${current.status}` };
+      const providerDispatchEffectId = event.providerDispatchEffectId.trim();
+      if (!providerDispatchEffectId) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_PROVIDER_EFFECT_ID_REQUIRED' };
+      if (current.providerDispatchStartedAt) {
+        if (current.providerDispatchEffectId === providerDispatchEffectId) return { kind: 'no_op', current, reason: 'provider_dispatch_already_started' };
+        return { kind: 'reject', code: 'CONTROLLER_RELAY_PROVIDER_EFFECT_MISMATCH' };
+      }
+      return accept(current, {
+        providerDispatchEffectId,
+        providerDispatchAttempt: (current.providerDispatchAttempt ?? 0) + 1,
+        providerDispatchStartedAt: event.at,
+        ...(event.bindingId ? { bindingId: event.bindingId } : {}),
+        updatedAt: event.at,
+      }, 'controller_round_provider_dispatch_started');
+    }
     case 'provider_dispatch_succeeded': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
       if (current.status === 'dispatched') return { kind: 'no_op', current, reason: 'dispatch_already_confirmed' };
-      if (current.status !== 'dispatching') return { kind: 'reject', code: `CONTROLLER_RELAY_DISPATCH_STATE_INVALID:${current.status}` };
+      const reconcilesOutcomeUnknown = current.status === 'blocked'
+        && controllerRoundBlockerClass(current) === 'provider_dispatch_outcome_unknown';
+      if (current.status !== 'dispatching' && !reconcilesOutcomeUnknown) return { kind: 'reject', code: `CONTROLLER_RELAY_DISPATCH_STATE_INVALID:${current.status}` };
+      if (current.providerDispatchEffectId && current.providerDispatchEffectId !== event.providerDispatchEffectId) return { kind: 'reject', code: 'CONTROLLER_RELAY_PROVIDER_EFFECT_MISMATCH' };
       return accept(current, {
         status: 'dispatched', lifecycleStage: 'dispatch_confirmed', consecutiveFailures: 0, providerDispatchEffectId: event.providerDispatchEffectId,
+        providerDispatchAttempt: current.providerDispatchAttempt ?? 1, providerDispatchStartedAt: current.providerDispatchStartedAt ?? event.at,
         failureClass: undefined, lastError: undefined, nextRecoveryAt: undefined, blockedReason: undefined,
         ...(event.bindingId ? { bindingId: event.bindingId } : {}),
         ...(event.providerDispatchReceiptId ? { providerDispatchReceiptId: event.providerDispatchReceiptId } : {}),
         dispatchedAt: event.at, updatedAt: event.at,
-      }, 'controller_round_relay_dispatched');
+      }, reconcilesOutcomeUnknown ? 'controller_round_relay_unknown_dispatch_reconciled' : 'controller_round_relay_dispatched');
     }
     case 'provider_dispatch_outcome_unknown': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
       if (current.status !== 'dispatching') return { kind: 'reject', code: `CONTROLLER_RELAY_DISPATCH_STATE_INVALID:${current.status}` };
       if (!event.providerDispatchEffectId.trim()) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_PROVIDER_EFFECT_ID_REQUIRED' };
+      if (current.providerDispatchEffectId && current.providerDispatchEffectId !== event.providerDispatchEffectId) return { kind: 'reject', code: 'CONTROLLER_RELAY_PROVIDER_EFFECT_MISMATCH' };
       return accept(current, {
         status: 'blocked', consecutiveFailures: current.consecutiveFailures + 1, providerFailureTotal: (current.providerFailureTotal ?? 0) + 1, nextRecoveryAt: undefined,
         failureClass: undefined, lastError: event.error, blockedReason: 'provider_dispatch_outcome_unknown',
-        providerDispatchEffectId: event.providerDispatchEffectId, updatedAt: event.at,
+        providerDispatchEffectId: event.providerDispatchEffectId, providerDispatchAttempt: current.providerDispatchAttempt ?? 1,
+        providerDispatchStartedAt: current.providerDispatchStartedAt ?? event.at, updatedAt: event.at,
       }, 'controller_round_relay_dispatch_outcome_unknown');
     }
     case 'provider_user_action_required': {
@@ -145,6 +200,23 @@ export function decideControllerRoundTransition(
         blockedReason: 'provider_user_action_required', handoffId: event.handoffId, updatedAt: event.at,
       }, 'controller_round_relay_waiting_for_user');
     }
+    case 'provider_user_action_resolved': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status !== 'waiting_for_user' || controllerRoundBlockerClass(current) !== 'provider_user_action_required') {
+        return { kind: 'reject', code: `CONTROLLER_RELAY_PROVIDER_USER_ACTION_STATE_INVALID:${current.status}` };
+      }
+      const handoffId = event.handoffId.trim();
+      if (!handoffId) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_WAIT_FOR_USER_HANDOFF_REQUIRED' };
+      if (current.handoffId !== handoffId) return { kind: 'reject', code: `CONTROLLER_RELAY_PROVIDER_USER_ACTION_HANDOFF_MISMATCH:${current.handoffId ?? 'missing'}` };
+      const occurrenceId = event.occurrenceId.trim();
+      if (!occurrenceId) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_OCCURRENCE_ID_REQUIRED' };
+      return accept(current, {
+        status: 'dispatching', lifecycleStage: 'dispatching', occurrenceId,
+        handoffId: undefined, blockedReason: undefined, failureClass: undefined, lastError: undefined, nextRecoveryAt: undefined,
+        providerDispatchEffectId: undefined, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined,
+        reason: `provider_user_action_resolved:${handoffId}`, updatedAt: event.at,
+      }, 'controller_round_relay_provider_user_action_resolved');
+    }
     case 'provider_dispatch_failed': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
       if (current.status !== 'dispatching') return { kind: 'reject', code: `CONTROLLER_RELAY_DISPATCH_STATE_INVALID:${current.status}` };
@@ -156,9 +228,26 @@ export function decideControllerRoundTransition(
       return accept(current, {
         status: blocked ? 'blocked' : 'dispatching', consecutiveFailures: failures, providerFailureTotal: (current.providerFailureTotal ?? 0) + 1, failureClass: undefined, lastError: event.error,
         blockedReason: blocked ? `consecutive_failures:${failures}>=${current.maxFailures}` : undefined,
+        ...(blocked ? {} : { providerDispatchEffectId: undefined, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined }),
         nextRecoveryAt: blocked ? undefined : event.nextRecoveryAt, updatedAt: event.at,
       }, blocked ? 'controller_round_relay_recovery_blocked' : 'controller_round_relay_recovery_retry_scheduled');
     }
+    case 'provider_retry_requested': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status !== 'failed') return { kind: 'reject', code: `CONTROLLER_RELAY_PROVIDER_RETRY_STATE_INVALID:${current.status}` };
+      if (current.consecutiveFailures >= current.maxFailures) return { kind: 'reject', code: `CONTROLLER_RELAY_PROVIDER_RETRY_BUDGET_EXHAUSTED:${current.consecutiveFailures}>=${current.maxFailures}` };
+      const occurrenceId = event.occurrenceId?.trim() || current.occurrenceId;
+      if (current.occurrenceId && occurrenceId && current.occurrenceId !== occurrenceId) {
+        return { kind: 'reject', code: `CONTROLLER_RELAY_PROVIDER_RETRY_OCCURRENCE_MISMATCH:${current.occurrenceId}` };
+      }
+      return accept(current, {
+        status: 'dispatching', lifecycleStage: 'dispatching',
+        ...(occurrenceId ? { occurrenceId } : {}),
+        providerDispatchEffectId: undefined, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined,
+        nextRecoveryAt: undefined, blockedReason: undefined, failureClass: undefined, lastError: undefined,
+        reason: 'provider_retry_requested', updatedAt: event.at,
+      }, 'controller_round_relay_provider_retry_begin');
+    }
     case 'provider_environment_recovered': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
       if (controllerRoundBlockerClass(current) !== 'consecutive_failures') return { kind: 'reject', code: 'CONTROLLER_RELAY_PROVIDER_RECOVERY_BLOCKER_MISMATCH' };
@@ -166,7 +255,11 @@ export function decideControllerRoundTransition(
       return accept(current, {
         status: 'dispatching', lifecycleStage: 'dispatching', consecutiveFailures: 0,
         providerRecoveryEpoch: (current.providerRecoveryEpoch ?? 0) + 1, providerRecoveryEvidenceId: event.evidenceId.slice(0, 500),
-        blockedReason: undefined, failureClass: undefined, lastError: undefined, nextRecoveryAt: undefined,
+        providerDispatchEffectId: undefined, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined,
+        // A resolved user-action handoff belongs to the failed provider epoch.
+        // Keeping it makes the next dispatch reject it as terminal before it can
+        // reach the recovered provider environment.
+        handoffId: undefined, blockedReason: undefined, failureClass: undefined, lastError: undefined, nextRecoveryAt: undefined,
         reason: `provider_environment_recovered:${event.evidenceId.slice(0, 240)}`, updatedAt: event.at,
       }, 'controller_round_relay_provider_environment_recovered');
     }
@@ -195,9 +288,54 @@ export function decideControllerRoundTransition(
         if (!current.providerDispatchEffectId) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_PROVIDER_EFFECT_ID_REQUIRED' };
         return accept(current, { status: 'claimed', lifecycleStage: 'controller_claimed', controllerId: event.session.controllerId, controllerType: event.session.controllerType, principalId: event.principalId, controllerInstanceId: event.controllerInstanceId, sessionId: event.session.sessionId, claimGeneration: event.session.claimGeneration, consecutiveFailures: 0, blockedReason: undefined, failureClass: undefined, lastError: undefined, nextRecoveryAt: undefined, claimedAt: event.at, updatedAt: event.at }, 'controller_round_relay_claim_confirmed_unknown_dispatch');
       }
+      if (current.status === 'waiting_for_user' && event.userResume === true) {
+        return accept(current, {
+          status: 'claimed', lifecycleStage: 'controller_claimed',
+          controllerId: event.session.controllerId, controllerType: event.session.controllerType,
+          principalId: event.principalId, controllerInstanceId: event.controllerInstanceId,
+          sessionId: event.session.sessionId, claimGeneration: event.session.claimGeneration,
+          disposition: undefined, handoffId: undefined, blockedReason: undefined,
+          failureClass: undefined, lastError: undefined, nextRecoveryAt: undefined,
+          claimedAt: event.at, updatedAt: event.at,
+        }, 'controller_round_relay_user_resumed');
+      }
       if (!['dispatching', 'dispatched'].includes(current.status)) return { kind: 'reject', code: `CONTROLLER_RELAY_CLAIM_STATE_INVALID:${current.status}` };
       return accept(current, { status: 'claimed', lifecycleStage: 'controller_claimed', controllerId: event.session.controllerId, controllerType: event.session.controllerType, principalId: event.principalId, controllerInstanceId: event.controllerInstanceId, sessionId: event.session.sessionId, claimGeneration: event.session.claimGeneration, claimedAt: event.at, updatedAt: event.at, failureClass: undefined, lastError: undefined }, 'controller_round_relay_claim_acknowledged');
     }
+    case 'controller_turn_settled': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status !== 'claimed') {
+        if (['pending_release', 'waiting', 'waiting_for_user', 'goal_complete', 'handed_off', 'blocked', 'failed'].includes(current.status)) {
+          return { kind: 'no_op', current, reason: `controller_turn_already_closed:${current.status}` };
+        }
+        return { kind: 'reject', code: `CONTROLLER_RELAY_TURN_SETTLED_STATE_INVALID:${current.status}` };
+      }
+      const completionEvidenceId = event.completionEvidenceId.trim();
+      if (!completionEvidenceId) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_TURN_COMPLETION_EVIDENCE_REQUIRED' };
+      const blockingHandoffId = event.blockingHandoffId?.trim();
+      if (blockingHandoffId) {
+        return accept(current, {
+          disposition: 'wait_for_user', status: 'waiting_for_user', lifecycleStage: 'semantic_round_closed',
+          stateFingerprint: event.stateFingerprint, handoffId: blockingHandoffId,
+          controllerTurnCompletionEvidenceId: completionEvidenceId, controllerTurnSettledAt: event.at,
+          reason: current.reason ?? 'controller_turn_settled_with_blocking_handoff',
+          submittedAt: event.at, updatedAt: event.at,
+        }, 'controller_round_turn_settled_wait_for_user');
+      }
+      const roundCount = current.roundCount + 1;
+      const repeatedStateCount = current.stateFingerprint === event.stateFingerprint ? current.repeatedStateCount + 1 : 0;
+      let blockedReason: string | undefined;
+      if (roundCount > current.maxRounds) blockedReason = `round_budget_exhausted:${roundCount}>${current.maxRounds}`;
+      else if (repeatedStateCount >= current.maxRepeatedState) blockedReason = `repeated_state:${repeatedStateCount}>=${current.maxRepeatedState}`;
+      else if (current.consecutiveFailures >= current.maxFailures) blockedReason = `consecutive_failures:${current.consecutiveFailures}>=${current.maxFailures}`;
+      return accept(current, {
+        disposition: 'continue_immediately', status: blockedReason ? 'blocked' : 'pending_release', lifecycleStage: 'semantic_round_closed',
+        stateFingerprint: event.stateFingerprint, roundCount, repeatedStateCount, blockedReason,
+        controllerTurnCompletionEvidenceId: completionEvidenceId, controllerTurnSettledAt: event.at,
+        reason: current.reason ?? 'controller_turn_settled_nonterminal_work',
+        submittedAt: event.at, updatedAt: event.at,
+      }, blockedReason ? 'controller_round_turn_settled_blocked' : 'controller_round_turn_settled_autocontinue');
+    }
     case 'semantic_state_changed': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
       if (controllerRoundBlockerClass(current) !== 'repeated_state') return { kind: 'reject', code: 'CONTROLLER_RELAY_SEMANTIC_PROGRESS_BLOCKER_MISMATCH' };
@@ -218,12 +356,17 @@ export function decideControllerRoundTransition(
       if (roundCount > current.maxRounds) blockedReason = `round_budget_exhausted:${roundCount}>${current.maxRounds}`;
       else if (repeatedStateCount >= current.maxRepeatedState) blockedReason = `repeated_state:${repeatedStateCount}>=${current.maxRepeatedState}`;
       if (blockedReason) return accept(current, { status: 'blocked', stateFingerprint: event.stateFingerprint, roundCount, repeatedStateCount, blockedReason, updatedAt: event.at }, 'controller_round_relay_stalled_blocked');
-      const authorityId = current.status === 'dispatching' && current.authorityId ? current.authorityId : event.proposedAuthorityId;
-      return accept(current, { authorityId, status: 'dispatching', lifecycleStage: 'dispatching', stateFingerprint: event.stateFingerprint, roundCount, repeatedStateCount, failureClass: undefined, lastError: blocker === 'repeated_state' ? undefined : event.lastError, reason: blocker === 'repeated_state' ? 'semantic_state_changed_after_repeated_state_block' : current.reason, nextRecoveryAt: undefined, claimedAt: undefined, blockedReason: undefined, updatedAt: event.at }, 'controller_round_relay_stalled_recovery_begin');
+      const resumesSameDispatch = current.status === 'dispatching';
+      const authorityId = resumesSameDispatch && current.authorityId ? current.authorityId : event.proposedAuthorityId;
+      return accept(current, { authorityId, status: 'dispatching', lifecycleStage: 'dispatching', stateFingerprint: event.stateFingerprint, roundCount, repeatedStateCount, failureClass: undefined, lastError: blocker === 'repeated_state' ? undefined : event.lastError, reason: blocker === 'repeated_state' ? 'semantic_state_changed_after_repeated_state_block' : current.reason, nextRecoveryAt: undefined, claimedAt: undefined, blockedReason: undefined, controllerTurnCompletionEvidenceId: undefined, controllerTurnSettledAt: undefined, ...(resumesSameDispatch ? {} : { providerDispatchEffectId: undefined, providerDispatchAttempt: 0, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined }), updatedAt: event.at }, 'controller_round_relay_stalled_recovery_begin');
     }
     case 'semantic_disposition_submitted': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
-      if (current.status !== 'claimed') return { kind: 'reject', code: `CONTROLLER_RELAY_ROUND_NOT_CLAIMED:${current.status}` };
+      const providerWaitTerminalGoalComplete = event.terminalGoalComplete === true
+        && event.disposition === 'goal_complete'
+        && current.status === 'waiting_for_user'
+        && controllerRoundBlockerClass(current) === 'provider_user_action_required';
+      if (current.status !== 'claimed' && !providerWaitTerminalGoalComplete) return { kind: 'reject', code: `CONTROLLER_RELAY_ROUND_NOT_CLAIMED:${current.status}` };
       const maxRounds = Math.min(current.maxRounds, event.maxRounds);
       const maxRepeatedState = Math.min(current.maxRepeatedState, event.maxRepeatedState);
       const maxFailures = Math.min(current.maxFailures, event.maxFailures);
@@ -272,6 +415,68 @@ export function decideControllerRoundTransition(
       if (current.successorWorkId && current.successorWorkId !== event.successorWorkId) return { kind: 'reject', code: `CONTROLLER_RELAY_SUCCESSOR_ALREADY_BOUND:${current.successorWorkId}` };
       return accept(current, { successorWorkId: event.successorWorkId, updatedAt: event.at }, 'controller_round_successor_work_bound');
     }
+    case 'failed_dispatch_successor_handoff': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status !== 'failed') return { kind: 'reject', code: `CONTROLLER_RELAY_FAILED_SUCCESSOR_HANDOFF_STATE_INVALID:${current.status}` };
+      if (current.lifecycleStage !== 'dispatching' || current.claimGeneration !== 0) {
+        return { kind: 'reject', code: 'CONTROLLER_RELAY_FAILED_SUCCESSOR_HANDOFF_PRECLAIM_REQUIRED' };
+      }
+      if (current.successorWorkId && current.successorWorkId !== event.successorWorkId) {
+        return { kind: 'reject', code: `CONTROLLER_RELAY_SUCCESSOR_ALREADY_BOUND:${current.successorWorkId}` };
+      }
+      const nextRoundCount = current.roundCount + 1;
+      if (nextRoundCount > current.maxRounds) {
+        return { kind: 'reject', code: `CONTROLLER_RELAY_ROUND_BUDGET_EXHAUSTED:${nextRoundCount}>${current.maxRounds}` };
+      }
+      const handedOff: ControllerRoundRelayRecord = {
+        ...current,
+        successorWorkId: event.successorWorkId,
+        status: 'handed_off',
+        lifecycleStage: 'semantic_round_closed',
+        authorityId: undefined,
+        updatedAt: event.at,
+      };
+      const successor: ControllerRoundRelayRecord = {
+        ...current,
+        originWorkId: event.successorWorkId,
+        predecessorWorkId: current.originWorkId,
+        successorWorkId: undefined,
+        status: 'dispatching',
+        lifecycleStage: 'dispatching',
+        authorityId: event.proposedAuthorityId,
+        stateFingerprint: event.successorStateFingerprint,
+        roundCount: nextRoundCount,
+        repeatedStateCount: 0,
+        consecutiveFailures: 0,
+        controllerInstanceId: '',
+        sessionId: '',
+        claimGeneration: 0,
+        assistantContextSnapshot: undefined,
+        controllerTurnCompletionEvidenceId: undefined,
+        controllerTurnSettledAt: undefined,
+        bindingId: undefined,
+        providerDispatchEffectId: undefined,
+        providerDispatchAttempt: 0,
+        providerDispatchStartedAt: undefined,
+        providerDispatchReceiptId: undefined,
+        blockedReason: undefined,
+        failureClass: undefined,
+        lastError: undefined,
+        nextRecoveryAt: undefined,
+        dispatchedAt: undefined,
+        claimedAt: undefined,
+        updatedAt: event.at,
+      };
+      return {
+        kind: 'accept_atomic',
+        next: handedOff,
+        action: 'controller_round_failed_preclaim_successor_handoff_closed',
+        relatedWorkId: event.successorWorkId,
+        relatedNext: successor,
+        relatedAction: 'controller_round_relay_successor_dispatch_begin',
+      };
+    }
+
     case 'successor_release_handoff': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
       if (current.status !== 'pending_release') return { kind: 'reject', code: `CONTROLLER_RELAY_SUCCESSOR_HANDOFF_STATE_INVALID:${current.status}` };
@@ -281,7 +486,7 @@ export function decideControllerRoundTransition(
         ...current, originWorkId: event.successorWorkId, predecessorWorkId: current.originWorkId, successorWorkId: undefined,
         status: 'dispatching', lifecycleStage: 'dispatching', authorityId: event.proposedAuthorityId,
         stateFingerprint: event.successorStateFingerprint, repeatedStateCount: 0, controllerInstanceId: '', sessionId: '', claimGeneration: 0,
-        assistantContextSnapshot: undefined,
+        assistantContextSnapshot: undefined, controllerTurnCompletionEvidenceId: undefined, controllerTurnSettledAt: undefined,
         bindingId: undefined, providerDispatchEffectId: undefined, providerDispatchAttempt: 0, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined,
         blockedReason: undefined, failureClass: undefined, lastError: undefined, nextRecoveryAt: undefined, dispatchedAt: undefined, claimedAt: undefined, updatedAt: event.at,
       };
@@ -290,7 +495,7 @@ export function decideControllerRoundTransition(
     case 'controller_release_observed': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
       if (current.status !== 'pending_release') return { kind: 'no_op', current, reason: 'release_not_pending' };
-      return accept(current, { authorityId: event.proposedAuthorityId, status: 'dispatching', lifecycleStage: 'dispatching', assistantContextSnapshot: undefined, updatedAt: event.at }, 'controller_round_relay_dispatch_begin');
+      return accept(current, { authorityId: event.proposedAuthorityId, status: 'dispatching', lifecycleStage: 'dispatching', assistantContextSnapshot: undefined, controllerTurnCompletionEvidenceId: undefined, controllerTurnSettledAt: undefined, providerDispatchEffectId: undefined, providerDispatchAttempt: 0, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined, updatedAt: event.at }, 'controller_round_relay_dispatch_begin');
     }
     case 'terminal_work_observed': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
@@ -302,7 +507,23 @@ export function decideControllerRoundTransition(
     }
     case 'authority_recovery_requested': {
       if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
-      return accept(current, { authorityId: event.proposedAuthorityId, status: event.keepsConfirmedDispatch ? 'dispatched' : 'dispatching', lifecycleStage: event.keepsConfirmedDispatch ? 'dispatch_confirmed' : 'dispatching', failureClass: undefined, claimedAt: undefined, nextRecoveryAt: undefined, updatedAt: event.at }, 'controller_round_relay_explicit_authority_recovered');
+      if (event.preserveBlockedState) {
+        if (current.status !== 'blocked') return { kind: 'reject', code: `CONTROLLER_RELAY_AUTHORITY_REKEY_BLOCKED_STATE_REQUIRED:${current.status}` };
+        return accept(current, {
+          authorityId: event.proposedAuthorityId,
+          ...(event.reason ? { reason: event.reason } : {}),
+          updatedAt: event.at,
+        }, 'controller_round_relay_explicit_authority_rekeyed_while_blocked');
+      }
+      if (event.preserveWaitingForUserState) {
+        if (current.status !== 'waiting_for_user') return { kind: 'reject', code: `CONTROLLER_RELAY_AUTHORITY_REKEY_WAITING_FOR_USER_STATE_REQUIRED:${current.status}` };
+        return accept(current, {
+          authorityId: event.proposedAuthorityId,
+          ...(event.reason ? { reason: event.reason } : {}),
+          updatedAt: event.at,
+        }, 'controller_round_relay_explicit_authority_rekeyed_while_waiting_for_user');
+      }
+      return accept(current, { authorityId: event.proposedAuthorityId, status: event.keepsConfirmedDispatch ? 'dispatched' : 'dispatching', lifecycleStage: event.keepsConfirmedDispatch ? 'dispatch_confirmed' : 'dispatching', failureClass: undefined, blockedReason: undefined, claimedAt: undefined, nextRecoveryAt: undefined, ...(event.reason ? { reason: event.reason } : {}), ...(event.keepsConfirmedDispatch ? {} : { providerDispatchEffectId: undefined, providerDispatchAttempt: 0, providerDispatchStartedAt: undefined, providerDispatchReceiptId: undefined }), updatedAt: event.at }, 'controller_round_relay_explicit_authority_recovered');
     }
   }
 }

package/packages/kernel/controller/domain/controller-round.ts

@@ -61,6 +61,9 @@ export interface ControllerRoundRelayRecord {
   qualityAdjustmentResults?: ExecutionQualityAdjustmentResult[];
   /** Exact bounded assistant context identity delivered for the currently claimed round. */
   assistantContextSnapshot?: AssistantContextSnapshot;
+  /** Provider-neutral evidence that the exact Controller turn visibly settled. Never a semantic disposition by itself. */
+  controllerTurnCompletionEvidenceId?: string;
+  controllerTurnSettledAt?: string;
   roundCount: number;
   repeatedStateCount: number;
   consecutiveFailures: number;
@@ -83,7 +86,7 @@ export interface ControllerRoundRelayRecord {
   providerFailureEvidenceId?: string;
   providerEffectReconciliationEvidenceId?: string;
   providerDispatchStartedAt?: string;
-  /** Canonical provider-dispatch receipt for this semantic round. Scheduler occurrence copies it only as a replay projection. */
+  /** Canonical provider-dispatch receipt for this semantic round. Trigger occurrences never duplicate this lifecycle truth. */
   providerDispatchReceiptId?: string;
   /** Explicit schedule/manual/replan occurrence identity when a prior lineage exists. */
   occurrenceId?: string;

package/packages/kernel/controller/domain/execution-quality.ts

@@ -73,7 +73,7 @@ export interface AssistantContextItemEvidence {
 
 export interface AssistantContextSnapshot {
   digest: string;
-  projectId: string;
+  projectId?: string;
   items: AssistantContextItemEvidence[];
   gaps: string[];
   missingRequiredSources: string[];
@@ -85,6 +85,8 @@ export interface AssistantContextUsage {
   itemId: string;
   decision: 'used' | 'rejected';
   reason: string;
+  /** Model-authored retrieval rejection semantics. Optional only for frozen-client compatibility. */
+  rejectionKind?: 'irrelevant' | 'stale' | 'contradicted';
 }
 
 export interface ClosedRoundObservation {