feat(local-coord-mcp): role tiers, supervisor gating, quarantine queue

Tasks #5 + #6. Adds the supervision layer that makes supervised peers
(gemini / codex / vibe by default) safe to have in a shared workspace —
Tier 2+ ops land in a quarantine queue for supervisor review instead of
delivering directly.

FFI changes (local_coord_ffi.zig):
- New Role enum { supervisor, executor, supervised } stored on each Peer.
  Default derived from client_kind: claude -> executor, everything else
  -> supervised.
- coord_register now takes role_hint as a 2nd arg; ROLE_HINT_DEFAULT=-1
  honors client_kind default; role_hint=0 (supervisor) is ALWAYS
  rejected — use coord_promote_to_supervisor instead.
- coord_promote_to_supervisor gates supervisor role on the
  BOJ_SUPERVISOR_TOKEN env var (constant-time compare) + at most one
  supervisor rule. Env var unset = supervisor role unavailable.
- coord_set_role lets the active supervisor reassign other peers'
  roles, with protection against demoting the sole supervisor.
- coord_send_gated routes Tier 2+ ops from supervised peers to a
  32-entry quarantine queue; returns an encoded request_id (negative
  value < -1000) instead of a direct send count.
- coord_review / coord_review_entry / coord_approve / coord_reject
  are the supervisor-only review tools. approve delivers the pending
  message to its target(s); reject logs the reason without delivery.
- coord_read_peer_role helper for adapter introspection.

Adapter changes (local_coord_adapter.zig):
- coord_register accepts optional `role` JSON field.
- New dispatch handlers for coord_promote_to_supervisor,
  coord_send_gated, coord_review, coord_review_entry, coord_approve,
  coord_reject.
- coord_review emits a JSON array with request_id + preview;
  coord_review_entry returns the full message body.

MCP surface:
- cartridge.ncl declares the 6 new tools with full schemas.
- cartridge.json regenerated.
- mcp-bridge/lib/tools.js declares the same tools to clients.
- mcp-bridge/main.js dispatchTool routes the new names to
  dispatchLocalCoord.

Tests (all passing):
- Default role derives from client_kind
- Register rejects role_hint=supervisor (-3)
- Promote contract documented (env-var check behaviour)
- Gated send from supervised lands in quarantine; Tier 0/1 delivers direct
- Supervisor approve delivers the message to the target
- Supervisor reject removes without delivery
- Non-supervisor cannot review/approve/reject (-1)
- Pre-existing send/receive/claim/context/suffix tests updated for new
  coord_register signature.

Version bump: 0.2.0 -> 0.3.0 (new API surface).

