jules-orchestrator-kit 0.29.0 → 0.29.1

package/README.md

@@ -332,19 +332,21 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 
 | Command | Usage | Description | Exit Codes |
 | :--- | :--- | :--- | :--- |
+| `init` | `agentctl init [--interactive] [--tier pro]` | Interactive onboarding wizard & stack oracle inspector generating `.agent/config.yml`. | `0` (Created) |
+| `task create` | `agentctl task create [--title <t>] [--prompt <p>]` | Interactively authors & scopes falsifiable task envelopes with secret scrubbing & preflight gate checks. | `0` (Queued), `1` (Unfalsifiable / Secret leak) |
 | `dispatch` | `agentctl dispatch --title <t> --prompt <p>` | Dispatches a single task to an AI agent in an isolated worktree. | `0` (Success), `1` (Arg error), `2` (429 Rate limit), `3` (Scope deny), `4` (OODA exhausted), `5` (Diff > 75KB), `6` (Secret leak) |
+| `scan` | `agentctl scan` | Scans codebase for TODO/FIXME annotations to seed task authoring. | `0` (Scanned) |
 | `review-repair`| `agentctl review-repair <pr-comments.json>`| Parses GitHub PR review comments and synthesizes actionable OODA repair tasks. | `0` (Parsed), `1` (Missing file) |
 | `dashboard` | `agentctl dashboard [port]` | Starts zero-dependency local HTTP telemetry and audit visualizer dashboard. | `0` (Running) |
-| `gate` / `audit`| `agentctl gate --base main --json` | Runs security, secret scanning, and verification gate against current branch. | `0` (Approved), `3` (Scope violation), `5` (Diff limit), `6` (Secret leak) |
+| `gate` / `audit`| `agentctl gate --mode working-tree --json` | Runs security, secret scanning, and verification gate against working tree or branch. | `0` (Approved), `3` (Scope violation), `5` (Diff limit), `6` (Secret leak) |
 | `bootstrap` | `agentctl bootstrap [--force] [--json]` | Inspects an untested repository and synthesizes `.agent/config.yml` with a zero-test verification oracle (`php -l`, `compileall`, `dotnet build`, `tsc`, `smoke`). | `0` (Bootstrapped / Existing) |
 | `queue` | `agentctl queue` | Consumes and executes pending markdown task envelopes in `.agent/queue/`. | `0` (Complete) |
 | `swarm` | `agentctl swarm` | Runs parallel multi-agent swarm across queued tasks with token-bucket concurrency. | `0` (Complete) |
 | `doctor` | `agentctl doctor` | Diagnostic inspect: displays detected stack, container wrapper, test command, and daily session budget. | `0` (Healthy) |
 | `lock` | `agentctl lock <acquire\|release\|status>`| Manages VFS mutex locks for multi-agent non-overlapping file ownership. | `0` (Locked/Released), `1` (Conflict) |
 | `clean` | `agentctl clean` | Prunes stale git worktrees, lockfiles, and temporary ledgers. | `0` (Clean) |
