spike(#446): herdr × mycelium wake path — doc + PoC

[juliarvalenti]

Spike for #446 — does herdr solve mycelium's persistent-runtime gap, and what's the seam. Exploration / de-risking, not a commitment to build. Two deliverables: a "what's possible" doc and a working PoC of Shape 1.

The gap it closes

A non-resident mycelium agent invoke <handle> queues on the durable cursor with nothing to wake it — it "goes to the aether." herdr keeps agent sessions alive + addressable, so the wake becomes herdr agent prompt <pane>: the agent wakes in place with full context and replies through the room. Strictly better than the removed claude -p cold-spawn (which discarded context every turn), without the coupling that rotted openclaw/hermes.

Proven live (end-to-end)

Against a running backend + a real persistent Claude Opus session in a herdr pane:

invoke poc-reviewer → not resident → herdr agent prompt w2:pV "<wake prompt>"
  → live session woke IN PLACE, ran `mycelium await` then `mycelium respond`
  → reply landed: poc-reviewer [broadcast]: "Confirmed — the herdr wake path delivered this…"

What's here

• docs/design/herdr-integration.md — the "what's possible" deliverable: surfaces herdr exposes, the 4 shapes re-scoped after a live 0.8.0/protocol-19 probe, user stories, open questions.
• integrations/herdr/ — fail-soft CLI bridge + durable handle→pane registry (~/.mycelium/herdr/registry.json).
• mycelium herdr group — map / unmap / ls (live liveness column) / status / wake.
• opt-in herdr.autowake wired into agent invoke (config-gated, fail-soft; degrades to the cursor).
• config — new [herdr] section; fixes save() global-section whitelist that dropped it.
• tests — 18 mocked-herdr unit tests (registry, parsing, wake, invoke gate). Full CLI gate green (ruff/format/ty + 314 tests).

Two backend-await findings the live run surfaced (NOT herdr bugs)

These are the spike's real payoff — the issue's "wake semantics" / "lifecycle ownership" open questions, now concrete with file:line anchors:

1. Cold-wake races the first-await cursor init (fastapi-backend/app/routes/participate.py:158): a handle's cursor inits to current transcript end on first poll, so invoke → wake → first-await misses the just-posted message. Correct for a looping resident, wrong for cold-wake. A second invoke (cursor established) delivered fine.
2. Presence lease outlives actual awaiting (commands/agent.py:174): post-wake, _is_resident reads True from a stale lease even though the agent settled and isn't looping — so the next invoke skips the wake.

Both are backend fixes, deliberately out of scope for this CLI-side PoC.

Non-goals

• Not replacing await/respond — herdr is an optional wake, not a requirement.
• Not spawning panes/agents from mycelium — the PoC only drives agents the user created.
• Not committing to build — this is to decide whether it's worth it and what the seam is.

Closes the exploration in #446.

Known gaps

• Agent-to-agent mentions don't wake (structural). Wake-on-mention is hooked
  only into the human message path (routes/messages.py POST /messages, i.e.
  the UI / room send). Agent replies go out via mycelium respond →
  routes/participate.py POST /reply, which does not call the
  _enqueue_herdr_wakes hook — so an agent @-mentioning another agent enqueues
  no wake and the tag falls into the aether. Human→agent works; agent→agent
  doesn't. Fix is to run the same mention→enqueue on the /reply path (and ideally
  factor it into one shared post-message hook so no future write path can miss it).
• herdr state is title-scraped (flaky). Without the herdr claude state-hook,
  herdr infers working from the terminal-title spinner (osc_title_working,
  prio 1100 > live_prompt_box, 950), which can stick after an interrupted turn —
  a pane reads working while idle and its held wake never releases. Reliable
  state needs herdr integration install claude.
• Backend restart blanks presence for ~45s. The sync bridge only re-pushes on
  change/heartbeat, so after a backend bounce the badges/wakes go dark until the
  next heartbeat (or a bridge restart). Bridge should force a push per tick or the
  backend should request a resync.
• Security: the two new endpoints are unauthenticated. POST /sessions/herdr-presence and GET /sessions/herdr-wakes have no authz, and a
  wake ultimately runs herdr agent prompt against a local coding-agent pane —
  room-post content can steer a local agent. Single-user-local PoC only; must be
  architected around the D1 JWT/SPIRE identity work before anything hosted/multi-user.

[juliarvalenti]

Follow-up (pushed): residence grounded in herdr's live agent list.

Per review, the set of lease-holding agents is now reconciled against herdr availability — the fix for Finding 2 (the containerized, herdr-blind backend reporting a stale lease as "resident"). The CLI is the only layer that reaches both the backend /members API and the local herdr socket, so it lives here.

• agent invoke — _resolve_presence makes herdr authoritative for a mapped handle: live+idle → wake in place (over a stale lease), working/blocked → resident, dead pane → stale (queued + warned); unmapped handles keep lease behavior.
• mycelium herdr ls — now a 3-way reconciliation (registry × backend presence slim/lease × live herdr state) with stale lease / herdr-only / in sync verdicts. Verified live:

  handle          mycelium   herdr   verdict
  @poc-reviewer   absent     done    herdr-only (not joined)
  

  (the agent is alive in herdr but its lease has lapsed — the inverse of a stale lease).
• +6 tests (idle-wins-over-stale-lease, stale-mapping, reconcile verdicts). 320 pass, gate green.

[juliarvalenti]