@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/mcp/manager.d.ts

@@ -0,0 +1,26 @@
+import { Client } from '@modelcontextprotocol/client';
+import { HarnessError } from "../core/errors.js";
+import { type OAuthHost } from "./oauth.js";
+import type { LaunchConfig } from "./types.js";
+export declare const signInRequired: (config: Pick<LaunchConfig, "name">) => HarnessError;
+export declare const isSignInRequired: (error: unknown) => boolean;
+export declare class McpManager {
+    private readonly oauth;
+    private readonly sessions;
+    constructor(oauth: OAuthHost);
+    close(connectionId?: string, sessionId?: string): Promise<void>;
+    /** The client for a connection in one scope, reconnecting when the connection's configuration changed. */
+    client(scope: string, config: LaunchConfig): Promise<Client>;
+    private connectStdio;
+    private connectHttp;
+    /** Runs `work` on a connection opened only for it. */
+    private once;
+    /** What a connection offers, read on a connection of its own. */
+    probe(config: LaunchConfig): Promise<{
+        serverName: string;
+        tools: unknown[];
+        vaultId: string | null;
+    }>;
+    /** One read on a connection of its own, outside any session. */
+    readSource(config: LaunchConfig, tool: string, args: Record<string, unknown>): Promise<unknown>;
+}

package/dist/sdk/mcp/manager.js