-| `init` | `agentctl init` | Scaffolds `.agent/` directory structure and default `.agent/config.yml`. | `0` (Created) |
 | `mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server for tool integration. | `0` / Stdio stream |
-| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.27.0`). | `0` |
+| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.29.0`). | `0` |
 
 <br/>
 
@@ -353,14 +355,15 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 <br/>
 
 <a id="roadmap"></a>
-## 🗺️ v0.27+ Next-Gen Feature Roadmap
+## 🗺️ v0.29+ Feature Roadmap
 
 | Feature | Module / Command | Architectural Blueprint | Target Release |
 | :--- | :--- | :--- | :---: |
+| **Onboarding & Stack Oracle Wizard** | `agentctl init --interactive` (`src/wizard-init.mjs`) | Zero-dependency interactive CLI wizard auto-detecting verification oracles, quota tiers, and preset workflows. | **v0.29.0** *(Shipped)* |
+| **Guided Task Authoring Subsystem** | `agentctl task create` (`src/wizard-task.mjs`) | Guided task authoring with TODO candidate harvesting, Shannon entropy secret scrubbing, and guardrail footer synthesis. | **v0.29.0** *(Shipped)* |
 | **PR Review Auto-Remediation Loop** | `agentctl review-repair` (`src/review-repair.mjs`) | Ingests GitHub PR review comments (`CHANGES_REQUESTED`), extracts line/file context, and dispatches automated OODA repair turns until reviewer comments are resolved. | **v0.27.0** *(Shipped)* |
 | **Multi-Provider Failover Router** | `createFailoverProvider` (`src/provider.mjs`) | Ordered router (`["jules", "claude-code", "local-mcp"]`) that seamlessly falls back to secondary LLMs on HTTP 429 rate limits or 5xx service unavailability. | **v0.27.0** *(Shipped)* |
 | **Telemetry & Audit Web Dashboard**| `agentctl dashboard` (`src/dashboard.mjs`) | Zero-dependency local HTTP server displaying real-time DAG execution graphs, Wilson-Score flaky test ledgers, and SHA-256 telemetry chains. | **v0.27.0** *(Shipped)* |
-| **Cross-Language Contract Guard** | `hashCrossLanguageInterface` (`src/merge-blocks.mjs`)| Canonical SHA-256 schema hashing for OpenAPI/Protobuf specs across polyglot task dependencies in `DagExecutor`. | **v0.26.0** *(Shipped)* |
 
 <br/>
 
@@ -371,11 +374,10 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 ## 📖 Recipes, Documentation & Prior Art
 
 - [**Google Jules Official Documentation**](https://jules.google) — Official platform overview and API specifications for Google Jules.
-- [**Google Labs Code Repositories**](https://github.com/google-labs-code) — Official Google Labs public GitHub organization (jules-action, jules-sdk).
+- [**Onboarding & Task Wizard Specification**](./docs/ONBOARDING_AND_TASK_WIZARD_SPEC.md) — Normative architecture specification for zero-dependency TUI, stack oracle, and guided task authoring.
 - [**Universal Polyglot Architecture & Zero-Test Specification**](./docs/UNIVERSAL_POLYGLOT_ARCHITECTURE.md) — Comprehensive technical report on boundary resolution, OODA math, and B2B workflows.
 - [**v0.27.0 Architectural Audit & Platform Evolution**](./docs/V0.27_ARCHITECTURAL_AUDIT_AND_EVOLUTION.md) — PR review remediation, failover router, and local dashboard specs.
 - [**Examples & Task Envelope Recipes**](./EXAMPLES.md) — Production YAML and Markdown task envelopes.
-- [**Adversarial Security Audit Phase 4 Report**](./docs/AUDIT_REPORT.md) — CWE-77, CWE-1321, and CWE-183 security hardening analysis.
 - [**Changelog**](./CHANGELOG.md) — Full release history and migration guides.
 
 <br/>

package/bin/agentctl.mjs

@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.29.0 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.29.1 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -54,7 +54,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.29.0");
+    console.log("agentctl v0.29.1");
     process.exit(0);
   }
 
@@ -265,7 +265,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.29.0)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.29.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);
@@ -401,7 +401,7 @@ async function main() {
     case "status": {
       const queueDir = getQueueDir(root);
       const files = existsSync(queueDir) ? readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir)) : [];
-      console.log(`\n📊 agentctl Status Summary (v0.29.0)`);
+      console.log(`\n📊 agentctl Status Summary (v0.29.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Pending Tasks    : ${files.length}`);

package/index.mjs

@@ -1,5 +1,5 @@
 /**
- * Google Jules Orchestrator Kit - Node.js SDK (v0.29.0)
+ * Google Jules Orchestrator Kit - Node.js SDK (v0.29.1)
  *
  * Exposes core orchestrator functions for programmatically driving agent tasks,
  * security auditing, repo gating, and state operations.

package/package.json

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

package/src/dashboard.mjs

@@ -32,7 +32,7 @@ export function getDashboardHtml(root = process.cwd()) {
   </style>
 </head>
 <body>
-  <h1>🚀 jules-orchestrator-kit Dashboard (v0.29.0)</h1>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v0.29.1)</h1>
   <div class="subtitle">Repository: <code>${root}</code></div>
 
   <div class="grid">
@@ -87,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.29.0", root, ts: new Date().toISOString() }));
+      return res.end(JSON.stringify({ ok: true, version: "0.29.1", root, ts: new Date().toISOString() }));
     }
 
     if (url.pathname === "/api/telemetry") {

package/src/engine.mjs

@@ -46,14 +46,8 @@ export function isTaskFile(fileName, queueDirOrContent = null) {
       }
       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;
-            }
-          }
+        if (trimmed.includes("JULES_TASK_ENVELOPE") || trimmed.includes("# Task ID:") || trimmed.startsWith("---")) {
+          return true;
         }
       }
     } catch (_) {}

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.29.0",
+  version: "0.29.1",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling

package/src/security.mjs

@@ -13,7 +13,7 @@ export const HIGH_CONFIDENCE_PATTERNS = [
 
   /\bAKIA[0-9A-Z]{16}\b/g,
   /\bASIA[0-9A-Z]{16}\b/g,
-  /\baws_secret_access_key\s*=\s*['"]?[A-Za-z0-9\/+=]{40}['"]?/g,
+  /\baws_secret_access_key\s*=\s*['"]?[A-Za-z0-9\/+=]{40}['"]?/gi,
 
   /-----BEGIN (?:RSA|DSA|EC|OPENSSH|PRIVATE)(?:\s+PRIVATE)? KEY-----[\s\S]*?-----END (?:RSA|DSA|EC|OPENSSH|PRIVATE)(?:\s+PRIVATE)? KEY-----/g,
   /PuTTY-User-Key-File-[0-9]:[^\n]+/g,

package/src/tui.mjs

@@ -41,6 +41,13 @@ export function styleText(text, style) {
   return `${style}${text}${ANSI.reset}`;
 }
 
+export class WizardCancelledError extends Error {
+  constructor(message = "Wizard cancelled by user") {
+    super(message);
+    this.name = "WizardCancelledError";
+  }
+}
+
 /**
  * Read keypress in raw mode from TTY input stream.
  * @param {import("node:stream").Readable} stream
@@ -60,7 +67,7 @@ async function* readKeypresses(stream = process.stdin) {
       if (str === "\u0003") {
         // Ctrl+C SIGINT
         process.stdout.write(ANSI.showCursor + "\n");
-        process.exit(130);
+        throw new WizardCancelledError("Wizard operation cancelled by user (SIGINT).");
       }
       yield str;
     }

package/src/wizard-init.mjs

@@ -1,9 +1,26 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { parseYaml } from "./config.mjs";
 import { detectStackOracles, runVerificationProbe } from "./wizard-oracle.mjs";
 import { select, multiSelect, input, confirm, spinner, isTTY } from "./tui.mjs";
 
+/**
+ * Write a file atomically using a temporary file and atomic rename.
+ * @param {string} filePath
+ * @param {string} content
+ */
+function writeAtomic(filePath, content) {
+  const tmpPath = `${filePath}.tmp.${Date.now()}.${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);
+}
+
 export const TIER_PROFILES = {
   free: {
     concurrency: 1,
@@ -71,21 +88,30 @@ export function planInit(root = process.cwd(), options = {}) {
   const tierName = options.tier || "pro";
   const limits = TIER_PROFILES[tierName] || TIER_PROFILES.pro;
 
+  // Preserve existing config if present
+  let existingConfig = {};
+  const existingConfigPath = join(root, ".agent", "config.yml");
+  if (existsSync(existingConfigPath)) {
+    try {
+      existingConfig = parseYaml(readFileSync(existingConfigPath, "utf-8")) || {};
+    } catch (_) {}
+  }
+
   const verify = {
-    test: options.testCmd || oracle.candidates.testCmd || "",
-    build: options.buildCmd || oracle.candidates.buildCmd || "",
-    lint: options.lintCmd || oracle.candidates.lintCmd || "",
-    typecheck: options.typecheckCmd || oracle.candidates.typecheckCmd || "",
+    test: options.testCmd || existingConfig.verify?.test || oracle.candidates.testCmd || "",
+    build: options.buildCmd || existingConfig.verify?.build || oracle.candidates.buildCmd || "",
+    lint: options.lintCmd || existingConfig.verify?.lint || oracle.candidates.lintCmd || "",
+    typecheck: options.typecheckCmd || existingConfig.verify?.typecheck || oracle.candidates.typecheckCmd || "",
   };
 
-  const selectedPresets = options.presets || ["nightly-security-audit", "flaky-test-quarantine"];
+  const selectedPresets = options.presets || existingConfig.presets || ["nightly-security-audit", "flaky-test-quarantine"];
 
   const configYaml = `# Google Jules Orchestrator Kit Config (v0.29.0)
 version: 1
-provider: jules
+provider: ${existingConfig.provider || "jules"}
 tier: ${tierName}
-base_branch: ${options.baseBranch || "main"}
-branch_prefix: agent/
+base_branch: ${options.baseBranch || existingConfig.base_branch || "main"}
+branch_prefix: ${existingConfig.branch_prefix || "agent/"}
 
 limits:
   concurrency: ${limits.concurrency}
@@ -161,6 +187,10 @@ export function loadPresets(root = process.cwd()) {
 export async function runInitWizard(root = process.cwd(), options = {}) {
   const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
 
+  if (!interactive && !options.allowDefaults && !options.tier) {
+    throw new Error("Non-interactive init requires explicit options or allowDefaults: true");
+  }
+
   let selectedTier = options.tier || "pro";
   let testCmd = options.testCmd;
   let buildCmd = options.buildCmd;
@@ -232,8 +262,8 @@ export async function runInitWizard(root = process.cwd(), options = {}) {
   const configPath = join(agentDir, "config.yml");
   const julesPath = join(agentDir, "jules.yml");
 
-  writeFileSync(configPath, plan.configYaml, "utf-8");
-  writeFileSync(julesPath, plan.julesYaml, "utf-8");
+  writeAtomic(configPath, plan.configYaml);
+  writeAtomic(julesPath, plan.julesYaml);
 
   return {
     ok: true,

package/src/wizard-task.mjs

@@ -1,8 +1,9 @@
 import { writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { resolve } from "node:path";
 import { loadConfig } from "./config.mjs";
 import { gate } from "./engine.mjs";
 import { scanDiff, shannonEntropy } from "./security.mjs";
+import { getQueueDir } from "./state.mjs";
 import { scanCodebaseForTodos } from "../scripts/jules-scan-todos.mjs";
 import { select, input, confirm, spinner, isTTY } from "./tui.mjs";
 
@@ -16,6 +17,8 @@ HARD CONSTRAINTS:
 - BEFORE opening the PR: Run \`git fetch origin main && git rebase origin/main\`, then re-verify.
 `;
 
+const TRIVIAL_ORACLES = new Set(["true", "echo", ":", "false", "exit 0", "exit 1", "echo ok"]);
+
 /**
  * Pure planning core for task creation & envelope synthesis.
  * @param {string} root
@@ -29,7 +32,6 @@ HARD CONSTRAINTS:
  *   verifyCmd: string,
  *   flags: { autoPr: boolean, requirePlanApproval: boolean, repoless: boolean, startingBranch: string },
  *   secretFindings: Array<any>,
- *   gateResult: object,
  *   taskFileContent: string
  * }}
  */
@@ -38,28 +40,37 @@ export function planTaskCreate(root = process.cwd(), inputObj = {}) {
 
   const title = inputObj.title || "Agent Task";
   const rawPrompt = inputObj.prompt || "";
-  const verifyCmd = inputObj.verifyCmd || config.verify.test || config.verify.build || "";
+  const verifyCmd = (inputObj.verifyCmd || config.verify.test || config.verify.build || "").trim();
 
   // 1. Falsifiability check
   if (!rawPrompt.trim()) {
     throw new Error("Task prompt cannot be empty.");
   }
-  if (!verifyCmd && !inputObj.allowUnverifiable) {
+  const cleanCmd = verifyCmd.toLowerCase().replace(/['"]/g, "").trim();
+  if ((!verifyCmd || TRIVIAL_ORACLES.has(cleanCmd)) && !inputObj.allowUnverifiable) {
     throw new Error(
-      "Unfalsifiable Task Rejected: Task must include a concrete verification test/build command. Configure verify.test in .agent/config.yml or pass --verify-cmd."
+      "Unfalsifiable Task Rejected: Task must include a non-trivial verification test/build command. Configure verify.test in .agent/config.yml or pass --verify-cmd."
     );
   }
 
-  // 2. Secret Scrubbing Preflight
+  // 2. Secret Scrubbing Preflight (multiline diff formatting)
   const secretFindings = [];
-  const secretScan = scanDiff(`+${rawPrompt}`);
+  const multilineDiff = rawPrompt.split("\n").map((line) => `+${line}`).join("\n");
+  const secretScan = scanDiff(multilineDiff);
   if (!secretScan.ok) {
-    secretScan.findings.forEach((f) => secretFindings.push(f));
+    secretScan.findings.forEach((f) => secretFindings.push({ id: f.type || f.id || "SECRET_LEAK", ...f }));
   }
   if (shannonEntropy(rawPrompt) > 4.5 && !inputObj.allowHighEntropy) {
     secretFindings.push({ id: "HIGH_ENTROPY_PROMPT", line: 1 });
   }
 
+  // High-confidence secrets cannot be bypassed
+  const highConfidenceFindings = secretFindings.filter((f) => f.id !== "HIGH_ENTROPY_PROMPT");
+  if (highConfidenceFindings.length > 0) {
+    throw new Error(
+      `Pre-Dispatch Secret Leak Blocked: Prompt contains ${highConfidenceFindings.length} high-confidence secret finding(s). High-confidence credentials cannot be bypassed.`
+    );
+  }
   if (secretFindings.length > 0 && !inputObj.allowSecrets) {
     throw new Error(
       `Pre-Dispatch Secret Leak Blocked: Prompt contains potential secrets or credentials (${secretFindings.length} finding(s)). Scrub keys before dispatching.`
@@ -74,7 +85,11 @@ export function planTaskCreate(root = process.cwd(), inputObj = {}) {
     startingBranch: inputObj.startingBranch || config.baseBranch || "main",
   };
 
-  // 4. Prompt Envelope & Guardrail Footer Synthesis
+  // 4. Task ID Sanitization (Path Traversal Guard)
+  const rawId = inputObj.id || `TASK-${Date.now().toString(36).toUpperCase()}`;
+  const taskId = String(rawId).replace(/[^a-zA-Z0-9_-]/g, "_");
+
+  // 5. Prompt Envelope & Guardrail Footer Synthesis
   const fullPrompt = `[TASK INSTRUCTIONS]
 ${rawPrompt}
 
@@ -83,9 +98,16 @@ Test/Verification Command: ${verifyCmd || "(None)"}
 
 ${GUARDRAIL_FOOTER}`;
 
-  const taskId = inputObj.id || `TASK-${Date.now().toString(36).toUpperCase()}`;
+  const envelopeMetadata = {
+    version: 1,
+    id: taskId,
+    title,
+    flags,
+    verifyCmd,
+  };
 
-  const taskFileContent = `# ${title}
+  const taskFileContent = `<!-- JULES_TASK_ENVELOPE: ${JSON.stringify(envelopeMetadata)} -->
+# ${title}
 # Task ID: ${taskId}
 # Auto-PR: ${flags.autoPr} | Plan Approval: ${flags.requirePlanApproval} | Repoless: ${flags.repoless}
 
@@ -173,16 +195,24 @@ export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
   // Perform Gate Preflight
   const gateRes = await gate({ root, mode: "working-tree" });
   if (!gateRes.ok && (gateRes.code === 3 || gateRes.code === 6) && !options.allowGateFailure) {
-    throw new Error(`Gate Preflight Rejected Task: Repository contains scope or secret violations (Exit ${gateRes.code}).`);
+    // Filter out uncommitted .agent/ config scope warnings if user initialized locally
+    const realViolations = gateRes.phases[0]?.violations?.filter((v) => !v.file.startsWith(".agent/")) || [];
+    if (realViolations.length > 0 || gateRes.code === 6) {
+      throw new Error(`Gate Preflight Rejected Task: Repository contains scope or secret violations (Exit ${gateRes.code}).`);
+    }
   }
 
-  // Write Task File to .agent/queue/
-  const queueDir = join(root, ".agent", "queue");
+  // Write Task File to canonical queue directory (getQueueDir)
+  const queueDir = getQueueDir(root);
   if (!existsSync(queueDir)) {
     mkdirSync(queueDir, { recursive: true });
   }
 
-  const taskFile = join(queueDir, `${plan.taskId}.md`);
+  const taskFile = resolve(queueDir, `${plan.taskId}.md`);
+  if (!taskFile.startsWith(resolve(queueDir))) {
+    throw new Error("Task ID path traversal blocked.");
+  }
+
   writeFileSync(taskFile, plan.taskFileContent, "utf-8");
 
   return {