# 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.98, edition 2024; `roncho` 1.0.0 (`default-features = false, features =
["tls"]`, which brings `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

The gate count is `make gate`'s tests after the task. Mutations are one-line breaks of the
reference, each run against the task's given tests (checklist, T28); those not caught cannot change
behaviour, or are checked by the task's own greps instead, as the task says.

| # | Delivers | Crates | Gate | Mutations |
|---|---|---|---|---|
| 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 | 1130 | |
| 02 | `loopd` logs the speaker on the `User` record and sends the turn number in `SessionUpdated` | loopd | 1138 | |
| 03 | `gatewayd` sets the speaker: the Mattermost username when every post of the burst is from one person, else none | gatewayd | 1148 | |
| 04 | `bxctl chat --speaker NAME`, opt-in, no default | bxctl | 1158 | |
| 05 | `brokerd` serves `run/memory-broker/state.sock` from its state store; `brokerd-listener-lost` and `socket-forbidden` name it | brokerd | 1171 | |
| 06 | `memoryd`'s `[honcho]` section and its keys, checked at start; runbook `honcho-config-invalid` | memoryd | 1188 | |
| 07 | The ledger, `memory/honcho.jsonl`: its records, append, read-through, and the outbox; runbook `honcho-ledger-damaged` | memoryd | 1212 | 45: 41 caught; 3 (no sync, two writes) checked by the task's greps; 1 cannot change behaviour |
| 08 | The decision for a turn (a pure function: state, labels, speaker, text) | memoryd | 1230 | 36: all caught |
| 09 | On `SessionUpdated`, after `loopd` has its answer: ask `brokerd`, read the log, decide, record; undecided turns retried at the next report of any session; the ledger read through at start; runbook `broker-state-unavailable` | memoryd | 1257 | 42: all caught |
| 10 | `roncho` clients per workspace, and making sure of workspaces, peers and sessions (the agent unobserved, the fleet with reasoning, summaries and dreaming off, the `-2` sessions); the fake Honcho server | memoryd | 1278 | 44: 43 caught, 1 cannot change behaviour |
| 11 | The worker for turns: messages in parts of 25,000, neutralised, one batch; backoff; outage logged once; refused sends and keys; runbooks `honcho-unreachable`, `honcho-send-refused`, `honcho-key-refused` | memoryd | 1300 | 36: 35 caught, 1 cannot change behaviour |
| 12 | Memory writes decided as they are journalled, by spec 4's table (conclusions, their deletion, fleet messages, undo); the ledger's own lock | memoryd | 1314 | 21: 17 caught, 4 cannot change behaviour |
| 13 | The worker for memory writes: conclusions made in `<id>_memory` and deleted, fleet messages | memoryd | 1324 | 23: all caught |
| 14 | `bxctl memory sync`: the ledger's counts and its failed items | memoryd, bxctl, bxcore | 1332 | 14: all caught |
| 15 | Sync begins when Honcho is turned on (`began`, and a skip for older turns); conclusions matched by peer | memoryd | 1345 | 15: all caught |

A later task that changes a given file gives the earlier task its own copy, `<name>-taskNN` (T19),
and that task's copy command names it.

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

## The owner's answers (2026-09-27)

1. **`bxctl chat`'s speaker is opt-in: `--speaker NAME`, with no default.** Console turns are
   mostly tests, and Honcho can neither forget them nor be shared without them; a `bxctl chat` turn
   without the flag has no speaker and is not synced (spec 4). Task 04.
2. **Saved Honcho responses** for the fake server: the design model records real responses from
   rift in task 00, in a throwaway workspace, `boxmaker-plan-probe`, that it creates and deletes.
   It touches no other workspace on rift, in any way (not even a read): rift has no keys yet, so
   the rule is ours to keep.

## The owner's decisions (2026-09-28)

1. **Sync starts when Honcho is turned on.** The ledger's first line records when sync began, and
   a turn from before it is skipped: turning on `[honcho]` never sends earlier conversations. Task
   15. The first report of a session that ran before then decides a skip for each of its earlier
   turns; `bxctl memory sync` counts them.
2. **Conclusions go to `<id>_memory`**, the Boxmaker session's own Honcho session, holding the
   agent's and the owner's peers, made on first use whether or not a turn of the session is
   synced. An undo's conclusions carry the undone edit's session. Tasks 12, 13.
3. **No retraction.** A note cannot be undone (notes are append-only), so nothing is retracted,
   and the row went from spec section 4. `Action::Retract` stays in the ledger's schema, unused;
   the worker leaves one waiting. Tasks 12, 13.
4. **Sends are at least once.** The worker records `sent` after Honcho answers: a crash between the
   two, or an owner removing a `sent` line, sends the item again (Honcho cannot delete a message).
   Tasks 07, 11.

## Changes to the outline

- The runbook entry `broker-state-unavailable` moved from task 05, which did not add it, to task
  09, which adds the pointer (the rule: the entry comes with the task that writes its pointer).
- Task 12 decides only; task 13 sends. Task 15 was added for the owner's decision 1 and for the
  matching of conclusions by peer found while writing task 13.

## Known issue

`gatewayd`'s `gateway_sock` test `brokerd_closing_first_ends_it_as_no_longer_pending` fails now and
then on a loaded machine (2 of 10 runs without any M5c-1 change, at a load average near 10, on
talos): after `Ended` arrives, the handler can still hold the answer's receiver for a moment. It is
a timing race in the test, not in `memoryd`. Tasks 13 to 15 tell the implementer: if it is the one
test that fails, run the gate once more. To be fixed after M5c-1.

## 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

```sh
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.)