feat(local-coord-mcp): watchdog TTL enforcement (DD-20)

From P1 in docs/handover/COORD-MCP-TODO.md — closes the DD-20 watchdog
item. Bump cartridge version to 0.9.0.

Mechanism
---------
Each claim now carries `claimed_at_ms`, stamped at grant and refreshed
on heartbeat. `sweepExpiredClaims(now_ms)` walks active claims and
auto-releases any where `(now − claimed_at_ms) > TTL(holder.role)`.

TTLs (DD-20):
  apprentice  → 30 s
  journeyman  → 5 min
  master      → no watchdog (approver, not executor)

Sweep runs:
  - implicitly at the top of every coord_claim_task (contention is the
    natural moment abandoned work matters — the new caller benefits
    immediately from the release), and
  - explicitly via `coord_sweep_watchdog` for ops that want a polling
    tick independent of claim traffic.

New FFI + tools
---------------
  FFI:
    coord_progress(token, task)     — 0 OK, -1 bad token, -2 no claim,
                                       -3 not the holder
    coord_sweep_watchdog(token)     — released-count, -1 on bad token

  Adapter:
    coord_progress {token, task}
    coord_sweep_watchdog {token}
      → {released, ttl_apprentice_ms, ttl_journeyman_ms}

Durability
----------
  EventType.claim_progress = 17 — payload: claim_idx:u8 timestamp_ms:u64
  Replay sets claimed_at_ms from claim_progress events; claim_add alone
  restores a fresh TTL (old logs predate the field).

Audit
-----
Auto-releases emit an audit record (kind=3 AUTO_RELEASE) with the
claim index, holder, role, age_ms, and task name. DD-21's warn_drift
broadcast via Opus review is a separate P1 item.

Tests
-----
  watchdog: apprentice claim swept past 30s TTL
  watchdog: progress heartbeat keeps claim alive
  watchdog: journeyman gets 5min TTL, master never swept
  watchdog: progress rejected from non-holder
  watchdog: implicit sweep frees stale slot on contention

Tests rewind `claims[i].claimed_at_ms` directly (same-module private
access) to simulate elapsed time deterministically — no sleeps, no
flakiness.

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

https://claude.ai/code/session_01DobLJY3jgoso4M3z7xcZi8

Author: claude

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

@@ -818,6 +818,39 @@ fn dispatch(tool: []const u8, body: []const u8, resp: []u8, allocator: std.mem.A
         return .{ .status = 200, .body = resp[0..stream.pos] };
     }
 
+    if (std.mem.eql(u8, tool, "coord_progress")) {
+        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 task_val = parsed.value.object.get("task") orelse return .{ .status = 400, .body = errJson(resp, "missing task") };
+
+        var token: [16]u8 = undefined;
+        if (!parseToken(token_val.string, &token)) return .{ .status = 400, .body = errJson(resp, "invalid token hex") };
+
+        const task = task_val.string;
+        const rc = ffi.coord_progress(&token, 16, task.ptr, @intCast(task.len));
+        if (rc == 0) return .{ .status = 200, .body = okJson(resp, "heartbeat") };
+        if (rc == -1) return .{ .status = 401, .body = errJson(resp, "unauthenticated") };
+        if (rc == -2) return .{ .status = 404, .body = errJson(resp, "no active claim for this task") };
+        if (rc == -3) return .{ .status = 403, .body = errJson(resp, "caller is not the claim holder") };
+        return .{ .status = 500, .body = errJson(resp, "progress failed") };
+    }
+
+    if (std.mem.eql(u8, tool, "coord_sweep_watchdog")) {
+        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 rc = ffi.coord_sweep_watchdog(&token, 16);
+        if (rc < 0) return .{ .status = 401, .body = errJson(resp, "unauthenticated") };
+        const body_out = std.fmt.bufPrint(resp,
+            "{{\"success\":true,\"released\":{d},\"ttl_apprentice_ms\":30000,\"ttl_journeyman_ms\":300000}}",
+            .{rc}) catch return .{ .status = 500, .body = errJson(resp, "buffer overflow") };
+        return .{ .status = 200, .body = body_out };
+    }
+
     if (std.mem.eql(u8, tool, "coord_health")) {
         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

@@ -589,7 +589,44 @@
         "type": "object"
       },
       "name": "coord_health"
