fix(agents): Cloud Agent Figma MCP auth fallback

.github/workflows/codeql-pr.yml

@@ -90,12 +90,46 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha }}
 
       - name: Initialize CodeQL
+        id: init-codeql
+        continue-on-error: true
+        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      # Feature-enablement GET /code-scanning/codeql-action/features returns
+      # HTTP 503 "No server is currently available" during GitHub API outages.
+      # One 20s retry was not enough when sibling CodeQL jobs recovered later.
+      - name: Wait before CodeQL init retry
+        if: steps.init-codeql.outcome == 'failure'
+        run: sleep 30
+
+      - name: Retry Initialize CodeQL after GitHub API outage
+        id: init-codeql-retry
+        if: steps.init-codeql.outcome == 'failure'
+        continue-on-error: true
+        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      - name: Wait before CodeQL init second retry
+        if: steps.init-codeql.outcome == 'failure' && steps.init-codeql-retry.outcome == 'failure'
+        run: sleep 60
+
+      - name: Second retry Initialize CodeQL after GitHub API outage
+        id: init-codeql-retry-2
+        if: steps.init-codeql.outcome == 'failure' && steps.init-codeql-retry.outcome == 'failure'
         uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
 
       - name: Perform CodeQL Analysis
+        if: >-
+          steps.init-codeql.outcome == 'success' ||
+          steps.init-codeql-retry.outcome == 'success' ||
+          steps.init-codeql-retry-2.outcome == 'success'
         uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           category: "/language:${{ matrix.language }}"
@@ -197,12 +231,46 @@ jobs:
           ref: ${{ format('refs/pull/{0}/merge', github.event.pull_request.number) }}
 
       - name: Initialize CodeQL
+        id: init-codeql
+        continue-on-error: true
+        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      # Feature-enablement GET /code-scanning/codeql-action/features returns
+      # HTTP 503 "No server is currently available" during GitHub API outages.
+      # One 20s retry was not enough when sibling CodeQL jobs recovered later.
+      - name: Wait before CodeQL init retry
+        if: steps.init-codeql.outcome == 'failure'
+        run: sleep 30
+
+      - name: Retry Initialize CodeQL after GitHub API outage
+        id: init-codeql-retry
+        if: steps.init-codeql.outcome == 'failure'
+        continue-on-error: true
+        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      - name: Wait before CodeQL init second retry
+        if: steps.init-codeql.outcome == 'failure' && steps.init-codeql-retry.outcome == 'failure'
+        run: sleep 60
+
+      - name: Second retry Initialize CodeQL after GitHub API outage
+        id: init-codeql-retry-2
+        if: steps.init-codeql.outcome == 'failure' && steps.init-codeql-retry.outcome == 'failure'
         uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
 
       - name: Perform CodeQL Analysis
+        if: >-
+          steps.init-codeql.outcome == 'success' ||
+          steps.init-codeql-retry.outcome == 'success' ||
+          steps.init-codeql-retry-2.outcome == 'success'
         uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           category: "/language:${{ matrix.language }}-merge"

AGENTS.md

@@ -5,3 +5,4 @@
 
 Materialize accepts only exact SHA-256 pins or a bounded relative `-r` include (no `.`/`..`); a lone `--require-hashes` directive is not trust evidence. See [`docs/doctoring/hourly-nvidia-nim-autofix.md`](docs/doctoring/hourly-nvidia-nim-autofix.md).
 Conflict-scope roots fail closed when the immediate parent directory is a symbolic link.
+Cursor Cloud Agents cannot complete Figma MCP OAuth against `https://mcp.figma.com/mcp` (allowlisted-client catalog; Cloud unsupported). Desktop/CLI remain the MCP path. Cloud Agents that must read Figma files store `FIGMA_ACCESS_TOKEN`, run `python3 scripts/ci/figma_rest_auth.py`, then `python3 scripts/ci/figma_rest_file.py <file-key-or-url>`. See [`docs/doctoring/figma-cloud-agent-mcp-auth.md`](docs/doctoring/figma-cloud-agent-mcp-auth.md).

ARCHITECTURE.md

@@ -90,6 +90,33 @@ sequenceDiagram
 - Rust remains the psychometric arithmetic owner. Repair never substitutes
   Python for scoring math.
 
