Per-workspace dashboard identity: stable instance id + auto-derived ports¶

Angelo › zettelkasten › Phase 2: Literature Review System › Workshop tab: Reading Syllabus (learn) + claim-centric Review/Outline (write) › Phase M4+M5 (combined): Analysis tools + Phase 2 enrichment — queued coordinator graph › Dashboard shakedown: fix KGLite/native concurrency SIGSEGV + multi-workspace port collision

Type: Decision · Status: active · Created: 2026-06-22

Tags: dashboard,launcher,multi-workspace,ports

Completes the multi-workspace coexistence fix. Two checkouts of the same dashboard (e.g. angelo + a sibling clone like fin-notes) previously shared one service name ("zettelkasten-dashboard") and one default port, so the launcher's health-confirmed port skip would adopt the other workspace's backend (serving a stale API) instead of starting its own.

Fix (shared launcher_core, so both memory and zettelkasten dashboards benefit): 1. Stable per-workspace instance id = first 8 hex of sha1(resolved workspace path). Deterministic on purpose (NOT a random per-window UUID, which would stop the launcher recognizing/skipping its own already-running dashboard and require plumbing the id from the window). Both launcher and backend derive the same id independently from ANGELO_WORKSPACE; the launcher also exports ANGELO_DASHBOARD_INSTANCE. 2. Identity-aware health: /api/health now reports service='@' (e.g. zettelkasten-dashboard@4648ceff) plus an instance field. The launcher only treats a port as 'ours' on an instance match, so a sibling checkout's dashboard reads as foreign instead of being adopted. 3. Auto-derived per-workspace ports: resolve_ports() shifts base ports by a deterministic offset (int(instance,16) % PORT_OFFSET_SPAN, span=64, env-tunable); explicit env override (ZK_DASHBOARD_BACKEND_PORT etc.) still wins. angelo lands on backend 8805 / frontend 5237. Launcher exports resolved ports into child env; both vite.config.ts read them so the Vite proxy/port match the backend.

main entries now pass base ports + frontend_port_env and let the core own resolution. 40 launcher tests pass (added coverage: instance-id stability/path-normalisation, env fallback, port-offset determinism, env override, distinct-workspace separation); both backends import cleanly.

Referenced files¶

Source: memory entry deci-e627491d.