+    },
+    {
+      "description": "Heartbeat for a held claim — resets the watchdog TTL (DD-20). Apprentice TTL is 30 s, journeyman 5 min, master no watchdog. Long-running work should ping this periodically so the server doesn't auto-release the claim.",
+      "inputSchema": {
+        "properties": {
+          "task": {
+            "description": "Task identifier previously claimed via coord_claim_task",
+            "type": "string"
+          },
+          "token": {
+            "description": "Session token from coord_register",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token",
+          "task"
+        ],
+        "type": "object"
+      },
+      "name": "coord_progress"
+    },
+    {
+      "description": "Explicit watchdog sweep — release any claim whose holder has missed its role-based TTL. The sweep also runs implicitly at the top of every coord_claim_task, so this tool is only needed by ops wanting an external tick.",
+      "inputSchema": {
+        "properties": {
+          "token": {
+            "description": "Session token from coord_register — any active peer may invoke.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "type": "object"
+      },
+      "name": "coord_sweep_watchdog"
     }
   ],
-  "version": "0.8.0"
+  "version": "0.9.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.8.0",
+  version = "0.9.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",
@@ -295,6 +295,29 @@
         required = ["token", "peer_id"],
       },
     },
+    {
+      name = "coord_progress",
+      description = "Heartbeat for a held claim — resets the watchdog TTL (DD-20). Apprentice TTL is 30 s, journeyman 5 min, master no watchdog. Long-running work should ping this periodically so the server doesn't auto-release the claim.",
+      inputSchema = {
+        type = "object",
+        properties = {
+          token = { type = "string", description = "Session token from coord_register" },
+          task = { type = "string", description = "Task identifier previously claimed via coord_claim_task" },
+        },
+        required = ["token", "task"],
+      },
+    },
+    {
+      name = "coord_sweep_watchdog",
+      description = "Explicit watchdog sweep — release any claim whose holder has missed its role-based TTL. The sweep also runs implicitly at the top of every coord_claim_task, so this tool is only needed by ops wanting an external tick.",
+      inputSchema = {
+        type = "object",
+        properties = {
+          token = { type = "string", description = "Session token from coord_register — any active peer may invoke." },
+        },
+        required = ["token"],
+      },
+    },
     {
       name = "coord_health",
       description = "Read-only snapshot of coord-mcp state: active peer count (with per-kind / per-role breakdown), pending quarantine depth, active claims, track-record fill, and recent reject counts with cooldown flags. Lets other tooling monitor coord health without walking every export individually.",

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

@@ -56,6 +56,8 @@ pub const EventType = enum(u16) {
     peer_variant_set = 15,
     // Task #34 — capability advertisement (class / tier / prover_strengths).
     peer_capabilities_set = 16,
+    // DD-20 — watchdog heartbeat for a claim.
+    claim_progress = 17,
     _,
 };
 
@@ -313,6 +315,14 @@ pub fn logClaimRel(claim_idx: u8) void {
     append(.claim_rel, &[_]u8{claim_idx});
 }
 
+/// CLAIM_PROGRESS — claim_idx:u8 timestamp_ms:u64 (9B). DD-20 watchdog.
+pub fn logClaimProgress(claim_idx: u8, timestamp_ms: u64) void {
+    var buf: [9]u8 = undefined;
+    buf[0] = claim_idx;
+    std.mem.writeInt(u64, buf[1..9], timestamp_ms, .little);
+    append(.claim_progress, &buf);
+}
+
 /// QUAR_ADD — request_id:u32 sender_idx:u8 target_idx:i8 risk_tier:u8
 ///            msg_len:u16 msg[msg_len]
 pub fn logQuarAdd(request_id: u32, sender_idx: u8, target_idx: i8, risk_tier: u8, msg: []const u8) void {
@@ -478,6 +488,15 @@ pub fn decodeClaimAdd(p: []const u8) ?ClaimAdd {
     return .{ .claim_idx = p[0], .holder_idx = p[1], .task = p[3 .. 3 + n] };
 }
 
+pub const ClaimProgress = struct { claim_idx: u8, timestamp_ms: u64 };
+pub fn decodeClaimProgress(p: []const u8) ?ClaimProgress {
+    if (p.len < 9) return null;
+    return .{
+        .claim_idx = p[0],
+        .timestamp_ms = std.mem.readInt(u64, p[1..9], .little),
+    };
+}
+
 pub const QuarAdd = struct {
     request_id: u32,
     sender_idx: u8,