jules-orchestrator-kit 0.22.6 → 0.22.7

package/README.md

@@ -68,8 +68,11 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 ### Engine System Highlights
 
-- **Linearizable VFS Mutex (`src/state.mjs`)**: Kernel-level directory mutex (`withVfsMutex`) guaranteeing serial linearizability for SHA-256 hash-chained session ledgers under high concurrency.
-- **PID Recycling & Stale Lock Protection (`src/state.mjs`)**: Linux `/proc/<pid>/stat` launch-time validation prevents false-positive lock reaps from recycled OS process IDs.
+- **Native Task DAG Executor (`src/dag-engine.mjs`)**: Zero-dependency `DagExecutor` with Kahn's topological sort algorithm, SHA-256 interface fingerprinting post-task execution, and pre-execution cycle detection (`DagCycleError`).
+- **Intent Journaling & Zombie Worktree Reaper (`src/journal.mjs`)**: Automatic boot-time scan (`reapOrphanedIntents`) in `agentctl` and MCP server that tracks git operations in `.agent/state/journal.jsonl` and prunes orphaned worktrees left by crashed/recycled processes.
+- **Hermetic Network Egress Guard (`src/preload-net-guard.mjs`)**: Intercepts and blocks unmocked outbound HTTP/HTTPS egress during test execution (`NODE_OPTIONS="--import ./src/preload-net-guard.mjs"`), enforcing hermetic testing while allowing local loopback (`localhost`, `127.0.0.1`).
+- **Linearizable VFS Mutex (`src/state.mjs`)**: Kernel-level directory mutex (`withVfsMutex`) guaranteeing serial linearizability for SHA-256 hash-chained session ledgers with atomic budget reservation (`reserveBudgetAtomic`).
+- **PID Recycling & Stale Lock Protection (`src/state.mjs`)**: Linux `/proc/<pid>/stat` launch-time validation and random UUID nonces prevent false-positive lock reaps from recycled OS process IDs.
 - **Memory-Bounded Content-Length MCP Streaming (`src/mcp.mjs`)**: Native MCP server over stdio streams using `McpFrameDecoder` with a 4 MB memory safety ceiling and panic boundaries to prevent stdout stack trace leaks.
 - **Process Group Isolation (`src/process-group.mjs`)**: `ProcessGroupManager` creates isolated process groups (`detached: true`) and catches `SIGINT`/`SIGTERM`/`exit` signals to execute `process.kill(-pgid)`, guaranteeing zero zombie processes.
 - **TOCTOU & Symlink Defense (`src/security.mjs`)**: `safeAtomicWrite()` uses `O_CREAT | O_EXCL | O_WRONLY` temp files with `fsyncSync` + `renameSync` and `lstatSync`/`realpathSync` symlink checks.
@@ -84,12 +87,14 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 ![Zero-Trust Security Guarantees](docs/assets/security-shield.svg?v=3)
 
-### The 4-Phase Safety Audit (`agentctl gate`)
+### The 4-Phase Safety Audit & Security Boundary (`agentctl gate`)
 
 1. **Scope Fencing (`forbidden_paths`)**: Ensures agents cannot modify protected files (`package.json`, `.github/`, deployment keys) without explicit overrides.
 2. **Diff Payload Governor**: Rejects oversized diffs (> 75 KB) to prevent truncation and hidden payload injections.
 3. **Secret Entropy Scanner**: Scans diffs for high-confidence secrets (AWS keys, Stripe keys, GitHub tokens, SSH private keys) using Shannon Entropy analysis (> 3.6 bits).
-4. **Trusted Verification Suite**: Executes auto-detected unit tests and linters (`npm test`) to guarantee zero regressions before merging.
+4. **Trusted Verification Suite**: Executes auto-detected unit tests and linters (`npm test`) inside a hermetic network sandbox to guarantee zero regressions before merging.
+5. **Prompt Guard Boundary (`src/prompt-guard.mjs`)**: `sanitizeUntrustedData` strips bidi control characters, ANSI escape sequences, zero-width unicode, and neutralizes prompt injection tags (`<|im_start|>`, `[INST]`).
+6. **MCP Stream Isolation (`src/mcp.mjs`)**: Seals `process.stdout.write` framing stream to prevent log output from corrupting JSON-RPC stdio frames.
 
 > [!NOTE]
 > All security rules are fetched strictly from `origin/main` (never untrusted PR branches) to prevent prompt-injection attacks from altering security rules.
@@ -178,7 +183,7 @@ steps:
 | **`mcp`** | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) JSON-RPC 2.0 server |
 | **`doctor`** | `agentctl doctor` | Verifies stack configuration, environment keys, and daily token budget |
 | **`scan`** | `agentctl scan` | Scans codebase for `TODO` and `FIXME` comments and generates task queue |
-| **`cleanup`** | `agentctl cleanup` | Audits and cleans up stale git worktrees and temporary state files |
+| **`clean`** | `agentctl clean` | Audits and cleans up stale git worktrees, orphaned intents, locks, and temporary state files |
 
 </details>
 

