jules-orchestrator-kit 0.32.7 → 0.33.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 **458 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 **498 unit tests across 75 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/>
 

package/bin/agentctl.mjs

@@ -5,18 +5,34 @@ 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 } from "../src/budget.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-export const VERSION = "0.32.7";
+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.
+ * @param {{ used: number, limit: number, source: string, certain: boolean }} b
+ */
+export function formatBudgetLine(b) {
+  const scope = `${b.used} / ${b.limit} used (this repo)`;
+  if (b.source === "learned") return `${scope} — provider refused further work today`;
+  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.7 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v${VERSION} — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -41,6 +57,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 today's task budget and its provenance (reset --yes to reconcile)
   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 +81,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 +321,49 @@ 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 today's ledger.`);
+          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);
+      }
+
+      console.log(`Daily Budget : ${formatBudgetLine(b)}`);
+      console.log(`  ${b.note}`);
+      console.log(`  Open reservations today: ${listOpenReservations(root).length}`);
+      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 +395,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 +420,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 +690,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

@@ -130,3 +130,18 @@ export {
   generateEvidenceMarkdown,
   computeEvidenceHash,
 } from "./src/evidence.mjs";
+
+export {
+  resolveDailyLimit,
+  budgetStatus,
+  readObservedCeiling,
+  readActiveCeiling,
+  recordObservedCeiling,
+  isDailyQuotaRejection,
+  listOpenReservations,
+  releaseOpenReservations,
+  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.7",
+  "version": "0.33.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

@@ -135,10 +135,20 @@ export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
   return res;
 }
 
