jules-orchestrator-kit 0.33.0 → 0.35.0

package/README.md

@@ -98,7 +98,9 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 * **⚡ AST Blast-Radius Selective Testing:** Traverses file import dependency graphs to execute only affected downstream test suites, cutting monorepo test latency from minutes to milliseconds.
 
-* **🚨 Asynchronous HITL Escalation Bridge (`agentctl escalate`):** Dispatches Slack & Discord webhook alerts when Jules needs feedback, allowing engineers to unblock agents asynchronously via `agentctl resume <id> --response "<reply>"`.
+* **🔕 Type III Silence Governor & Interruption Budgeting (`v0.35.0`):** `agentctl escalate` manages Slack and Discord webhook alerts with configurable digest modes and hourly interruption budgets, buffering non-critical notifications while guaranteeing zero-latency delivery for critical escalations.
+
+* **🩹 Automated Flaky Test Healing Swarm (`v0.35.0`):** `agentctl flaky heal` automatically consumes Wilson-quarantined tests (Exit Code 8) and dispatches specialized anti-flakiness repair tasks to eliminate race conditions, async timing leaks, and resource collisions without weakening test assertions.
 
 * **🔒 Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:tty`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
 
@@ -120,7 +122,7 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 * **🚀 Zero-Test Bootstrapping (`agentctl bootstrap`):** Synthesizes deterministic syntax-check and smoke-test verification oracles for untested legacy repositories so agents always operate against a falsifiable feedback loop.
 
-* **📈 Proven Scale & Reliability:** Empirically tested with **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.
+* **📈 Proven Scale & Reliability:** Empirically tested with **526 unit tests across 79 suites passing in < 10.0s**. An adversarial red-team suite (`test/adversarial-claims.test.mjs`) continuously attempts to falsify the safety guarantees documented above — including cross-platform probes for the case-insensitive filesystems on macOS and Windows — and a documentation-sync gate (`scripts/doc-sync-check.mjs`) blocks any release whose docs have drifted from the code.
 
 <br/>
 
@@ -297,9 +299,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" |
@@ -404,9 +406,11 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 | `lock` | `agentctl lock <acquire\|release\|status>`| Manages VFS mutex locks for multi-agent non-overlapping file ownership. | `0` (Locked/Released), `1` (Conflict) |
 | `clean` | `agentctl clean` | Prunes stale git worktrees, lockfiles, and temporary ledgers. | `0` (Clean) |
 | `evidence` | `agentctl evidence <generate\|verify\|show> [--manifest <path>] [--json]` | Generates, verifies, or prints a SHA-256 cryptographic evidence manifest (changed-file hashes + test-file tamper lock) for audit trails. | `0` (Verified/Generated), `1` (Tamper detected / Verification failed) |
+| `escalate` | `agentctl escalate [<sessionId>] [--status] [--flush] [--clear]` | Dispatches or manages webhook escalation incidents across Slack and Discord with Type III Silence Governor and interruption budgeting. | `0` (Dispatched/Buffered) |
+| `flaky` | `agentctl flaky <status\|heal\|reset> [--dispatch] [--dry-run] [--role <name>]` | Manages Wilson-quarantined tests (Exit Code 8) and dispatches automated anti-flakiness healing swarm without assertion weakening. | `0` (Healed/Queued/Listed) |
 | `mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server for tool integration. | `0` / Stdio stream |
 | `mcp init` | `agentctl mcp init [--target cursor\|vscode\|claude\|all]` | 1-click scaffolding for Cursor (`.cursor/mcp.json`), VS Code tasks (`tasks.json`), and Claude Desktop. | `0` (Scaffolded) |
-| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.32.5`). | `0` |
+| `version` | `agentctl version` | Outputs orchestrator kit semantic version. | `0` |
 
 <br/>
 

package/bin/agentctl.mjs

@@ -9,7 +9,7 @@ import { acquireLock, releaseLock, lockStatus, getQueueDir } from "../src/state.
 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";
+import { budgetStatus, listOpenReservations, releaseOpenReservations, resolveConcurrency } from "../src/budget.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -21,11 +21,14 @@ export const VERSION = KIT_VERSION;
  * 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 (this repo)`;
