node-command 2.0.15 → 2.0.16

package/bin/nc.mjs

@@ -30,12 +30,15 @@ import {
   removePartialSystemRoot,
   removePartialUserRoot,
   resolveExecutable,
+  resolveInstallConsent,
   setupTarget,
   unreadableSystemInstallations,
   maintainLinuxIdentity,
   loadProtectedHelperProducer,
   LINUX_PAIRED_UNINSTALL_ENTRY,
   modeWarningFor,
+  PARTIAL_SYSTEM_ROOT,
+  partialEnrollmentSystemRoot,
   runUninstallerScript,
   uninstallFailureSuggestion,
   uninstallerForRoot,
@@ -1562,22 +1565,51 @@ async function fetchPrivilegedInstallContext({ baseUrl, hostId, hostToken, priva
 }
 
 /**
- * Publishes the locally generated helper public key as a pending candidate.
- * Only the public key is sent; a failure never rolls back the installed agent.
+ * Publishes the locally generated helper ACK public key as a pending candidate.
+ * The ACK key is the helper identity; privileged-helper-public.pem is the
+ * control-plane pin and is never a candidate. Only the derived public key is
+ * sent; a failure never rolls back the installed agent.
  */
 async function publishPrivilegedHelperCandidate({ root, baseUrl, hostId, hostToken, privateKey }) {
-  const publicKeyPath = path.join(root, 'libexec', 'privileged-helper', 'privileged-helper-public.pem');
+  const helperDir = path.join(root, 'libexec', 'privileged-helper');
+  const bootstrapPath = path.join(helperDir, 'helper-bootstrap.json');
+  const failed = { published: false, warning: 'Admin remains pending; candidate publication failed: protected helper ACK key not found or invalid.' };
+  let ackKeyPath = path.join(helperDir, 'privileged-helper-ack-key.pem');
+  let bootstrap;
+  try {
+    const bootstrapInfo = fs.lstatSync(bootstrapPath);
+    if (!bootstrapInfo.isFile() || bootstrapInfo.isSymbolicLink()) return failed;
+    bootstrap = JSON.parse(fs.readFileSync(bootstrapPath, 'utf8'));
+  } catch (err) {
+    if (err?.code !== 'ENOENT') return failed;
+  }
+  if (bootstrap && typeof bootstrap.ack_private_key_file === 'string' && bootstrap.ack_private_key_file) {
+    if (!path.isAbsolute(bootstrap.ack_private_key_file) ||
+        path.resolve(bootstrap.ack_private_key_file) !== bootstrap.ack_private_key_file) return failed;
+    ackKeyPath = bootstrap.ack_private_key_file;
+  }
+  let ackKeyBytes;
+  try {
+    const ackInfo = fs.lstatSync(ackKeyPath);
+    if (!ackInfo.isFile() || ackInfo.isSymbolicLink() ||
+        (process.geteuid?.() === 0 && ackInfo.uid !== 0) || (ackInfo.mode & 0o777) !== 0o600) return failed;
+    ackKeyBytes = fs.readFileSync(ackKeyPath);
+  } catch {
+    return failed;
+  }
+  let publicKey;
   let pem;
   try {
-    const info = fs.lstatSync(publicKeyPath);
-    if (!info.isFile() || info.isSymbolicLink()) throw new Error('not a regular file');
-    pem = fs.readFileSync(publicKeyPath, 'utf8');
+    const ackPrivateKey = crypto.createPrivateKey(ackKeyBytes);
+    if (ackPrivateKey.asymmetricKeyType !== 'ed25519') return failed;
+    publicKey = crypto.createPublicKey(ackPrivateKey);
+    pem = publicKey.export({ type: 'spki', format: 'pem' });
   } catch {
-    return { published: false, warning: 'Admin remains pending; candidate publication failed: protected helper public key not found.' };
+    return failed;
+  } finally {
+    ackKeyBytes.fill(0);
   }
   try {
-    const publicKey = crypto.createPublicKey(pem);
-    if (publicKey.asymmetricKeyType !== 'ed25519') throw new Error('helper public key is not Ed25519');
     const candidateUrl = `${baseUrl}/api/clients/${encodeURIComponent(hostId)}/privileged-helper/candidate`;
     assertCredentialOrigin(candidateUrl, { label: 'helper candidate URL', action: 'publish' });
     const proof = createDeviceProofCli({ privateKey, hostId, method: 'POST', url: candidateUrl, credential: hostToken });
@@ -1590,16 +1622,142 @@ async function publishPrivilegedHelperCandidate({ root, baseUrl, hostId, hostTok
       throw new Error(sanitizeForDisplay(res.data?.error || `HTTP ${res.status}`, 120));
     }
     const keyId = crypto.createHash('sha256').update(publicKey.export({ type: 'spki', format: 'der' })).digest('hex');
-    return { published: true, fingerprint: `sha256:${keyId}` };
+    const candidate = res.data?.candidate;
+    let candidateKey = null;
+    try { candidateKey = candidate?.public_key ? crypto.createPublicKey(candidate.public_key) : null; } catch {}
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate) ||
+        !/^cand_[0-9a-f]{32}$/.test(String(candidate.candidate_generation || '')) ||
+        candidate.helper_key_id !== keyId || !candidateKey ||
+        candidateKey.export({ type: 'spki', format: 'der' }).compare(publicKey.export({ type: 'spki', format: 'der' })) !== 0) {
+      throw new Error('the control plane did not return a matching candidate generation');
+    }
+    return { published: true, fingerprint: `sha256:${keyId}`, candidate_generation: candidate.candidate_generation,
+      helper_key_id: keyId, public_key: pem, expires_at_ms: candidate.expires_at_ms };
   } catch (err) {
     const detail = sanitizeForDisplay(err instanceof Error ? err.message : String(err), 200);
     return {
       published: false,
-      warning: `Admin remains pending; candidate publication failed: ${detail}. The agent is installed without the Admin helper; approve the helper candidate from the dashboard once the control plane accepts it.`
+      warning: `Admin remains pending; candidate publication failed: ${detail}. The helper remains installed but unbound; re-run setup with root consent or use the documented break-glass maintenance path.`
     };
   }
 }
 
+/**
+ * Reads the protected helper bootstrap record written by the privileged
+ * installer. The record supplies the exact tenant/control-plane/client tuple
+ * and ACK key id that the signed challenge must match; it is never a source of
+ * trust on its own (the producer verifies the pinned challenge before writing).
+ * @param {string} root
+ * @param {string} hostId
+ * @param {{ helper_key_id: string }} candidate
+ */
+function readProtectedHelperBootstrap(root, hostId, candidate) {
+  const file = path.join(root, 'libexec', 'privileged-helper', 'helper-bootstrap.json');
+  const failed = (reason) => new PairingError('HELPER_BINDING_FAILED', `Protected helper bootstrap is not usable: ${reason}. The helper remains installed but unbound.`);
+  let info;
+  try {
+    info = fs.lstatSync(file);
+  } catch (err) {
+    throw failed(err?.code === 'ENOENT' ? 'the helper bootstrap file is missing' : 'the helper bootstrap file cannot be inspected');
+  }
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 65536) throw failed('the helper bootstrap file is not a bounded regular file');
+  let bootstrap;
+  try {
+    bootstrap = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw failed('the helper bootstrap file is not valid JSON');
+  }
+  if (!bootstrap || typeof bootstrap !== 'object' || Array.isArray(bootstrap) ||
+      bootstrap.client_id !== hostId || bootstrap.root_consent !== true ||
+      typeof bootstrap.tenant_id !== 'string' || !bootstrap.tenant_id ||
+      typeof bootstrap.control_plane_id !== 'string' || !bootstrap.control_plane_id ||
+      bootstrap.helper_key_id !== candidate.helper_key_id) {
+    throw failed('the bootstrap tuple does not match the published candidate');
+  }
+  return bootstrap;
+}
+
+/**
+ * Requests the signed install-binding challenge. Exactly one management source
+ * authorizes the request server-side: the unexpired install authorization on
+ * the Y path (no intent), or the consumed root-on intent id on the root-on
+ * path. The device proof is the same one used by other client-authenticated
+ * routes.
+ * @param {{ baseUrl: string, hostId: string, hostToken: string, privateKey: import('node:crypto').KeyObject, candidate: { candidate_generation: string, public_key: string }, rootOnIntentId?: string|null }} options
+ */
+export async function requestPrivilegedHelperInstallBinding({ baseUrl, hostId, hostToken, privateKey, candidate, rootOnIntentId = null }) {
+  const bindingUrl = `${baseUrl}/api/clients/${encodeURIComponent(hostId)}/privileged-helper/install-binding`;
+  assertCredentialOrigin(bindingUrl, { label: 'helper install-binding URL', action: 'request' });
+  const body = {
+    candidate_generation: candidate.candidate_generation,
+    public_key: candidate.public_key,
+    expected_helper_key_binding_id: null
+  };
+  if (rootOnIntentId) body.root_on_intent_id = rootOnIntentId;
+  const proof = createDeviceProofCli({ privateKey, hostId, method: 'POST', url: bindingUrl, credential: hostToken });
+  const res = await requestJson('POST', bindingUrl, body, {
+    Authorization: `NC-Device ${hostToken}`,
+    'NC-Device-Proof': proof
+  });
+  if (res.status < 200 || res.status >= 300) {
+    const detail = sanitizeForDisplay(res.data?.error || res.data?.message || `HTTP ${res.status}`, 160);
+    throw new PairingError('HELPER_BINDING_FAILED', `The control plane refused the helper install-binding request (${detail}). The helper remains installed but unbound.`);
+  }
+  const challenge = res.data?.challenge ?? res.data?.maintenance?.challenge;
+  const bindingId = res.data?.helper_key_binding_id ?? res.data?.binding_id ??
+    res.data?.binding?.helper_key_binding_id ?? res.data?.maintenance?.binding?.helper_key_binding_id;
+  if (!challenge || typeof challenge !== 'object' || Array.isArray(challenge) ||
+      typeof bindingId !== 'string' || !bindingId) {
+    throw new PairingError('HELPER_BINDING_FAILED', 'The control plane returned no signed challenge/binding id. The helper remains installed but unbound.');
+  }
+  const appliedPermission = [res.data?.applied_permission, res.data?.permission?.applied_permission,
+    res.data?.execution_permission?.applied_permission, res.data?.local_privilege?.applied_permission]
+    .find((value) => value === 'admin' || value === 'user') ?? null;
+  return { challenge, helper_key_binding_id: bindingId, applied_permission: appliedPermission };
+}
+
+/**
+ * Completes the first helper binding inside the same elevated setup: request
+ * the signed challenge, verify it with the protected producer, write the
+ * binding atomically and restart the helper. A failure is a typed fail-closed
+ * error; the helper stays installed and unbound for a repairable retry.
+ * @param {{ root: string, baseUrl: string, hostId: string, hostToken: string, privateKey: import('node:crypto').KeyObject, candidate: { candidate_generation: string, helper_key_id: string, public_key: string }, rootOnIntentId?: string|null, producer?: any }} options
+ */
+export async function completePrivilegedHelperBinding({ root, baseUrl, hostId, hostToken, privateKey, candidate, rootOnIntentId = null, producer = null }) {
+  const response = await requestPrivilegedHelperInstallBinding({ baseUrl, hostId, hostToken, privateKey, candidate, rootOnIntentId });
+  const bootstrap = readProtectedHelperBootstrap(root, hostId, candidate);
+  const binding = {
+    control_plane_id: bootstrap.control_plane_id,
+    tenant_id: bootstrap.tenant_id,
+    client_id: hostId,
+    helper_key_binding_id: response.helper_key_binding_id,
+    helper_key_id: candidate.helper_key_id,
+    public_key: candidate.public_key,
+    confirmed: true,
+    active: false
+  };
+  const libexec = path.join(root, 'libexec');
+  fs.mkdirSync(libexec, { recursive: true, mode: 0o755 });
+  const tempDir = fs.mkdtempSync(path.join(libexec, '.nc-install-binding-'));
+  try {
+    fs.chmodSync(tempDir, 0o700);
+    const bindingFile = path.join(tempDir, 'binding.json');
+    const challengeFile = path.join(tempDir, 'challenge.json');
+    fs.writeFileSync(bindingFile, JSON.stringify(binding), { mode: 0o600, flag: 'wx' });
+    fs.writeFileSync(challengeFile, JSON.stringify(response.challenge), { mode: 0o600, flag: 'wx' });
+    const module = producer || await loadProtectedHelperProducer(root);
+    await module.configureProtectedHelperBinding({ root, bindingFile, challengeFile, activateLocally: true });
+  } catch (err) {
+    if (err instanceof PairingError) throw err;
+    const detail = sanitizeForDisplay(err instanceof Error ? err.message : String(err), 200);
+    throw new PairingError('HELPER_BINDING_FAILED', `Protected helper binding failed: ${detail}. The helper remains installed but unbound; no Admin readiness is claimed.`);
+  } finally {
+    try { fs.rmSync(tempDir, { recursive: true, force: true }); } catch {}
+  }
+  return { bound: true, helper_key_binding_id: binding.helper_key_binding_id,
+    fingerprint: `sha256:${binding.helper_key_id}`, applied_permission: response.applied_permission ?? null };
+}
+
 /**
  * Downloads, verifies, extracts, and installs the agent package. Writes NO
  * credentials — the env file must already exist before this runs.
@@ -1628,10 +1786,16 @@ async function publishPrivilegedHelperCandidate({ root, baseUrl, hostId, hostTok
  * @param {{ ncRoot?: string, updatesUrl?: string, serverUrl?: string, release?: Record<string, unknown>|null, installMode?: 'system'|'user', rootConsent?: boolean, runInstaller?: (scriptPath: string, ncRoot: string, env?: Record<string, string>) => void, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject, downloadTimeoutMs?: number }} options
  * @returns {Promise<{ helperCandidate: { published: boolean, fingerprint?: string, warning?: string }|null }>} `helperCandidate` is null when no helper was requested.
  */
