@virsanghavi/axis-server 1.7.1 → 1.8.0

package/.axis/instructions/conventions.md

@@ -51,7 +51,13 @@ Skip jobs ONLY for: single-line fixes, typos, config tweaks.
 - Release locks IMMEDIATELY by completing jobs. Never hold a lock while doing unrelated work.
 - `force_unlock` is a **last resort** — only for locks >25 min old from a crashed agent. Always give a reason.
 
+### Releasing Locks (CRITICAL — do not skip)
+**Every file you lock MUST be unlocked before your session ends.** Dangling locks block every other agent in the project.
+- **Primary unlock method**: `complete_job` — releases all locks for that job.
+- **Session end**: `finalize_session` — clears ALL remaining locks. Call this before you stop responding.
+- **Self-check**: Before finishing, verify: "Have I completed all jobs and called `finalize_session`?" If not, do it now.
+
 ### Session Cleanup (MANDATORY)
-- `complete_job` after EVERY finished task — do not accumulate incomplete jobs.
+- `complete_job` after EVERY finished task — do not accumulate incomplete jobs. **This is how locks get released.**
 - `update_shared_context` after meaningful steps — log decisions, not just actions.
-- `finalize_session` when the user's request is fully complete — this is required, not optional.
+- `finalize_session` when the user's request is fully complete — this is required, not optional. **This clears all remaining locks.**

package/dist/mcp-server.mjs

@@ -284,7 +284,7 @@ var CircuitOpenError = class extends Error {
     this.name = "CircuitOpenError";
   }
 };
-var NerveCenter = class {
+var NerveCenter = class _NerveCenter {
   mutex;
   state;
   contextManager;
@@ -876,6 +876,38 @@ ${notepad}`;
     }
   }
   // --- Decision & Orchestration ---
+  /**
+   * Check if two file paths conflict hierarchically.
+   * A lock on a directory blocks locks on any file within it, and vice versa.
+   * Examples:
+   *   pathsConflict("/foo/bar", "/foo/bar/baz.ts") => true  (parent blocks child)
+   *   pathsConflict("/foo/bar/baz.ts", "/foo/bar") => true  (child blocks parent)
+   *   pathsConflict("/foo/bar", "/foo/bar")         => true  (exact match)
+   *   pathsConflict("/foo/bar", "/foo/baz")         => false (siblings)
+   */
+  static pathsConflict(pathA, pathB) {
+    const a = pathA.replace(/\/+$/, "");
+    const b = pathB.replace(/\/+$/, "");
+    if (a === b) return true;
+    if (b.startsWith(a + "/")) return true;
+    if (a.startsWith(b + "/")) return true;
+    return false;
+  }
+  /**
+   * Find any existing lock that conflicts hierarchically with the requested path.
+   * Skips locks owned by the same agent and stale locks.
+   */
+  findHierarchicalConflict(requestedPath, requestingAgent, locks) {
+    for (const lock of locks) {
+      if (lock.agentId === requestingAgent) continue;
+      const isStale = Date.now() - lock.timestamp > this.lockTimeout;
+      if (isStale) continue;
+      if (_NerveCenter.pathsConflict(requestedPath, lock.filePath)) {
+        return lock;
+      }
+    }
+    return null;
+  }
   async proposeFileAccess(agentId, filePath, intent, userPrompt) {
     return await this.mutex.runExclusive(async () => {
       logger.info(`[proposeFileAccess] Starting - agentId: ${agentId}, filePath: ${filePath}`);
@@ -906,6 +938,16 @@ ${notepad}`;
         } catch (e) {
           if (e.message && e.message.includes("409")) {
             logger.info(`[proposeFileAccess] Lock conflict (409)`);
+            let blockingAgent;
+            try {
+              const jsonMatch = e.message.match(/\{.*\}/s);
+              if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[0]);
+                blockingAgent = parsed.current_lock?.agent_id;
+              }
+            } catch {
+            }
+            this.logLockEvent("BLOCKED", filePath, agentId, blockingAgent, intent);
             return {
               status: "REQUIRES_ORCHESTRATION",
               message: `File '${filePath}' is locked by another agent`
@@ -917,6 +959,26 @@ ${notepad}`;
       }
       if (this.useSupabase && this.supabase && this._projectId) {
         try {
+          const { data: existingLocks } = await this.supabase.from("locks").select("agent_id, file_path, intent, updated_at").eq("project_id", this._projectId);
+          if (existingLocks && existingLocks.length > 0) {
+            const asFileLocks = existingLocks.map((row2) => ({
+              agentId: row2.agent_id,
+              filePath: row2.file_path,
+              intent: row2.intent,
+              userPrompt: "",
+              timestamp: row2.updated_at ? Date.parse(row2.updated_at) : Date.now()
+            }));
+            const conflict2 = this.findHierarchicalConflict(filePath, agentId, asFileLocks);
+            if (conflict2) {
+              logger.info(`[proposeFileAccess] Hierarchical conflict: '${filePath}' overlaps with locked '${conflict2.filePath}' (owner: ${conflict2.agentId})`);
+              this.logLockEvent("BLOCKED", filePath, agentId, conflict2.agentId, intent);
+              return {
+                status: "REQUIRES_ORCHESTRATION",
+                message: `Conflict: '${filePath}' overlaps with '${conflict2.filePath}' locked by '${conflict2.agentId}'`,
+                currentLock: conflict2
+              };
+            }
+          }
           const { data, error } = await this.supabase.rpc("try_acquire_lock", {
             p_project_id: this._projectId,
             p_file_path: filePath,
@@ -949,17 +1011,16 @@ ${notepad}`;
           logger.warn("[NerveCenter] Lock RPC failed. Falling back to local.", e);
         }
       }
