@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -0,0 +1,376 @@
+import {
+  ComputerProviderError,
+  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,
+  type ComputerConsoleUnlockProviderRequest,
+  type ComputerRuntimeExecutionRequest,
+  type ComputerRuntimeProviderExecutionRequest,
+} from '../../../packages/protocols/computer/index';
+import { DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID } from '../../../adapters/computer/desktop-operator-contract';
+import { createDesktopOperatorComputerProvider, type DesktopOperatorComputerProvider } from '../../../adapters/computer/index';
+import { resolveControllerHome } from '../../cli/repositories/controller-home';
+import { currentComputerPlatform } from '../platform/computer-platform';
+import { getExternalPluginAdapter } from '../plugins/external-adapter';
+import { getExternalPluginRegistration } from '../plugins/external-registration';
+import { AssistantPluginError } from '../plugins/errors';
+import type { AssistantPluginActionExecutionInput } from '../plugins/types';
+
+let computerProviders: ComputerProviderRegistry | undefined;
+let computerProviderCompositionKey: string | undefined;
+let desktopOperatorProvider: DesktopOperatorComputerProvider | undefined;
+const NATIVE_BROWSER_BUNDLE_IDS: Record<ComputerBrowserProduct, string> = {
+  chrome: 'com.google.Chrome',
+  vivaldi: 'com.vivaldi.Vivaldi',
+};
+function currentDesktopOperatorRegistration(controllerHome: string) {
+  return getExternalPluginRegistration(controllerHome, DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID);
+}
+
+function computerCompositionKey(controllerHome: string): string {
+  const registration = currentDesktopOperatorRegistration(controllerHome);
+  const fingerprint = registration
+    ? `${registration.revision}:${registration.registrationFingerprint}:${registration.enabled ? 'enabled' : 'disabled'}`
+    : 'desktop_operator:unregistered';
+  return `${controllerHome}:${currentComputerPlatform()}:${fingerprint}`;
+}
+
+function ensureComputerComposition(controllerHome: string = resolveControllerHome()): ComputerProviderRegistry {
+  const compositionKey = computerCompositionKey(controllerHome);
+  if (computerProviders && computerProviderCompositionKey === compositionKey) return computerProviders;
+
+  computerProviders?.dispose();
+  const next = new ComputerProviderRegistry();
+  if (currentComputerPlatform() === 'darwin') {
+    const registration = currentDesktopOperatorRegistration(controllerHome);
+    desktopOperatorProvider = createDesktopOperatorComputerProvider({
+      lookupRegistration: (providerPluginId) => {
+        if (providerPluginId !== DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID || !registration) return undefined;
+        return computerProviderRegistrationSnapshot(registration);
+      },
+    });
+    next.register(desktopOperatorProvider);
+  }
+  computerProviders = next;
+  computerProviderCompositionKey = compositionKey;
+  return next;
+}
+
+async function executeComputerProviderRequest(
+  request: ComputerRuntimeProviderExecutionRequest,
+  timeoutMs: number,
+  controllerHome: string,
+): Promise<Record<string, unknown>> {
+  const providers = ensureComputerComposition(controllerHome);
+  try {
+    return await providers.execute(request, timeoutMs);
+  } catch (error) {
+    if (error instanceof ComputerProviderError) {
+      throw new AssistantPluginError(error.code, error.detailMessage, {
+        retryable: error.retryable,
+        effectOutcome: error.effectOutcome,
+        details: error.details,
+      });
+    }
+    throw error;
+  }
+}
+
+export async function executeRuntimeComputer(
+  request: ComputerRuntimeExecutionRequest,
+  timeoutMs: number,
+  controllerHome: string = resolveControllerHome(),
+): Promise<Record<string, unknown>> {
+  return await executeComputerProviderRequest(request, timeoutMs, controllerHome);
+}
+
+export interface RuntimeComputerConsoleUnlockAuthorization {
+  kind: 'explicit_single_use';
+  confirmed: true;
+  invocationId: string;
+}
+
+/**
+ * Protected Computer path. The caller must obtain explicit authorization for either
+ * provider-local credential preparation or one handle-bound unlock attempt. Raw console
+ * credential material never enters Runtime, generic Plugin actions, Jobs, or receipts.
+ */
+export async function executeRuntimeComputerConsoleUnlock(
+  request: ComputerConsoleUnlockCommandRequest,
+  authorization: RuntimeComputerConsoleUnlockAuthorization,
+  timeoutMs: number,
+  controllerHome: string = resolveControllerHome(),
+): Promise<Record<string, unknown>> {
+  if (request.capability !== COMPUTER_CONSOLE_UNLOCK_CAPABILITY
+    || !['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
+    || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(authorization.invocationId)) {
+    throw new AssistantPluginError('COMPUTER_CONSOLE_UNLOCK_EXPLICIT_AUTHORIZATION_REQUIRED', 'Protected console unlock requires one explicit single-use authorization bound to this invocation.', { retryable: false });
+  }
+  if (request.action === 'unlock_console'
+    && !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(request.credentialHandle)) {
+    throw new AssistantPluginError('COMPUTER_CONSOLE_UNLOCK_CREDENTIAL_HANDLE_REQUIRED', 'Protected console unlock requires one provider-local opaque credential handle.', { retryable: false });
+  }
+  const providerRequest: ComputerConsoleUnlockProviderRequest = { ...request, authorization };
+  return await executeComputerProviderRequest(providerRequest, timeoutMs, controllerHome);
+}
+
+export async function executeRuntimeComputerBrowserAutomation(
+  request: ComputerBrowserAutomationRequest,
+  timeoutMs: number,
+  controllerHome: string = resolveControllerHome(),
+): Promise<Record<string, unknown>> {
+  ensureComputerComposition(controllerHome);
+  if (!desktopOperatorProvider) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_COMPATIBILITY_PROVIDER_UNAVAILABLE',
+      'Native Browser compatibility requires the macOS Desktop Operator provider.',
+      { retryable: true, details: { providerId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID } },
+    );
+  }
+  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,
+): Promise<void> {
+  const platform = currentComputerPlatform();
+  if (platform !== 'darwin') {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_FOREGROUND_ACTIVATOR_UNSUPPORTED_PLATFORM',
+      `Native browser foreground activation is unavailable on ${platform} until a platform Computer provider is registered.`,
+      { retryable: false, details: { browserProduct: product, platform } },
+    );
+  }
+  const desktopOperator = getExternalPluginAdapter(input.controllerHome, DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID);
+  if (!desktopOperator) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_FOREGROUND_ACTIVATOR_UNAVAILABLE',
+      'Native browser foreground activation requires an available Computer application provider.',
+      { retryable: true, details: { browserProduct: product, providerId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID } },
+    );
+  }
+  await desktopOperator.executeAction({
+    controllerHome: input.controllerHome,
+    repoId: input.repoId,
+    repoRoot: input.repoRoot,
+    pluginId: DESKTOP_OPERATOR_PROVIDER_PLUGIN_ID,
+    actionId: 'desktop_session_open',
+    requestId: `${input.requestId}:native-browser-foreground:${product}`,
+    args: { bundle_id: NATIVE_BROWSER_BUNDLE_IDS[product], launch: false, activate: true },
+    origin: input.origin,
+    jobId: input.jobId,
+    timeoutMs: input.timeoutMs,
+    signal: input.signal,
+    deadlineAtMs: input.deadlineAtMs,
+  });
+}
+
+export function runtimeComputerProviderSnapshot(controllerHome: string = resolveControllerHome()): Array<{ providerId: string; capabilities: string[] }> {
+  return ensureComputerComposition(controllerHome).snapshot();
+}
+
+export function disposeRuntimeComputerComposition(): void {
+  computerProviders?.dispose();
+  computerProviders = undefined;
+  computerProviderCompositionKey = undefined;
+  desktopOperatorProvider = undefined;
+}

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

