@moretea-labs/forge 1.7.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moretea-labs/forge",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Local-first action assistant for software work with resumable execution, bounded tools, and reviewable evidence",
   "license": "MIT",
   "author": "Moretea Labs contributors",
@@ -46,6 +46,7 @@
     "docs/images/",
     "docs/architecture/",
     "docs/operations/",
+    "!docs/operations/v2-candidate-certification.md",
     "docs/wiki/",
     "docs/public-usage-guide.md",
     "docs/public-usage-guide.zh-CN.md",
@@ -61,6 +62,8 @@
     "install.ps1",
     "bin/",
     "scripts/",
+    "adapters/",
+    "packages/",
     "src/",
     "AGENTS.md",
     "CLAUDE.md",
@@ -80,8 +83,8 @@
     "build:controller-ui": "bun scripts/build-controller-ui.ts",
     "check:controller-ui": "bun scripts/build-controller-ui.ts --check",
     "check:design": "npx -y @google/design.md@0.4.0 lint DESIGN.md",
-    "benchmark:skills": "bun scripts/run-skill-evals.ts",
     "benchmark:controller-hotpath": "bun scripts/benchmark-controller-hotpath.ts",
+    "benchmark:computer-hotpath": "bun scripts/benchmark-computer-hotpath.ts",
     "benchmark:thin-harness-mcp-e2e": "bun scripts/benchmark-thin-harness-mcp-e2e.ts --json",
     "benchmark:mcp-transport": "bun scripts/benchmark-mcp-transport.ts",
     "benchmark:mcp-host": "bash scripts/benchmark-mcp-host.sh",
@@ -90,7 +93,8 @@
     "benchmark:quality-harness": "bun scripts/benchmark-quality-harness.ts",
     "benchmark:background-check-overlap": "bun scripts/benchmark-background-check-overlap.ts",
     "check:quality-harness": "bun scripts/benchmark-quality-harness.ts",
-    "check:evaluation-framework": "bun test tests/evaluation-framework.test.ts",
+    "check:evaluation-framework": "bun test ./tests/evaluation-framework.test.ts && bun test ./evaluation/protocol.test.ts && bun test ./evaluation/candidate-runner.test.ts && bun test ./evaluation/calibration.test.ts && bun test ./evaluation/certification.test.ts && bun test ./evaluation/public-mcp-runner.test.ts",
+    "check:v2-certification": "bun evaluation/check-v2-certification.ts",
     "check:background-check-overlap": "bun scripts/benchmark-background-check-overlap.ts",
     "check:typescript-navigation": "bun scripts/benchmark-typescript-navigation.ts",
     "check:semantic-navigation-providers": "bun test tests/runtime/semantic-navigation-provider.test.ts",
@@ -106,6 +110,7 @@
     "test:coverage": "bun test --coverage",
     "check:type": "bun x tsc --noEmit",
     "check:runtime-architecture": "node scripts/check-runtime-architecture.mjs",
+    "check:repository-hygiene": "node scripts/check-repository-hygiene.mjs",
     "check:generated-authority": "node scripts/sync-generated-authority.mjs --check",
     "check:source-duplication": "node scripts/check-source-duplication.mjs",
     "check:executable-modes": "bun scripts/repair-executable-modes.ts --check",
@@ -131,20 +136,20 @@
     "check:public-export": "bun scripts/public-release.ts",
     "package:source-zip": "bash scripts/package-source-archive.sh",
     "check:release-published": "bash scripts/check-release-published.sh",
-    "smoke:tarball-install": "bash scripts/check-tarball-install-smoke.sh",
+    "smoke:tarball-install": "node scripts/run-bounded-command.mjs --timeout-ms 180000 -- bash scripts/check-tarball-install-smoke.sh",
     "check:release-version": "node scripts/check-release-version.mjs",
     "release:dry-run": "node scripts/check-release-version.mjs && bun run check:release",
     "release:rc": "bash scripts/publish-release-tarball.sh next",
     "release:stable": "bash scripts/publish-release-tarball.sh latest",