+## Figma Cloud Agent REST fallback
+
+```mermaid
+flowchart TD
+  Need["Cloud Agent needs Figma"]
+  Mcp{"Figma MCP OAuth available?"}
+  Desktop["Desktop / CLI: Settings → Tools and MCP → Figma → Connect"]
+  Token{"FIGMA_ACCESS_TOKEN set?"}
+  Whoami["python3 scripts/ci/figma_rest_auth.py"]
+  File["python3 scripts/ci/figma_rest_file.py file-key-or-url"]
+  Mint["Mint a Figma PAT with file_content:read and store the secret"]
+
+  Need --> Mcp
+  Mcp -->|"yes, Desktop/CLI"| Desktop
+  Mcp -->|"no, Cloud Agent"| Token
+  Token -->|"no"| Mint
+  Mint --> Whoami
+  Token -->|"yes"| Whoami
+  Whoami --> File
+```
+
+Cloud Agents never complete Figma MCP OAuth. Whoami alone is not file
+read. The file helper allowlists the key and node ids, opens a
+pinned `HTTPSConnection("api.figma.com")`, and prints a token-free JSON
+outline. See
+[`docs/doctoring/figma-cloud-agent-mcp-auth.md`](docs/doctoring/figma-cloud-agent-mcp-auth.md).
+
 ## Quality gates
 
 `scripts/ci/` ships with 100% statement/branch coverage and 100% docstrings.
@@ -106,5 +133,7 @@ tests pin workflow structure and governance prose so drift fails closed.
   contract.
 - [`docs/doctoring/hourly-nvidia-nim-autofix.md`](docs/doctoring/hourly-nvidia-nim-autofix.md)
   — current increment's repair-worker decision and APA 7th citations.
+- [`docs/doctoring/figma-cloud-agent-mcp-auth.md`](docs/doctoring/figma-cloud-agent-mcp-auth.md)
+  — Cloud Agent Figma MCP boundary and REST file-read fallback.
 - [`docs/doctoring/fast-mlsirm-hourly-review-caller.md`](docs/doctoring/fast-mlsirm-hourly-review-caller.md)
   — product-specific psychometric repair heartbeat and scientific gates.

CHANGELOG.md

@@ -8,6 +8,7 @@ Semantic Versioning where the repository publishes a release.
 
 ### Added
 
+- Added Cloud Agent Figma REST helpers `scripts/ci/figma_rest_auth.py` and `scripts/ci/figma_rest_file.py` that verify `FIGMA_ACCESS_TOKEN` against pinned `GET /v1/me` and then read an allowlisted `GET /v1/files/{key}` (optional `/nodes` or `/images`) so whoami is not treated as file read.
 - Added a trusted pull-request comment router for `@cwl-noema-review` and review-only `@opencode-agent` dispatches, with an organization sweep, exact-head receipts, repository allowlisting, fixed runners, immutable checkout pins, and a permanent 100% statement/branch/docstring quality gate.
 - Added exact-base `uv.lock` materialization that reconstructs standalone nested projects with a checksum-pinned official `uv` exporter, isolated frozen/offline execution, strict exact-pin and SHA-256 output validation, and complete Python 3.10/3.14 quality evidence.
 - Added a permanent exact-head contract workflow for the hourly review-repair scheduler, immutable reusable-workflow source, NVIDIA NIM model boundary, credential isolation, and fail-closed unattended-agent permissions.
@@ -26,6 +27,7 @@ Semantic Versioning where the repository publishes a release.
 
 ### Fixed
 
+- Retried CodeQL `init` up to three times (30s then 60s) after a GitHub feature-enablement API 503 (`No server is currently available`) so a brief outage does not fail the required compatibility analysis.
 - Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context.
 - Refused a conflict-scope repository root whose immediate parent is a symbolic link, so a swapped parent cannot redirect the canonical worktree after the last-component check (CWE-367).
 - Bounded the Strix quality self-test's deterministic timeout fixtures to 3-second process and 5-second fake-sleep budgets so exact-head policy evidence completes inside the existing job limit without changing production Strix scanner timeouts, providers, credentials, or review semantics.
@@ -39,6 +41,7 @@ Semantic Versioning where the repository publishes a release.
 
 ### Security
 
+- Pin Figma REST calls to `http.client.HTTPSConnection("api.figma.com")`, allow only the `X-Figma-Token` header, allowlist file keys and node ids, and cap whoami/file bodies so `file://`, `Host` retargeting, and path traversal cannot leave the pinned origin.
 - Reject `.github/` and `scripts/ci/` from review-thread-derived autofix path authority so an untrusted inline reviewer cannot authorize the write-capable repair agent to modify workflows, CODEOWNERS, actions, scheduler code, or CI helpers that govern its own control plane.
 - Require the model-write snapshot and exact-path allowlist to remain outside the pull-request worktree, checking both absolute and resolved locations so repository-local controls and outside-looking symlinks resolving into the repository fail closed before they can authorize or verify model changes.
 - Snapshot the complete pre-model worktree for ordinary and conflict repair and reject every model-caused created, deleted, modified, mode-changed, retargeted, ignored, dangling, directory-backed, external-link, metadata-race, or out-of-scope path before staging or push.
