Status: Accepted (2026-04-24) Supersedes: kanban tasks 20260417184801-7b6a0aa0, 20260417184805-63d6b6ae, 20260417184809-69bbb336 (closed as partial-done) Refines: decision 20260202004516-45e16b85 (Interface-Agnostic Box Architecture) Applies: convention 20260215011959-7e07b9cf (IAddon Composability Principle)
Audit of the current hive-mcp lifecycle surface showed the core module is directly coupled to addon-specific concretions, violating the Interface-Agnostic Box decision (20260202004516-45e16b85). Concrete findings:
src/hive_mcp/server/lifecycle.clj:61-80 — the JVM shutdown hook directly
calls olympus-ws/stop! and resolves hive-mcp.swarm.datascript/mark-coordinator-terminated!
inline. The core lifecycle module knows about Olympus and the DataScript
swarm store by name, so either addon disappearing requires edits to core.src/hive_mcp/agent/headless.clj:406-456 — watchdog-sweep! is bolted
onto the headless addon as a private fn with its own
ScheduledExecutorService, reading the headless-private process-registry.
There is no generic "sweep" abstraction the core can schedule; every future
sweepable resource (addon caches, idle sessions, dead LSP sidecars) would
copy this pattern.src/hive_mcp/agent/ling/spawn.clj:299-333 — kill! already uses
requiring-resolve for the NATS bridge and swarm-event-bridge (good), but
still makes direct calls to ds-lings/can-kill?, ds-lings/remove-slave!,
and lifecycle/resolve-strategy. Release-of-claims and DataScript mutation
run inline with no priority ordering, so kill-ordering relies on call-site
convention rather than a registry.Connection to solo-maintainer axiom 20260228020131-33d15f0b: bus factor = 1, so hive-mcp core must stay small enough to hold in one engineer's head. Every addon-shaped branch that leaks into core inflates the blast radius of a single change.
Historical note (2026-11-14). This Context is the pre-migration audit snapshot; the migration it motivates has since landed and the file:line citations are as of the audit. The JVM shutdown hook in
server/lifecycle.cljno longer callsolympus-ws/stop!ormark-coordinator-terminated!inline: it runs the registry-driven sequencerun-shutdown-sequence!, and the concrete hooks now live insrc/hive_mcp/system/shutdown/in_core.clj. That namespace no longer requires any addon (noolympus-ws); it requires only the protocol, registry andswarm.syncnamespaces.src/hive_mcp/agent/headless.clj'swatchdog-sweep!is no longer a private fn with its own scheduler; it is driven by theHeadlessWatchdogISweepableimpl registered on the sweep coordinator. Thekill!body cited below now sits near the end ofsrc/hive_mcp/agent/ling/spawn.clj(no longer at 299-333). The repo has no trackedplans/directory; the Plan path in Cross-references was an out-of-tree location.
hive-mcp core defines three lifecycle protocols (IShutdownHook,
ISweepable, IResourceOwner, later joined by IShutdownBudget) and owns
three registries plus two orchestrators (a JVM shutdown hook and a sweep
coordinator).
hive-spi.lifecycle.ports and are re-exported as
def aliases from src/hive_mcp/protocols/lifecycle.clj, so an addon can
implement them without compile-depending on hive-mcp. The aliases also
cover IShutdownBudget, added after this ADR.register-shutdown!, register-sweep!,
register-resource-owner!) live under src/hive_mcp/system/registry.clj,
storing into hive-spi.lifecycle.registry keyed by participant id.server/lifecycle.clj
iterates reg/registered-shutdown-hooks in priority order under a
wall-clock budget; the sweep coordinator in system/sweep_coordinator.clj
schedules all ISweepable participants on one shared executor.requiring-resolve from inside the addon's
IAddon.init!. hive-mcp (core)
┌─────────────────────────────────────────┐
│ protocols/lifecycle.clj │
│ IShutdownHook, ISweepable, IResourceOwner, IShutdownBudget
│ system/registry.clj │
│ register-shutdown!, register-sweep!, register-resource-owner!
│ system/sweep_coordinator.clj │
│ server/lifecycle.clj (orchestrator) │
└──────────────▲──────────────────────────┘
│ register! via requiring-resolve
│
┌──────────────┼──────────────┬──────────┬──────────────┐
│ │ │ │ │
hive-agent hive-knowledge hive-nats hive-qdrant lsp-mcp
(lings, (KG stores, (NATS (vector (sidecar
headless, index cache client store process)
terminal) sweep) close) close)
| Band | Phase | Examples |
|---|---|---|
| 0-99 | External service stop | Olympus WS |
| 100-199 | Subprocess kill | Lings, LSP sidecars, headless processes |
| 200-299 | Client close | NATS, Chroma, Qdrant |
| 300-399 | Store close | Datalevin, Datahike, Proximum |
| 400+ | Final bookkeeping | Coordinator mark-terminated, session-end |
Bands are enforced by the registry at insertion time; participants declare their band in the registration call and the orchestrator sorts ascending.
Positive
server/lifecycle.clj imports olympus-ws; after migration
it imports only the protocol and registry namespaces.register! call in its init!; no
core edits.ClassNotFoundException.Negative
requiring-resolve at register time adds a small startup cost (one-shot
per addon, bounded).init! is a local edit.when (resolve ...) switches on classpath presence —
rejected: non-composable and violates the IAddon principle
(20260215011959-7e07b9cf). Core ends up knowing every addon namespace.plans/cluster-a-lifecycle-protocols.edn (an out-of-tree plans/
dir; no plans/ is tracked in this repo)Can you improve this documentation?Edit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |