docs: daemon foundation design note (IPC, permission routing, local auth)

[mxh1999]

Covers the three items @chauncygu requested in #68 before the foundation PR lands.

Scope is intentionally narrow — service inventory, phasing, persistence, and cost guardrail defaults were settled in the issue thread and are not re-litigated here.

What's in this PR

A single new doc: docs/RFC/0001-daemon-design-note.md (164 lines).

Three sections:

1. IPC — Unix-socket default with optional TCP (--listen tcp://); HTTP/1.1 framing on top; JSON-RPC 2.0 for the data plane (POST /rpc), SSE for events (GET /events); existing /healthz /readyz /metrics unchanged.
2. Permission routing — every PermissionRequest carries an originator; only the originator may answer (other clients see read-only via /events). Fixes the first-answer-wins race called out in [Question] Should /monitor, /agent, bridges survive REPL exit? #68 review.
3. Local auth — explicitly framed as a security boundary, not a multi-user feature. Peer credentials (SO_PEERCRED / LOCAL_PEERCRED) on the Unix socket; bearer token on TCP. TLS out of scope; reverse-proxy recipe documented instead.

A short "Related decisions" section anchors the items already settled in #68 (subprocess-per-agent, bridges in foundation, cost defaults, API RC window) so reviewers know what's not up for debate here.

Open questions flagged in the doc

1. HTTP-on-socket vs raw newline-delimited JSON-RPC.
2. Whether an autonomous agent_runner is its own originator class or whether the configured bridge is the originator for those requests.
3. Audit log default for the Unix socket (off vs always-on).

Happy to discuss inline. Once these are resolved, the foundation PR follows.

Refs #68

[chauncygu]

Hi @mxh1999

This is a solid note overall. The originator-based permission routing in §2 is the strongest part and resolves a real race that the earlier "first-answer-wins" draft would have shipped. Threat model is realistic, defaults are concrete, and the Open Questions section makes the trade-offs reviewable instead of buried.

I'd like a few items in the document itself before we accept it as the foundation PR's contract — most are one- or two-line additions. Comments below.

Must address before accept (1–9): threading model, SSE heartbeat, client_id lifecycle, session.send semantics, macOS peer-cred reality, API versioning, event retention default, audit-log default flip, interactive permission timeout.

Can land as follow-up checklist (10–12): /events filter semantics, binary payload story, metrics-endpoint redaction.

---

Inline comments (anchor each to the listed section)

§1 IPC › Protocol — threading model

Reuses stdlib http.server and http.client. No third-party dependency.

http.server.HTTPServer is single-threaded — one long-lived SSE client blocks every /rpc call behind it. With multiple clients in scope (REPL + Web UI + Telegram + Slack + WeChat + monitor + agent runners), this is a fast path to a hang.

Please specify ThreadingHTTPServer (also stdlib) and a per-client SSE concurrency cap (e.g. ≤ 64) so we have an explicit number to reason about under load. One sentence in §1 is enough.

§1 IPC › Event channel — keep-alive heartbeat

SSE behind NAT or a reverse proxy will be silently closed after idle timeouts (commonly 30–60s) and the client won't know until it tries to reconnect. Please specify a server-side heartbeat: a single SSE comment line (:\n\n) every 15–30s. Trivial to implement, prevents an entire class of "events stopped arriving" bug reports.

§1 IPC › Method namespace — session.send semantics

JSON-RPC is request/response, but agent.run() is a stream. The note doesn't say what session.send returns or where the streamed text/tool events surface.

Please pick one explicitly:

• (A, recommended) session.send returns { "turn_id": "...", "accepted_at": "..." } immediately; all subsequent text chunks, tool starts/ends, permission requests for that turn flow through /events tagged with the turn_id. Keeps /rpc purely synchronous.
• (B) Hold the HTTP response open and write JSON-RPC notifications until the turn ends. Breaks JSON-RPC's single-response semantics; harder to debug.

Pinning this in the note avoids re-litigating it during the foundation PR.

§2 Permission routing › client_id lifecycle

5. Originator disconnects mid-request — the request is held until timeout. On reconnect, the originator gets the request back via SSE replay scoped to its own pending requests…

Two questions the note doesn't answer:

1. Who issues client_id? If the daemon mints a new one on every connection, "REPL crashed and restarted" is a different originator and the held request is lost.
2. Does the client persist its client_id across process restarts?

Suggest: daemon mints client_id on first connection from a given client kind, returns it in the connect response; client persists it at ~/.cheetahclaws/clients/<kind>.id (mode 0600); subsequent connections present the saved id to resume the same originator identity. Worth a short subsection — this is load-bearing for the disconnect-then-reconnect flow you already designed.

§2 Permission routing › interactive timeout default

Defaults: 5 min for unattended mode, unlimited for interactive modes.

"Unlimited" for interactive is unsafe in practice: REPL crashes, user walks away, laptop sleeps — the request sits forever, holding the agent turn open and (for /agent runners) potentially blocking the schedule.

Suggest 30 min default for interactive, configurable per-session, with permission.refresh_timeout RPC if a client wants to extend an active request. Matches what most users will subjectively expect ("if I don't answer in half an hour, just deny it").

§3 Local auth › macOS peer-cred reality check

Daemon checks peer credentials on accept (SO_PEERCRED on Linux, LOCAL_PEERCRED on macOS) and rejects connections from a different UID.

Two practical issues:

1. Python's socket module doesn't expose LOCAL_PEERCRED directly — it needs getsockopt(SOL_LOCAL, LOCAL_PEERCRED) with SOL_LOCAL = 0 and a hand-parsed xucred struct. Real implementation hazard.
2. Older macOS versions have inconsistent behavior on LOCAL_PEERCRED for newly-accepted sockets.

Recommend: on macOS, lean on getpeereid() via ctypes (stable, returns just (uid, gid)), or accept that the 0600 socket + 0700 parent directory is the auth and document peer-cred as Linux-only enhancement. Either is fine; just don't promise LOCAL_PEERCRED and discover the parsing pain in the foundation PR.

§3 Local auth › audit log default for Unix socket

Off by default for the Unix socket (peer-cred-checked, low-noise). On by default for TCP.

Push back: flip Unix socket to on by default.

• Authentication failures on a peer-cred-protected socket are by definition rare; the noise argument is weak.
• The forensics value of "something tried to connect from a different UID" is high — that's exactly the kind of event you want logged, even (especially) when it's rare.
• Cost is one rotated JSONL file with a few lines/day in steady state.

Suggest aligning here.

Note-wide › API versioning

The note doesn't say how clients negotiate protocol version. chauncygu asked for an RC one minor version before the default flip — that requires the protocol to be identifiable as v0 from the foundation PR onward, otherwise we have nothing to RC.

Pick one:

• Cheetahclaws-Api-Version: 0 request header, daemon rejects mismatched majors with 426.
• Method prefix: v0.session.send, v0.permission.answer.

I'd take the header — keeps method names readable. Either way, please bake it into §1 so the foundation PR ships with it instead of retrofitting.

§1 IPC › Event channel — retention default

Replay is bounded by the daemon_events retention window (rolling, default 7 days / 1M rows).

7 days of token chunks + tool events for an active user is a non-trivial SQLite file and a heavy backfill on reconnect. For a local-machine daemon with no multi-host story, the use case is "REPL just disconnected, what did I miss" — that's hours, not days.

Suggest 24h / 100K rows default, configurable. Long-term archival is a separate concern (session_store already handles it).

---

Smaller items / can be follow-ups

§1 IPC › /events?since=<id> — filtering semantics

filtered by the caller's auth — see §2

In a single-user daemon, "filtered by auth" needs a sentence of clarification. Is it:

• per-originator (REPL doesn't see permission events targeted at the Telegram bridge), or
• per-client-kind (Web UI sees everything; bridges only see their own session traffic), or
• per-session (each subscriber names which sessions to follow)?

Pick the model and write one sentence. The current phrasing reads as "auth-filtered" but in single-user there's only one identity, which is what's confusing.

Note-wide › binary payloads

Out of v1 scope, but worth one defensive sentence so we don't paint into a corner: image/audio/file payloads go out-of-band (e.g. future /blobs endpoint with daemon-issued URLs), not inline-base64 over SSE. Keeps the event channel small and avoids buffer-bloat decisions later.

§3 Local auth › metrics-endpoint redaction

--unauthenticated-metrics is the right escape hatch for Prometheus, but please add a one-liner: even with auth on, /metrics and /healthz payloads must never include token fragments, full session IDs, or rationale strings. They're the safest endpoint to leak by misconfiguration; design out the leakage.

---

Once 1–9 are addressed in the doc, this is good. Thanks for the careful write-up.