@litfamily/litcodex 1.0.0

package/dist/install/errors.js

@@ -0,0 +1,53 @@
+// M12 / T17 — typed installer error + JSON renderer (S12 §errors.ts).
+export const INSTALL_ERROR_CODES = [
+    "LITCODEX_INSTALL_CODEX_NOT_FOUND",
+    "LITCODEX_INSTALL_CODEX_VERSION_UNSUPPORTED",
+    "LITCODEX_INSTALL_HOST_PROBE_FAILED",
+    "LITCODEX_INSTALL_MARKETPLACE_ADD_FAILED",
+    "LITCODEX_INSTALL_PLUGIN_ADD_FAILED",
+    "LITCODEX_INSTALL_HOOKS_MISSING",
+    "LITCODEX_INSTALL_AGENTS_MISSING",
+    "LITCODEX_INSTALL_UNSAFE_MODEL_ROUTE",
+    "LITCODEX_INSTALL_CONFIG_WRITE_FAILED",
+    "LITCODEX_INSTALL_HOST_CONFIG_INCOMPATIBLE",
+    "LITCODEX_INSTALL_UNKNOWN_COMMAND",
+    "LITCODEX_INSTALL_BAD_FLAG",
+];
+export class InstallError extends Error {
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "InstallError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Process exit code for an installer error (S12 §Exit-code table). */
+export function exitCodeForInstallError(code) {
+    switch (code) {
+        case "LITCODEX_INSTALL_UNKNOWN_COMMAND":
+        case "LITCODEX_INSTALL_BAD_FLAG":
+            return 1;
+        case "LITCODEX_INSTALL_CODEX_NOT_FOUND":
+        case "LITCODEX_INSTALL_CODEX_VERSION_UNSUPPORTED":
+        case "LITCODEX_INSTALL_HOST_PROBE_FAILED":
+            return 2;
+        case "LITCODEX_INSTALL_MARKETPLACE_ADD_FAILED":
+        case "LITCODEX_INSTALL_PLUGIN_ADD_FAILED":
+        case "LITCODEX_INSTALL_HOOKS_MISSING":
+        case "LITCODEX_INSTALL_AGENTS_MISSING":
+        case "LITCODEX_INSTALL_UNSAFE_MODEL_ROUTE":
+        case "LITCODEX_INSTALL_CONFIG_WRITE_FAILED":
+        // Same exit code the incompatible-host-config case already returned when it
+        // was misreported as a rejected managed write; only the code name is new.
+        case "LITCODEX_INSTALL_HOST_CONFIG_INCOMPATIBLE":
+            return 3;
+    }
+}
+/** Machine-readable error envelope (written to stderr alongside a human prefix line). */
+export function toErrorJson(err) {
+    if (err instanceof InstallError) {
+        return { ok: false, error: { code: err.code, message: err.message, details: { ...err.details } } };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { code: "LITCODEX_INSTALL_UNKNOWN_COMMAND", message, details: {} } };
+}

package/dist/install/execute.d.ts

@@ -0,0 +1,56 @@
+import type { MigrateOptions, MigrateResult } from "../config-migration/index.js";
+import { type PreparedAgentSources, type WritableFsLike } from "./agents-install.js";
+import { type ReadonlyFsLike, type SpawnLike } from "./codex.js";
+import { type HostCapabilities } from "./host-capabilities.js";
+import type { InstallPreflightResult, InstallPreflightStage, InstallResult, InstallStep, InstallStepResult } from "./types.js";
+export type { WritableFsLike } from "./agents-install.js";
+/** Injectable side-effect surface (every default is overridable for tests). */
+export interface ExecuteDeps {
+    readonly spawn: SpawnLike;
+    readonly fs: ReadonlyFsLike;
+    readonly env: NodeJS.ProcessEnv;
+    readonly now: () => number;
+    /** Absolute development repo root retained for compatibility with injected hook verifiers. */
+    readonly repoRoot: string;
+    /** In-process config migration (defaults to the real M13 engine). */
+    readonly migrateConfig: (opts: MigrateOptions) => Promise<MigrateResult>;
+    /** Hook verification (defaults to the M14 resolvers over `repoRoot`). */
+    readonly verifyHook?: (repoRoot: string) => void;
+    /** Whether `--force` re-runs skippable steps despite a present probe. */
+    readonly force?: boolean;
+    /** Resolved Codex home (passed to `migrateCodexConfig` as `cwd`). */
+    readonly codexHome?: string;
+    /** Writable fs surface for agents-install (defaults to node:fs). */
+    readonly writeFs?: WritableFsLike;
+    /** Absolute path to the bundled agents source dir (defaults to resolved @litcodex/lit-loop/agents). */
+    readonly agentsSourceDir?: string;
+    /** Optional callback fired before each step begins (for TUI spinners). */
+    readonly onStepStart?: (step: InstallStep) => void;
+    /** Optional callback fired after each step completes (for TUI spinners). */
+    readonly onStepEnd?: (result: InstallStepResult) => void;
+    /** Optional callback fired when a visible pre-install preparation stage begins. */
+    readonly onPreflightStart?: (stage: InstallPreflightStage) => void;
+    /** Optional callback fired after a preparation stage completes or is intentionally skipped. */
+    readonly onPreflightEnd?: (result: InstallPreflightResult) => void;
+    readonly profile?: import("../config-migration/gpt56-policy.js").Gpt56Profile;
+    /** Explicit lead model id; "gpt-5.6-sol" routes the managed sol profile through the explicit id. */
+    readonly leadModel?: string;
+    readonly effort?: import("../config-migration/gpt56-policy.js").ReasoningEffort;
+    readonly subagentModel?: string;
+    readonly subagentEffort?: import("../config-migration/gpt56-policy.js").ReasoningEffort;
+    readonly style?: string;
+    readonly reconfigure?: boolean;
+    readonly enforceCapabilityPreflight?: boolean;
+    readonly hostCapabilities?: HostCapabilities;
+    /** Package-bundled marketplace root. Omit only for explicit custom --repo/test flows. */
+    readonly marketplaceSourceDir?: string;
+    /** Internal: payload version changed, so replace an already-installed plugin. */
+    readonly refreshPlugin?: boolean;
+    readonly authMode?: import("./auth-mode.js").AuthMode;
+    readonly preparedAgentSources?: PreparedAgentSources;
+}
+/**
+ * Run the plan in order. Returns a `Promise<InstallResult>` (config-update is async). Throws a
+ * typed `InstallError` on the first non-recoverable step failure; the dry-run path never calls this.
+ */
+export declare function executeInstallPlan(steps: readonly InstallStep[], deps: ExecuteDeps): Promise<InstallResult>;

package/dist/install/execute.js

@@ -0,0 +1,221 @@
+// M12 / T17 — install execution (S12 §execute.ts; addendum A3/A4/A5).
+//
+// SELF-CONTAINED + IDEMPOTENT. The ONLY child process ever spawned is `codex`. Each skippable
+// registration step is PROBE-GATED before spawn (addendum A5.1) so a re-install is a guaranteed
+// no-op regardless of Codex's own re-add exit codes. `config-update` is in-process: it calls
+// `migrateCodexConfig({ env, cwd: codexHome, mode: "install" })` (A3 C4) and maps every
+// `CodexConfigMigrationError` → `LITCODEX_INSTALL_CONFIG_WRITE_FAILED` (exit 3). `hooks-register`
+// is a best-effort drift guard; the real hook is wired by `codex plugin add` from the marketplace.
+// `agents-install` copies bundled litwork agent .toml files (resolved relative to THIS package, so
+// npx/global installs work regardless of cwd) into <codexHome>/agents/ except the native generic
+// default role, which is installed beside that directory and selected through the native binding;
+// all writes remain backup-safe + idempotent.
+import { CodexConfigMigrationError } from "../config-migration/errors.js";
+import { EXPLICIT_GPT56_SOL_MODEL } from "../config-migration/gpt56-policy.js";
+import { prepareAgentSources, runAgentsInstall, } from "./agents-install.js";
+import { detectAuthMode } from "./auth-mode.js";
+import { capabilityPreflightError } from "./capability-preflight-error.js";
+import { findCodexBinary, resolveCodexHome } from "./codex.js";
+import { InstallError } from "./errors.js";
+import { defaultVerifyHook } from "./hook-verifier.js";
+import { modelContextsForWrites, probeHostCapabilities } from "./host-capabilities.js";
+import { materializeManagedMarketplace } from "./marketplace-payload.js";
+import { runRegistration } from "./registration.js";
+/**
+ * Run the plan in order. Returns a `Promise<InstallResult>` (config-update is async). Throws a
+ * typed `InstallError` on the first non-recoverable step failure; the dry-run path never calls this.
+ */
+export async function executeInstallPlan(steps, deps) {
+    // Pre-flight: discover `codex` (pure, no spawn). Null → hard "not found", exit 2, zero mutation.
+    deps.onPreflightStart?.("host-capabilities");
+    const codexBin = findCodexBinary(deps.env, deps.fs);
+    if (codexBin === null) {
+        throw new InstallError("LITCODEX_INSTALL_CODEX_NOT_FOUND", "Codex CLI not found on PATH or in CODEX_HOME.", {
+            source: deps.env["CODEX_BIN"]?.trim() ? "CODEX_BIN" : "PATH",
+        });
+    }
+    const codexHome = deps.codexHome ?? resolveCodexHome(deps.env);
+    const authMode = detectAuthMode(deps.fs, codexHome);
+    const preparedAgentSources = steps.some((step) => step.kind === "agents-install")
+        ? (deps.preparedAgentSources ??
+            prepareAgentSources({
+                now: deps.now,
+                repoRoot: deps.repoRoot,
+                ...(deps.codexHome === undefined ? {} : { codexHome: deps.codexHome }),
+                ...(deps.writeFs === undefined ? {} : { writeFs: deps.writeFs }),
+                ...(deps.agentsSourceDir === undefined ? {} : { agentsSourceDir: deps.agentsSourceDir }),
+                ...(deps.subagentModel === undefined ? {} : { subagentModel: deps.subagentModel }),
+                ...(deps.subagentEffort === undefined ? {} : { subagentEffort: deps.subagentEffort }),
+                authMode,
+            }))
+        : undefined;
+    let hostCapabilities = deps.hostCapabilities;
+    if (deps.enforceCapabilityPreflight === true) {
+        hostCapabilities = probeHostCapabilities(codexBin, deps.spawn, {
+            env: deps.env,
+            ...(deps.profile === undefined ? {} : { profile: deps.profile }),
+            ...(deps.effort === undefined ? {} : { effort: deps.effort }),
+        });
+        if (hostCapabilities.concurrency.status === "unavailable") {
+            throw capabilityPreflightError(hostCapabilities, codexBin);
+        }
+    }
+    deps.onPreflightEnd?.({
+        stage: "host-capabilities",
+        status: "ok",
+        detail: hostCapabilities === undefined
+            ? "Codex CLI found"
+            : `Codex host accepted · concurrency ${hostCapabilities.concurrency.status}`,
+    });
+    deps.onPreflightStart?.("config-dry-run");
+    if (deps.enforceCapabilityPreflight === true && hostCapabilities !== undefined) {
+        await deps.migrateConfig({
+            env: deps.env,
+            ...(deps.codexHome === undefined ? {} : { cwd: deps.codexHome }),
+            mode: "install",
+            dryRun: true,
+            ...(deps.profile === undefined ? {} : { profile: deps.profile }),
+            ...(deps.effort === undefined ? {} : { effort: deps.effort }),
+            ...(deps.reconfigure === undefined ? {} : { reconfigure: deps.reconfigure }),
+            ...(deps.subagentModel === undefined ? {} : { subagentModel: deps.subagentModel }),
+            ...(deps.subagentEffort === undefined ? {} : { subagentEffort: deps.subagentEffort }),
+            modelContexts: modelContextsForWrites(hostCapabilities),
+        });
+        deps.onPreflightEnd?.({
+            stage: "config-dry-run",
+            status: "ok",
+            detail: "strict config accepted · no files changed",
+        });
+    }
+    else {
+        deps.onPreflightEnd?.({
+            stage: "config-dry-run",
+            status: "skipped",
+            detail: "host config validation not requested",
+        });
+    }
+    deps.onPreflightStart?.("marketplace-payload");
+    const marketplaceStep = steps.find((step) => step.kind === "marketplace-add");
+    const marketplaceTarget = marketplaceStep?.command?.at(-1);
+    const payload = deps.marketplaceSourceDir === undefined || marketplaceTarget === undefined
+        ? undefined
+        : materializeManagedMarketplace({ sourceRoot: deps.marketplaceSourceDir, targetRoot: marketplaceTarget });
+    deps.onPreflightEnd?.({
+        stage: "marketplace-payload",
+        status: payload === undefined ? "skipped" : "ok",
+        detail: payload === undefined
+            ? "custom or test marketplace source retained"
+            : payload.changed
+                ? "bundled marketplace payload staged"
+                : "bundled marketplace payload already current",
+    });
+    const results = [];
+    const effectiveDeps = {
+        ...deps,
+        ...(hostCapabilities === undefined ? {} : { hostCapabilities }),
+        ...(payload?.changed === true ? { refreshPlugin: true } : {}),
+        authMode,
+        ...(preparedAgentSources === undefined ? {} : { preparedAgentSources }),
+    };
+    for (const step of steps) {
+        deps.onStepStart?.(step);
+        try {
+            const result = await runStep(step, codexBin, effectiveDeps);
+            deps.onStepEnd?.(result);
+            results.push(result);
+        }
+        catch (error) {
+            deps.onStepEnd?.({
+                kind: step.kind,
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    return {
+        ok: results.every((r) => r.status !== "failed"),
+        steps: results,
+        codexHome: deps.codexHome ?? "",
+        ...(hostCapabilities === undefined ? {} : { capabilities: hostCapabilities }),
+    };
+}
+async function runStep(step, codexBin, deps) {
+    switch (step.kind) {
+        case "marketplace-add":
+            return runRegistration(step, codexBin, deps, "marketplace");
+        case "plugin-add":
+            return runRegistration(step, codexBin, deps, "plugin");
+        case "hooks-register":
+            return runHooksRegister(step, deps);
+        case "agents-install":
+            return runAgentsInstall(step, deps);
+        case "config-update":
+            return runConfigUpdate(step, deps);
+        case "verify":
+            return ok(step, "doctor passed");
+    }
+}
+/** Verify the host wired the bundled UserPromptSubmit hook; fail loudly if the payload is broken. */
+function runHooksRegister(step, deps) {
+    try {
+        const verify = deps.verifyHook ?? defaultVerifyHook;
+        verify(deps.repoRoot);
+    }
+    catch (err) {
+        throw new InstallError("LITCODEX_INSTALL_HOOKS_MISSING", "Bundled lit-loop UserPromptSubmit hook payload is missing or malformed.", { cause: err instanceof Error ? err.message : String(err) });
+    }
+    return { kind: step.kind, status: "skipped", detail: "UserPromptSubmit hook wired (manifest-driven)" };
+}
+/** In-process config migration via the M13 engine; collapses all M13 codes → CONFIG_WRITE_FAILED. */
+async function runConfigUpdate(step, deps) {
+    let res;
+    const migrateOpts = { env: deps.env, mode: "install" };
+    if (deps.codexHome !== undefined) {
+        migrateOpts.cwd = deps.codexHome;
+    }
+    try {
+        res = await deps.migrateConfig({
+            ...migrateOpts,
+            ...(deps.profile === undefined ? {} : { profile: deps.profile }),
+            ...(deps.effort === undefined ? {} : { effort: deps.effort }),
+            ...(deps.style === undefined ? {} : { style: deps.style }),
+            ...(deps.reconfigure === undefined ? {} : { reconfigure: deps.reconfigure }),
+            ...(deps.hostCapabilities === undefined
+                ? {}
+                : { modelContexts: modelContextsForWrites(deps.hostCapabilities) }),
+            ...(deps.subagentModel === undefined ? {} : { subagentModel: deps.subagentModel }),
+            ...(deps.subagentEffort === undefined ? {} : { subagentEffort: deps.subagentEffort }),
+            ...(deps.authMode === "chatgpt" || deps.leadModel === EXPLICIT_GPT56_SOL_MODEL
+                ? { solModelOverride: EXPLICIT_GPT56_SOL_MODEL }
+                : {}),
+        });
+    }
+    catch (e) {
+        if (e instanceof CodexConfigMigrationError) {
+            throw new InstallError("LITCODEX_INSTALL_CONFIG_WRITE_FAILED", e.message, {
+                cause: e.code,
+                configPath: e.configPath,
+                ...e.details,
+            });
+        }
+        throw e;
+    }
+    const rootPreserved = res.skipped.some((skip) => skip.reason === "user-modified" || skip.reason === "preserved");
+    if (res.changed.length > 0 && rootPreserved) {
+        return mark(step, "ok", `config partially applied (${res.changed.length} file(s)); root preserved, review --dry-run then use --reconfigure for a one-time managed update`);
+    }
+    if (res.changed.length > 0) {
+        return mark(step, "ok", `config.toml managed keys updated (${res.changed.length} file(s))`);
+    }
+    if (rootPreserved) {
+        return mark(step, "skipped", "config preserved; review --dry-run, then use --reconfigure for a one-time managed update");
+    }
+    return mark(step, "skipped", "config.toml already current");
+}
+function ok(step, detail) {
+    return mark(step, "ok", detail);
+}
+function mark(step, status, detail) {
+    return { kind: step.kind, status, detail };
+}

package/dist/install/file-walk.d.ts

@@ -0,0 +1,33 @@
+import { closeSync, constants, type Dir, type Dirent, fstatSync, lstatSync, openSync } from "node:fs";
+export interface WalkedEntry {
+    readonly absolutePath: string;
+    readonly relativePath: string;
+    readonly kind: "directory" | "file" | "unexpected";
+}
+export interface PayloadEntry {
+    readonly relativePath: string;
+    readonly kind: "file" | "unexpected";
+}
+export type PayloadDirectoryReader = (directory: Dir, lexicalPath: string) => readonly Dirent<string>[];
+export type PayloadDirectoryCapability = "posix-verified-fd" | "windows-stable-path";
+export interface StableFileReadFs {
+    readonly closeSync: typeof closeSync;
+    readonly constants: typeof constants;
+    readonly fstatSync: typeof fstatSync;
+    readonly lstatSync: typeof lstatSync;
+    readonly openSync: typeof openSync;
+    readonly readFileSync: (fd: number) => Uint8Array;
+}
+/** Enumerate a directory without following links, using APIs available at the Node 20.0 floor. */
+export declare function walkDirectory(root: string, directoryReader?: PayloadDirectoryReader, directoryCapability?: PayloadDirectoryCapability): readonly WalkedEntry[];
+/**
+ * Return every non-directory entry for exact payload comparison.
+ *
+ * Regular files are expected. Symlinks, sockets, FIFOs, devices, and other special
+ * entries deliberately remain in the returned path set so callers fail closed.
+ */
+export declare function listPayloadPaths(root: string): readonly string[];
+/** Preserve each non-directory entry's no-follow kind for exact installed-payload checks. */
+export declare function listPayloadEntries(root: string, directoryReader?: PayloadDirectoryReader, directoryCapability?: PayloadDirectoryCapability): readonly PayloadEntry[];
+/** Read one stable regular-file identity without following a leaf symbolic link. */
+export declare function readRegularFileBuffer(path: string, fs?: StableFileReadFs): Uint8Array;

package/dist/install/file-walk.js

@@ -0,0 +1,252 @@
+import { closeSync, constants, fstatSync, lstatSync, opendirSync, openSync, readdirSync, readFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+const nativeDirectoryCapability = process.platform === "win32" ? "windows-stable-path" : "posix-verified-fd";
+const NODE_FILE_READ_FS = Object.freeze({
+    closeSync,
+    constants,
+    fstatSync,
+    lstatSync,
+    openSync,
+    readFileSync: (fd) => readFileSync(fd),
+});
+function pathDirectoryMetadata(path) {
+    const metadata = lstatSync(path, { bigint: true });
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+        throw new Error("payload directory is not a real directory");
+    }
+    return metadata;
+}
+function directoryMetadataMatches(left, right) {
+    return (left.isDirectory() &&
+        right.isDirectory() &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.birthtimeNs === right.birthtimeNs &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function exactDirectoryEntries(entries) {
+    return entries
+        .map((entry) => [entry.name, entry.isDirectory() ? "directory" : entry.isFile() ? "file" : "unexpected"])
+        .sort(([leftName, leftKind], [rightName, rightKind]) => leftName === rightName ? leftKind.localeCompare(rightKind) : leftName.localeCompare(rightName))
+        .map((entry) => JSON.stringify(entry));
+}
+function openFileDescriptors() {
+    for (const registry of ["/proc/self/fd", "/dev/fd"]) {
+        try {
+            const descriptors = new Map();
+            for (const name of readdirSync(registry)) {
+                const descriptor = Number(name);
+                if (!Number.isInteger(descriptor) || descriptor < 0)
+                    continue;
+                try {
+                    const identity = fstatSync(descriptor, { bigint: true });
+                    descriptors.set(descriptor, `${identity.dev}:${identity.ino}`);
+                }
+                catch {
+                    // Ignore the registry's already-closed enumeration descriptor.
+                }
+            }
+            return descriptors;
+        }
+        catch {
+            // Try the next platform descriptor registry.
+        }
+    }
+    throw new Error("open file descriptors cannot be inspected safely");
+}
+const readDirectoryFromDescriptor = (directory) => {
+    const entries = [];
+    for (let entry = directory.readSync(); entry !== null; entry = directory.readSync())
+        entries.push(entry);
+    return entries;
+};
+function readPosixStableDirectory(path, directoryReader) {
+    const before = pathDirectoryMetadata(path);
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fstatSync(fd, { bigint: true });
+        if (!opened.isDirectory() ||
+            opened.dev !== before.dev ||
+            opened.ino !== before.ino ||
+            opened.ctimeNs !== before.ctimeNs ||
+            opened.birthtimeNs !== before.birthtimeNs) {
+            throw new Error("payload directory identity changed before enumeration");
+        }
+        const descriptorsBefore = openFileDescriptors();
+        const openedIdentity = `${opened.dev}:${opened.ino}`;
+        const directory = opendirSync(path);
+        try {
+            const directoryDescriptors = [...openFileDescriptors()].flatMap(([descriptor, identity]) => descriptor !== fd && identity === openedIdentity && descriptorsBefore.get(descriptor) !== identity
+                ? [descriptor]
+                : []);
+            const [directoryDescriptor] = directoryDescriptors;
+            if (directoryDescriptors.length !== 1 || directoryDescriptor === undefined) {
+                throw new Error("payload directory descriptor cannot be identified safely");
+            }
+            const directoryBefore = fstatSync(directoryDescriptor, { bigint: true });
+            if (!directoryBefore.isDirectory() ||
+                directoryBefore.dev !== opened.dev ||
+                directoryBefore.ino !== opened.ino ||
+                directoryBefore.ctimeNs !== opened.ctimeNs ||
+                directoryBefore.birthtimeNs !== opened.birthtimeNs) {
+                throw new Error("payload directory descriptor identity changed before enumeration");
+            }
+            const entries = directoryReader(directory, path);
+            const directoryAfter = fstatSync(directoryDescriptor, { bigint: true });
+            if (!directoryAfter.isDirectory() ||
+                directoryAfter.dev !== directoryBefore.dev ||
+                directoryAfter.ino !== directoryBefore.ino ||
+                directoryAfter.birthtimeNs !== directoryBefore.birthtimeNs ||
+                directoryAfter.mtimeNs !== directoryBefore.mtimeNs ||
+                directoryAfter.ctimeNs !== directoryBefore.ctimeNs) {
+                throw new Error("payload directory descriptor mutated during enumeration");
+            }
+            const after = lstatSync(path, { bigint: true });
+            if (!after.isDirectory() ||
+                after.dev !== opened.dev ||
+                after.ino !== opened.ino ||
+                after.ctimeNs !== opened.ctimeNs ||
+                after.birthtimeNs !== opened.birthtimeNs) {
+                throw new Error("payload directory identity changed during enumeration");
+            }
+            return entries;
+        }
+        finally {
+            directory.closeSync();
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readWindowsStableDirectoryOnce(path, expected, directoryReader) {
+    const beforeOpen = pathDirectoryMetadata(path);
+    if (!directoryMetadataMatches(beforeOpen, expected)) {
+        throw new Error("payload directory identity or metadata changed before enumeration");
+    }
+    const directory = opendirSync(path);
+    let entries;
+    try {
+        const afterOpen = pathDirectoryMetadata(path);
+        if (!directoryMetadataMatches(afterOpen, expected)) {
+            throw new Error("payload directory identity or metadata changed while opening enumeration handle");
+        }
+        entries = directoryReader(directory, path);
+    }
+    finally {
+        directory.closeSync();
+    }
+    const afterClose = pathDirectoryMetadata(path);
+    if (!directoryMetadataMatches(afterClose, expected)) {
+        throw new Error("payload directory identity or metadata changed during enumeration");
+    }
+    return entries;
+}
+/**
+ * Node does not expose a Windows `Dir` file descriptor for direct file-id verification. The native
+ * Windows branch therefore brackets two handle-bound enumerations with no-follow path identity and
+ * nanosecond metadata snapshots, then requires both name/kind sets to match exactly.
+ */
+function readWindowsStableDirectory(path, directoryReader) {
+    const expected = pathDirectoryMetadata(path);
+    const first = readWindowsStableDirectoryOnce(path, expected, directoryReader);
+    const second = readWindowsStableDirectoryOnce(path, expected, directoryReader);
+    const firstEntries = exactDirectoryEntries(first);
+    const secondEntries = exactDirectoryEntries(second);
+    if (firstEntries.length !== secondEntries.length ||
+        firstEntries.some((entry, index) => entry !== secondEntries[index])) {
+        throw new Error("payload directory entries changed between stable enumerations");
+    }
+    return first;
+}
+function readStableDirectory(path, directoryReader, directoryCapability) {
+    return directoryCapability === "windows-stable-path"
+        ? readWindowsStableDirectory(path, directoryReader)
+        : readPosixStableDirectory(path, directoryReader);
+}
+/** Enumerate a directory without following links, using APIs available at the Node 20.0 floor. */
+export function walkDirectory(root, directoryReader = readDirectoryFromDescriptor, directoryCapability = nativeDirectoryCapability) {
+    const walked = [];
+    const pending = [{ absolutePath: root, relativePath: "" }];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        for (const entry of readStableDirectory(current.absolutePath, directoryReader, directoryCapability)) {
+            const absolutePath = join(current.absolutePath, entry.name);
+            const relativePath = current.relativePath.length === 0 ? entry.name : `${current.relativePath}/${entry.name}`;
+            const kind = entry.isDirectory() ? "directory" : entry.isFile() ? "file" : "unexpected";
+            walked.push({ absolutePath, relativePath, kind });
+            if (kind === "directory")
+                pending.push({ absolutePath, relativePath });
+        }
+    }
+    return walked;
+}
+/**
+ * Return every non-directory entry for exact payload comparison.
+ *
+ * Regular files are expected. Symlinks, sockets, FIFOs, devices, and other special
+ * entries deliberately remain in the returned path set so callers fail closed.
+ */
+export function listPayloadPaths(root) {
+    return listPayloadEntries(root).map((entry) => entry.relativePath);
+}
+/** Preserve each non-directory entry's no-follow kind for exact installed-payload checks. */
+export function listPayloadEntries(root, directoryReader = readDirectoryFromDescriptor, directoryCapability = nativeDirectoryCapability) {
+    return walkDirectory(root, directoryReader, directoryCapability).flatMap(({ relativePath, kind }) => kind === "directory" ? [] : [{ relativePath, kind }]);
+}
+/** Read one stable regular-file identity without following a leaf symbolic link. */
+export function readRegularFileBuffer(path, fs = NODE_FILE_READ_FS) {
+    const parent = dirname(path);
+    const parentBefore = fs.lstatSync(parent, { bigint: true });
+    if (parentBefore.isSymbolicLink() || !parentBefore.isDirectory()) {
+        throw new Error("payload parent is not a real directory");
+    }
+    const before = fs.lstatSync(path, { bigint: true });
+    if (!before.isFile())
+        throw new Error("payload entry is not a regular file");
+    const fd = fs.openSync(path, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fs.fstatSync(fd, { bigint: true });
+        if (!opened.isFile() ||
+            opened.dev !== before.dev ||
+            opened.ino !== before.ino ||
+            opened.ctimeNs !== before.ctimeNs ||
+            opened.birthtimeNs !== before.birthtimeNs) {
+            throw new Error("payload file identity changed before read");
+        }
+        const parentAfterOpen = fs.lstatSync(parent, { bigint: true });
+        if (parentAfterOpen.isSymbolicLink() ||
+            !parentAfterOpen.isDirectory() ||
+            parentAfterOpen.dev !== parentBefore.dev ||
+            parentAfterOpen.ino !== parentBefore.ino ||
+            parentAfterOpen.ctimeNs !== parentBefore.ctimeNs ||
+            parentAfterOpen.birthtimeNs !== parentBefore.birthtimeNs) {
+            throw new Error("payload parent identity changed before read");
+        }
+        const bytes = fs.readFileSync(fd);
+        const after = fs.lstatSync(path, { bigint: true });
+        if (!after.isFile() ||
+            after.dev !== opened.dev ||
+            after.ino !== opened.ino ||
+            after.ctimeNs !== opened.ctimeNs ||
+            after.birthtimeNs !== opened.birthtimeNs) {
+            throw new Error("payload file identity changed during read");
+        }
+        const parentAfterRead = fs.lstatSync(parent, { bigint: true });
+        if (parentAfterRead.isSymbolicLink() ||
+            !parentAfterRead.isDirectory() ||
+            parentAfterRead.dev !== parentBefore.dev ||
+            parentAfterRead.ino !== parentBefore.ino ||
+            parentAfterRead.ctimeNs !== parentBefore.ctimeNs ||
+            parentAfterRead.birthtimeNs !== parentBefore.birthtimeNs) {
+            throw new Error("payload parent identity changed during read");
+        }
+        return bytes;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}