jules-orchestrator-kit 0.34.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 **510 unit tests across 77 suites passing in < 10.0s**. An adversarial red-team suite (`test/adversarial-claims.test.mjs`) continuously attempts to falsify the safety guarantees documented above — including cross-platform probes for the case-insensitive filesystems on macOS and Windows — and a documentation-sync gate (`scripts/doc-sync-check.mjs`) blocks any release whose docs have drifted from the code.
+* **📈 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/>
 
@@ -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

@@ -59,6 +59,8 @@ 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 the 24h task budget, worker slots and their provenance (reset --yes)
   scan                  Scan codebase for TODO/FIXME task candidates
@@ -779,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

@@ -103,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";
@@ -149,3 +160,16 @@ export {
 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.34.0",
+  "version": "0.35.0",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/src/config.mjs

@@ -429,6 +429,21 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
       complex: parsed.router?.complex || "",
       threshold: Number.isFinite(Number(parsed.router?.threshold)) ? Number(parsed.router.threshold) : 0,
     },
+    notifications: {
+      mode: parsed.notifications?.mode || "immediate",
+      threshold: Number.isFinite(Number(parsed.notifications?.threshold)) ? Number(parsed.notifications.threshold) : 5,
+      windowMs: Number.isFinite(Number(parsed.notifications?.window_ms ?? parsed.notifications?.windowMs))
+        ? Number(parsed.notifications.window_ms ?? parsed.notifications.windowMs)
+        : 300000,
+      budgetPerHour: Number.isFinite(Number(parsed.notifications?.budget_per_hour ?? parsed.notifications?.budgetPerHour))
+        ? Number(parsed.notifications.budget_per_hour ?? parsed.notifications.budgetPerHour)
+        : 3,
+      criticalReasons: Array.isArray(parsed.notifications?.critical_reasons)
+        ? parsed.notifications.critical_reasons
+        : ["R3_GATE_VIOLATION", "AWAITING_USER_FEEDBACK", "OODA_REPAIR_EXHAUSTED", "SECRET_LEAK_DETECTED", "CRITICAL_FAILURE"],
+      slackWebhookUrl: parsed.notifications?.slack_webhook_url || parsed.notifications?.slackWebhookUrl || "",
+      discordWebhookUrl: parsed.notifications?.discord_webhook_url || parsed.notifications?.discordWebhookUrl || "",
+    },
     scope: normalizeScope(parsed),
     limits: {
       ...DEFAULTS.limits,

package/src/flaky-ledger.mjs

@@ -1,6 +1,7 @@
-import { readFileSync, existsSync, appendFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, appendFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { getStateDir, ensureDir } from "./state.mjs";
+import { getStateDir, getQueueDir, ensureDir } from "./state.mjs";
+import { resolveRoot } from "./config.mjs";
 
 /**
  * Calculates Wilson score interval for binomial proportion.
@@ -169,3 +170,205 @@ export function flakyVerdict(runs = []) {
     wilson,
   };
 }
+
+/**
+ * Lists all test suites/commands currently classified as QUARANTINED in .agent/state/flaky.jsonl.
+ * @param {string} [root]
+ * @returns {Array<object>} Quarantined tests with oscillation & Wilson stats
+ */
+export function listQuarantinedTests(root = resolveRoot()) {
+  const allRuns = readVerifyRuns(root);
+  if (allRuns.length === 0) return [];
+
+  // Group by testCmd
+  const grouped = new Map();
+  for (const run of allRuns) {
+    const cmd = run.testCmd || "default";
+    if (!grouped.has(cmd)) grouped.set(cmd, []);
+    grouped.get(cmd).push(run);
+  }
+
+  const quarantined = [];
+  for (const [testCmd, runs] of grouped.entries()) {
+    const verdict = flakyVerdict(runs);
+    if (verdict.verdict === "QUARANTINED") {
+      const lastRun = runs[runs.length - 1];
+      quarantined.push({
+        testCmd,
+        verdict: verdict.verdict,
+        oscillation: verdict.oscillation,
+        fails: verdict.fails,
+        passes: verdict.passes,
+        n: verdict.n,
+        wilson: verdict.wilson,
+        lastRunTimestamp: lastRun?.timestamp || new Date().toISOString(),
+        lastDurationMs: lastRun?.durationMs || 0,
+        fingerprint: lastRun?.fingerprint || null,
+      });
+    }
+  }
+
+  return quarantined;
+}
+
+/**
+ * Clears flaky ledger entries for all tests or a specific command.
+ * @param {string} [root]
+ * @param {string} [testCmd]
+ */
+export function clearFlakyLedger(root = resolveRoot(), testCmd = null) {
+  const stateDir = getStateDir(root);
+  const filePath = join(stateDir, "flaky.jsonl");
+  if (!existsSync(filePath)) return { ok: true, cleared: 0 };
+
+  if (!testCmd) {
+    try {
+      unlinkSync(filePath);
+    } catch (_) {
+      writeFileSync(filePath, "", "utf-8");
+    }
+    return { ok: true, cleared: "all" };
+  }
+
+  const runs = readVerifyRuns(root);
+  const retained = runs.filter((r) => r.testCmd !== testCmd);
+  const clearedCount = runs.length - retained.length;
+  writeFileSync(filePath, retained.map((r) => JSON.stringify(r)).join("\n") + (retained.length ? "\n" : ""), "utf-8");
+  return { ok: true, cleared: clearedCount, remaining: retained.length };
+}
+
+/**
+ * Synthesizes a specialized anti-flakiness prompt envelope for a quarantined test.
+ * @param {object|string} quarantinedItem - Quarantined item object or test command string
+ * @param {object} [options]
+ * @returns {{ taskId: string, title: string, prompt: string, role: string, verifyCmd: string, fullEnvelope: string }}
+ */
+export function synthesizeFlakyHealingTask(quarantinedItem, options = {}) {
+  const item = typeof quarantinedItem === "string" ? { testCmd: quarantinedItem, oscillation: 0.5, fails: 3, passes: 3, n: 6 } : quarantinedItem;
+  const testCmd = item.testCmd || "npm test";
+  const oscillationPct = Math.round((item.oscillation || 0.4) * 100);
+  const role = options.role || "janitor";
+  const slug = String(testCmd).replace(/[^a-zA-Z0-9]/g, "-").replace(/-+/g, "-").slice(0, 20).toLowerCase();
+  const taskId = options.taskId || `flaky-heal-${slug}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+
+  // Build verification oracle that verifies deterministic stability over multiple consecutive runs
+  const verifyOracle = options.verifyCmd || `${testCmd} && ${testCmd} && ${testCmd}`;
+
+  const prompt = `# Task: Eliminate Flaky Test Timing Oscillations & Race Conditions
+
+## Context & Statistical Diagnosis
+The test command \`${testCmd}\` has been quarantined by the Wilson-Score Statistical Flaky Guard (Exit Code 8).
+- **Oscillation Rate**: ${oscillationPct}% state transitions between passes and failures
+- **Total Sample Window**: ${item.n || 6} runs (${item.fails || 3} failures, ${item.passes || 3} passes)
+- **Quarantine Verdict**: Statistical non-determinism detected (Wilson CI interior score).
+
+## Root Cause Remediations Required
+1. **Eliminate Arbitrary Sleep & Polling Race Conditions**:
+   - Replace arbitrary timers (\`sleep()\`, \`setTimeout()\`, \`delay()\`) with deterministic condition-based assertions or event-driven completion promises.
+2. **State & Resource Isolation**:
+   - Ensure tests clean up global variables, open socket descriptors, temporary filesystem directories, or database handles in \`afterEach\` / teardown hooks.
+   - Prevent port collisions by binding to ephemeral ports (port \`0\`) or namespaced mutexes.
+3. **Mock Unreliable Boundaries**:
+   - Intercept and mock non-deterministic external network calls, system clocks, and asynchronous background timers.
+4. **STRICT INVARIANT: NO TEST WEAKENING**:
+   - You are **strictly forbidden** from deleting failing assertions, commenting out checks, skipping test cases, or increasing broad timeouts indefinitely to force a pass.
+   - The test requirements and assertions must remain 100% rigorous; only the underlying non-determinism, race conditions, or unhandled timing flaws must be fixed.
+
+## Verification Gate
+Before opening PR, the test must pass cleanly across consecutive executions without a single oscillation:
+\`\`\`bash
+${verifyOracle}
+\`\`\``;
+
+  const title = `Heal Flaky Test: ${testCmd.slice(0, 50)}`;
+
+  const envelopeMetadata = {
+    version: 1,
+    id: taskId,
+    title,
+    role,
+    verifyCmd: verifyOracle,
+  };
+
+  const fullEnvelope = `<!-- JULES_TASK_ENVELOPE: ${JSON.stringify(envelopeMetadata)} -->
+# ${title}
+# Task ID: ${taskId}
+
+[TASK INSTRUCTIONS]
+${prompt}
+
+[VERIFICATION ORACLE]
+Test/Verification Command: ${verifyOracle}
+`;
+
+  return {
+    taskId,
+    title,
+    prompt,
+    role,
+    verifyCmd: verifyOracle,
+    fullEnvelope,
+    item,
+  };
+}
+
+/**
+ * Runs the Flaky Healing Swarm: scans quarantined tests, synthesizes healing envelopes,
+ * and either enqueues them in .agent/jules-queue/ or dispatches them directly.
+ * @param {string} [root]
+ * @param {object} [options]
+ * @returns {Promise<object>}
+ */
+export async function runFlakyHealingSwarm(root = resolveRoot(), options = {}) {
+  const quarantined = listQuarantinedTests(root);
+  if (quarantined.length === 0) {
+    return { count: 0, tasks: [], message: "No quarantined flaky tests detected in repository." };
+  }
+
+  const tasks = [];
+  const queueDir = getQueueDir(root);
+
+  for (const item of quarantined) {
+    const taskPlan = synthesizeFlakyHealingTask(item, options);
+    tasks.push(taskPlan);
+
+    if (options.dryRun) {
+      continue;
+    }
+
+    if (options.dispatch) {
+      const { dispatch } = await import("./engine.mjs");
+      const { loadConfig } = await import("./config.mjs");
+      const config = loadConfig(root);
+      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 {
+      const fileName = `${taskPlan.taskId}.md`;
+      const filePath = join(queueDir, fileName);
+      writeFileSync(filePath, taskPlan.fullEnvelope, "utf-8");
+      taskPlan.taskFile = filePath;
+      taskPlan.queued = true;
+    }
+  }
+
+  return {
+    count: tasks.length,
+    tasks,
+    queued: !options.dispatch && !options.dryRun,
+    dispatched: Boolean(options.dispatch && !options.dryRun),
+    dryRun: Boolean(options.dryRun),
+  };
+}

package/src/ops/command-registry.mjs

@@ -222,6 +222,60 @@ export const COMMAND_REGISTRY = [
       { name: "json", type: "boolean", description: "Output status in JSON format" },
     ],
   },
+  {
+    id: "escalate",
+    path: ["escalate"],
+    title: "escalate",
+    description: "Dispatch or manage webhook escalation incidents with Silence Governor",
+    category: "Operate",
+    mutates: true,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["esc"],
+    examples: [
+      'agentctl escalate sess-123 --reason "AWAITING_USER_FEEDBACK"',
+      "agentctl escalate --status",
+      "agentctl escalate --flush",
+      "agentctl escalate --clear",
+    ],
+    flags: [
+      { name: "reason", type: "string", description: "Escalation reason category" },
+      { name: "branch", type: "string", description: "Target git branch" },
+      { name: "logs", type: "string", description: "Error logs text" },
+      { name: "critical", type: "boolean", description: "Bypass Silence Governor and alert immediately" },
+      { name: "flush", type: "boolean", description: "Flush buffered escalation digest" },
+      { name: "status", type: "boolean", description: "Inspect digest status and interruption budget" },
+      { name: "clear", type: "boolean", description: "Clear pending digest buffer" },
+      { name: "dry-run", type: "boolean", description: "Simulate dispatch without sending HTTP requests" },
+      { name: "json", type: "boolean", description: "Output JSON structured response" },
+    ],
+  },
+  {
+    id: "flaky",
+    path: ["flaky"],
+    title: "flaky",
+    description: "Manage Wilson-quarantined tests and dispatch healing swarm",
+    category: "Repair",
+    mutates: true,
+    risk: "moderate",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["flk"],
+    examples: [
+      "agentctl flaky status",
+      "agentctl flaky heal",
+      'agentctl flaky heal "npm test"',
+      "agentctl flaky reset",
+    ],
+    flags: [
+      { name: "dispatch", type: "boolean", description: "Dispatch healing tasks directly to AI agents" },
+      { name: "role", type: "string", description: "Agent persona role (default: janitor)" },
+      { name: "test-cmd", type: "string", description: "Target specific test command" },
+      { name: "dry-run", type: "boolean", description: "Simulate healing swarm generation without writing" },
+      { name: "json", type: "boolean", description: "Output JSON structured response" },
+    ],
+  },
 ];
 
 /**

package/src/webhook.mjs

@@ -1,5 +1,420 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { getStateDir } from "./state.mjs";
+import { resolveRoot } from "./config.mjs";
+import { redactSecrets } from "./security.mjs";
+
+export const DEFAULT_CRITICAL_REASONS = [
+  "R3_GATE_VIOLATION",
+  "AWAITING_USER_FEEDBACK",
+  "OODA_REPAIR_EXHAUSTED",
+  "SECRET_LEAK_DETECTED",
+  "CRITICAL_FAILURE",
+];
+
+export function getDigestFilePath(root = resolveRoot()) {
+  return join(getStateDir(root), "escalation-digest.json");
+}
+
+export function getInterruptionLedgerPath(root = resolveRoot()) {
+  return join(getStateDir(root), "interruption-ledger.json");
+}
+
+export function loadEscalationDigest(root = resolveRoot()) {
+  const file = getDigestFilePath(root);
+  if (!existsSync(file)) return { incidents: [], createdAt: null, updatedAt: null };
+  try {
+    const raw = readFileSync(file, "utf-8");
+    const data = JSON.parse(raw);
+    return {
+      incidents: Array.isArray(data.incidents) ? data.incidents : [],
+      createdAt: data.createdAt || null,
+      updatedAt: data.updatedAt || null,
+    };
+  } catch (_) {
+    return { incidents: [], createdAt: null, updatedAt: null };
+  }
+}
+
+export function saveEscalationDigest(root = resolveRoot(), digestData = {}) {
+  const file = getDigestFilePath(root);
+  const data = {
+    incidents: digestData.incidents || [],
+    createdAt: digestData.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(file, JSON.stringify(data, null, 2), "utf-8");
+  return data;
+}
+
+export function clearEscalationDigest(root = resolveRoot()) {
+  const file = getDigestFilePath(root);
+  if (existsSync(file)) {
+    try {
+      unlinkSync(file);
+    } catch (_) {
+      writeFileSync(file, JSON.stringify({ incidents: [], createdAt: null, updatedAt: null }), "utf-8");
+    }
+  }
+  return { ok: true, cleared: true };
+}
+
+export function bufferEscalationIncident(incident = {}, root = resolveRoot()) {
+  const current = loadEscalationDigest(root);
+  const rawLogs = incident.logs || incident.error || "";
+  const scrubbedLogs = rawLogs ? redactSecrets(String(rawLogs)) : "";
+  const entry = {
+    id: incident.sessionId || `incident-${Date.now()}`,
+    sessionId: incident.sessionId || "unknown-session",
+    taskId: incident.taskId || "agent-task",
+    branch: incident.branch || "main",
+    reason: incident.reason || "NON_CRITICAL_EVENT",
+    logs: scrubbedLogs.split("\n").slice(-10).join("\n"),
+    timestamp: incident.timestamp || new Date().toISOString(),
+  };
+  const updatedIncidents = [...current.incidents, entry];
+  saveEscalationDigest(root, {
+    incidents: updatedIncidents,
+    createdAt: current.createdAt || new Date().toISOString(),
+  });
+  return {
+    buffered: true,
+    count: updatedIncidents.length,
+    incident: entry,
+  };
+}
+
+export function loadInterruptionLedger(root = resolveRoot()) {
+  const file = getInterruptionLedgerPath(root);
+  if (!existsSync(file)) return [];
+  try {
+    const raw = readFileSync(file, "utf-8");
+    const arr = JSON.parse(raw);
+    return Array.isArray(arr) ? arr : [];
+  } catch (_) {
+    return [];
+  }
+}
+
+export function recordInterruption(root = resolveRoot()) {
+  const file = getInterruptionLedgerPath(root);
+  const now = Date.now();
+  const entries = loadInterruptionLedger(root).filter((ts) => now - ts < 3600000); // 1 hour sliding window
+  entries.push(now);
+  writeFileSync(file, JSON.stringify(entries), "utf-8");
+  return entries.length;
+}
+
+export function countRecentInterruptions(root = resolveRoot(), windowMs = 3600000) {
+  const now = Date.now();
+  const entries = loadInterruptionLedger(root);
+  return entries.filter((ts) => now - ts < windowMs).length;
+}
+
+export function getEscalationDigestStatus(root = resolveRoot(), config = {}) {
+  const digest = loadEscalationDigest(root);
+  const notifications = config.notifications || {};
+  const budgetPerHour = notifications.budgetPerHour ?? 3;
+  const recentInterruptions = countRecentInterruptions(root);
+
+  return {
+    pendingCount: digest.incidents.length,
+    incidents: digest.incidents,
+    createdAt: digest.createdAt,
+    updatedAt: digest.updatedAt,
+    budgetPerHour,
+    recentInterruptions,
+    budgetAvailable: Math.max(0, budgetPerHour - recentInterruptions),
+    mode: notifications.mode || "immediate",
+    threshold: notifications.threshold || 5,
+  };
+}
+
+export async function flushEscalationDigest(config = {}, options = {}) {
+  const root = options.root || resolveRoot();
+  const digest = loadEscalationDigest(root);
+  if (digest.incidents.length === 0) {
+    return { flushed: false, count: 0, reason: "No pending incidents in digest" };
+  }
+
+  const notifications = config.notifications || {};
+  const slackUrl = process.env.SLACK_WEBHOOK_URL || notifications.slackWebhookUrl || config.slackWebhookUrl || "";
+  const discordUrl = process.env.DISCORD_WEBHOOK_URL || notifications.discordWebhookUrl || config.discordWebhookUrl || "";
+  const dryRun = options.dryRun || config.dryRun || false;
+
+  const count = digest.incidents.length;
+  const results = { flushed: true, count, slack: false, discord: false, dryRun };
+
+  if (dryRun) {
+    if (!options.preserve) clearEscalationDigest(root);
+    return {
+      ...results,
+      payload: {
+        count,
+        incidents: digest.incidents,
+      },
+    };
+  }
+
+  if (!slackUrl && !discordUrl) {
+    return { flushed: false, count, slack: false, discord: false, reason: "No webhook URL configured" };
+  }
+
+  // Format Slack digest
+  if (slackUrl) {
+    try {
+      const summaryText = digest.incidents
+        .map((inc) => `• *\`${inc.sessionId}\`* on \`${inc.branch}\` [${inc.reason}]: \`agentctl resume ${inc.sessionId}\``)
+        .join("\n");
+
+      const slackBody = {
+        text: `📋 *Jules Escalation Digest* (${count} batched incident${count > 1 ? "s" : ""})`,
+        blocks: [
+          {
+            type: "header",
+            text: { type: "plain_text", text: `📋 Jules Escalation Digest (${count} incidents)` },
+          },
+          {
+            type: "section",
+            text: { type: "mrkdwn", text: summaryText.slice(0, 2500) },
+          },
+          {
+            type: "context",
+            elements: [
+              { type: "mrkdwn", text: `Aggregated by Type III Silence Governor · Oldest: ${digest.createdAt || "N/A"}` },
+            ],
+          },
+        ],
+      };
+
+      const res = await fetch(slackUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(slackBody),
+      });
+      results.slack = res.ok;
+    } catch (_) {
+      results.slack = false;
+    }
+  }
+
+  // Format Discord digest
+  if (discordUrl) {
+    try {
+      const fields = digest.incidents.slice(0, 10).map((inc) => ({
+        name: `Session \`${inc.sessionId}\` [${inc.reason}]`,
+        value: `Branch: \`${inc.branch}\`\n\`agentctl resume ${inc.sessionId} --response "<answer>"\``,
+        inline: false,
+      }));
+
+      const discordBody = {
+        content: `📋 **Jules Escalation Digest** (${count} batched incident${count > 1 ? "s" : ""})`,
+        embeds: [
+          {
+            title: `Escalation Digest (${count} incidents)`,
+            color: 3447003,
+            fields,
+            footer: { text: `Aggregated by Type III Silence Governor · Total: ${count}` },
+          },
+        ],
+      };
+
+      const res = await fetch(discordUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(discordBody),
+      });
+      results.discord = res.ok;
+    } catch (_) {
+      results.discord = false;
+    }
+  }
+
+  if (results.slack || results.discord) {
+    if (!options.preserve) {
+      clearEscalationDigest(root);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Dispatches an asynchronous escalation incident payload to configured Slack and/or Discord webhooks,
+ * governed by the Type III Silence Governor and interruption budget.
+ * @param {object} incident - Incident details
+ * @param {string} incident.sessionId
+ * @param {string} [incident.taskId]
+ * @param {string} [incident.branch]
+ * @param {string} [incident.reason] - AWAITING_USER_FEEDBACK | OODA_REPAIR_EXHAUSTED | R3_GATE_VIOLATION
+ * @param {string} [incident.logs] - Last 20 lines of compiler/test output
+ * @param {boolean} [incident.critical] - Force immediate alert
+ * @param {object} [config]
+ * @returns {Promise<object>} Dispatch status
+ */
+export async function dispatchEscalation(incident = {}, config = {}) {
+  const root = config.root || resolveRoot();
+  const notifications = config.notifications || {};
+  const mode = (notifications.mode || config.notificationMode || "immediate").toLowerCase();
+  const threshold = notifications.threshold || 5;
+  const budgetPerHour = notifications.budgetPerHour ?? 3;
+  const criticalReasons = notifications.criticalReasons || DEFAULT_CRITICAL_REASONS;
+
+  const reason = incident.reason || "AWAITING_USER_FEEDBACK";
+  const isCritical = incident.critical === true || criticalReasons.includes(reason) || config.forceImmediate === true;
+
+  // Non-critical governance
+  if (!isCritical) {
+    if (mode === "silent") {
+      bufferEscalationIncident(incident, root);
+      return {
+        dispatched: false,
+        buffered: true,
+        silent: true,
+        reason: "SILENT_MODE",
+      };
+    }
+
+    if (mode === "digest" || mode === "threshold") {
+      const bufferRes = bufferEscalationIncident(incident, root);
+      if (bufferRes.count >= threshold) {
+        return await flushEscalationDigest(config, { root, dryRun: config.dryRun });
+      }
+      return {
+        dispatched: false,
+        buffered: true,
+        digestCount: bufferRes.count,
+        reason: "BUFFERED_IN_DIGEST",
+      };
+    }
+
+    // mode === "immediate" with interruption budget
+    const recentCount = countRecentInterruptions(root);
+    if (recentCount >= budgetPerHour) {
+      const bufferRes = bufferEscalationIncident(incident, root);
+      return {
+        dispatched: false,
+        buffered: true,
+        digestCount: bufferRes.count,
+        reason: "INTERRUPTION_BUDGET_EXCEEDED",
+      };
+    }
+  }
+
+  // If immediate/critical dispatch:
+  if (!isCritical) {
+    recordInterruption(root);
+  }
+
+  const slackUrl = process.env.SLACK_WEBHOOK_URL || notifications.slackWebhookUrl || config.slackWebhookUrl || "";
+  const discordUrl = process.env.DISCORD_WEBHOOK_URL || notifications.discordWebhookUrl || config.discordWebhookUrl || "";
+
+  if (!slackUrl && !discordUrl && !config.dryRun) {
+    return { dispatched: false, slack: false, discord: false, reason: "No webhook URL configured" };
+  }
+
+  const sessionId = incident.sessionId || "unknown-session";
+  const taskId = incident.taskId || "agent-task";
+  const branch = incident.branch || "main";
+  const rawLogs = incident.logs || incident.error || "No error log attached.";
+
+  // Normalize last 20 lines of logs with secret scrubbing
+  const scrubbedLogs = redactSecrets(String(rawLogs));
+  const logLines = scrubbedLogs.split("\n").slice(-20).join("\n");
+  const resumeCmd = `agentctl resume ${sessionId} --response "<your-answer>"`;
+
+  const results = { dispatched: true, slack: false, discord: false };
+
+  if (config.dryRun) {
+    return {
+      ...results,
+      dryRun: true,
+      payload: {
+        sessionId,
+        taskId,
+        reason,
+        resumeCmd,
+        logLines,
+      },
+    };
+  }
+
+  // Dispatch to Slack
+  if (slackUrl) {
+    try {
+      const slackBody = {
+        text: `🚨 *Jules Agent Escalation* [${reason}]: Session ${sessionId}`,
+        blocks: [
+          {
+            type: "header",
+            text: { type: "plain_text", text: `🚨 Jules Escalation: ${reason}` },
+          },
+          {
+            type: "section",
+            fields: [
+              { type: "mrkdwn", text: `*Session ID:*\n\`${sessionId}\`` },
+              { type: "mrkdwn", text: `*Branch:*\n\`${branch}\`` },
+            ],
+          },
+          {
+            type: "section",
+            text: { type: "mrkdwn", text: `*Recent Log Output:*\n\`\`\`${logLines.slice(0, 1000)}\`\`\`` },
+          },
+          {
+            type: "context",
+            elements: [
+              { type: "mrkdwn", text: `👉 *To resume session run:* \`${resumeCmd}\`` },
+            ],
+          },
+        ],
+      };
+
+      const res = await fetch(slackUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(slackBody),
+      });
+      results.slack = res.ok;
+    } catch (_) {
+      results.slack = false;
+    }
+  }
+
+  // Dispatch to Discord
+  if (discordUrl) {
+    try {
+      const discordBody = {
+        content: `🚨 **Jules Agent Escalation** [${reason}] for session \`${sessionId}\``,
+        embeds: [
+          {
+            title: `Escalation Reason: ${reason}`,
+            color: 15158332, // Red
+            fields: [
+              { name: "Session ID", value: `\`${sessionId}\``, inline: true },
+              { name: "Branch", value: `\`${branch}\``, inline: true },
+              { name: "Resume Command", value: `\`${resumeCmd}\`` },
+            ],
+            description: `\`\`\`\n${logLines.slice(0, 1000)}\n\`\`\``,
+          },
+        ],
+      };
+
+      const res = await fetch(discordUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(discordBody),
+      });
+      results.discord = res.ok;
+    } catch (_) {
+      results.discord = false;
+    }
+  }
+
+  return results;
+}
+
 
 /**
  * Verify GitHub webhook HMAC SHA-256 signature against request payload.
@@ -186,122 +601,3 @@ export function createWebhookServer({ _port = 8787, secret = process.env.JULES_W
   return server;
 }
 
-/**
- * Dispatches an asynchronous escalation incident payload to configured Slack and/or Discord webhooks.
- * @param {object} incident - Incident details
- * @param {string} incident.sessionId
- * @param {string} [incident.taskId]
- * @param {string} [incident.branch]
- * @param {string} [incident.reason] - AWAITING_USER_FEEDBACK | OODA_REPAIR_EXHAUSTED | R3_GATE_VIOLATION
- * @param {string} [incident.logs] - Last 20 lines of compiler/test output
- * @param {object} [config]
- * @returns {Promise<object>} Dispatch status { dispatched: boolean, slack: boolean, discord: boolean }
- */
-export async function dispatchEscalation(incident = {}, config = {}) {
-  const slackUrl = process.env.SLACK_WEBHOOK_URL || config.slackWebhookUrl || "";
-  const discordUrl = process.env.DISCORD_WEBHOOK_URL || config.discordWebhookUrl || "";
-
-  if (!slackUrl && !discordUrl && !config.dryRun) {
-    return { dispatched: false, slack: false, discord: false, reason: "No webhook URL configured" };
-  }
-
-  const sessionId = incident.sessionId || "unknown-session";
-  const taskId = incident.taskId || "agent-task";
-  const branch = incident.branch || "main";
-  const reason = incident.reason || "AWAITING_USER_FEEDBACK";
-  const rawLogs = incident.logs || incident.error || "No error log attached.";
-
-  // Normalize last 20 lines of logs
-  const logLines = String(rawLogs).split("\n").slice(-20).join("\n");
-  const resumeCmd = `agentctl resume ${sessionId} --response "<your-answer>"`;
-
-  const results = { dispatched: true, slack: false, discord: false };
-
-  if (config.dryRun) {
-    return {
-      ...results,
-      dryRun: true,
-      payload: {
-        sessionId,
-        taskId,
-        reason,
-        resumeCmd,
-        logLines,
-      },
-    };
-  }
-
-  // Dispatch to Slack
-  if (slackUrl) {
-    try {
-      const slackBody = {
-        text: `🚨 *Jules Agent Escalation* [${reason}]: Session ${sessionId}`,
-        blocks: [
-          {
-            type: "header",
-            text: { type: "plain_text", text: `🚨 Jules Escalation: ${reason}` },
-          },
-          {
-            type: "section",
-            fields: [
-              { type: "mrkdwn", text: `*Session ID:*\n\`${sessionId}\`` },
-              { type: "mrkdwn", text: `*Branch:*\n\`${branch}\`` },
-            ],
-          },
-          {
-            type: "section",
-            text: { type: "mrkdwn", text: `*Recent Log Output:*\n\`\`\`${logLines.slice(0, 1000)}\`\`\`` },
-          },
-          {
-            type: "context",
-            elements: [
-              { type: "mrkdwn", text: `👉 *To resume session run:* \`${resumeCmd}\`` },
-            ],
-          },
-        ],
-      };
-
-      const res = await fetch(slackUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(slackBody),
-      });
-      results.slack = res.ok;
-    } catch (_) {
-      results.slack = false;
-    }
-  }
-
-  // Dispatch to Discord
-  if (discordUrl) {
-    try {
-      const discordBody = {
-        content: `🚨 **Jules Agent Escalation** [${reason}] for session \`${sessionId}\``,
-        embeds: [
-          {
-            title: `Escalation Reason: ${reason}`,
-            color: 15158332, // Red
-            fields: [
-              { name: "Session ID", value: `\`${sessionId}\``, inline: true },
-              { name: "Branch", value: `\`${branch}\``, inline: true },
-              { name: "Resume Command", value: `\`${resumeCmd}\`` },
-            ],
-            description: `\`\`\`\n${logLines.slice(0, 1000)}\n\`\`\``,
-          },
-        ],
-      };
-
-      const res = await fetch(discordUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(discordBody),
-      });
-      results.discord = res.ok;
-    } catch (_) {
-      results.discord = false;
-    }
-  }
-
-  return results;
-}
-