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

package/lib/effects.mjs

@@ -1,3 +1,6 @@
+import { selectServerPorts } from './server-ports.mjs';
+import { qualifyPodman } from './podman-preflight.mjs';
+import { engineName, bindPodman, runContainer, nativeBuildCommands } from './container-engine.mjs';
 // ours-install v3 — the real side effects.
 //
 // Every mutation the installer can perform lives here and nowhere else, behind
@@ -11,21 +14,25 @@
 // state-directory guard and the enable/reload. The installer never touches a
 // unit file or the service manager directly.
 
+import { publishClientCli } from './client-cli.mjs';
+import { commandFailure } from './diagnostics.mjs';
 import { spawnSync, execFileSync } from 'node:child_process';
 import { chmodSync, closeSync, constants, cpSync, existsSync, fstatSync, lstatSync, openSync, readFileSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir, userInfo, platform as osPlatform, release as osRelease, arch as osArch } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { randomUUID, createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
-import { maintenanceServices, installationPaths, validateInstallation, consumerServiceState, unitNameForStateDir, launchdLabelForStateDir, messengerServicePlan, selectSourcePackages, resolveSourcePolicy, SERVER_SERVICES } from './plan.mjs';
-import { validateHostProfile } from './target.mjs';
+import { clientPackageNames, maintenanceServices, installationPaths, validateInstallation, consumerServiceState, unitNameForStateDir, launchdLabelForStateDir, messengerServicePlan, selectSourcePackages, resolveSourcePolicy, SERVER_SERVICES } from './plan.mjs';
+import { validateHostProfile, validateGatewayClientProfile } from './target.mjs';
+import { serverBase, validateGatewayDiscovery, gatewayCompose, gatewayNginx, gatewayAddress } from './gateway.mjs';
 import { createServerOnboarding } from './server-onboarding.mjs';
 import { atomicWriteConfig, snapshotConfig, restoreConfig } from './config.mjs';
 import { select as selectOnTty, multiselect as multiselectOnTty, askLine as askLineOnTty } from './prompt.mjs';
 import { classifyHarnessProbe } from './logic.mjs';
+import { qualifyDockerRuntime, refreshDockerPolicyCopy } from './docker-runtime-repair.mjs';
 import { classifyStateDir } from './detect.mjs';
 import { BASE_RECORDS, CONTEXT, readBuildRecords, equalBuildRecords, initializeBuildMarker } from '../assets/scripts/maintenance/build-context.mjs';
-import { releaseBinding, verifyReleaseGraph, verifyRuntimeRelease } from '../assets/scripts/maintenance/release-graph.mjs';
+import { hostCliPolicy, releaseBinding, verifyReleaseGraph, verifyRuntimeRelease } from '../assets/scripts/maintenance/release-graph.mjs';
 
 /** GET http://127.0.0.1:<port>/state-dir — the unauthenticated identity probe. */
 async function probePort(port, { timeoutMs = 1500 } = {}) {
@@ -399,7 +406,7 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
     // invocation only and never to the installer's own process: a state
     // directory selected by one run must not leak into anything the operator
     // starts afterwards.
-    run: async (cmd, args, { env: extraEnv = null, stream = false, cwd, sensitive = false, allowCodes = [] } = {}) => {
+    run: async (cmd, args, { env: extraEnv = null, stream = false, cwd, sensitive = false, allowCodes = [], timeout } = {}) => {
       // Always built from this layer's OWN env rather than left to spawnSync's
       // implicit inheritance, so what a child receives is a property of the
       // effects object a caller constructed and not of whatever ambient shell
@@ -410,18 +417,18 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
       const executable = cmd === 'npm' ? npmBin : cmd;
       const r = spawnSync(executable, args, {
         cwd,
+        timeout,
         encoding: 'utf8',
         stdio: [...(stream ? ['ignore', 'inherit', 'inherit'] : ['ignore', 'pipe', 'pipe']), ...(installationLockFd === null ? [] : [installationLockFd])],
         env: childEnv,
       });
       if (r.error) {
-        const error = new Error(`${executable} could not start (${r.error.code ?? 'launch error'})`, { cause: r.error });
+        const error = commandFailure(executable, args, r, { sensitive, cwd, env: childEnv });
         error.code = r.error.code;
         throw error;
       }
       if (r.status !== 0 && !allowCodes.includes(r.status)) {
-        const detail = sensitive ? '' : (r.stderr || r.stdout || '').trim().split('\n').slice(-3).join('; ');
-        throw new Error(`${executable} ${args.join(' ')} exited ${r.status}${detail ? `: ${detail}` : ''}`);
+        throw commandFailure(executable, args, r, { sensitive, cwd, env: childEnv });
       }
       return { ok: true, code: r.status, stdout: r.stdout ?? '' };
     },
@@ -435,7 +442,8 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
       delete childEnv.OURS_INSTALLER_LOCK_FD;
       if (installationLockFd !== null) childEnv.OURS_INSTALLER_LOCK_FD = '3';
       const r = spawnSync(cmd, args, { stdio: ['inherit', 'inherit', 'inherit', ...(installationLockFd === null ? [] : [installationLockFd])], env: childEnv });
-      return { ok: !r.error && r.status === 0, code: r.status ?? -1 };
+      if (r.error || r.status !== 0) throw commandFailure(cmd, args, r, { env: childEnv });
+      return { ok: true, code: r.status };
     },
     installedVersion: (pkg) => installedVersionOf(pkg, npmBin),
     packageDependencies: (spec) => packageDependenciesOf(spec, npmBin),
@@ -534,6 +542,7 @@ export function networkEffects(effects) {
   const baseEnv = (record) => ({
     OURS_DAEMON_ID: record.instanceId,
     OURS_IMAGE: `${record.project}:runtime`,
+    OURS_GATEWAY_IMAGE: `${record.project}:gateway`,
     OURS_MAINTENANCE_IMAGE: `${record.project}:maintenance`,
     OURS_UID: String(record.uid ?? 1000), OURS_GID: String(record.gid ?? 1000),
     OURS_HOST_PORT: String(record.port ?? 3050),
@@ -545,14 +554,55 @@ export function networkEffects(effects) {
     'compose', '--project-directory', record.workDir, '--file', join(record.workDir,
       record.schema === 1 && existsSync(join(record.workDir, 'docker-compose.legacy.yaml'))
         ? 'docker-compose.legacy.yaml' : 'docker-compose.yaml'),
+    ...(record.gateway ? ['--file', join(record.workDir, 'docker-compose.gateway.yaml')] : []),
+    ...(engineName(record) === 'podman' ? ['--file', join(record.workDir, 'compose.podman.json')] : []),
     '--project-name', record.project, ...args,
   ];
-  const compose = (record, args, options = {}) => effects.run('docker', composeArgs(record, args),
-    { ...options, env: { ...baseEnv(record), ...options.env } });
+  const container = (record, args, options = {}) => runContainer(effects, record, args, options);
+  const compose = async (record, args, options = {}) => {
+    const selected = { ...options, env: { ...baseEnv(record), ...options.env } };
+    if (engineName(record) === 'podman' && args[0] === 'build') {
+      const result = await container(record, composeArgs(record, ['--profile', '*', 'config', '--format', 'json']), { env: selected.env });
+      for (const command of nativeBuildCommands(JSON.parse(result.stdout), args.slice(1), { ...env, ...selected.env })) await container(record, command, selected);
+      return { code: 0, stdout: '' };
+    }
+    if (engineName(record) === 'podman' && ['run', 'up'].includes(args[0])) {
+      const resolved = JSON.parse((await container(record, composeArgs(record, ['--profile', '*', 'config', '--format', 'json']), { env: selected.env })).stdout);
+      for (const [key, volume] of Object.entries(resolved.volumes ?? {})) {
+        if (volume.external) throw new Error('Unexpected external installation volume');
+        const name = volume.name ?? `${record.project}_${key}`;
+        const found = await container(record, ['volume', 'inspect', '--format', '{{json .}}', name], { allowCodes: [1] });
+        if (found.code === 1) continue;
+        const value = JSON.parse(found.stdout);
+        if (value.Name !== name || value.Labels?.['com.docker.compose.project'] !== record.project || value.Labels?.['com.docker.compose.volume'] !== key) throw new Error(`Refusing foreign volume: ${name}`);
+      }
+    }
+    // Compose run can implicitly build an absent administration image. Build
+    // its resolved target natively first, just like explicit build operations.
+    if (engineName(record) === 'podman' && args[0] === 'run') {
+      const resolved = JSON.parse((await container(record, composeArgs(record, ['--profile', '*', 'config', '--format', 'json']), { env: selected.env })).stdout);
+      const takesValue = new Set(['--name', '--entrypoint', '--env', '-e', '--user', '-u', '--workdir', '-w', '--volume', '-v', '--publish', '-p', '--label', '-l', '--pull']);
+      let name;
+      for (let i = 1; i < args.length; i++) {
+        if (takesValue.has(args[i])) { i++; continue; }
+        if (args[i].startsWith('-')) continue;
+        name = args[i]; break;
+      }
+      const service = resolved.services?.[name];
+      if (!service) throw new Error(`Unresolved Podman administration service: ${name}`);
+      if (service.build) {
+        const image = await container(record, ['image', 'inspect', service.image], { allowCodes: [1] });
+        if (image.code === 1) for (const command of nativeBuildCommands(resolved, [name], { ...env, ...selected.env })) await container(record, command, selected);
+      }
+    }
+    return container(record, composeArgs(record, args), selected);
+  };
   const dockerStartupError = async (record, service, cause) => {
     const args = ['logs', '--no-color', '--tail', '50', '--timestamps', service];
     const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
-    const command = `OURS_DAEMON_ID=${quote(record.instanceId)} docker ${composeArgs(record, args).map(quote).join(' ')}`;
+    const engine = engineName(record);
+    const prefix = engine === 'podman' ? ['--remote', '--url', `unix://${record.containerBinding.socket}`] : [];
+    const command = `OURS_DAEMON_ID=${quote(record.instanceId)} ${engine} ${[...prefix, ...composeArgs(record, args)].map(quote).join(' ')}`;
     let detail;
     try {
       const logs = await compose(record, args);
@@ -563,7 +613,7 @@ export function networkEffects(effects) {
     } catch {
       detail = 'Container logs could not be read.';
     }
-    return new Error(`Docker service "${service}" failed to start or become healthy.\n${detail}\nStartup error: ${cause.message}\nInspect logs: ${command}`, { cause });
+    return new Error(`${engine === 'podman' ? 'Podman' : 'Docker'} service "${service}" failed to start or become healthy.\n${detail}\nStartup error: ${cause.message}\nInspect logs: ${command}`, { cause });
   };
   const bin = (record, name) => join(record.workDir, 'node_modules', '.bin', name);
   const localEnv = (record, service = 'daemon') => {
@@ -577,14 +627,15 @@ export function networkEffects(effects) {
     return { ...common, OURS_MESSENGER_STATE_DIR: state, ...(record.messengerIdentity ? { OURS_MESSENGER_IDENTITY: record.messengerIdentity } : {}), OURS_MESSENGER_PORT: String(record.messengerPort), OURS_MESSENGER_HOST: '127.0.0.1', OURS_MESSENGER_PUBLIC_ORIGIN: `http://127.0.0.1:${record.messengerPort}` };
   };
   const ownerCommand = (record, service, op, options = {}) => {
-    const name = { daemon: 'ours', telegram: 'ours-tg-connector', cowork: 'ours-cowork' }[service];
-    const args = service === 'daemon' ? ['daemon', op, ...(['install-service', 'uninstall-service'].includes(op) ? ['--yes'] : []), '--config', record.configPath, '--state-dir', installationPaths(record).daemon, '--json'] : [op];
+    const daemonBinary = existsSync(bin(record, 'ours-daemon')) ? 'ours-daemon' : 'ours';
+    const name = { daemon: daemonBinary, telegram: 'ours-tg-connector', cowork: 'ours-cowork' }[service];
+    const args = service === 'daemon' ? [...(daemonBinary === 'ours' ? ['daemon'] : []), op, ...(['install-service', 'uninstall-service'].includes(op) ? ['--yes'] : []), '--config', record.configPath, '--state-dir', installationPaths(record).daemon, '--json'] : [op];
     return effects.run(bin(record, name), args, { ...options, env: localEnv(record, service) });
   };
   const requireCleanContainerExit = async (record, selected) => {
     const containers = await compose(record, ['ps', '-aq', ...selected]);
     for (const id of containers.stdout.split(/\s+/).filter(Boolean)) {
-      const result = await effects.run('docker', ['inspect', '--format', '{{json .State}}', id]);
+      const result = await container(record, ['inspect', '--format', '{{json .State}}', id]);
       const state = JSON.parse(result.stdout);
       if (state.Status !== 'exited' || state.ExitCode !== 0 || state.OOMKilled !== false || state.Dead !== false) {
         throw new Error('Selected source container did not stop cleanly; state operation refused');
@@ -618,7 +669,7 @@ export function networkEffects(effects) {
         return version;
       });
     },
-    newInstallation(root, mode) {
+    newInstallation(root, mode, { containerEngine } = {}) {
       if (existsSync(root)) {
         privateDirectory(root);
         if (readdirSync(root).some(name => name !== '.operation.lock')) throw new Error('Installation root is not empty and has no selection record');
@@ -626,9 +677,10 @@ export function networkEffects(effects) {
       const instanceId = env.OURS_DAEMON_ID || randomUUID();
       if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(instanceId)) throw new Error('OURS_DAEMON_ID must be a lowercase UUID');
       const project = `ours-${createHash('sha256').update(root).digest('hex').slice(0, 16)}`;
-      return { schema: 2, root, mode, instanceId, project, workDir: join(root, 'runtime'), configPath: installationPaths({ schema: 2, root }).config, sourcesPath: join(root, 'sources.json'), services: [...SERVER_SERVICES], port: 3050, coworkPort: 3052, messengerPort: 8420, messengerIdentity: env.OURS_MESSENGER_IDENTITY || null, uid: 1000, gid: 1000 };
+      return { schema: 2, root, mode, ...(containerEngine ? { containerEngine } : {}), instanceId, project, workDir: join(root, 'runtime'), configPath: installationPaths({ schema: 2, root }).config, sourcesPath: join(root, 'sources.json'), services: [...SERVER_SERVICES, ...(mode === 'docker' ? ['gateway'] : [])], ...(mode === 'docker' ? { gateway: { version: 1 } } : {}), port: 3050, coworkPort: 3052, messengerPort: 8420, messengerIdentity: env.OURS_MESSENGER_IDENTITY || null, uid: 1000, gid: 1000 };
     },
-    async serverPreflight(record, operation, { existing, sourcePath = record.sourcesPath, sourceManifest, identityName } = {}) {
+    async serverPreflight(record, operation, { existing, sourcePath = record.sourcesPath, sourceManifest, identityName, explicitPorts } = {}) {
+      if (!existing && operation === 'install' && Number.isInteger(record.port)) selectServerPorts(record, portTakenSync, explicitPorts, effects.out);
       if (existing) {
         privateDirectory(record.root);
         assertPrivateRegularFile(join(record.root, 'installation.json'), 'selection');
@@ -636,37 +688,55 @@ export function networkEffects(effects) {
         if (env.OURS_DAEMON_ID && env.OURS_DAEMON_ID !== record.instanceId) throw new Error('Conflicting instance ID');
       }
       if (record.mode === 'docker') {
-        const nativeRoot = existing ? '/path/to/new-empty-directory' : record.root;
-        const quotedRoot = `'${String(nativeRoot).replaceAll("'", "'\\''")}'`;
-        const quotedName = `'${String(identityName ?? record.messengerIdentity ?? 'Your Name').replaceAll("'", "'\\''")}'`;
-        const recovery = [
-          'Please install Docker Desktop on macOS/Windows, or Docker Engine with the Compose plugin on Linux, and start Docker before retrying.',
-          'Docker is recommended for macOS and Windows.',
-          `Alternatively, use native installation: ours-install server install --mode packages --state-dir ${quotedRoot} --identity-name ${quotedName}`,
-          'Native mode requires systemd user services on Linux/WSL or a launchd GUI session on macOS.',
-          ...(existing ? ['Keep this existing Docker installation in Docker mode; use a separate empty directory for a new native installation.'] : []),
-        ].join('\n');
-        try {
-          await effects.run('docker', ['info', '--format', '{{.ServerVersion}}']);
-        } catch (cause) {
-          const problem = cause.code === 'ENOENT'
-            ? 'Docker command was not found in PATH.'
-            : `Docker Engine is not reachable. Start Docker and check that your user can access it.\nDetails: ${cause.message}`;
-          throw new Error(`${problem}\n${recovery}`, { cause });
-        }
-        let version;
-        try {
-          version = await effects.run('docker', ['compose', 'version', '--short']);
-        } catch (cause) {
-          throw new Error(`Docker Compose 2.35 or newer is required, but the Compose plugin could not run. Update Docker Desktop or install the Docker Compose plugin.\n${recovery}`, { cause });
-        }
-        const match = /^v?(\d+)\.(\d+)/.exec(version.stdout.trim());
-        if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 35)) {
-          throw new Error(`Docker Compose 2.35 or newer is required. Update Docker Desktop or the Docker Compose plugin.\n${recovery}`);
+        if (engineName(record) === 'podman') {
+          await bindPodman(effects, record);
+          if (['install', 'start', 'restart', 'update', 'rebuild', 'gateway-enable'].includes(operation)) {
+            const userHome = userInfo().homedir;
+            for (const [key, expected] of Object.entries({ HOME: userHome, XDG_CONFIG_HOME: join(userHome, '.config'), XDG_DATA_HOME: join(userHome, '.local/share'), XDG_RUNTIME_DIR: `/run/user/${process.getuid()}` })) {
+              if (env[key] && env[key] !== expected) throw new Error(`${key} selects a custom Podman environment that the standard boot service does not retain`);
+            }
+            if (record.containerBinding.socket !== `/run/user/${process.getuid()}/podman/podman.sock`) throw new Error('The standard user boot service requires the default local Podman socket');
+            await effects.run('systemctl', ['--user', 'is-enabled', 'podman.socket']);
+            await effects.run('systemctl', ['--user', 'is-enabled', 'podman-restart.service']);
+            const restart = await effects.run('systemctl', ['--user', 'show', 'podman-restart.service', '--property=ExecStart', '--value']);
+            if (!/--filter[ =]+should-start-on-boot=true(?:[ ;}]|$)/.test(restart.stdout)) throw new Error('Installed podman-restart.service cannot recover unless-stopped workloads; use a Podman release with should-start-on-boot support');
+            const linger = await effects.run('loginctl', ['show-user', String(process.getuid()), '--property=Linger', '--value']);
+            if (linger.stdout.trim() !== 'yes') throw new Error('Rootless server requires user linger for logout/reboot recovery; ask your administrator to enable it');
+            await qualifyPodman(effects, record);
+          }
+        } else {
+          const nativeRoot = existing ? '/path/to/new-empty-directory' : record.root;
+          const quotedRoot = `'${String(nativeRoot).replaceAll("'", "'\\''")}'`;
+          const quotedName = `'${String(identityName ?? record.messengerIdentity ?? 'Your Name').replaceAll("'", "'\\''")}'`;
+          const recovery = [
+            'Please install Docker Desktop on macOS/Windows, or Docker Engine with the Compose plugin on Linux, and start Docker before retrying.',
+            'Docker is recommended for macOS and Windows.',
+            `Alternatively, use native installation: ours-install server install --mode packages --state-dir ${quotedRoot} --identity-name ${quotedName}`,
+            'Native mode requires systemd user services on Linux/WSL or a launchd GUI session on macOS.',
+            ...(existing ? ['Keep this existing Docker installation in Docker mode; use a separate empty directory for a new native installation.'] : []),
+          ].join('\n');
+          try {
+            await container(record, ['info', '--format', '{{.ServerVersion}}']);
+          } catch (cause) {
+            const problem = cause.code === 'ENOENT'
+              ? 'Docker command was not found in PATH.'
+              : `Docker Engine is not reachable. Start Docker and check that your user can access it.\nDetails: ${cause.message}`;
+            throw new Error(`${problem}\n${recovery}`, { cause });
+          }
+          let version;
+          try {
+            version = await container(record, ['compose', 'version', '--short']);
+          } catch (cause) {
+            throw new Error(`Docker Compose 2.35 or newer is required, but the Compose plugin could not run. Update Docker Desktop or install the Docker Compose plugin.\n${recovery}`, { cause });
+          }
+          const match = /^v?(\d+)\.(\d+)/.exec(version.stdout.trim());
+          if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 35)) {
+            throw new Error(`Docker Compose 2.35 or newer is required. Update Docker Desktop or the Docker Compose plugin.\n${recovery}`);
+          }
         }
         if (operation !== 'status') {
           // Compose clients can disappear while their Engine-owned command continues.
-          const active = await effects.run('docker', ['ps', '--filter', `label=com.docker.compose.project=${record.project}`, '--filter', 'label=com.docker.compose.oneoff=True', '--format', '{{.ID}}']);
+          const active = await container(record, ['ps', '--filter', `label=com.docker.compose.project=${record.project}`, '--filter', 'label=com.docker.compose.oneoff=True', '--format', '{{.ID}}']);
           if (active.stdout.trim()) throw new Error('Another server installation operation is still running in Docker');
         }
       } else {
@@ -704,6 +774,55 @@ export function networkEffects(effects) {
       else if (!readFileSync(record.sourcesPath).equals(bytes)) throw new Error('Migration source selection changed');
       if (!retainConfig) writePrivateNew(record.configPath, JSON.stringify({ stateDir: record.mode === 'docker' ? '/var/lib/ours' : installationPaths(record).daemon, port: record.port, apiVisibility: 'owner' }, null, 2) + '\n');
     },
+    async qualifyDockerRuntime(record) { return qualifyDockerRuntime(record, effects); },
+    async prepareGateway(record) {
+      atomicWriteConfig(join(record.workDir, 'docker-compose.gateway.yaml'), gatewayCompose(record));
+      atomicWriteConfig(join(record.workDir, 'nginx.conf'), gatewayNginx(record));
+      atomicWriteConfig(join(record.workDir, 'gateway-entrypoint.sh'), readFileSync(join(INSTALLER_ASSETS, 'gateway-entrypoint.sh'), 'utf8'));
+      atomicWriteConfig(join(record.workDir, 'Dockerfile.gateway'), readFileSync(join(INSTALLER_ASSETS, 'Dockerfile.gateway'), 'utf8'));
+      await compose(record, ['build', 'gateway'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
+    },
+    async removeGatewayContainer(record) { await compose(record, ['rm', '-f', 'gateway']); },
+    async verifyGateway(record) {
+      const { prefix } = gatewayAddress(record);
+      const script = `const fs=require('node:fs');let stage='selection';(async()=>{
+        const base=${JSON.stringify('http://gateway:8080' + prefix)};
+        const get=async(path,options={})=>{const r=await fetch(base+path,{...options,redirect:'error',signal:AbortSignal.timeout(5000)});if(!r.ok)throw Error('Gateway readiness HTTP '+r.status);return r.json();};
+        const selection=await get('/daemon/selection');
+        if(selection.instanceId!==${JSON.stringify(record.instanceId)})throw Error('Gateway daemon instance mismatch');
+        stage='unauthenticated-management';
+        const denied=await fetch(base+'/cowork/management/rpc',{method:'POST',redirect:'error',signal:AbortSignal.timeout(5000),headers:{'content-type':'application/json'},body:'{}'});
+        await denied.body?.cancel();if(denied.status!==401)throw Error('Gateway management does not reject unauthenticated requests');
+        stage='credential';
+        const token=fs.readFileSync('/var/lib/ours/daemon-token','utf8').trim();
+        const headers={'x-ours-api-token':token,'content-type':'application/json'};
+        stage='authenticated-daemon';
+        const identities=await get('/daemon/identities',{headers});
+        if(!Array.isArray(identities.identities))throw Error('Gateway daemon API invalid');
+        stage='authenticated-management';
+        const result=await get('/cowork/management/rpc',{method:'POST',headers,body:JSON.stringify({version:1,id:'installer-readiness',method:'room.list',params:{}})});
+        if(result.version!==1||result.id!=='installer-readiness'||!Array.isArray(result.result)||result.error)throw Error('Gateway Cowork management unavailable');
+      })().catch(error=>{const code=error.cause?.code;process.stdout.write('gateway-readiness:'+stage+':'+(['EAI_AGAIN','ENOTFOUND','ECONNREFUSED','ETIMEDOUT'].includes(code)?code:'CHECK_FAILED'));process.exitCode=1;});`;
+      const result = await compose(record, ['exec', '-T', 'daemon', 'node', '-e', script], { sensitive: true, allowCodes: [1] });
+      if (result.code === 1) {
+        const match = /^gateway-readiness:(selection|unauthenticated-management|credential|authenticated-daemon|authenticated-management):(EAI_AGAIN|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|CHECK_FAILED)$/.exec(result.stdout.trim());
+        const detail = match ? ` (${match[1]}, ${match[2]})` : '';
+        throw new Error(`Gateway readiness failed${detail}. Keep installation state intact; check the managed gateway startup and network connection, then retry setup.`);
+      }
+    },
+    async qualifyGatewayRuntime(record) {
+      for (const [name, args, capability] of [
+        ['cowork', ['--json', 'capabilities'], 'cowork.http-management-v1'],
+        ['messenger-server', ['capabilities'], 'messenger.gateway-prefix-v1'],
+        ['tg-connector', ['capabilities'], 'telegram.gateway-listener-v1'],
+      ]) {
+        const probe = await container(record, ['run', '--rm', '--network', 'none', '--read-only', '--entrypoint', 'node', `${record.project}:runtime`, `/opt/ours/node_modules/@ours.network/${name}/dist/cli.js`, ...args]);
+        let value; try { value = JSON.parse(probe.stdout); } catch {}
+        const capabilities = value?.result?.capabilities ?? value?.capabilities;
+        if (!Array.isArray(capabilities) || !capabilities.includes(capability))
+          throw new Error(`Selected ${name} artifact lacks ${capability}; select a compatible release before enabling the gateway`);
+      }
+    },
     async prepareInstallation(record, { runtimeOnly = false } = {}) {
       let copied = false;
       if (!existsSync(record.workDir)) {
@@ -717,13 +836,26 @@ export function networkEffects(effects) {
       if (!existsSync(materialized)) writePrivateNew(materialized, retained);
       else if (!readFileSync(materialized).equals(retained)) throw new Error('Materialized sources differ from retained selection');
       if (record.mode === 'docker') {
+        if (engineName(record) === 'podman') atomicWriteConfig(join(record.workDir, 'compose.podman.json'), JSON.stringify({ services: Object.fromEntries(record.services.map(name => [name, { restart: 'unless-stopped' }])) }));
+        const rebuildPrivateScripts = refreshDockerPolicyCopy(record);
+        if (record.gateway) {
+          atomicWriteConfig(join(record.workDir, 'docker-compose.gateway.yaml'), gatewayCompose(record));
+          atomicWriteConfig(join(record.workDir, 'nginx.conf'), gatewayNginx(record));
+          for (const file of ['Dockerfile.gateway', 'gateway-entrypoint.sh']) atomicWriteConfig(join(record.workDir, file), readFileSync(join(INSTALLER_ASSETS, file), 'utf8'));
+        }
         // The installer owns these dependencies in both installation modes.
         const { dependencies } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
         writeFileSync(join(record.workDir, 'scripts/maintenance/package.json'), JSON.stringify({ private: true, type: 'module', dependencies }, null, 2) + '\n', { mode: 0o600 });
-        const image = await effects.run('docker', ['image', 'inspect', `${record.project}:runtime`], { allowCodes: [1] });
-        if (image.code !== 0) await compose(record, ['build', 'daemon'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
+        const image = await container(record, ['image', 'inspect', `${record.project}:runtime`], { allowCodes: [1] });
+        if (image.code !== 0 || rebuildPrivateScripts) await compose(record, ['build', 'daemon'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
+        await effects.qualifyDockerRuntime(record);
+        if (rebuildPrivateScripts) rmSync(join(record.workDir, '.script-permissions-rebuild'));
+        if (record.gateway) {
+          await effects.qualifyGatewayRuntime(record);
+          await compose(record, ['build', 'gateway'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
+        }
         if (runtimeOnly) return;
-        await compose(record, ['run', '--rm', '--no-deps', '-T', 'prepare', 'prepare']);
+        await effects.prepareServerVolumes(record);
       } else {
         if (!existsSync(join(record.workDir, '.packages-ready'))) {
           const sourceRoot = join(record.root, `build-${randomUUID()}`);
@@ -744,12 +876,15 @@ export function networkEffects(effects) {
         const profilePath = join(installationPaths(record).mcp, 'profile.json');
         if (!existsSync(profilePath)) writePrivateNew(profilePath, JSON.stringify({ endpoint: `http://127.0.0.1:${record.port}`, expectedInstanceId: record.instanceId, credentialPath: join(installationPaths(record).daemon, 'daemon-token') }));
         const config = JSON.parse(readFileSync(record.configPath, 'utf8'));
-        config.networkMcp ??= { profile: { endpoint: `http://127.0.0.1:${record.port}`, expectedInstanceId: record.instanceId, credentialPath: join(installationPaths(record).daemon, 'daemon-token') }, applicationConfigPath: join(installationPaths(record).mcp, 'config.json') };
         effects.writeJson(record.configPath, JSON.stringify(config, null, 2) + '\n');
         const cowork = join(installationPaths(record).cowork, 'config.json');
         if (!existsSync(cowork)) writePrivateNew(cowork, JSON.stringify({ version: 1, stateDir: installationPaths(record).cowork, rest: { enabled: true, host: '127.0.0.1', port: record.coworkPort } }));
       }
     },
+    async prepareServerVolumes(record) {
+      if (record.mode !== 'docker') return;
+      await compose(record, ['run', '--rm', '--no-deps', '-T', 'prepare', 'prepare']);
+    },
     async prepareServerBuild(record, args) {
       validateInstallation(record, record.root);
       if (record.schema !== 2 || record.layoutConversion || !['update', 'rebuild'].includes(args.operation)) {
@@ -792,17 +927,17 @@ export function networkEffects(effects) {
     },
     async copyDockerBuildRecords(record, directory) {
       // Inspect immutable image metadata; never reinterpret a failed context copy as legacy.
-      const label = (await effects.run('docker', ['image', 'inspect', '--format', '{{ index .Config.Labels "network.ours.build-context" }}', `${record.project}:runtime`])).stdout.trim();
+      const label = (await container(record, ['image', 'inspect', '--format', '{{ index .Config.Labels "network.ours.build-context" }}', `${record.project}:runtime`])).stdout.trim();
       if (!['', '<no value>', '1'].includes(label)) throw new Error('Unsupported image build-context schema');
       const names = [...BASE_RECORDS, ...(label === '1' ? [CONTEXT] : [])];
       const stage = mkdtempSync(join(directory, '.records-'));
       const name = `${record.project}-records`;
       let created = false;
       try {
-        await effects.run('docker', ['create', '--name', name, '--entrypoint', '/bin/true', `${record.project}:runtime`]);
+        await container(record, ['create', '--name', name, '--entrypoint', '/bin/true', `${record.project}:runtime`]);
         created = true;
         for (const file of names) {
-          await effects.run('docker', ['cp', `${name}:/opt/ours/${file}`, join(stage, file)]);
+          await container(record, ['cp', `${name}:/opt/ours/${file}`, join(stage, file)]);
           const st = lstatSync(join(stage, file));
           if (!st.isFile() || st.uid !== process.getuid() || (st.mode & 0o7002)) throw new Error('Unsafe copied build record');
           chmodSync(join(stage, file), 0o600);
@@ -812,7 +947,7 @@ export function networkEffects(effects) {
         for (const file of names) renameSync(join(stage, file), join(directory, file));
         if (label !== '1' && existsSync(join(directory, CONTEXT))) throw new Error('Legacy image conflicts with retained build context');
       } finally {
-        try { if (created) await effects.run('docker', ['rm', name]); }
+        try { if (created) await container(record, ['rm', name]); }
         finally { rmSync(stage, { recursive: true, force: true }); }
       }
     },
@@ -863,12 +998,12 @@ export function networkEffects(effects) {
     async publishServerBuild(record, candidate) {
       const previous = join(candidate.root, 'previous-runtime');
       if (record.mode === 'docker') {
-        for (const target of ['runtime', 'maintenance']) {
+        for (const target of ['runtime', 'maintenance', ...(record.gateway ? ['gateway'] : [])]) {
           const retained = `${candidate.project}:previous-${target}`;
-          const found = await effects.run('docker', ['image', 'inspect', retained], { allowCodes: [1] });
+          const found = await container(record, ['image', 'inspect', retained], { allowCodes: [1] });
           if (found.code !== 0) {
-            const current = await effects.run('docker', ['image', 'inspect', `${record.project}:${target}`], { allowCodes: [1] });
-            if (current.code === 0) await effects.run('docker', ['tag', `${record.project}:${target}`, retained]);
+            const current = await container(record, ['image', 'inspect', `${record.project}:${target}`], { allowCodes: [1] });
+            if (current.code === 0) await container(record, ['tag', `${record.project}:${target}`, retained]);
           }
         }
       }
@@ -884,8 +1019,8 @@ export function networkEffects(effects) {
         renameSync(candidate.workDir, record.workDir);
       } else privateDirectory(record.workDir);
       if (record.mode === 'docker') {
-        for (const target of ['runtime', 'maintenance']) {
-          await effects.run('docker', ['tag', `${candidate.project}:${target}`, `${record.project}:${target}`]);
+        for (const target of ['runtime', 'maintenance', ...(record.gateway ? ['gateway'] : [])]) {
+          await container(candidate, ['tag', `${candidate.project}:${target}`, `${record.project}:${target}`]);
         }
       }
       atomicWriteConfig(record.sourcesPath, readFileSync(candidate.sourcesPath));
@@ -899,10 +1034,10 @@ export function networkEffects(effects) {
     },
     async discardServerBuild(candidate) {
       if (candidate.mode === 'docker') {
-        for (const target of ['runtime', 'maintenance', 'previous-runtime', 'previous-maintenance']) {
+        for (const target of ['runtime', 'maintenance', 'previous-runtime', 'previous-maintenance', ...(candidate.gateway ? ['gateway', 'previous-gateway'] : [])]) {
           const image = `${candidate.project}:${target}`;
-          const found = await effects.run('docker', ['image', 'inspect', image], { allowCodes: [1] });
-          if (found.code === 0) await effects.run('docker', ['image', 'rm', image]);
+          const found = await container(candidate, ['image', 'inspect', image], { allowCodes: [1] });
+          if (found.code === 0) await container(candidate, ['image', 'rm', image]);
         }
       }
       privateDirectory(candidate.root);
@@ -910,7 +1045,15 @@ export function networkEffects(effects) {
     },
     async serverAccess(record, operation, { output, migrate = false } = {}) {
       if (record.mode === 'docker') {
-        if (!output) return compose(record, ['run', '--rm', '--no-deps', '-T', 'access', operation], { sensitive: true, env: { OURS_ACCESS_MIGRATE: migrate ? '1' : '0' } });
+        // Retained images contain the old helper that discarded CLI errors.
+        // Execute the shipped installer helper against the SAME selected image
+        // and Compose volume/user/environment contract, without retag/rebuild.
+        const diagnosticsUrl = `data:text/javascript;base64,${readFileSync(join(INSTALLER_ASSETS, 'scripts/runtime/diagnostics.mjs')).toString('base64')}`;
+        const helper = `process.argv.splice(1, 0, '/opt/ours/docker/client-setup.mjs');\n` + readFileSync(join(INSTALLER_ASSETS, 'scripts/runtime/client-setup.mjs'), 'utf8')
+          .replace("'../maintenance/build-context.mjs'", "'/opt/ours/maintenance/build-context.mjs'")
+          .replace("'./diagnostics.mjs'", JSON.stringify(diagnosticsUrl));
+        const accessArgs = (...args) => ['--entrypoint', 'node', 'access', '--input-type=module', '-e', helper, '--', ...args];
+        if (!output) return compose(record, ['run', '--rm', '--no-deps', '-T', ...accessArgs(operation)], { sensitive: true, env: { OURS_ACCESS_MIGRATE: migrate ? '1' : '0' } });
         privateDirectory(dirname(output));
         if (existsSync(output)) throw new Error('Credential output already exists');
         const name = `${record.project}-issue-${randomUUID()}`;
@@ -918,23 +1061,23 @@ export function networkEffects(effects) {
         const staging = join(dirname(output), `.ours-issued-${randomUUID()}`);
         ensurePrivateDirectory(staging);
         try {
-          await compose(record, ['run', '--name', name, '--no-deps', '-T', 'access', 'access-issue', issuedPath], { sensitive: true });
+          await compose(record, ['run', '--name', name, '--no-deps', '-T', ...accessArgs('access-issue', issuedPath)], { sensitive: true });
           const file = join(staging, 'credential');
-          await effects.run('docker', ['cp', `${name}:${issuedPath}`, file], { sensitive: true });
+          await container(record, ['cp', `${name}:${issuedPath}`, file], { sensitive: true });
           assertPrivateRegularFile(file, 'issued credential');
           // Exclusive publication never overwrites an unrelated credential.
           writePrivateNew(output, readFileSync(file));
         } finally {
           await compose(record, ['run', '--rm', '--no-deps', '-T', '--entrypoint', 'rm', 'access', '-f', issuedPath], { sensitive: true });
-          await effects.run('docker', ['rm', '-f', name], { sensitive: true });
+          await container(record, ['rm', '-f', name], { sensitive: true });
           rmSync(staging, { recursive: true, force: true });
         }
         return;
       }
       const options = { env: localEnv(record), sensitive: true };
-      if (operation !== 'access-issue') return effects.run(bin(record, 'ours'), ['config', operation, '--config', record.configPath, ...(operation === 'access-replace' ? ['--confirm'] : migrate ? ['--migrate'] : []), '--json'], options);
+      if (operation !== 'access-issue') return effects.run(bin(record, existsSync(bin(record, 'ours-daemon')) ? 'ours-daemon' : 'ours'), ['config', operation, '--config', record.configPath, ...(operation === 'access-replace' ? ['--confirm'] : migrate ? ['--migrate'] : []), '--json'], options);
       const outputs = output ? [output] : [join(installationPaths(record).daemon, 'daemon-token'), ...['telegram', 'cowork', 'messenger'].map(s => installationPaths(record).credentials[s])];
-      for (const path of outputs) await effects.run(bin(record, 'ours'), ['config', operation, '--config', record.configPath, '--output', path, ...(output ? [] : ['--replace']), '--json'], options);
+      for (const path of outputs) await effects.run(bin(record, existsSync(bin(record, 'ours-daemon')) ? 'ours-daemon' : 'ours'), ['config', operation, '--config', record.configPath, '--output', path, ...(output ? [] : ['--replace']), '--json'], options);
     },
     async recordRuntimeBuild(record) {
       if (record.mode === 'docker') return; // Image preparation records its build.
@@ -978,7 +1121,7 @@ export function networkEffects(effects) {
         await effects.run(process.execPath, [join(INSTALLER_ASSETS, 'scripts/maintenance/state-operation.mjs'), ...command], {
           env: { ...localEnv(record), OURS_STATE_DOMAIN: args.domain,
             OURS_STATE_ROOT: join(record.root, 'storage'), OURS_LIVE_ROOT: ['server', 'daemon'].includes(args.domain) ? paths.state : paths[args.domain],
-            OURS_BUILD_ROOT: record.workDir, OURS_CLI_PATH: bin(record, 'ours'),
+            OURS_BUILD_ROOT: record.workDir, OURS_CLI_PATH: bin(record, existsSync(bin(record, 'ours-daemon')) ? 'ours-daemon' : 'ours'),
             OURS_DAEMON_CONFIG: record.configPath, OURS_COWORK_CLI_PATH: bin(record, 'ours-cowork'),
             OURS_COWORK_CONFIG: join(paths.cowork, 'config.json'), OURS_COWORK_STATE_DIR: paths.cowork },
         });
@@ -996,12 +1139,12 @@ export function networkEffects(effects) {
         if (typeof name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name)) {
           throw new Error('Invalid conversion volume name');
         }
-        const result = await effects.run('docker', ['volume', 'inspect', '--format', '{{json .}}', name], {
+        const result = await container(record, ['volume', 'inspect', '--format', '{{json .}}', name], {
           ...(optional ? { allowCodes: [1] } : {}),
         });
         if (result.code !== 0) {
           if (optional) {
-            const inventory = await effects.run('docker', ['volume', 'ls', '--format', '{{.Name}}']);
+            const inventory = await container(record, ['volume', 'ls', '--format', '{{.Name}}']);
             if (inventory.code === 0 && !inventory.stdout.split(/\s+/).includes(name)) return false;
           }
           throw new Error(`Source volume is missing or unavailable: ${name}`);
@@ -1063,7 +1206,7 @@ export function networkEffects(effects) {
       await ownerCommand(record, 'cowork', 'prepare-backup');
     },
     async retainConvertedPackageAuthority(record, daemon) {
-      await effects.run(bin(record, 'ours'), [
+      await effects.run(bin(record, existsSync(bin(record, 'ours-daemon')) ? 'ours-daemon' : 'ours'), [
         'config', 'access-retain', '--config', record.configPath,
         '--target-state-dir', daemon, '--json',
       ], { env: localEnv(record), sensitive: true });
@@ -1125,7 +1268,9 @@ export function networkEffects(effects) {
         }
         const start = async service => {
           effects.out(`Starting ${service}; waiting for readiness...`);
-          try { await compose(record, ['up', '-d', '--no-build', '--no-deps', '--wait', service]); }
+          // Gateway has no persistent state. Recreate its network endpoint on each
+          // managed start, including retries after an interrupted/failed bind.
+          try { await compose(record, ['up', '-d', '--no-build', '--no-deps', ...(service === 'gateway' ? ['--force-recreate'] : []), '--wait', service]); }
           catch (cause) { throw await dockerStartupError(record, service, cause); }
           effects.out(`${service} is ready.`);
         };
@@ -1135,6 +1280,7 @@ export function networkEffects(effects) {
           try { await start(service); }
           catch (error) { failures.push({ service, error }); }
         }
+        if (!failures.length && record.gateway && ['daemon', 'cowork', 'gateway'].every(service => selected.includes(service))) await effects.verifyGateway(record);
         if (failures.length) throw new Error(`Application readiness failed: ${failures.map(f => f.service).join(', ')}. Check the selected application prerequisites.\n${failures.map(f => f.error.message).join('\n\n')}`);
         return;
       }
@@ -1149,21 +1295,19 @@ export function networkEffects(effects) {
       return JSON.parse(readFileSync(path, 'utf8'));
     },
     async discoverClientProfile(endpoint, credentialPath) {
-      const url = new URL(endpoint);
-      if (url.protocol !== 'http:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
-        throw new Error('Client endpoint must be an HTTP origin');
-      const response = await fetch(`${url.origin}/selection`, { redirect: 'error', signal: AbortSignal.timeout(5000) });
-      if (!response.ok) throw new Error(`Daemon selection answered HTTP ${response.status}`);
-      const selection = await response.json();
-      // Full metadata and authenticated capability validation follows before publication.
-      return validateHostProfile({ endpoint: url.origin, expectedInstanceId: selection.instanceId, credentialPath: resolve(credentialPath) });
+      const base = serverBase(endpoint);
+      const request = path => fetch(`${base}${path}`, { redirect: 'error', signal: AbortSignal.timeout(5000) });
+      const discovery = await request('/.well-known/ours');
+      if (discovery.ok) return validateGatewayDiscovery(base, await discovery.json(), resolve(credentialPath));
+      throw new Error(`Gateway discovery answered HTTP ${discovery.status}; enable the gateway. Direct daemon fallback is not supported.`);
     },
-    importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath, refresh = false }) {
+    importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath, disableFleetAgentsSetup = false, refresh = false, notificationsProducerPath }) {
+      profile = validateGatewayClientProfile(profile);
       const root = join(home, '.ours-client');
       const configPath = join(root, 'profile.json');
       const credentialPath = join(root, 'credential');
       const current = effects.readManagedClientProfile();
-      if (current && (current.endpoint !== profile.endpoint || current.expectedInstanceId !== profile.expectedInstanceId))
+      if (current && current.expectedInstanceId !== profile.expectedInstanceId)
         throw new Error('Managed client already selects another server; existing default was not changed');
       assertPrivateRegularFile(profile.credentialPath, 'credential');
       const credential = readFileSync(profile.credentialPath, 'utf8');
@@ -1174,13 +1318,30 @@ export function networkEffects(effects) {
         : readFileSync(sourcesPath);
       const fleetSettings = (!current || refresh) && fleetSettingsPath ? readFileSync(fleetSettingsPath) : null;
       if (fleetSettings) JSON.parse(fleetSettings.toString());
+      let producer = null;
+      if (notificationsProducerPath) {
+        assertPrivateRegularFile(notificationsProducerPath, 'notification producer credential');
+        producer = readFileSync(notificationsProducerPath, 'utf8');
+        let bound; try { bound = JSON.parse(producer); } catch { bound = null; }
+        if (bound?.schema !== 1 || bound.serverUrl !== profile.serverUrl || bound.expectedInstanceId !== profile.expectedInstanceId || !/^[A-Za-z0-9_-]{32,256}$/.test(bound.token ?? ''))
+          throw new Error('Notification producer credential does not match the selected server');
+      }
       ensurePrivateDirectory(root);
+      // Written before the profile it belongs to is published or changed.
+      let notificationsProducerChanged = false;
+      if (producer !== null) {
+        const producerPath = join(root, 'notifications-producer.json');
+        if (!existsSync(producerPath) || readFileSync(producerPath, 'utf8') !== producer) { atomicWriteConfig(producerPath, producer); notificationsProducerChanged = true; }
+      }
       if (current && !refresh) {
         assertPrivateRegularFile(credentialPath, 'managed credential');
         if (readFileSync(credentialPath, 'utf8') !== credential) atomicWriteConfig(credentialPath, credential);
-        return { configPath, profile: validateHostProfile(current), settings: current.installer };
+        const saved = { ...current, ...profile, credentialPath };
+        if (current.endpoint !== saved.endpoint || current.serverUrl !== saved.serverUrl)
+          atomicWriteConfig(configPath, JSON.stringify(saved, null, 2) + '\n');
+        return { configPath, profile: validateGatewayClientProfile(saved), settings: current.installer, notificationsProducerChanged };
       }
-      const settings = { sourcesPath: join(root, 'sources.json'), integrations };
+      const settings = { sourcesPath: join(root, 'sources.json'), integrations, ...(disableFleetAgentsSetup ? { disableFleetAgentsSetup: true } : {}) };
       if (fleetSettings) settings.fleetSettingsPath = join(root, 'fleet-settings.json');
       // Publish the profile last: clients cannot select incomplete imported inputs.
       atomicWriteConfig(settings.sourcesPath, sources);
@@ -1188,20 +1349,41 @@ export function networkEffects(effects) {
       atomicWriteConfig(credentialPath, credential);
       const saved = { ...profile, credentialPath, installer: settings };
       atomicWriteConfig(configPath, JSON.stringify(saved, null, 2) + '\n');
-      return { configPath, profile: validateHostProfile(saved), settings };
+      return { configPath, profile: validateHostProfile(saved), settings, notificationsProducerChanged };
+    },
+    async qualifyInstalledGatewayClient(profile) {
+      if (!profile.installer?.integrations?.includes('fleet')) return;
+      let info;
+      try { info = JSON.parse((await effects.run('ours-fleet', ['version', '--json'])).stdout); } catch {}
+      if (!Array.isArray(info?.capabilities) || !info.capabilities.includes('cowork.http-management-v1'))
+        throw new Error('Installed Fleet does not support gateway HTTP management; upgrade Fleet before gateway-enable');
     },
-    async acquireClientPackages(configPath, sourcesPath, integrations, { refresh = false } = {}) {
+    async qualifyGatewayClient({ profile, sourcesPath, sources, integrations, refresh = false }) {
+      if (!profile.serverUrl || !integrations.includes('fleet')) return;
+      // Acquire into the retained package cache without publishing a profile,
+      // credential, native command, or integration. Normal acquisition rechecks it.
+      const staging = mkdtempSync(join(home, '.ours-gateway-client-'));
+      try {
+        const stagedSources = join(staging, 'sources.json');
+        writeFileSync(stagedSources, sources ? JSON.stringify(sources, null, 2) + '\n' : readFileSync(sourcesPath), { mode: 0o600 });
+        await effects.acquireClientPackages(join(home, '.ours-client/profile.json'), stagedSources, integrations,
+          { refresh, gatewayServerUrl: profile.serverUrl, qualifyOnly: true });
+      } finally { rmSync(staging, { recursive: true, force: true }); }
+    },
+    async acquireClientPackages(configPath, sourcesPath, integrations, { refresh = false, hostCliOnly = false, gatewayServerUrl, qualifyOnly = false } = {}) {
       const manifest = JSON.parse(readFileSync(sourcesPath, 'utf8'));
-      // Public SDK client APIs are actual integration dependencies; Fleet also owns CLI usage.
-      const selected = [...new Set(['sdk', ...(integrations.includes('fleet') ? ['cli'] : []), ...integrations])];
+      // Every client installation includes the native CLI and its SDK dependency.
+      const selected = clientPackageNames(integrations);
       const packages = selectSourcePackages(manifest, 'client', selected);
-      const selectionKey = refresh ? JSON.stringify([configPath, manifest, integrations]) : configPath;
+      const selectionKey = JSON.stringify([hostCliOnly ? 'host-cli-private-v1' : 'host-cli-v1', configPath, ...(hostCliOnly ? [manifest] : []), ...(refresh ? [manifest, integrations] : [])]);
       const root = join(home, '.ours-client-install', createHash('sha256').update(selectionKey).digest('hex').slice(0, 16));
       const hasGit = Object.values(packages).some(selection => selection.source);
       await effects.run('npm', ['--version']);
       if (hasGit) {
         for (const command of ['python3', 'git', 'make', 'cc']) await effects.run(command, ['--version']);
       }
+      // This directory retains active executables, not disposable download cache.
+      ensurePrivateDirectory(join(home, '.ours-client-install'));
       ensurePrivateDirectory(root);
       const retained = join(root, 'sources.json');
       const bytes = readFileSync(sourcesPath);
@@ -1226,13 +1408,33 @@ export function networkEffects(effects) {
         writePrivateNew(join(root, '.packages-ready'), 'ready\n');
       }
       verifyReleaseGraph(root, manifest, { requiredPackages: Object.keys(packages) });
+      if (integrations.includes('fleet') && (gatewayServerUrl || readHostProfileFile(configPath)?.serverUrl)) {
+        let info;
+        try { info = JSON.parse(readFileSync(join(root, 'node_modules/@ours.network/fleet/dist/build-info.json'), 'utf8')); } catch {}
+        if (!Array.isArray(info?.capabilities) || !info.capabilities.includes('cowork.http-management-v1'))
+          throw new Error('Selected Fleet artifact does not support gateway HTTP management; select a compatible client release');
+      }
+      if (qualifyOnly) return;
+      const cliPolicy = hostCliOnly ? null : hostCliPolicy(manifest);
       // Local acquisition alone does not publish native commands. Use the user's
       // configured npm prefix and retained dependency closure, including on retry.
       for (const name of integrations.filter(name => name === 'fleet' || name === 'codex')) {
         await effects.run('npm', ['install', '--global', '--install-links=false', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', join(root, 'node_modules', '@ours.network', name)]);
       }
+      let cliBin = join(root, 'node_modules/.bin/ours');
+      if (cliPolicy) {
+        const cliSources = join(root, 'host-cli-sources.json');
+        const cliBytes = JSON.stringify(cliPolicy, null, 2) + '\n';
+        if (!existsSync(cliSources)) writePrivateNew(cliSources, cliBytes);
+        else if (readFileSync(cliSources, 'utf8') !== cliBytes) throw new Error('Retained host CLI source selection differs');
+        const acquired = await effects.acquireClientPackages(configPath, cliSources, [], { refresh, hostCliOnly: true });
+        cliBin = acquired.cliBin;
+      } else {
+        // Publish last so optional integration installation cannot downgrade ours.
+        await publishClientCli(effects, join(root, 'node_modules', '@ours.network/cli'), { policy: manifest, isolated: hostCliOnly });
+      }
       const localPackages = Object.fromEntries(integrations.filter(n => n !== 'fleet').map(name => [name, join(root, 'node_modules', '@ours.network', name)]));
-      return { localPackages, packages: {}, fleetBin: integrations.includes('fleet') ? join(root, 'node_modules/.bin/ours-fleet') : null };
+      return { localPackages, packages: {}, cliBin, fleetBin: integrations.includes('fleet') ? join(root, 'node_modules/.bin/ours-fleet') : null };
     },
     async prepareClientMarketplace(name, packagePath) {
       const acquisitionRoot = dirname(dirname(dirname(packagePath)));
@@ -1241,7 +1443,7 @@ export function networkEffects(effects) {
       const release = releaseBinding(policy);
       const integrationsPath = join(acquisitionRoot, 'integrations.json');
       const integrations = existsSync(integrationsPath) ? JSON.parse(readFileSync(integrationsPath, 'utf8')) : null;
-      const requiredPackages = integrations ? [...new Set(['sdk', ...(integrations.includes('fleet') ? ['cli'] : []), ...integrations])].map(name => '@ours.network/' + name) : Object.keys(policy.packages ?? {});
+      const requiredPackages = integrations ? clientPackageNames(integrations).map(name => '@ours.network/' + name) : Object.keys(policy.packages ?? {});
       verifyReleaseGraph(acquisitionRoot, policy, { requiredPackages });
       const root = join(acquisitionRoot, 'marketplaces', name);
       const plugin = join(root, 'plugins', 'ours');
@@ -1250,7 +1452,7 @@ export function networkEffects(effects) {
         cpSync(packagePath, plugin, { recursive: true });
         const manifestPath = join(plugin, 'package.json');
         const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-        for (const dependency of release ? [] : ['sdk', 'cli']) {
+        for (const dependency of release ? [] : ['sdk', 'cli', 'mcp']) {
           const name = `@ours.network/${dependency}`;
           if (manifest.dependencies?.[name]) manifest.dependencies[name] = `file:${join(dirname(packagePath), dependency)}`;
         }
@@ -1270,42 +1472,7 @@ export function networkEffects(effects) {
       effects.writeJson(manifestPath, JSON.stringify(value, null, 2) + '\n');
       return root;
     },
-    async verifyPackagedMcp(configPath) {
-      const profile = typeof configPath === 'string' ? readHostProfileFile(configPath) : validateHostProfile(configPath);
-      assertPrivateRegularFile(profile.credentialPath, 'credential');
-      const token = readFileSync(profile.credentialPath, 'utf8').trim();
-      const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'x-ours-api-token': token, 'x-ours-session-mode': 'external', 'x-ours-lease-token': randomUUID() };
-      const request = async (method, params, id) => {
-        const response = await fetch(`${profile.endpoint}/mcp`, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(5000), headers, body: JSON.stringify({ jsonrpc: '2.0', ...(id === undefined ? {} : { id }), method, params }) });
-        const session = response.headers.get('mcp-session-id');
-        if (session) headers['mcp-session-id'] = session;
-        if (!response.ok) throw new Error(`Packaged MCP verification failed: HTTP ${response.status}`);
-        if (id === undefined) { await response.body?.cancel(); return; }
-        const text = await response.text();
-        const messages = response.headers.get('content-type')?.includes('text/event-stream')
-          ? text.split('\n').filter(line => line.startsWith('data:')).map(line => JSON.parse(line.slice(5)))
-          : [JSON.parse(text)];
-        const message = messages.find(value => value.id === id);
-        if (!message || message.error || !message.result) throw new Error('Packaged MCP returned no successful protocol result');
-        return message.result;
-      };
-      try {
-        const initialized = await request('initialize', { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'ours-install', version: '1' } }, 1);
-        if (initialized.serverInfo?.name !== 'ours' || !initialized.protocolVersion) throw new Error('Selected MCP is not the packaged OURS server');
-        headers['mcp-protocol-version'] = initialized.protocolVersion;
-        await request('notifications/initialized', {}, undefined);
-        const resources = await request('resources/list', {}, 2);
-        if (!resources.resources?.some(resource => resource.uri === 'ours://application-identities')) throw new Error('Packaged network MCP identity resource is absent');
-        const toolList = await request('tools/list', {}, 3);
-        if (!toolList.tools?.some(tool => tool.name === 'list_identities')) throw new Error('Packaged OURS identity tools are absent');
-      } finally {
-        if (headers['mcp-session-id']) {
-          const response = await fetch(`${profile.endpoint}/mcp`, { method: 'DELETE', redirect: 'error', signal: AbortSignal.timeout(5000), headers });
-          await response.body?.cancel();
-          if (!response.ok) throw new Error('MCP verification session could not be closed');
-        }
-      }
-    },
+
   };
 }
 
@@ -1352,7 +1519,6 @@ async function nativeLifecycle(record, operation, selected, { effects, localEnv,
     if (service === 'daemon') {
       const profilePath = join(installationPaths(record).mcp, 'profile.json');
       await effects.verifyHostProfile(profilePath);
-      await effects.verifyPackagedMcp(profilePath);
       return;
     }
     if (service === 'cowork') { await ownerCommand(record, service, 'status'); return; }
@@ -1430,7 +1596,7 @@ async function nativeLifecycle(record, operation, selected, { effects, localEnv,
       }
       if (!ready) throw new Error('Application is not ready');
     } catch {
-      if (service === 'daemon') throw new Error('Daemon and packaged MCP are not ready; consumers were not started');
+      if (service === 'daemon') throw new Error('Daemon API is not ready; consumers were not started');
       failures.push(service);
     }
   }