release: promote verified 2.52.0 product tree to main

AGENTS.md

@@ -31,7 +31,14 @@ Bun-native TypeScript with no separate server compile step.
 - `go/` — retired Go native-runtime experiment; kept only where the TypeScript
   runtime still references it. New work does not go here.
 - `structure/` — maintainer invariants and architecture notes; read before
-  changing shared subsystems.
+  changing shared subsystems. [`structure/INDEX.md`](./structure/INDEX.md) is the
+  reading order and the source-ownership table, and
+  [`structure/AGENTS.md`](./structure/AGENTS.md) holds the rules for changing
+  anything in there. Ownership is not advisory: changing an owned source area
+  obliges the same change to update its doc, and `bun run structure:check`
+  (wired into the suite by `tests/ci-workflows/structure-ssot.test.ts`) fails on a
+  doc that names a path this tree no longer has, on an invariant whose test is
+  gone, and on a new `src/` area nobody claimed.
 - `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
   release authority.
 - `devlog/` — planning and investigation notes, tracked in this repository. See
@@ -187,6 +194,8 @@ bun run test:changed   # import-graph tests against the resolved `dev` merge bas
 bun run test           # full tests/ suite (PR-ready / explicit ask only)
 bun run lint:gui       # GUI eslint
 bun run privacy:scan   # credential/privacy scan used by CI
+bun run structure:check # structure/ doc-map, ownership, and invariant-binding gate
+bun run structure:index # regenerate structure/INDEX.md from structure/manifest.json
 bun run build:gui      # Vite GUI build
 ```
 

CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thanks for helping with opencodex.
 - Start with the canonical guide: [Contributing](https://opencodex.me/contributing/)
 - Pull-request quality contract: [Review readiness and author responsibility](https://opencodex.me/contributing/pr-quality/)
 - Public user docs live in [`docs-site/`](./docs-site)
-- Current maintainer invariants live in [`structure/`](./structure)
+- Current maintainer invariants live in [`structure/`](./structure); start at [`structure/INDEX.md`](./structure/INDEX.md)
 - Maintainer roles and merge policy live in [`MAINTAINERS.md`](./MAINTAINERS.md)
 - Attribution for work landed through a maintainer carry lives in [`CREDITS.md`](./CREDITS.md)
 - Historical investigations live in [`docs/`](./docs)

devlog/_fin/260912_devin_cli_account_login/000_plan.md

@@ -0,0 +1,88 @@
+# Devin CLI as an account provider
+
+**Unit:** 260912_devin_cli_account_login
+**Class:** C3 (public provider contract + a documented invariant + GUI surface)
+**Goal (host):** register devin-cli as an account provider so it appears in the
+dashboard accounts tab beside devin, by giving it a login entry that drives the
+installed Devin CLI's own auth flow, without opencodex holding a usable Devin
+bearer token.
+
+## Why this unit exists
+
+The dashboard's add-provider dialog has three tabs. Two of them (Free, Paid) are
+rendered from the preset catalog; the Accounts tab is not. In
+`gui/src/components/provider-catalog/ProviderCatalog.tsx` the preset rows are
+drawn only when `tier !== "accounts"`, and the Accounts tab instead renders
+`accountRows`, which is built from providers that have a login flow. The
+`buckets.accounts` bucket that `bucketPresets` computes is never rendered at
+all.
+
+That is why `devin-cli` is reachable only under Free today: `authKind: "local"`
+makes `isFreeProvider` true (`gui/src/provider-workspace/catalog.ts`), the same
+branch that holds Ollama, vLLM and LM Studio. Reclassifying the tier alone would
+remove it from Free and put it in a bucket nothing draws, so it would vanish
+from the dialog entirely. The only way into the Accounts tab is to become a
+provider with a login.
+
+## The constraint this unit has to move
+
+`src/providers/registry.ts` and `tests/providers/devin-cli-adapter.test.ts`
+currently pin the opposite posture:
+
+> The installed CLI carries its own credentials from `devin auth login`, so this
+> provider takes no key and the proxy never sees a token for this provider.
+
+That statement is about the **request path**, and it stays true: the adapter
+spawns `devin acp` and the child authenticates itself. What changes is the
+**dashboard path**, which gains a login entry whose job is to run the CLI's own
+auth flow and read back who is signed in. The distinction the unit must keep
+explicit, in code comments and in the tests, is:
+
+- the adapter still never reads, requests, or forwards a credential at request time;
+- the OAuth entry stores an identity marker, never a usable Devin bearer token.
+
+If those two cannot both hold, the unit stops and reports rather than inventing a
+token to satisfy the framework.
+
+## Constraints
+
+- No repository-wide local suite, typecheck, or build. Focused tests only; hosted
+  CI on the exact PR head is the gate. Push with `--no-verify`.
+- The Devin CLI is **not installed** on the development machine and must not be
+  installed as part of this unit without a separate instruction. Every code path
+  that depends on the binary needs a documented degraded behaviour and a test
+  that exercises it through an injected spawn, the way
+  `tests/providers/devin-cli-adapter.test.ts` already drives the adapter.
+- `src/lab/` must stay off the core path; nothing here touches `src/router.ts`,
+  `src/server/lifecycle.ts`, or `src/server/responses/core.ts`.
+- Target branch is `dev`.
+
+## Work-phase map
+
+Dependency-ordered; each is one full PABCD cycle.
+
+| Phase | Doc | Outcome |
+|---|---|---|
+| wp1 | this unit | Roadmap locked, every later phase written to diff level |
+| wp2 | `010_phase1_cli_login.md` | `src/oauth/devin-cli.ts`: signed-in detection, login that drives the CLI, identity-only credential |
+| wp3 | `020_phase2_reclassify.md` | Registry + OAUTH_PROVIDERS registration, invariant text, tests that pinned `local` |
+| wp4 | `030_phase3_surface_and_land.md` | Accounts-tab proof against the running service, docs/locale, PR, merge |
+
+## Open risks carried into wp2
+
+1. **CLI absent.** Signed-in detection cannot be proven end to end on this
+   machine. wp2 must therefore make the binary lookup injectable and prove both
+   branches (found / not found) with the existing `resolveDevinCliBinary`
+   override seam, and wp4 must state plainly that the live signed-in path is
+   unproven here.
+2. **No documented status subcommand.** If the CLI exposes no non-interactive way
+   to report the signed-in account, the login entry can only report "the CLI
+   reports it is signed in" without an identity. That is still enough for an
+   accounts row, but it changes the credential shape, so wp2 decides this against
+   the subagent finding recorded in `001_cli_auth_survey.md` and amends
+   `010_` before building.
+3. **Refresh.** The OAuth framework expects a refresh path. `src/oauth/devin.ts`
+   throws `invalid_grant` because Cognition mints no refresh token; the CLI entry
+   has the same shape and should reuse that posture rather than extending an
+   expiry it cannot honour.
+

devlog/_fin/260912_devin_cli_account_login/001_cli_auth_survey.md

@@ -0,0 +1,82 @@
+# 001 — What the surfaces actually require
+
+Findings from three parallel read-only investigations (subagents Carson, Gibbs,
+Rawls), recorded here so each later phase starts from evidence rather than from
+the transcript.
+
+## The Accounts tab is fed by OAUTH_PROVIDERS, not by the preset catalog
+
+`GET /api/oauth/providers` returns `listOAuthProviders()`, which is
+`Object.keys(OAUTH_PROVIDERS)` minus `chatgpt`
+(`src/server/management/oauth-account-routes.ts:137-140`,
+`src/oauth/index.ts:335-371`). The GUI turns that list into the Accounts rows in
+`gui/src/pages/providers-page-utils.ts:8-25`. A provider does **not** need to be
+in `config.json` to appear. So membership in `OAUTH_PROVIDERS` is the whole
+admission rule.
+
+## What an OAuth entry must provide
+
+`OAuthProviderDef` (`src/oauth/index.ts:184-196`) requires `login`, `refresh`,
+`providerConfig`, `defaultModel`. `providerConfig` is not hand-written: `oauthConfig(id)`
+calls `deriveOAuthProviderConfig`, which finds the registry row **only when
+`authKind === "oauth"`** and throws otherwise (`src/providers/derive.ts:350-353`).
+That is why the registry reclassification and the OAuth registration are one
+atomic change, not two independent edits.
+
+`OAuthCredentials` requires `access: string`, `refresh: string`, `expires: number`;
+`normalizeCredential` drops the whole credential if any of the three is missing or
+mistyped (`src/oauth/store.ts:447-502`).
+
+## The durable-key precedent already exists
+
+`devin` faces the same "no refresh endpoint" problem and solves it without
+inventing one: it stores the durable key as both `access` and `refresh`, sets
+`expires: Number.MAX_SAFE_INTEGER`, declares `defaultRefreshPolicy: "disabled"`,
+and its `refresh` throws `invalid_grant` so a forced refresh marks the account
+`needsReauth` instead of pretending success (`src/oauth/devin.ts:50-72, 155-166`,
+`src/oauth/index.ts:310-315`). `orcarouter-oauth` does the same. An empty
+`refresh: ""` is explicitly the wrong shape — it makes `detectOAuthWarning` report
+`stale_credentials` from the moment of login.
+
+This unit reuses that shape, with one difference that has to stay visible: for
+`devin` the stored string is a real API key; for `devin-cli` it is a non-secret
+presence marker, because there is no token for opencodex to hold.
+
+## The fail-closed check that makes this a migration
+
+`src/server/auth-cors.ts:731-737` rejects a saved provider row whose
+`authMode === "local"` when its registry entry is not local:
+
+> `provider ${name} cannot use authMode "local" — its registry entry requires ${entry.authKind} auth`
+
+`derive.ts:217-231` seeds `authMode` from `authKind`, so every config saved while
+`devin-cli` was local carries `authMode: "local"`. Flipping the registry to
+`oauth` without a migration turns those configs into a startup rejection. This is
+the single highest-risk item in the unit and `020` owns it.
+
+## Everything else `"local"` currently controls for this provider
+
+From `gui/src/provider-workspace/`: `catalog.ts:137-143` treats local as
+configuration-ready; `catalog.ts:170-174` puts it in the Free tier;
+`auth.ts:21-22` returns `null` so no auth surface is drawn; `kind.ts:12-21`
+classifies it as kind `local` for the rail filter. Under `oauth` all four change
+behaviour, which is the intent — an OAuth row gets an auth surface and a login
+button — but `030` has to look at the rail, not only the modal.
+
+From `src/providers/`: `fastwire.ts:109` returns `"none"` for local, so no
+Authorization header is attached. This matters: the `devin-cli` adapter never
+travels the fetch path at all (`buildRequest` is a placeholder), so the header
+policy is inert for it either way. `quota.ts:2899` and `key-failover.ts` skip
+local rows; under `oauth` they take the OAuth branches, which is correct because
+there is now an account to reason about.
+
+## What the Devin CLI itself stores
+
+The CLI keeps its own credential on disk as `credentials.toml`. opencodex never
+reads it; the adapter only spawns `devin acp` and the child authenticates itself
+(`src/adapters/devin-cli/adapter.ts:1-8`). The CLI is **not installed** on this
+machine, so the exact path and any non-interactive status subcommand are
+unconfirmed. `010` therefore treats both the path and the status probe as
+injected dependencies with a proven not-found branch, and `030` states plainly
+that the live signed-in path is unproven here.
+

devlog/_fin/260912_devin_cli_account_login/002_audit_resolution.md

@@ -0,0 +1,101 @@
+# 002 — Audit resolution: the reclassification is the wrong mechanism
+
+Independent adversarial audit of `000`/`010`/`020`/`030` returned **VERDICT: FAIL**
+with four blockers. Three are fixable in place. The first invalidates the central
+decision, and the roadmap changes rather than arguing with it.
+
+## Blocker 1 (fatal to the original design)
+
+Flipping `authKind` to `oauth` couples the REQUEST path to a credential that
+carries no meaning. `src/router.ts:317-318` forces `authMode` from the registry
+for oauth entries, and `src/server/responses/core.ts:4323` then always calls
+`getValidAccessTokenSnapshot`, which throws `OAuthLoginRequiredError` when no
+account set exists (`src/oauth/index.ts:576-578`) and stamps
+`apiKey: resolved.accessToken` at `:4401`.
+
+Today a configured `devin-cli` row answers with no opencodex credential at all,
+because the child authenticates itself. Under the original plan every turn would
+401 until someone clicked Login, and a dashboard logout would break inference
+while the CLI stayed signed in. `020`'s boundary forbids touching
+`responses/core.ts`, so the plan could not have special-cased its way out.
+
+The audit also killed a claim in `000`: reclassifying does NOT make the row vanish.
+`providerTier` only puts the canonical OpenAI forward provider in `accounts`
+(`gui/src/provider-workspace/catalog.ts:160-181`), so an oauth preset with a
+non-loopback base URL lands in **Paid**, which is rendered. The original
+motivation sentence was wrong about the failure mode while being right that the
+Accounts tab is unreachable from the preset catalog.
+
+## The corrected mechanism
+
+Accounts-tab admission is `OAUTH_PROVIDERS` membership — `listOAuthProviders()`
+is `Object.keys(OAUTH_PROVIDERS)` minus `chatgpt`
+(`src/oauth/index.ts:369-371`, `src/server/management/oauth-account-routes.ts:139-140`).
+Nothing in that path reads `authKind`.
+
+`authKind: "oauth"` was only needed because `oauthConfig(id)` derives
+`providerConfig` through `deriveOAuthProviderConfig`, which filters on it
+(`src/providers/derive.ts:350-353`). But `providerConfig` is an ordinary
+`OcxProviderConfig` field — it can be built from the registry row directly.
+
+**So: register `devin-cli` in `OAUTH_PROVIDERS` and leave `authKind: "local"`
+alone.** The Accounts row appears; the request path keeps seeing a local
+provider, demands no token, and behaves exactly as it does today. The
+`auth-cors` migration in `020` and its whole new migration module become
+unnecessary, because no persisted `authMode` ever mismatches.
+
+This also resolves the honesty problem that made the original design
+uncomfortable: opencodex no longer needs a marker to stand in for a bearer
+token on the request path, because the request path never asks. The stored
+credential exists only so the Accounts row has a state to show.
+
+The residual risk moves to `isOAuthProvider("devin-cli")` becoming true, which
+switches on `ocx login` (`src/oauth/login-cli.ts:86-88`), changes `ocx account`
+(`src/cli/account-api.ts:83-93`), and admits the row to generic 429 failover
+(`src/oauth/generic-account-failover.ts:97-98`). wp2 must prove each of those
+three is either intended or inert for a stdio adapter, and `openUrl("")` in the
+CLI login path must not be reached.
+
+## Blocker 2 — preset duplication
+
+`dashboardPreset: true` keeps the row in `deriveProviderPresets`
+(`src/providers/derive.ts:365`), so it would show on a preset tab as well as
+Accounts. Set `dashboardPreset: false`, matching `devin` and `cursor`, and update
+the assertion at `tests/providers/devin-cli-adapter.test.ts:33` that currently
+pins it true. With `authKind` staying local the preset tab would otherwise be
+Free, not Paid, but the duplication is the same defect either way.
+
+## Blocker 3 — login cannot inherit stdio
+
+`010` said to run `devin auth login` with inherited stdio. Dashboard login is
+`POST /api/oauth/login` inside the proxy, typically a launchd process with no
+TTY. Use kiro's working shape instead: piped spawn with `stdin: "ignore"`
+(`src/oauth/kiro.ts:151-156`), surface the CLI's own output through
+`ctrl.onProgress`, and treat a login that cannot complete without a terminal as
+a reported failure rather than a hang. If the CLI turns out to require a TTY, the
+honest end state is an Accounts row that reports signed-in status and tells the
+operator to run `devin auth login` in their own terminal — wp2 decides this
+against the real binary and records which it was.
+
+## Blocker 4 — wrong label file
+
+Accounts rows use `oauthLabel` → `OAUTH_LABELS[id] ?? id`
+(`gui/src/pages/providers-shared.ts:49-59`), not `formatProviderDisplayName`.
+Without an `OAUTH_LABELS` entry the row reads `devin-cli`. `030`'s write set
+moves from `gui/src/provider-icons.ts` to `gui/src/pages/providers-shared.ts`.
+
+## Structure obligation the plan missed
+
+`structure/AGENTS.md:49` binds changes in `src/oauth/` and `src/providers/` to
+`runtime.md`, `subagents.md`, `transports/inventory.md`, and
+`providers/xai-grok.md`, not only `adapters/registry.md`. wp4 checks each for a
+sentence this change falsifies.
+
+## Effect on the work-phase map
+
+wp2 and wp3 swap emphasis: wp2 still builds `src/oauth/devin-cli.ts` (now with a
+piped spawn and no marker-as-bearer concern), wp3 becomes registration plus the
+`dashboardPreset` flip and the three `isOAuthProvider` consequences, with the
+`authKind` flip and its migration DELETED. wp4 is unchanged apart from the label
+file and the structure docs.
+