lidge-jun · lidge-jun · Sep 2, 2026 · Sep 1, 2026 · Sep 1, 2026 · Sep 1, 2026
@@ -14,18 +14,35 @@ name: Dev version bump
 # sign-off that a bot cannot supply. Until that merge the red persists. This converts a
 # forgotten chore into a queued, reviewable change - not into an automatic repair.
 #
-# A `release` event resolves this workflow file from the repository DEFAULT branch
-# (`main`), not from `dev` - the same trap documented in cleanup-closed-pr-branches.yml.
-# So merging this file to `dev` installs it but arms nothing; it first fires after an
-# ordinary dev -> main promotion carries it there.
+# WHY THIS IS CALLED, NOT TRIGGERED. It used to listen for `release: published`, and in
+# that form it ran ZERO times across v2.37.0, v2.38.0 and v2.39.0 - every one of those
+# bumps was still opened by hand (#3045, #3076, #3127). The workflow was not broken; the
+# event never existed. `release.yml` creates the GitHub release with
+# `GH_TOKEN: ${{ github.token }}`, and GitHub does not start workflow runs from events
+# raised by the default `GITHUB_TOKEN`. A `release: published` listener therefore cannot
+# observe a release this repository publishes itself, no matter which branch it sits on.
+#
+# The fix keeps the credential surface unchanged: no PAT, no app token, no
+# `contents: write` on the release job. `release.yml` CALLS this workflow directly after
+# a successful publish, so the run is a child of the release run instead of a reaction to
+# an event that is never delivered.
+#
+# A `workflow_call` body resolves from the CALLER's ref, and `release.yml` only ever runs
+# on `main` or `preview` (its own branch gate). So this file must be on `main` to take
+# effect - the same promotion requirement the old comment described, now for a different
+# reason.
 #
 # There is deliberately no `workflow_dispatch`: a branch-selected manual run executes
 # THAT branch body with `contents: write`. Re-drive a missed run by running
 # `bun scripts/bump-dev-version.ts <released> package.json` locally and opening the pull
 # request normally.
 on:
-  release:
-    types: [published]
+  workflow_call:
+    inputs:
+      released-version:
+        description: "The tag that just published, e.g. v2.39.0"
+        required: true
+        type: string
 
 permissions: {}
 
@@ -69,7 +86,7 @@ jobs:
       - name: Decide the version dev should carry
         id: decide
         env:
-          RELEASED_VERSION: ${{ github.event.release.tag_name }}
+          RELEASED_VERSION: ${{ inputs.released-version }}
         run: |
           set -euo pipefail
           bun scripts/bump-dev-version.ts "${RELEASED_VERSION}" package.json
@@ -88,7 +105,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           NEXT_VERSION: ${{ steps.decide.outputs.version }}
-          RELEASED_VERSION: ${{ github.event.release.tag_name }}
+          RELEASED_VERSION: ${{ inputs.released-version }}
         run: |
           set -euo pipefail
 

@@ -36,6 +36,41 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  # Move `dev` past the version that just published.
+  #
+  # This is a CALL, not a `release: published` listener. The release is created with
+  # `github.token`, and GitHub does not start workflow runs from events that token
+  # raises - so a listener cannot observe a release this repository publishes itself. In
+  # that form it ran ZERO times across v2.37.0, v2.38.0 and v2.39.0 while every one of
+  # those bumps was opened by hand (#3045, #3076, #3127).
+  #
+  # `needs: publish` means this is skipped unless the publish job succeeded, so a failed
+  # publish or a failed release creation never opens a bump pull request; the explicit
+  # condition only adds the dry-run case. The called workflow declares its own
+  # `contents: write` / `pull-requests: write` for its own job, so nothing here gains
+  # write access.
+  #
+  # Both channels call this, and the double-call is safe because `bump-dev-version.ts`
+  # compares against what `dev` already carries. In the usual train `dev` is already at
+  # the stable core when the preview publishes, so that call returns `changed=false`
+  # ("dev already carries 2.40.0, which is ahead of the published 2.40.0-preview.*") and
+  # every later step is gated on that output. The stable call returns `changed=true` and
+  # opens the one pull request. A preview publishing while `dev` is genuinely behind
+  # still bumps it, which is the point.
+  #
+  # It is declared FIRST in this file, ahead of the jobs it depends on, because
+  # tests/ci-workflows.test.ts splits the workflow on `- name:` and reads each `run:`
+  # block to the start of the next one when it checks that dispatch inputs never
+  # interpolate into shell source. A job declared between two steps lands inside that
+  # window and reads as shell. Job order in YAML carries no execution meaning - `needs`
+  # does - so declaring it before its own dependency costs nothing.
+  bump-dev-version:
+    needs: publish
+    if: ${{ inputs.dry-run != true }}
+    uses: ./.github/workflows/dev-version-bump.yml
+    with:
+      released-version: v${{ inputs.version }}
+
   validate-dispatch:
     runs-on: ubuntu-latest
     permissions:

