@virsanghavi/axis-server 1.7.1 → 1.7.2

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

@@ -906,6 +906,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`
@@ -1785,10 +1795,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 +1961,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- 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 +1988,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 +2048,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.7.2",
     "description": "Axis MCP Server CLI",
     "main": "dist/index.js",
     "bin": {