@ours.network/install 1.2.1-nightly.2 → 1.2.1-nightly.4

package/lib/legacy-state.mjs

@@ -0,0 +1,205 @@
+import * as fs from 'node:fs';
+import * as net from 'node:net';
+import { homedir } from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join, resolve, isAbsolute, sep } from 'node:path';
+import { installationPaths } from './plan.mjs';
+import { copyPrivateTree, scanSource } from '../assets/scripts/maintenance/state-archive.mjs';
+import { publishNoReplace } from '../assets/scripts/maintenance/state-native.mjs';
+
+const MARKER = '.ours-legacy-import.json';
+const uid = () => process.getuid();
+const ownership = () => ({ uid: uid(), gid: process.getgid() });
+function canonical(path) {
+  if (typeof path !== 'string' || !isAbsolute(path) || resolve(path) !== path) throw Error('Legacy migration requires normalized absolute paths');
+  let cursor = path;
+  while (true) {
+    try { if (fs.realpathSync(cursor) !== cursor) throw Error('Legacy migration refuses symlink paths'); return path; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; const parent = dirname(cursor); if (parent === cursor) throw error; cursor = parent; }
+  }
+}
+function privatePath(path, directory = false) {
+  canonical(path); const stat = fs.lstatSync(path);
+  if (!(directory ? stat.isDirectory() : stat.isFile()) || stat.uid !== uid()
+    || (stat.mode & 0o7777) !== (directory ? 0o700 : 0o600) || (!directory && stat.nlink !== 1))
+    throw Error('Legacy migration requires private owner-only regular files and directories');
+  return stat;
+}
+function objectFile(path) {
+  privatePath(path); const value = JSON.parse(fs.readFileSync(path, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error('Legacy configuration must be an object');
+  return value;
+}
+const contains = (parent, child) => parent === child || child.startsWith(parent + sep);
+function inspectRoot(stateDir) {
+  const root = objectFile(join(stateDir, 'root.json'));
+  if (root.v !== 1 || typeof root.name !== 'string' || !root.name || root.name !== root.name.trim()
+    || root.name.normalize('NFC') !== root.name || root.name.length > 64 || /[\x00-\x1f\x7f/\\]/.test(root.name)
+    || ['.', '..', 'contact-book', 'root.json', 'bindings.json'].includes(root.name)) throw Error('Legacy root marker is invalid');
+  privatePath(join(stateDir, root.name), true);
+  for (const file of ['identity.key', 'state_data.bin']) if (privatePath(join(stateDir, root.name, file)).size === 0) throw Error('Legacy root identity is incomplete');
+  // CID and hierarchy are packet facts, not fields in root.json. The caller
+  // must compare authenticated identity-list results before/after activation.
+  return root.name;
+}
+export function inspectLegacyState(configPath, targetRoot) {
+  canonical(configPath); canonical(targetRoot);
+  const config = objectFile(configPath);
+  const defaultState = join(homedir(), '.ours');
+  if (config.stateDir === undefined && configPath !== join(defaultState, 'config.json')) throw Error('Custom legacy config requires explicit stateDir');
+  const stateDir = config.stateDir === undefined ? canonical(defaultState) : canonical(config.stateDir);
+  privatePath(stateDir, true);
+  if (contains(stateDir, targetRoot) || contains(targetRoot, stateDir) || contains(targetRoot, configPath)) throw Error('Legacy source and target roots must be disjoint');
+  if (config.database && (typeof config.database !== 'object' || Array.isArray(config.database)
+    || (config.database.provider !== undefined && config.database.provider !== 'sqlite') || config.database.url))
+    throw Error('Legacy migration does not support external or non-SQLite history');
+  const entries = scanSource(stateDir, ownership());
+  if (entries.some(entry => entry.name.split('/').includes('.ours-provenance'))) throw Error('Legacy unmanaged migration does not support existing build provenance');
+  if (entries.some(entry => entry.name.endsWith('/history-postgresql.json'))) throw Error('Legacy migration cannot copy external PostgreSQL history');
+  if (fs.existsSync(join(stateDir, '.mcp'))) privatePath(join(stateDir, '.mcp'), true);
+  if (config.networkMcp !== undefined) {
+    const mcp = config.networkMcp;
+    if (!mcp || typeof mcp !== 'object' || Array.isArray(mcp)
+      || mcp.applicationConfigPath !== join(stateDir, '.mcp/config.json')
+      || !mcp.profile || mcp.profile.credentialPath !== join(stateDir, 'daemon-token'))
+      throw Error('Legacy migration requires embedded MCP configuration and credentials; external MCP paths are unsupported');
+  }
+  if (config.apiTokenDeliveryFiles !== undefined && (!Array.isArray(config.apiTokenDeliveryFiles)
+    || config.apiTokenDeliveryFiles.some(path => path !== join(stateDir, 'daemon-token'))))
+    throw Error('Legacy migration does not support external token delivery paths');
+  return { configPath, stateDir, config, rootCid: null, rootName: inspectRoot(stateDir) };
+}
+const receipt = (source, record) => ({ sourceStateDir: source.stateDir, sourceConfigPath: source.configPath, targetRoot: record.root, rootName: source.rootName });
+function writePrivate(path, value) {
+  fs.writeFileSync(path, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 }); fs.chmodSync(path, 0o600);
+}
+
+function publishLegacyMcp(source, destination, expected, profile) {
+  canonical(destination);
+  if (fs.existsSync(destination)) {
+    privatePath(destination, true);
+    if (fs.existsSync(join(destination, MARKER))) {
+      if (JSON.stringify(objectFile(join(destination, MARKER))) !== JSON.stringify(expected)) throw Error('Legacy MCP destination receipt mismatch');
+      return;
+    }
+    if (fs.readdirSync(destination).length) throw Error('Legacy MCP destination must be absent or empty');
+  }
+  const staging = join(dirname(destination), `.legacy-mcp-${randomUUID()}`);
+  try {
+    const embedded = join(source.stateDir, '.mcp');
+    if (fs.existsSync(embedded)) copyPrivateTree(embedded, staging, ownership());
+    else fs.mkdirSync(staging, { mode: 0o700 });
+    writePrivate(join(staging, 'profile.json'), profile);
+    writePrivate(join(staging, MARKER), expected);
+    scanSource(staging, ownership());
+    if (fs.existsSync(destination)) fs.rmdirSync(destination);
+    publishNoReplace(staging, destination);
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+}
+
+// Caller excludes source writers and owns installation exclusion through activation.
+export function stageLegacyState(source, record) {
+  if (record.schema !== 2 || !['packages', 'docker'].includes(record.mode)
+    || !Number.isInteger(record.port) || record.port < 1 || record.port > 65535) throw Error('Unsupported legacy migration destination');
+  const fresh = inspectLegacyState(source.configPath, record.root);
+  if (fresh.stateDir !== source.stateDir || fresh.rootName !== source.rootName) throw Error('Legacy source selection changed');
+  const paths = installationPaths(record);
+  const destination = paths.daemon, parent = dirname(destination);
+  canonical(destination); privatePath(parent, true);
+  const expected = receipt(fresh, record);
+  if (fs.existsSync(destination)) {
+    privatePath(destination, true);
+    if (fs.existsSync(join(destination, MARKER))) {
+      const saved = objectFile(join(destination, MARKER));
+      if (JSON.stringify(saved) !== JSON.stringify(expected) || inspectRoot(destination) !== fresh.rootName) throw Error('Legacy destination receipt does not match selected source');
+      const mcpReceipt = objectFile(join(paths.mcp, MARKER));
+      if (JSON.stringify(mcpReceipt) !== JSON.stringify(expected)) throw Error('Legacy MCP destination receipt does not match selected source');
+      return { ...expected, destination, reused: true };
+    }
+    if (fs.readdirSync(destination).length) throw Error('Legacy destination must be absent or empty');
+  }
+  const staging = join(parent, `.legacy-${randomUUID()}`);
+  try {
+    copyPrivateTree(fresh.stateDir, staging, ownership());
+    // Preserve the untouched source as the rollback copy. Only copied PID hints
+    // are discarded; opaque identities, authority, SQLite sidecars all survive.
+    for (const name of ['ours-cli-daemon.json', 'daemon.pid', 'startup-progress.json']) fs.rmSync(join(staging, name), { force: true });
+    const config = structuredClone(fresh.config);
+    config.stateDir = record.mode === 'docker' ? '/var/lib/ours' : destination;
+    config.port = record.mode === 'docker' ? 3050 : record.port; config.apiVisibility = 'owner';
+    delete config.apiToken; delete config.apiTokenDeliveryFiles;
+    config.networkMcp = {
+      profile: { endpoint: `http://127.0.0.1:${config.port}`, expectedInstanceId: record.instanceId, credentialPath: join(config.stateDir, 'daemon-token') },
+      applicationConfigPath: record.mode === 'docker' ? '/var/lib/ours-mcp/config.json' : join(paths.mcp, 'config.json'),
+    };
+    // Publish MCP separately before daemon publication. Its receipt allows a
+    // retry after an interrupted second rename, without overwriting live data.
+    publishLegacyMcp(fresh, paths.mcp, expected, config.networkMcp.profile);
+    writePrivate(join(staging, 'config.json'), config); writePrivate(join(staging, MARKER), expected);
+    scanSource(staging, ownership());
+    if (fs.existsSync(destination)) fs.rmdirSync(destination); // succeeds only for the empty skeleton
+    publishNoReplace(staging, destination);
+    return { ...expected, destination, reused: false };
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+}
+
+let Database;
+export async function ensureLegacyLockSupport() {
+  if (!['linux', 'darwin'].includes(process.platform) || typeof process.getuid !== 'function') throw Error('Legacy migration requires Linux/macOS source locking');
+  try { ({ DatabaseSync: Database } = await import('node:sqlite')); }
+  catch { throw Error('Legacy migration requires Node with node:sqlite support; upgrade Node before stopping the source daemon'); }
+}
+
+// Protocol adapted from SDK src/internal/state-root-lock.ts: permanent SQLite
+// guard serializes stale socket probe/unlink/rebind; socket ownership lasts for
+// the callback. Never replace the guard inode or unlink on ambiguous probes.
+function lockDirectory(path) {
+  try { fs.mkdirSync(path, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  privatePath(path, true);
+}
+function probe(path) {
+  return new Promise(resolveProbe => {
+    const socket = net.createConnection(path); let finished = false;
+    const done = result => { if (finished) return; finished = true; socket.destroy(); resolveProbe(result); };
+    socket.setTimeout(1000);
+    socket.once('connect', () => done('live'));
+    socket.once('timeout', () => done('ambiguous'));
+    socket.once('error', error => done(['ECONNREFUSED', 'ENOENT'].includes(error.code) ? 'stale' : 'ambiguous'));
+  });
+}
+async function socketLock(stateDir, path) {
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const server = net.createServer(socket => { socket.on('error', () => {}); socket.end(JSON.stringify({ pid: process.pid, stateDir, startedAt: new Date().toISOString() }) + '\n'); });
+    try {
+      await new Promise((accept, reject) => { server.once('error', reject); server.listen(path, () => { server.removeListener('error', reject); accept(); }); });
+      server.unref(); return server;
+    } catch (error) {
+      try { server.close(); } catch { /* not listening */ }
+      if (error.code !== 'EADDRINUSE') throw error;
+      const result = await probe(path);
+      if (result !== 'stale') throw Error(`Legacy source lock is ${result}; refusing to remove a potentially live owner`);
+      try { fs.unlinkSync(path); } catch (failure) { if (failure.code !== 'ENOENT') throw failure; }
+    }
+  }
+  throw Error('Could not acquire legacy source lock');
+}
+export async function withLegacyStateLock(stateDir, callback) {
+  await ensureLegacyLockSupport(); canonical(stateDir); privatePath(stateDir, true);
+  const base = `/tmp/ours-${uid()}`; lockDirectory(base); lockDirectory(join(base, 'locks'));
+  const path = join(base, 'locks', createHash('sha256').update(stateDir).digest('hex') + '.sock');
+  if (Buffer.byteLength(path) > 103) throw Error('Legacy lock socket path exceeds portable limit');
+  const guardPath = path + '.guard';
+  try { const fd = fs.openSync(guardPath, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600); fs.closeSync(fd); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const before = privatePath(guardPath), guard = new Database(guardPath); let server;
+  try {
+    const after = privatePath(guardPath);
+    if (before.dev !== after.dev || before.ino !== after.ino || before.mode !== after.mode || before.uid !== after.uid) throw Error('Legacy acquisition guard changed');
+    guard.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE'); server = await socketLock(stateDir, path);
+  } finally { guard.close(); }
+  let closed = false;
+  const close = async () => { if (closed) return; closed = true; await new Promise(resolveClose => server.close(resolveClose)); };
+  if (callback === undefined) return { stateDir, close };
+  try { return await callback(); }
+  finally { await close(); }
+}

package/lib/managed-cli.mjs

@@ -0,0 +1,164 @@
+/** Replace only the verified, user-owned npm CLI entry after managed cutover. */
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+
+const marker = '// ours-managed-cli-v1 ';
+const backupName = 'managed-cli-original.json';
+const sha = bytes => createHash('sha256').update(bytes).digest('hex');
+const uid = () => process.getuid();
+function absolute(path) {
+  if (typeof path !== 'string' || !isAbsolute(path) || resolve(path) !== path || /[\r\n\0]/.test(path)) throw new Error('Managed CLI requires normalized absolute paths');
+  return path;
+}
+function owned(path, { directory = false, writable = false } = {}) {
+  const stat = lstatSync(path);
+  if (stat.uid !== uid() || (directory ? !stat.isDirectory() : (!stat.isFile() || stat.nlink !== 1)) || (stat.mode & 0o022)) throw new Error(`Managed CLI refuses foreign or unsafe ownership: ${path}`);
+  if (directory && realpathSync(path) !== path) throw new Error('Managed CLI directory must be canonical');
+  if (writable) {
+    if (!(stat.mode & 0o200)) throw new Error(`Managed CLI path is read-only: ${path}`);
+    accessSync(path, constants.W_OK | (directory ? constants.X_OK : 0));
+  }
+  return stat;
+}
+function snapshot(path) {
+  const stat = lstatSync(path);
+  if (stat.uid !== uid() || (!stat.isSymbolicLink() && (!stat.isFile() || stat.nlink !== 1))) throw new Error('Managed CLI entry is not an owned file or symlink');
+  if (!stat.isSymbolicLink() && (stat.mode & 0o022)) throw new Error('Managed CLI entry is writable by another user');
+  return { kind: stat.isSymbolicLink() ? 'symlink' : 'file', dev: stat.dev, ino: stat.ino, uid: stat.uid, mode: stat.mode & 0o7777,
+    size: stat.size, mtimeMs: stat.mtimeMs, ...(stat.isSymbolicLink() ? { link: readlinkSync(path), resolved: realpathSync(path) } : {}), digest: sha(readFileSync(path)) };
+}
+function readBackup(targetRoot) {
+  const path = join(targetRoot, 'legacy-backup', backupName);
+  owned(dirname(path), { directory: true }); owned(path);
+  const value = JSON.parse(readFileSync(path, 'utf8'));
+  if (value.schema !== 1 || value.targetRoot !== targetRoot || !value.original || typeof value.originalProgram !== 'string') throw new Error('Invalid managed CLI backup');
+  return value;
+}
+
+export function buildManagedCli(recordPath, installerPath) {
+  absolute(recordPath); absolute(installerPath);
+  const binding = { schema: 1, targetRoot: dirname(recordPath), recordPath, installerPath };
+  return `#!/usr/bin/env node
+${marker}${JSON.stringify(binding)}
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const binding = ${JSON.stringify(binding)};
+function fail(message) { console.error('ours: ' + message); process.exit(2); }
+const args = process.argv.slice(2);
+if (args.some(arg => /^(?:--config|--state-dir|--port|--daemon-id|--daemon-url|--endpoint|--credential-path)(?:=|$)/.test(arg))) fail('This command belongs to the managed installation. Use ours-install to select or manage another installation.');
+let record;
+try {
+  const stat = fs.lstatSync(binding.recordPath);
+  if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid() || (stat.mode & 0o077) || fs.realpathSync(binding.recordPath) !== binding.recordPath) throw new Error('unsafe record');
+  record = JSON.parse(fs.readFileSync(binding.recordPath, 'utf8'));
+} catch { fail('The managed installation record is missing or unsafe; repair it with ours-install.'); }
+if (record.schema !== 2 || record.root !== binding.targetRoot || !['packages', 'docker'].includes(record.mode)
+    || typeof record.instanceId !== 'string' || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(record.instanceId)
+    || !Number.isInteger(record.port) || record.port < 1 || record.port > 65535
+    || record.workDir !== path.join(record.root, 'runtime') || record.configPath !== path.join(record.root, 'storage/state/daemon/config.json')
+    || (record.mode === 'docker' && (typeof record.project !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(record.project)))) fail('The managed installation selection is invalid.');
+const env = { ...process.env };
+for (const key of Object.keys(env)) if (key.startsWith('OURS_')) delete env[key];
+const lifecycle = args[0] === 'daemon' && ['start', 'stop', 'restart', 'status'].includes(args[1]);
+const version = args[0] === 'version' || args[0] === '--version' || args[0] === '-V';
+let command, commandArgs;
+if (lifecycle) {
+  if (args.slice(2).some(arg => arg !== '--json') || (args[1] !== 'status' && args.includes('--json'))) fail('Use ours-install server for lifecycle options; --json is supported for status only.');
+  command = process.execPath;
+  commandArgs = [binding.installerPath, 'server', args[1], '--state-dir', record.root];
+} else {
+  if (args[0] === 'daemon') fail('Use ours-install server to manage this installation and its services.');
+  if (args[0] === 'config' && args[1] !== 'show') fail('Use ours-install server to manage configuration and credentials.');
+  if (record.mode === 'docker') {
+    command = 'docker';
+    commandArgs = ['exec', '-i', record.project + '-daemon-1', 'node', '/opt/ours/node_modules/@ours.network/cli/dist/cli.js', ...args];
+    if (!version) commandArgs.push('--config', '/var/lib/ours/config.json', '--state-dir', '/var/lib/ours');
+  } else {
+    command = path.join(record.workDir, 'node_modules/.bin/ours');
+    commandArgs = [...args];
+    if (!version) commandArgs.push('--config', record.configPath, '--state-dir', path.join(record.root, 'storage/state/daemon'));
+    Object.assign(env, { OURS_CONFIG: record.configPath, OURS_STATE_DIR: path.join(record.root, 'storage/state/daemon'), OURS_PORT: String(record.port), OURS_DAEMON_ID: record.instanceId });
+  }
+}
+const result = spawnSync(command, commandArgs, { stdio: 'inherit', env });
+if (result.error) fail('Could not start the managed command: ' + result.error.message);
+if (result.signal) { process.kill(process.pid, result.signal); process.exit(1); }
+process.exit(result.status ?? 1);
+`;
+}
+
+export async function inspectManagedCli(effects, targetRoot) {
+  if (!['linux', 'darwin'].includes(effects.platform?.platform ?? process.platform) || typeof process.getuid !== 'function') throw new Error('Managed CLI cutover supports Linux/macOS only');
+  absolute(targetRoot);
+  const output = async args => {
+    const result = await effects.run(args[0], args.slice(1));
+    if (result.code !== undefined && result.code !== 0) throw new Error('Cannot determine the existing global CLI selection');
+    return absolute(result.stdout.trim());
+  };
+  const npmRoot = await output(['npm', 'root', '--global']);
+  const prefix = await output(['npm', 'prefix', '--global']);
+  const binPath = join(prefix, 'bin', 'ours');
+  const selected = await output(['which', 'ours']);
+  if (selected !== binPath) throw new Error('PATH selects another ours command; select the verified npm global bin before migration');
+  owned(dirname(binPath), { directory: true, writable: true });
+  const packageRoot = realpathSync(join(npmRoot, '@ours.network/cli'));
+  const packagePath = join(packageRoot, 'package.json'); owned(packagePath);
+  const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+  if (pkg.name !== '@ours.network/cli' || typeof pkg.bin?.ours !== 'string') throw new Error('Global package does not declare the expected ours CLI');
+  const originalProgram = realpathSync(resolve(packageRoot, pkg.bin.ours));
+  if (!originalProgram.startsWith(packageRoot + '/')) throw new Error('Global CLI bin escapes its package');
+  owned(originalProgram); accessSync(originalProgram, constants.R_OK | constants.X_OK);
+  const before = snapshot(binPath);
+  let installed = false;
+  let installerPath = fileURLToPath(new URL('../install.mjs', import.meta.url));
+  if (before.kind === 'symlink') {
+    if (before.resolved !== originalProgram) throw new Error('Global ours symlink does not target the verified npm CLI');
+  } else {
+    const contents = readFileSync(binPath, 'utf8');
+    const line = contents.split('\n')[1];
+    if (!line?.startsWith(marker)) throw new Error('Refusing to replace an unknown ours executable');
+    const binding = JSON.parse(line.slice(marker.length));
+    if (binding.schema !== 1 || binding.targetRoot !== targetRoot || binding.recordPath !== join(targetRoot, 'installation.json')) throw new Error('Managed CLI belongs to another installation');
+    installerPath = absolute(binding.installerPath);
+    if (contents !== buildManagedCli(binding.recordPath, installerPath)) throw new Error('Managed CLI launcher was modified');
+    const backup = readBackup(targetRoot);
+    if (backup.binPath !== binPath || backup.originalProgram !== originalProgram) throw new Error('Managed CLI backup selects another original executable');
+    installed = true;
+  }
+  return { schema: 1, targetRoot, binPath, originalProgram, installerPath, before, installed };
+}
+
+export async function installManagedCli(record, cliPlan, effects, { rename = renameSync } = {}) {
+  if (record.root !== cliPlan.targetRoot) throw new Error('Managed CLI target changed after inspection');
+  const fresh = await inspectManagedCli(effects, record.root);
+  if (fresh.binPath !== cliPlan.binPath || fresh.originalProgram !== cliPlan.originalProgram || JSON.stringify(fresh.before) !== JSON.stringify(cliPlan.before)) throw new Error('Global CLI changed after inspection; cutover refused');
+  const installerPath = absolute(cliPlan.installerPath);
+  owned(installerPath);
+  if (realpathSync(installerPath) !== installerPath) throw new Error('Managed installer path must be canonical');
+  if (fresh.installed && fresh.installerPath !== installerPath) throw new Error('Managed installer selection changed after inspection');
+  if (fresh.installed) return { binPath: fresh.binPath, originalProgram: fresh.originalProgram, changed: false };
+  owned(record.root, { directory: true });
+  const backupDir = join(record.root, 'legacy-backup');
+  if (!existsSync(backupDir)) mkdirSync(backupDir, { mode: 0o700 });
+  const backupStat = owned(backupDir, { directory: true });
+  if (backupStat.mode & 0o077) throw new Error('CLI backup directory must be private');
+  const backupPath = join(backupDir, backupName);
+  const backup = { schema: 1, targetRoot: record.root, binPath: fresh.binPath, originalProgram: fresh.originalProgram,
+    original: fresh.before, ...(fresh.before.kind === 'file' ? { bytes: readFileSync(fresh.binPath).toString('base64') } : {}) };
+  if (existsSync(backupPath)) {
+    const original = readBackup(record.root);
+    if (original.binPath !== backup.binPath || original.originalProgram !== backup.originalProgram) throw new Error('Existing CLI backup differs from the selected original');
+  } else writeFileSync(backupPath, JSON.stringify(backup, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  const contents = buildManagedCli(join(record.root, 'installation.json'), installerPath);
+  const temporary = join(dirname(fresh.binPath), `.ours-managed-${randomUUID()}`);
+  try {
+    writeFileSync(temporary, contents, { flag: 'wx', mode: 0o700 }); chmodSync(temporary, 0o755);
+    if (JSON.stringify(snapshot(fresh.binPath)) !== JSON.stringify(fresh.before)) throw new Error('Global CLI changed during cutover');
+    rename(temporary, fresh.binPath);
+  } finally { rmSync(temporary, { force: true }); }
+  return { binPath: fresh.binPath, originalProgram: fresh.originalProgram, changed: true };
+}

package/lib/orchestrate.mjs

@@ -1,3 +1,4 @@
+import { executeLegacyMigration } from './legacy-migration.mjs';
 // ours-install v3 — the orchestrator.
 //
 // This is the part that cannot be pure: it walks the flow, renders the screens
@@ -1250,7 +1251,9 @@ export async function runInstall(argv, effects) {
 
 export async function runServerCommand(args, effects) {
   if (args.operation === 'status') return executeServerCommand(args, effects);
-  return effects.withInstallationLock(args.stateDir, () => executeServerCommand(args, effects));
+  return effects.withInstallationLock(args.stateDir, () => args.migrateFrom
+    ? executeLegacyMigration(args, effects, executeServerCommand)
+    : executeServerCommand(args, effects));
 }
 
 async function executeServerCommand(args, effects) {
@@ -1366,6 +1369,7 @@ async function executeServerCommand(args, effects) {
         layoutConversion: record.schema === 1 ? 'preparation-pending' : 'activation-pending',
       } : {}),
     }));
+    if (args.operation === 'status') return EXIT_OK;
   }
   effects.out(ok(`Server ${args.operation} completed for ${record.root}`));
   return EXIT_OK;