jules-orchestrator-kit 0.1.9 → 0.2.9

package/scripts/jules-dispatch.mjs

@@ -3,12 +3,15 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { resolveProjectCommands } from "./command-resolver.mjs";
 
-const taskTitle = process.argv[2];
-const taskPromptArg = process.argv[3];
+const isMainModule = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
 
-if (!taskTitle || !taskPromptArg) {
+const taskTitle = isMainModule ? process.argv[2] : "";
+const taskPromptArg = isMainModule ? process.argv[3] : "";
+
+if (isMainModule && (!taskTitle || !taskPromptArg)) {
   console.error(
     'Usage: node scripts/jules-dispatch.mjs <task-title> <path-to-prompt.md | "raw prompt string">'
   );
@@ -39,9 +42,41 @@ function loadEnv() {
 }
 loadEnv();
 
-// 0.1 Pre-Flight Secret Redaction Gate
-function redactSecrets(text) {
+// 0.1 Shannon Entropy Calculator
+export function calculateEntropy(str) {
+  if (!str) return 0;
+  const len = str.length;
+  const frequencies = {};
+  for (let i = 0; i < len; i++) {
+    const char = str[i];
+    frequencies[char] = (frequencies[char] || 0) + 1;
+  }
+  let entropy = 0;
+  for (const char in frequencies) {
+    const p = frequencies[char] / len;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+// 0.2 Pre-Flight Secret Redaction Gate (RegEx + Shannon Entropy + Env Denylist)
+export function redactSecrets(text) {
   if (!text) return "";
+  let sanitized = text;
+
+  // Redact active env secrets from denylist keys (*_KEY, *_SECRET, *_TOKEN, etc.)
+  for (const [envKey, envVal] of Object.entries(process.env)) {
+    if (
+      envVal &&
+      envVal.length >= 6 &&
+      /KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|AUTH/i.test(envKey)
+    ) {
+      if (sanitized.includes(envVal)) {
+        sanitized = sanitized.split(envVal).join("[REDACTED_ENV_SECRET]");
+      }
+    }
+  }
+
   const patterns = [
     /gh[pusr]_[a-zA-Z0-9]{36}/g,
     /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/g,
@@ -52,110 +87,143 @@ function redactSecrets(text) {
     /sk-(?:ant-api03-|proj-|svcacct-)[a-zA-Z0-9\-\_]{32,}/g,
     /xox[baprs]-[a-zA-Z0-9\-]{10,}/g,
     /eyJ[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}/g,
-    /-----BEGIN (?:RSA|OPENSSH|EC|PRIVATE) KEY-----[\s\S]*?-----END (?:RSA|OPENSSH|EC|PRIVATE) KEY-----/,
+    /-----BEGIN (?:RSA|OPENSSH|EC|PRIVATE) KEY-----[\s\S]*?-----END (?:RSA|OPENSSH|EC|PRIVATE) KEY-----/g,
   ];
-  let sanitized = text;
   for (const pat of patterns) {
     sanitized = sanitized.replace(pat, "[REDACTED_BY_SECURITY_GATE]");
   }
+  // Exclude file paths (tokens with slashes or common extensions) from entropy redaction
+  sanitized = sanitized.replace(/[a-zA-Z0-9_\-\.]{20,}/g, (token) => {
+    if (
+      token.startsWith("[REDACTED_") ||
+      token.includes("/") ||
+      /\.(?:ts|js|jsx|tsx|json|md|py|rs|go|yml|yaml|toml|html|css|sh|config)$/i.test(token)
+    ) {
+      return token;
+    }
+    const entropy = calculateEntropy(token);
+    if (entropy > 3.6) {
+      return "[REDACTED_ENTROPY_KEY]";
+    }
+    return token;
+  });
   return sanitized;
 }
 
-// 1. Resolve prompt content (file path or inline string)
-let rawPrompt = "";
-const possiblePath = path.resolve(process.cwd(), taskPromptArg);
-if (fs.existsSync(possiblePath) && fs.statSync(possiblePath).isFile()) {
-  rawPrompt = fs.readFileSync(possiblePath, "utf-8");
-} else {
-  rawPrompt = taskPromptArg;
+// 0.3 Hardened Path Traversal & Symlink Defense
+export function assertPathWithinWorkspace(targetPath, workspaceRoot = process.cwd()) {
+  const rootReal = fs.existsSync(workspaceRoot) ? fs.realpathSync(path.resolve(workspaceRoot)) : path.resolve(workspaceRoot);
+  const resolvedTarget = path.resolve(rootReal, targetPath);
+  const targetReal = fs.existsSync(resolvedTarget) ? fs.realpathSync(resolvedTarget) : resolvedTarget;
+  const normalizedRoot = rootReal.replace(/\\/g, "/");
+  const normalizedTarget = targetReal.replace(/\\/g, "/");
+  if (!normalizedTarget.startsWith(normalizedRoot)) {
+    throw new Error(`FATAL: Sandboxed directory traversal breach blocked for path: ${targetPath}`);
+  }
+  return targetReal;
 }
-rawPrompt = redactSecrets(rawPrompt);
-
-// 2. Dynamic Guardrail Composition (DGC) from .agent/rules/dynamic-guardrails.json
-function getDynamicGuardrails(promptText) {
-  const guardrailsPath = path.resolve(process.cwd(), ".agent/rules/dynamic-guardrails.json");
-  if (!fs.existsSync(guardrailsPath)) return "";
 
-  try {
-    const data = JSON.parse(fs.readFileSync(guardrailsPath, "utf-8"));
-    if (!data.rules || !Array.isArray(data.rules)) return "";
-
-    const active = [];
-    for (const item of data.rules) {
-      if (new RegExp(item.trigger, "i").test(promptText)) {
-        active.push(item.guardrail);
-      }
-    }
-    return active.join("\n\n");
-  } catch (e) {
-    return "";
+// 0.4 Dynamic Guardrails & Directive Definitions
+export function getDynamicGuardrails(prompt = "") {
+  const guardrails = [];
+  if (/\b(?:astro|components|pages|src\/.*\.astro)\b/i.test(prompt)) {
+    guardrails.push("- Astro Guidance: Ensure zero client JS shipped by default. Use server islands or nano stores if state is required.");
+  }
+  if (/\b(?:db|database|d1|postgres|drizzle|migration|schema)\b/i.test(prompt)) {
+    guardrails.push("- Database Guidance: Do not modify migrations directly without inspecting current schema constraints.");
   }
+  return guardrails.length > 0 ? `## Context-Specific Guardrails\n${guardrails.join("\n")}` : "";
 }
 
-// 3. Dynamic Command Resolution (Language & Framework Detection)
-const resolvedCmds = resolveProjectCommands(process.cwd());
-const verifyDirective = resolvedCmds.testCmd || resolvedCmds.buildCmd
-  ? `\n\n## 🛠️ MANDATORY VERIFICATION COMMANDS\nBefore submitting PR, you MUST execute: \`${[resolvedCmds.testCmd, resolvedCmds.buildCmd].filter(Boolean).join(" && ")}\``
-  : "";
-
-// 4. Load Base Rules / Guardrails
-const rulesPath = fs.existsSync(path.resolve(process.cwd(), "AGENTS.md"))
-  ? path.resolve(process.cwd(), "AGENTS.md")
-  : path.resolve(process.cwd(), "JULES_RULES_TEMPLATE.md");
-
-const baseRules = fs.existsSync(rulesPath)
-  ? fs.readFileSync(rulesPath, "utf-8")
-  : "";
-
-const dynamicRules = getDynamicGuardrails(rawPrompt);
-
-// Machine XML Directives
-const envelope = `
-<MCP_DIRECTIVE>
-  <system_state>HEADLESS_CI_MODE</system_state>
-  <strict_invariants>
-    <rule>1. READ-BEFORE-WRITE (ZERO HALLUCINATION): You are FORBIDDEN from guessing internal API signatures. Before editing, use search tools or MCP doc tools to verify exact signatures.</rule>
-    <rule>2. VERIFICATION LOOP: After patching code, you MUST execute the verification commands and ensure 0 errors.</rule>
-    <rule>3. ABORT CONDITION: On repeated unresolvable test failures, output <status>ABORT_UNRESOLVABLE</status> and terminate.</rule>
-  </strict_invariants>
-</MCP_DIRECTIVE>
-`.trim();
-
-const fullPrompt = redactSecrets(`MCP DIRECTIVE: ${rawPrompt.trim()}${verifyDirective}\n\n---\n\n${envelope}\n\n---\n\n${dynamicRules ? `${dynamicRules}\n\n---\n\n` : ""}${baseRules.trim()}`);
-
-// 5. Log Dispatch History
-const dateStr = new Date().toISOString().split("T")[0];
-const slug = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
-
-const historyDir = path.resolve(process.cwd(), ".agent/history");
-if (!fs.existsSync(historyDir)) {
-  fs.mkdirSync(historyDir, { recursive: true });
+function getBaseRules(projectRoot = process.cwd()) {
+  const templatePath = path.join(projectRoot, "JULES_RULES_TEMPLATE.md");
+  if (fs.existsSync(templatePath)) {
+    return fs.readFileSync(templatePath, "utf-8");
+  }
+  const agentsPath = path.join(projectRoot, "AGENTS.md");
+  if (fs.existsSync(agentsPath)) {
+    return fs.readFileSync(agentsPath, "utf-8");
+  }
+  return `## Operational Directives
+- **Read Before Write**: Always inspect target files and symbol definitions before modifying code.
+- **Verification**: Execute test and build verification suite and ensure 0 errors.
+- **Anti-Patch Invariant**: Do NOT create out-of-band shell scripts (patch.sh, test-fix.sh) or disable assertions to force tests to pass.`;
 }
-const historyFile = path.join(historyDir, `${dateStr}-dispatch-${slug}.md`);
-fs.writeFileSync(historyFile, `---\ntype: jules_dispatch\ntitle: "${taskTitle}"\ntimestamp: "${new Date().toISOString()}"\n---\n# Jules Task Dispatch: ${taskTitle}\n\n## Prompt\n${rawPrompt}\n`, "utf-8");
 
-console.log(`🚀 Dispatching task to Google Jules: "${taskTitle}"...`);
-console.log(`📝 Logged dispatch history to: ${path.relative(process.cwd(), historyFile)}`);
+// 1. Resolve prompt content and construct directive envelope
+let rawPrompt = "";
+let fullPrompt = "";
+let historyFile = "";
+let tmpPayloadFile = "";
+let tmpDir = "";
+
+const apiKey = process.env.JULES_API_KEY || process.env.GEMINI_API_KEY || "";
+const repo = process.env.JULES_REPO || "";
+
+if (isMainModule) {
+  const possiblePath = path.resolve(process.cwd(), taskPromptArg);
+  if (fs.existsSync(possiblePath) && fs.statSync(possiblePath).isFile()) {
+    assertPathWithinWorkspace(possiblePath);
+    rawPrompt = fs.readFileSync(possiblePath, "utf-8");
+  } else {
+    rawPrompt = taskPromptArg;
+  }
+  rawPrompt = redactSecrets(rawPrompt);
+
+  const dynamicRules = getDynamicGuardrails(rawPrompt);
+  const baseRules = getBaseRules(process.cwd());
+  const envelope = `## Envelope Directives
+- **Zero Hallucination:** Inspect exact symbol definitions before editing.
+- **Verification:** Execute project verification suite and ensure 0 errors.
+- **Anti-Patch / Zero Out-of-band Scripts:** Do NOT create workaround runner scripts (e.g. patch.sh, test-fix.sh) or disable assertions to pass tests.`;
+
+  const { testCmd, buildCmd } = resolveProjectCommands(process.cwd());
+  const verifyDirective = testCmd || buildCmd 
+    ? `\n\nVERIFICATION DIRECTIVE: Execute \`${[testCmd, buildCmd].filter(Boolean).join(" && ")}\` after patching.`
+    : "";
+
+  fullPrompt = redactSecrets(`MCP DIRECTIVE: ${rawPrompt.trim()}${verifyDirective}\n\n---\n\n${envelope}\n\n---\n\n${dynamicRules ? `${dynamicRules}\n\n---\n\n` : ""}${baseRules.trim()}`);
+
+  const dateStr = new Date().toISOString().split("T")[0];
+  const slug = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+
+  // Resolve history directory relative to main workspace root, avoiding temporary worktrees
+  const mainWorkspaceRoot = process.env.JULES_PROJECT_ROOT || process.env.INIT_CWD || process.cwd();
+  const historyDir = path.resolve(mainWorkspaceRoot, ".agent/history");
+  if (!fs.existsSync(historyDir)) {
+    fs.mkdirSync(historyDir, { recursive: true });
+  }
+  historyFile = path.join(historyDir, `${dateStr}-dispatch-${slug}.md`);
+  fs.writeFileSync(historyFile, `---\ntype: jules_dispatch\ntitle: "${taskTitle}"\ntimestamp: "${new Date().toISOString()}"\n---\n# Jules Task Dispatch: ${taskTitle}\n\n## Prompt\n${rawPrompt}\n`, "utf-8");
 
-// 6. Dispatch via REST API or Ephemeral Payload File (Avoid ARG_MAX shell limits)
-const apiKey = process.env.JULES_API_KEY;
-const repo = process.env.JULES_REPO;
+  console.log(`🚀 Dispatching task to Google Jules: "${taskTitle}"...`);
+  console.log(`📝 Logged dispatch history to: ${path.relative(process.cwd(), historyFile)}`);
 
-const payloadHash = crypto.createHash("sha256").update(taskTitle + Date.now()).digest("hex").slice(0, 12);
-const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "jules-payload-"));
-const tmpPayloadFile = path.join(tmpDir, `payload_${payloadHash}.json`);
-fs.writeFileSync(tmpPayloadFile, JSON.stringify({ repo, title: taskTitle, prompt: fullPrompt }), { mode: 0o600 });
+  const payloadHash = crypto.createHash("sha256").update(taskTitle + Date.now()).digest("hex").slice(0, 12);
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "jules-payload-"));
+  tmpPayloadFile = path.join(tmpDir, `payload_${payloadHash}.json`);
+  fs.writeFileSync(tmpPayloadFile, JSON.stringify({ repo, title: taskTitle, prompt: fullPrompt }), { mode: 0o600 });
+}
 
 function cleanupTmp() {
   try {
     if (fs.existsSync(tmpDir)) {
       fs.rmSync(tmpDir, { recursive: true, force: true });
     }
-  } catch (_) {}
+  } catch (err) {
+    console.warn(`⚠️ Failed to remove temporary payload directory at ${tmpDir}:`, err.message);
+  }
 }
 
 async function executeDispatch() {
   try {
+    if (process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1") {
+      console.log(`[DRY RUN] Dispatch payload prepared successfully for task: "${taskTitle}".`);
+      console.log(`[DRY RUN] Target Repository: ${repo || "(default)"}`);
+      console.log(`[DRY RUN] Prompt Length: ${fullPrompt.length} chars.`);
+      return;
+    }
+
     if (apiKey && repo) {
       console.log(`🌐 Using Jules REST API for repository ${repo}...`);
       const formattedSource = repo.startsWith("sources/") ? repo : (repo.includes("/") ? `sources/github/${repo}` : repo);
@@ -172,7 +240,8 @@ async function executeDispatch() {
 
       let res;
       try {
-        res = await fetch("https://jules.googleapis.com/v1alpha/sessions", {
+        const apiUrl = process.env.JULES_API_URL || "https://jules.googleapis.com/v1alpha/sessions";
+        res = await fetch(apiUrl, {
           method: "POST",
           headers: {
             "X-Goog-Api-Key": apiKey,
@@ -202,7 +271,9 @@ async function executeDispatch() {
       try {
         const data = await res.json();
         sessionId = data.name || data.id || sessionId;
-      } catch (_) {}
+      } catch (jsonErr) {
+        console.warn("⚠️ Failed to parse REST API JSON response:", jsonErr.message);
+      }
 
       console.log(`✅ REST API Dispatch response: Session ${sessionId} created successfully.`);
       fs.appendFileSync(historyFile, `\n## Session\n- ID: \`${sessionId}\`\n`);
@@ -214,7 +285,6 @@ async function executeDispatch() {
   }
 }
 
-
 function dispatchViaCli(targetRepo, payloadFile, title) {
   try {
     let promptToSend = fullPrompt;
@@ -222,7 +292,9 @@ function dispatchViaCli(targetRepo, payloadFile, title) {
       try {
         const payloadData = JSON.parse(fs.readFileSync(payloadFile, "utf-8"));
         if (payloadData.prompt) promptToSend = payloadData.prompt;
-      } catch (_) {}
+      } catch (jsonErr) {
+        console.warn("⚠️ Failed to parse payload JSON file:", jsonErr.message);
+      }
     }
 
     const args = ["new"];
@@ -239,10 +311,9 @@ function dispatchViaCli(targetRepo, payloadFile, title) {
   }
 }
 
-
-executeDispatch().catch((err) => {
-  console.error("❌ Fatal unhandled rejection in dispatch:", err);
-  process.exit(1);
-});
-
-
+if (isMainModule) {
+  executeDispatch().catch((err) => {
+    console.error("❌ Fatal unhandled rejection in dispatch:", err);
+    process.exit(1);
+  });
+}

package/scripts/jules-queue-runner.mjs

@@ -1,9 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const dispatchScript = path.resolve(__dirname, "jules-dispatch.mjs");
+
 const queueDir = path.resolve(process.cwd(), ".agent/jules-queue");
 const completedDir = path.resolve(process.cwd(), ".agent/jules-queue/completed");
+const queueLogFile = path.join(queueDir, "queue.jsonl");
 
 if (!fs.existsSync(queueDir)) {
   console.error(`❌ Queue directory not found: ${queueDir}`);
@@ -14,11 +20,20 @@ if (!fs.existsSync(completedDir)) {
   fs.mkdirSync(completedDir, { recursive: true });
 }
 
+function logQueueState(file, status, error = null) {
+  const entry = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    file,
+    status,
+    error: error ? error.message || String(error) : null,
+  }) + "\n";
+  fs.appendFileSync(queueLogFile, entry, "utf-8");
+}
+
 const files = fs.readdirSync(queueDir).filter(
   (f) => f.endsWith(".md") && f !== "README.md" && !f.startsWith("_") && !f.startsWith(".")
 );
 
-
 if (files.length === 0) {
   console.log("ℹ️ No tasks found in the queue.");
   process.exit(0);
@@ -33,17 +48,20 @@ files.forEach((file, index) => {
   
   console.log(`\n----------------------------------------`);
   console.log(`[${index + 1}/${files.length}] Dispatching queued task: ${title}`);
+  logQueueState(file, "RUNNING");
   
   try {
-    execFileSync("node", ["scripts/jules-dispatch.mjs", title, filePath], {
+    execFileSync("node", [dispatchScript, title, filePath], {
       stdio: "inherit",
     });
     
     // Move to completed
     const destPath = path.join(completedDir, file);
     fs.renameSync(filePath, destPath);
+    logQueueState(file, "COMPLETED");
     console.log(`✅ Moved ${file} to completed/`);
   } catch (error) {
+    logQueueState(file, "FAILED", error);
     console.error(`⚠️ Failed to dispatch task [${title}]:`, error.message);
   }
 });

package/scripts/jules-self-audit.mjs

@@ -43,6 +43,14 @@ export function matchGlob(filepath, globPattern) {
 }
 
 
+/**
+ * Lightweight Zero-Dependency YAML Pattern Extractor
+ * Extracts forbidden_paths and allow_paths arrays from jules.yml.
+ * Supported subset:
+ *  - Flow style arrays: forbidden_paths: ["path1", "path2"]
+ *  - Block style arrays: forbidden_paths:\n  - path1\n  - path2
+ * Limitations: Does not support multiline strings (|/>), nested dicts, or inline comments.
+ */
 export function loadForbiddenPatterns(configContent = "") {
   const defaultForbidden = [
     ".github/**",
@@ -112,10 +120,35 @@ export function loadAllowedPatterns(configContent = "") {
   return blockParsed;
 }
 
+export function parseAndCleanStderr(stderrStr) {
+  if (!stderrStr) return "";
+  const clean = stderrStr.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
+  const lines = clean.split("\n").filter(Boolean);
+  return lines.slice(-100).join("\n");
+}
+
+export function logAuditMetrics(metrics) {
+  const historyDir = path.resolve(process.cwd(), ".agent/history");
+  if (!fs.existsSync(historyDir)) {
+    fs.mkdirSync(historyDir, { recursive: true });
+  }
+  const metricsFile = path.join(historyDir, "metrics.jsonl");
+  const logLine = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    ...metrics,
+  }) + "\n";
+  fs.appendFileSync(metricsFile, logLine, "utf-8");
+}
+
 export function runSelfAudit() {
   console.log("🔍 Running Jules PR Self-Audit Gatekeeper...\n");
 
   const targetBranch = process.env.BASE_BRANCH || "main";
+  const SAFE_BRANCH = /^[a-zA-Z0-9._\/-]+$/;
+  if (!SAFE_BRANCH.test(targetBranch)) {
+    console.error(`❌ FATAL: Invalid BASE_BRANCH "${targetBranch}". Must match ^[a-zA-Z0-9._\\/-]+$`);
+    process.exit(1);
+  }
   console.log(`🎯 Target Branch: ${targetBranch}`);
 
   if (process.env.CI) {
@@ -150,7 +183,6 @@ export function runSelfAudit() {
   const forbiddenPatterns = loadForbiddenPatterns(trustedConfig);
   const allowedPatterns = loadAllowedPatterns(trustedConfig);
 
-
   const violations = rawDiffFiles.filter((file) => {
     const isForbidden = forbiddenPatterns.some((pattern) => matchGlob(file, pattern));
     if (!isForbidden) return false;
@@ -166,18 +198,38 @@ export function runSelfAudit() {
   }
   console.log("\n✅ Restricted File Boundary Check: PASSED");
 
-
   console.log("\n🛠️ Resolving Dynamic Verification Suite...");
   const resolvedCmds = resolveWorkspaceExecutionBoundary(changedCodeFiles, process.cwd());
   console.log(`📋 Discovered Execution Scope: ${resolvedCmds.source}`);
 
+  const startTime = Date.now();
+  let testPassed = true;
+  let failureLog = "";
+
+  const runVerification = (cmd) => {
+    try {
+      execSync(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+      return true;
+    } catch (err) {
+      failureLog = parseAndCleanStderr((err.stderr || "") + "\n" + (err.stdout || "") + "\n" + (err.message || ""));
+      return false;
+    }
+  };
+
   if (resolvedCmds.testCmd) {
     console.log(`▶ Running Test Verification: ${resolvedCmds.testCmd}`);
-    runCommand(resolvedCmds.testCmd);
+    if (!runVerification(resolvedCmds.testCmd)) {
+      testPassed = false;
+      console.error(`❌ Test verification failed: ${resolvedCmds.testCmd}`);
+    }
   }
-  if (resolvedCmds.buildCmd) {
+
+  if (testPassed && resolvedCmds.buildCmd) {
     console.log(`▶ Running Build Verification: ${resolvedCmds.buildCmd}`);
-    runCommand(resolvedCmds.buildCmd);
+    if (!runVerification(resolvedCmds.buildCmd)) {
+      testPassed = false;
+      console.error(`❌ Build verification failed: ${resolvedCmds.buildCmd}`);
+    }
   }
 
   if (!resolvedCmds.testCmd && !resolvedCmds.buildCmd) {
@@ -185,6 +237,21 @@ export function runSelfAudit() {
     runCommand("git status");
   }
 
+  const durationMs = Date.now() - startTime;
+  logAuditMetrics({
+    targetBranch,
+    changedFilesCount: changedCodeFiles.length,
+    testPassed,
+    durationMs,
+    scope: resolvedCmds.source,
+  });
+
+  if (!testPassed) {
+    console.error("\n🔄 OODA SELF-HEALING FEEDBACK LOG:");
+    console.error(failureLog.slice(-1500));
+    process.exit(1);
+  }
+
   console.log("\n🎉 JULES PR SELF-AUDIT PASSED SUCCESSFULLY!");
 }
 

package/scripts/jules-swarm.mjs

@@ -9,7 +9,7 @@ const tasksFile = process.argv[2];
 
 if (!tasksFile) {
   console.error("Usage: node scripts/jules-swarm.mjs <path-to-tasks.json>");
-  console.error('Format of tasks.json: [ { "id": "t1", "title": "Task 1", "prompt": "Description 1" } ]');
+  console.error('Format of tasks.json: [ { "id": "t1", "title": "Task 1", "prompt": "Description 1", "scope": ["src/moduleA/**"] } ]');
   process.exit(1);
 }
 
@@ -25,15 +25,61 @@ if (!Array.isArray(tasks)) {
   process.exit(1);
 }
 
-const MAX_CONCURRENT = parseInt(process.env.JULES_SWARM_CONCURRENCY || "3", 10);
-const STAGGER_MS = parseInt(process.env.JULES_SWARM_STAGGER_MS || "1500", 10);
+const parsedConcurrent = parseInt(process.env.JULES_SWARM_CONCURRENCY || "3", 10);
+const MAX_CONCURRENT = Number.isFinite(parsedConcurrent) && parsedConcurrent > 0 ? parsedConcurrent : 3;
 
-console.log(`🐝 Launching Jules Swarm Orchestrator (${tasks.length} tasks, Concurrency: ${MAX_CONCURRENT})...`);
+const parsedStagger = parseInt(process.env.JULES_SWARM_STAGGER_MS || "1500", 10);
+const STAGGER_MS = Number.isFinite(parsedStagger) && parsedStagger >= 0 ? parsedStagger : 1500;
+
+const USE_WORKTREES = process.env.JULES_USE_WORKTREES === "true";
+
+// Ensure root project path is preserved for history logs even when running in worktrees
+process.env.JULES_PROJECT_ROOT = process.cwd();
+
+console.log(`🐝 Launching Jules Swarm Orchestrator (${tasks.length} tasks, Concurrency: ${MAX_CONCURRENT}, Worktrees: ${USE_WORKTREES ? "ENABLED" : "DISABLED"})...`);
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+async function createWorktree(taskId) {
+  const slug = taskId.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  const wtDir = path.resolve(process.cwd(), `.agent/worktrees/${slug}`);
+  const branchName = `jules/${slug}`;
+  try {
+    if (!fs.existsSync(path.dirname(wtDir))) {
+      fs.mkdirSync(path.dirname(wtDir), { recursive: true });
+    }
+    await execFileAsync("git", ["worktree", "add", "-b", branchName, wtDir, "HEAD"]);
+    return { wtDir, branchName };
+  } catch (err) {
+    try {
+      await execFileAsync("git", ["worktree", "add", "--force", wtDir, "HEAD"]);
+      return { wtDir, branchName: null };
+    } catch (fallbackErr) {
+      console.warn(`⚠️ Failed to create worktree for ${taskId}:`, fallbackErr.message);
+      return null;
+    }
+  }
+}
+
+async function removeWorktree(wtDir, branchName) {
+  if (!wtDir) return;
+  try {
+    await execFileAsync("git", ["worktree", "remove", "--force", wtDir]);
+  } catch (err) {
+    console.warn(`⚠️ Failed to remove worktree at ${wtDir}:`, err.message);
+  }
+  if (branchName) {
+    try {
+      await execFileAsync("git", ["branch", "-D", branchName]);
+    } catch (err) {
+      console.warn(`⚠️ Failed to delete swarm branch ${branchName}:`, err.message);
+    }
+  }
+}
+
 async function runSwarm() {
   const results = [];
+  let hasFailure = false;
 
   for (let i = 0; i < tasks.length; i += MAX_CONCURRENT) {
     const batch = tasks.slice(i, i + MAX_CONCURRENT);
@@ -49,15 +95,39 @@ async function runSwarm() {
         console.log(`\n----------------------------------------`);
         console.log(`[${taskNum}/${tasks.length}] Dispatching Swarm Task: ${task.title} (${taskId})`);
 
+        let wtInfo = null;
+        let execCwd = process.cwd();
+
+        if (USE_WORKTREES) {
+          wtInfo = await createWorktree(taskId);
+          if (wtInfo?.wtDir) {
+            execCwd = wtInfo.wtDir;
+            console.log(`🌲 Isolated Task ${taskId} in Git Worktree: ${wtInfo.wtDir}`);
+          }
+        }
+
+        let effectivePrompt = task.prompt || "";
+        if (task.scope) {
+          const scopeStr = typeof task.scope === "string" ? task.scope : JSON.stringify(task.scope);
+          effectivePrompt += `\n\n[SCOPE LOCK]\nStrictly limit changes to designated bounds: ${scopeStr}`;
+        }
+
         try {
-          const { stdout } = await execFileAsync("node", ["scripts/jules-dispatch.mjs", task.title, task.prompt], {
+          const dispatchScript = path.resolve(process.cwd(), "scripts/jules-dispatch.mjs");
+          const { stdout } = await execFileAsync("node", [dispatchScript, task.title, effectivePrompt], {
+            cwd: execCwd,
             timeout: 15 * 60 * 1000,
+            env: { ...process.env, JULES_PROJECT_ROOT: process.env.JULES_PROJECT_ROOT },
           });
           if (stdout) console.log(stdout.trim());
           return { taskId, title: task.title, status: "SUCCESS" };
         } catch (error) {
           console.error(`⚠️ Failed task [${task.title}]:`, error.message);
           return { taskId, title: task.title, status: "FAILED", error: error.message };
+        } finally {
+          if (wtInfo?.wtDir) {
+            await removeWorktree(wtInfo.wtDir, wtInfo.branchName);
+          }
         }
       })
     );
@@ -65,8 +135,10 @@ async function runSwarm() {
     for (const r of batchResults) {
       if (r.status === "fulfilled") {
         results.push(r.value);
+        if (r.value.status === "FAILED") hasFailure = true;
       } else {
         results.push({ title: "Unknown Task", status: "FAILED", error: r.reason });
+        hasFailure = true;
       }
     }
 
@@ -81,7 +153,13 @@ async function runSwarm() {
   results.forEach((res) => {
     console.log(`  - [${res.status}] ${res.title}`);
   });
-}
 
-runSwarm();
+  if (hasFailure) {
+    process.exitCode = 1;
+  }
+}
 
+runSwarm().catch((err) => {
+  console.error("❌ Unhandled swarm rejection:", err);
+  process.exit(1);
+});