Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(codex): republish allowlist ConfigMap after grant changes
Alfredo Lopezb42cfb199779
diff --git a/.agents/skills/minikube-t0-t1-t2/SKILL.md b/.agents/skills/minikube-t0-t1-t2/SKILL.mdindex 03f6a3b6c..d95eaff8f 100644--- a/.agents/skills/minikube-t0-t1-t2/SKILL.md+++ b/.agents/skills/minikube-t0-t1-t2/SKILL.md@@ -9,4 +9,5 @@ The canonical copy of this skill lives at`.cursor/skills/minikube-t0-t1-t2/SKILL.md` (workflow, checklist, decisiontree) with `.cursor/skills/minikube-t0-t1-t2/reference.md` (anti-patterns,failure codes, recovery). Read and follow those files; do not duplicate their-content here.+content here. Control UI / Desktop port-forwards are documented in+`.cursor/skills/minikube-t0-t1-t2/SKILL.md` Step 0 and `AGENTS.md`.diff --git a/.cursor/rules/minikube-t0-t1-t2.mdc b/.cursor/rules/minikube-t0-t1-t2.mdcindex dda3388a8..7fc35ff30 100644--- a/.cursor/rules/minikube-t0-t1-t2.mdc+++ b/.cursor/rules/minikube-t0-t1-t2.mdc@@ -34,6 +34,26 @@ repository — never mix its PRs or clusters into this lane.- Health/Playwright are opt-in via `T2_HEALTHCHECK_COMMAND` /`T2_PLAYWRIGHT_COMMAND` (`T2_REQUIRE_PLAYWRIGHT=true` refuses `NOT_RUN`).+## Branch-profile UI port-forwards++First-hand (do not search): `.local-notes/minikube-profiles/branch.mk`.+Implementation: `branch-profile.sh` in that directory. HARD DENY:+`ls`/`cat` `~/.cache/clerum/minikube-profiles/`.++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-health+```++Host-side hold for Control UI / Desktop. Profile-owned random ports only+(never `:3000` / `:8090`). Run on the host, not a sandboxed agent shell.+`make minikube-pf-all-bg` is a gate refresh only — it does not replace+`branch-profile-pf`. Do not kill this lane's forwards.+`branch-profile-pf-health` stops PFs on EXIT. Inner `pre-gate-sync` may use+`--skip-port-forwards`; never pass that globally into `make minikube-t2`.+## Profile and evidence- Reuse the owned `MINIKUBE_PROFILE`; do not create a new profile because HEADdiff --git a/.cursor/skills/minikube-t0-t1-t2/SKILL.md b/.cursor/skills/minikube-t0-t1-t2/SKILL.mdindex c5e4d876e..f1f9bfada 100644--- a/.cursor/skills/minikube-t0-t1-t2/SKILL.md+++ b/.cursor/skills/minikube-t0-t1-t2/SKILL.md@@ -28,6 +28,14 @@ Before running anything, verify ALL of these:Never change the global kubectl current-context.- [ ] Never read `~/.cache/clerum/minikube-profiles/` directly (HARD DENY —it holds private profile state). The harness reads it for you.+- [ ] Hold Control UI / Desktop PFs on the host via the first-hand helper+ (do not search `.local-notes/` for it):+ `MINIKUBE_PROFILE=<owned-profile> make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf`+ then `branch-profile-health`. Implementation:+ `.local-notes/minikube-profiles/branch-profile.sh`. Do not replace+ that hold with `make minikube-pf-all-bg`. Do not start UI PFs from a+ sandboxed agent shell. Do not kill this lane's `branch-profile-pf`.+ `branch-profile-pf-health` stops PFs on EXIT — not a lasting hold.## Step 1 — Plan (read-only)diff --git a/.cursor/skills/minikube-t0-t1-t2/reference.md b/.cursor/skills/minikube-t0-t1-t2/reference.mdindex 052c58985..c304bcf7b 100644--- a/.cursor/skills/minikube-t0-t1-t2/reference.md+++ b/.cursor/skills/minikube-t0-t1-t2/reference.md@@ -15,6 +15,11 @@ Companion to `SKILL.md`. Source of truth: `scripts/minikube/t2.sh`,already green on the same HEAD — use `make minikube-t2-runtime`.- **Do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.** Private profilestate (ports, pids, markers). The harness is the only reader.+- **Do not hunt for UI port-forwards.** First-hand hold:+ `MINIKUBE_PROFILE=<owned-profile> make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf`+ (implementation `branch-profile.sh` beside it). Run on the host, not a+ sandboxed agent shell. `make minikube-pf-all-bg` is a gate refresh only.+ `branch-profile-pf-health` stops PFs on EXIT. Never shared `:3000`/`:8090`.- **Do not invent `ADMIN_PASSWORD`** or any credential. When a product E2Eneeds it, load it from the primary checkout `.env`; never echo it.- **Do not reset PVCs** outside the explicit `T2_RESET_PVC=true` +@@ -51,7 +56,7 @@ Companion to `SKILL.md`. Source of truth: `scripts/minikube/t2.sh`,| --- | --- | --- || `BOOTSTRAP_REQUIRED` | Profile missing/uninitialized, or the planner produced no transition. Standalone preflight refuses to bootstrap. | Run `make minikube-t2` — its internal planner (`T2_PLAN_MODE=true`) makes `full-bootstrap` reachable and runs the supported setup with `IMAGE_SOURCE=local`. || `HEAD_MARKER_MISMATCH` | Pre-gate marker does not match this worktree/HEAD; the final T2 preflight selected something other than `already-synced`. | Re-run `make minikube-t2` on this HEAD so `pre-gate-sync` updates the marker. Never hand-edit the marker. |-| `PORT_FORWARD_CONFLICT` | A port-forward for this profile is owned by a process not recorded for it (or not a real `kubectl`). | Identify the foreign owner; if it belongs to another lane, stop. Restart forwards via `scripts/minikube/pf-all-stack.sh` for this profile only. |+| `PORT_FORWARD_CONFLICT` | A port-forward for this profile is owned by a process not recorded for it (or not a real `kubectl`). | Identify the foreign owner; if it belongs to another lane, stop. Do not kill this lane's `branch-profile-pf`. Restore UI PFs with `make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf`. || `PROFILE_BUSY` | Profile lock held. Live owner PID → genuinely busy. No valid owner PID → orphaned lock. | Live owner: wait or coordinate; never remove. Orphan: verify no T2 process owns the profile, then remove ONLY `$T2_LOCK_ROOT/<profile>.lock` and retry. Never remove the lock root. || `DEVELOPMENT_SCOPE_REQUIRED` | Preflight/final preflight failed a precondition, or T2-only mode was attempted without `already-synced`. | Repair the first reported condition; if T2-only was refused, run full `make minikube-t2`. || `ZERO_TESTS_EXECUTED` | A lane was configured off or executed nothing (including a required-but-missing Playwright journey). | Re-run with the lane enabled, or supply the required `T2_PLAYWRIGHT_COMMAND`. |diff --git a/AGENTS.md b/AGENTS.mdindex a769985a8..424ce08ef 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -23,6 +23,27 @@ also required when the selected profile is missing or unhealthy. Never useshared fixed localhost ports for branch-owned profiles; use the profile-ownedrandom port mapping already recorded for that profile.+## Branch-profile UI port-forwards++First-hand entry point (gitignored helper at repo root — do not search for+it). Implementation is `.local-notes/minikube-profiles/branch-profile.sh`.+Do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf++MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-health+```++This is the host-side hold for Control UI / Desktop. Run it on the host, not+from a sandboxed agent shell. `make minikube-pf-all-bg` is a gate refresh+only and must not replace `branch-profile-pf`. Do not kill this lane's+forwards. `branch-profile-pf-health` starts then stops PFs on EXIT — do not+use it as the lasting hold. Inner `pre-gate-sync` may use+`--skip-port-forwards`; never pass that globally into `make minikube-t2`.+## Incremental local image updatesFor a service-only change in an already healthy profile, rebuild and restartdiff --git a/CLAUDE.md b/CLAUDE.mdindex 717a2c1ab..06f86fa3f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -12,6 +12,10 @@ The local Minikube T0/T1/T2 contract is development-only. Follow thecanonical `make minikube-t2-preflight`, `make minikube-t2`, and`make minikube-t2-runtime` entry points and the ownership, secret-safety, andevidence rules in `AGENTS.md` and `docs/testing/minikube-t2-runbook.md`.+Hold Control UI / Desktop port-forwards on the host with+`make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf`+(`AGENTS.md` § Branch-profile UI port-forwards). Do not search for that+helper and do not use `make minikube-pf-all-bg` as the hold.`make minikube-t2-preflight` is a planner, not a lane verdict. A T2 verdict isproduced only by the final exact-head preflight inside `make minikube-t2` (or`make minikube-t2-runtime` after T0 and T1 are already green on the same HEAD).diff --git a/control-api/package-lock.json b/control-api/package-lock.jsonindex 29d4d00c4..0343b3028 100644--- a/control-api/package-lock.json+++ b/control-api/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-api",- "version": "0.1.496",+ "version": "0.1.497","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-api",- "version": "0.1.496",+ "version": "0.1.497","dependencies": {"@clerum/display-field": "file:../packages/display-field","@clerum/image-policy": "file:../packages/image-policy",diff --git a/control-api/package.json b/control-api/package.jsonindex ad4671e58..0fa0dfca6 100644--- a/control-api/package.json+++ b/control-api/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-api",- "version": "0.1.496",+ "version": "0.1.497","description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets","main": "dist/main.js","engines": {diff --git a/control-api/src/observability/metrics.ts b/control-api/src/observability/metrics.tsindex 65a65fbc4..a1155e5a9 100644--- a/control-api/src/observability/metrics.ts+++ b/control-api/src/observability/metrics.ts@@ -531,9 +531,9 @@ export function recordGovernedTraceOperationalError(}// ─── LLM allowlist ConfigMap materialization (spec §3-R3.4 / V7) ─────────// Increments when the `clerum-llm-allowed-models` ConfigMap write fails after-// its short retry — either during a CRUD mutation (phase=mutation, the route-// then answers 503) or during the non-fatal boot reconcile (phase=boot). A-// rate > 0 means Postgres and the delivered ConfigMap have drifted.+// its short retry — LLM Models CRUD / Codex grant mutations (phase=mutation)+// or the non-fatal boot reconcile (phase=boot). A rate > 0 means Postgres and+// the delivered ConfigMap have drifted.export const llmAllowlistConfigMapWriteFailuresTotal = getOrCreateCounter({name: 'clerum_llm_allowlist_configmap_write_failures_total',help: 'Count of failed clerum-llm-allowed-models ConfigMap writes, labelled by phase.',diff --git a/control-api/src/routes/admin/codexSubscription.ts b/control-api/src/routes/admin/codexSubscription.tsindex bc5c03bd0..661df0f00 100644--- a/control-api/src/routes/admin/codexSubscription.ts+++ b/control-api/src/routes/admin/codexSubscription.ts@@ -5,6 +5,7 @@ import { asyncHandler } from '../../http/asyncHandler.js'import type { K8sGateway } from '../../k8s.js'import { deriveOAuthEncryptionKey } from '../../oauth/encryption.js'import { rootLogger } from '../../observability/logger.js'+import { llmAllowlistConfigMapWriteFailuresTotal } from '../../observability/metrics.js'import {type CodexCatalogTransport,createCodexCatalogTransportFromEnv,@@ -36,6 +37,7 @@ import {isPublicCodexCliClient,resolveCodexControlUiBaseUrl,} from '../../services/codexSubscriptionRedirectUri.js'+import { publishAllowedModelsConfigMapAfterGrantChange } from '../../services/llmAllowedModelsConfigMap.js'import {adminCodexReadRateLimits,adminCodexWriteRateLimits,@@ -151,6 +153,43 @@ export function createAdminCodexSubscriptionRouter(.filter(host => host.name)}+ async function publishRuntimeAllowlist(): Promise<void> {+ await publishAllowedModelsConfigMapAfterGrantChange(gateway?.llmAllowedModelsConfigMap())+ }++ async function publishRuntimeAllowlistBestEffort(): Promise<void> {+ try {+ await publishRuntimeAllowlist()+ } catch (err) {+ llmAllowlistConfigMapWriteFailuresTotal.inc({ phase: 'mutation' })+ log.error(+ { err, event: 'codex_allowed_models_cm_write_failed' },+ 'Codex grant change saved but the runtime ConfigMap was not updated'+ )+ }+ }++ async function publishRuntimeAllowlistOrFail(res: {+ status: (n: number) => { json: (body: unknown) => void }+ }): Promise<boolean> {+ try {+ await publishRuntimeAllowlist()+ return false+ } catch (err) {+ llmAllowlistConfigMapWriteFailuresTotal.inc({ phase: 'mutation' })+ log.error(+ { err, event: 'codex_allowed_models_cm_write_failed' },+ 'Codex grant change saved but the runtime ConfigMap was not updated'+ )+ res.status(503).json({+ error: 'configmap_write_failed',+ message:+ 'the grant change was saved but the ConfigMap could not be updated; runtime hosts still see the previous snapshot — retry or it will reconcile on the next change/boot',+ })+ return true+ }+ }+async function withAssignedHosts<T extends { connectionKey: string }>(connection: T,hosts?: Array<{ metadata?: { name?: string }; spec?: unknown }> | null@@ -214,6 +253,7 @@ export function createAdminCodexSubscriptionRouter(oauthDeps(req, resolveBrowserRedirectUri(req), keyFromReq(req)),state)+ if (result.status === 'connected') await publishRuntimeAllowlistBestEffort()res.status(200).json(result)} catch (err) {sendOAuthError(res, err)@@ -253,6 +293,7 @@ export function createAdminCodexSubscriptionRouter(const synced = await syncCodexSubscriptionCatalog(db, catalogTransport, secrets.accessToken, {connectionKey,})+ if (await publishRuntimeAllowlistOrFail(res)) returnres.status(200).json({outcome: synced.outcome,added: synced.added,@@ -270,6 +311,7 @@ export function createAdminCodexSubscriptionRouter(const connection = await revokeCodexSubscription(oauthDeps(req, resolveBrowserRedirectUri(req), keyFromReq(req)))+ if (await publishRuntimeAllowlistOrFail(res)) returnres.status(200).json(await withAssignedHosts(connection))} catch (err) {sendOAuthError(res, err)diff --git a/control-api/src/routes/auth/codexSubscription.ts b/control-api/src/routes/auth/codexSubscription.tsindex b08ef039d..d37eeb4a3 100644--- a/control-api/src/routes/auth/codexSubscription.ts+++ b/control-api/src/routes/auth/codexSubscription.ts@@ -2,8 +2,10 @@ import { Router } from 'express'import { config } from '../../config.js'import { pool } from '../../db.js'import { asyncHandler } from '../../http/asyncHandler.js'+import type { K8sGateway } from '../../k8s.js'import { deriveOAuthEncryptionKey } from '../../oauth/encryption.js'import { rootLogger } from '../../observability/logger.js'+import { llmAllowlistConfigMapWriteFailuresTotal } from '../../observability/metrics.js'import {type CodexOAuthDeps,CodexSubscriptionOAuthError,@@ -14,6 +16,7 @@ import {buildCodexBrowserReturnLocation,resolveCodexCallbackControlUiBaseUrl,} from '../../services/codexSubscriptionRedirectUri.js'+import { publishAllowedModelsConfigMapAfterGrantChange } from '../../services/llmAllowedModelsConfigMap.js'import { codexOAuthCallbackRateLimits } from '../workflows/shared/rateLimit.js'const log = rootLogger.child({ module: 'auth-codex-subscription' })@@ -49,7 +52,7 @@ function redirectToCodexSurface(res.redirect(303, buildCodexBrowserReturnLocation(outcome))}-export function createAuthCodexSubscriptionRouter(): Router {+export function createAuthCodexSubscriptionRouter(gateway?: K8sGateway): Router {const router = Router()router.get(@@ -60,6 +63,15 @@ export function createAuthCodexSubscriptionRouter(): Router {const state = typeof req.query.state === 'string' ? req.query.state : ''try {await handleCodexBrowserCallback(oauthDeps(req), { code, state })+ try {+ await publishAllowedModelsConfigMapAfterGrantChange(gateway?.llmAllowedModelsConfigMap())+ } catch (err) {+ llmAllowlistConfigMapWriteFailuresTotal.inc({ phase: 'mutation' })+ log.error(+ { err, event: 'codex_allowed_models_cm_write_failed' },+ 'Codex callback persisted but the runtime ConfigMap was not updated'+ )+ }redirectToCodexSurface(res, 'connected')} catch (err) {if (err instanceof CodexSubscriptionOAuthError) {diff --git a/control-api/src/routes/auth/index.ts b/control-api/src/routes/auth/index.tsindex b11cbf81c..4dd900bcc 100644--- a/control-api/src/routes/auth/index.ts+++ b/control-api/src/routes/auth/index.ts@@ -7,7 +7,7 @@ import { createAuthRecipeOauthRoutes } from './recipe-oauth/index.js'export function createAuthRoutes(gateway: K8sGateway): Router {const router = Router()router.use(createAuthMcpHostRoutes())- router.use(createAuthCodexSubscriptionRouter())+ router.use(createAuthCodexSubscriptionRouter(gateway))router.use(createAuthRecipeOauthRoutes(gateway))return router}diff --git a/control-api/src/services/llmAllowedModelsConfigMap.ts b/control-api/src/services/llmAllowedModelsConfigMap.tsindex 806ee6999..27e75cbe5 100644--- a/control-api/src/services/llmAllowedModelsConfigMap.ts+++ b/control-api/src/services/llmAllowedModelsConfigMap.ts@@ -110,6 +110,22 @@ export interface AllowedModelsConfigMapMaterializer {materialize(db?: DbClient): Promise<void>}+/**+ * Push the current Postgres allowlist + per-grant Codex snapshot to the+ * runtime ConfigMap. Catalog sync, revoke, and a successful OAuth persist+ * must call this — mcp-host/HCC never read Postgres, and a cluster in+ * operation cannot wait for the next control-api boot.+ *+ * Missing writer is a no-op so unit tests without a K8s gateway stay local.+ */+export async function publishAllowedModelsConfigMapAfterGrantChange(+ writer: AllowedModelsConfigMapMaterializer | undefined+): Promise<'published' | 'skipped'> {+ if (!writer) return 'skipped'+ await writer.materialize()+ return 'published'+}+/*** Build the ConfigMap `data` and its content hash from grouped enabled rows.* Provider keys and per-provider model arrays are already deterministicallydiff --git a/control-api/test/routes.admin.codexSubscription.test.ts b/control-api/test/routes.admin.codexSubscription.test.tsindex d90339470..3ad98946d 100644--- a/control-api/test/routes.admin.codexSubscription.test.ts+++ b/control-api/test/routes.admin.codexSubscription.test.ts@@ -13,6 +13,11 @@ const oauth = vi.hoisted(() => ({revoke: vi.fn(),}))+const catalog = vi.hoisted(() => ({+ loadSecrets: vi.fn(),+ sync: vi.fn(),+}))+vi.mock('../src/services/codexSubscriptionOAuth.js', async () => {const actual = await vi.importActual('../src/services/codexSubscriptionOAuth.js')return {@@ -26,6 +31,22 @@ vi.mock('../src/services/codexSubscriptionOAuth.js', async () => {}})+vi.mock('../src/services/codexSubscriptionConnection.js', async () => {+ const actual = await vi.importActual('../src/services/codexSubscriptionConnection.js')+ return {+ ...actual,+ loadCodexSubscriptionSecrets: catalog.loadSecrets,+ }+})++vi.mock('../src/services/codexSubscriptionCatalog.js', async () => {+ const actual = await vi.importActual('../src/services/codexSubscriptionCatalog.js')+ return {+ ...actual,+ syncCodexSubscriptionCatalog: catalog.sync,+ }+})+vi.mock('../src/db.js', () => ({pool: { query: vi.fn() },}))@@ -38,7 +59,17 @@ const { createCodexCatalogTransportFromEnv } =const { createAdminCodexSubscriptionRouter } =await import('../src/routes/admin/codexSubscription.js')-function makeAuthedApp(gateway?: { listResource: ReturnType<typeof vi.fn> }) {+function makeGateway(materialize: () => Promise<void> = async () => {}) {+ return {+ listResource: vi.fn().mockResolvedValue([]),+ llmAllowedModelsConfigMap: () => ({ materialize }),+ }+}++function makeAuthedApp(gateway?: {+ listResource: ReturnType<typeof vi.fn>+ llmAllowedModelsConfigMap?: () => { materialize: () => Promise<void> }+}) {const app = express()app.use(express.json())app.use((req: Request & { adminAuth?: { sub: string } }, _res: Response, next: NextFunction) => {@@ -93,6 +124,8 @@ describe('admin Codex subscription routes', () => {config.codexOAuthClientId = originalClientIdconfig.controlUiBaseUrl = originalControlUiBaseUrlfor (const fn of Object.values(oauth)) fn.mockReset()+ catalog.loadSecrets.mockReset()+ catalog.sync.mockReset()})it('returns 404 while the feature flag is off', async () => {@@ -279,4 +312,115 @@ describe('admin Codex subscription routes', () => {expect(res.body).toEqual({ error: 'connection_mismatch' })assertNoLeak(res.body)})++ it('publishes the runtime ConfigMap after a catalog sync', async () => {+ const materialize = vi.fn(async () => {})+ catalog.loadSecrets.mockResolvedValue({ accessToken: 'access-secret' })+ catalog.sync.mockResolvedValue({+ outcome: 'ready',+ added: 8,+ refreshed: 0,+ staled: 0,+ connection: { connectionKey: 'codex-aaa', status: 'connected', catalogRevision: 1 },+ })+ const res = await request(makeAuthedApp(makeGateway(materialize))).post(+ '/admin/llm/providers/codex-subscription/connections/codex-aaa/catalog/sync'+ )+ expect(res.status).toBe(200)+ expect(res.body.added).toBe(8)+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.body)+ })++ it('returns 503 when catalog sync cannot publish the runtime ConfigMap', async () => {+ const materialize = vi.fn(async () => {+ throw new Error('apiserver down')+ })+ catalog.loadSecrets.mockResolvedValue({ accessToken: 'access-secret' })+ catalog.sync.mockResolvedValue({+ outcome: 'ready',+ added: 8,+ refreshed: 0,+ staled: 0,+ connection: { connectionKey: 'codex-aaa', status: 'connected', catalogRevision: 1 },+ })+ const res = await request(makeAuthedApp(makeGateway(materialize))).post(+ '/admin/llm/providers/codex-subscription/catalog/sync'+ )+ expect(res.status).toBe(503)+ expect(res.body.error).toBe('configmap_write_failed')+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.body)+ })++ it('publishes the runtime ConfigMap after revoke', async () => {+ const materialize = vi.fn(async () => {})+ oauth.revoke.mockResolvedValue({+ connectionKey: 'codex-aaa',+ status: 'revoked',+ credentialRevision: 3,+ })+ const res = await request(makeAuthedApp(makeGateway(materialize))).post(+ '/admin/llm/providers/codex-subscription/connections/codex-aaa/revoke'+ )+ expect(res.status).toBe(200)+ expect(res.body.status).toBe('revoked')+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.body)+ })++ it('returns 503 when revoke cannot publish the runtime ConfigMap', async () => {+ const materialize = vi.fn(async () => {+ throw new Error('apiserver down')+ })+ oauth.revoke.mockResolvedValue({+ connectionKey: 'deployment-default',+ status: 'revoked',+ credentialRevision: 9,+ })+ const res = await request(makeAuthedApp(makeGateway(materialize))).post(+ '/admin/llm/providers/codex-subscription/revoke'+ )+ expect(res.status).toBe(503)+ expect(res.body.error).toBe('configmap_write_failed')+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.body)+ })++ it('publishes the runtime ConfigMap after a connected device poll', async () => {+ const materialize = vi.fn(async () => {})+ oauth.pollDevice.mockResolvedValue({ status: 'connected', connectionKey: 'codex-aaa' })+ const res = await request(makeAuthedApp(makeGateway(materialize))).get(+ '/admin/llm/providers/codex-subscription/connections/codex-aaa/device/poll'+ )+ expect(res.status).toBe(200)+ expect(res.body.status).toBe('connected')+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.body)+ })++ it('keeps a connected device poll at 200 when ConfigMap publish fails', async () => {+ const materialize = vi.fn(async () => {+ throw new Error('apiserver down')+ })+ oauth.pollDevice.mockResolvedValue({ status: 'connected', connectionKey: 'codex-aaa' })+ const res = await request(makeAuthedApp(makeGateway(materialize))).get(+ '/admin/llm/providers/codex-subscription/device/poll'+ )+ expect(res.status).toBe(200)+ expect(res.body.status).toBe('connected')+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.body)+ })++ it('does not publish the ConfigMap while a device poll is still pending', async () => {+ const materialize = vi.fn(async () => {})+ oauth.pollDevice.mockResolvedValue({ status: 'pending' })+ const res = await request(makeAuthedApp(makeGateway(materialize))).get(+ '/admin/llm/providers/codex-subscription/device/poll'+ )+ expect(res.status).toBe(200)+ expect(materialize).not.toHaveBeenCalled()+ assertNoLeak(res.body)+ })})diff --git a/control-api/test/routes.auth.codexSubscriptionCallback.test.ts b/control-api/test/routes.auth.codexSubscriptionCallback.test.tsindex e1afdf150..ac9262b49 100644--- a/control-api/test/routes.auth.codexSubscriptionCallback.test.ts+++ b/control-api/test/routes.auth.codexSubscriptionCallback.test.ts@@ -31,15 +31,18 @@ vi.mock('../src/services/rateLimiterService.js', () => ({vi.mock('../src/observability/metrics.js', () => ({rateLimitHitsTotal: { inc: vi.fn() },+ llmAllowlistConfigMapWriteFailuresTotal: { inc: vi.fn() },}))const { config } = await import('../src/config.js')const { createAuthCodexSubscriptionRouter } =await import('../src/routes/auth/codexSubscription.js')-function makeApp() {+function makeApp(gateway?: {+ llmAllowedModelsConfigMap: () => { materialize: () => Promise<void> }+}) {const app = express()- app.use(createAuthCodexSubscriptionRouter())+ app.use(createAuthCodexSubscriptionRouter(gateway as never))return app}@@ -86,6 +89,44 @@ describe('GET /auth/codex-subscription/callback', () => {assertNoLeak(res.text)})+ it('publishes the runtime ConfigMap after a successful callback', async () => {+ const materialize = vi.fn(async () => {})+ oauth.callback.mockResolvedValue({+ status: 'connected',+ accountFingerprint: 'fp',+ credentialRevision: 1,+ })+ const res = await request(makeApp({ llmAllowedModelsConfigMap: () => ({ materialize }) }))+ .get('/auth/codex-subscription/callback')+ .query({ code: 'code-1', state: 'state-1' })+ expect(res.status).toBe(303)+ expect(res.headers.location).toBe(+ '/llm-models/providers/codex-subscription?codex_oauth=connected'+ )+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.headers.location)+ })++ it('still redirects when ConfigMap publish fails after a successful callback', async () => {+ const materialize = vi.fn(async () => {+ throw new Error('apiserver down')+ })+ oauth.callback.mockResolvedValue({+ status: 'connected',+ accountFingerprint: 'fp',+ credentialRevision: 1,+ })+ const res = await request(makeApp({ llmAllowedModelsConfigMap: () => ({ materialize }) }))+ .get('/auth/codex-subscription/callback')+ .query({ code: 'code-1', state: 'state-1' })+ expect(res.status).toBe(303)+ expect(res.headers.location).toBe(+ '/llm-models/providers/codex-subscription?codex_oauth=connected'+ )+ expect(materialize).toHaveBeenCalledTimes(1)+ assertNoLeak(res.headers.location)+ })+it('redirects callback replay errors back to the Codex surface', async () => {oauth.callback.mockRejectedValue(new CodexSubscriptionOAuthError('state_replayed', 'replay'))const res = await request(app)diff --git a/control-api/test/services.llmAllowedModelsConfigMap.test.ts b/control-api/test/services.llmAllowedModelsConfigMap.test.tsindex 09ab3112d..cc5d6e37a 100644--- a/control-api/test/services.llmAllowedModelsConfigMap.test.ts+++ b/control-api/test/services.llmAllowedModelsConfigMap.test.ts@@ -12,6 +12,7 @@ import {buildCodexReadinessAnnotations,buildConfigMapData,mapCodexConnectionStatusForSnapshot,+ publishAllowedModelsConfigMapAfterGrantChange,} from '../src/services/llmAllowedModelsConfigMap.js'function fakeDb(@@ -302,3 +303,17 @@ describe('Codex readiness annotations', () => {expect(annotations[CONNECTION_REVISION_ANNOTATION]).toBeUndefined()})})++describe('publishAllowedModelsConfigMapAfterGrantChange', () => {+ it('skips when no writer is wired', async () => {+ await expect(publishAllowedModelsConfigMapAfterGrantChange(undefined)).resolves.toBe('skipped')+ })++ it('materializes when a writer is present', async () => {+ const materialize = vi.fn(async () => {})+ await expect(publishAllowedModelsConfigMapAfterGrantChange({ materialize })).resolves.toBe(+ 'published'+ )+ expect(materialize).toHaveBeenCalledTimes(1)+ })+})diff --git a/docs/deploy/minikube.md b/docs/deploy/minikube.mdindex dc85db36d..acb000fe7 100644--- a/docs/deploy/minikube.md+++ b/docs/deploy/minikube.md@@ -122,7 +122,11 @@ follow the fail-closed migration and rollout order inbefore enabling the feature flag.When deployable code changed and the E2E runner will manage port-forwards-itself, force the sync and skip the short-lived background port-forward refresh:+itself, force the sync and skip the short-lived background port-forward refresh.+Inner `pre-gate-sync` may use `--skip-port-forwards`; never pass that globally+into `make minikube-t2`. Do not kill this lane's `branch-profile-pf`.+`make minikube-pf-all-bg` is a gate refresh only; it must not replace+`branch-profile-pf`.```bashmake minikube-pre-gate-sync GATE=<gate-name> ARGS="--force-cluster-sync --skip-port-forwards"@@ -158,6 +162,25 @@ open http://localhost:3000`make minikube-setup` seeds the default test user and agent/context access. `npm run ui` keeps the required API port-forwards open while it runs the local frontends.+For a branch-owned profile, the host-side hold for Control UI / Desktop is+the first-hand entry point (gitignored helper at repo root — do not search+for it). Implementation: `.local-notes/minikube-profiles/branch-profile.sh`.+HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.+Profile-owned random ports only (never shared `:3000`/`:8090`).+`make minikube-pf-all-bg` is a gate refresh only; it must not replace+`branch-profile-pf`. Do not start UI PFs from a sandboxed agent shell. Run+the make target on the host. Do not kill this lane's `branch-profile-pf`.+`branch-profile-pf-health` starts PFs then STOPS them on EXIT — do not use+it as the lasting hold.++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf++MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-health+```+`make test-e2e-vitest` and `make test-e2e-all` install `tests/e2e`dependencies when missing and hold the minikube port-forwards for the Vitestphase. They also mint `MCP_HOST_AUTH_TOKEN` for legacy direct `mcp-host`@@ -463,6 +486,26 @@ kubectl rollout restart deployment/rpc-proxy -n rpc-proxy --context clerum-test## Port Forwards for the Desktop App+On a branch-owned profile, do not use the shared `:3000`/`:8090` mapping+below. First-hand entry point (gitignored helper at repo root — do not+search for it):++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf++MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-health+```++Implementation: `.local-notes/minikube-profiles/branch-profile.sh`.+HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.+`make minikube-pf-all-bg` is a gate refresh only; it must not replace+`branch-profile-pf`. `branch-profile-pf-health` starts PFs then STOPS them+on EXIT — do not use it as the lasting hold.++The shared `clerum-test` Desktop mapping remains:+```bashmake minikube-pf-desktop# equivalent to:diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex 423cc5e3a..f934fecbd 100644--- a/docs/get-started/quickstart.md+++ b/docs/get-started/quickstart.md@@ -116,7 +116,28 @@ screen — live activity, artifacts, sandbox UIs — seeThe headless path exercises the production JWT chain end to end. With`make minikube-pf-all` holding port-forwards in another terminal-(control-api :8090, external-rest-api :8091, rpc-proxy :8094, mcp-host :8080):+(control-api :8090, external-rest-api :8091, rpc-proxy :8094, mcp-host :8080)+on the shared `clerum-test` profile. For a branch-owned profile, first-hand+entry point (gitignored helper at repo root — do not search for it):++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf++MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-health+```++Implementation: `.local-notes/minikube-profiles/branch-profile.sh`.+HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.+This is the host-side hold for Control UI / Desktop. Profile-owned random+ports only (never shared `:3000`/`:8090`). `make minikube-pf-all-bg` is a+gate refresh only; it must not replace `branch-profile-pf`. Do not start UI+PFs from a sandboxed agent shell. Run the make target on the host. Do not+kill this lane's `branch-profile-pf`. `branch-profile-pf-health` starts PFs+then STOPS them on EXIT — do not use it as the lasting hold.++Shared-profile curl example (fixed ports):```bashEXT=http://localhost:8091 RPC=http://localhost:8094 HOST=chatllm@@ -177,7 +198,7 @@ Details: [Connect Telegram](../how-to/connect-telegram.md).| `minikube start` fails on memory | Raise Docker Desktop to ≥10 GB RAM / 6 CPUs — or, if you can't spare it, `MINIKUBE_MEMORY=9216 MINIKUBE_IMAGE_TAG=latest make minikube-setup` (stock Docker Desktop's ~9.9 GB is just under the 10 GB default) || Pods `Pending` early on | Calico is still coming up — wait, then `make minikube-status` || postgres CrashLoopBackOff after cold start | `make minikube-setup ARGS="--reset-db --skip-build"` |-| Port-forwards die | re-run `make minikube-pf-all` (it holds them open; Ctrl-C stops) |+| Port-forwards die | Shared profile: re-run `make minikube-pf-all` (it holds them open; Ctrl-C stops). Branch-owned profile: `MINIKUBE_PROFILE=<owned-profile> make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf` (do not use `branch-profile-pf-health` as the lasting hold; do not replace it with `make minikube-pf-all-bg`) |## Next stepsdiff --git a/docs/testing/e2e-guide.md b/docs/testing/e2e-guide.mdindex e54e2a2b4..3772a7996 100644--- a/docs/testing/e2e-guide.md+++ b/docs/testing/e2e-guide.md@@ -80,7 +80,9 @@ make minikube-pre-gate-sync GATE=<gate-name>```Use `--force-cluster-sync --skip-port-forwards` when deployable code changed-and your test runner will hold its own port-forwards:+and your test runner will hold its own port-forwards. Inner `pre-gate-sync`+may use `--skip-port-forwards`; never pass that globally into+`make minikube-t2`.```bashmake minikube-pre-gate-sync GATE=<gate-name> ARGS="--force-cluster-sync --skip-port-forwards"@@ -106,7 +108,29 @@ phase. Direct `npx vitest` runs still require a held port-forward terminal:make minikube-pf-all```-With port-forwards held, verify the localhost ports used by the tests:+For Control UI / Desktop on a branch-owned profile, the first-hand entry+point (gitignored helper at repo root — do not search for it) is the+host-side hold. Implementation:+`.local-notes/minikube-profiles/branch-profile.sh`.+HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.+Profile-owned random ports only (never shared `:3000`/`:8090`).+`make minikube-pf-all-bg` is a gate refresh only; it must not replace+`branch-profile-pf`. Do not start UI PFs from a sandboxed agent shell. Run+the make target on the host. Do not kill this lane's `branch-profile-pf`.+`branch-profile-pf-health` starts PFs then STOPS them on EXIT — do not use+it as the lasting hold.++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf++MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-health+```++With shared-profile (`make minikube-pf-all`) port-forwards held, verify the+localhost ports used by the tests. A branch-owned profile uses the random+ports from `branch-profile-health`, never shared `:8090`:```bashcurl -sS http://127.0.0.1:8090/healthdiff --git a/docs/testing/minikube-t2-runbook.md b/docs/testing/minikube-t2-runbook.mdindex 498085d0e..2768df5df 100644--- a/docs/testing/minikube-t2-runbook.md+++ b/docs/testing/minikube-t2-runbook.md@@ -45,6 +45,28 @@ The profile helper that generated the profile remains the source of truth forthe profile metadata and random localhost port mapping. Do not copy ports fromanother worktree or use shared fixed ports.+First-hand entry point (gitignored helper at repo root — do not search for+it):++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-pf++MINIKUBE_PROFILE=<owned-profile> \+ make -f .local-notes/minikube-profiles/branch.mk branch-profile-health+```++Implementation: `.local-notes/minikube-profiles/branch-profile.sh`.+HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.+This is the host-side hold for Control UI / Desktop. Profile-owned random+ports only (never shared `:3000`/`:8090`). `make minikube-pf-all-bg` is a+gate refresh only; it must not replace `branch-profile-pf`. Do not start UI+PFs from a sandboxed agent shell (hooks/PATH; runners clean children). Run+the make target on the host. Do not kill this lane's `branch-profile-pf`.+Inner `pre-gate-sync` may use `--skip-port-forwards`; never pass that+globally into `make minikube-t2`. `branch-profile-pf-health` starts PFs then+STOPS them on EXIT — do not use it as the lasting hold.+## State transitions### Bootstrap@@ -117,8 +139,10 @@ rm -rf -- "$T2_LOCK_ROOT/<profile>.lock"Never remove a lock with a live owner, and never remove the whole lock root.After bootstrap or reconcile, `make minikube-t2` calls `pre-gate-sync` with-`--skip-port-forwards`. T1 opens its own `control-postgres` port-forward and-does not inherit Control UI stack forwards. `t2_process_check` accepts only+`--skip-port-forwards`. Never pass that flag globally into `make minikube-t2`.+T1 opens its own `control-postgres` port-forward and+does not inherit Control UI stack forwards. Do not kill this lane's+`branch-profile-pf`. `t2_process_check` accepts onlyreal `kubectl` port-forward PIDs recorded in the profile cache or legacy`/tmp/pf-<profile>-*.pid`.@@ -134,7 +158,9 @@ Allowed port-forward PIDs live in`$HOME/.cache/clerum/minikube-profiles/<profile>/pids/*.pid` (and thelegacy `/tmp/pf-<profile>-*.pid` files written by `pf-all-stack.sh`).`make minikube-t2` invokes `pre-gate-sync` with `--skip-port-forwards` so the-orchestrator does not plant forwards that fail its own T2 check. Secret values+orchestrator does not plant forwards that fail its own T2 check. The Control+UI / Desktop hold stays on the host via the first-hand helper above; do not+replace it with `make minikube-pf-all-bg`. Secret valuesare never printed. The local Real PostgreSQL lane resolves the`control-postgres` Secret using the explicit context, constructs its admin DSNonly in process memory, and passes it only to the shared-server suites. Suites