@moretea-labs/forge 1.7.2 → 1.8.1

package/adapters/mcp/runtime-gateway/work-controller-operations.ts

@@ -0,0 +1,257 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import type { RepositoryRecord } from '../../../src/cli/repositories/types';
+import { result } from './result-adapter';
+import { buildFacadeResult, getHandoffItem } from '../../../src/runtime/control-plane/facade';
+import { getWorkContract } from '../../../packages/kernel/work/api/index';
+import { launchSuperController } from '../../../src/runtime/control-plane/launcher/thin-launcher';
+import {
+  upsertChatgptControllerRoundTransportBinding,
+} from '../../../src/runtime/root/controller-round-composition';
+import { touchSchedulerWakeSignal } from '../../../src/runtime/control-plane/global-scheduler/wake-signal';
+import {
+  bindControllerSessionBinding,
+  controllerRoundBlockerClass,
+  getControllerRoundRelay,
+  releaseObservedControllerSession,
+} from '../../../packages/kernel/controller/api/index';
+import { authenticatedFacadeControllerIdentity, bindFacadeControllerOwnership } from './controller-authority-adapter';
+import {
+  bindCurrentWorkflowSupervisorConversationForWork,
+  bindWorkflowSupervisorConversationForWork,
+  getWorkflowSupervisorConversationBindingForWork,
+} from '../../../src/runtime/root/workflow-supervisor-composition';
+import { reconcileControllerProgression } from '../../../src/runtime/root/controller-progression-composition';
+
+const RH_WORK_CONTROLLER_OPERATIONS = new Set(['launcher_start']);
+
+export function isRhWorkControllerOperation(operation: string): boolean {
+  return RH_WORK_CONTROLLER_OPERATIONS.has(operation);
+}
+
+export async function callRhWorkControllerOperation(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: RepositoryRecord,
+  operation: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (operation !== 'launcher_start') return undefined;
+  const store = { controllerHome: ctx.controllerHome, repoId: repository.repoId };
+  try {
+    const controllerType = String(args.controller_type ?? 'codex');
+    if (!['chatgpt', 'codex', 'grok', 'claude'].includes(controllerType)) throw new Error('CONTROLLER_TYPE_INVALID');
+    const workId = String(args.work_id ?? '').trim();
+    const launchArgs = Array.isArray(args.launch_args) ? args.launch_args.map(String) : [];
+
+    if (controllerType === 'chatgpt') {
+      const work = getWorkContract(store, workId);
+      if (!work) throw new Error(`WORK_NOT_FOUND: ${workId}`);
+      const launchRequestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+      if (!launchRequestId) throw new Error('LAUNCHER_START_REQUEST_ID_REQUIRED');
+
+      const explicitConversationUrl = typeof args.conversation_url === 'string' && args.conversation_url.trim()
+        ? args.conversation_url.trim()
+        : undefined;
+      const enrollCurrentConversation = args.enroll_current_conversation === true;
+      if (enrollCurrentConversation && explicitConversationUrl) {
+        throw new Error('CURRENT_CONVERSATION_ENROLLMENT_EXPLICIT_URL_CONFLICT');
+      }
+
+      const handoffId = typeof args.handoff_id === 'string' ? args.handoff_id.trim() : '';
+      const handoff = handoffId ? getHandoffItem(store, handoffId) : undefined;
+      const valueForFlag = (flag: string): string | undefined => {
+        const index = launchArgs.indexOf(flag);
+        if (index < 0) return undefined;
+        const value = launchArgs[index + 1];
+        if (!value || value.startsWith('--')) throw new Error(`CHATGPT_LAUNCH_ARG_VALUE_REQUIRED: ${flag}`);
+        return value;
+      };
+      const supportedFlags = new Set(['--model', '--reasoning', '--tab-policy', '--timeout-ms']);
+      for (let index = 0; index < launchArgs.length; index += 2) {
+        const flag = launchArgs[index];
+        if (!flag || !supportedFlags.has(flag)) throw new Error(`CHATGPT_LAUNCH_ARG_UNSUPPORTED: ${flag ?? ''}`);
+        if (!launchArgs[index + 1] || launchArgs[index + 1]!.startsWith('--')) {
+          throw new Error(`CHATGPT_LAUNCH_ARG_VALUE_REQUIRED: ${flag}`);
+        }
+      }
+
+      const reasoning = valueForFlag('--reasoning') ?? 'high';
+      if (!['medium', 'high', 'xhigh'].includes(reasoning)) throw new Error(`CHATGPT_LAUNCH_REASONING_INVALID: ${reasoning}`);
+      const tabPolicy = valueForFlag('--tab-policy') ?? 'auto';
+      if (!['auto', 'reuse', 'new'].includes(tabPolicy)) throw new Error(`CHATGPT_LAUNCH_TAB_POLICY_INVALID: ${tabPolicy}`);
+      const timeoutValue = valueForFlag('--timeout-ms');
+      const timeoutMs = timeoutValue === undefined ? undefined : Number(timeoutValue);
+      if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        throw new Error(`CHATGPT_LAUNCH_TIMEOUT_INVALID: ${timeoutValue}`);
+      }
+      const continuationPrompt = typeof args.continuation_prompt === 'string' ? args.continuation_prompt.trim() : '';
+      const initialContinuationPrompt = [
+        handoff ? `Handoff: ${handoff.summary}\nNext: ${handoff.recommendedContinuationPrompt ?? handoff.recommendedPrompt}` : '',
+        continuationPrompt ? `Continuation: ${continuationPrompt}` : '',
+      ].filter(Boolean).join('\n') || undefined;
+
+      const requestedTransportConversation = args.transport_conversation === 'fresh'
+        ? 'fresh'
+        : args.transport_conversation === 'bound' ? 'bound' : undefined;
+      if (enrollCurrentConversation && requestedTransportConversation === 'fresh') {
+        throw new Error('CURRENT_CONVERSATION_ENROLLMENT_FRESH_TRANSPORT_CONFLICT');
+      }
+
+      // All request/identity and clearly terminal round validation happens before
+      // any conversation binding is persisted. Frozen compatibility must be
+      // transport-only: an invalid launcher request is a zero-write request.
+      const identity = authenticatedFacadeControllerIdentity(ctx, args);
+      const existingRound = getControllerRoundRelay(store, workId);
+      if (existingRound?.status === 'failed') {
+        throw new Error(existingRound.lastError ?? `CONTROLLER_RELAY_FAILED:${workId}`);
+      }
+      if (existingRound?.status === 'blocked'
+        && controllerRoundBlockerClass(existingRound) !== 'provider_dispatch_outcome_unknown') {
+        throw new Error(`CONTROLLER_RELAY_LAUNCH_BLOCKED:${existingRound.blockedReason ?? existingRound.relayScopeId}`);
+      }
+      if (existingRound && ['pending_release', 'goal_complete', 'handed_off'].includes(existingRound.status)) {
+        throw new Error(`CONTROLLER_RELAY_NOT_PROGRESSABLE:${existingRound.status}`);
+      }
+
+      let conversationBinding = getWorkflowSupervisorConversationBindingForWork(store, workId);
+      if (requestedTransportConversation === 'fresh' && conversationBinding) {
+        throw new Error('CHATGPT_FRESH_CONVERSATION_EXISTING_BINDING_CONFLICT');
+      }
+      if (enrollCurrentConversation) {
+        const currentBinding = await bindCurrentWorkflowSupervisorConversationForWork(store, workId);
+        if (currentBinding.status !== 'bound') {
+          throw new Error(currentBinding.reason ?? `CURRENT_CONVERSATION_ENROLLMENT_${currentBinding.status.toUpperCase()}`);
+        }
+        conversationBinding = currentBinding.binding;
+      } else if (explicitConversationUrl) {
+        if (args.transport_conversation === 'fresh') {
+          throw new Error('CHATGPT_FRESH_CONVERSATION_EXPLICIT_URL_CONFLICT');
+        }
+        conversationBinding = bindWorkflowSupervisorConversationForWork(store, {
+          workId,
+          conversationUrl: explicitConversationUrl,
+          localAlias: 'Forge autonomous execution',
+        });
+      }
+
+      const transportConversation = requestedTransportConversation
+        ?? (conversationBinding ? 'bound' : 'fresh');
+      if (transportConversation === 'bound' && !conversationBinding) {
+        throw new Error('WORKFLOW_SUPERVISOR_BOUND_CONVERSATION_REQUIRED');
+      }
+
+      const occurrenceId = `launcher_start:${work.workId}:${launchRequestId}`;
+      const relayScopeId = work.requirementId ? `requirement:${work.requirementId}` : `goal:${work.workId}`;
+
+      let launchOwner;
+      if (!existingRound) {
+        launchOwner = bindFacadeControllerOwnership(ctx, store, workId, identity, {
+          allowClaimIfMissing: true,
+          leaseMs: 60_000,
+        });
+        const controllerBinding = upsertChatgptControllerRoundTransportBinding(store, {
+          workId,
+          sessionId: launchOwner.sessionId,
+          browserSessionId: undefined,
+          conversationUrl: transportConversation === 'bound' ? conversationBinding?.conversationUrl : undefined,
+          model: valueForFlag('--model') ?? 'gpt-5.6',
+          reasoning: reasoning as 'medium' | 'high' | 'xhigh',
+          tabPolicy: tabPolicy as 'auto' | 'reuse' | 'new',
+          timeoutMs,
+          transportConversation,
+          continuationPrompt: initialContinuationPrompt,
+          authorizationGrantRefs: conversationBinding?.authorizationGrantRefs ?? [],
+        });
+        bindControllerSessionBinding(store, {
+          workId,
+          sessionId: launchOwner.sessionId,
+          binding: controllerBinding.binding,
+        });
+      }
+
+      let progression;
+      try {
+        progression = await reconcileControllerProgression(
+          {
+            controllerHome: ctx.controllerHome,
+            repoId: repository.repoId,
+            repoRoot: repository.canonicalRoot,
+          },
+          {
+            workId,
+            occurrenceId,
+            relayScopeId,
+            continuationHint: initialContinuationPrompt,
+            scheduleName: 'launcher-start',
+          },
+        );
+      } finally {
+        if (launchOwner) {
+          const released = releaseObservedControllerSession(store, {
+            workId,
+            actor: `launcher-start-retain:${workId}`,
+            owner: launchOwner,
+          });
+          if (!released.allowed) {
+            throw new Error(`CONTROLLER_LAUNCH_RESUME_IDENTITY_RELEASE_FAILED:${workId}:${released.reason}`);
+          }
+        }
+      }
+
+      touchSchedulerWakeSignal(ctx.controllerHome, `controller-round-ready:${workId}`);
+      if (progression.status === 'rejected') {
+        throw new Error(progression.reason ?? 'CHATGPT_CONTINUATION_LAUNCH_REJECTED');
+      }
+      if (progression.status === 'terminal_or_missing') {
+        throw new Error(progression.reason);
+      }
+      if (progression.status === 'retained_session_missing' || progression.status === 'human_controller') {
+        throw new Error(progression.reason);
+      }
+
+      return result(buildFacadeResult({
+        summary: progression.status === 'chatgpt_enrolled'
+          ? 'ChatGPT continuation enrolled with Workflow Supervisor effect authority.'
+          : progression.status === 'chatgpt_not_enrolled'
+            ? 'ChatGPT continuation is durably queued; Workflow Supervisor enrollment will retry without consuming provider failure budget.'
+            : `ChatGPT continuation is waiting in canonical progression state: ${progression.status}.`,
+        data: {
+          workId,
+          continuationQueued: true,
+          continuationDispatched: false,
+          relayScopeId: 'relayScopeId' in progression ? progression.relayScopeId : relayScopeId,
+          transportConversation,
+          progressionStatus: progression.status,
+          ...(progression.status === 'chatgpt_enrolled' || progression.status === 'chatgpt_not_enrolled'
+            ? { supervisorEnrollment: progression.supervisorEnrollment }
+            : {}),
+        },
+      }) as unknown as Record<string, unknown>);
+    }
+
+    const launched = await launchSuperController({ work: store, handoff: store }, {
+      controllerType: controllerType as 'codex' | 'grok' | 'claude',
+      executable: typeof args.executable === 'string' && args.executable.trim() ? args.executable.trim() : undefined,
+      args: launchArgs,
+      workId,
+      launchReservationMs: typeof args.launch_reservation_ms === 'number'
+        ? args.launch_reservation_ms
+        : typeof args.lease_ms === 'number' ? args.lease_ms : undefined,
+      handoffId: typeof args.handoff_id === 'string' ? args.handoff_id : undefined,
+      browserSessionId: typeof args.browser_session_id === 'string' ? args.browser_session_id : undefined,
+      conversationUrl: typeof args.conversation_url === 'string' ? args.conversation_url : undefined,
+      continuationPrompt: typeof args.continuation_prompt === 'string' ? args.continuation_prompt : undefined,
+      cwd: repository.canonicalRoot,
+    });
+    return result(buildFacadeResult({
+      summary: `Thin Launcher started ${launched.controllerType}.`,
+      data: { pid: launched.pid, executable: launched.executable, workId, reservationId: launched.reservationId },
+    }) as unknown as Record<string, unknown>);
+  } catch (error) {
+    return result(buildFacadeResult({
+      status: 'blocked',
+      summary: error instanceof Error ? error.message : 'Launcher failed.',
+      data: {},
+    }) as unknown as Record<string, unknown>, true);
+  }
+}

