@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/release/release-state-migration.ts

@@ -0,0 +1,25 @@
+import { migrateReleaseSessionState, type ReleaseSessionStateMigration } from './release-session';
+import { migrateRuntimeReleaseAuthorityState, readRuntimeReleaseAuthority, type RuntimeReleaseAuthority } from '../root/release-store';
+
+export interface ReleaseDurableStateMigration {
+  authority?: RuntimeReleaseAuthority;
+  sessions: ReleaseSessionStateMigration;
+}
+
+/**
+ * One migration boundary for all persisted Runtime release semantics.
+ * Runtime and Recovery cross this boundary before they declare themselves ready
+ * or consume ReleaseSession state. RuntimeReleaseAuthority upgrades its storage
+ * schema; ReleaseSession keeps downgrade-readable wire schema 1 while migrating
+ * once to semanticEpoch 2. Steady-state readers consume only the current model.
+ */
+export function migrateReleaseDurableState(controllerHome: string): ReleaseDurableStateMigration {
+  const authority = migrateRuntimeReleaseAuthorityState(controllerHome);
+  const sessions = migrateReleaseSessionState(controllerHome, {
+    readAuthority: () => authority ?? readRuntimeReleaseAuthority(controllerHome),
+  });
+  return {
+    ...(authority ? { authority } : {}),
+    sessions,
+  };
+}

package/src/runtime/resources/leases/store.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from 'crypto';
 import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { controllerSystemRoot } from '../../../cli/repositories/controller-home';
 import { ControllerLockContentionError, withControllerLock } from '../../../cli/repositories/locks';
 import type { ResourceClaimSpec } from '../../execution/jobs/types';
 import { readJsonFile, removeFile, writeJsonAtomic } from '../../shared/json-files';
@@ -9,7 +9,7 @@ import { markRepositoryProjectionDirty } from '../../projections/invalidation';
 import { touchSchedulerWakeSignal } from '../../control-plane/global-scheduler/wake-signal';
 import { claimsConflict } from '../claims/conflicts';
 import { appendRuntimeEvent } from '../../evidence/event-ledger';