@@ -14,27 +14,55 @@ npm install -g @bitkyc08/opencodex
 ocx start        # proxy + dashboard on localhost:10100
 ```
 
-<table align="center">
-  <tr>
-    <td width="50%" align="center">
-      <img src="assets/claude-code-models.gif" alt="Claude Code running a routed model through opencodex — the status bar shows gpt-5.6-luna-medium as the active model" width="410"><br>
-      <sub><b>Claude Code, running any model.</b><br>The picker is stock Claude Code. The brain behind it isn't.</sub>
-    </td>
-    <td width="50%" align="center">
-      <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/demo.gif" alt="opencodex demo — running a task in the Codex app on a routed non-OpenAI model" width="410"><br>
-      <sub><b>Codex, running any model.</b><br>Pick a provider and go — same workflow, different brain.</sub>
-    </td>
-  </tr>
-  <tr>
-    <td width="50%" align="center">
-      <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/claude-desktop-subagent.gif" alt="Claude Desktop answering as Claude Opus 4.8, then dispatching a GPT-5.6 Sol subagent through opencodex" width="410"><br>
-      <sub><b>Claude Desktop, running any model.</b><br>Opus answers, then hands the task to a GPT-5.6 Sol subagent.</sub>
-    </td>
-    <td width="50%" align="center">
-      <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/grok-build-subagent.gif" alt="Grok Build running GPT-5.6 Sol through opencodex and calling a Kimi K3 subagent" width="410"><br>
-      <sub><b>Grok Build, running any model.</b><br>Sol drives the session and calls a Kimi K3 subagent.</sub>
-    </td>
-  </tr>
+<table>
+<tr>
+<td width="50%" valign="middle">
+
+### Claude Code, running any model
+
+The picker is stock Claude Code. The brain behind it isn't.
+
+</td>
+<td width="50%">
+  <img src="assets/claude-code-models.gif" alt="Claude Code running a routed model through opencodex — the status bar shows gpt-5.6-luna-medium as the active model" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Codex, running any model
+
+Pick a provider and go — same workflow, different brain.
+
+</td>
+<td width="50%">
+  <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/demo.gif" alt="opencodex demo — running a task in the Codex app on a routed non-OpenAI model" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Claude Desktop, running any model
+
+Opus answers, then hands the task to a GPT-5.6 Sol subagent.
+
+</td>
+<td width="50%">
+  <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/claude-desktop-subagent.gif" alt="Claude Desktop answering as Claude Opus 4.8, then dispatching a GPT-5.6 Sol subagent through opencodex" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Grok Build, running any model
+
+Sol drives the session and calls a Kimi K3 subagent.
+
+</td>
+<td width="50%">
+  <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/grok-build-subagent.gif" alt="Grok Build running GPT-5.6 Sol through opencodex and calling a Kimi K3 subagent" width="100%">
+</td>
+</tr>
 </table>
 
 <p align="center">

@@ -0,0 +1,105 @@
+# 000 — Research: remote hub mode (evidence base)
+
+Unit: 260827_remote_hub · Branch: codex/remote-hub-design · Status: research
+
+## Motivation (user request, 2026-08-27)
+
+Run one ocx as a central HUB (Oracle VM / Mac mini / Docker — any machine), keep every
+provider key, OAuth credential, and shared config there, and let other machines connect
+with only a pointer + token ("ocx connect <tailnet-dns>"). The dashboard on a client
+machine must still work at localhost:10100 with a two-plane split: shared pages operate
+the hub, machine pages operate local file integration. Explicit constraint from the user:
+today a Tailscale-bound GUI is unusable for some operations even WITH the admin token —
+the design must fix remote GUI operability without collapsing the consent boundary.
+
+## In-repo evidence (verified 2026-08-27 on dev @ 8b1b65b8d)
+
+- Non-loopback bind forces the data token: `isApiAuthRequired` returns true whenever the
+  bind hostname is not loopback (src/server/auth-cors.ts:260-262), and startup refuses a
+  public bind without a configured data credential.
+- The remote-GUI limitation is a deliberate restriction, not an unreported weakness, and
+  it is already visible in shipped public code: `issueGuiSession` returns null when
+  `isApiAuthRequired(config)` is true and additionally requires a loopback Host
+  (src/server/management-auth.ts, `issueGuiSession`). The published dashboard guide
+  states the same boundary in user terms.
+
+  The consequence is a capability gap rather than an exposure: on a remote bind the
+  principal `gui-session` is unobtainable, so consent-bearing routes requiring
+  `ctx.principal === "gui-session"` (src/server/management/sidebar-routes.ts:42,
+  src/server/management/codex-prompt-routes.ts:298) answer 403 even to the admin token.
+  That 403 is correct and stays correct — the admin token must never be able to spend the
+  user's consent (AGENTS.md user-consent boundary). What is missing is any path for a
+  *browser* to mint a session remotely, which is what this unit designs.
+
+  Stated precisely: the current behavior fails closed. Nothing here describes a way to
+  obtain authority one should not have, so this note is a design rationale rather than
+  pre-disclosure material, and `AGENTS.md`'s scratch-space rule for unfixed defects does
+  not apply to it. Anything in this unit that WOULD describe an unfixed exploitable
+  weakness belongs in scratch space, not in `devlog/`.
+- `managementRequestOrigin` returns null for a non-loopback Host when apiAuth is NOT
+  required (src/server/auth-cors.ts:118-129); when apiAuth IS required it derives the
+  origin from the request, which a TLS terminator breaks (http observed vs https public).
+- The GUI attaches credentials only same-origin: `needsApiAuth` refuses absolute
+  cross-origin URLs (gui/src/api.ts:53-60). A two-plane GUI therefore needs an explicit
+  multi-target API layer, not a base-URL swap.
+- The GUI needs a secure context in places: `crypto.subtle.digest` at
+  gui/src/log-conversation-id.ts:26, `navigator.clipboard` at
+  gui/src/oauth-health-display.ts:133 (with execCommand fallback).
+- Injector already supports non-loopback targets: dedicated provider block with
+  `env_key = "OPENCODEX_API_AUTH_TOKEN"` and `model_catalog_json` requiring a LOCAL
+  absolute path (src/codex/inject.ts:186-247, 622+).
+- `GET /api/catalog` and `GET /api/client-config` already exist behind management auth
+  (src/server/management/model-routes.ts:334-420).
+- Headless OAuth exists: `oauthOpenBrowser: false` (src/oauth/open-browser-choice.ts) and
+  `POST /api/oauth/login/code` (src/server/management/oauth-account-routes.ts:208).
+- Allowlist-listener precedent: the unauthenticated loopback listener enumerates exactly
+  the routes it serves (src/server/index.ts, loopbackRouteAllowed) — the machine-plane
+  listener should copy this failure mode (default-404).
+- Token-file delivery precedent: `OCX_API_TOKEN_FILE` (src/lib/service-secrets.ts,
+  src/service.ts:1571+).
+- CLI already talks to the management API over HTTP with injectable baseUrl
+  (src/cli/runtime-api.ts, RuntimeApiDeps.baseUrl) — client-mode remote management
+  commands are a URL + credential change, not a new client.
+
+## External evidence (Luna swarm, 3 lanes, sources opened 2026-08-27)
+
+Peer proxies separate UI sessions from master keys:
+- LiteLLM: LITELLM_MASTER_KEY for API/admin, separate UI login minting expiring
+  virtual keys; per-user/per-device virtual keys with budgets, central key custody.
+  https://docs.litellm.com.cn/docs/proxy/ui , virtual_keys.md / access_control.md in
+  BerriAI/litellm-docs (opened 2026-08-27).
+- sub2api: admin web UI uses JWT session; automation uses a separate global Admin API
+  Key (x-api-key). https://github.com/Wei-Shaw/sub2api (opened 2026-08-27).
+- One API broken-access-control reports (#2410, #2423) show central key custody makes
+  route-level authz the main defense.
+
+Tailscale transport facts (official docs, verified dates in page footers):
+- `tailscale serve` = tailnet-only reverse proxy to a localhost backend; injects
+  Tailscale-User-* identity headers; backend must bind loopback or headers are
+  spoofable. https://tailscale.com/docs/features/tailscale-serve
+- `tailscale cert` issues public CA certs only for the ts.net FQDN (not bare MagicDNS
+  short names); names land in Certificate Transparency logs.
+  https://tailscale.com/docs/how-to/set-up-https-certificates
+- Funnel is public-internet exposure (ports 443/8443/10000) — out of scope here.
+
+Browser platform facts (MDN/WHATWG/IETF, opened 2026-08-27):
+- Plain-HTTP non-localhost origins are NOT secure contexts: no crypto.subtle, no
+  async clipboard, Secure cookies unavailable. http://localhost IS potentially
+  trustworthy. https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts
+- Header-token SPAs avoid ambient-cookie CSRF but still need exact-origin allowlists
+  and Origin checks on mutations (WHATWG Fetch; RFC 9700 OAuth BCP).
+- RFC 8628 device flow is the reference pattern for headless-hub OAuth; ocx's
+  oauthOpenBrowser:false + /api/oauth/login/code is already equivalent in shape.
+
+## Design consequences (carried into 010)
+
+1. Two credential worlds stay separate: data-plane admission (client machines) vs
+   management (admin token / gui-session). Peers (LiteLLM, sub2api) validate this split.
+2. Remote GUI needs a NEW session-issuance path, not a weakening of requireManagementAuth:
+   the loopback-only refusal in issueGuiSession is the single gate to generalize.
+3. HTTPS via tailscale serve against a loopback-only management ingress is the
+   recommended browser path; plain-HTTP tailnet operation must exist as a documented
+   opt-in because usability on a private tailnet was the user's explicit complaint.
+4. localhost:10100 client GUI + direct-to-hub shared plane is cross-origin; the hub
+   needs management CORS for an allowlisted client origin, or the client listener
+   relays. Both appear in 010 with the relay constrained to a fixed target.
@@ -0,0 +1,75 @@
+# 001 — Interview record (2026-08-28)
+
+Answers captured from the maintainer (session 01a0439a, I-phase round 2):
+
+- **Scope: ALL 6 phases, full implementation including hardening (P6).** Delivery as a
+  stacked PR chain grown from this branch (codex/remote-hub-design is the stack base;
+  each phase PR targets the previous head; retarget to dev as parents land —
+  DEV-STACK / enforce-target child rules).
+- Q2 (plain-HTTP pairing): accepted — rung 4 ships in Phase 2 with rung 3.
+- Q3 (per-client keys): recommendation accepted BUT see new usage requirement below,
+  which pulls toward auto-issuing per-client keys at connect.
+- Q4 (URL split): accepted — separate managementUrl allowed, /readyz advertises it.
+- Q5 (remote session TTL): accepted — renewable long-lived remote sessions.
+- Q6 (hub local integration): accepted — hub does not inject locally by default.
+- Q7 (Claude): launcher-scope first confirmed; maintainer notes it is machine-local
+  anyway — clean separation is the requirement, not persistent integration.
+- Q8 (deployment): **dogfood on clisu-oracle as part of this work**, AND the protocol
+  must tolerate release-build peers: a released client against a dev-build hub (and
+  the reverse) must interoperate "어느정도" — i.e. protocol-version negotiation in
+  /readyz is a hard requirement, not polish (Phase 1 scope).
+- **NEW requirement (usage attribution):** the client GUI usage page should reflect
+  "my machine's usage" while connected, and after `ocx disconnect` the GUI (back in
+  standalone mode) shows the local proxy's own usage again. Feasibility confirmed in
+  code: usage attempts already persist `apiKeyId` for configured-key admissions
+  (src/server/management/api-key-usage.ts:78-89, admissionFields in
+  src/server/auth-cors.ts:369-375), so a per-client filtered usage view is a query
+  over existing data — it requires the machine to authenticate with its OWN key,
+  which is why connect should default to per-client key issuance.
+
+Open contradiction (to resolve this round): shared-token-allowed (Q3 answer) vs
+per-machine usage view (new requirement) — attribution is keyed on apiKeyId, so a
+shared token collapses all machines into one bucket.
+
+## Round 3 answers (2026-08-28)
+
+- **Q-A = a (auto-issue per-client key at connect).** Storage question resolved in
+  code: the key is NEVER written to config.toml (env_key contract); it lands in the
+  existing owner-only token file (serviceApiTokenFilePath, src/lib/service-secrets.ts:5,
+  0600 + ACL hardening) which the shim already reads into OPENCODEX_API_AUTH_TOKEN when
+  the env is empty (src/codex/shim.ts:699-701 unix, :1000-1001 batch, :1043 ps).
+  disconnect deletes the file. The shared-token-vs-attribution contradiction is CLOSED:
+  per-client keys are the connect default, so per-machine usage attribution works.
+- **Q-C = a.** Protocol v1 negotiated via /readyz; same-major interop with
+  feature-detection; guaranteed pair = dev hub ↔ latest release client; older peers get
+  an explicit "hub protocol too new/old, upgrade ocx" error. Phase 1 hard requirement.
+- **Q-B: OPEN ASSUMPTION (low)** — usage page default while connected = "this machine"
+  slice with a toggle to hub-wide; not answered explicitly, adopting the recommended
+  default; reversible in Phase 4 GUI work.
+
+## Final contradiction rescan (round 3)
+
+- Shared-token vs attribution: RESOLVED (per-client default; shared token remains a
+  degraded documented mode where usage collapses into one bucket).
+- Pairing-grant issuance vs POST /api/keys authority: connect needs admin-class
+  authority ONCE — satisfied by pairing code (rung 3/4) or admin token; neither is
+  persisted on the client. No contradiction.
+- Dogfood release-compat vs stacked delivery: protocol version lives in Phase 1 (stack
+  base), so every later phase rides it. No ordering conflict.
+- Remaining OPEN ASSUMPTIONS: Q-B default; session TTL exact value (12h sliding,
+  tunable); relay streaming backpressure deferred to Phase 6.
+
+Interview readiness: Goal/Constraint/Success/Ontology all covered by asked-and-answered
+rounds 1-3. Ready for I -> P.
+
+## Round 4 answer (2026-08-28) — usage rendering settled
+
+Maintainer's rule, adopted verbatim as the design: **connected → render the hub's
+usage (my apiKeyId slice); not connected → render the local usage.jsonl.** No local
+mirroring of the connect-period usage (option b rejected as unnecessary complexity);
+the connect-period history lives on the hub and is visible there. Grounding:
+usage persists where the serving proxy runs (appendUsageEntry →
+~/.opencodex/usage.jsonl, src/usage/log.ts:166-167, 521-523), so this rule is just
+"render the store that actually recorded the traffic" — zero data duplication,
+no schema change. Q-B default (this-machine slice with hub-wide toggle) stands as
+the connected view's default.