fullcourtdefense-cli 1.36.2 → 1.36.4

package/dist/machineIdentity.js

@@ -33,8 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.__setMachineIdentityDepsForTest = __setMachineIdentityDepsForTest;
+exports.resetMachineIdentityCache = resetMachineIdentityCache;
 exports.normalizeHostname = normalizeHostname;
+exports.shortMachineId = shortMachineId;
+exports.isIdentityReadOnlyCommand = isIdentityReadOnlyCommand;
+exports.setMachineIdentityReadOnly = setMachineIdentityReadOnly;
+exports.isPinConfirmed = isPinConfirmed;
+exports.readPinnedIdentity = readPinnedIdentity;
 exports.getMachineIdentity = getMachineIdentity;
+exports.reconcileMachineIdentity = reconcileMachineIdentity;
+exports.confirmMachineIdentity = confirmMachineIdentity;
 exports.localMachineKind = localMachineKind;
 exports.resetLocalMachineKindCache = resetLocalMachineKindCache;
 exports.stampMachineIdentityContext = stampMachineIdentityContext;
@@ -46,6 +55,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const devConfirm_1 = require("./devConfirm");
+const distress_1 = require("./distress");
 /**
  * OS-agnostic stable machine identity.
  *
@@ -60,8 +70,49 @@ const devConfirm_1 = require("./devConfirm");
  *   - Linux:   /etc/machine-id (fallback /var/lib/dbus/machine-id)
  *
  * `username@hostname` is kept only as a human-readable display label.
+ *
+ * PINNING. Reading MachineGuid needs a `reg.exe` child process, and Microsoft
+ * Defender flags that exact command line (`Trojan:Win32/Commando.A!ml`,
+ * FastPath) on machines that start many CLI processes: the spawn fails with
+ * EPERM and the id used to fall back to whatever a stale fallback file held —
+ * the machine silently changed identity and the backend refused it (#1853).
+ * So the id is resolved ONCE and pinned in `identity.json`; every later
+ * process (hooks, flush-spool, watchdog, daemon) reads the pin and spawns
+ * nothing. The only remaining spawns:
+ *   - no pin at all (first run after install/upgrade): one native read,
+ *     at most once per boot and 24 h per user (`identity-probe.json`);
+ *   - an UNCONFIRMED fallback pin, or a pin whose hostname no longer matches:
+ *     the daemon (`reconcileMachineIdentity('heal')`) re-reads natively under
+ *     the same throttle; `login` re-reads unthrottled (a human is enrolling).
+ * Node has no registry API and no bundled N-API module exposes one; a
+ * PowerShell read is also a child process, so reg.exe stays for that one read.
+ *
+ * Precedence: backend-confirmed (enrollment, recovery, or a heartbeat the
+ * backend accepted) > native > fallback. A confirmed id is never replaced by
+ * a native read that disagrees — that records `machine_id_conflict` and keeps
+ * the confirmed id. The pin is per-user and written only into an existing
+ * `~/.fullcourtdefense`; inspect / remove commands run read-only (#1870).
  */
 let cached;
