@stage-labs/metro 0.1.0-beta.289 → 0.1.0-beta.290

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.289",
+  "version": "0.1.0-beta.290",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.289",
+  "version": "0.1.0-beta.290",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

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

@@ -20,23 +20,25 @@ export interface ConnectorGate {
 }
 
 let gates: ConnectorGate[] = [];
+let managed = new Set<string>();
 
 const normalized = (name: string): string => name.replace(/[^a-zA-Z0-9_-]/g, '_');
 
-function approvalChanged(gate: ConnectorGate, tool: string, next: GateRow | undefined, keys: Map<string, string>): boolean {
+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[]): void {
-  const keys = serverKeysOf([...rows]);
+export function registerConnectors(rows: readonly GateRow[], managedIds: readonly string[] = [], keys: ReadonlyMap<string, string> = serverKeysOf([...rows])): void {
+  const nextManaged = new Set(managedIds);
   revokeToolPrompts((tool) => {
     const found = connectorToolOf(tool);
-    if (found === undefined || !isOrgRelayId(found.gate.id)) return false;
+    if (found === undefined || (!isOrgRelayId(found.gate.id) && !managed.has(found.gate.id) && !nextManaged.has(found.gate.id))) return false;
     return approvalChanged(found.gate, found.tool, rows.find((row) => row.id === found.gate.id), keys);
   });
+  managed = nextManaged;
   gates = rows.map((row) => ({
     id: row.id,
     name: row.name,

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

@@ -0,0 +1,55 @@
+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 type { ConnectorMigrations, MigrationAction } from './migration-control.js';
+
+const PATH = '/api/connectors/migrations';
+const actions: readonly MigrationAction[] = ['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;
+}
+
+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'].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) };
+}
+
+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 } = inputOf(body);
+    return deps.run(sourceId, action, scope, operationId, uncertainty);
+  });
+}

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

@@ -0,0 +1,269 @@
+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 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, type MetroApi } from './metro-api.js';
+import { migrationSource } from './migration-preview.js';
+import { migrationPayload } from './migration-source.js';
+import { localMigrationIdle } from './migration-guard.js';
+import { migrationUncertaintyReceipt, resolveMigrationUncertainty } from './migration-operations.js';
+import { 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 = '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;
+}
+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 }: MigrationRecord, uncertainty: string | null): MigrationView => ({ id, sourceId, name, destinationId, phase, auth, reason, uncertainty });
+const reasons: Record<RemoteMigration['readiness'], string | null> = { pending: 'not_verified', ready: null, signin: 'sign_in', changed: 'destination_changed', unavailable: 'unavailable' };
+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());
+
+function received(record: MigrationRecord, snapshot: DeliverySnapshot): boolean {
+  const delivered = snapshot.connectors.find((row) => row.id === record.destinationId);
+  return delivered?.state === 'ready' && delivered.name === record.name && samePolicy(delivered.policy, record.policy);
+}
+
+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 : '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));
+    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' | '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 {
+      throw uncertain();
+    }
+    this.check(context, record);
+    const remote = response.migration;
+    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) throw conflict('The prepared destination no longer matches this local connector. Roll back this preparation before trying again.');
+    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, reason: reasons[remote.readiness] });
+  }
+
+  private create(context: Context, id: string): MigrationRecord {
+    const payload = migrationPayload(migrationSource(id, this.dir));
+    return this.save(context, {
+      id: newId(), owner: context.owner, agentId: context.agentId, keyId: context.key.keyId,
+      sourceId: id, name: payload.name, destinationId: null, phase: 'preparing', auth: payload.auth.kind,
+      sourceStamp: payload.sourceStamp, policy: payload.policy, reason: null,
+    });
+  }
+
+  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') {
+      this.save(context, { ...record, phase: 'prepared' });
+      return;
+    }
+    if (begun.migration.phase !== 'preparing' || 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, 'prepare', sealed);
+    record = this.accept(context, record, migration);
+    if (migration.phase !== 'prepared') throw uncertain();
+    this.save(context, { ...record, phase: 'prepared' });
+  }
+
+  private waiting(context: Context, record: MigrationRecord, includeOrganization = false): boolean {
+    const uncertain = migrationUncertaintyReceipt(record.sourceId, this.dir) !== null;
+    if (!uncertain && this.localIdle(record.sourceId) && (!includeOrganization || this.orgIdle(record.sourceId))) return false;
+    this.save(context, { ...record, reason: 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> {
+    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);
+    if (this.deps.restore !== undefined) this.deps.restore(record.sourceId, record.auth === 'oauth');
+    else localRollbackMigrationSource(record.sourceId, record.auth === 'oauth', this.dir);
+    this.save(context, { ...record, phase: 'rolled_back', reason: record.auth === 'oauth' ? 'sign_in' : null });
+  }
+
+  private async reconcile(context: Context, record: MigrationRecord): Promise<void> {
+    if (record.phase === 'preparing') return this.prepare(context, record);
+    if (record.phase === 'cutover') return this.cutover(context, record);
+    if (record.phase === 'rollback') return this.rollback(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): MigrationRecord | null {
+    const record = migrationRecord(sourceId, this.dir);
+    if (record !== null) this.check(context, record);
+    if (action === 'prepare' && (record === null || record.phase === 'rolled_back')) return this.create(context, sourceId);
+    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 === '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 resolve(context: Context, record: MigrationRecord, receipt: string | null): 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.');
+    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 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): 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, action === 'prepare' || action === 'cutover');
+    this.validateIntent(sourceId, action, operationId, uncertainty);
+    this.running = true;
+    try {
+      const record = this.obtain(context, sourceId, action);
+      if (record !== null) {
+        if (action === 'resolve') 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: 'unavailable' }); } catch {
+          log.warn('connector migration: the interrupted operation needs reconciliation in its original enrollment');
+        }
+      }
+      throw error;
+    } finally { this.running = false; }
+  }
+}

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

