🤖 feat(backup): back up and restore portable top-level config settings - #4229

Summary

Settings backup now carries the portable top-level config.json settings and restores them: per-agent model overrides (agentAiDefaults: model, thinking level, reasoning mode, enabled and advisor flags, sub-agent profile), default and hidden models, minimum thinking levels, model fallbacks, advisor settings, task settings, heartbeat and goal defaults, transcript width, debug-log toggle, runtime enablement and default runtime, and layout presets. Before this change the backup exported only a subset of userPreferences, so a restore on another machine left every one of these at the target's values.

Status

Head 12327c89. Paused for a scope decision (16:40Z). The automatic Codex pair on this head (rounds 11 and 12) completed: security clean; code review with two P2 findings. (1) Invalidated pre-write layout read: the generation guard keeps a stale getConfigForWrite response out of React state but still returns it, so a layout edit racing a restore is derived from the pre-restore presets; the read-modify-write window predates this PR, the guard made it observable. This is the fourth consecutive round with a new ordering finding in the layout mechanism (rounds 4/5, 7/8, 9/10, 11), so under the repository's non-convergence rule the next step is Mike's decision, put to him in the authoring chat: bounded fix forward (re-read when the pre-write fetch was invalidated), or take layoutPresets and the live layout refresh out of this PR, or keep as-is with a reasoned pushback. (2) Normalization-rejected values reset the target: a value the loose on-disk schema accepts but load-time normalization rejects (defaultModel: "garbage", a malformed hidden-models entry, an unknown runtime id, a layout slot the normalizer drops) was recorded as a null reset, deleting the target's valid setting instead of being reported as unsupported. Confirmed and fixed locally in 4d4f4b20 (fieldSchema tightened to what each normalizer accepts; empty spellings still mean unset; new test fails without it; 413 backup tests, typecheck, lint green), held unpushed so the branch takes one review pair after the decision. Since 27c72b9b this head carries the fixes for the three round-9 findings (runtime keys dirty-tracked at startup; one generation counter across every UILayoutsProvider request; last loaded presets kept when a later refresh fails), each with a regression test that fails without it. CI on this head: every job green except Codex Comments and Required, which fail while Codex threads are open. No remote UAT round has run on 12327c89; the delta since 27c72b9b (UAT round 5, passed) is renderer ordering and startup seeding covered by unit tests. Caveat alongside the deferred items: UAT round 5 showed that restoring defaultModel: null clears the key and a second origin of the same backend re-imports its stale mirror on reload (V3-01..V3-03); the UI has no way to clear the default model, so this state is newly reachable through restore, and the pre-existing import condition alone does not make it safe (see Deferred). Earlier provenance (Mike's direct merge request, rounds 7 to 10 beyond the six-review ceiling set for this PR, the Test / Unit QuickJS flake and its baseline) is condensed in the ledger toggle.

Background

Restoring a backup did not bring back the exec/plan model overrides configured under Settings > Agents, or any other top-level setting. createBackupPayload wrote AGENTS.md, agents, skills, global memory, redacted mcp.jsonc and a preferences.json projected from userPreferences alone; nothing read the rest of the config.

Implementation

