[AlbertoSanmartinMartinez]

Problem

Orca 1.4.214 and later keep the profile state in profile-state.db, a SQLite database. A new profile on these versions has no orca-data.json. Because of this, python3 install.py stops with "Orca state was not found. Open Orca, or pass --orca-state PATH.", and the watcher cannot find the selected workspace.

A profile that existed before the update keeps its old orca-data.json. Orca imports that file once and never updates it again (legacy-json README: "The original JSON remains unchanged after import and may be much older than SQLite", L19). An installation made before the Orca update thus reads a stale file, and the panel shows an old workspace without an error. The same README names v1.4.214 as "the first stable SQLite release" (L28).

The new format

profile-state.db has a profile_state_documents table with the columns domain, payload, domain_version, revision, updated_at and content_hash. Each row holds one former top-level key of orca-data.json. The payload of the workspaceSession, repos and folderWorkspaces rows has the same shape as before (domain_version 1). Thus resolve_workspace does not change.

Changes

• workspace.py: in each profile, discovery looks for profile-state.db first and orca-data.json second. When the state file is a database, read_selection reads only the three rows above, with a read-only (mode=ro) SQLite connection. The 16 MiB limit applies to each document. A SQLite error gives the same "Cannot read Orca's current workspace" message as a bad JSON file.
• When config.json (or --orca-state) names an orca-data.json and a profile-state.db is in the same folder, the sync process reads the database. doctor shows that file. Existing installations thus keep working after an Orca update, without a new install.
• Two profiles with different formats still need --profile or --orca-state. The installer does not select one silently.
• install.py: the --orca-state help text names both files.
• Tests: 10 new tests. They cover worktree and folder selection from a database, a read during an open write transaction, a database that does not change, missing or unreadable databases, an oversized document, the discovery order, a stale JSON file next to a database, mixed profile formats, and an install and build from a database.
• Docs: installation, architecture (a new "State formats" section), troubleshooting, FAQ, llms.txt and the changelog. I regenerated the mirrors with scripts/build_docs.py.

Orca keeps the database in WAL mode. A read-only reader does not block the writes of Orca, and it sees only committed state. When Orca is closed, SQLite can create empty -wal and -shm files next to the database. The database file itself does not change, and a test checks this.

Validation

• python3 -m unittest discover -s tests -v: 24 tests pass on Python 3.15 and macOS. I did not run Python 3.9 locally. The CI matrix covers it.
• python3 scripts/check_public.py passes.
• I did not run the browser tests, because the panel did not change.
• Desktop check on Orca 1.4.224, macOS 27.0, Python 3.15: I installed this branch with install.py and registered the runtime plugin folder under Settings → Plugins → Development. The installer found profile-state.db and opened the Git Graph Sync terminal. When I switched worktrees in the left sidebar, the sync output followed each switch (parallel → pipelines-delivery → parallel, 400 commits each) and rewrote panel.html. Each state read took about 2 ms.

🤖 Generated with Claude Code