@bli-cockpit/cli 0.2.47 → 0.2.49

package/dist/autostart-windows-scripts.js

@@ -0,0 +1,310 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "./local-state.js";
+import { savedDiscoveryLimitArgs } from "./discovery-limits.js";
+import { fileExists, resolveAutostartSettings, schedulerNodeExecutable, WINDOWS_AUTOSTART_TASK_NAME, } from "./autostart-contract.js";
+/**
+ * The three files the Windows scheduled task actually runs, and how to tell
+ * whether the copies on disk still say what this build would write.
+ *
+ * Registration with Task Scheduler is the sibling file's job
+ * (autostart-windows.ts); reading back what Task Scheduler stored is
+ * autostart-windows-task-xml.ts. Renderer and drift check share this module
+ * because the check compares against the renderer's own output.
+ */
+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 — 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";
+/** Where each written file lives, so the flow can name them in one breath. */
+export function windowsAutostartScriptPath(homeDir) {
+    return windowsStateFile(homeDir, WINDOWS_AUTOSTART_SCRIPT_NAME);
+}
+export function windowsAutostartRegistrationScriptPath(homeDir) {
+    return windowsStateFile(homeDir, WINDOWS_AUTOSTART_REGISTRATION_SCRIPT_NAME);
+}
+export function windowsAutostartLauncherPath(homeDir) {
+    return windowsStateFile(homeDir, WINDOWS_AUTOSTART_LAUNCHER_NAME);
+}
+function windowsSyncLogPath(homeDir) {
+    return windowsStateFile(homeDir, WINDOWS_SYNC_LOG_NAME);
+}
+function windowsStateFile(homeDir, fileName) {
+    return path.join(getCollectorRuntimePaths(homeDir ?? os.homedir()).state_dir, fileName);
+}
+/** Windows PowerShell 5.1, always by absolute path: the scheduled task runs
+ * with a bare environment and nothing here may depend on PATH. */
+export function windowsPowerShellPath(env = process.env) {
+    const windowsRoot = env.SystemRoot ?? env.WINDIR ?? "C:\\Windows";
+    return path.win32.join(windowsRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+/** The windowless script host the task's action must name (BLI-2677). */
+export function windowsWScriptPath(env = process.env) {
+    const windowsRoot = env.SystemRoot ?? env.WINDIR ?? "C:\\Windows";
+    return path.win32.join(windowsRoot, "System32", "wscript.exe");
+}
+/**
+ * Writes the sync script, its windowless launcher, and the registration script
+ * Task Scheduler is driven by — the whole on-disk half of a Windows install,
+ * before anything is registered.
+ */
+export async function writeWindowsAutostartScripts(options) {
+    const scriptPath = windowsAutostartScriptPath(options.homeDir);
+    const launcherPath = windowsAutostartLauncherPath(options.homeDir);
+    const registrationPath = windowsAutostartRegistrationScriptPath(options.homeDir);
+    await mkdir(path.dirname(scriptPath), { recursive: true });
+    await writeFile(scriptPath, `${UTF8_BOM}${renderWindowsSyncScript({
+        discoveryArgs: await savedDiscoveryLimitArgs(options.homeDir),
+        workDirs: options.workDirs,
+        dashboardUrl: options.dashboardUrl,
+        nodeExecutable: options.nodeExecutable,
+        cliEntryPoint: options.cliEntryPoint,
+        syncLogPath: windowsSyncLogPath(options.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,
+        launcherPath,
+        intervalMinutes: options.intervalMinutes,
+    })}`, "utf8");
+    return {
+        script_path: scriptPath,
+        launcher_path: launcherPath,
+        registration_path: registrationPath,
+    };
+}
+/** Removes all three written files; used by uninstall, where a missing file is
+ * the desired end state either way. */
+export async function removeWindowsAutostartScripts(homeDir) {
+    await rm(windowsAutostartScriptPath(homeDir), { force: true });
+    await rm(windowsAutostartRegistrationScriptPath(homeDir), { force: true });
+    await rm(windowsAutostartLauncherPath(homeDir), { force: true });
+}
+/**
+ * What the sync script says it will run, parsed out of the file itself
+ * (BLI-3553) rather than rebuilt from `process.execPath`.
+ */
+export async function readRegisteredWindowsRuntimePaths(homeDir) {
+    const script = await readFile(windowsAutostartScriptPath(homeDir), "utf8").catch(() => "");
+    return {
+        node_executable: /\$nodeExecutable = '([^']*)'/u.exec(script)?.[1] ?? null,
+        cli_entry_point: /\$cliEntryPoint = '([^']*)'/u.exec(script)?.[1] ?? null,
+    };
+}
+/**
+ * Named problem with the sync script on disk, or null.
+ *
+ * Existence always; content only when the caller supplied roots (a bare
+ * `cockpit autostart status` stays permissive by design — see BLI-2362).
+ */
+export async function syncScriptProblem(options) {
+    const scriptPath = windowsAutostartScriptPath(options.homeDir);
+    if (!(await fileExists(scriptPath)))
+        return "sync script is missing";
+    if (!options.repoRoots || options.repoRoots.length === 0)
+        return null;
+    const settings = resolveAutostartSettings(options, "win32");
+    const expected = `${UTF8_BOM}${renderWindowsSyncScript({
+        discoveryArgs: await savedDiscoveryLimitArgs(options.homeDir),
+        workDirs: settings.work_dirs,
+        dashboardUrl: settings.dashboard_url,
+        nodeExecutable: (await schedulerNodeExecutable(options, "win32")).path,
+        cliEntryPoint: settings.cli_entry_point,
+        syncLogPath: windowsSyncLogPath(options.homeDir),
+    })}`;
+    const difference = renderedFileDifference(await readFile(scriptPath, "utf8").catch(() => null), expected);
+    return difference
+        ? `sync script does not match the current roots or Tower runtime (${describeDifference(difference)})`
+        : null;
+}
+/**
+ * Named problem with the .vbs launcher on disk, or null.
+ *
+ * The launcher's content depends on nothing but the PowerShell path and the
+ * sync-script path, but the roots gate is kept identical to the sync script's
+ * so the two commands' disagreement surface stays the same.
+ */
+export async function syncLauncherProblem(options) {
+    const launcherPath = windowsAutostartLauncherPath(options.homeDir);
+    if (!(await fileExists(launcherPath)))
+        return "sync launcher is missing";
+    if (!options.repoRoots || options.repoRoots.length === 0)
+        return null;
+    const expected = renderWindowsLauncherScript({
+        powershellPath: windowsPowerShellPath(),
+        scriptPath: windowsAutostartScriptPath(options.homeDir),
+    });
+    const difference = renderedFileDifference(await readFile(launcherPath, "utf8").catch(() => null), expected);
+    return difference
+        ? `sync launcher does not match the current Tower runtime (${describeDifference(difference)})`
+        : null;
+}
+function renderedFileDifference(current, expected) {
+    const expectedLines = normalizedScriptLines(expected);
+    if (current === null) {
+        return {
+            reason: "file_unreadable",
+            first_differing_line: null,
+            current_line_count: null,
+            expected_line_count: expectedLines.length,
+        };
+    }
+    if (hasByteOrderMark(current) !== hasByteOrderMark(expected)) {
+        return {
+            reason: "byte_order_mark",
+            first_differing_line: 0,
+            current_line_count: normalizedScriptLines(current).length,
+            expected_line_count: expectedLines.length,
+        };
+    }
+    const currentLines = normalizedScriptLines(current);
+    const shared = Math.min(currentLines.length, expectedLines.length);
+    for (let index = 0; index < shared; index += 1) {
+        if (currentLines[index] !== expectedLines[index]) {
+            return {
+                reason: "line_content",
+                first_differing_line: index,
+                current_line_count: currentLines.length,
+                expected_line_count: expectedLines.length,
+            };
+        }
+    }
+    if (currentLines.length !== expectedLines.length) {
+        return {
+            reason: "line_count",
+            first_differing_line: shared,
+            current_line_count: currentLines.length,
+            expected_line_count: expectedLines.length,
+        };
+    }
+    return null;
+}
+/** Safe to print: a reason label, a line index, two counts. No content. */
+function describeDifference(difference) {
+    if (difference.reason === "file_unreadable")
+        return "file could not be read";
+    if (difference.reason === "byte_order_mark")
+        return "byte-order mark differs";
+    return `${difference.reason} at line ${difference.first_differing_line}, ${difference.current_line_count} lines on disk vs ${difference.expected_line_count} expected`;
+}
+function normalizedScriptLines(value) {
+    const withoutBom = hasByteOrderMark(value) ? value.slice(UTF8_BOM.length) : value;
+    return withoutBom
+        .replace(/\r\n/gu, "\n")
+        .replace(/\s+$/u, "")
+        .split("\n");
+}
+function hasByteOrderMark(value) {
+    return value.startsWith(UTF8_BOM);
+}
+function renderWindowsRegistrationScript(options) {
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        `$taskName = ${powershellLiteral(options.taskName)}`,
+        `$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:
+        // `C:\Users\Brandon Chiem\...` reached schtasks as a stray `Chiem\...`
+        // argument and /Create exited 0x80004005 on every CLI version (BLI-2598).
+        // 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 = '//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",
+        "Set-ScheduledTask -TaskName $taskName -Settings $settings | Out-Null",
+        "",
+    ].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
+        ? ""
+        : ` --dashboard-url ${powershellLiteral(options.dashboardUrl)}`;
+    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 2>&1 | ForEach-Object { "$_" } | Add-Content -LiteralPath $syncLogPath -Encoding UTF8`,
+        "  if ($LASTEXITCODE -ne 0) { $exitCode = $LASTEXITCODE }",
+        "} catch {",
+        "  Add-Content -LiteralPath $syncLogPath -Encoding UTF8 -Value $_.Exception.Message",
+        "  $exitCode = 1",
+        "}",
+    ]);
+    return [
+        // '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",
+        "",
+    ].join("\r\n");
+}
+function powershellLiteral(value) {
+    return `'${value.replace(/'/gu, "''")}'`;
+}