@@ -0,0 +1,90 @@
+import { ApiError } from '@metro-labs/http/api-error';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { agentsDir } from '../agents/files.js';
+import type { AgentKey } from './agent-key.js';
+import { migrationRecord, migrationRecords } from './migration-state.js';
+import { assertMigrationOutcomeKnown, beginMigrationOperation, migrationOperationsIdle, migrationRequestEffectful, type MigrationOperation } from './migration-operations.js';
+
+const locked = (phase: string): boolean => phase !== 'rolled_back';
+const retired = (phase: string): boolean => phase === 'cutover' || phase === 'active' || phase === 'rollback';
+const refused = (): ApiError => new ApiError('This local connector is locked while it moves to the organization.', 409);
+
+export function migrationSource(id: string, dir = agentsDir()): ReturnType<typeof migrationRecords>[number] | null {
+  const record = migrationRecord(id, dir);
+  return record !== null && locked(record.phase) ? record : null;
+}
+
+export function localMigrationEnabled(id: string, dir = agentsDir()): boolean {
+  const record = migrationSource(id, dir);
+  return record === null || !retired(record.phase);
+}
+
+export function assertLocalMigrationUse(id: string, dir = agentsDir()): void {
+  const record = migrationSource(id, dir);
+  if (record === null) return;
+  if (retired(record.phase)) throw refused();
+  assertMigrationOutcomeKnown(id, dir);
+}
+
+export function assertLocalMigrationEdit(id: string, name: string | undefined, dir = agentsDir()): void {
+  if (migrationRecords(dir).some((record) => locked(record.phase) && (record.sourceId === id || record.name === name))) throw refused();
+}
+
+export function migrationExportableRows<T extends { id: string; name: string }>(rows: readonly T[], dir = agentsDir()): T[] {
+  const records = migrationRecords(dir).filter((record) => locked(record.phase));
+  return rows.filter((row) => !records.some((record) => record.sourceId === row.id || record.name === row.name));
+}
+
+export function localMigrationIdle(id: string, dir = agentsDir()): boolean {
+  return migrationOperationsIdle(id, dir, migrationSource(id, dir) !== null);
+}
+
+export interface LocalMigrationOperation extends MigrationOperation {
+  check: () => void;
+  fetch: FetchLike;
+  close: () => void;
+}
+
+export function beginLocalMigrationOperation(id: string, dir = agentsDir(), edit = false, name?: string): LocalMigrationOperation {
+  let closed = false;
+  const check = (): void => {
+    if (closed) throw refused();
+    if (edit) assertLocalMigrationEdit(id, name, dir);
+    else assertLocalMigrationUse(id, dir);
+  };
+  check();
+  const tracked = beginMigrationOperation(id, dir, migrationSource(id, dir) !== null);
+  const dispatch: MigrationOperation['dispatch'] = (send, options) => {
+    check();
+    return tracked.dispatch(send, { ...options, protectedSource: migrationSource(id, dir) !== null });
+  };
+  return {
+    check,
+    dispatch,
+    fetch: (input, init) => dispatch(() => fetch(input, init), { effectful: migrationRequestEffectful(init?.method, init?.body) }),
+    close: () => { closed = true; tracked.close(); },
+  };
+}
+
+export async function withLocalMigrationOperation<T>(id: string, dir: string, run: (operation: LocalMigrationOperation) => Promise<T>, edit = false, name?: string): Promise<T> {
+  const operation = beginLocalMigrationOperation(id, dir, edit, name);
+  try { return await run(operation); }
+  finally { operation.close(); }
+}
+
+export interface MigrationRuntimeMapping {
+  aliases: { sourceId: string; destinationId: string; name: string }[];
+  reserved: string[];
+}
+
+export function migrationRuntimeMapping(owner: string | null, key: AgentKey | null, dir = agentsDir()): MigrationRuntimeMapping {
+  const records = migrationRecords(dir).filter((record) => locked(record.phase));
+  const aliases = records.flatMap((record) => {
+    if (record.phase !== 'active' || record.destinationId === null || owner === null || key === null) return [];
+    if (record.owner !== owner || record.keyId !== key.keyId || record.owner !== key.enrollment?.organization || record.agentId !== key.enrollment.server) return [];
+    return [{ sourceId: record.sourceId, destinationId: record.destinationId, name: record.name }];
+  });
+  const reserved = records.flatMap((record) => record.destinationId === null ? [] : [record.destinationId]);
+  if (new Set(aliases.map((alias) => alias.sourceId)).size !== aliases.length || new Set(reserved).size !== reserved.length) throw refused();
+  return { aliases, reserved };
+}

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

