docs: write down the coordination channel the fleet already runs on
The logstream has carried cross-machine work since 2026-08-18 — patch handoff, review, a v1->v2 supersede — and nothing in this repo said it existed. That gap had a measurable cost this morning: another host addressed a retraction to pi@tor-ms22 by name and it was read only because the human said "read the logstream", while the agent was actively rebuilding the thing it warned about. Split by what each document is authoritative for, so there is one copy of each claim rather than three that drift: - README § Cross-machine agent coordination — what the CONTAINER needs. MEMPALACE_REMOTE_URL selects the shared palace; MEMPALACE_PI_DEVICE is what makes this machine reachable, because where every host is a thin client of one palace the stamped agent name is the only thing that distinguishes them. Stated as a rule with teeth: set both or neither, since a container missing the device var can read the log but is addressable by nobody. - AGENTS.md release checklist step 2 — the vendored-snapshot refresh, as a MECHANISM in the document a releasing agent actually reads, not a comment hoping to be noticed. It says the refresh costs a base rebuild, that skipping it is legitimate (every enrolled host reads its live clone), and that skipping it silently is not. - CHANGELOG — the three-way split itself, plus the measurement that shaped the ack contract: unfiltered, the mailbox returned 5 events, 4 of them finished broadcasts from eight days earlier; with status="open", exactly the 1 that needed an answer. Norms live in the skillset skill (82a8d3c, already live on every host that mounts the skillset — no rebuild) and mechanism in mempalace-toolkit's extensions/pi/README.md (e70bef2, which also documents the edge stamper that 553d8657 shipped undocumented). Deliberately NOT duplicated here. Consequence recorded rather than hidden: the skill edit lands in the skillset, so this repo's SKILLSET_SNAPSHOT_REF now honestly reports itself behind, and --check exits 1 with "has moved to 82a8d3c; the snapshot describes the older c04cd15". That message is also fixed in this commit — it previously blamed "the working tree" even when the tree was clean and only the ref had moved, which is the same defect class as a canary pinned to a phrase the release deleted: a message that names the wrong cause. Now distinguishes moved-HEAD from dirty-tree, verified against both plus the in-sync case.
This commit is contained in:
@@ -187,6 +187,45 @@ the skillset actually is — a maintainer's clone, or any running container.
|
||||
`pi-devbox-version` degrades quietly on such an image: no fingerprint, no
|
||||
annotation, verified against the real v1.8.7 manifest.
|
||||
|
||||
### Documented
|
||||
|
||||
- **The fleet's cross-machine coordination, which was working and unwritten.**
|
||||
The RFC 003 logstream has carried real work between hosts since 2026-08-18 —
|
||||
patch handoff, design review, a v1→v2 supersede — and no document in this repo
|
||||
or the toolkit said so. Written up in three places, split by what each is
|
||||
authoritative for:
|
||||
- `README.md` § *Cross-machine agent coordination* — what the **container**
|
||||
needs: `MEMPALACE_REMOTE_URL` selects the shared palace, and
|
||||
`MEMPALACE_PI_DEVICE` is what makes this machine *reachable* on the log,
|
||||
because when every host is a thin client of one palace the stamped agent name
|
||||
is the only thing distinguishing them. Set both or neither: a container
|
||||
without the device var can read the log but is addressable by nobody.
|
||||
- the skillset's `mempalace` skill (`82a8d3c`, live on every host that mounts
|
||||
the skillset, no rebuild needed) — the **norms**: a mailbox query at wake-up,
|
||||
and the sender-declared ack contract, where a *directed* event with
|
||||
`status="open"` is owed a reply and a `*` broadcast owes nothing. Measured
|
||||
while designing it: an unfiltered mailbox returned 5 events, 4 of them
|
||||
finished broadcasts from eight days earlier, where `status="open"` returned
|
||||
exactly the 1 that needed an answer — an unfiltered mailbox trains you to
|
||||
ignore it, so the filter is the feature.
|
||||
- mempalace-toolkit `extensions/pi/README.md` (`e70bef2`) — the **mechanism**,
|
||||
including that the bridge is *write-only* today (it stamps events going out
|
||||
and never reads the log, so nothing in this image polls on the agent's
|
||||
behalf), and that live SSE push is a palace-deployment question: the server
|
||||
implements `GET /logstream/stream`, but a reverse proxy exposing only `/mcp`
|
||||
makes it unreachable — verified by 404s against the real endpoint.
|
||||
|
||||
⚠️ **This makes the vendored snapshot stale on purpose.** The skill edit is in
|
||||
the skillset (`82a8d3c`), so `SKILLSET_SNAPSHOT_REF` still records `c04cd15`
|
||||
and `scripts/vendor-mempalace-skill.sh --check` now exits 1 with
|
||||
*"has moved to 82a8d3c; the snapshot describes the older c04cd15"*. Refreshing
|
||||
it is a deliberate release-day decision, not an oversight — hence the new
|
||||
step 2 in `AGENTS.md` § *Release-day checklist*, which states both that the
|
||||
refresh costs a base rebuild and that skipping it is legitimate because every
|
||||
enrolled host reads its live clone. What is not legitimate is skipping it
|
||||
*silently*, which is precisely what the new manifest fields and
|
||||
`pi-devbox-version` output make impossible.
|
||||
|
||||
---
|
||||
|
||||
## v1.8.7 — 2026-08-25
|
||||
|
||||
Reference in New Issue
Block a user