Every file:line citation in docs/remote-agents.md was labeled against
`c1bca1b56` or `b4f4ed1a6`, neither of which is an ancestor of main
(merge-base with 28ae6cd21 is af4b7087d). Readers could not resolve them.
Rather than assume offsets, each cited line's content was extracted at the
old pin and located in the merged tree. 44 of 49 already resolved
byte-exactly at 28ae6cd21 — they had been verified against the PR base, not
the labeled pin, so the caveat paragraph had the accuracy backwards.
Three drifted as pure offsets, corrected here:
discovery.rs:74-193 -> 75-207 KNOWN_ACP_RUNTIMES; all four cited
metadata fields occur only in this range
runtime.rs:1006 -> 1001 spawn_agent_child(.., false, ..); the
eager/lazy contrast with restore.rs:333
(true) still holds
types.rs:809 -> 814 DEFAULT_AGENT_PARALLELISM, still 10, so
the ~87s / ~197s arithmetic is unchanged
One drift was not an offset but a factual error. PRESENCE_TTL_SECS is 180,
not 90: bf139e8d0 (#3783, Jul 30 15:26) raised it to preserve a
three-heartbeat window after the desktop heartbeat moved to 60s, landing
after this spec's base (Jul 30 12:30) but before it merged. The spec merged
onto a main that had already invalidated the number. Pinned by test at
presence.rs:114-115.
90s was load-bearing in three places, all understating the real bound by 2x
(I3 at :206, the BUZZ_ACP_NO_PRESENCE argument at :216, the same argument
for I5 at :928), and the spec quotes the vision's "ninety seconds" prose
inline. Corrected in both documents. I3's promise is that the staleness
window is bounded, never indefinite; the width was inherited from a
relay-wide constant that moved for unrelated perf reasons, and the binding's
grace period targets the avoidable half either way.
Each Known Defect claim was re-verified live at 28ae6cd21 rather than
relabeled — a re-pin carrying a stale assertion forward is worse than the
offset it fixes. All eight still hold: KD1 bare strip_prefix at
backend.rs:467, KD3 deploy_payload_json emits 15 flat fields with no launch
block, KD4 BUZZ_ACP_EXIT_AFTER_INACTIVITY has zero occurrences, KD5
provider_deploy invokes deploy with no preceding info, KD8's empty-string
arm in coerceConfigValues.
Docs-only. No behavior change.
Co-authored-by: Tyler <109685178+tlongwell-block@users.noreply.github.com>
Signed-off-by: Tyler <109685178+tlongwell-block@users.noreply.github.com>
## What
A formal specification for remote agents and their management —
`docs/remote-agents.md` — in the style of
`docs/git-on-object-storage.md`: stated system model, named invariants,
explicit trust boundaries, provider conformance checklist, and an
implementation-correspondence table.
Requested by Tyler in the buzz-remote-agents design thread; co-designed
with Dawn and Wren (review pending).
## Structure
- **System model** — five principals (Desktop / Provider / Substrate /
Agent / Relay) and the design axiom **M1: no management channel** —
everything the desktop knows about a live remote agent flows through the
relay.
- **Five invariants** with enforcement mechanism and stated boundary:
- I1 identity fail-closed, I2 no secrets in configuration, I3
presence-is-status, I4 at-most-one-live-instance, I5 bounded lifetime.
- **Provider protocol** — discovery, `info`/`deploy` wire contract,
untrusted-output rules, the reserved-key rule, and the **deploy state
machine** (Running → no-op).
- **Auto-stop** — `--exit-after-inactivity` /
`BUZZ_ACP_EXIT_AFTER_INACTIVITY`, default off, definition of "inactive",
and why it must not share a name with the three existing timeout
concepts.
- **The Kubernetes binding** — `buzz-backend-kubernetes`:
kubeconfig-only auth, random-default namespace via schema `default`, the
sprig image, pod shape (bare Pod, `terminationGracePeriodSeconds: 60`,
32-hex label / full-pubkey annotation), secrets, GC, config budget.
- **Known defects** at `c1bca1b56` (Windows `.exe` id pollution;
provider env inheritance vs kubeconfig exec plugins).
- **Open decisions A–E** marked inline and consolidated, awaiting owner
ruling.
## Notes for review
Docs-only. Every code claim was verified against the tree
(correspondence table maps each spec concept to its file/function). The
spec deliberately documents two desktop bugs as Known Defects rather
than fixing them here — fixes are follow-up PRs.
---------
Signed-off-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
Co-authored-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
