Feature: dev-server HMR into agent hosts — hot-swap plugin MCP/hooks behind a stable host connection (webpack-HMR analog)

[ScriptedAlchemy]

Motivation

Iterating on a plugin that is installed and in active use in real hosts (Claude Code, Codex, Cursor) currently requires: agent-bundle build → copy/reinstall artifact per host → restart the host or start a new session so the stdio MCP server respawns. Every cycle kills open MCP connections and loses host-side session state. What we want is the webpack-HMR analog: the host's connection stays open while the plugin's code hot-swaps behind it.

What exists today (verified on agent-bundle dev, cargo-conductor project, 2026-09-01)

• agent-bundle dev serves the loopback workbench and (with AGENT_BUNDLE_AGENT_API_TOKEN + --agent-api) an authenticated /mcp endpoint — but that endpoint exposes the workbench's control tools (project_status, skills_list, skill_inspect, …), not the developed plugin's own MCP tools, so a host cannot attach to a live dev instance of the plugin.
• The dev server does not watch source: editing a file under src/ does not advance activeEpoch / projectRevision in project_status output (verified by polling before/after an edit).
• Host installs consume a built artifact (stdio MCP + copied skills/mcp-apps), so there is no live link back to the project at all.

The epoch model (activeEpoch, epoch-scoped workbench tools) looks like it was built for exactly this — the missing pieces are the file-watch rebuild and a host-facing stable endpoint that swaps epochs without dropping connections.

Proposed design

1. Watch mode: agent-bundle dev --watch rebuilds a new epoch on source change (debounced), keeping the last-good epoch active when the build fails (diagnostics surface in the workbench, never a dead server).
2. Host dev proxy: agent-bundle dev --install-host <claude|codex|cursor> installs a thin, stable stdio proxy as the plugin's MCP server in the host. The proxy connects to the dev server and forwards the plugin's MCP surface. On epoch swap the proxy keeps the host pipe open, re-resolves tools against the new epoch, and emits notifications/tools/list_changed (the server already advertises tools.listChanged: true) — the host never sees a disconnect.
3. Hooks: generated hook commands in the host point at the dev proxy too; since hooks are spawned per event they pick up the new epoch naturally on the next event.
4. Skills / mcp-apps: re-sync copied assets on epoch swap for hosts that read them from disk (Cursor), or serve them through the proxy where the host supports it.
5. Session semantics: in-flight tool calls run to completion against the epoch they started on; new calls bind to the active epoch (same rule webpack uses for module disposal).

Why the proxy indirection

Hosts spawn stdio MCP servers themselves and cache the connection per session; only a process that outlives rebuilds can keep that connection stable. A ~zero-dependency proxy binary whose behavior never changes is the smallest thing a host can hold onto while everything behind it stays fluid.

Environment

agent-bundle dev workbench serving /fast/projects/agent-plugins/cargo-conductor, Node 22.23.1, Linux.

[ScriptedAlchemy]

Decision (2026-09-01): sequenced after #218 stages 2-3 land; not parked.

[ScriptedAlchemy]

Stage 1 landed — #339 (27a0d592e8d234e6f16c770b5db92d365d7caba2)

The keystone of this epic: a host now holds ONE stable stdio MCP process while agent-bundle dev hot-swaps the generated plugin server behind it.

