Repository navigation
mcpx: Phase 1 of #1384 — supervised stdio transport behind a flag (supervisor owns the child's pipes) #1385
Description
Phase 1 of the mcpx supervisor design, #1384 (design doc: files/designs/code-mcpx-stdio-supervisor.md in the keep-the-four-repos-healthy goal workspace). This phase is deliberately the experiment that proves the attach model before any takeover code changes: everything here is additive and flag-gated.
Scope
- Hidden
mcpx supervisesubcommand. Re-exec of the same binary. It spawns exactly one stdio MCP server child with the process semanticsNewStdiohas today (pkgs/mcpx/internal/mcpclient/stdio.go: own process group viaSetpgid, plainos.Pipe()s rather thancmd.Std*Pipe, stderr captured to a ring buffer), owns the child's stdin/stdout/stderr for the child's whole life, and:- serves one attached daemon at a time over a unix socket in the mcpx state directory (socket file mode follows the 0600 state-file precedent,
internal/daemon/sessions.go); - pumps stdin/stdout bytes between socket and child without interpreting MCP frames (framing stays in the daemon's transport reader);
- buffers child output produced while no daemon is attached, up to a bounded limit; on overflow it keeps the tail and counts dropped bytes, reporting the count to the next daemon that attaches;
- reports child PID and child exit (with exit error) to the attached daemon;
- exits when its child has exited and no daemon is attached (no lingering supervisors for dead children).
- serves one attached daemon at a time over a unix socket in the mcpx state directory (socket file mode follows the 0600 state-file precedent,
- Supervised transport in
internal/mcpclientimplementing the same transport interface the pool uses forStdioTransport, connecting to the supervisor socket instead of spawning a child.Detach/adoption semantics of the existing transport are not reused — a supervised transport'sClosedetaches from the supervisor without signalling the child. - Per-server opt-in config flag selecting the supervised transport for a stdio server. Default off. With the flag off, behaviour is byte-for-byte today's (direct spawn, existing takeover path untouched).
Out of scope: any change to internal/daemon/takeover.go or internal/pool/handoff.go (that is Phase 2); HTTP/SSE upstreams; making supervised the default (Phase 3).
Acceptance criteria
- With the flag on for a stdio server, the server runs under a supervisor: child PID ≠ daemon-spawned direct child, and the supervisor's parent is not the daemon's serving process (child survives the daemon).
- Defining test: start daemon + supervised server, make a call, SIGKILL the daemon, start a new daemon — the child's PID is unchanged and a subsequent call on that server succeeds.
- Child exit while supervised is surfaced to the daemon exactly as a direct child's exit is today (existing pool behaviour/tests apply), and the supervisor process exits afterwards.
- Unattached-output buffer: a child that writes while no daemon is attached does not block indefinitely or grow memory unboundedly; the dropped-byte count is reported on attach (test covers overflow).
- With the flag off (default), the full existing mcpx test suite passes unchanged, including
internal/e2e/takeover_test.go. -
go test ./...inpkgs/mcpxpasses; new code has tests for the supervisor pump, attach/detach, and buffer overflow.
Evidence / grounding
- Design: design(mcpx): a supervisor that owns each stdio child's pipes — replace the takeover handoff for stdio #1384;
pkgs/mcpx/TODO.md:3;planning/roadmaps/mcpx.md(Next, supervisor,idea). - Current spawn semantics to mirror:
internal/mcpclient/stdio.goNewStdio(~line 86 onward). - State-dir + 0600 precedent:
internal/daemon/sessions.go.
Activity
developing-today commentedon Oct 27, 2026
CODE-479
dezren39 commentedon Oct 27, 2026
🤖 Agent note · filed
files/designs/code-mcpx-stdio-supervisor.md(goal workspace)dezren39 commentedon Oct 27, 2026
🤖 Agent note · blocked
repo-health-code-shadowqueue as task 1354 instead ofrepo-health-code-pilot. Because queue dedupe is absolute on the dedupe key, re-enqueueing with the correct--queuereturned that same row; I cancelled task 1354 (reason recorded on the task) rather than leave live work in the dormant shadow queue. This issue still carriesqueue/queuedwith no live task — the fleet monitor's safety-net reconciliation is the route that re-enqueues it into the pilot queue.dezren39 commentedon Oct 27, 2026
🤖 Agent note · blocked
queue/queuedbut has no live task in repo-health-code-pilot. The monitor built a triage packet and called enqueue at 2026-10-27T10:49Z; the RPC returned the CANCELLED shadow-queue task 1354 (same dedupe keyrepo-health:v1:triage:developing-today/code:issue:1385, cancelled with reason "enqueued into shadow queue by a flag-less first attempt; re-enqueue to repo-health-code-pilot") and created no pilot task — verified by a direct live-queue query afterwards. Until Queue dedupe is a one-way door: a cancelled task permanently blocks re-enqueue of its issue #1298 is fixed (or an operator clears/repoints the cancelled row), this work order cannot be enqueued under its deterministic key. The richer architect-authored packet text survives on cancelled task 1354.28 remaining items
dezren39 commentedon Oct 27, 2026
🤖 Agent note · parked
dezren39 commentedon Oct 28, 2026
🤖 Agent note · picked up
queue/1463-1385-supervised-stdioMerge pull request #1495 from developing-today/queue/1463-1385-superv…
dezren39 commentedon Oct 28, 2026
🤖 Agent note · done
mcpx supervisesubcommand, supervised transport in internal/mcpclient (attach handshake, 1 MiB tail-keep buffer with droppedBytes reporting, detach-only Close),mcpx.supervisedper-server flag default off, Pool.dial branch; takeover.go/handoff.go untouched. Closing this issue — all acceptance criteria are Phase 1 scope and are covered by the merged implementation + its tests (supervisor pump, attach/detach, buffer overflow, defining SIGKILL-reattach test in internal/mcpclient/supervised_test.go, full suite green in CI). Cross-repo: dezren39/nix no longer vendors mcpx — it builds from the pinnedmcpx-srcflake input, so the nix side picks this up on its next pin bump (recorded as SET-REMAINDER in the code backlog; no nix source port owed).