feat(local-coord-mcp): reassignment suggestion engine (Task #14)

Engine emits candidate envelopes INTO the quarantine (server-origin,
sender_idx=0xFE sentinel) for supervisor review via the existing
coord_review + coord_approve / coord_reject flow. Never auto-modifies
affinities.

New FFI + tools:
  coord_set_declared_affinities(token, tags_csv) — self-reported strengths
  coord_scan_suggestions(token) — runs scan, enqueues candidates

Scanner rules:
  overclaim: avg_confidence >= 80% AND effective_affinity < 30%   -> op_kind=fyi
  promote:   effective_affinity >= 70% AND tag not declared      -> op_kind=fyi
  remove:    effective_affinity <= 20% AND attempts >= 5         -> op_kind=clarify

coord_report_outcome now takes an optional confidence_pct (8th arg,
-1 for unset). Log format extends track_update with a trailing
confidence byte (backward-compatible via length-check). coord_register
accepts an optional declared_affinities array.

coord_review adapter output adds an "origin" field
("peer" | "server-engine") so supervisors can tell engine-synthesised
suggestions from real peer messages.

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

Author: hyperpolymath

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

@@ -109,6 +109,30 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
             }
         }
 
+        // Optional declared_affinities — an array of tag strings that the
+        // peer self-reports as strengths. Stored as a CSV internally so the
+        // reassignment engine (Task #14) can diff against track record.
+        if (parsed.value.object.get("declared_affinities")) |decl_val| {
+            if (decl_val == .array) {
+                var csv_buf: [256]u8 = undefined;
+                var csv_len: usize = 0;
+                for (decl_val.array.items) |item| {
+                    if (item != .string) continue;
+                    const s = item.string;
+                    if (csv_len > 0 and csv_len < csv_buf.len) {
+                        csv_buf[csv_len] = ',';
+                        csv_len += 1;
+                    }
+                    const to_copy: usize = @min(s.len, csv_buf.len - csv_len);
+                    if (to_copy > 0) @memcpy(csv_buf[csv_len .. csv_len + to_copy], s[0..to_copy]);
+                    csv_len += to_copy;
+                }
+                if (csv_len > 0) {
+                    _ = ffi.coord_set_declared_affinities(&token, 16, &csv_buf, @intCast(csv_len));
+                }
+            }
+        }
+
         var token_hex: [32]u8 = undefined;
         const hex_chars = "0123456789abcdef";
         for (token, 0..) |b, i| {
@@ -374,8 +398,11 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
             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,
+            // sender_idx = 0xFE indicates a server-origin (engine-generated)
+            // entry from coord_scan_suggestions (Task #14).
+            const origin: []const u8 = if (sender_idx == 0xFE) "server-engine" else "peer";
+            std.fmt.format(w, "{{\"request_id\":{d},\"origin\":\"{s}\",\"sender_idx\":{d},\"target_idx\":{d},\"risk_tier\":{d},\"msg_len\":{d},\"preview\":\"{s}\"}}", .{
+                rid, origin, 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") };
@@ -429,6 +456,15 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
             const v = parsed.value.object.get("duration_ms") orelse break :blk 0;
             break :blk v.integer;
         };
+        // confidence is optional; accept 0..1 float or 0..100 integer, -1 if absent.
+        const confidence: i32 = blk: {
+            const v = parsed.value.object.get("confidence") orelse break :blk -1;
+            switch (v) {
+                .float => |f| break :blk @intFromFloat(@min(@max(f * 100.0, 0.0), 100.0)),
+                .integer => |i| break :blk @intCast(i),
+                else => break :blk -1,
+            }
+        };
 
         var token: [16]u8 = undefined;
         if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
@@ -450,13 +486,57 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
 
         const tier: i32 = @intCast(tier_val.integer);
         const duration: i32 = @intCast(duration_val);
-        const rc = ffi.coord_report_outcome(&token, 16, tag_str.ptr, @intCast(tag_str.len), outcome, duration, tier);
+        const rc = ffi.coord_report_outcome(&token, 16, tag_str.ptr, @intCast(tag_str.len), outcome, duration, tier, confidence);
         if (rc == 0) return .{ .status = 200, .body = okJson(resp, "recorded") };
         if (rc == -1) return .{ .status = 401, .body = errJson(resp, "unauthenticated") };
         if (rc == -2) return .{ .status = 400, .body = errJson(resp, "invalid args") };
         return .{ .status = 500, .body = errJson(resp, "report failed") };
     }
 
+    if (std.mem.eql(u8, tool, "coord_set_declared_affinities")) {
+        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 tags_val = parsed.value.object.get("tags") orelse return .{ .status = 400, .body = errJson(resp, "missing tags") };
+        if (tags_val != .array) return .{ .status = 400, .body = errJson(resp, "tags must be an array of strings") };
+
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        var csv_buf: [256]u8 = undefined;
+        var csv_len: usize = 0;
+        for (tags_val.array.items) |item| {
+            if (item != .string) continue;
+            const s = item.string;
+            if (csv_len > 0 and csv_len < csv_buf.len) {
+                csv_buf[csv_len] = ',';
+                csv_len += 1;
+            }
+            const to_copy: usize = @min(s.len, csv_buf.len - csv_len);
+            if (to_copy > 0) @memcpy(csv_buf[csv_len .. csv_len + to_copy], s[0..to_copy]);
+            csv_len += to_copy;
+        }
+
+        const rc = ffi.coord_set_declared_affinities(&token, 16, &csv_buf, @intCast(csv_len));
+        if (rc == 0) return .{ .status = 200, .body = okJson(resp, "declared") };
+        if (rc == -1) return .{ .status = 401, .body = errJson(resp, "unauthenticated") };
+        if (rc == -2) return .{ .status = 400, .body = errJson(resp, "declared affinities CSV too long") };
+        return .{ .status = 500, .body = errJson(resp, "set failed") };
+    }
+
+    if (std.mem.eql(u8, tool, "coord_scan_suggestions")) {
+        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") };
+
+        const n = ffi.coord_scan_suggestions(&token, 16);
+        if (n == -1) return .{ .status = 401, .body = errJson(resp, "unauthenticated") };
+        const body_out = std.fmt.bufPrint(resp, "{{\"success\":true,\"suggestions_queued\":{d},\"hint\":\"use coord_review to inspect, coord_approve/coord_reject to act\"}}", .{n}) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+        return .{ .status = 200, .body = body_out };
+    }
+
     if (std.mem.eql(u8, tool, "coord_get_affinities")) {
         const parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch return .{ .status = 400, .body = errJson(resp, "invalid json") };
         defer parsed.deinit();

cartridges/local-coord-mcp/cartridge.json

@@ -28,7 +28,7 @@
   "tier": "Ayo",
   "tools": [
     {
-      "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>.",
+      "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. Optional `declared_affinities` is an array of tag names the peer self-reports as strengths — feeds the reassignment engine (Task #14).",
       "inputSchema": {
         "properties": {
           "client_kind": {
@@ -45,6 +45,13 @@
             "description": "Optional per-window disambiguator (repo name, tty label). Alphanumeric/hyphen/underscore only, max 32 chars.",
             "type": "string"
           },
+          "declared_affinities": {
+            "description": "Optional array of tag strings the peer claims as strengths (e.g. ['proof-analysis', 'supervision']). Feeds Task #14 reassignment engine.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
           "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": [
@@ -325,9 +332,15 @@
       "name": "coord_reject"
     },
     {
-      "description": "Report the outcome of a claim or attempted op against an affinity tag. Aggregated into the track record keyed on client_kind (survives peer restart). Feeds effective_affinity + reassignment suggestions.",
+      "description": "Report the outcome of a claim or attempted op against an affinity tag. Aggregated into the track record keyed on client_kind (survives peer restart). Feeds effective_affinity + reassignment suggestions. Task #14: optional `confidence` 0.0-1.0 feeds the overclaim detector.",
       "inputSchema": {
         "properties": {
+          "confidence": {
+            "description": "Self-assessed confidence at claim time (0.0-1.0). Feeds overclaim detection.",
+            "maximum": 1,
+            "minimum": 0,
+            "type": "number"
+          },
           "duration_ms": {
             "description": "Wall-time duration of the op in ms (optional, default 0)",
             "minimum": 0,
@@ -382,7 +395,47 @@
         "type": "object"
       },
       "name": "coord_get_affinities"
+    },
+    {
+      "description": "Set this peer's declared affinities (self-reported strengths). Replaces any existing list. Task #14 diffs against effective_affinity to detect overclaim/promote/remove outliers.",
+      "inputSchema": {
+        "properties": {
+          "tags": {
+            "description": "Array of tag names (e.g. ['proof-analysis', 'supervision']). Serialised as CSV internally (max 256 bytes total).",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "token": {
+            "description": "Session token from coord_register",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token",
+          "tags"
+        ],
+        "type": "object"
+      },
+      "name": "coord_set_declared_affinities"
+    },
+    {
+      "description": "Run the reassignment-suggestion scanner (Task #14). Scans track-record aggregates vs declared_affinities; enqueues candidate envelopes in the quarantine for supervisor review. Rules: overclaim (high avg_confidence + low effective_affinity), promote (high effective_affinity on undeclared tag), remove (low effective_affinity with >=5 attempts). Supervisor reviews via coord_review / approves via coord_approve / rejects via coord_reject — never auto-modifies.",
+      "inputSchema": {
+        "properties": {
+          "token": {
+            "description": "Session token from coord_register",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "type": "object"
+      },
+      "name": "coord_scan_suggestions"
     }
   ],
-  "version": "0.4.0"
+  "version": "0.5.0"
 }

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

@@ -327,7 +327,10 @@ pub fn logAudit(kind: u8, detail: []const u8) void {
 }
 
 /// TRACK_UPDATE — client_kind:u8 outcome:u8 risk_tier:u8 duration_ms:u32
-///                timestamp_ms:u64 tag_len:u8 tag[tag_len]
+///                timestamp_ms:u64 tag_len:u8 tag[tag_len] confidence_pct:u8
+///
+/// confidence_pct is 0..100, or 255 = unset. Always the last byte so old
+/// decoders (16+tag.len) can still parse the leading fields.
 ///
 /// DD-29: keyed on client_kind (not peer_id/suffix) so the track record
 /// survives peer crash+restart — a fresh peer of the same client_kind
@@ -339,17 +342,19 @@ pub fn logTrackUpdate(
     duration_ms: u32,
     timestamp_ms: u64,
     tag: []const u8,
+    confidence_pct: u8,
 ) void {
     if (tag.len > 64) return;
-    var buf: [16 + 64]u8 = undefined;
+    var buf: [17 + 64]u8 = undefined;
     buf[0] = client_kind;
     buf[1] = outcome;
     buf[2] = risk_tier;
     std.mem.writeInt(u32, buf[3..7], duration_ms, .little);
     std.mem.writeInt(u64, buf[7..15], timestamp_ms, .little);
     buf[15] = @intCast(tag.len);
     if (tag.len > 0) @memcpy(buf[16 .. 16 + tag.len], tag);
-    append(.track_update, buf[0 .. 16 + tag.len]);
+    buf[16 + tag.len] = confidence_pct;
+    append(.track_update, buf[0 .. 17 + tag.len]);
 }
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -463,18 +468,21 @@ pub const TrackUpdate = struct {
     duration_ms: u32,
     timestamp_ms: u64,
     tag: []const u8,
+    confidence_pct: u8, // 255 = unset (old event or never reported)
 };
 pub fn decodeTrackUpdate(p: []const u8) ?TrackUpdate {
     if (p.len < 16) return null;
     const n: usize = p[15];
     if (p.len < 16 + n) return null;
+    const conf: u8 = if (p.len >= 17 + n) p[16 + n] else 255;
     return .{
         .client_kind = p[0],
         .outcome = p[1],
         .risk_tier = p[2],
         .duration_ms = std.mem.readInt(u32, p[3..7], .little),
         .timestamp_ms = std.mem.readInt(u64, p[7..15], .little),
         .tag = p[16 .. 16 + n],
+        .confidence_pct = conf,
     };
 }
 
@@ -611,7 +619,7 @@ test "replay decodes every event type" {
     logQuarApprove(42);
     logQuarReject(43, "confabulated path");
     logAudit(1, "tier3-from-supervised");
-    logTrackUpdate(0, 1, 2, 1234, 1_700_000_000_000, "proof-analysis");
+    logTrackUpdate(0, 1, 2, 1234, 1_700_000_000_000, "proof-analysis", 85);
     logPeerRemove(0);
     close();
 
@@ -642,4 +650,5 @@ test "replay decodes every event type" {
     try std.testing.expectEqual(@as(u32, 1234), tr.duration_ms);
     try std.testing.expectEqual(@as(u64, 1_700_000_000_000), tr.timestamp_ms);
     try std.testing.expectEqualSlices(u8, "proof-analysis", tr.tag);
+    try std.testing.expectEqual(@as(u8, 85), tr.confidence_pct);
 }