switchman-dev 0.1.0 → 0.1.2

package/src/mcp/server.js

@@ -11,6 +11,7 @@
  *   switchman_task_claim   — claim files for a task (conflict-safe)
  *   switchman_task_done    — mark a task complete + release file claims
  *   switchman_task_fail    — mark a task failed + release file claims
+ *   switchman_lease_heartbeat — refresh a lease heartbeat
  *   switchman_scan         — scan all worktrees for conflicts right now
  *   switchman_status       — full system overview (tasks, claims, worktrees)
  */
@@ -23,12 +24,15 @@ import { findRepoRoot } from '../core/git.js';
 import {
   openDb,
   createTask,
-  assignTask,
+  startTaskLease,
   completeTask,
   failTask,
   listTasks,
-  getTask,
   getNextPendingTask,
+  listLeases,
+  getActiveLeaseForTask,
+  heartbeatLease,
+  getStaleLeases,
   claimFiles,
   releaseFileClaims,
   getActiveFileClaims,
@@ -95,7 +99,10 @@ Returns JSON:
       "description": string | null,
       "priority": number,    // 1-10, higher = more urgent
       "worktree": string,
-      "status": "in_progress"
+      "status": "in_progress",
+      "lease_id": string,    // Active lease/session ID for the task
+      "lease_status": "active",
+      "heartbeat_at": string
     } | null                 // null when queue is empty
   }
 
@@ -124,17 +131,27 @@ Examples:
         return toolOk(JSON.stringify({ task: null }), { task: null });
       }
 
-      const assigned = assignTask(db, task.id, worktree, agent ?? null);
-      db.close();
+      const lease = startTaskLease(db, task.id, worktree, agent ?? null);
 
-      if (!assigned) {
+      if (!lease) {
+        db.close();
         // Race condition: another agent grabbed it first — try again
         return toolOk(
           JSON.stringify({ task: null, message: 'Task was claimed by another agent. Call switchman_task_next again.' }),
         );
       }
 
-      const result = { task: { ...task, worktree, status: 'in_progress' } };
+      db.close();
+      const result = {
+        task: {
+          ...task,
+          worktree,
+          status: 'in_progress',
+          lease_id: lease.id,
+          lease_status: lease.status,
+          heartbeat_at: lease.heartbeat_at,
+        },
+      };
       return toolOk(JSON.stringify(result, null, 2), result);
     } catch (err) {
       return toolError(`${err.message}. Make sure switchman is initialised in this repo (run 'switchman init').`);
@@ -210,16 +227,20 @@ Args:
   - worktree (string): Your git worktree name
   - files (array of strings): File paths you plan to edit, relative to repo root (e.g. ["src/auth/login.js", "tests/auth.test.js"])
   - agent (string, optional): Agent identifier for logging
+  - lease_id (string, optional): Active lease ID returned by switchman_task_next
   - force (boolean, optional): If true, claim even if conflicts exist (default: false)
 
 Returns JSON:
   {
+    "lease_id": string,
     "claimed": string[],     // Files successfully claimed
     "conflicts": [           // Files already claimed by other worktrees
       {
         "file": string,
+        "claimed_by_task_id": string,
         "claimed_by_worktree": string,
-        "claimed_by_task": string
+        "claimed_by_task": string,
+        "claimed_by_lease_id": string | null
       }
     ],
     "safe_to_proceed": boolean   // true if no conflicts (or force=true)
@@ -234,6 +255,7 @@ Examples:
       worktree: z.string().min(1).describe('Your git worktree name'),
       files: z.array(z.string().min(1)).min(1).max(500).describe('File paths to claim, relative to repo root'),
       agent: z.string().optional().describe('Agent identifier for logging'),
+      lease_id: z.string().optional().describe('Optional lease ID returned by switchman_task_next'),
       force: z.boolean().default(false).describe('Claim even if conflicts exist (use with caution)'),
     }),
     annotations: {
@@ -243,9 +265,10 @@ Examples:
       openWorldHint: false,
     },
   },
-  async ({ task_id, worktree, files, agent, force }) => {
+  async ({ task_id, worktree, files, agent, lease_id, force }) => {
+    let db;
     try {
-      const { db } = getContext();
+      ({ db } = getContext());
 
       // Check for conflicts first
       const conflicts = checkFileConflicts(db, files, worktree);
@@ -256,8 +279,10 @@ Examples:
           claimed: [],
           conflicts: conflicts.map((c) => ({
             file: c.file,
+            claimed_by_task_id: c.claimedBy.task_id,
             claimed_by_worktree: c.claimedBy.worktree,
             claimed_by_task: c.claimedBy.task_title,
+            claimed_by_lease_id: c.claimedBy.lease_id ?? null,
           })),
           safe_to_proceed: false,
         };
@@ -268,15 +293,20 @@ Examples:
         );
       }
 
