Introduce AGENTS.md (root, primary agent instruction file) documenting six
hard-won fixes with explicit DO NOT / WHY, plus executable enforcement so a
future AI cannot delete or reintroduce them:
1. package-lock.json must be generated with npm 10 (Docker's npm 10.9.8).
npm 11 drops the top-level @emnapi/core + @emnapi/runtime entries npm 10
needs, breaking the tag-triggered Docker build at `npm ci` (happened on
v1.0.14). Add scripts/verify-lockfile-npm10.mjs + .npmrc + a Dockerfile
fail-fast check + a CI step + tests/unit/lockfile-npm10-guard.test.js.
Also re-fix the lockfile itself (regenerated with npm 10.9.8).
2. Tests must never write to the real ~/.9router DB (isolateDataDir).
3. Hidden providers must not leak into Usage (usageProviders !p.hidden).
4. codebuddy-intl connection test + OAuth identity.
5. Fork-only features that must survive upstream syncs.
6. Upstream sync procedure.
Each marker cross-references AGENTS.md and the covering test. CLAUDE.md now
points to AGENTS.md at the top. Verified: build ok, guard script passes,
full suite leaves the real DB count unchanged (38), 0 new regressions.
Root cause of fake connections in Usage (zed-live-*@example.com,
guard-*@example.com, zed "Account N", kimchi-nope): route-level tests
(zed-live-models, zed-native-auth) call createProviderConnection, which
persists to $DATA_DIR/db/data.sqlite. With DATA_DIR unset — the default
for `npx vitest run` — that resolved to the user's real ~/.9router DB,
appending test rows on every run. Both files documented "RUN WITH AN
ISOLATED DB" but never enforced it.
Add tests/setup/isolateDataDir.js (wired via vitest setupFiles) that
points DATA_DIR at a throwaway temp dir before src/lib/dataDir.js is
imported. Opt out with RUN_REAL=1 or an explicit DATA_DIR (used by the
*.real.test.js suites that read live credentials).
Verified: a full suite run now leaves the real DB byte-count unchanged;
new guard test tests/unit/test-data-dir-isolation.test.js locks it in.
The Usage page auto-adds every noAuth free provider so connectionless
providers (opencode) still appear. It did not filter the registry's
hidden flag, so devin-cli and mimo-free — both category:"free" with
noAuth:true and hidden:true — showed up in Usage despite having no
connection and being absent from the Providers page (which does filter
hidden).
Extract the list assembly into buildUsageProviderList (shared/utils/
usageProviders.js) and skip hidden free providers there. Behavior for
visible noAuth providers (opencode) and dedup of active connections is
unchanged; covered by tests/unit/usage-provider-list.test.js.
Two bugs on codebuddy-intl connections:
1. Test Connection always failed with "Provider test not supported":
codebuddy-intl was missing from OAUTH_TEST_CONFIG, so testOAuthConnection
bailed before probing. Add a real probe against the Keycloak realm's
userinfo endpoint (URL derived from the token's iss claim), and wire
refreshable so an expired token is rotated via refreshCodebuddyIntlToken.
2. OAuth logins were named "Account N" with no email: mapTokens returned no
identity, even though the access token is a Keycloak JWT carrying
email/name claims. Extract email + displayName in mapTokens (new shared
extractDisplayNameFromAccessToken helper) so fresh logins are named and
deduped by identity.
Also add a run-once backfill (backfillCodeBuddyIntlIdentity) invoked from
GET /api/providers and /api/providers/client to self-heal existing rows
(backfill email/displayName, rename the generic "Account N" placeholder).
Verified live: the real connection now returns valid:true and the row is
renamed to the account email.
Upstream f6e7cabe stopped workos:-prefixing opaque tokens (ClinePass API
keys like clp_...), so getClineAccessToken now only prefixes WorkOS JWTs.
The fork's test asserted the old unconditional-prefix behavior.
gitbook-pages.yml deployed to upstream org's 9router.github.io which a fork
cannot (no GH_PAGES_DEPLOY_KEY) — renamed to .yml.disabled. Dockerfile gains
a /api/health HEALTHCHECK. .env.example documents the new pool geostrobes
env knobs (POOL_GEO_PROBE_DISABLED, GEO_PROBE_URL).
New /api/system/memory reports db + data-dir sizes and in-memory state
(fitness/geo registries, freebuff session/cooldown counts); profile page
'Local Mode' card gets a Check Size Memory button rendering the summary.
Geo-probe toggle hint localized to English.
Header toggle in Proxy Fitness persists settings.poolGeoProbeEnabled
(default on); the probe scheduler reads it each pass and skips when off.
The env POOL_GEO_PROBE_DISABLED remains a hard override. Smart rotation is
unaffected — it runs off the fitness registry from real request failures.
Try ipwho.is -> ip-api.com -> ipapi.co -> ipinfo.io in order so a
rate-limited/broken provider falls through to the next; ipinfo (most
quota-bound) is last. Normalize each payload to {ip,country,region,city,org},
keep 15s timeout per endpoint, and support GEO_PROBE_URL to replace the
chain with a single custom endpoint.
Refuse re-probing failures too fast: 500/429 failures get a 2h backoff,
other errors 30m (flapping relays/quota stops hammering ipinfo every pass,
passes every 30 min instead of 15). One-line summary per pass
(geo N/M · fail: rate×a server×b) replaces the per-pool error wall.
New env POOL_GEO_PROBE_DISABLED=1 turns the feature off.
Remove [DBG:STREAM] chunk/pipe/EOF instrumentation and [DBG:SSE] flush +
fetch success lines that spam the dev console every request. Keep the stream
stall watchdog and the fetch-error (✖) diagnostics.
Unrecoverable refresh errors (invalid_grant/invalid_request) are persisted as
a refreshBlocked marker so the background scheduler stops hammering the
provider every 5 minutes and surfaces re-login required; the marker is lifted
automatically when a later refresh succeeds. Cooldown maps gained lazy pruning.
Background probe fetches ipinfo through each pool itself (provider-agnostic
transport), fills an egress IP/country cache (TTL 1h, 8-IP history) and flags
flapping relays as unstable. Periodic state sweeper (10 min) prunes expired
fitness marks, stale geo/ip-history and Freebuff session/cooldown state;
schedulers skip non-server runtimes. Unit tests for the geo cache.
Pool/IP fitness registry (globalThis-backed, provider::model scopes, 5-min
cooldown, provider::* wildcard) fed by pool-scoped failures: freebuff
limited-IP / model-locked gates and opencode free per-IP limits. chatCore
retries a failed pool via another pool without locking the account; new
Smart rotation strategy (per-connection + no-auth providers) skips unfit
pools. Proxy Fitness dashboard page: active-block table with provider/IP
filters, per-record Clear and provider-scoped Clear All; egress column via
pool geo enrichment. Unit tests for the registry.
MUH. IQRAM BAHRING