jules-orchestrator-kit 0.22.4 → 0.22.6

package/bin/agentctl.mjs

@@ -4,16 +4,17 @@ import { parseArgs } from "node:util";
 import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, resolveRoot, detectStack } from "../src/config.mjs";
-import { gate, dispatch, run } from "../src/engine.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";
 
 const args = process.argv.slice(2);
 const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.22.4 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.22.6 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -43,11 +44,12 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.22.4");
+    console.log("agentctl v0.22.6");
     process.exit(0);
   }
 
   const root = resolveRoot();
+  reapOrphanedIntents(root);
   const config = loadConfig(root);
 
   switch (command) {
@@ -150,7 +152,7 @@ async function main() {
 
     case "queue": {
       const queueDir = getQueueDir(root);
-      const files = readdirSync(queueDir).filter((f) => f.endsWith(".md"));
+      const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
       console.log(` Found ${files.length} queued task(s) in .agent/queue/`);
       if (files.length > 0) {
         const tasks = files.map((f) => ({
@@ -168,7 +170,7 @@ async function main() {
     case "swarm": {
       console.log("🚀 Running Swarm Orchestrator...");
       const queueDir = getQueueDir(root);
-      const files = readdirSync(queueDir).filter((f) => f.endsWith(".md"));
+      const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
       if (files.length === 0) {
         console.log("No pending tasks found for swarm.");
         process.exit(0);
@@ -223,7 +225,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.22.4)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.22.6)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);

package/index.mjs

@@ -16,7 +16,7 @@ export {
 } from "./src/security.mjs";
 export { sanitizeUntrustedData, buildAgentEnvelope } from "./src/prompt-guard.mjs";
 export { isolateMcpStdout, writeMcpFrame } from "./src/mcp.mjs";
-export { git, runCmd, changedFiles, diffBytes, diffText } from "./src/git.mjs";
+export { git, runCmd, resolveBase, changedFiles, diffBytes, diffText } from "./src/git.mjs";
 export { createProvider, JULES_PRESET, CLAUDE_PRESET, CODEX_PRESET } from "./src/provider.mjs";
 export {
   appendLedger,
@@ -36,8 +36,9 @@ export {
   BudgetError,
   isPidAlive,
   getProcessStartTime,
+  parseProcStat,
 } from "./src/state.mjs";
-export { gate, dispatch, repair, run, fingerprintFailureState } from "./src/engine.mjs";
+export { gate, dispatch, repair, run, fingerprintFailureState, isTaskFile } from "./src/engine.mjs";
 export { validateEnvelope } from "./src/envelope.mjs";
 export {
   createExecutionEnvelope,
@@ -49,6 +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";
 
 // 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.4",
+  "version": "0.22.6",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/scripts/jules-queue-runner.mjs

@@ -5,6 +5,7 @@
  */
 
 import { getQueueDir, ensureDir } from "../src/state.mjs";
+import { isTaskFile } from "../src/engine.mjs";
 import { readdirSync, renameSync } from "node:fs";
 import { join } from "node:path";
 
@@ -19,7 +20,7 @@ export function classifyQueueFailure(err) {
 if (process.argv[1] && process.argv[1].endsWith("jules-queue-runner.mjs")) {
   const root = process.env.JULES_PROJECT_ROOT || process.cwd();
   const queueDir = getQueueDir(root);
-  const files = readdirSync(queueDir).filter((f) => f.endsWith(".md"));
+  const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
 
   if (files.length === 0) {
     console.log("Queue processing complete!");

package/src/engine.mjs

@@ -3,10 +3,60 @@ 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 { readdirSync, readFileSync, renameSync } from "node:fs";
+import { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 
+/**
+ * Validates whether a file in .agent/jules-queue/ is a task file.
+ * Filters out README.md and matches TASK-*.md or valid envelope front-matter.
+ */
+export function isTaskFile(fileName, queueDirOrContent = null) {
+  if (!fileName || typeof fileName !== "string") return false;
+  const lower = fileName.toLowerCase();
+
+  // Explicitly filter out README.md
+  if (lower === "readme.md" || lower.endsWith("/readme.md") || lower.endsWith("\\readme.md")) {
+    return false;
+  }
+
+  if (!lower.endsWith(".md")) {
+    return false;
+  }
+
+  // Matching TASK-*.md or task-*.md
+  if (/^task-.*\.md$/i.test(fileName)) {
+    return true;
+  }
+
+  // Check valid envelope front-matter
+  if (queueDirOrContent) {
+    try {
+      let content = queueDirOrContent;
+      if (typeof queueDirOrContent === "string" && !queueDirOrContent.includes("\n") && existsSync(queueDirOrContent)) {
+        const fullPath = queueDirOrContent.endsWith(fileName) ? queueDirOrContent : join(queueDirOrContent, fileName);
+        if (existsSync(fullPath)) {
+          content = readFileSync(fullPath, "utf-8");
+        }
+      }
+      if (typeof content === "string") {
+        const trimmed = content.trimStart();
+        if (trimmed.startsWith("---")) {
+          const endFm = trimmed.indexOf("\n---", 3);
+          if (endFm !== -1) {
+            const frontMatter = trimmed.slice(3, endFm);
+            if (/(?:taskId|envelopeId|baseRef|baseSha|task|title|id|version|capabilities|scope|verify):/i.test(frontMatter)) {
+              return true;
+            }
+          }
+        }
+      }
+    } catch (_) {}
+  }
+
+  return false;
+}
+
 /**
  * Computes a SHA-256 fingerprint for a failure state (normalized stderr + diff text).
  */
@@ -322,7 +372,7 @@ export async function run(opts = {}) {
   const completedDir = join(queueDir, "completed");
   ensureDir(completedDir);
 
-  const files = readdirSync(queueDir).filter((f) => f.endsWith(".md"));
+  const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
   const results = [];
 
   for (let i = 0; i < files.length; i += concurrency) {

package/src/git.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { sep } from "node:path";
+import { journalIntent, journalDone } from "./journal.mjs";
 
 export class GateError extends Error {
   constructor(message, opts = {}) {
@@ -14,8 +15,14 @@ function normalizePath(p) {
   return p.split(sep).join("/").replace(/\\/g, "/");
 }
 
+const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
+const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024; // 10 MB
+
 export function runCmd(command, opts = {}) {
   const cwd = opts.cwd || process.cwd();
+  const timeout = opts.timeout || DEFAULT_TIMEOUT;
+  const maxBuffer = opts.maxBuffer || DEFAULT_MAX_BUFFER;
+
   let binary = "";
   let args = [];
 
@@ -40,16 +47,36 @@ export function runCmd(command, opts = {}) {
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],
       env: opts.env || process.env,
+      timeout,
+      maxBuffer,
     });
     return { status: 0, stdout: stdout.trim(), stderr: "" };
   } catch (err) {
+    const isTimeout = err.code === "ETIMEDOUT" || (err.signal === "SIGTERM" && err.killed);
+    const isNobufs = err.code === "ENOBUFS" || (err.message && err.message.includes("maxBuffer"));
+
+    const status = err.status || (isTimeout ? 124 : 1);
+    let stdout = (err.stdout || "").toString().trim();
+    let stderr = (err.stderr || err.message || "").toString().trim();
+
+    if (isTimeout && !stderr.includes("ETIMEDOUT")) {
+      stderr = `Command execution timed out after ${timeout}ms (ETIMEDOUT)${stderr ? "\n" + stderr : ""}`;
+    }
+    if (isNobufs && !stderr.includes("ENOBUFS")) {
+      stderr = `Command output buffer exceeded limit of ${maxBuffer} bytes (ENOBUFS)${stderr ? "\n" + stderr : ""}`;
+    }
+
     if (opts.ignoreError) {
-      return {
-        status: err.status || 1,
-        stdout: (err.stdout || "").toString().trim(),
-        stderr: (err.stderr || "").toString().trim(),
-      };
+      return { status, stdout, stderr };
     }
+
+    if (isTimeout) {
+      throw new GateError(`Command execution timed out (ETIMEDOUT): ${binary}`, { code: status });
+    }
+    if (isNobufs) {
+      throw new GateError(`Command output buffer exceeded limit (ENOBUFS): ${binary}`, { code: status });
+    }
+
     throw err;
   }
 }
@@ -59,20 +86,35 @@ export function runCmd(command, opts = {}) {
  */
 export function git(args = [], opts = {}) {
   const cwd = opts.cwd || process.cwd();
+  const timeout = opts.timeout || DEFAULT_TIMEOUT;
+  const maxBuffer = opts.maxBuffer || DEFAULT_MAX_BUFFER;
   const argArray = Array.isArray(args) ? args : String(args).split(" ").filter(Boolean);
+
   try {
     const stdout = execFileSync("git", argArray, {
       cwd,
       encoding: "utf-8",
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],
+      timeout,
+      maxBuffer,
     });
     return opts.raw ? stdout : stdout.trim();
   } catch (err) {
     if (opts.ignoreError) {
       return "";
     }
+    const isTimeout = err.code === "ETIMEDOUT" || (err.signal === "SIGTERM" && err.killed);
+    const isNobufs = err.code === "ENOBUFS" || (err.message && err.message.includes("maxBuffer"));
     const stderr = (err.stderr || err.message || "").toString().trim();
+
+    if (isTimeout) {
+      throw new GateError(`Git command timed out [git ${argArray.join(" ")}]: ETIMEDOUT`, { code: 124 });
+    }
+    if (isNobufs) {
+      throw new GateError(`Git command output buffer exceeded limit [git ${argArray.join(" ")}]: ENOBUFS`, { code: 1 });
+    }
+
     throw new GateError(`Git command failed [git ${argArray.join(" ")}]: ${stderr}`);
   }
 }
@@ -88,7 +130,7 @@ export function resolveBase(root = process.cwd(), baseRef = "main") {
         stdio: ["ignore", "pipe", "ignore"],
       });
       if (res && res.trim()) {
-        return ref;
+        return res.trim();
       }
     } catch (_) {}
   }
@@ -133,8 +175,28 @@ export function showFromOrigin(root = process.cwd(), base = "main", filePath = "
   }
 }
 
+export function createBranch(root = process.cwd(), branch = "") {
+  const opId = journalIntent(root, { type: "create_branch", branch, targetPath: "" });
+  try {
+    const res = git(["branch", branch], { cwd: root });
+    journalDone(root, opId);
+    return res;
+  } catch (err) {
+    journalDone(root, opId);
+    throw err;
+  }
+}
+
 export function worktreeAdd(root = process.cwd(), branch = "agent/task", targetDir = "") {
-  return git(["worktree", "add", targetDir, "-b", branch], { cwd: root });
+  const opId = journalIntent(root, { type: "worktree_add", targetPath: targetDir, branch });
+  try {
+    const res = git(["worktree", "add", targetDir, "-b", branch], { cwd: root });
+    journalDone(root, opId);
+    return res;
+  } catch (err) {
+    journalDone(root, opId);
+    throw err;
+  }
 }
 
 export function worktreeRemove(root = process.cwd(), targetDir = "") {

package/src/journal.mjs

@@ -0,0 +1,176 @@
+import { openSync, writeSync, fsyncSync, closeSync, existsSync, readFileSync, unlinkSync, readdirSync } 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";
+
+/**
+ * Appends an intent record to .agent/state/journal.jsonl before a mutating operation.
+ * @param {string} root - Project root directory
+ * @param {Object|string} op - Operation payload or name
+ * @returns {string} opId - Unique operation identifier
+ */
+export function journalIntent(root, op) {
+  const stateDir = getStateDir(root);
+  const journalPath = join(stateDir, "journal.jsonl");
+
+  const opObj = typeof op === "string" ? { type: op } : op || {};
+  const opId = opObj.opId || `op-${randomUUID()}`;
+  const pid = process.pid;
+  const processStartTime = getProcessStartTime(pid);
+
+  const record = {
+    opId,
+    event: "intent",
+    type: opObj.type || opObj.operation || "unknown",
+    targetPath: opObj.targetPath || opObj.targetDir || opObj.path || "",
+    pid,
+    processStartTime,
+    timestamp: new Date().toISOString(),
+    ...opObj,
+  };
+
+  const fd = openSync(journalPath, "a");
+  try {
+    writeSync(fd, JSON.stringify(record) + "\n", "utf-8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+
+  return opId;
+}
+
+/**
+ * Appends a journal_done record to .agent/state/journal.jsonl upon operation completion.
+ * @param {string} root - Project root directory
+ * @param {string} opId - Operation identifier returned by journalIntent
+ * @returns {string|null} opId
+ */
+export function journalDone(root, opId) {
+  if (!opId) return null;
+  const stateDir = getStateDir(root);
+  const journalPath = join(stateDir, "journal.jsonl");
+
+  const record = {
+    opId,
+    event: "journal_done",
+    timestamp: new Date().toISOString(),
+  };
+
+  const fd = openSync(journalPath, "a");
+  try {
+    writeSync(fd, JSON.stringify(record) + "\n", "utf-8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+
+  return opId;
+}
+
+/**
+ * Scans .agent/state/journal.jsonl for uncompleted intents belonging to dead PIDs,
+ * prunes orphaned worktrees, removes stale lock files, and marks intents reaped.
+ * Idempotent: Subsequent calls result in 0 additional reaps.
+ * @param {string} root - Project root directory
+ * @returns {{ reapedCount: number, reaped: Array<Object> }}
+ */
+export function reapOrphanedIntents(root) {
+  const stateDir = getStateDir(root);
+  const journalPath = join(stateDir, "journal.jsonl");
+
+  if (!existsSync(journalPath)) {
+    return { reapedCount: 0, reaped: [] };
+  }
+
+  let lines = [];
+  try {
+    const raw = readFileSync(journalPath, "utf-8");
+    lines = raw.split("\n").filter(Boolean);
+  } catch (_) {
+    return { reapedCount: 0, reaped: [] };
+  }
+
+  const intents = new Map();
+  const finishedOpIds = new Set();
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (!entry || !entry.opId) continue;
+      if (entry.event === "intent") {
+        intents.set(entry.opId, entry);
+      } else if (entry.event === "journal_done" || entry.event === "journal_reaped") {
+        finishedOpIds.add(entry.opId);
+      }
+    } catch (_) {
+      // Ignore corrupted or partial lines
+    }
+  }
+
+  const reaped = [];
+
+  for (const [opId, intent] of intents.entries()) {
+    if (finishedOpIds.has(opId)) {
+      continue;
+    }
+
+    const alive = isPidAlive(intent.pid, intent.processStartTime);
+    if (!alive) {
+      // Owner PID is dead or recycled -> reap orphaned intent
+      if (intent.targetPath) {
+        try {
+          worktreeRemove(root, intent.targetPath);
+        } catch (_) {}
+        try {
+          worktreePrune(root);
+        } catch (_) {}
+      }
+
+      // Clean up stale lock files associated with this PID or targetPath
+      try {
+        const lockDir = getLockDir(root);
+        if (existsSync(lockDir)) {
+          const lockFiles = readdirSync(lockDir);
+          for (const file of lockFiles) {
+            if (file.endsWith(".json")) {
+              const lockPath = join(lockDir, file);
+              try {
+                const lockContent = JSON.parse(readFileSync(lockPath, "utf-8"));
+                if (
+                  lockContent.pid === intent.pid ||
+                  (intent.targetPath && Array.isArray(lockContent.files) && lockContent.files.includes(intent.targetPath))
+                ) {
+                  unlinkSync(lockPath);
+                }
+              } catch (_) {}
+            }
+          }
+        }
+      } catch (_) {}
+
+      // Record journal_reaped to guarantee idempotency
+      const reapedRecord = {
+        opId,
+        event: "journal_reaped",
+        reapedAt: new Date().toISOString(),
+        pid: intent.pid,
+      };
+
+      try {
+        const fd = openSync(journalPath, "a");
+        try {
+          writeSync(fd, JSON.stringify(reapedRecord) + "\n", "utf-8");
+          fsyncSync(fd);
+        } finally {
+          closeSync(fd);
+        }
+      } catch (_) {}
+
+      reaped.push(intent);
+    }
+  }
+
+  return { reapedCount: reaped.length, reaped };
+}

package/src/mcp.mjs

@@ -3,10 +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";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.20.0",
+  version: "0.22.6",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling
@@ -352,6 +353,8 @@ export function writeMcpFrame(targetOutput, data) {
 }
 
 export function startMcpServer(input = process.stdin, output = process.stdout, opts = {}) {
+  const root = opts.root || resolveRoot();
+  reapOrphanedIntents(root);
   isolateMcpStdout(process.stdout, opts);
   if (output && output !== process.stdout) {
     isolateMcpStdout(output, opts);

package/src/state.mjs

@@ -292,18 +292,24 @@ export function getLockDir(rootOrOpts = resolveRoot()) {
   return dir;
 }
 
+export function parseProcStat(stat) {
+  if (typeof stat !== "string") return null;
+  const rpar = stat.lastIndexOf(")");
+  if (rpar === -1) return null;
+  const rest = stat.slice(rpar + 2).trim().split(/\s+/);
+  return rest[19] || null;
+}
+
 export function getProcessStartTime(pid) {
-  if (!pid || typeof pid !== "number") return null;
+  if (!pid) return null;
+  if (typeof pid === "string" && pid.includes(")")) {
+    return parseProcStat(pid);
+  }
+  if (typeof pid !== "number") return null;
   if (process.platform === "linux") {
     try {
       const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
-      const rpar = stat.lastIndexOf(")");
-      if (rpar !== -1) {
-        const rest = stat.slice(rpar + 1).trim().split(/\s+/);
-        return rest[19] || null;
-      }
-      const parts = stat.trim().split(/\s+/);
-      return parts[21] || null;
+      return parseProcStat(stat);
     } catch (_) {}
   }
   return null;