feat(local-coord-mcp): per-window peer ID disambiguation via context field

Running 3 Claude Code windows on one box previously collided in peer IDs like
claude-7f3a / claude-b2c1 / claude-4e9d — readable but nothing said which
window was which. Adding an optional context disambiguator so peer_id becomes
claude-7f3a@007-lang / claude-b2c1@aerie / claude-4e9d@eclipse-repos.

Changes:
- ffi: Peer gains context [32]u8 + context_len. New exports
  coord_set_context (alphanumeric/hyphen/underscore only, max 32, rollback
  on bad input) and coord_read_peer_context. coord_register clears context
  on slot reuse. Tests cover valid/invalid context + slot reuse cleanup +
  coord_find_peer_by_suffix happy/miss paths.
- adapter: coord_register accepts optional `context` JSON field; on
  validation failure the half-registered peer is deregistered so the caller
  can retry cleanly. renderPeerId + extractSuffix helpers keep peer_id
  format consistent across register/list/send. coord_list_peers returns
  context as a separate field AND embedded in peer_id. coord_send target
  parser handles both <kind>-<4hex> and <kind>-<4hex>@<context> forms.
- cartridge.ncl + cartridge.json: declare the new optional context field.
- mcp-bridge/lib/tools.js: surface context in coord_register input schema.
- version: 0.1.0 -> 0.2.0 (covers dispatch completion in 5d57daa + this).

Follows the supervision architecture in memory/project_coord_supervision_architecture.md.

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

Author: hyperpolymath

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

@@ -43,6 +43,28 @@ fn parseToken(token_hex: []const u8, out: *[16]u8) bool {
     return true;
 }
 
