Episode 14 --- Agent Coordination
Working YouTube title:
The Tool That Tells Agents "Zero Coupling" When There Isn't
Thumbnail thought:
two agents. one address. one wrong number.
Target runtime: ~9:00
[0:00--0:20] COLD OPEN
[CAMERA --- Episode 13's closing line, on screen: "what happens when there isn't just one agent anymore, but a dozen, all reaching for the same repository at once."]
GABRIEL:
One agent with a key is easy. A dozen agents, same repo, same minute --- that's a coordination problem, and Muse has a whole subsystem for it. Let's put it under load.
[TITLE CARD --- fast]
AGENT COORDINATION
[Music enters.]
[0:20--1:00] THE PROMISE: PARTITION THE WORK
[TERMINAL]
$ muse coord shard --help | head -3
Partition the codebase into N low-coupling work zones for parallel agents.
GABRIEL VO:
Before agents even touch code, split the codebase into zones that
don't step on each other. Four files, a real call chain --- app
calls auth and billing, both call db.
[1:00--2:30] THE NUMBER THAT SHOULD BE NONZERO
[TERMINAL]
$ muse code impact "auth.py::login"
{ "blast_radius": { "1": ["app.py::handle_request"] } }
GABRIEL:
Real coupling. app calls auth. Now let's shard this into two
zones and see what the tool thinks about that coupling.
$ muse coord shard --agents 2
{
"cross_shard_edges": 0,
"shards": [
{ "shard": 1, "files": ["app.py", "db.py"], "coupling_score": 0 },
{ "shard": 2, "files": ["auth.py", "billing.py"], "coupling_score": 0 }
]
}
[beat, GABRIEL staring at it]
GABRIEL:
app.py and auth.py --- the exact pair I just showed you calling
each other --- landed in different shards, and the tool says
coupling zero between them. That's wrong. That's not a rounding
issue, that's the tool telling two agents "you're independent" when
they demonstrably aren't.
[2:30--4:00] FINDING IT
[CAMERA]
$ muse code cat "muse/cli/commands/shard.py::_build_import_edges"
imported = rec["qualified_name"].split(".")[-1].replace("import::", "")
target = stem_to_file.get(imported)
GABRIEL VO:
qualified_name for an import isn't dot-separated. It's
double-colon-separated.
$ muse code deps app.py
{ "imports": ["import::auth::login", "import::billing::charge"] }
GABRIEL:
"import::auth::login".split(".") --- there are no dots in that
string. Split does nothing. [-1] is the whole thing, unchanged.
Strip the "import::" prefix and you're left with "auth::login"
--- which will never match a file stem like "auth". Every single
from X import Y statement --- which is most Python code --- silently
fails to resolve. muse coord shard has been computing coupling as
if none of those imports exist.
[4:00--5:00] PROVING THE REST OF IT ACTUALLY WORKS
[CAMERA]
Same exact coupling, written as import auth instead of
from auth import login:
$ muse coord shard --agents 2
{
"shards_created": 1,
"shards": [{ "shard": 1, "files": ["app.py","auth.py","billing.py","db.py"] }]
}
GABRIEL VO:
One shard. It correctly refuses to split this codebase into two,
because with bare imports the parsing actually resolves and the
partitioner sees the real coupling and does the right thing. The
connected-components logic, the greedy partitioner --- all of it is
sound. One string-parsing line is wrong, and it happens to break the
import style almost everyone actually uses. Filed as staging#206.
[5:00--6:00] RESERVATIONS: WHERE COORDINATION ACTUALLY WORKS
[CAMERA]
Zoom out from sharding to the layer underneath it --- advisory reservations, checked before an agent even starts editing.
$ muse coord reserve "app.py::handle_request" --run-id agent-1 --op modify
$ muse coord reserve "app.py::handle_request" --run-id agent-2 --op modify
{ "conflicts": ["already reserved by run-id 'agent-1'"] }
GABRIEL VO:
Immediate, correct, no ambiguity.
$ muse coord forecast
{
"conflicts": [{
"conflict_type": "address_overlap",
"agents": ["agent-1@main", "agent-2@main"],
"confidence": 1.0
}]
}
GABRIEL:
Confidence 1.0 --- this isn't a guess, it's the same address, reserved twice. This is the layer that would have caught the sharding mistake too, if two agents had actually tried to work the "independent" shards at once.
[6:00--7:00] THE QUEUE: ATOMIC CLAIMS, NOT A GUESS
[TERMINAL]
$ muse coord enqueue "Refactor billing.charge to support partial refunds"
$ muse coord enqueue "Add rate limiting to auth.login"
$ muse coord claim --run-id agent-1
{ "task": { "title": "Refactor billing.charge to support partial refunds" } }
$ muse coord claim --run-id agent-2
{ "task": { "title": "Add rate limiting to auth.login" } }
GABRIEL VO:
Two agents, two different tasks, no coordination between them beyond "ask the queue." A third agent right now gets:
{ "status": "empty" }
GABRIEL:
Not a race. Not "maybe I get task 1, maybe you do." The queue decides once, atomically, and both agents know exactly what they own.
[7:00--8:00] RECONCILE: MERGE ORDER ACROSS REAL BRANCHES
[TERMINAL]
$ muse checkout -b feat/agent-a && muse coord reserve "app.py::handle_request" --run-id agent-1
$ muse switch main && muse checkout -b feat/agent-b && muse coord reserve "app.py::handle_request" --run-id agent-2
$ muse coord reconcile
{
"conflict_hotspots": 1,
"recommended_merge_order": ["feat/agent-a", "feat/agent-b", "main"],
"strategies": { "feat/agent-b": "rebase onto main before merging" }
}
GABRIEL VO:
Two branches, same reserved address, genuine divergence. reconcile
correctly names the hotspot and recommends an order --- not "merge
whichever finishes first," an actual sequenced plan.
[8:00--8:40] WHAT THIS EPISODE ACTUALLY PROVES
[CAMERA]
Reservations, forecasting, the queue, reconcile --- four real, correct, load-bearing pieces of coordination infrastructure. One piece --- sharding's coupling metric --- was wrong in a way that would have quietly defeated the other four's purpose for the single most common Python import style there is.
[beat]
That's exactly why every layer matters independently. If shard had
been the only safety net, two agents would have collided with zero
warning. Because reservations and forecasting don't depend on
shard's coupling score at all, the collision still gets caught.
Defense in depth, mostly by accident of architecture, but real.
[8:40--9:00] OUT
[TERMINAL --- fading to black]
GABRIEL VO:
Claiming, reserving, forecasting --- all snapshot-in-time decisions. What happens when an agent's work gets interrupted mid-task, and a completely different agent has to pick it back up hours later with zero shared memory?
[beat]
That's next.
[CUT TO BLACK]
musehub.ai
Production Notes
Episode 14 has five real subsystems and one real bug; the risk is letting the bug eat the runtime the other four deserve. Budget it tightly: the shard bug gets the setup-discovery-proof arc (parts 1-2, ~4 minutes with tight editing), everything else moves fast and confident because it's demonstrating things that actually work.
The Contrast In Part 2 Is Not Optional
Showing bare-import sharding correctly refusing to split the coupled codebase is the only thing that keeps this from reading as "the coordination system is broken." It proves the fault is one string operation, not the architecture. Do not cut it for time --- cutting it is the single biggest risk to this episode's credibility.
Reconcile Was Almost A Second Bug Report --- It Wasn't
Early in research, muse coord reconcile appeared to miss an
address-overlap conflict entirely (reported zero hotspots for two
agents holding the same reservation). Retesting with the reservations
actually split across two divergent branches showed reconcile
working correctly — its job is merge-order recommendation across
branches, not raw reservation-conflict detection (that's forecast's
job, and forecast catches it correctly even in the single-branch
case). Don't resurrect the single-branch framing on camera; it was a
wrong mental model on my part, not a second bug. Worth remembering for
future research: retest a suspicious finding against the command's
actual stated purpose before concluding it's broken.
Ticket Discipline
staging#206 names the exact line, the exact wrong assumption
(::-delimited qualified names split on .), and the exact fix
(split on ::, take the segment after import). Filed before this
script was written, not after.
Everything Here Is Real
Every command in both demo repos (coord-episode14, the from-import
version showing the bug; coord-episode14-bare, the bare-import
contrast) was run against the actual current build and reproduced.
Re-run make-coord-episode14-demo.sh at record time — if #206 has
been fixed, Part 1's shard output needs to be re-captured showing the
correct nonzero coupling, and the framing shifts from "here's the bug"
to "here's what got fixed."
The Seed
The viewer arrives thinking:
Sharding, reserving, queuing, forecasting, reconciling — that's a lot of moving parts. Surely something in here is just decorative.
They should leave thinking:
One of these five pieces was actually wrong, and I couldn't have told you which one just from the feature list. The only way to know which parts of a coordination system you can trust is to actually put agents in conflict and watch what each layer does.
That's the exact posture Episode 15 needs — an agent's work getting interrupted, and trusting the right layer to hand it off cleanly.