package/dist/autostart-windows-task-xml.js

@@ -0,0 +1,260 @@
+import path from "node:path";
+import { decodeXmlEntities } from "./autostart-xml.js";
+/**
+ * The operator-facing problem list for a stored task definition, in the order
+ * it is read aloud in `Windows task needs repair: …`. Empty means healthy.
+ */
+export function windowsTaskRegistrationProblems(taskXml, expected) {
+    const definition = parseWindowsTaskDefinition(taskXml);
+    return [
+        ...taskSettingProblems(definition),
+        ...principalProblems(definition),
+        ...actionContextProblems(definition),
+        ...triggerProblems(definition, windowsTaskInterval(expected.intervalMinutes)),
+        ...actionProblems(definition, expected),
+        // Last on purpose: this is the order operators have read these problems in
+        // since the check was written, and the message is a joined list.
+        ...(/<Duration>/iu.test(definition.repetition)
+            ? ["repetition has a finite duration"]
+            : []),
+    ];
+}
+function parseWindowsTaskDefinition(taskXml) {
+    const decodedXml = decodeXmlEntities(taskXml);
+    const principal = soleBlock(sectionBody(decodedXml, "Principals"), "Principal");
+    const trigger = soleBlock(sectionBody(decodedXml, "Triggers"), "TimeTrigger");
+    const repetitionBlocks = trigger ? allBlocks(trigger, "Repetition") : [];
+    const execAction = soleBlock(sectionBody(decodedXml, "Actions"), "Exec");
+    return {
+        decodedXml,
+        principal,
+        principalId: principal.match(/<Principal\s[^>]*\bid\s*=\s*["']([^"']+)["'][^>]*>/iu)?.[1] ?? null,
+        trigger,
+        repetition: repetitionBlocks.length === 1 ? repetitionBlocks[0] ?? "" : "",
+        repetitionCount: repetitionBlocks.length,
+        actionContext: decodedXml.match(/<Actions\s[^>]*\bContext\s*=\s*["']([^"']+)["'][^>]*>/iu)?.[1] ?? null,
+        execAction,
+        // Strip a wrapping quote pair defensively: every real capture we have shows
+        // Task Scheduler storing <Command> unquoted, but the writer builds the /TR
+        // executable segment with the same \"-escaped quoting it uses for the
+        // launcher argument (BLI-2598), and there is no verified capture proving
+        // schtasks' own TR-splitting heuristic always discards those quotes rather
+        // than leaving them as literal text (BLI-2996 canary-gated gap). A stray
+        // pair of quotes should never be the reason a correctly-registered task
+        // reads as broken.
+        command: stripSurroundingQuotes(execAction?.match(/<Command>\s*([^<]*?)\s*<\/Command>/iu)?.[1]?.trim() ?? ""),
+        actionArguments: execAction.match(/<Arguments>\s*([^<]*?)\s*<\/Arguments>/iu)?.[1]?.trim() ??
+            "",
+    };
+}
+/** The inside of `<Tag …>…</Tag>`, or "" when the section is absent. */
+function sectionBody(xml, tag) {
+    return (new RegExp(`<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)</${tag}>`, "iu").exec(xml)?.[1] ?? "");
+}
+function allBlocks(body, tag) {
+    return [...body.matchAll(blockPattern(tag))].map((match) => match[0]);
+}
+/**
+ * The one `<Tag>…</Tag>` block in this section, or "" when there are zero, more
+ * than one, or anything else alongside it.
+ */
+function soleBlock(body, tag) {
+    const blocks = allBlocks(body, tag);
+    const remainder = body.replace(blockPattern(tag), "").trim();
+    return blocks.length === 1 && remainder === "" ? (blocks[0] ?? "") : "";
+}
+function blockPattern(tag) {
+    return new RegExp(`<${tag}(?:\\s[^>]*)?>[\\s\\S]*?</${tag}>`, "giu");
+}
+/** The battery, overlap, and missed-run settings the fleet depends on. */
+function taskSettingProblems(definition) {
+    const requirements = [
+        [
+            /<DisallowStartIfOnBatteries>\s*false\s*<\/DisallowStartIfOnBatteries>/iu,
+            "task is blocked on battery",
+        ],
+        [
+            /<StopIfGoingOnBatteries>\s*false\s*<\/StopIfGoingOnBatteries>/iu,
+            "task stops on battery",
+        ],
+        [
+            /<MultipleInstancesPolicy>\s*IgnoreNew\s*<\/MultipleInstancesPolicy>/iu,
+            "overlap policy is not IgnoreNew",
+        ],
+        [
+            /<StartWhenAvailable>\s*true\s*<\/StartWhenAvailable>/iu,
+            "missed-run recovery is disabled",
+        ],
+    ];
+    return requirements
+        .filter(([pattern]) => !pattern.test(definition.decodedXml))
+        .map(([, message]) => message);
+}
+function principalProblems(definition) {
+    if (!definition.principal) {
+        return ["task must contain exactly one principal"];
+    }
+    const problems = [];
+    if (!/<LogonType>\s*InteractiveToken\s*<\/LogonType>/iu.test(definition.principal)) {
+        problems.push("logon type is not InteractiveToken");
+    }
+    // Windows omits <RunLevel> entirely when a task runs at the default
+    // LeastPrivilege, so `schtasks /Create ... /RL LIMITED` stores a principal
+    // block with no RunLevel element at all. Demanding the element asks Windows
+    // to state a default it never states, which is why this check failed on
+    // every Windows machine in the fleet and passed on none (0 of 4
+    // autostart-alive events ok, 2026-08-12). Absent means LeastPrivilege; only
+    // an explicit elevated value is a real problem.
+    const runLevel = definition.principal
+        .match(/<RunLevel>\s*([^<]*?)\s*<\/RunLevel>/iu)?.[1]
+        ?.trim() || "LeastPrivilege";
+    if (!/^LeastPrivilege$/iu.test(runLevel)) {
+        problems.push(`task does not run with limited privileges (RunLevel=${runLevel})`);
+    }
+    return problems;
+}
+/** An action that runs as a different principal than the task declares. */
+function actionContextProblems(definition) {
+    const mismatched = definition.actionContext !== null &&
+        definition.actionContext !== definition.principalId;
+    return mismatched ? ["task action context does not match its principal"] : [];
+}
+function triggerProblems(definition, expectedInterval) {
+    const problems = [];
+    if (!definition.trigger) {
+        problems.push("task must contain exactly one TimeTrigger");
+    }
+    if (definition.repetitionCount !== 1) {
+        problems.push("task must contain exactly one repetition schedule");
+    }
+    else if (!new RegExp(`<Interval>\\s*${escapeRegExp(expectedInterval)}\\s*</Interval>`, "iu").test(definition.repetition)) {
+        problems.push(`repetition interval is not ${expectedInterval}`);
+    }
+    if (/<EndBoundary>/iu.test(definition.trigger)) {
+        problems.push("task trigger has an end boundary");
+    }
+    const randomDelay = definition.trigger
+        .match(/<RandomDelay>\s*([^<]+?)\s*<\/RandomDelay>/iu)?.[1]
+        ?.trim()
+        .toUpperCase() ?? null;
+    if (randomDelay && !["PT0S", "PT0M", "PT0H"].includes(randomDelay)) {
+        problems.push("task trigger has a nonzero random delay");
+    }
+    return problems;
+}
+/** Does the stored action still run our windowless launcher, and only it? */
+function actionProblems(definition, expected) {
+    const problems = [];
+    if (!definition.execAction) {
+        problems.push("task must contain exactly one Exec action");
+    }
+    if (!sameWindowsPath(definition.command, expected.wscriptPath)) {
+        problems.push("task action does not run the expected windowless script host");
+    }
+    const argumentProblem = windowsActionArgumentProblem(definition.actionArguments, "//B", expected.launcherPath);
+    if (argumentProblem)
+        problems.push(argumentProblem);
+    return problems;
+}
+/**
+ * Task Scheduler stores a normalized form of the action it was given, not the
+ * 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 (BLI-2541).
+ *
+ * BLI-2996: that lesson was only ever applied to the pre-BLI-2677 `-File`
+ * action. The wscript launcher pair (`//B "<launcher>"`) has NO verified
+ * real-Windows capture — `windowlessWindowsTaskXml()` in autostart.test.ts is
+ * SYNTHETIC, built by hand-editing the one real capture we have rather than
+ * exported from a machine actually running this action. A repair that rewrites
+ * the task correctly but is judged against a guessed shape can fail forever
+ * without ever being wrong (Brandon's machine: same non-convergence under two
+ * different validator messages across two CLI versions, neither of which ever
+ * repaired anything). So this comparison is deliberately structural, not
+ * positional: tokenize the way CommandLineToArgvW groups quoted/unquoted
+ * arguments, then check flag-token-then-path-token semantically (a real path
+ * comparison, case- and quote-insensitive) instead of demanding the exact
+ * byte layout we happened to send. Whatever the wscript action's real
+ * normalization turns out to be once a canary captures it, this only fails on
+ * an actual different flag or different script — not on Windows' own
+ * reformatting.
+ */
+function windowsActionArgumentProblem(actionArguments, expectedFlags, expectedLauncherPath) {
+    const tokens = splitWindowsArgumentTokens(actionArguments);
+    if (tokens.length === 0) {
+        return "task action names no sync launcher to run";
+    }
+    if ((tokens[0] ?? "").toUpperCase() !== expectedFlags.toUpperCase()) {
+        return "task action does not run the launcher with the expected batch-mode flag";
+    }
+    if (tokens.length > 2) {
+        return "task action passes unexpected extra arguments to the sync launcher";
+    }
+    const launcherArgument = tokens[1];
+    if (!launcherArgument) {
+        return "task action names no sync launcher to run";
+    }
+    if (!sameWindowsPath(launcherArgument, expectedLauncherPath)) {
+        return "task action runs a script other than the Tower sync launcher";
+    }
+    return null;
+}
+/**
+ * Quote-aware whitespace tokenizer for an already-XML-decoded `<Arguments>`
+ * value: a `"..."` run is one token (quotes stripped, whitespace inside kept),
+ * everything else splits on whitespace. Windows paths never contain a quote
+ * character, so this does not need CommandLineToArgvW's backslash-escaping
+ * rules — only its quoting rule — to tell "one argument with a space in it"
+ * apart from "two arguments".
+ */
+function splitWindowsArgumentTokens(value) {
+    const tokens = [];
+    let current = "";
+    let inQuotes = false;
+    let hasToken = false;
+    for (const char of value) {
+        if (char === '"') {
+            inQuotes = !inQuotes;
+            hasToken = true;
+            continue;
+        }
+        if (!inQuotes && /\s/u.test(char)) {
+            if (hasToken) {
+                tokens.push(current);
+                current = "";
+                hasToken = false;
+            }
+            continue;
+        }
+        current += char;
+        hasToken = true;
+    }
+    if (hasToken)
+        tokens.push(current);
+    return tokens;
+}
+/** Removes one wrapping pair of double quotes, if present. Used only to
+ * normalize before a path comparison — never to reconstruct a shell-safe
+ * value. */
+function stripSurroundingQuotes(value) {
+    const match = value.match(/^"([\s\S]*)"$/u);
+    return match ? match[1] : value;
+}
+function sameWindowsPath(left, right) {
+    if (!left || !right)
+        return false;
+    return path.win32.resolve(left).toLowerCase() ===
+        path.win32.resolve(right).toLowerCase();
+}
+/** The ISO-8601 duration Task Scheduler stores for a minutes-based cadence. */
+function windowsTaskInterval(minutes) {
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return `PT${hours > 0 ? `${hours}H` : ""}${remainingMinutes > 0 ? `${remainingMinutes}M` : ""}`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}