package/bin/agentctl.mjs

@@ -7,14 +7,14 @@ import { loadConfig, resolveRoot, detectStack } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
 import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir, ensureDir } from "../src/state.mjs";
 import { worktreePrune } from "../src/git.mjs";
-import { reapOrphanedIntents } from "../src/journal.mjs";
+import { reapOrphanedIntents, reapStaleMutexDirs } from "../src/journal.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.22.6 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.22.7 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -44,12 +44,13 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.22.6");
+    console.log("agentctl v0.22.7");
     process.exit(0);
   }
 
   const root = resolveRoot();
   reapOrphanedIntents(root);
+  reapStaleMutexDirs(root);
   const config = loadConfig(root);
 
   switch (command) {
@@ -225,7 +226,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.22.6)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.22.7)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);

package/index.mjs

@@ -50,7 +50,7 @@ export { checkAssetIntegrity } from "./src/asset_integrity.mjs";
 export { classifyRiskTier, RISK_TIERS } from "./src/risk.mjs";
 export { checkRulesBudget } from "./src/rules_budget.mjs";
 export { DagExecutor, DagCycleError } from "./src/dag-engine.mjs";
-export { journalIntent, journalDone, reapOrphanedIntents } from "./src/journal.mjs";
+export { journalIntent, journalDone, reapOrphanedIntents, reapStaleMutexDirs } from "./src/journal.mjs";
 
 // Legacy SDK shims for backward compatibility
 export { resolveProjectCommands, resolveWorkspaceExecutionBoundary } from "./scripts/command-resolver.mjs";

package/package.json

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

package/src/engine.mjs

@@ -3,6 +3,7 @@ import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
 import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
 import { createProvider } from "./provider.mjs";
 import { withBudget, appendLedger, getQueueDir, ensureDir } from "./state.mjs";
+import { sanitizeUntrustedData, buildAgentEnvelope } from "./prompt-guard.mjs";
 import { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
@@ -164,8 +165,9 @@ export async function gate(opts = {}) {
   let buildResult = { ok: true, status: 0 };
 
   const existingNodeOptions = process.env.NODE_OPTIONS || "";
-  const netGuardFlag = "--import ./src/preload-net-guard.mjs";
-  const guardNodeOptions = existingNodeOptions && !existingNodeOptions.includes(netGuardFlag)
+  const netGuardUrl = new URL("./preload-net-guard.mjs", import.meta.url).href;
+  const netGuardFlag = `--import ${netGuardUrl}`;
+  const guardNodeOptions = existingNodeOptions && !existingNodeOptions.includes(netGuardFlag) && !existingNodeOptions.includes("preload-net-guard.mjs")
     ? `${existingNodeOptions} ${netGuardFlag}`
     : existingNodeOptions ? existingNodeOptions : netGuardFlag;
 
@@ -354,8 +356,15 @@ export async function dispatch(task, opts = {}) {
   }
 
   // Redact secrets in prompt before dispatching
-  const cleanPrompt = redactSecrets(task.prompt);
-  const cleanTask = { ...task, prompt: cleanPrompt };
+  const cleanPrompt = redactSecrets(task.prompt || "");
+
+  // Wire Prompt Guard & Envelope to wrap raw task arguments
+  const untrustedData = task.untrustedData || [cleanPrompt];
+  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 };
 
   return withBudget(
     () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun }),

package/src/git.mjs

@@ -2,6 +2,9 @@ import { execFileSync } from "node:child_process";
 import { sep } from "node:path";
 import { journalIntent, journalDone } from "./journal.mjs";
 
