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

package/README.md

@@ -7,9 +7,10 @@ npm install -g @ours.network/install@nightly
 ours-install
 ```
 
-With no arguments, the console form collects the installation choices: server
-and clients (default), runtime mode, installation directory, install/update,
-Human identity name, ports, client integrations and Fleet settings. Linux x64
+With no arguments, the wizard explains each step and offers keyboard choices.
+Use arrow keys and Enter to choose, and Space to select integrations. Recommended
+settings keep advanced ports and package overrides out of the usual flow. Text
+input is used for your name and explicitly customized paths or ports. Linux x64
 recommends native mode; macOS and Windows recommend Docker. On Windows run the
 installer inside WSL with Docker Desktop integration. This recommendation concerns
 packaging and isolation, not a guarantee that emulated x64 is faster on ARM Macs.
@@ -55,6 +56,44 @@ The installer embeds exact component versions and SHA-512 values for its release
 An existing server's retained release selects matching local clients. Secrets are
 read from protected files, and client setup never copies the daemon API master.
 
+## Migrate an existing global installation
+
+The wizard detects the old `~/.ours/config.json` and offers to keep its identities,
+messages, keys and settings in the new installation. It follows the configured
+state directory, including a custom location. An equivalent unattended preset is:
+
+```sh
+ours-install all --mode docker --state-dir "$HOME/ours-docker" \
+  --migrate-from "$HOME/.ours/config.json" --compatible --integrations codex
+```
+
+Run the old daemon before the first migration so the installer can record and
+verify its identities. The new runtime is downloaded/built first. Then the old
+boot service and daemon stop, and the complete daemon state is copied while its
+writer lock is held. Docker migration imports that copy into its named storage
+volume. Existing Human/role names and CIDs must match before applications start;
+migration never creates a replacement Human.
+
+The original state/configuration remain unchanged. A private `legacy-backup`
+directory stores the original config/service definition, and
+`legacy-client/profile.json` is a prepared connection profile for the new server.
+Selected integrations are configured by the usual client setup. The global `ours` command is switched to a launcher for the managed installation
+only after verifying ownership of its existing npm entry; foreign or read-only
+commands are refused before migration. Ordinary `ours identity list` is checked
+after cutover. Lifecycle commands manage the new installation, and selection
+overrides cannot accidentally return to the old daemon. The old configuration is
+not reinterpreted as a client profile. Do not start the old state alongside the
+migrated daemon. Reinstalling the global CLI with npm can replace the launcher;
+repeat the same migration command to verify and repair that routing.
+
+Repeat the same command after an interruption. Once the destination has started,
+retries repair it in place instead of replacing it with an older source snapshot.
+The source is kept stopped after an activation failure to avoid diverging identity
+sessions. Migration requires local Linux/macOS (or WSL) with `node:sqlite` support,
+a verifiable old CLI/service, and a separate target directory. External PostgreSQL
+history or unsupported external MCP/token-delivery paths are refused before
+shutdown. Unrelated application data outside the daemon tree is not copied.
+
 ## Selected network installations (2.0)
 
 The installed package carries its compatible `assets/sources.json` policy.
@@ -71,7 +110,7 @@ ours-install server start --state-dir /private/ours-install
 ours-install server restart --state-dir /private/ours-install
 ```
 
-Choose one mode for a private installation root. The private `installation.json`
+Choose one mode and a folder for its programs and data. The private `installation.json`
 records mode, instance selection, configuration/source paths and service selection;
 it never records master bytes or an issued-token registry. The selected policy
 is resolved to an exact, role-filtered `sources.json` before acquisition.

package/assets/Dockerfile

@@ -21,6 +21,7 @@ COPY scripts/runtime/runtime-common.mjs /opt/ours/docker/runtime-common.mjs
 COPY scripts/runtime/check-client.mjs /opt/ours/docker/check-client.mjs
 COPY scripts/runtime/check-start.mjs /opt/ours/docker/check-start.mjs
 COPY scripts/runtime/client-setup.mjs /opt/ours/docker/client-setup.mjs
+COPY scripts/runtime/legacy-import.mjs /opt/ours/docker/legacy-import.mjs
 COPY scripts/runtime/entrypoint.sh /opt/ours/docker/entrypoint.sh
 COPY scripts/runtime/healthcheck.mjs /opt/ours/docker/healthcheck.mjs
 COPY scripts/runtime/start-telegram.sh scripts/runtime/health-telegram.sh scripts/runtime/start-cowork.sh scripts/runtime/health-cowork.sh scripts/runtime/start-messenger.sh scripts/runtime/health-messenger.mjs /opt/ours/docker/

package/assets/docker-compose.yaml

