jules-orchestrator-kit 0.36.0 → 0.37.0

package/README.md

@@ -104,7 +104,7 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 * **🔒 Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:tty`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
 
-* **🛡️ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, matching against **canonicalised, case-folded paths** so `./`, `..`, mixed separators or a `.GitHub/` spelling cannot walk past a rule (the same repo is checked out on case-insensitive macOS and Windows filesystems). Redacts high-entropy secrets and PII from dry-runs and git diffs, blocks unsupported Node.js native module imports in Edge environments (Cloudflare Workers, Vercel Edge, Netlify Edge), and rejects PRs exceeding the 75 KB Diff Payload governor.
+* **🛡️ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, matching against **canonicalised, case-folded paths** so `./`, `..`, mixed separators or a `.GitHub/` spelling cannot walk past a rule (the same repo is checked out on case-insensitive macOS and Windows filesystems). Redacts high-entropy secrets and PII from dry-runs and git diffs — **including credentials wrapped in base64**, so a key inside a Kubernetes `Secret` manifest is not invisible to a line-oriented scanner — blocks unsupported Node.js native module imports in Edge environments (Cloudflare Workers, Vercel Edge, Netlify Edge), and rejects PRs exceeding the 75 KB Diff Payload governor.
 
 * **🔄 Autonomous OODA Self-Healing:** Captures test stderr/stdout, normalizes failure fingerprints, and feeds structured error contexts back into repair iterations (up to 3 automatic attempts) before human escalation.
 
@@ -122,7 +122,7 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 * **🚀 Zero-Test Bootstrapping (`agentctl bootstrap`):** Synthesizes deterministic syntax-check and smoke-test verification oracles for untested legacy repositories so agents always operate against a falsifiable feedback loop.
 
-* **📈 Proven Scale & Reliability:** Empirically tested with **532 unit tests across 79 suites passing in < 10.0s**. An adversarial red-team suite (`test/adversarial-claims.test.mjs`) continuously attempts to falsify the safety guarantees documented above — including cross-platform probes for the case-insensitive filesystems on macOS and Windows — and a documentation-sync gate (`scripts/doc-sync-check.mjs`) blocks any release whose docs have drifted from the code.
+* **📈 Proven Scale & Reliability:** Empirically tested with **547 unit tests across 80 suites passing in < 10.0s**. An adversarial red-team suite (`test/adversarial-claims.test.mjs`) continuously attempts to falsify the safety guarantees documented above — every probe in it currently holds, with no open gaps — including cross-platform probes for the case-insensitive filesystems on macOS and Windows — and a documentation-sync gate (`scripts/doc-sync-check.mjs`) blocks any release whose docs have drifted from the code.
 
 <br/>
 

package/bin/agentctl.mjs

@@ -334,18 +334,41 @@ async function main() {
         // The count is local-only, so an operator who knows their real usage
         // must be able to correct it. Appending `budget_released` keeps the
         // hash chain intact — the ledger is corrected forwards, never edited.
+        // An unrecognised flag is refused rather than ignored. `reset` writes to
+        // the ledger, and a misremembered flag — `--root`, `--force` — silently
+        // dropping through to a full release is the kind of misfire that only
+        // becomes visible after the count is already gone.
+        const known = new Set(["--dry-run", "--yes", "-y", "--all"]);
+        const unknown = args.slice(2).filter((a) => !known.has(a));
+        if (unknown.length) {
+          console.error(`Unrecognised option${unknown.length > 1 ? "s" : ""} for \`budget reset\`: ${unknown.join(", ")}`);
+          console.error("Accepted: --dry-run, --yes/-y, --all. Nothing was released.");
+          process.exit(2);
+        }
         const dryRun = args.includes("--dry-run");
         const confirmed = args.includes("--yes") || args.includes("-y");
+        // Committed reservations reached the provider, so releasing them makes
+        // the local count understate real usage. That has to be deliberate.
+        const includeCommitted = args.includes("--all");
         if (!dryRun && !confirmed) {
           const open = listOpenReservations(root);
-          console.log(`Would release ${open.length} open reservation(s) from the last 24 hours.`);
+          const committed = open.filter((r) => r.committed).length;
+          const target = includeCommitted ? open.length : open.length - committed;
+          console.log(`Would release ${target} open reservation(s) from the last 24 hours.`);
+          if (committed > 0 && !includeCommitted) {
+            console.log(`Keeping ${committed} that reached Jules — those sessions really spent quota.`);
+            console.log("Add --all to release them too, if you know the count is still wrong.");
+          }
           console.log("This rewrites nothing — it appends `budget_released` entries.");
           console.log("Re-run with --yes to confirm, or --dry-run for detail.");
           process.exit(0);
         }
