lxreview 0.1.0__tar.gz

lxreview-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

lxreview-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: quality
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+        python: ['3.12', '3.13', '3.14']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+        with:
+          version: '0.12.19'
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src
+      - run: uv run pytest
+      - run: uv build
+      - name: Wheel installs as a uv tool
+        run: |
+          export UV_TOOL_DIR=/tmp/lxreview-tools UV_TOOL_BIN_DIR=/tmp/lxreview-tools/bin
+          uv tool install --python '${{ matrix.python }}' dist/*.whl
+          /tmp/lxreview-tools/bin/lxreview version
+          /tmp/lxreview-tools/bin/lxreview --help
+  browser:
+    # Drives the real Playwright session against a local page that mirrors ChatGPT's markup.
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+        with:
+          version: '0.12.19'
+          python-version: '3.13'
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run playwright install --with-deps chromium
+      - run: uv run pytest -m browser
+        env:
+          LXREVIEW_BROWSER_TESTS: '1'

lxreview-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: publish
+# Publishes a release to PyPI when a version tag such as v0.1.0 is pushed. PyPI trusts this
+# workflow through trusted publishing, so no API token is stored.
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: read
+jobs:
+  publish:
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+        with:
+          version: '0.12.19'
+          python-version: '3.12'
+      - name: Tag matches the package version
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest
+      - run: uv build
+      - name: Wheel installs as a uv tool
+        run: |
+          UV_TOOL_DIR=/tmp/tools UV_TOOL_BIN_DIR=/tmp/tools/bin uv tool install --managed-python dist/*.whl
+          /tmp/tools/bin/lxreview version
+      - run: uv publish --trusted-publishing always

lxreview-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+*.egg-info/
+.live-results/
+
+# Local-only agent instructions; never commit
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+AGENTS.md
+LXReview-instructions.md
+.agents/
+.codex/

lxreview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Falco Beirer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lxreview-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: lxreview
+Version: 0.1.0
+Summary: Independent AI review loops for LXPLUS development
+Project-URL: Homepage, https://github.com/jbeirer/lxreview
+Project-URL: Issues, https://github.com/jbeirer/lxreview/issues
+Author: Joshua Beirer
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: aiohttp==3.14.3
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp==2.2.0
+Requires-Dist: playwright==1.63.0
+Requires-Dist: psutil<8,>=7
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: rich<16,>=14
+Requires-Dist: tomli-w<2,>=1.2
+Requires-Dist: typer<1,>=0.16
+Description-Content-Type: text/markdown
+
+# LXReview
+
+**Independent AI review loops for Claude Code development on LXPLUS.**
+
+ChatGPT reviews the actual GitHub PR, Claude evaluates and fixes useful findings, and LXReview sends the updated PR through another independent review. The run continues in the background until no accepted substantial issues remain or the pass limit is reached.
+
+## Why LXReview?
+
+- **Independent review** — ChatGPT reads the PR on GitHub rather than relying on Claude's description of its work.
+- **Automatic fix/review loop** — accepted findings can be fixed, checked, committed, pushed and reviewed again.
+- **Persistent runs** — reviews keep running after you close the Claude chat.
+- **Visible decisions** — follow findings, accept/reject reasons, edits, checks, commits and subsequent passes.
+- **Uses existing subscriptions** — sign into ChatGPT normally; no OpenAI API key or API credits are required.
+
+## How it works
+
+```mermaid
+flowchart LR
+    PR[PR on GitHub] --> Review[ChatGPT reviews]
+    Review --> Evaluate[Claude evaluates findings]
+    Evaluate --> Fix[Accepted fixes + checks + push]
+    Fix --> Review
+```
+
+The loop finishes when no accepted substantial issues remain, with at most one extra pass of non-blocking fixes. The final pass reports remaining issues without making edits that would go unreviewed; errors stop the run rather than count as success.
+
+## Quick start
+
+### Prerequisites
+
+- An LXPLUS account and a Git checkout of the project you want reviewed.
+- Claude Code installed and authenticated, plus GitHub CLI (`gh`) authenticated with `gh auth login`.
+- Git and [uv](https://docs.astral.sh/uv/) available on the installation host.
+- A ChatGPT account that can access the PR, and a workstation with SSH and a VNC viewer for the initial browser login.
+
+The host also needs the desktop and sandbox tools checked by `doctor`; see [host requirements](docs/OPERATIONS.md#lxplus-host-considerations).
+
+### Install and log in
+
+On the LXPLUS host where you will work:
+
+```bash
+uv tool install --managed-python lxreview
+lxreview setup --mode lxplus-browser
+lxreview login
+lxreview doctor
+```
+
+To install from a checkout instead, use `uv tool install --managed-python /path/to/lxreview`. uv gives LXReview its own environment on a uv-managed Python and puts the `lxreview` command in `~/.local/bin`; if that directory is not on your PATH, `uv tool update-shell` adds it. `setup` installs the pinned Chrome and the Claude Code integration under `~/.lxreview`, and `login` walks you through connecting to the remote desktop and signing into ChatGPT. Installation is private to your account.
+
+To view the browser again later, run `lxreview desktop connect` on the same LXPLUS host. It prints the SSH tunnel and VNC viewer instructions to follow on your workstation; see [reconnecting to the desktop](docs/OPERATIONS.md#reconnect-to-the-desktop).
+
+### Start your first review
+
+Open a **new Claude Code conversation in the project you want reviewed**, with its PR branch checked out and the working tree clean. Replace the example URL with your PR:
+
+```text
+/review-loop https://github.com/owner/repository/pull/123
+```
+
+Or let LXReview find the current branch's PR:
+
+```text
+/review-loop
+```
+
+The branch must be pushed to its upstream and have an open, accessible PR because ChatGPT reads the code on GitHub. The command returns a run ID and follows progress in the same chat.
+
+## What happens during a review?
+
+1. ChatGPT independently reviews the current PR in a fresh Temporary Chat.
+2. Claude evaluates substantial findings and eligible non-blocking findings against the code and PR discussion, including decisions already settled there.
+3. Claude runs the project's relevant checks on the unchanged code, implements accepted fixes, then checks again.
+4. Claude commits the fixes; LXReview pushes them and asks ChatGPT to review the updated PR.
+
+New check failures block publication. Pre-existing failures and checks that cannot run are reported. See [review decisions and verification](docs/OPERATIONS.md#review-decisions-and-verification) for the detailed policy.
+
+## Following and controlling a run
+
+**Closing the Claude chat does not stop the review run.** Watch it again from another conversation on the same LXPLUS host, or use the terminal. Ctrl-C in a terminal watch also stops only the watching.
+
+Replace `<run-id>` with the ID returned at startup; `lxreview runs` lists IDs and hosts.
+
+| Task | Claude Code | Terminal |
+| --- | --- | --- |
+| Follow | `/review-watch <run-id>` | `lxreview watch <run-id>` |
+| Check status | `/review-status <run-id>` | `lxreview status <run-id>` |
+| Inspect pass 1 | `/review-show <run-id> 1` | `lxreview show <run-id> --pass 1` |
+| Stop | `/review-stop <run-id>` | `lxreview stop <run-id>` |
+| Resume | `/review-resume <run-id>` | `lxreview resume <run-id>` |
+
+Resume is for failed, cancelled or interrupted runs and requires a clean, pushed checkpoint. Runs survive ordinary disconnection, subject to host policy, but not node reboot or drain.
+
+## Choosing models
+
+Defaults work without configuration. Override model and effort for one run:
+
+```text
+/review-loop --chatgpt sol:high --claude opus:xhigh
+```
+
+`lxreview options` lists available choices. See [Configuration](docs/CONFIGURATION.md) for persistent defaults, pass limits and custom verification environments.
+
+## Browser modes
+
+Use **`lxplus-browser`** for normal LXPLUS use and persistent runs.
+
+| Mode | Best for | Main trade-off |
+| --- | --- | --- |
+| `lxplus-browser` | Runs independent of your workstation | Browser runs on the LXPLUS host |
+| `local-browser` | Keeping the browser on your workstation | Workstation must stay online, awake and connected |
+
+For the alternative mode, run `lxreview setup --mode local-browser --role host` on LXPLUS, then follow the [workstation setup and pairing steps](docs/OPERATIONS.md#local-browser).
+
+## Common commands
+
+| Command | Purpose |
+| --- | --- |
+| `lxreview doctor` | Check setup and perform a ChatGPT smoke test |
+| `lxreview runs` | Find runs and their host |
+| `lxreview options` | List model and effort choices |
+| `lxreview update` | Verify/reinstall the current release's pinned runtimes |
+| `lxreview uninstall` | Remove integration and archive the installation |
+
+Run controls are listed above. See [Operations](docs/OPERATIONS.md) for application upgrades, reports and recovery.
+
+## Troubleshooting
+
+- Run `lxreview doctor`; use `--no-smoke` to avoid consuming a ChatGPT turn.
+- Check `gh auth status` and ensure your clean, pushed branch matches the PR.
+- On AFS, `run` and `resume` require at least two hours of token lifetime; renew with `kinit` followed by `aklog`.
+- After setup changes, open a fresh Claude Code conversation to load the integration.
+
+More help: [Operations and troubleshooting](docs/OPERATIONS.md#troubleshooting).
+
+## More documentation
+
+- [Configuration](docs/CONFIGURATION.md)
+- [Browser setup and operations](docs/OPERATIONS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Security](SECURITY.md)
+- [Development](docs/ARCHITECTURE.md#development)
+- [Third-party notices](THIRD_PARTY.md)
+
+Browser automation is not an official OpenAI, Anthropic or CERN integration. UI changes can break it; each user logs in normally, with no CAPTCHA or MFA bypass.

lxreview-0.1.0/README.md

@@ -0,0 +1,145 @@
+# LXReview
+
+**Independent AI review loops for Claude Code development on LXPLUS.**
+
+ChatGPT reviews the actual GitHub PR, Claude evaluates and fixes useful findings, and LXReview sends the updated PR through another independent review. The run continues in the background until no accepted substantial issues remain or the pass limit is reached.
+
+## Why LXReview?
+
+- **Independent review** — ChatGPT reads the PR on GitHub rather than relying on Claude's description of its work.
+- **Automatic fix/review loop** — accepted findings can be fixed, checked, committed, pushed and reviewed again.
+- **Persistent runs** — reviews keep running after you close the Claude chat.
+- **Visible decisions** — follow findings, accept/reject reasons, edits, checks, commits and subsequent passes.
+- **Uses existing subscriptions** — sign into ChatGPT normally; no OpenAI API key or API credits are required.
+
+## How it works
+
+```mermaid
+flowchart LR
+    PR[PR on GitHub] --> Review[ChatGPT reviews]
+    Review --> Evaluate[Claude evaluates findings]
+    Evaluate --> Fix[Accepted fixes + checks + push]
+    Fix --> Review
+```
+
+The loop finishes when no accepted substantial issues remain, with at most one extra pass of non-blocking fixes. The final pass reports remaining issues without making edits that would go unreviewed; errors stop the run rather than count as success.
+
+## Quick start
+
+### Prerequisites
+
+- An LXPLUS account and a Git checkout of the project you want reviewed.
+- Claude Code installed and authenticated, plus GitHub CLI (`gh`) authenticated with `gh auth login`.
+- Git and [uv](https://docs.astral.sh/uv/) available on the installation host.
+- A ChatGPT account that can access the PR, and a workstation with SSH and a VNC viewer for the initial browser login.
+
+The host also needs the desktop and sandbox tools checked by `doctor`; see [host requirements](docs/OPERATIONS.md#lxplus-host-considerations).
+
+### Install and log in
+
+On the LXPLUS host where you will work:
+
+```bash
+uv tool install --managed-python lxreview
+lxreview setup --mode lxplus-browser
+lxreview login
+lxreview doctor
+```
+
+To install from a checkout instead, use `uv tool install --managed-python /path/to/lxreview`. uv gives LXReview its own environment on a uv-managed Python and puts the `lxreview` command in `~/.local/bin`; if that directory is not on your PATH, `uv tool update-shell` adds it. `setup` installs the pinned Chrome and the Claude Code integration under `~/.lxreview`, and `login` walks you through connecting to the remote desktop and signing into ChatGPT. Installation is private to your account.
+
+To view the browser again later, run `lxreview desktop connect` on the same LXPLUS host. It prints the SSH tunnel and VNC viewer instructions to follow on your workstation; see [reconnecting to the desktop](docs/OPERATIONS.md#reconnect-to-the-desktop).
+
+### Start your first review
+
+Open a **new Claude Code conversation in the project you want reviewed**, with its PR branch checked out and the working tree clean. Replace the example URL with your PR:
+
+```text
+/review-loop https://github.com/owner/repository/pull/123
+```
+
+Or let LXReview find the current branch's PR:
+
+```text
+/review-loop
+```
+
+The branch must be pushed to its upstream and have an open, accessible PR because ChatGPT reads the code on GitHub. The command returns a run ID and follows progress in the same chat.
+
+## What happens during a review?
+
+1. ChatGPT independently reviews the current PR in a fresh Temporary Chat.
+2. Claude evaluates substantial findings and eligible non-blocking findings against the code and PR discussion, including decisions already settled there.
+3. Claude runs the project's relevant checks on the unchanged code, implements accepted fixes, then checks again.
+4. Claude commits the fixes; LXReview pushes them and asks ChatGPT to review the updated PR.
+
+New check failures block publication. Pre-existing failures and checks that cannot run are reported. See [review decisions and verification](docs/OPERATIONS.md#review-decisions-and-verification) for the detailed policy.
+
+## Following and controlling a run
+
+**Closing the Claude chat does not stop the review run.** Watch it again from another conversation on the same LXPLUS host, or use the terminal. Ctrl-C in a terminal watch also stops only the watching.
+
+Replace `<run-id>` with the ID returned at startup; `lxreview runs` lists IDs and hosts.
+
+| Task | Claude Code | Terminal |
+| --- | --- | --- |
+| Follow | `/review-watch <run-id>` | `lxreview watch <run-id>` |
+| Check status | `/review-status <run-id>` | `lxreview status <run-id>` |
+| Inspect pass 1 | `/review-show <run-id> 1` | `lxreview show <run-id> --pass 1` |
+| Stop | `/review-stop <run-id>` | `lxreview stop <run-id>` |
+| Resume | `/review-resume <run-id>` | `lxreview resume <run-id>` |
+
+Resume is for failed, cancelled or interrupted runs and requires a clean, pushed checkpoint. Runs survive ordinary disconnection, subject to host policy, but not node reboot or drain.
+
+## Choosing models
+
+Defaults work without configuration. Override model and effort for one run:
+
+```text
+/review-loop --chatgpt sol:high --claude opus:xhigh
+```
+
+`lxreview options` lists available choices. See [Configuration](docs/CONFIGURATION.md) for persistent defaults, pass limits and custom verification environments.
+
+## Browser modes
+
+Use **`lxplus-browser`** for normal LXPLUS use and persistent runs.
+
+| Mode | Best for | Main trade-off |
+| --- | --- | --- |
+| `lxplus-browser` | Runs independent of your workstation | Browser runs on the LXPLUS host |
+| `local-browser` | Keeping the browser on your workstation | Workstation must stay online, awake and connected |
+
+For the alternative mode, run `lxreview setup --mode local-browser --role host` on LXPLUS, then follow the [workstation setup and pairing steps](docs/OPERATIONS.md#local-browser).
+
+## Common commands
+
+| Command | Purpose |
+| --- | --- |
+| `lxreview doctor` | Check setup and perform a ChatGPT smoke test |
+| `lxreview runs` | Find runs and their host |
+| `lxreview options` | List model and effort choices |
+| `lxreview update` | Verify/reinstall the current release's pinned runtimes |
+| `lxreview uninstall` | Remove integration and archive the installation |
+
+Run controls are listed above. See [Operations](docs/OPERATIONS.md) for application upgrades, reports and recovery.
+
+## Troubleshooting
+
+- Run `lxreview doctor`; use `--no-smoke` to avoid consuming a ChatGPT turn.
+- Check `gh auth status` and ensure your clean, pushed branch matches the PR.
+- On AFS, `run` and `resume` require at least two hours of token lifetime; renew with `kinit` followed by `aklog`.
+- After setup changes, open a fresh Claude Code conversation to load the integration.
+
+More help: [Operations and troubleshooting](docs/OPERATIONS.md#troubleshooting).
+
+## More documentation
+
+- [Configuration](docs/CONFIGURATION.md)
+- [Browser setup and operations](docs/OPERATIONS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Security](SECURITY.md)
+- [Development](docs/ARCHITECTURE.md#development)
+- [Third-party notices](THIRD_PARTY.md)
+
+Browser automation is not an official OpenAI, Anthropic or CERN integration. UI changes can break it; each user logs in normally, with no CAPTCHA or MFA bypass.

lxreview-0.1.0/SECURITY.md

@@ -0,0 +1,17 @@
+# Security model
+
+LXReview deliberately runs its dedicated Claude worker with bypass permissions. It does not change permission mode in ordinary Claude conversations.
+
+Workers have an explicit tool list, no subagent tools, no external MCP servers, and run-scoped `PreToolUse` hooks. Claude's Bash sandbox is explicitly enabled with `failIfUnavailable` and no unsandboxed fallback; missing sandbox prerequisites fail rather than weaken the policy. No worker turn has network access. Evaluation is read-only. The edit/test turn may run the project's own tooling, one literal command at a time: hooks refuse shell composition and expansion, shells and wrapper commands (`bash`, `env`, `xargs`, `sudo` and similar), `GIT_*`, loader and `PATH` assignments, Git mutations, commands that modify files outside the repository, and paths to credentials. The sandbox confines writes to the repository (Git metadata, hooks and tool configuration such as `.claude`, `.gitmodules` and `.lfsconfig` excluded) and a private per-turn directory, and hides credentials and private data: the installation root, `~/.config` (except Git's own configuration), `~/.claude`, SSH, GnuPG, cloud, container and package-registry credentials, keyrings, browser profiles, shell histories, Kerberos ticket files and `.env` files. The publication turn may only stage and commit, with no Co-Authored-By or Claude attribution.
+
+Before each evaluation, LXReview reads the PR's discussion with your `gh` login, outside the sandbox, through one read-only GraphQL query; Claude receives it as untrusted text, and each pass keeps a copy in its audit directory. LXReview itself verifies that publication added exactly one commit on top of the reviewed head and left no uncommitted changes, then signs (if configured) and pushes it outside the sandbox with the user's credentials, to the existing upstream by an explicit refspec. Push policy checks reject force/mirror refspecs and alternate destinations in Git configuration. Pre-push hooks are not run for these pushes, since they could execute files the worker changed; commit hooks run inside the sandbox. A repository setup command from `[verify.setup]` runs outside the sandbox before the worker edits anything; it comes from the user's own configuration and must not source repository files.
+
+These protections are defense in depth, not a claim that hooks safely execute arbitrary hostile projects. Test code and commit hooks are executable code; use a disposable branch and trusted repository. A failing check or push is never fixed by disabling the sandbox. User or enterprise Claude managed settings may further restrict operation.
+
+Playwright drives Chrome over a private pipe, so Chrome opens no debugging port. The browser service accepts calls only on a 0600 unix socket in a 0700 per-user runtime directory (`/run/user/<uid>`, or the private installation root where the host has none), with a per-start bearer token. VNC and the relay bind only to loopback. SSH reverse forwarding explicitly binds `127.0.0.1` on the exact LXPLUS node. Loopback is not a user boundary: relay bearer authentication remains mandatory. A fresh challenge checks server possession of the relay token before the client sends its bearer to a potentially stale port. Pairing uses a single-use ten-minute nonce. Relay credentials rotate on bridge creation, expire after at most eight hours, and are sent over SSH stdin, never argv. A disconnected bridge is unavailable, and credentials expire even when remote cleanup cannot run. The relay accepts only named package operations and no arbitrary URL or file proxying.
+
+Private roots/directories use 0700 and secrets/state use 0600. Runtime archives are pinned by SHA-256 and Python dependencies by `uv.lock` hashes; Playwright never downloads browsers. Downloads are staged and checked before extraction. Browser state is never copied, exported or shared. No OpenAI API, cookie extraction, CAPTCHA bypass, or MFA bypass exists.
+
+Events redact credential-shaped keys/values and drop thinking/signature blocks. Raw reviewer responses are preserved verbatim by contract, so do not send credentials to the reviewer. Audit artifacts may contain proprietary code and should be handled as private repository data. The package cannot reliably recognize every arbitrary secret embedded in source text; inspect reports before sharing them.
+
+Installer integration refuses command collisions. Uninstall removes only registrations and links that still match ownership records. It archives the private root for recovery; delete the archive for complete removal. No shell startup, conda, global npm, user VNC startup or unrelated browser process is modified.

lxreview-0.1.0/THIRD_PARTY.md

@@ -0,0 +1,16 @@
+# Third-party components
+
+LXReview composes these projects.
+
+| Component | License / terms | Distribution |
+|---|---|---|
+| [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/) 154.0.8037.57 | Google Chrome terms and Chromium third-party notices | Downloaded directly from Google's release bucket |
+| [CPython](https://www.python.org/) | PSF license | uv-managed private runtime |
+| [uv](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | User-provided installer (`uv tool install`) |
+| [Playwright](https://github.com/microsoft/playwright) 1.63.0 | Apache-2.0 (its wheel bundles a Node.js driver under MIT) | Python dependency; drives the pinned Chrome |
+| [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) | MIT | Python dependency |
+| Typer, Pydantic, HTTPX, Rich, tomli-w | MIT | Python dependencies |
+| aiohttp | Apache-2.0 | Python dependency |
+| psutil | BSD-3-Clause | Python dependency |
+
+Exact Python dependencies and hashes are in `uv.lock`. Preserve upstream license files when redistributing runtimes. Claude Code, TigerVNC, Xfce, systemd, tmux, SSH and macOS launchd are external installed tools, not bundled here. This software has no claimed endorsement by CERN, OpenAI, Anthropic or any upstream project.

lxreview-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,109 @@
+# Architecture
+
+For setup and run control, see [Operations](OPERATIONS.md). For trust boundaries and publication restrictions, see [Security](../SECURITY.md).
+
+## Components
+
+| Module | Responsibility |
+| --- | --- |
+| `contracts.py` | Normalized requests, responses, health, reviewer and browser-session protocols |
+| `worker.py` | Provider-neutral review loop |
+| `reviewer.py` | Independent review semantics and prompts |
+| `browser/playwright.py` | ChatGPT selectors, page state, prompt readback, submission and completion rules |
+| `browser/service.py` | Supervised driver process that owns Chrome and serves named operations over a private Unix socket |
+| `backend.py` | Composition root; workflow prompts and worker logic do not branch on browser placement |
+| `bridge/relay.py` | Named browser operations, with a workstation session lock across a whole review |
+| `bridge/ssh.py` | Exact-host pairing and reverse forwarding |
+| `mcp/server.py` | Stable package-owned stdio API for browser operations |
+| `process.py` | Package-scoped supervision through systemd, tmux under a systemd scope, or launchd |
+
+Configuration uses strict TOML/Pydantic. Schema 1 is the initial schema; unknown versions fail with an upgrade instruction rather than being rewritten. User settings are described in [Configuration](CONFIGURATION.md).
+
+## Browser placement
+
+In `lxplus-browser` mode, the worker and browser run on the same host:
+
+```mermaid
+flowchart LR
+    Worker[Persistent Claude worker] --> Reviewer[Reviewer contract]
+    Reviewer --> Service[Browser service]
+    Service --> Chrome[Chrome on private VNC desktop]
+    Viewer[Workstation VNC viewer] -. login .-> Chrome
+```
+
+In `local-browser` mode, the browser service runs on the workstation:
+
+```mermaid
+flowchart LR
+    Worker[Worker on LXPLUS] --> Reviewer[Reviewer contract]
+    Reviewer --> Relay[Authenticated operation relay]
+    Relay --> Service[Workstation browser service]
+    Service --> Chrome[Workstation Chrome]
+```
+
+The relay is reached through a loopback-only SSH reverse tunnel to the exact LXPLUS node. MCP exposes the browser contract to Claude Code; the worker calls the reviewer backend directly. Browser authentication and transport boundaries are detailed in [Security](../SECURITY.md).
+
+## Worker lifecycle
+
+The full review loop holds one cross-process reviewer lock and one repository lock. Each pass creates a fresh Temporary Chat in the same browser tab and persists the raw review before invoking Claude. The independent reviewer receives only the PR target, updated SHA and rubric, never earlier review findings.
+
+Claude uses three restricted turns in one Claude session:
+
+1. Read-only evaluation of findings against the repository and PR discussion.
+2. Offline edits and checks, without Git metadata writes.
+3. Staging and committing after verification permits publication.
+
+LXReview validates the resulting commit and pushes it outside those turns. The [operations policy](OPERATIONS.md#review-decisions-and-verification) covers findings, baseline checks and final-pass behavior.
+
+```mermaid
+stateDiagram-v2
+    [*] --> QUEUED
+    QUEUED --> RUNNING
+    RUNNING --> CLEAN
+    RUNNING --> NO_VALID_SUBSTANTIAL_FINDINGS
+    RUNNING --> MAX_PASSES
+    RUNNING --> FAILED
+    RUNNING --> CANCELLED
+    RUNNING --> INTERRUPTED
+    FAILED --> QUEUED: verified resume
+    CANCELLED --> QUEUED: verified resume
+    INTERRUPTED --> QUEUED: verified resume
+```
+
+Resume verifies branch/remote identity and a clean, pushed HEAD. Incomplete pass evidence is archived before another independent pass. A durable cancellation marker wins over later worker state updates; observing a missing worker marks a nonterminal run interrupted.
+
+## Hosts, storage and integration
+
+Host identity prevents shared-home LXPLUS users from treating another node's services as local. Supervisor names include an installation-root hash to avoid collisions between installations. Sockets and service temporary files live in `/run/user/<uid>/lxreview-<hash>` when available, falling back to the installation's `run` directory; AFS homes cannot hold Unix sockets.
+
+| Location | Contents |
+| --- | --- |
+| `~/.local/bin/lxreview` | Command installed by `uv tool install` |
+| `~/.lxreview/bin/lxreview` | Fixed launcher written by `setup`: the tool environment's interpreter with this installation root |
+| `~/.lxreview/state/runs/<id>/` | Run state, redacted events, worker output, Claude session ID and cancellation marker |
+| `<git-common-dir>/review-loop/<id>/` | Run metadata, events, summary and per-pass evidence |
+| `<git-common-dir>/review-loop/<id>/pass-NN/` | Verbatim review, explicit evaluations, PR discussion, diff, check reports and metadata |
+
+Using the Git common directory keeps audit evidence out of commits and supports worktrees. Interrupted pass directories are retained with an `-interrupted-*` suffix. Events exclude hidden reasoning and redact credential-shaped values; raw reviews remain verbatim. See [Security](../SECURITY.md) before sharing artifacts.
+
+Claude's user integration registers the MCP server and six slash commands pointing to the fixed launcher, so upgrading the package keeps them valid. Ownership records allow uninstall to remove only unchanged package-owned entries. Setup leaves shell startup files and PATH untouched.
+
+During sandboxed commands, Claude Code creates empty, read-only placeholders for protected paths such as `.bashrc`, `.mcp.json` and `.claude/settings.json`. They disappear after the command, and LXReview excludes them from `git status` during the run. The full filesystem boundary is documented in [Security](../SECURITY.md).
+
+## Development
+
+From the source checkout:
+
+```bash
+uv sync --frozen
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv build
+uv tool install --managed-python --reinstall .   # use this checkout as the installed lxreview
+```
+
+Releases are published to PyPI by the `publish` workflow when a tag matching the package version (`v0.1.0`) is pushed. Playwright, mcp and aiohttp are pinned exactly in `pyproject.toml`, because an installed wheel does not use `uv.lock`.
+
+The default test suite does not require a live browser or account login. See [third-party notices](../THIRD_PARTY.md) for runtime dependencies.