@youdie006/prodex 0.40.6 → 0.40.9

package/docs/claude.md

@@ -105,9 +105,13 @@ The server currently exposes ledger-first tools:
 
 Write tools are narrow and receipt-gated, and they require a git worktree with a committed HEAD. Claude must first call `repo_write_file_dry_run` with an existing repo-relative text file, replacement content, and the expected git HEAD. The file is not changed; the receipt stores hashes/diff and points at a replacement-text artifact under `.bridge/artifacts/repo-writes/`. To apply it, Claude must call `repo_write_file_apply` with the dry-run receipt id, the same expected HEAD, and the reported preimage hash. If git HEAD, file content, or artifact content changed, apply fails. To stage the result, Claude must call `repo_stage_reviewed_paths` with applied write receipt ids and the same expected HEAD; staging fails if any file changed after apply.
 
-`pro_consult` lets Claude ask your logged-in ChatGPT (Pro) directly: it drives the same explicit visible-browser consult as `prodex pro browser ask` (human-paced, blocker-gated, receipt-recorded, answer saved under `.bridge/artifacts/pro-consults/`) and can take minutes for Pro extended reasoning. It requires a prior `prodex pro browser login` session and is registered only on the local stdio MCP server — the HTTP MCP surface never exposes it, so nothing reachable through a tunnel or ChatGPT itself can drive your browser.
+`pro_consult` lets Claude ask your logged-in ChatGPT (Pro) directly: it drives the same explicit visible-browser consult as `prodex pro browser ask` (human-paced, blocker-gated, receipt-recorded, answer saved under `.bridge/artifacts/pro-consults/`) and can take minutes for Pro extended reasoning. Ordinary calls start fresh. Each stdio MCP connection gets one default `session_key`, and `continue_thread` only resolves that key's latest finished consult in the same project. Logical agents sharing one connection should pass distinct explicit keys and preserve them for follow-ups. An explicit key also keeps continuity across an MCP process restart. It requires a prior `prodex pro browser login` session and is registered only on the local stdio MCP server; the HTTP MCP surface never exposes it, so nothing reachable through a tunnel or ChatGPT itself can drive your browser.
 
-`pro_recover` collects an answer that finished after a consult stopped waiting. A timed-out or still-running consult returns the thread it landed in, and the answer is almost always sitting there; this is also how a deep research report is collected, since a research run keeps going after the consult that started it has returned. It reads a thread and sends nothing, so retrying it is safe. Like `pro_consult`, it is registered only on the local stdio MCP server.
+`pro_recover` reads a finished, rendered answer after a consult stopped waiting. Pass the original `request_id` with its `thread` to verify the answer follows that exact marked user turn. Omitting it supports old records but returns `request_verified: false` and a warning. It sends nothing and refuses wrong-request, wrong-thread, still-generating, or unstable content. Deep-research widget reports remain unsupported, and this tool is also registered only on the local stdio MCP server.
+
+Updating the installed package does not reload an already-running MCP process. Reconnect the MCP server or restart the Codex/Claude agent client to load the new build. The dedicated browser profile remains signed in, so no ChatGPT reauthentication is needed.
+
+Generic bridge result/session/task tools redact ChatGPT thread metadata, including nested blockers; local `pro_consult` recovery information remains available. A legacy result artifact with no saved hash returns `legacy_artifact_unverified` rather than implying its bytes were verified. `sessions cancel` only clears stale bookkeeping after a send was interrupted; it does not stop an active consult.
 
 No shell, public tunnel, direct ungated write, or direct ungated staging tools are exposed through the Claude stdio MCP server; the only browser-facing tools are the explicit `pro_consult` consult and the read-only `pro_recover` described above.
 

package/docs/cli-reference.md

