Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

fix(mcp): serialize deferred startup joins

Rach Pradhanc42563a43683
diff --git a/docs/adr/0197-deferred-mcp-joins-are-registry-serial.md b/docs/adr/0197-deferred-mcp-joins-are-registry-serial.md
new file mode 100644
index 00000000..a363d7ad
--- /dev/null
+++ b/docs/adr/0197-deferred-mcp-joins-are-registry-serial.md
@@ -0,0 +1,24 @@
+# 0197. Deferred MCP joins are serial within a registry
+
+Status: accepted 2026-09-24
+
+## Context
+
+ADR 0035 starts optional MCP connections before the first model call, and
+ADR 0104 joins only finished connections at later request boundaries. A parent
+and background child share one registry. When both request at once, they can
+observe the same completed startup future and each try to consume it. That
+can double-await the future or read its freed queue entry.
+
+## Decision
+
+Use the registry mutex for every deferred queue mutation and join. Public
+entry points take the lock; private helpers perform joins while it is held.
+Keep model requests nonblocking with respect to unfinished handshakes. Emit
+notices after releasing the lock.
+
+## Consequences
+
+Parent and child requests consume each finished connection once. Joining a
+completed handshake briefly serializes registry users. Explicit inspection
+and teardown can still wait for unfinished handshakes as before.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 64add5d8..0b66bf28 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -221,6 +221,7 @@ record only when you need the evidence or the edge cases.
| [0193](0193-jev-selects-effort-only.md) | Optional Jev selects only supported session effort at the next request boundary; arbitrary judgments are not exposed. |
| [0194](0194-acp-child-sessions-are-an-opt-in-preview.md) | Draft ACP child sessions stream live only with explicit opt-in; durable replay is required before default enablement. |
| [0195](0195-embedded-browser-replaces-kuri.md) | Desktop browser uses embedded Chromium, web preview uses the paired extension, and CLI fetch uses built-in HTTP without a sidecar. |
+| [0197](0197-deferred-mcp-joins-are-registry-serial.md) | Deferred MCP startup queues and joins use the registry lock so concurrent parent and child requests consume each connection once. |
## When to write one
diff --git a/src/mcp_boot.zig b/src/mcp_boot.zig
index 1a1381ec..1738838f 100644
--- a/src/mcp_boot.zig
+++ b/src/mcp_boot.zig
@@ -159,7 +159,13 @@ pub fn init(gpa: Allocator, io: Io, config_path: []const u8, global_path: ?[]con
}
/// True when `name` is already live or queued on a deferred boot.
-pub fn alreadyStarting(reg: *const Registry, name: []const u8) bool {
+pub fn alreadyStarting(reg: *Registry, name: []const u8) bool {
+ reg.mutex.lockUncancelable(reg.io);
+ defer reg.mutex.unlock(reg.io);
+ return alreadyStartingLocked(reg, name);
+}
+
+fn alreadyStartingLocked(reg: *const Registry, name: []const u8) bool {
for (reg.servers) |s| if (std.mem.eql(u8, s.name, name)) return true;
for (reg.pending_names) |n| if (std.mem.eql(u8, n, name)) return true;
return false;
@@ -179,7 +185,9 @@ fn startCtx(reg: *const Registry) StartCtx {
/// companion auto-connect so first paint is not the handshake. If the
/// thread pool cannot take the task, skip — do not run `io.async` inline.
pub fn queueStdio(reg: *Registry, name: []const u8, command: []const u8, args: []const []const u8) void {
- if (alreadyStarting(reg, name)) return;
+ reg.mutex.lockUncancelable(reg.io);
+ defer reg.mutex.unlock(reg.io);
+ if (alreadyStartingLocked(reg, name)) return;
const a = reg.arena();
const n = a.dupe(u8, name) catch return;
var cfg: std.json.ObjectMap = .empty;
@@ -298,19 +306,23 @@ fn noteMcpDeferred(io: Io) void {
/// First model call: do not wait for deferred MCP handshakes (ADR 0035).
/// Later requests only consume ready outcomes; `/mcp` and teardown may wait.
pub fn joinBeforeRequest(reg: *Registry) bool {
- switch (firstRequestJoin(reg.pending_starts.len, &reg.first_request_join_skipped)) {
- .none => return false,
- .skip => {
- noteMcpDeferred(reg.io);
- return false;
- },
- .join => return joinReady(reg),
- }
+ reg.mutex.lockUncancelable(reg.io);
+ const decision = firstRequestJoin(reg.pending_starts.len, &reg.first_request_join_skipped);
+ const merged = if (decision == .join) joinReadyLocked(reg) else false;
+ reg.mutex.unlock(reg.io);
+ if (decision == .skip) noteMcpDeferred(reg.io);
+ return merged;
}
/// Compact unfinished tasks in place without changing their flag addresses.
/// No unfinished handshake is ever awaited on the request path.
pub fn joinReady(reg: *Registry) bool {
+ reg.mutex.lockUncancelable(reg.io);
+ defer reg.mutex.unlock(reg.io);
+ return joinReadyLocked(reg);
+}
+
+fn joinReadyLocked(reg: *Registry) bool {
const pending = reg.pending_starts;
var merged = false;
for (pending, 0..) |*task, i| {
@@ -340,13 +352,11 @@ pub fn joinReady(reg: *Registry) bool {
/// (companion servers may already be present). Idempotent. Returns true
/// when this call actually merged something, so the agent can rebuild catalogs.
pub fn joinPending(reg: *Registry) bool {
- if (reg.pending_starts.len == 0) return false;
const t0 = Io.Timestamp.now(reg.io, .awake);
- const futures = reg.pending_starts;
- reg.pending_starts = &.{};
- reg.pending_names = &.{};
- mergeOutcomes(reg, futures);
- reg.gpa.free(futures);
+ reg.mutex.lockUncancelable(reg.io);
+ const joined = joinPendingLocked(reg);
+ reg.mutex.unlock(reg.io);
+ if (!joined) return false;
const waited = @max(0, t0.untilNow(reg.io, .awake).toMilliseconds());
if (waited >= 80) {
if (@import("engine_sink.zig").hostedSink()) |sink| {
@@ -358,6 +368,16 @@ pub fn joinPending(reg: *Registry) bool {
return true;
}
+fn joinPendingLocked(reg: *Registry) bool {
+ if (reg.pending_starts.len == 0) return false;
+ const futures = reg.pending_starts;
+ reg.pending_starts = &.{};
+ reg.pending_names = &.{};
+ mergeOutcomes(reg, futures);
+ reg.gpa.free(futures);
+ return true;
+}
+
test "MCP boot fans server handshakes out with io.concurrent" {
const src = @embedFile("mcp_boot.zig");
try std.testing.expect(std.mem.indexOf(u8, src, "io.concurrent(startServerTask") != null);
@@ -447,6 +467,48 @@ test "#860 later requests leave unfinished handshakes queued and consume ready t
try std.testing.expectEqual(@as(usize, 0), reg.pending_starts.len);
}
+test "concurrent parent and child requests consume a deferred handshake once" {
+ const io = std.testing.io;
+ var reg = Registry.empty(std.testing.allocator, io);
+ defer reg.deinit();
+ reg.first_request_join_skipped = true;
+ const ready = try reg.gpa.create(std.atomic.Value(bool));
+ ready.* = .init(false);
+ var completed: Io.Event = .unset;
+ var release_start: Io.Event = .unset;
+ defer release_start.set(io);
+ const Start = struct {
+ fn run(task_io: Io, flag: *std.atomic.Value(bool), done: *Io.Event, release: *Io.Event) StartOutcome {
+ flag.store(true, .release);
+ done.set(task_io);
+ release.wait(task_io) catch {};
+ return .{};
+ }
+ };
+ reg.pending_starts = try reg.gpa.alloc(PendingStart, 1);
+ reg.pending_starts[0] = .{ .future = try io.concurrent(Start.run, .{ io, ready, &completed, &release_start }), .ready = ready };
+ reg.pending_names = try reg.arena().dupe([]const u8, &.{"server"});
+ try completed.wait(io);
+
+ var release: Io.Event = .unset;
+ const Request = struct {
+ fn run(task_io: Io, registry: *Registry, gate: *Io.Event) bool {
+ gate.wait(task_io) catch return false;
+ return joinBeforeRequest(registry);
+ }
+ };
+ var parent = try io.concurrent(Request.run, .{ io, &reg, &release });
+ var child = try io.concurrent(Request.run, .{ io, &reg, &release });
+ release.set(io);
+ // Keep the future outstanding while both request threads reach its join.
+ try io.sleep(.fromMilliseconds(20), .awake);
+ release_start.set(io);
+ const parent_merged = parent.await(io);
+ const child_merged = child.await(io);
+ try std.testing.expect(parent_merged != child_merged);
+ try std.testing.expectEqual(@as(usize, 0), reg.pending_starts.len);
+}
+
test "ACP stdout discipline does not block optional startup handshakes" {
try std.testing.expect(isAcp(&.{"acp"}));
try std.testing.expect(!isAcp(&.{}));