node-command 2.0.11 → 2.0.13

package/bin/nc.mjs

@@ -24,7 +24,9 @@ import {
   isPartialSystemRemovalCandidate,
   isPartialUserRemovalCandidate,
   isUserInstallRoot,
+  incompleteSystemInstallationShape,
   probeInstallRoot,
+  removeIncompleteSystemInstallation,
   removePartialSystemRoot,
   removePartialUserRoot,
   resolveExecutable,
@@ -3118,20 +3120,25 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
   }
   for (const root of removable) {
     const pair = paired.find(selected => selected.ncRoot === root);
+    // A pending-helper or failed-install system tree is removed by the narrow
+    // bounded path below even when its packaged entry still exists: the
+    // protected drain requires lifecycle custody those shapes never created.
+    const incompleteShape = !pair && os.platform() === 'linux' ? incompleteSystemInstallationShape(root) : null;
     const script = pair ? LINUX_PAIRED_UNINSTALL_ENTRY : uninstallerForRoot(root);
     // A failed per-user install can leave its own tree (config plus partial
     // payload) without the packaged uninstaller. Only the canonical user root
     // is eligible, and the bounded removal revalidates ancestry, ownership and
     // every top-level entry. Real system installs never use this fallback;
     // the exact /opt/nc partial tree has its own narrower root-only exception.
-    const scriptExists = pair || fs.existsSync(script);
     const explicitRemoval = command === 'uninstall' || command === 'remove';
+    const incompleteSystemTree = incompleteShape !== null && explicitRemoval && isPartialSystemRemovalCandidate(root);
+    const scriptExists = pair || incompleteSystemTree || fs.existsSync(script);
     const partialUserTree = !scriptExists && explicitRemoval && isPartialUserRemovalCandidate(root);
     // The narrow system exception is /opt/nc only, requires real+effective
     // root, and refuses app/, uninstall.sh, units, libexec/ and lifecycle
     // metadata inside removePartialSystemRoot.
     const partialSystemTree = !scriptExists && explicitRemoval && isPartialSystemRemovalCandidate(root);
-    const boundedTree = partialUserTree || partialSystemTree;
+    const boundedTree = partialUserTree || partialSystemTree || incompleteSystemTree;
     if (!scriptExists && !boundedTree) {
       console.error(`error: [UNINSTALLER_MISSING] uninstaller not found at ${script}; skipping ${root}.`);
       console.error(uninstallFailureSuggestion());
@@ -3149,15 +3156,18 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
     try {
       if (boundedTree) {
         try {
-          if (partialSystemTree) removePartialSystemRoot(root);
+          if (incompleteSystemTree) removeIncompleteSystemInstallation(root);
+          else if (partialSystemTree) removePartialSystemRoot(root);
           else removePartialUserRoot(root);
-          console.log(partialSystemTree
-            ? `Removed partial system Node Command installation at ${root} (no packaged uninstaller, unit or application payload).`
-            : `Removed partial per-user Node Command installation at ${root} (no packaged uninstaller was present).`);
+          console.log(incompleteSystemTree
+            ? `Removed ${incompleteShape.kind === 'pending-helper' ? 'pending-helper' : 'failed'} system Node Command installation at ${root} (exact unit/bounded tree only).`
+            : partialSystemTree
+              ? `Removed partial system Node Command installation at ${root} (no packaged uninstaller, unit or application payload).`
+              : `Removed partial per-user Node Command installation at ${root} (no packaged uninstaller was present).`);
         } catch (err) {
           const code = typeof err?.code === 'string' && /_REFUSED$/.test(err.code) ? err.code : 'PARTIAL_ROOT_REMOVAL_REFUSED';
           console.error(`error: [${code}] ${sanitizeForDisplay(err instanceof Error ? err.message : String(err), 300)}`);
-          console.error(partialSystemTree
+          console.error(incompleteSystemTree || partialSystemTree
             ? 'suggested_action: The system tree was left untouched. Inspect /opt/nc and complete or repair the failed system installation through explicit root maintenance; credentials/config were preserved.'
             : 'suggested_action: The tree was left untouched. Repair it with `nodecommand --user`, or remove it yourself after confirming it is your own Node Command directory.');
           failed += 1;

package/lib/setup.mjs

@@ -479,6 +479,42 @@ const PARTIAL_SYSTEM_FORBIDDEN_PATHS = [
   '/var/lib/nodecommand/nc'
 ];
 
+/** Files a rejected/expired enrollment may leave in the system config tree. */
+const PARTIAL_ENROLLMENT_CONFIG_ENTRIES = new Set(['.nc-cli.lock', 'nc-device-key.pem', 'nc-enroll-state.json']);
+
+/** The exact residue that identifies the narrow recoverable enrollment shape. */
+const PARTIAL_ENROLLMENT_REQUIRED = ['nc-device-key.pem', 'nc-enroll-state.json'];
+
+/**
+ * True only for the exact canonical system root carrying the residue of a
+ * rejected/expired enrollment: a root-owned config directory with the device
+ * key and enrollment state, no host environment, and no application payload.
+ * Discovery uses this so the abandoned tree is a removal target; removal
+ * revalidates every entry before deleting anything.
+ * @param {string} root
+ * @param {typeof fs} [io]
+ */
+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;
+  try {
+    if (!readdir(PARTIAL_SYSTEM_ROOT).every((name) => PARTIAL_SYSTEM_ENTRIES.has(name))) return false;
+    const config = path.join(PARTIAL_SYSTEM_ROOT, 'config');
+    const configInfo = lstat(config);
+    if (configInfo.isSymbolicLink() || !configInfo.isDirectory()) return false;
+    const names = readdir(config);
+    if (!names.every((name) => PARTIAL_ENROLLMENT_CONFIG_ENTRIES.has(name))) return false;
+    if (!PARTIAL_ENROLLMENT_REQUIRED.every((name) => names.includes(name))) return false;
+    return PARTIAL_ENROLLMENT_REQUIRED.every((name) => {
+      const entry = lstat(path.join(config, name));
+      return !entry.isSymbolicLink() && entry.isFile();
+    });
+  } catch {
+    return false;
+  }
+}
+
 /**
  * True when `root` is the canonical per-user tree for the current account and
  * is not a protected system root. This is the cheap path/ownership gate; the
@@ -522,8 +558,43 @@ export function isPartialSystemRemovalCandidate(root, { platform = os.platform()
   return path.resolve(root) === PARTIAL_SYSTEM_ROOT;
 }
 
+/** A real installation is proven by a readable, owner-matching host env. */
+function requireHostEnvironment(root, { uid, io, refused, owner }) {
+  for (const [file, directory] of [['config', true], [path.join('config', 'nc-client.env'), false]]) {
+    const info = io.lstatSync(path.join(root, file));
+    if (info.isSymbolicLink() || (directory ? !info.isDirectory() : !info.isFile())) {
+      throw refused(`the ${file} marker is missing or not a regular ${directory ? 'directory' : 'file'}`);
+    }
+    if (info.uid !== uid) throw refused(`the ${file} marker is not owned by ${owner}`);
+  }
+  io.accessSync(path.join(root, 'config', 'nc-client.env'), fs.constants.R_OK);
+}
+
+/**
+ * A rejected/expired enrollment leaves only the device key and enrollment
+ * state (plus this process's own CLI lock) in config/. A host environment, an
+ * app payload or any unknown file means this is not the narrow recoverable
+ * shape, so removal fails closed.
+ */
+function requirePartialEnrollment(root, { uid, io, refused, owner }) {
+  const config = path.join(root, 'config');
+  const info = io.lstatSync(config);
+  if (info.isSymbolicLink() || !info.isDirectory()) throw refused('the config marker is missing or not a regular directory');
+  if (info.uid !== uid) throw refused(`the config marker is not owned by ${owner}`);
+  const names = io.readdirSync(config);
+  for (const name of names) {
+    if (!PARTIAL_ENROLLMENT_CONFIG_ENTRIES.has(name)) throw refused(`unexpected config entry "${name}"`);
+    const entry = io.lstatSync(path.join(config, name));
+    if (entry.isSymbolicLink() || !entry.isFile()) throw refused(`config entry "${name}" is not a regular file`);
+    if (entry.uid !== uid) throw refused(`config entry "${name}" is not owned by ${owner}`);
+  }
+  for (const name of PARTIAL_ENROLLMENT_REQUIRED) {
+    if (!names.includes(name)) throw refused(`the partial-enrollment marker "${name}" is missing`);
+  }
+}
+
 /** Shared bounded removal of an already-authorized root. */
-function removeBoundedRoot(root, { uid, allowedEntries, io, refused, owner }) {
+function removeBoundedRoot(root, { uid, allowedUids = null, allowedEntries, io, refused, owner, verifyConfig = requireHostEnvironment }) {
   const resolved = path.resolve(root);
   if (io.realpathSync(resolved) !== resolved) throw refused('a symlinked ancestor is not removable');
   const rootInfo = io.lstatSync(resolved);
@@ -534,16 +605,9 @@ function removeBoundedRoot(root, { uid, allowedEntries, io, refused, owner }) {
     if (!allowedEntries.has(name)) throw refused(`unexpected top-level entry "${name}"`);
     const info = io.lstatSync(path.join(resolved, name));
     if (info.isSymbolicLink()) throw refused(`top-level entry "${name}" is a symlink`);
-    if (info.uid !== uid) throw refused(`top-level entry "${name}" is not owned by ${owner}`);
+    if (allowedUids ? !allowedUids.has(info.uid) : info.uid !== uid) throw refused(`top-level entry "${name}" is not owned by ${owner}`);
   }
-  for (const [file, directory] of [['config', true], [path.join('config', 'nc-client.env'), false]]) {
-    const info = io.lstatSync(path.join(resolved, file));
-    if (info.isSymbolicLink() || (directory ? !info.isDirectory() : !info.isFile())) {
-      throw refused(`the ${file} marker is missing or not a regular ${directory ? 'directory' : 'file'}`);
-    }
-    if (info.uid !== uid) throw refused(`the ${file} marker is not owned by ${owner}`);
-  }
-  io.accessSync(path.join(resolved, 'config', 'nc-client.env'), fs.constants.R_OK);
+  verifyConfig(resolved, { uid, io, refused, owner });
   for (const name of entries) {
     io.rmSync(path.join(resolved, name), { recursive: true, force: true });
   }
@@ -609,12 +673,22 @@ export function removePartialSystemRoot(root, { platform = os.platform(), getuid
       }
       throw refused(`${file} exists; a real installation requires its packaged maintenance`);
     }
-    removeBoundedRoot(path.resolve(root), {
+    const resolved = path.resolve(root);
+    const hostEnvMarker = path.join(resolved, 'config', 'nc-client.env');
+    let verifyConfig = requireHostEnvironment;
+    try {
+      io.lstatSync(hostEnvMarker);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw refused(`the host environment marker at ${hostEnvMarker} cannot be verified`);
+      verifyConfig = requirePartialEnrollment;
+    }
+    removeBoundedRoot(resolved, {
       uid: 0,
       allowedEntries: PARTIAL_SYSTEM_ENTRIES,
       io,
       refused,
-      owner: 'root'
+      owner: 'root',
+      verifyConfig
     });
   } catch (err) {
     if (err?.code === 'PARTIAL_SYSTEM_REMOVAL_REFUSED') throw err;
@@ -622,6 +696,297 @@ export function removePartialSystemRoot(root, { platform = os.platform(), getuid
   }
 }
 
+/** Top-level entries a real system install may contain. */
+const INCOMPLETE_SYSTEM_ENTRIES = new Set([
+  'app', 'config', 'data', 'logs', 'releases', 'backups', 'tmp', 'tools', 'libexec', 'uninstall.sh', 'install-linux.sh'
+]);
+
+const INCOMPLETE_SYSTEM_LAUNCHER = '/opt/nc/app/launcher.mjs';
+const INCOMPLETE_SYSTEM_NODE = '/opt/nc/tools/node/bin/node';
+const INCOMPLETE_SYSTEM_HOST_ENV = '/opt/nc/config/nc-client.env';
+const INCOMPLETE_SYSTEM_UNIT = '/etc/systemd/system/nc-client.service';
+const INCOMPLETE_SYSTEM_UNIT_DROPIN = '/etc/systemd/system/nc-client.service.d';
+const INCOMPLETE_HELPER_APP = '/opt/nc/libexec/privileged-helper';
+const INCOMPLETE_HELPER_DAEMON = INCOMPLETE_HELPER_APP + '/privileged-helper-linux-daemon.mjs';
+const INCOMPLETE_HELPER_PROFILE = INCOMPLETE_HELPER_APP + '/privileged-helper-profile.json';
+const INCOMPLETE_HELPER_UNIT = '/etc/systemd/system/nc-privileged-helper.service';
+const INCOMPLETE_HELPER_UNIT_DROPIN = '/etc/systemd/system/nc-privileged-helper.service.d';
+const INCOMPLETE_HELPER_SOCKET = '/etc/systemd/system/nc-privileged-helper.socket';
+const INCOMPLETE_HELPER_SOCKET_DROPIN = '/etc/systemd/system/nc-privileged-helper.socket.d';
+const INCOMPLETE_HELPER_TMPFILES = '/etc/tmpfiles.d/nc-privileged-helper.conf';
+const INCOMPLETE_HELPER_SOCKET_PATH = '/run/nc/privileged-helper-v1.sock';
+const INCOMPLETE_SYSTEM_LIFECYCLE = '/var/lib/nc-lifecycle';
+const INCOMPLETE_SYSTEM_PAIRED_ROOT = '/var/lib/nodecommand/nc';
+
+const SYSTEM_BOOTSTRAP_FIELDS = [
+  'client_id', 'control_plane_id', 'tenant_id', 'root_consent', 'ack_private_key_file', 'helper_key_id',
+  'helper_key_binding_id', 'binding_state', 'node_bin', 'ordinary_root', 'ordinary_service_scope', 'lifecycle_custody_state'
+];
+
+const systemLstat = (io) => io.lstatSync || fs.lstatSync;
+const systemRealpath = (io) => io.realpathSync || fs.realpathSync;
+const systemReaddir = (io) => io.readdirSync || fs.readdirSync;
+
+function systemLstatOrNull(io, file) {
+  try { return systemLstat(io)(file); } catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
+}
+
+/** Read a fixed protected file with root-only metadata and an exclusive fd. */
+function readSystemFile(io, file, { uids = new Set([0]), mode = null, max = 65536 } = {}) {
+  const info = systemLstat(io)(file);
+  if (info.isSymbolicLink() || !info.isFile() || !uids.has(info.uid) || info.nlink !== 1 ||
+      (info.mode & 0o022) || (mode !== null && (info.mode & 0o7777) !== mode) ||
+      !Number.isSafeInteger(info.size) || info.size <= 0 || info.size > max) throw new Error('unprotected');
+  if (systemRealpath(io)(file) !== file) throw new Error('noncanonical');
+  const fd = (io.openSync || fs.openSync)(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const checked = (io.fstatSync || fs.fstatSync)(fd);
+    if (checked.dev !== info.dev || checked.ino !== info.ino || checked.size !== info.size ||
+        checked.uid !== info.uid || checked.nlink !== 1) throw new Error('changed');
+    const text = String((io.readFileSync || fs.readFileSync)(fd, 'utf8'));
+    if (Buffer.byteLength(text) !== info.size) throw new Error('changed');
+    return text;
+  } finally { (io.closeSync || fs.closeSync)(fd); }
+}
+
+const systemUnitValues = (text, key) => text.split(/\r?\n/)
+  .filter((line) => line.startsWith(key + '=')).map((line) => line.slice(key.length + 1));
+
+function systemExecStart(value) {
+  const match = /^(?:"([^"\n]+)"|([^\s]+))\s+(?:"([^"\n]+)"|([^\s]+))\s*$/.exec(value);
+  return match ? { runtime: match[1] || match[2], launcher: match[3] || match[4] } : null;
+}
+
+const systemCanonical = (value) => typeof value === 'string' && path.isAbsolute(value) &&
+  path.resolve(value) === value && !/[\x00-\x1f\x7f]/.test(value);
+
+/** A unit runtime may be the canonical path or an equivalent symlink to it. */
+function systemRuntimeMatches(io, actual, runtime) {
+  if (actual === runtime) return true;
+  if (!systemCanonical(actual)) return false;
+  try { return systemRealpath(io)(actual) === runtime; } catch { return false; }
+}
+
+/** Verify the exact ordinary client unit this tree produced. */
+function systemValidateClientUnit(io, runtime) {
+  if (systemLstatOrNull(io, INCOMPLETE_SYSTEM_UNIT_DROPIN)) throw new Error('unit drop-in');
+  const text = readSystemFile(io, INCOMPLETE_SYSTEM_UNIT);
+  const directories = systemUnitValues(text, 'WorkingDirectory');
+  const launches = systemUnitValues(text, 'ExecStart');
+  const launch = launches.length === 1 ? systemExecStart(launches[0]) : null;
+  if (directories.length !== 1 || !['/opt/nc', '/opt/nc/app'].includes(directories[0]) ||
+      !launch || launch.launcher !== INCOMPLETE_SYSTEM_LAUNCHER || !systemRuntimeMatches(io, launch.runtime, runtime))
+    throw new Error('foreign client unit');
+  for (const key of ['User', 'Group']) {
+    const values = systemUnitValues(text, key);
+    if (values.length !== 1 || values[0] !== 'nodecommand') throw new Error('foreign client identity');
+  }
+}
+
+/** Verify the exact helper socket/service/tmpfiles that point at this tree. */
+function systemValidateHelperArtifacts(io, runtime) {
+  if (systemLstatOrNull(io, INCOMPLETE_HELPER_UNIT_DROPIN) || systemLstatOrNull(io, INCOMPLETE_HELPER_SOCKET_DROPIN))
+    throw new Error('helper drop-in');
+  const service = systemLstatOrNull(io, INCOMPLETE_HELPER_UNIT);
+  const socket = systemLstatOrNull(io, INCOMPLETE_HELPER_SOCKET);
+  if (!!service !== !!socket) throw new Error('incomplete helper unit pair');
+  let group = null;
+  if (service) {
+    const text = readSystemFile(io, INCOMPLETE_HELPER_UNIT);
+    const directories = systemUnitValues(text, 'WorkingDirectory');
+    const launches = systemUnitValues(text, 'ExecStart');
+    const launch = launches.length === 1 ? systemExecStart(launches[0]) : null;
+    if (directories.length !== 1 || directories[0] !== INCOMPLETE_HELPER_APP ||
+        !launch || launch.launcher !== INCOMPLETE_HELPER_DAEMON || !systemRuntimeMatches(io, launch.runtime, runtime))
+      throw new Error('foreign helper unit');
+    for (const key of ['User', 'Group']) {
+      const values = systemUnitValues(text, key);
+      if (values.length !== 1 || values[0] !== 'root') throw new Error('foreign helper identity');
+    }
+    const socketText = readSystemFile(io, INCOMPLETE_HELPER_SOCKET);
+    const listen = systemUnitValues(socketText, 'ListenStream');
+    const services = systemUnitValues(socketText, 'Service');
+    const groups = systemUnitValues(socketText, 'SocketGroup');
+    const removeOnStop = systemUnitValues(socketText, 'RemoveOnStop');
+    if (listen.length !== 1 || listen[0] !== INCOMPLETE_HELPER_SOCKET_PATH || services.length > 1 ||
+        (services[0] !== undefined && services[0] !== 'nc-privileged-helper.service') ||
+        groups.length !== 1 || !/^[a-z_][a-z0-9_-]*[$]?$/.test(groups[0]) ||
+        removeOnStop.length !== 1 || removeOnStop[0] !== 'true') throw new Error('foreign helper socket');
+    group = groups[0];
+  }
+  const tmpfiles = systemLstatOrNull(io, INCOMPLETE_HELPER_TMPFILES);
+  if (tmpfiles) {
+    if (!group) throw new Error('orphan helper tmpfiles');
+    const text = readSystemFile(io, INCOMPLETE_HELPER_TMPFILES);
+    if (text.trim() !== `d /run/nc 0750 root ${group} -`) throw new Error('foreign helper tmpfiles');
+  }
+  return { service: !!service, tmpfiles: !!tmpfiles };
+}
+
+/**
+ * Recognize the two root-recoverable system-install leftovers this CLI may
+ * remove without the packaged maintenance entry: a helper provisioned but
+ * never bound (`pending`/`not_initialized`, no profile, no lifecycle custody)
+ * and a failed install whose app payload never landed but whose stale unit
+ * remains. Anything else returns null so callers keep failing closed.
+ * @param {string} root
+ * @param {{ platform?: string, io?: typeof fs }} [options]
+ * @returns {null | { kind: 'pending-helper'|'failed-install', runtime: string, payloadUid: number, helperArtifacts: { service: boolean, tmpfiles: boolean } }}
+ */
+export function incompleteSystemInstallationShape(root, { platform = os.platform(), io = fs } = {}) {
+  if (platform !== 'linux' || path.resolve(root) !== PARTIAL_SYSTEM_ROOT) return null;
+  try {
+    const lstat = systemLstat(io);
+    if (systemRealpath(io)(root) !== root) return null;
+    const rootInfo = lstat(root);
+    if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory() || rootInfo.uid !== 0 || (rootInfo.mode & 0o022)) return null;
+    const names = systemReaddir(io)(root);
+    if (names.length === 0 || !names.every((name) => INCOMPLETE_SYSTEM_ENTRIES.has(name))) return null;
+    const appInfo = systemLstatOrNull(io, path.join(root, 'app'));
+    if (!appInfo || appInfo.isSymbolicLink() || !appInfo.isDirectory()) return null;
+    let payloadUid = appInfo.uid;
+    const configInfo = systemLstatOrNull(io, path.join(root, 'config'));
+    if (configInfo) {
+      if (configInfo.isSymbolicLink() || !configInfo.isDirectory()) return null;
+      payloadUid = configInfo.uid;
+    }
+    for (const name of names) {
+      const info = lstat(path.join(root, name));
+      if (info.isSymbolicLink() || (info.uid !== 0 && info.uid !== payloadUid)) return null;
+    }
+    const helper = systemLstatOrNull(io, INCOMPLETE_HELPER_APP);
+    if (helper) {
+      if (helper.isSymbolicLink() || !helper.isDirectory() || helper.uid !== 0 || (helper.mode & 0o022)) return null;
+      // A bound/prepared helper, external lifecycle custody or the other
+      // ordinary root all require their own trusted maintenance.
+      if (systemLstatOrNull(io, INCOMPLETE_HELPER_PROFILE) || systemLstatOrNull(io, INCOMPLETE_SYSTEM_LIFECYCLE) ||
+          systemLstatOrNull(io, INCOMPLETE_SYSTEM_PAIRED_ROOT)) return null;
+      const bootstrap = JSON.parse(readSystemFile(io, INCOMPLETE_HELPER_APP + '/helper-bootstrap.json', { mode: 0o600 }));
+      const controlPlaneId = (value) => typeof value === 'string' && value.length > 0 && value.length <= 256 &&
+        value.trim() === value && !/[\x00-\x1f\x7f]/.test(value);
+      const id = (value) => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/.test(value);
+      if (!bootstrap || typeof bootstrap !== 'object' || Array.isArray(bootstrap) ||
+          Object.keys(bootstrap).length !== SYSTEM_BOOTSTRAP_FIELDS.length ||
+          !SYSTEM_BOOTSTRAP_FIELDS.every((field) => Object.hasOwn(bootstrap, field)) ||
+          !/^nc_[0-9a-f]{64}$/.test(bootstrap.client_id) || !controlPlaneId(bootstrap.control_plane_id) ||
+          !id(bootstrap.tenant_id) || !id(bootstrap.helper_key_id) || bootstrap.root_consent !== true ||
+          bootstrap.helper_key_binding_id !== null || bootstrap.binding_state !== 'pending' ||
+          bootstrap.lifecycle_custody_state !== 'not_initialized' || bootstrap.ordinary_root !== root ||
+          bootstrap.ordinary_service_scope !== 'system' ||
+          bootstrap.ack_private_key_file !== INCOMPLETE_HELPER_APP + '/privileged-helper-ack-key.pem' ||
+          !systemCanonical(bootstrap.node_bin)) return null;
+      readSystemFile(io, INCOMPLETE_HELPER_APP + '/privileged-helper.json', { mode: 0o600 });
+      readSystemFile(io, INCOMPLETE_HELPER_APP + '/privileged-helper-ack-key.pem', { mode: 0o600 });
+      readSystemFile(io, INCOMPLETE_HELPER_APP + '/privileged-helper-public.pem', { mode: 0o644 });
+      const peercred = systemLstatOrNull(io, '/opt/nc/libexec/nc-linux-peercred');
+      if (!peercred || peercred.isSymbolicLink() || !peercred.isFile() || peercred.uid !== 0 || peercred.nlink !== 1) return null;
+      const daemon = systemLstatOrNull(io, INCOMPLETE_HELPER_DAEMON);
+      if (!daemon || daemon.isSymbolicLink() || !daemon.isFile() || daemon.uid !== 0 || !(daemon.mode & 0o111)) return null;
+      readSystemFile(io, INCOMPLETE_SYSTEM_LAUNCHER, { uids: new Set([0, payloadUid]) });
+      const hostEnv = readSystemFile(io, INCOMPLETE_SYSTEM_HOST_ENV, { uids: new Set([0, payloadUid]) });
+      const ids = hostEnv.split(/\r?\n/).filter((line) => /^\s*NC_CLIENT_ID\s*=/.test(line));
+      const clientId = ids[0]?.match(/^\s*NC_CLIENT_ID\s*=\s*(?:"(nc_[0-9a-f]{64})"|'(nc_[0-9a-f]{64})'|(nc_[0-9a-f]{64}))\s*$/);
+      if (ids.length !== 1 || !clientId || (clientId[1] || clientId[2] || clientId[3]) !== bootstrap.client_id) return null;
+      systemValidateClientUnit(io, bootstrap.node_bin);
+      const helperArtifacts = systemValidateHelperArtifacts(io, bootstrap.node_bin);
+      return Object.freeze({ kind: 'pending-helper', runtime: bootstrap.node_bin, payloadUid, helperArtifacts });
+    }
+    // Failed-install shape: no helper payload, no packaged uninstaller, and an
+    // exactly matching stale unit whose launcher never landed (or is empty).
+    if (systemLstatOrNull(io, '/opt/nc/libexec/nc-linux-peercred')) return null;
+    if (systemLstatOrNull(io, path.join(root, 'uninstall.sh'))) return null;
+    for (const artifact of [INCOMPLETE_HELPER_UNIT, INCOMPLETE_HELPER_SOCKET, INCOMPLETE_HELPER_TMPFILES])
+      if (systemLstatOrNull(io, artifact)) return null;
+    if (systemLstatOrNull(io, INCOMPLETE_SYSTEM_LIFECYCLE) || systemLstatOrNull(io, INCOMPLETE_SYSTEM_PAIRED_ROOT)) return null;
+    const libexec = systemLstatOrNull(io, path.join(root, 'libexec'));
+    if (libexec) {
+      if (libexec.isSymbolicLink() || !libexec.isDirectory() || systemReaddir(io)(path.join(root, 'libexec')).length !== 0) return null;
+    }
+    const launcher = systemLstatOrNull(io, INCOMPLETE_SYSTEM_LAUNCHER);
+    if (launcher && (launcher.isSymbolicLink() || !launcher.isFile() || launcher.size !== 0 ||
+        (launcher.uid !== 0 && launcher.uid !== payloadUid))) return null;
+    systemValidateClientUnit(io, INCOMPLETE_SYSTEM_NODE);
+    return Object.freeze({
+      kind: 'failed-install',
+      runtime: INCOMPLETE_SYSTEM_NODE,
+      payloadUid,
+      helperArtifacts: Object.freeze({ service: false, tmpfiles: false })
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Root-only removal of the exact incomplete system shapes above. Stops and
+ * disables the selected client, removes only the exact helper artifacts that
+ * point at /opt/nc, then removes the bounded tree. The dedicated nodecommand
+ * account is never touched, and no other path is eligible.
+ * @param {string} root
+ * @param {{ platform?: string, getuid?: (() => number)|null, geteuid?: (() => number)|null, io?: typeof fs, run?: Function }} [options]
+ * @returns {'pending-helper'|'failed-install'}
+ */
+export function removeIncompleteSystemInstallation(root, {
+  platform = os.platform(), getuid = process.getuid, geteuid = process.geteuid, io = fs, run = child_process.spawnSync
+} = {}) {
+  const refused = (reason) => Object.assign(
+    new Error(`Refusing incomplete system removal of ${root}: ${reason}.`),
+    { code: 'PARTIAL_SYSTEM_REMOVAL_REFUSED' }
+  );
+  if (!isPartialSystemRemovalCandidate(root, { platform, getuid, geteuid })) {
+    throw refused('it is not the canonical incomplete system root');
+  }
+  const shape = incompleteSystemInstallationShape(root, { platform, io });
+  if (!shape) throw refused('the system tree is not the exact pending-helper or failed-install shape');
+  const unlink = io.unlinkSync || fs.unlinkSync;
+  const systemctl = (args) => {
+    const result = run('/usr/bin/systemctl', ['--system', '--no-pager', '--no-ask-password', ...args], {
+      env: { PATH: '/usr/sbin:/usr/bin:/sbin:/bin', LANG: 'C', LC_ALL: 'C' }, cwd: '/', encoding: 'utf8',
+      timeout: 15000, stdio: ['ignore', 'pipe', 'pipe']
+    });
+    if (!result || result.error || result.signal || result.status !== 0) throw refused(`systemctl ${args.join(' ')} failed`);
+    return String(result.stdout ?? '');
+  };
+  try {
+    systemctl(['disable', '--now', 'nc-client.service']);
+    if (shape.kind === 'pending-helper' && shape.helperArtifacts.service) {
+      systemctl(['disable', '--now', 'nc-privileged-helper.socket']);
+      systemctl(['stop', 'nc-privileged-helper.service']);
+      try {
+        systemLstat(io)(INCOMPLETE_HELPER_SOCKET_PATH);
+        throw refused('the privileged helper socket is still present after stop');
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+      }
+      if (shape.helperArtifacts.tmpfiles) unlink(INCOMPLETE_HELPER_TMPFILES);
+      unlink(INCOMPLETE_HELPER_SOCKET);
+      unlink(INCOMPLETE_HELPER_UNIT);
+    }
+    unlink(INCOMPLETE_SYSTEM_UNIT);
+    systemctl(['daemon-reload']);
+    const units = shape.kind === 'pending-helper' && shape.helperArtifacts.service
+      ? ['nc-client.service', 'nc-privileged-helper.socket', 'nc-privileged-helper.service']
+      : ['nc-client.service'];
+    for (const unit of units) {
+      const state = systemctl(['show', unit, '--property=LoadState', '--value']).trim();
+      if (state !== 'not-found') throw refused(`${unit} is still loaded as ${state}`);
+    }
+    removeBoundedRoot(root, {
+      uid: 0,
+      allowedUids: new Set([0, shape.payloadUid]),
+      allowedEntries: INCOMPLETE_SYSTEM_ENTRIES,
+      io,
+      refused,
+      owner: 'root',
+      verifyConfig: () => {}
+    });
+    return shape.kind;
+  } catch (error) {
+    if (error?.code === 'PARTIAL_SYSTEM_REMOVAL_REFUSED') throw error;
+    throw refused(error instanceof Error ? error.message : 'the tree could not be verified');
+  }
+}
+
 /**
  * Canonical machine-wide roots that exist but cannot be inspected by the
  * current unprivileged caller. Setup must escalate before deciding anything
@@ -699,16 +1064,21 @@ export function findRemovalTargets({ io = {}, ...rest } = {}) {
   const install = [];
   const unreadable = [];
   let pair = null;
+  let incompleteRoot = null;
   if ((rest.platform || os.platform()) === 'linux') {
+    let pairedError = null;
     try {
       pair = linuxPairedInstallation(io);
     } catch (err) {
       // Protected metadata this account cannot stat or read is not a local
-      // removal target. Inventory discovery continues so an ordinary user can
-      // still remove their own readable tree; nothing here executes a root.
-      // Any other validation failure remains a hard stop.
-      if (err?.code !== 'TRUSTED_ROOT_MAINTENANCE_REQUIRED' || !pairedMetadataUnreadable(io)) throw err;
-      pair = null;
+      // removal target. Any other validation failure remains a hard stop
+      // unless the tree is the exact recoverable pending/failed shape.
+      if (err?.code !== 'TRUSTED_ROOT_MAINTENANCE_REQUIRED') throw err;
+      pairedError = err;
+    }
+    if (!pair) {
+      if (incompleteSystemInstallationShape(PARTIAL_SYSTEM_ROOT, { platform: 'linux', io })) incompleteRoot = PARTIAL_SYSTEM_ROOT;
+      if (pairedError && !incompleteRoot && !pairedMetadataUnreadable(io)) throw pairedError;
     }
   }
   const env = rest.env || process.env;
@@ -719,6 +1089,15 @@ export function findRemovalTargets({ io = {}, ...rest } = {}) {
     const status = probeRemovalRoot(root, io);
     if (status === 'install' && !install.includes(root)) install.push(root);
     else if (status === 'unreadable' && !unreadable.includes(root)) unreadable.push(root);
+    else if (status === 'foreign' && !install.includes(root) && isPartialSystemRemovalCandidate(root, rest) &&
+      partialEnrollmentSystemRoot(root, io)) install.push(root);
+  }
+  // The exact pending-helper / failed-install system tree is a bounded target
+  // only for a real+effective root caller; an ordinary caller gets the
+  // trusted-maintenance message instead of a silent "nothing to remove".
+  if (incompleteRoot && !install.includes(incompleteRoot) && !unreadable.includes(incompleteRoot)) {
+    if (isPartialSystemRemovalCandidate(incompleteRoot, rest)) install.push(incompleteRoot);
+    else unreadable.push(incompleteRoot);
   }
   // The paired relation is only actionable when its root is itself readable.
   // An unverifiable/foreign paired root is reported through `unreadable`.

package/package.json

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