-      claimFiles(db, task_id, worktree, files, agent ?? null);
-      db.close();
+      const lease = claimFiles(db, task_id, worktree, files, agent ?? null);
+      if (lease_id && lease.id !== lease_id) {
+        return toolError(`Task ${task_id} is active under lease ${lease.id}, not ${lease_id}.`);
+      }
 
       const result = {
+        lease_id: lease.id,
         claimed: files,
         conflicts: conflicts.map((c) => ({
           file: c.file,
+          claimed_by_task_id: c.claimedBy.task_id,
           claimed_by_worktree: c.claimedBy.worktree,
           claimed_by_task: c.claimedBy.task_title,
+          claimed_by_lease_id: c.claimedBy.lease_id ?? null,
         })),
         safe_to_proceed: true,
       };
@@ -286,6 +316,8 @@ Examples:
       );
     } catch (err) {
       return toolError(err.message);
+    } finally {
+      db?.close();
     }
   },
 );
@@ -302,15 +334,18 @@ Call this when you have finished your implementation and committed your changes.
 
 Args:
   - task_id (string): The task ID to complete
+  - lease_id (string, optional): Active lease ID returned by switchman_task_next
 
 Returns JSON:
   {
     "task_id": string,
+    "lease_id": string | null,
     "status": "done",
     "files_released": true
   }`,
     inputSchema: z.object({
       task_id: z.string().min(1).describe('The task ID to mark complete'),
+      lease_id: z.string().optional().describe('Optional lease ID returned by switchman_task_next'),
     }),
     annotations: {
       readOnlyHint: false,
@@ -319,14 +354,19 @@ Returns JSON:
       openWorldHint: false,
     },
   },
-  async ({ task_id }) => {
+  async ({ task_id, lease_id }) => {
     try {
       const { db } = getContext();
+      const activeLease = getActiveLeaseForTask(db, task_id);
+      if (lease_id && activeLease && activeLease.id !== lease_id) {
+        db.close();
+        return toolError(`Task ${task_id} is active under lease ${activeLease.id}, not ${lease_id}.`);
+      }
       completeTask(db, task_id);
       releaseFileClaims(db, task_id);
       db.close();
 
-      const result = { task_id, status: 'done', files_released: true };
+      const result = { task_id, lease_id: activeLease?.id ?? lease_id ?? null, status: 'done', files_released: true };
       return toolOk(JSON.stringify(result, null, 2), result);
     } catch (err) {
       return toolError(err.message);
@@ -346,17 +386,20 @@ Call this if you cannot complete the task — the task will be visible in the qu
 
 Args:
   - task_id (string): The task ID to mark as failed
+  - lease_id (string, optional): Active lease ID returned by switchman_task_next
   - reason (string): Brief explanation of why the task failed
 
 Returns JSON:
   {
     "task_id": string,
+    "lease_id": string | null,
     "status": "failed",
     "reason": string,
     "files_released": true
   }`,
     inputSchema: z.object({
       task_id: z.string().min(1).describe('The task ID to mark as failed'),
+      lease_id: z.string().optional().describe('Optional lease ID returned by switchman_task_next'),
       reason: z.string().min(1).max(500).describe('Brief explanation of why the task failed'),
     }),
     annotations: {
@@ -366,14 +409,74 @@ Returns JSON:
       openWorldHint: false,
     },
   },