-  if (b.source === "learned") return `${scope} — provider refused further work today`;
+  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`;
 }
@@ -56,8 +59,10 @@ Commands:
   mcp init              Scaffold IDE integration config (cursor | vscode | claude | all)
   rollback              Restore git state & working tree to atomic pre-flight checkpoint
   resume                Resume warm session with human response (--response "<text>")
+  escalate              Dispatch or manage webhook escalation incidents (--flush, --status, --clear)
+  flaky                 Manage Wilson-quarantined tests and dispatch healing swarm (status | heal | reset)
   status                Display queue and system status summary
-  budget                Show today's task budget and its provenance (reset --yes to reconcile)
+  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
@@ -333,7 +338,7 @@ async function main() {
         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(`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);
@@ -353,9 +358,15 @@ async function main() {
         process.exit(0);
       }
 
-      console.log(`Daily Budget : ${formatBudgetLine(b)}`);
+      const slots = resolveConcurrency(config);
+      console.log(`Task Budget  : ${formatBudgetLine(b)}`);
       console.log(`  ${b.note}`);
-      console.log(`  Open reservations today: ${listOpenReservations(root).length}`);
+      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.");
@@ -770,6 +781,244 @@ async function main() {
       break;
     }
 
+    case "escalate": {
+      const {
+        dispatchEscalation,
+        flushEscalationDigest,
+        getEscalationDigestStatus,
+        clearEscalationDigest,
+      } = await import("../src/webhook.mjs");
+
+      const { values, positionals } = parseArgs({
+        args: args.slice(1),
+        options: {
+          reason: { type: "string", short: "r", default: "AWAITING_USER_FEEDBACK" },
+          branch: { type: "string", short: "b", default: config.baseBranch || "main" },
+          logs: { type: "string", short: "l" },
+          "log-file": { type: "string" },
+          critical: { type: "boolean" },
+          flush: { type: "boolean" },
+          status: { type: "boolean" },
+          clear: { type: "boolean" },
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      if (values.status) {
+        const st = getEscalationDigestStatus(root, config);
+        if (values.json) {
+          console.log(JSON.stringify({ ok: true, status: st }, null, 2));
+        } else {
+          console.log(`\n🔇 Type III Silence Governor Status (v${VERSION})`);
+          console.log(`--------------------------------------------------`);
+          console.log(`  Notification Mode     : ${st.mode.toUpperCase()}`);
+          console.log(`  Pending Digest Count  : ${st.pendingCount} / ${st.threshold}`);
+          console.log(`  Interruption Budget   : ${st.recentInterruptions} / ${st.budgetPerHour} per hour (Available: ${st.budgetAvailable})`);
+          if (st.createdAt) {
+            console.log(`  Oldest Buffered Item  : ${st.createdAt}`);
+          }
+          if (st.incidents.length > 0) {
+            console.log(`\n  Buffered Incidents (${st.incidents.length}):`);
+            st.incidents.forEach((inc) => {
+              console.log(`   - [${inc.reason}] Session ${inc.sessionId} (${inc.branch})`);
+            });
+          }
+          console.log(`--------------------------------------------------\n`);
+        }
+        process.exit(0);
+      }
+
+      if (values.clear) {
+        const res = clearEscalationDigest(root);
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`✅ Cleared pending escalation digest buffer.`);
+        }
+        process.exit(0);
+      }
+
+      if (values.flush) {
+        const res = await flushEscalationDigest(config, { root, dryRun: values["dry-run"] });
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          if (res.flushed) {
+            console.log(`\n📢 Flushed Escalation Digest (${res.count} incidents)`);
+            console.log(`   Slack   : ${res.slack ? "✅ Delivered" : "❌ Skipped/Failed"}`);
+            console.log(`   Discord : ${res.discord ? "✅ Delivered" : "❌ Skipped/Failed"}\n`);
+          } else {
+            console.log(`ℹ️ Nothing to flush: ${res.reason}`);
+          }
+        }
+        process.exit(0);
+      }
+
+      const sessionId = positionals[0] || values.session;
+      if (!sessionId) {
+        console.error("Error: Session ID is required for agentctl escalate <sessionId> (or use --flush / --status).");
+        process.exit(1);
+      }
+
+      let logContent = values.logs || "";
+      if (values["log-file"] && existsSync(values["log-file"])) {
+        logContent = readFileSync(values["log-file"], "utf-8");
+      }
+
+      const incident = {
+        sessionId,
+        branch: values.branch,
+        reason: values.reason,
+        logs: logContent,
+        critical: values.critical,
+      };
+
+      const res = await dispatchEscalation(incident, {
+        root,
+        config,
+        dryRun: values["dry-run"],
+      });
+
+      if (values.json) {
+        console.log(JSON.stringify({ ok: true, result: res }, null, 2));
+      } else {
+        if (res.buffered) {
+          console.log(`\n🔇 Incident buffered by Silence Governor (${res.reason})`);
+          console.log(`   Session ID   : ${sessionId}`);
+          console.log(`   Digest Count : ${res.digestCount || 1}`);
+          console.log(`   (Use 'agentctl escalate --flush' to deliver immediately)\n`);
+        } else if (res.dispatched) {
+          console.log(`\n🚨 Incident Escalation Dispatched!`);
+          console.log(`   Session ID : ${sessionId}`);
+          console.log(`   Reason     : ${values.reason}`);
+          console.log(`   Slack      : ${res.slack ? "✅ Sent" : "N/A"}`);
+          console.log(`   Discord    : ${res.discord ? "✅ Sent" : "N/A"}\n`);
+        } else {
+          console.log(`⚠️ Escalation not dispatched: ${res.reason}`);
+        }
+      }
+      process.exit(0);
+      break;
+    }
+
+    case "flaky": {
+      const {
+        listQuarantinedTests,
+        clearFlakyLedger,
+        runFlakyHealingSwarm,
+        synthesizeFlakyHealingTask,
+      } = await import("../src/flaky-ledger.mjs");
+
+      const subAction = args[1] || "status";
+      const { values, positionals } = parseArgs({
+        args: args.slice(2),
+        options: {
+          dispatch: { type: "boolean" },
+          role: { type: "string", short: "r", default: "janitor" },
+          "test-cmd": { type: "string", short: "t" },
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      if (subAction === "status" || subAction === "list") {
+        const quarantined = listQuarantinedTests(root);
+        if (values.json) {
+          console.log(JSON.stringify({ ok: true, quarantined, count: quarantined.length }, null, 2));
+        } else {
+          console.log(`\n🧪 Statistical Flaky Test Quarantine (v${VERSION})`);
+          console.log(`--------------------------------------------------`);
+          if (quarantined.length === 0) {
+            console.log(`  ✅ Zero quarantined tests. All suites stable.`);
+          } else {
+            console.log(`  Found ${quarantined.length} test suite(s) quarantined (Exit Code 8):\n`);
+            quarantined.forEach((q, idx) => {
+              const oscPct = Math.round(q.oscillation * 100);
+              console.log(`  ${idx + 1}. \`${q.testCmd}\``);
+              console.log(`     Oscillation: ${oscPct}% (${q.fails} fails / ${q.passes} passes in last ${q.n} runs)`);
+              console.log(`     Wilson CI  : [${q.wilson.lower.toFixed(2)}, ${q.wilson.upper.toFixed(2)}]`);
+              console.log(`     Last Run   : ${q.lastRunTimestamp}\n`);
+            });
+            console.log(`  👉 To dispatch auto-healing swarm, run: agentctl flaky heal`);
+          }
+          console.log(`--------------------------------------------------\n`);
+        }
+        process.exit(0);
+      }
+
+      if (subAction === "heal") {
+        const targetCmd = positionals[0] || values["test-cmd"];
+        let res;
+        if (targetCmd) {
+          const taskPlan = synthesizeFlakyHealingTask({ testCmd: targetCmd }, { role: values.role });
+          if (values.dispatch && !values["dry-run"]) {
+            const { dispatch } = await import("../src/engine.mjs");
+            try {
+              const session = await dispatch(
+                { title: taskPlan.title, prompt: taskPlan.prompt, role: taskPlan.role },
+                { root, config }
+              );
+              taskPlan.session = session;
+              taskPlan.dispatched = true;
+            } catch (err) {
+              taskPlan.dispatchError = err.message;
+              taskPlan.dispatched = false;
+            }
+          } else if (!values["dry-run"]) {
+            const { writeFileSync } = await import("node:fs");
+            const queueDir = getQueueDir(root);
+            const filePath = join(queueDir, `${taskPlan.taskId}.md`);
+            writeFileSync(filePath, taskPlan.fullEnvelope, "utf-8");
+            taskPlan.taskFile = filePath;
+            taskPlan.queued = true;
+          }
+          res = { count: 1, tasks: [taskPlan], dryRun: values["dry-run"] };
+        } else {
+          res = await runFlakyHealingSwarm(root, {
+            dispatch: values.dispatch,
+            dryRun: values["dry-run"],
+            role: values.role,
+          });
+        }
+
+        if (values.json) {
+          console.log(JSON.stringify({ ok: true, ...res }, null, 2));
+        } else {
+          if (res.count === 0) {
+            console.log(`ℹ️ ${res.message || "No quarantined tests to heal."}`);
+          } else {
+            console.log(`\n🩹 Flaky Test Healing Swarm (${res.count} task${res.count > 1 ? "s" : ""})`);
+            console.log(`--------------------------------------------------`);
+            res.tasks.forEach((t) => {
+              console.log(`  • ${t.title}`);
+              if (t.taskFile) console.log(`    Queued: ${t.taskFile}`);
+              if (t.session) console.log(`    Dispatched Session: ${t.session.id}`);
+            });
+            console.log(`--------------------------------------------------\n`);
+          }
+        }
+        process.exit(0);
+      }
+
+      if (subAction === "reset" || subAction === "clear") {
+        const targetCmd = positionals[0] || values["test-cmd"] || null;
+        const res = clearFlakyLedger(root, targetCmd);
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`✅ Flaky test ledger reset (${targetCmd ? `command: ${targetCmd}` : "all tests"}).`);
+        }
+        process.exit(0);
+      }
+
+      console.error(`Unknown flaky subaction: '${subAction}'. Supported: agentctl flaky status | heal | reset`);
+      process.exit(1);
+      break;
+    }
+
     case "test-gen": {
       const { scaffoldTddTest, runTddCycle } = await import("../src/ops/tdd-generator.mjs");
       const { values } = parseArgs({

package/index.mjs

@@ -49,6 +49,9 @@ export {
   rollbackBudgetReservation,
   withBudget,
   checkDailyBudget,
+  scanBudgetWindow,
+  getLedgerPathsInWindow,
+  ROLLING_WINDOW_MS,
   acquireLock,
   releaseLock,
   lockStatus,
@@ -100,8 +103,19 @@ export { scorePromptFalsifiability, optimizeTaskPrompt, levenshteinDistance, ext
 // Atomic Git Checkpoints & Rollback
 export { createCheckpoint, restoreCheckpoint, listCheckpoints, pruneCheckpoints, CheckpointError } from "./src/ops/checkpoint.mjs";
 
-// Webhook & HITL Escalation Bridge
-export { dispatchEscalation, verifySignature, parseWebhookPayload, routeWebhookEvent, createWebhookServer } from "./src/webhook.mjs";
+// Webhook, Silence Governor & HITL Escalation Bridge
+export {
+  dispatchEscalation,
+  verifySignature,
+  parseWebhookPayload,
+  routeWebhookEvent,
+  createWebhookServer,
+  flushEscalationDigest,
+  getEscalationDigestStatus,
+  clearEscalationDigest,
+  bufferEscalationIncident,
+  DEFAULT_CRITICAL_REASONS,
+} from "./src/webhook.mjs";
 
 // PR Review Evidence Bundler & Dev Server Probe
 export { synthesizePrDescription, probeDevServer } from "./src/engine.mjs";
@@ -140,8 +154,22 @@ export {
   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";
+
+// Statistical Flaky Ledger & Automated Healing Swarm
+export {
+  wilsonScoreInterval,
+  computeOscillation,
+  recordVerifyRun,
+  readVerifyRuns,
+  flakyVerdict,
+  listQuarantinedTests,
+  clearFlakyLedger,
+  synthesizeFlakyHealingTask,
+  runFlakyHealingSwarm,
+} from "./src/flaky-ledger.mjs";

package/package.json

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