Remaining for the coord backbone:
- Watchdog TTL on supervised claims (DD-20)
- warn_drift broadcast via Opus review on auto-release (DD-21)
- Quarantine spill to VeriSimDB when in-memory queue full (DD-21)
- VeriSimDB sidecar for durable state (Task #7)
- E2E test across 2 instances (Task #8)

Follows memory/project_coord_supervision_architecture.md.
Design log + rationale: Desktop/COORD-MCP-DESIGN-LOG.md (Parts 3-4,
Appendices A-J).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

cartridges/local-coord-mcp/adapter/local_coord_adapter.zig

@@ -83,9 +83,21 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
             break :blk ctx_val.string;
         };
 
+        // Optional role hint. Server rejects role=supervisor here; callers
+        // must promote via coord_promote_to_supervisor with the env secret.
+        const role_hint: i32 = blk: {
+            const rv = parsed.value.object.get("role") orelse break :blk -1;
+            const rs = rv.string;
+            if (std.mem.eql(u8, rs, "supervisor")) break :blk 0;
+            if (std.mem.eql(u8, rs, "executor")) break :blk 1;
+            if (std.mem.eql(u8, rs, "supervised")) break :blk 2;
+            break :blk -1;
+        };
+
         var token: [16]u8 = undefined;
         var suffix: [4]u8 = undefined;
-        const idx = ffi.coord_register(kind, &token, &suffix);
+        const idx = ffi.coord_register(kind, role_hint, &token, &suffix);
+        if (idx == -3) return .{ .status = 400, .body = errJson(resp, "supervisor role must be obtained via coord_promote_to_supervisor") };
         if (idx < 0) return .{ .status = 500, .body = errJson(resp, "registry full") };
 
         if (ctx_str.len > 0) {
@@ -241,6 +253,155 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
         return .{ .status = 500, .body = errJson(resp, "claim failed") };
     }
 
+    if (std.mem.eql(u8, tool, "coord_promote_to_supervisor")) {
+        const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
+        defer parsed.deinit();
+        const token_val = parsed.value.object.get("token") orelse return .{ .status = 400, .body = errJson(resp, "missing token") };
+        const secret_val = parsed.value.object.get("secret") orelse return .{ .status = 400, .body = errJson(resp, "missing secret") };
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        const secret = secret_val.string;
+        const rc = ffi.coord_promote_to_supervisor(&token, 16, secret.ptr, @intCast(secret.len));
+        if (rc == 0) return .{ .status = 200, .body = okJson(resp, "promoted") };
+        if (rc == -1) return .{ .status = 401, .body = errJson(resp, "unauthenticated") };
+        if (rc == -2) return .{ .status = 409, .body = errJson(resp, "supervisor already exists") };
+        if (rc == -3) return .{ .status = 403, .body = errJson(resp, "supervisor role not configured on this server") };
+        if (rc == -4) return .{ .status = 403, .body = errJson(resp, "secret does not match") };
+        return .{ .status = 500, .body = errJson(resp, "promotion failed") };
+    }
+
+    if (std.mem.eql(u8, tool, "coord_send_gated")) {
+        const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
+        defer parsed.deinit();
+        const token_val = parsed.value.object.get("token") orelse return .{ .status = 400, .body = errJson(resp, "missing token") };
+        const target_val = parsed.value.object.get("target") orelse return .{ .status = 400, .body = errJson(resp, "missing target") };
+        const msg_val = parsed.value.object.get("message") orelse return .{ .status = 400, .body = errJson(resp, "missing message") };
+        const tier_val = parsed.value.object.get("risk_tier") orelse return .{ .status = 400, .body = errJson(resp, "missing risk_tier") };
+
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        const target_str = target_val.string;
+        var target_idx: i32 = -1;
+        if (!std.mem.eql(u8, target_str, "*")) {
+            const suffix = extractSuffix(target_str) orelse return .{ .status = 400, .body = errJson(resp, "invalid target format") };
+            target_idx = ffi.coord_find_peer_by_suffix(suffix.ptr);
+            if (target_idx < 0) return .{ .status = 404, .body = errJson(resp, "target peer not found") };
+        }
+
+        const msg = msg_val.string;
+        const tier: i32 = @intCast(tier_val.integer);
+        const rc = ffi.coord_send_gated(&token, 16, target_idx, msg.ptr, @intCast(msg.len), tier);
+
+        if (rc >= 0) {
+            const body_out = std.fmt.bufPrint(resp, "{{\"success\":true,\"status\":\"delivered\",\"sent\":{d}}}", .{rc}) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+            return .{ .status = 200, .body = body_out };
+        }
+        if (rc < -1000) {
+            const request_id: i64 = -(@as(i64, rc) + 1000);
+            const body_out = std.fmt.bufPrint(resp, "{{\"success\":true,\"status\":\"quarantined\",\"request_id\":{d}}}", .{request_id}) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+            return .{ .status = 200, .body = body_out };
+        }
+        if (rc == -1) return .{ .status = 401, .body = errJson(resp, "unauthenticated") };
+        if (rc == -2) return .{ .status = 404, .body = errJson(resp, "target peer not found") };
+        if (rc == -3) return .{ .status = 503, .body = errJson(resp, "target inbox full") };
+        if (rc == -4) return .{ .status = 503, .body = errJson(resp, "quarantine queue full — spill to VeriSimDB not yet wired") };
+        if (rc == -5) return .{ .status = 428, .body = errJson(resp, "no supervisor registered — Tier 2+ from supervised requires a supervisor") };
+        return .{ .status = 500, .body = errJson(resp, "gated send failed") };
+    }
+
+    if (std.mem.eql(u8, tool, "coord_review")) {
+        const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
+        defer parsed.deinit();
+        const token_val = parsed.value.object.get("token") orelse return .{ .status = 400, .body = errJson(resp, "missing token") };
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        // 32 entries max * 16 bytes per record = 512 bytes raw.
+        var raw: [512]u8 = undefined;
+        const count = ffi.coord_review(&token, 16, &raw, @intCast(raw.len));
+        if (count < 0) return .{ .status = 403, .body = errJson(resp, "supervisor role required") };
+
+        var stream = std.io.fixedBufferStream(resp);
+        const w = stream.writer();
+        w.writeAll("{\"success\":true,\"entries\":[") catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+
+        var i: usize = 0;
+        const cnt: usize = @intCast(count);
+        while (i < cnt) : (i += 1) {
+            const rec = raw[i * 16 ..][0..16];
+            const rid_bytes: *const [4]u8 = rec[0..4];
+            const rid: u32 = @bitCast(rid_bytes.*);
+            const sender_idx: u8 = rec[4];
+            const target_idx_sign: i8 = @bitCast(rec[5]);
+            const risk_tier: u8 = rec[6];
+            const mlen_bytes: *const [2]u8 = rec[7..9];
+            const mlen: u16 = @bitCast(mlen_bytes.*);
+            const preview_n: usize = @min(@as(usize, 7), @as(usize, mlen));
+            const preview = rec[9 .. 9 + preview_n];
+
+            if (i > 0) w.writeAll(",") catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+            std.fmt.format(w, "{{\"request_id\":{d},\"sender_idx\":{d},\"target_idx\":{d},\"risk_tier\":{d},\"msg_len\":{d},\"preview\":\"{s}\"}}", .{
+                rid, sender_idx, target_idx_sign, risk_tier, mlen, preview,
+            }) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+        }
+        w.writeAll("]}") catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+        return .{ .status = 200, .body = resp[0..stream.pos] };
+    }
+
+    if (std.mem.eql(u8, tool, "coord_review_entry")) {
+        const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
+        defer parsed.deinit();
+        const token_val = parsed.value.object.get("token") orelse return .{ .status = 400, .body = errJson(resp, "missing token") };
+        const rid_val = parsed.value.object.get("request_id") orelse return .{ .status = 400, .body = errJson(resp, "missing request_id") };
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        var msg_buf: [512]u8 = undefined;
+        const rc = ffi.coord_review_entry(&token, 16, @intCast(rid_val.integer), &msg_buf, @intCast(msg_buf.len));
+        if (rc == -1) return .{ .status = 403, .body = errJson(resp, "supervisor role required") };
+        if (rc == -2) return .{ .status = 404, .body = errJson(resp, "request_id not found") };
+        if (rc < 0) return .{ .status = 500, .body = errJson(resp, "review failed") };
+
+        const msg_slice = msg_buf[0..@intCast(rc)];
+        const body_out = std.fmt.bufPrint(resp, "{{\"success\":true,\"message\":\"{s}\"}}", .{msg_slice}) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+        return .{ .status = 200, .body = body_out };
+    }
+
+    if (std.mem.eql(u8, tool, "coord_approve")) {
+        const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
+        defer parsed.deinit();
+        const token_val = parsed.value.object.get("token") orelse return .{ .status = 400, .body = errJson(resp, "missing token") };
+        const rid_val = parsed.value.object.get("request_id") orelse return .{ .status = 400, .body = errJson(resp, "missing request_id") };
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        const rc = ffi.coord_approve(&token, 16, @intCast(rid_val.integer));
+        if (rc == 0) return .{ .status = 200, .body = okJson(resp, "approved") };
+        if (rc == -1) return .{ .status = 403, .body = errJson(resp, "supervisor role required") };
+        if (rc == -2) return .{ .status = 404, .body = errJson(resp, "request_id not found") };
+        if (rc == -3) return .{ .status = 503, .body = errJson(resp, "target inbox full — retry") };
+        return .{ .status = 500, .body = errJson(resp, "approve failed") };
+    }
+
+    if (std.mem.eql(u8, tool, "coord_reject")) {
+        const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
+        defer parsed.deinit();
+        const token_val = parsed.value.object.get("token") orelse return .{ .status = 400, .body = errJson(resp, "missing token") };
+        const rid_val = parsed.value.object.get("request_id") orelse return .{ .status = 400, .body = errJson(resp, "missing request_id") };
+        const reason_val = parsed.value.object.get("reason") orelse return .{ .status = 400, .body = errJson(resp, "missing reason") };
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        const reason = reason_val.string;
+        const rc = ffi.coord_reject(&token, 16, @intCast(rid_val.integer), reason.ptr, @intCast(reason.len));
+        if (rc == 0) return .{ .status = 200, .body = okJson(resp, "rejected") };
+        if (rc == -1) return .{ .status = 403, .body = errJson(resp, "supervisor role required") };
+        if (rc == -2) return .{ .status = 404, .body = errJson(resp, "request_id not found") };
+        return .{ .status = 500, .body = errJson(resp, "reject failed") };
+    }
+
     return .{ .status = 404, .body = errJson(resp, "not implemented") };
 }
 

