@youdie006/prodex 0.40.16 → 0.40.18

package/dist/cli-pro.js

@@ -1,6 +1,7 @@
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { BrowserProcessInspectionError } from "./browser-process.js";
 import { buildDryRunBundle } from "./bundle.js";
 import { ChatGptBrowserBlockerError, DEFAULT_CDP_PORT, resolveCdpPort, resolveConversationToDelete, resolveProjectToDelete, chatGptVisibilityBlocker, defaultChatGptProfileDir, formatDurationMs, getChatGptBrowserStatus, formatModelMenuOption, listChatGptModelOptions, deleteChatGptConversation, endWedgedBrowser, browserRecoveryPlan, findWedgedBrowser, wedgedBrowserBlocker, deleteChatGptProject, listChatGptProjectsWithIds, listRecentChatGptConversations, listChatGptSidebarProjects, normalizeChatGptTargetUrl, openChatGptBrowser, openChatGptTab, parseProMode, parseReasoningEffort, defaultTimeoutForTools, ensureVirtualDisplay, minimizeChatGptWindow, readLastBrowserLoginLaunch, resolveBrowserWindowMode, recordBrowserLoginLaunch, recoverChatGptAnswerFromThread, sendChatGptPrompt, statusMeansBrowserDead, namesPro, sendWarningsFromError, destinationVerification, chatGptProjectIdFromUrl } from "./chatgpt-browser.js";
 import { ASK_PRO_BOOLEAN_FLAGS, ASK_PRO_PREVIEW_VALUE_FLAGS, ASK_PRO_VALUE_FLAGS, assertHelpRequestArgs, assertNoExtraArgs, assertOnlyOptions, findHelpFlagIndexBeforePromptDelimiter, formatCliCommand, hasAskProDryRunMode, hasAskProMode, hasAskProSendMode, isHelpSubcommand, parseAskProArgs, printHelpIfRequested, readFlag, readPortFlag, readPositionalsWithOptions, readNonNegativeIntegerFlag, readPositiveIntegerFlag, readRepeatedFlag, resolveCwdFlag, resolveOptionalFileFlag, unknownSubcommandError } from "./cli-args.js";
@@ -3075,6 +3076,21 @@ export function printBrowserLoginGuide(stdout, input) {
                 : input.opened
                     ? "Opened the dedicated Chrome window for ChatGPT."
                     : "Dry run: no browser was opened.");