+const defaultDeps = {
+    execFileSync: (file, args, options) => String((0, child_process_1.execFileSync)(file, args, options)),
+    platform: () => os.platform(),
+    now: () => Date.now(),
+    uptimeSeconds: () => os.uptime(),
+    hostname: () => os.hostname(),
+    linuxMachineId: () => safe(() => fs.readFileSync('/etc/machine-id', 'utf8'))
+        || safe(() => fs.readFileSync('/var/lib/dbus/machine-id', 'utf8')),
+};
+let deps = defaultDeps;
+/** Test seam: replace the spawn / clock / platform, and forget the cached identity. */
+function __setMachineIdentityDepsForTest(overrides) {
+    deps = overrides ? { ...defaultDeps, ...overrides } : defaultDeps;
+    cached = undefined;
+}
+/** Forget the in-process identity (the pin changed). */
+function resetMachineIdentityCache() {
+    cached = undefined;
+}
 function safe(fn) {
     try {
         const value = fn();
@@ -79,79 +130,290 @@ function normalizeHostname(raw) {
         .replace(/\..*$/, '') // drop any remaining domain suffix
         .toLowerCase() || 'unknown-host';
 }
+/** First 8 hex chars — how ids appear in logs, distress details and recovery requests. */
+function shortMachineId(machineId) {
+    return machineId.slice(0, 8);
+}
+const MACHINE_ID_RE = /^[0-9a-f]{16,64}$/;
+/** A spawn the OS or an EDR refused, or that hung: repeating the same command line cannot help. */
+const SPAWN_REFUSED_RE = /^(EPERM|EACCES|ENOENT|ETIMEDOUT|EBUSY|UNKNOWN)$/;
+function spawnFailureReason(error) {
+    const e = error;
+    if (typeof e?.code === 'string' && e.code)
+        return e.code;
+    if (typeof e?.status === 'number')
+        return `exit ${e.status}`;
+    return String((e && e.message) || error).slice(0, 80);
+}
+/** Linux reads files; Windows (reg.exe) and macOS (ioreg) need a child process. */
+function nativeReadSpawns() {
+    const platform = deps.platform();
+    return platform === 'win32' || platform === 'darwin';
+}
 /** Raw OS-native stable id (UNHASHED). Internal — prefer `getMachineIdentity().machineId`. */
-function rawStableId() {
-    const platform = os.platform();
+function readNativeStableId() {
+    const platform = deps.platform();
     if (platform === 'win32') {
         // MachineGuid lives only in the 64-bit registry view. When this process is
         // 32-bit (e.g. spawned by an MSI custom action via SysWOW64 PowerShell),
         // a plain query is redirected to WOW6432Node and finds nothing — which
         // would silently change the machineId and enroll a DUPLICATE fleet record.
         // Query the 64-bit view first, then fall back for true 32-bit Windows.
-        const queryMachineGuid = (extraArgs) => safe(() => {
-            const out = (0, child_process_1.execFileSync)('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid', ...extraArgs], { encoding: 'utf8', windowsHide: true, timeout: 4000 });
-            const match = out.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i);
-            return match ? match[1] : undefined;
-        });
-        return queryMachineGuid(['/reg:64']) || queryMachineGuid([]);
+        const query = (extraArgs) => {
+            try {
+                const out = deps.execFileSync('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid', ...extraArgs], { encoding: 'utf8', windowsHide: true, timeout: 4000 });
+                const match = out.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i);
+                return match ? { ok: true, raw: match[1] } : { ok: false, reason: 'MachineGuid missing from reg output' };
+            }
+            catch (error) {
+                return { ok: false, reason: spawnFailureReason(error) };
+            }
+        };
+        const view64 = query(['/reg:64']);
+        if (view64.ok || SPAWN_REFUSED_RE.test(view64.reason))
+            return view64;
+        return query([]);
     }
     if (platform === 'darwin') {
-        return safe(() => {
-            const out = (0, child_process_1.execFileSync)('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8', timeout: 4000 });
+        try {
+            const out = deps.execFileSync('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8', windowsHide: true, timeout: 4000 });
             const match = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
-            return match ? match[1] : undefined;
-        });
+            return match ? { ok: true, raw: match[1] } : { ok: false, reason: 'IOPlatformUUID missing from ioreg output' };
+        }
+        catch (error) {
+            return { ok: false, reason: spawnFailureReason(error) };
+        }
     }
     // linux + others
-    return (safe(() => fs.readFileSync('/etc/machine-id', 'utf8'))
-        || safe(() => fs.readFileSync('/var/lib/dbus/machine-id', 'utf8')));
+    const raw = safe(() => deps.linuxMachineId());
+    return raw ? { ok: true, raw } : { ok: false, reason: 'no /etc/machine-id' };
+}
+function hashNativeId(raw) {
+    return crypto.createHash('sha256').update(raw).digest('hex').slice(0, 32);
 }
 /**
- * Where the FALLBACK machine id is persisted when no OS-native stable id is
- * readable (locked-down registry / missing /etc/machine-id). Two locations:
- *
- *  - machine-wide (ProgramData on Windows): shared by EVERY user AND the
- *    SYSTEM/S4U daemon tasks. Without it, the composite fallback — which
- *    includes the username — gives the daemon (running as SYSTEM) a DIFFERENT
- *    machineId than the enrolling user, creating duplicate fleet records with
- *    split telemetry for the same laptop.
- *  - per-user (~/.fullcourtdefense): fallback when ProgramData is not
- *    writable; keeps the id stable across upgrades for that user at least.
- *
- * The persisted value is the final HASHED id (never the raw composite).
+ * Where the pin lives: the per-user state directory only, and only when it
+ * already exists (an installed / enrolled machine). Identity persistence never
+ * CREATES a directory: `verify-removed` or any command run after an uninstall
+ * must leave a machine with zero FullCourtDefense remnants (#1870). The MSI
+ * uninstall deletes `~/.fullcourtdefense` whole, so nothing written here
+ * survives it. A machine-wide pin needs the MSI's SYSTEM cleanup to remove it
+ * first (#1871).
  */
