doctor: needs source/dev-mode awareness — flags FAIL on intentional non-canonical layouts

[vasconceloscezar]

Summary

omni doctor assumes the canonical embedded deployment layout: PM2 entry named omni-api, embedded pgserve at port 8432, data dir ~/.omni/data/pgserve. Users running omni from source (the documented dev workflow — bun packages/api/src/index.ts) get a wall of FAIL/WARN findings even though their setup is healthy and intentional. There's no way to express "I know what I'm doing, this is dev mode, skip canonical-layout checks."

What we see

Host runs omni from source (cwd /home/genie/dev/omni), PM2 entry name omni-v2-api, sharing canonical pgserve on port 8434 (used by genie):

$ omni doctor
  ⚠ pm2-env-drift        omni-api not found in pm2
  ✓ cli-key-valid        stored CLI key validates against server
  ✗ pgserve-reachable    cannot connect to pgserve on :8432
  ✓ omni-db-exists       omni database is reachable
  ⚠ orphaned-data-dirs   orphaned data dirs: /home/genie/repos/omni/.pgserve-data
  ⚠ version-match        version mismatch: cli=v2.260508.4 server=v2.260501.1
  ✗ pm2-status           pm2 status: omni-api=missing omni-nats=online
  ✗ pm2-max-restarts     omni-api not found in pm2; omni-nats has no max_restarts
  ✓ pm2-logrotate-installed pm2-logrotate installed with expected settings
  ✓ pgserve-canonical    using canonical pgserve@^2.1.0
  ✗ port-canonical-owner omni-api:8882 owned by pid=550121 but pm2 has no PID for omni-api

  summary: 5 OK, 3 WARN, 4 FAIL

Every FAIL is correct for the canonical layout and wrong for source mode:

Check	What it says	What's actually true
pgserve-reachable :8432	"can't connect"	Connecting to canonical pgserve on :8434, intentionally
pm2-status omni-api=missing	"missing"	Entry is named omni-v2-api, intentionally
port-canonical-owner	"owned but pm2 has no PID for omni-api"	PM2 has it under the source-mode name
version-match	"cli=v2.260508.4 server=v2.260501.1"	Server is built from local source HEAD, expected to drift

The danger: if a less-experienced operator runs omni doctor --fix here, the canonical migration would try to "fix" the working dev setup into the canonical layout, breaking the developer's workflow.

Why source mode matters

Source mode is the documented contributor path (clone repo, bun install, bun packages/api/src/index.ts). Many operators run it permanently: faster iteration, custom branches for testing, or hosting omni alongside genie in a shared-pgserve setup. omni doctor should support — not silently penalize — this path.

Suggested fixes

Minimum: detect dev mode and label N/A

If the running omni-* PM2 process's pm_exec_path points to a packages/api/src/index.ts (or any path inside a git working tree, not node_modules/), tag dev mode and:

• Skip pm2-env-drift for the canonical name; check the discovered name instead
• Skip version-match (or downgrade to INFO with "dev build")
• Skip pgserve-reachable :8432 if DATABASE_URL env var resolves to a healthy postgres on a different port
• pm2-status should look up the discovered name, not hardcode omni-api

Better: explicit profile in config

~/.omni/config.json could carry "deploymentMode": "embedded" | "canonical" | "source". Doctor checks branch on profile; omni doctor --fix becomes a no-op (or prints "doctor is informational in source mode") when deploymentMode === "source".

Best: refuse --fix on source mode

Even with source-mode awareness for read-only checks, omni doctor --fix should refuse to run when source mode is detected (or require --force-canonical-migration) — the consequences of fixing a working dev setup back into canonical layout are severe and silent.

Reproduction

# Clone, build, run from source
git clone https://github.com/automagik-dev/omni /tmp/omni && cd /tmp/omni
bun install
PGSERVE_EMBEDDED=false DATABASE_URL=postgresql://postgres:postgres@localhost:8434/omni \
  pm2 start "bun packages/api/src/index.ts" --name omni-v2-api
# Install canonical pgserve via genie (or any other consumer) on :8434
omni doctor
# Observe 4 FAILs that are all false positives for this intentional layout

Environment

• omni CLI: 2.260508.4
• omni server: built from source at HEAD 2.260501.1
• pgserve: 2.3.0 (canonical, shared with genie)
• PM2 entry: omni-v2-api (deliberate; predates canonical naming)
• bun: 1.3.11
• OS: Linux 6.8.12-16-pve

Related

• omni-api crash-loops on hosts with canonical pgserve due to embedded-pgserve internal port collision (port 9432) #609 (canonical pgserve coexistence) — adjacent: that issue handles embedded-vs-canonical at the embedded-pgserve layer; this one is about doctor's mental model of layout
• fix(doctor): isPgserveInstalled probe via 'pgserve port' false-negatives on freshly-installed binary #582 / fix(doctor): cli-key-valid cascade reproduces when canonical-pgserve fix returns FAILED #583 (doctor probe + cascade fixes) — same surface