+    if (noInteractiveWindow && !input.opened && !input.reused) {
+        const previewCommand = formatBrowserLoginCommand(input.sourceCli, {
+            ...input.commandOptions,
+            profileDir: input.profileDir,
+            port: input.port
+        });
+        const modeFlag = input.headless ? "--headless" : "--virtual-display";
+        stdout("");
+        stdout(`Next: run \`${previewCommand} ${modeFlag}\` without \`--dry-run\` to start or reuse Chrome with no visible window.`);
+        stdout("Readiness was not checked. A real launch reuses this profile and reports any login or protection blocker; it does not switch to a visible window automatically.");
+        stdout("");
+        stdout(`Profile: ${input.profileDir}`);
+        stdout(`Debug: http://127.0.0.1:${input.port}`);
+        return;
+    }
     if (noInteractiveWindow && (input.opened || input.reused)) {
         stdout("");
         stdout(input.headless
@@ -3210,10 +3226,24 @@ export async function printProductCheck(store, io, args, configCwd = io.cwd) {
             // report both as "not running": the browser really is gone, or it is still
             // there and has stopped answering. The second keeps burning CPU until
             // somebody notices, and nobody notices a message that says it is absent.
-            const wedged = statusMeansBrowserDead(browserStatus)
-                ? findWedgedBrowser({ ...(browserCommandOptions.port !== undefined ? { port: browserCommandOptions.port } : {}) })
-                : [];
-            const blocker = wedged.length > 0 ? wedgedBrowserBlocker(wedged, browserCommandOptions.port ?? DEFAULT_CDP_PORT) : browserStatus.blocker;
+            let blocker = browserStatus.blocker;
+            if (statusMeansBrowserDead(browserStatus)) {
+                try {
+                    const wedged = findWedgedBrowser({ ...(browserCommandOptions.port !== undefined ? { port: browserCommandOptions.port } : {}) });
+                    if (wedged.length > 0)
+                        blocker = wedgedBrowserBlocker(wedged, browserCommandOptions.port ?? DEFAULT_CDP_PORT);
+                }
+                catch (error) {
+                    if (!(error instanceof BrowserProcessInspectionError))
+                        throw error;
+                    blocker = {
+                        code: "browser_process_unverified",
+                        message: "The operating system could not verify browser process identity.",
+                        retryable: false,
+                        next_step: `Leave the existing browser unchanged. Check OS process-inspection permissions, then run \`${formatBrowserCheckCommand(sourceCli, browserCommandOptions)}\`.`
+                    };
+                }
+            }
             io.stdout(`chatgpt: ${blocker?.code ?? "unreachable"} - ${blocker?.message ?? "browser is not reachable"}`);
             const nextStep = productCheckBrowserNextStep(blocker?.next_step, sourceCli, browserCommandOptions);
             if (nextStep)

package/dist/cli.js

@@ -14,6 +14,7 @@ import { getTokenExpiryStatus, loadLocalConfig, resolveProdexCwd } from "./confi
 import { startHttpMcpServer } from "./http-mcp.js";
 import { createMcpToolHandlers } from "./mcp-tools.js";
 import { runMcpServer } from "./mcp.js";
+import { execNpm } from "../scripts/npm-command.mjs";
 import { BridgeStore } from "./store.js";
 import { printHelpIfRequested, assertNoExtraArgs, assertOnlyOptions, formatCliCommand, formatSourceCliOption, isHelpSubcommand, readFlag, resolveCwdFlag, resolveExistingPathFlag, resolveOptionalFileFlag, shellQuote, unknownSubcommandError, unknownTopLevelCommandError } from "./cli-args.js";
 import { listRawResultsForInspection, listTasksForInspection, runReceiptsCommand, runResultsCommand, runSessionsCommand, runTasksCommand } from "./cli-ledger.js";
@@ -711,7 +712,7 @@ async function readReleasePackageJson(packageJsonPath) {
 }
 async function readReleasePackStatus(cwd, packageJson, sourceCli, releaseHintCwd) {
     try {
-        const { stdout } = await execFileAsync(commandForPlatform("npm"), ["pack", "--json", "--dry-run", "--ignore-scripts"], {
+        const { stdout } = await execNpm(["pack", "--json", "--dry-run", "--ignore-scripts"], {
             cwd,
             timeout: 120_000,
             maxBuffer: 20 * 1024 * 1024
@@ -872,9 +873,6 @@ function writeCommandOutput(output, write) {
     for (const line of trimmed.split(/\r?\n/))
         write(line);
 }
-function commandForPlatform(command) {
-    return process.platform === "win32" && command === "npm" ? "npm.cmd" : command;
-}
 function firstErrorLine(error) {
     const failed = typeof error === "object" && error !== null ? error : {};
     const stderr = firstOutputLine(failed.stderr);

package/dist/config.js

@@ -5,6 +5,7 @@ import { isIP } from "node:net";
 import path from "node:path";
 import { z } from "zod";
 import { SCHEMA_VERSION } from "./schema.js";
+import { ensureBridgeGitignore } from "./bridge-gitignore.js";
 import { readVerifiedUtf8File, writeVerifiedUtf8File } from "./safe-file.js";
 const BRIDGE_DIRECTORY_MODE = 0o700;
 const BrowserDefaultsSchema = z.object({
@@ -329,30 +330,7 @@ async function ensureBridgeLocalFiles(cwd) {
     const bridgeDir = path.join(cwd, ".bridge");
     await ensurePrivateBridgeDirectory(cwd);
     const ignorePath = path.join(bridgeDir, ".gitignore");
-    let current = "";
-    try {
-        current = await readVerifiedUtf8File(ignorePath, () => assertBridgeGitignoreTargetSafe(cwd));
-    }
-    catch (error) {
-        if (!isMissingFileError(error))
-            throw error;
-    }
-    const required = [
-        "tasks/*.json",
-        "results/*.json",
-        "sessions/*.json",
-        "receipts/*.json",
-        "artifacts/*",
-        "config.local.json",
-        "receipt-key.local",
-        "!.gitignore"
-    ];
-    const lines = new Set(current.split(/\r?\n/).filter(Boolean));
-    for (const line of required)
-        lines.add(line);
-    await writeVerifiedUtf8File(ignorePath, `${Array.from(lines).join("\n")}\n`, () => assertBridgeGitignoreTargetSafe(cwd), {
-        create: true
-    });
+    await ensureBridgeGitignore(ignorePath, () => assertBridgeGitignoreTargetSafe(cwd));
 }
 async function ensurePrivateBridgeDirectory(cwd) {
     await mkdir(path.join(cwd, ".bridge"), { recursive: true, mode: BRIDGE_DIRECTORY_MODE });
@@ -362,7 +340,9 @@ async function chmodPrivateBridgeDirectory(cwd) {
     const bridgeDir = path.join(cwd, ".bridge");
     const handle = await openNoFollowDirectory(bridgeDir, ".bridge");
     try {
-        await handle.chmod(BRIDGE_DIRECTORY_MODE);
+        // Windows uses inherited ACLs; POSIX modes do not restrict Windows access.
+        if (process.platform !== "win32")
+            await handle.chmod(BRIDGE_DIRECTORY_MODE);
         await assertDirectoryHandle(handle, ".bridge");
     }
     finally {
@@ -421,9 +401,17 @@ async function openNoFollowDirectory(dirPath, label) {
     const noFollowFlag = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
     const directoryFlag = typeof constants.O_DIRECTORY === "number" ? constants.O_DIRECTORY : 0;
     try {
+        const before = await lstat(dirPath, { bigint: true });
+        if (before.isSymbolicLink() || !before.isDirectory()) {
+            throw new Error(`${label} must be a real directory and must not be a symlink`);
+        }
         const handle = await open(dirPath, constants.O_RDONLY | directoryFlag | noFollowFlag);
         try {
             await assertDirectoryHandle(handle, label);
+            const opened = await handle.stat({ bigint: true });
+            if (opened.dev !== before.dev || opened.ino !== before.ino) {
+                throw new Error(`${label} changed while opening the directory`);
+            }
             return handle;
         }
         catch (error) {

package/dist/repo.js

@@ -10,6 +10,7 @@ const execFileAsync = promisify(execFile);
 export function findRipgrep(env = process.env, exists = existsSync) {
     const pathDirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
     const home = env.HOME ?? env.USERPROFILE ?? "";
+    const executable = process.platform === "win32" ? "rg.exe" : "rg";
     const fallbackDirs = [
         "/usr/bin",
         "/usr/local/bin",
@@ -20,7 +21,7 @@ export function findRipgrep(env = process.env, exists = existsSync) {
         ...(home ? [path.join(home, ".cargo", "bin"), path.join(home, ".local", "bin")] : [])
     ];
     for (const dir of [...pathDirs, ...fallbackDirs]) {
-        const candidate = path.join(dir, "rg");
+        const candidate = path.join(dir, executable);
         try {
             if (exists(candidate))
                 return candidate;
@@ -47,6 +48,9 @@ export function assertRepoRelativePath(repoPath) {
     if (path.isAbsolute(repoPath)) {
         throw new Error("Path must be repo-relative, not absolute");
     }
+    if (process.platform === "win32" && repoPath.includes(":")) {
+        throw new Error("Path must not use a Windows alternate data stream");
+    }
     const normalized = path.posix.normalize(repoPath.replaceAll("\\", "/"));
     if (normalized === "." || normalized.startsWith("../") || normalized === "..") {
         throw new Error("Path must stay inside the repo-relative root");
@@ -191,11 +195,14 @@ function parseRipgrepJsonMatch(line) {
     if (!isRipgrepJsonMatch(event))
         return undefined;
     return {
-        path: event.data.path.text.replace(/^\.\//, ""),
+        path: normalizeRipgrepMatchPath(event.data.path.text),
         line: event.data.line_number,
         text: stripOneTrailingLineEnding(event.data.lines.text)
     };
 }
+function normalizeRipgrepMatchPath(matchPath) {
+    return matchPath.split(path.sep).join("/").replace(/^\.\//, "");
+}
 function isRipgrepJsonMatch(value) {
     if (!isRecord(value) || value.type !== "match" || !isRecord(value.data))
         return false;

package/dist/safe-file.js

@@ -74,6 +74,7 @@ export async function readVerifiedUtf8File(filePath, validate, options = {}) {
         const content = await readHandleUtf8(handle, filePath, options.maxBytes);
         if (options.mode !== undefined) {
             await testHooks.beforeChmod?.(filePath, "read");
+            await assertSafeOpenFile(handle, filePath, "read");
             await handle.chmod(options.mode);
         }
         await validate();
@@ -108,6 +109,7 @@ export async function writeVerifiedUtf8File(filePath, content, validate, options
         await testHooks.afterWrite?.(filePath, "write");
         if (options.mode !== undefined) {
             await testHooks.beforeChmod?.(filePath, "write");
+            await assertSafeOpenFile(handle, filePath, "write");
             await handle.chmod(options.mode);
         }
         await validate();
@@ -131,16 +133,17 @@ export async function replaceVerifiedUtf8File(filePath, content, validate, verif
         const latestContent = await readHandleUtf8(handle, filePath, options.maxBytes);
         await verifyCurrentContent(latestContent);
         await testHooks.beforeWrite?.(filePath, "write");
-        await replaceByVerifiedTempFile(filePath, content, validate, options, {
-            beforeOpenAlreadyRan: true,
-            beforeWriteAlreadyRan: true,
-            parentSnapshot,
-            skipExistingTargetCheck: true
-        });
     }
     finally {
         await handle.close();
     }
+    // Windows cannot replace some files while their verification handle is open.
+    await replaceByVerifiedTempFile(filePath, content, validate, options, {
+        beforeOpenAlreadyRan: true,
+        beforeWriteAlreadyRan: true,
+        parentSnapshot,
+        skipExistingTargetCheck: true
+    });
 }
 async function replaceByVerifiedTempFile(filePath, content, validate, options = {}, hookState = {}) {
     await validate();
@@ -159,6 +162,7 @@ async function replaceByVerifiedTempFile(filePath, content, validate, options =
             await writeHandleUtf8(tmpHandle, tmpPath, content);
             if (options.mode !== undefined) {
                 await testHooks.beforeChmod?.(filePath, "write");
+                await assertSafeOpenFile(tmpHandle, tmpPath, "write");
                 await tmpHandle.chmod(options.mode);
             }
         }
@@ -182,6 +186,7 @@ async function replaceByVerifiedTempFile(filePath, content, validate, options =
     }
 }
 async function readHandleUtf8(handle, filePath, maxBytes) {
+    await assertOpenFileMatchesPath(handle, filePath, "read");
     const stat = await handle.stat();
     if (!stat.isFile()) {
         throw new Error("Target path is not a regular file");
@@ -205,7 +210,7 @@ async function readHandleUtf8(handle, filePath, maxBytes) {
 }
 async function writeHandleUtf8(handle, filePath, content) {
     const replacement = Buffer.from(content, "utf8");
-    await assertSafeOpenFile(handle, filePath);
+    await assertSafeOpenFile(handle, filePath, "write");
     await handle.truncate(0);
     let offset = 0;
     while (offset < replacement.length) {
@@ -216,11 +221,36 @@ async function writeHandleUtf8(handle, filePath, content) {
         offset += bytesWritten;
     }
 }
-async function assertSafeOpenFile(handle, filePath) {
-    const stat = await handle.stat();
-    if (!stat.isFile()) {
+async function assertOpenFileMatchesPath(handle, filePath, operation) {
+    const handleStat = await handle.stat({ bigint: true });
+    if (!handleStat.isFile()) {
+        throw new Error("Target path is not a regular file");
+    }
+    let pathStat;
+    try {
+        pathStat = await lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            throw new Error(`Target path changed during ${operation} file operation`);
+        }
+        throw error;
+    }
+    if (pathStat.isSymbolicLink()) {
+        throw new Error(`Target path is a symlink or changed during ${operation} file operation`);
+    }
+    if (!pathStat.isFile()) {
         throw new Error("Target path is not a regular file");
     }
+    const handleIdentity = { dev: BigInt(handleStat.dev), ino: BigInt(handleStat.ino) };
+    const pathIdentity = { dev: BigInt(pathStat.dev), ino: BigInt(pathStat.ino) };
+    if (!sameFileIdentity(handleIdentity, pathIdentity)) {
+        throw new Error(`Target path changed during ${operation} file operation`);
+    }
+}
+async function assertSafeOpenFile(handle, filePath, operation) {
+    await assertOpenFileMatchesPath(handle, filePath, operation);
+    const stat = await handle.stat();
     assertNotHardLinked(filePath, stat.nlink);
 }
 function assertNotHardLinked(filePath, linkCount) {
@@ -271,8 +301,10 @@ async function captureParentSnapshot(filePath) {
     };
 }
 async function openStableNoFollow(filePath, flags, operation, parentSnapshot, mode) {
-    if (!parentSnapshot)
-        return openNoFollow(filePath, flags, operation, mode);
+    if (!parentSnapshot) {
+        const handle = await openNoFollow(filePath, flags, operation, mode);
+        return verifyOpenedHandle(handle, filePath, operation);
+    }
     if (process.platform !== "linux") {
         const actualParentBeforeOpen = await realpath(parentSnapshot.path);
         if (actualParentBeforeOpen !== parentSnapshot.realPath) {
@@ -284,6 +316,7 @@ async function openStableNoFollow(filePath, flags, operation, parentSnapshot, mo
             if (actualParentAfterOpen !== parentSnapshot.realPath) {
                 throw new Error(`Parent directory changed during ${operation} file operation`);
             }
+            await assertOpenFileMatchesPath(handle, filePath, operation);
             return handle;
         }
         catch (error) {
@@ -298,12 +331,23 @@ async function openStableNoFollow(filePath, flags, operation, parentSnapshot, mo
         if (actualParent !== parentSnapshot.realPath) {
             throw new Error(`Parent directory changed during ${operation} file operation`);
         }
-        return await openNoFollow(path.join(parentFdPath, path.basename(filePath)), flags, operation, mode);
+        const handle = await openNoFollow(path.join(parentFdPath, path.basename(filePath)), flags, operation, mode);
+        return await verifyOpenedHandle(handle, filePath, operation);
     }
     finally {
         await parentHandle.close();
     }
 }
+async function verifyOpenedHandle(handle, filePath, operation) {
+    try {
+        await assertOpenFileMatchesPath(handle, filePath, operation);
+        return handle;
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
 async function openNoFollowDirectory(dirPath, operation) {
     const noFollowFlag = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
     const directoryFlag = typeof constants.O_DIRECTORY === "number" ? constants.O_DIRECTORY : 0;

package/dist/store-writer.js

@@ -16,7 +16,7 @@
 //
 // Everything after the anchoring uses the same helpers the in-process path uses,
 // on relative names.
-import { closeSync, constants, fstatSync, openSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { link, lstat, readdir, rename, rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -34,7 +34,22 @@ function sameIdentity(a, b) {
 function openDirectoryHere(name) {
     const directoryFlag = typeof constants.O_DIRECTORY === "number" ? constants.O_DIRECTORY : 0;
     const noFollowFlag = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
-    return openSync(name, constants.O_RDONLY | directoryFlag | noFollowFlag);
+    const before = lstatSync(name, { bigint: true });
+    if (before.isSymbolicLink() || !before.isDirectory()) {
+        throw new Error("Anchored writer expected a real directory, not a symlink");
+    }
+    const fd = openSync(name, constants.O_RDONLY | directoryFlag | noFollowFlag);
+    try {
+        const opened = fstatSync(fd, { bigint: true });
+        if (opened.dev !== before.dev || opened.ino !== before.ino || !opened.isDirectory()) {
+            throw new Error("Anchored writer directory changed while opening");
+        }
+        return fd;
+    }
+    catch (error) {
+        closeSync(fd);
+        throw error;
+    }
 }
 function currentDirectoryIdentity() {
     const fd = openDirectoryHere(".");
@@ -55,10 +70,10 @@ export function anchorCurrentDirectory(anchor, segments) {
         throw new Error("Anchored writer was not started in the directory the caller validated");
     }
     for (const segment of segments) {
-        if (segment.length === 0 || segment === "." || segment === ".." || segment.includes("/")) {
+        if (segment.length === 0 || segment === "." || segment === ".." || /[\\/]/.test(segment) || (process.platform === "win32" && segment.includes(":"))) {
             throw new Error(`Anchored writer refuses to descend into ${JSON.stringify(segment)}`);
         }
-        // O_NOFOLLOW proves the name is a real directory rather than a symlink, and
+        // The no-follow/identity checks reject symlinks and Windows junctions, and
         // the identity check after chdir proves we landed on that same directory
         // and not on something swapped in between the two calls.
         const fd = openDirectoryHere(segment);
@@ -100,7 +115,7 @@ export async function runAnchoredJob(job) {
         }
     };
     const { fileName } = job;
-    if (fileName.length === 0 || fileName.includes("/") || fileName === "." || fileName === "..") {
+    if (fileName.length === 0 || /[\\/]/.test(fileName) || (process.platform === "win32" && fileName.includes(":")) || fileName === "." || fileName === "..") {
         throw new Error(`Anchored writer refuses the file name ${JSON.stringify(fileName)}`);
     }
     if (job.op === "deleteIfPresent") {

package/dist/store.js

@@ -1,6 +1,7 @@
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { createRequire } from "node:module";
 import { registerBridgeRoot } from "./registry.js";
+import { ensureBridgeGitignore } from "./bridge-gitignore.js";
 import { closeSync, constants, existsSync, openSync, readdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { link, lstat, mkdir, open, readdir, realpath, rename, rm, stat } from "node:fs/promises";
@@ -841,31 +842,7 @@ export class BridgeStore {
     }
     async ensureBridgeGitignore() {
         const ignorePath = path.join(this.bridgeDir, ".gitignore");
-        let current = "";
-        try {
-            current = await readVerifiedUtf8File(ignorePath, () => this.assertBridgeGitignoreTargetSafe());
-        }
-        catch (error) {
-            if (!isErrorCode(error, "ENOENT"))
-                throw error;
-        }
-        const required = [
-            "tasks/*.json",
-            "results/*.json",
-            "sessions/*.json",
-            "receipts/*.json",
-            "artifacts/*",
-            "config.local.json",
-            "receipt-key.local",
-            "last-browser-send",
-            "!.gitignore"
-        ];
-        const lines = new Set(current.split(/\r?\n/).filter(Boolean));
-        for (const line of required)
-            lines.add(line);
-        await writeVerifiedUtf8File(ignorePath, `${Array.from(lines).join("\n")}\n`, () => this.assertBridgeGitignoreTargetSafe(), {
-            create: true
-        });
+        await ensureBridgeGitignore(ignorePath, () => this.assertBridgeGitignoreTargetSafe());
     }
     async hasReadyBridgeStorageReadOnly() {
         try {
@@ -1025,6 +1002,12 @@ export class BridgeStore {
             throw new Error(`Bridge record path must stay under .bridge/${kind}`);
         }
         await this.assertStorageDirIsRealDirectory(kind);
+        if (job.op === "cleanupTempHardLinks") {
+            await storeTestHooks.beforeRecordTempCleanup?.(kind, filePath);
+        }
+        else if (job.op === "writeByRename" || job.op === "linkIfAbsent") {
+            await storeTestHooks.beforeRecordRename?.(kind, filePath);
+        }
         const outcome = await runAnchoredWrite(this.bridgeDir, [kind], {
             ...job,
             fileName: path.basename(filePath),
@@ -1549,9 +1532,17 @@ async function openNoFollowDirectory(dirPath, label) {
     const noFollowFlag = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
     const directoryFlag = typeof constants.O_DIRECTORY === "number" ? constants.O_DIRECTORY : 0;
     try {
+        const before = await lstat(dirPath, { bigint: true });
+        if (before.isSymbolicLink() || !before.isDirectory()) {
+            throw new Error(`${label} must be a real directory and must not be a symlink`);
+        }
         const handle = await open(dirPath, constants.O_RDONLY | directoryFlag | noFollowFlag);
         try {
             await assertOpenDirectoryHandle(handle);
+            const opened = await handle.stat({ bigint: true });
+            if (opened.dev !== before.dev || opened.ino !== before.ino) {
+                throw new Error(`${label} changed while opening the directory`);
+            }
             return handle;
         }
         catch (error) {
@@ -1574,7 +1565,9 @@ async function ensurePrivateDirectory(dirPath, label) {
 async function chmodPrivateDirectory(dirPath, label) {
     const handle = await openNoFollowDirectory(dirPath, label);
     try {
-        await handle.chmod(BRIDGE_DIRECTORY_MODE);
+        // Windows uses inherited ACLs; fchmod on a read-only directory is EPERM.
+        if (process.platform !== "win32")
+            await handle.chmod(BRIDGE_DIRECTORY_MODE);
         await assertOpenDirectoryHandle(handle);
     }
     finally {

package/dist/tui-run.js

@@ -382,5 +382,5 @@ function cancel(io) {
 }
 /** Quote only what a shell would need quoted, so the echo can be pasted. */
 export function formatCommand(args) {
-    return args.map(shellQuote).join(" ");
+    return args.map((arg) => shellQuote(arg)).join(" ");
 }

package/docs/cli-reference.md

@@ -33,7 +33,9 @@ Not implemented:
 
 This section connects coding agents (Claude, Codex, ChatGPT Projects) to the bridge over MCP. It is not required for the standalone terminal flow above — if you only want Pro answers in your terminal, the [Quickstart](#quickstart-a-pro-second-opinion-from-your-terminal) is complete on its own.
 
-Requires Node.js 20 or newer, `git`, and `ripgrep` (`rg`) on PATH. The optional visible-browser adapter needs a Chromium-family browser: PATH binaries (`google-chrome`, `chromium`, `chromium-browser`, `microsoft-edge`, `brave-browser`), standard macOS app bundles, Windows Program Files/LOCALAPPDATA installs, and Windows-host browsers under WSL are all probed automatically; anything else via `PRODEX_CHROME=/path/to/browser`.
+Requires Node.js 20 or newer, `git`, and `ripgrep` (`rg`) on PATH. The optional browser adapter probes PATH binaries (`google-chrome`, `chromium`, `chromium-browser`, `microsoft-edge`, `brave-browser`), native macOS app bundles, and native Windows Program Files/LOCALAPPDATA installs. Set `PRODEX_CHROME` for another executable. WSL uses Linux browser paths, not automatic Windows-host browser discovery. Do not share one profile between native Windows Chrome and Linux Chrome. See [platform verification](platform-verification.md) and [local storage permissions](../SECURITY.md#local-storage-permissions).
+
+Native Windows command examples use PowerShell quoting, including doubled apostrophes inside single-quoted arguments. Use PowerShell 7 for compound examples containing `&&`; these examples are not `cmd.exe` commands. Internal CLI/MCP child processes receive literal argument arrays without a shell.
 
 Install from npm — **note the scope**. The unscoped `prodex` on npm is an unrelated third-party package; do **not** install it. Use the scoped name: