docs(codex-cloud): formalize shell sanitation and guarded GitHub fallback

AGENTS.md

@@ -866,8 +866,8 @@ Codex Cloud uses an isolated Linux container and does not inherit desktop files,
 credentials, OAuth sessions, MCP authentication, local services, or uncommitted work.
 Use `docs/codex-cloud.md` as the environment contract:
 
-- Setup: `bash scripts/setup-codex-cloud.sh`.
-- Maintenance: `bash scripts/maintain-codex-cloud.sh`.
+- Configure setup as `bash scripts/setup-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh`.
+- Configure maintenance as `bash scripts/maintain-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh`.
 - Default to `CODEX_CLOUD_ACCESS_PROFILE=offline` for ordinary and protected RAG work.
   Use `connected` only when the user explicitly authorizes the required provider access.
 - Cloud has no Windows task-start script. Report that exact fact, then perform equivalent
@@ -880,16 +880,19 @@ Use `docs/codex-cloud.md` as the environment contract:
 - Repository setup cannot grant GitHub installation permissions, workspace RBAC, network
   policy, or provider credentials. Treat those as product/account settings and verify them
   separately without printing secret values.
-- In a Cloud agent shell, `npm run check:codex-cloud` validates the tracked contract and
-  effective access-profile modes. Use `npm run check:codex-cloud -- --runtime` for the
-  complete installed toolchain and browser executables. Also run
-  `npm run check:runtime` and `npm run check:installed-lock-parity` before trusting a new
-  or reset environment. A skipped browser install is not full browser readiness. Output is
-  limited to approved mode values, presence booleans, repository identity, and MCP
-  server/command/environment-variable names; never print credential values.
+- In a fresh Cloud agent shell, run `npm run check:codex-cloud` directly, without manually
+  sourcing a profile or entering a login shell; it must report the static-and-environment PASS
+  line. Then run `npm run check:codex-cloud -- --runtime`; it must report the static,
+  environment, and runtime PASS line. The command shims load the generated profile for normal
+  `node`, `npm`, and `npx` work. Also run `npm run check:runtime` and
+  `npm run check:installed-lock-parity` before trusting a new or reset environment. A skipped
+  browser install is not full browser readiness. Output is limited to approved mode values,
+  presence booleans, repository identity, and MCP server/command/environment-variable names;
+  never print credential values.
 - Do not add OpenAI, Supabase, Railway, GitHub, database, or user credentials as ordinary
   Cloud environment variables. Codex Cloud secrets are setup-only and unavailable to the
-  agent phase; do not copy them into files to bypass that boundary.
+  agent phase unless the platform explicitly exposes a secret to the named task phase; do not
+  copy them into files to bypass that boundary.
 - Provider-backed checks, hosted CI mutations, deployment, production data access, and
   Git publishing still require the explicit authorization defined above.
 - The ordinary offline Cloud profile intentionally cannot perform authenticated production or
@@ -900,22 +903,27 @@ Use `docs/codex-cloud.md` as the environment contract:
   credentials to the Codex Cloud agent shell.
 - Railway reads require both the pinned CLI and a dedicated `RAILWAY_API_TOKEN`. Never substitute
   `RAILWAY_TOKEN`. GitHub CLI authentication, the credential-free `origin` URL, and shell Git
-  authentication are separate capabilities; never add a PAT or token-bearing credential helper.
-- The Codex GitHub connection used to clone a repository is separate from agent-shell
-  `git push` or `gh` authentication. Reconnect the repository in Codex settings if a
-  controlled write test cannot publish; never add a PAT to Cloud variables or secrets.
+  authentication are separate capabilities.
 - For an explicitly authorised GitHub task, use the authenticated GitHub connector/MCP
   tools as the default remote control plane. Use them for repository, PR, issue, review
   thread, and Actions work, including inline-thread replies/resolution, Actions
   run/job/log/artifact inspection, and approved branch, file, or PR mutations. Missing
   `gh`, shell GitHub credentials, or direct shell network access is not a loss of this
-  capability and must not prompt a PAT workaround. The intended connection is `BigSimmo`
-  with administrator access to this repository. Use shell `git` or `gh` only for a
-  genuine connector gap and only when the task permits it.
-- Confirm the exact repository and PR/thread/job before a write, and verify the
-  connector result before treating the write as successful. If the connector lacks a
-  needed GitHub setting or organisation control, report that limit rather than attempting a
-  credential, secret, or shell-based bypass.
+  capability. The intended connection is `BigSimmo` with repository write access.
+  Reserve administrator access for separately approved operations.
+- A PAT is a connected-only, user-authorised exception for a genuine connector gap. Store a
+  short-lived, fine-grained `CODEX_CLOUD_GITHUB_PAT` only as a connected Cloud secret and
+  scope it to this repository and the named operation. Never make it an ordinary variable,
+  profile value, remote URL, or cached file. Use only
+  `bash scripts/delete-codex-cloud-branch-with-pat.sh <non-protected-branch>` for an exact
+  branch-deletion instruction; it verifies the profile, ref, and credential-free origin and
+  never prints the token. Remove or rotate the secret immediately afterwards. If secrets are
+  unavailable in that task phase, report the platform limit rather than bypassing it.
+- Confirm the exact repository and PR/thread/job before a write, and verify the connector
+  result before treating the write as successful. A repository cannot sanitize a variable
+  already inherited by the top-level task process; the tracked shims protect normal
+  `node`/`npm`/`npx` commands. Report raw-parent exposure as a Codex Cloud launcher defect
+  rather than weakening the provider-variable contract.
 - Cloud browser proof is Playwright/Chromium, Firefox, or WebKit container evidence, not
   physical iPhone Safari/PWA acceptance.
 
