jules-orchestrator-kit 0.32.8 → 0.34.0

package/src/ops/doctor-registry.mjs

@@ -1,7 +1,9 @@
 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";
+import { loadConfig } from "../config.mjs";
+import { resolveConcurrency } from "../budget.mjs";
 
 /**
  * @typedef {"pass" | "warn" | "fail" | "skip" | "unknown"} DiagnosticStatus
@@ -261,6 +263,41 @@ export async function runDoctorChecks(options = {}) {
     });
   }
 
+  // 3b. Worker slots against the plan's ceiling.
+  //
+  // A warning, never a failure: the kit cannot see the account, only the
+  // config. Pooled accounts legitimately exceed a single plan's ceiling, and
+  // the provider refuses what it will not allow regardless of what we think.
+  try {
+    const cfg = loadConfig(root);
+    const slots = resolveConcurrency(cfg);
+    addResult({
+      id: "limits.concurrency",
+      category: "Config",
+      title: "Worker Slots vs Plan Ceiling",
+      status: slots.overCeiling ? "warn" : "pass",
+      severity: slots.overCeiling ? "medium" : "info",
+      summary: `${slots.concurrency} concurrent worker(s) — ${slots.note}`,
+      evidence: [
+        { label: "concurrency", value: slots.concurrency, sensitive: false },
+        { label: "planCeiling", value: slots.ceiling, sensitive: false },
+        { label: "source", value: slots.source, sensitive: false },
+      ],
+      remediation: slots.overCeiling
+        ? [
+            {
+              summary: `Set limits.concurrency to ${slots.ceiling} or lower in .agent/config.yml, unless this account pools several plans`,
+              risk: "low",
+              automatic: false,
+              requiresProbe: false,
+            },
+          ]
+        : [],
+    });
+  } catch (_) {
+    // A config the loader rejects is already reported by config.present.
+  }
+
   // 4. Verification Oracle Checks
   const pkgPath = join(root, "package.json");
   if (existsSync(pkgPath)) {
@@ -393,16 +430,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 +454,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

@@ -55,6 +55,129 @@ export function getDailyLedgerPath(rootOrOpts = resolveRoot()) {
   return join(getStateDir(root), `ledger-${dateStr}.jsonl`);
 }
 
+/**
+ * How far back a task still counts against the allowance.
+ *
+ * The provider's daily quota resets on a rolling 24-hour window, not at
+ * midnight. Counting per calendar day — which the ledger's `ledger-<date>`
+ * rotation invites — is wrong in both directions: a batch dispatched at 23:00
+ * stops being counted at 00:01 while the provider still refuses on it, and
+ * yesterday's last hours vanish from a count that should still include them.
+ *
+ * The files stay day-scoped, because rotation is a storage concern. Counting
+ * is not: it spans whatever files the window touches and filters on entry
+ * timestamps.
+ */
+export const ROLLING_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Ledger files that can hold entries inside the rolling window, oldest first.
+ *
+ * One day wider than the window itself: an entry timestamped 23:59 UTC sits in
+ * that day's file, and a window opening moments later still has to see it.
+ *
+ * @param {string} [root]
+ * @param {number} [now] - Epoch ms; injectable so tests need not wait a day.
+ * @param {number} [windowMs]
+ * @returns {string[]}
+ */
+export function getLedgerPathsInWindow(root = resolveRoot(), now = Date.now(), windowMs = ROLLING_WINDOW_MS) {
+  const stateDir = getStateDir(root);
+  const spanDays = Math.ceil(windowMs / DAY_MS) + 1;
+  const paths = [];
+  for (let i = spanDays - 1; i >= 0; i--) {
+    const dateStr = new Date(now - i * DAY_MS).toISOString().split("T")[0];
+    const filePath = join(stateDir, `ledger-${dateStr}.jsonl`);
+    if (!paths.includes(filePath) && existsSync(filePath)) paths.push(filePath);
+  }
+  return paths;
+}
+
+/**
+ * Replay the budget events in the rolling window and report what is still spent.
+ *
+ * Reservations carrying a `reservationId` are matched by name. Legacy id-less
+ * ones — written by older kit versions — can only be matched by position, so a
+ * release without a `releasedTimestamp` consumes the oldest still-open
+ * anonymous reservation. `releaseOpenReservations` records that timestamp
+ * precisely so the pairing survives the window boundary: without it, an
+ * anonymous release could outlive the reservation it cancelled and start
+ * subtracting from a later one instead.
+ *
+ * Entries whose timestamp will not parse are counted. A budget event the kit
+ * cannot place in time is safer treated as spent than as free.
+ *
+ * @param {string} [root]
+ * @param {object} [opts]
+ * @param {number} [opts.now]
+ * @param {number} [opts.windowMs]
+ * @returns {{ used: number, open: { reservationId: string|null, timestamp: string, committed: boolean }[], windowStart: string }}
+ */
+export function scanBudgetWindow(root = resolveRoot(), opts = {}) {
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const windowMs = Number.isFinite(opts.windowMs) ? opts.windowMs : ROLLING_WINDOW_MS;
+  const cutoff = now - windowMs;
+
+  /** @type {Map<string, { reservationId: string, timestamp: string, committed: boolean, inWindow: boolean }>} */
+  const byId = new Map();
+  /** @type {{ reservationId: null, timestamp: string, committed: boolean, inWindow: boolean }[]} */
+  const anonymous = [];
+
+  const inWindow = (timestamp) => {
+    const ts = Date.parse(timestamp || "");
+    return Number.isFinite(ts) ? ts >= cutoff : true;
+  };
+
+  for (const filePath of getLedgerPathsInWindow(root, now, windowMs)) {
+    let raw = "";
+    try {
+      raw = readFileSync(filePath, "utf-8");
+    } catch (_) {
+      continue;
+    }
+    for (const line of raw.split("\n")) {
+      if (!line) continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch (_) {
+        continue;
+      }
+      if (!entry || !entry.event) continue;
+      const timestamp = entry.timestamp || "";
+
+      if (entry.event === "budget_reserved") {
+        const record = { timestamp, committed: false, inWindow: inWindow(timestamp) };
+        if (entry.reservationId) byId.set(entry.reservationId, { reservationId: entry.reservationId, ...record });
+        else anonymous.push({ reservationId: null, ...record });
+      } else if (entry.event === "budget_committed") {
+        // A commit does not free the slot — the task really ran — it only marks
+        // the reservation as having reached the provider.
+        const record = entry.reservationId ? byId.get(entry.reservationId) : null;
+        if (record) record.committed = true;
+      } else if (entry.event === "budget_rolled_back" || entry.event === "budget_released") {
+        if (entry.reservationId) {
+          byId.delete(entry.reservationId);
+        } else if (entry.releasedTimestamp) {
+          const idx = anonymous.findIndex((r) => r.timestamp === entry.releasedTimestamp);
+          if (idx !== -1) anonymous.splice(idx, 1);
+        } else {
+          anonymous.shift();
+        }
+      }
+    }
+  }
+
+  const open = [...byId.values(), ...anonymous].filter((r) => r.inWindow);
+  return {
+    used: open.length,
+    open: open.map(({ reservationId, timestamp, committed }) => ({ reservationId, timestamp, committed })),
+    windowStart: new Date(cutoff).toISOString(),
+  };
+}
+
 export class MutexTimeoutError extends Error {
   constructor(message = "Failed to acquire VFS mutex lock within timeout") {
     super(message);
@@ -187,43 +310,24 @@ export function readLedger(filePath) {
   }
 }
 
-export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
+/**
+ * Tasks still counted against the allowance, over the rolling 24-hour window.
+ *
+ * The name is kept for compatibility; "daily" here means the provider's day,
+ * which is the last 24 hours rather than the calendar one.
+ */
+export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300, opts = {}) {
   let root = typeof arg1 === "string" ? arg1 : resolveRoot();
   let limit = typeof arg1 === "number" ? arg1 : typeof arg2 === "number" ? arg2 : 300;
 
-  const filePath = getDailyLedgerPath(root);
-  if (!existsSync(filePath)) {
-    return { ok: true, used: 0, budget: limit, remaining: limit };
-  }
   try {
-    const content = readFileSync(filePath, "utf-8");
-    const lines = content.split("\n").filter(Boolean);
-    let count = 0;
-    const activeIds = new Set();
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-        if (entry && entry.event === "budget_reserved") {
-          if (entry.reservationId) {
-            activeIds.add(entry.reservationId);
-          } else {
-            count++;
-          }
-        } else if (entry && (entry.event === "budget_rolled_back" || entry.event === "budget_released")) {
-          if (entry.reservationId) {
-            activeIds.delete(entry.reservationId);
-          } else {
-            count = Math.max(0, count - 1);
-          }
-        }
-      } catch (_) {}
-    }
-    const used = count + activeIds.size;
+    const scan = scanBudgetWindow(root, opts);
     return {
-      ok: used < limit,
-      used,
+      ok: scan.used < limit,
+      used: scan.used,
       budget: limit,
-      remaining: Math.max(0, limit - used),
+      remaining: Math.max(0, limit - scan.used),
+      windowStart: scan.windowStart,
     };
   } catch (_) {
     return { ok: true, used: 0, budget: limit, remaining: limit };
@@ -244,48 +348,43 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
   const mutexDir = join(stateDir, ".budget.mutex");
 
   return withVfsMutex(mutexDir, () => {
-    const dateStr = new Date().toISOString().split("T")[0];
+    const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+    const dateStr = new Date(now).toISOString().split("T")[0];
     const filePath = join(stateDir, `ledger-${dateStr}.jsonl`);
 
-    let count = 0;
-    const activeIds = new Set();
+    // The count spans the rolling window; the hash chain does not. A chain is
+    // per file, so the new entry links to today's last hash even when the
+    // reservations it is counted against were written yesterday.
+    const used = scanBudgetWindow(root, { ...opts, now }).used;
     let prevHash = "0".repeat(64);
 
     if (existsSync(filePath)) {
       try {
         const raw = readFileSync(filePath, "utf-8");
         const lines = raw.split("\n").filter(Boolean);
-        for (const line of lines) {
+        for (let i = lines.length - 1; i >= 0; i--) {
           try {
-            const entry = JSON.parse(line);
-            if (entry && entry.event === "budget_reserved") {
-              if (entry.reservationId) {
-                activeIds.add(entry.reservationId);
-              } else {
-                count++;
-              }
-            } else if (entry && (entry.event === "budget_rolled_back" || entry.event === "budget_released")) {
-              if (entry.reservationId) {
-                activeIds.delete(entry.reservationId);
-              } else {
-                count = Math.max(0, count - 1);
-              }
-            }
+            const entry = JSON.parse(lines[i]);
             if (entry && entry.hash) {
               prevHash = entry.hash;
+              break;
             }
           } catch (_) {}
         }
       } catch (_) {}
     }
 
-    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)`);
     }
 
-    const timestamp = new Date().toISOString();
-    const reservationId = `res-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    const timestamp = new Date(now).toISOString();
+    const reservationId = `res-${now}-${Math.random().toString(36).substring(2, 8)}`;
     const rawPayload = { timestamp, event: "budget_reserved", reservationId, budget: limit, prevHash };
     const hash = createHash("sha256").update(JSON.stringify(rawPayload)).digest("hex");
     const payload = { ...rawPayload, hash };
@@ -303,12 +402,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 +421,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,57 @@ 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";
+    // The ceiling is shown next to the default so the number the wizard writes
+    // reads as a starting point rather than as the plan's limit.
+    const slots = p.maxConcurrency > p.concurrency
+      ? `${p.concurrency} ${worker} (plan allows ${p.maxConcurrency})`
+      : `${p.concurrency} ${worker}`;
+    return {
+      label: TIER_LABELS[name] || name,
+      value: name,
+      description: `${slots}, ~${p.dailyTasks} daily tasks, ${p.diffKb} KB diff limit`,
+    };
+  });
+}
+
 export const BUILTIN_PRESETS = [
   {
     id: "nightly-security-audit",
@@ -86,7 +117,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 +139,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 +236,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
     );