node-command 2.0.2 → 2.0.4

package/bin/nc.mjs

@@ -8,19 +8,32 @@ import path from 'node:path';
 import os from 'node:os';
 import child_process from 'node:child_process';
 import readline from 'node:readline';
-import { Writable } from 'node:stream';
+import { Transform, Writable, pipeline } from 'node:stream';
 import { fileURLToPath } from 'node:url';
 import {
   canElevate,
+  canRepairUserApplication,
+  captureBrowserDefaultBrand,
+  normalizeBrowserBrand,
+  browserBrandReexecArgs,
   decideInstallMode,
   findRemovalTargets,
   getNcRootForMode,
   installerEnvForMode,
   isElevated,
+  isUserInstallRoot,
+  probeInstallRoot,
+  resolveExecutable,
+  setupTarget,
+  unreadableSystemInstallations,
+  maintainLinuxIdentity,
+  loadProtectedHelperProducer,
+  LINUX_PAIRED_UNINSTALL_ENTRY,
   modeWarningFor,
   runUninstallerScript,
   uninstallFailureSuggestion,
-  uninstallerForRoot
+  uninstallerForRoot,
+  windowsExecutablePath
 } from '../lib/setup.mjs';
 
 const baseUrl = process.env.NC_BASE_URL || 'https://auth.nodecommand.app';
@@ -29,14 +42,16 @@ const baseUrl = process.env.NC_BASE_URL || 'https://auth.nodecommand.app';
  * downloads, and `/releases/*`. The auth host (`baseUrl` above) serves only
  * browser-facing OAuth/device flow and enrollment (`/oauth/*`, `/api/enroll*`);
  * Caddy routes `/api/clients*` solely on the agent (and dash) edge, so
- * verification against the auth host answers 404. `NC_SERVER_URL` is NOT
- * this value: it is the agent WS/server address written to the client env.
+ * verification against the auth host answers 404. Fresh enrollment uses this
+ * configured API destination; installed credentials instead use their stored
+ * NC_SERVER_URL for authenticated HTTP, just like the agent runtime.
  */
 export const apiBase = process.env.NC_API_URL || 'https://agent.nodecommand.app';
 const clientId = 'nc-cli';
 
 export const DEFAULT_CLI_REQUEST_TIMEOUT_MS = 30_000;
 export const DEFAULT_CLI_MAX_RESPONSE_BYTES = 8 * 1024 * 1024; // 8 MiB