@@ -933,7 +941,7 @@ Durable notes for Cloud Agents. Standard commands live in `README.md` and `packa
   connector/MCP tools first for PR, issue, comment, review-thread, and Actions tasks they
   support (including run/job/log/artifact inspection and review-thread replies/resolution).
   A missing `gh` CLI is not a blocker for connector-supported work; never add a PAT as a
-  workaround. The intended connection is `BigSimmo` with administrator access to this
-  repository. Verify the exact target and connector result before any write. Ordinary
+  workaround. The intended connection is `BigSimmo` with repository write access.
+  Reserve administrator access for separately approved operations. Verify the exact target and connector result before any write. Ordinary
   authorised shell `git` branch publication remains allowed; use shell `gh` only for a
   genuine connector gap and only when the task permits it.

README.md

@@ -28,7 +28,9 @@ the Cloud-only Bash setup script.
 
 For Codex Cloud, use the tracked environment setup and acceptance contract in
 [`docs/codex-cloud.md`](docs/codex-cloud.md). It installs the complete repository
-toolchain and distinguishes safe offline tasks from explicitly connected provider tasks.
+toolchain, installs the profile-loading Node command shims, and distinguishes safe offline
+tasks from explicitly connected provider tasks. Fresh Cloud validation runs the direct
+`npm run check:codex-cloud` commands without manually sourcing a profile.
 
 3. Copy the full `.env.example` to `.env.local` and fill in Supabase and OpenAI
    values. Copy the worker and upload defaults too — they are conservative

docs/README.md

@@ -19,7 +19,7 @@ npm run docs:check-links
 | [site-map.md](site-map.md)             | **Generated** route map — regenerate with `npm run docs:update`, verify with `npm run sitemap:check`       |
 | [agents-guide.md](agents-guide.md)     | Human onboarding pointer; Cursor MCP default read path (Supabase, Railway, Context7); rules in `AGENTS.md` |
 | [scripts-index.md](scripts-index.md)   | Curated map of `scripts/` and the `package.json` command surface by purpose                                |
-| [codex-cloud.md](codex-cloud.md)       | Codex Cloud setup, access profiles, platform settings, and acceptance checks                               |
+| [codex-cloud.md](codex-cloud.md)       | Codex Cloud setup, access profiles, profile-loading command shims, GitHub exception, and acceptance checks |
 
 ## Architecture
 

docs/codex-cloud.md

@@ -30,18 +30,21 @@ In Codex environment settings, create an environment for `BigSimmo/Database` usi
 official [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environment)
 contract:
 
-| Setting               | Value                                  |
-| --------------------- | -------------------------------------- |
-| Repository            | `BigSimmo/Database`                    |
-| Base image            | Default universal image                |
-| Node version          | `24`                                   |
-| Setup command         | `bash scripts/setup-codex-cloud.sh`    |
-| Maintenance command   | `bash scripts/maintain-codex-cloud.sh` |
-| Environment variables | Use the complete profile below         |
-
-Enable agent internet access only when a task needs it. Prefer a domain allowlist and the
-minimum HTTP methods for the task. Package installation happens during setup; ordinary
-structure-only work, including the RAG decomposition prompt below, should remain offline.
+| Setting               | Value                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------- |
+| Repository            | `BigSimmo/Database`                                                                         |
+| Base image            | Default universal image                                                                     |
+| Node version          | `24`                                                                                        |
+| Setup command         | `bash scripts/setup-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh`    |
+| Maintenance command   | `bash scripts/maintain-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh` |
+| Environment variables | Use the complete profile below                                                              |
+
+Keep agent internet access off for this repository's ordinary Cloud environments. Package
+installation happens during setup; ordinary structure-only work, including the RAG
+decomposition prompt below, remains offline. The appended command-shim installer is required:
+it makes every normal `node`, `npm`, and `npx` invocation load the generated sanitized
+profile before starting Node. It is idempotent and uses `nvm which` rather than
+`command -v node`, so maintenance cannot accidentally wrap an earlier wrapper.
 
 The setup command fails if the complete toolchain cannot be installed. It pins Railway CLI
 `5.30.1` and Codex CLI `0.146.0`, both stable npm releases as reviewed on 2026-07-30. Railway's
@@ -69,14 +72,17 @@ PLAYWRIGHT_OFFLINE_MODE=true
 ```
 
 The generated shell profile removes known OpenAI, Supabase, Railway, GitHub/GitLab,