+/// Render a peer_id into the caller buffer. Format is `<kind>-<4hex>` when
+/// ctx is empty, `<kind>-<4hex>@<context>` when set. Returns the slice of
+/// buf actually used.
+fn renderPeerId(buf: []u8, kind_str: []const u8, suffix: []const u8, ctx: []const u8) ![]u8 {
+    if (ctx.len == 0) {
+        return try std.fmt.bufPrint(buf, "{s}-{s}", .{ kind_str, suffix });
+    }
+    return try std.fmt.bufPrint(buf, "{s}-{s}@{s}", .{ kind_str, suffix, ctx });
+}
+
+/// Extract the 4-char hex suffix from a target peer_id string. Format is
+/// `<kind>-<4hex>` or `<kind>-<4hex>@<context>`. Returns null if malformed.
+fn extractSuffix(target: []const u8) ?[]const u8 {
+    // Find the last '-' before any '@' — the 4 hex chars follow it.
+    const at_pos = std.mem.indexOfScalar(u8, target, '@') orelse target.len;
+    const left = target[0..at_pos];
+    const dash_pos = std.mem.lastIndexOfScalar(u8, left, '-') orelse return null;
+    const suffix = left[dash_pos + 1 ..];
+    if (suffix.len != 4) return null;
+    return suffix;
+}
+
 fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.Allocator) Response {
     if (std.mem.eql(u8, tool, "coord_register")) {
         const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
@@ -55,19 +77,37 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
         if (std.mem.eql(u8, kind_str, "gemini")) kind = 1;
         if (std.mem.eql(u8, kind_str, "copilot")) kind = 2;
 
+        // Optional context for per-window disambiguation.
+        const ctx_str: []const u8 = blk: {
+            const ctx_val = parsed.value.object.get("context") orelse break :blk "";
+            break :blk ctx_val.string;
+        };
+
         var token: [16]u8 = undefined;
         var suffix: [4]u8 = undefined;
         const idx = ffi.coord_register(kind, &token, &suffix);
         if (idx < 0) return .{ .status = 500, .body = errJson(resp, "registry full") };
 
+        if (ctx_str.len > 0) {
+            const set_rc = ffi.coord_set_context(&token, 16, ctx_str.ptr, @intCast(ctx_str.len));
+            if (set_rc < 0) {
+                // Rollback: deregister the half-registered peer so the caller can retry cleanly.
+                _ = ffi.coord_deregister(&token, 16);
+                return .{ .status = 400, .body = errJson(resp, "invalid context (alphanumeric/hyphen/underscore only, max 32 bytes)") };
+            }
+        }
+
         var token_hex: [32]u8 = undefined;
         const hex_chars = "0123456789abcdef";
         for (token, 0..) |b, i| {
             token_hex[i * 2] = hex_chars[b >> 4];
             token_hex[i * 2 + 1] = hex_chars[b & 0x0f];
         }
 
-        const body_out = std.fmt.bufPrint(resp, "{{\"success\":true,\"peer_id\":\"{s}-{s}\",\"token\":\"{s}\"}}", .{ kind_str, suffix, token_hex }) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+        var peer_id_buf: [96]u8 = undefined;
+        const peer_id = renderPeerId(&peer_id_buf, kind_str, &suffix, ctx_str) catch return .{ .status = 500, .body = errJson(resp, "peer_id render overflow") };
+
+        const body_out = std.fmt.bufPrint(resp, "{{\"success\":true,\"peer_id\":\"{s}\",\"token\":\"{s}\"}}", .{ peer_id, token_hex }) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
         return .{ .status = 200, .body = body_out };
     }
 
@@ -108,9 +148,16 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
             const status_len = ffi.coord_read_peer_status(i, &status_buf, @intCast(status_buf.len));
             const status_slice: []const u8 = if (status_len > 0) status_buf[0..@intCast(status_len)] else "";
 
+            var ctx_buf: [32]u8 = undefined;
+            const ctx_len = ffi.coord_read_peer_context(i, &ctx_buf, @intCast(ctx_buf.len));
+            const ctx_slice: []const u8 = if (ctx_len > 0) ctx_buf[0..@intCast(ctx_len)] else "";
+
+            var peer_id_buf: [96]u8 = undefined;
+            const peer_id = renderPeerId(&peer_id_buf, kindName(kind_val), suffix, ctx_slice) catch return .{ .status = 500, .body = errJson(resp, "peer_id render overflow") };
+
             if (written_idx > 0) w.writeAll(",") catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
-            std.fmt.format(w, "{{\"peer_id\":\"{s}-{s}\",\"kind\":\"{s}\",\"state\":\"{s}\",\"status\":\"{s}\"}}", .{
-                kindName(kind_val), suffix, kindName(kind_val), stateName(state), status_slice,
+            std.fmt.format(w, "{{\"peer_id\":\"{s}\",\"kind\":\"{s}\",\"state\":\"{s}\",\"context\":\"{s}\",\"status\":\"{s}\"}}", .{
+                peer_id, kindName(kind_val), stateName(state), ctx_slice, status_slice,
             }) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
             written_idx += 1;
         }
@@ -132,9 +179,8 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
         const target_str = target_val.string;
         var target_idx: i32 = -1;
         if (!std.mem.eql(u8, target_str, "*")) {
-            // Peer ID format: "<kind>-<suffix>". Extract suffix (last 4 chars).
-            if (target_str.len < 5) return .{ .status = 400, .body = errJson(resp, "invalid target format") };
-            const suffix = target_str[target_str.len - 4 ..];
+            // Peer ID format: "<kind>-<4hex>" or "<kind>-<4hex>@<context>".
+            const suffix = extractSuffix(target_str) orelse return .{ .status = 400, .body = errJson(resp, "invalid target format — expected <kind>-<4hex>[@<context>]") };
             target_idx = ffi.coord_find_peer_by_suffix(suffix.ptr);
             if (target_idx < 0) return .{ .status = 404, .body = errJson(resp, "target peer not found") };
         }

cartridges/local-coord-mcp/cartridge.json

@@ -28,7 +28,7 @@
   "tier": "Ayo",
   "tools": [
     {
-      "description": "Register this instance as a coordination peer. Returns a hybrid peer ID (e.g. claude-7f3a) and a session token for all subsequent calls.",
+      "description": "Register this instance as a coordination peer. Returns a peer ID and a session token for all subsequent calls. Optional `context` (alphanumeric + hyphen/underscore, max 32 bytes) disambiguates multiple windows of the same client_kind — peer_id becomes <kind>-<4hex>@<context>.",
       "inputSchema": {
         "properties": {
           "client_kind": {
@@ -40,6 +40,10 @@
               "custom"
             ],
             "type": "string"
+          },
+          "context": {
+            "description": "Optional per-window disambiguator (repo name, tty label). Alphanumeric/hyphen/underscore only, max 32 chars.",
+            "type": "string"
           }
         },
         "required": [
@@ -150,5 +154,5 @@
       "name": "coord_status"
     }
   ],
-  "version": "0.1.0"
+  "version": "0.2.0"
 }

cartridges/local-coord-mcp/cartridge.ncl

@@ -11,7 +11,7 @@
   spdx = "PMPL-1.0-or-later",
   copyright = "Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>",
   name = "local-coord-mcp",
-  version = "0.1.0",
+  version = "0.2.0",
   description = "Localhost multi-instance coordination — peer discovery, message passing, and task claiming for parallel AI sessions on the same machine",
   domain = "ai",
   tier = "Ayo",
@@ -35,7 +35,7 @@
   tools = [
     {
       name = "coord_register",
-      description = "Register this instance as a coordination peer. Returns a hybrid peer ID (e.g. claude-7f3a) and a session token for all subsequent calls.",
+      description = "Register this instance as a coordination peer. Returns a peer ID and a session token for all subsequent calls. Optional `context` (alphanumeric + hyphen/underscore, max 32 bytes) disambiguates multiple windows of the same client_kind — peer_id becomes <kind>-<4hex>@<context>.",
       inputSchema = {
         type = "object",
         properties = {
@@ -44,6 +44,10 @@
             description = "Client type: claude, gemini, copilot, or custom",
             enum = ["claude", "gemini", "copilot", "custom"],
           },
+          context = {
+            type = "string",
+            description = "Optional per-window disambiguator (repo name, tty label). Alphanumeric/hyphen/underscore only, max 32 chars.",
+          },
         },
         required = ["client_kind"],
       },

cartridges/local-coord-mcp/ffi/local_coord_ffi.zig

@@ -60,6 +60,12 @@ pub const ClaimResult = enum(c_int) {
 // Peer Registry
 // ═══════════════════════════════════════════════════════════════════════
 
+/// Per-window context disambiguator. Short label (e.g. repo name, tty-hash)
+/// appended to peer_id as `<kind>-<4hex>@<context>`. Optional — empty means
+/// the old `<kind>-<4hex>` form. Alphanumeric + hyphens only; enforced in
+/// coord_set_context.
+const MAX_CONTEXT: usize = 32;
+
 const Peer = struct {
     active: bool,
     kind: ClientKind,
@@ -75,6 +81,9 @@ const Peer = struct {
     // Status string
     status: [256]u8,
     status_len: u16,
+    // Context disambiguator (repo / tty / window label)
+    context: [MAX_CONTEXT]u8,
+    context_len: u8,
 };
 
 const empty_peer = Peer{
@@ -90,6 +99,8 @@ const empty_peer = Peer{
     .inbox_count = 0,
     .status = [_]u8{0} ** 256,
     .status_len = 0,
+    .context = [_]u8{0} ** MAX_CONTEXT,
+    .context_len = 0,
 };
 
 var peers: [MAX_PEERS]Peer = [_]Peer{empty_peer} ** MAX_PEERS;
@@ -211,6 +222,7 @@ pub export fn coord_register(kind: c_int, token_out: [*]u8, suffix_out: [*]u8) c
             p.inbox_tail = 0;
             p.inbox_count = 0;
             p.status_len = 0;
+            p.context_len = 0; // reset on slot reuse
 
             // Copy token and suffix to caller
             @memcpy(token_out[0..TOKEN_LEN], &p.token);
@@ -222,6 +234,51 @@ pub export fn coord_register(kind: c_int, token_out: [*]u8, suffix_out: [*]u8) c
     return -1; // registry full
 }
 
+/// Set a context disambiguator for this peer (repo name, tty hash, window
+/// label). Must be alphanumeric or hyphen, max MAX_CONTEXT bytes — anything
+/// else returns -2 and the existing context is untouched.
+pub export fn coord_set_context(
+    token_ptr: [*]const u8,
+    token_len: c_int,
+    ctx_ptr: [*]const u8,
+    ctx_len: c_int,
+) c_int {
+    mutex.lock();
+    defer mutex.unlock();
+
+    const idx = findPeerByToken(token_ptr, @intCast(token_len)) orelse return -1;
+    const clen: usize = @intCast(ctx_len);
+    if (clen > MAX_CONTEXT) return -2;
+
+    // Validate: alphanum + hyphen + underscore only.
+    var k: usize = 0;
+    while (k < clen) : (k += 1) {
+        const c = ctx_ptr[k];
+        const ok = (c >= '0' and c <= '9') or (c >= 'a' and c <= 'z') or
+            (c >= 'A' and c <= 'Z') or c == '-' or c == '_';
+        if (!ok) return -2;
+    }
+
+    if (clen > 0) @memcpy(peers[idx].context[0..clen], ctx_ptr[0..clen]);
+    peers[idx].context_len = @intCast(clen);
+    return 0;
+}
+
+/// Read a peer's context disambiguator. Writes up to out_cap bytes into out.
+/// Returns context length on success, 0 if unset, -1 if peer index out of
+/// range / inactive. Caller token is not required — context is broadcast-
+/// visible by design (it's how other peers identify which window this is).
+pub export fn coord_read_peer_context(peer_idx: c_int, out: [*]u8, out_cap: c_int) c_int {
+    mutex.lock();
+    defer mutex.unlock();
+    if (peer_idx < 0 or peer_idx >= MAX_PEERS) return -1;
+    const p = &peers[@intCast(peer_idx)];
+    if (!p.active) return -1;
+    const clen: usize = @min(@as(usize, p.context_len), @as(usize, @intCast(out_cap)));
+    if (clen > 0) @memcpy(out[0..clen], p.context[0..clen]);
+    return @intCast(clen);
+}
+
 /// Deregister a peer. Releases any claims it holds.
 pub export fn coord_deregister(token_ptr: [*]const u8, token_len: c_int) c_int {
     mutex.lock();
@@ -438,7 +495,7 @@ pub export fn boj_cartridge_name() [*:0]const u8 {
 }
 
 pub export fn boj_cartridge_version() [*:0]const u8 {
-    return "0.1.0";
+    return "0.2.0";
 }
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -636,6 +693,67 @@ test "broadcast message" {
     coord_reset();
 }
 
+test "set and read peer context" {
+    coord_reset();
+    var tok: [TOKEN_LEN]u8 = undefined;
+    var suf: [4]u8 = undefined;
+    const idx = coord_register(0, &tok, &suf);
+    try std.testing.expect(idx >= 0);
+
+    // Initially empty
+    var ctx_buf: [MAX_CONTEXT]u8 = undefined;
+    const empty = coord_read_peer_context(idx, &ctx_buf, @intCast(ctx_buf.len));
+    try std.testing.expectEqual(@as(c_int, 0), empty);
+
+    // Set a valid context
+    const ctx = "007-lang";
+    const set_ok = coord_set_context(&tok, TOKEN_LEN, ctx.ptr, @intCast(ctx.len));
+    try std.testing.expectEqual(@as(c_int, 0), set_ok);
+
+    // Read it back
+    const read_len = coord_read_peer_context(idx, &ctx_buf, @intCast(ctx_buf.len));
+    try std.testing.expectEqual(@as(c_int, @intCast(ctx.len)), read_len);
+    try std.testing.expect(std.mem.eql(u8, ctx_buf[0..ctx.len], ctx));
+
+    // Bad context (spaces) rejected
+    const bad = "has space";
+    const rc_bad = coord_set_context(&tok, TOKEN_LEN, bad.ptr, @intCast(bad.len));
+    try std.testing.expectEqual(@as(c_int, -2), rc_bad);
+
+    // Original context untouched after rejection
+    const reread = coord_read_peer_context(idx, &ctx_buf, @intCast(ctx_buf.len));
+    try std.testing.expectEqual(@as(c_int, @intCast(ctx.len)), reread);
+
+    // Slot reuse clears context
+    _ = coord_deregister(&tok, TOKEN_LEN);
+    var tok2: [TOKEN_LEN]u8 = undefined;
+    const idx2 = coord_register(0, &tok2, &suf);
+    // Same slot likely re-used; context should be zeroed
+    const after = coord_read_peer_context(idx2, &ctx_buf, @intCast(ctx_buf.len));
+    try std.testing.expectEqual(@as(c_int, 0), after);
+
+    coord_reset();
+}
+
+test "find peer by suffix" {
+    coord_reset();
+    var tok: [TOKEN_LEN]u8 = undefined;
+    var suf: [4]u8 = undefined;
+    const idx = coord_register(0, &tok, &suf);
+    try std.testing.expect(idx >= 0);
+
+    // Lookup should find it
+    const found = coord_find_peer_by_suffix(&suf);
+    try std.testing.expectEqual(@as(c_int, idx), found);
+
+    // Unknown suffix returns -1
+    const miss = [4]u8{ 'z', 'z', 'z', 'z' };
+    const not_found = coord_find_peer_by_suffix(&miss);
+    try std.testing.expectEqual(@as(c_int, -1), not_found);
+
+    coord_reset();
+}
+
 test "deregister releases claims" {
     coord_reset();
     var tok1: [TOKEN_LEN]u8 = undefined;

mcp-bridge/lib/tools.js

@@ -267,11 +267,12 @@ function buildToolList() {
   // Local coordination (localhost multi-instance AI coordination — local-coord-mcp cartridge)
   tools.push({
     name: "coord_register",
-    description: "Register this AI instance as a coordination peer on localhost. Returns a hybrid peer ID (e.g. claude-7f3a) and a session token for all subsequent calls. Loopback-only, never exposed beyond 127.0.0.1.",
+    description: "Register this AI instance as a coordination peer on localhost. Returns a peer ID and a session token for all subsequent calls. Loopback-only, never exposed beyond 127.0.0.1. Pass the optional `context` (repo name, tty tag, or similar) to disambiguate multiple windows of the same client_kind on one machine — peer_id becomes <kind>-<4hex>@<context> rather than just <kind>-<4hex>.",
     inputSchema: {
       type: "object",
       properties: {
         client_kind: { type: "string", enum: ["claude", "gemini", "copilot", "custom"], description: "Client type prefix for the peer ID" },
+        context: { type: "string", description: "Optional disambiguator, e.g. current repo name. Alphanumeric + hyphen/underscore, max 32 bytes. Absent = old <kind>-<4hex> form.", maxLength: 32 },
       },
       required: ["client_kind"],
     },