Migrate desktop macOS app from Rust backend to Python backend

[beastoin]

Problem

The desktop macOS app uses a dedicated Rust backend (desktop/Backend-Rust/, deployed as desktop-backend on Cloud Run) with 80+ endpoints that largely duplicate the Python backend's 339+ endpoints at api.omi.me. This creates dual maintenance, separate deployments, and has caused bugs (#5296 stale download).

Python backend is the source of truth. Swift app adapts to Python's existing contracts. Rust-only features get ported to Python or dropped.

Scope

Auth is NOT in scope — desktop auth (omi-desktop-auth Cloud Run) is separate.

Current Status

Already Migrated

• Sparkle auto-updates — PR Consolidate desktop updates: Python-only appcast with beta/stable channels #5304
• Download endpoint — Python /v2/desktop/download/latest
• Release registration — GitHub metadata
• Channel switch UX — PR Desktop: auto-check updates on channel switch + downgrade confirmation #5314
• Dev environment — PRs Add dev auto-deploy for Rust desktop backend #5310, Make GCE project configurable for AgentVM provisioning #5349, Use dedicated omi-agent-vm firewall tag for AgentVM instances #5353, Add .env.example templates for desktop app and Rust backend #5357

Verified Endpoint Audit

• ~65 endpoints: no work needed — direct Python equivalents exist
• 11 PRs needed — see 3-day plan below
• 4 features dropped for cutover (Crisp, LLM usage, stats, Sentry)

3-Day Migration Plan (v4)

Chat Strategy: Option A — Python CRUD compat

Add desktop-compat CRUD endpoints in Python matching Rust's message contract. Python streaming RAG untouched for mobile/web. Swift changes = zero for chat. Full ChatEngine rewrite is follow-up optimization.

Day 1: Unblock Critical Contracts (5 PRs parallel)

• PR1: Python chat CRUD compat (/v2/desktop/messages)
• PR2: Python chat sessions CRUD (/v2/chat-sessions)
• PR3: Python screen activity sync (POST /v1/screen-activity/sync)
• PR4: Swift decoder fixes (action_items key, optional fields, agent VM paths)
• PR5: Router wiring in backend/main.py

Day 2: Port Remaining Gaps (5 PRs parallel)

• PR6: Python focus sessions + stats
• PR7: Python daily score + scores
• PR8: Python AI profile + assistant settings
• PR9: Python advice CRUD
• PR10: Python staged tasks + promote logic (largest)

Day 3: Integration + Hardening + Cutover

• PR11: Final compat fixes + edge cases
• Full test pass (backend/test.sh)
• Desktop smoke suite against Python backend
• Cutover: OMI_API_URL → api.omi.me
• Rust backend hot as rollback for 72h

Critical Path

PR1 (chat) + PR2 (sessions) → PR5 (wiring) → Day 3 integration
PR10 (staged tasks)         → Day 3 integration
PR4 (Swift decoders)        → Day 3 smoke test

Decision Gate

Day 2 noon: if chat compat is unstable → switch to Option B (keep Rust for chat only, migrate everything else).

Swift Must Adapt

Mismatch	Rust	Python	Fix
Action items key	"items"	"action_items"	Swift CodingKeys
Agent VM paths	/v2/agent/*	/v1/agent/vm-*	Swift URL map
Memory optional fields	Required	Optional	Swift defaults
Conversation timestamps	Required	Optional	Swift optional

Rollback

1. Rust backend stays hot for 72h+ after cutover
2. Instant rollback via OMI_API_URL env var change
3. All Python changes are additive — no destructive schema changes

Related

• macos.omi.me serves stale DMG — Codemagic missing isLive metadata, Python download endpoint bypassed #5296, Consolidate desktop updates: Python-only appcast with beta/stable channels #5304, Desktop: auto-check updates on channel switch + downgrade confirmation #5314, Make GCE project configurable for AgentVM provisioning #5349, Use dedicated omi-agent-vm firewall tag for AgentVM instances #5353, Add .env.example templates for desktop app and Rust backend #5357

Full analysis in comments below.

[beastoin]

Backup of original issue description (v1)

Click to expand original description

Problem

The desktop macOS app uses a separate Rust backend (desktop/Backend-Rust/, deployed as desktop-backend on Cloud Run) that duplicates ~85+ endpoints the Python backend (api.omi.me) already has. This adds maintenance burden, deployment complexity, and has already caused bugs (stale macos.omi.me download — #5296, ghost promote_release.sh script that was never created).

The Swift app loads its API URL from OMI_API_URL in the .env file. Migration = point that URL to api.omi.me and ensure endpoint parity.

Scope

Auth is NOT in scope — the desktop auth service (omi-desktop-auth Cloud Run, hardcoded in AuthService.swift:47) is separate.

Sparkle updates partially addressed — #5296 / PR #5298 restores Python /v2/desktop/download/latest and adds isLive metadata to Codemagic releases.

Endpoint Audit Summary

Full parity (~130 endpoints): Memories, Messages, Chat Sessions, Conversations (core CRUD), Action Items, Advice, Apps, Users/Settings, Focus Sessions, Goals, People, Personas, Folders, Daily Score, Staged Tasks, LLM Usage, Stats.

Gaps requiring work before migration:

Tier 1 — Hard Blockers

Feature	Rust Endpoints	Python Status	Notes
Sparkle auto-updates	/appcast.xml, /updates/latest, /download, POST /updates/releases, PATCH /updates/releases/promote	Partially addressed by #5296	Appcast + release registration still only in Rust. Codemagic registers releases in Firestore via Rust backend. Need to decide: keep Rust for this, or port to Python.
Screen activity + Pinecone	POST /v1/screen-activity/sync	Python has Firestore writes only	Rust writes embeddings to Pinecone ns3 for semantic screenshot search. Python backend has no Pinecone integration for desktop.
Knowledge graph	GET /v1/knowledge-graph, POST .../rebuild, DELETE	Python has stubs	Rust has full entity extraction from memories, deduplication, edge detection. Desktop app relies on this for 3D graph visualization.

Tier 2 — Feature parity

Feature	Rust Endpoints	Python Status	Notes
Agent VM provisioning	POST /v2/agent/provision, GET /v2/agent/status	Missing	Rust creates GCE VMs, tracks status in Firestore. Python may delegate to agent-proxy service instead.
Chat context (RAG)	POST /v2/chat-context, POST /v2/chat/initial-message	Partial	Rust has date extraction, conversation filtering, citation tracking. Python completeness unclear.
Conversation visibility	PATCH .../visibility, GET .../shared	Partial	Rust syncs to Redis for fast lookups. Python has the endpoints but Redis sync may be incomplete.
Apple domain verification	GET /.well-known/apple-developer-domain-association.txt	Missing	Static file, trivial to add.

Tier 3 — Minor

Feature	Rust Endpoints	Python Status
Crisp unread messages	GET /v1/crisp/unread	Unclear
Sentry webhooks	POST /v1/webhooks/sentry, .../poll	Likely exists

Firestore Collections (Desktop-Specific)

Rust creates these collections that Python may not manage:

• users/{uid}/screen_activity/{id} — screenshot metadata + embeddings
• desktop_releases/{doc_id} — release tracking (version, channel, download_url)
• users/{uid}/agentVm/ — VM name, IP, status, auth token
• users/{uid}/knowledge_graph/nodes/{id} and edges/{id}

Migration Plan

Phase 1: Audit & Validate (no code changes)

• Verify Python endpoints match Rust response shapes for all "full parity" categories (spot-check 5-10 key endpoints with real requests)
• Confirm Codemagic can register releases without the Rust backend (after macos.omi.me serves stale DMG — Codemagic missing isLive metadata, Python download endpoint bypassed #5296 merges)
• Map which desktop-specific Firestore collections Python backend already reads/writes

Phase 2: Port Missing Endpoints

• Screen activity sync with Pinecone ns3 writes
• Knowledge graph rebuild with LLM entity extraction
• Agent VM provisioning (or confirm agent-proxy handles it)
• Chat context/RAG feature completeness
• Apple domain verification static file
• Any response shape differences found in Phase 1

Phase 3: Switch & Test

• Point dev build (OMI_API_URL) to api.omiapi.com, run full E2E
• Point staging build to api.omi.me, beta test with team
• Verify: conversations, memories, chat, knowledge graph, screen activity, auto-updates, agent provisioning

Phase 4: Sunset Rust Backend

• Remove Codemagic "Deploy Rust backend to Cloud Run" step
• Stop desktop-backend Cloud Run service
• Archive desktop/Backend-Rust/ (don't delete — reference for porting)
• Update desktop/CLAUDE.md and repo docs

by AI for @beastoin

[beastoin]

Comprehensive Migration Plan (v2) — Deep Dive Results

Full codex-validated analysis of all 80+ Rust endpoints, 339+ Python endpoints, and 100+ Swift app API calls.

Core Strategy

Compatibility layer in Python — add desktop CRUD endpoints alongside existing RAG pipeline. Do NOT rewrite Swift chat architecture.

Critical Architecture Finding

The biggest blocker is a semantic collision on POST /v2/messages:

	Rust Backend	Python Backend
POST /v2/messages	CRUD save — stores message to Firestore	Streaming RAG — LangChain pipeline with tool use
GET /v2/messages	List from Firestore (app_id/session_id filter)	Different shape (includes memories, files, chart_data)
Chat sessions	Full CRUD (title/preview/starred/message_count)	Minimal — no title, preview, starred

The Swift app does LLM calls client-side (Gemini API key in .env) and uses the backend purely for message persistence. Solution: add CRUD message endpoints in Python under a compat namespace.

Progress

• Sparkle auto-updates — Migrated (PR Consolidate desktop updates: Python-only appcast with beta/stable channels #5304). Python /v2/desktop/appcast.xml is source of truth.
• Download endpoint — Python /v2/desktop/download/latest works.
• Release registration — Now via GitHub release metadata, no Firestore.
• Knowledge graph — Python already has full endpoints (/v1/knowledge-graph, rebuild, delete) with DB layer.
• Chat CRUD + sessions — Hard blocker, must port
• Agent VM provisioning — Path mismatch + behavior gap
• Screen activity sync — Python has DB layer but no REST endpoint
• Response shape mismatches — 7 identified

5-Phase Plan

Phase 0: Contract freeze + test harness (Low risk, S)

• Capture Rust response fixtures for all 100+ desktop endpoints
• Add Python contract tests (shape + required fields)
• Add OMI_BACKEND_VERSION runtime switch in desktop app

Phase 1: Chat + Agent blockers (HIGH risk, L) — gates cutover

• Desktop message CRUD endpoints in Python (save/list/delete/rate)
• Chat sessions full CRUD (title/preview/starred/message_count)
• Chat initial-message + generate-title (JSON, not streaming)
• Agent VM provision + status (v2 aliases with full GCE create logic)
• Action item envelope fix ({items, has_more} wrapper)

Phase 2: Productivity features (Medium risk, M-L)

• POST /v1/screen-activity/sync — Firestore + Pinecone ns3
• Focus sessions/stats CRUD
• Daily score + scores calculation
• AI profile GET/PATCH
• Assistant settings GET/PATCH
• Staged tasks promote logic
• 7 response shape fixes (visibility default, missing fields, envelope keys)

Phase 3: Secondary integrations (Low risk, S-M)

• Crisp unread messages
• Chat message stats (PostHog)
• Apple domain verification (static file)
• LLM usage tracking
• Drop 5 obsolete endpoints (release registration, sentry webhooks, one-time migrations)

Phase 4: Canary rollout (Medium risk, M)

• 5% → 25% → 100% with per-feature remote config kill switch
• Keep Rust backend hot for 2 weeks as fallback
• Monitor decode failures, 4xx/5xx, feature-specific errors

Complete Gap Registry (32 items)

#	Endpoint	Action	Size	Phase	Risk
1	POST /v2/desktop/messages (CRUD)	Port	L	1	High
2	GET /v2/desktop/messages (list)	Port	M	1	High
3	DELETE /v2/desktop/messages	Port	S	1	Low
4	PATCH /v2/desktop/messages/{id}/rating	Port	S	1	Low
5	POST /v2/chat-sessions	Port	L	1	High
6	GET /v2/chat-sessions	Port	M	1	High
7	GET /v2/chat-sessions/{id}	Port	S	1	Low
8	PATCH /v2/chat-sessions/{id}	Port	S	1	Low
9	DELETE /v2/chat-sessions/{id}	Port	S	1	Low
10	POST /v2/chat/initial-message (JSON)	Port	M	1	Med
11	POST /v2/chat/generate-title	Port	M	1	Med
12	POST /v2/agent/provision	Port	L	1	High
13	GET /v2/agent/status	Port	M	1	Med
14	Action item envelope {items, has_more}	Fix	S	1	Low
15	POST /v1/screen-activity/sync	Port	M	2	Med
16	GET/POST/DELETE /v1/focus-sessions	Port	M	2	Low
17	GET /v1/focus-stats	Port	M	2	Low
18	GET /v1/daily-score	Port	M	2	Low
19	GET /v1/scores	Port	M	2	Low
20	GET/PATCH /v1/users/ai-profile	Port	M	2	Low
21	GET/PATCH /v1/users/assistant-settings	Port	M	2	Low
22	POST /v1/staged-tasks/promote	Port	L	2	Med
23	Response shape fixes (7 mismatches)	Fix	M	2	Med
24	GET /v1/crisp/unread	Port	M	3	Low
25	GET /v1/users/stats/chat-messages	Port	S	3	Low
26	GET /.well-known/apple-developer-*	Port	S	3	Low
27	POST/GET /v1/users/me/llm-usage	Port	S	3	Low
28	POST /v2/chat-context	Drop	S	—	—
29	POST /updates/releases	Drop	S	—	—
30	PATCH /updates/releases/promote	Drop	S	—	—
31	POST /v1/webhooks/sentry	Drop	S	—	—
32	POST /v1/staged-tasks/migrate*	Drop	S	—	—

7 Response Shape Mismatches

Field	Rust	Python	Fix
Memory visibility default	"private"	"public"	Change Python default
Memory is_read, is_dismissed	Present	Missing	Add to response model
Action item envelope	{items, has_more}	Raw array	Wrap in envelope
Action item metadata, deleted_by	Present	Missing	Add to response
Chat session title/preview/starred	Present	Missing	Add fields
Conversation started_at/finished_at	Required	Optional	Always populate
Apps capabilities	Vec (ordered)	Set (unordered)	Use list

Rollback Strategy

1. Keep Rust backend hot for 2+ weeks after 100% cutover
2. Per-feature remote config kill switch (chat/agent/tasks can rollback independently)
3. Python compat routes are additive — no destructive schema changes
4. Instant rollback via Cloud Run env var change

Testing Strategy

1. Contract tests — Rust fixtures vs Python responses (key-by-key validation in CI)
2. Decoder tests — Swift Codable decode against Python fixture corpus
3. E2E smoke — chat save/list/rate, session CRUD, agent provision, screen activity sync
4. Golden parity — 7 known mismatches with regression tests

Open Questions

1. Should Swift app eventually adopt Python's RAG pipeline? (out of scope, but informs compat layer permanence)
2. Should agent VM provisioning move to agent-proxy service?
3. Remote config service vs build-time flag for canary?
4. Memory visibility default change — verify mobile app compatibility

Full plan with implementation details: desktop/MIGRATION_PLAN.md (will be committed with first PR)

by AI for @beastoin

[beastoin]

Migration Plan v3 — Daily Release Strategy

Key reframe: Python backend is source of truth. Swift app adapts to Python's contracts. Rust-only features get ported to Python or dropped.

Architecture Decision: Option A — Swift adopts Python streaming chat

Python POST /v2/messages is a streaming RAG pipeline. Swift currently does LLM client-side and uses Rust for CRUD persistence. Target: Swift adopts Python's streaming pipeline, eliminating client-side Gemini dependency and getting full RAG/tool-use for free.

Verified Endpoint Gap Analysis

Checked every endpoint against Python backend source. Results:

Feature	Python Status	Action
Focus sessions/stats	MISSING (no router)	Port to Python
Daily score/scores	MISSING (no router)	Port to Python
AI profile	MISSING (no endpoint)	Port to Python
Assistant settings	MISSING (no endpoint)	Port to Python
Staged tasks (all CRUD + promote)	MISSING (no router, no DB layer)	Port to Python
Advice (CRUD)	MISSING (only goal-advice GET exists)	Port to Python
Screen activity sync	MISSING REST endpoint (DB + Pinecone layer exists)	Port to Python (easy)
Chat sessions	MISSING (no /v2/chat-sessions router)	Port to Python
Crisp unread	MISSING (no endpoint)	Drop for cutover, port later
LLM usage POST	MISSING (only GET exists)	Drop for cutover, port later
Chat message stats	MISSING (no /stats endpoint)	Drop for cutover
Action items envelope	EXISTS but key differs: Python=action_items, Swift expects=items	Swift adapts
Agent VM	EXISTS but v1 paths: Python /v1/agent/vm-status, Swift calls /v2/agent/status	Swift adapts to v1 paths
Knowledge graph	EXISTS — full parity	No work
Conversations, memories, folders, goals, apps, users, people, personas	EXISTS — full parity	No work

20-Day Daily PR Sequence

Every PR is independently shippable and doesn't break the app on either backend.

Week 1: Swift routing framework + decoder hardening

Day	PR	Side	Change	State After
1	PR1	Swift	Add BackendRoutePolicy dual-routing layer (python/rust per endpoint group) with no behavior change. All routes default to Rust.	100% Rust
2	PR2	Swift	Remote-config route map + global kill switch + per-route fallback on 404/decode failure	100% Rust default
3	PR3	Swift	Decoder hardening: action_items key (not items), optional conversation timestamps, optional memory fields (is_read, is_dismissed with defaults)	Works on both backends
4	PR4	Swift	Adapt agent VM calls: /v2/agent/provision → /v1/agent/vm-ensure, /v2/agent/status → /v1/agent/vm-status behind route flag	Rust default, Python-ready

Week 2: Chat engine migration (highest risk)

Day	PR	Side	Change	State After
5	PR5	Swift	Introduce ChatEngine protocol (LegacyGemini vs PythonStreaming). Keep Legacy active.	No behavior change
6	PR6	Swift	Implement PythonStreaming send path for POST /v2/messages (streaming response parsing) behind flag	Legacy default
7	PR7	Swift	Implement Python chat history/rating/delete path (GET/DELETE/PATCH /v2/messages) adapting to Python response shape	Legacy default
8	PR8	Swift	Chat session strategy: map to Python's model (plugin_id=app_id, local title/preview/starred storage or Python chat_sessions if routed)	Legacy default
9	PR9	Swift	Internal canary toggle for Python chat + chat health metrics (decode errors, latency, fallback rate)	Off by default

Week 3: Port Rust-only features to Python

Day	PR	Side	Change	State After
10	PR10	Python	Add POST /v1/screen-activity/sync — wire existing database/screen_activity.py + database/vector_db.py to REST endpoint	Additive, no breakage
11	PR11	Python	Add focus sessions router: GET/POST/DELETE /v1/focus-sessions, GET /v1/focus-stats	Additive
12	PR12	Python	Add GET /v1/daily-score, GET /v1/scores (compute from action_items)	Additive
13	PR13	Python	Add GET/PATCH /v1/users/ai-profile, GET/PATCH /v1/users/assistant-settings	Additive
14	PR14	Python	Add advice CRUD router: GET/POST/PATCH/DELETE /v1/advice, POST /v1/advice/mark-all-read	Additive

Week 4: Staged tasks + canary rollout

Day	PR	Side	Change	State After
15	PR15	Python	Add staged tasks router: GET/POST/DELETE /v1/staged-tasks, PATCH /batch-scores, POST /promote	Additive
16	PR16	Python	Add chat sessions router: POST/GET/PATCH/DELETE /v2/chat-sessions with title/preview/starred/message_count	Additive
17	PR17	Swift	Disable Crisp unread, chat-message stats, LLM cost total in Python mode (graceful no-op)	No breakage
18	PR18	Swift/Ops	Flip 5% internal users to Python route map	Instant rollback
19	PR19	Swift/Ops	Expand to 25% → 100% after SLO gates pass	Rust hot fallback
20	PR20	Ops/Docs	Remove Rust deployment, archive desktop/Backend-Rust/, update docs	Migration complete

Migration Switch Mechanism

1. OMI_API_URL_PYTHON (api.omi.me) + OMI_API_URL_RUST (desktop-backend) in app env
2. BackendRoutePolicy in Swift — per-endpoint-group routing (chat, agent, tasks, screen, etc.)
3. Remote config JSON for policy overrides
4. Automatic fallback: try configured backend, fall back to other on 404/501/decode failure
5. Global kill switch: force all routes to Rust instantly

Rust-Only Feature Decisions

Feature	Decision	Rationale
Screen activity sync	Port (Day 10)	Python has DB+Pinecone layer, just needs REST endpoint
Focus sessions/stats	Port (Day 11)	Simple Firestore CRUD, desktop depends on it
Daily score/scores	Port (Day 12)	Simple computation from action_items
AI profile	Port (Day 13)	Simple Firestore CRUD
Assistant settings	Port (Day 13)	Simple Firestore CRUD
Advice CRUD	Port (Day 14)	Desktop has full Advice UI tab
Staged tasks + promote	Port (Day 15)	Core productivity feature
Chat sessions	Port (Day 16)	Needed for chat history UI
Crisp unread	Drop for cutover	Nice-to-have, port later
LLM usage POST	Drop for cutover	Tracking only, port later
Chat message stats	Drop for cutover	Analytics only
Sentry webhooks	Drop	Desktop-specific, not needed

Canary SLO Gates (Day 18-19)

Must pass before expanding rollout:

• Decode error rate < 0.1%
• Chat send success rate > 99%
• Fallback-to-Rust rate < 5%
• API 5xx rate < baseline + 1%
• p95 latency < 2x Rust baseline

Critical Path

PR1 (routing) → PR3 (decoders) → PR5-9 (chat engine) → PR18 (canary)
                                    ↓
                              PR10-16 (Python ports) → PR18 (canary)

Chat engine migration (Week 2) and Python endpoint ports (Week 3) can run in parallel.

by AI for @beastoin

[beastoin]

3-Day Migration Plan (v4) — Compressed Sprint

Chat Strategy: Option A — Python CRUD compat

Instead of rewriting Swift's ChatEngine (5 days), add desktop-compat CRUD endpoints in Python that match Rust's message save/list/delete contract. Python's streaming RAG stays untouched for mobile/web. Swift app changes = zero for chat.

Saves 4+ days. Full ChatEngine rewrite becomes a follow-up optimization.

---

Day 1: Unblock Critical Contracts (5 PRs in parallel)

PR	Agent	Side	Scope
PR1	A	Python	Chat compat: POST /v2/desktop/messages (CRUD save), GET /v2/desktop/messages (list), DELETE /v2/desktop/messages, PATCH /v2/desktop/messages/{id}/rating — matches Rust contract exactly
PR2	B	Python	Chat sessions: POST/GET/PATCH/DELETE /v2/chat-sessions with title/preview/starred/message_count
PR3	C	Python	Screen activity: POST /v1/screen-activity/sync — wire existing database/screen_activity.py + database/vector_db.py
PR4	D	Swift	Decoder fixes: action_items key fallback, optional timestamps, optional memory fields, agent VM path mapping (v2→v1)
PR5	Integrator	Python	Router wiring in backend/main.py — merge-conflict ownership

Parallelization: PR3, PR4 fully independent. PR1+PR2 share database/chat.py — same agent or sequential. PR5 after all Python PRs.

Day 2: Port Remaining Gaps (5 PRs in parallel)

PR	Agent	Side	Scope
PR6	E	Python	Focus: GET/POST/DELETE /v1/focus-sessions, GET /v1/focus-stats
PR7	F	Python	Scores: GET /v1/daily-score, GET /v1/scores
PR8	G	Python	User settings: GET/PATCH /v1/users/ai-profile, GET/PATCH /v1/users/assistant-settings
PR9	H	Python	Advice: GET/POST/PATCH/DELETE /v1/advice, POST /v1/advice/mark-all-read
PR10	B	Python	Staged tasks: GET/POST/DELETE /v1/staged-tasks, PATCH /batch-scores, POST /promote (largest chunk — promote has dedup + rank logic)

Parallelization: PR6, PR7, PR8, PR9 fully parallel (separate router files, no shared code). PR10 is the longest — start Day 1 afternoon.

Day 3: Integration + Hardening + Cutover

PR	Agent	Side	Scope
PR11	Integrator	Both	Final compat fixes, edge cases, docs update

Testing sequence:

1. backend/test.sh for each Python PR before merge
2. Full test pass on integration branch
3. swift build on desktop PR (decoder changes)
4. Desktop smoke suite against Python backend:
   • Chat: save → list → rate → delete
   • Staged tasks: create → promote → verify action item
   • Focus: create session → get stats
   • Scores: get daily + weekly + overall
   • Advice: create → update → delete
   • Screen activity: sync batch → verify Firestore + Pinecone
   • Agent VM: status check via v1 path
5. Cutover: point desktop OMI_API_URL to api.omi.me
6. Rust backend stays hot as rollback for 72h

---

Critical Path

Day 1: PR1 (chat compat) + PR2 (sessions) ──→ PR5 (wiring) ──→ Day 3 integration
Day 1-2: PR10 (staged tasks)            ──────────────────────→ Day 3 integration  
Day 1: PR4 (Swift decoders)             ──────────────────────→ Day 3 smoke test

Everything else (PR3, PR6-9) is parallel and not on critical path.

What We Sacrifice vs 20-Day Plan

Sacrificed	Impact	Follow-up
Full ChatEngine rewrite	Desktop still does LLM client-side (no Python RAG)	Optimize later
Remote-config dual-routing	Single backend URL, no per-feature fallback	Add if needed
Canary rollout (5%→25%→100%)	Binary cutover with manual rollback	Acceptable for team-size userbase
Crisp/stats/LLM tracking	Graceful no-op	Port later
Deep observability	Basic smoke + error checks only	Add monitoring post-cutover

Risk Assessment

Risk	Severity	Mitigation
Chat compat edge cases	High	Contract tests from Rust fixtures
Staged-task promote regression	Medium	Port exact Rust logic, test with real data
Merge collisions in main.py	Medium	Single integrator owns shared files
3-day timeline slip	Medium	Decision gate: if chat compat unstable by Day 2 noon, switch to Option B (keep Rust for chat only)
Mobile/web breakage	Low	All Python changes are additive, new routes only

Decision Gate

Day 2, noon: If chat-compat PR is not stable → immediately switch to Option B (keep Rust for chat, migrate everything else). This preserves the 3-day schedule.

by AI for @beastoin