• POST /mcp/host/:serverName?target=<t> — stateful host-facing Streamable HTTP MCP endpoint on the foreground server, serving the developed plugin's MCP surface (tools/resources/prompts, listChanged: true) from the active artifact epoch. This is the endpoint this issue found missing ("/mcp exposes the workbench's control tools, not the developed plugin's own MCP tools").
• Pooled per-epoch sessions: one live generated-server session per connection per epoch, reused across calls — session-lifetime state accumulates exactly like a packed host process (pinned: in-memory counter returns 1 → 2 across calls on one connection).
• Epoch swap on rebuild: new epoch session opened + primed, promoted, notifications/tools/list_changed emitted on the same connection; in-flight calls complete against the epoch they started on (the webpack module-disposal rule from this issue's §5), then the old session drains and closes. Failed builds keep last-good serving.
• Fail-closed drift: vanished epoch → typed AB8024 MCP error ({ code, epochId }), connection invalidated — the AB8018/fix(dev): fail MCP tool calls closed when the pinned epoch vanishes #134 discipline extended to the host surface.
• agent-bundle dev proxy --root <project> --server <name> [--target <t>] [--url <origin>] — the thin stable stdio proxy hosts spawn (issue §2). Discovers the dev server via the dev-lock sidecar (discoverDevServerUrl, PR fix(dev): include owning server URL in AB5000 #132's publication read back), forwards everything including notifications, fails closed with AB8025 when no dev server is running.

Evidence: tests/host-mcp-proxy.test.ts (integration) — real proxy child process, real dev server, real rebuild: list_changed received mid-session, v1 in-flight completes while v2 serves, AB8024 on physical epoch removal, AB8025 on server loss and on cold start.

Gates local on fb25f47aa: build/typecheck/lint (0/0) · unit 2615/2616 (1 pre-existing mcp-probe timing flake, 9/9 isolated) · route-unit 24 · projection 59 · proxy integration 5/5. Pre-existing on clean main, not this diff: cli.test.ts inspect-JSON pin vs the #133 Codex validator diagnostics.

Stages: 1 done · 2 (hooks/skills re-sync into installed hosts) in review · 3 (live-host acceptance via the #242/#311 machinery) and 4 (#218 stage-4 dev-epoch contract matrix through the session-injected entry points) queued.

[ScriptedAlchemy]

Stage 2 landed — #343 (05f53c82dc3dd988c365e64bdadfa4414da17470)

Issue §3/§4 (hooks + skills/mcp-apps re-sync): agent-bundle dev --install-host <claude|codex|cursor> (repeatable) installs the developed plugin as a marked dev variant and re-syncs it into the installed host locations on every successful epoch swap.

• First epoch installs through the ordinary public installer (real claude/codex plugin CLIs, Cursor copy); the installed MCP document points at the stable stage-1 proxy — process.execPath + the framework's own resolved CLI entry + dev proxy --root … --server … --target <host> — and is never rewritten on swap (byte-identical pin).
• Re-sync on artifact.available: immutable per-epoch generations, atomic top-level symlink/file pointer renames (no torn reads, including the first swap), rollback + AB7202 on failure via a new epoch-scoped dev.host.sync event, generations pruned to {current, previous}. Claude/Codex caches are updated directly — zero host-CLI calls per epoch (pinned by command-runner call count).
• Failed builds re-sync nothing (last-good stays installed); dev-server shutdown leaves the install in place with the proxy failing closed (AB8025).
• Workbench log-kind mirror updated so the new events don't trip the strict AB8093 decoder.

Evidence: tests/dev-host-install.test.ts — real DevCoordinator+EpochStore rebuild propagating skill+hook edits into an isolated Cursor install; binary-gated real Claude and Codex lanes (install via host CLI, re-sync into the host-owned cache, marker advanced); spawn proofs for all three hosts that the exact emitted command runs without PATH assumptions and fails closed AB8025 when no dev server runs. pnpm test:host-install 16/16 with 0 skips locally.

Stages: 1 done (#339) · 2 done · 3 (live-host acceptance) and 4 (#218 stage-4 dev-epoch matrix) dispatched.

[ScriptedAlchemy]

Stage 3 landed — #374 (9fe8a35d9882621e5961ddd3128edbe8980dde23)

Live-host acceptance for the stage-1 proxy (#339) and stage-2 re-sync (#343), through the exact installed host layout rather than a hand-built client: tests/dev-live-host.test.ts (now part of pnpm test:host-install).

lane	what runs	evidence
Cursor (isolated HOME)	startDevServer({ installHosts: ['cursor'] }) installs the dev variant; the test reads ~/.cursor/plugins/local/<plugin>/mcp.json, spawns that command over stdio, sees v1:cursor, edits MCP entry + Skill + hook sources, receives exactly one notifications/tools/list_changed on the same connection, sees v2:cursor; marker advanced, installed SKILL.md and hook module re-synced	passed
Claude (real claude 2.1.257, isolated CLAUDE_CONFIG_DIR)	host-owned install through the real plugin CLI (a PATH-shim recorder around the real binary pins the plugin command count), same v1→v2 cycle through the installed .mcp.json command; zero additional host-CLI calls across the rebuild	passed
Codex (real codex-cli 0.147.0, isolated CODEX_HOME)	same discipline through the host-owned plugins/cache/... install	passed
Claude live model session (opt-in AGENT_BUNDLE_HOST_INSTALL_CLAUDE_SESSION=1)	two real model turns (--session-id then --resume) against the installed tree return v1:claude-session then v2:claude-session with no reinstall; normal Claude settings/plugin tree byte-unchanged	passed locally (4/4 + 1 honest skip)
Codex live model session	it.skip — Codex exec exposes no inline plugin-loading surface for an isolated dev install; the reason is in the test title	honestly skipped

Gates on the merged tree: build · typecheck · lint (0/0) · pnpm test:host-install 19/19 (2 documented skips) · PR CI green (Verify, Examples, Release gates after one unrelated npm audit signatures registry retry).

Stages: 1 done (#339) · 2 done (#343) · 3 done · 4 (#218 stage-4 dev-epoch contract gate + Workbench visibility) in review as #385.

[ScriptedAlchemy]

Stage 4 landed — #385 (5fac48048d2188e1478bb8a2a30ebc57d0948a5a) — epic complete

The last design item: a rebuild that would change the source→artifact→dev→installed-host contract is gated before any host-facing surface adopts it (#218 stage 4). dev.contracts (opt-in) runs the shared contract matrix against each published epoch through an epoch-pinned generated stdio session; only a passing epoch reaches the stage-1 proxy connections and the stage-2 installs, a failing one stays inactive (AB7211, or AB7210 for a bad declaration) while the last passing epoch keeps serving, and the Workbench Overview shows Host adoption (host-facing vs published build, failed checks per route) instead of silently applying it. Cold start with a failing initial build seeds the restored last-good epoch through the same gate. Full detail and evidence in the #218 close-out comment.

Acceptance against this issue's proposed design

design item	status	evidence
1. Watch mode: debounced rebuild, last-good stays active on failure, diagnostics in the workbench	done (pre-existing, verified by every stage)	#73/#75/#38/#332; tests/host-mcp-proxy.test.ts "failed builds keep last-good serving"
2. Host dev proxy: --install-host <claude|codex|cursor> installs a stable stdio proxy; epoch swap keeps the host pipe open, re-resolves against the new epoch, emits notifications/tools/list_changed (+ resources/prompts), host never sees a disconnect	done	stage 1 #339 (27a0d592): POST /mcp/host/:server, agent-bundle dev proxy, AB8024/AB8025; stage 2 #343 (05f53c82): installed MCP document pins the proxy command byte-identically across swaps; stage 3 #374 (9fe8a35d): exact installed command on Cursor, real Claude 2.1.257, real Codex 0.147.0 observes v1→v2 on one connection with exactly one list_changed
3. Hooks point at the dev flow and pick up the new epoch on the next event	done	#343: hooks re-synced into the installed layout per adopted epoch (atomic generation swap, rollback + AB7202); #374 pins the installed hook module advancing to v2
4. Skills / mcp-apps re-sync on epoch swap for hosts reading from disk	done	#343 (Cursor local layout, Claude/Codex host-owned caches, zero extra host-CLI calls — pinned by command-runner count); #374 pins SKILL.md → v2 in all three installed layouts
5. Session semantics: in-flight calls finish on their epoch, new calls bind to the active epoch	done	#339 host-mcp-proxy.test.ts: v1 in-flight completes while v2 serves; old session drains after
Contract-gated adoption (added from #218 stage 4): failing epoch never reaches hosts, surfaced as diagnostic + Workbench	done	#385: tests/dev-contract-adoption.test.ts, packages/workbench/tests/host-adoption.e2e.test.ts (1440×900), AB7210/AB7211 in docs/diagnostics.md
Docs	done	docs/framework-mode.md "Live development into hosts", docs/architecture/rsc-runtime-workbench.md host-adoption axis, docs/diagnostics.md (AB7200–AB7202, AB7210–AB7211, AB8024–AB8025), package + root README

Real-host evidence beyond the deterministic lanes: the opt-in AGENT_BUNDLE_HOST_INSTALL_CLAUDE_SESSION=1 lane drove two real Claude model turns (--session-id / --resume) against the installed dev plugin and got v1:claude-session then v2:claude-session with no reinstall and the normal Claude settings/plugin tree byte-unchanged. Codex exposes no inline plugin-loading surface for an isolated dev install; that lane is an honest skip with the reason in its title.

Stages: 1 #339 · 2 #343 · 3 #374 · 4 #385. Closing.