-database, CI-trigger, and test-user credential variables. This prevents an unrelated Cloud
-task from silently becoming provider-backed.
+database, CI-trigger, test-user, and emergency-PAT variables. This prevents an unrelated
+Cloud task from silently becoming provider-backed.
 
 Set all five offline values in the environment UI. The setup also writes the generated
 profile to `.bashrc`, `.profile`, and `.bash_profile`. Covering `.bash_profile` is required:
 Bash stops login-profile discovery at the first matching file, so an existing `.bash_profile`
 can otherwise prevent `.profile` from running. Offline mode values are forced after inherited
 platform values so stale `auto`/`false` settings cannot outrank the repository contract.
+Do not manually source the profile as an acceptance workaround: start a fresh task and invoke
+the direct `npm run check:codex-cloud` commands below. The tracked command shims make those
+ordinary Node commands load the profile themselves.
 
 ### Connected (explicit opt-in)
 
@@ -133,14 +139,23 @@ approved operations. Some GitHub APIs, including review-thread or Actions manage
 may not be exposed in every Cloud task; use an approved GitHub-connected workflow for those
 operations or report the unavailable capability. Do not use shell credentials as a workaround.
 
-GitHub connector permission is separate from credentials inside the agent shell. Do
-not add a personal access token to Cloud secrets or environment variables to make
-`git push` or `gh` work. If a Cloud task cannot publish a branch, reconnect the
-repository in Codex settings and run a controlled branch/PR write test. Confirm the
-exact repository and PR/thread/job before a write, and verify the connector result
-before treating the write as successful. If the connector does not expose a required
-repository/organisation setting, report the limit rather than attempting a credential or
-secret workaround.
+GitHub connector permission is separate from credentials inside the agent shell. The connector
+remains the default for repository, PR, review, and Actions work. For an explicitly authorised
+connector gap, a fine-grained GitHub PAT may be stored only as the connected environment secret
+`CODEX_CLOUD_GITHUB_PAT`. Scope it to the `BigSimmo/Database` repository, give it only the
+least privilege needed for the named operation (for stale-branch deletion, **Contents: write**),
+and set a short expiry. Never add it as an ordinary environment variable, print it, put it in a
+remote URL, cache, profile, or repository file, or use it for provider access. The default and
+ordinary connected profiles both scrub the name before Node work begins.
+
+The only tracked PAT helper is
+`bash scripts/delete-codex-cloud-branch-with-pat.sh <non-protected-branch>`. It refuses offline
+mode, protected/invalid refs, and any origin other than the credential-free
+`https://github.com/BigSimmo/Database.git`; it uses a temporary askpass program and deletes
+only the specified branch and disables Git hooks for its PAT-bearing push. Use it only for the exact
+user-authorised cleanup, then remove or
+rotate the secret. If Cloud does not expose secrets to the requested task phase, the PAT is not a
+usable workaround—report that platform limit rather than copying the token anywhere.
 
 Setup restores a missing `origin` to the credential-free URL
 `https://github.com/BigSimmo/Database.git`; it preserves an existing correct remote and fails
@@ -166,22 +181,21 @@ approve cleanup.
 
 ## Setup and maintenance
 
-Setup:
+Configure the following complete commands in the environment UI:
 
 ```bash
-bash scripts/setup-codex-cloud.sh
+bash scripts/setup-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh
 ```
 
-Maintenance:
-
 ```bash
-bash scripts/maintain-codex-cloud.sh
+bash scripts/maintain-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh
 ```
 
 The maintenance command reasserts the safe `origin`, runs static/effective environment
-acceptance, then runtime acceptance. Any runtime, dependency, CLI, Deno, Python/OCR, or browser
-drift reruns the full setup instead of repairing only `node_modules`. All profile insertions,
-CLI installs, and remote repair are idempotent.
+acceptance, then runtime acceptance. The shim installer runs after either lifecycle command and
+repairs the normal Node command boundary. Any runtime, dependency, CLI, Deno, Python/OCR, or
+browser drift reruns the full setup instead of repairing only `node_modules`. All profile
+insertions, command shims, CLI installs, and remote repair are idempotent.
 
 ## Acceptance
 
@@ -212,6 +226,12 @@ identity, offline credential absence when applicable, and obsolete npm proxy var
 without reading or printing their values. MCP inspection emits server names, commands, and
 environment variable names only.
 
+A repository cannot remove a variable already inherited by the top-level task process. The
+command shims protect normal Node work, which is what the acceptance commands exercise. If a
+fresh task still exposes a provider variable to a direct raw `/bin/bash`, Python, or another
+native child before the generated profile is loaded, treat that as a Codex Cloud launcher defect
+and report the variable name only; do not weaken the profile or reintroduce provider variables.
+
 `npm run check:production-readiness` remains useful in the offline profile for local safeguards.
 Missing Supabase/OpenAI agent-phase credentials are reported as a provider capability gap and do
 not make the provider-free cache unhealthy. `ALLOW_PROVIDER_TESTS=true` expresses authorization,