| 1 | # Legacy `.deepseek/` compatibility paths — audit & migration status (#3068) |
| 2 | |
| 3 | ## v0.9.10 cleanse ledger |
| 4 | |
| 5 | This is the release-window decision record for residue that can otherwise look |
| 6 | interchangeable in a text search. A compatibility entry must name the contract |
| 7 | that still requires it; new production code must use a current path. |
| 8 | |
| 9 | | Class | Surface | Decision / contract | |
| 10 | |---|---|---| |
| 11 | | DELETE | Retired underwater build-version test override | Removed in `1cc4d1d1b`; the owner test was already deleted and the production-only build version remains authoritative. | |
| 12 | | MIGRATE | Cross-task Agent Mail | `bd998495a` and managed-app `4ff7bc50d` replace guessed event aliases and same-session mailbox conflation with one durable typed runtime protocol. | |
| 13 | | MIGRATE | TUI `status_message` writes | Active residue; touched flows must move to the typed toast/current-state owner. No new writes are allowed. | |
| 14 | | COMPATIBILITY | `.deepseek/` state and stored provider aliases | Read fallback for upgraded installations and stored provider identity; writes remain Codewhale-only. Details are below. | |
| 15 | | COMPATIBILITY | `agent_message` transcript/protocol decoding | Persisted transcripts and tool wire values require decoding; it is not the cross-task Agent Mail transport. | |
| 16 | | COMPATIBILITY | Managed runtime envelope schema 1 | Previously persisted/enrolled runner replay; current local Codewhale Agent Mail producer is schema 2 and both normalize to the managed envelope. | |
| 17 | | CURRENT | DeepSeek provider support | A real selectable provider, not product branding; provider-scoped names and configuration remain. | |
| 18 | | CURRENT | Same-session subagent mailbox | Start/status/peek/message/followup/interrupt/wait/cancel stays scoped to a parent runtime session. | |
| 19 | | CURRENT | Web locale dictionaries | The application and documentation routes have no page-local `isZh` branches; new copy continues through dictionaries. | |
| 20 | | CURRENT | Safety, authorization, protocol, persistence, migration, and data-integrity tests | These protect external or durable contracts and are not copy/layout cleanup candidates. | |
| 21 | |
| 22 | Snapshot on 2026-08-19: `10,954` Rust `#[test]` attributes under |
| 23 | `crates/tui`, `523` TUI `status_message` source lines, and zero page-local |
| 24 | `isZh` files under `apps/web/app` in the paired managed-app candidate. Counts |
| 25 | are inventory signals, not deletion targets. |
| 26 | |
| 27 | Codewhale was renamed from DeepSeek-TUI. To avoid breaking existing installs, the runtime reads |
| 28 | state from the new `~/.codewhale/` location but **falls back** to the legacy `~/.deepseek/` location, |
| 29 | and always **writes** to `~/.codewhale/`. This doc audits each legacy reference and records a |
| 30 | keep / deprecate / remove decision so the migration is auditable. |
| 31 | |
| 32 | ## The canonical resolver (use this for new code) |
| 33 | |
| 34 | State-dir resolution is consolidated in `crates/config/src/lib.rs`: |
| 35 | |
| 36 | | Symbol | Line | Purpose | |
| 37 | |---|---|---| |
| 38 | | `CODEWHALE_APP_DIR` / `LEGACY_APP_DIR` | 5369 | re-exported from `crates/paths` (defined at `crates/paths/src/lib.rs` 13 / 16) | |
| 39 | | `codewhale_home()` | 5375 | `~/.codewhale` | |
| 40 | | `legacy_deepseek_home()` | 5392 | `~/.deepseek` (legacy) | |
| 41 | | `resolve_state_dir(subdir)` | 5434 | **read** path: `~/.codewhale/<subdir>`, falling back to `~/.deepseek/<subdir>` when only the legacy dir exists | |
| 42 | | `ensure_state_dir(subdir)` | 5458 | **write** path: always creates under `~/.codewhale/<subdir>` | |
| 43 | |
| 44 | Migration contract: read-with-fallback, write-to-new. This preserves the v0.8.44 migration for |
| 45 | users who still have `~/.deepseek/` while steering all new writes to `~/.codewhale/`. |
| 46 | |
| 47 | ## Per-path decisions |
| 48 | |
| 49 | **Decision for all legacy references below: keep-as-fallback.** Removing the `.deepseek` fallback |
| 50 | would strand users who upgraded in place and never re-ran onboarding. Revisit only after a release |
| 51 | that actively migrates `~/.deepseek/` → `~/.codewhale/` on first run and a deprecation window. |
| 52 | |
| 53 | | Reference | Routed through `resolve_state_dir`? | Decision | |
| 54 | |---|---|---| |
| 55 | | `config::resolve_state_dir` / `ensure_state_dir` | n/a (the resolver itself) | keep — canonical | |
| 56 | | `crates/tui/src/skills/mod.rs` (`~/.deepseek/skills`) | no — hardcoded | keep-as-fallback; route through resolver in a follow-up refactor | |
| 57 | | `crates/tui/src/prompts.rs` (`LEGACY_HANDOFF_RELATIVE_PATH = ".deepseek/handoff.md"`) | no — explicit legacy const | keep — explicit legacy handoff fallback | |
| 58 | | `crates/tui/src/workspace_trust.rs` | no — hardcoded | keep-as-fallback; follow-up | |
| 59 | | `crates/tui/src/session_manager.rs` | no — hardcoded | keep-as-fallback; follow-up | |
| 60 | | `crates/tui/src/skill_state.rs` | no — hardcoded | keep-as-fallback; follow-up | |
| 61 | | `crates/tui/src/tools/skill.rs` | no — hardcoded | keep-as-fallback; follow-up | |
| 62 | | `crates/tui/src/snapshot/mod.rs` | no — hardcoded | keep-as-fallback; follow-up | |
| 63 | | `crates/tui/src/workspace_discovery.rs` | no — hardcoded | keep-as-fallback; follow-up | |
| 64 | |
| 65 | ## Follow-up (separate, non-doc change — out of scope for #3068) |
| 66 | |
| 67 | The optional consolidation the issue mentions — routing the hardcoded sites above through |
| 68 | `resolve_state_dir`/`ensure_state_dir` instead of joining `.deepseek`/`.codewhale` by hand — is a |
| 69 | small refactor that should land as its own PR with tests asserting read-fallback + write-to-new for |
| 70 | each migrated site. It is intentionally kept out of this audit so the documentation can land safely |
| 71 | on its own. |
| 72 |