package/adapters/mcp/runtime-gateway/work-detail-projection.ts

@@ -0,0 +1,60 @@
+import {
+  WORK_PHASES,
+  type WorkContract,
+} from '../../../packages/kernel/work/api/index';
+
+const MAX_DETAIL_VERIFICATIONS = 50;
+const MAX_DETAIL_CHECKS = 30;
+const MAX_DETAIL_EVIDENCE_REFS = 100;
+const MAX_PHASE_EVIDENCE_REFS = 20;
+
+/**
+ * Read-only bounded projection of mechanical Work execution/evidence facts.
+ * This adapter never mutates Work or derives semantic state/completion.
+ */
+export function projectWorkExecutionEvidence(work: WorkContract) {
+  const maxEvidenceRefs = Math.max(0, Math.min(work.evidencePolicy.maxEvidenceRefs, MAX_DETAIL_EVIDENCE_REFS));
+  return {
+    dispatchState: work.dispatchState,
+    evidenceState: work.evidenceState,
+    phase: work.phase,
+    workKind: work.workKind,
+    ...(work.completionOutcome ? { completionOutcome: work.completionOutcome } : {}),
+    checks: work.checks.slice(0, MAX_DETAIL_CHECKS),
+    phaseEvidence: WORK_PHASES.map((phase) => ({
+      phase,
+      state: work.phaseEvidence[phase].state,
+      source: work.phaseEvidence[phase].source,
+      summary: work.phaseEvidence[phase].summary,
+      evidenceRefs: work.phaseEvidence[phase].evidenceRefs.slice(0, MAX_PHASE_EVIDENCE_REFS),
+      recordedAt: work.phaseEvidence[phase].recordedAt,
+      ...(work.phaseEvidence[phase].receiptId ? { receiptId: work.phaseEvidence[phase].receiptId } : {}),
+    })),
+    evidenceRefs: maxEvidenceRefs === 0 ? [] : work.evidenceRefs.slice(-maxEvidenceRefs),
+    verifications: work.checkRefs.slice(-MAX_DETAIL_VERIFICATIONS).map((verification) => ({
+      checkId: verification.checkId,
+      outcome: verification.outcome,
+      summary: verification.summary,
+      recordedAt: verification.recordedAt,
+      ...(verification.sourceRevision ? { sourceRevision: verification.sourceRevision } : {}),
+      ...(verification.startedAt ? { startedAt: verification.startedAt } : {}),
+      ...(verification.completedAt ? { completedAt: verification.completedAt } : {}),
+      ...(verification.staleReason ? { staleReason: verification.staleReason } : {}),
+      ...(verification.evidenceRef ? { evidenceRef: verification.evidenceRef } : {}),
+      ...(verification.receipt ? {
+        receipt: {
+          receiptId: verification.receipt.receiptId,
+          processId: verification.receipt.processId,
+          status: verification.receipt.status,
+          runtimeStatus: verification.receipt.runtimeStatus,
+          ok: verification.receipt.ok,
+          timedOut: verification.receipt.timedOut,
+          cancelled: verification.receipt.cancelled,
+          ...(verification.receipt.reusedExecution !== undefined ? { reusedExecution: verification.receipt.reusedExecution } : {}),
+          startedAt: verification.receipt.startedAt,
+          finishedAt: verification.receipt.finishedAt,
+        },
+      } : {}),
+    })),
+  };
+}

