xonecas.io
60255
Zn

Zoea-Nova / files

Zoea-Nova / documentation / current / KNOWN_ISSUES.md

8.9 KB
1# Known Issues & Technical Debt
2
3Active todo list of known issues, bugs, and planned improvements for Zoea Nova.
4
5## High Priority
6
7## Medium Priority
8
9## Low Priority
10
11### TUI / Rendering
12
13- [ ] **Exit splash screen** - Display branding, connection cleanup status, and animated loading bar during shutdown
14  - **Trigger:** User presses q/ESC/CTRL+C
15  - **Purpose:** Provide visual feedback during graceful shutdown
16  - **Needs:** Splash screen design with loading animation
17
18- [ ] **Inconsistent JSON rendering in tool messages** - Some tool results render as raw text with tool call ID prefix
19  - **Example:** `chatcmpl-tool-XXX:{"player": {...}}` instead of tree view
20  - **Location:** `internal/tui/focus.go` - `renderLogEntry()`
21  - **Action:** Audit JSON detection logic for consistency
22
23### Testing / Coverage
24
25- [ ] **TUI integration tests skipped (config setup)** - Two tests skipped due to missing provider config
26  - **Tests:** `TestIntegration_NewMysisInput`, `TestIntegration_CreateAndStartMysis`
27  - **Root Cause:** Tests need temp config file after DefaultConfig() removal (commit 068a5a6)
28  - **Action:** Update tests to use setupTUITest() pattern from tui_test.go:32-56
29
30### Provider Reliability
31
32- [ ] **OpenCode provider crashes with undefined input_tokens** - Provider returns 500 errors when processing usage statistics
33  - **Error:** `Cannot read properties of undefined (reading 'input_tokens')`
34  - **Impact:** Causes myses to enter `errored` state and stop operating
35  - **Observed:** 2026-02-09 04:14:57 UTC - `nano` mysis (zen-nano provider) crashed after multiple successful turns
36  - **Pattern:** Error occurs during response processing, likely in usage statistics handling
37  - **Root cause:** OpenCode provider response format may not include expected `usage.input_tokens` field, or field is null/undefined
38  - **Location:** Provider response parsing in `internal/provider/opencode.go` or OpenCode SDK
39  - **Workaround:** None currently - requires provider restart to recover
40  - **Action needed:** 
41    - Add defensive null checks for usage statistics fields
42    - Make usage statistics optional/non-fatal
43    - Log raw response when usage parsing fails for debugging
44  - **Related:** May be connected to zen-nano vs zen-pickle provider differences
45
46- [ ] **OpenCode Zen endpoint workaround for gpt-5-nano** - Using `/chat/completions` instead of documented `/responses` endpoint
47  - **Issue:** Official docs specify `gpt-5-nano` uses `/v1/responses` endpoint, but this returns HTTP 500 errors
48  - **Error:** `request failed after 3 retries: chat completion status 500` with server error mentioning `input_tokens` (Anthropic field)
49  - **Root cause:** `/responses` endpoint appears to expect non-OpenAI request format; our code uses OpenAI SDK with Chat Completions format
50  - **Workaround:** Hardcoded `gpt-5-nano` to use `/chat/completions` endpoint (works but contradicts official docs)
51  - **Location:** `internal/provider/opencode.go` line 53
52  - **Action needed:** Contact OpenCode support to clarify `/responses` endpoint format or confirm `/chat/completions` is acceptable
53  - **Reference:** https://opencode.ai/docs/zen/#models
54
55- [ ] **Investigate Ollama timeout errors** - Occasional "context deadline exceeded" errors when calling Ollama chat completions
56  - **Error:** `Post "http://localhost:11434/v1/chat/completions": context deadline exceeded`
57  - **Needs:** Root cause analysis (model size, request timeout configuration)
58  - **Recent evidence (2026-02-05):** Ollama logs show prompt truncation (`limit=32768`, `prompt=41611`) followed by bursts of `400` responses on `/v1/chat/completions` and one `500` response. No corresponding errors in `~/.zoea-nova/zoea.log`.
59
60### Documentation & Tooling
61
62- [ ] **Add plan enforcement command** - OpenCode slash command to require plan/todo creation before implementation
63  - **Purpose:** Enforce workflow discipline for complex changes
64
65- [ ] **Add documentation audit command** - OpenCode slash command to audit AGENTS.md and README.md against codebase using @explore
66  - **Purpose:** Keep documentation in sync with code changes
67
68### Operations
69
70- [ ] **Validate game server API changes** - Monitor and validate MCP and SpaceMolt game server updates for breaking changes
71  - **Reference:** `documentation/current/KNOWN_SERVER_ISSUES.md`
72  - **Process:** Periodic checks against upstream API
73
74---
75
76## Recently Resolved
77
78- [x] **TestStateTransition_Running_To_Idle hangs** (2026-02-08) - Fixed goroutine leak in idle transition. Root cause: `setIdle()` wasn't canceling the context, causing the run loop goroutine to continue running. Added context cancellation to `setIdle()` method (lines 1092-1096 in `mysis.go`). The run loop now exits cleanly when transitioning to idle state. Test passes consistently in ~0.003-0.005s. Fixed in commit `d7a675a`.
79
80- [x] **Network indicator shows idle despite active Myses** (2026-02-07) - Fixed missing `EventNetworkIdle` after successful MCP tool execution and added counter tracking for network operations. Root cause: `EventNetworkMCP` was published for each tool call but `EventNetworkIdle` was only published on errors, causing counter to grow unbounded. Added `activeNetworkOps` counter in TUI that increments on LLM/MCP events and decrements on idle events. Indicator now correctly shows activity for both user-initiated and autonomous operations. See `documentation/architecture/NETWORK_EVENT_GUARANTEES.md` for event contract. Coverage improved from 85.0% to 85.3%.
81
82- [x] **Config validation and type safety** (2026-02-05) - Added comprehensive config validation with aggregated errors for provider/swarm settings. Replaced Event.Data interface{} with typed fields for type safety. Standardized Mysis receiver names. Coverage improved from 61% to 71.4%.
83
84- [x] **Testing coverage expansion** (2026-02-05) - Added config validation tests (11 subtests), provider error handling tests, HTTP mocking for tool calls, MCP proxy tests, and concurrent write benchmark (p50: 0.3ms, p99: 1.9ms).
85
86- [x] **Memory growth analysis** (2026-02-05) - Documented memory growth rate (279 memories/hour, 0.96 MB/hour DB growth). DB size is not a concern for v1. See `documentation/reports/MEMORY_GROWTH_REPORT.md`.
87
88- [x] **Ollama reliability investigation** (2026-02-05) - Analyzed 24h of Ollama logs. Found 65 HTTP 500s, 19 HTTP 400s, 3 prompt truncations, 23 client disconnects. Evidence documented in KNOWN_ISSUES.md for future investigation.
89
90- [x] **State-aware ContinuePrompt** (2026-02-05) - Implemented activity state tracking (idle, traveling, mining, in_combat, cooldown) to suppress nudges during known wait states. Parses arrival_tick and cooldown_ticks from tool results.
91
92- [x] **Prompt reinforcement and time awareness** (2026-02-05) - Reinforced critical rules in ContinuePrompt with drift detection. Removed real-time awareness, replaced with game tick time instructions. Added captain's log guidance with limits and examples.
93
94- [x] **TUI Enhancements** (2026-02-05) - Implemented display reasoning in focus view, account status in dashboard and focus header, JSON tree rendering with verbose toggle, and visual scrollbar indicator. Improves readability and navigation UX.
95
96- [x] **Track broadcast sender and suppress self-response** (2026-02-05) - Added sender_id to memories (schema v8), excluded sender from broadcast recipients, and updated focus view labels to distinguish swarm broadcasts from self broadcasts.
97
98- [x] **Tool payload bloat removal** (2026-02-04) - Removed `provider` and `state` fields from MysisInfo struct and `zoea_list_myses` tool payload. Added `GetStateCounts()` method to Commander for `zoea_swarm_status`. Saves ~22 tokens per mysis, ~352 tokens for full swarm (16 myses). **Note:** Both `zoea_list_myses` and `zoea_swarm_status` tools were later removed entirely.
99
100- [x] **Context snapshot compaction** (2026-02-04) - Implemented snapshot compaction in `getContextMemories()` to keep only most recent result for each snapshot tool (get_ship, get_system, get_poi, get_nearby, get_cargo). Added search tool reminders to SystemPrompt and ContinuePrompt. See `documentation/architecture/CONTEXT_COMPRESSION.md` for details.
101
102- [x] **Database reset with account backup** (2026-02-05) - Added `make db-reset-accounts` target to safely wipe database while preserving account credentials via export/import cycle.
103
104- [x] **Goroutine cleanup on exit** (2026-02-06) - Fixed terminal hangs and errored state on quit. Implemented complete goroutine cleanup with timeouts, WaitGroup tracking, and graceful shutdown sequence. See `documentation/plans/2026-02-06-goroutine-cleanup-fixes.md`.
105
106- [x] **OpenCode Zen 500 errors** (2026-02-07) - Fixed system-only message crashes, added Stream parameter, improved message merging, added validation. See `documentation/reports/OPENCODE_ZEN_FIX_2026-02-07.md`.
107
108- [x] **Session ID claim→login loops** (2026-02-07) - Fixed infinite loops caused by session_required errors. Added prompt reinforcement and error message interception. See `documentation/reports/SESSION_ID_LOOP_FIX_IMPLEMENTATION_2026-02-07.md`.