@@ -82,6 +82,7 @@ Use this only when you explicitly want to use your logged-in ChatGPT Pro web ses
 ```bash
 prodex pro browser login --dry-run
 prodex pro browser login
+prodex pro browser login --headed  # force a visible window for interactive reauthentication
 prodex pro browser help
 prodex pro browser check
 prodex pro browser smoke --cwd /absolute/path/to/your/repo
@@ -105,6 +106,7 @@ What happens:
 
 - `login --dry-run` prints the dedicated Chrome profile, debug URL, and next commands without opening a browser.
 - `login` opens that dedicated Chrome profile at ChatGPT. In an interactive terminal it then waits (default 5 minutes; `--no-wait` skips, `--wait-timeout-ms` tunes) and narrates which manual step is still missing until it reports READY; scripts and agents get the immediate return unless they pass `--wait`.
+- `login` reuses the last profile recorded for the resolved debug port when `--profile-dir` is omitted. It does not reuse a saved custom port implicitly: `--port` / `PRODEX_CDP_PORT` / the normal `9333` default still resolve the port exactly as before.
 - You log in manually in the visible browser.
 - If ChatGPT asks for captcha, Cloudflare/human verification, permission, or account verification, handle it in that browser.
 - If ChatGPT shows a usage limit, message limit, model limit, or rate limit, wait for the reset or choose an available model in the browser.
@@ -129,7 +131,11 @@ prodex results artifact latest
 prodex sessions show latest
 ```
 
-This uses the currently available ChatGPT web session and model selection. It is not a hidden API client, and it does not read cookies, tokens, localStorage, or sessionStorage.
+This uses the currently available ChatGPT web session and model selection. Each ordinary ask starts a fresh chat, including inside a configured project. Use `--session-key <id> --continue` for a follow-up scoped to one caller, or `--continue-task <task_id>` to deliberately name a consult across sessions. `PRODEX_SESSION_KEY` and then `CODEX_THREAD_ID` are the CLI fallbacks. It is not a hidden API client, and it does not read cookies, tokens, localStorage, or sessionStorage.
+
+Current builds read rendered page content only. Project/conversation listings are limited to entries exposed by the UI. Automatic chat/project deletion and deep-research report retrieval are unsupported; those commands stop rather than call internal endpoints. Every send carries a visible request marker; success requires the returned assistant turn to follow that marker. Recover a timeout with `--target-url <thread> --request-id <request_id>` so recovery verifies the same turn. Omitting the request ID is legacy, unverified recovery. Formatting may differ from ChatGPT's rendered message.
+
+Locks fail closed if a process is killed while reclaiming an abandoned lock. A leftover `.reap` claim then needs manual cleanup: first stop every prodex process using that resource and confirm no request/write/startup is active; only then remove the affected lock and its matching `.reap` file. Browser locks live beside the recorded send lock, repo-write locks under `.bridge`, and virtual-display allocation locks under `~/.local/share/prodex/xvfb`. Do not remove a live request's lock to shorten a wait.
 
 #### Choosing the model, reasoning effort, and project
 
@@ -174,13 +180,18 @@ Log in once, then never see the browser again:
 ```bash
 prodex pro browser login                    # once, headed - sign in
 prodex pro browser login --virtual-display  # from now on: no window anywhere
+prodex pro browser login --headed            # force a visible window for login/captcha
 ```
 