+export const CLI_MAX_PACKAGE_BYTES = 512 * 1024 * 1024; // 512 MiB
 
 export function getCliRequestTimeoutMs() {
   const envVal = Number(process.env.NC_CLI_TIMEOUT_MS || process.env.NC_TIMEOUT_MS);
@@ -48,6 +63,81 @@ export function getCliMaxResponseBytes() {
   return Number.isFinite(envVal) && envVal > 0 ? envVal : DEFAULT_CLI_MAX_RESPONSE_BYTES;
 }
 
+/**
+ * Hard ceiling for downloaded agent packages. Raised only through an explicit
+ * positive override so tests can exercise the streaming cap deterministically.
+ */
+export function getCliMaxPackageBytes() {
+  const envVal = Number(process.env.NC_CLI_MAX_PACKAGE_BYTES);
+  return Number.isSafeInteger(envVal) && envVal > 0 ? envVal : CLI_MAX_PACKAGE_BYTES;
+}
+
+/** Package downloads are bounded separately from ordinary JSON requests. */
+export const DEFAULT_CLI_DOWNLOAD_TIMEOUT_MS = 30 * 60_000; // 30 minutes
+export const MIN_CLI_DOWNLOAD_TIMEOUT_MS = 30_000;
+export const MAX_CLI_DOWNLOAD_TIMEOUT_MS = 60 * 60_000;
+
+export function getCliDownloadTimeoutMs(env = process.env) {
+  const envVal = Number(env.NC_CLI_DOWNLOAD_TIMEOUT_MS);
+  if (!Number.isFinite(envVal) || envVal <= 0) return DEFAULT_CLI_DOWNLOAD_TIMEOUT_MS;
+  return Math.min(MAX_CLI_DOWNLOAD_TIMEOUT_MS, Math.max(MIN_CLI_DOWNLOAD_TIMEOUT_MS, Math.floor(envVal)));
+}
+
+/**
+ * Strips terminal control sequences and control characters from untrusted
+ * display text (server-provided versions, URLs, errors and messages) so a
+ * hostile field cannot forge logs or move the cursor. Line breaks collapse to
+ * spaces, keeping every rendered message on one line.
+ * @param {unknown} value
+ * @param {number} [maxLength]
+ */
+export function sanitizeForDisplay(value, maxLength = 512) {
+  let text = typeof value === 'string' ? value : String(value ?? '');
+  text = text.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '');
+  text = text.replace(/\x1b[P^_X][\s\S]*?\x1b\\/g, '');
+  text = text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+  text = text.replace(/\x1b[@-_]/g, '');
+  text = text.replace(/[\r\n\t]+/g, ' ');
+  text = text.replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+  if (text.length > maxLength) text = `${text.slice(0, maxLength)}…`;
+  return text;
+}
+
+/** Explicit insecure-HTTP opt-in for local testing only. */
+export const INSECURE_HTTP_OPT_IN_ENV = 'NC_ALLOW_INSECURE_HTTP';
+
+export function allowsInsecureCredentialHttp(env = process.env) {
+  return String(env[INSECURE_HTTP_OPT_IN_ENV] ?? '').trim() === '1';
+}
+
+/**
+ * Refuses credential-bearing origins that are not HTTPS unless the explicit
+ * local-testing opt-in is set. Mirrors the stricter maintenance-config check.
+ * @param {string} targetUrl
+ * @param {{ env?: NodeJS.ProcessEnv, label?: string, action?: string }} [options]
+ */
+export function assertCredentialOrigin(targetUrl, { env = process.env, label = 'server URL', action = 'send credentials' } = {}) {
+  let parsed;
+  try {
+    parsed = new URL(String(targetUrl));
+  } catch {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to ${action} with an invalid ${label}.`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to ${action} to a ${label} that embeds user credentials.`);
+  }
+  if (parsed.protocol === 'http:' && !allowsInsecureCredentialHttp(env)) {
+    throw new PairingError(
+      'INSECURE_SERVER_URL',
+      `Refusing to ${action} over plaintext http:// (${label}). Use an https:// URL; set ${INSECURE_HTTP_OPT_IN_ENV}=1 only for local testing.`
+    );
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to ${action} to a non-HTTP(S) ${label}.`);
+  }
+  return parsed;
+}
+
 /**
  * Sends a JSON HTTP request using node:https or node:http with timeout and response cap guards (NC-AUD-010).
  * @param {string} method
@@ -252,7 +342,19 @@ export function httpGet(targetUrl, maxRedirects = 5, extraHeaders = {}, options
           res.statusCode < 400 &&
           res.headers.location
         ) {
-          const redirectUrl = new URL(res.headers.location, targetUrl).toString();
+          /** @type {string} */
+          let redirectUrl;
+          try {
+            redirectUrl = new URL(res.headers.location, targetUrl).toString();
+          } catch (err) {
+            // A malformed Location header must reject the request, never throw
+            // out of the response callback as an uncaughtException.
+            res.resume();
+            return reject(new PairingError(
+              'INSTALL_DOWNLOAD_ERROR',
+              `The package response from ${targetUrl} contained an invalid redirect location: ${err instanceof Error ? err.message : String(err)}`
+            ));
+          }
           res.resume();
           const forwarded = isSameOrigin(targetUrl, redirectUrl) ? extraHeaders : {};
           return resolve(httpGet(redirectUrl, maxRedirects - 1, forwarded, { signal, timeoutMs }));
@@ -289,42 +391,111 @@ export async function fetchJson(targetUrl, extraHeaders = {}) {
 }
 
 /**
- * Downloads a remote file stream directly to disk.
+ * Downloads a remote file stream directly to disk with a hard byte ceiling and
+ * an incrementally computed SHA-256 digest. The archive is never loaded into
+ * the heap: bytes are hashed as they are written.
  * @param {string} targetUrl
  * @param {string} destinationPath
  * @param {Record<string, string>} [extraHeaders] Device headers for `/api/clients/...` package URLs; empty for public `/releases/...` URLs.
- * @param {{ timeoutMs?: number, signal?: AbortSignal }} [options]
- * @returns {Promise<string>}
+ * @param {{ timeoutMs?: number, signal?: AbortSignal, maxBytes?: number }} [options]
+ * @returns {Promise<{ path: string, bytes: number, sha256: string }>}
  */
 export async function downloadToFile(targetUrl, destinationPath, extraHeaders = {}, options = {}) {
-  const res = await httpGet(targetUrl, 5, extraHeaders, options);
+  const maxBytes = Number.isSafeInteger(options.maxBytes) && options.maxBytes > 0 ? options.maxBytes : getCliMaxPackageBytes();
+  const timeoutMs = options.timeoutMs ?? getCliDownloadTimeoutMs();
+  const controller = new AbortController();
+  let timedOut = false;
+  let timer;
+  if (timeoutMs > 0) {
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    timer.unref?.();
+  }
+  const clearTimer = () => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+  const timeoutError = () => Object.assign(
+    new Error(`Agent package download timed out after ${timeoutMs}ms.`),
+    { code: 'CLI_DOWNLOAD_TIMEOUT', name: 'TimeoutError' }
+  );
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  let res;
+  try {
+    res = await httpGet(targetUrl, 5, extraHeaders, { ...options, timeoutMs: 0, signal });
+  } catch (err) {
+    clearTimer();
+    throw timedOut ? timeoutError() : err;
+  }
   return new Promise((resolve, reject) => {
-    const fileStream = fs.createWriteStream(destinationPath);
-    let resolved = false;
+    const tooLarge = () => Object.assign(
+      new Error(`Agent package exceeds the maximum supported size of ${maxBytes} bytes.`),
+      { code: 'CLI_PACKAGE_TOO_LARGE' }
+    );
+    const declaredLength = Number(res.headers?.['content-length']);
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+      res.resume();
+      clearTimer();
+      reject(tooLarge());
+      return;
+    }
+
+    const fileStream = fs.createWriteStream(destinationPath, { mode: 0o600 });
+    const hash = crypto.createHash('sha256');
+    let bytes = 0;
+    let settled = false;
+
+    const meter = new Transform({
+      transform(chunk, encoding, callback) {
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          callback(tooLarge());
+          return;
+        }
+        hash.update(chunk);
+        callback(null, chunk);
+      }
+    });
 
     const onError = (err) => {
-      if (resolved) return;
-      resolved = true;
+      if (settled) return;
+      settled = true;
+      clearTimer();
       fileStream.destroy();
       try {
         fs.unlinkSync(destinationPath);
       } catch {}
-      reject(err);
+      reject(timedOut ? timeoutError() : err);
     };
 
     res.on('error', onError);
+    meter.on('error', onError);
     fileStream.on('error', onError);
 
-    fileStream.on('finish', () => {
-      if (resolved) return;
-      resolved = true;
-      fileStream.close(() => resolve(destinationPath));
+    pipeline(res, meter, fileStream, (err) => {
+      if (err) return onError(err);
+      if (settled) return;
+      settled = true;
+      clearTimer();
+      resolve({ path: destinationPath, bytes, sha256: hash.digest('hex') });
     });
-
-    res.pipe(fileStream);
   });
 }
 
+/** Distinguishes an aborted/slow transfer from a credential or manifest failure. */
+function isCliTimeoutError(err) {
+  return Boolean(err) && (
+    err.name === 'TimeoutError' ||
+    err.name === 'AbortError' ||
+    err.code === 'ABORT_ERR' ||
+    err.code === 'CLI_DOWNLOAD_TIMEOUT'
+  );
+}
+
 /**
  * Determines the canonical installation root (NC_ROOT) dynamically based on
  * OS:
@@ -361,14 +532,81 @@ export function getNcRoot({ platform = os.platform(), env = process.env } = {})
  * @returns {string}
  */
 function getTarCommand() {
-  if (os.platform() === 'win32') {
-    const sysTar = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe');
-    if (fs.existsSync(sysTar)) {
-      return sysTar;
+  return resolveExecutable('tar');
+}
+
+/** Only pass GNU confinement flags when this tar actually advertises them. */
+function tarSupportsNoAbsoluteFilenames(tarCmd) {
+  try {
+    const help = child_process.execFileSync(tarCmd, ['--help'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+      maxBuffer: 256 * 1024,
+      env: { ...process.env, LC_ALL: 'C', LANG: 'C' }
+    });
+    return /--no-absolute-filenames/.test(String(help));
+  } catch {
+    return false;
+  }
+}
+
+function tarInspectionError(tarCmd, err) {
+  const detail = err?.stderr ? err.stderr.toString().trim() : err?.message;
+  return new Error(
+    `Failed to inspect tarball (${tarCmd}): ${sanitizeForDisplay(detail, 300)}`,
+    { cause: err }
+  );
+}
+
+function rejectsTarEntry(name) {
+  const value = String(name).trim();
+  if (!value) return false;
+  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) return true;
+  return value.split(/[\\/]+/).includes('..');
+}
+
+/**
+ * Rejects traversal, absolute and link entries before extraction. This is
+ * defense-in-depth on top of GNU tar's --no-absolute-filenames; the archive is
+ * fully listed first so a hostile entry cannot be extracted at all.
+ */
+function assertSafeTarArchive(tarCmd, archivePath) {
+  let listing;
+  try {
+    listing = child_process.execFileSync(tarCmd, ['-tzf', archivePath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 30000,
+      maxBuffer: 4 * 1024 * 1024
+    });
+  } catch (err) {
+    throw tarInspectionError(tarCmd, err);
+  }
+  for (const name of String(listing).split(/\r?\n/)) {
+    if (rejectsTarEntry(name)) {
+      throw new Error(`Unsafe archive entry escapes the extraction root: ${sanitizeForDisplay(name, 200)}`);
+    }
+  }
+
+  let verbose;
+  try {
+    verbose = child_process.execFileSync(tarCmd, ['-tvzf', archivePath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 30000,
+      maxBuffer: 4 * 1024 * 1024
+    });
+  } catch (err) {
+    throw tarInspectionError(tarCmd, err);
+  }
+  for (const line of String(verbose).split(/\r?\n/)) {
+    // Symlink (l) and hardlink (h) entries can redirect later writes outside
+    // the extraction root even when their names look safe.
+    if (/^[lh][rwxStTs-]{9}/.test(line)) {
+      throw new Error(`Unsafe archive link entry is not permitted: ${sanitizeForDisplay(line, 200)}`);
     }
-    return 'tar.exe';
   }
-  return 'tar';
 }
 
 /**
@@ -377,14 +615,18 @@ function getTarCommand() {
  * @param {string} targetDir
  */
 function extractTarball(archivePath, targetDir) {
-  const tarCmd = getTarCommand();
+  let tarCmd = 'tar';
   try {
-    child_process.execFileSync(tarCmd, ['-xzf', archivePath, '-C', targetDir], {
+    tarCmd = getTarCommand();
+    assertSafeTarArchive(tarCmd, archivePath);
+    const args = ['-xzf', archivePath, '-C', targetDir];
+    if (tarSupportsNoAbsoluteFilenames(tarCmd)) args.unshift('--no-absolute-filenames');
+    child_process.execFileSync(tarCmd, args, {
       stdio: ['ignore', 'pipe', 'pipe']
     });
   } catch (err) {
     const details = err.stderr ? err.stderr.toString().trim() : err.message;
-    throw new Error(`Failed to extract tarball (${tarCmd}): ${details}`, { cause: err });
+    throw new Error(`Failed to extract tarball (${tarCmd}): ${sanitizeForDisplay(details, 300)}`, { cause: err });
   }
 }
 
@@ -431,33 +673,39 @@ export function findInstallerScript(tempDir) {
  */
 export function runInstallerScript(scriptPath, ncRoot, extraEnv = {}) {
   const platform = os.platform();
-  const installEnv = {
-    ...process.env,
-    NC_ROOT: ncRoot,
-    ...extraEnv
-  };
 
   if (platform === 'win32') {
     child_process.execFileSync(
-      'powershell.exe',
-      ['-ExecutionPolicy', 'Bypass', '-File', scriptPath],
+      windowsExecutablePath('powershell'),
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath],
       {
-        env: installEnv,
+        env: { ...process.env, NC_ROOT: ncRoot, ...extraEnv },
         stdio: 'inherit'
       }
     );
-  } else if (platform === 'darwin') {
-    child_process.execFileSync('bash', [scriptPath], {
-      env: installEnv,
-      stdio: 'inherit'
-    });
-  } else {
-    // Linux and other POSIX
-    child_process.execFileSync('bash', [scriptPath], {
-      env: installEnv,
-      stdio: 'inherit'
-    });
+    return;
   }
+
+  // The OS installer runs with root privileges, so it never inherits the
+  // caller's environment. Only a fixed base plus NC_* installer knobs and
+  // explicit extras reach it; BASH_ENV/ENV/SHELLOPTS/LD_*/NODE_OPTIONS cannot.
+  const installEnv = {
+    PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+    HOME: os.userInfo().homedir,
+    LANG: 'C',
+    LC_ALL: 'C'
+  };
+  for (const [name, value] of Object.entries(process.env)) {
+    if (name.startsWith('NC_') && typeof value === 'string') installEnv[name] = value;
+  }
+  Object.assign(installEnv, { NC_ROOT: ncRoot }, extraEnv);
+  // `-p` (privileged mode) plus --noprofile/--norc ignores BASH_ENV/ENV startup
+  // files; cwd '/' keeps a user-writable directory out of the root installer.
+  child_process.execFileSync(resolveExecutable('bash'), ['--noprofile', '--norc', '-p', '--', scriptPath], {
+    env: installEnv,
+    stdio: 'inherit',
+    cwd: '/'
+  });
 }
 
 /**
@@ -526,17 +774,240 @@ export function getEnrollStatePath(ncRoot = getNcRoot()) {
   return path.join(ncRoot, 'config', 'nc-enroll-state.json');
 }
 
+/**
+ * Serializes setup/install/uninstall for one installation root. The lock file
+ * lives under the root, is created with O_CREAT|O_EXCL and 0600 (O_EXCL
+ * refuses an existing file or symlink instead of following it), carries the
+ * owner PID, and is released by the exit handler as well as by the caller's
+ * finally block (so `process.exit` cannot leave it behind). A live owner is a
+ * clear SETUP_IN_PROGRESS refusal; a dead PID is stale and is reclaimed once.
+ * @param {string} ncRoot
+ * @returns {{ release: () => void }}
+ */
+export function acquireInstallLock(ncRoot) {
+  const configDir = path.join(ncRoot, 'config');
+  const lockPath = path.join(configDir, '.nc-cli.lock');
+  const createdConfig = !fs.existsSync(configDir);
+  const createdRoot = createdConfig && !fs.existsSync(ncRoot);
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o750 });
+
+  const readOwnerPid = () => {
+    let fd;
+    try {
+      fd = fs.openSync(lockPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+      const info = fs.fstatSync(fd);
+      if (!info.isFile() || info.size > 32) return null;
+      const text = fs.readFileSync(fd, 'utf8').trim();
+      return /^\d+$/.test(text) ? Number(text) : null;
+    } catch {
+      return null;
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+  };
+
+  const pidIsAlive = (pid) => {
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      return err?.code === 'EPERM';
+    }
+  };
+
+  let acquired = false;
+  for (let attempt = 0; attempt < 2 && !acquired; attempt += 1) {
+    try {
+      // `wx` is O_WRONLY|O_CREAT|O_EXCL: an existing file OR symlink at the
+      // lock path fails with EEXIST instead of being followed or truncated.
+      fs.writeFileSync(lockPath, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
+      if (process.platform !== 'win32') {
+        try {
+          fs.chmodSync(lockPath, 0o600);
+        } catch {}
+      }
+      acquired = true;
+    } catch (err) {
+      if (err?.code !== 'EEXIST') throw err;
+      const owner = readOwnerPid();
+      if (owner === null || pidIsAlive(owner)) {
+        throw new PairingError(
+          'SETUP_IN_PROGRESS',
+          `Another Node Command setup, install or uninstall is already running for ${ncRoot}${owner === null ? '' : ` (pid ${owner})`}. Wait for it to finish; no configuration was changed.`
+        );
+      }
+      // Stale owner: reclaim the lock exactly once.
+      try {
+        fs.unlinkSync(lockPath);
+      } catch (unlinkErr) {
+        if (unlinkErr?.code !== 'ENOENT') throw unlinkErr;
+      }
+    }
+  }
+  if (!acquired) {
+    throw new PairingError('SETUP_IN_PROGRESS', `Could not acquire the setup lock for ${ncRoot}; no configuration was changed.`);
+  }
+
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    try {
+      const owner = readOwnerPid();
+      if (owner === process.pid) fs.unlinkSync(lockPath);
+    } catch {}
+    // Remove empty directories created only for the lock so a failed setup
+    // does not leave a root that blocks the next attempt.
+    if (createdConfig) {
+      try {
+        fs.rmdirSync(configDir);
+        if (createdRoot) fs.rmdirSync(ncRoot);
+      } catch {}
+    }
+  };
+  process.once('exit', release);
+  return {
+    release: () => {
+      process.removeListener('exit', release);
+      release();
+    }
+  };
+}
+
+/**
+ * Prepares the token transport used for legacy `setup <host_id> <token>`
+ * elevation: the secret goes to a 0600 owner-only temp file and only its path
+ * enters sudo/UAC argv.
+ * @param {string} token
+ */
+export function createEnrollmentTokenFile(token) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nc-enroll-'));
+  const filePath = path.join(dir, 'token');
+  fs.writeFileSync(filePath, String(token), { mode: 0o600, flag: 'wx' });
+  if (os.platform() !== 'win32') {
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {}
+  }
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {}
+  };
+  // process.exit() skips finally blocks, so the exit hook guarantees the
+  // secret file is removed even on the declined-elevation hard stops.
+  process.once('exit', cleanup);
+  return {
+    filePath,
+    cleanup: () => {
+      process.removeListener('exit', cleanup);
+      cleanup();
+    }
+  };
+}
+
+/**
+ * Reads the elevated-invocation token file (no symlinks, owner-only) and
+ * removes it immediately after use.
+ * @param {string} filePath
+ */
+function readEnrollmentTokenFile(filePath) {
+  if (typeof filePath !== 'string' || !path.isAbsolute(filePath)) {
+    throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file path is invalid.');
+  }
+  let fd;
+  let token;
+  try {
+    try {
+      fd = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    } catch {
+      throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is missing, unreadable, or a symlink.');
+    }
+    const info = fs.fstatSync(fd);
+    if (!info.isFile() || info.size <= 0 || info.size > 1024) {
+      throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is not a valid token file.');
+    }
+    if (os.platform() !== 'win32') {
+      if ((info.mode & 0o077) !== 0) {
+        throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is not owner-only.');
+      }
+      const currentUid = typeof process.getuid === 'function' ? process.getuid() : null;
+      if (currentUid !== null) {
+        const allowedUids = new Set([currentUid]);
+        // `sudo` runs the elevated reader as root while the pre-sudo writer
+        // owned the file as the invoking user. Trust SUDO_UID only when the
+        // reader is actually root, and only as a validated numeric uid.
+        if (currentUid === 0 && typeof process.env.SUDO_UID === 'string' && /^\d+$/.test(process.env.SUDO_UID)) {
+          const sudoUid = Number(process.env.SUDO_UID);
+          if (Number.isSafeInteger(sudoUid) && sudoUid >= 0) allowedUids.add(sudoUid);
+        }
+        if (!allowedUids.has(info.uid)) {
+          throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is not owned by the invoking user.');
+        }
+      }
+    }
+    token = fs.readFileSync(fd, 'utf8');
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try {
+      fs.unlinkSync(filePath);
+      const dir = path.dirname(filePath);
+      if (path.basename(dir).startsWith('nc-enroll-')) fs.rmdirSync(dir);
+    } catch {}
+  }
+  return token;
+}
+
+/**
+ * Replaces the legacy enrollment token in the elevated argv with a file path.
+ * Pure so the no-secret-in-argv property is directly testable.
+ * @param {string[]} nodeArgs process.argv.slice(1)
+ * @param {string[]} setupArgs subcommand args (without a literal `setup`)
+ * @param {number} tokenIndex index of the token in setupArgs
+ * @param {string} tokenFile
+ * @returns {string[]}
+ */
+export function buildElevatedSetupArgs(nodeArgs, setupArgs, tokenIndex, tokenFile) {
+  if (!Array.isArray(nodeArgs) || !Array.isArray(setupArgs) || tokenIndex < 0 || tokenIndex >= setupArgs.length) return [...nodeArgs];
+  const prefixLength = nodeArgs.length - setupArgs.length;
+  const elevated = [...nodeArgs];
+  elevated.splice(prefixLength + tokenIndex, 1, '--enrollment-token-file', tokenFile);
+  // A bare `<host_id> <token>` invocation must route through the setup handler
+  // after elevation; adding the subcommand keeps dispatch unchanged.
+  if (prefixLength === 1) elevated.splice(1, 0, 'setup');
+  return elevated;
+}
+
 /**
  * Builds the canonical agent env file content from HOST credentials only.
  * There is deliberately no parameter for the OAuth token: by construction it
  * cannot end up in the file. Host id/token shapes are enforced so a caller
  * mistake (e.g. passing an enrollment token as the client token) fails here
  * instead of producing a broken agent that crash-loops on 401.
- * @param {{ serverUrl: string, hostId: string, hostToken: string, clientName?: string }} options
+ * @param {{ serverUrl: string, hostId: string, hostToken: string, clientName?: string, browserBrand?: string }} options
  */
-export function buildHostEnvContent({ serverUrl, hostId, hostToken, clientName = os.hostname() }) {
-  if (typeof serverUrl !== 'string' || !serverUrl) {
-    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config without a server URL.');
+export function buildHostEnvContent({ serverUrl, hostId, hostToken, clientName = os.hostname(), browserBrand = 'unknown' }) {
+  if (typeof serverUrl !== 'string' || !serverUrl || /[\x00-\x1f\x7f]/.test(serverUrl)) {
+    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config without a valid server URL.');
+  }
+  let parsedServerUrl;
+  try {
+    parsedServerUrl = new URL(serverUrl);
+  } catch {
+    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config: the server URL is not an absolute http(s) URL.');
+  }
+  if ((parsedServerUrl.protocol !== 'https:' && parsedServerUrl.protocol !== 'http:') || parsedServerUrl.username || parsedServerUrl.password) {
+    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config: the server URL must be http(s) and must not embed credentials.');
+  }
+  if (parsedServerUrl.protocol === 'http:' && !allowsInsecureCredentialHttp()) {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to write agent config: plaintext http:// is not allowed for a credential-bearing server URL; use https:// (set ${INSECURE_HTTP_OPT_IN_ENV}=1 only for local testing).`);
+  }
+  if (typeof clientName !== 'string' || /[\x00-\x1f\x7f]/.test(clientName)) {
+    throw new PairingError('INVALID_CLIENT_NAME', 'Refusing to write agent config: the client name contains control characters.');
   }
   if (!HOST_ID_RE.test(String(hostId || ''))) {
     throw new PairingError(
@@ -556,6 +1027,7 @@ export function buildHostEnvContent({ serverUrl, hostId, hostToken, clientName =
     `NC_CLIENT_NAME=${clientName}`,
     `NC_CLIENT_TOKEN=${hostToken}`,
     'NC_REMOTE_EXEC_ENABLED=true',
+    `NC_BROWSER_DEFAULT_BRAND=${normalizeBrowserBrand(browserBrand)}`,
     'NC_SESSION_ENABLED=true'
   ].join('\n') + '\n';
 }
@@ -604,6 +1076,11 @@ export function loadValidHostEnv(envPath = getEnvFilePath()) {
   } catch {
     return null;
   }
+  // Duplicate required keys are ambiguous (a repeated line could shadow the
+  // verified identity), so the loader refuses the file instead of last-wins.
+  for (const name of ['NC_CLIENT_ID', 'NC_CLIENT_TOKEN', 'NC_SERVER_URL']) {
+    if (text.split(/\r?\n/).filter((line) => new RegExp(`^\\s*${name}\\s*=`).test(line)).length > 1) return null;
+  }
   const env = parseEnvFile(text);
   if (!HOST_ID_RE.test(String(env.NC_CLIENT_ID || ''))) return null;
   if (!HOST_TOKEN_RE.test(String(env.NC_CLIENT_TOKEN || ''))) return null;
@@ -611,6 +1088,15 @@ export function loadValidHostEnv(envPath = getEnvFilePath()) {
   return env;
 }
 
+function assertMatchingHostIdentity(localEnv, requestedHostId) {
+  if (localEnv && requestedHostId && localEnv.NC_CLIENT_ID !== requestedHostId) {
+    throw new PairingError(
+      'HOST_ID_MISMATCH',
+      `This installation belongs to host ${localEnv.NC_CLIENT_ID}, but host ${requestedHostId} was requested. Stored credentials are unchanged; the supplied enrollment token has not been redeemed.`
+    );
+  }
+}
+
 /**
  * Resume marker for idempotent re-runs. Holds the host id and lifecycle
  * phase only — never any token or key material (those live in nc-client.env
@@ -716,6 +1202,52 @@ export function loadDeviceKeyPair(keyFile) {
   return { privateKey: key, publicKey, thumbprint: deviceKeyThumbprintCli(publicKey) };
 }
 
+/** Read only the selected ordinary key for Root-managed paired verification. */
+function loadRootManagedPairKey(ncRoot, ordinaryUid) {
+  const invalid = () => { throw new Error('Root-managed pair device key cannot be verified safely.'); };
+  if (os.platform() !== 'linux' || process.getuid?.() !== 0 || process.geteuid?.() !== 0 ||
+      !['/opt/nc', '/var/lib/nodecommand/nc'].includes(ncRoot) || !Number.isSafeInteger(ordinaryUid) || ordinaryUid <= 0) invalid();
+  let directoryFd, keyFd;
+  try {
+    // Pin each directory before opening its child. NOFOLLOW on the key alone
+    // would still follow a replaced ordinary root/config ancestor as Root.
+    const components = ncRoot === '/opt/nc' ? ['', 'opt', 'nc', 'config'] : ['', 'var', 'lib', 'nodecommand', 'nc', 'config'];
+    for (const component of components) {
+      const next = fs.openSync(component ? `/proc/self/fd/${directoryFd}/${component}` : '/',
+        fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+      if (directoryFd !== undefined) fs.closeSync(directoryFd);
+      directoryFd = next;
+      const info = fs.fstatSync(directoryFd);
+      const ordinaryRoot = ncRoot === '/var/lib/nodecommand/nc' && component === 'nc';
+      const protectedAncestor = !ordinaryRoot && component !== 'config';
+      if (!info.isDirectory() || (ordinaryRoot ? ![0, ordinaryUid].includes(info.uid) : info.uid !== (protectedAncestor ? 0 : ordinaryUid)) ||
+          (protectedAncestor && (info.gid !== 0 || (info.mode & 0o022)))) invalid();
+    }
+    keyFd = fs.openSync(`/proc/self/fd/${directoryFd}/nc-device-key.pem`,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    const before = fs.fstatSync(keyFd);
+    if (!before.isFile() || before.uid !== ordinaryUid || before.nlink !== 1 ||
+        !Number.isSafeInteger(before.size) || before.size <= 0 || before.size > 65536) invalid();
+    const buffer = Buffer.alloc(65537);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = fs.readSync(keyFd, buffer, length, buffer.length - length, null);
+      if (count === 0) break;
+      length += count;
+    }
+    const after = fs.fstatSync(keyFd);
+    if (length !== before.size || length > 65536 || !after.isFile() ||
+        ['dev', 'ino', 'uid', 'gid', 'mode', 'nlink', 'size', 'mtimeMs', 'ctimeMs'].some(field => before[field] !== after[field])) invalid();
+    const privateKey = crypto.createPrivateKey(buffer.subarray(0, length));
+    if (privateKey.asymmetricKeyType !== 'ed25519') invalid();
+    const publicKey = publicRawFromPrivateCli(privateKey);
+    return { privateKey, publicKey, thumbprint: deviceKeyThumbprintCli(publicKey) };
+  } finally {
+    if (keyFd !== undefined) fs.closeSync(keyFd);
+    if (directoryFd !== undefined) fs.closeSync(directoryFd);
+  }
+}
+
 /**
  * Loads the device key, generating and persisting a fresh Ed25519 key when
  * none exists (atomic tmp-write + rename, 0600). Mirrors
@@ -813,6 +1345,7 @@ export async function requestEnrollment({ baseUrl, oauthToken, platform = 'linux
     throw new PairingError('ENROLL_NO_OAUTH_TOKEN', 'Cannot request enrollment without a sign-in token. Re-run the device flow.');
   }
   const origin = String(baseUrl || '').replace(/\/$/, '');
+  assertCredentialOrigin(origin, { label: 'enrollment origin' });
   const body = { platform, ...(name ? { name } : {}), ...(tenantId ? { tenant_id: tenantId } : {}) };
   let res;
   try {
@@ -826,8 +1359,8 @@ export async function requestEnrollment({ baseUrl, oauthToken, platform = 'linux
     }
     return res.data;
   }
-  const serverError = res.data?.error;
-  const serverMessage = typeof res.data?.message === 'string' ? `: ${res.data.message}` : '';
+  const serverError = sanitizeForDisplay(res.data?.error || '', 120);
+  const serverMessage = typeof res.data?.message === 'string' ? `: ${sanitizeForDisplay(res.data.message)}` : '';
   if (res.status === 401) {
     throw new PairingError('ENROLL_UNAUTHORIZED', 'Sign-in expired or was revoked. Re-run the device flow to sign in again.');
   }
@@ -852,14 +1385,16 @@ export async function requestEnrollment({ baseUrl, oauthToken, platform = 'linux
 /**
  * Redeems a one-time enrollment token with Device Proof v1, binding the
  * local Ed25519 key to the host identity. Returns the redemption payload
- * (client_id, client_token, release). A 410 ENROLLMENT_ALREADY_USED means a
- * previous run already consumed this token — the caller resumes from local
- * credentials instead of retrying redemption.
- * @param {{ baseUrl: string, hostId: string, enrollmentToken: string, keyPair: { privateKey: import('node:crypto').KeyObject, publicKey: string, thumbprint: string } }} options
+ * (client_id, client_token, release, optional execution_initialization). The
+ * selected intent is covered by the unchanged proof's exact pathname/query.
+ * Token authentication failures do not disclose whether redemption committed.
+ * @param {{ baseUrl: string, hostId: string, enrollmentToken: string, initialPermission?: 'user'|'admin', keyPair: { privateKey: import('node:crypto').KeyObject, publicKey: string, thumbprint: string } }} options
  */
-export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPair }) {
+export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPair, initialPermission = 'user' }) {
+  if (!['user', 'admin'].includes(initialPermission)) throw new PairingError('INVALID_INITIAL_PERMISSION', 'Initial execution intent must be user or admin.');
   const origin = String(baseUrl || '').replace(/\/$/, '');
-  const redeemPath = '/api/enroll/redeem';
+  assertCredentialOrigin(origin, { label: 'redemption origin' });
+  const redeemPath = `/api/enroll/redeem?initial_permission=${initialPermission}`;
   const proof = createDeviceProofCli({
     privateKey: keyPair.privateKey,
     hostId,
@@ -875,7 +1410,7 @@ export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPa
       { 'NC-Device-Proof': proof }
     );
   } catch (err) {
-    throw new PairingError('REDEEM_NETWORK_ERROR', `Could not reach the redemption endpoint: ${err.message}`);
+    throw new PairingError('REDEEM_NETWORK_ERROR', `Redemption response was not received: ${err.message}. The server may have committed; preserve local identity and use authorized recovery rather than reminting or replaying initialization.`);
   }
   if (res.status === 200 && res.data) {
     const r = res.data;
@@ -887,11 +1422,11 @@ export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPa
     }
     return r;
   }
