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

package/lib/server-onboarding.mjs

@@ -1,3 +1,4 @@
+import { gatewayAddress } from './gateway.mjs';
 /** Human bootstrap and local client handoff through the existing owner interfaces. */
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
@@ -28,16 +29,67 @@ function validateRecord(record) {
 }
 
 export function createServerOnboarding(effects, { compose, localEnv, bin }) {
-  async function identityCommand(record, args) {
-    const result = record.mode === 'docker'
-      ? await compose(record, ['exec', '-T', 'daemon', 'node', '/opt/ours/node_modules/@ours.network/cli/dist/cli.js', ...args, '--config', '/var/lib/ours/config.json', '--state-dir', '/var/lib/ours', '--json'])
-      : await effects.run(bin(record, 'ours'), [...args, '--config', record.configPath, '--state-dir', installationPaths(record).daemon, '--json'], { env: localEnv(record) });
+  // CLI client commands only accept gateway profiles in current releases. Use
+  // the installed SDK against the selected local daemon and its private file.
+  const identityScript = `
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { randomUUID } from 'node:crypto';
+const selection = JSON.parse(process.argv[1]);
+const require = createRequire(selection.anchor);
+const { attachOursClient } = await import(pathToFileURL(require.resolve('@ours.network/sdk/client')).href);
+const client = await attachOursClient({ endpoint: selection.endpoint,
+  expectedInstanceId: selection.instanceId, credentialPath: selection.credentialPath,
+  sessionMode: 'external', leaseToken: randomUUID(), env: {} });
+// The lease this short-lived client takes is released exactly once. An operation is not reported as done
+// while that release is incomplete, and what failed first is what is reported.
+let output, released = false;
+try {
+  const result = selection.operation === 'list' ? await client.listIdentities()
+    : selection.operation === 'create-role' ? { created: await client.createIdentity({ name: selection.name, bio: '',
+        exposeLocal: true, localAutoAccept: true }), current: await client.currentIdentity() }
+    : selection.operation === 'describe-role' ? (await client.chooseIdentity({ name: selection.name, force: false }),
+        { current: await client.currentIdentity() })
+    : await client.createRootIdentity({ name: selection.name, bio: '',
+        exposeLocal: true, localAutoAccept: true, skipIfRootExists: true });
+  released = true;
+  const release = await client.releaseLease();
+  output = release?.failed > 0 ? { onboardingError: 'LEASE_RELEASE_INCOMPLETE' } : result;
+} catch (error) {
+  output = { onboardingError: error.code || 'OWNER_OPERATION_FAILED' };
+  if (!released) try { await client.releaseLease(); } catch {}
+} finally {
+  try { await client.close(); } catch {}
+}
+process.stdout.write(JSON.stringify(output));
+`;
+  async function identityCommand(record, operation, name) {
+    validateRecord(record);
+    const docker = record.mode === 'docker';
+    const selection = {
+      operation, ...(name === undefined ? {} : { name }),
+      endpoint: `http://127.0.0.1:${docker ? 3050 : record.port}`,
+      instanceId: record.instanceId,
+      credentialPath: docker ? '/var/lib/ours/daemon-token' : join(installationPaths(record).daemon, 'daemon-token'),
+      anchor: docker ? '/opt/ours/package.json' : join(record.workDir, 'package.json'),
+    };
+    const args = ['--input-type=module', '-e', identityScript, JSON.stringify(selection)];
+    const result = docker
+      ? await compose(record, ['exec', '-T', 'daemon', 'node', ...args])
+      : await effects.run(process.execPath, args, { env: localEnv(record), sensitive: true });
     if (result.code !== undefined && result.code !== 0) throw new Error('Owner identity operation failed');
-    try { return JSON.parse(result.stdout); }
+    let value;
+    try { value = JSON.parse(result.stdout); }
     catch { throw new Error('Owner identity operation returned malformed JSON'); }
+    if (value?.onboardingError) {
+      const error = new Error('Owner identity operation failed');
+      error.code = value.onboardingError;
+      throw error;
+    }
+    return value;
   }
   async function identities(record) {
-    const rows = await identityCommand(record, ['identity', 'list']);
+    const rows = await identityCommand(record, 'list');
     if (!Array.isArray(rows) || rows.some(row => !row || typeof row.name !== 'string'
         || (!['root', 'role'].includes(row.kind) && !['reconciling', 'awaiting-root', 'migration-failed', 'refresh-failed'].includes(row.status))
         || (row.kind && (typeof row.cid !== 'string' || !row.cid)))) throw new Error('Owner identity list is malformed');
@@ -59,10 +111,11 @@ export function createServerOnboarding(effects, { compose, localEnv, bin }) {
       if (prior.rows.some(row => row.name === name)) throw new Error('Requested Human identity name already exists; no identity was changed');
       effects.out?.(`Creating Human identity ${name}; retaining ${prior.rows.length} existing identities.`);
       try {
-        await identityCommand(record, ['identity', 'create-root', '--name', name, '--skip-if-root-exists', 'true']);
+        await identityCommand(record, 'create-root', name);
       } catch (error) {
-        // ROOT_EXISTS is currently a CLI error. A concurrent creator is safe only
+        // A concurrent creator is safe only
         // when the authoritative list now contains a root; other errors stay errors.
+        if (error.code !== 'ROOT_EXISTS') throw error;
         const after = await identities(record);
         if (after.root) return retained(after);
         throw error;
@@ -73,16 +126,98 @@ export function createServerOnboarding(effects, { compose, localEnv, bin }) {
       effects.out?.(`Human identity ${after.root.name} is ready.`);
       return { name: after.root.name, cid: after.root.cid, created: true };
     },
+    /**
+     * The person's own identity under the Human root, which Messenger runs as. An identity of that name is
+     * used only when the daemon itself describes it as a permanent role of exactly the retained root;
+     * nothing else is renamed or adopted.
+     */
+    async serverEnsureMessengerIdentity(record, name) {
+      validateRecord(record);
+      validateIdentityName(name);
+      const listed = row => row?.kind === 'role' && row.temp === null && typeof row.cid === 'string';
+      const taken = () => new Error('Requested Messenger identity name is already used by another identity; no identity was changed');
+      const prior = await identities(record);
+      if (!prior.root) throw new Error('Messenger identity requires the Human identity; no identity was changed');
+      // The list has no parent column. What the daemon describes for the identity, bound for a moment, names its root.
+      const under = (current, row) => current?.name === name && current.temporary === false && current.isRoot === false
+        && current.described === true && typeof current.roleId === 'string' && current.roleId !== ''
+        && typeof current.cid === 'string' && current.cid === row.cid
+        && typeof current.rootCid === 'string' && current.rootCid.toLowerCase() === String(prior.root.cid).toLowerCase();
+      const adopt = async rows => {
+        const row = rows.rows.find(candidate => candidate.name === name);
+        if (rows.root?.cid !== prior.root.cid || !listed(row)) throw taken();
+        const { current } = await identityCommand(record, 'describe-role', name);
+        if (!under(current, row)) throw taken();
+        return row;
+      };
+      if (prior.rows.some(row => row.name === name)) {
+        const row = await adopt(prior);
+        effects.out?.(`Retained Messenger identity ${name}.`);
+        return { name, cid: row.cid, created: false };
+      }
+      effects.out?.(`Creating Messenger identity ${name} under ${prior.root.name}; retaining ${prior.rows.length} existing identities.`);
+      let result;
+      try {
+        result = await identityCommand(record, 'create-role', name);
+      } catch (error) {
+        // Only a name collision can mean a concurrent creator; any other failure is reported as it is.
+        if (error.code !== 'NAME_TAKEN') throw error;
+        // That creator is accepted only when the authoritative list now shows the name under the same root.
+        const after = await identities(record);
+        if (!after.rows.some(row => row.name === name)) throw error;
+        const row = await adopt(after);
+        return { name, cid: row.cid, created: false };
+      }
+      const after = await identities(record);
+      const row = after.rows.find(candidate => candidate.name === name);
+      if (result?.created?.hierarchy !== 'role' || result.created.underRoot !== prior.root.name || after.root?.cid !== prior.root.cid
+          || !listed(row) || result.created.info?.cid !== row.cid || !under(result.current, row))
+        throw new Error('Messenger identity creation completed without a usable identity under the Human identity');
+      effects.out?.(`Messenger identity ${name} is ready.`);
+      return { name, cid: row.cid, created: true };
+    },
+    async serverEnsureHumanProfile(record, human) {
+      validateRecord(record);
+      for (const key of ['name', 'surname']) if (typeof human[key] !== 'string' || !human[key].trim() || human[key].length > 100 || /[\x00-\x1f\x7f]/.test(human[key])) throw new Error('Invalid Messenger human profile');
+      // Messenger owns the profile lifecycle. Never rename the daemon root or
+      // overwrite a profile already present on a retained installation.
+      const script = `
+import { readFileSync } from 'node:fs';
+const selection = JSON.parse(process.argv[1]);
+const token = readFileSync(selection.credentialPath, 'utf8').trim();
+const base = selection.base;
+async function request(path, value) {
+ const response = await fetch(base + '/api/' + path, { method: value === undefined ? 'GET' : 'POST', redirect: 'error', signal: AbortSignal.timeout(15000), headers: { 'X-Ours-Api-Token': token, ...(value === undefined ? {} : { 'Content-Type': 'application/json', Origin: selection.origin, 'X-Ours-Messenger-CSRF': '1' }) }, ...(value === undefined ? {} : { body: JSON.stringify(value) }) });
+ if (!response.ok) { await response.body?.cancel(); throw new Error('Messenger human profile operation failed (HTTP ' + response.status + ')'); }
+ return response.json();
+}
+const identity = await request('identity');
+if (identity.humanProfile) process.stdout.write('Retained Messenger Name and Surname.');
+else { await request('identity/profile', selection.human); process.stdout.write('Messenger Name and Surname initialized.'); }
+`;
+      const docker = record.mode === 'docker';
+      const selection = { base: `http://127.0.0.1:${docker ? 8420 : record.messengerPort}`,
+        // Behind the gateway Messenger accepts mutations only from the gateway origin.
+        origin: record.gateway ? gatewayAddress(record).origin : `http://127.0.0.1:${record.messengerPort}`,
+        credentialPath: docker ? '/credentials/messenger/daemon-token' : installationPaths(record).credentials.messenger,
+        human: { name: human.name, surname: human.surname } };
+      const args = ['--input-type=module', '-e', script, JSON.stringify(selection)];
+      const result = docker ? await compose(record, ['exec', '-T', 'messenger', 'node', ...args])
+        : await effects.run(process.execPath, args, { env: localEnv(record), sensitive: true });
+      if (result.code !== undefined && result.code !== 0) throw new Error('Messenger human profile initialization failed');
+      effects.out?.(result.stdout);
+    },
     async prepareLocalClient(record, integrations, fleetSettingsPath) {
       validateRecord(record);
-      if (!Array.isArray(integrations) || !integrations.length || new Set(integrations).size !== integrations.length
+      if (!Array.isArray(integrations) || new Set(integrations).size !== integrations.length
           || integrations.some(name => !['codex', 'claude-code', 'fleet'].includes(name))) throw new Error('Client integrations must select codex, claude-code and/or fleet');
       if (fleetSettingsPath !== undefined) {
         if (typeof fleetSettingsPath !== 'string' || !isAbsolute(fleetSettingsPath) || resolve(fleetSettingsPath) !== fleetSettingsPath) throw new Error('Fleet settings path must be absolute');
         const settings = JSON.parse(readFileSync(fleetSettingsPath, 'utf8'));
         if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Fleet settings must be a JSON object');
       }
-      const endpoint = `http://127.0.0.1:${record.port}`;
+      const serverUrl = record.gateway ? gatewayAddress(record).base : undefined;
+      const endpoint = serverUrl ? `${serverUrl}/daemon` : `http://127.0.0.1:${record.port}`;
       const current = effects.readManagedClientProfile();
       if (current && (current.endpoint !== endpoint || current.expectedInstanceId !== record.instanceId)) throw new Error('Managed client already selects another server; no credential was issued');
       privatePath(record.root, true);
@@ -93,13 +228,16 @@ export function createServerOnboarding(effects, { compose, localEnv, bin }) {
       const published = join(root, 'issued-' + randomUUID());
       const credential = join(stage, 'credential');
       try {
-        effects.out?.('Issuing a separate local client credential with the retained server authority.');
-        try { await effects.serverAccess(record, 'access-issue', { output: credential }); }
-        catch { throw new Error('Client credential issuance failed; existing profiles were retained'); }
-        const stat = privatePath(credential);
-        if (stat.size > 4096 || !readFileSync(credential, 'utf8').trim()) throw new Error('Issued client credential is empty or invalid');
+        if (!current) {
+          effects.out?.('Issuing a separate local client credential with the retained server authority.');
+          try { await effects.serverAccess(record, 'access-issue', { output: credential }); }
+          catch (cause) { throw new Error('Client credential issuance failed; existing profiles were retained', { cause }); }
+        }
+        const retainedCredential = current?.credentialPath ?? credential;
+        const stat = privatePath(retainedCredential);
+        if (stat.size > 4096 || !readFileSync(retainedCredential, 'utf8').trim()) throw new Error('Issued client credential is empty or invalid');
         const profile = {
-          ...validateHostProfile({ endpoint, expectedInstanceId: record.instanceId, credentialPath: join(published, 'credential') }),
+          ...validateHostProfile({ ...(serverUrl ? { serverUrl } : {}), endpoint, expectedInstanceId: record.instanceId, credentialPath: current?.credentialPath ?? join(published, 'credential') }),
           installer: { integrations: [...integrations], ...(fleetSettingsPath !== undefined ? { fleetSettingsPath } : {}) },
         };
         writeFileSync(join(stage, 'profile.json'), JSON.stringify(profile, null, 2) + '\n', { flag: 'wx', mode: 0o600 });

package/lib/server-ports.mjs

@@ -0,0 +1,17 @@
+/** Fresh selections only; retained installations keep their recorded addresses. */
+export function selectServerPorts(record, isTaken, explicitPorts = [], out = () => {}) {
+  const reserved = new Set([3051]);
+  for (const key of ['port', 'coworkPort', 'messengerPort']) {
+    const preferred = record[key];
+    let selected = preferred;
+    while (reserved.has(selected) || isTaken(selected)) {
+      if (explicitPorts.includes(key)) throw Error(`Requested ${key} ${preferred} is unavailable; select another explicit port`);
+      selected++;
+      if (selected > 65535) throw Error(`No free loopback port available for ${key}`);
+    }
+    reserved.add(selected);
+    record[key] = selected;
+    if (selected !== preferred) out(`${key}: ${preferred} is unavailable; selected loopback port ${selected}`);
+  }
+  return record;
+}

package/lib/setup-options.mjs

@@ -1,13 +1,16 @@
+import { hostname } from 'node:os';
+import { serverBase } from './gateway.mjs';
 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',
+  '--container-engine': 'containerEngine', '--server-url': 'serverUrl', '--scope': 'scope', '--action': 'operation', '--mode': 'mode', '--state-dir': 'stateDir',
+  '--username': 'localUsername', '--name': 'name', '--surname': 'surname', '--hostname': 'hostname',
   '--identity-name': 'identityName', '--integrations': 'integrations', '--fleet-settings': 'fleetSettingsPath',
   '--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 boolFlags = new Map([['--compatible', 'compatible'], ['--dry-run', 'dryRun'], ['--migrate', 'migrate'], ['--disable-fleet-agents-setup', 'disableFleetAgentsSetup']]);
 const allowed = new Set([...valueFlags.values(), ...boolFlags.values(), 'interactive', 'explicitPorts']);
 const defaults = { port: 3050, coworkPort: 3052, messengerPort: 8420 };
 const paths = ['stateDir', 'config', 'sources', 'fleetSettingsPath', 'migrateFrom'];
@@ -15,7 +18,7 @@ const nonempty = value => typeof value === 'string' && value.trim().length > 0 &
 
 export function recommendedMode({ platform, arch, release = '' } = {}) {
   if (platform === 'linux' && /microsoft|wsl/i.test(release)) return { mode: 'docker', reason: 'Docker is recommended on Windows and WSL.' };
-  if (platform === 'linux' && arch === 'x64') return { mode: 'packages', reason: 'Native packages are recommended on Linux x64 with a systemd user manager.' };
+  if (platform === 'linux' && arch === 'x64') return { mode: 'docker', reason: 'Docker provides the integrated gateway for full-stack setup; native mode is server-only.' };
   if (platform === 'darwin') return { mode: 'docker', reason: 'Docker is recommended on macOS.' };
   if (platform === 'win32') return { mode: 'docker', reason: 'Docker is recommended on Windows; run the installer inside WSL with Docker Desktop.' };
   return { mode: 'docker', reason: 'Docker is recommended for this platform.' };
@@ -31,17 +34,42 @@ export function validateSetupOptions(input, { interactive = input?.interactive =
   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 suppliedHuman = ['localUsername', 'name', 'surname'].some(key => options[key] !== undefined);
+  if (suppliedHuman) {
+    for (const key of ['localUsername', 'name', 'surname']) if (!nonempty(options[key])) throw new Error(`Missing human profile option: ${key}`);
+    if (!/^[a-z0-9][a-z0-9-]{0,29}$/.test(options.localUsername)) throw new Error('Local username must contain 1–30 lowercase letters, digits or hyphens');
+    for (const key of ['name', 'surname']) {
+      if (options[key].trim().length > 100) throw new Error(`${key} must contain at most 100 characters`);
+      options[key] = options[key].trim();
+    }
+    // Name and Surname together name the person's own identity, which Messenger runs as.
+    const person = `${options.name} ${options.surname}`;
+    if ([...person].length > 64 || person !== person.normalize('NFC') || /[\\/\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u.test(person))
+      throw new Error('Name and Surname together must contain at most 64 NFC characters, including the space between them, without slashes or control characters');
+    options.hostname = options.hostname?.trim() || defaultHostname();
+    if (!/^[a-z0-9][a-z0-9-]{0,29}$/.test(options.hostname)) throw new Error('Hostname must contain 1–30 lowercase letters, digits or hyphens');
+    const identity = `${options.localUsername}@${options.hostname}`;
+    if (options.migrateFrom === undefined && options.identityName !== undefined && options.identityName !== identity) throw new Error('--identity-name conflicts with username and hostname');
+    if (options.migrateFrom === undefined) options.identityName = identity;
+  } else if (options.hostname !== undefined) throw new Error('--hostname requires username, name and surname');
+  if (options.disableFleetAgentsSetup !== undefined && typeof options.disableFleetAgentsSetup !== 'boolean') throw new Error('disableFleetAgentsSetup must be a boolean');
+  if (options.disableFleetAgentsSetup && options.fleetSettingsPath) throw new Error('--disable-fleet-agents-setup conflicts with --fleet-settings');
   const missing = [];
   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.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 (Array.isArray(options.integrations) && options.integrations.includes('fleet') && !interactive && !options.disableFleetAgentsSetup && !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';
   if (server && !['packages', 'docker'].includes(options.mode)) throw new Error('Mode must be packages (or native) or docker');
+  if (options.containerEngine !== undefined && (!server || options.mode !== 'docker' || !['docker', 'podman'].includes(options.containerEngine))) throw new Error('--container-engine docker|podman requires server container mode');
+  if (options.serverUrl !== undefined) {
+    if (!server || options.mode !== 'docker' || options.operation !== 'install') throw new Error('--server-url requires Docker server installation');
+    options.serverUrl = serverBase(options.serverUrl);
+  }
   if (server && options.config !== undefined) throw new Error('--config is only valid for client scope');
-  if (!server) for (const key of ['mode', 'stateDir', 'identityName', ...Object.keys(defaults), 'compatible', 'migrate']) {
+  if (!server) for (const key of ['mode', 'stateDir', 'identityName', 'localUsername', 'name', 'surname', 'hostname', ...Object.keys(defaults), 'compatible', 'migrate']) {
     if (options[key] !== undefined) throw new Error(`${key} is only valid for server or all scope`);
   }
   if (!client && (options.integrations !== undefined || options.fleetSettingsPath !== undefined)) throw new Error('--integrations and --fleet-settings require all or client scope');
@@ -84,7 +112,7 @@ function expandPaths(options, home) {
   return output;
 }
 
-export function parseSetupArgs(argv, { home } = {}) {
+export function parseSetupArgs(argv, { home, validate = true } = {}) {
   if (!Array.isArray(argv) || !argv.every(arg => typeof arg === 'string')) throw new Error('Arguments must be strings');
   const options = { interactive: false, explicitPorts: [] };
   const seen = new Set();
@@ -115,30 +143,34 @@ export function parseSetupArgs(argv, { home } = {}) {
   if (positional.length && scopes.includes(positional[0])) put('scope', positional.shift());
   if (positional.length && ['install', 'update'].includes(positional[0])) put('operation', positional.shift());
   if (positional.length) throw new Error(`Unexpected setup argument: ${positional.join(' ')}`);
-  return validateSetupOptions(expandPaths(options, home), { interactive: false });
+  return validate ? validateSetupOptions(expandPaths(options, home), { interactive: false }) : expandPaths(options, home);
+}
+
+export function defaultHostname() {
+  return hostname().toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/^[^a-z0-9]+/, '').slice(0, 30) || 'workspace';
 }
 
-export async function collectSetupOptions(effects) {
+export async function collectSetupOptions(effects, presets = {}) {
   if (effects.interactive !== true) throw new Error('Interactive setup requires a TTY; provide the complete CLI options instead');
-  const options = { interactive: true, explicitPorts: [] };
+  const options = { ...presets, interactive: true, explicitPorts: presets.explicitPorts ?? [] };
   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');
+  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') {
     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?', [
+    const location = options.stateDir ? 'preset' : 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 ??= 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 migrationJournal = existing?.legacyMigrationSource ? effects.readJson(join(options.stateDir, 'legacy-migration.json')) : null;
@@ -150,7 +182,7 @@ export async function collectSetupOptions(effects) {
     ? '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?', [
+  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');
@@ -160,7 +192,8 @@ export async function collectSetupOptions(effects) {
     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;
+    if (options.migrateFrom) { /* Explicit selection is validated below. */ }
+    else 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;
@@ -184,41 +217,69 @@ export async function collectSetupOptions(effects) {
       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);
+      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)');
     }
   }
   if (options.scope !== 'client') {
     const recommendation = recommendedMode({ ...effects.platform, arch: effects.platform?.arch ?? process.arch });
-    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);
+    // Native runs the server only: local clients need the container gateway. A retained
+    // native installation keeps its mode, so a full setup of it cannot finish.
+    // (An unfinished migration is resumed in its recorded mode and is validated with the plan.)
+    if (options.scope === 'all' && existing?.mode === 'packages' && !options.migrateFrom)
+      throw new Error('This installation runs natively, which supports the server only. Choose the server-only setup to maintain it (ours-install server); local clients need an installation that runs in Docker or Podman. Nothing was changed.');
+    const nativeOffered = options.scope === 'server' || existing?.mode === 'packages';
+    effects.out(nativeOffered
+      ? `${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.`
+      : 'The server runs in containers. Docker and Podman both work; the one you choose must be installed and running. An existing installation must keep its current mode.');
+    const runtime = options.mode ?? await effects.select('How should the server run?', [
+      ...(nativeOffered ? [{ value: 'packages', label: 'Native packages' }] : []), { value: 'docker', label: 'Docker' }, { value: 'podman', label: 'Podman' },
+    ], existing?.mode === 'docker' && existing?.containerEngine === 'podman' ? 'podman' : existing?.mode ?? recommendation.mode);
+    options.mode = runtime === 'podman' ? 'docker' : runtime;
+    if (runtime === 'podman') options.containerEngine = 'podman';
     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');
+      if (existing?.messengerIdentity) {
+        effects.out(`Existing Human identity ${existing.messengerIdentity} and Messenger profile will be retained.`);
+        // Supplied profile inputs never rename a retained root.
+        if (!['localUsername', 'name', 'surname'].some(key => options[key] !== undefined)) options.identityName ??= existing.messengerIdentity;
+      } else if (options.identityName === undefined || options.localUsername !== undefined) {
+        effects.out('Choose a local username (no global uniqueness check). Name and Surname appear in Messenger; the optional host name identifies this workspace.');
+        options.localUsername ??= await effects.askLine('Local username: ', (effects.username?.() ?? 'me').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 30));
+        options.name ??= await effects.askLine('Name: ', '');
+        options.surname ??= await effects.askLine('Surname: ', '');
+        options.hostname ??= await effects.askLine('Host / machine name (optional): ', '');
+      }
+    }
+    if (['localUsername', 'name', 'surname'].some(key => options[key] !== undefined)) {
+      // Partial profile presets still collect missing fields on retained and
+      // migration paths; these inputs never replace their authoritative root.
+      effects.out('Name and Surname initialize a missing Messenger profile; an existing profile is retained.');
+      options.localUsername ??= await effects.askLine('Local username: ', (effects.username?.() ?? 'me').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 30));
+      options.name ??= await effects.askLine('Name: ', '');
+      options.surname ??= await effects.askLine('Surname: ', '');
+      options.hostname ??= await effects.askLine('Host / machine name (optional): ', '');
     }
-    for (const [key, fallback] of Object.entries(defaults)) options[key] = existing?.[key] ?? fallback;
+    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);
+      options.compatible ??= await effects.ask('Proceed with this update and keep a recovery backup?', false);
     }
   } 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?', [
+    const connection = options.config ? 'preset' : 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);
+    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() : [];
     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?', [
+    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')) {
+    if (options.integrations.includes('fleet') && !options.disableFleetAgentsSetup && !options.fleetSettingsPath) {
       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' },