-`--virtual-display` (or `PRODEX_VIRTUAL_DISPLAY=1`, which also covers the MCP server and its auto-recovery) starts an X virtual framebuffer and runs the dedicated Chrome on it. It is a **real headed browser**, so Cloudflare treats it as an ordinary one — measured end to end: the signed-in profile loaded chatgpt.com with no challenge and a real Pro send returned in 31 seconds, with nothing on the desktop and nothing in the taskbar. Headless, by contrast, never gets past Cloudflare at all (see below).
+Window mode is one mutually exclusive choice: `--headed`, `--headless`, `--minimized`, or `--virtual-display`. Supplying a CLI mode flag selects the whole mode and overrides environment and saved state. With no mode flag, any non-empty `PRODEX_HEADLESS`, `PRODEX_MINIMIZE_WINDOW`, or `PRODEX_VIRTUAL_DISPLAY` value selects the whole environment mode; `0`, `false`, and `no` are meaningful false values, so `PRODEX_HEADLESS=0` explicitly selects ordinary headed mode instead of falling back to a saved headless launch. With neither flags nor mode environment settings, `login` and CLI/MCP auto-recovery reuse the last recorded mode. With no saved record, the normal default is headed.
+
+`--virtual-display` (or `PRODEX_VIRTUAL_DISPLAY=1`, which also covers the MCP server and its auto-recovery) starts an X virtual framebuffer and runs the dedicated Chrome on it. It is a **real headed browser** without a desktop window, not Chrome's headless mode. Login, captcha, rate limits, and permission checks still apply; this mode does not bypass them.
+
+Requires `Xvfb` and `xauth` (`sudo apt install -y xvfb x11-xkb-utils xauth`); prodex names the package if they are missing. Linux and WSL only. New displays use Linux abstract Unix sockets, which also work when WSLg mounts `/tmp/.X11-unix` read-only. TCP and filesystem Unix listeners are disabled. A per-display xauth cookie under `~/.local/share/prodex/xvfb/` restricts access to clients holding that credential; `-ac` is never used. The X server outlives the CLI on purpose (the browser runs on it) and is reused by later commands; `PRODEX_VIRTUAL_DISPLAY_NUM` selects the first number to try if `:99` is taken. A setup failure stops the launch or recovery, without falling back to a desktop window.
 
-Requires `Xvfb` and `xauth` (`sudo apt install -y xvfb x11-xkb-utils xauth`); prodex names the package if they are missing. Linux and WSL only. The display is served over loopback TCP because WSLg mounts `/tmp/.X11-unix` read-only, and it is protected by a per-display xauth cookie under `~/.local/share/prodex/xvfb/` — never `-ac`, so no other process can watch your signed-in window. The X server outlives the CLI on purpose (the browser runs on it) and is reused by later commands; `PRODEX_VIRTUAL_DISPLAY_NUM` picks the display number if `:99` is taken.
+Existing browsers and legacy TCP X servers are not stopped or migrated automatically. Finish pending consults, stop the dedicated browser and its old X server, then run the updated `prodex pro browser login --virtual-display` to migrate. New launches skip display numbers with an existing TCP listener and record the display number actually used.
 
-A browser already running on your desktop cannot be moved onto a virtual display by reusing it, so prodex refuses the switch and tells you to close it first (`pkill -f "remote-debugging-port=9333"`).
+A browser already running on your desktop cannot be moved onto a virtual display by reusing it. prodex refuses the switch without ending the browser; close it yourself, then rerun with the intended mode. Reinvoking `login` for an already-running virtual browser reuses its saved display identity and does not allocate another display.
 
 ### Keeping the window, just out of the way
 
@@ -192,10 +203,10 @@ The catch is what "minimized" means to your desktop. Under WSLg a minimized Chro
 
 `prodex pro browser login --headless` (or `PRODEX_HEADLESS=1`, which also covers the MCP server and its auto-recovery) runs the dedicated browser with no visible window. Two constraints are real, not cosmetic:
 
-- **Sign in headed first.** Nobody can log in to a window that does not exist, so headless reuses a profile you already signed into. The headless login verifies the saved session and tells you to run the headed login once if it is not there.
+- **Sign in headed first.** Nobody can log in to a window that does not exist, so headless reuses a profile you already signed into. If login, captcha, Cloudflare, permission, or account verification is needed, close the hidden browser yourself and run `prodex pro browser login --headed` for a visible interactive window. Do not merely omit `--headless`: saved modes persist.
 - **One mode at a time.** A single Chrome profile cannot serve a headed and a headless instance simultaneously; close the running one before switching (prodex refuses the switch instead of silently reusing the wrong mode).
 
