@openchambery/web 2.1.7 → 2.1.8-beta.11

package/server/lib/config-sync/engine.js

@@ -13,6 +13,8 @@ import { collectLocalTarBuffer } from './tar.js';
  *   syncRunId: string,
  *   sourceHomedir: string,
  *   collectTar?: typeof collectLocalTarBuffer,
+ *   collectCredentials?: () => Promise<Buffer>,
+ *   collectMagpie?: () => Promise<Buffer>,
  * }} args
  */
 export const applyConfigSyncPlan = async ({
@@ -21,6 +23,8 @@ export const applyConfigSyncPlan = async ({
   syncRunId,
   sourceHomedir,
   collectTar = collectLocalTarBuffer,
+  collectCredentials,
+  collectMagpie,
 }) => {
   assertPlanDirection(plan);
   const home = String(sourceHomedir || '');
@@ -31,9 +35,9 @@ export const applyConfigSyncPlan = async ({
   ];
   const hasConfigPayload = tarEntries.length > 0;
   const hasAgentsPayload = Boolean(plan.agentsRoot);
-  const hasAuthPayload = Boolean(plan.authFile);
+  const hasCredentialPayload = Boolean(plan.providerCredentials);
 
-  if (!hasConfigPayload && !hasAgentsPayload && !hasAuthPayload) {
+  if (!hasConfigPayload && !hasAgentsPayload && !hasCredentialPayload && !plan.magpie) {
     // Nothing to upload — preserve the historical short-circuit (no remote prepare).
     return {
       ok: true,
@@ -42,7 +46,7 @@ export const applyConfigSyncPlan = async ({
       deletes: plan.deletes.length,
       totalBytes: plan.totalBytes,
       agentsRoot: null,
-      authFile: null,
+      providerCredentials: null,
       plan,
     };
   }
@@ -54,25 +58,26 @@ export const applyConfigSyncPlan = async ({
   const agentsTarBuffer = hasAgentsPayload
     ? await collectTar(['-h', '-czf', '-', '-C', home, '.agents'], { windowsHide })
     : null;
-  const authShareDir = path.join(home, '.local', 'share', 'opencode');
-  const authTarBuffer = hasAuthPayload
-    ? await collectTar(['-h', '-czf', '-', '-C', authShareDir, 'auth.json'], { windowsHide })
+  const credentialPayload = hasCredentialPayload
+    ? await collectCredentials()
     : null;
+  const magpiePayload = plan.magpie ? await collectMagpie() : null;
 
   await executor.prepare(plan, { syncRunId });
 
+  if (magpiePayload) await executor.putTar({ kind: 'magpie', payload: magpiePayload });
   if (configTarBuffer) {
     await executor.putTar({ kind: 'config', payload: configTarBuffer });
   }
   if (agentsTarBuffer) {
     await executor.putTar({ kind: 'agents', payload: agentsTarBuffer });
   }
-  if (authTarBuffer) {
-    // Only auth.json — never the rest of ~/.local/share/opencode (session DBs live there).
-    await executor.putTar({ kind: 'auth', payload: authTarBuffer });
+  if (credentialPayload) {
+    // Versioned credential payload; never a database or filesystem archive.
+    await executor.putTar({ kind: 'credentials', payload: credentialPayload });
   }
 
-  await executor.finalize(plan, { syncRunId });
+  const receipt = await executor.finalize(plan, { syncRunId });
 
   return {
     ok: true,
@@ -81,8 +86,9 @@ export const applyConfigSyncPlan = async ({
     deletes: plan.deletes.length,
     totalBytes: plan.totalBytes,
     agentsRoot: plan.agentsRoot ? { fileCount: plan.agentsRoot.fileCount } : null,
-    authFile: plan.authFile ? { bytes: plan.authFile.bytes } : null,
+    providerCredentials: plan.providerCredentials ? { bytes: plan.providerCredentials.bytes } : null,
     plan,
+    ...(receipt?.magpieWarnings?.length ? { magpieWarnings: receipt.magpieWarnings } : {}),
   };
 };
 

package/server/lib/config-sync/index.js

@@ -2,9 +2,7 @@ export {
   OPENCODE_CONFIG_SYNC_ALLOWLIST,
   OPENCODE_CONFIG_SYNC_BACKUP_DIR,
   OPENCODE_AGENTS_SYNC_BACKUP_DIR,
-  OPENCODE_AUTH_SYNC_BACKUP_DIR,
   OPENCODE_AGENTS_ROOT_PROBE_MARKER,
-  OPENCODE_AUTH_FILE_PROBE_MARKER,
   OPENCODE_CONFIG_SYNC_MAX_BYTES,
   OPENCODE_CONFIG_SYNC_MAX_FILES,
   OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS,
@@ -42,7 +40,6 @@ export {
   buildRemoteSyncInventoryScript,
   buildRemoteConfigTarScript,
   buildRemoteAgentsTarScript,
-  buildRemoteAuthTarScript,
   sanitizeSyncRunIdForPath,
   shellQuote,
 } from './scripts.js';

package/server/lib/config-sync/local-backup.js

@@ -5,7 +5,6 @@ import { spawn } from 'node:child_process';
 
 import {
   OPENCODE_AGENTS_SYNC_BACKUP_DIR,
-  OPENCODE_AUTH_SYNC_BACKUP_DIR,
   OPENCODE_CONFIG_SYNC_ALLOWLIST,
   OPENCODE_CONFIG_SYNC_BACKUP_DIR,
   OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS,
@@ -108,18 +107,6 @@ export const prepareLocalSyncDestination = async (homedir, plan, options) => {
     await fsp.rm(path.join(home, '.agents'), { recursive: true, force: true });
   }
 
-  if (plan?.authFile) {
-    const authBackupRoot = path.join(home, OPENCODE_AUTH_SYNC_BACKUP_DIR);
-    const authRun = path.join(authBackupRoot, syncRunId);
-    await fsp.rm(authRun, { recursive: true, force: true });
-    await fsp.mkdir(authRun, { recursive: true });
-    await pruneGenerations(authBackupRoot, syncRunId, generations);
-    await copyPathIfExists(
-      path.join(home, '.local', 'share', 'opencode', 'auth.json'),
-      path.join(authRun, 'auth.json'),
-    );
-  }
-
   return { runBackup };
 };
 

package/server/lib/config-sync/magpie-auth.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const MAX_AUTH_BYTES = 8 * 1024 * 1024;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const accountKey = (value) => typeof value === 'string' && /^[\w.-]+(?:#[\w.-]+)?$/.test(value)
+  && !['__proto__', 'constructor', 'prototype'].includes(value);
+const portableLogin = (row, plugins) => object(row) && typeof row.user === 'string'
+  && ((row.agent === 'codex' && !row.home && object(row.auth) && object(row.auth.tokens))
+    || (typeof row.agent === 'string' && row.agent.startsWith('plugin:')
+      && accountKey(row.home) && Object.hasOwn(plugins, row.home)
+      && row.agent === `plugin:${row.home.split('#')[0]}`));
+
+const readStore = async (file, fallback) => {
+  try {
+    if ((await fs.stat(file)).size > MAX_AUTH_BYTES) throw new Error();
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    throw new Error('Unable to read Magpie authorization store');
+  }
+};
+
+export const validateMagpieAuth = (value) => {
+  if (!object(value) || !object(value.plugins) || !Array.isArray(value.logins)
+    || typeof value.incomplete !== 'boolean' || JSON.stringify(value).length > MAX_AUTH_BYTES
+    || Object.entries(value.plugins).some(([key, auth]) => !accountKey(key) || !object(auth)
+      || !['api', 'oauth'].includes(auth.type)
+      || (auth.type === 'api' ? typeof auth.key !== 'string' || !auth.key
+        : typeof auth.access !== 'string' || typeof auth.refresh !== 'string'))
+    || value.logins.some((row) => !portableLogin(row, value.plugins))) {
+    throw new Error('Invalid Magpie authorization payload');
+  }
+  return value;
+};
+
+export const collectMagpieAuth = async (dir, accounts) => {
+  if (!Array.isArray(accounts) || accounts.some((row) => !object(row) || typeof row.agent !== 'string')) {
+    throw new Error('Unable to read source Magpie accounts');
+  }
+  const plugins = await readStore(path.join(dir, 'plugin-auth.json'), {});
+  const rows = await readStore(path.join(dir, 'logins.json'), []);
+  if (!object(plugins) || !Array.isArray(rows) || rows.some((row) => !object(row))) {
+    throw new Error('Invalid Magpie authorization store');
+  }
+  const available = new Set(accounts.map((row) => row.agent));
+  const visiblePlugins = Object.fromEntries(Object.entries(plugins).filter(([key]) => available.has(key.split('#')[0])
+    && !rows.some((row) => row.agent === `plugin:${key.split('#')[0]}` && row.home === key && row.hidden)));
+  const logins = rows.filter((row) => !row.hidden && portableLogin(row, visiblePlugins));
+  return validateMagpieAuth({ plugins: visiblePlugins, logins,
+    incomplete: accounts.some((account) => !Object.keys(visiblePlugins).some((key) => key.split('#')[0] === account.agent)
+      && !logins.some((row) => row.agent === account.agent && row.user === account.user)) });
+};
+
+const writeStore = async (file, value) => {
+  const staging = `${file}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    await fs.writeFile(staging, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+    await fs.rename(staging, file);
+  } finally { await fs.rm(staging, { force: true }); }
+};
+
+// Use Magpie's own lock filenames; never steal a lock from a running token refresh.
+const lockStore = async (file) => {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    try {
+      const handle = await fs.open(`${file}.lock`, 'wx', 0o600);
+      await handle.close();
+      return () => fs.rm(`${file}.lock`, { force: true });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw new Error('Unable to lock Magpie authorization store');
+      await delay(50);
+    }
+  }
+  throw new Error('Magpie authorization store is busy; retry sync');
+};
+
+export const restoreMagpieAuth = async (dir, input, importCodex) => {
+  const auth = validateMagpieAuth(input);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const pluginFile = path.join(dir, 'plugin-auth.json');
+  const unlockPlugins = await lockStore(pluginFile);
+  try {
+    const plugins = await readStore(pluginFile, {});
+    if (!object(plugins)) throw new Error('Invalid destination Magpie authorization store');
+    await writeStore(pluginFile, { ...plugins, ...auth.plugins });
+  } finally { await unlockPlugins(); }
+  // Codex's native importer owns its OS-level logins lock, account deduplication and identity.
+  for (const row of auth.logins) {
+    if (row.agent === 'codex' && !row.hidden) await importCodex(row.auth);
+  }
+};
+
+export const verifyMagpieAuth = (auth, accounts) => {
+  if (!Array.isArray(accounts) || accounts.some((row) => !object(row) || typeof row.agent !== 'string')) {
+    throw new Error('Unable to verify Magpie accounts');
+  }
+  const expected = new Map();
+  for (const key of Object.keys(auth.plugins)) {
+    const id = key.split('#')[0];
+    expected.set(id, (expected.get(id) || 0) + 1);
+  }
+  const missingAccount = auth.logins.some((row) => !row.hidden
+    && !accounts.some((account) => account.agent === row.agent.replace(/^plugin:/, '')
+      && String(account.user).toLowerCase() === row.user.toLowerCase()));
+  if (missingAccount || [...expected].some(([id, count]) => accounts.filter((row) => row.agent === id).length < count)) {
+    throw new Error('Magpie authorization saved but some accounts are not recognized; check destination plugins and retry');
+  }
+};

package/server/lib/config-sync/magpie-auth.test.js

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { collectMagpieAuth, restoreMagpieAuth, validateMagpieAuth, verifyMagpieAuth } from './magpie-auth.js';
+
+const dirs = [];
+const directory = async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'magpie-auth-test-'));
+  dirs.push(dir);
+  return dir;
+};
+const auth = { plugins: { 'cursor#one': { type: 'oauth', access: 'fixture-access', refresh: 'fixture-refresh', expires: 123 } }, logins: [], incomplete: false };
+afterEach(async () => { vi.restoreAllMocks(); await Promise.all(dirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true }))); });
+
+describe('Magpie authorization transfer', () => {
+  it('exports recognized plugin accounts, excludes hidden/stale accounts and flags unsupported subscriptions', async () => {
+    const dir = await directory();
+    await fs.writeFile(path.join(dir, 'plugin-auth.json'), JSON.stringify({ ...auth.plugins,
+      stale: { type: 'api', key: 'fixture' }, 'cursor#hidden': { type: 'api', key: 'fixture' } }));
+    await fs.writeFile(path.join(dir, 'logins.json'), JSON.stringify([
+      { agent: 'plugin:cursor', user: 'hidden', home: 'cursor#hidden', hidden: 'mark' },
+      { agent: 'chatgpt-api', user: 'fixture', auth: { clientId: 'machine-specific' } },
+    ]));
+    const result = await collectMagpieAuth(dir, [{ agent: 'cursor' }, { agent: 'chatgpt-api', user: 'fixture' }]);
+    expect(result.plugins).toEqual(auth.plugins);
+    expect(result.logins).toEqual([]);
+    expect(result.incomplete).toBe(true);
+  });
+
+  it('does not turn corrupted stores into successful empty credentials', async () => {
+    const dir = await directory();
+    await fs.writeFile(path.join(dir, 'plugin-auth.json'), '{broken');
+    await expect(collectMagpieAuth(dir, [])).rejects.toThrow('authorization store');
+    await expect(restoreMagpieAuth(dir, auth, vi.fn())).rejects.toThrow('authorization store');
+    expect(await fs.readFile(path.join(dir, 'plugin-auth.json'), 'utf8')).toBe('{broken');
+    expect(await fs.readdir(dir)).toEqual(['plugin-auth.json']);
+  });
+
+  it('merges repeated imports without deleting unrelated accounts and releases the plugin lock before native imports', async () => {
+    const dir = await directory();
+    await fs.writeFile(path.join(dir, 'plugin-auth.json'), '{"other":{"type":"api","key":"keep"}}');
+    const input = { ...auth, logins: [{ agent: 'codex', user: 'fixture', auth: { tokens: {} } }] };
+    const importCodex = vi.fn(async () => {
+      await expect(fs.stat(path.join(dir, 'plugin-auth.json.lock'))).rejects.toThrow();
+    });
+    await restoreMagpieAuth(dir, input, importCodex);
+    await restoreMagpieAuth(dir, input, importCodex);
+    expect(JSON.parse(await fs.readFile(path.join(dir, 'plugin-auth.json'), 'utf8'))).toEqual({ other: { type: 'api', key: 'keep' }, ...auth.plugins });
+    expect((await fs.stat(path.join(dir, 'plugin-auth.json'))).mode & 0o777).toBe(0o600);
+    expect(await fs.readdir(dir)).toEqual(['plugin-auth.json']);
+  });
+
+  it('keeps successful plugin writes when a native import fails, so retry can finish', async () => {
+    const dir = await directory();
+    await expect(restoreMagpieAuth(dir, { ...auth, logins: [{ agent: 'codex', user: 'fixture', auth: { tokens: {} } }] },
+      async () => { throw new Error('fixture failure'); })).rejects.toThrow();
+    expect(JSON.parse(await fs.readFile(path.join(dir, 'plugin-auth.json'), 'utf8'))).toEqual(auth.plugins);
+    expect(await fs.readdir(dir)).toEqual(['plugin-auth.json']);
+  });
+
+  it('preserves the previous store and cleans staging files when atomic publication fails', async () => {
+    const dir = await directory();
+    const file = path.join(dir, 'plugin-auth.json');
+    await fs.writeFile(file, '{"other":{"type":"api","key":"keep"}}');
+    vi.spyOn(fs, 'rename').mockRejectedValueOnce(new Error('fixture rename failure'));
+    await expect(restoreMagpieAuth(dir, auth, vi.fn())).rejects.toThrow();
+    expect(JSON.parse(await fs.readFile(file, 'utf8'))).toEqual({ other: { type: 'api', key: 'keep' } });
+    expect(await fs.readdir(dir)).toEqual(['plugin-auth.json']);
+  });
+
+  it('rejects unsafe shapes and verifies every expected account rather than one account per provider', () => {
+    expect(() => validateMagpieAuth({ ...auth, plugins: { '../path': { type: 'api', key: 'fixture' } } })).toThrow();
+    const two = { ...auth, plugins: { ...auth.plugins, 'cursor#two': auth.plugins['cursor#one'] } };
+    expect(() => verifyMagpieAuth(two, [{ agent: 'cursor' }])).toThrow('not recognized');
+    expect(() => verifyMagpieAuth(two, [{ agent: 'cursor' }, { agent: 'cursor' }])).not.toThrow();
+    expect(() => verifyMagpieAuth(auth, {})).toThrow('verify');
+  });
+});

package/server/lib/config-sync/magpie.js

@@ -0,0 +1,276 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { collectMagpieAuth, restoreMagpieAuth, validateMagpieAuth, verifyMagpieAuth } from './magpie-auth.js';
+
+const MAX_BYTES = 64 * 1024 * 1024;
+const CONFIG_FILES = ['providers.json', 'settings.json', 'profiles.json', 'library.json', 'plugins.json', 'plugin-auth.json', 'logins.json'];
+const exists = async (file) => {
+  try { return await fs.stat(file); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null; throw error; }
+};
+
+// Raw CLI output may contain provider names, paths or credentials. Never forward it.
+const runCli = (binary, args, { input = '', env, timeout = 600_000 } = {}) => new Promise((resolve, reject) => {
+  const child = spawn(binary, args, { env, windowsHide: true, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] });
+  let output = '';
+  let exceeded = false;
+  const stop = () => {
+    exceeded = true;
+    try {
+      if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, 'SIGKILL');
+      else child.kill('SIGKILL');
+    } catch { child.kill('SIGKILL'); }
+  };
+  const timer = setTimeout(stop, timeout);
+  const collect = (chunk) => {
+    if (output.length + chunk.length > 1024 * 1024) { stop(); return; }
+    output += chunk.toString();
+  };
+  child.stdout.on('data', collect);
+  child.stderr.on('data', collect);
+  child.stdin.on('error', () => {});
+  child.on('error', () => { clearTimeout(timer); reject(new Error('Unable to start Magpie CLI')); });
+  child.on('close', (code) => {
+    clearTimeout(timer);
+    if (code !== 0 || exceeded) reject(new Error('Magpie CLI operation failed or timed out'));
+    else resolve(output.replace(/\x1b\[[0-9;]*m/g, ''));
+  });
+  child.stdin.end(input);
+});
+
+/** Host-owned discovery and native backup/restore. No renderer-supplied paths or commands. */
+export function createMagpieSync({
+  homedir = os.homedir,
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  fetchImpl = fetch,
+  run = runCli,
+  tempdir = os.tmpdir,
+} = {}) {
+  let installing = null;
+  let busy = false;
+  const home = () => homedir();
+  const configDir = () => path.join(env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME)
+    ? env.XDG_CONFIG_HOME : path.join(home(), '.config'), 'magpie');
+  const managedBinary = () => path.join(env.OPENCHAMBER_DATA_DIR || path.join(home(), '.config', 'openchamber'),
+    'tools', 'magpie', platform === 'win32' ? 'magpie.exe' : 'magpie');
+  const hasConfig = async (dir) => {
+    for (const file of CONFIG_FILES) if ((await exists(path.join(dir, file)))?.isFile()) return true;
+    return false;
+  };
+
+  const locate = async () => {
+    const name = platform === 'win32' ? 'magpie.exe' : 'magpie';
+    const candidates = [
+      env.MAGPIE_BINARY,
+      ...(env.PATH || '').split(path.delimiter).filter(Boolean).map((dir) => path.join(dir, name)),
+      path.join(home(), '.local', 'bin', name),
+      ...(platform === 'darwin' ? [
+        '/Applications/magpie.app/Contents/MacOS/magpie',
+        path.join(home(), 'Applications', 'magpie.app', 'Contents', 'MacOS', 'magpie'),
+        '/opt/homebrew/bin/magpie', '/usr/local/bin/magpie',
+      ] : []),
+      ...(platform === 'win32' && env.LOCALAPPDATA ? [path.join(env.LOCALAPPDATA, 'Programs', 'magpie', name)] : []),
+      managedBinary(),
+    ].filter(Boolean);
+    for (const candidate of new Set(candidates)) {
+      if (!(await exists(candidate))?.isFile()) continue;
+      const binary = await fs.realpath(candidate);
+      const version = await run(binary, ['--version'], { env, timeout: 10_000 });
+      if (!/^magpie\s+\S+/m.test(version)) throw new Error('Invalid Magpie executable');
+      return binary;
+    }
+    return null;
+  };
+
+  const dataDir = async (binary) => {
+    if (!binary) return configDir();
+    let beside = path.dirname(binary);
+    if (path.basename(beside) === 'MacOS' && path.basename(path.dirname(beside)) === 'Contents') {
+      beside = path.dirname(path.dirname(path.dirname(beside)));
+    } else if (platform === 'linux' && env.APPIMAGE && env.APPDIR
+      && binary.startsWith(`${env.APPDIR}${path.sep}`)) beside = path.dirname(env.APPIMAGE);
+    const portable = path.join(beside, 'data');
+    if (await exists(path.join(beside, '.portable'))) return portable;
+    if (!(await exists(portable))?.isDirectory()) return configDir();
+    const shared = [home(), '/Applications', ...['Applications', 'Downloads', 'Desktop', 'Documents'].map((dir) => path.join(home(), dir))];
+    if (!shared.some((dir) => dir.toLowerCase() === beside.toLowerCase())) return portable;
+    return await hasConfig(portable) && !await hasConfig(configDir()) ? portable : configDir();
+  };
+
+  const inventory = async () => {
+    const binary = await locate();
+    return { available: Boolean(binary) && await hasConfig(await dataDir(binary)), installed: Boolean(binary) };
+  };
+
+  const downloadBytes = async (url, limit) => {
+    const response = await fetchImpl(url, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok || !response.body) throw new Error('Unable to download Magpie CLI');
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+      size += chunk.length;
+      if (size > limit) throw new Error('Magpie download exceeds size limit');
+      chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  };
+
+  const publishExecutable = async (binary) => {
+    const entry = path.join(home(), '.local', 'bin', platform === 'win32' ? 'magpie.exe' : 'magpie');
+    if (await exists(entry)) {
+      if (await fs.realpath(entry) === binary) return binary;
+      const version = await run(entry, ['--version'], { env, timeout: 10_000 });
+      if (!/^magpie\s+\S+/m.test(version)) throw new Error('Magpie command conflicts with an existing executable');
+      if (await dataDir(await fs.realpath(entry)) !== await dataDir(binary)) {
+        throw new Error('Magpie command uses a different portable configuration; resolve the command conflict before syncing');
+      }
+      return binary;
+    }
+    await fs.mkdir(path.dirname(entry), { recursive: true });
+    try {
+      if (platform === 'win32' && await dataDir(binary) === configDir()) await fs.link(binary, entry);
+      else await fs.symlink(binary, entry, 'file');
+    } catch (error) {
+      if (error.code !== 'EEXIST' || !await exists(entry)) throw new Error('Unable to publish Magpie command for plugins');
+    }
+    return binary;
+  };
+
+  const repairInstallation = async () => {
+    const binary = managedBinary();
+    if (!(await exists(binary))?.isFile()) return;
+    const version = await run(binary, ['--version'], { env, timeout: 10_000 });
+    if (!/^magpie\s+\S+/m.test(version)) throw new Error('Invalid managed Magpie executable');
+    await publishExecutable(await fs.realpath(binary));
+  };
+
+  const ensure = async () => {
+    const binary = await locate();
+    if (binary) return publishExecutable(binary);
+    if (installing) return installing;
+    installing = (async () => {
+      const cpu = { x64: 'amd64', arm64: 'arm64' }[arch];
+      if (!cpu || !['darwin', 'linux', 'win32'].includes(platform)) throw new Error('Magpie CLI is not available for this platform');
+      const assetName = `magpie-cli-${platform === 'win32' ? 'windows' : platform}-${cpu}${platform === 'win32' ? '.exe' : ''}`;
+      let feed;
+      try { feed = JSON.parse((await downloadBytes('https://usemagpie.ai/api/latest', 2 * 1024 * 1024)).toString()); }
+      catch { throw new Error('Unable to read Magpie release metadata'); }
+      const asset = feed.assets?.[assetName];
+      if (!asset || !/^[a-f0-9]{64}$/i.test(asset.sha256 || '')
+        || typeof asset.url !== 'string' || !asset.url.startsWith('https://github.com/yetone/magpie-releases/releases/download/')) {
+        throw new Error('No verified Magpie CLI release for this platform');
+      }
+      const bytes = await downloadBytes(asset.url, 256 * 1024 * 1024);
+      if (createHash('sha256').update(bytes).digest('hex') !== asset.sha256.toLowerCase()) throw new Error('Magpie CLI checksum mismatch');
+      const target = managedBinary();
+      await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+      const staging = `${target}.${randomBytes(8).toString('hex')}${platform === 'win32' ? '.exe' : ''}`;
+      try {
+        await fs.writeFile(staging, bytes, { mode: 0o700, flag: 'wx' });
+        const version = await run(staging, ['--version'], { env, timeout: 10_000 });
+        if (!/^magpie\s+\S+/m.test(version)) throw new Error('Invalid downloaded Magpie CLI');
+        await fs.rename(staging, target);
+      } finally { await fs.rm(staging, { force: true }); }
+      return publishExecutable(target);
+    })();
+    try { return await installing; }
+    finally { installing = null; }
+  };
+
+  const exclusive = async (work) => {
+    if (busy) throw new Error('Magpie sync already in progress');
+    busy = true;
+    try { return await work(); } finally { busy = false; }
+  };
+  const withTemp = async (work) => {
+    const dir = await fs.mkdtemp(path.join(tempdir(), 'openchamber-magpie-'));
+    try { return await work(path.join(dir, 'setup.magpie-backup')); }
+    finally { await fs.rm(dir, { recursive: true, force: true }); }
+  };
+
+  return {
+    inventory,
+    repairInstallation,
+    download: () => exclusive(async () => {
+      if (!(await inventory()).available) throw new Error('No Magpie configuration found on source');
+      const binary = await ensure();
+      const passphrase = randomBytes(32).toString('hex');
+      return withTemp(async (file) => {
+        await run(binary, ['backup', file], { env, input: `${passphrase}\n` });
+        const stat = await fs.stat(file);
+        if (stat.size > MAX_BYTES) throw new Error('Magpie backup exceeds size limit');
+        const backup = await fs.readFile(file);
+        let authorization;
+        try {
+          const accounts = JSON.parse(await run(binary, ['accounts', '--json'], { env }));
+          authorization = await collectMagpieAuth(await dataDir(binary), accounts);
+        } catch { throw new Error('Unable to export Magpie authorizations'); }
+        const payload = Buffer.from(JSON.stringify({ format: 'magpie-sync-v2', passphrase, backup: backup.toString('base64'), authorization }));
+        if (payload.length > MAX_BYTES * 2) throw new Error('Magpie sync exceeds size limit');
+        return payload;
+      });
+    }),
+    import: (payload) => exclusive(async () => {
+      let decoded;
+      let backup;
+      try {
+        if (payload.length > MAX_BYTES * 2) throw new Error();
+        decoded = JSON.parse(Buffer.from(payload).toString());
+        if (!['magpie-sync-v1', 'magpie-sync-v2'].includes(decoded.format) || !/^[a-f0-9]{64}$/.test(decoded.passphrase)
+          || typeof decoded.backup !== 'string') throw new Error();
+        if (decoded.format === 'magpie-sync-v2') validateMagpieAuth(decoded.authorization);
+        backup = Buffer.from(decoded.backup, 'base64');
+        if (!backup.length || backup.length > MAX_BYTES || JSON.parse(backup.toString()).format !== 'magpie-backup') throw new Error();
+      } catch { throw new Error('Invalid Magpie sync payload'); }
+      const binary = await ensure();
+      return withTemp(async (file) => {
+        await fs.writeFile(file, backup, { mode: 0o600, flag: 'wx' });
+        let output;
+        try { output = await run(binary, ['restore', file], { env, input: `${decoded.passphrase}\n` }); }
+        catch { throw new Error('Magpie restore failed; some configuration may already have been applied. Retry to finish.'); }
+        if (/Couldn't add the plugin/i.test(output)) throw new Error('Magpie restore partially completed: plugin installation failed. Check the target Magpie plugins.');
+        if (/Library:.*couldn't/i.test(output)) throw new Error('Magpie restore partially completed: library application failed. Check the target Magpie library.');
+        if (/Needs a key/i.test(output)) throw new Error('Magpie restore partially completed: some providers still require API keys.');
+        let needsSignIn = /not signed in on this computer/i.test(output);
+        if (decoded.format === 'magpie-sync-v2') {
+          const dir = await dataDir(binary);
+          try {
+            await restoreMagpieAuth(dir, decoded.authorization, async (auth) => {
+              const credentialFile = path.join(path.dirname(file), 'codex.json');
+              try {
+                await fs.writeFile(credentialFile, JSON.stringify(auth), { mode: 0o600, flag: 'wx' });
+                await run(binary, ['accounts', 'import', 'codex', credentialFile, '--yes'], { env });
+              } finally { await fs.rm(credentialFile, { force: true }); }
+            });
+            const accounts = JSON.parse(await run(binary, ['accounts', '--json'], { env }));
+            verifyMagpieAuth(decoded.authorization, accounts);
+            const configured = JSON.parse(await fs.readFile(path.join(dir, 'providers.json'), 'utf8').catch((error) => {
+              if (error.code === 'ENOENT') return '{"providers":[]}';
+              throw error;
+            }));
+            if (!Array.isArray(configured.providers)) throw new Error();
+            const signedIn = new Set(accounts.map((account) => account.agent));
+            needsSignIn = decoded.authorization.incomplete || configured.providers.some((provider) =>
+              !provider.hidden && provider.id && !['chat', 'responses', 'anthropic', 'gemini'].some((key) => provider[key])
+              && !signedIn.has(provider.id));
+            if (/Left as they are/i.test(output)) {
+              output = await run(binary, ['restore', file], { env, input: `${decoded.passphrase}\n` });
+              if (/Couldn't add the plugin|Needs a key|Library:.*couldn't/i.test(output)) throw new Error();
+            }
+          } catch {
+            throw new Error('Magpie authorization sync or verification failed; some configuration and accounts may already be applied. Retry to finish.');
+          }
+        }
+        const magpieWarnings = [];
+        if (needsSignIn) magpieWarnings.push('sign_in_required');
+        if (/Left as they are/i.test(output)) magpieWarnings.push('agent_settings_skipped');
+        return { ok: true, ...(magpieWarnings.length ? { magpieWarnings } : {}) };
+      });
+    }),
+  };
+}