-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 } = {}) {
+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, rootOnIntentId = null, bindingProducer = null } = {}) {
+  if (rootConsent === true && installMode === 'user') {
+    throw new PairingError('ROOT_HELPER_REQUIRES_SYSTEM_INSTALL', 'Root-command consent requires a system install; no per-user install was created. Install in user mode, then run `sudo npx --yes node-command@latest root on <host_id>` to elevate this host.');
+  }
+  if (rootConsent === true && os.platform() !== 'linux') {
+    throw new PairingError('ROOT_HELPER_UNSUPPORTED_PLATFORM', 'Root-command consent with the privileged helper is Linux-only. Install in user mode; this host does not claim Admin readiness.');
+  }
   ncRoot = ncRoot || (installMode ? getNcRootForMode(installMode) : getNcRoot());
   const modeEnv = { ...(installMode ? installerEnvForMode(installMode) : {}), NC_ROOT_COMMAND_CONSENT: rootConsent === true ? 'yes' : 'no' };
-  const helperRequested = rootConsent === true && installMode !== 'user' && os.platform() === 'linux';
+  const helperRequested = rootConsent === true && os.platform() === 'linux';
   const invokeInstaller = (scriptPath, installRoot) =>
     runInstaller ? runInstaller(scriptPath, installRoot, modeEnv) : runInstallerScript(scriptPath, installRoot, modeEnv);
   const root = ncRoot;
@@ -1654,6 +1818,9 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
   if (hasDeviceIdentity) {
     assertCredentialOrigin(defaultBaseUrl, { label: 'agent server origin' });
   }
+  if (helperRequested && !hasDeviceIdentity) {
+    throw new PairingError('HELPER_BINDING_FAILED', 'Root-command consent requires the existing host identity to publish and bind the helper. No Admin readiness was claimed; re-run setup with an enrollment.');
+  }
   /** @type {Record<string, any>} */
   let activeRelease;
   if (release && typeof release === 'object') {
@@ -1922,6 +2089,7 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
   }
 
   let helperCandidate = null;
+  let helperBinding = null;
   if (helperRequested && hasDeviceIdentity) {
     helperCandidate = await publishPrivilegedHelperCandidate({
       root,
@@ -1930,11 +2098,24 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       hostToken,
       privateKey
     });
-    if (helperCandidate.published === false && helperCandidate.warning) {
-      console.warn(`Warning: ${helperCandidate.warning}`);
+    if (helperCandidate.published !== true) {
+      // One-session binding is the install contract: never report success with
+      // a silently unbound helper. The agent stays installed and the next
+      // setup/root-on can resume the same host identity.
+      throw new PairingError('HELPER_BINDING_FAILED', `${helperCandidate.warning || 'The helper candidate could not be published.'} The agent is installed; the helper remains unbound and no Admin readiness is claimed.`);
     }
+    helperBinding = await completePrivilegedHelperBinding({
+      root,
+      baseUrl: defaultBaseUrl,
+      hostId,
+      hostToken,
+      privateKey,
+      candidate: helperCandidate,
+      rootOnIntentId,
+      producer: bindingProducer
+    });
   }
-  return { helperCandidate };
+  return { helperCandidate, helperBinding };
 }
 
 /**
@@ -2123,9 +2304,15 @@ export async function pairDeviceAndInstall({
     intervalMs: verifyIntervalMs
   });
   writePairState(statePath, { host_id: hostId, phase: 'verified' });
+  const helperBinding = installOutcome?.helperBinding ?? null;
+  // Admin readiness is truthful only when the helper is actually bound and the
+  // server-reported applied personal permission is still Admin. The install
+  // answer alone is never evidence of readiness.
+  const appliedPermission = executionInitialization?.permission?.applied_permission ?? null;
+  const adminReady = helperBinding?.bound === true && appliedPermission === 'admin';
   return { hostId, serverUrl: enrollServerUrl, resumed: false, version: agentVersion, rootConsent: selectedRootConsent,
-    privilegeReadiness: selectedRootConsent ? 'pending' : 'unavailable', executionInitialization,
-    helperCandidate: installOutcome?.helperCandidate ?? null };
+    privilegeReadiness: helperBinding?.bound === true ? 'helper-ready' : selectedRootConsent ? 'pending' : 'unavailable',
+    executionInitialization, helperCandidate: installOutcome?.helperCandidate ?? null, helperBinding, adminReady };
 }
 
 /**
@@ -2165,12 +2352,14 @@ function printCliHelp() {
       '  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 root on <host_id>        elevate an existing user-mode Linux install to a system helper (interactive)',
+      '  nodecommand [--allow-root-commands]  explicitly request privileged preparation (default No; one-session helper binding)',
       '  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)',
       '  nodecommand --diagnostics --apply    write the diagnostics bundle (.tar.gz) for a support ticket',
       '  nodecommand --diagnostics --apply --output <path>   write the bundle to a chosen path',
+      '  nodecommand root --help              show the root-on elevation help',
       '  nodecommand --help                   show this help',
       '',
       'Environment:',
@@ -2231,11 +2420,75 @@ export function isBareHostIdInvocation(args = []) {
   return typeof hostId === 'string' && !hostId.startsWith('-') && HOST_ID_RE.test(hostId);
 }
 
+function printRootHelp() {
+  console.log(
+    [
+      'nodecommand root — one-time local elevation for a user-mode Linux host',
+      '',
+      'Usage:',
+      '  nodecommand root on <host_id>   consume the Owner-issued intent and install/bind the system helper',
+      '  nodecommand root --help         show this help',
+      '',
+      'The command requires an interactive terminal, real root (run it with sudo), an existing',
+      'user-mode host identity, and a current Owner-issued Admin request in the dashboard.',
+      'It preserves the host id, token, device key, server URL and local audit state.',
+      'It never accepts secrets on the command line. Linux only.'
+    ].join('\n')
+  );
+}
+
+/**
+ * `nodecommand root on <host_id>`. Dispatch stays small: the implementation
+ * lives in lib/root-on.mjs and is loaded only for this command.
+ * @param {string[]} args
+ */
+export async function runRootCommand(args = []) {
+  if (args.length === 0 || args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    printRootHelp();
+    return;
+  }
+  assertKnownFlags(args, ['--help', '-h'], 'root');
+  const positionals = args.filter((arg) => !arg.startsWith('-'));
+  if (positionals.length !== 2 || positionals[0] !== 'on') {
+    console.error('error: [INVALID_ROOT_ARGS] `root` takes exactly `on <host_id>`.');
+    console.error('suggested_action: Run `sudo npx --yes node-command@latest root on <host_id>` with the canonical host id from the dashboard.');
+    process.exit(1);
+    return;
+  }
+  const hostId = positionals[1];
+  if (!HOST_ID_RE.test(hostId)) {
+    console.error('error: [INVALID_HOST_ID] The supplied host id is not a canonical nc_<64hex> id.');
+    console.error('suggested_action: Copy the exact host id shown by the dashboard; no elevation was attempted.');
+    process.exit(1);
+    return;
+  }
+  const { runRootOn } = await import('../lib/root-on.mjs');
+  const result = await runRootOn({ hostId });
+  if (result.alreadyEnabled === true) {
+    console.log(`helper-ready: host ${sanitizeForDisplay(hostId, 128)} is already bound; no changes were made.`);
+    console.log('Admin-ready: pending (current execution permission is not verified by this command)');
+    return;
+  }
+  if (result.helperReady !== true) {
+    console.error('error: [HELPER_BINDING_FAILED] The system install did not complete the helper binding; no Admin readiness is claimed.');
+    console.error('suggested_action: Preserve both installations and re-run `sudo npx --yes node-command@latest root on <host_id>` after resolving the reported install error.');
+    process.exit(1);
+    return;
+  }
+  console.log(`helper-ready: host ${sanitizeForDisplay(hostId, 128)} is installed and bound.`);
+  if (result.adminReady === true) console.log('Admin-ready: yes (current execution permission is Admin)');
+  else console.log('Admin-ready: pending (current execution permission is not Admin)');
+}
+
 async function main() {
   const cliArgs = process.argv.slice(2);
   // Subcommands route FIRST: otherwise `setup --diagnostics` or a stray flag
   // would be swallowed by the global flag handlers instead of the command.
   const [subcommand, ...subArgs] = cliArgs;
+  if (subcommand === 'root') {
+    await runRootCommand(subArgs);
+    return;
+  }
   if (subcommand === 'setup') {
     await runSetup(subArgs);
     return;
@@ -2338,7 +2591,34 @@ export function suggestedActionFor(code) {
     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.';
+      return 'The helper is installed but unbound. Re-run setup with root consent or use the documented break-glass maintenance path; no Admin readiness is claimed.';
+    case 'ROOT_HELPER_REQUIRES_SYSTEM_INSTALL':
+      return 'Install in user mode first, then run `sudo npx --yes node-command@latest root on <host_id>` to elevate this host.';
+    case 'ROOT_HELPER_UNSUPPORTED_PLATFORM':
+      return 'The privileged helper is Linux-only; install in user mode. This host does not claim Admin readiness.';
+    case 'ROOT_ELEVATION_REQUIRED':
+      return 'Provide administrator/root rights for a system install, or install in user mode and run `sudo npx --yes node-command@latest root on <host_id>`.';
+    case 'ROOT_ON_UNSUPPORTED_PLATFORM':
+      return 'The privileged helper elevation path is Linux-only; this host remains User-only and does not claim Admin readiness.';
+    case 'ROOT_ON_NON_INTERACTIVE':
+      return 'Run the command in an interactive terminal so the required local confirmation can be entered.';
+    case 'ROOT_ON_NOT_ROOT':
+      return 'Run `sudo npx --yes node-command@latest root on <host_id>` with real root/administrator rights.';
+    case 'ROOT_ON_IDENTITY_MISSING':
+      return 'Install the host in user mode first so its existing host id, token and device key exist; root-on never re-enrolls.';
+    case 'ROOT_ON_IDENTITY_MISMATCH':
+      return 'The local installation does not match the requested host id. Preserve it and use its own maintenance flow; no identity was replaced.';
+    case 'ROOT_ON_CONFLICT':
+      return 'A different system installation or service already exists. Preserve it and resolve the conflict through its maintenance flow before retrying.';
+    case 'ROOT_ON_CONFIRMATION_DECLINED':
+      return 'No elevation was performed. Re-run and confirm the exact host when you intend to enable Admin.';
+    case 'ROOT_ON_INTENT_REQUIRED':
+    case 'ROOT_ON_INTENT_EXPIRED':
+      return 'Ask the workspace Owner to select Admin for this host again in the dashboard, then re-run `sudo npx --yes node-command@latest root on <host_id>` before the 10-minute intent expires.';
+    case 'ROOT_ON_AUTH_FAILED':
+      return 'The host identity was rejected; the intent was not consumed. Verify the stored host credentials and re-run.';
+    case 'ROOT_ON_MIGRATION_FAILED':
+      return 'The user installation was preserved and the partial system root was rolled back. Resolve the reported conflict and re-run.';
     default:
       return 'Re-run the command; use `nodecommand --help` for usage.';
   }
@@ -2389,7 +2669,7 @@ function getCliVersion() {
  * host id, install mode, CLI version, and verification status.
  * @param {{ hostId: string, serverUrl: string, installMode?: 'system'|'user', resumed?: boolean, version?: string|null, rootConsent?: boolean, ncRoot?: string, executionInitialization?: any, helperCandidate?: { published: boolean, fingerprint?: string, warning?: string }|null }} options
  */
-export function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null, rootConsent = false, ncRoot = undefined, executionInitialization = null, helperCandidate = null }) {
+export function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null, rootConsent = false, ncRoot = undefined, executionInitialization = null, helperCandidate = null, helperBinding = null, adminReady = false }) {
   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: ${sanitizeForDisplay(version, 120)}`);
@@ -2404,15 +2684,18 @@ export function printSetupSuccess({ hostId, serverUrl, installMode = undefined,
   } else {
     console.log(`root command consent: ${rootConsent === true ? 'Yes' : 'No'}`);
     if (rootConsent !== true) {
-      console.log('local privilege readiness: unavailable (not requested)');
-    } else if (helperCandidate && helperCandidate.published === true) {
-      const match = /^sha256:([0-9a-f]{64})$/i.exec(String(helperCandidate.fingerprint || ''));
+      console.log('local privilege readiness: user-mode (no privileged helper installed)');
+      console.log(`Admin is available with one command: sudo npx --yes node-command@latest root on ${sanitizeForDisplay(hostId, 128)}`);
+    } else if (helperBinding?.bound === true) {
+      const match = /^sha256:([0-9a-f]{64})$/i.exec(String(helperBinding.fingerprint || ''));
       const shortFingerprint = match ? `sha256:${match[1].slice(0, 16).toLowerCase()}` : null;
-      console.log(`local privilege readiness: Admin pending: approve the helper candidate in the dashboard${shortFingerprint ? ` (fingerprint: ${shortFingerprint})` : ''}`);
+      console.log(`local privilege readiness: helper-ready${shortFingerprint ? ` (fingerprint: ${shortFingerprint})` : ''}`);
+      if (adminReady === true) console.log('Admin-ready: yes (current execution permission is Admin)');
+      else console.log('Admin-ready: pending (current execution permission is not Admin)');
     } else if (helperCandidate && typeof helperCandidate.warning === 'string' && helperCandidate.warning) {
       console.log(`local privilege readiness: ${helperCandidate.warning}`);
     } else {
-      console.log('local privilege readiness: pending independent management approval and protected helper binding');
+      console.log('local privilege readiness: helper installed but unbound; re-run setup with root consent or use the documented break-glass maintenance path');
     }
     const receipt = executionInitialization;
     const fields = ['outcome', 'reason', 'subject_user_id', 'permission'];
@@ -2528,18 +2811,20 @@ 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)',
         '',
+        '  nodecommand root on <host_id>       elevate an existing user-mode Linux install to a system helper',
         '  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.',
+        '    BREAK-GLASS ONLY: explicit local recovery maintenance, never part of the normal install flow.',
         '',
-        '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.',
+        'The install asks once: Allow root/administrator commands through Node Command? [y/N]',
+        '  Y = system install that provisions, binds and restarts the privileged helper in the same run.',
+        '  N = user-mode install; Admin is then available with `sudo npx --yes node-command@latest root on <host_id>`.',
+        'The explicit per-user switch always selects user mode and never asks or upgrades.',
+        'Noninteractive setup defaults to No; --allow-root-commands explicitly requests Y.',
         '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.'
+        'macOS: fresh non-root installs use the per-user LaunchAgent without sudo;',
+        'explicit root uses system mode when root consent is Y. Existing roots/modes are preserved or setup stops.'
       ].join('\n')
     );
     return;
@@ -2548,6 +2833,9 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
   // 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('--allow-root-commands')) {
+    throw new PairingError('INVALID_SETUP_ARGS', '--user selects a per-user installation without the privileged helper and cannot be combined with --allow-root-commands. Choose one: Y for a system install with Admin, or --user for User-only.');
+  }
   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.');
   }
@@ -2693,6 +2981,24 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
     }
   };
   try {
+    // A rejected/expired pre-redemption enrollment leaves only the device key
+    // and enrollment state under /opt/nc/config. That exact residue is not an
+    // installation, but setupTarget refuses any existing root without a host
+    // environment, so it would block every retry. When this invocation carries
+    // fresh enrollment material, clear exactly that bounded root through the
+    // same root-only removal the uninstall path uses; every other shape (host
+    // env, app, units, helpers or foreign entries) still fails closed.
+    if (positionals.length > 0 && installMode === 'system' &&
+        isPartialSystemRemovalCandidate(PARTIAL_SYSTEM_ROOT) &&
+        partialEnrollmentSystemRoot(PARTIAL_SYSTEM_ROOT)) {
+      console.log(`Clearing the partial enrollment residue at ${PARTIAL_SYSTEM_ROOT} before a fresh setup (no host configuration or application payload was present).`);
+      const partialLock = acquireInstallLock(PARTIAL_SYSTEM_ROOT);
+      try {
+        removePartialSystemRoot(PARTIAL_SYSTEM_ROOT);
+      } finally {
+        partialLock.release();
+      }
+    }
     if (!unreadableSystemRoot) {
       const target = setupTarget({ mode: installMode });
       ({ mode: installMode, ncRoot } = target);
@@ -2779,6 +3085,32 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
     }
     return;
   }
+  // The install answer is the only local root decision. Ask exactly once,
+  // before the final mode/elevation selection, and carry it through a single
+  // elevation without asking again. `--user` never asks or upgrades.
+  const explicitRootConsent = args.includes('--allow-root-commands');
+  let rootConsentAnswer = false;
+  if (!forceUser) {
+    if (explicitRootConsent) rootConsentAnswer = true;
+    else if (process.env.NC_ELEVATED === '1' && process.env.NC_ROOT_CONSENT_CONFIRMED === '1') rootConsentAnswer = true;
+    else rootConsentAnswer = await promptRootCommandConsent();
+  }
+  // --user never probes elevation (the explicit switch is final). macOS never
+  // auto-elevates, so it never probes either. Only an explicit Y on Linux or
+  // Windows may ask the platform whether elevation is available.
+  const consentPlatform = os.platform();
+  const alreadyElevated = isElevated();
+  const mayProbeElevation = !forceUser && rootConsentAnswer === true && !alreadyElevated &&
+    (consentPlatform === 'linux' || consentPlatform === 'win32');
+  const consentPlan = resolveInstallConsent({ forceUser, explicitOptIn: explicitRootConsent, answer: rootConsentAnswer,
+    platform: consentPlatform, elevated: alreadyElevated, elevationAvailable: mayProbeElevation ? canElevate() : false });
+  if (consentPlan.error) {
+    reportSetupError(new PairingError(consentPlan.error, `Root consent was selected, but this invocation cannot obtain administrator rights. No per-user install was created. Install in user mode, then run \`sudo npx --yes node-command@latest root on ${positionals[0] || '<host_id>'}\`.`));
+    process.exit(1);
+    return;
+  }
+  installMode = consentPlan.installMode;
+  if (!existingTarget) ncRoot = getNcRootForMode(installMode);
   // 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
