feat(settings): export DB settings to the CLI's .env

[pnewsam]

Description

This continues efforts to refactor some of the code around updating settings. Because we have multiple sources of truth (.env file and sqlite DB), issues are inevitable unless we write/read to/from these sources in an consistent manner.

This simplifies by enforcing a new one-way data flow. Settings are always written to the DB then replicated to the .env file. In future we may deprecate the .env file but this reduces inconsistency in the meantime. The meatier part of this work is on the client-side PR where we can remove significant code to align around a more consistent write path.

flowchart LR
    write["settings change<br/>(form save / login / logout)"] --> svc["SettingService"]
    svc -->|"1 · commit"| db[("cowork.db<br/>source of truth")]
    svc -->|"2 · derive + write"| env["$COWORK_HOME/.env<br/>(export for the CLI)"]
    env --> cli["anton CLI reads"]

Loading

[github-actions]

No PR environment for this pull request

Add the deploy label and push to create one. It is torn down when the label is removed or the PR closes, so any URL you saw here earlier is gone.

_{Updated on every push to this PR.}

[pnewsam]

Code Review

Verdict: COMMENT — merge-blocking findings

The new boundary is well-factored and the focused settings tests pass, but two consistency gaps still undermine the DB-as-source-of-truth guarantee: the startup Minds URL backfill bypasses export, and concurrent exporters can atomically install a stale snapshot.

Validation

• Targeted settings suite: 30 passed
• Full suite: 698 passed, 1 skipped; 3 unrelated/environment failures

The row-presence handling, tenancy guard, secret permissions, and focused test coverage are otherwise solid.

[pnewsam]

Code Review

Verdict: COMMENT — merge-blocking findings

The earlier backfill and in-process lost-update findings are fixed, but the current export can still produce CLI configurations that Anton cannot run, and it writes DB strings into a startup-sensitive dotenv file without escaping. Overall merge risk is High until the provider/model contract, pinned Anton compatibility, and dotenv serialization findings are addressed. The plaintext-key duplication, retained Electron//settings/raw writer race, best-effort stale export behavior, and isolated-build COWORK_HOME mismatch remain explicit rollout risks.

Validation

• Re-read all 7 changed-file patches at head 653c1791763eeb83f3c9473d610d92a30990459f.
• Inspected the settings write/read paths and existing review resolutions.
• Compared the exported schema with the exact anton-agent commit pinned by this head's uv.lock (c51afe87).
• Confirmed the visible GitHub build/deploy workflow succeeded; no current test status contexts were exposed.
• Source review only; I did not rerun the suite locally.

[pnewsam]

Code Review

Verdict: COMMENT — one merge-blocking finding remains

The provider/model pairing and CR/LF dotenv-injection findings are addressed at this head. The single-provider Gemini/OpenAI-compatible translation also works, but mixed planning/coding/router configurations can still produce a global Anton key/base combination that does not represent any role correctly. Bottom line: keep the Anton-compatibility thread open until mixed providers are handled or explicitly rejected.

Validation

• Re-read the updated settings boundary and regression tests at head de28960b2db4d729938b09347bcc7c3c5426c656.
• Compared the emitted variables with the exact pinned anton-agent settings/provider construction at c51afe87.
• Confirmed the current visible build/deploy workflow succeeded.
• Source review only; I did not rerun the server test suite locally.

[pnewsam]

Code Review

Verdict: COMMENT

The earlier provider/model pairing, Gemini translation, shared OpenAI-slot collision, and CR/LF-injection findings are addressed. Two Major compatibility/state-management edge cases remain, so I do not think this is merge-ready yet.

Validation

• Re-reviewed all 7 changed files at head 76eac509b07428c485435dc50ec4d43dee3a29b0.
• Compared the export behavior with the pinned Anton dependency at c51afe87add12b49bf030190446aab61b55b3a88.
• Confirmed all earlier review threads are resolved.
• GitHub Actions run 527 and the Snyk commit status are successful.

[pnewsam]

Code Review

Verdict: COMMENT

At head dbe81f7, the new export still violates the DB-source-of-truth contract and can produce invalid or misrouted CLI configurations. Three Major findings remain; these should be addressed before merge.

Validation

• Re-reviewed all 7 changed files and the resolved discussion at the current head.
• Relevant settings suites: 85 passed.
• Reproduced the stale raw-sync, missing-base, and router provider/model cases against the pinned Anton dependency.
• git diff --check passed.
• GitHub Actions run 528 and the Snyk commit status are successful.

[pnewsam]

Code review — Phase A (DB→.env export).

The one-way export is sound and unusually well-guarded (atomic write, 0o600, CR/LF injection reject, representability + atomic cluster validation, Windows-lock retry), and the regression coverage is strong. Ran pytest tests/test_env_boundary.py test_settings_raw.py test_settings_schema.py → 32 passed. No blocking issues; a few minor/nit items inline. Verdict: COMMENT.

[pnewsam]

Preserving Claude's notes:

Exceptions (pre-existing, collapsed in Phase B)

.env is not yet a pure one-way copy of the DB, because this PR leaves the older paths alone:

• Startup seeds once in the other direction (the .env→DB migration). It passes export_env=False so it can't rewrite the file it is reading from.
• The client still writes .env itself on onboarding/login to bootstrap the server's first boot. Phase B removes that so the server is the sole writer, and needs a real-build onboarding/login/CLI pass to verify.

Known limitation

