[WRONG BRANCH] release: promote dev to preview for v2.31.0-preview.20260822

README.md

@@ -208,7 +208,7 @@ Qwen Cloud, SiliconFlow, and more. Full list: `ocx init` or the
 ocx init                       # interactive setup (writes config, wires Codex, offers the shim)
 ocx start [--port 10100]       # start the proxy in the foreground
 ocx stop                       # stop + restore native Codex
-ocx service [install|start|stop|status|uninstall|remove]  # background service
+ocx service [install|repair|restart|start|stop|status|uninstall|remove]  # background service
 ocx codex-shim install         # start the proxy on demand whenever `codex` launches
 ocx health [--json]            # check immediate proxy liveness
 ocx ready [--json] [--wait [--timeout <seconds>]]  # check post-sync readiness

devlog/_plan/260818_fastwire_b2_xai/evidence/README.md

@@ -0,0 +1,17 @@
+# FastWire B2 (xAI) — UI evidence
+
+`010_logs_priority_lower_bound.png` — Logs & Debug, three seeded `xai/grok-4.6` rows
+that exercise every branch of the new pricing path:
+
+| Row | Situation | Cost cell |
+| --- | --- | --- |
+| `req-standard` | no Fast requested | `~$0.0300` |
+| `req-priority` | response-confirmed priority, prompt under the long-context threshold | `~$0.0600` — exactly the documented 2x premium over the row above |
+| `req-longctx-priority` | response-confirmed priority, prompt at or above 200k | `≥$0.8760` — the published long-context rate, marked a lower bound because xAI publishes no combined price |
+
+The `≥` prefix is the visible change: a cost that is a known floor rather than an
+estimate now says so instead of rendering as `~$`. The detail drawer explains why
+via the `priority_lower_bound` estimate reason.
+
+Captured against a local proxy with a seeded `usage.jsonl`; no live xAI request was
+billed to produce it.

devlog/_plan/260820_sidecar_selection_unification/160_vision_external_research.md

