jules-orchestrator-kit 0.33.0 → 0.35.0

package/src/budget.mjs

@@ -1,25 +1,32 @@
 import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { resolveRoot } from "./config.mjs";
-import { getStateDir, getDailyLedgerPath, ensureDir, appendLedger, checkDailyBudget } from "./state.mjs";
+import {
+  getStateDir,
+  ensureDir,
+  appendLedger,
+  checkDailyBudget,
+  scanBudgetWindow,
+  ROLLING_WINDOW_MS,
+} from "./state.mjs";
 
 /**
  * Where the observed quota ceiling lives, outside the ledger so it survives
  * rotation.
  *
- * Deliberately scoped to the day it was observed. The local ledger only counts
- * tasks dispatched from *this* checkout, while the account's quota is also
- * spent from the web UI and other machines, so the local count at the moment of
- * a refusal is a lower bound on the real allowance — not the allowance. Treated
- * as permanent it would hard-block the operator below their own quota, which is
- * the exact failure this whole mechanism exists to prevent.
+ * Deliberately short-lived. The local ledger only counts tasks dispatched from
+ * *this* checkout, while the account's quota is also spent from the web UI and
+ * other machines, so the local count at the moment of a refusal is a lower
+ * bound on the real allowance — not the allowance. Treated as permanent it
+ * would hard-block the operator below their own quota, which is the exact
+ * failure this whole mechanism exists to prevent.
  *
- * What it does mean is precise and useful: *today* the provider has started
- * refusing, so stop asking until tomorrow.
+ * What it does mean is precise and useful: within the last 24 hours the
+ * provider started refusing, so stop asking until that refusal ages out.
  */
 export const CEILING_FILE = "budget-ceiling.json";
 
-/** Local calendar day, matching the ledger's own rotation key. */
+/** Local calendar day, retained as the fallback key for pre-0.34 records. */
 function today() {
   return new Date().toISOString().split("T")[0];
 }
