heph.nvim: plug-and-play managed daemon (autostart, self-heal, client/server guardrail)

The plugin now manages its own hephd by default (autostart = true): if nothing
is serving the socket it spawns a local daemon against the default XDG paths,
kills only what it spawned on VimLeavePre, and self-heals — rpc.call retries
once through a respawn hook when the connection drops (the prior owner releases
the DB lock on exit, so a respawn can claim it).

- daemon.ensure() connects to an already-running daemon (any mode) or spawns one
  we own; stop_spawned()/is_managed() track lifecycle.
- A server/client daemon you started is always respected (spawn only when nothing
  serves the socket). autostart = false → connect-only, warns/errors if down,
  and clears the self-heal hook so it fails loudly.
- config: autostart defaults true; new `db` option; $HEPH_SOCKET / $HEPH_DB
  fallbacks isolate a dev Neovim onto a separate daemon + DB.

e2e: managed_daemon_spec covers autostart spawn, self-heal-after-kill, and
connect-only error. 10 specs green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

heph.nvim/lua/heph/config.lua

@@ -3,19 +3,25 @@
 local M = {}
 
 M.defaults = {
-  --- Path to hephd's unix socket. `nil` → resolved to the daemon default.
+  --- Path to hephd's unix socket. `nil` → `$HEPH_SOCKET`, else the daemon default.
   socket = nil,
-  --- Spawn a local hephd if the socket is not ready (off by default in v1).
-  autostart = false,
-  --- hephd binary for autostart.
+  --- DB path for an autostarted local daemon. `nil` → `$HEPH_DB`, else hephd's default.
+  db = nil,
+  --- Plug-and-play: spawn (and manage) a local hephd when none is serving
+  --- `socket`. Set `false` when you run your own daemon (server/client): the
+  --- plugin then connects only, and warns if nothing is reachable.
+  autostart = true,
+  --- hephd binary for autostart (on PATH for an installed heph).
   bin = "hephd",
   --- Set the default `<leader>h*` keymaps. `false` to opt out.
   keymaps = true,
 }
 
---- Resolve the socket path, mirroring hephd's `default_socket_path`:
---- `$XDG_RUNTIME_DIR/heph/hephd.sock`, falling back to the temp dir.
+--- Resolve the socket path: explicit opt, then `$HEPH_SOCKET`, then hephd's
+--- default (`$XDG_RUNTIME_DIR/heph/hephd.sock`, temp-dir fallback). The env knob
+--- lets a dev Neovim target a `mise run dev` daemon without touching real data.
 function M.resolve_socket(opt)
+  opt = (opt and #opt > 0) and opt or vim.env.HEPH_SOCKET
   if opt and #opt > 0 then
     return opt
   end
@@ -24,6 +30,17 @@ function M.resolve_socket(opt)
   return (base:gsub("/+$", "")) .. "/heph/hephd.sock"
 end
 
+--- Resolve the DB path for an autostarted daemon: explicit opt, then `$HEPH_DB`,
+--- else nil (let hephd pick its default). Pairs with `resolve_socket` for dev
+--- isolation.
+function M.resolve_db(opt)
+  opt = (opt and #opt > 0) and opt or vim.env.HEPH_DB
+  if opt and #opt > 0 then
+    return opt
+  end
+  return nil
+end
+
 --- Apply the default keymaps (no-op when `opts.keymaps` is false).
 function M.apply_keymaps(opts)
   if not opts.keymaps then

heph.nvim/lua/heph/daemon.lua

@@ -6,6 +6,10 @@ local uv = vim.uv or vim.loop
 
 local M = {}
 
+-- The daemon THIS nvim spawned (nil if we connected to an existing one).
+-- `{ handle, exited = { done }, socket, db, bin }`.
+M._managed = nil
+
 --- Spawn a `local`-mode hephd against `opts.db` listening on `opts.socket`.
 --- `opts.bin` defaults to `hephd` on PATH. Returns `{ handle, pid }`.
 function M.spawn(opts)
@@ -55,4 +59,71 @@ function M.wait_ready(socket, timeout)
   return true
 end
 
+--- Ensure a daemon is reachable at `opts.socket`. If one is already serving the
+--- socket (any mode — local/server/client), connect to it and do NOT spawn. Else
+--- if `opts.autostart`, spawn a local hephd we own (and manage its lifecycle).
+--- Returns `reachable, spawned_by_us`.
+function M.ensure(opts)
+  -- Already serving? A quick probe respects a daemon someone else started.
+  if M.wait_ready(opts.socket, opts.probe_ms or 400) then
+    return true, false
+  end
+  if not opts.autostart then
+    return false, false
+  end
+  local exited = { done = false }
+  local d = M.spawn({
+    bin = opts.bin,
+    socket = opts.socket,
+    db = opts.db,
+    on_exit = function()
+      exited.done = true
+    end,
+  })
+  local ok, reason = M.wait_ready(opts.socket, opts.ready_ms or 5000)
+  if not ok then
+    pcall(function()
+      if not d.handle:is_closing() then
+        d.handle:kill("sigterm")
+      end
+    end)
+    error("heph: spawned hephd but it never became ready: " .. tostring(reason))
+  end
+  M._managed = {
+    handle = d.handle,
+    exited = exited,
+    socket = opts.socket,
+    db = opts.db,
+    bin = opts.bin,
+  }
+  return true, true
+end
+
+--- True if this nvim currently owns a live spawned daemon.
+function M.is_managed()
+  return M._managed ~= nil and not M._managed.exited.done
+end
+
+--- Stop the daemon this nvim spawned (no-op if we connected to an existing one).
+function M.stop_spawned()
+  local m = M._managed
+  if not m then
+    return
+  end
+  M._managed = nil
+  if m.handle and not m.exited.done then
+    pcall(function()
+      m.handle:kill("sigterm")
+    end)
+    vim.wait(2000, function()
+      return m.exited.done
+    end, 20)
+  end
+  pcall(function()
+    if m.handle and not m.handle:is_closing() then
+      m.handle:close()
+    end
+  end)
+end
+
 return M

heph.nvim/lua/heph/init.lua

@@ -14,15 +14,44 @@ M.config = nil
 function M.setup(opts)
   local cfg = vim.tbl_deep_extend("force", config.defaults, opts or {})
   cfg.socket = config.resolve_socket(cfg.socket)
+  cfg.db = config.resolve_db(cfg.db)
   M.config = cfg
 
-  require("heph.rpc").setup(cfg.socket)
+  local rpc = require("heph.rpc")
+  local daemon = require("heph.daemon")
+  rpc.setup(cfg.socket)
 
   if cfg.autostart then
-    local ok = require("heph.daemon").wait_ready(cfg.socket, 500)
+    -- Plug-and-play: bring up a managed local daemon if none is serving, and
+    -- self-heal a dropped connection on later calls.
+    local ok = pcall(daemon.ensure, {
+      socket = cfg.socket,
+      db = cfg.db,
+      bin = cfg.bin,
+      autostart = true,
+    })
     if not ok then
-      require("heph.daemon").spawn({ bin = cfg.bin, socket = cfg.socket, db = nil })
-      require("heph.daemon").wait_ready(cfg.socket, 5000)
+      require("heph.util").notify(
+        "could not start hephd; will retry on first use",
+        vim.log.levels.WARN
+      )
+    end
+    rpc.set_respawn(function()
+      pcall(daemon.ensure, {
+        socket = cfg.socket,
+        db = cfg.db,
+        bin = cfg.bin,
+        autostart = true,
+      })
+    end)
+  else
+    -- Explicit architecture: connect only, never spawn over the user's daemon.
+    rpc.set_respawn(nil)
+    if not daemon.ensure({ socket = cfg.socket, autostart = false }) then
+      require("heph.util").notify(
+        "no hephd reachable at " .. cfg.socket .. " (autostart disabled)",
+        vim.log.levels.WARN
+      )
     end
   end
 

heph.nvim/lua/heph/rpc.lua

@@ -182,9 +182,34 @@ function M.session()
   return M._default
 end
 
---- Blocking call on the default session.
+--- Register a hook that (re)ensures the daemon — called once to self-heal a
+--- dropped connection before a single retry. `nil` disables self-heal (used when
+--- autostart is off, so a connect-only setup fails loudly instead of respawning).
+function M.set_respawn(fn)
+  M._respawn = fn
+end
+
+local function is_connection_error(msg)
+  msg = tostring(msg)
+  return msg:find("connect", 1, true) ~= nil
+    or msg:find("connection", 1, true) ~= nil
+    or msg:find("timeout", 1, true) ~= nil
+end
+
+--- Blocking call on the default session. If the call fails because the
+--- connection is dead and a respawn hook is set, ensure the daemon and retry
+--- once (the prior owner releases the DB lock on exit, so a respawn can claim it).
 function M.call(method, params, opts)
-  return M.session():call(method, params, opts)
+  local ok, result = pcall(M.session().call, M.session(), method, params, opts)
+  if ok then
+    return result
+  end
+  if M._respawn and is_connection_error(result) then
+    pcall(M._respawn)
+    M.session():close() -- drop the dead connection so the retry reconnects
+    return M.session():call(method, params, opts)
+  end
+  error(result)
 end
 
 --- An isolated session for a socket — used by tests for independent assertions.