jules-orchestrator-kit 0.21.0 → 0.22.1

package/.github/workflows/jules-audit.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: ['22.x', '24.x']
+        node-version: ['20.x', '22.x', '24.x']
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

package/README.md

@@ -5,10 +5,10 @@
 [![Jules PR Audit](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml/badge.svg)](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml)
 [![npm version](https://img.shields.io/npm/v/jules-orchestrator-kit.svg)](https://www.npmjs.com/package/jules-orchestrator-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
 
 > **High-Volume Autonomous Orchestration Engine for Google Jules**  
-> Built specifically to execute 300+ daily agent sessions and parallel swarms safely. Zero external runtime dependencies. Built strictly on native Node.js 18+ ESM.
+> Built specifically to execute 300+ daily agent sessions and parallel swarms safely. Zero external runtime dependencies. Built strictly on native Node.js 20+ ESM.
 
 ---
 

package/bin/agentctl.mjs

@@ -13,7 +13,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.21.0 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.22.1 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -43,7 +43,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.21.0");
+    console.log("agentctl v0.22.1");
     process.exit(0);
   }
 
@@ -223,7 +223,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.21.0)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.22.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);

package/index.mjs

@@ -21,12 +21,19 @@ export {
   readLedger,
   verifyLedgerIntegrity,
   reserveBudget,
+  reserveBudgetAtomic,
   commitBudgetReservation,
   withBudget,
   checkDailyBudget,
   acquireLock,
   releaseLock,
   lockStatus,
+  getLockDir,
+  withVfsMutex,
+  MutexTimeoutError,
+  BudgetError,
+  isPidAlive,
+  getProcessStartTime,
 } from "./src/state.mjs";
 export { gate, dispatch, repair, run, fingerprintFailureState } from "./src/engine.mjs";
 export { validateEnvelope } from "./src/envelope.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",