@@ -2786,21 +3118,24 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
   // 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())) {
+  if (unreadableSystemRoot && !consentPlan.elevationRequired) {
     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.');
+      : 'suggested_action: Re-run with Y/--allow-root-commands and 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) {
+  if (consentPlan.elevationRequired && !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
+    const baseElevatedArgs = tokenFile
       ? buildElevatedSetupArgs(process.argv.slice(1), args, args.lastIndexOf(positionals[1]), tokenFile.filePath)
-      : undefined;
+      : process.argv.slice(1);
+    // Carry the single Y answer through the elevation without re-prompting.
+    const elevatedArgs = baseElevatedArgs.includes('--allow-root-commands')
+      ? baseElevatedArgs : [...baseElevatedArgs, '--allow-root-commands'];
     try {
       if (os.platform() === 'win32') {
         if (process.stdin.isTTY) {
@@ -2811,8 +3146,8 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
             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.');
+        console.error('error: [ROOT_ELEVATION_REQUIRED] Elevation was unavailable or declined; no system-wide installation was performed and no per-user fallback was attempted.');
+        console.error('suggested_action: Run as Administrator in an elevated shell for a system-wide install at C:\\ProgramData\\NC, or install in user mode and then run `node-command root on <host_id>`.');
         process.exit(1);
       }
       console.log('Admin rights required for a system-wide install. Requesting sudo…');
@@ -2821,20 +3156,21 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
       // The caller's PATH is never forwarded into the privileged re-exec.
       const elevationEnv = {
         PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
-        NC_ELEVATED: '1'
+        NC_ELEVATED: '1',
+        NC_ROOT_CONSENT_CONFIRMED: '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(`error: [ROOT_ELEVATION_REQUIRED] ${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))],
+        ['--preserve-env=NC_ELEVATED,NC_ROOT_CONSENT_CONFIRMED', process.execPath, ...elevatedArgs],
         { stdio: 'inherit', env: elevationEnv }
       );
       if (elevated && elevated.status === 0) {
@@ -2864,8 +3200,8 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
     // 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.');
+    console.error('error: [ROOT_ELEVATION_REQUIRED] Elevation was unavailable or declined; no system-wide installation was performed and no per-user fallback was attempted.');
+    console.error('suggested_action: Provide administrator/root rights for a machine-wide installation, or install in user mode and then run `sudo npx --yes node-command@latest root on <host_id>`.');
     process.exit(1);
     return;
   }
@@ -2895,7 +3231,9 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
       }
     }
 
-    const rootConsent = () => promptRootCommandConsent({ explicitOptIn: args.includes('--allow-root-commands') });
+    // The answer was resolved once before elevation; pass the boolean so a
+    // re-entrant prompt can never contradict the selected install mode.
+    const rootConsent = rootConsentAnswer;
     if (positionals.length === 2) {
       const [hostId, enrollmentToken] = positionals;
       try {

package/lib/root-on.mjs

@@ -0,0 +1,338 @@
+import child_process from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  PairingError,
+  HOST_ID_RE,
+  assertCredentialOrigin,
+  confirmPrompt,
+  createDeviceProofCli,
+  downloadAndInstallAgent,
+  getDeviceKeyPath,
+  getEnvFilePath,
+  loadDeviceKeyPair,
+  loadValidHostEnv,
+  requestJson,
+  sanitizeForDisplay
+} from '../bin/nc.mjs';
+import { getNcRootForMode, probeInstallRoot } from './setup.mjs';
+
+const CANONICAL_SYSTEM_ROOT = '/opt/nc';
+const DEFAULT_JOURNAL_FILE = '/var/lib/nc-cli/root-on-journal.json';
+const PRESERVED_CONFIG_FILES = ['nc-client.env', 'nc-device-key.pem', 'nc-enroll-state.json'];
+const MIGRATED_ENV_REMOVALS = /^(NC_ROOT|NC_SERVICE_MODE|NC_SERVICE_UNIT|NC_OPERATOR_USER|NC_AUDIT_FILE|NC_SERVER_LOG_FILE|NC_TUNNEL_LOG_FILE|NC_STATE_FILE|NC_CLIENT_LOG|NC_LOCAL_AUDIT_FILE)=/;
+
+const fail = (code, message) => new PairingError(code, message);
+
+/**
+ * Resolve the invoking operator's home when the command runs through sudo.
+ * The user-mode installation lives under that account, not under root's HOME.
+ * @param {{ env?: NodeJS.ProcessEnv, io?: Pick<typeof fs, 'readFileSync'> }} [options]
+ */
+export function resolveOperatorHome({ env = process.env, io = fs } = {}) {
+  const user = env.SUDO_USER || env.NC_OPERATOR_USER;
+  if (!user || user === 'root') return os.homedir();
+  try {
+    for (const line of io.readFileSync('/etc/passwd', 'utf8').split('\n')) {
+      const parts = line.split(':');
+      if (parts[0] === user && parts[5]) return parts[5];
+    }
+  } catch {}
+  return os.homedir();
+}
+
+/**
+ * Locate the existing user-mode installation for this host. Root-on never
+ * re-enrolls: a missing or mismatched identity fails closed before any
+ * mutation.
+ * @param {{ hostId: string, platform?: string, env?: NodeJS.ProcessEnv, homedir?: string, io?: typeof fs }} [options]
+ */
+export function locateUserInstallation({ hostId, platform = os.platform(), env = process.env, homedir = resolveOperatorHome({ env }), io = fs } = {}) {
+  if (!HOST_ID_RE.test(String(hostId || ''))) throw fail('INVALID_HOST_ID', 'The supplied host id is not a canonical nc_<64hex> id.');
+  const candidates = [];
+  if (env.NC_ROOT && path.resolve(env.NC_ROOT) !== CANONICAL_SYSTEM_ROOT) candidates.push(path.resolve(env.NC_ROOT));
+  candidates.push(path.resolve(getNcRootForMode('user', { platform, env: { ...env, NC_ROOT: undefined }, homedir })));
+  candidates.push(path.resolve(getNcRootForMode('user', { platform, env, homedir })));
+  let mismatch = null;
+  for (const sourceRoot of [...new Set(candidates)]) {
+    if (probeInstallRoot(sourceRoot, io) !== 'install') continue;
+    const localEnv = loadValidHostEnv(getEnvFilePath(sourceRoot));
+    if (!localEnv) continue;
+    // Root-on elevates a user-mode installation; an already-system tree is a
+    // different maintenance target, not a source to copy from.
+    if (localEnv.NC_SERVICE_MODE === 'system') continue;
+    if (localEnv.NC_CLIENT_ID !== hostId) {
+      mismatch = mismatch || localEnv.NC_CLIENT_ID;
+      continue;
+    }
+    let key;
+    try {
+      key = loadDeviceKeyPair(getDeviceKeyPath(sourceRoot));
+    } catch {
+      throw fail('ROOT_ON_IDENTITY_MISSING', `The user installation at ${sourceRoot} has no usable device key; no elevation was attempted.`);
+    }
+    return {
+      sourceRoot,
+      hostId,
+      hostToken: localEnv.NC_CLIENT_TOKEN,
+      serverUrl: String(localEnv.NC_SERVER_URL).replace(/\/$/, ''),
+      privateKey: key.privateKey
+    };
+  }
+  if (mismatch) {
+    throw fail('ROOT_ON_IDENTITY_MISMATCH', `The local installation belongs to ${sanitizeForDisplay(mismatch, 128)}, not ${sanitizeForDisplay(hostId, 128)}. No identity was replaced.`);
+  }
+  throw fail('ROOT_ON_IDENTITY_MISSING', `No user-mode installation for host ${sanitizeForDisplay(hostId, 128)} was found. Install the host in user mode first; root-on never re-enrolls.`);
+}
+
+/**
+ * Inspect the canonical system root before consuming an intent. A different
+ * installation, a partial tree, or a competing service is a typed conflict;
+ * the same host with a bound helper is an idempotent no-op.
+ * @param {{ targetRoot?: string, hostId: string, io?: typeof fs, serviceFile?: string }} [options]
+ */
+export function inspectRootOnTarget({ targetRoot = CANONICAL_SYSTEM_ROOT, hostId, io = fs, serviceFile = '/etc/systemd/system/nc-client.service' } = {}) {
+  let status;
+  try {
+    status = probeInstallRoot(targetRoot, io);
+  } catch {
+    return { state: 'conflict', reason: 'the system root cannot be inspected' };
+  }
+  if (status === 'absent') {
+    try {
+      if (io.lstatSync(serviceFile)) return { state: 'conflict', reason: 'a competing system service already exists' };
+    } catch (err) {
+      if (err?.code !== 'ENOENT') return { state: 'conflict', reason: 'the system service state cannot be inspected' };
+    }
+    return { state: 'absent' };
+  }
+  if (status !== 'install') return { state: 'conflict', reason: 'the system root is not a verifiable installation' };
+  const targetEnv = loadValidHostEnv(getEnvFilePath(targetRoot));
+  if (!targetEnv || targetEnv.NC_CLIENT_ID !== hostId) return { state: 'conflict', reason: 'the system root belongs to a different host' };
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(targetRoot, 'libexec', 'privileged-helper', 'privileged-helper.json'), 'utf8'));
+    const binding = config?.helper_key_binding;
+    if (config?.client_id === hostId && binding?.active === true &&
+        typeof binding.helper_key_binding_id === 'string' && binding.helper_key_binding_id) {
+      return { state: 'already-enabled' };
+    }
+  } catch {}
+  return { state: 'conflict', reason: 'the system root is installed but its helper is not bound' };
+}
+
+/**
+ * Consume the Owner-issued, single-use root-on intent with the existing host
+ * device identity. Authentication/tenant failures never burn the intent: the
+ * CLI makes exactly one request and the control plane owns the atomic CAS.
+ * @param {{ baseUrl: string, hostId: string, hostToken: string, privateKey: import('node:crypto').KeyObject, request?: typeof requestJson }} options
+ */
+export async function consumeRootOnIntent({ baseUrl, hostId, hostToken, privateKey, request = requestJson }) {
+  const url = `${baseUrl}/api/clients/${encodeURIComponent(hostId)}/root-on/consume`;
+  assertCredentialOrigin(url, { label: 'root-on consume URL', action: 'consume' });
+  const proof = createDeviceProofCli({ privateKey, hostId, method: 'POST', url, credential: hostToken });
+  let response;
+  try {
+    response = await request('POST', url, {}, {
+      Authorization: `NC-Device ${hostToken}`,
+      'NC-Device-Proof': proof
+    });
+  } catch (err) {
+    throw fail('ROOT_ON_AUTH_FAILED', `Could not reach the root-on consume endpoint (${sanitizeForDisplay(err instanceof Error ? err.message : String(err), 160)}). The intent was not consumed; no elevation was attempted.`);
+  }
+  const detail = sanitizeForDisplay(response?.data?.error || response?.data?.message || `HTTP ${response?.status}`, 160);
+  if (response?.status === 401 || response?.status === 403) {
+    throw fail('ROOT_ON_AUTH_FAILED', `The host identity was rejected (${detail}). The intent was not consumed; no elevation was attempted.`);
+  }
+  if (response?.status === 404 || response?.status === 409 || response?.status === 410) {
+    throw fail('ROOT_ON_INTENT_REQUIRED', `No valid Owner-issued root-on intent is available for this host (${detail}). Ask the Owner to select Admin again, then re-run before the 10-minute intent expires.`);
+  }
+  if (!response || response.status < 200 || response.status >= 300) {
+    throw fail('ROOT_ON_INTENT_INVALID', `The root-on consume request failed (${detail}). No elevation was attempted.`);
+  }
+  const data = response.data;
+  const intentId = data?.intent_id ?? data?.root_on_intent_id;
+  if (typeof intentId !== 'string' || !/^[A-Za-z0-9_.:-]{1,256}$/.test(intentId)) {
+    throw fail('ROOT_ON_INTENT_INVALID', 'The control plane returned no valid root-on intent id. No elevation was attempted.');
+  }
+  const permission = [data?.applied_permission, data?.permission?.applied_permission, data?.execution_permission?.applied_permission]
+    .find((value) => value === 'admin' || value === 'user') ?? null;
+  return { intent_id: intentId, release: data?.release && typeof data.release === 'object' ? data.release : null, permission };
+}
+
+/**
+ * Journal and copy the existing host identity into the canonical system root.
+ * The user installation is never deleted; on failure only the partial system
+ * root created by this invocation is removed.
+ * @param {{ sourceRoot: string, targetRoot?: string, hostId: string, journalFile?: string, io?: typeof fs, run?: typeof child_process.spawnSync }} options
+ */
+export function migrateUserInstallation({ sourceRoot, targetRoot = CANONICAL_SYSTEM_ROOT, hostId, journalFile = DEFAULT_JOURNAL_FILE, io = fs, run = child_process.spawnSync }) {
+  const sourceEnvPath = getEnvFilePath(sourceRoot);
+  const sourceEnv = loadValidHostEnv(sourceEnvPath);
+  if (!sourceEnv || sourceEnv.NC_CLIENT_ID !== hostId) {
+    throw fail('ROOT_ON_IDENTITY_MISMATCH', 'The user installation identity does not match the requested host id. No migration was attempted.');
+  }
+  let targetExists = false;
+  try {
+    targetExists = Boolean(io.lstatSync(targetRoot));
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw fail('ROOT_ON_CONFLICT', `The target root ${targetRoot} cannot be inspected. No migration was attempted.`);
+  }
+  if (targetExists) throw fail('ROOT_ON_CONFLICT', `A system installation already exists at ${targetRoot}. No migration was attempted.`);
+
+  const sourceEnvText = io.readFileSync(sourceEnvPath, 'utf8');
+  const envOperator = /^NC_OPERATOR_USER=([A-Za-z_][A-Za-z0-9_-]*)\s*$/m.exec(sourceEnvText)?.[1];
+  const sudoOperator = /^[A-Za-z_][A-Za-z0-9_-]*$/.test(process.env.SUDO_USER || '') ? process.env.SUDO_USER : null;
+  const operator = [envOperator, sudoOperator].find((value) => value && value !== 'root') || null;
+  const userSystemctl = (args) => {
+    if (!operator) return;
+    try { run('/usr/bin/runuser', ['-u', operator, '--', '/usr/bin/systemctl', '--user', ...args], { stdio: 'ignore' }); } catch {}
+  };
+  const journal = { version: 1, host_id: hostId, source_root: sourceRoot, target_root: targetRoot, created_at: new Date().toISOString(), steps: [] };
+  const writeJournal = (step) => {
+    journal.steps.push(step);
+    io.writeFileSync(journalFile, JSON.stringify(journal) + '\n', { mode: 0o600 });
+  };
+  const rollback = () => {
+    userSystemctl(['enable', '--now', 'nc-client.service']);
+    for (const args of [
+      ['disable', '--now', 'nc-client.service'],
+      ['disable', '--now', 'nc-privileged-helper.socket'],
+      ['disable', '--now', 'nc-privileged-helper.service']
+    ]) {
+      try { run('/usr/bin/systemctl', args, { stdio: 'ignore' }); } catch {}
+    }
+    try { io.rmSync(targetRoot, { recursive: true, force: true }); } catch {}
+    try { io.rmSync(journalFile, { force: true }); } catch {}
+  };
+
+  try {
+    io.mkdirSync(path.dirname(journalFile), { recursive: true, mode: 0o750 });
+    writeJournal('start');
+    io.mkdirSync(path.join(targetRoot, 'config'), { recursive: true, mode: 0o750 });
+    io.mkdirSync(path.join(targetRoot, 'logs'), { recursive: true, mode: 0o750 });
+    writeJournal('directories');
+    // Stop the existing user-scope agent so the same identity is not served by
+    // two installations. Best-effort: a missing/headless user manager does not
+    // block the migration, and rollback re-enables it.
+    userSystemctl(['disable', '--now', 'nc-client.service']);
+    writeJournal('stop-user-service');
+    const envText = sourceEnvText
+      .split(/\r?\n/)
+      .filter((line) => !MIGRATED_ENV_REMOVALS.test(line))
+      .join('\n');
+    io.writeFileSync(path.join(targetRoot, 'config', 'nc-client.env'), envText.endsWith('\n') ? envText : envText + '\n', { mode: 0o600 });
+    writeJournal('copy:nc-client.env');
+    for (const name of PRESERVED_CONFIG_FILES.filter((name) => name !== 'nc-client.env')) {
+      const source = path.join(sourceRoot, 'config', name);
+      let info;
+      try {
+        info = io.lstatSync(source);
+      } catch (err) {
+        if (err?.code === 'ENOENT') continue;
+        throw err;
+      }
+      if (!info.isFile() || info.isSymbolicLink() || info.size > 65536) throw new Error(`${name} is not a bounded regular file`);
+      const destination = path.join(targetRoot, 'config', name);
+      io.copyFileSync(source, destination);
+      io.chmodSync(destination, 0o600);
+      writeJournal(`copy:${name}`);
+    }
+    const audit = path.join(sourceRoot, 'logs', 'audit.jsonl');
+    try {
+      if (io.lstatSync(audit).isFile()) {
+        io.copyFileSync(audit, path.join(targetRoot, 'logs', 'audit.jsonl'));
+        io.chmodSync(path.join(targetRoot, 'logs', 'audit.jsonl'), 0o600);
+        writeJournal('copy:audit.jsonl');
+      }
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err;
+    }
+    writeJournal('complete');
+  } catch (err) {
+    rollback();
+    if (err instanceof PairingError) throw err;
+    throw fail('ROOT_ON_MIGRATION_FAILED', `User-to-system migration failed (${sanitizeForDisplay(err instanceof Error ? err.message : String(err), 160)}). The user installation was preserved and the partial system root was rolled back.`);
+  }
+  return { targetRoot, journalFile, rollback };
+}
+
+/**
+ * One-time local elevation. Requires an interactive TTY and real root even
+ * when already root (the explicit confirmation is the local authorization),
+ * rejects unsupported platforms and missing identities with typed errors, and
+ * never accepts secrets on the command line.
+ * @param {{ hostId: string, platform?: string, input?: import('node:stream').Readable, output?: import('node:stream').Writable, geteuid?: () => number, confirm?: (question: string) => Promise<boolean>, identity?: Record<string, unknown>, targetRoot?: string, deps?: Record<string, Function> }} [options]
+ */
+export async function runRootOn({
+  hostId,
+  platform = os.platform(),
+  input = process.stdin,
+  output = process.stdout,
+  geteuid = process.geteuid?.bind(process),
+  confirm = null,
+  identity = null,
+  targetRoot = CANONICAL_SYSTEM_ROOT,
+  deps = {}
+} = {}) {
+  if (!HOST_ID_RE.test(String(hostId || ''))) throw fail('INVALID_HOST_ID', 'The supplied host id is not a canonical nc_<64hex> id.');
+  if (platform !== 'linux') {
+    throw fail('ROOT_ON_UNSUPPORTED_PLATFORM', 'The privileged helper elevation path is Linux-only. This host remains User-only and does not claim Admin readiness.');
+  }
+  if (!input?.isTTY || !output?.isTTY) {
+    throw fail('ROOT_ON_NON_INTERACTIVE', 'Root-on requires an interactive terminal and explicit local confirmation; no elevation was attempted.');
+  }
+  if (typeof geteuid !== 'function' || geteuid() !== 0) {
+    throw fail('ROOT_ON_NOT_ROOT', 'Root-on requires real root/administrator rights; run it with sudo. No elevation was attempted.');
+  }
+
+  const inspectTarget = deps.inspectTarget || inspectRootOnTarget;
+  const target = inspectTarget({ targetRoot, hostId });
+  if (target?.state === 'already-enabled') return { alreadyEnabled: true, hostId, helperReady: true, adminReady: false };
+  if (target?.state !== 'absent') {
+    throw fail('ROOT_ON_CONFLICT', `Root-on refused: ${target?.reason || 'a conflicting system installation exists'}. Neither installation was changed.`);
+  }
+
+  const activeIdentity = identity || (deps.locateIdentity || locateUserInstallation)({ hostId, platform });
+  if (!activeIdentity?.hostToken || !activeIdentity?.privateKey || !activeIdentity?.serverUrl) {
+    throw fail('ROOT_ON_IDENTITY_MISSING', 'The existing host identity is incomplete; root-on never re-enrolls. No elevation was attempted.');
+  }
+
+  const ask = confirm || confirmPrompt;
+  const confirmed = await ask(`Elevate host ${sanitizeForDisplay(hostId, 128)} to a system install and bind the privileged helper? [y/N] `);
+  if (confirmed !== true) throw fail('ROOT_ON_CONFIRMATION_DECLINED', 'No elevation was performed.');
+
+  const consume = deps.consumeIntent || consumeRootOnIntent;
+  const consumed = await consume({ baseUrl: activeIdentity.serverUrl, hostId, hostToken: activeIdentity.hostToken, privateKey: activeIdentity.privateKey });
+  if (!consumed?.intent_id) throw fail('ROOT_ON_INTENT_INVALID', 'No valid root-on intent was returned. No elevation was attempted.');
+
+  const migrate = deps.migrate || migrateUserInstallation;
+  const migrated = await migrate({ sourceRoot: activeIdentity.sourceRoot, targetRoot, hostId, journalFile: deps.journalFile });
+  try {
+    const install = deps.installAgent || downloadAndInstallAgent;
+    const result = await install({
+      ncRoot: targetRoot,
+      serverUrl: activeIdentity.serverUrl,
+      installMode: 'system',
+      rootConsent: true,
+      hostId,
+      hostToken: activeIdentity.hostToken,
+      privateKey: activeIdentity.privateKey,
+      rootOnIntentId: consumed.intent_id,
+      release: consumed.release || undefined
+    });
+    return {
+      hostId,
+      helperReady: result?.helperBinding?.bound === true,
+      // Admin-ready is claimed only from post-binding control-plane evidence,
+      // never from the pre-consumption intent answer (the Owner may have
+      // reverted Admin while the local install was running).
+      adminReady: result?.helperBinding?.bound === true && result?.helperBinding?.applied_permission === 'admin',
+      helperBinding: result?.helperBinding ?? null,
+      intentId: consumed.intent_id
+    };
+  } catch (err) {
+    try { migrated?.rollback?.(); } catch {}
+    throw err;
+  }
+}