@@ -55,6 +58,7 @@ Semantic Versioning where the repository publishes a release.
 
 ### Documentation
 
+- Added an APA 7 doctoring record for the Cloud Agent Figma MCP OAuth boundary, REST whoami and file-read helpers, operator next-action contract, and Figma file-endpoint citations.
 - Added an APA 7 doctoring record for conflict-control evidence isolation, including the Strix-reported trust-boundary failure, test-first remediation, canonical-path rule, operator contract, rollback, MITRE CWE-22, and current GitHub Actions secure-use guidance.
 - Added operator and APA 7 doctoring records for the hourly cadence, immutable source identity, NVIDIA NIM provider and secret boundary, high-reasoning Mistral Small 4 writer, model-process credential isolation, modular MSA ownership, product-specific caller activation, verification contract, and rollback.
 - Added DiskSage operational documentation for the hourly RCA loop, bounded retry cadence, permission model, standalone and MSA reuse, verification, rollback, and APA 7 references.

CLAUDE.md

@@ -128,3 +128,8 @@ repeatable compile command.
   cross-repo references as `owner/repo#num` or full URLs; durable knowledge in the repo/Project, not
   private memory; one roadmap phase at a time) are defined in `docs/CWL-MASTER-CONTEXT.md` §7 and
   apply here.
+- **Figma on Cloud Agents is REST-only.** Do not retry MCP Connect against
+  `https://mcp.figma.com/mcp`. Store `FIGMA_ACCESS_TOKEN`, run
+  `python3 scripts/ci/figma_rest_auth.py`, then
+  `python3 scripts/ci/figma_rest_file.py <file-key-or-url>`. Desktop/CLI keep
+  the full MCP path. See `docs/doctoring/figma-cloud-agent-mcp-auth.md`.

docs/CWL-MASTER-CONTEXT.md

@@ -129,6 +129,7 @@ GitHub **Project #1** is the shared source of truth. Structure: real **Issues**
 - **BLOCKER B1**: org GitHub Actions effectively HALTED (~86 queued, ~0 in_progress org-wide) — likely the Actions monthly SPENDING CAP. Blocks ALL PR checks/merges + the Cloudflare DNS run (nameservers). Fix (org-admin): raise the Actions spending limit OR add a self-hosted runner. Nothing merges until then.
 - **Decisions pending**: (D1) Code Security enablement vs the CodeQL-only code_scanning ruleset (osv/trivy/scorecard SARIF upload) — a private repo needs GHAS seats; reconcile or make those checks non-required. (D2) trivy `limit-severities-for-sarif: true` (gate only CRITICAL/HIGH) — held pending the user's strict-security preference.
 - **Built this session, PR-open, awaiting merge (B1)**: see Project #1 PRs (contextual-orchestrator cost/routing #46 + naruon#973; pg-llm-batch; keyverse Keycloak; inkspan; SBOM #361; opencode auto-retry #360; Strix neutral #349 + emit #358; appguardrail collector #254; auto-rebase #357; noema #359/naruon#970; PDF-DOM naruon#965/newsdom#300; SDP #11; fast-mlsirm GPGPU #109; scopeweave #284/naruon#971; fuzzing 10 PRs (found+fixed 2 real naruon bugs); Cloudflare DNS/Pages #362; this protocol #363; planning #974). Human step: report the mapasevo21 malware file (github user-attachments) to GitHub Abuse; rotate the xtrmLLMBatchPython-leaked keys; the org-admin runner/decisions above.
+- **Figma MCP on Cloud Agents (2026-08-16)**: `https://mcp.figma.com/mcp` is OAuth-only and not supported in Cursor Cloud Agents / Automations. Desktop IDE and CLI remain the MCP path. Cloud Agents that must read Figma files store `FIGMA_ACCESS_TOKEN`, run `python3 scripts/ci/figma_rest_auth.py`, then `python3 scripts/ci/figma_rest_file.py <file-key-or-url>`. See `docs/doctoring/figma-cloud-agent-mcp-auth.md`.
 
 ---
 *Keep this current. Update Project #1 as the live tracker; this file is the narrative brief a fresh agent reads to reconstruct the whole picture.*