fullcourtdefense-cli 1.26.4 → 1.26.6

package/dist/machineIdentity.js

@@ -40,6 +40,7 @@ const child_process_1 = require("child_process");
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
+const path = __importStar(require("path"));
 /**
  * OS-agnostic stable machine identity.
  *
@@ -100,6 +101,53 @@ function rawStableId() {
     return (safe(() => fs.readFileSync('/etc/machine-id', 'utf8'))
         || safe(() => fs.readFileSync('/var/lib/dbus/machine-id', 'utf8')));
 }
+/**
+ * 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).
+ */
+function persistedIdPaths() {
+    const perUser = path.join(os.homedir(), '.fullcourtdefense', 'machine-id');
+    if (os.platform() === 'win32') {
+        const programData = process.env.ProgramData || 'C:\\ProgramData';
+        return { machineWide: path.join(programData, 'FullCourtDefense', 'machine-id'), perUser };
+    }
+    return { perUser };
+}
+function readPersistedFallbackId() {
+    const { machineWide, perUser } = persistedIdPaths();
+    for (const file of [machineWide, perUser]) {
+        if (!file)
+            continue;
+        const value = safe(() => fs.readFileSync(file, 'utf8'));
+        if (value && /^[0-9a-f]{16,64}$/i.test(value))
+            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 friendlyOs() {
     const platform = os.platform();
     const release = os.release();
@@ -149,10 +197,28 @@ function getMachineIdentity() {
     }
     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; fall back to a stable
-    // composite so we still produce a deterministic id on locked-down machines.
-    const raw = rawStableId() || `${hostname}|${user}|${os.platform()}|${os.arch()}`;
-    const machineId = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 32);
+    // 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);
+    }
+    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);
+        }
+    }
     cached = {
         machineId,
         user,

package/dist/runtimeConfig.d.ts

@@ -101,6 +101,8 @@ export interface FetchBundleInput {
 }
 export interface EffectiveBundle extends RuntimeBundle {
     source: 'server' | 'cache' | 'default';
+    /** Epoch ms of the last server 200/304 that confirmed this bundle (absent on the 'default' fallback). */
+    serverValidatedAt?: number;
 }
 /**
  * Resolve the effective runtime bundle for a Shield, using the local cache when

package/dist/runtimeConfig.js

@@ -39,6 +39,7 @@ exports.resetCacheOnEnrollment = resetCacheOnEnrollment;
 exports.isSuspendedByCache = isSuspendedByCache;
 exports.getCachedScanRootOverrides = getCachedScanRootOverrides;
 exports.getCachedExtraScanRoots = getCachedExtraScanRoots;
+const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -47,6 +48,15 @@ const sessionLimits_1 = require("./sessionLimits");
 const CACHE_PATH = path.join(os.homedir(), '.fullcourtdefense-runtime.json');
 const DEFAULT_TTL_MS = 60_000;
 const REFRESH_TIMEOUT_MS = 1_500; // tight: the hook must stay fast
+/**
+ * Hot-path monitor/shadow callers accept a stale cache because the resident
+ * daemon owns freshness (60s poll). But when the cache is THIS old the daemon
+ * is presumably dead — the machine would never learn about a kill-switch flip
+ * or a monitor->block promotion. Past this bound ONE hook per interval pays a
+ * bounded (≤1.5s) refresh; everyone else keeps taking the stale cache.
+ */
+const HOT_PATH_MAX_STALE_MS = 10 * 60_000;
+const HOT_PATH_REVALIDATE_INTERVAL_MS = 5 * 60_000;
 function readCacheFile() {
     try {
         const raw = fs.readFileSync(CACHE_PATH, 'utf-8');
@@ -66,10 +76,111 @@ function writeCacheFile(data) {
 function isMode(value) {
     return value === 'block' || value === 'monitor' || value === 'shadow';
 }
+// ---------------------------------------------------------------------------
+// Tamper-resistant kill-switch marker
+//
+// The runtime cache is a plain JSON file: editing `suspended: false` into it
+// (or deleting the file) must NOT clear an admin suspension. A second,
+// HMAC-signed marker file records last-known-suspended per shield; it is
+// asserted on every server response that says suspended and cleared ONLY by a
+// server-confirmed response that says not-suspended. Effective bundles overlay
+// it, so both files must be forged/deleted together — and the daemon re-asserts
+// the marker on every poll while the server still says suspended.
+// ---------------------------------------------------------------------------
+const KILLSWITCH_DIR = path.join(os.homedir(), '.fullcourtdefense');
+const KILLSWITCH_MARKER_PATH = path.join(KILLSWITCH_DIR, 'killswitch.json');
+const KILLSWITCH_SECRET_PATH = path.join(KILLSWITCH_DIR, '.ks-secret');
+/** Atomic write-temp-rename — a crash mid-write must never corrupt the marker. */
+function writeFileAtomic(file, data, mode) {
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(tmp, data, { encoding: 'utf-8', mode });
+    fs.renameSync(tmp, file);
+}
+function killSwitchSecret(createIfMissing) {
+    try {
+        const raw = fs.readFileSync(KILLSWITCH_SECRET_PATH, 'utf-8').trim();
+        if (raw.length >= 32)
+            return raw;
+    }
+    catch { /* not created yet */ }
+    if (!createIfMissing)
+        return undefined;
+    try {
+        const secret = crypto.randomBytes(32).toString('hex');
+        writeFileAtomic(KILLSWITCH_SECRET_PATH, secret, 0o600);
+        return secret;
+    }
+    catch {
+        return undefined;
+    }
+}
+function killSwitchSig(secret, shieldId, suspendedAt) {
+    return crypto.createHmac('sha256', secret).update(`fcd-killswitch|${shieldId}|${suspendedAt}`).digest('hex');
+}
+function readKillSwitchMarker() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(KILLSWITCH_MARKER_PATH, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function assertSuspendMarker(shieldId) {
+    try {
+        const secret = killSwitchSecret(true);
+        if (!secret)
+            return;
+        const marker = readKillSwitchMarker();
+        const entries = marker.entries && typeof marker.entries === 'object' ? marker.entries : {};
+        // Keep the original suspendedAt when re-asserting (audit-friendly).
+        const existing = entries[shieldId];
+        const suspendedAt = existing?.suspendedAt && killSwitchSig(secret, shieldId, existing.suspendedAt) === existing.sig
+            ? existing.suspendedAt
+            : new Date().toISOString();
+        entries[shieldId] = { suspendedAt, sig: killSwitchSig(secret, shieldId, suspendedAt) };
+        writeFileAtomic(KILLSWITCH_MARKER_PATH, JSON.stringify({ entries }), 0o600);
+    }
+    catch { /* marker is defense-in-depth — never break the caller */ }
+}
+function clearSuspendMarker(shieldId) {
+    try {
+        const marker = readKillSwitchMarker();
+        if (!marker.entries || !marker.entries[shieldId])
+            return;
+        delete marker.entries[shieldId];
+        writeFileAtomic(KILLSWITCH_MARKER_PATH, JSON.stringify({ entries: marker.entries }), 0o600);
+    }
+    catch { /* best-effort */ }
+}
+/** Any shield with a VALID (HMAC-verified) suspend marker? Never throws. */
+function hasValidSuspendMarker() {
+    try {
+        const marker = readKillSwitchMarker();
+        if (!marker.entries)
+            return false;
+        const secret = killSwitchSecret(false);
+        if (!secret)
+            return false;
+        return Object.entries(marker.entries).some(([shieldId, entry]) => entry && typeof entry.suspendedAt === 'string' && typeof entry.sig === 'string'
+            && killSwitchSig(secret, shieldId, entry.suspendedAt) === entry.sig);
+    }
+    catch {
+        return false;
+    }
+}
 /** A cached entry as an EffectiveBundle — single place that decides which fields survive the cache. */
 function cachedToEffective(cached) {
-    const { fetchedAt: _fetchedAt, ...bundle } = cached;
-    return { ...bundle, source: 'cache' };
+    const { fetchedAt, revalidateAttemptAt: _attemptAt, ...bundle } = cached;
+    // Kill-switch overlay: a hand-edited cache (`suspended: false`) cannot clear
+    // an admin suspension while the signed marker still stands.
+    const suspended = bundle.suspended === true || hasValidSuspendMarker();
+    // fetchedAt is refreshed on every 200 AND every 304, so it doubles as
+    // "when did the control plane last confirm this bundle" — consumers that
+    // must distinguish a validated cache from a network-down fallback (the
+    // daemon's update-policy mirror) read this instead of `source`.
+    return { ...bundle, suspended, source: 'cache', serverValidatedAt: fetchedAt };
 }
 /** Keep only a well-formed machine-role block (limits must be numbers or null; legacy keys normalized). */
 function sanitizeMachineRole(value) {
@@ -113,8 +224,26 @@ async function getRuntimeBundle(input) {
     }
     // MONITOR CONTRACT: hot-path callers never wait on a refresh for a
     // monitor/shadow machine — stale cache wins, the daemon refreshes it.
+    //
+    // BOUNDED: only while the cache is younger than HOT_PATH_MAX_STALE_MS. A
+    // cache that old means the daemon is dead and nothing else will ever pick
+    // up a kill-switch flip or a monitor->block promotion. Past the bound, ONE
+    // hook per revalidate interval falls through to the bounded (≤1.5s) refresh
+    // below; concurrent/subsequent hooks keep taking the stale cache.
     if (cached && !input.force && input.hotPath && cached.mode !== 'block') {
-        return cachedToEffective(cached);
+        const age = Date.now() - cached.fetchedAt;
+        const sinceLastAttempt = Date.now() - (cached.revalidateAttemptAt || 0);
+        if (age < HOT_PATH_MAX_STALE_MS || sinceLastAttempt < HOT_PATH_REVALIDATE_INTERVAL_MS) {
+            return cachedToEffective(cached);
+        }
+        // Claim the revalidation slot BEFORE fetching so parallel hooks don't all
+        // pay the timeout together (docker compose spawns hooks in bursts).
+        try {
+            cached.revalidateAttemptAt = Date.now();
+            cache[input.shieldId] = cached;
+            writeCacheFile(cache);
+        }
+        catch { /* best-effort */ }
     }
     try {
         const headers = { 'Content-Type': 'application/json' };
@@ -131,9 +260,15 @@ async function getRuntimeBundle(input) {
             params.set('machineId', input.machineId);
         const resp = await fetch(`${input.apiUrl}/api/cli/bundle?${params.toString()}`, { method: 'GET', headers, signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS) });
         // 304 Not Modified — cache is still valid; refresh its timestamp.
+        // Re-assert the marker when the cache says suspended, but NEVER clear it
+        // here: a 304 validates the version string, not the (locally editable)
+        // suspended field — a hand-edited `suspended: false` cache would otherwise
+        // launder the edit through the 304. Clearing requires a full server body.
         if (resp.status === 304 && cached) {
             cache[input.shieldId] = { ...cached, fetchedAt: Date.now() };
             writeCacheFile(cache);
+            if (cached.suspended === true)
+                assertSuspendMarker(input.shieldId);
             return cachedToEffective(cached);
         }
         if (resp.status === 401 || resp.status === 403) {
@@ -174,7 +309,15 @@ async function getRuntimeBundle(input) {
                 };
                 cache[input.shieldId] = entry;
                 writeCacheFile(cache);
-                return { ...entry, source: 'server' };
+                // Sync the tamper-resistant marker from the ONLY trustworthy source —
+                // a live server response. Suspended asserts it; not-suspended is the
+                // sole path that clears it.
+                if (entry.suspended)
+                    assertSuspendMarker(input.shieldId);
+                else
+                    clearSuspendMarker(input.shieldId);
+                const { fetchedAt, revalidateAttemptAt: _attemptAt, ...bundle } = entry;
+                return { ...bundle, source: 'server', serverValidatedAt: fetchedAt };
             }
         }
     }
@@ -191,6 +334,13 @@ async function getRuntimeBundle(input) {
     // not hard-block the developer. Machines that WERE told to enforce keep
     // enforcement through the stale-while-error cache above, and explicit
     // install-time --enforce/--fail-closed flags still win in the callers.
+    //
+    // EXCEPT the kill-switch: a machine whose last-known state is SUSPENDED
+    // (signed marker) stays suspended even when the cache file goes missing —
+    // deleting the cache must not unlock a suspended machine.
+    if (hasValidSuspendMarker()) {
+        return { mode: 'monitor', version: '', suspended: true, source: 'default' };
+    }
     return { mode: 'monitor', version: '', source: 'default' };
 }
 /**
@@ -253,6 +403,25 @@ function resetCacheOnEnrollment() {
         writeCacheFile({});
     }
     catch { /* cache is best-effort — never fail an enrollment over it */ }
+    // Local Safety snapshots are keyed by shieldId + identity — after a
+    // re-enrollment the old shield's snapshot (possibly ENFORCING) must not
+    // survive under a key the new identity still happens to resolve. Lazy
+    // import keeps the hook hot path free of this module.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { clearAllLocalSafetySnapshotCaches } = require('./localSafetySnapshot');
+        clearAllLocalSafetySnapshotCaches();
+    }
+    catch { /* best-effort */ }
+    // Enrollment only reaches here after the SERVER accepted a valid fleet
+    // token, so clearing the last-known-suspended marker is legitimate — the
+    // old shield binding is gone and a stale marker would otherwise suspend the
+    // re-enrolled machine forever (marker entries are keyed by old shieldIds).
+    // If the org still suspends this machine, the first bundle poll re-asserts.
+    try {
+        fs.unlinkSync(KILLSWITCH_MARKER_PATH);
+    }
+    catch { /* marker may not exist */ }
 }
 /**
  * Is ANY cached bundle marked suspended by an admin (kill-switch)?
@@ -266,7 +435,10 @@ function resetCacheOnEnrollment() {
 function isSuspendedByCache() {
     try {
         const cache = readCacheFile();
-        return Object.values(cache).some(entry => entry && entry.suspended === true);
+        if (Object.values(cache).some(entry => entry && entry.suspended === true))
+            return true;
+        // Signed last-known-suspended marker: survives cache edits AND deletion.
+        return hasValidSuspendMarker();
     }
     catch {
         return false;

package/dist/selfTest.d.ts

@@ -18,6 +18,16 @@ export interface SelfTestCheck {
     label: string;
     ok: boolean;
     detail: string;
+    /**
+     * Advisory check: a failure is worth SEEING (console shows it) but must not
+     * fail the machine's overall health. The redundant credential-store probes
+     * (native / DPAPI / key file — `credentials` + `bundle_auth` are the
+     * aggregate proof that auth actually works), the PowerShell probe (the
+     * product is PowerShell-free; hardened fleets legitimately block it), and
+     * the cosmetic windowless-tasks check are advisory. Required checks are the
+     * ones whose failure means protection or updates are actually broken.
+     */
+    optional?: boolean;
 }
 export interface SelfTestReport {
     ok: boolean;

package/dist/selfTest.js

@@ -32,13 +32,14 @@ async function runDeepSelfTest(input) {
     if (process.platform === 'win32') {
         const mode = (0, config_1.capturePowershellLanguageMode)();
         if (!mode) {
-            add({ id: 'powershell', label: 'PowerShell available', ok: false, detail: 'powershell.exe/pwsh.exe did not answer (EDR/AppLocker block?)' });
+            add({ id: 'powershell', label: 'PowerShell available', ok: false, optional: true, detail: 'powershell.exe/pwsh.exe did not answer (EDR/AppLocker block?) — advisory: the CLI is PowerShell-free on its enforcement paths' });
         }
         else {
             add({
                 id: 'powershell',
                 label: 'PowerShell available',
                 ok: true,
+                optional: true,
                 detail: `language mode: ${mode}${mode !== 'FullLanguage' ? ' (hardened — CLM-safe code paths required)' : ''}`,
             });
         }
@@ -46,20 +47,20 @@ async function runDeepSelfTest(input) {
         // store (CLI ≥1.21.34). A failure here is NOT fatal while DPAPI works,
         // but the console should see which machines run on the fallback.
         const native = (0, credentialStore_1.nativeStoreRoundtripProbe)();
-        add({ id: 'native_store', label: 'Credential Manager (native) roundtrip', ok: native.ok, detail: native.detail });
+        add({ id: 'native_store', label: 'Credential Manager (native) roundtrip', ok: native.ok, optional: true, detail: native.detail });
         // 3. DPAPI roundtrip — encrypt AND decrypt a probe value with the exact
         // snippets the CLI uses for the shield key. This is the check that would
         // have identified the lptx1110 credential break in one click. Kept as its
         // own check: it is the fallback store for machines without the native
         // binding and the rollback path to ≤1.21.33.
         const probe = (0, config_1.dpapiRoundtripProbe)();
-        add({ id: 'dpapi_roundtrip', label: 'Credential store (DPAPI) roundtrip', ok: probe.ok, detail: probe.detail });
+        add({ id: 'dpapi_roundtrip', label: 'Credential store (DPAPI) roundtrip', ok: probe.ok, optional: true, detail: probe.detail });
         // 4. Machine key file — the S4U-safe mirror the daemon/watchdog tasks
         // read (Credential Manager and DPAPI are both sealed to S4U sessions).
         // Without it, a daemon under the windowless S4U principal is key-less
         // and every bundle poll 401s.
         const keyFile = (0, machineKeyFile_1.machineKeyFileProbe)();
-        add({ id: 'machine_key_file', label: 'Machine key file (S4U mirror) roundtrip', ok: keyFile.ok, detail: keyFile.detail });
+        add({ id: 'machine_key_file', label: 'Machine key file (S4U mirror) roundtrip', ok: keyFile.ok, optional: true, detail: keyFile.detail });
     }
     // 3. Credentials resolved on THIS machine right now.
     const trace = (() => {
@@ -160,6 +161,7 @@ async function runDeepSelfTest(input) {
             id: 'windowless_tasks',
             label: 'Scheduled tasks are windowless',
             ok: flashing.length === 0,
+            optional: true,
             detail: flashing.length === 0
                 ? conhostShielded.length === 0
                     ? 'no FCD task can open a console window (S4U principals)'
@@ -167,7 +169,11 @@ async function runDeepSelfTest(input) {
                 : `visible console window on every trigger of: ${flashing.join(', ')} — bare console action on an InteractiveToken principal (neither S4U nor conhost --headless)`,
         });
     }
-    return { ok: checks.every(check => check.ok), checks, ranAt: new Date().toISOString() };
+    // Overall health gates on REQUIRED checks only. An advisory failure (e.g.
+    // PowerShell blocked on a hardened bank machine, or one of the redundant
+    // credential stores unavailable while auth demonstrably works) used to fail
+    // the whole report, training operators to ignore red self-tests entirely.
+    return { ok: checks.every(check => check.ok || check.optional === true), checks, ranAt: new Date().toISOString() };
 }
 /** FCD per-user tasks that could flash a console window on every trigger. */
 const WINDOWED_TASK_CANDIDATES = ['FullCourtDefense Daemon', 'FullCourtDefense Daemon Watchdog', 'FullCourtDefense Auto-Protect', 'FullCourtDefenseDesktopDiscover'];
@@ -192,8 +198,13 @@ function listConhostShieldedFcdTasks() {
 }
 /** Compact one-line summary for the machine-action result card. */
 function summarizeSelfTest(report) {
-    const failed = report.checks.filter(check => !check.ok);
-    if (failed.length === 0)
+    const failed = report.checks.filter(check => !check.ok && check.optional !== true);
+    const advisory = report.checks.filter(check => !check.ok && check.optional === true);
+    if (failed.length === 0 && advisory.length === 0)
         return `Deep self-test passed — all ${report.checks.length} subsystems healthy.`;
-    return `Deep self-test: ${report.checks.length - failed.length}/${report.checks.length} passed — FAILED: ${failed.map(check => `${check.id} (${check.detail})`).join('; ')}`;
+    if (failed.length === 0) {
+        return `Deep self-test passed (${report.checks.length - advisory.length}/${report.checks.length} required subsystems healthy) — advisory: ${advisory.map(check => `${check.id} (${check.detail})`).join('; ')}`;
+    }
+    const advisorySuffix = advisory.length > 0 ? ` — advisory: ${advisory.map(check => check.id).join(', ')}` : '';
+    return `Deep self-test: ${report.checks.length - failed.length - advisory.length}/${report.checks.length} passed — FAILED: ${failed.map(check => `${check.id} (${check.detail})`).join('; ')}${advisorySuffix}`;
 }

package/dist/selfUpdate.d.ts

@@ -35,11 +35,23 @@ export declare function resolveNpmCommand(platform?: NodeJS.Platform, execPath?:
  */
 export declare function buildUpdaterTaskCommand(root: string, exists?: (p: string) => boolean): string | undefined;
 /**
- * True when a registered task command still points at the PowerShell updater
- * while this install carries the Node updater — i.e. the task predates the
- * PowerShell-free updater and should be re-registered.
+ * True when a registered task command should be re-registered:
+ *   - it still points at the PowerShell updater while this install carries
+ *     the Node updater (predates the PowerShell-free updater), or
+ *   - it runs the Node updater WITHOUT `--api-url` (an old self-healed task —
+ *     those default to prod, silently retargeting staging machines).
  */
 export declare function updaterTaskNeedsModernization(taskToRun: string, root: string, exists?: (p: string) => boolean): boolean;
+/**
+ * Task Scheduler XML for the updater task — settings-parity with the MSI's
+ * own registration (Install-FullCourtDefense.ps1): StartWhenAvailable so a
+ * laptop asleep at 03:07 catches up on wake, battery-friendly so the task is
+ * not skipped/killed unplugged, SYSTEM at highest run level, daily trigger.
+ * `schtasks /Create` flags cannot express these (its defaults silently drop
+ * StartWhenAvailable and stop on battery) — registration goes through
+ * `/Create /XML` instead.
+ */
+export declare function buildUpdaterTaskXml(root: string, apiUrl: string): string | undefined;
 /**
  * Upgrade an EXISTING updater task from the PowerShell command to the Node
  * command. Machines that upgraded from a pre-Node-updater MSI keep their old
@@ -47,7 +59,7 @@ export declare function updaterTaskNeedsModernization(taskToRun: string, root: s
  * this converges them whenever a daemon runs elevated. Best-effort: needs an
  * elevated token to re-register a SYSTEM task, silent no-op otherwise.
  */
-export declare function modernizeUpdaterTask(log: (message: string) => void): void;
+export declare function modernizeUpdaterTask(log: (message: string) => void, apiUrl?: string): void;
 /**
  * Updater script log (%ProgramData%\FullCourtDefense\updater.log) — the
  * elevated task's own words. Read by the diagnostics bundle and the update-
@@ -81,6 +93,9 @@ export declare function maybeSelfUpdate(input: {
     /** Bypass the retry cooldown — used by explicit admin upgrade_cli actions so
      *  they always attempt and report the REAL outcome instead of "in progress". */
     force?: boolean;
+    /** Control-plane URL this machine is enrolled against — preserved on any
+     *  self-healed updater task so staging machines never retarget prod. */
+    apiUrl?: string;
 }): SelfUpdateResult | undefined;
 /** Version the MSI updater script reads from the installed package.json. */
 export declare function installedMsiVersion(installFolder: string): string | undefined;