-**Cloudflare is the catch, and it is not theoretical.** Measured on a real signed-in profile: headless Chrome lands on the "Just a moment..." interstitial and stays there past 60 seconds, so ChatGPT never loads. A signed-in profile does not buy a pass — the challenge keys on the headless browser itself. Treat `--headless` as available-but-unproven against ChatGPT: try it, and if `prodex pro browser check` reports the challenge, run headed. Only the window is optional; the login is not.
+**Cloudflare is the catch, and it is not theoretical.** Measured on a real signed-in profile: headless Chrome lands on the "Just a moment..." interstitial and stays there past 60 seconds, so ChatGPT never loads. A signed-in profile does not buy a pass — the challenge keys on the headless browser itself. Treat `--headless` as available-but-unproven against ChatGPT: if `prodex pro browser check` reports the challenge, run `prodex pro browser login --headed` and complete it visibly. prodex does not invoke a hidden API or bypass login/protection. Only the window is optional; the login is not.
 
 If a consult finds the browser closed, prodex now relaunches it in the same mode you last used and retries once — including from the MCP server, which has no terminal to prompt in. `PRODEX_NO_AUTO_LOGIN=1` turns that off.
 
@@ -270,7 +281,7 @@ Token-bearing MCP URLs are secrets. They authorize all enabled bridge tools, inc
 prodex status --show-token --url-only
 ```
 
-`status --show-token` requires a token with an expiry, so run `setup --token-ttl-hours <hours>` before asking for a paste-ready URL. The URL token is stored only in `.bridge/config.local.json`, which is ignored by git. Rotate it with `setup` when you no longer need that URL. If you intentionally created a non-expiring token for local-only debugging, `status --show-token` refuses to reveal it unless you also pass `--unsafe-show-non-expiring-token`. `doctor` and `pro browser check` also print `config_warning` when the saved token is non-expiring.
+`status --show-token` requires a token with an expiry, so run `setup --token-ttl-hours <hours>` before asking for a paste-ready URL. The URL token is stored only in `.bridge/config.local.json`, which is ignored by git. Rotate it with `setup --token-ttl-hours <hours>`, then restart `prodex start` and update client URLs. Plain `setup` preserves the saved token and expiry, and unspecified listener settings are preserved. If you intentionally created a non-expiring token for local-only debugging, `status --show-token` refuses to reveal it unless you also pass `--unsafe-show-non-expiring-token`. `doctor` and `pro browser check` also print `config_warning` when the saved token is non-expiring.
 
 After adding the MCP URL to ChatGPT, generate a paste-ready verification prompt:
 

package/docs/clients.md

@@ -20,6 +20,18 @@ Install the `prodex` binary with `npm install -g @youdie006/prodex` (note the sc
 The same operating rules apply to every client: manual-first, explicit `pro browser ...`
 sends only, stop on blockers, no bypass, low volume, local only (see the README).
 
+Each stdio MCP connection gets one default `session_key`. An ordinary `pro_consult`
+starts a fresh chat; `new_chat: false` does not reuse whichever conversation another
+session left in the shared tab. A `continue_thread: true` call searches only the same
+session key and project. Logical agents sharing one connection should use distinct
+explicit keys and preserve them for follow-ups. An explicit key also keeps continuity
+across an MCP process restart; `continue_task` deliberately names a recorded consult.
+
+After updating the installed package, reconnect the MCP server or restart the agent
+client. A running stdio process keeps the old code until it exits. The dedicated
+browser profile is unchanged, so restarting Codex/Claude does not require signing in
+to ChatGPT again.
+
 ## Claude Code
 
 See [claude.md](claude.md), or:
@@ -48,12 +60,12 @@ consult you expect. Claude Code needs no change: its default stdio tool
 timeout is effectively unlimited (~28h) unless you tightened `MCP_TOOL_TIMEOUT`
 or a per-server `"timeout"`.
 
-A deep research consult (`tools: ["deep-research"]`) is the longest of these:
-the run takes about ten minutes and prodex raises its own budget to 30, so a
-client timeout below that aborts the call while the research keeps going. That
-is recoverable rather than lost - `pro_recover` with the thread from the
-blocker collects the report afterwards - but a client budget that covers the
-run avoids the round trip.
+Keep the client budget longer than the ordinary consult budget. Current
+browser-only builds block `tools: ["deep-research"]` before sending because
+automatic report retrieval depended on an internal API. Run research manually
+in ChatGPT. Recover a timed-out ordinary answer with both the returned `thread` and
+`request_id`; recovery without a request ID is retained for old records but is marked
+unverified.
 
 Approval gate (verified on Codex 0.142.5): Codex asks for per-call approval
 before invoking prodex MCP tools. In interactive `codex` sessions you simply

package/docs/http-mcp.md

@@ -4,6 +4,8 @@ Use this path when you want a ChatGPT Project to hand tasks back to this local r
 
 This is not the ChatGPT Pro browser adapter. It does not open ChatGPT, read cookies, or automate a web session. It starts a local HTTP MCP server that exposes the same bridge/repo tools as the Claude stdio server.
 
+Generic task, session and result responses redact personal ChatGPT thread metadata, including nested blockers and recovery URLs in diagnostic text. Local CLI records retain that context for recovery. Legacy result artifacts without a recorded hash are readable with a `legacy_artifact_unverified` warning; a signed completion receipt does not verify unhashed artifact bytes.
+
 ## What It Is
 
 `prodex start` runs a local Streamable HTTP MCP server.
@@ -63,7 +65,9 @@ Equivalent from outside the repo:
 prodex setup --cwd /absolute/path/to/your/repo --token-ttl-hours 24
 ```
 
