@bli-cockpit/cli 0.2.21 → 0.2.23

package/dist/autostart.js

@@ -8,6 +8,21 @@ export const AUTOSTART_LABEL = "com.bli.cockpit.sync";
 export const WINDOWS_AUTOSTART_TASK_NAME = "BLI Cockpit Sync";
 const WINDOWS_AUTOSTART_SCRIPT_NAME = "autostart-sync.ps1";
 const WINDOWS_AUTOSTART_REGISTRATION_SCRIPT_NAME = "autostart-register.ps1";
+/**
+ * Windowless launcher for the scheduled sync (BLI-2677). Task Scheduler ran
+ * powershell.exe directly under an interactive token, and PowerShell is a
+ * console-subsystem binary, so every 15-minute tick flashed a conhost window
+ * over whatever the operator was doing \u2014 on every Windows machine in the
+ * fleet. wscript.exe is a GUI-subsystem host, so it never allocates a console,
+ * and it starts the PowerShell child with window style 0 (hidden). S4U was
+ * considered and rejected: it breaks on Microsoft-account logons and the task
+ * deliberately stays on InteractiveToken with least privilege.
+ */
+const WINDOWS_AUTOSTART_LAUNCHER_NAME = "autostart-sync.vbs";
+const WINDOWS_SYNC_LOG_NAME = "sync.log";
+/** With the window hidden, the log is the only place output goes; cap it so an
+ * always-on machine syncing every 15 minutes cannot grow it without bound. */
+const WINDOWS_SYNC_LOG_LIMIT_BYTES = 10 * 1024 * 1024;
 const UTF8_BOM = "\uFEFF";
 export const DEFAULT_AUTOSTART_INTERVAL_SECONDS = 15 * 60;
 /**
@@ -179,6 +194,7 @@ async function installWindowsTask(options) {
     const intervalMinutes = Math.max(1, Math.ceil(intervalSeconds / 60));
     const scriptPath = path.join(getCollectorRuntimePaths(homeDir).state_dir, WINDOWS_AUTOSTART_SCRIPT_NAME);
     const registrationPath = path.join(getCollectorRuntimePaths(homeDir).state_dir, WINDOWS_AUTOSTART_REGISTRATION_SCRIPT_NAME);
+    const launcherPath = windowsAutostartLauncherPath(homeDir);
     const nodeExecutable = path.win32.resolve(options.nodeExecutable ?? process.execPath);
     const cliEntryPoint = path.win32.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
     await mkdir(path.dirname(scriptPath), { recursive: true });
@@ -188,10 +204,18 @@ async function installWindowsTask(options) {
         dashboardUrl,
         nodeExecutable,
         cliEntryPoint,
+        syncLogPath: windowsSyncLogPath(homeDir),
     })}`, "utf8");
+    // No BOM on the launcher: wscript.exe reads .vbs files as ANSI and treats a
+    // UTF-8 BOM as an invalid character. The rendered content is ASCII-safe for
+    // every path this fleet has.
+    await writeFile(launcherPath, renderWindowsLauncherScript({
+        powershellPath: windowsPowerShellPath(),
+        scriptPath,
+    }), "utf8");
     await writeFile(registrationPath, `${UTF8_BOM}${renderWindowsRegistrationScript({
         taskName: WINDOWS_AUTOSTART_TASK_NAME,
-        scriptPath,
+        launcherPath,
         intervalMinutes,
     })}`, "utf8");
     const created = await options.exec("powershell.exe", [
@@ -240,10 +264,12 @@ async function installWindowsTask(options) {
 async function uninstallWindowsTask(options) {
     const scriptPath = windowsAutostartScriptPath(options.homeDir);
     const registrationPath = windowsAutostartRegistrationScriptPath(options.homeDir);
+    const launcherPath = windowsAutostartLauncherPath(options.homeDir);
     const current = await windowsTaskStatus(options);
     if (current.status === "absent") {
         await rm(scriptPath, { force: true });
         await rm(registrationPath, { force: true });
+        await rm(launcherPath, { force: true });
         return {
             ...current,
             plist_path: scriptPath,
@@ -259,6 +285,7 @@ async function uninstallWindowsTask(options) {
     if (removed.code === 0) {
         await rm(scriptPath, { force: true });
         await rm(registrationPath, { force: true });
+        await rm(launcherPath, { force: true });
     }
     return {
         status: removed.code === 0 ? "uninstalled" : "not_loaded",
@@ -275,6 +302,7 @@ async function uninstallWindowsTask(options) {
 }
 async function windowsTaskStatus(options) {
     const scriptPath = windowsAutostartScriptPath(options.homeDir);
+    const launcherPath = windowsAutostartLauncherPath(options.homeDir);
     const query = await options.exec("schtasks.exe", [
         "/Query",
         "/TN",
@@ -304,9 +332,9 @@ async function windowsTaskStatus(options) {
     const intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
     const intervalMinutes = Math.max(1, Math.ceil(intervalSeconds / 60));
     const registrationProblems = windowsTaskRegistrationProblems(query.stdout, {
-        scriptPath,
+        launcherPath,
         intervalMinutes,
-        powershellPath: windowsPowerShellPath(),
+        wscriptPath: windowsWScriptPath(),
     });
     if (disabled)
         registrationProblems.unshift("task is disabled");
@@ -321,12 +349,32 @@ async function windowsTaskStatus(options) {
             dashboardUrl: options.dashboardUrl ?? DEFAULT_DASHBOARD_URL,
             nodeExecutable: path.win32.resolve(options.nodeExecutable ?? process.execPath),
             cliEntryPoint: path.win32.resolve(options.cliEntryPoint ?? process.argv[1] ?? ""),
+            syncLogPath: windowsSyncLogPath(options.homeDir),
         })}`;
         const currentScript = await readFile(scriptPath, "utf8").catch(() => null);
         if (currentScript !== expectedScript) {
             registrationProblems.push("sync script does not match the current roots or Cockpit runtime");
         }
     }
+    // Same shape as the sync-script checks: existence always, content only when
+    // the caller supplied roots (a bare `autostart status` stays permissive by
+    // design — see BLI-2362). The launcher's content depends on nothing but the
+    // PowerShell path and the sync-script path, but gating keeps the two
+    // commands' disagreement surface identical to the script check above.
+    const launcherExists = await fileExists(launcherPath);
+    if (!launcherExists) {
+        registrationProblems.push("sync launcher is missing");
+    }
+    else if (options.repoRoots && options.repoRoots.length > 0) {
+        const expectedLauncher = renderWindowsLauncherScript({
+            powershellPath: windowsPowerShellPath(),
+            scriptPath,
+        });
+        const currentLauncher = await readFile(launcherPath, "utf8").catch(() => null);
+        if (currentLauncher !== expectedLauncher) {
+            registrationProblems.push("sync launcher does not match the current Cockpit runtime");
+        }
+    }
     // Both branches log. A line that only fires on failure cannot answer "did
     // background collection validate at all today?", which is the question that
     // would have caught a validator rejecting every healthy Windows task.
@@ -362,12 +410,23 @@ function windowsAutostartScriptPath(homeDir) {
 function windowsAutostartRegistrationScriptPath(homeDir) {
     return path.join(getCollectorRuntimePaths(homeDir ?? os.homedir()).state_dir, WINDOWS_AUTOSTART_REGISTRATION_SCRIPT_NAME);
 }
+function windowsAutostartLauncherPath(homeDir) {
+    return path.join(getCollectorRuntimePaths(homeDir ?? os.homedir()).state_dir, WINDOWS_AUTOSTART_LAUNCHER_NAME);
+}
+function windowsSyncLogPath(homeDir) {
+    return path.join(getCollectorRuntimePaths(homeDir ?? os.homedir()).state_dir, WINDOWS_SYNC_LOG_NAME);
+}
 function renderWindowsRegistrationScript(options) {
     return [
         "$ErrorActionPreference = 'Stop'",
         `$taskName = ${powershellLiteral(options.taskName)}`,
-        `$syncScriptPath = ${powershellLiteral(options.scriptPath)}`,
-        "$powershellPath = Join-Path $PSHOME 'powershell.exe'",
+        `$launcherPath = ${powershellLiteral(options.launcherPath)}`,
+        // wscript.exe is the windowless script host: the task runs the .vbs
+        // launcher, which starts PowerShell with its window hidden, so the
+        // 15-minute sync never flashes a terminal (BLI-2677). //B is batch mode —
+        // a script error becomes a nonzero exit instead of a modal dialog that
+        // would hang the scheduled run.
+        "$wscriptPath = Join-Path (Join-Path $env:SystemRoot 'System32') 'wscript.exe'",
         // Windows PowerShell 5.1 passes a native argument's embedded quotes to
         // CommandLineToArgvW unescaped, so a /TR value with bare quotes falls out
         // of the quoted region at the first space inside a quoted path:
@@ -376,8 +435,8 @@ function renderWindowsRegistrationScript(options) {
         // Escaping the embedded quotes as \" keeps the whole /TR value one
         // argument; Task Scheduler still normalizes what it stores (BLI-2541),
         // which the read-back validator already compares path-wise.
-        "$actionArgs = '-NoProfile -NonInteractive -ExecutionPolicy Bypass -File \\\"' + $syncScriptPath + '\\\"'",
-        "$taskCommand = '\\\"' + $powershellPath + '\\\" ' + $actionArgs",
+        "$actionArgs = '//B \\\"' + $launcherPath + '\\\"'",
+        "$taskCommand = '\\\"' + $wscriptPath + '\\\" ' + $actionArgs",
         `& schtasks.exe /Create /TN $taskName /TR $taskCommand /SC MINUTE /MO ${options.intervalMinutes} /IT /RL LIMITED /F | Out-Null`,
         "if ($LASTEXITCODE -ne 0) { throw \"schtasks /Create exited $LASTEXITCODE\" }",
         "$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -MultipleInstances IgnoreNew",
@@ -385,6 +444,30 @@ function renderWindowsRegistrationScript(options) {
         "",
     ].join("\r\n");
 }
+/**
+ * The .vbs launcher the scheduled task actually runs. WshShell.Run with window
+ * style 0 starts PowerShell with its console hidden — no flash, no focus
+ * steal — and waiting on the child propagates the sync exit code back to Task
+ * Scheduler as LastTaskResult. VBScript escapes a quote inside a string by
+ * doubling it; Windows paths cannot contain quotes, so the doubled quotes here
+ * are only the fixed delimiters around the two paths.
+ */
+function renderWindowsLauncherScript(options) {
+    const quotedPowershell = `""${options.powershellPath}""`;
+    const quotedScript = `""${options.scriptPath}""`;
+    return [
+        "' BLI Cockpit sync launcher (BLI-2677). wscript.exe never allocates a",
+        "' console and starts PowerShell hidden, so the 15-minute background sync",
+        "' does not flash a terminal over the operator. Sync output lands in",
+        "' sync.log next to this file instead of a visible window.",
+        "Option Explicit",
+        "Dim windowsShell, syncExitCode",
+        'Set windowsShell = CreateObject("WScript.Shell")',
+        `syncExitCode = windowsShell.Run("${quotedPowershell} -NoProfile -NonInteractive -ExecutionPolicy Bypass -File ${quotedScript}", 0, True)`,
+        "WScript.Quit syncExitCode",
+        "",
+    ].join("\r\n");
+}
 function renderWindowsSyncScript(options) {
     const dashboardArgs = options.dashboardUrl === DEFAULT_DASHBOARD_URL
         ? ""
@@ -392,18 +475,29 @@ function renderWindowsSyncScript(options) {
     const discoveryArgs = options.discoveryArgs.length > 0 ? ` ${options.discoveryArgs.join(" ")}` : "";
     const commands = options.workDirs.flatMap((root) => [
         "try {",
-        `  & $nodeExecutable $cliEntryPoint sync --workspace ${powershellLiteral(root)}${dashboardArgs}${discoveryArgs} --json`,
+        `  & $nodeExecutable $cliEntryPoint sync --workspace ${powershellLiteral(root)}${dashboardArgs}${discoveryArgs} --json 2>&1 | ForEach-Object { "$_" } | Add-Content -LiteralPath $syncLogPath -Encoding UTF8`,
         "  if ($LASTEXITCODE -ne 0) { $exitCode = $LASTEXITCODE }",
         "} catch {",
-        "  [Console]::Error.WriteLine($_.Exception.Message)",
+        "  Add-Content -LiteralPath $syncLogPath -Encoding UTF8 -Value $_.Exception.Message",
         "  $exitCode = 1",
         "}",
     ]);
     return [
-        "$ErrorActionPreference = 'Stop'",
+        // 'Continue', not 'Stop': the collector logs to stderr on success as well
+        // as failure (that is the repo's logging contract), and Windows PowerShell
+        // 5.1 under 'Stop' turns the first redirected stderr line of a native
+        // command into a terminating NativeCommandError — 'Stop' would kill every
+        // healthy run at its first log line. Failures are tracked by exit code.
+        "$ErrorActionPreference = 'Continue'",
         "$exitCode = 0",
         `$nodeExecutable = ${powershellLiteral(options.nodeExecutable)}`,
         `$cliEntryPoint = ${powershellLiteral(options.cliEntryPoint)}`,
+        // The task window is hidden (BLI-2677), so this log is the only place the
+        // sync's output exists; sync.err.log stays macOS-only because launchd does
+        // stream separation for free and PowerShell 5.1 does not.
+        `$syncLogPath = ${powershellLiteral(options.syncLogPath)}`,
+        `$syncLogFile = Get-Item -LiteralPath $syncLogPath -ErrorAction SilentlyContinue`,
+        `if ($syncLogFile -and $syncLogFile.Length -gt ${WINDOWS_SYNC_LOG_LIMIT_BYTES}) { Set-Content -LiteralPath $syncLogPath -Value '' -Encoding UTF8 }`,
         ...commands,
         "exit $exitCode",
         "",
@@ -462,7 +556,7 @@ function windowsTaskRegistrationProblems(taskXml, expected) {
     const actionArguments = exactExecBlock
         .match(/<Arguments>\s*([^<]*?)\s*<\/Arguments>/iu)?.[1]
         ?.trim() ?? "";
-    const expectedArgumentFlags = "-NoProfile -NonInteractive -ExecutionPolicy Bypass -File";
+    const expectedArgumentFlags = "//B";
     const requirements = [
         [
             /<DisallowStartIfOnBatteries>\s*false\s*<\/DisallowStartIfOnBatteries>/iu,
@@ -531,10 +625,10 @@ function windowsTaskRegistrationProblems(taskXml, expected) {
     if (!exactExecBlock) {
         problems.push("task must contain exactly one Exec action");
     }
-    if (!sameWindowsPath(command, expected.powershellPath)) {
-        problems.push("task action does not run the expected Windows PowerShell");
+    if (!sameWindowsPath(command, expected.wscriptPath)) {
+        problems.push("task action does not run the expected windowless script host");
     }
-    const actionArgumentProblem = windowsActionArgumentProblem(actionArguments, expectedArgumentFlags, expected.scriptPath);
+    const actionArgumentProblem = windowsActionArgumentProblem(actionArguments, expectedArgumentFlags, expected.launcherPath);
     if (actionArgumentProblem) {
         problems.push(actionArgumentProblem);
     }
@@ -547,30 +641,34 @@ function windowsPowerShellPath(env = process.env) {
     const windowsRoot = env.SystemRoot ?? env.WINDIR ?? "C:\\Windows";
     return path.win32.join(windowsRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
 }
+function windowsWScriptPath(env = process.env) {
+    const windowsRoot = env.SystemRoot ?? env.WINDIR ?? "C:\\Windows";
+    return path.win32.join(windowsRoot, "System32", "wscript.exe");
+}
 /**
  * Task Scheduler stores a normalized form of the action it was given, not the
- * string we passed: `schtasks /Create /TR "<powershell> <args>"` is split into
+ * string we passed: `schtasks /Create /TR "<host> <args>"` is split into
  * <Command> plus <Arguments>, and the quotes around a space-free script path
  * are dropped. Comparing <Arguments> against the exact string we built
  * therefore fails on a task that is registered perfectly — observed on
  * DESKTOP-G2UO1GK (CLI 0.2.13, 2026-08-12), where the stored value differed
- * from the expected one only by those quotes.
+ * from the expected one only by those quotes (BLI-2541).
  *
- * Compare the flags exactly, because those are ours, and compare the script as
- * a path, because that is what Windows normalizes. Each failure returns its own
- * reason so a repair message says which half is wrong rather than "arguments
- * differ".
+ * Compare the flags exactly, because those are ours, and compare the launcher
+ * as a path, because that is what Windows normalizes. Each failure returns its
+ * own reason so a repair message says which half is wrong rather than
+ * "arguments differ".
  */
-function windowsActionArgumentProblem(actionArguments, expectedFlags, expectedScriptPath) {
+function windowsActionArgumentProblem(actionArguments, expectedFlags, expectedLauncherPath) {
     if (!actionArguments.startsWith(expectedFlags)) {
-        return "task action does not run PowerShell with the expected Cockpit sync flags";
+        return "task action does not run the launcher with the expected batch-mode flag";
     }
-    const scriptArgument = unquoteWindowsArgument(actionArguments.slice(expectedFlags.length));
-    if (!scriptArgument) {
-        return "task action names no sync script to run";
+    const launcherArgument = unquoteWindowsArgument(actionArguments.slice(expectedFlags.length));
+    if (!launcherArgument) {
+        return "task action names no sync launcher to run";
     }
-    if (!sameWindowsPath(scriptArgument, expectedScriptPath)) {
-        return "task action runs a script other than the Cockpit sync script";
+    if (!sameWindowsPath(launcherArgument, expectedLauncherPath)) {
+        return "task action runs a script other than the Cockpit sync launcher";
     }
     return null;
 }

package/dist/commands/local.js

@@ -711,9 +711,16 @@ function sanitizeInstallErrorCode(value) {
         .slice(0, 120);
     return normalized || "unknown";
 }
+/**
+ * Posts pending install events. Also the collector's only per-tick listening
+ * post: the response carries the server-published `min_cli_version` floor
+ * (BLI-2678), so the last one observed is returned for the scheduled
+ * self-update step to act on. Every early-out returns null — no receipt, no
+ * floor.
+ */
 export async function reportInstallEventsBestEffort(options) {
     if (options.events.length === 0)
-        return;
+        return null;
     const paths = getCollectorRuntimePaths(options.homeDir);
     try {
         await enqueueInstallEventEntry(paths, {
@@ -744,17 +751,18 @@ export async function reportInstallEventsBestEffort(options) {
         if (options.json) {
             writeLine(options.io.stderr, "Install event outbox unavailable: local_write_failed");
         }
-        return;
+        return null;
     }
     const session = await readLocalCollectorSessionFile(paths).catch(() => null);
     if (!session ||
         session.session_state !== "valid" ||
         typeof session.device_token !== "string" ||
         !session.device_token) {
-        return;
+        return null;
     }
     const pending = (await readPendingInstallEventEntries(paths)).slice(0, 20);
     const failures = [];
+    let observedMinCliVersion = null;
     for (let offset = 0; offset < pending.length; offset += 5) {
         await Promise.all(pending.slice(offset, offset + 5).map(async (entry) => {
             const controller = new AbortController();
@@ -777,6 +785,13 @@ export async function reportInstallEventsBestEffort(options) {
                 if (!response.ok) {
                     throw new Error(`http_${response.status}`);
                 }
+                const receipt = (await response
+                    .json()
+                    .catch(() => null));
+                if (typeof receipt?.min_cli_version === "string" &&
+                    receipt.min_cli_version.trim()) {
+                    observedMinCliVersion = receipt.min_cli_version.trim();
+                }
                 await removeInstallEventEntry(paths, entry.outbox_id);
             }
             catch (error) {
@@ -795,6 +810,7 @@ export async function reportInstallEventsBestEffort(options) {
     if (options.json && failures.length > 0) {
         writeLine(options.io.stderr, `Install event telemetry queued for retry: ${[...new Set(failures)].join(",")}`);
     }
+    return observedMinCliVersion;
 }
 function classifyInstallTelemetryError(error) {
     if (error instanceof Error && error.name === "AbortError") {
@@ -2135,7 +2151,7 @@ async function runSync(command, io) {
     const paths = getCollectorRuntimePaths(command.homeDir);
     const config = await readLocalCollectorConfig(paths).catch(() => null);
     const dashboardUrl = command.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
-    await reportInstallEventsBestEffort({
+    const minCliVersionAtStart = await reportInstallEventsBestEffort({
         homeDir: command.homeDir,
         dashboardUrl,
         command: "sync",
@@ -2145,7 +2161,7 @@ async function runSync(command, io) {
     });
     try {
         const result = await runSyncWithHealthReceipt(command, io);
-        await reportInstallEventsBestEffort({
+        const minCliVersion = await reportInstallEventsBestEffort({
             homeDir: command.homeDir,
             dashboardUrl,
             command: "sync",
@@ -2155,11 +2171,11 @@ async function runSync(command, io) {
         });
         // BLI-2601: self-update runs only after collection's own outcome above is
         // already decided and reported, win or lose. See the function doc.
-        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl);
+        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
         return result.exitCode;
     }
     catch (error) {
-        await reportInstallEventsBestEffort({
+        const minCliVersion = await reportInstallEventsBestEffort({
             homeDir: command.homeDir,
             dashboardUrl,
             command: "sync",
@@ -2174,7 +2190,7 @@ async function runSync(command, io) {
             json: command.json,
             io,
         });
-        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl);
+        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
         throw error;
     }
 }
@@ -2188,10 +2204,10 @@ async function runSync(command, io) {
  * reported as its own named `update` receipt, never surfaced as a `sync`
  * failure or thrown from this function.
  */
-async function runScheduledSelfUpdateAfterSync(command, io, dashboardUrl) {
+async function runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion) {
     let event;
     try {
-        event = await runScheduledSelfUpdateForSync(command, io);
+        event = await runScheduledSelfUpdateForSync(command, io, minCliVersion);
     }
     catch (error) {
         // The throttle/probe/install machinery below is defensive already; this
@@ -2215,7 +2231,7 @@ async function runScheduledSelfUpdateAfterSync(command, io, dashboardUrl) {
         io,
     });
 }
-async function runScheduledSelfUpdateForSync(command, io) {
+async function runScheduledSelfUpdateForSync(command, io, minCliVersion) {
     const rawExec = io.exec;
     if (!rawExec) {
         // Only the real production `defaultIo()` supplies a process runner. A
@@ -2235,7 +2251,7 @@ async function runScheduledSelfUpdateForSync(command, io) {
         exec,
         currentVersion: LOCAL_COLLECTOR_VERSION,
         install: (tag) => attemptScheduledSelfUpdateInstall(scheduledIo, tag),
-    }, { env: io.env });
+    }, { env: io.env, minVersion: minCliVersion });
     return scheduledSelfUpdateInstallEvent(result);
 }
 async function attemptScheduledSelfUpdateInstall(io, tag) {
@@ -2260,9 +2276,21 @@ function scheduledSelfUpdateInstallEvent(result) {
     // produces a receipt.
     if (result.reason === "throttled_recent_attempt")
         return null;
-    if (result.status === "ok")
-        return { step: "update", status: "ok" };
+    // A forced attempt names its trigger in the receipt either way, so the
+    // ledger can tell "converged on the daily cadence" from "the floor pulled
+    // this machine forward" (BLI-2678).
+    const forcedDetail = result.forced && result.min_version
+        ? `forced_min_version ${result.min_version}`
+        : null;
+    if (result.status === "ok") {
+        return {
+            step: "update",
+            status: "ok",
+            ...(forcedDetail ? { error_detail: forcedDetail } : {}),
+        };
+    }
     const detail = [
+        forcedDetail,
         result.target_version ? `target ${result.target_version}` : null,
         result.installed_version ? `installed ${result.installed_version}` : null,
     ]

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.21");
+    writeLine(io?.stdout ?? process.stdout, "0.2.23");
     return 0;
   }
 

package/dist/scheduled-self-update.js

@@ -37,9 +37,22 @@ export async function runScheduledSelfUpdate(paths, deps, options = {}) {
     const env = options.env ?? process.env;
     const now = options.now ?? new Date();
     const tag = options.tag ?? "latest";
+    // BLI-2678: the fleet forced-update floor. When the server says the minimum
+    // is above what this process is running, the daily throttle stops applying —
+    // the whole point of the floor is converging faster than once a day. This is
+    // NOT remote code execution: being below the floor only makes the exact
+    // same npm self-update that runs daily anyway run now. An unparseable floor
+    // is ignored rather than obeyed — a typo must fail toward the safe default.
+    const minVersion = parseSemverTriple(options.minVersion ?? null)
+        ? options.minVersion.trim()
+        : null;
+    const forced = minVersion !== null && isSemverBelow(deps.currentVersion, minVersion);
+    const forcedFields = forced ? { forced: true, min_version: minVersion } : {};
     const marker = path.join(paths.state_dir, SELF_UPDATE_THROTTLE_MARKER);
     const lastCheck = await fs.stat(marker).catch(() => null);
-    if (lastCheck && now.getTime() - lastCheck.mtimeMs < SELF_UPDATE_MIN_INTERVAL_MS) {
+    if (!forced &&
+        lastCheck &&
+        now.getTime() - lastCheck.mtimeMs < SELF_UPDATE_MIN_INTERVAL_MS) {
         // The steady-state case: already checked today, nothing to do. Not
         // reported as an "attempt" by the caller — this fires on ~95 of every 96
         // ticks and would otherwise be pure noise.
@@ -56,11 +69,33 @@ export async function runScheduledSelfUpdate(paths, deps, options = {}) {
     // disabled machine reports itself at most once per day too, instead of on
     // every tick.
     if (env["COCKPIT_DISABLE_AUTO_UPDATE"] === "1") {
-        return { status: "skipped", reason: "disabled_by_env" };
+        // The incident-triage freeze outranks the forced floor: a human pinned
+        // this machine on purpose, and the server must not be able to unpin it.
+        return { status: "skipped", reason: "disabled_by_env", ...forcedFields };
     }
     const targetVersion = await latestCliVersionFromNpm(deps.exec, tag);
+    if (forced &&
+        targetVersion &&
+        isSemverBelow(targetVersion, minVersion)) {
+        // The floor is above what npm actually serves — a typo'd floor, or one set
+        // before the release finished publishing. Installing would not clear the
+        // floor, so every forced tick would run `npm install` forever. Skip loudly
+        // instead: this reason posts a receipt on every tick until the floor is
+        // corrected, which is exactly the alarm a misconfig should raise.
+        return {
+            status: "skipped",
+            reason: "min_version_above_npm_latest",
+            target_version: targetVersion,
+            ...forcedFields,
+        };
+    }
     if (targetVersion && targetVersion === deps.currentVersion) {
-        return { status: "ok", reason: "already_latest", target_version: targetVersion };
+        return {
+            status: "ok",
+            reason: "already_latest",
+            target_version: targetVersion,
+            ...forcedFields,
+        };
     }
     const installed = await deps.install(tag);
     if (!installed.ok) {
@@ -68,6 +103,7 @@ export async function runScheduledSelfUpdate(paths, deps, options = {}) {
             status: "fail",
             reason: installed.eacces ? "eacces_needs_chown" : "npm_install_failed",
             ...(targetVersion ? { target_version: targetVersion } : {}),
+            ...forcedFields,
         };
     }
     // Verify against what the platform returns, not the exit code npm handed
@@ -82,6 +118,7 @@ export async function runScheduledSelfUpdate(paths, deps, options = {}) {
             reason: "stale_after_self_update",
             ...(targetVersion ? { target_version: targetVersion } : {}),
             ...(installedVersion ? { installed_version: installedVersion } : {}),
+            ...forcedFields,
         };
     }
     return {
@@ -89,8 +126,37 @@ export async function runScheduledSelfUpdate(paths, deps, options = {}) {
         reason: "updated",
         target_version: targetVersion ?? installedVersion,
         installed_version: installedVersion,
+        ...forcedFields,
     };
 }
+/**
+ * Ordering comparison for the forced-update floor. Mirrors the dashboard's
+ * parseSemver/compareParsedSemver (apps/dashboard/src/lib/ambient/rollups.ts)
+ * rather than adding a `semver` dependency for two ten-line functions. A
+ * version either side fails to parse → false: an unreadable floor or version
+ * must never force anything.
+ */
+function parseSemverTriple(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = value.trim().match(/^(\d+)\.(\d+)\.(\d+)/u);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function isSemverBelow(left, right) {
+    const parsedLeft = parseSemverTriple(left);
+    const parsedRight = parseSemverTriple(right);
+    if (!parsedLeft || !parsedRight)
+        return false;
+    for (let part = 0; part < 3; part += 1) {
+        if ((parsedLeft[part] ?? 0) < (parsedRight[part] ?? 0))
+            return true;
+        if ((parsedLeft[part] ?? 0) > (parsedRight[part] ?? 0))
+            return false;
+    }
+    return false;
+}
 async function latestCliVersionFromNpm(exec, tag) {
     const result = await exec("npm", [
         "view",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "private": false,
   "type": "module",
   "bin": {