jules-orchestrator-kit 0.41.1 → 0.51.0

package/src/ops/checkpoint.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { git, changedFiles, diffText } from "../git.mjs";
-import { resolveRoot } from "../config.mjs";
+import { resolveRoot, isWindowsAbsolutePath } from "../config.mjs";
 
 export class CheckpointError extends Error {
   constructor(message, opts = {}) {
@@ -11,6 +11,29 @@ export class CheckpointError extends Error {
   }
 }
 
+// Checkpoint ids are used verbatim as the snapshot filename under
+// `.agent/state/checkpoints/`. An id that is not a single plain filename —
+// `../…`, `C:\…`, `\\server\share`, or any value carrying a separator — would
+// let a restore read (or a create write) outside that directory. Ids are
+// therefore restricted to one `[A-Za-z0-9]`-led filename component, and the
+// drive/UNC spellings are rejected explicitly on top of the whitelist
+// (`SEC-02` / `P-01`).
+const CHECKPOINT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function assertSafeCheckpointId(id) {
+  if (
+    typeof id !== "string" ||
+    id.length === 0 ||
+    isWindowsAbsolutePath(id) ||
+    !CHECKPOINT_ID_RE.test(id)
+  ) {
+    throw new CheckpointError(
+      `Invalid checkpoint session id '${id}': expected a plain filename (letters, digits, '.', '_', '-') without path separators.`
+    );
+  }
+  return id;
+}
+
 /**
  * Ensures checkpoint storage directory exists.
  */
@@ -29,6 +52,7 @@ export function getCheckpointDir(root = resolveRoot()) {
  * @returns {object} Checkpoint metadata
  */
 export function createCheckpoint(sessionId = `session-${Date.now()}`, options = {}) {
+  const safeId = assertSafeCheckpointId(sessionId);
   const root = options.root || resolveRoot();
   const dir = getCheckpointDir(root);
 
@@ -47,7 +71,7 @@ export function createCheckpoint(sessionId = `session-${Date.now()}`, options =
 
   const snapshot = {
     version: 1,
-    id: sessionId,
+    id: safeId,
     timestamp: new Date().toISOString(),
     headSha,
     branch,
@@ -55,7 +79,7 @@ export function createCheckpoint(sessionId = `session-${Date.now()}`, options =
     diffContent,
   };
 
-  const snapshotPath = join(dir, `${sessionId}.json`);
+  const snapshotPath = join(dir, `${safeId}.json`);
   writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
 
   // Keep last 10 checkpoints
@@ -83,6 +107,10 @@ export function restoreCheckpoint(sessionId = "--latest", options = {}) {
     targetId = list[0].id;
   }
 
+  // A caller-supplied id becomes a filename here; reject anything that is not
+  // a plain filename before `join` can turn it into a path escape (`P-01`).
+  targetId = assertSafeCheckpointId(targetId);
+
   const snapshotFile = join(dir, `${targetId}.json`);
   if (!existsSync(snapshotFile)) {
     throw new CheckpointError(`Checkpoint snapshot file not found for session '${targetId}'.`);

package/src/perf.mjs

@@ -0,0 +1,92 @@
+import { monitorEventLoopDelay } from "node:perf_hooks";
+import { execSync } from "node:child_process";
+import { resolveVerify } from "./config.mjs";
+
+/**
+ * Measures Node.js Event Loop delay during test execution or asynchronous workloads
+ * to detect synchronous blocking, catastrophic regex backtracking, or O(n^2) starvation.
+ *
+ * @param {string|Function} target - Command line string to execute or async/sync function
+ * @param {object} [options]
+ * @param {string} [options.root=process.cwd()] - Working directory
+ * @param {number} [options.maxDelayMs=50] - Maximum allowable p99/max event loop delay in milliseconds
+ * @param {number} [options.resolution=10] - Sampling resolution in milliseconds (default: 10)
+ * @param {number} [options.timeoutMs=60000] - Process timeout in milliseconds
+ * @returns {object} { ok, maxMs, meanMs, p50Ms, p90Ms, p99Ms, minMs, thresholdMs, summary, stdout, stderr, exitCode }
+ */
+export function measureEventLoopDelay(target, options = {}) {
+  const root = options.root || process.cwd();
+  const maxDelayMs = typeof options.maxDelayMs === "number" ? options.maxDelayMs : 50;
+  const resolution = options.resolution || 10;
+  const timeoutMs = options.timeoutMs || 60000;
+
+  const histogram = monitorEventLoopDelay({ resolution });
+  histogram.enable();
+
+  let exitCode = 0;
+  let stdout = "";
+  let stderr = "";
+
+  const startTime = Date.now();
+
+  try {
+    if (typeof target === "function") {
+      target();
+    } else {
+      const cmd = target || resolveVerify(root).testCmd || "npm test";
+      const env = { ...process.env };
+      for (const k of Object.keys(env)) {
+        if (k.startsWith("NODE_TEST_") || k.startsWith("NODE_CHANNEL_")) {
+          delete env[k];
+        }
+      }
+
+      try {
+        stdout = execSync(cmd, {
+          cwd: root,
+          env,
+          timeout: timeoutMs,
+          stdio: ["ignore", "pipe", "pipe"],
+          encoding: "utf-8",
+        });
+      } catch (err) {
+        exitCode = err.status || 1;
+        stdout = err.stdout ? String(err.stdout) : "";
+        stderr = err.stderr ? String(err.stderr) : err.message;
+      }
+    }
+  } finally {
+    histogram.disable();
+  }
+
+  const durationMs = Date.now() - startTime;
+
+  // Convert nanoseconds to milliseconds
+  const minMs = Math.round((histogram.min / 1e6) * 100) / 100;
+  const maxMs = Math.round((histogram.max / 1e6) * 100) / 100;
+  const meanMs = Number.isFinite(histogram.mean) ? Math.round((histogram.mean / 1e6) * 100) / 100 : 0;
+  const p50Ms = Math.round((histogram.percentile(50) / 1e6) * 100) / 100;
+  const p90Ms = Math.round((histogram.percentile(90) / 1e6) * 100) / 100;
+  const p99Ms = Math.round((histogram.percentile(99) / 1e6) * 100) / 100;
+
+  // If p99 or max exceeds threshold, mark as lag violation
+  const ok = exitCode === 0 && (p99Ms <= maxDelayMs || maxMs <= maxDelayMs);
+
+  const summary = `Event Loop Delay: p99=${p99Ms}ms, max=${maxMs}ms, mean=${meanMs}ms (threshold: ${maxDelayMs}ms, duration: ${durationMs}ms)`;
+
+  return {
+    ok,
+    minMs,
+    maxMs,
+    meanMs,
+    p50Ms,
+    p90Ms,
+    p99Ms,
+    thresholdMs: maxDelayMs,
+    durationMs,
+    exitCode,
+    stdout,
+    stderr,
+    summary,
+  };
+}

package/src/provider.mjs

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join, extname } from "node:path";
 import { redactSecrets } from "./security.mjs";
+import { resolveWindowsSpawn } from "./git.mjs";
 
 // Extensions node --check can parse as a script. .mjs/.cjs are unambiguous;
 // plain .js is checked as a script too — a stray top-level ESM import would
@@ -509,10 +510,18 @@ export function createProvider(spec = "jules", config = {}) {
 
         const processedArgs = filteredArgs.map((arg) => interpolateString(arg, data));
 
-        const res = spawnSync(command, processedArgs, {
+        // `claude`, `gemini` and `codex` are npm-installed CLI binaries, which on
+        // Windows are `.cmd` shims that `spawnSync(..., { shell: false })` cannot
+        // start (CreateProcess cannot run a batch file). Route them through
+        // cmd.exe with per-argument quoting instead (P-08); on other platforms
+        // this is a null and the command spawns directly as before.
+        const winSpawn = resolveWindowsSpawn(command, processedArgs, process.env);
+
+        const res = spawnSync(winSpawn ? winSpawn.file : command, winSpawn ? winSpawn.args : processedArgs, {
           cwd: config._root || process.cwd(),
           encoding: "utf-8",
           shell: false,
+          windowsVerbatimArguments: Boolean(winSpawn && winSpawn.verbatim),
           input: providerSpec.promptViaStdin ? data.prompt : undefined,
           timeout: providerSpec.timeoutMs || 900000,
           maxBuffer: 32 * 1024 * 1024,

package/src/remediation.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
-import { randomUUID } from "node:crypto";
+import { randomUUID, createHash } from "node:crypto";
 import { getStateDir, ensureDir } from "./state.mjs";
 import { redactSecrets } from "./security.mjs";
 
@@ -162,3 +162,156 @@ export function hydrateMemory(root, options = {}) {
   return `[LEARNED_REMEDIATIONS_CONTEXT]\nThe following historical failure-and-fix patterns were harvested from previous OODA runs in this repository. Avoid repeating these failure modes:\n\n${items.join("\n\n")}`;
 }
 
+/**
+ * Creates an OODA Thrash Cycle Breaker.
+ * Tracks rolling SHA-256 fingerprints of diff hunks and failure states in repair loops.
+ * Trips circuit breaker if an identical patch or failure ping-pong cycle is observed.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.maxHistory=10] - Maximum states to retain in ring buffer
+ * @param {number} [opts.threshold=2] - Number of occurrences before tripping (default: 2 -> A -> B -> A)
+ * @returns {{ recordAttempt: (state: { diff?: string, symptom?: string, targetFiles?: string[] }) => { thrash: boolean, cycleLength?: number, fingerprint: string, occurrences: number, reason?: string }, getHistory: () => string[], reset: () => void }}
+ */
+export function createThrashDetector(opts = {}) {
+  const maxHistory = opts.maxHistory || 10;
+  const threshold = opts.threshold || 2;
+  const history = [];
+
+  function computeStateFingerprint(state = {}) {
+    const normDiff = (state.diff || "").trim();
+    const normSymptom = (state.symptom || "").trim();
+    const normFiles = (state.targetFiles || []).slice().sort().join(",");
+    return createHash("sha256")
+      .update(`${normDiff}:::${normSymptom}:::${normFiles}`)
+      .digest("hex");
+  }
+
+  function recordAttempt(state = {}) {
+    const fingerprint = computeStateFingerprint(state);
+    history.push(fingerprint);
+    if (history.length > maxHistory) {
+      history.shift();
+    }
+
+    // Check for duplicate occurrences in history
+    const occurrences = history.filter((h) => h === fingerprint).length;
+    if (occurrences >= threshold) {
+      const firstIdx = history.indexOf(fingerprint);
+      const lastIdx = history.lastIndexOf(fingerprint);
+      const cycleLength = lastIdx - firstIdx;
+
+      return {
+        thrash: true,
+        cycleLength,
+        fingerprint,
+        occurrences,
+        reason: `OODA Thrash Circuit Tripped: State fingerprint ${fingerprint.slice(0, 12)} repeated ${occurrences} times across repair loop (cycle length: ${cycleLength}).`,
+      };
+    }
+
+    return {
+      thrash: false,
+      fingerprint,
+      occurrences,
+    };
+  }
+
+  return {
+    recordAttempt,
+    getHistory: () => [...history],
+    reset: () => {
+      history.length = 0;
+    },
+  };
+}
+
+/**
+ * Creates a Whack-a-Mole Test-Oscillation Detector for OODA repair loops.
+ * Detects when consecutive repair turns oscillate between different failing test sets
+ * (e.g. fixing Test A causes Test B to break, then fixing Test B re-breaks Test A).
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.maxHistory=8] - Maximum test state signatures to retain
+ * @param {number} [opts.threshold=2] - Number of repeating occurrences before triggering
+ * @returns {{ recordTestOutcome: (failingTests: string[] | string) => { whackAMole: boolean, cycleLength?: number, oscillatingTests?: string[], occurrences: number, promptDirective?: string, reason?: string }, getHistory: () => string[], reset: () => void }}
+ */
+export function createWhackAMoleDetector(opts = {}) {
+  const maxHistory = opts.maxHistory || 8;
+  const threshold = opts.threshold || 2;
+  const history = []; // Array of signature strings
+  const testSets = []; // Array of string[]
+
+  function normalizeTestSet(input) {
+    if (!input) return [];
+    if (Array.isArray(input)) {
+      return [...new Set(input.map((s) => String(s).trim()).filter(Boolean))].sort();
+    }
+    const str = String(input).trim();
+    return str ? [str] : [];
+  }
+
+  function recordTestOutcome(failingInput) {
+    const tests = normalizeTestSet(failingInput);
+    const signature = tests.join("||") || "__ALL_PASS__";
+
+    history.push(signature);
+    testSets.push(tests);
+
+    if (history.length > maxHistory) {
+      history.shift();
+      testSets.shift();
+    }
+
+    if (signature === "__ALL_PASS__") {
+      return {
+        whackAMole: false,
+        occurrences: 0,
+      };
+    }
+
+    const occurrences = history.filter((h) => h === signature).length;
+    if (occurrences >= threshold) {
+      const firstIdx = history.indexOf(signature);
+      const lastIdx = history.lastIndexOf(signature);
+      const cycleLength = lastIdx - firstIdx;
+
+      // Extract all distinct failing tests observed in the cycle window
+      const cycleTests = new Set();
+      for (let i = firstIdx; i <= lastIdx; i++) {
+        for (const t of testSets[i]) {
+          cycleTests.add(t);
+        }
+      }
+      const oscillatingTests = [...cycleTests];
+
+      const testSummary = oscillatingTests.length > 0 ? oscillatingTests.join(" <-> ") : "tests";
+      const promptDirective = `[WHACK_A_MOLE_WARNING] You are trapped in a local optimization cycle where fixing one test breaks another (${testSummary}). Do not add more conditional edge-case band-aids. Revert recent patches and refactor the core logic cleanly.`;
+
+      return {
+        whackAMole: true,
+        cycleLength,
+        oscillatingTests,
+        occurrences,
+        promptDirective,
+        reason: `Whack-a-Mole Test Oscillation Detected: Test failure signature repeated across repair turns (${testSummary}).`,
+      };
+    }
+
+    return {
+      whackAMole: false,
+      occurrences,
+    };
+  }
+
+  return {
+    recordTestOutcome,
+    getHistory: () => [...history],
+    reset: () => {
+      history.length = 0;
+      testSets.length = 0;
+    },
+  };
+}
+
+
+

package/src/rules-budget.mjs

@@ -45,8 +45,14 @@ export function checkRulesBudget(root = process.cwd(), opts = {}) {
 
     try {
       const content = readFileSync(fullPath, "utf-8");
-      const charCount = content.length;
-      const lineCount = content.split("\n").length;
+      // A CRLF checkout inflates the character count by one `\r` per line, so
+      // the identical rules file passes as LF and fails as CRLF — a false
+      // budget violation that depends purely on git's autocrlf setting rather
+      // than the content. Normalise line endings before measuring (P-12) so the
+      // budget counts the rule text, not the line-ending dialect.
+      const normalized = content.replace(/\r\n/g, "\n");
+      const charCount = normalized.length;
+      const lineCount = normalized.split("\n").length;
 
       if (charCount > maxChars) {
         violations.push({

package/src/scaffold.mjs

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { detectPolyglotStack, detectEdgeRuntime } from "./stack-detector.mjs";
 
 const KIT_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -77,6 +78,136 @@ function copyDir(srcDir, destDir, force) {
   return written;
 }
 
+/**
+ * Generate stack-tailored contract templates (SPEC.md, CONSTRAINTS.md, DESIGN.md).
+ *
+ * @param {string} root - Project root
+ * @param {{ force?: boolean }} [options]
+ * @returns {string[]} Created contract file names
+ */
+export function scaffoldContracts(root = process.cwd(), options = {}) {
+  const force = Boolean(options.force);
+  const created = [];
+
+  const specPath = join(root, "SPEC.md");
+  if (!existsSync(specPath) || force) {
+    const specContent = `# SPEC — System & Product Contract
+
+## Product
+- Brief 1–2 sentence description of the system and target users.
+
+## Core Loop
+- Step-by-step lifecycle from input/event to final response/artifact.
+
+## Goals
+- [Goal 1: Core invariant functionality that MUST work]
+- [Goal 2: Performance, throughput, or latency targets]
+- [Goal 3: Test coverage & reliability criteria]
+
+## Non-Goals
+- [Explicit out-of-scope feature or abstraction]
+- [Out-of-scope third-party dependencies or integrations]
+
+## Definition of Done
+- All verification test suites pass cleanly with 0 errors
+- Zero security vulnerabilities and zero leaked secrets
+- Diff size stays within the configured limit (<= 75 KB)
+`;
+    writeFileSync(specPath, specContent, "utf-8");
+    created.push("SPEC.md");
+  }
+
+  const constraintsPath = join(root, "CONSTRAINTS.md");
+  if (!existsSync(constraintsPath) || force) {
+    const edgeInfo = detectEdgeRuntime(root);
+    const stackInfo = detectPolyglotStack(root);
+
+    let constraintsContent = "";
+    if (edgeInfo.edgePlatform === "cloudflare") {
+      constraintsContent = `# CONSTRAINTS — Cloudflare Workers / workerd
+
+## Runtime Invariants
+- Zero unbundled \`node:*\` imports in \`src/\` (rely on standard Web APIs or polyfilled modules)
+- Bundle size: Max 10 MB total
+- RAM memory limit: 128 MB
+- Database & KV: Batch operations via \`db.batch([])\`, zero unbounded query loops
+- Static content: Zero client-side JavaScript for static content
+`;
+    } else if (stackInfo.stack === "cargo") {
+      constraintsContent = `# CONSTRAINTS — Rust Architecture
+
+## Runtime & Safety Invariants
+- Zero \`unsafe\` blocks unless explicitly audited and documented
+- No unhandled \`.unwrap()\` or \`.expect()\` in production/request-handling code paths
+- Clippy compliance: \`cargo clippy -- -D warnings\` must pass with 0 warnings
+- Strict error propagation using \`Result<T, E>\` / \`thiserror\` / \`anyhow\`
+`;
+    } else if (stackInfo.stack === "go") {
+      constraintsContent = `# CONSTRAINTS — Go Architecture
+
+## Runtime & Safety Invariants
+- Deterministic builds: \`CGO_ENABLED=0\`
+- Explicit error handling: Never discard \`err\` returns (\`_ = err\` is strictly prohibited)
+- Data race free: \`go test -race ./...\` must pass with 0 failures
+- Strict struct tagging and deterministic serialization
+`;
+    } else if (["python", "poetry", "uv", "pipenv"].includes(stackInfo.stack)) {
+      constraintsContent = `# CONSTRAINTS — Python Architecture
+
+## Runtime & Safety Invariants
+- Strict type annotations on all function signatures (\`mypy --strict\` passes)
+- Zero unpinned dependencies in production manifests
+- Lint & format cleanly with \`ruff\` or \`flake8\`/\`black\`
+- Pytest suite passes 100% cleanly
+`;
+    } else {
+      constraintsContent = `# CONSTRAINTS — Technical Invariants
+
+## Architecture & Code Quality
+- Zero third-party runtime dependencies in core orchestration/shared packages
+- Diff Payload Budget: Keep diffs under 75 KB to prevent truncation
+- Strict Test Lock: Never weaken assertions or delete failing tests to force green status
+- Cross-Platform: Normalize all filesystem paths to POSIX slashes (\`/\`)
+`;
+    }
+
+    writeFileSync(constraintsPath, constraintsContent, "utf-8");
+    created.push("CONSTRAINTS.md");
+  }
+
+  // If web/UI stack is detected (Astro, Next, Svelte, Vue, React, Tailwind), scaffold DESIGN.md
+  const isWeb = existsSync(join(root, "astro.config.mjs")) ||
+    existsSync(join(root, "next.config.js")) ||
+    existsSync(join(root, "next.config.mjs")) ||
+    existsSync(join(root, "svelte.config.js")) ||
+    existsSync(join(root, "tailwind.config.js")) ||
+    existsSync(join(root, "tailwind.config.mjs")) ||
+    existsSync(join(root, "tailwind.config.ts"));
+
+  const designPath = join(root, "DESIGN.md");
+  if (isWeb && (!existsSync(designPath) || force)) {
+    const designContent = `# DESIGN — Visual Tokens & Design System
+
+## Typography
+- Headings: Clean sans-serif / geometric font
+- Body: Readable system font / sans-serif
+
+## Tokens (@theme)
+- Consistent spacing scale (4px, 8px, 16px, 24px, 32px, 48px)
+- Strict color tokens for surfaces, text, and borders
+
+## Hard UI Rules
+- Zero client-side JS for purely static content
+- Accessible contrast ratios (WCAG AA minimum 4.5:1)
+- Explicit hover, focus-visible, and active states on all interactive elements
+`;
+    writeFileSync(designPath, designContent, "utf-8");
+    created.push("DESIGN.md");
+  }
+
+  return created;
+}
+
 /**
  * Scaffold the repository assets the CLI's documented features depend on.
  *
@@ -90,7 +221,7 @@ function copyDir(srcDir, destDir, force) {
  * routine way to pick up new presets and must not overwrite local edits.
  *
  * @param {string} [root=process.cwd()]
- * @param {{ force?: boolean }} [options]
+ * @param {{ force?: boolean, contracts?: boolean }} [options]
  * @returns {{ created: string[], gitignore: string[] }}
  */
 export function scaffoldRepoAssets(root = process.cwd(), options = {}) {
@@ -119,7 +250,7 @@ export function scaffoldRepoAssets(root = process.cwd(), options = {}) {
   }
 
   if (copyDir(join(KIT_ROOT, ".agent/prompts"), join(agentDir, "prompts"), force) > 0) {
-    created.push(".agent/prompts/ (Overseer, Bolt, Sentinel, Janitor)");
+    created.push(".agent/prompts/ (Overseer, Bolt, Sentinel, Janitor, A11y, Scribe, Spectator, Alchemist)");
   }
   if (copyDir(join(KIT_ROOT, ".agent/rules"), join(agentDir, "rules"), force) > 0) {
     created.push(".agent/rules/");
@@ -128,6 +259,12 @@ export function scaffoldRepoAssets(root = process.cwd(), options = {}) {
     created.push(".agent/workflows/");
   }
 
+  // Scaffold contract documents (SPEC.md, CONSTRAINTS.md, DESIGN.md)
+  if (options.contracts !== false) {
+    const contracts = scaffoldContracts(root, options);
+    created.push(...contracts);
+  }
+
   // isTaskFile() skips README.md, so the queue can carry its own explanation
   // without the runner mistaking it for a task envelope.
   const queueReadme = join(queueDir, "README.md");