jules-orchestrator-kit 0.32.8 → 0.34.0

package/README.md

@@ -120,7 +120,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 **461 unit tests across 66 suites passing in < 10.0s**, supporting 300+ daily agent sessions per repository. 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 **510 unit tests across 77 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.
 
 <br/>
 
@@ -297,9 +297,9 @@ scope:
 limits:
   diffKb: 75             # 75 KB Diff Payload Governor limit
   promptKb: 50           # Maximum prompt payload size
-  dailyTasks: 300        # Daily task session quota limit
+  dailyTasks: 300        # Task quota per rolling 24h window (not per calendar day)
   repairAttempts: 3      # Maximum OODA repair iterations
-  concurrency: 1         # Worker slot concurrency limit
+  concurrency: 15        # Worker slots; the ultra plan allows up to 60
 
 # Dynamic Complexity & Cost Router — opt-in, disabled by default.
 # Provider-agnostic: "fast"/"complex" accept any provider key ("jules" |

package/bin/agentctl.mjs

@@ -5,18 +5,37 @@ import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
-import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir } from "../src/state.mjs";
+import { acquireLock, releaseLock, lockStatus, getQueueDir } from "../src/state.mjs";
 import { worktreePrune } from "../src/git.mjs";
 import { reapOrphanedIntents, reapStaleMutexDirs } from "../src/journal.mjs";
