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

package/lib/orchestrate.mjs

@@ -1266,6 +1266,7 @@ async function executeServerCommand(args, effects) {
   } else {
     if (args.operation !== 'install' || !args.mode) throw new Error('First server install requires --mode');
     record = effects.newInstallation(args.stateDir, args.mode);
+    for (const key of ['port', 'coworkPort', 'messengerPort']) if (args[key] !== undefined) record[key] = args[key];
   }
   if (record.layoutConversion && !['install', 'start', 'stop', 'status'].includes(args.operation)) {
     throw new Error('Layout conversion is incomplete; resume with server install or server start before changing state or authority');
@@ -1273,14 +1274,32 @@ async function executeServerCommand(args, effects) {
   if (record.buildTransition && !['stop', 'status', record.buildTransition.operation].includes(args.operation)) {
     throw new Error(`Server build activation is incomplete; repeat server ${record.buildTransition.operation} before other mutations`);
   }
+  const showInstallProgress = args.operation === 'install' && !(existing && (record.schema === 1 || record.layoutConversion));
+  const installStageCount = (existing ? 7 : 9) + (args.identityName ? 2 : 0);
+  let completedInstallStages = 0;
+  const installStage = async (label, explanation, action) => {
+    if (!showInstallProgress) return action();
+    effects.out(progress(completedInstallStages, installStageCount, label, explanation));
+    try {
+      const result = await action();
+      completedInstallStages += 1;
+      effects.out(ok(`${label} complete`));
+      return result;
+    } catch (error) {
+      effects.out(warn(`Server installation stopped during ${label.toLowerCase()}.`));
+      throw error;
+    }
+  };
   if ((!existing || args.operation === 'update') && !record.buildTransition) {
-    const policy = args.sources ? effects.readJson(args.sources) : effects.packagedSourcePolicy();
-    args.resolvedSources = await effects.resolveSourcePolicy(policy, 'server');
+    args.resolvedSources = await installStage('Package selection', 'Resolve the selected server packages before installation.', async () => {
+      const policy = args.sourcePolicy ?? (args.sources ? effects.readJson(args.sources) : effects.packagedSourcePolicy());
+      return effects.resolveSourcePolicy(policy, 'server');
+    });
   }
   if (!existing && args.sources) record.sourcePolicyHash = effects.sourcePolicyHash(args.sources);
-  await effects.serverPreflight(record, args.operation, {
-    existing, sourcePath: args.sources ?? record.sourcesPath, sourceManifest: args.resolvedSources,
-  });
+  await installStage('Prerequisite checks', record.mode === 'docker' ? 'Check Docker Engine and Docker Compose.' : 'Check native tools and the user service manager.', () => effects.serverPreflight(record, args.operation, {
+    existing, sourcePath: args.sources ?? record.sourcesPath, sourceManifest: args.resolvedSources, identityName: args.identityName,
+  }));
   if (existing && (record.schema === 1 || record.layoutConversion)
     && ['install', 'start', 'restart', 'update', 'rebuild'].includes(args.operation)) {
     record = record.mode === 'docker'
@@ -1295,16 +1314,27 @@ async function executeServerCommand(args, effects) {
     await effects.stopPendingConversion(record);
   } else if (args.operation === 'install') {
     if (!existing) {
-      await effects.initializeSelection(record, args.resolvedSources);
-      effects.writeJson(recordPath, JSON.stringify(record, null, 2) + '\n');
+      await installStage('Installation setup', 'Save the selected packages and installation settings.', async () => {
+        await effects.initializeSelection(record, args.resolvedSources);
+        effects.writeJson(recordPath, JSON.stringify(record, null, 2) + '\n');
+      });
     }
-    await effects.prepareInstallation(record);
+    await installStage('Runtime preparation', record.mode === 'docker' ? 'Prepare the Docker runtime. Downloads and builds may take several minutes.' : 'Download and prepare the native runtime packages. This may take several minutes.', () => effects.prepareInstallation(record));
     // A repeated setup repairs delivery with the retained master and exact packages.
-    await effects.serverLifecycle(record, 'stop');
-    await effects.serverAccess(record, 'access-init', { migrate: !!args.migrate });
-    await effects.serverAccess(record, 'access-issue');
-    await effects.recordInstallationBuild(record);
-    await effects.serverLifecycle(record, 'start');
+    await installStage('Service shutdown', 'Stop managed services before configuring access.', () => effects.serverLifecycle(record, 'stop'));
+    await installStage('Credential initialization', 'Initialize or retain the installation credentials.', () => effects.serverAccess(record, 'access-init', { migrate: !!args.migrate }));
+    await installStage('Credential delivery', 'Prepare access for the selected services.', () => effects.serverAccess(record, 'access-issue'));
+    await installStage('Build verification', 'Record the installed runtime and selected package versions.', () => effects.recordInstallationBuild(record));
+    if (args.identityName) {
+      await installStage('Daemon startup', 'Start the daemon and restore its retained identities.', () => effects.serverLifecycle(record, 'start', ['daemon']));
+      const identity = await installStage('Human identity', 'Keep the existing Human identity, or create it on a fresh daemon.', () => effects.serverEnsureIdentity(record, args.identityName));
+      record.messengerIdentity = identity.name;
+      effects.writeJson(recordPath, JSON.stringify(record, null, 2) + '\n');
+      await installStage('Application startup', 'Start the selected applications and check readiness.', () => effects.serverLifecycle(record, 'start', record.services.filter(name => name !== 'daemon')));
+    } else {
+      await installStage('Service startup', 'Start the daemon and selected services, then check readiness.', () => effects.serverLifecycle(record, 'start'));
+    }
+    if (showInstallProgress) effects.out(progress(installStageCount, installStageCount, 'Installation complete', 'The selected services are ready.'));
   } else if (['backup', 'restore', 'reset'].includes(args.operation)) {
     await effects.serverMaintenance(record, args);
   } else if (['update', 'rebuild'].includes(args.operation)) {
@@ -1341,18 +1371,18 @@ async function executeServerCommand(args, effects) {
   return EXIT_OK;
 }
 
-async function runClientCommand(command, effects) {
+export async function runClientCommand(command, effects) {
   const managedPath = join(effects.home, '.ours-client', 'profile.json');
   const saved = effects.readManagedClientProfile();
   let configPath = command.config;
   if (!configPath && saved) {
-    if (effects.interactive && !await effects.ask(`Reuse saved client server ${saved.endpoint}?`, true))
+    if (!command.preset && effects.interactive && !await effects.ask(`Reuse saved client server ${saved.endpoint}?`, true))
       throw new InstallUsageError('Saved client default retained; use an explicit prepared profile to validate replacement input');
     configPath = managedPath;
   }
   let profile;
   if (configPath) profile = validateHostProfile(effects.readProfile(configPath));
-  else if (effects.interactive) {
+  else if (!command.preset && effects.interactive) {
     const endpoint = await effects.askLine('Server HTTP endpoint: ', 'http://127.0.0.1:3050');
     const credentialPath = await effects.askLine('Private issued-token file: ', '');
     if (!credentialPath) throw new InstallUsageError('Client setup requires an issued-token file');
@@ -1369,40 +1399,51 @@ async function runClientCommand(command, effects) {
   await effects.verifyPackagedMcp(configPath || profile);
   const settings = saved?.installer ?? (configPath ? effects.readJson(configPath)?.installer : undefined);
   const settingsBase = saved ? dirname(managedPath) : configPath ? dirname(configPath) : process.cwd();
-  let integrations = settings?.integrations;
-  if (!integrations && effects.interactive) {
+  let integrations = command.integrations ?? settings?.integrations;
+  if (!integrations && !command.preset && effects.interactive) {
     integrations = [];
     for (const name of ['codex', 'claude-code', 'fleet']) if (await effects.ask(`Install ${name}?`, name !== 'fleet')) integrations.push(name);
   }
   if (!Array.isArray(integrations) || !integrations.length || integrations.some(name => !['codex', 'claude-code', 'fleet'].includes(name)) || new Set(integrations).size !== integrations.length) throw new InstallUsageError('installer.integrations must select codex, claude-code and/or fleet');
-  let fleetSettingsPath = settings?.fleetSettingsPath;
+  let fleetSettingsPath = command.preset ? command.fleetSettingsPath : settings?.fleetSettingsPath;
+  if (command.nonInteractive && integrations.includes('fleet') && !fleetSettingsPath) throw new InstallUsageError('Fleet in CLI mode requires --fleet-settings; no interactive wizard will be opened');
   if (fleetSettingsPath !== undefined && (typeof fleetSettingsPath !== 'string' || !fleetSettingsPath))
     throw new InstallUsageError('installer.fleetSettingsPath must be a non-empty path when supplied');
   if (fleetSettingsPath) fleetSettingsPath = resolve(settingsBase, fleetSettingsPath);
   const selectedClients = [...new Set(['sdk', ...(integrations.includes('fleet') ? ['cli'] : []), ...integrations])];
   let sourcesPath = settings?.sourcesPath;
   let resolvedSources;
-  if (saved) sourcesPath = resolve(settingsBase, sourcesPath);
+  if (command.sourcePolicy) {
+    resolvedSources = await effects.resolveSourcePolicy(command.sourcePolicy, 'client', selectedClients);
+    sourcesPath = undefined;
+  } else if (saved) sourcesPath = resolve(settingsBase, sourcesPath);
   else {
     if (sourcesPath) sourcesPath = resolve(settingsBase, sourcesPath);
     const policy = sourcesPath ? effects.readJson(sourcesPath) : effects.packagedSourcePolicy();
     resolvedSources = await effects.resolveSourcePolicy(policy, 'client', selectedClients);
   }
-  const imported = effects.importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath });
+  effects.out(progress(0, 4, 'Client configuration', 'Prepare the selected integrations and private connection profile.'));
+  const imported = effects.importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath, refresh: !!command.preset });
   try {
     await effects.verifyHostProfile(imported.configPath);
-    const exactSuite = await effects.acquireClientPackages(imported.configPath, imported.settings.sourcesPath, integrations);
+    effects.out(progress(1, 4, 'Client packages', 'Acquire and verify the selected client package versions.'));
+    const exactSuite = await effects.acquireClientPackages(imported.configPath, imported.settings.sourcesPath, integrations, { refresh: !!command.preset });
     const args = { assumeYes: true, dryRun: false, channel: 'latest', clientIntegrations: integrations,
       acquiredFleet: exactSuite.fleetBin, fleetSettingsPath: imported.settings.fleetSettingsPath };
     const target = { mode: 'host-profile', managed: true, configPath: imported.configPath, profile: imported.profile, endpoint: imported.profile.endpoint };
+    effects.out(progress(2, 4, 'Client integrations', 'Register the selected agent integrations.'));
     const summary = await runHarnessPhase(args, effects, { target, isDefaultStateDir: false, exactSuite });
-    if (integrations.includes('fleet')) summary.push(await runFleetPhase(args, effects, { target, isDefaultStateDir: false }));
+    if (integrations.includes('fleet')) {
+      effects.out(progress(3, 4, 'Fleet configuration', 'Apply prepared settings or open the selected Fleet wizard.'));
+      summary.push(await runFleetPhase(args, effects, { target, isDefaultStateDir: false }));
+    }
     const incomplete = integrations.filter(name => !summary.some(row => row.key === name && row.state === 'installed'));
     if (effects.env.OURS_CONFIG && resolve(effects.env.OURS_CONFIG) !== imported.configPath)
       effects.out(warn('This shell has an explicit OURS_CONFIG override. Unset it for new clients to use the saved default; installer did not edit your shell.'));
     effects.out(incomplete.length
       ? warn(`Client setup incomplete (${incomplete.join(', ')}); saved profile and settings retained. Re-run ours-install client install.`)
       : ok(`Client setup complete. New clients discover ${imported.configPath}; no OURS_CONFIG export is required.`));
+    if (!incomplete.length) effects.out(progress(4, 4, 'Client setup complete', 'All selected integrations are configured.'));
     return incomplete.length ? EXIT_REFUSED : EXIT_OK;
   } catch (error) {
     effects.out(warn(`Client setup incomplete: ${reason(error)}. Saved profile and settings retained; re-run ours-install client install.`));

package/lib/server-onboarding.mjs

@@ -0,0 +1,113 @@
+/** 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';
+import { randomUUID } from 'node:crypto';
+import { installationPaths } from './plan.mjs';
+import { validateHostProfile } from './target.mjs';
+
+export function validateIdentityName(name) {
+  if (typeof name !== 'string' || [...name].length < 1 || [...name].length > 64 || name !== name.normalize('NFC')
+      || /[\\/\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u.test(name)
+      || ['.', '..', 'contact-book', 'root.json', 'bindings.json'].includes(name)) {
+    throw new Error('Invalid Human identity name; use 1–64 NFC characters without reserved names or path/control characters');
+  }
+}
+function privatePath(path, directory = false) {
+  const stat = lstatSync(path);
+  if (!(directory ? stat.isDirectory() : stat.isFile()) || realpathSync(path) !== path
+      || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || (!directory && stat.nlink !== 1)) {
+    throw new Error('Onboarding requires an owned private ' + (directory ? 'directory' : 'regular credential file'));
+  }
+  return stat;
+}
+function validateRecord(record) {
+  if (!record || !['packages', 'docker'].includes(record.mode) || typeof record.root !== 'string'
+      || !isAbsolute(record.root) || resolve(record.root) !== record.root
+      || !Number.isInteger(record.port) || record.port < 1 || record.port > 65535) throw new Error('Invalid local server selection');
+  validateHostProfile({ endpoint: `http://127.0.0.1:${record.port}`, expectedInstanceId: record.instanceId, credentialPath: join(record.root, 'client', 'credential') });
+}
+
+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) });
+    if (result.code !== undefined && result.code !== 0) throw new Error('Owner identity operation failed');
+    try { return JSON.parse(result.stdout); }
+    catch { throw new Error('Owner identity operation returned malformed JSON'); }
+  }
+  async function identities(record) {
+    const rows = await identityCommand(record, ['identity', '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');
+    const roots = rows.filter(row => row.kind === 'root');
+    if (roots.length > 1) throw new Error('Owner identity list contains multiple Human roots');
+    return { rows, root: roots[0] };
+  }
+  function retained({ rows, root }) {
+    effects.out?.(`Retained ${rows.length} existing ${rows.length === 1 ? 'identity' : 'identities'}; Human identity: ${root.name}.`);
+    return { name: root.name, cid: root.cid, created: false };
+  }
+  return {
+    async serverEnsureIdentity(record, name) {
+      validateRecord(record);
+      validateIdentityName(name);
+      const prior = await identities(record);
+      if (prior.root) return retained(prior);
+      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']);
+      } catch (error) {
+        // ROOT_EXISTS is currently a CLI error. A concurrent creator is safe only
+        // when the authoritative list now contains a root; other errors stay errors.
+        const after = await identities(record);
+        if (after.root) return retained(after);
+        throw error;
+      }
+      const after = await identities(record);
+      if (!after.root) throw new Error('Human identity creation completed without a visible root');
+      if (after.root.name !== name) return retained(after);
+      effects.out?.(`Human identity ${after.root.name} is ready.`);
+      return { name: after.root.name, cid: after.root.cid, created: true };
+    },
+    async prepareLocalClient(record, integrations, fleetSettingsPath) {
+      validateRecord(record);
+      if (!Array.isArray(integrations) || !integrations.length || 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 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);
+      const root = join(record.root, 'client');
+      if (!existsSync(root)) mkdirSync(root, { mode: 0o700 });
+      privatePath(root, true);
+      const stage = mkdtempSync(join(root, '.pending-'));
+      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');
+        const profile = {
+          ...validateHostProfile({ endpoint, expectedInstanceId: record.instanceId, 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 });
+        // Publish the complete pair in one rename. Managed-default activation and
+        // package/source selection remain the normal client installer's job.
+        renameSync(stage, published);
+        effects.out?.('Local client profile is ready for authenticated client setup.');
+        return { configPath: join(published, 'profile.json'), profile };
+      } finally { rmSync(stage, { recursive: true, force: true }); }
+    },
+  };
+}

package/lib/setup-options.mjs

@@ -0,0 +1,157 @@
+import { join, resolve } 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',
+}));
+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 nonempty = value => typeof value === 'string' && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+
+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 === '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.' };
+}
+
+export function validateSetupOptions(input, { interactive = input?.interactive === true } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Setup options must be an object');
+  for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`Unknown setup option: ${key}`);
+  const options = { ...input, scope: input.scope ?? 'all', operation: input.operation ?? 'install', interactive };
+  if (!scopes.includes(options.scope)) throw new Error('Scope must be all, server, or client');
+  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';
+  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 (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 (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';
+  if (server && !['packages', 'docker'].includes(options.mode)) throw new Error('Mode must be packages (or native) or docker');
+  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 (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');
+  if (options.integrations !== undefined) {
+    if (!Array.isArray(options.integrations) || options.integrations.some(name => !integrations.includes(name)) || new Set(options.integrations).size !== options.integrations.length) throw new Error('Integrations must be unique codex, claude-code, fleet, or none');
+    options.integrations = [...options.integrations];
+  }
+  if (options.fleetSettingsPath !== undefined && !options.integrations?.includes('fleet')) throw new Error('--fleet-settings requires the fleet integration');
+  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();
+    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`);
+    }
+    if (new Set(Object.keys(defaults).map(key => options[key])).size !== 3) throw new Error('Server ports must be distinct');
+  }
+  options.explicitPorts ??= [];
+  if (!Array.isArray(options.explicitPorts) || options.explicitPorts.some(key => !Object.hasOwn(defaults, key)) || new Set(options.explicitPorts).size !== options.explicitPorts.length || (!server && options.explicitPorts.length)) throw new Error('Invalid explicitPorts selection');
+  options.explicitPorts = [...options.explicitPorts];
+  return options;
+}
+
+function expandPaths(options, home) {
+  const output = { ...options };
+  for (const key of paths) if (nonempty(output[key])) {
+    const value = output[key];
+    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);
+  }
+  return output;
+}
+
+export function parseSetupArgs(argv, { home } = {}) {
+  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();
+  const positional = [];
+  const put = (key, value) => {
+    if (seen.has(key)) throw new Error(`Duplicate or conflicting setup option: ${key}`);
+    seen.add(key); options[key] = value;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('-')) { positional.push(arg); continue; }
+    const equal = arg.indexOf('=');
+    const flag = equal < 0 ? arg : arg.slice(0, equal);
+    if (boolFlags.has(flag)) {
+      if (equal >= 0) throw new Error(`${flag} takes no value`);
+      put(boolFlags.get(flag), true); continue;
+    }
+    if (!valueFlags.has(flag)) throw new Error(`Unknown setup flag: ${flag}`);
+    const value = equal < 0 ? argv[++i] : arg.slice(equal + 1);
+    if (!nonempty(value) || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+    const key = valueFlags.get(flag);
+    if (key === 'integrations') put(key, value === 'none' ? [] : value.split(',').map(item => item.trim()));
+    else if (Object.hasOwn(defaults, key)) {
+      if (!/^[1-9]\d*$/.test(value)) throw new Error(`${flag} requires an integer port`);
+      put(key, Number(value)); options.explicitPorts.push(key);
+    } else put(key, value);
+  }
+  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 });
+}
+
+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();
+  if (!scopes.includes(options.scope)) throw new Error('Scope must be all, server, or client');
+  let existing;
+  if (options.scope !== 'client') {
+    options.stateDir = await effects.askLine('Private installation root: ', join(effects.home, '.ours-install'));
+    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.`);
+  }
+  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);
+    }
+    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'));
+  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);
+    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;
+    }
+  }
+  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'}.`);
+  if (!await effects.ask('Continue with this setup?', false)) throw new Error('Setup cancelled; nothing was changed');
+  return validated;
+}

package/lib/setup.mjs

@@ -0,0 +1,145 @@
+import { join } from 'node:path';
+import { parseSetupArgs, collectSetupOptions, validateSetupOptions } from './setup-options.mjs';
+import { parseNetworkArgs, validateHostProfile, InstallUsageError } from './target.mjs';
+import { validateInstallation } from './plan.mjs';
+import { runServerCommand, runClientCommand } from './orchestrate.mjs';
+import { banner, heading, info, ok, warn, progress } from './ui.mjs';
+import { isCancel } from './prompt.mjs';
+import { USAGE } from './usage.mjs';
+import { validateIdentityName } from './server-onboarding.mjs';
+import { validateFleetSettings } from './fleet-settings.mjs';
+
+const maintenance = new Set(['status', 'start', 'stop', 'restart', 'rebuild', 'access-issue', 'access-replace', 'backup', 'restore', 'reset']);
+const clientPackages = integrations => [...new Set(['sdk', ...(integrations.includes('fleet') ? ['cli'] : []), ...integrations])];
+
+export function completeReleasePolicy(retained, supplied) {
+  if (retained?.release) {
+    return { release: retained.release, packages: Object.fromEntries(Object.entries(retained.release.packages).map(([name, entry]) => [name, { type: 'npm', version: entry.version }])) };
+  }
+  if (supplied) return supplied;
+  throw new InstallUsageError('This development installation needs its full --sources policy to configure clients; server-only selections cannot supply client packages');
+}
+
+function readObject(effects, path, label) {
+  const value = effects.readJson(path);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new InstallUsageError(`${label} must be a readable JSON object: ${path}`);
+  return value;
+}
+
+/** Read-only validation of the complete plan, before any locks, installs or service changes. */
+export async function prepareSetupPlan(options, effects) {
+  options = validateSetupOptions(options, { interactive: options.interactive });
+  if (effects.platform?.platform === 'win32') throw new InstallUsageError('Run ours-install inside WSL with Docker Desktop integration on Windows. Direct Windows Node installations are not supported.');
+  const plan = { ...options };
+  if (options.scope !== 'server' && options.integrations.length) {
+    for (const name of ['OURS_API_TOKEN', 'OURS_PORT', 'OURS_STATE_DIR', 'OURS_DAEMON_ID']) {
+      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.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.scope !== 'client') {
+    const value = effects.readJson(join(options.stateDir, 'installation.json'));
+    if (value) {
+      plan.existing = validateInstallation(value, options.stateDir);
+      if (options.mode !== plan.existing.mode) throw new InstallUsageError('The selected mode conflicts with the retained installation; choose its existing mode or a separate empty directory');
+      for (const key of ['port', 'coworkPort', 'messengerPort']) {
+        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') {
+        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);
+      }
+    } else if (options.operation === 'update') {
+      throw new InstallUsageError('Update requires an existing installation.json; choose install for a new installation');
+    }
+    // Reject a local client already attached to another server before changing the server.
+    const saved = options.scope === 'all' && options.integrations.length ? effects.readManagedClientProfile() : null;
+    if (saved && (!plan.existing || saved.expectedInstanceId !== plan.existing.instanceId || saved.endpoint !== `http://127.0.0.1:${plan.port}`)) {
+      throw new InstallUsageError('This user already has clients attached to a different server; their saved connection was not changed');
+    }
+  } else {
+    const profile = validateHostProfile(readObject(effects, options.config, 'Client profile'));
+    if (!profile) throw new InstallUsageError('Client profile must contain endpoint, expectedInstanceId and credentialPath');
+    if (!effects.readText(profile.credentialPath)?.trim()) throw new InstallUsageError('Client credential file is missing or empty');
+    plan.profile = profile;
+    const saved = effects.readManagedClientProfile();
+    if (saved && (saved.endpoint !== profile.endpoint || saved.expectedInstanceId !== profile.expectedInstanceId)) throw new InstallUsageError('Managed clients already select another server; existing connection was not changed');
+    if (saved && options.operation === 'install' && !options.sources) plan.sourcePolicy = readObject(effects, saved.installer.sourcesPath, 'Retained client source policy');
+  }
+  // Dry-run never spawns a resolver or acquires an installation lock.
+  if (!options.dryRun) {
+    if (options.scope === 'all' && options.operation === 'update' && options.integrations.length) {
+      const running = await effects.serverLifecycle(plan.existing, 'status', ['daemon']);
+      if (!running.includes('daemon')) throw new InstallUsageError('Full-stack update requires the selected daemon to be running for client verification. Start it first, or use server update to preserve its stopped state.');
+    }
+    if (options.scope !== 'client') await effects.resolveSourcePolicy(plan.sourcePolicy, 'server');
+    if (options.scope !== 'server' && options.integrations.length) await effects.resolveSourcePolicy(plan.sourcePolicy, 'client', clientPackages(options.integrations));
+  }
+  return plan;
+}
+
+export async function executeSetupPlan(plan, effects, { server = runServerCommand, client = runClientCommand } = {}) {
+  if (!plan.interactive) effects.out(banner());
+  effects.out(heading(`${plan.operation === 'update' ? 'Update' : 'Install'} ours.network`));
+  effects.out(info(`Scope: ${plan.scope}; ${plan.scope === 'client' ? `profile: ${plan.config}` : `mode: ${plan.mode === 'packages' ? 'native' : 'docker'}; directory: ${plan.stateDir}`}`));
+  if (plan.scope !== 'server') effects.out(info(`Client integrations: ${plan.integrations.join(', ') || 'none'}`));
+  if (plan.dryRun) {
+    effects.out(info('Preview only. No packages, identities, credentials or services will be changed.'));
+    if (plan.scope !== 'client') effects.out(info('Server: prerequisites → runtime preparation/update → retained identity/state restoration → readiness.'));
+    if (plan.scope !== 'server' && plan.integrations.length) effects.out(info('Clients: private connection → exact packages → selected integrations → Fleet settings when selected.'));
+    return 0;
+  }
+  let clientConfig = plan.config;
+  let clientPolicy = plan.sourcePolicy;
+  if (plan.scope !== 'client') {
+    effects.out(heading(plan.operation === 'update' ? 'Server update and identity restoration' : 'Server installation'));
+    const result = await server({ ...plan, role: 'server', operation: plan.operation, sourcePolicy: plan.sourcePolicy }, effects);
+    if (result !== 0) return result;
+    const record = validateInstallation(effects.readJson(join(plan.stateDir, 'installation.json')), plan.stateDir);
+    if (plan.operation === 'update') {
+      effects.out(progress(0, 1, 'Retained identities', 'Verify the Human identity after state restoration; existing names and keys are retained.'));
+      const running = await effects.serverLifecycle(record, 'status', ['daemon']);
+      if (running.includes('daemon')) {
+        await effects.serverEnsureIdentity(record, plan.identityName);
+        effects.out(ok('Retained identities verified.'));
+      } else effects.out(info('Daemon remains stopped; stored identities are retained and will restore on the next start.'));
+    }
+    if (plan.scope === 'all' && plan.integrations.length) {
+      clientPolicy = completeReleasePolicy(readObject(effects, record.sourcesPath, 'Server source policy'), plan.sourcePolicy);
+      effects.out(heading('Connect local clients'));
+      const handoff = await effects.prepareLocalClient(record, plan.integrations, plan.fleetSettingsPath);
+      clientConfig = handoff.configPath;
+    }
+  }
+  if (plan.scope !== 'server' && plan.integrations.length) {
+    const result = await client({ role: 'client', operation: 'install', config: clientConfig,
+      integrations: plan.integrations, fleetSettingsPath: plan.fleetSettingsPath, sourcePolicy: clientPolicy,
+      preset: true, nonInteractive: !plan.interactive }, effects);
+    if (result !== 0) return result;
+  }
+  effects.out(ok(`Requested ${plan.operation} completed. Existing identities were retained.`));
+  if (plan.integrations?.includes('fleet')) effects.out(info('Fleet is configured but stopped. Review its settings, then run ours-fleet doctor, ours-fleet config and ours-fleet up.'));
+  return 0;
+}
+
+/** The sole executable entry: manual answers and CLI presets share one plan/executor. */
+export async function runSetup(argv, effects) {
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) { effects.out(USAGE); return 0; }
+    if (argv.length === 1 && ['--version', '-V'].includes(argv[0])) { effects.out(effects.version ?? 'unknown'); return 0; }
+    if (argv[0] === 'server' && maintenance.has(argv[1])) return await runServerCommand(parseNetworkArgs(argv), effects);
+    if (!argv.length && effects.env?.OURS_ASSUME_YES) throw new InstallUsageError('OURS_ASSUME_YES cannot fill an interactive setup plan. Supply complete CLI presets for unattended installation.');
+    if (!argv.length) { effects.out(banner()); effects.out(heading('Interactive setup')); }
+    const options = argv.length ? parseSetupArgs(argv, { home: effects.home }) : await collectSetupOptions(effects);
+    const plan = await prepareSetupPlan(options, effects);
+    return await executeSetupPlan(plan, effects);
+  } catch (error) {
+    if (isCancel(error)) { effects.out(warn('Installation cancelled.')); return 130; }
+    effects.out(warn(`ours-install: ${error.message}`));
+    return 2;
+  }
+}