@@ -177,6 +177,26 @@ services:
       start_period: 30s
       retries: 12
 
+  legacy-import:
+    profiles: [maintenance]
+    build:
+      <<: *source-build
+      target: maintenance
+    platform: linux/amd64
+    image: "${OURS_MAINTENANCE_IMAGE:-ours-compose-2-maintenance:local}"
+    user: "0:0"
+    network_mode: none
+    read_only: true
+    cap_drop: [ALL]
+    cap_add: [CHOWN, DAC_OVERRIDE]
+    security_opt: [no-new-privileges:true]
+    entrypoint: [node, /opt/ours/docker/legacy-import.mjs]
+    environment:
+      OURS_UID: "${OURS_UID:-1000}"
+      OURS_GID: "${OURS_GID:-1000}"
+    volumes:
+      - {type: volume, source: server-storage, target: /storage, volume: {nocopy: true}}
+
   state-operation:
     profiles: [maintenance]
     build:

package/assets/release-lock.json

@@ -565,9 +565,9 @@
       ]
     },
     "node_modules/@anthropic-ai/sdk": {
-      "version": "0.126.0",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.126.0.tgz",
-      "integrity": "sha512-VhiZl6rA/8uC+MgDaOhEcAWaIZ2tPnIY885jlZqxrGrutUW2nqCtophBtlsX0tk5kChBUjV/1NVjL3y0M4OwUg==",
+      "version": "0.127.0",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.127.0.tgz",
+      "integrity": "sha512-OKiVbG9LHCxjn4fBJZJFy/Bz3hqE1RYpwaeSEDNheQnvz0XNKmGT/Lhkz2Sf1a27Ldt3vVv+BkU81I0U/8EpoQ==",
       "license": "MIT",
       "optional": true,
       "peer": true,
@@ -811,9 +811,9 @@
       }
     },
     "node_modules/@fastify/websocket": {
-      "version": "11.3.0",
-      "resolved": "https://registry.npmjs.org/@fastify/websocket/-/websocket-11.3.0.tgz",
-      "integrity": "sha512-g89ag4BCcD9YP5wBZXixzoLnuf5j89p/sXFcfpCiv2pdEkYYukBEoK3heVzqsp0EAtszVDc2BBZG0KZqeAShIA==",
+      "version": "11.3.1",
+      "resolved": "https://registry.npmjs.org/@fastify/websocket/-/websocket-11.3.1.tgz",
+      "integrity": "sha512-3117Fteg0MC9zRl0ilNAQelRb+PNDvNuWe0yJ+jnLthaPPZnlml+GraGpesNUEQvLl8+3C+W4aKZz10XmQ10Mg==",
       "funding": [
         {
           "type": "github",

package/assets/release.json

@@ -1,7 +1,7 @@
 {
   "schema": 1,
   "channel": "nightly",
-  "installerVersion": "1.2.1-nightly.2",
+  "installerVersion": "1.2.1-nightly.3",
   "packages": {
     "@ours.network/sdk": {
       "version": "3.8.1-nightly.3",

package/assets/scripts/runtime/legacy-import.mjs

@@ -0,0 +1,103 @@
+/** Import a stopped, read-only host migration stage into the managed Docker volume. */
+import * as fs from 'node:fs';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+// Repository layout and the maintenance image intentionally place this binding differently.
+const nativeModule = new URL('../maintenance/state-native.mjs', import.meta.url);
+const { publishNoReplace } = await import(fs.existsSync(nativeModule) ? nativeModule.href : new URL('./state-native.mjs', import.meta.url).href);
+
+const MARKER = '.ours-legacy-import.json';
+const COMPONENTS = ['mcp', 'daemon'];
+const fail = message => { throw Error(`Legacy volume import: ${message}`); };
+function canonical(path) {
+  if (typeof path !== 'string' || !isAbsolute(path) || resolve(path) !== path) fail('paths must be normalized absolute paths');
+  if (fs.realpathSync(path) !== path) fail('symlink paths are not supported');
+}
+function privateEntry(path, uid, gid, directory) {
+  const stat = fs.lstatSync(path);
+  if (!(directory ? stat.isDirectory() : stat.isFile()) || stat.isSymbolicLink()
+    || stat.uid !== uid || stat.gid !== gid
+    || (directory ? (stat.mode & 0o7777) !== 0o700 : ((stat.mode & 0o7077) !== 0 || !(stat.mode & 0o400)))
+    || (!directory && stat.nlink !== 1)) fail('unsafe ownership, permissions, or linked state entry');
+  return stat;
+}
+function scan(root, uid, gid) {
+  const entries = [];
+  function visit(path, relative) {
+    const stat = fs.lstatSync(path), directory = stat.isDirectory();
+    privateEntry(path, uid, gid, directory); entries.push({ relative, directory, mode: stat.mode & 0o700 });
+    if (directory) for (const name of fs.readdirSync(path).sort()) visit(join(path, name), relative ? join(relative, name) : name);
+  }
+  canonical(root); visit(root, ''); return entries;
+}
+function readReceipt(root, uid, gid, targetRoot) {
+  privateEntry(join(root, MARKER), uid, gid, false);
+  const value = JSON.parse(fs.readFileSync(join(root, MARKER), 'utf8'));
+  const keys = ['sourceStateDir', 'sourceConfigPath', 'targetRoot', 'rootName'];
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0') !== [...keys].sort().join('\0')
+    || keys.some(key => typeof value[key] !== 'string' || !value[key])
+    || value.targetRoot !== targetRoot
+    || ['sourceStateDir', 'sourceConfigPath', 'targetRoot'].some(key => !isAbsolute(value[key]) || resolve(value[key]) !== value[key])) fail('invalid or mismatched migration receipt');
+  return Object.fromEntries(keys.map(key => [key, value[key]]));
+}
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function existingDestination(path, expected, uid, gid, targetRoot) {
+  if (!fs.existsSync(path)) return false;
+  canonical(path); privateEntry(path, uid, gid, true);
+  if (!fs.readdirSync(path).length) return false;
+  if (!fs.existsSync(join(path, MARKER)) || !same(readReceipt(path, uid, gid, targetRoot), expected)) fail('nonmatching existing destination');
+  return true;
+}
+function makeDirectory(path, uid, gid) {
+  if (!fs.existsSync(path)) { fs.mkdirSync(path, { mode: 0o700 }); fs.chownSync(path, uid, gid); }
+  canonical(path); privateEntry(path, uid, gid, true);
+}
+
+/** Caller holds installation exclusion and has stopped all destination writers. */
+export function importLegacyVolume({ sourceRoot = '/legacy-import', storageRoot = '/storage', targetRoot, uid, gid }) {
+  if (![uid, gid].every(value => Number.isSafeInteger(value) && value >= 0)) fail('numeric target UID/GID required');
+  if (typeof targetRoot !== 'string' || !isAbsolute(targetRoot) || resolve(targetRoot) !== targetRoot) fail('expected target root required');
+  canonical(sourceRoot); canonical(storageRoot);
+  const sourceOwner = fs.lstatSync(sourceRoot);
+  privateEntry(sourceRoot, sourceOwner.uid, sourceOwner.gid, true);
+  const sources = COMPONENTS.map(component => {
+    const path = join(sourceRoot, component);
+    const entries = scan(path, sourceOwner.uid, sourceOwner.gid);
+    return { component, path, entries, receipt: readReceipt(path, sourceOwner.uid, sourceOwner.gid, targetRoot) };
+  });
+  if (!same(sources[0].receipt, sources[1].receipt)) fail('source daemon and MCP receipts differ');
+  const rootStat = fs.lstatSync(storageRoot);
+  const freshRoot = rootStat.isDirectory() && rootStat.uid === 0 && rootStat.gid === 0 && fs.readdirSync(storageRoot).length === 0;
+  if (!freshRoot) privateEntry(storageRoot, uid, gid, true);
+  const state = join(storageRoot, 'state');
+  if (fs.existsSync(state)) { canonical(state); privateEntry(state, uid, gid, true); }
+  // Validate every existing destination before changing even an empty volume.
+  for (const source of sources) source.reused = existingDestination(join(state, source.component), source.receipt, uid, gid, targetRoot);
+  if (freshRoot) { fs.chmodSync(storageRoot, 0o700); fs.chownSync(storageRoot, uid, gid); }
+  makeDirectory(state, uid, gid);
+  for (const source of sources) {
+    if (source.reused) continue;
+    const destination = join(state, source.component), staging = join(state, `.legacy-import-${randomUUID()}`);
+    try {
+      fs.cpSync(source.path, staging, { recursive: true, errorOnExist: true, force: false });
+      for (const entry of [...source.entries].reverse()) {
+        const path = entry.relative ? join(staging, entry.relative) : staging;
+        fs.chmodSync(path, entry.mode); fs.chownSync(path, uid, gid);
+      }
+      scan(staging, uid, gid);
+      if (!same(readReceipt(staging, uid, gid, targetRoot), source.receipt)) fail('copied receipt changed');
+      if (fs.existsSync(destination)) fs.rmdirSync(destination); // empty skeleton only
+      publishNoReplace(staging, destination);
+    } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+  }
+  return { imported: sources.filter(source => !source.reused).map(source => source.component), retained: sources.filter(source => source.reused).map(source => source.component) };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    importLegacyVolume({ targetRoot: process.env.OURS_LEGACY_TARGET_ROOT, uid: Number(process.env.OURS_UID), gid: Number(process.env.OURS_GID) });
+    console.log('Legacy daemon and MCP state imported into the selected volume.');
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/assets/sources.json

@@ -2,7 +2,7 @@
   "release": {
     "schema": 1,
     "channel": "nightly",
-    "installerVersion": "1.2.1-nightly.2",
+    "installerVersion": "1.2.1-nightly.3",
     "packages": {
       "@ours.network/sdk": {
         "version": "3.8.1-nightly.3",

package/lib/effects.mjs

@@ -21,7 +21,7 @@ import { maintenanceServices, installationPaths, validateInstallation, consumerS
 import { validateHostProfile } from './target.mjs';
 import { createServerOnboarding } from './server-onboarding.mjs';
 import { atomicWriteConfig, snapshotConfig, restoreConfig } from './config.mjs';
-import { askYesNo, askLine as askLineOnTty } from './prompt.mjs';
+import { select as selectOnTty, multiselect as multiselectOnTty, askLine as askLineOnTty } from './prompt.mjs';
 import { classifyHarnessProbe } from './logic.mjs';
 import { classifyStateDir } from './detect.mjs';
 import { BASE_RECORDS, CONTEXT, readBuildRecords, equalBuildRecords, initializeBuildMarker } from '../assets/scripts/maintenance/build-context.mjs';
@@ -444,7 +444,9 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
     hasClaudePlugin,
     out: out ?? ((line) => process.stdout.write(`${line}\n`)),
     // Never called when assumeYes: the orchestrator takes the default itself.
-    ask: async (prompt, def = false) => (ttyFd == null ? def : askYesNo(write, ttyFd, `  ${prompt}  `, def)),
+    select: async (question, choices, def) => selectOnTty(write, ttyFd, question, choices, def),
+    multiselect: async (question, choices, defaults = []) => multiselectOnTty(write, ttyFd, question, choices, defaults),
+    ask: async (question, def = false) => selectOnTty(write, ttyFd, question, [{ value: true, label: 'Yes' }, { value: false, label: 'No' }], def),
     askLine: async (prompt, def = '') => (ttyFd == null ? def : askLineOnTty(write, ttyFd, `  ${prompt}  `, def)),
   };
   return Object.assign(effects, networkEffects(effects));
@@ -680,7 +682,17 @@ export function networkEffects(effects) {
         }
       }
     },
-    async initializeSelection(record, manifest) {
+    async prepareLegacyDockerImport(record) {
+      if (record.mode === 'docker') await compose(record, ['build', 'legacy-import'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
+    },
+    async importLegacyDockerState(record) {
+      if (record.mode !== 'docker') return;
+      const source = join(record.root, 'storage', 'state');
+      if (source.includes(':')) throw new Error('Docker migration requires an installation path without colon characters');
+      await compose(record, ['run', '--rm', '--no-deps', '-T', '--volume', `${source}:/legacy-import:ro`,
+        '--env', `OURS_LEGACY_TARGET_ROOT=${record.root}`, 'legacy-import']);
+    },
+    async initializeSelection(record, manifest, { retainConfig = false } = {}) {
       if (typeof manifest === 'string') manifest = JSON.parse(readFileSync(manifest, 'utf8'));
       selectSourcePackages(manifest, 'server');
       const bytes = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
@@ -688,8 +700,9 @@ export function networkEffects(effects) {
       if (record.schema === 2) {
         for (const path of [join(record.root, 'storage'), installationPaths(record).state, installationPaths(record).daemon]) ensurePrivateDirectory(path);
       }
-      writePrivateNew(record.sourcesPath, bytes);
-      writePrivateNew(record.configPath, JSON.stringify({ stateDir: record.mode === 'docker' ? '/var/lib/ours' : installationPaths(record).daemon, port: record.port, apiVisibility: 'owner' }, null, 2) + '\n');
+      if (!retainConfig || !existsSync(record.sourcesPath)) writePrivateNew(record.sourcesPath, bytes);
+      else if (!readFileSync(record.sourcesPath).equals(bytes)) throw new Error('Migration source selection changed');
+      if (!retainConfig) writePrivateNew(record.configPath, JSON.stringify({ stateDir: record.mode === 'docker' ? '/var/lib/ours' : installationPaths(record).daemon, port: record.port, apiVisibility: 'owner' }, null, 2) + '\n');
     },
     async prepareInstallation(record, { runtimeOnly = false } = {}) {
       let copied = false;

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