ralph-hero-mcp-server 2.5.51 → 2.5.57

package/dist/index.js

@@ -218,6 +218,13 @@ function registerCoreTools(server, client) {
                 detail: "RALPH_GH_PROJECT_NUMBER not set",
             };
         }
+        // Token source detection — re-derive which env vars resolved
+        const repoTokenSource = resolveEnv("RALPH_GH_REPO_TOKEN")
+            ? "RALPH_GH_REPO_TOKEN"
+            : "RALPH_HERO_GITHUB_TOKEN";
+        const projectTokenSource = resolveEnv("RALPH_GH_PROJECT_TOKEN")
+            ? "RALPH_GH_PROJECT_TOKEN"
+            : repoTokenSource;
         // Summary
         const allOk = Object.values(checks).every((c) => c.status === "ok" || c.status === "skip");
         return toolSuccess({
@@ -228,11 +235,17 @@ function registerCoreTools(server, client) {
                 repo: client.config.repo || "(not set)",
                 projectOwner: resolveProjectOwner(client.config) || "(not set)",
                 projectNumber: client.config.projectNumber || "(not set)",
-                tokenMode: client.config.projectToken &&
-                    client.config.projectToken !== client.config.token
+                tokenMode: projectTokenSource !== repoTokenSource
                     ? "dual-token"
                     : "single-token",
             },
+            tokenSources: {
+                repoToken: repoTokenSource,
+                projectToken: projectTokenSource,
+                note: projectTokenSource !== repoTokenSource
+                    ? `Repo operations use ${repoTokenSource}, project operations use ${projectTokenSource}`
+                    : `Both repo and project operations use ${repoTokenSource}`,
+            },
         });
     });
 }

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.51",
+  "version": "2.5.57",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",