-function persistedIdPaths() {
-    const perUser = path.join(os.homedir(), '.fullcourtdefense', 'machine-id');
-    if (os.platform() === 'win32') {
+function pinDir() {
+    return path.join(os.homedir(), '.fullcourtdefense');
+}
+/**
+ * Legacy `machine-id` locations, machine-wide first. Pre-1.36.3 CLIs wrote the
+ * fallback id here when the native read failed; it is READ for convergence
+ * (every user and the SYSTEM daemon on a locked-down machine agree on it) and
+ * REWRITTEN to the pinned id only where it already exists (heals old CLIs on a
+ * downgrade). Never created.
+ */
+function legacyIdFiles() {
+    const perUser = path.join(pinDir(), LEGACY_FILE);
+    if (deps.platform() === 'win32') {
         const programData = process.env.ProgramData || 'C:\\ProgramData';
-        return { machineWide: path.join(programData, 'FullCourtDefense', 'machine-id'), perUser };
+        return [path.join(programData, 'FullCourtDefense', LEGACY_FILE), perUser];
     }
-    return { perUser };
+    return [perUser];
+}
+/** Authoritative pin (JSON). */
+const PIN_FILE = 'identity.json';
+/** Legacy fallback id (bare hashed id), see legacyIdFiles(). */
+const LEGACY_FILE = 'machine-id';
+/** Native-read throttle marker. */
+const PROBE_FILE = 'identity-probe.json';
+const PROBE_RETRY_MS = 24 * 60 * 60_000;
+/** Two boot-time estimates this close are the same boot (uptime is read in whole seconds, clocks drift). */
+const SAME_BOOT_TOLERANCE_MS = 5 * 60_000;
+const READ_ONLY_COMMANDS = new Set([
+    'verify-removed', 'uninstall', 'uninstall-all', 'detach', 'doctor', 'help',
+    'unprotect-all', 'unwrap-all', 'rollback-codex-managed-hooks',
+    'hotfix-status', 'codex-hook-status', 'shell-guard-status', 'cmd-guard-status',
+]);
+/**
+ * CLI commands that inspect or remove the installation: `uninstall-*`,
+ * `*-status`, the removal commands, and `--uninstall` / `--unschedule` /
+ * `--status` runs of the daemon, auto-protect and discover.
+ */
+function isIdentityReadOnlyCommand(command, flags = {}) {
+    if (READ_ONLY_COMMANDS.has(command) || command.startsWith('uninstall-') || command.endsWith('-status'))
+        return true;
+    return ['uninstall', 'unschedule', 'status'].some(flag => flags[flag] !== undefined && String(flags[flag]) !== 'false');
 }
-function readPersistedFallbackId() {
-    const { machineWide, perUser } = persistedIdPaths();
-    for (const file of [machineWide, perUser]) {
-        if (!file)
+/**
+ * Read-only mode decided from the CLI's own argv when this module loads:
+ * modules imported by the entry resolve the id at import time (detector
+ * updates), before the command dispatch could switch anything.
+ */
+function readOnlyFromArgv(argv) {
+    if (!/(^|[\\/])index\.js$/.test(argv[1] || ''))
+        return false;
+    const [command = '', ...rest] = argv.slice(2);
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        if (!rest[i].startsWith('--'))
             continue;
+        const next = rest[i + 1];
+        flags[rest[i].slice(2)] = next !== undefined && !next.startsWith('--') ? next : 'true';
+    }
+    return isIdentityReadOnlyCommand(command, flags);
+}
+let readOnly = readOnlyFromArgv(process.argv);
+/**
+ * Inspect / remove commands (verify-removed, uninstall, doctor, …): resolve
+ * from what is on disk, write nothing and never spawn the native read.
+ */
+function setMachineIdentityReadOnly(on) {
+    readOnly = on;
+    cached = undefined;
+}
+/** Atomic write into an EXISTING directory; never creates one. */
+function writeAtomic(file, body) {
+    if (readOnly)
+        return false;
+    const dir = path.dirname(file);
+    try {
+        if (!fs.statSync(dir).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(3).toString('hex')}`;
+    try {
+        fs.writeFileSync(tmp, body, 'utf8');
+        fs.renameSync(tmp, file);
+        return true;
+    }
+    catch {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* never created */ }
+        return false;
+    }
+}
+function parsePin(text) {
+    if (!text)
+        return undefined;
+    try {
+        const raw = JSON.parse(text);
+        const machineId = typeof raw.machineId === 'string' ? raw.machineId.toLowerCase() : '';
+        if (!MACHINE_ID_RE.test(machineId))
+            return undefined;
+        if (!['native', 'fallback', 'enrollment', 'recovered'].includes(String(raw.source)))
+            return undefined;
+        const now = new Date(deps.now()).toISOString();
+        return {
+            schema: 1,
+            machineId,
+            source: raw.source,
+            firstSeen: typeof raw.firstSeen === 'string' ? raw.firstSeen : now,
+            updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : now,
+            ...(typeof raw.confirmedAt === 'string' ? { confirmedAt: raw.confirmedAt } : {}),
+            ...(typeof raw.hostname === 'string' && raw.hostname ? { hostname: raw.hostname } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPinConfirmed(pin) {
+    return !!pin.confirmedAt || pin.source === 'enrollment' || pin.source === 'recovered';
+}
+function pinRank(pin) {
+    if (isPinConfirmed(pin))
+        return 3;
+    return pin.source === 'native' ? 2 : 1;
+}
+function readPinnedIdentity() {
+    return parsePin(safe(() => fs.readFileSync(path.join(pinDir(), PIN_FILE), 'utf8')));
+}
+/**
+ * Write the pin, and sync the legacy files that already exist. Never
+ * downgrades: an existing pin that outranks this one stays, and a confirmed
+ * pin for a different id is only replaced by a new confirmed one (`force`).
+ */
+function writePin(pin, options = {}) {
+    const existing = readPinnedIdentity();
+    if (existing && !options.force) {
+        if (pinRank(existing) > pinRank(pin))
+            return false;
+        if (existing.machineId !== pin.machineId && isPinConfirmed(existing))
+            return false;
+    }
+    if (!writeAtomic(path.join(pinDir(), PIN_FILE), `${JSON.stringify(pin, null, 2)}\n`))
+        return false;
+    for (const file of legacyIdFiles()) {
+        if (fs.existsSync(file))
+            writeAtomic(file, pin.machineId);
+    }
+    return true;
+}
+function readLegacyFallbackId() {
+    for (const file of legacyIdFiles()) {
         const value = safe(() => fs.readFileSync(file, 'utf8'));
-        if (value && /^[0-9a-f]{16,64}$/i.test(value))
+        if (value && MACHINE_ID_RE.test(value.toLowerCase()))
             return value.toLowerCase();
     }
     return undefined;
 }
-function persistFallbackId(machineId) {
-    const { machineWide, perUser } = persistedIdPaths();
-    for (const file of [machineWide, perUser]) {
-        if (!file)
-            continue;
-        try {
-            fs.mkdirSync(path.dirname(file), { recursive: true });
-            const tmp = `${file}.tmp-${process.pid}`;
-            fs.writeFileSync(tmp, machineId, 'utf8');
-            fs.renameSync(tmp, file);
-        }
-        catch { /* best-effort — the composite recomputes deterministically for this user */ }
+function bootStartedAt() {
+    return deps.now() - deps.uptimeSeconds() * 1000;
+}
+/** A native read already happened (or is in flight) this boot, within 24 h. */
+function probeThrottled() {
+    let marker;
+    try {
+        marker = JSON.parse(fs.readFileSync(path.join(pinDir(), PROBE_FILE), 'utf8'));
+    }
+    catch {
+        return false;
     }
+    if (!marker || typeof marker.attemptedAt !== 'string' || typeof marker.bootAt !== 'string')
+        return false;
+    return Math.abs(Date.parse(marker.bootAt) - bootStartedAt()) < SAME_BOOT_TOLERANCE_MS
+        && deps.now() - Date.parse(marker.attemptedAt) < PROBE_RETRY_MS;
+}
+function writeProbeMarker(marker) {
+    writeAtomic(path.join(pinDir(), PROBE_FILE), JSON.stringify(marker));
+}
+/** One native read, recorded in the throttle marker BEFORE the spawn so concurrent processes skip it. */
+function probeNative() {
+    if (!nativeReadSpawns())
+        return readNativeStableId();
+    const base = { bootAt: new Date(bootStartedAt()).toISOString(), attemptedAt: new Date(deps.now()).toISOString() };
+    writeProbeMarker({ ...base, result: 'pending' });
+    const read = readNativeStableId();
+    writeProbeMarker({ ...base, result: read.ok ? 'ok' : 'failed', ...(read.ok ? {} : { reason: read.reason }) });
+    return read;
+}
+/**
+ * With no pin, any process may read (throttled when the read spawns). With a
+ * pin, only the daemon / enrollment re-check it — except that a spawn-free
+ * read (Linux) may heal an unconfirmed fallback pin anywhere. Hostname and
+ * conflict checks therefore never run, or report, per hook process. Read-only
+ * commands never spawn.
+ */
+function mayProbe(mode, pin) {
+    if (readOnly && nativeReadSpawns())
+        return false;
+    if (!pin)
+        return !nativeReadSpawns() || mode === 'force' || !probeThrottled();
+    if (mode === 'unpinned')
+        return !nativeReadSpawns() && pin.unconfirmedFallback;
+    return mode === 'force' || !nativeReadSpawns() || !probeThrottled();
+}
+function nowIso() {
+    return new Date(deps.now()).toISOString();
+}
+function currentUser() {
+    return safe(() => os.userInfo().username) || process.env.USER || process.env.USERNAME || 'unknown-user';
+}
+function currentHostname() {
+    return normalizeHostname(safe(() => deps.hostname()) || 'unknown-host');
 }
 function friendlyOs() {
     const platform = os.platform();
@@ -177,62 +439,163 @@ function friendlyOs() {
     }
     return `${platform} ${release}`;
 }
+/** Ephemeral fleet override (CI / workloads), or undefined on a real machine. */
+function ciOverrideIdentity() {
+    // On CI runners the PIPELINE is the fleet identity, not the disposable
+    // runner hardware. `ci-protect` enrolls the pipeline and exports these envs
+    // (via GITHUB_ENV) so every subsequent hook/gateway process in the job
+    // attributes its events to the pipeline machine record.
+    const ciMachineId = (process.env.FCD_MACHINE_ID || '').trim();
+    if (!ciMachineId)
+        return undefined;
+    return {
+        machineId: ciMachineId.slice(0, 64),
+        user: 'ci',
+        hostname: (process.env.FCD_MACHINE_HOSTNAME || 'ci-pipeline').trim().toLowerCase().slice(0, 160) || 'ci-pipeline',
+        developerName: (process.env.FCD_DEVELOPER_NAME || 'ci@pipeline').trim().toLowerCase().slice(0, 160) || 'ci@pipeline',
+        platform: os.platform(),
+        osFriendly: 'CI runner',
+        idSource: 'ci',
+    };
+}
+/** Resolve the id: pin first; native only when the mode and throttle allow it. */
+function resolveMachineId(mode, hostname, user) {
+    const pin = readPinnedIdentity();
+    if (pin) {
+        const unconfirmedFallback = !isPinConfirmed(pin) && pin.source === 'fallback';
+        const hostnameChanged = !!pin.hostname && pin.hostname !== hostname;
+        const report = { machineId: pin.machineId, source: pin.source, confirmed: isPinConfirmed(pin), probed: false };
+        if (!(unconfirmedFallback || hostnameChanged) || !mayProbe(mode, { unconfirmedFallback }))
+            return report;
+        const native = probeNative();
+        report.probed = true;
+        if (!native.ok) {
+            report.probeError = native.reason;
+            return report;
+        }
+        const nativeId = hashNativeId(native.raw);
+        if (nativeId === pin.machineId) {
+            writePin({ ...pin, source: pin.source === 'fallback' ? 'native' : pin.source, hostname, updatedAt: nowIso() });
+            return { ...report, source: pin.source === 'fallback' ? 'native' : pin.source };
+        }
+        if (!isPinConfirmed(pin)) {
+            // The owner's case (#1853): a stale fallback id beats nothing, but the OS id beats it.
+            writePin({ schema: 1, machineId: nativeId, source: 'native', firstSeen: nowIso(), updatedAt: nowIso(), hostname });
+            return { machineId: nativeId, source: 'native', confirmed: false, probed: true, healed: { from: pin.machineId, to: nativeId } };
+        }
+        (0, distress_1.reportDistress)('identity', 'machine_id_conflict', `pinned ${shortMachineId(pin.machineId)} (${pin.source}, confirmed) vs native ${shortMachineId(nativeId)}${hostnameChanged ? ` · hostname ${pin.hostname} -> ${hostname}` : ''}; keeping the confirmed id`);
+        return { ...report, conflict: { pinned: pin.machineId, native: nativeId } };
+    }
+    if (mayProbe(mode, undefined)) {
+        const native = probeNative();
+        if (native.ok) {
+            const machineId = hashNativeId(native.raw);
+            writePin({ schema: 1, machineId, source: 'native', firstSeen: nowIso(), updatedAt: nowIso(), hostname });
+            return { machineId, source: 'native', confirmed: false, probed: true };
+        }
+        // Native unreadable: the legacy fallback file (every user + the SYSTEM
+        // daemon converge on it), else the legacy composite, which keeps the
+        // pre-existing shape (incl. username) so machines already enrolled on this
+        // path keep their identity across upgrades. Pinned UNCONFIRMED: the
+        // backend's answer to the next heartbeat confirms it or triggers recovery.
+        const machineId = readLegacyFallbackId() || hashNativeId(`${hostname}|${user}|${deps.platform()}|${os.arch()}`);
+        writePin({ schema: 1, machineId, source: 'fallback', firstSeen: nowIso(), updatedAt: nowIso(), hostname });
+        return { machineId, source: 'fallback', confirmed: false, probed: true, probeError: native.reason };
+    }
+    // Another process read (or is reading) natively this boot: use the fallback
+    // in memory and leave pinning to that process.
+    const machineId = readLegacyFallbackId() || hashNativeId(`${hostname}|${user}|${deps.platform()}|${os.arch()}`);
+    return { machineId, source: 'fallback', confirmed: false, probed: false };
+}
+function buildIdentity(mode) {
+    const user = currentUser();
+    const hostname = currentHostname();
+    const report = resolveMachineId(mode, hostname, user);
+    return {
+        report,
+        identity: {
+            machineId: report.machineId,
+            user,
+            hostname,
+            developerName: `${user.toLowerCase()}@${hostname}`,
+            platform: os.platform(),
+            osFriendly: friendlyOs(),
+            idSource: report.source,
+            idConfirmed: report.confirmed,
+        },
+    };
+}
 /**
- * Compute (and cache) the stable machine identity. The raw OS id is hashed
+ * The stable machine identity (cached per process). The raw OS id is hashed
  * (SHA-256, 32 hex chars) so we never transmit the raw hardware UUID.
  */
 function getMachineIdentity() {
     if (cached)
         return cached;
-    // Ephemeral fleet override: on CI runners the PIPELINE is the fleet identity,
-    // not the disposable runner hardware. `ci-protect` enrolls the pipeline and
-    // exports these envs (via GITHUB_ENV) so every subsequent hook/gateway
-    // process in the job attributes its events to the pipeline machine record.
-    const ciMachineId = (process.env.FCD_MACHINE_ID || '').trim();
-    if (ciMachineId) {
-        cached = {
-            machineId: ciMachineId.slice(0, 64),
-            user: 'ci',
-            hostname: (process.env.FCD_MACHINE_HOSTNAME || 'ci-pipeline').trim().toLowerCase().slice(0, 160) || 'ci-pipeline',
-            developerName: (process.env.FCD_DEVELOPER_NAME || 'ci@pipeline').trim().toLowerCase().slice(0, 160) || 'ci@pipeline',
-            platform: os.platform(),
-            osFriendly: 'CI runner',
-        };
-        return cached;
+    const ci = ciOverrideIdentity();
+    if (ci)
+        return (cached = ci);
+    cached = buildIdentity('unpinned').identity;
+    return cached;
+}
+/**
+ * Re-resolve with a wider native-read allowance: the daemon at boot (`heal`)
+ * and enrollment (`force`). Replaces the cached identity.
+ */
+function reconcileMachineIdentity(mode) {
+    const ci = ciOverrideIdentity();
+    if (ci) {
+        cached = ci;
+        return { machineId: ci.machineId, source: 'enrollment', confirmed: true, probed: false };
     }
-    const user = safe(() => os.userInfo().username) || process.env.USER || process.env.USERNAME || 'unknown-user';
-    const hostname = normalizeHostname(safe(() => os.hostname()) || 'unknown-host');
-    // Seed the hash with the OS-native id when available; otherwise reuse the
-    // persisted fallback id (so every user + the SYSTEM daemon on the same
-    // locked-down machine converge on ONE identity); only then compute the
-    // legacy composite — and persist it so future contexts converge on it.
-    const nativeRaw = rawStableId();
-    let machineId;
-    if (nativeRaw) {
-        machineId = crypto.createHash('sha256').update(nativeRaw).digest('hex').slice(0, 32);
+    const { identity, report } = buildIdentity(mode);
+    cached = identity;
+    return report;
+}
+/**
+ * Record that the backend accepted `machineId` for this machine:
+ *  - `enrollment`: the enroll call succeeded — authoritative, always pinned;
+ *  - `heartbeat`: events:batch returned 200 for the id this process uses;
+ *  - `recovered`: the backend named the machine bound to this shield. Never
+ *    replaces a different confirmed id (records `machine_id_conflict`).
+ */
+function confirmMachineIdentity(machineId, how) {
+    if ((process.env.FCD_MACHINE_ID || '').trim())
+        return 'skipped';
+    const id = String(machineId || '').toLowerCase();
+    if (!MACHINE_ID_RE.test(id))
+        return 'skipped';
+    const hostname = currentHostname();
+    const now = nowIso();
+    const pin = readPinnedIdentity();
+    if (how === 'heartbeat') {
+        if (pin && pin.machineId !== id)
+            return 'skipped';
+        if (pin && isPinConfirmed(pin))
+            return 'already';
+        const source = pin?.source || (cached?.idSource === 'native' ? 'native' : 'fallback');
+        const written = writePin({ schema: 1, machineId: id, source, firstSeen: pin?.firstSeen || now, updatedAt: now, confirmedAt: now, hostname });
+        if (written && cached?.machineId === id)
+            cached = { ...cached, idConfirmed: true };
+        return written ? 'pinned' : 'skipped';
     }
-    else {
-        const persisted = readPersistedFallbackId();
-        if (persisted) {
-            machineId = persisted;
-        }
-        else {
-            // Composite keeps the pre-existing shape (incl. username) so machines
-            // already enrolled on this path keep their identity across upgrades.
-            const composite = `${hostname}|${user}|${os.platform()}|${os.arch()}`;
-            machineId = crypto.createHash('sha256').update(composite).digest('hex').slice(0, 32);
-            persistFallbackId(machineId);
-        }
+    if (how === 'recovered' && pin && pin.machineId !== id && isPinConfirmed(pin)) {
+        (0, distress_1.reportDistress)('identity', 'machine_id_conflict', `pinned ${shortMachineId(pin.machineId)} (${pin.source}, confirmed) vs backend-recovered ${shortMachineId(id)}; keeping the confirmed id`);
+        return 'conflict';
     }
-    cached = {
-        machineId,
-        user,
+    if (pin && pin.machineId === id && isPinConfirmed(pin) && how === 'recovered')
+        return 'already';
+    const written = writePin({
+        schema: 1,
+        machineId: id,
+        source: how,
+        firstSeen: pin?.machineId === id ? pin.firstSeen : now,
+        updatedAt: now,
+        confirmedAt: now,
         hostname,
-        developerName: `${user.toLowerCase()}@${hostname}`,
-        platform: os.platform(),
-        osFriendly: friendlyOs(),
-    };
-    return cached;
+    }, { force: true });
+    cached = undefined;
+    return written ? 'pinned' : 'skipped';
 }
 let cachedKind;
 /**

package/dist/telemetry.d.ts

@@ -179,6 +179,15 @@ export interface FlushInput {
     };
     timeoutMs?: number;
 }
+/** Why the last flush in this process returned null. `status` is set only when the backend answered. */
+export interface FlushFailure {
+    kind: 'locked' | 'empty' | 'http' | 'network';
+    status?: number;
+    /** Backend machine-readable code, e.g. MACHINE_NOT_ENROLLED. */
+    code?: string;
+    error?: string;
+}
+export declare function getLastFlushFailure(): FlushFailure | undefined;
 /** Drain the spool to the backend in one batch (+ optional heartbeat). Returns accepted count. */
 export declare function flushSpool(input: FlushInput): Promise<{
     accepted: number;