@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

package/runtime/node_modules/@metro-labs/daemon/src/connectors/gates.ts

@@ -0,0 +1,114 @@
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { decide, policyFor, setPolicies, type PolicyTarget, type ToolPolicy } from '../policy/policy.js';
+import { serverKeysOf } from './plugin-sync.js';
+import { NEEDS_APPROVAL, revokeToolPrompts, settlePrompts, takeGrant } from '../approvals/pending.js';
+import { isOrgRelayId } from './relay-id.js';
+import type { BlockedReason } from './relay-policy.js';
+
+export interface GateRow {
+  id: string;
+  name: string;
+  config: { policy?: ToolPolicy; toolGroups?: Record<string, ToolGroup> };
+}
+
+export interface ConnectorGate {
+  id: string;
+  name: string;
+  server: string;
+  policy: ToolPolicy;
+  tools: Record<string, ToolGroup>;
+}
+
+let gates: ConnectorGate[] = [];
+
+const normalized = (name: string): string => name.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+function approvalChanged(gate: ConnectorGate, tool: string, next: GateRow | undefined, keys: ReadonlyMap<string, string>): boolean {
+  if (next === undefined || gate.server !== keys.get(gate.id) || JSON.stringify([gate.name, gate.policy]) !== JSON.stringify([next.name, next.config.policy ?? {}])) return true;
+  const before = decide(gate.policy, { name: tool, group: toolGroupOf(gate, tool) });
+  const after = decide(next.config.policy, { name: tool, group: next.config.toolGroups?.[tool] === 'read' ? 'read' : 'write' });
+  return before !== after;
+}
+
+export function registerConnectors(rows: readonly GateRow[], keys: ReadonlyMap<string, string> = serverKeysOf([...rows])): void {
+  const next = rows.map((row) => ({
+    id: row.id,
+    name: row.name,
+    server: keys.get(row.id) ?? '',
+    policy: row.config.policy ?? {},
+    tools: row.config.toolGroups ?? {},
+  }));
+  revokeToolPrompts((tool) => {
+    const before = connectorToolOf(tool);
+    const after = connectorToolOf(tool, next);
+    if (before?.gate.id !== after?.gate.id) return true;
+    return before !== undefined && approvalChanged(before.gate, before.tool, rows.find((row) => row.id === before.gate.id), keys);
+  });
+  gates = next;
+  const entries = rows.flatMap((row): [PolicyTarget, ToolPolicy][] =>
+    row.config.policy === undefined ? [] : [[{ kind: 'connector', id: row.id }, row.config.policy]],
+  );
+  setPolicies('connector', entries);
+}
+
+export const connectorGates = (): readonly ConnectorGate[] => gates;
+
+export const toolGroupOf = (gate: ConnectorGate, tool: string): ToolGroup => (gate.tools[tool] === 'read' ? 'read' : 'write');
+
+const promptFor = (connectorId: string, tool: string) => (asked: string): boolean => {
+  const found = connectorToolOf(asked);
+  return found?.gate.id === connectorId && found.tool === tool;
+};
+
+export function blockedReason(connectorId: string, tool: string, args: Record<string, unknown> = {}): string | null {
+  const gate = gates.find((g) => g.id === connectorId);
+  if (gate === undefined) return 'This connector is not available.';
+  settlePrompts(promptFor(connectorId, tool), args);
+  const access = policyFor({ kind: 'connector', id: connectorId }, { name: tool, group: toolGroupOf(gate, tool) });
+  if (access === 'deny') return `Blocked by the owner's policy for ${gate.name} (${tool}).`;
+  if (access === 'allow' || takeGrant(promptFor(connectorId, tool), args)) return null;
+  return NEEDS_APPROVAL(gate.name, tool);
+}
+
+export function requestConnectorBlocker(): () => BlockedReason {
+  const permits = new Map<string, number>();
+  return () => {
+    const seen = new Map<string, number>();
+    return (id, tool, args) => {
+      const gate = gates.find((entry) => entry.id === id);
+      if (gate === undefined) return 'This organization connector is not available.';
+      const group = toolGroupOf(gate, tool);
+      const access = policyFor({ kind: 'connector', id }, { name: tool, group });
+      if (access !== 'ask') return blockedReason(id, tool, args);
+      const key = JSON.stringify([id, gate.server, gate.policy, group, tool, args]);
+      const occurrence = seen.get(key) ?? 0;
+      seen.set(key, occurrence + 1);
+      if (occurrence < (permits.get(key) ?? 0)) return null;
+      const reason = blockedReason(id, tool, args);
+      if (reason === null) permits.set(key, (permits.get(key) ?? 0) + 1);
+      return reason;
+    };
+  };
+}
+
+function resolvedTool(gate: ConnectorGate, called: string): { gate: ConnectorGate; tool: string } {
+  const known = [...Object.keys(gate.tools), ...Object.keys(gate.policy.tools ?? {})];
+  return { gate, tool: known.find((name) => name === called) ?? known.find((name) => normalized(name) === called) ?? called };
+}
+
+export function connectorToolOf(toolName: string, entries: readonly ConnectorGate[] = gates): { gate: ConnectorGate; tool: string } | undefined {
+  if (toolName.startsWith('mcp__metro__')) return undefined;
+  for (const gate of entries)
+    for (const prefix of [`mcp__plugin_metro_${gate.server}__`, `mcp__${gate.server}__`])
+      if (toolName.startsWith(prefix) && toolName.length > prefix.length) return resolvedTool(gate, toolName.slice(prefix.length));
+  return legacyToolOf(toolName, entries);
+}
+
+function legacyToolOf(toolName: string, entries: readonly ConnectorGate[]): { gate: ConnectorGate; tool: string } | undefined {
+  if (!toolName.startsWith('mcp__metro_box_')) return undefined;
+  const legacy = entries.filter((gate) => !isOrgRelayId(gate.id) && toolName.startsWith(`mcp__${normalized(`metro.box ${gate.name}`)}__`));
+  const gate = legacy.length === 1 ? legacy[0] : undefined;
+  if (gate === undefined) return undefined;
+  const called = toolName.slice(`mcp__${normalized(`metro.box ${gate.name}`)}__`.length);
+  return called === '' ? undefined : resolvedTool(gate, called);
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/health.ts

@@ -0,0 +1,18 @@
+export interface ConnectorHealth {
+  ok: boolean;
+  reason: string | null;
+  at: string;
+}
+
+const seen = new Map<string, ConnectorHealth>();
+
+export function noteHealth(id: string, ok: boolean, reason: string | null = null): void {
+  seen.set(id, { ok, reason: ok ? null : reason, at: new Date().toISOString() });
+}
+
+export const healthOf = (id: string): ConnectorHealth | null => seen.get(id) ?? null;
+
+export function forgetHealth(id?: string): void {
+  if (id === undefined) seen.clear();
+  else seen.delete(id);
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/metro-api.ts

@@ -0,0 +1,93 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { signAgentRequest } from '@metro-labs/http/agent-signature';
+import type { AgentKey } from './agent-key.js';
+
+const TIMEOUT_MS = 15_000;
+const ANSWER_MAX = 64 * 1024;
+
+export type AgentFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface MetroApi {
+  base: string;
+  fetch: AgentFetch;
+  now: () => number;
+}
+
+export const METRO_API: MetroApi = {
+  base: 'https://api.metro.box',
+  fetch: (url, init) => fetch(url, init),
+  now: () => Date.now(),
+};
+
+const tooLarge = (): ApiError => new ApiError('api.metro.box sent an answer too large for Metro.', 503);
+const unreachable = (): ApiError => new ApiError('Metro could not reach api.metro.box. Try again.', 503);
+
+async function answerOf(response: Response, max: number): Promise<unknown> {
+  if (Number(response.headers.get('content-length') ?? '0') > max) throw tooLarge();
+  const reader = response.body?.getReader();
+  if (reader === undefined) return null;
+  const parts: Uint8Array[] = [];
+  let size = 0;
+  for (let part = await reader.read(); !part.done; part = await reader.read()) {
+    size += part.value.length;
+    if (size > max) {
+      await reader.cancel();
+      throw tooLarge();
+    }
+    parts.push(part.value);
+  }
+  try {
+    return JSON.parse(Buffer.concat(parts).toString('utf8')) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+export class MetroApiRefusal extends ApiError {
+  constructor(message: string, readonly upstreamStatus: number, readonly code: string | null) {
+    super(message, upstreamStatus >= 500 ? 503 : 400);
+  }
+}
+
+function refusal(status: number, value: unknown): ApiError {
+  const said = isRecord(value) && typeof value.error === 'string' && value.error.length <= 300 ? value.error : `api.metro.box answered ${String(status)}`;
+  const code = isRecord(value) && typeof value.code === 'string' ? value.code : null;
+  return new MetroApiRefusal(said, status, code);
+}
+
+interface AgentCallOptions {
+  answerMax?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+function signedCall(api: MetroApi, key: AgentKey, path: string, body: Record<string, unknown> | undefined): { url: URL; method: string; text: string; authorization: string } {
+  const url = new URL(path, api.base);
+  const method = body === undefined ? 'GET' : 'POST';
+  const text = body === undefined ? '' : JSON.stringify(body);
+  const authorization = signAgentRequest({ method, host: url.host, path: `${url.pathname}${url.search}`, body: Buffer.from(text, 'utf8') }, key.signing, key.keyId, api.now());
+  return { url, method, text, authorization };
+}
+
+export async function agentCall(api: MetroApi, key: AgentKey, path: string, body?: Record<string, unknown>, options: AgentCallOptions = {}): Promise<Record<string, unknown>> {
+  const { url, method, text, authorization } = signedCall(api, key, path, body);
+  let response: Response;
+  try {
+    response = await api.fetch(url.toString(), {
+      method,
+      headers: { authorization, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+      ...(body === undefined ? {} : { body: text }),
+      redirect: 'error',
+      signal: AbortSignal.any([AbortSignal.timeout(options.timeoutMs ?? TIMEOUT_MS), ...(options.signal === undefined ? [] : [options.signal])]),
+    });
+  } catch {
+    throw unreachable();
+  }
+  const value = await answerOf(response, options.answerMax ?? ANSWER_MAX).catch((err: unknown) => {
+    throw err instanceof ApiError ? err : unreachable();
+  });
+  if (!response.ok) throw refusal(response.status, value);
+  if (!isRecord(value)) throw new ApiError('api.metro.box sent an answer Metro cannot read.', 503);
+  return value;
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/migration-api.ts

@@ -0,0 +1,60 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { parseId } from '@metro-labs/core/ids';
+import { ApiError } from '@metro-labs/http/api-error';
+import { readJsonBody, sessionRoute } from '@metro-labs/http/api-http';
+import { publicOAuthResource } from '@metro-labs/http/connector-public-url';
+import type { ConnectorMigrations, MigrationAction } from './migration-control.js';
+
+const PATH = '/api/connectors/migrations';
+const actions: readonly MigrationAction[] = ['move', 'prepare', 'reconcile', 'cutover', 'rollback', 'resolve'];
+export type MigrationApiDeps = Pick<ConnectorMigrations, 'status' | 'run'>;
+
+interface MigrationInput {
+  sourceId: string;
+  action: MigrationAction;
+  scope: string;
+  operationId: string | null;
+  uncertainty: string | null;
+  oauthResource?: string;
+}
+
+function operationOf(value: unknown): string | null {
+  if (value === null) return null;
+  const id = parseId(value);
+  if (id === null) throw new ApiError('A migration needs its current operation ID, or null for an unprepared source.', 400);
+  return id;
+}
+
+function receiptOf(body: Record<string, unknown>, action: MigrationAction): string | null {
+  if (action !== 'resolve') {
+    if (Object.hasOwn(body, 'uncertainty')) throw new ApiError('Only request settlement accepts an uncertainty receipt.', 400);
+    return null;
+  }
+  if (typeof body.uncertainty !== 'string' || !/^[a-f0-9]{64}$/.test(body.uncertainty)) throw new ApiError('Confirming settled vendor requests needs the current uncertainty receipt.', 400);
+  return body.uncertainty;
+}
+
+function inputOf(body: unknown): MigrationInput {
+  if (!isRecord(body) || Object.keys(body).some((key) => !['scope', 'sourceId', 'action', 'operationId', 'uncertainty', 'oauthResource'].includes(key)) || typeof body.scope !== 'string' || !/^[a-f0-9]{64}$/.test(body.scope)) {
+    throw new ApiError('A migration needs its connector, action and current enrollment scope.', 400);
+  }
+  const sourceId = parseId(body.sourceId);
+  const action = actions.find((value) => value === body.action);
+  if (sourceId === null || action === undefined) throw new ApiError('A migration needs a valid connector and action.', 400);
+  return {
+    sourceId, action, scope: body.scope, operationId: operationOf(body.operationId), uncertainty: receiptOf(body, action),
+    ...(body.oauthResource === undefined ? {} : { oauthResource: publicOAuthResource(body.oauthResource) }),
+  };
+}
+
+export function handleMigrationRequest(req: IncomingMessage, res: ServerResponse, deps: MigrationApiDeps): boolean {
+  return sessionRoute(req, res, { methods: { [PATH]: ['GET', 'POST'] }, admin: true, label: 'connector-migration-api' }, async (session) => {
+    const body = req.method === 'POST' ? await readJsonBody(req) : null;
+    const current = deps.status();
+    if (current.owner === null || current.owner !== session.subject) throw new ApiError('This agent belongs to another organization.', 403);
+    if (req.method !== 'POST') return current;
+    const { sourceId, action, scope, operationId, uncertainty, oauthResource } = inputOf(body);
+    return deps.run(sourceId, action, scope, operationId, uncertainty, oauthResource);
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/migration-control.ts

@@ -0,0 +1,366 @@
+import { newId } from '@metro-labs/core/ids';
+import { log } from '@metro-labs/core/log';
+import type { ConnectorSyncStatus } from '@metro-labs/core/connector-sync';
+import { ApiError } from '@metro-labs/http/api-error';
+import { publicOAuthResource } from '@metro-labs/http/connector-public-url';
+import type { DeliverySnapshot } from '@metro-labs/http/connector-delivery';
+import { migrationResponseOf, sealConnectorMigration, type MigrationResponse, type MigrationView as RemoteMigration } from '@metro-labs/http/connector-migration';
+import { agentsDir } from '../agents/files.js';
+import { readAgentKey, type AgentKey } from './agent-key.js';
+import { agentCall, METRO_API, MetroApiRefusal, type MetroApi } from './metro-api.js';
+import { migrationSource } from './migration-preview.js';
+import { MigrationBlocked, migrationPayload } from './migration-source.js';
+import { localMigrationIdle } from './migration-guard.js';
+import { migrationUncertaintyReceipt, migrationRefreshUncertain, migrationOperationsIdle, resolveMigrationUncertainty } from './migration-operations.js';
+import { flushMigrationSource, localRollbackMigrationSource } from './store.js';
+import { freshOrgConnectors, orgConnectorMigrationIdle, orgConnectorSyncStatus, refreshOrgConnectorRuntime } from './org-sync-watch.js';
+import { migrationRecord, migrationRecords, saveMigration, type MigrationRecord } from './migration-state.js';
+
+export type MigrationAction = 'move' | 'prepare' | 'reconcile' | 'cutover' | 'rollback' | 'resolve';
+interface Context { key: AgentKey; owner: string; agentId: string; scope: string }
+export interface MigrationView extends Pick<MigrationRecord, 'id' | 'sourceId' | 'name' | 'destinationId' | 'phase' | 'auth' | 'reason'> {
+  uncertainty: string | null;
+  move: boolean;
+  grantImported: boolean;
+}
+export interface MigrationStatus {
+  scope: string;
+  owner: string | null;
+  agentId: string | null;
+  enabled: boolean;
+  enrolled: boolean;
+  migrations: MigrationView[];
+}
+
+interface MigrationDeps {
+  dir?: string;
+  api?: MetroApi;
+  status?: () => ConnectorSyncStatus;
+  key?: () => AgentKey | null;
+  fresh?: () => Promise<DeliverySnapshot>;
+  changed?: () => void;
+  localIdle?: (id: string) => boolean;
+  orgIdle?: (id: string) => boolean;
+  restore?: (id: string, oauth: boolean) => void;
+}
+
+const conflict = (message: string): ApiError => new ApiError(message, 409);
+const uncertain = (): ApiError => new ApiError('The migration request was not confirmed. Refresh and reconcile this connector before trying another action; an interrupted request may already have reached Metro.', 503);
+const viewOf = ({ id, sourceId, name, destinationId, phase, auth, reason, move, grantImported }: MigrationRecord, uncertainty: string | null): MigrationView => ({ id, sourceId, name, destinationId, phase, auth, reason, uncertainty, move: move === true, grantImported: grantImported === true });
+const reasons: Record<RemoteMigration['readiness'], string | null> = { pending: 'not_verified', ready: null, signin: 'sign_in', changed: 'destination_changed', unavailable: 'unavailable', refresh_uncertain: 'refresh_uncertain' };
+const samePolicy = (a: MigrationRecord['policy'], b: MigrationRecord['policy']): boolean =>
+  (a.read ?? 'allow') === (b.read ?? 'allow') && (a.write ?? 'allow') === (b.write ?? 'allow') && JSON.stringify(Object.entries(a.tools ?? {}).sort()) === JSON.stringify(Object.entries(b.tools ?? {}).sort());
+
+const grantTransfer = (record: MigrationRecord): boolean => record.move === true && record.auth === 'oauth';
+const upgrading = (record: MigrationRecord, remote: RemoteMigration): boolean => grantTransfer(record) && remote.grantImported !== true;
+const canUpgrade = (record: MigrationRecord): boolean => record.move !== true && ['preparing', 'prepared'].includes(record.phase);
+
+function checkResponse(record: MigrationRecord, remote: RemoteMigration): void {
+  if (remote.operationId !== record.id || remote.sourceId !== record.sourceId || (record.destinationId !== null && remote.destinationId !== record.destinationId)) throw uncertain();
+  if (remote.sourceStamp === null || remote.sourceStamp === record.sourceStamp || upgrading(record, remote)) return;
+  throw conflict('The prepared destination no longer matches this local connector. Reconcile its current operation before continuing.');
+}
+
+function callFailure(error: unknown, action: string): ApiError {
+  if (error instanceof MetroApiRefusal && error.code === 'migration_conflict') return new MigrationBlocked('destination_changed', 'The mapped destination already has credentials or changed settings. Inspect it and reconcile; Metro will not overwrite credentials or create a duplicate.');
+  if (action === 'prepare' && error instanceof MetroApiRefusal && error.upstreamStatus === 400 && error.code === 'oauth_resource_required') {
+    return new ApiError("Enter the provider's public OAuth resource. Roll back this preparation, then prepare again with that public value; never enter credentials.", 400);
+  }
+  return uncertain();
+}
+
+function received(record: MigrationRecord, snapshot: DeliverySnapshot): boolean {
+  const delivered = snapshot.connectors.find((row) => row.id === record.destinationId);
+  if (delivered?.state !== 'ready' || delivered.name !== record.name) return false;
+  const layers = delivered.policyLayers;
+  return layers === undefined ? samePolicy(delivered.policy, record.policy) : samePolicy(layers.organization, record.policy) && samePolicy(layers.agent, {});
+}
+
+export class ConnectorMigrations {
+  private readonly dir: string;
+  private readonly api: MetroApi;
+  private running = false;
+
+  constructor(private readonly deps: MigrationDeps = {}) {
+    this.dir = deps.dir ?? agentsDir();
+    this.api = deps.api ?? METRO_API;
+  }
+
+  private syncStatus(): ConnectorSyncStatus { return (this.deps.status ?? orgConnectorSyncStatus)(); }
+  private key(): AgentKey | null { return this.deps.key === undefined ? readAgentKey(this.dir) : this.deps.key(); }
+  private changed(): void { (this.deps.changed ?? refreshOrgConnectorRuntime)(); }
+  private localIdle(id: string): boolean { return this.deps.localIdle?.(id) ?? localMigrationIdle(id, this.dir); }
+  private orgIdle(id: string): boolean { return (this.deps.orgIdle ?? orgConnectorMigrationIdle)(id); }
+
+  status(): MigrationStatus {
+    const { scope, owner, agentId, enabled, enrolled } = this.syncStatus();
+    const keyId = this.key()?.keyId;
+    const migrations = migrationRecords(this.dir).filter((row) => row.owner === owner).map((row) => {
+      const uncertainty = migrationUncertaintyReceipt(row.sourceId, this.dir);
+      const reason = uncertainty === null ? row.reason : migrationRefreshUncertain(row.sourceId, this.dir) ? 'local_refresh_uncertain' : 'requests_uncertain';
+      return viewOf({ ...row, reason: row.agentId !== agentId || row.keyId !== keyId ? 'identity_changed' : reason }, uncertainty);
+    });
+    return { scope, owner, agentId, enabled, enrolled, migrations };
+  }
+
+  private context(scope: string, requireSync: boolean): Context {
+    const status = this.syncStatus();
+    const key = this.key();
+    if (scope !== status.scope) throw conflict('The organization, agent or enrollment changed. Refresh before continuing the migration.');
+    if (!status.enrolled || key?.enrollment?.organization !== status.owner || key.enrollment.server !== status.agentId) throw conflict('Enroll this agent with the current organization before migrating connectors.');
+    if (requireSync && !status.enabled) throw conflict('Enable organization connector sync on the Server page before preparing or switching a connector.');
+    return { key, owner: key.enrollment.organization, agentId: key.enrollment.server, scope };
+  }
+
+  private check(context: Context, record?: MigrationRecord): void {
+    const current = this.context(context.scope, false);
+    if (current.key.keyId !== context.key.keyId || current.owner !== context.owner || current.agentId !== context.agentId) throw conflict('The migration identity changed. Refresh before continuing.');
+    if (record !== undefined && (record.owner !== current.owner || record.agentId !== current.agentId || record.keyId !== current.key.keyId)) throw conflict('This migration belongs to a different enrollment. Restore its original enrollment before reconciling it.');
+  }
+
+  private save(context: Context, record: MigrationRecord): MigrationRecord {
+    this.check(context, record);
+    saveMigration(record, this.dir);
+    this.changed();
+    return record;
+  }
+
+  private source(record: MigrationRecord): ReturnType<typeof migrationPayload> {
+    const payload = migrationPayload(migrationSource(record.sourceId, this.dir, record.move === true && record.captured === true), record.oauthResource, record.move === true && record.captured === true);
+    if (payload.sourceStamp !== record.sourceStamp) throw conflict('The retained local connector changed. Restore its original settings before continuing; Metro will not overwrite it.');
+    return payload;
+  }
+
+  private async call(context: Context, record: MigrationRecord, action: 'begin' | 'prepare' | 'handover' | 'status' | 'activate' | 'rollback', sealed?: ReturnType<typeof sealConnectorMigration>): Promise<MigrationResponse> {
+    this.check(context, record);
+    let response: MigrationResponse;
+    try {
+      response = migrationResponseOf(await agentCall(this.api, context.key, '/api/agents/connector-migrations', {
+        action, operationId: record.id, sourceId: record.sourceId, ...(sealed === undefined ? {} : { sealed }),
+      }, { timeoutMs: 60_000 }));
+    } catch (error) {
+      throw callFailure(error, action);
+    }
+    this.check(context, record);
+    checkResponse(record, response.migration);
+    return response;
+  }
+
+  private accept(context: Context, record: MigrationRecord, remote: RemoteMigration): MigrationRecord {
+    if (remote.phase !== 'preparing' && remote.phase !== 'rolled_back' && (remote.name !== record.name || remote.auth !== record.auth || remote.policy === null || !samePolicy(record.policy, remote.policy))) {
+      return this.save(context, { ...record, destinationId: remote.destinationId, reason: 'destination_changed' });
+    }
+    return this.save(context, { ...record, destinationId: remote.destinationId, grantImported: remote.grantImported === true, reason: reasons[remote.readiness] });
+  }
+
+  private create(context: Context, id: string, oauthResource?: string, move = false): MigrationRecord {
+    const payload = migrationPayload(migrationSource(id, this.dir), oauthResource);
+    return this.save(context, {
+      id: newId(), owner: context.owner, agentId: context.agentId, keyId: context.key.keyId,
+      sourceId: id, name: payload.name, destinationId: null, phase: move ? 'freezing' : 'preparing', move, auth: payload.auth.kind,
+      sourceStamp: payload.sourceStamp, policy: payload.policy, reason: null,
+      ...(payload.oauthResource === undefined ? {} : { oauthResource: payload.oauthResource }),
+    });
+  }
+
+  private async prepare(context: Context, record: MigrationRecord): Promise<void> {
+    const payload = this.source(record);
+    const begun = await this.call(context, record, 'begin');
+    record = this.accept(context, record, begun.migration);
+    if (begun.migration.phase === 'prepared' && !upgrading(record, begun.migration)) {
+      this.save(context, { ...record, phase: 'prepared' });
+      return;
+    }
+    if (!['preparing', 'prepared'].includes(begun.migration.phase) || begun.receiving === undefined) throw uncertain();
+    const receiving = begun.receiving;
+    const expected = { owner: context.owner, agent: context.agentId, keyId: context.key.keyId, operationId: record.id, sourceId: record.sourceId, destinationId: record.destinationId };
+    for (const [key, value] of Object.entries(expected)) if (receiving.context[key as keyof typeof receiving.context] !== value) throw uncertain();
+    const sealed = sealConnectorMigration(receiving.publicKey, receiving.context, payload);
+    const { migration } = await this.call(context, record, grantTransfer(record) ? 'handover' : 'prepare', sealed);
+    record = this.accept(context, record, migration);
+    if (migration.phase !== 'prepared') throw uncertain();
+    this.save(context, { ...record, phase: 'prepared' });
+  }
+
+  private async freeze(context: Context, record: MigrationRecord): Promise<MigrationRecord | null> {
+    const until = Date.now() + 10_000;
+    while (!this.localIdle(record.sourceId) && migrationUncertaintyReceipt(record.sourceId, this.dir) === null && Date.now() < until) {
+      await new Promise((resolve) => { setTimeout(resolve, 100); });
+      this.check(context, record);
+    }
+    if (this.waiting(context, record)) return null;
+    flushMigrationSource(this.dir);
+    const payload = migrationPayload(migrationSource(record.sourceId, this.dir, true), record.oauthResource, true);
+    return this.save(context, { ...record, sourceStamp: payload.sourceStamp, captured: true, phase: 'preparing', reason: null });
+  }
+
+  private async move(context: Context, record: MigrationRecord): Promise<void> {
+    if (record.phase === 'recovering') return this.finishRecovery(context, record);
+    if (['active', 'rolled_back'].includes(record.phase)) return this.reconcile(context, record);
+    if (record.phase === 'rollback') return this.rollback(context, record);
+    if (record.phase === 'freezing') {
+      const captured = await this.freeze(context, record);
+      if (captured === null) return;
+      record = captured;
+    }
+    if (record.phase === 'preparing') {
+      await this.prepare(context, record);
+      record = migrationRecord(record.sourceId, this.dir) ?? record;
+    }
+    if (record.phase === 'prepared' || record.phase === 'cutover') await this.cutover(context, record);
+  }
+
+  private waiting(context: Context, record: MigrationRecord, includeOrganization = false): boolean {
+    const uncertain = migrationUncertaintyReceipt(record.sourceId, this.dir) !== null;
+    const localIdle = this.localIdle(record.sourceId);
+    if (!uncertain && localIdle && (!includeOrganization || this.orgIdle(record.sourceId))) return false;
+    this.save(context, { ...record, reason: uncertain ? migrationRefreshUncertain(record.sourceId, this.dir) ? 'local_refresh_uncertain' : 'requests_uncertain' : 'waiting_for_local' });
+    return true;
+  }
+
+  private async cutover(context: Context, record: MigrationRecord): Promise<void> {
+    this.context(context.scope, true);
+    this.source(record);
+    if (record.phase === 'prepared') {
+      const { migration } = await this.call(context, record, 'status');
+      record = this.accept(context, record, migration);
+      if (migration.phase !== 'prepared' || record.reason !== null) return;
+      record = this.save(context, { ...record, phase: 'cutover' });
+    }
+    if (this.waiting(context, record)) return;
+    const { migration } = await this.call(context, record, 'activate');
+    record = this.accept(context, record, migration);
+    if (migration.phase !== 'active' || record.reason !== null) return;
+    const snapshot = await (this.deps.fresh ?? freshOrgConnectors)().catch(() => {
+      throw new ApiError('Fresh organization delivery could not be verified. The source stays stopped; restore sync and reconcile this migration.', 503);
+    });
+    this.check(context, record);
+    this.context(context.scope, true);
+    if (!received(record, snapshot)) {
+      this.save(context, { ...record, reason: 'sync_unavailable' });
+      return;
+    }
+    this.save(context, { ...record, phase: 'active', reason: null });
+  }
+
+  private async rollback(context: Context, record: MigrationRecord): Promise<void> {
+    if (record.phase === 'recovering') return this.finishRecovery(context, record);
+    if (record.grantImported === true) throw new MigrationBlocked('finish_forward', 'Central owns this OAuth grant. Finish forward or sign in centrally; the old local tokens cannot be restored.');
+    const begun = await this.call(context, record, 'begin');
+    if (begun.migration.grantImported === true) {
+      record = this.accept(context, record, begun.migration);
+      this.save(context, { ...record, phase: begun.migration.phase === 'active' ? 'cutover' : 'prepared', reason: 'finish_forward' });
+      return;
+    }
+    if (record.phase !== 'freezing') this.source(record);
+    record = this.save(context, { ...record, phase: 'rollback' });
+    if (this.waiting(context, record, true)) return;
+    const { migration } = await this.call(context, record, 'rollback');
+    if (migration.phase !== 'rolled_back') {
+      this.accept(context, record, migration);
+      return;
+    }
+    this.check(context, record);
+    this.restore(context, record);
+
+  }
+
+  private restore(context: Context, record: MigrationRecord): void {
+    const signOut = record.auth === 'oauth' && record.move !== true;
+    if (this.deps.restore !== undefined) this.deps.restore(record.sourceId, signOut);
+    else localRollbackMigrationSource(record.sourceId, signOut, this.dir);
+    this.save(context, { ...record, phase: 'rolled_back', reason: signOut ? 'sign_in' : null });
+  }
+
+  private async reconcile(context: Context, record: MigrationRecord): Promise<void> {
+    if (record.phase === 'recovering') return this.finishRecovery(context, record);
+    if (record.phase === 'rollback') return this.rollback(context, record);
+    if (record.move === true && record.phase !== 'active' && record.phase !== 'rolled_back') return this.move(context, record);
+    if (record.phase === 'preparing') return this.prepare(context, record);
+    if (record.phase === 'cutover') return this.cutover(context, record);
+    if (record.phase === 'rolled_back') return;
+    const { migration } = await this.call(context, record, 'status');
+    this.accept(context, record, migration);
+  }
+
+  private obtain(context: Context, sourceId: string, action: MigrationAction, oauthResource?: string): MigrationRecord | null {
+    const record = migrationRecord(sourceId, this.dir);
+    if (record !== null) this.check(context, record);
+    if (['prepare', 'move'].includes(action) && (record === null || record.phase === 'rolled_back')) return this.create(context, sourceId, oauthResource, action === 'move');
+    if (action === 'move' && record !== null && canUpgrade(record)) return this.save(context, { ...record, move: true, phase: 'freezing' });
+    if (record === null && action !== 'reconcile') throw conflict('Prepare this connector before moving it.');
+    return record;
+  }
+
+  private perform(context: Context, record: MigrationRecord, action: MigrationAction): Promise<void> {
+    if (action === 'move') return this.move(context, record);
+    if (action === 'prepare' && record.phase === 'preparing') return this.prepare(context, record);
+    if (action === 'cutover' && (record.phase === 'prepared' || record.phase === 'cutover')) return this.cutover(context, record);
+    if (action === 'rollback' && record.phase !== 'rolled_back') return this.rollback(context, record);
+    return this.reconcile(context, record);
+  }
+
+  private async resolve(context: Context, record: MigrationRecord, receipt: string | null): Promise<void> {
+    this.check(context, record);
+    if (receipt === null || receipt !== migrationUncertaintyReceipt(record.sourceId, this.dir)) throw conflict('The outstanding request receipt changed. Refresh before confirming that vendor requests have settled.');
+    localMigrationIdle(record.sourceId, this.dir, true);
+    if (migrationRefreshUncertain(record.sourceId, this.dir)) return this.recoverRefresh(context, record, receipt);
+    if (!resolveMigrationUncertainty(record.sourceId, receipt, this.dir)) throw conflict('Requests are still running or their receipt changed. Wait for vendor completion, then refresh before confirming settlement.');
+    this.save(context, { ...record, reason: record.phase === 'prepared' ? 'not_verified' : null });
+  }
+
+  private async recoverRefresh(context: Context, record: MigrationRecord, receipt: string): Promise<void> {
+    if (record.move !== true || !['freezing', 'rollback'].includes(record.phase) || !migrationOperationsIdle(record.sourceId, this.dir, false)) throw conflict('The uncertain local refresh must stop before aborting the handover.');
+    const { migration } = await this.call(context, record, 'rollback');
+    if (migration.phase !== 'rolled_back') throw uncertain();
+    record = this.save(context, { ...record, phase: 'recovering', recoveryReceipt: receipt });
+    await this.finishRecovery(context, record);
+  }
+
+  private async finishRecovery(context: Context, record: MigrationRecord): Promise<void> {
+    const { migration } = await this.call(context, record, 'rollback');
+    if (migration.phase !== 'rolled_back' || record.recoveryReceipt === undefined) throw uncertain();
+    localRollbackMigrationSource(record.sourceId, true, this.dir, true);
+    const receipt = migrationUncertaintyReceipt(record.sourceId, this.dir);
+    if (receipt !== null && !resolveMigrationUncertainty(record.sourceId, record.recoveryReceipt, this.dir)) throw uncertain();
+    this.save(context, { ...record, phase: 'rolled_back', recoveryReceipt: undefined, reason: 'sign_in' });
+  }
+
+  private validateResource(sourceId: string, action: MigrationAction, oauthResource: string | undefined): void {
+    if (oauthResource === undefined) return;
+    const resource = publicOAuthResource(oauthResource);
+    const record = migrationRecord(sourceId, this.dir);
+    if (action === 'prepare' && (record === null || record.phase === 'rolled_back')) return;
+    if (record?.oauthResource !== resource) throw conflict('The public OAuth resource is fixed for this preparation. Roll back, then prepare again to change it.');
+  }
+
+  private validateIntent(sourceId: string, action: MigrationAction, operationId: string | null, receipt: string | null): void {
+    if ((migrationRecord(sourceId, this.dir)?.id ?? null) !== operationId) throw conflict('This connector migration changed. Refresh before acting on its current operation.');
+    if (action === 'resolve' && (receipt === null || receipt !== migrationUncertaintyReceipt(sourceId, this.dir))) throw conflict('The outstanding request receipt changed. Refresh before confirming that vendor requests have settled.');
+  }
+
+  async run(sourceId: string, action: MigrationAction, scope: string, operationId: string | null, uncertainty: string | null = null, oauthResource?: string): Promise<MigrationStatus> {
+    if (this.running) throw conflict('Another migration request is still running on this agent. Refresh after it finishes.');
+    const context = this.context(scope, ['move', 'prepare', 'cutover'].includes(action));
+    this.validateIntent(sourceId, action, operationId, uncertainty);
+    this.validateResource(sourceId, action, oauthResource);
+    this.running = true;
+    try {
+      const record = this.obtain(context, sourceId, action, oauthResource);
+      if (record !== null) {
+        if (action === 'resolve') await this.resolve(context, record, uncertainty);
+        else await this.perform(context, record, action);
+      }
+      this.check(context);
+      return this.status();
+    } catch (error) {
+      const record = migrationRecord(sourceId, this.dir);
+      if (record !== null) {
+        try { this.save(context, { ...record, reason: error instanceof MigrationBlocked ? error.reason : 'unavailable' }); } catch {
+          log.warn('connector migration: the interrupted operation needs reconciliation in its original enrollment');
+        }
+      }
+      throw error;
+    } finally { this.running = false; }
+  }
+}