jules-orchestrator-kit 0.27.1 → 0.28.2

package/README.md

@@ -36,6 +36,12 @@
 
 <br/>
 
+<p align="center">
+  <img src="docs/assets/hero-flow.svg" alt="Autonomous Orchestration Pipeline" width="100%" />
+</p>
+
+<br/>
+
 ---
 
 <br/>
@@ -75,6 +81,12 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 <br/>
 
+<p align="center">
+  <img src="docs/assets/security-shield.svg" alt="Zero-Trust Security & Reliability Guarantees" width="100%" />
+</p>
+
+<br/>
+
 ---
 
 <br/>
@@ -125,6 +137,12 @@ To ensure maximum merge success, dispatch tasks according to our deterministic t
 
 <br/>
 
+<p align="center">
+  <img src="docs/assets/tier-presets.svg" alt="Subscription Tier Allocation Matrix" width="100%" />
+</p>
+
+<br/>
+
 ---
 
 <br/>
@@ -229,9 +247,23 @@ Ecosystems Natively Supported by src/stack-detector.mjs:
 
 <br/>
 
+<p align="center">
+  <img src="docs/assets/architecture-layers.svg" alt="Control Plane Architecture Layers" width="100%" />
+</p>
+
+<br/>
+
 ### 1. The Autonomous OODA Verification Loop
 Every task dispatched to `jules-orchestrator-kit` executes within an immutable, fail-closed verification loop:
 
+<br/>
+
+<p align="center">
+  <img src="docs/assets/ooda-loop-cycle.svg" alt="Self-Healing OODA Repair Loop & Thrash Breaker" width="100%" />
+</p>
+
+<br/>
+
 ```mermaid
 flowchart TD
     A["📩 Task Envelope"] --> B["1. Validate Scope & Base Freshness"]
@@ -265,6 +297,28 @@ flowchart TD
 
 <br/>
 
+### 3. Multi-Agent Parallel Swarm Topology
+Run concurrent agents across parallel worktree slots with AST/JSON 3-way merging:
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/swarm-topology.svg" alt="Multi-Agent Parallel Swarm Topology" width="100%" />
+</p>
+
+<br/>
+
+### 4. Model Context Protocol (MCP) Integration
+Native stdio server exposing task dispatch, gate verification, and risk auditing to client tools (Antigravity, Claude, Cursor):
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/mcp-integration.svg" alt="Model Context Protocol (MCP) Integration" width="100%" />
+</p>
+
+<br/>
+
 ---
 
 <br/>

package/bin/agentctl.mjs

@@ -14,12 +14,12 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.27.1 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.28.2 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
 Commands:
-  dispatch              Dispatch a single task to an AI agent
+  dispatch | create     Dispatch a single task to an AI agent
   gate | audit          Run CI security and verification gate against current branch
   queue                 Run pending task queue
   swarm                 Run parallel task swarm
@@ -31,10 +31,16 @@ Commands:
   review-repair         Parse PR review comments and synthesize OODA repair tasks
   dashboard             Start local HTTP telemetry and audit dashboard
   init                  Scaffold .agent/ directory and config.yml
+  status                Display queue and system status summary
+  scan                  Scan codebase for TODO/FIXME task candidates
   version               Output agentctl version
 
 Options:
   --dry-run, -d         Simulate action without making API calls or modifying git
+  --mode, -m            Gate evaluation mode (working-tree | committed | staged)
+  --repoless            Dispatch task in repoless execution mode
+  --source, -s          Specify Jules repository source name
+  --branch, -b          Specify target starting branch
   --json, -j            Emit machine-readable JSON output
   --help, -h            Show command help
 `);
@@ -47,7 +53,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.27.0");
+    console.log("agentctl v0.28.2");
     process.exit(0);
   }
 
