logseq/docs/agent-guide/034-db-worker-node-owner-process-management.md

DB Worker Node Owner-Aware Process Management Implementation Plan

Goal: Add owner-aware lock metadata and orphan-process recovery so CLI and Electron can safely share one graph daemon without cross-managing each other.

Architecture: Keep one db-worker.lock per graph directory, but extend lock schema with owner-source so lifecycle actions can enforce owner boundaries. Architecture: Keep read and write traffic reusable across clients, while restricting stop and restart to the side that originally started the daemon. Architecture: Add orphan-process detection for lock-missing cases so logseq server restart does not hang on timeout when a legacy process is still alive.

Tech Stack: ClojureScript, Node.js child process APIs, promesa, logseq.cli.server, logseq.db-worker.daemon, Electron main-process daemon manager, db-worker-node lock helpers.

Related: Builds on docs/agent-guide/033-desktop-db-worker-node-backend.md. Related: Relates to docs/agent-guide/030-logseq-cli-db-graph-default-dir-locking.md. Related: Relates to docs/agent-guide/003-db-worker-node-cli-orchestration.md.

Problem statement

Current lock payload only records repo, pid, host, and port, so ownership is implicit and lifecycle commands cannot distinguish CLI-started and Electron-started daemons.

stop-server! and restart-server! can currently terminate any alive daemon if the lock exists, which violates the requirement that each client should manage only its own process.

If a db-worker-node process remains alive but lock file is missing, server restart can wait until timeout because startup relies on lock appearance and has no orphan recovery path.

When CLI starts a daemon first, Electron may treat the runtime as managed-by-self and attempt stop or restart logic, which can break graph open flow and produce user-facing errors.

Testing Plan

I will follow @test-driven-development and add failing tests before each implementation change.

I will add lock schema and owner compatibility tests in src/test/frontend/worker/db_worker_node_lock_test.cljs.

I will add daemon-owner lifecycle and orphan-recovery tests in src/test/logseq/cli/server_test.cljs and src/test/logseq/db_worker/daemon_test.cljs.

I will add Electron manager tests for external-runtime attachment and no-cross-stop behavior in src/test/electron/db_worker_manager_test.cljs.

I will add db-worker-node argument and lock-write tests in src/test/frontend/worker/db_worker_node_test.cljs.

I will run focused red-green loops first, then run bb dev:lint-and-test, and finish with a review pass against @prompts/review.md.

NOTE: I will write all tests before I add any implementation behavior.

Current behavior map

Area	Current behavior	Target behavior
Lock metadata	No owner field in db-worker.lock.	Lock includes owner-source as cli or electron, plus versioned metadata.
Lifecycle authority	Any caller can stop or restart lock-owned daemon.	stop and restart are allowed only for matching owner-source.
Runtime reuse	Reuse happens, but manager cannot tell owned vs external runtime.	Reuse still happens, and runtime state tracks owned? to prevent cross-stop.
Lock missing + orphan process	Startup can timeout with no clear recovery path.	Orphan detection and cleanup path runs before or after failed startup wait.
Compatibility	Legacy lock without owner is ambiguous.	Legacy lock is treated as owner-source: unknown with explicit policy.

Integration sketch

CLI or Electron request ensure-server(repo, requester-owner)
  -> read lock
  -> if lock exists and healthy:
       return runtime + ownership(owned/external)
  -> if lock missing:
       scan orphan db-worker-node process for same repo/data-dir
       if orphan found:
         terminate orphan
       spawn new daemon with --owner-source <cli|electron>
  -> db-worker-node writes lock {repo,pid,host,port,owner-source,lock-id,...}

stop/restart(requester-owner)
  -> read lock owner-source
  -> if owner-source matches requester-owner: allow
  -> else: deny with :server-owned-by-other

Implementation plan

Phase 1: Add failing tests for owner-aware lock schema and policies.

