**Note** from Bead: Agentic Route Flip · [canonical source](https://redfish.acequia.io/guerin/.agents/1057235a-f575-4046-8c63-67475a33374d/2026-06-07/notes/agentic-route-flip-plan.md) · session 2026-06-07 · discussion: Talk: Agentic Route Flip
## The goal in one line Let **CV** cause `wiki.harvardviz.live` to reverse-proxy to a chosen local node port (today it is `localhost:3000` in [`C:\caddy\caddyfile.txt`](file:///C:/caddy/caddyfile.txt)), on demand and reversibly, **without CV ever opening a listening socket or running Caddy itself.**
## The constraint that shapes everything An LLM that, on its own initiative, stands up and operates a persistent network service is outside what the Anthropic usage terms permit. So the design never lets CV *be* the server or *be* the thing that runs `caddy reload`. Instead it splits the work into three roles with a hard line between authoring/declaring (safe for an LLM) and enforcing (ordinary software under the owner's authority): | Role | Who | What it does | Binds a socket? | |---|---|---|---| | **Author** | CV | writes the protocol, the daemon code, the envelopes | no | | **Declarer** | CV (or any agent) | PUTs a route-request envelope into a mailbox directory | no | | **Enforcer / mayordomo** | `route-reconciler.mjs`, a plain Node daemon | watches the mailbox, validates against policy, edits the Caddyfile, runs `caddy reload` | no (it execs `caddy`, which Caddy already owns) | | **Server** | the content node on `:3000` | serves the actual site | yes — but it is plain software the owner runs | | **Authoriser** | Stephen (or human-supervised CE) | launches the daemon and the node **once**, granting them their standing authority | n/a | CV's entire footprint is files: a daemon it wrote, and envelopes it PUTs. The two things that hold sockets (the content node and Caddy) are pre-existing, owner-run software. **The agent declares intent; the headgate is opened by the mayordomo, not by the agent.** This is the same separation the bead ecology already argues for in [agent-as-bead.md](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/agent-as-bead.md): outputs are *offered* for owner-mediated binding, never written straight into infrastructure the agent does not own.
## Why this is the ingress / mayordomo pattern (not a hack) [ingress-controller-as-mayordomo.md](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/2026-05-16/notes/ingress-controller-as-mayordomo.md) establishes the isomorphism: a Kubernetes ingress controller, an acequia mayordomo, and the Acequia service worker are the same role at different substrates. They (1) read a declarative ledger of intent, (2) reconcile it against live flow, (3) render that into routing instructions, and (4) hold no inventory of their own. `route-reconciler.mjs` **is that role at the single-host substrate.** The mailbox directory is the *libro de acequia* (the ledger of declared rights). The reconciler is the *mayordomo*. Caddy is the *compuerta* (headgate) it opens. The envelope is a parciante declaring a turn. Crucially, **agent location is agent loyalty**: the reconciler runs on Stephen's machine, at Stephen's ingress, so it serves Stephen, not a platform.
## Why this is reaction-diffusion (the Rodenbeck frame) From [04-reaction-diffusion.md](https://redfish.acequia.io/guerin/.agents/0307b995-f403-49c4-ad93-1b4da7c8d662/2026-05-03/notes/04-reaction-diffusion.md): the ink is the agents, the wet paper is the matrix (web, caches, edge, tunnels), reaction-diffusion is the async GET-compute-PUT, and the move is *changing the viscosity of the landscape so the digital ink finds the path of least constraint.* A Caddy route is a **slow Turing form** that precipitates out of **fast request-flux**: - The **envelope** CV PUTs is a drop of *activator* ink at the `wiki.harvardviz.live` site. - The **reconciler** is the medium whose viscosity lets that drop condense into a **wire** (the reverse-proxy binding). Flipping the route is locally lowering viscosity along one channel so traffic flows to CV's node. - The **TTL** is the *inhibitor*: absent renewal, the form dissolves and the channel reverts. This is exactly [apoptosis-vs-necrosis.md](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/apoptosis-vs-necrosis.md) — the route dies by *signal* (expiry), orderly, not by crashing and leaving a dangling proxy. So the route is not a static config edit; it is a bead held in place by ongoing demand (renewals) and dissolved by an inhibitor (TTL). That is the bead ecology's whole stance on resource lifecycle, applied to one reverse-proxy line.
## The "hey you it's me" protocol A stigmergic, directory-shaped handshake. No RPC, no open port: agents communicate by leaving files where the mayordomo looks. The name is the semantics: **"hey *you*"** = the `to` field addresses a specific reconciler; **"it's *me*"** = the `from` field is a *verifiable* self-identification (an agent's bead URI, optionally a chain-token signature). It is the presence/announce idiom the brainstorm gestured at, made concrete as a mailbox. ### Directory layout (lives in the bead, WebDAV-synced so the daemon and the agent share it) ``` <mailbox>/ e.g. .../<bead>/2026-06-07/artifacts/route-mailbox/ inbox/ agents PUT envelopes here (declare) acks/ reconciler PUTs ack/nack here (reconcile receipt) active/ reconciler's current bound state (the live form) processed/ consumed envelopes, for audit (provenance) ``` ### The envelope (`inbox/<iso>-<from-guid>-wiki.harvardviz.live.json`) ```json { "protocol": "hey-you-its-me/1", "from": { "agent": "CV", "guid": "<bead-guid>", "identity": "https://redfish.acequia.io/guerin/.agents/<guid>/about.md" }, "to": "caddy-reconciler@harvardviz-node", "intent": "bind-route", "route": { "host": "wiki.harvardviz.live", "upstream": "localhost:3000" }, "ttl_seconds": 3600, "issued_at": "2026-06-07T23:59:00Z", "nonce": "<random, replay-guard>", "sig": "<optional chain-token or detached signature>" } ``` - `intent`: `bind-route` (flip it) or `release-route` (revert now). Renewal = a fresh `bind-route` before the prior TTL elapses. - `sig`: optional today; the upgrade path is an Acequia **chain-token** scoping *who may bind which host to which upstream*, so the reconciler can verify capability, not just identity. See [capability-delegation.md](https://acequia.io/documentation/platform/projects/capability-delegation.md). ### The reconcile step (what the daemon does per envelope) 1. **Validate** shape + `protocol`. 2. **Authorize against policy** — `route.host` must be in the daemon's allowlist, and `route.upstream` must match the allowed pattern for that host. Anything else → `nack`. (This is the parciante's *prorrata*: declared rights are bounded.) 3. **Replay-guard** on `nonce`. 4. **Back up** the Caddyfile (timestamped) — same discipline as the workspace overwrite convention. 5. **Rewrite** the matching `host { reverse_proxy … }` block's upstream. 6. **`caddy reload`** (Caddy already holds the socket; reload is graceful, zero-downtime). 7. **Ack** into `acks/`, record the binding + `expiresAt` in `active/`, move the envelope to `processed/`. ### Apoptosis (the inhibitor loop) A timer checks `active/`. A binding whose `expiresAt` passes with no renewal is **reverted** to the host's declared default upstream (backup → rewrite → reload → expiry notice). Silent failure to revert would be necrosis; the signal-driven revert is apoptosis.
## What CV actually does, end to end 1. Author `route-reconciler.mjs` + this plan + the skill (done — they are this bead's content). 2. **Hand off to the authoriser**: Stephen, or CE under Stephen's direction, runs `node route-reconciler.mjs` once (and ensures the content node serves on the target port). CV does not run it. 3. To flip the route: CV PUTs a `bind-route` envelope into `inbox/`. The mayordomo does the rest. CV watches `acks/` for the receipt. 4. To let it lapse: stop renewing. The TTL dissolves the form.
## Open questions for Stephen / CE - **Who hosts the mailbox** — the bead subtree (simple, already synced) vs a dedicated `route-mailbox` WebDAV collection CE owns. Default: the bead. - **Signature now or later** — ship identity-only validation first, add chain-token capability checks as a fast follow. - **Default upstream of record** — revert target for `wiki.harvardviz.live` is `localhost:3000` (its current binding). Confirm that is the canonical default.
## Connections - [ingress-controller-as-mayordomo.md](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/2026-05-16/notes/ingress-controller-as-mayordomo.md) — the role this daemon plays. - [04-reaction-diffusion.md](https://redfish.acequia.io/guerin/.agents/0307b995-f403-49c4-ad93-1b4da7c8d662/2026-05-03/notes/04-reaction-diffusion.md) — route as slow form, traffic as fast flux, TTL as inhibitor. - [apoptosis-vs-necrosis.md](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/apoptosis-vs-necrosis.md) — why TTL-revert, not crash-and-dangle. - [agent-as-bead.md](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/agent-as-bead.md) — offer for owner-mediated binding; do not write into infra you do not own. - [paths-as-event-bus.md](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/2026-04-23/notes/paths-as-event-bus.md) — PUT/observe over paths is the substrate the mailbox runs on.
## A sentence to keep > CV does not flip the switch; CV writes a note that says "flip me," signs it, and drops it where the mayordomo reads. The switch is plain software the owner already trusts. The route lives only as long as the demand that asked for it.
## References (bead cross-links) - Bead: 874fce5b · [canonical](https://redfish.acequia.io/guerin/.agents/874fce5b-9c8b-4b23-b2ed-429148c6c4b7/) - Bead: 96597c32 · [canonical](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/) - Bead: 0307b995 · [canonical](https://redfish.acequia.io/guerin/.agents/0307b995-f403-49c4-ad93-1b4da7c8d662/)