# Daemon Integration Round 12 Plan

## Summary

Round 12 should integrate the new daemon boundary into existing clients without making it mandatory.

The work is sequenced in this order:

1. add optional daemon-backed read paths to CLI and/or MCP
2. keep direct fallback paths intact
3. verify parity when daemon is present and graceful fallback when it is absent

## Key Changes

### Client integration

- add an optional daemon address or mode flag
- route a narrow set of read-only operations through the daemon first
- keep writes direct for now unless the daemon path stays very simple
- current implementation reuses a shared daemon stdio session keyed by `(daemon_bin, config_path)` for repeated reads inside one process
- if that shared session dies, the next request rebuilds it once before falling back
- CLI and MCP preserve direct fallback paths when daemon-backed reads fail or the daemon binary is unavailable

### Protocol robustness

- MCP stdio now returns JSON-RPC parse errors with code `-32700` for malformed JSON and continues serving later requests
- lifecycle daemon stdio now returns structured `{ ok: false, error: ... }` responses for malformed JSON and continues serving later requests

## Test Plan

- daemon-present parity tests
- daemon-absent fallback tests
- no-regression checks for direct mode
- malformed JSON recovery checks on both MCP and daemon stdio loops

## Assumptions

- Round 12 does not make the daemon mandatory
- Round 12 does not move writes into the daemon by default
- Round 12 keeps protocol changes minimal

## Completion Status

Last checked: `2026-04-13`

Completed in this round:

- added optional daemon-backed lifecycle reads for MCP via `--daemon-bin`
- preserved direct-read fallback when the daemon binary is unavailable or daemon reads fail
- verified parity for daemon-present and daemon-absent MCP read flows with smoke coverage
- current daemon client integration reuses a shared stdio daemon session keyed by `(daemon_bin, config_path)` across repeated reads inside one process
- if that shared session dies, the next request drops the stale session, rebuilds it once, and then continues; direct fallback remains intact when daemon transport still fails after rebuild
- malformed JSON handling is now hardened across both stdio boundaries involved in daemon-backed MCP reads:
  - MCP returns JSON-RPC parse errors and continues serving later requests
  - daemon returns structured `ok: false` errors and continues serving later requests
- verification completed with targeted MCP/daemon smoke coverage and final full-suite green runs

Checked for omissions against this plan:

- daemon use remains optional
- writes remain outside the daemon path by default
- protocol changes stayed narrow and compatibility-focused
