docs(docs): add ADR-0036 for omni-dev daemon framework deployment and lifecycle

[newhoggy]

Description

This PR adds ADR-0036, proposing the daemon framework design for omni-dev, covering deployment, IPC, lifecycle management, and per-OS supervisor integration. The ADR addresses the architectural need for a long-lived shared daemon process to support features requiring persistent state, shared resources, or cross-session coordination — most immediately the proposed Claude Code chat-history module from issue #876.

The core problem: per-invocation MCP servers cannot cheaply support features requiring a persistent on-disk index (Tantivy + SQLite + vectors), an always-loaded embedding model (~500 MB resident, ~80 ms cold-start), or coordination across multiple concurrent Claude Code instances. Without a shared daemon, N concurrent Claude Code sessions each spawn their own MCP server processes, leading to the documented 42-process / ~1.9 GB RAM OOM problem (anthropics/claude-code#28860).

ADR-0036 records twelve policies taken together that define the daemon framework:

1. Single binary — omni-dev daemon serve, omni-dev mcp stub, and all existing CLI subcommands coexist in one artifact with one version number.
2. Stub + daemon split — supervisor (systemd/launchd) as the primary path; stub-spawn as the automatic fallback.
3. IPC — Unix domain sockets on Linux/macOS, named pipes on Windows, CBOR framing for non-MCP control traffic.
4. Linux deployment — systemd user units with socket activation (omni-dev-daemon.socket + omni-dev-daemon.service).
5. macOS deployment — launchd LaunchAgent plist with Sockets key and KeepAlive.Crashed = true.
6. Windows deployment — stub-spawn by default; opt-in Scheduled Task via omni-dev daemon install-service.
7. Filesystem layout — XDG-aware cross-platform paths via the directories crate; per-module data under modules/<name>/.
8. Generic module hosting — daemon is not history-specific; modules implement a small trait; shared embedding-model pool, tokio runtime, and IPC layer.
9. Installation flow — omni-dev daemon setup (= install + install-mcp + install-hooks); all steps idempotent with matching uninstall counterparts.
10. Version handshake — every stub→daemon connection carries version info; stub-newer-than-daemon triggers graceful supervisor-assisted self-restart.
11. Security — peer-credential verification, 0600 socket/pipe permissions, 0700 data directories, no network listener by default, refuse to run as root.
12. Out of scope for v1 — multi-machine HTTP transport, Windows Services, Docker/OCI, sandbox/seccomp hardening, user-overridable paths.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test coverage improvement
• CI/CD changes
• Dependency update

Related Issue

Relates to #876 — proposal: shared-daemon MCP server for Claude Code session history; the proximate driver for the daemon framework.

Changes Made

Documentation:

• Added docs/adrs/adr-0036.md — full Architecture Decision Record (512 lines) covering daemon framework deployment and lifecycle with status 🟡 Proposed (2026-05-25)
• Updated docs/adrs/README.md — registered ADR-0036 in the ADR index table

ADR Content Coverage:

• Context: explains why the per-invocation MCP pattern is insufficient for persistent-state features and the multi-session OOM problem
• Decision: twelve numbered policies covering binary structure, IPC design, per-OS supervisor integration, module hosting, installation flow, version handshake, security, and explicit out-of-scope boundaries
• Consequences: positive (one binary, best-practice deployment, 42-process problem solved, generic framework), negative (more runtime moving parts, per-OS complexity, weaker Windows story), and neutral observations
• Coverage expectations: mirrors ADR-0028/ADR-0035 patterns; specifies which surfaces are uncovered by design (live systemctl/launchctl execution in CI) and which must be covered cross-platform (file generation golden tests, IPC round-trips, handshake version-skew matrix, stub-spawn fallback, end-to-end daemon setup in a temp $HOME)

Testing

Automated Testing:

• All existing tests pass
• New tests added for new functionality — N/A; this is a documentation-only PR
• Integration tests updated/added — N/A
• Performance tests (if applicable) — N/A

Manual Testing:

• Reviewed ADR content for accuracy, consistency with referenced ADRs (ADR-0016, ADR-0021, ADR-0027, ADR-0028, ADR-0030, ADR-0035), and correct Markdown formatting
• Verified ADR index entry in docs/adrs/README.md matches the new file name and summary

Test Commands

# Code quality checks (no code changed, but verify docs build cleanly)
cargo clippy -- -D warnings
cargo fmt --check

# Core test suite
cargo test

Review Focus Areas

Please pay special attention to:

• Architecture changes — the proposed daemon architecture is a significant structural decision; reviewers should evaluate whether the twelve policies are complete, consistent, and correctly scoped
• Security implications — the security policy in §11 (peer credentials, socket permissions, no-root enforcement) is documented but not yet implemented; verify the policy is sufficient before implementation begins
• Backward compatibility — §1 and §8 assert the existing omni-dev MCP server and all existing CLI subcommands are unchanged; confirm the proposed namespacing (omni-dev-daemon MCP server alongside omni-dev) is acceptable
• User experience — the omni-dev daemon setup / install / install-mcp / install-hooks / teardown command hierarchy; verify it fits ADR-0016's hierarchical subcommand conventions

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works — N/A; documentation-only PR
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published — implementation PRs will follow
• I have read and followed the PR Guidelines

Performance Impact

• No performance impact — this PR adds only documentation; no code is changed

Security Considerations

• No security implications — this PR contains only an ADR document proposing a security policy; no security-sensitive code is added or modified in this PR

Breaking Changes

None. This PR adds only documentation. No existing functionality is changed.

Deployment Notes

• No special deployment requirements — documentation-only change

Additional Notes

Future Enhancements:

• Implementation PRs will follow this ADR to build the actual daemon framework, starting with the IPC layer and module trait, then per-OS supervisor integration
• A follow-up ADR specific to the history module (storage schema, MCP tool surface, embedding strategy) is scoped to issue proposal: shared-daemon MCP server for Claude Code session history #876

Known Limitations:

• ADR-0036 is currently 🟡 Proposed; it is not yet Accepted. Implementation should not begin until the ADR is accepted after review
• Windows deployment is materially weaker than Linux/macOS in v1 (no socket activation, opt-in Scheduled Task only); WSL2 with systemd is the recommended Windows path for full experience

Alternatives Considered:

• Localhost TCP instead of UDS/named pipes — rejected due to port allocation complexity and lack of peer-credential support
• HTTP MCP transport from day one — deferred to a future opt-in omni-dev daemon serve --http mode for multi-machine scenarios; out of scope for v1
• Windows Services — rejected as system-wide and requiring admin elevation; wrong scope for a per-user tool
• Dynamic module loading — rejected for the same reasons ADR-0035 rejected runtime-overlayable ASR backends; compile-time modules are a bounded contract the implementation can honour

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!