jules-orchestrator-kit 0.57.0 → 0.59.0

package/src/stack-detector.mjs

@@ -1,5 +1,42 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
+import { whichBinary } from "./provider-readiness.mjs";
+
+/**
+ * The Python interpreter to invoke, by whatever name this machine has it under.
+ *
+ * `python3` does not exist on a default Windows install (the launcher is `py`,
+ * the Store package is `python`), so a hardcoded `python3` made every Python
+ * command in the kit unrunnable there.
+ */
+function pythonBin(env = process.env) {
+  for (const name of ["python3", "python", "py"]) {
+    if (whichBinary(name, env)) return name;
+  }
+  return "python3";
+}
+
+/**
+ * The command that runs a pytest suite.
+ *
+ * Not `pytest`. Invoked as a bare console script, pytest does not put the
+ * working directory on `sys.path`; invoked as `-m`, Python does. So the most
+ * ordinary Python layout there is — a module at the root, its test under
+ * `tests/` importing it — collapsed at collection with `ModuleNotFoundError:
+ * No module named 'calc'`, and the gate reported exit 4 on a project whose
+ * suite passes perfectly when the developer types `python3 -m pytest`. A
+ * first-run rejection of correct code is the most expensive failure this tool
+ * can produce: it teaches the user the gate is wrong.
+ *
+ * Falls back to the bare console script only when no interpreter can be found
+ * to host the module.
+ */
+export function pytestCmd(env = process.env) {
+  for (const name of ["python3", "python", "py"]) {
+    if (whichBinary(name, env)) return `${name} -m pytest`;
+  }
+  return "pytest";
+}
 
 /**
  * Generate a zero-dependency smoke test file using node:test for untested JS/Generic repos.
@@ -186,7 +223,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
   }
   if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "requirements.txt")) || existsSync(join(projectRoot, "setup.py"))) {
     const triggerFile = existsSync(join(projectRoot, "pyproject.toml")) ? "pyproject.toml" : existsSync(join(projectRoot, "requirements.txt")) ? "requirements.txt" : "setup.py";
-    return { ...container, stack: "python", testCmd: "pytest", buildCmd: "python3 -m compileall -q .", triggerFile };
+    return { ...container, stack: "python", testCmd: pytestCmd(), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile };
   }
   if (existsSync(join(projectRoot, "mix.exs"))) {
     return { ...container, stack: "mix", testCmd: "mix test", buildCmd: "mix compile", triggerFile: "mix.exs" };
@@ -270,7 +307,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     }
     const pyFile = rootFiles.find((f) => f.endsWith(".py"));
     if (pyFile) {
-      return { ...container, stack: "python", testCmd: "pytest", buildCmd: "python3 -m compileall -q .", triggerFile: pyFile };
+      return { ...container, stack: "python", testCmd: pytestCmd(), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile: pyFile };
     }
   } catch (_) {}
 
@@ -699,7 +736,7 @@ export function bootstrapZeroTestRepo(root = process.cwd(), options = {}) {
   if (detected.stack === "php" || detected.stack === "laravel" || detected.stack === "wordpress") {
     testCmd = 'php -l $(find . -name "*.php" -not -path "./vendor/*" -not -path "./node_modules/*")';
   } else if (detected.stack === "python") {
-    testCmd = "python3 -m compileall -q -x '^\\./(\\.\\venv|venv|node_modules|\\.git)/' .";
+    testCmd = `${pythonBin()} -m compileall -q -x '^\\./(\\.\\venv|venv|node_modules|\\.git)/' .`;
   } else if (detected.stack === "dotnet") {
     testCmd = "dotnet build --no-incremental --nologo";
   } else if (detected.stack === "cargo") {

package/src/state.mjs

@@ -530,6 +530,54 @@ export function isPidAlive(pid, expectedStartTime = null) {
   return true;
 }
 
+export const LOCK_TTL_MS = 7200000;
+
+/**
+ * The epoch-ms instant a lock record stops holding.
+ *
+ * Records written before leases existed carry only `acquiredAt`, so they keep
+ * the two-hour window they were reaped on before.
+ */
+function lockExpiry(record) {
+  if (!record) return 0;
+  if (record.expiresAt) {
+    const t = new Date(record.expiresAt).getTime();
+    if (Number.isFinite(t)) return t;
+  }
+  if (record.acquiredAt) {
+    const t = new Date(record.acquiredAt).getTime();
+    if (Number.isFinite(t)) return t + LOCK_TTL_MS;
+  }
+  return Infinity;
+}
+
+/**
+ * Is this lock still held?
+ *
+ * There are two kinds of holder and only one of them has a process worth
+ * asking about.
+ *
+ * An in-process caller — the engine, the swarm — holds the lock for as long as
+ * it runs, so its pid is a real witness: if it died the lock is garbage, and
+ * reaping on a dead pid is what stops a crash from wedging the repo for the
+ * full TTL.
+ *
+ * `agentctl lock acquire` is the opposite. That process writes the file and
+ * exits *by design* — the agent it speaks for lives in some other process, on
+ * another machine, or has not started yet. Asking whether the CLI that wrote
+ * the record is alive therefore always answered "no", so the very next acquire
+ * reaped the lock and handed the same files to a second agent, telling both
+ * they had exclusive access. Two holders who each believe they are alone is
+ * worse than no lock at all. A record written that way marks itself `leased`,
+ * and then only its expiry decides.
+ */
+export function isLockLive(record) {
+  if (!record) return false;
+  if (Date.now() >= lockExpiry(record)) return false;
+  if (record.leased === true) return true;
+  return isPidAlive(record.pid, record.processStartTime ?? record.starttime ?? null);
+}
+
 function assertSafeTaskId(taskId) {
   if (typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || basename(taskId) !== taskId) {
     throw new Error("Invalid task id for lock path");
@@ -546,15 +594,16 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   if (existsSync(lockFile)) {
     try {
       const existing = JSON.parse(readFileSync(lockFile, "utf-8"));
-      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) {
-        try { unlinkSync(lockFile); } catch (_) {}
-      } else {
-        return { ok: false, holder: existing.agent, taskId, pid: existing.pid };
+      if (isLockLive(existing)) {
+        return {
+          ok: false,
+          holder: existing.agent,
+          taskId,
+          pid: existing.pid,
+          expiresAt: existing.expiresAt || null,
+        };
       }
+      try { unlinkSync(lockFile); } catch (_) {}
     } catch (_) {
       try { unlinkSync(lockFile); } catch (_) {}
     }
@@ -573,11 +622,7 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   if (requested.size > 0) {
     for (const held of lockStatus(root)) {
       if (!held || held.taskId === taskId) continue;
-      const recordedStart = held.processStartTime ?? held.starttime ?? null;
-      const stillHeld =
-        isPidAlive(held.pid, recordedStart) &&
-        !(held.acquiredAt && Date.now() - new Date(held.acquiredAt).getTime() > 7200000);
-      if (!stillHeld) continue;
+      if (!isLockLive(held)) continue;
 
       const overlap = (Array.isArray(held.files) ? held.files : [])
         .map((f) => normalizePath(f))
@@ -588,13 +633,22 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
           holder: held.agent,
           taskId: held.taskId,
           pid: held.pid,
+          expiresAt: held.expiresAt || null,
           conflictingFiles: overlap,
         };
       }
     }
   }
 
-  const startTime = getProcessStartTime(process.pid);
+  // `leased` says the holder is not this process. A caller that will stay
+  // alive for the duration (the engine, the swarm) leaves it off and gets pid
+  // liveness; a one-shot CLI sets it and gets a plain time-bounded lease. See
+  // isLockLive.
+  const leased = opts?.lease === true;
+  const ownerPid = Number.isInteger(opts?.ownerPid) && opts.ownerPid > 0 ? opts.ownerPid : process.pid;
+  const ttlMs = Number.isFinite(opts?.ttlMs) && opts.ttlMs > 0 ? opts.ttlMs : LOCK_TTL_MS;
+  const startTime = getProcessStartTime(ownerPid);
+  const acquiredAt = new Date();
   const concurrencyGroup = String(opts?.concurrencyGroup || opts?.concurrency_group || "").trim();
   const payload = {
     agent: agentName,
@@ -602,12 +656,14 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
     branch,
     files,
     concurrencyGroup,
-    pid: process.pid,
+    pid: ownerPid,
     processStartTime: startTime,
     starttime: startTime,
+    leased,
     nonce: randomUUID(),
     hostname: hostname(),
-    acquiredAt: new Date().toISOString(),
+    acquiredAt: acquiredAt.toISOString(),
+    expiresAt: new Date(acquiredAt.getTime() + ttlMs).toISOString(),
   };
 
   let fd;

package/src/test-paths.mjs

@@ -0,0 +1,68 @@
+/**
+ * One answer to "is this path a test file?".
+ *
+ * There were five, in five modules, and they disagreed with each other:
+ *
+ *   - `security.mjs`  matched the substring `/test/`, so a file in the
+ *     repository's own root-level `tests/` directory had no leading slash and
+ *     was not a test file. The entire tamper guard — skip injection, vacuous
+ *     assertions, commented-out assertions, removal, weakening, expectation
+ *     rewrites — was therefore switched off for the standard pytest layout
+ *     (`tests/test_calc.py`), the standard Rust integration layout
+ *     (`tests/integration.rs`) and every RSpec suite (`spec/`).
+ *   - `mutation.mjs`  had the same substring bug, in the opposite direction:
+ *     those same files were not excluded, so the harness mutated operators
+ *     inside the tests themselves and scored the result.
+ *   - `engine.mjs`    never looked for `_test.`, so `strictTestLock` did not
+ *     consider a Go test file to be a test file.
+ *   - `coverage.mjs`  and `evidence.mjs` each had a third and fourth spelling.
+ *
+ * A predicate this load-bearing cannot have five definitions. This is the one
+ * they all use.
+ *
+ * The classification errs toward "yes". Four of the five callers get stricter
+ * when it does — the tamper guard applies, the integrity hash covers more, the
+ * lock triggers — and the fifth (mutation) has nothing to lose, because
+ * mutating an operator inside a test proves nothing about the code under test.
+ */
+
+/**
+ * Directory names that mean "everything below here is a test".
+ *
+ * Matched as whole path segments, not substrings: `latest/` is not `test/`,
+ * and `myspec/` is not `spec/`.
+ */
+const TEST_DIR_SEGMENTS = new Set(["test", "tests", "spec", "specs", "__tests__", "__test__"]);
+
+/**
+ * True when `file` names a test file under any convention the kit supports.
+ *
+ * Covers, by directory: `test/`, `tests/`, `spec/`, `specs/`, `__tests__/` at
+ * any depth including the repository root. By filename: `foo.test.js`,
+ * `foo.spec.ts`, `foo_test.go`, `foo_spec.rb`, `test_calc.py` (pytest),
+ * `spec_helper.rb`, and Foundry's `Foo.t.sol` / `FooTest.sol`.
+ *
+ * @param {string} file - Repo-relative path, either separator.
+ * @returns {boolean}
+ */
+export function isTestPath(file) {
+  if (!file || typeof file !== "string") return false;
+  const segments = file.replace(/\\/g, "/").toLowerCase().split("/").filter(Boolean);
+  if (segments.length === 0) return false;
+
+  for (let i = 0; i < segments.length - 1; i++) {
+    if (TEST_DIR_SEGMENTS.has(segments[i])) return true;
+  }
+
+  const base = segments[segments.length - 1];
+  return (
+    base.includes(".test.") ||
+    base.includes(".spec.") ||
+    base.includes("_test.") ||
+    base.includes("_spec.") ||
+    base.startsWith("test_") ||
+    base.startsWith("spec_") ||
+    base.endsWith("test.sol") ||
+    base.endsWith(".t.sol")
+  );
+}