@youdie006/prodex 0.40.17 → 0.40.19

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";
@@ -391,9 +392,10 @@ export async function runProCommand(rest, io, runCliFn) {
                     port: opened.port,
                     headless,
                     minimized,
+                    // A blocked background handoff must not make a temporary auth window permanent.
                     ...(alreadyRunning && savedLaunchForPort?.resume_headless === true &&
-                        !Object.values(windowModeOptions.flags).some((value) => typeof value === "boolean") &&
-                        !["PRODEX_HEADLESS", "PRODEX_VIRTUAL_DISPLAY", "PRODEX_MINIMIZE_WINDOW"].some((key) => (process.env[key] ?? "").trim() !== "")
+                        (background || (!Object.values(windowModeOptions.flags).some((value) => typeof value === "boolean") &&
+                            !["PRODEX_HEADLESS", "PRODEX_VIRTUAL_DISPLAY", "PRODEX_MINIMIZE_WINDOW"].some((key) => (process.env[key] ?? "").trim() !== "")))
                         ? { resume_headless: true } : {}),
                     ...(virtualDisplay
                         ? { virtual_display: virtualDisplay.displayNumber }
@@ -1543,7 +1545,7 @@ export async function runAskProCommand(rest, io, beforeSend) {
             }
         }
         catch (error) {
-            const blocker = sourceAwareBrowserBlocker(browserSendBlockerFromError(error), sourceCli, browserCommandOptions);
+            const blocker = await withManualStepForWindowMode(sourceAwareBrowserBlocker(browserSendBlockerFromError(error), sourceCli, browserCommandOptions), resolveCdpPort(browserPort), sourceCli, browserCommandOptions);
             const message = blocker.next_step ? `${blocker.message} Next: ${blocker.next_step}` : errorMessage(error);
             // The blocker text can quote the requested/default project name (e.g. a
             // "project not found" error). Local stdout/stderr keep it (useful to the
@@ -2318,6 +2320,7 @@ async function completeBackgroundBrowserLogin(io, options) {
             port: opened.port,
             timeoutMs: options.timeoutMs,
             windowMode: { headless: true, virtualDisplay: false, minimized: false },
+            verifiedHeadedHandoff: true,
             headedLoginCommand: options.headedLoginCommand,
             headlessRecoveryCommand: options.headlessRecoveryCommand
         });
@@ -2386,6 +2389,12 @@ export async function waitForChatGptLoginReady(stderr, options, deps = {}) {
         const blocker = status.blocker;
         const blockerNextStep = blocker?.next_step ? ` Next: ${blocker.next_step}` : "";
         if (!hasInteractiveWindow && blocker && needsVisibleAuthRecovery(blocker.code)) {
+            if (options.verifiedHeadedHandoff) {
+                stderr(`login: blocked - ${blocker.message}`);
+                stderr(`login: NOT READY - ${blocker.code}. Sign-in was verified before the headless handoff, but the same profile is not ready headlessly.`);
+                stderr("login: Another login is not a demonstrated fix. Stop automatic recovery and inspect this headless failure before another login or mode change. No further window will be opened automatically.");
+                return false;
+            }
             const visibleStep = options.windowMode?.headless === true && options.headlessRecoveryCommand
                 ? `run \`${options.headlessRecoveryCommand}\` to handle it visibly.`
                 : `${manualInspection} Handle the reported step visibly.`;
@@ -3039,6 +3048,60 @@ export async function listConsultListEntries(store, options = { readOnly: true }
     }
     return entries;
 }
+/** Blockers whose only remedy is a person acting inside the browser window. */
+const MANUAL_BROWSER_STEP_CODES = new Set(["login_required", "captcha_required", "cloudflare_check"]);
+/**
+ * Rewrite a "do it in the visible browser" next step for a browser that has no
+ * window to do it in.
+ *
+ * Measured with a signed-out profile on a virtual display: `pro browser check`
+ * and every send reported `login_required` with "Log in manually in the
+ * visible browser." - on a browser prodex had itself started with no visible
+ * window. The login command already knew the way out (close that browser, log
+ * in through a headed one), but the blocker a send or a check prints did not.
+ * A session that expires under a no-window setup is exactly this case, and the
+ * advice it got could not be followed.
+ *
+ * Only the manual-step codes are rewritten, and only when the saved launch
+ * belongs to the port in use, so a stale record for another browser cannot
+ * change the advice for this one.
+ */
+export function manualBrowserStepForWindowMode(blocker, launch, port, commands) {
+    if (!MANUAL_BROWSER_STEP_CODES.has(blocker.code))
+        return blocker;
+    if (!launch || launch.port !== port)
+        return blocker;
+    if (launch.headless === true) {
+        return {
+            ...blocker,
+            next_step: `The dedicated browser runs headless, with no window to do this in. Run \`${commands.visibleRecovery}\` ` +
+                "to switch it to a visible window through the guarded path, complete the step there, then retry."
+        };
+    }
+    if (launch.virtual_display !== undefined) {
+        return {
+            ...blocker,
+            next_step: "The dedicated browser runs on a virtual display, with no window to do this in. Close it yourself when no " +
+                `consult is running, then run \`${commands.headedLogin}\` to complete the step in a visible window, and retry.`
+        };
+    }
+    return blocker;
+}
+/** The same rewrite, with the saved launch record and the commands resolved for this call. */
+async function withManualStepForWindowMode(blocker, port, sourceCli, commandOptions) {
+    if (!MANUAL_BROWSER_STEP_CODES.has(blocker.code))
+        return blocker;
+    const launch = await readLastBrowserLoginLaunch().catch(() => undefined);
+    const options = {
+        ...commandOptions,
+        port,
+        ...(launch?.profile_dir ? { profileDir: launch.profile_dir } : {})
+    };
+    return manualBrowserStepForWindowMode(blocker, launch, port, {
+        headedLogin: formatHeadedBrowserLoginCommand(sourceCli, options),
+        visibleRecovery: formatVisibleAuthRecoveryCommand(sourceCli, options)
+    });
+}
 function formatHeadedBrowserLoginCommand(sourceCli, options = {}) {
     return `${formatBrowserLoginCommand(sourceCli, options)} --headed`;
 }
@@ -3099,6 +3162,9 @@ export function printBrowserLoginGuide(stdout, input) {
         return;
     }
     stdout("");
+    stdout("Chrome account connection is separate from ChatGPT sign-in. If Chrome asks, choose whether to connect the browser account yourself.");
+    stdout("'Use Chrome without an account' declines that browser connection, not your ChatGPT login. Keep the ChatGPT tab open after making that choice.");
+    stdout("");
     stdout("Steps:");
     if (windowAvailable) {
         stdout(input.reusedProfile || input.reused === true
@@ -3225,10 +3291,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)
@@ -3246,7 +3326,12 @@ export async function printProductCheck(store, io, args, configCwd = io.cwd) {
         else if (browserStatus.blocker) {
             const visibilityText = browserStatus.blocker.code === "tab_not_visible" ? ` visibility=${browserStatus.visibilityState ?? "unknown"}` : "";
             io.stdout(`chatgpt: blocked ${browserStatus.blocker.code}${visibilityText} - ${browserStatus.blocker.message}`);
-            const nextStep = productCheckBrowserNextStep(browserStatus.blocker.next_step, sourceCli, browserCommandOptions);
+            const modeAware = await withManualStepForWindowMode(browserStatus.blocker, checkPort, sourceCli, browserCommandOptions);
+            // A rewritten step already carries fully formed commands; running it back
+            // through the product-check rewrite would only re-derive them.
+            const nextStep = modeAware === browserStatus.blocker
+                ? productCheckBrowserNextStep(browserStatus.blocker.next_step, sourceCli, browserCommandOptions)
+                : modeAware.next_step;
             if (nextStep)
                 io.stdout(`next: ${nextStep}`);
         }

package/dist/cli-shared.js

@@ -88,10 +88,10 @@ export function sourceAwareBrowserNextStep(nextStep, sourceCli, options = {}) {
         return `\`cd ${cwdPrefix} && ${formatBrowserAskCommandBody(sourceCli)}${storedArgs ?? ""}\``;
     })
         .replace(/`prodex pro browser login([^`]*)?`/g, (_match, storedArgs) => {
-        return `\`${formatBrowserLoginCommand(sourceCli, browserOptionsWithStoredPort(options, storedArgs))}\``;
+        return `\`${formatBrowserLoginCommand(sourceCli, browserOptionsWithStoredPort(options, storedArgs))}${flagsBesidesPort(storedArgs)}\``;
     })
         .replace(/`prodex pro browser smoke([^`]*)?`/g, (_match, storedArgs) => {
-        return `\`${formatBrowserSmokeCommand(sourceCli, browserOptionsWithStoredPort(options, storedArgs))}\``;
+        return `\`${formatBrowserSmokeCommand(sourceCli, browserOptionsWithStoredPort(options, storedArgs))}${flagsBesidesPort(storedArgs)}\``;
     })
         .replace(/`prodex pro browser ask([^`]*)?`/g, (_match, storedArgs) => {
         return `\`${formatBrowserAskCommandBody(sourceCli)}${storedArgs ?? ""}\``;
@@ -131,6 +131,19 @@ export function isUntrustedResultError(error) {
 export function formatCommandInCwd(command, cwd) {
     return cwd ? `cd ${shellQuote(cwd)} && ${command}` : command;
 }
+/**
+ * The flags of a quoted command other than --port, which the rewrite rebuilds
+ * itself. They used to be dropped: a next step saying "run `prodex pro browser
+ * login --background`" came out as a plain `login`, and "--headed" vanished from
+ * the step that exists to get a window - so following the advice relaunched the
+ * browser in the very mode it was telling the caller to leave.
+ */
+export function flagsBesidesPort(storedArgs) {
+    if (!storedArgs)
+        return "";
+    const rest = storedArgs.replace(/(?:^|\s)--port\s+\d{1,5}(?=\s|$)/, " ").replace(/\s+/g, " ").trim();
+    return rest ? ` ${rest}` : "";
+}
 export function browserOptionsWithStoredPort(options, storedArgs) {
     if (options.port || !storedArgs)
         return options;

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: