════════════════════════════════════════════════════════════════════════
  CODE REVIEW
  Gnomad Desktop Assistant · docs/CODE_REVIEW.md
════════════════════════════════════════════════════════════════════════

CODE REVIEW — GNOMAD DESKTOP ASSISTANT
======================================

Reviewed: 2026-05-31 (updated after hiring-feedback implementation)  
Scope: src/, src-tauri/src/, workflows, agent/security paths

SUMMARY
-------

The app is a Tauri v2 + React 19 desktop assistant: tray/panel, global shortcut, OS context (active window, clipboard), cloud + local LLM chat with an agent tool loop, persistent PTY shell session, filesystem agent tools, Sudo Gate / Path Gate HITL, and structured error payloads end-to-end.

  Area                            |  Status                                                                                
  Frontend build (npm run build)  |  Pass                                                                                  
  Rust tests (cargo test)         |  Pass (error, privilege, shell_session)                                                
  LLM orchestration               |  Cloud chat_completion_turn + tools; local Ollama +  fallback                          
  Structured errors               |  GnomadError → JSON in invoke Err(String); frontend parseInvokeError + AgentErrorBanner
  App shell                       |  App.tsx ~400 lines; hooks + ChatView / SettingsPanel / gate modals                    
  Elevation hardening             |  Pre-flight injection blocks; Linux pkexec argv-only; macOS per-arg escaping           

────────────────────────────────────────

ARCHITECTURE (HIGH LEVEL)
-------------------------

  [code]
    Tray + Global Shortcut (lib.rs)
            │
            ▼
    React App shell (App.tsx) ──hooks──► useAgentExecution, useChatSubmit, …
            │                              │
            ▼                              ▼
    ChatView / SettingsPanel ──invoke──► Tauri commands
                                         ├── agent_runtime / agent_fs
                                         ├── shell_session (PTY)
                                         ├── privilege.rs (safety + elevation)
                                         ├── error.rs (GnomadError payloads)
                                         └── context, keychain, llm, …

────────────────────────────────────────

AGENT ERROR PAYLOAD CONTRACT
----------------------------

Tauri commands still return Result. During migration, error strings are JSON matching:

  [json]
    {
      "code": "safety_blocked",
      "message": "Human-readable summary",
      "detail": "Optional technical detail",
      "hint": "Optional remediation",
      "retryable": false
    }

Frontend: src/lib/errors.ts — parseInvokeError, executionFailedLabel, formatErrorForUser.  
UI: src/components/AgentErrorBanner.tsx on messages with errorPayload.

Stable code values are covered by error::tests::payload_codes_are_stable.

────────────────────────────────────────

STRENGTHS
---------

  1. Module split — Rust agent, shell, privilege, FS; React hooks mirror execution concerns.
  2. HITL — Sudo Gate and Path Gate with explicit approve/deny.
  3. Defense in depth — Server-side safety before shell; elevation rejects injection patterns.
  4. Cross-platform awareness — platformInfo drives labels and capability flags.

────────────────────────────────────────

REMAINING GAPS (PRIORITY)
-------------------------

P1 — Security / product

  1. Wave B error migration — ✓ Shipped on LLM, planner, and chat history paths.
  2. Windows elevation — Structured elevation_unsupported; user must use elevated terminal for admin ops.
  3. Path Gate tokens — ✓ Shipped — path_token.rs; boolean IPC bypass rejected.

P2 — Engineering

  4. Typed invoke errors — Optional future: Result at Tauri boundary once JSON-in-string is stable everywhere.
  5. Vitest — ✓ parseInvokeError tests in CI (npm run test).
  6. GGUF planner + local chat — In-process inference via optional embedded-llm feature; Ollama remains fallback.

────────────────────────────────────────

SUGGESTED NEXT STEPS
--------------------

  1. Generate updater signing keys per UPDATER.md and replace the placeholder pubkey in tauri.conf.json.
  2. End-to-end updater test once signing keys are configured.
  3. Snap / Flatpak manifests (community packaging).

────────────────────────────────────────

FILE REFERENCE
--------------

  File                            |  Role                                  
  src/App.tsx                     |  Thin shell, providers wiring          
  src/hooks/useAgentExecution.ts  |  Shell cwd, gates, executeCommandSafely
  src/hooks/useChatSubmit.ts      |  Submit orchestration, agent loop      
  src/components/ChatView.tsx     |  Messages, composer, context footer    
  src-tauri/src/error.rs          |  GnomadError, AgentErrorPayload        
  src-tauri/src/privilege.rs      |  Safety + elevation                    
  src-tauri/src/shell_session.rs  |  PTY session + validation

════════════════════════════════════════════════════════════════════════
Built with ❤️ by Gnomad Studio 🦙
https://gnomadstudio.org
════════════════════════════════════════════════════════════════════════