The server writes $COWORK_HOME/.env, but the CLI reads a hardcoded ~/.cowork/.env and ignores COWORK_HOME. They are the same file on prod, so the CLI sees the export; on an isolated non-prod build they diverge. Follow-up if we want CLI parity there.

[ZoranPandovski]

Not blocking this PR, but I think this approach adds more complexity to an already complicated settings flow.

To simplify it long term, we should:

1. Update the desktop client so it no longer reads settings from .env and writes them back into the DB.
2. Update the standalone Anton CLI so that, when it starts, it gets the current provider, model, base URL, and credentials from the local Cowork server instead of relying on a mirrored .env file.
3. Once older desktop clients are no longer relying on the current behavior, remove the automatic DB-to-.env export.

I’m fine with this as a temporary compatibility layer, but I think we should make the removal plan explicit so it does not become permanent.

[pnewsam]

@ZoranPandovski That makes sense, this PR adds a lot of code just to accommodate a flow we're already planning to deprecate. So in that sense it may not be a step in the right direction. I think we can go ahead and remove the .env dependency from cowork, if we just include updates on the anton side as well. I'll see if I can rework these PRs to align with that approach.

[lucas-koontz]

Reviewed at 89616e6, as a direction review rather than line by line, since @ZoranPandovski's pushback and your reply land this in "replaced by #280" territory and env_boundary.py is slated for deletion. Line-reviewing 494 doomed lines would just spend your attention twice. Four things worth recording before this closes.

1. #280 fully supersedes this, and the salvage list is empty. I diffed it rather than assuming: env_boundary.py goes 494 to 76 lines (only SETTING_ENV_ALIASES, normalize_provider_value, env_to_db_updates survive), _export_env_for_cli plus the export lock and the export_env kwarg are gone, and GET/POST /settings/raw is deleted outright; anton#313 drops ~/.cowork/.env from _build_env_files() so the CLI reads only ~/.anton/.env.

Everything independently valuable is already carried over: the apply_model_defaults fix deriving router_model from router_provider is byte-identical in #280 (and safe, since router_provider: Provider has a non-None default at user_settings.py:265), along with the alias map, normalize_provider_value, env_to_db_updates, and the COWORK_HOME conftest guard. What gets dropped is moot under the new shape: atomic_write_env, the Windows-lock retry and _is_dotenv_safe have no writer left in cowork-server, and the /raw hardening plus the sync_env_vars_to_db(incoming) narrowing die with the endpoint. Nothing needs porting.

One thing does land untested though: router_model-from-router_provider had its only coverage in tests/test_env_boundary.py, which #280 deletes with the module. Worth a dedicated test in #280.

Recommend closing this in favour of #280 rather than keeping it as a fallback. The two designs write the same file from opposite ends, so "fall back" would mean un-merging #280, not flipping a switch.

2. The one real gap the decoupling opens, worth raising on #280 while it is still a draft. After #524 + #280 + anton#313, nothing writes or clears ~/.cowork/.env, but it still holds plaintext provider keys. Two consequences: any anton install not yet upgraded past #313 keeps reading it and silently runs on frozen credentials (the MindsHub token refresh currently rewrites that file through POST /raw, documented as a caller at settings.py:394, so once the endpoint is gone the CLI keeps the pre-rotation key and 401s with no signal); and logout no longer clears it, so a signed-out machine leaves live keys on disk indefinitely.

flowchart LR
  ref["MindsHub token refresh"] -->|"today: POST /raw"| env["~/.cowork/.env"]
  ref -.->|"after #280: DB only"| db[("cowork.db")]
  env --> old["anton < #313"]
  old --> stale["runs the pre-rotation key, 401s"]
  db --> new["anton >= #313, ~/.anton/.env"]

Loading

A one-shot cleanup in #280 that strips the ANTON_* credential lines (or renames the file) after the DB is seeded closes both. It needs its own sentinel: _env_migrated_v2 (migrations.py:50, 107-109) has already fired on every existing install, so migrate_env_to_db returns early there and cannot carry it.

3. question, for @ZoranPandovski: your step 2 was "the standalone Anton CLI gets the current provider, model, base URL and credentials from the local Cowork server". anton#313 does something materially different: the CLI gets its own ~/.anton/.env and the desktop-to-CLI inheritance is dropped, so a desktop-configured user re-onboards the CLI once. The reasoning (the standalone CLI has to run with no server) is sound and probably better, but it currently lives only in anton#313's description in another repo. Losing "configure once" is a product call rather than a refactor detail, so worth an explicit sign-off here rather than finding it in a draft elsewhere.

4. Two loose ends before this closes. Nothing on this PR points at the replacement: ENG-1295, #280, anton#313 and the reworked cowork#524 are only discoverable from their own descriptions, so the "make the removal plan explicit" ask reads as unanswered on the thread where it was raised. A closing comment linking all four settles it. Separately, #280 keeps sync_env_vars_to_db (migrations.py:79) but deletes its only caller along with POST /raw, leaving it referenced only from a comment in a test; cheap to drop while that PR is still a draft.

For the record, since it is easy to lose when a PR closes: the round-trip test pattern in tests/test_env_boundary.py, feeding the rendered env through the pinned AntonSettings + LLMClient.from_settings, is the best idea in that file. It dies with #280 because nothing renders env anymore, which is correct, but it is the kind of test worth reaching for again the next time we serialize config for another process. I also confirmed the CodeQL "incomplete URL substring sanitization" alert is genuinely fixed rather than merely outdated (head asserts equality against GEMINI_BASE_URL at tests/test_env_boundary.py:45,61 instead of the substring check), so nothing carries forward there.