-  async ({ task_id, reason }) => {
+  async ({ task_id, lease_id, reason }) => {
     try {
       const { db } = getContext();
+      const activeLease = getActiveLeaseForTask(db, task_id);
+      if (lease_id && activeLease && activeLease.id !== lease_id) {
+        db.close();
+        return toolError(`Task ${task_id} is active under lease ${activeLease.id}, not ${lease_id}.`);
+      }
       failTask(db, task_id, reason);
       releaseFileClaims(db, task_id);
       db.close();
 
-      const result = { task_id, status: 'failed', reason, files_released: true };
+      const result = { task_id, lease_id: activeLease?.id ?? lease_id ?? null, status: 'failed', reason, files_released: true };
+      return toolOk(JSON.stringify(result, null, 2), result);
+    } catch (err) {
+      return toolError(err.message);
+    }
+  },
+);
+
+// ── switchman_lease_heartbeat ─────────────────────────────────────────────────
+
+server.registerTool(
+  'switchman_lease_heartbeat',
+  {
+    title: 'Refresh Lease Heartbeat',
+    description: `Refreshes the heartbeat timestamp for an active lease.
+
+Call this periodically while an agent is still working on a task so stale-session reaping does not recycle the task prematurely.
+
+Args:
+  - lease_id (string): Active lease ID returned by switchman_task_next
+  - agent (string, optional): Agent identifier to attach to the refreshed lease
+
+Returns JSON:
+  {
+    "lease_id": string,
+    "task_id": string,
+    "worktree": string,
+    "heartbeat_at": string
+  }`,
+    inputSchema: z.object({
+      lease_id: z.string().min(1).describe('Active lease ID returned by switchman_task_next'),
+      agent: z.string().optional().describe('Agent identifier for logging'),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  async ({ lease_id, agent }) => {
+    try {
+      const { db } = getContext();
+      const lease = heartbeatLease(db, lease_id, agent ?? null);
+      db.close();
+
+      if (!lease) {
+        return toolError(`Lease ${lease_id} was not found or is no longer active.`);
+      }
+
+      const result = {
+        lease_id: lease.id,
+        task_id: lease.task_id,
+        worktree: lease.worktree,
+        heartbeat_at: lease.heartbeat_at,
+      };
       return toolOk(JSON.stringify(result, null, 2), result);
     } catch (err) {
       return toolError(err.message);
@@ -479,13 +582,17 @@ Returns JSON:
       "in_progress": number,
       "done": number,
       "failed": number,
-      "active": [{ "id": string, "title": string, "worktree": string, "priority": number }]
+      "active": [{ "id": string, "title": string, "worktree": string, "priority": number, "lease_id": string | null }]
     },
     "file_claims": {
       "total_active": number,
-      "by_worktree": { [worktree: string]: string[] }   // worktree -> files
+      "by_worktree": { [worktree: string]: { "file_path": string, "task_id": string, "lease_id": string | null }[] }
+    },
+    "leases": {
+      "active": [{ "id": string, "task_id": string, "worktree": string, "agent": string | null, "heartbeat_at": string }],
+      "stale": [{ "id": string, "task_id": string, "worktree": string, "heartbeat_at": string }]
     },
-    "worktrees": [{ "name": string, "branch": string, "agent": string | null, "status": string }],
+    "worktrees": [{ "name": string, "branch": string, "agent": string | null, "status": string, "active_lease_id": string | null }],
     "repo_root": string
   }`,
     inputSchema: z.object({}),
@@ -503,14 +610,27 @@ Returns JSON:
       const tasks = listTasks(db);
       const claims = getActiveFileClaims(db);
       const worktrees = listWorktrees(db);
+      const leases = listLeases(db);
+      const staleLeases = getStaleLeases(db);
       db.close();
 
       const byWorktree = {};
       for (const c of claims) {
         if (!byWorktree[c.worktree]) byWorktree[c.worktree] = [];
-        byWorktree[c.worktree].push(c.file_path);
+        byWorktree[c.worktree].push({
+          file_path: c.file_path,
+          task_id: c.task_id,
+          lease_id: c.lease_id ?? null,
+        });
       }
 
+      const activeLeaseByTask = new Map(
+        leases.filter((lease) => lease.status === 'active').map((lease) => [lease.task_id, lease]),
+      );
+      const activeLeaseByWorktree = new Map(
+        leases.filter((lease) => lease.status === 'active').map((lease) => [lease.worktree, lease]),
+      );
+
       const result = {
         tasks: {
           pending: tasks.filter((t) => t.status === 'pending').length,
@@ -519,17 +639,45 @@ Returns JSON:
           failed: tasks.filter((t) => t.status === 'failed').length,
           active: tasks
             .filter((t) => t.status === 'in_progress')
-            .map((t) => ({ id: t.id, title: t.title, worktree: t.worktree, priority: t.priority })),
+            .map((t) => ({
+              id: t.id,
+              title: t.title,
+              worktree: t.worktree,
+              priority: t.priority,
+              lease_id: activeLeaseByTask.get(t.id)?.id ?? null,
+            })),
         },
         file_claims: {
           total_active: claims.length,
           by_worktree: byWorktree,
+          claims: claims.map((claim) => ({
+            file_path: claim.file_path,
+            worktree: claim.worktree,
+            task_id: claim.task_id,
+            lease_id: claim.lease_id ?? null,
+          })),
+        },
+        leases: {
+          active: leases.filter((lease) => lease.status === 'active').map((lease) => ({
+            id: lease.id,
+            task_id: lease.task_id,
+            worktree: lease.worktree,
+            agent: lease.agent ?? null,
+            heartbeat_at: lease.heartbeat_at,
+          })),
+          stale: staleLeases.map((lease) => ({
+            id: lease.id,
+            task_id: lease.task_id,
+            worktree: lease.worktree,
+            heartbeat_at: lease.heartbeat_at,
+          })),
         },
         worktrees: worktrees.map((wt) => ({
           name: wt.name,
           branch: wt.branch,
           agent: wt.agent ?? null,
           status: wt.status,
+          active_lease_id: activeLeaseByWorktree.get(wt.name)?.id ?? null,
         })),
         repo_root: repoRoot,
       };
@@ -552,4 +700,4 @@ async function main() {
 main().catch((err) => {
   process.stderr.write(`switchman MCP server fatal error: ${err.message}\n`);
   process.exit(1);
-});
+});

package/CLAUDE.md

@@ -1,98 +0,0 @@
-# Switchman Agent Instructions
-
-This repository uses **Switchman** to coordinate parallel AI coding agents.
-You MUST follow these instructions every session to avoid conflicting with other agents.
-
----
-
-## Your worktree
-
-Find your worktree name by running:
-```bash
-git worktree list
-```
-The path that matches your current directory is your worktree. Use the last path segment as your worktree name (e.g. `/projects/myapp-feature-auth` → `feature-auth`). The main repo root is always named `main`.
-
----
-
-## Required workflow — follow this every session
-
-### 1. Start of session — get your task
-
-Call the `switchman_task_next` MCP tool with your worktree name:
-```
-switchman_task_next({ worktree: "<your-worktree-name>", agent: "claude-code" })
-```
-
-- If `task` is `null` — the queue is empty. Ask the user what to work on, or stop.
-- If you receive a task — note the `task.id`. You'll need it in the next steps.
-
-### 2. Before editing any files — claim them
-
-Call `switchman_task_claim` with every file you plan to edit **before you edit them**:
-```
-switchman_task_claim({
-  task_id: "<task-id>",
-  worktree: "<your-worktree-name>",
-  files: ["src/auth/login.js", "tests/auth.test.js"]
-})
-```
-
-- If `safe_to_proceed` is `false` — there are conflicts. Do NOT edit those files.
-  Read the `conflicts` array to see which worktrees own them, then either:
-  - Choose different files that accomplish the same goal
-  - Ask the user how to proceed
-
-- If `safe_to_proceed` is `true` — you are clear to edit.
-
-### 3. Do the work
-
-Implement the task. Make commits as normal. Other agents will avoid your claimed files.
-
-If you discover mid-task that you need to edit additional files, call `switchman_task_claim` again for those files before editing them.
-
-### 4. End of session — mark complete or failed
-
-**On success:**
-```
-switchman_task_done({ task_id: "<task-id>", release_files: true })
-```
-
-**On failure (can't complete the task):**
-```
-switchman_task_fail({ task_id: "<task-id>", reason: "Brief explanation of what blocked you" })
-```
-
-Always call one of these before ending your session. Released file claims allow other agents to proceed.
-
----
-
-## Checking for conflicts
-
-At any time you can scan for conflicts across all worktrees:
-```
-switchman_scan()
-```
-
-Run this before merging your branch. If `safe_to_proceed` is `false`, do not merge until conflicts are resolved.
-
----
-
-## Checking system state
-
-To see what other agents are doing:
-```
-switchman_status()
-```
-
-This shows all pending and in-progress tasks, file claims per worktree, and worktree list.
-
----
-
-## Rules
-
-1. **Always claim files before editing them** — not after.
-2. **Always call `switchman_task_done` or `switchman_task_fail` at end of session** — never leave tasks as `in_progress` when you stop.
-3. **If `safe_to_proceed` is false, do not edit the conflicting files** — coordinate first.
-4. **Do not claim files you don't need** — over-claiming blocks other agents unnecessarily.
-5. **One task per session** — complete or fail your current task before taking another.