zclaw_openfang/docs/superpowers/specs/2026-04-11-detail-panel-7-fixes-design.md

Detail Panel 7-Issue Fix Design

Date: 2026-04-11 Status: Draft Approach: Path B — System Bridge (fix bugs + bridge disconnected systems) Constraint: No new SaaS endpoints, no new stores, no new middleware (stabilization compliance)

Background

User discovered 7 issues during real usage of ZCLAW desktop app's detail panel (RightPanel). Root cause analysis revealed a pattern: 5 of 7 issues stem from "backend has capability but frontend doesn't consume it" — disconnected systems that need bridging.

Issue Summary

#	Problem	Severity	Root Cause	Category
1	Can't chat after restart	P0	Heartbeat degrades to 'tauri' in localStorage, restoreSession blindly trusts it	Route race
2	"About me / How I see you" never updates	P1	Panel reads agentStore.Clone, memory extractor writes identity files — no bridge	Data disconnect
3	Memory 311 count but empty list/graph	P0	memory_search empty query + min_similarity=None → FTS5 returns 0	Query logic bug
4	Only 1 reflection, effects unknowable	P1	History only persists latest (not array); pattern thresholds too high; state restore race	Multi-factor
5	hand_trigger always rejected	P0	autonomy-manager.ts:268 maps hand_trigger to null — hardcoded bug	Hardcoded bug
6	Evolution has data but effects unknowable	P2	HistoryItem only shows truncated reason, no expandable diff	UX gap
7	Butler "6 messages" incorrect + empty below	P2	Shared chat stats header confused for butler data; no pain points detected	UX confusion

---

Section 1: P0 Fixes

Fix 1 — Chat Routing After Restart

Root Cause: saasStore.restoreSession() blindly trusts localStorage connectionMode written by heartbeat degrade. After restart, SaaS auth may still be valid but the persisted 'tauri' mode prevents SaaS relay usage.

Solution:

1. In restoreSession() (saasStore.ts ~line 750): Before accepting persisted mode, validate SaaS token:
   • Attempt refresh token → access token exchange
   • If successful, restore to 'saas' mode regardless of persisted value
   • Only accept 'tauri' mode if token refresh fails
2. In loadConnectionMode() (saas-session.ts ~line 170): Add staleness check:
   • Persist timestamp alongside mode in localStorage
   • On load, if persisted mode is 'tauri' and timestamp > 5 minutes old, re-validate
3. Heartbeat degrade writes timestamp for staleness tracking

Files:

• desktop/src/store/saasStore.ts — restoreSession() ~line 750 (verify exact location before implementation)
• desktop/src/lib/saas-session.ts — loadConnectionMode() ~line 170
• desktop/src/store/connectionStore.ts — connect() routing ~line 428

Risk: Low. Only changes startup validation logic, doesn't affect active session behavior.

---

Fix 3 — Memory List/Graph Empty Despite 311 Entries

Root Cause: memory_search Tauri command calls VikingStorage::find() with empty query string and min_similarity: None. FTS5 requires non-empty query to match anything. memory_stats works because it sets min_similarity: Some(0.0) which triggers table scan path.

Solution:

1. In memory_commands.rs memory_search (line 164): When query is empty or whitespace-only, set min_similarity: Some(0.0) as default fallback
2. This makes the empty-query behavior consistent with memory_stats — table scan returns all entries
3. No changes to VikingStorage internals — only the calling parameter

Files:

• desktop/src-tauri/src/memory_commands.rs — memory_search at line 148-184

Risk: Minimal. Single-line parameter change. Performance concern mitigated by existing limit: 50 default.

---

Fix 5 — hand_trigger Always Rejected

Root Cause: autonomy-manager.ts:268 maps hand_trigger: null in the actionMap. When configKey is null, isActionAllowed() immediately returns false. No handAutoTrigger field exists in AutonomyConfig.allowedActions.

Solution:

1. Add handAutoTrigger: boolean to AutonomyConfig.allowedActions type (autonomy-manager.ts)
2. Change actionMap: hand_trigger: null → hand_trigger: 'handAutoTrigger'
3. Update default configs:
   • autonomous level: handAutoTrigger: true
   • supervised level: handAutoTrigger: false
   • guided level: handAutoTrigger: false
4. Add toggle control in AutonomyConfig.tsx UI

Files:

• desktop/src/lib/autonomy-manager.ts — line 268 actionMap + allowedActions type + default configs
• desktop/src/components/AutonomyConfig.tsx — add handAutoTrigger toggle

Risk: Low. Pure frontend change. Backend already supports autonomous mode bypassing approval gate.

---

Section 2: P1 Fixes

Fix 2 — "About Me / How I See You" Auto-Update

Root Cause: Panel reads from agentStore.Clone static fields. Memory extractor writes to identity files (soul/instructions/user_profile). Backend UserProfileStore (Rust) has structured user modeling (industry/role/expertise/communication_style/recent_topics) but no Tauri command exposes it to frontend.

Solution (System Bridge — Alternative Approach: Extend Existing Command):

To comply with stabilization constraint "no new Tauri commands" (CLAUDE.md §1.3: "已有 189 个，70 个无前端调用"), we use Option (b): extend an existing command's return payload.

1. Extend agent_get command: The existing agent_get(agent_id) command returns AgentConfig. Extend its return to include an optional user_profile field from UserProfileStore::get().

   • This avoids creating a new command while exposing existing backend data.
   • File: desktop/src-tauri/src/kernel_commands/agents.rs — extend return type

2. Frontend bridge:

   • Use component-local state (useState) in RightPanel for UserProfile data (not Store — per CLAUDE.md §4.2 layered responsibilities)
   • On mount and after conversation complete, re-fetch agent data which now includes profile
   • "How I See You" section renders from two sources:
     • Static: Clone fields (userName, workspaceDir, privacyOptIn)
     • Dynamic: UserProfile fields (industry, role, expertise, communication_style, recent_topics)
   • Fallback: if UserProfile empty, show static Clone data only

3. Refresh trigger: In streamStore flow completion callback (~line 446), after memory extraction, trigger RightPanel's profile refresh via a lightweight event or re-fetch

Files:

• desktop/src-tauri/src/kernel_commands/agents.rs — extend agent_get return type
• desktop/src-tauri/src/lib.rs — no change needed (command already registered)
• desktop/src/components/RightPanel.tsx — dual-source rendering (lines 523-557)
• desktop/src/store/chat/streamStore.ts — add profile refresh trigger ~line 446

Risk: Medium. Extends existing command rather than creating new one. UserProfileStore already exists. No new SaaS endpoints. No new stores.

---

Fix 4 — Reflection Only 1 Entry, Effects Unknowable

Root Cause: Multi-factor — history only persists reflection:latest (single entry) not reflection:history (array); pattern detection thresholds too high (5+ same type); state restore race condition in post_conversation_hook.

Solution:

1. Fix history persistence (reflection.rs):

   • Ensure reflect() appends to reflection:history:{agent_id} array (not overwrite)
   • Maintain cap at 20 entries (FIFO)
   • Always write both reflection:latest AND reflection:history

2. Lower pattern detection thresholds (reflection.rs analyze_patterns()):

   • Pattern "many tasks": 5+ → 3+ (rationale: early pattern detection provides timely insights)
   • Pattern "many preferences": 5+ → 3+ (rationale: user preferences accumulate quickly in normal use)
   • Pattern "many experiences": 5+ → 3+ (rationale: experiences are high-value patterns worth detecting early)
   • Pattern "high-visit memories": 3+ → 2+ (rationale: even 2 high-visit memories indicate recurring interest)
   • Pattern "low-importance memories": 20+ → 15+ (rationale: conservative reduction from 20 — avoids noisy cleanup suggestions at 10)

3. Fix state restore race (intelligence_hooks.rs):

   • Change post_conversation_hook state restore from "pop (read + delete)" to "read only"
   • Cleanup mechanism: old state is cleaned up on next conversation hook invocation (FIFO with max 1 entry per agent), preventing indefinite accumulation
   • Let getHistory always find complete data in VikingStorage

4. Enhance reflection effect visibility (ReflectionLog.tsx):

   • Each history entry shows: pattern count + summary, improvement suggestion count, identity proposal count
   • Timeline indicator: "Triggered after N conversations"
   • Expandable detail view for patterns and suggestions

Files:

• desktop/src-tauri/src/intelligence/reflection.rs — history persistence + threshold adjustment
• desktop/src-tauri/src/intelligence_hooks.rs — state restore race fix
• desktop/src/components/ReflectionLog.tsx — enhanced visibility UI

Risk: Low-Medium. Reflection persistence fix is the most impactful change. Threshold changes are conservative (3+ is still meaningful).

---

Section 3: P2 Fixes

Fix 6 — Evolution Effects Unknowable

Root Cause: HistoryItem component only renders truncated reason text and timestamp. Snapshot data contains full files object but UI never renders diff content. ProposalCard already has a DiffView component that could be reused.

Solution:

1. Expandable HistoryItem (IdentityChangeProposal.tsx):

   • Add click-to-expand behavior on history items
   • When expanded, show which files changed (as tags)
   • Show full reason text (no truncation)
   • Reuse existing DiffView component for before/after comparison

2. Evolution summary metadata:

   • Each history item header shows file change count badge
   • Color coding: soul changes = purple, instructions = blue, user_profile = green

Files:

• desktop/src/components/IdentityChangeProposal.tsx — HistoryItem component (lines 269-304)

Risk: Low. Pure UI enhancement. Reuses existing DiffView component.

---

Fix 7 — Butler Tab Confusion + Empty Data

Root Cause: "6 messages" is shared chat statistics header displayed across ALL tabs (not butler-specific). Butler tab below is empty because: (a) no pain points detected in short conversations, (b) no proposals generated, (c) Viking memory path empty.

Solution:

1. Contextual header (RightPanel.tsx):

   • When butler tab is active, replace chat statistics with butler-specific summary
   • Show: Butler name + pain points count + proposals count + memory count
   • Other tabs keep existing chat statistics

2. Enhanced empty state (ButlerPanel/index.tsx):

   • When all sections empty, show friendly onboarding message
   • "管家正在了解您，多轮对话后会自动发现您的需求"
   • Add manual "analyze now" button that calls analyze_for_pain_signals with current conversation history
   • Button disabled when conversation < 2 messages (prevents meaningless analysis)
   • Show loading state during analysis
   • Display "未发现痛点" message when analysis completes with no results

3. Lower pain point detection threshold (pain_aggregator.rs):

   • Relax keyword matching patterns
   • Allow pain point extraction from shorter conversations (minimum 2 messages instead of 3+)

Files:

• desktop/src/components/RightPanel.tsx — conditional header rendering (lines 374-386)
• desktop/src/components/ButlerPanel/index.tsx — empty state enhancement
• desktop/src-tauri/src/intelligence/pain_aggregator.rs — threshold adjustment

Risk: Low. UX improvements. Pain point threshold change is conservative.

---

Implementation Priority

Batch	Issues	Severity	Est. Complexity
Batch 1	1, 3, 5	P0	Low (small targeted fixes)
Batch 2	2, 4	P1	Medium (system bridge + persistence fix)
Batch 3	6, 7	P2	Low (UX enhancements)

Testing Plan

Automated Tests (after each batch)

• tsc --noEmit — TypeScript type check
• cargo check — Rust compilation
• vitest run — Frontend unit tests

Rust Unit Tests (Batch 2)

• memory_search empty query behavior: verify min_similarity defaults to Some(0.0) when query is empty
• Reflection history persistence: verify reflect() appends to history array, not overwrites

Manual Test Matrix

Fix 1 — Chat Routing (must test both modes):

• SaaS mode: restart app with valid SaaS session → should restore to 'saas' mode
• SaaS mode: restart app with expired SaaS session → should degrade to 'tauri' mode
• Tauri mode: restart app → should stay in 'tauri' mode
• Fresh install → should prompt login or default to local mode

Fix 2 — Agent Profile:

• UserProfile empty → fallback to static Clone data
• UserProfile populated → dynamic fields shown alongside static
• After multi-turn conversation → profile fields refresh

Fix 3 — Memory Display:

• Memory panel loads with entries visible (not just count)
• Memory graph renders with nodes and edges
• Pagination works for > 50 entries

Fix 5 — Hand Trigger:

• Existing autonomy configs migrate correctly (no handAutoTrigger → default false)
• Autonomous level → hand_trigger auto-allowed
• Supervised/guided → hand_trigger requires approval

Fix 4 — Reflection:

• After 3+ conversations → reflection triggers automatically
• History shows multiple entries (not just 1)
• Each entry shows pattern/improvement/proposal counts

Fix 6 — Evolution:

• Click history item → expandable diff view appears
• Diff view shows before/after for changed files

Fix 7 — Butler:

• Butler tab shows contextual header (not chat stats)
• "Analyze now" button disabled when < 2 messages
• Empty state shows onboarding message

Documentation Updates (per CLAUDE.md §8.3)

• Update docs/TRUTH.md if command count changes
• Update wiki/log.md with change record
• Update wiki/module-status.md if module status affected

Constraint Compliance

Constraint	Status
No new SaaS API endpoints	OK
No new SKILL.md files	OK
No new middleware	OK
No new stores	OK — using component-local state
No new admin pages	OK
No new Tauri commands	OK — Fix 2 extends existing agent_get command instead

Note: Fix 2 originally proposed a new Tauri command but was revised to extend existing agent_get to comply with stabilization constraint.