package/adapters/mcp/runtime-gateway/work-input-wire-migration.ts

@@ -0,0 +1,246 @@
+import { isDeepStrictEqual } from 'node:util';
+import { AUTOMATION_RECEIPT_CAPABILITY_PREFIX } from './automation-receipt-adapter';
+
+export type RhWorkInputWireMigrationResult =
+  | {
+      ok: true;
+      args: Record<string, unknown>;
+      operation: string;
+      scheduleIdOverride?: string;
+      requirementOperationArgs?: Record<string, unknown>;
+    }
+  | { ok: false; summary: string; data: Record<string, unknown> };
+
+function failure(summary: string, data: Record<string, unknown> = {}): RhWorkInputWireMigrationResult {
+  return { ok: false, summary, data };
+}
+
+const FROZEN_SEMANTIC_V1_PREFIX = 'semantic.v1:';
+const FROZEN_CURRENT_CONVERSATION_ENROLLMENT = 'controller.current_conversation.enroll';
+const FROZEN_SEMANTIC_V1_MAX_BYTES = 8 * 1024;
+const FROZEN_FORBIDDEN_OBJECT_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+const FROZEN_COMMON_FIELDS = ['repo_id', 'checkout_id', 'request_id', 'detail_level'] as const;
+const FROZEN_SEMANTIC_V1_FIELDS: Record<string, ReadonlySet<string>> = {
+  work_get: new Set([...FROZEN_COMMON_FIELDS, 'operation', 'work_id']),
+  work_revise: new Set([
+    ...FROZEN_COMMON_FIELDS,
+    'operation',
+    'work_id',
+    'expected_revision',
+    'objective',
+    'work_state',
+    'requirement_revision',
+    'plan_revision',
+    'work_result_refs',
+  ]),
+  work_complete: new Set([
+    ...FROZEN_COMMON_FIELDS,
+    'operation',
+    'work_id',
+    'expected_revision',
+    'objective',
+    'requirement_revision',
+    'plan_revision',
+    'work_result_refs',
+  ]),
+  requirement_get: new Set([...FROZEN_COMMON_FIELDS, 'operation', 'requirement_id']),
+  requirement_revise: new Set([
+    ...FROZEN_COMMON_FIELDS,
+    'operation',
+    'requirement_id',
+    'expected_revision',
+    'requirement_title',
+    'requirement_outcome',
+    'requirement_acceptance_criteria',
+    'requirement_delivery_references',
+    'requirement_state',
+  ]),
+  plan_get: new Set([...FROZEN_COMMON_FIELDS, 'operation', 'plan_id']),
+  plan_revise: new Set([
+    ...FROZEN_COMMON_FIELDS,
+    'operation',
+    'plan_id',
+    'expected_revision',
+    'superseded_by',
+    'requirement_revision',
+    'source_revision',
+    'objective',
+    'non_goals',
+    'assumptions',
+    'resolved_decisions',
+    'stop_conditions',
+    'replan_conditions',
+    'integration_strategy',
+    'plan_items',
+  ]),
+  plan_list: new Set([...FROZEN_COMMON_FIELDS, 'operation', 'limit']),
+};
+const FROZEN_CURRENT_CONVERSATION_FIELDS = new Set([
+  'operation',
+  'capability_id',
+  'repo_id',
+  'checkout_id',
+  'request_id',
+  'detail_level',
+  'work_id',
+  'handoff_id',
+  'launch_args',
+  'launch_reservation_ms',
+  'lease_ms',
+  'continuation_prompt',
+  'controller_type',
+  'transport_conversation',
+]);
+
+function unsafeObjectKey(value: unknown): string | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const nested = unsafeObjectKey(item);
+      if (nested) return nested;
+    }
+    return undefined;
+  }
+  for (const [key, nestedValue] of Object.entries(value as Record<string, unknown>)) {
+    if (FROZEN_FORBIDDEN_OBJECT_KEYS.has(key)) return key;
+    const nested = unsafeObjectKey(nestedValue);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+function parseFrozenSemanticV1(capabilityId: string):
+  | { ok: true; value: Record<string, unknown> }
+  | { ok: false; summary: string; data: Record<string, unknown> } {
+  const encoded = capabilityId.slice(FROZEN_SEMANTIC_V1_PREFIX.length);
+  if (Buffer.byteLength(encoded, 'utf8') > FROZEN_SEMANTIC_V1_MAX_BYTES) {
+    return { ok: false, summary: 'FROZEN_MCP_SEMANTIC_V1_TOO_LARGE', data: { maxBytes: FROZEN_SEMANTIC_V1_MAX_BYTES } };
+  }
+  try {
+    const parsed = JSON.parse(encoded) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, summary: 'FROZEN_MCP_SEMANTIC_V1_INVALID', data: {} };
+    }
+    const unsafeKey = unsafeObjectKey(parsed);
+    if (unsafeKey) return { ok: false, summary: 'FROZEN_MCP_SEMANTIC_V1_UNSAFE_KEY', data: { key: unsafeKey } };
+    return { ok: true, value: parsed as Record<string, unknown> };
+  } catch {
+    return { ok: false, summary: 'FROZEN_MCP_SEMANTIC_V1_INVALID', data: {} };
+  }
+}
+
+function unsupportedInputField(input: Record<string, unknown>, allowed: ReadonlySet<string>): string | undefined {
+  return Object.keys(input).find((key) => !allowed.has(key));
+}
+
+function translateFrozenSemanticV1(
+  outer: Record<string, unknown>,
+  semantic: Record<string, unknown>,
+): RhWorkInputWireMigrationResult {
+  const frozenOperation = typeof semantic.operation === 'string' ? semantic.operation.trim() : '';
+  const allowed = FROZEN_SEMANTIC_V1_FIELDS[frozenOperation];
+  if (!allowed) return failure('FROZEN_MCP_SEMANTIC_V1_OPERATION_UNSUPPORTED', { operation: frozenOperation });
+  const operation = frozenOperation === 'work_get'
+    ? 'get'
+    : frozenOperation === 'work_revise'
+      ? 'revise'
+      : frozenOperation === 'work_complete'
+        ? 'complete'
+        : frozenOperation;
+
+  const semanticUnsupported = unsupportedInputField(semantic, allowed);
+  if (semanticUnsupported) {
+    return failure('FROZEN_MCP_SEMANTIC_V1_FIELD_UNSUPPORTED', { operation: frozenOperation, field: semanticUnsupported });
+  }
+  const outerAllowed = new Set([...allowed, 'capability_id']);
+  const outerUnsupported = unsupportedInputField(outer, outerAllowed);
+  if (outerUnsupported) {
+    return failure('FROZEN_MCP_SEMANTIC_V1_FIELD_UNSUPPORTED', { operation: frozenOperation, field: outerUnsupported });
+  }
+
+  for (const field of allowed) {
+    if (field === 'operation') continue;
+    if (Object.prototype.hasOwnProperty.call(semantic, field)
+      && Object.prototype.hasOwnProperty.call(outer, field)
+      && !isDeepStrictEqual(semantic[field], outer[field])) {
+      return failure('FROZEN_MCP_SEMANTIC_V1_FIELD_CONFLICT', { operation: frozenOperation, field });
+    }
+  }
+
+  const translated: Record<string, unknown> = { operation };
+  for (const field of allowed) {
+    if (field === 'operation') continue;
+    if (Object.prototype.hasOwnProperty.call(semantic, field)) translated[field] = semantic[field];
+    else if (Object.prototype.hasOwnProperty.call(outer, field)) translated[field] = outer[field];
+  }
+  return { ok: true, args: translated, operation };
+}
+
+/**
+ * Versioned wire bridge for MCP clients whose rh_work schema was frozen before
+ * the Thin Forge cutover. The bridge owns no lifecycle or persistence: it only
+ * validates and translates two bounded historical carriers into current
+ * semantic/controller operations, which remain the sole mutation authorities.
+ *
+ * Removal condition: the minimum supported MCP client contract no longer
+ * advertises these pre-Thin carriers and release reconnect canaries prove there
+ * are no supported frozen-session consumers.
+ */
+export function normalizeRhWorkInputWireMigration(input: Record<string, unknown>): RhWorkInputWireMigrationResult {
+  const unsafeKey = unsafeObjectKey(input);
+  if (unsafeKey) return failure('FROZEN_MCP_INPUT_UNSAFE_KEY', { key: unsafeKey });
+
+  const args = { ...input };
+  const requestedOperation = String(args.operation ?? 'start');
+  const capabilityId = typeof args.capability_id === 'string' ? args.capability_id.trim() : '';
+
+  if (capabilityId === FROZEN_CURRENT_CONVERSATION_ENROLLMENT) {
+    const unsupported = unsupportedInputField(args, FROZEN_CURRENT_CONVERSATION_FIELDS);
+    if (unsupported) return failure('FROZEN_MCP_CURRENT_CONVERSATION_FIELD_UNSUPPORTED', { field: unsupported });
+    if (args.controller_type !== undefined && args.controller_type !== 'chatgpt') {
+      return failure('FROZEN_MCP_CURRENT_CONVERSATION_FIELD_CONFLICT', { field: 'controller_type' });
+    }
+    if (args.transport_conversation !== undefined && args.transport_conversation !== 'bound') {
+      return failure('FROZEN_MCP_CURRENT_CONVERSATION_FIELD_CONFLICT', { field: 'transport_conversation' });
+    }
+    const translated: Record<string, unknown> = {
+      ...args,
+      operation: 'launcher_start',
+      controller_type: 'chatgpt',
+      transport_conversation: 'bound',
+      enroll_current_conversation: true,
+    };
+    delete translated.capability_id;
+    return { ok: true, args: translated, operation: 'launcher_start' };
+  }
+
+  if (capabilityId.startsWith(FROZEN_SEMANTIC_V1_PREFIX)) {
+    const parsed = parseFrozenSemanticV1(capabilityId);
+    if (!parsed.ok) return failure(parsed.summary, parsed.data);
+    return translateFrozenSemanticV1(args, parsed.value);
+  }
+
+  if (capabilityId.startsWith(AUTOMATION_RECEIPT_CAPABILITY_PREFIX)) {
+    // Frozen clients attach ordinary repository context and a reason. These are
+    // transport annotations, never receipt/task/effect authority. Strip them;
+    // the canonical Supervisor derives all causal identity from its own journal.
+    const allowed = new Set(['operation', 'capability_id', 'repo_id', 'checkout_id', 'reason']);
+    const unsupported = unsupportedInputField(args, allowed);
+    if (unsupported) return failure('FROZEN_MCP_AUTOMATION_RECEIPT_FIELD_UNSUPPORTED', { field: unsupported });
+    if (requestedOperation !== 'repair') return failure('FROZEN_MCP_AUTOMATION_RECEIPT_OPERATION_INVALID', { operation: requestedOperation });
+    for (const field of ['repo_id', 'checkout_id', 'reason']) {
+      if (args[field] !== undefined && (typeof args[field] !== 'string' || (args[field] as string).length > 2_000)) {
+        return failure('FROZEN_MCP_AUTOMATION_RECEIPT_FIELD_INVALID', { field });
+      }
+    }
+    return { ok: true, args: { operation: 'repair', capability_id: capabilityId }, operation: 'repair' };
+  }
+
+  if (capabilityId.includes(':')) {
+    return failure('FROZEN_MCP_LIFECYCLE_REMOVED: only bounded semantic.v1 and current-conversation enrollment carriers remain supported.', {
+      carrier: capabilityId.slice(0, capabilityId.indexOf(':')),
+    });
+  }
+
+  return { ok: true, args, operation: requestedOperation };
+}