@stage-labs/metro 0.1.0-beta.291 → 0.1.0-beta.292

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.291",
+  "version": "0.1.0-beta.292",
   "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.291",
+  "version": "0.1.0-beta.292",
   "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/config.ts

@@ -44,6 +44,8 @@ function readOAuth(raw: Record<string, unknown>): ConnectorAuth {
     clientId,
     tokenEndpoint,
     issuer: stringOf(raw.issuer),
+    ...(typeof raw.resource === 'string' ? { resource: raw.resource } : {}),
+    ...(typeof raw.tokenEndpointAuthMethod === 'string' ? { tokenEndpointAuthMethod: raw.tokenEndpointAuthMethod } : {}),
     ...(refreshToken === '' ? {} : { refreshToken }),
     ...(clientSecret === '' ? {} : { clientSecret }),
     ...(scope === '' ? {} : { scope }),

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

@@ -7,7 +7,7 @@ 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[] = ['prepare', 'reconcile', 'cutover', 'rollback', 'resolve'];
+const actions: readonly MigrationAction[] = ['move', 'prepare', 'reconcile', 'cutover', 'rollback', 'resolve'];
 export type MigrationApiDeps = Pick<ConnectorMigrations, 'status' | 'run'>;
 
 interface MigrationInput {

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

@@ -9,17 +9,19 @@ 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 { migrationPayload } from './migration-source.js';
+import { MigrationBlocked, migrationPayload } from './migration-source.js';
 import { localMigrationIdle } from './migration-guard.js';
-import { migrationUncertaintyReceipt, resolveMigrationUncertainty } from './migration-operations.js';
-import { localRollbackMigrationSource } from './store.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 = 'prepare' | 'reconcile' | 'cutover' | 'rollback' | 'resolve';
+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;
@@ -44,12 +46,23 @@ interface MigrationDeps {
 
 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 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 destination already has credentials, a name conflict 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);
   }
@@ -82,7 +95,7 @@ export class ConnectorMigrations {
     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';
+      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 };
@@ -111,12 +124,12 @@ export class ConnectorMigrations {
   }
 
   private source(record: MigrationRecord): ReturnType<typeof migrationPayload> {
-    const payload = migrationPayload(migrationSource(record.sourceId, this.dir), record.oauthResource);
+    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' | 'status' | 'activate' | 'rollback', sealed?: ReturnType<typeof sealConnectorMigration>): Promise<MigrationResponse> {
+  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 {
@@ -127,9 +140,7 @@ export class ConnectorMigrations {
       throw callFailure(error, action);
     }
     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.');
+    checkResponse(record, response.migration);
     return response;
   }
 
@@ -137,14 +148,14 @@ export class ConnectorMigrations {
     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] });
+    return this.save(context, { ...record, destinationId: remote.destinationId, grantImported: remote.grantImported === true, reason: reasons[remote.readiness] });
   }
 
-  private create(context: Context, id: string, oauthResource?: string): MigrationRecord {
+  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: 'preparing', auth: payload.auth.kind,
+      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 }),
     });
@@ -154,25 +165,53 @@ export class ConnectorMigrations {
     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') {
+    if (begun.migration.phase === 'prepared' && !upgrading(record, begun.migration)) {
       this.save(context, { ...record, phase: 'prepared' });
       return;
     }
-    if (begun.migration.phase !== 'preparing' || begun.receiving === undefined) throw uncertain();
+    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, 'prepare', sealed);
+    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;
     if (!uncertain && this.localIdle(record.sourceId) && (!includeOrganization || this.orgIdle(record.sourceId))) return false;
-    this.save(context, { ...record, reason: uncertain ? 'requests_uncertain' : 'waiting_for_local' });
+    this.save(context, { ...record, reason: uncertain ? migrationRefreshUncertain(record.sourceId, this.dir) ? 'local_refresh_uncertain' : 'requests_uncertain' : 'waiting_for_local' });
     return true;
   }
 
@@ -202,7 +241,15 @@ export class ConnectorMigrations {
   }
 
   private async rollback(context: Context, record: MigrationRecord): Promise<void> {
-    this.source(record);
+    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');
@@ -211,15 +258,23 @@ export class ConnectorMigrations {
       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 });
+    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 === '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);
@@ -228,25 +283,45 @@ export class ConnectorMigrations {
   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 (action === 'prepare' && (record === null || record.phase === 'rolled_back')) return this.create(context, sourceId, oauthResource);
+    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 resolve(context: Context, record: MigrationRecord, receipt: string | null): void {
+  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.');
+    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);
@@ -262,14 +337,14 @@ export class ConnectorMigrations {
 
   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, action === 'prepare' || action === 'cutover');
+    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') this.resolve(context, record, uncertainty);
+        if (action === 'resolve') await this.resolve(context, record, uncertainty);
         else await this.perform(context, record, action);
       }
       this.check(context);