@@ -0,0 +1,124 @@
+// Live MCP client sessions: one per (session, connection), opened on first use and closed when
+// the session's run ends or the connection changes.
+import { Client, SSEClientTransport, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+import { randomUUID } from 'node:crypto';
+import { HarnessError } from "../core/errors.js";
+import { StoredOAuthProvider } from "./oauth.js";
+export const signInRequired = (config) => new HarnessError('mcp_unauthorized', `${config.name} needs you to sign in again in Connections.`);
+export const isSignInRequired = (error) => error instanceof UnauthorizedError || (error instanceof HarnessError && error.code === 'mcp_unauthorized');
+export class McpManager {
+    oauth;
+    sessions = new Map();
+    constructor(oauth) {
+        this.oauth = oauth;
+    }
+    async close(connectionId, sessionId) {
+        const closing = [...this.sessions].filter(([key]) => (!connectionId || key.endsWith(`:${connectionId}`)) && (!sessionId || key.startsWith(`${sessionId}:`)));
+        for (const [key] of closing)
+            this.sessions.delete(key);
+        await Promise.allSettled(closing.map(async ([, session]) => {
+            const live = await session;
+            await live.client.close();
+            await live.transport.close();
+        }));
+    }
+    /** The client for a connection in one scope, reconnecting when the connection's configuration changed. */
+    async client(scope, config) {
+        const key = `${scope}:${config.id}`;
+        const fingerprint = JSON.stringify(config);
+        const existing = this.sessions.get(key);
+        if (existing) {
+            const live = await existing.catch(() => null);
+            if (live?.config === fingerprint)
+                return live.client;
+            await live?.client.close().catch(() => undefined);
+            this.sessions.delete(key);
+        }
+        const pending = (async () => {
+            const { client, transport } = config.transport === 'http' ? await this.connectHttp(config) : await this.connectStdio(config);
+            client.onclose = () => {
+                if (this.sessions.get(key) === pending)
+                    this.sessions.delete(key);
+            };
+            return { client, transport, config: fingerprint };
+        })();
+        this.sessions.set(key, pending);
+        try {
+            return (await pending).client;
+        }
+        catch (error) {
+            this.sessions.delete(key);
+            throw error;
+        }
+    }
+    async connectStdio(config) {
+        const client = new Client({ name: 'xagent', version: '0.1.0' });
+        const transport = new StdioClientTransport({ command: config.command, args: config.args, cwd: config.cwd ?? undefined, env: config.env, stderr: 'pipe' });
+        try {
+            await client.connect(transport, { timeout: 30000 });
+        }
+        catch {
+            await transport.close();
+            throw new HarnessError('mcp_unavailable', `${config.name} could not start or initialize. Check its executable and arguments.`);
+        }
+        // Servers' diagnostics may contain secrets; do not persist or forward stderr.
+        transport.stderr?.on('data', () => undefined);
+        return { client, transport };
+    }
+    async connectHttp(config) {
+        const authProvider = config.auth === 'oauth' ? new StoredOAuthProvider(this.oauth, config, false) : undefined;
+        // Without saved tokens the only way forward is the browser, which a session may not open.
+        if (authProvider && !(await authProvider.tokens()))
+            throw signInRequired(config);
+        const options = { authProvider, requestInit: { headers: config.headers } };
+        // Servers that predate Streamable HTTP only answer on SSE.
+        for (const Transport of [StreamableHTTPClientTransport, SSEClientTransport]) {
+            const client = new Client({ name: 'xagent', version: '0.1.0' });
+            const transport = new Transport(new URL(config.url), options);
+            try {
+                await client.connect(transport, { timeout: 30000 });
+                return { client, transport };
+            }
+            catch (error) {
+                await transport.close().catch(() => undefined);
+                if (isSignInRequired(error))
+                    throw signInRequired(config);
+            }
+        }
+        throw new HarnessError('mcp_unavailable', `${config.name} could not be reached. Check its address and credentials.`);
+    }
+    /** Runs `work` on a connection opened only for it. */
+    async once(prefix, config, work) {
+        const scope = `${prefix}-${randomUUID()}`;
+        try {
+            return await work(await this.client(scope, config));
+        }
+        finally {
+            const key = `${scope}:${config.id}`;
+            const session = this.sessions.get(key);
+            this.sessions.delete(key);
+            if (session)
+                await (await session).client.close().catch(() => undefined);
+        }
+    }
+    /** What a connection offers, read on a connection of its own. */
+    probe(config) {
+        return this.once('probe', config, async (client) => {
+            const tools = (await client.listTools()).tools;
+            let vaultId = null;
+            if (tools.some((tool) => tool.name === 'x_workspace_status')) {
+                const status = await client.callTool({ name: 'x_workspace_status', arguments: {} });
+                const envelope = status.structuredContent;
+                if (!envelope?.ok)
+                    throw new HarnessError('mcp_unavailable', envelope?.error?.message ?? 'Workspace vault is not bound.');
+                vaultId = envelope.vaultId ?? null;
+            }
+            return { serverName: client.getServerVersion()?.name ?? config.name, tools, vaultId };
+        });
+    }
+    /** One read on a connection of its own, outside any session. */
+    readSource(config, tool, args) {
+        return this.once('source', config, (client) => client.callTool({ name: tool, arguments: args }, { timeout: 60000 }));
+    }
+}

package/dist/sdk/mcp/oauth.d.ts

@@ -0,0 +1,35 @@
+import type { OAuthClientInformationContext, OAuthClientMetadata, OAuthClientProvider, OAuthDiscoveryState, StoredOAuthClientInformation, StoredOAuthTokens } from '@modelcontextprotocol/client';
+import { type HttpConfig } from "./types.js";
+/** Where a connection's OAuth state is read and written, and how a sign-in page is shown. */
+export interface OAuthHost {
+    load(connectionId: string): Promise<Record<string, unknown>>;
+    save(connectionId: string, state: Record<string, unknown>): Promise<void>;
+    openUrl(url: string): Promise<void> | void;
+    /** The name shown on the provider's consent page. */
+    clientName: string;
+}
+export declare class StoredOAuthProvider implements OAuthClientProvider {
+    private readonly host;
+    private readonly config;
+    private readonly interactive;
+    readonly expectedState: `${string}-${string}-${string}-${string}-${string}`;
+    private verifier;
+    constructor(host: OAuthHost, config: Pick<HttpConfig, 'id' | 'scopes'>, interactive: boolean);
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    state(): string;
+    private load;
+    private change;
+    clientInformation(context?: OAuthClientInformationContext): Promise<StoredOAuthClientInformation | undefined>;
+    saveClientInformation(client: StoredOAuthClientInformation): Promise<void>;
+    tokens(): Promise<StoredOAuthTokens | undefined>;
+    saveTokens(tokens: StoredOAuthTokens): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    saveDiscoveryState(discovery: OAuthDiscoveryState): Promise<void>;
+    saveCodeVerifier(verifier: string): void;
+    codeVerifier(): string;
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+    redirectToAuthorization(url: URL): Promise<void>;
+}
+/** Opens the provider's sign-in page and waits for the browser to return to the loopback address. */
+export declare function signIn(host: OAuthHost, config: HttpConfig): Promise<void>;

package/dist/sdk/mcp/oauth.js

@@ -0,0 +1,171 @@
+// OAuth sign-in for a remote connection. State is kept with the connection's other secrets.
+// Only an interactive provider (a sign-in a person started) may open a browser; a session that
+// needs a new sign-in fails instead.
+import { auth, UnauthorizedError } from '@modelcontextprotocol/client';
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { HarnessError } from "../core/errors.js";
+import { MCP_OAUTH_PORT, MCP_OAUTH_REDIRECT_URL } from "./types.js";
+export class StoredOAuthProvider {
+    host;
+    config;
+    interactive;
+    expectedState = randomUUID();
+    verifier = null;
+    constructor(host, config, interactive) {
+        this.host = host;
+        this.config = config;
+        this.interactive = interactive;
+    }
+    get redirectUrl() {
+        return MCP_OAUTH_REDIRECT_URL;
+    }
+    get clientMetadata() {
+        return {
+            client_name: this.host.clientName,
+            redirect_uris: [MCP_OAUTH_REDIRECT_URL],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+            ...(this.config.scopes.length ? { scope: this.config.scopes.join(' ') } : {})
+        };
+    }
+    state() {
+        return this.expectedState;
+    }
+    load() {
+        return this.host.load(this.config.id);
+    }
+    async change(edit) {
+        await this.host.save(this.config.id, edit(await this.load()));
+    }
+    async clientInformation(context) {
+        const saved = await this.load();
+        if (!saved.staticClient)
+            return saved.client;
+        // A client the user registered themselves (providers without dynamic registration) wins. It is
+        // tied to the authorization server seen at sign-in, so a session never offers it to another one.
+        if (this.interactive && context && saved.staticIssuer !== context.issuer)
+            await this.change((current) => ({ ...current, staticIssuer: context.issuer }));
+        const issuer = this.interactive ? context?.issuer : saved.staticIssuer;
+        return issuer ? { ...saved.staticClient, issuer } : saved.staticClient;
+    }
+    async saveClientInformation(client) {
+        await this.change((saved) => ({ ...saved, client }));
+    }
+    async tokens() {
+        return (await this.load()).tokens;
+    }
+    async saveTokens(tokens) {
+        await this.change((saved) => ({ ...saved, tokens }));
+    }
+    async discoveryState() {
+        return (await this.load()).discovery;
+    }
+    async saveDiscoveryState(discovery) {
+        await this.change((saved) => ({ ...saved, discovery }));
+    }
+    saveCodeVerifier(verifier) {
+        this.verifier = verifier;
+    }
+    codeVerifier() {
+        if (!this.verifier)
+            throw new UnauthorizedError('Sign-in was not started from this app.');
+        return this.verifier;
+    }
+    async invalidateCredentials(scope) {
+        if (scope === 'verifier' || scope === 'all')
+            this.verifier = null;
+        if (scope === 'verifier')
+            return;
+        await this.change((saved) => (scope === 'all' ? {} : { ...saved, [scope]: undefined }));
+    }
+    async redirectToAuthorization(url) {
+        if (!this.interactive)
+            throw new UnauthorizedError('Sign in again in Connections.');
+        // Google only returns a refresh token when offline access is requested with a consent prompt.
+        if (url.hostname === 'accounts.google.com') {
+            url.searchParams.set('access_type', 'offline');
+            url.searchParams.set('prompt', 'consent');
+        }
+        await this.host.openUrl(url.toString());
+    }
+}
+const page = (title, message) => `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font:16px system-ui;margin:20vh auto;max-width:28rem;text-align:center"><p>${message}</p></body>`;
+// One sign-in owns the loopback port. Starting another ends the one still waiting, so a closed
+// browser tab never blocks a retry.
+let cancelActive = null;
+/** Waits on the fixed loopback address for the provider to send the browser back. */
+function listenForCallback(expectedState, clientName) {
+    return new Promise((ready, failed) => {
+        let settle;
+        const result = new Promise((resolve, reject) => {
+            settle = { resolve, reject };
+        });
+        result.catch(() => undefined);
+        const server = createServer((request, response) => {
+            const url = new URL(request.url ?? '/', MCP_OAUTH_REDIRECT_URL);
+            const reply = (status, message) => {
+                response.writeHead(status, { 'content-type': 'text/html; charset=utf-8' });
+                response.end(page(clientName, message));
+            };
+            if (url.pathname !== new URL(MCP_OAUTH_REDIRECT_URL).pathname)
+                return reply(404, 'Not found.');
+            // Anything on this machine can reach the port; only the request carrying this sign-in's state counts.
+            if (url.searchParams.get('state') !== expectedState)
+                return reply(400, `This sign-in link is not the one ${clientName} is waiting for.`);
+            const code = url.searchParams.get('code');
+            if (!code) {
+                reply(400, 'Sign-in was not completed. You can close this window.');
+                return settle.reject(new HarnessError('mcp_unauthorized', url.searchParams.get('error') === 'access_denied' ? 'Sign-in was cancelled.' : 'The provider did not complete the sign-in.'));
+            }
+            reply(200, `Signed in. You can close this window and return to ${clientName}.`);
+            settle.resolve({ code, iss: url.searchParams.get('iss') ?? undefined });
+        });
+        const timer = setTimeout(() => settle.reject(new HarnessError('mcp_unauthorized', 'Sign-in timed out. Try again.')), 300000);
+        server.once('error', (error) => {
+            clearTimeout(timer);
+            failed(new HarnessError('invalid_request', error.code === 'EADDRINUSE' ? `Port ${MCP_OAUTH_PORT} is in use. Finish or cancel the other sign-in, or quit the program using that port, then try again.` : 'The sign-in listener could not start.'));
+        });
+        const closed = new Promise((resolve) => server.once('close', resolve));
+        const close = () => {
+            clearTimeout(timer);
+            if (cancelActive === cancel)
+                cancelActive = null;
+            server.close();
+            server.closeAllConnections();
+            return closed;
+        };
+        const cancel = () => {
+            settle.reject(new HarnessError('mcp_unauthorized', 'Sign-in was cancelled.'));
+            return close();
+        };
+        server.listen(MCP_OAUTH_PORT, '127.0.0.1', () => {
+            cancelActive = cancel;
+            ready({ result, close });
+        });
+    });
+}
+/** Opens the provider's sign-in page and waits for the browser to return to the loopback address. */
+export async function signIn(host, config) {
+    const provider = new StoredOAuthProvider(host, config, true);
+    const scope = config.scopes.join(' ') || undefined;
+    await cancelActive?.();
+    const callback = await listenForCallback(provider.expectedState, host.clientName);
+    try {
+        if ((await auth(provider, { serverUrl: config.url, scope, forceReauthorization: true })) === 'REDIRECT') {
+            const { code, iss } = await callback.result;
+            if ((await auth(provider, { serverUrl: config.url, scope, authorizationCode: code, iss })) !== 'AUTHORIZED')
+                throw new HarnessError('mcp_unauthorized', 'The provider did not complete the sign-in.');
+        }
+    }
+    catch (error) {
+        if (error instanceof HarnessError)
+            throw error;
+        // Provider responses can quote credentials; report only that it failed.
+        throw new HarnessError('mcp_unauthorized', `${config.name} sign-in failed. Check the connection's address and OAuth client, then try again.`);
+    }
+    finally {
+        await callback.close();
+    }
+}

package/dist/sdk/mcp/scopeMigration.d.ts

@@ -0,0 +1,19 @@
+interface MigrationRecord {
+    version: 1;
+    status: 'attachments-written' | 'complete';
+    connectionCount: number;
+    scopeAssignmentCount: number;
+    connectionsBackup: string | null;
+    attachmentsBackup: string | null;
+    hadAttachments: boolean;
+}
+/** Scope writes are safe only after the legacy records have been copied and stripped. */
+export declare function connectionScopeMigrationComplete(root: string): boolean;
+/**
+ * Runs once when a data root opens. Both source files are backed up before either is changed;
+ * a stage marker makes an interrupted migration safe to finish on the next open.
+ */
+export declare function migrateConnectionScopes(root: string, stateDir: string): MigrationRecord;
+/** Restores the byte-identical pre-migration files from the backups if an operator rolls back. */
+export declare function rollbackConnectionScopeMigration(root: string, stateDir: string): void;
+export {};

package/dist/sdk/mcp/scopeMigration.js

@@ -0,0 +1,198 @@
+// Moves who can reach each connected app out of the device-local connection records and into
+// the data root's shared capability attachment store. The originals remain as owner-only backups.
+import { chmodSync, existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWrite, readJson, writeJson } from "../core/fs.js";
+import * as attachments from "../plugins/attachments.js";
+import { connectionCapabilityId, connectionSchema } from "./types.js";
+const recordPath = (root) => join(root, 'config/capability-scope-migration.json');
+const attachmentsPath = (root) => join(root, 'config/plugin-attachments.json');
+const connectionPath = (stateDir) => join(stateDir, 'connections.json');
+const connectionsBackupPath = (stateDir) => join(stateDir, 'connections.pre-capability-scope.json');
+const attachmentsBackupPath = (root) => join(root, 'config/plugin-attachments.pre-capability-scope.json');
+/** Scope writes are safe only after the legacy records have been copied and stripped. */
+export function connectionScopeMigrationComplete(root) {
+    try {
+        const marker = readJson(recordPath(root));
+        return marker?.version === 1 && marker.status === 'complete';
+    }
+    catch {
+        return false;
+    }
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function scopeRows(connection) {
+    const agents = new Map();
+    const projects = new Map();
+    for (const id of unique([...connection.agentIds, ...connection.excludedAgentIds])) {
+        agents.set(id, !connection.excludedAgentIds.includes(id));
+    }
+    for (const id of unique([...connection.projectIds, ...connection.excludedProjectIds])) {
+        projects.set(id, !connection.excludedProjectIds.includes(id));
+    }
+    return { global: connection.global, agents, projects };
+}
+function assignmentCount(rows) {
+    return 1 + rows.agents.size + rows.projects.size;
+}
+function removeId(choices, id) {
+    attachments.forgetId(choices, id);
+}
+function put(map, id, value) {
+    map.on = map.on.filter((item) => item !== id);
+    map.off = map.off.filter((item) => item !== id);
+    map[value ? 'on' : 'off'].push(id);
+}
+function writeRows(choices, id, rows) {
+    removeId(choices, id);
+    put(choices.global, id, rows.global);
+    for (const [scopeId, on] of rows.agents) {
+        const target = (choices.agents[scopeId] ??= { on: [], off: [] });
+        put(target, id, on);
+    }
+    for (const [scopeId, on] of rows.projects) {
+        const target = (choices.projects[scopeId] ??= { on: [], off: [] });
+        put(target, id, on);
+    }
+}
+function readValue(item, id) {
+    if (item?.off.includes(id))
+        return false;
+    if (item?.on.includes(id))
+        return true;
+    return null;
+}
+function verifyRows(choices, id, expected) {
+    if (readValue(choices.global, id) !== expected.global)
+        return false;
+    for (const [scopeId, on] of expected.agents) {
+        if (readValue(choices.agents[scopeId], id) !== on)
+            return false;
+    }
+    for (const [scopeId, on] of expected.projects) {
+        if (readValue(choices.projects[scopeId], id) !== on)
+            return false;
+    }
+    return true;
+}
+function backup(source, target) {
+    if (!existsSync(source))
+        return false;
+    if (!existsSync(target))
+        atomicWrite(target, readFileSync(source));
+    chmodSync(target, 0o600);
+    return true;
+}
+function setPrivate(path) {
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* The atomic write remains usable if chmod is unavailable. */ }
+}
+function stripScopes(stateDir) {
+    const path = connectionPath(stateDir);
+    if (!existsSync(path))
+        return;
+    const stored = readJson(path);
+    if (!Array.isArray(stored))
+        throw new Error('Stored connector data must be a list before its scopes can be migrated.');
+    const records = stored.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new Error('A stored connector record is invalid; no scope data was removed.');
+        const { global: _global, agentIds: _agentIds, projectIds: _projectIds, excludedAgentIds: _excludedAgentIds, excludedProjectIds: _excludedProjectIds, ...connection } = item;
+        return connection;
+    });
+    writeJson(path, records);
+    setPrivate(path);
+}
+/**
+ * Runs once when a data root opens. Both source files are backed up before either is changed;
+ * a stage marker makes an interrupted migration safe to finish on the next open.
+ */
+export function migrateConnectionScopes(root, stateDir) {
+    const marker = readJson(recordPath(root));
+    if (marker?.version === 1 && marker.status === 'complete')
+        return marker;
+    if (marker?.version === 1 && marker.status === 'attachments-written') {
+        stripScopes(stateDir);
+        const complete = { ...marker, status: 'complete' };
+        writeJson(recordPath(root), complete);
+        return complete;
+    }
+    const connectionsFile = connectionPath(stateDir);
+    const hadConnections = existsSync(connectionsFile);
+    const raw = hadConnections ? readJson(connectionsFile) : [];
+    if (!Array.isArray(raw))
+        throw new Error('Stored connector data must be a list before its scopes can be migrated.');
+    const parsed = raw.map((item) => {
+        const result = connectionSchema.safeParse(item);
+        if (!result.success)
+            throw new Error('A stored connector record is invalid; no scope data was removed.');
+        return result.data;
+    });
+    const connectionBackup = hadConnections ? connectionsBackupPath(stateDir) : null;
+    const hadAttachments = existsSync(attachmentsPath(root));
+    const attachmentBackup = hadAttachments ? attachmentsBackupPath(root) : null;
+    const migration = {
+        version: 1,
+        status: 'attachments-written',
+        connectionCount: parsed.length,
+        scopeAssignmentCount: parsed.reduce((count, connection) => count + assignmentCount(scopeRows(connection)), 0),
+        connectionsBackup: connectionBackup,
+        attachmentsBackup: attachmentBackup,
+        hadAttachments
+    };
+    backup(connectionsFile, connectionBackup ?? '');
+    backup(attachmentsPath(root), attachmentBackup ?? '');
+    try {
+        const choices = attachments.load(root);
+        const expected = new Map();
+        for (const connection of parsed) {
+            const id = connectionCapabilityId(connection.id);
+            const rows = scopeRows(connection);
+            expected.set(id, rows);
+            writeRows(choices, id, rows);
+        }
+        const migratedAssignments = [...expected.values()].reduce((count, rows) => count + assignmentCount(rows), 0);
+        if (migratedAssignments !== migration.scopeAssignmentCount || [...expected].some(([id, rows]) => !verifyRows(choices, id, rows))) {
+            throw new Error('Connector scope count check failed; the original files were restored.');
+        }
+        attachments.save(root, choices);
+        const saved = attachments.load(root);
+        if ([...expected].some(([id, rows]) => !verifyRows(saved, id, rows)))
+            throw new Error('Connector scope count check failed after saving; the original files were restored.');
+        writeJson(recordPath(root), migration);
+        stripScopes(stateDir);
+        const complete = { ...migration, status: 'complete' };
+        writeJson(recordPath(root), complete);
+        return complete;
+    }
+    catch (error) {
+        if (attachmentBackup && existsSync(attachmentBackup))
+            atomicWrite(attachmentsPath(root), readFileSync(attachmentBackup));
+        else if (!hadAttachments && existsSync(attachmentsPath(root)))
+            unlinkSync(attachmentsPath(root));
+        if (connectionBackup && existsSync(connectionBackup))
+            atomicWrite(connectionsFile, readFileSync(connectionBackup));
+        try {
+            unlinkSync(recordPath(root));
+        }
+        catch { /* No marker is also a valid retry state. */ }
+        throw error;
+    }
+}
+/** Restores the byte-identical pre-migration files from the backups if an operator rolls back. */
+export function rollbackConnectionScopeMigration(root, stateDir) {
+    const marker = readJson(recordPath(root));
+    if (!marker || marker.version !== 1)
+        return;
+    if (marker.attachmentsBackup && existsSync(marker.attachmentsBackup))
+        atomicWrite(attachmentsPath(root), readFileSync(marker.attachmentsBackup));
+    else if (!marker.hadAttachments && existsSync(attachmentsPath(root)))
+        unlinkSync(attachmentsPath(root));
+    if (marker.connectionsBackup && existsSync(marker.connectionsBackup))
+        atomicWrite(connectionPath(stateDir), readFileSync(marker.connectionsBackup));
+    unlinkSync(recordPath(root));
+}