**Bead** `4c6470f9-b74a-4aba-b436-5e998f469cce` · [canonical URI](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/) · discussion: Talk: Orchestrator This page is the wiki facet of a [bead](https://redfish.acequia.io/guerin/.agents/); the bead is the source of truth.
> The **mayordomo of the bead commons**: a coordination agent that watches the `.agents/` tree, keeps each bead's interface files current against the latest bead protocol, preserves backward compatibility through interface-version duck-typing, brokers smart sync + leader election across the acequia endpoints that host beads, and dispatches OS-node subagents that bridge service-worker caches to their real CORS origins.
## Identity - **name:** `bead-orchestrator` - **URI:** https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/ - **Local origin:** `sites/redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/` - **GUID:** `4c6470f9-b74a-4aba-b436-5e998f469cce` - **Slug:** `bead-orchestrator` (working name, pending Stephen) - **Opened:** 2026-06-14 - **Parciante:** Stephen Guerin (guerin) - **Parent (dominus):** `https://redfish.acequia.io/guerin/` (workspace-level concern; not hatched from a single sibling bead) - **Currently animated by:** Claude (CE — Claude Code extension, bead scribe with filesystem/WebDAV write authority)
## Motivation (Why a GUID) Stephen opened this bead with: *"start-bead bead-orchestrator which will be in charge of monitoring beads, making sure the evolving architecture of beads is updated in the beads. eg are there skills and agent.md and agent.json updating to the latest protocol interfaces. we might need to considering having duck-typing to different versions where apps were written against a given bead interface. the orchestrator may also have smart syncing across the different acequia-endpoints hosting the beads and making sure leader election is working. The bead-orchestrator may also have subagents on os nodes (windows, mac, linux, android and iphones) that help cross-origin caches filled by service workers on one domain get to the actual CORS origin. mount relevant beads in this chat."* The bead protocol (`.agents/beads.md`) has been **evolving fast** — `agent.md`, `agent.json`, `keywords.json`, `names.json`, `README.md`, `bead-bind-startup.md` were all ratified or sharpened within the last week, and the handler / cognition-ladder layer is still being designed. Beads minted before a given ratification drift out of conformance; apps bound against an older interface can break. Nothing yet **tends the commons as a whole**: no agent walks the tree, reports staleness, migrates interfaces, or coordinates the several origins now serving beads. This bead is that custodian — a mayordomo, in the acequia sense: it shapes the demand ring and keeps the ditch flowing, it does not own the water.
## Mechanism (What this bead does) Holds the **charter + design** for the coordination duties (four in the [charter](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-14/notes/00-orchestrator-charter.md); Duty 5 in [note 02](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-18/notes/02-master-scheduler-world-ask.md); Duty 6 in [note 03](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-20/notes/03-links-as-first-class-primitives.md)): 1. **Conformance monitoring** — walk `.agents/`; for each bead validate the presence/shape of the canonical root files against the current protocol; emit a conformance report (offered, never force-written into other beads). 2. **Interface-version duck-typing** — introduce an explicit `protocolVersion` on the agent-face, plus an adapter layer so a caller bound to an older bead interface still resolves. Old beads are *adapted at interaction time*, not rewritten under them. 3. **Smart multi-endpoint sync + leader election** — coordinate `/bead-sync` across the acequia endpoints (home node, cloud host, shared host) with conflict resolution and a lease/leader-election so exactly one animator holds a path at a time. 4. **OS-node cache→CORS bridge** — dispatch subagents on parciante nodes (windows / mac / linux / android / iphone) that help a cross-origin cache filled by a service worker on one domain reach the actual CORS origin. 5. **Master scheduler** (added 2026-06-18) — be the **World**: `world.ask(beads, b => b.step())`. Drive every schedulable bead's own `step` on its cadence; the bead acts on itself (the orchestrator never mutates its tree). Duties 1-4 become the orchestrator's own scheduled job — it schedules itself, World and turtle both. Executable face: [`agent.mjs`](agent.mjs); design: [02-master-scheduler-world-ask.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-18/notes/02-master-scheduler-world-ask.md). 6. **Link harvesting + maintenance** (added 2026-06-20) — run a background index (reuse orama-bead `6f5044df`) that scans chats/notes for bead-id references and keeps **links** fresh; and open the **link-as-first-class-primitive** slice (a link is a resource with its own URI, `end1`/`end2` just URIs, living anywhere — `collaborative-beads` `48a76785`'s membrane is the first real instance). Offer-only: materializes link resources in link-space, offers backlink envelopes into docks, never edits a target's tree. Design: [03-links-as-first-class-primitives.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-20/notes/03-links-as-first-class-primitives.md). This is a **design + coordination bead**. It describes and *offers*; it does not reify infrastructure it does not own (no force-writes into third-party bead trees; reports land in this bead and in the target bead's `uploads/` dock).
## Folder Layout ``` 4c6470f9-b74a-4aba-b436-5e998f469cce/ ├── about.md # this file — descriptive self ├── README.md # front-door sidecar ├── agent.md # operative self ├── agent.json # machine twin (protocolVersion + the `orchestrator` + `scheduler` blocks) ├── agent.mjs # ★ execute-face: the master-scheduler lifecycle (startup/setup/step/die) + world.ask ├── names.json # local namespace — the mounted beads ├── keywords.json # index surface ├── bead-bind-startup.md # resume contract — read first when binding this bead ├── uploads/ # inbound dock └── 2026-06-14/ ├── notes/ │ └── 00-orchestrator-charter.md # ★ the core charter: four duties, mechanism sketches, open questions ├── chats/ │ └── 2026-06-14-bead-orchestrator-birth.md # verbatim session log ├── skills/ # (future) conformance-scan / migrate / sync-elect skills └── artifacts/ # (future) reference scan output, adapter prototypes └── 2026-06-16/ └── notes/ └── 01-agent-step-and-determinism.md # ★ the tick: how step works + why it collapses to a rung-0 .mjs └── 2026-06-18/ ├── notes/ │ └── 02-master-scheduler-world-ask.md # ★ Duty 5: the World's ask over the bead population └── chats/ └── 2026-06-18-master-scheduler-bind.md └── 2026-06-20/ └── notes/ ├── 03-links-as-first-class-primitives.md # ★ Duty 6: links as first-class (own URI, end1/end2) + realization spectrum (dock⇄WS⇄WebRTC) + orama harvest ├── 04-response-dock-the-return-lane.md # protocol proposal: response/ as the dock's return lane (pairs request/; the efferent half of a thread) └── 05-addressing-scope-local-vs-fully-qualified.md # bead-id addressing: bare/local (same-origin, OS disk) vs fully-qualified URI; persist canonical, resolve contextual ```
## Session Log - **2026-06-14** — Bead opened (`start-bead`, CE for Stephen). Surveyed `.agents/beads.md`, the `agent.md`/`agent.json` prototype lineage (5595c7f1, d9dfa5e4), the handler/cognition-ladder design (fe7fbaf5), the home-hosting + leader-election runbook (7049c694), and the live router-bead (82bd6fa4). Confirmed no prior orchestrator/monitor/registry bead exists — this is greenfield. Scaffolded the agent-face, mounted the relevant beads in `names.json`, and drafted the charter note with four duties + open questions for Stephen to bind. - **2026-06-20** — Ran the orchestrator's own **`step`** (`node agent.mjs`, dry-run over the live commons): census **116 beads, 4 schedulable** (`4c6470f9` self, `72efa91c`, `d4b881f0`, `d718e68a`); `world.ask` would step all four; no side effects. Growth signal vs note 02 (was 103/2). The orchestrator scheduled **itself** (first in the asked list) — World and turtle both, as designed. - **2026-06-20** — Addressing scope: wrote [05-addressing-scope-local-vs-fully-qualified.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-20/notes/05-addressing-scope-local-vs-fully-qualified.md) — a bead-id is location-free; addressing spans bare-GUID (local, same-origin/OS-disk) → origin-relative → fully-qualified URI, resolved by a mount-table + resolution-order. Rule: **persist canonical, resolve contextual**. Two orthogonal scopings (request-id = who asks; target = what/where). Touches Duty 4 (local resolution avoids the CORS bridge), Duty 6 (per-caller relative links), Duty 1 (durable refs must resolve anywhere). Per Stephen. - **2026-06-20** — Link **realization spectrum** added to note 03 §2.1: a link's transport spans the liveness ladder — request/response dock (cold) ⇄ WebSocket (warm) ⇄ WebRTC (hot, peer-to-peer, no origin); soft/renegotiable (upgrade for interactive/streaming, demote to dock on disconnect; thread persists). Added `transport`/`liveness` to the `agent.json` links shape. Per Stephen's *"a link can also become a websocket or webrtc connection. but also the request/response structure."* - **2026-06-20** — Protocol proposal: wrote [04-response-dock-the-return-lane.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-20/notes/04-response-dock-the-return-lane.md) — a `response/` return lane completing the async dock corridor (`uploads/`/`request/` afferent ⊕ `response/` efferent). My read: needed, but earns its place specifically for **dock-less callers** (browser/CB that can only poll) and inbox hygiene, *not* mere symmetry (a caller with a dock can already get answers reflected into its `uploads/`). Must be request-id-correlated, ephemeral (TTL/apoptosis, unlike provenance `uploads/`), and is the efferent half of a thread riding a link (note 03). Mounted bead-remote `792ebed9` (owns `request/`); to be co-ratified with it + handler `fe7fbaf5`. 7 open Qs. Per Stephen's *"beads should have a /response directory too."* - **2026-06-20** — Added **Duty 6 (link harvesting + the link primitive)**: wrote [03-links-as-first-class-primitives.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-20/notes/03-links-as-first-class-primitives.md), opening the **Links slice** that note 02 §8 deferred. A **link** becomes a first-class resource with its own URI (`resourcetype: <link/>`), `end1`/`end2` are just URIs, it lives anywhere and yields free backlinks. A background harvest (reuse orama-bead `6f5044df`, which already indexes the commons + `.claude` chats) scans for bead-id citations and keeps links fresh; offer-only. `collaborative-beads` `48a76785`'s membrane is recognized as the first real `<link/>` (end1=Hubler corpus, end2=Manav RAG). Mounted `6f5044df` + `48a76785`; added Duty 6 + a `links` block to `agent.json`/`agent.md`. 7 open questions. Per Stephen's *"links to be first class primitives like beads with their own uris … end1 and end2 just being uris."* - **2026-06-18** — Added **Duty 5 (master scheduler)**: the orchestrator is the **World** driving `world.ask(beads, b => b.step())`. Wrote the execute-face [`agent.mjs`](agent.mjs) (`startup`/`setup`/`step`/`die` + pure `schedule` + `ask`; Node self-test dry-runs one tick over the live 103-bead commons, 2 schedulable). Added the `scheduler` block to `agent.json`, Duty 5 to `agent.md`, [02-master-scheduler-world-ask.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-18/notes/02-master-scheduler-world-ask.md), and mounted the World/agent framing beads (`f4ef67b7`, `d4b881f0`, `874fce5b`). Per Stephen's *"bead-bind bead-orchestrator … master scheduler of beads calling their steps."* - **2026-06-16** — Designed `agent.step`: wrote [01-agent-step-and-determinism.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-16/notes/01-agent-step-and-determinism.md) — the tick (SENSE/COMPUTE/ACT), the argument that the steady-state tick is a deterministic `step.mjs` (no model SDK), the two boundaries where cognition genuinely lives (compile the protocol spec; author adapters / drain escalations), the decision rule for what may stay an LLM call, and the concrete `skills/*.mjs` shape mirroring `82bd6fa4`'s `handle(req,ctx)`. 5 open questions added.
## Modus Operandi (How to interact) - Read [00-orchestrator-charter.md](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-14/notes/00-orchestrator-charter.md) first. - The open questions in the charter §"Open questions" are Stephen's binding decisions; nothing there is reified until he binds. - Deposit material/requests into `uploads/` per the blackboard protocol. - Conformance reports the orchestrator produces about another bead are *offered* into that bead's `uploads/` dock, never written into its tree directly.
## Capabilities - Design synthesis over the bead-protocol / multi-endpoint / liveness thread (by reference to the mounted beads). - No deployed monitor/sync daemon yet — this bead *describes* the orchestrator; reference `conformance-scan.mjs`, `migrate-interface.mjs`, and a leader-election sketch are natural next artifacts once the open questions are bound.
## Lifecycle Active design + coordination thread. Apoptoses into a citable record + a set of skills once the duties are bound and (optionally) a running orchestrator daemon is hatched as a child bead; the folder persists as the fossil.
## Limitations - Paper design — no running monitor, sync-coordinator, or leader-election exists yet. - `protocolVersion` and the `agent.json.orchestrator` block are **proposed**, not ratified into `.agents/beads.md`. - Leader election across endpoints is named in the hosting runbook but unimplemented; the cross-origin/CORS bridge is a sketch.
## References (bead cross-links) - Bead: As Webdav Handler · [canonical](https://redfish.acequia.io/guerin/.agents/fe7fbaf5-4c47-43b6-be1b-2f6ca15e8bfa/) - Bead: Stephenguerin.live Router Bead · [canonical](https://redfish.acequia.io/guerin/.agents/82bd6fa4-4d5a-435b-9deb-ca930a82aa89/) - Bead: Home Port Forward Hosting · [canonical](https://redfish.acequia.io/guerin/.agents/7049c694-e45b-4116-a887-49e64885ac8e/) - Bead: Agentify Bead · [canonical](https://redfish.acequia.io/guerin/.agents/d9dfa5e4-3c92-4216-bd53-13b520c59a5e/) - Bead: CV · [canonical](https://redfish.acequia.io/guerin/.agents/5595c7f1-4621-437c-a4ae-7902b640f0e8/) - Bead: Agentscript Webgpu · [canonical](https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/) - Bead: Agent Based Hubler Network · [canonical](https://redfish.acequia.io/guerin/.agents/d4b881f0-c320-4428-adac-7fa03941def4/) - Bead: 874fce5b · [canonical](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/) - Bead 81ed75bb · [canonical](https://redfish.acequia.io/guerin/.agents/81ed75bb-82af-4f72-86ed-c76ccd4c3b90/) (no page yet) - Bead: Claude Memory · [canonical](https://redfish.acequia.io/guerin/.agents/404514b5-52bf-4181-b249-9a305593f8c2/) - Bead: Orama Bead · [canonical](https://redfish.acequia.io/guerin/.agents/6f5044df-cd90-459d-a150-e0250e98039a/) - Bead: Collaborative Beads · [canonical](https://redfish.acequia.io/guerin/.agents/48a76785-d7a3-4fee-99f5-84b57fb158ba/) - Bead: Remote · [canonical](https://redfish.acequia.io/guerin/.agents/792ebed9-c03a-4ed0-82fb-da4d19a1a5f5/)
See all: Beads