-Expired tokens are rejected by `prodex start` and by the HTTP MCP server. Rerun `setup` to rotate the URL.
+Token-bearing MCP URLs are secrets. Keep the renewed URL in your own trusted private MCP client configuration.
+
+Expired tokens are rejected by `prodex start` and by the HTTP MCP server. Run `prodex setup --token-ttl-hours <hours>` to rotate the URL, restart `prodex start`, then reconnect clients using `prodex status --show-token --url-only`. Plain `setup` preserves the existing token and expiry; changing the TTL preserves the listener unless `--host` or `--port` is supplied.
 
 ## Start The Local Server
 

package/docs/releasing.md

@@ -21,7 +21,7 @@ One-time setup (owner, on npmjs.com): open the package → Settings → Trusted
 
 ## Release checks
 
-GitHub Actions runs `npm ci`, `npm run build`, `npm run release:check`, and `npm run release:verify` on pushes to `main` and pull requests. The workflow installs `ripgrep` because the repo-search smoke checks require `rg`. It verifies release readiness only; it does not publish anything.
+GitHub Actions runs `npm ci`, `npm run build`, `npm run release:check -- --metadata-only`, and `npm run release:verify` on pushes to `main` and pull requests. The metadata step checks package readiness; the verification step runs the full test and package checks once. The workflow installs `ripgrep` because the repo-search smoke checks require `rg`. It verifies release readiness only; it does not publish anything.
 
 Before sharing a package tarball, run:
 
@@ -39,6 +39,8 @@ npm run release:verify
 
 This runs tests, typecheck, build, package smoke, and `doctor` without weakening the publish guard.
 
+Package smoke runs tarball publish dry-runs against an isolated, read-only loopback registry. This keeps repeat verification working after the package version has already been published. It does not establish that a version is available on npm; the separate release dry-run and actual publish still enforce registry readiness. No package is uploaded by the smoke check.
+
 If direct `npm pack` is blocked because a WSL/Windows mount reports normal source files as executable, build the publish tarball from a temporary Linux staging directory:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdie006/prodex",
-  "version": "0.40.6",
+  "version": "0.40.9",
   "description": "Local receipt bus for coordinating Codex execution with ChatGPT Pro/Projects consultation.",
   "author": "youdie006",
   "license": "MIT",