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

package/lib/effects.mjs

@@ -13,14 +13,15 @@
 
 import { spawnSync, execFileSync } from 'node:child_process';
 import { chmodSync, closeSync, constants, cpSync, existsSync, fstatSync, lstatSync, openSync, readFileSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { homedir, userInfo, platform as osPlatform, release as osRelease } from 'node:os';
+import { homedir, userInfo, platform as osPlatform, release as osRelease, arch as osArch } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { randomUUID, createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { maintenanceServices, installationPaths, validateInstallation, consumerServiceState, unitNameForStateDir, launchdLabelForStateDir, messengerServicePlan, selectSourcePackages, resolveSourcePolicy, SERVER_SERVICES } from './plan.mjs';
 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';
@@ -333,7 +334,7 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
     version,
     interactive: ttyFd != null,
     // Preflight reads the machine rather than asking the orchestrator to.
-    platform: { platform: osPlatform(), release: osRelease() },
+    platform: { platform: osPlatform(), release: osRelease(), arch: osArch() },
     nodeVersion: process.versions.node,
     exists: (path) => existsSync(path),
     knownStateDirs: () => knownStateDirsIn(home),
@@ -413,7 +414,12 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
         stdio: [...(stream ? ['ignore', 'inherit', 'inherit'] : ['ignore', 'pipe', 'pipe']), ...(installationLockFd === null ? [] : [installationLockFd])],
         env: childEnv,
       });
-      if (r.error || (r.status !== 0 && !allowCodes.includes(r.status))) {
+      if (r.error) {
+        const error = new Error(`${executable} could not start (${r.error.code ?? 'launch error'})`, { cause: r.error });
+        error.code = r.error.code;
+        throw error;
+      }
+      if (r.status !== 0 && !allowCodes.includes(r.status)) {
         const detail = sensitive ? '' : (r.stderr || r.stdout || '').trim().split('\n').slice(-3).join('; ');
         throw new Error(`${executable} ${args.join(' ')} exited ${r.status}${detail ? `: ${detail}` : ''}`);
       }
@@ -438,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));
@@ -533,12 +541,30 @@ export function networkEffects(effects) {
     OURS_MESSENGER_PORT: String(record.messengerPort ?? 8420),
     OURS_MESSENGER_IDENTITY: record.messengerIdentity ?? '',
   });