@@ -57,13 +63,19 @@ async function main() {
   const config = loadConfig(root);
 
   switch (command) {
-    case "dispatch": {
+    case "dispatch":
+    case "create": {
       const { values } = parseArgs({
         args: args.slice(1),
         options: {
           title: { type: "string", short: "t" },
           prompt: { type: "string", short: "p" },
           "prompt-file": { type: "string", short: "f" },
+          source: { type: "string", short: "s" },
+          branch: { type: "string", short: "b" },
+          repoless: { type: "boolean" },
+          "auto-pr": { type: "boolean" },
+          "require-plan-approval": { type: "boolean" },
           "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
         },
@@ -87,10 +99,22 @@ async function main() {
       const task = {
         title: values.title || "CLI Dispatch Task",
         prompt: promptContent,
+        source: values.source,
+        branch: values.branch,
+        repoless: values.repoless,
+        autoPr: values["auto-pr"],
+        requirePlanApproval: values["require-plan-approval"],
       };
 
       try {
-        const session = await dispatch(task, { root, config, dryRun: values["dry-run"] });
+        const session = await dispatch(task, {
+          root,
+          config,
+          dryRun: values["dry-run"],
+          repoless: values.repoless,
+          source: values.source,
+          branch: values.branch,
+        });
         if (values.json) {
           console.log(JSON.stringify({ ok: true, session }, null, 2));
         } else {
@@ -100,12 +124,13 @@ async function main() {
         }
         process.exit(0);
       } catch (err) {
+        const exitCode = typeof err.code === "number" ? err.code : 1;
         if (values.json) {
-          console.log(JSON.stringify({ ok: false, error: err.message, code: err.code || 1 }, null, 2));
+          console.log(JSON.stringify({ ok: false, error: err.message, code: exitCode }, null, 2));
         } else {
           console.error(`❌ Dispatch Failed: ${err.message}`);
         }
-        process.exit(err.code || 1);
+        process.exit(exitCode);
       }
       break;
     }
@@ -116,6 +141,10 @@ async function main() {
         args: args.slice(1),
         options: {
           base: { type: "string", short: "b", default: config.baseBranch || "main" },
+          mode: { type: "string", short: "m", default: "working-tree" },
+          "working-tree": { type: "boolean" },
+          staged: { type: "boolean" },
+          committed: { type: "boolean" },
           fix: { type: "boolean" },
           "allow-protected": { type: "boolean" },
           json: { type: "boolean", short: "j" },
@@ -123,10 +152,16 @@ async function main() {
         allowPositionals: true,
       });
 
+      let selectedMode = values.mode || "working-tree";
+      if (values.staged) selectedMode = "staged";
+      if (values.committed) selectedMode = "committed";
+      if (values["working-tree"]) selectedMode = "working-tree";
+
       const res = await gate({
         root,
         config,
         base: values.base,
+        mode: selectedMode,
         fix: values.fix,
         allowProtected: values["allow-protected"],
       });
@@ -134,7 +169,7 @@ async function main() {
       if (values.json) {
         console.log(JSON.stringify(res, null, 2));
       } else {
-        console.log(`\n🛡️ agentctl Safety Gate Audit Results (Base: ${values.base})`);
+        console.log(`\n🛡️ agentctl Safety Gate Audit Results (Base: ${values.base}, Mode: ${selectedMode})`);
         console.log(`-----------------------------------------------------`);
         for (const p of res.phases) {
           const status = p.ok ? "✅ PASS" : "❌ FAIL";
@@ -150,14 +185,14 @@ async function main() {
         console.log(`Overall Result: ${res.ok ? "APPROVED (Exit 0)" : `REJECTED (Exit ${res.code})`}\n`);
       }
 
-      process.exit(res.code);
+      process.exit(typeof res.code === "number" ? res.code : 0);
       break;
     }
 
     case "queue": {
       const queueDir = getQueueDir(root);
       const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
-      console.log(` Found ${files.length} queued task(s) in .agent/queue/`);
+      console.log(`Found ${files.length} queued task(s) in .agent/queue/`);
       if (files.length > 0) {
         const tasks = files.map((f) => ({
           id: f,
@@ -229,7 +264,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.25.1)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.28.2)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);
@@ -315,6 +350,35 @@ base_branch: main
       break;
     }
 
+    case "status": {
+      const queueDir = getQueueDir(root);
+      const files = existsSync(queueDir) ? readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir)) : [];
+      console.log(`\n📊 agentctl Status Summary (v0.28.2)`);
+      console.log(`--------------------------------------------------`);
+      console.log(`  Project Root     : ${root}`);
+      console.log(`  Pending Tasks    : ${files.length}`);
+      console.log(`  Active VFS Locks : ${lockStatus(root).length}`);
+      const budget = checkDailyBudget(root, config.limits.dailyTasks);
+      console.log(`  Daily Budget     : ${budget.used} / ${budget.budget} used`);
+      console.log(`--------------------------------------------------\n`);
+      process.exit(0);
+      break;
+    }
+
+    case "scan": {
+      const { scanCodebaseForTodos } = await import("../scripts/jules-scan-todos.mjs");
+      const todos = scanCodebaseForTodos(root);
+      console.log(`\n🔍 Scanned ${todos.length} TODO/FIXME annotation(s).`);
+      for (const t of todos.slice(0, 10)) {
+        console.log(`   - ${t.file}:${t.line} [${t.type}] ${t.text}`);
+      }
+      if (todos.length > 10) {
+        console.log(`   ... and ${todos.length - 10} more.`);
+      }
+      process.exit(0);
+      break;
+    }
+
     case "mcp": {
       const { startMcpServer } = await import("../src/mcp.mjs");
       startMcpServer();
@@ -330,5 +394,6 @@ base_branch: main
 
 main().catch((err) => {
   console.error(`[FATAL ERROR] ${err.message}`);
-  process.exit(err.code || 1);
+  const exitCode = typeof err.code === "number" ? err.code : 1;
+  process.exit(exitCode);
 });

package/bin/init.js

@@ -221,7 +221,9 @@ let skippedCount = 0;
 
 if (fs.existsSync(sourceScriptsDir)) {
   const scriptFiles = fs.readdirSync(sourceScriptsDir);
+  const excludeFiles = new Set(["release.mjs"]);
   scriptFiles.forEach((file) => {
+    if (excludeFiles.has(file)) return;
     const srcFile = path.join(sourceScriptsDir, file);
     const destFile = path.join(targetScriptsDir, file);
     if (!fs.existsSync(destFile) || isForce) {
@@ -247,14 +249,14 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
     pkg.scripts = pkg.scripts || {};
     let updated = false;
     const julesScripts = {
-      "jules:dispatch": "node scripts/jules-dispatch.mjs",
-      "jules:queue": "node bin/agentctl.mjs queue",
-      "jules:create": "node scripts/jules-create.mjs",
-      "jules:status": "node scripts/jules-status.mjs",
-      "jules:audit": "node scripts/jules-self-audit.mjs",
-      "jules:scan": "node scripts/jules-scan-todos.mjs",
-      "jules:swarm": "node bin/agentctl.mjs swarm",
-      "jules:nightly": "node scripts/jules-nightly.mjs"
+      "jules:dispatch": "npx agentctl dispatch",
+      "jules:queue": "npx agentctl queue",
+      "jules:create": "npx agentctl create",
+      "jules:status": "npx agentctl status",
+      "jules:audit": "npx agentctl gate",
+      "jules:scan": "npx agentctl scan",
+      "jules:swarm": "npx agentctl swarm",
+      "jules:nightly": "npx agentctl clean"
     };
 
     for (const [key, val] of Object.entries(julesScripts)) {

package/index.mjs

@@ -1,11 +1,11 @@
 /**
- * Google Jules Orchestrator Kit - Node.js SDK (v0.25.1)
+ * Google Jules Orchestrator Kit - Node.js SDK (v0.28.2)
  *
  * Exposes core orchestrator functions for programmatically driving agent tasks,
  * security auditing, repo gating, and state operations.
  */
 
-export { loadConfig, detectStack, resolveVerify, resolveRoot, normalizePath, TIER_PRESETS } from "./src/config.mjs";
+export { loadConfig, parseYaml, detectStack, resolveVerify, resolveRoot, normalizePath, TIER_PRESETS } from "./src/config.mjs";
 export {
   shannonEntropy,
   redactSecrets,
@@ -19,14 +19,17 @@ export { isolateMcpStdout, writeMcpFrame } from "./src/mcp.mjs";
 export { git, runCmd, resolveBase, changedFiles, diffBytes, diffText } from "./src/git.mjs";
 export {
   createProvider,
+  createFailoverProvider,
   JULES_PRESET,
   CLAUDE_PRESET,
   CODEX_PRESET,
+  MissingApiKeyError,
   ProviderRateLimitError,
   ProviderUnavailableError,
   ProviderSchemaError,
   parseRetryAfter,
 } from "./src/provider.mjs";
+export { detectPolyglotStack, resolveWorkspaceBoundary, bootstrapZeroTestRepo } from "./src/stack-detector.mjs";
 export {
   appendLedger,
   readLedger,

package/package.json

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

package/scripts/jules-dispatch.mjs

@@ -10,10 +10,12 @@ import { loadConfig } from "../src/config.mjs";
 import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 
-process.emitWarning(
-  "scripts/jules-dispatch.mjs is deprecated and will be removed in v1.0.0. Use 'agentctl dispatch' or the programmatic SDK.",
-  "DeprecationWarning"
-);
+if (process.argv[1] && (process.argv[1].endsWith("jules-dispatch.mjs") || process.argv[1].endsWith("jules-dispatch"))) {
+  process.emitWarning(
+    "scripts/jules-dispatch.mjs is deprecated and will be removed in v1.0.0. Use 'agentctl dispatch' or the programmatic SDK.",
+    "DeprecationWarning"
+  );
+}
 
 const args = process.argv.slice(2);
 let title = "Task Dispatch";

package/scripts/jules-self-audit.mjs

@@ -5,12 +5,23 @@
  * Delegates execution to src/engine.mjs gate().
  */
 
-import { gate } from "../src/engine.mjs";
-import { loadConfig, parseYaml } from "../src/config.mjs";
-import { matchesGlob } from "../src/security.mjs";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
+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);
 }

package/src/config.mjs

@@ -257,6 +257,19 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
   const envDailyTasks = process.env.JULES_DAILY_BUDGET !== undefined ? Number(process.env.JULES_DAILY_BUDGET) : null;
   const envDiffKb = process.env.JULES_MAX_DIFF_KB !== undefined ? Number(process.env.JULES_MAX_DIFF_KB) : null;
 
+  const parsedLimits = parsed.limits || {};
+  const normalizedLimits = {
+    diffKb: parsedLimits.diff_kb ?? parsedLimits.diffKb,
+    promptKb: parsedLimits.prompt_kb ?? parsedLimits.promptKb,
+    dailyTasks: parsedLimits.daily_tasks ?? parsedLimits.dailyTasks,
+    repairAttempts: parsedLimits.repair_attempts ?? parsedLimits.repairAttempts,
+    concurrency: parsedLimits.concurrency,
+    staggerMs: parsedLimits.stagger_ms ?? parsedLimits.staggerMs,
+  };
+  for (const k of Object.keys(normalizedLimits)) {
+    if (normalizedLimits[k] === undefined) delete normalizedLimits[k];
+  }
+
   const config = {
     version: parsed.version || DEFAULTS.version,
     provider: parsed.provider || DEFAULTS.provider,
@@ -269,7 +282,7 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     limits: {
       ...DEFAULTS.limits,
       ...tierLimits,
-      ...(parsed.limits || {}),
+      ...normalizedLimits,
       ...(envDailyTasks !== null && !isNaN(envDailyTasks) ? { dailyTasks: envDailyTasks } : {}),
       ...(envDiffKb !== null && !isNaN(envDiffKb) ? { diffKb: envDiffKb } : {}),
     },

package/src/dashboard.mjs

@@ -32,7 +32,7 @@ export function getDashboardHtml(root = process.cwd()) {
   </style>
 </head>
 <body>
-  <h1>🚀 jules-orchestrator-kit Dashboard (v0.27.0)</h1>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v0.28.2)</h1>
   <div class="subtitle">Repository: <code>${root}</code></div>
 
   <div class="grid">
@@ -59,11 +59,11 @@ export function getDashboardHtml(root = process.cwd()) {
           fetch('/api/locks').then(r => r.json())
         ]);
 
-        document.getElementById('telemetry-status').innerHTML = telRes.integrity?.valid
+        document.getElementById('telemetry-status').innerHTML = (telRes.integrity?.ok || telRes.integrity?.valid)
           ? '<span class="badge badge-success">✓ SHA-256 Hash Chain Valid</span> <p>Events logged: ' + telRes.events.length + '</p>'
           : '<span class="badge badge-warn">⚠ Check Telemetry Logs</span>';
 
-        document.getElementById('flaky-status').innerHTML = '<p>Verdict: <code>' + (flakyRes.verdict?.action || 'CLEAN') + '</code></p><p>Tracked test runs: ' + flakyRes.count + '</p>';
+        document.getElementById('flaky-status').innerHTML = '<p>Verdict: <code>' + (flakyRes.verdict?.verdict || flakyRes.verdict?.action || 'CLEAN') + '</code></p><p>Tracked test runs: ' + flakyRes.count + '</p>';
         document.getElementById('locks-status').innerHTML = '<p>Active VFS Locks: <code>' + locksRes.count + '</code></p>';
       } catch (err) {
         console.error("Dashboard update failed:", err);
@@ -79,13 +79,6 @@ export function getDashboardHtml(root = process.cwd()) {
 export function createDashboardServer({ root = process.cwd(), port: _port = 4100 } = {}) {
   return http.createServer((req, res) => {
     const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
-    res.setHeader("Access-Control-Allow-Origin", "*");
-    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
-
-    if (req.method === "OPTIONS") {
-      res.writeHead(204);
-      return res.end();
-    }
 
     if (url.pathname === "/" || url.pathname === "/index.html") {
       res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
@@ -94,7 +87,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: "0.27.0", root, ts: new Date().toISOString() }));
+      return res.end(JSON.stringify({ ok: true, version: "0.28.2", root, ts: new Date().toISOString() }));
     }
 
     if (url.pathname === "/api/telemetry") {
@@ -127,10 +120,10 @@ export function createDashboardServer({ root = process.cwd(), port: _port = 4100
   });
 }
 
-export function startDashboardServer(port = 4100, root = process.cwd()) {
+export function startDashboardServer(port = 4100, root = process.cwd(), host = "127.0.0.1") {
   const server = createDashboardServer({ root, port });
-  server.listen(port, "0.0.0.0", () => {
-    console.log(`🚀 jules-orchestrator-kit Dashboard running at http://localhost:${port}`);
+  server.listen(port, host, () => {
+    console.log(`🚀 jules-orchestrator-kit Dashboard running at http://${host}:${port}`);
   });
   return server;
 }

package/src/engine.mjs

@@ -101,20 +101,21 @@ export async function gate(opts = {}) {
   const root = opts.root || process.cwd();
   const config = opts.config || loadConfig(root);
   const base = opts.base || config.baseBranch || "main";
+  const mode = opts.mode || (opts.workingTree ? "working-tree" : (process.env.JULES_GATE_MODE || "working-tree"));
   const progressBus = opts.progressBus;
   const progressToken = opts.progressToken;
   const phases = [];
 
-  appendTelemetry(root, "gate_started", { base });
+  appendTelemetry(root, "gate_started", { base, mode });
 
   let files = [];
   let bytes = 0;
   let diffStr = "";
 
   try {
-    files = changedFiles(root, base);
-    bytes = diffBytes(root, base);
-    diffStr = diffText(root, base);
+    files = changedFiles(root, base, mode);
+    bytes = diffBytes(root, base, mode);
+    diffStr = diffText(root, base, mode);
   } catch (err) {
     phases.push({ phase: "git_resolution", ok: false, error: err.message });
     appendTelemetry(root, "gate_finished", { ok: false, code: 1, error: err.message });
@@ -493,9 +494,9 @@ export async function dispatch(task, opts = {}) {
   const cleanPrompt = redactSecrets(task.prompt || "");
 
   // Wire Prompt Guard & Envelope to wrap raw task arguments
-  const untrustedData = task.untrustedData || [cleanPrompt];
+  const taskInstructions = task.taskInstructions || cleanPrompt || task.title || "Autonomous Task Execution";
+  const untrustedData = Array.isArray(task.untrustedData) ? task.untrustedData : [];
   const systemPolicy = task.systemPolicy || config.systemPolicy || "";
-  const taskInstructions = task.taskInstructions || task.title || "Autonomous Task Execution";
   const envelopedPrompt = buildAgentEnvelope(systemPolicy, taskInstructions, untrustedData);
 
   const cleanTask = { ...task, prompt: envelopedPrompt };
@@ -547,7 +548,7 @@ export async function run(tasksOrOpts = {}, opts = {}) {
 
   let filesToProcess = [];
   if (Array.isArray(tasks)) {
-    filesToProcess = tasks.map((t) => (typeof t === "string" ? t : t.id || t.file || t.title));
+    filesToProcess = tasks;
   } else {
     filesToProcess = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
   }
@@ -558,21 +559,27 @@ export async function run(tasksOrOpts = {}, opts = {}) {
     const batch = filesToProcess.slice(i, i + concurrency);
     await Promise.all(
       batch.map(async (fileOrItem) => {
-        const fileName = typeof fileOrItem === "string" ? fileOrItem : fileOrItem.id || fileOrItem.file;
+        const fileName = typeof fileOrItem === "string" ? fileOrItem : fileOrItem.id || fileOrItem.file || fileOrItem.title || "task";
         const srcPath = join(queueDir, fileName);
         try {
           let prompt = typeof fileOrItem === "object" && fileOrItem.prompt ? fileOrItem.prompt : "";
+          let title = typeof fileOrItem === "object" && fileOrItem.title ? fileOrItem.title : fileName;
           if (!prompt && existsSync(srcPath)) {
             prompt = await fs.promises.readFile(srcPath, "utf-8");
           }
-          const task = { title: fileName, prompt };
+          const task = typeof fileOrItem === "object" ? { ...fileOrItem, title, prompt } : { title, prompt };
           const session = await dispatch(task, { root, config, dryRun: isDry });
-          const dstPath = join(completedDir, fileName);
-          if (existsSync(srcPath)) {
-            renameSync(srcPath, dstPath);
+
+          if (session && session.ok === false) {
+            results.push({ file: fileName, ok: false, status: session.status, error: session.error, session });
+          } else {
+            const dstPath = join(completedDir, fileName);
+            if (existsSync(srcPath)) {
+              renameSync(srcPath, dstPath);
+            }
+            appendLedger({ event: "task_completed", file: fileName, session }, root);
+            results.push({ file: fileName, ok: true, session });
           }
-          appendLedger({ event: "task_completed", file: fileName, session }, root);
-          results.push({ file: fileName, ok: true, session });
         } catch (err) {
           results.push({ file: fileName, ok: false, error: err.message });
         }

package/src/git.mjs

@@ -1,4 +1,6 @@
 import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
 import { normalizePath } from "./config.mjs";
 
 
@@ -23,23 +25,35 @@ export function runCmd(command, opts = {}) {
 
   let binary = "";
   let args = [];
+  let useShell = false;
+  let shellCmd = "";
 
   if (Array.isArray(command)) {
     binary = command[0];
     args = command.slice(1);
   } else if (typeof command === "string") {
-    const tokens = command.trim().split(/\s+/).filter(Boolean);
-    binary = tokens[0] || "";
-    args = tokens.slice(1);
+    const trimmed = command.trim();
+    if (/[\&\|\>\<\$\"\'\n\;]/.test(trimmed)) {
+      useShell = true;
+      shellCmd = trimmed;
+    } else {
+      const tokens = trimmed.split(/\s+/).filter(Boolean);
+      binary = tokens[0] || "";
+      args = tokens.slice(1);
+    }
   }
 
-  if (!binary) {
+  if (!binary && !useShell) {
     if (opts.ignoreError) return { status: 0, stdout: "", stderr: "" };
     throw new GateError("Empty command provided");
   }
 
   try {
-    const stdout = execFileSync(binary, args, {
+    const isWin = process.platform === "win32";
+    const execBin = useShell ? (isWin ? (process.env.ComSpec || "cmd.exe") : "/bin/sh") : binary;
+    const execArgs = useShell ? (isWin ? ["/d", "/s", "/c", shellCmd] : ["-c", shellCmd]) : args;
+
+    const stdout = execFileSync(execBin, execArgs, {
       cwd,
       encoding: "utf-8",
       shell: false,
@@ -69,10 +83,10 @@ export function runCmd(command, opts = {}) {
     }
 
     if (isTimeout) {
-      throw new GateError(`Command execution timed out (ETIMEDOUT): ${binary}`, { code: status });
+      throw new GateError(`Command execution timed out (ETIMEDOUT): ${useShell ? shellCmd : binary}`, { code: status });
     }
     if (isNobufs) {
-      throw new GateError(`Command output buffer exceeded limit (ENOBUFS): ${binary}`, { code: status });
+      throw new GateError(`Command output buffer exceeded limit (ENOBUFS): ${useShell ? shellCmd : binary}`, { code: status });
     }
 
     throw err;
@@ -138,29 +152,55 @@ export function resolveBase(root = process.cwd(), baseRef = "main") {
   );
 }
 
-export function changedFiles(root = process.cwd(), base = "main") {
+export function changedFiles(root = process.cwd(), base = "main", mode = "committed") {
   const resolvedRef = resolveBase(root, base);
-  const raw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", `${resolvedRef}...HEAD`], {
-    cwd: root,
-    raw: true,
-  });
-  return raw
-    .split("\0")
-    .map(normalizePath)
-    .filter(Boolean);
+  if (mode === "working-tree" || mode === "working") {
+    const committedRaw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", `${resolvedRef}...HEAD`], { cwd: root, raw: true, ignoreError: true }) || "";
+    const uncommittedRaw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", "HEAD"], { cwd: root, raw: true, ignoreError: true }) || "";
+    const untrackedRaw = git(["-c", "core.quotePath=false", "ls-files", "-z", "--others", "--exclude-standard"], { cwd: root, raw: true, ignoreError: true }) || "";
+
+    const set = new Set([
+      ...committedRaw.split("\0").map(normalizePath).filter(Boolean),
+      ...uncommittedRaw.split("\0").map(normalizePath).filter(Boolean),
+      ...untrackedRaw.split("\0").map(normalizePath).filter(Boolean),
+    ]);
+    return Array.from(set);
+  } else if (mode === "staged" || mode === "index") {
+    const raw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", "--cached", resolvedRef], { cwd: root, raw: true });
+    return raw.split("\0").map(normalizePath).filter(Boolean);
+  } else {
+    const raw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
+    return raw.split("\0").map(normalizePath).filter(Boolean);
+  }
 }
 
-export function diffBytes(root = process.cwd(), base = "main") {
+export function diffText(root = process.cwd(), base = "main", mode = "committed") {
   const resolvedRef = resolveBase(root, base);
-  const raw = git(["diff", "--shortstat", `${resolvedRef}...HEAD`], { cwd: root });
-  if (!raw) return 0;
-  const diffStr = git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
-  return Buffer.byteLength(diffStr, "utf-8");
+  if (mode === "working-tree" || mode === "working") {
+    const committed = git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true, ignoreError: true }) || "";
+    const uncommitted = git(["diff", "HEAD"], { cwd: root, raw: true, ignoreError: true }) || "";
+
+    const untrackedRaw = git(["-c", "core.quotePath=false", "ls-files", "-z", "--others", "--exclude-standard"], { cwd: root, raw: true, ignoreError: true }) || "";
+    const untrackedFiles = untrackedRaw.split("\0").map(normalizePath).filter(Boolean);
+    let untrackedDiff = "";
+    for (const file of untrackedFiles) {
+      try {
+        const fullPath = join(root, file);
+        if (existsSync(fullPath)) {
+          const content = readFileSync(fullPath, "utf-8");
+          untrackedDiff += `\ndiff --git a/${file} b/${file}\nnew file mode 100644\n--- /dev/null\n+++ b/${file}\n`;
+          untrackedDiff += content.split("\n").map((line) => `+${line}`).join("\n") + "\n";
+        }
+      } catch (_) {}
+    }
+    return [committed, uncommitted, untrackedDiff].filter(Boolean).join("\n");
+  }
+  return git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
 }
 
-export function diffText(root = process.cwd(), base = "main") {
-  const resolvedRef = resolveBase(root, base);
-  return git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
+export function diffBytes(root = process.cwd(), base = "main", mode = "committed") {
+  const text = diffText(root, base, mode);
+  return Buffer.byteLength(text, "utf-8");
 }
 
 export function showFromOrigin(root = process.cwd(), base = "main", filePath = "") {

package/src/mcp.mjs

@@ -9,7 +9,7 @@ import { ProgressBus } from "./mcp-progress.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.25.1",
+  version: "0.28.2",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling

package/src/prompt-guard.mjs

@@ -96,7 +96,10 @@ export function buildAgentEnvelope(systemPolicy = "", taskInstructions = "", unt
   }
 
   const sections = [];
-  sections.push(`SYSTEM WARNING: ${warning}`);
+
+  if (sanitizedBlocks.length > 0) {
+    sections.push(`SYSTEM WARNING: ${warning}`);
+  }
 
   if (systemPolicy && typeof systemPolicy === "string" && systemPolicy.trim()) {
     sections.push(`[SYSTEM POLICY]\n${systemPolicy.trim()}`);

package/src/provider.mjs

@@ -3,15 +3,20 @@ import { spawnSync } from "node:child_process";
 export const JULES_PRESET = {
   name: "jules",
   type: "http",
-  url: "https://jules.googleapis.com/v1/projects/{project}/sessions",
+  url: "https://jules.googleapis.com/v1alpha/sessions",
   headers: {
-    "Authorization": "Bearer {token}",
+    "X-Goog-Api-Key": "{token}",
     "Content-Type": "application/json",
   },
   bodyTemplate: {
-    prompt: "{prompt}",
     title: "{title}",
-    branch: "{branch}",
+    prompt: "{prompt}",
+    sourceContext: {
+      source: "{source}",
+      githubRepoContext: {
+        startingBranch: "{branch}",
+      },
+    },
   },
 };
 
@@ -31,6 +36,14 @@ export const CODEX_PRESET = {
   promptViaStdin: false,
 };
 
+export class MissingApiKeyError extends Error {
+  constructor(message = "JULES_API_KEY environment variable is required for Google Jules API dispatch.") {
+    super(message);
+    this.name = "MissingApiKeyError";
+    this.status = 401;
+  }
+}
+
 export class ProviderRateLimitError extends Error {
   constructor(message, opts = {}) {
     super(message);
@@ -92,6 +105,9 @@ function interpolateDeep(node, data) {
  * Creates an HTTP or Exec provider adapter based on spec/config.
  */
 export function createProvider(spec = "jules", config = {}) {
+  if (spec && typeof spec === "object" && typeof spec.dispatch === "function") {
+    return spec;
+  }
   const providerSpec = typeof spec === "string"
     ? (spec === "claude-code" ? CLAUDE_PRESET : spec === "codex" ? CODEX_PRESET : JULES_PRESET)
     : spec;
@@ -100,11 +116,28 @@ export function createProvider(spec = "jules", config = {}) {
     name: providerSpec.name || "custom-provider",
 
     async dispatch(task, ctx = {}) {
-      const rawToken = process.env.JULES_API_KEY || process.env.GEMINI_API_KEY || "";
+      const rawToken = process.env.JULES_API_KEY || (ctx.allowLegacyKey ? process.env.GEMINI_API_KEY : "") || "";
+      if (!rawToken && !ctx.dryRun && providerSpec.name === "jules") {
+        throw new MissingApiKeyError();
+      }
+
+      const isRepoless = Boolean(task.repoless || ctx.repoless);
+      const rawRepo = task.source || ctx.source || process.env.JULES_REPO || "";
+      if (!rawRepo && !ctx.dryRun && providerSpec.name === "jules" && !isRepoless) {
+        throw new Error("Missing connected Jules repository source. Set JULES_REPO or pass source/repoless option.");
+      }
+
+      const sourceName = rawRepo
+        ? (rawRepo.startsWith("sources/") ? rawRepo : `sources/github/${rawRepo}`)
+        : undefined;
+
+      const startingBranch = task.branch || ctx.branch || config.baseBranch || process.env.BASE_BRANCH || "main";
+
       const data = {
         prompt: task.prompt || "",
         title: task.title || "Agent Task",
-        branch: task.branch || (config.branchPrefix ? config.branchPrefix + "task" : "agent/task"),
+        branch: startingBranch,
+        source: sourceName || "",
         project: process.env.JULES_PROJECT_ID || "default",
         ...ctx,
       };
@@ -135,19 +168,31 @@ export function createProvider(spec = "jules", config = {}) {
         }
 
         let body;
+        let bodyObj;
         if (typeof providerSpec.bodyTemplate === "string") {
           try {
             const parsedObj = JSON.parse(providerSpec.bodyTemplate);
-            const interpolatedObj = interpolateDeep(parsedObj, data);
-            body = JSON.stringify(interpolatedObj);
+            bodyObj = interpolateDeep(parsedObj, data);
           } catch (_) {
             body = interpolateString(providerSpec.bodyTemplate, data);
           }
         } else if (providerSpec.bodyTemplate) {
-          const interpolatedObj = interpolateDeep(providerSpec.bodyTemplate, data);
-          body = JSON.stringify(interpolatedObj);
+          bodyObj = interpolateDeep(providerSpec.bodyTemplate, data);
         } else {
-          body = JSON.stringify(data);
+          bodyObj = { ...data };
+        }
+
+        if (bodyObj && typeof bodyObj === "object") {
+          if (isRepoless || !sourceName) {
+            delete bodyObj.sourceContext;
+          }
+          if (task.autoPr || ctx.autoPr) {
+            bodyObj.automationMode = "AUTO_CREATE_PR";
+          }
+          if (task.requirePlanApproval || ctx.requirePlanApproval) {
+            bodyObj.requirePlanApproval = true;
+          }
+          body = JSON.stringify(bodyObj);
         }
 
         const timeoutMs = ctx.timeoutMs || config.timeoutMs || providerSpec.timeoutMs || 120_000;