jules-orchestrator-kit 0.74.0 → 0.75.0

package/src/ops/doctor-registry.mjs

@@ -3,8 +3,15 @@ import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
 import { loadConfig, detectStack } from "../config.mjs";
-import { probeProvider, detectAvailableProviders, probeProviderLiveness } from "../provider-readiness.mjs";
+import { probeProvider, detectAvailableProviders, probeProviderLiveness, whichBinary } from "../provider-readiness.mjs";
 import { resolveConcurrency } from "../budget.mjs";
+import { isLockLive, getLockDir } from "../state.mjs";
+import {
+  extractPrimaryExecutable,
+  missingNodeModules,
+  missingPythonEnv,
+  probeOracleLightly,
+} from "./toolchain-diagnostics.mjs";
 
 /**
  * @typedef {"pass" | "warn" | "fail" | "skip" | "unknown"} DiagnosticStatus
@@ -429,6 +436,119 @@ export async function runDoctorChecks(options = {}) {
     });
   }
 
+
+  // 4b. Toolchain readiness — name a missing verify binary / install tree before
+  // dispatch, so first-run failures are diagnosable without reading spawn ENOENT.
+  if (effectiveTest) {
+    const primaryBin = extractPrimaryExecutable(effectiveTest);
+    if (primaryBin) {
+      const onPath = Boolean(whichBinary(primaryBin));
+      if (!onPath) {
+        const status = verificationRequired ? "fail" : "warn";
+        addResult({
+          id: "toolchain.binary",
+          category: "Verification",
+          title: "Verify Toolchain Binary",
+          status,
+          severity: verificationRequired ? "high" : "medium",
+          summary: `Verification binary \`${primaryBin}\` is not on PATH — gate will fail when it runs \`${effectiveTest}\``,
+          evidence: [
+            { label: "primaryBinary", value: primaryBin, sensitive: false },
+            { label: "testCommand", value: effectiveTest, sensitive: false },
+          ],
+          fixes: [
+            {
+              id: "toolchain.install-binary",
+              title: `Install ${primaryBin}`,
+              summary: `Install \`${primaryBin}\` (or change verify.test to a command available on this machine)`,
+              risk: "low",
+              automatic: false,
+              requiresProbe: false,
+            },
+          ],
+        });
+      } else {
+        addResult({
+          id: "toolchain.binary",
+          category: "Verification",
+          title: "Verify Toolchain Binary",
+          status: "pass",
+          severity: "info",
+          summary: `Verification binary \`${primaryBin}\` is on PATH`,
+          evidence: [
+            { label: "primaryBinary", value: primaryBin, sensitive: false },
+            { label: "testCommand", value: effectiveTest, sensitive: false },
+          ],
+        });
+
+        // Active probe: lightweight read-only check so ops know the pipeline
+        // answers before a paid dispatch.
+        if (activeProbe) {
+          const probe = probeOracleLightly(root, effectiveTest, primaryBin);
+          addResult({
+            id: "oracle.probe",
+            category: "Verification",
+            title: "Verification Oracle Probe",
+            status: probe.ok ? "pass" : "warn",
+            severity: probe.ok ? "info" : "medium",
+            summary: probe.detail,
+            evidence: [
+              { label: "primaryBinary", value: primaryBin, sensitive: false },
+              { label: "probed", value: true, sensitive: false },
+            ],
+          });
+        }
+      }
+    }
+  }
+
+  // 4c. Dependency install trees — warn only; doctor must stay exit 0 for a
+  // missing node_modules on a brand-new clone until the operator installs.
+  if (missingNodeModules(root)) {
+    addResult({
+      id: "toolchain.deps",
+      category: "Verification",
+      title: "Node Dependency Tree",
+      status: "warn",
+      severity: "medium",
+      summary: "package.json is present but node_modules/ is missing — run `npm install` (or pnpm/yarn) before verify",
+      evidence: [{ label: "nodeModules", value: false, sensitive: false }],
+      fixes: [
+        {
+          id: "toolchain.npm-install",
+          title: "Install Node dependencies",
+          summary: "Run npm install (or pnpm install / yarn) at the repository root",
+          risk: "low",
+          automatic: false,
+          requiresProbe: false,
+        },
+      ],
+    });
+  }
+
+  if (missingPythonEnv(root)) {
+    addResult({
+      id: "toolchain.python-env",
+      category: "Verification",
+      title: "Python Virtual Environment",
+      status: "warn",
+      severity: "medium",
+      summary:
+        "Python project manifest found but no usable venv (.venv/venv) — create one and install deps before verify",
+      evidence: [{ label: "venv", value: false, sensitive: false }],
+      fixes: [
+        {
+          id: "toolchain.python-venv",
+          title: "Create a Python venv",
+          summary: "Run `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt` (or poetry/uv equivalent)",
+          risk: "low",
+          automatic: false,
+          requiresProbe: false,
+        },
+      ],
+    });
+  }
+
   // 5. State & Telemetry Checks
   const telemetryDate = new Date().toISOString().split("T")[0];
   const telemetryHeadPath = join(root, ".agent", "state", `telemetry-${telemetryDate}.head`);
@@ -463,13 +583,30 @@ export async function runDoctorChecks(options = {}) {
   }
 
   // 6. VFS Locks Check
-  const locksDir = join(root, ".agent", "state", "locks");
+  const locksDir = getLockDir(root);
   let activeLockCount = 0;
+  let staleLockCount = 0;
   let lockInspectionFailed = false;
   try {
     if (existsSync(locksDir)) {
       const lockFiles = readdirSync(locksDir).filter((f) => f.endsWith(".json"));
-      activeLockCount = lockFiles.length;
+      for (const file of lockFiles) {
+        try {
+          const content = readFileSync(join(locksDir, file), "utf-8");
+          if (!content || !content.trim()) {
+            staleLockCount += 1;
+            continue;
+          }
+          const record = JSON.parse(content);
+          if (isLockLive(record)) {
+            activeLockCount += 1;
+          } else {
+            staleLockCount += 1;
+          }
+        } catch (_) {
+          staleLockCount += 1;
+        }
+      }
     }
   } catch (_) {
     lockInspectionFailed = true;
@@ -482,35 +619,50 @@ export async function runDoctorChecks(options = {}) {
       summary: "Could not inspect VFS lock directory",
     });
   }
-  if (!lockInspectionFailed && activeLockCount === 0) {
-    addResult({
-      id: "locks.active",
-      category: "State",
-      title: "VFS Active Locks",
-      status: "pass",
-      severity: "info",
-      summary: "No active VFS locks present",
-    });
-  } else if (!lockInspectionFailed) {
-    addResult({
-      id: "locks.active",
-      category: "State",
-      title: "VFS Active Locks",
-      status: "warn",
-      severity: "medium",
-      summary: `${activeLockCount} active VFS lock(s) held`,
-      evidence: [{ label: "lockCount", value: activeLockCount, sensitive: false }],
-      fixes: [
-        {
-          id: "locks.prune-stale",
-          title: "Prune stale locks",
-          summary: "Remove locks owned by dead processes",
-          risk: "low",
-          automatic: true,
-          requiresProbe: false,
-        },
-      ],
-    });
+  if (!lockInspectionFailed) {
+    if (staleLockCount > 0) {
+      addResult({
+        id: "locks.active",
+        category: "State",
+        title: "VFS Locks",
+        status: "warn",
+        severity: "medium",
+        summary: `${staleLockCount} stale VFS lock(s) detected (${activeLockCount} active)`,
+        evidence: [
+          { label: "staleLockCount", value: staleLockCount, sensitive: false },
+          { label: "activeLockCount", value: activeLockCount, sensitive: false },
+        ],
+        fixes: [
+          {
+            id: "locks.prune-stale",
+            title: "Prune stale locks",
+            summary: "Run `agentctl lock reap` to clean up dead or expired locks",
+            risk: "low",
+            automatic: true,
+            requiresProbe: false,
+          },
+        ],
+      });
+    } else if (activeLockCount === 0) {
+      addResult({
+        id: "locks.active",
+        category: "State",
+        title: "VFS Active Locks",
+        status: "pass",
+        severity: "info",
+        summary: "No active VFS locks present",
+      });
+    } else {
+      addResult({
+        id: "locks.active",
+        category: "State",
+        title: "VFS Active Locks",
+        status: "pass",
+        severity: "info",
+        summary: `${activeLockCount} active VFS lock(s) held`,
+        evidence: [{ label: "lockCount", value: activeLockCount, sensitive: false }],
+      });
+    }
   }
 
   // 7. Provider readiness — for the provider this repository actually selected.

package/src/ops/pr-harvest.mjs

@@ -102,6 +102,23 @@ export function readPrFiles(pr = {}, fileCap = 100) {
  * @param {string|string[]} tierOption
  * @returns {Set<string>}
  */
