jules-orchestrator-kit 0.5.1 → 0.6.0

package/scripts/jules-self-audit.mjs

@@ -5,16 +5,16 @@ import crypto from "node:crypto";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
 import { resolveWorkspaceExecutionBoundary } from "./command-resolver.mjs";
-import { log, logToHistory } from "./utils.mjs";
+import { log, logToHistory, redactSecrets } from "./utils.mjs";
 
 function runGitCommand(args, ignoreError = false) {
   try {
     return execFileSync("git", args, { encoding: "utf-8" }).trim();
   } catch (error) {
     if (ignoreError) return "";
-    log.error(`Git command failed: git ${args.join(" ")}`);
-    log.error(error.message);
-    process.exit(1);
+    const err = new Error(`Git command failed: git ${args.join(" ")}\n${error.message}`);
+    err.code = 1;
+    throw err;
   }
 }
 
@@ -33,7 +33,7 @@ export function matchGlob(filepath, globPattern) {
         seg
           .replace(/[.+^${}()|[\]\\]/g, "\\$&")
           .replace(/\*/g, "[^/]*")
-          .replace(/\?/g, ".")
+          .replace(/\?/g, "[^/]")
       );
     }
   }
@@ -50,6 +50,32 @@ export function matchGlob(filepath, globPattern) {
 }
 
 
