Skip to content

Commit 6f92853

Browse files
fix: close the late-registration gaps and tidy review findings
- Headless disclosure: `printDisclosureOnceForHeadless` now prints whenever Base is registered and the once-per-install marker is unclaimed, not only when this launch's own registration finished. A registration that outlasted the startup wait finished in the background and every later launch reported "already registered", so the notice was never shown. The marker is claimed with an exclusive create before printing, so concurrent launches print once. - Register route: skip the process-wide reload only when the credential is unchanged AND Base is already in this server's provider list. After a background auto-registration (or a credential refreshed in place) the file is unchanged but the cached provider state predates it. - Move `isPublicZen` out of the `Provider` namespace into `provider/public-zen.ts` (packages/opencode/AGENTS.md "Module shape"). - Restore `altimate_base_register_result` for picker registrations during first-run onboarding (welcome picker `origin: "welcome"`, catalogue and provider dialog `origin: "model"`), as the removed confirm component did. - Cap the persisted 429 auto-register backoff at 24 hours, and serialise the backoff record's read-modify-write under its own file lock. - Docs: registration happens on every unregistered install, whether or not the user has a model of their own; logout keeps automatic registration off until Base is picked again; fleet audits look for `altimate-base.json`; the `ALTIMATE_CLI_CLIENT=datamates` skip applies to `serve`; the registration telemetry row covers the server route. - Tests: route reload when Base is not loaded, backoff cap, headless disclosure after a background registration, picker result callback; the explicit-model test restores its env even if mounting fails. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_016x3nbZU5Vb6HnSTqE7vELm
1 parent daa773c commit 6f92853

20 files changed

Lines changed: 252 additions & 67 deletions

