@indigoai-us/hq-cli 5.345.147 → 5.345.149

package/dist/lib/lanes/watcher.js

@@ -33,7 +33,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { LanesError } from "./errors.js";
+import { LaneSchemaError, LanesError } from "./errors.js";
 import { compareEnvelopeNames } from "./envelope-sequence.js";
 import { questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, STORY_STATUSES, LANE_PROVIDERS, } from "./types.js";
@@ -738,7 +738,7 @@ export function readLatestEnvelopeFile(hqRoot, laneId, minName) {
             ref,
             path: filePath,
             text,
-            envelope: parseLaneEnvelope(JSON.parse(text)),
+            envelope: parseLaneEnvelopeForLane(hqRoot, laneId, JSON.parse(text)),
             error: null,
         };
     }
@@ -752,6 +752,31 @@ export function readLatestEnvelopeFile(hqRoot, laneId, minName) {
         };
     }
 }
+/**
+ * Parse strictly first. Only a story_complete / story_status mismatch reads the
+ * lane record: a --no-story lane (no_story_reason set) has no board story, so
+ * that mismatch is repaired instead of failing the lane. An unreadable lane
+ * record keeps the strict error.
+ */
+function parseLaneEnvelopeForLane(hqRoot, laneId, raw) {
+    try {
+        return parseLaneEnvelope(raw);
+    }
+    catch (err) {
+        if (!(err instanceof LaneSchemaError) || err.details.error !== "story_complete_status_mismatch")
+            throw err;
+        let noStory = false;
+        try {
+            noStory = readLane(hqRoot, laneId).no_story_reason !== undefined;
+        }
+        catch {
+            throw err;
+        }
+        if (!noStory)
+            throw err;
+        return parseLaneEnvelope(raw, { storyBound: false });
+    }
+}
 /** A descriptor for this run's manifest slot when no envelope file was written. */
 export function missingExpectedEnvelopeFile(hqRoot, laneId, envelopePath) {
     if (!envelopePath || !path.isAbsolute(envelopePath))

package/dist/lib/lanes/worker-continuity.d.ts

@@ -5,6 +5,8 @@ export interface WorkerContinuityLookup {
     provider: LaneProvider;
     company: LaneRecord["company"];
     freshThread?: boolean;
+    /** When set, a live lane on another machine names that machine and how to free the worker. */
+    runsHere?: (lane: LaneRecord) => boolean;
 }
 export interface WorkerContinuityResult {
     previous?: LaneRecord;

package/dist/lib/lanes/worker-continuity.js

@@ -14,6 +14,22 @@ function sameCompany(left, right) {
 function compareNewest(left, right) {
     return right.created_at.localeCompare(left.created_at) || right.lane_id.localeCompare(left.lane_id);
 }
+function workerBusyError(lookup, lane, lead, extra = {}) {
+    const remote = lookup.runsHere !== undefined && lookup.runsHere(lane) === false;
+    const fix = `hq lanes stop ${lane.lane_id}`;
+    const message = remote
+        ? `${lead} on ${lane.host.kind}:${lane.host.id} (state ${lane.state}). That lane is on another machine. Free the worker on that machine with \`${fix}\`.`
+        : `${lead} (state ${lane.state}). Free the worker with \`${fix}\`.`;
+    return new LanesError("worker_lane_busy", message, {
+        worker: lookup.worker,
+        lane_id: lane.lane_id,
+        state: lane.state,
+        host: lane.host,
+        remote,
+        fix_command: fix,
+        ...extra,
+    });
+}
 export function sameLaneHost(left, right) {
     return left.kind === right.kind && left.id === right.id;
 }
@@ -25,11 +41,7 @@ export function findWorkerContinuityLane(lanes, lookup) {
         .sort(compareNewest);
     const live = scoped.find((lane) => !isTerminalLaneState(lane.state));
     if (live) {
-        throw new LanesError("worker_lane_busy", `Worker ${lookup.worker} already has live lane ${live.lane_id}`, {
-            worker: lookup.worker,
-            lane_id: live.lane_id,
-            state: live.state,
-        });
+        throw workerBusyError(lookup, live, `Worker ${lookup.worker} already has live lane ${live.lane_id}`);
     }
     const previous = scoped[0];
     if (!previous)
@@ -45,12 +57,7 @@ export function findWorkerContinuityLane(lanes, lookup) {
             (lane.state === "queued" || lane.state === "running"))
             .sort(compareNewest)[0];
         if (liveDescendant) {
-            throw new LanesError("worker_lane_busy", `Provider thread lineage is active in lane ${liveDescendant.lane_id}`, {
-                worker: lookup.worker,
-                lane_id: liveDescendant.lane_id,
-                state: liveDescendant.state,
-                provider_session_id: previousSessionId,
-            });
+            throw workerBusyError(lookup, liveDescendant, `Provider thread lineage is active in lane ${liveDescendant.lane_id}`, { provider_session_id: previousSessionId });
         }
     }
     // Only clean, resumable terminal outcomes are safe for automatic reuse.

package/dist/lib/manifest-disabled.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The kill switch hq-cloud's manifest pass honours. Restated locally (rather
+ * than imported) for two reasons: it lives in the same unreleased module as
+ * the manifest exports, and — more importantly — we must be able to read it
+ * BEFORE deciding to do any work at all.
+ *
+ * Kept in its own leaf module so `hq doctor` can read the switch without
+ * loading `hq sync manifest` and its imports.
+ */
+export declare const MANIFEST_DISABLED_ENV = "HQ_SYNC_MANIFEST_DISABLED";
+/** True when the kill switch is set to anything other than empty/0/false. */
+export declare function manifestUploadsDisabled(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=manifest-disabled.d.ts.map

package/dist/lib/manifest-disabled.js

@@ -0,0 +1,19 @@
+/**
+ * The kill switch hq-cloud's manifest pass honours. Restated locally (rather
+ * than imported) for two reasons: it lives in the same unreleased module as
+ * the manifest exports, and — more importantly — we must be able to read it
+ * BEFORE deciding to do any work at all.
+ *
+ * Kept in its own leaf module so `hq doctor` can read the switch without
+ * loading `hq sync manifest` and its imports.
+ */
+export const MANIFEST_DISABLED_ENV = "HQ_SYNC_MANIFEST_DISABLED";
+/** True when the kill switch is set to anything other than empty/0/false. */
+export function manifestUploadsDisabled(env = process.env) {
+    const raw = env[MANIFEST_DISABLED_ENV];
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value !== "" && value !== "0" && value !== "false";
+}
+//# sourceMappingURL=manifest-disabled.js.map

package/dist/lib/service-manager/launchd.d.ts

@@ -62,6 +62,7 @@ export declare const LAUNCHD_BOOTSTRAP_BACKOFF_MS: readonly number[];
 /** Bootstrap attempts after bootout (first try + EIO retries). */
 export declare const LAUNCHD_BOOTSTRAP_ATTEMPTS: number;
 export declare const defaultRunCommand: RunCommand;
+export declare function blockingSleep(ms: number): void;
 export declare function launchdServiceTarget(plistPath: string, uid?: number): string;
 /** ProgramArguments from a LaunchAgent plist. */
 export declare function launchdPlistProgramArguments(plist: string): string[];

package/dist/lib/service-manager/launchd.js

@@ -177,7 +177,7 @@ export const defaultRunCommand = (cmd, args) => {
         stderr: r.error ? r.error.message : (typeof r.stderr === "string" ? r.stderr : ""),
     };
 };
-function blockingSleep(ms) {
+export function blockingSleep(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 function guiDomain(uid = os.userInfo().uid) {

package/dist/lib/windows/console-encoding.d.ts

@@ -0,0 +1,24 @@
+/** ASCII stand-ins for characters cmd.exe cannot show on code page 437. */
+export declare function toAscii(text: string): string;
+/** Parse `chcp` output (`Active code page: 437`). Null when the number is missing. */
+export declare function parseChcpOutput(text: string): number | null;
+type ChcpRun = () => {
+    status: number | null;
+    stdout: string;
+};
+export declare function readConsoleCodePage(run?: ChcpRun): number | null;
+export interface ConsoleEncodingDeps {
+    platform?: NodeJS.Platform;
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+    /** Known code page. Null means the page could not be read and is treated as not UTF-8. */
+    codePage?: number | null;
+    readCodePage?: () => number | null;
+}
+/**
+ * Wrap console stdout and stderr on Windows when the code page is not UTF-8.
+ * Returns false when no wrap was installed.
+ */
+export declare function installWindowsConsoleEncoding(deps?: ConsoleEncodingDeps): boolean;
+export {};
+//# sourceMappingURL=console-encoding.d.ts.map

package/dist/lib/windows/console-encoding.js

@@ -0,0 +1,83 @@
+/**
+ * cmd.exe on a non-UTF-8 code page prints UTF-8 em dashes as mojibake.
+ * When stdout or stderr is a console and the code page is not 65001, string
+ * writes are transliterated to ASCII. Pipes are left as UTF-8 so captured
+ * logs stay intact. Buffer writes are not modified.
+ */
+import { spawnSync } from "node:child_process";
+const WRAP = Symbol.for("hq.windowsConsoleEncoding");
+const REPLACEMENTS = [
+    [/\u2014/g, "--"],
+    [/\u2013/g, "-"],
+    [/\u2018|\u2019|\u201A/g, "'"],
+    [/\u201C|\u201D|\u201E/g, "\""],
+    [/\u2026/g, "..."],
+    [/\u00A0/g, " "],
+    [/\u2022/g, "*"],
+    [/\u2192/g, "->"],
+    [/\u2190/g, "<-"],
+    [/\u21D2/g, "=>"],
+    [/\u00D7/g, "x"],
+];
+/** ASCII stand-ins for characters cmd.exe cannot show on code page 437. */
+export function toAscii(text) {
+    let out = text;
+    for (const [pattern, replacement] of REPLACEMENTS)
+        out = out.replace(pattern, replacement);
+    return out.replace(/[^\t\n\r\x20-\x7E]/g, "?");
+}
+/** Parse `chcp` output (`Active code page: 437`). Null when the number is missing. */
+export function parseChcpOutput(text) {
+    const match = /:\s*(\d+)/.exec(text);
+    if (!match)
+        return null;
+    const codePage = Number(match[1]);
+    return Number.isInteger(codePage) ? codePage : null;
+}
+function defaultChcp() {
+    const result = spawnSync("chcp", [], { encoding: "utf8", windowsHide: true, timeout: 2000 });
+    return { status: result.status, stdout: result.stdout ?? "" };
+}
+export function readConsoleCodePage(run = defaultChcp) {
+    try {
+        const result = run();
+        if (result.status !== 0)
+            return null;
+        return parseChcpOutput(result.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+function wrapStream(stream) {
+    if (stream[WRAP])
+        return;
+    const original = stream.write.bind(stream);
+    stream.write = ((chunk, encoding, cb) => {
+        if (typeof chunk === "string")
+            return original(toAscii(chunk), encoding, cb);
+        return original(chunk, encoding, cb);
+    });
+    stream[WRAP] = true;
+}
+/**
+ * Wrap console stdout and stderr on Windows when the code page is not UTF-8.
+ * Returns false when no wrap was installed.
+ */
+export function installWindowsConsoleEncoding(deps = {}) {
+    if ((deps.platform ?? process.platform) !== "win32")
+        return false;
+    const stdout = (deps.stdout ?? process.stdout);
+    const stderr = (deps.stderr ?? process.stderr);
+    if (!stdout.isTTY && !stderr.isTTY)
+        return false;
+    const codePage = deps.codePage !== undefined ? deps.codePage : (deps.readCodePage ?? readConsoleCodePage)();
+    if (codePage === 65001)
+        return false;
+    if (stdout.isTTY)
+        wrapStream(stdout);
+    if (stderr.isTTY)
+        wrapStream(stderr);
+    return true;
+}
+//# sourceMappingURL=console-encoding.js.map

package/dist/lib/windows/install-followup.d.ts

@@ -0,0 +1,35 @@
+export declare function isInstallFollowupSkipped(argv: readonly string[], env: NodeJS.ProcessEnv): boolean;
+export declare function isInstalledPackageEntry(entry: string | undefined): boolean;
+/**
+ * `version`: the CLI version whose mesh daemon install succeeded.
+ * `path`: the shim folder and CLI version whose PATH step already ran, so a
+ * refused or locked HKCU is not retried on every command.
+ * `meshFailedAt`: when a daemon install for `meshFailedVersion` last failed.
+ * A failure is retried after MESH_RETRY_MS rather than on every command.
+ */
+export interface InstallFollowupMarker {
+    version?: string;
+    path?: {
+        dir: string;
+        version: string;
+    };
+    meshFailedVersion?: string;
+    meshFailedAt?: number;
+}
+/** A failed daemon install blocks for up to 30 s, so it is retried at most hourly. */
+export declare const MESH_RETRY_MS: number;
+export interface InstallFollowupDeps {
+    argv: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    /** The npm shim folder for this entry, or null when hq is not an npm global install. */
+    shimDir?: () => string | null;
+    ensurePath?: () => void;
+    /** True when the daemon install succeeded. */
+    spawnMesh?: () => boolean;
+    version?: string;
+    readMarker?: () => InstallFollowupMarker;
+    writeMarker?: (marker: InstallFollowupMarker) => void;
+    now?: () => number;
+}
+export declare function runWindowsInstallFollowup(deps: InstallFollowupDeps): void;
+//# sourceMappingURL=install-followup.d.ts.map

package/dist/lib/windows/install-followup.js

@@ -0,0 +1,142 @@
+/**
+ * Work that npm 11 will not run from postinstall: put the hq shim folder on
+ * the user PATH, and point the mesh daemon at this install once per CLI version.
+ * Failures are ignored. Hook, version, and staged-install routes do not run it.
+ *
+ * Both steps record their result in ~/.hq/install-followup.json, so later
+ * commands start no PowerShell or daemon process for the same version.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureShimOnUserPath, npmShimDir } from "./user-path.js";
+const MARKER_NAME = "install-followup.json";
+export function isInstallFollowupSkipped(argv, env) {
+    if (env.HQ_INSTALL_FOLLOWUP === "1" || env.HQ_STAGED_INSTALL === "1")
+        return true;
+    const args = argv.slice(2).filter((arg) => arg !== "--verbose");
+    if (args[0] === "mesh" && args[1] === "daemon")
+        return true;
+    if (args[0] === "daemon" && (args[1] === "run" || args[1] === "install"))
+        return true;
+    return false;
+}
+export function isInstalledPackageEntry(entry) {
+    return Boolean(entry && /node_modules[/\\]@indigoai-us[/\\]hq-cli[/\\]/i.test(entry));
+}
+function packageVersion() {
+    try {
+        const pkgPath = fileURLToPath(new URL("../../../package.json", import.meta.url));
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "";
+    }
+    catch {
+        return "";
+    }
+}
+/** A failed daemon install blocks for up to 30 s, so it is retried at most hourly. */
+export const MESH_RETRY_MS = 60 * 60 * 1000;
+function markerFile(env) {
+    const home = env.USERPROFILE || env.HOME || os.homedir();
+    return path.join(home, ".hq", MARKER_NAME);
+}
+function readMarker(env) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(markerFile(env), "utf8"));
+        const marker = {};
+        if (typeof parsed.version === "string")
+            marker.version = parsed.version;
+        if (typeof parsed.path?.dir === "string" && typeof parsed.path.version === "string") {
+            marker.path = { dir: parsed.path.dir, version: parsed.path.version };
+        }
+        if (typeof parsed.meshFailedVersion === "string" && typeof parsed.meshFailedAt === "number") {
+            marker.meshFailedVersion = parsed.meshFailedVersion;
+            marker.meshFailedAt = parsed.meshFailedAt;
+        }
+        return marker;
+    }
+    catch {
+        return {};
+    }
+}
+function writeMarker(env, marker) {
+    const file = markerFile(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(marker)}\n`);
+}
+/** True only when `hq mesh daemon install --if-stale` exited 0. */
+function defaultSpawnMesh(argv, env) {
+    const entry = argv[1];
+    if (!entry)
+        return false;
+    const result = spawnSync(process.execPath, [entry, "mesh", "daemon", "install", "--if-stale"], {
+        env: { ...env, HQ_INSTALL_FOLLOWUP: "1" },
+        timeout: 30_000,
+        windowsHide: true,
+        stdio: "ignore",
+    });
+    return result.status === 0 && !result.error;
+}
+export function runWindowsInstallFollowup(deps) {
+    const env = deps.env ?? process.env;
+    if (isInstallFollowupSkipped(deps.argv, env))
+        return;
+    const version = deps.version ?? packageVersion();
+    if (!version)
+        return;
+    const read = deps.readMarker ?? (() => readMarker(env));
+    const write = deps.writeMarker ?? ((marker) => writeMarker(env, marker));
+    const save = (update) => {
+        try {
+            write({ ...read(), ...update });
+        }
+        catch {
+            // A marker failure only means the next command tries again.
+        }
+    };
+    let shimDir;
+    try {
+        shimDir = (deps.shimDir ?? (() => npmShimDir(deps.argv[1], fs.existsSync)))();
+    }
+    catch {
+        shimDir = null;
+    }
+    const marker = read();
+    if (shimDir && !(marker.path?.dir === shimDir && marker.path.version === version)) {
+        try {
+            (deps.ensurePath ?? (() => {
+                ensureShimOnUserPath({ entry: deps.argv[1], env });
+            }))();
+        }
+        catch {
+            // PATH repair must not block the command the user asked for.
+        }
+        // Recorded whatever the outcome: a refused or locked HKCU is retried after
+        // the next upgrade, and `hq doctor` keeps reporting the missing folder.
+        save({ path: { dir: shimDir, version } });
+    }
+    if (!isInstalledPackageEntry(deps.argv[1]))
+        return;
+    const mesh = read();
+    if (mesh.version === version)
+        return;
+    const now = (deps.now ?? Date.now)();
+    if (mesh.meshFailedVersion === version && mesh.meshFailedAt !== undefined && now - mesh.meshFailedAt < MESH_RETRY_MS)
+        return;
+    let ok = false;
+    try {
+        ok = (deps.spawnMesh ?? (() => defaultSpawnMesh(deps.argv, env)))();
+    }
+    catch {
+        // The daemon install is best-effort, same as the old postinstall `|| true`.
+    }
+    // Only a successful install marks the version done. A failure is retried
+    // after MESH_RETRY_MS.
+    if (ok)
+        save({ version, meshFailedVersion: undefined, meshFailedAt: undefined });
+    else
+        save({ meshFailedVersion: version, meshFailedAt: now });
+}
+//# sourceMappingURL=install-followup.js.map

package/dist/lib/windows/user-path.d.ts

@@ -0,0 +1,125 @@
+export type PowerShellRun = (script: string, env: NodeJS.ProcessEnv) => {
+    status: number | null;
+    stdout: string;
+};
+export interface ShimPathCheck {
+    /** The folder holding `hq.cmd`. */
+    shimDir: string;
+    onPath: boolean;
+    /** Where the PATH came from: the persisted registry values, or this process's PATH when those could not be read. */
+    source: "registry" | "process";
+}
+export interface ShimPathDeps {
+    platform?: NodeJS.Platform;
+    /** The running CLI entry script (process.argv[1]). */
+    entry?: string;
+    exists?: (p: string) => boolean;
+    powerShell?: PowerShellRun;
+    env?: NodeJS.ProcessEnv;
+}
+/** The longest user Path HQ will write. Longer values break `setx` and some installers. */
+export declare const MAX_USER_PATH_LENGTH = 2047;
+/**
+ * Tests on Windows point the scripts at a scratch key with this variable. The
+ * scripts accept only keys under HKCU:\Software\HQTest\ and skip the
+ * broadcast for them.
+ */
+export declare const USER_PATH_TEST_KEY_ENV = "HQ_USER_PATH_TEST_KEY";
+/** The npm prefix folder above the package's `node_modules`, when `hq.cmd` is there. */
+export declare function npmShimDir(entry: string | undefined, exists: (p: string) => boolean): string | null;
+/** Expand `%NAME%` references the way Windows does, matching names case-insensitively. */
+export declare function expandWindowsEnv(value: string, env: NodeJS.ProcessEnv): string;
+/**
+ * Prints `U:<base64>` for the unexpanded user Path and `M:<base64>` for the
+ * machine Path, base64 of the UTF-16LE bytes, or `U-` / `M-` when a value
+ * cannot be read. Base64 is ASCII, so the console code page cannot change it.
+ */
+export declare const READ_PATHS_SCRIPT: string;
+/** Decode READ_PATHS_SCRIPT output. Null for a value that could not be read. */
+export declare function parseReadPathsOutput(stdout: string): {
+    user: string | null;
+    machine: string | null;
+};
+/**
+ * The PATH a new terminal will get: the user Path then the machine Path, as
+ * stored in the registry. Falls back to this process's PATH when neither can
+ * be read.
+ */
+export declare function readPersistedPath(run: PowerShellRun, env: NodeJS.ProcessEnv): {
+    value: string;
+    source: "registry" | "process";
+};
+export declare function isDirOnPath(dir: string, pathValue: string): boolean;
+/** Null when not on Windows or when hq was not installed as an npm global shim. */
+export declare function checkShimOnPath(deps?: ShimPathDeps): ShimPathCheck | null;
+/** Dummy user variable set and cleared so Windows tells running programs that the environment changed. */
+export declare const PATH_REFRESH_VAR = "HQ_PATH_REFRESH";
+/**
+ * A PowerShell command that appends `dir` to the user Path, keeping the value
+ * as REG_EXPAND_SZ so existing `%VAR%` entries still expand. Writing the
+ * registry alone does not notify Explorer, so terminals it opens would keep the
+ * old PATH until the next sign-in. Setting and clearing a dummy user variable
+ * through [Environment]::SetEnvironmentVariable broadcasts WM_SETTINGCHANGE.
+ */
+export declare function pathFixCommand(dir: string): string;
+/** Lines to print when the shim folder is missing from PATH; empty when it is present. */
+export declare function shimPathWarning(check: ShimPathCheck): string[];
+export type UserPathWriteReason = "unreadable" | "present" | "written" | "write-failed" | "unsafe-value" | "too-long";
+export interface UserPathWriteResult {
+    written: boolean;
+    reason: UserPathWriteReason;
+}
+/** Adds a folder to HKCU Path in one step: read, check, and write happen together. */
+export interface UserPathStore {
+    appendUserPath(dir: string): UserPathWriteResult;
+}
+export type UserPathAppendPlan = {
+    action: "write";
+    value: string;
+} | {
+    action: "skip";
+    reason: "present" | "unsafe-value" | "too-long";
+};
+/**
+ * Decide the new unexpanded user Path. Membership is decided on the expanded
+ * value so `%APPDATA%\npm` counts. The stored text keeps `%VARS%`. A value
+ * that already holds U+FFFD was garbled by an earlier decode and is never
+ * written back. The ensure script applies the same rules inside PowerShell.
+ */
+export declare function planUserPathAppend(current: string, dir: string, env: NodeJS.ProcessEnv): UserPathAppendPlan;
+/** Exit codes of ENSURE_USER_PATH_SCRIPT. */
+export declare const ENSURE_EXIT: {
+    readonly written: 0;
+    readonly badInput: 2;
+    readonly unreadable: 3;
+    readonly unsafeValue: 4;
+    readonly tooLong: 5;
+    readonly writtenNoBroadcast: 6;
+    readonly present: 10;
+};
+/**
+ * Appends $env:HQ_SHIM_DIR to the HKCU Path as REG_EXPAND_SZ, then broadcasts
+ * the change. The value is read, checked, and written inside this script, so
+ * no console encoding touches it. Mirrors planUserPathAppend.
+ */
+export declare const ENSURE_USER_PATH_SCRIPT: string;
+export declare function ensureExitReason(status: number | null): UserPathWriteResult;
+export declare function powershellUserPathStore(run?: PowerShellRun, extraEnv?: NodeJS.ProcessEnv): UserPathStore;
+export interface EnsureShimResult {
+    shimDir: string;
+    written: boolean;
+    onPath: boolean;
+    source: ShimPathCheck["source"];
+    reason: UserPathWriteReason;
+}
+export interface EnsureShimDeps extends ShimPathDeps {
+    store?: UserPathStore;
+}
+export declare function resetUserPathEnsureCacheForTests(): void;
+/**
+ * Add the npm shim folder to HKCU Path when it is missing. Null off Windows
+ * or when this process is not an npm global install. A failed read does not
+ * write. Machine Path is never written.
+ */
+export declare function ensureShimOnUserPath(deps?: EnsureShimDeps): EnsureShimResult | null;
+//# sourceMappingURL=user-path.d.ts.map