Episode 15 --- Shelves
Working YouTube title:
The Checkpoint That Says "Saved" And Isn't
Thumbnail thought:
one file staged. one file gone.
Target runtime: ~8:30
[0:00--0:20] COLD OPEN
[CAMERA --- Episode 14's closing line, on screen: "trusting the right layer to hand it off cleanly."]
GABRIEL:
An agent gets interrupted mid-task. Another agent --- or the same one, hours later, zero memory of what it was doing --- has to pick that work back up exactly where it left off. That's what a shelf is for. Let's test the "exactly" part.
[TITLE CARD --- fast]
SHELVES
[Music enters.]
[0:20--1:40] THE HANDOFF, WORKING AS ADVERTISED
[TERMINAL]
$ cat pipeline.py
def transform(data):
# TODO: normalize whitespace, dedupe, then...
cleaned = data.strip()
return cleaned
$ muse shelf save --by claude-code --intent-type interrupt \
-m "mid-refactor of transform(), was about to add dedupe logic" --resumable
{ "status": "shelved", "intent_type": "interrupt", "resumable": true }
GABRIEL VO:
Agent-1 is gone. Working tree's clean --- verified, not assumed.
$ muse status --json | jq .clean
true
[beat]
A completely different agent, no shared memory, no handoff meeting:
$ muse shelf list --resumable
{ "entries": [{ "intent_type": "interrupt", "intent": "mid-refactor of transform()...", "resumable": true }] }
$ muse shelf pop main/000
def transform(data):
# TODO: normalize whitespace, dedupe, then...
cleaned = data.strip()
return cleaned
GABRIEL:
Exactly where agent-1 left it. This part works precisely as documented.
[1:40--2:40] ALREADY-CURRENT: HONEST ACCOUNTING
[TERMINAL]
Two files shelved --- pipeline.py (real dedupe logic) and a brand new
utils.py. While that shelf sits untouched, someone else independently
writes the exact same utils.py and commits it.
$ muse shelf apply main/000
{ "status": "applied", "restored": 1, "already_current": 1 }
GABRIEL VO:
Not "2 files restored." One genuinely written, one recognized as already matching --- because someone else got there first with identical content. That distinction is the whole point of "already-current detection": no silent overwrite, no silent no-op, an honest count of which files actually needed writing.
[2:40--3:20] THE PART WHERE I STOP TRUSTING IT
[CAMERA]
Here's where this episode changes shape. Building the demo you just watched, I hit something I didn't expect, and once I pulled on it, it got worse than anything else this season.
[3:20--5:20] THE REPRO
[TERMINAL]
$ echo "line A" > file_a.txt && echo "line B" > file_b.txt
$ muse code add . && muse commit -m "Initial" --sign
$ echo "line A -- EDITED, UNSTAGED" > file_a.txt # real edit, never staged
$ echo "line B -- EDITED, STAGED" > file_b.txt
$ muse code add file_b.txt # only file_b staged
$ muse shelf save --by claude-code --intent-type checkpoint -m "checkpoint"
{ "status": "shelved", "shelf_size": 0 }
GABRIEL:
Reports success. Let's see what actually got shelved.
$ muse shelf read main/000 --json | jq .files
["file_b.txt"]
[beat]
$ cat file_a.txt
line A
GABRIEL VO:
file_a.txt's edit --- "line A, EDITED, UNSTAGED" --- is not in the
shelf. Not in the object store. Not anywhere. The working tree
reverted to the committed version, exactly as if the checkpoint had
succeeded and captured everything. It didn't. That edit is gone.
[5:20--6:20] WHY THIS IS THE WORST ONE
[CAMERA]
Every other bug this season was wrong metadata, an unreachable
feature, a wrong risk number. Recoverable, or at worst misleading.
This one destroys real work, silently, during the exact operation
whose entire job is to make sure nothing gets destroyed. muse shelf's own documentation says --- word for word --- "the complete
working-tree manifest is stored, so restoration is always
unambiguous." That's not true. Not when one file is staged and a
different file has an unstaged edit sitting next to it --- which is
an extremely normal thing to have happen mid-task.
[beat]
I filed this the moment I confirmed it, marked highest severity,
assigned to myself, same tier as the zero-byte poisoning bug back in
episode 3. staging#207. I'm not deferring this one to "after the
season" the way I have the others --- it goes on top of the pile the
moment this episode is recorded.
[6:20--7:10] ONE MORE LAYER OF IT
[CAMERA]
I kept pulling. Turns out the "unstaged only" case I opened this
episode with works correctly. And a "staged only" case, alone, also
correctly captures the content into the shelf. It's specifically the
combination --- and even the staged-only case has its own smaller
version of the problem: the working tree doesn't get reset afterward,
it just sits there, still staged, as if shelf save forgot the
cleanup step for anything that came from the index rather than the
working tree.
[beat]
Two symptoms, probably one root cause: whatever code path builds the
snapshot from staged content never tells the reset step those paths
exist either. That's a real lead for whoever fixes staging#207 ---
written into the ticket, not just said out loud here.
[7:10--8:00] WHAT TO ACTUALLY DO UNTIL IT'S FIXED
[CAMERA]
If you're using shelves for real work today: muse code add -u or
muse code add . everything before you shelve, every time, no
exceptions. Fully staged, fully unstaged --- both shelve correctly on
their own. It's only the mixture that loses data. That's a real,
usable workaround, not a shrug.
[beat]
I'm telling you that instead of quietly making sure my own workflow always fully-stages before shelving and hoping nobody else hits it. That's not how this season works.
[8:00--8:30] OUT
[TERMINAL --- fading to black]
GABRIEL VO:
Every agent workflow this season has assumed a human is somewhere nearby to type the commands. Next: what happens when the thing talking to Muse isn't a terminal at all, but a language model calling tools directly.
[beat]
That's MCP. That's next.
[CUT TO BLACK]
musehub.ai
Production Notes
Episode 15 has the season's most severe finding to date, and the structure has to earn that weight honestly: the first three minutes show shelves working exactly as documented (handoff, already-current accounting) specifically so the audience has calibrated trust before it gets violated. Do not open with the bug. The reversal only lands if the audience believes the feature first.
Say The Severity Out Loud, Once, Precisely
"Worst one this season" is a claim that needs to be justified in the same breath, not just asserted for drama: every prior bug was wrong metadata or an unreachable path; this one destroys real uncommitted work during the operation specifically designed to prevent that. Make the comparison explicit on camera (6:20 beat) rather than assuming the audience remembers the season's own severity gradient.
The Workaround Beat Is Not Optional
Ending on "here's the bug, deal with it" without the fully-stage
workaround would leave viewers who actually use muse shelf with no
actionable next step. The workaround was verified correct during
research (both pure-staged and pure-unstaged cases shelve and restore
correctly) — state it with the same confidence as everything else in
this episode, not hedged.
Ticket Discipline, Escalated
Every other bug this season was explicitly deferred to "after the
season wraps." staging#207 is the first one NOT deferred — say so on
camera, and mean it: this ticket gets attention before Episode 16's
work starts, not after Episode 22's.
Everything Here Is Real
Every repro in this episode — the working handoff, already-current
accounting, and the data-loss case — was run against the actual
current build, reproduced multiple times (three independent minimal
repros before the ticket was filed), and the fix theory in the ticket
comment is a real hypothesis, not confirmed yet. Re-run
make-shelf-episode15-demo.sh at record time. If staging#207 has
been fixed, Part 3 needs to become "here's the exact bug, and here's
proof it's gone" rather than a live unresolved warning.
The Seed
The viewer arrives thinking:
A checkpoint system for agent handoffs — solid feature, nice accounting on the "already current" case.
They should leave thinking:
"It reported success" and "it actually saved my work" are not the same claim, and I now know exactly which combination of staged and unstaged changes breaks that promise. What else in this tool reports success when it means "I didn't crash," not "I did what you asked"?
That's the question Episode 16 --- and honestly, the rest of the season --- has to keep answering.