+/**
+ * Checks if a PR carries an exact hold label (case-insensitive, whitespace-trimmed).
+ * Safely handles GitHub label records ({ name }) and raw strings.
+ * @param {object} pr
+ * @returns {boolean}
+ */
+export function hasHoldLabel(pr = {}) {
+  const labels = pr && Array.isArray(pr.labels) ? pr.labels : [];
+  for (const label of labels) {
+    const name = typeof label === "string" ? label : label && typeof label === "object" ? label.name : "";
+    if (typeof name === "string" && name.trim().toLowerCase() === "hold") {
+      return true;
+    }
+  }
+  return false;
+}
+
 export function parseTierFilter(tierOption) {
   const mapShorthand = (t) => {
     const upper = String(t).toUpperCase().trim();
@@ -207,12 +224,15 @@ export async function harvestPullRequests(root = process.cwd(), options = {}) {
     const isMergeable = String(pr.mergeable || "").toUpperCase() === "MERGEABLE";
     const checksUsable = checks.passing || (checks.noChecks && allowNoChecks);
     const filesUsable = fileInfo.known && !fileInfo.truncated;
+    const isHeld = hasHoldLabel(pr);
 
-    const eligible = checksUsable && filesUsable && gate.safe && tierMatches && isMergeable;
+    const eligible = checksUsable && filesUsable && gate.safe && tierMatches && isMergeable && !isHeld;
     let actionStatus = "SKIPPED";
     let actionReason = "";
 
-    if (!filesUsable) {
+    if (isHeld) {
+      actionReason = "PR carries hold label ('hold')";
+    } else if (!filesUsable) {
       actionReason = fileInfo.truncated
         ? `Changed-file list truncated at ${files.length} entries — risk tier cannot be trusted`
         : "Changed-file list unavailable from gh — risk tier cannot be determined";

package/src/ops/toolchain-diagnostics.mjs

@@ -0,0 +1,253 @@
+/**
+ * First-run toolchain diagnostics: name the binary a verify command needs,
+ * spot missing install trees, and turn Exit-4 failure text into a targeted hint.
+ *
+ * Zero third-party deps. PATH lookup reuses whichBinary from provider-readiness.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { whichBinary } from "../provider-readiness.mjs";
+
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const SHELL_SKIP = new Set(["cd", "env", "command", "exec", "nice", "time", "nohup"]);
+
+/**
+ * Peel the primary executable out of an effective verify.test command string.
+ *
+ * Handles `PYTHONPATH=src python3 -m pytest`, `npm test`, `cargo test`, and
+ * simple `cmd && …` chains (first segment only). Returns null when nothing
+ * resolvable remains.
+ *
+ * @param {string} cmd
+ * @returns {string|null}
+ */
+export function extractPrimaryExecutable(cmd) {
+  if (!cmd || typeof cmd !== "string") return null;
+  const tokens = cmd.trim().split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < tokens.length) {
+    if (ENV_ASSIGNMENT.test(tokens[i])) {
+      i += 1;
+      continue;
+    }
+    if (tokens[i] === "cd" && tokens[i + 1] && !tokens[i + 1].startsWith("-")) {
+      i += 2;
+      if (tokens[i] === "&&" || tokens[i] === ";" || tokens[i] === "||") i += 1;
+      continue;
+    }
+    if (tokens[i] === "&&" || tokens[i] === ";" || tokens[i] === "||" || tokens[i] === "|") {
+      i += 1;
+      continue;
+    }
+    if (SHELL_SKIP.has(tokens[i])) {
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  let bin = tokens[i] || "";
+  bin = bin.replace(/^['"]|['"]$/g, "");
+  if (!bin || bin.startsWith("-")) return null;
+  // Basename for PATH lookup when the command used an absolute/relative path.
+  if (bin.includes("/") || bin.includes("\\")) {
+    const parts = bin.split(/[/\\]/);
+    const base = parts[parts.length - 1];
+    return base || bin;
+  }
+  return bin;
+}
+
+/**
+ * True when a Python virtualenv looks usable under root (or VIRTUAL_ENV).
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function hasUsableVenv(root, env = process.env) {
+  if (env.VIRTUAL_ENV && existsSync(env.VIRTUAL_ENV)) {
+    const marker = join(env.VIRTUAL_ENV, process.platform === "win32" ? "Scripts" : "bin");
+    if (existsSync(marker)) return true;
+  }
+  const candidates = [".venv", "venv", ".direnv"];
+  for (const name of candidates) {
+    const base = join(root, name);
+    const binDir = join(base, process.platform === "win32" ? "Scripts" : "bin");
+    const py = join(binDir, process.platform === "win32" ? "python.exe" : "python");
+    const py3 = join(binDir, process.platform === "win32" ? "python.exe" : "python3");
+    if (existsSync(py) || existsSync(py3)) return true;
+  }
+  return false;
+}
+
+/**
+ * True when root has a package.json but no node_modules directory.
+ * @param {string} root
+ * @returns {boolean}
+ */
+export function missingNodeModules(root) {
+  return existsSync(join(root, "package.json")) && !existsSync(join(root, "node_modules"));
+}
+
+/**
+ * True when a Python dep manifest is present without a usable venv.
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function missingPythonEnv(root, env = process.env) {
+  const hasManifest =
+    existsSync(join(root, "pyproject.toml")) ||
+    existsSync(join(root, "requirements.txt")) ||
+    existsSync(join(root, "Pipfile")) ||
+    existsSync(join(root, "setup.py"));
+  if (!hasManifest) return false;
+  return !hasUsableVenv(root, env);
+}
+
+/**
+ * Lightweight, read-only probe that the verify binary answers at all.
+ * Prefers `--version` / `-V`; for `python* -m MOD` also tries a cheap import.
+ *
+ * @param {string} root
+ * @param {string} effectiveTest
+ * @param {string} primaryBin
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ ok: boolean, detail: string }}
+ */
+export function probeOracleLightly(root, effectiveTest, primaryBin, env = process.env) {
+  if (!primaryBin) return { ok: false, detail: "No primary executable to probe" };
+  const resolved = whichBinary(primaryBin, env);
+  if (!resolved) return { ok: false, detail: `\`${primaryBin}\` is not on PATH` };
+
+  const trySpawn = (args) => {
+    try {
+      const ret = spawnSync(resolved, args, {
+        cwd: root,
+        encoding: "utf-8",
+        timeout: 8000,
+        stdio: ["ignore", "pipe", "pipe"],
+        env,
+      });
+      return ret.status === 0;
+    } catch (_) {
+      return false;
+    }
+  };
+
+  if (trySpawn(["--version"]) || trySpawn(["-V"]) || trySpawn(["version"])) {
+    return { ok: true, detail: `\`${primaryBin}\` answered a version probe` };
+  }
+
+  const modMatch = String(effectiveTest || "").match(/(?:^|\s)-m\s+(\S+)/);
+  if (modMatch && /^python/.test(primaryBin)) {
+    const mod = modMatch[1].replace(/[^A-Za-z0-9_.]/g, "");
+    if (mod && trySpawn(["-c", `import ${mod}`])) {
+      return { ok: true, detail: `\`${primaryBin} -c "import ${mod}"\` succeeded` };
+    }
+    return {
+      ok: false,
+      detail: `\`${primaryBin}\` is on PATH but could not import \`${mod || "module"}\` — install project deps / activate a venv`,
+    };
+  }
+
+  // Binary exists on PATH; version flags are optional for some tools.
+  try {
+    if (existsSync(resolved) && statSync(resolved).isFile()) {
+      return { ok: true, detail: `\`${primaryBin}\` is on PATH at ${resolved}` };
+    }
+  } catch (_) {}
+  return { ok: false, detail: `\`${primaryBin}\` did not respond to a lightweight probe` };
+}
+
+/**
+ * Name the missing binary from a failed verify stage when possible.
+ * @param {{ command?: string|null, stderr?: string, stdout?: string, error?: string, code?: string|number }} failure
+ * @returns {string|null}
+ */
+export function inferMissingBinary(failure = {}) {
+  const text = [failure.stderr, failure.stdout, failure.error, failure.message]
+    .filter(Boolean)
+    .map(String)
+    .join("\n");
+  // Node spawn: `spawnSync foo ENOENT` / `spawn foo ENOENT`
+  const spawn = text.match(/spawn(?:Sync)?(?:\s+\S+\/)*\s*([^\s/\\]+)(?:\.exe|\.cmd|\.bat)?\s+ENOENT/i);
+  if (spawn) return spawn[1];
+  const notFound = text.match(/(?:command not found|not found):\s*([^\s]+)/i);
+  if (notFound) return notFound[1].replace(/^['"`]|['"`]$/g, "");
+  if (failure.command) return extractPrimaryExecutable(String(failure.command));
+  return null;
+}
+
+/**
+ * Classify an Exit-4 verification failure for the CLI remediation hint.
+ *
+ * @param {{ exitCode?: number|null, stderr?: string, stdout?: string, error?: string|object, code?: string|number, command?: string|null, message?: string }} failure
+ * @returns {{ kind: "missing-binary"|"missing-deps"|"general", binary?: string|null, lines: string[] }}
+ */
+export function diagnoseVerifyFailure(failure = {}) {
+  const exitCode = failure.exitCode;
+  const errCode =
+    typeof failure.code === "string"
+      ? failure.code
+      : failure.error && typeof failure.error === "object" && failure.error.code
+        ? String(failure.error.code)
+        : "";
+  const text = [
+    failure.stderr || "",
+    failure.stdout || "",
+    typeof failure.error === "string" ? failure.error : failure.error?.message || "",
+    failure.message || "",
+    errCode,
+  ].join("\n");
+
+  const missingBinary =
+    exitCode === 127 ||
+    errCode === "ENOENT" ||
+    /\bENOENT\b/i.test(text) ||
+    /command not found/i.test(text) ||
+    /is not recognized as an internal or external command/i.test(text);
+
+  if (missingBinary) {
+    const binary = inferMissingBinary(failure);
+    const named = binary ? `\`${binary}\`` : "the required binary";
+    return {
+      kind: "missing-binary",
+      binary,
+      lines: [
+        `Verification could not start because ${named} is missing from PATH (exit ${exitCode ?? "n/a"}).`,
+        binary
+          ? `Install \`${binary}\`, or set verify.test in .agent/config.yml to a command this machine has.`
+          : "Install the missing tool, or set verify.test in .agent/config.yml to a command this machine has.",
+      ],
+    };
+  }
+
+  const missingDeps =
+    /Cannot find module\b/i.test(text) ||
+    /ModuleNotFoundError\b/i.test(text) ||
+    /No module named\b/i.test(text) ||
+    /Could not find a version that satisfies/i.test(text);
+
+  if (missingDeps) {
+    const isPy = /ModuleNotFoundError\b|No module named\b/i.test(text);
+    return {
+      kind: "missing-deps",
+      lines: [
+        "Verification failed because a required dependency is not installed.",
+        isPy
+          ? "Create/activate a venv and install deps (e.g. `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`), then re-run the gate."
+          : "Install project dependencies (e.g. `npm install` / `pnpm install`), then re-run the gate.",
+      ],
+    };
+  }
+
+  return {
+    kind: "general",
+    lines: [
+      "The stage above exited non-zero. Reproduce it locally, then re-run the gate.",
+      "To start an explicit repair workflow, pipe the failing command's output to: agentctl repair",
+    ],
+  };
+}