-import { assertRuntimeMayWrite, assertRuntimeMayWriteOrThrow } from '../../root/write-fence';
+import { assertRuntimeMayWrite, assertRuntimeMayWriteOrThrow, getRuntimeWriteClaim, isRuntimeWriteFenceError } from '../../root/write-fence';
 import type {
   ExecutionLease,
   LeaseAcquisitionOptions,
@@ -18,8 +18,10 @@ import type {
   ExecutionLeaseOwnerIdentity,
 } from './types';
 
-function leaseRoot(controllerHome: string, repoId: string): string {
-  return join(repositoryControllerRoot(controllerHome, repoId), 'leases');
+function leaseRoot(controllerHome: string, _repoId: string): string {
+  // Concrete resource leases coordinate across the whole ForgeInstance. repoId
+  // is provenance/filter metadata, never the storage partition.
+  return join(controllerSystemRoot(controllerHome), 'execution-leases');
 }
 function activeRoot(controllerHome: string, repoId: string): string { return join(leaseRoot(controllerHome, repoId), 'active'); }
 function leasePath(controllerHome: string, repoId: string, leaseId: string): string { return join(activeRoot(controllerHome, repoId), `${leaseId}.json`); }
@@ -29,6 +31,21 @@ function counterPath(controllerHome: string, repoId: string, resourceKey: string
 }
 function expired(lease: ExecutionLease): boolean { return Date.parse(lease.expiresAt) <= Date.now(); }
 
+function currentManagedRuntimeClaim(controllerHome: string) {
+  const fence = assertRuntimeMayWrite(undefined, controllerHome);
+  if (!fence.allowed) return undefined;
+  const current = getRuntimeWriteClaim();
+  return current && !current.unmanaged ? current : undefined;
+}
+
+function fencedEphemeralOwner(lease: ExecutionLease, current: ReturnType<typeof getRuntimeWriteClaim>): boolean {
+  if (lease.visibility !== 'ephemeral' || !lease.ownerIdentity || !current || current.unmanaged) return false;
+  const ownerInstanceId = lease.ownerIdentity.controllerInstanceId?.trim();
+  const ownerGeneration = lease.ownerIdentity.controllerGeneration?.trim();
+  if (!ownerInstanceId || !ownerGeneration || ownerGeneration === 'unbound') return false;
+  return ownerInstanceId !== current.runtimeInstanceId;
+}
+
 function validateClaimScopes(repoId: string, claims: ResourceClaimSpec[]): void {
   const checkoutIds = new Set<string>();
   const workIds = new Set<string>();
@@ -82,10 +99,12 @@ function normalizedOwnerIdentity(
     branch: provided?.branch?.trim() || 'unknown',
     principalId: provided?.principalId?.trim() || `owner:${ownerJobId}`,
     controllerInstanceId: provided?.controllerInstanceId?.trim()
+      || process.env.FORGE_RUNTIME_INSTANCE_ID?.trim()
       || process.env.FORGE_WRITER_INSTANCE_ID?.trim()
       || process.env.FORGE_DAEMON_INSTANCE_ID?.trim()
       || `process:${process.pid}`,
     controllerGeneration: provided?.controllerGeneration?.trim()
+      || process.env.FORGE_RUNTIME_INCARNATION_GENERATION?.trim()
       || process.env.FORGE_WRITER_GENERATION?.trim()
       || process.env.FORGE_ACTIVE_RUNTIME_REVISION?.trim()
       || 'unbound',
@@ -139,19 +158,29 @@ export function resetLeaseSideEffectMetrics(): void {
   leaseSideEffectMetrics.ephemeralReleases = 0;
 }
 
-export function listActiveLeases(controllerHome: string, repoId: string): ExecutionLease[] {
-  try {
-    const leases: ExecutionLease[] = [];
-    for (const name of readdirSync(activeRoot(controllerHome, repoId)).filter((entry) => entry.endsWith('.json'))) {
-      const path = join(activeRoot(controllerHome, repoId), name);
-      try {
-        const lease = readJsonFile<ExecutionLease>(path);
-        if (expired(lease)) removeFile(path);
-        else leases.push(lease);
-      } catch { removeFile(path); }
+function listAllActiveLeases(controllerHome: string): ExecutionLease[] {
+  const root = activeRoot(controllerHome, '__instance__');
+  if (!existsSync(root)) return [];
+  const currentRuntime = currentManagedRuntimeClaim(controllerHome);
+  const leases: ExecutionLease[] = [];
+  for (const name of readdirSync(root).filter((entry) => entry.endsWith('.json'))) {
+    const path = join(root, name);
+    try {
+      const lease = readJsonFile<ExecutionLease>(path);
+      if (!lease?.leaseId || !lease.repoId || !lease.resourceKey || !lease.ownerJobId) {
+        throw new Error('required lease identity is missing');
+      }
+      if (expired(lease) || fencedEphemeralOwner(lease, currentRuntime)) removeFile(path);
+      else leases.push(lease);
+    } catch (error) {
+      throw new Error(`LEASE_STORE_CORRUPT: ${path}: ${error instanceof Error ? error.message : String(error)}`);
     }
-    return leases;
-  } catch { return []; }
+  }
+  return leases;
+}
+
+export function listActiveLeases(controllerHome: string, repoId: string): ExecutionLease[] {
+  return listAllActiveLeases(controllerHome).filter((lease) => lease.repoId === repoId);
 }
 
 export function acquireExecutionLeases(
@@ -186,8 +215,9 @@ export function acquireExecutionLeases(
   const identityDigest = ownerIdentityDigest(ownerIdentity);
 
   try {
-    return withControllerLock(controllerHome, { scope: 'repository', repoId }, `lease-acquire:${ownerJobId}`, () => {
-    const active = listActiveLeases(controllerHome, repoId).filter((lease) => lease.ownerJobId !== ownerJobId);
+    return withControllerLock(controllerHome, { scope: 'global', resource: 'execution-leases' }, `lease-acquire:${ownerJobId}`, () => {
+    const active = listAllActiveLeases(controllerHome)
+      .filter((lease) => lease.ownerJobId !== ownerJobId || lease.repoId !== repoId);
     const blockers = claims.flatMap((claim) => active
       .filter((lease) => claimsConflict(claim, lease))
       .map((lease) => ({ resourceKey: lease.resourceKey, ownerJobId: lease.ownerJobId, leaseId: lease.leaseId, mode: lease.mode, ownerIdentityDigest: lease.ownerIdentityDigest })));
@@ -297,10 +327,10 @@ export function renewExecutionLeases(
   try {
     assertRuntimeMayWriteOrThrow('renew_lease', controllerHome);
   } catch (error) {
-    if (error instanceof Error && error.message.startsWith('WRITER_FENCED:')) throw error;
+    if (isRuntimeWriteFenceError(error)) throw error;
     /* unbound legacy */
   }
-  return withControllerLock(controllerHome, { scope: 'repository', repoId }, `lease-renew:${ownerJobId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: 'execution-leases' }, `lease-renew:${ownerJobId}`, () => {
     const expectedRefs = expectedLeaseMap(expected);
     const timestamp = new Date().toISOString();
     const owned = listActiveLeases(controllerHome, repoId)
@@ -329,10 +359,10 @@ export function releaseExecutionLeases(
   try {
     assertRuntimeMayWriteOrThrow('release_lease', controllerHome);
   } catch (error) {
-    if (error instanceof Error && error.message.startsWith('WRITER_FENCED:')) throw error;
+    if (isRuntimeWriteFenceError(error)) throw error;
     /* unbound legacy */
   }
-  return withControllerLock(controllerHome, { scope: 'repository', repoId }, `lease-release:${ownerJobId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: 'execution-leases' }, `lease-release:${ownerJobId}`, () => {
     const expectedRefs = expectedLeaseMap(expected);
     let releasedCount = 0;
     let visibility: LeaseVisibility = options?.visibility ?? 'durable';
@@ -384,10 +414,10 @@ export function releaseExactExecutionLeases(
   try {
     assertRuntimeMayWriteOrThrow('release_lease', controllerHome);
   } catch (error) {
-    if (error instanceof Error && error.message.startsWith('WRITER_FENCED:')) throw error;
+    if (isRuntimeWriteFenceError(error)) throw error;
     /* unbound legacy */
   }
-  return withControllerLock(controllerHome, { scope: 'repository', repoId }, `lease-release-exact:${ownerJobId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: 'execution-leases' }, `lease-release-exact:${ownerJobId}`, () => {
     const expectedRefs = expectedLeaseMap(expected) ?? new Map<string, ExpectedLeaseRef>();
     if (expectedRefs.size !== expected.length) {
       throw new Error(`LEASE_SET_INVALID: ${ownerJobId} contains duplicate lease ids`);
@@ -460,7 +490,7 @@ export function releaseTerminalProcessLeases(
   const normalizedProcessId = processId.trim();
   if (!normalizedProcessId) throw new Error('TERMINAL_PROCESS_ID_REQUIRED');
   const ownerJobId = `process:${normalizedProcessId}`;
-  return withControllerLock(controllerHome, { scope: 'repository', repoId }, `terminal-lease-release:${ownerJobId}`, () => {
+  return withControllerLock(controllerHome, { scope: 'global', resource: 'execution-leases' }, `terminal-lease-release:${ownerJobId}`, () => {
     const expectedRefs = expectedLeaseMap(expected) ?? new Map<string, ExpectedLeaseRef>();
     if (expectedRefs.size !== expected.length) {
       throw new Error(`TERMINAL_PROCESS_LEASE_SET_INVALID: ${normalizedProcessId} contains duplicate lease ids`);
@@ -530,6 +560,7 @@ export function assertFencingToken(
   const path = leasePath(controllerHome, repoId, leaseId);
   if (!existsSync(path)) throw new Error(`LEASE_EXPIRED: ${leaseId}`);
   const lease = readJsonFile<ExecutionLease>(path);
+  if (lease.repoId !== repoId) throw new Error(`LEASE_REPOSITORY_SCOPE_MISMATCH: expected ${repoId}, received ${lease.repoId}`);
   if (expired(lease)) {
     removeFile(path);
     throw new Error(`LEASE_EXPIRED: ${leaseId}`);

package/src/runtime/root/computer-composition.ts

@@ -3,9 +3,12 @@ import {
   ComputerProviderRegistry,
   computerProviderRegistrationSnapshot,
 } from '../../../packages/plugin-runtime/computer/index';
+import { randomUUID } from 'crypto';
 import {
   COMPUTER_BROWSER_AUTOMATION_CAPABILITY,
   COMPUTER_CONSOLE_UNLOCK_CAPABILITY,
+  COMPUTER_ELEMENT_OBSERVE_CAPABILITY,
+  COMPUTER_INPUT_CAPABILITY,
   type ComputerBrowserAutomationRequest,
   type ComputerBrowserProduct,
   type ComputerConsoleUnlockCommandRequest,
@@ -37,7 +40,7 @@ function computerCompositionKey(controllerHome: string): string {
   const registration = currentDesktopOperatorRegistration(controllerHome);
   const fingerprint = registration
     ? `${registration.revision}:${registration.registrationFingerprint}:${registration.enabled ? 'enabled' : 'disabled'}`
-    : 'desktop_operator:unregistered_v0_2';
+    : 'desktop_operator:unregistered';
   return `${controllerHome}:${currentComputerPlatform()}:${fingerprint}`;
 }
 
@@ -54,9 +57,6 @@ function ensureComputerComposition(controllerHome: string = resolveControllerHom
         if (providerPluginId !== DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID || !registration) return undefined;
         return computerProviderRegistrationSnapshot(registration);
       },
-      // Compatibility is an explicit Runtime composition decision, never an adapter fallback.
-      // Remove this switch once Desktop Operator 0.2.x support is retired.
-      legacyFallback: 'unregistered_v0_2',
     });
     next.register(desktopOperatorProvider);
   }
@@ -111,8 +111,8 @@ export async function executeRuntimeComputerConsoleUnlock(
   controllerHome: string = resolveControllerHome(),
 ): Promise<Record<string, unknown>> {
   if (request.capability !== COMPUTER_CONSOLE_UNLOCK_CAPABILITY
-    || !['prepare_unlock_console', 'unlock_console'].includes(request.action)) {
-    throw new AssistantPluginError('COMPUTER_CONSOLE_UNLOCK_REQUEST_INVALID', 'Protected console unlock accepts only computer.console.unlock.v1 prepare/unlock commands.', { retryable: false });
+    || !['prepare_unlock_console', 'unlock_console', 'console_unlock_enroll', 'console_unlock_status', 'console_unlock_recover', 'console_unlock_revoke'].includes(request.action)) {
+    throw new AssistantPluginError('COMPUTER_CONSOLE_UNLOCK_REQUEST_INVALID', 'Protected console unlock accepts only declared computer.console.unlock.v1 temporary or unattended-recovery commands.', { retryable: false });
   }
   if (authorization.kind !== 'explicit_single_use'
     || authorization.confirmed !== true
@@ -143,6 +143,191 @@ export async function executeRuntimeComputerBrowserAutomation(
   return await desktopOperatorProvider.executeBrowserCompatibility(request, timeoutMs);
 }
 
+type BrowserTrustedInputSemanticProof = {
+  domRole: string;
+  accessibleName: string;
+  editable: true;
+  focused: true;
+  multiline: boolean;
+};
+type BrowserTrustedInputRequest = Extract<ComputerBrowserAutomationRequest, { action: 'trusted_input' }> & {
+  semanticTarget?: BrowserTrustedInputSemanticProof;
+};
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function stringValue(record: Record<string, unknown> | undefined, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = record?.[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+function browserTrustedInputAction(
+  controllerHome: string,
+  actionId: string,
+  args: Record<string, unknown>,
+  requestId: string,
+  timeoutMs: number,
+): AssistantPluginActionExecutionInput {
+  return {
+    controllerHome,
+    repoId: '__controller__',
+    repoRoot: controllerHome,
+    pluginId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID,
+    actionId,
+    requestId,
+    args,
+    origin: { surface: 'system', actor: 'native-browser-trusted-input' },
+    timeoutMs,
+  };
+}
+
+/**
+ * Trusted text/key input is a Unified Computer concern, not Browser compatibility.
+ * Browser owns the exact tab and DOM identity; the Desktop Operator interaction is
+ * a short-lived transport binding used only after that exact tab is already
+ * foreground. No provider session is promoted into a second semantic authority.
+ */
+export async function executeRuntimeComputerBrowserTrustedInput(
+  request: BrowserTrustedInputRequest,
+  timeoutMs: number,
+  controllerHome: string = resolveControllerHome(),
+): Promise<Record<string, unknown>> {
+  if (request.input.kind !== 'text' && request.input.kind !== 'key') {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_UNIFIED_INPUT_KIND_UNSUPPORTED',
+      `Unified native Browser input handles text/key only, not ${request.input.kind}.`,
+      { retryable: false, details: { browserProduct: request.product, inputKind: request.input.kind } },
+    );
+  }
+  if (currentComputerPlatform() !== 'darwin') {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_TRUSTED_INPUT_UNSUPPORTED_PLATFORM',
+      `Native Browser trusted input is unavailable on ${currentComputerPlatform()}.`,
+      { retryable: false, details: { browserProduct: request.product } },
+    );
+  }
+  const expectedBundleId = NATIVE_BROWSER_BUNDLE_IDS[request.product];
+  const desktopOperator = getExternalPluginAdapter(controllerHome, DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID);
+  if (!desktopOperator) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_TRUSTED_INPUT_UNAVAILABLE',
+      'Native Browser trusted input requires the Unified Computer provider.',
+      { retryable: true, details: { browserProduct: request.product, providerId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID } },
+    );
+  }
+  const invocationId = randomUUID();
+  let interactionId = '';
+  let effectCompleted = false;
+  try {
+    const opened = await desktopOperator.executeAction(browserTrustedInputAction(
+      controllerHome,
+      'desktop_session_open',
+      { bundle_id: expectedBundleId, launch: false, activate: false },
+      `native-browser-trusted-input:${invocationId}:open`,
+      timeoutMs,
+    ));
+    interactionId = stringValue(opened, 'interactionId', 'interaction_id');
+    const observedBundleId = stringValue(opened, 'bundleIdentifier', 'bundle_id');
+    if (!interactionId || observedBundleId !== expectedBundleId) {
+      throw new AssistantPluginError(
+        observedBundleId ? 'PLUGIN_BROWSER_TRUSTED_INPUT_IDENTITY_MISMATCH' : 'PLUGIN_BROWSER_TRUSTED_INPUT_IDENTITY_UNVERIFIED',
+        'Unified Computer did not bind the exact requested native browser application.',
+        { retryable: false, details: { browserProduct: request.product, expectedBundleId, observedBundleId: observedBundleId || undefined } },
+      );
+    }
+
+    if (request.input.kind === 'text') {
+      if (request.input.text.length > 10_000) {
+        throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Trusted Browser text input must be at most 10000 characters.', { retryable: false });
+      }
+      const proof = request.semanticTarget;
+      if (!proof || proof.editable !== true || proof.focused !== true || !proof.accessibleName.trim() || !proof.domRole.trim()) {
+        throw new AssistantPluginError(
+          'PLUGIN_BROWSER_TRUSTED_INPUT_SEMANTIC_TARGET_REQUIRED',
+          'Unified Computer text input requires exact Browser-owned DOM semantic target proof.',
+          { retryable: false, details: { browserProduct: request.product } },
+        );
+      }
+      const expectedAxRole = proof.domRole === 'textbox'
+        ? (proof.multiline ? 'AXTextArea' : 'AXTextField')
+        : proof.domRole;
+      const observed = await executeRuntimeComputer({
+        capability: COMPUTER_ELEMENT_OBSERVE_CAPABILITY,
+        action: 'observe_elements',
+        interactionId,
+        maxDepth: 2,
+        maxNodes: 16,
+        includeValues: true,
+        rootSelector: { role: expectedAxRole },
+      }, timeoutMs, controllerHome);
+      const root = objectValue(observed.root);
+      const target = objectValue(root?.target);
+      const ref = stringValue(root, 'ref');
+      const targetInteractionId = stringValue(target, 'interactionId');
+      const targetBundleId = stringValue(target, 'bundleIdentifier');
+      const axAccessibleNames = [stringValue(root, 'description'), stringValue(root, 'name')].filter(Boolean);
+      const semanticIdentityMatches = axAccessibleNames.includes(proof.accessibleName.trim());
+      if (stringValue(root, 'role') !== expectedAxRole
+        || !semanticIdentityMatches
+        || !ref
+        || targetInteractionId !== interactionId
+        || targetBundleId !== expectedBundleId
+        || typeof target?.pid !== 'number'
+        || !Number.isInteger(target.pid)
+        || typeof target?.appName !== 'string'
+        || typeof target?.snapshotRevision !== 'number'
+        || !Number.isInteger(target.snapshotRevision)) {
+        throw new AssistantPluginError(
+          'PLUGIN_BROWSER_TRUSTED_INPUT_SEMANTIC_TARGET_MISMATCH',
+          'Unified Computer element identity no longer matches the Browser-owned active DOM target.',
+          { retryable: true, details: { browserProduct: request.product, interactionId, expectedAxRole, accessibleName: proof.accessibleName, observedRole: root?.role, observedNames: axAccessibleNames, ref: ref || undefined } },
+        );
+      }
+      // AX set_value can report success for Chromium contenteditable controls while
+      // React immediately restores the DOM value. Keep element.observe.v2 as the
+      // exact identity fence, then perform the actual text mutation through the
+      // Unified Computer input capability bound to that exact observed AX ref.
+      await executeRuntimeComputer({
+        capability: COMPUTER_INPUT_CAPABILITY,
+        action: 'type_text',
+        interactionId: targetInteractionId,
+        selector: { ref },
+        text: request.input.text,
+        replace: true,
+      }, timeoutMs, controllerHome);
+    } else {
+      await desktopOperator.executeAction(browserTrustedInputAction(
+        controllerHome,
+        'desktop_key',
+        { interaction_id: interactionId, keys: [request.input.key] },
+        `native-browser-trusted-input:${invocationId}:key`,
+        timeoutMs,
+      ));
+    }
+    effectCompleted = true;
+    return { performed: true, transport: 'computer', inputKind: request.input.kind };
+  } finally {
+    if (interactionId) {
+      try {
+        await desktopOperator.executeAction(browserTrustedInputAction(
+          controllerHome,
+          'desktop_session_close',
+          { interaction_id: interactionId },
+          `native-browser-trusted-input:${invocationId}:close`,
+          timeoutMs,
+        ));
+      } catch (error) {
+        // Provider-session cleanup is transport hygiene, never external-effect
+        // outcome authority. In particular, do not convert a confirmed text/key
+        // mutation into a replayable failure because session retirement failed.
+        process.stderr.write(`[computer-browser-trusted-input] cleanup_failed effect_completed=${effectCompleted} ${error instanceof Error ? error.message : String(error)}\n`);
+      }
+    }
+  }
+}
+
 export async function activateRuntimeComputerBrowserApplication(
   input: AssistantPluginActionExecutionInput,
   product: ComputerBrowserProduct,

package/src/runtime/root/controller-progression-composition.ts

@@ -0,0 +1,192 @@
+import {
+  beginControllerRoundRelayAfterRelease,
+  controllerRoundBlockerClass,
+  getControllerRoundRelay,
+  getControllerWorkBinding,
+  getRetainedControllerSession,
+  prepareControllerRoundOccurrence,
+  resumeControllerRoundOccurrence,
+  type ControllerBinding,
+  type ControllerHost,
+} from '../../../packages/kernel/controller/api/index';
+import { getWorkContract, semanticWorkState } from '../../../packages/kernel/work/api/index';
+import {
+  controllerHostForScheduledBinding,
+  ensureScheduledControllerBindingForWork,
+} from './scheduled-controller-composition';
+import {
+  ensureWorkflowSupervisorEnrollmentForWork,
+  type WorkflowSupervisorEnrollmentStatus,
+} from './workflow-supervisor-composition';
+
+export interface ControllerProgressionInput {
+  workId: string;
+  occurrenceId: string;
+  relayScopeId?: string;
+  continuationHint?: string;
+  allowSemanticWaitRecovery?: boolean;
+  scheduleName?: string;
+  bindingArgs?: Record<string, unknown>;
+}
+
+export interface ControllerProgressionDependencies {
+  ensureBinding?: typeof ensureScheduledControllerBindingForWork;
+  hostForBinding?: typeof controllerHostForScheduledBinding;
+  prepareOccurrence?: typeof prepareControllerRoundOccurrence;
+  resumeOccurrence?: typeof resumeControllerRoundOccurrence;
+  ensureSupervisorEnrollment?: typeof ensureWorkflowSupervisorEnrollmentForWork;
+}
+
+export type ControllerProgressionResult =
+  | { status: 'terminal_or_missing'; reason: string }
+  | { status: 'retained_session_missing'; reason: string }
+  | { status: 'human_controller'; reason: string }
+  | { status: 'semantic_wait'; reason?: string; binding: ControllerBinding }
+  | { status: 'wait_for_user'; reason?: string; binding: ControllerBinding }
+  | { status: 'rejected'; reason?: string; binding: ControllerBinding }
+  | {
+      status: 'chatgpt_enrolled';
+      binding: ControllerBinding;
+      relayScopeId: string;
+      reused: boolean;
+      supervisorEnrollment: {
+        status: WorkflowSupervisorEnrollmentStatus;
+        taskId?: string;
+        effectId?: string;
+        reason?: string;
+      };
+    }
+  | {
+      status: 'chatgpt_not_enrolled';
+      binding: ControllerBinding;
+      relayScopeId: string;
+      reused: boolean;
+      supervisorEnrollment: {
+        status: WorkflowSupervisorEnrollmentStatus;
+        taskId?: string;
+        effectId?: string;
+        reason?: string;
+      };
+    }
+  | {
+      status: 'provider_dispatched';
+      binding: ControllerBinding;
+      relayScopeId: string;
+      reused: boolean;
+      providerDispatchReceiptId?: string;
+    };
+
+/**
+ * Stateless composition for one already-authorized Controller progression
+ * occurrence. It owns no persistence and introduces no lifecycle state.
+ *
+ * Work decides semantic terminality. ControllerSession/ControllerRound provide
+ * retained execution identity and one mechanical occurrence. Workflow Supervisor
+ * exclusively reserves and delivers Work-bound ChatGPT effects. Non-ChatGPT
+ * ControllerHost remains the direct provider boundary.
+ */
+export async function reconcileControllerProgression(
+  options: { controllerHome: string; repoId: string; repoRoot: string },
+  input: ControllerProgressionInput,
+  dependencies: ControllerProgressionDependencies = {},
+): Promise<ControllerProgressionResult> {
+  const store = { controllerHome: options.controllerHome, repoId: options.repoId };
+  const work = getWorkContract(store, input.workId);
+  if (!work || semanticWorkState(work) !== 'open') {
+    return { status: 'terminal_or_missing', reason: work ? `WORK_TERMINAL:${semanticWorkState(work)}` : 'WORK_NOT_FOUND' };
+  }
+
+  const retainedSession = getRetainedControllerSession(store, input.workId);
+  if (!retainedSession) return { status: 'retained_session_missing', reason: 'CONTROLLER_SESSION_NOT_RETAINED' };
+  if (retainedSession.controllerType === 'human') return { status: 'human_controller', reason: 'HUMAN_CONTROLLER' };
+
+  const ensureBinding = dependencies.ensureBinding ?? ensureScheduledControllerBindingForWork;
+  const existingBinding = getControllerWorkBinding(store, input.workId)?.binding;
+  const binding = existingBinding ?? ensureBinding(store, {
+    workId: input.workId,
+    session: retainedSession,
+    scheduleName: input.scheduleName,
+    args: input.bindingArgs ?? {},
+  });
+
+  if (retainedSession.controllerType === 'chatgpt') {
+    const ensureSupervisorEnrollment = dependencies.ensureSupervisorEnrollment ?? ensureWorkflowSupervisorEnrollmentForWork;
+    let existingRound = getControllerRoundRelay(store, input.workId);
+    let controllerRoundOccurrenceId = input.occurrenceId;
+    if (existingRound?.status === 'pending_release') {
+      // The semantic turn already chose continue_immediately. Once its exact
+      // ControllerSession lease has been released, reopen that same durable
+      // ControllerRound for dispatch before reserving another Supervisor effect.
+      // Schedule occurrence ids are trigger evidence, not a replacement
+      // ControllerRound identity for an already-open continuation chain.
+      existingRound = beginControllerRoundRelayAfterRelease(store, {
+        workId: input.workId,
+        releasedSession: retainedSession,
+      }) ?? getControllerRoundRelay(store, input.workId);
+    }
+    // An already-open recoverable ControllerRound keeps its durable occurrence
+    // identity across Scheduler wake attempts. A fresh ScheduleOccurrence is
+    // trigger/evidence identity only; replacing the round occurrence here would
+    // manufacture a second open round and permanently self-block continuation.
+    if (existingRound?.occurrenceId?.trim()
+      && ['dispatching', 'dispatched', 'claimed'].includes(existingRound.status)) {
+      controllerRoundOccurrenceId = existingRound.occurrenceId.trim();
+    }
+    if (existingRound?.status === 'blocked'
+      && controllerRoundBlockerClass(existingRound) === 'provider_dispatch_outcome_unknown') {
+      const supervisorEnrollment = await ensureSupervisorEnrollment(store, input.workId);
+      return {
+        status: supervisorEnrollment.status === 'enrolled' ? 'chatgpt_enrolled' : 'chatgpt_not_enrolled',
+        binding,
+        relayScopeId: existingRound.relayScopeId,
+        reused: true,
+        supervisorEnrollment,
+      };
+    }
+
+    const prepareOccurrence = dependencies.prepareOccurrence ?? prepareControllerRoundOccurrence;
+    const prepared = prepareOccurrence(store, {
+      occurrenceId: controllerRoundOccurrenceId,
+      workId: input.workId,
+      controllerBindingId: binding.bindingId,
+      relayScopeId: input.relayScopeId,
+      continuationHint: input.continuationHint,
+      allowSemanticWaitRecovery: input.allowSemanticWaitRecovery,
+    });
+    if (prepared.outcome === 'semantic_wait') return { status: 'semantic_wait', reason: prepared.reason, binding };
+    if (prepared.outcome === 'wait_for_user') return { status: 'wait_for_user', reason: prepared.reason, binding };
+    if (prepared.outcome === 'rejected') return { status: 'rejected', reason: prepared.reason, binding };
+
+    const supervisorEnrollment = await ensureSupervisorEnrollment(store, input.workId);
+    return {
+      status: supervisorEnrollment.status === 'enrolled' ? 'chatgpt_enrolled' : 'chatgpt_not_enrolled',
+      binding,
+      relayScopeId: prepared.relay.relayScopeId,
+      reused: prepared.reused,
+      supervisorEnrollment,
+    };
+  }
+
+  const hostForBinding = dependencies.hostForBinding ?? controllerHostForScheduledBinding;
+  const host: ControllerHost = hostForBinding(options, binding);
+  const resumeOccurrence = dependencies.resumeOccurrence ?? resumeControllerRoundOccurrence;
+  const resumed = await resumeOccurrence(store, {
+    occurrenceId: input.occurrenceId,
+    workId: input.workId,
+    controllerBindingId: binding.bindingId,
+    relayScopeId: input.relayScopeId,
+    continuationHint: input.continuationHint,
+    allowSemanticWaitRecovery: input.allowSemanticWaitRecovery,
+  }, host);
+
+  if (resumed.outcome === 'semantic_wait') return { status: 'semantic_wait', reason: resumed.reason, binding };
+  if (resumed.outcome === 'wait_for_user') return { status: 'wait_for_user', reason: resumed.reason, binding };
+  if (resumed.outcome === 'rejected') return { status: 'rejected', reason: resumed.reason, binding };
+  return {
+    status: 'provider_dispatched',
+    binding,
+    relayScopeId: resumed.relay.relayScopeId,
+    reused: resumed.reused,
+    providerDispatchReceiptId: resumed.providerDispatchReceiptId,
+  };
+}