-  const serverError = res.data?.error;
+  const serverError = sanitizeForDisplay(res.data?.error || '', 120);
   if (res.status === 410 && serverError === 'ENROLLMENT_ALREADY_USED') {
     throw new PairingError(
       'ENROLLMENT_ALREADY_USED',
-      'This enrollment was already redeemed (a previous run consumed it). Re-running resumes from the locally stored host credentials.'
+      'The legacy server refused redemption. Preserve existing host/device identity and recover only through authorized existing credentials or management; no credentials were recovered by this attempt.'
     );
   }
   if (res.status === 410) {
@@ -901,7 +1436,7 @@ export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPa
     );
   }
   if (res.status === 401) {
-    throw new PairingError('REDEEM_UNAUTHORIZED', `Redemption was refused (${serverError || 'unauthorized'}). Re-run to request a fresh enrollment.`);
+    throw new PairingError('REDEEM_UNAUTHORIZED', `Redemption was refused (${serverError || 'unauthorized'}). No credentials or initialization were recovered. Preserve any existing identity and use authorized credential/management recovery; do not blindly remint or replay.`);
   }
   throw new PairingError('REDEEM_REJECTED', `Redemption failed (${serverError || `HTTP ${res.status}`}). Re-run to request a fresh enrollment.`);
 }
@@ -912,14 +1447,16 @@ export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPa
  * uses). Polls until the identity is accepted or the timeout expires.
  * Success here proves the env credentials actually authenticate; only then
  * may the CLI print a success message.
- * Device-channel endpoints live on the agent edge (`apiBase`/`NC_API_URL`),
- * never on the auth host. `baseUrl` stays accepted for backward
+ * Device-channel endpoints use the supplied agent destination. Resume callers
+ * must supply the stored NC_SERVER_URL, not the fresh-enrollment API default.
+ * `baseUrl` stays accepted for backward
  * compatibility but an explicit `apiBase` (or `NC_API_URL`/default agent
  * origin when neither is given) wins.
  * @param {{ baseUrl?: string, apiBase?: string, hostId: string, hostToken: string, privateKey: import('node:crypto').KeyObject, timeoutMs?: number, intervalMs?: number }} options
   */
 export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined, apiBase: apiBaseOpt = undefined, hostId, hostToken, privateKey, timeoutMs = 45000, intervalMs = 2000 }) {
   const origin = String(apiBaseOpt ?? baseUrlOpt ?? process.env.NC_API_URL ?? apiBase).replace(/\/$/, '');
+  assertCredentialOrigin(origin, { label: 'agent server origin' });
   const target = `/api/clients/${encodeURIComponent(hostId)}/policy`;
   const deadline = Date.now() + Math.max(1000, Number(timeoutMs) || 45000);
   const step = Math.max(250, Math.min(Number(intervalMs) || 2000, deadline - Date.now()));
@@ -932,20 +1469,25 @@ export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined,
         'NC-Device-Proof': proof
       });
       if (res.status === 200 && res.data?.policy) return { ok: true, hostId };
-      lastError = res.data?.error || `HTTP ${res.status}`;
+      lastError = sanitizeForDisplay(res.data?.error || `HTTP ${res.status}`, 200);
       // A missing client row will never appear by waiting: fail fast so the
       // user gets the real cause instead of a timeout.
       if (res.status === 404) {
-        throw new PairingError('VERIFY_FAILED', `Host ${hostId} is not registered on the server (${lastError}). Re-run to enroll again.`);
+        throw new PairingError('VERIFY_FAILED', `Host ${sanitizeForDisplay(hostId, 128)} is not registered on the server (${lastError}). Re-run to enroll again.`);
+      }
+      // A refused device credential cannot become valid by waiting: fail fast
+      // instead of polling until the verification timeout.
+      if (res.status === 401 || res.status === 403) {
+        throw new PairingError('VERIFY_FAILED', `Host ${sanitizeForDisplay(hostId, 128)} was refused at ${sanitizeForDisplay(origin, 256)} (${lastError}). The stored device credential is not accepted; re-run to enroll again.`);
       }
     } catch (err) {
       if (err instanceof PairingError) throw err;
-      lastError = err.message;
+      lastError = sanitizeForDisplay(err.message, 200);
     }
     if (Date.now() >= deadline) {
       throw new PairingError(
         'VERIFY_TIMEOUT',
-        `Could not confirm host ${hostId} on the server in time (last: ${lastError}). The credentials are stored; check connectivity and re-run to verify.`
+        `Could not confirm host ${sanitizeForDisplay(hostId, 128)} on the server in time (last: ${lastError}). The credentials are stored; check connectivity and re-run to verify.`
       );
     }
     await sleep(Math.min(step, Math.max(250, deadline - Date.now())));
@@ -977,11 +1519,11 @@ export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined,
  * (`/releases/client/<version>/bootstrap.tar.gz`) stays anonymous. The
  * proof binds method GET + the full request URL + the redemption-issued
  * client token, exactly like redeemEnrollment.
- * @param {{ ncRoot?: string, updatesUrl?: string, serverUrl?: string, release?: Record<string, unknown>|null, installMode?: 'system'|'user', runInstaller?: (scriptPath: string, ncRoot: string) => void, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject }} options
+ * @param {{ ncRoot?: string, updatesUrl?: string, serverUrl?: string, release?: Record<string, unknown>|null, installMode?: 'system'|'user', rootConsent?: boolean, runInstaller?: (scriptPath: string, ncRoot: string) => void, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject, downloadTimeoutMs?: number }} options
  */
