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

package/lib/orchestrate.mjs

@@ -1,3 +1,5 @@
+import { validateGatewayClientProfile } from './target.mjs';
+import { enableGateway } from './gateway-transition.mjs';
 import { executeLegacyMigration } from './legacy-migration.mjs';
 // ours-install v3 — the orchestrator.
 //
@@ -26,7 +28,7 @@ import { executeLegacyMigration } from './legacy-migration.mjs';
 
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseNetworkArgs, validateHostProfile, parseInstallArgs, resolveTarget, resolveProfileSelection, profileEnv, InstallUsageError } from './target.mjs';
-import { selectSourcePackages, validateInstallation, SERVER_SERVICES, planDaemonConfig, planServiceInstall, serviceInstallCommand } from './plan.mjs';
+import { clientPackageNames, selectSourcePackages, validateInstallation, SERVER_SERVICES, planDaemonConfig, planServiceInstall, serviceInstallCommand } from './plan.mjs';
 import {
   COMPONENTS,
   planComponentSelection, planMcpAttachment, planTgAttachment, planCoworkAttachment,
@@ -43,6 +45,7 @@ import {
   validateChannelVersion,
 } from './marketplace.mjs';
 import { USAGE } from './usage.mjs';
+import { installerFailure } from './diagnostics.mjs';
 import { ok, info, warn, heading, banner, box, c, progress } from './ui.mjs';
 
 export const EXIT_OK = 0;
@@ -86,6 +89,37 @@ async function perform(effects, dryRun, label, thunk) {
 
 const reason = (error) => (error instanceof Error ? error.message : String(error));
 
+function clientDiagnostic(error) {
+  return installerFailure(error);
+}
+
+function clientRetry(effects, imported, integrations) {
+  effects.out(info(`Saved server connection: ${imported.configPath}.`));
+  if (integrations.includes('fleet') && !imported.settings.disableFleetAgentsSetup && !imported.settings.fleetSettingsPath) {
+    effects.out(info('Saved profile and settings retained. Run ours-install, choose Connect to an existing server, and reuse the saved profile to finish the interactive Fleet configuration.'));
+    return;
+  }
+  const args = ['client', 'install', '--config', imported.configPath, '--integrations', integrations.join(',') || 'none', '--sources', imported.settings.sourcesPath];
+  if (imported.settings.disableFleetAgentsSetup) args.push('--disable-fleet-agents-setup');
+  if (imported.settings.fleetSettingsPath) args.push('--fleet-settings', imported.settings.fleetSettingsPath);
+  const command = `ours-install client install ${args.slice(2).map((value, i) => i % 2 === 0 ? value : shellQuote(value)).join(' ')}`;
+  effects.out(info(`Saved profile and settings retained; re-run ${command}`));
+}
+
+function explainClientFailure(effects, name, row) {
+  const label = { codex: 'Codex', 'claude-code': 'Claude Code', fleet: 'Fleet' }[name];
+  const command = name === 'claude-code' ? 'claude' : name;
+  if (row?.note === 'not installed') {
+    effects.out(warn(`${label}: executable not found on PATH. Install ${label} or make its executable available in this shell, then check ${command} --version before retrying.`));
+  } else if (row?.manual) {
+    effects.out(warn(`${label}: cannot register the plugin automatically — ${clientDiagnostic(row.note)}. Use the real executable (check ${command} --version), or register the displayed local marketplace manually.`));
+  } else {
+    effects.out(warn(`${label}: ${row?.failedStep ?? 'integration setup'} failed. ${clientDiagnostic(row?.detail ?? row?.note ?? 'The integration did not report successful completion. Review the messages above.')} Fix the reported command error before retrying.`));
+    if (row?.failedCommand) effects.out(info(`Failed command: ${row.failedCommand.map(shellQuote).join(' ')}`));
+  }
+}
+
+
 function semverMajor(version) {
   const match = /^(?:[~^<>= ]*)(\d+)\./.exec(String(version ?? '').trim());
   return match ? Number(match[1]) : null;
@@ -110,6 +144,7 @@ function incompatibleUpgrade(target, cliDependencies) {
 async function prepareIncompatibleUpgrade(args, effects, target, cliPkg, mismatch) {
   const dir = target.stateDir;
   const configPath = join(dir, 'config.json');
+  const owner = effects.readJson(join(dir, 'ours-cli-daemon.json'))?.owner === '@ours.network/daemon' ? ['ours-daemon'] : ['ours', 'daemon'];
   if (mismatch.unknown) {
     effects.out(warn(`ours: cannot verify whether ${cliPkg} can restore daemon v${mismatch.runningVersion}. Nothing was changed.`));
     effects.out(info('Check npm registry access and re-run; compatibility checks fail closed.'));
@@ -153,13 +188,13 @@ async function prepareIncompatibleUpgrade(args, effects, target, cliPkg, mismatc
   }
 
   await perform(effects, false, 'stop the incompatible daemon', () => effects.run(
-    'ours', ['daemon', 'stop', '--state-dir', dir, '--config', configPath], { stream: true },
+    owner[0], [...owner.slice(1), 'stop', '--state-dir', dir, '--config', configPath], { stream: true },
   ));
   try {
     await perform(effects, false, `back up complete daemon state to ${backupPath}`, () => effects.copyDir(dir, backupPath));
   } catch (error) {
     try {
-      await effects.run('ours', ['daemon', 'start', '--state-dir', dir, '--config', configPath], { stream: true });
+      await effects.run(owner[0], [...owner.slice(1), 'start', '--state-dir', dir, '--config', configPath], { stream: true });
       effects.out(ok('backup failed, but the old daemon was started again'));
     } catch {
       effects.out(warn(`backup failed and the old daemon did not restart; its state is still untouched at ${dir}`));
@@ -168,11 +203,11 @@ async function prepareIncompatibleUpgrade(args, effects, target, cliPkg, mismatc
   }
   try {
     await perform(effects, false, 'remove the incompatible daemon boot service', () => effects.run(
-      'ours', ['daemon', 'uninstall-service', '--yes', '--state-dir', dir, '--config', configPath], { stream: true },
+      owner[0], [...owner.slice(1), 'uninstall-service', '--yes', '--state-dir', dir, '--config', configPath], { stream: true },
     ));
   } catch (error) {
     try {
-      await effects.run('ours', ['daemon', 'start', '--state-dir', dir, '--config', configPath], { stream: true });
+      await effects.run(owner[0], [...owner.slice(1), 'start', '--state-dir', dir, '--config', configPath], { stream: true });
       effects.out(ok(`service removal failed, but the old daemon was started again; backup retained at ${backupPath}`));
     } catch {
       effects.out(warn(`service removal failed and the old daemon did not restart; state remains at ${dir} and the backup is at ${backupPath}`));
@@ -193,11 +228,11 @@ async function prepareIncompatibleUpgrade(args, effects, target, cliPkg, mismatc
  * rather than one harness. So a failure here is one honest line plus whatever
  * the caller wants to say about retrying, and the walk continues.
  */
-async function attempt(effects, dryRun, label, thunk) {
+async function attempt(effects, dryRun, label, thunk, formatReason = reason) {
   try {
     return { ok: true, ...(await perform(effects, dryRun, label, thunk)) };
   } catch (error) {
-    effects.out(warn(`${label} — did not complete: ${reason(error)}`));
+    effects.out(warn(`${label} — did not complete: ${formatReason(error)}`));
     return { ok: false, error };
   }
 }
@@ -333,14 +368,13 @@ export async function runDaemonPhase(args, effects, exactSuite = null) {
   const mcpPkg = exactSuite?.packages?.mcp
     ? `@ours.network/mcp@${exactSuite.packages.mcp}`
     : componentSpec(componentByKey('mcp'), args.channel);
-  // The CLI intentionally publishes only `latest`; unlike the lockstep MCP and
-  // connector packages it has no nightly dist-tag. Keep this untagged on every
-  // installer channel, and inspect that package's SDK dependency for the gate.
-  const cliPkg = '@ours.network/cli';
+  // Inspect the runtime package SDK compatibility before replacing the owner.
+  const cliPkg = args.channel === 'nightly' ? '@ours.network/cli@nightly' : '@ours.network/cli';
+  const daemonPkg = args.channel === 'nightly' ? '@ours.network/daemon@nightly' : '@ours.network/daemon';
   if (!creating && target.daemonVersion) {
-    const mismatch = incompatibleUpgrade(target, effects.packageDependencies(cliPkg));
+    const mismatch = incompatibleUpgrade(target, effects.packageDependencies(daemonPkg));
     if (mismatch) {
-      const prepared = await prepareIncompatibleUpgrade(args, effects, target, cliPkg, mismatch);
+      const prepared = await prepareIncompatibleUpgrade(args, effects, target, daemonPkg, mismatch);
       if (prepared.refused) return { target, refused: prepared.refused, steps };
       creating = prepared.purged === true;
       target.backupPath = prepared.backupPath;
@@ -349,6 +383,18 @@ export async function runDaemonPhase(args, effects, exactSuite = null) {
   }
   await perform(effects, args.dryRun, `MCP server installed (npm i -g ${mcpPkg})`, () => effects.run('npm', ['i', '-g', mcpPkg]));
   steps.push({ id: 'mcp-package', changed: true, packageRefresh: true });
+  await perform(effects, args.dryRun, 'daemon runtime installed', () => effects.run('npm', ['i', '-g', daemonPkg]));
+  // A retained global unit still points into the old CLI package. Rewrite and
+  // activate that owned unit before npm replaces its executable with thin CLI.
+  let migratedService;
+  if (!creating) {
+    const retained = planServiceInstall({ stateDir: dir, home: effects.home, readText: effects.readText, platform: effects.platform?.platform });
+    if (retained.unitPath && effects.readText(retained.unitPath) !== null) {
+      try { migratedService = await runServicePhase(args, effects, dir, target.port); }
+      catch (error) { await recoverDaemon(args, effects, dir, join(dir, 'config.json'), target.port); throw error; }
+      if (migratedService.refused) return { target, refused: migratedService.refused, steps };
+    }
+  }
   await perform(effects, args.dryRun, `ours CLI installed (npm i -g ${cliPkg})`, () => effects.run('npm', ['i', '-g', cliPkg]));
   steps.push({ id: 'cli', changed: true, packageRefresh: true });
 
@@ -383,14 +429,14 @@ export async function runDaemonPhase(args, effects, exactSuite = null) {
 
   try {
     if (creating) {
-      await perform(effects, args.dryRun, `start the daemon on port ${target.port}`, () => effects.run('ours', ['daemon', 'start', '--config', configPath], { stream: true }));
+      await perform(effects, args.dryRun, `start the daemon on port ${target.port}`, () => effects.run('ours-daemon', [ 'start', '--config', configPath], { stream: true }));
       steps.push({ id: 'start', changed: true });
     } else {
-      await perform(effects, args.dryRun, `restart the daemon on port ${target.port}`, () => effects.run('ours', ['daemon', 'restart', '--config', configPath], { stream: true }));
+      await perform(effects, args.dryRun, `restart the daemon on port ${target.port}`, () => effects.run('ours-daemon', [ 'restart', '--config', configPath], { stream: true }));
       steps.push({ id: 'restart', changed: true });
     }
 
-    const service = await runServicePhase(args, effects, dir, target.port);
+    const service = migratedService ?? await runServicePhase(args, effects, dir, target.port);
     if (service.unsupported) serviceUnsupported = service.unsupported;
     if (service.refused) {
       // A REFUSAL IS A FAILURE TO REACH THE STATE, not a special case. An unknown
@@ -420,7 +466,7 @@ export async function runDaemonPhase(args, effects, exactSuite = null) {
       effects.out(recovery.recovered
         ? ok('your daemon is running again — nothing was committed, and the service is unchanged')
         : warn('and the daemon did NOT come back up — start it yourself before anything else: '
-          + `ours daemon start --config ${configPath}`));
+          + `ours-daemon start --config ${configPath}`));
     }
     throw error;
   }
@@ -443,7 +489,7 @@ export async function runDaemonPhase(args, effects, exactSuite = null) {
 async function recoverDaemon(args, effects, dir, configPath, port) {
   if (args.dryRun) return null;
   try {
-    await effects.run('ours', ['daemon', 'start', '--config', configPath]);
+    await effects.run('ours-daemon', [ 'start', '--config', configPath]);
     return { recovered: true };
   } catch (recoveryError) {
     return { recovered: false, reason: reason(recoveryError) };
@@ -794,7 +840,7 @@ export async function runIdentityPhase(args, effects, { target, mcpReady }) {
     }
     if (/not running|not reachable|ECONNREFUSED|connect/i.test(text)) {
       effects.out(warn("The daemon isn't reachable yet — couldn't create your human identity."));
-      effects.out(info(`Fix: run 'ours daemon start --config ${env.OURS_CONFIG}', then 'ours identity create-root --config ${env.OURS_CONFIG} --name "${name}"'.`));
+      effects.out(info(`Fix: run 'ours-daemon start --config ${env.OURS_CONFIG}', then 'ours identity create-root --config ${env.OURS_CONFIG} --name "${name}"'.`));
       return { key: 'identity', label: 'Human identity', state: 'failed', note: 'daemon not reachable' };
     }
     effects.out(warn(`Couldn't create your human identity: ${text.split('\n')[0]}`));
@@ -817,6 +863,9 @@ export async function runIdentityPhase(args, effects, { target, mcpReady }) {
 export async function runHarnessPhase(args, effects, { target, isDefaultStateDir, exactSuite = null }) {
   effects.out(heading('Harness plugins'));
   const detected = (await effects.detectHarnesses()).filter(h => !args.clientIntegrations || args.clientIntegrations.includes(h.name));
+  for (const name of args.clientIntegrations ?? []) {
+    if (name !== 'fleet' && !detected.some(h => h.name === name)) detected.push({ name, status: 'absent' });
+  }
   for (const h of detected) {
     if (h.status === 'ok') effects.out(ok(`'${h.command ?? h.name}'  → ${h.detail ?? 'real program'} (its plugin can be installed)`));
     else if (h.status === 'alias') effects.out(warn(`'${h.command ?? h.name}'  → ${h.detail} (I won't call it — manual steps below)`));
@@ -826,7 +875,7 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
   if (detected.every((h) => h.status === 'absent')) {
     effects.out(info('No Claude Code, Codex or Hermes found — install one and re-run to wire it up.'));
     effects.out(info('Your daemon is unaffected; nothing else in this run depends on a harness.'));
-    return [];
+    return args.clientIntegrations ? detected.map(h => ({ key: h.name, state: 'skipped', note: 'not installed' })) : [];
   }
 
   const plans = planHarnessPlugins({
@@ -851,7 +900,7 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
     if (plan.action === 'manual' && exactSuite?.localPackages?.[plan.name]) {
       const root = await effects.prepareClientMarketplace(plan.name, exactSuite.localPackages[plan.name]);
       effects.out(warn(`${plan.label} requires manual registration of exact local marketplace ${root}; ${target.managed ? 'the saved client default is retained' : `keep OURS_CONFIG=${target.configPath}`}.`));
-      rows.push({ ...row, state: 'failed', note: 'native executable unavailable' });
+      rows.push({ ...row, state: 'failed', note: plan.reason, manual: true });
       continue;
     }
     if (plan.action === 'manual') {
@@ -873,7 +922,7 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
       effects.out(warn(`${plan.label} — ${plan.reason}; install it yourself with:`));
       for (const step of manual) effects.out(info(`  ${step}`));
       if (plan.envLine) effects.out(info(`Before later native launches, set:  ${plan.envLine}`));
-      rows.push({ ...row, state: 'skipped', note: plan.reason });
+      rows.push({ ...row, state: 'skipped', note: plan.reason, manual: true });
       continue;
     }
 
@@ -884,13 +933,16 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
       const steps = plan.name === 'codex'
         ? [['codex', 'plugin', 'marketplace', 'add', registration], ['codex', 'plugin', 'add', 'ours@ours-codex-marketplace']]
         : [['claude', 'plugin', 'marketplace', 'add', registration], ['claude', 'plugin', await effects.hasClaudePlugin() ? 'update' : 'install', 'ours@ours.network']];
-      let failed = false;
+      let failure = null;
       for (const step of steps) {
-        const outcome = await attempt(effects, false, step.join(' '), () => effects.run(step[0], step.slice(1), { env: profileEnv(target) }));
-        if (!outcome.ok) { failed = true; break; }
+        const outcome = await attempt(effects, false, step.join(' '), () => effects.run(step[0], step.slice(1), { env: profileEnv(target) }), clientDiagnostic);
+        if (!outcome.ok) {
+          failure = { failedCommand: step, failedStep: step[2] === 'marketplace' ? `Register ${plan.label} marketplace` : `Install ${plan.label} plugin`, detail: clientDiagnostic(outcome.error) };
+          break;
+        }
       }
       effects.out(info(target.managed ? `Native ${plan.name} launches use the saved client default.` : `Native ${plan.name} launches must retain OURS_CONFIG=${target.configPath}.`));
-      rows.push({ ...row, state: failed ? 'failed' : 'installed' });
+      rows.push({ ...row, state: failure ? 'failed' : 'installed', ...(failure ?? {}) });
       continue;
     }
 
@@ -956,6 +1008,11 @@ export async function runFleetPhase(args, effects, { target, isDefaultStateDir }
     return { key: 'fleet', label: plan.label, state: 'skipped' };
   }
   const install = args.acquiredFleet ? { ok: true } : await attempt(effects, args.dryRun, plan.install.join(' '), () => effects.run(plan.install[0], plan.install.slice(1)));
+  if (args.disableFleetAgentsSetup) {
+    if (!install.ok) return { key: 'fleet', label: plan.label, state: 'failed', note: 'Fleet installation failed' };
+    effects.out(ok('Fleet CLI installed; agent and model setup deferred to the App. Existing Fleet configuration was retained.'));
+    return { key: 'fleet', label: plan.label, state: 'installed', note: 'agents setup deferred' };
+  }
   // Fleet owns its v2 manifest, roles, models and permissions. With no prepared
   // settings, its wizard keeps the user's terminal while this invocation carries
   // the selected daemon; --settings makes the same call strictly noninteractive.
@@ -1262,15 +1319,22 @@ async function executeServerCommand(args, effects) {
   const existing = record !== null;
   if (existing) {
     record = validateInstallation(record, args.stateDir);
+    if (args.containerEngine && args.containerEngine !== (record.containerEngine ?? 'docker')) throw new Error('Conflicting container engine; explicit migration is required');
     if (args.mode && args.mode !== record.mode) throw new Error('Conflicting runtime mode; retained installation was not changed');
     if (args.operation !== 'update' && args.sources && (record.sourcePolicyHash
       ? effects.sourcePolicyHash(args.sources) !== record.sourcePolicyHash
       : effects.readText(args.sources) !== effects.readText(record.sourcesPath))) throw new Error('Conflicting source selection; use explicit server update');
   } else {
     if (args.operation !== 'install' || !args.mode) throw new Error('First server install requires --mode');
-    record = effects.newInstallation(args.stateDir, args.mode);
+    record = effects.newInstallation(args.stateDir, args.mode, args);
     for (const key of ['port', 'coworkPort', 'messengerPort']) if (args[key] !== undefined) record[key] = args[key];
   }
+  if (effects.readJson(join(record.root, 'gateway-transition.json')) && args.operation !== 'gateway-enable' && args.operation !== 'status') throw new Error('Interrupted gateway migration; run server gateway-enable before other changes');
+  if (args.serverUrl && args.operation === 'install') {
+    if (!record.gateway) throw new Error('Use server gateway-enable to migrate an existing Docker installation');
+    if (existing && record.gateway.serverUrl !== args.serverUrl) throw new Error('Conflicting gateway server URL');
+    record.gateway = { ...record.gateway, serverUrl: args.serverUrl };
+  }
   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');
   }
@@ -1278,7 +1342,8 @@ async function executeServerCommand(args, effects) {
     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);
+  const installStageCount = (existing ? 7 : 9) + (args.identityName ? 2 : 0)
+    + (args.identityName && args.name && args.surname && (!existing || [undefined, null, args.identityName, `${args.name} ${args.surname}`].includes(record.messengerIdentity)) ? 1 : 0);
   let completedInstallStages = 0;
   const installStage = async (label, explanation, action) => {
     if (!showInstallProgress) return action();
@@ -1301,7 +1366,7 @@ async function executeServerCommand(args, effects) {
   }
   if (!existing && args.sources) record.sourcePolicyHash = effects.sourcePolicyHash(args.sources);
   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,
+    existing, sourcePath: args.sources ?? record.sourcesPath, sourceManifest: args.resolvedSources, identityName: args.identityName, explicitPorts: args.explicitPorts,
   }));
   if (existing && (record.schema === 1 || record.layoutConversion)
     && ['install', 'start', 'restart', 'update', 'rebuild'].includes(args.operation)) {
@@ -1331,13 +1396,26 @@ async function executeServerCommand(args, effects) {
     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;
+      // Messenger runs as the person's own identity under the Human identity when Name and Surname are known.
+      // An installation whose Messenger already runs as some other identity under it keeps that identity.
+      const person = args.name && args.surname ? `${args.name} ${args.surname}` : undefined;
+      const selected = existing ? record.messengerIdentity : undefined;
+      if (person && (!selected || selected === identity.name || selected === person)) {
+        const own = await installStage('Messenger identity', 'Keep or create your own identity under the Human identity; Messenger runs as it.', () => effects.serverEnsureMessengerIdentity(record, person));
+        record.messengerIdentity = own.name;
+      } else if (selected && selected !== identity.name
+          && (await effects.serverListIdentities(record)).some(row => row.name === selected && row.kind === 'role' && row.temp === null)) {
+        record.messengerIdentity = selected;
+      } else 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 (record.gateway) await effects.verifyGateway(record);
     if (showInstallProgress) effects.out(progress(installStageCount, installStageCount, 'Installation complete', 'The selected services are ready.'));
+  } else if (args.operation === 'gateway-enable') {
+    await enableGateway(record, args, effects);
   } else if (['backup', 'restore', 'reset'].includes(args.operation)) {
     await effects.serverMaintenance(record, args);
   } else if (['update', 'rebuild'].includes(args.operation)) {
@@ -1385,22 +1463,21 @@ export async function runClientCommand(command, effects) {
     configPath = managedPath;
   }
   let profile;
-  if (configPath) profile = validateHostProfile(effects.readProfile(configPath));
+  if (configPath) profile = validateGatewayClientProfile(effects.readProfile(configPath));
   else if (!command.preset && effects.interactive) {
-    const endpoint = await effects.askLine('Server HTTP endpoint: ', 'http://127.0.0.1:3050');
+    const endpoint = await effects.askLine('Server HTTP or HTTPS 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');
     profile = await effects.discoverClientProfile(endpoint, credentialPath);
   }
   if (!profile) throw new InstallUsageError('client install requires a complete network profile; supply --config or use the interactive client setup');
-  if (saved && (saved.endpoint !== profile.endpoint || saved.expectedInstanceId !== profile.expectedInstanceId))
+  if (saved && saved.expectedInstanceId !== profile.expectedInstanceId)
     throw new InstallUsageError('Managed client already selects another server; existing default was not changed');
   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 client profile selection`);
   }
   effects.out(info(`Selected server ${profile.endpoint} (instance ${profile.expectedInstanceId}).`));
   await effects.verifyHostProfile(configPath || profile);
-  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 = command.integrations ?? settings?.integrations;
@@ -1408,13 +1485,14 @@ export async function runClientCommand(command, effects) {
     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');
+  if (!Array.isArray(integrations) || integrations.some(name => !['codex', 'claude-code', 'fleet'].includes(name)) || new Set(integrations).size !== integrations.length) throw new InstallUsageError('installer.integrations must be an array of codex, claude-code and/or fleet; use an empty array for CLI only');
   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');
+  const disableFleetAgentsSetup = command.disableFleetAgentsSetup ?? settings?.disableFleetAgentsSetup ?? false;
+  if (command.nonInteractive && !disableFleetAgentsSetup && 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])];
+  const selectedClients = clientPackageNames(integrations);
   let sourcesPath = settings?.sourcesPath;
   let resolvedSources;
   if (command.sourcePolicy) {
@@ -1427,30 +1505,38 @@ export async function runClientCommand(command, effects) {
     resolvedSources = await effects.resolveSourcePolicy(policy, 'client', selectedClients);
   }
   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 });
+  if (profile.serverUrl && integrations.includes('fleet')) await effects.qualifyGatewayClient({ profile, sourcesPath, sources: resolvedSources, integrations, refresh: !!command.preset });
+  const imported = effects.importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath, disableFleetAgentsSetup, refresh: !!command.preset });
+  let phase = 'Validate saved server connection';
   try {
     await effects.verifyHostProfile(imported.configPath);
     effects.out(progress(1, 4, 'Client packages', 'Acquire and verify the selected client package versions.'));
+    phase = 'Acquire client packages';
     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 };
+      acquiredFleet: exactSuite.fleetBin, fleetSettingsPath: imported.settings.fleetSettingsPath, disableFleetAgentsSetup: imported.settings.disableFleetAgentsSetup };
     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.'));
+    phase = 'Register client integrations';
     const summary = await runHarnessPhase(args, effects, { target, isDefaultStateDir: false, exactSuite });
     if (integrations.includes('fleet')) {
       effects.out(progress(3, 4, 'Fleet configuration', 'Apply prepared settings or open the selected Fleet wizard.'));
+      phase = 'Configure Fleet';
       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(warn(`Client setup incomplete (${incomplete.join(', ')}). The selected client integrations need attention:`));
+      for (const name of incomplete) explainClientFailure(effects, name, summary.find(row => row.key === name));
+      clientRetry(effects, imported, integrations);
+    } else effects.out(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.`));
+    effects.out(warn(`Client setup incomplete: ${phase} failed — ${clientDiagnostic(error)}. Fix this error before retrying.`));
+    clientRetry(effects, imported, integrations);
     return EXIT_REFUSED;
   }
 }

package/lib/plan.mjs

@@ -1,3 +1,5 @@
+import { validateContainerEngine } from './container-engine.mjs';
+import { gatewayAddress } from './gateway.mjs';
 // ours-install v3 — daemon creation and boot-service installation.
 //
 // Pure planning code, like lib/target.mjs: the orchestrator
@@ -97,7 +99,7 @@ export function launchdLabelForStateDir(stateDir) {
 export function classifyUnit(text) {
   if (text === null || text === undefined) return { kind: 'absent' };
   const s = String(text);
-  if (s.startsWith(CLI_UNIT_MARKER)) return { kind: 'cli-managed' };
+  if ((s.startsWith(CLI_UNIT_MARKER) || s.startsWith('# Managed by @ours.network/daemon'))) return { kind: 'cli-managed' };
   const looksLikeOursMcp = /ExecStart=.*\bours-mcp\b/.test(s)
     || /^Description=ours MCP daemon\b/m.test(s)
     || (/^Environment=OURS_STATE_DIR=/m.test(s) && /^Environment=OURS_TRANSPORT=http$/m.test(s));
@@ -138,7 +140,7 @@ export function planServiceInstall({ stateDir, home, readText, platform = 'linux
       platform,
       reason: 'no-service-manager',
       message: `installing a boot service is not available on ${platform} — the ours CLI supports Linux user systemd and macOS launchd`,
-      manual: ['ours', 'daemon', 'serve', '--config'],
+      manual: ['ours-daemon', 'serve', '--config'],
     };
   }
 
@@ -224,7 +226,7 @@ export function serviceInstallCommand({ stateDir, adoptLegacyUnit = false }) {
   // --json so the caller can read back whether the unit actually CHANGED rather
   // than assuming it did. --force is reachable only through the explicit argument
   // above, and the CLI refuses to overwrite a unit it did not write.
-  const cmd = ['ours', 'daemon', 'install-service', '--yes', '--json', '--state-dir', dir, '--config', join(dir, 'config.json')];
+  const cmd = ['ours-daemon', 'install-service', '--yes', '--json', '--state-dir', dir, '--config', join(dir, 'config.json')];
   if (adoptLegacyUnit) cmd.push('--force');
   return cmd;
 }
@@ -265,20 +267,20 @@ export function planDaemonSteps(target, { cliVersionChanged = false, cliStartedI
   const steps = [{ id: 'cli', label: 'install the ours-sdk CLI', command: ['npm', 'i', '-g', '@ours.network/cli'] }];
   steps.push({ id: 'config', label: `write ${join(dir, 'config.json')}`, port: target.port });
   if (target.action === 'create') {
-    steps.push({ id: 'start', label: `start the daemon on port ${target.port}`, command: ['ours', 'daemon', 'start', '--config', join(dir, 'config.json')] });
+    steps.push({ id: 'start', label: `start the daemon on port ${target.port}`, command: ['ours-daemon', 'start', '--config', join(dir, 'config.json')] });
   } else if (cliVersionChanged) {
     // `ours daemon stop` refuses to signal a daemon it did not start, so a
     // daemon under another launcher is left running and the caller says which
     // launcher must be restarted instead.
     steps.push(cliStartedIt
-      ? { id: 'restart', label: 'restart the daemon (package version changed)', command: ['ours', 'daemon', 'restart', '--config', join(dir, 'config.json')] }
+      ? { id: 'restart', label: 'restart the daemon (package version changed)', command: ['ours-daemon', 'restart', '--config', join(dir, 'config.json')] }
       : { id: 'restart-external', label: 'daemon was not started by the CLI — restart it with its own launcher', command: null });
   }
   steps.push({ id: 'service', label: 'install the boot service', command: serviceInstallCommand({ stateDir: dir }) });
   return steps;
 }
 
-export const SERVER_PACKAGES = ['sdk', 'cli', 'mcp', 'tg-connector', 'cowork', 'messenger-server'].map(n => `@ours.network/${n}`);
+export const SERVER_PACKAGES = ['sdk', 'cli', 'daemon', 'tg-connector', 'cowork', 'messenger-server'].map(n => `@ours.network/${n}`);
 export const SERVER_DEPENDENCIES = {
   daemon: [], telegram: ['daemon'], cowork: ['daemon'], messenger: ['daemon'],
 };
@@ -356,15 +358,21 @@ export function installationPaths(record) {
 }
 
 export function validateInstallation(record, root) {
+  if (record) validateContainerEngine(record);
   if (!record || ![1, 2].includes(record.schema) || !['docker', 'packages'].includes(record.mode)
     || record.root !== root || record.configPath !== installationPaths(record).config
     || record.sourcesPath !== join(root, 'sources.json') || record.workDir !== join(root, 'runtime')
     || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(record.instanceId ?? '')
     || !/^ours-[a-z0-9]+$/.test(record.project ?? '')
     || (record.sourcePolicyHash !== undefined && !/^[0-9a-f]{64}$/.test(record.sourcePolicyHash))
-    || !Array.isArray(record.services) || record.services[0] !== 'daemon' || new Set(record.services).size !== record.services.length || record.services.some(s => !SERVER_SERVICES.includes(s))) {
+    || !Array.isArray(record.services) || record.services[0] !== 'daemon' || new Set(record.services).size !== record.services.length || record.services.some(s => !SERVER_SERVICES.includes(s) && !(s === 'gateway' && record.gateway?.version === 1))) {
     throw new Error('Invalid or conflicting installation selection');
   }
+  if (record.gateway !== undefined && (record.schema !== 2 || record.mode !== 'docker' || record.gateway?.version !== 1
+    || Object.keys(record.gateway).some(key => !['version', 'serverUrl'].includes(key)) || record.services.at(-1) !== 'gateway')) {
+    throw new Error('Invalid gateway installation selection');
+  }
+  if (record.gateway) gatewayAddress(record);
   if (record.layoutConversion !== undefined) {
     // DEPRECATED (introduced in 2.0): legacy managed-layout conversion only.
     // Removal target: 3.0, after supported installs convert and upgrade inputs
@@ -380,7 +388,8 @@ export function validateInstallation(record, root) {
       throw new Error('Invalid layout conversion record');
     }
     validateInstallation(source, root);
-    if (['mode', 'instanceId', 'project', 'sourcesPath', 'workDir'].some(key => source[key] !== record[key])
+    if (JSON.stringify(source.containerBinding) !== JSON.stringify(record.containerBinding)) throw new Error('Conflicting conversion backend');
+    if (['mode', 'containerEngine', 'instanceId', 'project', 'sourcesPath', 'workDir'].some(key => source[key] !== record[key])
       || JSON.stringify(source.services) !== JSON.stringify(record.services)
       || conversion.runningServices.some(service => !source.services.includes(service))) {
       throw new Error('Conflicting layout conversion source');
@@ -402,7 +411,7 @@ export function validateInstallation(record, root) {
       throw new Error('Invalid server build transition');
     }
     validateInstallation(candidate, candidate.root);
-    for (const key of ['schema', 'mode', 'instanceId', 'services', 'port', 'coworkPort', 'messengerPort', 'messengerIdentity', 'uid', 'gid']) {
+    for (const key of ['schema', 'mode', 'containerEngine', 'containerBinding', 'instanceId', 'services', 'gateway', 'port', 'coworkPort', 'messengerPort', 'messengerIdentity', 'uid', 'gid']) {
       if (JSON.stringify(candidate[key]) !== JSON.stringify(record[key])) throw new Error('Conflicting server build candidate');
     }
   }
@@ -470,3 +479,7 @@ export function consumerServiceState(text, service, platform) {
   }
   return matches === 1 ? selected : undefined;
 }
+
+export function clientPackageNames(integrations) {
+  return [...new Set(['sdk', 'cli', ...(integrations.some(name => ['codex', 'claude-code'].includes(name)) ? ['mcp'] : []), ...integrations])];
+}

package/lib/podman-preflight.mjs

@@ -0,0 +1,40 @@
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { runContainer } from './container-engine.mjs';
+
+export const PROBE_IMAGE = 'docker.io/library/nginx:1.28-alpine@sha256:a8b39bd9cf0f83869a2162827a0caf6137ddf759d50a171451b335cecc87d236';
+/** Behavioral checks, in disposable resources, before touching installation storage. */
+export async function qualifyPodman(effects, record) {
+  const root = mkdtempSync(join(tmpdir(), 'ours-podman-preflight-'));
+  const project = `ours-probe-${randomUUID()}`;
+  const file = join(root, 'compose.json'), overlay = join(root, 'reset.yaml');
+  const common = { image: PROBE_IMAGE, entrypoint: ['/bin/sh', '-ec'], read_only: true, cap_drop: ['ALL'], security_opt: ['no-new-privileges:true'] };
+  writeFileSync(file, JSON.stringify({ services: {
+    prepare: { ...common, user: '0:0', network_mode: 'none', cap_add: ['CHOWN', 'DAC_OVERRIDE'],
+      command: ['mkdir -p /storage/state/daemon /storage/state/sibling; chmod 700 /storage/state/daemon; chown 1000:1000 /storage/state/daemon'],
+      volumes: [{ type: 'volume', source: 'data', target: '/storage', volume: { nocopy: true } }] },
+    probe: { ...common, user: '1000:1000', command: ['test ! -e /data/sibling; test "$(stat -c %a /data)" = 700; nslookup -type=A probe.; echo ready > /data/probe; sleep 120'],
+      healthcheck: { test: ['CMD-SHELL', 'test -s /data/probe'], interval: '1s', timeout: '2s', retries: 10 },
+      volumes: [{ type: 'volume', source: 'data', target: '/data', volume: { nocopy: true, subpath: 'state/daemon' } }] },
+  }, volumes: { data: {} } }), { mode: 0o600 });
+  writeFileSync(overlay, 'services:\n  probe:\n    ports: !reset []\n', { mode: 0o600 });
+  const compose = args => runContainer(effects, record, ['compose', '-p', project, '-f', file, '-f', overlay, ...args], { timeout: 180000 });
+  try {
+    await compose(['config', '--format', 'json']);
+    await compose(['run', '--rm', '--no-deps', '-T', 'prepare']);
+    await compose(['up', '-d', '--no-build', '--wait', 'probe']);
+    const result = await compose(['ps', '--format', 'json']);
+    const rows = result.stdout.trim().startsWith('[') ? JSON.parse(result.stdout) : result.stdout.trim().split('\n').map(s => JSON.parse(s));
+    if (!rows.some(r => r.Service === 'probe' && r.State === 'running')) throw new Error('Compose JSON status is incompatible');
+    await compose(['exec', '-T', 'probe', '/bin/sh', '-ec', 'test -s /data/probe; test ! -e /data/state']);
+  } catch (cause) {
+    let logs = '';
+    try { logs = (await compose(['logs', '--no-color', '--tail', '30'])).stdout; } catch {}
+    throw new Error(`Podman capability check failed (Compose !reset/wait/status, DNS, rootless UID, volume subpath): ${cause.message}\n${logs}`, { cause });
+  } finally {
+    try { await compose(['down', '--volumes', '--remove-orphans']); }
+    finally { rmSync(root, { recursive: true, force: true }); }
+  }
+}