| 1 | # v0.8.6 Takeover Prompt — Fresh DeepSeek V4 Session |
| 2 | |
| 3 | You are taking over the v0.8.6 sprint for `github.com/Hmbown/DeepSeek-TUI`. |
| 4 | A previous DeepSeek session kept getting interrupted because the parent session |
| 5 | grew too large during long-running work. The user has now pruned local saved |
| 6 | sessions, but that is only temporary relief. Your job is to stabilize the branch |
| 7 | and fix the product so long-running agent work survives by default. |
| 8 | |
| 9 | ## Prime Directive |
| 10 | |
| 11 | Do not run this as one long sequential parent session. |
| 12 | |
| 13 | The parent session is the coordinator. Use `agent_spawn` for tool-carrying work, |
| 14 | use `rlm` for batch classification/synthesis over long issue lists or docs, and |
| 15 | keep the parent transcript small. If you find yourself reading files one by one |
| 16 | for the same topic, stop and delegate. |
| 17 | |
| 18 | ## Immediate Emergency |
| 19 | |
| 20 | Start with #402: |
| 21 | |
| 22 | - `#402 P0: make long-running sessions survivable by default (Codex-style compaction + bounded transcript state)` |
| 23 | |
| 24 | This is now the top priority because it caused the interrupted handoff loop. |
| 25 | The issue body names the exact gap versus `/Volumes/VIXinSSD/codex-main`: |
| 26 | |
| 27 | - DeepSeek TUI keeps unbounded `api_messages` and visible `history`. |
| 28 | - `auto_compact = false` and the capacity controller is off by default. |
| 29 | - saved sessions serialize full `messages: Vec<Message>` snapshots. |
| 30 | - the important mocked engine tests for compaction/subagents/parallel execution |
| 31 | are still ignored because the engine takes a concrete `DeepSeekClient`. |
| 32 | - Codex has runtime pre/mid-turn compaction, replacement history, persisted |
| 33 | compacted rollout items, and sanitized/last-N subagent fork behavior. |
| 34 | |
| 35 | Do not treat this as docs or prompt tuning. Implement runtime guardrails. |
| 36 | |
| 37 | ## Current Branch State To Verify |
| 38 | |
| 39 | Branch should be `feat/v0.8.6`. The prior interrupted session had dirty work. |
| 40 | Verify before trusting any claim: |
| 41 | |
| 42 | 1. `git status --short --branch` |
| 43 | 2. `cargo check --workspace --all-targets --locked` |
| 44 | 3. `cargo test --workspace --all-features --locked` if check passes |
| 45 | 4. read `AGENTS.md`, `V086_BRIEF.md`, `docs/ARCHITECTURE.md`, and issue #402 |
| 46 | |
| 47 | Known partial work from the interrupted session: |
| 48 | |
| 49 | - Goal mode command dispatch (`/goal`) — inspect `crates/tui/src/commands/goal.rs` |
| 50 | - File tree pane — inspect `crates/tui/src/tui/file_tree.rs` |
| 51 | - user-defined command plumbing — inspect `crates/tui/src/commands/user_commands.rs` |
| 52 | - localization/sidebar/rendering changes across `crates/tui/src/*` |
| 53 | |
| 54 | Do not overwrite unrelated dirty files. Work with the existing changes. |
| 55 | |
| 56 | ## Updated v0.8.6 Issue Set |
| 57 | |
| 58 | The original brief said 23 issues, but the live v0.8.6 label now includes more. |
| 59 | Refresh live state with: |
| 60 | |
| 61 | ```bash |
| 62 | gh issue list --label v0.8.6 --state open --limit 100 --json number,title,body,labels |
| 63 | ``` |
| 64 | |
| 65 | New or especially relevant additions: |
| 66 | |
| 67 | - `#402` P0 long-running session survivability: runtime compaction, bounded transcript/session persistence. |
| 68 | - `#401` prune overly defensive assertions: remove brittle prompt-substring/snapshot-style tests. |
| 69 | - `#400` chat/sidebar text bleed-through: timestamp fragments persist across cells when scrolling. |
| 70 | - `#399` lag/freeze audit: sync git on UI thread, unbounded history Vec, file-tree blocking walk. |
| 71 | - `#398` codex-mcp parity: agent-style MCP server tool plus `deepseek mcp add/list/get/remove`. |
| 72 | |
| 73 | Existing high-priority v0.8.6 issues still include: |
| 74 | |
| 75 | - `#397` Goal mode |
| 76 | - `#396` per-turn cache hit chip |
| 77 | - `#395` cycle-boundary visualization |
| 78 | - `#394` file-tree pane |
| 79 | - `#393` share session URL |
| 80 | - `#392` `/model auto` |
| 81 | - `#391` user-defined slash commands |
| 82 | - `#390` profile hot-switch |
| 83 | - `#389` inline LSP diagnostics |
| 84 | - `#388` crash-recovery prompt |
| 85 | - `#387` self-update |
| 86 | - `#386` `/init` |
| 87 | - `#385` `/diff` |
| 88 | - `#384` `/undo` |
| 89 | - `#383` `/edit` |
| 90 | - `#382` collapse Steer/Queue/Immediate |
| 91 | - `#380` inline diff highlighting |
| 92 | - `#379` smart clipboard |
| 93 | - `#378` docs polish |
| 94 | - `#377` shrink App state |
| 95 | - `#376` native-copy escape |
| 96 | - `#375` right-click context menu |
| 97 | - `#374` clickable file:line |
| 98 | - `#373` Tasks panel ignores shell jobs |
| 99 | |
| 100 | ## First-Hour Execution Plan |
| 101 | |
| 102 | Do this as a fanout, not a serial survey. |
| 103 | |
| 104 | 1. Parent: create a checklist with lanes below, then run one batched read/status |
| 105 | turn: `git status`, `gh issue list --label v0.8.6`, focused `rg` for |
| 106 | compaction/session/history/capacity, and the initial cargo check. |
| 107 | |
| 108 | 2. Spawn sub-agent A: #402 runtime/session survivability. |
| 109 | Ownership: `crates/tui/src/core/engine.rs`, `crates/tui/src/compaction.rs`, |
| 110 | `crates/tui/src/session_manager.rs`, `crates/tui/src/tui/app.rs`, |
| 111 | `crates/tui/tests/integration_mock_llm.rs`, and relevant config docs. |
| 112 | Task: design and implement the smallest runtime guardrail slice that bounds |
| 113 | parent model history/session persistence and unblocks real integration tests. |
| 114 | |
| 115 | 3. Spawn sub-agent B: current dirty-tree compile repair. |
| 116 | Ownership: partial v0.8.6 files from the interrupted session: |
| 117 | `commands/goal.rs`, `commands/user_commands.rs`, `tui/file_tree.rs`, |
| 118 | `commands/mod.rs`, `localization.rs`, `tui/sidebar.rs`, `tui/ui.rs`. |
| 119 | Task: make the branch compile without widening scope. |
| 120 | |
| 121 | 4. Spawn sub-agent C: UI performance/bleed-through lane (#399/#400/#394). |
| 122 | Ownership: transcript rendering/cache, sidebar rendering, file-tree traversal. |
| 123 | Task: fix the regression and identify any blocking synchronous UI work. |
| 124 | |
| 125 | 5. Spawn sub-agent D: issue/test hygiene lane (#401 plus ignored mock tests). |
| 126 | Ownership: brittle tests, prompt snapshot tests, and ignored integration tests. |
| 127 | Task: remove brittle assertions where appropriate and convert #402 acceptance |
| 128 | criteria into real tests. |
| 129 | |
| 130 | 6. Spawn sub-agent E only if needed: MCP parity (#398) or command surface |
| 131 | follow-through (#391/#397). Keep it separate from #402 so the P0 fix is not |
| 132 | tangled with feature work. |
| 133 | |
| 134 | ## RLM Usage |
| 135 | |
| 136 | Use `rlm` when the input is large enough that pasting/reading it in the parent |
| 137 | would bloat the session. Good RLM tasks here: |
| 138 | |
| 139 | - classify all live `v0.8.6` issue bodies into independent implementation lanes; |
| 140 | - compare #402 against Codex files by giving RLM extracted snippets from both |
| 141 | repos and asking for a bounded acceptance checklist; |
| 142 | - batch-review a long test list for brittle assertions related to #401; |
| 143 | - summarize long cargo/clippy output into file-owned fix clusters. |
| 144 | |
| 145 | Inside RLM, use `llm_query_batched()` for independent classifications and |
| 146 | `rlm_query()` only for recursive critique/decomposition. The parent should get |
| 147 | the final synthesis, not every intermediate chunk. |
| 148 | |
| 149 | ## Session Survival Rules |
| 150 | |
| 151 | - Keep at most 5 sub-agents running. |
| 152 | - After spawning agents, keep doing non-overlapping local coordination work. |
| 153 | - Use `agent_wait` only when blocked on results. |
| 154 | - Use `agent_result` for completed agents and summarize results into the parent. |
| 155 | - Suggest `/compact` at 60% context, but do not rely on that as the product fix. |
| 156 | - If the parent reaches 3 sequential turns on the same topic, spawn or RLM it. |
| 157 | - Do not paste full logs into the parent. Store logs as artifacts or ask RLM to |
| 158 | summarize them. |
| 159 | |
| 160 | ## PR Workflow |
| 161 | |
| 162 | Use GitHub PRs as an extra review surface. Do not let a giant local branch pile |
| 163 | up without outside checks. |
| 164 | |
| 165 | - Prefer small PRs by issue or tightly related lane: #402 can be its own PR, |
| 166 | compile-repair can be its own PR, UI performance/regression fixes can be their |
| 167 | own PR, and command-surface features can be separate. |
| 168 | - Push work branches and open PRs early once each slice compiles and has focused |
| 169 | tests. Include `Closes #...` only when the PR actually satisfies the issue. |
| 170 | - Let CI and any GitHub AI/code-review agents inspect the code. Treat review |
| 171 | comments as real work: address them with follow-up commits rather than |
| 172 | hand-waving them away. |
| 173 | - When a PR comes back clean, merge it into the target branch and continue from |
| 174 | the updated branch. When it comes back with requested fixes, make the fixes, |
| 175 | rerun the relevant gates, and wait for the updated checks before merging. |
| 176 | - Keep the parent session tracking PR state with `gh pr view`, `gh pr checks`, |
| 177 | and `gh issue view`; do not manually close issues unless acceptance is |
| 178 | verified and the merge did not close them automatically. |
| 179 | |
| 180 | ## Verification Gates |
| 181 | |
| 182 | Before claiming anything is done: |
| 183 | |
| 184 | ```bash |
| 185 | cargo fmt --all -- --check |
| 186 | cargo check --workspace --all-targets --locked |
| 187 | cargo test --workspace --all-features --locked |
| 188 | cargo clippy --workspace --all-targets --all-features --locked -- -D warnings |
| 189 | ``` |
| 190 | |
| 191 | For #402 specifically, also add or enable focused tests proving: |
| 192 | |
| 193 | - compaction/cycle guardrail runs before dangerous context growth; |
| 194 | - live `api_messages` or equivalent model history is bounded after compaction; |
| 195 | - visible transcript/session persistence is bounded or virtualized; |
| 196 | - sub-agent result ingestion into the parent is summarized/bounded; |
| 197 | - child fork history can use sanitized last-N behavior; |
| 198 | - session save/checkpoint does not rewrite arbitrary huge full transcripts. |
| 199 | |
| 200 | ## Final Report Format |
| 201 | |
| 202 | Use these headings: |
| 203 | |
| 204 | - Implemented |
| 205 | - Verified |
| 206 | - Issues safe to close |
| 207 | - Issues still open and why |
| 208 | - Commands run |
| 209 | - Residual risks |
| 210 | |
| 211 | Be explicit about what is local-only, what is committed, what is pushed, and what |
| 212 | is merely planned. Do not close issues unless acceptance criteria are verified. |
| 213 |