node-command 2.0.1 → 2.0.3

package/bin/nc.mjs

@@ -8,14 +8,23 @@ 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 { fileURLToPath } from 'node:url';
 import {
   canElevate,
+  captureBrowserDefaultBrand,
+  normalizeBrowserBrand,
+  browserBrandReexecArgs,
   decideInstallMode,
   findRemovalTargets,
   getNcRootForMode,
   installerEnvForMode,
   isElevated,
+  isUserInstallRoot,
+  setupTarget,
+  maintainLinuxIdentity,
+  loadProtectedHelperProducer,
+  LINUX_PAIRED_UNINSTALL_ENTRY,
   modeWarningFor,
   runUninstallerScript,
   uninstallFailureSuggestion,
@@ -28,8 +37,9 @@ 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';
@@ -531,9 +541,9 @@ export function getEnrollStatePath(ncRoot = getNcRoot()) {
  * 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() }) {
+export function buildHostEnvContent({ serverUrl, hostId, hostToken, clientName = os.hostname(), browserBrand = 'unknown' }) {
   if (typeof serverUrl !== 'string' || !serverUrl) {
     throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config without a server URL.');
   }
@@ -555,6 +565,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';
 }
@@ -610,6 +621,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
@@ -715,6 +735,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
@@ -851,14 +917,15 @@ 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';
+  const redeemPath = `/api/enroll/redeem?initial_permission=${initialPermission}`;
   const proof = createDeviceProofCli({
     privateKey: keyPair.privateKey,
     hostId,
@@ -874,7 +941,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;
@@ -890,7 +957,7 @@ export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPa
   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) {
@@ -900,7 +967,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.`);
 }
@@ -911,8 +978,9 @@ 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
@@ -976,11 +1044,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 }} 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 } = {}) {
   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;
@@ -1075,6 +1143,21 @@ 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 tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nc-install-'));
   const archivePath = path.join(tempDir, 'bootstrap.tar.gz');
 
@@ -1102,35 +1185,25 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       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 {}
-        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.`
-        );
-      }
+    if (archiveBytes.length !== expectedSize) {
+      try {
+        fs.unlinkSync(archivePath);
+      } catch {}
+      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.`
+      );
     }
-    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.');
+    const actualHash = crypto.createHash('sha256').update(archiveBytes).digest('hex');
+    if (actualHash.toLowerCase() !== 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.`
+      );
     }
 
     console.log('📂 Extracting agent archive...');
@@ -1168,9 +1241,9 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
  * 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
+ * agent origin (`apiBase` / `NC_API_URL`) for fresh enrollment. Local resume
+ * binds verification and installation requests 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,
@@ -1182,6 +1255,8 @@ export async function pairDeviceAndInstall({
   deviceName = os.hostname(),
   platform = mapEnrollPlatform(),
   installMode = undefined,
+  rootConsent = false,
+  browserBrand = captureBrowserDefaultBrand(),
   verifyTimeoutMs = 45000,
   verifyIntervalMs = 2000,
   hooks = {}
@@ -1208,15 +1283,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);
@@ -1227,7 +1307,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,
@@ -1240,10 +1320,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,
@@ -1253,23 +1333,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;
@@ -1291,14 +1373,17 @@ 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);
     }
@@ -1306,30 +1391,16 @@ export async function pairDeviceAndInstall({
       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;
-    }
   }
 
   // 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...');
