ralph-hero-mcp-server 2.5.50 → 2.5.52

package/dist/lib/helpers.js

@@ -319,7 +319,8 @@ export function resolveConfig(client, args) {
     const owner = args.owner || client.config.owner;
     const repo = args.repo || client.config.repo;
     if (!owner)
-        throw new Error("owner is required (set RALPH_GH_OWNER env var or pass explicitly)");
+        throw new Error("owner is required. Set RALPH_GH_OWNER in ~/.claude/settings.json (user-scoped) " +
+            "or .claude/settings.local.json (project-scoped), or pass owner explicitly.");
     if (!repo)
         throw new Error("repo is required. Set RALPH_GH_REPO env var, pass repo explicitly, or link exactly one repo to your project.");
     return { owner, repo };
@@ -334,7 +335,8 @@ export function resolveConfig(client, args) {
 export function resolveConfigOptionalRepo(client, args) {
     const owner = args.owner || client.config.owner;
     if (!owner)
-        throw new Error("owner is required (set RALPH_GH_OWNER env var or pass explicitly)");
+        throw new Error("owner is required. Set RALPH_GH_OWNER in ~/.claude/settings.json (user-scoped) " +
+            "or .claude/settings.local.json (project-scoped), or pass owner explicitly.");
     const repo = args.repo || client.config.repo;
     return { owner, repo };
 }

package/dist/lib/lock-guard.js

@@ -0,0 +1,40 @@
+/**
+ * Server-side lock guard for save_issue.
+ *
+ * Provides a pure, unit-testable function that determines whether a workflow
+ * state transition would result in a lock conflict — i.e., two agents trying
+ * to claim the same exclusive lock state simultaneously.
+ */
+import { LOCK_STATES } from "./workflow-states.js";
+/**
+ * Returns true when the requested transition is a lock conflict.
+ *
+ * A conflict exists when:
+ *   1. The issue is already in a lock state (currentState ∈ LOCK_STATES), AND
+ *   2. The caller is trying to set another lock state (targetState ∈ LOCK_STATES)
+ *
+ * The guard is intentionally narrow:
+ *   - If currentState is undefined or empty, the issue's state is unknown
+ *     (e.g., no project item yet). Allow the claim — it cannot conflict.
+ *   - If targetState is NOT a lock state (e.g., moving to Done or reverting to
+ *     Backlog), the guard is bypassed entirely. Non-lock transitions are always
+ *     safe and should not incur an extra API roundtrip in the caller.
+ *
+ * @param currentState - The issue's current workflow state from the live API,
+ *                       or undefined/empty if it could not be resolved.
+ * @param targetState  - The workflow state the caller is trying to set.
+ * @returns true if the transition should be blocked, false if it should proceed.
+ */
+export function isLockConflict(currentState, targetState) {
+    if (!currentState) {
+        return false;
+    }
+    if (!LOCK_STATES.includes(targetState)) {
+        return false;
+    }
+    if (currentState === targetState) {
+        return false; // idempotent re-claim: same agent re-locking is safe
+    }
+    return LOCK_STATES.includes(currentState);
+}
+//# sourceMappingURL=lock-guard.js.map

package/dist/tools/issue-tools.js

@@ -14,8 +14,9 @@ import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
 import { expandProfile } from "../lib/filter-profiles.js";
 import { toolSuccess, toolError } from "../types.js";
-import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, autoAdvanceParent, resolveIterationId, } from "../lib/helpers.js";
+import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, autoAdvanceParent, resolveIterationId, } from "../lib/helpers.js";
 import { lookupRepo, mergeDefaults } from "../lib/repo-registry.js";
+import { isLockConflict } from "../lib/lock-guard.js";
 // ---------------------------------------------------------------------------
 // Register issue tools
 // ---------------------------------------------------------------------------
@@ -833,6 +834,8 @@ export function registerIssueTools(server, client, fieldCache) {
             .describe("Iteration/sprint title (e.g., 'Sprint 1'), @current, @next, or null to clear."),
         command: z.string().optional()
             .describe("Ralph command for semantic intent resolution (e.g., 'ralph_impl'). Required when workflowState is a semantic intent."),
+        force: z.boolean().optional()
+            .describe("Bypass lock guard. Use only for recovery when an agent crash left an issue stuck in a lock state."),
     }, async (args) => {
         try {
             const { owner, repo } = resolveConfig(client, args);
@@ -989,6 +992,18 @@ export function registerIssueTools(server, client, fieldCache) {
                 if (!projectId) {
                     return toolError("Could not resolve project ID");
                 }
+                // Server-side lock guard: prevent two agents from claiming the same
+                // lock state simultaneously. Only fires when the caller is trying to
+                // SET a lock state — non-lock transitions skip this check entirely.
+                if (!args.force && resolvedWorkflowState && LOCK_STATES.includes(resolvedWorkflowState)) {
+                    const currentWorkflowState = await getCurrentFieldValue(client, fieldCache, owner, repo, args.number, "Workflow State", projectNumber);
+                    if (isLockConflict(currentWorkflowState, resolvedWorkflowState)) {
+                        return toolError(`Issue #${args.number} is already in a lock state ("${currentWorkflowState}") ` +
+                            `and cannot be claimed as "${resolvedWorkflowState}". ` +
+                            `Another agent is actively working on this issue. ` +
+                            `Use save_issue with force=true to override, or wait for the lock holder to release.`);
+                    }
+                }
                 // Collect field updates for aliased batch mutation
                 const updates = [];
                 // Collect fields to clear (separate mutations)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.50",
+  "version": "2.5.52",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",