@@ -0,0 +1,16 @@
+import type { ComputerInteractionTargetAuthorityPort, ComputerInteractionTargetCleanupReport } from '../../../packages/plugin-runtime/computer/target-authority';
+import { createComputerInteractionTargetAuthority } from '../../../adapters/computer/interaction-target-authority';
+import { createRuntimeComputerTargetPersistence } from './computer-target-persistence';
+
+const computerInteractionTargetAuthority = createComputerInteractionTargetAuthority(createRuntimeComputerTargetPersistence());
+
+export function runtimeComputerInteractionTargetAuthority(): ComputerInteractionTargetAuthorityPort {
+  return computerInteractionTargetAuthority;
+}
+
+export function cleanupRuntimeComputerInteractionTargets(
+  controllerHome: string,
+  options?: { nowMs?: number; ttlMs?: number; maxTombstones?: number; maxRemovals?: number },
+): Promise<ComputerInteractionTargetCleanupReport> {
+  return computerInteractionTargetAuthority.cleanupTombstones(controllerHome, options);
+}

package/src/runtime/root/computer-target-persistence.ts

@@ -0,0 +1,39 @@
+import type { ComputerTargetPersistencePort } from '../../../packages/plugin-runtime/computer/target-persistence';
+import { CONTROLLER_SCOPE_REPO_ID } from '../../cli/repositories/controller-home';
+import { withControllerLockAsync } from '../../cli/repositories/locks';
+import {
+  deleteControlPlaneRecord,
+  deleteControlPlaneRecordWithinTransaction,
+  listAllControlPlaneRecords,
+  listAllControlPlaneRecordsWithinTransaction,
+  listControlPlaneRecords,
+  listControlPlaneRecordsWithinTransaction,
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  withControlPlaneTransaction,
+  writeControlPlaneRecord,
+  writeControlPlaneRecordWithinTransaction,
+} from '../control-plane/persistence/sqlite-store';
+
+export function createRuntimeComputerTargetPersistence(): ComputerTargetPersistencePort {
+  return {
+    read: (controllerHome, namespace, scope, key) => readControlPlaneRecord(controllerHome, namespace, scope, key),
+    list: (controllerHome, input) => listControlPlaneRecords(controllerHome, input),
+    listAll: (controllerHome, input) => listAllControlPlaneRecords(controllerHome, input),
+    write: (controllerHome, input) => writeControlPlaneRecord(controllerHome, input),
+    delete: (controllerHome, input) => deleteControlPlaneRecord(controllerHome, input),
+    transaction: (controllerHome, operation) => withControlPlaneTransaction(controllerHome, (database) => operation({
+      read: (namespace, scope, key) => readControlPlaneRecordWithinTransaction(database, namespace, scope, key),
+      list: (input) => listControlPlaneRecordsWithinTransaction(database, input),
+      listAll: (input) => listAllControlPlaneRecordsWithinTransaction(database, input),
+      write: (input) => writeControlPlaneRecordWithinTransaction(database, input),
+      delete: (input) => deleteControlPlaneRecordWithinTransaction(database, input),
+    })),
+    withTargetLock: (controllerHome, targetId, operation) => withControllerLockAsync(
+      controllerHome,
+      { scope: 'task', repoId: CONTROLLER_SCOPE_REPO_ID, taskId: `computer-target-${targetId}` },
+      `computer-target:${targetId}`,
+      operation,
+    ),
+  };
+}

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,
+  };
+}