fix: repair Codex Cloud Python setup

[BigSimmo]

Summary

• Add a Python 3.12-specific, hash-locked Cloud worker environment while preserving the Python 3.11 production worker lock.
• Add automatic, sanitized Cloud setup diagnostics with issue and fix guidance for the failed setup phase.
• Make Cloud setup validate its Python runtime, install with hashes, run pip check, and retain atomic configuration failure coverage on Windows.
• Update the Cloud guide and generated script inventory.

RAG impact: no retrieval behaviour change — the production Python 3.11 worker lock and retrieval/ranking code are unchanged; this adds a Cloud-only Python 3.12 setup lock and diagnostics.

Why

The August 2 Cloud setup used the Python 3.11-generated worker lock under Python 3.12. medspacy==1.3.1 requires spacy>=3.8 on Python 3.12, while the old lock pinned spacy==3.7.5, so pip stopped with ResolutionImpossible before any requested tests could run.

Verification

• npm run verify:pr-local — PASS (runtime, installed-lock parity, formatting, docs contracts, ledger, lint, typecheck, full Vitest suite, production build, client-secret scan, and 36 RAG fixtures)
• Focused Vitest: 3 files passed, 21 tests passed
• Python 3.11 production lock reproduction — PASS
• Python 3.12 Cloud lock reproduction — PASS
• Isolated Python 3.12 hash-locked install, pip check, and medspaCy/spaCy imports — PASS
• npm run check:branch-review-ledger — PASS (540 live + 1206 archived records)
• npm run verify:ui — not run; no UI, routing, styling, or browser behaviour changed
• npm run verify:release — not run locally; hosted CI and post-merge Cloud acceptance provide the requested handoff evidence
• npm run check:production-readiness — code guards passed, but the isolated worktree correctly failed on intentionally absent Supabase/OpenAI secrets

Risk and rollout

• Risk: low to moderate; Cloud setup now requires Python 3.12 explicitly and uses a separate generated lock. Production remains on its existing Python 3.11 lock.
• Rollback: revert this PR to restore the prior single-lock Cloud setup.
• Provider or production effects: GitHub PR/CI and post-merge Cloud validation are explicitly authorized. No production data mutation, deployment, or provider-key exposure is performed.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

Notes

• Review ledger outcome: PASS, no actionable findings, at 2de7b7abbdea9a1286b198e14eecb021fff32693.
• The old temporary Cloud validation folders could not be removed because the desktop command safety policy rejected the recursive deletion; they were not included in this branch.

---

Summary by CodeRabbit

• New Features

  • Added automatic diagnostics when Cloud setup fails, including health checks, issue details, and remediation guidance.
  • Added support for separate, validated Python environments for production and Cloud runtimes.
  • Added commands to generate and verify Cloud worker dependency locks.

• Bug Fixes

  • Improved setup failure handling with clearer phase tracking and validation of Python and dependency versions.

• Documentation

  • Documented automatic diagnostics, manual troubleshooting commands, and Cloud-specific Python requirements.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:36 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 68ea5e93-a1bf-42c2-8e77-0e88ff2944c8

📥 Commits

Reviewing files that changed from the base of the PR and between 0465ec5 and 05932f9.

📒 Files selected for processing (5)

• docs/branch-review-ledger.md
• scripts/diagnose-codex-cloud.mjs
• scripts/setup-codex-cloud.sh
• tests/codex-cloud-diagnose.test.ts
• tests/codex-cloud-setup.test.ts

📝 Walkthrough

Walkthrough

The PR adds separate Python 3.11 production and Python 3.12 Cloud lock targets. Codex Cloud setup now validates the Cloud lock, tracks phases, and runs diagnostics after failures. Documentation and tests cover the new commands and behavior.

Changes

Worker Python lock lifecycle

Layer / File(s)	Summary
Worker Python lock targets and validation scripts/worker-python-lock-config.mjs, scripts/generate-worker-python-lock.mjs, scripts/check-worker-python-lock.mjs, worker/python/requirements-cloud.txt, worker/python/requirements.in, tests/worker-python-lock.test.ts, package.json, docs/scripts-index.md	Production and Cloud targets now define separate Python versions, output files, generation commands, and validation rules. The Cloud lock pins Python 3.12 dependencies with hashes.
Cloud setup phases and diagnostics scripts/diagnose-codex-cloud.mjs, scripts/setup-codex-cloud.sh, scripts/check-codex-cloud-setup.mjs, tests/codex-cloud-diagnose.test.ts, tests/codex-cloud-setup.test.ts, docs/codex-cloud.md, docs/branch-review-ledger.md	Cloud setup tracks phases, validates Python and lock alignment, installs hashed dependencies, and reports coded diagnostics after failures. Tests cover diagnostics, failure handling, and Windows execution.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
participant setup_codex_cloud
participant check_worker_python_lock
participant diagnose_codex_cloud
participant CodexCloud
setup_codex_cloud->>check_worker_python_lock: validate requirements-cloud.txt
setup_codex_cloud->>CodexCloud: install Python 3.12 worker dependencies
setup_codex_cloud->>diagnose_codex_cloud: run diagnostics when setup fails
diagnose_codex_cloud-->>CodexCloud: print issue codes and fixes

Loading

Possibly related PRs

• BigSimmo/Database#1575: Extends worker Python lock generation and validation to support a separate Cloud target.
• BigSimmo/Database#1497: Shares Codex Cloud setup validation and test coverage.
• BigSimmo/Database#1581: Shares Codex Cloud setup scripts and documentation.

Suggested labels:codex

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: repairing Codex Cloud Python setup.
Description check	✅ Passed	The description includes the required summary, verification, risk, rollback, governance, and notes sections with relevant details and reasons for skipped checks.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 2 potential issues.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:0465ec583f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BigSimmo]

@codex resolve actionable Codex review findings for this pull request and current head using the repository instructions. This is the pull request's single automatic repair pass: do not perform a fresh review, create new standalone findings, or request another review. Work only the existing unresolved Codex threads on the current head. The only repository destination is BigSimmo/Database, and the only branch destination is the pull request head branch codex/cloud-python-self-diagnosis at starting commit 0465ec5; never publish fixes to a detached or synthetic work branch and never create a stacked pull request. Use the authenticated GitHub connector to commit each approved fix to BigSimmo/Database:codex/cloud-python-self-diagnosis, then verify that the pull request head contains the published commit before reporting success. Always fix P0 and P1 findings. For P2 and lower findings, fix only clear, scoped, low-risk issues; otherwise disposition them with a concise reason. For a fixed thread, reply with as the first line and as the second line. For a no-code disposition, use followed by . These result markers authorize the workflow to close that exact thread only after it verifies a fixed commit is the pull request head; a local-only commit is not a fix. If publication or verification fails, do not use either result marker, do not claim success, and leave the thread open with the blocker. If human input or new authorization is required, do the same. Finish only after every actionable thread is fixed or dispositioned and closed, or explicitly left open for a human decision. Do not update the branch from main, address unrelated reviews, broaden scope, or create more than one scoped fix commit. Do not use external APIs, paid services, credentials, dependency changes, or broad refactors unless explicitly authorized. Add targeted tests where behavior changes and run the narrowest relevant validation.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit:0465ec583f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".