• src/node/services/backup/settingsProjection.ts: a fail-closed allowlist of the portable keys with the exclusion rationale (machine/network-local values, governor secrets, credential-derived routing, destructive archive policies, legacy save-time projections, internal state). Keys are validated one at a time against AppConfigOnDiskSchema (the on-disk schema is passthrough, so a picked object would carry any key of a repository-controlled document into the config).
• The export is a complete snapshot: every listed key is present and null means unset, so a setting the user reset to its default (cleared agent overrides, deleted fallback chains, full-width off) round-trips as that default instead of a gap the restore fills from the target. agentAiDefaults spells its empty state as {}, the value config load normalizes to. A key that is absent from the block (an older build's export) keeps the local value.
• One NORMALIZE table maps each key to the canonical in-memory value using the same functions Config applies on save and load (exported from src/node/config/index.ts for that purpose). Export, read, merge and the post-write verification share it, so a schema-valid but non-canonical document (a padded model string, an unsanitized fallback chain) compares equal to what config.json holds after the write instead of tripping the post-write IO_ERROR after files were written.
• The block rides inside preferences.json under a sibling settings key. No new payload file and no schema bump: older builds refuse unknown payload paths while parsing the manifest, but their non-strict UserPreferencesSchema strips the unknown key, so they keep restoring what they understand.
• Restore merges each present key over the local config inside the same editConfig edit as preferences (hiddenModels also marks migrations.hiddenModelsInitialized, as the UI path does); preview flags preferences.json as modified when settings differ.
• Downgrade tolerance: a key whose value fails this build's schema (a thinking level or runtime added by a newer build, or a damaged document) keeps its local value instead of failing the whole restore. Preview and restore results name such keys in unsupportedSettings (same pattern as projectBundleSkipped) and the Backup section shows them, so the user knows what to reapply after updating.
• Renderer: model, agent and runtime defaults are read from localStorage mirrors seeded from the backend at startup. A restore rewrites config behind them, which left Settings > Models and Runtimes stale and let the next hide/unhide persist the stale list over the restored one. Seeding now lives in seedConfigMirrors (authoritative: a value the backend no longer holds clears the mirror; startup dirty keys stay protected) and the Backup section re-seeds after a successful restore. UILayoutsProvider refreshes on onConfigChanged so restored layout presets apply without a reload.
• Backup section's "Included" list gains "Model and agent settings".

Validation

• Remote dogfood UAT through Coder Agents on two isolated Xum roots: round 1 on ece81ce2 verified export contents, exclusion of machine-local keys (including a grep of the whole backup repository for locally set marker values), preview/restore/re-preview, older-format and malformed backups, and found the stale-mirror clobber fixed in 116832b0; round 2 on 116832b0 passed (clobber fix confirmed, cross-tab Models and Runtimes live, machine-local keys smuggled into the block ignored, sanity). Round 3 on the final head aad7583a passed every scenario: reset round-trip with the 19-key snapshot and no archive keys in preferences.json, clobber and reload, Runtimes live, restored layout preset applied without a reload, unsupported-settings notice (a tampered thinkingLevel skipped and named after Preview and after Restore, restore not refused, the valid defaultModel next to it applied, local agent defaults untouched), and sanity on both roots. 27 unique screenshots plus the exported preferences.json and manifest. Round 4 on b8b2bc38 passed every scenario (35 unique screenshots): unknown layout preset version and non-object document reported as unsupported with the local slot untouched and still applying, notice cleared by save, preview and backup, unset advisor cap exported as 3 and an explicit unlimited cap as null with both applied on the target, layout refresh ordering under rapid restore-and-apply cycles, and the round-3 regression set. The critic noted that the notice stays while a Back up now attempt is in flight or fails; that is intended: a failed push does not replace the remote bundle, so the preview and the notice describing it remain accurate and are cleared together on success. Round 5 on the final head 27c72b9b (27 unique screenshots, adjudicated PASS for the targeted scenarios): V1 corrupt layout shapes ({"version":2,"slots":"corrupt"}, {"version":2,"slots":{"1":{"name":5}}}) reported as unsupported, restore completes, layoutPresets byte-identical before and after, slot 1 still applies; V2 a restore failing after its snapshot (project-memory file flipped read-only at the config rewrite by a timing watcher, a harness contrivance that was deterministic in three attempts) shows the snapshot path in the error, config already holds the restored default and hidden models, and the Models page reflects them live, keeps them when one more model is hidden, and after reload; V4 regression smoke (exec override reset live, 19-key block without archive keys, hidden-model clobber, layout version 3 unsupported, unset advisor cap exported as 3) passed; V5 sanity passed. V3 is an observation, not a pass: the manual control (clearing the default model in the UI) is not reachable because the UI has no way to clear it, and after restoring defaultModel: null at one origin a reload of a second origin (localhost versus 127.0.0.1, same backend) re-imported that origin's stale default model into config, which the first origin then showed after its reload; hiddenModels was unaffected. Cosmetic, pre-existing: the post-snapshot failure message joins two sentences without punctuation. Evidence under .mux-uat/round-5/ in the authoring workspace.
• Unit and integration tests: projection inclusion/exclusion and null-means-unset, canonicalization of non-canonical input, wholesale merge semantics, unsupported values skipped and named through preview and restore, the older-build strip guarantee, restore through a real Config against a bare origin repository (including a source that reset its settings clearing the target's overrides), mirror re-seeding and clearing (including dirty runtime keys during the startup load), layout refresh ordering (out-of-order responses, a refresh completing after a save, a failed refresh after a successful load, the initial-load fallback).
• tests/ui/BackupSection.test.ts has 7 failures on this branch that reproduce identically on the base commit 023701d; they are pre-existing and unrelated.

Risks

• Restore semantics: a key present in the backup replaces the local value wholesale, including null resetting it to the default; only a key absent from the block leaves the target untouched. Restores now write into settings other services read at runtime (agent defaults, model fallbacks, task settings); every value passes the on-disk zod schema and the existing save/load normalization, and the safety snapshot taken before a restore also carries the settings block, so the undo path covers them.
• Archive behaviors (worktreeArchiveBehavior, coderWorkspaceArchiveBehavior) are deliberately not portable: a repository-controlled "delete" would make later archives destructive with no prompt naming the policy.
• WorkspaceContext startup seeding moved into the shared helper; the one behavior change is that a backend without a stored default model or hidden list now clears the corresponding mirror instead of leaving a stale value. Dirty-key protection now covers the runtime keys as well as the model keys, so a toggle made during the initial config load survives it.

Deferred (pre-existing, found during UAT)

Owner: Mike (this note is the follow-up record; issues to be filed on request). Trigger: after this PR merges, or earlier if one of them bites.

• Checksum-mismatch error gives no remediation guidance.
• No undo control for a restore in the UI (the safety snapshot path is reported in the status message).
• Settings sections paint defaults before the config fetch resolves.
• manifest.json sourceLabel is the exporting root's directory name.
• Post-write verification window (thread). Disposition: the base already ran this exact check for userPreferences (edit, then a synchronous loadConfigOrDefault() read-back compared through the backup projection); this PR widens the compared set to the settings block, so more writers can in principle trip it. editConfig serializes every read-modify-write behind a single permit, so a concurrent edit is derived from the restored config and no restored value is lost; the read-back runs synchronously in the continuation of the same await, so a competing edit must complete a file write first, which makes the window practically unreachable. Consequence if hit: a spurious IO_ERROR naming the safety snapshot, after which the Backup section re-seeds the mirrors from the backend (27c72b9b). Fix: have editConfig expose its persisted result so the check binds to the edit.
• Legacy model-preference re-import from another origin (thread). Disposition: migrateLocalModelPrefsToBackend is unchanged by this PR; it imports a non-empty localStorage defaultModel mirror whenever the backend has none, and a hidden-list mirror while hiddenModelsInitialized is false. What this PR adds is one more way to reach the "no default model" state: a restore carrying defaultModel: null. The restoring origin is re-seeded and does not re-import; the exposure is a second origin of the same config root (browser mode on another host or port, or Electron plus a browser) that was used while the model was set and loads again afterwards, which then re-imports its stale mirror. UAT round 5 reproduced exactly this (V3-01..V3-03) and found that the UI offers no way to clear the default model, so a cleared default is reachable only through restore; the pre-existing import condition therefore does not by itself establish that the newly reachable state is safe, and this stays a caveat on the feature until the import is gated (for example on a one-time migrations flag like hiddenModelsInitialized). A hiddenModels: null cannot come from a real source because load-time seeding always materializes an array, and the hidden-list import is gated on hiddenModelsInitialized. Fix: a persisted "model preferences initialized" marker that ends legacy re-import.

Generated with xum • Model: anthropic:claude-fable-5-1 • Thinking: xhigh • Cost: $237.54