+export const NET_GUARD_PRELOAD_URL = new URL("./preload-net-guard.mjs", import.meta.url).href;
+export const NET_GUARD_FLAG = `--import ${NET_GUARD_PRELOAD_URL}`;
+
 export class GateError extends Error {
   constructor(message, opts = {}) {
     super(message);

package/src/journal.mjs

@@ -1,9 +1,54 @@
-import { openSync, writeSync, fsyncSync, closeSync, existsSync, readFileSync, unlinkSync, readdirSync } from "node:fs";
+import { openSync, writeSync, fsyncSync, closeSync, existsSync, readFileSync, unlinkSync, readdirSync, statSync, renameSync, rmdirSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { getStateDir, getProcessStartTime, isPidAlive, getLockDir } from "./state.mjs";
 import { worktreeRemove, worktreePrune } from "./git.mjs";
 
+/**
+ * Scans .agent/state/ for .mutex directories.
+ * If empty AND older than ttlMs, renames to a temporary .grave-<pid> path and rmdirSyncs it (atomic CAS pattern).
+ * @param {string} root - Project root directory
+ * @param {Object} [opts] - Options object
+ * @param {number} [opts.ttlMs=30000] - Time to live in milliseconds
+ * @returns {{ reapedCount: number, reaped: Array<string> }}
+ */
+export function reapStaleMutexDirs(root, { ttlMs = 30000 } = {}) {
+  const stateDir = getStateDir(root);
+  if (!existsSync(stateDir)) {
+    return { reapedCount: 0, reaped: [] };
+  }
+
+  const reaped = [];
+  try {
+    const entries = readdirSync(stateDir, { withFileTypes: true });
+    const now = Date.now();
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.endsWith(".mutex")) {
+        const mutexPath = join(stateDir, entry.name);
+        try {
+          const contents = readdirSync(mutexPath);
+          if (contents.length === 0) {
+            const stat = statSync(mutexPath);
+            const age = now - stat.mtimeMs;
+            if (age >= ttlMs) {
+              const gravePath = join(stateDir, `.grave-${process.pid}-${randomUUID()}`);
+              try {
+                renameSync(mutexPath, gravePath);
+                try {
+                  rmdirSync(gravePath);
+                  reaped.push(entry.name);
+                } catch (_) {}
+              } catch (_) {}
+            }
+          }
+        } catch (_) {}
+      }
+    }
+  } catch (_) {}
+
+  return { reapedCount: reaped.length, reaped };
+}
+
 /**
  * Appends an intent record to .agent/state/journal.jsonl before a mutating operation.
  * @param {string} root - Project root directory
@@ -138,6 +183,14 @@ export function reapOrphanedIntents(root) {
               const lockPath = join(lockDir, file);
               try {
                 const lockContent = JSON.parse(readFileSync(lockPath, "utf-8"));
+                const lockPid = lockContent.pid;
+                const lockStartTime = lockContent.processStartTime ?? lockContent.starttime ?? null;
+
+                // Do NOT unlink if the PID exists AND its start time matches a live process
+                if (lockPid && isPidAlive(lockPid, lockStartTime)) {
+                  continue;
+                }
+
                 if (
                   lockContent.pid === intent.pid ||
                   (intent.targetPath && Array.isArray(lockContent.files) && lockContent.files.includes(intent.targetPath))
@@ -174,3 +227,4 @@ export function reapOrphanedIntents(root) {
 
   return { reapedCount: reaped.length, reaped };
 }
+

package/src/mcp.mjs

@@ -3,11 +3,11 @@ import { loadConfig, resolveRoot, detectStack } from "./config.mjs";
 import { gate, dispatch } from "./engine.mjs";
 import { classifyRiskTier } from "./risk.mjs";
 import { checkDailyBudget, lockStatus } from "./state.mjs";
-import { reapOrphanedIntents } from "./journal.mjs";
+import { reapOrphanedIntents, reapStaleMutexDirs } from "./journal.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.22.6",
+  version: "0.22.7",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling
@@ -355,6 +355,7 @@ export function writeMcpFrame(targetOutput, data) {
 export function startMcpServer(input = process.stdin, output = process.stdout, opts = {}) {
   const root = opts.root || resolveRoot();
   reapOrphanedIntents(root);
+  reapStaleMutexDirs(root);
   isolateMcpStdout(process.stdout, opts);
   if (output && output !== process.stdout) {
     isolateMcpStdout(output, opts);

package/src/prompt-guard.mjs

@@ -78,8 +78,12 @@ export function buildAgentEnvelope(systemPolicy = "", taskInstructions = "", unt
   if (Array.isArray(untrustedDataArray)) {
     for (const item of untrustedDataArray) {
       if (typeof item === "string") {
-        if (item.trim().startsWith("<<<UNTRUSTED-DATA-BEGIN")) {
-          sanitizedBlocks.push(item);
+        const trimmed = item.trim();
+        const match = /^<<<UNTRUSTED-DATA-BEGIN(?:\s+source="([^"]+)")?>\n?([\s\S]*?)\n?<<<UNTRUSTED-DATA-END>>>$/.exec(trimmed);
+        if (match) {
+          const src = match[1] || "untrusted";
+          const body = match[2];
+          sanitizedBlocks.push(sanitizeUntrustedData(body, src));
         } else {
           sanitizedBlocks.push(sanitizeUntrustedData(item, "untrusted"));
         }

package/src/state.mjs

@@ -188,7 +188,15 @@ export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
   try {
     const content = readFileSync(filePath, "utf-8");
     const lines = content.split("\n").filter(Boolean);
-    const count = lines.length;
+    let count = 0;
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry && entry.event === "budget_reserved") {
+          count++;
+        }
+      } catch (_) {}
+    }
     return {
       ok: count < limit,
       used: count,
@@ -224,13 +232,14 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
       try {
         const raw = readFileSync(filePath, "utf-8");
         const lines = raw.split("\n").filter(Boolean);
-        count = lines.length;
-        for (let i = lines.length - 1; i >= 0; i--) {
+        for (const line of lines) {
           try {
-            const lastObj = JSON.parse(lines[i]);
-            if (lastObj.hash) {
-              prevHash = lastObj.hash;
-              break;
+            const entry = JSON.parse(line);
+            if (entry && entry.event === "budget_reserved") {
+              count++;
+            }
+            if (entry && entry.hash) {
+              prevHash = entry.hash;
             }
           } catch (_) {}
         }