-  const compose = (record, args, options = {}) => effects.run('docker', [
+  const composeArgs = (record, args) => [
     'compose', '--project-directory', record.workDir, '--file', join(record.workDir,
       record.schema === 1 && existsSync(join(record.workDir, 'docker-compose.legacy.yaml'))
         ? 'docker-compose.legacy.yaml' : 'docker-compose.yaml'),
     '--project-name', record.project, ...args,
-  ], { ...options, env: { ...baseEnv(record), ...options.env } });
+  ];
+  const compose = (record, args, options = {}) => effects.run('docker', composeArgs(record, args),
+    { ...options, env: { ...baseEnv(record), ...options.env } });
+  const dockerStartupError = async (record, service, cause) => {
+    const args = ['logs', '--no-color', '--tail', '50', '--timestamps', service];
+    const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+    const command = `OURS_DAEMON_ID=${quote(record.instanceId)} docker ${composeArgs(record, args).map(quote).join(' ')}`;
+    let detail;
+    try {
+      const logs = await compose(record, args);
+      // Limit terminal diagnostics; container output must not inject terminal controls.
+      detail = (logs.stdout ?? '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '').trim().slice(-6000);
+      detail = detail ? `Recent ${service} logs:\n${detail}` : 'The container produced no readable logs.';
+    } catch {
+      detail = 'Container logs could not be read.';
+    }
+    return new Error(`Docker service "${service}" failed to start or become healthy.\n${detail}\nStartup error: ${cause.message}\nInspect logs: ${command}`, { cause });
+  };
   const bin = (record, name) => join(record.workDir, 'node_modules', '.bin', name);
   const localEnv = (record, service = 'daemon') => {
     const paths = installationPaths(record);
@@ -566,6 +592,7 @@ export function networkEffects(effects) {
     }
   };
   return {
+    ...createServerOnboarding(effects, { compose, localEnv, bin }),
     sourcePolicyHash(path) {
       return createHash('sha256').update(readFileSync(path)).digest('hex');
     },
@@ -601,7 +628,7 @@ export function networkEffects(effects) {
       const project = `ours-${createHash('sha256').update(root).digest('hex').slice(0, 16)}`;
       return { schema: 2, root, mode, instanceId, project, workDir: join(root, 'runtime'), configPath: installationPaths({ schema: 2, root }).config, sourcesPath: join(root, 'sources.json'), services: [...SERVER_SERVICES], port: 3050, coworkPort: 3052, messengerPort: 8420, messengerIdentity: env.OURS_MESSENGER_IDENTITY || null, uid: 1000, gid: 1000 };
     },
-    async serverPreflight(record, operation, { existing, sourcePath = record.sourcesPath, sourceManifest } = {}) {
+    async serverPreflight(record, operation, { existing, sourcePath = record.sourcesPath, sourceManifest, identityName } = {}) {
       if (existing) {
         privateDirectory(record.root);
         assertPrivateRegularFile(join(record.root, 'installation.json'), 'selection');
@@ -609,10 +636,34 @@ export function networkEffects(effects) {
         if (env.OURS_DAEMON_ID && env.OURS_DAEMON_ID !== record.instanceId) throw new Error('Conflicting instance ID');
       }
       if (record.mode === 'docker') {
-        await effects.run('docker', ['info', '--format', '{{.ServerVersion}}']);
-        const version = await effects.run('docker', ['compose', 'version', '--short']);
+        const nativeRoot = existing ? '/path/to/new-empty-directory' : record.root;
+        const quotedRoot = `'${String(nativeRoot).replaceAll("'", "'\\''")}'`;
+        const quotedName = `'${String(identityName ?? record.messengerIdentity ?? 'Your Name').replaceAll("'", "'\\''")}'`;
+        const recovery = [
+          'Please install Docker Desktop on macOS/Windows, or Docker Engine with the Compose plugin on Linux, and start Docker before retrying.',
+          'Docker is recommended for macOS and Windows.',
+          `Alternatively, use native installation: ours-install server install --mode packages --state-dir ${quotedRoot} --identity-name ${quotedName}`,
+          'Native mode requires systemd user services on Linux/WSL or a launchd GUI session on macOS.',
+          ...(existing ? ['Keep this existing Docker installation in Docker mode; use a separate empty directory for a new native installation.'] : []),
+        ].join('\n');
+        try {
+          await effects.run('docker', ['info', '--format', '{{.ServerVersion}}']);
+        } catch (cause) {
+          const problem = cause.code === 'ENOENT'
+            ? 'Docker command was not found in PATH.'
+            : `Docker Engine is not reachable. Start Docker and check that your user can access it.\nDetails: ${cause.message}`;
+          throw new Error(`${problem}\n${recovery}`, { cause });
+        }
+        let version;
+        try {
+          version = await effects.run('docker', ['compose', 'version', '--short']);
+        } catch (cause) {
+          throw new Error(`Docker Compose 2.35 or newer is required, but the Compose plugin could not run. Update Docker Desktop or install the Docker Compose plugin.\n${recovery}`, { cause });
+        }
         const match = /^v?(\d+)\.(\d+)/.exec(version.stdout.trim());
-        if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 35)) throw new Error('Docker Compose 2.35 or newer is required');
+        if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 35)) {
+          throw new Error(`Docker Compose 2.35 or newer is required. Update Docker Desktop or the Docker Compose plugin.\n${recovery}`);
+        }
         if (operation !== 'status') {
           // Compose clients can disappear while their Engine-owned command continues.
           const active = await effects.run('docker', ['ps', '--filter', `label=com.docker.compose.project=${record.project}`, '--filter', 'label=com.docker.compose.oneoff=True', '--format', '{{.ID}}']);
@@ -631,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`);
@@ -639,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;
@@ -659,7 +721,7 @@ export function networkEffects(effects) {
         const { dependencies } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
         writeFileSync(join(record.workDir, 'scripts/maintenance/package.json'), JSON.stringify({ private: true, type: 'module', dependencies }, null, 2) + '\n', { mode: 0o600 });
         const image = await effects.run('docker', ['image', 'inspect', `${record.project}:runtime`], { allowCodes: [1] });
-        if (image.code !== 0) await compose(record, ['build', 'daemon']);
+        if (image.code !== 0) await compose(record, ['build', 'daemon'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
         if (runtimeOnly) return;
         await compose(record, ['run', '--rm', '--no-deps', '-T', 'prepare', 'prepare']);
       } else {
@@ -667,8 +729,8 @@ export function networkEffects(effects) {
           const sourceRoot = join(record.root, `build-${randomUUID()}`);
           ensurePrivateDirectory(sourceRoot);
           try {
-            await effects.run(process.execPath, [join(record.workDir, 'scripts/build/build.mjs')], { cwd: record.workDir, env: { OURS_BUILD_ROOT: record.workDir, OURS_SOURCE_ROOT: sourceRoot } });
-            await effects.run('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], { cwd: record.workDir });
+            await effects.run(process.execPath, [join(record.workDir, 'scripts/build/build.mjs')], { stream: true, cwd: record.workDir, env: { OURS_BUILD_ROOT: record.workDir, OURS_SOURCE_ROOT: sourceRoot } });
+            await effects.run('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], { stream: true, cwd: record.workDir });
             await effects.run(process.execPath, [join(record.workDir, 'scripts/build/record-build.mjs')], { cwd: record.workDir, env: { OURS_BUILD_ROOT: record.workDir } });
             writePrivateNew(join(record.workDir, '.packages-ready'), 'ready\n');
           } finally { rmSync(sourceRoot, { recursive: true, force: true }); }
@@ -1061,13 +1123,19 @@ export function networkEffects(effects) {
           if ((await effects.serverLifecycle(record, 'status', selected)).length) throw new Error('Writers did not stop');
           return;
         }
-        if (selected.includes('daemon')) await compose(record, ['up', '-d', '--no-build', '--no-deps', '--wait', 'daemon']);
+        const start = async service => {
+          effects.out(`Starting ${service}; waiting for readiness...`);
+          try { await compose(record, ['up', '-d', '--no-build', '--no-deps', '--wait', service]); }
+          catch (cause) { throw await dockerStartupError(record, service, cause); }
+          effects.out(`${service} is ready.`);
+        };
+        if (selected.includes('daemon')) await start('daemon');
         const failures = [];
         for (const service of selected.filter(s => s !== 'daemon')) {
-          try { await compose(record, ['up', '-d', '--no-build', '--no-deps', '--wait', service]); }
-          catch { failures.push(service); }
+          try { await start(service); }
+          catch (error) { failures.push({ service, error }); }
         }
-        if (failures.length) throw new Error(`Application readiness failed: ${failures.join(', ')}. Check owning prerequisites; no identities were created.`);
+        if (failures.length) throw new Error(`Application readiness failed: ${failures.map(f => f.service).join(', ')}. Check the selected application prerequisites.\n${failures.map(f => f.error.message).join('\n\n')}`);
         return;
       }
       return nativeLifecycle(record, operation, selected, { effects, localEnv, ownerCommand, bin });
@@ -1090,7 +1158,7 @@ export function networkEffects(effects) {
       // Full metadata and authenticated capability validation follows before publication.
       return validateHostProfile({ endpoint: url.origin, expectedInstanceId: selection.instanceId, credentialPath: resolve(credentialPath) });
     },
-    importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath }) {
+    importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath, refresh = false }) {
       const root = join(home, '.ours-client');
       const configPath = join(root, 'profile.json');
       const credentialPath = join(root, 'credential');
@@ -1101,13 +1169,13 @@ export function networkEffects(effects) {
       const credential = readFileSync(profile.credentialPath, 'utf8');
       if (!credential.trim()) throw new Error('Client credential is empty');
       // Read every supplied input before any publication. Existing setup settings win on retry.
-      const sources = current ? null : resolvedSources
+      const sources = current && !refresh ? null : resolvedSources
         ? Buffer.from(`${JSON.stringify(resolvedSources, null, 2)}\n`)
         : readFileSync(sourcesPath);
-      const fleetSettings = !current && fleetSettingsPath ? readFileSync(fleetSettingsPath) : null;
+      const fleetSettings = (!current || refresh) && fleetSettingsPath ? readFileSync(fleetSettingsPath) : null;
       if (fleetSettings) JSON.parse(fleetSettings.toString());
       ensurePrivateDirectory(root);
-      if (current) {
+      if (current && !refresh) {
         assertPrivateRegularFile(credentialPath, 'managed credential');
         if (readFileSync(credentialPath, 'utf8') !== credential) atomicWriteConfig(credentialPath, credential);
         return { configPath, profile: validateHostProfile(current), settings: current.installer };
@@ -1122,12 +1190,13 @@ export function networkEffects(effects) {
       atomicWriteConfig(configPath, JSON.stringify(saved, null, 2) + '\n');
       return { configPath, profile: validateHostProfile(saved), settings };
     },
-    async acquireClientPackages(configPath, sourcesPath, integrations) {
+    async acquireClientPackages(configPath, sourcesPath, integrations, { refresh = false } = {}) {
       const manifest = JSON.parse(readFileSync(sourcesPath, 'utf8'));
       // Public SDK client APIs are actual integration dependencies; Fleet also owns CLI usage.
       const selected = [...new Set(['sdk', ...(integrations.includes('fleet') ? ['cli'] : []), ...integrations])];
       const packages = selectSourcePackages(manifest, 'client', selected);
-      const root = join(home, '.ours-client-install', createHash('sha256').update(configPath).digest('hex').slice(0, 16));
+      const selectionKey = refresh ? JSON.stringify([configPath, manifest, integrations]) : configPath;
+      const root = join(home, '.ours-client-install', createHash('sha256').update(selectionKey).digest('hex').slice(0, 16));
       const hasGit = Object.values(packages).some(selection => selection.source);
       await effects.run('npm', ['--version']);
       if (hasGit) {
@@ -1147,12 +1216,12 @@ export function networkEffects(effects) {
           const sourceRoot = join(root, `build-${randomUUID()}`);
           ensurePrivateDirectory(sourceRoot);
           try {
-            await effects.run(process.execPath, [join(INSTALLER_ASSETS, 'scripts/build/build.mjs')], { cwd: root, env: { OURS_BUILD_ROOT: root, OURS_SOURCE_ROOT: sourceRoot, OURS_BUILD_PACKAGES: selected.join(',') } });
+            await effects.run(process.execPath, [join(INSTALLER_ASSETS, 'scripts/build/build.mjs')], { stream: true, cwd: root, env: { OURS_BUILD_ROOT: root, OURS_SOURCE_ROOT: sourceRoot, OURS_BUILD_PACKAGES: selected.join(',') } });
           } finally { rmSync(sourceRoot, { recursive: true, force: true }); }
         } else {
           writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'ours-native-clients', private: true, dependencies: Object.fromEntries(Object.entries(packages).map(([name, selection]) => [name, selection.version])) }), { mode: 0o600 });
         }
-        await effects.run('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], { cwd: root });
+        await effects.run('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], { stream: true, cwd: root });
         verifyReleaseGraph(root, manifest, { requiredPackages: Object.keys(packages) });
         writePrivateNew(join(root, '.packages-ready'), 'ready\n');
       }
@@ -1365,5 +1434,5 @@ async function nativeLifecycle(record, operation, selected, { effects, localEnv,
       failures.push(service);
     }
   }
-  if (failures.length) throw new Error(`Application readiness failed: ${failures.join(', ')}. Check owning prerequisites; no identities were created.`);
+  if (failures.length) throw new Error(`Application readiness failed: ${failures.join(', ')}. Check the selected application prerequisites.`);
 }

package/lib/fleet-settings.mjs

@@ -0,0 +1,43 @@
+// Structural preflight adapted from @ours.network/fleet src/init-wizard.ts
+// (readInitSettings/generateSetup), shipped in Fleet 1.2.0-nightly.1.
+// This checks complete answers before installer effects, without duplicating
+// Fleet's evolving model catalog. Fleet init remains authoritative for model
+// membership, exact capability arrays, and its packaged preset validation.
+const WORKS = ['development', 'review', 'coordination'];
+const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const REASONING = { quick: 'low', balanced: 'medium', thorough: 'high' };
+const fail = message => { throw new Error(`Fleet settings ${message}`); };
+function exactKeys(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0') !== [...keys].sort().join('\0'))
+    fail(`${label} must contain exactly ${keys.join(', ')}`);
+}
+function uniqueSelection(value, choices, label) {
+  if (!Array.isArray(value) || value.length === 0 || new Set(value).size !== value.length
+    || value.some(item => !choices.includes(item)))
+    fail(`${label} must be a nonempty unique selection of ${choices.join(', ')}`);
+}
+
+export function validateFleetSettings(value) {
+  exactKeys(value, ['subscriptions', 'assignmentStrategy', 'models', 'reasoning'], 'answers');
+  uniqueSelection(value.subscriptions, ['codex', 'claude'], 'subscriptions');
+  if (!['one-model', 'per-job'].includes(value.assignmentStrategy)) fail('assignmentStrategy must be one-model or per-job');
+  if (typeof value.reasoning !== 'string' || !Object.hasOwn(REASONING, value.reasoning)) fail('reasoning must be quick, balanced, or thorough');
+  exactKeys(value.models, WORKS, 'models');
+  const tuples = new Set();
+  for (const work of WORKS) {
+    const model = value.models[work];
+    exactKeys(model, ['harness', 'session', 'model', 'efforts'], `${work} model`);
+    if (!['codex', 'claude-code'].includes(model.harness)) fail(`${work} harness must be codex or claude-code`);
+    if (model.session !== 'acp') fail(`${work} session must be acp`);
+    if (typeof model.model !== 'string' || !model.model.trim()) fail(`${work} model must be a nonempty string`);
+    uniqueSelection(model.efforts, EFFORTS, `${work} efforts`);
+    if (!model.efforts.includes(REASONING[value.reasoning])) fail(`${work} efforts do not support the selected reasoning`);
+    if (!value.subscriptions.includes(model.harness === 'codex' ? 'codex' : 'claude'))
+      fail(`${work} uses a harness outside the selected subscriptions`);
+    tuples.add(JSON.stringify([model.harness, model.session, model.model]));
+  }
+  if (value.assignmentStrategy === 'one-model' && tuples.size !== 1)
+    fail('one-model assignment requires the same model for development, review, and coordination');
+  return value;
+}

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