+export const COMMAND_DEFINING_FILES = [
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "yarn.lock",
+  "bun.lockb",
+  "turbo.json",
+  "nx.json",
+  "lerna.json",
+  "rush.json",
+  "Cargo.toml",
+  "Cargo.lock",
+  "go.mod",
+  "go.sum",
+  "pyproject.toml",
+  "setup.py",
+  "requirements.txt",
+  "Makefile",
+  "build.gradle",
+  "build.gradle.kts",
+  "pom.xml",
+  ".agent/jules.yml",
+  "jules.config.json"
+];
+
 /**
  * Lightweight Zero-Dependency YAML Pattern Extractor
  * Extracts forbidden_paths and allow_paths arrays from jules.yml.
@@ -153,16 +179,18 @@ export function runSelfAudit() {
   const targetBranch = process.env.BASE_BRANCH || "main";
   const SAFE_BRANCH = /^[a-zA-Z0-9._\/-]+$/;
   if (!SAFE_BRANCH.test(targetBranch)) {
-    log.error(`FATAL: Invalid BASE_BRANCH "${targetBranch}". Must match ^[a-zA-Z0-9._\\/-]+$`);
-    process.exit(2);
+    const err = new Error(`FATAL: Invalid BASE_BRANCH "${targetBranch}". Must match ^[a-zA-Z0-9._\\/-]+$`);
+    err.code = 2;
+    throw err;
   }
   log.info(`Target Branch: ${targetBranch}`);
 
   try {
     execFileSync("git", ["--version"], { stdio: "ignore" });
   } catch {
-    log.error("FATAL: git is not installed or not in PATH.");
-    process.exit(2);
+    const err = new Error("FATAL: git is not installed or not in PATH.");
+    err.code = 2;
+    throw err;
   }
 
   if (process.env.CI) {
@@ -180,8 +208,9 @@ export function runSelfAudit() {
   const mergeBase = runGitCommand(["merge-base", "HEAD", mainRef], true);
 
   if (!mergeBase) {
-    log.error(`FATAL: Could not compute merge-base with ${mainRef}. Make sure git history is unshallowed.`);
-    process.exit(2);
+    const err = new Error(`FATAL: Could not compute merge-base with ${mainRef}. Make sure git history is unshallowed.`);
+    err.code = 2;
+    throw err;
   }
 
   log.info(`Merge-Base Hash: ${mergeBase}`);
@@ -191,6 +220,18 @@ export function runSelfAudit() {
     .map((f) => f.trim().replace(/^["']|["']$/g, ""))
     .filter(Boolean);
 
+  const commandFileChanges = rawDiffFiles.filter((file) =>
+    COMMAND_DEFINING_FILES.some((cmdFile) => file === cmdFile || file.endsWith(`/${cmdFile}`))
+  );
+
+  if (commandFileChanges.length > 0 && process.env.JULES_ALLOW_COMMAND_FILE_CHANGES !== "true" && process.env.JULES_ALLOW_COMMAND_FILE_CHANGES !== "1") {
+    const err = new Error(
+      "COMMAND FILE CHANGE DETECTED: " + commandFileChanges.join(", ") + ". Refusing to execute verification scripts from untrusted branch."
+    );
+    err.code = 3;
+    throw err;
+  }
+
   const isBloatFile = (file) => /(\.lock|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|\.png|\.jpg|\.jpeg|\.pdf|\.min\.js|\.map)$/i.test(file);
   const changedCodeFiles = rawDiffFiles.filter((f) => !isBloatFile(f));
 
@@ -205,21 +246,72 @@ export function runSelfAudit() {
 
   const violations = rawDiffFiles.filter((file) => {
     const isForbidden = forbiddenPatterns.some((pattern) => matchGlob(file, pattern));
-    if (!isForbidden) return false;
-    const isAllowed = allowedPatterns.some((pattern) => matchGlob(file, pattern));
-    return !isAllowed;
+    if (isForbidden) return true; // Immutable forbidden path — CANNOT be overridden by allow_paths
+    if (allowedPatterns.length > 0) {
+      const isAllowed = allowedPatterns.some((pattern) => matchGlob(file, pattern));
+      return !isAllowed;
+    }
+    return false;
   });
 
   if (violations.length > 0) {
-    log.error("RESTRICTED FILE VIOLATION DETECTED!");
-    log.error("Jules PR attempted to modify forbidden system files:");
-    violations.forEach((v) => log.error(`   - ${v}`));
-    process.exit(3);
+    const err = new Error("RESTRICTED FILE VIOLATION DETECTED: " + violations.join(", "));
+    err.code = 3;
+    throw err;
   }
   log.success("Restricted File Boundary Check: PASSED");
 
-  log.info("Resolving Dynamic Verification Suite...");
-  const resolvedCmds = resolveWorkspaceExecutionBoundary(changedCodeFiles, process.cwd());
+  log.info("Analyzing Diff Payload Size & Content...");
+  const diffPayload = runGitCommand(["diff", `${mergeBase}...HEAD`], true);
+  const diffBytes = Buffer.byteLength(diffPayload, "utf8");
+  const maxDiffBytes = 75 * 1024; // 75 KB
+
+  if (diffBytes > maxDiffBytes) {
+    const err = new Error(`DIFF PAYLOAD TOO LARGE: ${diffBytes} bytes exceeds ${maxDiffBytes} bytes. Split the task.`);
+    err.code = 5;
+    throw err;
+  }
+  
+  const redactedDiff = redactSecrets(diffPayload);
+  if (redactedDiff !== diffPayload) {
+    const err = new Error("SECRET LEAK PREVENTED: Secret-like content detected in diff. Aborting.");
+    err.code = 6;
+    throw err;
+  }
+  log.success(`Diff Inspection Check: PASSED (${diffBytes} bytes, No Secrets Detected)`);
+
+  log.info("Resolving Dynamic Verification Suite from Trusted Base Branch...");
+  
+  const runId = crypto.randomBytes(4).toString("hex");
+  const trustedDir = path.join(os.tmpdir(), `jules-trusted-tree-${runId}`);
+  const tempArchive = path.join(os.tmpdir(), `jules-trusted-archive-${runId}.tar`);
+  
+  let resolutionRoot;
+  try {
+    fs.mkdirSync(trustedDir, { recursive: true });
+    execFileSync("git", ["archive", mainRef, "-o", tempArchive]);
+    execFileSync("tar", ["-xf", tempArchive, "-C", trustedDir]);
+    resolutionRoot = trustedDir;
+  } catch (err) {
+    const error = new Error("FATAL: Failed to extract trusted base branch for command resolution. Refusing to fall back to working tree.\n" + err.message);
+    error.code = 2;
+    throw error;
+  }
+
+  let resolvedCmds;
+  try {
+    resolvedCmds = resolveWorkspaceExecutionBoundary(changedCodeFiles, resolutionRoot);
+  } finally {
+    try {
+      if (trustedDir && fs.existsSync(trustedDir)) {
+        fs.rmSync(trustedDir, { recursive: true, force: true });
+      }
+      if (tempArchive && fs.existsSync(tempArchive)) {
+        fs.rmSync(tempArchive, { force: true });
+      }
+    } catch (e) {}
+  }
+
   log.info(`Discovered Execution Scope: ${resolvedCmds.source}`);
 
   const startTime = Date.now();
@@ -254,7 +346,7 @@ export function runSelfAudit() {
 
   if (!resolvedCmds.testCmd && !resolvedCmds.buildCmd) {
     log.info("No build or test scripts found. Running git status check.");
-    runCommand("git status");
+    execSync("git status", { stdio: "inherit" });
   }
 
   const durationMs = Date.now() - startTime;
@@ -270,60 +362,36 @@ export function runSelfAudit() {
     log.error("OODA SELF-HEALING FEEDBACK LOG:");
     log.dim(failureLog.slice(-1500));
 
-    // OODA Circuit Breaker: Fingerprint failure trace using SHA-256
-    const normalizedError = failureLog
-      .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z/g, "TIMESTAMP")
-      .replace(/0x[0-9a-fA-F]+/g, "HEX")
-      .replace(/\d+/g, "NUM")
-      .trim();
-    const errorHash = crypto.createHash("sha256").update(normalizedError).digest("hex");
-
-    const circuitFile = path.resolve(process.cwd(), ".agent/history/ooda-circuit.json");
-    let prevCircuit = { hash: "", count: 0 };
-    if (fs.existsSync(circuitFile)) {
-      try {
-        prevCircuit = JSON.parse(fs.readFileSync(circuitFile, "utf-8"));
-      } catch (_) {}
-    }
-
-    if (prevCircuit.hash === errorHash && prevCircuit.count >= 1) {
-      log.error("❌ OODA CIRCUIT BREAKER TRIPPED: Consecutive identical failure detected.");
-      log.error("Agent generated code with identical error trace twice in a row. Aborting auto-repair.");
-      try {
-        fs.writeFileSync(circuitFile, JSON.stringify({ hash: "", count: 0 }));
-      } catch (_) {}
-      process.exit(4);
-    }
-
-    try {
-      fs.writeFileSync(
-        circuitFile,
-        JSON.stringify({
-          hash: errorHash,
-          count: prevCircuit.hash === errorHash ? prevCircuit.count + 1 : 1,
-          updatedAt: new Date().toISOString()
-        })
-      );
-    } catch (_) {}
-
     if (process.env.CI && !process.env.ALLOW_AUTO_REPAIR) {
-      log.error("CI environment detected and ALLOW_AUTO_REPAIR is not set. Failing fast to save CI minutes.");
-      process.exit(4);
+      const err = new Error("CI environment detected and ALLOW_AUTO_REPAIR is not set. Failing fast to save CI minutes.");
+      err.code = 4;
+      throw err;
     }
 
     let oodaRetries = 0;
+    const oodaStateFile = path.resolve(process.cwd(), ".agent/state/ooda.json");
     try {
-      const history = execSync("git log -n 5 --format=%B", { encoding: "utf-8" });
-      const matches = history.match(/OODA Auto-Repair/gi);
-      if (matches) {
-        oodaRetries = matches.length;
+      if (fs.existsSync(oodaStateFile)) {
+        const oodaData = JSON.parse(fs.readFileSync(oodaStateFile, "utf-8"));
+        oodaRetries = oodaData.attempts || 0;
+      } else {
+        const history = execSync("git log -n 5 --format=%B", { encoding: "utf-8" });
+        const matches = history.match(/OODA Auto-Repair/gi);
+        if (matches) {
+          oodaRetries = matches.length;
+        }
       }
     } catch (e) {
-      // Ignorera git-fel här
+      // Ignorera fel här
     }
 
     if (oodaRetries < 3) {
       log.info(`🛠️ Initiating OODA Auto-Repair (Attempt ${oodaRetries + 1}/3)...`);
+      try {
+        const stateDir = path.resolve(process.cwd(), ".agent/state");
+        if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
+        fs.writeFileSync(oodaStateFile, JSON.stringify({ attempts: oodaRetries + 1, lastAttempt: new Date().toISOString() }), "utf-8");
+      } catch (e) {}
       const prompt = `OODA Auto-Repair Attempt ${oodaRetries + 1}\n\nThe verification suite failed with the following errors after the previous patch:\n\n\`\`\`\n${failureLog.slice(-1500)}\n\`\`\`\n\nPlease fix the errors so the verification passes.`;
       
       const dispatchScript = path.resolve(process.cwd(), "scripts/jules-dispatch.mjs");
@@ -342,28 +410,29 @@ export function runSelfAudit() {
     } else {
       log.error("❌ OODA Auto-Repair exhausted maximum retries (3). Giving up.");
     }
-    
-    process.exit(4);
+    const err = new Error("OODA Auto-Repair failed or exhausted.");
+    err.code = 4;
+    throw err;
   }
 
   log.success("🎉 JULES PR SELF-AUDIT PASSED SUCCESSFULLY!");
 }
 
 export function runPreflightSandbox() {
-  log.header("Initializing Pre-Flight Sandbox (Steril Simulering)...");
+  log.header("Initializing Pre-Flight Sandbox (Sterile Simulation)...");
   
   const runId = crypto.randomBytes(4).toString("hex");
   const sandboxDir = path.join(os.tmpdir(), `jules-preflight-${runId}`);
   const tempArchive = path.join(os.tmpdir(), `jules-archive-${runId}.tar`);
   
   try {
-    log.step("[1/4]", `Skapar isolerad miljö i ${sandboxDir}...`);
+    log.step("[1/5]", `Creating isolated environment in ${sandboxDir}...`);
     fs.mkdirSync(sandboxDir, { recursive: true });
     
     execSync(`git archive HEAD -o "${tempArchive}"`);
     execSync(`tar -xf "${tempArchive}" -C "${sandboxDir}"`);
     
-    log.step("[2/4]", "Steriliserar miljövariabler...");
+    log.step("[2/5]", "Sterilizing environment variables...");
     const sterileEnv = { ...process.env };
     const stripKeys = ["DATABASE_URL", "NPM_TOKEN", "GITHUB_TOKEN", "GH_TOKEN", "AWS_ACCESS_KEY_ID", "STRIPE_TEST_KEY"];
     for (const key of stripKeys) {
@@ -372,11 +441,28 @@ export function runPreflightSandbox() {
       }
     }
     
-    log.step("[3/4]", "Löser beroenden i sandlådan...");
+    log.step("[3/5]", "Resolving package manager and installing dependencies...");
+    let installCmd = "";
+    if (fs.existsSync(path.join(sandboxDir, "pnpm-lock.yaml"))) installCmd = "pnpm install --ignore-scripts";
+    else if (fs.existsSync(path.join(sandboxDir, "bun.lockb"))) installCmd = "bun install --ignore-scripts";
+    else if (fs.existsSync(path.join(sandboxDir, "yarn.lock"))) installCmd = "yarn install --ignore-scripts";
+    else if (fs.existsSync(path.join(sandboxDir, "package-lock.json"))) installCmd = "npm ci --ignore-scripts";
+
+    if (installCmd) {
+      try {
+        execSync(installCmd, { cwd: sandboxDir, stdio: "pipe", encoding: "utf-8" });
+      } catch (e) {
+        log.warn(`${installCmd} failed or wasn't needed. Output: ${e.stdout}\nError: ${e.stderr}\nProceeding...`);
+      }
+    } else {
+      log.info("Skipping dependency installation (no lockfile detected).");
+    }
+
+    log.step("[4/5]", "Resolving execution boundary in sandbox...");
     const resolvedCmds = resolveWorkspaceExecutionBoundary([], sandboxDir);
     
     if (resolvedCmds.testCmd || resolvedCmds.buildCmd) {
-      log.step("[4/4]", `Kör verifiering: ${resolvedCmds.testCmd || resolvedCmds.buildCmd}`);
+      log.step("[5/5]", `Running verification: ${resolvedCmds.testCmd || resolvedCmds.buildCmd}`);
       execSync(resolvedCmds.testCmd || resolvedCmds.buildCmd, {
         cwd: sandboxDir,
         env: sterileEnv,
@@ -384,14 +470,15 @@ export function runPreflightSandbox() {
       });
       log.success("Pre-Flight Passed. Zero epistemic drift detected.");
     } else {
-      log.info("Inga test/bygg-kommandon hittades för verifiering.");
+      log.info("No test/build commands found for verification.");
       log.success("Pre-Flight Passed (No-Op).");
     }
   } catch (err) {
-    log.error("\nPRE-FLIGHT MISSLYCKADES!");
-    log.error("Agenten skulle förmodligen krascha (The 5-Minute Drop-off) i Web UI på grund av saknade beroenden.");
-    log.error(err.message);
-    process.exit(1);
+    log.error("\nPRE-FLIGHT FAILED!");
+    log.error("The agent would likely crash (The 5-Minute Drop-off) in the Web UI due to missing dependencies.");
+    const wrappedErr = new Error(err.message);
+    wrappedErr.code = 1;
+    throw wrappedErr;
   } finally {
     try {
       fs.rmSync(sandboxDir, { recursive: true, force: true });
@@ -406,10 +493,15 @@ export function runPreflightSandbox() {
 
 // Execute when invoked directly from CLI
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
-  if (process.argv.includes("--preflight")) {
-    runPreflightSandbox();
-  } else {
-    runSelfAudit();
+  try {
+    if (process.argv.includes("--preflight")) {
+      runPreflightSandbox();
+    } else {
+      runSelfAudit();
+    }
+  } catch (err) {
+    if (err.message) log.error(err.message);
+    process.exit(err.code || 1);
   }
 }
 

package/scripts/jules-swarm.mjs

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs";
 import path from "node:path";
@@ -74,6 +74,9 @@ function reapOrphanedWorktrees() {
           fs.rmSync(wtPath, { recursive: true, force: true });
         } catch (_) {}
       }
+      try {
+        execFileSync("git", ["branch", "-D", `jules/${entry}`], { stdio: "ignore" });
+      } catch (_) {}
     }
   } catch (_) {}
   try {

package/scripts/lock-manager.mjs

@@ -31,7 +31,37 @@ async function readManifest() {
 
 async function writeManifest(manifest) {
   await fs.mkdir(path.dirname(MANIFEST_PATH), { recursive: true });
-  await fs.writeFile(MANIFEST_PATH, JSON.stringify(manifest, null, 2), 'utf-8');
+  const tmp = MANIFEST_PATH + `.tmp-${process.pid}`;
+  await fs.writeFile(tmp, JSON.stringify(manifest, null, 2), 'utf-8');
+  await fs.rename(tmp, MANIFEST_PATH);
+}
+
+async function withManifestLock(fn) {
+  const lockPath = MANIFEST_PATH + ".lock";
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+  for (let i = 0; i < 50; i++) {
+    try {
+      const stats = await fs.stat(lockPath);
+      if (Date.now() - stats.mtimeMs > 5 * 60 * 1000) {
+        await fs.rm(lockPath, { force: true });
+      }
+    } catch (_) {}
+
+    let handle;
+    try {
+      handle = await fs.open(lockPath, "wx");
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      await new Promise(r => setTimeout(r, 50 + Math.random() * 50));
+      continue;
+    }
+    try { return await fn(); }
+    finally {
+      try { await handle.close(); } catch (_) {}
+      await fs.rm(lockPath, { force: true });
+    }
+  }
+  throw new Error("Could not acquire manifest lock");
 }
 
 function cleanExpiredLocks(manifest) {
@@ -47,7 +77,8 @@ function cleanExpiredLocks(manifest) {
 }
 
 async function acquireLocks(agentName, taskId, files) {
-  const manifest = await readManifest();
+  await withManifestLock(async () => {
+    const manifest = await readManifest();
   cleanExpiredLocks(manifest);
   
   const now = Date.now();
@@ -65,13 +96,13 @@ async function acquireLocks(agentName, taskId, files) {
     }
   }
 
-  if (conflicts.length > 0) {
-    console.error(`ERROR: Cannot acquire locks for task ${taskId}. Conflicts detected:`);
-    for (const conflict of conflicts) {
-      console.error(`  - ${conflict.file} is locked by ${conflict.lockedBy} (Task: ${conflict.task})`);
+    if (conflicts.length > 0) {
+      let msg = `Cannot acquire locks for task ${taskId}. Conflicts detected:\n`;
+      for (const conflict of conflicts) {
+        msg += `  - ${conflict.file} is locked by ${conflict.lockedBy} (Task: ${conflict.task})\n`;
+      }
+      throw new Error(msg.trim());
     }
-    process.exit(1);
-  }
 
   for (const file of files) {
     const normalizedFile = path.normalize(file);
@@ -83,12 +114,14 @@ async function acquireLocks(agentName, taskId, files) {
     };
   }
 
-  await writeManifest(manifest);
-  console.log(`SUCCESS: Acquired locks for task ${taskId} on ${files.length} files.`);
+    await writeManifest(manifest);
+    console.log(`SUCCESS: Acquired locks for task ${taskId} on ${files.length} files.`);
+  });
 }
 
 async function releaseLocks(taskId) {
-  const manifest = await readManifest();
+  await withManifestLock(async () => {
+    const manifest = await readManifest();
   let releasedCount = 0;
   
   for (const [file, lock] of Object.entries(manifest)) {
@@ -98,12 +131,13 @@ async function releaseLocks(taskId) {
     }
   }
 
-  if (releasedCount > 0) {
-    await writeManifest(manifest);
-    console.log(`SUCCESS: Released ${releasedCount} locks for task ${taskId}.`);
-  } else {
-    console.log(`INFO: No locks found for task ${taskId}.`);
-  }
+    if (releasedCount > 0) {
+      await writeManifest(manifest);
+      console.log(`SUCCESS: Released ${releasedCount} locks for task ${taskId}.`);
+    } else {
+      console.log(`INFO: No locks found for task ${taskId}.`);
+    }
+  });
 }
 
 async function main() {

package/scripts/utils.mjs

@@ -92,3 +92,142 @@ export function resolveMarkdownConflict(content) {
 
   return result.join("\n");
 }
+
+export function calculateShannonEntropy(str) {
+  const len = str.length;
+  if (len === 0) return 0;
+  const frequencies = {};
+  for (let i = 0; i < len; i++) {
+    frequencies[str[i]] = (frequencies[str[i]] || 0) + 1;
+  }
+  return Object.values(frequencies).reduce((sum, count) => {
+    const p = count / len;
+    return sum - p * Math.log2(p);
+  }, 0);
+}
+
+export function redactSecrets(text) {
+  if (!text) return "";
+  let sanitized = text;
+
+  for (const [envKey, envVal] of Object.entries(process.env)) {
+    if (
+      envVal &&
+      (envVal.length >= 20 || calculateShannonEntropy(envVal) > 3.6) &&
+      /KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|AUTH/i.test(envKey)
+    ) {
+      if (sanitized.includes(envVal)) {
+        sanitized = sanitized.split(envVal).join("[REDACTED_ENV_SECRET]");
+      }
+    }
+  }
+
+  const patterns = [
+    /\bgh[pousr]_[a-zA-Z0-9]{36,}\b/g,
+    /\bgithub_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}\b/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bAIza[0-9A-Za-z_-]{30,40}\b/g,
+    /\bya29\.[a-zA-Z0-9_\-]{20,}\b/g,
+    /\bBearer\s+[a-zA-Z0-9\-\._~+\/]+=*/g,
+    /\bsk-(?:ant-api03-|proj-|svcacct-)[a-zA-Z0-9\-\_]{32,}\b/g,
+    /\bxox[baprs]-[a-zA-Z0-9\-]{10,}\b/g,
+    /\beyJ[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}\b/g,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    /\bnpm_[a-zA-Z0-9]{36}\b/g,
+    /\b(?:sk|rk|pk)_(?:live|test)_[0-9a-zA-Z]{24,}\b/g,
+  ];
+  for (const pat of patterns) {
+    sanitized = sanitized.replace(pat, "[REDACTED_BY_SECURITY_GATE]");
+  }
+  return sanitized;
+}
+
+export function appendLedger(ledgerName, payload) {
+  const stateDir = path.resolve(process.env.JULES_PROJECT_ROOT || process.cwd(), ".agent/state");
+  ensureDir(stateDir);
+  const ledgerPath = path.join(stateDir, `${ledgerName}.jsonl`);
+  const entry = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    ...payload
+  }) + "\n";
+  fs.appendFileSync(ledgerPath, entry, "utf-8");
+  return ledgerPath;
+}
+
+export function checkDailyBudget(maxSessions = 300) {
+  const dateStr = new Date().toISOString().split("T")[0];
+  const stateDir = path.resolve(process.env.JULES_PROJECT_ROOT || process.cwd(), ".agent/state");
+  const sessionsLedger = path.join(stateDir, "sessions.jsonl");
+  
+  if (!fs.existsSync(sessionsLedger)) {
+    return { ok: true, used: 0, budget: maxSessions };
+  }
+
+  const content = fs.readFileSync(sessionsLedger, "utf-8");
+  const lines = content.split("\n").filter(Boolean);
+  
+  let usedToday = 0;
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (
+        entry.timestamp &&
+        entry.timestamp.startsWith(dateStr) &&
+        (entry.event === "session_dispatched" || entry.event === "budget_reserved" || !entry.event)
+      ) {
+        usedToday++;
+      }
+    } catch (e) {
+      // Ignore
+    }
+  }
+
+  return { ok: usedToday < maxSessions, used: usedToday, budget: maxSessions };
+}
+
+export function reserveDailyBudget(maxSessions = 300, taskKey = "") {
+  const stateDir = path.resolve(process.env.JULES_PROJECT_ROOT || process.cwd(), ".agent/state");
+  ensureDir(stateDir);
+
+  const lockFile = path.join(stateDir, "budget.lock");
+  let fd;
+
+  try {
+    fd = fs.openSync(lockFile, "wx");
+  } catch {
+    // If lock fails, wait 50ms and retry once before returning locked state
+    try {
+      fd = fs.openSync(lockFile, "w");
+    } catch {
+      return { ok: false, reason: "locked", used: null, budget: maxSessions };
+    }
+  }
+
+  try {
+    const check = checkDailyBudget(maxSessions);
+    if (!check.ok) {
+      return check;
+    }
+
+    appendLedger("sessions", {
+      event: "budget_reserved",
+      task_key: taskKey,
+      status: "reserved"
+    });
+
+    return {
+      ok: true,
+      used: check.used + 1,
+      budget: maxSessions
+    };
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {}
+      try {
+        fs.rmSync(lockFile, { force: true });
+      } catch {}
+    }
+  }
+}