-export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl = undefined, serverUrl = undefined, release = undefined, installMode = undefined, runInstaller = undefined, hostId = undefined, hostToken = undefined, privateKey = undefined } = {}) {
+export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl = undefined, serverUrl = undefined, release = undefined, installMode = undefined, rootConsent = false, runInstaller = undefined, hostId = undefined, hostToken = undefined, privateKey = undefined, downloadTimeoutMs = undefined } = {}) {
   ncRoot = ncRoot || (installMode ? getNcRootForMode(installMode) : getNcRoot());
-  const modeEnv = installMode ? installerEnvForMode(installMode) : {};
+  const modeEnv = { ...(installMode ? installerEnvForMode(installMode) : {}), NC_ROOT_COMMAND_CONSENT: rootConsent === true ? 'yes' : 'no' };
   const invokeInstaller =
     runInstaller || ((scriptPath, root) => runInstallerScript(scriptPath, root, modeEnv));
   const root = ncRoot;
@@ -993,28 +1535,33 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
   // used here. NC_SERVER_URL remains the agent server address and is read
   // before the API origin so existing installs keep resolving as before.
   const defaultBaseUrl = serverUrl || process.env.NC_SERVER_URL || process.env.NC_API_URL || apiBase;
+  const hasDeviceIdentity =
+    typeof hostId === 'string' &&
+    hostId &&
+    typeof hostToken === 'string' &&
+    hostToken &&
+    privateKey;
+  // Device identity must never travel over plaintext HTTP, including the
+  // fresh-enrollment resume paths that skip the manifest above.
+  if (hasDeviceIdentity) {
+    assertCredentialOrigin(defaultBaseUrl, { label: 'agent server origin' });
+  }
   /** @type {Record<string, any>} */
   let activeRelease;
   if (release && typeof release === 'object') {
     // Redemption release wins: skip the manifest entirely, so its URL is
     // never logged as a misleading signal.
     activeRelease = /** @type {Record<string, any>} */ (release);
-    const releaseVersion = activeRelease.version ? ` ${activeRelease.version}` : '';
+    const releaseVersion = activeRelease.version ? ` ${sanitizeForDisplay(activeRelease.version, 120)}` : '';
     console.log(`📦 Using release${releaseVersion} from enrollment redemption; skipping update manifest.`);
-  } else if (
-    typeof hostId === 'string' &&
-    hostId &&
-    typeof hostToken === 'string' &&
-    hostToken &&
-    privateKey
-  ) {
+  } else if (hasDeviceIdentity) {
     // Resume paths (verified stored credentials, already-redeemed enrollment)
     // carry no redemption release, but they DO hold device identity. Resolve
     // the release from the client-authenticated per-host manifest the agent
     // updater itself uses, never from the admin-only /api/updates manifest
     // (which can only answer 401/404 to a non-admin CLI).
     const clientManifestUrl = `${defaultBaseUrl}/api/clients/${encodeURIComponent(hostId)}/update/manifest`;
-    console.log(`📡 Fetching client update manifest from ${clientManifestUrl}...`);
+    console.log(`📡 Fetching client update manifest from ${sanitizeForDisplay(clientManifestUrl, 256)}...`);
     let manifestData;
     try {
       manifestData = await fetchJson(
@@ -1025,14 +1572,17 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       const detail = err instanceof Error ? err.message : String(err);
       throw new PairingError(
         'INSTALL_MANIFEST_ERROR',
-        `Could not fetch the client update manifest: ${detail}`
+        `Could not fetch the client update manifest: ${sanitizeForDisplay(detail, 300)}`
       );
     }
     activeRelease = manifestData?.release || manifestData || {};
   } else {
     const manifestOrigin = String(process.env.NC_API_URL || apiBase).replace(/\/$/, '');
     const manifestUrl = updatesUrl || process.env.NC_UPDATES_URL || `${manifestOrigin}/api/updates`;
-    console.log(`📡 Fetching update manifest from ${manifestUrl}...`);
+    // The anonymous manifest controls sha256, size and package URLs; a MITM
+    // over plaintext HTTP could rewrite all three.
+    assertCredentialOrigin(manifestUrl, { label: 'update manifest URL', action: 'fetch' });
+    console.log(`📡 Fetching update manifest from ${sanitizeForDisplay(manifestUrl, 256)}...`);
     let manifestData;
     try {
       manifestData = await fetchJson(manifestUrl);
@@ -1041,10 +1591,10 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       if (/status 401\b/i.test(detail)) {
         throw new PairingError(
           'INSTALL_MANIFEST_ERROR',
-          `Update manifest refused with ADMIN_AUTH_REQUIRED (${detail}). The manifest endpoint is admin-only; run with an enrollment (setup <host_id> <token>) so the release ships with the redemption, then re-run.`
+          `Update manifest refused with ADMIN_AUTH_REQUIRED (${sanitizeForDisplay(detail, 300)}). The manifest endpoint is admin-only; run with an enrollment (setup <host_id> <token>) so the release ships with the redemption, then re-run.`
         );
       }
-      throw new PairingError('INSTALL_MANIFEST_ERROR', `Could not fetch the agent release manifest: ${detail}`);
+      throw new PairingError('INSTALL_MANIFEST_ERROR', `Could not fetch the agent release manifest: ${sanitizeForDisplay(detail, 300)}`);
     }
     if (manifestData && typeof manifestData === 'object' && manifestData.error === 'ADMIN_AUTH_REQUIRED') {
       throw new PairingError(
@@ -1069,6 +1619,15 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
     if (!tarballUrl.startsWith('http://') && !tarballUrl.startsWith('https://')) {
       tarballUrl = new URL(tarballUrl, defaultBaseUrl).toString();
     }
+    let parsedTarballUrl;
+    try {
+      parsedTarballUrl = new URL(tarballUrl);
+    } catch {
+      throw new PairingError('INSTALL_MANIFEST_ERROR', 'Agent package URL is not a valid absolute URL.');
+    }
+    if (parsedTarballUrl.username || parsedTarballUrl.password) {
+      throw new PairingError('INSTALL_MANIFEST_ERROR', 'Agent package URL must not embed user credentials.');
+    }
   } else {
     if (!version) {
       throw new PairingError('INSTALL_MANIFEST_ERROR', 'Unable to determine agent version from update manifest.');
@@ -1076,6 +1635,28 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
     tarballUrl = `${defaultBaseUrl}/releases/client/${encodeURIComponent(version)}/bootstrap.tar.gz`;
   }
 
+  const expectedHash = activeRelease.bootstrap_sha256 ?? activeRelease.sha256;
+  if (typeof expectedHash !== 'string' || expectedHash.length !== 64 || !/^[a-f0-9]{64}$/i.test(expectedHash)) {
+    throw new PairingError('INSTALL_MANIFEST_ERROR', 'Agent release manifest must provide a valid sha256 before downloading or installing.');
+  }
+  const expectedSizeRaw = activeRelease.bootstrap_size_bytes ?? activeRelease.size_bytes;
+  const expectedSize =
+    typeof expectedSizeRaw === 'number'
+      ? expectedSizeRaw
+      : typeof expectedSizeRaw === 'string' && expectedSizeRaw.length > 0 && !/[^0-9]/.test(expectedSizeRaw)
+        ? Number(expectedSizeRaw)
+        : NaN;
+  if (!Number.isSafeInteger(expectedSize) || expectedSize <= 0) {
+    throw new PairingError('INSTALL_MANIFEST_ERROR', 'Agent release manifest must provide a valid positive integer size before downloading or installing.');
+  }
+  const maxPackageBytes = getCliMaxPackageBytes();
+  if (expectedSize > maxPackageBytes) {
+    throw new PairingError(
+      'INSTALL_MANIFEST_ERROR',
+      `Agent package size ${expectedSize} bytes exceeds the maximum supported ${maxPackageBytes} bytes; nothing was downloaded or installed.`
+    );
+  }
+
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nc-install-'));
   const archivePath = path.join(tempDir, 'bootstrap.tar.gz');
 
@@ -1087,58 +1668,66 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
 
   // Identity decision per endpoint: device headers only for the
   // device-authenticated per-client URLs; public release URLs stay bare so
-  // no credential is ever sent where it is not required (or valid).
+  // no credential is ever sent where it is not required (or valid). A
+  // device-authenticated URL that left the trusted origin is refused before
+  // any request, so a hostile manifest cannot redirect the credential.
   let downloadHeaders = {};
   if (isDeviceAuthenticatedPackageUrl(tarballUrl)) {
+    if (!isSameOrigin(tarballUrl, defaultBaseUrl)) {
+      throw new PairingError(
+        'INSTALL_MANIFEST_ERROR',
+        `Agent package URL ${sanitizeForDisplay(tarballUrl, 256)} is not on the trusted origin ${sanitizeForDisplay(defaultBaseUrl, 256)}; refusing to send device credentials.`
+      );
+    }
     if (typeof hostId === 'string' && typeof hostToken === 'string' && hostId && hostToken && privateKey) {
       downloadHeaders = buildDeviceDownloadHeaders({ hostId, hostToken, privateKey }, tarballUrl);
     }
   }
 
   try {
-    console.log(`⬇️ Downloading agent package from ${tarballUrl}...`);
+    console.log(`⬇️ Downloading agent package from ${sanitizeForDisplay(tarballUrl)}...`);
+    const effectiveDownloadTimeoutMs = downloadTimeoutMs ?? getCliDownloadTimeoutMs();
+    let download;
     try {
-      await downloadToFile(tarballUrl, archivePath, downloadHeaders);
+      download = await downloadToFile(tarballUrl, archivePath, downloadHeaders, {
+        maxBytes: getCliMaxPackageBytes(),
+        timeoutMs: effectiveDownloadTimeoutMs
+      });
     } catch (err) {
-      throw new PairingError('INSTALL_DOWNLOAD_ERROR', `Could not download the agent package: ${err.message}`);
-    }
-
-    const expectedHash = activeRelease.bootstrap_sha256 || activeRelease.sha256;
-    const expectedSizeRaw = activeRelease.bootstrap_size_bytes ?? activeRelease.size_bytes;
-    const expectedSize =
-      expectedSizeRaw === undefined || expectedSizeRaw === null ? null : Number(expectedSizeRaw);
-    const archiveBytes = fs.readFileSync(archivePath);
-    if (expectedSize !== null && Number.isFinite(expectedSize)) {
-      if (archiveBytes.length !== expectedSize) {
-        try {
-          fs.unlinkSync(archivePath);
-        } catch {}
+      if (isCliTimeoutError(err)) {
         throw new PairingError(
-          'INSTALL_MANIFEST_ERROR',
-          `Agent package integrity check failed: size mismatch for ${tarballUrl} (expected ${expectedSize} bytes, got ${archiveBytes.length}). The download was discarded; nothing was installed.`
+          'INSTALL_DOWNLOAD_TIMEOUT',
+          `The agent package download from ${sanitizeForDisplay(tarballUrl)} timed out after ${effectiveDownloadTimeoutMs}ms. No archive was installed; check network speed or raise NC_CLI_DOWNLOAD_TIMEOUT_MS (${MIN_CLI_DOWNLOAD_TIMEOUT_MS}-${MAX_CLI_DOWNLOAD_TIMEOUT_MS}), then re-run.`
         );
       }
+      throw new PairingError('INSTALL_DOWNLOAD_ERROR', `Could not download the agent package: ${sanitizeForDisplay(err.message, 300)}. No archive was installed.`);
     }
-    if (expectedHash && /^[a-f0-9]{64}$/i.test(String(expectedHash))) {
-      const actualHash = crypto.createHash('sha256').update(archiveBytes).digest('hex');
-      if (actualHash.toLowerCase() !== String(expectedHash).toLowerCase()) {
-        try {
-          fs.unlinkSync(archivePath);
-        } catch {}
-        throw new PairingError(
-          'INSTALL_MANIFEST_ERROR',
-          `Agent package integrity check failed: sha256 mismatch for ${tarballUrl}. The download was discarded; nothing was installed.`
-        );
-      }
-    } else {
-      console.warn('⚠️ Release manifest lacks a valid sha256; skipping archive integrity check.');
+
+    if (download.bytes !== expectedSize) {
+      try {
+        fs.unlinkSync(archivePath);
+      } catch {}
+      throw new PairingError(
+        'INSTALL_MANIFEST_ERROR',
+        `Agent package integrity check failed: size mismatch for ${sanitizeForDisplay(tarballUrl, 256)} (expected ${expectedSize} bytes, got ${download.bytes}). The download was discarded; nothing was installed.`
+      );
+    }
+    const actualHash = download.sha256;
+    if (actualHash.toLowerCase() !== expectedHash.toLowerCase()) {
+      try {
+        fs.unlinkSync(archivePath);
+      } catch {}
+      throw new PairingError(
+        'INSTALL_MANIFEST_ERROR',
+        `Agent package integrity check failed: sha256 mismatch for ${sanitizeForDisplay(tarballUrl, 256)}. The download was discarded; nothing was installed.`
+      );
     }
 
     console.log('📂 Extracting agent archive...');
     try {
       extractTarball(archivePath, tempDir);
     } catch (err) {
-      throw new PairingError('INSTALL_EXTRACT_ERROR', `Could not extract the agent package: ${err.message}`);
+      throw new PairingError('INSTALL_EXTRACT_ERROR', `Could not extract the agent package: ${sanitizeForDisplay(err.message, 300)}`);
     }
 
     console.log('🚀 Running installation script...');
@@ -1151,7 +1740,7 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       invokeInstaller(scriptPath, root);
     } catch (err) {
       if (err instanceof PairingError) throw err;
-      throw new PairingError('INSTALL_FAILED', `Agent installer failed: ${err.message}. Re-running resumes from the stored host credentials.`);
+      throw new PairingError('INSTALL_FAILED', `Agent installer failed: ${sanitizeForDisplay(err.message, 300)}. Re-running resumes from the stored host credentials.`);
     }
   } finally {
     console.log('🧹 Cleaning up temporary directory...');
@@ -1168,10 +1757,11 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
  * the OAuth enrollment step is skipped and the supplied token is redeemed
  * directly. `installMode` is forwarded to the installer via NC_MODE.
  * Host split: enrollment (OAuth/redeem) uses the auth origin (`baseUrl` /
- * `NC_BASE_URL`); device-channel verification (`/api/clients/*`) uses the
- * agent origin (`apiBase` / `NC_API_URL`). `NC_SERVER_URL` stays the agent
- * server address and never selects the verify host.
- * @param {{ baseUrl?: string, apiBase?: string, oauthToken?: string|null, enrollment?: { host_id: string, enrollment_token: string, server_url?: string }|null, ncRoot?: string, serverUrl?: string, deviceName?: string, platform?: string, installMode?: 'system'|'user', verifyTimeoutMs?: number, verifyIntervalMs?: number, hooks?: { installAgent?: (options: { ncRoot: string, serverUrl: string, release?: Record<string, unknown>|null, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject }) => Promise<void> } }} options
+ * `NC_BASE_URL`); fresh-enrollment verification, installation and the stored
+ * env bind to the enrollment `server_url` (the agent destination the host
+ * credential will actually use), never to the separate NC_API_URL/baseUrl.
+ * Local resume binds verification and installation to the stored NC_SERVER_URL.
+ * @param {{ baseUrl?: string, apiBase?: string, oauthToken?: string|null, enrollment?: { host_id: string, enrollment_token: string, server_url?: string }|null, ncRoot?: string, serverUrl?: string, deviceName?: string, platform?: string, installMode?: 'system'|'user', rootConsent?: boolean|(() => Promise<boolean>), browserBrand?: string, verifyTimeoutMs?: number, verifyIntervalMs?: number, hooks?: { installAgent?: (options: { ncRoot: string, serverUrl: string, release?: Record<string, unknown>|null, hostId?: string, hostToken?: string, rootConsent?: boolean, privateKey?: import('node:crypto').KeyObject }) => Promise<void> } }} options
   */
 export async function pairDeviceAndInstall({
   baseUrl: baseUrlParam = undefined,
@@ -1183,6 +1773,8 @@ export async function pairDeviceAndInstall({
   deviceName = os.hostname(),
   platform = mapEnrollPlatform(),
   installMode = undefined,
+  rootConsent = false,
+  browserBrand = captureBrowserDefaultBrand(),
   verifyTimeoutMs = 45000,
   verifyIntervalMs = 2000,
   hooks = {}
@@ -1200,7 +1792,6 @@ export async function pairDeviceAndInstall({
   }
   const root = ncRoot || getNcRoot();
   const origin = String(baseUrlParam ?? process.env.NC_BASE_URL ?? baseUrl).replace(/\/$/, '');
-  const apiOrigin = String(apiBaseParam ?? process.env.NC_API_URL ?? apiBase).replace(/\/$/, '');
   const defaultServerUrl = serverUrl || process.env.NC_SERVER_URL || 'https://agent.nodecommand.app';
   const envPath = getEnvFilePath(root);
   const keyPath = getDeviceKeyPath(root);
@@ -1209,15 +1800,20 @@ export async function pairDeviceAndInstall({
   const installAgent =
     hooks.installAgent ||
     (async ({ ncRoot: installRoot, serverUrl: installServerUrl, release: installRelease = undefined, hostId: installHostId = undefined, hostToken: installHostToken = undefined, privateKey: installPrivateKey = undefined }) => {
-      await downloadAndInstallAgent({ ncRoot: installRoot, serverUrl: installServerUrl, installMode, release: installRelease, hostId: installHostId, hostToken: installHostToken, privateKey: installPrivateKey });
+      await downloadAndInstallAgent({ ncRoot: installRoot, serverUrl: installServerUrl, installMode, rootConsent: selectedRootConsent, release: installRelease, hostId: installHostId, hostToken: installHostToken, privateKey: installPrivateKey });
     });
+  let selectedRootConsent = false;
 
   // Fast path — idempotent resume: usable host credentials already on disk
   // are verified over the device channel and the installer is resumed. No
   // new enrollment is minted, so a re-run can never orphan a host or hit
   // ENROLLMENT_ALREADY_USED for a token it no longer holds.
   const localEnv = loadValidHostEnv(envPath);
+  assertMatchingHostIdentity(localEnv, enrollment?.host_id);
   if (localEnv) {
+    // Match the agent's HTTP base normalization without dropping a supported
+    // path prefix or redirecting installed credentials to NC_API_URL.
+    const storedServerUrl = localEnv.NC_SERVER_URL.replace(/\/$/, '');
     let localKey = null;
     try {
       localKey = loadDeviceKeyPair(keyPath);
@@ -1228,7 +1824,7 @@ export async function pairDeviceAndInstall({
       const prior = readPairState(statePath);
       try {
         await verifyHostRegistration({
-          apiBase: apiOrigin,
+          apiBase: localEnv.NC_SERVER_URL,
           hostId: localEnv.NC_CLIENT_ID,
           hostToken: localEnv.NC_CLIENT_TOKEN,
           privateKey: localKey.privateKey,
@@ -1241,10 +1837,10 @@ export async function pairDeviceAndInstall({
           return { hostId: localEnv.NC_CLIENT_ID, serverUrl: localEnv.NC_SERVER_URL, resumed: true };
         }
         console.log(`🔁 Resuming installation for host ${localEnv.NC_CLIENT_ID} (stored credentials verified)...`);
-        await installAgent({ ncRoot: root, serverUrl: localEnv.NC_SERVER_URL, hostId: localEnv.NC_CLIENT_ID, hostToken: localEnv.NC_CLIENT_TOKEN, privateKey: localKey.privateKey });
+        await installAgent({ ncRoot: root, serverUrl: storedServerUrl, hostId: localEnv.NC_CLIENT_ID, hostToken: localEnv.NC_CLIENT_TOKEN, privateKey: localKey.privateKey });
         writePairState(statePath, { host_id: localEnv.NC_CLIENT_ID, phase: 'installed' });
         await verifyHostRegistration({
-          apiBase: apiOrigin,
+          apiBase: localEnv.NC_SERVER_URL,
           hostId: localEnv.NC_CLIENT_ID,
           hostToken: localEnv.NC_CLIENT_TOKEN,
           privateKey: localKey.privateKey,
@@ -1254,23 +1850,25 @@ export async function pairDeviceAndInstall({
         writePairState(statePath, { host_id: localEnv.NC_CLIENT_ID, phase: 'verified' });
         return { hostId: localEnv.NC_CLIENT_ID, serverUrl: localEnv.NC_SERVER_URL, resumed: true };
       } catch (err) {
-        // Only a definitive 404 (VERIFY_FAILED) falls through to a fresh
-        // enrollment. A timeout (VERIFY_TIMEOUT) rethrows with the timeout
-        // guidance: wiping stored credentials on a transient stall would
-        // orphan a healthy host identity. The caller reports the stored-
-        // credentials connectivity hint via suggestedActionFor.
+        // Failure at the bound destination is not permission to enroll on
+        // another server or replace this installed host identity.
         if (err instanceof PairingError && err.code === 'VERIFY_FAILED') {
-          // Stored credentials no longer authenticate (rotated, revoked, or
-          // server reset): fall through to a fresh enrollment, which
-          // overwrites the stale files below.
-          console.warn(`⚠️ Stored host credentials no longer verify (${err.code}); requesting a fresh enrollment...`);
-        } else {
-          throw err;
+          throw new PairingError('VERIFY_FAILED', 'The existing host is not registered at its stored server. Preserve host/device credentials and use the existing installation maintenance flow.');
         }
+        throw err;
       }
     }
   }
 
+  const incomplete = readPairState(statePath);
+  if (incomplete?.phase === 'enrolled' && HOST_ID_RE.test(String(incomplete.host_id || ''))) {
+    throw new PairingError('REDEEM_RECOVERY_REQUIRED', 'A previous redemption may have committed without a saved response. Preserve local host/device identity; recover using authorized existing credentials or target management. No automatic remint or initialization replay was attempted.');
+  }
+  // Authentication/preflight precede this fresh-only question. Ask before
+  // minting the five-minute token, or before redeeming an already running one.
+  // Reuse this one literal answer for both signed intent and local installer.
+  selectedRootConsent = (typeof rootConsent === 'function' ? await rootConsent() : rootConsent) === true;
+
   // Fresh enrollment with the OAuth USER token (user authorization only),
   // or the caller-supplied enrollment from `setup <host_id> <token>`.
   let activeEnrollment = enrollment;
@@ -1292,50 +1890,42 @@ export async function pairDeviceAndInstall({
   let agentVersion = null;
   /** @type {Record<string, unknown>|null} */
   let redemptionRelease = null;
-  try {
+  let executionInitialization = null;
+  {
     const redemption = await redeemEnrollment({
       baseUrl: origin,
       hostId,
       enrollmentToken: activeEnrollment.enrollment_token,
-      keyPair
+      keyPair,
+      initialPermission: selectedRootConsent ? 'admin' : 'user'
     });
     hostToken = redemption.client_token;
+    executionInitialization = redemption.execution_initialization ?? null;
     if (redemption.release && typeof redemption.release === 'object') {
       redemptionRelease = /** @type {Record<string, unknown>} */ (redemption.release);
     }
     if (redemption.release?.version) {
       agentVersion = redemption.release.version;
-      console.log(`📦 Release: ${agentVersion}`);
-    }
-  } catch (err) {
-    if (err instanceof PairingError && err.code === 'ENROLLMENT_ALREADY_USED') {
-      // A previous run consumed this token and stored the credentials:
-      // resume from them instead of failing on the single-use rule.
-      const again = loadValidHostEnv(envPath);
-      if (again && again.NC_CLIENT_ID === hostId) {
-        console.log('🔁 Enrollment was already redeemed by an earlier run — resuming from stored credentials...');
-        hostToken = again.NC_CLIENT_TOKEN;
-      } else {
-        throw err;
-      }
-    } else {
-      throw err;
+      console.log(`📦 Release: ${sanitizeForDisplay(agentVersion, 120)}`);
     }
   }
 
   // Host credentials ONLY — the OAuth token is never written here.
   console.log('📝 Creating configuration file...');
-  writeHostEnvFile(envPath, buildHostEnvContent({ serverUrl: enrollServerUrl, hostId, hostToken, clientName: deviceName }));
+  writeHostEnvFile(envPath, buildHostEnvContent({ serverUrl: enrollServerUrl, hostId, hostToken, clientName: deviceName, browserBrand }));
   console.log(`📝 Configuration saved to ${envPath}`);
   writePairState(statePath, { host_id: hostId, phase: 'redeemed' });
 
   console.log('🚀 Installing agent...');
-  await installAgent({ ncRoot: root, serverUrl: enrollServerUrl, release: redemptionRelease, hostId, hostToken, privateKey: keyPair.privateKey });
+  await installAgent({ ncRoot: root, serverUrl: enrollServerUrl, release: redemptionRelease, hostId, hostToken, privateKey: keyPair.privateKey, rootConsent: selectedRootConsent });
   writePairState(statePath, { host_id: hostId, phase: 'installed' });
 
-  console.log('🔍 Verifying host registration...');
+  console.log(`🔍 Verifying host registration at ${sanitizeForDisplay(enrollServerUrl, 256)}...`);
+  // Verify against the origin stored in the env file and used by the installer:
+  // NC_API_URL/baseUrl only authenticated enrollment and is not the destination
+  // this host credential was bound to.
   await verifyHostRegistration({
-    apiBase: apiOrigin,
+    apiBase: enrollServerUrl,
     hostId,
     hostToken,
     privateKey: keyPair.privateKey,
@@ -1343,7 +1933,8 @@ export async function pairDeviceAndInstall({
     intervalMs: verifyIntervalMs
   });
   writePairState(statePath, { host_id: hostId, phase: 'verified' });
-  return { hostId, serverUrl: enrollServerUrl, resumed: false, version: agentVersion };
+  return { hostId, serverUrl: enrollServerUrl, resumed: false, version: agentVersion, rootConsent: selectedRootConsent,
+    privilegeReadiness: selectedRootConsent ? 'pending' : 'unavailable', executionInitialization };
 }
 
 /**
@@ -1381,6 +1972,9 @@ function printCliHelp() {
       '  nodecommand                          pair this machine via the browser device flow',
       '  nodecommand <host_id>                install with a dashboard host id (prompts for the token, hidden input)',
       '  nodecommand setup [host_id token]    install the agent (auto system/user mode; no args = browser device flow)',
+      '  nodecommand setup --user             force a per-user install (never requests sudo/UAC)',
+      '  nodecommand --user                   same as `setup --user`',
+      '  nodecommand [--allow-root-commands]  explicitly request privileged preparation (default No; independent binding required)',
       '  nodecommand uninstall [--yes]        remove the agent from the canonical root (alias: remove)',
       '  nodecommand remove [--yes]           uninstall the agent (asks for confirmation unless --yes)',
       '  nodecommand --diagnostics            preview a redacted diagnostics bundle (dry-run, writes nothing)',
@@ -1487,17 +2081,22 @@ async function main() {
   // form the dashboard and install_command used to emit) to the `setup
   // <host_id> <token>` path instead of silently ignoring the arguments in the
   // device flow.
-  if (isBareEnrollmentInvocation(cliArgs)) {
+  const enrollmentArgs = cliArgs.filter(arg => arg !== '--allow-root-commands' && arg !== '--user');
+  if (isBareEnrollmentInvocation(enrollmentArgs)) {
     await runSetup(cliArgs);
     return;
   }
   // Canonical token-free form: the single-use token is typed at a masked
   // interactive prompt inside runSetup, so it never enters argv (shell
   // history, `ps`, recordings, telemetry).
-  if (isBareHostIdInvocation(cliArgs)) {
+  if (isBareHostIdInvocation(enrollmentArgs)) {
     await runSetup(cliArgs, { allowHostIdOnly: true });
     return;
   }
+  if (enrollmentArgs.length === 0) {
+    await runSetup(cliArgs);
+    return;
+  }
   await runDeviceFlow();
 }
 
@@ -1509,6 +2108,8 @@ async function main() {
  */
 export function suggestedActionFor(code) {
   switch (code) {
+    case 'HOST_ID_MISMATCH':
+      return 'Preserve the existing credentials and use the existing host maintenance flow with its current mode/root. Check the requested host id and installation target before trying enrollment again.';
     case 'ENROLL_NO_OAUTH_TOKEN':
       return 'Re-run `nodecommand setup` without arguments and approve the browser device flow.';
     case 'ENROLL_UNAUTHORIZED':
@@ -1519,7 +2120,10 @@ export function suggestedActionFor(code) {
     case 'PLAN_HOST_LIMIT_EXCEEDED':
       return 'Upgrade the workspace plan or remove an old host, then re-run.';
     case 'ENROLLMENT_ALREADY_USED':
-      return 'Re-run `nodecommand setup` without arguments; it resumes from the stored host credentials.';
+    case 'REDEEM_RECOVERY_REQUIRED':
+    case 'REDEEM_NETWORK_ERROR':
+    case 'REDEEM_UNAUTHORIZED':
+      return 'Preserve host/device identity. Resume only with authorized stored host credentials; otherwise use authenticated target-management recovery. Do not automatically remint or replay initialization after an uncertain redemption.';
     case 'ENROLLMENT_EXPIRED':
     case 'INVALID_ENROLL_TOKEN':
     case 'INVALID_HOST_ID':
@@ -1530,12 +2134,20 @@ export function suggestedActionFor(code) {
       return 'The update manifest is admin-only; run with an enrollment (setup <host_id> <token>) so the release ships with the redemption, or check network connectivity to the agent release host and re-run; stored credentials are reused.';
     case 'INSTALL_DOWNLOAD_ERROR':
       return 'The agent package endpoint requires the device credential issued at redemption; re-run `nodecommand setup <host_id> <token>` to redeem a fresh enrollment, then re-run; stored credentials are reused.';
+    case 'INSTALL_DOWNLOAD_TIMEOUT':
+      return 'The agent package download did not finish within the configured timeout. Check network speed/connectivity or raise NC_CLI_DOWNLOAD_TIMEOUT_MS (30000-3600000), then re-run; stored credentials are reused.';
+    case 'INSECURE_SERVER_URL':
+      return 'Use an https:// server URL. Set NC_ALLOW_INSECURE_HTTP=1 only for an isolated local test.';
     case 'INSTALL_FAILED':
     case 'INSTALL_EXTRACT_ERROR':
     case 'INSTALL_INTEGRITY_ERROR':
       return 'The agent install did not complete; check network connectivity to the agent release host and re-run; stored credentials are reused.';
     case 'VERIFY_TIMEOUT':
       return 'Check connectivity to the server and re-run to verify; credentials are already stored.';
+    case 'SETUP_IN_PROGRESS':
+      return 'Another setup, install or uninstall owns this installation root. Wait for it to finish (or remove a stale lock after confirming no setup is running) and re-run.';
+    case 'HELPER_BINDING_FAILED':
+      return 'Verify NC_ROOT, the protected management response and the signed challenge file, then re-run the binding maintenance; no binding state was changed.';
     default:
       return 'Re-run the command; use `nodecommand --help` for usage.';
   }
@@ -1584,24 +2196,55 @@ function getCliVersion() {
 /**
  * Prints the one-line install summary required after a successful setup:
  * host id, install mode, CLI version, and verification status.
- * @param {{ hostId: string, serverUrl: string, installMode?: 'system'|'user', resumed?: boolean, version?: string|null }} options
+ * @param {{ hostId: string, serverUrl: string, installMode?: 'system'|'user', resumed?: boolean, version?: string|null, rootConsent?: boolean, ncRoot?: string, executionInitialization?: any }} options
  */
-function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null }) {
-  console.log(`\n✅ Setup complete for host ${hostId}${resumed ? ' (resumed)' : ''}.`);
+export function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null, rootConsent = false, ncRoot = undefined, executionInitialization = null }) {
+  console.log(`\n✅ Setup complete for host ${sanitizeForDisplay(hostId, 128)}${resumed ? ' (resumed)' : ''}.`);
   if (installMode) console.log(`installed as ${installMode}`);
-  if (version) console.log(`agent version: ${version}`);
+  if (version) console.log(`agent version: ${sanitizeForDisplay(version, 120)}`);
   console.log(`cli version: ${getCliVersion()}`);
-  console.log(`server: ${serverUrl}`);
+  console.log(`server: ${sanitizeForDisplay(serverUrl, 256)}`);
   console.log('status: agent credentials verified online');
+  if (ncRoot) console.log(`installation root: ${ncRoot}`);
+  console.log('OS execution identity: not verified by this credential check; native service/readiness verification required');
+  console.log('agent runtime: installer-selected; not verified by this credential check (customer global Node/PATH unchanged)');
+  if (resumed) {
+    console.log('execution permission: existing choice preserved; no privilege maintenance performed');
+  } else {
+    console.log(`root command consent: ${rootConsent === true ? 'Yes' : 'No'}`);
+    console.log(`local privilege readiness: ${rootConsent === true ? 'pending independent management approval and protected helper binding' : 'unavailable (not requested)'}`);
+    const receipt = executionInitialization;
+    const fields = ['outcome', 'reason', 'subject_user_id', 'permission'];
+    const reasons = { requested: ['admin_requested'], preserved: ['existing_permission_preserved', 'existing_host_preserved'],
+      defaulted: ['default_user', 'verified_origin_unavailable', 'origin_authority_changed', 'origin_not_owner', 'origin_inactive'] };
+    const closed = receipt && typeof receipt === 'object' && !Array.isArray(receipt) && Object.keys(receipt).length === fields.length &&
+      fields.every(field => Object.hasOwn(receipt, field)) && typeof receipt.outcome === 'string' && typeof receipt.reason === 'string' &&
+      Object.hasOwn(reasons, receipt.outcome) && reasons[receipt.outcome].includes(receipt.reason) &&
+      (receipt.subject_user_id === null || (typeof receipt.subject_user_id === 'string' && receipt.subject_user_id.length > 0)) &&
+      (receipt.subject_user_id !== null || receipt.permission === null);
+    const permission = closed ? receipt.permission : null;
+    const projectionFields = ['requested_permission', 'applied_permission', 'permission_generation', 'permission_revision', 'applied_revision', 'enforcement_state', 'changed_by', 'updated_at'];
+    const projected = permission && typeof permission === 'object' && !Array.isArray(permission) &&
+      Object.keys(permission).length === projectionFields.length && projectionFields.every(field => Object.hasOwn(permission, field)) &&
+      ['user', 'admin'].includes(permission.requested_permission) && [null, 'user', 'admin'].includes(permission.applied_permission) &&
+      [permission.permission_revision, permission.applied_revision].every(value => value === null || (Number.isSafeInteger(value) && value >= 0)) &&
+      [permission.permission_generation, permission.changed_by].every(value => value === null || typeof value === 'string') &&
+      typeof permission.enforcement_state === 'string' && (permission.updated_at === null || typeof permission.updated_at === 'string' || Number.isFinite(permission.updated_at));
+    if (!closed || (permission !== null && !projected)) {
+      console.log('personal execution initialization: unknown (server receipt unavailable or invalid); no User/Admin initialization claimed');
+    } else {
+      console.log(`personal execution initialization: ${receipt.outcome} (${receipt.reason})`);
+      if (!projected) console.log('personal execution permission: unknown (no verified applicable personal record reported)');
+      else {
+        const label = value => value === 'admin' ? 'Admin' : value === 'user' ? 'User' : 'unknown';
+        const state = permission.enforcement_state === 'pending' ? 'pending' : permission.enforcement_state === 'applied' ? 'server-reported applied' : 'not verified';
+        console.log(`personal execution permission: server requested ${label(permission.requested_permission)}; enforcement ${state}`);
+        console.log(`server-reported applied personal permission: ${label(permission.applied_permission)}; local Root enforcement not verified by setup`);
+      }
+    }
+  }
 }
 
-/**
- * Guidance printed when Windows UAC elevation for a system-wide install is
- * unavailable (headless shell) or was declined by the operator.
- */
-const WINDOWS_ELEVATION_INSTALL_DECLINED =
-  'Elevation unavailable or declined. Please run as Administrator in an elevated shell for a system-wide install at C:\\ProgramData\\NC.';
-
 /**
  * Guidance printed when Windows UAC elevation for uninstallation is
  * unavailable (headless shell) or was declined by the operator.
@@ -1615,17 +2258,20 @@ const WINDOWS_ELEVATION_UNINSTALL_DECLINED =
  * console is visible) and returns the spawnSync result. Never throws: a
  * missing powershell or a declined prompt resolves to null/non-zero.
  */
-function requestWindowsElevation() {
-  const args = [...process.argv.slice(1)];
+function requestWindowsElevation(browserBrand = undefined, elevatedArgs = undefined) {
+  const originalArgs = elevatedArgs ? [...elevatedArgs] : [...process.argv.slice(1)];
+  const args = browserBrand === undefined ? originalArgs : browserBrandReexecArgs(originalArgs, browserBrand);
+  const literal = value => "'" + value.replace(/'/g, "''") + "'";
+  const quote = value => '"' + String(value).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1') + '"';
+  const script = `$p=Start-Process -FilePath ${literal(process.execPath)} -ArgumentList ${literal(args.map(quote).join(' '))} -Verb RunAs -Wait -PassThru; exit $p.ExitCode`;
   try {
     return child_process.spawnSync(
-      'powershell',
+      windowsExecutablePath('powershell'),
       [
         '-NoProfile',
-        '-Command',
-        `Start-Process -FilePath "${process.execPath}" -ArgumentList ${args
-          .map((a) => `"${String(a).replace(/"/g, '`"')}"`)
-          .join(',')} -Verb RunAs -Wait`
+        '-NonInteractive',
+        '-EncodedCommand',
+        Buffer.from(script, 'utf16le').toString('base64')
       ],
       { stdio: 'inherit' }
     );
@@ -1638,7 +2284,9 @@ function requestWindowsElevation() {
  * `nodecommand setup [host_id enrollment_token]`.
  *
  * Mode is automatic (never prompted): elevated processes install machine-wide.
- * POSIX: a non-root admin requests sudo; a refusal falls back to a per-user
+ * Fresh non-root macOS installs use the existing user LaunchAgent, including
+ * administrator accounts; existing/conflicting state is checked first.
+ * Linux: a non-root admin requests sudo; a refusal falls back to a per-user
  * install with a single-line capability notice. Windows: a standard shell
  * requests UAC elevation instead and hard-stops (exit 1) when elevation is
  * unavailable or declined — never a silent %LOCALAPPDATA% degradation.
@@ -1655,7 +2303,23 @@ function requestWindowsElevation() {
  * @param {{ allowHostIdOnly?: boolean, promptToken?: (io: { input: import('node:stream').Readable, output: import('node:stream').Writable }) => Promise<string> }} [options]
  */
 export async function runSetup(args = [], { allowHostIdOnly = false, promptToken = promptEnrollmentToken } = {}) {
+  // Elevated legacy enrollments receive the single-use token from an
+  // owner-only temp file, never through sudo/UAC argv.
+  let elevatedToken;
+  const tokenFileFlagIndex = args.indexOf('--enrollment-token-file');
+  if (tokenFileFlagIndex >= 0) {
+    const tokenFile = args[tokenFileFlagIndex + 1];
+    if (typeof tokenFile !== 'string' || tokenFile.startsWith('-')) {
+      reportSetupError(new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file argument is missing.'));
+      process.exit(1);
+      return;
+    }
+    elevatedToken = readEnrollmentTokenFile(tokenFile);
+    args = args.filter((_, index) => index !== tokenFileFlagIndex && index !== tokenFileFlagIndex + 1);
+  }
   const positionals = args.filter((a) => !a.startsWith('-'));
+  if (elevatedToken !== undefined) positionals.push(elevatedToken);
+  const positionalTokenInArgv = elevatedToken === undefined && positionals.length === 2;
   if (positionals.includes('help') || args.includes('--help') || args.includes('-h')) {
     console.log(
       [
@@ -1663,13 +2327,78 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
         '  nodecommand setup                  install via the browser device flow (auto system/user mode)',
         '  nodecommand setup <host_id> <token>  install with a dashboard enrollment token (legacy positional form)',
         '',
-        'The install mode is chosen automatically: administrator/root installs',
-        'machine-wide (system), anything else installs per-user (user).'
+        '  nodecommand setup --maintain-identity <host_id>  explicit root-only selected identity migration (NC_ROOT required)',
+        '  nodecommand setup --configure-helper-binding <host_id> <management_response.json> <signed_challenge.json>',
+        '    --activate-initial-binding explicitly activates only the local initial binding and restarts unsynchronized.',
+        '',
+        'macOS: fresh non-root installs use the per-user LaunchAgent without sudo;',
+        'explicit root uses system mode. Existing roots/modes are preserved or setup stops.',
+        'Windows/Linux retain their existing automatic system/user elevation behavior.',
+        'Use the per-user switch documented by `nodecommand --help` to force a per-user install without sudo/UAC.',
+        'Service installation authorization does not allow root commands through chat.',
+        'New setup asks: Allow root/administrator commands through Node Command? [y/N]',
+        'Noninteractive setup defaults to No; --allow-root-commands explicitly requests preparation.',
+        'Admin stays unavailable until protected helper binding and management approval are verified.'
       ].join('\n')
     );
     return;
   }
-  assertKnownFlags(args, ['--help', '-h'], 'setup');
+  assertKnownFlags(args, ['--help', '-h', '--allow-root-commands', '--user', '--maintain-identity', '--configure-helper-binding', '--activate-initial-binding'], 'setup');
+  // Explicit per-user mode: never elevate, and never degrade silently into a
+  // competing user install beside a system tree the caller cannot inspect.
+  const forceUser = args.includes('--user');
+  if (forceUser && (args.includes('--maintain-identity') || args.includes('--configure-helper-binding'))) {
+    throw new PairingError('INVALID_SETUP_ARGS', '--user selects a per-user installation and cannot be combined with selected-installation maintenance.');
+  }
+  if (args.includes('--configure-helper-binding')) {
+    if (positionals.length !== 3 || !process.env.NC_ROOT || args.includes('--allow-root-commands') || args.includes('--maintain-identity'))
+      throw new PairingError('INVALID_SETUP_ARGS', 'Selected helper binding maintenance needs NC_ROOT, existing host ID, protected management response and signed challenge.');
+    try {
+      const producer = await loadProtectedHelperProducer(process.env.NC_ROOT);
+      const files = producer.protectedHelperPaths(process.env.NC_ROOT);
+      const selected = JSON.parse(fs.readFileSync(files.configFile, 'utf8'));
+      assertMatchingHostIdentity({ NC_CLIENT_ID: selected.client_id }, positionals[0]);
+      const result = await producer.configureProtectedHelperBinding({ root: process.env.NC_ROOT, bindingFile: path.resolve(positionals[1]),
+        challengeFile: path.resolve(positionals[2]), activateLocally: args.includes('--activate-initial-binding') });
+      console.log(JSON.stringify(result));
+      console.log('Local binding preparation is not execution readiness. The control plane must consume fresh proof, then complete signed sync and helper ACK.');
+      return;
+    } catch (err) {
+      // Never surface a raw stack (or JSON.parse input snippets) from helper
+      // binding maintenance; callers get the stable setup error shape.
+      if (err instanceof PairingError) {
+        reportSetupError(err);
+      } else {
+        const detail = err instanceof SyntaxError
+          ? 'the selected protected configuration is not valid JSON'
+          : err instanceof Error ? err.message : String(err);
+        reportSetupError(new PairingError('HELPER_BINDING_FAILED', `Protected helper binding maintenance failed: ${detail}. Existing binding state is unchanged.`));
+      }
+      process.exit(1);
+      return;
+    }
+  }
+  if (args.includes('--activate-initial-binding')) throw new PairingError('INVALID_SETUP_ARGS', 'Initial binding activation requires explicit --configure-helper-binding maintenance.');
+  if (args.includes('--maintain-identity')) {
+    if (positionals.length !== 1 || !process.env.NC_ROOT || args.includes('--allow-root-commands')) throw new PairingError('INVALID_SETUP_ARGS', 'Selected identity maintenance needs NC_ROOT and exactly one existing host ID; root-command consent is a separate operation.');
+    if (!process.stdin.isTTY || !process.stdout.isTTY) throw new PairingError('INSTALL_FAILED', 'Selected identity maintenance requires an interactive operator to confirm exact-host reconnection in authenticated management; no account or service was changed.');
+    console.log('Selected OS identity maintenance preserves the existing personal permission and does not enable root commands through chat.');
+    const result = await maintainLinuxIdentity({ ncRoot: process.env.NC_ROOT, hostId: positionals[0], operatorUser: process.env.NC_OPERATOR_USER,
+      authorizeMaintenance: async facts => {
+        await verifyHostRegistration({ apiBase: facts.server_url, hostId: facts.client_id, hostToken: facts.hostToken, privateKey: facts.privateKey });
+        console.log(`Selected target: ${facts.client_id}; issuer ${facts.server_url}; root ${facts.ncRoot}; device SPKI sha256:${facts.device_key_id}; current OS account ${facts.old_user} (${facts.uid}:${facts.gid}).`);
+        return confirmPrompt('Confirm this exact target is authorized for identity maintenance and is NOT held, in your authenticated management session? [y/N] ');
+      },
+      verifyReconnection: async facts => {
+        await verifyHostRegistration({ apiBase: facts.server_url, hostId: facts.client_id, hostToken: facts.hostToken, privateKey: facts.privateKey });
+        console.log(`Verify host ${facts.client_id} on ${facts.server_url}; device SPKI sha256:${facts.device_key_id}; OS identity nodecommand (${facts.uid}:${facts.gid}); root ${facts.ncRoot}.`);
+        if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+        return confirmPrompt('Confirm this exact host reconnected in your authenticated management session as nodecommand? [y/N] ');
+      } });
+    console.log(`Identity maintenance verified: ${result.client_id}, ${result.ncRoot}, nodecommand (${result.uid}:${result.gid}). Existing personal permission preserved; privileged support unavailable pending independent maintenance/binding.`);
+    if (result.workspace) console.log(`Writable workspace: ${result.workspace}. Additional data/workspace roots require explicit authorized signed policy changes; no login-home ACLs, services or credentials were inherited.`);
+    return;
+  }
   // Arity is validated BEFORE any mode/root output: an invalid invocation
   // must fail without printing an installation plan it will not execute.
   // One positional (host id) is valid only for the bare `nodecommand
@@ -1680,71 +2409,303 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
     console.error('suggested_action: Re-run as `nodecommand setup` or `nodecommand setup <host_id> <token>`.');
     process.exit(1);
   }
-  let installMode = decideInstallMode();
-  // A non-root admin must not silently fall back to a per-user install: the
-  // install root, service scope and privileged helper all differ. POSIX
-  // requests sudo and re-runs elevated; Windows requests UAC (Start-Process
-  // -Verb RunAs) so the install lands machine-wide at the canonical system
-  // root. A refused or unavailable Windows elevation is a hard stop: the CLI
-  // never silently degrades a system install into %LOCALAPPDATA%.
-  if (installMode === 'user' && canElevate() && !process.env.NC_ELEVATED) {
-    if (os.platform() === 'win32') {
-      if (process.stdin.isTTY) {
-        console.log('Admin rights required for a system-wide install. Requesting UAC elevation…');
-        const elevated = requestWindowsElevation();
-        if (elevated && elevated.status === 0) process.exit(0);
+  if (positionalTokenInArgv) {
+    console.warn('warning: [ENROLL_TOKEN_IN_ARGV] The positional enrollment token is visible in shell history and process listings. Re-run without the token to use the masked prompt; continuing with the supplied token.');
+  }
+  const browserBrand = captureBrowserDefaultBrand();
+  let installMode = forceUser ? 'user' : decideInstallMode();
+  let ncRoot;
+  let existingTarget;
+  let existingEnv;
+  let existingKey;
+  let rootManagedPair;
+  let protectedKeyContext;
+  let needsUserAppRepair = false;
+  // A non-root caller cannot stat a root-owned 0750 system tree. Escalate
+  // before setupTarget's fail-closed inspection so the elevated child inspects
+  // the real installation; an unreadable root must never look like "absent".
+  const unreadableSystemRoot = os.platform() === 'linux' && installMode === 'user' && !process.env.NC_ELEVATED
+    ? unreadableSystemInstallations()[0]
+    : undefined;
+  // config + device key alone are not a working agent: an empty/missing
+  // launcher is repaired for a per-user tree from stored credentials, and
+  // otherwise fails closed instead of being reported as an online
+  // installation. Stored credentials are preserved for repair.
+  const verifyExistingTarget = (root, { clientId = null, protectedContext = null, repairUserApplication = false } = {}) => {
+    const localEnv = loadValidHostEnv(getEnvFilePath(root));
+    if (!localEnv) throw new Error(`Existing host configuration at ${root} is incomplete; refusing a new enrollment or credential overwrite.`);
+    if (clientId && localEnv.NC_CLIENT_ID !== clientId) throw new Error('Existing ordinary host identity conflicts with the protected helper selection; explicit Root maintenance is required.');
+    assertMatchingHostIdentity(localEnv, positionals[0]);
+    // Missing/unreadable/invalid keys are not permission to regenerate an
+    // existing device identity. The normal verified resume flow is kept.
+    const keyPath = getDeviceKeyPath(root);
+    if (!protectedContext) {
+      const keyInfo = fs.lstatSync(keyPath);
+      if (!keyInfo.isFile() || keyInfo.isSymbolicLink() || keyInfo.size > 65536 ||
+          (os.platform() !== 'win32' && installMode === 'user' && keyInfo.uid !== process.getuid())) {
+        throw new Error(`Existing device key at ${root} has an unverifiable type/owner; refusing identity replacement.`);
       }
-      console.error(WINDOWS_ELEVATION_INSTALL_DECLINED);
-      process.exit(1);
     }
-    console.log('Admin rights required for a system-wide install. Requesting sudo…');
-    const elevated = child_process.spawnSync(
-      'sudo',
-      ['-E', process.execPath, ...process.argv.slice(1)],
-      { stdio: 'inherit', env: { ...process.env, NC_ELEVATED: '1' } }
-    );
-    if (elevated && elevated.status === 0) process.exit(0);
-    console.warn('Elevation unavailable or declined; continuing with a per-user install.');
+    try {
+      existingKey = protectedContext ? loadRootManagedPairKey(root, protectedContext.ordinaryUid) : loadDeviceKeyPair(keyPath);
+    } catch {
+      throw new Error(`Existing device key at ${root} cannot be verified; preserve it for selected-installation maintenance.`);
+    }
+    existingEnv = localEnv;
+    const appInfo = fs.lstatSync(path.join(root, 'app'));
+    if (!appInfo.isDirectory() || appInfo.isSymbolicLink()) throw new Error(`Existing application at ${root} is incomplete; use selected-installation maintenance.`);
+    const launcherPath = path.join(root, 'app', 'launcher.mjs');
+    let launcherInfo;
+    try {
+      launcherInfo = fs.lstatSync(launcherPath);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw new Error(`Existing application at ${root} cannot be verified; use selected-installation maintenance.`, { cause: err });
+    }
+    if (!launcherInfo || !launcherInfo.isFile() || launcherInfo.isSymbolicLink() || launcherInfo.size === 0) {
+      // A partial per-user tree is repairable in place from the stored host
+      // identity; protected/system roots stay fail-closed for maintenance.
+      if (repairUserApplication && canRepairUserApplication({ mode: installMode, protectedContext })) {
+        needsUserAppRepair = true;
+        return;
+      }
+      throw new Error(`Existing application at ${root} is incomplete: app/launcher.mjs is missing or empty. Repair or reinstall the application from the existing root (config/nc-client.env and config/nc-device-key.pem are preserved); no new enrollment was attempted.`);
+    }
+  };
+  try {
+    if (!unreadableSystemRoot) {
+      const target = setupTarget({ mode: installMode });
+      ({ mode: installMode, ncRoot } = target);
+      existingTarget = target.existing;
+      rootManagedPair = target.rootManagedPair;
+      protectedKeyContext = (process.getuid?.() === 0 || process.geteuid?.() === 0) ? target.protectedInstallation : null;
+      if (target.existing) verifyExistingTarget(ncRoot, { clientId: target.clientId, protectedContext: protectedKeyContext, repairUserApplication: installMode === 'user' && !target.rootManagedPair });
+    } else {
+      // A valid per-user installation is still usable beside an unreadable
+      // system tree: verify it as this user instead of demanding elevation.
+      const userRoot = path.resolve(getNcRootForMode('user'));
+      if (probeInstallRoot(userRoot) === 'install') {
+        verifyExistingTarget(userRoot);
+        installMode = 'user';
+        ncRoot = userRoot;
+        existingTarget = { existing: true, ncRoot: userRoot, mode: 'user' };
+      }
+    }
+  } catch (err) {
+    if (err instanceof PairingError && err.code === 'HOST_ID_MISMATCH') {
+      reportSetupError(err);
+    } else {
+      console.error(`error: [INSTALL_FAILED] ${err instanceof Error ? err.message : 'Cannot verify installation state.'}`);
+      console.error('suggested_action: Preserve the existing mode/root; resolve conflicting state through its existing maintenance flow, with explicit administrator rights for system installs.');
+    }
+    process.exit(1);
+    return;
   }
-  // Mode-aware root: on win32 a system install lives in %ProgramData%\NC,
-  // not the %LOCALAPPDATA% tree getNcRoot() returns, so credentials must be
-  // written where the system installer will actually read them.
-  const ncRoot = getNcRootForMode(installMode);
-  console.log(installMode === 'system' ? `Installing as system (machine-wide), root: ${ncRoot}.` : `Installing as user (per-user), root: ${ncRoot}.`);
-  const warning = modeWarningFor(installMode);
-  if (warning) console.warn(warning);
-
-  // Canonical token-free form: prompt AFTER elevation so the token is typed
-  // on the elevated terminal and never enters argv (a sudo/UAC re-exec
-  // forwards only the host id). Masked input: the token is not echoed.
-  if (onePositionalOk) {
+  if (existingTarget) {
+    // An installed tree is verification-only here, except that a partial
+    // per-user application is repaired from its stored host identity. In
+    // particular, a legacy tree without pairing-state metadata must not rerun
+    // OS installers that can replace shared services/helpers; system/protected
+    // repairs remain selected maintenance. The lock keeps a concurrent
+    // uninstall from removing the tree while this verification reads its
+    // credentials and keys.
+    let lock;
     try {
-      const enrollmentToken = await promptToken({ input: process.stdin, output: process.stderr });
-      positionals.push(String(enrollmentToken || ''));
+      lock = acquireInstallLock(ncRoot);
     } catch (err) {
       reportSetupError(err);
       process.exit(1);
+      return;
+    }
+    try {
+      if (needsUserAppRepair) {
+        // Repair only the application payload from the stored host identity:
+        // no OAuth, no enrollment token and no new device key are involved.
+        console.log(`Repairing the existing user application at ${ncRoot} from stored host credentials (no new enrollment).`);
+        try {
+          await downloadAndInstallAgent({
+            ncRoot,
+            serverUrl: existingEnv.NC_SERVER_URL,
+            installMode: 'user',
+            rootConsent: false,
+            hostId: existingEnv.NC_CLIENT_ID,
+            hostToken: existingEnv.NC_CLIENT_TOKEN,
+            privateKey: existingKey.privateKey
+          });
+        } catch (err) {
+          const detail = err instanceof Error ? err.message : String(err);
+          console.error(`error: [INSTALL_FAILED] Repair of the existing user installation at ${ncRoot} failed: ${detail}`);
+          console.error(`suggested_action: Stored host/device credentials were preserved at ${ncRoot}; resolve the reported download/install problem and re-run setup. No new enrollment was requested.`);
+          process.exit(1);
+          return;
+        }
+      }
+      console.log(`Verifying existing ${rootManagedPair ? 'Root-managed paired' : installMode} installation at ${ncRoot}, host: ${existingEnv.NC_CLIENT_ID}.`);
+      if (rootManagedPair) console.log(`Local management: Root; ordinary service scope: ${rootManagedPair.serviceScope}; selected UID: ${rootManagedPair.ordinaryUid} (credential verification only; no user impersonation).`);
+      try {
+        await verifyHostRegistration({ apiBase: existingEnv.NC_SERVER_URL, hostId: existingEnv.NC_CLIENT_ID, hostToken: existingEnv.NC_CLIENT_TOKEN, privateKey: existingKey.privateKey });
+        printSetupSuccess({ hostId: existingEnv.NC_CLIENT_ID, serverUrl: existingEnv.NC_SERVER_URL, installMode: rootManagedPair ? undefined : installMode, ncRoot, resumed: true });
+        if (needsUserAppRepair) console.log('repair: application reinstalled from stored host credentials; host identity preserved.');
+        if (args.includes('--allow-root-commands')) console.warn('Existing root consent unchanged. Enabling root requires explicit selected-installation privileged maintenance and independent management approval.');
+      } catch (err) {
+        const code = err instanceof PairingError ? err.code : 'INSTALL_FAILED';
+        const detail = code === 'VERIFY_FAILED' ? 'The existing host is not registered on the server; stored identity is unchanged.' : err.message;
+        console.error(`error: [${code}] ${detail}`);
+        console.error(`suggested_action: Preserve host/device credentials at ${ncRoot}; use this installation's maintenance flow to repair registration or connectivity. No new enrollment was requested.`);
+        process.exit(1);
+      }
+    } finally {
+      lock.release();
     }
+    return;
   }
-
-  if (positionals.length === 2) {
-    const [hostId, enrollmentToken] = positionals;
+  // macOS has already resolved its user/system boundary without automatic
+  // elevation. Linux requests sudo; Windows requests UAC (Start-Process
+  // -Verb RunAs) so the install lands machine-wide at the canonical system
+  // root. A refused or unavailable Windows elevation is a hard stop: the CLI
+  // never silently degrades a system install into %LOCALAPPDATA%. An
+  // unreadable canonical system installation also forces this branch: without
+  // elevation it is unknowable and must not become a per-user competitor.
+  if (unreadableSystemRoot && (forceUser || !canElevate())) {
+    console.error(`error: [INSTALL_FAILED] An existing system installation at ${unreadableSystemRoot} cannot be inspected without administrator rights.`);
+    console.error(forceUser
+      ? 'suggested_action: --user cannot create a per-user installation beside it; re-run without --user with Administrator/root rights so the existing installation can be inspected. No per-user installation was created.'
+      : 'suggested_action: Re-run this setup with Administrator/root rights so the existing installation can be inspected; no per-user installation was created beside it.');
+    process.exit(1);
+    return;
+  }
+  if (!forceUser && os.platform() !== 'darwin' && installMode === 'user' && canElevate() && !process.env.NC_ELEVATED) {
+    // A legacy positional token must never enter sudo/UAC argv: it travels in
+    // a 0600 owner-only temp file whose path alone is re-executed.
+    const tokenFile = positionals.length === 2 ? createEnrollmentTokenFile(positionals[1]) : null;
+    const elevatedArgs = tokenFile
+      ? buildElevatedSetupArgs(process.argv.slice(1), args, args.lastIndexOf(positionals[1]), tokenFile.filePath)
+      : undefined;
     try {
-      const result = await pairDeviceAndInstall({
-        baseUrl,
-        apiBase,
-        enrollment: { host_id: hostId, enrollment_token: enrollmentToken },
-        installMode,
-        ncRoot
-      });
-      printSetupSuccess({ hostId: result.hostId, serverUrl: result.serverUrl, installMode, resumed: result.resumed, version: result.version });
+      if (os.platform() === 'win32') {
+        if (process.stdin.isTTY) {
+          console.log('Admin rights required for a system-wide install. Requesting UAC elevation…');
+          const elevated = requestWindowsElevation(browserBrand, elevatedArgs);
+          if (elevated && elevated.status === 0) {
+            tokenFile?.cleanup();
+            process.exit(0);
+          }
+        }
+        console.error('error: [INSTALL_FAILED] Elevation was unavailable or declined; no system-wide installation was performed and no per-user fallback was attempted.');
+        console.error('suggested_action: Re-run `nodecommand setup --user` for a per-user installation, or run as Administrator in an elevated shell for a system-wide install at C:\\ProgramData\\NC.');
+        process.exit(1);
+      }
+      console.log('Admin rights required for a system-wide install. Requesting sudo…');
+      // Preserve only the single signal the elevated re-exec depends on; sudo
+      // resets the rest of the environment instead of forwarding it wholesale.
+      // The caller's PATH is never forwarded into the privileged re-exec.
+      const elevationEnv = {
+        PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+        NC_ELEVATED: '1'
+      };
+      if (process.env.TERM) elevationEnv.TERM = process.env.TERM;
+      let sudo;
+      try {
+        sudo = resolveExecutable('sudo');
+      } catch (err) {
+        console.error(`error: [INSTALL_FAILED] ${err.message}`);
+        console.error('suggested_action: Install an absolute sudo binary or run the system installer explicitly with administrator rights; no per-user fallback was attempted for an unsafe elevation path.');
+        process.exit(1);
+      }
+      const elevated = child_process.spawnSync(
+        sudo,
+        ['--preserve-env=NC_ELEVATED', process.execPath, ...(elevatedArgs ?? process.argv.slice(1))],
+        { stdio: 'inherit', env: elevationEnv }
+      );
+      if (elevated && elevated.status === 0) {
+        tokenFile?.cleanup();
+        process.exit(0);
+      }
+    } finally {
+      tokenFile?.cleanup();
+    }
+    if (unreadableSystemRoot) {
+      console.error(`error: [INSTALL_FAILED] The elevated setup did not inspect or repair the existing system installation at ${unreadableSystemRoot}.`);
+      console.error('suggested_action: Preserve the existing system tree and re-run the system installer with explicit administrator rights; no per-user installation was attempted.');
+      process.exit(1);
+    }
+    try {
+      // A failed elevated child may already have created an installation.
+      // Recheck before reporting the failure rather than creating a competing
+      // agent; a partially completed system install must be preserved.
+      const target = setupTarget({ mode: installMode });
+      if (target.existing) throw new Error(`An installation now exists at ${target.ncRoot}; preserve it through its maintenance flow.`);
     } catch (err) {
-      reportSetupError(err);
+      console.error(`error: [INSTALL_FAILED] ${err.message}`);
+      console.error('suggested_action: Preserve existing roots and select their maintenance flow; declining elevation does not authorize a second installation.');
       process.exit(1);
+      return;
     }
+    // No silent fallback after an attempted elevation: a per-user install here
+    // would compete with the expected system install and could prompt for a
+    // second enrollment token in the same run. Fail closed instead.
+    console.error('error: [INSTALL_FAILED] Elevation was unavailable or declined; no system-wide installation was performed and no per-user fallback was attempted.');
+    console.error('suggested_action: Re-run `nodecommand setup --user` for a per-user installation, or provide administrator/root rights for a machine-wide installation.');
+    process.exit(1);
     return;
   }
-  await runDeviceFlow({ installMode, ncRoot });
+  // Mode-aware root: on win32 a system install lives in %ProgramData%\NC,
+  // not the %LOCALAPPDATA% tree getNcRoot() returns, so credentials must be
+  // written where the system installer will actually read them.
+  ncRoot = ncRoot || getNcRootForMode(installMode);
+  // Serialize credential/key writes and the installer against any concurrent
+  // setup or uninstall for this root.
+  const lock = acquireInstallLock(ncRoot);
+  try {
+    console.log(installMode === 'system' ? `Installing as system (machine-wide), root: ${ncRoot}.` : `Installing as user (per-user), root: ${ncRoot}.`);
+    const warning = modeWarningFor(installMode);
+    if (warning) console.warn(warning);
+
+    // Canonical token-free form: prompt AFTER elevation so the token is typed
+    // on the elevated terminal and never enters argv (a sudo/UAC re-exec
+    // forwards only the host id). Masked input: the token is not echoed.
+    if (onePositionalOk) {
+      try {
+        assertMatchingHostIdentity(loadValidHostEnv(getEnvFilePath(ncRoot)), positionals[0]);
+        const enrollmentToken = await promptToken({ input: process.stdin, output: process.stderr });
+        positionals.push(String(enrollmentToken || ''));
+      } catch (err) {
+        reportSetupError(err);
+        process.exit(1);
+      }
+    }
+
+    const rootConsent = () => promptRootCommandConsent({ explicitOptIn: args.includes('--allow-root-commands') });
+    if (positionals.length === 2) {
+      const [hostId, enrollmentToken] = positionals;
+      try {
+        const result = await pairDeviceAndInstall({
+          baseUrl,
+          apiBase,
+          enrollment: { host_id: hostId, enrollment_token: enrollmentToken },
+          browserBrand,
+          installMode,
+          rootConsent,
+          ncRoot
+        });
+        printSetupSuccess({ ...result, installMode, ncRoot });
+      } catch (err) {
+        reportSetupError(err);
+        process.exit(1);
+      }
+      return;
+    }
+    await runDeviceFlow({ installMode, ncRoot, browserBrand, rootConsent });
+  } finally {
+    lock.release();
+  }
+}
+
+export const ROOT_COMMAND_CONSENT_PROMPT = 'Allow root/administrator commands through Node Command? [y/N]';
+
+export async function promptRootCommandConsent({ explicitOptIn = false, input = process.stdin, output = process.stdout, confirm = confirmPrompt } = {}) {
+  if (explicitOptIn === true) return true;
+  if (!input.isTTY || !output.isTTY) return false;
+  return (await confirm(ROOT_COMMAND_CONSENT_PROMPT + ' ')) === true;
 }
 
 /**
@@ -1777,6 +2738,9 @@ export function promptEnrollmentToken({ input = process.stdin, output = process.
       );
       return;
     }
+    // Non-secret guidance: the operator must know paste/Enter are honored even
+    // though no character is echoed. The token itself is never rendered.
+    output.write('Paste the enrollment token from the dashboard. Input is hidden (nothing is echoed); press Enter to submit.\n');
     output.write(ENROLLMENT_TOKEN_PROMPT);
     const sink = new Writable({ write(_chunk, _encoding, callback) { callback(); } });
     sink.isTTY = true;
@@ -1801,16 +2765,19 @@ export function promptEnrollmentToken({ input = process.stdin, output = process.
       close();
       reject(new PairingError('ENROLL_TOKEN_REQUIRED', message));
     };
-    rl.on('SIGINT', () => abort('Enrollment token entry was cancelled.'));
+    rl.on('SIGINT', () => abort('Enrollment token entry was cancelled; nothing was submitted.'));
     rl.on('close', () => {
-      if (!settled) abort('No enrollment token was entered (terminal closed). Re-run in a terminal and paste the token from the dashboard.');
+      if (!settled) abort('No enrollment token was entered (terminal closed); nothing was submitted. Re-run in a terminal and paste the token from the dashboard.');
     });
     rl.question('', (answer) => {
       const token = String(answer ?? '').trim();
       if (!token) {
-        abort('No enrollment token was entered. Re-run in a terminal and paste the token shown in the dashboard.');
+        abort('No enrollment token was entered; nothing was submitted. Re-run in a terminal and paste the token shown in the dashboard.');
         return;
       }
+      // Length-only acknowledgement: confirms the paste/Enter pair was received
+      // without revealing any token byte.
+      output.write(`Enrollment token received (${token.length} characters). Validating...\n`);
       finish(token);
     });
   });
@@ -1853,8 +2820,8 @@ export function confirmPrompt(question, openInterface = null) {
  * tree is executed (never a downloaded copy) and its exit status is reported.
  * Target discovery is centered on the canonical root (candidateInstallRoots
  * lists it first) and treats an unreadable system tree as installed, so a
- * non-root shell routes it to the elevated uninstaller instead of reporting
- * "nothing to remove".
+ * non-root shell reports trusted maintenance as required instead of falsely
+ * reporting "nothing to remove". Discovery never authorizes root execution.
  * @param {string[]} args
  * @param {{ command: string, emptyMessage: string, elevateOnWindows?: boolean, completionMessage: string }} options
  */
@@ -1866,12 +2833,19 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
   assertKnownFlags(args, ['--yes', '-y', '--help', '-h'], command);
   const stray = args.filter((a) => !a.startsWith('-') && a !== 'help');
   if (stray.length > 0) {
-    console.error(`error: [UNKNOWN_ARGUMENT] \`${command}\` takes no positional arguments (got: ${stray.join(', ')}).`);
+    console.error(`error: [UNKNOWN_ARGUMENT] \`${command}\` takes no positional arguments (got ${stray.length}).`);
     console.error(`suggested_action: Run \`nodecommand ${command} --yes\` (or plain \`nodecommand ${command}\` to be asked).`);
     process.exit(1);
   }
   const yes = args.includes('--yes') || args.includes('-y');
-  const { install, unreadable } = findRemovalTargets();
+  let discovery;
+  try { discovery = findRemovalTargets(); } catch (err) {
+    console.error(`error: [TRUSTED_ROOT_MAINTENANCE_REQUIRED] ${err.message}`);
+    console.error(uninstallFailureSuggestion());
+    process.exit(1);
+    return;
+  }
+  const { install, unreadable, paired = [] } = discovery;
   const targets = [...install, ...unreadable];
   if (targets.length === 0) {
     console.log(emptyMessage);
@@ -1880,7 +2854,7 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
   // Windows: a machine-wide tree at C:\ProgramData\NC cannot be removed from
   // a standard shell — request UAC (Start-Process -Verb RunAs) and re-run this
   // same command elevated. Declined or headless elevation is a hard stop.
-  if (elevateOnWindows && os.platform() === 'win32' && !isElevated()) {
+  if (elevateOnWindows && os.platform() === 'win32' && targets.some((root) => !isUserInstallRoot(root)) && !isElevated()) {
     if (process.stdin.isTTY) {
       console.log('Admin rights required to remove the system-wide agent. Requesting UAC elevation…');
       const elevated = requestWindowsElevation();
@@ -1889,7 +2863,16 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
     console.error(WINDOWS_ELEVATION_UNINSTALL_DECLINED);
     process.exit(1);
   }
-  console.log(`Found Node Command installation(s): ${targets.join(', ')}`);
+  console.log(`Found Node Command installation(s): ${targets.map(root => {
+    const pair = paired.find(selected => selected.ncRoot === root);
+    return pair ? pair.helperRoot === root ? `${root} (co-located protected helper)` : `${root} (paired protected helper: ${pair.helperRoot})` : root;
+  }).join(', ')}`);
+  if (paired.length && (os.platform() !== 'linux' || process.getuid?.() !== 0 || process.geteuid?.() !== 0)) {
+    console.error('error: [TRUSTED_ROOT_MAINTENANCE_REQUIRED] Paired Linux removal requires explicitly invoked real/effective Root maintenance. No elevation or ordinary-script fallback was attempted; both roots and lifecycle records are preserved.');
+    console.error(uninstallFailureSuggestion());
+    process.exit(1);
+    return;
+  }
   if (unreadable.length > 0) {
     console.log(
       `Elevated removal needed for system install(s): ${unreadable.join(', ')} (not readable as the current user).`
@@ -1909,36 +2892,64 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
   }
   let failed = 0;
   for (const root of install) {
-    const script = uninstallerForRoot(root);
-    if (!fs.existsSync(script)) {
+    const pair = paired.find(selected => selected.ncRoot === root);
+    const script = pair ? LINUX_PAIRED_UNINSTALL_ENTRY : uninstallerForRoot(root);
+    if (!pair && !fs.existsSync(script)) {
       console.error(`error: [UNINSTALLER_MISSING] uninstaller not found at ${script}; skipping ${root}.`);
-      console.error('suggested_action: Remove the directory manually after stopping the agent service.');
+      console.error(uninstallFailureSuggestion());
+      failed += 1;
+      continue;
+    }
+    let lock;
+    try {
+      lock = acquireInstallLock(root);
+    } catch (err) {
+      reportSetupError(err);
       failed += 1;
       continue;
     }
     try {
       runUninstallerScript(script);
-      console.log(`Removed ${root} (exit 0).`);
+      console.log(`Removed ${root}${pair && pair.helperRoot !== root ? ` and paired protected helper ${pair.helperRoot}` : ''} (exit 0).`);
     } catch (err) {
       const rc = typeof err?.status === 'number' ? err.status : 1;
       console.error(`error: [UNINSTALL_FAILED] uninstaller for ${root} exited with status ${rc}: ${err.message}`);
       console.error(uninstallFailureSuggestion());
+      if (pair) {
+        process.exit(rc || 1);
+        return;
+      }
       failed += 1;
+    } finally {
+      lock.release();
     }
   }
-  // Unreadable (system) roots: the local tree cannot be stat'ed, so the
-  // uninstaller's presence is validated by the elevated run itself — the
-  // in-tree script refuses non-NC directories before deleting anything.
+  // Unreadable system roots remain visible, but never trigger implicit sudo.
   for (const root of unreadable) {
     const script = uninstallerForRoot(root);
+    let lock = null;
+    try {
+      lock = acquireInstallLock(root);
+    } catch (err) {
+      if (err instanceof PairingError && err.code === 'SETUP_IN_PROGRESS') {
+        reportSetupError(err);
+        failed += 1;
+        continue;
+      }
+      // Best effort: an unreadable system root usually cannot host a writable
+      // lock from an ordinary caller. The privileged uninstaller remains the
+      // authority; do not turn a lock-permission failure into a false refusal.
+    }
     try {
       runUninstallerScript(script);
-      console.log(`Removed ${root} (elevated, exit 0).`);
+      console.log(`Removed ${root} (exit 0).`);
     } catch (err) {
       const rc = typeof err?.status === 'number' ? err.status : 1;
-      console.error(`error: [UNINSTALL_FAILED] elevated uninstaller for ${root} exited with status ${rc}: ${err.message}`);
+      console.error(`error: [UNINSTALL_FAILED] uninstaller for ${root} exited with status ${rc}: ${sanitizeForDisplay(err.message, 300)}`);
       console.error(uninstallFailureSuggestion());
       failed += 1;
+    } finally {
+      lock?.release();
     }
   }
   if (failed > 0) process.exit(1);
@@ -1953,6 +2964,8 @@ export async function runRemove(args = []) {
   return runRemoval(args, {
     command: 'remove',
     emptyMessage: 'No Node Command installation found (nothing to remove).',
+    // remove is the legacy uninstall alias and must share its UAC path.
+    elevateOnWindows: true,
     completionMessage: 'Remove complete.'
   });
 }
@@ -1981,10 +2994,11 @@ export async function runUninstall(args = []) {
 /**
  * Browser device flow + enroll/redeem/install/verify. Extracted verbatim from
  * the historical bare-invocation path; `setup` reuses it with an explicit
- * install mode while bare `nodecommand` keeps the previous behavior.
- * @param {{ installMode?: 'system'|'user' }} [options]
+ * install mode; plain `nodecommand` now uses the same setup preflight.
+ * @param {{ installMode?: 'system'|'user', ncRoot?: string, browserBrand?: string, rootConsent?: boolean|(() => Promise<boolean>) }} [options]
  */
-async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {}) {
+async function runDeviceFlow({ installMode = undefined, ncRoot = undefined, browserBrand = captureBrowserDefaultBrand(), rootConsent = false } = {}) {
+  assertCredentialOrigin(baseUrl, { label: 'NC_BASE_URL' });
   const deviceEndpoint = `${baseUrl}/oauth/device/code`;
   let initRes;
 
@@ -2001,17 +3015,20 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
   try {
     initRes = await postJson(deviceEndpoint, {
       client_id: clientId,
+      // B4: scope is an explicit client request, never a server default.
+      // nc-cli enrollment/install needs the write/admin surface.
+      scope: 'mcp:all',
       code_challenge: deviceCodeChallenge,
       code_challenge_method: 'S256'
     });
   } catch (err) {
-    console.error(`error: [DEVICE_FLOW_CONNECT] Could not connect to ${deviceEndpoint}: ${err.message}`);
+    console.error(`error: [DEVICE_FLOW_CONNECT] Could not connect to ${sanitizeForDisplay(deviceEndpoint, 256)}: ${sanitizeForDisplay(err.message, 300)}`);
     console.error('suggested_action: Check network access to the control plane (or NC_BASE_URL), then re-run.');
     process.exit(1);
   }
 
   if (initRes.status !== 200 || !initRes.data || !initRes.data.device_code) {
-    const err = initRes.data?.error_description || initRes.data?.error || `HTTP ${initRes.status}`;
+    const err = sanitizeForDisplay(initRes.data?.error_description || initRes.data?.error || `HTTP ${initRes.status}`, 300);
     console.error(`error: [DEVICE_FLOW_START] Failed to start device flow: ${err}`);
     console.error('suggested_action: Re-run the command; if it persists, verify the control plane is reachable and NC_BASE_URL is correct.');
     process.exit(1);
@@ -2039,7 +3056,8 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
   // has a manual 8-character code input; the deep-link form is useless here
   // because the login redirect strips the query (return_to=/device only), so
   // the code would never auto-fill after sign-in anyway.
-  const verifyUrl = verification_uri || `${baseUrl}/device`;
+  const verifyUrl = sanitizeForDisplay(verification_uri || `${baseUrl}/device`, 512);
+  const displayUserCode = sanitizeForDisplay(user_code, 64);
 
   printBox([
     { text: `${bold}Node Command — Device Authorization${reset}`, rawLength: 'Node Command — Device Authorization'.length },
@@ -2047,7 +3065,7 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
     { text: 'To complete pairing, open this URL in your browser:', rawLength: 'To complete pairing, open this URL in your browser:'.length },
     { text: `${cyan}${bold}${verifyUrl}${reset}`, rawLength: verifyUrl.length },
     { text: '', rawLength: 0 },
-    { text: `Then enter this code on the page: ${yellow}${bold}${user_code}${reset}`, rawLength: `Then enter this code on the page: ${user_code}`.length },
+    { text: `Then enter this code on the page: ${yellow}${bold}${displayUserCode}${reset}`, rawLength: `Then enter this code on the page: ${displayUserCode}`.length },
     { text: '', rawLength: 0 },
     { text: `${dim}Waiting for approval in browser...${reset}`, rawLength: 'Waiting for approval in browser...'.length }
   ]);
@@ -2092,12 +3110,14 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
         const oauthToken = tokenRes.data.access_token;
         console.log('\n🔓 Browser approval received. Enrolling this machine...');
         try {
-          const result = await pairDeviceAndInstall({ baseUrl, apiBase, oauthToken, installMode, ncRoot });
+          const result = await pairDeviceAndInstall({ baseUrl, apiBase, oauthToken, installMode, ncRoot, browserBrand, rootConsent });
           if (installMode) {
             // `setup` reports the structured success block (host, mode,
             // versions, online status); bare `nodecommand` keeps the legacy
             // pairing messages below.
             printSetupSuccess({
+              ...result,
+              ncRoot,
               hostId: result.hostId,
               serverUrl: result.serverUrl,
               installMode,
@@ -2126,7 +3146,7 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
         currentIntervalMs += 5000;
       } else {
         // Any fatal error (expired_token, access_denied, invalid_grant, etc.)
-        const errMsg = tokenRes.data?.error_description || tokenRes.data?.error || `HTTP ${tokenRes.status}`;
+        const errMsg = sanitizeForDisplay(tokenRes.data?.error_description || tokenRes.data?.error || `HTTP ${tokenRes.status}`, 300);
         console.error(`\nerror: [DEVICE_FLOW_AUTH_DENIED] Authorization failed: ${errMsg}`);
         console.error('suggested_action: Re-run the command and approve the prompt in the browser.');
         process.exit(1);
@@ -2137,7 +3157,7 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
       consecutiveNetErrors += 1;
       if (consecutiveNetErrors >= MAX_NET_ERROR_RETRIES) {
         const detail = pollErr instanceof Error ? pollErr.message : String(pollErr);
-        console.error(`\nerror: [DEVICE_FLOW_CONNECT] Could not reach ${tokenEndpoint} after ${consecutiveNetErrors} attempts: ${detail}`);
+        console.error(`\nerror: [DEVICE_FLOW_CONNECT] Could not reach ${sanitizeForDisplay(tokenEndpoint, 256)} after ${consecutiveNetErrors} attempts: ${sanitizeForDisplay(detail, 300)}`);
         console.error('suggested_action: Check network access to the control plane (or NC_BASE_URL), then re-run.');
         process.exit(1);
       }
@@ -2160,5 +3180,8 @@ const isMainModule = () => {
 };
 
 if (isMainModule()) {
-  main();
+  main().catch((err) => {
+    reportSetupError(err);
+    process.exitCode = 1;
+  });
 }