‎docs/docs/configure/providers.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,14 @@ If you need stronger guarantees — no training on your data, metadata-only rete
6262
[Altimate LLM Gateway](https://help.altimate.ai/datamates/user-guide/components/llm-gateway/)
6363
instead.
6464

65-
Choose **Altimate Base** from the first-run picker or `/connect` — or do nothing at all: a fresh
66-
install with no model of its own registers it automatically, before your first prompt, so it works
67-
the same way headlessly (`run`, `serve`, `acp`, `web`). There is no confirmation dialog to accept.
68-
The disclosure above is printed once per install the first time this happens — a toast in the TUI,
69-
or a one-line notice to stderr for a headless entrypoint (skipped when `ALTIMATE_CLI_CLIENT=datamates`,
70-
since the VS Code extension shows its own notice). After registration, the model is available as
65+
Choose **Altimate Base** from the first-run picker or `/connect` — or do nothing at all: every
66+
install that is not yet registered registers it automatically at startup, before your first prompt,
67+
so it works the same way headlessly (`run`, `serve`, `acp`, `web`). This happens whether or not you
68+
also have a model of your own; a registered Base only becomes your default when nothing you
69+
configured is usable. There is no confirmation dialog to accept.
70+
The disclosure above is printed once per install the first time Base is registered — a toast in the TUI,
71+
or a one-line notice to stderr for a headless entrypoint (`serve` skips it when
72+
`ALTIMATE_CLI_CLIENT=datamates`, since the VS Code extension shows its own notice). After registration, the model is available as
7173
`altimate-free/altimate-base` and becomes the free fallback when no paid Altimate Gateway or
7274
explicit model is selected. Big Pickle is retired as a new selection — it no longer appears in the
7375
picker or the full model catalog for users choosing a model for the first time. Users already on
@@ -81,16 +83,18 @@ To opt out: set `ALTIMATE_BASE_AUTO_REGISTER=0` before this install first regist
8183
`altimate providers logout altimate-base` afterward, or keep it out of your own choices with
8284
`enabled_providers` / `disabled_providers`. The env var is the only one of these that stops the
8385
background registration call itself; the other two only control whether Base can be *selected* as
84-
your model on this machine — logging out also un-registers it (it will auto-register again on the
85-
next launch unless the env var is also set).
86+
your model on this machine. Logging out un-registers it and also stops automatic registration on
87+
this machine: later launches skip it until you pick Altimate Base again in the picker (or an IDE
88+
calls the registration route), which reconnects it.
8689

8790
Registration is per machine, not per host: once any host on a machine has registered Altimate
8891
Base (auto-registration on any entrypoint, or the HTTP registration route used by IDE
8992
integrations), every other host on that machine treats Base as the default free model too — the
9093
TUI migrates an implicit free default silently, and headless `altimate run`, `altimate serve`, and
9194
ACP sessions resolve to Base ahead of the keyless public Zen tier. Logging out on any host applies
9295
to all hosts on the machine, since the credential is a single shared file. Administrators auditing
93-
a fleet can check for the registered `altimate-free` provider entry in `auth.json`.
96+
a fleet can check for the Altimate Base credential file, `altimate-base.json`, in the data directory
97+
(it is stored separately from the shared provider-auth file).
9498

9599
Official release binaries embed the current gateway endpoint at build time. Operators and local
96100
development can override it without changing code:

‎docs/docs/getting-started/quickstart.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ On a fresh install, a welcome panel appears with a curated 6-provider picker:
2525

2626
- **Altimate LLM Gateway** *(recommended)* — 10M tokens free, no API keys. Routes to the best model per task across Sonnet, Opus, GPT-5, and more. Sign-in opens a browser tab; complete Google or email signup and you're back in the TUI. If your terminal can't open a browser (SSH / tmux / WSL), the CLI prints the URL — paste it into a browser on your desktop.
2727
- **Anthropic** / **OpenAI** / **Google** — paste an API key or OAuth in.
28-
- **Altimate Base** — a hosted open model, free and rate limited, with no signup or API key. Requests and responses may be logged and used to improve Altimate's products, so do not send secrets or confidential code. If you don't pick another provider, a fresh install registers it automatically — there is no confirmation dialog — and prints this notice once. Opt out with `ALTIMATE_BASE_AUTO_REGISTER=0`, `altimate providers logout altimate-base`, or `disabled_providers` (see [providers](../configure/providers.md#altimate-base)).
28+
- **Altimate Base** — a hosted open model, free and rate limited, with no signup or API key. Requests and responses may be logged and used to improve Altimate's products, so do not send secrets or confidential code. Every install registers it automatically at startup, whichever provider you pick — there is no confirmation dialog — and shows this notice once; it only becomes your model when nothing else you configured is usable. Opt out with `ALTIMATE_BASE_AUTO_REGISTER=0`, `altimate providers logout altimate-base`, or `disabled_providers` (see [providers](../configure/providers.md#altimate-base)).
2929
- **Search all providers…** — full picker if you need Bedrock, Databricks AI Gateway, Cloudflare AI Gateway, Snowflake Cortex, DigitalOcean Inference, etc.
3030

3131
Or set an environment variable and skip the picker:

‎docs/docs/reference/network.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ altimate needs outbound HTTPS access to:
4141
| Destination | Purpose |
4242
|-------------|---------|
4343
| Your LLM provider API | Model inference (Anthropic, OpenAI, etc.) |
44-
| Official Altimate Base gateway (embedded in release), or the host set by `ALTIMATE_BASE_GATEWAY_URL` | Altimate Base registration (automatic on a fresh install with no model of its own, unless `ALTIMATE_BASE_AUTO_REGISTER=0`) and inference |
44+
| Official Altimate Base gateway (embedded in release), or the host set by `ALTIMATE_BASE_GATEWAY_URL` | Altimate Base registration (automatic at startup on any install not yet registered, unless `ALTIMATE_BASE_AUTO_REGISTER=0` or after logging out of Base) and inference |
4545
| `registry.npmjs.org` | Package updates |
4646
| `models.dev` | Model catalog (can be disabled) |
4747
| Your warehouse endpoints | Database connections |

‎docs/docs/reference/security-faq.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,14 @@ Answers to the most common security questions about running Altimate Code in you
1313

1414
Altimate Code sends prompts and context to the LLM provider you configure (Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, etc.). **You choose the provider.** No data is sent anywhere else except optional [telemetry](#what-telemetry-is-collected), which contains no code, queries, or credentials.
1515

16-
Altimate Base is Altimate's own hosted free model. A fresh install with no model of its own
17-
registers it automatically — there is no confirmation dialog to accept. Requests and responses are
16+
Altimate Base is Altimate's own hosted free model. Every install that is not yet registered
17+
registers it automatically at startup, whether or not you also have a model of your own — there is
18+
no confirmation dialog to accept. It only becomes your default model when nothing you configured is
19+
usable. Requests and responses are
1820
logged and may be used to improve Altimate products and services, including the model; secrets are
1921
automatically masked before storage, but don't rely on it — avoid sending secrets or confidential
2022
code. This notice is printed once — a toast in the TUI, or a one-line stderr notice the first time
21-
a headless entrypoint (`run`, `serve`, `acp`, `web`) registers it — and is part of the Altimate
23+
a headless entrypoint (`run`, `serve`, `acp`, `web`) runs with Base registered — and is part of the Altimate
2224
Base service, separate from anonymous product telemetry. To opt out: set
2325
`ALTIMATE_BASE_AUTO_REGISTER=0` before Base ever registers, run `altimate providers logout
2426
altimate-base` afterward, or exclude it from your own model choices with `enabled_providers` /
@@ -115,7 +117,7 @@ You can also configure per-agent permissions. For example, restrict the `analyst
115117
| Destination | Purpose |
116118
|-------------|---------|
117119
| Your configured LLM provider | Model inference |
118-
| Altimate Base gateway | Registration (automatic on a fresh install with no model of its own) and inference |
120+
| Altimate Base gateway | Registration (automatic at startup on any install not yet registered) and inference |
119121
| Your warehouse endpoints | Database queries |
120122
| `registry.npmjs.org` | Package updates |
121123
| `models.dev` | Model catalog (can be disabled) |

‎docs/docs/reference/telemetry.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ We collect the following categories of events:
4545
| `first_launch` | Fired once on the first CLI run after an install or upgrade, triggered by a marker file the installer wrote — the installers themselves send nothing and contact no telemetry endpoint. Contains the installed version, `is_upgrade`, and `install_method` (`curl`, `powershell`, `npm`, `vscode-extension`, `local` for `install --binary`, or `unknown` for markers written before the field existed). `vscode-extension` starts appearing only once an extension build containing the marker write ships, so a zero share for it means the extension has not rolled out yet rather than no extension installs. No PII. **Reading `is_upgrade`:** it means "this machine had run altimate-code before", probed as whether `~/.altimate/machine-id` already existed — *not* "a binary was already present". A reinstall onto a machine that ever ran the CLI reports `is_upgrade: true`, and `altimate uninstall` leaves `machine-id` in place, so a metric excluding upgrades counts installs **per previously-unseen machine** and undercounts reinstalls onto known ones. (`is_upgrade` is a boolean in the event schema; it arrives in Application Insights `customDimensions` as a string, so KQL filters read `tostring(customDimensions.is_upgrade) != "true"`.) Delivery is at-most-once: the marker is deleted before the event flushes, so a process that dies first loses that install rather than re-firing it every launch. Local `--binary` installs report `version: "local"`. |
4646
| `startup_ready` | Fired once per process when the top-level command can serve its first request or frame (`serve` listening, TUI transport resolved, `run` about to send its first prompt). Contains the command name, `duration_ms` since process start, and `fresh_install` (true when this process also emitted a non-upgrade `first_launch`). No PII. |
4747
| `event_loop_stall` | A 250 ms monitor tick fired more than 1 s late, meaning the event loop was blocked for that long (for example an in-process dependency install). Contains the command name, `thread` (`main` or `worker`), `blocked_ms`, and `since_start_ms`. Capped at 20 per thread (the main thread and the TUI server worker each keep their own counter). No PII. |
48-
| `altimate_base_registration` | Timing and outcome of each Altimate Base registration, whether triggered automatically at startup or by an explicit picker selection (concurrent calls share one result, and a still-valid cached credential reports `success` without a network round trip): `result` (`success`, `network`, `http`, `response`, `cancelled`, `configuration`, or `error`), `duration_ms`, and the HTTP `status` when the result is `http`. Distinct from `altimate_base_register_result`, which records the onboarding-flow outcome. No gateway URL, response body, credential, or error text is included. |
48+
| `altimate_base_registration` | Timing and outcome of each Altimate Base registration, whether triggered automatically at startup, by an explicit picker selection, or through the `POST /altimate/base/register` route an IDE calls (`origin: "server"`) (concurrent calls share one result, and a still-valid cached credential reports `success` without a network round trip): `result` (`success`, `network`, `http`, `response`, `cancelled`, `configuration`, or `error`), `duration_ms`, and the HTTP `status` when the result is `http`. Distinct from `altimate_base_register_result`, which records the onboarding-flow outcome. No gateway URL, response body, credential, or error text is included. |
4949
| `task_outcome_signal` | Behavioral quality signal at session end — accepted, error, abandoned, or cancelled. Includes tool count, step count, duration, and last tool category. No user content. |
5050
| `task_classified` | Intent classification of the first user message using keyword matching — category (e.g. `debug_dbt`, `write_sql`, `optimize_query`), confidence score, and detected warehouse type. No user text is sent — only the classified category. |
5151
| `tool_chain_outcome` | Aggregated tool execution sequence at session end — ordered tool names (capped at 50), error count, recovery count, final outcome, duration, and cost. No tool arguments or outputs. |

‎packages/opencode/src/acp/service.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,9 @@ import { ProviderV2 } from "@opencode-ai/core/provider"
4444
import { ModelV2 } from "@opencode-ai/core/model"
4545
import { Provider } from "@/provider/provider"
4646
import type { Command } from "@/command"
47+
// altimate_change start — keyless public Zen predicate (flat module)
48+
import { isPublicZen } from "@/provider/public-zen"
49+
// altimate_change end
4750

4851
export const AuthMethodID = "opencode-login"
4952

@@ -878,7 +881,7 @@ export function defaultModelFromConfig(
878881
// altimate_change — a stale recent pick of the now-broken keyless public Zen tier is replaced
879882
// by registered Base rather than replayed; it is guaranteed to fail otherwise. A
880883
// credentialed/paid selection is never overridden.
881-
if (registeredBaseAvailable && Provider.isPublicZen(provider)) continue
884+
if (registeredBaseAvailable && isPublicZen(provider)) continue
882885
return { providerID, modelID }
883886
}
884887

@@ -903,7 +906,7 @@ export function defaultModelFromConfig(
903906
if (id === "altimate-free") return false
904907
if (hasProviderAllowlist && !Object.prototype.hasOwnProperty.call(providerFilter, id)) return false
905908
const info = providers[ProviderV2.ID.make(id)]
906-
if (registeredBaseAvailable && info && Provider.isPublicZen(info)) return false
909+
if (registeredBaseAvailable && info && isPublicZen(info)) return false
907910
return true
908911
}
909912
const opencodeProvider = providerAllowed("opencode") ? providers[ProviderV2.ID.make("opencode")] : undefined
@@ -976,7 +979,7 @@ function isStalePublicZenSnapshotModel(snapshot: Directory.Snapshot, model: Dire
976979
const registeredBaseAvailable = Boolean(baseProvider?.models[ModelV2.ID.make("altimate-base")])
977980
if (!registeredBaseAvailable) return false
978981
const provider = snapshot.providers[model.providerID]
979-
return Boolean(provider && Provider.isPublicZen(provider))
982+
return Boolean(provider && isPublicZen(provider))
980983
}
981984
// altimate_change end
982985

‎packages/opencode/src/altimate/free/client.ts‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -531,14 +531,17 @@ function autoRegisterDisabledByEnv(): boolean {
531531
// mirroring the disclosure marker in consent.ts) and read at the start of every `autoRegister()`
532532
// call, including the first one in a brand-new process.
533533
const AUTO_REGISTER_BACKOFF_MS = 60 * 60 * 1000 // 1 hour
534+
// A gateway or proxy sending an enormous Retry-After must not disable auto-registration for days.
535+
const AUTO_REGISTER_BACKOFF_MAX_MS = 24 * 60 * 60 * 1000 // 24 hours
534536

535537
function autoRegisterBackoffMs(
536538
kind: Exclude<RegistrationResult, "success">,
537539
error: unknown,
538540
): number | undefined {
539541
if (kind === "network") return AUTO_REGISTER_BACKOFF_MS
540542
if (kind === "http" && error instanceof RegistrationError) {
541-
if (error.status === 429) return Math.max(AUTO_REGISTER_BACKOFF_MS, error.retryAfterMs ?? 0)
543+
if (error.status === 429)
544+
return Math.min(AUTO_REGISTER_BACKOFF_MAX_MS, Math.max(AUTO_REGISTER_BACKOFF_MS, error.retryAfterMs ?? 0))
542545
if (error.status !== undefined && error.status >= 500) return AUTO_REGISTER_BACKOFF_MS
543546
}
544547
return undefined
@@ -584,17 +587,26 @@ async function getPersistedAutoRegisterBackoff(gateway: string): Promise<number
584587
return record[gateway]
585588
}
586589

590+
// Concurrent entrypoints (a TUI and a `serve`, say) can update the record at the same moment; the
591+
// read-modify-write runs under its own lock so one cannot drop or resurrect the other's entry.
592+
// Not LOCK_KEY: these run after the registration lock is released, and must not queue behind it.
593+
const BACKOFF_LOCK_KEY = "altimate-base-auto-register-backoff"
594+
587595
async function setPersistedAutoRegisterBackoff(gateway: string, until: number): Promise<void> {
588-
const record = await readAutoRegisterBackoffRecord()
589-
record[gateway] = until
590-
await writeAutoRegisterBackoffRecord(record)
596+
await Flock.withLock(BACKOFF_LOCK_KEY, async () => {
597+
const record = await readAutoRegisterBackoffRecord()
598+
record[gateway] = until
599+
await writeAutoRegisterBackoffRecord(record)
600+
}).catch((error) => log.warn("failed to update Altimate Base auto-register backoff", { error }))
591601
}
592602

593603
async function clearPersistedAutoRegisterBackoff(gateway: string): Promise<void> {
594-
const record = await readAutoRegisterBackoffRecord()
595-
if (!(gateway in record)) return
596-
delete record[gateway]
597-
await writeAutoRegisterBackoffRecord(record)
604+
await Flock.withLock(BACKOFF_LOCK_KEY, async () => {
605+
const record = await readAutoRegisterBackoffRecord()
606+
if (!(gateway in record)) return
607+
delete record[gateway]
608+
await writeAutoRegisterBackoffRecord(record)
609+
}).catch((error) => log.warn("failed to clear Altimate Base auto-register backoff", { error }))
598610
}
599611

600612
// Test-only: this file is otherwise process-global state with no reset hook, so a backoff set by

‎packages/opencode/src/altimate/free/consent.ts‎

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -102,20 +102,7 @@ function disclosureMarkerPath(): string {
102102
return path.join(path.dirname(FreeTierStore.credentialPath()), "altimate-base-disclosure-shown.json")
103103
}
104104

105-
async function disclosureAlreadyShown(): Promise<boolean> {
106-
try {
107-
await fs.access(disclosureMarkerPath())
108-
return true
109-
} catch {
110-
return false
111-
}
112-
}
113105

114-
async function markDisclosureShown(): Promise<void> {
115-
const target = disclosureMarkerPath()
116-
await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 })
117-
await fs.writeFile(target, JSON.stringify({ shownAt: new Date().toISOString() }) + "\n", { mode: 0o600 })
118-
}
119106

120107
/**
121108
* Print the Base disclosure to stderr for a headless entrypoint, once per install. A no-op unless
@@ -125,10 +112,31 @@ async function markDisclosureShown(): Promise<void> {
125112
* later launch, never blocks startup.
126113
*/
127114
export async function printDisclosureOnceForHeadless(justRegistered: boolean): Promise<void> {
128-
if (!justRegistered) return
129-
if (await disclosureAlreadyShown().catch(() => false)) return
115+
// A registration that outlasted the startup wait finishes in the background, and every later
116+
// launch reports "already registered", so this launch's own result cannot be the only trigger:
117+
// print whenever Base is registered and the once-per-install marker is not yet set.
118+
const registered = justRegistered || (await FreeTier.isRegistered().catch(() => false))
119+
if (!registered) return
120+
// Claim the marker before printing: an exclusive create lets exactly one of several concurrent
121+
// headless launches win, so the notice cannot print twice. If the claim fails for any other
122+
// reason (unwritable directory), print anyway — a repeat is better than a missed notice.
123+
const claimed = await claimDisclosureMarker()
124+
if (claimed === "taken") return
130125
console.error(`Altimate Base: ${ALTIMATE_BASE_DISCLOSURE}`)
131-
await markDisclosureShown().catch(() => {})
126+
}
127+
128+
async function claimDisclosureMarker(): Promise<"claimed" | "taken" | "unavailable"> {
129+
const target = disclosureMarkerPath()
130+
try {
131+
await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 })
132+
await fs.writeFile(target, JSON.stringify({ shownAt: new Date().toISOString() }) + "\n", {
133+
mode: 0o600,
134+
flag: "wx",
135+
})
136+
return "claimed"
137+
} catch (error) {
138+
return (error as NodeJS.ErrnoException).code === "EEXIST" ? "taken" : "unavailable"
139+
}
132140
}
133141
// altimate_change end
134142

0 commit comments

Comments
 (0)