jules-orchestrator-kit 0.72.2 → 0.73.0

package/scripts/jules-self-audit.mjs

@@ -1,148 +1,17 @@
 #!/usr/bin/env node
 
 /**
- * Self-audit gatekeeper: runs 4-phase safety gate against working tree or base branch.
+ * Self-audit CLI entrypoint.
+ *
+ * All audit logic lives in src/self-audit.mjs (P04 shim cleanup); this file
+ * is only the executable gate that CI (`jules-audit.yml`) invokes. The
+ * re-export below preserves the historical `scripts/jules-self-audit.mjs`
+ * import surface for external consumers.
  */
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+export * from "../src/self-audit.mjs";
 
-let gate, loadConfig, parseYaml, matchesGlob;
-try {
-  ({ gate } = await import("../src/engine.mjs"));
-  ({ loadConfig, parseYaml } = await import("../src/config.mjs"));
-  ({ matchesGlob } = await import("../src/security.mjs"));
-} catch (_) {
-  try {
-    ({ gate, loadConfig, parseYaml, matchesGlob } = await import("jules-orchestrator-kit"));
-  } catch (err) {
-    console.error("Error: Could not resolve jules-orchestrator-kit modules.", err.message);
-    process.exit(1);
-  }
-}
-
-export function matchGlob(filepath, globPattern) {
-  return matchesGlob(filepath, globPattern);
-}
-
-export const EXECUTION_CONFIG_FILES = ["package.json", "tsconfig.json", "Cargo.toml", "go.mod", "pyproject.toml", "vite.config.ts", "jest.config.js", ".npmrc"];
-export const RESTRICTED_AGENT_FILES = ["AGENTS.md", "JULES_RULES_TEMPLATE.md"];
-export const COMMAND_DEFINING_FILES = ["package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".agent/jules.yml", ".agent/config.yml"];
-
-export function loadForbiddenPatterns(configContent = "") {
-  const defaults = ["scripts/jules-*", ".agent/jules.yml", ".github/**", "**/*.pem"];
-  if (!configContent) return defaults;
-  const parsed = parseYaml(configContent);
-  const userPaths = Array.isArray(parsed.forbidden_paths) ? parsed.forbidden_paths : [];
-  return Array.from(new Set([...defaults, ...userPaths]));
-}
-
-export function loadAllowedPatterns(configContent = "") {
-  if (!configContent) return [];
-  const parsed = parseYaml(configContent);
-  return Array.isArray(parsed.allow_paths) ? parsed.allow_paths : [];
-}
-
-export function validateJulesConfig(_configContent = "", jsonGuardrailsContent = "") {
-  const errors = [];
-  if (jsonGuardrailsContent) {
-    try {
-      const parsed = JSON.parse(jsonGuardrailsContent);
-      if (Array.isArray(parsed.rules)) {
-        for (const rule of parsed.rules) {
-          try {
-            new RegExp(rule.trigger, "i");
-          } catch (err) {
-            errors.push(`Invalid RegExp trigger: ${err.message}`);
-          }
-        }
-      }
-    } catch (err) {
-      errors.push(`JSON Parse Error: ${err.message}`);
-    }
-  }
-  return { ok: errors.length === 0, errors };
-}
-
-export function parseAndCleanStderr(str = "") {
-  if (typeof str !== "string") return "";
-  return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "").replace(/\u001b\[[0-9;]*m/g, "");
-}
-
-export function getOodaStateFile(mergeBase = "main") {
-  return `.agent/state/ooda-${mergeBase}.json`;
-}
-
-export function logAuditMetrics() {}
-
-/**
- * Audit ledger states and verify integrity of ledger/state files.
- */
-export function auditLedgers(opts = {}) {
-  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
-  const stateDir = join(root, ".agent", "state");
-  const exists = existsSync(stateDir);
-  return { ok: true, stateDir, exists };
-}
-
-/**
- * Audit git worktrees and active workspace boundaries.
- */
-export function auditWorktrees(opts = {}) {
-  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
-  const worktreeDir = join(root, ".agent", "worktrees");
-  const exists = existsSync(worktreeDir);
-  return { ok: true, worktreeDir, exists };
-}
-
-/**
- * Audit gate rules (scope, payload governor, secret scanning, verification suite).
- */
-export async function auditGates(opts = {}) {
-  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
-  const config = opts.config || loadConfig(root);
-  const base = opts.base || process.env.BASE_BRANCH || config.baseBranch || "main";
-
-  return await gate({
-    root,
-    config,
-    base,
-    fix: process.env.ALLOW_AUTO_REPAIR === "true",
-    allowProtected: process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "true",
-  });
-}
-
-/**
- * Main self-audit entrypoint executing validation passes.
- */
-export async function runSelfAudit(opts = {}) {
-  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
-  const config = loadConfig(root);
-  const base = opts.base || process.env.BASE_BRANCH || config.baseBranch || "main";
-
-  const optsWithContext = { ...opts, root, config, base };
-
-  const ledgersResult = auditLedgers(optsWithContext);
-  const worktreesResult = auditWorktrees(optsWithContext);
-  const gatesResult = await auditGates(optsWithContext);
-
-  if (!gatesResult.ok) {
-    return gatesResult;
-  }
-
-  return {
-    ...gatesResult,
-    audits: {
-      ledgers: ledgersResult,
-      worktrees: worktreesResult,
-      gates: gatesResult,
-    },
-  };
-}
-
-export async function runPreflightSandbox() {
-  return { ok: true };
-}
+import { runSelfAudit } from "../src/self-audit.mjs";
 
 if (process.argv[1] && process.argv[1].endsWith("jules-self-audit.mjs")) {
   runSelfAudit()

package/scripts/jules-status.mjs

@@ -2,50 +2,44 @@
 
 /**
  * Session status and budget status summarizer.
+ *
+ * categorizeTaskStatus moved to src/session-ops.mjs (P04 shim cleanup) and is
+ * re-exported here for historical importers; the CLI body now runs only under
+ * the entry guard, so importing this script no longer executes side effects.
  */
 
+export { categorizeTaskStatus } from "../src/session-ops.mjs";
+
 import { checkDailyBudget } from "../src/state.mjs";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-export function categorizeTaskStatus(statusStr = "") {
-  const s = String(statusStr).toUpperCase();
-  if (s === "AWAITING_PLAN_APPROVAL" || s === "AWAITING_USER_FEEDBACK") {
-    return "action_required";
-  }
-  if (s === "IN_PROGRESS" || s === "DISPATCHED") {
-    return "in_progress";
-  }
-  if (s === "COMPLETED" || s === "FAILED") {
-    return "completed";
-  }
-  return "unknown";
-}
+if (process.argv[1] && process.argv[1].endsWith("jules-status.mjs")) {
+  const isJson = process.argv.includes("--json");
+  const root = process.env.JULES_PROJECT_ROOT || process.cwd();
+  const budget = checkDailyBudget(root);
 
-const isJson = process.argv.includes("--json");
-const root = process.env.JULES_PROJECT_ROOT || process.cwd();
-const budget = checkDailyBudget(root);
-
-let queueItems = [];
-const queueFile = join(root, ".agent/jules-queue/queue.jsonl");
-if (existsSync(queueFile)) {
-  try {
-    const raw = readFileSync(queueFile, "utf-8");
-    queueItems = raw
-      .split("\n")
-      .filter(Boolean)
-      .map((line) => {
-        const parsed = JSON.parse(line);
-        return {
-          ...parsed,
-          Status: parsed.Status || parsed.status || "PENDING",
-        };
-      });
-  } catch (_) {}
-}
+  let queueItems = [];
+  const queueFile = join(root, ".agent/jules-queue/queue.jsonl");
+  if (existsSync(queueFile)) {
+    try {
+      const raw = readFileSync(queueFile, "utf-8");
+      queueItems = raw
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+          const parsed = JSON.parse(line);
+          return {
+            ...parsed,
+            Status: parsed.Status || parsed.status || "PENDING",
+          };
+        });
+    } catch (_) {}
+  }
 
-if (isJson) {
-  console.log(JSON.stringify({ queue: queueItems, sessions: [], budget }));
-} else {
-  console.log(`[Shim] Status: Daily Budget ${budget.used}/${budget.budget} used.`);
+  if (isJson) {
+    console.log(JSON.stringify({ queue: queueItems, sessions: [], budget }));
+  } else {
+    console.log(`[Shim] Status: Daily Budget ${budget.used}/${budget.budget} used.`);
+  }
 }

package/scripts/jules-webhook-receiver.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { createWebhookServer } from "../src/webhook.mjs";
-import { loadEnv, log, timestamp } from "./utils.mjs";
+import { loadEnv, log, timestamp } from "../src/runtime-env.mjs";
 import { spawn } from "node:child_process";
 import { resolveRoot } from "../src/config.mjs";
 

package/src/assertions.mjs

@@ -4,7 +4,7 @@ import { gzipSync } from "node:zlib";
 import { checkAssetIntegrity } from "./asset-integrity.mjs";
 import { checkRulesBudget } from "./rules-budget.mjs";
 import { runMutationTest } from "./mutation.mjs";
-import { checkTestTampering } from "./security.mjs";
+import { checkTestTampering, matchesGlob } from "./security.mjs";
 import { runV8Coverage, calculateDiffCoverage } from "./coverage.mjs";
 import { runStabilityProbe } from "./stability.mjs";
 import { measureEventLoopDelay } from "./perf.mjs";
@@ -54,56 +54,11 @@ export function resolveBytesLimit(opts = {}) {
 }
 
 /**
- * Simple zero-dependency glob/pattern matcher supporting * and **.
- * @param {string} pathStr
- * @param {string} pattern
- * @returns {boolean}
+ * Glob matching is delegated to the single linear-time matcher in
+ * src/security.mjs (segment DP; no regex, so no catastrophic backtracking).
+ * Re-exported so `./assertions.mjs` callers keep the same entry point.
  */
-export function matchesGlob(pathStr, pattern) {
-  if (!pattern || pattern === "*") return true;
-  const normalizedPath = normalizePosix(pathStr).replace(/^\.\//, "");
-  const normalizedPattern = normalizePosix(pattern).replace(/^\.\//, "");
-
-  if (normalizedPath === normalizedPattern) return true;
-
-  // Convert simple glob pattern to RegExp
-  let regexStr = "^";
-  let i = 0;
-  while (i < normalizedPattern.length) {
-    const c = normalizedPattern[i];
-    if (c === "*" && normalizedPattern[i + 1] === "*") {
-      if (normalizedPattern[i + 2] === "/") {
-        regexStr += "(?:.*/)?";
-        i += 3;
-        continue;
-      } else {
-        regexStr += ".*";
-        i += 2;
-        continue;
-      }
-    } else if (c === "*") {
-      regexStr += "[^/]*";
-      i++;
-    } else if (c === "?") {
-      regexStr += "[^/]";
-      i++;
-    } else if (["\\", ".", "+", "^", "$", "{", "}", "(", ")", "|", "[", "]"].includes(c)) {
-      regexStr += "\\" + c;
-      i++;
-    } else {
-      regexStr += c;
-      i++;
-    }
-  }
-  regexStr += "$";
-
-  try {
-    const re = new RegExp(regexStr);
-    return re.test(normalizedPath);
-  } catch (_) {
-    return normalizedPath.includes(normalizedPattern);
-  }
-}
+export { matchesGlob };
 
 /**
  * Asserts total byte size of a directory.

package/src/bidi-guard.mjs

@@ -0,0 +1,36 @@
+/**
+ * Trojan Source (CVE-2021-42574) BiDi override detection.
+ *
+ * Split out of src/security.mjs (P05). A Unicode directional override can make
+ * the line an agent reads differ from the line the parser executes, so the
+ * check runs on every added line of every non-markdown file before anything
+ * else looks at the diff.
+ */
+
+export function checkTrojanSource(diffOrText = "", _options = {}) {
+  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+
+  const violations = [];
+  const bidiRegex = /[\u202A\u202B\u202C\u202D\u202E\u2066\u2067\u2068\u2069\u061C\u200E\u200F]/;
+
+  const lines = diffOrText.split("\n");
+  // Only filter diff syntax if we actually start with typical diff headers
+  // This avoids treating text containing "+++ b/" as a diff mistakenly.
+  const isDiff = diffOrText.startsWith("--- a/") || diffOrText.startsWith("+++ b/") || diffOrText.includes("\n+++ b/");
+
+  const targetLines = lines.filter((line) => {
+    if (isDiff) {
+      return line.startsWith("+") && !line.startsWith("+++");
+    }
+    return true;
+  });
+
+  for (const line of targetLines) {
+    if (bidiRegex.test(line)) {
+      violations.push({ reason: "Trojan Source BiDi override detected: contains invisible directional control characters (CVE-2021-42574)." });
+      break; // One violation is enough for the file/diff block
+    }
+  }
+
+  return { ok: violations.length === 0, violations };
+}

package/src/budget.mjs

@@ -1,8 +1,9 @@
-import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { execSync } from "node:child_process";
 import { userInfo } from "node:os";
 import { resolveRoot } from "./config.mjs";
+import { safeAtomicWrite } from "./security.mjs";
 import {
   getStateDir,
   ensureDir,
@@ -101,18 +102,6 @@ export function isDailyQuotaRejection(err) {
   return DAILY_QUOTA_HINT.test(text);
 }
 
-function writeAtomic(filePath, content) {
-  const tmpPath = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-  const fd = openSync(tmpPath, "w");
-  try {
-    writeFileSync(fd, content, "utf-8");
-    fsyncSync(fd);
-  } finally {
-    closeSync(fd);
-  }
-  renameSync(tmpPath, filePath);
-}
-
 /**
  * Read the stored ceiling, whenever it was observed.
  *
@@ -190,7 +179,7 @@ export function recordObservedCeiling(usedAtRejection, root = resolveRoot(), met
     observedAt: new Date().toISOString(),
     source: meta.source || "provider-rejection",
   };
-  writeAtomic(join(stateDir, CEILING_FILE), JSON.stringify(record, null, 2) + "\n");
+  safeAtomicWrite(join(stateDir, CEILING_FILE), JSON.stringify(record, null, 2) + "\n");
 
   // Mirrored into the hash-chained ledger so the change is auditable; the JSON
   // file above is only a cheap index that survives ledger rotation.

package/src/config.mjs

@@ -1001,12 +1001,8 @@ export function resolveTrustedPolicy(root = process.cwd(), baseRef = null, mode
   // 1. Resolve base branch
   let base = baseRef || opts.base;
   if (!base) {
-    if (mode === "committed") {
-      base = detectDefaultBranch(root) || "main";
-    } else {
-      const diskConfig = opts.config || (existsSync(join(root, ".agent/config.yml")) ? loadConfig(root) : null);
-      base = diskConfig?.baseBranch || detectDefaultBranch(root) || "main";
-    }
+    const diskConfig = opts.config || (existsSync(join(root, ".agent/config.yml")) ? loadConfig(root) : null);
+    base = diskConfig?.baseBranch || detectDefaultBranch(root) || "main";
   }
 
   // F08 Guard: In committed mode, base branch can never be HEAD

package/src/dashboard.mjs

@@ -4,16 +4,11 @@
  */
 
 import http from "node:http";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { join, dirname } from "node:path";
 import { readTelemetry, verifyTelemetryIntegrity } from "./telemetry.mjs";
 import { readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
 import { lockStatus } from "./state.mjs";
 import { KIT_VERSION } from "./version.mjs";
 
-const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")).version;
-
 export function getDashboardHtml(root = process.cwd()) {
   return `<!DOCTYPE html>
 <html lang="en">
@@ -38,7 +33,7 @@ export function getDashboardHtml(root = process.cwd()) {
   </style>
 </head>
 <body>
-  <h1>🚀 jules-orchestrator-kit Dashboard (v${pkgVersion})</h1>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v${KIT_VERSION})</h1>
   <div class="subtitle">Repository: <code>${root}</code></div>
 
   <div class="grid">
@@ -82,8 +77,9 @@ export function getDashboardHtml(root = process.cwd()) {
 </html>`;
 }
 
-export function createDashboardServer({ root = process.cwd(), port: _port = 4100 } = {}) {
-  return http.createServer((req, res) => {
+export function createDashboardServer({ root = process.cwd(), port = 4100 } = {}) {
+  const dashboardPort = Number(port);
+  const server = http.createServer((req, res) => {
     const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
 
     if (url.pathname === "/" || url.pathname === "/index.html") {
@@ -93,7 +89,7 @@ export function createDashboardServer({ root = process.cwd(), port: _port = 4100
 
     if (url.pathname === "/api/status") {
       res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-      return res.end(JSON.stringify({ ok: true, version: KIT_VERSION, root, ts: new Date().toISOString() }));
+      return res.end(JSON.stringify({ ok: true, version: KIT_VERSION, root, port: dashboardPort, ts: new Date().toISOString() }));
     }
 
     if (url.pathname === "/api/telemetry") {
@@ -124,6 +120,8 @@ export function createDashboardServer({ root = process.cwd(), port: _port = 4100
     res.writeHead(404, { "Content-Type": "application/json; charset=utf-8" });
     res.end(JSON.stringify({ ok: false, error: "Not Found", path: url.pathname }));
   });
+  server.dashboardPort = dashboardPort;
+  return server;
 }
 
 export function startDashboardServer(port = 4100, root = process.cwd(), host = "127.0.0.1") {

package/src/dispatch.mjs

@@ -0,0 +1,212 @@
+/**
+ * Task-dispatch helpers: dynamic guardrails, multimodal attachment
+ * collection, static preflight checks, swarm slot partitioning, and the
+ * programmatic `dispatchTask` wrapper around the engine.
+ *
+ * This is the home of the logic that used to live in
+ * `scripts/jules-dispatch.mjs`; that file is now a deprecated CLI entry
+ * point. Argv parsing stays a pure function so importing this module can
+ * never consume the importer's `process.argv` (D10).
+ */
+
+import { dispatch } from "./engine.mjs";
+import { loadConfig } from "./config.mjs";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Pure argv parser for the deprecated CLI shim. It used to run at module scope,
+ * so merely importing the script consumed the importer's process.argv and baked
+ * it into dispatchTask()'s defaults. It is now called only from the CLI entry
+ * guard at the bottom of scripts/jules-dispatch.mjs.
+ *
+ * @param {string[]} [argv]
+ * @returns {{ title: string, prompt: string, dryRun: boolean, repoless: boolean }}
+ */
+export function parseDispatchArgs(argv = []) {
+  const args = Array.isArray(argv) ? argv : [];
+  let title = "Task Dispatch";
+  let prompt = "";
+  const dryRun =
+    process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1" || args.includes("--dry-run");
+  const repoless = args.includes("--repoless");
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--title" && args[i + 1]) title = args[i + 1];
+    else if (args[i] === "--prompt" && args[i + 1]) prompt = args[i + 1];
+  }
+
+  if (!prompt && args[0] && !args[0].startsWith("-")) {
+    title = args[0];
+    prompt = args[1] || args[0];
+  }
+
+  if (!prompt) {
+    prompt = "Execute task";
+  }
+
+  return { title, prompt, dryRun, repoless };
+}
+
+/**
+ * Built-in guardrail triggers, used when no project-level
+ * `.agent/rules/dynamic-guardrails.json` matches (or the file is absent).
+ *
+ * Matching is on word boundaries: the old substring checks fired on "sector"
+ * ("sec"), "breakfast" ("fast") and "keyboard" ("key"). Role labels are the
+ * canonical slugs (security, performance, hygiene, database), not the legacy
+ * RPG names.
+ */
+const BUILTIN_GUARDRAIL_TRIGGERS = [
+  { pattern: /\b(auth|sec|key|token|secret)\b/i, guardrail: "security: SECRET REDACTION GUARDRAILS" },
+  { pattern: /\b(perf|optimiz\w*|fast|cache|memoiz\w*)\b/i, guardrail: "performance: Performance Guidance" },
+  { pattern: /\b(clean|refactor|lint|deadcode)\b/i, guardrail: "hygiene: Clean Code Guidance" },
+  {
+    pattern: /\b(db|database|sql\w*|schema|drizzle|postgres\w*|sqlite\w*|mysql\w*)\b/i,
+    guardrail: "database: DATABASE GUARDRAILS",
+  },
+  { pattern: /\b(css|theme|tailwind)\b/i, guardrail: "CSS & DESIGN GUARDRAILS" },
+];
+
+/**
+ * Collects the guardrail blocks relevant to a prompt: built-in canonical-role
+ * triggers plus any project rules from
+ * `<projectRoot>/.agent/rules/dynamic-guardrails.json` (`{ rules:
+ * [{ trigger, guardrail }] }`, trigger compiled case-insensitively).
+ *
+ * @param {string} [promptText]
+ * @param {string} [projectRoot]
+ * @returns {string} Matching guardrails joined by newlines ("" when none match).
+ */
+export function getDynamicGuardrails(promptText = "", projectRoot = process.cwd()) {
+  const text = promptText || "";
+  const rules = [];
+  for (const { pattern, guardrail } of BUILTIN_GUARDRAIL_TRIGGERS) {
+    if (pattern.test(text)) rules.push(guardrail);
+  }
+  try {
+    const rulesPath = join(projectRoot || process.cwd(), ".agent", "rules", "dynamic-guardrails.json");
+    if (existsSync(rulesPath)) {
+      const parsed = JSON.parse(readFileSync(rulesPath, "utf-8"));
+      const fileRules = Array.isArray(parsed) ? parsed : parsed?.rules;
+      if (Array.isArray(fileRules)) {
+        for (const rule of fileRules) {
+          if (!rule || typeof rule.trigger !== "string" || typeof rule.guardrail !== "string") continue;
+          let trigger;
+          try {
+            trigger = new RegExp(rule.trigger, "i");
+          } catch (_) {
+            continue;
+          }
+          if (trigger.test(text)) rules.push(rule.guardrail);
+        }
+      }
+    }
+  } catch (_) {
+    // A missing or corrupt rules file must not break dispatch; the built-ins above still apply.
+  }
+  return rules.join("\n");
+}
+
+export function extractImageAttachments(promptText = "", projectRoot = process.cwd()) {
+  if (!promptText || typeof promptText !== "string") return [];
+  const regex = /!\[([^\]]*)\]\(([^)]+)\)/g;
+  const matches = [];
+  let match;
+  while ((match = regex.exec(promptText)) !== null) {
+    const relPath = match[2].trim();
+    if (relPath.includes("..")) continue;
+    const absPath = join(projectRoot, relPath);
+    if (existsSync(absPath)) {
+      let mime = "image/png";
+      if (relPath.endsWith(".jpg") || relPath.endsWith(".jpeg")) mime = "image/jpeg";
+      if (relPath.endsWith(".gif")) mime = "image/gif";
+      if (relPath.endsWith(".webp")) mime = "image/webp";
+      const size = statSync(absPath).size;
+      matches.push({ relPath, absPath, mime, size });
+    }
+  }
+  return matches;
+}
+
+export function getMultimodalAttachmentDirective(attachments = []) {
+  if (!attachments || attachments.length === 0) return "";
+  return `### Multimodal Task Attachments (${attachments.length})\n` + attachments.map((a) => `- ${a.relPath}`).join("\n");
+}
+
+/**
+ * Real pre-flight manifest check: the project must carry a parseable
+ * package.json object. Previously this returned "PASSED" unconditionally, so a
+ * missing or corrupt manifest was reported as verified.
+ *
+ * @param {string} [projectRoot]
+ * @returns {string} "PASSED", or "FAILED: <reason>".
+ */
+export function runPreflightStaticCheck(projectRoot = process.cwd()) {
+  const root = projectRoot || process.cwd();
+  const pkgPath = join(root, "package.json");
+  if (!existsSync(pkgPath)) {
+    return "FAILED: package.json not found";
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  } catch (err) {
+    return `FAILED: package.json is not valid JSON (${err.message})`;
+  }
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) {
+    return "FAILED: package.json must contain a JSON object";
+  }
+  return "PASSED";
+}
+
+/**
+ * Balanced letter partition for parallel swarm slots: the 26 letters are split
+ * into `total` contiguous ranges whose sizes differ by at most one
+ * (N=3 → A-I, J-R, S-Z). Out-of-range slots and slots past Z (total > 26) get
+ * an empty range. Totals <= 1 keep the historical "A-Z".
+ *
+ * @param {number|string} [slotIndex]
+ * @param {number|string} [totalSlots]
+ * @returns {string} e.g. "A-M", "J-R", "Z", or "".
+ */
+export function getAlphaRange(slotIndex = 0, totalSlots = 1) {
+  const total = Number(totalSlots);
+  const idx = Number(slotIndex);
+  if (!Number.isFinite(total) || total <= 1) return "A-Z";
+  if (!Number.isInteger(idx) || idx < 0 || idx >= total) return "";
+  const base = Math.floor(26 / total);
+  const extra = 26 % total;
+  const count = base + (idx < extra ? 1 : 0);
+  if (count <= 0) return "";
+  const start = idx * base + Math.min(idx, extra);
+  const end = start + count - 1;
+  const first = String.fromCharCode(65 + start);
+  const last = String.fromCharCode(65 + end);
+  return first === last ? first : `${first}-${last}`;
+}
+
+export function getSlotPartitionDirective(slotIndex = 0, totalSlots = 1) {
+  const total = Number(totalSlots);
+  const idx = Number(slotIndex);
+  if (total <= 1) return "";
+  return `[PARALLEL SWARM SLOT ${idx} of ${total}] Range: ${getAlphaRange(idx, total)} (Partition Focus)`;
+}
+
+export async function dispatchTask(opts = {}) {
+  const root = process.env.JULES_PROJECT_ROOT || process.cwd();
+  const config = loadConfig(root);
+  const isDry =
+    opts.dryRun ?? (process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1");
+  const taskTitle = opts.title || "Task Dispatch";
+  const taskPrompt = opts.prompt || "Execute task";
+
+  if (isDry) {
+    console.log(`[DRY RUN] Dispatching task: ${taskTitle}`);
+    console.log(`[DRY RUN] Dispatch payload prepared successfully`);
+    if (opts.repoless) {
+      console.log(`[DRY RUN] Target: (repoless / serverless)`);
+    }
+  }
+  return dispatch({ title: taskTitle, prompt: taskPrompt }, { config, dryRun: isDry });
+}