@@ -62,7 +62,7 @@
     "lint": "eslint ."
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "keywords": [
     "jules",

package/scripts/release.mjs

@@ -55,12 +55,22 @@ if (!notes) {
   console.log("   ✅ Extracted release notes from CHANGELOG.md.\n");
 }
 
-// 3. Create Git Tag if not exists
+// 3. Create Git Tag if not exists (or update if version mismatch)
 console.log(`3. Checking Git tag ${tagName}...`);
 try {
-  const tags = execSync("git tag -l", { cwd: root, encoding: "utf-8" });
-  if (tags.split("\n").includes(tagName)) {
-    console.log(`   ℹ️ Git tag ${tagName} already exists.`);
+  const tags = execSync("git tag -l", { cwd: root, encoding: "utf-8" }).split("\n").map((t) => t.trim());
+  if (tags.includes(tagName)) {
+    let taggedVersion = "";
+    try {
+      const rawPkg = execSync(`git show ${tagName}:package.json`, { cwd: root, encoding: "utf-8" });
+      taggedVersion = JSON.parse(rawPkg).version;
+    } catch (_) {}
+    if (taggedVersion && taggedVersion !== version) {
+      console.log(`   ⚠️ Tag ${tagName} points to package.json version ${taggedVersion}. Updating tag to HEAD (${version})...`);
+      execSync(`git tag -f -a ${tagName} -m "${pkg.name} ${tagName}"`, { cwd: root, stdio: "inherit" });
+    } else {
+      console.log(`   ℹ️ Git tag ${tagName} already exists.`);
+    }
   } else {
     execSync(`git tag -a ${tagName} -m "${pkg.name} ${tagName}"`, { cwd: root, stdio: "inherit" });
     console.log(`   ✅ Created Git tag ${tagName}.`);

package/src/state.mjs

@@ -11,7 +11,7 @@ import {
   unlinkSync,
 } from "node:fs";
 import { join } from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { hostname } from "node:os";
 import { resolveRoot } from "./config.mjs";
 
@@ -34,7 +34,7 @@ export function getQueueDir(rootOrOpts = resolveRoot()) {
 
 export function getStateDir(rootOrOpts = resolveRoot()) {
   const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
-  const dir = join(root, ".agent/state");
+  const dir = root.endsWith(".agent/state") ? root : join(root, ".agent/state");
   ensureDir(dir);
   return dir;
 }
@@ -45,11 +45,19 @@ export function getDailyLedgerPath(rootOrOpts = resolveRoot()) {
   return join(getStateDir(root), `ledger-${dateStr}.jsonl`);
 }
 
+export class MutexTimeoutError extends Error {
+  constructor(message = "Failed to acquire VFS mutex lock within timeout") {
+    super(message);
+    this.name = "MutexTimeoutError";
+  }
+}
+
 /**
  * Executes a function inside a kernel-level VFS directory mutex for strict linearizability.
+ * Fail-closed: Throws MutexTimeoutError if lock acquisition times out.
  */
 export function withVfsMutex(mutexDir, fn, opts = {}) {
-  const maxRetries = opts.maxRetries || 50;
+  const maxRetries = opts.maxRetries || 200;
   const retryDelayMs = opts.retryDelayMs || 10;
 
   for (let i = 0; i < maxRetries; i++) {
@@ -71,7 +79,7 @@ export function withVfsMutex(mutexDir, fn, opts = {}) {
       throw err;
     }
   }
-  return fn();
+  throw new MutexTimeoutError(`Failed to acquire VFS mutex lock at ${mutexDir} after ${maxRetries} retries`);
 }
 
 /**
@@ -80,7 +88,7 @@ export function withVfsMutex(mutexDir, fn, opts = {}) {
 export function appendLedger(entry, rootOrOpts = resolveRoot()) {
   const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
   const filePath = getDailyLedgerPath(root);
-  const mutexDir = join(getStateDir(root), ".ledger.mutex");
+  const mutexDir = join(getStateDir(root), ".budget.mutex");
 
   return withVfsMutex(mutexDir, () => {
     let prevHash = "0".repeat(64);
@@ -200,16 +208,64 @@ export class BudgetError extends Error {
   }
 }
 
-export function reserveBudget(rootOrOpts = resolveRoot(), limit = 300) {
-  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
-  const budget = checkDailyBudget(root, limit);
-  if (!budget.ok) {
-    throw new BudgetError(`Daily budget exhausted (${budget.used}/${budget.budget} tasks executed)`);
-  }
+export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300, opts = {}) {
+  const root = typeof stateDirOrRoot === "string" ? stateDirOrRoot : resolveRoot();
+  const stateDir = getStateDir(root);
+  const mutexDir = join(stateDir, ".budget.mutex");
+
+  return withVfsMutex(mutexDir, () => {
+    const dateStr = new Date().toISOString().split("T")[0];
+    const filePath = join(stateDir, `ledger-${dateStr}.jsonl`);
+
+    let count = 0;
+    let prevHash = "0".repeat(64);
+
+    if (existsSync(filePath)) {
+      try {
+        const raw = readFileSync(filePath, "utf-8");
+        const lines = raw.split("\n").filter(Boolean);
+        count = lines.length;
+        for (let i = lines.length - 1; i >= 0; i--) {
+          try {
+            const lastObj = JSON.parse(lines[i]);
+            if (lastObj.hash) {
+              prevHash = lastObj.hash;
+              break;
+            }
+          } catch (_) {}
+        }
+      } catch (_) {}
+    }
+
+    if (count >= limit) {
+      throw new BudgetError(`Daily budget exhausted (${count}/${limit} tasks executed)`);
+    }
+
+    const timestamp = new Date().toISOString();
+    const reservationId = `res-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    const rawPayload = { timestamp, event: "budget_reserved", reservationId, budget: limit, prevHash };
+    const hash = createHash("sha256").update(JSON.stringify(rawPayload)).digest("hex");
+    const payload = { ...rawPayload, hash };
+
+    const fd = openSync(filePath, "a");
+    try {
+      writeSync(fd, JSON.stringify(payload) + "\n", "utf-8");
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
 
-  const reservationId = `res-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
-  appendLedger({ event: "budget_reserved", reservationId, budget: limit }, root);
-  return { ok: true, reservationId, remaining: Math.max(0, budget.remaining - 1) };
+    return {
+      ok: true,
+      reservationId,
+      remaining: Math.max(0, limit - (count + 1)),
+      used: count + 1,
+    };
+  }, opts);
+}
+
+export function reserveBudget(rootOrOpts = resolveRoot(), limit = 300) {
+  return reserveBudgetAtomic(rootOrOpts, limit);
 }
 
 export function commitBudgetReservation(rootOrOpts = resolveRoot(), reservationId = "") {
@@ -236,8 +292,25 @@ export function getLockDir(rootOrOpts = resolveRoot()) {
   return dir;
 }
 
+export function getProcessStartTime(pid) {
+  if (!pid || typeof pid !== "number") return null;
+  if (process.platform === "linux") {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+      const rpar = stat.lastIndexOf(")");
+      if (rpar !== -1) {
+        const rest = stat.slice(rpar + 1).trim().split(/\s+/);
+        return rest[19] || null;
+      }
+      const parts = stat.trim().split(/\s+/);
+      return parts[21] || null;
+    } catch (_) {}
+  }
+  return null;
+}
+
 /**
- * Checks if a PID is alive with optional PID-recycling start time validation on Linux.
+ * Checks if a PID is alive with PID-recycling start time validation on Linux.
  */
 export function isPidAlive(pid, expectedStartTime = null) {
   if (!pid || typeof pid !== "number") return false;
@@ -247,30 +320,20 @@ export function isPidAlive(pid, expectedStartTime = null) {
     return false;
   }
 
-  if (expectedStartTime && process.platform === "linux") {
+  if (expectedStartTime !== null && expectedStartTime !== undefined && process.platform === "linux") {
     try {
-      const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
-      const parts = stat.split(" ");
-      const startTime = parts[21];
-      if (startTime && String(startTime) !== String(expectedStartTime)) {
+      const actualStartTime = getProcessStartTime(pid);
+      if (!actualStartTime || String(actualStartTime) !== String(expectedStartTime)) {
         return false;
       }
-    } catch (_) {}
+    } catch (_) {
+      return false;
+    }
   }
 
   return true;
 }
 
-function getProcessStartTime(pid) {
-  if (process.platform === "linux") {
-    try {
-      const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
-      return stat.split(" ")[21] || null;
-    } catch (_) {}
-  }
-  return null;
-}
-
 export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveRoot()) {
   const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
   const lockDir = getLockDir(root);
@@ -279,7 +342,8 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   if (existsSync(lockFile)) {
     try {
       const existing = JSON.parse(readFileSync(lockFile, "utf-8"));
-      const isAlive = isPidAlive(existing.pid, existing.processStartTime);
+      const recordedStartTime = existing.processStartTime ?? existing.starttime ?? null;
+      const isAlive = isPidAlive(existing.pid, recordedStartTime);
       const isExpired = existing.acquiredAt && Date.now() - new Date(existing.acquiredAt).getTime() > 7200000;
 
       if (!isAlive || isExpired) {
@@ -292,12 +356,15 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
     }
   }
 
+  const startTime = getProcessStartTime(process.pid);
   const payload = {
     agent: agentName,
     taskId,
     files,
     pid: process.pid,
-    processStartTime: getProcessStartTime(process.pid),
+    processStartTime: startTime,
+    starttime: startTime,
+    nonce: randomUUID(),
     hostname: hostname(),
     acquiredAt: new Date().toISOString(),
   };
@@ -352,3 +419,4 @@ export function lockStatus(rootOrOpts = resolveRoot()) {
   } catch (_) {}
   return locks;
 }
+