@@ -277,7 +352,7 @@ export class ConnectorMigrations {
     } catch (error) {
       const record = migrationRecord(sourceId, this.dir);
       if (record !== null) {
-        try { this.save(context, { ...record, reason: 'unavailable' }); } catch {
+        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');
         }
       }

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

@@ -6,7 +6,7 @@ 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 retired = (record: NonNullable<ReturnType<typeof migrationRecord>>): boolean => record.move === true || record.phase === 'cutover' || record.phase === 'active' || record.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 {
@@ -16,13 +16,13 @@ export function migrationSource(id: string, dir = agentsDir()): ReturnType<typeo
 
 export function localMigrationEnabled(id: string, dir = agentsDir()): boolean {
   const record = migrationSource(id, dir);
-  return record === null || !retired(record.phase);
+  return record === null || !retired(record);
 }
 
 export function assertLocalMigrationUse(id: string, dir = agentsDir()): void {
   const record = migrationSource(id, dir);
   if (record === null) return;
-  if (retired(record.phase)) throw refused();
+  if (retired(record)) throw refused();
   assertMigrationOutcomeKnown(id, dir);
 }
 
@@ -35,8 +35,8 @@ export function migrationExportableRows<T extends { id: string; name: string }>(
   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 function localMigrationIdle(id: string, dir = agentsDir(), allowUncertain = false): boolean {
+  return migrationOperationsIdle(id, dir, !allowUncertain && migrationSource(id, dir) !== null);
 }
 
 export interface LocalMigrationOperation extends MigrationOperation {
@@ -61,6 +61,7 @@ export function beginLocalMigrationOperation(id: string, dir = agentsDir(), edit
   return {
     check,
     dispatch,
+    persistedRefresh: tracked.persistedRefresh,
     fetch: (input, init) => dispatch(() => fetch(input, init), { effectful: migrationRequestEffectful(init?.method, init?.body) }),
     close: () => { closed = true; tracked.close(); },
   };

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

@@ -14,11 +14,13 @@ interface RequestOperation {
   lease: string;
   durable: boolean;
   abandoned: boolean;
+  refresh: boolean;
 }
 
 export interface MigrationOperation {
-  dispatch: (send: () => Promise<Response>, options?: { protectedSource?: boolean; effectful?: boolean }) => Promise<Response>;
+  dispatch: (send: () => Promise<Response>, options?: { protectedSource?: boolean; effectful?: boolean; refresh?: boolean }) => Promise<Response>;
   close: () => void;
+  persistedRefresh: () => void;
 }
 
 const leases = new Map<string, Set<string>>();
@@ -57,7 +59,7 @@ 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 (!ids.every((id): id is string => typeof id === 'string' && /^r?[a-f0-9]{32}$/.test(id))) throw unavailable();
   if (new Set(ids).size !== ids.length) throw unavailable();
   return ids;
 }
@@ -114,7 +116,8 @@ export function resolveMigrationUncertainty(source: string, expectedReceipt: str
   return true;
 }
 
-function finish(request: RequestOperation, completed: boolean): void {
+function finish(request: RequestOperation, completed: boolean, persisted = false): void {
+  if (request.refresh && completed && !persisted) return;
   if (request.abandoned) return;
   requests.delete(request.id);
   if (completed) held.delete(request.id);
@@ -153,10 +156,10 @@ function observed(response: Response, request: RequestOperation): Response {
   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> {
+async function dispatch(source: string, dir: string, lease: string, protectedSource: boolean, effectful: boolean, refresh: 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 };
+  const request: RequestOperation = { id: `${refresh ? 'r' : ''}${randomBytes(16).toString('hex')}`, source, dir, lease, durable: false, abandoned: false, refresh };
   if (protectedSource) {
     const pending = readPending(source, dir);
     if (pending.length >= 10_000) throw unavailable();
@@ -180,7 +183,10 @@ export function beginMigrationOperation(source: string, dir: string, protectedSo
   return {
     dispatch: (send, options = {}) => {
       if (closed) return Promise.reject(uncertain());
-      return dispatch(source, dir, lease, options.protectedSource ?? protectedSource, options.effectful ?? true, send);
+      return dispatch(source, dir, lease, options.protectedSource ?? protectedSource, options.effectful ?? true, options.refresh ?? false, send);
+    },
+    persistedRefresh: () => {
+      for (const request of held.values()) if (request.lease === lease && request.refresh) finish(request, true, true);
     },
     close: () => {
       if (closed) return;
@@ -194,3 +200,7 @@ export function beginMigrationOperation(source: string, dir: string, protectedSo
     },
   };
 }
+
+export function migrationRefreshUncertain(source: string, dir = agentsDir()): boolean {
+  return readPending(source, dir).some((id) => id.startsWith('r') && !requests.has(id));
+}

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

@@ -5,6 +5,7 @@ import { isRecord } from '@metro-labs/core/is-record';
 import { ApiError } from '@metro-labs/http/api-error';
 import { bodyField } from '@metro-labs/http/api-http';
 import { connectorAuth, connectorClient, connectorName } from '@metro-labs/http/connector-input';
+import { portableGrant } from '@metro-labs/http/connector-grant';
 import { connectorPolicyOf } from '@metro-labs/http/connector-delivery';
 import { readConfig } from './config.js';
 import type { LocalConnectorRow } from './store.js';
@@ -12,9 +13,10 @@ import { agentsDir } from '../agents/files.js';
 import { normalizePolicy, type ToolPolicy } from '../policy/policy.js';
 import { connectorSyncScope, syncOptedIn, syncSetting } from './org-sync-setting.js';
 import { readAgentKey } from './agent-key.js';
+import { MigrationBlocked } from './migration-source.js';
 import { migrationOrigin } from './migration-url.js';
 
-export type MigrationIssue = 'invalid_config' | 'unsupported_url' | 'custom_policy' | 'oauth_sign_in' | 'header_reentry' | 'unused_oauth_client';
+export type MigrationIssue = 'invalid_config' | 'unsupported_url' | 'custom_policy' | 'oauth_sign_in' | 'header_reentry' | 'unused_oauth_client' | 'oauth_unsupported';
 
 export interface MigrationConnector {
   id: string;
@@ -29,6 +31,7 @@ export interface MigrationConnector {
 export interface ConnectorMigrationPreview {
   migrationSupported: true;
   oauthResourceSupported: true;
+  moveAllSupported: true;
   enabled: boolean;
   enrolled: boolean;
   agentId: string | null;
@@ -54,7 +57,7 @@ function validClient(raw: unknown): boolean {
 }
 
 function oauthAuth(raw: Record<string, unknown>): 'oauth' {
-  if (!onlyKeys(raw, ['kind', 'accessToken', 'refreshToken', 'clientId', 'clientSecret', 'tokenEndpoint', 'issuer', 'scope', 'expiresAt'])) invalid();
+  if (!onlyKeys(raw, ['kind', 'accessToken', 'refreshToken', 'clientId', 'clientSecret', 'tokenEndpoint', 'issuer', 'scope', 'expiresAt', 'resource', 'tokenEndpointAuthMethod'])) invalid();
   return 'oauth';
 }
 
@@ -145,8 +148,17 @@ function rowIdentity(row: Record<string, unknown>, index: number): { id: string;
   return { id: id ?? `invalid-${String(index + 1)}`, name: name ?? `Connector ${String(index + 1)}`, valid: id !== null && name !== null };
 }
 
+function grantIssues(row: Record<string, unknown>): MigrationIssue[] {
+  const grant = bodyField(row.config, 'auth');
+  if (!isRecord(grant) || grant.kind !== 'oauth') return ['oauth_sign_in'];
+  try {
+    const portable = portableGrant(grant, String(row.url));
+    return portable.expiresAt !== undefined && portable.expiresAt <= Date.now() && portable.refreshToken === undefined ? ['oauth_sign_in'] : [];
+  } catch { return ['oauth_unsupported']; }
+}
+
 function authIssues(row: Record<string, unknown>, auth: MigrationConnector['auth']): MigrationIssue[] {
-  if (auth === 'oauth') return ['oauth_sign_in'];
+  if (auth === 'oauth') return grantIssues(row);
   const client = bodyField(row.config, 'client');
   return (auth === 'none' || auth === 'header') && client !== undefined && client !== null ? ['unused_oauth_client'] : [];
 }
@@ -200,10 +212,16 @@ function previewRows(dir: string): MigrationConnector[] {
   return rows;
 }
 
-export function migrationSource(id: string, dir = agentsDir()): LocalConnectorRow {
+function assertTransferable(source: MigrationConnector): void {
+  if (source.issues.includes('oauth_sign_in')) throw new MigrationBlocked('sign_in', 'No usable local OAuth grant is saved. Sign in locally before moving it.');
+  if (source.issues.includes('oauth_unsupported')) throw new MigrationBlocked('unsupported_grant', 'This OAuth grant has unsupported client authentication or provider binding. Keep it local or sign in separately.');
+}
+
+export function migrationSource(id: string, dir = agentsDir(), transfer = false): LocalConnectorRow {
   const source = previewRows(dir).find((row) => row.id === id);
   if (source === undefined) throw new ApiError('The local connector is missing.', 404);
-  if (source.issues.some((issue) => issue !== 'oauth_sign_in')) throw new ApiError('This connector cannot be migrated without changing its settings or permissions. Resolve the preview blockers first.', 409);
+  if (source.issues.some((issue) => issue !== 'oauth_sign_in' && issue !== 'oauth_unsupported')) throw new ApiError('This connector cannot be migrated without changing its settings or permissions. Resolve the preview blockers first.', 409);
+  if (transfer) assertTransferable(source);
   const raw = readRows(dir).find((row) => isRecord(row) && row.id === id);
   if (!isRecord(raw) || typeof raw.url !== 'string') throw unavailable();
   return { id, name: source.name, url: raw.url, config: { ...readConfig(raw.config), oauth: source.auth === 'oauth', policy: source.policy } };
@@ -212,8 +230,8 @@ export function migrationSource(id: string, dir = agentsDir()): LocalConnectorRo
 export function connectorMigrationPreview(owner: string | null, dir = agentsDir()): ConnectorMigrationPreview {
   const enabled = syncOptedIn(dir) && syncSetting(dir, connectorSyncScope(owner, readAgentKey(dir))).enabled;
   const liveEnabled = process.env.METRO_CONNECTORS_LIVE_ENABLED === 'true';
-  if (!enabled) return { migrationSupported: true, oauthResourceSupported: true, enabled, enrolled: false, agentId: null, owner, liveEnabled, connectors: [] };
+  if (!enabled) return { migrationSupported: true, oauthResourceSupported: true, moveAllSupported: true, enabled, enrolled: false, agentId: null, owner, liveEnabled, connectors: [] };
   const enrollment = owner === null ? null : readAgentKey(dir)?.enrollment;
   const agentId = enrollment?.organization === owner ? enrollment?.server ?? null : null;
-  return { migrationSupported: true, oauthResourceSupported: true, enabled, enrolled: agentId !== null, agentId, owner, liveEnabled, connectors: previewRows(dir) };
+  return { migrationSupported: true, oauthResourceSupported: true, moveAllSupported: true, enabled, enrolled: agentId !== null, agentId, owner, liveEnabled, connectors: previewRows(dir) };
 }

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

@@ -2,12 +2,17 @@ import { createHash } from 'node:crypto';
 import type { MigrationPayload } from '@metro-labs/http/connector-migration';
 import { connectorPolicyOf } from '@metro-labs/http/connector-delivery';
 import { ApiError } from '@metro-labs/http/api-error';
+import { portableGrant } from '@metro-labs/http/connector-grant';
 import { boundOAuthResource } from '@metro-labs/http/connector-public-url';
 import type { LocalConnectorRow } from './store.js';
 
-export function migrationPayload(row: LocalConnectorRow, oauthResource?: string): MigrationPayload {
+export class MigrationBlocked extends ApiError {
+  constructor(readonly reason: string, message: string) { super(message, 409); }
+}
+
+export function migrationPayload(row: LocalConnectorRow, oauthResource?: string, transfer = false): MigrationPayload {
   const oauth = row.config.oauth || row.config.auth.kind === 'oauth';
-  const auth = oauth ? { kind: 'oauth' as const } : row.config.auth;
+  const auth = sourceAuth(row, oauth, transfer);
   if (!oauth && oauthResource !== undefined) throw new ApiError('Only an OAuth connector accepts a public OAuth resource.', 400);
   return stamped({
     name: row.name, url: row.url, auth, client: row.config.client, policy: connectorPolicyOf(row.config.policy ?? {}),
@@ -15,6 +20,11 @@ export function migrationPayload(row: LocalConnectorRow, oauthResource?: string)
   });
 }
 
+function sourceAuth(row: LocalConnectorRow, oauth: boolean, transfer: boolean): MigrationPayload['auth'] {
+  if (!oauth) return row.config.auth;
+  return transfer ? { kind: 'oauth', grant: transferableGrant(row) } : { kind: 'oauth' };
+}
+
 function stamped(value: Omit<MigrationPayload, 'sourceStamp'>): MigrationPayload {
   const policy = value.policy;
   const canonical = {
@@ -24,3 +34,9 @@ function stamped(value: Omit<MigrationPayload, 'sourceStamp'>): MigrationPayload
   const sourceStamp = createHash('sha256').update(JSON.stringify(canonical)).digest('base64url');
   return { ...value, sourceStamp };
 }
+
+function transferableGrant(row: LocalConnectorRow): ReturnType<typeof portableGrant> {
+  if (row.config.auth.kind !== 'oauth') throw new MigrationBlocked('sign_in', 'This connector has no saved OAuth grant. Sign in locally before moving it.');
+  try { return portableGrant(row.config.auth, row.url); }
+  catch { throw new MigrationBlocked('unsupported_grant', 'This OAuth grant has unsupported client authentication or provider binding. Keep it local or sign in separately.'); }
+}

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

@@ -10,7 +10,7 @@ import { publicOAuthResource } from '@metro-labs/http/connector-public-url';
 import { agentsDir } from '../agents/files.js';
 import { captureMigrationOperations } from './migration-operations.js';
 
-export type MigrationPhase = 'preparing' | 'prepared' | 'cutover' | 'active' | 'rollback' | 'rolled_back';
+export type MigrationPhase = 'recovering' | 'freezing' | 'preparing' | 'prepared' | 'cutover' | 'active' | 'rollback' | 'rolled_back';
 export type MigrationAuth = 'none' | 'header' | 'oauth';
 
 export interface MigrationRecord {
@@ -24,14 +24,18 @@ export interface MigrationRecord {
   phase: MigrationPhase;
   auth: MigrationAuth;
   oauthResource?: string;
+  move?: boolean;
+  grantImported?: boolean;
+  captured?: boolean;
+  recoveryReceipt?: string;
   sourceStamp: string;
   policy: ConnectorPolicy;
   reason: string | null;
 }
 
-const phases: readonly MigrationPhase[] = ['preparing', 'prepared', 'cutover', 'active', 'rollback', 'rolled_back'];
+const phases: readonly MigrationPhase[] = ['recovering', 'freezing', 'preparing', 'prepared', 'cutover', 'active', 'rollback', 'rolled_back'];
 const auths: readonly MigrationAuth[] = ['none', 'header', 'oauth'];
-const fields = ['id', 'owner', 'agentId', 'keyId', 'sourceId', 'name', 'destinationId', 'phase', 'auth', 'oauthResource', 'sourceStamp', 'policy', 'reason'];
+const fields = ['id', 'owner', 'agentId', 'keyId', 'sourceId', 'name', 'destinationId', 'phase', 'auth', 'oauthResource', 'sourceStamp', 'policy', 'reason', 'move', 'grantImported', 'captured', 'recoveryReceipt'];
 const unavailable = (): ApiError => new ApiError('Protected connector migration records cannot be read. Restore their file or permissions before using connectors.', 503);
 const DIGEST = /^[A-Za-z0-9_-]{43}$/;
 const pathOf = (dir: string): string => join(dir, 'connector-migrations.json');
@@ -48,12 +52,25 @@ function field(value: unknown, pattern: RegExp): string {
   return value;
 }
 
+function movementOf(value: Record<string, unknown>): Pick<MigrationRecord, 'move' | 'grantImported' | 'captured' | 'recoveryReceipt'> {
+  const result: Pick<MigrationRecord, 'move' | 'grantImported' | 'captured' | 'recoveryReceipt'> = {};
+  for (const key of ['move', 'grantImported', 'captured'] as const) {
+    const flag = value[key];
+    if (flag === undefined) continue;
+    if (typeof flag !== 'boolean') throw unavailable();
+    result[key] = flag;
+  }
+  if (value.recoveryReceipt !== undefined) result.recoveryReceipt = field(value.recoveryReceipt, /^[a-f0-9]{64}$/);
+  return result;
+}
+
 function recordOf(value: unknown): MigrationRecord {
   if (!isRecord(value) || Object.keys(value).some((key) => !fields.includes(key))) throw unavailable();
   const phase = phases.find((item) => item === value.phase);
   const auth = auths.find((item) => item === value.auth);
   if (phase === undefined || auth === undefined || (value.oauthResource !== undefined && auth !== 'oauth')) throw unavailable();
   return {
+    ...movementOf(value),
     ...(value.oauthResource === undefined ? {} : { oauthResource: publicOAuthResource(value.oauthResource) }),
     id: requiredId(value.id), sourceId: requiredId(value.sourceId), agentId: requiredId(value.agentId),
     owner: field(value.owner, /^org_[A-Za-z0-9]{1,128}$/), keyId: field(value.keyId, DIGEST), sourceStamp: field(value.sourceStamp, DIGEST),

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

@@ -102,6 +102,7 @@ function authOf(pendingAuth: PendingAuth, tokens: OAuthTokens): OAuthAuth {
     kind: 'oauth',
     issuer: pendingAuth.server.issuer,
     tokenEndpoint: pendingAuth.server.tokenEndpoint,
+    resource: pendingAuth.resource,
     clientId: pendingAuth.client.clientId,
     ...(pendingAuth.client.clientSecret === undefined
       ? {}
@@ -156,7 +157,7 @@ export async function refreshOAuth(
     server,
     client,
     auth.refreshToken,
-    resource,
+    auth.resource ?? resource,
     auth.scope,
     send,
   );

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

@@ -327,8 +327,10 @@ function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Prom
   const running = inflight.get(key);
   if (running !== undefined) return running;
   const job = withLocalMigrationOperation(row.id, dir, async (operation) => {
-    const fresh = await refreshOAuth(auth, parseConnectorUrl(row.url).toString(), operation.fetch);
+    const fresh = await refreshOAuth(auth, parseConnectorUrl(row.url).toString(), (input, init) => operation.dispatch(() => fetch(input, init), { refresh: true }));
     updateRow(dir, row.id, { auth: fresh }, true);
+    flushMigrationSource(dir);
+    operation.persistedRefresh();
     return fresh;
   }).finally(() => { inflight.delete(key); });
   inflight.set(key, job);
@@ -369,11 +371,7 @@ async function oauthTarget(row: LocalConnectorRow, auth: OAuthAuth, force: boole
   }
 }
 
-export async function localRelayTarget(
-  connectorId: string,
-  force: boolean,
-  dir = agentsDir(),
-): Promise<RelayTarget> {
+export async function localRelayTarget(connectorId: string, force: boolean, dir = agentsDir()): Promise<RelayTarget> {
   return withLocalMigrationOperation(connectorId, dir, async (operation) => {
     const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
     if (row === undefined) return { kind: 'missing' };
@@ -385,11 +383,15 @@ export async function localRelayTarget(
   });
 }
 
-export function localRollbackMigrationSource(id: string, signOutOAuth: boolean, dir = agentsDir()): void {
-  if (migrationSource(id, dir)?.phase !== 'rollback' || !localMigrationIdle(id, dir)) throw new ConnectorError('The connector migration is not ready to roll back.', 409);
+export function localRollbackMigrationSource(id: string, signOutOAuth: boolean, dir = agentsDir(), discardUncertain = false): void {
+  if (!['rollback', 'recovering'].includes(migrationSource(id, dir)?.phase ?? '') || !localMigrationIdle(id, dir, discardUncertain && signOutOAuth)) throw new ConnectorError('The connector migration is not ready to roll back.', 409);
   const row = rowOrThrow(id, dir);
   if (signOutOAuth) replace(dir, signedOut(row), true);
-  if (signOutOAuth) for (const path of [filePath(dir), dir]) {
+  if (signOutOAuth) flushMigrationSource(dir);
+}
+
+export function flushMigrationSource(dir = agentsDir()): void {
+  for (const path of [filePath(dir), dir]) {
     const fd = openSync(path, 'r');
     try { fsyncSync(fd); } finally { closeSync(fd); }
   }

package/runtime/node_modules/@metro-labs/http/package.json

@@ -22,7 +22,8 @@
     "./connector-oauth": "./src/connector-oauth.ts",
     "./connector-input": "./src/connector-input.ts",
     "./connector-delivery": "./src/connector-delivery.ts",
-    "./connector-migration": "./src/connector-migration.ts"
+    "./connector-migration": "./src/connector-migration.ts",
+    "./connector-grant": "./src/connector-grant.ts"
   },
   "scripts": {
     "build": "tsc",

package/runtime/node_modules/@metro-labs/http/src/connector-grant.ts

@@ -0,0 +1,59 @@
+import { deliveryRecord } from './connector-delivery-validation.js';
+import type { OAuthAuth } from './connector-mcp.js';
+import { boundOAuthResource, parsePublicConnectorUrl } from './connector-public-url.js';
+
+export interface PortableGrant extends OAuthAuth {
+  resource: string;
+  tokenEndpointAuthMethod: 'none' | 'client_secret_post';
+}
+
+const invalid = (): never => { throw new Error('This OAuth grant cannot be transferred. Its client authentication or provider binding is unsupported. Sign in separately.'); };
+
+function text(raw: unknown, max = 16384): string {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > max || /[^\x21-\x7e]/.test(raw)) return invalid();
+  return raw;
+}
+
+function endpoint(raw: unknown): string {
+  const value = text(raw, 2048);
+  parsePublicConnectorUrl(value);
+  return value;
+}
+
+export function grantResource(target: string, raw: unknown): string {
+  const transport = parsePublicConnectorUrl(target);
+  const resource = parsePublicConnectorUrl(raw);
+  if (resource.toString() === transport.toString() && typeof raw === 'string') return raw;
+  return boundOAuthResource(target, raw);
+}
+
+function binding(value: Record<string, unknown>): Pick<PortableGrant, 'clientId' | 'clientSecret' | 'tokenEndpointAuthMethod'> {
+  const clientSecret = value.clientSecret === undefined ? undefined : text(value.clientSecret);
+  const method = value.tokenEndpointAuthMethod ?? (clientSecret === undefined ? 'none' : 'client_secret_post');
+  if (method !== 'none' && method !== 'client_secret_post') return invalid();
+  if ((method === 'client_secret_post') !== (clientSecret !== undefined)) return invalid();
+  return { clientId: text(value.clientId), tokenEndpointAuthMethod: method, ...(clientSecret === undefined ? {} : { clientSecret }) };
+}
+
+function expiry(raw: unknown): Pick<PortableGrant, 'expiresAt'> {
+  if (raw === undefined) return {};
+  if (typeof raw !== 'number' || !Number.isSafeInteger(raw) || raw < 0) return invalid();
+  return { expiresAt: raw };
+}
+
+function scopeOf(raw: unknown): Pick<PortableGrant, 'scope'> {
+  if (raw === undefined) return {};
+  if (typeof raw !== 'string' || raw.length > 16384 || /[^\x20-\x7e]/.test(raw)) return invalid();
+  return { scope: raw };
+}
+
+export function portableGrant(raw: unknown, target: string): PortableGrant {
+  const value = deliveryRecord(raw, ['kind', 'accessToken', 'refreshToken', 'expiresAt', 'clientId', 'clientSecret', 'issuer', 'tokenEndpoint', 'scope', 'resource', 'tokenEndpointAuthMethod']);
+  if (value.kind !== 'oauth') return invalid();
+  return {
+    kind: 'oauth', accessToken: text(value.accessToken, 16377), issuer: endpoint(value.issuer), tokenEndpoint: endpoint(value.tokenEndpoint),
+    resource: grantResource(target, value.resource ?? parsePublicConnectorUrl(target).toString()),
+    ...binding(value), ...expiry(value.expiresAt), ...scopeOf(value.scope),
+    ...(value.refreshToken === undefined ? {} : { refreshToken: text(value.refreshToken) }),
+  };
+}

package/runtime/node_modules/@metro-labs/http/src/connector-mcp.ts

@@ -17,6 +17,8 @@ export interface OAuthAuth extends OAuthTokens {
   clientId: string;
   clientSecret?: string;
   scope?: string;
+  resource?: string;
+  tokenEndpointAuthMethod?: string;
 }
 
 export type ConnectorAuth =

package/runtime/node_modules/@metro-labs/http/src/connector-migration.ts

@@ -4,6 +4,7 @@ import { sealingKeyOf } from './agent-signature.js';
 import { deliveryBytes, deliveryRecord } from './connector-delivery-validation.js';
 import { connectorAuth, connectorClient, connectorName } from './connector-input.js';
 import type { OAuthClient } from './connector-oauth.js';
+import { portableGrant, type PortableGrant } from './connector-grant.js';
 import { connectorPolicyOf, type ConnectorPolicy } from './connector-policy.js';
 import { boundOAuthResource, parsePublicConnectorUrl } from './connector-public-url.js';
 import { openTransfer, sealTransfer, type SealedTransfer } from './transfer-crypto.js';
@@ -24,7 +25,7 @@ export interface MigrationContext {
 export interface MigrationPayload {
   name: string;
   url: string;
-  auth: { kind: 'none' } | { kind: 'header'; name: string; value: string } | { kind: 'oauth' };
+  auth: { kind: 'none' } | { kind: 'header'; name: string; value: string } | { kind: 'oauth'; grant?: PortableGrant };
   client: OAuthClient | null;
   oauthResource?: string;
   policy: ConnectorPolicy;
@@ -36,7 +37,8 @@ export interface MigrationView {
   sourceId: string;
   destinationId: string;
   phase: 'preparing' | 'prepared' | 'active' | 'rolled_back';
-  readiness: 'pending' | 'ready' | 'signin' | 'changed' | 'unavailable';
+  readiness: 'pending' | 'ready' | 'signin' | 'changed' | 'unavailable' | 'refresh_uncertain';
+  grantImported?: boolean;
   name: string | null;
   auth: 'none' | 'header' | 'oauth' | null;
   policy: ConnectorPolicy | null;
@@ -48,7 +50,7 @@ export interface MigrationResponse {
   receiving?: { publicKey: string; context: MigrationContext };
 }
 
-export type MigrationRequest = { action: 'begin' | 'status' | 'activate' | 'rollback'; operationId: string; sourceId: string } | { action: 'prepare'; operationId: string; sourceId: string; sealed: unknown };
+export type MigrationRequest = { action: 'begin' | 'status' | 'activate' | 'rollback'; operationId: string; sourceId: string } | { action: 'prepare' | 'handover'; operationId: string; sourceId: string; sealed: unknown };
 
 const invalid = (): Error => new Error('Invalid connector migration.');
 const idOf = (value: unknown): string => {
@@ -61,7 +63,7 @@ export function migrationRequestOf(raw: unknown): MigrationRequest {
   const value = deliveryRecord(raw, ['action', 'operationId', 'sourceId', 'sealed']);
   const operationId = idOf(value.operationId);
   const sourceId = idOf(value.sourceId);
-  if (value.action === 'prepare' && Object.hasOwn(value, 'sealed')) return { action: 'prepare', operationId, sourceId, sealed: value.sealed };
+  if ((value.action === 'prepare' || value.action === 'handover') && Object.hasOwn(value, 'sealed')) return { action: value.action, operationId, sourceId, sealed: value.sealed };
   if (Object.hasOwn(value, 'sealed')) throw invalid();
   if (value.action !== 'begin' && value.action !== 'status' && value.action !== 'activate' && value.action !== 'rollback') throw invalid();
   return { action: value.action, operationId, sourceId };
@@ -79,15 +81,19 @@ function contextBytes(context: MigrationContext): Buffer {
   return Buffer.from(JSON.stringify(['metro-connector-migration/v1', value.owner, value.agent, value.keyId, value.operationId, value.sourceId, value.destinationId]));
 }
 
-function authOf(raw: unknown): MigrationPayload['auth'] {
-  const value = deliveryRecord(raw, ['kind', 'name', 'value']);
-  if (value.kind === 'header') {
-    const auth = connectorAuth(value.name, value.value);
-    if (auth.kind !== 'header' || auth.name !== value.name || auth.value !== value.value || ['__proto__', 'constructor', 'prototype'].includes(auth.name)) throw invalid();
-    return auth;
-  }
+function headerOf(value: Record<string, unknown>): MigrationPayload['auth'] {
+  const auth = connectorAuth(value.name, value.value);
+  if (auth.kind !== 'header' || auth.name !== value.name || auth.value !== value.value || ['__proto__', 'constructor', 'prototype'].includes(auth.name)) throw invalid();
+  return auth;
+}
+
+function authOf(raw: unknown, target: string): MigrationPayload['auth'] {
+  const value = deliveryRecord(raw, ['kind', 'name', 'value', 'grant']);
+  if (value.kind !== 'oauth' && Object.hasOwn(value, 'grant')) throw invalid();
+  if (value.kind === 'header') return headerOf(value);
   if ((value.kind !== 'none' && value.kind !== 'oauth') || Object.hasOwn(value, 'name') || Object.hasOwn(value, 'value')) throw invalid();
-  return { kind: value.kind };
+  if (value.kind === 'none' || value.grant === undefined) return { kind: value.kind };
+  return { kind: 'oauth', grant: portableGrant(value.grant, target) };
 }
 
 function clientOf(raw: unknown): OAuthClient | null {
@@ -109,7 +115,7 @@ export function migrationPayloadOf(raw: unknown): MigrationPayload {
   if (typeof value.name !== 'string' || connectorName(value.name) !== value.name || typeof value.url !== 'string' || typeof value.sourceStamp !== 'string') throw invalid();
   parsePublicConnectorUrl(value.url);
   deliveryBytes(value.sourceStamp, 32);
-  const auth = authOf(value.auth);
+  const auth = authOf(value.auth, value.url);
   const client = migrationClient(auth, value);
   const payload = { name: value.name, url: value.url, auth, client, ...(Object.hasOwn(value, 'oauthResource') ? { oauthResource: boundOAuthResource(value.url, value.oauthResource) } : {}), policy: connectorPolicyOf(value.policy), sourceStamp: value.sourceStamp };
   if (Buffer.byteLength(JSON.stringify(payload)) > PAYLOAD_MAX) throw invalid();
@@ -122,7 +128,7 @@ function phaseOf(value: unknown): MigrationView['phase'] {
 }
 
 function readinessOf(value: unknown): MigrationView['readiness'] {
-  if (value !== 'pending' && value !== 'ready' && value !== 'signin' && value !== 'changed' && value !== 'unavailable') throw invalid();
+  if (value !== 'pending' && value !== 'ready' && value !== 'signin' && value !== 'changed' && value !== 'unavailable' && value !== 'refresh_uncertain') throw invalid();
   return value;
 }
 
@@ -145,8 +151,9 @@ function nullableStamp(value: unknown): string | null {
 }
 
 function viewOf(raw: unknown): MigrationView {
-  const view = deliveryRecord(raw, ['operationId', 'sourceId', 'destinationId', 'phase', 'readiness', 'name', 'auth', 'policy', 'sourceStamp']);
-  return { operationId: idOf(view.operationId), sourceId: idOf(view.sourceId), destinationId: idOf(view.destinationId), phase: phaseOf(view.phase), readiness: readinessOf(view.readiness), name: nullableName(view.name), auth: authKindOf(view.auth), policy: view.policy === null ? null : connectorPolicyOf(view.policy), sourceStamp: nullableStamp(view.sourceStamp) };
+  const view = deliveryRecord(raw, ['operationId', 'sourceId', 'destinationId', 'phase', 'readiness', 'name', 'auth', 'policy', 'sourceStamp', 'grantImported']);
+  if (view.grantImported !== undefined && typeof view.grantImported !== 'boolean') throw invalid();
+  return { ...(view.grantImported === undefined ? {} : { grantImported: view.grantImported }), operationId: idOf(view.operationId), sourceId: idOf(view.sourceId), destinationId: idOf(view.destinationId), phase: phaseOf(view.phase), readiness: readinessOf(view.readiness), name: nullableName(view.name), auth: authKindOf(view.auth), policy: view.policy === null ? null : connectorPolicyOf(view.policy), sourceStamp: nullableStamp(view.sourceStamp) };
 }
 
 export function migrationResponseOf(raw: unknown): MigrationResponse {

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.291"
+  "version": "0.1.0-beta.292"
 }

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.291",
+  "version": "0.1.0-beta.292",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",