-        const res = releaseOpenReservations({ root, dryRun, reason: "operator-reconcile" });
+        const res = releaseOpenReservations({ root, dryRun, includeCommitted, reason: "operator-reconcile" });
         const verb = dryRun ? "Would release" : "Released";
-        console.log(`${verb} ${res.released} reservation(s) (${res.committed} committed, ${res.uncommitted} never closed).`);
+        console.log(`${verb} ${res.released} of ${res.open} open reservation(s) — ${res.uncommitted} never closed, ${res.committed} committed.`);
+        if (res.kept > 0) {
+          console.log(`Kept ${res.kept} committed reservation(s); re-run with --all to release those as well.`);
+        }
         if (!dryRun) {
           const after = budgetStatus(loadConfig(root), root);
           console.log(`Daily Budget : ${formatBudgetLine(after)}`);
@@ -363,14 +386,17 @@ async function main() {
       console.log(`  ${b.note}`);
       console.log(`  Window opened at ${b.windowStart} — the quota resets ${b.windowHours}h after each task,`);
       console.log("  not at midnight, so this count spans yesterday's ledger too.");
-      console.log(`  Open reservations in the window: ${listOpenReservations(root).length}`);
+      const openNow = listOpenReservations(root);
+      const committedNow = openNow.filter((r) => r.committed).length;
+      console.log(`  Open reservations in the window: ${openNow.length} (${committedNow} confirmed dispatched, ${openNow.length - committedNow} never closed)`);
       console.log("");
       console.log(`Worker Slots : ${slots.concurrency} concurrent`);
       console.log(`  ${slots.note}`);
       console.log("");
       console.log("The ledger counts this checkout only — sessions started from the Jules");
       console.log("web UI or another machine spend the same quota without appearing here.");
-      console.log("Use `agentctl budget reset --yes` to reconcile a count you know is wrong.");
+      console.log("Use `agentctl budget reset --yes` to clear the ones that never closed,");
+      console.log("or `--all` to also give back the ones that did reach Jules.");
       process.exit(0);
       break;
     }

package/index.mjs

@@ -13,6 +13,7 @@ export {
   matchesGlob,
   checkScope,
   scanDiff,
+  hasEncodedSecret,
   checkEdgeRuntimeImports,
   checkCrossPackageImports,
 } from "./src/security.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/src/budget.mjs

@@ -276,32 +276,54 @@ export function listOpenReservations(root = resolveRoot(), opts = {}) {
  * forwards — never by editing or deleting the file, which would break the chain
  * and destroy the audit trail the ledger exists to provide.
  *
- * This is an operator override, not an inference. The kit cannot tell a
- * reservation that reached the provider from one whose process died first, so
- * only the operator knows whether the local count still reflects reality.
+ * This is an operator override, not an inference — but the two kinds of open
+ * reservation are not equally likely to be wrong, and by default only one of
+ * them is released.
+ *
+ * An **uncommitted** reservation was taken and never resolved: the process died
+ * between reserving the slot and learning what happened to it. That is the
+ * phantom this function exists to clear.
+ *
+ * A **committed** one carries proof that the dispatch reached the provider, so
+ * a real session exists and the quota really was spent. Releasing it makes the
+ * local count *understate* actual usage, which is the dangerous direction: the
+ * kit then dispatches confidently past the provider's real limit and gets
+ * refused. `includeCommitted` therefore has to be asked for.
+ *
+ * Legacy id-less reservations have no `budget_committed` entry that could ever
+ * name them, so they always read as uncommitted and are always released.
  *
  * @param {object} [opts]
  * @param {string} [opts.root]
  * @param {string} [opts.reason] - Recorded on every released entry.
  * @param {boolean} [opts.dryRun] - Report what would be released, write nothing.
- * @returns {{ released: number, committed: number, uncommitted: number, ids: string[], dryRun: boolean }}
+ * @param {boolean} [opts.includeCommitted] - Also release reservations that
+ *   demonstrably reached the provider. Off by default.
+ * @returns {{ released: number, kept: number, open: number, committed: number,
+ *   uncommitted: number, anonymous: number, ids: string[],
+ *   includeCommitted: boolean, dryRun: boolean }}
  */
 export function releaseOpenReservations(opts = {}) {
   const root = opts.root || resolveRoot();
   const openRecords = listOpenReservations(root);
   const committed = openRecords.filter((r) => r.committed).length;
+  const includeCommitted = Boolean(opts.includeCommitted);
+  const targets = includeCommitted ? openRecords : openRecords.filter((r) => !r.committed);
 
   const result = {
-    released: openRecords.length,
+    released: targets.length,
+    kept: openRecords.length - targets.length,
+    open: openRecords.length,
     committed,
     uncommitted: openRecords.length - committed,
-    anonymous: openRecords.filter((r) => !r.reservationId).length,
-    ids: openRecords.map((r) => r.reservationId).filter(Boolean),
+    anonymous: targets.filter((r) => !r.reservationId).length,
+    ids: targets.map((r) => r.reservationId).filter(Boolean),
+    includeCommitted,
     dryRun: Boolean(opts.dryRun),
   };
-  if (opts.dryRun || openRecords.length === 0) return result;
+  if (opts.dryRun || targets.length === 0) return result;
 
-  for (const rec of openRecords) {
+  for (const rec of targets) {
     const entry = { event: "budget_released", reason: opts.reason || "operator-reconcile" };
     if (rec.reservationId) {
       entry.reservationId = rec.reservationId;

package/src/security.mjs

@@ -142,6 +142,19 @@ export function redactSecrets(text) {
     sanitized = sanitized.replace(pat, "[REDACTED_BY_SECURITY_GATE]");
   }
 
+  // A key the scanner can find inside a base64 blob must not survive redaction
+  // just because the literal bytes differ — otherwise scanDiff blocks the
+  // dispatch and the escalation payload leaks the very value it blocked on. The
+  // whole blob goes, not part of it: a partially-redacted encoding still
+  // decodes to the key.
+  const encoded = new Set();
+  decodeBase64Blobs(sanitized, (plain, blob) => {
+    if (hasHighConfidenceSecret(plain)) encoded.add(blob);
+  });
+  for (const blob of encoded) {
+    sanitized = sanitized.split(blob).join("[REDACTED_ENCODED_SECRET]");
+  }
+
   return sanitized;
 }
 
@@ -374,14 +387,118 @@ const STRING_CONCAT_JOIN = /(["'`])\s*\+\s*(["'`])/g;
  * Produces the variants of the added-line text that secret patterns are run
  * against: as-written, with invisible characters stripped, and with
  * source-level string concatenation collapsed.
+ *
+ * `normalized` is the last of those — every normalisation applied. It is
+ * returned separately for checks that are too expensive to run three times and
+ * gain nothing from the intermediate forms.
+ *
  * @param {string} addedLines
- * @returns {string[]}
+ * @returns {{ all: string[], normalized: string }}
  */
 function secretScanVariants(addedLines) {
   const stripped = addedLines.replace(INVISIBLE_CHARS, "");
   // Collapse `"AAA" +\n  "BBB"` into `"AAABBB"` before matching.
   const dejoined = stripped.replace(/\s*\n\s*/g, " ").replace(STRING_CONCAT_JOIN, "");
-  return [...new Set([addedLines, stripped, dejoined])];
+  return { all: [...new Set([addedLines, stripped, dejoined])], normalized: dejoined };
+}
+
+// Base64 is less an evasion technique than a file format. Every value in a
+// Kubernetes Secret manifest is base64 by specification, and whole `.env` files
+// get encoded into a single CI variable. A credential arriving that way is
+// ordinary rather than adversarial — and a line-oriented scanner walks straight
+// past it, which makes this the encoding most likely to carry a live key
+// through the gate.
+const BASE64_CANDIDATE = /[A-Za-z0-9+/]{24,}={0,2}/g;
+
+// Decoding is cheap per blob and ruinous per diff if left unbounded. A patch
+// that checks in a binary, a source map or a bundled font is otherwise enough
+// to turn one scan into a memory event, so both the number of candidates and
+// the total decoded size are capped. Exceeding a cap skips the remainder; it
+// does not fail the scan, because a large diff is not evidence of a leak.
+const BASE64_MAX_CANDIDATES = 64;
+const BASE64_MAX_DECODED_BYTES = 64 * 1024;
+
+/**
+ * Share of characters that are printable ASCII (plus tab/newline/return).
+ *
+ * `Buffer.from(str, "base64")` never throws — it discards what it cannot parse
+ * and returns whatever it managed to decode. So a hex digest or a random
+ * identifier of the right length "decodes" successfully into bytes that mean
+ * nothing. A wrapped credential, on the other hand, decodes to text: keys,
+ * PEM blocks and `.env` bodies are all ASCII. This ratio is what separates the
+ * two, and it removes nearly all of the noise before any pattern runs.
+ */
+function printableRatio(str) {
+  if (!str) return 0;
+  let printable = 0;
+  for (let i = 0; i < str.length; i++) {
+    const c = str.charCodeAt(i);
+    if (c === 9 || c === 10 || c === 13 || (c >= 32 && c <= 126)) printable++;
+  }
+  return printable / str.length;
+}
+
+/**
+ * Decode the base64-looking blobs in `text` that plausibly hold text.
+ *
+ * @param {string} text
+ * @param {(plain: string, blob: string) => void} [onDecoded] - Called per blob.
+ * @returns {string[]}
+ */
+function decodeBase64Blobs(text, onDecoded) {
+  if (!text) return [];
+  const decoded = [];
+  let candidates = 0;
+  let bytes = 0;
+
+  BASE64_CANDIDATE.lastIndex = 0;
+  let match;
+  while ((match = BASE64_CANDIDATE.exec(text)) !== null) {
+    if (candidates++ >= BASE64_MAX_CANDIDATES) break;
+    const blob = match[0];
+    // Valid base64 is a multiple of four characters including padding. This
+    // costs nothing and rejects three quarters of the alphanumeric runs — commit
+    // hashes, minified identifiers — that would otherwise be decoded for nothing.
+    if (blob.length % 4 !== 0) continue;
+    // Check the budget against what this blob *would* cost, not against what
+    // has already been spent — otherwise the first candidate decodes in full
+    // however large it is, and a single checked-in binary costs more than the
+    // cap was meant to allow. `continue`, not `break`: one oversized blob must
+    // not hide the smaller ones after it.
+    if (bytes + (blob.length * 3) / 4 > BASE64_MAX_DECODED_BYTES) continue;
+
+    let plain;
+    try {
+      plain = Buffer.from(blob, "base64").toString("utf-8");
+    } catch (_) {
+      continue;
+    }
+    bytes += plain.length;
+    if (printableRatio(plain) < 0.9) continue;
+
+    decoded.push(plain);
+    if (onDecoded) onDecoded(plain, blob);
+  }
+  BASE64_CANDIDATE.lastIndex = 0;
+  return decoded;
+}
+
+/**
+ * True when a base64-encoded value on an added line decodes to a structured
+ * credential.
+ *
+ * Deliberately runs the high-confidence patterns *only*. The low-confidence set
+ * is entropy- and keyword-driven, and decoded bytes are high-entropy by
+ * construction — pointing it at this output would flag close to every encoded
+ * blob in every repository. `AKIA[0-9A-Z]{16}` cannot match decoded noise;
+ * "looks secret-ish" always can. That asymmetry is the whole reason this check
+ * is safe to enable by default.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function hasEncodedSecret(text) {
+  return decodeBase64Blobs(text).some((plain) => hasHighConfidenceSecret(plain));
 }
 
 export function scanDiff(diffTextStr = "", options = {}) {
@@ -392,13 +509,23 @@ export function scanDiff(diffTextStr = "", options = {}) {
     .map((line) => line.slice(1))
     .join("\n");
 
-  const variants = secretScanVariants(addedLines);
+  const { all: variants, normalized } = secretScanVariants(addedLines);
   const hasHigh = variants.some((v) => hasHighConfidenceSecret(v));
-  const hasLow = !hasHigh && variants.some((v) => hasLowConfidenceSecret(v));
+  // Only worth decoding when nothing was found in the clear, and only against
+  // the fully-normalised text: decoding is the expensive step, and the
+  // intermediate variants differ from it in ways base64 blobs do not care about.
+  const hasEncoded = !hasHigh && hasEncodedSecret(normalized);
+  const hasLow = !hasHigh && !hasEncoded && variants.some((v) => hasLowConfidenceSecret(v));
   const findings = [];
 
   if (hasHigh) {
     findings.push({ severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", description: "High-confidence secret pattern detected in added diff lines" });
+  } else if (hasEncoded) {
+    // Same type as the cleartext case: every gate that blocks on
+    // HIGH_CONFIDENCE_SECRET should block on this too, and a new type would
+    // have silently passed through the ones not updated. The description
+    // carries the difference the operator needs.
+    findings.push({ severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", description: "High-confidence secret pattern detected inside a base64-encoded value on an added diff line" });
   } else if (hasLow) {
     findings.push({ severity: "HIGH", type: "LOW_CONFIDENCE_SECRET", description: "Low-confidence secret or authorization token detected in added diff lines" });
   }
@@ -419,7 +546,7 @@ export function scanDiff(diffTextStr = "", options = {}) {
   }
 
   return {
-    ok: !hasHigh && !hasLow && edgeRes.ok && crossPkgRes.ok,
+    ok: !hasHigh && !hasEncoded && !hasLow && edgeRes.ok && crossPkgRes.ok,
     findings,
   };
 }