+import { KIT_VERSION } from "../src/version.mjs";
+import { budgetStatus, listOpenReservations, releaseOpenReservations, resolveConcurrency } from "../src/budget.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-export const VERSION = "0.32.8";
+export const VERSION = KIT_VERSION;
+
+/**
+ * Render the budget line so the number is never mistaken for the vendor's own
+ * counter. The ledger counts what *this checkout* dispatched; sessions started
+ * from the web UI or another machine spend the same quota unseen, so a bare
+ * "N / M used" invites the reader to trust a figure that cannot be complete.
+ * "last 24h", not "today": the provider's allowance resets on a rolling
+ * window, so a figure labelled by the calendar day would be a different number
+ * from the one being enforced.
+ * @param {{ used: number, limit: number, source: string, certain: boolean }} b
+ */
+export function formatBudgetLine(b) {
+  const scope = `${b.used} / ${b.limit} used in the last 24h (this repo)`;
+  if (b.source === "learned") return `${scope} — provider refused further work`;
+  if (b.certain) return `${scope} — limit from ${b.source === "env" ? "JULES_DAILY_BUDGET" : "config"}`;
+  return `${scope} — limit estimated from tier "${b.tier || "?"}", not enforced`;
+}
 
 export function printHelp() {
   console.log(`
-🚀 agentctl v0.32.8 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v${VERSION} — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -41,6 +60,7 @@ Commands:
   rollback              Restore git state & working tree to atomic pre-flight checkpoint
   resume                Resume warm session with human response (--response "<text>")
   status                Display queue and system status summary
+  budget                Show the 24h task budget, worker slots and their provenance (reset --yes)
   scan                  Scan codebase for TODO/FIXME task candidates
   hydrate [prompt]      Prepend active system learnings and baton-pass state to a prompt
   harvest               Harvest failure traces and record/quarantine resolution rules
@@ -64,11 +84,33 @@ Options:
 
 
 async function main() {
-  if (!command || command === "--help" || command === "-h") {
+  if (command === "--help" || command === "-h") {
     printHelp();
     process.exit(0);
   }
 
+  // Bare `agentctl` answers "what do I do next" rather than dumping thirty
+  // commands. The help text is a reference for people who already know the
+  // tool; a newcomer cannot tell which entry is step one, and guessing wrong
+  // costs them a confusing failure instead of a hint.
+  if (!command) {
+    const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
+    const cwd = process.cwd();
+    let budgetLine = "";
+    let where = cwd;
+    try {
+      const nextRoot = resolveRoot();
+      where = nextRoot;
+      budgetLine = formatBudgetLine(budgetStatus(loadConfig(nextRoot), nextRoot));
+    } catch (_) {
+      // Outside a repository there is no root to load a config from; the
+      // next step below is `git init`, which does not need one.
+    }
+    const next = resolveNextStep(where);
+    console.log(renderNextStep({ version: VERSION, root: where, next, budgetLine: next.blocking ? "" : budgetLine }));
+    process.exit(0);
+  }
+
   if (command === "version" || command === "--version" || command === "-v") {
     console.log(`agentctl v${VERSION}`);
     process.exit(0);
@@ -282,6 +324,55 @@ async function main() {
       break;
     }
 
+    case "budget": {
+      const action = args[1];
+      const b = budgetStatus(config, root);
+
+      if (action === "reset") {
+        // 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.
+        const dryRun = args.includes("--dry-run");
+        const confirmed = args.includes("--yes") || args.includes("-y");
+        if (!dryRun && !confirmed) {
+          const open = listOpenReservations(root);
+          console.log(`Would release ${open.length} open reservation(s) from the last 24 hours.`);
+          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 verb = dryRun ? "Would release" : "Released";
+        console.log(`${verb} ${res.released} reservation(s) (${res.committed} committed, ${res.uncommitted} never closed).`);
+        if (!dryRun) {
+          const after = budgetStatus(loadConfig(root), root);
+          console.log(`Daily Budget : ${formatBudgetLine(after)}`);
+        }
+        process.exit(0);
+      }
+
+      if (args.includes("--json")) {
+        console.log(JSON.stringify({ ok: true, budget: { ...b, scope: "this-repository" } }, null, 2));
+        process.exit(0);
+      }
+
+      const slots = resolveConcurrency(config);
+      console.log(`Task Budget  : ${formatBudgetLine(b)}`);
+      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}`);
+      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.");
+      process.exit(0);
+      break;
+    }
+
     case "lock": {
       const action = args[1];
       if (action === "acquire") {
@@ -313,6 +404,24 @@ async function main() {
     }
 
     case "doctor": {
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: { json: { type: "boolean", short: "j" } },
+        allowPositionals: true,
+        strict: false,
+      });
+
+      // runDoctorChecks() and its seven checks existed but nothing rendered
+      // them: this command printed a hand-written summary, so findings like a
+      // git-tracked .env were computed, tested, and never shown to anyone.
+      const { runDoctorChecks } = await import("../src/ops/doctor-registry.mjs");
+      const report = await runDoctorChecks({ root });
+
+      if (values.json) {
+        console.log(JSON.stringify(report, null, 2));
+        process.exit(report.summary.fail > 0 ? 1 : 0);
+      }
+
       console.log(`\n🔍 agentctl System Diagnostics (v${VERSION})`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
@@ -320,10 +429,22 @@ async function main() {
       console.log(`  Detected Stack   : ${detectStack(root).stack}`);
       console.log(`  Test Command     : ${config.verify.test || "(None)"}`);
       console.log(`  Build Command    : ${config.verify.build || "(None)"}`);
-      const budget = checkDailyBudget(root, config.limits.dailyTasks);
-      console.log(`  Daily Budget     : ${budget.used} / ${budget.budget} sessions used`);
-      console.log(`--------------------------------------------------\n`);
-      process.exit(0);
+      console.log(`  Daily Budget     : ${formatBudgetLine(budgetStatus(config, root))}`);
+      console.log(`--------------------------------------------------`);
+
+      const icon = { pass: "✅", warn: "⚠️ ", fail: "❌", skip: "⏭️ ", unknown: "❔" };
+      for (const r of report.results) {
+        console.log(`  ${icon[r.status] || "•"} ${r.title}`);
+        if (r.status !== "pass") {
+          console.log(`       ${r.summary}`);
+          for (const fix of r.remediation || []) console.log(`       → ${fix.summary}`);
+        }
+      }
+
+      const { pass, warn, fail } = report.summary;
+      console.log(`--------------------------------------------------`);
+      console.log(`  ${pass} passed, ${warn} warning(s), ${fail} failure(s)\n`);
+      process.exit(fail > 0 ? 1 : 0);
       break;
     }
 
@@ -578,8 +699,8 @@ async function main() {
       console.log(`  Project Root     : ${root}`);
       console.log(`  Pending Tasks    : ${files.length}`);
       console.log(`  Active VFS Locks : ${lockStatus(root).length}`);
-      const budget = checkDailyBudget(root, config.limits.dailyTasks);
-      console.log(`  Daily Budget     : ${budget.used} / ${budget.budget} used`);
+      const budget = budgetStatus(config, root);
+      console.log(`  Daily Budget     : ${formatBudgetLine(budget)}`);
       console.log(`--------------------------------------------------\n`);
       process.exit(0);
       break;

package/index.mjs

@@ -49,6 +49,9 @@ export {
   rollbackBudgetReservation,
   withBudget,
   checkDailyBudget,
+  scanBudgetWindow,
+  getLedgerPathsInWindow,
+  ROLLING_WINDOW_MS,
   acquireLock,
   releaseLock,
   lockStatus,
@@ -130,3 +133,19 @@ export {
   generateEvidenceMarkdown,
   computeEvidenceHash,
 } from "./src/evidence.mjs";
+
+export {
+  resolveDailyLimit,
+  budgetStatus,
+  readObservedCeiling,
+  readActiveCeiling,
+  recordObservedCeiling,
+  isDailyQuotaRejection,
+  listOpenReservations,
+  releaseOpenReservations,
+  resolveConcurrency,
+  CEILING_FILE,
+} from "./src/budget.mjs";
+export { KIT_VERSION } from "./src/version.mjs";
+export { VENDOR_TIERS, FALLBACK_TIER } from "./src/config.mjs";
+export { tierOptions } from "./src/wizard-init.mjs";

package/package.json

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

package/scripts/doc-sync-check.mjs

@@ -16,7 +16,7 @@
  * Exit codes: 0 = in sync, 1 = drift detected.
  */
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { execSync } from "node:child_process";
 import { resolveRoot } from "../src/config.mjs";
@@ -60,6 +60,33 @@ function readIfExists(path) {
   return existsSync(path) ? readFileSync(path, "utf-8") : null;
 }
 
+/**
+ * Version numbers that appear in shipped sources but do not describe this kit.
+ * Kept as an explicit, justified list rather than a looser pattern, so a real
+ * drift can never slip through by resembling one of these.
+ */
+const FOREIGN_VERSIONS = [
+  { file: "src/ops/doctor-registry.mjs", value: "20.0.0", why: "minimum supported Node.js runtime" },
+  { file: "src/ops/ide-scaffold.mjs", value: "2.0.0", why: "VS Code tasks.json schema version" },
+  { file: "src/version.mjs", value: "0.0.0", why: "documented fallback when package.json is absent" },
+];
+
+function isForeignVersion(relPath, value) {
+  return FOREIGN_VERSIONS.some((f) => f.file === relPath && f.value === value);
+}
+
+/** Every .mjs under `dir`, recursively. */
+function listSourceFiles(dir, acc = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith(".") || entry === "node_modules") continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) listSourceFiles(full, acc);
+    else if (entry.endsWith(".mjs")) acc.push(full);
+  }
+  return acc;
+}
+
 /**
  * Verifies documentation is in sync with package.json and the real test counts.
  * @param {string} [root]
@@ -80,18 +107,52 @@ export function checkDocSync(root = process.cwd(), opts = {}) {
   if (cli === null) {
     add("agentctl present", false, "bin/agentctl.mjs not found");
   } else {
+    // Either the version is derived from the manifest — which cannot drift —
+    // or it is a literal, which must match. The derived form is preferred;
+    // this check exists to stop a literal creeping back in unnoticed.
+    const derived = /export const VERSION\s*=\s*KIT_VERSION/.test(cli);
     const constMatch = cli.match(/export const VERSION\s*=\s*"([^"]+)"/);
-    add(
-      "agentctl VERSION const",
-      constMatch?.[1] === version,
-      constMatch ? `found "${constMatch[1]}", expected "${version}"` : "no `export const VERSION` found"
-    );
+    if (derived) {
+      const versionModule = readIfExists(join(root, "src", "version.mjs"));
+      const readsManifest = Boolean(versionModule && /package\.json/.test(versionModule));
+      add(
+        "agentctl VERSION const",
+        readsManifest,
+        readsManifest ? "derived from package.json via src/version.mjs" : "VERSION derives from KIT_VERSION but src/version.mjs does not read package.json"
+      );
+    } else {
+      add(
+        "agentctl VERSION const",
+        constMatch?.[1] === version,
+        constMatch ? `found "${constMatch[1]}", expected "${version}"` : "no `export const VERSION` found"
+      );
+    }
 
-    const stale = [...cli.matchAll(/agentctl v(\d+\.\d+\.\d+)/g)].map((m) => m[1]).filter((v) => v !== version);
+    // Scan everything shipped, not just the CLI: the MCP server, dashboard and
+    // init wizard each hardcoded a version and sat three minor releases behind
+    // while this gate only ever looked at bin/agentctl.mjs and stayed green.
+    const shipped = [
+      ...listSourceFiles(join(root, "src")),
+      join(root, "bin", "agentctl.mjs"),
+    ];
+    const stale = [];
+    for (const file of shipped) {
+      const text = readIfExists(file);
+      if (text === null) continue;
+      const rel = file.replace(root + "/", "");
+      for (const m of text.matchAll(/\bv?(\d+\.\d+\.\d+)\b/g)) {
+        if (m[1] === version) continue;
+        // Only flag figures presented as *this kit's* version.
+        const context = text.slice(Math.max(0, m.index - 60), m.index).toLowerCase();
+        if (!/version|agentctl|orchestrator kit|kit config/.test(context)) continue;
+        if (isForeignVersion(rel, m[1], context)) continue;
+        stale.push(`${rel}: ${m[1]}`);
+      }
+    }
     add(
       "agentctl banner/version strings",
       stale.length === 0,
-      stale.length ? `stale version string(s): ${[...new Set(stale)].join(", ")}` : `all reference v${version}`
+      stale.length ? `stale version string(s): ${[...new Set(stale)].join(", ")}` : `all shipped sources reference v${version}`
     );
   }
 

package/scripts/utils.mjs

@@ -142,9 +142,13 @@ export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
  *   explicit root to keep callers (notably tests) off the operator's real ledger.
  */
 export function reserveDailyBudget(maxSessions = 300, taskKey = "", root = resolveRoot()) {
-  appendLedger({ event: "budget_reserved", key: taskKey }, root);
+  // The id is what makes the reservation releasable. Written without one, a
+  // reservation counted against the day and no rollback, commit or reconcile
+  // could ever name it again — it stayed charged until the ledger rotated.
+  const reservationId = `res-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+  appendLedger({ event: "budget_reserved", reservationId, key: taskKey }, root);
   const check = checkDailyBudget(root, maxSessions);
-  return { ok: check.ok, used: check.used, budget: maxSessions };
+  return { ok: check.ok, used: check.used, budget: maxSessions, reservationId };
 }
 
 export function verifyLedgerIntegrity(filePath) {