-      const existing = Object.values(this.state.locks).find((l) => l.filePath === filePath);
-      if (existing) {
-        const isStale = Date.now() - existing.timestamp > this.lockTimeout;
-        if (!isStale && existing.agentId !== agentId) {
-          this.logLockEvent("BLOCKED", filePath, agentId, existing.agentId, intent);
-          return {
-            status: "REQUIRES_ORCHESTRATION",
-            message: `Conflict: File '${filePath}' is currently locked by '${existing.agentId}'`,
-            currentLock: existing
-          };
-        }
+      const allLocks = Object.values(this.state.locks);
+      const conflict = this.findHierarchicalConflict(filePath, agentId, allLocks);
+      if (conflict) {
+        logger.info(`[proposeFileAccess] Hierarchical conflict (local): '${filePath}' overlaps with locked '${conflict.filePath}' (owner: ${conflict.agentId})`);
+        this.logLockEvent("BLOCKED", filePath, agentId, conflict.agentId, intent);
+        return {
+          status: "REQUIRES_ORCHESTRATION",
+          message: `Conflict: '${filePath}' overlaps with '${conflict.filePath}' locked by '${conflict.agentId}'`,
+          currentLock: conflict
+        };
       }
       this.state.locks[filePath] = { agentId, filePath, intent, userPrompt, timestamp: Date.now() };
       await this.saveState();
@@ -1785,10 +1846,16 @@ Agents MUST execute the full Axis workflow without being told:
 Every non-trivial task MUST follow: post_job \u2192 claim_next_job \u2192 propose_file_access \u2192 (edit) \u2192 complete_job.
 Skip ONLY for single-line typo fixes.
 
+### Releasing Locks (CRITICAL)
+Every file you lock MUST be unlocked before your session ends. Dangling locks block all other agents.
+- complete_job releases locks for that job. Call it IMMEDIATELY after each task.
+- finalize_session clears ALL remaining locks. Call it before you stop responding.
+- NEVER end a session while holding locks. Self-check: "Did I call finalize_session?"
+
 ### Session Cleanup (MANDATORY)
-- complete_job IMMEDIATELY after finishing each task.
+- complete_job IMMEDIATELY after finishing each task \u2014 this is how locks get released.
 - update_shared_context after meaningful steps.
-- finalize_session when the user's request is fully complete \u2014 do not wait to be told.
+- finalize_session when the user's request is fully complete \u2014 do not wait to be told. This clears all remaining locks.
 
 ### Force-Unlock Policy
 force_unlock is a LAST RESORT \u2014 only for locks >25 min old from a crashed agent. Always give a reason.
@@ -1945,7 +2012,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     // --- Decision & Orchestration ---
     {
       name: "propose_file_access",
-      description: "**CRITICAL: REQUEST FILE LOCK** \u2014 call this before EVERY file edit, no exceptions.\n- Checks if another agent currently holds a lock.\n- Returns `GRANTED` if safe to proceed, or `REQUIRES_ORCHESTRATION` if someone else is editing.\n- Usage: Provide your `agentId` (e.g., 'cursor-agent'), `filePath` (absolute), and `intent` (descriptive \u2014 e.g. 'Refactor auth to use JWT', NOT 'editing file').\n- Locks expire after 30 minutes. Use `force_unlock` only as a last resort for crashed agents.",
+      description: "**CRITICAL: REQUEST FILE LOCK** \u2014 call this before EVERY file edit, no exceptions.\n- Checks if another agent currently holds a lock.\n- Returns `GRANTED` if safe to proceed, or `REQUIRES_ORCHESTRATION` if someone else is editing.\n- **Hierarchical matching**: Locking a directory also blocks locks on files within it, and vice versa. E.g. locking `src/api/` blocks `src/api/auth/login.ts`.\n- Usage: Provide your `agentId` (e.g., 'cursor-agent'), `filePath` (absolute), and `intent` (descriptive \u2014 e.g. 'Refactor auth to use JWT', NOT 'editing file').\n- Locks expire after 30 minutes. Use `force_unlock` only as a last resort for crashed agents.\n- **IMPORTANT**: Every lock you acquire MUST be released. Call `complete_job` when done with each task, and `finalize_session` before ending your session. Dangling locks block all other agents.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1972,7 +2039,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     // --- Permanent Memory ---
     {
       name: "finalize_session",
-      description: "**MANDATORY SESSION CLEANUP** \u2014 call this automatically when the user's request is fully complete.\n- Archives the current Live Notepad to a permanent session log.\n- Clears all active locks and completed jobs.\n- Resets the Live Notepad for the next session.\n- Do NOT wait for the user to say 'we are done.' When all tasks are finished, call this yourself.",
+      description: "**MANDATORY SESSION CLEANUP** \u2014 call this automatically when the user's request is fully complete.\n- Archives the current Live Notepad to a permanent session log.\n- **Clears ALL active file locks** and completed jobs. This is your safety net to ensure no dangling locks.\n- Resets the Live Notepad for the next session.\n- Do NOT wait for the user to say 'we are done.' When all tasks are finished, call this yourself.\n- **CRITICAL**: You MUST call this before ending ANY session. Failing to do so leaves file locks that block all other agents.",
       inputSchema: { type: "object", properties: {}, required: [] }
     },
     {
@@ -2032,7 +2099,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "complete_job",
-      description: "**CLOSE TICKET**: Mark a job as done and release file locks.\n- Call this IMMEDIATELY after finishing each job \u2014 do not accumulate completed-but-unclosed jobs.\n- Requires `outcome` (what was done).\n- If you are not the assigned agent, you must provide the `completionKey`.\n- Leaving jobs open holds locks and blocks other agents.",
+      description: "**CLOSE TICKET**: Mark a job as done and release file locks.\n- Call this IMMEDIATELY after finishing each job \u2014 do not accumulate completed-but-unclosed jobs.\n- Requires `outcome` (what was done).\n- If you are not the assigned agent, you must provide the `completionKey`.\n- **This is the primary way to release file locks.** Leaving jobs open holds locks and blocks other agents.\n- REMINDER: After completing all jobs, you MUST also call `finalize_session` to clear any remaining locks.",
       inputSchema: {
         type: "object",
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@virsanghavi/axis-server",
-    "version": "1.7.1",
+    "version": "1.8.0",
     "description": "Axis MCP Server CLI",
     "main": "dist/index.js",
     "bin": {