-export function reserveDailyBudget(maxSessions = 300, taskKey = "") {
-  appendLedger({ event: "budget_reserved", key: taskKey });
-  const check = checkDailyBudget(maxSessions);
-  return { ok: check.ok, used: check.used, budget: maxSessions };
+/**
+ * @param {number} [maxSessions=300]
+ * @param {string} [taskKey=""]
+ * @param {string} [root] - Ledger root. Defaults to the git toplevel. Pass an
+ *   explicit root to keep callers (notably tests) off the operator's real ledger.
+ */
+export function reserveDailyBudget(maxSessions = 300, taskKey = "", root = resolveRoot()) {
+  // 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, reservationId };
 }
 
 export function verifyLedgerIntegrity(filePath) {

package/src/budget.mjs

@@ -0,0 +1,318 @@
+import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { resolveRoot } from "./config.mjs";
+import { getStateDir, getDailyLedgerPath, ensureDir, appendLedger, checkDailyBudget } from "./state.mjs";
+
+/**
+ * Where the observed quota ceiling lives, outside the ledger so it survives
+ * rotation.
+ *
+ * Deliberately scoped to the day it was observed. The local ledger only counts
+ * tasks dispatched from *this* checkout, while the account's quota is also
+ * spent from the web UI and other machines, so the local count at the moment of
+ * a refusal is a lower bound on the real allowance — not the allowance. Treated
+ * as permanent it would hard-block the operator below their own quota, which is
+ * the exact failure this whole mechanism exists to prevent.
+ *
+ * What it does mean is precise and useful: *today* the provider has started
+ * refusing, so stop asking until tomorrow.
+ */
+export const CEILING_FILE = "budget-ceiling.json";
+
+/** Local calendar day, matching the ledger's own rotation key. */
+function today() {
+  return new Date().toISOString().split("T")[0];
+}
+
+/**
+ * Signals that a provider rejection means "you are out of quota for today"
+ * rather than "you are going too fast right now". A 429 alone cannot tell the
+ * two apart, and learning a ceiling from a per-minute throttle would pin the
+ * daily limit to whatever burst happened to trip it.
+ */
+const DAILY_QUOTA_HINT = /resource[_\s-]?exhausted|daily|per[\s-]?day|quota/i;
+const TRANSIENT_HINT = /per[\s-]?minute|per[\s-]?second|too many requests|slow down|retry[\s-]?after/i;
+
+/**
+ * Decide whether a provider error is evidence of a daily quota ceiling.
+ *
+ * Deliberately conservative: an unrecognised rejection teaches nothing. A
+ * missed lesson costs one wasted API call, whereas a ceiling learned from a
+ * burst throttle would be recorded as certain and would then hard-block the
+ * operator well below their real allowance.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isDailyQuotaRejection(err) {
+  if (!err || typeof err !== "object") return false;
+  const status = /** @type {any} */ (err).status;
+  if (status !== 429 && status !== 403) return false;
+  const text = `${/** @type {any} */ (err).message || ""} ${/** @type {any} */ (err).body || ""}`;
+  if (TRANSIENT_HINT.test(text)) return false;
+  return DAILY_QUOTA_HINT.test(text);
+}
+
+function writeAtomic(filePath, content) {
+  const tmpPath = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  const fd = openSync(tmpPath, "w");
+  try {
+    writeFileSync(fd, content, "utf-8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmpPath, filePath);
+}
+
+/**
+ * Read the stored ceiling, whenever it was observed.
+ * @param {string} [root]
+ * @returns {{ ceiling: number, day: string, observedAt: string, source: string, stale: boolean } | null}
+ */
+export function readObservedCeiling(root = resolveRoot()) {
+  const filePath = join(getStateDir(root), CEILING_FILE);
+  if (!existsSync(filePath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    if (!parsed || typeof parsed.ceiling !== "number" || !Number.isFinite(parsed.ceiling)) return null;
+    if (parsed.ceiling < 0) return null;
+    const day = typeof parsed.day === "string" ? parsed.day : String(parsed.observedAt || "").slice(0, 10);
+    return {
+      ceiling: Math.floor(parsed.ceiling),
+      day,
+      observedAt: typeof parsed.observedAt === "string" ? parsed.observedAt : "",
+      source: typeof parsed.source === "string" ? parsed.source : "provider-rejection",
+      stale: day !== today(),
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * The ceiling only if it still applies — i.e. observed today.
+ * @param {string} [root]
+ */
+export function readActiveCeiling(root = resolveRoot()) {
+  const rec = readObservedCeiling(root);
+  return rec && !rec.stale ? rec : null;
+}
+
+/**
+ * Record that the provider refused further work after `usedAtRejection` tasks
+ * were dispatched locally today.
+ *
+ * Zero is a legitimate value: it means the quota was already spent elsewhere
+ * (the web UI, another machine) before this checkout dispatched anything.
+ *
+ * @param {number} usedAtRejection - Tasks reserved locally when the refusal came.
+ * @param {string} [root]
+ * @param {object} [meta]
+ * @returns {{ ceiling: number, day: string, observedAt: string, source: string } | null}
+ */
+export function recordObservedCeiling(usedAtRejection, root = resolveRoot(), meta = {}) {
+  const ceiling = Math.floor(Number(usedAtRejection));
+  if (!Number.isFinite(ceiling) || ceiling < 0) return null;
+
+  const stateDir = getStateDir(root);
+  ensureDir(stateDir);
+  const record = {
+    ceiling,
+    day: today(),
+    observedAt: new Date().toISOString(),
+    source: meta.source || "provider-rejection",
+  };
+  writeAtomic(join(stateDir, CEILING_FILE), JSON.stringify(record, null, 2) + "\n");
+
+  // Mirrored into the hash-chained ledger so the change is auditable; the JSON
+  // file above is only a cheap index that survives ledger rotation.
+  try {
+    appendLedger({ event: "budget_ceiling_observed", ceiling, source: record.source }, root);
+  } catch (_) {}
+
+  return record;
+}
+
+/**
+ * Resolve today's effective task limit *and how much we trust it*.
+ *
+ * Precedence, most to least authoritative:
+ *   1. `limits.daily_tasks` written explicitly in .agent/config.yml, or
+ *      JULES_DAILY_BUDGET — the operator stating their own plan.
+ *   2. A ceiling the provider demonstrated by refusing work.
+ *   3. The tier preset — a guess, and marked as one.
+ *
+ * `certain` is what callers must branch on: an uncertain limit may warn but
+ * must not hard-block, because refusing a request the provider would have
+ * accepted breaks the tool for anyone whose plan we guessed wrong.
+ *
+ * @param {object} config - A config from loadConfig().
+ * @param {string} [root]
+ * @returns {{ limit: number, source: "config"|"env"|"learned"|"tier"|"default", certain: boolean, note: string }}
+ */
+export function resolveDailyLimit(config, root = resolveRoot()) {
+  const provenance = config?.provenance?.dailyTasks || "default";
+  const configured = Number(config?.limits?.dailyTasks);
+
+  // `>= 0`, not `> 0`: a limit of zero is a deliberate "dispatch nothing", and
+  // treating it as absent would silently fall through to a permissive estimate.
+  if ((provenance === "config" || provenance === "env") && Number.isFinite(configured) && configured >= 0) {
+    return {
+      limit: configured,
+      source: provenance,
+      certain: true,
+      note: provenance === "env" ? "set via JULES_DAILY_BUDGET" : "set in .agent/config.yml",
+    };
+  }
+
+  // Only today's observation may enforce. Yesterday's refusal says nothing
+  // about today's remaining quota, and carrying it forward would keep the
+  // operator locked out after the quota reset.
+  const learned = readActiveCeiling(root);
+  if (learned) {
+    return {
+      limit: learned.ceiling,
+      source: "learned",
+      certain: true,
+      note: `the provider refused further work today after ${learned.ceiling} local task(s); resets tomorrow`,
+    };
+  }
+
+  const fallback = Number.isFinite(configured) && configured > 0 ? configured : 300;
+  return {
+    limit: fallback,
+    source: provenance === "tier" ? "tier" : "default",
+    certain: false,
+    note: `estimated from tier "${config?.tier || "unknown"}" — set limits.daily_tasks to make this exact`,
+  };
+}
+
+/**
+ * List reservations that today's ledger still counts as spent.
+ *
+ * A reservation is open until a `budget_rolled_back` or `budget_released` entry
+ * names it. `budget_committed` deliberately does not close one — a committed
+ * dispatch really did consume quota — so the open set is "everything reserved
+ * today that was not given back".
+ *
+ * Anonymous reservations (no `reservationId`, as older kit versions and
+ * scripts/utils.mjs wrote them) are counted too, as records with
+ * `reservationId: null`. They must be, or a reconcile would silently leave them
+ * charged against the day: `checkDailyBudget` counts them, and with no id there
+ * is nothing a targeted release could name. They are matched by count, the same
+ * way the counter itself treats them.
+ *
+ * @param {string} [root]
+ * @returns {{ reservationId: string|null, timestamp: string, committed: boolean }[]}
+ */
+export function listOpenReservations(root = resolveRoot()) {
+  const filePath = getDailyLedgerPath(root);
+  if (!existsSync(filePath)) return [];
+
+  /** @type {Map<string, { reservationId: string, timestamp: string, committed: boolean }>} */
+  const open = new Map();
+  /** @type {{ reservationId: null, timestamp: string, committed: boolean }[]} */
+  const anonymous = [];
+  let raw = "";
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch (_) {
+    return [];
+  }
+
+  for (const line of raw.split("\n").filter(Boolean)) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (_) {
+      continue;
+    }
+    if (!entry || !entry.event) continue;
+
+    if (entry.event === "budget_reserved") {
+      if (entry.reservationId) {
+        open.set(entry.reservationId, {
+          reservationId: entry.reservationId,
+          timestamp: entry.timestamp || "",
+          committed: false,
+        });
+      } else {
+        anonymous.push({ reservationId: null, timestamp: entry.timestamp || "", committed: false });
+      }
+    } else if (entry.event === "budget_committed") {
+      const rec = entry.reservationId ? open.get(entry.reservationId) : null;
+      if (rec) rec.committed = true;
+    } else if (entry.event === "budget_rolled_back" || entry.event === "budget_released") {
+      if (entry.reservationId) open.delete(entry.reservationId);
+      else anonymous.pop();
+    }
+  }
+
+  return [...open.values(), ...anonymous];
+}
+
+/**
+ * Give today's open reservations back, by appending `budget_released` entries.
+ *
+ * The ledger is append-only and hash-chained, so a miscounted day is corrected
+ * 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.
+ *
+ * @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 }}
+ */
+export function releaseOpenReservations(opts = {}) {
+  const root = opts.root || resolveRoot();
+  const openRecords = listOpenReservations(root);
+  const committed = openRecords.filter((r) => r.committed).length;
+
+  const result = {
+    released: openRecords.length,
+    committed,
+    uncommitted: openRecords.length - committed,
+    anonymous: openRecords.filter((r) => !r.reservationId).length,
+    ids: openRecords.map((r) => r.reservationId).filter(Boolean),
+    dryRun: Boolean(opts.dryRun),
+  };
+  if (opts.dryRun || openRecords.length === 0) return result;
+
+  for (const rec of openRecords) {
+    const entry = { event: "budget_released", reason: opts.reason || "operator-reconcile" };
+    // An anonymous reservation is released by an equally anonymous entry: the
+    // counter decrements those by count, so naming an id here would leave the
+    // original charged and subtract from someone else's total instead.
+    if (rec.reservationId) entry.reservationId = rec.reservationId;
+    appendLedger(entry, root);
+  }
+  return result;
+}
+
+/**
+ * Human-readable budget status for the CLI, dashboard and MCP surface.
+ * @param {object} config
+ * @param {string} [root]
+ */
+export function budgetStatus(config, root = resolveRoot()) {
+  const resolved = resolveDailyLimit(config, root);
+  const check = checkDailyBudget(root, resolved.limit);
+  return {
+    used: check.used,
+    limit: resolved.limit,
+    remaining: check.remaining,
+    tier: config?.tier || "unknown",
+    source: resolved.source,
+    certain: resolved.certain,
+    note: resolved.note,
+    // Only a limit we actually know may stop a dispatch.
+    enforced: resolved.certain,
+    exhausted: check.used >= resolved.limit,
+  };
+}

package/src/config.mjs

@@ -270,6 +270,17 @@ export function resolveVerify(root = process.cwd(), userVerify = {}) {
   };
 }
 
+/**
+ * The single source of truth for tier defaults. `src/wizard-init.mjs` projects
+ * this into snake_case rather than keeping a second table: the two tables
+ * previously disagreed (wizard wrote free=30 while the runtime assumed 15), so
+ * a freshly initialised repo was budgeted against numbers no other code used.
+ *
+ * `dailyTasks` here is a *hint*, not a fact. Provider quotas are set by the
+ * vendor and change without notice, so these numbers are only ever a starting
+ * guess — see `isTierGuess()` and the learned-ceiling logic in src/state.mjs.
+ * An explicit `limits.daily_tasks` in .agent/config.yml always wins.
+ */
 export const TIER_PRESETS = {
   free: {
     dailyTasks: 15,
@@ -292,8 +303,24 @@ export const TIER_PRESETS = {
     staggerMs: 1000,
     diffKb: 75,
   },
+  // Not a vendor plan: a self-hosted/pooled profile for operators who front
+  // several accounts. Defined here so `tier: enterprise` resolves to what the
+  // wizard writes instead of silently collapsing onto the ultra preset.
+  enterprise: {
+    dailyTasks: 1000,
+    repairAttempts: 3,
+    concurrency: 10,
+    staggerMs: 500,
+    diffKb: 100,
+  },
 };
 
+/** Tier names that correspond to real vendor plans, in ascending order. */
+export const VENDOR_TIERS = ["free", "pro", "ultra"];
+
+/** The tier used when a config names one that does not exist. */
+export const FALLBACK_TIER = "ultra";
+
 /**
  * Loads and validates configuration from .agent/config.yml or .agent/jules.yml.
  */
@@ -382,6 +409,18 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
       ...(envDailyTasks !== null && !isNaN(envDailyTasks) ? { dailyTasks: envDailyTasks } : {}),
       ...(envDiffKb !== null && !isNaN(envDiffKb) ? { diffKb: envDiffKb } : {}),
     },
+    // Where each contested limit actually came from. The merge above flattens
+    // config, env and tier into one number, after which no caller can tell a
+    // figure the operator stated from one the kit guessed — and the budget gate
+    // must not hard-block on a guess. See resolveDailyLimit() in src/budget.mjs.
+    provenance: {
+      dailyTasks:
+        envDailyTasks !== null && !isNaN(envDailyTasks)
+          ? "env"
+          : normalizedLimits.dailyTasks !== undefined
+            ? "config"
+            : "tier",
+    },
     isolation: parsed.isolation || DEFAULTS.isolation,
     runner: parsed.runner || DEFAULTS.runner,
     branchPrefix: parsed.branch_prefix || parsed.branchPrefix || DEFAULTS.branchPrefix,

package/src/dashboard.mjs

@@ -10,6 +10,7 @@ import { join, dirname } from "node:path";
 import { readTelemetry, verifyTelemetryIntegrity } from "./telemetry.mjs";
 import { readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
 import { lockStatus } from "./state.mjs";
+import { KIT_VERSION } from "./version.mjs";
 
 const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")).version;
 
@@ -92,7 +93,7 @@ export function createDashboardServer({ root = process.cwd(), port: _port = 4100
 
     if (url.pathname === "/api/status") {
       res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-      return res.end(JSON.stringify({ ok: true, version: "0.29.1", root, ts: new Date().toISOString() }));
+      return res.end(JSON.stringify({ ok: true, version: KIT_VERSION, root, ts: new Date().toISOString() }));
     }
 
     if (url.pathname === "/api/telemetry") {

package/src/engine.mjs

@@ -3,7 +3,8 @@ import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
 import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
 import { createProvider, ProviderRateLimitError, ProviderUnavailableError } from "./provider.mjs";
 import { resolveRoutedProvider } from "./router.mjs";
-import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation, isConcurrencyGroupLocked } from "./state.mjs";
+import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation, isConcurrencyGroupLocked, checkDailyBudget } from "./state.mjs";
+import { resolveDailyLimit, recordObservedCeiling, isDailyQuotaRejection } from "./budget.mjs";
 import { sanitizeUntrustedData, buildAgentEnvelope } from "./prompt-guard.mjs";
 import { recordVerifyRun, readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
 import fs, { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
@@ -695,7 +696,12 @@ export async function dispatch(task = {}, opts = {}) {
   }
   const root = opts.config?._root || opts.root || process.cwd();
   const config = opts.config || loadConfig(root);
-  const { provider, routed, classification } = resolveRoutedProvider(task, config);
+  // opts.provider mirrors gate()'s existing injection point, so a caller can
+  // exercise dispatch without reaching a live provider.
+  const resolved = resolveRoutedProvider(task, config);
+  const provider = opts.provider || resolved.provider;
+  const routed = opts.provider ? false : resolved.routed;
+  const classification = opts.provider ? null : resolved.classification;
   if (routed && classification) {
     appendTelemetry(root, "router_decision", {
       tier: classification.tier,
@@ -739,14 +745,39 @@ export async function dispatch(task = {}, opts = {}) {
 
   const cleanTask = { ...task, prompt: envelopedPrompt };
 
+  const runDispatch = () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun });
+
+  // An estimated ceiling may warn but must not block: refusing a dispatch the
+  // provider would have accepted is a worse failure than an over-count.
+  const budget = resolveDailyLimit(config, root);
+  if (!opts.dryRun && !budget.certain) {
+    const check = checkDailyBudget(root, budget.limit);
+    if (check.used >= budget.limit) {
+      console.warn(
+        `[BUDGET_ESTIMATE] ${check.used}/${budget.limit} tasks used — ${budget.note}. ` +
+        `Proceeding: the real allowance is unknown, so this is not enforced.`
+      );
+    }
+  }
+
   try {
-    const session = await withBudget(
-      () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun }),
-      root,
-      config.limits.dailyTasks
-    );
+    // A dry run performs no provider call and produces no work, so it must not
+    // consume one of the operator's finite daily task slots. Reserving here also
+    // made every `npm test` burn real budget, which eventually exhausted the
+    // ledger and turned the suite red for reasons unrelated to any code change.
+    const session = opts.dryRun
+      ? await runDispatch()
+      : await withBudget(runDispatch, root, budget.limit, { enforce: budget.certain });
     return classification ? { ...session, _routeTier: classification.tier, _routeReason: classification.reason } : session;
   } catch (err) {
+    // A refusal for daily quota is the only authoritative statement of the
+    // account's real allowance, so record it: from here on the gate enforces a
+    // number the provider demonstrated instead of one a tier preset guessed.
+    if (isDailyQuotaRejection(err)) {
+      try {
+        recordObservedCeiling(checkDailyBudget(root, budget.limit).used, root, { source: "provider-rejection" });
+      } catch (_) {}
+    }
     if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
       if (err.reservationId && !err.budgetReservationRolledBack) {
         rollbackBudgetReservation(root, err.reservationId);

package/src/mcp.mjs

@@ -2,14 +2,16 @@ import { Transform } from "node:stream";
 import { loadConfig, resolveRoot, detectStack } from "./config.mjs";
 import { gate, dispatch } from "./engine.mjs";
 import { classifyRiskTier } from "./risk.mjs";
-import { checkDailyBudget, lockStatus } from "./state.mjs";
+import { lockStatus } from "./state.mjs";
+import { budgetStatus } from "./budget.mjs";
 import { reapOrphanedIntents, reapStaleMutexDirs } from "./journal.mjs";
 import { readTelemetry } from "./telemetry.mjs";
 import { ProgressBus } from "./mcp-progress.mjs";
+import { KIT_VERSION } from "./version.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.29.1",
+  version: KIT_VERSION,
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling
@@ -321,13 +323,22 @@ export async function handleMcpRequest(request, opts = {}) {
 
       if (toolName === "get_jules_status") {
         const stackInfo = detectStack(root);
-        const budget = checkDailyBudget(root, config.limits.dailyTasks);
+        const budget = budgetStatus(config, root);
         const locks = lockStatus(root);
         const status = {
           version: MCP_SERVER_INFO.version,
           root,
           stack: stackInfo.stack,
-          budget: { used: budget.used, limit: budget.budget, remaining: budget.budget - budget.used },
+          // `source`/`enforced` travel with the number so an agent reading this
+          // can tell a measured limit from an estimated one.
+          budget: {
+            used: budget.used,
+            limit: budget.limit,
+            remaining: budget.remaining,
+            source: budget.source,
+            enforced: budget.enforced,
+            scope: "this-repository",
+          },
           activeLocksCount: locks.length,
           locks,
         };

package/src/ops/command-registry.mjs

@@ -155,7 +155,7 @@ export const COMMAND_REGISTRY = [
       "agentctl init --tier pro --yes",
     ],
     flags: [
-      { name: "tier", type: "string", description: "Target configuration tier (free, pro, enterprise)" },
+      { name: "tier", type: "string", description: "Target configuration tier (free, pro, ultra, enterprise)" },
       { name: "interactive", type: "boolean", description: "Launch interactive onboarding wizard" },
       { name: "yes", type: "boolean", description: "Accept auto-detected Stack Oracle defaults" },
     ],
@@ -180,6 +180,29 @@ export const COMMAND_REGISTRY = [
       { name: "host", type: "string", description: "Bind host address (default 127.0.0.1)" },
     ],
   },
+  {
+    id: "budget",
+    path: ["budget"],
+    title: "budget",
+    description: "Show today's task budget, where its limit came from, and reconcile a wrong count",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["b"],
+    examples: [
+      "agentctl budget",
+      "agentctl budget --json",
+      "agentctl budget reset --dry-run",
+      "agentctl budget reset --yes",
+    ],
+    flags: [
+      { name: "json", type: "boolean", description: "Output structured JSON budget snapshot" },
+      { name: "dry-run", type: "boolean", description: "Report what reset would release, write nothing" },
+      { name: "yes", type: "boolean", description: "Confirm releasing today's open reservations" },
+    ],
+  },
   {
     id: "status",
     path: ["status"],

package/src/ops/doctor-registry.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 
 /**
  * @typedef {"pass" | "warn" | "fail" | "skip" | "unknown"} DiagnosticStatus
@@ -393,16 +393,21 @@ export async function runDoctorChecks(options = {}) {
   }
 
   // 7. Jules Provider Key Check
-  const hasApiKey = Boolean(process.env.JULES_API_KEY || process.env.GEMINI_API_KEY);
-  if (hasApiKey) {
+  const keyVar = process.env.JULES_API_KEY ? "JULES_API_KEY" : process.env.GEMINI_API_KEY ? "GEMINI_API_KEY" : "";
+  if (keyVar) {
     addResult({
       id: "provider.key",
       category: "Jules",
       title: "Jules Provider API Key",
       status: "pass",
       severity: "info",
-      summary: "API key environment variable detected",
-      evidence: [{ label: "keyConfigured", value: true, sensitive: false }],
+      // Naming the variable, not the value: an operator who wonders which key a
+      // dispatch will use should not have to echo a secret to find out.
+      summary: `API key supplied via ${keyVar} (environment only — never written to config or sent anywhere but the provider)`,
+      evidence: [
+        { label: "keyConfigured", value: true, sensitive: false },
+        { label: "keySource", value: keyVar, sensitive: false },
+      ],
     });
   } else {
     addResult({
@@ -412,10 +417,50 @@ export async function runDoctorChecks(options = {}) {
       status: "warn",
       severity: "high",
       summary: "Neither JULES_API_KEY nor GEMINI_API_KEY environment variable is set",
+      remediation: [
+        {
+          summary: "Export JULES_API_KEY in your shell profile, or place it in a git-ignored .env",
+          risk: "low",
+          automatic: false,
+          requiresProbe: false,
+        },
+      ],
       evidence: [{ label: "keyConfigured", value: false, sensitive: false }],
     });
   }
 
+  // 7b. A .env holding the key must not be tracked by git.
+  const envFile = join(root, ".env");
+  if (existsSync(envFile)) {
+    let tracked = false;
+    try {
+      const res = spawnSync("git", ["ls-files", "--error-unmatch", ".env"], { cwd: root, encoding: "utf-8" });
+      tracked = res.status === 0;
+    } catch (_) {}
+
+    addResult({
+      id: "provider.key.dotenv",
+      category: "Jules",
+      title: "Local .env secrecy",
+      status: tracked ? "fail" : "pass",
+      severity: tracked ? "critical" : "info",
+      summary: tracked
+        ? ".env is tracked by git — an API key committed here is disclosed to everyone with repository access"
+        : ".env is present and untracked",
+      evidence: [{ label: "gitTracked", value: tracked, sensitive: false }],
+      remediation: tracked
+        ? [
+            {
+              summary: "Run: git rm --cached .env && echo '.env' >> .gitignore, then rotate the key",
+              risk: "low",
+              automatic: false,
+              requiresProbe: false,
+            },
+          ]
+        : [],
+    });
+  }
+
   // Summarize count by status
   const summary = { pass: 0, warn: 0, fail: 0, skip: 0, unknown: 0 };
   for (const r of results) {

package/src/ops/next-step.mjs

@@ -0,0 +1,111 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+/**
+ * Work out the one thing the operator should do next.
+ *
+ * `agentctl --help` lists thirty commands with no indication of which is step
+ * one. That list is a reference for people who already know the tool; someone
+ * meeting it for the first time cannot tell `hydrate` from `harvest` from
+ * `dispatch`, and the cost of guessing wrong is a confusing failure rather than
+ * a hint. This walks the same preconditions the commands themselves enforce and
+ * names the single next action.
+ *
+ * Ordered by dependency: nothing later is worth suggesting while something
+ * earlier is unmet.
+ *
+ * @param {string} root
+ * @param {object} [env=process.env]
+ * @returns {{ id: string, headline: string, detail: string, command: string, blocking: boolean }}
+ */
+export function resolveNextStep(root, env = process.env) {
+  const inGitRepo = (() => {
+    try {
+      return spawnSync("git", ["rev-parse", "--git-dir"], { cwd: root, stdio: "ignore" }).status === 0;
+    } catch (_) {
+      return false;
+    }
+  })();
+
+  if (!inGitRepo) {
+    return {
+      id: "git",
+      headline: "This directory is not a git repository",
+      detail:
+        "Every safety guarantee here is expressed in terms of diffs, branches and a base to compare against, so the kit has nothing to reason about without git.",
+      command: "git init",
+      blocking: true,
+    };
+  }
+
+  const configured = existsSync(join(root, ".agent", "config.yml")) || existsSync(join(root, ".agent", "jules.yml"));
+  if (!configured) {
+    return {
+      id: "init",
+      headline: "No .agent/ configuration yet",
+      detail:
+        "The wizard detects your stack, proposes a verification command, and writes the scope rules the gate enforces.",
+      command: "agentctl init",
+      blocking: true,
+    };
+  }
+
+  if (!env.JULES_API_KEY && !env.GEMINI_API_KEY) {
+    return {
+      id: "key",
+      headline: "No provider API key in the environment",
+      detail:
+        "The key is read from the environment only — never written to config and never sent anywhere but the provider. Until it is set you can still run `agentctl gate` and `--dry-run` dispatches locally.",
+      command: "export JULES_API_KEY=...",
+      blocking: false,
+    };
+  }
+
+  const queueDir = join(root, ".agent", "queue");
+  const queued = existsSync(queueDir) ? readdirSync(queueDir).filter((f) => f.endsWith(".json") || f.endsWith(".yml")).length : 0;
+  if (queued > 0) {
+    return {
+      id: "queue",
+      headline: `${queued} task(s) waiting in the queue`,
+      detail: "Run them through the gate and dispatch pipeline.",
+      command: "agentctl queue",
+      blocking: false,
+    };
+  }
+
+  return {
+    id: "ready",
+    headline: "Set up and ready to dispatch",
+    detail: "Add --dry-run first to see the envelope without spending a task.",
+    command: 'agentctl dispatch -p "your task"',
+    blocking: false,
+  };
+}
+
+/**
+ * Render the bare-invocation greeting: state, next step, and where the full
+ * command list lives for those who want it.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.version
+ * @param {string} ctx.root
+ * @param {{ headline: string, detail: string, command: string }} ctx.next
+ * @param {string} [ctx.budgetLine]
+ * @returns {string}
+ */
+export function renderNextStep({ version, root, next, budgetLine }) {
+  const lines = [
+    ``,
+    `🚀 agentctl v${version}`,
+    `   ${root}`,
+    ``,
+    `   ${next.headline}`,
+    `   ${next.detail}`,
+    ``,
+    `   Next:  ${next.command}`,
+  ];
+  if (budgetLine) lines.push(``, `   Budget: ${budgetLine}`);
+  lines.push(``, `   All commands: agentctl --help`, ``);
+  return lines.join("\n");
+}

package/src/state.mjs

@@ -280,7 +280,12 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
     }
 
     const used = count + activeIds.size;
-    if (used >= limit) {
+    // `enforce: false` marks a limit the kit only guessed (a tier preset rather
+    // than a stated or provider-demonstrated figure). Blocking on a guess would
+    // refuse work the provider would happily have accepted, so an uncertain
+    // ceiling records the overrun and lets the call through to find out.
+    const overLimit = used >= limit;
+    if (overLimit && opts.enforce !== false) {
       throw new BudgetError(`Daily budget exhausted (${used}/${limit} tasks executed)`);
     }
 
@@ -303,12 +308,13 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
       reservationId,
       remaining: Math.max(0, limit - (used + 1)),
       used: used + 1,
+      softLimitExceeded: overLimit,
     };
   }, opts);
 }
 
-export function reserveBudget(rootOrOpts = resolveRoot(), limit = 300) {
-  return reserveBudgetAtomic(rootOrOpts, limit);
+export function reserveBudget(rootOrOpts = resolveRoot(), limit = 300, opts = {}) {
+  return reserveBudgetAtomic(rootOrOpts, limit, opts);
 }
 
 export function commitBudgetReservation(rootOrOpts = resolveRoot(), reservationId = "") {
@@ -321,8 +327,13 @@ export function rollbackBudgetReservation(rootOrOpts = resolveRoot(), reservatio
   return appendLedger({ event: "budget_rolled_back", reservationId }, root);
 }
 
-export async function withBudget(fn, root = resolveRoot(), limit = 300) {
-  const reservation = reserveBudget(root, limit);
+/**
+ * @param {object} [opts]
+ * @param {boolean} [opts.enforce=true] - Pass false when `limit` is an estimate
+ *   rather than a known allowance; the overrun is then recorded, not blocked.
+ */
+export async function withBudget(fn, root = resolveRoot(), limit = 300, opts = {}) {
+  const reservation = reserveBudget(root, limit, opts);
   try {
     const result = await fn();
     commitBudgetReservation(root, reservation.reservationId);

package/src/version.mjs

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The kit version, read once from package.json.
+ *
+ * Every module that needed to name the version used to hardcode it, and they
+ * drifted: the CLI banner said 0.32.8 while the MCP server, the dashboard and
+ * the config the wizard scaffolded all still claimed 0.29.x. Reading the
+ * manifest is the only way the number cannot go stale.
+ *
+ * fileURLToPath keeps this correct on Windows, where a file:// URL pathname
+ * starts with a drive-letter slash that fs cannot open.
+ */
+function readKitVersion() {
+  try {
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+  } catch (_) {
+    // A consumer may vendor src/ without the manifest; a placeholder is better
+    // than an import-time crash in a library whose whole job is running gates.
+    return "0.0.0";
+  }
+}
+
+export const KIT_VERSION = readKitVersion();

package/src/wizard-init.mjs

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { parseYaml } from "./config.mjs";
+import { parseYaml, TIER_PRESETS, VENDOR_TIERS, FALLBACK_TIER } from "./config.mjs";
 import { detectStackOracles, runVerificationProbe } from "./wizard-oracle.mjs";
 import { select, multiSelect, input, confirm, spinner, isTTY } from "./tui.mjs";
+import { KIT_VERSION } from "./version.mjs";
 
 /**
  * Write a file atomically using a temporary file and atomic rename.
@@ -21,27 +22,52 @@ function writeAtomic(filePath, content) {
   renameSync(tmpPath, filePath);
 }
 
-export const TIER_PROFILES = {
-  free: {
-    concurrency: 1,
-    daily_tasks: 30,
-    stagger_ms: 3000,
-    diff_kb: 50,
-  },
-  pro: {
-    concurrency: 3,
-    daily_tasks: 300,
-    stagger_ms: 1500,
-    diff_kb: 75,
-  },
-  enterprise: {
-    concurrency: 10,
-    daily_tasks: 1000,
-    stagger_ms: 500,
-    diff_kb: 100,
-  },
+/**
+ * Snake_case projection of {@link TIER_PRESETS} for the YAML the wizard writes.
+ * Derived rather than declared: as a second literal table it drifted out of sync
+ * with the runtime and scaffolded configs with limits nothing else agreed on.
+ */
+export const TIER_PROFILES = Object.fromEntries(
+  Object.entries(TIER_PRESETS).map(([name, p]) => [
+    name,
+    {
+      concurrency: p.concurrency,
+      daily_tasks: p.dailyTasks,
+      stagger_ms: p.staggerMs,
+      diff_kb: p.diffKb,
+    },
+  ])
+);
+
+const TIER_LABELS = {
+  free: "Free",
+  pro: "Pro",
+  ultra: "Ultra",
+  enterprise: "Custom / self-hosted pool",
 };
 
+/**
+ * Build the tier menu from {@link TIER_PRESETS} so the prompt text cannot drift
+ * from the limits actually written. The hardcoded descriptions it replaces
+ * advertised numbers no tier had, and omitted `ultra` entirely.
+ *
+ * No option is marked "recommended": picking a plan the account does not have
+ * is precisely how the budget ends up guarding the wrong ceiling.
+ * @returns {Array<{ label: string, value: string, description: string }>}
+ */
+export function tierOptions() {
+  const order = [...VENDOR_TIERS, ...Object.keys(TIER_PRESETS).filter((t) => !VENDOR_TIERS.includes(t))];
+  return order.map((name) => {
+    const p = TIER_PRESETS[name];
+    const worker = p.concurrency === 1 ? "worker" : "workers";
+    return {
+      label: TIER_LABELS[name] || name,
+      value: name,
+      description: `${p.concurrency} ${worker}, ~${p.dailyTasks} daily tasks, ${p.diffKb} KB diff limit`,
+    };
+  });
+}
+
 export const BUILTIN_PRESETS = [
   {
     id: "nightly-security-audit",
@@ -86,7 +112,9 @@ export const BUILTIN_PRESETS = [
 export function planInit(root = process.cwd(), options = {}) {
   const oracle = detectStackOracles(root);
   const tierName = options.tier || "pro";
-  const limits = TIER_PROFILES[tierName] || TIER_PROFILES.pro;
+  // An unrecognised name resolves the same way loadConfig() resolves it, so the
+  // scaffolded limits always match what the runtime will later enforce.
+  const limits = TIER_PROFILES[tierName] || TIER_PROFILES[FALLBACK_TIER];
 
   // Preserve existing config if present
   let existingConfig = {};
@@ -106,7 +134,7 @@ export function planInit(root = process.cwd(), options = {}) {
 
   const selectedPresets = options.presets || existingConfig.presets || ["nightly-security-audit", "flaky-test-quarantine"];
 
-  const configYaml = `# Google Jules Orchestrator Kit Config (v0.29.0)
+  const configYaml = `# Google Jules Orchestrator Kit Config (v${KIT_VERSION})
 version: 1
 provider: ${existingConfig.provider || "jules"}
 tier: ${tierName}
@@ -203,12 +231,8 @@ export async function runInitWizard(root = process.cwd(), options = {}) {
     sp.stop(`Detected Stack: ${oracle.stack}`);
 
     selectedTier = await select(
-      [
-        { label: "Pro Tier (Recommended)", value: "pro", description: "3 parallel workers, 300 daily tasks, 75 KB diff limit" },
-        { label: "Free / Individual Tier", value: "free", description: "1 worker, 30 daily tasks, 50 KB diff limit" },
-        { label: "Custom Enterprise", value: "enterprise", description: "10 workers, 1000 daily tasks, 100 KB diff limit" },
-      ],
-      "Select Jules Orchestrator Usage Tier",
+      tierOptions(),
+      "Which plan does your Jules account use? (limits are adjustable later)",
       options
     );