rightsize 0.7.8 → 0.7.10

package/dist/backend-msb/restore-broker.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The Windows-only job-object-breakaway problem this whole module exists to
+ * route around. EMPIRICALLY VERIFIED across a four-round live diagnostic
+ * campaign on Windows CI (2026-09-18): msb's detached spawn on Windows
+ * (`sdk/rust/lib/runtime/spawn.rs`, msb 0.7.1/0.7.2) always passes
+ * `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_BREAKAWAY_FROM_JOB`
+ * when it launches the new `msb.exe` that supervises a restored sandbox —
+ * `msb restore` is detached-by-design (see `MsbCliBackend.bootRestoreOnce`'s
+ * own doc), so it must spawn that new process every time. When the CALLING
+ * `msb.exe` itself sits inside a Windows job object that was never granted
+ * `JOB_OBJECT_LIMIT_BREAKAWAY_OK`, `CreateProcess` fails outright with
+ * `ERROR_ACCESS_DENIED`, and msb surfaces the bare `error: io error: Access
+ * is denied. (os error 5)` — the exact signature `isRestoreAccessDeniedFailure`
+ * matches, previously attributed entirely to a Windows file-handle release
+ * lag. Direct probes at failure time ruled the lag theory out: no msb.exe
+ * processes alive, the artifact readable/writable/hardlinkable from another
+ * process, nothing locked — the denial is the spawn itself, not the file.
+ *
+ * Gradle test workers and cargo-test binaries run inside exactly such
+ * breakaway-denying job objects (`inJob=True, limitFlags=0x0`, live-probed),
+ * which is why the sibling rust/kotlin libraries hit this deterministically
+ * on their own Windows CI while this repository's node test workers —
+ * confirmed to add no such job object — never have.
+ *
+ * THE MITIGATION IS LIVE-VALIDATED: the identical `msb restore <artifact>
+ * --name X` launched through WMI (`Invoke-CimMethod -ClassName Win32_Process
+ * -MethodName Create`), whose children run under `WmiPrvSE` OUTSIDE the
+ * caller's job hierarchy, returns `ReturnValue=0` and the restored sandbox
+ * shows Running in `msb ls` — reproduced in two separate cycles in the exact
+ * environment where a direct spawn is denied every time.
+ *
+ * This module is the resulting escape hatch: `realRestoreBroker` shells the
+ * exact same `msb restore ...` invocation through a WMI-created process
+ * instead of a direct child, for the callers in `backend.ts`
+ * (`rebootUnderFreshName`/`retryRestoreAfterAccessDenied`) that escalate to
+ * it once — and only once — a restore attempt on a Windows host hits that
+ * classified access-denied failure (POLICY v2; see those methods' own doc).
+ * It changes nothing for a healthy environment: the first attempt of any
+ * reboot is always a direct spawn, and a host that never hits the access-
+ * denied signature never touches this module at all.
+ */
+/** One brokered restore attempt whose own outcome was captured — classify `output` with the exact same predicates a direct attempt's output goes through. */
+export interface RestoreBrokerCompleted {
+    kind: "completed";
+    exitCode: number;
+    output: string;
+}
+/**
+ * The broker's own `ecFile` (see `buildOuterBrokerScript`) never appeared
+ * within its bounded wait, so no exit code/output could be read back — but
+ * the WMI `Create` call itself was accepted (`ReturnValue=0`), so the
+ * restore may well be running in the background regardless. The caller
+ * (`MsbCliBackend.bootRestoreOnce`) treats this exactly like a confirmed
+ * exit 0: skip classification and fall through to its own `msb ls`
+ * readiness poll, which — being activation-gated — settles the question on
+ * its own either way.
+ */
+export interface RestoreBrokerUnconfirmed {
+    kind: "unconfirmed";
+}
+export type RestoreBrokerResult = RestoreBrokerCompleted | RestoreBrokerUnconfirmed;
+/**
+ * The injectable seam `MsbCliBackend` calls through for every brokered
+ * restore attempt — `msbPath`/`argv` are exactly what a direct attempt would
+ * spawn (`MsbCommands.restore(spec)`'s own argv, unmodified), `timeoutMs` the
+ * same boot budget a direct attempt is held to. Rejects only for a broker-
+ * INFRASTRUCTURE failure (missing `powershell.exe`, a script-file write
+ * failure, WMI refusing to even create the process) — the caller falls back
+ * to a direct attempt on a rejection (POLICY v2 point 5: the broker must
+ * never become a new single point of failure). Resolves for every other
+ * outcome, including the brokered restore itself failing (access-denied
+ * again, an "already exists" collision, or any other msb refusal) — that is
+ * ordinary classified output for the caller to interpret, not a broker
+ * failure.
+ */
+export type RestoreBrokerLauncher = (msbPath: string, argv: readonly string[], timeoutMs: number) => Promise<RestoreBrokerResult>;
+/**
+ * Doubles every embedded `'` so `value` can be dropped verbatim into a
+ * PowerShell single-quoted string literal (`'...'`) — PowerShell's own
+ * escaping rule for that quoting style, the same one a hand-written `''`
+ * inside a single-quoted string represents a literal `'`. Applied to every
+ * interpolated value this module builds a script around (the msb binary
+ * path, every restore argv token, and the temp out/ec file paths) — never
+ * only the ones expected to need it, since a caller-controlled mount path or
+ * artifact ref is exactly the kind of value that might one day carry one.
+ */
+export declare function escapePowerShellSingleQuoted(value: string): string;
+/**
+ * The script text the WMI-created powershell process itself runs: the real
+ * `msb <argv>` invocation (the call operator `&`, since `msbPath` is a
+ * runtime string, not a literal command name), its combined stdout+stderr
+ * merged into `outFile` via PowerShell's `*>` all-streams redirection —
+ * mirroring `fetchStdoutExact`'s own reason for treating stdout+stderr as
+ * one channel — followed by writing the invocation's own `$LASTEXITCODE` to
+ * `ecFile`. Both files are how this reaches back across the WMI boundary:
+ * `Invoke-CimMethod`'s `Create` has no stdout/exit-code channel of its own
+ * (it returns only a `ProcessId` and a `ReturnValue` for the CREATE call
+ * itself, never anything about what that process goes on to do). Every path
+ * and argv token is its own single-quoted literal (`quoteSingle`) — never
+ * string-interpolated — so a value carrying spaces, `$`, or a literal `'`
+ * (an exotic mount path, in principle) round-trips as data, not script
+ * syntax.
+ */
+export declare function buildInnerRestoreScript(msbPath: string, argv: readonly string[], outFile: string, ecFile: string): string;
+/**
+ * Encodes `script` the way `powershell -EncodedCommand` requires: UTF-16LE
+ * bytes, base64. Chosen over `-Command "<script>"` specifically to sidestep
+ * a second layer of quote-escaping entirely — `buildInnerRestoreScript`'s
+ * own output already carries single-quoted literals of its own, and nesting
+ * that inside ANOTHER quoted string (the `CommandLine` this module hands to
+ * `Invoke-CimMethod`) would mean escaping quotes-within-quotes-within-quotes.
+ * A base64 payload is alphanumeric-plus-`+/=` only, so embedding it inside
+ * the OUTER script's own single-quoted `CommandLine` literal (see
+ * `buildOuterBrokerScript`) needs no escaping of its own at all.
+ */
+export declare function encodeAsEncodedCommand(script: string): string;
+/** How long `buildOuterBrokerScript`'s own polling loop waits for `ecFile` to appear before giving up and letting the caller fall through to its own `msb ls` readiness poll (see `RestoreBrokerUnconfirmed`'s own doc) — generous for `msb restore`'s own detach, which the rest of this codebase documents as "typically within seconds". */
+export declare const RESTORE_BROKER_ECFILE_WAIT_SECONDS = 30;
+/**
+ * The OUTER script — the one actually run as `powershell -NoProfile -File
+ * <script>` (see `realRestoreBroker`) — that performs the WMI escape itself
+ * and reports back what happened, all through plain stdout this module's own
+ * node-side caller can read directly (no temp file needed for THIS layer,
+ * unlike the inner restore's own output — this process's stdout pipe is
+ * ordinary, since it is never the one msb's job object would deny).
+ *
+ * `encodedInner` (see `encodeAsEncodedCommand`) is embedded inside this
+ * script's own single-quoted `$cmdLine` literal — safe with no escaping of
+ * its own, being pure base64 — as the `-EncodedCommand` argument of the
+ * powershell invocation `Invoke-CimMethod` launches. `outFile`/`ecFile` are
+ * each their own single-quoted literal via `quoteSingle`, the same as every
+ * path `buildInnerRestoreScript` embeds.
+ *
+ * `powershell.exe` (never the bare `powershell`, nor `pwsh`) both here and as
+ * the WMI-launched process's own executable — the task this whole module
+ * exists for names it explicitly "for maximum compatibility": every
+ * supported Windows release ships Windows PowerShell under that exact name,
+ * while PowerShell 7 (`pwsh`) is an opt-in install this backend has no
+ * business depending on.
+ */
+export declare function buildOuterBrokerScript(params: {
+    encodedInner: string;
+    outFile: string;
+    ecFile: string;
+    waitSeconds?: number;
+}): string;
+export interface ParsedBrokerScriptOutput {
+    /** The WMI `Create` call's own `ReturnValue` (0 == accepted), or `undefined` if the marker line itself never showed up (the outer script died before printing it). */
+    returnValue: number | undefined;
+    /** The WMI-created process's own pid, purely diagnostic — never load-bearing for classification. */
+    processId: number | undefined;
+    /** `outFile`'s contents (the brokered `msb restore`'s combined stdout+stderr), or `undefined` if `outFile` never existed when the outer script checked. */
+    outText: string | undefined;
+    /** `ecFile`'s contents (the brokered invocation's own `$LASTEXITCODE`, as text), or `undefined` if it never appeared within the wait bound. */
+    ecText: string | undefined;
+}
+/** Parses `buildOuterBrokerScript`'s own stdout back into its four parts — see `ParsedBrokerScriptOutput`'s own doc on each field. Tolerant of CRLF (PowerShell's own native line ending) and of any marker being absent, since the outer script can die (or its own wait bound expire) after printing only some of them. */
+export declare function parseBrokerScriptOutput(stdout: string): ParsedBrokerScriptOutput;
+/**
+ * The real, production `RestoreBrokerLauncher` — writes the outer script
+ * (see `buildOuterBrokerScript`) to a unique temp file, runs it via
+ * `powershell.exe -NoProfile -NonInteractive -File <script>`, and turns its
+ * parsed output (`parseBrokerScriptOutput`) into a `RestoreBrokerResult`:
+ *
+ * - WMI's own `ReturnValue` missing or non-zero (the process was never even
+ *   created) throws — broker-infrastructure failure, per this function's own
+ *   `RestoreBrokerLauncher` contract, for the caller to catch and fall back
+ *   to a direct attempt.
+ * - `ecFile` never read back (`ecText === undefined`, or unparsable as an
+ *   integer) resolves `{ kind: "unconfirmed" }` — see that type's own doc.
+ * - Otherwise resolves `{ kind: "completed", exitCode, output: outText ?? ""
+ *   }` — the brokered restore's own result, for the caller to classify
+ *   exactly like a direct attempt's.
+ *
+ * Every temp file (script, `outFile`, `ecFile`) is unique per call
+ * (`randomBytes`-suffixed, under `os.tmpdir()`) and best-effort removed in a
+ * `finally` — cleanup failures are swallowed, never allowed to mask the real
+ * outcome above.
+ */
+export declare const realRestoreBroker: RestoreBrokerLauncher;
+//# sourceMappingURL=restore-broker.d.ts.map

package/dist/backend-msb/restore-broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-broker.d.ts","sourceRoot":"","sources":["../../src/backend-msb/restore-broker.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,6JAA6J;AAC7J,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,MAAM,mBAAmB,GAAG,sBAAsB,GAAG,wBAAwB,CAAC;AAEpF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAMzH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,+UAA+U;AAC/U,eAAO,MAAM,kCAAkC,KAAK,CAAC;AASrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAwBT;AAED,MAAM,WAAW,wBAAwB;IACvC,sKAAsK;IACtK,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,oGAAoG;IACpG,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,2JAA2J;IAC3J,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+IAA+I;IAC/I,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAkCD,6TAA6T;AAC7T,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAShF;AAoDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,EAAE,qBA2C/B,CAAC"}

package/dist/backend-msb/restore-broker.js

@@ -0,0 +1,264 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CLOSED_STDIN } from "./invoke.js";
+/**
+ * Doubles every embedded `'` so `value` can be dropped verbatim into a
+ * PowerShell single-quoted string literal (`'...'`) — PowerShell's own
+ * escaping rule for that quoting style, the same one a hand-written `''`
+ * inside a single-quoted string represents a literal `'`. Applied to every
+ * interpolated value this module builds a script around (the msb binary
+ * path, every restore argv token, and the temp out/ec file paths) — never
+ * only the ones expected to need it, since a caller-controlled mount path or
+ * artifact ref is exactly the kind of value that might one day carry one.
+ */
+export function escapePowerShellSingleQuoted(value) {
+    return value.replace(/'/g, "''");
+}
+/** `value` wrapped as its own single-quoted PowerShell literal (see `escapePowerShellSingleQuoted`). */
+function quoteSingle(value) {
+    return `'${escapePowerShellSingleQuoted(value)}'`;
+}
+/**
+ * The script text the WMI-created powershell process itself runs: the real
+ * `msb <argv>` invocation (the call operator `&`, since `msbPath` is a
+ * runtime string, not a literal command name), its combined stdout+stderr
+ * merged into `outFile` via PowerShell's `*>` all-streams redirection —
+ * mirroring `fetchStdoutExact`'s own reason for treating stdout+stderr as
+ * one channel — followed by writing the invocation's own `$LASTEXITCODE` to
+ * `ecFile`. Both files are how this reaches back across the WMI boundary:
+ * `Invoke-CimMethod`'s `Create` has no stdout/exit-code channel of its own
+ * (it returns only a `ProcessId` and a `ReturnValue` for the CREATE call
+ * itself, never anything about what that process goes on to do). Every path
+ * and argv token is its own single-quoted literal (`quoteSingle`) — never
+ * string-interpolated — so a value carrying spaces, `$`, or a literal `'`
+ * (an exotic mount path, in principle) round-trips as data, not script
+ * syntax.
+ */
+export function buildInnerRestoreScript(msbPath, argv, outFile, ecFile) {
+    const quotedArgv = argv.map(quoteSingle).join(" ");
+    return [
+        `& ${quoteSingle(msbPath)} ${quotedArgv} *> ${quoteSingle(outFile)}`,
+        `Set-Content -LiteralPath ${quoteSingle(ecFile)} -Value $LASTEXITCODE -NoNewline`,
+    ].join("\n");
+}
+/**
+ * Encodes `script` the way `powershell -EncodedCommand` requires: UTF-16LE
+ * bytes, base64. Chosen over `-Command "<script>"` specifically to sidestep
+ * a second layer of quote-escaping entirely — `buildInnerRestoreScript`'s
+ * own output already carries single-quoted literals of its own, and nesting
+ * that inside ANOTHER quoted string (the `CommandLine` this module hands to
+ * `Invoke-CimMethod`) would mean escaping quotes-within-quotes-within-quotes.
+ * A base64 payload is alphanumeric-plus-`+/=` only, so embedding it inside
+ * the OUTER script's own single-quoted `CommandLine` literal (see
+ * `buildOuterBrokerScript`) needs no escaping of its own at all.
+ */
+export function encodeAsEncodedCommand(script) {
+    return Buffer.from(script, "utf16le").toString("base64");
+}
+/** How long `buildOuterBrokerScript`'s own polling loop waits for `ecFile` to appear before giving up and letting the caller fall through to its own `msb ls` readiness poll (see `RestoreBrokerUnconfirmed`'s own doc) — generous for `msb restore`'s own detach, which the rest of this codebase documents as "typically within seconds". */
+export const RESTORE_BROKER_ECFILE_WAIT_SECONDS = 30;
+const RETURN_VALUE_PREFIX = "RIGHTSIZE-BROKER-RETURNVALUE=";
+const PROCESS_ID_PREFIX = "RIGHTSIZE-BROKER-PROCESSID=";
+const OUT_BEGIN = "RIGHTSIZE-BROKER-OUT-BEGIN";
+const OUT_END = "RIGHTSIZE-BROKER-OUT-END";
+const EC_BEGIN = "RIGHTSIZE-BROKER-EC-BEGIN";
+const EC_END = "RIGHTSIZE-BROKER-EC-END";
+/**
+ * The OUTER script — the one actually run as `powershell -NoProfile -File
+ * <script>` (see `realRestoreBroker`) — that performs the WMI escape itself
+ * and reports back what happened, all through plain stdout this module's own
+ * node-side caller can read directly (no temp file needed for THIS layer,
+ * unlike the inner restore's own output — this process's stdout pipe is
+ * ordinary, since it is never the one msb's job object would deny).
+ *
+ * `encodedInner` (see `encodeAsEncodedCommand`) is embedded inside this
+ * script's own single-quoted `$cmdLine` literal — safe with no escaping of
+ * its own, being pure base64 — as the `-EncodedCommand` argument of the
+ * powershell invocation `Invoke-CimMethod` launches. `outFile`/`ecFile` are
+ * each their own single-quoted literal via `quoteSingle`, the same as every
+ * path `buildInnerRestoreScript` embeds.
+ *
+ * `powershell.exe` (never the bare `powershell`, nor `pwsh`) both here and as
+ * the WMI-launched process's own executable — the task this whole module
+ * exists for names it explicitly "for maximum compatibility": every
+ * supported Windows release ships Windows PowerShell under that exact name,
+ * while PowerShell 7 (`pwsh`) is an opt-in install this backend has no
+ * business depending on.
+ */
+export function buildOuterBrokerScript(params) {
+    const { encodedInner, outFile, ecFile } = params;
+    const waitSeconds = params.waitSeconds ?? RESTORE_BROKER_ECFILE_WAIT_SECONDS;
+    return [
+        `$ErrorActionPreference = 'Stop'`,
+        `$cmdLine = 'powershell.exe -NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encodedInner}'`,
+        `$create = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cmdLine }`,
+        `Write-Output "${RETURN_VALUE_PREFIX}$($create.ReturnValue)"`,
+        `Write-Output "${PROCESS_ID_PREFIX}$($create.ProcessId)"`,
+        `$deadline = (Get-Date).AddSeconds(${waitSeconds})`,
+        `while (-not (Test-Path -LiteralPath ${quoteSingle(ecFile)}) -and (Get-Date) -lt $deadline) {`,
+        `  Start-Sleep -Milliseconds 250`,
+        `}`,
+        `if (Test-Path -LiteralPath ${quoteSingle(outFile)}) {`,
+        `  Write-Output '${OUT_BEGIN}'`,
+        `  Get-Content -LiteralPath ${quoteSingle(outFile)} -Raw`,
+        `  Write-Output '${OUT_END}'`,
+        `}`,
+        `if (Test-Path -LiteralPath ${quoteSingle(ecFile)}) {`,
+        `  Write-Output '${EC_BEGIN}'`,
+        `  Get-Content -LiteralPath ${quoteSingle(ecFile)} -Raw`,
+        `  Write-Output '${EC_END}'`,
+        `}`,
+    ].join("\n");
+}
+function extractPrefixedInt(text, prefix) {
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith(prefix)) {
+            const parsed = Number.parseInt(trimmed.slice(prefix.length).trim(), 10);
+            return Number.isFinite(parsed) ? parsed : undefined;
+        }
+    }
+    return undefined;
+}
+function extractBetween(text, beginMarker, endMarker) {
+    const beginIdx = text.indexOf(beginMarker);
+    if (beginIdx === -1) {
+        return undefined;
+    }
+    const contentStart = text.indexOf("\n", beginIdx);
+    if (contentStart === -1) {
+        return undefined;
+    }
+    const endIdx = text.indexOf(endMarker, contentStart);
+    if (endIdx === -1) {
+        return undefined;
+    }
+    const raw = text.slice(contentStart + 1, endIdx);
+    // The captured content always carries exactly one trailing "\n" of its
+    // own — the line break between the last content line and the end
+    // marker's own line — which is an artifact of this scan, never part of
+    // what `Write-Output`/`Get-Content -Raw` actually produced; strip it.
+    return raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+}
+/** Parses `buildOuterBrokerScript`'s own stdout back into its four parts — see `ParsedBrokerScriptOutput`'s own doc on each field. Tolerant of CRLF (PowerShell's own native line ending) and of any marker being absent, since the outer script can die (or its own wait bound expire) after printing only some of them. */
+export function parseBrokerScriptOutput(stdout) {
+    const normalized = stdout.replace(/\r\n/g, "\n");
+    const ecText = extractBetween(normalized, EC_BEGIN, EC_END);
+    return {
+        returnValue: extractPrefixedInt(normalized, RETURN_VALUE_PREFIX),
+        processId: extractPrefixedInt(normalized, PROCESS_ID_PREFIX),
+        outText: extractBetween(normalized, OUT_BEGIN, OUT_END),
+        ecText: ecText?.trim(),
+    };
+}
+function runPowerShellFile(scriptFile, timeoutMs) {
+    return new Promise((resolveRun, rejectRun) => {
+        const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-File", scriptFile], {
+            stdio: [CLOSED_STDIN, "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            child.kill("SIGKILL");
+            rejectRun(new Error(`restore broker: its own powershell.exe driver did not exit within ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.once("error", (err) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            rejectRun(new Error(`restore broker: failed to spawn powershell.exe: ${err.message}`));
+        });
+        child.once("close", () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            // Combined for the same reason `fetchStdoutExact`'s sibling calls
+            // treat stdout/stderr as one channel elsewhere in this backend: the
+            // outer script's own diagnostics (a PowerShell terminating error,
+            // say) could land on either.
+            resolveRun({ stdout: stderr.length > 0 ? `${stdout}\n${stderr}` : stdout });
+        });
+    });
+}
+/**
+ * The real, production `RestoreBrokerLauncher` — writes the outer script
+ * (see `buildOuterBrokerScript`) to a unique temp file, runs it via
+ * `powershell.exe -NoProfile -NonInteractive -File <script>`, and turns its
+ * parsed output (`parseBrokerScriptOutput`) into a `RestoreBrokerResult`:
+ *
+ * - WMI's own `ReturnValue` missing or non-zero (the process was never even
+ *   created) throws — broker-infrastructure failure, per this function's own
+ *   `RestoreBrokerLauncher` contract, for the caller to catch and fall back
+ *   to a direct attempt.
+ * - `ecFile` never read back (`ecText === undefined`, or unparsable as an
+ *   integer) resolves `{ kind: "unconfirmed" }` — see that type's own doc.
+ * - Otherwise resolves `{ kind: "completed", exitCode, output: outText ?? ""
+ *   }` — the brokered restore's own result, for the caller to classify
+ *   exactly like a direct attempt's.
+ *
+ * Every temp file (script, `outFile`, `ecFile`) is unique per call
+ * (`randomBytes`-suffixed, under `os.tmpdir()`) and best-effort removed in a
+ * `finally` — cleanup failures are swallowed, never allowed to mask the real
+ * outcome above.
+ */
+export const realRestoreBroker = async (msbPath, argv, timeoutMs) => {
+    const unique = `rightsize-restore-broker-${process.pid}-${randomBytes(6).toString("hex")}`;
+    const base = path.join(os.tmpdir(), unique);
+    const scriptFile = `${base}.ps1`;
+    const outFile = `${base}.out.txt`;
+    const ecFile = `${base}.ec.txt`;
+    const inner = buildInnerRestoreScript(msbPath, argv, outFile, ecFile);
+    const outer = buildOuterBrokerScript({ encodedInner: encodeAsEncodedCommand(inner), outFile, ecFile });
+    try {
+        try {
+            await fs.writeFile(scriptFile, outer, "utf8");
+        }
+        catch (err) {
+            throw new Error(`restore broker: failed to write its own script file '${scriptFile}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const { stdout } = await runPowerShellFile(scriptFile, timeoutMs);
+        const parsed = parseBrokerScriptOutput(stdout);
+        if (parsed.returnValue === undefined) {
+            throw new Error(`restore broker: could not find a WMI ReturnValue in its own driver script's output:\n${stdout}`);
+        }
+        if (parsed.returnValue !== 0) {
+            throw new Error(`restore broker: WMI 'Win32_Process Create' refused to launch the restore (ReturnValue=${parsed.returnValue}):\n${stdout}`);
+        }
+        if (parsed.ecText === undefined) {
+            return { kind: "unconfirmed" };
+        }
+        const exitCode = Number.parseInt(parsed.ecText, 10);
+        if (!Number.isFinite(exitCode)) {
+            return { kind: "unconfirmed" };
+        }
+        return { kind: "completed", exitCode, output: parsed.outText ?? "" };
+    }
+    finally {
+        await Promise.all([
+            fs.rm(scriptFile, { force: true }).catch(() => { }),
+            fs.rm(outFile, { force: true }).catch(() => { }),
+            fs.rm(ecFile, { force: true }).catch(() => { }),
+        ]);
+    }
+};
+//# sourceMappingURL=restore-broker.js.map

package/dist/backend-msb/restore-broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-broker.js","sourceRoot":"","sources":["../../src/backend-msb/restore-broker.ts"],"names":[],"mappings":"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"}

package/dist/backend-msb/sandbox-already-exists.d.ts

@@ -0,0 +1,32 @@
+/**
+ * True if `output` (an `msb restore` invocation's combined stdout/stderr)
+ * names msb's own sandbox-name collision refusal — msb refuses to create a
+ * second sandbox under a name it already has one for. Captured shape:
+ *
+ * ```text
+ * error: sandbox 'rz-abc-1' already exists
+ * ```
+ *
+ * EMPIRICALLY VERIFIED against msb 0.7.1's own source
+ * (`prepare_create_target` in `sdk/rust/lib/backend/local/sandbox/create.rs`):
+ * the check is `existing.is_some() || dir_exists` — the refusal fires when
+ * EITHER the sandbox's database record still exists OR its on-disk directory
+ * does, two independent things that can each still be mid-release on
+ * Windows. `MsbCliBackend.createCheckpoint`'s own stop/snapshot/`rm`/restore
+ * cycle removes the source sandbox and immediately restores a fresh one
+ * under the SAME name, so a lingering release on either side races the very
+ * next `restore` straight into this refusal.
+ *
+ * Deliberately a broad, case-insensitive substring match (mirrors this
+ * backend's own `isPortBindConflictOutput`, and the sibling classifiers this
+ * whole family of msb backends — rust, kotlin — use for the identical
+ * signature) rather than a strict parse: msb has no structured/typed error
+ * for this, only combined process output, and a collision can be worded
+ * around either the sandbox's name or (rarely, alternate msb builds) its
+ * dedicated "already in use" phrasing. Only ever checked against a
+ * `msb restore` invocation's own output — a `msb snapshot load` "already
+ * exists" (see `isSnapshotAlreadyExistsError`) is a completely different
+ * command and never appears here.
+ */
+export declare function isSandboxAlreadyExistsFailure(output: string): boolean;
+//# sourceMappingURL=sandbox-already-exists.d.ts.map

package/dist/backend-msb/sandbox-already-exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-already-exists.d.ts","sourceRoot":"","sources":["../../src/backend-msb/sandbox-already-exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGrE"}

package/dist/backend-msb/sandbox-already-exists.js

@@ -0,0 +1,35 @@
+/**
+ * True if `output` (an `msb restore` invocation's combined stdout/stderr)
+ * names msb's own sandbox-name collision refusal — msb refuses to create a
+ * second sandbox under a name it already has one for. Captured shape:
+ *
+ * ```text
+ * error: sandbox 'rz-abc-1' already exists
+ * ```
+ *
+ * EMPIRICALLY VERIFIED against msb 0.7.1's own source
+ * (`prepare_create_target` in `sdk/rust/lib/backend/local/sandbox/create.rs`):
+ * the check is `existing.is_some() || dir_exists` — the refusal fires when
+ * EITHER the sandbox's database record still exists OR its on-disk directory
+ * does, two independent things that can each still be mid-release on
+ * Windows. `MsbCliBackend.createCheckpoint`'s own stop/snapshot/`rm`/restore
+ * cycle removes the source sandbox and immediately restores a fresh one
+ * under the SAME name, so a lingering release on either side races the very
+ * next `restore` straight into this refusal.
+ *
+ * Deliberately a broad, case-insensitive substring match (mirrors this
+ * backend's own `isPortBindConflictOutput`, and the sibling classifiers this
+ * whole family of msb backends — rust, kotlin — use for the identical
+ * signature) rather than a strict parse: msb has no structured/typed error
+ * for this, only combined process output, and a collision can be worded
+ * around either the sandbox's name or (rarely, alternate msb builds) its
+ * dedicated "already in use" phrasing. Only ever checked against a
+ * `msb restore` invocation's own output — a `msb snapshot load` "already
+ * exists" (see `isSnapshotAlreadyExistsError`) is a completely different
+ * command and never appears here.
+ */
+export function isSandboxAlreadyExistsFailure(output) {
+    const m = output.toLowerCase();
+    return m.includes("already exists") || (m.includes("already in use") && m.includes("name"));
+}
+//# sourceMappingURL=sandbox-already-exists.js.map

package/dist/backend-msb/sandbox-already-exists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-already-exists.js","sourceRoot":"","sources":["../../src/backend-msb/sandbox-already-exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,6BAA6B,CAAC,MAAc;IAC1D,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAC/B,OAAO,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9F,CAAC"}

package/dist/backend-msb/snapshot-create.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extracts the artifact path msb prints as the LAST line of a successful
+ * `msb snapshot create --from-sandbox ...` invocation's stdout. EMPIRICALLY
+ * VERIFIED against a real msb 0.7.1 binary: the command prints the snapshot
+ * ID line first, then the absolute artifact path as its final line —
+ * `<destDir-or-default>/<sourceSandbox>/snap_<32-hex-digest>` (see
+ * `MsbCommands.snapshotCreate`'s own doc for why the caller-supplied name
+ * never determines this path). `MsbCliBackend.createCheckpoint` uses the
+ * returned path — never the ref it asked msb to create the snapshot under —
+ * as the effective checkpoint ref for every later restore/rm/inspect call.
+ *
+ * Deliberately conservative, matching the HARD CONSTRAINT this parser was
+ * written to satisfy: trims the whole output, keeps only non-empty lines,
+ * takes the LAST one, and requires it to be an absolute path (`path.isAbsolute`)
+ * — anything else (empty output, a relative-looking last line, some future
+ * extra trailing line this parser has never seen) resolves `undefined`
+ * rather than guessing, so the caller can fail loudly with the raw,
+ * unparsed output quoted verbatim instead of minting a checkpoint ref from a
+ * misread line.
+ */
+export declare function parseSnapshotCreateArtifactPath(stdout: string): string | undefined;
+//# sourceMappingURL=snapshot-create.d.ts.map

package/dist/backend-msb/snapshot-create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-create.d.ts","sourceRoot":"","sources":["../../src/backend-msb/snapshot-create.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUlF"}

package/dist/backend-msb/snapshot-create.js

@@ -0,0 +1,33 @@
+import * as path from "node:path";
+/**
+ * Extracts the artifact path msb prints as the LAST line of a successful
+ * `msb snapshot create --from-sandbox ...` invocation's stdout. EMPIRICALLY
+ * VERIFIED against a real msb 0.7.1 binary: the command prints the snapshot
+ * ID line first, then the absolute artifact path as its final line —
+ * `<destDir-or-default>/<sourceSandbox>/snap_<32-hex-digest>` (see
+ * `MsbCommands.snapshotCreate`'s own doc for why the caller-supplied name
+ * never determines this path). `MsbCliBackend.createCheckpoint` uses the
+ * returned path — never the ref it asked msb to create the snapshot under —
+ * as the effective checkpoint ref for every later restore/rm/inspect call.
+ *
+ * Deliberately conservative, matching the HARD CONSTRAINT this parser was
+ * written to satisfy: trims the whole output, keeps only non-empty lines,
+ * takes the LAST one, and requires it to be an absolute path (`path.isAbsolute`)
+ * — anything else (empty output, a relative-looking last line, some future
+ * extra trailing line this parser has never seen) resolves `undefined`
+ * rather than guessing, so the caller can fail loudly with the raw,
+ * unparsed output quoted verbatim instead of minting a checkpoint ref from a
+ * misread line.
+ */
+export function parseSnapshotCreateArtifactPath(stdout) {
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const lastLine = lines.at(-1);
+    if (lastLine === undefined || !path.isAbsolute(lastLine)) {
+        return undefined;
+    }
+    return lastLine;
+}
+//# sourceMappingURL=snapshot-create.js.map

package/dist/backend-msb/snapshot-create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-create.js","sourceRoot":"","sources":["../../src/backend-msb/snapshot-create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,+BAA+B,CAAC,MAAc;IAC5D,MAAM,KAAK,GAAG,MAAM;SACjB,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}