v0.8.67 Setup: config persistence, migration, secret handling, and rollback

[Hmbown]

Product shape

This is the safety layer under every setup step: one transactional persistence model so that a wizard session — which may touch provider, trust, tools, constitution, and more — either fully applies or fully rolls back, and never leaves a half-written ~/.codewhale/config.toml. To the user it is invisible when it works (config just sticks) and trustworthy when it doesn't (a clear message + unchanged files). It must preserve comments, unknown sections, project overlays, legacy migration behavior, and above all secrets.

Non-goals

• Not designing a new config format; reuse the existing TOML + comment-preserving helpers.
• Not owning per-step semantics (which fields each step writes) — each step owns its fields; this issue owns the write / rollback / secret contract.
• Not migrating users away from legacy ~/.deepseek in this issue; only handling it safely when present.

Safe fallback

• Partial failure leaves config unchanged or in a documented complete state — atomic write (temp file + rename) or rollback, never a partial in-place edit.
• Unknown sections and user comments survive every write.
• Secrets are redacted everywhere: UI, logs, reports, error messages, and test snapshots.

Doctor / docs expectations

• codewhale doctor can detect and report a half-applied/malformed config left by an older crash and offer repair.
• Docs (v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy #3412) describe what setup can change, what requires a restart, and the rollback guarantee.

Problem

A full setup wizard will touch many config areas. It must preserve existing settings, comments, unknown fields, project overlays, legacy migration behavior, and secrets. Setup should feel safe for existing users, not like a config file rewrite lottery.

Scope

• Define one setup persistence transaction model for wizard steps: preview, apply, rollback/failure handling, and restart-required changes.
• Use comment-preserving TOML helpers where possible; add narrow helpers for any missing config sections.
• Preserve unknown config sections and user comments.
• Handle ~/.codewhale/config.toml, legacy ~/.deepseek/config.toml, explicit --config, and project-level overlays safely.
• Redact secrets in UI, logs, reports, tests, and error messages.
• Support secret references such as environment variables or script-backed key retrieval where available.
• Add tests for multi-step save, partial failure, rollback/no-partial-write, malformed config, legacy migration, project overlay warning, and secret redaction.

Definition of done

• Setup can apply multiple changes without corrupting unrelated config.
• Failure leaves config either unchanged or in a documented complete state; no half-written wizard output.
• Secrets never appear in setup report, logs, issue-friendly diagnostics, or test snapshots.
• Existing config migration behavior remains compatible with setup.

Acceptance criteria

• Setup applies multiple changes across steps without corrupting unrelated config.
• Failure leaves config unchanged (atomic write/rollback); no half-written wizard output.
• Unknown sections and comments are preserved across writes.
• ~/.codewhale, legacy ~/.deepseek, explicit --config, and project overlays are handled safely.
• Secrets never appear in setup report, logs, issue-friendly diagnostics, or test snapshots.
• Tests cover multi-step save, partial failure + rollback, malformed config, legacy migration, project-overlay warning, and secret redaction.

Related

• Epic: v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402 · State model: v0.8.67 Setup: audit current setup/onboarding surfaces and define the unified setup state model #3403 · Wizard shell: v0.8.67 Setup: implement the setup wizard shell, navigation, resume, and /setup entry point #3404 · Verification/doctor: v0.8.67 Setup: verification, doctor integration, setup report, and release QA matrix #3411 · Docs: v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy #3412