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

package/lib/prompt.mjs

@@ -1,6 +1,6 @@
 // Interactive prompts drawn on the controlling terminal (/dev/tty), so they work under
 // `curl | bash` (where stdin/stdout are the pipe). Synchronous, dependency-free: line prompts via
-// fs.readSync, and a raw-mode checkbox multi-select. When there is no tty or OURS_ASSUME_YES is
+// fs.readSync, and raw-mode single/multiple choices. When there is no tty or OURS_ASSUME_YES is
 // set, every prompt returns its default without reading — the headless/CI path never blocks.
 import { readSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
@@ -30,77 +30,66 @@ function readByte(fd) {
   }
 }
 
-// askLine: print `prompt` and read a line. We read in RAW mode with signal generation OFF (stty
-// -icanon -echo -isig) so Ctrl+C arrives as the byte 0x03 that we turn into a clean InstallCancelled
-// — rather than a SIGINT that a blocked synchronous readSync would defer forever (the old
-// "^C^C^C… and keeps going" bug). We echo/backspace ourselves since -echo is off. If stty isn't
-// available (not a real tty), fall back to a plain cooked read. Throws InstallCancelled on Ctrl+C.
-export function askLine(write, fd, prompt, def = '') {
+// Decode incrementally: a terminal read may split a UTF-8 code point across bytes.
+// Fatal decoding rejects malformed input instead of storing a corrupted name or path.
+function textEntry(write, fd, prompt, def, secret, {
+  read = readByte, enterRaw = enterSelectionMode,
+} = {}) {
   if (fd == null || ASSUME_YES()) return def;
-  write(prompt);
-
-  const saved = spawnSync('stty', ['-g'], { stdio: [fd, 'pipe', 'ignore'], encoding: 'utf8' });
-  const rawOk = saved.status === 0
-    && spawnSync('stty', ['-icanon', '-echo', '-isig', 'min', '1', 'time', '0'], { stdio: [fd, 'ignore', 'ignore'] }).status === 0;
-  const restore = () => { if (rawOk) spawnSync('stty', (saved.stdout || '').trim() ? [(saved.stdout || '').trim()] : ['sane'], { stdio: [fd, 'ignore', 'ignore'] }); };
-
-  let s = '';
+  let restore;
+  try { restore = enterRaw(fd); } catch (error) {
+    // A secret must never fall back to an echoing cooked terminal.
+    if (secret && isCancel(error)) { write(`${prompt}\n`); return null; }
+    throw error;
+  }
+  let decoder = new TextDecoder('utf-8', { fatal: true });
+  let pending = false;
+  const characters = [];
   try {
+    write(prompt);
     for (;;) {
-      const b = readByte(fd);
-      if (b === null || b === 0x04) break;               // EOF / Ctrl+D → take the default
-      if (b === 0x03) { restore(); write('^C'); throw new InstallCancelled(); } // Ctrl+C
-      if (b === 0x0a || b === 0x0d) { if (rawOk) write('\n'); break; }          // Enter
-      if (b === 0x7f || b === 0x08) { if (s.length) { s = s.slice(0, -1); if (rawOk) write('\b \b'); } continue; } // backspace
-      if (b < 0x20) continue;                            // ignore other control bytes
-      s += String.fromCharCode(b);
-      if (rawOk) write(String.fromCharCode(b));           // manual echo
+      const byte = read(fd);
+      if (byte == null || byte === 0x03 || byte === 0x04) throw new InstallCancelled();
+      if (byte === 0x7f || byte === 0x08) {
+        if (pending) {
+          decoder = new TextDecoder('utf-8', { fatal: true });
+          pending = false;
+        } else if (characters.length) {
+          characters.pop();
+          if (!secret) write('\b \b');
+        }
+        continue;
+      }
+      if (byte === 0x0a || byte === 0x0d) {
+        try { decoder.decode(); } catch { throw new InstallCancelled(); }
+        write('\n');
+        const answer = characters.join('').trim();
+        return answer === '' ? def : answer;
+      }
+      if (byte < 0x20) {
+        if (pending) throw new InstallCancelled();
+        continue;
+      }
+      let decoded;
+      try { decoded = decoder.decode(Uint8Array.of(byte), { stream: true }); }
+      catch { throw new InstallCancelled(); }
+      pending = decoded.length === 0;
+      for (const character of decoded) {
+        characters.push(character);
+        if (!secret) write(character);
+      }
     }
   } finally {
     restore();
   }
-  const ans = s.trim();
-  return ans === '' ? def : ans;
 }
 
-// Secret variant of askLine: identical cancellation/backspace/default semantics, but typed
-// characters are never echoed (not even as placeholder stars). This keeps provider keys out of
-// terminal scrollback, curl|bash output, and captured CI logs.
-export function askSecret(write, fd, prompt, def = '') {
-  if (fd == null || ASSUME_YES()) return def;
-
-  const saved = spawnSync('stty', ['-g'], { stdio: [fd, 'pipe', 'ignore'], encoding: 'utf8' });
-  const rawOk = saved.status === 0
-    && spawnSync('stty', ['-icanon', '-echo', '-isig', 'min', '1', 'time', '0'], { stdio: [fd, 'ignore', 'ignore'] }).status === 0;
-  const restore = () => {
-    if (rawOk) spawnSync('stty', (saved.stdout || '').trim() ? [(saved.stdout || '').trim()] : ['sane'], { stdio: [fd, 'ignore', 'ignore'] });
-  };
-  if (!rawOk) {
-    // Fail closed: a cooked fallback would echo the secret. Returning null lets the caller
-    // explain that secure input is unavailable without ever reading a credential.
-    write(`${prompt}\n`);
-    return null;
-  }
-  // Disable echo BEFORE displaying the prompt. Otherwise an automated or very fast typist can
-  // submit bytes in the small prompt→stty window and have the terminal driver echo the secret.
-  write(prompt);
+export function askLine(write, fd, prompt, def = '', controls) {
+  return textEntry(write, fd, prompt, def, false, controls);
+}
 
-  let s = '';
-  try {
-    for (;;) {
-      const b = readByte(fd);
-      if (b === null || b === 0x04) break;
-      if (b === 0x03) { restore(); write('^C'); throw new InstallCancelled(); }
-      if (b === 0x0a || b === 0x0d) { write('\n'); break; }
-      if (b === 0x7f || b === 0x08) { if (s.length) s = s.slice(0, -1); continue; }
-      if (b < 0x20) continue;
-      s += String.fromCharCode(b);
-    }
-  } finally {
-    restore();
-  }
-  const ans = s.trim();
-  return ans === '' ? def : ans;
+export function askSecret(write, fd, prompt, def = '', controls) {
+  return textEntry(write, fd, prompt, def, true, controls);
 }
 
 // askYesNo: y/n with a default shown in caps. Returns boolean.
@@ -111,69 +100,74 @@ export function askYesNo(write, fd, prompt, def = false) {
   return /^y/i.test(ans);
 }
 
-// checkboxSelect: raw-mode multi-select drawn on the tty. ↑/↓ (or k/j) move, Space toggles, Enter
-// confirms, a/n = all/none, q cancels (selects nothing). Returns the selected names in order.
-// `specs` are { name, label } (optionally { checked }). No-tty → returns pre-checked defaults.
-export function checkboxSelect(write, fd, specs, { title } = {}) {
-  const names = specs.map((s) => s.name);
-  const labels = specs.map((s) => s.label);
-  const sel = specs.map((s) => (s.checked ? 1 : 0));
-  const n = specs.length;
-  const chosen = () => names.filter((_, i) => sel[i] === 1);
-
-  if (fd == null) return chosen();
-
-  // Enter raw mode via `stty` on the tty fd (NOT tty.ReadStream.setRawMode, which would flip the
-  // fd to non-blocking and break our fs.readSync). Save the current settings and restore them
-  // after. If stty is unavailable / this isn't a real tty, fall back to the pre-checked defaults.
+// Keep terminal controls injectable so key sequences and cleanup can be checked without a TTY.
+function enterSelectionMode(fd) {
   const saved = spawnSync('stty', ['-g'], { stdio: [fd, 'pipe', 'ignore'], encoding: 'utf8' });
-  if (saved.status !== 0) return chosen();
-  const savedMode = (saved.stdout || '').trim();
-  const setRaw = spawnSync('stty', ['-echo', '-icanon', 'min', '1', 'time', '0'], { stdio: [fd, 'ignore', 'ignore'] });
-  if (setRaw.status !== 0) return chosen();
-  const restore = () => spawnSync('stty', savedMode ? [savedMode] : ['sane'], { stdio: [fd, 'ignore', 'ignore'] });
-
-  let cur = 0;
-  let drawn = 0;
+  if (saved.status !== 0 || !saved.stdout?.trim()) throw new InstallCancelled();
+  const restore = () => spawnSync('stty', [saved.stdout.trim()], { stdio: [fd, 'ignore', 'ignore'] });
+  const raw = spawnSync('stty', ['-echo', '-icanon', '-isig', 'min', '1', 'time', '0'], { stdio: [fd, 'ignore', 'ignore'] });
+  if (raw.status !== 0) { restore(); throw new InstallCancelled(); }
+  return restore;
+}
 
+function choose(write, fd, question, choices, defaults, multiple, {
+  read = readByte, enterRaw = enterSelectionMode,
+} = {}) {
+  if (!choices.length) throw new Error('A choice prompt requires at least one choice');
+  const selected = choices.map(choice => defaults.includes(choice.value));
+  let current = Math.max(0, selected.indexOf(true));
+  const result = () => multiple
+    ? choices.filter((_, i) => selected[i]).map(choice => choice.value)
+    : choices[current].value;
+  if (fd == null || ASSUME_YES()) return result();
+  const restore = enterRaw(fd);
+  let drawn = false;
+  const next = () => {
+    const byte = read(fd);
+    if (byte == null || byte === 0x03 || byte === 0x04) throw new InstallCancelled();
+    return byte;
+  };
   const redraw = () => {
-    if (drawn) write(`\x1b[${n}A`); // rewind over the previous frame
-    drawn = 1;
-    for (let i = 0; i < n; i++) {
-      const box = sel[i] ? c.green('[x]') : '[ ]';
-      const point = i === cur ? c.cyan('> ') : '  ';
-      write(`\r\x1b[K  ${point}${box} ${labels[i]}\n`);
-    }
+    if (drawn) write(`\x1b[${choices.length}A`);
+    drawn = true;
+    choices.forEach((choice, i) => {
+      const marker = multiple ? (selected[i] ? c.green('[x]') : '[ ]') : (i === current ? c.green('(●)') : '( )');
+      write(`\r\x1b[K  ${i === current ? c.cyan('> ') : '  '}${marker} ${choice.label}\n`);
+    });
   };
-
-  write(`  ${title || 'Choose — ' + c.bold('↑/↓') + ' move, ' + c.bold('Space') + ' toggle, ' + c.bold('Enter') + ' confirm (a=all, n=none)'}:\n`);
-  redraw();
-
-  loop: for (;;) {
-    const b = readByte(fd);
-    if (b === null) break;
-    switch (b) {
-      case 0x1b: { // ESC — arrow key sequence \x1b [ A/B
-        const b1 = readByte(fd);
-        if (b1 === 0x5b || b1 === 0x4f) { // '[' or 'O'
-          const b2 = readByte(fd);
-          if (b2 === 0x41) cur = (cur - 1 + n) % n; // up
-          else if (b2 === 0x42) cur = (cur + 1) % n; // down
+  try {
+    write(`\x1b[?25l  ${question}\n  ${c.bold('↑/↓')} move${multiple ? ', ' + c.bold('Space') + ' toggle' : ''}, ${c.bold('Enter')} confirm\n`);
+    redraw();
+    for (;;) {
+      const byte = next();
+      if (byte === 0x0d || byte === 0x0a) return result();
+      if (byte === 0x1b) {
+        const prefix = next();
+        if (prefix === 0x5b || prefix === 0x4f) {
+          const direction = next();
+          if (direction === 0x41) current = (current - 1 + choices.length) % choices.length;
+          if (direction === 0x42) current = (current + 1) % choices.length;
         }
-        break;
-      }
-      case 0x6b: case 0x4b: cur = (cur - 1 + n) % n; break; // k/K
-      case 0x6a: case 0x4a: cur = (cur + 1) % n; break;     // j/J
-      case 0x20: sel[cur] = 1 - sel[cur]; break;            // space
-      case 0x61: case 0x41: for (let i = 0; i < n; i++) sel[i] = 1; break; // a/A
-      case 0x6e: case 0x4e: for (let i = 0; i < n; i++) sel[i] = 0; break; // n/N
-      case 0x71: case 0x51: for (let i = 0; i < n; i++) sel[i] = 0; break loop; // q/Q cancel
-      case 0x0d: case 0x0a: break loop; // enter
-      default: break;
+      } else if (multiple && byte === 0x20) selected[current] = !selected[current];
+      redraw();
     }
-    redraw();
+  } finally {
+    try { restore(); } finally { write('\x1b[?25h'); }
   }
+}
 
-  restore();
-  return chosen();
+export function select(write, fd, question, choices, defaultValue, controls) {
+  return choose(write, fd, question, choices, [defaultValue], false, controls);
+}
+
+export function multiselect(write, fd, question, choices, defaults = [], controls) {
+  return choose(write, fd, question, choices, defaults, true, controls);
+}
+
+// Preserve the existing component selection API using the same keyboard implementation.
+export function checkboxSelect(write, fd, specs, { title } = {}) {
+  if (!specs.length) return [];
+  return multiselect(write, fd, title || 'Choose components',
+    specs.map(({ name, label }) => ({ value: name, label })),
+    specs.filter(spec => spec.checked).map(spec => spec.name));
 }

package/lib/server-onboarding.mjs

@@ -50,6 +50,7 @@ export function createServerOnboarding(effects, { compose, localEnv, bin }) {
     return { name: root.name, cid: root.cid, created: false };
   }
   return {
+    async serverListIdentities(record) { return (await identities(record)).rows; },
     async serverEnsureIdentity(record, name) {
       validateRecord(record);
       validateIdentityName(name);

package/lib/setup-options.mjs

@@ -1,16 +1,16 @@
-import { join, resolve } from 'node:path';
+import { join, resolve, isAbsolute, dirname } from 'node:path';
 
 const scopes = ['all', 'server', 'client'];
 const integrations = ['codex', 'claude-code', 'fleet'];
 const valueFlags = new Map(Object.entries({
   '--scope': 'scope', '--action': 'operation', '--mode': 'mode', '--state-dir': 'stateDir',
   '--identity-name': 'identityName', '--integrations': 'integrations', '--fleet-settings': 'fleetSettingsPath',
-  '--config': 'config', '--sources': 'sources', '--port': 'port', '--cowork-port': 'coworkPort', '--messenger-port': 'messengerPort',
+  '--config': 'config', '--sources': 'sources', '--migrate-from': 'migrateFrom', '--port': 'port', '--cowork-port': 'coworkPort', '--messenger-port': 'messengerPort',
 }));
 const boolFlags = new Map([['--compatible', 'compatible'], ['--dry-run', 'dryRun'], ['--migrate', 'migrate']]);
 const allowed = new Set([...valueFlags.values(), ...boolFlags.values(), 'interactive', 'explicitPorts']);
 const defaults = { port: 3050, coworkPort: 3052, messengerPort: 8420 };
-const paths = ['stateDir', 'config', 'sources', 'fleetSettingsPath'];
+const paths = ['stateDir', 'config', 'sources', 'fleetSettingsPath', 'migrateFrom'];
 const nonempty = value => typeof value === 'string' && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
 
 export function recommendedMode({ platform, arch, release = '' } = {}) {
@@ -29,11 +29,13 @@ export function validateSetupOptions(input, { interactive = input?.interactive =
   if (!['install', 'update'].includes(options.operation)) throw new Error('Operation must be install or update');
   const server = options.scope !== 'client';
   const client = options.scope !== 'server';
+  if (options.migrateFrom !== undefined && (!server || options.operation !== 'install')) throw new Error('--migrate-from requires server or all scope and operation install');
+  if (options.migrateFrom !== undefined && (!nonempty(options.migrateFrom) || !isAbsolute(options.migrateFrom))) throw new Error('--migrate-from requires an absolute daemon config path');
   const missing = [];
-  if (server) for (const [key, flag] of [['mode', '--mode'], ['stateDir', '--state-dir'], ['identityName', '--identity-name']]) if (!nonempty(options[key])) missing.push(flag);
+  if (server) for (const [key, flag] of [['mode', '--mode'], ['stateDir', '--state-dir'], ...(options.migrateFrom === undefined ? [['identityName', '--identity-name']] : [])]) if (!nonempty(options[key])) missing.push(flag);
   if (client && options.integrations === undefined) missing.push('--integrations (use none to skip)');
   if (!server && !nonempty(options.config)) missing.push('--config');
-  if (server && options.operation === 'update' && options.compatible !== true) missing.push('--compatible');
+  if (server && (options.operation === 'update' || options.migrateFrom !== undefined) && options.compatible !== true) missing.push('--compatible');
   if (Array.isArray(options.integrations) && options.integrations.includes('fleet') && !interactive && !nonempty(options.fleetSettingsPath)) missing.push('--fleet-settings');
   if (missing.length) throw new Error(`Missing required setup options: ${missing.join(', ')}`);
   if (options.mode === 'native') options.mode = 'packages';
@@ -51,7 +53,10 @@ export function validateSetupOptions(input, { interactive = input?.interactive =
   for (const key of paths) if (options[key] !== undefined && !nonempty(options[key])) throw new Error(`Invalid path for ${key}`);
   for (const key of ['compatible', 'migrate']) if (options[key] !== undefined && typeof options[key] !== 'boolean') throw new Error(`${key} must be a boolean`);
   if (server) {
-    options.identityName = options.identityName.trim();
+    if (options.identityName !== undefined) {
+      if (!nonempty(options.identityName)) throw new Error('Invalid Human identity name');
+      options.identityName = options.identityName.trim();
+    }
     for (const [key, fallback] of Object.entries(defaults)) {
       options[key] ??= fallback;
       if (!Number.isInteger(options[key]) || options[key] < 1 || options[key] > 65535) throw new Error(`${key} must be an integer port between 1 and 65535`);
@@ -71,7 +76,10 @@ function expandPaths(options, home) {
     if (value === '~' || value.startsWith('~/')) {
       if (!nonempty(home)) throw new Error('Home directory is required to expand ~/ paths');
       output[key] = resolve(home, value === '~' ? '' : value.slice(2));
-    } else output[key] = resolve(value);
+    } else {
+      if (key === 'migrateFrom' && !isAbsolute(value)) throw new Error('--migrate-from requires an absolute daemon config path');
+      output[key] = resolve(value);
+    }
   }
   return output;
 }
@@ -113,45 +121,133 @@ export function parseSetupArgs(argv, { home } = {}) {
 export async function collectSetupOptions(effects) {
   if (effects.interactive !== true) throw new Error('Interactive setup requires a TTY; provide the complete CLI options instead');
   const options = { interactive: true, explicitPorts: [] };
-  options.scope = (await effects.askLine('Set up all, server, or client? ', 'all')).trim();
+  const scopeChoices = [
+    { value: 'all', label: 'Everything on this computer' },
+    { value: 'server', label: 'Server only' },
+    { value: 'client', label: 'Connect this computer to an existing server' },
+  ];
+  effects.out('Choose what this computer should do. Everything runs the server here and connects your selected apps; client-only uses a server you already have.');
+  options.scope = await effects.select('What would you like to set up?', scopeChoices, 'all');
   if (!scopes.includes(options.scope)) throw new Error('Scope must be all, server, or client');
   let existing;
+  let pendingMigration;
   if (options.scope !== 'client') {
-    options.stateDir = await effects.askLine('Private installation root: ', join(effects.home, '.ours-install'));
+    const recommendedRoot = join(effects.home, '.ours-install');
+    effects.out(`Stores the server programs and data, including identities and messages. The recommended folder is ${recommendedRoot}; choose another only if you want to manage its location yourself.`);
+    const location = await effects.select('Where should server programs and data be stored?', [
+      { value: 'recommended', label: `Use the recommended folder (${recommendedRoot})` },
+      { value: 'custom', label: 'Choose another folder' },
+    ], 'recommended');
+    options.stateDir = location === 'recommended' ? recommendedRoot : await effects.askLine('Folder for server programs and data: ', recommendedRoot);
     options.stateDir = expandPaths({ stateDir: options.stateDir }, effects.home).stateDir;
     existing = effects.readJson(join(options.stateDir, 'installation.json'));
-    const legacyRoot = join(effects.home, '.ours');
-    const legacy = !existing ? effects.readJson(join(legacyRoot, 'config.json')) : null;
-    if (legacy?.stateDir === legacyRoot) throw new Error(`An existing global daemon was found at ${legacyRoot}, without a managed installation record for the selected root. This form cannot migrate that installation yet. Keep its state; use explicit CLI presets with a different empty directory only if you intend a separate installation.`);
+    const migrationJournal = existing?.legacyMigrationSource ? effects.readJson(join(options.stateDir, 'legacy-migration.json')) : null;
+    pendingMigration = existing?.legacyMigrationSource && migrationJournal?.phase !== 'complete' ? existing.legacyMigrationSource : null;
+  }
+  effects.out(pendingMigration
+    ? 'An earlier migration is unfinished. Resume it in this same folder to retain the copied data and repair the installation.'
+    : existing
+    ? 'This folder already contains an installation. Update selects this installer’s release while retaining state; repair reinstalls the retained package selection.'
+    : options.scope === 'client' ? 'Install connects your selected apps. Update refreshes their packages while keeping the server connection.'
+      : 'Install creates a managed installation in the selected folder. Update requires an installation already recorded there.');
+  options.operation = !existing && options.scope !== 'client' ? 'install' : await effects.select('What should happen?', [
+    { value: 'install', label: pendingMigration ? 'Resume the unfinished migration' : existing ? 'Repair this installation' : 'Install and configure' },
+    { value: 'update', label: 'Update an existing installation' },
+  ], existing && !pendingMigration ? 'update' : 'install');
+  if (options.scope !== 'client' && options.operation === 'install') {
+    const defaultConfig = join(effects.home, '.ours', 'config.json');
+    const legacy = !existing ? effects.readJson(defaultConfig) : null;
+    const legacyState = nonempty(legacy?.stateDir) ? legacy.stateDir
+      : legacy && legacy.stateDir === undefined && nonempty(effects.readJson(join(effects.home, '.ours', 'root.json'))?.name)
+        ? join(effects.home, '.ours') : null;
+    if (pendingMigration) options.migrateFrom = pendingMigration;
+    else if (legacyState) {
+      effects.out(`Found an existing ours installation at ${legacyState}. Upgrade it to keep its identities, messages and settings. The old server will stop; its original state is kept as a recovery copy.`);
+      if (await effects.ask('Upgrade this existing ours installation and keep its data?', true)) options.migrateFrom = defaultConfig;
+      else {
+        effects.out('A separate installation creates a different server. It does not move or share the identities and messages in the existing installation.');
+        if (!await effects.ask('Create a separate fresh installation and keep the existing daemon unchanged?', false)) throw new Error('Setup cancelled; existing daemon was not changed');
+      }
+    } else {
+      effects.out('Start fresh if you have no existing ours data to bring over. If your old installation is stored elsewhere, select its configuration file to retain its data.');
+      const migration = await effects.select('Should existing ours data be brought over?', [
+        { value: 'fresh', label: 'Start a fresh installation' },
+        { value: 'migrate', label: 'Bring data from another existing installation' },
+      ], 'fresh');
+      if (migration === 'migrate') options.migrateFrom = expandPaths({ migrateFrom: await effects.askLine('Existing daemon configuration file: ', '') }, effects.home).migrateFrom;
+    }
+    if (options.migrateFrom) {
+      if (existing && pendingMigration !== options.migrateFrom) throw new Error('--migrate-from requires a new managed installation root; the selected root already has installation.json');
+      const sourceConfig = effects.readJson(options.migrateFrom);
+      const sourceState = sourceConfig?.stateDir ?? dirname(options.migrateFrom);
+      const root = effects.readJson(join(sourceState, 'root.json'));
+      if (!nonempty(root?.name)) throw new Error('Cannot read the existing Human identity name; choose the configuration file for a complete existing installation');
+      options.identityName = root.name;
+      effects.out(`Your existing Human identity, ${root.name}, will be retained; no replacement identity will be created. Migration keeps the original state, but compatibility with an older release cannot be guaranteed automatically.`);
+      options.compatible = await effects.ask('Proceed with this release and keep the original state as a recovery copy?', false);
+      if (!options.compatible) throw new Error('Migration requires explicit compatibility confirmation (--compatible)');
+    }
   }
-  options.operation = (await effects.askLine('Install or update? ', existing ? 'update' : 'install')).trim();
   if (options.scope !== 'client') {
     const recommendation = recommendedMode({ ...effects.platform, arch: effects.platform?.arch ?? process.arch });
-    effects.out(`Detected ${effects.platform?.platform ?? 'unknown'} / ${effects.platform?.arch ?? process.arch}. ${recommendation.reason}`);
-    const defaultMode = existing?.mode ?? recommendation.mode;
-    options.mode = await effects.askLine('Runtime mode (native or docker): ', defaultMode === 'packages' ? 'native' : defaultMode);
-    options.identityName = await effects.askLine('What name should others see? ', existing?.messengerIdentity ?? effects.username?.() ?? 'me');
-    for (const [key, fallback] of Object.entries(defaults)) {
-      const label = { port: 'Daemon', coworkPort: 'Cowork', messengerPort: 'Messenger' }[key];
-      const value = await effects.askLine(`${label} port: `, String(existing?.[key] ?? fallback));
-      if (!/^[1-9]\d*$/.test(value)) throw new Error(`${label} port must be an integer`);
-      options[key] = Number(value); options.explicitPorts.push(key);
+    effects.out(`${recommendation.reason} Native runs directly on this computer; Docker runs in containers and needs Docker installed and running. An existing installation must keep its current mode.`);
+    options.mode = await effects.select('How should the server run?', [
+      { value: 'packages', label: 'Native packages' }, { value: 'docker', label: 'Docker' },
+    ], existing?.mode ?? recommendation.mode);
+    if (!options.migrateFrom) {
+      effects.out(existing ? 'Existing identities and names are retained. This name is used only if a Human identity needs to be created.' : 'Choose the name other people and agents should see for your Human identity.');
+      options.identityName = await effects.askLine('What name should others see? ', existing?.messengerIdentity ?? effects.username?.() ?? 'me');
+    }
+    for (const [key, fallback] of Object.entries(defaults)) options[key] = existing?.[key] ?? fallback;
+    if (options.operation === 'update') {
+      effects.out('The update retains identities and messages and creates a recovery backup before changing stored state. Proceed only if you accept this release for your existing data; compatibility is not automatically guaranteed.');
+      options.compatible = await effects.ask('Proceed with this update and keep a recovery backup?', false);
     }
-    if (options.operation === 'update') options.compatible = await effects.ask('Confirm that the selected update is compatible with retained state?', false);
-  } else options.config = await effects.askLine('Prepared client profile path: ', join(effects.home, '.ours-client', 'profile.json'));
+  } else {
+    const savedProfile = join(effects.home, '.ours-client', 'profile.json');
+    effects.out('A connection profile identifies the server and its private access credential. Reuse your saved connection or select a profile supplied by the server owner.');
+    const connection = await effects.select('Which server connection should this computer use?', [
+      { value: 'saved', label: 'Use the saved server connection' }, { value: 'file', label: 'Choose a connection profile file' },
+    ], effects.readJson(savedProfile) ? 'saved' : 'file');
+    options.config = connection === 'saved' ? savedProfile : await effects.askLine('Connection profile file: ', savedProfile);
+  }
   if (options.scope !== 'server') {
     const detected = typeof effects.detectHarnesses === 'function' ? await effects.detectHarnesses() : [];
-    options.integrations = [];
-    for (const name of integrations) if (await effects.ask(`Install ${name}?`, name === 'fleet' || detected.some(item => item.name === name && item.status === 'ok'))) options.integrations.push(name);
+    const selected = integrations.filter(name => name === 'fleet' || detected.some(item => item.name === name && item.status === 'ok'));
+    effects.out('Choose the apps to connect. Detected agent apps are selected by default; Fleet configures persistent agents but leaves them stopped. Use Space to toggle choices, then Enter to continue. You can select none.');
+    options.integrations = await effects.multiselect('Which integrations should be configured?', [
+      { value: 'codex', label: 'Codex' }, { value: 'claude-code', label: 'Claude Code' }, { value: 'fleet', label: 'Fleet — persistent agents' },
+    ], selected);
     if (options.integrations.includes('fleet')) {
-      const path = await effects.askLine('Fleet settings file (leave empty for the interactive Fleet wizard): ', '');
-      if (path.trim()) options.fleetSettingsPath = path;
+      effects.out('Fleet needs model and agent settings. Its guided setup asks for these later; a prepared settings file applies your existing choices. Fleet roles will not start automatically.');
+      const fleetMode = await effects.select('How should Fleet be configured?', [
+        { value: 'wizard', label: 'Configure interactively with Fleet' }, { value: 'file', label: 'Use a prepared settings file' },
+      ], 'wizard');
+      if (fleetMode === 'file') options.fleetSettingsPath = await effects.askLine('Fleet settings file: ', '');
+    }
+  }
+  effects.out('Recommended settings use the standard service ports and this installer’s packaged release. Customize only if you need different ports or a development package selection.');
+  const advanced = await effects.select('Installation settings', [
+    { value: 'recommended', label: 'Use recommended settings' }, { value: 'custom', label: 'Customize' },
+  ], 'recommended');
+  if (advanced === 'custom') {
+    if (options.scope !== 'client') {
+      effects.out('Ports determine where local apps reach each service. Use three different available ports; an existing installation keeps its recorded ports.');
+      for (const key of Object.keys(defaults)) {
+        const label = { port: 'Daemon', coworkPort: 'Cowork', messengerPort: 'Messenger' }[key];
+        const value = await effects.askLine(`${label} port: `, String(options[key]));
+        if (!/^[1-9]\d*$/.test(value)) throw new Error(`${label} port must be an integer`);
+        options[key] = Number(value); options.explicitPorts.push(key);
+      }
     }
+    effects.out('A source override replaces the packaged release selection. Leave it empty for the supported packaged release; use a file only for a deliberate development override.');
+    const sources = await effects.askLine('Source policy override file (optional): ', '');
+    if (sources.trim()) options.sources = sources;
   }
-  const sources = await effects.askLine('Source policy override (leave empty for the packaged release): ', '');
-  if (sources.trim()) options.sources = sources;
   const validated = validateSetupOptions(expandPaths(options, effects.home), { interactive: true });
-  effects.out(`Setup: ${validated.operation} ${validated.scope}${validated.mode ? ` using ${validated.mode} in ${validated.stateDir}` : ` from ${validated.config}`}; integrations: ${validated.integrations?.join(', ') || 'none'}.`);
+  const scopeLabel = scopeChoices.find(choice => choice.value === validated.scope).label;
+  effects.out(`Setup: ${scopeLabel}; ${validated.operation}${validated.mode ? ` using ${validated.mode === 'packages' ? 'native packages' : 'Docker'} in ${validated.stateDir}` : ` from ${validated.config}`}; integrations: ${validated.integrations?.join(', ') || 'none'}${validated.migrateFrom ? `; migrate from: ${validated.migrateFrom}` : ''}.`);
+  effects.out('Continue to apply these choices. Cancelling now leaves programs, services and data unchanged.');
   if (!await effects.ask('Continue with this setup?', false)) throw new Error('Setup cancelled; nothing was changed');
   return validated;
 }

package/lib/setup.mjs

@@ -1,3 +1,4 @@
+import { inspectLegacyMigration } from './legacy-migration.mjs';
 import { join } from 'node:path';
 import { parseSetupArgs, collectSetupOptions, validateSetupOptions } from './setup-options.mjs';
 import { parseNetworkArgs, validateHostProfile, InstallUsageError } from './target.mjs';
@@ -36,10 +37,19 @@ export async function prepareSetupPlan(options, effects) {
       if (effects.env?.[name]?.trim()) throw new InstallUsageError(`${name} conflicts with the selected client profile. Clear this override before full-stack/client setup; nothing was changed.`);
     }
   }
-  if (options.scope !== 'client') validateIdentityName(options.identityName);
+  if (options.scope !== 'client' && !options.migrateFrom) validateIdentityName(options.identityName);
   if (options.fleetSettingsPath) validateFleetSettings(readObject(effects, options.fleetSettingsPath, 'Fleet settings'));
   const policy = options.sources ? readObject(effects, options.sources, 'Source policy') : effects.packagedSourcePolicy();
   plan.sourcePolicy = policy;
+  if (options.migrateFrom) {
+    for (const name of ['OURS_API_TOKEN', 'OURS_API_VISIBILITY', 'OURS_STATE_DIR', 'OURS_PORT', 'OURS_DAEMON_ID', 'OURS_DATABASE_PROVIDER', 'OURS_DATABASE_URL']) {
+      if (effects.env?.[name]?.trim()) throw new InstallUsageError(`${name} conflicts with legacy migration. Clear it before setup; nothing was changed.`);
+    }
+    plan.legacyPlan = await (effects.inspectLegacyMigration ?? inspectLegacyMigration)(options, effects);
+    plan.sourcePolicy = plan.legacyPlan.journal.sourcePolicy ?? policy;
+    plan.identityName = plan.legacyPlan.source?.rootName ?? plan.legacyPlan.journal.identities.find(row => row.kind === 'root')?.name;
+    validateIdentityName(plan.identityName);
+  }
   if (options.scope !== 'client') {
     const value = effects.readJson(join(options.stateDir, 'installation.json'));
     if (value) {
@@ -49,7 +59,7 @@ export async function prepareSetupPlan(options, effects) {
         if (options.explicitPorts?.includes(key) && options[key] !== plan.existing[key]) throw new InstallUsageError(`${key} conflicts with the retained installation`);
         plan[key] = plan.existing[key];
       }
-      if (options.operation === 'install') {
+      if (options.operation === 'install' && !options.migrateFrom) {
         const retained = readObject(effects, plan.existing.sourcesPath, 'Retained source policy');
         plan.sourcePolicy = options.scope === 'server' || !options.integrations?.length ? retained : completeReleasePolicy(retained, options.sources ? policy : null);
       }

package/lib/usage.mjs

@@ -31,8 +31,10 @@ export const USAGE = `ours-install — interactive setup or complete CLI presets
   --port N                  daemon port (default 3050 on a fresh installation)
   --cowork-port N           cowork port (default 3052)
   --messenger-port N        messenger port (default 8420)
-  --compatible              required attestation for server updates of retained state
-  --migrate                 explicit legacy access migration during install
+  --compatible              required for server updates and legacy state migration
+  --migrate-from CONFIG     migrate an existing daemon into a new managed root; install only
+                           requires an absolute config path and --compatible
+  --migrate                 explicit legacy credential migration; separate from --migrate-from
   --dry-run                 show the validated plan without changing anything
   --help, -h                show help
   --version, -V             print installer version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/install",
-  "version": "1.2.1-nightly.2",
+  "version": "1.2.1-nightly.3",
   "private": false,
   "description": "The all-in-one ours.network installer: one shared daemon, MCP, cowork, Telegram, Fleet initialization, harness plugins, Human identity, progress UI, and guided next steps.",
   "type": "module",