cartridges/local-coord-mcp/cartridge.json

@@ -44,6 +44,14 @@
           "context": {
             "description": "Optional per-window disambiguator (repo name, tty label). Alphanumeric/hyphen/underscore only, max 32 chars.",
             "type": "string"
+          },
+          "role": {
+            "description": "Optional requested role. supervisor is ALWAYS rejected here — promote via coord_promote_to_supervisor. Default derived from client_kind (claude->executor, others->supervised).",
+            "enum": [
+              "executor",
+              "supervised"
+            ],
+            "type": "string"
           }
         },
         "required": [
@@ -152,7 +160,145 @@
         "type": "object"
       },
       "name": "coord_status"
+    },
+    {
+      "description": "Promote this peer to the supervisor role. Requires the BOJ_SUPERVISOR_TOKEN env-var to be set on the server and the presented secret to match. At most one supervisor at a time. Intended for the Opus-tier Claude that holds the veto.",
+      "inputSchema": {
+        "properties": {
+          "secret": {
+            "description": "Must match BOJ_SUPERVISOR_TOKEN env var on the server",
+            "type": "string"
+          },
+          "token": {
+            "description": "Own session token from coord_register",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token",
+          "secret"
+        ],
+        "type": "object"
+      },
+      "name": "coord_promote_to_supervisor"
+    },
+    {
+      "description": "Send a message with a declared risk_tier. Tier 2+ from role=supervised peers is quarantined for supervisor review; everything else delivers directly. Returns status:quarantined + request_id when gated.",
+      "inputSchema": {
+        "properties": {
+          "message": {
+            "description": "Message content (typically an A2ML envelope per schemas/coord-messages.ncl)",
+            "type": "string"
+          },
+          "risk_tier": {
+            "description": "Declared risk tier 0-4 per the risk ladder",
+            "maximum": 4,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "target": {
+            "description": "Peer ID to send to, or '*' for broadcast",
+            "type": "string"
+          },
+          "token": {
+            "description": "Session token from coord_register",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token",
+          "target",
+          "message",
+          "risk_tier"
+        ],
+        "type": "object"
+      },
+      "name": "coord_send_gated"
+    },
+    {
+      "description": "List all currently quarantined messages awaiting supervisor decision. Supervisor role only.",
+      "inputSchema": {
+        "properties": {
+          "token": {
+            "description": "Supervisor session token",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "type": "object"
+      },
+      "name": "coord_review"
+    },
+    {
+      "description": "Read the full message body of a specific quarantined entry. Supervisor role only.",
+      "inputSchema": {
+        "properties": {
+          "request_id": {
+            "description": "Request ID from coord_review or coord_send_gated",
+            "type": "integer"
+          },
+          "token": {
+            "description": "Supervisor session token",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token",
+          "request_id"
+        ],
+        "type": "object"
+      },
+      "name": "coord_review_entry"
+    },
+    {
+      "description": "Approve a quarantined message — delivers to target and removes from queue. Supervisor role only.",
+      "inputSchema": {
+        "properties": {
+          "request_id": {
+            "description": "Request ID to approve",
+            "type": "integer"
+          },
+          "token": {
+            "description": "Supervisor session token",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token",
+          "request_id"
+        ],
+        "type": "object"
+      },
+      "name": "coord_approve"
+    },
+    {
+      "description": "Reject a quarantined message with a reason — removes from queue without delivery. Supervisor role only. Reason logged for audit.",
+      "inputSchema": {
+        "properties": {
+          "reason": {
+            "description": "Reason for rejection (surfaces in audit log)",
+            "type": "string"
+          },
+          "request_id": {
+            "description": "Request ID to reject",
+            "type": "integer"
+          },
+          "token": {
+            "description": "Supervisor session token",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token",
+          "request_id",
+          "reason"
+        ],
+        "type": "object"
+      },
+      "name": "coord_reject"
     }
   ],
-  "version": "0.2.0"
+  "version": "0.3.0"
 }