@@ -1342,7 +1413,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 };
 }
 
 /**
@@ -1378,7 +1450,9 @@ function printCliHelp() {
       '',
       'Usage:',
       '  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 [--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)',
@@ -1404,8 +1478,8 @@ function printCliHelp() {
 
 /**
  * True when the invocation is exactly the bare enrollment form
- * `nodecommand <host_id> <token>` — the shape emitted by the dashboard and
- * the control-plane install_command (`npx node-command <host_id> <token>`).
+ * `nodecommand <host_id> <token>` — the legacy positional shape accepted for
+ * backward compatibility with already-published dashboards and docs.
  *
  * Exactly two non-flag arguments with plausible shapes route to the same path
  * as `setup <host_id> <token>`. The guards stay deliberately loose (host id
@@ -1425,6 +1499,25 @@ export function isBareEnrollmentInvocation(args = []) {
   return hostId.length >= 3 && token.length >= 8;
 }
 
+/**
+ * True when the invocation is exactly the token-free enrollment form
+ * `nodecommand <host_id>` — the canonical shape the control-plane
+ * install_command emits. The single-use token is NOT accepted on the command
+ * line for this form: runSetup prompts for it with masked (non-echoing)
+ * input, so it never lands in argv, shell history, `ps`, terminal
+ * recordings, or telemetry.
+ *
+ * Only a canonical host id (`nc_<64hex>`) qualifies: a stray single word
+ * keeps its previous behavior (browser device flow) instead of being
+ * misread as an enrollment.
+ * @param {string[]} args
+ */
+export function isBareHostIdInvocation(args = []) {
+  if (!Array.isArray(args) || args.length !== 1) return false;
+  const [hostId] = args;
+  return typeof hostId === 'string' && !hostId.startsWith('-') && HOST_ID_RE.test(hostId);
+}
+
 async function main() {
   const cliArgs = process.argv.slice(2);
   // Subcommands route FIRST: otherwise `setup --diagnostics` or a stray flag
@@ -1462,10 +1555,23 @@ async function main() {
     if (!result.ok) process.exit(1);
     return;
   }
-  // Bare enrollment: route `nodecommand <host_id> <token>` (the form the
-  // dashboard and install_command emit) to the `setup <host_id> <token>`
-  // path instead of silently ignoring the arguments in the device flow.
-  if (isBareEnrollmentInvocation(cliArgs)) {
+  // Bare enrollment: route `nodecommand <host_id> <token>` (legacy positional
+  // 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.
+  const enrollmentArgs = cliArgs.filter(arg => arg !== '--allow-root-commands');
+  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(enrollmentArgs)) {
+    await runSetup(cliArgs, { allowHostIdOnly: true });
+    return;
+  }
+  if (enrollmentArgs.length === 0) {
     await runSetup(cliArgs);
     return;
   }
@@ -1480,6 +1586,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':
@@ -1490,11 +1598,16 @@ 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':
       return 'Re-run `nodecommand setup` without arguments for a fresh enrollment.';
+    case 'ENROLL_TOKEN_REQUIRED':
+      return 'Re-run in an interactive terminal so the token can be typed with hidden input, or pass the token as the second argument.';
     case 'INSTALL_MANIFEST_ERROR':
       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':
@@ -1553,15 +1666,53 @@ 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 }) {
+export function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null, rootConsent = false, ncRoot = undefined, executionInitialization = null }) {
   console.log(`\n✅ Setup complete for host ${hostId}${resumed ? ' (resumed)' : ''}.`);
   if (installMode) console.log(`installed as ${installMode}`);
   if (version) console.log(`agent version: ${version}`);
   console.log(`cli version: ${getCliVersion()}`);
   console.log(`server: ${serverUrl}`);
   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`);
+      }
+    }
+  }
 }
 
 /**
@@ -1584,17 +1735,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) {
+  const originalArgs = [...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',
+      'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe',
       [
         '-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' }
     );
@@ -1607,53 +1761,172 @@ 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.
  * Without arguments a fresh enrollment is requested via the browser device
- * flow; with `host_id` + `token` (dashboard flow) the supplied enrollment is
- * redeemed directly. Enrollment always goes through POST /api/enroll with the
+ * flow; with `host_id` + `token` (legacy dashboard flow) the supplied
+ * enrollment is redeemed directly; with a bare canonical `host_id`
+ * (`allowHostIdOnly`, the canonical install_command form) the single-use
+ * token is read from a masked interactive prompt and never touches argv.
+ * Enrollment always goes through POST /api/enroll with the
  * OAuth user grant — the same tested chain as the default pairing flow — not
  * through the dashboard shell snippets, because this CLI already embeds
  * download, install, and device-auth verification.
  * @param {string[]} args
+ * @param {{ allowHostIdOnly?: boolean, promptToken?: (io: { input: import('node:stream').Readable, output: import('node:stream').Writable }) => Promise<string> }} [options]
  */
-export async function runSetup(args = []) {
+export async function runSetup(args = [], { allowHostIdOnly = false, promptToken = promptEnrollmentToken } = {}) {
   const positionals = args.filter((a) => !a.startsWith('-'));
   if (positionals.includes('help') || args.includes('--help') || args.includes('-h')) {
     console.log(
       [
         'Usage:',
         '  nodecommand setup                  install via the browser device flow (auto system/user mode)',
-        '  nodecommand setup <host_id> <token>  install with a dashboard enrollment token',
+        '  nodecommand setup <host_id> <token>  install with a dashboard enrollment token (legacy positional form)',
+        '',
+        '  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.',
         '',
-        'The install mode is chosen automatically: administrator/root installs',
-        'machine-wide (system), anything else installs per-user (user).'
+        '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.',
+        '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', '--maintain-identity', '--configure-helper-binding', '--activate-initial-binding'], 'setup');
+  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.');
+    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;
+  }
+  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.
-  if (positionals.length !== 0 && positionals.length !== 2) {
+  // One positional (host id) is valid only for the bare `nodecommand
+  // <host_id>` form; `setup <host_id>` stays a loud usage error.
+  const onePositionalOk = allowHostIdOnly && positionals.length === 1;
+  if (positionals.length !== 0 && positionals.length !== 2 && !onePositionalOk) {
     console.error('error: [INVALID_SETUP_ARGS] setup takes either no arguments or `<host_id> <token>`.');
     console.error('suggested_action: Re-run as `nodecommand setup` or `nodecommand setup <host_id> <token>`.');
     process.exit(1);
   }
+  const browserBrand = captureBrowserDefaultBrand();
   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
+  let ncRoot;
+  let existingTarget;
+  let existingEnv;
+  let existingKey;
+  let rootManagedPair;
+  let protectedKeyContext;
+  {
+    try {
+      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) {
+        const localEnv = loadValidHostEnv(getEnvFilePath(ncRoot));
+        if (!localEnv) throw new Error(`Existing host configuration at ${ncRoot} is incomplete; refusing a new enrollment or credential overwrite.`);
+        if (target.clientId && localEnv.NC_CLIENT_ID !== target.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(ncRoot);
+        if (!protectedKeyContext) {
+          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 ${ncRoot} has an unverifiable type/owner; refusing identity replacement.`);
+          }
+        }
+        try {
+          existingKey = protectedKeyContext ? loadRootManagedPairKey(ncRoot, protectedKeyContext.ordinaryUid) : loadDeviceKeyPair(keyPath);
+        } catch {
+          throw new Error(`Existing device key at ${ncRoot} cannot be verified; preserve it for selected-installation maintenance.`);
+        }
+        existingEnv = localEnv;
+        const appInfo = fs.lstatSync(path.join(ncRoot, 'app'));
+        if (!appInfo.isDirectory() || appInfo.isSymbolicLink()) throw new Error(`Existing application at ${ncRoot} is incomplete; use selected-installation maintenance.`);
+      }
+    } 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;
+    }
+  }
+  if (existingTarget) {
+    // An installed tree is verification-only here. In particular, a legacy
+    // tree without pairing-state metadata must not rerun OS installers that
+    // can replace shared services/helpers. Repair is selected maintenance.
+    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 (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);
+    }
+    return;
+  }
+  // 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%.
-  if (installMode === 'user' && canElevate() && !process.env.NC_ELEVATED) {
+  if (os.platform() !== 'darwin' && 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();
+        const elevated = requestWindowsElevation(browserBrand);
         if (elevated && elevated.status === 0) process.exit(0);
       }
       console.error(WINDOWS_ELEVATION_INSTALL_DECLINED);
@@ -1666,16 +1939,43 @@ export async function runSetup(args = []) {
       { stdio: 'inherit', env: { ...process.env, NC_ELEVATED: '1' } }
     );
     if (elevated && elevated.status === 0) process.exit(0);
+    try {
+      // A failed elevated child may already have created an installation.
+      // Recheck before falling back rather than creating a competing agent.
+      const target = setupTarget({ mode: installMode });
+      if (target.existing) throw new Error(`An installation now exists at ${target.ncRoot}; preserve it through its maintenance flow.`);
+      ncRoot = target.ncRoot;
+    } catch (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;
+    }
     console.warn('Elevation unavailable or declined; continuing with a per-user install.');
   }
   // 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);
+  ncRoot = 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) {
+    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 {
@@ -1683,17 +1983,96 @@ export async function runSetup(args = []) {
         baseUrl,
         apiBase,
         enrollment: { host_id: hostId, enrollment_token: enrollmentToken },
+        browserBrand,
         installMode,
+        rootConsent,
         ncRoot
       });
-      printSetupSuccess({ hostId: result.hostId, serverUrl: result.serverUrl, installMode, resumed: result.resumed, version: result.version });
+      printSetupSuccess({ ...result, installMode, ncRoot });
     } catch (err) {
       reportSetupError(err);
       process.exit(1);
     }
     return;
   }
-  await runDeviceFlow({ installMode, ncRoot });
+  await runDeviceFlow({ installMode, ncRoot, browserBrand, rootConsent });
+}
+
+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;
+}
+
+/**
+ * Prompt text for the masked enrollment-token prompt. Printed to stderr (the
+ * CLI's human channel) so stdout stays clean for machine payloads.
+ */
+export const ENROLLMENT_TOKEN_PROMPT = 'Enrollment token (input hidden): ';
+
+/**
+ * Reads a single-use enrollment token from an interactive terminal WITHOUT
+ * echoing it. Node-stdlib only, no new deps: readline drives the input (line
+ * editing, paste, Ctrl+C, raw mode) while its echo/cursor frames are written
+ * into a sink stream, so the typed token never reaches the terminal,
+ * scrollback, or a session recording.
+ *
+ * Fails closed (PairingError ENROLL_TOKEN_REQUIRED) instead of hanging when
+ * stdin is not an interactive terminal, on EOF, on Ctrl+C, or on an empty
+ * submission. The caller maps the code to a suggested_action line.
+ * @param {{ input?: import('node:stream').Readable, output?: import('node:stream').Writable }} [streams]
+ * @returns {Promise<string>} the typed token (trimmed)
+ */
+export function promptEnrollmentToken({ input = process.stdin, output = process.stderr } = {}) {
+  return new Promise((resolve, reject) => {
+    if (!input || input.isTTY !== true) {
+      reject(
+        new PairingError(
+          'ENROLL_TOKEN_REQUIRED',
+          'No enrollment token was provided and stdin is not an interactive terminal. Re-run in a terminal so the token can be typed with hidden input, or pass the token as the second argument.'
+        )
+      );
+      return;
+    }
+    output.write(ENROLLMENT_TOKEN_PROMPT);
+    const sink = new Writable({ write(_chunk, _encoding, callback) { callback(); } });
+    sink.isTTY = true;
+    sink.columns = 80;
+    let settled = false;
+    const rl = readline.createInterface({ input, output: sink, terminal: true });
+    const close = () => {
+      try {
+        rl.close();
+      } catch {}
+      output.write('\n');
+    };
+    const finish = (token) => {
+      if (settled) return;
+      settled = true;
+      close();
+      resolve(token);
+    };
+    const abort = (message) => {
+      if (settled) return;
+      settled = true;
+      close();
+      reject(new PairingError('ENROLL_TOKEN_REQUIRED', message));
+    };
+    rl.on('SIGINT', () => abort('Enrollment token entry was cancelled.'));
+    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.');
+    });
+    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.');
+        return;
+      }
+      finish(token);
+    });
+  });
 }
 
 /**
@@ -1733,8 +2112,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
  */
@@ -1751,7 +2130,14 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
     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);
@@ -1760,7 +2146,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();
@@ -1769,7 +2155,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).`
@@ -1789,34 +2184,37 @@ 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;
     }
     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;
     }
   }
-  // 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);
     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}: ${err.message}`);
       console.error(uninstallFailureSuggestion());
       failed += 1;
     }
@@ -1833,6 +2231,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.'
   });
 }
@@ -1861,10 +2261,10 @@ 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 } = {}) {
   const deviceEndpoint = `${baseUrl}/oauth/device/code`;
   let initRes;
 
@@ -1903,7 +2303,9 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
     verification_uri_complete,
     verification_uri,
     interval = 3,
-    expires_in = 600
+    // Platform contract: the server always returns expires_in and grants live
+    // 300s. Keep the fallback at the mandated 300s TTL, never the old 600s.
+    expires_in = 300
   } = initRes.data;
 
   const bold = '\x1b[1m';
@@ -1937,8 +2339,9 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
   let isPolling = false;
   let currentIntervalMs = pollIntervalMs;
   // Poll bounds (RFC 8628 §3.5): the device_code lives ~expires_in seconds
-  // server-side, and consecutive network failures must not spin forever.
-  const lifetimeSec = Number(expires_in) > 0 ? Number(expires_in) : 600;
+  // server-side (300s mandated TTL), and consecutive network failures must
+  // not spin forever. Fallback mirrors the same 300s contract.
+  const lifetimeSec = Number(expires_in) > 0 ? Number(expires_in) : 300;
   const flowDeadline = Date.now() + lifetimeSec * 1000;
   let consecutiveNetErrors = 0;
   const MAX_NET_ERROR_RETRIES = 10;
@@ -1969,12 +2372,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,