@@ -0,0 +1,110 @@
+# 160 — Vision external-backend research (xai Grok / Antigravity Gemini describers)
+
+Continuation of #2188. Web-search shipped four external backends (L6-L9, docs
+060-090); the vision sidecar still dispatches only openai-forward and
+anthropic-OAuth. GUI evidence: the vision dropdown lists only Codex/Claude
+rows while the web-search dropdown already lists Grok/Gemini.
+
+## Current vision dispatch inventory
+
+- Types: `OcxVisionSidecarConfig.backend?: "openai" | "anthropic"` (src/types.ts).
+- Union: `VisionSidecarBackend` (src/vision/eligibility.ts:30) — 2 arms.
+- Candidate mapping: `visionBackendForCandidate` (eligibility.ts:150-165) —
+  native/openai → openai; anthropic only via the resolved OAuth provider name.
+- Options: `visionEligibleModelOptions` (eligibility.ts:201+) iterates
+  `["openai","anthropic"] as const` and injects `BASELINE_VISION_MODELS`.
+- Enabled backends: `enabledVisionBackends`
+  (src/server/management/vision-sidecar-options.ts:31-43); empty-auth fallback
+  returns both universal sides.
+- Write gate: `visionDescriberIsProvablyBlind` (vision-sidecar-options.ts:94+)
+  probes ONLY the openai/anthropic vendor tables.
+- PUT validation: config-routes.ts:594-596 rejects backends outside the two
+  literals; hint fall-through at :623; claude-code override near :738-740.
+- Runtime plan: `planVisionSidecar` (src/vision/index.ts) — anthropic arm and
+  openai-forward arm only. `resolveVisionBackend`: explicit > anthropic-if-auth
+  > openai.
+- GUI: `SidecarBackend = "openai" | "anthropic"` (gui/src/pages/
+  dashboard-shared.ts:62, claude-manual-env.ts:8). NOTE: this type is shared
+  with WebSearchModelOption and is ALREADY stale — the server emits
+  xai/gemini/exa web rows today.
+
+## Wire research (from shipped web-search executors, probe-verified 2026-08-20/21)
+
+### xai describe wire
+
+Mirror src/web-search/xai-executor.ts: POST `https://api.x.ai/v1/responses`
+(origin pinned; provider baseUrl honored only on same origin), stored OAuth
+bearer via `getValidAccessToken`, `redirect: "manual"`. Body for describe:
+
+```json
+{
+  "model": "<settings.model>",
+  "instructions": "<describe instruction>",
+  "input": [{ "role": "user", "content": [
+    { "type": "input_text", "text": "<context>" },
+    { "type": "input_image", "image_url": "<data: or https: url>" }
+  ]}],
+  "reasoning": { "effort": "<low|medium|high>" },
+  "stream": true
+}
+```
+
+SSE reduction: reuse the `response.output_text.delta` / `.done` handling
+shape from parseXaiResponsesSSE, without the citation/source machinery.
+Grok Responses accepts `input_image` with data URLs (same shape the OpenAI
+forward describer already posts — describe.ts builds input_image parts).
+
+### Gemini (Antigravity CCA) describe wire
+
+Mirror src/web-search/gemini-executor.ts: POST
+`{registry base}/v1internal:generateContent`, `ANTIGRAVITY_REQUEST_UA`,
+token + projectId via `getValidAccessTokenSnapshot`, envelope:
+
+```json
+{
+  "model": "<wireModelId from resolveAntigravityEffortWireModel>",
+  "userAgent": "antigravity", "requestType": "agent",
+  "project": "<projectId>", "requestId": "agent-<uuid>",
+  "request": {
+    "systemInstruction": { "role": "user", "parts": [{ "text": "<describe instruction>" }] },
+    "contents": [{ "role": "user", "parts": [
+      { "text": "<context>" },
+      { "inlineData": { "mimeType": "<mime>", "data": "<base64>" } }
+    ]}]
+  }
+}
+```
+
+inlineData shape matches src/adapters/google.ts:972/:1233. Response mapping:
+`candidates[0].content.parts[].text` join (mapCcaGroundedResponse shape,
+minus grounding). https: image URLs cannot be inlined without proxy-side
+fetch — REJECTED for gemini describe (data: URLs only, documented delta,
+same stance as anthropic-describe's stricter base64 rule).
+
+## Metadata facts
+
+- xai vendor table: bare grok-2/grok-3/grok-4 are `text`-only; grok-4.x
+  fast/4.3/4.5/4.6 and grok-2-vision are `text,image`.
+- No bare model id collides across the four vendor tables (openai 48,
+  anthropic 26, xai 32, google 43; collision scan 2026-08-21: zero) — the
+  "vendor tables never disagree" premise of visionDescriberIsProvablyBlind
+  survives widening to four families.
+
+## Audit deltas folded into this unit (sol-medium audit, 2026-08-21)
+
+- **Blocker A**: `BASELINE_VISION_MODELS` is a TOTAL
+  `Record<VisionSidecarBackend, string>`; widening the union without a
+  decision breaks typecheck. Decision → doc 170: baselines become
+  descriptor-owned (only openai/anthropic carry one).
+- **Blocker B**: `visionDescriberIsProvablyBlind` collapses non-anthropic
+  hints to openai and probes two families; a bare grok id absent from
+  candidates would slip the gate. Decision → doc 170: probe all four vendor
+  families.
+- Empty-auth fallback stays `["openai","anthropic"]` — never offer
+  xai/gemini unauthenticated.
+- GUI shared `SidecarBackend` must split (web-search has exa; vision does
+  not).
+- New executors: `sidecarEnter("vision")` (NOT "web-search"),
+  `signalWithTimeout` + `cancelBodyOnAbort`, `redactSecretString` on all
+  error paths, timeout-bounds.ts as single authority.
+

devlog/_plan/260820_sidecar_selection_unification/170_vision_backend_union.md

@@ -0,0 +1,80 @@
+# 170 — Backend union: "routed" describer (wp2, REVISED)
+
+Depends on: 160. REVISION 2026-08-22: user directive — vision does not need
+per-backend executors. Any picker-visible model with image input can describe;
+the proxy's own router already speaks every provider wire. The earlier
+xai/gemini backend literals were implemented but never released; this revision
+replaces them before any push.
+
+## Design
+
+- `VisionSidecarBackend = "openai" | "anthropic" | "routed"`.
+- "openai"/"anthropic" arms unchanged (forward Responses / OAuth Messages) —
+  they carry auth semantics loopback routing cannot replicate (forwarded
+  headers, OAuth beta fences), and their defaults must not drift.
+- "routed": the describer is ANY routed model, dispatched through the proxy's
+  own /v1/chat/completions on loopback (pattern: src/claude/gateway-cache.ts
+  self-fetch). One executor, every provider.
+
+## Filter (#2188 rules, unchanged shape)
+
+1. Picker-visible ∪ auth slots (pickerVisibleSidecarCandidates).
+2. − provably text-only (modelAcceptsImageInput === false drops the row).
+
+visionBackendForCandidate: native/openai → openai; resolved-OAuth anthropic
+row → anthropic; ANY OTHER provider row → "routed". Routed option values are
+NAMESPACED ("provider/model") so routeModel is unambiguous; legacy sides keep
+bare ids (GUI/current-value compatibility).
+
+## Gate
+
+visionDescriberIsProvablyBlind keeps the four-family probe widening AND
+learns namespaced ids: split on first "/", probe that provider's config row +
+metadata family. Bare ids keep the existing all-family probe.
+
+## Runtime
+
+- planVisionSidecar routed arm requires: cfg.backend === "routed", explicit
+  cfg.model, and plan-time modelAcceptsImageInput !== false for the target.
+- Recursion safety: the loopback request re-enters the vision planner only if
+  the routed model is provably text-only; the plan-time check excludes exactly
+  that set, so describe recursion is structurally impossible.
+- resolveVisionBackend: explicit honored; unset default order UNCHANGED.
+
+## Files (wp2 scope, revised)
+
+- src/vision/eligibility.ts: union, visionBackendForCandidate routed arm,
+  namespaced option values, BASELINE narrow-key record (kept from r1).
+- src/vision/backends.ts (r1 descriptor table): SIMPLIFIED — descriptors for
+  openai/anthropic/routed; xai/gemini entries dropped.
+- vision-sidecar-options.ts: enabledVisionBackends offers "routed" whenever
+  any routed row exists; gate learns namespaced ids.
+- config-routes.ts + agent-settings-routes.ts: literal sets accept "routed"
+  (xai/gemini literals removed).
+- types: backend unions.
+- tests: vision-backend-union.test.ts rewritten for routed.
+
+
+## Audit round 2 amendments (2026-08-22, sol-medium)
+
+- **Recursion fence is a MECHANISM, not a predicate claim.** The loopback
+  describe request carries a terminal marker header
+  `x-opencodex-vision-describe: 1`. The Responses plan site treats a marked
+  request as terminal: images are STRIPPED, never described (depth cap 1).
+  This holds under predicate drift (modelInputModalities is invisible to a
+  row-less plan-time target) and combo re-resolution (router.ts:625-631 can
+  land a different sibling). Belt-and-braces: the routed arm also requires
+  `!isModelTextOnly(resolvedRoute.provider, resolvedRoute.modelId)` at plan
+  time — the exact re-entry predicate on the resolved route.
+- **PUT-gate coherence:** a namespaced model with backend openai/anthropic is
+  REJECTED (forward executor POSTs the string verbatim — web-search F1
+  selector/slug failure); backend "routed" REQUIRES a namespaced id.
+- **GUI inference:** `value.includes("/") → "routed"` in
+  visionSidecarBackendForModel's fallback; persisted backend keeps traveling
+  as currentBackend.
+- Known limitation (recorded, not fixed here): a non-loopback-only bindHost
+  where 127.0.0.1 does not answer — same latent limitation gateway-cache has.
+- handleNativeChatCompletions fast path has no vision handling; the marked
+  describe request must not regress it (marker check lives at the Responses
+  plan site the bridge replays into).
+

devlog/_plan/260820_sidecar_selection_unification/180_vision_describe_executors.md

@@ -0,0 +1,73 @@
+# 180 — Routed describe executor + dispatch (wp3, REVISED)
+
+Depends on: 170 (revised).
+
+## src/vision/routed-describe.ts (new)
+
+Loopback POST http://127.0.0.1:{config.port}/v1/chat/completions:
+
+```json
+{ "model": "<namespaced routed id>", "stream": false,
+  "messages": [
+    { "role": "system", "content": "<describe instruction>" },
+    { "role": "user", "content": [
+      { "type": "text", "text": "<context>" },
+      { "type": "image_url", "image_url": { "url": "<data:/https:>" } }
+    ]}]}
+```
+
+- Auth: none on loopback binds (resolveApiAuth admits loopback without a
+  token); when OPENCODEX_API_AUTH_TOKEN is set, send it as Authorization
+  bearer (auth-cors.ts:399-400 accepts bearer on /v1/chat/completions).
+- signalWithTimeout(settings.timeoutMs) + cancelBodyOnAbort;
+  sidecarEnter("vision"); redactSecretString on error paths; response text
+  from choices[0].message.content; DESC clamp caller-side (existing).
+- validateImageUrl reused (data: mime allowlist + 20MB, https passthrough).
+- The chat inbound translates image_url → input_image and every adapter
+  compiles its own wire (anthropic blocks, CCA inlineData, xai Responses),
+  so provider coverage is the router's, not this file's.
+
+## planVisionSidecar routed arm
+
+VisionPlan gains { backend: "routed", routedModel: string }. Arm requires
+explicit model + plan-time modelAcceptsImageInput !== false (recursion
+fence). executeDescription routed arm calls describeImageRouted.
+
+## Tests
+
+vision-routed.test.ts: wire shape against a mock loopback server; recursion
+fence (text-only target never plans routed); timeout/error taxonomy;
+redaction. E2E: routed describer via a second mock provider.
+
+
+## Audit round 2 amendments (2026-08-22)
+
+- **Admission ladder (blocker 2):** token =
+  configuredApiAuthToken() || loadServiceTokenFromFile(env) || first
+  config.apiKeys entry; sent as `x-opencodex-api-key` (never Authorization —
+  gateway-cache.ts:77-86 rule); omitted entirely on loopback binds where
+  isApiAuthRequired is false.
+- **Terminal marker:** executor sets `x-opencodex-vision-describe: 1`; the
+  core.ts plan site checks it and strips images instead of planning vision.
+- Executor also passes stream:false and reads choices[0].message.content;
+  non-2xx → {error} with redacted body slice.
+
+
+## Audit round 3 amendment (2026-08-22) — marker propagation
+
+The chat→responses bridge rebuilds headers from the FORWARD_HEADERS allowlist
+(chat-completions.ts:198-203, openai-responses.ts:28-36), which would DROP
+`x-opencodex-vision-describe` before the plan site — on exactly the one path
+recursion lives. Therefore:
+
+- The marker is detected AT THE CHAT SURFACE (raw req.headers before the
+  bridge) and carried as an explicit option/flag into handleResponses
+  (`visionDescribeTerminal: true`), not as a header the bridge must
+  preserve. The Responses surface ALSO honors the raw header directly for
+  native /v1/responses callers.
+- Regression test drives the FULL chat-surface path: marked POST to
+  /v1/chat/completions with an image + text-only routed model → assert the
+  plan site STRIPS (no describe dispatch, no recursion), while the same
+  unmarked POST plans normally. A predicate-only test is insufficient and
+  would stay green with the marker broken.
+

devlog/_plan/260820_sidecar_selection_unification/190_vision_surfaces_and_delivery.md

@@ -0,0 +1,71 @@
+# 190 — Surfaces, live proof, delivery (wp4 cycle)
+
+Depends on: 180.
+
+## GUI
+
+- Split the shared SidecarBackend (dashboard-shared.ts:62): web-search side
+  keeps its server-provided backend strings (already emits xai/gemini/exa —
+  stale type fixed by the split); vision side gets
+  VisionBackend = "openai" | "anthropic" | "xai" | "gemini".
+- visionSidecarBackendForModel fallback stays server-provenance-first;
+  catalog inference (anthropic-vs-openai guess) only for legacy rows.
+- claude-manual-env.ts SidecarOverride backend union widens for vision.
+- No new dropdown UI: options arrive from visionModels server list already.
+
+## CLI
+
+- src/cli/agent.ts: usage already names xai|gemini; verify backend values
+  pass through PUT unvalidated client-side (server gate authoritative);
+  vision --list renders new backends' rows.
+
+## Live proof (acceptance 3-5)
+
+- GET /api/sidecar-settings on live :10100 shows visionModels containing
+  xai/gemini rows (auth present on this machine for both — web-search rows
+  prove it).
+- PUT vision {backend:"xai", model:"grok-4.3"} → 200; PUT model grok-4
+  (bare) → 400 provably-blind; restore original settings after proof.
+- GUI screenshot of the vision dropdown listing Grok/Gemini rows.
+
+## Delivery
+
+- Small commits per layer (backends table / eligibility+gate / executors /
+  GUI+CLI / tests+devlog), full bun run typecheck + bun run test green at
+  final head, push directly to dev (user-authorized, no PR).
+- devlog docs 160-190 land with the same push train; unit stays in _plan
+  until the release train closes it.
+
+
+## Delivery evidence (2026-08-22, wp4)
+
+- Live dev server (commit 3ff19c33e, port 11100, copied auth home):
+  - GET /api/sidecar-settings visionModels: 25 rows — legacy openai/anthropic
+    sides + 17 namespaced [routed] rows (xai/grok-4.6,
+    google-antigravity/gemini-3.7-flash, cursor/kimi-k3, zenmux/…,
+    alibaba…/qwen3.8-max, …). Rule 2 confirmed live: no text-only rows.
+  - PUT gates live: routed+xai/grok-4.6 → 200; routed+xai/grok-3 →
+    400 provably-blind; openai+namespaced → 400 coherence.
+  - GET after PUT reports the routed model verbatim
+    ({"model":"xai/grok-4.6","backend":"routed"}) — fixed the legacy-collapse
+    display bug found during this verification.
+  - GUI screenshot: vision dropdown lists namespaced routed rows; current
+    selection renders as xai/grok-4.6.
+  - CLI: `ocx agent sidecar vision --list` prints the same 25 rows with
+    [routed] backend tags (server-computed list, no drift).
+  - LIVE describe e2e: POST /v1/chat/completions with a 64x64 red PNG to
+    xai/grok-composer-2.5-fast (noVisionModels) with routed describer
+    xai/grok-4.6 → main answer "red"; request history shows the inner
+    grok-4.6 describe call followed by the outer composer call. (A 1x1 probe
+    earlier failed with xai invalid_image min-8px — upstream constraint, not
+    a pipeline defect; the graceful degradation path handled it and the main
+    call still succeeded.)
+- Verification-side effect handled: the 11100 dev server rewrote
+  ~/.grok/config.toml to port 11100 during startup sync; restored to 10100
+  via production `ocx ensure` and confirmed (27x base_url 10100, zero
+  11100). Temp verify home moved aside (/tmp/trash-ocx-vision-verify-*).
+- privacy:scan green; root+gui tsc clean; focused suites green (185 pass).
+- Full-suite run at final head queued behind another worktree's runner
+  (scripts/test.ts exclusive-run queue); recorded separately below when it
+  lands.
+