ADR-0001: Threads + channels for the recorder (not tokio)
- Status: Accepted
- Date: 2026-07-04
- Deciders: Halfhand engineering
- Requirements context: the crate & dependency plan lists
tokio (or threads + channels — implementer's choice, justify in ADR)forhh-record.
Context
hh-record must concurrently drive three independent I/O sources during a
recording:
- a PTY (read agent stdout, forward stdin, handle resize/signals),
- a recursive filesystem watcher (
notify) for file changes, - (optionally) a stdio MCP proxy forwarding JSON-RPC both ways,
- and feed all of them into the single-writer SQLite task.
We need to choose a concurrency model for the recorder crate. The two realistic options are:
- A.
tokio— an async runtime; each source becomes anasynctask multiplexed on a thread pool, withtokio::sync::mpscfeeding the writer. - B. OS threads +
std::sync::mpsc— one thread per source, plus the writer thread, communicating through standard channels.
Decision
We choose B: OS threads + std::sync::mpsc for v0.1.
Justification
- Concurrency shape is small and fixed. A recording has a bounded, known set of long-lived workers (PTY reader, PTY writer, FS watcher, MCP proxy sides, SQLite writer). There is no fan-out to thousands of tasks. The cost/benefit of an async runtime does not pay off here: we would be paying the runtime's complexity to multiplex a handful of blocking I/O streams.
- All real I/O here is blocking.
portable-ptyis a blocking PTY API;notifydelivers events through a blocking channel; SQLite writes are blocking. Wrapping blocking I/O inspawn_blockingdefeats the purpose of async and adds thread-pool juggling. Direct threads match the I/O model exactly. - The single-writer rule maps directly to a thread + channel. CLAUDE.md
mandates "single-writer for SQLite (one writer task fed by an mpsc channel)
… Never share a
Connectionacross threads." That is literally one thread draining onestd::sync::mpsc::Receiver. Introducingtokiowould require a runtime, atokio::sync::mpsc, andspawning the writer — more moving parts for the same guarantee, and a runtime handle that must be threaded across the FFI/PTY boundary. - Smaller, more auditable binary — relevant to the no-network rule. No async runtime
means fewer transitive crates and a smaller attack surface for a tool whose
core promise is "never talks to the network."
tokiopulls a large dependency graph with features (time, net, process, fs) we do not need. - MCP proxy latency (< 5 ms p50 target) is fine with threads. Two threads (one per stdio direction) forwarding bytes add negligible overhead; there is no scheduler poll, no task wakeup latency.
- Cancellation is straightforward. Agent exit or SIGTERM tears down the recorder by joining the workers; no runtime to shut down, no task abort machinery.
Consequences
- The recorder will use
std::thread+std::sync::mpsc(orcrossbeamchannels if a multi-producer detail calls for it).signal-hookfor SIGTERM/SIGINT. - We forgo structured concurrency primitives (
tokio::select!, cancellation tokens). We will emulate what we need with channel close +JoinHandle, which is adequate for this fixed topology. - Reversibility: if v0.2+ adds many concurrent MCP servers, streaming
adapters, or a network-facing feature (none currently in scope —
cloud/network features are excluded), we would revisit this and likely adopt
tokioat that boundary only, keepinghh-coreruntime-free.
Requirements deviation flagged
The requirements leave this open ("implementer's choice"). This ADR is the required justification. No requirement is violated by either choice.