-    "check:brain-manifest": "forge run check-brain-manifest",
-    "check:context-files": "forge run check-context-files",
-    "check:deploy-sql": "forge run check-deploy-sql-order",
-    "check:architecture-sync": "forge run check-architecture-sync",
-    "check:task-sync": "forge run check-task-sync",
-    "check:task-workflow": "forge run check-task-workflow --strict",
+    "check:brain-manifest": "bun src/cli/index.ts run check-brain-manifest",
+    "check:context-files": "bun src/cli/index.ts run check-context-files",
+    "check:deploy-sql": "bun src/cli/index.ts run check-deploy-sql-order",
+    "check:architecture-sync": "bun src/cli/index.ts run check-architecture-sync",
+    "check:task-sync": "bun src/cli/index.ts run check-task-sync",
+    "check:task-workflow": "bun src/cli/index.ts run check-task-workflow --strict",
     "runtime:activate-source-baseline": "bun scripts/activate-source-baseline.ts request",
     "plugin:install-desktop-operator": "bun scripts/install-desktop-operator-registration.ts",
-    "sync:brain-docs": "forge run sync-brain-docs --all",
+    "sync:brain-docs": "bun src/cli/index.ts run sync-brain-docs --all",
     "sync:codex-installed": "bash scripts/sync-codex-installed-copies.sh",
     "check:forge-runtime": "bash scripts/verify-forge-runtime.sh",
     "repo:registry": "bun src/cli/v81-entry.ts repo",
@@ -154,7 +159,8 @@
     "test:node-smoke": "node --test tests/node/*.test.mjs",
     "check:ci:portable": "FORGE_ALLOW_NODE_ONLY=1 bash scripts/check-ci.sh",
     "dev:controller-ui": "vite --config src/cli/local-bridge/frontend/vite.config.ts",
-    "prepack": "node scripts/sync-generated-authority.mjs --check"
+    "prepack": "node scripts/sync-generated-authority.mjs --check",
+    "check:portable-package": "node --test tests/node/*.test.mjs && npm run smoke:tarball-install"
   },
   "devDependencies": {
     "@colbymchenry/codegraph": "1.0.1",
@@ -167,13 +173,16 @@
     "vite": "^7.3.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.28.0",
     "commander": "^14.0.3",
     "express": "^5.2.1",
     "playwright": "^1.54.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.8",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server-legacy": "^2.0.0",
+    "@modelcontextprotocol/node": "^2.0.0"
   },
   "packageManager": "npm@10.0.0",
   "optionalDependencies": {

package/packages/kernel/controller/api/index.ts

@@ -0,0 +1,2 @@
+export * from '../application/controller-service';
+export * from '../application/controller-round-service';

package/packages/kernel/controller/application/controller-round-service.ts

@@ -0,0 +1,29 @@
+/** Canonical provider-neutral ControllerRound application surface. */
+export * from '../domain/controller-round';
+export * from '../domain/controller-round-transition-policy';
+export * from '../domain/execution-quality';
+export {
+  acknowledgeControllerRoundClaim,
+  beginControllerRoundRelayAfterRelease,
+  beginInitialControllerRoundDispatch,
+  bindLegacyControllerRoundOccurrence,
+  bindControllerRoundSuccessorWork,
+  claimStalledControllerRoundRelays,
+  finishControllerRoundRelayDispatch,
+  getControllerRoundRelay,
+  readControllerRoundContextSnapshot,
+  readControllerRoundSemanticStateFingerprint,
+  rearmControllerRoundAfterProviderRecovery,
+  reconcileControllerRoundAfterAbandonedRelease,
+  reconcileControllerRoundAfterTerminalWork,
+  recoverControllerRoundRelayAuthority,
+  resolveRequirementControllerRoundRelayForWork,
+  submitControllerRoundDisposition,
+  type BeginInitialControllerRoundDispatchInput,
+  type BindLegacyControllerRoundOccurrenceInput,
+  type ControllerRoundContextSnapshot,
+  type ControllerRoundRelayStoreOptions,
+  type RecoverControllerRoundRelayAuthorityInput,
+  type RearmControllerRoundAfterProviderRecoveryInput,
+  type SubmitControllerRoundDispositionInput,
+} from '../infrastructure/controller-round-store';

package/packages/kernel/controller/application/controller-service.ts

@@ -0,0 +1,30 @@
+/** Canonical ControllerSession claim/release/fencing application surface. */
+export {
+  assertControllerOwnershipAuthority,
+  bindControllerSessionToCurrentRuntime,
+  claimControllerSession,
+  controllerSessionAuthorityDigest,
+  controllerSessionAuthorityMatches,
+  controllerSessionBlocksRecovery,
+  controllerSessionPrincipalId,
+  controllerTerminalizationAuthorityFromSession,
+  getControllerSession,
+  getRetainedControllerSession,
+  listControllerSessions,
+  mintControllerSessionAuthority,
+  releaseControllerSession,
+  releaseControllerSessionWithAuthority,
+  releaseObservedControllerSession,
+  requireControllerOwnershipAuthority,
+  resumeControllerSession,
+  withControllerSessionTerminalizationFence,
+  type ControllerOwnershipAuthority,
+  type ControllerSessionClaimInput,
+  type ControllerSessionStoreOptions,
+  type ControllerTerminalizationAuthority,
+  type ControllerTerminalizationFenceReason,
+  type ControllerTerminalizationFenceResult,
+} from '../infrastructure/controller-session-store';
+export type { ControllerBinding, ControllerLease, ControllerRoundContext, ControllerSession, ControllerSessionStore, ControllerType } from '../domain/types';
+export type { ControllerHost, ControllerHostResumeResult } from '../ports/controller-host';
+export { bindControllerSessionBinding, getControllerSessionBinding, getControllerWorkBinding, type ControllerSessionBindingRecord, type ControllerWorkBindingRecord } from '../infrastructure/controller-binding-store';

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

@@ -0,0 +1,308 @@
+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 type ControllerRoundBlockerClass =
+  | 'repeated_state'
+  | 'consecutive_failures'
+  | 'round_budget_exhausted'
+  | 'provider_dispatch_outcome_unknown'
+  | 'provider_user_action_required';
+
+export function controllerRoundBlockerClass(record: Pick<ControllerRoundRelayRecord, 'status' | 'blockedReason'>): ControllerRoundBlockerClass | undefined {
+  if (record.status === 'waiting_for_user' && record.blockedReason === 'provider_user_action_required') return 'provider_user_action_required';
+  if (record.status !== 'blocked') return undefined;
+  const reason = record.blockedReason ?? '';
+  if (reason === 'provider_dispatch_outcome_unknown') return 'provider_dispatch_outcome_unknown';
+  if (reason.startsWith('repeated_state:')) return 'repeated_state';
+  if (reason.startsWith('consecutive_failures:')) return 'consecutive_failures';
+  if (reason.startsWith('round_budget_exhausted:')) return 'round_budget_exhausted';
+  return undefined;
+}
+
+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: '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_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: '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: '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: '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 };
+
+export type ControllerRoundTransitionDecision =
+  | { kind: 'accept'; next: ControllerRoundRelayRecord; action: string }
+  | { kind: 'accept_atomic'; next: ControllerRoundRelayRecord; action: string; relatedWorkId: string; relatedNext: ControllerRoundRelayRecord; relatedAction: string }
+  | { kind: 'no_op'; current: ControllerRoundRelayRecord; reason: string }
+  | { kind: 'reject'; code: string }
+  | { kind: 'needs_evidence'; code: string };
+
+function accept(current: ControllerRoundRelayRecord, patch: Partial<ControllerRoundRelayRecord>, action: string): ControllerRoundTransitionDecision {
+  return { kind: 'accept', next: { ...current, ...patch }, action };
+}
+
+export function decideControllerRoundTransition(
+  current: ControllerRoundRelayRecord | undefined,
+  event: ControllerRoundTransitionEvent,
+): ControllerRoundTransitionDecision {
+  switch (event.type) {
+    case 'occurrence_requested': {
+      const previous = current;
+      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);
+        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 (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
+        // provider adapter may retry that known, non-ambiguous failure without
+        // manufacturing a new semantic occurrence.  A caller that presents an
+        // occurrence id is explicitly asking to reopen the failed lineage as
+        // an external occurrence, which remains fenced below.  Other prior
+        // 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 === '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' };
+      }
+      const maxRounds = previous ? Math.min(previous.maxRounds, event.maxRounds) : event.maxRounds;
+      const maxRepeatedState = previous ? Math.min(previous.maxRepeatedState, event.maxRepeatedState) : event.maxRepeatedState;
+      const maxFailures = previous ? Math.min(previous.maxFailures, event.maxFailures) : event.maxFailures;
+      // A legal new semantic occurrence advances the existing lineage budget; it never
+      // 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;
+      const repeatedStateCount = previous ? (previous.stateFingerprint === event.stateFingerprint ? previous.repeatedStateCount + 1 : 0) : 0;
+      const consecutiveFailures = event.abandonedReleaseRecovery && previous ? previous.consecutiveFailures : 0;
+      let blockedReason: string | undefined;
+      if (roundCount > maxRounds) blockedReason = `round_budget_exhausted:${roundCount}>${maxRounds}`;
+      else if (repeatedStateCount >= maxRepeatedState) blockedReason = `repeated_state:${repeatedStateCount}>=${maxRepeatedState}`;
+      else if (consecutiveFailures >= maxFailures) blockedReason = `consecutive_failures:${consecutiveFailures}>=${maxFailures}`;
+      const record: ControllerRoundRelayRecord = {
+        schemaVersion: 1, repoId: event.repoId, relayScopeId: event.relayScopeId, originWorkId: event.originWorkId,
+        ...(event.requirementId ? { requirementId: event.requirementId } : {}), disposition: 'continue_immediately',
+        status: blockedReason ? 'blocked' : 'dispatching', lifecycleStage: 'dispatching',
+        observationWindow: previous?.observationWindow, qualityDecisions: previous?.qualityDecisions, qualityAdjustmentResults: previous?.qualityAdjustmentResults,
+        controllerId: event.identity.controllerId.trim().slice(0, 240) || 'controller-host', controllerType: event.identity.controllerType,
+        principalId: event.identity.principalId.trim().slice(0, 240) || event.identity.controllerId.trim().slice(0, 240),
+        controllerInstanceId: event.identity.controllerInstanceId.trim().slice(0, 240), sessionId: event.identity.sessionId.trim().slice(0, 240),
+        claimGeneration: 0, authorityId: event.proposedAuthorityId, stateFingerprint: event.stateFingerprint, roundCount, repeatedStateCount, consecutiveFailures,
+        ...(previous?.providerFailureTotal !== undefined ? { providerFailureTotal: previous.providerFailureTotal } : {}),
+        ...(previous?.providerRecoveryEpoch !== undefined ? { providerRecoveryEpoch: previous.providerRecoveryEpoch } : {}),
+        ...(previous?.providerRecoveryEvidenceId ? { providerRecoveryEvidenceId: previous.providerRecoveryEvidenceId } : {}),
+        maxRounds, maxRepeatedState, maxFailures,
+        reason: event.abandonedReleaseRecovery ? 'launcher_start_recovered_abandoned_claim' : 'launcher_start_requested_continuation',
+        ...(event.bindingId ? { bindingId: event.bindingId } : previous?.bindingId ? { bindingId: previous.bindingId } : {}),
+        ...(event.occurrenceId ? { occurrenceId: event.occurrenceId } : {}), ...(blockedReason ? { blockedReason } : {}), submittedAt: event.at, updatedAt: event.at,
+      };
+      return { kind: 'accept', next: record, action: blockedReason ? 'controller_round_initial_launch_blocked' : 'controller_round_initial_launch_begin' };
+    }
+    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}` };
+      return accept(current, {
+        status: 'dispatched', lifecycleStage: 'dispatch_confirmed', consecutiveFailures: 0, providerDispatchEffectId: event.providerDispatchEffectId,
+        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');
+    }
+    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' };
+      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,
+      }, 'controller_round_relay_dispatch_outcome_unknown');
+    }
+    case 'provider_user_action_required': {
+      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.handoffId.trim()) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_WAIT_FOR_USER_HANDOFF_REQUIRED' };
+      return accept(current, {
+        status: 'waiting_for_user', nextRecoveryAt: undefined, failureClass: undefined, lastError: event.error,
+        blockedReason: 'provider_user_action_required', handoffId: event.handoffId, updatedAt: event.at,
+      }, 'controller_round_relay_waiting_for_user');
+    }
+    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}` };
+      const failures = current.consecutiveFailures + 1;
+      if (!event.recovery) {
+        return accept(current, { status: 'failed', consecutiveFailures: failures, providerFailureTotal: (current.providerFailureTotal ?? 0) + 1, nextRecoveryAt: undefined, failureClass: undefined, lastError: event.error, updatedAt: event.at }, 'controller_round_relay_failed');
+      }
+      const blocked = failures >= current.maxFailures;
+      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,
+        nextRecoveryAt: blocked ? undefined : event.nextRecoveryAt, updatedAt: event.at,
+      }, blocked ? 'controller_round_relay_recovery_blocked' : 'controller_round_relay_recovery_retry_scheduled');
+    }
+    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' };
+      if (!event.evidenceId.trim()) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_PROVIDER_RECOVERY_EVIDENCE_REQUIRED' };
+      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,
+        reason: `provider_environment_recovered:${event.evidenceId.slice(0, 240)}`, updatedAt: event.at,
+      }, 'controller_round_relay_provider_environment_recovered');
+    }
+    case 'legacy_occurrence_bound': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status !== 'dispatching') return { kind: 'reject', code: `CONTROLLER_RELAY_LEGACY_OCCURRENCE_STATE_INVALID:${current.status}` };
+      if (current.occurrenceId?.trim()) return { kind: 'reject', code: `CONTROLLER_RELAY_OCCURRENCE_ALREADY_BOUND:${current.occurrenceId.trim()}` };
+      if (!current.authorityId?.trim()) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_LEGACY_OCCURRENCE_AUTHORITY_REQUIRED' };
+      if ((current.providerRecoveryEpoch ?? 0) < 1 || !current.providerRecoveryEvidenceId?.trim()) {
+        return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_LEGACY_OCCURRENCE_PROVIDER_RECOVERY_REQUIRED' };
+      }
+      const occurrenceId = event.occurrenceId.trim();
+      if (!occurrenceId) return { kind: 'needs_evidence', code: 'CONTROLLER_RELAY_OCCURRENCE_ID_REQUIRED' };
+      return accept(current, { occurrenceId, updatedAt: event.at }, 'controller_round_relay_legacy_occurrence_bound');
+    }
+    case 'controller_claim_observed': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status === 'claimed') {
+        if (current.controllerId === event.session.controllerId && current.sessionId === event.session.sessionId && current.claimGeneration === event.session.claimGeneration) {
+          return { kind: 'no_op', current, reason: 'claim_already_acknowledged' };
+        }
+        return accept(current, { controllerType: event.session.controllerType, controllerInstanceId: event.controllerInstanceId, sessionId: event.session.sessionId, claimGeneration: event.session.claimGeneration, lifecycleStage: 'controller_claimed', claimedAt: event.at, updatedAt: event.at, failureClass: undefined, lastError: undefined }, 'controller_round_relay_claim_migrated');
+      }
+      const blocker = controllerRoundBlockerClass(current);
+      if (blocker === 'provider_dispatch_outcome_unknown') {
+        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 (!['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 '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' };
+      if (event.stateFingerprint === current.stateFingerprint) return { kind: 'no_op', current, reason: 'semantic_fingerprint_unchanged' };
+      if (current.roundCount > current.maxRounds || current.consecutiveFailures >= current.maxFailures) return { kind: 'reject', code: 'CONTROLLER_RELAY_OTHER_BUDGET_EXHAUSTED' };
+      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, stateFingerprint: event.stateFingerprint, repeatedStateCount: 0, blockedReason: undefined, failureClass: undefined, lastError: undefined, claimedAt: event.at, updatedAt: event.at }, 'controller_round_relay_claim_rearmed_after_state_change');
+    }
+    case 'stalled_round_observed': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      const blocker = controllerRoundBlockerClass(current);
+      if (blocker && blocker !== 'repeated_state') return { kind: 'reject', code: `CONTROLLER_RELAY_STALLED_BLOCKER_NOT_RECOVERABLE:${blocker}` };
+      if (!['pending_release', 'dispatching', 'dispatched', 'claimed', 'blocked'].includes(current.status)) return { kind: 'reject', code: `CONTROLLER_RELAY_STALLED_STATE_INVALID:${current.status}` };
+      if (blocker === 'repeated_state' && event.stateFingerprint === current.stateFingerprint) return { kind: 'no_op', current, reason: 'semantic_fingerprint_unchanged' };
+      const resumesUndispatchedRound = current.status === 'pending_release' || current.status === 'dispatching';
+      const roundCount = current.roundCount + (resumesUndispatchedRound ? 0 : 1);
+      const repeatedStateCount = resumesUndispatchedRound ? current.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}`;
+      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');
+    }
+    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 maxRounds = Math.min(current.maxRounds, event.maxRounds);
+      const maxRepeatedState = Math.min(current.maxRepeatedState, event.maxRepeatedState);
+      const maxFailures = Math.min(current.maxFailures, event.maxFailures);
+      const continuing = event.disposition === 'continue_immediately';
+      const roundCount = current.roundCount + (continuing ? 1 : 0);
+      const repeatedStateCount = continuing
+        ? (current.stateFingerprint === event.stateFingerprint ? current.repeatedStateCount + 1 : 0)
+        : current.repeatedStateCount;
+      let blockedReason: string | undefined;
+      if (continuing) {
+        if (roundCount > maxRounds) blockedReason = `round_budget_exhausted:${roundCount}>${maxRounds}`;
+        else if (repeatedStateCount >= maxRepeatedState) blockedReason = `repeated_state:${repeatedStateCount}>=${maxRepeatedState}`;
+        else if (current.consecutiveFailures >= maxFailures) blockedReason = `consecutive_failures:${current.consecutiveFailures}>=${maxFailures}`;
+      }
+      const status = blockedReason ? 'blocked' : continuing ? 'pending_release' : event.disposition === 'wait' ? 'waiting' : event.disposition === 'wait_for_user' ? 'waiting_for_user' : 'goal_complete';
+      const sessionIdentity = {
+        controllerId: event.controllerSession.controllerId,
+        controllerType: event.controllerSession.controllerType,
+        principalId: event.controllerSession.principalId?.trim() || event.controllerSession.controllerId,
+        controllerInstanceId: event.controllerSession.controllerInstanceId?.trim() || '',
+        // A transport/session rollover inside the same Runtime does not change
+        // the durable relay owner. A new Runtime instance is the explicit
+        // recovery boundary that permits the terminal identity handoff.
+        sessionId: event.controllerSession.controllerInstanceId?.trim() !== current.controllerInstanceId?.trim()
+          ? event.controllerSession.sessionId
+          : current.sessionId,
+        claimGeneration: event.controllerSession.claimGeneration ?? current.claimGeneration,
+      };
+      return accept(current, {
+        disposition: event.disposition, status, lifecycleStage: 'semantic_round_closed', stateFingerprint: event.stateFingerprint,
+        roundCount, repeatedStateCount, maxRounds, maxRepeatedState, maxFailures,
+        ...(status === 'goal_complete' ? sessionIdentity : {}),
+        ...(event.qualityDecisions ? { qualityDecisions: event.qualityDecisions } : {}),
+        ...(event.qualityAdjustmentResults ? { qualityAdjustmentResults: event.qualityAdjustmentResults } : {}),
+        ...(event.observationWindow ? { observationWindow: event.observationWindow } : {}),
+        ...(event.handoffId ? { handoffId: event.handoffId } : {}),
+        ...(event.reason ? { reason: event.reason } : {}),
+        ...(event.bindingId ? { bindingId: event.bindingId } : {}),
+        blockedReason, submittedAt: event.at, updatedAt: event.at,
+      }, 'controller_round_disposition_submitted');
+    }
+    case 'successor_bound': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      if (current.status !== 'claimed') return { kind: 'reject', code: `CONTROLLER_RELAY_SUCCESSOR_BIND_REQUIRES_CLAIMED_ROUND:${current.status}` };
+      if (current.successorWorkId === event.successorWorkId) return { kind: 'no_op', current, reason: 'successor_already_bound' };
+      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 '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}` };
+      if (current.successorWorkId !== event.successorWorkId) return { kind: 'reject', code: 'CONTROLLER_RELAY_SUCCESSOR_HANDOFF_STALE' };
+      const handedOff: ControllerRoundRelayRecord = { ...current, 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, repeatedStateCount: 0, controllerInstanceId: '', sessionId: '', claimGeneration: 0,
+        assistantContextSnapshot: 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_relay_successor_handoff_closed', relatedWorkId: event.successorWorkId, relatedNext: successor, relatedAction: 'controller_round_relay_successor_dispatch_begin' };
+    }
+    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');
+    }
+    case 'terminal_work_observed': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      return current.status === 'failed' ? { kind: 'no_op', current, reason: 'terminal_work_already_retired' } : accept(current, { status: 'failed', failureClass: 'terminal_work', lastError: event.error, claimedAt: undefined, updatedAt: event.at }, 'controller_round_relay_terminal_work_retired');
+    }
+    case 'abandoned_release_observed': {
+      if (!current) return { kind: 'reject', code: 'CONTROLLER_RELAY_CURRENT_REQUIRED' };
+      return current.status !== 'claimed' ? { kind: 'no_op', current, reason: 'round_not_claimed' } : accept(current, { status: 'failed', failureClass: 'abandoned_release', lastError: event.error, claimedAt: undefined, updatedAt: event.at }, 'controller_round_relay_abandoned_release');
+    }
+    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');
+    }
+  }
+}

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

