#168: revise chapter 13 — the second herdr daemon, and the ticket TTL
- Renamed the product to fleet / fleetd. The invariant on line 63 was right; only
the name was wrong.
- §2 described one herdr socket. It now covers the optional `memberHerdrSocket:`
key and says why it exists: herdr forks every pane as its own OS user, so
running members as a different user needs a second herdr owned by that user.
It is read once at startup (FleetConfig.java:34-37,84; Fleetd.java:148-158).
- §4 now says what /healthz reports with two daemons: the body gains a `member`
key, and `protocolMismatch: true` when the protocol numbers differ
(FleetApp.java:256-264). The `herdr` key keeps the LEAD's values on purpose,
because redeploy-fleetd.sh and rename-checkout.sh read it. An operator who
reads the wrong key gets the wrong answer.
- Trap 5 was stale. The ticket TTL is now counted from when the turn FINISHES,
not from when it was sent (#197). Under the old behaviour any task longer than
the TTL lost its report on arrival. The trap now states both, and says to check
the running jar, since a daemon started before that fix still has the old rule.
All twelve traps in §6 are kept. Both diagrams rendered with mmdc.
Match the code cutover: daemon name, config (fleetd.yaml), scripts, launchd/
systemd units, module dir, and MCP tool prefix bridge_* -> fleet_*. Kept:
the BRIDGED_MEMBER security marker, mcp__bridge__ (historical mount name), and
the .bridged-worktrees on-disk path. The portable CLAUDE.md block stays
byte-identical with the repo's CLAUDE.md.
Two members audited Home.md + 4-Setup.md and 5-Operations.md against the
code. Three findings changed what Home.md says.
1. The AgentAPI fallback does not exist. The page said it was "retained as a
swappable fallback injector"; `grep -ri agentapi bridged/src/main` returns
nothing, and the only injection path in shipped code is the herdr one. It
is a discarded option, not something you can switch to, and reading it as
a fallback would send an operator looking for a lever that was never
built.
2. "One `claude mcp add` line for both sides" is claude-code framing only.
An opencode member mounts through a generated opencode.json and gets no
ANTHROPIC_* variables at all (OpenCodeLauncher). Also added what the
broker actually is - optional, and LavinMQ over AMQP when on, not the
Redis Streams / NATS the design era assumed.
3. The subscription boundary now has a deliberate exception. A profile with
`subscription: true` runs its members on the operator's own plan on
purpose, and an opencode member sits outside the boundary entirely on its
own provider credential. The old absolute wording hid the one setting in
the system that spends money.
Also corrected the reply paragraph: the blocking bridge_send is capped by the
lead's own MCP client timeout at about 60 seconds, so real work uses
wait:false and a ticket. The page described only the blocking path.
docs: add chapter 13, the operator user guide, for release 1.1
The wiki had twelve chapters and none of them told an operator how to run
the thing. Chapters 1-3 explain why the design is what it is, 9-12 explain
how the code is put together, 11 lists capabilities. The two pages that were
meant to cover bring-up and day-2 - 4-Setup and 5-Operations - were never
written past their scope note, and every technical detail in them had gone
wrong: a decommissioned model host, port 8080, herdr protocol 14, a systemd
unit that does not exist, Redis Streams and NATS that were never built,
"no per-session authz yet" after Authz shipped, and recycle() events that
have no code behind them.
So this adds 13-User-Guide.md, written against the running system on
2026-08-17, and points the two stubs at it rather than leaving wrong claims
in place.
The guide covers:
1. what this is and, more usefully, the five things it is NOT, each with
the reason it is not that;
2. install - herdr (check the PROTOCOL number, not the version), the
daemon, the login-shell rule for secrets.sh, and the lead's tab label;
3. configure - the four knobs that cost money, the live profile table with
who pays for each, the gateway paths, and memberCredentials' two halves;
4. run - the redeploy script, and the four checks that go beyond /healthz,
because health is green while every spawn fails;
5. delegate - the eleven tools, the spawn-all-then-send-all rule, the ~60s
client cap on a blocking send, and the authz table;
6. when it breaks - twelve traps hit for real this year, grouped by
bring-up, losing a member's work, and merging a member's work;
7. where to look next.
Home.md is corrected too: it claimed members launch against ollama.ltms.dev,
a host that no longer exists (the gateway is llm.ltms.dev), it framed the
system as Claude-only with one worker, it listed 8 of the 13 pages, and its
status still said "Design".
Dai Ha