1. Add a failing test in src/test/frontend/worker/db_worker_node_lock_test.cljs that lock serialization includes owner-source.
2. Add a failing test in src/test/frontend/worker/db_worker_node_lock_test.cljs that missing owner metadata is normalized to :unknown.
3. Add a failing test in src/test/frontend/worker/db_worker_node_test.cljs that --owner-source cli is written into the lock.
4. Add a failing test in src/test/frontend/worker/db_worker_node_test.cljs that --owner-source electron is written into the lock.
5. Add a failing test in src/test/logseq/cli/server_test.cljs that stop-server! returns :server-owned-by-other on owner mismatch.
6. Add a failing test in src/test/logseq/cli/server_test.cljs that restart-server! does not SIGTERM external-owner daemon.
7. Add a failing test in src/test/electron/db_worker_manager_test.cljs that external runtime release does not call stop-daemon!.
8. Run bb dev:test -v 'frontend.worker.db-worker-node-lock-test' and confirm failures match new assertions.
9. Run bb dev:test -v 'logseq.cli.server-test' and confirm failures match new assertions.

Phase 2: Extend lock schema and daemon startup arguments.

10. Update argument parsing in src/main/frontend/worker/db_worker_node.cljs to accept --owner-source.
11. Add owner-source validation in src/main/frontend/worker/db_worker_node.cljs with allowed values cli, electron, and fallback unknown.
12. Thread owner-source through start-daemon! in src/main/frontend/worker/db_worker_node.cljs into lock creation.
13. Update create-lock! in src/main/frontend/worker/db_worker_node_lock.cljs to persist owner-source.
14. Update read-lock normalization path in src/main/frontend/worker/db_worker_node_lock.cljs to inject :owner-source :unknown for legacy files.
15. Keep update-lock! in src/main/frontend/worker/db_worker_node_lock.cljs from mutating existing owner-source during port updates.
16. Add targeted tests for lock read-write roundtrip in src/test/frontend/worker/db_worker_node_lock_test.cljs.
17. Run bb dev:test -v 'frontend.worker.db-worker-node-test' and make sure lock owner assertions pass.

Phase 3: Make CLI server orchestration owner-aware.

18. Add requester owner config to ensure-server! in src/main/logseq/cli/server.cljs.
19. Pass owner-source to daemon spawn args from spawn-server! in src/main/logseq/db_worker/daemon.cljs.
20. Update ensure-server-started! in src/main/logseq/cli/server.cljs to return ownership metadata for caller state tracking.
21. Update stop-server! in src/main/logseq/cli/server.cljs to deny stop when lock owner-source differs from requester owner.
22. Update restart-server! in src/main/logseq/cli/server.cljs to preserve the same owner check semantics as stop-server!.
23. Update server-status and list-servers in src/main/logseq/cli/server.cljs to include owner-source in output payload.
24. Update server command response formatting so logseq server list human output includes an OWNER column mapped from owner-source (and preserves owner metadata in structured output).
25. Add regression tests in src/test/logseq/cli/server_test.cljs for owner-aware start, stop, and restart.
26. Run bb dev:test -v 'logseq.cli.server-test' and verify no timeout-based flaky failure remains.

Phase 4: Add orphan-process detection and recovery for lock-missing start.

27. Add process listing helper in src/main/logseq/db_worker/daemon.cljs that discovers db-worker-node processes by repo and data-dir arguments.
28. Add parser helpers in src/main/logseq/db_worker/daemon.cljs to read repo, data-dir, and owner-source from command args.
29. Add cleanup-orphan-process! in src/main/logseq/db_worker/daemon.cljs to SIGTERM matched orphan pids before new spawn.
30. Call orphan cleanup path in ensure-server-started! in src/main/logseq/cli/server.cljs when lock is missing before spawn.
31. Add timeout fallback in ensure-server-started! in src/main/logseq/cli/server.cljs to emit :server-start-timeout-orphan with discovered pids.
32. Add unit tests in src/test/logseq/db_worker/daemon_test.cljs for process-arg parsing and orphan match logic.
33. Add CLI regression test in src/test/logseq/cli/server_test.cljs for lock-missing orphan scenario to avoid raw timeout.
34. Run bb dev:test -v 'logseq.db-worker.daemon-test' and bb dev:test -v 'logseq.cli.server-test'.

Phase 5: Make Electron manager attach external daemon without cross-management.

35. Pass requester owner as electron from start-managed-daemon! in src/electron/electron/db_worker.cljs.
36. Save ownership flag in manager runtime state in src/electron/electron/db_worker.cljs.
37. Update stop flow in src/electron/electron/db_worker.cljs so stop-daemon! runs only when owned? is true.
38. Update unhealthy-runtime branch in src/electron/electron/db_worker.cljs to avoid stopping external owner daemon and re-resolve runtime instead.
39. Add tests in src/test/electron/db_worker_manager_test.cljs for external runtime reuse plus no-stop-on-release.
40. Run bb dev:test -v 'electron.db-worker-manager-test' and confirm lifecycle behavior.

Phase 6: Update docs and error surfaces.

41. Update CLI docs in docs/cli/logseq-cli.md to document owner-aware server stop and server restart behavior.
42. Update desktop lifecycle docs in docs/developers/desktop-db-worker-node.md to explain external runtime attachment semantics.
43. Add explicit error messages for :server-owned-by-other and :server-start-timeout-orphan in src/main/logseq/cli/format.cljs.
44. Add one integration note in docs/agent-guide/033-desktop-db-worker-node-backend.md linking to owner-aware behavior.

Phase 7: Full verification and review gate.

45. Run bb dev:test -v 'frontend.worker.db-worker-node-test'.
46. Run bb dev:test -v 'frontend.worker.db-worker-node-lock-test'.
47. Run bb dev:test -v 'logseq.db-worker.daemon-test'.
48. Run bb dev:test -v 'logseq.cli.server-test'.
49. Run bb dev:test -v 'electron.db-worker-manager-test'.
50. Run bb dev:lint-and-test and confirm zero failures and zero errors.
51. Perform final review checklist pass against @prompts/review.md.

Edge cases

Scenario	Expected behavior
Lock file missing but old CLI daemon still alive.	CLI restart detects orphan by repo and data-dir, cleans it, then starts cleanly.
Lock owner is cli and Electron calls ensure runtime.	Electron reuses runtime with owned? false and never stops it on window close.
Lock owner is electron and CLI calls server stop.	CLI returns :server-owned-by-other with owner metadata and no process kill.
Legacy lock file has no owner-source field.	System treats owner as unknown and allows CLI takeover with owner metadata rewrite.
Two owners race to start same graph.	First lock wins and second caller reuses healthy daemon without extra spawn.
Owner process crashes and lock remains stale.	Stale lock cleanup still works, and next owner can start daemon normally.

Verification commands and expected outputs

bb dev:test -v 'frontend.worker.db-worker-node-lock-test'
bb dev:test -v 'frontend.worker.db-worker-node-test'
bb dev:test -v 'logseq.db-worker.daemon-test'
bb dev:test -v 'logseq.cli.server-test'
bb dev:test -v 'electron.db-worker-manager-test'
bb dev:lint-and-test

Each command should finish with 0 failures, 0 errors.

The owner-mismatch tests should return :server-owned-by-other instead of timeout or forced stop behavior.

logseq server list human output should include an OWNER column.

The orphan-recovery tests should return deterministic cleanup behavior instead of waiting until generic timeout.

Testing Details

The tests validate behavior by asserting lifecycle authority boundaries, successful runtime reuse across clients, and orphan recovery outcomes.

The tests avoid mock-only success criteria by asserting returned error codes and process-management side effects observable from public APIs.

The critical regressions are lock-missing orphan restart and CLI-first then Electron-open graph flow, and both are explicitly covered.

Implementation Details

• Extend lock payload with owner-source and preserve it across lock updates.
• Pass --owner-source when spawning db-worker-node from both CLI and Electron pathways.
• Return ownership metadata from server orchestration so callers can track owned? state.
• Enforce owner check for stop and restart while keeping read and write invoke reuse unchanged.
• Add orphan process discovery by command args for lock-missing recovery.
• Scope orphan process discovery in v1 to macOS and Linux, and use a Windows-safe no-op fallback.
• Keep stale-lock cleanup logic and layer orphan recovery without changing healthy lock reuse flow.
• Add explicit CLI error codes for owner mismatch and orphan timeout contexts.
• Prevent Electron manager from stopping external-owner runtime on release or health fallback.
• Document operator-visible behavior changes in CLI and desktop developer docs.
• Execute full suite and @prompts/review.md checks before merge.

Question

Decision: CLI is allowed to take over owner-source: unknown and rewrite ownership metadata in v1.

Decision: when lock file is missing, orphan cleanup terminates all matching repo and data-dir processes.

Decision: v1 scopes orphan process-scan support to macOS and Linux only, with a Windows-safe no-op fallback.

---