@@ -0,0 +1,107 @@
+import type { AssistantContextSnapshot, ClosedRoundObservation, ExecutionQualityAdjustmentResult, ExecutionQualityDecision } from './execution-quality';
+import type { ControllerType } from './types';
+
+export const CONTROLLER_ROUND_DISPOSITIONS = [
+  'continue_immediately',
+  'wait',
+  'wait_for_user',
+  'goal_complete',
+] as const;
+export type ControllerRoundDisposition = (typeof CONTROLLER_ROUND_DISPOSITIONS)[number];
+
+export const CONTROLLER_RELAY_ABANDONED_RELEASE_ERROR = 'CONTROLLER_RELAY_CLAIM_RELEASED_WITHOUT_DISPOSITION';
+
+export type ControllerRoundLifecycleStage =
+  | 'dispatching'
+  | 'dispatch_confirmed'
+  | 'controller_claimed'
+  | 'semantic_round_closed';
+
+export type ControllerRoundRelayStatus =
+  | 'pending_release'
+  | 'dispatching'
+  | 'dispatched'
+  | 'claimed'
+  | 'waiting'
+  | 'waiting_for_user'
+  | 'goal_complete'
+  | 'handed_off'
+  | 'blocked'
+  | 'failed';
+
+export type ControllerRoundFailureClass = 'terminal_work' | 'abandoned_release';
+
+export interface ControllerRoundRelayRecord {
+  schemaVersion: 1;
+  repoId: string;
+  relayScopeId: string;
+  originWorkId: string;
+  /** Previous Work when this round was mechanically handed across a Plan successor. */
+  predecessorWorkId?: string;
+  /** Already-admitted successor Work selected by GoalWorkloop; never selected by ControllerRound. */
+  successorWorkId?: string;
+  requirementId?: string;
+  disposition: ControllerRoundDisposition;
+  status: ControllerRoundRelayStatus;
+  /** Durable semantic stage; transport/session state must never substitute for lifecycle authority. */
+  lifecycleStage?: ControllerRoundLifecycleStage;
+  controllerId: string;
+  controllerType: ControllerType;
+  principalId: string;
+  controllerInstanceId: string;
+  sessionId: string;
+  claimGeneration: number;
+  /** Opaque per-round capability. Rotates when Forge dispatches a new controller round. */
+  authorityId?: string;
+  stateFingerprint: string;
+  /** Round owner appends only at semantic close; oldest entries expire with this bounded record. */
+  observationWindow?: ClosedRoundObservation[];
+  qualityDecisions?: ExecutionQualityDecision[];
+  /** Verified post-adjustment outcomes; these never reset ControllerRound budgets. */
+  qualityAdjustmentResults?: ExecutionQualityAdjustmentResult[];
+  /** Exact bounded assistant context identity delivered for the currently claimed round. */
+  assistantContextSnapshot?: AssistantContextSnapshot;
+  roundCount: number;
+  repeatedStateCount: number;
+  consecutiveFailures: number;
+  maxRounds: number;
+  maxRepeatedState: number;
+  maxFailures: number;
+  handoffId?: string;
+  reason?: string;
+  /** Opaque provider binding owned by a ControllerHost adapter. */
+  bindingId?: string;
+  /** Stable provider-neutral identity for the exact external dispatch responsibility. */
+  providerDispatchEffectId?: string;
+  /** Monotonic provider-effect attempt within one semantic round authority. */
+  providerDispatchAttempt?: number;
+  /** Monotonic historical provider failures; recovery epochs never erase it. */
+  providerFailureTotal?: number;
+  /** Bounded provider-recovery epoch for the same semantic round. */
+  providerRecoveryEpoch?: number;
+  providerRecoveryEvidenceId?: string;
+  providerFailureEvidenceId?: string;
+  providerEffectReconciliationEvidenceId?: string;
+  providerDispatchStartedAt?: string;
+  /** Canonical provider-dispatch receipt for this semantic round. Scheduler occurrence copies it only as a replay projection. */
+  providerDispatchReceiptId?: string;
+  /** Explicit schedule/manual/replan occurrence identity when a prior lineage exists. */
+  occurrenceId?: string;
+  blockedReason?: string;
+  /** Typed failed-lineage classification. lastError remains diagnostic text only. */
+  failureClass?: ControllerRoundFailureClass;
+  lastError?: string;
+  nextRecoveryAt?: string;
+  submittedAt: string;
+  updatedAt: string;
+  dispatchedAt?: string;
+  claimedAt?: string;
+}
+
+export interface ControllerRoundRelayIdentity {
+  controllerId: string;
+  controllerType: ControllerType;
+  principalId: string;
+  controllerInstanceId: string;
+  sessionId: string;
+}