@@ -67,10 +74,17 @@ function writeAtomic(filePath, content) {
 
 /**
  * Read the stored ceiling, whenever it was observed.
+ *
+ * A refusal expires 24 hours after it happened, matching the window the quota
+ * itself resets on. Expiring it at midnight instead — as this did before —
+ * either freed the operator hours before the provider would, or kept them
+ * blocked hours after it already had.
+ *
  * @param {string} [root]
- * @returns {{ ceiling: number, day: string, observedAt: string, source: string, stale: boolean } | null}
+ * @param {number} [now] - Epoch ms; injectable for tests.
+ * @returns {{ ceiling: number, day: string, observedAt: string, source: string, stale: boolean, expiresAt: string, msRemaining: number } | null}
  */
-export function readObservedCeiling(root = resolveRoot()) {
+export function readObservedCeiling(root = resolveRoot(), now = Date.now()) {
   const filePath = join(getStateDir(root), CEILING_FILE);
   if (!existsSync(filePath)) return null;
   try {
@@ -78,12 +92,24 @@ export function readObservedCeiling(root = resolveRoot()) {
     if (!parsed || typeof parsed.ceiling !== "number" || !Number.isFinite(parsed.ceiling)) return null;
     if (parsed.ceiling < 0) return null;
     const day = typeof parsed.day === "string" ? parsed.day : String(parsed.observedAt || "").slice(0, 10);
+    const observedAt = typeof parsed.observedAt === "string" ? parsed.observedAt : "";
+
+    // Records written before 0.34.0 carry only a day. Falling back to the old
+    // calendar comparison keeps them honest rather than reviving a ceiling
+    // whose age cannot be established.
+    const observedMs = Date.parse(observedAt);
+    const dated = Number.isFinite(observedMs);
+    const age = dated ? now - observedMs : Number.POSITIVE_INFINITY;
+    const stale = dated ? age >= ROLLING_WINDOW_MS : day !== today();
+
     return {
       ceiling: Math.floor(parsed.ceiling),
       day,
-      observedAt: typeof parsed.observedAt === "string" ? parsed.observedAt : "",
+      observedAt,
       source: typeof parsed.source === "string" ? parsed.source : "provider-rejection",
-      stale: day !== today(),
+      stale,
+      expiresAt: dated ? new Date(observedMs + ROLLING_WINDOW_MS).toISOString() : "",
+      msRemaining: dated ? Math.max(0, ROLLING_WINDOW_MS - age) : 0,
     };
   } catch (_) {
     return null;
@@ -94,14 +120,14 @@ export function readObservedCeiling(root = resolveRoot()) {
  * The ceiling only if it still applies — i.e. observed today.
  * @param {string} [root]
  */
-export function readActiveCeiling(root = resolveRoot()) {
-  const rec = readObservedCeiling(root);
+export function readActiveCeiling(root = resolveRoot(), now = Date.now()) {
+  const rec = readObservedCeiling(root, now);
   return rec && !rec.stale ? rec : null;
 }
 
 /**
  * Record that the provider refused further work after `usedAtRejection` tasks
- * were dispatched locally today.
+ * were dispatched locally inside the current window.
  *
  * Zero is a legitimate value: it means the quota was already spent elsewhere
  * (the web UI, another machine) before this checkout dispatched anything.
@@ -166,16 +192,17 @@ export function resolveDailyLimit(config, root = resolveRoot()) {
     };
   }
 
-  // Only today's observation may enforce. Yesterday's refusal says nothing
-  // about today's remaining quota, and carrying it forward would keep the
-  // operator locked out after the quota reset.
+  // Only a refusal from the last 24 hours may enforce. An older one says
+  // nothing about the remaining quota, and carrying it forward would keep the
+  // operator locked out after the window had already reset.
   const learned = readActiveCeiling(root);
   if (learned) {
+    const hours = Math.max(1, Math.round(learned.msRemaining / 3600000));
     return {
       limit: learned.ceiling,
       source: "learned",
       certain: true,
-      note: `the provider refused further work today after ${learned.ceiling} local task(s); resets tomorrow`,
+      note: `the provider refused further work after ${learned.ceiling} local task(s); that refusal ages out in ~${hours}h`,
     };
   }
 
@@ -189,71 +216,61 @@ export function resolveDailyLimit(config, root = resolveRoot()) {
 }
 
 /**
- * List reservations that today's ledger still counts as spent.
+ * Resolve how many workers may run at once, and against what ceiling.
+ *
+ * The same provenance rule as {@link resolveDailyLimit}: a figure the operator
+ * stated is authoritative, a tier preset is a default. The difference is that
+ * exceeding this one is not the kit's call to refuse — the provider enforces
+ * its own slot limit, and an operator pooling several accounts legitimately
+ * runs past any single plan's ceiling. So an overrun is reported, never
+ * blocked.
+ *
+ * @param {object} config - A config from loadConfig().
+ * @returns {{ concurrency: number, ceiling: number, source: "config"|"tier", overCeiling: boolean, note: string }}
+ */
+export function resolveConcurrency(config) {
+  const concurrency = Math.max(1, Math.floor(Number(config?.limits?.concurrency) || 1));
+  const ceiling = Math.floor(Number(config?.limits?.maxConcurrency) || 0);
+  const source = config?.provenance?.concurrency === "config" ? "config" : "tier";
+  const overCeiling = ceiling > 0 && concurrency > ceiling;
+  const tier = config?.tier || "unknown";
+
+  let note;
+  if (overCeiling) {
+    note = `${concurrency} workers exceeds what the "${tier}" plan allows (${ceiling}); sessions past the ${ceiling}th will be refused unless the account pools several plans`;
+  } else if (source === "config") {
+    note = ceiling > 0 ? `set in .agent/config.yml (plan allows up to ${ceiling})` : "set in .agent/config.yml";
+  } else {
+    note = ceiling > 0
+      ? `tier default for "${tier}" — the plan allows up to ${ceiling}, held back to leave slots for sessions this ledger cannot see`
+      : `tier default for "${tier}"`;
+  }
+  return { concurrency, ceiling, source, overCeiling, note };
+}
+
+/**
+ * List reservations the rolling 24-hour window still counts as spent.
  *
  * A reservation is open until a `budget_rolled_back` or `budget_released` entry
  * names it. `budget_committed` deliberately does not close one — a committed
  * dispatch really did consume quota — so the open set is "everything reserved
- * today that was not given back".
+ * inside the window that was not given back".
  *
- * Anonymous reservations (no `reservationId`, as older kit versions and
- * scripts/utils.mjs wrote them) are counted too, as records with
- * `reservationId: null`. They must be, or a reconcile would silently leave them
- * charged against the day: `checkDailyBudget` counts them, and with no id there
- * is nothing a targeted release could name. They are matched by count, the same
- * way the counter itself treats them.
+ * Anonymous reservations (no `reservationId`, as older kit versions wrote them)
+ * appear as records with `reservationId: null`. They must, or a reconcile would
+ * silently leave them charged: the counter counts them, and with no id there is
+ * nothing a targeted release could name.
  *
  * @param {string} [root]
+ * @param {object} [opts] - Forwarded to scanBudgetWindow (`now`, `windowMs`).
  * @returns {{ reservationId: string|null, timestamp: string, committed: boolean }[]}
  */
-export function listOpenReservations(root = resolveRoot()) {
-  const filePath = getDailyLedgerPath(root);
-  if (!existsSync(filePath)) return [];
-
-  /** @type {Map<string, { reservationId: string, timestamp: string, committed: boolean }>} */
-  const open = new Map();
-  /** @type {{ reservationId: null, timestamp: string, committed: boolean }[]} */
-  const anonymous = [];
-  let raw = "";
-  try {
-    raw = readFileSync(filePath, "utf-8");
-  } catch (_) {
-    return [];
-  }
-
-  for (const line of raw.split("\n").filter(Boolean)) {
-    let entry;
-    try {
-      entry = JSON.parse(line);
-    } catch (_) {
-      continue;
-    }
-    if (!entry || !entry.event) continue;
-
-    if (entry.event === "budget_reserved") {
-      if (entry.reservationId) {
-        open.set(entry.reservationId, {
-          reservationId: entry.reservationId,
-          timestamp: entry.timestamp || "",
-          committed: false,
-        });
-      } else {
-        anonymous.push({ reservationId: null, timestamp: entry.timestamp || "", committed: false });
-      }
-    } else if (entry.event === "budget_committed") {
-      const rec = entry.reservationId ? open.get(entry.reservationId) : null;
-      if (rec) rec.committed = true;
-    } else if (entry.event === "budget_rolled_back" || entry.event === "budget_released") {
-      if (entry.reservationId) open.delete(entry.reservationId);
-      else anonymous.pop();
-    }
-  }
-
-  return [...open.values(), ...anonymous];
+export function listOpenReservations(root = resolveRoot(), opts = {}) {
+  return scanBudgetWindow(root, opts).open;
 }
 
 /**
- * Give today's open reservations back, by appending `budget_released` entries.
+ * Give the window's open reservations back, by appending `budget_released` entries.
  *
  * The ledger is append-only and hash-chained, so a miscounted day is corrected
  * forwards — never by editing or deleting the file, which would break the chain
@@ -286,10 +303,16 @@ export function releaseOpenReservations(opts = {}) {
 
   for (const rec of openRecords) {
     const entry = { event: "budget_released", reason: opts.reason || "operator-reconcile" };
-    // An anonymous reservation is released by an equally anonymous entry: the
-    // counter decrements those by count, so naming an id here would leave the
-    // original charged and subtract from someone else's total instead.
-    if (rec.reservationId) entry.reservationId = rec.reservationId;
+    if (rec.reservationId) {
+      entry.reservationId = rec.reservationId;
+    } else {
+      // An anonymous reservation is released by an equally anonymous entry —
+      // naming an id here would leave the original charged and subtract from
+      // someone else's total instead. The timestamp pins which one it cancels,
+      // so the pair does not drift apart as the rolling window advances past
+      // the reservation but not yet past its release.
+      entry.releasedTimestamp = rec.timestamp;
+    }
     appendLedger(entry, root);
   }
   return result;
@@ -311,6 +334,10 @@ export function budgetStatus(config, root = resolveRoot()) {
     source: resolved.source,
     certain: resolved.certain,
     note: resolved.note,
+    // The count is a rolling 24h window, not a calendar day — surfaced so a
+    // caller reporting "used today" cannot quietly mean something else.
+    windowStart: check.windowStart || "",
+    windowHours: ROLLING_WINDOW_MS / 3600000,
     // Only a limit we actually know may stop a dispatch.
     enforced: resolved.certain,
     exhausted: check.used >= resolved.limit,

package/src/config.mjs

@@ -281,35 +281,63 @@ export function resolveVerify(root = process.cwd(), userVerify = {}) {
  * guess — see `isTierGuess()` and the learned-ceiling logic in src/state.mjs.
  * An explicit `limits.daily_tasks` in .agent/config.yml always wins.
  */
+/**
+ * Per-tier defaults, with the vendor's own ceiling recorded alongside them.
+ *
+ * `maxConcurrency` is what the plan allows; `concurrency` is what the kit will
+ * start by using. They differ on purpose, for the same reason the daily count
+ * is a lower bound: this ledger sees one checkout, while the account's slots
+ * are also taken by the web UI, the CLI and other machines. A default sitting
+ * on the ceiling would collide with every session the kit cannot see.
+ *
+ * The defaults used to sit at 1/2/3 against ceilings of 3/15/60 — a Pro
+ * account running two workers where it could run fifteen. Raising them is the
+ * single largest throughput change available; leaving headroom is what keeps
+ * it from being reckless. An operator who knows their account is theirs alone
+ * can state `limits.concurrency` up to the ceiling.
+ *
+ * Ceilings verified against the vendor's published limits page
+ * (jules.google/docs/usage-limits, 2026-08-20). They are a vendor number and
+ * may change without notice. The URL is written without a scheme on purpose:
+ * test/egress-allowlist.test.mjs treats every host literal in shipped source
+ * as a destination this kit might contact, and a citation is not one.
+ */
 export const TIER_PRESETS = {
   free: {
     dailyTasks: 15,
     repairAttempts: 1,
-    concurrency: 1,
+    // The whole allowance is 15 tasks a day; there is no headroom worth
+    // reserving, so the default is the ceiling.
+    concurrency: 3,
+    maxConcurrency: 3,
     staggerMs: 3000,
     diffKb: 50,
   },
   pro: {
     dailyTasks: 100,
     repairAttempts: 2,
-    concurrency: 2,
+    concurrency: 8,
+    maxConcurrency: 15,
     staggerMs: 1500,
     diffKb: 75,
   },
   ultra: {
     dailyTasks: 300,
     repairAttempts: 3,
-    concurrency: 3,
+    concurrency: 15,
+    maxConcurrency: 60,
     staggerMs: 1000,
     diffKb: 75,
   },
   // Not a vendor plan: a self-hosted/pooled profile for operators who front
   // several accounts. Defined here so `tier: enterprise` resolves to what the
-  // wizard writes instead of silently collapsing onto the ultra preset.
+  // wizard writes instead of silently collapsing onto the ultra preset. Its
+  // ceiling is whatever the pool adds up to, so the kit does not claim one.
   enterprise: {
     dailyTasks: 1000,
     repairAttempts: 3,
     concurrency: 10,
+    maxConcurrency: 0,
     staggerMs: 500,
     diffKb: 100,
   },
@@ -401,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,
@@ -420,6 +463,7 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
           : normalizedLimits.dailyTasks !== undefined
             ? "config"
             : "tier",
+      concurrency: normalizedLimits.concurrency !== undefined ? "config" : "tier",
     },
     isolation: parsed.isolation || DEFAULTS.isolation,
     runner: parsed.runner || DEFAULTS.runner,

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" },
+    ],
+  },
 ];
 
 /**