@@ -0,0 +1,196 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { parseId } from '@metro-labs/core/ids';
+import { ensureSecureDir, writeSecure } from '@metro-labs/core/secure-fs';
+import { ApiError } from '@metro-labs/http/api-error';
+import { agentsDir } from '../agents/files.js';
+
+interface RequestOperation {
+  id: string;
+  source: string;
+  dir: string;
+  lease: string;
+  durable: boolean;
+  abandoned: boolean;
+}
+
+export interface MigrationOperation {
+  dispatch: (send: () => Promise<Response>, options?: { protectedSource?: boolean; effectful?: boolean }) => Promise<Response>;
+  close: () => void;
+}
+
+const leases = new Map<string, Set<string>>();
+const requests = new Map<string, RequestOperation>();
+const held = new Map<string, RequestOperation>();
+const keyOf = (source: string, dir: string): string => JSON.stringify([resolve(dir), source]);
+const unavailable = (): ApiError => new ApiError('Protected connector request records cannot be read. Restore their files before using this connector.', 503);
+const uncertain = (): ApiError => new ApiError('A previous connector request has an unknown outcome. Inspect the vendor and acknowledge it before continuing. Do not retry the tool.', 409);
+const CONTROL = new Set(['initialize', 'ping', 'tools/list', 'notifications/initialized', 'notifications/cancelled']);
+
+export function migrationRequestEffectful(method: string | undefined, body: unknown): boolean {
+  const verb = (method ?? 'GET').toUpperCase();
+  if (['GET', 'HEAD', 'DELETE'].includes(verb)) return false;
+  if (verb !== 'POST') return true;
+  const text = typeof body === 'string' ? body : body instanceof Uint8Array ? new TextDecoder().decode(body) : null;
+  if (text === null) return true;
+  try {
+    const value: unknown = JSON.parse(text);
+    const batch: unknown[] = Array.isArray(value) ? value : [value];
+    return batch.length === 0 || batch.some((item) => !isRecord(item) || item.jsonrpc !== '2.0' || typeof item.method !== 'string' || !CONTROL.has(item.method));
+  } catch { return true; }
+}
+
+function paths(source: string, dir: string): { data: string; marker: string } {
+  if (parseId(source) === null) throw unavailable();
+  const data = join(dir, `connector-migration-operations-${source}.json`);
+  return { data, marker: `${data}.initialized` };
+}
+
+function flush(path: string): void {
+  const fd = openSync(path, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function pendingOf(text: string): string[] {
+  const value: unknown = JSON.parse(text);
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.pending) || value.pending.length > 10_000) throw unavailable();
+  const ids: unknown[] = value.pending;
+  if (!ids.every((id): id is string => typeof id === 'string' && /^[a-f0-9]{32}$/.test(id))) throw unavailable();
+  if (new Set(ids).size !== ids.length) throw unavailable();
+  return ids;
+}
+
+function readPending(source: string, dir: string, initialize = false): string[] {
+  const { data, marker } = paths(source, dir);
+  try {
+    if (initialize && !existsSync(data) && !existsSync(marker)) return [];
+    if (readFileSync(marker, 'utf8') !== '1\n') throw unavailable();
+    return pendingOf(readFileSync(data, 'utf8'));
+  } catch { throw unavailable(); }
+}
+
+function writePending(source: string, dir: string, pending: string[]): void {
+  const { data, marker } = paths(source, dir);
+  ensureSecureDir(dir);
+  if (!existsSync(marker)) {
+    writeFileSync(marker, '1\n', { flag: 'wx', mode: 0o600 });
+    flush(marker);
+    flush(dir);
+  }
+  writeSecure(data, `${JSON.stringify({ version: 1, pending })}\n`);
+  flush(data);
+  flush(dir);
+}
+
+export function captureMigrationOperations(source: string, dir: string, initialize: boolean): void {
+  const pending = new Set(readPending(source, dir, initialize));
+  const active = [...held.values()].filter((request) => keyOf(request.source, request.dir) === keyOf(source, dir));
+  for (const request of active) pending.add(request.id);
+  writePending(source, dir, [...pending]);
+  for (const request of active) request.durable = true;
+}
+
+export function migrationUncertaintyReceipt(source: string, dir = agentsDir()): string | null {
+  const unknown = readPending(source, dir).filter((id) => !requests.has(id)).sort();
+  return unknown.length === 0 ? null : createHash('sha256').update(JSON.stringify([1, source, unknown])).digest('hex');
+}
+
+export function assertMigrationOutcomeKnown(source: string, dir = agentsDir()): void {
+  if (migrationUncertaintyReceipt(source, dir) !== null) throw uncertain();
+}
+
+export function migrationOperationsIdle(source: string, dir: string, protectedSource: boolean): boolean {
+  if (leases.has(keyOf(source, dir))) return false;
+  return !protectedSource || readPending(source, dir).length === 0;
+}
+
+export function resolveMigrationUncertainty(source: string, expectedReceipt: string, dir = agentsDir()): boolean {
+  if (leases.has(keyOf(source, dir))) return false;
+  const receipt = migrationUncertaintyReceipt(source, dir);
+  if (receipt === null || receipt !== expectedReceipt) return false;
+  writePending(source, dir, []);
+  return true;
+}
+
+function finish(request: RequestOperation, completed: boolean): void {
+  if (request.abandoned) return;
+  requests.delete(request.id);
+  if (completed) held.delete(request.id);
+  if (completed && request.durable) writePending(request.source, request.dir, readPending(request.source, request.dir).filter((id) => id !== request.id));
+  request.abandoned = true;
+}
+
+function observed(response: Response, request: RequestOperation): Response {
+  if (response.status === 401 || response.status === 403) {
+    finish(request, true);
+    return response;
+  }
+  if (response.body === null) {
+    finish(request, response.ok);
+    return response;
+  }
+  const reader = response.body.getReader();
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          finish(request, response.ok);
+          controller.close();
+        } else controller.enqueue(result.value);
+      } catch (error) {
+        finish(request, false);
+        controller.error(error);
+      }
+    },
+    async cancel(reason: unknown) {
+      finish(request, false);
+      await reader.cancel(reason);
+    },
+  });
+  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+
+async function dispatch(source: string, dir: string, lease: string, protectedSource: boolean, effectful: boolean, send: () => Promise<Response>): Promise<Response> {
+  if (protectedSource) assertMigrationOutcomeKnown(source, dir);
+  if (!effectful) return send();
+  const request: RequestOperation = { id: randomBytes(16).toString('hex'), source, dir, lease, durable: false, abandoned: false };
+  if (protectedSource) {
+    const pending = readPending(source, dir);
+    if (pending.length >= 10_000) throw unavailable();
+    writePending(source, dir, [...pending, request.id]);
+    request.durable = true;
+  }
+  requests.set(request.id, request);
+  held.set(request.id, request);
+  try { return observed(await send(), request); }
+  catch (error) { finish(request, false); throw error; }
+}
+
+export function beginMigrationOperation(source: string, dir: string, protectedSource: boolean): MigrationOperation {
+  if (protectedSource) assertMigrationOutcomeKnown(source, dir);
+  const key = keyOf(source, dir);
+  const lease = randomBytes(16).toString('hex');
+  const active = leases.get(key) ?? new Set<string>();
+  active.add(lease);
+  leases.set(key, active);
+  let closed = false;
+  return {
+    dispatch: (send, options = {}) => {
+      if (closed) return Promise.reject(uncertain());
+      return dispatch(source, dir, lease, options.protectedSource ?? protectedSource, options.effectful ?? true, send);
+    },
+    close: () => {
+      if (closed) return;
+      closed = true;
+      for (const request of held.values()) if (request.lease === lease) {
+        finish(request, false);
+        held.delete(request.id);
+      }
+      active.delete(lease);
+      if (active.size === 0) leases.delete(key);
+    },
+  };
+}