package/lib/setup.mjs

@@ -194,6 +194,31 @@ export function canElevate(options = {}) {
   }
 }
 
+/**
+ * Resolve the single local root decision into the final install mode and the
+ * elevation requirement. `--user` is always user mode and never asks. An
+ * explicit Y without usable elevation is a typed failure: the caller must not
+ * silently downgrade to a user install because that would leave the requested
+ * Admin helper unprovisioned.
+ * @param {{ forceUser?: boolean, explicitOptIn?: boolean, answer?: boolean, platform?: string, elevated?: boolean, elevationAvailable?: boolean }} [options]
+ * @returns {{ rootConsent: boolean, installMode: 'system'|'user', elevationRequired: boolean, error: string|null }}
+ */
+export function resolveInstallConsent({ forceUser = false, explicitOptIn = false, answer = false, platform = os.platform(), elevated = false, elevationAvailable = false } = {}) {
+  if (forceUser === true) return { rootConsent: false, installMode: 'user', elevationRequired: false, error: null };
+  const rootConsent = explicitOptIn === true || answer === true;
+  if (!rootConsent) return { rootConsent: false, installMode: 'user', elevationRequired: false, error: null };
+  if (elevated === true) return { rootConsent: true, installMode: 'system', elevationRequired: false, error: null };
+  // macOS keeps its existing no-automatic-sudo contract; a privileged system
+  // install must be started explicitly by an administrator.
+  if (platform !== 'linux' && platform !== 'win32') {
+    return { rootConsent: true, installMode: 'system', elevationRequired: false, error: 'ROOT_ELEVATION_REQUIRED' };
+  }
+  if (elevationAvailable !== true) {
+    return { rootConsent: true, installMode: 'system', elevationRequired: false, error: 'ROOT_ELEVATION_REQUIRED' };
+  }
+  return { rootConsent: true, installMode: 'system', elevationRequired: true, error: null };
+}
+
 /**
  * Warning text for the given mode: a single line for user mode, null for
  * system mode (callers assert presence/absence on this, not on stdout).
@@ -494,7 +519,7 @@ const PARTIAL_ENROLLMENT_REQUIRED = ['nc-device-key.pem', 'nc-enroll-state.json'
  * @param {string} root
  * @param {typeof fs} [io]
  */
-function partialEnrollmentSystemRoot(root, io = fs) {
+export function partialEnrollmentSystemRoot(root, io = fs) {
   if (path.resolve(root) !== PARTIAL_SYSTEM_ROOT) return false;
   const lstat = io.lstatSync || fs.lstatSync;
   const readdir = io.readdirSync || fs.readdirSync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-command",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {