boxmaker/docs/plans/M5c1/README.md

M5c-1 implementation plan: Honcho, the write path

For the implementer: each task file is one closed task for one fresh session. Read AGENTS.md, then the task file, and do exactly that task. The driver is tools/run-plan.sh.

Goal: finished turns and memory writes reach Honcho: turns to the agent's trusted or untrusted workspace by the session's state at the turn's end (never a secret session's), trusted memory writes mirrored as conclusions at once, untrusted notes to the fleet workspace as messages, all through an append-only ledger that is also the outbox.

Architecture: bxcore gains the speaker on a turn, the turn number on SessionUpdated, and a session-state question; loopd, gatewayd and bxctl chat carry the speaker; brokerd answers the question on a new socket; memoryd gains a honcho module (configuration, ledger, decision, roncho clients, a sync worker, mirrored memory writes) and bxctl memory sync shows its state.

Tech stack: Rust 1.95, edition 2024; roncho 1.0.0 (default-features = false, features = ["blocking"]), added by the design model in task 00; no other new crate.

Spec: docs/specs/2026-09-27-m5c-honcho.md (approved 2026-09-27), sections 3 to 7 and 10 to 13. The read path (recall over the fleet, ask_memory) is M5c-2, a later plan.

Global constraints

• Roles depend on bxcore only; memoryd also on roncho (task 00). No unsafe, no async runtime.
• Every roncho client is built with .without_config_file() (spec 6).
• Nothing is logged that holds memory text or a key: roncho errors are logged by kind and status only (spec 6).
• Nothing above private is written, and never a secret session's turn (spec 3).
• No file the implementer reads holds a chat-template tag whole (T33); no fake key whole.
• Every path a given test creates is removed by a guard (T44); every process a test starts has a deadline.
• Every fail-closed state has a runbook entry, added by the task that adds its pointer (T49's lesson from M5b: the gate needs the entry with the pointer).
• Commit trailer from the driver; gate with a 600000 ms timeout.

Tasks (outline, for the owner's review)

#	Delivers	Crates
00	(the design model, before the run) roncho added: workspace dependency, docs/dependencies.md, docs/egress.md (rift), cargo deny, the Nix build on straylight; saved Honcho responses for the fake server (below)	all
01	Wire: Turn.speaker, LogRecord::User.speaker (optional, absent in old logs), SessionUpdated.turn, SessionState → SessionStateReply; fixtures	bxcore
02	loopd logs the speaker on the User record and sends the turn number in SessionUpdated	loopd
03	gatewayd sets the speaker: the Mattermost username when every post of the burst is from one person, else none	gatewayd
04	bxctl chat --speaker NAME	bxctl
05	brokerd serves run/memory-broker/state.sock from its state store; runbook broker-state-unavailable	brokerd
06	memoryd's [honcho] section and its keys, checked at start; runbook honcho-config-invalid	memoryd
07	The ledger, memory/honcho.jsonl: its records, append, read-through, and the outbox	memoryd
08	The decision for a turn (a pure function: state, labels, speaker, text)	memoryd
09	On SessionUpdated: ask brokerd, read the labels, decide, record; undecided turns retried	memoryd
10	roncho clients per workspace, and creating workspaces, peers and sessions (names, the agent unobserved, the fleet with reasoning, summaries and dreaming off, the -2 sessions); the fake Honcho server	memoryd
11	The sync worker for turns: messages in parts of 25,000, neutralised; backoff; outage logged once; refused sends and keys; runbooks honcho-unreachable, honcho-send-refused, honcho-key-refused	memoryd
12	Memory writes mirrored: each journalled edit decided by spec 4's table (conclusions, fleet messages, retractions, undo)	memoryd
13	The sync worker for memory writes: conclusions created and deleted, fleet messages	memoryd
14	bxctl memory sync: decided, sent, waiting, failed	memoryd, bxctl

After task 14, the design model runs the M5c-1 device check (spec 13) on straylight, rift and the owner's Mattermost.

Two points for the owner

1. bxctl chat's speaker is a flag, --speaker NAME. The spec says "from its configuration", but bxctl has none; without the flag a bxctl chat turn has no speaker and is not synced, which is the spec's rule for an unknown speaker.
2. Saved Honcho responses. The fake server in the tests answers from fixtures. Written from the OpenAPI document alone they could be wrong in the ways the roncho review found (the evidence fields). The design model would record real responses from rift in task 00, in a throwaway workspace (boxmaker-plan-probe) that it deletes afterwards: creating a workspace, peers, a session, messages and conclusions, and deleting a conclusion. This writes to your Honcho; nothing else on rift is touched.

Before hand-over

Every task is worked through docs/plans/CHECKLIST.md with a reference in a scratch worktree with its own build directory, replayed from its task text; mutations; /tmp compared around a gate run; scratch files in the worktree's .state/; the reference moved to straylight as a bundle before the run. Task files name their log row (T47); a scanner-like function gets a golden file (T46); a request through another role is counted against its limits (T49).

Running it

git switch -c m5c1 master
OPENCODE_MODEL=straylight/ornith-1.5-35b-a3b RESUME=1 \
  SLOTS_URL='http://straylight:11434/slots?model=ornith-1.5-35b-a3b' \
  tools/run-plan.sh docs/plans/M5c1 01

(Or titan's Ornith, titan/… and http://127.0.0.1:8081/…, once its GPU is free.)