@ours.network/install 1.2.0-nightly.2 → 1.2.1-nightly.10

package/lib/legacy-migration.mjs

@@ -0,0 +1,202 @@
+/** Local-only migration: preserve opaque daemon state and retire its old launcher. */
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inspectLegacyState, stageLegacyState, withLegacyStateLock, ensureLegacyLockSupport } from './legacy-state.mjs';
+import { inspectManagedCli, installManagedCli } from './managed-cli.mjs';
+import { atomicWriteConfig } from './config.mjs';
+import { classifyUnit, unitPathForStateDir, validateInstallation } from './plan.mjs';
+
+const journalPath = root => join(root, 'legacy-migration.json');
+const parse = result => JSON.parse(result.stdout);
+const phases = ['prepared', 'stopped', 'copied', 'activating', 'verified', 'complete'];
+function readJournal(root) {
+  const path = journalPath(root);
+  if (!existsSync(path)) return null;
+  const j = JSON.parse(readFileSync(path));
+  if (j.schema !== 1 || j.targetRoot !== root || !phases.includes(j.phase) || !Array.isArray(j.identities)) throw new Error('Invalid legacy migration journal');
+  return j;
+}
+function selection(source) {
+  return { env: { OURS_CONFIG: source.configPath, OURS_STATE_DIR: source.stateDir, OURS_PORT: String(source.config.port ?? 3050), OURS_API_TOKEN: undefined, OURS_DAEMON_ID: undefined, OURS_DAEMON_URL: undefined, OURS_DAEMON_CREDENTIAL_PATH: undefined }, sensitive: true };
+}
+async function oldCommand(effects, source, args, options = {}) {
+  return effects.run(source.originalProgram ?? 'ours', [...args, '--config', source.configPath, '--state-dir', source.stateDir, '--json'], { ...selection(source), ...options });
+}
+function validateIdentities(rows, source) {
+  if (!Array.isArray(rows) || !rows.length || rows.some(r => !['root', 'role'].includes(r.kind) || typeof r.cid !== 'string' || !r.cid || typeof r.name !== 'string')) throw new Error('Legacy identities are not fully restored; migration requires a healthy source daemon');
+  const roots = rows.filter(r => r.kind === 'root');
+  if (roots.length !== 1 || roots[0].name !== source.rootName) throw new Error('Legacy Human identity does not match its stored root');
+  return rows.map(({ name, kind, cid }) => ({ name, kind, cid })).sort((a,b) => a.name.localeCompare(b.name));
+}
+
+export async function inspectLegacyMigration(options, effects, deps = {}) {
+  const inspect = deps.inspectLegacyState ?? inspectLegacyState;
+  await (deps.ensureLegacyLockSupport ?? ensureLegacyLockSupport)();
+  const cliPlan = options.dryRun ? null : await (deps.inspectManagedCli ?? inspectManagedCli)(effects, options.stateDir);
+  const journal = readJournal(options.stateDir);
+  if (journal) {
+    if (journal.sourceConfig !== options.migrateFrom) throw new Error('Another legacy source is already selected for this target');
+    return { journal, cliPlan, source: journal.phase === 'complete' ? null : { ...inspect(options.migrateFrom, options.stateDir), originalProgram: cliPlan?.originalProgram } };
+  }
+  const source = { ...inspect(options.migrateFrom, options.stateDir), originalProgram: cliPlan?.originalProgram };
+  if (options.mode === 'docker' && options.stateDir.includes(':')) throw new Error('Docker migration requires an installation path without colon characters');
+  if (effects.readJson(join(options.stateDir, 'installation.json'))) throw new Error('Legacy migration requires a new managed installation root');
+  if (existsSync(options.stateDir) && readdirSync(options.stateDir).length) throw new Error('Legacy migration target must be empty');
+  if (options.dryRun) return { source, journal: { schema: 1, sourceConfig: source.configPath, sourceStateDir: source.stateDir, targetRoot: options.stateDir, phase: 'prepared', identities: [], service: null } };
+  // The owning CLI verifies endpoint, process and state directory. No PID guessing.
+  const status = parse(await oldCommand(effects, source, ['daemon', 'status']));
+  if (status.state !== 'running' || status.stateDir !== source.stateDir) throw new Error('Start the legacy daemon before migration so its identities can be verified');
+  const identities = validateIdentities(parse(await oldCommand(effects, source, ['identity', 'list'])), source);
+  const service = parse(await oldCommand(effects, source, ['daemon', 'uninstall-service', '--dry-run']));
+  if (service.conflict) {
+    const legacy = effects.platform?.platform === 'linux' && source.stateDir === join(effects.home, '.ours')
+      ? unitPathForStateDir(source.stateDir, effects.home) : null;
+    if (!legacy?.ok || legacy.path !== service.serviceFile || classifyUnit(effects.readText(legacy.path)).kind !== 'legacy') {
+      throw new Error('Legacy boot service ownership could not be verified: ' + service.conflict.message);
+    }
+    service.legacyUnit = legacy.unit;
+  }
+  return { source, cliPlan, journal: { schema: 1, sourceConfig: source.configPath, sourceStateDir: source.stateDir, targetRoot: options.stateDir,
+    phase: 'prepared', identities, service, sourcePort: source.config.port ?? 3050 } };
+}
+
+export async function prepareMigrationCliRuntime(record, effects) {
+  const root = join(record.root, 'launcher-runtime');
+  const entry = join(root, 'node_modules', '@ours.network', 'install', 'install.mjs');
+  const ready = join(root, '.ready');
+  if (existsSync(ready) && existsSync(entry)) return entry;
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  effects.out('Preparing permanent management commands so ours will keep working after this installer exits.');
+  const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+  const packed = parse(await effects.run('npm', ['pack', packageRoot, '--ignore-scripts', '--pack-destination', root, '--json']));
+  if (!Array.isArray(packed) || packed.length !== 1 || typeof packed[0].filename !== 'string' || basename(packed[0].filename) !== packed[0].filename) throw new Error('Cannot prepare the persistent installer package');
+  await effects.run('npm', ['install', '--prefix', root, '--prefer-offline', '--ignore-scripts', '--no-audit', '--no-fund', join(root, packed[0].filename)], { stream: true });
+  if (!existsSync(entry)) throw new Error('Persistent installer entry is missing');
+  await effects.run(process.execPath, [entry, '--help']);
+  atomicWriteConfig(ready, 'ready\n');
+  return entry;
+}
+
+/** Called under the normal installation lock; retries never overwrite imported state. */
+export async function executeLegacyMigration(args, effects, install, deps = {}) {
+  const stage = deps.stageLegacyState ?? stageLegacyState;
+  const lock = deps.withLegacyStateLock ?? withLegacyStateLock;
+  const save = (root, value) => (deps.atomicWriteConfig ?? atomicWriteConfig)(journalPath(root), JSON.stringify(value, null, 2) + '\n');
+  const prepareCli = deps.prepareMigrationCliRuntime ?? prepareMigrationCliRuntime;
+  const inspected = args.legacyPlan ?? await inspectLegacyMigration(args, effects, deps);
+  let journal = readJournal(args.stateDir) ?? inspected.journal;
+  if (journal.phase === 'complete') {
+    const retained = effects.readJson(join(args.stateDir, 'installation.json'));
+    inspected.cliPlan.installerPath = await prepareCli(retained, effects);
+    await (deps.installManagedCli ?? installManagedCli)(retained, inspected.cliPlan, effects);
+    const rows = validateIdentities(parse(await effects.run('ours', ['identity', 'list', '--json'])), { rootName: journal.identities.find(row => row.kind === 'root')?.name });
+    if (JSON.stringify(rows) !== JSON.stringify(journal.identities)) throw new Error('Completed migration identity verification failed; no replacement Human was created');
+    effects.out('Legacy migration already completed; retained identities verified.');
+    return 0;
+  }
+  const source = inspected.source;
+  let record;
+  let sourceLock;
+  let activationAttempted = phases.indexOf(journal.phase) >= phases.indexOf('activating');
+  const wrapped = { ...effects,
+    newInstallation(root, mode) {
+      if (journal.record) {
+        if (journal.record.root !== root || journal.record.mode !== mode) throw new Error('Migration target selection changed');
+        return validateInstallation(journal.record, root);
+      }
+      return effects.newInstallation(root, mode);
+    },
+    async initializeSelection(selected, manifest) {
+      record = selected;
+      selected.legacyMigrationSource = args.migrateFrom;
+      journal.record = selected;
+      journal.sourcePolicy = args.sourcePolicy;
+      journal.sourceManifest = manifest;
+      save(selected.root, journal);
+      effects.writeJson(join(selected.root, 'installation.json'), JSON.stringify(selected, null, 2) + '\n');
+      await effects.initializeSelection(selected, manifest, { retainConfig: true });
+    },
+    async serverPreflight(selected, operation, options) {
+      if (journal.record && !existsSync(selected.sourcesPath)) {
+        if (!journal.sourceManifest) throw new Error('Migration journal lacks its retained package selection');
+        await effects.initializeSelection(selected, journal.sourceManifest, { retainConfig: true });
+      }
+      return effects.serverPreflight(selected, operation, options);
+    },
+    async prepareInstallation(selected) {
+      record = selected;
+      if (!existsSync(selected.sourcesPath)) {
+        const manifest = journal.sourceManifest ?? await effects.resolveSourcePolicy(args.sourcePolicy, 'server');
+        await effects.initializeSelection(selected, manifest, { retainConfig: true });
+      }
+      await effects.prepareInstallation(selected, { runtimeOnly: true });
+      if (selected.mode === 'docker') await effects.prepareLegacyDockerImport(selected);
+      inspected.cliPlan.installerPath = await prepareCli(selected, effects);
+      journal.cliInstallerPath = inspected.cliPlan.installerPath;
+      if (activationAttempted) await effects.serverLifecycle(selected, 'stop');
+      // Backups contain secrets; the enclosing installation is private.
+      const backup = join(selected.root, 'legacy-backup');
+      mkdirSync(backup, { mode: 0o700, recursive: true });
+      const configBackup = join(backup, 'config.json');
+      if (!existsSync(configBackup)) writeFileSync(configBackup, readFileSync(source.configPath), { flag: 'wx', mode: 0o600 });
+      if (journal.service.serviceFile && existsSync(journal.service.serviceFile) && !existsSync(join(backup, 'service'))) {
+        writeFileSync(join(backup, 'service'), readFileSync(journal.service.serviceFile), { flag: 'wx', mode: 0o600 });
+      }
+      save(selected.root, journal);
+      if (!activationAttempted) {
+        effects.out('Migration: retire the old boot service and stop its daemon.');
+        if (journal.service.legacyUnit) await effects.run('systemctl', ['--user', 'disable', '--now', journal.service.legacyUnit]);
+        else await oldCommand(effects, source, ['daemon', 'uninstall-service', '--yes']);
+        await oldCommand(effects, source, ['daemon', 'stop']);
+        journal.phase = 'stopped'; save(selected.root, journal);
+      }
+      // Hold the SDK-compatible owner lock until activation finishes, including failures.
+      sourceLock = await lock(source.stateDir);
+      effects.out('Migration: copy retained identities, keys, history and session state.');
+      stage(source, selected);
+      if (selected.mode === 'docker') await effects.importLegacyDockerState(selected);
+      if (!activationAttempted) { journal.phase = 'copied'; save(selected.root, journal); }
+      await effects.prepareInstallation(selected);
+    },
+    async serverLifecycle(selected, operation, services) {
+      if (operation === 'start') {
+        activationAttempted = true;
+        journal.phase = 'activating'; save(selected.root, journal);
+      }
+      return effects.serverLifecycle(selected, operation, services);
+    },
+    async serverEnsureIdentity(selected) {
+      const rows = await effects.serverListIdentities(selected);
+      const actual = validateIdentities(rows, source);
+      if (JSON.stringify(actual) !== JSON.stringify(journal.identities)) throw new Error('Migrated identities differ from the source; no replacement Human was created');
+      journal.phase = 'verified'; save(selected.root, journal);
+      const root = actual.find(r => r.kind === 'root');
+      return { ...root, created: false };
+    },
+  };
+  try {
+    const result = await install({ ...args, migrate: true }, wrapped);
+    if (result !== 0) throw new Error('Migrated server setup did not complete');
+    // Publish an explicit host profile; a daemon --config file is not a client profile.
+    const directory = join(record.root, 'legacy-client');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const credentialPath = join(directory, 'credential');
+    if (!existsSync(credentialPath)) await effects.serverAccess(record, 'access-issue', { output: credentialPath });
+    const profile = { endpoint: `http://127.0.0.1:${record.port}`, expectedInstanceId: record.instanceId, credentialPath };
+    atomicWriteConfig(join(directory, 'profile.json'), JSON.stringify(profile, null, 2) + '\n');
+    await (deps.installManagedCli ?? installManagedCli)(record, inspected.cliPlan, effects);
+    const defaultRows = validateIdentities(parse(await effects.run('ours', ['identity', 'list', '--json'])), source);
+    if (JSON.stringify(defaultRows) !== JSON.stringify(journal.identities)) throw new Error('Default ours command does not select the migrated identities');
+    journal.phase = 'complete'; save(record.root, journal);
+    effects.out(`Migration complete. Original state remains at ${source.stateDir}; original config/service are backed up in ${join(record.root, 'legacy-backup')}. Do not start the original state alongside the migrated daemon.`);
+    return 0;
+  } catch (error) {
+    if (record && activationAttempted) {
+      try { await effects.serverLifecycle(record, 'stop'); }
+      catch { throw new Error(`Migration activation failed and destination shutdown could not be confirmed. Keep the source stopped; repair this same target. ${error.message}`); }
+      throw new Error(`Migration paused after activation; source remains stopped to avoid diverging identity sessions. Repeat the same migration command to repair the retained target. ${error.message}`);
+    }
+    throw new Error(`Migration paused before activation; source data is retained. Repeat the same migration command. ${error.message}`);
+  } finally { await sourceLock?.close(); }
+}

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 };
+}