@moretea-labs/forge 1.8.0 → 1.8.2

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

@@ -0,0 +1,320 @@
+import { createHash, randomUUID } from 'crypto';
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import {
+  createWorkSemanticContext,
+  getWorkContract,
+  listWorkSemanticRevisionRecords,
+  readWorkContractStore,
+  normalizeWorkObjectiveRelationIds,
+  projectWorkObjectiveGraph,
+  reviseWorkSemanticContext,
+  workSemanticView,
+  semanticWorkState,
+  type WorkContractStoreOptions,
+} from '../../../packages/kernel/work/api/index';
+import { buildFacadeResult, type BuildFacadeResultOptions } from '../../../src/runtime/control-plane/facade';
+import { getPlanContract, currentPlanSemanticRevision, getPlanSemanticRevisionRecord, planSemanticView } from '../../../src/runtime/control-plane/facade/plan-contract-store';
+import { readRequirement, currentRequirementSemanticRevision, getRequirementRevisionRecord, requirementSemanticView } from '../../../src/runtime/control-plane/persistence/requirement-store';
+import { buildWorkContinuationSnapshot } from '../../../src/runtime/control-plane/facade/work-continuation';
+import { result } from './result-adapter';
+import { projectWorkExecutionEvidence } from './work-detail-projection';
+import { readWorkHandle } from '../../../src/runtime/control-plane/execution/work-handle-store';
+import { reconcileSingleTerminalWorkCleanup } from '../../../src/runtime/control-plane/execution/work-terminal-cleanup';
+
+import { existsSync } from 'node:fs';
+import { getWorkflowSupervisorTask, stopWorkflowSupervisorTask } from '../../../supervisor/client';
+import { workflowSupervisorSocketPath } from '../../../supervisor/paths';
+
+async function stopTerminalWorkSupervisor(
+  options: WorkContractStoreOptions,
+  workId: string,
+  state: 'completed' | 'cancelled',
+): Promise<{ status: 'stopped' | 'already_terminal' | 'not_enrolled' | 'pending_reconcile'; reason?: string }> {
+  const controllerHome = options.controllerHome;
+  const repoId = options.repoId?.trim();
+  if (!controllerHome || !repoId || !existsSync(workflowSupervisorSocketPath(controllerHome))) {
+    return { status: 'pending_reconcile', reason: 'Supervisor socket unavailable; native consumer will reconcile terminal Work on restart.' };
+  }
+  const taskId = `forge:${repoId}:work:${workId}`;
+  try {
+    const task = await getWorkflowSupervisorTask(controllerHome, taskId);
+    if (!task) return { status: 'not_enrolled' };
+    // Fail closed: an unrelated Requirement/standalone Goal must never be
+    // stopped by a lower-layer Work transition.
+    if (task.taskId !== taskId || task.completionContract?.work_id !== workId
+      || task.completionContract?.repo_id !== repoId
+      || task.continuationPolicy.kind === 'standalone_supervisor') {
+      return { status: 'pending_reconcile', reason: 'Supervisor task contract is not exact Work-owned.' };
+    }
+    const stopped = await stopWorkflowSupervisorTask(controllerHome, taskId, `Work ${workId} changed to ${state}; its exact Work-owned automatic continuation is closed.`);
+    return { status: stopped.deduplicated ? 'already_terminal' : 'stopped' };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const code = reason.split(':', 1)[0]?.trim();
+    if (code === 'WORKFLOW_SUPERVISOR_TASK_UNKNOWN') return { status: 'not_enrolled' };
+    if (code === 'WORKFLOW_SUPERVISOR_TASK_TERMINAL') return { status: 'already_terminal' };
+    return { status: 'pending_reconcile', reason };
+  }
+}
+
+const RH_WORK_SEMANTIC_OPERATIONS = new Set(['start', 'get', 'revise', 'complete']);
+
+type WorkSemanticFacadeData = Record<string, unknown> & {
+  work?: ReturnType<typeof workSemanticView>;
+  currentWork?: ReturnType<typeof workSemanticView>;
+  revisionHistory?: ReturnType<typeof listWorkSemanticRevisionRecords>;
+};
+
+export function buildWorkSemanticFacadeResult(options: BuildFacadeResultOptions<WorkSemanticFacadeData>) {
+  const facade = buildFacadeResult(options);
+  // These authored projections already have domain limits. Generic diagnostic
+  // clipping corrupts their read/revise round trip (100 refs become 50, and a
+  // valid objective becomes an ellipsis). Keep execution diagnostics bounded.
+  if (options.data.work) facade.data.work = options.data.work;
+  if (options.data.currentWork) facade.data.currentWork = options.data.currentWork;
+  if (options.data.revisionHistory) facade.data.revisionHistory = options.data.revisionHistory;
+  return facade;
+}
+
+/** Resolve semantic version references against existing canonical heads/history. */
+function workBasis(store: WorkContractStoreOptions, x: { requirementId?: string; requirementRevision?: number; planId?: string; planRevision?: number }) {
+  const plan = x.planId ? getPlanContract(store, x.planId) : undefined;
+  if (x.planId && !plan) throw new Error(`WORK_PLAN_NOT_FOUND: ${x.planId}`);
+  if (x.requirementId && plan?.requirementId && x.requirementId !== plan.requirementId) {
+    throw new Error(`WORK_PLAN_REQUIREMENT_MISMATCH: ${x.planId} belongs to ${plan.requirementId}, not ${x.requirementId}`);
+  }
+  const requirementId = x.requirementId || plan?.requirementId;
+  if (x.requirementRevision !== undefined && !requirementId) throw new Error('WORK_REQUIREMENT_ID_REQUIRED_FOR_REVISION');
+  if (x.planRevision !== undefined && !x.planId) throw new Error('WORK_PLAN_ID_REQUIRED_FOR_REVISION');
+  if (requirementId && !store.controllerHome) throw new Error('WORK_REQUIREMENT_STORE_UNAVAILABLE');
+  const requirement = requirementId ? readRequirement({ controllerHome: store.controllerHome! }, requirementId)?.value : undefined;
+  if (requirementId && !requirement) throw new Error(`WORK_REQUIREMENT_NOT_FOUND: ${requirementId}`);
+  for (const [kind, revision] of [['REQUIREMENT', x.requirementRevision], ['PLAN', x.planRevision]] as const) {
+    if (revision !== undefined && (!Number.isInteger(revision) || revision < 1)) throw new Error(`WORK_${kind}_REVISION_INVALID`);
+  }
+  const requirementRevision = requirement ? x.requirementRevision ?? currentRequirementSemanticRevision(requirement) : undefined;
+  const planRevision = plan ? x.planRevision ?? currentPlanSemanticRevision(plan) : undefined;
+  if (requirement && requirementRevision !== currentRequirementSemanticRevision(requirement)
+    && !getRequirementRevisionRecord({ controllerHome: store.controllerHome! }, requirementId!, requirementRevision!)) {
+    throw new Error(`WORK_REQUIREMENT_REVISION_NOT_FOUND: ${requirementId}:r${requirementRevision}`);
+  }
+  if (plan && planRevision !== currentPlanSemanticRevision(plan)
+    && !getPlanSemanticRevisionRecord(store, x.planId!, planRevision!)) {
+    throw new Error(`WORK_PLAN_REVISION_NOT_FOUND: ${x.planId}:r${planRevision}`);
+  }
+  return { requirementId, requirementRevision, planId: x.planId, planRevision };
+}
+
+/** On-demand projection for manual and automated continuation; never adopts a head. */
+function versionBinding(store: WorkContractStoreOptions, work: NonNullable<ReturnType<typeof getWorkContract>>, detail: boolean) {
+  const req = work.requirementId && store.controllerHome
+    ? readRequirement({ controllerHome: store.controllerHome }, work.requirementId)?.value : undefined;
+  const plan = work.planId ? getPlanContract(store, work.planId) : undefined;
+  const reqHead = req ? requirementSemanticView(req) : undefined;
+  const planHead = plan ? planSemanticView(plan) : undefined;
+  const reqAdopted = detail && reqHead && work.requirementRevision !== reqHead.revision
+    ? getRequirementRevisionRecord({ controllerHome: store.controllerHome! }, work.requirementId!, work.requirementRevision!) : undefined;
+  const planAdopted = detail && planHead && work.planRevision !== planHead.revision
+    ? getPlanSemanticRevisionRecord(store, work.planId!, work.planRevision!) : undefined;
+  return {
+    ...(work.requirementId ? { requirement: {
+      id: work.requirementId, adoptedRevision: work.requirementRevision, currentRevision: reqHead?.revision,
+      updateAvailable: Boolean(reqHead && work.requirementRevision !== reqHead.revision),
+      ...(detail ? { current: reqHead, adopted: reqAdopted ?? (work.requirementRevision === reqHead?.revision ? reqHead : undefined) } : {}),
+    } } : {}),
+    ...(work.planId ? { plan: {
+      id: work.planId, adoptedRevision: work.planRevision, currentRevision: planHead?.revision,
+      updateAvailable: Boolean(planHead && work.planRevision !== planHead.revision),
+      ...(detail ? { current: planHead, adopted: planAdopted ?? (work.planRevision === planHead?.revision ? planHead : undefined) } : {}),
+    } } : {}),
+  };
+}
+
+
+export function semanticWorkId(store: WorkContractStoreOptions, args: Record<string, unknown>): string {
+  const explicit = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+  if (explicit) return explicit;
+  const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+  if (requestId) {
+    const scopeKey = store.scopeKey?.trim() || store.repoId?.trim() || 'semantic';
+    const digest = createHash('sha256').update(`${scopeKey}\0${requestId}`).digest('hex').slice(0, 12);
+    return `work-semantic-${digest}`;
+  }
+  return `work-semantic-${randomUUID().slice(0, 12)}`;
+}
+
+function semanticCreateMatches(existing: ReturnType<typeof getWorkContract>, args: Record<string, unknown>, requestId: string): boolean {
+  if (!existing) return false;
+  const objective = String(args.objective ?? '').trim();
+  const requirementId = typeof args.requirement_id === 'string' ? args.requirement_id.trim() : '';
+  const planId = typeof args.plan_id === 'string' ? args.plan_id.trim() : '';
+  const semanticParentWorkId = typeof args.semantic_parent_work_id === 'string' ? args.semantic_parent_work_id.trim() : '';
+  const dependsOnWorkIds = normalizeWorkObjectiveRelationIds(Array.isArray(args.depends_on_work_ids) ? args.depends_on_work_ids.map(String) : []).sort();
+  const existingDependencies = normalizeWorkObjectiveRelationIds(existing.dependsOnWorkIds).sort();
+  return existing.objective === objective
+    && (planId && !requirementId ? true : (existing.requirementId ?? '') === requirementId)
+    && (args.requirement_revision === undefined || existing.requirementRevision === args.requirement_revision)
+    && (args.plan_revision === undefined || existing.planRevision === args.plan_revision)
+    && (existing.planId ?? '') === planId
+    && (existing.semanticParentWorkId ?? '') === semanticParentWorkId
+    && existingDependencies.length === dependsOnWorkIds.length
+    && existingDependencies.every((id, index) => id === dependsOnWorkIds[index])
+    && (existing.requestId ?? '') === requestId;
+}
+
+export async function callRhWorkSemanticOperation(
+  store: WorkContractStoreOptions,
+  operation: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (!RH_WORK_SEMANTIC_OPERATIONS.has(operation)) return undefined;
+  const workId = operation === 'start' ? semanticWorkId(store, args) : String(args.work_id ?? '').trim();
+  if (operation === 'start') {
+    const objective = String(args.objective ?? '').trim();
+    if (!objective) return result(buildWorkSemanticFacadeResult({
+      status: 'blocked', summary: 'WORK_OBJECTIVE_REQUIRED', data: { workId },
+    }) as unknown as Record<string, unknown>, true);
+    const requestId = typeof args.request_id === 'string' ? args.request_id.trim() : '';
+    const existing = getWorkContract(store, workId);
+    if (existing) {
+      if (!semanticCreateMatches(existing, args, requestId)) return result(buildWorkSemanticFacadeResult({
+        status: 'blocked',
+        summary: `WORK_SEMANTIC_CREATE_CONFLICT: ${workId}`,
+        data: { workId, currentWork: workSemanticView(existing) },
+      }) as unknown as Record<string, unknown>, true);
+      return result(buildWorkSemanticFacadeResult({
+        summary: `Work ${workId} already exists; semantic create was deduplicated.`,
+        data: { work: workSemanticView(existing), deduplicated: true },
+      }) as unknown as Record<string, unknown>);
+    }
+    try {
+      const basis = workBasis(store, {
+        requirementId: typeof args.requirement_id === 'string' ? args.requirement_id.trim() || undefined : undefined,
+        requirementRevision: typeof args.requirement_revision === 'number' ? args.requirement_revision : undefined,
+        planId: typeof args.plan_id === 'string' ? args.plan_id.trim() || undefined : undefined,
+        planRevision: typeof args.plan_revision === 'number' ? args.plan_revision : undefined,
+      });
+      const created = createWorkSemanticContext(store, {
+        workId,
+        objective,
+        requestedBy: 'chatgpt',
+        ...basis,
+        ...(typeof args.semantic_parent_work_id === 'string' ? { semanticParentWorkId: args.semantic_parent_work_id } : {}),
+        ...(Array.isArray(args.depends_on_work_ids) ? { dependsOnWorkIds: args.depends_on_work_ids.map(String) } : {}),
+        ...(requestId ? { requestId } : {}),
+      });
+      return result(buildWorkSemanticFacadeResult({
+        summary: `Work ${workId} created as semantic context.`,
+        data: { work: workSemanticView(created), deduplicated: false },
+      }) as unknown as Record<string, unknown>);
+    } catch (error) {
+      const raced = getWorkContract(store, workId);
+      if (raced && semanticCreateMatches(raced, args, requestId)) return result(buildWorkSemanticFacadeResult({
+        summary: `Work ${workId} already exists; semantic create was deduplicated.`,
+        data: { work: workSemanticView(raced), deduplicated: true },
+      }) as unknown as Record<string, unknown>);
+      return result(buildWorkSemanticFacadeResult({
+        status: 'blocked',
+        summary: error instanceof Error ? error.message : String(error),
+        data: { workId },
+      }) as unknown as Record<string, unknown>, true);
+    }
+  }
+  if (operation === 'get') {
+    const work = workId ? getWorkContract(store, workId) : undefined;
+    if (!work) return result(buildWorkSemanticFacadeResult({
+      status: 'not_found', summary: `Work ${workId || '(missing)'} not found.`, data: { workId },
+    }) as unknown as Record<string, unknown>, true);
+    const semantic = workSemanticView(work);
+    const detail = args.detail_level === 'detail';
+    const revisionHistory = detail ? listWorkSemanticRevisionRecords(store, semantic.workId, 100) : [];
+    const objectiveGraph = detail ? projectWorkObjectiveGraph(
+      readWorkContractStore(store).contracts.map(workSemanticView),
+      listWorkSemanticRevisionRecords(store, undefined, 200),
+      semantic.workId,
+    ) : undefined;
+    return result(buildWorkSemanticFacadeResult({
+      summary: `Work ${semantic.workId} retrieved at semantic revision ${semantic.revision}.`,
+      data: {
+        work: semantic,
+        versionBinding: versionBinding(store, work, detail),
+        ...(detail ? {
+          revisionHistory,
+          objectiveGraph,
+          executionEvidence: projectWorkExecutionEvidence(work),
+          continuation: buildWorkContinuationSnapshot(work),
+        } : {}),
+      },
+      detailLevel: args.detail_level === 'detail' ? 'detail' : 'summary',
+    }) as unknown as Record<string, unknown>);
+  }
+
+  const expectedRevision = Number(args.expected_revision);
+  const targetState = operation === 'complete'
+    ? 'completed'
+    : (args.work_state === 'open' || args.work_state === 'completed' || args.work_state === 'cancelled' ? args.work_state : undefined);
+  try {
+    const current = getWorkContract(store, workId);
+    const choosingVersion = typeof args.requirement_revision === 'number' || typeof args.plan_revision === 'number';
+    if (choosingVersion && !current) throw new Error(`WORK_NOT_FOUND: ${workId}`);
+    if (choosingVersion && current && semanticWorkState(current) !== 'open') throw new Error(`WORK_TERMINAL_BASIS_IMMUTABLE: ${workId}`);
+    const basis = choosingVersion ? workBasis(store, {
+      requirementId: current?.requirementId,
+      requirementRevision: typeof args.requirement_revision === 'number' ? args.requirement_revision : undefined,
+      planId: current?.planId,
+      planRevision: typeof args.plan_revision === 'number' ? args.plan_revision : undefined,
+    }) : undefined;
+    const revised = reviseWorkSemanticContext(store, workId, {
+      expectedRevision,
+      ...(typeof args.objective === 'string' ? { objective: args.objective } : {}),
+      ...(targetState ? { state: targetState } : {}),
+      ...(typeof args.requirement_revision === 'number' ? { requirementRevision: basis?.requirementRevision } : {}),
+      ...(typeof args.plan_revision === 'number' ? { planRevision: basis?.planRevision } : {}),
+      ...(operation === 'revise' && typeof args.semantic_parent_work_id === 'string' ? { semanticParentWorkId: args.semantic_parent_work_id } : {}),
+      ...(operation === 'revise' && Array.isArray(args.depends_on_work_ids) ? { dependsOnWorkIds: args.depends_on_work_ids.map(String) } : {}),
+      ...(Array.isArray(args.work_result_refs) ? { resultRefs: args.work_result_refs.map(String) } : {}),
+    });
+    const semantic = workSemanticView(revised);
+    const supervisorClosure = semantic.state !== 'open'
+      ? await stopTerminalWorkSupervisor(store, semantic.workId, semantic.state)
+      : undefined;
+    let resourceReconciliation: Awaited<ReturnType<typeof reconcileSingleTerminalWorkCleanup>> | undefined;
+    if (
+      semantic.state !== 'open'
+      && store.controllerHome
+      && revised.repoId?.trim()
+      && readWorkHandle(store.controllerHome, revised.repoId, revised.workId)
+    ) {
+      try {
+        resourceReconciliation = await reconcileSingleTerminalWorkCleanup(
+          store.controllerHome,
+          revised.repoId,
+          revised.workId,
+        );
+      } catch (error) {
+        resourceReconciliation = {
+          status: 'blocked',
+          workId: revised.workId,
+          reason: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+    return result(buildWorkSemanticFacadeResult({
+      summary: `Work ${semantic.workId} revised atomically to semantic revision ${semantic.revision}.`,
+      data: {
+        work: semantic,
+        expectedRevision,
+        semanticRevision: semantic.revision,
+        versionBinding: versionBinding(store, revised, false),
+        ...(supervisorClosure ? { supervisorClosure } : {}),
+        ...(resourceReconciliation ? { resourceReconciliation } : {}),
+      },
+    }) as unknown as Record<string, unknown>);
+  } catch (error) {
+    const current = workId ? getWorkContract(store, workId) : undefined;
+    return result(buildWorkSemanticFacadeResult({
+      status: 'blocked', summary: error instanceof Error ? error.message : String(error),
+      data: { workId, expectedRevision, ...(current ? { currentWork: workSemanticView(current) } : {}) },
+    }) as unknown as Record<string, unknown>, true);
+  }
+}

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

@@ -0,0 +1,113 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { WorkflowJsonValue } from '../../../packages/workflow-runtime/api/index';
+import { getWorkContract } from '../../../packages/kernel/work/api/index';
+import { selectRepositoryCheckout } from '../../../src/cli/repositories/registry';
+import { executionIdentityForRepository } from '../../../src/runtime/control-plane/execution/execution-identity';
+import { readWorkflowRun } from '../../../src/runtime/control-plane/persistence/workflow-run-store';
+import { schedulePublicationOutcomeCollection } from '../../../src/runtime/root/assistant-learning-loop';
+import { ensureXiaohongshuWorkflowInstalled, XIAOHONGSHU_WORKFLOW_IDS } from '../../../src/runtime/workflows/first-party/xiaohongshu';
+import { executeRegisteredWorkflow, observeAndReconcileRegisteredWorkflow } from '../../../src/runtime/workflows/runtime';
+import { buildFacadeResult } from '../../../src/runtime/control-plane/facade';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { result } from './result-adapter';
+
+type RepositorySelection = Parameters<typeof selectRepositoryCheckout>[0];
+
+/**
+ * Dedicated rh_work Workflow domain dispatch. Workflow execution is fenced by
+ * its typed Work/target/effect identities rather than Work-wide Controller ownership;
+ * this adapter does not own Work lifecycle transitions or semantic completion.
+ */
+export async function callRhWorkWorkflowOperation(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: RepositorySelection,
+  operation: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (operation !== 'workflow_execute' && operation !== 'workflow_reconcile') return undefined;
+  const store = { controllerHome: ctx.controllerHome, repoId: repository.repoId };
+  try {
+    const workId = String(args.work_id ?? '').trim();
+    const workflowId = String(args.workflow_id ?? '').trim();
+    const runId = String(args.workflow_run_id ?? '').trim();
+    if (!workId || !workflowId || !runId) throw new Error('WORKFLOW_FACADE_IDENTITY_REQUIRED');
+    const work = getWorkContract(store, workId);
+    if (!work) throw new Error(`WORK_NOT_FOUND: ${workId}`);
+
+    const workRepository = selectRepositoryCheckout(repository, work.checkoutId);
+    const executionIdentity = executionIdentityForRepository(workRepository, { workId });
+    if (Object.values(XIAOHONGSHU_WORKFLOW_IDS).includes(workflowId as never)) {
+      ensureXiaohongshuWorkflowInstalled(ctx.controllerHome, workflowId);
+    }
+    const projectId = typeof args.workflow_scope_project_id === 'string' ? args.workflow_scope_project_id.trim() : '';
+    const registryScope = projectId ? { kind: 'project' as const, projectId } : { kind: 'controller' as const };
+    const workflowInputs = args.workflow_inputs && typeof args.workflow_inputs === 'object' && !Array.isArray(args.workflow_inputs)
+      ? args.workflow_inputs as Record<string, WorkflowJsonValue>
+      : {};
+    const base = {
+      controllerHome: ctx.controllerHome,
+      repository: workRepository,
+      executionIdentity,
+      workId,
+      runId,
+      registryScope,
+      workflowId,
+      inputs: workflowInputs,
+      timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+    };
+    const learningMetadata = (workflow: Awaited<ReturnType<typeof executeRegisteredWorkflow>>) => {
+      const persisted = readWorkflowRun(ctx.controllerHome, workId, runId)?.value;
+      let outcomeCollectionSchedule;
+      let outcomeCollectionError: string | undefined;
+      if (workflow.status === 'succeeded' && workflow.publicationReceipt) {
+        try {
+          outcomeCollectionSchedule = schedulePublicationOutcomeCollection({
+            controllerHome: ctx.controllerHome,
+            repoId: repository.repoId,
+            workId,
+            publication: workflow.publicationReceipt,
+            workflowInputs,
+          });
+        } catch (error) {
+          outcomeCollectionError = error instanceof Error ? error.message : 'OUTCOME_COLLECTION_SCHEDULE_FAILED';
+        }
+      }
+      return {
+        ...(persisted?.evidenceRef ? { workflowEvidenceRef: persisted.evidenceRef } : {}),
+        ...(outcomeCollectionSchedule ? { outcomeCollectionSchedule } : {}),
+        ...(outcomeCollectionError ? { outcomeCollectionError } : {}),
+      };
+    };
+
+    if (operation === 'workflow_reconcile') {
+      const reconciliationRequestId = String(args.workflow_reconciliation_request_id ?? '').trim();
+      if (!reconciliationRequestId) throw new Error('WORKFLOW_RECONCILIATION_REQUEST_ID_REQUIRED');
+      const reconciled = await observeAndReconcileRegisteredWorkflow({ ...base, reconciliationRequestId });
+      if (reconciled.status === 'running') {
+        const resumed = await executeRegisteredWorkflow(base);
+        return result(buildFacadeResult({
+          summary: `Workflow ${workflowId}/${runId} reconciled from canonical observation and resumed without replaying the uncertain effect.`,
+          data: { workflow: resumed, ...learningMetadata(resumed) },
+        }) as unknown as Record<string, unknown>);
+      }
+      return result(buildFacadeResult({
+        status: reconciled.status === 'failed' ? 'blocked' : 'ok',
+        summary: `Workflow ${workflowId}/${runId} reconciliation settled as ${reconciled.status}.`,
+        data: { workflow: reconciled },
+      }) as unknown as Record<string, unknown>, reconciled.status === 'failed');
+    }
+
+    const executed = await executeRegisteredWorkflow(base);
+    return result(buildFacadeResult({
+      status: executed.status === 'failed' || executed.status === 'reconcile_required' ? 'blocked' : 'ok',
+      summary: `Workflow ${workflowId}/${runId} is ${executed.status}.`,
+      data: { workflow: executed, ...learningMetadata(executed) },
+    }) as unknown as Record<string, unknown>, executed.status === 'failed' || executed.status === 'reconcile_required');
+  } catch (error) {
+    return result(buildFacadeResult({
+      status: 'blocked',
+      summary: error instanceof Error ? error.message : 'Workflow execution failed.',
+      data: { workflowExecuted: false },
+    }) as unknown as Record<string, unknown>, true);
+  }
+}

package/adapters/mcp/runtime-gateway/workflow-supervisor-adapter.ts

@@ -0,0 +1,180 @@
+import { createHash } from 'node:crypto';
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import {
+  getWorkflowSupervisorContinuationProof,
+  getWorkflowSupervisorTask,
+  getWorkflowSupervisorTaskStall,
+  listWorkflowSupervisorTasks,
+  listWorkflowSupervisorTerminalTasks,
+  migrateWorkflowSupervisorConversation,
+  recoverWorkflowSupervisorTask,
+  registerWorkflowSupervisorTask,
+  reviseWorkflowSupervisorTaskObjective,
+  reserveWorkflowSupervisorEnrollment,
+  stopWorkflowSupervisorTask,
+} from '../../../supervisor/client';
+import { resolveWorkflowSupervisorForgeHome } from '../../../supervisor/paths';
+import { workflowSupervisorCompletionContractSha256 } from '../../../supervisor/store';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { result } from './result-adapter';
+
+function textArg(args: Record<string, unknown>, key: string): string {
+  return typeof args[key] === 'string' ? String(args[key]).trim() : '';
+}
+
+function standaloneTaskId(repoId: string | undefined, requestId: string): string {
+  const digest = createHash('sha256').update(`${repoId ?? 'global'}\0${requestId}`).digest('hex').slice(0, 24);
+  return `supervisor:${digest}`;
+}
+
+export async function callWorkflowSupervisorAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (name !== 'supervisor_task') return undefined;
+  const operation = textArg(args, 'operation');
+  const forgeHome = resolveWorkflowSupervisorForgeHome(ctx.controllerHome);
+  const repoId = textArg(args, 'repo_id') || ctx.explicitRepository?.repoId || ctx.repoId || undefined;
+
+  if (operation === 'start') {
+    const objective = textArg(args, 'objective');
+    const requestId = textArg(args, 'request_id');
+    if (!objective) throw new Error('WORKFLOW_SUPERVISOR_OBJECTIVE_REQUIRED');
+    if (!requestId) throw new Error('WORKFLOW_SUPERVISOR_REQUEST_ID_REQUIRED');
+    const workId = textArg(args, 'work_id');
+    const requirementId = textArg(args, 'requirement_id');
+    if (workId && requirementId) throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_AMBIGUOUS');
+    if ((workId || requirementId) && !repoId) throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_REPO_REQUIRED');
+    const id = standaloneTaskId(repoId, requestId);
+    const task = await registerWorkflowSupervisorTask(forgeHome, {
+      taskId: id,
+      conversationId: `bootstrap:${id}`,
+      conversationUrl: 'https://chatgpt.com/',
+      objective,
+      completionContract: {
+        kind: 'model_semantic_completion',
+        ...(repoId ? { repo_id: repoId, controller_home: ctx.controllerHome } : {}),
+        ...(workId ? { work_id: workId } : {}),
+        ...(requirementId ? { requirement_id: requirementId } : {}),
+      },
+      continuationPolicy: { kind: 'standalone_supervisor', bootstrap: true, ...(repoId ? { repo_id: repoId } : {}) },
+      userBlockerPolicy: { kind: 'model_semantic_user_blocker' },
+    });
+    const effect = await reserveWorkflowSupervisorEnrollment(forgeHome, task.taskId);
+    return result({ task, effect, summary: `Standalone Supervisor task ${task.taskId} started.` });
+  }
+
+  if (operation === 'list') {
+    if (args.terminal_only === true) {
+      const terminalTasks = await listWorkflowSupervisorTerminalTasks(forgeHome);
+      return result({ terminalTasks, count: terminalTasks.length, terminalOnly: true, summary: `${terminalTasks.length} canonically terminal Supervisor task(s) in retained history; conversations are not archived or deleted.` });
+    }
+    const activeOnly = args.active_only !== false;
+    const tasks = await listWorkflowSupervisorTasks(forgeHome, activeOnly);
+    return result({ tasks, count: tasks.length, activeOnly, summary: `${tasks.length} Supervisor task(s) listed.` });
+  }
+
+  if (operation === 'revise') {
+    const id = textArg(args, 'task_id');
+    const objective = textArg(args, 'objective');
+    const expectedObjectiveSha256 = textArg(args, 'expected_objective_sha256');
+    const expectedCompletionContractSha256 = textArg(args, 'expected_completion_contract_sha256');
+    const workId = textArg(args, 'work_id');
+    const requirementId = textArg(args, 'requirement_id');
+    const requestId = textArg(args, 'request_id');
+    if (!id) throw new Error('WORKFLOW_SUPERVISOR_TASK_ID_REQUIRED');
+    if (!objective) throw new Error('WORKFLOW_SUPERVISOR_OBJECTIVE_REQUIRED');
+    if (!expectedObjectiveSha256) throw new Error('WORKFLOW_SUPERVISOR_OBJECTIVE_REVISION_EXPECTED_SHA_REQUIRED');
+    if (!requestId) throw new Error('WORKFLOW_SUPERVISOR_REQUEST_ID_REQUIRED');
+    if (workId && requirementId) throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_TARGET_INVALID');
+    if ((workId || requirementId) && !expectedCompletionContractSha256) throw new Error('WORKFLOW_SUPERVISOR_COMPLETION_CONTRACT_REVISION_EXPECTED_SHA_REQUIRED');
+    if (!(workId || requirementId) && expectedCompletionContractSha256) throw new Error('WORKFLOW_SUPERVISOR_COMPLETION_CONTRACT_REVISION_TARGET_REQUIRED');
+    const revised = await reviseWorkflowSupervisorTaskObjective(forgeHome, {
+      taskId: id,
+      objective,
+      expectedObjectiveSha256,
+      requestId,
+      ...(workId ? { workId } : {}),
+      ...(requirementId ? { requirementId } : {}),
+      ...(expectedCompletionContractSha256 ? { expectedCompletionContractSha256 } : {}),
+      authorizedBy: textArg(args, 'authorized_by') || 'operator',
+    });
+    const bindingSummary = workId || requirementId
+      ? `; semantic completion binding ${revised.semanticBindingChanged ? 'revised' : 'confirmed'}`
+      : '';
+    return result({ ...revised, summary: `Supervisor task ${id} objective ${revised.changed ? 'revised' : 'confirmed'} in place${bindingSummary}.` });
+  }
+
+  if (operation === 'stop') {
+    const id = textArg(args, 'task_id');
+    if (!id) throw new Error('WORKFLOW_SUPERVISOR_TASK_ID_REQUIRED');
+    const stopped = await stopWorkflowSupervisorTask(forgeHome, id, textArg(args, 'reason') || 'Stopped by operator request.');
+    return result({ ...stopped, summary: `Supervisor task ${id} stopped.` });
+  }
+
+  if (operation === 'switch_to_fresh_conversation') {
+    const id = textArg(args, 'task_id');
+    const expectedConversationId = textArg(args, 'expected_conversation_id');
+    const requestId = textArg(args, 'request_id');
+    const reason = textArg(args, 'reason');
+    if (!id) throw new Error('WORKFLOW_SUPERVISOR_TASK_ID_REQUIRED');
+    if (!expectedConversationId) throw new Error('WORKFLOW_SUPERVISOR_MIGRATION_EXPECTED_CONVERSATION_REQUIRED');
+    if (!requestId) throw new Error('WORKFLOW_SUPERVISOR_REQUEST_ID_REQUIRED');
+    if (!reason) throw new Error('WORKFLOW_SUPERVISOR_MIGRATION_REASON_REQUIRED');
+    const migrated = await migrateWorkflowSupervisorConversation(forgeHome, {
+      taskId: id, expectedConversationId, requestId, reason, fresh: true,
+      authorizedBy: textArg(args, 'authorized_by') || 'operator',
+    });
+    return result({
+      ...migrated,
+      status: migrated.migrated ? 'switching_to_fresh_conversation' : 'unchanged',
+      summary: migrated.migrated
+        ? `Supervisor task ${id} reserved a fresh conversation and will bind it after the enrollment send is observed.`
+        : `Supervisor task ${id} conversation was unchanged.`,
+    });
+  }
+
+  if (operation === 'recover') {
+    const id = textArg(args, 'task_id');
+    const requestId = textArg(args, 'request_id');
+    const reason = textArg(args, 'reason');
+    if (!id) throw new Error('WORKFLOW_SUPERVISOR_TASK_ID_REQUIRED');
+    if (!requestId) throw new Error('WORKFLOW_SUPERVISOR_REQUEST_ID_REQUIRED');
+    if (!reason) throw new Error('WORKFLOW_SUPERVISOR_RECOVERY_REASON_REQUIRED');
+    const recovered = await recoverWorkflowSupervisorTask(forgeHome, {
+      taskId: id,
+      sourceEffectId: textArg(args, 'source_effect_id') || undefined,
+      requestId,
+      reason,
+      authorizedBy: textArg(args, 'authorized_by') || 'operator',
+      ...(args.supersede_unknown === true ? { supersedeUnknown: true } : {}),
+    });
+    return result({ ...recovered, summary: `Supervisor task ${id} recovery ${recovered.action}.` });
+  }
+
+  if (operation === 'get') {
+    const id = textArg(args, 'task_id');
+    if (!id) throw new Error('WORKFLOW_SUPERVISOR_TASK_ID_REQUIRED');
+    const task = await getWorkflowSupervisorTask(forgeHome, id);
+    if (!task) return result({ taskId: id, status: 'not_found', summary: `Supervisor task ${id} not found.` }, true);
+    // Derived read-only projection: an effect that exhausted its mechanical
+    // retry/resume budget used to make the task silently leave the delivery
+    // queue. The stall state names the exact operator action that can move it.
+    const stall = await getWorkflowSupervisorTaskStall(forgeHome, id).catch(() => undefined);
+    return result({ task, completionContractSha256: workflowSupervisorCompletionContractSha256(task.completionContract), ...(stall ? { stall } : {}), summary: `Supervisor task ${id} retrieved${stall ? ` (${stall.state})` : ''}; canonical completion-contract CAS fingerprint included.` });
+  }
+
+  if (operation === 'proof') {
+    const activeReleaseId = textArg(args, 'active_release_id');
+    const notBefore = textArg(args, 'not_before');
+    if (!activeReleaseId) throw new Error('WORKFLOW_SUPERVISOR_PROOF_RELEASE_REQUIRED');
+    if (!notBefore) throw new Error('WORKFLOW_SUPERVISOR_PROOF_BOUNDARY_REQUIRED');
+    const proof = await getWorkflowSupervisorContinuationProof(forgeHome, { repoId, activeReleaseId, notBefore });
+    return result(proof
+      ? { proof, summary: `Standalone Supervisor continuation proof found for ${proof.taskId}.` }
+      : { status: 'not_found', summary: 'No matching CONTINUE -> CONTINUE -> DONE proof found.' }, !proof);
+  }
+
+  throw new Error(`WORKFLOW_SUPERVISOR_OPERATION_INVALID:${operation || '(missing)'}`);
+}